# TCAP User's Guide

Copyright © 2003-2005 Motivity Telecom Inc.

Version: 1.1

Authors: Vance Shipley (`vances@motivity.ca`).

The `tcap` application is a protocol stack implementation of the Transaction Capabilities Application Part (TCAP) of the Signaling System No. 7 (SS7) specifications ITU-T Q.771-Q.774 and ANSI T1.114-2000. Transaction Capabilities (TC) users include the Intelligent Network Application Protocol (INAP) ITU-T Q.1208 and the Mobile Application Part (MAP) 3GPP 29.002.

### Requirements

This application includes only the TCAP procedures and must be used with a seperate application providing the SCCP service. The `nms` application provides a binding to the embedded SCCP layer on the TX3220/TX4000 boards. An native Erlang SCCP User Adaptation (SUA) for SIGTRAN SCTP is planned.

### Transaction Capabilities

Transaction Capabilities (TC) provides support for interactive applications in a distributed environment through a generic remote procedure call service. TC provides the framework for invoking remote procedures and returning the results of these procedures.

Figure 1-1 shows the structure of TC using SS7 network services. TC is composed of two sublayers; the Component Sublayer (CSL) and the Transaction Sublayer (TSL). The CSL deals with components which are the Application Protocol Data Units (APDU) that convey remote operations and their responses. The CSL optionally may utilize the dialogue portion protocol for conveying information related to application context or user information. The TSL deals with the exchange of messages containing components and optionally, a dialogue portion, between TC-Users.

Figure 1-1: TC in SS7

### Open Systems Interconnection (OSI)

TC is based on the Remote Operations concept defined in Recommendation X.880 (ROS). TC allows communication between TC-Users across an SS7 network. This communication can be modelled with the OSI seven layer stack as shown in Figure-2.1. SS7 does not define an Intermediate Services Part (ISP) so the Presentation, Session and Transport layers are formally missing however some aspects of the these are present in TC. CSL lies entirely within the application layer.

Figure 2-1: TC in OSI

Figure-2.2 shows the structure of the OSI Application Layer. An Application Process (AP) consists of application code within and outside the OSI framework. The part of an application which resides in the OSI framework is called an Application Entity (AE). The AE may contain a number of cooperating components, each with it's own protocol elements. These components are called Application Service Elements (ASE). An ASE is a separately defined (standardized) part of an Application Entity. ASEs provide a service to higher level ASEs not a higher level layer. The distinction being that unlike layer services an ASE service may consider only part of the communication between Application Entities.

Figure 2-2: OSI Application Process

The Component sublayer is in partial alignment with the capabilities of the Remote Operation Service Element (ROSE) X.219 and X.229. The X.229 protocol is contained within the TC component protocol. CSL includes some extensions to ROSE. The dialogue control facilities are in partial alignment with the capabilities of the Association Control Service Element (ACSE) X.217 and X.227. The abstract syntax for the dialogue control APDUs are a subset of the OSI ACSE abstract syntax.

Figure-2.3 shows an Application Process with an Application Entity which includes the Transaction Capabilities ASE and the Mobile Application Part ASE.

Figure 2-3: SS7 Application Process

An Application Entity (AE) is the part of your Application Process (AP) which uses the services of a combined set of ASEs. An AE-Type defines a set of functions used for communications. For example one AE-Type may combine a TC ASE with a MAP ASE while another combines a TC ASE with an INAP ASE. An AE Invocation (AEI) is an instance of an AE and it's ASEs.

An AEI may perform a subset of the communication functions defined by the AE-Type. The actual procedures that may need to be performed for an instance of communication are determined by the Application Context (AC). The Application Context states which functions are needed. Based on this information the AEI is instantiated from the AE-Type which fits these criteria.

Using the `tcap` application you will implement your Application Process (AP) and Application Entity (AE) in Erlang. The set of processes which make up an instance of the Component Sublayer (CSL) form the TC ASE. For each new dialogue an AEI including a TC ASE and a TC-User ASE (e.g. MAP) is created. The AE uses the ASEs together to provide higher level functions to the AP.

Figure 3-1: AE Invocations

For example you may have an AE which uses TCAP and MAP ASEs implemented in a `gen_fsm` callback module named ae_map_v3. An AEI for a location update could be created as:

    	gen_fsm:start_link(ae_map_v3, ['networkLocUpContext-v3', TSL], [])

