3.1 Introduction

3.2 Initializing the ISUP 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 ISUP Congestion Control

3.4 Tracing API Calls and Events

3.1 Introduction

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

3.2 Initializing the ISUP Service Under Natural Access

Before calling any ISUP primitives, the application must first initialize the Natural Access run-time environment, create the desired queues and contexts, and open the ISUP service. These steps are described in the following subsections.

For more information about the Natural Access architecture, queues, contexts, and programming models, refer to the Natural Access Developer's Reference Manual. This manual is available on the NMS web site (www.nmscommunications.com).

3.2.1 Initializing the Natural Access Environment

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

CTA_INIT_PARMS      isupInitparms       = {0};
CTA_SERVICE_NAME    isupServiceNames[]  = {{"ISUP", "ISUPMGR"}};

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

Ret = ctaInitialize(isupServiceNames, 1, &isupInitparms);
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 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, "IsupSAP-%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 ISUP user service access point by calling ctaOpenServices once for each binding. The binding operation specifies the following parameters:

board TX board number

srcEnt Calling application entity ID

srcInst Calling application instance ID

suId Calling applications service user ID

spId ISUP service access point ID on which to bind

ssn ISUP subsystem number associated with the service access point

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 isupOpenSvcLst[] = {{{"ISUP", "ISUPMGR"}, {0}, {0}, {0}}};

isupOpenSvcLst[0].svcargs.args[0] = board;   /* board number           */
isupOpenSvcLst[0].svcargs.args[1] = INST_ID; /* srcInst                */
isupOpenSvcLst[0].svcargs.args[2] = ENT_ID;  /* srcEnt                 */
isupOpenSvcLst[0].svcargs.args[3] = 1;       /* AutoBind? (yes=1,no= 0)*/
isupOpenSvcLst[0].svcargs.args[4] = SAP_ID;  /* spId                   */
isupOpenSvcLst[0].svcargs.args[5] = SAP_ID;  /* suId                   */

The ctaOpenServices function 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 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 a unique entity IDs.

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



Ret = ctaOpenServices( ctaHd, isupOpenSvcLst, 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 ISUP service [%s]\n", sErr );
    ctaDestroyQueue( pSap->ctaQueue );    /* destroys context too */
    return(  );
}

3.3 ISUP Congestion Control

There is a second event that can be received from the ISUP API: ISUPEVN_CONG. This event indicates that one of two congestion issues may be arising from the system:

• Memory usage on the TX board has become very high.

• The queue in the ISUP API is growing.

In either case, you will get a congestion level of zero through three in the value element of the CTA_EVENT structure.

If your application receives a level one event, it should reduce the number of calls being generated. At levels two and three, avoid all new calls and clear existing calls. As memory usage lowers or the outbound queue shrinks, congestion events with lower congestion levels will be generated in order for the application to resume more normal traffic.

If your application is interested in finding out additional information about the congestion, a call to ISUPGetApiStats will return additional statistics.

3.4 Tracing API Calls and Events

Natural Access provides a mechanism for tracing API calls and events issued/received by an application. To capture trace messages, the ctdeamon application must be running, and the ISUP service must be included in the [ctasys] section of the cta.cfg file, as illustrated below:

[ctasys]
Service = isup, isupmgr

In addition, the application must enable tracing in its initialization parameters when Natural Access is initialized.

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

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

Natural Access tracing is explained in detail in the Natural Access Developer's Reference Manual.