2.1 Introduction

2.2 TCAP Service Users

2.3 Entity and Instance IDs

2.4 API Primitives

2.5 Queues and Contexts

2.6 SCCP Quality of Service (QOS)

2.7 TCAP Transactions

2.8 TCAP API Procedures

2.9 Congestion Control

2.10 TCAP Configuration

2.1 Introduction

This chapter describes the principles of operation for the TCAP API. The API is comprised of a set of primitives (function calls) which provide access to the TCAP layer operations, and a set of events which notify the application of incoming messages, network status, and message delivery errors. The TCAP API also performs the byte ordering translation, where necessary, between application processor ("little endian") byte order and network (or "big endian") byte order.

The TCAP API is implemented as a Natural Access service. Natural Access is a development environment for telephony and signaling applications that provides a standard application programming interface for services, such as signaling protocol stacks, that is independent of the underlying hardware.

Natural Access is described in detail in the Natural Access Developer's Reference Manual. Understanding of the basic Natural Access programming concepts - services, queues, contexts, and asynchronous events - is critical to developing applications which utilize the TCAP API service.

2.2 TCAP Service Users

The TCAP service supports one or more user applications by way of service access points, or SAPs. One SAP is defined for each application that may use the TCAP service. A user applications binds to a particular SAP at initialization time, specifying the SAP ID that it wishes to bind to. Each user SAP is associated with a single SCCP subsystem number. All TCAP messages destined for a particular subsystem number are routed to the application bound to the SAP associated with that subsystem number.

SAPs are illustrated in Figure 2:

.

Figure 2. TCAP Service Access Points (SAPs)

Note: The number of SAPs and the characteristics of each SAP are specified at TCAP configuration time. See the Signaling System 7 (SS7) Installation and Configuration Manual for details.

2.3 Entity and Instance IDs

Each user application must also have a unique entity and instance number, which is used to route messages among the various processes in the system. Entity IDs are single byte values in the range 0x00 to 0x3F, assigned as desired by the application developer. Entity IDs are allocated as follows:

Range	Usage
0x00 to 0x1F	Reserved for use by system utilities, configuration utilities, and management utilities.
0x20 to 0x3F	Available for use by applications.

Instance IDs identify the processor on which the entity executes. The host is always processor 0 (zero), so for all host-resident TCAP user applications this value should be coded to zero. All tasks on TX board number 1 receive an instance ID of 1, all tasks on TX board number two receive and instance ID of 2, and so on.

2.4 API Primitives

The SS7 TCAP service API provides a set of functions which provide the application access to the TCAP layer services. Applications invoke TCAP services by calling TCAP API request primitives which generally result in an TCAP message to a remote exchange, or signaling point (SP). Request primitive parameters are converted by the API to messages and sent via the device driver to the TCAP process.

The TCAP requests from the remote signaling points are presented to the application at the receiving side as indications.

The receiving application may then issue a reply to the originating signaling point by invoking the appropriate TCAP API response primitive. The response primitive is typically translated by the SCCP layer into a protocol message back to the originating signaling point. That response is presented back to the application as a confirmation.

This communication model is illustrated in Figure 3. Some operations, such as sending unit data, include only the request/indication steps. These operations are called unconfirmed operations.

Figure 3. TCAP Communication Model

All API primitives are asynchronous in nature; that is, completion of the API routine implies only that the primitive was successfully initiated (a request message was queued to the SCCP task). Errors detected by the SCCP task result in asynchronous status indications (see below) being sent to the application. Successfully delivered requests generally result in no notification to the application until the far end takes some corresponding action, such as responding to a transaction invoke component with a return-result component.

Indication and confirmation messages, as well as status messages from the local TCAP layer, are passed to application processes as asynchronous events. All events for a particular user SAP (subsystem) are delivered with the associated Natural Access queue. Queues are described in Section 2.5 and in the Natural Access Developer's Reference Manual.

Applications detect that an event is pending through a call to ctaWaitEvent. The application then retrieves the event data from an API primitive which also translates the event parameters from SS7 TCAP raw format to API format.

2.5 Queues and Contexts

Natural Access organizes services and their associated resources around a processing object known as a context. Each instance of an application binding to a TCAP service access point comprises a unique context. Contexts are created with ctaCreateContext.

All events and messages from the TCAP service are delivered to the application through a queue object. Queues are created with ctaCreateQueue. Each context is associated with a single queue through which all events and messages belonging to that context are distributed. More than one context can be assigned to the same queue.

Different application programming models are possible depending on how many TCAP service access points (how many subsystems) are implemented by the application and how the application is organized.

