(Page 1 of 1 in this chapter) Version

Chapter 2

Programming Model

2.1 ISUP Service Users

2.2 Entity and Instance IDs

2.3 API Primitives

2.4 Contexts and Queues

2.5 Configuring ISUP for the Japan/NTT Variant

2.6 Signaling Parameters

2.7 ISUP API Procedures

: 2.7.1 Initialization and Binding
: 2.7.2 Connection Establishment
: 2.7.3 Connection Establishment with Continuity Check Required
: 2.7.4 Continuity Recheck
: 2.7.5 Aborted Continuity Check
: 2.7.6 Data Transfer
: 2.7.7 Connection Clearing
: 2.7.8 Circuit Reset
: 2.7.9 Circuit Group Reset
: 2.7.10 Circuit Blocking/Unblocking
: 2.7.11 Circuit Group Blocking/Unblocking
: 2.7.12 Circuit Group Query

2.1 ISUP Service Users

The ISUP user interface 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 ISUP service. A user applications binds to a particular SAP at initialization time, specifying the SAP ID to which it wishes to bind. Associated with each user SAP (in the ISUP configuration file) is a switch type (CCITT, ANSI-88, or ANSI-92) which the ISUP process uses to associate with its configured network connections. Multiple SAPs, and hence multiple applications, for a particular switch type may be defined for outgoing call requests. Incoming messages which are associated with a previously issued outgoing request are always routed to the SAP that issued the original outgoing request. Incoming call requests, however, are always routed to the first SAP whose switch type matches the switch type of the network connection that the request was received over. Note: The number of SAPs and the characteristics of each SAP are specified in the ISUP configuration file. See the Signaling System 7 (SS7) Installation and Configuration Manual for details.

2.2 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...0x3F, assigned as desired by the application developer. Entity IDs are allocated as follows: Range Usage 0x00 - 0x1F Reserved for use by system utilities, configuration utilities, and management utilities 0x20 - 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 ISUP 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 2 receive an instance ID of 2, and so on.

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

2.3 API Primitives

The SS7 ISUP API provides a set of functions which provide the application access to the ISUP layer services. Applications invoke ISUP services by calling ISUP API request primitives which generally result in an ISUP message to a remote exchange, or endpoint. Request primitive parameters are converted by the API to messages and sent by the host OS TX driver to the ISUP process.
The ISUP requests from the remote endpoints are presented to the application as indications, through the same driver and API mechanisms through which confirmations are received. The application may then issue a reply to the endpoint by invoking the appropriate ISUP API response primitive.
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 ISUP task). Errors detected by the ISUP 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, for example, returning a connect confirm message in response to a connect request.
Indication and confirmation messages, as well as status messages from the local ISUP layer, are passed to application processes as asynchronous events. All events for a particular user SAP (subsystem) are delivered via the associated CT Access queue. Queues are described in the next section and in the CT Access Developer's Reference Manual.
Applications detect that an event is pending through an operating system specific mechanism such as poll in UNIX or WaitForMultipleObjects in Windows NT. The application then retrieves the event data (also known as a message) via an API primitive which also translates the confirmation parameters from SS7 ISUP raw format to API format.

2.4 Contexts and Queues

CT Access organizes services and their associated resources around a processing object known as a context. Each instance of an application binding to an ISUP service SAP comprises a unique CTA context. Contexts are created with the ctaCreateContext primitive.
All events and messages from the ISUP service are delivered to the application via a CTA queue object. Queues are created with the ctaCreateQueue primitive. 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 ISUP service SAPs (i.e., how many subsystems) are implemented by the application and how the application is organized.
An application that uses a single ISUP SAP uses a single-context single-queue model as shown in Figure 2. Figure 2. Single-Context, Single-Queue Model
For a single-threaded application which uses multiple ISUP SAPs (implements multiple subsystems), a multiple-context single-queue model is recommended, as shown in Figure 3. In this case the application has a single event loop with events from all SAPs delivered via the same queue. The application determines which SAP a particular event is associated with from a service user ID (suID) value returned with each event. Figure 3. Multiple-Context, Single-Queue Model
For multi-threaded applications using multiple ISUP SAPs (one per thread), a multiple-context multiple-queue modes (shown in Figure 4) is recommended. In this case each thread has its own independent event loop, receiving only the events associated with its SCCP SAP on its CTA 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 4. Multiple-Context, Multiple-Queue Model

2.5 Configuring ISUP for the Japan/NTT Variant

