(Page 1 of 1 in this chapter)

Chapter 2

SS7 SCCP API Description

2.1 SCCP Service Users
2.2 Entity and Instance IDs
2.3 API Primitives
2.4 Messages, Parameters, and Fields
2.5 Operating System Specific Considerations
2.5.1 Receiving Confirmations and Indications
2.5.2 UnixWare and Solaris Systems
2.5.3 Windows NT
2.6 SCCP API Procedures
2.6.1 Initialization/Binding
2.6.2 Connectionless Data Transfer
2.6.3 Connection Establishment
2.6.4 Data Transfer
2.6.5 Connection Reset
2.6.6 Connection Clearing
2.6.7 Status Indications
2.6.8 Signaling Point and Subsystem Status Procedures
2.6.9 Coordinated State Change
2.6.10 Subsystem State Changes
2.6.11 Remote Signaling Point Failures
2.7 SCCP Configuration
2.8 Unsolicited Alarms

The following subsections provide a more detailed description of the SCCP API.

2.1 SCCP Service Users

The SCCP 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 SCCP 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 SCCP subsystem number. All SCCP messages destined for a particular subsystem number are routed to the application bound to the SAP associated with that subsystem number.

An application may implement multiple subsystems by binding to multiple SCCP SAPs. If an application supports multiple TX Series boards, it must bind with each board separately.

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

Each SAP (and hence subsystem number) may optionally have backup point codes - that is a backup node which implements the same subsystem - and/or a set of concerned point codes which are notified by the SCCP process whenever the availability of the subsystem changes.

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. The following entity IDs are reserved.

0x00 - 0x13

 Reserved

ISUP

 0x14

 ISDN User Part Protocol Handler

MTP3

 0x15

 Message Transfer Part Layer 3

MTP2

 0x16

 Message Transfer Part Layer 2

 0x17 - 0x1B

 Reserved

MTP1

 0x1C

 Message Transfer Part Layer 1

 0x1D

 Reserved

SCCP

 0x1E

 SCCP Protocol Handler

 0x1F

 Reserved

 0x20 - 0x3F

 Available for applications

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

2.3 API Primitives

The SS7 SCCP API provides a set of functions which provide the application access to the SCCP layer services. Applications invoke SCCP services by calling SCCP API request primitives which generally result in an SCCP message to a remote exchange, or end point. Request primitive parameters are converted by the API to messages and sent via the host OS TX Series driver to the SCCP process.

The remote end point may optionally return a confirmation (i.e., acknowledgment), which is delivered to the application via the TX Series driver. The application retrieves the confirmation via an API primitive which also translates the confirmation parameters from SS7/SCCP raw format to API format.

The SCCP requests from the remote end points 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 end point by invoking the appropriate SCCP API response primitive.

Note: All API requests are asynchronous in nature; that is, completion of the API routine implies only that the request was successfully queued to the SCCP task. Errors detected by the SCCP task result in asynchronous status indications 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 returning a connect confirm message in response to a connect request sent by the application.

In addition to performing IPC message handling on behalf of the application, the SCCP API primitives also perform the byte ordering translation, where necessary, between application processor (Intel, or "little endian") byte order and network (or "big endian") byte order.

2.4 Messages, Parameters, and Fields

Signaling parameters are passed between the application process and the SCCP process in the form of messages, which correlate (for the most part) with actual SCCP messages exchanged across the link. Messages are fixed format structures consisting of one or more parameters (sometimes referred to as information elements, or IEs).

Parameters themselves are fixed format structures consisting of one or more fields. Parameters that may be optional in a message contain a flag indicating their presence or absence from the corresponding SCCP message.

Applications generate SCCP messages by allocating a message structure, populating the values and setting the "present indicator" for each optional parameters it wishes to include in the message, and passing the message to the appropriate SCCP API primitive.

Likewise, once received messages have been decoded into the fixed message format by the SCCP API, the application can scan each parameter to determine if it was present in the SCCP protocol message and, if so, extract its field values.