Where `'networkLocUpContext-v3'` is the application context name and `TSL` is a reference to the transaction sublayer used for this operation. The callback module would start TC and MAP and coordinate them to provide the location update service to the Application Program.

    	-module(ae_map_v3).
    	-export([init/1, handle_event/2]).
    	-behaviour(gen_fsm).
    	-record(state, {ac, tsl, csl, map}).

    	init([AC, TSL]) ->
    	    case tcap:open(TSL, self(), []) of
    	        {ok, CSL} ->
    	            case map:open(CSL, self(), []) of
    	               {ok, MAP} ->
    	                   State = #state{ac = AC, tsl = TSL, csl = CSL, map = MAP},
    	                   {ok, idle, State};
    	               Error ->
    	                   Error
    	            end;
    	         Error ->
    	            Error
    	    end.

In ASN.1 an `OPERATION-PACKAGE` type is used to define an ASE. An `APPLICATION-CONTEXT` type defines an AC. An application protocol is defined by the set of all possible ACs. The above example uses these definitions from the 3GPP/GSM MAP specification:

    	networkLocUpContext-v3 APPLICATION-CONTEXT ::= {
    	    -- Responder is HLR if Initiator is VLR
    	    INITIATOR CONSUMER OF {locationUpdatingPackage-v3 | dataRestorationPackage-v3}
    	    RESPONDER CONSUMER OF {subscriberDataMngtPackage-v3 | tracingPackage-v3}
    	    ID                    {map-ac networkLocUp(1) version3(3)}
    	}

    	locationUpdatingPackage-v3 OPERATION-PACKAGE ::= {
    	    -- Supplier is HLR if Consumer is VLR
    	    CONSUMER INVOKES      {updateLocation}
    	    SUPPLIER INVOKES      {forwardCheckSs-Indication}
    	}

    	updateLocation OPERATION ::= { --Timer m
    	    ARGUMENT              UpdateLocationArg
    	    RESULT                UpdateLocationRes
    	    ERRORS                {systemFailure | dataMissing | unexpectedDataValue | unknownSubscriber | roamingNotAllowed}
    	    CODE                  local:2
    	}

In a complex AE there may be multiple TC-User ASEs. The operation codes (e.g. `local:2` for the `updateLocation` above) of the received components allow the AE to distribute to the appropriate ASE. While the `locationUpdatingPackage-v3` definition above appears informally in the current specifications MAP is still viewed as having a single Application Service Element for historical reasons. The Intelligent Network Application Protocol (INAP) however clearly defines many distinct ASEs. Figure 3-2 shows the configuration of an AEI for INAP using the `scf-to-ssf-status-reporting-v1` AC.

Figure 3-2: Example INAP AEI

### Addressing

When used with SS7 network services the addressesing of the Signaling Connection Control Part (SCCP) is used. The SCCP CalledParty and CallingParty address formats are used in the TCAP address parameters; Destination Address and Originating Address. These parameters identify the destination and originating TC-user.

The SCCP Subsystem Number (SSN) is used by SCCP for message distrubution to seperate instances of the TCAP Transaction Sublayer (TSL).

Figure 4-1: SSN Distribution

### Process Communication

A number of processes interact to provide the TCAP service. Figure 5-1 depicts the message paths between processes used with the TCAP application.

The TCAP protocol layer is split into two sublayers; the Transaction Sublayer and the Component Sublayer.

In the transaction sublayer a transaction coordinator (TCO) process performs marshalling of incoming indications from the SCCP service access point (SAP). It spawns a transaction state machine (TSM) for each new transaction.

In the component sublayer a dialogue handler (DHA) process is started for each transaction. It then spawns a component coordinator process (CCO). For a remotely initiated transaction DHA is started by TCO. For a locally initiated transaction DHA is started by the TC-User. An invocation state machine (ISM) is started for each locally invoked operation involved in the transaction.

Figure 5-1

### Modules

##### `tcap`

This module implements the application programming interface (API) for the application.

##### `tcap_app`

This is the start module for the application. It is an `application` behaviour callback module.

##### `tcap_sup`

This module implements the top level supervisor for the application. It is a `supervisor` behaviour callback module.

##### `tcap_sap_sup`

This module implements a supervisor at the SAP level, one per SAP. It is a `supervisor` behaviour callback module.

##### `tcap_tco_server`

This module implements the transaction coordinator (TCO). It is a `gen_server` behaviour callback module.

##### `tcap_transaction_sup`

This module implements a supervisor at the transaction level, one per transaction. It is a `supervisor` behaviour callback module.

##### `tcap_tsm_fsm`

This module implements the transaction state machine (TSM). It is a `gen_fsm` behaviour callback module.

##### `tcap_dialogue_sup`

This module implements a supervisor at the dialogue level, one per dialogue (transaction). It is a `supervisor` behaviour callback module.

##### `tcap_dha_fsm`

This module implements the dialogue handler (DHA). It is a `gen_fsm` behaviour callback module.

##### `tcap_components_sup`

This module implements a supervisor at the components level, one per component sequence (dialogue/transaction). It is a `supervisor` behaviour callback module.

##### `tcap_cco_server`