The SWITCH_TYPE attribute for all USAP, NSAP, and CIRCUIT entries should be set to JNTT.
16-bit point codes may be specified in either hex or in "x.y.z" dotted notation. Hex point codes must be specified in the same order that they are transmitted on the link; that is, the U-code in the most significant 7 bits, the S-code in the next 4 bits, and the M-code in the least significant 5 bits.
In order to specify J-NTT 16 bit point codes in "x.y.z" notation, the following statement must be added to the MTP3 general configuration section: PC_FORMAT JNTT
This tells the ISUP configuration utility to treat all subsequent point codes as M-Code.S-Code.U-Code format and generate 16-bit internal point codes with the U-code in the most significant 7 bits, the S-code in the next 4 bits, and the M-code in the least significant 5 bits.

2.6 Signaling Parameters

Signaling parameters are passed between the application process and the ISUP process in the form of events. Events are fixed format structures consisting of one or more information elements. Information elements are fixed format structures consisting of a flag indicating their presence or absence from the corresponding ISUP message, and one or more tokens, or fields. Likewise, each token is a structure consisting of a flag indicating its presence or absence, possible filler to insure proper byte alignment, and a value.
The event/information element/token structure greatly simplifies applications by allowing them to operate on fixed format structures rather than the variable length/variable formats employed by the ISUP protocol. Figure 5. Sample Event/Information Element/Token Structure

2.7 ISUP API Procedures

The SS7 ISUP interface typically consists of several phases: binding, connection establishment, data transfer, and connection clearing. In addition, there are miscellaneous requests and indications which may take place outside of the context of any particular connection. These stages are described in the following subsections.

2.7.1 Initialization and Binding

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

Call the ctaInitialize primitive (once per application) to initialize the CT Access environment

Create one or more CTA queues

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

Open the ISUP service, binding the user application to the specified ISUP SAP and associating that SAP with a CTA 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 the ISUPStatusReq primitive 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 ISUP SAP.

2.7.2 Connection Establishment

The application initiates a circuit switched connection by invoking the ISUPConnectReq primitive. This results in the generation of an ISUP Initial Address Message (IAM) to the far exchange. Alternatively, the far exchange may initiate the connection by sending the IAM message. This results in the application receiving a connect indication (EVTSITCONIND) event.

Figure 6. Outgoing Connection Establishment (dashed lines indicate optional messages)
During the connection establishment phase, the application exchanges call progress and other status information with the far exchange by invoking the ISUPConnectStatusReq primitive (with the desired event type) and by receiving connect status indications (EVTSITCNSTIND) from the ISUP process.

Figure 7. Incoming Connection Establishment
The connection establishment phase ends when the application receives a connect confirmation event (EVTSITCONCFM) (far exchange sent Answer or Connect message); or, for an incoming call, the application invoked the ISUPConnectResp primitive to signal to the far end that the connection is established.

2.7.3 Connection Establishment with Continuity Check Required

The application initiates a circuit switched connection with continuity check required by invoking the ISUPConnectReq primitive with the Nature of Connection Indicator IE field contChk set to CONTCHK_REQ. This results in the generation of an ISUP Initial Address Message (IAM) to the far exchange. When the Initial Address Message has been sent, the ISUP layer will issue a status indication (EVTSITSTAIND) with event type CONTCHK to the application. This is an indication to the application to perform the continuity check on the circuit. The application then reports the results of the continuity check by calling the ISUPStatusReq primitive with event type of CONTREP. Assuming that the continuity test is successful, call processing resumes normally. If the continuity test fails, the application should request a recheck of the circuit as described in Section 2.7.4, Continuity Recheck. Optionally, the application may release the connection as described in Section 2.7.7, Connection Clearing.

Figure 8. Outgoing Connection Establishment with Continuity Check Required
Alternatively, the far exchange may initiate the connection with continuity check required by sending the IAM message. This results in the application receiving a connect indication (EVTSITCONIND) event with the Nature of Connection Indicator IE field contChk set to CONTCHK_REQ. This is an indication to the application to set up a loopback condition on the specified circuit. The far exchange then performs the continuity check and sends a Continuity Message (COT) to report the results of the check. This results in the generation of a status indication (EVTSITSTAIND) with event type CONTREP to the application. Regardless of the results of the check, the application should remove the loop back condition on the circuit. If the continuity check was successful (status event structure contInd IE set to CONTCHK_SUCC) the application should continue with normal call setup. In the case of failure (status event structure contInd IE set to CONTCHK_FAIL), the application should wait for continuity recheck on the indicated circuit. (See Section 2.7.4, Continuity Recheck). Figure 9. Incoming Connection Establishment with Continuity Check Required