The message/parameter/field structure greatly simplifies applications by allowing them to operate on fixed format structures rather than the variable length/variable formats employed by the SCCP protocol. Figure 2 shows an example message from the SCCP API.

Figure 2. Sample Message/Parameter/Field Structure

2.5 Operating System Specific Considerations

The following subsections address specific concerns depending on which operating system the SCCP software is run.

2.5.1 Receiving Confirmations and Indications

Applications receive confirmations (responses) and indications of far-end initiated requests by periodically calling the SCCPRetrieveMessage primitive. This primitive checks for an incoming message and returns an indication of whether or not a message is available. When an incoming message is received, SCCPRetrieveMessage copies the event structure to the buffer provided by the caller, performs any byte-order translation between network byte order and host byte order necessary, and reports which event was received back to the calling application. The application must periodically call this primitive to receive messages from the SCCP layer.

2.5.2 UnixWare and Solaris Systems

To allow applications more flexibility in handling multiple devices, the SCCP API makes the device file descriptor (or handle) used to access the TX Series device available to the application (see the SCCPInitAPI routine description). Use of this file descriptor is operating system dependent, but is generally intended to allow the application to utilize operating system facilities to determine when a message from the SCCP layer is available rather than periodically call SCCPRetrieveMessage to "poll" the TX Series device.

For example, the value returned on UnixWare and Solaris systems is a file descriptor for an open streams device. The application may use this file descriptor with the poll or select system calls to determine when a message from the SCCP layer is available. The application should then call SCCPRetrieveMessage to read and decode the message (i.e., the application should not call getmsg directly).

2.5.3 Windows NT

On Windows NT systems, an application can obtain a handle (via the SCCPSyncObj primitive) which can be used with the WIN32 WaitForSingleObject or WaitForMultipleObjects system calls to efficiently perform asynchronous, or non-blocking, I/O. This allows an application to determine when a message from a single TX Series device or from any TX Series device in a multiple board installation is available without having to periodically call SCCPRetrieveMessage to "poll" each TX Series device.

To access this "synchronization handle," the application performs the following.

  1. After calling SCCPInitAPI, the application calls SCCPSyncObj to obtain the synchronization handle.

    

  2. The application uses the synchronization handle WaitForSingleObject or WaitForMultipleObjects to check or wait for a message.  
    

    

  3. When WaitForSingleObject or WaitForMultipleObjects indicates an event completion on the corresponding TX Series synchronization handle, the application then calls SCCPRetrieveMessage (passing the original handle from SCCPInitAPI, not the synchronization handle) to retrieve and decode the packet.
    

    
 
    








2.6	 SCCP API Procedures





The SS7 SCCP interface for connection oriented services consists of four phases:  initialization/binding, connection establishment, data transfer, and connection clearing.  For connectionless services, only the initialization/binding and data transfer phases are employed.  These stages are described in the following subsections.






2.6.1	 Initialization/Binding





Before calling any other API primitives, the application must first call the SCCPInitAPI primitive to initialize the API.  This primitive "opens" the TX Series driver and allocates any other resources needed by the API.  It may be called once to initialize the API for all TX Series boards or separately for each board.  When the SCCP API is no longer needed (for example, during a graceful system shutdown) the SCCPTermAPI primitive is called to free up any resources allocated by the API.



The binding phase establishes the application as a user of the SCCP interface, identifying a particular SAP. Binding consists of a single BIND request from the application to SCCP, for which there is no response (it always succeeds). Errors in the binding process are noted by alarms generated by the SCCP task. If an application attempts to bind to a SAP for which an application was previously bound, the older binding is removed and the new binding is established. 



An application may subsequently disassociate itself from a SAP by generating an UNBIND request.  Again, if the SCCP configuration specified one or more concerned point codes for the associated subsystem number, this results in those nodes being notified that the subsystem is now unavailable.


Note:  If the application requires that concerned point codes be notified of the application subsystem becoming available, the application should call the SCCPStateRqst primitive to generate SCCP Subsystem-Allowed (SSA) messages to all concerned point codes after binding but before attempting any data transfer.

 






2.6.2	 Connectionless Data Transfer





