3.1 Introduction

3.2 Initializing the TCAP 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.2.4 Receiving TCAP Service Events

3.3 Handling Redundancy Events

3.4 SCCP Addressing and Routing

3.4.1 Message Routing

Routing by PC and SSN

Routing by Global Title

3.4.2 About Global Titles

3.5 Dialog IDs

3.6 Tracing API Calls and Events

3.1 Introduction

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

3.2 Initializing the TCAP Service Under Natural Access

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

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

• Natural Access Developer's Reference Manual

• Natural Access Function Reference Manual

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

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      tcapInitparms       = {0};
CTA_SERVICE_NAME    tcapServiceNames[]  = {{"TCAP", "TCAPMGR"}};

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

Ret = ctaInitialize(tcapServiceNames, 1, &tcapInitparms);
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 queues and contexts, as described in Section 2.5. 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, "TcapSAP-%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 TCAP 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 TCAP service access point ID

ssn TCAP subsystem number associated with the service access point

API queue size Maximum number of requests that may be queued to the board within the API. Valid range is 128 to 1024 and defaults to 128.

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 TCAPOpenSvcLst[] = {{{"TCAP", "TCAPMGR"}, {0}, {0}, {0}}};

tcapOpenSvcLst[0].svcargs.args[0] = boardNum;        /* board number   */
tcapOpenSvcLst[0].svcargs.args[1] = DPRCHAN + sapid; /* srcEnt         */
tcapOpenSvcLst[0].svcargs.args[2] = ZERO;            /* srcInst        */
tcapOpenSvcLst[0].svcargs.args[3] = SUID;            /* suId           */
tcapOpenSvcLst[0].svcargs.args[4] = sapid;           /* spId           */
tcapOpenSvcLst[0].svcargs.args[5] = ssn;             /* ssn            */
tcapOpenSvcLst[0].svcargs.args[6] = 256;
                                            /* increase API queue size */

The ctaOpenServices function is asynchronous - 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: Only a single thread should call ctaOpenServices to open the TCAP service for a single board. All messages generated by the TCAP task on a single board will be reported to the last thread to call ctaOpenServices for the TCAP service.

3.2.4 Receiving TCAP Service Events

After binding to a TCAP user SAP with ctaOpenServices, the application then receives TCAP service events by periodically calling ctaWaitEvent, specifying the Natural Access queue handle created earlier, as shown in the following example. The TCAP service may generate two classes of events: data events and congestion events.

ret = ctaWaitEvent( ctaQueue, &event, CTA_WAIT_FOREVER );
if ( ret != SUCCESS )
   /* handle the error */
