3.1 Introduction

3.2 Initializing the MTP 3 Service Under Natural Access

3.2.1 Initializing the Natural Access Environment

3.2.2 Creating Queues and Contexts

3.2.3 Use of ctaOpenServices

3.3 Handling Redundancy Events

3.1 Introduction

This chapter describes use of the MTP 3 API within an application: compiling and linking, utilizing Natural Access, and handling errors.

3.2 Initializing the MTP 3 Service Under Natural Access

Before calling any MTP 3 API primitives, the application must first initialize the Natural Access run-time environment, create the desired queues and contexts, and open the MTP 3 service to bind itself to the desired MTP 3 SAPs. These steps are described in the following subsections.

For more information about the Natural Access architecture, as well as Natural Access contexts, queues, and programming models, refer to the Natural Access Developer's Reference Manual (available on the NMS web site at www.nmscommunicationss.com).

3.2.1 Initializing the Natural Access Environment

The Natural Access environment is initialized by calling the ctaInitialize primitive as shown below. This is done once per application, regardless of the number of queues and contexts to be created.

CTA_INIT_PARMS      mtp3Initparms       = {0};
CTA_SERVICE_NAME    mtp3ServiceNames[]  = {{"MTP3", "MTP3MGR"}};

mtp3Initparms.size              = sizeof(CTA_INIT_PARMS);
mtp3Initparms.traceflags        = CTA_TRACE_ENABLE;
mtp3Initparms.parmflags         = CTA_PARM_MGMT_SHARED;
mtp3Initparms.ctacompatlevel    = CTA_COMPATLEVEL;

Ret = ctaInitialize(mtp3ServiceNames, 1, &mtp3Initparms);
if (Ret != SUCCESS) {
    printf("ERROR code 0x%08x initializing Natural Access.", Ret);
    exit( 1 );
}

3.2.2 Creating Queues and Contexts

The application creates the required Natural Access queues and contexts, as described in Section 2.4. The queue must always be created before any context that will be associated with it.

CTAHD       ctaHd;                  /* CTA context handle */
CTAQUEUEHD  ctaQueue;               /* Queue */


Ret = ctaCreateQueue( NULL, 0, &ctaQueue );
if ( Ret != SUCCESS )
{
     ctaGetText( NULL_CTAHD, Ret, sErr, sizeof( sErr ) );
     printf( "*ERROR : ctaCreateQueue failed( %s )\n", sErr );
     
}

sprintf( contextName, "Mtp3SAP-%d", spId ); /* context name is optional */

Ret = ctaCreateContext( ctaQueue, spId, contextName, &ctaHd );
if ( Ret != SUCCESS )
{
     ctaGetText( NULL_CTAHD, Ret, sErr, sizeof( sErr ) );
     printf( "ERROR : ctaCreateContext failed( %s )\n", sErr );
     ctaDestroyQueue( pSap->ctaQueue );
     
}

3.2.3 Use of ctaOpenServices

Once the queues and contexts are created, the application must bind itself to each desired MTP 3 user SAP by calling ctaOpenServices once for each binding. The binding operation specifies the following parameters:

Parameter	Description
board	TX board number.
srvInfo	Service information octet.
sapId	MTP 3 NSAP ID (defined in configuration) on which to bind. This should be passed in all functions that make requests to the board.
srcEnt	Calling application entity ID.
srcInst	Calling application instance ID.
suId	Calling application service user ID. This will be passed up in future indications from the board.
poolsize	Number of messages allowed to be queued to the TX board. Default value is 256.

Under Natural Access, these parameters are specified in the CTA_SERVICE_ARGS structure, contained in the CTA_SERVICE_DESC structure. An example of the parameter specification is provided:

CTA_SERVICE_DESC mtp3OpenSvcLst[] = {{{"MTP3","MTP3MGR"}, {0}, {0}, {0}}};

mtp3OpenSvcLst[0].svcargs.args[0] = Board;     /* board number          */
mtp3OpenSvcLst[0].svcargs.args[1] = Sio;       /* Service Information
                                                * Octet                 */
mtp3OpenSvcLst[0].svcargs.args[2] = NSapNmb;   /* network SAP number    */
mtp3OpenSvcLst[0].svcargs.args[3] = MyEnt;     /* application entity ID */
mtp3OpenSvcLst[0].svcargs.args[4] = DFLT_INST; /* Inst ID               */
mtp3OpenSvcLst[0].svcargs.args[5] = SuId;      /* Service user ID       */
mtp3OpenSvcLst[0].svcargs.args[6] = poolsize;  /* Pool size             */

ctaOpenServices is an asynchronous function - that is, the return from the function indicates that the bind operation has been initiated. Once completed, a CTAEVN_OPEN_SERVICES_DONE event is returned to the user application.

Note: If multiple contexts are assigned to the same queue, then all of those contexts must use the same entity ID in the service arguments parameter shown above. Conversely, contexts bound to different queues must specify unique entity IDs.

CTA_EVENT   event;    /* Event structure to wait for MTP3 events */



Ret = ctaOpenServices( ctaHd, mtp3OpenSvcLst, 1 );
if ( Ret != SUCCESS )
{
    ctaGetText( NULL_CTAHD, Ret, sErr, sizeof( sErr ) );
    printf( "ERROR : ctaOpenServices failed( %s )\n", sErr );
    ctaDestroyQueue( ctaQueue );  /* destroys context too */
    return()
}

/* Wait for "open services" to complete; note: this loop 
 * assumes no other contexts are already active on the queue
 * we're waiting on, so no other events will be received that
 * need handling
 */
event.id = CTAEVN_NULL_EVENT;
do
{
    ctaWaitEvent( ctaQueue, &event, 5000 );
}
while( (event.id != CTAEVN_OPEN_SERVICES_DONE) &&
       (event.id != CTAEVN_WAIT_TIMEOUT) );

/* check if binding succeeded */
if( (pSap->event.id != CTAEVN_OPEN_SERVICES_DONE) ||
    (pSap->event.value != CTA_REASON_FINISHED) )
{
    ctaGetText( event.ctahd, event.value, sErr, sizeof( sErr ) );
    printf( "ERROR opening MTP3 service [%s]\n", sErr );
    ctaDestroyQueue( pSap->ctaQueue );    /* destroys context too */
    return(  );
}

Note: The previous example is only correct if the application uses a separate queue for each context/service instance. If the application opens multiple service instances against the same queue, either multiple SAPs on the same board or on multiple boards (in a redundant configuration), it must process events (call MTP3RetrieveMessage) for other contexts while waiting for the CTAEVN_OPEN_SERVICES_DONE event. Failure to do so can result in an infinite loop.

3.3 Handling Redundancy Events

After binding to a MTP 3 user SAP, the application will receive a MTP3RUNSTATEIND event indicating the redundancy state of the MTP 3 layer on the board. This event type associated with this event will indicate one of the following states.

Event Type	Description
SN_HAST_STANDALONE	Application is in a non-redundant configuration; normal operation may begin
SN_HAST_PRIMARY	MTP 3 task on this board is currently the primary board in a redundant board pair; normal operation is allowed as long as the board remains the primary
SN_HAST_BACKUP	MTP 3 task on this board is currently the backup board in a redundant board pair, monitoring the status of the primary; no active traffic will pass through this SAP until the board becomes the primary member of the pair

The MTP3RUNSTATEIND event will be the first message posted to the application's queue for each SAP after the binding is confirmed. No data traffic (unitdata or connections requests) should be directed to this SAP until this event is received.

See the SS7 Health Management Developer's Reference Manual for more details on writing redundant MTP 3 applications.