An application using the connectionless service sends data to the far end by invoking the SCCPUDataRqst primitive.  Depending on the size of the data and the class of service employed, the SCCP task will then generate a Unitdata (UDT) or Extended Unitdata (XUDT) message to the far end (Figure 3). There is no response from the far end to these messages.



If the far end SCCP layer cannot process the received data message and returns a Unitdata Service message (UDTS) or Extended Unitdata Service message (XUDTS) to the SCCP task, the application is notified with a SCCPStatusIndication. The application receives incoming UDT and XUDT messages via the SCCPUDataIndication.


 



Figure 3.	 Connectionless Data Transfer



 






2.6.3	 Connection Establishment





The application initiates a SCCP connection by invoking the SCCPConnectRqst primitive. This results in the generation of an SCCP Connect Request Message (CR) to the far exchange (Figure 4).


   



Figure 4.	 Outgoing Connection Establishment




The connection establishment phase ends when the application receives the SCCPConnectConfirm message (far exchange sent Connection Confirm).  If the far end refuses the connection request, the application receives a SCCPReleaseInd indication instead of a connect confirmation (Figure 5).


 



Figure 5.	 Outgoing Connection Refused




Alternatively, the far exchange may initiate the connection by sending the CR message.  This results in the application receiving an SCCPConnectIndication event (Figure 6).


 



Figure 6.	 Incoming Connection Establishment




For an incoming connection, the application invokes the SCCPConnectResp primitive to signal to the far end that the connection is accepted.  If the application chooses to refuse the connection, it calls the SCCPReleaseRqst primitive instead (Figure 7).


 



Figure 7.	 Incoming Connection Refused by Application






2.6.4	 Data Transfer





During the time that the call is connected the application may exchange data with its peer in the far endpoint by invoking the SCCPDataRqst or SCCPEDataRqst (expedited data) primitive and/or receiving SCCPDataInd or SCCPEDataInd  indications from the SCCP layer (Figure 8).


 



Figure 8.	 Connection-oriented Data Transfer






2.6.5	 Connection Reset





The application may request that an active connection be reset by invoking the SCCPResetRqst primitive.  When the far end acknowledges the reset with a reset confirmation message, the application receives a SCCPResetConf event.   Likewise, if the far end initiates the connection reset, the application receives a SCCPResetInd event and is expected to respond by invoking the SCCPResetConf primitive.


 






2.6.6	 Connection Clearing





The application requests clearing of a connection by invoking the SCCPReleaseRqst primitive, which results in a SCCP Released (RLSD) message being generated to the far end.  No confirmation is returned to the application (Figure 9). 


  



Figure 9.	 Application Connection Release




When a connection is released first by the far party, the application receives a SCCPReleaseInd indication. There is no response from the application to this indication (Figure 10).


 



Figure 10.	 Far End Connection Release






2.6.7	 Status Indications





The application may be notified of changes in the status of the SCCP layer, protocol errors, and other abnormal events at any time with a unsolicited SCCPStatusInd indication.  Valid event types for these status messages and their meaning are listed in the SCCPStatusInd reference section.






2.6.8	 Signaling Point and Subsystem Status Procedures





The SCCP API also contains several sets of primitives for maintaining signaling point and subsystem status between the system containing the TX Series device(s) and backup signaling points or concerned signaling points.






2.6.9	 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 the SCCPCoordRqst.  This generates a SCCP Subsystem-Out-Of-Service-Request (SOR) to the backup signaling point (as specified in the SAP configuration).  The application receives a SCCPCoordConf confirmation when the backup signaling point returns a Subsystem-Out-Of-Service-Grant (SOG).  See Figure 11.


 



Figure 11.	 Subsystem Out of Service Request



 




If the backup signaling point fails to return a SOG message and the grant request times out, the SCCP layer returns SCCPCoordConf confirmation back to the application with an indication that the request failed, and 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 SCCPCoordInd event (Figure 12). The application invokes the SCCPCoordResp primitive to accept the request and return the SOG message. 


 



Figure 12.	 Remote Subsystem Out-of-Service Indication






