Sie sind auf Seite 1von 918

hp OpenCall SS7 platform

Application Developers Guide


For Release 3.1 on Linux
Second Edition

Manufacturing Part Number: 5971-3502


E0103

Notice
The information contained in this document is subject to change without notice.
Hewlett-Packard makes no warranty of any kind with regard to this material,
including, but not limited to, the implied warranties of merchantability and fitness
for a particular purpose. Hewlett-Packard shall not be liable for any errors contained
herein, or for incidental or consequential damages in connection with the furnishing,
performance or use of this material.
2003 Copyright Hewlett Packard Development Company, L.P.
Reproduction, adaptation or translation without prior written permission is
prohibited, except as allowed under the copyright laws.

Printing History
First Edition

For Release 3.1 on Linux, January 2003

Second Edition

For Release 3.1 on Linux, May 2003

Hewlett-Packard Company
OpenCall Business Unit
38053 GRENOBLE Cedex 9
France

ii

Contents
Preface
1. Introduction to HP OpenCall SS7 APIs
HP OpenCall SS7 Developers Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Development Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loopback Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Categories of API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Permission to Access HP OpenCall SS7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stack and Management APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 Stack APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3/M3UA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP Application Message Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 Management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Guardian. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Alias Point Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Virtual Point Codes (VPCs) and Virtual Users (VUs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Virtual Point Codes (VPC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Virtual Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OAM API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 on Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SIGTRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Names and Path Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

36
36
37
38
38
38
39
40
40
40
41
41
41
41
42
43
44
44
46
46
47
47
47
47
49
49
49

2. General System Guidelines


Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for System Predictability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for System Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Techniques for Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimizing OS Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Test and Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

52
52
52
52
53
54

iii

Contents
Platform and User Application Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using LANs with GDI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C++ Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples of Compile/Link Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

55
56
57
57
57
58

3. General API Guidelines


Accessing the SS7 Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interaction of Multiple APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7 Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating SS7 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling SS7 Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pre-select Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Post-select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Signaling Information via an API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Signaling Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Signaling Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing SS7 Stack Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rescheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPC Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning IPC Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPC Flow Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outbound Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Visibility of a Switchover at Each Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3, ISUP, and TUP APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examining Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4. Using the Level 3 (MTP3/M3UA) API


iv

60
62
63
64
64
65
65
65
66
67
67
68
68
68
69
69
70
71
72
73
73
74
74
74
75
76

Contents
General Description of the Level 3 (MTP3/M3UA) API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
MTP Level 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
MTP Level 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
MTP Level 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
MTP3 User Adaptation (M3UA) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Stream Control Transport Protocol (SCTP) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Features of MTP3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Multiple Application Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Network Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Traffic Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Link Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Route Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Combining Linksets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
How to Use the MTP3 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Creating MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Scheduling MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
MTP3 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Receiving MSUs (Message Signaling Units). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Sending MSUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Closing MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Using the MTP3 API Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Creating MTP3 Stack Connections with SS7_xifcreate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Scheduling MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
SS7_ifselectmask(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
SS7_ifcnxhandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
MTP3 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Receiving MSUs with MTPL3_recv(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Sending MSUs Using MTPL3_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Closing MTP3 Stack Connections with SS7_ifclose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Tuning MTP3 IPC Buffers with SS7_ifctrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
MTP3 API Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Sending MSUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Receiving MSUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
DPC Unavailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
DPC Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
DPC Congestion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Contents
DPC Uncongested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Local MTP3 Unavailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Local MTP3 Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

5. Using the SCCP API


General Description of SCCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Subsystem Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Features of the SCCP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connectionless Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Application Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Addressing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Signaling Point Status Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Segmentation/Reassembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subsystem Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subsystem Status Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replicated Subsystems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Relay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview of How to Use the SCCP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating SCCP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling SCCP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving SCCP Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending SCCP Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing SCCP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the SCCP API Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating SCCP Stack Connections Using SS7_xifcreate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling SCCP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7_ifselectmask(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7_ifcnxhandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vi

106
106
106
108
108
108
108
109
109
109
109
109
110
110
111
111
112
112
112
112
112
113
113
113
113
114
116
116
116
117
119

Contents
Recommendation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local Alias PC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Title Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving SCCP Primitives Using SCCP_recv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending SCCP Primitives Using SCCP_send(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing SCCP Stack Connections Using SS7_ifclose() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling the SCCP Using SS7_ifctrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Addressing and Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Addressing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Global Title Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outgoing Routing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Routing Without GT Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Routing with Local GT Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Incoming Routing Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Routing Without GT Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Routing with Local GT Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Signaling Point Status Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Signaling Point Prohibited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Signaling Point Allowed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Signaling Point Congested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subsystem Status Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local Subsystem Out of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local Subsystem In Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subsystem Status Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replicated Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Available Backup Subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unavailable Backup Subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
No Peer Point Code Configured. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SccpClient.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SccpServer.c. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

120
121
121
126
127
130
131
132
133
133
135
142
144
147
148
149
153
153
154
156
156
158
158
160
160
161
162
164
164
166
167
168
168
169

6. Using the TCAP API


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Chapter Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

vii

Contents
API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the TCAP API Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Description of TCAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component Sublayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Sublayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
No Component Layer Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of TCAP Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialogue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The HP OpenCall SS7 TCAP API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hybrid Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reverse Hybrid Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialogue Portion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Non-disruptive Service Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Direct Access to the Transaction Sublayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7 Stack Switchover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Simultaneous Access by Multiple TCAP Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Take-over of TCAP Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using ITU-T White Book TCAP for ITU-T Blue Book
TCAP Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Called and Calling Party Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Use the TCAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating TCAP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling TCAP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If TC-user, Use Invoke and Dialogue ids. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If TR-user, then... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Component Sublayer, for TC-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the TCAP Component Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Allocate, Fill, Allocate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Storing the Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Create a Dialogue Primitive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
viii

172
173
174
174
174
176
177
177
178
178
178
179
179
180
180
181
182
182
183
183
184
186
188
190
191
192
192
192
192
192
193
193
193
193
193
194

Contents
Sending Components and the Dialogue Primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Releasing Buffers and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving TCAP Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing TCAP Stack Connections for TC-users and TR-users . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating TCAP Stack Connections Using TCX_open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Creating a TC-user Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling TCAP Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_select_mask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_cnx_handler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Scheduling a TCAP Stack Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Component Sublayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoke ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialogue ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invocation and Dialogue Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Storing the Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the TCAP Component Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tcx_component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tc_component_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component Type Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Allocating Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Allocating Components to a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_alloc_component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_alloc_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Allocating One Component and One Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Filling the Buffer with User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Passing a Component to the Component Sublayer
Using TCX_put_component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Component Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Releasing Buffers and Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_free_components () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_flush_components (). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_free_buffer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialogue Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tcx_primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Primitive Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Service Quality Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Primitive Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

194
194
195
195
196
197
200
200
200
201
201
203
203
203
203
206
206
208
208
209
210
212
212
212
213
213
215
216
216
217
217
218
218
219
219
220
222
224
ix

Contents
dialogue_portion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Creating a Dialogue Primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX Primitive Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Components via the Component
Sublayer Using TCX_send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Using TCX_send () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Components from the Component
Sublayer Using TCX_recv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Receiving Components Using TCX_recv () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extracting Components Using TCX_get_component(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Transaction Sublayer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending User Data via the Transaction
Sublayer Using TLX_send() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving User Data from the Transaction
Sublayer Using TLX-recv(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing TCAP Stack Connections Using TCX_close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example: Closing a TC-user Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Component Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving Component Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Invoke IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Wait-for-reject Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialogue Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example of a TC Dialogue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Dialogue ID Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Simultaneous Dialogues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
API Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tuning TCAP IPC Buffers Using TCX_control() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_control(): Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_control(): Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using TCAP over GDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GDI Access (Application Interface Layer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GDI Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
x

226
227
229
230
230
233
234
236
237
237
237
238
239
240
240
241
241
241
241
241
242
242
243
243
244
245
246
246
248
250
251
252
252

Contents
TCAP Addressing Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Stack Switchovers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Dual Signaling LANs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TcapClient.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TcapServer.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building IN Message Sets Over the HP OpenCall SS7 TCAP API . . . . . . . . . . . . . . . . . . . . . . . .

253
253
254
257
260
260
261
262

7. Using the TCAP Application Message Dispatcher


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling and Disabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Dispatching Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customer-Supplied Dispatching Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shared Library Technical Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Header File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
When the Library Functions are Called . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAProuter_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAProuter_application_activate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAProuter_application_deactivate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAProuter_incoming_message(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAProuter_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Some Approaches to Dispatching Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Partitioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Round Robin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uneven Distribution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching on INAP Service Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching Algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calls to Functions in the Customer-Supplied Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tracing and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TTL (Telecom Tracing and Logging) Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Principles of Stack Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trace Function Prototype. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Activating the Trace Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
When to Use the Trace Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Guidelines for Developing the Customer-Supplied Shared Library . . . . . . . . . . . . . . . . . . . . . . . .
Designing for Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

264
264
265
265
269
269
269
270
270
270
270
270
271
271
272
273
274
274
276
278
281
281
281
281
282
282
283
283

xi

Contents
Designing for Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for Shared Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for High Availability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing in Accordance with Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Header File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tcx_application_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tcx_primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP Application Message Dispatcher Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

284
285
285
286
287
287
287
288
288
288
289
290
290
290

8. PIC/AG - Introduction
Some Basic Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Purposes of the HP OpenCall PIC Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ensuring HA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communicating with Another Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Possible Plug-in Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Components of the PIC Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is Supplied in the PIC Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What the User Must Develop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Role of Each Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Benefits of the PIC Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of PIC Framework Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Plug-in Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Programming Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xii

292
294
294
295
295
296
296
297
297
297
298
299
299
300
301
302
302
303
304
305

Contents
Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Execution API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading and Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA Model (on HP OpenCall SS7) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registry API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Purpose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PCA (Plug-in Communication API) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communication Setup and Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TimerLib API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PIC Pool of Timers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in Pools of Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the User Plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting/Stopping the User Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Command Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Product Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hardware Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other Equipment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Usability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PCA Message Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
High Availability Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How the PIC Manages Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How the Plug-in Should Manage Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

306
307
307
307
307
310
310
310
310
311
316
316
316
317
318
318
319
319
320
320
322
324
325
325
326
326
326
327
327
327
328
328
329
329
329
330

9. PIC/AG - Using the PCA API

xiii

Contents
High Availability (HA) and the PCA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Enabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PCA Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Opening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server IPC Parameterization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Connection Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Opening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client IPC Parameterization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Connection Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customizing Plug-in Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Deletion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Session Dispatching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Session Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Client Session Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Reject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Parameterization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types and Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Meaning of errorCode and errorText Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of PCA Payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PCA_Message Internal Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Buffer Allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiv

332
332
333
334
334
339
339
340
341
341
341
343
343
345
345
345
346
347
347
348
348
351
352
354
355
355
356
356
357
359
359
361
362
362
364
366

Contents
Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

366
366
367
368
368
368
368
369

10. PIC/AG - Using the PIC APIs


Structure of PIC APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Plugin Object Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Plug-in Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Plug-in Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in Scheduling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in Body Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Asynchronous Tasks (TimerLib) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in HA Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State Completion Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example of an HA Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Plug-in Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

372
375
375
376
376
377
377
380
381
381
381
382
383

11. Using the OA&M API


SS7 OA&M Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OA&M APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OA&M Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining Notification about OA&M Entity State Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Issuing OA&M Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating MTP and SCCP OA&M Connections using SS7_xifcreate . . . . . . . . . . . . . . . . . . . . . . .
Scheduling MTP and SCCP OA&M Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7_ifselectmask(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7_ifcnxhandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending MTP2 OA&M Requests using MTP2X_oamcmd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving MTP2 OA&M Notifications using MTP2X_oamrecv() . . . . . . . . . . . . . . . . . . . . . . . .

386
388
388
388
389
390
391
391
391
391
392
394
395

xv

Contents
MTP3 Entities and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3 Entity Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description of MTP3 Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rules for Creating and Manipulating MTP3 Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing MTP3 Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Possible States of MTP3 Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending MTP3 OA&M Requests using MTPL3_oamcmd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response to Expect from an MTPL3 OA&M Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Collecting MTP3 OA&M Statistics Using MTPL3_oamstat() . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Report Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response to Expect When You Collect MTP3 OA&M Statistics . . . . . . . . . . . . . . . . . . . . . . . .
Receiving MTP3 OA&M Command and Statistic Notifications
Using MTPL3_oamrecv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response to Expect When You Use the MTPL3_oamrecv() Command . . . . . . . . . . . . . . . . . . .
SCCP OA&M Entities and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Entity Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description of SCCP Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rules for Creating and Manipulating SCCP Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing SCCP Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Possible States of SCCP Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending SCCP OA&M Requests Using SCCP_oamcmd(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response to Expect When You Send an SCCP OA&M Request . . . . . . . . . . . . . . . . . . . . . . . .
Collecting SCCP OA&M Statistics Using SCCP_oamstat(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Report Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response to Expect When You Collect SCCP OA&M Statistics . . . . . . . . . . . . . . . . . . . . . . . .
Receiving SCCP OA&M Command and Statistic Notifications
Using SCCP_oamrecv(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Response to Expect When You Use the SCCP_oamrecv() Command . . . . . . . . . . . . . . . . . . . .
Closing MTP and SCCP OA&M Connections Using SS7_close(). . . . . . . . . . . . . . . . . . . . . . . . .
Using TCAP OA&M Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Opening a TCAP OA&M Connection Using TCX_open(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling TCAP OA&M Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_select_mask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCX_cnx_handler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Requesting TCAP Statistics Using TCX_control() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Collecting TCAP Statistics Using TCX_recv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xvi

396
396
397
398
399
400
402
402
403
403
405
406
406
408
408
409
410
410
412
413
413
414
414
416
417
417
419
420
421
422
422
422
422
424
426

Contents
Closing a TCAP OA&M Connection Using TCX_close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

12. Using the ISUP API


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Software Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Version-Specific Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Orientation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Lifespan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the ISUP API Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7 Stack Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State-machine Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bypass Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP CIC-based distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Instance Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Application Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dynamic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
API Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IsupMgr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IsupProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IsupSMProbe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IsupBPProbe. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outline of the Basic Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Application Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing the IsupMgr object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading the Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and Opening a Probe Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a Probe Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Opening a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Primary and Secondary Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling Probe Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pre-select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

430
431
432
432
433
434
434
434
434
435
436
437
437
437
438
439
442
444
445
445
446
448
448
448
448
449
449
450
450
451
451
452
452
459
459

xvii

Contents
Select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Post-select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Activity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Criteria for Choosing to Implement the Activity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to use the Activity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Redefining the Activity Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages via Probe Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing and Destroying a Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
oamReceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
oamStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Dynamic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
reload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dump() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using State-machine Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Bypass Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

460
461
462
462
463
463
466
467
467
467
469
469
472
474
477
477
478
480
480
481
482

13. Exchanging ISUP Messages


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 ISUP Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Acknowledgment Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Attempt To Use Non-Supported Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State Machine Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bypass Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP Related Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 ISUP Supported Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Encoder/Decoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xviii

484
485
486
486
487
488
505
505
510
511
511
513
514

Contents
Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading a Set of Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying a Set of Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Messages Supported. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Complete List of Messages and Message Sets Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Partial Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specific Accessors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessor Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Data Part of an IsupMsg Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Queued Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Casting Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Queued Indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Automated Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring for Automated Call Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Parameters List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

515
516
516
517
518
518
518
519
519
519
520
522
524
526
527
527
528
529
531
532
533

14. Managing HP OpenCall SS7 ISUP


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Race Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Memory Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Object Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling IPC Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying IPC Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPC Flow Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outbound Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Circuit States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provided Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

536
537
538
539
539
539
539
540
541
542
543
544
545
547
547

xix

Contents
How HP OpenCall SS7 ISUP Tracks Circuit State Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Developing a Circuit Update Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Propagating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Synchronizing States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Activating the Standby Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recovering States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

548
549
549
550
551
552

15. Introduction to ISUP Procedures


Supported Finite State Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interaction Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound and Outbound Circuits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3 Interaction Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local MPT-3 Status Indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote DPC Status Indications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DPC States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic Primitive Processing (State-machine Probe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic Primitive Processing (Bypass Probe). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic ISUP Message Handling (State-machine Probe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic ISUP Message Handling (Bypass Probe). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic ISUP Circuit Group Message Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ANSI Based HP OpenCall SS7 ISUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITU-T Based HP OpenCall SS7 ISUP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CFN and UCIC Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CFN Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CFN Receipt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UCIC Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UCIC Receipt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Defined ISUP Message Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Segmentation - ITU-T 93, 97, ETSI-V2 Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Segmentation for Outgoing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reassembly of Incoming Messages - Normal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reassembly of Incoming Messages -Failure Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reassembly of Incoming Messages -Failure Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Unrecognized Messages ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xx

556
558
558
559
559
563
563
566
568
569
570
571
572
573
574
574
574
574
574
575
576
576
577
577
578
580

Contents
16. ISUP Call Control - Procedures Common to ANSI and ITU-T
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conventions Used in Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Setup Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETUP Request Locally Refused by HP OpenCall SS7 ISUP . . . . . . . . . . . . . . . . . . . . . . . . . .
SETUP Request - Dual Seizure Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETUP Request - Dual Seizure Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETUP Request - Failure to Receive ACM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Incoming Call Setup with Immediate Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Successful Call Setup for Incoming Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Call Release - Outgoing Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Call Release - Incoming Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release Collision - Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release Collision - Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Incoming Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 ISUP Initiated Reset - Successful Procedure . . . . . . . . . . . . . . . . . . . . . . . . .
Reset from Network - Successful Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reset from Application - Successful Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Reset from Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Failure Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Double Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Information Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Solicited Information Exchange - Success. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Solicited Information Exchange - Failure Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Solicited Information Exchange - Failure Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unsolicited Information Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Information Exchange - Failure Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - T6 Expiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Forward Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Forward Transfer Message - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pass Along Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pass Along Request - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pass Along Request - Error Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check Request with IAM or CCR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

583
584
585
585
586
587
588
589
589
591
591
591
592
593
594
596
596
597
598
599
599
600
601
603
603
604
605
606
606
608
608
610
610
611
611
612
613

xxi

Contents
Continuity Check on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
Continuity Check on the Previous Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Facility Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

17. ISUP Circuit Maintenance - Procedures Specific to ANSI


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking/Unblocking from a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking from a Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking from User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking from a Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking from User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking from a Network on Reception of an IAM . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking during Setup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Blocking/Unblocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking from Network Immediate Release - Normal Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking from Network - No Release Normal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Immediate Release or Not)
- From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Unblocking from NetworkNormal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Unblocking (Immediate or Not)
- From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Without Immediate Release)
- During Call Setup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query from the Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query from User (Application) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Validation from Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Validation from User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

620
621
621
621
622
622
623
623
625
625
627
628
629
630
630
632
632
633
642
642
643

18. ISUP Call Control - Procedures Specific to ANSI


Call Setup Without ACM Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
Abnormal Call Release - Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
xxii

Contents
Abnormal Call Release - Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 ISUP Initiated Reset
- Failure to Receive RLC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Reset from User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reservation from Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reservation from Network - T_CRA Expiry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - Outgoing Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - Incoming Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exit Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exit Message - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check Request with IAM or CCR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check Request with CRM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

651
653
653
655
655
656
656
657
658
658
659
660
660
661
661
672
672

19. ISUP Call Control - Procedures Specific to ITU-T


Successful Call Setup for Outgoing Side. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Setup Including ACM Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the CON Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the SAM Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abnormal Call Release - Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abnormal Call Release - Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 ISUP Initiated Reset
- Failure to Receive RLC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Reset from USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - Incoming Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - Outgoing Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - T2 Expiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check Request with IAM or CCR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Facility Request, Facility Accepted, Facility Reject Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . .

678
678
679
680
682
682
683
685
685
687
687
688
688
689
691
692
692
704
xxiii

Contents
Facility Exchange - Success. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
Facility Exchange - Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

20. ISUP Circuit Maintenance - Procedures Specific to ITU-T


Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking/Unblocking from a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking from a Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking from User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking from Network - Normal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking from User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking from a Network on Reception of an IAM . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking during Setup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Blocking/Unblocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Maintenance Oriented)
- From Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Hardware Oriented) from Network Normal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Maintenance Oriented)
- From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Hardware Oriented)
- From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Unblocking (Maintenance Oriented)
- From Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Unblocking (Hardware Oriented)
- From Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Unblocking (Maintenance Oriented)
- From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Unblocking (Hardware Oriented)
- From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Maintenance Oriented)
- During Call Setup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group Blocking (Hardware Oriented)
- During Call Setup Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query from the Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query from Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A. ISUP Library Values


xxiv

708
709
709
710
711
711
712
713
714
714
716
717
718
719
720
721
722
723
724
725
725
726

Contents
ANSI-based HP OpenCall SS7 ISUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
ITU-T - based HP OpenCall SS7 ISUP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734

B. TUP Addendum
How to Use This Addendum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functionality Identical to HP OpenCall SS7 ISUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functionality Not Identical to HP OpenCall SS7 ISUP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flavors Supported by HP OpenCall SS7 TUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Software Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Software Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for System Predictability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Techniques for Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Test and Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Orientation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the TUP API Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7 Stack Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
API Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outline of the Basic Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing the IsupMgr Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and Opening a Probe Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling Probe Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Activity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages via Probe Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing and Destroying a Probe Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Dynamic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 TUP Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 TUP Message Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

742
742
742
743
745
745
745
745
747
747
747
747
747
747
748
748
748
748
748
748
748
748
749
749
749
749
749
750
750
751
751
751
751
766

xxv

Contents
Automated Call Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACR State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing HP OpenCall SS7 TUP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Race Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Memory Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Object Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling IPC Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Congestion and Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Circuit States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Developing a Circuit Update Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction to TUP Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported Finite State Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interaction Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3 Interaction Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote DPC Status Indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic Primitive Processing (State Machine Probe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic Primitive Processing (Bypass Probe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic TUP Message Handling (State Machine Probe). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic TUP Message Handling (Bypass Probe) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic TUP Circuit Group Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Setup Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking/Unblocking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Blocking/Unblocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Miscellaneous Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of MPM Message (CTUP Only). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of MAL Message (CTUP Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of FOT Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using State-machine Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Bypass Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xxvi

782
784
784
785
785
785
785
785
785
786
788
791
792
792
793
793
794
794
794
794
794
795
798
798
834
856
856
860
878
878
879
879
880
880
880
881

Contents
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883

xxvii

Contents

xxviii

Preface
This guide contains guidelines for developing applications for HP OpenCall SS7
platforms.
This guide accompanies HP OpenCall SS7 3.1 on Linux.

About This Guide


Purpose
The purpose of this guide is to describe how to develop applications to run on top of
the HP OpenCall SS7 software. Refer to this guide for:

General guidelines for developing applications and using the APIs supplied
with the HP OpenCall SS7 software.

Using the following APIs:


Level 3 (MTP3/M3UA) API
SCCP API
TCAP API
OA&M API
ISUP API
TUP API

Using the TCAP Application Message Dispatcher.

Using the PIC/AG to develop user plug-in (shared library)s.

Guidelines for developing applications and using the API supplied with the
HP OpenCall SS7 ISUPand HP Opencall SS7 TUP software.

Opening, closing, and using connections to the ISUP/TUP library.

Creating, handling, and exchanging standard ANSI and ITU-T messages.

ISUP/TUP FSMs, interaction with the MTP layer, and segmentation


mechanisms.

ISUP/TUP call setup and call teardown procedures and circuit maintenance
processes.

xxix

Contents and Structure


The contents and structure of this guide are as follows:
Chapter

Contents

Chapter 1, Introduction to
HP OpenCall SS7 APIs.

Introduces the APIs provided by HP OpenCall SS7. A general


description of the HP OpenCall SS7 stack versions is also included.

Chapter 2, General System


Guidelines.

Gives guidelines to help you develop applications to run on top of the


HP OpenCall SS7 platform. Following these guidelines will ensure
that the applications will inter-operate correctly and efficiently with
the individual sub-systems of the HP OpenCall SS7 platform.

Chapter 3, General API


Guidelines.

Introduces the general concepts and mechanisms that must be used


when developing applications. These guidelines are applicable to each
HP OpenCall SS7 API, and must be read in association with the
following API chapters.

Chapter 4, Using the Level 3


(MTP3/M3UA) API.

Describes the Level 3 API and the functions that applications can use
to exchange signaling information with the SS7 stack. The guidelines
in this chapter will ensure that the application correctly uses the Level
3 API. The same Level 3 API is used whether the Level 3 protocol is
MTP3 (SS7) or M3UA (SIGTRAN).

Chapter 5, Using the SCCP


API.

Describes the SCCP API and the functions that the application can use
to exchange signalling information with the SS7 stack. The guidelines
in this chapter will ensure that the application correctly communicates
with the SCCP API.

Chapter 6, Using the TCAP


API.

Describes the TCAP API and the functions that the application can use
to establish and maintain TCAP dialogues with a remote TCAP user.

Chapter 7, Using the TCAP


Application Message
Dispatcher.

Describes the TCAP Application Message Dispatcher.

Chapter 8, PIC/AG Introduction.

Introduces the Application Guardian. The Application Guardian


(Plug-In Container/Application Guardian) is used to run a user plug-in
(shared library).

Chapter 9, PIC/AG - Using


the PCA API.

Describes how to use the PCA API to develop a user plug-in (shared
library) to run with the Application Guardian.

xxx

Chapter

Contents

Chapter 10, PIC/AG - Using


the PIC APIs.

Describes how to use the PIC APIs to develop a user plug-in (shared
library) to run with the Application Guardian.

Chapter 11, Using the OA&M


API.

Describes the Operation, Administration & Maintenance (OA&M)


functions that applications can use to manage the MTP2, MTP3, SCCP
and TCAP processes in the SS7 Stack.

Chapter 12, Using the ISUP


API.

Describes how to open, close and use an SS7 stack connection via the
HP OpenCall SS7 ISUP API.

Chapter 13, Exchanging ISUP


Messages.

Describes how to create, manipulate and exchange standard ANSI and


ITU-T messages. It also describes the primitives provided for
IsupSMProbe and IsupBPProbe objects.

Chapter 14, Managing


HP OpenCall SS7 ISUP.

Provides management guidelines for use in developing the application.

Chapter 15, Introduction to


ISUP Procedures.

Presents information about ISUP procedures, including FSMs,


interaction with the MTP layer and segmentation mechanisms.

Chapter 16, ISUP Call


Control - Procedures Common
to ANSI and ITU-T.

Describes how HP OpenCall SS7 ISUP behaves when controlling call


setup and call teardown procedures that are common to ANSI and
ITU-T.

Chapter 18, ISUP Call


Control - Procedures Specific
to ANSI.

Describes how HP OpenCall SS7 ISUP behaves when controlling call


setup and call teardown procedures that are specific to ANSI.

Chapter 19, ISUP Call


Control - Procedures Specific
to ITU-T.

Describes how HP OpenCall SS7 ISUP behaves when controlling call


setup and call teardown procedures that are specific to ITU-T.

Chapter 17, ISUP Circuit


Maintenance - Procedures
Specific to ANSI.

Describes circuit maintenance processes that are specific to ANSI.

Chapter 20, ISUP Circuit


Maintenance - Procedures
Specific to ITU-T.

Describes circuit maintenance processes that are specific to ITU-T.

Appendix A, ISUP Library


Values.

Lists the AdditionalInfo values that can be returned by the ISUP


Library in certain ANSI and ITU-T -based scenarios.

xxxi

Chapter
Appendix B, TUP
Addendum.

xxxii

Contents
Describes HP Opencall SS7 TUP. It describes the differences between
HP Opencall SS7 TUP and HP OpenCall SS7 ISUP.

Associated Documentation
The following guides are on the HP OpenCall SS7 3.1 on Linux CD-ROM:
Table 1

Guides on the HP OpenCall SS7 3.1 on Linux CD-ROM

HP OpenCall SS7 Application


Developers Guide

Describes the HP OpenCall SS7 APIs. In particular, it describes how to


design and develop user applications to run on ISUP or TUP.

HP OpenCall SS7
Conformance and Compliance
Statements

Outlines platform conformance and compliance to ANSI and ITU-T


protocols.

HP OpenCall SS7 Glossary

Defines terms used in the documentation set.

HP OpenCall SS7 Operations


Guide

Describes how to install and configure the platform and SS7 network,
how to start, stop and monitor the platform, and how to use the platform
management tools. The guide also includes SS7 hardware (TSC and
TSU) installation and maintenance procedures, as well as platform
expansion procedures.
It contains information on the SS7 Monitor, configuration files, and the
SNMP traps generated by the platform.

HP OpenCall SS7 TSU and


TSC Starter Sheet

Describes the safety regulations and conformance to international


standards for TSUs and TSCs.

HP OpenCall SS7
Troubleshooting Guide

Describes how to troubleshoot an HP OpenCall SS7 platform.

HP OpenCall SS7 Welcome


Guide

Describes the main features of the platform.

xxxiii

The following guides are available but are not on the HP OpenCall SS7 3.1 on
Linux CD-ROM:
Table 2

Other Documents
Title

Contents

HP OpenCall SS7 Release Notes

This document contains release-specific information. In


particular, it gives details of the HP Opencall SS7
packages, the servers supported, the Linux distributions
supported and the associated patches (if any).

HP OpenCall SS7 Software Installation


QuickStart Guide

This guide contains a procedure for installing


HP OpenCall SS7 version 3.1 on Linux from scratch.
The procedure in this guide applies if the platform has
never had HP OpenCall SS7 installed.

xxxiv

We Welcome Your Comments


Your feedback on these manuals is very important to us.
You can contact us by e-mail at the following address:
opencall_docs@hp.com
You can also mail your comments to:
Hewlett-Packard Company,
OpenCall Business Unit,
38053 GRENOBLE Cedex 9,
France

xxxv

xxxvi

Introduction to HP OpenCall SS7 APIs


This chapter describes the APIs provided by HP OpenCall SS7. A general
description of the HP OpenCall SS7 stack versions is also included.

Chapter 1

35

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 Developers Environment

HP OpenCall SS7 Developers Environment


The HP OpenCall SS7 software is available as a runtime environment or as a
developers environment. The HP OpenCall SS7 developers environment allows
the development and testing of applications on top of the SS7 stack. These
applications can be deployed on the HP OpenCall SS7 environment software while
remaining independent of the platform configuration.

Development Software
In the development environment, the SS7 Stack and management libraries are
accessible via the HP OpenCall SS7 Application Programming Interfaces (APIs),
thus allowing the development of C/C++ applications. The APIs provide a
transparent interface, shielding applications from the underlying network
procedures and the platform architecture.
Figure 1-1

36

Development Platform

Chapter 1

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 Developers Environment

Loopback Testing
Once an application has been developed, it can be tested on the development
platform using loopback testing. The advantage of loopback testing is that SS7
network access connections are not necessary.
However, for applications that use the lower MTP levels, a limited number of
network access links must be used.

NOTE

Chapter 1

ISUP loopback can only be used when CIC-based distribution is disabled.

37

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 APIs

HP OpenCall SS7 APIs


Application Programming Interfaces (APIs) provide applications with access to the
HP OpenCall SS7 platform libraries and the SS7 network. These APIs support the
management and protocol services required to achieve SS7 connectivity.

Categories of API
The HP OpenCall SS7 APIs can be divided into three main categories:

SS7 APIs
Each protocol level is accessible via its dedicated API, such as the
MTP3/M3UA, SCCP, ISUP, TUP and TCAP APIs. In the case of TCAP, the
stacks default round robin algorithm (for load sharing when there are several
users connected on the same SSN) can be replaced by a user algorithm using the
TCAP Application Message Dispatcher.

SS7 Management APIs


Operations, Administration and Maintenance (OA&M) services of MTP, SCCP
and TCAP are accessible via their respective OA&M APIs.

Application Guardian API


By using the Application Guardian, user applications can benefit from the High
Availability facilities of HP OpenCall SS7.

An application can use a single API (either an SS7 Stack or an SS7 Management
API) or simultaneously use multiple APIs.

Permission to Access HP OpenCall SS7


Only members of the group ocadmin. can access the HP OpenCall SS7 APIs. To
allow access, you do not need to change a users account, you just add the user to the
list of members of the group ocadmin.
For a developer, who does not need to operate the platform, membership can be
defined as secondary. For an operator, who needs to operate the platform, the users
primary group must be ocadmin.
See also the group(4) and password(4) man pages.

38

Chapter 1

Introduction to HP OpenCall SS7 APIs


Stack and Management APIs

Stack and Management APIs


Figure 1-2

HP OpenCall SS7 Stack and Management APIs

User application

TCAP
API

ISUP
& TUP
APIs

SCCP
API
MTP3/
M3UA
API

AG API

OA & M
APIs

TCAP
SCCP

Chapter 1

MTP level 3

M3UA

MTP level 2

SCTP

MTP level 1

IP

39

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 Stack APIs

HP OpenCall SS7 Stack APIs


The Stack APIs provide access to the SS7 protocol stack. These APIs allow an
application to request services from the appropriate protocol layer (MTP Level 3,
SCCP or TCAP).

MTP3/M3UA API
MTP3/M3UA Level 3 services are accessible through this API. Using the provided
functions, an application written in C can exchange MSUs with a peer application.
Applications can utilize the functions provided by this API to request services such
as:

Message Handling,

Network Management,

Link Management (MTP3 only).

See Chapter 4, Using the Level 3 (MTP3/M3UA) API,, for a full description.

SCCP API
The SCCP library enhances the transport services of MTP Level 3, and combined
with the MTP library forms the Network Service Part (NSP) which is equivalent to
Layer 3 of the Open Systems Interconnection (OSI) reference model.
Applications written in C can utilize the functions provided by this API to request
SCCP services such as:

Message Handling

Global Title Translation

Routing

Addressing

Signaling Point Management and Subsystem Management

Segmentation/Reassembly

See Chapter 5, Using the SCCP API,, for a full description.

40

Chapter 1

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 Stack APIs

TCAP API
The TCAP API allows an application written in C to access either the component or
the transaction sublayer. This enables non-standard TCAP components to use the
HP OpenCall SS7 transaction sublayer.
This API provides functions to request the services of the TCAP library such as:

Exchange of TCAP components,

Multiple User Access,

Component Management,

Transaction/Dialog Management.

For a description, see Chapter 6, Using the TCAP API,.

TCAP Application Message Dispatcher


If several users are connected with the same SSN on the same stack, you can supply
your own algorithm to replace the round-robin algorithm used by default. You do
this using the TCAP Application Message Dispatcher.
The TCAP Application Message Dispatcher has its own API. This API is described
in Chapter 7, Using the TCAP Application Message Dispatcher,.

ISUP API
HP OpenCall SS7 ISUP enables ISUP call control applications to run over SS7
networks. It relies on MTP Level 3 functionality to transfer its messages through the
SS7 network to the destination point code.
For a description, see Chapter 12, Using the ISUP API, and subsequent chapters.

TUP API
HP Opencall SS7 TUP enables TUP call control applications to run over SS7
networks. It relies on MTP Level 3 functionality to transfer its messages through the
SS7 network to the destination point code.
For a description, see Appendix B, TUP Addendum.

Chapter 1

41

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 Management APIs

HP OpenCall SS7 Management APIs


The management API is the OA&M (Operations, Administration and Maintenance
API.
This API provides functions for the development and deployment of SS7 Stack and
platform management applications. The OA&M APIs are provided for each SS7
Stack level (MTP, SCCP and TCAP). They allow applications to access and use the
SS7 management functions such as node configuration, control and surveillance.
See Chapter 11, Using the OA&M API, for a full description.

42

Chapter 1

Introduction to HP OpenCall SS7 APIs


Application Guardian

Application Guardian
By using the Application Guardian feature, user applications can benefit from the
High Availability facilities of the HP OpenCall SS7 product. The application
concerned becomes a user plug-in (shared library). For an introduction to the
Application Guardian, see the HP OpenCall SS7 Welcome Guide.
The Application Guardian has its own APIs.
These APIs are described in Chapter 9, PIC/AG - Using the PCA API, and
Chapter 10, PIC/AG - Using the PIC APIs.

Chapter 1

43

Introduction to HP OpenCall SS7 APIs


Alias Point Code

Alias Point Code


The Alias Point Code feature allows the HP OpenCall SS7 product itself to be part
of one or more aliases as defined by the Bellcore standard GR-82-CORE Issue 1,
June 1994.
Such an alias is known as a local alias.

Local Alias
You can define one or more aliases, whose constituents are HP OpenCall SS7 nodes.
An HP OpenCall SS7 node can belong to at most 4 aliases. Therefore, an
HP OpenCall SS7 node can have a maximum of 4 aliases.
Each node of the network can then access the HP OpenCall SS7 node either by
using its LPC or by using one of its aliases. The goal is to allow a remote node to
reach an HP OpenCall SS7 node other than by using its LPC.
The local alias is visible only up to the MTP3 level. The applications above MTP3
are not aware of its existence and just see the LPC.
Figure 1-3 on page 45 shows an example of how an incoming message for an alias is
handled.
The diagram shows a pair of HP OpenCall SS7 nodes (A and B) with an alias c
defined for them.
Step

1. The remote node D sends a message with DPC = c.

Step

2. The STP E selects one of the constituents of the alias (let us say A).

Step

3. E routes the message to A.

Step

4. The message enters the MTP3 level of A with DPC = c.

Step

5. The message exits the MTP3 level of A with DPC = a.

Step

6. The application on A receives the message DPC = a.


The existence of the alias has no effect on outgoing messages from A. Such
messages are sent with OPC = a. The alias c does not appear in such messages.

44

Chapter 1

Introduction to HP OpenCall SS7 APIs


Alias Point Code
Figure 1-3

Chapter 1

Example of an Incoming Message for a Local Alias

45

Introduction to HP OpenCall SS7 APIs


Virtual Point Codes (VPCs) and Virtual Users (VUs)

Virtual Point Codes (VPCs) and Virtual Users (VUs)


NOTE

The VPC and VU features are available only if the signaling network is SS7. These
features are not available if the signaling network is IP (using SIGTRAN).

These features provide the following functionalities:

On a single node, an SS7 stack can have multiple non-physical point codes
(called VPCs).

A user application, called a Virtual User (VU), can receive and send traffic
through VPCs, and manage the VPC behavior.

A user application can bridge a non-SS7 network with an SS7 network.

Two objects are associated with these features:

a VPC object that must be configured as a new point code.

a VU object that must be configured as a new local user application.

Virtual Point Codes (VPC)


A VPC is a non-physical point code. The configuration of a VPC consists in the
dynamic configuration of a point code. A maximum of 16 VPCs is allowed on each
HP OpenCall SS7 stack.
Like an Alias Point Code, a VPC is associated with the LPC.
In the case of an incoming MSU containing an Alias Point Code, the alias is
replaced by the LPC (in the MTP routing label) before being given to the user. In the
case of an incoming MSU containing a VPC, the DPC of the MTP Routing Label
remains set to the VPC.
An outgoing MSU with the OPC set to a VPC is sent to the network without any
substitution of the OPC.
Management and monitoring are not available on VPCs.

46

Chapter 1

Introduction to HP OpenCall SS7 APIs


Virtual Point Codes (VPCs) and Virtual Users (VUs)

Virtual Users
A VU is a user that can be connected to a VPC. The configuration of a VU consists
of the dynamic configuration of a SubSystem Number (SSN) associated with a
VPC. Thus a VU is identified by two values: VPC and SSN.
A maximum of 16 VUs is allowed on each HP OpenCall SS7 stack. Because a VU
application behaves like a local user application, all the SCCP functionalities,
including monitoring, are available for a VU.

OAM API
The OAM API allows configuration of Virtual Point Codes (VPCs) through the
command MTPL3_oamcmd() using the virtual_pc MtpOamObject object.
The OAM API allows configuration and monitoring of VUs using the following
commands SCCP_oamcmd(), SCCP_oamrecv() and SCCP_oamstat() through
the SO_VIRTUAL_USER SccpOamObject object.

SCCP API
The SCCP API allows connection to a Virtual User (VU) using the
ss7_xifcreate() function and the cnx_info variable which has a specific
add_info field.

Tutorials
The OAM and SCCP specific VPC tutorials show how to use the data structures and
the functions of the OAM and SCCP APIs.
To use the OAM tutorials, execute the cc_oam makefile. This creates an executable
file OAM. Execute this file without arguments to see how to use the program.
To use the SCCP VPC tutorials, execute the cc_sccp_vpc makefile. This creates
two executables: SccpClientVpc and SccpServerVpc. Execute these programs
without any arguments to see the available options. Do not forget to set the mode
option (primary or secondary) to connect the tutorial to a Virtual User.
The files cc_sccp_vpc, SccpClientVpc.c and SccpServerVpc.c are located
in the /opt/OC/tutorials directory.

Chapter 1

47

Introduction to HP OpenCall SS7 APIs


Virtual Point Codes (VPCs) and Virtual Users (VUs)

CAUTION

48

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

Chapter 1

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 on Linux

HP OpenCall SS7 on Linux


SIGTRAN
References to SIGTRAN, M3UA, and SCTP in this guide are not relevant to
HP OpenCall SS7 3.1 on Linux.

File Names and Path Names


Some system path names and file names are different depending on your Linux
distribution. Table 1-1 on page 49 gives some examples of files/path names.

Table 1-1

File/Path Names
Purpose

File Path/Name

Network configuration and host names.

You should use the SystemConfigurator tool.

SNMP Agent

/etc/snmp/snmpd.conf

Log Files

/var/log/messages
/var/log/daemon.log
/var/log/rpmpkgs
/var/adm/nettl.LOGxx

NOTE

The contents of this table is indicative and non-exhaustive.


To find the exact file/path name, you must refer to the documentation accompanying
your Linux distribution. The Linux document that you should consult depends on
the context (for example, LAN Configuration, system log files).

Chapter 1

49

Introduction to HP OpenCall SS7 APIs


HP OpenCall SS7 on Linux

50

Chapter 1

General System Guidelines


This chapter gives guidelines to help you develop applications to run on top of the
HP OpenCall SS7 platform. Following these guidelines will ensure that applications
will inter-operate correctly and efficiently with the individual sub-systems of the
HP OpenCall SS7 platform.

Chapter 2

51

General System Guidelines


Development Guidelines

Development Guidelines
Application must integrate with the HP OpenCall SS7 components, so that they run
seamlessly as one homogenous unit. Therefore, all test and validation procedures
should be applied to the platform as a whole, and not solely to the application.

Designing for System Predictability


The platform as a whole should behave in a predictable fashion under all possible
operating conditions. It must respond to requests from the SS7 network within
pre-defined and predictable time limits that are within the range of 0.5 second to 1
second. Operating within this range allows the operating system to behave
predictability even though it is not a real time operating system.

Designing for System Performance


Telecommunications application performance can be defined as the optimal use of
computing resources to produce the call control and signalling transactions for
which the application has been designed. The best way of measuring performance
is against the quantification of resource usage (CPU usage, main memory, I/O,
network) required to process each unit of work; for example, transactions.

Techniques for Performance Optimization


The hints below are provided to assist you in obtaining optimum performance for
HP OpenCall SS7 platform applications. The list will help you identify key areas for
optimization.

52

Minimize the number of process switches that you have implied in the
performance path.

Pay particular attention to the Inter-Process Communication (IPC) part of


application as this is always the most critical in terms of system performance.

Allocate all dynamic objects into a free pool at startup and use them from there,
as required.

Chapter 2

General System Guidelines


Optimizing OS Performance

Optimizing OS Performance
The main causes of poor performance leading to unpredictable system response are
due to access contention of memory and CPU resources.
You can use the real time features of the OS scheduler to manage system
performance, but you should use this with caution as many processes in the
HP OpenCall SS7 platform need easy access to processing resources (see Platform
and User Application Scheduling on page 55).
A better way to ensure predictable and optimized performance is to avoid resource
access contention by following these guidelines:

Chapter 2

Always keep total CPU usage below 85% and keep spare CPU resources to
minimize any CPU resource access contention.

Do not try to increase the priority of an application process with nice, rtprio
or rtsched.

Make sure you have sufficient physical memory for all HP OpenCall SS7 and
application processes. For a Front End running HP OpenCall SS7 processes
only, with no application processes, 128 MB is the recommended minimum for
the system. The recommended minimum per stack is also 128 MB. The system
must have at least twice as much swap memory (also known as virtual memory)
as physical memory.

Design and implement proactive overload handling mechanisms which will


avoid the platform limiting the throughput due to it delaying the scheduling
processes (that is, 100% CPU usage).

Minimize the number of processes involved in the performance path.

Beware of the effect of buffered I/Os. See the product Release Notes.

Avoid swapping end monitor swap usage.

Avoid dynamic memory allocation in application processes. Even when all the
memory leaks are eliminated, the fragmentation effect can cause the process
memory consumption to increase with time.

When using a FE/BE topology it is preferable to use high speed LANs such as
FDDI or 100BASE-T.

53

General System Guidelines


System Test and Validation

System Test and Validation


Follow the procedures below during the testing and validation of applications, to
ensure that they will operate correctly with the HP OpenCall SS7 platform.
Load the HP OpenCall SS7 platform with the operational and logging configuration
that you are going to use. At the maximum traffic load, check the following:

The CPU usage must always be less than 85%.


For a multiprocessor platform, the CPU usage of the processor running
HP OpenCall SS7 must be less than 85%.

The HP OpenCall SS7 platform must respond to STLM messages in less than
40 ms. This can be measured using an SS7 tester such as an HP 37900 analyzer.

Ensure that the HP OpenCall SS7 platform mechanism is functioning correctly:


No erroneous switchovers due to heartbeat losses should be detected,
The FTC must have sufficient CPU to function correctly,
See the section below on Platform and User Application Scheduling.

54

No swapping should occur on the system.

Chapter 2

General System Guidelines


Platform and User Application Scheduling

Platform and User Application Scheduling


On the HP OpenCall SS7 system it is important that:

NOTE

the application scheduling be done in only one main loop

all HA processes have a fair share of the CPU time available

It is especially important that HA processes (such as the SS7 stack) have enough
processing power and have CPU access in real-time when they need it. This is
because a system of heartbeats is used to detect failure; a process that is not
scheduled cannot send heartbeats, and so will be detected as dead by the system.

These constraints are also normally true for application processes, which must
process SS7 messages in a timely fashion. The HP OpenCall SS7 Stack API also
generates heartbeats to monitor connections. The stack API clears the connection
from its end if the heartbeats are not received. If the connection closes it is up to the
application to close the connection on the application end. To keep the connection
open, regularly call the API.
The HP OpenCall SS7 processes are configured with a priority level which ensures
the correct operation of the platform. These preset default values should not be
changed.
Although the SS7_Stack process is given a high priority (20), it is self-regulating.
SS7_Stack monitors its connection with an application in order not to overflow it,
and if it sees that an application cannot process its buffer it will relinquish some of
its share of CPU.

Chapter 2

55

General System Guidelines


Using LANs with GDI

Using LANs with GDI


The Generic Data Interface (GDI) allows TCAP to run over TCP. This allows TCAP
applications to communicate using an IP network.
GDI supports one or two signaling LANs. Each LAN interface used by a system
must be configured on a different subnet.
LANs used by GDI must be dedicated to GDI. The IP addresses of GDI signaling
LAN cards should not be configured in the /etc/hosts configuration file because
GDI LANs are identified in HP OpenCall SS7 by their IP addresses (the IP
addresses are configured in the SS7 Stack Monitor). Declaring these addresses in
/etc/hosts or any other name resolution service (such as DNS) will cause the
system to use these addresses for non-GDI traffic.

56

Chapter 2

General System Guidelines


Compiling and Linking

Compiling and Linking


HP OpenCall SS7 APIs are available as shared libraries.

C Language
Compiling and Linking in a Single Command (C)
To compile and link a C program in a single command line, you use:
gcc -D_GNU_SOURCE -fexceptions -pthread -Wall -I/opt/OC/include -o foo foo.c
-L/opt/OC/lib -lSS7utilXXX

where XXX = WBB, AAA, WAA, or ABB.


Compiling Only (C)
To compile a C source-code, you use:
gcc -D_GNU_SOURCE -fexceptions -pthread -Wall -I/opt/OC/include -c foo.c

Linking Only (C)


To link a C program, you use:
gcc -fexceptions -pthread foo.o -o foo -L/opt/OC/lib -lSS7utilXXX

where XXX = WBB, AAA, WAA, or ABB.

C++ Language
Compiling and Linking in a Single Command (C++)
To compile and link a C++ program in the same command line, you use:
g++ -fexceptions -pthread -Wall -I/opt/OC/include -o foo foo.c -L/opt/OC/lib
-lSS7utilXXX

where XXX = WBB, AAA, WAA, or ABB.

Chapter 2

57

General System Guidelines


Compiling and Linking
Compiling Only (C++)
To compile a C++ source-code, you use:
g++ -F_GNU_SOURCE -fexceptions -pthread -Wall -I/opt/OC/include -c foo.c

Linking Only (C++)


To link a C++ program, you use:
g++ -D_GNU_SOURCE -fexceptions -pthread -Wall foo.o -o foo
-L/opt/OC/lib -lSS7utilXXX

-I/opt/OC/include

where XXX = WBB, AAA, WAA, or ABB.

Examples of Compile/Link Commands


There are examples of compile/link commands (appropriate for each
HP OpenCall SS7 API) in the sections listed below.
These examples show a compile and link in a single command. If you want to
compile and link separately, you must adjust these examples using the principles
shown in the sections: Compiling Only (C), Compiling Only (C++), Linking
Only (C), Linking Only (C++).
Level 3 API

Using the MTP3 API Shared Library on page 84.

SCCP API

Using the SCCP API Shared Library on page 113.

TCAP API

Using the TCAP API Shared Library on page 173.

ISUP API

Using the ISUP API Shared Library on page 435 and ISUP Makefiles on
page 482.

TUP API

Using the TUP API Shared Library on page 747.

58

Chapter 2

General API Guidelines


This chapter introduces the general concepts and mechanisms that must be used
when developing applications. These guidelines are applicable to each
HP OpenCall SS7 API, and must be read in association with the following API
chapters.

Chapter 3

59

General API Guidelines


Accessing the SS7 Stack

Accessing the SS7 Stack


The aim of an API is to provide applications with SS7 network access while
shielding the architecture of the platform. This abstract view of the platform allows
an application to use the SS7 and management functions without being dependent
on the platform configuration.
An application can access the HP OpenCall SS7 stack locally (if it runs on the FE
server) or remotely (if it runs on the BE server). In both 1-host and 2-host
development platforms, applications and APIs co-exist on the same computer as the
SS7 stack.
Figure 3-1

Local SS7 Stack Access - Architecture

In distributed platforms the user applications run on a back-end (BE) computer and
the SS7 platform runs on the front-end (FE) computer. Applications on the BEs
access the SS7 network via the HP OpenCall SS7 stack(s) located at the FE(s).

60

Chapter 3

General API Guidelines


Accessing the SS7 Stack
Figure 3-2

Chapter 3

Remote HP OpenCall SS7 Stack Access: Distributed Platform

61

General API Guidelines


Accessing the SS7 Stack
Remote SS7 access enables all computers to be sized to the needs of the
applications. It also eases application maintenance, since bringing down one BE for
an application upgrade does not affect network service for the remaining
applications. Applications that run on development platforms also run without code
modification on distributed platforms.

Interaction of Multiple APIs


An application can interface with a single API or use multiple APIs. Any API
combination is possible, but the guidelines on scheduling must be observed. See
Scheduling SS7 Connections on page 65.

62

Chapter 3

General API Guidelines


Designing for Threads

Designing for Threads


The HP OpenCall SS7 APIs (except the TimerLib) are Posix.1c Thread-Restricted
level B. This means that the interface is not thread-safe, but that it can be used by
any single dedicated thread of a multi-threaded application. Every other API that
is Thread-Restricted Level B must be called from the application thread where
HP OpenCall SS7 APIs are called. HP OpenCall SS7 APIs are not cancel-safe or
async-cancel safe. See the OS user manuals for more information about Posix.1c
threads.
The HP OpenCall SS7 APIs are not Async-Signal-Safe (that is, no
HP OpenCall SS7 functions can be called from a Signal Handler execution context).
The HP OpenCall SS7 APIs are neither Cancel-Safe nor Async-Cancel-Safe (that is,
if the thread that uses an HP OpenCall SS7 function is cancelled by another thread,
the HP OpenCall SS7 context is not left in a consistent state).

Chapter 3

63

General API Guidelines


SS7 Connections

SS7 Connections
Whether the application is remote or local to the HP OpenCall SS7 Stack, it
communicates with the SS7 stack via connections. These connections represent
service access points.

Creating SS7 Stack Connections


Before you can exchange data with the SS7 network, the application must request a
connection to be created between the application and an HP OpenCall SS7 stack.
This connection should be tested by the application. In case of a receive failure, the
application must close the connection to release all associated resources. After the
connection is closed, the application can reconnect.

NOTE

Unclosed connections can consume a significant amount of API resources. It is


important for the application to close failed connections.

className

In an HA configuration, a connection automatically connects the application to the


active SS7 stack known using the generic stack name, className. In the case of
stack failure, traffic is redirected from the failed stack to the standby stack.

Connection
Identifier

When an HP OpenCall SS7 API has created a connection between the application
and an SS7 stack, a connection identifier is returned. This identifier must be used by
the application for all subsequent operations regarding this connection.

64

Chapter 3

General API Guidelines


Scheduling SS7 Connections

Scheduling SS7 Connections


Communication is achieved by the asynchronous services offered by an API. When
the application requests an API to exchange signaling information via a connection,
control is returned to the application until the API returns a response to the request.
Application scheduling must only be done in one application main loop, with only
one select call in the loop. Each select call loop should take a maximum of 500
milliseconds to process.

Scheduling Phases
These asynchronous services of the API are based on the HP OpenCall SS7
scheduling mechanism. This mechanism is based on select(), a system call
which allows I/O multiplexing. It contains three phases:

Pre-select

select()

Post-select

These phases must be taken as a block. Keep them together when writing the
application.

Pre-select Phase
This first phase is used to set up necessary values according to API requirements
before the select() call, using SS7_ifselectmask() for MTP, SCCP and
OA&M API calls, and TCX_select_mask() for TCAP API calls.
Sockets

The HP OpenCall SS7 APIs depend on inter-process communication (IPC) to


communicate with the SS7 stack processes.
HP OpenCall SS7 uses the Berkeley socket mechanism to exchange signaling
information between the application and the HP OpenCall SS7 stack.
The API uses file descriptors to access these sockets.

Masks

Chapter 3

Because file descriptors can also be used by the application, you must provide the
API with three file descriptor masks known as the read, write and exception bit
masks. Reset all the masks before they are used by the application.

65

General API Guidelines


Scheduling SS7 Connections
These bit masks can be set to include the file descriptors used by the application.
Using a preselect function, the SS7 API sets the read, write and exception masks to
include the file descriptors managed by the API.
The resulting masks are passed to select().
Timeout Value

select() also uses a shared timeout value. This value is the maximum length of
time that a process is allowed to block during a select() if there is no I/0 activity.

In the pre-select phase the application must determine a timeout value and submit it
to the preselect function. The API assesses its own requirements and may decrease
this value to a minimal value such as 500 ms. Because of this make sure to initialize
the select() timeout just before the call.
Function

The pre-select function is mandatory and only modifies the timeout value and bits
set by the API in the file descriptor masks, leaving those file descriptors managed by
the application untouched.

select()
This second phase is the basis of the scheduling mechanism.
select() examines the file descriptors specified in the read, write and exception
bit masks. When select() is successful, it modifies and returns these bit masks.
The respective masks indicate if there is information waiting to be sent (written) or
received (read).

See the select() man page for details.

66

Chapter 3

General API Guidelines


Scheduling SS7 Connections

Post-select
This third phase analyzes the results of select(), and triggers the necessary
processing of the file descriptor bit masks. The API also processes the pending
requests to receive and send information via the active connections (file
descriptors).
During this phase the application can process the bits used by the file descriptors.
Function

The post-select function manages any information waiting to be exchanged and the
internal HA mechanisms. It notifies the application about all the active connections.

Scheduling Loop
For HP OpenCall SS7 to maintain the multiple IPC connections to the
HP OpenCall SS7 stack(s), the application must be structured around the three
scheduling phases.
You must do this by using an endless select() loop:
while(1){
// pre-select
// select()
// post-select
}

You must always include these three phases, even if you do not want to receive
information from a connection. Certain internal API mechanisms require I/O
processing without interaction with the application.
Scheduling Multiple When you are using multiple APIs in the application, you must only have one
APIs
scheduling loop:
while(1){
// pre-select for each API you use
// select()
// post-select for each API you use
}

You must set up the pre-select phase for each API involved. Only a single
select() can appear in the application. When select() has successfully
returned, you must complete the post-scheduling phase for each API involved.

Chapter 3

67

General API Guidelines


Exchanging Signaling Information via an API

Exchanging Signaling Information via an API


Through its service access points, HP OpenCall SS7 processes the requests received
from an API to exchange signaling information with a peer application. The
application is expected to send and receive signaling information via opened and
scheduled stack connections using the respective functions provided by the SS7
stack APIs.

Receiving Signaling Information


Only when the three scheduling phases are completed can the application request an
API to receive signaling information on its behalf. This is necessary because the
active stack connections and internal timers must be serviced.
The receive functions provided by HP OpenCall SS7 are non-blocking, and must be
repeatedly called until there is no more information to be received for the particular
connection.
A receive function returns a primitive, its associated signaling data or message and
the number of messages waiting to be received. For example, if the application
wants to receive the information from MTP3, you must ensure that the application
calls the receive function provided by the MTP3 API.

Sending Signaling Information


Once scheduling is completed, the application can request the API to send signaling
information on its behalf. Each of the HP OpenCall SS7 send functions are
non-blocking.
All messages and primitives are sent with respect to a connection.

68

Chapter 3

General API Guidelines


Closing SS7 Stack Connections

Closing SS7 Stack Connections


Close a connection only when you are certain that it will no longer be used.
Repeated creation and destruction of connections place a high overhead on the API
mechanism. Closing a connection does not stop the application, it only closes a
specific service access point between the application and the SS7 stack. The close
functions supported by the MTP3, SCCP and TCAP APIs also close all entities that
were used by the connection.

Rescheduling
After a connection has been closed, you must reschedule the API and its
connections. This ensures that all the previous calls for the connection are executed.
After this, any further message exchange and OA&M function calls for that
connection are rejected.

Chapter 3

69

General API Guidelines


IPC Buffers

IPC Buffers
IPC buffers are used by the HP OpenCall SS7 APIs to communicate with the
HP OpenCall SS7 Stack.
All the messages that you send or receive from a connection are stored in these
internal buffers. You can decide whether messages are buffered before being sent, or
if they are automatically flushed to the stack each time the application calls a
send() function.
By default, HP OpenCall SS7 is set to non-buffering mode, flushing the internal
buffers each time a send() is called.
Figure 3-3

IPC Buffers

NOTE

When an IPC send buffer is full, it is automatically flushed.

70

Chapter 3

General API Guidelines


IPC Buffers

Tuning IPC Buffers


Changing the size of the IPC buffers can optimize the performance of a stack
connection because it concatenates the messages contained in the buffer and so
reduces the number of IPC calls between processes.
You must consider the requirements of the application because increasing
throughput will also increase latency.
Buffering Modes

The HP OpenCall SS7 APIs support two modes of buffering:

Non-buffering mode
In this default mode, the send buffer is automatically flushed each time the API
is requested to send messages on behalf of the application

Buffering mode
This buffering mode allows the application to manually flush the send buffer.
Flushing of the buffer can be dependent on whether the send buffer is full or the
transit time of the oldest message in the buffer has exceeded the maximum
transit time.

Transit Time

The application can set the maximum time for which messages can be stored in the
API buffer before they are sent. This is known as transit time. Each SS7 stack API
allows the application to set the transit time for connections with low and high
traffic.

Buffer Sizes

Internal buffer size is defined by the variable FT_BSize in the file global.conf.
The default value is 64 Kbytes. This value cannot be changed while the stack is
running.
IPC buffers can be increased from the default value of 8 Kb. The application can
only increase their size to the maximum of 64 Kbytes. These buffers can be sized
dynamically by the application by using either SS7_ifctrl() for the MTP, SCCP
and OA&M APIs or TCX_control() for the TCAP API. The Internal Buffer size
must not be reduced to less than the half of the configured IPC buffer size.
For details about the specific IPC functions, see the following API chapters.

Chapter 3

71

General API Guidelines


IPC Flow Control

IPC Flow Control


Using back-pressure, HP OpenCall SS7 provides both inbound and outbound flow
control. Inbound flow control is necessary when the application cannot receive all
the pending indications in the inbound queue. Outbound flow control becomes
necessary when the requests are blocked at the API.
Figure 3-4

72

Back-pressure

Chapter 3

General API Guidelines


IPC Flow Control

Inbound Path
The application receives single indications from an HP OpenCall SS7 API, even if
multiple indications have been generated after the occurrence of a protocol event. A
protocol event is a primitive received from the application or from the stack, or
simply a timeout.
Indications waiting to be received by the application are maintained by the
HP OpenCall SS7 APIs in an inbound queue.
Waiting Indications

As described in Receiving Signaling Information on page 68, the number of


messages waiting to be received are returned to the application. The application
must receive all these waiting indications.

TCP Network
Back-pressure

If the application does not receive all the pending indications, HP OpenCall SS7
will force back pressure on the LAN and as a consequence on the stack. When a
certain period of time elapses, the SS7 stack will delete all the new messages that
were not received by the application.

Outbound Path
When a protocol event occurs, HP OpenCall SS7 may generate one or more SS7
messages destined for the network. These messages are placed in the outbound
queue. Once all HP OpenCall SS7 processing is completed, the queued messages
are sent to the network.
Remaining Messages If HP OpenCall SS7 has successfully sent all the queued messages, the outbound
queue is empty. Otherwise it contains messages that it could not send.
Application
Back-pressure

Chapter 3

The number of remaining messages is used by HP OpenCall SS7 to accept or reject


the service primitives issued by the application. The application is notified by the
API of this situation.

73

General API Guidelines


Visibility of a Switchover at Each Level

Visibility of a Switchover at Each Level


This section describes the visibility of a switchover to an application at each stack
level.
Note that the platform can be configured either in Parallel Engine mode
(Active/Active) or in compatible mode (Active/Hot-Standby) and this may have an
effect on the behavior during a switchover.

TCAP API
Failure of one of the active SS7 stacks is transparent to the application since the
remaining active stacks handle the new incoming and outgoing messages.
This behavior is independent of whether the platform is in Parallel Engine mode
(Active/Active) or compatible mode (Active/Hot-Standby). It is also independent of
whether the level 3 is MTP3 or M3UA.
If one of the active SS7 Stacks handling the traffic fails, all the TCAP transactions
currently being handled by this stack are aborted, and the TCAP users are notified
through a TC_P_ABORT primitive for each transaction lost. The TCAP user must
reset its local timers and state-machines.

SCCP API
If the application calls the API during a switchover it receives an API_BUSY
message.
The application should continue to process normally (by calling the post-select
handler function).
This behavior is independent of whether the platform is in Parallel Engine mode
(Active/Active) or compatible mode (Active/Hot-Standby). It is also independent of
whether the level 3 is MTP3 or M3UA.

MTP3, ISUP, and TUP APIs


On Top of an MTP3 Level 3
If the application calls the API during a switchover it receives an API_BUSY
message.

74

Chapter 3

General API Guidelines


Visibility of a Switchover at Each Level
The application should continue to process normally (by calling the post-select
handler function).
This behavior is independent of whether the platform is in Parallel Engine mode
(Active/Active) or compatible mode (Active/Hot-Standby).
For ISUP and TUP, if one of the active SS7 Stacks handling the traffic fails, all the
call setups being handled by this stack are aborted.
On Top of an M3UA Level 3
Failure of one of the active SS7 stacks is transparent to the user since the remaining
active stacks handle the new incoming and outgoing messages.
This behavior is independent of whether the platform is in Parallel Engine mode
(Active/Active) or compatible mode (Active/Hot-Standby).

Chapter 3

75

General API Guidelines


Examining Error Codes

Examining Error Codes


All the functions provided by the HP OpenCall SS7 APIs return a value. The
application must check this returned value.
In the following chapters, the return values for the supported HP OpenCall SS7
functions are described in detail.

76

Chapter 3

Using the Level 3 (MTP3/M3UA) API


This chapter describes the Level 3 (MTP3/M3UA) API.

Chapter 4

77

Using the Level 3 (MTP3/M3UA) API


General Description of the Level 3 (MTP3/M3UA) API

General Description of the Level 3 (MTP3/M3UA) API


This API provides the functions that the application can use to exchange signaling
information with the SS7 stack.
The guidelines given in this chapter will ensure that the application correctly uses
the services of the Level 3 (MTP3/M3UA) API.
The same API is used for both MTP3 and M3UA. Consequently, the API behavior is
the same whether the level 3 layer is MTP3 or M3UA.
In this guide, this Level 3 API is referred to as the MTP3 API.
As the basis of SS7, MTP provides its applications (such as SCCP, TUP and ISUP)
with reliable transfer of messages between signaling points, and error correction and
detection. MTP provides all the functions of layers one, two and three in the OSI
model. These functions can be categorized according to MTP levels.

MTP Level 1
This level supports the physical transfer of signaling information over the SS7
network.

MTP Level 2
Level 2 provides the functions and procedures for the error detection and correction
of signaling information between two signaling points. This level is maintained at
the signaling link level.

MTP Level 3
This level provides signaling functions to SS7 Level 4. These functions include
signaling message handling and signaling network management.

MTP3 User Adaptation (M3UA) Layer


HP OpenCall SS7 uses the services of M3UA on top of SCTP to exchange signaling
messages over IP networks (a SIGTRAN solution). The connection to the IP
network is provided by LAN cards accommodated in the host server(s) of the
platform. No special signaling hardware is required.

78

Chapter 4

Using the Level 3 (MTP3/M3UA) API


General Description of the Level 3 (MTP3/M3UA) API
HP OpenCall SS7 uses M3UA to transfer MTP3 signaling information between the
upper layers of the protocol stack (SCCP, ISUP, and TUP) and remote network
entities via SCTP services. Since M3UA and MTP3 provide identical interfaces
(Service Access Points) to the upper stack layers, it is transparent to these upper
layers whether M3UA or MTP3 is being used.

Stream Control Transport Protocol (SCTP) Layer


SCTP interacts directly with the Internet Protocol (IP) to connect entities in an IP
network, in the same way as TCP. SCTP also provides the following facilities:

Chapter 4

Multi-homing which provides the high availability of IP connectivity. An SCTP


end-point supports multiple IP addresses, allowing an alternative address to be
used if the main one becomes unavailable. This improves the tolerance of an
SCTP connection to network faults.

Multi-streaming which allows an SCTP connection that contains several


independent parallel streams. A failure in one stream does not affect message
delivery in the other streams.

Order-of-arrival option for the delivery of individual user messages within the
streams.

Acknowledged, error-free, non-duplicated transfers of user data.

Data fragmentation to conform with MTU size.

Optional bundling of multiple user messages into a single SCTP packet.

Cookie mechanism during initialization to protect against security attacks.

79

Using the Level 3 (MTP3/M3UA) API


General Description of the Level 3 (MTP3/M3UA) API
Figure 4-1

MTP Levels and Functions

User application

TCAP
API

ISUP
& TUP
APIs

SCCP
API
MTP3/
M3UA
API

AG API

OA & M
APIs

TCAP
SCCP
MTP level 3

M3UA

Signaling Network Functions


Signaling Message Handling

SCTP

Signaling Network
Management

IP

MTP level 2
MTP level 1

80

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Features of MTP3

Features of MTP3
HP OpenCall SS7 MTP3 provides the standard MTP protocol with the following
functionality.

Message Handling
The processing of MTP3 transfer requests and indications is handled as described in
ITU-T Q.703 and ANSI T1.111.1. The functions that support this Message
Signaling Unit (MSU) processing include:

MSU discrimination functions

MSU distribution functions

MSU routing functions

Multiple Application Connections


MTP3 can accept multiple connections on the same user part (ISUP, SCCP or
others). You can therefore build software redundancy into the system. One
connection is active and handles the traffic, the other connection(s) are secondary
and do not handle traffic. You can only have one primary connection per connection
identifier, whereas you may have several secondary connections. You can set it so
that the standby connections take over the primary connection. See the cnx_info
parameter of the call Creating MTP3 Stack Connections with SS7_xifcreate() on
page 85 for more information.

Network Management
The HP OpenCall SS7 signaling network management provides procedures and
functions required to maintain signaling services, and to restore normal signaling
conditions in the event of disruption in the signaling network, either in signaling
links or at signaling points.
These management functions include:

Chapter 4

Route management

Loadsharing using the SLS value of an MSU

81

Using the Level 3 (MTP3/M3UA) API


Features of MTP3

Traffic Management
In the case of congestion, HP OpenCall SS7 MTP3 uses signaling traffic
management functions to divert traffic from signaling links or routes, or to reduce
the amount of traffic on signaling links.
Traffic management functions include:

Link availability and unavailability

Route availability and unavailability

signaling point availability

Link Management
Locally connected signaling links are controlled by the signaling link management
functions. These functions provide the possibility to establish and maintain a certain
predetermined capability of a linkset. Thus, in the event of signaling link failures,
the signaling link management function controls the actions aimed at restoring the
capability of the linkset.
Link management functions include:

Link activation and deactivation

Link restoration

Route Management
The signaling route management functions ensure a reliable exchange of
information about the availability of signaling routes.

Combining Linksets
The HP OpenCall SS7 software can use combined linksets to share the traffic load if
failures occur (according to ANSI T1-111-4 1998). A combined linkset is a set of
linksets constituting routes of the same priority leading to a given destination. When
there are one or more alternative signaling links available in the combined linkset to
which the unavailable link belongs, the signaling traffic is transferred within the
combined linkset.

82

Chapter 4

Using the Level 3 (MTP3/M3UA) API


How to Use the MTP3 API

How to Use the MTP3 API


Several steps are required when using the HP OpenCall SS7 MTP3 layer: open,
schedule, receive, send, and close. This is briefly described below and then the
relevant sections for each action are referenced.

Creating MTP3 Stack Connections


First you must create an MTP3 stack connection using the SS7_xifcreate() call.
For new applications, and to be able to use functionality such as segmentation and
reassembly, use SS7_xifcreate() and all other calls that include the _x in
their name.
See Creating MTP3 Stack Connections with SS7_xifcreate() on page 85.

Scheduling MTP3 Stack Connections


Secondly, you must schedule all the connections using the HP OpenCall SS7
scheduling mechanism and the following function calls:

SS7_ifselectmask()

select()

SS7_ifcnxhandler()

Scheduling MTP3 Stack Connections on page 87.

MTP3 Primitives
Once you have opened and scheduled the MTP3 connection, you must use
primitives and their respective parameters to communicate.
See MTP3 Primitives on page 90 for a list and explanation of all MTP3
primitives.

Chapter 4

83

Using the Level 3 (MTP3/M3UA) API


How to Use the MTP3 API

Receiving MSUs (Message Signaling Units)


The scheduling mechanism returns the number of stack connections (num_cnxId)
for which there are MSUs (message signaling units) waiting to be received. An array
containing the active connection identifiers is also returned. These messages are
stored by the MTP3 API in the receive buffer, and must be received by the
application using MTPL3_recv().
See Receiving MSUs with MTPL3_recv() on page 92.

Sending MSUs
MTPL3_send() sends MSUs to a remote destination.

See Sending MSUs Using MTPL3_send on page 94.

Closing MTP3 Stack Connections


Only close an MTP3 stack connection when you are certain that the connection will
not be used. Repeated opening and closing of a stack connection places a high
overhead on the MTP3 API mechanism.
See Closing MTP3 Stack Connections with SS7_ifclose() on page 96.

Using the MTP3 API Shared Library


The MTP3 API is available as a shared library.
The following is an example of a compile/link line:
gcc -fexceptions -pthread -D_GNU_SOURCE -Wall -I/opt/OC/include -L/opt/OC/lib
-o MtpClient MtpClient.c -lSS7utilXXX

where XXX = WBB, AAA, WAA, or ABB.

84

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Creating MTP3 Stack Connections with SS7_xifcreate()

Creating MTP3 Stack Connections with SS7_xifcreate()


The MTP3 API creates stack connections on behalf of the application. Via these
stack connections, the application can request the services of MTP3 provided by
HP OpenCall SS7. If successful, SS7_xifcreate() returns a connection
identifier (cnxId), which must be used in all subsequent API calls concerning the
connection.

NOTE

The correct function to call is SS7_xifcreate(). If the application uses


SS7_ifcreate(), you should replace it with SS7_xifcreate().

To enable the multiple connection functionality, you will also have to set parameters
in the sys.<className>.api configuration file as follows:
Table 4-1

Multiple Connection Configuration

If you...

...then set the


parameter...

...to...

do not want this functionality

autoSwitch

NO

want the secondary connection to become active if the primary fails


want the primary connection to be closed when the secondary
connection becomes active

YES
closeOnEnable

want the primary connection to become standby when the secondary


connection becomes active
want to close the existing primary connection when a new primary
connection is created
want to make the existing primary connection secondary when a new
primary connection is created

NOTE

Chapter 4

YES
NO

closeOnCreate

YES
NO

When a connection becomes secondary, MTPL3_recv() returns -1 with ss7errno


set to EAPIDISABLE even if the connection is closed afterwards.

85

Using the Level 3 (MTP3/M3UA) API


Creating MTP3 Stack Connections with SS7_xifcreate()
For details about syntax, parameters, and return values, see the
SS7_xifcreate() man page.
Example 4-1

Creating an MTP3 Stack Connection

#include <failures.h>
#include <ss7_if.h>
int return_val;
int cnxId;
ss7_service_parms sceParms;
sceParms.SI = tup_user; // e.g., TUP, but can be any user
return_val = SS7_xifcreate (SS7_Stack1, ss7_mtp, &sceparms, &cnxId);
if (return_val ==-1){
/* enter error routines */
}

86

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Scheduling MTP3 Stack Connections

Scheduling MTP3 Stack Connections


As described in Scheduling SS7 Connections on page 65 of Chapter 3, you must
schedule all the connections using the HP OpenCall SS7 scheduling mechanism.
Scheduling the MTP3 stack connections is achieved by:

SS7_ifselectmask()

select()

SS7_ifcnxhandler()

SS7_ifselectmask()
This pre-select function is used for all MTP3 stack connections. It takes the file
descriptor masks created by the application, and sets these masks to include the file
descriptors used by the API to manage the MTP3 stack connections. The application
must call this function before calling select().
For details about syntax, parameters, and return values, see the
SS7_ifselectmask() man page.

select()
The select() function is used for all HP OpenCall SS7 scheduling. It modifies
the read, write and exception masks created by SS7_ifselectmask() if the file
descriptors change.

Chapter 4

87

Using the Level 3 (MTP3/M3UA) API


Scheduling MTP3 Stack Connections

SS7_ifcnxhandler()
The application must call this post-select function. SS7_ifcnxhandler()
requests the API to process the masks returned by select() and manage the
internal mechanisms. An array of stack connection identifiers is used to identify the
stack connections that have messages waiting to be received by the application.
Activity on the connection is flagged when one of the following events occurs.

A message is received by the SS7 stack.

A closed connection is found (a send or receive call returns an error). The


application should call the close function to deallocate API resources.

A connection goes from busy state (API_BUSY) to normal state. The


application can resume processing (send and receive calls no longer return an
error).

For details about syntax, parameters, and return values, see the
SS7_ifcnxhandler() man page.
Example 4-2

Scheduling MTP3 Stack Connections

int
int
int
int
fd_set
fd_set
fd_set
struct timeval

nfound;
/* select result */
num_cnx;
numFd;
cnx_active[MAX_FD];
readMask;
/* mask for select */
writeMask;
/* mask for select */
exceptionMask /*mask for select*/
tmout, * time = &tmout;

ss7_service_parms sceparms;
sceparms . SI = SI_VALUE;

/* service parameters */

/* Zero select bit masks before entering loop */


FD_ZERO(&readMask);
FD_ZERO(&writeMask);
FD_ZERO(&exceptionMask);
/* compute the mask for select operation on service
* descriptor, set the timeout value to 200 microseconds,
* and wait for messages from the connection
*/
tmout.tv_sec = 0;
tmout.tv_usec = 200;
/* Must set this each time round loop as selectmask call may change the
/* pointer time = &tmout;

88

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Scheduling MTP3 Stack Connections
/* Note: As we have no other fds open, the initial max fd (1st param)
* is 0. Also, we dont use the exeception mask, so we pass 0.
* Note too that last param is a struct timeval **.
*/
numFd = SS7_ifselectmask(0, &readMask, &writeMask, &exceptionMask, &time);
nfound = select(numFd, (int *)&readMask, (int *)&writeMask, &exceptionMask, time);
/* Note: ALWAYS call the cnxhandler function after select(2),
* even if select returns an error (-1). This is to allow the API
* lib to clear any socket errors.
*/
num_cnx = MAX_FD;
/* initial size of cnx_active array */
SS7_ifcnxhandler(nfound, &readMask, &writeMask, &exceptionMask, &num_cnx, cnx_active);
/* check if the select was triggered by
the port of the scedesc file descriptor,
* and receive messages
*/
if( (num_cnx > 0) && ( cnx_active[0] == cnxId) )
// call receive function;

Chapter 4

89

Using the Level 3 (MTP3/M3UA) API


MTP3 Primitives

MTP3 Primitives
A dialog between different layers is performed by primitives, which are abstract
elementary functions used to exchange information. There are two categories of
MTP3 primitives:
Request:

mtp_transfer_req

To send messages.

Indication:

mtp_transfer_ind

To receive messages.

mtp_status_ind

To inform the application about the


status of the local or remote MTP3.

mtp_pause_ind

To inform the application that a


particular destination is
temporarily unavailable.

mtp_resume_ind

To inform the application that a


particular destination is available
again.

Thus, the application exchanges messages and status information with MTP3.

90

Chapter 4

Using the Level 3 (MTP3/M3UA) API


MTP3 Primitives
Figure 4-2

Chapter 4

MTP3 Primitives

91

Using the Level 3 (MTP3/M3UA) API


Receiving MSUs with MTPL3_recv()

Receiving MSUs with MTPL3_recv()


The HP OpenCall SS7 MTP3 scheduling mechanism returns the number of stack
connections for which messages have been received (num_cnxId), and provides an
array of their connection ids (cnx_active). These messages are stored by the API
in the receive buffer, and must be received by the application using
MTPL3_recv().
For details about syntax, parameters, and return values, see the MTPL3_recv()
man page.
Example 4-3

Receiving Messages from the MTP3 API

int
dpc;
/* destination point code */
unsigned char
sio;
/* Service Information Octet */
int
sls;
/* signaling link selection */
int
datalen;
/* data length */
int
cnxId;
mtp_primit
primitive;
/* MTP primitive indication */
char
data [100];
char
username [50];
/* user name found in directory*/
int
result;
/* receive all messages available on IPC port */
while(MTPL3_recv(cnxId, NULL, &opc, &dpc, &sls, &sio, &primitive, &datalen, data)
> 0)
{
switch (primitive) {
case mtp_transfer_ind:
/* extract phone number and search username in directory
* send back the user name */
break;
case mtp_status_ind:
{
mtp_status_cause cause;
memcpy (&cause, data, sizeof(mtp_status_cause));
switch (cause) {
case dpc_congested:
printf (DPC congestion %d\n, dpc);
break;
case dpc_uncongested:
printf (DPC congestion end %d\n, dpc);
break;
case mtp_available:
printf (MTP available\n);

92

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Receiving MSUs with MTPL3_recv()
break;
case mtp_unavailable:
printf (MTP failed\n);
break;
case mtp_restarting:
printf (MTP restarting\n);
break;
case mtp_congested:
printf (MTP congested\n);
break;
case upu_unavailable:
printf (MTP upu unavailable\n);
break;
default:
printf (Unknown mtp_status indication %d\n, cause);
break;
}
}
break;
case mtp_pause_ind:
printf (MTP_PAUSE on %d\n, dpc);
break;
case mtp_resume_ind:
printf (MTP_RESUME on %d\n,dpc);
break;
default:
printf(Unknown MTP primitive %d\n,primitive);
break;
}

Chapter 4

93

Using the Level 3 (MTP3/M3UA) API


Sending MSUs Using MTPL3_send

Sending MSUs Using MTPL3_send


To send MSUs using the MTP3 API, the application must provide the SIO (Service
Indicator Octet) and the SIF (signaling Information Field) for the MSU. You can use
MTPL3_send() to send MSUs via stack connections (cnxIds) when they have
been scheduled and the IPC send buffer is not full.

NOTE

If the application sends messages to MTP level 3 that are greater than 268 Bytes for
ITU-T and 265 Bytes for ANSI, the HP OpenCall SS7 stack will log an error and
discard the message

For details about syntax, parameters, and return values, see the MTPL3_send()
man page.
Example 4-4

Sending MSUs via MTP3 API

fd_set writeMask, readMask, exceptionMask;


/* mask for select */
int
numFd,nFound;
int
cnxId, num_cnx, cnx_active[MAX_FD];
struct timeval
timeout = {1,0};
struct timeval
*timeptr, ctime;
int
phone_number;
char
* phoneNumberPtr;
int
SIO=0xa3
/*message priority=2, NI=2 MTP
user part=SCCP*/
while (server_available && (pending_requests < MAX_PENDING_REQUESTS))
{
phone_number = (rand () % 10) + PHONEOFFSET;
phoneNumberPtr = (char *)&phone_number;
printf (Client ask for phone number id = %d\n,phone_number);
FD_ZERO(&writeMask);
FD_ZERO(&readMask);
FD_ZERO(&exceptionMask)
while ( MTPL3_send(cnxId, NULL, -1, DPC, rand()%16, SIO, 0,
mtp_transfer_req, 4, phoneNumberPtr) == -1)
{
if ((ss7errno == EAPISENDFULL) || (ss7errno == EAPIBUSY)) {
/* LAN congestion: wait and retry later */
/* A real application would go back to the main loop */
/* and keep scheduling the whole application not just */
/* the SS7 connections. In this example, we stay in
*/
/* a local loop until the SS7 connection to MTP is */
/* un-flowcontrolled */

94

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Sending MSUs Using MTPL3_send
gettimeofday(&ctime,0);
printf(In the local loop - Time: sec(%d),usec(%d) \n,
ctime.tv_sec, ctime.tv_usec);
timeptr = &timeout;
numFd = SS7_ifselectmask(0, &readMask, &writeMask, &exceptionMask, &timeptr);
select(numFd,(int *)&readMask, (int *)&writeMask,
(int*)&exceptionMask;
NULL,timeptr);
/* When exiting the select either the timer pointed by */
/* the pointer timeptr has expired,
*/
/* or data is received on the SS7 connection to MTP, */
/* or the SS7 connection to MTP is un-flowcontrolled */
SS7_ifcnxhandler(nFound, &readMask, &writeMask,
&exceptionMask, &num_cnx,
cnx_active);
}
else
EXIT ((mtpsend failed error number %d\n, ss7errno));
}
}

Chapter 4

95

Using the Level 3 (MTP3/M3UA) API


Closing MTP3 Stack Connections with SS7_ifclose()

Closing MTP3 Stack Connections with SS7_ifclose()


You must only close an MTP3 connection when you are certain that the connection
will not be used. Repeated opening and closing of a stack connection places a high
overhead on the MTP3 API mechanism.
An MTP3 service is terminated when the application closes a stack connection using
SS7_ifclose(). All the entities used by the connection are also closed, and any
calls to MTPL3_send() or MTPL3_recv() are refused.
For details about syntax, parameters, and return values, see the SS7_ifclose()
man page.

96

Chapter 4

Using the Level 3 (MTP3/M3UA) API


Tuning MTP3 IPC Buffers with SS7_ifctrl()

Tuning MTP3 IPC Buffers with SS7_ifctrl()


As described in Tuning IPC Buffers, the application may need to alter the default
values of the IPC send and receive buffers. The application can use SS7_ifctrl()
to customize these IPC buffer attributes for each stack connection.
For details about syntax, parameters, and return values, see the SS7_ifctrl()
man page.

Chapter 4

97

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior

MTP3 API Behavior


The following sections illustrate how in certain situations the MTP3 API and library
react with respect to the application.

Sending MSUs
When the application issues an mtp_transfer_request primitive, the message
handling functions of MTP3 ensure that the MSU is delivered to the correct User
Part or peer application. These functions are based on the routing label (DPC, OPC
and SLS) contained in the MSU, and the loadsharing and route management
mechanisms of HP OpenCall SS7.
Figure 4-3

98

Sending an MSU

Chapter 4

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior

Receiving MSUs
The MTP3 message handling functions ensure that any signaling messages received
from the signaling network are delivered to the correct User Part or application.
When a message arrives, the message discrimination functions are activated to
determine if the received message is for this HP OpenCall SS7 Platform. That is, if
the DPC encoded in the routing label is the LPC, one of its local aliases, or one of its
VPCs, it accepts the message. If a local alias is encoded in the DPC field of the
routing label of an incoming MSU, MTP replaces it with the LPC before notifying
the upper layer. Then the message distribution functions examine the SI to deliver it
to the destined User Part (application).
An mtp_transfer_ind primitive is issued to inform the application that an MSU
destined for the application has been received.
Figure 4-4

Receiving an MSU

DPC Unavailable
When a DPC becomes unavailable because of a network event, the API informs the
application that the affected DPC is unavailable via the mtp_pause_ind primitive.

Chapter 4

99

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior
Figure 4-5

Receiving an mtp_pause_ind Primitive

If the application attempts to send an MSU to the affected DPC, it will result in the
error code EAPIILLVALUE.

100

Chapter 4

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior

DPC Available
When a DPC becomes available because of a network event, the API informs the
application that the previously unavailable DPC is available via the
mtp_resume_ind primitive.
Figure 4-6

Receiving an mtp_resume_ind Primitive

At this point the application can continue sending MSUs to the DPC.

Chapter 4

101

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior

DPC Congestion
When a DPC is congested, the API informs the application that the affected DPC is
congested via the mtp_status[dpc_congested] primitive.
Figure 4-7

Receiving mtp_status_ind[dpc_congested] Primitive

DPC Uncongested
When the affected DPC is uncongested, the application is notified by an
mtp_status_ind[dpc_uncongested] primitive, allowing the application to
continue sending MSUs to the DPC.
Figure 4-8

102

Receiving mtp_status_ind[dpc_uncongested] Primitive

Chapter 4

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior

Local MTP3 Unavailable


When all the local signaling links from the HP OpenCall SS7 platform are
unavailable due to failure, blocking, inhibiting, or deactivation of MTP3, the
application cannot use the services of MTP3.
In this situation the MTP3 API issues an mtp_status[mtp_unavailable]
primitive to the application. If the application attempts to send MSUs to any DPC,
the API will respond with the error EAPIILLVALUE.

Local MTP3 Restart


When the local MTP3 is unavailable due to global signaling link unavailability, the
signaling network functions initiates the restart procedure. The API informs the
application about the restart with an mtp_status[mtp_restart] primitive.
MTP3 starts activating its signaling links.
ANSI and ITU-T
Modes

If any DPCs become unavailable or available during the restart procedure, the
application is notified with the mtp_pause and mtp_resume primitives.
The mtp_status[available] primitive is issued to the application when this
procedure is finished, and the signaling links are available again.

TTC Mode

In TTC mode, the behavior during the restart procedure is different from ANSI and
ITU-T modes. DPCs that become available during the restart procedure are not
notified explicitly through the mtp_pause and mtp_resume primitives. Instead,
notification is done implicitly through the subsequent mtp_status[available]
primitive.
All requests from the application to send MSUs during the restart procedure are
refused with the error EAPIBUSY.

Chapter 4

103

Using the Level 3 (MTP3/M3UA) API


MTP3 API Behavior

104

Chapter 4

Using the SCCP API


This chapter describes the SCCP API and the functions that the application can use
to exchange signaling information with the SS7 stack. The guidelines given in this
chapter will ensure that the application correctly communicates with the SCCP API.

Chapter 5

105

Using the SCCP API


General Description of SCCP

General Description of SCCP


With MTP, SCCP provides its users or subsystems with the SS7 Network Service
Part (NSP) which is equivalent to OSI layers 1 to 3. The SCCP services include
end-to-end routing.

SCCP Routing
SCCP provides a routing function which allows signaling messages to be routed to a
signaling point based on a Global Title. This involves a translation function which
allows the Global Title to be translated into a signaling point code and a subsystem
number.
Preferred/Next
HP OpenCall SS7 complies to the ANSI standard for the Preferred/Next Preferred
Preferred and
functionality, as described in GR-82-CORE, Issue 1, June 1994, Revision 3,
Primary/ Secondary December 1995, paragraph 4.3.3.1 in the SCCP Management Procedures. This
functionality is also closely related to the Primary/Secondary functionality as
described in ITU-T 96. It allows a priority table on global title translations. If the
DPC on a translation is no longer preferred (for example, is not responding), the
global title will be translated to the next preferred DPC. See the section on
configuring SCCP in the HP OpenCall SS7 Operations Guide for more information.

SCCP Subsystem Management


SCCP also provides a management function to control the availability of the
subsystems, and broadcasts this information to other nodes in the network that need
to know the status of the subsystem.

106

Chapter 5

Using the SCCP API


General Description of SCCP
Figure 5-1

SCCP in the SS7 Stack

User application

TCAP
API

ISUP
& TUP
APIs

SCCP
API
MTP3/
M3UA
API

AG API

OA & M
APIs

TCAP
SCCP
End-to-end Routing
Functions

Chapter 5

MTP level 3

M3UA

MTP level 2

SCTP

MTP level 1

IP

107

Using the SCCP API


Features of the SCCP

Features of the SCCP


The SS7 Stack provides the services of SCCP to applications or subsystems
requiring enhanced transport services. The HP OpenCall SS7 SCCP supports the
features described below.

Connectionless Services
HP OpenCall SS7 provides the capabilities that are necessary to transfer
user-to-user information blocks (Network Service Data Unit - NSDU) without using
logical signaling connections. These NSDUs can be transferred either
non-sequentially or sequentially.

Class 0 - Non-sequential data transfer.

Class 1 - Sequential data transfer.

Multiple Application Connections


SCCP can accept multiple connections on the same SSN. One connection is active
and handles the traffic. One or several secondary standby connections can be made
that can be set to take over the active connection. A standby connection cannot
accept traffic until it becomes primary. You can only have one primary connection
per connection identifier. It describes the parameters you must set to use this
functionality.

Return Option
This feature determines how messages that encounter transport problems are
handled. With this option the message can be discarded, or returned to the
originating subsystem if the Calling Party Address is provided in the message. For a
segmented message, only the first segment is returned.

108

Chapter 5

Using the SCCP API


Features of the SCCP

SCCP Addressing Components


The HP OpenCall SS7 SCCP routing functions are based on the information
provided in the Called Party Address parameter. There are four basic components of
an SCCP address:

Global Title

DPC

SSN

Routing Indicator, either using Global Title or SSN.

Signaling Point Status Management


The SCCP informs the attached subsystems of the state of a remote signaling point,
such as

DPC unavailable

DPC available

Segmentation/Reassembly
HP OpenCall SS7 supports segmentation/reassembly, as defined in ITU-T White
Book 93, section Q.14 and in ANSI 96. This functionality is enabled by using the
_x function calls and associated primitives.

Subsystem Management
The SCCP updates the status of the subsystems based on failure, withdrawal and
recovery. These states are identified as:

User Out of Service

User In Service

Subsystem Status Test


The SCCP initiates an audit procedure to verify the status of a prohibited subsystem.

Chapter 5

109

Using the SCCP API


Features of the SCCP

SCCP Restart
On restart SCCP needs information about the accessibility of signaling points and
their subsystems. Thus, SCCP supports restart procedures initiated by the local
MTP, SCCP or subsystems. See the files sys.<className>.mtp and
sys.<className>.sccp and the HP OpenCall SS7 Operations Guide for more
details.

Replicated Subsystems
HP OpenCall SS7 supports replicated subsystems, but not the management of
replicated subsystems. Replicated subsystem numbers (SSNs) perform the same
function as the original SSNs. If the original SSN cannot handle the calls, it
negotiates to have calls sent to the replicated system. HP OpenCall SS7 allows you
to create your own replicated system, with the following constraints:

110

The backup subsystem must be a distant PC, for example a Peer Point Code.

The replicated subsystem must have the same SSN as the original subsystem.

Chapter 5

Using the SCCP API


Features of the SCCP

Message Priority
You can assign priority to outgoing messages. If the MTP level 3 becomes
congested, it will discard the messages with the lowest priority and keep those with
the highest priority. This is set in the SCCP parameter importance.
Messages with priority 0 will be discarded at SCCP level if there is remote SP
congestion. If the return option is set, a UDTS with the cause of network congestion
is returned to the initiator of the message. For other priorities (1 or 2) the messages
are given to MTP3 which is responsible for discarding them according to the level
of congestion.
The same rule applies to messages coming from the network that must be relayed by
SCCP after a translation.

NOTE

SCCP management messages (SSA, SSP, SST, SOR, SOG) have a default priority
of 0. This value can be changed via the SetMgtMsgPriority parameter in the
sys.<className>.sccp configuration file.

SCCP Relay
The HP OpenCall SS7 SCCP API can fully ensure the SCCP relay functions by
using one of the non-standard SCCP primitives sccp_xnotice_req or
sccp_notice_req. These primitives allow the application to generate the
necessary XUDTS or UDTS on the network.

Chapter 5

111

Using the SCCP API


Overview of How to Use the SCCP API

Overview of How to Use the SCCP API


Several steps are required when using the HP OpenCall SS7 SCCP layer: open,
schedule, receive, send, and close. This is briefly described below and then the
relevant sections for each action are referenced.

Creating SCCP Stack Connections


First you must create a SCCP stack connection using the SS7_xifcreate()
function. Use SS7_xifcreate() and other functions that include the _x in
their name, to be able to use new functionality, such as segmentation and
reassembly. See Creating SCCP Stack Connections Using SS7_xifcreate() on
page 114.

Scheduling SCCP Stack Connections


Secondly, you must schedule all the connections using the HP OpenCall SS7
scheduling mechanism and the following function calls:

SS7_ifselectmask()

select()

SS7_ifcnxhandler()

See Scheduling SCCP Stack Connections on page 116.

SCCP Primitives
Once you have opened and scheduled the SCCP connection, you can use primitives
and their respective parameters to communicate. Primitives consist of commands
and their respective responses associated with the services requested of SCCP. See
SCCP Primitives on page 119.

SCCP Parameters
Each SCCP primitive has associated SCCP parameters that include the necessary
information to complete the function corresponding to the primitive. See SCCP
Parameters on page 121.

112

Chapter 5

Using the SCCP API


Overview of How to Use the SCCP API

Receiving SCCP Primitives


The scheduling mechanism returns the number of stack connections (num_cnxId)
for which there are SCCP primitives waiting to be received. An array containing the
active connection identifiers is also returned. These primitives are stored by the
SCCP API in the receive buffer, and must be received by the application using
SCCP_recv(). See Receiving SCCP Primitives Using SCCP_recv() on
page 127.

Sending SCCP Primitives


HP OpenCall SS7 provides the application with SCCP_send() to send data to a
remote destination. This function supports both Class 0 and Class 1 of the SCCP
connectionless services. See Sending SCCP Primitives Using SCCP_send() on
page 130.

Closing SCCP Stack Connections


Only close an SCCP stack connection when you are certain that the connection will
not be used again. Repeated opening and closing of a stack connection places a high
overhead on the SCCP API mechanism. See Closing SCCP Stack Connections
Using SS7_ifclose() on page 131.

Using the SCCP API Shared Library


The SCCP API is available as a shared library.
The following is an example of a compile/link line:
gcc -fexceptions -pthread -D_GNU_SOURCE -Wall -I/opt/OC/include -L/opt/OC/lib
-o SccpClient SccpClient.c -lSS7utilXXX

where XXX = WBB, AAA, WAA, or ABB.

Chapter 5

113

Using the SCCP API


Creating SCCP Stack Connections Using SS7_xifcreate()

Creating SCCP Stack Connections Using


SS7_xifcreate()
The SCCP API creates stack connections for the application. The application
requests the services of SCCP using these connections.

NOTE

SS7_xifcreate() is the correct function to use. If the application uses


SS7_ifcreate(), you should replace it with SS7_xifcreate().

With the introduction of SS7_xifcreate() additional primitives replace existing


primitives, for example sccp_xunitdata_req ()now replaces
sccp_unitdata_req(). Use _x primitives with _x calls.

To enable multiple connections, you will also have to set parameters in the
configuration file sys.<className>.api:
Table 5-1

Multiple Connection Configuration

If you...

...then set the parameter...

...to...

do not want this functionality

autoSwitch

NO

want the secondary connection to become active if the


primary fails
want the primary connection to be closed when the
secondary connection becomes active

YES
(default)
closeOnEnable

want the primary connection to become standby when


the secondary connection becomes active
want to close the existing primary connection when a
new primary connection is created

YES
NO
(default)

closeOnCreate

want to make the existing primary connection secondary


when a new primary connection is created

YES
NO
(default)

For more details, see the SS7_xifcreate() man page.

114

Chapter 5

Using the SCCP API


Creating SCCP Stack Connections Using SS7_xifcreate()
Example 5-1

Creating an SCCP Stack Connection

ss7_service_parms
sceparms;
OCTET
client_ssn = 101;
int
cnxId;
sceparms.ssn = client_ssn;
sceparms.mode = SCCP_ITU_WHITE;

/* service parameters */

/* open the SCCP service */


if (SS7_xifcreate (Stack_1,ss7_sccp,NULL,&sceparms,&cnxId,NULL) == -1)
/* error handling */

Chapter 5

115

Using the SCCP API


Scheduling SCCP Stack Connections

Scheduling SCCP Stack Connections


As described in Chapter 3, General API Guidelines, you must schedule all the
stack connections using the HP OpenCall SS7 scheduling mechanism. Scheduling
the SCCP stack connections is achieved by using:

SS7_ifselectmask()

select()

SS7_ifcnxhandler()

SS7_ifselectmask()
This pre-select function is used for all SCCP stack connections. It takes the file
descriptor masks created by the application, and sets these masks to include the file
descriptors used by the API to manage the SCCP stack connections. The application
must call this function before calling select().
For details about syntax, parameters, and return values, see the
SS7_ifselectmask() man page.

select()
The select() function is used for all HP OpenCall SS7 scheduling. It modifies
the read, write and exception masks created by SS7_ifselectmask().

116

Chapter 5

Using the SCCP API


Scheduling SCCP Stack Connections

SS7_ifcnxhandler()
The application must call this function after using select(), regardless of the
result of the select() command. SS7_ifcnxhandler() requests the API to
process the masks returned by select() and manage the internal mechanisms.
An array of stack connection identifiers is used to identify the stack connections that
have messages waiting to be received by the application.
Activity on the connection is flagged when:

a message is received by the SS7 stack

a closed connection is found (a send or receive call returns an error). The


application should call the close function to deallocate API resources.

a connection goes from busy state (API_BUSY) to normal state. The application
can resume processing (send and receive calls no longer return an error).

For details about syntax, parameters, and return values, see the
SS7_ifcnxhandler() man page.
Example 5-2

Scheduling SCCP Stack Connections

ss7_service_parms
sceparms;
/* service parameters */
int
i, result;
fd_set
readMask, writeMask, exceptionMask; /* masks for select */
int
nfound;
/* select result */
struct timeval
tmout, * time = &tmout;
int
numFd;
int
num_cnx, cnx_active[MAX_FD];
sceparms.ssn = client_ssn;
sceparms.mode = SCCP_ITU_WHITEBOOK
/* open the SCCP service */
/* Zero select bit masks before entering loop */
FD_ZERO(&readMask);
FD_ZERO(&writeMask);
FD_ZERO (&exceptionMask)
for (;;)
/* endless select loop
{
tmout.tv_sec = 1;
tmout.tv_usec = 1;
/* Must set this each time round loop as selectmask call
* may change the pointer
*/
time = &tmout;

Chapter 5

117

Using the SCCP API


Scheduling SCCP Stack Connections
pending_requests = 0;
// send a request
/* Note: As we have no other fds open, the initial max fd
* is 0. Also, we dont use the exeception mask, so we pass 0.
* Note too that last param is a struct timeval **.
*/
numFd = SS7_ifselectmask(0, &readMask, &writeMask, &exceptionMask, &time);
nfound = select(numFd,(int *)&readMask, (int *)&writeMask,
&exceptionMask, time);
/* Note: We ALWAYS call the cnxhandler function after select(2),
* even if select returns an error (-1). This is to allow the API
* lib to clear any socket errors.
*/
num_cnx = MAX_FD;
/* initial size of cnx_active array */
SS7_ifcnxhandler(nfound, &readMask, &writeMask, &exceptionMask,
&num_cnx, cnx_active);
/* check if the select was triggered by
* the port of the scedesc file descriptor,and receive messages
*/
if ( (num_cnx > 0) && ( cnx_active[0] == cnxId) )
// receive waiting indications
}

118

Chapter 5

Using the SCCP API


SCCP Primitives

SCCP Primitives
Primitives consist of commands and their respective responses associated with the
services requested of SCCP. As shown in Figure 5-2, SCCP Primitives,, there are
four categories.
Figure 5-2

SCCP Primitives

The SCCP API is an abstract interface providing applications with stack


connections which are used to exchange the following service primitives.

Chapter 5

119

Using the SCCP API


SCCP Primitives

Recommendation
Use of the _x primitives is preferred because they take advantage of the
segmentation/reassembly functionality.
Table 5-2

SCCP Service Primitives

Type

Primitive Name

Associated Structure

Service

Request

sccp_xunitdata_req

sccp_xunitdata_parms

To request SCCP to transport data.

sccp_state_req

sccp_state_parms

To request the status of a subsystem number.

sccp_xnotice_req

sccp_xnotice_parms

Indicates that a unitdata message cannot be


delivered (GT translation has failed)..

sccp_coord_req

sccp_coord_parms

To request permission for a subsystem to go


out of service.

Response

sccp_coord_resp

sccp_coord_parms

To inform SCCP that the withdrawal of a


subsystem has been accepted.

Indication

sccp_xunitdata_ind

sccp_xunitdata_parms

To inform an SCCP user that signaling data


has been delivered.

sccp_state_ind

sccp_state_parms

To inform an SCCP user of the status of a


signaling point.

sccp_pcstate_ind

sccp_pcstate_parms

To return the status of a signaling point.

sccp_xnotice_ind

sccp_xnotice_parms

To indicate that a message issued from the


SCCP user was not delivered.

sccp_coord_ind

sccp_coord_parms

To inform an SCCP user that a Subsystem


out of Service Request message has been
received.

sccp_coord_conf

sccp_coord_parms

To confirm that the Subsystem out of


Service Request message was accepted.

Confirmation

For more details, see the SCCP_recv(3) man page.

120

Chapter 5

Using the SCCP API


SCCP Parameters

SCCP Parameters
Each SCCP primitive has associated SCCP parameters that include the necessary
information to complete the function corresponding to the primitive.

Local Alias PC
The SCCP level automatically changes the PointCode field of the
calledAddress parameter from a local alias used by the network and received by
the platform into the LPC. This makes use of local aliases completely transparent to
the higher levels such as TCAP. Therefore you should never use a local alias within
a local application.
Table 5-3

SCCP Parameters and Values

SCCP Parameter

Structure

Element

Type

Value

affectedDPC

BITS32

affectedSSN

OCTET

associatedPC

BITS32

Chapter 5

121

Using the SCCP API


SCCP Parameters
Table 5-3

SCCP Parameters and Values (Continued)

SCCP Parameter

Structure

Element

Type

Value

callingAddress

SC_ADDRESS

pointCodePrese
nt

SC_PC_USAGE

SC_no,
SC_SCCPUse,
SC_MTPUse

pointCode

BITS32

ssnPresent

ubool

ssn

OCTET

gt

pointer to a
SC_GLOBAL_TITLEstructure
or NULL (no global title)

calledAddress

SC_GLOBAL_
TITLE

coordStatus

122

Following fields only used when gt contains a pointer


routeOnGt

ubool

gtIndicator

SC_GT_INDICATOR

SC_noGlobalTitle
SC_gtType1
SC_gtType2
SC_gtType3
SC_gtType4

translation

SC_TRANSLATION_TYP
E

SC_unused
SC_internetwork_1
SC_networkSpecific_1

numbering

SC_NUMBERING_PLAN

SC_unknownNumbering
SC_isdn
SC_userdata
SC_telex
SC_maritimeMobile
SC_landMobile
SC_isdnMobile

encoding

SC_ENCODING_SCHEME

SC_unknownEncode
SC_bcdOdd
SC_bcdEven

nature

SC_ADDRESS_NATURE

SC_subscriberNo
SC_nationalNo
SC_internationalNo

digits

char*

SC_CONFIRM_STATUS

SC_granted_withdrawal
SC_denied_withdrawal
SC_no_peer

Chapter 5

Using the SCCP API


SCCP Parameters
Table 5-3

SCCP Parameters and Values (Continued)

SCCP Parameter

Structure

Element

Type

Value

hopCounter

unsigned char

Range: 1-15
Defaults to 15 if set outside
range.

importance

InSequence

int

This sets the priority level of


the message, (whether it will be
discarded at MTP if there is
congestion). Values range from
0-2, with 0 being the lowest
level of importance. If the value
of importance in
SCCP_send() is out of range
(0 to 2), the value is reset to 0.

ubool

Set to 0.

multInd

SC_SMI

multIndUnknown
multIndSolitary
multIndDuplicated

returnOption

ubool

Chapter 5

123

Using the SCCP API


SCCP Parameters
Table 5-3

SCCP Parameters and Values (Continued)

SCCP Parameter

Structure

Element

Type

Value

returnReason

SC_RETURN_REASON

SC_noTranslationNature
SC_noTranslationSpecif
ic
SC_subsystemCongestion
SC_subsystemFailure
SC_unequippedUser
SC_networkFailure
SC_networkCongestion
SC_unqualified
SC_errorInMsgTransport
SC_errorInLocalprocess
ing
SC_noDestReassembly
SC_sccpFailure
SC_hopCounterViolation
SC_segNotSupported
SC_segFailure
SC_invalidISNIrouting
SC_unauthorizedMsg
SC_msgIncompatibility
SC_noISNIconsRouting
SC_redundantISNIconsRo
uting
SC_noISNIidentificatio
n
SC_noError

SegmOption

ubool

For future use. Should be set to


0, but no error message is
returned

sequenceControl

int

serviceClass

SC_SERVICE
_ CLASS

spStatus

SC_SP_STATUS

SC_inaccessible
SC_congestedSC_accessi
ble
SC_restartingSC_conges
ted
SC_cnx_error

XUDTOption

ubool

See Table Note 1

XUDTSOption

ubool

See Table Note 2

124

SCCP_CLASS_0 = 0
SCCP_CLASS_1

Chapter 5

Using the SCCP API


SCCP Parameters
Table 5-3

SCCP Parameters and Values (Continued)

SCCP Parameter

Structure

Element

Type

Value

userStatus

SC_USER_STATUS

SC_UIS
SC_UOS

See also the SCCP_recv(3) man page.


Table Note 1

In xunitdata_req:
FALSE: XUDT sent only when segmentation is needed (UDT otherwise).
TRUE: force use of XUDT rather than UDT.
In xunitdata_ind:
FALSE: UDT received.
TRUE: XUDT received.

Table Note 2

In xnotice_req:
FALSE: Use UDTS message type.
TRUE: Use XUDTS message type.
In xnotice_ind:
FALSE: UDTS received.
TRUE: XUDTS received.

Chapter 5

125

Using the SCCP API


SCCP Parameters

Global Title Types


The HP OpenCall SS7 SCCP supports all Global Title types as defined in Q.713
3.4.1. The application identifies the GT type by setting the gtIndicator.
Table 5-4

Global Title Type


SC_GT_Indicator

ITU-T

ANSI

SC_gtType1

nature of address

translation type,
numbering plan,
encode-scheme

SC_gtType2

translation type

translation type

SC_gtType3

translation type,

not used

numbering plan,
encode-scheme
SC_gtType4

nature of address,

not used

translation type,
numbering plan,
encode-scheme
You must ensure that gt element of SC_ADDRESS contains a pointer to
SC_GT_TITLE.

126

Chapter 5

Using the SCCP API


Receiving SCCP Primitives Using SCCP_recv()

Receiving SCCP Primitives Using SCCP_recv()


The scheduling mechanism returns the number of stack connections (num_cnxId)
for which there are SCCP primitives waiting to be received. An array containing the
active connection identifiers is also returned. These primitives are stored by the
SCCP API in the receive buffer, and must be received by the application using
SCCP_recv().
For details about syntax, parameters, and return values, see the SCCP_recv() man
page.
Example 5-3

Receiving SCCP Primitives

/* process incoming data from SS7 */


void receive_request()
{
BITS32
dpc;
/* destination point code
*/
long
data[WB_MAX_USERDATA/sizeof(long)];
sccp_primitive
primitive;
/* SCCP primitive */
sccp_xunitdata_parms
* udt_parms_ptr;
sccp_xnotice_parms
* not_parms_ptr;
sccp_state_parms
* state_parms_ptr;
sccp_pcstate_parms
* pcstate_parms_ptr;
SC_USER_STATUS
userstat;
SC_SP_STATUS
pcstat;
OCTET
ssn;
int
result;
while ((result=SCCP_recv (cnxId,NULL, &primitive, (char *)data)) > 0)
{
switch (primitive) {
case sccp_xunitdata_ind:
udt_parms_ptr = (sccp_xunitdata_parms *) data;
printf (Phone number %d, user name is %s\n,
*(int *)udt_parms_ptr->data,(udt_parms_ptr->data+4));
pending_requests--;
nb_requests_processed--;
break;
case sccp_xnotice_ind:
not_parms_ptr = (sccp_xnotice_parms *) data;
dpc = not_parms_ptr->calledAddress.pointCode;
ssn = not_parms_ptr->calledAddress.SSN;

Chapter 5

127

Using the SCCP API


Receiving SCCP Primitives Using SCCP_recv()
printf ( sccp_xnotice_ind return reason = %d dpc %u ssn %d\n,
not_parms_ptr->returnReason, dpc, ssn );
break;
case sccp_pcstate_ind:
pcstate_parms_ptr = (sccp_pcstate_parms *) data;
pcstat = pcstate_parms_ptr->spStatus;
dpc = pcstate_parms_ptr->affectedDPC;
switch(pcstat) {
case SC_congested:
printf (SCCP congestion %d\n, dpc);
break;
case SC_uncongested:
printf (SCCP congestion end %d\n, dpc);
break;
case SC_accessible:
pending_requests=0;
server_available=1;
printf (SCCP available %d\n, dpc);
break;
case SC_inaccessible:
printf (SCCP unavailable %d\n, dpc);
/*
server_available=0; */
break;
case SC_restarting:
printf (SCCP restarting %d\n, dpc);
break;
case SC_cnx_error:
printf (Error on SCCP connection\n);
exit(1);
break;
default:
printf (Unknown sccp_pcstate indication %d\n, pcstat);
}
break;
case sccp_state_ind:
state_parms_ptr = (sccp_state_parms *) data;
userstat = state_parms_ptr->userStatus;

128

Chapter 5

Using the SCCP API


Receiving SCCP Primitives Using SCCP_recv()
dpc = state_parms_ptr->associatedPC;
ssn = state_parms_ptr->affectedSSN;
if ( (dpc == server_pc) && (ssn == server_ssn) )
switch(userstat) {
case SC_UIS:
server_available = 1;
printf (Server in service\n);
break;
case SC_UOS:
pending_requests = 0;
server_available = 0;
printf (Server out of service\n);
break;
default:
printf (Unknown sccp_state indication %d\n, userstat);
}
break;
default:
printf(Received unknown sort of primitive %d\n,primitive);
exit(0);
}
}
/*Error Handling*/
if (result == -1)
print((Error in sccprecv = %d\n, ss7errno));
}

Chapter 5

129

Using the SCCP API


Sending SCCP Primitives Using SCCP_send()

Sending SCCP Primitives Using SCCP_send()


HP OpenCall SS7 provides the application with SCCP_send() to send data to a
remote destination. This function supports both Class 0 and Class 1 of the SCCP
connectionless services.
This non-blocking function sends data to a remote destination. When used for
in-sequence message transfer, the serviceClass parameter must be set to
SCCP_CLASS_1. The sequenceControl parameter contains the sequence
number selected by the application. This sequence number is used to generate the
signaling Link Selection field (SLS - routing label) used to send the message. The
same sequenceControl value always generates the same SLS field.
For details about syntax, parameters, and return values, see the SCCP_send() man
page.

130

Chapter 5

Using the SCCP API


Closing SCCP Stack Connections Using SS7_ifclose()

Closing SCCP Stack Connections Using SS7_ifclose()


Only close an SCCP stack connection when you are certain that the connection will
not be used. Repeated opening and closing of a stack connection places a high
overhead on the SCCP API mechanism.
An SCCP service is terminated when the application closes a stack connection using
SS7_ifclose(). All the entities used by the connection are also closed, and any
calls to SCCP_send() or SCCP_recv() are refused.
You must reschedule the stack connections after you have called SS7_ifclose(),
this ensures that all messages are flushed from the send IPC buffers.
For details about syntax, parameters, and return values, see the SS7_ifclose()
man page.

Chapter 5

131

Using the SCCP API


Controlling the SCCP Using SS7_ifctrl()

Controlling the SCCP Using SS7_ifctrl()


As described in Tuning IPC Buffers, the application may need to alter the default
values of the IPC send and receive buffers. The application can use SS7_ifctrl()
to customize these IPC buffer attributes for each stack connection.
This function modifies the IPC buffers attached to a particular stack connection
(cnxId) according to the selected IPC command.
For details about syntax, parameters, and return values, see the SS7_ifctrl()
man page.

132

Chapter 5

Using the SCCP API


SCCP Addressing and Routing

SCCP Addressing and Routing


SCCP Addressing
From the SCCP API there is no direct access to the MTP label information. Some
MTP addressing label information is accessible from the SCCP address.

For incoming messages that will be delivered to the user, the Called and Calling
party address will be completed with the PC in the MTP label if:
((no point code present) and (no GT present) and ((GT present) and (Route on
PC)))

The Called and Calling party address will always contain a point code before
delivery to the local user.
The indicator of the point code presence (SC_PC_USAGE) will be set to:

SC_PC_USAGE setting

Meaning

SC_no

Never; the Called and Calling party addresses will


always contain the point code information

SC_SccpUse

When the point code was originally present in the


SCCP addressing labels, or a local translation took
place. Note that in this case the SCCP user does not
have access to the MTP routing label information,
even though this information might be different
from information which is present in the SCCP
addressing labels.

SC_MtpUse

When there is no other point code given (explicitly,


in the SCCP part or implicitly, through Route on
GT)

For outgoing messages it is the responsibility of the application to fill in the


relevant fields. SC_PC_USAGE may take two values:

SC_no if no PC information is added by the application

In this case routing indicator must be set to RtGT and the translation must
take place locally

Chapter 5

133

Using the SCCP API


SCCP Addressing and Routing

SC_SccpUse if the application provides a point code

In this case the routing indicator can be set to:


RtGT
and the translation will be done remotely because PC != LPC
RtPC
and message distributed to a local subsystem if PC = LPC or message
sent to a remote is PC != LPC
Incoming Messages
For incoming messages that will be delivered to the user Called and Calling party
address will be completed with the PC in the MTP label if:

((no point code present) and

(no GT present) or ((GT present) and (Route on PC)))

In this case the indicator of the point code presence is set to: SC_MtpUse.
The Called and Calling party address will ALWAYS contain a point code before
delivery to the local user.

134

Chapter 5

Using the SCCP API


SCCP Addressing and Routing
Outgoing Messages
For outgoing messages it is the responsibility of the application to fill in the relevant
fields. SC_PC_USAGE may take two values:

SC_no if no PC information is added by the application

In this case the routing indicator must be set to RtGT and the translation must
take place locally.

SC_SccpUse if the application provides a point code

In this case the routing indicator can be set to:


RtGT
and the translation will be done remotely because PC != LPC
RtPC
and message distributed to a local subsystem if PC = LPC or message sent
to a remote is PC != LPC

Types of Traffic
There are four types of traffic: loopback, outbound, inbound, and relay.
The different parts of the traffic flow within each type of traffic are described in
more detail in the message transfer flowcharts later in this chapter.
Inbound

Chapter 5

Inbound traffic goes from the MTP layer to the SCCP layer.

135

Using the SCCP API


SCCP Addressing and Routing
Figure 5-3

Inbound Traffic

Outbound

Outbound traffic goes from the application to the SCCP layer that has addressing
capabilities, such as Global title translation, and then to the MTP layer.

Figure 5-4

Outbound Traffic

136

Chapter 5

Using the SCCP API


SCCP Addressing and Routing
Loopback

Loopback traffic goes from the application to the SCCP layer to a local application
on the same system.

Figure 5-5

Loopback Traffic

Chapter 5

137

Using the SCCP API


SCCP Addressing and Routing
Relay

Relay traffic is inbound traffic that goes to the SCCP layer, a translation of addresses
is performed, and then the traffic goes back to the MTP layer.

Figure 5-6

Relay Traffic

138

Chapter 5

Using the SCCP API


SCCP Addressing and Routing
Elements of SCCP Addressing
SCCP addressing includes four separate elements:

Destination Point Code (DPC)


This element is recognized by MTP, and is used to determine if the SCCP
message has arrived at its destination or if it must be routed via MTP to another
Point Code.

Global Title (GT)


This address element is not recognized by the SS7 network, and must be
translated into a DPC or a DPC and SSN.

Subsystem Number
This element identifies the sub-system (ISUP, SCCP management or a TCAP
user) that can be accessed via the SCCP.

Routing Indicator
This indicates whether routing is based on the SSN or on a GT.

Chapter 5

139

Using the SCCP API


SCCP Addressing and Routing
The Main Fields in SCCP Called and Calling Party Addresses
The table below describes the main fields in the SCCP routing addresses.
Table 5-5

The SCCP Addressing Fields and Possible Values


Field Name

Can be set to:

PointCodePresent

SC_no
(no point code)

PointCode

a DPC value

SsnPresent

Boolean value

SSN

an SSN value

SC_SccpUse
(use for routing)

SC_MtpUse
(use for routing, but code
address at MTP level only,
not at SCCP level).

gt pointer to the structure


routeOnGt
nature
translation type
numbering plan
... (other fields)

140

Boolean value
NAI value
TT value
NP value
...

Chapter 5

Using the SCCP API


SCCP Addressing and Routing

Global Title Translation


HP OpenCall SS7 SCCP contains a Global Title Table which uses the Numbering
Plan (NP), Translation Type (TT) and Nature of Address Indicator (NAI) elements
of the Global Title to perform its translation. Global Titles that do not have all these
elements are assumed to contain the value 0.
HP OpenCall SS7 does not support the translation of one Global Title to another
Global Title.
The result of a Global Title Translation is either:

a DPC
This corresponds to an incomplete translation. The GT continues to be used for
routing (routOnGt remains set to yes).

a DPC and SSN


This corresponds to a complete translation. The GT is no longer used for routing
(routOnGt is set to no). However, if the DPC found during the GT translation
is the LPC, then routOnGt remains set to yes.

Chapter 5

141

Using the SCCP API


SCCP Addressing and Routing
Figure 5-7

142

Global Title Translation

Chapter 5

Using the SCCP API


Outgoing Routing Control

Outgoing Routing Control


When the application requests the SCCP API to send an sccp_xunitdata_req
primitive and associated parameters (using sccp_send(), you must also provide a
calledPartyAddress parameter.
The HP OpenCall SS7 SCCP outbound routing mechanism depends on the gt
element of the calledPartyAddress, which indicates whether routing is based
on the GT or on DPC and SSN. The contents of the callingPartyAddress is left
untouched by the routing mechanism.

Chapter 5

143

Using the SCCP API


Outgoing Routing Control
Figure 5-8

144

Message Transfer 1: TCAP or SCCP Application to SCCP Local Bus

Chapter 5

Using the SCCP API


Outgoing Routing Control
Figure 5-9

Chapter 5

Message Transfer 2: Remote Entity to MTP Layer

145

Using the SCCP API


Outgoing Routing Control

Routing Without GT Translation


HP OpenCall SS7 does not perform a GT translation when the application provides
a point code. This point code is either a local point code (LPC) or a remote point
code (DPC).
In a calledPartyAddress, the point code can also be combined with an SSN
value or a GT value. Once the application sets the pointCodePresent field of the
calledPartyAddress parameter of an sccp_xunitdata_req primitive,
SCCP checks the pointCode value.
SSN

If the pointCode field of the calledPartyAddress contains the LPC (the point
code of the HP OpenCall SS7 platform), the primitive must be forwarded to a local
SSN user. The contents of the calledPartyAddress are left untouched.

DPC and SSN

If the pointCode value of the calledPartyAddress contains a DPC, this


indicates that the sccp_xunitdata_req primitive must be sent to a remote SCCP
user (SSN). The DPC is used by the MTP3 to send a Unit Data (UDT) or extended
Unit Data (XUDT) message to this remote point code.
The contents of the calledPartyAddress is not modified by the SCCP routing
control mechanism.

DPC and GT

146

If the gt and the pointCode fields are both present in the


calledPartyAddress, GT translation does not occur. MTP routing of the UDT
message is determined by the DPC value contained in the pointCode field.
Translation is then performed by the DPC SCCP translation tables.

Chapter 5

Using the SCCP API


Outgoing Routing Control

Routing with Local GT Translation


When there is no pointCode value in the calledPartyAddress parameter, then
the HP OpenCall SS7 SCCP performs a local translation on the value contained in
the calledPartyAddress field.
The local GT translation can produce a local SSN address, a DPC or both.
GT = LPC and SSN

If the calledPartyAddress parameter contains only a gt value, this value is


translated by the local translation tables to an LPC and an SSN value. Because the
translation returns an LPC, the sccp_xunitdata_req primitive is forwarded to a
local SCCP user (SSN2).

GT= PC

The local translation of a GT value can also produce a point code (PC1) only.
Because the point code is not an LPC, UDT containing the calledPartyAddress
(as defined in the sccp_xunitdata_req primitive) is routed by MTP3 with the
DPC set to PC1.
The gt value is translated to a pointCode (PC1). Therefore a UDT message
containing the calledPartyAddress is sent to PC1 via MTP.

GT = PC and SSN

Even if the calledPartyAddress parameter contains an SSN value (SSN1), a


GT translation must be performed on the gt value to determine if the primitive is
destined for a local SCCP user or if it must routed through MTP to a remote SCCP
user.
The gt value is translated into a point code (PC1) and a new SSN value (SSN2).
The values contained in the calledPartyAddress are modified: the new SSN
replaces the SSN value, and the routing indicator is set to false (routing on Point
Code) indicating that PC1 is the final DPC and that SSN2 is a local user of PC1.

Chapter 5

147

Using the SCCP API


Incoming Routing Control

Incoming Routing Control


When HP OpenCall SS7 SCCP receives an mtp_transfer_ind from MTP3, the
calledPartyAddress parameter of the received SCCP message is checked. The
SCCP inbound routing mechanism is activated by the contents of the
calledPartyAddress parameter.

148

Chapter 5

Using the SCCP API


Incoming Routing Control
Figure 5-10

Chapter 5

Message Transfer 3: MTP layer to SCCP Local Bus

149

Using the SCCP API


Incoming Routing Control
Figure 5-11

150

Message Transfer 4: Local User Entity to SCCP Interface

Chapter 5

Using the SCCP API


Incoming Routing Control
Figure 5-12

Chapter 5

Message Transfer 5: SCCP to TCAP or an Application on SCCP API

151

Using the SCCP API


Incoming Routing Control

Routing Without GT Translation


GT translation is not performed if the routing indicator in the incoming
calledPartyAddress is set to routing on PC (routOnGt=FALSE). This
indicates that the SCCP message received from the network is destined for a local
SSN, and retransmission is not necessary.
The SSN can be combined with a PC value in the received
calledPartyAddress.
SSN only

When the received calledPartyAddress only contains an SSN value (SSN1),


SCCP routes an sccp_xunitdata_ind primitive to the local SCCP user.
Before the primitive is passed to the application, the pointCodePresent is set to
SC_MtpUse indicating that the point code values of calledPartyAddess and
callingPartyAddress are retrieved from the MTP routing label.

DPC and SSN

If the received calledPartyAddress contains both an LPC and an SSN, then the
sccp_xunitdata_ind passed to the SCCP user (SSN1) with the
pointCodePresent is set to SC_SccpUse. This indicates to the application that
the point code values were previously present in the SCCP addressing labels.

Routing with Local GT Translation


Local GT translation is necessary when the incoming calledPartyAddress only
contains a GT value (gt). The local translation of a gt produces either a local point
code or a DPC and/or an SSN.
Local PC and/or
SSN

The sccp_xunitdata_ind primitive is destined for a local SCCP user if the GT


translation of the received calledPartyAddress returns only an SSN. Before the
primitive is passed to the SCCP user, the calledPartyAddress is modified.

DPC and/or SSN

Local GT translation can also result in the relay of the SCCP message. In this case,
the result of the local GT translation is used to determine the outbound route of the
SCCP message (the MTP3 label).

152

Chapter 5

Using the SCCP API


Return Option

Return Option
The HP OpenCall SS7 SCCP provides a return on error procedure if the SCCP
routing is unable to transfer a UDT or an XUDT message.
The message is returned undelivered to the originating SCCP user using the
sccp_xnotice_ind primitive if a signaling point or subsystem is inaccessible or
undefined in the SCCP routing information.
A message can only be returned if the callingPartyAddress parameter contains
the address of the originating SCCP user. The reason for the message return is
provided in the returnReason parameter of the sccp_xnotice_ind. Table 5-3,
SCCP Parameters and Values, lists the possible values of this parameter.
To use the return option of the HP OpenCall SS7 SCCP, the application must set the
returnoption and callingPartyAddress parameters for each
sccp_xunitdata_req primitive sent by the application.

Chapter 5

153

Using the SCCP API


Return Option
Figure 5-13

154

Returning an Undelivered Message

Chapter 5

Using the SCCP API


Signaling Point Status Management

Signaling Point Status Management


Signaling point status management updates the status information provided by
MTP3 management primitives. This allows alternative routing to backup signaling
points and/or backup subsystems.
HP OpenCall SS7 does not provide alternative GT translations if a remote PC is
unavailable.

Signaling Point Prohibited


When an mtp_pause_ind primitive is received from MTP3, HP OpenCall SS7
SCCP updates its status information to indicate that a DPC is prohibited and that its
backup signaling points must be used. All the subsystems associated with DPC1 are
also prohibited.
The application is notified of this situation by an sccp_state_ind primitive. This
primitive indicates to the application that a particular SSN (SSN2) is out of service
(UOS), and if there is a backup subsystem for SSN2.
An sccp_pcstate_ind primitive indicating the status of the affected DPC is also
passed to the application.

Chapter 5

155

Using the SCCP API


Signaling Point Status Management
Figure 5-14

156

Signaling Point Prohibited

Chapter 5

Using the SCCP API


Signaling Point Status Management

Signaling Point Allowed


HP OpenCall SS7 SCCP receives an mtp_resume_ind primitive from MTP3 if a
DPC becomes accessible again.
As shown in Figure 5-15, Signaling Point Allowed, the application is notified by
an sccp_pcstate_ind primitive.
Figure 5-15

Signaling Point Allowed

Signaling Point Congested


SCCP updates the congestion status of the identified signaling point when the
HP OpenCall SS7 SCCP receives an mtp_status_ind primitive from MTP3. The
application is notified of the congestion situation by an sccp_pcstate_ind
primitive as shown in Figure 5-16, Signaling Point Congestion.

Chapter 5

157

Using the SCCP API


Signaling Point Status Management
Figure 5-16

158

Signaling Point Congestion

Chapter 5

Using the SCCP API


Subsystem Status Management

Subsystem Status Management


The status of subsystems is based on their failure, withdrawal and recovery. A
subsystem is said to be in service (UIS) or out of service (UOS).

Local Subsystem Out of Service


When a local subsystem goes out of service, SCCP is notified by an
sccp_state_req primitive from the subsystem. HP OpenCall SS7 SCCP then
modified its signaling information by marking the specific subsystem as prohibited.
Other local subsystems are notified with the sccp_state_ind primitive. Remote
subsystems attached to a remote SCCP are notified with Subsystem-Prohibited
(SSP) messages.
Figure 5-17

Chapter 5

Local Subsystem Out Service

159

Using the SCCP API


Subsystem Status Management

Local Subsystem In Service


When a local subsystem returns to service, SCCP is notified by an
sccp_state_req primitive from the subsystem. HP OpenCall SS7 SCCP then
modifies status information by marking the specific subsystem as allowed.
Other local subsystems are notified with sccp_state_ind primitive. Remote
subsystems attached to remote SCCP are notified with Subsystem-Allowed (SSA)
messages.
Figure 5-18

160

Local Subsystem In Service

Chapter 5

Using the SCCP API


Subsystem Status Test

Subsystem Status Test


This test procedure verifies the status of a subsystem when it is marked as
prohibited. It is initiated when an mtp_resume_ind primitive or an SSP message
is received. The subsystem status test is stopped if an mtp_pause_ind or a
Subsystem-Allowed (SSA) message is received.
The test procedure is performed in fixed time intervals for all subsystems marked as
prohibited. A Subsystem State Test (SST) message is sent from the local SCCP to
the SCCP of the failed subsystem. On receipt of an SST, the state of the subsystem
concerned is checked. If the subsystem is in service an SSA message is returned.

Chapter 5

161

Using the SCCP API


Subsystem Status Test
Figure 5-19

162

Subsystem Status Test

Chapter 5

Using the SCCP API


Replicated Subsystems

Replicated Subsystems
The HP OpenCall SS7 SCCP supports the coordinated withdrawal of local and peer
subsystems.

Available Backup Subsystem


To smoothly withdraw a subsystem, the application must pass an
sccp_coord_req primitive from the specific SSN to the HP OpenCall SS7 SCCP.
A Subsystem Out of Service Request (SOR) message is sent to the backup
subsystem. If the backup subsystem is available, a Subsystem Out of Service Grant
(SOG) message is returned, thus canceling the T(Coord. chg.) timer.
SSP messages are broadcast, and T(ignore SST) timer is started. All SST messages
are ignored until T(ignore SST) expires or the requesting subsystem indicates via an
sccp_state_req primitive that it is out of service.
An sccp_coord_conf primitive notifies the application that withdrawal has been
granted and that the requested subsystem is out of service.

Chapter 5

163

Using the SCCP API


Replicated Subsystems
Figure 5-20

164

Successful Withdrawal of a Replicated Subsystem

Chapter 5

Using the SCCP API


Replicated Subsystems

Unavailable Backup Subsystem


If a backup subsystem is not available, then an SOG is not returned by the backup
subsystem. An sccp_coord_conf primitive is passed to the application to inform
it that a subsystems request for withdrawal has been denied
(SC_denied_withdrawal).
Figure 5-21

Chapter 5

Refused Withdrawal of a Replicated Subsystem

165

Using the SCCP API


Replicated Subsystems

No Peer Point Code Configured


When there is no backup subsystem for a requesting subsystem, the
sccp_coord_req is handled locally as a graceful withdrawal.
SSP messages are broadcast, and all Subsystem Status Test (SST) messages are
ignored until the T(Ignore SST) timer expires or the requesting subsystem indicates
via a sccp_state_req primitive that it is out of service.
A sccp_coord_conf primitive notifies the application that no backup system is
configured for its subsystem and the requested subsystem is out of service.
Figure 5-22

166

Graceful Withdrawal of a Replicated Subsystem

Chapter 5

Using the SCCP API


SCCP Tutorial Programs

SCCP Tutorial Programs


Two tutorials (that is, example programs) named SccpClient and SccpServer
are provided with HP OpenCall SS7.
The source code is in the /opt/OC/tutorials/SS7 directory.

CAUTION

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

First, you must compile the two programs using the command cc_sccp. This
compiles both programs at the same time.
Then, you can run the programs on the client and server. When you run them, you
must provide the following parameters on the command line, according to the
configuration.

server and client point code

server and client sub system number

The programs SccpClient and SccpServer must run at the same time on two
separate SS7 stacks..
The names of the executables are SccpClient_32_xxx and
SccpServer_32_xxx (where xxx=AAA, ABB, WBB, or WAA).
To run SccpClient on the client using SSN 10, enter:
SccpClient_32_AAA SS7_Stack_36 36 35 -o10 -r10

To run SccpServer on the server using SSN 10, enter:


SccpServer_32_AAA SS7_Stack_35 35 -o10

SccpClient.c
The client process emulates a database request generator. It generates a random
phone number and sends an SS7 message. This process then receives an SS7
message containing a phone number resolved with a user name from the server
process SccpServer.

Chapter 5

167

Using the SCCP API


SCCP Tutorial Programs

SccpServer.c
This program is the server process. It receives requests for phone number resolution
from the client SccpClient, and finds in its directory list a user name associated
with the phone number. Then an SS7 message is returned to the client with a phone
number and its associated user name.
To run this program, you must provide an SS7 classname.

168

Chapter 5

Using the SCCP API


SCCP Tutorial Programs

Chapter 5

169

Using the SCCP API


SCCP Tutorial Programs

170

Chapter 5

Using the TCAP API


This chapter describes the TCAP API and the functions that the application can use
to establish and maintain TCAP dialogues with a remote TCAP user.

Chapter 6

171

Using the TCAP API


Overview

Overview
Chapter Organization
This chapter is organized in the following way:

General Description of TCAP

Features of the HP OpenCall SS7 TCAP

How to use the TCAP API


Creating and scheduling TCAP stack connections
Component Sublayer
Transaction Sublayer
Closing TCAP stack connections

Management guidelines

API Functions
In release 3.1 of HP OpenCall SS7, the API function calls for previous releases that
use the TC_function (or TL_function) call syntax are obsolete. Whenever a
TCX_function (or TLX_function) exists, you must use it instead of the equivalent
TC_function (or TL_function). For example, you must use TCX_open() instead of
TC_open(), and TLX_send() instead of TL_send(), etc.
These functions are listed in Table 6-1, Obsolete API Functions.
Table 6-1

Obsolete API Functions

Obsolete Function
(Not Supported in Release 3.1)

172

Function To Be Used

TC_close()

TCX_close()

TC_open()

TCX_open()

TC_recv()

TCX_recv()

TC_select_mask()

TCX_select_mask()

Chapter 6

Using the TCAP API


Overview
Table 6-1

Obsolete API Functions (Continued)

Obsolete Function
(Not Supported in Release 3.1)

Function To Be Used

TC_send()

TCX_send()

TL_recv()

TLX_recv()

TL_send()

TLX_send()

Migration
To migrate to the recommended functions, modify the application to take the
following into account.

Include the TCAP_ext.h include file

Replace the TC_ function calls by the TCX_ versions listed in Table 6-1,
Obsolete API Functions.

Use TCX_alloc_buffer() to determine message length.

Use TCX_alloc_component() to allocate components instead of


TC_control().

Select flag ANSI or ITU-T.

Using the TCAP API Shared Library


The TCAP API is available as a shared library.
The following is an example of a compile/link line:
gcc -fexceptions -pthread -D_GNU_SOURCE -Wall -I/opt/OC/include -L/opt/OC/lib
-o TcapClient TcapClient.c -lSS7utilXXX

where XXX = WBB, AAA, WAA, or ABB.

Chapter 6

173

Using the TCAP API


General Description of TCAP

General Description of TCAP


TCAP provides functions for the exchange of non-circuit related information
between remote entities and distributed applications. To perform these objectives
TCAP contains two sublayers: the component sublayer and the transaction
sublayer.

Component Sublayer
The component sublayer receives information from an application containing the
primitives and parameters necessary to invoke an operation or request the services
from another entity.

Transaction Sublayer
The transaction sublayer provides the information necessary for SCCP to route the
component information to its destination.

174

Chapter 6

Using the TCAP API


General Description of TCAP
Figure 6-1

Sublayers of TCAP

User application

TCAP
API

ISUP
& TUP
APIs

SCCP
API
MTP3/
M3UA
API

AG API

OA & M
APIs

TCAP
Component
Sublayer
Transaction
Sublayer

AMD shared
Sublayer

SCCP

Chapter 6

MTP level 3

M3UA

MTP level 2

SCTP

MTP level 1

IP

175

Using the TCAP API


General Description of TCAP

No Component Layer Option


The HP OpenCall SS7 platform provides a bypass to the TCAP component-layer.
User applications can use their preferred ASN1 compiler, and use only the TCAP
transaction layer.
The TCAP layer then acts as a simple transport mechanism for a Local or Remote
API.

176

Chapter 6

Using the TCAP API


Types of TCAP Users

Types of TCAP Users


TCAP applications can interface the transaction sublayer either indirectly, via the
component sublayer as a TC-user, or directly via the transaction sublayer as a
TR-user.
Figure 6-2

TCAP Terms

Component
A component consists either of a request to perform an operation, or a reply.
Components are passed between an application and the component sublayer. Several
components may be transmitted in a single TCAP message to a peer application.

Chapter 6

177

Using the TCAP API


Types of TCAP Users

Dialogue
The successive exchange of components between two TC-users is known as a
dialogue. The component sublayer provides dialogue facilities allowing several
dialogues to run concurrently between two remote TC-users.
A dialogue can also be used for the transfer and negotiation of the application
context, and the transparent exchange of user information between two remote
ITU-T White Book TC-users.

Transaction
The setup of an end-to-end connection by the transaction sublayer on behalf of the
TR-users is known as a transaction. The transaction sublayer provides the capability
to exchange user data between TR-users. It also allows the exchange transaction
messages between peer TR-layer entities by means of the Network Service Part
(NSP).

TCAP Messages
The TCAP message format consists of three parts:

Transaction portion
The transaction portion contains protocol control information for the
transaction sublayer.

Dialogue portion (optional)


The dialogue portion is concerned with the application context and optionally,
user information. This portion is only present in ITU-T White Book TCAP
messages.

Component portion
The component portion contains information about individual operations and
their responses to operators.

178

Chapter 6

Using the TCAP API


Types of TCAP Users
Figure 6-3

TCAP Message Structure

Message Length
The TCAP and SCCP message length is expandable to 2,000 bytes if the extended
TCAP API or SCCP API is used.

Addressing
In an SS7 environment using a connectionless network service, TCAP uses SCCP
addressing.

Chapter 6

179

Using the TCAP API


The HP OpenCall SS7 TCAP API

The HP OpenCall SS7 TCAP API


The available TCAP versions include:

ANSI 90

ITU-T Blue Book (1988)

ITU-T White Book (1992)

The HP OpenCall SS7 TCAP API provides:

The TCAP API enables you to build messages of up to 2000 bytes in length.
You must allocate the buffer and component structure. This functionality is
available in ANSI and ITU-T.

Component handling and function calls. TCX_ function calls provide better
control of processes. Many commands handled by invoking the
TCX_control() function are now function calls in their own right, although
TCX_control() calls will still work.

TCAP connection takeover without loss of traffic. The application can have 2
connections to TCAP in an active/standby configuration. They can be set so
that if the active connection fails, the standby connection will take the traffic.
This provides the possibility of software redundancy, having one application
ready to take over the traffic if the active application connection fails.

Hybrid Stacks
HP OpenCall SS7 ITU-T White Book TCAP connects with ANSI SCCP, thus
providing ANSI and ITU-T application access to the SS7 network.
Connections for applications using the SCCP ITU-T White Book will be refused, as
shown in Figure 6-4, Hybrid stack: Application Connection.

180

Chapter 6

Using the TCAP API


The HP OpenCall SS7 TCAP API
Figure 6-4

Hybrid stack: Application Connection

General restriction - The only restriction imposed on ITU-T White Book TCAP applications using a
use of Global Title
hybrid stack is the use of the Global Title. Only types 1 and 2 of the Global Title are
supported, types 3 and 4 are not recognized by ANSI SCCP.

Reverse Hybrid Stacks


HP OpenCall SS7 also provides TCAP ANSI that can connect to ITU-T SCCP Blue
Book (ABB). It is called the Reverse Hybrid Stack.
Connections for applications using the SCCP ANSI will be refused, as shown in
Figure 6-5, Reverse Hybrid Stack: Application Connection.

Chapter 6

181

Using the TCAP API


The HP OpenCall SS7 TCAP API
Figure 6-5

Reverse Hybrid Stack: Application Connection

Dialogue Portion
A TCAP application can negotiate the Application Context or transparently transfer
user data by using the Dialogue Portion as described in ITU-T White Book TCAP.
ITU-T Blue Book TCAP applications are also supported by the White Book TCAP
if the Dialogue Portion is not included in any dialogue handling primitives.

Non-disruptive Service Update


Access to TCAP can be outgoing only, thus allowing a TCAP user to initiate
transactions without accepting incoming transactions.
With this feature, a TCAP user can terminate its access to TCAP and update its
service, without any transactions with a remote TCAP user being aborted or lost.

Direct Access to the Transaction Sublayer


The TCAP API allows a TCAP user to access the transaction sublayer either
indirectly, by using the component sublayer mechanisms, or directly, bypassing the
component sublayer.

182

Chapter 6

Using the TCAP API


The HP OpenCall SS7 TCAP API
With direct access to the transaction sublayer, the TCAP user can use an ASN.1
compiler to encode and decode non-standard components, operations and
parameters.

Message Priority
You can set the priority of the outgoing messages. If the MTP level 3 becomes
congested, it will discard the messages with the lowest priority and keep those with
the highest priority. This is set in the TCAP parameter tcx_importance. See
SCCP Service Quality Structure on page 222.
Messages with priority 0 will be discarded at SCCP level if there is remote SP
congestion. If the return option is set, a UDTS with the cause of network congestion
is returned to the initiator of the message. For other priorities (1 or 2) the messages
are given to MTP3 which is responsible for discarding them according to the level
of congestion.
The same rule applies to messages coming from the network that must be relayed by
SCCP after a translation.

NOTE

SCCP management messages (SSA, SSP, SST, SOR, SOG) have a default priority
of 0. This value can be changed via the SetMgtMsgPriority parameter. Use the
cfgSccp command (for a description, see the man page). See also the
HP OpenCall SS7 Operations Guide.

Receive Mechanism, To improve throughput the TCAP API stores incoming messages from the SS7 stack
Buffering and Test
in a buffer. A more_messages parameter is set during the TCX_recv() call to
indicate the number of TCAP messages that are still waiting to be received. These
Message
messages are received by the user one by one with a TCX_recv() call. Because of
this:

The select() call (used in conjunction with TCX_select_mask) will


trigger only once for several TCAP messages grouped in the same packet.

One TCX_recv() gives one message to the user, but several may have been
received from the socket.

The timeout returned by TCX_select_mask(), and used in select(), forces the


user to call TCX_cnx_handler() periodically to serve TCAP connections.
The size of the TCX_recv() buffer can be configured with a TCX_control()
command.

Chapter 6

183

Using the TCAP API


The HP OpenCall SS7 TCAP API

SS7 Stack Switchover


A 2-host cluster contains two host servers and provides highly available SS7
connectivity and functionality (using redundant software and hardware
components). 2-host HP OpenCall SS7 platforms achieve continuous software
availability by replicating and synchronizing an SS7 Stack on each of the two hosts.
If a failure occurs on one of the hosts, the other will take care of the traffic. The
process of moving the activity from one host to the other is known as a switchover.
Controlling the
TCP/IP Flow

The default configuration for the API is to send every TCAP message to the SS7
stack immediately. In some cases it may be necessary to optimize message transfer
between the API and the SS7 stack. This is always done from the SS7 stack to the
API. In the other direction it must be controlled by the user.
When transfer optimization is on, the TCAP API concatenates several TCAP
messages in one buffer. This buffer is sent to the SS7 stack provided one of the
following conditions is met:

The buffer is full

The transit time of the first message in the buffer has been exceeded

As the API does not use any process signals, in order to fulfil the second condition,
the API must be called regularly by the user process to check if the transit time has
been exceeded. The call that should be used is the TCX_cnx_handler call. If there
is nothing to send or receive, the user may also call TCX_control with
OUT_BUFFER_FLUSH_COND.
The command OUT_BUFFER_FLUSH forces the API to send the buffer contents
whether the above conditions are satisfied or not.
The transit time for each message is computed depending on the average load at the
time when the message is put in the buffer. It varies between two limits, which can
be set by the LOW_TRANSIT_TIME and HIGH_TRANSIT_TIME controls.
The OUT_IPC_BUFFER_SIZE command configures the size of the socket internal
buffer (refer to setsockopt command).
Transparent SS7
Stack Replication

184

The replication of the SS7 stack is transparent to all TCAP users. When
TCX_open() is called, the TCAP API automatically establishes an IPC channel
with each SS7 stack. The TCAP API transparently manages these channels and
automatically directs the traffic to the active SS7 stacks. Thus, the TCAP user is
only notified of a failure when both SS7 stacks are unable to provide any service.

Chapter 6

Using the TCAP API


The HP OpenCall SS7 TCAP API
Figure 6-6

Transparent SS7 Stack Replication

Notification

If one of the active SS7 Stacks handling the traffic fails, all the transactions being
handled by this stack are aborted, and the TCAP users are notified through a
TC_P_ABORT primitive for each transaction lost. The TCAP user must reset its
local timers and state-machines.

Simultaneous Access by Multiple TCAP Users


Multiple TCAP users can simultaneously access TCAP using the same or different
SSNs. When the application opens a TCAP connection to the SS7 stack, the
connection is assigned an SSN.
If multiple TCAP users use the same SSN to access TCAP, by default all incoming
traffic is shared between the TCAP users using a round-robin algorithm. However, if
the TCAP Application Message Dispatcher feature is used, incoming messages are
shared between TCAP users using a customer-supplied algorithm (see Chapter 7,
Using the TCAP Application Message Dispatcher,, and the HP OpenCall SS7
Welcome Guide).
It is possible to assign multiple SSNs to a single TCAP user or multiple TCAP users
on a single or multiple systems.
Single TCAP User

Chapter 6

A single TCAP user can establish multiple TCAP stack connections. Each
connection can be given identical or different SSN values.
185

Using the TCAP API


The HP OpenCall SS7 TCAP API
Figure 6-7, Single TCAP User with Multiple TCAP Stack Connections, shows how
a single TCAP user, using TCX_open(), can open two TCAP stack connections
identified as cnx_id1 and cnx_id2. cnx_id1 is assigned the SSN value SSNy,
and cnx_id2 is assigned the SSN value SSNx.
Thus, all dialogues/transactions destined for SSNx and SSNy are received by the
same TCAP user.
Figure 6-7

Single TCAP User with Multiple TCAP Stack Connections

Multiple TCAP
Users

If several TCAP users are connected with the same SSN on the same stack, by
default, all incoming transactions/dialogues are shared between them using a
round-robin algorithm. All incoming TC_BEGINs are distributed statistically. All
other transaction primitives are sent to the user handling the transaction.
The maximum number of connections is 32, with up to 8 SSNs.
Figure 6-8, Multiple TCAP Users on the SS7 Stack, shows two TCAP users
connected the SS7 Stack. Each stack connection is assigned an SSN value. Both
TCAP USER1 and TCAP USER2 have 3 stack connections each. Each stack
connection is assigned an SSN value.
All the stack connections belonging to TCAP USER2 have the same SSN values as
the stack connections belonging to TCAP USER1. Hence, all transactions/dialogues
routed to SSNy, SSNx and SSNz are shared between TCAP USER1 and TCAP
USER2.

186

Chapter 6

Using the TCAP API


The HP OpenCall SS7 TCAP API
Figure 6-8

Chapter 6

Multiple TCAP Users on the SS7 Stack

187

Using the TCAP API


The HP OpenCall SS7 TCAP API

Take-over of TCAP Connections


The application can make active a second connection with the same
application_id and instance_id as an already open/active connection. When
this is done the first connection no longer accepts new incoming dialogues but
continues to process dialogues in progress. In the following figure, two sets of
replicate connections are shown, each set having the same SSN.
Figure 6-9

open/active, open/active and open/non-active, open/non-active

Active and
non-active

The state of active and non-active is the responsibility of two identifiers,


instance_id and application_id. The open/active connections accept traffic.
The open/non-active connections have the same application_id and
instance_id as the open/active connections but do not accept any new incoming
dialogues. The application needs to make active the non-active connections in order
for them to begin processing traffic.
If a second connection was previously configured, TCAP connection take-over
occurs automatically if the first connection goes down. TCAP connection take-over
can also occur on the specific request of an API. In this case the first connection no
longer accepts new traffic but continues to process dialogs in progress. All new
traffic uses the second connection.

application_id

The application_id is a user-application identifier.


See Creating TCAP Stack Connections Using TCX_open() on page 196.

188

Chapter 6

Using the TCAP API


The HP OpenCall SS7 TCAP API
Load sharing is possible by setting up several connections with the same
application_id and different instance_id and by distributing in-coming
traffic over these connections. This assumes that all instances of an
application_id are connected on the same SSN.
instance_id

The instance_id is defined within an application_id, identifying an instance


of the application, and is exclusive.
See Creating TCAP Stack Connections Using TCX_open() on page 196.

Open/active to
open/non-active

When the connection in the open/active mode goes to open/non-active two main
events occur:
1. The once open/active connection, now open/non-active, refuses any further
TC_BEGIN() primitives, but it still accepts all other primitives. This allows it
to refuse any new transactions while at the same time allowing it to complete
any ongoing transactions.
2. The open/non-active connection passes to open/active and it begins to accept
TC_BEGIN() primitives, hence accepting all new traffic that would have gone
to the now non-active connection.

Figure 6-10

Non-active to closed

Chapter 6

open/non-active, open/active and open/active, open/non-active

To close the open/non-active connection you need to call TCX_close. Otherwise


the connection will stay open/non-active. If you want the connection to be
automatically closed, you can set the CloseOnCreate option to YES using the
cfgTcap command (for a description, see the man page).

189

Using the TCAP API


The HP OpenCall SS7 TCAP API
Figure 6-11

closed, open/active and open/active, open/non-active

Using ITU-T White Book TCAP for ITU-T Blue Book


TCAP Applications
To run an ITU-T Blue Book TCAP application using the ITU-T White Book version
of TCAP, you must observe the following conditions:

NOTE

190

The dlg_info_present fields of all tc_primitive structures must be set


to TC_NO.

The address type of the o_address field in tc_primitive must be set to


NO_TC_ADDRESS. This ensures that the option to alter the originating address
will not be used.

The application must be recompiled using -DTCAP_WHITE.

The application must be re-linked using the White Book library, libSS7util.so
library.

Using the ITU-T White Book version of TCAP for ITU-T Blue Book
applications does not guarantee that Blue Book applications will not receive
and understand White Book transactions/dialogues.

Chapter 6

Using the TCAP API


The HP OpenCall SS7 TCAP API

Called and Calling Party Address


You can set the called and calling party address from TCAP by setting parameters in
file sys.<className>_TDx.tcap. You can change the calling address specified
in TC_CONTINUE, TC_END, or TC_U_ABORT when TCAP receives a TC_BEGIN
from the network.
To do this, use the cfgTcap command (for a description, see the man page). See
also the HP OpenCall SS7 Operations Guide.
You can also control what information is stored in the called address by TCAP when
routing on Global Title. It is used only after receiving TC_BEGIN or TC_QUERY. It
does not concern the application; the application will receive the called address
without any modification. This address is reused as the calling address for each
outgoing TCAP message.

Chapter 6

191

Using the TCAP API


How to Use the TCAP API

How to Use the TCAP API


Overview
Several steps are required to give TCAP the primitives and parameters necessary to
invoke an operation, or to request services from another entity. These steps are
outlined here with a brief description, and then the relevant sections are referenced.
Most TCAP calls are defined in the header file TCAP_ext.h.

Creating TCAP Stack Connections


First you must open a connection to the stack. The connection allows the application
to access the TCAP services either as a TC-user or as a TR-user. The application
must ask TCAP to open this connection using TCX_open().
See Creating TCAP Stack Connections Using TCX_open() on page 196.

Scheduling TCAP Stack Connections


Secondly, you must schedule all the connections using the HP OpenCall SS7
scheduling mechanism and the following function calls:

TCX_select_mask()

select()

TCX_cnx_handler()

See Scheduling TCAP Stack Connections on page 200.

If TC-user, Use Invoke and Dialogue ids


If you are a TC-user, the application must use the invoke and dialogue ids to allow
several invocation and dialogues to be simultaneously active.
See Using the Component Sublayer on page 203.
Continue on to Using the Component Sublayer, for TC-users on page 193.

192

Chapter 6

Using the TCAP API


How to Use the TCAP API

If TR-user, then...
If you are a TR-user, the application must manage all memory allocation,
component handling, and transactions.
See Using the Transaction Sublayer on page 237.

Using the Component Sublayer, for TC-users


The following sections only apply to TC-users using the component sublayer of the
TCAP API, unless specified otherwise.

Using the TCAP Component Structure


The TCAP API provides a C structure tcx_component, which builds the
component list so that you can exchange component data between the application
and the TCAP API.
See Using the TCAP Component Structure on page 208.

Allocate, Fill, Allocate


To create the components, you must allocate a component list structure, fill it with
user data, and allocate a buffer. Use TCX_alloc_component() to allocate the
component list, and TCX_alloc_buffer to allocate the buffer.
See Allocating Components to a List on page 212.

Storing the Components


The application passes components to the component sublayer of the TCAP API
library individually using the TCX_put_component().
To create a components list with one component, you must make a component list of
one using TCX_alloc_component().
See Storing the Components on page 206.

Create a Dialogue Primitive


The application must now create a dialogue primitive to request the transmission of
the components to the remote TC-user. The purpose of the dialogue primitive is to
request or indicate the dialogue handling functions supported by the component
sublayer.

Chapter 6

193

Using the TCAP API


How to Use the TCAP API
See Dialogue Handling on page 219.

Sending Components and the Dialogue Primitive


TCX_send() assembles and transmits TCAP messages to the transaction sublayer.

The dialogue primitive comes from the application and the encoded components
from the component sublayer of the TCAP API library, then both the primitive and
encoded components go to the transaction sublayer.
See Sending Components via the Component Sublayer Using TCX_send() on
page 230.

Releasing Buffers and Components


There are three commands to use to release component structures and buffers:

TCX_free_components()

TCX_free_buffer()

TCX_flush_components()

See Releasing Buffers and Components on page 217.

194

Chapter 6

Using the TCAP API


How to Use the TCAP API

Receiving TCAP Components


The application must use a TC-user connection to receive TCAP messages. This
again involves creating and scheduling a TCAP stack connection. Then the
application must use TCX_recv().
See Creating TCAP Stack Connections Using TCX_open() on page 196.
See Receiving Components from the Component Sublayer Using TCX_recv() on
page 233.
Extracting
components

After receiving a TCAP message with TXC_recv(), the components are decoded
but they remain in the internal API component list. The application must extract
these components individually from the component sublayer using
TCX_get_component().
See Extracting Components Using TCX_get_component() on page 236.

Closing TCAP Stack Connections for TC-users and TR-users


Closing, and thus destroying a TCAP stack connection, must only be done when you
are certain that the application will not use the connections again.

NOTE

Only close a TCAP stack connection when you are sure the application no longer
needs it.

If a connection is repeatedly opened and closed, the application will place high
overhead on the TCAP API mechanism.
A TCAP service is terminated when the application closes a stack connection using
TCX_close(). All the entities associated with this stack connection are also
closed, and all calls to TCX_send(), TLX_send(), TCX_recv(), or
TLX_recv() will be refused.
See Closing TCAP Stack Connections Using TCX_close() on page 240.

Chapter 6

195

Using the TCAP API


Creating TCAP Stack Connections Using TCX_open()

Creating TCAP Stack Connections Using TCX_open()


The TCAP API creates stack connections on behalf of the application. The
application can request the services of the component and/or the transaction
sublayers via the connections created by TCX_open().
TCX_open() creates a new TCAP access point (stack connections), allowing the
application to access the TCAP services either as a TC-user or a TR-user. If
successful, TCX_open() returns a connection Identifier (tcx_cnxid) that must be
used in all subsequent calls related to the stack connection.

To enable multiple connections, you will also have to set some of the following
parameters using the cfgTcap command (for a description, see the man page):
Table 6-2

Multiple Connection Configuration

If you...

...then set the


parameter...

...to...

do not want this functionality

autoSwitch

NO (default)

want the secondary connection to become active if the


primary fails
want the primary connection to be closed when the secondary
connection becomes active

YES (default)
closeOnEnable

want the primary connection to become standby when the


secondary connection becomes active
want to close the existing primary connection when a new
primary connection is created
want to make the existing primary connection secondary
when a new primary connection is created

YES (default)
NO (default)

closeOnCreate

YES (default)
NO (default)

When a connection becomes secondary, it receives an MGT primitive with a


DESACTIVATE stats type even if the connection is closed later.
For more details about syntax, parameters, and return values, see the TCX_open()
man page.

196

Chapter 6

Using the TCAP API


Creating TCAP Stack Connections Using TCX_open()

Example: Creating a TC-user Connection


This example is a code fragment that shows how to make a TC-user connection.
/* Example of TCX_open (): */
#include <TCAP_ext.h>
#include <TCAP_errors.h>
tcx_application_info AppliInfo;
char ErrorMessage[100];
struct timeval
timeoutValue;
timeoutValue=1; /* value in seconds */
AppliInfo.mode= TCX_CNX_OVERWRITE ;
AppliInfo.application_id= TCAP_APPLICATION_ID;
AppliInfo.instance_id = InstanceId; // User application identification
CnxId =

TCX_open(ClassName,
TCX_TCAP_STD,
OSSN,
TC_YES,
TC_YES,
&AppliInfo,
TCX_SCCP_SERVICE_ITU_WB,
&timeoutValue);

/*Error Handling for TCX_open () */


if (CnxId == -1)
{
/* An error has occured during TCX_open */
/* You should consult tc_errno to know the reason */
switch (tc_errno)
{
case TCE_ILLEGAL_VALUE :
sprintf(ErrorMessage,TCX_OPEN error : You have used an illegal value
(%d),tc_errno);
break;
case TCE_NO_CONFIG :
sprintf(ErrorMessage,TCX_OPEN error : global.conf not be accessed (%d),
tc_errno);
break;
case TCE_BAD_CONFIG :

Chapter 6

197

Using the TCAP API


Creating TCAP Stack Connections Using TCX_open()
sprintf(ErrorMessage,TCX_OPEN error : global.conf could not be parsed for %s
(%d), ClassName, tc_errno);
break;
case TCE_MEMORY_ERROR :
sprintf(ErrorMessage,TCX_OPEN error : The application could not allocate
memory
break;
case TCE_CONNECT_INIT :
sprintf(ErrorMessage,TCX_OPEN error : A connection to SS7 stack cannot be
established (%d), tc_errno);
break;
case TCE_MAX_USERS :
sprintf(ErrorMessage,TCX_OPEN error : The maximum number of TCAP users has
been exceeded (%d), tc_errno);
break;
<parameter>OR</parameter>
sprintf(ErrorMessage,TCX_OPEN error : The maximum number of open connections
from the
application has been exceeded (%d), tc_errno);
break;
case TCE_INVALID_SSN :
sprintf(ErrorMessage,TCX_OPEN error : The SSN provided for this user is not
with in
the correct range (%d), tc_errno);
break;
case TCE_CNX_ID :
sprintf(ErrorMessage,TCX_OPEN error : The returned cnxId is not
available. Close this cnxId and try to reopen it (%d), tc_errno);
break;
case TCE_API_BUSY :
sprintf(ErrorMessage,TCX_OPEN error : The API is looking for a backup
connection.
Retry later (%d), tc_errno);
break;
case TCE_NO_SSN :

198

Chapter 6

Using the TCAP API


Creating TCAP Stack Connections Using TCX_open()
sprintf(ErrorMessage,TCX_OPEN error : The given SSN has not been
configured(%d), tc_errno);
break;
case TCE_NO_SERVICE :
sprintf(ErrorMessage,TCX_OPEN error : The required service doesnt
exist (%d), tc_errno);
break;
case TCE_BAD_VERSION :
sprintf(ErrorMessage,TCX_OPEN error : API version is not supported by
SS7 stack (%d), tc_errno);
break;
default :
sprintf(ErrorMessage,TCX_OPEN error : TCX_open returned an unknown error value
(%d), tc_errno);
break;
} // End of switch()
fprintf(stderr,%s\n, ErrorMessage);
}
else {
/* Connection is OK */
......
}

Chapter 6

199

Using the TCAP API


Scheduling TCAP Stack Connections

Scheduling TCAP Stack Connections


As described in Scheduling SS7 Connections on page 65, you must schedule all
the stack connections using the HP OpenCall SS7 scheduling mechanism.
Scheduling the TCAP stack connections is achieved by using:

NOTE

TCX_select_mask()

select()

TCX_cnx_handler()

The read, write and exception masks must be used with all three commands.

TCX_select_mask()
This pre-select function is used for all TCAP stack connections. It takes the file
descriptor masks created by the application, and sets them to include the file
descriptors used by the API to manage the TCAP stack connections. The application
must call this function before calling select().
For details about syntax, parameters, and return values, see the
TCX_select_mask() man page.

select()
The select() function is used for all HP OpenCall SS7 scheduling. It modifies
the read, write and exception masks created by TCX_select_mask() to indicate
which sockets are to be used.

TCX_cnx_handler()
It is mandatory to call TCX_cnx_handler after every use of select().
TCX_cnx_handler() requests the API to process the masks returned by
select() and manage the internal mechanisms. An array of stack connection
identifiers is used to identify the stack connections that have messages waiting to be
received by the application.
Activity on the connection is flagged when one of the following events occurs:

200

Chapter 6

Using the TCAP API


Scheduling TCAP Stack Connections

A message is received by the SS7 stack.

An L_cancel is generated by the API and must be extracted by the receive


function call.

A closed connection is found (a send or receive call returns an error). The


application should call the close function to deallocate API resources.

A connection goes from busy state (API_BUSY) to normal state. The


application can resume processing (send and receive calls no longer return an
error).

For details about syntax, parameters, and return values, see the
TCX_cnx_handler() man page.

Example: Scheduling a TCAP Stack Connection


This is a code fragment of how to schedule a TCAP stack connection.
/* Example of scheduling stack connection: */
while( 1 ){
/* init select bit masks & timer in each loop */
FD_ZERO(&readMask);
FD_ZERO(&writeMask);
FD_ZERO(&exceptMask);
tmout.tv_sec = 2;
tmout.tv_usec = 0;
time = &tmout;
/*
*
HP OC SS7 select phase
*/
numFd = TCX_select_mask(0, &readMask, &writeMask, &exceptMask, &time);
n = select(numFd, &readMask, &writeMask, &exceptMask, time);
if ( n < 0 )
{
/* select error Mgmt */
switch(errno)
{
case EINTR:
/* note that select exit with EINTR if a sigalarm is received */
/* continue processing */
break;
default:
printf (Error during select, reason: %d\n, errno );
exit (-1);

Chapter 6

201

Using the TCAP API


Scheduling TCAP Stack Connections
}
}
/*
*
end of HP OC SS7 select phase
*/
num_cnx = MAX_FD;
cnx_active[0] = -1;
TCX_cnx_handler(n, &readMask, &writeMask, &exceptMask, &num_cnx, cnx_active);
/*
*
end of HP OC SS7 select phase
*/
if ( (num_cnx > 0) && ( cnx_active[0] == cnxId) )
{
more = 1; p_type = 0; prov_id = 0;
/* Receive all possible messages arrived */
..............

202

Chapter 6

Using the TCAP API


Using the Component Sublayer

Using the Component Sublayer


The application exchanges components with the TCAP component sublayer via a
scheduled TC-user connection. The component sublayer manages the association
between operations and results.

Invoke ID
The request to perform a remote operation is called an invocation. It is identified by
an invoke ID which allows several invocations of the same or different operations to
be simultaneously active.
Only one reply is sent to an operation. A reply carries an indication of success or
failure of the operation, and the operations invoke ID.

Dialogue ID
The component sublayer provides dialogue facilities which allow several dialogues
to run concurrently between two TC-users. Two types of facilities are provided:

Unstructured dialogues
The application can send components without forming an explicit association
with the end TC-user. No replies are returned.

Structured dialogues
The application can form an explicit association with a TC-user using a
structured dialogue. A structured dialogue allows the application to run several
dialogues concurrently where each dialogue is identified by a dialogue ID.

Invocation and Dialogue Handling


Figure 6-12, Invocation and Dialogue Handling, describes how multiple invocations
of the same operation are managed using invoke ids. This figure also shows how a
dialogue id locally identifies a dialogue between two TC-users.

Chapter 6

203

Using the TCAP API


Using the Component Sublayer
Figure 6-12

Invocation and Dialogue Handling

TC-USER1 requests the remote invocation of an operation (op1) by TC-USER3. The invocation is identified by the
invoke id w, and the dialogue between TC-USER1 and TC-USER3 is locally identified with the dialogue id z1.

A TCAP BEGIN message containing the invoke id w and the dialogue id z1 is sent to TC-USER3.

TC-USER3 receives an invocation component with invoke id w. TC-USER3 locally identifies its dialogue with
TC-USER1 with the dialogue id z2.

After TC-USER3 performs the operation op1 as requested by TC-USER1, the reply is returned to TC-USER1 in a result
component identified by the invoke id w.

A TCAP END message containing the result component and TC-USER1 dialogue id z1 is sent to TC-USER1.

204

Chapter 6

Using the TCAP API


Using the Component Sublayer

TC-USER1 receives a reply from TC-USER3. Invoke id w matches the reply with the invocation. The dialogue id z1
indicates that the result component came from TC-USER3.

TC-USER1 simultaneously requests TC-USER2 to perform operation op1. This invocation is identified by the invoke id
x, and TC-USER1 locally identifies its dialogue with TC-USER2 with the dialogue id y1.

A TCAP BEGIN message containing the invoke id x and the local dialogue id y1 is sent to TC-USER2.

TC-USER2 receives an invocation component with invoke id x. TC-USER2 locally identifies its dialogue with
TC-USER1 with the dialogue id y2.

10

After TC-USER2 performs the operation op1 as requested by TC-USER1, the reply is returned to TC-USER1 in a result
component. The result component is identified by the invoke id x.

11

A TCAP END message containing the result component and TC-USER1s dialogue id y1 is sent to TC-USER1.

12

TC-USER1 receives TC-USER2s reply. Invoke id x matches the reply with the corresponding invocation. The dialogue
id y1 indicates that the result component came from TC-USER2.

Chapter 6

205

Using the TCAP API


Creating a Component

Creating a Component
To create a component, you must

allocate the component list structure and number of components you want to
put in the list by using TCX_alloc_component() (one component makes a
list of one)

build the component structure by using tcx_component

allocate the buffer to contain the data by using TCX_alloc_buffer()

fill the user data in the allocated buffer

Now you need to store the components in the TCAP API Library.

Storing the Components


Before calling TCX_send() to encode and transmit the components to the
transaction sublayer, the components must be stored one by one in the TCAP library
using TCX_put_component(). Error checking is done each time
TCX_put_component() is used and any component causing an error can be
readily identified.
When you use TCX_send(), all stored components are encoded then the dialogue
primitive and encoded components are sent to the transaction sublayer.

206

Chapter 6

Using the TCAP API


Creating a Component
Figure 6-13

Chapter 6

Storing the Components within the TCAP library

207

Using the TCAP API


Using the TCAP Component Structure

Using the TCAP Component Structure


The TCAP API provides a C structure, tcx_component, which builds the
component list so that you can exchange component data between the application
and the TCAP API.

tcx_component
Components consist of a type and any parameters required to be used when
invoking a specific operation or replying to an operation.
The tcx_component structure is defined in the header file TCAP_ext.h.

208

Chapter 6

Using the TCAP API


Using the TCAP Component Structure

tc_component_type
Most component types are common to both ITU-T and ANSI defined components.
The following table lists the component types that must be used to create a
component. The table also identifies whether the component type is supported by
ITU-T and/or ANSI.
Table 6-3

TCAP Component Types

Component
Type

Meaning

TC_INVOKE

ANSI

ITU-T

Invocation of an operation.

TC_INVOKE_L

Invocation of an operation. Component list is complete.

TC_INVOKE_NL

Invocation of an operation. More components expected.

TC_RESULT_L

Last part of a successful segmented result.

TC_RESULT_NL

Segment of a successful result.

TC_U_ERROR

Unsuccessful result, the invoked operation could not be


executed by the remote TC-user.

TC_U_CANCEL

Local cancel.

TC_L_CANCEL

Timeout of associated operation timer.

TC_U_REJECT

Rejection of an invalid component by remote TC-user.

TC_L_REJECT

Rejection of an invalid component by local component sublayer.

TC_R_REJECT

Rejection of an invalid component by remote component


sublayer.

Chapter 6

209

Using the TCAP API


Using the TCAP Component Structure

Component Type Structure


Although some component types are common to both ANSI and ITU-T TCAP, the
structure of the component type is not identical. When you are creating a TCAP
component you must ensure that at least the mandatory parameters as defined in
Table 6-4, Structure of ANSI and ITU-T Components, contain valid values.
Table 6-4
Component Type

Parameters

Mandatory/Optional

TC_INVOKE

class

mandatory

invoke_id

mandatory

link_id

optional

operation

mandatory

parameter

optional

timeout

mandatory

class

optional

invoke_id

mandatory

correlation_id

optional

operation

mandatory

parameter

optional

timeout

optional

class

optional

invoke_id

mandatory

correlation_id

mandatory

operation

mandatory

parameter

optional

timeout

optional

TC_INVOKE_L

TC_INVOKE_NL

210

Structure of ANSI and ITU-T Components

Chapter 6

Using the TCAP API


Using the TCAP Component Structure
Table 6-4

Structure of ANSI and ITU-T Components (Continued)

Component Type

Parameters

Mandatory/Optional

TC_RESULT_L

invoke_id

mandatory - ITU-T only

correlation_id

mandatory - ANSI only

operation

optional - ITU-T only

parameter

optional

invoke_id

mandatory - ITU-T only

correlation_id

mandatory - ANSI only

operation

optional - ITU-T only

parameter

optional

invoke_id

mandatory - ITU-T only

correlation_id

mandatory - ANSI only

error

mandatory

parameter

optional

TC_U_CANCEL

invoke_id

mandatory - ITU-T only

TC_L_CANCEL

correlation_id

mandatory - ANSI only

TC_U_REJECT

invoke_id

mandatory - ITU-T only

TC_L_REJECT

correlation_id

mandatory - ANSI only

TC_R_REJECT

problem_code

mandatory

parameter

optional

TC_RESULT_NL

TC_U_ERROR

Chapter 6

211

Using the TCAP API


Allocating Components

Allocating Components
After defining the component structure, you must allocate the component, fill in the
user data, and allocate adjoining buffer structure.
The application passes components to the component sublayer individually using
TCX_put_component(). The components are then sent in a single message to the
remote end.
Components in a message are delivered to the remote TC-user in the same order as
they were provided by the application.
All component memory allocation is performed by the TCAP API.

Allocating Components to a List


If you want to pass the components to the component sublayer to have them stored
there, you must take the following steps.
1. Allocate a component list of one using TCX_alloc_component().
2. Allocate one buffer for the one component of data using
TCX_alloc_buffer().
3. Fill in the data.
4. Use TCX_put_component() on each component of the link to send it to the
component sublayer. See Passing a Component to the Component Sublayer
Using TCX_put_component on page 216.
The parameters for TCX_alloc_component() and TCX_alloc_buffer()
follow.

TCX_alloc_component
This function allows you to allocate a number of chained components from the
library.
TCX_alloc_component() is defined in the header file TCAP_ext.h.

For details about syntax, parameters, and return values, see the
TCX_alloc_component() man page.

212

Chapter 6

Using the TCAP API


Allocating Components

TCX_alloc_buffer
This function allows you to allocate a buffer from the library. Buffers are freed with
their encapsulating component structure.
TCX_alloc_buffer() is defined in the header file TCAP_ext.h.

For details about syntax, parameters, and return values, see the
TCX_alloc_buffer() man page.

Example: Allocating One Component and One Buffer


This example is a code fragment for allocating one component and one buffer.
See Example: Filling the Buffer with User Data on page 215 to fill the
components with user information.
/* allocation of one component example*/
tcx_buffer
*Buffer = NULL;
tcx_component *Component;
Error = TCX_alloc_component(&Component, 1); // We want only one component.
/*Error handler*/
if (Error != 0){
switch(tc_errno)
{
case TCE_ILLEGAL_VALUE :
fprintf(stderr,TCX_alloc_component
Error);
break;

ILLEGAL VALUE (error value == %d),

case TCE_MEMORY_ERROR :
fprintf(stderr,TCX_alloc_component No more memory (error value == %d),
Error);
break;
default :
fprintf(stderr,TCX_alloc_component returned an unexpected error value : %d,
Error);
break;
} // end of switch(Error)
......
} // End of if (Error != 0)
else
{

Chapter 6

213

Using the TCAP API


Allocating Components

Error = TCX_alloc_buffer(&Buffer, 1000); // We want a buffer of 1000 bytes


if (Error != 0)
{
switch(tc_errno)
{
case TCE_ILLEGAL_VALUE :
fprintf(stderr,TCX_alloc_component
%d),Error);
break;

ILLEGAL VALUE (error value ==

case TCE_MEMORY_ERROR :
fprintf(stderr,TCX_alloc_component No more memory (error value ==
%d),Error);
break;
default :
fprintf(stderr,TCX_alloc_component: unexpected error value :
%d,Error);
break;
} // end of switch(Error)
......
} // end of if (Error != 0)
memcpy(Buffer->bufferp, bufdata, 500); // copy user datas into component buffer
Buffer->actual_length=500;
with the length
of the datas
Component->parameter= Buffer;
component

// You must update this field

// now, give the address of data buffer to

} // end of else

214

Chapter 6

Using the TCAP API


Allocating Components

Example: Filling the Buffer with User Data


This example is a code fragment of filling buffers with user information.
/*Example of filling up the buffer with user data*/
tcx_component MyComponent;
MyComponent.next_component =NULL; // We are not chaining a list of components
MyComponent.c_type = TC_INVOKE;
MyComponent.op_class = 1;
MyComponent.invoke_id=230; // This value must be < 255 and unique
MyComponent.linked_id =-1;
MyComponent.operation.tag = GLOBAL_TYPE; /* No Action requested */
MyComponent.operation.length = 10;
memset(&MyComponent.operation.datas,0,10);
MyComponent.timer.tv_sec = NO_TIMER; /* We do not use the timer feature */
MyComponent.timer.tv_usec=0;
MyComponent.error.tag = LOCAL_TYPE;
/* No error handler specified */
MyComponent.error.length = MAX_OPERATION_LEN;
memset(&MyComponent.error.datas,0,MAX_OPERATION_LEN);

Chapter 6

215

Using the TCAP API


Allocating Components

Passing a Component to the Component Sublayer


Using TCX_put_component
TCX_put_component() passes a component to the TCAP API internal
component list. This internal component list is sent in a single TCAP message.
TCX_put_component() is defined in the header file TCAP_ext.h.

For details about syntax, parameters, and return values, see the
TCX_put_component() man page.

Advanced Component Management


The wait-for-reject timer is activated when a reply to an invocation is received. It
avoids duplication of an invoke ID for two different operation invocations.
For details about syntax, parameters, and return values, see the TCX_control()
man page.

216

Chapter 6

Using the TCAP API


Releasing Buffers and Components

Releasing Buffers and Components


TCX_free_components and TCX_free_buffer are used to release the
TCX_component structures that are stored in the application.

TCX_free_components ()
TCX_free_components() frees a list of components. The structure of
TCX_free_components() is defined in the header file TCX_ext.h.

For details about syntax, parameters, and return values, see the
TCX_free_components() man page.
If a problem occurs and you get an error return while using
TCX_put_component(), use TCX_free_components to free the components
from the application.
Figure 6-14

Chapter 6

When to Use TCX_free_components ()

217

Using the TCAP API


Releasing Buffers and Components

TCX_flush_components ()
TCX_flush_components() is used to flush TCX_component structures stored
in the component sublayer of the TCAP library. It deletes all waiting components
with a specific user_dialogue_id (uid) and provider_dialogue_id (pid). This function
call is defined in the header file TCAP_ext.h. For details about syntax,
parameters, and return values, see the TCX_flush_components() man page.

If you use TCX_put_component successfully and then TCX_send() and then you
get an error return, use TCX_flush_components() to release the components
from the component layer of the TCAP API library.
Figure 6-15

When to Use TCX_flush_components

TCX_free_buffer()
TCX_free_buffer() frees the buffer allocated by TCX_alloc_buffer(). The
structure of TCX_free_buffer() is defined in the header file TCX_ext.h.

For more details, see the TCX_free_buffer() man page.

218

Chapter 6

Using the TCAP API


Dialogue Handling

Dialogue Handling
Although the application has created and passed components to the component
sublayer, they are not transmitted until requested by the application.
The application must create a dialogue primitive to request transmission of the
components to a peer TC-user. The purpose of the dialogue primitive is to request or
indicate the dialogue handling functions supported by the component sublayer.

tcx_primitive
The application must use the tcx_primitive structure defined in file
TCAP_ext.h.
Table 6-5

Structure of tcx_primitive

Field

Type

Meaning

p_type

tc_primitive_type

See Primitive Types on


page 220

service_quality

tcx_sccp_service_quality

See SCCP Service Quality


Structure on page 222

d_address

tc_address

SCCP destination address for


the TCAP message.

o_address

tc_address

SCCP originating address for


the TCAP message.

user_dialogue_id

unsigned int

This reference integer


identifier must be generated by
the application. See Dialogue
Management on page 242.

provider_dialogue_id

unsigned int

This dialogue reference


identifier is provided by TCAP.
See Dialogue Management
on page 242.

dialog_portion

tc_dialog_portion

See dialogue_portion on
page 226

Chapter 6

219

Using the TCAP API


Dialogue Handling
Table 6-5

Structure of tcx_primitive (Continued)

Field

Type

Meaning

tcx_primitive_option

tcx_primitive_option

See TCX Primitive Options


on page 229.

Primitive Types
Dialogue primitives map onto transaction (TR) primitives with the same generic
name because there is a one-to-one relationship between a dialogue and a
transaction.
Table 6-6, Primitive Types, lists the valid tc_primitive_type values, and if
they are supported by ANSI and/or ITU-T.
Table 6-6

Primitive Types

Primitive Name

Meaning

ANSI

ITU-T

TC_UNI

Indicates an unstructured dialogue.

TC_BEGIN

Indicates the beginning of a structured dialogue.

TC_CONTINUE

Indicates the continuation of a dialogue. This


primitive must come after a TC_BEGIN or a previous
TC_CONTINUE.

TC_END

Indicates the end of a dialogue.

TC_NOTICE

Informs the TC-user that the Network Service


Provider has been unable to provide the requested
service.

TC_U_ABORT

Allows a TC-user to abort a dialogue without


transmitting any pending components.

TC_P_ABORT

Informs the TC-user that the dialogue has been


terminated by the transaction sublayer. Pending
components are not transmitted.

TC_QUERY_W_PERM

Starts a dialogue, informing the remote TC-user that it


can end the dialogue.

220

Chapter 6

Using the TCAP API


Dialogue Handling
Table 6-6

Primitive Types (Continued)

Primitive Name

Meaning

ANSI

ITU-T

TC_QUERY_WO_PERM

Starts a dialogue, informing the remote TC-user that it


cannot end the dialogue.

TC_RESPONSE

Indicates the end of a dialogue.

TC_CONV_W_PERM

Indicates the continuation of a dialogue, and that the


remote TC-user can end the dialogue.

TC_CONV_WO_PERM

Indicates the continuation of a dialogue, and that the


remote TC-user cannot end the dialogue.

SCCP_USER_STATUS

Requests or indicates the status of a remote SCCP


subsystem.

SCCP_PC_STATUS

Indicates the status of a remote SCCP point code.

SCCP_N_COORD

Requests or indicates that a subsystem withdrawal is


initiated.

SCCP_N_COORD_RES

Requests or indicates that a subsystem withdrawal is


granted.

NO_PRIMITIVE

Returns local component indication: L_CANCEL.

MGT

Returns management and statistic information about


TCAP.

SWITCH_STARTED

Indicates that the SS7 stack has begun its switchover


procedure.

SWITCH_DONE

Indicates that the SS7 stack switchover has finished.

Chapter 6

221

Using the TCAP API


Dialogue Handling

SCCP Service Quality Structure


This table describes the parameters of the service quality structure.
Table 6-7

SCCP Service Quality Structure

Type

Field

Meaning

TC_BOOL

use_default_values

This parameter
be set by you.
TC_YES: use default quality parameters
for ALL of the following parameters in this
table.
TC_NO: You must declare all of the
following parameters.

TC_BOOL

sccp_return_option

TC_YES: The stack sends TC_notice()


messages back to the application when
there are problems.
TC_NO: The stack does not send
TC_notice () messages back to the
application in case of problems.
Default:TC_NO

TC_BOOL

sccp_use_extended_data

TC_YES: Forces the use of SCCP XUDT


protocol messages for all TCAP
transactions.
TC_NO: SCCP only uses an XUDT
protocol message to transport TCAP
transactions if data cannot fit into a UDT
message.
Default: TC_NO

222

Chapter 6

Using the TCAP API


Dialogue Handling
Table 6-7

SCCP Service Quality Structure (Continued)

Type

Field

Meaning

tcx_sccp_class

sccp_service_class

TCX_SCCP_CLASS0: No guarantee of
sequential delivery of TCAP messages.
TCX_SCCP_CLASS1: Sequential delivery
of TCAP messages guaranteed. Must use
sccp_sequence_control values for
different TCAP transactions to prevent all
TCAP messages going over the same SS7
link.
Default: TCX_SCCP_CLASS0

tcx_importance

sccp_importance

Determines the priority level for outgoing


messages. If congestion occurs, messages
with the lowest priority will be discarded
first.
Set to
TCX_IMPORTANCE_LOW (0)
TCX_IMPORTANCE_MEDIUM (1)
TCX_IMPORTANCE_HIGH (2)
Default: TCX_IMPORTANCE_LOW
If the value of sccp_importance is out
of range in TCX_send(), its value is reset to
TCX_IMPORTANCE_LOW.

unsigned
character

sccp_sequence_control

Only relevant if sccp_service_class


is set to TCX_SCCP_CLASS1
Sequence numbers range from 0 to 255

Chapter 6

223

Using the TCAP API


Dialogue Handling

Primitive Structure
When the application exchanges primitives with the TCAP API, you must ensure
that the primitives contain the correct parameters as shown in Table 6-8, Structure
of Dialogue Primitives.
Table 6-8

Structure of Dialogue Primitives

Primitive Type

Parameters

Mandatary or Optional

TC_UNI

sce_quality

optional

d_address

mandatory

o_address

mandatory

dialogue_portion

optional - ITU-T White Book only

user_dialogue_id

mandatory

TC_BEGIN

sce_quality

optional

TC_QUERY_W_PERM

d_address

mandatory

TC_QUERY_WO_PERM

o_address

mandatory

dialogue_portion

optional - ITU-T White Book only

user_dialogue_id

mandatory

TC_CONTINUE

sce_quality

optional

TC_CONV_W_PERM

d_address

optional - accepted but not used a

TC_CONV_WO_PERM

o_address

optional - accepted but not used a

dialogue_portion

optional - ITU-T White Book only

user_dialogue_id

mandatory

provider_dialogue_id

mandatory

224

Chapter 6

Using the TCAP API


Dialogue Handling
Table 6-8

Structure of Dialogue Primitives (Continued)

Primitive Type

Parameters

Mandatary or Optional

TC_END

sce_quality

optional

TC_RESPONSE

d_address

optional - accepted but not used.

o_address

optional - accepted but not used.

dialogue_portion

optional - ITU-T White Book only

user_dialogue_id

mandatory

provider_dialogue_id

mandatory - absent in prearranged end.

sce_quality

optional

d_address

optional - accepted but not used.

o_address

optional - accepted but not used.

user_dialogue_id

mandatory

provider_dialogue_id

mandatory

report_cause

mandatory

sce_quality

optional

d_address

optional - accepted but not used.

o_address

optional - accepted but not used.

dialogue_portion

optional - ITU-T White Book only

user_dialogue_id

mandatory

provider_dialogue_id

mandatory - absent if following


TC_BEGIN

TC_NOTICE

TC_U_ABORT

u_abort_cause

mandatory

Chapter 6

225

Using the TCAP API


Dialogue Handling
Table 6-8

Structure of Dialogue Primitives (Continued)

Primitive Type

Parameters

Mandatary or Optional

TC_P_ABORT

sce_quality

optional

d_address

optional - accepted but not used.

o_address

optional - accepted but not used.

user_dialogue_id

mandatory

provider_dialogue_id

mandatory - absent if following


TC_BEGIN

p_abort_cause

mandatory
SCCP_USER_STATUS

tc_ustatus

mandatory

SCCP_PC_STATUS

tc_pcstatus

mandatory

SCCP_N_COORD

tc_ncoord

Not used on request, provided on


indication

SCCP_N_COORD_RES

tc_ncoord

mandatory

NO_PRIMITIVE

user_dialogue_id

mandatory

provider_dialogue_id

mandatory - absent if from network

MGT

tc_stat

mandatory

SWITCH_STARTED

no parameter

SWITCH_DONE

no parameter

a. Used in ITU-T White Book for the first TC_CONTINUE in a dialogue.

dialogue_portion
This field allows the negotiation of the Application Context and, as a further option
within it, the transparent transfer of user data which is not components.

226

Chapter 6

Using the TCAP API


Dialogue Handling
It is only used for ITU-T White Book dialogue primitives.
Table 6-9

dialogue_portion Structure

Field

Structure

Contents

Meaning

dlg_info_present

TC_BOOL

TC_NO

Indicates the dialogue information


is present.

TC_YES
application_context_name

user_information

tc_data

tc_data

length

Length of encoded
Object Identifier value

data

Object Identifier value


encoded in ASN.1

length

Length of encoded user


information value.

data

EXTERNAL TAG +
EXTERNAL LENGTH +
EXTERNAL VALUE

Reference to an explicitly defined


set of the TC-user Application
Service Elements (ASEs).
The TCAP API encodes the
Application Context Tag, the
Application Context Length and the
Object Identifier Tag.
Information that can be exchanged
between TC-users, independently of
the remote operation service.
user_information data is
transparent to TCAP, but must be
formatted according to Table 49 of
Q.773 and must include an
EXTERNAL tag and length.
Similarly for incoming messages
arriving from the network.
If the PDU is AARQ, AARE,
AABRT or AUDT, the TCAP API
encodes and decodes the User
Information Tag. Otherwise only
the Dialogue Portion Tag is encoded
and decoded.

abort_reason

tc_abort_reason

AC_name_not_suppor
ted
user_specific

Indicates whether a dialogue is


aborted because the received
application context name is not
supported and an alternative cannot
be proposed, or because of any
other user problem.

Example: Creating a Dialogue Primitive


This example is a code fragment for creating a dialogue primitive.
/*Example of primitive creation*/
tcx_primitive Primitive;

Chapter 6

227

Using the TCAP API


Dialogue Handling

Primitive.p_type = TC_BEGIN;
Primitive.service_quality.use_default_values = TC_YES;
Primitive.o_address.type= DPC_SSN;
Primitive.o_address.pc_value = 16;
Primitive.o_address.ssn
= 10;
Primitive.d_address.type= DPC_SSN;
Primitive.d_address.pc_value = 3;
Primitive.d_address.ssn
= 10;
Primitive.user_dialogue_id=2456;

// Computed by the application,


// must be different for each dialogue and > 0)

Primitive.provider_dialogue_id=0;
dialogue

// Computed by the API, but when you create a


// (TC_BEGIN) you initiate this field with 0.

228

Chapter 6

Using the TCAP API


Dialogue Handling

TCX Primitive Options


This is a list of the tcx_primitive options.
Table 6-10

tcx_primitive_option

Type

Field

Meaning

tc_u_abort

u_abort_cause

This field is used by ANSI and ITU-T


Blue Book components to indicate the
TC-user defined reason for the aborted
dialogue.

tc_termination_type

termination_type

This field indicates whether the


termination of a dialogue is basic or
prearranged, as defined in Q.771.

tc_transport_reason_
return

report_cause

This field contains information returned


by SCCP that indicates the reason for the
exception handling.

tc_p_abort_cause

p_abort_cause

This field indicates the local reason for the


aborted dialogue.

struct tc_stat_struct

tc_stat

This is the statistic information provided


by the local component sublayer.

struct tcx_pcstatus_
struct

tc_pcstatus

This is the SCCP signalling point status.

struct tcx_ustatus_
struct

tc_ustatus

This is the status of the remote TC-user.

struct tcx_ncoord_
struct

tc_ncoord

This contains information about the


withdrawal of a peer subsystem.

For further information refer to the following files:

Chapter 6

TCAP_ext.h

TCAP_ccitt.h

TCAP_common.h

TCAP_ansi.h

229

Using the TCAP API


Sending Components via the Component Sublayer Using TCX_send()

Sending Components via the Component


Sublayer Using TCX_send()
The application must use a TC-user TCAP connection if you want to encode and
send TCAP messages via the component sublayer. You must ensure that the
component sublayer has been enabled.
TCX_send() assembles and transmits TCAP messages. Components, that have
been passed to the component sublayer either individually or in a list, are sent with a
dialogue primitive to the transaction sublayer for further processing.
TCX_send() is defined in the header file TCAP_ext.h. For details about syntax,
parameters, and return values, see the TCX_send() man page.

Example: Using TCX_send ()


This example is a code fragment showing how to send components via the
component sublayer to the transaction sublayer.
/* example of sending data */
/*
* ---------------------------------------------------------------------* error management function
* returns TRUE in the current dialogue should be restarted
* ---------------------------------------------------------------------*/
TC_BOOL error_handler( int error,
int user_id,
int prov_id,
tcx_component *comp )
{
printf (ERROR : %s\n, tc_error_text[error] );
switch (error)
{
case TCE_ILLEGAL_VALUE :
case TCE_WRONG_IDS :
case TCE_NOT_IMPLEMENTED :
case TCE_ILLEGAL_CALL :
case TCE_NO_CONFIG :
case TCE_BAD_CONFIG :
case TCE_CONNECT_INIT :
case TCE_INVALID_SSN :
case TCE_MAX_USERS :
case TCE_INTERNAL :
case TCE_MEMORY_ERROR :

230

Chapter 6

Using the TCAP API


Sending Components via the Component Sublayer Using TCX_send()
exit(-1);
case TCE_CNX_CLOSED :
case TCE_CNX_ID :
TCX_close( cnxId );
connection_handler(AI, II);
return( TRUE );
case TCE_SYNTAX_ERROR :
if (TCX_free_components(comp) == -1)
{
printf (Error in TCX_free_components: %s\n,
tc_error_text[tc_errno]);
exit (-1);
}
return( TRUE );
case TCE_COMPONENT_ERROR :
case TCE_TOO_MANY_COMPONENTS :
if (TCX_flush_components(cnxId, user_id, prov_id) == -1)
{
printf (Error in TCX_flush_component: %s\n,
tc_error_text[tc_errno]);
exit (-1);
}
break;
case TCE_SEND_FULL :
case TCE_API_BUSY :
break;
default :
printf(Returned an unknown error\n);
}
return( FALSE );
}
int build_component_with_put(
{
tcx_component *comp_ptr;
tcx_buffer *buf_ptr;
int len;

tc_component_type type, int inv_id, int uid, int pid )

/* allocate one component */


if (TCX_alloc_component(&comp_ptr, 1) == -1)
{
printf (Error in TCX_alloc_component: %s\n, tc_error_text[tc_errno]);
exit (-1);
}
/* allocate one buffer of 1000 octets */
if (TCX_alloc_buffer(&buf_ptr, 1000) == -1)
{
printf (Error in TCX_alloc_buffer: %s\n, tc_error_text[tc_errno]);
exit (-1);
}

Chapter 6

231

Using the TCAP API


Sending Components via the Component Sublayer Using TCX_send()

comp_ptr->c_type = type;
comp_ptr->op_class = 1;
comp_ptr->invoke_id = inv_id;
comp_ptr->linked_id = -1;
/* operation fields */
comp_ptr->operation.tag = GLOBAL_TYPE;
comp_ptr->operation.length = 10;
sprintf ((char *)(comp_ptr->operation.datas),abcdefghij);
/* parameter field */
/* buffer size used initialisation */
buf_ptr->actual_length = 5;
/* copy user datas in buffer */
sprintf ((char *)(buf_ptr->bufferp), 12345);
/* buffer pointer affectation to component */
comp_ptr->parameter= buf_ptr;
/* Initialize operation timer */
comp_ptr->timer.tv_sec = 30;
comp_ptr->timer.tv_usec = 0;
if (len= TCX_put_component(cnxId, uid, pid, comp_ptr) == -1)
{
error_handler( tc_errno, uid, pid, comp_ptr );
return( -1 );
}
return (len);
}
/* now the send portion code */
send_full=FALSE;
if (TCX_send(cnxId, NULL, &primitive_to_send, NULL) == -1)
{
switch( tc_errno )
{
case TCE_SEND_FULL :
case TCE_API_BUSY :
send_full = TRUE;
break;
default :
diag_init = error_handler( tc_errno, user_id, prov_id, NULL );
}
}

232

Chapter 6

Using the TCAP API


Receiving Components from the Component Sublayer Using TCX_recv()

Receiving Components from the Component


Sublayer Using TCX_recv()
The application must use a TC-user connection to receive components and dialogue
primitives from the component sublayer. See Creating TCAP Stack Connections
Using TCX_open() on page 196 for details about creating TC-user connections.
Before any TC-user connection can be accessed, it must be scheduled as described
in Scheduling TCAP Stack Connections on page 200.
The TCX_recv() function receives a TCAP message from the network and
decodes the components found in the received message.
Extraction must be done by the application using TCX_get_component() as
described in Extracting Components Using TCX_get_component() on page 236.
For details about syntax, parameters, and return values, see the TCX_recv() man
page.

Chapter 6

233

Using the TCAP API


Receiving Components from the Component Sublayer Using TCX_recv()

Example: Receiving Components Using TCX_recv ()


The example is a code fragment showing how to receive components using
TCX_recv().
/* receive example */
while (1)
{
/* init select bit masks & timer in each loop */
FD_ZERO(&readMask);
FD_ZERO(&writeMask);
FD_ZERO(&exceptMask);
tmout.tv_sec = 2;
tmout.tv_usec = 0;
time = &tmout;
/*
*
HP OC SS7 select phase
*/
numFd = TCX_select_mask(0,&readMask,&writeMask,&exceptMask,&time);
n = select(numFd, &readMask, &writeMask, &exceptMask, time);
if ( n < 0 )
{
/* select error Mgmt */
switch(errno)
{
case EINTR:
/* note that select exit with EINTR if a sigalarm is received */
/* continue processing */
break;
default:
printf (Error during select, reason: %d\n, errno );
exit (-1);
}
}
num_cnx = MAX_FD;
cnx_active[0] = -1;
TCX_cnx_handler(n, &readMask, &writeMask, &exceptMask, &num_cnx, cnx_active);
if ( (num_cnx > 0) && ( cnx_active[0] == cnxId) )
{
more = 1; p_type = 0; prov_id = 0;
/* Receive all possible messages arrived */
while( more > 0 )
{
result= TCX_recv( cnxId, NULL, &primitive, NULL, &more );
switch( result )

234

Chapter 6

Using the TCAP API


Receiving Components from the Component Sublayer Using TCX_recv()
{
case -1 :
/* error */
error_handler( tc_errno, 0, 0, NULL );
continue;
case 0 :
/* nothing received */
continue;
case NO_COMPONENTS :
/* something received without component
*/
default :
/* something received */
p_type= decode_primitive (&primitive);
prov_id = TC_P_PROVIDER_ID(&primitive);
break;
}
.........

Chapter 6

235

Using the TCAP API


Extracting Components Using TCX_get_component()

Extracting Components Using TCX_get_component()


After receiving components with TCX_recv(), the components of a received
TCAP message are decoded but remain in the internal API component list. The
application must extract these components individually from the component
sublayer
This function extracts a component from the component sublayer. It also updates the
state-machines of the component sublayer.
TCX_get_component() is defined in the header file TCX_ext.h.

For details about syntax, parameters, and return values, see the
TCX_get_components() man page.

236

Chapter 6

Using the TCAP API


Using the Transaction Sublayer

Using the Transaction Sublayer


The TCAP transaction sublayer facilities are also accessible via the TCAP API.
When the application creates a TR-user connection as described in Creating TCAP
Stack Connections Using TCX_open() on page 196, then non-standard user data
and dialogue information not defined by HP OpenCall SS7 can be exchanged with a
remote TR-user.

Component Handling
The component handling primitives of the component sublayer as shown in
Table 6-3, TCAP Component Types, do not have any counterpart in the transaction
sublayer.
The TCAP API uses a byte table to exchange encoded user data. Encoding and
decoding of data in this table is the responsibility of the application.
All memory allocation must be managed by the application.

Transaction Handling
There is a one-to-one relationship between dialogue handling primitives of the
component sublayer and the transaction handling primitives in the transaction
sublayer.
Thus the primitive types and their structure given in Table 6-6, Primitive Types, and
Table 6-8, Structure of Dialogue Primitives, are also provided by the TCAP API for
the exchange of user data via the transaction sublayer to a remote TR-user.

Chapter 6

237

Using the TCAP API


Sending User Data via the Transaction Sublayer Using TLX_send()

Sending User Data via the Transaction


Sublayer Using TLX_send()
User data can only be sent via a scheduled TR-user connection. Initially, the
application must create and encode all the user information as bytes in a component.
Then TLX_send() must be called.
TLX_send() assembles and transmits a TCAP message. The component portion of
the TCAP message must be previously encoded by the application.
TLX_send() is defined in the header file TCAP_ext.h.

For details about syntax, parameters, and return values, see the TCX_send() man
page.

238

Chapter 6

Using the TCAP API


Receiving User Data from the Transaction Sublayer Using TLX-recv()

Receiving User Data from the Transaction


Sublayer Using TLX-recv()
The application must use a TR-user stack connection to receive a TCAP message
directly from the transaction sublayer.
Before any TR-user connection can be accessed, it must be scheduled as described
in Scheduling TCAP Stack Connections on page 200.
The TLX_recv() receives TCAP message from the network but does not decode
the components found in the received message.
For details about syntax, parameters, and return values, see the TCX_recv() man
page.

Chapter 6

239

Using the TCAP API


Closing TCAP Stack Connections Using TCX_close()

Closing TCAP Stack Connections Using TCX_close()


CAUTION

Only close a TCAP stack connection when you are certain that the application will
not use the connection again. If a connection is repeatedly opened and closed, the
application will place a high overhead on the TCAP API mechanism.

A TCAP service is terminated when the application closes a stack connection using
TCX_close(). All the entities associated with this stack connection are also
closed, and all calls to TCX_send(), TLX_send(), TCX_recv() or TLX_recv()
will be refused.
This function closes a TCAP stack connection. You must reschedule any remaining
stack connections after you have called TCX_close(). If the application closes the
final TCAP stack connection, then TCAP will be disconnected from SCCP.
For details about syntax, parameters, and return values, see the TCX_close() man
page.

Example: Closing a TC-user Connection


The example is a code fragment that shows how to close a TC-user connection.
int
tcx_primitive
tc_primitive_type
struct tcx_component

cnxId, result, more;


primitive;
p_type;
* comp_ptr;

if ((result = TCX_recv(cnxId,NULL,&primitive, &comp_ptr, &more))>0)


{
p_type = TC_P_TYPE(primitive);
if (p_type == TC_END) {
if (TCX_close (cnxId) == -1)
printf (Error during TCX_close\n);
printf (TC_CLIENT: End of operations\n);
/* finished */
}
}

240

Chapter 6

Using the TCAP API


Component Management

Component Management
The tcx_component structure is used by the TCAP API to exchange data with a
TC-user. The application needs to allocate a buffer and component list. See
Creating a Component on page 206.

Retrieving Component Buffers


The application can retrieve a component buffer by using
TCX_get_component(). See Extracting Components Using
TCX_get_component() on page 236.

Memory Allocation
All component memory allocation and de-allocation is performed by the TCAP API.

Invoke IDs
Each invocation of an operation can be referenced by its invoke ID. The range of
invoke ID is 0 to 255. An invoke ID can be reused if the previous operation using
the invoke Id has been terminated.

Wait-for-reject Timer
The wait-for-reject timer is activated when a reply to an invocation is received. It
avoids duplication of an invoke ID for two different operation invocations.
The application can reduce this timeout value by calling TCX_control() with the
SET_REJECT_TIMER command. See Advanced Component Management on
page 216.

Chapter 6

241

Using the TCAP API


Dialogue Management

Dialogue Management
A dialogue is fully identified by a user_dialogue_id and a
provider_dialogue_id. Each dialogue primitive must contain one or both of
these IDs.
See Dialogue Handling on page 219 and the following dialogue example.

Example of a TC Dialogue
1. The local TC user starts the dialogue with a TC_BEGIN(), assigning the
user_dialogue_id which is only used locally (uidx). When the remote TC
user receives the TC_BEGIN(), the remote user assigns his own
user_dialogue_id before responding. So, this value starts as uid0 and
passes to uidz. The provider_dialogue_id is also assigned (pidy).
2. The local TC user receives the provider_dialogue_id from the remote
user (pidy), and continues to use his own local user_dialogue_id (uidx).
3. The dialogue continues, identified uniquely on the Local TC user side with
uidx and pidy, and identified uniquely on the Remote TC user side with uidz
and pidy.
Figure 6-16

TC Dialogue Example

Setting Dialogue ID Values


Since the provider_dialogue_id is allocated by TCAP, it may be necessary to
control its value.

242

Chapter 6

Using the TCAP API


Dialogue Management
To define the minimum (setLowPId), use the cfgTcap command (for a
description, see the man page). See also the HP OpenCall SS7 Operations Guide.
The maximum (setHighPId) provider_dialogue_id value available is
automatically calculated.

Simultaneous Dialogues
The number of simultaneous dialogues supported by TCAP depends on the
expansion level. The minimum is 65,535 and the maximum is 262,140 (4 x 65,535).

Chapter 6

243

Using the TCAP API


Transaction Management

Transaction Management
Transaction management is only necessary if the application is directly using the
transaction sublayer services of the TCAP API via a TR-user connection. Because a
TR-user connection bypasses the component sublayer, the application must manage
the encoding/decoding mechanisms, state-machines and timers according to the
non-standard requirements.
The application must also manage transaction IDs as described in Dialogue
Management on page 242.

244

Chapter 6

Using the TCAP API


API Memory Management

API Memory Management


The application can increase the maximum size of memory (in bytes) allowed for
the TCAP API using TCX_control() and the SET_API_MEMORY_SYZE
command. The default is 65,000 bytes. You must set the cnxId parameter of
TCX_control() to NULL.

Chapter 6

245

Using the TCAP API


Tuning TCAP IPC Buffers Using TCX_control()

Tuning TCAP IPC Buffers Using TCX_control()


As described in Tuning IPC Buffers on page 71, the application may need to alter
the default values of the IPC send and receive buffers.

TCX_control(): Syntax
The TCAP API provides the application with TCX_control() to customize these
IPC buffer attributes for each TCAP stack connection.
Return
Value

Function

Parameters

int

TCX_control

(int

cnxId,

voida

* context,

tc_control_c

command,

tc_control_parms

* parameters);

a. In 64-bit mode the context field is an int, not a void.


context

This parameter is not supported. Set its value to NULL.

cnxId

This input parameter specifies which stack connection IPC buffers will be modified.

246

Chapter 6

Using the TCAP API


Tuning TCAP IPC Buffers Using TCX_control()
command

This input parameter defines the IPC buffer command as described in the table.

Table 6-11

IPC Management Commands

Command

Meaning

OUT_IPC_BUFFER_SIZE

Increases the IPC transmit buffer from the default value of 8000 bytes.
The maximum size is 65,535 bytes.

IN_IPC_BUFFER_SIZE

Increases the internal IPC receive buffer from the default value of 8000
bytes. The maximum size is 65,535 bytes.

LOW_TRANSIT_TIME

Sets the maximum transit time before messages are sent on a LAN with
low traffic (default 20 ms).

HIGH_TRANSIT_TIME

Sets the maximum transit time before messages are sent on a LAN with
high traffic (default 100 ms).

OUT_BUFFER_BLOCK

Allows messages to be buffered. Reduces the number of IPC system


calls, and must be done as soon as the application requires high message
throughput. Should be used in association with OUT_BUFFER_FLUSH
and OUT_BUFFER_FLUSH_COND.

OUT_BUFFER_DONT_BLOCK

Flushes the send buffer as soon as a TCX_send() or TLX_send() call


is issued.

OUT_BUFFER_FLUSH

Immediately flushes the send buffer.

OUT_BUFFER_FLUSH_COND

Flushes the send buffer only if one of the following conditions is


satisfied:
- the send buffer is full
- the transit time of the oldest message in the send buffer has exceeded
the set transit time

GET_CONNECTION_INFO

Copies all the IPC information from cnx_id to the cnx_info field of
parameters. This command be used before or after changing a
connection.

DESACTIVATE

Sets the active flag of TCAP connection to TC_NO. This command


allows the application to smoothly disconnect a TCAP connection
without losing the last incoming message.

Chapter 6

247

Using the TCAP API


Tuning TCAP IPC Buffers Using TCX_control()
Table 6-11

IPC Management Commands (Continued)

Command

Meaning

ACTIVATE

Sets the active flag of the TCAP connection to TC_YES. This command
allows the application to reconnect a TCAP connection to the SS7 stack,
and allows TCAP to accept new incoming transaction requests for a TCor TR-user.

parameters

These parameters are associated with particular IPC commands.


TCX_control uses the tc_control_params_struct structure defined in the
TCAP_common.h file to exchange data and information with the application.

Table 6-12

Associated Parameters of IPC Commands

IPC command

Associated tc_control_params_struct field

OUT_IPC_BUFFER_SIZE

tx_buffer_size must be set to between 8,000 and 65,535.

IN_IPC_BUFFER_SIZE

rx_buffer_size must be set to between 8,000 and 65,535.

HIGH_TRANSIT_TIME

high_transit_time must contain a microsecond value.

LOW_TRANSIT_TIME

low_transit_time must contain a microsecond value.

GET_CONNECTION_INFO

cnx_info field is used to store current connection information.

TCX_control(): Return Values


If TCX_control() is successful, a positive integer is returned.

248

Chapter 6

Using the TCAP API


Tuning TCAP IPC Buffers Using TCX_control()
If TCX_control() is unsuccessful, the return value is -1 and tc_errno is set to
indicate the error.
Table 6-13

TCX_control() Error Values

tc_errno

Meaning

TCE_ILLEGAL_VALUE

You used an illegal parameter value.

TCE_CNX_ID

You passed an invalid connection id for cnx_id.

TCE_CNX_CLOSED

The cnx_id connection has been closed.

TCE_ILLEGAL_CALL

You must enable the component sublayer before calling


TCX_put_component().

TCE_API_BUSY

A switchover is in progress. You must call TCX_control() again.

TCE_WRONG_IDS

An incorrect user_dialogue_id or provider_dialogue_id


value has been passed to TCX_put_component().

TCE_NOT_IMPLEMENTED

You passed an illegal command to TCX_control().

TCE_MEMORY_ERROR

No memory available.

Chapter 6

249

Using the TCAP API


Transaction Timers

Transaction Timers
TCAP provides a timer mechanism for the transaction sublayer that aborts any
transaction that has not been terminated after a certain period of time.
This behavior is managed by a timer that can be configured using the cfgTcap
command (for a description, see the man page). See also the HP OpenCall SS7
Operations Guide.
In the file sys.<className>.tcap, setTimerPeriod sets the maximum time
between the beginning of a transaction and the end of a transaction in seconds. If it
is set to 0, then the transaction timers are disabled.

250

Chapter 6

Using the TCAP API


Using TCAP over GDI

Using TCAP over GDI


The Generic Data Interface (GDI) allows TCAP to run over TCP. This allows TCAP
applications to communicate using an IP network.
TCAP accesses to GDI and SCCP are similar to those over a normal SS7 stack but
there are three differences:

NOTE

TCAP messages have a maximum component portion size of 4000 bytes. The
remaining 90 bytes are used for TCAP header encoding.

Error codes are specific to GDI or SCCP.

TCAP requests a connection on GDI using the Sub-System Number (SSN) 256.

The SSN 256 is reserved for applications using the GDI protocol and cannot be used
for SCCP connections.

The GDI interface is defined by Bellcore as "ISCP Generic Data Interface for
TCP/IP", with versions:

5.0 January 97

4.1 May 96

HP OpenCall SS7 implements all GDI 4.1 features, and can interoperate with 5.0.
The HP OpenCall SS7 stack provides the transport protocol part of GDI.

Chapter 6

251

Using the TCAP API


Using TCAP over GDI

GDI Access (Application Interface Layer)


TCAP accesses GDI and SCCP in a similar way, with the following exceptions:

GDI messages can be longer than those run over SCCP. The maximum GDI
message length is 4096 bytes (6 bytes of header). GDI messages are versioned.

Error codes are specific to GDI.

The sub layer (SCCP or GDI) to which a message must be routed is determined
by the SubSystem Number (SSN) during the TCAP connection phase. The
TCAP API requests a connection to GDI using the SSN 256. This SSN is
reserved for GDI.

The Distant GDI Point Code (DGPC) maps a logical connection to a remote
host (client or server).

GDI Connectivity
This section lists some rules for GDI connectivity:

252

Connections are made using the OS socket interface.

The transport layer is TCP.

The GDI stack can run as a server or as a client. The server listens and accepts
client connection requests. If a connection between a GDI client and a GDI
server goes down, the GDI client tries to reconnect periodically until the
connection is reestablished. Once a connection has been established, either the
client or the server can initiate a transaction.

A GDI server accepts client connections only if a TCAP application is


connected to its SSN (256). If not, the connection is refused.

A GDI application is located on a host defined by a Port Service Number (PSN)


and by one or two IP address(es).

Keep Alive Mechanism: If no response is received during the specified time,


the connection is closed. The timer value is specified in the file
sys.<className>.gdi.

Transport Error Handling: if an error occurs at GDI level, the GDI layer (server
or client) closes the connection and refuses all outstanding requests for that
connection.

Security Implementation: to prevent unauthorized access, the GDI server only


accepts connections from preconfigured IP addresses.

Chapter 6

Using the TCAP API


Using TCAP over GDI

2-host platform: a 2-host HP OpenCall SS7 platform has one active host and
one peer host. Only connection requests to the active host are accepted. The
peer host refuses client connections.

Dual signaling LAN: GDI uses the two LANs to do loadsharing. However, as
TCP/IP cannot ensure delivery order over more than one LAN a transaction is
always kept on the same LAN. If one of the two LANs goes down, traffic is
ensured on the other one. All open transactions are lost if a LAN switchover
occurs.

TCAP Addressing Mode


A remote host is defined by its Distant GDI Point Code (DGPC). In TCAP, the
DGPC maps directly to the DPC in the tc_address structure. This means that the
DPC_SSN addressing mode must be used to identify a remote host. The DSSN
value in tc_address structure must be set to 0.

Notifications
GDI uses the SCCP_USER_STATUS primitive to indicate to the TCAP user
whether a connection to a remote GDI host is available or not.(Return values are
Out of Service and In Service). This differs from SCCP where it indicates
that a remote SCCP user is in service or out of service.
GDI uses the TC_NOTICE primitive to indicate GDI transport errors to the TCAP
user. The GDI transport error is returned in the report_cause field of the
TC_NOTICE primitive.

Chapter 6

253

Using the TCAP API


Using TCAP over GDI
Transport errors:
generalFailure:

One or more errors occurred either on route to the server or on


the server system

incompatibleVersions:
The version number in the GDI message header does not match
the versions supported on the server
queue full:

The server cannot process the request at this time due to a full
input queue

resultsTooLong:

The response message exceeds the maximum message size of a


GDI message

taskrefused:

The request was refused by the server system

timerExpired:

The timer on the server expired

unauthorizedRequest:
The request was refused by the server system because of
security
systemNotResponding:
The server site is not responding

Managing Stack Switchovers


For general information on GDI, see the HP OpenCall SS7 Welcome Guide.
Chapter 2, General System Guidelines, and Chapter 3, General API Guidelines,
of the current guide contain general guidelines.
You should also take into account the following GDI-specific points:

254

During a switchover, connections to the remote GDI hosts are unavailable.

When a standby SS7 stack becomes active, the local TCAP user is notified by
the SCCP_USER_STATUS primitive, which indicates that the connection to
the remote GDI host is again available (In Service).

When an active SS7 stack becomes standby, the remote TCAP user receives an
SCCP_USER_STATUS primitive indicating that the connection to it is
unavailable (Out of Service), and a second SCCP_USER_STATUS primitive
indicating that the connection to the host with the active SS7 stack is available
(In Service). (DGPC1 is In Service, DGPC2 is Out Of Service seen from host
1). The TCAP application is responsible for managing both DGPCs.

Chapter 6

Using the TCAP API


Using TCAP over GDI

NOTE

All active transactions are lost on switchover. The TCAP user must reset its local
timer and state-machines.

After a switchover, the newly active SS7 stack can accept connection requests from
GDI client hosts. It is the responsibility of the GDI client to set the reconnection
attempt period to a meaningful value. In the worst case, the interruption of service
time is equal to the switchover time plus the reconnection attempt period.
Figure 6-17

Chapter 6

GDI Connectivity in HP OpenCall SS7 Product

255

Using the TCAP API


Using TCAP over GDI

Managing Dual Signaling LANs


Load Sharing Using Two LANs
GDI uses two LANs to do loadsharing.
As TCP does not ensure transaction integrity over multiple LANs, each transaction
must be kept on the same LAN.
TCP hides LAN failures from the upper layers. Only the GDI Keep Alive
mechanism checks whether the LAN connection is still there or not. This means that
a broken LAN continues be seen as In Service until the Keep Alive timer pops and
that GDI continues to send transactions on the broken LAN. These transactions will
be lost.
For an example, see Figure 6-18, GDI Dual LANS - Failure of One LAN, and the
explanatory text that follows the figure.
When the keep alive timer pops, GDI indicates the error to the TCAP user by
sending a TC_NOTICE primitive (report_cause field set to
systemNotResponding) for any transaction in progress.
Hewlett-Packard recommends that the application manages timeouts on transactions
in order to avoid traffic stopping when a GDI signaling LAN goes down. This can
be done either by implementing timeout transaction management in the application,
or by letting the stack do it by uncommenting the setTimerPeriod.
To do this, use the cfgTcap command (for a description, see the man page). See
also the HP OpenCall SS7 Operations Guide.

256

Chapter 6

Using the TCAP API


Using TCAP over GDI
Figure 6-18

Chapter 6

GDI Dual LANS - Failure of One LAN

257

Using the TCAP API


Using TCAP over GDI
GDI Keep Alive Mechanism
To verify that the LAN is still available, the GDI protocol layer sends a Keep Alive
request at regular intervals. The frequency of this request is 1.5 times the value of
the GDI Keep Alive Timeout specified in the sys.<className>.gdi file.
The default value of this timer is 40,000 milliseconds. With the default setting of the
timer, a Keep Alive request will be sent every minute (1.5 x 40,000 ms). In the
figure, this is represented by the thick blue arrows.
The destination GDI application responds with a Keep Alive response almost
immediately afterwards (within milliseconds). In the figure, this is represented by
the thinner green arrows. This is the normal behavior when no LAN fault occurs,
and is shown on the left side of the figure.
When a LAN Fault Occurs
When a LAN fault occurs, there is a period during which traffic is disturbed. During
this period:

All transactions in progress on the LAN that failed are lost.

Half of all new transactions which start during this period are lost.

In the worst case, the maximum period of disturbed traffic is equal to:
1.5 x (Keep Alive Timeout) + 1 period = 2.5 x (Keep Alive Timeout)

After the period of disturbed traffic, the initial level of traffic returns on the
remaining LAN.
During the disturbed period, either the application must handle a TCAP transaction
timer, or you can set the TCAP setTimerPeriod timer to a value which suits the
traffic. To do this, use the cfgTcap command (for a description, see the man page).
This is to ensure that uncompleted TCAP transactions are aborted when the timer
pops and that further TCAP transactions can be started.
Choosing a GDI Timer Value
The default timer value is 40,000 ms, which causes a KeepAliveRequest to be sent
every minute. However, reducing the 40,000 ms value increases the frequency of the
KeepAliveRequests but also creates increased traffic on the LAN. Using the
information in the figure, a compromise must be made between the required
reactivity to a LAN failure and the level of Keep Alive traffic that is acceptable.

258

Chapter 6

Using the TCAP API


TCAP Tutorial Programs

TCAP Tutorial Programs


Two tutorials (that is, example programs) named TcapClient and TcapServer
are provided with HP OpenCall SS7.
The source code is in the /opt/OC/tutorials/SS7 directory.

CAUTION

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

TcapClient.c
This TC-user program requests a remote ITU-T TCAP application TcapServer to
perform operations on its behalf.
You must first compile TcapClient using the command cc_tcap. This will also
compile TcapServer at the same time. The name of the executable are
TcapClient_32_xxx (where xxx=AAA, ABB, WBB, or WAA).
To run the program, the following values must be provided:

className:
Name of the SS7 stack

org point code


Point code number of the SS7 stack

org subsystem number


Subsystem number of the SS7 stack

dest point code


Point code number of the Server application

dest subsystem number


Subsystem number of the Server application

For example, to run TcapClient on the client using SSN 40, enter:

Chapter 6

259

Using the TCAP API


TCAP Tutorial Programs
TcapClient_32_AAA SS7_Stack_36 36 35 40 40

TcapServer.c
This TC-user program performs operations on behalf of the ITU-T TCAP client
application TcapClient.
You must first compile TcapServer using the command cc_tcap. This will also
compile TcapClient at the same time.
The name of the executable is TcapServer_32_xxx (where xxx=AAA, ABB,
WBB, or WAA).
To run this program, the following values must be provided:

className
Name of the SS7 stack

org point code


Point code number of the SS7 stack

org subsystem number


Subsystem number of the SS7 stack

dest point code


Point code number of the Server application

dest subsystem number


Subsystem number of the Server application

For example, to run TcapServer on the server using SSN 40, enter:
TcapServer_32_AAA SS7_Stack_35 35 36 40 40

260

Chapter 6

Using the TCAP API


Building IN Message Sets Over the HP OpenCall SS7 TCAP API

Building IN Message Sets Over the HP OpenCall SS7


TCAP API
To create IN message sets, you need an ASN.1 compiler.
Such software tools are available on the market.
For example, you can obtain OSS ASN.1 tools from OSS Nokalva Inc. at:
http://www.nokalva.com
or the ASN.1 product line from MARBEN at:
http://www.marben-products.com/ASN.1/overview.html

Chapter 6

261

Using the TCAP API


Building IN Message Sets Over the HP OpenCall SS7 TCAP API

262

Chapter 6

Using the TCAP Application Message


Dispatcher
This chapter describes the TCAP Application Message Dispatcher.

Chapter 7

263

Using the TCAP Application Message Dispatcher


Introduction

Introduction
The SS7 stack supplies a default dispatching algorithm (round robin). Using the
TCAP Application Message Dispatcher, customers supply their own dispatching
algorithm which replaces the default algorithm supplied by the stack.
If the TCAP Application Message Dispatcher is enabled and the dispatching library
file is not found at the start-up of the stack, a LOG is generated and the stack does
not start.
The following table presents a few of the messages used in this chapter.
Table 7-1

ITU and ANSI Versions of Messages

ITU Version
TC-BEGIN

ANSI Version
TC-QUERY-WITH-PERMISSION

Meaning
Message that begins a transaction.

TC-QUERY-WITHOUT-PERMISSION
TC-CONTINUE

TC-CONVERSATION-WITH-PERMISSION
TC-CONVERSATION-WITHOUT-PERMISSION

TC-UNI

TC-UNI

Message belonging to an
established transaction.
Uni-directional message (not
belonging to a transaction).

Enabling and Disabling


TCAP Application Message Dispatcher is enabled and disabled using the cfgTcap
command (for a description, see the man page).
If TCAP Application Message Dispatcher is enabled, a client supplied shared library
named TCAProuter.<className>.so must be provided in the /opt/OC/lib
directory.

NOTE

264

If necessary, the shared library directory can be changed by modifying the


TCAProuterPath variable in the [<classname>] section of the global.conf
configuration file.

Chapter 7

Using the TCAP Application Message Dispatcher


Introduction
TCAP Application Message Dispatcher is enabled or disabled globally for all
applications connected to the SS7 stack. Consequently, if the dispatcher is enabled,
the customer-supplied library functions must route all incoming TC-BEGIN and
TC-UNI messages for all applications.

Default Dispatching Algorithm


The default algorithm supplied by the stack is round robin. Figure 7-1 illustrates this
algorithm for the case of four TCAP users connected to the same SSN.
Figure 7-1

Round Robin Algorithm

As shown in the figure, incoming TC-BEGIN and TC-UNI messages are distributed
to each TCAP user connected to the same SSN, application id, and instance id,
strictly in turn. For example, suppose that User 4 is the most appropriate user to
handle the 2nd TC-BEGIN. The round robin algorithm gives this message to User 3
(since this algorithm has no way of knowing that User 4 is the most appropriate
user).

Customer-Supplied Dispatching Algorithm


In this case, the customer supplies the dispatching algorithm to be used (in the form
of a shared library loaded by the stack).
Figure 7-2 illustrates the role of a customer-supplied dispatching algorithm.

Chapter 7

265

Using the TCAP Application Message Dispatcher


Introduction
Figure 7-2

Customer-Supplied Dispatching Algorithm

Dispatching Outgoing Messages


The customer-supplied dispatching algorithm is not involved in the dispatching of
outgoing TCAP messages. The dispatching of such TCAP messages is the concern
of the destination stack.
ITU and ANSI Messages
In the discussion on TCAP-Layer application based routing in this document, the
ITU messages are used. However, everything said about ITU messages also applies
to their ANSI equivalents (see Table 7-1 on page 264).
Dispatching Incoming TC-BEGIN and TC-UNI Messages
If the TCAP Application Message Dispatcher is enabled, TCAP layer dispatching is
performed as shown in Figure 7-2 on page 266. When the SS7 stack receives a
TC-BEGIN or TC-UNI message (or their ANSI equivalents), it asks the
customer-supplied dispatching algorithm to make a dispatching decision. The SS7
stack then routes the message to the TCAP user selected by the dispatching
algorithm.
266

Chapter 7

Using the TCAP Application Message Dispatcher


Introduction
Dispatching Incoming TC-CONTINUE and TC-END Messages
For TC-CONTINUE and TC-END messages (and their ANSI equivalents), the
customer-supplied dispatching algorithm is not involved in the dispatching decision.
These messages concern an existing transaction, so the stack routes them directly to
the TCAP user associated with the transaction.
Distributing Incoming Transactions
There are a number of ways of distributing incoming transactions.
Some examples are:

NOTE

Based on the originating point code, or on a value within the message itself,
such as a free phone number or a ported number. For example, the customer
defines ranges of telephone numbers (R1, R2, R3, R4, etc.). Messages with a
telephone number within R1 are routed to application A1, those within R2 are
routed to application A2, etc.

Randomly or in a round robin fashion.

Based on the current workload. If an application is overloaded, then the


customer-supplied dispatching algorithm routes the message to another
application (or filters, or deletes the message).

Giving more traffic to one application than to the others.

The shared library may implement a separate dispatch algorithm for different SSNs
(for example, see Figure 7-3, Example of Dispatching Algorithms.).

Identifying Application Instances (TCAP Users)


The identification of an application instance is passed between the stack and the
customer-provided functions through a structure of type
tcx_application_info.
This structure contains the applicationID and the instanceID. Each
application instance must be uniquely identified through the combination of an
applicationID and an instanceID.
Applications Must Connect Using TCX_open()
Applications using TCAP Application Message Dispatcher must connect using the
API function TCX_open().

Chapter 7

267

Using the TCAP Application Message Dispatcher


Introduction
One of the parameters of this function is a pointer to a structure of type
tcx_application_info containing an applicationID and an instanceID.

268

Chapter 7

Using the TCAP Application Message Dispatcher


Shared Library Technical Requirements

Shared Library Technical Requirements


If the TCAP Application Message Dispatcher feature is enabled, the dispatching
algorithm is provided in a customer-supplied shared library. This algorithm is used
to distribute incoming TCAP transactions between applications connected on the
same SSN (Subsystem Number).
This customer-supplied shared library must be robust, meaning that it must be
developed respecting the guidelines given in the Guidelines for Developing the
Customer-Supplied Shared Library on page 283.
The functions that must be present in this library are listed below. For details about
the syntax, parameters, and return values, see the TCAProuter(3) man page.
These customer-supplied functions are invoked by the HP OpenCall SS7 stack.
These functions must be coded in C or C++. Note that the names of the functions are
prefixed with TCAProuter_ for ease of identification.
The permissions on this shared library file must be 555 (that is, r-xr-xr-x or
world-readable and world-executable).

Header File
HP provides a header file for application developers. It must be included in each of
the source files of the customer-supplied library, and it is included in each of the
stack source files where there is a call to one of the functions in the
customer-supplied library.
For all functions, a negative return value indicates an error and has a
customer-supplied meaning. When a negative value is returned by a
customer-supplied function, the variable TCAProuter_errno should be set to a
value that is meaningful for the customer. The stack writes the
TCAProuter_errno value to a log file.

When the Library Functions are Called


The functions implemented by the shared library are called when a given service
(for example, an application identified by SSN, application identifier and instance
identifier) changes state and when an incoming TCAP transaction has to be routed.
Once a transaction is initiated, all related incoming messages are sent to the same
application without invoking the TCAP router shared library.

Chapter 7

269

Using the TCAP Application Message Dispatcher


Shared Library Technical Requirements
If the TCAP Application Message Dispatcher capability is disabled, the
HP OpenCall SS7 stack performs the application dispatching using a round robin
algorithm.

TCAProuter_init()
This function is invoked immediately at stack startup. It provides an opportunity for
data initialization in the customer-supplied library. This function has no parameters.

TCAProuter_application_activate()
This function is invoked when the first application, identified by SSN,
applicationId, and instanceId, becomes active.
Parameters indicate the SSN and a pointer the structure of the application that has
become active.

TCAProuter_application_deactivate()
This function is invoked when the last application instance, identified by SSN,
applicationId, and instanceId, is deactivated. In this event, the
customer-provided library updates its dispatching tables to account of the fact that
the application is no longer available.
Parameters indicate the SSN and a pointer the structure of the application that has
been deactivated.

TCAProuter_incoming_message()
This function is invoked for each incoming TC-BEGIN and TC-UNI message (and
for their ANSI equivalents). This function returns a pointer to the structure of the
application selected to get the message.
Input parameters indicate the primitive (decoded by the transaction sublayer), the
length, and a pointer to the component part of the message.

TCAProuter_shutdown()
This function is invoked just before the stack stops. It can be used for data cleanup.
This function has no parameters.

270

Chapter 7

Using the TCAP Application Message Dispatcher


Some Approaches to Dispatching Design

Some Approaches to Dispatching Design


The rest of this chapter gives some examples of how the TCAP Application
Message Dispatcher feature might be used and how the various components might
react in certain circumstances. It is the customers responsibility to code the
functions to obtain the desired behavior. These examples are intended to give you
some ideas, they are not to be taken as recommendations for design.
It is possible to employ a different technique for each SSN. For example, messages
destined to one SSN are distributed based on partitioning, while messages destined
to another SSN are distributed on a round robin basis. In this case, the
customer-supplied library contains a different dispatching table for each SSN.
The examples are:

Partitioning

Load Balancing

Round Robin

Uneven Distribution

Routing on INAP Service Key

Partitioning
The idea behind partitioning is to base the dispatching on some value inside the
message. For example, one range of called numbers is passed to one application
instance, and another range is passed to another application instance. In this case,
you code the function TCAProuter_incoming_message() so that it looks for
the value within the message, and based on this value, returns the appropriate
application and instance identifiers.
For example, several applications are running, each of which handles requests for a
range of called numbers. Each application has read/write access only to the section
of the database concerning its own range of numbers. This arrangement increases
performance by having each application keep a section of the database or a cache of
the database in its memory. As a consequence, if any given application is not
running, the messages with values in the range for that application are rejected.

Chapter 7

271

Using the TCAP Application Message Dispatcher


Some Approaches to Dispatching Design
At Application Startup
When an application starts up, it reads its section of database into memory and
connects to the stack. It identifies itself to the stack using its application ID and
instance ID in the call to TCX_open().
Roles of the Customer-Supplied Functions
TCAProuter_init() sets up a dispatching table that maps called number ranges
to application and instance identifiers.
TCAProuter_application_activate() and
TCAProuter_application_deactivate() update the in-memory table to
keep track of which applications are active.
TCAProuter_incoming_message() decodes the message to get the numeric
value. Using this number, it looks in the table to obtain the proper application ID and
instance ID, and returns them to the stack. Otherwise, -1 is returned to indicate that
the message could not be dispatched to any application.

Load Balancing
The idea behind load balancing is to send messages to the least busy application
instance.
At Application Startup
When an application starts up, it identifies itself to the stack using its application ID
and instance ID in the call to TCX_open().
Roles of the Customer-Supplied Functions
TCAProuter_init() initializes the librarys internal dispatching table.
TCAProuter_application_activate() updates the librarys internal
dispatching table to allow dispatching to that application.
TCAProuter_application_deactivate() updates the librarys internal
dispatching table to disallow dispatching to that application.
TCAProuter_incoming_message() routes the message to the application with
the lowest value for the number of transactions. This example uses the number of
transactions as an indicator of the load, but this is not necessarily a good measure of
the real traffic load. The real traffic load depends more on the number of messages
in a transaction rather than on the number of transactions.

272

Chapter 7

Using the TCAP Application Message Dispatcher


Some Approaches to Dispatching Design

Round Robin
If TCAP Application Message Dispatcher is not enabled, the default method of
distributing messages to applications connected at the TCAP interface is round
robin. This functionality is provided by the stack. If TCAP Application Message
Dispatcher is enabled, the stack passes all incoming TC-BEGIN and TC-UNI (or the
ANSI equivalents) to the customer-supplied library function
TCAProuter_incoming_message() for dispatching.
If it is desired to have applications responding to one SSN to be distributed based on
something in the message, and those applications responding to a different SSN
distributed on a round robin basis, the customer-supplied library must also provide
the round robin mechanism.
The stack and the shared library do not share dispatching responsibility. If TCAP
Application Message Dispatcher is enabled, the shared library is responsible for
dispatching. If TCAP Application Message Dispatcher is not enabled, the stack is
responsible for dispatching.
At Application Startup
When an application starts up, it identifies itself to the stack using its application ID
and instance ID in the call to TCX_open().
Roles of Customer-Supplied Functions
Each application ID and instance ID is indexed by a number. A counter is
maintained in the library to keep track of which one took the last message.
TCAProuter_incoming_message() increments the counter and wraps it around
from the last index to the first (when necessary). It does this until the counter
indexes an active application.
TCAProuter_application_activate() updates the librarys internal
dispatching table to allow dispatching to this application instance.
TCAProuter_application_deactivate() updates the librarys internal
dispatching table to disallow dispatching to this application instance.

Uneven Distribution
The idea behind uneven distribution is that some application instances have more
capacity than others. For example, it might be desirable to send twice as many
messages to one application instance than to another.

Chapter 7

273

Using the TCAP Application Message Dispatcher


Some Approaches to Dispatching Design
At Application Startup
When an application starts up, it identifies itself to the stack, using its application ID
and instance ID in the call to TCX_open().
Roles of Customer-Supplied Functions
The librarys internal dispatching table contains an integer field for each application
instance to indicate the desired percentage of transactions to be routed to that
instance. It may also contain an integer field for each application instance indicating
the current percentages given the number of instances that are currently connected
and active.
TCAProuter_init() initializes the librarys internal dispatching table loading the
desired percentage values.
TCAProuter_application_activate() updates the librarys internal
dispatching table to allow dispatching to that application instance, and to adjust the
current percentages to accommodate the number of application instances currently
alive.
TCAProuter_application_deactivate() updates the librarys internal
dispatching table to disallow dispatching to that application instance, and to adjust
the current percentages.
TCAProuter_incoming_message() looks in the table of user transactions
passed by parameter, and at the current percentages for each application instance, to
determine which instance gets the message. The actual weighting used depends on
the customer needs.

Dispatching on INAP Service Key


The idea behind dispatching based on the INAP service key is that different
applications handle different INAP services, so incoming messages are distributed
by INAP key.
At Application Startup
When an application starts up, it identifies itself to the stack using its application ID
and instance ID in the call to TCX_open().
Roles of Customer-Supplied Library Functions
The librarys internal dispatching table maps the INAP service key to different
application and instance IDs.

274

Chapter 7

Using the TCAP Application Message Dispatcher


Some Approaches to Dispatching Design
TCAProuter_application_activate() updates the librarys internal
dispatching table to allow dispatching to this application instance.
TCAProuter_application_deactivate() updates the librarys internal
dispatching table to disallow dispatching to this application instance.
TCAProuter_incoming_message() decodes the message up to the Service Key
and then maps the Service Key value to the appropriate application instance through
the dispatching table.

Chapter 7

275

Using the TCAP Application Message Dispatcher


Dispatching Algorithms

Dispatching Algorithms
Figure 7-3 shows an example of the use of dispatching algorithms within the
customer-supplied dispatching shared library. In this example, there are four SSNs.
Figure 7-3

Example of Dispatching Algorithms

In this example, the shared library implements a separate dispatching algorithm for
each of the four SSNs.
The dispatching algorithm is used to determine the destination applicationID
and instanceID, and the TCAProuter_incoming_message() function
returns these to the stack (which does the actual dispatching).
In this example, the dispatching algorithms use the following logic:

276

SSN1

uses the called number.

SSN2

uses random distribution.

SSN3

uses round robin.

SSN4

uses the current application workload.

Chapter 7

Using the TCAP Application Message Dispatcher


Dispatching Algorithms
The customer supplied algorithm determines which data to use and is responsible
for initializing and maintaining the data. There is no provision for replicating data.
For performance reasons, the data must be in-memory and the lookup mechanism
must be simple. For SSN3, the shared library must contain its own round robin
algorithm.

IMPORTANT

Chapter 7

SSN3 cannot use the stacks default round robin algorithm, because dispatching for
all applications must be done either by the stack or by the shared library but not by a
mixture of both.

277

Using the TCAP Application Message Dispatcher


Calls to Functions in the Customer-Supplied Library

Calls to Functions in the Customer-Supplied Library


Table 7-2, Context of Call to Customer-Supplied Functions, shows when the
customer-supplied functions TCAP Application Message Dispatcher are called by
the HP OpenCall SS7 stack.
Table 7-2

Call Context

Context of Call to Customer-Supplied Functions

Customer-supplied Function

Action at
Customer-supplied
Library

Stack Startup

TCAProuter_init()

Data initialization

First creation of a
TC-user connection
(applicationId,
instanceId) on a given
SSN: call to the
TCX_open()
function with the
active parameter set
to YES

TCAProuter_application_activate()

Update of dispatching
tables to take account of
the fact that the service is
connected and active.

Activation of a
secondary connection
when no primary
connection
(applicationId,
instanceId) on a given
SSN is available:
TC-CONTROL from
the application

TCAProuter_application_activate()

Update of dispatching
tables to take account of
the fact that the service is
connected and active.

278

Chapter 7

Using the TCAP Application Message Dispatcher


Calls to Functions in the Customer-Supplied Library
Table 7-2

Call Context

(Continued)Context of Call to Customer-Supplied Functions (Continued)

Customer-supplied Function

Action at
Customer-supplied
Library

Creation of a
non-active TC-user
connection
(applicationId,
instanceId): call to the
TCX_open()
function with the
active parameter set
to NO

No customer-supplied function is called.

No action.

Deactivation of the
last active TC-user
connection
(applicationId,
instanceId) on that
SSN: TC-CONTROL
from the application
or stack initiative

TCAProuter_application_deactivate()

Update of dispatching
tables to take account of
the fact that the service is
no longer active.

Close of the last


active TC-user
connection
(applicationId,
instanceId) on that
SSN: call to the
TCX_close()
function

TCAProuter_application_deactivate()

Update of dispatching
tables to take account of
the fact that the service is
no longer available.

Close of a non-active
TC-user connection
(applicationId,
instanceId): call to the
TCX_close()
function

No customer-supplied function is called.

No action.

Chapter 7

279

Using the TCAP Application Message Dispatcher


Calls to Functions in the Customer-Supplied Library
Table 7-2

Call Context

(Continued)Context of Call to Customer-Supplied Functions (Continued)

Customer-supplied Function

Action at
Customer-supplied
Library

Incoming traffic
message received by
TCAP

TCAProuter_incoming_message()

Return the identifier of


the application to which
the message must be
transmitted.

Stack Shutdown

TCAProuter_shutdown()

Data cleanup

280

Chapter 7

Using the TCAP Application Message Dispatcher


Tracing and Logging

Tracing and Logging


TTL (Telecom Tracing and Logging) Mechanism
The TTL trace mechanism of the SS7 stack process is available to the dispatching
library of the TCAP Application Message Dispatcher.

Principles of Stack Traces


The traces of the stack can be activated/deactivated dynamically function by
function and on different levels according to the masks configured in the
debug.conf configuration file.
A trace function using TTL is provided by the stack for the customer-library. This
function allows you to set traces within the code of the dispatching functions and to
display them as any other traces of the HP OpenCall SS7 process.
The dispatching library traces are identified within the traces of the
HP OpenCall SS7 stack process by a specific mask.
To allow more flexibility and efficiency, a number of trace levels are available to the
dispatching library functions. This is configurable as a parameter of the trace
function.
The valid trace levels available to the dispatching library are described in the
TCAProuter man page. If the trace function is called with a trace level different
from those listed in the TCAProuter man page, the trace is not displayed.

Trace Function Prototype


The TCAPRouter header file includes the trace levels and the prototype of the trace
function. This header file must be included in each source file of the shared library
using the trace function.
TCAProuter_trace( int traceLevel , char *string );

where:

Chapter 7

traceLevel

One of the values defined in the TCAProuter man page.

string

String to be displayed

281

Using the TCAP Application Message Dispatcher


Tracing and Logging

Activating the Trace Function


To activate the dispatching library traces, add 0x40000000 to the mask related to the
stack classname and the selected trace level.
The following extract of the debug.conf configuration file activates:

The memory dispatching library traces.

The error traces for the dispatching library and TCAP.

1 [SS7_Stack_TDx_n]
2 //Specific SS7_Stack:
3 //Environment = 0x00080000
4 //Proxy = 0x00100000
5 //Tcap = 0x00200000
6 //Sccp = 0x00400000
7 //Level = 0x00800000
8 //Level3-Links-Linksets = 0x01000000
9 //Level3-Routes-Dest = 0x02000000
10 //Level2 = 0x04000000
11 //Level2-Silt = 0x08000000
12 //SwitchCtrl = 0x10000000
13 //Gdi = 0x20000000
14 //User library = 0x40000000
15
16 COM_E_LL_FUNCTION_MASK = 0x00000000
17 COM_E_LL_MEMORY_MASK = 0x40000000 // set memory routing library traces
18 COM_E_LL_OBJECTS_MASK = 0x00000000
19 COM_E_LL_ERROR_MASK = 0x40200000 // set error traces for routing library and
Tcap
20 COM_E_LL_INFOFLOW1_MASK = 0x00000000
21 COM_E_LL_INFOFLOW2_MASK = 0x00000000
22 COM_E_LL_STATES_MASK = 0x00000000
23 COM_E_LL_STARTUP_MASK = 0x00000000

When to Use the Trace Function


The trace process is costly in terms of performance and in certain cases it may even
cause the stack to crash.
In a testing/debugging environment (for your shared library), you can use the trace
mechanism as needed.
In an operational environment, you are also recommended to activate the trace only
for errors (COM_E_LL_ERROR_MASK ).

282

Chapter 7

Using the TCAP Application Message Dispatcher


Guidelines for Developing the Customer-Supplied Shared Library

Guidelines for Developing the Customer-Supplied


Shared Library
This section gives some guidelines for developing the shared library.

Designing for Compatibility

Chapter 7

The dispatching library functions must be coded in C or C++ (using the ISO
C-89 or ISO C++-89 language versions).

If the TCAP Application Message Dispatcher is enabled, the library file


TCAProuter.<ClassName>.so must be present in the directory configured.

If the TCAP Application Message Dispatcher is enabled and the


customer-supplied dispatching library file is not found at the start-up of the
stack, a LOG is generated and the stack does not start.

Within the dispatching library, the use of threads is NOT allowed.

The use of a blocking operation is allowed only if the resulting external


contention does not make the TCAP Application Message Dispatcher exceed
the time-out limit defined in Designing for Performance on page 284.
Examples of blocking operations are Mutexes, Semaphores, and blocking I/Os.

The HA framework of the HP OpenCall SS7 product ensures the replication of


the application connection and activation commands on both hosts and where
necessary the same shared library functions are called on both platforms.
However, it is the customers responsibility to ensure the consistency of the
dispatching shared libraries on both platforms.

If the TCAP Application Message Dispatcher is enabled, all TCAP applications


must connect using the function TCX_open().

283

Using the TCAP Application Message Dispatcher


Guidelines for Developing the Customer-Supplied Shared Library

Designing for Performance

284

The customer-supplied dispatching function must be simple enough to ensure


the minimum impact on the SS7 stack performance.

Except for handling shared memory (see Designing for Shared Memory on
page 285), the customer-supplied library should make no system calls.

The dispatching decision must be simple, involving one lookup in an


in-memory table.

Except for the functions that initialize or shutdown the customer-supplied


library, the customer-code cannot perform any I/O operations. Consequently,
the customer-supplied functions TCAProuter_init() and
TCAProuter_shutdown() may perform an I/O operation (for example, to
read a configuration file).

In order not to impact HP OpenCall SS7 performance, you are recommended


not to exceed 300 microseconds processing time within the
TCAProuter_incoming_message() function. Since HP OpenCall SS7
does not enforce this limit, it is your responsibility not to exceed this maximum
processing time.

You are recommended not to exceed 0.5 seconds (corresponding to the


heartbeat frequency) processing time within the TCAProuter_init()
function.

The parameter maxRoutingTime in the sys.<className>_TDx.tcap


configuration file specifies the maximum processing time (in microseconds)
within the TCAProuter_incoming_message() function. Each time this
value is exceeded, a LOG is generated. This parameter aims to log any
excessive overstepping of the recommended processing time. This value should
be much higher than the recommended time (300 microseconds). By default, it
is set to 20000 microseconds (= 20 milliseconds).

Chapter 7

Using the TCAP Application Message Dispatcher


Guidelines for Developing the Customer-Supplied Shared Library

Designing for Shared Memory


If the dispatching library uses shared memory to communicate with the application,
you must take account of the following constraints:

The application and the HP OpenCall SS7 stack must run on the same host (that
is, an application on the back end cannot access the shared memory).

The stack and the client application must be part of the same FTC group. If this
is not the case, the shared memory will no longer be usable after the switchover
of one of them.

The application or the shared library is in charge of the management of the


shared memory.

The dispatching library is allowed to perform system calls only for shared
memory initialization and termination.

As regards HA, only the master accesses the shared memory. In case of a
switchover, it is the applications responsibility to update the shared memory.

Shared memory concurrent access (application for writing/shared library for


reading) must be managed efficiently enough not exceed the maximum
processing time allowed per dispatching function call.

Designing for High Availability


You are responsible for ensuring the consistency of the dispatching shared libraries
on both platforms.

Chapter 7

285

Using the TCAP Application Message Dispatcher


Guidelines for Developing the Customer-Supplied Shared Library

Designing in Accordance with Limits

The number of users at the TCAP interface is limited to 32 (whether or not


TCAP Application Message Dispatcher is enabled).

The maximum number of simultaneously open SSNs is 8 (whether or not TCAP


Application Message Dispatcher is enabled).

The component portion transmitted by the transaction sublayer to the


component sublayer after the dispatching function call is never decoded (even if
the dispatching library does it partially). At this point, only the transaction
portion and component sublayer header have been decoded.

If the TCAProuter_incoming_message() function returns 0 but with an


unknown application id/instance id value, a LOG is generated and a TC_ABORT
is sent by the transaction sublayer to the originator of the message with the
following cause: RESOURCE LIMITATION (in ITU).

The dispatching library is not invoked on reception of management messages.


Such messages are still broadcast to all the applications connected to the stack.

Any application connected to the stack can modify the SSN state.

Even if the function TCAProuter_incoming_message(), detects a


decoding error which prevents dispatching, the stack does not generate a
TC_R_REJECT or a TC_U_REJECT. This is the responsibility of the component
sublayer/user. In this case, the application designer may choose one of the
following 2 solutions:
The dispatching library function returns -1, which notifies the transaction
sublayer that no application has been found for the message. Thus, a
TC_ABORT is sent by the stack to the remote user.
The dispatching function returns 0 indicating that the dispatching worked
normally, but as application/instance id it provides the identifier of a
special application which is able to generate the TC_R_REJECT or
TC_U_REJECT to send to the remote user. It is the application developer's
responsibility to decide and implement the required behavior.

286

Chapter 7

Using the TCAP Application Message Dispatcher


Header File

Header File
HP supplies a header file to be included in each of the source files of the
customer-supplied library, and it is included in each of the stack source files where
there is a call to one of the functions in the customer-supplied library.

File Names
There are two versions of the header file:

TCAProuter.h in C

TCAProuter.hpp in C++

The header file includes the prototype of the functions to be implemented within the
shared library and of the trace function provided by the stack to the shared library.

Synopsis
#include
#include
#include
#include

<sys/stdsyms.h>
<stdio.h>
<time.h>
"TCAP_ext.h"/* API structures for TCAProuter */

extern int TCAProuter_errno;


extern void TCAProuter_trace(int traceLevel, char * string);
int TCAProuter_init(void);
int TCAProuter_shutdown(void);
int TCAProuter_application_activate(int ssn,tcx_application_info *app);
int TCAProuter_application_deactivate(int ssn,tcx_application_info *app);
int TCAProuter_incoming_message(tcx_primitive * primitive,
int componentLength,
char * component,
tcx_application_info *app);

Chapter 7

287

Using the TCAP Application Message Dispatcher


Structures

Structures
The API structure providing the application and instance identifier of an application
are redefined in the header file and used in each prototype of the customer-supplied
dispatching functions.

tcx_application_info
typedef struct
{

tcx_appid_mode mode;
int applicationId;
int instanceId;
} tcx_application_info;

tcx_primitive
The API structure related to the transaction portion of a TCAP message (primitive)
can also be redefined in the header file and used in the prototype of the
TCAProuter_incoming_message() function, allowing dispatching logic to be
based on fields of the transaction part. In particular, the destination SSN is a field of
this structure.

288

Chapter 7

Using the TCAP Application Message Dispatcher


Functions

Functions
The functions available for implementation by the shared library are the following:

TCAPRouter_init()

TCAPRouter_shutdown()

TCAPRouter_application_activate()

TCAPRouter_application_deactivate()

TCAPRouter_incoming_message()

The following function is provided by the stack to the shared library:

TCAPRouter_trace()

For information about each of the functions listed above, see the TCAProuter()
man page.

Chapter 7

289

Using the TCAP Application Message Dispatcher


TCAP Application Message Dispatcher Tutorials

TCAP Application Message Dispatcher Tutorials


CAUTION

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

C
A C shared library performing round robin application dispatching is available in
the tutorial directory /opt/OC/tutorials.
It contains:

TCAProuter.c

TCAProuter.h

This shared library can be compiled with the cc_TCAProuter command:


cc_TCAProuter

C++
A C++ shared library performing round robin application dispatching is available in
the tutorial directory /opt/OC/tutorials.
It contains:

TCAProuter.cpp

TCAProuter.hpp

This shared library can be compiled with the cc_TCAProuter command using the
C++ option:
cc_TCAProuter -C++

290

Chapter 7

PIC/AG - Introduction
This chapter introduces the HP OpenCall PIC/AG facility.

Chapter 8

291

PIC/AG - Introduction
Some Basic Terms

Some Basic Terms


The following terms are used in this document:

292

API

Application Programming Interface. In this document,


reference is made to the Execution API, the HA API, the
Registry API, the PCA, and the TimerLib API (which are
supplied with HP OpenCall), and an External API (which is
supplied by the user).

client

In a client/server architecture, this is the side that requests a


service from the server.

Execution API

Plug-In Execution API. This is one of the components of the


PIC Framework supplied with HP OpenCall.

FSM

Finite State Machine.

FTC

Fault Tolerant Controller. This is a component of the


HP OpenCall platform which provides fault tolerance.

g++

C++ Compiler for Linux.

HA API

HA API. This is one of the components of the PIC Framework


supplied with HP OpenCall.

IPC

Abbreviation for Inter Process Communication.

NOP

Means no operation. In a user plug-in (shared library)


context, NOP is used to indicate that, by default, a method does
nothing. If you want the method to perform some operations,
then you must customize the method by supplying the code to
perform the operations you desire.

OC

Abbreviation for HP OpenCall.

PCA

Plug-In Communications API. This is one of the components of


the PIC Framework supplied with HP OpenCall.

PIC/AG

Plug-In Container/Application Guardian. This is the name of


the HP OpenCall feature that supplies the PIC, the PIC
Framework, and the associated APIs.

Chapter 8

PIC/AG - Introduction
Some Basic Terms
PIC

Plug-In Container. This is one of the components of the PIC


Framework supplied with HP OpenCall. The role of the PIC is
to encapsulate user applications (called user plug-ins) so that
they can be managed by the FTC and can communicate with
other user plug-ins using the PCA.

PIC Framework
This framework is supplied with HP OpenCall. It provides the
PIC, the PCA, the Execution API, the HA API, and the Registry
API. This framework enables user-written code to benefit from
the facilities of HPs FTC (Fault Tolerant Controller) and to
communicate with other user plug-ins using the PCA.
PIC Process

This is a process running on the HP OpenCall platform. The


PIC, and the user plug-in (shared library) that it encapsulates,
run as a single process. This process is known as the PIC
process.

Registry API

Registry API. This is one of the components of the PIC


Framework supplied with HP OpenCall.

server

In a client/server architecture, this is the side that performs a


service for the client.

Session

A set of related messages within the flow of messages


exchanged between user plug-in processes.

TimerLib API

Timer Library API. This is one of the components of


HP OpenCall.

user plug-in

This is user-supplied code encapsulated in a PIC. It enables


user-written code to benefit from the facilities of HPs FTC
(Fault Tolerance Controller) and to communicate with another
user plug-in using the PCA.
The user plug-in is supplied in the form of a shared library.

Chapter 8

293

PIC/AG - Introduction
Purposes of the HP OpenCall PIC Framework

Purposes of the HP OpenCall PIC Framework


The following are the main purposes of this framework:

to enable user applications to benefit from the HP OpenCall High Availability


(HA) framework.

to facilitate communication between 2 user plug-ins.

These purposes are independent.


One application may want to benefit from HA while another application wants to
communicate with another user plug-in (application).
These purposes are illustrated in Figure 8-1, Purposes of a User Plug-in.
Figure 8-1

Purposes of a User Plug-in

Ensuring HA
The FTC ensures High Availability for the user plug-in process. This means that the
FTC is capable of detecting a failure or an infinite loop in the user plug-in (via the
PIC). For HA, the PIC interfaces with the FTC on behalf of the user plug-in.
The FTC does not preserve the context of the user plug-in. If you want to preserve
the user plug-in context in case of switchover, you must incorporate the code to do
this in your user plug-in.

294

Chapter 8

PIC/AG - Introduction
Purposes of the HP OpenCall PIC Framework

Communicating with Another Plug-in


Using the PCA (Plug-in Communications API), user plug-ins can communicate with
each other.

Possible Plug-in Applications


The following types of application could become user plug-ins:

Chapter 8

An application implementing a new protocol stack (that is, a stack not provided
in the HP OpenCall).

A CDR (Call Detail Record) application.

An application using the ISUP or TCAP API.

295

PIC/AG - Introduction
Components of the PIC Framework

Components of the PIC Framework


The components of the PIC framework are shown in Figure 8-2, Components of
the PIC Framework.
Figure 8-2

Components of the PIC Framework

What is Supplied in the PIC Framework


The HP OpenCall PIC framework supplies the following components:

The PIC (Plug-in Container)

The Execution API, the HA API, and the Registry API


You use the Execution API to set up the user plug-in (shared library) and define
its run-time scheduling. You use the HA API to interface with the FTC. You use
the Registry API to retrieve some PIC attributes.

The PCA API (Plug-in Communications API)


You use the PCA API for communication with another user plug-in.

The TimerLib API and the FTC are other components of HP OpenCall.

296

Chapter 8

PIC/AG - Introduction
Components of the PIC Framework
The TimerLib API enables the plug-in to set/cancel timers (and call a callback
method on timer expiry).

What the User Must Develop


The user must develop:

The user plug-in itself (as a shared library).

The External API and External Application (if the user plug-in needs to
interface with an external application).

Role of Each Component


The PIC encapsulates the user plug-in (shared library) to form an executable that is
integrated in the HA framework of the platform.
The Execution API schedules the user plug-in, that is, it gives the user plug-in some
CPU time. The HA API interfaces with the FTC for High Availability reasons. The
Registry API gives access to some PIC attributes.
The PCA is used to pass messages between user plug-ins.

Benefits of the PIC Framework


It enables an existing application to become HA (that is, its failure to be detected by
the FTC, restarted if desired, and can trigger a switchover).
The PIC is fully integrated in the ocftcontrol and ocftstatus commands.

Chapter 8

297

PIC/AG - Introduction
Summary of PIC Framework Features

Summary of PIC Framework Features


The HP OpenCall PIC Framework provides the following features:

298

One PIC supports a single user plug-in (shared library).

Multiple PIC executables, and therefore multiple user plug-ins, are supported
on the same platform. The maximum number of PICs depends on the FTC
maximum process number and the number of other Fault Tolerant processes
running on the platform.

The PIC process is managed as a Fault Tolerant process by the FTC.

The PIC reports all process state changes to the user plug-in (shared library).

Messages can be exchanged between 2 user plug-ins via the PCA. These
messages can contain any encoded data. The user plug-in developer is
responsible for any coding/decoding engines that are required.

Chapter 8

PIC/AG - Introduction
User Plug-in Development

User Plug-in Development


This section describes the Plug-in software from the user plug-in developers point
of view and lists the major requirements for user plug-in development.

Programming Guidelines
A user plug-in is a loadable library (shared library) that complies with the APIs
supplied with the PIC Framework. It provides a number of C++ objects that are
defined by the APIs, and is designed to minimize the amount of work required to
migrate existing C/C++ software to HP OpenCall.
Plug-in development has a number of constraints. For example, a user plug-in
cannot wait for a signal, or use archive libraries, and the user plug-in process must
run on the FE (Front-End) platform. Some constraints in more detail:

A user plug-in must run in a single-threaded process.

A user plug-in must not perform an OS waiting event. The user plug-in must
not make select(2)or poll(2) system calls. This is the responsibility of the
PIC.

A user plug-in must not call OS process control functions, such as exit().

A user plug-in must not handle its own timers. It must use timers provided in
the TimerLib (see TimerLib API on page 320).

A user plug-in shares CPU-time with the PIC. The PIC needs periodic
CPU-time to ensure High Availability (HA). This period depends on HA
constraints specified in configuration files. The CPU should not be kept busy
for a time interval of the same order of magnitude as the FTC heartbeat
timeout period.

A user plug-in shares platform resources with other HP OpenCall processes.


This applies to resources such as CPU, memory, disk, LAN, and so on. The
amount of resources that the user plug-in (shared library) needs must be taken
into account when configuring/sizing the HP OpenCall platform. For example a
disk-intensive user plug-in would need a dedicated SCSI interface; a
LAN-intensive user plug-in would need a dedicated LAN.

This list is not exhaustive. It emphasizes that caution is required when developing a
user plug-in (shared library).

Chapter 8

299

PIC/AG - Introduction
User Plug-in Development

Compiling and Linking


For an example of compiling and linking a user plug-in, see the Tutorial (and in
particular, the associated Makefile) delivered with the PIC Framework.
For an example of compiling and linking a user plug-in, see the Tutorial (and in
particular, the associated Makefile) delivered with the PIC Framework.
The user plug-in must be compiled on Linux using the g++ compiler with the option
to generate position independent code. For more details about exception
management, see Exception Handling on page 329.
You can compile a source code file into an object using the following command:
g++ -pthread -D_GNU_SOURCE -fPIC -Wall -fexceptions -I/opt/OC/include
-c MyObj1.C -o MyObj1.o

where the -fPIC option generates position independent code


You must link the user plug-in as a shared library.
The shared library link command is:
g++ -pthread -D_GNU_SOURCE -fexceptions -shared -Wl,--allow-shlib-undefined
MyObj1.o Myobj2.o -o MyPlugin.so -L/opt/OC/lib

where:
-shared

is for shared library.

-pthread

because HP OpenCall libraries are thread-safe level-1b.

--allow-shlib-undefined

to allow a cascade of link dependencies.


-fexceptions

to force the library call-stack to be instrumented to carry system


exceptions.

If you intend to use the TCAP API within the user plug-in, you must use
-lSS7utilWBB for the ITU/TCAP flavor and -lSS7utilAAA for the
ANSI/TCAP flavor after -L/opt/OC/lib in the above command.

Development Environment
The user plug-in development environment allows the developer to build user
plug-in libraries and debug the user plug-in software.

300

Chapter 8

PIC/AG - Introduction
Exchanging Messages

Exchanging Messages
The PIC Framework provides a facility to manage inter-user plug-in
communication. This is illustrated in Figure 8-3, Exchanging Messages.
Figure 8-3

Exchanging Messages

The following 2 types of messages are used by the user plug-in:

Data Messages.

Error Messages.

The PIC Framework defines a communications channel between user plug-ins


(shown by the arrow in the figure). This is provided by the PCA (Plug-in
Communication API).

Multiple Servers
A user plug-in can define several PCA_Servers. This is illustrated in Figure 8-4,
Multiple PCA_Servers.

Chapter 8

301

PIC/AG - Introduction
Exchanging Messages
Figure 8-4

Multiple PCA_Servers

Multiple Clients
From the PCA_Server point of view, several PCA_Clients (other user plug-ins) can
connect to it. There is no explicit limit to their number. All these clients are
equivalent, and the PCA_Server manages its connection to them in the same
manner.
The clients can be in different PICs.
Several PCA_Clients communicating with the same PCA_Server is illustrated in
Figure 8-5, Multiple PCA_Clients. In this case, the session initiation (that is, the
sending of the first message) must be done by the client (otherwise, the server will
open a session towards an unspecified client).

302

Chapter 8

PIC/AG - Introduction
Exchanging Messages

Figure 8-5

Multiple PCA_Clients

Session
Messages exchanged always belongs to a session. A session is implemented by a
C++ object which can be overloaded for user application usage.
Either side can create a session. It is created by the side that needs it and this side
sends the first message of the session. A session is called outbound at the session
creators side and inbound at the other side.
Irrespective of which side creates the session, both sides must close it. Otherwise,
session leaks may be caused by zombie sessions. The user plug-in must contain the
code to do this. The side which decides to close the session must inform the other
side of its decision. In contrast to the session creation phase, there is no
synchronization between the PCA_Server and the PCA_Client for session deletion.
It is at the application level, via the messages exchanged between the user plug-in
server and the user plug-in client, that the synchronization has to be done. For
example, the side that decides to close the session should send a last message to
the other side to inform it that it should also close the session. The user plug-in
closes a session using a C++ method.
For session management, the PCA allows you to:

Chapter 8

create a new session.

inform the user plug-in when the other side has created a new session.

303

PIC/AG - Introduction
Exchanging Messages

inform the user plug-in when the outbound path overflows (Transmit flow
control).

inform the user plug-in when the outbound path flow has returned to a normal
state (Transmit flow control).

close a session. A user plug-in must always close (or abort) a session, regardless
of which side created it.

abort a session. The session is closed with the propagation of an abort error
message.

Message Routing
Each message contains the session id. All messages belonging to the same session
contain the same session id. The receiver can retrieve the associated context using
this session id.
Multi PCA_Clients Case
In the case of multi PCA_Clients, several clients are connected to the same
PCA_Server, the message routing and dispatching over the multiple clients is done
as follows:

If the PCA_Client creates and sends the first message of the session, the user
plug-in receives it with its session id and the session is bound to the client that
sends the message. Any further messages using this session will be routed to
this client. The user plug-in does not know from which client the session
originated. This is managed by the PCA layer and is transparent to the user
plug-in.

If the user plug-in sends the first message of a new session (that is, the session
is created by the user plug-in), then in the multi PCA_Clients case, the PCA
determines the client that will receive the message using a round robin or load
balancing algorithm (based on parameters that the user plug-in specifies when it
creates the PCA Server). In any case, the user plug-in application cannot
specify the PCA_client to which a newly created session is to be associated.
This is fully controlled by the PCA layer. From the PCA_Server point of view,
all PCA_Clients are equivalent, and it is traffic or load balancing rules that
influence the selection of one client rather than another.

Flow Control
Flow Control is performed at two levels: session level and message level.

304

Chapter 8

PIC/AG - Introduction
Exchanging Messages
Levels of Flow Control
At the session level, flow control consists of preventing new sessions from being
opened. In this case, messages for existing sessions can still be sent and received.
At the message level, flow control consists of refusing messages even for existing
sessions.
At both levels, flow control is implemented based on the level of saturation of the
links between the PCA_Server and the PCA_Clients.
Between User Plug-ins
Between user plug-ins, the PIC enforces flow control by refusing the user plug-in
the right to open a session or send a message. Once the situation returns to normal,
the PIC informs the user plug-in that the flow control restriction is lifted so that the
user plug-in does not have to keep re-trying periodically.

Chapter 8

305

PIC/AG - Introduction
Execution API

Execution API
The Execution API is responsible for the setup of the user plug-in (shared library)
and its scheduling at run-time.
For more details, see Figure 10-1, C++ Structure of PIC API Classes.

Class
PIC_PluginExe is the interface class to the Execution API.

Loading and Binding


The user plug-in shared library has a single developer-provided entry-point binding
function. The run-time entry-point functions of the user plug-in are provided by
deriving a Plug-in Execution API virtual base class and optionally a Plug-in HA
base class. The purpose of the binding function is only to allocate to the user plug-in
specific objects inheriting from these base classes (and optionally from other base
classes). Subsequent access to the user plug-in is then performed through these
objects.

Scheduling
The Plug-in scheduling model is outlined in Figure 8-6, Plug-in Scheduling.

306

Chapter 8

PIC/AG - Introduction
Execution API
Figure 8-6

Plug-in Scheduling

This scheduling model uses the OS function select() to check for an OS signaled
event. Before calling select(), the PIC calls the
PIC_PluginExe::selectMasks()method to update the masks.
The PIC_PluginExe::connectionHandler()method is called by the PIC to
do the minimum necessary to remove the OS signaled event state. For example, if
the signaled event is I/O on a socket, the method reads the socket, if the event is a
timeout, the method decides what to do.
The PIC_PluginExe::pendingRequest()method is called by the PIC to
check if there is still work to be done (by the user plug-in). The
PIC_PluginExe::pendingRequest()method should not actually do the work
since this is the role of PIC_PluginExe::processRequest().
If the PIC_PluginExe::pendingRequest()method indicates that there is work
to be done, the PIC then calls the
PIC_PluginExe::processRequest()method to do some of this work. The
user plug-in developer must ensure that the work is broken down into tasks which
need little CPU time.

Chapter 8

307

PIC/AG - Introduction
Execution API
While PIC_PluginExe::pendingRequest() indicates that there is still work
to be done, there is an iteration on calls to
PIC_PluginExe::processRequest(). The maximum number of such
iterations is defined by the InternalLoopCount attribute in pic.conf.
The user plug-in developer should develop the methods of the PIC Execution API to
obtain the user plug-in behavior that is required.
In particular, the user plug-in developer must develop the
PIC_PluginExe::processRequest() method to do the work as and when
required.
The Plug-in scheduling model is shown in more detail in Figure 10-2, Plug-in
Scheduling Model.

308

Chapter 8

PIC/AG - Introduction
HA API

HA API
The HA API is responsible for the management of the HA FSM (Finite State
Machine).
The object model is shown in Figure 10-1, C++ Structure of PIC API Classes.

Class
PIC_PluginHA is the interface class to the HA API.

Features
The HA API provides the following HA features:

Interact with the user plug-in for HA state transitions.

It allows the user plug-in to request that the HA state is assigned DOWN in case
of internal failure.

It allows the user plug-in to notify the PIC about work completion in some
transient states.

HA States
In HP OpenCall platforms, the High-Availability (HA) feature is managed by the
Fault Tolerance Controller (FTC) process, also known as the FTController.
The FTC starts and manages all the High-Availability process life cycles of an
HP OpenCall platform.
On Linux, you can monitor and administer the HA status of HP OpenCall processes
using the ocftcontrol and ocftstatus commands.
The PIC (PlugInContainer) process (or any other HA process) life cycle is defined
by the HA states listed in Table 8-1, Definition of HA States.
Table 8-1

Definition of HA States
State

FTC_ACTIVE

Chapter 8

Definition
A process in this state is actively handling a functionality of the
platform.

309

PIC/AG - Introduction
HA API
Table 8-1

Definition of HA States (Continued)


State

Definition

FTC_HOT_STANDBY

A process in this state is ready to take over control of a service (but it is


not currently handling a functionality of the platform) in a minimum
time.

FTC_SWITCHING

A process in this state is actually taking control of a functionality.

FTC_STOPPING

A process in this state is going to FTC_DOWN.

FTC_SYNCHRONIZING

A process in this state is synchronizing itself with an FTC_ACTIVE


process. A process in this state is going to the FTC_HOT_STANDBY
state.

FTC_COLD_STANDBY

A process in this state may become active but is not currently


synchronized with the FTC_ACTIVE process.

FTC_BOOTING

A process in this state is starting. It is not ready to become


FTC_ACTIVE.

FTC_DOWN

A process in this state process has stopped (disappeared).


HA state transitions are driven by the HA Finite State Machine (FSM).
For more information on these states, see the FT_Monitor(1)man page (on an
HP OpenCall platform).

HA Model (on HP OpenCall SS7)


The HA FSM model as implemented by PIC is outlined in Figure 8-7, HA FSM for
PIC (on HP OpenCall SS7).

310

Chapter 8

PIC/AG - Introduction
HA API
Figure 8-7

Chapter 8

HA FSM for PIC (on HP OpenCall SS7)

311

PIC/AG - Introduction
HA API
When the FTC notifies the PIC of a change in the HA state, the PIC calls the
PIC_PluginHA::newState()method to notify the user plug-in of the new HA
state. The user plug-in developer may customize this method.
As regards HA, the user plug-in is mainly driven by the PIC and the FTC. Once
informed of a change in HA state by the PIC, the user plug-in can either
acknowledge the change, or ask for time before making the change (in a transient
transition). It can also decide to stop by executing the PIC_PluginHA::fault()
method and its state then becomes FTC_DOWN.
Transitions from an FTC driven state are controlled by the FTC. Transitions from
a Plug-in driven state are controlled by the user plug-in.
Transitions to the DOWN state can be triggered by either the FTC or the user
plug-in. Transitions to DOWN can be made from any other state.
Exit from the FTC_SWITCHING and FTC_SYNCHRONIZING states represents
the completion of transient operations for the user plug-in.
After FTC_STOPPING, the user plug-in can either go to FTC_HOT_STANDBY
(normal case), or go to FTC_COLD_STANDBY (and subsequently
FTC_SYNCHRONIZING).
The PIC uses the PIC_PluginHA::newState() method to inform the user
plug-in of changes in the HA state.
Transient States
In particular, when the HP OpenCall platform starts, the FTC and Plug-in process
decide which side will become FTC_ACTIVE and which side will become
FTC_HOT_STANDBY. The PIC informs the user plug-in via the
PIC_PluginHA::newState() method, of the new state that it is entering,
respectively FTC_SWITCHING for the Active side and FTC_SYNCHRONIZING
for the Standby side. Within the FTC_SWITCHING (respectively
FTC_SYNCHRONIZING) state, the user plug-in can then perform whatever
processing it has to perform in order to move to the FTC_ACTIVE (respectively
FTC_HOT_STANDBY) state.
During the transient states (FTC_SWITCHING, FTC_SYNCHRONIZING, and
FTC_STOPPING), the user plug-in should, in particular, manage the state of its
PCA connections. In order to be operational, they have to be both established and
then enabled.
Once it has completed the state transition, the user plug-in informs the PIC either
directly via the return code of the PIC_PluginHA::newState() method, or if it
requires more processing, by calling the PIC_PluginHA::stateCompleted()
method later.
312

Chapter 8

PIC/AG - Introduction
HA API
Connection Establishment
PCA connection establishment can only be performed on PCA_Client initiative.
Thus, the user plug-in acting as a PCA_Server has no control on PCA connection
establishment. However, if it acts as a PCA_Client, it should perform connection
establishment during its transient state transition (as appropriate).
Enabling/Disabling
Establishment of a PCA connection is not enough for traffic to be allowed over it.
The PCA connection must also be enabled.
In contrast with establishment, enabling has to be performed on both the client and
the server sides, and on client and server initiative, respectively. After its
establishment, by default, the PCA Connection is disabled on both sides.
On its side, the user plug-in (shared library) has thus the possibility to allow or
prevent traffic on its PCA connections, whether as a client or as a server, by
enabling or disabling them. During the transient state, the user plug-in should enable
(respectively disable) the PCA connections on its side, according to whether it wants
to allow (respectively prevent) traffic in the HA state it is going to (FTC_ACTIVE
or FTC_HOT_STANDBY).
For example, it can decide to enable (respectively disable) all its connections during
the FTC_SWITCHING (respectively FTC_SYNCHRONISING or
FTC_STOPPING) HA State.
The user plug-in enables connection by calling the PCA_Server::enable() or
the PCA_Client::enable() method depending on whether it is acting as a
server or as a client for the corresponding PCA connection.
The user plug-in disables connection by calling either the
PCA_Server::disable() or the PCA_Client::disable() method.
Switchover
In the case of a switchover:

the current FTC_HOT_STANDBY goes:


FTC_HOT_STANDBY --> FTC_SWITCHING --> FTC_ACTIVE
During the FTC_SWITCHING state, the user plug-in should enable its
PCA_Server and PCA_Client connections, as appropriate.

the current FTC_ACTIVE can either go:


FTC_ACTIVE --> FTC_STOPPING --> FTC_HOT_STANDBY

Chapter 8

313

PIC/AG - Introduction
HA API
In this case, it is recommended that the user plug-in perform the following
actions during the FTC_STOPPING state (using the appropriate PCA
methods):
Step

1. Flush its inbound queue (delete its messages).

Step

2. Flush the PCA Server(s).

Step

3. Close all its sessions (so it needs to keep a list of its sessions).

Step

4. Disable its PCA Server(s).


or it can go:
FTC_ACTIVE --> FTC_STOPPING --> FTC_DOWN
which corresponds to:

Step

1. It executes the PIC_PluginHA::fault() method during the FTC_STOPPING


state.

Step

2. Consequently, it goes FTC_DOWN and the user user plug-in object is deleted.

Step

3. It restarts clean, that is, once in the FTC_DOWN state, depending on its HA
configuration, it may be respawned automatically by the FTC. In this case, it goes:
FTC_BOOTING --> FTC_SYNCHRONIZING --> FTC_HOT_STANDBY
Switchback
In the case of a switchback, there is another switchover (so the original
FTC_ACTIVE becomes FTC_ACTIVE again, and the original
FTC_HOT_STANDBY becomes FTC_HOT_STANDBY again). The user plug-in
behavior during a switchback is as described above for a switchover.

314

Chapter 8

PIC/AG - Introduction
Registry API

Registry API
The Registry API is responsible for the retrieval of some PIC attributes.
This API is independent of the other APIs and is not linked to them. In comparison
to the other APIs, it is relatively simple. It is designed to enable the user plug-in to
retrieve some attributes. This Registry API can be used anywhere in the user plug-in
code.
The object model is shown in Figure 10-1, C++ Structure of PIC API Classes.

Class
PIC_Registry is the interface class to the Registry API.

Purpose
The Registry API provides access to some PIC attributes, in particular, the user
plug-in name.

Chapter 8

315

PIC/AG - Introduction
PCA (Plug-in Communication API)

PCA (Plug-in Communication API)


The PIC supplies a communication API (known as the PCA) and an Execution API.
These are illustrated in Figure 8-8, PCA Classes (as Generally Used in a Plug-in).
The PCA supplies the basic C++ classes that the user plug-in needs for
communication with other user plug-ins. For more details, see Figure 9-2, The
PCA Object Model as Used in a Plug-in.
Figure 8-8

316

PCA Classes (as Generally Used in a Plug-in)

Chapter 8

PIC/AG - Introduction
PCA (Plug-in Communication API)
The user plug-in developer should customize these to obtain the behavior that is
required. In particular, the user plug-in developer should develop the areas shown in
yellow in Figure 8-8, PCA Classes (as Generally Used in a Plug-in).
The user plug-in developer can also create and use application-specific classes that
are shown as MyAppli_Classes in the figure.

Classes
The following are some of the classes made available to the user:

PCA_Server: This is the basic server interface class to the PCA.

PCA_Client: This is the basic client interface class to the PCA.

PCA_Queue: On the inbound path, the PCA_Server delivers received messages


to the inbound queue which is an object of the PCA_Queue class.

PCA_Message: This is the class for messages exchanged between PCA users.

Communication Setup and Control


From the user plug-in point of view, one or more clients (other user plug-in
applications) can connect to the user plug-in.
For communications setup and management, the PCA allows you to:

start a user plug-in server (i.e. PCA_Server) to accept client connections.

enable/disable client connections to this server.

inform the user plug-in about each new client connection.

inform the user plug-in about each client disconnection.

act as a client of another user plug-in server.

Client connection/disconnection notifications are provided only for management


purposes. Connection notification allows the user plug-in to accept or reject a new
client. Disconnection notification allows the user plug-in to decide how to process
possible broken dialogues.
The server cannot disconnect a client. Disconnection occurs on client initiative only.
Exchanges of messages between the server and a connected client can occur only
once the connection has been enabled. Enabling has to be performed on both sides
of the connection (that is, by the server and by the client). The PCA allows the client
(which is a PCA_Client) to do this. Each side can thus control when traffic on the
connection starts or is interrupted.

Chapter 8

317

PIC/AG - Introduction
PCA (Plug-in Communication API)

Communication
Once a session is created, the user plug-in can freely send or receive messages on
the session. In the outbound direction, the user plug-in does not specify the client to
which the message is sent. In the inbound direction, the user plug-in does not need
to know which client originated the message. This is managed internally by the PCA
and is hidden from the user.
The PCA can:

handle message contents.

send messages within sessions.

receive messages within sessions.

restrict the inbound message flow (Receive flow control).

Management
The management interface can retrieve or set Inter Process Communication (IPC)
parameters, such as buffer size, and enable time-stamping of messages for
performance monitoring purposes.

318

Chapter 8

PIC/AG - Introduction
TimerLib API

TimerLib API
If the user plug-in needs timers, then it must use the TimerLib API to handle them.
The TimerLib library is dynamically linked with the PIC.
The TimerLib API is declared on an HP OpenCall system in the file
/opt/OC/include/TimerLib.h. To use the HP OpenCall TimerLib API, insert
the following line in the user plug-in source code:
#include <TimerLib.h>

This API enables you to set (and cancel) a timer.


There are two separate kinds of pools of timers:

A single PIC Pool of Timers

Optional Plug-in Pools of Timers

PIC Pool of Timers


In this case, the pool of timers is in the PIC. There is a single instance of the PIC
pool of timers. See the following figure.
Figure 8-9

The PIC Pool of Timers

The timer is set by the plug-in, but it pops in the PIC context.
Chapter 8

319

PIC/AG - Introduction
TimerLib API
The number of these timers is limited. The limit applies to the total number of timers
(the PICs own timers + the user plug-in timers). For the limit, see the
HP OpenCall SS7 Release Notes.
When using the PIC pool of timers, the PIC itself takes care of the API scheduling.
Therefore, the user plug-in must not use the TIMER_handler() and the
TIMER_select_time() functions. These functions are called by the PIC.
Table 8-2 on page 321 shows the functions available in the TimerLib API in the case
where the PIC pool of timers is used.
Table 8-2

The PIC Pool of Timers - TimerLib API Functions


Function

Purpose

TIMER_cancel_timer()

Cancel a timer that is currently running.

TIMER_handler()

Process timer expirations.


This is called by the PIC only.

TIMER_select_time()

Set a pointer to a timeval to the correct value.


This is called by the PIC only.

TIMER_set_timer()

Set a timer.

TIMER_set_timer_t()

Set a timer.

TIMER_ts_add()

Add two times.

TIMER_ts_equals()

Compare two times.

TIMER_ts_lessthan()

Compare two times.

TIMER_ts_now()

Get the current system time.

TIMER_ts_sub()

Subtract two times.

320

Chapter 8

PIC/AG - Introduction
TimerLib API

Plug-in Pools of Timers


In this case, the pools of timers are in the user plug-in. See the following figure.
Figure 8-10

Plug-in Pool of Timers

The number of these timers has no explicit limit except the one given by the user
when initializing the pool of timers (that is, when calling the
OCTIME_init_module(3) function in the plug-in constructor code).
The timer is set by the plug-in and it pops in the plug-in context, when the plug-in
calls the OCTIME_handler(3) function.
Armed timers are guaranteed to pop:
1. in the thread where they were armed.
2. when the OCTIME_handler(3) function is called.
When using plug-in pools of timers, the plug-in code is in charge of the maintenance
of the pool. See Table 8-3 on page 323 for the details.
Table 8-3 on page 323 shows the functions available in the TimerLib API in the case
where a user plug-in pool of timers is used.
Table 8-3

Plug-in Pool of Timers - TimerLib API Functions


Function

OCTIME_cancel_timer()

Chapter 8

Purpose
Cancel a timer that is currently running.

321

PIC/AG - Introduction
TimerLib API
Table 8-3

Plug-in Pool of Timers - TimerLib API Functions (Continued)


Function

Purpose

OCTIME_destroy_module()

Delete the dedicated pool of timers.

OCTIME_handler()

Process timer expirations. This must be called by the


plug-in for each initialized plug-in pool of timers, in the
connectionHandler() plug-in implementation.

OCTIME_init_module()

Start a new dedicated pool of timers. This must be called


from the plug-in constructor.

OCTIME_select_time()

Set a pointer to a timeval to the correct value. This must


be called for each initialized plug-in pool of timers in the
selectMask() plug-in code.

OCTIME_set_timer()

Set a timer.

OCTIME_set_timer_t()

Set a timer.

OCTIME_ts_add()

Add two times.

OCTIME_ts_equals()

Compare two times.

OCTIME_ts_lessthan()

Compare two times.

OCTIME_ts_now()

Get the current system time.

OCTIME_ts_sub()

Subtract two times.

322

Chapter 8

PIC/AG - Introduction
Changing the User Plug-in

Changing the User Plug-in


The HP OpenCall PIC Framework does not provide a specific
administration/management tool to change a user plug-in.
To change a user plug-in, you:

Chapter 8

Step

1. Stop the PIC.

Step

2. Change the user plug-in shared library. For example, replace the old version of the
user plug-in shared library with the new version, or change the path in the used
instance of pic.conf to point to the new version.

Step

3. Modify the configuration (if necessary).

Step

4. Restart the PIC.

323

PIC/AG - Introduction
Starting/Stopping the User Plug-in

Starting/Stopping the User Plug-in


A user plug-in can be monitored like any other HP OpenCall process (if managed by
the FTC).
The PIC can be managed through the FTC to start/stop a user plug-in.

Using Command Lines


To start a user plug-in, you add the PIC process to the list of processes controlled by
the FTC. You do this using the cfgPlatform command. In turn, the PIC loads and
starts the user plug-in.
The RunString field is used to specify the command line to start the process. See
the section on Configuring PIC/AG in the HP OpenCall SS7 Operations Guide.
While testing/debuging, you could use the PIC run string to start the PIC.
To force a switchover, you use the ocftcontrol command.
To stop a user plug-in, you use the ocftcontrol command to stop the PIC. In
turn, the PIC stops the user plug-in.

324

Chapter 8

PIC/AG - Introduction
Product Environment

Product Environment
Hardware Requirements
The HP OpenCall Plug-in runs on HP-UX (versions 11.0 and 11i) and Linux.
The required hardware configuration is specific to each user plug-in and must be
determined by the user plug-in developer. These requirements depend on what the
user plug-in application actually does.
However, the fact that the user plug-in runs on the same platform as HP OpenCall
means that the user plug-in shares hardware resources with HP OpenCall.
As far as possible, the resources used by the user plug-in(s) and HP OpenCall
should be dedicated to prevent possible resource conflicts. In particular, this applies
to the LAN, the SCSI bus, memory, CPU, etc.
For hardware resource availability, refer to the appropriate HP OpenCall
documentation.

Other Equipment
Typically, a user plug-in will interface with an external device, either hardware or
software, as shown in Figure 8-2. This is the responsibility of the user plug-in
developer.

Chapter 8

325

PIC/AG - Introduction
Usability

Usability
The purpose of this section is to provide usability and operability information about
the PIC and the user plug-in (shared library).

Upgrade
The Plug-in API provides a C++ interface. It clearly isolates PIC and API code from
developer code:

The user plug-in (shared library) requires to be updated and re-compiled each
time the API specification is modified.

The user plug-in (shared library) does not require to be re-compiled when the
API implementation is modified.

The user plug-in (shared library) does not require to be re-compiled when the
PIC implementation is modified.

The user plug-in (shared library) is not loaded/unloaded dynamically. The PIC is
started with a specified user plug-in as a shared library. To upgrade to a new user
plug-in (shared library) version, you must restart the PIC.

PCA Message Contents


The PCA can transfer any data transparently.
The user plug-in developer must work with the following knowledge of PCA
behavior:

326

No check is performed on exchanged messages by the PCA. It is possible to


send invalid messages to the remote side. It is the responsibility of each side to
check the validity of exchanged messages, and these must be checked either
before transmission or on reception.

The PCA and the PIC do not check the contents of messages. The coding and
decoding of the data contents of messages is the responsibility of the user
plug-in developer. For example, a message could hold a heading data part
encoded in Q.931 and a trailing data part encoded in PER, as long as both the
user plug-ins agree that this is the format to be used.

Chapter 8

PIC/AG - Introduction
Usability

Plug-in Management
The following limitations apply:

The Plug-in API provides no management facilities.

The maximum number of PICs is a parameter of HP OpenCall.

High Availability Framework


The PIC runs on the same platform as HP OpenCall and can switch along with
HP OpenCall or be managed independently.

Chapter 8

327

PIC/AG - Introduction
Exception Handling

Exception Handling
On Linux, the g++ compiler is used.
The user plug-in programmer has to deal with exceptions raised either by the PIC or
by the user plug-in.
There are two cases of exceptions management:

Exceptions managed by the PIC.

Exceptions managed by the user plug-in.

How the PIC Manages Exceptions


The PIC (and the PCA, PIC Execution, PIC HA, and PIC Registry APIs) do not
raise any PIC specific exceptions. However, other kinds of exceptions, for example,
the one coming from STL functions as bad_alloc, can be raised.
Any bad_alloc exceptions raised by new or STL functions are caught internally
in the PIC. Such an exception is converted to a specific explicit status returned by
the API functions.
At the PIC main level, there is a general exception handler that catches any uncaught
exceptions, produces a trace message and makes the whole PIC go down. Then,
depending on the HA policy, the PIC will either be re-spawned on the same host, or
will switchover to the standby host.

How the Plug-in Should Manage Exceptions


There are two basic rules to follow:

328

Since the PIC, the PCA, and the PIC APIs (Execution, HA, and Registry), raise
only fatal exceptions, the user plug-in does not need to use a catch mechanism.
Basically, when such exceptions are raised, the PIC (and thus the user plug-in)
is going down.

Since all exceptions caught by the general exception handler are fatal, the user
user plug-in code should not raise non-fatal exceptions to the PIC.

Chapter 8

PIC/AG - Introduction
Plug-in Tutorial

Plug-in Tutorial
A tutorial is supplied with the HP OpenCall PIC Framework.
The tutorial is located in the /opt/OC/tutorials/PIC directory.

CAUTION

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

This tutorial contains an example of a user plug-in (shared library).


For further explanation of the HP OpenCall Plug-in feature, you are recommended
to refer to this tutorial. In particular, you should refer to the tutorial to see how to run
a user plug-in interactively.

Chapter 8

329

PIC/AG - Introduction
Plug-in Tutorial

330

Chapter 8

PIC/AG - Using the PCA API


This chapter describes the operation of the PCA (Plug-in Communication API) and
how it interfaces to a user plug-in.

Chapter 9

331

PIC/AG - Using the PCA API


High Availability (HA) and the PCA

High Availability (HA) and the PCA


This section describes the HA model for the HP Opencall Plug-in and how it
impacts the PCA.

HA Model
Typically, in a configuration with Active and Standby platforms, two types of
connection are opened through the PCA, as shown in Figure 9-1:

Figure 9-1

Active connections are used to exchange data with the Active clients.

Standby connections are opened by Standby clients but do not carry data.

Active and Standby Connections

A Standby connection is used to improve the performance of a possible switchover.


It can be activated in a much shorter time than opening a new connection.
A connection is Active if both the client and the server side are Active. A connection
is Standby if both the client and the server are Standby. Otherwise, the connection is
in a transient state. Exchange of messages is allowed only on Active connections.

332

Chapter 9

PIC/AG - Using the PCA API


High Availability (HA) and the PCA

Connection Enabling
The PCA allows the user to enable a connection when it enters the HA Active state.
Conversely, the user can also disable a connection when it exits the Active state to a
Standby state or any other state.
These features are implemented by the PCA_Server::enable(),
PCA_Client::enable(), PCA_Server::disable(), and
PCA_Client::disable() methods.
Enabling or disabling a connection does not impact the establishment of the
connection, it only impacts the exchange of messages above the connection. Note
also that Plug-in HA state transitions are driven by the PIC API and are outside the
scope of this chapter.
If a Server or Client connection is not enabled, you cannot create a new session and
if you try you will get the PCA_NOT_ACTIVE error code.
An attempt to send a message on an inactive connection returns an error. This
returns an immediate error status if the local side is not Active, or a delayed error
message if the remote side is not Active (this should remain transient).
Default States
The default state of a server is disabled. A user plug-in should always call the
enable() method during user plug-in server setup. This can be done at any time
after the server object is created regardless of whether or not another client is
already connected. The state automatically applies to all present and future client
connections.
The default state of a client is disabled. A user plug-in should always call the
enable() method during user plug-in client setup. This can be done at any time
after the client object is created regardless of whether the client is already connected
to a server or not.

Chapter 9

333

PIC/AG - Using the PCA API


PCA Description

PCA Description
This section describes the PCA user-aware classes and how to setup a user plug-in
server. It also describes how clients connect to this server and how messages can be
exchanged.
Note that a user plug-in does not only interface with the PCA. The PCA only
addresses the communication aspects with other clients. A user plug-in must also
interface to the Plug-in Container execution interface (see Chapter 10, PIC/AG Using the PIC APIs, on page 371) for scheduling and HA driving purposes.
For scheduling, see Plug-in Scheduling on page 377.
For HA, see Plug-in HA Management on page 381.

Object Model
The PCA has an object-oriented architecture. The object model of the PCA is shown
in Figure 9-2.

334

Chapter 9

PIC/AG - Using the PCA API


PCA Description
Figure 9-2

Chapter 9

The PCA Object Model as Used in a Plug-in

335

PIC/AG - Using the PCA API


PCA Description
The PCA provides a number of classes that can be used by the user plug-in as is, and
a number of base classes that are intended to be customized by developers for
specific purposes.
These base classes usually have a default implementation that can be left
unmodified by developers to provide the functionality of the class, provided the
default meets their requirements.
In Figure 9-2, the Plug-in Body block depicts the user-specific classes that are not
strictly related to the PCA but that are required to implement the actual processing
part of the user plug-in. The Plug-in body is the user of the PCA.
The following classes are made available to the user:

NOTE

PCA_Queue: On the inbound path, the server delivers received messages to the
inbound queue which is an object of the PCA_Queue class. The user plug-in
then reads messages from the queue when it is scheduled. PCA_Queue is a
fixed-length queue with high and low watermarks for flow control
management.

PCA_Message: This is the class for messages exchanged between user


plug-ins. A message consists of a number of chained buffers together with read
and write pointers. The PCA_Message class provides basic data handling
methods such as read and write. It also provides structured message handling
methods for building and parsing the headers of messages.
A message read is performed with PCA_Queue::get().
A message write is performed with PCA_Server::send() or with
PCA_Client::send().

Do not use the PCA_Queue::put() method. The PCA_Queue::put() method is


used by the PCA to fill the user plug-in inbound queue with messages received from
the external PCA clients. Then, the user plug-in can retrieve these messages using
the PCA_Queue::get() method, and answer them using one of the send()
methods. The user plug-in should not add messages to its own inbound queue.

The following classes are base classes that can be customized (but this
customization is optional) by the user plug-in developer:

336

PCA_Server: This class acts both as a base class and an API access class
(server interface class to the PCA). It allows the setup of a user plug-in server
and the exchange of messages with clients. You may customize the
PCA_Server to implement your own connection management (and flow control
management). If you implement your own connection management, the user

Chapter 9

PIC/AG - Using the PCA API


PCA Description
plug-in is then notified of each connection attempt and can accept or reject such
requests. The PCA_Server is also notified of disconnection. In addition, the
outbound path and session flow control mechanisms (see below) interface with
this class. A user plug-in can possibly define many servers if it offers many
services.

PCA_Client: This class acts both as a base class and an API access class
(client interface class to the PCA). It allows a user plug-in to act as a client of a
user plug-in server and to exchange messages with it. You can refine some
member functions for connection management and flow control management.
If you refine the PCA_Client to implement your own connection management,
then the PCA_Client is notified of connection open and close state
changes. In addition, the outbound path and session flow control mechanisms
(see below) interface with this class.

PCA_Session: The session is a basic concept of the PCA. A session identifies


a set of related messages (for example, an answer message related to a previous
question message). The same session object is attached to all messages within
the same set. A session is uniquely associated with one PCA connection
between a user plug-in server and a client. Plug-in developers can define their
own session object to add context sensitive information to the base session
class. Then, each time a message is processed it can easily retrieve information
associated with the dialogue.

PCA_SessionFactory: Session objects are allocated internally by the PCA.


If a developer customizes the base PCA_Session class, the developer must
also provide a Session Factory object which is used by the PCA to create and
delete the users session when required.

PCA_BufferAllocator: PCA messages consist of chained buffers. If


developers find it efficient to control the allocation of such buffers (for
example, buffers allocated from a specified pool or from shared memory), then
the developers must define their own PCA_BufferAllocator inherited
object to perform the allocation. Many such objects can be provided if many
pools are used, depending on the purpose of each messages. If developers do
not need any special allocation mechanism, they can use the default
implementation of the PCA_BufferAllocator class which allocates buffers
from the OS heap. In this case, they do not need either to understand the
chained buffers structure of the PCA messages or how to handle it.

Typically, the user plug-in developer customizes PCA_Server (to customize the
connection and/or flow control) and PCA_Session (and consequently,
PCA_SessionFactory) to associate a context with a session.

Chapter 9

337

PIC/AG - Using the PCA API


PCA Description
Plug-in Server and Client Names
Plug-in servers are addressed by clients via physical addresses in the form:
<tcp-port>@<hostname> or <tcp-port>@<IP-address>.

338

Chapter 9

PIC/AG - Using the PCA API


Server Setup

Server Setup
First, a server object must be setup to provide a communication capability with other
clients.

Server Initialization
A server is setup by creating an object from the PCA_Server class, or from a
user-defined derived class. The purpose of deriving a user class is for client
connection management and session flow control management. This is addressed in
Client Connection Management on page 341 and Session Management on
page 347.
The newly created PCA_Server object must first be initialized with the
PCA_Server::init() method. It is associated with the following parameters:

Chapter 9

The inbound queue:


The inbound queue is an object from the API-provided PCA_Queue class,
created using the PCA_Queue::create() method. It stores the messages
received by the PCA_Server before they get processed by the user plug-in.
The parameterization of this queue, performed by calling the
PCA_Server::init() method, directly impacts inbound flow control
behavior. This is discussed in Receiving Messages on page 368.
You (the user plug-in developer) provide the inbound queue. This is because
when a user plug-in is made up of many user plug-in servers, you can decide
whether to use a single queue for all servers or many queues (depending on the
specific requirements of the application). In the future, you may also want to
customize this interface class.

The user session factory:


If you define your own session class, you must also define your own session
factory class inheriting from PCA_SessionFactory. This is discussed in
Session Management on page 347. This argument is a pointer to a
user-session factory object. If you have no specific requirements concerning
sessions, you may simply pass a pointer to a PCA_SessionFactory object.

The user buffer allocator for inbound messages:


To optimize or customize memory usage for PCA messages, you can specify
buffer allocators.
This argument is a pointer to a user buffer allocator object. If you have no
specific requirements about the buffer allocator, you can pass a NULL pointer
or a pointer to a PCA_BufferAllocator object.

339

PIC/AG - Using the PCA API


Server Setup

This parameter is provided only for inbound messages. For outbound messages,
the buffer allocator is associated with the message at message construction
time, see Buffer Allocator on page 364.

The outbound queue parameterization:


To cope with outbound overflow conditions, the PCA maintains internally a
PCA_Queue-like outbound queue. This fixed-size queue is parameterized with
a low watermark and a high watermark. These parameters directly impact the
transmit flow control behavior. This is discussed in Session Management on
page 347 and Sending Messages on page 366.

The PCA_Server::init() method returns a status that indicates whether or not


the operation succeeded. The operation can only fail due to internal memory
allocation problems. In case of failure, the user plug-in developer should check the
consistency of queue-sizing parameters.

Server Opening
Once initialized, the PCA server must be opened by attaching it to a user plug-in
server name as a physical address.
Opening a server is performed by the PCA_Server::open() method. It succeeds
unless there is an internal memory allocation problem or the required name is
unknown.
Once opened successfully, a server is ready to receive client connection requests.
This is detailed in Client Connection Management on page 341.

NOTE

After a correct open operation on the Server, you must enable it before sending
traffic (that is, before session creation).

Server Closing
In the current release of HP Opencall, dynamic loading and unloading of the user
plug-in is not addressed. Servers are not intended to be closed by software after
being opened. The operator must kill the PIC process instead.

340

Chapter 9

PIC/AG - Using the PCA API


Server Setup
However, the PCA provides a simple lazy-closing mechanism. When no client is
connected (none connected yet, or all disconnected), you can call
PCA_Server::close() to stop the server. Subsequently, the server can be
re-started by calling PCA_Server::open() again, or the object may be deleted if
it is no longer useful.
The operation fails if one or more clients are connected. The user plug-in cannot
force the disconnection of clients.

Server IPC Parameterization


The low-level communication layer between the user plug-in server and the clients
can be parameterized on a server basis for performance purposes. This can be done
at server-setup time, or dynamically once the server is connected to its clients, as
long as consistency rules on parameter values are respected.
Changing the server Inter Process Communication (IPC) parameters impacts all
present and future low level connections between the server and each peer client.
Low-level connections cannot be individually configured.
The IPC methods include:

PCA_Server::setCnxLowTransmitTime()

PCA_Server::setCnxHighTransmitTime()

PCA_Server::setCnxEnableBuffering()

PCA_Server::setCnxRecvBufferSize()

PCA_Server::setCnxSendBufferSize()

Client Connection Management


Connection is always initiated by the client side. A user plug-in cannot initiate
connection to the client. It can only set up a server and wait for connections.
Client connection management can optionally be performed by customizing the
PCA_Server base class. Three virtual methods are defined for this purpose:

Chapter 9

PCA_Server::authorizeClient()
This method allows the server to accept or reject each connection attempt from
a client. The decision can be made from the number of connected clients or the
identity of the new client. The default implementation is accept.

341

PIC/AG - Using the PCA API


Server Setup

PCA_Server::clientConnected()
This method informs the server that a client previously authorized by
PCA_Server::authorizeClient() is now connected. The default
implementation is NOP (no operation).

PCA_Server::clientDisconnected()
This method informs the server that either a client previously authorized failed
to connect, or that a running client disconnected on its own or due to an IPC
error. The default implementation is NOP.

Within all these methods, a client is identified by a unique address as a literal string.
This address is a physical address, made up of a TCP port and IP address or
hostname, terminated by a trailing '!'. This address is provided by the PCA layer of
the connected client. The TCP Port is usually allocated dynamically at connection
setup. The client itself has no control on the address that is provided.
The default implementation of connection management always accepts connection
requests from clients, and logs the effective connections and
disconnections.
The user plug-in cannot exchange messages with clients before the first client is
connected.
The connection management interface indicates when the user plug-in can start
communicating with its clients.
Note that all clients of a user plug-in server are equivalent. There is no way to
specify the destination client for an outgoing session.

342

Chapter 9

PIC/AG - Using the PCA API


Client Setup

Client Setup
First, a client object must be setup to provide a communication capability with a
user plug-in server. This object is needed only if the user wants to connect to another
user plug-in server.

Client Initialization
A client is setup by creating an object from the PCA_Client class, or from a
user-defined derived class. The purpose of deriving a user class is for server
connection management and session flow control management. This is addressed in
Client Connection Management on page 341 and Session Management on
page 347.
The newly created PCA_Client object must first be initialized with the
PCA_Client::init() method.
It is associated with the following parameters:

Chapter 9

The target server name:


The PCA allows a user to pass a physical address (tcpPort@ipAddress).
Note that the target server is defined at client initialization. A PCA_Client can
connect to one and only one server and this cannot be changed after the
initialization.

Literal information about the client:


This string will be passed to the destination server as an argument to the
PCA_Server::clientConnected() method. Within this method, the
server also receives the name (that is, the address) of the client. However, this
address, which is usually a physical address of the form TCP port @ IP address,
is provided by the PCA layer of the client. The client itself has no control on the
provided address. If it wants to identify itself to the server, it can use this literal
information.

The inbound queue:


The inbound queue is an object from the API-provided PCA_Queue class,
created using the PCA_Queue::create() method. It stores the messages
received by the PCA_Client before they get processed by the user plug-in.
The parameterization of this queue, performed by calling the
PCA_Client::init() method, directly impacts inbound flow control
behavior. This is discussed in Receiving Messages on page 368.

343

PIC/AG - Using the PCA API


Client Setup

The user session factory:


If you define your own session class, you must also define your own session
factory class inheriting from PCA_SessionFactory. This is discussed in
Session Management on page 347. This argument is a pointer to a
user-session factory object. If you have no specific requirements concerning
sessions, you may simply pass a pointer to a PCA_SessionFactory object.

The user buffer allocator for inbound messages:


To optimize or customize memory usage for PCA messages, you can specify
buffer allocators.
This argument is a pointer to a user buffer allocator object. If you have no
specific requirements about the buffer allocator, you can pass a NULL pointer
or a pointer to a PCA_BufferAllocator object.
This parameter is provided only for inbound messages. For outbound messages,
the buffer allocator is associated with the message at message construction
time, see Buffer Allocator on page 364.

The outbound queue parameterization:


To cope with outbound overflow conditions, the PCA maintains internally a
PCA_Queue-like outbound queue. This fixed-size queue is parameterized with
a low watermark and a high watermark. These parameters directly impact the
transmit flow control behavior. This is discussed in Session Management on
page 347 and Sending Messages on page 366.

The session parameterization:


Session management is parameterized with the maximum number of sessions
needed (originated from both sides) and the maximum number of sessions
originated from the client side. These parameters (of the
PCA_Client::init() method) should be set large enough to cope with all
situations. They cannot be changed after the initialization. They involve neither
significant memory consumption nor any processing overhead either at the
client side or the server side.

The PCA_Client::init() method returns a status that indicates whether or not


the operation succeeded. The operation can only fail due to internal memory
allocation problems. In case of failure, the user plug-in developer should check the
consistency of queue-sizing parameters.

Client Opening
Once initialized, the PCA client must be opened, that is, it must try to connect to its
target server.

344

Chapter 9

PIC/AG - Using the PCA API


Client Setup
Client opening is performed by the PCA_Client::open() method. It succeeds
unless there is an internal memory allocation problem or the required name is
unknown.
Connection setup completes when the PCA calls either the
PCA_Client::stateOpened() method or the
PCA_Client::stateClosed() method. See Server Connection Management
on page 346.
Once opened successfully (that is, PCA_Client::stateOpened() has been
called), a client is ready to communicate with its target server. This is detailed in
Server Connection Management on page 346.

NOTE

After a correct open operation on the client, you must enable it before sending traffic
(that is, before session creation).

Client Closing
To disconnect from its target server, the client calls the PCA_Client::close()
method.

Client IPC Parameterization


The low-level communication layer between the client and the server can be
parameterized for performance purposes. This can be done at client-setup time, or
dynamically once the client is connected to its server, as long as consistency rules on
parameter values are respected.
Changing the client IPC parameter impacts present and future low level connections
between the client and its server. A client can connect to one and only one server
(the target server defined at client initialization). However, the client can
open/close/re-open this connection several times, for example, in case of connection
failure.
The IPC methods include:

Chapter 9

PCA_Client::setCnxLowTransmitTime()

PCA_Client::setCnxHighTransmitTime()

PCA_Client::setCnxEnableBuffering()

PCA_Client::setCnxRecvBufferSize()

345

PIC/AG - Using the PCA API


Client Setup

PCA_Client::setCnxSendBufferSize()

Server Connection Management


Connection with the server is always initiated at the client side by calling the
PCA_Client::open() method. The termination of the PCA_Client::open()
method does not correspond to the establishment of the connection. If there is no
error (returned status: NO_ERROR) in the processing of the
PCA_Client::open()method, the PCA has acknowledged the request to
establish the connection and handles the request asynchronously. It then notifies the
client of the connection state change by asynchronous calls to virtual functions as
detailed below.
Connection management can optionally be performed by customizing two virtual
methods of the PCA_Client base class defined for this purpose:

PCA_Client::stateOpened()
When the connection actually becomes open, the PCA calls this method to
notify the client of this event.

PCA_Client::stateClosed()
When the connection is closed, the PCA calls this method to notify the client of
this event. This may occur either in the setup phase or once the connection is
established.

The default implementation of these connection management methods is NOP (No


Operation).

346

Chapter 9

PIC/AG - Using the PCA API


Session Management

Session Management
Messages are exchanged between a user plug-in server and a user plug-in client
within sessions.
A session identifies a set of related messages.
It is the session that identifies the client-server connection on which a message is
exchanged, as a session is associated with one and only one connection. Message
routing between the user plug-in server and its clients is based on the session. All
messages within a session are exchanged with the same client. There is no way for
the user plug-in to know with which client the session is associated. This is
transparent to the user plug-in and fully managed by the PCA.
From a programming point of view, a session is an object. Each message exchanged
with the client references a session object.
This section shows how users can define their own sessions, and then manage them
for exchanging messages with the connected user plug-ins.

Customizing Plug-in Sessions


If you (a user plug-in developer) needs to add contextual information to a session,
you can specialize the PCA_Session base class. Since sessions are created
internally by the PCA, you must then provide your own session factory class
inheriting from the PCA_SessionFactory base class, in order to allocate and
release objects from this new class. This requires the
PCA_SessionFactory::createSession() and
PCA_SessionFactory::destroySession() methods.
The specialized session factory can also perform some other tasks. For example, to
open a session a user plug-in specific external device must be setup, you can do this
in the PCA_SessionFactory::createSession() method, and you can undo it
in the PCA_SessionFactory::destroySession() method.
The user plug-in developer is free to implement all suitable tasks, provided they
remain compliant to the generic user plug-in programming guidelines.

Session Type
Session creation can be initiated either by the client side, or by the server side,
depending on who sends the first message of the session. This session type (CALLER
or CALLEE) can be found with the PCA_Session::getType() method.

Chapter 9

347

PIC/AG - Using the PCA API


Session Management

Session States
A session can be in one of the following 4 possible states:

ACTIVE

BROKEN

REJECTED

ZOMBIE

You can retrieve the state of a session using the PCA_Session::getState()


method.
The normal state of a session is ACTIVE.
The state of session can change depending on:

the state of the connection between the user plug-in server and a client (over
which the session is used to send messages),

the condition of reception of messages sent within this session,

the condition of deletion of the session object.

The state mechanism for a session is shown in Figure 9-3, State Machine for a
Session.

348

Chapter 9

PIC/AG - Using the PCA API


Session Management
Figure 9-3

State Machine for a Session

ACTIVE State
This is the default state after successful creation. ACTIVE sessions are used to
exchange messages between the user plug-in (shared library) server and the client.

Chapter 9

349

PIC/AG - Using the PCA API


Session Management
BROKEN State
Any session is uniquely bound to one connection between a user plug-in (shared
library) server and a client.
Sometimes, a client can disconnect from the server with some sessions being left
open. For example, the disconnection may occur on client initiative, or due to an
IPC failure, or to a client being re-spawned.
In such cases, on the server side, the sessions related to the connection are said to be
broken and are automatically moved by the PCA to the BROKEN state. However,
on the client side, the corresponding sessions are automatically closed by the PCA.
There is no concept of broken sessions on a client. This concept is specific to the
server.
For example, the disconnection may occur on the client initiative, or due to an IPC
failure, or to a client being re-spawned.
You should not attempt to send messages on a session that is in a BROKEN state.
Even if the client re-opens the connection to the server, it is not possible to use the
broken sessions to exchange messages again with this client (as the sessions on the
client side are automatically closed upon disconnection). You are recommended to
delete these BROKEN sessions.
REJECTED State
A message sent from the server to a client, or from a client to the server, within a
session, may be rejected by the receiving side (see Session Reject on page 356).
This results in an error message being returned to the sender (see Messages on
page 359) and the session is said to be rejected.
ZOMBIE State
In some transient states, a session object may still exist but will be deleted soon by
the PCA (see Session Deletion on page 352 and Session Locking on page 354).
The session is then said to be a zombie session.
This happens when the user plug-in requests the PCA to delete a session object (via
a close() or abort() method), and the PCA cannot delete the session object
because it is currently locked or it is still referenced by some messages. In such
cases, the PCA acknowledges the request by changing the state of the session to
ZOMBIE.
The PCA will effectively delete the session object as soon as it is no longer locked,
or referenced by messages. When this will occur is effectively outside of the control
of the user plug-in (shared library) application. For example, if the session is

350

Chapter 9

PIC/AG - Using the PCA API


Session Management
referenced by a message currently in the outbound-queue waiting to be delivered,
the reference is removed when the PCA deletes the message, following its delivery.
The user plug-in cannot control when the PCA will delete this message. The user
plug-in can use locks to prevent the session from being deleted if it still needs access
to it. However, if the user plug-in unlocks a session or deletes a message referring to
it, this can potentially lead to the deletion of this session object.

Session Creation
Sessions can be created either by the server or by a client, depending on the side that
initiates the dialogue (that is, sends the first message using this session). The sender
creates an outgoing session by using either the PCA_Server::openSession(),
or the PCA_Client::openSession() method.
The reception of the first message using this session automatically triggers the
creation of a corresponding session object on the receiver side. The creation of the
incoming session is transparent to the receiver.
In both cases, the PCA internally calls the
PCA_SessionFactory::createSession() method to allocate the session.
The type of the session to be created is passed to the method. Plug-in developers can
customize this method and may implement any specific processing required in
addition to session object creation. However, user plug-in (shared library)
developers must not try to access the public PCA_Session members of the newly
created object within this method.
On the sender side, the session creation can fail if:

the receiver(s) is overloaded (that is, all the connected clients if the sender is the
user plug-in server, or the destination server if the sender is a client). See
Server Session Flow Control on page 355 and Client Session Flow Control
on page 356.

the maximum number of sessions allocated to the connection is reached. See


the section on session parametrization in Client Initialization on page 343. It
will not be possible to create new session unless some sessions (currently in
use) are deleted.

other conditions, defined by the user plug-in (shared library) developer during
customization of the PCA_SessionFactory::createSession(), method
occur.

On the receiver side, the automatic session creation can also fail and result in a
session reject. See Session Reject on page 356.

Chapter 9

351

PIC/AG - Using the PCA API


Session Management

Session Deletion
Normal Case
The destruction of a session should be performed both by the client side and the
server side.
Contrary to session creation, there is no mechanism that automatically triggers,
following the deletion of a session on one side, the deletion of the corresponding
session on the other side. The synchronization between client and server on session
deletion has to be managed at the application level. The server and the client should
agree on a protocol that allows each of them to inform (or request) the other side of
which session to delete and when to delete it.
Clients call the PCA_Client::closeSession() method to delete a session.
Servers call the PCA_Server::closeSession() method to delete a session.
Both sides must always be involved in session deletion (irrespective of which side
initiated the session).
Aborting a Session
In some exceptional cases, a session can be aborted by calling the
PCA_Server::abortSession() method on the user plug-in server side, or the
PCA_Client::abortSession() method on the user plug-in client side. In this
case, the session is closed and an abort error message is propagated. The abort
session feature is based on a low level REJECT message. This means that in some
flow controlled situations, the message can be lost. The receiver of an abort message
should then close the session on its side.
Closing Broken Sessions
The PCA does not provide any means to recycle broken sessions on the server side,
and so these sessions must be closed by the server.
Since the user plug-in server does not know which sessions are related to a
disconnected client, the PCA provides the
PCA_Server::closeBrokenSessions() method to close all sessions that are
in the BROKEN state.
Typically, this method can be called when the user plug-in is notified of a client
disconnection by the PCA. For this notification, the PCA calls the
PCA_Server::clientDisconnected() method, which can be customized by
the user plug-in developer.

352

Chapter 9

PIC/AG - Using the PCA API


Session Management
However, if closing broken sessions is mandatory to avoid memory leaks, the use of
the PCA_Server::closeBrokenSessions() method is optional. Instead, the
user may close broken sessions by calling the PCA_Server::closeSession()
method repeatedly. A mixed approach with some broken sessions being closed
manually and some being closed automatically, is also possible.
Automatic Closing
On the client side, when the client is disconnected from the server, sessions are
closed automatically and the user-defined PCA_Client::stateClosed()
method is called.
Session Object Deletion
When a session is closed, the associated object is deleted by the user-provided
PCA_SessionFactory::destroySession() method, unless some messages
still reference the session or the session is locked.
For example, this may happen if some messages related to the session are pending in
the inbound queue. The session object is marked for deletion and its state turns
zombie. When the last reference to the session is released and the session is
unlocked, the PCA calls the PCA_SessionFactory::destroySession()
method, which deletes the session object.

Session Locking
In some cases, you may want to prevent a closed (zombie) session from being
deleted immediately (so that you can perform some action on the session before it
disappears). For example, if a session was previously closed, deleting a message
can destroy the related session object. To prevent this, you lock the session (and
unlock it when you no longer need it).
You can lock a session using the PCA_Session::lock() method. You can unlock
a session using the PCA_Session::unlock() method.
For example, if the session was previously closed, the following two versions of the
processErrorMsg() function perform safe access to the session object:
void processErrorMsg(PCA_Message *P_msg)
{
P_msg->getSession()->errorCount+=1;
delete P_msg;
}

or
Chapter 9

353

PIC/AG - Using the PCA API


Session Management
void processErrorMsg(PCA_Message *P_msg)
{
MySession L_session;
L_session=P_msg->getSession();
L_session->lock();
delete P_msg;
L_session->errorCount+=1;
L_session->unlock();
}

In the first case, the session object is accessed from the message referencing it. All
access to the session object is done before the message deletion. Following the
message deletion, there is no guarantee that the session object still exists. In the
second case, a lock is placed on the session object before the message is deleted,
thus ensuring the session object will "survive" the message deletion. Further access
to the session object can be done safely as long as the lock is not removed.
Following the unlock of the session, there is no guarantee that the session object still
exists.

Server Session Dispatching


At creation time, a session is bound to one and only one connection between a user
plug-in server and a client. As such, a session always involves only one client.
Sessions created on the client side are naturally attached to the client that created the
session. From the client side, there is no need to select the target server as a user
plug-in client can be connected to one and only one user plug-in server. For server
outgoing sessions (that is, sessions created by the user plug-in server), the
destination client selection is performed by the PCA, at session creation time,
according to the outbound flow control state of each client and a round robin
algorithm:

354

A client is said to be outbound overflowed if the outbound queue, as


parameterized in PCA_Server::init(), has overflowed. Then the instance
is not eligible to hold a new session. Overflow occurs when
P_outQueueHighWatermark is exceeded. The overflow condition is
removed once the queue goes below P_outQueueLowWatermark.

When many clients are eligible, the PCA selects one of them using a round
robin model.

Chapter 9

PIC/AG - Using the PCA API


Session Management
For the user plug-in server, all the clients are equivalent. The user plug-in server has
no control on the clients that will be selected for the session it creates. This is all
managed at the PCA level. This session dispatching strategy is defined to balance
traffic load between the connected clients.
If a client is overloaded, it will delay processing of user plug-in messages making
the associated user plug-in outbound queue overflow. No new session will be
opened to this client until it returns to a normal state. However, the client is free to
open sessions to the server.
In the meantime, the user plug-in will route all new sessions and subsequent traffic
to the clients that offer enough processing bandwidth.

Server Session Flow Control


In the previous server session dispatching model, when no client is eligible to hold a
session, the PCA_Server::openSession() request is rejected with a
PCA_BUSY status.
Session setup is suspended until the PCA calls the user-defined
PCA_Server::sessionResume() method. The user can then issue new
PCA_Server::openSession() requests.
A user plug-in (shared library) developer should be aware of the following points:

The PCA does not guarantee that the first PCA_Server::openSession()


attempt, after the PCA_Server::sessionResume() method, will succeed.
In some cases, messages being sent between calls to these two methods could
overflow all clients, making dispatching of a new session impossible. However,
if the outbound queue is correctly parameterized, this should only happen
occasionally.

Using PCA_Server::sessionResume() is recommended because it avoids


the overhead of polling the PCA. However, the use of
PCA_Server::sessionResume() is not mandatory, you can just retry to
open a session periodically until it succeeds.

Client Session Flow Control


If the destination server is overloaded, the PCA_Client::openSession()
request is rejected with a PCA_BUSY status.
Session setup is suspended until the PCA calls the user-defined
PCA_Client::sessionResume() method. The user can then issue new
PCA_Client::openSession() requests.

Chapter 9

355

PIC/AG - Using the PCA API


Session Management
A user plug-in developer should be aware of the following points:

The PCA does not guarantee that the first PCA_Client:openSession()


attempt, after the PCA_Client::sessionResume() method, will succeed.
In some cases, messages being sent between calls to these two methods could
overflow the destination server, making the creation of a new session
impossible. However, if the outbound queue is correctly parameterized, this
should only happen occasionally.

Using PCA_Client::sessionResume() is recommended because it avoids


the overhead of polling the PCA server. However, the use of
PCA_Client::sessionResume() is not mandatory, you can just retry to
open a session periodically until it succeeds.

Session Reject
Upon reception of a message on a session, the receiver may reject the session. The
receiver can be either a user plug-in server or a client.
Rejection of a session can occur on the reception of the first message on the session,
which requires a session creation on the receiver side, or on subsequent messages
once the session has already been created on the receiver side.
A session rejection can occur in the following cases:

The receiver could not allocate internal resources to be associated with the
session. For example, the maximum number of sessions available for the
connection (as defined during the client initialization phase) has been reached.
See Client Initialization on page 343.

The receiver is not in FTC_ACTIVE state. This may happen in some transient
HA states.

The session referenced in the message has already been closed on the receiver
side. Due to some inconsistencies between the server and the clients, some
sessions are closed on one side, but not on the other side. There is now a kind of
session leak at the PCA internal level (to understand how these resources are
parameterized, see Parameterization on page 357).

When a session is rejected, an ERROR message is delivered to the sender with the
rejection cause (see Messages on page 359) and the session enters the rejected
state. Note that session rejection may only happen when a message is sent on the
session. If a session is only opened and does not contain any traffic, it will not be
rejected.

356

Chapter 9

PIC/AG - Using the PCA API


Session Management
The sender must take the appropriate decision depending on the cause of the
rejection. Typically, the HA state problems are only transient. The sender can try to
re-send the message on the session later on. Internal resource or session leak causes
are a design or an implementation issue.

Parameterization
The user plug-in server side cannot parameterize/configure session allocation,
except for some specific requirements through its Session Factory.
However, the client can configure some parameters related to session allocation.
Client parameters control the maximum number of sessions that can be originated
by each side. These parameters should be set large enough to cope with all
situations.They do not involve significant memory consumption or processing
overhead either at the client or at the server side.

Chapter 9

357

PIC/AG - Using the PCA API


Messages

Messages
A message is the basic unit exchanged between user plug-ins (server and client).
A message consists of a fixed header part, and a data part whose content is the
responsibility of the user plug-in developer. The following sections describe the
generic structure and handling of data messages and existing message types.

Types and Headers


This section focuses on message building and parsing.
A user plug-in exchanges formatted messages with the PCA. The messages consist
of a header whose structure is fixed by the PCA specification and a data part whose
contents are defined by the user plug-in developer.
Two types of messages are defined:

DATA. These messages hold user data exchanged between user plug-ins (in
both directions).

ERROR. These messages are notifications from the PCA to the user plug-in
(shared library) of an asynchronous problem. They hold an error code and a
literal error diagnostic. When an error message is received, the associated
session is rejected (see Session Reject on page 356). A user plug-in can only
receive an ERROR message; it cannot send one.

The format of each message type is shown in Figure 9-4, PCA Messages Format.
The purpose of birthDate is discussed in Profiling on page 369. The meaning
of errorCode and errorText can be found in Meaning of errorCode and
errorText Fields on page 361.

358

Chapter 9

PIC/AG - Using the PCA API


Messages
Figure 9-4

PCA Messages Format

The type field must be read prior to any processing to know whether the message
type is DATA or ERROR. This is performed by the PCA_Message::getType()
method. In addition, this method performs consistency checking on the message
length. If it returns an error, the message must be discarded. Note that the
getType() method may be called any number of times for the same message.
The session associated with the message is held in the session field which is a
pointer to the associated session object. It can be retrieved by using the
PCA_Message::getSession() method provided that getType() has
previously returned successfully. This method can also be called multiple times for
the same message. Since PCA messages internally reference their session object, the
return session object is always valid. This is true even if the session has been closed
by the user using the PCA_Server::closeSession() method or the
PCA_Client::closeSession() method, and it is in the Zombie state (see
Session Deletion on page 352).
A formatted message is built using the PCA_Message::putHeader() method
and is parsed using the PCA_Message::getHeader() method. Both methods
copy the message header, passed as an argument, to or from a C++ structure. The
getHeader() method can be called only once because it removes header bytes
from the message. Once the header is extracted, the remaining part of the message
(DATA payload or ERROR text) can be read using basic PCA_Message handling
methods.

Chapter 9

359

PIC/AG - Using the PCA API


Messages

NOTE

Using the PCA_Messsage::putHeader() method to set the message header,


instead of the generic PCA_Message::write() method, or the
PCA_Message::writeAtHead() method, is mandatory. This ensures that the
relationships between sessions and their messages are correctly managed.

Meaning of errorCode and errorText Fields


Table 9-1, Meaning of errorCode and errorText, gives the meaning of the
errorCode and errorText fields.

Table 9-1

errorCode

PCA_FAILURE

Meaning of errorCode and errorText

errorText

Default
Text
Value

Meaning for User

Session closed at
peer

PCA_FAILURE

memory
overflow

PCA_FAILURE

A session is
closed at local
side, but is still
open at peer side

PCA_NOT_ACTIVE

Peer is disabled

Result of:
PCA_sessionFactory->getLastErro
rText()
If you customize this method, the associated
string is under your control. A default
implementation is available.

PCA_ABORTED

Last parameter of:


PCA_Server::abortSession()

PCA_ABORTED

Last parameter of:


PCA_Client::abortSession()

360

Chapter 9

PIC/AG - Using the PCA API


Messages

NOTE

It is also possible to generate an error code through a parameter of the


PCA_Client::disable() and PCA_Server::disable() methods. In both
cases, the error text is Peer is disabled.

Types of PCA Payload


There are 3 types of payload: PRIVATE, DDL, and BER. Only PRIVATE should be
used.
Coding and decoding messages is not addressed by the PIC. This is left to the user
plug-in developer.

PCA_Message Internal Structure


PCA messages consist of a number of chained data buffers, together with read and
write pointers, as shown in Figure 9-5, PCA Message Structure.
In normal usage, buffer chaining is transparent to the user plug-in developer, unless
explicitly specified, and for buffer handling optimization purposes. See the methods
PCA_Message::getFirst() and PCA_Message::getNextDb().
Figure 9-5

PCA Message Structure

PCA messages are objects from the PCA_Message class.


The following basic operations can be performed on such objects:

Chapter 9

361

PIC/AG - Using the PCA API


Messages

PCA_Message::write()
This writes a number of bytes at the write pointer position at the end of the
message. If the last data buffer is filled, new ones are allocated (as shown in
Figure 9-5) until the requested number of bytes is copied into the message. The
method takes a base address and a size, or a C++ String, as its arguments.

PCA_Message::writeAtHead()
This method writes a number of bytes before the read pointer at the head of the
message. The method is typically used to add a header to an existing message.
However, dedicated methods exist to paste the PCA header message, and their
use is mandatory (see Types and Headers on page 359 and Figure 9-4, PCA
Messages Format.). If there is enough space in the current read data buffer, the
copy is made there, otherwise a new data buffer is allocated and linked at the
head of the data buffer chain. The method takes a base address and a size as its
arguments.

PCA_Message::read()
This method copies a number of bytes, from the current read pointer position at
the head of the message, into a user buffer. The read pointer is incremented and
cannot exceed the write pointer. The method takes as arguments either a base
address and a size, or a C++ String and a size. If size is omitted, it attempts to
read the whole message.

PCA_Message::peek()
This method performs the same task as read except that it does not affect the
read pointer. Bytes from a PCA message can be read only once but may be
peeked at any number of times. Typically, this is used in intermediate
dispatching of messages based on the contents of specific fields. The method
takes a base address, a size, and a byte offset from the current read pointer, as its
arguments.

In addition, the PCA_Message class provides a number of other handling methods


to retrieve message sizing attributes or optimize memory usage.

Buffer Allocator
A buffer allocator is associated with each PCA_Message at message construction
time. This object is used each time the message must allocate a new data buffer to
perform a write operation, and when the message is deleted or cleaned up using
PCA_Message::erase().
PCA_BufferAllocator is the abstract base class for the message buffer allocator.

It has two member methods:

362

Chapter 9

PIC/AG - Using the PCA API


Messages

PCA_BufferAllocator::alloc()
This allocates a data buffer. The difference between this and the usual
malloc() or new is that the input size is also an output parameter. The
allocated buffer may be smaller than the requested one (for example, if the
memory pool is fragmented), it may also be larger than the requested one (if
memory blocks are pre-sized). The actual size of the data buffer is taken into
account by PCA_Message when writing the current data and for future writes.

PCA_BufferAllocator::free()
This frees a data buffer. This works just like the usual free() or delete.

Using a buffer allocator provides the maximum flexibility to the user plug-in
developer. It allows you to optimize message handling, for example, making it
possible to allocate data buffers from a shared memory area, or from a specific
memory pool.
The user plug-in developer may define as many buffer allocators as it needs to meet
its memory management constraints.
If there are no specific requirements about message memory management, the user
plug-in developer may use the default implementation of the
PCA_BufferAllocator class provided by the PCA. By default, this class
implements alloc() and free() with the usual new and delete operators.

Chapter 9

363

PIC/AG - Using the PCA API


Sending Messages

Sending Messages
This section describes how messages can be sent from the user plug-in to a client or
to another server.

Principles
Messages are always sent within sessions.
A session is attached to the message by setting the session field in the DATA
header (errors cannot be sent). The session is either an outbound session previously
opened by the PCA_Server::openSession() method, or the
PCA_Client::openSession() method, or an inbound session that was retrieved
from a received message.
Once the header is set by the PCA_Message::putHeader() method, the user can
call the PCA_Server::send() method, or the PCA_Client::send() method,
to transmit the message.

Flow Control
The success of a PCA_Server::send() request, or a PCA_Client::send()
request, depends on the state of the outbound queue parameterized by the
PCA_Server::init() method, or the PCA_Client::init() method (see
Server Initialization on page 339 and Client Initialization on page 343). If the
queue does not overflow, the operation succeeds. If the queue overflows, the
operation succeeds, but the server returns a PCA_OVERFLOW status as a warning. If
the queue is full, the operation fails with a PCA_BUSY status.
Overflow occurs when P_outQueueHighWatermark is exceeded. The overflow
condition is removed once the queue goes below P_outQueueLowWatermark.
Once PCA_BUSY is returned for a session, the session is said to be flow controlled
and no more messages can be sent within the session until it exits this state. This
happens when the PCA calls the user-provided PCA_Server::sendResume() or
PCA_Client::sendResume() method. These methods provide the sender with a
set of sessions being released from the flow controlled state. The sender can then
start re-sending messages within these sessions.
Note that only the sessions provided by the sendResume() method are released
from their flow controlled state. Some flow controlled sessions may not belong to
this set.

364

Chapter 9

PIC/AG - Using the PCA API


Sending Messages
The set of sessions is implemented with an array of pointers to PCA_Session
objects. Some entries in this array may be NULL. This must not be considered by
the user plug-in as an error. The PCA guarantees that a lower index session within
this array was flow controlled before a session with a higher index. This feature
may be used to provide a fair send-restart turn.
The session array is only meaningful within the scope of the method. The user
plug-in must not keep a pointer to a part or the whole array and try to use it later.
Instead, if the user plug-in wants to keep track of unflow controlled sessions, it
should copy the information from the array to a private storage.
Usage of the sendResume() method is optional. Its default implementation is
NOP. Users may choose to retry periodically to send a message on a session until it
gets unflow controlled.

Message Ownership
If a send request succeeds, the message becomes the responsibility of the PCA. This
means that the user must not attempt to access the message (read, write, and so on)
or to delete it. This also applies if the send() method returned an PCA_OVERFLOW
warning status.
If a send request fails due to the saturation of the outbound queue, the message
remains the property of the user plug-in. It can perform any operation on it, or keep
it for future re-transmission.
In all other error cases (for example, PCA internal errors, or bad messages), the
message is deleted by the PCA. The user must not attempt to use it further.

Chapter 9

365

PIC/AG - Using the PCA API


Receiving Messages

Receiving Messages
This section describes how messages from a client or from another server are
received in the user plug-in.

Principles
Received messages are stored by the PCA_Server or PCA_Client in the inbound
queue provided by the user at initialization time (see Server Initialization on
page 339, or Client Initialization on page 343). The user plug-in reads each
message in sequence from this queue and processes it.
The inbound queue is a PCA_Queue object that allows a handling method to know
when messages are available for retrieval.

Flow Control
When the queue high watermark level is exceeded, the inbound queue overflows.
The queue exits the overflow condition when it goes below the low watermark. Both
the high watermark and low watermark are specified at queue-creation time. The
queue contains a built-in flow control mechanism that prevents the server from
delivering new messages to an overflowed queue.
The PCA_Server or PCA_Client can deliver messages again when the inbound
queue exits the overflowed state. The PCA_Server or PCA_Client is informed
that the queue has exited the overflow condition.
The user plug-in does not need to check the state of the inbound queue periodically,
or that it goes from overflowed to non-overflowed after a message is retrieved.

Message Ownership
Once messages have been read from the inbound queue, they belong to the user
plug-in. When their processing is complete, the user plug-in must delete them or
re-cycle them by calling the PCA_Message::reset() method and further
handling methods.
Deletion destroys a messages relation with its session (reference counting), while
the PCA_Message::reset() method keeps this relation active. To re-define a
messages session, you use the PCA_Message::putHeader() method.

366

Chapter 9

PIC/AG - Using the PCA API


Receiving Messages

Profiling
The PCA can provide a profile for the amount of time spent in the inbound path by
setting the global variable extern int G_pcaProfile to 1. Then, the
birthDate field of a DATA message holds the date in ms when the message
became the responsibility of the PCA, above the underlying communication
mechanism. The user can then call the gettimeofday() function to retrieve the
current date and compute the elapsed time.
Profiling can be activated and de-activated dynamically. When de-activated, the
birthDate field is set to 0.

Chapter 9

367

PIC/AG - Using the PCA API


Receiving Messages

368

Chapter 9

PIC/AG - Using the PCA API


Receiving Messages

Chapter 9

369

PIC/AG - Using the PCA API


Receiving Messages

370

Chapter 9

10

PIC/AG - Using the PIC APIs


This chapter describes the operation of the PIC APIs (which includes the Execution
API, the HA API, and the Registry API).

Chapter 10

371

PIC/AG - Using the PIC APIs


Structure of PIC APIs

Structure of PIC APIs


These APIs are responsible for the setup of the user plug-in (shared library), its
scheduling at run-time, the management of the HA FSM (Finite State Machine), and
the retrieval of some PIC attributes.
Figure 10-1, C++ Structure of PIC API Classes, shows the C++ structure of these
APIs.
These APIs consist of several base classes: PIC_PluginExe, PIC_PluginHA,
and PIC_Registry.
The PIC_PluginExe class deals with the scheduling interface of the Plug-in. The
PIC_PluginHA class deals with the HA aspects of the Plug-in. The
PIC_Registry gives access to some PIC attributes.
These classes hold concrete and virtual member methods. Concrete members
provide some entry points to the PIC, whereas virtual members must be derived by
the developer when creating a user plug-in. All virtual methods have a default
implementation. The user plug-in developer implements only the ones of interest.
The C piSetup() function must be implemented by the user plug-in developer to
create and register instances of user plug-in objects that customize the
PIC_PluginExe, and optionally the PIC_PluginHA classes. The piSetup()
function receives as an argument a structure in which the objects created have to be
registered (and it returns its completion status).
The piSetup() function can be considered to be the main for the user plug-in, and
it is the only function called by the PIC at startup.

372

Chapter 10

PIC/AG - Using the PIC APIs


Structure of PIC APIs
Figure 10-1

C++ Structure of PIC API Classes

The piSetup() function, the PIC_PluginExe::init() and the


PIC_PluginExe::close() methods allow the initialization and shutdown of the
user user plug-in.
They are discussed in Plug-in Setup on page 375.
The PIC_PluginExe::selectMasks(), the
PIC_PluginExe::connectionHandler(), the
PIC_PluginExe::pendingRequest(), and the
PIC_PluginExe::processRequest() methods all belong to the scheduling
part of the API.
They are detailed in Plug-in Scheduling on page 377.

Chapter 10

373

PIC/AG - Using the PIC APIs


Structure of PIC APIs
Finally, the PIC_PluginHA::newState(), PIC_PluginHA::getState(),
PIC_PluginHA::stateCompleted(), and PIC_PluginHA::fault()
methods, allow the user plug-in to interface with the HP OpenCall Fault Tolerant
Controller.

374

Chapter 10

PIC/AG - Using the PIC APIs


Plug-in Setup

Plug-in Setup
User Plugin Object Creation
The first step in user plug-in setup deals with the creation of the UserPlugin
objects. The user plug-in developer must provide a C piSetup() function in the
user plug-in shared library. This function receives a pointer to the
PIC_PluginInterface structure as an argument in which the created objects
have to be registered, and it returns a completion status. The purpose of this function
is to allocate a user user plug-in PIC_PluginExe object and optionally a
PIC_PluginHA object. It returns 0 in case of success.
The PIC_PluginInterface structure contains only two pointers: pluginExe
and pluginHA for registering user objects.
Typical Implementation
A typical implementation of this method would be:
int piSetup(PIC_PluginInterface *P_pluginInterface)
{
P_pluginInterface->pluginExe=new UserPluginExe;
P_pluginInterface->pluginHA=new UserPluginHA;
return(0);
}

However, the user plug-in developer is free to add any specific processing to the
function, such as for checking the availability of resources or performing some type
of initialization, provided it complies with PIC HA programming constraints.
Only one instance of each user user plug-in object is created at a time. In some cases
(for example, process abort), the PIC may delete the user plug-in object(s). The user
plug-in developer must ensure that the delete operator of the object is consistent
with the new operator used to allocate it within the piSetup() function.
Errors During Object Creation
If piSetup() function returns an error code (that is, user dependent), the PIC just
stops.

Chapter 10

375

PIC/AG - Using the PIC APIs


Plug-in Setup
In case of an exception that is not caught by the user code, the PIC traces the fact
that it received this exception, and the PIC traces its own termination.
For all other errors, no specific mechanism is provided by the PIC.

User Plug-in Initialization


Once user plug-in objects are created, the PIC calls their user-provided init()
method. Within this method, the user plug-in is intended to perform all the required
initialization before going through the HA FSM. When this method is called, the
HA state is BOOTING.
The method returns an initialization status. In case of failure, the PIC aborts and
enters the HA DOWN state. The conditions under which it can restart depend on the
HA policy selected for the user plug-in.

User Plug-in Shutdown


In case of a PIC stop, the user plug-in objects user-provided close() method is
called to ask the user plug-in to free all its allocated resources. This is the last
method called by the PIC before the user plug-in objects get deleted.

376

Chapter 10

PIC/AG - Using the PIC APIs


Plug-in Scheduling

Plug-in Scheduling
Plug-in scheduling addresses the execution of the user plug-in body, and the
execution of asynchronous operations such as timers. The user plug-in uses the PIC
Scheduler.

Plug-in Body Scheduling


The basic paradigm in user plug-in body scheduling is that OS I/O waiting (that is,
call to the OS select()) is performed by the PIC itself. The Execution API
provides a method for the PIC to retrieve the set of waiting OS I/Os (namely OS file
descriptors) from the user plug-in, and requests the user plug-in to process OS I/Os.
A user plug-in must not perform an OS waiting event.
For better management of time sharing, processing of OS I/Os is performed in two
steps:

Acknowledgment
The PIC asks the user plug-in for acknowledgment of fired I/Os immediately
after the select() method returns. The user plug-in is intended to perform the
minimum amount of work to make the OS I/O exit from the signalled state. For
example, if a fired I/O indicates the arrival of data on a socket, the user plug-in
should simply read the socket.

Actual processing of the OS I/O


In a second step, the PIC provides the user plug-in with CPU time to perform
tasks subsequent to the OS I/O. In the previous example, this would mean
processing the received data.

Figure 10-2 shows the Plug-in scheduling model.

Chapter 10

377

PIC/AG - Using the PIC APIs


Plug-in Scheduling
Figure 10-2

Plug-in Scheduling Model

OS I/O collection is performed with the PIC calling the selectMasks() method.
After the select() method returns, OS I/Os are acknowledged by the PIC calling
the connectionHandler() method. Then a sequence of
pendingRequest()/processRequest() methods is issued.
The user plug-in pendingRequest() and processRequest() methods return a
status indicating whether or not there is some work left to be done.
The possible status values are:
EMPTY

378

The user plug-in lets the scheduler choose depending on the


user plug-in task attributes (I/O fed, Task fed, ...).
This status should not be used.
Chapter 10

PIC/AG - Using the PIC APIs


Plug-in Scheduling
IDLE

The user plug-in has no processing left to do.

PROCESSING

The user plug-in requests processing time.

The pendingRequest() method should check only if the user plug-in needs
processing time. It should return an IDLE or PROCESSING status as appropriate. If
pendingRequest() returns PROCESSING, then the PIC calls the
processRequest() method to do the work. This work may either result from the
set of fired OS I/Os passed by the connectionHandler() method or from an
internal trigger.
If there is work to be done, then the PIC calls the processRequest() method to
actually do this work. The processRequest() method should return either IDLE
(if it has no more processing to do), or PROCESSING (if it has processing left to
do). If it returns PROCESSING, then the PIC calls it again. The sequence completes
either when the processRequest() method returns IDLE, or when a PIC
configuration parameter (InternalLoopCount in the [PIC] section of
pic.conf) is reached.
The selectMasks(), connectionHandler(), processRequest(), and
pendingRequest() methods are C++ virtual members of the PIC_PluginExe
base class that must be implemented by the developer in a specific user plug-in class
inheriting from the PIC_PluginExe class.
The amount of work performed in each call to the processRequest() method is
the responsibility of the user plug-in developer. It should be consistent with the
InternalLoopCount parameter to ensure that the user plug-in does not keep the
CPU busy for a time greater than the configured FTC heart beat.

NOTE

TheInternalLoopCount parameter is just a simple way to define the difference


in priority between high priority tasks (PCA and the PIC) and the low priority task
(HA). TheInternalLoopCount parameter is not intended to be used to tune the
PIC scheduling.

Asynchronous Tasks (TimerLib)


The user plug-in is provided with a timer library (TimerLib) that allows the setting
and cancelling of timers and provides a user-defined callback method to be called
when a timer expires. See the TimerLib man pages.
The user plug-in can use all functions defined in the TimerLib library except for
TIMER_select_time() and TIMER_handler(). Execution of the timer
callback is the responsibility of the PIC (which uses the Scheduler). It is triggered
Chapter 10

379

PIC/AG - Using the PIC APIs


Plug-in Scheduling
periodically (each the time select() method returns). For equality of time
sharing, heavy processing in such methods is strongly discouraged. Instead, the user
user plug-in should save the time-out event in some context variables of its user
plug-in, and then process it within the processRequest() scope.

380

Chapter 10

PIC/AG - Using the PIC APIs


Plug-in HA Management

Plug-in HA Management
Features
HA management for the user plug-in consists of three features:

The user plug-in is informed of all HA FSM state changes.


Consequently, it can perform the appropriate processing depending on its
current state. For example, when entering the FTC_ACTIVE state it should
enable the Plug-in Communication API servers (see Chapter 9, PIC/AG Using the PCA API, on page 331). This also applies to any specific
processing, such as accessing an external device.
For states other than FTC_BOOTING or FTC_DOWN, this is performed
through the user-defined PIC_PluginHA::newState() method. This
method returns a state completion value that drives the next state transition for
some transient states (FTC_SWITCHING, FTC_SYNCHRONIZING, or
FTC_STOPPING).
If the state completion value is PENDING, the current HA FSM state will not
terminate after PIC_PluginHA::newState() returns, it will terminate after
PIC_PluginHA::stateCompleted() is called.

The user plug-in may request the PIC to go FTC_DOWN.


If the user plug-in encounters a critical error, it may call the
PIC_PluginHA::fault() method to make the whole PIC enter the HA state
FTC_DOWN. Then, depending on the HA policy, the PIC will be re-spawned
on the same host, or will switchover to the standby host.

The user plug-in may inform the PIC about work completion.
When the user plug-in has completed its work in some transient states
(FTC_SWITCHING, FTC_SYNCHRONIZING, and FTC_STOPPING), it uses
the PIC_PluginHA::stateCompleted() method to notify the PIC that it is
ready to go to the next state.

State Completion Values


The state completion values of a transient state like FTC_SWITCHING,
FTC_SYNCHRONIZING, or FTC_STOPPING, can be:
PENDING

Chapter 10

The HA FSM state will not terminate automatically.

381

PIC/AG - Using the PIC APIs


Plug-in HA Management
DONE

The HA FSM state will terminate automatically.

SYNC

The HA FSM state will terminate with the need of


synchronization (FTC_STOPPING before
FTC_COLD_STANDBY).

Example of an HA Sequence
The user plug-in scheduling takes place as long as the current HA FSM state is
neither FTC_BOOTING nor FTC_DOWN.
For the HA FSM states, see Figure 8-7, HA FSM for PIC (on HP OpenCall SS7).
For the user plug-in scheduling model, see Plug-in Body Scheduling on page 377.
Below is an example showing the sequence of HA function calls that drive the user
plug-in HA FSM state at startup:

382

Step

1. The PIC calls PIC_PluginHA::newState() with the value FTC_SWITCHING


and the user plug-in returns PENDING.

Step

2. The user plug-in calls PIC_PluginHA::stateCompleted() with the value


DONE from PIC_PluginExe::processRequest().

Step

3. The PIC calls PIC_PluginHA::newState() with the value FTC_ACTIVE and


the user plug-in returns DONE. Note that the default return of newState() is
DONE.

Step

4. The PIC calls PIC_PluginHA::newState() with the value FTC_STOPPING


and the user plug-in returns SYNC.

Step

5. The PIC calls PIC_PluginHA::newState() with the value


FTC_COLD_STANDBY and the user plug-in returns DONE.

Step

6. The PIC calls PIC_PluginHA::newState() with the value


FTC_SYNCHRONIZING and the user plug-in returns PENDING.

Step

7. The user plug-in calls PIC_PluginHA::stateCompleted() with the value


DONE from PIC_PluginExe::processRequest().

Step

8. The PIC calls PIC_PluginHA::newState() with the value


FTC_HOT_STANDBY and the user plug-in returns DONE.

Step

9. The procedure continues from Step 1.

Chapter 10

PIC/AG - Using the PIC APIs


The Plug-in Registry

The Plug-in Registry


This enables the user plug-in to retrieve some PIC attributes.
Currently, only the logical name of the PIC process can be retrieved using the
PIC_Registry::getProcessName() method. The user plug-in developer can
use this to build the user plug-in address for the PCA.
See Plug-in Server and Client Names on page 338.

Chapter 10

383

PIC/AG - Using the PIC APIs


The Plug-in Registry

384

Chapter 10

11

Using the OA&M API


This chapter describes the Operation, Administration & Maintenance (OA&M)
functions that the application can use to manage the MTP2, MTP3, SCCP and
TCAP processes in the SS7 Stack.

Chapter 11

385

Using the OA&M API


SS7 OA&M Services

SS7 OA&M Services


HP OpenCall SS7 provides Operation, Administration & Maintenance (OA&M)
services for MTP, SCCP and TCAP including:

Configuration
Dynamic configuration of SS7 entities such as destinations, routes, linksets,
links, local and remote SSNs and Global Title translations.

Statistics
Collection of statistics from the various SS7 components (destinations, routes,
linksets, links, SCCP and TCAP).

Control
Commands for the dynamic control of an active SS7 stack, and the
configuration of an inactive SS7 stack.

386

Chapter 11

Using the OA&M API


SS7 OA&M Services
Figure 11-1

OA&M in the SS7 Stack

User application

OA & M
APIs

TCAP
API

MTP3/
M3UA
API

- Configuration

AG API

ISUP
& TUP
APIs

SCCP
API

- Monitoring

TCAP

- Control

SCCP
MTP level 3

M3UA

MTP level 2

SCTP

MTP level 1

IP

OA&M APIs
The SS7 stack provides an OA&M API for the development of customized
management applications such as platform administration and user interfaces (Q.3,
SNMP or customized interfaces) for MTP2, MTP3, SCCP and TCAP.

Chapter 11

387

Using the OA&M API


SS7 OA&M Services

OA&M Entities
The OA&M API is organized in an object-oriented structure. It provides the
application with access to the entities that manage the SS7 stack. These entities
perform operations requested by the application, and return the associated reply.
Each entity is assigned a type and an address.

Obtaining Notification about OA&M Entity State Changes


An OA&M entity may change state. No spontaneous notifications are supplied.
However, the application can request to be notified about state changes in one of the
following ways:

On occurrence (available for MTP only)


Each time an entity changes its state the application is notified. The request may
be refused if the maximum number of requests has already been recorded.
When you request notification about OA&M entity state changes, on
occurrence is the default request mode. The other modes must be explicitly
requested.

Periodic (available for MTP and SCCP)


The application requests an entity to periodically send a notification of its
current state. The request may be refused if the maximum number of requests
has already been recorded.

Immediate (available for MTP and SCCP)


The application requests an entity to send a notification containing its current
state.

Issuing OA&M Requests


The application can issue a command requesting an OA&M entity to perform an
operation such as state change, configuration or statistical information. All entities
return a notification after a request has been completed.
OA&M Notifications An OA&M notification is always generated in reply to a request. It may be a
spontaneous notification if the application has previously set some statistic or set an
event report.

388

Chapter 11

Using the OA&M API


Creating MTP and SCCP OA&M Connections using SS7_xifcreate

Creating MTP and SCCP OA&M Connections using


SS7_xifcreate
Requests generated by the application are passed to the appropriate OA&M entity
via OA&M connections. These connections are also used to return notifications
from an entity to the application.

NOTE

SS7_xifcreate() is the function to use. If the application was written using


SS7_ifcreate(), you should replace it with SS7_xifcreate().

The SS7_xifcreate() function creates an MTP or SCCP stack connection. If


successful SS7_xifcreate() returns a connection Identifier (cnxId) that must
be used in all subsequent calls related to the stack connection.
For details about syntax, parameters, and return values, see the SS7_xifcreate()
man page.

Chapter 11

389

Using the OA&M API


Scheduling MTP and SCCP OA&M Connections

Scheduling MTP and SCCP OA&M Connections


As described in Scheduling SS7 Connections on page 65, you must schedule all
the connections using the HP OpenCall SS7 scheduling mechanism. Scheduling the
MTP and SCCP OA&M connections is achieved by:

SS7_ifselectmask()

select()

SS7_ifcnxhandler()

SS7_ifselectmask()
This pre-select function is used for all MTP and SCCP OA&M connections. It takes
the file descriptor masks created by the application, and sets these masks to include
the file descriptors used by the OA&M API to manage the MTP and SCCP OA&M
connections.
The application must call this function before calling select().
For details about syntax, parameters, and return values, see the
SS7_ifselectmask() man page.

select()
The select() function is used for all HP OpenCall SS7 scheduling.
It modifies the read, write and exception masks created by
SS7_ifselectmask().

SS7_ifcnxhandler()
The application must call this post-select function. SS7_ifcnxhandler()
requests the OA&M API to process the masks returned by select() and manage
the internal mechanisms.
An array of OA&M connection identifiers is used to identify the OA&M
connections that have messages waiting to be received by the application.
Activity on the connection is flagged when one of the following events occurs:

390

A message is received by the SS7 stack.

Chapter 11

Using the OA&M API


Scheduling MTP and SCCP OA&M Connections

A closed connection is found (a send or receive call returns an error). The


application should call the close function to deallocate API resources.

A connection goes from busy state (API_BUSY) to normal state. The


application can resume processing (send and receive calls no longer return an
error).

For details about syntax, parameters, and return values, see the
SS7_ifcnxhandler() man page.

Examples
Example 11-1

Scheduling MTP and SCCP OA&M Connections

#define MAX_FD
int
int
fd_set
int
int
int
int
struct

127

nfound;
/* select result */
v1,v2,v3;
readMask, writeMask, exceptionMask;
num_cnx, cnx_active[MAX_FD];
cnxId, numFd, count, Tempo;
IdxCnx=0, ToDo=0;
ToSend=0;
timeval
tmout, * time = &tmout;

for (count=0;;count++)
{
tmout.tv_sec = 1;
tmout.tv_usec = 0;
time = &tmout;
/* Zero select bit masks before entering loop */
FD_ZERO(&readMask);
FD_ZERO(&writeMask);
FD_ZERO (&exceptionMask);
numFd = SS7_ifselectmask(0,
&readMask,
&writeMask,
&exceptionMask,
&time);
nfound =select(numFd,
&readMask,
&writeMask,
&exceptionMask,
time);

Chapter 11

391

Using the OA&M API


Scheduling MTP and SCCP OA&M Connections
num_cnx = MAX_FD;

/* initial size of cnx_active array */

SS7_ifcnxhandler(nfound,
&readMask,
&writeMask,
&exceptionMask,
&num_cnx,
cnx_active);
for( IdxCnx=0, ToDo=0; IdxCnx < num_cnx; IdxCnx++ )
{
if( cnx_active[IdxCnx] == cnxId ){
ToDo = 1;
break;
}
}
if ( !ToSend && !ToDo ) continue;
send_request();
count++;
}

392

Chapter 11

Using the OA&M API


Sending MTP2 OA&M Requests using MTP2X_oamcmd()

Sending MTP2 OA&M Requests using


MTP2X_oamcmd()
The application can request a Signalling Unit (SU) to perform an operation. Each
request contains an address identifying the entity that must perform the operation.
The OA&M connections must be scheduled before the application issues any
request using MTP2X_oamcmd().
The MTP2X_oamcmd() command allows the application to remotely control the
MTP level 2 layer of SS7. It is a non-blocking call which remotely monitors the SS7
hardware entities.
Several commands are provided to allow complete monitoring of the SS7 level 2
layer by the application. You can get the status of the SIU, TSU or TSC. To specify
a command, provide the object address, to which the command will apply, and the
command. The commands will trigger a notification return, which contains all
information relevant to the command.
For details about syntax, parameters, and return values, see the MTP2X_oamcmd()
man page.

Chapter 11

393

Using the OA&M API


Receiving MTP2 OA&M Notifications using MTP2X_oamrecv()

Receiving MTP2 OA&M Notifications using


MTP2X_oamrecv()
The OA&M connections must be scheduled before the application receives any
generated notifications using MTP2X_oamrecv(). The application must receive all
generated notifications until none are left to be received.
This function receives the OA&M notifications send by the local MTP2 OA&M
entities. It is a non-blocking call which receives notifications sent by the SS7 local
node. These notifications hold two types of management information: status and
configuration. They are triggered by the use of MTP2X_oamcmd() calls, and
collected in notifications received by MTP2X_oamrecv. MTP2X_oamrecv()
returns the type of notification received, and the associated information in the
notifstruct parameter.
To avoid an incoming messages buffer overflow, the application should call
MTP2X_oamrecv() often enough. The recommendation is to wait until messages
arrive using the scheduling loop SS7_ifselectmask, select system call (refer
to the OS select(2) manual pages) and SS7_ifcnxhandler.
For details about syntax, parameters, and return values, see the MTP2X_oamrecv()
man page. This man page also contains an example.

394

Chapter 11

Using the OA&M API


MTP3 Entities and Management

MTP3 Entities and Management


At MTP3, the application can manage entities that map onto real objects managed
by MTP3. The application can use the OA&M API to set and configure the MTP3
OA&M entities.

MTP3 Entity Structure


An entity can only be accessed when its type and its address are provided. Because
the OA&M API has an object oriented design, an entity is addressed in relation to its
local system, and if necessary its parent entity. The figure below shows the
hierarchy of the MTP3 entities together with each entitys address and attributes.
Figure 11-2

MTP3 Entities in a Containment Tree

Static Entities

Static entities, such as the MTP3 entity itself, cannot be deleted.

Chapter 11

395

Using the OA&M API


MTP3 Entities and Management
Attributes Set When The address of an entity must be set when the entity is created. For some entities the
an Entity is Created cmdParms field must also be set, for example the cmdParms field is used to set a
route to primary or secondary.
Additional
Parameters

Additional parameters, indicated above as [ ], are set using the set_value


command. They can only be modified when the entity is deactivated. The new
values take effect when the entity is reactivated. An example of an additional
parameter set using the set_value command is the PDN of a link.

Description of MTP3 Entities


The MTP3 entities are described in the table below.
Table 11-1

Description of MTP3 OA&M Entities

Entity

Meaning

mtp

Represents the local point code of the SS7 platform.

local_alias

Represents the aliases of the local point code.

virtual_pc

Represents the virtual point codes associated with the local point code.

destination

Represents a destination MTP3 point code.

cluster

ANSI only: When MTP is configured in cluster routing, this entity denotes a
cluster, that is, a group of destinations located on the same mated STP pair.

route

Represents an MTP3 signalling route to a DPC.

cluster_route

ANSI only: represents a route towards a cluster.

linkset

Represents a linkset.

links

Represents the links that connect to an adjacent point code.

cluster Entity

The cluster entity does not appear explicitly in the following tables. However the
destination entity covers both full point code destinations and cluster
destinations.

cluster_route Entity

The cluster_route entity does not appear explicitly in the following tables.
However the route entity covers both full point code routes and cluster routes.

396

Chapter 11

Using the OA&M API


MTP3 Entities and Management

Rules for Creating and Manipulating MTP3 Entities

The LPC value of the MTPL3 entity must be set before using any MTP
commands.

An entity can only be added if its parent entity exists.

An entity can only be removed if both of the following are true:


all of its child entities have already been removed
it has been deactivated

An entity can only be activated if all of the following are true:


if it has been created
if its parameters are valid
(The Links entity must be explicitly set to a valid PDN value for the
Signalling Unit. The default value of D=-1 will not enable the link to be
activated.)
if all of its child entities can be activated

Chapter 11

The Local Alias entity can not be activated or deactivated. It can only be
configured or removed.

Deactivating an entity will deactivate all its child entities.

397

Using the OA&M API


MTP3 Entities and Management

Addressing MTP3 Entities


Table 11-2, MTP3 OA&M Addressing, lists the configurable parameters that can be
modified by the application.
For example, a route entity is addressed with respect to its local mtp entity and its
parent entity destination. The address field of all MTP3 entities must be
specified as shown in this table.
Table 11-2

MTP3 OA&M Addressing

Object Type

address[0]

address[1]

address[2]

Command
Parameters

mtp

LPC

local_alias

LPC

local alias number


(DPC)

virtual_pc

LPC

virtual point code


number (VPC)

destination

LPC

(DPC)

route

LPC

(DPC)

linkset

LPC

adjacent point code


(APC)

links

LPC

adjacent point code


(APC)

398

Primary/Secondary

Link number
(SLC)

Chapter 11

Using the OA&M API


MTP3 Entities and Management

Possible States of MTP3 Entities


Each MTP3 OA&M entity, except a local alias or virtual point code, has an
associated state.
Table 11-3

MTP3 OA&M States

Entity

State

Meaning

mtp

normal

In service state.

inactive

Awaiting activation.

out_of_service

No active linksets.

restarting

Undergoing restart procedure.

normal

At least one link available to carry traffic.

inactive

Awaiting activation.

out_of_service

No active links.

congested

At least one congested link.

normal

Active, ready for traffic.

inactive

Awaiting activation.

out_of_service

Failure during alignment

congested

Congestion indication received from MTP2.

inhibited

Link is inhibited but in service.

inhibited_OS

Link is inhibited but out of service.

inhibited_inactive

Link is inhibited and inactive.

normal

Available for traffic.

inactive

Awaiting activation.

congested

At least one signalling route is congested.

out_of_service

No signalling route available.

restricted

Only restricted route available for traffic.

linkset

links

destination

Chapter 11

399

Using the OA&M API


MTP3 Entities and Management
Table 11-3

MTP3 OA&M States (Continued)

Entity

State

Meaning

route

normal

Available for traffic.

inactive

Awaiting activation.

out_of_service

Linkset out of service or TFPa (or TCP for ANSI


only) message received.

congested

Linkset congested or TFCb message received.


TFR (or TCR for ANSI only) message received.

restricted

a. Transfer Prohibited
b. Transfer Controlled

400

Chapter 11

Using the OA&M API


Sending MTP3 OA&M Requests using MTPL3_oamcmd()

Sending MTP3 OA&M Requests using


MTPL3_oamcmd()
The OA&M API provides the application with commands to control the SS7 Stack.
An MTP3 OA&M connection must be created and scheduled before the application
can issue any commands.
For details about syntax and parameters,see the MTPL3_oamcmd() man page. This
man page also contains examples.

Response to Expect from an MTPL3 OA&M Request


When you issue an MTP3 request using MTPL3_oamcmd(), you will receive one of
the following responses:
Command
Successful

A non-negative integer is returned to indicate that the command was successful.


You must then use the command MTPL3_oamrecv() to receive the notification.

If the command was executed correctly you receive:


A notification.

If the command could not be executed (for example if you try to add an object
that already exists) you receive:
An MTPOamNotifStruct of type error. The failure_cause field
contains the reason why the command could not be executed.

Command Failed

Chapter 11

The value of -1 is returned to indicate that the command failed. The ss7errno
parameter is set to indicate the error.

401

Using the OA&M API


Collecting MTP3 OA&M Statistics Using MTPL3_oamstat()

Collecting MTP3 OA&M Statistics Using


MTPL3_oamstat()
The application can collect statistics from MTP3 OA&M entities using one of the
following modes:

Immediate
The current value of a statistic is returned in a notification.

Periodic
A notification containing the current value of a statistic is generated each time
the period elapses.

On occurrence
A notification is generated when the statistic changes value.

For details about syntax, parameters, and return values, see the MTPL3_oamcmd()
man page.

Report Types
Collecting MTP3 OA&M statistics or reports is also dependent on the entity type
and the statistic type. Table 11-4, Statistics by Report Type, lists the valid report
types for each MTP3 OA&M entity.
Table 11-4

Statistics by Report Type


Object Types

Statistic

object_state

traffic_gauge

traffic_count

402

mtp

destination

route

linkset

links

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

on occurrence

on occurrence

on occurrence

on occurrence

on occurrence

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

Chapter 11

Using the OA&M API


Collecting MTP3 OA&M Statistics Using MTPL3_oamstat()
Table 11-4

Statistics by Report Type (Continued)


Object Types

Statistic

failure_gauge

failure_count

congestion_gauge

congestion_count

rx_byte_count

tx_byte_count

discarded_msu

su_error_count

rx_load_average

tx_load_average

retransmitted_count

mtp

destination

route

linkset

links

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

immediate

immediate

immediate

periodic

periodic

periodic

immediate

immediate

immediate

periodic

periodic

periodic

immediate

immediate

periodic

periodic

immediate

immediate

periodic

periodic

immediate

immediate

periodic

periodic

immediate

immediate

periodic

periodic

immediate

immediate

periodic

periodic

immediate

immediate

periodic

periodic

immediate

immediate

periodic

periodic

Response to Expect When You Collect MTP3 OA&M Statistics


When you collect MTP3 statistics using the command MTPL3_oamstat(), you
will receive one of the following responses:

Chapter 11

403

Using the OA&M API


Collecting MTP3 OA&M Statistics Using MTPL3_oamstat()
Command successful A non-negative integer is returned to indicate that the command was successful.
You must then use the command MTPL3_oamrecv() to receive the notifications.

If the request is executed you receive:


An object_state notification acknowledging that the statistics request
was executed.
Depending on whether you requested on occurrence, periodic or immediate
statistics you will receive one or more notifications corresponding to the
statistic you requested. If, for example, you asked for a periodic
traffic_count statistic you will receive an MtpOamNotifType of type
traffic_count at regular intervals.
You must continue using MTPL3_oamrecv() until the value returned is 0
indicating that there are no more notifications waiting.

If the request can not be executed you receive:


An MtpOamNotifType of type error. The failure_cause field
contains the reason why the command could not be executed.

Command failed

404

The value of -1 is returned to indicate that the command failed. The ss7errno
parameter is set to indicate the error.

Chapter 11

Using the OA&M API


Receiving MTP3 OA&M Command and Statistic Notifications Using MTPL3_oamrecv()

Receiving MTP3 OA&M Command and Statistic


Notifications
Using MTPL3_oamrecv()
In response to a command from the application, the requested entity performs the
command, returning the result in a notification. The application must receive all
notifications using MTPL3_oamrecv().
This function receives notifications from MTP3 OA&M connections. These
notifications can contain status information, statistics or configuration information.
For details about syntax, parameters, and return values, see the MTPL3_oamrecv()
man page. This man page also contains an example.

Response to Expect When You Use the MTPL3_oamrecv()


Command
When you receive notifications using the MTPL3_oamrecv() command, you will
receive one of the following responses:
Command successful An integer indicating the number of notifications waiting to be received is returned.
If this integer is not 0 you also receive:
In response to a command:

If the command was executed correctly you receive:


a notification.

If the command could not be executed, (for example if you try to add an object
that already exists) you receive:
An MTPOamNotifStruct of type error. The failure_cause field
contains the reason why the command could not be executed.

In response to a request for statistics:

If the request is executed you receive:


An object_state notification acknowledging that the statistics request
was executed.

Chapter 11

405

Using the OA&M API


Receiving MTP3 OA&M Command and Statistic Notifications Using MTPL3_oamrecv()
Depending on whether you requested on occurrence, periodic or immediate
statistics you will receive one or more notifications corresponding to the
statistic you requested. If, for example, you asked for a periodic
traffic_count statistic you will receive an MtpOamNotifType of type
traffic_count at regular intervals.
You must continue using MTPL3_oamrecv() until the value returned is 0
indicating that there are no more notifications waiting.

If the request can not be executed you receive:


An MtpOamNotifType of type error. The failure_cause field
contains the reason why the command could not be executed.

Command failed

406

The value of -1 is returned to indicate that the command failed. The ss7errno
parameter is set to indicate the error.

Chapter 11

Using the OA&M API


SCCP OA&M Entities and Management

SCCP OA&M Entities and Management


When the application creates an SCCP OA&M connection, the entities associated
with SCCP can be monitored, configured and managed via the OA&M API.

SCCP Entity Structure


An entity can only be accessed when its type and its address are provided. Because
the OA&M API has an object oriented design, an entity is addressed in relation to its
local system, and if necessary its parent entity. The figure below shows the structure
of the SCCP entities together with the attributes of each entity and its address.
Figure 11-3

SCCP Entities in a Containment Tree

Static Entity

Static entities, such as the SCCP entity itself, cannot be deleted.

Chapter 11

407

Using the OA&M API


SCCP OA&M Entities and Management
Attributes Set When The address of an entity must be set when the entity is created. For some entities the
Entity is Created
cmdParms field must also be set, for example the cmdParms field is used to set the
concerned parameter as required.
Additional
Parameters

Additional parameters, indicated above as [ ], are set using the set_value


command. They can be modified at any time. Mode is an example of an additional
parameter.

Description of SCCP Entities


The SCCP entities are described in the table below.
Table 11-5

SCCP OA&M Entities

Entity

Entity Name

Description

SCCP

SO_SCCP

This entity models the local SCCP, and contains all


the entities belonging to SCCP.

Local User

SO_LOCAL_USER

This entity models a local SCCP user or SSN.

Virtual User

SO_VIRTUAL_USER

This entity models a virtual user.

Remote User

SO_REMOTE_USER

This entity models a remote SCCP user or SSN that


is known to the local SCCP.

Remote SP

SO_REMOTE_SP

This entity models a peer signalling point.

GT Translator
table

SO_GT_TRANSLATOR

This entity performs the Global Title translation


function for the local SCCP.
The GTTranslator Table is not created directly by
the user but is automatically created when you add
GT Entities. When the last entity is removed the
table is automatically deleted.

SO_FAILED_DEST

Failed
Destination

This entity is responsible for internally collecting


messages that do not have a valid destination. It is
unused.

Rules for Creating and Manipulating SCCP Entities

408

The LPC value of the MTPL3 entity must be set before starting to create any
SCCP entities.

Chapter 11

Using the OA&M API


SCCP OA&M Entities and Management

Only the SCCP entity itself can be activated or deactivated.

An entity can only be added if its parent entity exists.

An entity can only be removed if all of its child entities have already been
removed.

Addressing SCCP Entities


The SCCP OA&M entities are referenced through their type and address which is
contained in an array. The elements in an address depend on the entity.
Table 11-6

SCCP OA&M Addressing

Entity

address[0]

address[1]

cmdParms value to be set

SO_SCCP

Unused

Unused

SO_LOCAL_USER

Local PC

SSN

SO_VIRTUAL_USER

Local PC

SSN

SO_REMOTE_USER

DPC

SSN

SO_REMOTE_SP

DPC

Unused

concerned

SO_FAILED_DEST

Unused

Unused

SO_GT_TRANSLATOR

Translator Id

Unused

Translator Id

digit_pr_ssn priority

The Translator Id is a 32-bit integer structured as described in the table below.


Table 11-7

Translator Id

Field

Octet

Value

Nature of Address
Indicator

1 (LSB)

SC_unusedIndicator
SC_subscriberNo
SC_reserved_national_use
SC_nationalNo
SC_internationalNo

SC_unused

(NAI)

Translation Type
(TT)

Chapter 11

409

Using the OA&M API


SCCP OA&M Entities and Management
Table 11-7

Translator Id (Continued)

Field

Octet

Value

Numbering Plan

3 (MSB)

SC_unknownNumbering
SC_isdn
SC_userdata
SC_telex
SC_maritimeMobile
SC_landMobile
SC_isdnMobile
NULL

(NP)

Possible States of SCCP Entities


Some SCCP OA&M entities have associated state information. When a state change
occurs, a notification is sent from the particular entity to the application.
Table 11-8

SCCP OA&M States

Entity

State

Meaning

SO_SCCP

SO_AVAILABLE

In service state.

SO_UNAVAILABLE

Awaiting restart,
synchronized with MTP.

SO_RESTARTING
SO_CONGESTED
SO_UNCONGESTED
SO_STOPPED

Undergoing restart procedure.


Congestion indication
received from MTP.
MTP is no long congested.
SCCP disabled via OA&M
API.

SO_LOCAL_USER

SO_VIRTUAL_USER

SO_REMOTE_USER

410

SO_INSERVICE

In service state.

SO_OUTOFSERVICE

Out of service state.

SO_INSERVICE

In service state.

SO_OUTOFSERVICE

Out of service state.

SO_AVAILABLE

Remote user is accessible.

SO_UNAVAILABLE

Remote user is not accessible.


Chapter 11

Using the OA&M API


SCCP OA&M Entities and Management
Table 11-8

Chapter 11

SCCP OA&M States (Continued)

Entity

State

Meaning

SO_REMOTE_SP

SO_INSERVICE

Remote SP is accessible.

SO_OUTOFSERVICE

Remote SP is not accessible.

SO_GT_TRANSLATOR

Not applicable

SO_FAILED_DEST

Not applicable

411

Using the OA&M API


Sending SCCP OA&M Requests Using SCCP_oamcmd()

Sending SCCP OA&M Requests Using


SCCP_oamcmd()
The SCCP OA&M API provides the application with commands to control the
SCCP and its users (SSNs). Some commands trigger a notification containing all the
information relevant to the issued command.
For details about syntax, parameters, and return values, see the SCCP_oamcmd()
man page. This man page also contains examples.

Response to Expect When You Send an SCCP OA&M Request


When you issue an SCCP request using SCCP_oamcmd(), you will receive one of
the following responses:
Command successful A non-negative integer is returned to indicate that the command was successful.
You must then use the command SCCP_oamrecv() to receive the notification.

If the command was executed correctly you receive:


A notification.

If the command could not be executed, for example if you try to add an object
that already exists) you receive:
An sccp_notif whose failure field contains the reason why the
command could not be executed.

Command failed

412

The value of -1 is returned to indicate that the command failed. The ss7errno
parameter is set to indicate the error.

Chapter 11

Using the OA&M API


Collecting SCCP OA&M Statistics Using SCCP_oamstat()

Collecting SCCP OA&M Statistics Using


SCCP_oamstat()
The application can collect statistics from SCCP OA&M entities using one of the
following modes:

Immediate
The current value of a statistic is returned in a notification.

Periodic
A notification containing the current value of a statistic is generated each time
the period elapses.

For details about syntax, parameters, and return values, see the SCCP_oamstat()
man page. This man page also contains examples.

Report Types
The application can request an entity to return a statistical report. The type of mode
of report is dependent on the entity and the statistic type as shown in the following
table.
Table 11-9

Statistics by Report Type


Object Type

Statistic
SO_ SCCP

SO_LOCAL
_USER

SO_VIRTU
AL_USER

SO_REMOT
E_SP

SO_REMOT
E_USER

SO_GT_
TRANSLAT
OR

SO_FAILE
D_DEST

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

SO_UDT_COUNT
_TX

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

SO_UDT_COUNT
_RX

immediate

immediate

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

periodic

periodic

SO_UDT_GAUGE
_TX

periodic

periodic

periodic

periodic

periodic

SO_STATE

Chapter 11

413

Using the OA&M API


Collecting SCCP OA&M Statistics Using SCCP_oamstat()
Table 11-9

Statistics by Report Type (Continued)


Object Type

Statistic
SO_ SCCP

SO_LOCAL
_USER

SO_VIRTU
AL_USER

SO_REMOT
E_SP

SO_REMOT
E_USER

SO_GT_
TRANSLAT
OR

SO_FAILE
D_DEST

SO_UDT_GAUGE
_RX

periodic

periodic

periodic

periodic

periodic

periodic

periodic

SO_UDTS_COUN
T_TX

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

SO_UDTS_COUN
T_RX

immediate

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

SO_UDTS_GAUG
E_TX

periodic

periodic

periodic

periodic

periodic

SO_UDTS_GAUG
E_RX

periodic

periodic

periodic

periodic

periodic

periodic

SO_RTG_FAILU
RE_ COUNT

immediate

immediate

immediate

immediate

immediate

immediate

periodic

periodic

periodic

periodic

periodic

periodic

SO_RTG_FAILU
RE_ GAUGE

SO_TRANS_REQ
_ GAUGE

NOTE

414

periodic

The receive counters for a given object are incremented each time that object
receives a message. Both messages from remote users and requests from the
network to the object will cause the counters to be incremented. Similarly each
message transmitted from an object increments the transmit counters.

Chapter 11

Using the OA&M API


Collecting SCCP OA&M Statistics Using SCCP_oamstat()

Response to Expect When You Collect SCCP OA&M Statistics


When you collect SCCP statistics using SCCP_oamstat(), you will receive one of
the following responses:
Command successful A non-negative integer is returned to indicate that the command was successful.
You must then use the command SCCP_oamrecv() to receive the notification.

If the command was executed correctly, you receive:


An SO_EXECUTED notification to acknowledge the request.
Depending on whether you requested periodic or immediate statistics you
will receive one or more notifications corresponding to the statistic you
requested.

If the command could not be executed:


You will get an sccp_notif whose failure field contains the reason
why the command could not be executed.

Command failed

Chapter 11

The value of -1 is returned to indicate that the command failed. The ss7errno
parameter is set to indicate the error.

415

Using the OA&M API


Receiving SCCP OA&M Command and Statistic Notifications Using SCCP_oamrecv()

Receiving SCCP OA&M Command and Statistic


Notifications
Using SCCP_oamrecv()
In response to a command from the application, the requested entity responds with a
notification indicating the result of the command. The application must receive all
notifications using SCCP_oamrecv().
This function receives notifications from SCCP OA&M connections. These
notifications can contain status information, statistics, configurations or reports.
They are the responses to previous SCCP OA&M requests.
For details about syntax, parameters, and return values, see the SCCP_oamrecv()
man page. This man page also contains examples.

Response to Expect When You Use the SCCP_oamrecv()


Command
When you receive notifications using the SCCP_oamrecv() command, you will
receive one of the following responses:
Command successful An integer indicating the number of notifications waiting to be received is returned.
You must continue using SCCP_oamrecv() until the value returned is 0 indicating
that there are no more notifications waiting.
In response to a command:

If the command was executed correctly you receive:


A notification.

If the command could not be executed you receive:


An sccp_notif whose failure field contains the reason why the
command could not be executed.

In response to a request for statistics:

If the command was executed correctly, you receive:


An SO_EXECUTED notification to acknowledge the request.

416

Chapter 11

Using the OA&M API


Receiving SCCP OA&M Command and Statistic Notifications Using SCCP_oamrecv()
Depending on whether you requested on occurrence, periodic or immediate
statistics you will receive one or more notifications corresponding to the
statistic you requested.

If the command could not be executed you receive:


An sccp_notif whose failure field contains the reason why the
command could not be executed.

Command failed

Chapter 11

The value of -1 is returned to indicate that the command failed. The ss7errno
parameter is set to indicate the error.

417

Using the OA&M API


Closing MTP and SCCP OA&M Connections Using SS7_close()

Closing MTP and SCCP OA&M Connections Using


SS7_close()
Only close an MTP or SCCP OA&M connection when you are certain that the
OA&M connection will no longer be used. Repeated opening and closing of the
connection places a high overhead on the OA&M API mechanism.
An OA&M service is terminated when the application calls SS7_ifclose(). All
the entities used by the connection are also closed, and any calls to these entities are
refused.
For details about syntax, parameters, and return values, see the SS7_ifclose()
man page.

418

Chapter 11

Using the OA&M API


Using TCAP OA&M Functions

Using TCAP OA&M Functions


The application can collect TCAP statistics from the OA&M API. Unlike MTP and
SCCP, the TCAP OA&M applications can only request statistical information, you
cannot modify any configuration information.

Chapter 11

419

Using the OA&M API


Opening a TCAP OA&M Connection Using TCX_open()

Opening a TCAP OA&M Connection Using


TCX_open()
All TCAP OA&M requests and responses are exchanged via a TCAP OA&M
connection created by TCX_open().
TCX_open() creates a new TCAP access point (stack connections), allowing the
application to access the TCAP services either as a TC-user or a TR-user.

For details about syntax, parameters, and return values, see the TCX_open() man
page.
Example 11-2

Example: Creating a TC-user Connection


This example is a code fragment that shows how to make a TC-user connection.
/* Example of TCX_open (): */
#include <TCAP_ext.h>
#include <TCAP_errors.h>
CnxId = TCX_open(ClassName,
TCX_TCAP_STD,
OSSN,
TC_YES,
TC_YES,
NULL,
0,
0);

420

Chapter 11

Using the OA&M API


Scheduling TCAP OA&M Connections

Scheduling TCAP OA&M Connections


As described in Scheduling SS7 Connections on page 65, you must schedule all
the connections using the HP OpenCall SS7 scheduling mechanism. You schedule
the TCAP OA&M connections by using:

TCX_select_mask()

select()

TCX_cnx_handler()

TCX_select_mask()
This pre-select function is used for all TCAP OA&M connections. It takes the file
descriptor masks created by the application, and sets these masks to include the file
descriptors used by the OA&M API to manage the TCAP OA&M connections. The
application must call this function before calling select().
For details about syntax, parameters, and return values, see the
TCX_select_mask() man page.

select()
The select() function is used for all HP OpenCall SS7 scheduling. It modifies
the read, write and exception masks created by TCX_select_mask().

TCX_cnx_handler()
The application must call this post-select function. TCX_cnx_handler() requests
the API to process the masks returned by select() and manage the internal
mechanisms. An array of TCAP OA&M connection identifiers is used to identify
the OA&M connections that have messages waiting to be received by the
application.
Activity on the connection is flagged when one of these events occurs:

Chapter 11

A message is received by the SS7 stack.

An L_cancel is generated by the API and must be extracted by the receive


function call.

421

Using the OA&M API


Scheduling TCAP OA&M Connections

A closed connection is found (a send or receive call returns an error). The


application should call the close function to deallocate API resources.

A connection goes from busy state (API_BUSY) to normal state. The


application can resume processing (send and receive calls no longer return an
error).

For details about syntax, parameters, and return values, see the
TCX_cnx_handler() man page.
Example 11-3

Scheduling TCAP OA&M Connections

int
cnx_active[MAX_FD];
int
numFd, num_cnx;
fd_set
readMask, writeMask; /* masks for select */
int
n;
int
result;
struct timeval
&tmout, * time = &tmout;
/* Zero select bit masks before entering loop */
FD_ZERO(&readMask);
FD_ZERO(&writeMask);
while (1) {
tmout.tv_sec = 2;
tmout.tv_usec = 0;
/* Must set this each time round loop as selectmask call
* may change the pointer
*/
time = &tmout;
/* Note: As we have no other fds open, the initial max fd
/* is 0. Also, we dont use the exception mask, so we pass 0.
* Note too that last param is a struct timeval **.
*/
numFd = TCX_select_mask(0, &readMask, &writeMask,0, &time);
n = select(numFd, (int *)&readMask, (int *)&writeMask, 0, time);
/* Note: We ALWAYS call the cnxhandler function after select(2),
* even if select returns an error (-1). This is to allow the API
* lib to clear any socket errors.
*/
num_cnx = MAX_FD;
TCX_cnx_handler(n, &readMask, &writeMask, 0, &num_cnx, cnx_active);
if ( (num_cnx > 0) && ( cnx_active[0] == cnxId) ) {
/* OA&M operations*/
}

422

Chapter 11

Using the OA&M API


Requesting TCAP Statistics Using TCX_control()

Requesting TCAP Statistics Using TCX_control()


When the application has scheduled the TCAP OA&M connections, OA&M
commands relating to TCAP statistics can be issued.
This function issues requests for immediate or periodic statistical reports on behalf
of the application. A report is received by calling TCX_recv().
For details about syntax, parameters, and return values, see the TC_control()
man page.
The following table lists the types of statics produced.
Table 11-10

TCAP Statistic Types

Command

Meaning

STAT_ACTIVE_TRANSACTIONS

Number of active transactions/dialogues.

STAT_TRANSACTIONS_KILLED_
BY_TIMER

Number of transactions/dialogues that were terminated


internally by TCAP.

STAT_USER_LOAD

Number of TCAP messages per second for each user attached


to TCAP. Multiple notifications may be returned.

STAT_NODE_MSG_SENT

Total number of TCAP messages sent by the SS7 platform.

STAT_NODE_MSG_RECV

Total number of TCAP messages received by the SS7


platform.

STAT_ABORT_RECEIVED

Returns the P_cause of each P_ABORT received by TCAP.


Multiple notifications may be returned.

STAT_ABORT_SENT

Returns the P_cause of each P_ABORT sent by TCAP.


Multiple notifications may be returned.

STAT_REJECT_RECV

Returns the Problem Code of each rejected component


received by TCAP. Multiple notifications may be returned.

STAT_REJECT_SENT

Returns the Problem Code of each rejected component send


by TCAP. Multiple notifications may be returned.

STAT_U_REJECT_RECEIVED

Returns the abort cause of each U_ABORT received by


TCAP. Multiple notifications may be returned.

Chapter 11

423

Using the OA&M API


Requesting TCAP Statistics Using TCX_control()
Table 11-10

TCAP Statistic Types (Continued)

Command

Meaning

STAT_U_REJECT_SENT

Returns the abort cause of each U_ABORT send by TCAP.


Multiple notifications may be returned.

STAT_COMPONENT_RECV

Number of components received.

STAT_COMPONENT_SENT

Number of components sent.

RESET_STATS

Reset counters.

stat_end

Indicates the end of multiple notifications returned in


response to these commands: STAT_ABORT_RECEIVED,
STAT_ABORT_SENT, STAT_REJECT_RECV,
STAT_REJECT_SENT, STAT_U_REJECT_RECEIVED,
STAT_U_REJECT_SENT.

Example 11-4

Requesting TCAP Statistics

int ret, cnxId_tcap;


TC_control_c command;
tc_control_parms controlParms;
// send the request
command = STAT_ACTIVE_TRANSACTIONS;
ontrolParms.period_value = 30; // report period of 30 secs
ret = TCX_control (cnxId_tcap, NULL,command,&controlParms);
if (ret < 0) {
// error handling
}

424

Chapter 11

Using the OA&M API


Collecting TCAP Statistics Using TCX_recv()

Collecting TCAP Statistics Using TCX_recv()


When the application issues an OA&M statistic request, the related responses are
returned to the application via MGT primitives.
This function receives a MGT primitive containing statistic information from the
OA&M API.
For details about syntax, parameters, and return values, see the TCX_recv() man
page.
Example 11-5

Receiving TCAP OA&M Statistics

tcx_primitive primitive;
tc_primitive_type
ptype;
tc_control_c statType;
tc_p_abort_cause abort_cause;
Boolean abort = FALSE;
SSWnotif_type notif_type;
int
notif_value;
int
more_message;
int backup_info,L_ret;
int
period;
while ((ret = TCX_recv (cnxId_tcap,NULL,&primitive,NULL, &more_message,&backup_info))
> 0)
{
ptype = primitive.type;
if (ptype != MGT) {
// this is a spontaneous notification
}
if (ptype == MGT) {
statType = primitive.tcx_primitive_option.tc_stat.stat_type;
if (statType == STAT_ABORT_RECEIVED) {
abort_cause =
primitive.tcx_primitive_option.tc_stat.p.abort.p_abort;
notif_value =
primitive.tcx_primitive_option.tc_stat.p.abort.value;
abort = TRUE;
} else {
if (statType == STAT_ABORT_SENT) {
abort_cause =
primitive.tcx_primitive_option.tc_stat.p.abort.p_abort;
notif_value =
primitive.tcx_primitive_option.tc_stat.p.abort.value;
abort = TRUE;

Chapter 11

425

Using the OA&M API


Collecting TCAP Statistics Using TCX_recv()
} else {
notif_value = primitive.tcx_primitive_option.tc_stat.p.value;
}
} // end of if (primitive.p_type == MGT)
else {
printf (Bad primitive type received from TCAP\n);
}
} // end of while
if (ret < 0) {
if (tc_errno == TCE_CNX_CLOSED || tc_errno == TCE_ILLEGAL_CALL)
printf (tc_errno = %d\n,tc_errno);
}

426

Chapter 11

Using the OA&M API


Closing a TCAP OA&M Connection Using TCX_close()

Closing a TCAP OA&M Connection Using TCX_close()


Only close a TCAP OA&M connection when you are certain that the application
will not use the connections again. If a connection is repeatedly opened and closed,
the application will place a high overhead on the API mechanism.
A TCAP OA&M service is terminated when the application closes an OA&M
connection using TCX_close(). All the entities associated with this OA&M
connection are also closed, and all further calls to TCX_send(), TCX_recv() and
TCX_control() will be refused.
For details about syntax, parameters, and return values, see the TCX_close() man
page.

Chapter 11

427

Using the OA&M API


Closing a TCAP OA&M Connection Using TCX_close()

428

Chapter 11

12

Using the ISUP API


This chapter describes how to open, close and use an SS7 stack connection via the
HP OpenCall SS7 ISUP API.

Chapter 12

429

Using the ISUP API


Introduction

Introduction
The HP OpenCall SS7 ISUP API provides the application with object oriented
access to the HP OpenCall SS7 ISUP library and its supported functions. Hence the
application can access the SS7 network via an SS7 stack and the
HP OpenCall SS7 ISUP library.
In CIC-based distribution mode, an HA process called the Traffic Discriminator
routes ISUP traffic to the correct owner application using the CIC and DPC values
defined in the applications configuration.
This chapter explains how you can use the API to set up, operate and close a
connection between the application and the HP OpenCall SS7 stack via
HP OpenCall SS7 ISUP.
Example programs illustrating simple call setup and release are listed in ISUP
Tutorial Programs on page 480.
For all function signatures and object structures, refer to the man pages.

430

Chapter 12

Using the ISUP API


ISUP Software Versions

ISUP Software Versions


HP OpenCall SS7 ISUP software supports the following base protocols:

ANSI

ITU-T

The current derived protocols are ITU88, ITU97, TTC, etc.


For each protocol, different message sets are supported.
For example:

the ANSI protocols support the ANSI-92 and ANSI-95 message sets

the ITU97 protocol supports the ITU-T93 and ITU-T97 message sets

The combination of a protocol and a message set is known as a flavor.


For a complete list of ISUP flavors supported by HP OpenCall SS7 ISUP, please
contact your HP representative.

Chapter 12

431

Using the ISUP API


ISUP Software Components

ISUP Software Components


HP OpenCall SS7 ISUP contains both generic software componentscommon to
both the ANSI based and the ITU-T based product versionsand version specific
software components.
Figure 12-1

HP OpenCall SS7 ISUP Components

Generic Components
These components are independent of the software version. They include

432

Chapter 12

Using the ISUP API


ISUP Software Components

HP OpenCall SS7 ISUP API

This C++ interface provides a single abstract programming view of the


HP OpenCall SS7 ISUP library. It provides an application with objects and methods
to create ISUP messages with their associated parameters, and access the network
via an HP OpenCall SS7 stack to exchange signaling information.

HP OpenCall SS7 ISUP Supported Messages

These are the ISUP messages supported by the HP OpenCall SS7 ISUP library.
They are represented by the API as a set of C++ object classes known as message
classes. These message classes provide specific interfaces to build and access
individual parameters found in each message.

HP OpenCall SS7 ISUP core

This component contains several sub-components concerning internal


HP OpenCall SS7 ISUP information, handling, decoding/encoding and direct MTP3
access.

Version-Specific Components
These components affect the behavior of API objects. They include:

HP OpenCall SS7 ISUP State-machines

This component provides the ISUP behavior defined by the ANSI or ITU-T
standards

HP OpenCall SS7 ISUP Metadata

This component determines the behavior of the HP OpenCall SS7 ISUP Supported
Messages when they are manipulated by an application. It contains the internal
structure of those messages defined the ANSI or ITU-T standards. This component
can be customized using the HP OpenCall SS7 ISUP Message Customization
Package

HP OpenCall SS7 ISUP Circuit Manager

This component manages the state of the circuits manipulated by the state-machines.

Chapter 12

433

Using the ISUP API


Object Orientation Guidelines

Object Orientation Guidelines


HP OpenCall SS7 ISUP provides the application with a C++ API to manipulate all
SS7 stack connections and exchange messages as objects. Its object-oriented nature
should be kept in mind while you develop the application.

Object Lifespan
When you create an object, its lifespan should be considered before it is destroyed.
If the object is repeatedly used with the same parameters, then it must not be
destroyed when the initial task is completed, but it should exist until the application
has completed all its tasks for that object.
For example, the application communicates with an SS7 stack by means of a
connection object (IsupProbe). This connection must remain open until the
application no longer wishes to communicate with the SS7 stack. Otherwise,
creating and destroying a connection object each time you wish to exchange
messages with the SS7 stack involves a high processing overhead for the
application.

Inheritance
Most of the objects manipulated by the API are instances of derived classes. A base
class defines the common methods and data for its derived classes. Objects of a
derived class contain all the data and methods defined by both the base class and its
derived class. Hence, derived classes can refine the behavior of their parent classes.

Exception Handling
Exception handling is not used by the HP OpenCall SS7 APIs. Any errors are
indicated by the value returned after completion of a method. Such values are
known as Return Status Values, and each value signifies a specific state. However,
HP OpenCall SS7 APIs can carry user exceptions on Linux. Exceptions are enabled
by default with g++. Use the -fexceptions compilation flag with g++ or gcc to
force support of exceptions in the application code.

434

Chapter 12

Using the ISUP API


Using the ISUP API Shared Library

Using the ISUP API Shared Library


The ISUP API is available as a shared library.
The following is an example of a compile/link using the shared library (for ISUP
ITU):
g++ -fexceptions -pthread -I/opt/OC/include -I/opt/OC/include/ISUP
-o isupClientSMITU isupClientSMITU.C -lisupITUapi -lSS7utilWBB

The following is an example of a compile/link using the shared library (for ISUP
ANSI):
g++ -fexceptions -pthread -I/opt/OC/include -I/opt/OC/include/ISUP
-o isupClientSMANSI isupClientSMANSI.C -lisupANSIapi -lSS7utilAAA

See also ISUP Makefiles on page 482.

Chapter 12

435

Using the ISUP API


Connections

Connections
A centralized application, such as Call Control described by ITU-T, handles all
circuit objects attached to a system. Signaling information regarding these circuits is
exchanged between signaling points via the SS7 network.
HP OpenCall SS7 ISUP supports access to the SS7 network via a maximum of 4
SS7 stacks. The HP OpenCall SS7 ISUP API provides connection objects to
connect the application to an SS7 stack. These connection objects are commonly
known as probe objects.
Figure 12-2

436

Connection/Probe Relationship

Chapter 12

Using the ISUP API


SS7 Stack Access

SS7 Stack Access


Via its API and probe objects, the HP OpenCall SS7 ISUP library allows the
application to access each SS7 stack using one of the following access modes:

State-machine access mode

Bypass access mode

Access mode is selected when the application requests the API to create a probe
object on its behalf.

State-machine Mode
The state-machine access mode enables the application to benefit from the
state-machines and timers provided by HP OpenCall SS7 ISUP. The protocol
behavior of HP OpenCall SS7 ISUP is dependent on the state-machines
implemented for each software version (ANSI based or ITU-T based).

Bypass Mode
In this access mode, the application can bypass the provided state-machines and
timers, and directly interface with the ISUP Signaling Procedure Control (SPRC)
functional block.
This mode of access is recommended if you are developing a gateway application or
an application not requiring interaction with the state-machines.
If a customer has an existing application that implements the ISUP state-machines,
and the customer wants to use this application instead of the
HP OpenCall SS7 ISUP state-machines, then the Bypass Mode is the appropriate
mode.

Chapter 12

437

Using the ISUP API


ISUP CIC-based distribution

ISUP CIC-based distribution


ISUP CIC-based distribution is a facility that enables several primary ISUP
application instances to be connected simultaneously to the same ISUP user part of
MTP of the same SS7 stack, via an HA process called the Traffic Discriminator
(TDi).
See Figure 12-3 for details.
ISUP traffic is routed towards the application that handles the ISUP circuit defined
in its configuration. The circuit is identified by a couple [DPC value, CIC value].

Default Platform Configuration


When installed on the platform, CIC-based distribution is enabled by default. Any
new configuration that does not use CIC-based distribution, must explicitly disable
CIC-based distribution, see the cfgCreate man page.

Inconsistent Distribution
An application using CIC-based distribution must not run alongside another
application that does not use CIC-based distribution. Inconsistent distribution has a
serious impact on platform performance and results in ISUP traffic loss.

438

Chapter 12

Using the ISUP API


Application Instance Group

Application Instance Group


Schematically, such ISUP application instances can be grouped into AIGs
(Application Instance Groups).
Each AIG contains one primary application instance, and one secondary application
instance.
Each primary ISUP application instance is identified by a unique application id.
The secondary instance associated with this primary instance has the same
application id.
Figure 12-3 shows a sample configuration.
Figure 12-3

Several Primary ISUP Application Instances Connected to an SS7 Stack via the
TDi

Chapter 12

439

Using the ISUP API


Application Instance Group
The primary ISUP application instances handle the messages. The secondary
application instance does not handle messages. A secondary instance is dedicated to
a single primary instance, that is, a secondary instance cannot be the back up of
more than one primary instance.

AIG Configuration
The association between a CIC and an application id is defined in the applications
configuration. Each primary ISUP application has its own configuration containing
the CICs for which it is responsible.
This configuration (and consequently the set of CICs) also applies to the secondary
application instance that backs up the application. At any time, a CIC can be
assigned to just one application, that is, a CIC cannot be assigned simultaneously to
several applications.
To do this, use the cfgIsup command (for a description, see the man page). See
also the HP OpenCall SS7 Operations Guide.

NOTE

440

An applications configuration is not affected by the distribution mode, that is, it


does not need to be modified for use with (or without) CIC-based distribution.

Chapter 12

Using the ISUP API


ISUP Message Routing

ISUP Message Routing


Outgoing ISUP message routing is not affected by the traffic distribution mode, that
is CIC-based distribution or non distribution.

Incoming Message Routing


Each primary instance has its own set of ISUP circuits (for which it is responsible).
ISUP Circuit Owners
If a newly connected ISUP application tries to handle an ISUP circuit that belongs
to another application, an error trace is output and a log is generated. A circuit
belongs to the first application that loaded it for the duration of the TDis
existence.
TDi Routing Tables
The TDi loads any configuration file present at startup and consolidates its routing
table accordingly. If an ISUP application connects to the TDi after TDi startup, the
TDi loads the configuration at connection time and updates its routing table.
With ISUP CIC-based distribution, the active TDi routes incoming messages (that
is, messages coming from the SS7 network) to the appropriate primary ISUP
application instance, using the OPC and CIC value of the incoming message.
The routing table is not updated when the application disconnects from the TDi.

NOTE

Routing is based on the OPC of the incoming message. From the ISUP applications
point of view, this OPC corresponds to a DPC.

Messages from a Non-Assigned Circuit


Incoming messages from a non-assigned ISUP circuit are discarded and a log is
generated.

Chapter 12

441

Using the ISUP API


ISUP Message Routing

Management Messages
Management messages (MTP level 3 notifications) are broadcast to all primary
application instances. For example, a message concerning the availability of the
MTP service is sent to all the primary application instances.

442

Chapter 12

Using the ISUP API


ISUP Application Connection

ISUP Application Connection


In CIC-based distribution mode, ISUP applications connect to the stack via the TDi.
To connect to the stack, an ISUP application must use the IsupMgr::init method
from the ISUP API library:
static ISUP::IsupMgr::init(IsupMgr &*
P_mgr,HPAIN::Uint32, P_applicationId, HPAIN::Boolean,
P_cicDistributed)

The value of the P_cicDistributed Boolean can be set to bTrue or to bFalse.


To use CIC-based distribution, set the value to bTrue,else to bFalse.

NOTE

The connection of an ISUP application to more than one LPC is not supported.

Application Disconnection
When an application disconnects from the TDi, the TDi routing table is not updated.
If a new application connects to the TDi with the same application id, the former
configuration is used to route the messages for any ISUP circuits that exist in the
routing table at connection time.

Chapter 12

443

Using the ISUP API


Dynamic Configuration

Dynamic Configuration
The configuration of ISUP applications can be changed dynamically regardless of
the distribution mode.
To change the configuration of a connected application, you have to use the
cfgIsup command (for a description, see the man page). See also the
HP OpenCall SS7 Operations Guide.
Next, run the ss7isupReload command to commit the changes in the ISUP
library and TDi routing table.

NOTE

Do not use the IsupMgr::Reload method must in CIC-based distribution mode.

ISUP Loopback Mode


Loopback can only be used when CIC-based distribution is disabled.

Flow Control and Congestion Handling


Flow control and congestion handling mechanisms are not affected by the
distribution mode.

Online Upgrade
Online upgrade is supported (but with current shared library limitations).

444

Chapter 12

Using the ISUP API


API Structure

API Structure
The HP OpenCall SS7 ISUP API is a C++ interface that provides the application
with a single abstract view of the HP OpenCall SS7 ISUP library and its functions.
Its major objects conform to the following object model:

Chapter 12

IsupMgr

IsupProbe

IsupSMProbe/IsupBPProbe

445

Using the ISUP API


API Structure

Figure 12-4

Object Model1

IsupMgr
This is the management object class for the HP OpenCall SS7 ISUP API. The main
function of an IsupMgr object is to handle all the central processing for the API such
as scheduling, timers and loading of the ISUP configuration file. It also creates,
initializes and schedules probe objects.
1. This diagram was developed using the object model notation described in
Object-Oriented Development: The Fusion Method
Prentice-Hall International, Englewood Cliffs, New Jersey, 1994
446

Chapter 12

Using the ISUP API


API Structure
Only one instance of the IsupMgr is allowed per application.

IsupProbe
The probe objects supported by the HP OpenCall SS7 ISUP API are derived from a
single base class, IsupProbe. This class defines the common probe methods which
include opening, closing and managing the SS7 stack connections (probe objects).
Derived from this base class are two Probe classes:

IsupSMProbe

IsupBPProbe

IsupSMProbe
An object belonging to this class corresponds to an SS7 stack connection, and uses
the state-machine access mode to exchange primitives and messages concerning
Call Processing Control (CPC) and Circuit Supervision Control.
Though this class inherits its general activation and deactivation methods from
IsupProbe, its objects are initialized by the IsupMgr object.

IsupBPProbe
IsupBPProbe objects allow ISUP primitives and messages to be directly exchanged
with MTP Level 3, bypassing the state-machines. Like IsupSMProbe objects, they
are dedicated to SS7 stack connections and are initialized by the IsupMgr object.

Chapter 12

447

Using the ISUP API


Outline of the Basic Application

Outline of the Basic Application


The basic aim of the HP OpenCall SS7 ISUP is to allow you to develop both simple
and complex applications using the API objects. Although each application is
different, you must use and manage probe objects to exchange ISUP messages.
The application should incorporate the following structure. Designing the
application in relation to this skeleton structure will enhance the operation of the
application with regard to the HP OpenCall SS7 ISUP library.

General Application Structure


//
//
//
//
//
//
//
//

448

initialize_IsupMgr_object
if (initialize_IsupMgr_object != Ok) then
error handling
fi
create_Probe_object()
open_Probe_object()
schedule_Probe_object()

Chapter 12

Using the ISUP API


Initializing the IsupMgr object

Initializing the IsupMgr object


The static IsupMgr::init method creates and initializes the IsupMgr object. If
the application has previously created an IsupMgr object, then all subsequent calls
to the IsupMgr::init method return a pointer to this IsupMgr object and the
corresponding return value.
For details about the syntax, parameters, and return values of the IsupMgr::init
method see the IsupMgr(3) man page.

Loading the Configuration File


The IsupMgr::init method automatically loads a configuration file specifically
created for HP OpenCall SS7 ISUP. By default, this is a file identified by the
Application Identifier 0. Otherwise it is a file specified during configuration. This
configuration file contains Local Point Code (LPC), Destination Point Codes
(DPC), message set type and circuit information.
The call to the IsupMgr::init method may fail due to errors in this
configuration file.
Example 12-1

Initializing the IsupMgr Object


// initialize_IsupMgr_object()
// if (initialize_IsupMgr_object() != Ok) then
//
error handling
// fi
IsupMgr * isupMgr;
ISUP::InitStatus initStatus;
AppId=0;
// initialize IsupMgr object
initStatus = IsupMgr::init(isupMgr,AppId);
if (!(initStatus.isOk())){
cout << IsupMgr: init failed: << initStatus << \n <<
flush;
// error recovery
}

Chapter 12

449

Using the ISUP API


Creating and Opening a Probe Object

Creating and Opening a Probe Object


The application must request the HP OpenCall SS7 ISUP API to create a probe
object to exchange signaling information with the SS7 network via an SS7 stack.
Once a probe object has been created, it must be opened to activate the connection.
It can be opened as:

a single connection

(This type of connection is opened when application high availability is not


required.)

one of the connections in a active/standby configuration

(Such connections are used to provide a 2-host configuration with an active and a
standby application. The active application is opened on the primary connection, the
standby application is opened on the secondary connection. Both applications are
connected to the SS7 stack to enable application switchover.)

Creating a Probe Object


As no direct constructor exists for IsupSMProbe and IsupBPProbe, it is the
responsibility of the IsupMgr (factory) object to create each probe object using the
createSMProbe() and createBPProbe() methods.
For details about the syntax, parameters, and return values of the
createSMProbe() and createBPProbe() methods, see the IsupMgr(3) man
page.
The probe object is bound to an SS7 stack by the stacks classname (className).
Each classname must first be declared in the HP OpenCall SS7 ISUP configuration
file.
The ActivityObject is described in Using the Activity Object on page 462.

Opening a Connection
After the object has been created, you must explicitly open the connection to an SS7
stack and activate a probe object using the open()method.
For details about the syntax, parameters, and return values of the open() method,
see the IsupProbe(3) man page.

450

Chapter 12

Using the ISUP API


Creating and Opening a Probe Object

Primary and Secondary Connections


The API provides functionality that allows you to choose the connection mode that
is used when an ISUP application opens a connection via the ISUP API:

primary connection mode an application running over a primary connection

secondary connection mode for a an application running over a secondary


connection

The ISUP API provides this information to the SS7 stack (MTP L3) when the
connection is established.
Switching
The stack can switch from the primary to the secondary connection upon request of
the application running over the secondary connection or on primary application
failure. In the first case, the primary connection becomes the secondary, and the
secondary becomes the primary and is aware of MTP status (mtp_available,
mtp_unavailable, mtp_congested, mtp_uncongested,
mtp_restarting).
The diagram below shows how switchover occurs:

Chapter 12

451

Using the ISUP API


Creating and Opening a Probe Object
Figure 12-5

452

Switching

Chapter 12

Using the ISUP API


Creating and Opening a Probe Object
Restrictions Related to Switching
A primary connection already exists and a new one is requested: the new connection
becomes primary and the old one becomes the secondary connection.

A secondary connection wants to be primary: the previous primary is disabled


(becomes secondary) without notification from the SS7 stack. The new primary is
aware of the LPC state.

Chapter 12

453

Using the ISUP API


Creating and Opening a Probe Object
A primary connection is broken: the secondary connection becomes primary
automatically.

NOTE

It is impossible to perform the connection switchover from the application using the
primary connection. It is always the application using the secondary connection that
initiates the switchover with the enable command.

NOTE

The stack behavior is affected by the following parameters: AutoSwitch,


CloseonCreate, and CloseonEnable. For more details, see Table 4-1 on page 85.

Example 12-2

Creating and Opening an IsupSMProbe Object

ISUP::OpenStatus
openStatus;
ISUP::CreateStatus
createStatus;
IsupSMProbe*
isupSMProbe;
IsupSMProbe::ActivityObject* const activityObj =new ActivityObject();
char* className = new char [16];
// create_Probe_object()()
// if (create_Probe_object() != Ok) then
//
destroy_Probe_object()
//
error handling
// fi
createStatus = isupMgr->createSMProbe(className,activityObj,isupSMProbe);
if (!createStatus.isOk()) {
cout << "IsupSMProbe creation failed \n" << flush;

454

Chapter 12

Using the ISUP API


Creating and Opening a Probe Object
cout << "Error=" createStatus "\n" << flush;
// destroy probe
// error recovery
}
// open_Probe_object()
// if (open_Probe_object()!= Ok) then
//
close_Probe_object()
//
destroy_Probe
//
error handling
// fi
openStatus = isupSMProbe->open(ISUP::PRIMARY, HPAIN::bTrue);
if (! openStatus.isOk()){
cout << " isupSMProbe opening failure \n" << flush;
//
//
//
//

close_Probe_object()
destroy_probe_object
delete_activity_object
error recovery

Example 12-3

Creating and Asynchronously Opening an IsupSMProbe Object

ISUP::OpenStatus
ISUP::CreateStatus
IsupSMProbe*
IsupAdditional::Info*
IsupAdditional::NotifOpenCnx*
HPAIN::Uint32
IsupSMProbe::ActivityObject*
char*
//
//
//
//
//
//

openStatus;
createStatus;
isupSMProbe;
indication;
notifOpenCnx = NULL;
nbIndication;
const activityObj = new ActivityObject();
className = new char [16];

create an IsupSMProbe object


create_Probe_object()()
if (create_Probe_object() != Ok) then
destroy_Probe_object()
error handling
fi

createStatus = isupMgr->createSMProbe(className,activityObj,isupSMProbe);
if (!createStatus.isOk()) {
cout << "IsupSMProbe creation failed \n" << flush;
cout << "Error=" createStatus "\n" << flush;
// destroy probe
// error recovery
}

Chapter 12

455

Using the ISUP API


Creating and Opening a Probe Object

// open_Probe_object()
// if (open_Probe_object()!= Ok) then
//
close_Probe_object()
//
destroy_Probe
//
error handling
// fi
openStatus = isupSMProbe->open(ISUP::PRIMARY, HPAIN::bFalse);
if (! openStatus.isOk()){
cout << " isupSMProbe opening failure \n" << flush;
//
//
//
//

close_Probe_object()
destroy_probe_object
delete_activity_object
error recovery

}
// Wait for Open Connection Notification
while( myIsupMgr->oamReceive(indication, nbIndication).getStatus() ==
ISUP::OamStatus::OPEN_CNX_IN_PROGRESS )
{
// schedule ISUP library
}
// Check if aysnchronous open connection was successful
if( indication != NULL )
{
// Safe cast to NotifOpenCnx object
notifOpenCnx = IsupAdditional::NotifOpenCnx::castInfo( indication );
}
if( notifOpenCnx == NULL )
{
cout << " isupSMProbe opening failure: no Open Connection Notification \n" <<
flush;
//
//
//
//

close_Probe_object()
destroy_probe_object
delete_activity_object
error recovery

456

Chapter 12

Using the ISUP API


Creating and Opening a Probe Object

else if( !notifOpenCnx->successful() )


{
cout << " isupSMProbe opening failure: negative Open Connection Notification \n" <<
flush;
//
//
//
//

close_Probe_object()
destroy_probe_object
delete_activity_object
error recovery

Chapter 12

457

Using the ISUP API


Scheduling Probe Objects

Scheduling Probe Objects


Via the created and active probe objects, the application requests the API to
exchange ISUP messages on its behalf. This is achieved by the APIs asynchronous
services, which allow the application to complete other tasks until the API returns a
response to the request.
It is the scheduling mechanism which provides these asynchronous services. The
mechanism is based on select(), a system call which allows I/O multiplexing,
and contains 3 phases:

Pre-select

Select()

Post-select

Pre-select
The pre-select phase is used to set up certain masks and time values according to
API requirements.
Masks
The read_mask, write_mask and exception_mask input parameters are bit
masks used by the API to shield the IPC descriptions from the application. Do not
override the masks by setting them to NULL in you application. They can contain
IPC file descriptors managed by the application. Reset (using FD_ZERO) all the
select masks that will be used by the application before you enter the pre-select,
post-select loop.
The application must initially create these three bit masks in the standard OS
manner.
Timeout Value
The application must also provide the API with a timeout value, which is the
maximum length of time that the CPU is allowed to be blocked if there is no I/O
activity. The API assesses its own requirements and thus, decreases this value to a
minimal value, such as 500ms.

458

Chapter 12

Using the ISUP API


Scheduling Probe Objects
selectMask()
The API provides the pre-select method selectMask() to update and modify the
masks and timeout value provided by the application.
Using the contents of the read, write and exception masks, selectMask()sets the
file descriptor masks to indicate the file descriptors used by the API. The file
descriptors managed by the application are left untouched. The returned bit masks
are then used by select().
The application must call IsupMgr::selectMask() before each select().
For details about the syntax, parameters, and return values of selectMask()
method, see the IsupMgr(3) man page.

Select()
This second phase is the basis of the scheduling mechanism.
select() examines the file descriptors specified by the read, write and execute bit
masks. When select() is successful, it modifies and returns these bit masks. The
respective masks indicate if a file descriptor is ready for reading or writing, or if
there is a pending exception condition.

For details about the syntax, parameters, and return values of select() method,
see the select() man page.

Chapter 12

459

Using the ISUP API


Scheduling Probe Objects

Post-select
The post-select phase analyses the results of select() for the API and triggers the
necessary processing for the file descriptors (connections) managed by the API.
Processing is based on the Work value returned by either IsupMgr::handler()
or IsupMgr::doWork().
For details about the syntax, parameters, and return values of the
IIsupMgr::handler() and IsupMgr::doWork() methods, see the
IsupMgr(3) man page.
Work
Both IsupMgr::handler() and IsupMgr::doWork() return a value known as
Work to the application. This value indicates the number of ISUP messages waiting
to be received from the network.
handler()
The IsupMgr::handler() determines whether there are primitives to be
received from any of the active connections identified in the read bit mask. If there
are messages to be received, they are stored in a receive buffer.
It manages all the internal mechanisms and must be called after every OS
select(). As the IsupMgr::handler() returns just an estimation of the
processing to be done by the API, its CPU overhead is quite low.
It may occur that none of the connections require servicing, such as an internal
timeout has been received.
doWork()
After the IsupMgr::handler() call has returned, IsupMgr::doWork()
processes the ISUP messages that are waiting to be received. It activates the
state-machines and HP OpenCall SS7 ISUP internal mechanism. Finally, it can use
the Activity object mechanism to indicate to the application how many primitives are
waiting to be received.

460

Chapter 12

Using the ISUP API


Using the Activity Object

Using the Activity Object


HP OpenCall SS7 ISUP provides a way to optimize HP OpenCall SS7 ISUP API
calls through the ActivityObject. Implementing the ActivityObject takes
advantage of the callback methods provided by this object.

Criteria for Choosing to Implement the Activity Object


If you do not use the Activity Object
If you choose not to use the ActivityObject, the application must perform the
following tasks.

In case of outbound flow-control the application must regularly call the


IsupProbe::send() method to know if the flow-control condition is still
present

The application must regularly call the IsupProbe::receive() method to


receive all inbound ISUP messages.

If you Implement the Activity Object


If you choose to implement an ActivityObject the HP OpenCall SS7 ISUP API
provides the application with following information:

Chapter 12

the number of ISUP messages waiting to be received through the


recvActivity() method

the end of an outbound flow-control condition through the sendPossible()


method

any change of the MTP connection status through the cnxStatus() method.

461

Using the ISUP API


Using the Activity Object

How to use the Activity Object


You can derive an activity object mechanism for IsupSMProbe and
IsupBPProbe objects. The aim of the mechanism must be to inform the probe
object(s) that primitives are waiting to be received by the application. The
mechanism must also inform the probe object(s) whether it is possible to send ISUP
messages and primitives, and the status of the connection.
An ActivityObject class is defined by IsupSMProbe and IsupBPProbe.
These classes contain the following virtual methods:

Table 12-1
Return Type
virtual void

Activity Methods
Method
recvActivity()

Arguments
(IsupSMProbe *aProbe,
int nbOfRecvToDo)=0;
(IsupBPProbe *aProbe,
int nbOfRecvToDo)=0;

virtual void

sendPossible()

(IsupSMProbe * aprobe)=0;
(IsupBPProbe * aprobe)=0;

virtual void

cnxStatus()

(IsupSMProbe * aProbe,
ISUP::CnxStatus aStatus)=0;
(IsupBPProbe * aProbe,
ISUP::CnxStatus aStatus)=0;

Redefining the Activity Methods


The application can derive its own ActivityObject classes from the provided
parent class. You can then redefine the ActivityObject methods, using the same
arguments.

462

Chapter 12

Using the ISUP API


Using the Activity Object
recvActivity()
From the inbound path, the IsupSMProbe::recvActivity() and
IsupBPProbe::recvActivity() methods must provide the number of
primitives waiting to be received by a specific probe object.

NOTE

It must not receive the waiting primitives.

sendPossible()
From the outbound path, the IsupSMProbe::sendPossible() and
IsupSMProbe::sendPossible() methods must indicate whether it is possible
to send messages from a specific probe object to the network.
cnxStatus()
The cnxStatus() must indicate the status of the connection with the SS7 stack,
such as switchover or the connection has been closed.
Example 12-4

Redefining the recvActivity() for an IsupSMProbe Object.

// activity object inheriting from IsupSMProbe: definition and


// implementation
class
{
void
void
void
};

MyActivityObject: public IsupSMProbe::ActivityObject


recvActivity(IsupSMProbe * aProbe, int nbOfRecvToDo);
sendPossible(IsupSMProbe * aProbe);
cnxStatus(IsupSMProbe * aProbe, ISUP::CnxStatus aStatus);

// List of Pending messages for each active ProbeList_of_p<RecvToDo> *listOfRecvToDo;


//--------------------------------------------------------------------//
Implementation of callback method MyActivityObject::recvActivity()
//
<< DO NOT CALL receive in this callback method !! >>
//
//--------------------------------------------------------------------void MyActivityObject::recvActivity(IsupSMProbe * aProbe, int nbOfRecvToDo)
{
RecvToDo * recvToDo;
recvToDo= new RecvToDo (aProbe, nbOfRecvToDo);
if (listOfRecvToDo == NULL)
listOfRecvToDo = new List_of_p<RecvToDo>;

Chapter 12

463

Using the ISUP API


Using the Activity Object
listOfRecvToDo->put (recvToDo);
}

464

Chapter 12

Using the ISUP API


Exchanging Messages via Probe Objects

Exchanging Messages via Probe Objects


Using their send() and receive() methods, IsupSMProbe and IsupBPProbe
objects exchange primitives and messages. It is important that the primitives and
messages are consistent types, otherwise these methods will fail with the
corresponding error.
Manipulating and exchanging signaling information via probe objects is described
in detail in Chapter 13, Exchanging ISUP Messages,.
Example 12-5

Exchanging Messages via an IsupSMProbe object.

ISUP::RecvStatus
ISUP::SendStatus
IsupSMProbe *
IsupSMProbe::PrimitiveType
ISUP::Address
IsupMsg *
IsupAdditional::Info *
int

recvStatus;
sendStatus;
isupSMProbe;
primitive;
address;
isupMsg;
info;
nbIndication;

// receive messages
do { recvStatus=isupSMProbe->receive(primitive,address,isupMsg,info,nbIndication);
if (!recvStatus.isOk()){
cout << receive failed << recvstatus << \n << flush;
// error recovery
}
// process the message contents.
} while (nbIndication >0 );
// select IAM message and assign values, including address info,
// send message
sendStatus=isupSMProbe->send(IsupSMProbe::SETUP_REQ, address, isupMsg, info);
if (!sendStatus.isOk()){
cout << send failed = << sendStatus << \n<< flush ;
delete isupMsg;
delete info;
// error recovery
}

Chapter 12

465

Using the ISUP API


Closing and Destroying a Probe

Closing and Destroying a Probe


Closing and destroying a probe object should only be done when you are certain that
it will no longer be used. Its lifespan must be carefully considered, as recreating and
re-opening a probe object places a high overhead on the API mechanism.
Closing and destroying a probe object does not stop the application, it only closes
the connection to the SS7 stack.

Close()
This method closes the socket connection between a probe object and an SS7 stack.
You must do this before destroying the probe object.
For details about the syntax, parameters, and return values of the close() method,
see the IsupProbe(3) man page.

Destroy()
Only when the probe object has been closed, should you destroy it. After destroying
it, the pointer to the destroyed probe object is set to NULL, thus avoiding its
subsequent use.
When a probe object is destroyed, its activity object is not automatically destroyed.
For details about the syntax, parameters, and return values of the destroySMProbe
and destroyBPProbe() methods, see the IsupMgr(3) man page.
The usual time to destroy a probe object is at application termination. Normally, you
do not destroy a probe object during the life of the application.
Example 12-6

Closing and Destroying an IsupSMProbe Object

ISUP::CloseStatus
ISUP::DestroyStatus
IsupSMProbe *
MyActivityObject *

CloseStatus;
* destroyStatus;
IsupSMProbe;
const anActivityObject= new myActivityObject();

closeStatus = isupSMProbe->close();
if (!closeStatus.isOk()){
cout << IsupSMProbe:: failure to close Probe /n << flush;
cout << Error = << closeStatus << /n << flush;
// error recovery
}

466

Chapter 12

Using the ISUP API


Closing and Destroying a Probe
destroyStatus = isupMgr->destroySMProbe(isupSMProbe);
if (!destroyStatus.isOk()){
cout << IsupSMProbe:: failure to destroy Probe /n << flush;
cout << Error = << destroyStatus << /n << flush;
// error recovery
}
delete myActivityObject;

Chapter 12

467

Using the ISUP API


Receiving Notifications

Receiving Notifications
oamReceive()
Reload Procedure
During a reload procedure, the user application can receive notifications containing
the ISUP configuration changes. This mechanism can be enabled/disabled by setting
the ReportOnReload parameter to Yes/No in the static or in the dynamic
configuration.
To receive these notifications, the user application must call the
IsupMgr::oamReceive() function. If the ReportOnReload parameter is set to
YES and if the user application does not call IsupMgr::oamReceive(), this can
seriously impact the application behavior.
Notifications Sent About Events in the ISUP Library
The following notifications are used to inform the application about events in the
ISUP library:
Table 12-2
Notification

ISUP Receive Notifications


Event

Read Accessors

IsupAdditional::
NotifOpenCnx

Notifies the
termination of an
asynchronous
open connection
procedure.

OPC() returns the LPC value of the stack with which the
ISUP library has attempted to open a connection.
successful() returns the outcome of the open connection
procedure.

IsupAdditional::
NotifDelDpc

Notifies that a
DPC has been
removed from
the
configuration.

OPC() returns the LPC value.


DPC() returns the DPC value.

468

Chapter 12

Using the ISUP API


Receiving Notifications
Table 12-2
Notification
IsupAdditional::
NotifDelCics

ISUP Receive Notifications (Continued)


Event
Notifies that a
range of circuits
has been
removed from
the
configuration.

Read Accessors
OPC() returns the LPC value.
DPC() returns the DPC value.
CICMIN() returns the first CIC of the range.
CICMAX() returns the last CIC of the range.
NOTE: If CICMIN() and CICMAX() return the same
value, only one CIC has been removed.

IsupAdditional::
NotifAddDpc

Notifies that a
DPC has been
added.

OPC() returns the LPC value.


DPC() returns the DPC value.
MsgSetName() returns the message set applicable to the
added DPC.
releaseCause() returns the ReleaseCauseValue
corresponding to the added DPC.

IsupAdditional::
NotifCics

Notifies that a
range of circuits
has been added
or modified.

OPC() returns the LPC value.


DPC() returns the DPC value.
CICMIN() returns the first CIC of the range.
CICMAX() returns the last CIC of the range.
getOperation() returns whether the circuits have been
added or modified (return value are: CICS_ADDED or
CICS_MODIFIED).
reserved() returns the circuit status.
defaultGroup() returns the defaultGroup corresponding
to the circuit added or modified.
NOTE: defaultGroup() is only available for ANSI.

For a description of the accessor return types, see the


/opt/OC/include/ISUP/IsupAdditionalInfo.h file.
For any IsupAdditionalInfo received, you must:
1. Get the AdditionalInfo type using getInfoType().
2. Cast the AdditionalInfo on the right class using castInfo(const
Info* P_addInfo).
3. Get information from the AdditionalInfo using the corresponding Read
Accessors.

Chapter 12

469

Using the ISUP API


Receiving Notifications
An example of the implementation of the use of the IsupMgr::oamReceive()
function is available in the IsupServer tutorials. See ISUP Tutorial Programs on
page 480.
Example 12-7

oamReceive()

IsupAdditional::Info

*L_InfoRecvPtr=NULL; // additional information

ISUP::OamStatus

L_OamStatus; // status returned by receive cmd

HPAIN::Schedulable::Work

L_handler; // enum returned by handler

int
int
fd_set
fd_set
timeval
timeval
timeval
struct timezone
int
int
HPAIN::Uint32
char

maxFd;
numFd;
readMask;
writeMask;
time;
* timeout;
delay0, delay1;
delayzone;
timediff=0;
L_TimeMax = TIME_MAX;
L_nbIndication; // nb of messages to be read
L_str[40];

// scheduling part
memset(&readMask, 0, sizeof(fd_set));
memset(&writeMask, 0, sizeof(fd_set));
// start the timer to measure the delay of reception
gettimeofday( &delay0, &delayzone);

// as long as the primitive expected is not received


while (timediff <= L_TimeMax) {
// elapsed time
gettimeofday( &delay1, &delayzone);
timediff = CLK_diff ( &delay1, &delay0) / 1000000 ;
// if there is no more message to receive
if (G_MoreMessageToRead == 0 ) {
time.tv_sec = 5;
time.tv_usec = 0;
timeout = &time;
maxFd = IsupMgr->selectMask(0,&readMask,&writeMask,0,timeout);
if ((numFd = select(maxFd,&readMask, 0, 0, timeout))== -1) {
// if select failed only warning and go on (AT 3/96)

470

Chapter 12

Using the ISUP API


Receiving Notifications
cout << " Warning: select failed" << flush;
} // if
L_handler = IsupMgr->handler(numFd,&readMask,&writeMask,0);
if (L_handler>200) L_handler=200;
} // if G_MoreMessageToRead
// receive a message **********************
L_OamStatus = IsupMgr->oamReceive( L_InfoRecvPtr, L_nbIndication);
// number of messages to treat
G_MoreMessageToRead=L_nbIndication;
// check the result **********************
// if NO_MSG, we read again until time max
if (L_OamStatus.getStatus() != ISUP::OamStatus::NO_ERROR &&
L_OamStatus.getStatus() != ISUP::OamStatus::RELOAD_IN_PROGRESS) {
// an error occured and is unexpected error
cout << " Error received " << flush;
}
// print the message ******************
if (L_InfoRecvPtr) {
cout << "Notification RECEIVED = " << L_InfoRecvPtr << flush;
delete L_InfoRecvPtr;
} // if L_InfoRecvPtr
else {
G_MoreMessageToRead=0;
}
} // while

oamStatus()
During a reload/dump procedure, if you want to know when these procedures are
completed, this method can be used.
Example 12-8

oamStatus()

ISUP::OamStatus
HPAIN::Schedulable::Work
int
int
fd_set

Chapter 12

L_OamStatus; // status returned by receive cmd


L_handler; // enum returned by handler
maxFd;
numFd;
readMask;

471

Using the ISUP API


Receiving Notifications
fd_set
timeval
timeval
timeval
struct timezone
int
int

writeMask;
time;
* timeout;
delay0, delay1;
delayzone;
timediff=0;
L_TimeMax = TIME_MAX;

// scheduling part
memset(&readMask, 0, sizeof(fd_set));
memset(&writeMask, 0, sizeof(fd_set));
// start the timer to measure the delay of reception
gettimeofday( &delay0, &delayzone);
// as long as the primitive expected is not received
while (timediff <= L_TimeMax) {
// elapsed time
gettimeofday( &delay1, &delayzone);
timediff = CLK_diff ( &delay1, &delay0) / 1000000 ;
// if there is no more message to receive
time.tv_sec = 5;
time.tv_usec = 0;
timeout = &time;
maxFd = IsupMgr->selectMask(0,&readMask,&writeMask,0,timeout);
if ((numFd = select(maxFd,&readMask, 0, 0, timeout))== -1) {
// if select failed only warning and go on (AT 3/96)
cout << " Warning: select failed" << flush;
} // if
L_OamStatus = IsupMgr->OamStatus();
// if NO_MSG, we read again until time max
if (L_OamStatus.getStatus() != ISUP::OamStatus::NO_ERROR &&
// an error occured and is unexpected error
cout << " OamStatus error received " << flush;
} // while

472

Chapter 12

Using the ISUP API


Return Status Values

Return Status Values


Error handling is provided via values known as Return Status values. On execution
of all methods, an associated Return Status value indicates whether the method was
successful or erroneous, and the reason for the error, if any.
The following table indicates the common return status classes for IsupMgr and
IsupProbe methods, and their returned values.
The isOK() method can be used to check for successful completion.

Table 12-3

Probe Return Status Values

Status Class
InitStatus

CnxStatus

Chapter 12

Value

Reason

NO_ERROR

No error has occurred during Isupmgr


initialization.

ALREADY_CREATED

IsupMgr already exists.

NO_MORE_MEMORY

Problem occurred during memory allocation


for the IsupMgr.

NO_ISUP_CONFIG

Access to the HP OpenCall SS7 ISUP


configuration file has been denied.

BAD_ISUP_CONFIG

Erroneous or missing configuration file


provided for IsupMgr initialization.

INTERNAL_ERROR

An internal HP OpenCall SS7 ISUP error has


occurred.

NO_ERROR

No error for connection.

CNX_CLOSED

SS7 stack connection closed.

API_BUSY

Switchover in progress.

INTERNAL_ERROR

Internal HP OpenCall SS7 ISUP IPC error has


occurred.

473

Using the ISUP API


Return Status Values
Table 12-3

Probe Return Status Values (Continued)

Status Class
CreateStatus

DestroyStat
us

474

Value

Reason

NO_ERROR

Probe/connection created.

NO_MORE_MEMORY

Problem occurred during memory allocation


for the Probe object.

MAX_PROBE_NUMBER_
EXCEEDED

Maximum number of Probes has been reached.

ALREADY_CREATED

A Probe already exists for this LPC.

LPC_NOT_FOUND

LPC not found in configuration file.

INVALID_CLASSNAME

Unknown SS7 stack classname.

INVALID_SET_NAME

An invalid name for the set of messages has


been associated with a specific LPC.

WRONG_PROBE_TYPE

Different Probe type declared in


HP OpenCall SS7 ISUP configuration file.

INTERNAL_ERROR

Internal HP OpenCall SS7 ISUP IPC error has


occurred.

NO_ERROR

Probe/connection destroyed.

ALREADY_DESTROYED

Probe was previously destroyed.

Chapter 12

Using the ISUP API


Return Status Values
Table 12-3

Probe Return Status Values (Continued)

Status Class
OpenStatus

CloseStatus

Value

Reason

NO_ERROR

Probe/connection open.

NO_CONFIG

Configuration file could not be accessed.

BAD_GLOBAL_CONFIG

SS7 stack name not found in parsed


configuration file. The classname should be
checked.

CONNECT_INIT

Connection attempt rejected.

API_BUSY

High Availability switchover in progress.

ALREADY_OPEN

Probe/connection is already open.

INTERNAL_ERROR

Internal HP OpenCall SS7 ISUP IPC error has


occurred.

BAD_CNX_TYPE

Connection type is wrong (should be primary


or secondary)

NO_ERROR

Probe/connection closed.

PROBE_NOT_OPEN

Probe object not connected to the SS7 stack.

ALREADY_CLOSED

Probe object already closed.

IPC_SEND_FULL

IPC socket to SS7 stack is congested.

CLOSE_FAILED

Unable to close the SS7 stack connection.

INTERNAL_ERROR

Internal HP OpenCall SS7 ISUP IPC error has


occurred.

For information on return values related to creating and exchanging messages, refer
to the IsupMgr(3) man page.

Chapter 12

475

Using the ISUP API


Using Dynamic Configuration

Using Dynamic Configuration


Dynamic configuration enables you to modify the running ISUP. The changes are
allowed (any other changes will be refused):

modify the reportOnReload flag

add/remove DPCs

add/modify/remove CICs

Once you have prepared the changes dynamically, you can dynamically reload the
new configuration into the ISUP library using the dynamic reload procedure.
During the reload procedure, the user application can receive notifications
containing the ISUP configuration changes.

reload()
Once the ISUP dynamic configuration changes are defined using the cfgIsup
command (for a description, see the man page), then you can perform a reload to the
ISUP library. You can perform this reload using IsupMgr::reload().
The reload procedure:
1. Reads the new configuration generated by the cfgIsup command (for a
description, see the man page) in the file:
/var/opt/OC/ISUP/isup.app<applicationId>.changes
2. Makes all the changes.
3. Dumps the new configuration in a temporary file:
/var/opt/OC/ISUP/isup.app<applicationId>.conf.dump.
You can also reload using the ss7IsupReload command delivered (see the
DynamicConfiguration man page). Using this command is the recommended
procedure, except in CIC-based distribution mode. You can only perform one
reload/dump operation at a time.

NOTE

476

Do not use the IsupMgr::reload method in CIC-based distribution mode.

Chapter 12

Using the ISUP API


Using Dynamic Configuration

NOTE

If you are using ISUP dynamic configuration and the ISUP application is protected
by the PIC/AG, then you must set the ReloadSignal to SIGUSR2 (the default is
SIGUSR1) using the cfgIsup command (for a description, see the man page).
Otherwise, the ISUP application does not reload the new configuration (it never
receives the SIGUSR1 signal from the ss7IsupReload command).

Example 12-9

reload()
ISUP::ConfigStatus L_CStatus = IsupMgr::reload();
if (!L_CStatus.isOk()) {
cout << "reload failed" << flush;
return (RELOAD_ERROR);
}

return (RELOAD_STARTED);

dump()
If you need to dump the current ISUP configuration used by the application, this
method can be used.
Example 12-10

Using reload feature


ISUP::ConfigStatus L_CStatus = IsupMgr::dump();
if (!L_CStatus.isOk()) {
cout << "dump failed" << flush;
return (DUMP_ERROR);
}
return (DUMP_STARTED);

Chapter 12

477

Using the ISUP API


ISUP Tutorial Programs

ISUP Tutorial Programs


Tutorials (that is, example programs) are provided with HP OpenCall SS7 ISUP.
The syntax of their names are:
{Client}(SM}{ANSI}
isup{
}{ }{
}
{Server}{BP}{ITU }

All the possible combinations exist, giving 8 in total: isupClientSMAMNSI,


isupClientSMITU, ..., isupServerBPITU.
The tutorials show how to develop a simple call setup/release application using the
methods provided by the HP OpenCall SS7 ISUP.
The source code of these tutorials is in the /opt/OC/tutorials/ISUP directory.

CAUTION

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

NOTE

These tutorials use the ITU-T 88 or TTC version of the HP OpenCall SS7 ISUP
API.

Using State-machine Access


The Caller and Callee show how to develop an application by using the
state-machine mode of access (IsupSMProbe) and its associated methods.

478

Caller

isupClientSMANSI or isupClientSMITU

Callee

isupServerSMANSI or isupServerSMITU

Chapter 12

Using the ISUP API


ISUP Tutorial Programs

Using Bypass Access


The Caller and Callee show how to develop an application specifically using the
bypass access mode (IsupBPProbe) and its associated methods.

Chapter 12

Caller

isupClientBPANSI or isupClientBPITU

Callee

isupServerBPANSI or isupServerBPITU

479

Using the ISUP API


ISUP Makefiles

ISUP Makefiles
The following makefiles are provided with HP OpenCall SS7 ISUP:

CAUTION

480

/opt/OC/tutorials/ISUPMakefileANSI

/opt/OC/tutorials/ISUPMakefileITU

If you want to change a makefile or a tutorial supplied with HP OpenCall SS7, you
must first copy it to your own working directory. You must not change the sources
supplied with the HP OpenCall SS7 product in the directories in which they are
delivered.

Chapter 12

Using the ISUP API


ISUP Makefiles

Chapter 12

481

Using the ISUP API


ISUP Makefiles

482

Chapter 12

13

Exchanging ISUP Messages


This chapter describes how to create, manipulate and exchange standard ANSI and
ITU-T messages. It also describes the various primitives provided for
IsupSMProbe and IsupBPProbe objects.

Chapter 13

483

Exchanging ISUP Messages


Introduction

Introduction
The HP OpenCall SS7 ISUP API provides the application with programming access
to supported ISUP messages via C++ object classes. It gives a single abstract view
of the ISUP messages independent of the message layout.
This chapter describes the selection, creation and manipulation of these messages.

484

Chapter 13

Exchanging ISUP Messages


Exchanging Primitives

Exchanging Primitives
Dialogue between different layers is performed by primitives which are abstract
elementary functions used to exchange information. As indicated in Figure 13-1,
ISUP Primitives, an application such as Call Control requests the services provided
by ISUP via specific primitives.
The set of ISUP primitives is divided into four categories:

Figure 13-1

Chapter 13

Request

Indication

Response

Confirmation

ISUP Primitives

485

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives

HP OpenCall SS7 ISUP Primitives


MTP Level 3 can be accessed either via the HP OpenCall SS7 ISUP state-machines
using IsupSMProbe objects or directly via IsupBPProbe objects. Both classes of
probe objects exchange primitives with the API to request, and respond to, the
services supported by the HP OpenCall SS7 ISUP library.
Because IsupSMProbe objects interact with the HP OpenCall SS7 ISUP library
differently from IsupBPProbe objects, a distinct group of primitives is associated
with each probe class.

Acknowledgment Primitives
In addition to the standard ISUP primitives, HP OpenCall SS7 ISUP provides
acknowledgment primitives.
These primitives enable the application to be synchronized with the
HP OpenCall SS7 ISUP library. This mainly applies to the circuit internal reset and
release primitives such as START_RELEASE_IND. When HP OpenCall SS7 ISUP
realizes that a circuit must be reset, it informs the application and then waits for an
acknowledgment.
For example, the application may have to reset some hardware and software on
reception of RESET_IND. The application will reply with a RESET_RESP when the
hardware and software reset is completed. On receipt of the acknowledgment,
HP OpenCall SS7 ISUP sends the corresponding message(s) to the network.
Scenarios involving these acknowledgment primitives are described in:

Chapter 15, Introduction to ISUP Procedures,

Chapter 16, ISUP Call Control - Procedures Common to ANSI and ITU-T,

Chapter 18, ISUP Call Control - Procedures Specific to ANSI,

Chapter 19, ISUP Call Control - Procedures Specific to ITU-T.

Attempt To Use Non-Supported Message


When a primitive associated with an ISUP message is used with a standard that does
not support the message, the HP OpenCall SS7 ISUP behavior is as follows:

486

an attempt to create the message is refused with the


ISUP::SendStatus::INVALID_MESSAGE error status,

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives

Chapter 13

an attempt to send the primitive is refused with the


ISUP::SendStatus::ILLEGAL_PRIMITIVE error status.

487

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives

State Machine Mode


ISUP SM Mode
Primitives for ANSI

Table 13-1 lists the ISUP primitives for ANSI in State Machine Mode.
For each primitive, Table 13-1 also indicates whether or not a message or an
AdditionalInfo is attached (receiving) or must be attached (sending). It also specifies
the type of message and AdditionalInfo concerned (see also Table 13-4).
Table 13-2 lists the equivalent information for ITU based flavors.

Table 13-1

ISUP Primitives for State Machine Mode - ANSI

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

ADDRESS_COMPLETE_REQ

ACM

None

ADDRESS_COMPLETE_IND

ACM

None

BACKWARD_CHECK_TONE_ACK

None

None

BLOCKING_REQ

BLO

None

BLOCKING_IND

BLO

None

BLOCKING_RESP

BLA

None

BLOCKING_CONF

BLA

None

CALL_PROGRESS_REQ

CPG

None

CALL_PROGRESS_IND

CPG

None

CIRCUIT_VALIDATION_REQ

None

None

CIRCUIT_VALIDATION_IND

CVT

None

CIRCUIT_VALIDATION_RESP

CVR

None

CIRCUIT_VALIDATION_CONF

CVR

None

488

Comments

This primitive is used by


the application to signal
that the backward tone has
been checked
(Continuity-check
procedures).

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

CIRCUIT_VALIDATION_TEST_IND

CVT

CIRCUIT_VALIDATION_TEST_RESP

CVR

CIRCUIT_VALIDATION_TEST_REQ

CVT

CIRCUIT_VALIDATION_TEST_IND

CVT

CIRCUIT_VALIDATION_TEST_RESP

CVR

CIRCUIT_VALIDATION_TEST_CONF

CVR

CONFUSION_IND

CFN

None

CONNECT_LOOP_IND

None

None

CONNECT_LOOP_IND_ACK

None

None

CONNECT_TRANSCEIVER_IND

None

None

CONNECT_TRANSCEIVER_IND_ACK

None

None

CONTINUITY_RECHECK_REQ

CCR

None

CONTINUITY_RECHECK_IND

None

None

CONTINUITY_RECHECK_CONF

None

None

CONTINUITY_REPORT_REQ

COT

None

CONTINUITY_REPORT_IND

None

None

DISABLE_ECHO_IND

None

None

DISABLE_ECHO_IND_ACK

None

None

Chapter 13

Comments

This primitive is used to


ask the application to
connect its tone loop
(Continuity-check
procedures).
This primitive is used to
ask the application to
connect its transceiver
(Continuity-check
procedures).

This primitive is used to


ask the application to
disable its echo suppressor
(Continuity-check
procedures).

489

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

ENABLE_ECHO_IND

None

None

ENABLE_ECHO_IND_ACK

None

None

EXIT_IND

EXM

None

FACILITY_REQ

FAC

None

FACILITY_IND

FAC

None

FORWARD_TRANSFER_IND

FOT

None

GROUP_BLOCKING_REQ

CGB

None

GROUP_BLOCKING_IND

CGB

None

GROUP_BLOCKING_RESP

None

None

GROUP_BLOCKING_CONF

CGBA

None

GROUP_QUERY_REQ

CQM

None

GROUP_QUERY_CONF

CQR

None

GROUP_RESET_REQ

GRS

None

GROUP_RESET_IND

GRS

None

GROUP_RESET_RESP

GRA

None

GROUP_RESET_CONF

GRA

None

GROUP_STOP_REQ

None

None

GROUP_STOP_CONF

None

None

490

Comments
This primitive is used to
ask the application to
enable its echo suppressor
(Continuity-check
procedures).

This primitive is used by


the application to ask the
ISUP library to stop
re-transmitting
REL/RSC/CGB/GRS
messages concerning a
circuit group to the SS7
network.

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

GROUP_UNBLOCKING_REQ

CGU

None

GROUP_UNBLOCKING_IND

CGU

None

Comments

None

GROUP_UNBLOCKING_RESP
GROUP_UNBLOCKING_CONF

CGUA

None

ISUP_USR_MSG_REQ

FAA, FAR,

None

FAJ, or

This primitive is used for


messages defined using
the customizing facility.

USERDEF

ISUP_USR_MSG_IND

None

None

MAINTENANCE_SYSTEM_IND

None

Maintenance
System

This primitive is used to


inform the maintenance
system of a particular
event. For more
information, see the
AdditionalInfo
section.

PASS_ALONG_REQ

PAM

None

PASS_ALONG_IND

PAM

None

This primitive is used to


send/receive any ISUP
message that is already
encoded as part of a PAM
(Pass Along Message).

RELEASE_REQ

REL

None

RELEASE_IND

REL

None

RELEASE_RESP

RLC

None

RELEASE_CONF

RLC

None

Chapter 13

491

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

REMOVE_LOOP_IND

None

None

REMOVE_LOOP_IND_ACK

None

None

REMOVE_TRANSCEIVER_IND

None

None

REMOVE_TRANSCEIVER_IND_ACK

None

None

RESET_REQ

RSC

None

RESET_IND

RSC

Reset

RESET_RESP

RLC

Reset

RESET_CONF

RLC

None

RESUME_IND

RES

None

RESUME_REQ

RES

None

SETUP_FAILURE_IND

None

None

492

Comments
This primitive is used to
ask the application to
remove its tone loop
(Continuity-check
procedures).
This primitive is used to
ask the application to
remove its transceiver
(Continuity-check
procedures).

Either an RLC message or


a Reset (AdditionalInfo),
but not both.

This primitive is used to


inform the application that
the current call setup has
failed. For more
information, see the
AdditionalInfo
section.

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

SETUP_REQ

IAM

Setup

SETUP_IND

IAM

None

SETUP_IND_ACK

None

Setup

SETUP_RESP

ANM

None

SETUP_CONF

ANM

None

SOFT_RESET_REQ

None

None

SOLICITED_INFO_REQ

INR

None

SOLICITED_INFO_IND

INR

None

SOLICITED_INFO_RESP

INF

None

SOLICITED_INFO_CONF

INF

None

UNSOLICITED_INFO_REQ

INF

None

UNSOLICITED_INFO_IND

INF

None

START_CHECK_TONE_IND

None

None

START_CHECK_TONE_ACK

None

None

START_RELEASE_IND

None

StartRelease

START_RELEASE_IND_ACK

None

None

Chapter 13

Comments

This primitive is used to


ask the application to start
checking the backward
tone (Continuity-check
procedures).
This primitive is used to
inform the application that
the current call is being
released. For more
information, see the
AdditionalInfo
section.

493

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive


START_RESET_IND

ISUP
Message
None

Additional Info
StartReset
LocalReset

START_RESET_IND_ACK

None

None

STOP_CHECK_TONE_IND

None

None

STOP_CHECK_TONE_IND_ACK

None

None

STOP_REQ

None

None

STOP_CONF

None

None

SUSPEND_IND

SUS

Suspend
-Resume

SUSPEND_REQ

SUS

Comments
This primitive is used to
inform the application that
the associated circuit is
being reset. For more
information, see the
AdditionalInfo
section.
This primitive is used to
ask the application to stop
checking the backward
tone (Continuity-check
procedures).
This primitive is used by
the application to ask the
ISUP library to stop
re-transmitting REL/RSC
messages concerning a
circuit to the SS7 network.

Suspend
-Resume
TONE_DISAPPEARS_ACK

None

None

UNBLOCKING_REQ

UBL

None

UNBLOCKING_RESP

UBL

None

UNBLOCKING_IND

UBA

None

UNBLOCKING_CONF

UBA

None

494

This primitive is used by


the application to signal
the disappearance of the
backward tone.

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-1

ISUP Primitives for State Machine Mode - ANSI (Continued)

HP OpenCall SS7 ISUP Primitive


UNEQUIPPED_CIRCUIT_IND

ISUP
Message
UCIC

Additional Info

Comments

None

ISUP SM Mode
Table 13-2 lists the ISUP primitives for ITU based flavors in State Machine Mode.
Primitives for ITU-T
For each primitive, Table 13-2 also indicates whether or not a message or an
Flavors
AdditionalInfo is attached (receiving) or must be attached (sending). It also specifies
the type of message and AdditionalInfo concerned (see also Table 13-4).
Table 13-1 lists the equivalent information for ANSI.
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

ADDRESS_COMPLETE_REQ

ACM

None

ADDRESS_COMPLETE_IND

ACM

None

ALERT_REQ

ALT

None

ALERT_IND

ALT

None

APP_TRANSPORT_REQ

APM

None

APP_TRANSPORT_IND

APM

None

BACKWARD_CHECK_TONE_ACK

None

None

Chapter 13

Comments

This is supported in TTC3


only.
This is supported in TTC3
only.
This is supported in Spr98
only.
This is supported in
Spr98only.
This primitive is used by
the application to signal
that the backward tone has
been checked
(Continuity-check
procedures).

495

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

BLOCKING_REQ

BLO

None

BLOCKING_IND

BLO

None

BLOCKING_RESP

BLA

None

BLOCKING_CONF

BLA

None

CALL_PROGRESS_REQ

CPG

None

CALL_PROGRESS_IND

CPG

None

CHARGING_REQ

CHG

None

CHARGING_IND

CHG

None

CHARGING_UNIT_ACK

TXA

None

CHARGING_UNIT_CONF

TXA

None

CHARGING_UNIT_REQ

ITX

None

CHARGING_UNIT_IND

ITX

None

CIRCUIT_RESERVATION_IND

CRM

None

CIRCUIT_RESERVATION_RESP

CRA

None

CONFUSION_IND

CFN

None

CONNECT_LOOP_IND

None

None

CONNECT_LOOP_IND_ACK

None

None

496

Comments

This is supported in TTC3


only.
This is supported in TTC3
only.
This is supported in Spr98
only.
This is supported in
Spr98only.
This is supported in Spr98
only.
This is supported in
Spr98only.

This primitive is used to


ask the application to
connect its tone loop
(Continuity-check
procedures).

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

CONNECT_TRANSCEIVER_IND

None

None

CONNECT_TRANSCEIVER_IND_ACK

None

None

CONTINUITY_RECHECK_REQ

CCR

None

CONTINUITY_RECHECK_IND

None

None

CONTINUITY_RECHECK_CONF

None

None

CONTINUITY_REPORT_REQ

COT

None

CONTINUITY_REPORT_IND

None

None

DISABLE_ECHO_IND

None

None

DISABLE_ECHO_IND_ACK

None

None

ENABLE_ECHO_IND

None

None

ENABLE_ECHO_IND_ACK

None

None

FACILITY_ACCEPT_REQ

FAA

None

FACILITY_ACCEPT_IND

FAA

None

FACILITY_REJECT_REQ

FRJ

None

FACILITY_REJECT_IND

FRJ

None

Chapter 13

Comments
This primitive is used to
ask the application to
connect its transceiver
(Continuity-check
procedures).
This is not supported in
TTC.

This primitive is used to


ask the application to
disable its echo suppressor
(Continuity-check
procedures).
This primitive is used to
ask the application to
enable its echo suppressor
(Continuity-check
procedures).
This is not supported in
TTC.
This is not supported in
TTC.

497

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

FACILITY_REQ

FAC

None

FACILITY_IND

FAC

None

FACILITY_REQUEST_REQ

FAR

None

FACILITY_REQUEST_IND

FAR

None

FORWARD_TRANSFER_IND

FOT

None

GROUP_BLOCKING_REQ

CGB

None

GROUP_BLOCKING_IND

CGB

None

GROUP_BLOCKING_RESP

None

None

GROUP_BLOCKING_CONF

CGBA

None

GROUP_QUERY_REQ

CQM

None

GROUP_QUERY_CONF

CQR

None

GROUP_QUERY_IND

CQM

None

GROUP_QUERY_RESP

CQR

None

GROUP_RESET_REQ

GRS

None

GROUP_RESET_IND

GRS

None

GROUP_RESET_RESP

GRA

None

GROUP_RESET_CONF

GRA

None

GROUP_STOP_REQ

None

None

GROUP_STOP_CONF

None

None

498

Comments
This is not supported in
ITU-88, and TTC.
This is not supported in
TTC.

This primitive is used by


the application to ask the
ISUP library to stop
re-transmitting
REL/RSC/CGB/GRS
messages concerning a
circuit group to the SS7
network.

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

GROUP_UNBLOCKING_REQ

CGU

None

GROUP_UNBLOCKING_IND

CGU

None

GROUP_UNBLOCKING_RESP

None

None

GROUP_UNBLOCKING_CONF

CGUA

None

HW_GROUP_BLOCKING_REQ

CGB

None

HW_GROUP_BLOCKING_IND

CGB

None

HW_GROUP_BLOCKING_RESP

None

None

HW_GROUP_BLOCKING_CONF

CGBA

None

HW_GROUP_UNBLOCKING_REQ

CGU

None

HW_GROUP_UNBLOCKING_IND

CGU

None

HW_GROUP_UNBLOCKING_RESP

None

None

HW_GROUP_UNBLOCKING_CONF

CGU

None

INFORMATION_IND

SAM

None

INFORMATION_REQ

SAM

None

ISUP_USR_MSG_REQ

USERDEF

None

ISUP_USR_MSG_IND

None

None

MAINTENANCE_SYSTEM_IND

None

Maintenance
System

Chapter 13

Comments

This is not supported in


TTC.
This primitive is used for
messages defined using
the customizing facility.
This primitive is used to
inform the maintenance
system of a particular
event. For more details,
see the AdditionalInfo
section.

499

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

NETWORK_RESOURCE_MGT_REQ

NRM

None

NETWORK_RESOURCE_MGT_IND

NRM

None

PASS_ALONG_REQ

PAM

None

PASS_ALONG_IND

PAM

None

PRE_REL_INFORMATION_REQ

PRI

None

PRE_REL_INFORMATION_IND

PRI

None

PROGRESS_REQ

PRG

None

PROGRESS_IND

PRG

None

RELEASE_REQ

REL

None

RELEASE_IND

REL

None

RELEASE_RESP

RLC

None

RELEASE_CONF

RLC

None

REMOVE_LOOP_IND

None

None

REMOVE_LOOP_IND_ACK

None

None

500

Comments
This primitive is used to
send/receive the NRM
message used in echo
control procedures. This is
supported in ITU-T 93/97,
SSUR, and Spr98 only.
This primitive is used to
send/receive any ISUP
message that is already
encoded as part of a PAM
(Pass Along Message).
This is not supported in
TTC.
This is supported in Spr98
only.
This is supported in
Spr98only.
This is supported in TTC3
only.
This is supported in TTC3
only.

This primitive is used to


ask the application to
remove its tone loop
(Continuity-check
procedures).

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

REMOVE_TRANSCEIVER_IND

None

None

REMOVE_TRANSCEIVER_IND_ACK

None

None

RESET_REQ

RSC

None

RESET_IND

RSC

Reset

RESET_RESP

RLC

Reset

RESET_CONF

RLC

None

RESUME_IND

RES

None

RESUME_REQ

RES

None

SETUP_FAILURE_IND

None

None

SETUP_REQ

IAM

Setup

SETUP_IND

IAM

None

SETUP_IND_ACK

None

Setup

SETUP_RESP

CON or ANM

None

SETUP_CONF

CON or ANM

None

SOFTRESET_REQ

None

None

Chapter 13

Comments
This primitive is used to
ask the application to
remove its transceiver
(Continuity-check
procedures).

Either an RLC message or


a Reset (AdditionalInfo),
but not both.

This primitive is used to


inform the application that
the current call setup has
failed. For more
information, see the
AdditionalInfo
section.

501

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

SOLICITED_INFO_REQ

INR

None

SOLICITED_INFO_IND

INR

None

SOLICITED_INFO_RESP

INF

None

SOLICITED_INFO_CONF

INF

None

UNSOLICITED_INFO_REQ

INF

None

UNSOLICITED_INFO_IND

INF

None

START_CHECK_TONE_IND

None

None

START_CHECK_TONE_IND_ACK

None

None

START_RELEASE_IND

None

StartRelease

START_RELEASE_IND_ACK

None

None

START_RESET_IND

None

StartReset
LocalReset

START_RESET_IND_ACK

None

None

STOP_CHECK_TONE_IND

None

None

STOP_CHECK_TONE_IND_ACK

None

None

502

Comments
This is not supported in
TTC.

This primitive is used to


ask the application to start
checking the backward
tone (Continuity-check
procedures).
This primitive is used to
inform the application that
the current call is being
released. For more
information, see the
AdditionalInfo
section.
This primitive is used to
inform the application that
the associated circuit is
being reset. For more
information, see the
AdditionalInfo
section.
This primitive is used to
ask the application to stop
checking the backward
tone (Continuity-check
procedures).

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-2

ISUP Primitives State Machine Mode - ITU Based Flavors (Continued)

HP OpenCall SS7 ISUP Primitive

ISUP
Message

Additional Info

STOP_REQ

None

None

STOP_CONF

None

None

SUSPEND_IND

SUS

SUSPEND_REQ

SUS

Suspend
-Resume

Comments
This primitive is used by
the application to ask the
ISUP library to stop
re-transmitting REL/RSC
messages about a circuit to
the SS7 network.

Suspend
-Resume
TONE_DISAPPEARS_ACK

None

None

UNBLOCKING_REQ

UBL

None

UNBLOCKING_RESP

UBL

None

UNBLOCKING_IND

UBA

None

UNBLOCKING_CONF

UBA

None

UNEQUIPPED_CIRCUIT_IND

UCIC

None

UNKNOWN_MESSAGE_REQ

Message
with
unknown
ISUP type.

None

UNKNOWN_MESSAGE_IND

Chapter 13

This primitive is used by


the application to signal
the backward tone has
disappeared.

This primitive is used to


send/receive an ISUP
message of unknown
message type, with all
parameters being encoded
as OPTIONAL and a
MessageCompatibilit
yInformation
parameter indicating
PassOn. This is
supported in only ITU-T
93/97, SSUR, and Spr98.

503

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives

Bypass Mode
ISUP BP Primitives

Table 13-3 lists the ISUP primitives for Bypass Mode.

Table 13-3

ISUP Protocol Bypass Mode


Primitive

Event

INVALID_ISUP_MSG_IND

Indicate that a message from a known DPC could not be


decoded, and hence was destroyed.

ISUP_MSG_REQ
ISUP_MSG_IND

Send/receive any previously encoded ISUP message, except for


PAMs (Pass Along Messages).

PASS_ALONG_REQ
PASS_ALONG_IND
(not available for TTC)

Send/receive any previously encoded ISUP message as part of a


pass-along message.

UNKNOWN_MSG_REQ
UNKNOWN_MSG_IND

Send/receive any previously encoded ISUP message, except for


PAMs (Pass Along Messages).

UNKNOWN_OPC_MSG_IND

Indicate that a remote Point Code was not configured.

Additional Information
Additional information is required for some of the HP OpenCall SS7 ISUP
primitives. Therefore information elements are attached to these primitives. These
information elements aid the application in determining the reason why a protocol
event occurred, such as the information included in the SETUP_FAILURE_IND
primitive.
The details of how these information elements are handled vary depending on the
primitive in use, however, the general pattern for handling them is the same:
Step

1. Read the type of the additionalInfo using the getInfoType() method.

Step

2. Cast into the corresponding class. For a list of primitives that require, Additional
Information, see Table 13-4, Primitives Requiring Additional Information..

Step

3. Read the information using the appropriate accessors.


For details about the additional information values, see Appendix A, ISUP Library
Values.

504

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
See also Table 12-2, ISUP Receive Notifications, on page 469.
Table 13-4
Primitives

Primitives Requiring Additional Information


Additional
Information

Field

Used for:

SETUP_REQ

Setup

acmControlFlag

determining whether or not ACM control is


applied

SETUP_IND_ACK

Setup

N/A

determining whether or not ACM control is


applied

SETUP_FAILURE_IND

SetupFailure

setupFailureCause

determining the reason for failure.


Possible values are:
UNSPECIFIED
DUAL_SEIZURE
FLOW_CONTROL
BLOCKING
COT_FAILURE
RELEASE
T27_TIMEOUT
CPC_BUSY
CRCR_RESET

SUSPEND_IND
SUSPEND_REQ

SuspendResume

origin

defining the origin of a reset.


Possible values are:
FROM_NETWORK
FROM_USER

START_RELEASE_IND

StartRelease

releaseCause

determining the reason for the release.


Possible values are:
UNEXPECTED_RLC
T7_TIMEOUT
T33_TIMEOUT
T_CRA_TIMEOUT
BLOCKING
RELEASE_REQUEST
T8_TIMEOUT
T1_TIMEOUT
DCO_SUCCESS
STOP_REQ
T9_TIMEOUT
CONTINUITY_SUCCESS
BACKWARD_CHECK_TONE_ACK
T6_TIMEOUT
T2_TIMEOUT

Chapter 13

505

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-4
Primitives
START_RESET_IND

Primitives Requiring Additional Information (Continued)


Additional
Information
StartReset
LocalReset

Field
resetCause

Used for:
determining the reason for the reset.
Possible values for StartReset are:
NO_REASON
UNEXPECTED_MESSAGE
T5_TIMEOUT
BLOCKING_WITH_RELEASE
COT_CC_NOT_REQUIRED
COT_FAILURE
TCCRr_TIMEOUT
T27_TIMEOUT
T34_TIMEOUT
DCO_LPA_FAIL
UNEQUIPPED_CIRCUIT
TIMER_SHORTAGE
Possible values for LocalReset are:
MTP_UNAVAILABLE
DPC_UNAVAILABLE
BLS_STOPPED
CRS_STOPPED
CQS_STOPPED
CRCR_STOPPED
GBUS_STOPPED
CGRS_STOPPED
MGBS_STOPPED
HGBS_STOPPED
CRCS_STOPPED
DCO_STOPPED

GROUP_QUERY_IND

CQM

GROUP_QUERY_RESP

CQM

RESET_IND

Reset

RESET_RESP

resetEvent

determining whether it is part of a Group Reset


operation.
Possible values are:
GROUP_RESET

506

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives
Table 13-4

Primitives Requiring Additional Information (Continued)

Primitives

Additional
Information

MAINTENANCE_SYSTEM_I
ND

MaintenanceSy
stem

Field
maintenance
SystemEvent

Used for:
defining the reason for the reset, possible values
are:
T5_TIMEOUT
T17_TIMEOUT
RSC_AFTER_T17
RLC_AFTER_T17
CRS_STOP
MN_BLOCKING
HW_BLOCKING
MN_UNBLOCKING
HW_UNBLOCKING
MN_GROUP_BLOCKING
HW_GROUP_BLOCKING
MN_GROUP_UNBLOCKING
HW_GROUP_UNBLOCKING
T12_NOT_RUNNING
T13_TIMEOUT
T14_NOT_RUNNING
T15_TIMEOUT
T22_NOT_RUNNING
T19_TIMEOUT
T21_TIMEOUT
T23_TIMEOUT
T18_NOT_RUNNING
PRIORITY_TO_GROUP_RESET
T20_NOT_RUNNING
WRONG_STATUS_BITS
UCIC_STOP
COT_RECEIVED
DCO_FAIL
DCO_SUCCESS
STOP_REQ
REL_RECEIVED
T24_TIMEOUT
BACKWARD_CHECK_TONE_ACK
T28_TIMEOUT
T34_TIMEOUT
UNEQUIPPED_CIRCUIT
TIMER_SHORTAGE
RECV_ON_UNEQUIPPED_CIRCUIT
BLA_WHEN_IDLE
UBA_WHEN_LOCALLY_BLOCKED
NON_ISDN_ACCESS_INDICATION
CIRCUIT_VALIDATION_TEST_FAILED

Chapter 13

507

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Primitives

MTP Related Primitives


HP OpenCall SS7 ISUP forwards MTP related primitives to the application
indicating the current status of MTP Level 3. These primitives inform the
application whether it is possible to transfer information via MTP. These primitives
are forwarded to all probe objects.
Table 13-5

MTP Related Primitives


Primitive

508

Event

MTP_PAUSE_IND

Pause indication for a Destination Point Code

MTP_RESUME_IND

Resume indication for a Destination Point Code

MTP_DPC_CONGESTED_IND

Destination Point Code is congested

MTP_DPC_UNCONGESTED_IND

Destination Point Code is not congested

MTP_AVAILABLE_IND

Local MTP is available for message transfer

MTP_UNAVAILABLE_IND

Local MTP is unavailable for message transfer

MTP_CONGESTED_IND

Local MTP is congested

MTP_UNCONGESTED_IND

End of local MTP congestion

MTP_RESTARTING_IND

Local MTP is restarting

MTP_UPU_UNAVAILABLE_IND

Remote user part is unavailable

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Supported Messages

HP OpenCall SS7 ISUP Supported Messages


ISUP messages defined by ANSI and ITU-T standards are, by default, supported by
the HP OpenCall SS7 ISUP API. They are represented as a set of C++ object classes
derived from a base class, IsupMsg.

Message Classes
Each message has a defined object class, known as a message class. These message
classes provide specific interfaces to build and access the parameters found in each
message, while remaining abstract from their HP OpenCall SS7 ISUP internal
structure. Figure 13-2, Message Class Relationships illustrates their relationship to
each other, and to the IsupMgr class.

Chapter 13

509

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Supported Messages

Figure 13-2

Message Class Relationships1

Message Class for Customized Messages


Messages that deviate from the standard messages, such as operator-specific
messages containing non-standard structure or parameters, are manipulated by a
special message class, IsupUserMsg.

1. See Figure 12-4, Object Model


510

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Supported Messages

Metadata
The internal structure of an ISUP message is contained in the
HP OpenCall SS7 ISUP metadata. The metadata governs the behavior of message
classes when manipulated by the application, and also directs the
HP OpenCall SS7 ISUP encoder/decoder mechanism.
Standard Metadata
As the standard metadata is provided per software version (ANSI or ITU-T), it
contains the internal structure of the messages defined by the corresponding
recommendations.
Hence, the standard metadata provided for an ANSI version of the
HP OpenCall SS7 ISUP library does not contain the internal structure of any ITU-T
specific messages.

Chapter 13

511

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Supported Messages
Figure 13-3

Message Class/Metadata Relationship

Encoder/Decoder
HP OpenCall SS7 ISUP message encoding and decoding is performed by the
generic table-driven HP OpenCall SS7 ISUP Encoder/Decoder, and is coordinated
by the metadata. The encoder/decoder ignores any optional parameters which have
not been included in the metadata.

512

Chapter 13

Exchanging ISUP Messages


HP OpenCall SS7 ISUP Supported Messages

Tracing
IsupMgr defines two methods to explicitly trace the encoding and decoding of
exchanged messages.

Table 13-6
Type

Tracing Methods
Method

Arguments

void

setTraceOn

();

void

setTraceOff

();

You can also use the HP OpenCall SS7 configuration files to trace the application
process.

Chapter 13

513

Exchanging ISUP Messages


Loading a Set of Messages

Loading a Set of Messages


When the IsupMgr object is initialized with the IsupMgr::init method,
HP OpenCall SS7 ISUP configuration file is automatically loaded. This file
contains all the LPC, DPC and circuit information required for the
HP OpenCall SS7 ISUP library.
Each LPC and DPC pair has an associated set of messages. The MessageSetName
field in the configuration file identifies the messages that will be exchanged between
the particular SS7 stack and DPC.

Identifying a Set of Messages


When a set of messages is loaded by IsupMgr::init(), it is given a specific
identifier that must be used in the subsequent manipulation of messages belonging
to the set of messages.
IsupMgr provides the application with a method to find out which set of messages is
associated with a particular DPC, IsupMgr::whichMsgSet(). This method uses
the SS7 stack classname and the DPC to return the message set identifier,
msgSetId.
For details about the syntax, parameters, and return values of
IsupMgr::whichMsgSet(), see the IsupMgr(3) man page.
Example 13-1
ISUP::MsgSetID
ISUP::PointCode
ISUP::InfoStatus
ISUP::InfoStatus
IsupMgr*

Identifying a Set of Messages.


msgSetId;
dpc;
selectStatus_A;
identifyMsgSetStatus;
isupMgr;

// initialize DPC
// select set of messages using classname and DPC
selectStatus_A= isupMgr->whichMsgSet (SS7_Stack, dpc, msgSetId);
if (! selectStatus.isOk()){
// error recovery
}
// msgSetId is subsequently used to identify the messages exchanged with
// the specified DPC

514

Chapter 13

Exchanging ISUP Messages


Creating Messages

Creating Messages
To manipulate and send a message, the application must first create an instance of
the message. This is done using the constructor associated with the message.
Because a message belongs to a specific set of messages, identified by msgSetId,
its internal structure is dependent on the metadata defined for msgSetId. Thus, to
create an initial instance of the required message, the application must specify the
appropriate msgSetId in the message constructor.
When a constructor is called by the application and the specified msgSetId is
supported by the HP OpenCall SS7 ISUP library, the resulting message contains
only the mandatory message parameters. Their values are initialized to zero.
Example 13-2

Creating a Message
ISUP::MsgSetID
ISUP::InfoStatus
IsupMgr*

msgSetId;
identifyMsgSetStatus;
isupMgr;

// initialize DPC
// Get message set identifier
identifyMsgSetStatus = isupMgr->whichMsgSet (ISUP,
msgSetId);
if (! identifyMsgSetStatus.isOk()){
// error recovery
}
// create an instance of IAM
IsupIam* iamMsg = new IsupIam(msgSetId);

Chapter 13

515

Exchanging ISUP Messages


ISUP Messages Supported

ISUP Messages Supported


In general, HP OpenCall SS7 ISUP supports all message types defined by the
standards that it supports.
All message types are associated with a C++ message class.
State machines implement sufficient functionality for call set-up and release,
including group operations

Complete List of Messages and Message Sets Supported


For a complete list of the message sets available with the HP OpenCall SS7 ISUP
library, please contact your HP representative.

Partial Support
Some messages are not sent by the ISUP application but are sent indirectly by the
ISUP library. Some messages are not supported at all. Some messages are just
supported on reception mode.
Table 13-7, Messages Partially Supported by ISUP, lists ISUP messages that are
currently partially supported by the ISUP library.
Table 13-7

Messages Partially Supported by ISUP


How Implemented

Messages sent indirectly by the ISUP library.

ANSI Messages
CFN, COT, LPA, UCIC

Messages not supported.

ITU Messages
CFN, COT, LPA, UCIC
CMC, CMR, CMRJ, CRG,
DRS, EXM, OLM, USR,
LOP, UPT, UPA

Automatic response sent by the ISUP library.

CQR

CQR

Only reception implemented.

CRM, FOT

FOT, SGM

516

Chapter 13

Exchanging ISUP Messages


Accessors

Accessors
The parameter values of a message class instance, such as an instance of IsupIam,
are accessible via special message methods called accessors. There are two groups
of accessor: generic and specific.

Specific Accessors
All the parameter values contained in HP OpenCall SS7 ISUP Supported Messages
are accessible through parameter specific accessors. Each parameter has two
accessors, a read and a write accessor.
Optional parameters have two additional accessors:

the presence accessor, to indicate the presence of a specified optional


parameter,

the absence accessor, to force an optional parameter to be treated as absent


(whether it is in fact present or not).

When you write a value into an optional parameter, its presence indicator is
automatically set. Before applying a read accessor to an optional parameter, you
must examine the presence indicator to ascertain if the parameter is present in the
message.
The absence accessor forces an optional parameter to be treated as absent (whether
it is in fact present or not). This lets you reuse part of a message without creating a
new one and copying the parameters required by the application.

Accessor Behavior
The behavior of an accessor depends on the message or parameter that you want to
access and on the metadata.

Table 13-8
Type
ISUP::ParmValue

Chapter 13

Specific Accessors
Accessor
accessorNamea(read accessor)

Arguments
(ISUP::MsgStatus& status) const;

517

Exchanging ISUP Messages


Accessors
Table 13-8

Specific Accessors (Continued)

Type

Accessor

Arguments

IsupXXXb*

accessorNamea
(write accessor)

(ISUP::ParmValue& val,
ISUP::MsgStatus& status);

void

<parameterShortName>SetAbsent
(absence accessor)

(ISUP::MsgStatus& P_status);

HPAIN::Boolean

accessorNameaIsPresent
(presence accessor)

(ISUP::MsgStatus& status) const;

a. accessorName denotes the parameter name as listed in Supported Parameters List on


page 533.
b. IsupXXX denotes a specific message class as listed in Supported Parameters List on
page 533.

Accessing Data Part of an IsupMsg Object


Two methods are available to access the transfer representation (data part) of an
IsupMsg object:

IsupMsg::getPDU()

IsupMsg::setPDU()

These two methods are in the public area of the IsupMsg class.
IsupMsg::getPDU()

This method has the following signature:


IsupMsg::getPDU(void *PDU,HPAIN::Unit32
*P_length,ISUP::MsgStatus& P_status)

It returns the data read in the transfer representation of the message in the *PDU
buffer, and updates the P_length parameter accordingly.
The status returned is one of the following:
ISUP::MsgStatus::NO_ERROR is returned in case of correct behavior.
ISUP::MsgStatus::READ_ERROR is returned if:

518

the transfer representation does not exist.

Chapter 13

Exchanging ISUP Messages


Accessors

an error occurred when reading the transfer representation.

ISUP::MsgStatus::INVALID_LENGTH, if the given length parameter is not


large enough to allow copy of the transfer representation.
IsupMsg::setPDU()

This method has the following signature:


IsupMsg::setPDU(const void *P_PDU, HPAIN::Uint32 P_length,
ISUP::MsgStatus& P_status)

It sets the transfer representation of the IsupMsg object with the data found in the
buffer pointed to by the P_PDU parameter. The write operation is done starting from
the message type to the last parameter of the ISUP message.
Errors that are returned when using this method are the following:
ISUP::MsgStatus::NO_MORE_MEMORY, if the network representation cannot be
created.
ISUP::MsgStatus::WRITE_ERROR, if the write operation cannot be performed:

*P_length is null,

*P_PDU is null,

*the transfer representation already exists.

ISUP::MsgStatus::INVALID_TAG, if the type of the IsupMsg object used is


different from the message type read in the first byte of the PDU.

Chapter 13

519

Exchanging ISUP Messages


Assigning Values

Assigning Values
When a message is created via its message constructor, its mandatory parameters are
initialized with zeros. Naturally, you must assign values to these parameters and if
necessary, extend the message by including some of its optional parameters.
HP OpenCall SS7 ISUP provides a base classISUP::ParmValue for
encapsulating parameter values. This object class provides methods for assigning
values of differing lengths (32, 16 and 8 bits).
Table 13-9

Methods for Assigning Values

Type

Method

Arguments

ParmValue&

assign

(const char* s, HPAIN::Uint32 l);

ParmValue&

assign

(const void* s, HPAIN::Uint32 l);

ParmValue&

assign

(HPAIN::Uint32 i);

ParmValue&

assign

(HPAIN::Uint16 i);

ParmValue&

assign

(HPAIN::Byte b);

Example 13-3

Assigning Parameter Values

IsupIam* prepareIamMsg()
{
ISUP::ParmValue* value = new ISUP::ParmValue ();
ISUP::MsgStatus status;
// evaluate msgSetId
IsupIam* iamMsg = new IsupIam(msgSetId);
if (!iamMsg->isObjectValid(status)) {
delete value;
delete iamMsg;
return NULL;
}
iamMsg->natureOfCnxIndicators(value->assign (\x66, 1), status);
if (!status.isOk()) {
// error recovery
}
iamMsg->forwardCallIndicators(value->assign (\x33\x58, 2), status);
if (!status.isOk()){
// error recovery

520

Chapter 13

Exchanging ISUP Messages


Assigning Values
}
iamMsg->callingPartysCategory(value->assign (\x53, 1), status);
if (!status.isOk()){
// error recovery
}
iamMsg->userServiceInformation(value->assign (\x53\x33, 2), status);
if (!status.isOk()){
// error recovery
}
iamMsg->calledPartyNumber(value->assign (\x53\x33\x76\x68, 4), status);
if (!status.isOk()){
// error recovery
}
delete value;
return iamMsg;
}

Chapter 13

521

Exchanging ISUP Messages


Sending Messages

Sending Messages
After creating a message and setting its parameters, any of the active probe objects
can request the API to send the message to the network. Figure 13-4, Probe/Message
Relationship illustrates the overall relationship of messages, probe objects and
IsupMgr object.

522

Chapter 13

Exchanging ISUP Messages


Sending Messages

Figure 13-4

Chapter 13

Probe/Message Relationship1

523

Exchanging ISUP Messages


Sending Messages
Both IsupSMProbe and IsupBPProbe have defined send() methods, and as
described in Exchanging Primitives on page 485, there is an association between
the primitives and messages sent via this method.
If the call to IsupSMProbe::send() or IsupBPProbe::send() has been
successful, the API automatically deletes the message. Otherwise, it remains present
for further manipulation.
For details about the syntax, parameters, and return values of
IsupSMProbe::send() and IsupBPProbe::send(), see the
IsupSMProbe(3) and IsupBPProbe(3) man pages.

Queued Messages
When the application sends a message, it is placed by the API into an outbound
queue. The HP OpenCall SS7 ISUP library then attempts to send these queued
messages to the network. If this action succeeds, the queue is emptied.
Unsent messages are stored in the queue until they can be sent to the network.
Messages that cannot be sent to the MTP3 Level3 due to communication channel
congestion are kept in the outbound queue. If the capacity of the outbound queue
overflows, unsent messages are discarded without notifying the application.
This is part of the flow control mechanism performed by HP OpenCall SS7 ISUP,
and is described in IPC Flow Control on page 543.
Example 13-4

Sending a Message via an IsupSMProbe Object

ISUP::SendStatus
IsupSMProbe *
ISUP::Address

sendStatus;
isupSMProbe;
address;

// initialize address
if (!sendStatus.isOk()){
cout << Warning: send failed- error = sendStatus <<\n << flush;
// error recovery
}

1. See Figure 12-4, Object Model


524

Chapter 13

Exchanging ISUP Messages


Receiving Messages

Receiving Messages
Both probe classes provide a method to receive primitives and their associated
messages, receive(). This method must be used in association with the activity
object mechanism as described in Using the Activity Object on page 462.
For details about the syntax, parameters, and return values of
IsupSMProbe::receive() and IsupBPProbe::receive(), see the
IsupSMProbe(3) and IsupBPProbe(3) man pages.

Casting Messages
Both IsupSMProbe::receive() and IsupSMProbe::receive() return an
instance of the base message class, IsupMsg. To exactly identify which type of
message has been received, you must use the IsupMsg::getMsgType() method.
From the message type indicator returned by IsupMsg::getMsgType(), you
must select the appropriate cast method. Each message class has its own safe casting
method, which creates an instance of the message class from the contents of the
received message.
Unlike the send() methods, you must delete the received message when the
receive()call has been successful and you have finished processing its contents
using the accessors.
Table 13-10
Type

Casting Methods
Method

Arguments

static IsupXXXa

castMsg

(const IsupMsg* msg) const;

IsupMsg::Type

getMsgType

();

a. IsupXXX denotes a specific message class listed in Supported


Parameters List on page 533.

Chapter 13

525

Exchanging ISUP Messages


Receiving Messages
Example 13-5

Receiving a Message from an IsupSMProbe Object

ISUP::RecvStatus
ISUP::MsgStatus
IsupSMProbe *
IsupSMProbe::PrimitiveType
ISUP::Address
IsupMsg
IsupMsg::Type
ISUPAdditional:: Info *
ISUP::Parmvalue*
int

recvStatus;
status;
isupSMProbe;
primitive;
address;
*isupMsg, *acmMsg;
msgType;
info;
value;
nbIndication;

do {
// receive message via isupSMProbe object
recvStatus = isupSMProbe->receive(primitive,address, isupMsg, info, nbIndication);
if (!recvStatus.isOk()){
cout << receive failed- error= << recvStatus << \n << flush;
// error recovery
}
// check if error message received
if (isupMsg==NULL)
cout <<Warning: empty message received << \n << flush;
// check message type
msgType= isup->getMsgType();
// process message contents
if (msgType == IsupMsg::ACM){IsupAcm* acmMsg = IsupAcm::castMsg(msgType);
// process contents
// delete contents
}
} while (nbIndication >0);

Queued Indications
It is the responsibility of the application to repeatedly call receive() to retrieve
all the received indications (nbIndication) as soon as possible.
See IPC Flow Control on page 543.

526

Chapter 13

Exchanging ISUP Messages


Automated Call Release

Automated Call Release


HP OpenCall SS7 ISUP provides a means of automatically releasing a call on
request from the application. This helps the programmer by reducing the number of
exchanges with the ISUP API.
The decision to release a circuit is the responsibility of the application.
HP OpenCall SS7 ISUP handles all new message exchange on this circuit by
implementing a state machine to process all the incoming messages related to the
circuit being released.
Figure 13-5

Chapter 13

Successful Automated Call Release

527

Exchanging ISUP Messages


Automated Call Release
Figure 13-6

Unsuccessful Automated Call Release, Followed by Reset, and Local Reset


(STOP)

When started, the state machine initiates a release by sending a REL message. If no
RLC is arrived before T5 expires, HP OpenCall SS7 ISUP continues by initiating a
RESET procedure (sends a RSC). If no RLC is received before T17 times out,
HP OpenCall SS7 ISUP just locally resets the circuit (same as a STOP REQ
procedure) and returns to idle. The circuit is now available for future call attempts.
The application can release a circuit using the releaseCircuit() method (part
of the IsupSMProbe class). For details about releaseCircuit(), see the
IsupSMProbe(3) man page.
The application can get the number of circuits configured, using the
getNumberofCircuit()method (in the IsupMgr Object). For details about
getNumberofCircuit(), see the IsupMgr(3) man page.

528

Chapter 13

Exchanging ISUP Messages


Automated Call Release

Configuring for Automated Call Release


To use automatic call release with HP OpenCall SS7 ISUP, one cause value must be
configured per DPC in the isup.conf file.
The following example shows the line in the DPC section of the ISUP.conf file
with the release cause value (in hexadecimal) configured for automatic release.
[Isup_Dpc_NAME]
LPC=2
DPC=1
MessageSetName=IA92sep
ReleaseCauseValue=0xCAA9
circuit=0, reserved=NO
circuit=1, reserved=INCOMING
circuit=2, reserved=OUTGOING
...

Chapter 13

529

Exchanging ISUP Messages


Return Status Values

Return Status Values


Like all HP OpenCall SS7 ISUP methods, status values are returned after a method
has been completed for a message. It returns the success or failure of a method, and
in the latter case, the reason for the failure.
For a description of these status values, see the IsupMgr(3) man page.
The IsupMgr object manages all the status information regarding messages and
their manipulation. This includes information relating to the metadata.

530

Chapter 13

Exchanging ISUP Messages


Supported Parameters List

Supported Parameters List


This section covers the supported parameters for the ANSI and ITU-T based
versions of the product.
In general:

All parameters listed in supplied recommendations are supported by


HP OpenCall SS7 ISUP.

Attempts to access parameters of one standard, with metadata defined by the


other standard fail (with an IsupMsg::INVALID_PARM error) unless the
parameters are also supported version of ISUP in use.

Attempts to create a message for a standard, using a metadata of another


standard not supporting this message, fail with an
IsupMsg::INVALID_MESSAGE error.

No customer-specific parameters are supported in the provided message


classes. Such parameters are managed by applications using the installation
mechanism, that is part of the Message Customization Package.

Where a message parameter is specified as Mandatory by one standard and


Optional in another, the parameter appears as Optional in the C++ message
class. When used with the standard metadata where the parameter is mandatory,
the isPresent() method associated with the parameter fails with an
IsupMsg::NOT_OPTIONAL error.1

Where a message parameter is specified as Mandatory in one standard and is


not present in another, the parameter appears as Mandatory in the C++ message
class. When used with the standard metadata where the parameter is not
specified, the read and write parameter value accessor methods fail with an
IsupMsg::INVALID_PARM error.

1. Only applies for the IAM UserServiceInformation parameter, which


is a mandatory variable for ANSI-95 and an optional variable for ITUT-88.
Chapter 13

531

Exchanging ISUP Messages


Supported Parameters List

532

Chapter 13

Exchanging ISUP Messages


Supported Parameters List

Chapter 13

533

Exchanging ISUP Messages


Supported Parameters List

534

Chapter 13

14

Managing HP OpenCall SS7 ISUP


This chapter provides management guidelines for use in developing an ISUP
application.

Chapter 14

535

Managing HP OpenCall SS7 ISUP


Overview

Overview
The HP OpenCall SS7 ISUP API provides the application with objects and methods
to connect to and exchange primitives and messages with the SS7 stack.
Incorporate the HP OpenCall SS7 ISUP management guidelines described in this
chapter into the application.
If you are developing a High Availability application, you must use the circuit
update mechanism provided by HP OpenCall SS7 ISUP.

536

Chapter 14

Managing HP OpenCall SS7 ISUP


Managing Race Conditions

Managing Race Conditions


When numerous network events rapidly occur, a race condition may occur if the
application does not call receive() as soon as the internal call state changes.
In such circumstances, the HP OpenCall SS7 ISUP API returns the status value
WRONG_STATE if the application calls send(). The application must ignore this
unexpected return status value and receive the waiting indications from the API.
Following this, the application will then re-synchronize with the
HP OpenCall SS7 ISUP state-machines.

Chapter 14

537

Managing HP OpenCall SS7 ISUP


Managing Memory Space

Managing Memory Space


Control of the memory used by HP OpenCall SS7 ISUP is dependent on the
applications memory management. Thus, it is your responsibility to ensure that
there is not a shortage of memory space for the HP OpenCall SS7 ISUP API objects.
When every object is instantiated, it must be checked. A Return Status value of
NO_MORE_MEMORY is returned if the allocation of memory for a specific object has
failed. You are responsible for coping with this situation, and if there is no space
available, you must delete all the created objects and close all the probe objects, thus
allowing the SS7 stack to release the MTP3 connection.
Conversely, if you redefine the global new(), HP OpenCall SS7 ISUP will use it
and any mechanism using this new().

538

Chapter 14

Managing HP OpenCall SS7 ISUP


Managing Object Memory

Managing Object Memory


Since the application manipulates objects via the HP OpenCall SS7 ISUP API, you
must be aware of certain rules for managing these objects whether they are ISUP
messages, Return Status values or parameter values.

Messages
When you have created messages and assigned values to the particular parameters,
you must explicitly call the send() method. If the call succeeds, then the API frees
the memory used by the sent message. If the call to send() fails, the message is
returned to the application for further investigation.
On receiving a message from the SS7 stack, the API creates a message object for the
application via the receive() method. This message object must be deleted by the
application when it has finished manipulating the message. The message object can
also be returned to the API via a subsequent call to send().

Parameter Values
As illustrated in Accessors on page 519, you are recommended to create
parameter value objects using the ISUP::ParmValue object. These objects are
used by the appropriate write accessor to set the parameter.
To get a parameter value using a read accessor, the API creates the parameter value
objects.
In both cases, it is your responsibility to delete all parameter value objects.

Additional Information
Some primitives sent from the HP OpenCall SS7 ISUP library to the application
contain additional information objects (see Additional Information on page 505).
These objects are automatically created by the API.
If the application sends any primitives containing additional information, the API
automatically deletes these objects when the call to send() is successful.
In the case send() fails, the additional information objects are returned to the
application for further investigation. These objects must be deleted by the
application or returned to the API in a subsequent send().

Chapter 14

539

Managing HP OpenCall SS7 ISUP


Managing Object Memory

Return Status Values


Check the Return Status value for each method, as described in Exception
Handling on page 434. The creation and deletion of these return status objects is
your responsibility: the API only assigns values to these objects.

540

Chapter 14

Managing HP OpenCall SS7 ISUP


Handling IPC Buffers

Handling IPC Buffers


IPC buffers are used by HP OpenCall SS7 ISUP to communicate with the SS7
stack.
All the messages that you send or receive are stored in the internal buffers. You can
decide whether messages are buffered before being sent or whether they are
automatically flushed to the network each time you call IsupSMProbe::send()
or IsupBPProbe::send().
By default, HP OpenCall SS7 ISUP is set to non-buffering mode, thus flushing the
internal buffers each time send() is called.
Figure 14-1

Internal Buffers

NOTE

When an IPC send buffer is full, it is automatically flushed.

Chapter 14

541

Managing HP OpenCall SS7 ISUP


Handling IPC Buffers

Modifying IPC Buffers


Usually, IPC Configuration is not required because HP OpenCall SS7 ISUP
provides the application with default buffers for communication between the
application and the SS7 stack.
You may have to modify the attributes of these default buffers in order to optimize
performance, thus reducing the number of system calls. The following IsupProbe
methods available for modifying buffer characteristics:

setIPCSendSize

setIPCRecvSize

setLowTransitTime

setHighTransitTime

setBufferingMode

setNonBufferingMode

flush

flushConditional

For more details, see the IsupProbe(3) man page.

542

Chapter 14

Managing HP OpenCall SS7 ISUP


IPC Flow Control

IPC Flow Control


The HP OpenCall SS7 ISUP library provides both inbound and outbound flow
control via back-pressure. Inbound flow control is necessary when the application
cannot read all the pending message indications found in HP OpenCall SS7 ISUPs
inbound queue. On the outbound path, flow control becomes necessary when the
application requests are blocked at the MTP3 interface.
Figure 14-2

Chapter 14

Back-pressure and Paths

543

Managing HP OpenCall SS7 ISUP


IPC Flow Control

Inbound Path
The application receives single primitives from the HP OpenCall SS7 ISUP API,
even if multiple primitives have been generated after the occurrence of a protocol
event. A protocol event could be a primitive received from either the application or
the network, or simply a timeout.
Primitives waiting to be received by the application are maintained by
HP OpenCall SS7 ISUP in an inbound queue.
Waiting Indications
With each IsupSMProbe::receive()and IsupBPProbe::receive(), the
number of indications waiting to be received is also passed, see Receiving
Messages on page 527. It is your responsibility to repeatedly call receive() until
all the waiting indications have been received.
Network Back-pressure
While there are still indications waiting to be received by the application, MTP3 will
not perform a MTPL3recv() on behalf of HP OpenCall SS7 ISUP.
If the application does not receive all the pending primitives as soon as possible, the
back pressure HP OpenCall SS7 ISUP forces on the network will cause the SS7
stack to delete all new messages that it cannot send to HP OpenCall SS7 ISUP
within a certain period of time.

Outbound Path
When a protocol event occurs, HP OpenCall SS7 ISUP state-machines may
generate one or more ISUP messages destined for the network. The generated
messages are placed in an outbound queue by the processing state-machines.
Once the state-machines have completed their processing, HP OpenCall SS7 ISUP
attempts to send all the messages in the queue to the network.
Remaining Messages
If HP OpenCall SS7 ISUP is successful in sending all the messages, the queue is
empty. Otherwise, it contains the messages that it could not send.
Application Back-pressure
The number of remaining messages in the queue is used by HP OpenCall SS7 ISUP
to accept or reject the service primitives that the application issues.

544

Chapter 14

Managing HP OpenCall SS7 ISUP


IPC Flow Control
When the application issues a send(), HP OpenCall SS7 ISUP determines whether
the queue is empty or not. If it is not empty, then the send() fails with the Return
Status value IPC_SEND_FULL.
However terminating primitives can be sent from the application to
HP OpenCall SS7 ISUP library when this IPC congested state occurs. These
primitives are:

START_RELEASE_IND_ACK

RELEASE_RESP

START_RESET_IND_ACK

RESET_RESP

STOP_REQ

When the congestion disappears, HP OpenCall SS7 ISUP immediately calls


sendPossible(), indicating to the application via the activity object mechanism
that it can restart sending messages.

Chapter 14

545

Managing HP OpenCall SS7 ISUP


Managing Circuit States

Managing Circuit States


For a High-Availability configuration, an application developer can decide to use a
switchover mechanism on the application-level. Currently HP OpenCall SS7 ISUP
provides you with methods to update and restore dynamic circuit state information
for circuits attached to an IsupSMProbe object. Applications can also store circuit
states in a database.
These methods, coupled with an appropriate state synchronization protocol between
the applications, ensure that a standby application starts up its operations with an
up-to-date representation of the active and idle circuits within the
HP OpenCall SS7 ISUP library when application switchover occurs.

Provided Methods
Two methods provided by IsupSMProbe let the active application retrieve and set
the state of the circuits managed by the standby HP OpenCall SS7 ISUP. They are
IsupSMProbe::setCircuitState ()and
IsupSMProbe::getCircuitState(). For details about the syntax, parameters,
and return values of these two methods, see the IsupSMProbe(3)man page.
However, the application is only allowed to manage the circuit state information
when the IsupSMProbe objects are closed or inactive.

NOTE

The getCircuitState() method returns the same state as CQR only if a call is
complete. If the IAM, ACM, ANM sequence has been completed successfully, then
getCircuitState() returns BUSY. Otherwise, getCircuitState()returns
IDLE.

How HP OpenCall SS7 ISUP Tracks Circuit State Values


The HP OpenCall SS7 ISUP API provides applications with the capability to
manage the state of circuits attached to a probe. This capability is intended to
highly-available Call Control applications, and is not provided in an OA&M
context.
Call Control Applications use ISUP for call set-up and release.

546

Chapter 14

Managing HP OpenCall SS7 ISUP


Managing Circuit States
Applications maintain active circuits during failover. Circuits can be supported by
an external switch matrix and their state is maintained/retrieved by the application
during application failover.
Applications manage the states of circuits within the HP OpenCall SS7 ISUP
subsystem attached to the standby application. This prevents all
HP OpenCall SS7 ISUP circuit states being set to IDLE when an application fails
over and ensures that these circuits will be maintained. Applications manage the
states of circuits in a real-time manner to limit the application fail-over time.
Applications can retrieve the state of circuits maintained by HP OpenCall SS7 ISUP
at any time. Applications synchronize the update of circuit states within the standby
application and the ISUP API from the current states of the active application and
the ISUP API. An application can not set the HP OpenCall SS7 ISUP circuit states
while HP OpenCall SS7 ISUP is active.
The differences between the ANSI and the ITU-T circuit state definition list below
come from the Hardware Oriented Blocking function which is not supported in
ANSI (HW:Hardware, MN:Maintenance).
For a list of the circuit state values visible and manageable by applications, see the
IsupIntro(3) man page.

Chapter 14

547

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism

Developing a Circuit Update Mechanism


NOTE

The active/standby model presented below is only one possible HA model. Other
models (using database accesses or audit mechanisms to recover circuit states) could
also be used.

The circuit methods let an application running over an active HP OpenCall SS7
stack update an application running over a standby stack, prior to granting
permission to proceed with a switchover. Using this mechanism prevents a circuit
from being found active by an application running over a standby stack, if it is in the
process of being deactivated by the application running over the active stack.
To make use of this mechanism, follow these guidelines when developing the
application:

All new states, or changes in circuit states, must be propagated by the


HP OpenCall SS7 ISUP library of the application running over the standby
stack.

All changes in circuit states must be synchronized with the


HP OpenCall SS7 ISUP library of the application running over the standby
stack.

If the application fails, a switchover to the HP OpenCall SS7 ISUP library of


the application running over the standby stack should be performed.

The failed application instance must update its circuit states.

Propagating States
When a request to set up a call has been successfully received or sent by the
application running over the active stack, the application should propagate the state
for that particular circuit to the application running over the standby stack.

548

Chapter 14

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism
Figure 14-3

Propagation

Synchronizing States
Any further modifications or resetting of the state for the particular circuit should
then be synchronized in the HP OpenCall SS7 ISUP library of the application
running over the standby stack, ensuring that the inactive library always contains the
correct circuit state information.

Chapter 14

549

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism
Figure 14-4

Synchronization

Activating the Standby Application


If a stack fails, or must be deactivated, application failover may be necessary. After
the library has been successfully activated, you must activate the necessary probe
objects. Then, the application can continue to successfully operate.

550

Chapter 14

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism
Figure 14-5

Activation

Recovering States
Meanwhile, the failed instance of the application can initiate its recovery or
updating mechanism, including the updating of all the circuit states as saved in the
active (previously standby) HP OpenCall SS7 ISUP library.

Chapter 14

551

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism
Figure 14-6

552

Recovery

Chapter 14

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism

Chapter 14

553

Managing HP OpenCall SS7 ISUP


Developing a Circuit Update Mechanism

554

Chapter 14

15

Introduction to ISUP Procedures


This chapter presents information about ISUP procedures, including FSMs,
interaction with the MTP layer and segmentation mechanisms.

Chapter 15

555

Introduction to ISUP Procedures


Supported Finite State Machines

Supported Finite State Machines


The table below identifies which of the HP OpenCall SS7 ISUP FSMs are
supported, whatever the selected flavor. It also shows the associated implementation
particularities or limitations, when applicable.
Table 15-1
Acronym

FSM Support
Implemented

Particularities/Limitations

Signaling Procedure Control


MSDC

Yes

MSDC

Yes

CPCI

Yes

CPCO

Yes

SCCP interactions not implemented

Circuit reservation is supported in CPCI only (incoming


CRM) for ANSI flavor. Charging is not implemented.
Alerting, Proceed, InBandInfo and Progress primitives are
combined in a single Address_Complete or Call_Progress
primitive. AMC Control not supported.
ACM Control not supported.
ITU-T 93, 97 and ETSI V2 only.

SSCI

Yes

SSCO

Yes

ITU-T 93, 97 and ETSI V2 only.

Circuit Supervision Control


BLR

Yes

BLR

Yes

CCI

Yes

CCO

Yes

CGRR

Yes

CGRS

Yes

CQR

Yes

CQS

Yes

556

ITU-T based version only

Chapter 15

Introduction to ISUP Procedures


Supported Finite State Machines
Table 15-1
Acronym

FSM Support (Continued)


Implemented

Particularities/Limitations

CRI

Yes

Not present in TTC

CRO

Yes

Not present in TTC

CRR

Yes

CRS

Yes

CVTR

Yes

ANSI only

CVTS

Yes

ANSI only

DCO

Yes

ANSI only

GNR

Yes

GBNR

Yes

GBUR

Yes

GBUS

Yes

See the Note below.

HGA

No

ANSI only

SCGA

No

ANSI only

UCIC

Yes

Not present in TTC

NOTE

In ANSI, if an unexpected CGBA or CGUA is received in any state, the


corresponding circuit state is set to IDLE. This is so even if the previous state was
Wait for CGUA or Wait for CGBA. It is recommended that the application
responds to only one of the two CGB/CGUs received.
This is due to the specifications described on sheet 3 of the state machine GBUS of
the ANSI ISUP library (ANSI T1.113-1995). The problem occurs when a CGBA
message is received in the "Wait for CGUA" state, and the CICs are locally
unblocked. Instead of going to "Wait for CGUA" as a result of the "Bits set?"
decision, the state machine goes to Idle, which is not the correct transition.

Chapter 15

557

Introduction to ISUP Procedures


Interaction Scenarios

Interaction Scenarios
Interaction scenarios are representative of the external behavior of
HP OpenCall SS7 ISUP as perceived by its environment.

Inbound and Outbound Circuits


Some of the following scenarios refer to an inbound circuit and an outbound circuit.
This reflects the fact that the main purpose of ISUP is to manage end-to-end
connections over one or several circuits. When contributing to the provision of an
end-to-end connection, a Call Control application which does not reside on a local
exchange typically must manage 2 circuits for the same call. This is shown below.
Figure 15-1

ISUP Managing Inbound and Outbound Circuits

As shown above, Transit Exchange A manages two circuits for the provision of an
end-to-end connection between the Calling Party and the Called Party. These are the
inbound and outbound circuits. In some cases, the interactions of the application
with HP OpenCall SS7 ISUP regarding the outbound circuit include the
communication of the results of some operations performed on the inbound circuit.
This is especially applicable for the Continuity Check procedure.

558

Chapter 15

Introduction to ISUP Procedures


MTP3 Interaction Handling

MTP3 Interaction Handling


Certain primitives are related to the Local Point Code (LPC) and Destination Point
Code (DPC) status at the MTP3 Level.
When an inhibiting primitive is received, the application cannot send a message.
The call will be locally refused with the appropriate return status value until the
associated uninhibiting primitive is received.

Local MPT-3 Status Indications


The following indications received from MTP3 are processed by
HP OpenCall SS7 ISUP:

MTP_available

MTP_unavailable

MTP_congested

MTP_uncongested

MTP_restarting

After processing, all received indications are delivered to the application as MTP3
primitives. See MTP Related Primitives on page 510 for information about these.
LPC States
HP OpenCall SS7 ISUP maintains an internal representation of the SS7 stacks it
connects to by the means of LPC objects. An LPC object can be in one of the
following states:

NOTE

Chapter 15

Initial

Probe_created

Probe_opened_and_active

With the primary/secondary functionality, probe_opened_and_active means


that the connection is primary (opened_as_primary, or
opened_as_secondary, then enabled).

559

Introduction to ISUP Procedures


MTP3 Interaction Handling
Within the Probe_opened_and_active state, the following sub-states are
managed:

MTP-3_not_opened (initial state when the probe is created)

MTP-3_unavailable

MTP-3_available

MTP-3_congested

State Transitions
Substate changes occur as MPT-3 indications are received from the network:

The MTP_available indication brings the LPC to the available state.

The MTP_restarting and MTP_unavailable indications bring the LPC to


the unavailable substate.

The MTP_congested indication brings the LPC from the available state to
the congested state.

The MTP_uncongested indication brings the LPC from the congested state
to the available state.

The following rules apply to primitive invocations and function calls performed by
the application via the HP OpenCall SS7 ISUP API:

560

Creation of a second probe on a given LPC is refused.

Opening of an already opened probe is refused.

setCircuitState() operations are allowed in the probe created state and


refused in the other states. getCircuitState() operations can be performed
throughout the life of a probe.

Primitives can only be received and sent after a probe has been opened.

For both state-machine and bypass probes, primitives from the application are
refused if MTP3 is not available. Either the notOpenLPC or the
unavailableLPC status code is returned.
For state-machine probes (ANSI version only), the MTP_UNAVAILABLE
indication from the HP OpenCall SS7 stack initiates an internal reset of all
configured circuits attached to the probe. This is indicated to the application by
a START_RESET_IND primitive (IsupAdditional::LocalReset =
MTP_UNAVAILABLE) on each impacted circuit. Note that the
START_RESET_IND primitive with the MTP_UNAVAILABLE indication is
received only in the ANSI version (it does not apply to the ITU-T version).

Chapter 15

Introduction to ISUP Procedures


MTP3 Interaction Handling

For state-machine probes, primitives from the application are generally refused
if MTP3 is congested. An LPC_CONGESTED status code is returned. However,
there are some exceptions to the previous rule. The following primitives are
accepted by HP OpenCall SS7 ISUP with respect to the congested state of
MTP3 (they may be rejected later in the processing based on some other
grounds):
Primitives that terminate calls:
START_RELEASE_IND_ACK
RELEASE_REQ
RELEASE_RESP
Primitives that reset circuits
START_RELEASE_IND_ACK
RELEASE_REQ
RESET_RESP
Primitives that reset circuit groups:
GROUP_RESET_REQ
GROUP_RESET_RESP
Primitives that block/unblock circuits:
BLOCKING_REQ
BLOCKING_RESP
UNBLOCKING_REQ
UNBLOCKING_RESP
Primitives that block/unblock circuit groups:
GROUP_BLOCKING_REQ
GROUP_BLOCKING_RESP
GROUP_UNBLOCKING_REQ
GROUP_UNBLOCKING_RESP
Primitives that stop REL/RSC retransmission on circuits:
STOP_REQ

Chapter 15

561

Introduction to ISUP Procedures


MTP3 Interaction Handling
Primitives that stop REL/RSC retransmission on circuit groups:
GROUP_STOP_REQ

For bypass probes, all primitives from the application are refused if MTP3 is
congested. An LPC_CONGESTED status code is returned.

The following rules apply to the reception of MTP Transfer Indications (e.g. ISUP
messages) from the network with respect to the MTP3 state:

562

Transfer indications received in the MTP_3 congested state are processed as


in the MTP_3 available state.

Transfer indications received in the MTP_3 unavailable state are ignored.

Transfer indications received in the MTP_3 not opened state are ignored.

Chapter 15

Introduction to ISUP Procedures


Remote DPC Status Indications

Remote DPC Status Indications


This section describes how HP OpenCall SS7 ISUP processes the following
indications received from MTP3 about a specific DPC:

MTP_pause

MTP_resume

DPC_congested

DPC_uncongested

UPU_unavailable

After processing, all received indications are delivered to the application as MTP3
DPC-related primitives.

DPC States
HP OpenCall SS7 ISUP maintains an internal representation of the configured
DPCs. A DPC object can be in one of the following states:

DPC_available (the initial state when the DPC object is created)

DPC_congested

DPC_paused (in this state there is no available route to the specified DPC)

State Transitions
Indications received about a DPC which are not in the HP OpenCall SS7 ISUP
configuration are ignored.
DPC state changes occur as indications related to configured DPCs are received
from the network:

Chapter 15

the MTP_pause indication brings the DPC into the paused state.

MTP_resume indication brings the DPC from the paused state into the
available state.

DPC_congested indication brings the DPC from the available state to the
congested state.

DPC_uncongested indication brings the DPC from the congested to the


available state.

563

Introduction to ISUP Procedures


Remote DPC Status Indications

The UPU_unavailable indication is passed to the application without


interaction with the DPC state. It is the responsibility of the application to
handle situations where the ISUP User Part is not accessible on a given DPC.
The application could handle this by periodically initiating an outbound test
call.

For state-machine probes, primitives from the application that target a given
DPC are generally refused if the DPC is congested. A DPC_CONGESTED status
code is returned. However, there are some exceptions to the previous rule. The
following primitives are accepted by HP OpenCall SS7 ISUP with respect to
the congested state of a DPC (they may be rejected later in the processing based
on some other grounds):
Primitives that terminate calls:
START_RELEASE_IND_ACK
RELEASE_REQ
RELEASE_RESP
Primitives that reset circuits
START_RELEASE_IND_ACK
RESET_REQ
RESET_RESP
Primitives that reset circuit groups:
GROUP_RESET_REQ
GROUP_RESET_RESP
Primitives that block/unblock circuits:
BLOCKING_REQ
BLOCKING_RESP
UNBLOCKING_REQ
UNBLOCKING_RESP
Primitives that block/unblock circuit groups:
GROUP_BLOCKING_REQ
GROUP_BLOCKING_RESP

564

Chapter 15

Introduction to ISUP Procedures


Remote DPC Status Indications
GROUP_UNBLOCKING_REQ
GROUP_UNBLOCKING_RESP
Primitives that stop REL/RSC retransmission on circuits:
STOP_REQ
Primitives that stop REL/RSC retransmission on circuit groups:
GROUP_STOP_REQ

Chapter 15

For bypass probes, all primitives from the application and targeted at a given
DPC are refused if the DPC is congested. A DPC_CONGESTED status code is
returned.

565

Introduction to ISUP Procedures


Generic Primitive Processing (State-machine Probe)

Generic Primitive Processing (State-machine Probe)


This section describes the generic processing performed by HP OpenCall SS7 ISUP
when receiving a primitive from the application on an SM probe.
HP OpenCall SS7 ISUP does the following:
1. Checks the probe status and returns if the probe is not created and opened.
2. Checks the IPC flow control. If active, returns with an IPC_SEND_FULL status.
3. Checks the LPC status (refer to LPC States on page 559).
4. Identifies the target DPC object and returns with an DPC_NOT_FOUND status if
there is a failure.
5. Checks the DPC status (refer to State Transitions on page 560).
6. Identifies the target CIC object and returns with a CIRCUIT_NOT_FOUND
status if failure.
7. Returns with an UNEQUIPPED_CIRCUIT status if the circuit is unequipped.
8. Validates that the message attached to the primitive is present (if applicable)
and of the right type (for example, SETUP_REQ must be associated with an IAM
message), and returns with an INCONSISTENT_ARGUMENTS status if failure.
9. Validates that the attached message is a valid message and returns with an
INVALID_MESSAGE status if there is a failure. This test will fail if the
application creates an instance of a message class (say FAR) which is not
supported by the compiled ISUP ANSI 95 message set (e.g. the definition of the
FAR message is not included in the message set metadata). It ships the message
instance to HP OpenCall SS7 ISUP without testing its validity via the
isValid() method.
10. Checks (absence, presence, type) the additional information parameter of the
primitive against the primitive type and returns with an
INCONSISTENT_ARGUMENTS status if there is a failure.
11. Checks that the message attached to the primitive can be encoded, and returns
with an ENCODING_ERROR status if there is a failure.
12. Checks that the encoded message size is valid (e.g. less than 272 bytes, or less
than 544 bytes for versions of the product that support segmentation), and
returns with an ENCODING_ERROR status if there is a failure.
13. Identifies and activates the target state machine for the primitive.

566

Chapter 15

Introduction to ISUP Procedures


Generic Primitive Processing (Bypass Probe)

Generic Primitive Processing (Bypass Probe)


This section describes the generic processing performed on a Bypass probe by
HP OpenCall SS7 ISUP on receiving a primitive from the application.
HP OpenCall SS7 ISUP performs the following steps:
1. Checks the probe status and returns unless the probe is created and opened.
2. Checks the IPC flow control. If active, returns with an IPC_SEND_FULL status.
3. Checks the LPC status (refer to LPC States on page 559).
4. Identifies the target DPC object and returns with a DPC_NOT_FOUND status if
there is a failure.
5. Checks the DPC status (refer to DPC States on page 563).
6. Checks that the primitive is either ISUP_MSG_REQ or PASS_ALONG_REQ, and
returns with an INCONSISTENT_ARGUMENTS status if there is a failure.
7. Validates the attached message and returns an INVALID_MESSAGE status in
case of failure. This test fails if the application creates an instance of a message
class (say FAR for ANSI 95) that is not supported by the compiled ISUP
message set (e.g. the definition of the FAR message is not included in the
message set metadata). It transmits the message instance to
HP OpenCall SS7 ISUP without testing its validity (via the isValid()
method).
8. Checks that the message attached to the primitive can be encoded, returns with
an ENCODING_ERROR status if there is a failure.
9. Checks that the encoded message size is valid (e.g. less than 272 bytes, or less
than 544 bytes for flavors supporting segmentation), and returns with a
MSG_TOO_LONG status if failure.
10. Sends the encoded message to the network. If sending fails because of IPC
outbound flow control, it:

Chapter 15

keeps the message in the internal sending queue

reports the failure to application

marks the probe active for rescheduling

567

Introduction to ISUP Procedures


Generic ISUP Message Handling (State-machine Probe)

Generic ISUP Message Handling (State-machine Probe)


This section describes the generic processing performed by HP OpenCall SS7 ISUP
when receiving an ISUP message from the network on an SM probe.
HP OpenCall SS7 ISUP performs the following steps:
1. Ignores the message if the LPC is not opened (race condition when
opening/closing a probe).
2. Identifies the following originating point code (DPC) of the message:

NOTE

ignore the message if the DPC object is not found

ignore the message if DPC paused

Routing is based on the OPC of the incoming message. From the stacks point of
view, this OPC corresponds to a DPC.

3. Ignores the message if it is empty or less than 3 bytes long (cannot access CIC
or Message Type).
4. Sends back a UCIC message if:

the CIC value is greater than 2**14-1 that is 16,383 (maximum CIC value
in ANSI) or greater than 2**12-1, that is 4,095 (maximum CIC value for
ITU-T based flavors)

no circuit object is associated with the received CIC value

a circuit object is found but is configured as unequipped

5. Sends back a CFN message if the message is not supported (e.g. not included in
the message set metadata) or cannot be decoded

568

Chapter 15

Introduction to ISUP Procedures


Generic ISUP Message Handling (Bypass Probe)

Generic ISUP Message Handling (Bypass Probe)


This section describes the generic processing performed by HP OpenCall SS7 ISUP
when receiving an ISUP message from the network on a bypass probe.
HP OpenCall SS7 ISUP performs the following steps:
1. Ignores the message if the LPC is not opened (race condition when
opening/closing a probe).
2. Identifies the following originating point code (DPC) of the message:

ignores the message and generate an UNKNOWN_OPC_MSG_IND to the


application if the DPC object is not found

ignores the message if the DPC paused

3. Ignores the message and generates an INVALID_ISUP_MSG_IND to the


application if:

the message is empty or less than 3 bytes long (cannot access CIC or
Message Type)

the message is not supported (e.g. not included in the message set metadata
or cannot be decoded)

The UNKNOWN_OPC_MSG_IND and INVALID_ISUP_MSG_IND primitives are


purely informative. Their objective is to inform the application about the existence
of a configuration or interoperability problem. It is then the responsibility of the
application to warn the Operator about the situation. To support the Operator in
his/her troubleshooting activities, error messages are logged by
HP OpenCall SS7 ISUP using TTL.

Chapter 15

569

Introduction to ISUP Procedures


Generic ISUP Circuit Group Message Handling

Generic ISUP Circuit Group Message Handling


The circuit group messages that are supported in ISUP are:

GRS/GRA

CGB/CGBA

CGU/CGUA

CQM/CQR

They all contain a rangeAndStatus parameter which determines which circuits


belong to the group. Thus, in addition to the generic processing described above, the
rangeAndStatus parameter in an incoming message is interpreted as described in
the following sections.

570

Chapter 15

Introduction to ISUP Procedures


Generic ISUP Circuit Group Message Handling

ANSI Based HP OpenCall SS7 ISUP


For ANSI based HP OpenCall SS7 ISUP:

Table 15-2
ISUP
Message

if range is 0, status is absent in both inbound and outbound messages.

if range is not 0, its maximum value is 23 (national). 31 (international) is not


supported.

rangeAndStatus Parameter
range = 0

range !=0

GRS

group=predetermined
no status subfield

range<24
group=[CIC,CIC+range]
no status subfield

GRA

no status subfield

status bit = 1 for locally blocked circuits

CGB

group=predetermined
no status subfield

range<24
group=[CIC,CIC+range] for which status bit = 1

CGBA

no status subfield

status bit = 1 for circuits which have been blocked

CGU

group=predetermined
no status subfield

range<24
group=[CIC,CIC+range] for which status bit = 1

CGUA

no status subfield

status bit = 1 for circuits which have been remotely


unblocked

CQM

group=single circuit
no status subfield

range<24
group=[CIC,CIC+range]
no status subfield

CQR

no status subfield

no status subfield

Chapter 15

571

Introduction to ISUP Procedures


Generic ISUP Circuit Group Message Handling

ITU-T Based HP OpenCall SS7 ISUP


In addition to the generic processing described above, the
rangeAndStatus parameter in an incoming message is interpreted as follows:

Table 15-3
ISUP
Message

range = 0 is a reserved value.

if range is not 0, its maximum value is 23 (national). 31 (international) is not


supported.

rangeAndStatus Parameter
range = 0

range !=0

GRS

-Reserved-

range<32
group=[CIC,CIC+range]
no status subfield

GRA

-Reserved-

status bit = 1 for locally blocked circuits for maintenance


reasons

CGB

-Reserved-

range<255, but number of affected circuits is less than or


equal to 32
group=[CIC,CIC+range] for which status bit = 1

CGBA

-Reserved-

status bit = 1 for circuits which have been blocked

CGU

-Reserved-

range<255, but number of affected circuits is less than or


equal to 32
group=[CIC,CIC+range] for which status bit = 1

CGUA

-Reserved-

status bit = 1 for circuits which have been remotely


unblocked

CQM

group=single circuit
no status subfield

range<32
group=[CIC,CIC+range]
no status subfield

CQR

no status subfield

no status subfield

572

Chapter 15

Introduction to ISUP Procedures


CFN and UCIC Message Handling

CFN and UCIC Message Handling


CFN Sending
A CFN message is sent by HP OpenCall SS7 ISUP in the following cases:

unknown message

message cannot be decoded

CFN Receipt
On receipt of a CFN message from the network, a CONFUSION_IND primitive is
issued to the application.

UCIC Sending
A UCIC message is sent back in the following cases:

the circuit associated with the received message is not configured

the circuit is configured as Unequipped

UCIC Receipt
On receipt of a UCIC message from the network, a MAINTENANCE_SYSTEM_IND
and an UNEQUIPPED_CIRCUIT_IND primitive are issued to the application, and
the state-machine affected by the UCIC message is reset. If a CPC message is
received, a START_RESET_IND indicating Unequipped Circuit is sent.

Chapter 15

573

Introduction to ISUP Procedures


User Defined ISUP Message Exchange

User Defined ISUP Message Exchange


User defined messages can be exchanged at any state for a given circuit:

574

a customized message can be sent using the ISUP_USR_MSG_REQ primitive

on receipt of a message recognized as a customized, HP OpenCall SS7 ISUP


issues an ISUP_USR_MSG_IND primitive associated with the received message

Chapter 15

Introduction to ISUP Procedures


Segmentation - ITU-T 93, 97, ETSI-V2 Versions

Segmentation - ITU-T 93, 97, ETSI-V2 Versions


HP OpenCall SS7 ISUP offers facilities to handle the segmentation of messages
whose length is more than 272 bytes, and less than 544 bytes. This segmentation
mechanism is only offered when selecting the ITU97 version, used with the ITU-T
93, ITU-T 97 or ETSI-V2 message sets.

Segmentation for Outgoing Messages


The application issues a SETUP_REQ to HP OpenCall SS7 ISUP. The associated
IAM message length is more than 272 bytes, and therefore needs segmentation.
HP OpenCall SS7 ISUP handles the segmentation process and then sends a
segmented IAM message, with its SGM extra-segment, to the network.
Figure 15-2

Segmentation for Outgoing Messages

If the message built by the application cannot be segmented, it is locally refused by


HP OpenCall SS7 ISUP with the appropriate error status.

Chapter 15

575

Introduction to ISUP Procedures


Segmentation - ITU-T 93, 97, ETSI-V2 Versions

Reassembly of Incoming Messages - Normal Case


A message is received from the network indicating that an SGM message is following
(this indication is present either in the optional backward call indicator or in the
optional forward call indicator). HP OpenCall SS7 ISUP waits for the associated
SGM message, and reassembles both messages to build a single message of the same
type as the first one received. The reassembled message is then sent to the
application with the proper associated primitive.
Figure 15-3

Reassembly of Incoming Messages - Normal Case

Reassembly of Incoming Messages -Failure Case 1


A message is received from the network indicating that an SGM message is
following. HP OpenCall SS7 ISUP waits for the associated SGM message. It is not
received within T34. Reassembly is canceled and the first received message is sent
to the application with the proper associated primitive.

576

Chapter 15

Introduction to ISUP Procedures


Segmentation - ITU-T 93, 97, ETSI-V2 Versions
Figure 15-4

Reassembly of Incoming Messages - T34 Expiry

Reassembly of Incoming Messages -Failure Case 2


A message is received from the network indicating that an SGM message is
following. HP OpenCall SS7 ISUP waits for the associated SGM message. A new
message is received that is not SGM. The reassembly of the first received message is
canceled.
Figure 15-5

Chapter 15

Reassembly of Incoming Messages - Other Message Received

577

Introduction to ISUP Procedures


Segmentation - ITU-T 93, 97, ETSI-V2 Versions
Reassembly of Incoming Messages - Interacting with
Continuity Check
An IAM is received indicating that an SGM message is following. A
continuity-check procedure is running and the COT message is received before the
SGM message.
The COT message is saved as long as the SGM message is not received, and then sent
to the application with the appropriate CONTINUITY_REPORT_IND primitive.
The diagram below does not describe the primitives associated with the continuity
check procedure.
Figure 15-6

578

Reassembly of Incoming Messages - COT Received

Chapter 15

Introduction to ISUP Procedures


Handling Unrecognized Messages - ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP

Handling Unrecognized Messages ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP
ITU97 mode supports handling of unrecognized ISUP messages, that is, messages
whose message type field is not part of the standard message set.
To be able to handle these messages, the following assumption is made, as stated in
the ITU-T 93/97 recommendations:
All unrecognized messages that can be received only contain parameters coded as
optional parameters, no new messages will contain mandatory fixed or mandatory
variable parameters
Two specific primitives are dedicated to unknown message exchanges:

UNKNOWN_MSG_REQ

UNKNOWN_MSG_IND

The unknown message is supported by a specific C++ class, IsupUkwn, which


offers read/write access to all standard parameters of ITU-T 97 through accessors
dedicated to optional parameters.
Two dedicated methods enable the ISUP message type field to be handled:

Chapter 15

IsupUkwn::setTagValue() allows the application to set the ISUP


message type field to be used by HP OpenCall SS7 ISUP when sending the
message

IsupUkwn::getTagValue() allows the application to retrieve the ISUP


message type field when receiving an unknown message

579

Introduction to ISUP Procedures


Handling Unrecognized Messages - ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP

580

Chapter 15

16

ISUP Call Control - Procedures


Common to ANSI and ITU-T
This chapter describes HP OpenCall SS7 ISUP behavior when controlling call
setup/teardown procedures that are common to ANSI and ITU-T.

Chapter 16

581

ISUP Call Control - Procedures Common to ANSI and ITU-T


Overview

Overview
For each procedure, this chapter provides:

582

message and primitive flow

circuit states and timer activity

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Conventions Used in Diagrams

Conventions Used in Diagrams


The diagrams in this chapter and in the following chapters:

Chapter 18, ISUP Call Control - Procedures Specific to ANSI,

Chapter 19, ISUP Call Control - Procedures Specific to ITU-T,

Chapter 17, ISUP Circuit Maintenance - Procedures Specific to ANSI,

Chapter 20, ISUP Circuit Maintenance - Procedures Specific to ITU-T,

use the following convention:


Prmt_Name(xxx)

Where:
Prmt_Name

Is the primitive name

xxx

Is the message type

In these diagrams, the term Signaling Network refers to a network capable of


transporting MSUs. This may be an SS7 network or an IP network (using
SIGTRAN).

Chapter 16

583

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Setup Procedures

Call Setup Procedures


Call setup is triggered when a message from the application is received by the ISUP
library containing the SETUP_REQ primitive and IAM. The request to setup a call
may be unsuccessful due to various factors, such as failure to receive a specific
ISUP library or dual seizure. The following scenarios illustrate the behavior of the
ISUP library in these various circumstances.

SETUP Request Locally Refused by HP OpenCall SS7 ISUP


The application issues a SETUP_REQ to HP OpenCall SS7 ISUP. The primitive is
locally rejected. Refer to the HP OpenCall SS7 ISUP API man pages for details on
how the failure condition is reported to the application.
This situation occurs in the following cases:

Figure 16-1

584

the (DPC, CIC) does not correspond to a valid configured circuit

the circuit is reserved for inbound traffic

the circuit has already been seized (inbound seizure)

the circuit is under reset

the IAM message cannot be encoded

the IPC flow control is active

the SS7 Stack underneath is unavailable or congested

SETUP_REQ Locally Refused by HP OpenCall SS7 ISUP

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Setup Procedures

SETUP Request - Dual Seizure Case 1


This scenario corresponds to the case where a circuit is seized on both sides at the
same time. As a result of the SETUP_REQ, HP OpenCall SS7 ISUP issues an IAM
(IAM-1) to the network. The issued IAM crosses the IAM (IAM-2) received from the
peer, on its way to HP OpenCall SS7 ISUP. Consequently, HP OpenCall SS7 ISUP
receives this IAM when already engaged in the processing of an outbound call
(CPCO).
In such a case, HP OpenCall SS7 ISUP instances determine which of the inbound
and outbound call attempts must be abandoned as follows. If the Signaling Point
Code of HP OpenCall SS7 ISUP is greater than the Signaling Point Code of the
peer, then HP OpenCall SS7 ISUP controls all even CICs and the peer controls all
odd CICs.
Here, HP OpenCall SS7 ISUP gives up and issues a SETUP_FAILURE_IND
primitive with a DUAL_SEIZURE cause. The application may use this information to
re-attempt the call setup on another circuit.

NOTE

There is no automatic call setup re-attempt as another circuit has to be selected.

Figure 16-2

Dual Seizure

Chapter 16

585

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Setup Procedures

SETUP Request - Dual Seizure Case 2


In this second scenario of incoming seizure, the IAM from the peer has already been
received by HP OpenCall SS7 ISUP at the time the SETUP_REQ is issued by the
application. Most likely the SETUP_IND is queued in the HP OpenCall SS7 ISUP
API s Up List, waiting for the application to read it.
In this case, HP OpenCall SS7 ISUP is already engaged in the processing of an
inbound call (CPCI) for the circuit at stake. The SETUP_REQ is therefore refused
directly (that is, synchronously) without delivery of any asynchronous indication.
Refer to the HP OpenCall SS7 ISUP man pages for details on how the refusal is
communicated back to the application.
The application may re-try a call setup on another circuit.
Figure 16-3

Incoming Seizure

SETUP Request - Failure to Receive ACM


In this scenario, an ACM must be received as a response to the IAM within T7. Failure
to receive ACM within T7 makes HP OpenCall SS7 ISUP abandon the call attempt
and issue a START_RELEASE_IND to the application.

586

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Setup Procedures
Figure 16-4

Failure to Receive ACM

Incoming Call Setup with Immediate Release


In this scenario, an REL message is received immediately following the incoming
IAM message.

Successful Call Setup for Incoming Side


Call Setup Including ACM Message Use
The following figure presents a successful call setup scenario where the application
sends ACM messages.

Chapter 16

587

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Setup Procedures
Figure 16-5

Successful Call Setup - Incoming Side

Call Setup Without ACM Message


The following figure presents a successful call setup scenario where the application
directly sends an ANM message to complete the call.
Figure 16-6

588

Successful Call Setup - Incoming Side

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Release

Call Release
A call can be released by either party, calling or called.

Normal Call Release - Outgoing Release


If the application wishes to release a circuit, it will send a RELEASE_REQ primitive
with a REL message containing the cause for releasing the circuit, such as normal.
The circuit status is modified to TRANSIENT, and the REL message is sent to the
SS7 network.
Figure 16-7

Call Release - Outgoing Release

Normal Call Release - Incoming Release


When an incoming REL is received, the application is notified with a
RELEASE_IND from the ISUP library.

Chapter 16

589

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Release
Figure 16-8

Call Release - Incoming Release

Call Release Collision - Case 1


In this scenario, a RELEASE_REQ primitive is received and causes a REL message to
be sent to the network. In the mean time, a REL message is also received. As a
consequence, an RLC message is sent back. Meanwhile, in response to the REL
message previously sent, an RLC message is received and the application is notified
with a RELEASE_CONF.

590

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Release
Figure 16-9

Abnormal Release - REL Collision

Call Release Collision - Case 2


In this scenario, HP OpenCall SS7 ISUP receives a RELEASE_REQ primitive, but a
REL message has just been received previously. That collision results in the
RELEASE_REQ primitive being rejected with a cause indicating WRONG_STATE.
The received REL message is nevertheless processed, and an RLC message is sent
back.

Chapter 16

591

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Release
Figure 16-10

Abnormal Release - REL Collision

Incoming Reset
When an RSC message is received by HP OpenCall SS7 ISUP, the application is
notified by a RESET_IND without any timer constraint.

592

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Call Release
Figure 16-11

Abnormal Release - Incoming Reset

NOTE

A RESET_RESP with RLC must be answered for the circuit which has been reset
by the RSC.

Chapter 16

593

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Reset

Circuit Reset
Because the circuit state information is maintained by the ISUP library, there may be
occasions when this information is inaccurate. In such cases, the circuit must be
reset to an idle condition at both local and remote ends, thereby making it available
for new traffic.

HP OpenCall SS7 ISUP Initiated Reset - Successful Procedure


In this scenario, HP OpenCall SS7 ISUP initiates a Reset procedure after reception
of an unexpected message:

for the ANSI standard, when HP OpenCall SS7 ISUP is in the


Wait-For-OGC-Complete state

for ITU-T standard, when HP OpenCall SS7 ISUP is in the Wait-For-ACM


state

As a result, a START_RESET_IND is sent to the application. It contains an


additional StartRelease information indicating the cause of the setup failure:
UNEXPECTED_MESSAGE. The application must respond to this indication as soon as
possible via a START_RESET_IND_ACK primitive. Upon reception of the latter
primitive, HP OpenCall SS7 ISUP issues an RSC message to the network and starts
timers T16 and T17.
On receipt of the RLC message, a RESET_CONF primitive is issued to the
application. For ANSI based HP OpenCall SS7 ISUP only, a
MAINTENANCE_SYSTEM_IND indicating RLC_AFTER_T17 is issued to the
application.

594

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Reset
Figure 16-12

Call Reset - Successful

Reset from Network - Successful Procedure


In this case, the Reset procedure is initiated by the network, hence a RESET_IND
versus a START_RESET_IND. The application must reply promptly, even though
HP OpenCall SS7 ISUP does not set any timer waiting for RESET_RESP from the
application.

Chapter 16

595

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Reset
Figure 16-13

Reset from Network - Successful Procedure

Reset from Application - Successful Procedure


The application can decide to reset a circuit. It does so using the RESET_REQ
primitive.
Figure 16-14

596

Reset from Application- Successful Procedure

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Group Reset from Network

Circuit Group Reset from Network


Normal Case
In this scenario, a GRS message is received on a circuit group of which 2 circuits are
out of IDLE state. For each of these circuits, a RESET_IND primitive with an
additional information Reset indicating a GROUP_RESET, is delivered to the
application. The latter needs to respond with a RESET_RESP with the same
additional information and no message. That way, no RLC message will be sent over.
The GRA group reset ack message is sent back only after all the expected
RESET_RESP and the GROUP_RESET_RESP (without GRA associated message)
primitives have been received from the application (when all the circuits are in the
appropriate state).

NOTE

If the application responds with a RESET_RESP (RLC), an RLC message will be sent.

Should a second GRS be received, even if its rangeAndStatus parameter is identical


to the previous one and therefore could be a repetition, it is processed as a new one.
In the above case, it is likely that not so many RESET_IND primitives will be sent to
the application as most circuit states will be idle.

Chapter 16

597

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Group Reset from Network
Figure 16-15

Group Reset

Failure Case
In this case, the GROUP_RESET_RESP is sent back by the application, but not all
RESET_IND have been acknowledged. The GRA message cannot be sent back to the
network, and an error is returned to the application.

598

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Group Reset from Network
Figure 16-16

Group Reset - Failure Case

Double Reset
Here, a circuit must be reset twice. It must first be reset by a Circuit Reset RSC, and
then by a Circuit Group Reset (it belongs to the group). After the list of circuits
involved in the group is established, HP OpenCall SS7 ISUP finds that the circuit is
already being reset, and therefore does not produce a RESET_IND for it. The
application replies to the first RESET_IND by a RESET_RESP, and then to the other
RESET_IND. Upon receipt of GROUP_RESET_RESP, as all the circuits of the group
are in the appropriate state, HP OpenCall SS7 ISUP can send the GRA.

NOTE

Chapter 16

It is likely that the RESET_RESP corresponding to the Circuit Reset contains an RLC
message and no additional information. This causes an RLC message to be sent to
the network.

599

ISUP Call Control - Procedures Common to ANSI and ITU-T


Circuit Group Reset from Network
Figure 16-17

600

Group Reset - Double Reset

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Information Exchange

Information Exchange
When supported by the selected standard (TTC typically does not support this),
HP OpenCall SS7 ISUP offers primitives to exchange solicited or unsolicited
information messages.

Solicited Information Exchange - Success


Figure 16-18

Chapter 16

Solicited Information Exchange - Incoming Request

601

ISUP Call Control - Procedures Common to ANSI and ITU-T


Information Exchange
Figure 16-19

Solicited Information Exchange - Outgoing Request

Solicited Information Exchange - Failure Case 1


In this scenario, the remote fails to complete a solicited information exchange while
the call is being set up. In this case, HP OpenCall SS7 ISUP initiates a release
procedure after T33.

602

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Information Exchange
Figure 16-20

Solicited Information Exchange - Failure

Solicited Information Exchange - Failure Case 2


It is not possible for the application to invoke a second information request while a
prior request is still pending.

Chapter 16

603

ISUP Call Control - Procedures Common to ANSI and ITU-T


Information Exchange
Figure 16-21

Solicited Information Exchange - Failure

Unsolicited Information Exchange


Figure 16-22

Unsolicited Information Exchange

Information Exchange - Failure Case


Information Request or Information primitives on an IDLE circuit are refused.

604

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Information Exchange
Figure 16-23

Chapter 16

Unsolicited Information Exchange - Failure

605

ISUP Call Control - Procedures Common to ANSI and ITU-T


Suspend/Resume

Suspend/Resume
Suspend/Resume - T6 Expiry
This procedure applies for both ANSI based and ITU-T based
HP OpenCall SS7 ISUP.
On T6 timeout, the START_RELEASE_IND primitive is sent to the application
indicating T6_TIMEOUT. When the application replies with
START_RELEASE_IND_ACK, the REL message is issued to the network. On receipt
of the RLC from the network, a RELEASE_CONF is issued to the application.
Figure 16-24

606

Suspend/Resume - T6 Timeout

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Forward Transfer

Forward Transfer
Forward Transfer Message - Normal Case
Here, a Forward Transfer message comes from the network (always forward) and is
simply transmitted to the application through a FORWARD_TRANSFER_IND. No
response is expected from the application.
Figure 16-25

Chapter 16

Forward Transfer Message - Normal Case

607

ISUP Call Control - Procedures Common to ANSI and ITU-T


Pass Along Message

Pass Along Message


Pass-along messages (PAM), containing an embedded ISUP message, can be passed
in both directions.

Pass Along Request - Normal Case


A PAM message may contain any ISUP message. HP OpenCall SS7 ISUP does not
analyze the encapsulated message, but transparently transmits it to the network or to
the application. The remote end will be notified by a PASS_ALONG_IND containing
the message.
For an outgoing call, before a PAM message can be sent, an ACM, ANM or PAM
message must have been received, indicating for the first two that the pass-along
method is available (in the backwardCallIndicators parameter). Otherwise, the
PASS_ALONG_REQ primitive is rejected.
For an incoming call, after the IAM message is received, and provided it indicates
that the pass-along method is available (in the Forward Call Indicators parameter),
the PASS_ALONG_REQ is accepted and causes a PAM message to be sent out.
The ANM message can be sent afterwards.
Figure 16-26

608

Pass Along Procedure - Outgoing Call

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Pass Along Message
Figure 16-27

Pass Along Procedure - Incoming Call

Pass Along Request - Error Case


Here, the ANM message received indicates that the pass-along method is not
available (in the backwardCallIndicators parameter). Therefore, the
PASS_ALONG_REQ primitive is rejected.
Figure 16-28

Chapter 16

Pass Along Procedure - Failure

609

ISUP Call Control - Procedures Common to ANSI and ITU-T


Continuity Check Request with IAM or CCR

Continuity Check Request with IAM or CCR


The Continuity Check is a procedure for checking a circuit. It can be requested,
when supported by the selected flavor, in an IAM, a CCR or a CRM message. The
following sections describe a number of Continuity scenarios.

Continuity Check on this Circuit


A Continuity Check is performed on the current circuit if the continuity check
indicator in the IAM message is set to Continuity Check required on this circuit.
Successful Continuity Check
For the ANSI case, refer to Continuity Check Request with IAM or CCR on
page 661.
For the ITU-T case, refer to Continuity Check Request with IAM or CCR on
page 692.
Failed Continuity Check
In the case presented below, the loopback tone is not detected by the application,
and consequently the T24 timer expires. A COT message indicating
ContinuityFailure is sent by HP OpenCall SS7 ISUP.

610

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Continuity Check Request with IAM or CCR
Figure 16-29

Chapter 16

Continuity Check - Outgoing Side - Failure

611

ISUP Call Control - Procedures Common to ANSI and ITU-T


Continuity Check Request with IAM or CCR
After a failed continuity check, a re-check is done automatically as depicted in the
Continuity Recheck, see Continuity Recheck on page 663.
Figure 16-30

612

Continuity Check - Incoming Side - Failure

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Continuity Check Request with IAM or CCR

Continuity Check on the Previous Circuit


A Continuity Check is performed on the previous circuit if the
continuityCheckIndicator in the IAM message is set to Continuity Check required
on the previous circuit.
Figure 16-31

Chapter 16

Continuity Check on Previous Circuit - Outgoing Side

613

ISUP Call Control - Procedures Common to ANSI and ITU-T


Facility Message

Facility Message
This message is supported by HP OpenCall SS7 ISUP in following cases:

ANSI based HP OpenCall SS7 ISUP

ITU-T based HP OpenCall SS7 ISUP, with ITU-T 93, ITU-T 97 and ETSI-V2
message sets

The FAC message can be sent or received in any state of a call.


Figure 16-32

614

FAC Message

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Facility Message

Chapter 16

615

ISUP Call Control - Procedures Common to ANSI and ITU-T


Facility Message

616

Chapter 16

ISUP Call Control - Procedures Common to ANSI and ITU-T


Facility Message

Chapter 16

617

ISUP Call Control - Procedures Common to ANSI and ITU-T


Facility Message

618

Chapter 16

17

ISUP Circuit Maintenance Procedures Specific to ANSI


This chapter describes circuit maintenance procedures that are specific to ANSI.

Chapter 17

619

ISUP Circuit Maintenance - Procedures Specific to ANSI


Overview

Overview
The circuit maintenance processes described in this chapter include:

620

circuit blocking and unblocking

circuit group blocking and unblocking

circuit group query

circuit validation

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Blocking/Unblocking from a Network

Circuit Blocking/Unblocking from a Network


The blocking and unblocking mechanisms allow traffic to be removed from, and
then returned to, specific circuits.

Circuit Blocking from a Network - Normal Case


In this case, the circuit is put in the IDLE_REMOTELY_BLOCKED state.
Figure 17-1

Circuit Blocking from Network - Normal Case

Circuit Blocking from User - Normal Case


In this case, the circuit is put in the IDLE_LOCALLY_BLOCKED state.
Figure 17-2

Chapter 17

Circuit Blocking from User - Normal Case

621

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Blocking/Unblocking from a Network

Circuit Unblocking from a Network - Normal Case


The application is notified of the unblocking event if the circuit is actually remotely
blocked. In this case, it must reply with an UNBLOCKING_RESP primitive. That
causes the circuit to be marked not-remotely-blocked and the UBA message to be
sent to the network.
If the circuit is not remotely blocked, and a UBL is received, no UNBLOCKING_IND
is issued to the application, but the UBL message is acknowledged with a UBA.
Figure 17-3

Circuit Unblocking from Network- Normal Case

Circuit Unblocking from User - Normal Case


Figure 17-4

622

Circuit Unblocking from User - Normal Case

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Blocking/Unblocking from a Network

Circuit Unblocking from a Network on Reception of an IAM


In this case, an IAM indicating non test call, or a CRM message, received on a
REMOTELY_BLOCKED circuit, removes the blocking condition. It is the
responsibility of the application to synchronize the circuit state, as no
MAINTENANCE_SYSTEM_IND is issued by HP OpenCall SS7 ISUP.
Figure 17-5

Circuit Unblocking on Reception of IAM

Circuit Blocking during Setup Procedure


The reception of a BLO during the setup procedure (wait_for_ACM state) triggers a
release of the circuit. The application is informed through a START_RELEASE_IND
primitive indicating BLOCKING. On reply with a START_RELEASE_IND_ACK, the
REL message is sent to the network, and a RELEASE_CONF primitive is issued to the
application by HP OpenCall SS7 ISUP on receipt of the RLC message.

Chapter 17

623

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Blocking/Unblocking from a Network
Figure 17-6

624

Circuit Blocking during Call Setup

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking

Circuit Group Blocking/Unblocking


The group blocking/unblocking procedures are specific for each supplied standard
of HP OpenCall SS7 ISUP.
HP OpenCall SS7 ISUP handles both types of Group Blocking messages:

Group Blocking with immediate release

Group Blocking without immediate release

Group Blocking from Network Immediate Release - Normal Case 1


HP OpenCall SS7 ISUP reacts to the first received CGB message.
In this scenario, a CGB message is received from the network. The message specifies
that call release should be performed. Consequently, HP OpenCall SS7 ISUP:

issues a GROUP_BLOCKING_IND primitive

initiates the release of calls, by sending a START_RESET_IND primitive with


additional info indicating BLOCKING_WITH_RELEASE. The following diagram
depicts a situation where 2 circuits of the group are in this initial phase and
hence are released

waits for the START_RESET_IND_ACK and GROUP_BLOCKING_RESP


primitives

marks all circuits as remotely blocked

upon receipt of all these primitives, sends back the acknowledgment message
CGBA

If a START_RESET_IND_ACK is missing, the CGBA will not be sent and the


application will get an error.
The START_RESET_IND(BLOCKING_WITH_RELEASE) primitive does not cause
an RSC to be sent to the network, therefore no RLC is received and there is no
RESET_CONF to be awaited.

Chapter 17

625

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking
Figure 17-7

626

Group Blocking with Release - Normal Case

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking

Group Blocking from Network - No Release Normal Case


In this scenario, a CGB message is received from the network, and the CBG is
requesting the No Release of the call. As a result, HP OpenCall SS7 ISUP:

Figure 17-8

Chapter 17

issues a GROUP_BLOCKING_IND primitive to the application

waits for the GROUP_BLOCKING_RESP from the application and sends a CGBA
message back to the network

marks all circuits as remotely blocked

Group Blocking without Release - Normal Case

627

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking

Group Blocking (Immediate Release or Not)


- From User - Normal Case
In this scenario, a maintenance GROUP_BLOCKING request is sent by the user.
Consequently, HP OpenCall SS7 ISUP:

sends two identical CBG messages using the one associated with the primitive

waits for the GROUP_BLOCKING_CONF (CGBA) primitive

marks all circuits as locally blocked

The rangeAndStatus parameter is interpreted in the same way as the CGB


message
Figure 17-9

628

Group Blocking from User - Normal Case

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking

Group Unblocking from NetworkNormal Case


In this scenario, a CGU is received from the network. As a result,
HP OpenCall SS7 ISUP:

NOTE

informs the application using a GROUP_UNBLOCKING_IND

waits for the GROUP_UNBLOCKING_RESP, and upon receipt of it, sends a CGUA
back to the network

marks all circuits as locally blocked

Although the CGU must be of the same type as the CGB previously sent (i.e. no
release or immediate release), no control is performed, and the CGU is
always processed.

The rangeAndStatus parameter is interpreted in the same way as the CGB


message.
Figure 17-10

Chapter 17

Group Unblocking from Network- Normal Case

629

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking

Group Unblocking (Immediate or Not)


- From User - Normal Case
In this scenario, a maintenance GROUP_UNBLOCKING request is sent by the user.
Consequently, HP OpenCall SS7 ISUP:

Figure 17-11

sends the CGU message associated with the primitive to the network

waits for the CGUA message from the network and issues a
GROUP_BLOCKING_CONF primitive to the application

marks all circuits as locally unblocked

Group Unblocking from User - Normal Case

Group Blocking (Without Immediate Release)


- During Call Setup Procedure
This case only concerns received CGBs indicating no release with circuits in an
outgoing call setup phase (Wait for Address Complete state).
In such cases, HP OpenCall SS7 ISUP issues a START_RELEASE_IND primitive,
indicating the BLOCKING cause. When receiving START_RELEASE_IND_ACK for
each concerned circuit, HP OpenCall SS7 ISUP sends REL messages to release the
call. A RELEASE_CONF primitive is issued when an RLC comes back from the
network.

630

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Blocking/Unblocking
In parallel, the application finishes the group blocking operation by sending a
GROUP_BLOCKING_RESP primitive without any associated messages.
HP OpenCall SS7 ISUP creates and sends the corresponding CGBA message to the
network.
Figure 17-12

Chapter 17

Group Blocking during Call Setup

631

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query

Circuit Group Query


Circuit Group Query from the Network
Here, the network initiates a circuit group query by sending a Circuit Query message
(CQM).
HP OpenCall SS7 ISUP can process the request internally without interfering with
the application. Therefore, no indication is issued to the latter.
Each circuit of the group selected is examined, and its status is returned in the
Circuit State Indicator parameter of the Circuit Query Response Message (CQR). If
the circuit is not found, it is considered unequipped.
rangeAndStatus parameter interpretation:

Figure 17-13

632

if range is 0, the group is reduced to a single circuit

if range is not 0, a list is built from the message CIC, up to the range value +
1

Circuit Group Query - from Network

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query

Circuit Group Query from User (Application)


The application is allowed to activate a circuit group query procedure by creating a
CQM message and sending it to the network associated with a GROUP_QUERY_REQ
primitive.
HP OpenCall SS7 ISUP starts a T28 Timer dedicated to the group query procedure.
On receipt of the answer to the CQM from the network, HP OpenCall SS7 ISUP
inspects the received CQR message to check for error conditions in both the call
processing and the maintenance state. After this inspection, the CQS message is
transmitted to the application by HP OpenCall SS7 ISUP through a
GROUP_QUERY_CONF primitive. See Figure 17-14, Circuit Group Query from
User - Normal Case.
Figure 17-14

Circuit Group Query from User - Normal Case

If the started timer expires, HP OpenCall SS7 ISUP sends back a


MAINTENANCE_SYSTEM_IND primitive indicating T28_TIMEOUT as shown in
Figure 17-15, Circuit Group Query from User - Failure (T28 Timeout).
Figure 17-15

Chapter 17

Circuit Group Query from User - Failure (T28 Timeout)

633

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query
When the local circuit state is incoming busy or outgoing busy, and the remote
circuit is idle or unequipped, the behavior of HP OpenCall SS7 ISUP is as shown in
Figure 17-16, Circuit Group Query from User - Error in Processing State - Case 1.
Figure 17-16

Circuit Group Query from User - Error in Processing State - Case 1

NOTE

It is the applications responsibility to release any interconnected circuits.

When the local circuit state is idle or unequipped, and the remote circuit is incoming
busy or outgoing busy, the behavior of HP OpenCall SS7 ISUP is as shown in
Figure 17-17, Circuit Group Query from User - Error in Processing State - Case 2.

634

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query
Figure 17-17

Circuit Group Query from User - Error in Processing State - Case 2

When the local and remote circuit states are both incoming busy or both outgoing
busy, the behavior of HP OpenCall SS7 ISUP is as shown in Figure 17-18, Circuit
Group Query from User - Error in Processing State - Case 3.
Figure 17-18

Chapter 17

Circuit Group Query from User - Error in Processing State - Case 3

635

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query
When the local circuit state is unequipped, and the remote circuit is active (that is,
not locally or remotely blocked, and not unequipped or transient), the behavior of
HP OpenCall SS7 ISUP is as shown in Figure 17-19, Circuit Group Query from
User - Error in Maintenance State - Case 1.
Figure 17-19

Circuit Group Query from User - Error in Maintenance State - Case 1

When the local circuit state is not locally blocked, and the remote circuit is
unequipped, the behavior of HP OpenCall SS7 ISUP is as shown in Figure 17-20,
Circuit Group Query from User - Error in Maintenance State - Case 2.

636

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query
Figure 17-20

Circuit Group Query from User - Error in Maintenance State - Case 2

When the local circuit state is remotely blocked, and the remote circuit is not locally
blocked, the behavior of HP OpenCall SS7 ISUP is as shown in Figure 17-21,
Circuit Group Query from User - Error in Maintenance State - Case 3.
Figure 17-21

Circuit Group Query from User - Error in Maintenance State - Case 3

When the local circuit state is locally blocked, and the remote circuit is not remotely
blocked, the behavior of HP OpenCall SS7 ISUP is as shown in Figure 17-22,
Circuit Group Query from User - Error in Maintenance State - Case 4.

Chapter 17

637

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query
The behavior after sending the BLO message is the same as after a user initiated
BLOCKING_REQ.
Figure 17-22

Circuit Group Query from User - Error in Maintenance State - Case 4

When the local circuit state is not locally blocked, and the remote circuit is remotely
blocked, the behavior of HP OpenCall SS7 ISUP is as shown in Figure 17-23,
Circuit Group Query from User - Error in Maintenance State - Case 5.The
behavior after sending the BLO message is the same as after a user initiated
UNBLOCKING_REQ.

638

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Group Query
Figure 17-23

Circuit Group Query from User - Error in Maintenance State - Case 5

When the local circuit state is not remotely blocked, and the remote circuit is locally
blocked, the behavior of HP OpenCall SS7 ISUP is as shown in the Figure 17-24,
Circuit Group Query from User - Error in Maintenance State - Case 6.
Figure 17-24

Chapter 17

Circuit Group Query from User - Error in Maintenance State - Case 6

639

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation

Circuit Validation
Circuit Validation from Network
In this example, a Circuit Validation Test message (CVT) is received from the
network. Because the information requested by the CVT is only known to the
application, HP OpenCall SS7 ISUP simply informs the latter using a
CIRCUIT_VALIDATION_IND. The application may check that the circuit
translation exists and prepares the Circuit Validation Response Message (CVR),
which it sends using the primitive CIRCUIT_VALIDATION_RESP. The CVR
message is then sent back to the network.
Figure 17-25

640

Circuit Validation from Network

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation

Circuit Validation from User


Circuit Validation from User - Normal Case
In this example, the user (application) sends a CIRCUIT_VALIDATION_REQ to
HP OpenCall SS7 ISUP which then starts T_CVT and sends a Circuit Validation
Test message (CVT) to the network.
When a Circuit Validation Response message (CVR) is received from the network,
HP OpenCall SS7 ISUP stops T_CVT and informs the application using a
CIRCUIT_VALIDATION_CONF primitive.
Figure 17-26

Chapter 17

Circuit Validation from User - Normal Case

641

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation
Circuit Validation from User - Test Failed - Two T_CVT Timeouts
In this example, the user (application) sends a CIRCUIT_VALIDATION_REQ to
HP OpenCall SS7 ISUP which then starts T_CVT and sends a Circuit Validation
Test message (CVT) to the network.
On the first T_CVT timeout, another CVT message is sent to the network.
On the second T_CVT timeout, HP OpenCall SS7 ISUP informs the application
using a MAINTENANCE_SYSTEM_IND with indication
CIRCUIT_VALIDATION_TEST_FAILED.
Figure 17-27

642

Circuit Validation from User - Test Failed - Two T_CVT Timeouts

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation
Circuit Validation from User - Test Failed
- CVR Received Before Second T_CVT Timeout
In this example, the user (application) sends a CIRCUIT_VALIDATION_REQ to
HP OpenCall SS7 ISUP which then starts T_CVT and sends a Circuit Validation
Test message (CVT) to the network.
When T_CVT times out, another CVT message is sent to the network.
Subsequently a CVT message is received from the network, HP OpenCall SS7 ISUP
stops T_CVT and informs the application using a CIRCUIT_VALIDATION_CONF
primitive.
Figure 17-28

Chapter 17

Circuit Validation from User - Test Failed -CVR Received Before Second
T_CVT Timeout

643

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation

644

Chapter 17

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation

Chapter 17

645

ISUP Circuit Maintenance - Procedures Specific to ANSI


Circuit Validation

646

Chapter 17

18

ISUP Call Control - Procedures


Specific to ANSI
This chapter describes HP OpenCall SS7 ISUP behavior when controlling call
setup/teardown procedures that are specific to ANSI.

Chapter 18

647

ISUP Call Control - Procedures Specific to ANSI


Call Setup Without ACM Reception

Call Setup Without ACM Reception


The following figure presents a successful outgoing call with direct reception of
ANM.
Figure 18-1

648

Successful Call Setup - Outgoing Side

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Call Release

Call Release
A call can be released by either party, calling or called.

Abnormal Call Release - Case 1


This scenario depicts a a situation where the peer node fails to acknowledge the REL
message sent out by HP OpenCall SS7 ISUP.
As a result, HP OpenCall SS7 ISUP:

First retransmits the REL message every T1, until T5 pops

After T5, HP OpenCall SS7 ISUP A issues a MAINTENANCE_SYSTEM_IND


indicating T5_TIMEOUT to application A and initiate the Circuit Reset after
T5 procedure by sending a START_RESET_IND primitive to the application.
The procedure is controlled by one timer: T17. A reset message (RSC) is sent
out upon receipt of the START_RESET_IND_ACK from application.

On each occurrence of T17, an RSC message is sent out.

A MAINTENANCE_SYSTEM_IND indicating T17_TIMEOUT is issued.

The procedure goes on until a STOP_REQ primitive is received from application


A. The STOP primitive stops the reset procedure and brings the circuit back to
idle state.

A MAINTENANCE_SYSTEM_IND indicating CRS_STOP is issued.

The abnormal call release procedure described in this scenario is applicable to both
inbound and outbound circuits.

NOTE

Chapter 18

RSC Message generation upon time-out is suspended if MTP3 is not available or


congested.

649

ISUP Call Control - Procedures Specific to ANSI


Call Release
Figure 18-2

650

Abnormal Release - Reset Failed

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Call Release

Abnormal Call Release - Case 2


In this case, an RLC message is eventually received during the reset procedure. As a
result, HP OpenCall SS7 ISUP completes the reset sequence and issues a
RESET_CONF() primitive. A MAINTENANCE_SYSTEM_IND indicating
RLC_AFTER_T17 is issued to the application after RESET_CONF.

Chapter 18

651

ISUP Call Control - Procedures Specific to ANSI


Call Release
Figure 18-3

652

Abnormal Release - RLC Received at Last

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Circuit Reset

Circuit Reset
Because the circuit state information is maintained by the ISUP library, there may be
occasions when this information is inaccurate. In such cases, the circuit must be
reset to an idle condition at both local and remote ends, thereby making it available
for new traffic.

HP OpenCall SS7 ISUP Initiated Reset


- Failure to Receive RLC
In this case, HP OpenCall SS7 ISUP has initiated the CPC-initiated Reset
procedure. The network fails to respond with an RLC message. As a result,
HP OpenCall SS7 ISUP retransmits an RSC message every T16, until the procedure
is stopped by the application via a STOP_REQ primitive or until the first T17
time-out.
After T17:

a MAINTENANCE_SYSTEM_IND is issued to the application, informing the


application/Operator about the error situation

RSC messages are sent every T17 (typically 1 minute) instead of every T16
(typically 5 seconds)

until a STOP_REQ primitive is received from the application.

Chapter 18

653

ISUP Call Control - Procedures Specific to ANSI


Circuit Reset
Figure 18-4

654

Call Reset - Failure to Receive RLC

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Circuit Group Reset from User

Circuit Group Reset from User


Normal Case
In this scenario, a GROUP_RESET_REQ request is sent by the user. All the circuits of
the group are remotely and locally unblocked, and two GRS messages are two GRS
messages are sent to the network. Then ISUP waits for the Acknowledgment
message GRA before returning to idle.
Figure 18-5

Chapter 18

Group Reset from User- Normal Case

655

ISUP Call Control - Procedures Specific to ANSI


Circuit Reservation

Circuit Reservation
Circuit Reservation from Network
A circuit may be reserved prior to its setup. For the current version of
HP OpenCall SS7 ISUP, the application cannot request the reservation. However, it
is informed of a circuit reservation request by receiving a
CIRCUIT_RESERVATION_IND. Here, the circuit involved is marked incoming
busy by HP OpenCall SS7 ISUP. The application must respond to that indication.
On receipt of the CIRCUIT_RESERVATION_RESP, HP OpenCall SS7 ISUP sends
back a CRA message and starts the timer T_CRA associated with the
waiting-for-IAM state. The next steps are those described in the call setup procedure,
see Call Setup Procedures on page 585.
Figure 18-6

656

Circuit Reservation from Network

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Circuit Reservation

Circuit Reservation from Network - T_CRA Expiry


In this example, the timer T_CRA has expired before the IAM message is received.
The application is informed of that event by the receipt of a START_RELEASE_IND
(indicating TCRA_TIMEOUT) which it acknowledges by sending back a
START_RELEASE_IND_ACK primitive. Upon receipt of the latter,
HP OpenCall SS7 ISUP sends a Release message and goes into the release
procedure previously described.
Figure 18-7

Chapter 18

Circuit Reservation from Network - Failure

657

ISUP Call Control - Procedures Specific to ANSI


Suspend/Resume

Suspend/Resume
When supported by the selected flavor, HP OpenCall SS7 ISUP offers primitives
and procedures to handle Suspend/Resume messages.

Suspend/Resume - Outgoing Call


HP OpenCall SS7 ISUP only signals incoming SUS messages through a
SUSPENDED_IND primitive. Outgoing SUS messages are considered unexpected.
Figure 18-8

658

Suspend/Resume - Outgoing Call

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Suspend/Resume

Suspend/Resume - Incoming Call


HP OpenCall SS7 ISUP only accepts outgoing SUS messages associated with
SUSPEND_REQ primitives. Incoming SUS messages are considered unexpected.
The suspended condition is removed after the application sends a RESUME_REQ
primitive associated with an RES message.
Figure 18-9

Chapter 18

Suspend/Resume - Incoming Call

659

ISUP Call Control - Procedures Specific to ANSI


Exit Message

Exit Message
Exit Message - Normal Case
In this example, an Exit message comes from a gateway in the network. Because it
is significant during the call setup only, it is transmitted to the application, through
an EXIT_IND, only if the CPC status is wait-for-answer(3) or
wait-for-address-complete(2). The application can use it to generate timing
indications. No response is expected on the network side.
Figure 18-10

660

Exit Message - Normal Case

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR

Continuity Check Request with IAM or CCR


The Continuity Check is a procedure for checking a circuit. It can be requested,
when supported by the selected flavor, in an IAM, a CCR or a CRM message. The
following sections describe a number of Continuity scenarios.

Continuity Check on this Circuit


A Continuity Check is performed on the current circuit if the continuity check
indicator in the IAM message is set to Continuity Check required on this circuit.
Successful Continuity Check
The outgoing side sends a Continuity message with a successful indication after a
correct check of the transmission path (a loop is required on the incoming side, a
tone is sent from the outgoing side and is returned in time).

NOTE

Chapter 18

CONNECT_LOOP_IND and SETUP_IND are handled in parallel by


HP OpenCall SS7 ISUP. Therefore, depending on the behavior of the application,
the order of the primitives in the diagram below can change. However,
CONNECT_LOOP_IND and DISABLE_ECHO_IND will always be issued to the
application sequentially (that is, after the corresponding ACKs are sent back by the
application).

661

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR
Figure 18-11

662

Continuity Check - Outgoing Side

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR
Figure 18-12

Continuity Check - Incoming Side

Continuity Recheck
If the continuity recheck procedure is a success, only the outgoing side sends a REL
message to finish the procedure.

Chapter 18

663

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR
Figure 18-13

664

Continuity Recheck - Outgoing Side

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR

Chapter 18

665

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR
Figure 18-14

666

Continuity Recheck - Incoming Side

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR

Continuity Recheck - TCCR Expiry at Outgoing Side


If the TCCR timer expires during the continuity recheck phase, either activated after
a continuity failure during call setup, or after an explicit continuity recheck request,
the following occurs:

Chapter 18

On the outgoing side, a reset procedure is activated by HP OpenCall SS7 ISUP,


the continuity recheck phase is cancelled. A START_RESET_IND_ACK
indicating DCO_LPA_FAIL is issued to the application and an RSC message is
sent by HP OpenCall SS7 ISUP when application acknowledges by a
START_RESET_IND_ACK.

On the incoming side, the continuity recheck procedure is cancelled by the reset
procedure engaged on the outgoing side.

667

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR
Figure 18-15

668

Continuity Recheck - Outgoing Side - TCCR Expiry

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR

Continuity Recheck - T24 Expiry at Outgoing Side


If the T24 timer expires during the continuity recheck phase, either activated after a
continuity failure during call setup, or after an explicit continuity recheck request,
the following occurs.
On the outgoing side, a COT indicating failure is issued to the network, and a
MAINTENANCE_SYSTEM_IND primitive indicating DCO_FAIL is issued to the
application after the SECOND continuity failure (including the eventual call setup
continuity failure). The T26 timer is started to restart a continuity recheck phase at
its expiry.

Chapter 18

669

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR
Figure 18-16

670

Continuity Recheck - Outgoing Side - T24 Expiry

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with IAM or CCR

Chapter 18

671

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with CRM

Continuity Check Request with CRM


Because the Circuit Reservation Message is supported only on the incoming side,
the outgoing side is not represented in the following scenarios.

Continuity Check on this Circuit


Note that for Continuity Check, the order (SETUP_IND, CONNECT_LOOP_IND,
DISABLE_ECHO_IND) and (CONTINUITY_REPORT_IND,
SETUP_FAILURE_IND, REMOVE_LOOP_IND, and ENABLE_ECHO_IND) is
not deterministic since there are two separate state machines involved.
For Continuity Recheck, the order is deterministic since it is handled by one state
machine.

672

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with CRM
Successful Continuity Check
Figure 18-17

Chapter 18

Continuity Check with CRM - Incoming Side - Success

673

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with CRM
Failed Continuity Check and Recheck Procedure
Figure 18-18

674

Continuity Check with CRM - Incoming Side - Failure

Chapter 18

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with CRM
Continuity Check on the Previous Circuit
- Not Required on this Circuit
Even if the continuity check is required on the previous circuit,
HP OpenCall SS7 ISUP handles the request as if no continuity was required.
Figure 18-19

Chapter 18

Continuity Check with CRM - Not Required / Required on Previous

675

ISUP Call Control - Procedures Specific to ANSI


Continuity Check Request with CRM

676

Chapter 18

19

ISUP Call Control - Procedures


Specific to ITU-T
This chapter describes HP OpenCall SS7 ISUP behavior when controlling call
setup/teardown procedures that are specific to ITU-T.

Chapter 19

677

ISUP Call Control - Procedures Specific to ITU-T


Successful Call Setup for Outgoing Side

Successful Call Setup for Outgoing Side


Call Setup Including ACM Reception
The following figure presents a successful outgoing call with receipt of an ACM
message.
Figure 19-1

Successful Call Setup - Outgoing Side

During the outgoing call setup phase, unlimited CPG messages can also be received
by HP OpenCall SS7 ISUP. Receipt of the ANM message is signaled to the
application by a SETUP_CONF primitive, which indicates that the call enters the
active phase.

NOTE

678

The TTC flavor does not use the T9 timer. In this particular case, no T9 timer is
started when receiving an ACM message.

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Successful Call Setup for Outgoing Side

Use of the CON Message


When supported by the selected flavor, the CON message can be sent or received by
HP OpenCall SS7 ISUP during call setup phases.
Use of the CON Message for Outgoing Calls
The application must check the message type associated with the SETUP_CONF
primitive to determine which message (ANM or CON) has been used.
Figure 19-2

Use of CON Message - Outgoing Side

Use of the CON Message for Incoming Calls


Instead of using an ANM message to complete the incoming call, the application can
make use of the CON message associated with the SETUP_RESP primitive.

Chapter 19

679

ISUP Call Control - Procedures Specific to ITU-T


Successful Call Setup for Outgoing Side
Figure 19-3

Use of CON Message - Incoming Side

Use of the SAM Message


When supported by the selected flavor, the SAM message can be sent or received by
the application using HP OpenCall SS7 ISUP through INFORMATION_REQ and
INFORMATION_IND dedicated primitives.

NOTE

The SAM message can only be sent after having sent IAM and before having received
ACM.
The SAM message can only be received after having received IAM and before having
sent ACM.

680

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Successful Call Setup for Outgoing Side
Use of the SAM Message for Outgoing Calls
Figure 19-4

Use of SAM Message - Outgoing Side

Use of the SAM Message for Incoming Calls


Figure 19-5

Chapter 19

Use of SAM Message - Incoming Side

681

ISUP Call Control - Procedures Specific to ITU-T


Call Release

Call Release
A call can be released by either party, calling or called.

Abnormal Call Release - Case 1


This scenario depicts a a situation where the peer node fails to acknowledge the REL
message sent out by HP OpenCall SS7 ISUP. As a result, HP OpenCall SS7 ISUP:

First retransmits the REL message every T1, until T5 pops

After T5, HP OpenCall SS7 ISUP A issues a MAINTENANCE_SYSTEM_IND


indicating T5_TIMEOUT to application A and initiate the Circuit Reset after
T5 procedure by sending a START_RESET_IND primitive to the application.
The procedure is controlled by one timer: T17. A reset message (RSC) is sent
out upon receipt of the START_RESET_IND_ACK from application.

On each occurrence of T17, an RSC message is sent out

The procedure goes on until a STOP_REQ primitive is received from application


A. The STOP primitive stops the reset procedure and brings the circuit back to
idle state.

The abnormal call release procedure described in this scenario is applicable to both
inbound and outbound circuits.

NOTE

682

RSC Message generation upon time-out is suspended if MTP3 is not available or


congested.

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Call Release
Figure 19-6

Abnormal Release - Reset Failed

Abnormal Call Release - Case 2


In this case, an RLC message is eventually received during the reset procedure. As a
result, HP OpenCall SS7 ISUP completes the reset sequence and issues a
RESET_CONF() primitive. A MAINTENANCE_SYSTEM_IND indicating
RLC_AFTER_T17 is issued to the application before RESET_CONF.

Chapter 19

683

ISUP Call Control - Procedures Specific to ITU-T


Call Release
Figure 19-7

684

Abnormal Release - RLC Received at Least

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Circuit Reset

Circuit Reset
Because the circuit state information is maintained by the ISUP library, there may be
occasions when this information is inaccurate. In such cases, the circuit must be
reset to an idle condition at both local and remote ends, thereby making it available
for new traffic.

HP OpenCall SS7 ISUP Initiated Reset


- Failure to Receive RLC
In this case, HP OpenCall SS7 ISUP has initiated the CPC-initiated Reset
procedure. The network fails to respond with an RLC message. As a result,
HP OpenCall SS7 ISUP retransmits an RSC message every T16, until the procedure
is stopped by the application via a STOP_REQ primitive or until the first T17
time-out.
After T17:

a MAINTENANCE_SYSTEM_IND is issued to the application, informing the


application/Operator about the error situation

RSC messages are sent every T17 (typically 1 minute) instead of every T16
(typically 5 seconds)

until a STOP_REQ primitive is received from the application.

Chapter 19

685

ISUP Call Control - Procedures Specific to ITU-T


Circuit Reset
Figure 19-8

686

Call Reset - Failure to Receive RLC

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Circuit Group Reset from USER

Circuit Group Reset from USER


Normal Case
In this scenario, a GROUP_RESET_REQ request is sent by the user. All the circuits of
the group are remotely and locally unblocked, and two GRS messages are sent to the
network. Then ISUP waits for the Acknowledgment message GRA before returning
to idle.
Figure 19-9

Chapter 19

Group Reset from User- Normal Case

687

ISUP Call Control - Procedures Specific to ITU-T


Suspend/Resume

Suspend/Resume
Processing of the Suspend/Resume message depends on the source of the messages
(user or network initiated) and the origin of the call (outgoing or incoming).

Suspend/Resume - Incoming Call


For an incoming call, HP OpenCall SS7 ISUP ignores the SUS message indicating
Network Initiated in the SuspendResumeIndicator parameter. It only signals SUS
messages indicating User Initiated in the SuspendResumeIndicator parameter,
through a SUSPEND_IND primitive. The same behavior applies to the RES message,
that HP OpenCall SS7 ISUP issues to the application through a RESUME_IND
primitive.
In both cases, an AdditionnalInfo field indicating FROM_USER is associated with the
primitive.
HP OpenCall SS7 ISUP accepts both SUSPEND_REQ and RESUME_REQ primitives
with associated messages coming from the application.

688

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Suspend/Resume
Figure 19-10

Suspend/Resume - Incoming Call

Suspend/Resume - Outgoing Call


For an outgoing call, HP OpenCall SS7 ISUP accepts both the SUS message
indicating Network Initiated or UserInitiated in the SuspendResumeIndicator
parameter. It signals SUS messages through a SUSPEND_IND primitive. The same
behavior applies to the RES message that HP OpenCall SS7 ISUP issues to the
application through a RESUME_IND primitive.
In both cases, an AdditionnalInfo field indicating FROM_NETWORK or FROM_USER,
depending on the originator of the message, is associated with the primitive.
HP OpenCall SS7 ISUP accepts both SUSPEND_REQ and RESUME_REQ primitives
with associated messages coming from the application.

Chapter 19

689

ISUP Call Control - Procedures Specific to ITU-T


Suspend/Resume
Figure 19-11

690

Suspend/Resume - Outgoing Call

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Suspend/Resume

Suspend/Resume - T2 Expiry
When T2 timer expires, HP OpenCall SS7 ISUP activates a release procedure by
sending START_RELEASE_IND to the application, indicating T2_TIMEOUT. This
applies for both outgoing or incoming calls.
Figure 19-12

Chapter 19

Suspend/Resume - T6 Timeout

691

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR

Continuity Check Request with IAM or CCR


The Continuity Check is a procedure for checking a circuit. It can be requested,
when supported by the selected flavor, in an IAM, a CCR or a CRM message. The
following sections describe a number of Continuity scenarios.

Continuity Check on this Circuit


A Continuity Check is performed on the current circuit if the continuity check
indicator in the IAM message is set to Continuity Check required on this circuit.
Successful Continuity Check
The outgoing side sends a Continuity message with a successful indication after a
correct check of the transmission path (a loop is required on the incoming side, a
tone is sent from the outgoing side and is returned in time).

NOTE

692

The CONNECT_LOOP_IND primitive and the SETUP_IND primitive are handled in


parallel by HP OpenCall SS7 ISUP. Therefore, depending on the behavior of the
application, the order of primitives described in the diagram below can change.
CONNECT_LOOP_IND and DISABLE_ECHO_IND will always be issued to the
application sequentially (after corresponding ACKs are sent back by the application).

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Figure 19-13

Chapter 19

Continuity Check - Outgoing Side

693

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Figure 19-14

Continuity Check - Incoming Side

When selecting the ITU97 flavor for HP OpenCall SS7 ISUP, it is possible that the
SETUP_IND primitive is received AFTER the DISABLE_ECHO_IND primitive by
the application, if the IAM message is segmented and the SGM message is not
received.

694

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Continuity Recheck
If the continuity recheck procedure is a success, only the outgoing side sends a REL
message to finish the procedure.

Chapter 19

695

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Figure 19-15

696

Continuity Recheck - Outgoing Side

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR

Chapter 19

697

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Figure 19-16

698

Continuity Recheck - Incoming Side

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR

After a failed continuity check, a re-check is done automatically as depicted in the


next section.
Continuity Recheck - T24 Expiry at Outgoing Side
If the T24 timer expires during the continuity recheck phase, either activated after a
continuity failure during call setup, or after an explicit continuity recheck request,
the following occurs.
On the outgoing side, a COT indicating failure is issued to the network, and a
MAINTENANCE_SYSTEM_IND primitive indicating T24_TIMEOUT is issued to the
application after the SECOND continuity failure (including the eventual call setup
continuity failure). The T26 timer is started to restart a continuity recheck phase at
its expiry.

Chapter 19

699

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Figure 19-17

700

Continuity Recheck - Outgoing Side - T24 Expiry

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR

Chapter 19

701

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR
Figure 19-18

702

Continuity Recheck - Incoming Side - COT Failure

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Continuity Check Request with IAM or CCR

Chapter 19

703

ISUP Call Control - Procedures Specific to ITU-T


Facility Request, Facility Accepted, Facility Reject Messages

Facility Request, Facility Accepted, Facility Reject


Messages
Based on three messages, FAR, FAA and FRJ, this procedure allows the application
to invoke a facility (an operation) towards the other side. This invocation can be
accepted or rejected. These procedures are accessible only for flavors supporting the
corresponding messages.

Facility Exchange - Success


A facility can be invoked only after the setup procedure, once the call is established
(ICC Answered, OGC Answered). In this example, the application accepts the
invocation.
Figure 19-19

704

Facility Exchange - Success

Chapter 19

ISUP Call Control - Procedures Specific to ITU-T


Facility Request, Facility Accepted, Facility Reject Messages

Facility Exchange - Failure


The second example shows how the application can refuse the invocation by using a
FACILITY_REJECT_REQ primitive and the FRJ message.
Figure 19-20

Chapter 19

Facility Exchange - Failure

705

ISUP Call Control - Procedures Specific to ITU-T


Facility Request, Facility Accepted, Facility Reject Messages

706

Chapter 19

20

ISUP Circuit Maintenance Procedures Specific to ITU-T


This chapter describes circuit maintenance procedures that are specific to ITU-T.

Chapter 20

707

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Overview

Overview
The circuit maintenance processes described in this chapter include:

708

circuit blocking and unblocking

circuit group blocking and unblocking

circuit group query

circuit validation

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Blocking/Unblocking from a Network

Circuit Blocking/Unblocking from a Network


The blocking and unblocking mechanisms allow traffic to be removed from, and
then returned to, specific circuits.

Circuit Blocking from a Network - Normal Case


In this case, the circuit is put in the xxx_MN_REMOTELY_BLOCKED state.
Figure 20-1

Chapter 20

Circuit Blocking from Network - Normal Case

709

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Blocking/Unblocking from a Network

Circuit Blocking from User - Normal Case


In this case, the circuit is put in the xxx_MN_LOCALLY_BLOCKED state.
Figure 20-2

710

Circuit Blocking from User - Normal Case

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Blocking/Unblocking from a Network

Circuit Unblocking from Network - Normal Case


In this case, the message only unblocks a maintenance-oriented blocked circuit.
Figure 20-3

Circuit Unblocking from Network - Normal Case

Circuit Unblocking from User - Normal Case


Figure 20-4

Circuit Unblocking from User - Normal Case

Circuit Unblocking from a Network on Reception of an IAM


A circuit which is remotely blocked (maintenance-oriented or hardware-oriented) is
automatically unblocked on reception of an IAM, not being a test call.
Chapter 20

711

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Blocking/Unblocking from a Network
The application is warned through a MAINTENANCE_SYSTEM_IND primitive
indicating MN_UNBLOCKING or HW_UNBLOCKING, depending on the state of the
circuit.
Figure 20-5

712

Circuit Unblocking on Reception of IAM

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Blocking/Unblocking from a Network

Circuit Blocking during Setup Procedure


The reception of a BLO during the setup procedure (wait_for_ACM state) triggers a
release of the circuit. The application is informed through a START_RELEASE_IND
primitive indicating BLOCKING. On reply with a START_RELEASE_IND_ACK, the
REL message is sent to the network, and a RELEASE_CONF primitive is issued to the
application by HP OpenCall SS7 ISUP on receipt of the RLC message.
Figure 20-6

Chapter 20

Circuit Blocking during Call Setup

713

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Circuit Group Blocking/Unblocking


ITU-T based HP OpenCall SS7 ISUP handles both types of Group Blocking
messages:

Group Blocking for maintenance reasons

Group Blocking for hardware reasons

Group Blocking (Maintenance Oriented)


- From Network - Normal Case
In this scenario, a CGB message is received from the network. The message specifies
that maintenance group blocking should be performed. Consequently,
HP OpenCall SS7 ISUP:

NOTE

714

issues a GROUP_BLOCKING_IND primitive

issues a MAINTENANCE_SYSTEM_IND primitive indicating


MN_GROUP_BLOCKING

upon receipt of a GROUP_BLOCKING_RESP primitive, sends back the


acknowledgment message CGBA

marks all circuits as maintenance remotely blocked

For ITU97 mode, the MAINTENANCE_SYSTEM_IND indication is received prior to


the GROUP_BLOCKING_IND indication.

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking
Figure 20-7

Chapter 20

Maintenance Group Blocking - Normal Case

715

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Group Blocking (Hardware Oriented) from Network Normal Case


In this scenario, a CGB is received from the network and the CGB is requesting a
Hardware oriented blocking operation. As a result, HP OpenCall SS7 ISUP:

issues a HW_GROUP_BLOCKING_IND primitive to the application

issues a MAINTENANCE_SYSTEM_IND indicating HW_GROUP_BLOCKING

waits for the HW_GROUP_BLOCKING_RESP from the application and sends a


CGBA message back to the network

marks all circuits as remotely blocked

NOTE

For ITU97 mode, the MAINTENANCE_SYSTEM_IND indication is received prior to


the GROUP_BLOCKING_IND indication.

Figure 20-8

Hardware-Oriented Group Blocking - Normal Case

716

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Group Blocking (Maintenance Oriented)


- From User - Normal Case
In this scenario, a maintenance GROUP_BLOCKING_REQ request is sent by the user.
Consequently, HP OpenCall SS7 ISUP:

sends the CGB message to the network

sends a MAINTENANCE_SYSTEM_IND (MN_GROUP_BLOCKING) to the


application

waits for the CGBA message and issues a GROUP_BLOCKING_CONF (CGBA)


primitive to the application

marks all circuits as MN_LOCALLY_BLOCKED

The rangeAndStatus parameter is interpreted in the same way as for the CGB
message.

NOTE

A RELEASE_IND caused by a HW_GROUP_BLOCKING does not need a


RELEASE_RESP.

Figure 20-9

Group Blocking from User - Normal Case

Chapter 20

717

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Group Blocking (Hardware Oriented)


- From User - Normal Case
In this scenario, a hardware HW_GROUP_BLOCKING_REQ request is sent by the user.
Consequently, HP OpenCall SS7 ISUP:

sends the CGB message to the network

waits for the CGBA message and issues a HW_GROUP_BLOCKING_CONF(CGBA)


primitive to the application

marks all circuits as hardware locally blocked

The rangeAndStatus parameter is interpreted in the same way as for the CGB
message.
Figure 20-10

718

Group Blocking from User - Normal Case

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Group Unblocking (Maintenance Oriented)


- From Network - Normal Case
In this scenario, a CGU is received from the network. As a result,
HP OpenCall SS7 ISUP:

informs the application using GROUP_UNBLOCKING_IND

waits for the GROUP_UNBLOCKING_RESP, and upon receipt of it, sends a CGUA
back to the network primitive to the application

marks each of the latter unblocked

A maintenance blocked condition can only be removed by a maintenance oriented


group unblocking message.
The rangeAndStatus parameter is interpreted in the same way as for the CGB
message.
Figure 20-11

Chapter 20

Group Unblocking from Network - Normal Case

719

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Group Unblocking (Hardware Oriented)


- From Network - Normal Case
In this scenario, a CGU requesting hardware oriented unblocking is received from the
network. As a result, HP OpenCall SS7 ISUP:

informs the application using HW_GROUP_UNBLOCKING_IND

waits for the HW_GROUP_UNBLOCKING_RESP, and upon receipt of it, sends a


CGUA back to the network primitive to the application

marks each of the latter unblocked

A hardware blocked condition can only be removed by a hardware oriented group


unblocking message.
The rangeAndStatus parameter is interpreted in the same way as for the CGB
message.
Figure 20-12

720

Group Unblocking from Network - Normal Case

Chapter 20

ISUP Circuit Maintenance - Procedures Specific to ITU-T


Circuit Group Blocking/Unblocking

Group Unblocking (Maintenance Oriented)


- From User - Normal Case
In this scenario, a GROUP_UNBLOCKING_REQ request is sent by the user.
Consequently, HP OpenCall SS7 ISUP:

Figure 20-13

Chapter 20

sends the CGU message associated with the primitive to the network

waits for the CGUA message from the network and issues a
GROUP_UNBLOCKING_CONF primitive to the application

marks all circuits locally unblocked

G