(Page 1 of 1 in this chapter) Version

Chapter 3

Using the ISUP Service API

3.1 Introduction
3.2 Initializing the ISUP Service Under CT Access
3.2.1 Initializing the CT Access Environment
3.2.2 Creating Queues and Contexts
3.2.3 Use of ctaOpenServices
3.3 Checkpointing Circuit States
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 CT Access, and handling errors.

3.2 Initializing the ISUP Service Under CT Access

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

The CT Access API is documented in two Natural MicroSystems documents, available on the NMS web site (www.nmss.com):

Answers to general questions about the CT Access architecture, queues, contexts, etc. may be found in the aforementioned documents.

3.2.1 Initializing the CT Access Environment

The CT 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      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 CT Access.", Ret);
    exit( 1 );
}

3.2.2 Creating Queues and Contexts

The application creates the required CTA queues and contexts, as described in Chapter 2. 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 SAP by calling ctaOpenServices once for each binding. The binding operation specifies the parameters shown below:

board TX board number

srcEnt Calling application entity ID

srcInst Calling application instance ID

suId Calling applications service user ID

spId ISUP sap ID on which to bind

ssn ISUP subsystem number associated with the SAP

Under CT 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 Checkpointing Circuit States

The ISUPStatusReq API function now supports two new event types for circuit state checkpointing. These event types are:

CIRGRPSET        circuit group set status
CIRGRPGET        circuit group get status
Both status request types use the Range and Status IE, described in Appendix B. For the purposes of the two new status request types, the Range and Status IE fields are used as follows:
Field

 Description

range

 The number of circuits to modify (minus one). For example, to modify 24 circuits, the range value would be 23.

status

 An array of length range + 1. Each byte of the array contains the circuit status for one circuit.

Bits 0 and 1 indicate the maintenance blocking state as follows:

0x00 = Not Blocked
0x01 = Locally Blocked
0x02 = Remotely Blocked
0x03 = Remotely and Locally Blocked
Bits 2 and three indicate the call processing state as follows:

0x00 = Transient (will not alter call processing state for group set)
0x01 = Incoming Busy
0x02 = Outgoing Busy
0x11 = Idle
Bits 4 and 5 indicate the hardware blocking state as follows:

0x00 = Not Blocked
0x01 = Locally Blocked
0x02 = Remotely Blocked
0x03 = Remotely and Locally Blocked
As an example, if a circuit were Locally Maintenance Blocked and Idle, its status byte would be encoded as 0x0D.

3.4 Tracing API Calls and Events

CT 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 CT 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 CT Access.", Ret);
    exit( 1 );
}
CTA tracing is explained in detail in the CT Access Developer's Reference Manual.


(Page 1 of 1 in this chapter) Version

tech_support@nmss.com
Copyright © 2000, Natural MicroSystems, Inc. All rights reserved.