2.6.10	 Subsystem State Changes





The application may notify all concerned point codes of a change in its state by invoking the SCCPStateRqst primitive.  This request generates a Subsystem Available (SSA) or Subsystem Prohibited (SSP) message to all concerned signaling points as specified by the configuration of the application 's SAP.



Likewise, when the SCCP task receives messages from concerned signaling points indicating that their status has changed, the application receives an unsolicited SCCPStateInd indication (subsystem status) or SCCPPcStInd indication (point code status) .


 






2.6.11	 Remote Signaling Point Failures





An application may monitor the status of remote signaling points by specifying a list of concerned point codes in the user SAP configuration corresponding to that application (see Section 2.8, Unsolicited Alarms).



If all links to a concerned point code (CPC) fail, the application receives a SCCPPcStInd indication with the status field set to SP_INACC (signaling point inaccessible). In addition, the application receives a SCCPStateInd indication with the status field set to SS_UOS (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 SCCPStateInd (SS_UOS) indication for each known subsystem at that signaling point (but not the SCCPPcStInd indication, since in this case just the SCCP user part and not the entire signaling point has failed).



Receipt of a SCCPStateInd implies that any active connections with that signaling point/subsystem are dropped;  the application does not receive an individual release indication for each active connection.  Connections must be re-established when the affected signaling point/subsystem returns to service. However, if the SAVE_CONNS configuration parameter has been set (SAVE_CONNS in the SCCP configuration file), the application receives a SCCPPcStInd indication with the status field set to SP_INACC_NODROP (signaling point inaccessible, connections not dropped). In this case, any open connections are not closed. When the link has been restored (SP_ACC received), the connections may still be used. If the link stays down for the length of the Receive Inactive Timer (RXINACT_TIMER in the SCCP configuration file), the connections will then be closed and must be re-established when the link is restored.



When communication with the affected signaling point is restored, the application receives a SCCPPcSTInd indication with 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 SCCPStateInd indication with the status field set to SS_IS (subsystem in-service).  At this point the application may re-establish connections and/or resume connectionless data transfer with the affected SP/subsystem.



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


 



Figure 13.	 Remote Signaling Point Failure/Recovery



 






2.7	 SCCP Configuration





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



The SCCP layer supports the following configuration entities:



General   The general configuration defines the operational parameters of the SCCP layer: resource allocations, timer values, and threshold values.  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 SCCP layer services.  A user SAP is associated with a single subsystem number and switch type (ANSI or ITU-T). The user SAP defines whether the application is replicated on another node for reliability purposes, and lists any concerned point codes (i.e., nodes which must be notified of any change in the status of the application).  User SAPs are initially loaded at system boot time; additional user SAPs may be added later, up to the maximum specified in the general configuration.



Network SAPs   One network SAP is defined for each MTP3 layer interface that the SCCP layer uses.  Typically the SCCP layer has only a single network SAP, although if the same system supports multiple switch types (ANSI and ITU-T), the SCCP layer would have a separate network SAP for each switch type.  


 



Routes   One route is defined for each destination subsystem that the SCCP layer may be used to access.  The route defines the destination point code used to reach that subsystem as well as any backup point code which replicates the subsystem.  Routes are initially loaded at system boot time; additional routes may be added later, up to the maximum specified in the general configuration.



Addresses   Address entries define how the SCCP layer is to translate and/or route between global titles, point codes, and subsystem numbers.   Address translations are initially loaded at system boot time; additional address translations may be added later, up to the maximum specified in the general configuration.






Figure 14 shows the relationship between the various configurable entities. 


 



Figure 14.	 SCCP Configuration Entities






2.8	 Unsolicited Alarms





Any of the tasks on the TX Series device (including any of the SS7 layers) may generate unsolicited alarms at any time to indicate abnormal events or changes in the status of some entity.  For many host operating systems, a standard application is provided (in both source and executable form) to receive alarms and write them to a disk file on the host.  Systems employing other host operating systems, or those which require customized alarm handling, may implement their own alarm handlers. 











 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1999, Natural MicroSystems, Inc.   All rights
reserved.