Setting up the Natural Access environment

Before calling any ISUP service functions, the application must:

Refer to the Natural Access Developer's Reference Manual for information about Natural Access.

Initializing the Natural Access environment

The Natural Access environment is initialized by calling ctaInitialize. Initialize Natural Access only once per application, regardless of the number of queues and contexts 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 );
}

Creating queues and contexts

The application creates the required Natural Access queues and contexts. The queue must always be created before any associated context is created.

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 );
     ...
}

Binding to the ISUP service

Once the queues and contexts are created, the application must bind to each desired ISUP user service access point by calling ctaOpenServices once for each binding. The binding operation specifies the following parameters:

Field

Description

board

TX board number.

srcInst

Calling application instance ID.

srcEnt

Calling application entity ID.

AutoBind

Determines if the application should bind immediately to the ISUP task.

1 = yes

0 = no

spId

ISUP service access point ID on which to bind.

suId

Calling application service user ID.

API queue size

Maximum number of requests that can be queued to the board in the ISUP service. Valid range is 128 to 1024. Default = 128.


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

isupOpenSvcLst[0].svcargs.args[0] = boardNum; /* board number           */
isupOpenSvcLst[0].svcargs.args[1] = INST_ID;  /* srcInst                */
isupOpenSvcLst[0].svcargs.args[2] = ENT_ID;   /* dprChan                */
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                   */
isupOpenSvcLst[0].svcargs.args[6] = 1024;     /* API queue size         */

<NMSBREAK>

ctaOpenServices is an asynchronous function. The return from the function indicates that the bind operation initiated. Once completed, a CTAEVN_OPEN_SERVICES_DONE event is returned to the application:

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( ... );
}