An application that uses a single TCAP service access point uses a single-context single-queue model as shown in Figure 4:

Figure 4. Single-Context, Single-Queue Model

For a single-threaded application which uses multiple service access points (implements multiple subsystems), a multiple-context single-queue model is recommended, as shown in Figure 5. In this case the application has a single event loop with events from all service access points delivered with the same queue. The application determines which service access point a particular event is associated with from a service user ID (suID) value returned with each event.

Figure 5. Multiple-Context, Single-Queue Model

For multi-threaded applications using multiple service access points (one per thread), a multiple-context multiple-queue modes (shown in Figure 6) is recommended. In this case each thread has its own independent event loop, receiving only the events associated with a service access point on its queue.

Note: For this programming model, each thread/event queue must be assigned its own entity ID, which must be unique among all applications on that host accessing any of the SS7 services.

Figure 6. Multiple-Context, Multiple-Queue Model

2.6 SCCP Quality of Service (QOS)

The TCAP layer utilizes the SCCP connectionless transport service to deliver transaction messages to their destinations. With this service, three additional quality of service options are available to the application:

Service Option	Description
Message Priority	The application can assign a priority of from 0 (lowest priority) to 3 (highest priority).
Return Option	This option allows the calling application to request that messages (transaction requests) that cannot be delivered are returned to the application (via a TCAP Status Indication Message). By default, undeliverable messages are discarded by the SCCP layer without notifying the sending application.
Sequential Delivery	The application can request that consecutive transaction requests are delivered in order. This might be required if an application sends multiple transaction messages without waiting for a response to the first transaction request. When this option is selected, TCAP uses the SCCP class 1 connectionless service; by default TCAP uses the SCCP class 0 service, which has no guarantee of delivery order.

2.7 TCAP Transactions

2.7.1 ANSI Transaction Types

The TCAP layer supports the following ANSI transaction types (also called package types):

Transaction Type	Description
Unidirectional	Sends information in one direction only, with no reply expected. No TCAP transaction is established.
Query With Permission	Initiates a TCAP transaction and gives the destination node permission to end the transaction.
Query Without Permission	Initiates a TCAP transaction and notifies the destination node that it may not end the transaction.
Conversation With Permission	Continues a TCAP transaction and gives the destination node permission to end the transaction.
Conversation Without Permission	Continues a TCAP transaction and notifies the destination node that it may not end the transaction.
Response	Ends a TCAP transaction.
Abort	Terminates a TCAP without sending pending components.

2.7.2 ITU-T Transaction Types

The TCAP layer supports the following ITU-T transaction types:

Transaction Type	Description
Unidirectional	Sends information in one direction only, with no reply expected. No TCAP transaction is established.
Begin Transaction	Initiates a TCAP transaction.
Continue Transaction	Continues a TCAP transaction and can be used to transfer data in either direction.
End Transaction	Ends a TCAP transaction.
Abort	Terminates a TCAP without sending pending components.

2.7.3 TCAP Components

TCAP transactions are composed of components, which are remote operation invocations, or invokes, and responses to invokes. Each TCAP message (Begin, Continue, End, Query w/Permission, Response, etc.) is composed of zero or more components. Each component may optionally have application-specific parameters associated with it. Component parameters are not interpreted by the TCAP layer but are passed on to the destination application.

The ANSI and ITU-T standards define a fairly compatible set of component types:

Component Type	Description
Invoke [Last | Not Last]	Invokes a remote operation.
Return Result [Last | Not Last]	Reply for a successful operation invocation.
Return Error	Reply for an unsuccessful operation invocation.
Reject	Reports the receipt and rejection of an incorrect transaction package or component; this may be generated by either the TCAP layer itself or the application.
Cancel	Local operation only; cancels an outstanding invoke between the application and the TCAP layer, but does not notify the far end.

Note: The [Last | Not Last] designation for invokes applies only to ANSI standards; the [Last | Not Last] designation for Return Result components applies to both ANSI and ITU-T

Each invoke component is identified by a unique Invoke ID, assigned by the application that originates the invoke. The Invoke ID is returned in the response, and allows the originator to correlate the reply with the invoke operation to which it belongs.

A receiver of an invoke component can also generate a linked invoke in response to the original invoke received - for example, to collect more information from the sending node before generating the response to the original invoke. The linked invoke carries its own unique Invoke ID plus the Invoke ID of the original invoke, called the correlation ID in ANSI or the linked ID in ITU-T, to allow the originating application to associate the linked invoke with its original invoke.