else
{
   switch ( event.id )
   {
      case TCAPEVN_DATA:
         /* an TCAP date event has occured, call TCAPRetrieveMessage() 
            to retrieve the message and proccess it */
         tcret = TCAPRetrieveMessage( ctaHd, &msg, &infoBlk );
         if( ret == TCAP_SUCCESS )
             /* process received TCAP event */
         else if( ret == TCAP_NOMSG 
             /* this is normal - just ignore and wait for next event */
         else
             /* TCAPRetrieveMessage failed - handle the error */
       
         break;

      case TCAPEVN_CONGEST:
         /* TCAP layer or API is congested or congestion abated;
            take appropriate action */
         cong_lvl = (U8) event.value;
         if( cong_lvl == 0 )
             /* congestion abated - restore traffic to normal levels */
         else
             /* congestion now at level "cong_lvl" - take appropriate
                action to reduce traffic. */

         break;

      .
      .
      .
   }
}

When an event of type TCAPEVN_DATA is received, the application calls TCAPRetrieveMessage to retrieve the TCAP message for processing. The message could be a TCAP transaction message, or other type of indication, such as a status or notify event. It is possible for TCAPRetrieveMessage to return a value of TCAP_NOMSG, indicating that the event was processed internally by the TCAP service, and there is nothing for the application to process. This usually occurs before a congestion event is generated, but may also happen at other times.

If an event of type TCAPEVN_CONGEST is received, the outbound congestion level of the TCAP user SAP has changed. The new congestion level is contained in the value field of the event structure returned by ctaWaitEvent. Upon receipt of this event, the application should take action to reduce (in the case of congestion onset) or restore (in the case of congestion abatement) the traffic load it is generating.

3.3 Handling Redundancy Events

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

Event Type	Description
TCAP_STANDALONE	Application is in a non-redundant configuration; normal operation may begin
TCAP_PRIMARY	TCAP 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
TCAP_BACKUP	TCAP 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
TCAP_BACKUP_READY	Backup task has finished updating its list of open transactions

The TCAP_EVENT_RUN_STATE 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 Manual for more details on writing redundant TCAP applications.

3.4 SCCP Addressing and Routing

All SCCP connectionless data requests and connection establishment requests contain a mandatory called and calling party address (the calling address is optional for the connection request message). These addresses are passed to and from user applications via the SccpAddr data structure, which is a C-language structure representation of the actual address passed in the SCCP protocol message.

SCCP addresses can take several forms, containing various combinations of point code, subsystem number, and global title. The combination of the address and routing indicator constructed by applications (or received from the SS7 network) together with the SCCP configuration allow these messages to be routed to the correct destination or local application.

3.4.1 Message Routing

For outgoing messages from applications, the called party address in the unitdata request or connection request message is used to route the message. The routing method is chosen based on the value specified in the routing indicator field of the called party address: either routing by point code and subsystem number (ROUTE_PC_SSN) or routing by global title (ROUTE_GLT).

Routing by PC and SSN

When ROUTE_PC_SSN is chosen, the message is routed to the destination point code/subsystem number (DPC/SSN) specified in the called party address. The subsystem number must be present.

If the DPC is present, a route must be configured for the point code and the subsystem must be configured for that route (unless the default routing configuration option is selected).

If the DPC is absent, the message is routed to the point code associated with the first (and typically only) route in the SCCP configuration file, but that point code is not included in the outgoing message. This option is typically used only on point-to-point SS7 links, such as the link between a mobile switching center (MSC) and base station controller (BSC) in a wireless network, where the destination point code is not needed for routing.

If a global title was present in called party address, then it is copied to the outgoing message but the routing indicator remains ROUTE_PC_SSN.

Routing by Global Title

When ROUTE_PC_SSN is chosen, an address translation must be configured that, when combined with the address mask configured for the application SAP, matches the global title specified in the called party address. The message is routed to the point code and subsystem number from the configured address translation entry. If no subsystem number is configured for that address translation but one is supplied by the application, it is copied to the outgoing message.

If the global title must be further translated at another node, then the routing indicator configured in the address translation entry should specify ROUTE_GLT and the point code in the address translation entry specifies the next translator node. If this is the final translation, then the address translation entry should specify ROUTE_PC_SSN and the DPC in the address translation entry specifies the final destination point code.

3.4.2 About Global Titles

When a Global Title is specified by the user, the global title is translated (if possible) by the SCCP task, and the global title is included in the outgoing SCCP address, along with up to four parameters.

The glTransType, encoding, numPlan, and natAddrInd fields are only used in conjunction with the use of a Global Title. Based on the value of the glTitleInd field, some or all of these values are included with a global title in an outgoing SCCP address.

If swType is set to SW_ANSI, there are 2 combinations that may be included with a global title. The glTitleInd field determines which is selected:

global title + translation type (glTitleInd = GLT_TT)

global title + translation type + numbering plan + encoding (GLT_TT_NP_E)

If swType is set to SW_ITU, there are 4 combinations that may be included with a global title. The glTitleInd field determines which is selected:

global title + encoding + nature of address
(glTitleInd = GLT_ITU_FMT1)

global title + translation type (GLT_ITU_FMT2)

global title + translation type + numbering plan + encoding (GLT_ITU_FMT3)

global title + translation type + numbering plan + encoding + nature of address (GLT_ITU_FMT4)

If the user wants the Global Title to be passed to another node for translation, the ROUTING_IND field can be defined in one of the ADDR sections in the SCCP configuration file. If ROUTING_IND is set to GLT, the global title is passed along with its routing field set to Route by Global Title. The Point Code field is included, but the subsystem field is not included in the outgoing message.

Global Title translation is described in the SCCP Configuration section of the Signaling System 7 (SS7) Installation and Configuration Manual. The use of address masks is described, along with the possible replacement of global titles.

3.5 Dialog IDs

A TCAP application uses two dialog IDs to reference a particular transaction: a service user dialog ID (suDlgId) and a service provider dialog ID (spDlgId). Both are 32-bit unsigned integers.

The service user dialog ID is assigned by the application on the first outgoing request for a particular transaction. This ID must be unique among all concurrently active transactions associated with a particular TCAP SAP (subsystem number). The content of this dialog ID is not checked by the TCAP protocol layer, but it is passed back and forth between the application and the TCAP layer on all subsequent requests/indications belonging to that transaction. The application may choose any value it wishes for the suDlgId - an address or index to a data structure, for example - to help it associate a message with its transaction. A suDlgId value may be re-used by the application any time after the previous transaction using that value has completed.

The service provider dialog ID is assigned by the TCAP layer in the first incoming message associated with a particular transaction (either a new transaction indication or a response from a far SP). The application is expected to store this value and pass it back to the TCAP layer on all subsequent requests belonging to that transaction. On the first outgoing request for a transaction, and on any subsequent request prior to receiving an incoming message belonging to that transaction, the application must pass an spDlgId value of zero.

3.6 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 TCAP service must be included in the [ctasys] section of the cta.cfg file, as illustrated:

[ctasys]
Service = tcap, tcapmgr

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

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

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

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