2.7.4 Continuity Recheck

The application initiates a continuity recheck by invoking the ISUPStatusReq primitive with the event type of CONTCHK. This will cause the ISUP layer to send a Continuity Check Request message (CCR) to the far exchange. The far exchange will the set the indicated circuit in a loop back condition, and acknowledge with a Loop Back Acknowledgment message (LPA). Upon receipt of this message, the ISUP layer will issue a status indication (EVTSITSTAIND) to the application with event type of LOOPBACK. The application should then perform the continuity check. If the continuity check fails, the application should invoke the ISUPStatusReq primitive with the event type of CONTREP.

Figure 10. Outgoing Continuity Recheck Failure
If the continuity check is successful, the application should release the connection by following the procedures for outgoing release as described in Section 2.7.7, Connection Clearing. Figure 11. Outgoing Continuity Recheck Success
When a Continuity Check Request message (CCR) is received from the far exchange, the ISUP layer will issue a status indication (EVTSITSTAIND) with event type of CONTCHK to the application. The application should set the specified circuit into a loop back condition and acknowledge the request by invoking the ISUPStatusReq primitive with event type of LOOPBACK. If the continuity test fails, the far exchange will report the results with a Continuity message (COT). This will be presented to the application by the ISUP layer as a status indication (EVTSITSTAIND) with event type of CONTREP.

Figure 12. Incoming Continuity Recheck Failure
If successful, the far exchange will transmit a Release message (REL), which will be presented as a release indication (EVTSITRELIND) to the application. The application should the follow the normal procedures for a far exchange initiated release as described in Section 2.7.7, Connection Clearing. Figure 13. Incoming Continuity Recheck Success

2.7.5 Aborted Continuity Check

If, after transmitting an Initial Address message (IAM) with continuity check required, the ISUP layer receives a Release message (REL) from the far exchange, the ISUP layer will issue a status indication (EVTSITSTAIND) with event type STPCONTIND to the application. The application should then remove the check tone from the indicated circuit. The ISUP layer will subsequently issue a release indication (EVTSITRELIND) to the application. The application should then follow the normal procedure for an incoming release as described in Section 2.7.7, Connection Clearing. Figure 14. Aborted Outgoing Connection Establishment with Continuity Check Required
After sending an Initial Address message (IAM) with continuity check required, the far exchange may transmit a Release message (REL) instead of a Continuity message (COT). In this case, the application will receive a status indication (EVTSITSTAIND) with event type STPCONTIN. The application should remove the loopback condition from the designated circuit. The application will subsequently receive a release indication (EVTSITRELIND). The application should then follow the normal procedure for an incoming release as described in Section 2.7.7, Connection Clearing. Figure 15. Aborted Incoming Connection Establishment with Continuity Check Required

2.7.6 Data Transfer

During the time that the call is connected, the application may exchange user-to-user information with its peer in the far exchange by invoking the ISUPDataReq primitive and/or receiving data indications (EVTSITDATIND) from the ISUP layer.
During this time, the circuit connection may also be suspended/resumed by either party via the ISUPSuspendReq primitive or receiving a suspend indication event (EVTSITSUSPIND), and the ISUPResumeReq primitive or receiving a resume indication event (EVTSITRESMIND), respectively.

2.7.7 Connection Clearing

The application requests clearing of a connection by invoking the ISUPReleaseReq primitive, and is notified of the completion of the release procedure (i.e., the receipt of a Release Complete message) by receipt of a release confirm (EVTRELCFM) event.

Figure 16. Application Connection Release
If the far exchange initiates the release of the connection, the application receives an release indication event (EVTSITRELIND) from the ISUP layer. The application then completes the connection release by invoking the ISUPReleaseResp primitive to send the Release Complete message to the far exchange.

Figure 17. Far Exchange Connection Release

2.7.8 Circuit Reset

The application requests the reset of a circuit by invoking the ISUPStatusReq primitive with the event type of CIRRESREQ. When an acknowledgment (Release Complete message) is received from the far exchange, the ISUP layer delivers release confirm (EVTSITRELCFM) event to the application. The application may consider the circuit reset upon receiving this indication.