This module implements the component coordinator (CCO). It is a `gen_server` behaviour callback module.

##### `tcap_invocation_sup`

This module implements a supervisor at the invocation level, one per component sequence (dialogue/transaction). It is a `supervisor` behaviour callback module.

##### `tcap_ism_fsm`

This module implements the invocation state machine (ISM). It is a `gen_fsm` behaviour callback module.

### Supervision Tree

The processes which make up an instance of the TCAP service layer are all instantiated within a single supervision tree. When the application is started a top level supervisor is created with no children. The user calls `tcap:open/3` to create a new service access point (SAP) which dynamically adds a `tcap_sap_sup` supervisor with one worker TCO.

Figure 5-2 shows the structure of the supervision tree.

For every new transaction ID assigned (Begin indication or request) a `tcap_transaction_sup` supervisor is dynamically added to the `tcap_sap_sup` supervisor with one TSM worker and a `tcap_dialogue_sup` supervisor. In the case of a Unidirectional primitive no transaction is assigned. Instead a `tcap_dialogue_sup` supervisor is dynamically added to the `tcap_sap_sup` supervisor.

When a `tcap_dialogue_sup` supervisor is started it immediately creates a DHA worker and a `tcap_components_sup` supervisor with one CCO worker and a `tcap_invocation_sup` supervisor.

A `tcap_ism_fsm` worker is dynamically added to the `tcap_invocation_sup` supervisor for each locally invoked operation.

Figure 5-2

### Distribution

In order to facilitate building very large systems the processes involved may be distributed across nodes. Figure 6-1 shows some examples of how this distribution may be accomplished.

Figure 6-1

When a SAP is created with `tcap:open/3` the `tcap_tco_server` callback module name is provided to start a TCO which can adapt the specific implementation of SCCP in use to this TCAP service layer. Arguments are also passed to specify instance specific configuration such as SCCP subsystem number.

The `tcap_tco_server` callback module exports start functions used to create SAP, TCO, TSM and DHA processes. This allows the user to configure how the application is distributed.

The DHA always starts the CCO and ISM processes on it's local node.

### Primitives (ITU)

#### TC-User → Component Sublayer

##### Dialogue Handling

`{'TC', 'UNI', request, Parms}`
`{'TC', 'BEGIN', request, Parms}`
`{'TC', 'CONTINUE', request, Parms}`
`{'TC', 'END', request, Parms}`
`{'TC', 'U-ABORT', request, Parms}`

##### Component Handling

`{'TC', 'INVOKE', request, Parms}`
`{'TC', 'RESULT-L', request, Parms}`
`{'TC', 'RESULT-NL', request, Parms}`
`{'TC', 'U-ERROR', request, Parms}`
`{'TC', 'U-CANCEL', request, Parms}`
`{'TC', 'U-REJECT', request, Parms}`

#### Component Sublayer → TC-User

##### Dialogue Handling

`{'TC', 'UNI', indication, Parms}`
`{'TC', 'BEGIN', indication, Parms}`
`{'TC', 'END', indication, Parms}`
`{'TC', 'U-ABORT', indication, Parms}`
`{'TC', 'P-ABORT', indication, Parms}`
`{'TC', 'NOTICE', indication, Parms}`

##### Component Handling

`{'TC', 'INVOKE', indication, Parms}`
`{'TC', 'RESULT-L', indication, Parms}`
`{'TC', 'RESULT-NL', indication, Parms}`
`{'TC', 'U-ERROR', indication, Parms}`
`{'TC', 'L-CANCEL', indication, Parms}`
`{'TC', 'L-REJECT', indication, Parms}`
`{'TC', 'R-REJECT', indication, Parms}`
`{'TC', 'U-REJECT', indication, Parms}`
`{'TC', 'TIMER-RESET', indication, Parms}`

#### Component Sublayer → Transaction Sublayer

`{'TR', 'UNI', request, Parms}`
`{'TR', 'BEGIN', request, Parms}`
`{'TR', 'CONTINUE', request, Parms}`
`{'TR', 'END', request, Parms}`
`{'TR', 'U-ABORT', request, Parms}`

#### Transaction Sublayer → Component Sublayer

`{'TR', 'UNI', indication, Parms}`
`{'TR', 'BEGIN', indication, Parms}`
`{'TR', 'CONTINUE', indication, Parms}`
`{'TR', 'END', indication, Parms}`
`{'TR', 'U-ABORT', indication, Parms}`
`{'TR', 'P-ABORT', indication, Parms}`
`{'TR', 'NOTICE', indication, Parms}`

#### Transaction Sublayer → SCCP

`{'N', 'UNITDATA', request, Parms}`

#### SCCP → Transaction Sublayer

`{'N', 'UNITDATA', indication, Parms}`
`{'N', 'NOTICE', indication, Parms}`