Finally, in ITU-T only, an invoke operation is assigned by the application to one of four classes, numbered 1 through 4. The class designation specifies under what conditions a response is expected, and determines what a timeout implies about the success or failure of the operation.

Class Type	Description
Class 1	Both successes and failures are reported; a timeout is an "abnormal" failure.
Class 2	Only failure is reported; a timeout implies successful completion.
Class 3	Only success is reported; a timeout implies a failed operation.
Class 4	Neither success or failure is reported; no interpretation of timeout.

2.7.4 Message Lengths and Segmentation

The maximum size of a TCAP transaction, including transaction part, component parts, and application parameters is approximately 254 bytes, possibly less if global titles are used in SCCP addresses.

If an application has transactions (invokes or responses) that exceed the maximum size, it must provide its own segmentation and reassembly, using either the Last/Not Last designation for invokes (ANSI only) or responses, or some other application-specific means.

2.7.5 Multi-threading Considerations

In a multi-threaded application, any thread can generate a transaction request (either initiating a new transaction, or responding to a transaction initiated by a far SP). However, there should be a single receiver thread which receives all asynchronous events from the TCAP layer (new transaction invocations, transaction responses, and status indications) and routes them to the proper "transaction thread" based on the user dialog ID or other transaction information.

Consider, for example, an application which consisted of a main thread, which spawned a "child transaction thread" whenever it wanted to initiate a new transaction. The transaction thread would be responsible for initiating the transaction request, collecting the response, and taking the appropriate action. The application could have many simultaneous transactions, and hence transaction threads, active at any given time.

Multiple transaction threads could generate the transaction requests in any order; the requests would be processed by the TCAP layer in the order that they were received. If each transaction thread then called TCAPRetrieveMessage to retrieve the response to its transaction request, there would be no guarantee that the TCAP message returned by TCAPRetrieveMessage would be associated with the calling thread's transaction. The first thread to call TCAPRetrieveMessage when a message is pending would receive the first pending message, regardless of which transaction it was associated with (in fact, the incoming message could be a new transaction request from a far SP or a network status indication message).

Instead, the main thread itself or a separate child "receiver thread" should be the only caller of TCAPRetrieveMessage. It can then analyze each incoming event and either route it to the proper child transaction thread or, in the case of a new incoming transaction, create a new child transaction thread to handle the incoming transaction request.

Note: In a multi-threaded application like the one described here, ctaInitialize should be called from the parent thread before any of the other API primitives are called by any of the other threads.

2.7.6 Transaction Checkpointing

If two TX boards are configured as a redundant pair, TCAP transaction checkpointing may be used. In this configuration, one board is designated primary, and the other is designated backup. The TCAP task on the Backup board is ready to take over the TCAP service in the event that the Primary board fails or is taken out of service.

To enable the Backup TCAP task to take over the TCAP service, the Primary and Backup TX boards are connected by a private Ethernet connection. The Primary TCAP task sends transaction information to the Backup TCAP task, which is known as transaction checkpointing. If the Primary board fails, or is taken out of service, the Backup TCAP task has a complete list of open TCAP transactions so that it may properly handle TCAP traffic.

The transaction checkpointing process is performed automatically, but can be controlled by the TCAP application. A default checkpointing behavior may be set for each service access point in the TCAP configuration file. The DEFAULT_CHECKPOINT field in the SAP section of the TCAP configuration file may be set to one of the following:

Setting	Description
CHKPT_ALL	Checkpoint all transactions
CHKPT_SEND	Checkpoint only transactions initiated by the application
CHKPT_NONE	Don't checkpoint any transactions

A TCAP application may override the default checkpointing behavior for a single transaction by setting the chkpt field in the TCAPTransInfo structure. The chkpt field may be set to one of the following:

Setting	Description
TCAP_NO_CHKPT	Transaction is not checkpointed
TCAP_CHKPT	Checkpoint this transaction
TCAP_CHKPT_DEFAULT	Use the default checkpoint value

A transaction may be checkpointed at any time during the transaction lifetime. For example, if a Begin message is received and the transaction is not checkpointed (the default is set to CHKPT_SEND or CHKPT_NONE), the transaction may be checkpointed when the application sends a reply (Continue) message by setting the chkpt field to TCAP_CHKPT. All further transaction information will be checkpointed.

2.8 TCAP API Procedures

The following subsections describe how the TCAP API is used to implement application transactions, illustrated by some simple transaction examples.

2.8.1 Initialization/Binding

Before calling any SCCP API primitives, the application must first perform the following steps to set up the environment and bind itself to the desired SCCP SAPs:

1. Call ctaInitialize (once per application) to initialize the Natural Access environment