Figure 18. Application Initiated Circuit Reset
If the far exchange initiates the reset of the circuit, the application receives a status indication (EVTSITSTAIND) with the event type of CIRRESREQ from the ISUP layer. The application may consider the circuit reset upon receiving this indication. The ISUP task will acknowledge the reset request by sending a Release Complete message (RLC). Note: If the application had issued any request related to this circuit that had not been processed by the ISUP layer before receipt of the Circuit Reset message, the application will receive an error indication (EVTSITERRIND) with the cause code CCINVALCALLREF. The application may choose to ignore this indication. Figure 19. Far Exchange Initiated Circuit Reset
The ISUP layer may determine (due to protocol errors) that a particular circuit should be reset. Under these circumstances, the ISUP layer will issue a status indication (EVTSITSTAIND) with the event type of CIRRESREQLOC, and send a Circuit Reset message to the far exchange. When an acknowledgment (Release Complete message) is received from the far exchange, the ISUP layer delivers release confirm (EVTSITRELCFM) event to the application. The application may consider the circuit reset upon receiving this indication. Figure 20. ISUP Layer Initiated Circuit Reset

2.7.9 Circuit Group Reset

The application requests the reset of a circuit group by invoking the ISUPStatusReq primitive with the event type of CIRGRPRESREQ, and is notified of the completion of the group reset procedure (i.e., the receipt of a Group Reset Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPRESACK.

Figure 21. Application Initiated Group Reset Request
If the far exchange initiates the reset of the circuit group, the application receives a status indication (EVTSITSTAIND) with the event type of CIRRESREQ from the ISUP layer for each circuit in the circuit group. The application may consider these circuits reset upon receiving these indications. The ISUP task will acknowledge the group reset request by sending a Group Reset Acknowledgment message (GRA). Figure 22. Far Exchange Initiated Group Reset Request

2.7.10 Circuit Blocking/Unblocking

The application requests blocking of a circuit by invoking the ISUPStatusReq primitive with the event type of CIRBLKREQ, and is notified of the completion of the blocking procedure (i.e., the receipt of a Blocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRBLKRSP.

Figure 23. Application Initiated Blocking Request
If the far exchange initiates the blocking of the circuit, the application receives a status indication (EVTSITSTAIND) with the event type of CIRBLKREQ from the ISUP layer. The application then acknowledges the circuit blocking by invoking the ISUPStatusReq primitive with the event type of CIRBLKRSP.

Figure 24. Far Exchange Initiated Blocking Request
The application requests unblocking of a circuit by invoking the ISUPStatusReq primitive with the event type of CIRUNBLKREQ, and is notified of the completion of the unblocking procedure (i.e., the receipt of an Unblocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRUNBLKRSP.

Figure 25. Application Initiated Unblocking Request
If the far exchange initiates the unblocking of the circuit, the application receives a status indication (EVTSITSTAIND) with the event type of CIRUNBLKREQ from the ISUP layer. The application then acknowledges the circuit unblocking by invoking the ISUPStatusReq primitive with the event type of CIRUNBLKRSP.

Figure 26. Far Exchange Initiated Unblocking Request

2.7.11 Circuit Group Blocking/Unblocking

The application requests blocking of a circuit group by invoking the ISUPStatusReq primitive with the event type of CIRGRPBLKREQ, and is notified of the completion of the group blocking procedure (i.e., the receipt of a Group Blocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPBLKRSP.

Figure 27. Application Initiated Group Blocking Request
If the far exchange initiates the blocking of the circuit group, the application receives a status indication (EVTSITSTAIND) with the event type of CIRGRPBLKREQ from the ISUP layer. The application acknowledges the circuit group blocking by invoking the ISUPStatusReq primitive with the event type of CIRGRPBLKRSP.

Figure 28. Far Exchange Initiated Group Blocking Request
The application requests unblocking of a circuit group by invoking the ISUPStatusReq primitive with the event type of CIRGRPUNBLKREQ, and is notified of the completion of the group unblocking procedure (i.e., the receipt of a Group Unblocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPUNBLKRSP.

Figure 29. Application Initiated Group Unblocking Request
If the far exchange initiates the unblocking of the circuit group, the application receives a status indication (EVTSITSTAIND) with the event type of CIRGRPUNBLKREQ from the ISUP layer. The application then acknowledges the circuit group unblocking by invoking the ISUPStatusReq primitive with the event type of CIRGRPUNBLKRSP.

Figure 30. Far Exchange Initiated Group Unblocking Request

2.7.12 Circuit Group Query

The application may initiate a circuit group query by invoking the ISUPStatusReq primitive with the event type of CIRGRPQRYREQ, and is notified of the completion of the group query request (i.e., the receipt of a Circuit Query Response message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPQRYRSP.

Figure 31. Application Initiated Circuit Group Query Request

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com