2. Create one or more queues

3. Create one context per SAP and associate it with the appropriate queue

4. Open the SCCP service, binding the user application to the specified SCCP SAP and associating that SAP with a context and queue (done once for each context used by the application)
   Note: These steps are described in detail in Chapter 3.

It is also recommended that the application call TCAPStateReq and mark the subsystem in service as soon as it is ready to handle data traffic, in case the subsystem was previously left out of service by an application unbinding from the same TCAP SAP.

2.8.2 Transaction Requests

Generating a TCAP transaction requires the following steps (all data structures associated with a transaction are specified in Appendix A).

1. Allocating a memory buffer large enough for the transaction request. A TCAP transaction buffer must be at least TCAP_MSG_SIZE bytes.

2. Assign a unique user dialog ID (suDlgId) for the transaction (if its the first request belonging to this transaction) and populate the transaction information data structure with the message type, dialog ID(s), the originating address, destination address, and quality of service parameters.

3. Initialize the transaction request with TCAPInitTrans.

4. Add 1 or more components to the request with TCAPAddComp. Each invoke component must also have a unique (within the current dialog ID) invoke ID assigned.

5. Send the transaction to the destination SP by calling TCAPTransRqst.

The following subsections illustrate the use of the TCAP API primitives to implement a simple request/response transaction and a more complex conversational linked transaction. The ITU-T and ANSI variants are shown separately to help clarify their conceptual differences.

Simple Request/Response Transaction

A simple transaction consists of a transaction BEGIN (ITU-T) / Query With Permission (ANSI) request with a single INVOKE component, followed by a single END (ITU-T) / RESPONSE (ANSI) message with a single RETURN RESULT component. An example of such a transaction might be a request from a service switching point (SSP) to a service control point (SCP) to translate an 800 number into a subscriber directory number.

Figure 7 illustrates the ANSI version of the simple transaction. Figure 8 shows the ITU-T version.

Figure 7. Simple Transaction - ANSI

Figure 8. Simple Transaction - ITU-T

Conversational/Linked Transaction

An example of a slightly more complicated conversational/linked transaction is shown in Figure 9 (ANSI) and Figure 10 (ITU-T). An example of this type of transaction might occur as follows:

1. A switching application issues an INVOKE on behalf of a subscriber to initiate a feature in a remote switch.

2. The remote switch decides it does not have enough information to carry out the feature invocation; so, it responds with a new INVOKE (linked to the original invoke) to play and announcement to the subscriber and collect digits.

3. The original switch collects the digits and returns them as the result to INVOKE #2.

4. The remote switch now completes the feature invocation and returns the result to INVOKE #1.
   
   
   Figure 9. Conversational/Linked Transaction - ANSI
   
   
   Figure 10. Conversational/Linked Transaction - ITU-T

2.8.3 Handling Abnormal Conditions

A TCAP message consists of two parts, a transaction portion, and a component portion. If a TCAP message has an invalid transaction portion, it generally causes a P-Abort (which terminates the transaction) or it is ignored (which doesn't terminate the transaction). If a TCAP message has an invalid component, a Reject component is generated, but the transaction generally isn't closed. The various possibilities are addressed in this section.

Invalid Transaction Portions

A TCAP transaction may be received that has an invalid Transaction portion. The Transaction portion contains the transaction type (BEGIN (ITU-T)/Query (ANSI)), and any required transaction IDs (TIDs). Generally, if an error is detected and a valid transaction ID can be found, a P-Abort is returned to the sender, a P-Abort indication is delivered to the receiver, and the transaction is closed. However, if the TCAP stack can't find a valid transaction ID, it ignores the message. No response is returned to the sender, and no indication is sent to the receiver. As the message is ignored, any transaction that was open is still open.

The transaction shown illustrates a transaction where an ITU-T TCAP message is received that doesn't have a valid message type (Begin, Continue, End). The message does have a valid Originating Transaction ID, however. The TCAP stack recognizes the invalid message, and sends a P-Abort to the sender. Also, a P-Abort indication is delivered to the receiving application.

Figure 11 illustrates the ITU-T version of the invalid transaction:

Figure 11. Invalid Transaction - ITU-T

Transaction Inactivity Timeouts

Inactivity timeouts can optionally be specified for TCAP transactions. If a specified period of time elapses with no traffic, an Inactivity Timeout indication (TCAP_XACTION_TIMEOUT) is sent to the TCAP application. The TCAP application may then:

• Close the transaction through an end, response, or abort message

• Leave the transaction open with TCAPRetainTrans

• Do nothing and allow the transaction to expire

The TCAPRetainTrans API call resets the inactivity timer for that transaction. If the inactivity timer expires again and no traffic has occurred, another Inactivity Timeout indication will be sent to the application.

If the application does nothing, and no further traffic occurs for the transaction, the inactivity timer will expire a second time, and a P-Abort will close the transaction. The P-Abort indication will be sent to the TCAP application, and if traffic has been received, a P-Abort message will be sent to the destination.

A default inactivity timer value (INACTIVITY_TIMEOUT) may be specified in each SAP section of the TCAP configuration file. If INACTIVITY_TIMEOUT is set to zero, then inactivity timers are not set for any transactions. If INACTIVITY_TIMEOUT is set to a non-zero value, then inactivity timers are set to the specified number (in seconds) for every transaction.

A TCAP application may override the default Inactivity Timer value by setting the inactvTimer field in the TCAPTransInfo structure. If set to zero, the transaction uses the default inactivity timer. If greater than zero, a inactivity timer is set to that number of seconds for that transaction.

If the Inactivity Timer is not used, it is the responsibility of the application to ensure that transactions are closed. If transactions are not closed, then the TCAP task will eventually run of transaction contexts and fail.

A transaction is closed if one of the following occur:

• a P-Abort indication is received

• a User Abort message is sent or received

• An End (ITU-T) or Response (ANSI) message is sent or received

If none of these occur, the application must ensure that the transaction is eventually closed.

Invalid Component in a Begin/Query Message

If the TCAP stack receives a Begin (ITU_T) or Query (ANSI) message with an invalid component, it will pass a Reject component up to the receiving application, but will not automatically send the Reject component back to the Sender. This occurs because the stack is unsure whether to End the transaction, as another component in the message may be valid. In this case, the application must send a Continue or an End with no components. The TCAP stack will attach the Reject component and send it to the original sender.

An example of an invalid component would be if a Return Result or Return Error component is received with an Invoke ID that doesn't correspond to an outstanding Invoke component. In this case, a Reject component is returned to the sender with whatever Invoke ID it was sent with. If the TCAP stack receives a component with an invalid or missing Invoke ID, a Reject component is returned to the sender with an Invoke ID tag of ASN.1 Universal NULL (0x05). The Invoke ID length is set to zero.

In Figure 12, an invalid Invoke component is received. The TCAP stack recognizes the error, and passes up a Reject component to the receiving application. Since the Reject component is contained in a Begin message, the receiving application sends an End message with NO components. The TCAP stack attaches the Reject component (it has saved the component), and sends it to the original sender. The transaction is now closed.

Figure 12. Begin Message with Invalid Component - ITU-T

Invalid Component in a Continue/Conversation Message

If the TCAP stack receives a Continue (ITU-T) or Conversation (ANSI) message with a bad component, it automatically sends a Continue or Conversation with the Reject component back to the sender, and sends the Reject component to the receiving application. In this case, the application doesn't have to send any response.

In Figure 13, after sending an Invoke component, a Continue message with an invalid linked Invoke component is received. The TCAP stack automatically sends a Continue message with a Reject component back to the sender.

In addition, a Continue message with a Reject component is passed to the receiving application. The transaction is still open and can continue or be closed.

Figure 13. Continue Message with Invalid Component - ITU-T

Invalid Component in an End/Response Message

If the TCAP stack receives an End (ITU-T) or Response (ANSI) message with a bad component, it sends the Reject up to the receiving application, but nothing back to the sender, as the Sender has already closed the transaction. In this case, the application doesn't have to send any response.

Figure 14. End Message with Invalid Component - ITU-T

Invoke Time-outs (ITU-T only)

Only the ITU-T protocol implements invoke time-outs. If an application sends an Invoke component, and doesn't receive a Return Result Last, Return Error, or a Reject with the same Invoke ID within a configured time, the Invoke will time-out. A message type of TCAP_LOC_IND is returned with a TCAP_CANCEL component. The application at this point should close the transaction by an End (ITU-T) or a User Abort.

Figure 15. Invoke Timeout - ITU-T

Invalid Component in a Multiple Component Message

A TCAP message may contain multiple components. As soon as an invalid component is detected by the TCAP stack, any valid components are indicated to the receiving application along with the rejected component. Any components after the rejected component are ignored.

For example if a TCAP message is received with three components, and the second component is invalid, the first valid component and the second rejected component are indicated to the receiving application. The third valid component is ignored and not indicated to the receiving application.

2.8.4 Status and Notify Indications

The application may be notified of errors encountered in processing transaction requests by the TCAP layer at any time with unsolicited TCAP Status Indication messages (event type TCAP_EVENT_STA_IND). The status field returned in the status indication message indicates the reason for the error.

Transaction requests that could not be delivered by the SCCP layer due to routing errors, global title translation failures, or temporary network outages, for example, are returned to the originating application (if requested through the SCCP quality of service parameters) via unsolicited TCAP Notify Indication messages (event type TCAP_EVENT_NOT_IND). The notify indication includes a "return cause" field which identifies the reason the message could not be delivered.

2.8.5 Signaling Point and Subsystem Status Procedures

The TCAP API also contains several primitives which provide TCAP applications with access to the SCCP layer facilities for maintaining signaling point and subsystem status between the calling application's system and backup signaling points or concerned signaling points.

Coordinated State Change

An application may request that its subsystem be taken out of service (and have all traffic routed to its backup point code) by invoking TCAPStateReq with a request type of TCAP_COORDREQ. This generates a SCCP Subsystem-Out-Of-Service-Request (SOR) to the backup signaling point (as specified in the SCCP SAP configuration). The application receives an incoming TCAP event with an event type of TCAP_COORDCFM when the backup signaling point returns a Subsystem-Out-Of-Service-Grant (SOG), as shown in Figure 16:

Figure 16. Subsystem Out-of-Service Request

If the backup signaling point fails to return a SOG message and the grant request times out, the TCAP_COORDCFM event indication will contain a special value of UOR_DENIED in the subsystem multiplicity indicator (smi) field, implying that the application should not go out of service.

Alternatively, the backup point code may request to go out of service by sending the SOR message. This results in the application receiving an TCAP_COORDIND event (Figure 17). The application invokes TCAPStateResp with an event type of TCAP_COORDRESP to accept the request and return the SOG message.

Figure 17. Backup Subsystem Out-of-Service Indication

Subsystem State Changes

The application may notify all concerned point codes of a change in its state by invoking TCAPStateReq with a status of SS_IS (in service) or SS_OOS (out of service). This request generates a Subsystem Available (SSA) or Subsystem Prohibited (SSP) message to all concerned signaling points as specified by the SCCP configuration of the application 's SAP (an example of this is shown in Section 2.8.1, Initialization/Binding).

Likewise, when the SCCP task receives messages from concerned signaling points indicating that their status has changed, the application receives an unsolicited TCAP event with an event type of TCAP_SSNSTIND (subsystem status) or TCAP_PCSTIND (point code status).

Remote Signaling Point Failures

An application may monitor the status of remote signaling points by specifying a list of concerned point codes in the SCCP user SAP configuration corresponding to that application.

If all routes to a concerned point code (CPC) become unavailable, the application receives an unsolicited TCAP event with an event type of TCAP_PCSTIND with the status field set to SP_INACC (signaling point inaccessible). In addition, the application receives a receives an unsolicited TCAP event with an event type of TCAP_SSNSTIND with the status field set to SS_OOS (subsystem out-of-service) for each known subsystem at that signaling point.

Similarly, if the MTP layer receives an indication from the remote SP that the SCCP user part is unavailable, the application will receive the TCAP_SSNSTIND (SS_OOS) event for each known subsystem at that signaling point (but not the TCAP_PCSTIND event indication, since in this case just the SCCP user part and not the entire signaling point has failed).

When communication with the affected signaling point is restored, the application receives an unsolicited TCAP event with an event type of TCAP_PCSTIND and the status field set to SP_ACC (SP accessible). At this point the SCCP layer initiates subsystem status testing of all known subsystems at the affected SP. When a subsystem available message is returned by the affected SP, the application receives a TCAP event with an event type of TCAP_SSNSTIND and the status field set to SS_IS (subsystem in-service). At this point the application may re-establish communication with the affected SP/subsystem.

Figure 18 shows an example of remote signaling point failure and recovery procedures.

Figure 18. Remote Signaling Point Failure and Recovery

2.9 Congestion Control

Understanding the TCAP service congestion control mechanisms and developing an effective application congestion control strategy is a critical step in developing a reliable system.

The TCAP service implements a four-level congestion control strategy, where level zero indicates that TCAP is not congested and level three reflects the most congested state. The TCAP service further distinguishes between inbound (from the network and towards the application) and outbound (from the application and towards the network) congestion and keeps a separate congestion level for each direction.

Congestion control mechanisms include both notifications to applications of congestion conditions and congestion control actions within the TCAP layer itself. The purpose of congestion notifications is to allow the application to take some corrective action, such as reducing the traffic load that it generates, before the congestion becomes severe and impacts the operation of the service. The purpose of the congestion control actions within TCAP are to maintain the operation of the SS7 stack (possibly at a reduced capacity), including the operation of other SS7 layers and/or applications, during periods of congestion.

2.9.1 Outbound Congestion

In TCAP, there are three possible causes of outbound congestion:

• The user application generates TCAP traffic at a rate greater than the capacity of the SS7 links or downstream network, resulting in network overload.

• The user application generates TCAP requests faster than they can be processed by the TCAP layer, resulting in the TCAP API send queue building up beyond pre-determined thresholds.

• The overall memory available to the TCAP layer drops below pre-determined thresholds.

Network Overload

Network overload occurs when the MTP layer's outbound queues build up beyond configured limits due to a traffic load which exceeds the capacity of the available signaling links; or, due to receipt of a transfer controlled message (TFC) regarding a congested destination.

In either case, the user application is notified by receipt of a TCAP PC-STATE indication containing the affected pointed code and the current congestion level (Figure 19). The application should then reduce its traffic load toward the affected destination until the congestion abates. How the reduction is accomplished is up to the application. The TCAP layer itself takes no action to prevent further congestion.

Figure 19. Network Overload

In ANSI networks and in other national networks employing multiple congestion levels, the user application must not generate any new traffic towards the affected destination with a priority lower than the current destination congestion level, as it will be discarded at the MTP layer.

For the international signaling network, and other ITU-based networks without multiple congestion priorities, it is especially important for the user application to reduce the traffic load toward the affected destination, as the MTP layer only discards outgoing packets in cases of excessive queuing of traffic to congested signaling links. Failure of the application to reduce its traffic load toward the congested destination may escalate the congestion condition.

When the network overload condition ceases, the user application receives a TCAP PC-STATE indication containing the affected point code and a status value of SP_CONG_OFF, indicating that the application may resume normal traffic towards the affected destination.

TCAP API Congestion

TCAP API congestion occurs when either the application generates traffic faster than it can be accepted by the TCAP layer, resulting in the TCAP API transmission queue building beyond pre-determined thresholds. The application is notified of API congestion by receipt of a TCAPEVN_CONGEST Natural Access event which includes the current TCAP congestion level (0-3, where 0 indicates that congestion has ceased). As the TCAP congestion level increases, the application is expected to reduce its traffic load proportionately until the congestion ceases.

Note: The application receives the TCAPEVN_CONGEST event in the case of either TCAP API congestion or TCAP layer congestion (described below). If it is necessary to distinguish between these two causes, the application can call TCAPGetApiStats to check the current congestion level for each of the possible causes to determine the cause of the current congestion.

By default, the TCAP API allocates a buffer pool for up to 128 requests to be queued to the TCAP layer. If the application fails to reduce its traffic load enough to ease the congestion, the TCAP API buffer pool will eventually become depleted and the TCAP API primitives will fail with a CTAERR_OUT_OF_MEMORY return code. The application can increase the number of buffers in the pool (allowing a larger burst of traffic to be absorbed without triggering congestion, at the cost of more host memory used) by setting service argument array element six to a number between 128 and 1024 when opening the TCAP service (see section 3.2.3). Congestion onset and abatement thresholds are always set to a fixed percentage of the in-use (queued to the TCAP layer) regardless of the total size of the pool, as shown in the following table:

Congestion Levels	Onset Threshold (to reach this level)	Abatement Threshold (to next lower level)
1	Greater than 75% of pool in use	Less than 50% of pool in use
2	Greater than 85% of pool in use	Less than 80% of pool in use
3	Greater than 95% of pool in use	Less than90% of pool in use

TCAP Layer Congestion

TCAP layer outbound congestion occurs when the amount of memory available to the TCAP layer for processing new transaction requests falls below configurable thresholds. For the embedded TX board-based TCAP this is the total percentage of available free memory on the board.

Like TCAP API congestion, the application is notified of TCAP layer outbound by receipt of a TCAPEVN_CONGEST Natural Access event which includes the current TCAP congestion level (0-3, where 0 indicates that congestion has ceased). As the TCAP congestion level increases, the application is expected to reduce its traffic load proportionately until the congestion ceases. The TCAP layer also takes action to protect the integrity of the SS7 stack and minimize the impact of the congestion on other services. The following table shows the TCAP layer reaction to outbound congestion.

Congestion Level	TCAP Action
1	Alarm only - no traffic restriction.
2	No new outbound transactions (BEGIN or QUERY type) allowed. TCAP responds to each new transaction request from a user application with a TCAP_STATUS_IND event with a status of TCAP_CONGESTED (unless inbound congestion level is also at level three) and the SAP "outbound congestion abort" counter is pegged. Other transaction messages (CONTINUE/CONVERSATION, RESPONSE/END, and ABORT) are allowed.
3	All outbound messages are discarded and the SAP "outbound congestion discard" counter is pegged.

Note: User applications are always notified of a change in the outbound congestion level with a TCAPEVN_CONGEST event and an alarm is always generated.

The congestion onset thresholds for TCAP layer congestion can be adjusted with TCAPGenCfg or the tcapcfg utility TCMEM_THRESH_X parameters. The congestion abatement thresholds for each congestion level are set midway between the previous two congestion onset thresholds See Chapter 9 in the Signaling System 7 (SS7) Installation and Configuration Manual for more details.

2.9.2 Inbound Congestion

TCAP inbound congestion is caused by one of two possible conditions:

• The TCAP user application is not reading incoming messages as fast as they are being generated by the network, resulting in build-up of the user queue.

• The overall memory available to the TCAP layer drops below pre-determined thresholds.

The inbound congestion level of each TCAP user SAP at any given point in time is defined to be the more severe of the current TCAP layer memory congestion level and the user SAP queue congestion level. A low memory condition affects the inbound (and outbound) congestion level of all user SAPs. A queue build-up congestion condition affects the inbound congestion level of only the user SAP whose queue is building or receding.

Unlike outbound congestion, the TCAP user application is not notified directly of inbound congestion level changes, to prevent escalation of the congestion condition; however, an alarm is always generated when a change in a TCAP user SAP's inbound congestion level occurs. The current inbound congestion level of a user SAP can also be determined by calling TCAPSapStats or by using the tcapmgr utility STATS command.

For inbound congestion, the TCAP layer cannot rely on the user application to reduce its traffic load to ease the congestion, as the source of the traffic bursts is generally other network nodes. Instead, the TCAP layer acts directly to control inbound congestion by restricting the types of traffic that are allowed at the various congestion levels. These actions are described in the following table:

Congestion Level	TCAP Action
1	Alarm only - no traffic restriction.
2	No new inbound transactions allowed.TCAP responds to each incoming BEGIN (ITU) or QUERY (ANSI) transaction with a P-Abort with a cause of "resource limitation" (ITU) or "resource unavailable" (ANSI) and the SAP's inbound congestion abort counter is pegged; other transaction messages are allowed.
3	All inbound messages are discarded and the SAP's inbound congestion discard counter is pegged.

The memory onset and abatement thresholds may be adjusted with the same configuration parameters described in the TCAP Layer Congestion section for outbound congestion.

By default, the user SAP queue congestion thresholds are set to absorb approximately a two second burst of TCAP traffic at maximum load (based on a TX 3220 performance model with 32 MB of memory) of 600 messages without the user application retrieving a message before congestion control is triggered. For other board models, or to accommodate other traffic patterns which may be application-specific, the user SAP queue congestion thresholds can be adjusted with TCAPSapCfg or the TCAP configuration utility TCQ_THRESH_<n> (user SAP) parameters. The congestion abatement thresholds for each congestion level are set midway between the previous 2 congestion onset thresholds See Chapter 9 of the Signaling System 7 (SS7) Installation and Configuration Manual for more details.

2.10 TCAP Configuration

A standard configuration application is provided to read the SS7 (including TCAP) configuration from a (set of) text file(s) and download the configuration to the SS7 tasks running on the TX device (see the Signaling System 7 (SS7) Installation and Configuration Manual).

The TCAP layer supports the following configuration entities:

Configuration	Description
General	The general configuration defines the resource allocation for the TCAP layer: maximum number of user SAPs, maximum number of simultaneous dialogs, and maximum number of outstanding invokes. The general configuration is loaded only once at system boot time and must be loaded before any other configuration entities.
User SAPs	One user SAP is defined for each application using the TCAP layer services. A user SAP is associated with a single subsystem number and protocol switch type (ANSI-88, ANSI-92, ITU-88, ITU-92, or ITU-97). The user SAP defines the default timer values for invokes issued on the SAP and identifies the SCCP user SAP to be used. User SAPs (up to the maximum number specified in the general configuration) may be added any time after the general configuration has been set.

In addition to the API primitives, a standard configuration application is provided to read the TCAP configuration from a text file and download the configuration to the TCAP task running on the TX board (see the Signaling System 7 (SS7) Installation and Configuration Manual). The configuration application (tcapcfg) is distributed in both source and executable form; the executable may be used as a stand-alone configuration tool or the source can be used as a guide to developing a configuration utility with the TCAP management API.