HP OpenCall SS7 Application Developer`s Guide

Transcription

HP OpenCall SS7 Platform
Application Developer’s Guide
For Release 3.2 on HP-UX IA-64
First Edition
Manufacturing Part Number: 5971-2583
E1203
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.2 on HP-UX IA-64, December 2003
Trademarks
The following are trademarks or registered trademarks of
Hewlett-Packard:
HP-UX
Hewlett-Packard Company
OpenCall Business Unit
38053 GRENOBLE Cedex 9
France
ii
Preface
1. Introduction to HP OpenCall SS7 APIs
HP OpenCall SS7 Developer’s 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PIC/AG (Plug-In Container/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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VPC Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compatibility with Earlier Releases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Levels of Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Libraries Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP, ISUP, and OA&M APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP and TCAP APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
....................................................................
42
42
43
44
44
44
45
46
46
46
47
47
47
47
48
49
50
50
52
52
53
53
53
53
54
54
54
55
55
56
56
iii
2. General System Guidelines
Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for System Predictability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for System Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimizing OS Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Techniques for Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Test and Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Platform and User Application Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Storing User Applications on an HP OpenCall SS7 Platform . . . . . . . . . . . . . . . . . . . .
Directory Structures Reserved for HP OpenCall SS7. . . . . . . . . . . . . . . . . . . . . . . . .
Owner and Access Rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
58
58
59
59
60
61
62
63
63
63
3. General API Guidelines
Accessing the SS7 Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interaction of Multiple APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using HP OpenCall SS7 Libraries with Kernel Threads . . . . . . . . . . . . . . . . . . . . . .
Using HP OpenCall SS7 with 64-bit HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
66
68
69
69
69
70
71
71
72
72
72
73
74
74
75
75
75
76
76
77
78
79
Inbound Path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outbound Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Visibility of a Switchover at Each Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3, ISUP, and TUP APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
On Top of an MTP3 Level 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
On Top of an M3UA Level 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examining Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
80
80
81
81
81
82
82
82
83
4. Using the Level 3 (MTP3/M3UA) API
General Description of the Level 3 (MTP3/M3UA) API . . . . . . . . . . . . . . . . . . . . . . . .
MTP Level 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP Level 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP Level 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3 User Adaptation (M3UA) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stream Control Transport Protocol (SCTP) Layer . . . . . . . . . . . . . . . . . . . . . . . . . . .
Features of MTP3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Application Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Network Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Traffic Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Link Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Route Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Combining Linksets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Use the MTP3 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3 Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving MSUs (Message Signaling Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending MSUs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating MTP3 Stack Connections with SS7_xifcreate() . . . . . . . . . . . . . . . . . . . . . . .
Scheduling MTP3 Stack Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7_ifselectmask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
86
86
86
87
87
89
89
89
89
90
90
90
90
91
91
91
91
92
92
92
92
93
95
95
v
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
SS7_ifcnxhandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
MTP3 Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Receiving MSUs with MTPL3_recv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Sending MSUs Using MTPL3_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Message Size Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
MTP-Based Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
M3UA-Based Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
M3UA-Based Platform Using MTP-as-Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
MTPL3_send Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Closing MTP3 Stack Connections with SS7_ifclose(). . . . . . . . . . . . . . . . . . . . . . . . . . 104
Tuning MTP3 IPC Buffers with SS7_ifctrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
MTP3 API Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Sending MSUs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Receiving MSUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
DPC Unavailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
DPC Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
DPC Congestion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
DPC Uncongested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Local MTP3 Unavailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Local MTP3 Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
MTP3/M3UA Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
MtpClient.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
MtpServer.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi
116
116
116
118
118
118
118
119
119
119
Subsystem Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Subsystem Status Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replicated Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Relay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Oriented Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection ID Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Failures and Connection Preservation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Addressing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiple Application Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 IPC Using SS7_ifctrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
119
119
120
120
120
121
121
121
122
125
126
126
126
130
130
130
130
130
131
131
131
131
132
134
134
134
135
137
138
140
140
149
150
153
154
155
vii
Forwarding a Connection Using SCCP_ctrl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Addressing and Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Incoming Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outgoing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Elements of SCCP Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Main Fields in SCCP Called and Calling Party Addresses . . . . . . . . . . . . . .
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
156
157
157
158
159
160
164
165
166
168
171
172
173
177
177
178
180
180
182
182
184
184
185
186
188
188
190
191
192
192
193
6. Using the TCAP API
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Chapter Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
viii
Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
197
197
198
198
198
200
201
201
202
202
202
203
203
204
204
205
206
206
207
207
208
210
212
214
215
216
216
216
216
216
217
217
217
217
217
ix
Create a Dialogue Primitive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
x
218
218
218
219
219
220
221
224
224
224
225
225
227
227
227
227
230
230
232
232
233
234
236
236
236
237
237
239
240
240
241
241
242
242
243
tcx_primitive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Primitive Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SCCP Service Quality Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Primitive Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
243
244
246
248
251
252
253
254
254
257
258
260
261
261
261
262
263
264
264
265
265
265
265
265
266
266
267
267
268
269
270
270
xi
TCX_control(): Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transaction Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TCAP Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TcapClient.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TcapServer.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building IN Message Sets Over the HP OpenCall SS7 TCAP API. . . . . . . . . . . . . . .
272
274
275
275
276
277
7. Using the TCAP Application Message Dispatcher
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling and Disabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Dispatching Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customer-Supplied Dispatching Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching Outgoing Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ITU and ANSI Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching Incoming TC-BEGIN and TC-UNI Messages. . . . . . . . . . . . . . . . . .
Dispatching Incoming TC-CONTINUE and TC-END Messages . . . . . . . . . . . . .
Distributing Incoming Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying Application Instances (TCAP Users) . . . . . . . . . . . . . . . . . . . . . . . . .
Applications Must Connect Using TCX_open() . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
At Application Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Roles of the Customer-Supplied Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Roles of the Customer-Supplied Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Round Robin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xii
280
280
281
281
282
282
283
283
283
284
284
285
285
285
286
286
286
286
286
287
287
288
288
288
288
288
289
289
Roles of Customer-Supplied Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uneven Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Roles of Customer-Supplied Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching on INAP Service Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Roles of Customer-Supplied Library Functions. . . . . . . . . . . . . . . . . . . . . . . . . . .
Dispatching Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calls to Functions in the Customer-Supplied Library . . . . . . . . . . . . . . . . . . . . . . . . .
Tracing and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETTL 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 Tutorial Programs . . . . . . . . . . . . . . . . . . . .
C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
289
290
290
290
290
291
291
292
294
297
297
297
297
298
298
299
299
299
301
301
302
303
303
303
304
304
304
305
306
306
306
8. PIC/AG - Introduction
Some Basic Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Purposes of the HP OpenCall PIC Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Ensuring HA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
xiii
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multi PCA_Clients Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Levels of Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Between User Plug-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Execution API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading and Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA Model (on HP OpenCall SS7). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transient States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Establishment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling/Disabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Switchover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Switchback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registry API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xiv
311
311
312
312
313
313
313
314
315
315
316
316
317
317
318
319
320
320
321
321
321
322
322
322
322
325
325
325
325
326
328
329
329
329
330
331
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PCA (Plug-In Communication API) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communication Setup and Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TimerLib API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PIC Pool of Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the User Plug-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting/Stopping the User Plug-In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Platform Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
331
331
332
333
333
334
334
335
335
337
338
338
338
339
339
339
340
340
340
341
341
342
342
342
343
9. PIC/AG - Using the PCA API
High Availability (HA) and the PCA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HA Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Enabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PCA Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-In Server and Client Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
346
346
347
347
348
348
352
353
353
xv
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACTIVE State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BROKEN State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REJECTED State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ZOMBIE State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Aborting a Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing Broken Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Automatic Closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Session Object 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xvi
354
355
355
355
357
357
359
359
359
360
361
361
362
362
364
364
364
364
365
366
366
366
367
367
367
368
369
369
370
370
371
373
373
375
376
376
Buffer Allocator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Principles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Principles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Profiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
378
380
380
380
381
382
382
382
382
383
10. PIC/AG - Using the PIC APIs
Structure of PIC APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-In Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Plugin Object Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Typical Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Errors During 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
386
389
389
389
390
390
390
391
391
394
395
395
395
396
397
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
400
402
402
402
403
404
405
xvii
SS7_ifselectmask() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7_ifcnxhandler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending MTP2 OA&M Requests using MTP2X_oamcmd() . . . . . . . . . . . . . . . . . . . . .
Receiving MTP2 OA&M Notifications using MTP2X_oamrecv() . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xviii
405
405
405
406
408
409
410
410
411
412
413
414
416
416
417
417
419
420
420
422
422
423
424
424
426
427
427
428
428
430
431
431
433
434
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() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing a TCAP OA&M Connection Using TCX_close() . . . . . . . . . . . . . . . . . . . . . . .
435
436
436
436
436
438
440
442
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Archive and Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SS7 Stack Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State-machine Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bypass Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP CIC-Based Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Platform Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inconsistent Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Instance Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AIG configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Incoming Message Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Circuit Owners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TDi Routing Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Messages from a Non-Assigned Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Management Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Application Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
444
445
446
446
447
448
448
448
448
449
450
451
451
451
452
452
452
453
454
456
456
456
456
456
457
458
xix
Application Disconnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dynamic Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Loopback Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Flow Control and Congestion Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
On-line 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restrictions Related to Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling Probe Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pre-select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Timeout Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
selectMask(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Select() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Post-select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
handler() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
doWork(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Activity Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Criteria for Choosing to Implement the Activity Object. . . . . . . . . . . . . . . . . . . . . .
If you do not use the Activity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
If you Implement the Activity Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to use the Activity Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Redefining the Activity Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xx
458
459
459
459
459
460
461
462
462
462
463
463
464
464
465
465
466
466
466
468
474
474
474
474
475
475
476
476
476
476
477
477
477
477
478
478
recvActivity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sendPossible() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cnxStatus(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages via Probe Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing and Destroying a Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
oamReceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reload Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Notifications Sent About Events in the ISUP Library . . . . . . . . . . . . . . . . . . . . .
oamStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Status Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Dynamic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
reload(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dump() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Tutorial Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using State-machine Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Bypass Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ISUP Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
479
479
479
481
482
482
482
484
484
484
484
489
491
494
494
496
497
497
498
499
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Message Class for Customized Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
502
503
504
504
505
506
523
524
528
529
529
530
530
531
xxi
Encoder/Decoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IsupMsg::getPDU() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IsupMsg::setPDU() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
532
532
533
533
534
535
535
535
536
536
536
537
537
538
539
541
543
544
544
545
546
548
549
550
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxii
552
553
554
555
555
555
555
556
557
558
IPC Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound Path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Waiting Indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Network Back-pressure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Outbound Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remaining Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Back-pressure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Circuit States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provided Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How HP OpenCall SS7 ISUP Tracks Circuit State Values . . . . . . . . . . . . . . . . . . .
Developing a Circuit Update Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Propagating States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Synchronizing States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Activating the Standby Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recovering States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
559
560
560
560
560
560
561
562
562
563
564
564
565
566
567
15. Introduction to ISUP Procedures
Supported Finite State Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Interaction Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inbound and Outbound Circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP3 Interaction Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local MPT-3 Status Indications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LPC States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State Transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remote DPC Status Indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DPC States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State Transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
570
573
573
574
574
574
575
578
578
578
581
583
585
586
588
589
590
591
591
xxiii
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. . . . . . . . . . . . . . . . . . . . . . . . .
Reassembly of Incoming Messages - Interacting with
Continuity Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Unrecognized Messages ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP . . . . . . . . . . . . . . . . . . . . . . . .
591
591
591
592
593
593
594
594
595
596
597
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 Setup Including ACM Message Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Setup Without ACM Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxiv
600
601
602
602
603
604
605
606
606
606
607
608
608
608
609
610
611
613
613
614
615
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Successful Continuity Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Failed Continuity Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on the Previous Circuit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Facility Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
616
616
617
618
620
620
621
622
623
623
625
625
627
627
628
628
629
630
630
630
630
633
634
17. ISUP Call Control - Procedures Specific to ANSI
Call Setup Without ACM Reception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abnormal Call Release - Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . .
636
637
637
639
641
641
643
643
644
644
645
xxv
Suspend/Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - Outgoing Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - Incoming Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exit Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exit Message - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Recheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Recheck - TCCR Expiry at Outgoing Side . . . . . . . . . . . . . . . . . . . . .
Continuity Recheck - T24 Expiry at Outgoing Side . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check Request with CRM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Failed Continuity Check and Recheck Procedure . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check on the Previous Circuit/
Not Required on this Circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
646
646
646
648
648
649
649
649
652
656
658
661
661
662
663
664
18. 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 CON Message for Outgoing Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the CON Message for Incoming Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the SAM Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the SAM Message for Outgoing Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of the SAM Message for Incoming Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxvi
666
666
667
667
667
668
669
669
670
670
671
673
673
675
675
676
676
Suspend/Resume - Outgoing Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspend/Resume - T2 Expiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Recheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Recheck - T24 Expiry at Outgoing Side . . . . . . . . . . . . . . . . . . . . . . .
Facility Request, Facility Accepted, Facility Reject Messages. . . . . . . . . . . . . . . . . . .
Facility Exchange - Success . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Facility Exchange - Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
677
678
680
680
680
684
688
693
693
694
19. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
696
697
697
697
698
698
699
699
701
701
702
704
705
706
706
708
708
709
719
xxvii
Circuit Validation from Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Circuit Validation from User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Circuit Validation from User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Circuit Validation from User - Test Failed - Two T_CVT Timeouts . . . . . . . . . . . 721
Circuit Validation from User - Test Failed -CVR Received Before Second T_CVT
Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
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)
Group Blocking (Hardware Oriented)
xxviii
724
725
725
726
727
727
728
729
730
730
732
733
734
735
736
737
738
739
740
Circuit Group Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query from the Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Query from Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Failure to Receive CQR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
741
741
742
742
742
A. ISUP Library Values
ANSI-based HP OpenCall SS7 ISUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
ITU-T - based HP OpenCall SS7 ISUP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conventions Used in Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Designing for System Predictability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optimizing OS Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Techniques for Performance Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System Test and Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Orientation Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Archive and Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
758
758
758
759
761
761
761
761
762
763
763
763
763
763
763
764
765
765
765
765
765
765
765
765
766
xxix
Using the Activity Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages via Probe Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Closing and Destroying a Probe Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Receiving Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
oamReceive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Dynamic Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exchanging Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 TUP Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
State Machine Mode Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bypass Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MTP Related Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP OpenCall SS7 TUP Message Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Encoding/Decoding TUP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessors for TUP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP User Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP Message Class Naming Convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP Message Module Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TUP Message Description (API). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rounding a Parameter Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Automated Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACR State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing HP OpenCall SS7 TUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Race Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Memory Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Object Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling IPC Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Congestion and Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPC Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Automatic Congestion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxx
766
766
766
766
766
767
767
768
768
768
768
768
779
779
779
783
783
784
785
786
787
787
789
798
799
801
801
802
802
802
802
802
802
803
803
803
Managing Circuit States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Available 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setup Request Locally Refused by HP OpenCall SS7 TUP . . . . . . . . . . . . . . . .
Setup Request - Dual Seizure Case 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setup Request - Dual Seizure Case 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setup - Failure to Receive ACM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setup Request - Failure to Receive ANN (or ANC) . . . . . . . . . . . . . . . . . . . . . . .
Setup Request - Unsuccessful Backward Setup Message . . . . . . . . . . . . . . . . . .
Incoming Call Setup with Immediate Release . . . . . . . . . . . . . . . . . . . . . . . . . . .
Successful Call Setup for Outgoing Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Successful Call Setup for Incoming Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of SAM and SAO Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Information Exchange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use of GRQ and GSM Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Continuity Check Request with IAM or CCR . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Re-answer Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Normal Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abnormal Call Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking/Unblocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
805
805
809
810
810
812
812
812
812
812
812
812
813
816
816
816
817
819
820
821
822
824
824
825
826
828
830
834
847
852
852
857
860
867
875
875
xxxi
Circuit Blocking From Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Blocking From User - Normal Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking From Network - Normal Case . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking From User - Normal Case . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Unblocking From Network - On Reception of IAM . . . . . . . . . . . . . . . . .
Circuit Blocking During the Setup Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Blocking/Unblocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Blocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Unblocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Circuit Group Blocking/Unblocking - Acknowledgment . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxxii
875
876
876
877
877
877
879
880
889
895
897
897
898
898
899
899
899
900
Preface
This guide contains guidelines for developing applications for
HP OpenCall SS7 platforms. It accompanies HP OpenCall SS7 3.2.
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
•
Examples of code that use the HP OpenCall SS7 APIs.
•
Using the TCAP Application Message Dispatcher.
•
Using the Application Guardian 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, manipulating, and exchanging standard ANSI and ITU-T
messages.
•
ISUP/TUP FSMs, interaction with the MTP layer, and segmentation
mechanisms.
xxxiii
•
ISUP/TUP call setup and call teardown procedures.
•
ISUP/TUP circuit maintenance processes.
•
Examples of code that use the HP OpenCall SS7 ISUP API objects
and methods.
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.
xxxiv
Chapter
Contents
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 (Plug-In
Container/Application Guardian).
Chapter 9, “PIC/AG - Using the
PCA API.”
Describes how to use the PCA API of the Application
Guardian.
Chapter 10, “PIC/AG - Using
the PIC APIs.”
Describes how to use the PIC APIs of the Application
Guardian.
Chapter 11, “Using the OA&M
API.”
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 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 various 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.
xxxv
Chapter
Contents
- Procedures Specific to ANSI.”
are specific to ANSI.
- Procedures Specific to ITU-T.”
are specific to ITU-T.
Chapter 19, “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.
Appendix B, “TUP Addendum.”
Describes HP OpenCall SS7 TUP. It describes the
differences between HP OpenCall SS7 TUP and
HP OpenCall SS7 ISUP.
xxxvi
Associated Documentation
The following documents are on the HP OpenCall SS7 CD-ROM:
Table 1
Documents on the HP OpenCall SS7 CD-ROM
Title
Contents
HP OpenCall SS7 Application
Developer’s 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
telecommunications network 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.
The guide contains information on the SS7 Monitor,
configuration files and the SNMP traps generated by the
platform.
HP OpenCall SS7
Troubleshooting Guide
Describes how to troubleshoot an HP OpenCall SS7
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 Welcome
Guide
Describes the main features of the platform.
HP OpenCall SS7 Software
Installation QuickStart Guide
This is the booklet that accompanies the
HP OpenCall SS7 3.2 CD-ROM. It contains a procedure
for installing HP OpenCall SS7 version 3.2 from scratch.
The procedure in this booklet applies if the platform has
never had HP OpenCall SS7 installed. If the platform
already has a version of HP OpenCall SS7 installed, you
should use the software installation procedure described
in the HP OpenCall SS7 Operations Guide.
xxxvii
The following document is available but are not on the HP OpenCall SS7
CD-ROM:
Table 2
Other Documents
Title
HP OpenCall SS7 Release Notes
xxxviii
Contents
This document contains release-specific
information. In particular, it gives details of the
HP OpenCall SS7 packages, the servers
supported, the OS versions supported and the
associated patches (if any).
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
xxxix
xl
1
Introduction to
HP OpenCall SS7 APIs
This chapter describes the APIs provided by HP OpenCall SS7. It also
includes a general description of the HP OpenCall SS7 stack versions.
Chapter 1
41
Introduction to HP OpenCall SS7 APIs
HP OpenCall SS7 Developer’s Environment
The HP OpenCall SS7 software is available as a runtime environment or
as a developer’s environment. The HP OpenCall SS7 developer’s
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
42
Development Platform
Chapter 1
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.
43
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
MTP-3/M3UA, SCCP, ISUP, TUP and TCAP APIs. In the case of
TCAP, the stack’s 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 user’s 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 user’s primary group must be ocadmin.
See also the group(4) and password(4) man pages.
44
Chapter 1
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
45
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.
46
Chapter 1
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
47
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.
48
Chapter 1
PIC/AG (Plug-In Container/Application Guardian)
PIC/AG (Plug-In Container/Application
Guardian)
By using the PIC/AG 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 PIC/AG, see the HP OpenCall SS7 Welcome Guide.
The PIC/AG has its own APIs.
These APIs are described in Appendix 9, “PIC/AG - Using the PCA
API,”and Chapter 10, “PIC/AG - Using the PIC APIs.”
Chapter 1
49
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 51 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.
50
Chapter 1
Alias Point Code
Figure 1-3
Chapter 1
Example of an Incoming Message for a Local Alias
51
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.
52
Chapter 1
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.
VPC 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/tutorial directory.
Chapter 1
53
Compatibility with Earlier Releases
Levels of Compatibility
Table 1-1, “Meaning of the Different Possible Levels of Compatibility,”
defines the different possible levels or elements of compatibility for an
application developed for HP OpenCall SS7 2.x and 3.1.
Table 1-1
Meaning of the Different Possible Levels of Compatibility
Level or Element
of Compatibility
Meaning
Binary
The application works with the two releases without compilation and
linking. Only an application restart is required.
Source
The source code is compatible.
It is not mandatory to modify the source code of the application.
It is mandatory to recompile and re-link the application with the
libraries of the newer release.
Makefile/Build
The makefile and other build commands are still valid in the newer
release.
Binary compatibility with earlier releases of HP OpenCall SS7 is
provided for some HP OpenCall SS7 APIs.
For a list of the HP OpenCall SS7 APIs and releases for which binary
compatibility is provided, see the HP OpenCall SS7 Release Notes.
Environment Variables
In cases where binary compatibility is provided, you must also set the
values of the following environment variables:
export HP_AIN_CONFIG_FILE=/etc/opt/OC/platform/global.conf
export HP_AIN_DEBUG_CONFIG=/etc/opt/OC/supportability/debug.conf
54
Chapter 1
Libraries Available
Table 1-2
API Library
API Libraries Available
32-bit
64-bit
Archive
Shared
Posix
Thread
TCAP
Yes
Yes
No
Yes
Yes
ISUP
Yes
No
No
Yes
Yes
SCCP
Yes
Yes
No
Yes
Yes
MTP3 / M3UA
Yes
Yes
No
Yes
Yes
OA&M
Yes
Yes
No
Yes
Yes
MTP, ISUP, and OA&M APIs
Table 1-3, “Compatibility Table for MTP, ISUP, and OA&M APIs,” shows
the actual compatibility levels for these APIs.
Table 1-3
Compatibility Table for MTP, ISUP, and OA&M APIs
Compatibility Element
Applications Compiled
with 2.x Libraries
with 3.x Libraries
Source
Yes
Yes
Makefile / build
No*
No*
Re-link (archive)
NA**
NA**
Binary (archive)
No
No
* Different linker command lines.
** No archive library.
Chapter 1
55
SCCP and TCAP APIs
Table 1-3, “Compatibility Table for MTP, ISUP, and OA&M APIs,” shows
the actual compatibility levels for the MTP and TCAP APIs.
Table 1-4
Compatibility Table for SCCP and TCAP APIs
Compatibility Element
with 2.x Libraries
with 3.x Libraries
Source
Yes
Yes
Makefile / build
No*
No*
Re-link (archive)
NA**
NA**
Binary (archive)
No***
No***
* Different linker command lines.
** No archive library.
*** PA binary emulation on IPF is not supported, only native executable.
56
Chapter 1
2
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
57
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.
58
Chapter 2
Optimizing OS Performance
The main causes of poor performance leading to unpredictable system
response are due to access contention of memory and CPU resources.
General Guidelines
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 62).
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 the
nice, rtprio or rtsched commands, as these commands are not
supported.
•
Make sure you have sufficient physical memory for all
HP OpenCall SS7 and application processes, and ensure that your
system has been sized appropriately (buffer sizes, kernel parameters,
etc.). For details, refer to the installation procedure in the
HP OpenCall SS7 Operations Guide.
•
Design and implement proactive overload handling mechanisms that
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.
59
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.
60
•
Minimize the number of process switches that you have implied in
the performance path.
•
Minimize the number of system calls in your code, especially the use
of select().
•
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
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”.
•
Chapter 2
No swapping should occur on the system.
61
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.
62
Chapter 2
Storing User Applications on an HP OpenCall SS7 Platform
Storing User Applications on an
HP OpenCall SS7 Platform
Directory Structures Reserved for HP OpenCall SS7
The following directory structures are reserved for HP OpenCall SS7:
•
/etc/opt/OC/
•
/opt/OC/
•
/var/opt/OC
•
/var/tmp/OC
HP recommends that only HP OpenCall SS7 files be stored in these
directory structures.
No user applications or files, other than configuration files, should be
stored in these directories and their sub-directories. Using these
directories for other files could cause configuration problems or incorrect
behavior of user applications.
In particular, no binaries should be placed in either the /opt/OC/lbin or
in the /opt/OC/bin sub-directories.
Owner and Access Rights
Do not modify the access rights or owner of files and sub-directories in
these reserved structures.
Chapter 2
63
Storing User Applications on an HP OpenCall SS7 Platform
64
Chapter 2
3
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
65
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).
66
Chapter 3
Figure 3-2
Chapter 3
Remote HP OpenCall SS7 Stack Access: Distributed Platform
67
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 72.
68
Chapter 3
Designing for Threads
Designing for Threads
HP-UX
The HP OpenCall SS7 APIs over HP-UX 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 HP-UX 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
HP-UX user manuals for more information about Posix.1c threads.
Using HP OpenCall SS7 Libraries with Kernel
Threads
To use the HP OpenCall SS7 APIs with kernel threads, you must change
the value of the stacksize parameter to hexadecimal 0x100000. You must
do this before creating any threads.
You can change the value of the stacksize parameter using Pthread
library functions as shown in the following example:
/* Change the stack size of the OpenCall kernel thread */
pthread_attr_init(&thread_attr);
stacksize= 0x100000;
pthread_attr_setstacksize(&thread_attr,stacksize);
printf("StackSize (new) = 0x%x %d \n", stacksize, stacksize);
For more details, see the HP-UX reference documentation.
Chapter 3
69
Using HP OpenCall SS7 with 64-bit HP-UX
Using HP OpenCall SS7 with 64-bit HP-UX
A list of libraries for developing C or C++ applications on 64-bit HP-UX is
provided in the Release Notes.
For more information on developing and compiling 64-bit applications,
refer to the cc and aCC man pages
The extended TCAP API, described in Chapter 6, Using the TCAP API, is
the only TCAP API supported with 64-bit HP-UX.
Stack connections for MTP and SCCP must always be created using the
SS7_xifcreate() command when using 64-bit HP-UX. The command
SS7_ifcreate() is not supported with 64-bit HP-UX.
70
Chapter 3
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.
Chapter 3
71
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.
72
Chapter 3
Masks
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.
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.
Chapter 3
73
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 APIs
When you are using multiple APIs in the application, you must only have
one 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.
74
Chapter 3
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.
Chapter 3
75
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.
76
Chapter 3
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.
Chapter 3
77
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.
For details about the specific IPC functions, see the following API
chapters.
78
Chapter 3
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
Chapter 3
Back-pressure
79
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 75, 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
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.
80
Chapter 3
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).
Engine mode (Active/Active) or compatible mode (Active/Hot-Standby). It
is also independent of whether the level 3 is MTP3 or M3UA.
Chapter 3
81
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.
The application should continue to process normally (by calling the
post-select handler function).
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.
Engine mode (Active/Active) or compatible mode (Active/Hot-Standby).
82
Chapter 3
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.
Chapter 3
83
84
Chapter 3
4
Using the Level 3 (MTP3/M3UA)
API
This chapter describes the Level 3 (MTP3/M3UA) API.
Chapter 4
85
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.
86
Chapter 4
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 platform). 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.
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.
87
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
88
Chapter 4
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 93 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
89
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.
90
Chapter 4
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 93.
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 95.
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 98 for a list and explanation of all MTP3
primitives.
Chapter 4
91
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 100.
Sending MSUs
MTPL3_send() sends MSUs to a remote destination.
See “Sending MSUs Using MTPL3_send” on page 102.
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 104.
Compiling and Linking
The MTP3 API is available as a shared library. To know the compile and
link directives to use, refer to the MTP3/M3UA API tutorial (see
“MTP3/M3UA Tutorial Programs” on page 112).
92
Chapter 4
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(). Only
SS7_xifcreate() supports 64-bit HP-UX and threads.
To enable multiple connections, you will also have to set some of the
following parameters using SAM:
Table 4-1
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
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
Chapter 4
YES
NO (default)
closeOnCreate
YES
NO (default)
93
Creating MTP3 Stack Connections with SS7_xifcreate()
NOTE
The parameters closeOnEnable, closeOnCreate, and autoSwitch can
be set for each layer and apply to the API that connects to that layer. For
example, setting closeOnCreate in SCCP means that applications
connecting directly to SCCP will be subject to closeOnCreate, while
applications connecting to MTP3/M3UA or TCAP will not be affected.
Only the values of the highest configured layer can be modified. This
means that when SCCP + TCAP have been configured, only the values
for TCAP can be modified, and those for MTP/M3UA and SCCP MUST
NOT be modified. If only SCCP has been configured as the upper layer,
the values for MTP/M3UA MUST NOT be modified.
NOTE
When a connection becomes secondary, MTPL3_recv() returns -1 with
ss7errno set to EAPIDISABLE even if the connection is closed afterwards.
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 */
}
94
Chapter 4
As described in “Scheduling SS7 Connections” on page 72 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().
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
95
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).
SS7_ifcnxhandler() man page.
Example 4-2
int
nfound;
/* select result */
int
num_cnx;
int
numFd;
int
cnx_active[MAX_FD];
fd_set
readMask;
/* mask for select */
fd_set
writeMask;
fd_set
exceptionMask /*mask for select*/
struct timeval
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 micoseconds,
* and wait for messages from the connection
*/
tmout.tv_sec = 0;
tmout.tv_usec = 200;
96
Chapter 4
/* Must set this each time round loop as selectmask call may change the
/* pointer time = &tmout;
/* Note: As we have no other fd’s open, the initial max fd (1st param)
* is 0. Also, we don’t 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
97
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.
98
Chapter 4
MTP3 Primitives
Figure 4-2
Chapter 4
MTP3 Primitives
99
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().
MTPL3_recv() man page.
Example 4-3
Receiving Messages from the MTP3 API
int
dpc;
/* destination point code */
inunsigned 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”);
100
Chapter 4
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
101
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.
Message Size Limits
MTP-Based Platform
In the case of an MTP-based platform, if the application sends messages
to MTP3 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.
M3UA-Based Platform
In the case of an M3UA-based platform, the message size limit is 4096
bytes for all flavors.
M3UA-Based Platform Using MTP-as-Backup
In the case of an M3UA-based platform using MTP-as-backup, the
message size limits are the same as those for an MTP-based platform.
MTPL3_send Command
MTPL3_send() man page.
Example 4-4
Sending MSUs via MTP3 API
fd_set writeMask, readMask, exceptionMask;
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*/
102
Chapter 4
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(&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 */
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
103
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 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.
SS7_ifclose() man page.
104
Chapter 4
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.
SS7_ifctrl() man page.
Chapter 4
105
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
106
Sending an MSU
Chapter 4
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
Chapter 4
Receiving an MSU
107
MTP3 API Behavior
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.
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.
108
Chapter 4
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
109
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
110
Receiving mtp_status_ind[dpc_uncongested] Primitive
Chapter 4
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
111
MTP3/M3UA Tutorial Programs
Two tutorials (that is, example programs) named MtpClient and
MtpServer are provided with HP OpenCall SS7.
The source code of these tutorials 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.
Before compiling, you must configure some parameters according to your
configuration. In particular, you have to use:
#define SIO
to define your service information octet according the values configured
in your network.
Then, you must compile the two programs using the command cc_mtp.
This compiles both programs at the same time.
Finally, you must run both programs at the same time on two separate
SS7 stacks.
MtpClient.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 MtpServer.
This program also manages the primary/secondary connection feature:
112
•
primary connection (-m primary) that handles traffic.
•
secondary connection (-m secondary) that does not handle traffic.
This can be switched to primary using a kill -s SIGUSR1
processId command. The primary connection is then deactivated
and becomes secondary.
Chapter 4
MtpServer.c
This program is the server process. It receives requests for phone
number resolution from the client MtpClient, 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.
This program also manages the primary/secondary connection feature:
Chapter 4
•
primary connection (-m primary) that handles traffic
•
secondary connection (-m secondary) that does not handle traffic.
This can be switched to primary using a kill -s SIGUSR1
processId command. The primary connection is then deactivated
and becomes secondary.
113
114
Chapter 4
5
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
115
Using the SCCP API
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
Preferred and
Primary/
Secondary
HP OpenCall SS7 complies to the ANSI standard for the Preferred/Next
Preferred functionality, as described in GR-82-CORE, Issue 1, June 1994,
Revision 3, 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.
116
Chapter 5
Using the SCCP API
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
117
Using the SCCP API
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 both connectionless services and
connection oriented services, as described below (note that these services
have some features in common, described in “Common Features” on
page 126).
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.
The following features are supported for connectionless services.
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.
118
Chapter 5
Using the SCCP API
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
119
Using the SCCP API
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:
•
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.
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
120
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.
Chapter 5
Using the SCCP API
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.
Connection Oriented Services
HP OpenCall SS7 provides the mechanism to establish a user-to-user
connection for the transfer of information blocks (Network Service Data
Unit - NSDU) from the SCCP layer of one SS7 stack to another. In this
case, NSDUs are transferred sequentially. HP OpenCall SS7 supports
Class 2 only, providing basic connection and disconnection services.
The following features are supported for connection oriented services.
Connection ID Management
The identification of SCCP connections is managed at two levels; at the
application level and at the SCCP layer of the SS7 stack.
When an SCCP connection is requested, the requesting application
associates a unique Local Reference Number, userLRN, with the
requested connection. This is a parameter of the connection request
primitive sccp_nconnect_req, but is only a reference for use by the
application.
The SCCP layer of the local SS7 stack then allocates its own Local
Reference Number to the connection, as does the SCCP layer of the
destination SS7 stack. This latter identifier becomes the real reference
for the connection, sccpLRN, that is used in network exchanges.
The destination application also allocates its own userLRN to the
connection but, again, this is only for local use by the application (it is a
parameter of the primitive sccp_nconnect_resp).
The detailed mechanism of connection ID management when a
connection is requested is illustrated in Figure 5-2 below.
Chapter 5
121
Using the SCCP API
Figure 5-2
Connection ID Management
Connection Forwarding
An application that handles connection oriented Class 2 services can
have one or all of its established connections forwarded to another
application that is bound to the same SSN. The destination application
will then deal with incoming and/or outgoing traffic associated with the
forwarded connection(s). The original application will no longer be able
to send or receive data on the forwarded connection(s).
Forwarded connections are requested using the function SCCP_ctrl().
The destination application must be specified, and whether one or all
connections are to be forwarded. If only a single connection is to be
forwarded, this connection must be identified by its sccpLRN identifier.
The forward, all or single, is started by notifying the destination
application by a sccp_connect_fwd_ind primitive, and is finished when
the original application receives the sccp_connect_fwd_conf primitive.
The mechanism of setting up connection forwarding is illustrated in
Figure 5-3 below.
122
Chapter 5
Using the SCCP API
While forwarding all connections, a new forward request on all
connections will be refused, and the error message SC_fwd_not_ready is
returned by the SCCP_ctr() function. However, a single connection
forward can be performed, even if a forward on all connections is ongoing.
If a switchover occurs while forwarding all connections, the forward will
continue on the new active SCCP stack.
For more details of using the SCCP_ctrl() function, refer to “Forwarding
a Connection Using SCCP_ctrl()” on page 156.
Chapter 5
123
Using the SCCP API
Figure 5-3
Connection Forwarding Set-up
DEFAULT: Application 1 handles all traffic on connection (sccpLRN=1)
AppId=1
SSN=10
AppId=2
SSN=10
3
sc c p _c o nne c t_ind
(sccpLRN=1) 2
sc c p _c o nne c t_re s
p
(sccpLRN=1)
SAP=1
SAP=2
SSN=10
SLRN=1
SCCP Layer
4
1
CR CC
CONNECTION TRANSFER: Traffic on connection (sccpLRN=1)
transferred to Application 2
AppId=1
SSN=10
AppId=2
SSN=10
sc c p _c o nne c t_fwd _c o nf
(appId=2, sccpLRN=1)
4
sc c p _c trl_c o nne c tio n_fwd _re
q
1
3
sc c p _c o nne c t_fwd _ind
SAP=1
sc c p _d a ta _ind
6 (sccpLRN=1)
SAP=2
SSN=10
2
SCCP Layer
SLRN=1
SLRN=1
5
DT1
124
Chapter 5
Using the SCCP API
Failures and Connection Preservation
There are two types of failure that can lead to connection problems failure of the SCCP layer of the SS7 stack and failure of an SCCP
application.
SCCP Layer
Failure
Failure of the SCCP protocol layer of the SS7 stack causes the
connections handled by this stack to be passed to the standby stack. This
assures the preservation of connections in the following states:
•
established connections
•
connections awaiting confirmation from the remote or upper
application before being established.
However, such a switchover will result in the loss of messages in the
internal buffers between the SCCP API and the SCCP protocol layer,
resulting in the loss of messages concerned with requests for connections
and disconnections, as well as data. Therefore connections may fail to be
properly established or released. However, built-in inactivity control and
timeouts ensure that orphan connections are released by the local or
remote SCCP layer.
SCCP Application
Failure
Provided that a (primary) SCCP application has a corresponding
secondary back-up application, the failure of the primary application will
cause all established connections handled by this application to pass to
the secondary. The latter application will subsequently have to deal with
data and disconnection notifications for connections that it does not
know, and will therefore have to re-build the contexts associated with
these connections.
If an application has no secondary back-up, failure of this application
will result in the SCCP protocol layer releasing all associated
connections.
Protocol Caveats
The SCCP class 2 protocol, as defined by ITU and ANSI, is not robust in
cases where SCCP notifies the upper application of a connection request
received from MTP3. If this incoming connection request is never
confirmed or refused by the upper application, the connection remains
blocked forever. HP OpenCall SCCP starts the TconnEst timer to cope
with this situation. If the TconnEst timer is elapsed before confirmation
is sent by upper application, the connection is locally released and the
upper application will receive a sccp_disconnect_ind primitive.
Chapter 5
125
Using the SCCP API
Common Features
The following features are common to connectionless services and
connection-oriented services.
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.
SCCP can accept multiple connections on the same SSN. One connection
is active and handles the traffic. A secondary standby connection 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.
Primary and
Secondary Pairs
The number of primary/secondary pairs supported depends on the SCCP
class and on whether an application identifier, applicationId, is
specified when the Service Access Point (SAP) is opened using the
function SS7_xifcreate().
If the applicationId field is not filled in (the default), only one
primary/secondary pair is allowed per SSN. If this field is filled in, the
allowed number of primary/secondary pairs depends on the SCCP class,
as follows:
•
Class 0, Class 2 and MGT class - up to 8 primary/secondary pairs
•
Class 1 - only 1 primary/secondary pair
Note that a separate, dedicated connection can be opened for SCCP MGT
(management) traffic.
126
Chapter 5
Using the SCCP API
Traffic Filtering
NOTE
In the case of multiple primary/secondary pairs, a filtering system can be
implemented to allow a particular connection/application to be dedicated
to handling traffic of a particular class. For connection oriented traffic,
the filtering allows some applications to be dedicated to incoming traffic
and others to be dedicated to outgoing traffic. An application can be
registered for any of the following types of traffic:
•
Connectionless Class 0 traffic
•
Connectionless Class 1 traffic
•
Connection oriented Class 2 incoming traffic
•
Connection oriented Class 2 outgoing traffic
•
Management traffic only
At least one application per SSN must have the management filter set,
so that the SSN is in service and can send/receive traffic.
A filter is selected through the function SS7_xifcreate() when opening
a Service Access Point (SAP). If no filter is specified (the default), the
application is registered for Class 0, Class 1 and management traffic.
For an illustration of SCCP traffic filtering, refer to Figure 5-4 below.
Chapter 5
127
Using the SCCP API
Figure 5-4
128
SCCP Traffic Filtering
Chapter 5
Using the SCCP API
Distribution of
Traffic
If more than one primary/secondary pair is registered to receive Class 0
or Class2 SCCP traffic, the traffic is distributed among these
applications on a round-robin basis. Note that to qualify for distributed
traffic, an application must have filled in the applicationId field in the
SS7_xifcreate() function when opening a Service Access Point (SAP).
If several applications have been registered to handle SCCP
management traffic, all of these applications will receive all incoming
management messages.
Chapter 5
129
Using 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 an SCCP stack connection using the
SS7_xifcreate() function. At this stage, you also specify the SCCP
traffic filtering that you require, through this function (see “Multiple
Application Connections” on page 126). See “Creating SCCP Stack
Connections Using SS7_xifcreate()” on page 132.
Scheduling SCCP Stack Connections
calls:
•
SS7_ifselectmask()
•
select()
•
SS7_ifcnxhandler()
See “Scheduling SCCP Stack Connections” on page 134.
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 137.
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 140.
130
Chapter 5
Using the SCCP API
Receiving SCCP Primitives
(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 150.
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, and Class 2 of the SCCP
connection oriented services. See “Sending SCCP Primitives Using
SCCP_send()” on page 153.
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 154.
Using the SCCP API Shared Library
The SCCP API is available as a shared library.
To know the compile and link directives to use, refer to the SCCP API
tutorial (see “SCCP Tutorial Programs” on page 192).
Chapter 5
131
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
If you...
...then set the
parameter...
autoSwitch
want the secondary connection to become active if
the primary fails
want the primary connection to be closed when
the secondary connection becomes active
secondary when a new primary connection is
created
132
NO
(default)
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
...to...
YES
NO
(default)
closeOnCreate
YES
NO
(default)
Chapter 5
Using the SCCP API
Creating SCCP Stack Connections Using SS7_xifcreate()
When creating connections using SS7_xifcreate(), you can also specify
the SCCP traffic filtering that you require (see “Multiple Application
Connections” on page 126). This is done through the
ss7_service_parms structure and the following (cumulative) modes can
be specified.
Table 5-2
SCCP Traffic Filtering Modes
Mode
Description
SCCP_CLASS0_ONLY
Connection only handles
connectionless Class 0 traffic.
SCCP_CLASS1_ONLY
Connection only handles
connectionless Class 1 traffic.
SCCP_CLASS2_INC_ONLY
Connection only handles connection
oriented Class 2 incoming traffic.
SCCP_CLASS2_OUT_ONLY
Connection only handles connection
oriented Class 2 outgoing traffic.
SCCP_MGT_ONLY
Connection only handles SCCP
management traffic.
For more details of this function, see the SS7_xifcreate() man page.
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;
/* open the SCCP service */
if (SS7_xifcreate (“Stack_1”,ss7_sccp,NULL,&sceparms,&cnxId,NULL) == -1)
/* error handling */
Chapter 5
133
Using the SCCP API
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
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().
select()
SS7_ifselectmask().
134
Chapter 5
Using the SCCP API
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).
resources.
•
a connection goes from busy state (API_BUSY) to normal state. The
return an error).
Example 5-2
ss7_service_parms
sceparms;
int
i, result;
fd_set
readMask, writeMask, exceptionMask; /* masks for select */
int
nfound;
/* select result */
struct timeval
int
numFd;
int
num_cnx, cnx_active[MAX_FD];
sceparms.ssn = client_ssn;
sceparms.mode = SCCP_ITU_WHITEBOOK
/* open the SCCP service */
FD_ZERO(&readMask);
FD_ZERO (&exceptionMask)
for (;;)
/* endless select loop
{
tmout.tv_sec = 1;
tmout.tv_usec = 1;
Chapter 5
135
Using the SCCP API
/* Must set this each time round loop as selectmask call
* may change the pointer
*/
time = &tmout;
pending_requests = 0;
// send a request
/* Note: As we have no other fd’s open, the initial max fd
* is 0. Also, we don’t use the exeception mask, so we pass 0.
*/
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),
*/
num_cnx = MAX_FD;
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
}
136
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-5,
SCCP Primitives, there are four categories.
Figure 5-5
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
137
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-3
SCCP Service Primitives (Connectionless Services)
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
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.
138
Chapter 5
Using the SCCP API
SCCP Primitives
Table 5-4
SCCP Service Primitives (Connection Oriented Services)
Type
Primitive Name
Associated Structure
Service
Request
sccp_connect_req
sccp_connect_parms
To request a connection to a
remote SCCP user.
sccp_disconnect_req
sccp_disconnect_parms
To request the release of a
connection to a remote SCCP
user.
sccp_data_req
sccp_data_parms
To request data to be sent to a
remote SCCP user.
Response
sccp_connect_resp
sccp_connect_parms
To accept a connection request
from a remote SCCP user.
Indication
sccp_connect_ind
sccp_connect_parms
To indicate that a connection
request has been received from
a remote SCCP user.
sccp_disconnect_ind
sccp_disconnect_parms
To indicate that a request for
the release of a connection has
been received from a remote
SCCP user.
sccp_data_ind
sccp_data_parms
To indicate that a request for
the transfer of data (to the local
user) has been received from a
remote SCCP user.
Confirmation
sccp_connect_conf
sccp_connect_parms
To confirm that a connection
request has been accepted by
the remote SCCP user.
Forward*
sccp_connect_fwd_ind
sccp_connect_fwd_ack_parms
To indicate that a forwarding
request has been received from
another application.
sccp_connect_fwd_conf
sccp_connect_fwd_ack_parms
To confirm that a forwarding
request has been accepted by
the SCCP layer.
*Service primitives (not protocol primitives) that can only be received (and not sent)
Chapter 5
139
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-5
SCCP Parameters and Values
SCCP
Parameter
Structure
Element
Type
Value
affectedDPC
-
-
BITS32
-
affectedSSN
-
-
OCTET
-
associatedPC
-
-
BITS32
-
140
Chapter 5
Using the SCCP API
SCCP Parameters
Table 5-5
SCCP Parameters and Values (Continued)
SCCP
Parameter
Structure
Element
Type
Value
callingAddres
s
SC_ADDRES
S
pointCod
ePresent
SC_PC_USAGE
SC_no,
SC_SCCPUse,
SC_MTPUse
pointCod
e
BITS32
-
ssnPrese
nt
ubool
-
ssn
OCTET
-
gt
-
pointer to a SC_GLOBAL_TITLEstructure or
NULL (no global title)
calledAddress
SC_GLOBAL
_ TITLE
Chapter 5
Following fields only used when gt contains a pointer
routeOnG
t
ubool
-
gtIndica
tor
SC_GT_INDICATO
R
SC_noGlobalTitle
SC_gtType1
SC_gtType2
SC_gtType3
SC_gtType4
translat
ion
SC_TRANSLATION
_TYPE
SC_unused
SC_internetwork_1
SC_networkSpecific_1
numberin
g
SC_NUMBERING_P
LAN
SC_unknownNumbering
SC_isdn
SC_userdata
SC_telex
SC_maritimeMobile
SC_landMobile
SC_isdnMobile
encoding
SC_ENCODING_SC
HEME
SC_unknownEncode
SC_bcdOdd
SC_bcdEven
nature
SC_ADDRESS_NAT
URE
SC_subscriberNo
SC_nationalNo
SC_internationalNo
digits
char*
-
141
Using the SCCP API
SCCP Parameters
Table 5-5
SCCP
Parameter
Structure
Element
Type
Value
coordStatus
-
-
SC_CONFIRM_STA
TUS
SC_granted_withdrawal
SC_denied_withdrawal
SC_no_peer
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
-
returnReason
-
-
SC_RETURN_REAS
ON
SC_noTranslationNature
SC_noTranslationSpecific
SC_subsystemCongestion
SC_subsystemFailure
SC_unequippedUser
SC_networkFailure
SC_networkCongestion
SC_unqualified
SC_errorInMsgTransport
SC_errorInLocalprocessing
SC_noDestReassembly
SC_sccpFailure
SC_hopCounterViolation
SC_segNotSupported
SC_segFailure
SC_invalidISNIrouting
SC_unauthorizedMsg
SC_msgIncompatibility
SC_noISNIconsRouting
SC_redundantISNIconsRouting
SC_noISNIidentification
SC_noError
unsigned int
24-bit
sccpLRN
142
Chapter 5
Using the SCCP API
SCCP Parameters
Table 5-5
SCCP
Parameter
Structure
Element
Type
Value
SegmOption
-
-
ubool
For future use. Should be set to 0, but no
error message is returned
sequenceContr
ol
-
-
int
-
serviceClass
SC_SERVIC
E_ CLASS
-
spStatus
-
-
SC_SP_STATUS
SC_inaccessible
SC_congestedSC_accessible
SC_restartingSC_congested
SC_cnx_error
XUDTOption
-
-
ubool
See Table Note 1
XUDTSOption
-
-
ubool
See Table Note 2
Table 5-6
SCCP_CLASS_0 = 0
SCCP_CLASS_1
SCCP_CLASS_2
SCCP Parameters and Values
SCCP
Parameter
Structure
Element
Type
Value
affectedDPC
-
-
BITS32
-
affectedSSN
-
-
OCTET
-
associatedPC
-
-
BITS32
-
Chapter 5
143
Using the SCCP API
SCCP Parameters
Table 5-6
SCCP
Parameter
Structure
Element
Type
Value
callingAddres
s
SC_ADDRES
S
pointCod
ePresent
SC_PC_USAGE
SC_no,
SC_SCCPUse,
SC_MTPUse
pointCod
e
BITS32
-
ssnPrese
nt
ubool
-
ssn
OCTET
-
gt
-
pointer to a SC_GLOBAL_TITLEstructure or
NULL (no global title)
calledAddress
SC_GLOBAL
_ TITLE
144
Following fields only used when gt contains a pointer
routeOnG
t
ubool
-
gtIndica
tor
SC_GT_INDICATO
R
SC_noGlobalTitle
SC_gtType1
SC_gtType2
SC_gtType3
SC_gtType4
translat
ion
SC_TRANSLATION
_TYPE
SC_unused
SC_internetwork_1
SC_networkSpecific_1
numberin
g
SC_NUMBERING_P
LAN
SC_unknownNumbering
SC_isdn
SC_userdata
SC_telex
SC_maritimeMobile
SC_landMobile
SC_isdnMobile
encoding
SC_ENCODING_SC
HEME
SC_unknownEncode
SC_bcdOdd
SC_bcdEven
nature
SC_ADDRESS_NAT
URE
SC_subscriberNo
SC_nationalNo
SC_internationalNo
digits
char*
-
Chapter 5
Using the SCCP API
SCCP Parameters
Table 5-6
SCCP
Parameter
Structure
Element
Type
Value
coordStatus
-
-
SC_CONFIRM_STA
TUS
SC_granted_withdrawal
SC_denied_withdrawal
SC_no_peer
hopCounter
-
-
unsigned char
Range: 1-15
Defaults to 15 if set outside range.
importance
-
-
InSequence
multInd
originator
Chapter 5
-
-
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.
SC_SMI
multIndUnknown
multIndSolitary
multIndDuplicated
SC_ORIGINATOR
SC_network_service_provider
SC_network_service_user
SC_undefined
145
Using the SCCP API
SCCP Parameters
Table 5-6
SCCP
Parameter
Structure
Element
reason
returnOption
146
-
-
Type
Value
SC_RELEASE_REA
SON
SC_disconnection_non_transient_nature
SC_disconnection_transient_nature
SC_disconnection_invalid_state
SC_disconnection_release_in_progress
SC_disconnection_normal_condition
SC_disconnection_abnormal_condition
SC_disconnection_end_user_congestion
SC_disconnection_end_user_failure
SC_disconnection_sccp_user_originated
SC_disconnection_access_congestion
SC_disconnection_access_failure
SC_disconnection_subsystem_congestion
SC_disconnection_subsystem_failure
SC_disconnection_network_congestion
SC_disconnection_network_failure
SC_disconnection_undefined
SC_refusal_dest_unknown
SC_refusal_dest_inacc_non_transient
SC_refusal_dest_inacc_transient
SC_refusal_qos_unavail_non_transient
SC_refusal_qos_unavail_transient
SC_refusal_reason_unspecified_non_tra
nsient
SC_refusal_reason_unspecified_transie
nt
SC_refusal_local_error
SC_refusal_invalid_state
SC_refusal_no_translation
SC_refusal_in_restart_phase
SC_refusal_non_transient
SC_refusal_transient
SC_refusal_NSDU_incompatible_info
SC_refusal_end_user_originated
SC_refusal_end_user_congestion
SC_refusal_end_user_failure
SC_refusal_sccp_user_originated
SC_refusal_access_congestion
SC_refusal_access_failure
SC_refusal_subsystem_congestion
SC_refusal_subsystem_failure
SC_refusal_hop_counter_violation
SC_reason_undefined
ubool
-
Chapter 5
Using the SCCP API
SCCP Parameters
Table 5-6
SCCP
Parameter
Structure
Element
Type
Value
returnReason
-
-
SC_RETURN_REAS
ON
SC_noTranslationNature
SC_noTranslationSpecific
SC_subsystemCongestion
SC_subsystemFailure
SC_unequippedUser
SC_networkFailure
SC_networkCongestion
SC_unqualified
SC_errorInMsgTransport
SC_errorInLocalprocessing
SC_noDestReassembly
SC_sccpFailure
SC_hopCounterViolation
SC_segNotSupported
SC_segFailure
SC_invalidISNIrouting
SC_unauthorizedMsg
SC_msgIncompatibility
SC_noISNIconsRouting
SC_redundantISNIconsRouting
SC_noISNIidentification
SC_noError
unsigned int
24-bit
sccpLRN
SegmOption
-
-
ubool
For future use. Should be set to 0, but no
error message is returned
sequenceContr
ol
-
-
int
-
serviceClass
SC_SERVIC
E_ CLASS
-
spStatus
-
-
SC_SP_STATUS
SC_inaccessible
SC_congestedSC_accessible
SC_restartingSC_congested
SC_cnx_error
XUDTOption
-
-
ubool
See Table Note 1
XUDTSOption
-
-
ubool
See Table Note 2
unsigned int
24-bit
userLRN
Chapter 5
SCCP_CLASS_0 = 0
SCCP_CLASS_1
SCCP_CLASS_2
147
Using the SCCP API
SCCP Parameters
Table 5-6
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.
148
Chapter 5
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-7
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.
Chapter 5
149
Using the SCCP API
Receiving SCCP Primitives Using SCCP_recv()
Receiving SCCP Primitives Using
SCCP_recv()
(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().
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 */
* 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;
150
Chapter 5
Using the SCCP API
dpc = not_parms_ptr->calledAddress.pointCode;
ssn = not_parms_ptr->calledAddress.SSN;
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:
Chapter 5
151
Using the SCCP API
state_parms_ptr = (sccp_state_parms *) data;
userstat = state_parms_ptr->userStatus;
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));
}
152
Chapter 5
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(), a
non-blocking function to send data to a remote destination. The data is
delivered differently for connectionless services or connection oriented
services, as described below.
NOTE
SCCP_send() man page.
Connectionless
Services
The function supports both Class 0 and Class 1 of the SCCP
connectionless services.
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.
Connection
Oriented Sevices
Chapter 5
The function supports Class 2 of the SCCP connection oriented services.
For connection oriented services, the protocol assures that all messages
on a connection use the same SLS and are delivered in sequence.
153
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 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.
154
Chapter 5
Using the SCCP API
Controlling IPC Using SS7_ifctrl()
Controlling IPC 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.
SS7_ifctrl() man page.
Chapter 5
155
Using the SCCP API
Forwarding a Connection Using SCCP_ctrl()
Forwarding a Connection Using SCCP_ctrl()
As described in “Connection Forwarding” on page 122, an application
that handles connection oriented Class 2 services can have one or all of
its established connections forwarded to another application that is
bound to the same SSN.
NOTE
Only established connections or connections waiting for confirmation can
be forwarded in this way.
An application can use the function SCCP_ctrl()to request to have
either one or all of its connections forwarded. Through this function, the
application must provide the following information:
•
The service type - SCCP_CTRL_CONNECTION_FWD.
•
The value of sccpLRN:
— If only one connection is to be forwarded, sccpLRN must be set to
the connection identifier.
— If all connections are to be forwarded, sccpLRN must be set to
ALL_SLRN.
•
The application identifier of the destination application, provided
through the destApplicationId field.
Once a forwarding request has been accepted, the requesting application
will receive a sccp_connect_fwd_conf primitive.
156
Chapter 5
Using the SCCP API
SCCP Addressing and Routing
SCCP Addressing
NOTE
For connection oriented services, an SCCP address is only required while
a connection is being established.
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:
Chapter 5
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.
157
Using the SCCP API
SC_PC_USAGE setting
Meaning
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
•
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.
158
Chapter 5
Using the SCCP API
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
NOTE
Chapter 5
For connection oriented services, if an address is used with no PC, no
SSN and no GT, the address will be absent from the SCCP message.
159
Using the SCCP API
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
Inbound traffic goes from the MTP layer to the SCCP layer.
Figure 5-6
Inbound Traffic
The numbers in the above diagram refer to the message transfer
flowcharts later in this chapter:
3 refers to Figure 5-13 on page 174.
Outbound
160
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.
Chapter 5
Using the SCCP API
Figure 5-7
Outbound Traffic
Chapter 5
161
Using the SCCP API
Loopback
Loopback traffic goes from the application to the SCCP layer to a local
application on the same system.
Figure 5-8
Loopback Traffic
Relay
162
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.
Chapter 5
Using the SCCP API
Figure 5-9
Relay Traffic
Chapter 5
163
Using the SCCP API
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 (SCCP management or
BSSAP user) that can be accessed via the SCCP.
•
Routing Indicator
This indicates whether routing is based on the SSN or on a GT.
164
Chapter 5
Using the SCCP API
The Main Fields in SCCP Called and Calling Party Addresses
The table below describes the main fields in the SCCP routing addresses.
Table 5-8
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)
Chapter 5
Boolean value
NAI value
TT value
NP value
...
165
Using the SCCP API
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.
166
Chapter 5
Using the SCCP API
Figure 5-10
Chapter 5
167
Using the SCCP API
Outgoing Routing Control
When the application requests the SCCP API to send an
sccp_xunitdata_req or sccp_connect_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.
168
Chapter 5
Using the SCCP API
Figure 5-11
Chapter 5
Message Transfer 1: TCAP or SCCP Application to SCCP Local
Bus
169
Using the SCCP API
Figure 5-12
170
Message Transfer 2: Remote Entity to MTP Layer
Chapter 5
Using the SCCP API
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 or sccp_connect_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 or sccp_connect_req primitive
must be sent to a remote SCCP user (SSN). The DPC is used by the
MTP3 to send a Connection Request (CR), 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
Chapter 5
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.
171
Using the SCCP API
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 or sccp_connect_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.
172
Chapter 5
Using the SCCP API
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.
Chapter 5
173
Using the SCCP API
Figure 5-13
174
Message Transfer 3: MTP layer to SCCP Local Bus
Chapter 5
Using the SCCP API
Figure 5-14
Chapter 5
Message Transfer 4: Local User Entity to SCCP Interface
175
Using the SCCP API
Figure 5-15
176
Message Transfer 5: SCCP to TCAP or an Application on SCCP
API
Chapter 5
Using the SCCP API
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 or sccp_connect_req
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 or sccp_connect_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 or sccp_connect_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).
Chapter 5
177
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-6, “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.
178
Chapter 5
Using the SCCP API
Return Option
Figure 5-16
Chapter 5
Returning an Undelivered Message
179
Using the SCCP API
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.
180
Chapter 5
Using the SCCP API
Figure 5-17
Chapter 5
Signaling Point Prohibited
181
Using the SCCP API
Signaling Point Allowed
HP OpenCall SS7 SCCP receives an mtp_resume_ind primitive from
MTP3 if a DPC becomes accessible again.
As shown in the figure below, the application is notified by an
sccp_pcstate_ind primitive.
Figure 5-18
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 the figure
below.
182
Chapter 5
Using the SCCP API
Figure 5-19
Chapter 5
Signaling Point Congestion
183
Using the SCCP API
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-20
184
Local Subsystem Out Service
Chapter 5
Using the SCCP API
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-21
Chapter 5
Local Subsystem In Service
185
Using the SCCP API
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.
186
Chapter 5
Using the SCCP API
Figure 5-22
Chapter 5
187
Using the SCCP API
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.
188
Chapter 5
Using the SCCP API
Figure 5-23
Chapter 5
Successful Withdrawal of a Replicated Subsystem
189
Using the SCCP API
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-24
190
Refused Withdrawal of a Replicated Subsystem
Chapter 5
Using the SCCP API
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-25
Chapter 5
Graceful Withdrawal of a Replicated Subsystem
191
Using the SCCP API
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
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=WAA, ABB, WBB or AAA).
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.
192
Chapter 5
Using the SCCP API
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.
Chapter 5
193
Using the SCCP API
194
Chapter 5
6
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
195
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
Since 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.2)
196
Function To Be Used
TC_close()
TCX_close()
TC_open()
TCX_open()
TC_recv()
TCX_recv()
Chapter 6
Using the TCAP API
Overview
Table 6-1
Obsolete API Functions (Continued)
Obsolete Function
(Not Supported in Release
3.2)
Function To Be Used
TC_select_mask()
TCX_select_mask()
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.
The TCAP API is available as a shared library.
To know the compile and link directives to use, refer to the TCAP API
tutorial (see “TCAP Tutorial Programs” on page 275).
Chapter 6
197
Using the TCAP API
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.
198
Chapter 6
Using the TCAP API
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
199
Using the TCAP API
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.
200
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
201
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.
202
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
203
Using the 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.”
204
Chapter 6
Using the TCAP API
Figure 6-4
Hybrid stack: Application Connection
General
Restriction - Use
of Global Title
The only restriction imposed on ITU-T White Book TCAP applications
using a 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
205
Using the 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.
206
Chapter 6
Using the TCAP API
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.
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 246.
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 SAM menu options Actions | View/Modify | Signalling
Protocols | SCCP.
Receive
Mechanism,
Buffering and Test
Message
To improve throughput the TCAP API stores incoming messages from
the SS7 stack 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 messages are received by the user one by
one with a TCX_recv() call. Because of this:
•
Chapter 6
The select() call (used in conjunction with TCX_select_mask) will
trigger only once for several TCAP messages grouped in the same
packet.
207
Using the TCAP API
•
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.
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.
208
Chapter 6
Using the TCAP API
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
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.
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.
Chapter 6
209
Using the TCAP API
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
A single TCAP user can establish multiple TCAP stack connections. Each
connection can be given identical or different SSN values.
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
210
Single TCAP User with Multiple TCAP Stack Connections
Chapter 6
Using the TCAP API
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.
Figure 6-8
Chapter 6
Multiple TCAP Users on the SS7 Stack
211
Using the 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 220.
212
Chapter 6
Using the 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.
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 SAM.
213
Using the 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
214
•
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.a (or libSS7util.sl) 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
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. Use SAM menu options
Actions | View/Modify | Signaling Protocols | TCAP. In the case of
multiple stacks, there is an extra step in which you select the stack
concerned. This step comes after the menu option Signaling Protocols
(you select the stack by its LPC, and then you click on the Signaling
Protocol Configuration option).
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
215
Using 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().
Scheduling TCAP Stack Connections
calls:
•
TCX_select_mask()
•
select()
•
TCX_cnx_handler()
See “Scheduling TCAP Stack Connections” on page 224.
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 227.
Continue on to “Using the Component Sublayer, for TC-users” on
page 217.
216
Chapter 6
Using 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 261.
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 232.
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 236.
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 230.
Chapter 6
217
Using the TCAP API
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.
See “Dialogue Handling” on page 243.
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 254.
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 241.
218
Chapter 6
Using 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 “Receiving Components from the Component Sublayer Using
TCX_recv()” on page 257.
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 260.
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 264.
Chapter 6
219
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 SAM:
Table 6-2
If you...
...then set the
parameter...
...to...
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
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
secondary when a new primary connection is created
YES
NO (default)
closeOnCreate
YES
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.
220
Chapter 6
Using the TCAP API
The parameters closeOnEnable, closeOnCreate, and autoSwitch can
be set for each layer and apply to the API that connects to that layer. For
example, setting closeOnCreate in SCCP means that applications
connecting directly to SCCP will be subject to closeOnCreate, while
applications connecting to MTP3/M3UA or TCAP will not be affected.
NOTE
Only the values of the highest configured layer can be modified. This
means that when SCCP + TCAP have been configured, only the values
for TCAP can be modified, and those for MTP/M3UA and SCCP MUST
NOT be modified. If only SCCP has been configured as the upper layer,
the values for MTP/M3UA MUST NOT be modified.
Example: Creating a TC-user Connection
This code fragment 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 */
Chapter 6
221
Using the TCAP API
/* 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 :
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
within the correct range (%d)”, tc_errno);
222
Chapter 6
Using the TCAP API
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 :
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 doesn’t
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
223
Using the TCAP API
As described in “Scheduling SS7 Connections” on page 72, 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().
TCX_select_mask() man page.
select()
TCX_select_mask() to indicate which sockets are to be used.
224
Chapter 6
Using the TCAP API
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.
occurs:
•
•
An L_cancel is generated by the API and must be extracted by the
receive function call.
•
resources.
•
return an error).
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(&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);
Chapter 6
225
Using the TCAP API
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);
}
}
/*
*
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
*/
{
more = 1; p_type = 0; prov_id = 0;
/* Receive all possible messages arrived */
..............
226
Chapter 6
Using the TCAP API
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 operation’s 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
227
Using the TCAP API
Figure 6-12
Invocation and Dialogue Handling
1
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.
2
A TCAP BEGIN message containing the invoke id w and the dialogue id z1 is sent to TC-USER3.
3
TC-USER3 receives an invocation component with invoke id w. TC-USER3 locally identifies its dialogue
with TC-USER1 with the dialogue id z2.
4
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.
228
Chapter 6
Using the TCAP API
5
A TCAP END message containing the result component and TC-USER1 dialogue id z1 is sent to
TC-USER1.
6
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.
7
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.
8
A TCAP BEGIN message containing the invoke id x and the local dialogue id y1 is sent to TC-USER2.
9
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-USER1‘s dialogue id y1 is sent to
TC-USER1.
12
TC-USER1 receives TC-USER2’s 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
229
Using the TCAP API
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.
230
Chapter 6
Using the TCAP API
Figure 6-13
Chapter 6
Storing the components within the TCAP library
231
Using the TCAP API
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.
232
Chapter 6
Using the TCAP API
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
ANSI
ITUT
TC_INVOKE
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
233
Using the TCAP API
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
Structure of ANSI and ITU-T Components
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
234
Chapter 6
Using the TCAP API
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
correlation_id
operation
optional - ITU-T only
parameter
optional
invoke_id
correlation_id
error
mandatory
parameter
optional
TC_U_CANCEL
invoke_id
TC_L_CANCEL
correlation_id
TC_U_REJECT
invoke_id
TC_L_REJECT
correlation_id
TC_R_REJECT
problem_code
mandatory
parameter
optional
TC_RESULT_NL
TC_U_ERROR
Chapter 6
235
Using the TCAP API
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 240.
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.
TCX_alloc_component() man page.
236
Chapter 6
Using the TCAP API
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.
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 239 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)
{
fprintf(stderr,“TCX_alloc_component
Error);
break;
ILLEGAL VALUE (error value == %d)”,
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)
Chapter 6
237
Using the TCAP API
else
{
Error = TCX_alloc_buffer(&Buffer, 1000); // We want a buffer of 1000 bytes
if (Error != 0)
{
switch(tc_errno)
{
fprintf(stderr,“TCX_alloc_component
%d)”,Error);
break;
ILLEGAL VALUE (error value ==
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
238
Chapter 6
Using the TCAP API
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
239
Using the TCAP API
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.
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.
TCX_control() man page.
240
Chapter 6
Using the TCAP API
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.
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 ()
241
Using the TCAP API
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.
242
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 244
service_quality
tcx_sccp_service_quality
See “SCCP Service Quality
Structure” on page 246
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 266.
provider_dialogue_id
unsigned int
This dialogue reference
identifier is provided by
TCAP. See “Dialogue
Chapter 6
243
Using the TCAP API
Dialogue Handling
Table 6-5
Structure of tcx_primitive (Continued)
Field
Type
Meaning
dialog_portion
tc_dialog_portion
See “dialogue_portion” on
page 251
tcx_primitive_option
See “TCX Primitive
Options” on page 253.
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.
✓
✓
244
Chapter 6
Using the TCAP API
Dialogue Handling
Table 6-6
Primitive Types (Continued)
Primitive Name
Meaning
ANSI
ITU-T
TC_QUERY_W_PERM
Starts a dialogue, informing the remote
TC-user that it can end the dialogue.
✓
-
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
245
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
246
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
247
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
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
user_dialogue_id
mandatory
mandatory
248
Chapter 6
Using the TCAP API
Dialogue Handling
Table 6-8
Structure of Dialogue Primitives (Continued)
Primitive Type
Parameters
TC_END
sce_quality
optional
TC_RESPONSE
d_address
optional - accepted but not used.
o_address
dialogue_portion
user_dialogue_id
mandatory
mandatory - absent in prearranged
end.
sce_quality
optional
d_address
o_address
user_dialogue_id
mandatory
mandatory
report_cause
mandatory
sce_quality
optional
d_address
o_address
dialogue_portion
user_dialogue_id
mandatory
mandatory - absent if following
TC_BEGIN
TC_NOTICE
TC_U_ABORT
u_abort_cause
mandatory
Chapter 6
249
Using the TCAP API
Dialogue Handling
Table 6-8
Structure of Dialogue Primitives (Continued)
Primitive Type
Parameters
TC_P_ABORT
sce_quality
optional
d_address
o_address
user_dialogue_id
mandatory
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
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.
250
Chapter 6
Using the TCAP API
Dialogue Handling
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.
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.
Chapter 6
251
Using the TCAP API
Dialogue Handling
Table 6-9
dialogue_portion Structure (Continued)
Field
Structure
Contents
Meaning
abort_reason
tc_abort_reason
AC_name_not_suppor
ted
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.
user_specific
Example: Creating a Dialogue Primitive
This example is a code fragment for creating a dialogue primitive.
/*Example of primitive creation*/
tcx_primitive Primitive;
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.
252
Chapter 6
Using the TCAP API
Dialogue Handling
TCX Primitive Options
This is a list of the tcx_primitive options.
Table 6-10
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
253
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_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 :
254
Chapter 6
Using the TCAP API
case TCE_INTERNAL :
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]);
Chapter 6
255
Using the TCAP API
exit (-1);
}
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 );
}
}
256
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 220 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 224.
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 260.
TCX_recv() man page.
Chapter 6
257
Using the TCAP API
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(&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);
{
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 )
258
Chapter 6
Using the TCAP API
{
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
259
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.
TCX_get_components() man page.
260
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 220, 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
261
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.
TCX_send() man page.
262
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 224.
The TLX_recv() receives TCAP message from the network but does not
decode the components found in the received message.
Chapter 6
263
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.
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 */
}
}
264
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 230.
Retrieving Component Buffers
The application can retrieve a component buffer by using
TCX_get_component(). See “Extracting Components Using
TCX_get_component()” on page 260.
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
Chapter 6
265
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 243 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
266
TC Dialogue Example
Chapter 6
Using the TCAP API
Dialogue Management
Setting Dialogue ID Values
Since the provider_dialogue_id is allocated by TCAP, it may be
necessary to control its value. Using the SAM menu options Actions |
View/Modify | Signaling Protocols | TCAP, you can define the minimum
(setLowPId). In the case of multiple stacks, there is an extra step in
which you select the stack concerned. This step comes after the menu
option Signaling Protocols (you select the stack’s LPC and then you click
on the Signaling Protocol Configuration option)
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
267
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 266.
268
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
269
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 78, 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
int
Function
TCX_control
Parameters
(int
void
tc_control_c
tc_control_parms
cnxId,
* context,
command,
* parameters);
Comment
In 64-bit mode,
the context field
is an “int”, not a
“void”.
context
This parameter is not supported. Set its value to NULL. When compiling
in 64-bit mode in aCC, any warnings related to this parameter can be
ignored.
cnxId
This input parameter specifies which stack connection IPC buffers will
be modified.
270
Chapter 6
Using the TCAP API
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
271
Using the TCAP API
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 TC- or 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.
If TCX_control() is unsuccessful, the return value is -1 and tc_errno is
set to indicate the error.
272
Chapter 6
Using the TCAP API
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
273
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 SAM
menu options Actions | View/Modify | Signalling Protocols | TCAP. In
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.
274
Chapter 6
Using the TCAP API
TCAP Tutorial Programs
Two tutorials (that is, example programs) named TcapClient and
TcapServer are provided with HP OpenCall SS7.
The source code of these tutorials is in the /opt/OC/tutorials/SS7
directory.
CAUTION
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.
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
Chapter 6
275
Using the TCAP API
For example, to run TcapClient on the client using SSN 40, enter:
TcapClient 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.
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 SS7_Stack_35 35 36 40 40
276
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
277
Using the TCAP API
Building IN Message Sets Over the HP OpenCall SS7 TCAP API
278
Chapter 6
7
Using the TCAP Application
Message Dispatcher
This chapter describes the TCAP Application Message Dispatcher.
Chapter 7
279
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 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
TC-QUERY-WITHOUT-PERMISSION
TC-CONTINUE
TC-CONVERSATION-WITH-PERMISSION
TC-CONVERSATION-WITHOUT-PERMISSION
TC-UNI
TC-UNI
Meaning
Message that begins a
transaction.
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
SAM. If enabled, a client supplied shared library named
TCAProuter.<className>.sl must be provided in the /opt/OC/lib
directory.
NOTE
280
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
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).
Chapter 7
281
Introduction
Figure 7-2 illustrates the role of a customer-supplied dispatching
algorithm.
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 application message dispatching 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 280).
282
Chapter 7
Introduction
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 282. 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.
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
Chapter 7
•
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.”).
283
Introduction
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().
One of the parameters of this function is a pointer to a structure of type
tcx_application_info containing an applicationID and an
instanceID.
284
Chapter 7
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 299.
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.
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
285
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.
286
Chapter 7
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
customer’s 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
287
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.
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 library’s internal dispatching table.
TCAProuter_application_activate() updates the library’s internal
dispatching table to allow dispatching to that application.
TCAProuter_application_deactivate() updates the library’s 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
288
Chapter 7
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.
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.
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.
dispatching table to allow dispatching to this application instance.
dispatching table to disallow dispatching to this application instance.
Chapter 7
289
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.
When an application starts up, it identifies itself to the stack, using its
Roles of Customer-Supplied Functions
The library’s 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 library’s internal dispatching table
loading the desired percentage values.
dispatching table to allow dispatching to that application instance, and
to adjust the current percentages to accommodate the number of
application instances currently alive.
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.
290
Chapter 7
Roles of Customer-Supplied Library Functions
The library’s internal dispatching table maps the INAP service key to
different application and instance IDs.
dispatching table to allow dispatching to this application instance.
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
291
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:
292
SSN1
uses the called number.
SSN2
uses random distribution.
SSN3
uses round robin.
SSN4
uses the current application workload.
Chapter 7
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 stack’s 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.
293
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-supplie
d 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
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
Update of
take account of the
is connected and
active.
294
Chapter 7
Table 7-2
Call Context
Context of Call to Customer-Supplied Functions (Continued)
Action at
Customer-supplie
d 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
Update of
take account of the
is no longer active.
Close of the last
active TC-user
connection
(applicationId,
instanceId) on that
SSN: call to the
TCX_close()
function
Update of
take account of the
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
295
Table 7-2
Call Context
Context of Call to Customer-Supplied Functions (Continued)
Action at
Customer-supplie
d 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
296
Chapter 7
Tracing and Logging
Tracing and Logging
NETTL Mechanism
The NETTL 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 NETTL 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
297
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]
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 ).
298
Chapter 7
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
•
For compatibility reasons with the HP OpenCall SS7 stack, the
shared library must be compiled in an HP-UX environment. The
shared library (once compiled) plus the stack will be executed on HPUX.
•
The dispatching library functions must be coded in C or C++.
•
If the TCAP Application Message Dispatcher is enabled, the library
file TCAProuter.<ClassName>.sl 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 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 customer’s
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().
Designing for Performance
Chapter 7
•
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 301), the customer-supplied library should make
no system calls.
299
300
•
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
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 application’s 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
301
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.
302
Chapter 7
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
303
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.
304
Chapter 7
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
305
TCAP Application Message Dispatcher Tutorial Programs
Tutorial Programs
Two tutorials (that is, example programs) are provided with
HP OpenCall SS7.
CAUTION
C
A C shared library performing round robin application dispatching is
available in the /opt/OC/tutorials/SS7 directory.
It contains:
•
TCAProuter.c
•
TCAProuter.h
This shared library can be compiled with the cc_TCAProuter script:
cc_TCAProuter
C++
A C++ shared library performing round robin application dispatching is
available in the /opt/OC/tutorials/SS7 directory.
It contains:
•
TCAProuter.cpp
•
TCAProuter.hpp
This shared library can be compiled with the cc_TCAProuter script
using the C++ option:
cc_TCAProuter -C++
306
Chapter 7
8
PIC/AG - Introduction
This chapter introduces the HP OpenCall PIC/AG facility.
Chapter 8
307
Some Basic Terms
Some Basic Terms
The following terms are used in this document:
aCC
ANSI C++ Compiler for HP-UX.
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.
308
FSM
Finite State Machine.
FTC
Fault Tolerant Controller. This is a component of the
HP OpenCall platform which provides fault tolerance.
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
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 HP’s
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 HP’s 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
309
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.
310
Chapter 8
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.
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.
311
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
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.
312
Chapter 8
The TimerLib API and the FTC are other components of HP OpenCall.
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 Platform Monitor, the ocftcontrol,
and ocftstatus commands.
Chapter 8
313
Summary of PIC Framework Features
Summary of PIC Framework Features
The HP OpenCall PIC Framework provides the following features:
314
•
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
User Plug-In Development
This section describes the Plug-In software from the user plug-in
developer’s 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:
Chapter 8
•
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 335).
•
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
315
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).
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 an HP-UX computer using the
aCC compiler with the options to generate 32-bit, single-threaded,
position independent code. The version of aCC must be at least 3.35 and
be compatible with STL V2 libraries. For more details about exception
management, see “Exception Handling” on page 342.
You can compile a simple user plug-in using the following command:
aCC MyPlugin.C -c -AA -int +p +z +DA1.1 -I.-I/opt/OC/include -o MyPlugin.o
where the +z option generates position independent code, and +DA1.1
generates 32-bit code.
The user plug-in must be linked as a shared library.
You can link a simple user plug-in using the following command:
aCC -z -b -AA -int -o MyPlugin.sl MyPlugin.o
where the -b option generates a shared library.
Development Environment
The user plug-in development environment allows the developer to build
user plug-in libraries and debug the user plug-in software.
316
Chapter 8
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
317
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).
318
Chapter 8
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 creator’s 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.
319
Exchanging Messages
•
inform the user plug-in when the other side has created a new
session.
•
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:
320
•
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.
Chapter 8
Exchanging Messages
Flow Control
Flow Control is performed at two levels: session level and message level.
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
321
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.”
322
Chapter 8
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
323
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.”
324
Chapter 8
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 HP-UX, there is a graphical interface to the FTC. This graphical
interface is known as the Platform Monitor or FT_monitor. Using this
graphical interface, you can display the process states and issue
commands to the processes. You can monitor and administer the HA
status of HP OpenCall processes using the Platform Monitor GUI, the
ocftcontrol command, and the ocftstatus command.
Chapter 8
325
HA API
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
Definition
FTC_ACTIVE
A process in this state is actively handling a functionality of
the platform.
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).”
326
Chapter 8
HA API
Figure 8-7
Chapter 8
HA FSM for PIC (on HP OpenCall SS7)
327
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.
328
Chapter 8
HA API
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.
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:
Chapter 8
329
HA API
•
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
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.
330
Chapter 8
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
331
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
332
PCA Classes (as Generally Used in a Plug-In)
Chapter 8
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.
Chapter 8
333
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.
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.
334
Chapter 8
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.
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.
The number of these timers is limited. The limit applies to the total
number of timers (the PIC’s own timers + the user plug-in timers). For
the limit, see the HP OpenCall SS7 Release Notes.
Chapter 8
335
TimerLib API
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 336 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.
336
Chapter 8
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:
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.
Chapter 8
337
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 the Platform Monitor
To start a user plug-in, you start the PIC using the Platform Monitor. In
turn, the PIC loads and starts the user plug-in.
To force a switchover, you also use the Platform Monitor.
To stop a user plug-in, you use the Platform Monitor to stop the PIC. In
turn, the PIC stops 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.
Using Command Lines
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.
338
Chapter 8
Product Environment
Product Environment
Hardware Requirements
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
339
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:
340
•
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
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
341
Exception Handling
Exception Handling
On HP-UX, the PIC and the user plug-in are compiled by the aCC
compiler and use STL V2 libraries.
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:
342
•
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
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
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
343
Plug-In Tutorial
344
Chapter 8
9
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
345
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.
346
Chapter 9
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.
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
347
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 385) for
scheduling and HA driving purposes.
For scheduling, see “Plug-In Scheduling” on page 391.
For HA, see “Plug-In HA Management” on page 395.
Object Model
The PCA has an object-oriented architecture. The object model of the
PCA is shown in Figure 9-2.
348
Chapter 9
PCA Description
Figure 9-2
Chapter 9
The PCA Object Model as Used in a Plug-In
349
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:
350
Chapter 9
PCA Description
Chapter 9
•
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 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 user’s 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
351
PCA Description
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.
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>.
352
Chapter 9
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 355 and
“Session Management” on page 361.
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 382.
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 361. 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.
353
Server Setup
•
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 378.
•
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 361 and
“Sending Messages” on page 380.
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 355.
NOTE
354
After a correct open operation on the Server, you must enable it before
sending traffic (that is, before session creation).
Chapter 9
Server Setup
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.
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.
Chapter 9
355
Server Setup
Client connection management can optionally be performed by
customizing the PCA_Server base class. Three virtual methods are
defined for this purpose:
•
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.
•
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.
356
Chapter 9
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 355 and
“Session Management” on page 361.
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
357
Client Setup
calling the PCA_Client::init() method, directly impacts inbound
flow control behavior. This is discussed in “Receiving Messages” on
page 382.
•
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 361. 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 378.
•
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 361 and
“Sending Messages” on page 380.
•
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.
358
Chapter 9
Client Setup
Client Opening
Once initialized, the PCA client must be opened, that is, it must try to
connect to its target server.
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
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 360.
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()
359
Client Setup
•
PCA_Client::setCnxHighTransmitTime()
•
PCA_Client::setCnxEnableBuffering()
•
PCA_Client::setCnxRecvBufferSize()
•
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).
360
Chapter 9
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.
Chapter 9
361
Session Management
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.
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.”
362
Chapter 9
Session Management
Figure 9-3
Chapter 9
State Machine for a Session
363
Session Management
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.
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 370). This results in an error message being returned to
the sender (see “Messages” on page 373) 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 366 and
“Session Locking” on page 368). The session is then said to be a “zombie”
session.
364
Chapter 9
Session Management
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 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:
Chapter 9
365
Session Management
•
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 369
and “Client Session Flow Control” on page 370.
•
the maximum number of sessions allocated to the connection is
reached. See the section on session parametrization in “Client
Initialization” on page 357. 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 370.
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
366
Chapter 9
Session Management
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.
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.
Chapter 9
367
Session Management
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
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.
368
Chapter 9
Session Management
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:
•
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.
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.
Chapter 9
369
Session Management
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.
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.
370
Chapter 9
Session Management
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 357.
•
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 371).
When a session is rejected, an ERROR message is delivered to the sender
with the rejection cause (see “Messages” on page 373) 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.
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
Chapter 9
371
Session Management
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.
372
Chapter 9
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 370). 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 383. The
meaning of errorCode and errorText can be found in “Meaning of
errorCode and errorText Fields” on page 375.
Chapter 9
373
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 366).
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
374
Chapter 9
Messages
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.
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
Chapter 9
Meaning for User
Session closed
at peer
PCA_FAILURE
PCA_FAILURE
Default
Text
Value
memory
overflow
Result of:
PCA_sessionFactory->getLastErro
rText()
If you customize this method, the
associated string is under your
control. A default implementation is
available.
A session is
closed at local
side, but is
still open at
peer side
375
Messages
Table 9-1
Meaning of errorCode and errorText (Continued)
errorCode
errorText
PCA_NOT_ACTIVE
Default
Text
Value
Meaning for User
Peer is
disabled
PCA_ABORTED
Last parameter of:
PCA_Server::abortSession()
PCA_ABORTED
Last parameter of:
PCA_Client::abortSession()
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().
376
Chapter 9
Messages
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
•
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 373 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
377
Messages
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:
•
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.
378
Chapter 9
Messages
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
379
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 353
and “Client Initialization” on page 357). 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.
380
Chapter 9
Sending Messages
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.
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
381
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 353, or “Client Initialization” on page 357). 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.
382
Chapter 9
Receiving Messages
Deletion destroys a message’s relation with its session (reference
counting), while the PCA_Message::reset() method keeps this relation
active. To re-define a message’s session, you use the
PCA_Message::putHeader() method.
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
383
Receiving Messages
384
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
385
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.
386
Chapter 10
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 389.
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 391.
Chapter 10
387
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.
388
Chapter 10
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.
Chapter 10
389
Plug-In Setup
Errors During Object Creation
If piSetup() function returns an error code (that is, user dependent), the
PIC just stops.
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.
390
Chapter 10
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
391
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:
392
Chapter 10
Plug-In Scheduling
EMPTY
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.
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
Chapter 10
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.
393
Plug-In 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 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.
394
Chapter 10
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 345). 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:
Chapter 10
395
PENDING
The HA FSM state will not terminate automatically.
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 391.
Below is an example showing the sequence of HA function calls that
drive the user plug-in HA FSM state at startup:
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.
FTC_STOPPING and the user plug-in returns SYNC.
FTC_COLD_STANDBY and the user plug-in returns DONE.
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().
FTC_HOT_STANDBY and the user plug-in returns DONE.
Step 9. The procedure continues from Step 1.
396
Chapter 10
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 352.
Chapter 10
397
398
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
399
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.
400
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
Chapter 11
ISUP
& TUP
APIs
SCCP
API
- Monitoring
TCAP
- Control
SCCP
MTP level 3
M3UA
MTP level 2
SCTP
MTP level 1
IP
401
Using the OA&M API
SS7 OA&M Services
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.
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.
402
Chapter 11
Using the OA&M API
SS7 OA&M Services
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
Chapter 11
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.
403
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.
SS7_xifcreate() man page.
404
Chapter 11
Using the OA&M API
Scheduling MTP and SCCP OA&M Connections
Scheduling MTP and SCCP OA&M
Connections
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().
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.
Chapter 11
405
Using the OA&M API
occurs:
•
•
resources.
•
return an error).
Examples
Example 11-1
#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
for (count=0;;count++)
{
tmout.tv_sec = 1;
tmout.tv_usec = 0;
time = &tmout;
FD_ZERO(&readMask);
FD_ZERO (&exceptionMask);
numFd = SS7_ifselectmask(0,
&readMask,
&writeMask,
&exceptionMask,
&time);
406
Chapter 11
Using the OA&M API
nfound =select(numFd,
&readMask,
&writeMask,
&exceptionMask,
time);
num_cnx = MAX_FD;
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++;
}
Chapter 11
407
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.
MTP2X_oamcmd() man page.
408
Chapter 11
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 select(2) man pages) and
SS7_ifcnxhandler.
MTP2X_oamrecv() man page. This man page also contains an example.
Chapter 11
409
Using the OA&M API
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 entity’s address and attributes.
Figure 11-2
410
MTP3 Entities in a Containment Tree
Chapter 11
Using the OA&M API
Static Entities
Static entities, such as the MTP3 entity itself, cannot be deleted.
Attributes Set
When an Entity is
Created
The address of an entity must be set when the entity is created. For some
entities the 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
Chapter 11
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.
411
Using the OA&M API
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.
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
412
•
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.
Chapter 11
Using the OA&M API
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)
Chapter 11
Primary/Secondary
Link number
(SLC)
413
Using the OA&M API
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
out_of_service
No active links.
congested
At least one congested link.
normal
Active, ready for traffic.
inactive
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
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
414
Chapter 11
Using the OA&M API
Table 11-3
MTP3 OA&M States (Continued)
Entity
State
Meaning
route
normal
Available for traffic.
inactive
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
Chapter 11
415
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
416
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 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.
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
Chapter 11
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
417
Using the OA&M API
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
418
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
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Chapter 11
Using the OA&M API
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:
Command
successful
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
Command failed
Chapter 11
419
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.
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:
•
— a notification.
•
If the command could not be executed, (for example if you try to add
— An MTPOamNotifStruct of type error. The failure_cause field
420
Chapter 11
Using the OA&M API
Receiving MTP3 OA&M Command and Statistic Notifications Using MTPL3_oamrecv()
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.
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
Command failed
Chapter 11
421
Using the OA&M API
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
422
SCCP Entities in a Containment Tree
Chapter 11
Using the OA&M API
Static Entity
Static entities, such as the SCCP entity itself, cannot be deleted.
Attributes Set
When Entity is
Created
The address of an entity must be set when the entity is created. For some
entities the 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.
Failed
Destination
Chapter 11
SO_FAILED_DEST
This entity is responsible for internally
collecting messages that do not have a valid
destination. It is unused.
423
Using the OA&M API
Rules for Creating and Manipulating SCCP Entities
•
The LPC value of the MTPL3 entity must be set before starting to
create any SCCP entities.
•
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
424
digit_pr_ssn priority
Chapter 11
Using the OA&M API
Translator Id
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
2
SC_unused
3 (MSB)
SC_unknownNumbering
SC_isdn
SC_userdata
SC_telex
SC_maritimeMobile
SC_landMobile
SC_isdnMobile
NULL
(NAI)
Translation Type
(TT)
Numbering Plan
(NP)
Chapter 11
425
Using the OA&M API
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
SO_REMOTE_SP
426
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.
SO_INSERVICE
Remote SP is accessible.
SO_OUTOFSERVICE
Remote SP is not
accessible.
SO_GT_TRANSLATOR
Not applicable
SO_FAILED_DEST
Not applicable
Chapter 11
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.
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
successful.
You must then use the command SCCP_oamrecv() to receive the
notification.
•
— A notification.
•
If the command could not be executed, for example if you try to add
— An sccp_notif whose failure field contains the reason why
the command could not be executed.
Command failed
Chapter 11
427
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.
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_VIRTUA
L_USER
SO_REMOTE
_SP
SO_REMOTE
_USER
SO_GT_
TRANSLATO
R
SO_FAILED
_DEST
immediate
immediate
immediate
immediate
immediate
-
-
periodic
periodic
periodic
periodic
periodic
SO_UDT_COU
NT_TX
immediate
immediate
immediate
immediate
immediate
-
-
periodic
periodic
periodic
periodic
periodic
SO_UDT_COU
NT_RX
immediate
immediate
immediate
immediate
immediate
immediate
immediate
periodic
periodic
periodic
periodic
periodic
periodic
periodic
SO_UDT_GAU
GE_TX
periodic
periodic
periodic
periodic
periodic
-
-
SO_STATE
428
Chapter 11
Using the OA&M API
Table 11-9
Statistics by Report Type (Continued)
Object Type
Statistic
SO_ SCCP
SO_LOCAL_
USER
SO_VIRTUA
L_USER
SO_REMOTE
_SP
SO_REMOTE
_USER
SO_GT_
TRANSLATO
R
SO_FAILED
_DEST
SO_UDT_GAU
GE_RX
periodic
periodic
periodic
periodic
periodic
periodic
periodic
SO_UDTS_CO
UNT_TX
immediate
immediate
immediate
immediate
immediate
-
-
periodic
periodic
periodic
periodic
periodic
SO_UDTS_CO
UNT_RX
immediate
immediate
immediate
immediate
immediate
-
immediate
periodic
periodic
periodic
periodic
periodic
SO_UDTS_GA
UGE_TX
periodic
periodic
periodic
periodic
periodic
-
-
SO_UDTS_GA
UGE_RX
periodic
periodic
periodic
periodic
periodic
-
periodic
SO_RTG_FAI
LURE_
COUNT
immediate
immediate
immediate
immediate
immediate
immediate
-
periodic
periodic
periodic
periodic
periodic
periodic
SO_RTG_FAI
LURE_
GAUGE
-
-
-
-
-
-
-
SO_TRANS_R
EQ_ GAUGE
-
-
-
-
-
-
-
NOTE
Chapter 11
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.
429
Using the OA&M API
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
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
430
Chapter 11
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.
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:
•
— A notification.
•
If the command could not be executed you receive:
Chapter 11
431
Using the OA&M API
Receiving SCCP OA&M Command and Statistic Notifications Using SCCP_oamrecv()
In response to a request for statistics:
•
If the command was executed correctly, you receive:
— An SO_EXECUTED notification to acknowledge the request.
corresponding to the statistic you requested.
•
If the command could not be executed you receive:
Command failed
432
Chapter 11
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.
Chapter 11
433
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.
434
Chapter 11
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.
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);
Chapter 11
435
Using the OA&M API
Scheduling TCAP OA&M Connections
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
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().
TCX_select_mask() man page.
select()
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:
436
•
•
An L_cancel is generated by the API and must be extracted by the
receive function call.
Chapter 11
Using the OA&M API
•
resources.
•
return an error).
TCX_cnx_handler() man page.
Example 11-3
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;
FD_ZERO(&readMask);
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 fd’s open, the initial max fd
/* is 0. Also, we don’t use the exeception mask, so we pass 0.
*/
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),
*/
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*/
}
Chapter 11
437
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().
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.
438
Chapter 11
Using the OA&M API
Requesting TCAP Statistics Using TCX_control()
Table 11-10
TCAP Statistic Types (Continued)
Command
Meaning
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.
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
}
Chapter 11
439
Using the OA&M API
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.
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;
440
Chapter 11
Using the OA&M API
} 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);
}
Chapter 11
441
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.
TCX_close() man page.
442
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
443
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 application’s 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.
An example program illustrating simple call setup and release is listed
in “ISUP Tutorial Programs” on page 497.
For all function signatures and object structures, refer to the man pages.
444
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.
Both the ANSI based and the ITU-T based versions of the
HP OpenCall SS7 ISUP software can be customized using the
HP OpenCall SS7 ISUP message set customization tool.
NOTE
Chapter 12
The IupTTC3, IupJJ90, and IsupPT message sets cannot be customized.
445
Using the ISUP API
ISUP Software Components
HP OpenCall SS7 ISUP contains both generic software
components—common to both the ANSI based and the ITU-T based
product versions—and version specific software components.
Figure 12-1
HP OpenCall SS7 ISUP Components
Generic Components
These components are independent of the software version. They include
446
Chapter 12
Using the ISUP API
•
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
447
Using the ISUP API
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
Error handling is not supported by the HP OpenCall SS7 ISUP API. 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.
448
Chapter 12
Using the ISUP API
Archive and Shared Libraries
The ISUP API is available both as an archive library and as a shared
library. See also “ISUP Makefiles” on page 499.
To know the compile and link directives to use for the archive and shared
libraries, refer to the ISUP API tutorial (see “ISUP Tutorial Programs”
on page 497).
Chapter 12
449
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
450
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
451
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 on page 454 for a sample configuration.
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 SAM online help
for details.
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.
452
Chapter 12
Using the ISUP API
Application Instance Group
Schematically, 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 on page 454 shows a sample configuration.
Chapter 12
453
Using the ISUP API
Figure 12-3
Several Primary ISUP Application Instances Connected to an
SS7 Stack via the TDi
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
application’s 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
454
Chapter 12
Using the ISUP API
be assigned simultaneously to several applications. This is done using
SAM (platform configuration tool). For more information on configuring
ISUP applications online, see the HP OpenCall SS7 Operations Guide.
NOTE
Chapter 12
An application’s 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.
455
Using the ISUP API
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 TDi’s 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
application’s 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.
456
Chapter 12
Using the ISUP API
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.
Chapter 12
457
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.
458
Chapter 12
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, use SAM. See the
SAM on-line help and the HP OpenCall SS7 Operations Guide for more
information.
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 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.
On-line Upgrade
Online upgrade is supported (but with current shared library
limitations).
Chapter 12
459
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:
460
•
IsupMgr
•
IsupProbe
•
IsupSMProbe/IsupBPProbe
Chapter 12
Using the ISUP API
API Structure
Figure 12-4
Object Model
The object model diagram was developed using the object model notation
described in Object-Oriented Development: The Fusion Method,
Prentice-Hall International, Englewood Cliffs, New Jersey, 1994
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.
Chapter 12
461
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.
462
Chapter 12
Using the ISUP API
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
//
//
//
//
//
//
//
//
Chapter 12
initialize_IsupMgr_object
if (initialize_IsupMgr_object != Ok) then
error handling
fi
create_Probe_object()
open_Probe_object()
schedule_Probe_object()
463
Using the ISUP API
Initializing the IsupMgr object
Initializing the IsupMgr object
The static method IsupMgr::init() 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
IsupMgr::init(), see the IsupMgr(3) man page.
Loading the Configuration File
IsupMgr::init() also 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 IsupMgr::init() 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
}
464
Chapter 12
Using the ISUP API
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 stack’s 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 477.
Chapter 12
465
Using the ISUP API
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.
open() method, see the IsupProbe(3) man page.
Primary and Secondary Connections
The API provides functionality that enables 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:
466
Chapter 12
Using the ISUP API
Figure 12-5
Chapter 12
Switching
467
Using the ISUP API
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.
468
Chapter 12
Using the ISUP API
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 93.
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()()
Chapter 12
469
Using the ISUP API
// 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
}
// 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
}
470
Chapter 12
Using the ISUP API
Example 12-3
Creating and Asynchronously Opening an IsupSMProbe Object
ISUP::OpenStatus
openStatus;
ISUP::CreateStatus
createStatus;
IsupSMProbe*
isupSMProbe;
IsupAdditional::Info*
indication;
IsupAdditional::NotifOpenCnx* notifOpenCnx = NULL;
HPAIN::Uint32
nbIndication;
IsupSMProbe::ActivityObject*
const activityObj = new ActivityObject();
char*
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
}
// open_Probe_object()
// if (open_Probe_object()!= Ok) then
//
close_Probe_object()
//
destroy_Probe
//
error handling
Chapter 12
471
Using the ISUP API
// fi
openStatus = isupSMProbe->open(ISUP::PRIMARY, HPAIN::bFalse);
if (! openStatus.isOk()){
cout << " isupSMProbe opening failure \n" << flush;
// 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;
472
Chapter 12
Using the ISUP API
// error recovery
}
else if( !notifOpenCnx->successful() )
{
cout << " isupSMProbe opening failure: negative Open Connection Notification \n" <<
flush;
// error recovery
}
Chapter 12
473
Using the ISUP API
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 API’s
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 HP-UX 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.
474
Chapter 12
Using the ISUP API
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().
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
475
Using the ISUP API
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().
IsupMgr::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
HP-UX 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.
476
Chapter 12
Using the ISUP API
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.
477
Using the ISUP API
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.
478
Chapter 12
Using the ISUP API
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.
Chapter 12
479
Using the ISUP API
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>;
listOfRecvToDo->put (recvToDo);
}
480
Chapter 12
Using the ISUP API
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
481
Using the ISUP API
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.
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.
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.
482
Chapter 12
Using the ISUP API
Example 12-6
ISUP::CloseStatus
ISUP::DestroyStatus
IsupSMProbe *
MyActivityObject *
Closing and Destroying an IsupSMProbe Object
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
}
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
483
Using the ISUP API
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.
484
Chapter 12
Using the ISUP API
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
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.
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.
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
the ANSI flavor.
For detailed description of the accessor return types, consult the
IsupAdditionalInfo.h file located in the /opt/OC/include/ISUP
directory.
Chapter 12
485
Using the ISUP API
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.
486
Chapter 12
Using the ISUP API
An example of implementation of the use of the
IsupMgr::oamReceive() function is available in the IsupServer
tutorials.
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
maxFd;
int
numFd;
fd_set
readMask;
fd_set
writeMask;
timeval
time;
timeval
* timeout;
timeval
delay0, delay1;
struct timezone
delayzone;
int
timediff=0;
int
L_TimeMax = TIME_MAX;
HPAIN::Uint32
L_nbIndication; // nb of messages to be read
char
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
timediff = CLK_diff ( &delay1, &delay0) / 1000000 ;
// if there is no more message to receive
Chapter 12
487
Using the ISUP API
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)
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 {
488
Chapter 12
Using the ISUP API
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
L_OamStatus; // status returned by receive cmd
HPAIN::Schedulable::Work
L_handler; // enum returned by handler
int
maxFd;
int
numFd;
fd_set
readMask;
fd_set
writeMask;
timeval
time;
timeval
* timeout;
timeval
delay0, delay1;
struct timezone
delayzone;
int
timediff=0;
int
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
// as long as the primitive expected is not received
while (timediff <= L_TimeMax) {
// elapsed time
Chapter 12
489
Using the ISUP API
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
490
Chapter 12
Using the ISUP API
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.
491
Using the ISUP API
Table 12-3
Probe Return Status Values (Continued)
Status
Class
CreateStatus
DestroyStat
us
492
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
error has occurred.
NO_ERROR
Probe/connection destroyed.
ALREADY_DESTROYED
Probe was previously destroyed.
Chapter 12
Using the ISUP API
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
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
error has occurred.
For information on return values related to creating and exchanging
messages, refer to the IsupMgr(3) man page.
Chapter 12
493
Using the ISUP API
Using Dynamic Configuration
Dynamic configuration enables you to modify the running ISUP. The
changes are allowed (any other changes will be refused by SAM):
•
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 through SAM,
then you can perform a reload to the ISUP library. You can perform this
reload using IsupMgr::reload().
The reload procedure is a three step operation:
1. Read the new configuration generated by SAM (in the file
/var/opt/OC/isup/isup.app<applicationId>.changes ).
2. Make all the changes.
3. Dump the new configuration in a temporary file (
/var/opt/OC/isup/isup.app<applicationId>.conf.dump).
You can also reload using the ss7IsupReload script delivered (see the
DynamicConfiguration man page). Using this script is the
recommended procedure, except in CIC-based distribution mode. You can
only perform one reload/dump operation at a time.
NOTE
494
Do not use the IsupMgr::reload method in CIC-based distribution
mode.
Chapter 12
Using the ISUP API
NOTE
Chapter 12
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 SAM. Otherwise, the ISUP
application does not reload the new configuration (it never receives the
SIGUSR1 signal from the ss7IsupReload script).
495
Using the ISUP API
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);
496
Chapter 12
Using the ISUP API
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: isupClientSMANSI,
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
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 Called show how to develop an application by using the
state-machine mode of access (IsupSMProbe) and its associated methods.
Chapter 12
Caller
isupClientSMANSI or isupClientSMITU
Called
isupServerSMANSI or isupServerSMITU
497
Using the ISUP API
Using Bypass Access
The Caller and Called show how to develop an application specifically
using the bypass access mode (IsupBPProbe) and its associated methods.
498
Caller
isupClientBPANSI or isupClientBPITU
Called
isupServerBPANSI or isupServerBPITU
Chapter 12
Using the ISUP API
ISUP Makefiles
ISUP Makefiles
The following makefiles are provided with HP OpenCall SS7 ISUP:
CAUTION
Chapter 12
•
/opt/OC/tutorials/ISUPMakefileANSI
•
/opt/OC/tutorials/ISUPMakefileITU
499
Using the ISUP API
ISUP Makefiles
500
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
501
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.
502
Chapter 13
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
503
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:
504
•
Chapter 15, Introduction to ISUP Procedures,
•
Chapter 16, “ISUP Call Control - Procedures Common to ANSI and
ITU-T,”
•
Chapter 17, “ISUP Call Control - Procedures Specific to ANSI,”
•
Chapter 18, “ISUP Call Control - Procedures Specific to ITU-T.”
Chapter 13
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:
Chapter 13
•
an attempt to create the message is refused with the
ISUP::SendStatus::INVALID_MESSAGE error status,
•
an attempt to send the primitive is refused with the
ISUP::SendStatus::ILLEGAL_PRIMITIVE error status.
505
State Machine Mode
ISUP SM Mode
Table 13-1 lists the ISUP primitives for ANSI in State Machine Mode.
Primitives for ANSI
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
506
Comments
This primitive is used
by the application to
signal that the
backward tone has
been checked
(Continuity-check
procedures).
Chapter 13
Table 13-1
ISUP Primitives for State Machine Mode - ANSI (Continued)
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
to ask the application
to connect its tone loop
(Continuity-check
procedures).
to connect its
transceiver
(Continuity-check
procedures).
to disable its echo
suppressor
(Continuity-check
procedures).
507
Table 13-1
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
508
Comments
to enable its echo
suppressor
(Continuity-check
procedures).
ask the ISUP library to
stop re-transmitting
REL/RSC/CGB/GRS
messages concerning a
circuit group to the
SS7 network.
Chapter 13
Table 13-1
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
USERDEF
for messages defined
using the customizing
facility.
ISUP_USR_MSG_IND
None
None
MAINTENANCE_SYSTEM_IND
None
Maintenance
System
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
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
509
Table 13-1
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
510
Comments
to remove its tone loop
(Continuity-check
procedures).
to remove its
transceiver
(Continuity-check
procedures).
Either an RLC message
or a Reset
(AdditionalInfo), but
not both.
to inform the
application that the
current call setup has
failed. For more
information, see the
AdditionalInfo
section.
Chapter 13
Table 13-1
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
to start checking the
backward tone
(Continuity-check
procedures).
to inform the
current call is being
released. For more
AdditionalInfo
section.
511
Table 13-1
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-Resu
me
SUSPEND_REQ
SUS
Comments
to inform the
associated circuit is
being reset. For more
AdditionalInfo
section.
to stop checking the
backward tone
(Continuity-check
procedures).
REL/RSC messages
concerning a circuit to
the SS7 network.
Suspend-Resu
me
TONE_DISAPPEARS_ACK
512
None
None
signal the
disappearance of the
backward tone.
Chapter 13
Table 13-1
Primitive
ISUP
Message
Additional
Info
UNBLOCKING_REQ
UBL
None
UNBLOCKING_RESP
UBL
None
UNBLOCKING_IND
UBA
None
UNBLOCKING_CONF
UBA
None
UNEQUIPPED_CIRCUIT_IND
UCIC
None
Chapter 13
Comments
513
ISUP SM Mode
Primitives for
ITU-T Flavors
Table 13-2 lists the ISUP primitives for ITU based flavors in State
Machine Mode.
For each primitive, Table 13-2 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-1 lists the equivalent information for ANSI.
Table 13-2
ISUP Primitives State Machine Mode - ITU Based Flavors
Primitive
ISUP
Message
Additional
Info
ACM
None
ACM
None
ALERT_REQ
ALT
None
ALERT_IND
ALT
None
APP_TRANSPORT_REQ
APM
None
APP_TRANSPORT_IND
APM
None
None
None
BLOCKING_REQ
BLO
None
BLOCKING_IND
BLO
None
BLOCKING_RESP
BLA
None
BLOCKING_CONF
BLA
None
514
Comments
This is supported in
TTC3 only.
TTC3 only.
Spr98 only.
Spr98only.
signal that the
backward tone has
been checked
(Continuity-check
procedures).
Chapter 13
Table 13-2
Primitive
ISUP
Message
Additional
Info
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
None
None
None
None
None
None
Chapter 13
Comments
TTC3 only.
TTC3 only.
Spr98 only.
Spr98only.
Spr98 only.
Spr98only.
to connect its tone loop
(Continuity-check
procedures).
to connect its
transceiver
(Continuity-check
procedures).
515
Table 13-2
Primitive
ISUP
Message
Additional
Info
CCR
None
None
None
None
None
COT
None
None
None
DISABLE_ECHO_IND
None
None
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
FACILITY_REQ
FAC
None
FACILITY_IND
FAC
None
FACILITY_REQUEST_REQ
FAR
None
FACILITY_REQUEST_IND
FAR
None
516
Comments
This is not supported
in TTC.
to disable its echo
suppressor
(Continuity-check
procedures).
to enable its echo
suppressor
(Continuity-check
procedures).
in TTC.
in TTC.
in ITU-88, and TTC.
in TTC.
Chapter 13
Table 13-2
Primitive
ISUP
Message
Additional
Info
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
CGU
None
CGU
None
None
None
CGUA
None
Chapter 13
Comments
REL/RSC/CGB/GRS
messages concerning a
circuit group to the
SS7 network.
517
Table 13-2
Primitive
ISUP
Message
Additional
Info
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
USERDE
F
None
ISUP_USR_MSG_IND
None
None
Comments
in TTC.
for messages defined
using the customizing
facility.
None
Maintenance
System
to inform the
maintenance system of
a particular event. For
more information, see
the AdditionalInfo
section.
NETWORK_RESOURCE_MGT_REQ
NRM
None
NETWORK_RESOURCE_MGT_IND
NRM
None
to send/receive the
NRM message used in
echo control
procedures. This is
supported in ITU-T
93/97, SSUR, and
Spr98 only.
518
Chapter 13
Table 13-2
Primitive
ISUP
Message
Additional
Info
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
None
None
None
None
Chapter 13
Comments
to send/receive any
ISUP message that is
already encoded as
part of a PAM (Pass
Along Message). This
is not supported in
TTC.
Spr98 only.
Spr98only.
TTC3 only.
TTC3 only.
to remove its tone loop
(Continuity-check
procedures).
to remove its
transceiver
(Continuity-check
procedures).
519
Table 13-2
Primitive
ISUP
Message
Additional
Info
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
520
Comments
Either an RLC message
or a Reset
(AdditionalInfo), but
not both.
to inform the
current call setup has
failed. For more
AdditionalInfo
section.
Chapter 13
Table 13-2
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
INF
None
INF
None
None
None
START_CHECK_TONE_IND_ACK
None
None
START_RELEASE_IND
None
StartRelease
None
None
START_RESET_IND
None
StartReset
LocalReset
START_RESET_IND_ACK
Chapter 13
None
None
Comments
in TTC.
to start checking the
backward tone
(Continuity-check
procedures).
to inform the
current call is being
released. For more
AdditionalInfo
section.
to inform the
associated circuit is
being reset. For more
AdditionalInfo
section.
521
Table 13-2
Primitive
ISUP
Message
Additional
Info
STOP_CHECK_TONE_IND
None
None
None
None
STOP_REQ
None
None
STOP_CONF
None
None
SUSPEND_IND
SUS
SUSPEND_REQ
SUS
Suspend-Resu
me
Comments
to stop checking the
backward tone
(Continuity-check
procedures).
REL/RSC messages
about a circuit to the
SS7 network.
Suspend-Resu
me
TONE_DISAPPEARS_ACK
None
None
UNBLOCKING_REQ
UBL
None
UNBLOCKING_RESP
UBL
None
UNBLOCKING_IND
UBA
None
UNBLOCKING_CONF
UBA
None
UCIC
None
522
signal the
backward tone.
Chapter 13
Table 13-2
Primitive
UNKNOWN_MESSAGE_REQ
UNKNOWN_MESSAGE_IND
ISUP
Message
Message
with
unknown
ISUP
type.
Additional
Info
None
Comments
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.
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
Send/receive any previously encoded ISUP message,
except for PAMs (Pass Along Messages).
ISUP_MSG_IND
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
Send/receive any previously encoded ISUP message,
except for PAMs (Pass Along Messages).
UNKNOWN_MSG_IND
Chapter 13
523
Table 13-3
ISUP Protocol Bypass Mode (Continued)
Primitive
Event
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.”
See also Table 12-2, “ISUP Receive Notifications,” on page 484.
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
524
Chapter 13
Table 13-4
Primitives Requiring Additional Information (Continued)
Primitives
SETUP_FAILURE_IND
Additional
Information
Field
SetupFailure
setupFailureCause
Used for:
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.
FROM_NETWORK
FROM_USER
START_RELEASE_IND
StartRelease
releaseCause
determining the reason for the release.
UNEXPECTED_RLC
T7_TIMEOUT
T33_TIMEOUT
T_CRA_TIMEOUT
BLOCKING
RELEASE_REQUEST
T8_TIMEOUT
T1_TIMEOUT
DCO_SUCCESS
STOP_REQ
T9_TIMEOUT
CONTINUITY_SUCCESS
T6_TIMEOUT
T2_TIMEOUT
Chapter 13
525
Table 13-4
Primitives
START_RESET_IND
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.
GROUP_RESET
526
Chapter 13
Table 13-4
Primitives
Additional
Information
MAINTENANCE_SYSTEM
_IND
Maintenance
System
Field
maintenance
SystemEvent
Used for:
defining the reason for the reset.
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
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
527
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
Primitive
528
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
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
529
Figure 13-2
Message Class Relationships
See also Figure 12-4, “Object Model.”
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.
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.
530
Chapter 13
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.
Figure 13-3
Chapter 13
Message Class/Metadata Relationship
531
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.
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.
532
Chapter 13
Loading a Set of Messages
Loading a Set of Messages
When the IsupMgr object is initialized with IsupMgr::init(), the
HP OpenCall SS7 ISUP configuration file is automatically loaded. This
file contains all the LPC, DPC and circuit information required for the
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.
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
Chapter 13
533
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);
534
Chapter 13
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
ITU Messages
CFN, COT, LPA, UCIC
CFN, COT, LPA, UCIC
Messages not supported.
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
Chapter 13
535
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.
536
Chapter 13
Accessors
Table 13-8
Specific Accessors
Type
Accessor
ISUP::ParmValue
accessorName
(read accessor)*
Arguments
(ISUP::MsgStatus& status) const;
accessorName denotes the
parameter name as listed in
“Supported Parameters List”
on page 550.
IsupXXX**
accessorName
(write accessor)*
(ISUP::ParmValue& val,
ISUP::MsgStatus& status);
void
<parameterShortName>SetA
bsent
(absence accessor)
(ISUP::MsgStatus& P_status);
HPAIN::Boolean
accessorNameIsPresent
(presence accessor)*
(ISUP::MsgStatus& status) const;
* accessorName denotes the parameter name as listed in “Supported Parameters List” on
page 550.
**IsupXXX denotes a specific message class as listed in “Supported Parameters List” on
page 550.
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)
Chapter 13
537
Accessors
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:
•
the transfer representation does not exist.
•
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.
538
Chapter 13
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 class—ISUP::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);
Chapter 13
539
Assigning Values
if (!status.isOk()){
// error recovery
}
iamMsg->callingPartysCategory(value->assign (“\x53”, 1), status);
// error recovery
}
iamMsg->userServiceInformation(value->assign (“\x53\x33”, 2), status);
// error recovery
}
iamMsg->calledPartyNumber(value->assign (“\x53\x33\x76\x68”, 4), status);
// error recovery
}
delete value;
return iamMsg;
}
540
Chapter 13
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.
Chapter 13
541
Sending Messages
Figure 13-4
Probe/Message Relationship
See Figure 12-4, “Object Model.”
542
Chapter 13
Sending Messages
Both IsupSMProbe and IsupBPProbe have defined send() methods, and
as described in “Exchanging Primitives” on page 503, 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.
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. Otherwise, the queue still contains the messages that
were not sent.
This is part of the flow control mechanism performed by
HP OpenCall SS7 ISUP, and is described in “IPC Flow Control” on
page 559.
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
}
Chapter 13
543
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 477.
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 IsupXXX*
castMsg
(const IsupMsg* msg) const;
IsupMsg::Type
getMsgType
();
*IsupXXX denotes a specific message class listed in “Supported Parameters List”
on page 550.
544
Chapter 13
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.
While there are indications waiting to be received by the application, the
MTP3 will not perform a MTPL3recv() on behalf of the
See “IPC Flow Control” on page 559.
Chapter 13
545
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
546
Successful Automated Call Release
Chapter 13
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.
Chapter 13
547
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
...
548
Chapter 13
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.
Chapter 13
549
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
•
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.
This only applies for the IAM UserServiceInformation parameter,
which is a mandatory variable for ANSI-95 and an optional variable
for ITUT-88.
•
550
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.
Chapter 13
14
Managing
This chapter provides management guidelines for use in developing an
ISUP application.
Chapter 14
551
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.
552
Chapter 14
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
553
Managing Memory Space
Control of the memory used by HP OpenCall SS7 ISUP is dependent on
the application’s 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().
554
Chapter 14
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 536, 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.
Some primitives sent from the HP OpenCall SS7 ISUP library to the
application contain additional information objects (see “Additional
Information” on page 524). These objects are automatically created by
the API.
Chapter 14
555
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().
Check the Return Status value for each method, as described in
“Exception Handling” on page 448. The creation and deletion of these
return status objects is your responsibility: the API only assigns values
to these objects.
556
Chapter 14
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
557
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.
558
Chapter 14
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 ISUP’s 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
559
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 544. 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
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.
560
Chapter 14
IPC Flow Control
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.
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:
•
•
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
561
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
562
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.
Chapter 14
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.
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
563
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.
564
Chapter 14
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
565
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.
566
Chapter 14
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
567
Figure 14-6
568
Recovery
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
569
Introduction to ISUP Procedures
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
FSM Support
Acronym
Implemente
d
Particularities/Limitations
Signaling Procedure Control
MSDC
Yes
MSDC
Yes
CPCI
Yes
CPCO
Yes
SSCI
Yes
SSCO
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.
ITU-T 93, 97 and ETSI V2 only.
Circuit Supervision Control
570
BLR
Yes
BLR
Yes
CCI
Yes
CCO
Yes
Chapter 15
Table 15-1
FSM Support (Continued)
Acronym
NOTE
Chapter 15
Implemente
d
Particularities/Limitations
CGRR
Yes
CGRS
Yes
CQR
Yes
CQS
Yes
ITU-T based version only
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
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.
571
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.
572
Chapter 15
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.
Chapter 15
573
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 528 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
574
•
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).
Chapter 15
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:
Chapter 15
•
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
575
(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).
•
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
— 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
576
Chapter 15
— 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
•
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:
Chapter 15
•
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.
577
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:
578
•
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.
Chapter 15
•
DPC_uncongested indication brings the DPC from the congested to
the available state.
•
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:
— RELEASE_REQ
— RELEASE_RESP
— Primitives that reset circuits
— 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
Chapter 15
579
— 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
— Primitives that stop REL/RSC retransmission on circuit groups:
— GROUP_STOP_REQ
•
580
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.
Chapter 15
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 return 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 574).
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 575).
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.
Chapter 15
581
Generic Primitive Processing (State-machine Probe)
8. Validates that the message attached to the primitive is present (if
applicable) and of the right type (e.g. 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.
582
Chapter 15
Generic Primitive Processing (Bypass Probe)
HP OpenCall SS7 ISUP when receiving a primitive from the application
on a By-pass probe.
HP OpenCall SS7 ISUP performs the following steps:
1. Checks the probe status and return 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 574).
4. Identifies the target DPC object and returns with a DPC_NOT_FOUND
5. Checks the DPC status (refer to “DPC States” on page 578).
6. Checks that the primitive is either ISUP_MSG_REQ or
PASS_ALONG_REQ, and returns with an INCONSISTENT_ARGUMENTS
7. 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
for ANSI 95) which 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:
•
Chapter 15
keeps the message in the internal sending queue
583
584
•
reports the failure to application
•
marks the probe active for rescheduling
Chapter 15
Generic ISUP Message Handling (State-machine Probe)
Generic ISUP Message Handling
(State-machine Probe)
HP OpenCall SS7 ISUP when receiving an ISUP message from the
network on an SM probe.
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:
•
Ignore the message if the DPC object is not found.
•
Ignore the message if DPC paused.
3. Ignores the message if it is empty or less than 3 bytes long (cannot
access CIC or Message Type).
NOTE
Routing is based on the OPC of the incoming message. From the
stack’s point of view, this OPC corresponds to a DPC.
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
Chapter 15
585
Generic ISUP Message Handling (Bypass Probe)
Generic ISUP Message Handling (Bypass
Probe)
HP OpenCall SS7 ISUP when receiving an ISUP message from the
network on a bypass probe.
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:
586
•
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)
Chapter 15
Generic ISUP Message Handling (Bypass Probe)
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
587
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.
588
Chapter 15
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
CGUA
no status subfield
status bit = 1 for circuits which have been
remotely unblocked
CQM
group=single circuit
no status subfield
range<24
no status subfield
CQR
no status subfield
no status subfield
Chapter 15
589
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
rangeAndStatus Parameter
range = 0
range !=0
GRS
-Reserved-
range<32
no status subfield
GRA
-Reserved-
status bit = 1 for locally blocked circuits fro
maintenance reasons
CGB
-Reserved-
range<255, but number of affected circuits is less
than or equal to 32
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
CGUA
-Reserved-
status bit = 1 for circuits which have been remotely
unblocked
CQM
group=single circuit
no status subfield
range<32
no status subfield
CQR
no status subfield
no status subfield
590
Chapter 15
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
591
User Defined ISUP Message Exchange
User Defined ISUP Message Exchange
User defined messages can be exchanged at any state for a given circuit:
592
•
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
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
593
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
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.
594
Chapter 15
Figure 15-4
Reassembly of Incoming Messages - T34 Expiry
Reassembly of Incoming Messages - Failure Case 2
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
595
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
596
Reassembly of Incoming Messages - COT Received
Chapter 15
Handling Unrecognized Messages - ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP
Handling Unrecognized Messages ITU97 Mode for ITU-T Based
ITU97 mode supports handling of unrecognized ISUP messages, i.e.
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
597
Handling Unrecognized Messages - ITU97 Mode for ITU-T Based HP OpenCall SS7 ISUP
598
Chapter 15
16
ISUP Call Control - Procedures
Common to ANSI and ITU-T
This chapter describes HP OpenCall SS7 ISUP behavior for call control
setup/teardown procedures that are common to ANSI and ITU-T.
Chapter 16
599
ISUP Call Control - Procedures Common to ANSI and ITU-T
Overview
Overview
For each procedure, this chapter provides:
600
•
message and primitive flow
•
circuit states and timer activity
Chapter 16
Conventions Used in Diagrams
The diagrams in this chapter and in the following chapters:
•
•
Chapter 18, “ISUP Call Control - Procedures Specific to ITU-T,”
•
Chapter 19, “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
601
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
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:
602
•
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
Chapter 16
Figure 16-1
SETUP_REQ Locally Refused by HP OpenCall SS7 ISUP
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
Chapter 16
There is no automatic call setup re-attempt as another circuit has to be
selected.
603
Figure 16-2
Dual Seizure
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.
604
Chapter 16
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.
Chapter 16
605
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.
606
Chapter 16
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
Chapter 16
607
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.
608
Chapter 16
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.
Chapter 16
609
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.
610
Chapter 16
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.
Chapter 16
611
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.
612
Chapter 16
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.
Chapter 16
613
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.
614
Chapter 16
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
Chapter 16
Reset from Application- Successful Procedure
615
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.
616
Chapter 16
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.
Chapter 16
617
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
618
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.
Chapter 16
Figure 16-17
Chapter 16
Group Reset - Double Reset
619
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
620
Solicited Information Exchange - Incoming Request
Chapter 16
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.
Chapter 16
621
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.
622
Chapter 16
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.
Chapter 16
623
Figure 16-23
624
Unsolicited Information Exchange - Failure
Chapter 16
Suspend/Resume
Suspend/Resume
Suspend/Resume - T6 Expiry
This procedure applies for both ANSI based and ITU-T based
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.
Chapter 16
625
Suspend/Resume
Figure 16-24
626
Suspend/Resume - T6 Timeout
Chapter 16
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
627
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
628
Pass Along Procedure - Outgoing Call
Chapter 16
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
629
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 649.
For the ITU-T case, refer to “Continuity Check Request with IAM or
CCR” on page 680.
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.
630
Chapter 16
Figure 16-29
Chapter 16
Continuity Check - Outgoing Side - Failure
631
After a failed continuity check, a re-check is done automatically as
depicted in the Continuity Recheck, see “Continuity Recheck” on
page 652.
Figure 16-30
632
Continuity Check - Incoming Side - Failure
Chapter 16
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
633
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
634
FAC Message
Chapter 16
17
Specific to ANSI
setup/teardown procedures that are specific to ANSI.
Chapter 17
635
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 17-1
636
Successful Call Setup - Outgoing Side
Chapter 17
Call Release
Call Release
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 17
RSC Message generation upon time-out is suspended if MTP3 is not
available or congested.
637
Call Release
Figure 17-2
638
Abnormal Release - Reset Failed
Chapter 17
Call Release
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
application after RESET_CONF.
Chapter 17
639
Call Release
Figure 17-3
640
Abnormal Release - RLC Received at Last
Chapter 17
Circuit Reset
Circuit Reset
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 17
641
Circuit Reset
Figure 17-4
642
Call Reset - Failure to Receive RLC
Chapter 17
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 17-5
Chapter 17
Group Reset from User- Normal Case
643
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 602.
Figure 17-6
644
Circuit Reservation from Network
Chapter 17
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 17-7
Chapter 17
Circuit Reservation from Network - Failure
645
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 17-8
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.
646
Chapter 17
Suspend/Resume
Figure 17-9
Chapter 17
647
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 17-10
648
Exit Message - Normal Case
Chapter 17
scenarios.
on this circuit’.
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).
Chapter 17
649
Figure 17-11
650
Continuity Check - Outgoing Side
Chapter 17
NOTE
Chapter 17
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 above 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).
651
Figure 17-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.
652
Chapter 17
Figure 17-13
Chapter 17
Continuity Recheck - Outgoing Side
653
654
Chapter 17
Figure 17-14
Chapter 17
Continuity Recheck - Incoming Side
655
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:
656
•
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.
Chapter 17
Figure 17-15
Chapter 17
Continuity Recheck - Outgoing Side - TCCR Expiry
657
Continuity Recheck - T24 Expiry at Outgoing Side
If the T24 timer expires during the continuity recheck phase, either
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.
658
Chapter 17
Figure 17-16
Chapter 17
Continuity Recheck - Outgoing Side - T24 Expiry
659
660
Chapter 17
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.
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.
Chapter 17
661
Figure 17-17
662
Continuity Check with CRM - Incoming Side - Success
Chapter 17
Failed Continuity Check and Recheck Procedure
Figure 17-18
Chapter 17
Continuity Check with CRM - Incoming Side - Failure
663
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 17-19
664
Continuity Check with CRM - Not Required / Required on
Previous
Chapter 17
18
Specific to ITU-T
setup/teardown procedures that are specific to ITU-T.
Chapter 18
665
ISUP Call Control - Procedures Specific to ITU-T
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 18-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
666
The TTC flavor does not use the T9 timer. In this particular case, no T9
timer is started when receiving an ACM message.
Chapter 18
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 18-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 18
667
Figure 18-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.
668
Chapter 18
Use of the SAM Message for Outgoing Calls
Figure 18-4
Use of SAM Message - Outgoing Side
Use of the SAM Message for Incoming Calls
Figure 18-5
Chapter 18
Use of SAM Message - Incoming Side
669
Call Release
Call Release
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
670
RSC Message generation upon time-out is suspended if MTP3 is not
available or congested.
Chapter 18
Call Release
Figure 18-6
Abnormal Release - Reset Failed
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
application before RESET_CONF.
Chapter 18
671
Call Release
Figure 18-7
672
Abnormal Release - RLC Received at Least
Chapter 18
Circuit Reset
Circuit Reset
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
After T17:
•
a MAINTENANCE_SYSTEM_IND is issued to the application, informing
the application/Operator about the error situation
•
every T16 (typically 5 seconds)
until a STOP_REQ primitive is received from the application.
Chapter 18
673
Circuit Reset
Figure 18-8
674
Call Reset - Failure to Receive RLC
Chapter 18
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 18-9
Chapter 18
Group Reset from User- Normal Case
675
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).
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.
676
Chapter 18
Suspend/Resume
Figure 18-10
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 18
677
Suspend/Resume
Figure 18-11
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.
678
Chapter 18
Suspend/Resume
Figure 18-12
Chapter 18
Suspend/Resume - T6 Timeout
679
scenarios.
on this circuit’.
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).
680
Chapter 18
Figure 18-13
Chapter 18
Continuity Check - Outgoing Side
681
NOTE
682
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 above 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 18
Figure 18-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.
Chapter 18
683
Continuity Recheck
If the continuity recheck procedure is a success, only the outgoing side
sends a REL message to finish the procedure.
684
Chapter 18
Figure 18-15
Chapter 18
Continuity Recheck - Outgoing Side
685
686
Chapter 18
Figure 18-16
Chapter 18
Continuity Recheck - Incoming Side
687
After a failed continuity check, a re-check is done automatically as
depicted in the next section.
If the T24 timer expires during the continuity recheck phase, either
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.
688
Chapter 18
Figure 18-17
Chapter 18
689
690
Chapter 18
Figure 18-18
Chapter 18
Continuity Recheck - Incoming Side - COT Failure
691
692
Chapter 18
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 18-19
Chapter 18
Facility Exchange - Success
693
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 18-20
694
Facility Exchange - Failure
Chapter 18
19
ISUP Circuit Maintenance Procedures Specific to ANSI
This chapter describes circuit maintenance procedures that are specific
to ANSI.
Chapter 19
695
ISUP Circuit Maintenance - Procedures Specific to ANSI
Overview
Overview
The circuit maintenance processes described in this chapter include:
696
•
circuit blocking and unblocking
•
circuit group blocking and unblocking
•
circuit group query
•
circuit validation
Chapter 19
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 19-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 19-2
Chapter 19
697
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 19-3
Circuit Unblocking from Network- Normal Case
Circuit Unblocking from User - Normal Case
Figure 19-4
698
Chapter 19
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 19-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 19
699
Figure 19-6
700
Circuit Blocking during Call Setup
Chapter 19
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 19
701
Figure 19-7
Group Blocking with Release - Normal Case
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,
702
•
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
•
Chapter 19
Figure 19-8
Chapter 19
Group Blocking without Release - Normal Case
703
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 19-9
704
Group Blocking from User - Normal Case
Chapter 19
Group Unblocking from NetworkNormal Case
In this scenario, a CGU is received from the network. As a result,
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 19-10
Chapter 19
Group Unblocking from Network- Normal Case
705
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 19-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,
706
Chapter 19
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.
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 19-12
Chapter 19
Group Blocking during Call Setup
707
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 19-13
708
•
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 19
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 19-14, “Circuit Group Query from User - Normal Case.”
Figure 19-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 19-15, “Circuit Group Query from User - Failure (T28
Timeout).”
Figure 19-15
Chapter 19
Circuit Group Query from User - Failure (T28 Timeout)
709
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 19-16, “Circuit Group
Query from User - Error in Processing State - Case 1.”
Figure 19-16
Circuit Group Query from User - Error in Processing State - Case
1
NOTE
It is the application’s responsibility to release any interconnected
circuits.
710
Chapter 19
Circuit Group Query
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 19-17, “Circuit Group
Query from User - Error in Processing State - Case 2.”
Figure 19-17
Chapter 19
2
711
Circuit Group Query
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 19-18, “Circuit Group Query from User - Error in Processing
State - Case 3.”
Figure 19-18
712
3
Chapter 19
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 19-19, “Circuit Group Query from User - Error in Maintenance
State - Case 1.”
Figure 19-19
Chapter 19
Circuit Group Query from User - Error in Maintenance State Case 1
713
Circuit Group Query
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 19-20, “Circuit Group Query from User - Error in Maintenance
State - Case 2.”
Figure 19-20
714
Chapter 19
Circuit Group Query
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 19-21, “Circuit Group Query from User - Error in Maintenance
State - Case 3.”
Figure 19-21
Chapter 19
715
Circuit Group Query
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 19-22, “Circuit Group Query from User - Error in
Maintenance State - Case 4.”
The behavior after sending the BLO message is the same as after a user
initiated BLOCKING_REQ.
Figure 19-22
716
Chapter 19
Circuit Group Query
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 19-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.
Figure 19-23
Chapter 19
717
Circuit Group Query
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 19-24, “Circuit Group Query from User - Error in
Maintenance State - Case 6.”
Figure 19-24
718
Chapter 19
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 19-25
Chapter 19
Circuit Validation from Network
719
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 19-26
720
Circuit Validation from User - Normal Case
Chapter 19
Circuit Validation
Circuit Validation from User - Test Failed - Two T_CVT Timeouts
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 19-27
Chapter 19
Circuit Validation from User - Test Failed - Two T_CVT Timeouts
721
Circuit Validation
Circuit Validation from User - Test Failed -CVR Received Before
Second T_CVT Timeout
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 19-28
722
Circuit Validation from User - Test Failed -CVR Received Before
Second T_CVT Timeout
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
723
ISUP Circuit Maintenance - Procedures Specific to ITU-T
Overview
Overview
The circuit maintenance processes described in this chapter include:
724
•
•
•
circuit group query
•
circuit validation
Chapter 20
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
725
In this case, the circuit is put in the xxx_MN_LOCALLY_BLOCKED state.
Figure 20-2
726
Chapter 20
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
Figure 20-4
Chapter 20
727
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.
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
728
Circuit Unblocking on Reception of IAM
Chapter 20
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
729
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
730
•
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
Figure 20-7
Chapter 20
Maintenance Group Blocking - Normal Case
731
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,
•
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
•
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
732
Chapter 20
Group Blocking (Maintenance Oriented) from User Normal Case
In this scenario, a maintenance GROUP_BLOCKING_REQ request is sent by
•
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
Chapter 20
733
Group Blocking (Hardware Oriented) from User Normal Case
In this scenario, a hardware HW_GROUP_BLOCKING_REQ request is sent by
•
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 CGB message.
Figure 20-10
734
Chapter 20
Group Unblocking (Maintenance Oriented) from
Network Normal Case
In this scenario, a CGU is received from the network. As a result,
•
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 CGB message.
Figure 20-11
Chapter 20
Group Unblocking from Network - Normal Case
735
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 CGB message.
Figure 20-12
736
Group Unblocking from Network - Normal Case
Chapter 20
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
•
•
waits for the CGUA message from the network and issues a
GROUP_UNBLOCKING_CONF primitive to the application
•
marks all circuits locally unblocked
737
Group Unblocking (Hardware Oriented) from User Normal Case
In this scenario, an HW_GROUP_UNBLOCKING_REQ request is sent by the
user. Consequently, HP OpenCall SS7 ISUP:
Figure 20-14
738
•
•
waits for the CGUA message from the network and issues an
HW_GROUP_UNBLOCKING_CONF primitive to the application
•
marks all circuits locally unblocked
Chapter 20
Group Blocking (Maintenance Oriented)
If one of the circuits present in the CGB message received from the
network has issued a SETUP_REQ, an immediate release procedure is
engaged by HP OpenCall SS7 ISUP.
Consequently, a SETUP_FAILURE_IND indicating BLOCKING is issued to
the application.
Figure 20-15
Chapter 20
739
Group Blocking (Hardware Oriented)
If one of the circuits present in the CGB message received from the
network has issued a SETUP_REQ, an immediate release procedure is
engaged by HP OpenCall SS7 ISUP.
Consequently, a SETUP_FAILURE_IND indicating BLOCKING is issued to
the application.
Figure 20-16
740
Chapter 20
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 20-17
Chapter 20
•
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
741
Circuit Group Query
Circuit Group Query from Application
For ITU-T based HP OpenCall SS7 ISUP, 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 Timer dedicated to the group query
procedure:
•
the T34 timer for the ITU-T 88 version
•
the T28 timer for all other ITU-T based flavors
Normal Case
On receipt of the answer to the CQM from the network, the received CQR
message is transmitted to the application by HP OpenCall SS7 ISUP
through a GROUP_QUERY_CONF primitive.
Figure 20-18
Circuit Group Query from User - Normal Case
Failure to Receive CQR
If the timer expires, HP OpenCall SS7 ISUP sends back a
MAINTENANCE_SYSTEM_IND primitive indicating:
742
•
the T34_TIMEOUT for the ITU-T 88 version
•
the T28_TIMEOUT for all other ITU-T based flavors
Chapter 20
Circuit Group Query
Figure 20-19
Chapter 20
Circuit Group Query from User - Failure
743
Circuit Group Query
744
Chapter 20
A
ISUP Library Values
This appendix lists the AdditionalInfo values that can be returned by the
ISUP Library in certain ANSI and ITU-T -based scenarios.
Appendix A
745
ISUP Library Values
ANSI-based HP OpenCall SS7 ISUP
Table A-1
SETUP_FAILURE_IND
Value
Comments
DUAL_SEIZURE
The application, unaware that ISUP has already
received an IAM message on the same circuit, sent a
SETUP_REQ
COT_FAILURE
A continuity check (incoming or outgoing) failed
FLOW_CONTROL
T7 timeout popped, when in outbound flow control state
Table A-2
START_RESET_IND
Value
Comments
UNEXPECTED_MESSAGE
Received an unexpected message while in states where
a reset procedure must be engaged (see recommended
SDLs).
T5_TIMEOUT
T5 timeout expired.
COT_CC_NOT_REQUIRED
Received a COT message while continuity was not
required on the corresponding circuit.
MTP_UNAVAILABLE
See NOTE * below.
DPC_UNAVAILABLE
See NOTE * below.
BLOCKING_WITH_RELEASE
Handled a CGB message requesting immediate release.
See NOTE * below.
TCCRr_TIMEOUT
TCCRr timeout expired for incoming continuity
recheck.
T27_TIMEOUT
T27 timeout expired for incoming continuity recheck.
T34_TIMEOUT
T34 timeout expired for incoming continuity recheck.
DCO_LPA_FAIL
LPA was not received within the TCCRr timer for
outgoing continuity recheck.
746
Appendix A
ISUP Library Values
Table A-2
START_RESET_IND (Continued)
Value
Comments
UNEQUIPPED_CIRCUIT
Received a UCIC on a circuit that is not Idle regarding
the CPC state machine.
TIMER_SHORTAGE
when trying to start a T6, T7, T8, or T_CRA timer, there
is no timer available and the corresponding circuit is
not idle with regard to the CPC state machine.
NOTE
* No RESET_CONF indication should be awaited after a
START_RESET_IND with these cause values.
Table A-3
START_RELEASE_IND
Value
UNEXPECTED_RLC
Comments
RLC was received while in unexpected states (see SDL
diagrams):
CPCI:
•
Wait for COT and IAM
•
Wait for IAM
•
Wait for COT
•
Wait for OGC complete
•
Wait for Answer
•
ICC answered
•
ICC suspended
CPCO:
T6_TIMEOUT
Appendix A
•
Wait for continuity reports
•
Wait for address complete
•
Wait for answer
T6 timer expired
747
ISUP Library Values
Table A-3
START_RELEASE_IND (Continued)
Value
Comments
T7_TIMEOUT
T7 timeout expired
T8_TIMEOUT
T8 timeout expired
T33_TIMEOUT
T33 timeout expired
T_CRA_TIMEOUT
TCRA expired
BLOCKING
CPCO:
•
BLO/CGB (without release) received in Wait for
continuity reports
•
BLO/CGB (without release) received in Wait for
address complete
T1_TIMEOUT
T1 expired during outgoing continuity recheck
DCO_SUCCESS
Continuity recheck was successful.
STOP_REQ
Continuity recheck was stopped by the application.
Table A-4
Value returned
Comments
T13_TIMEOUT
T13 timer expired (BLS)
T15_TIMEOUT
T15 timeout expired (BLS)
T23_TIMEOUT
T23 first expiry (CGRS)
T5_TIMEOUT
T5 timeout expired
COT_RECEIVED
Received a COT with first time indicator=on during
incoming continuity recheck
T5_TIMEOUT
T5 expired during outgoing continuity recheck
DCO_FAIL
Outgoing continuity recheck failed (T24 timeout)
with first time indicator=on
DCO_SUCCESS
Outgoing continuity recheck succeeded with first
time indicator=on
748
Appendix A
ISUP Library Values
Table A-4
MAINTENANCE_SYSTEM_IND (Continued)
Value returned
Comments
STOP_REQ
The application sent STOP_REQ during outgoing
continuity recheck
T17_TIMEOUT
T17 expired
RSC_AFTER_T17
Received RSC while CRS state machine was in the
Wait for RLC state
CRS_STOP
CRS state machine stopped while waiting for RLC
message
RLC_AFTER_T17
Received RLC while the CRS state machine was in
the Wait for RLC state
T19_TIMEOUT
T19 timer expired (GBUS)
T21_TIMEOUT
T21 timer expired (GBUS)
T18_NOT_RUNNING
CGBA received while T18 was not running in Wait
for CGBA states on the GBUS state machine
WRONG_STATUS_BITS
CGBA/CGUA received while the GBUS state
machine was in Wait for CGBA/CGUA states and
too many or too few bits were set in status
T20_NOT_RUNNING
CGUA received while T20 is not running in Wait for
CGUA states on the GBUS state machine
UNEQUIPPED_CIRCUIT
UCIC received.
TIMER_SHORTAGE
Too many timers is use, no more timers available.
NON_ISDN_ACCESS_INDICATION
An address complete message is received with the
ISDN access indicator set to NON_ISDN (ITU-T
TTC3 only).
CIRCUIT_VALIDATION_TEST_FAI
LED (second time)
Circuit validation test failed. T_CVT timeout for the
second time.
A message is received on a non configured or
unequipped circuit.
Appendix A
749
ISUP Library Values
ITU-T - based HP OpenCall SS7 ISUP
Table A-5
SETUP_FAILURE_IND
Value
Comments
T27_TIMEOUT
T27 expired while in Wait for CCR state
DUAL_SEIZURE
•
IAM received while sending
CONTINUITY_RECHECK_REQ (CRCS state
machine)
•
IAM received while sending SETUP_REQ
CPC_BUSY
CONTINUITY_RECHECK_REQ requested while the
circuit was not IDLE
BLOCKING
•
CGB (Maintenance) has been sent through
GROUP_BLOCKING_REQ in WaitForContinuity
State (CPCI)
•
CGB (Maintenance) has been sent through
GROUP_BLOCKING_REQ in WaitForACM State
(CPCI)
•
CGB (Maintenance) has been received while in
WaitForACM State (CPCO)
•
CGB (Maintenance) has been received while in
WaitForContinuity State (CPCO)
•
CGB (Hardware) has been sent through
HW_GROUP_BLOCKING_REQ in
WaitForContinuity State (CPCI)
•
CGB (Hardware) has been received while in
WaitForContinuity State (CPCO)
•
COT indicating failure was received in
•
COT indicating failure was sent during outgoing
continuity recheck
RELEASE
COT_FAILURE
750
Appendix A
ISUP Library Values
Table A-5
SETUP_FAILURE_IND (Continued)
Value
ITU97 only (CRCR state machine):
CRCR_RESET
•
RSC received while waiting for Continuity (CCR)
•
GRS received while waiting for Continuity (CCR)
•
A Reset occurred while waiting for Continuity
(CCR)
In WaitForACM State (CPCO) in flow control condition
(T7 expiry+outbound flow control)
FLOW_CONTROL
Table A-6
Comments
START_RESET_IND
Value
UNEXPECTED_MESSAGE
Comments
•
ACM, ANM, CON, CPG, FOT, RES, SAM, SUS,
INR, INF, PAM, FAR, FRJ, FAA, COT received in
IDLE State
•
IAM, ACM, CON, ANM, CPG, FOT, RES, SUS, INR,
PAM, FAR, FAA, FRJ received in
•
IAM, ACM, ANM, CON, CPG, FOT, RES, SUS,
FAR, FRJ, FAA, COT received in WaitForACM
(CPCI)
•
ANM, FOT, RES, SAM, SUS, FAR, FRJ, FAA
received in WaitForACM (CPCI)
•
ACM, ANM, CON, CPG, FOT, RES, SAM, SUS,
FAR, FAA, FRJ received in WaitForContinuity
(CPCO)
COT_CC_NOT_REQUIRED
COT received when not awaited
UNEQUIPPED_CIRCUIT
Received a UCIC on a circuit that is not Idle regarding
the CPC state machine.
In this case, the application should not wait for a
RESET_CONF.
Appendix A
751
ISUP Library Values
Table A-6
START_RESET_IND (Continued)
Value
TIMER_SHORTAGE
Table A-7
Comments
•
when trying to start a T2, T6, T7, T8, T9, T33, or
T_CRA timer, there is no timer available and the
corresponding circuit is not idle regarding the CPC
state machine.
•
when trying to start a T34 timer, there is no timer
available and the SSC state machine is not in the
idle state (TTC3, SSUR, and ITU97 only).
START_RELEASE_IND
Value
Comments
CONTINUITY_SUCCESS
BackwardCheckTone received in
WaitForBackwardCheckTone, after
ENABLE_ECHO_IND_ACK received
UNEXPECTED_RLC
•
RLC received in WaitForACM, WaitForANM,
ACTIVE, Suspended States (CPCI)
•
RLC received in WaitForACM, WaitForANM,
ACTIVE, Suspended States (CPCO)
•
RLC received in WaitForContinuity (CPCI, CPCO)
•
RLC received after IAM received (CPCI)
•
BLO received in WaitForACM (CPCO)
•
BLO received in WaitForContinuity (CPCO)
BLOCKING
T2_TIMEOUT
T2 timer expired
T6_TIMEOUT
T6 timer expired
T8_TIMEOUT
T8 timer expired
T7_TIMEOUT
T7 timer expired
T9_TIMEOUT
T9 timer expired
T33_TIMEOUT
T33 timer expired
752
Appendix A
ISUP Library Values
Table A-8
Value
Comments
UNEQUIPPED_CIRCUIT
UCIC received.
TIMER_SHORTAGE
Too many timers is use, no more timers available.
A message is received on a non configured or
unequipped circuit.
MGBS/HGBS state machine
MN_GROUP_BLOCKING
•
GROUP_BLOCKING_REQ has been sent (MGBS
only)
•
in WaitForCGUA State, CGUA received and
CGUA != CGU status bits (ITU-T 93/97 ONLY)
MN_GROUP_UNBLOCKING
In WaitForCGBA State, CGBA received and CGBA !=
CGB status bits (ITU-T 93/97 ONLY)
HW_GROUP_BLOCKING
HW_GROUP_BLOCKING_REQ has been sent
(HGBS only)
HW_GROUP_UNBLOCKING
ITU97 only (and all standards based on ITU97),
HGBS state machine:
T19_TIMEOUT
Appendix A
•
on CGBA receipt in Idle state, generated for each
circuit not hardware locally blocked
•
on WaitForCGBA state, generated for each circuit
not asked to be blocked in the CGB and marked
as blocked in the CGBA statusBits (that is, CGB
status bits < CGBA status bits)
•
on WaitForCGUA state, generated for each circuit
not asked to be unblocked in the CGU and
marked as unblocked in the CGUA status bits
(that is, CGU status bits < CGUA status bits)
•
on WaitForCGUA state, generated if not all
circuits are acknowledged in the CGUA status
bits (that is, CGU status bits > CGUA status bits)
(only one notification)
First T19 expiry
753
ISUP Library Values
Table A-8
Value
Comments
T21_TIMEOUT
First T21 expiry
T18_NOT_RUNNING
In WaitForCGBA State, after CGBA is received,
CGB=CGBA (status bits), and T18 timer is not
running
In WaitForCGBA or WaitForCGUA State, after GRS
sent through GROUP_RESET_REQ, CGB<=GRS or
CGU<=GRS
T20_NOT_RUNNING
In WaitForCGUA State, after CGUA is received,
CGU=CGUA (status bits), and T20 timer is not
running
MGBR state machine
MN_BLOCKING
GROUP_BLOCKING_IND received
HGBR state machine
HW_BLOCKING
HW_GROUP_BLOCKING_IND received
HRB state machine
HW_UNBLOCKING
RSC/ GRS are sent (through
RESET_REQ/GROUP_RESET_REQ) or received in
remotely blocked state
HLB state machine
HW_UNBLOCKING
RSC/GRS are sent (through
RESET_REQ/GROUP_RESET_REQ) in locally
blocked state
CRS state machine
T17_TIMEOUT
First T17 expiry
RLC_AFTER_T17
RLC received in WaitForRelease state and T16 not
running
CRCS state machine
754
Appendix A
ISUP Library Values
Table A-8
Value
Comments
T5_TIMEOUT
T5 timer expired
T24_TIMEOUT
T24 timer expired in WaitForBackwardChecktone
and check indicator=2
BackwardCheckTone received and check indicator=3,
after ENABLE_ECHO_IND_ACK received
CRCR state machine
COT_RECEIVED
COT failure received in WaitForREL state and check
indicator=2
REL_RECEIVED
REL received in WaitForREL state and check
indicator=3
CQS state machine
T34_TIMEOUT
T34 timer expired (ITU-T 88 and TTC ONLY)
T28_TIMEOUT
T28 timer expired (ITU-T 93/97 ONLY)
BLS state machine
MN_BLOCKING
BLOCKING_REQ sent
T12_NOT_RUNNING
In WaitForBLA State, BLA received and T12 timer
not running
T13_TIMEOUT
First T13 expiry
MN_UNBLOCKING
After RSC/GRS sent (through
RESET_REQ/GROUP_RESET_REQ) in WaitForBLA
or LocallyBlocked state
T14_NOT_RUNNING
In WaitForUBA State, UBA received and T14 timer
not running
T15_TIMEOUT
First T15 expiry
Appendix A
755
ISUP Library Values
Table A-8
Value
Comments
BLA_WHEN_IDLE
ITU97 only (for all standards based on ITU97):
A BLA is received on a circuit for which the BLS state
machine is in the Idle state (that is, no Blocking
action has been requested).
UBA_WHEN_LOCALLY_BLOCKED
ITU97 only (for all standards based on ITU97):
A UBA is received on a locally blocked circuit.
BLR state machine
MN_BLOCKING
MN_UNBLOCKING
•
BLO received in IDLE state
•
after GRS/GRA exchange and status bits in GRA
=1
•
RSC sent or received, GRS received in
WaitForBLA or remotely blocked state
•
IAM received in remotely blocked state
CPC state machine
T5_TIMEOUT
T5 timer expired
CGRS state machine
T22_NOT_RUNNING
In WaitForGRA state, after GRA received and T22
timer not running
T23_NOT_RUNNING
First T23 timer expiry
756
Appendix A
B
TUP Addendum
This appendix contains a description of TUP (Telephone User Part) as
supported by HP OpenCall SS7 TUP. The description is based on the
description of HP OpenCall SS7 ISUP given in the rest of this guide.
Appendix B
757
TUP Addendum
How to Use This Addendum
How to Use This Addendum
There are many similarities between HP OpenCall SS7 TUP and
HP OpenCall SS7 ISUP. This addendum is written to take advantage of
these similarities.
This addendum does not contain a complete description of
HP OpenCall SS7 TUP. Instead, it describes HP OpenCall SS7 TUP in
terms of the differences between it and HP OpenCall SS7 ISUP.
Functionality Identical to HP OpenCall SS7 ISUP
If a functionality of HP OpenCall SS7 TUP is identical to the
corresponding functionality of HP OpenCall SS7 ISUP, its description is
not repeated in this addendum. Instead, an explicit cross-reference is
made to the description of the corresponding HP OpenCall SS7 ISUP
functionality in the body of this guide.
Consequently, while reading this addendum, you must refer to the rest of
this guide as and when necessary.
Functionality Not Identical to HP OpenCall SS7 ISUP
If there is a difference in a functionality between HP OpenCall SS7 TUP
and HP OpenCall SS7 ISUP, then the HP OpenCall SS7 TUP
functionality is fully described in this addendum.
758
Appendix B
TUP Addendum
Flavors Supported by HP OpenCall SS7 TUP
This addendum describes the flavors supported by
HP OpenCall SS7 TUP. The following terms are used:
CTUP
to refer to the ITU-T TUP China flavor,
Recommendations Q721 to Q725.
ITUP
to refer to the ITU-T TUP Blue Book flavor,
Recommendations Q721 to Q725.
Unless explicitly indicated otherwise (for example, by phrases such as
not supported in CTUP or CTUP Only, and not supported in ITUP or
ITUP Only), the contents of this addendum applies to both flavors.
NOTE
The term TUP is used to refer to generic TUP, that is, not specific to a
particular flavor.
If the contents of a Table or a Figure is specific to a particular flavor, then
its title includes the words CTUP Only or ITUP Only as appropriate.
Table B-1 lists the main differences between the two flavors supported.
Table B-1
Main Differences Between the CTUP and ITUP Flavors
Item
CTUP (China
Flavor)
ITUP (ITU-T
Flavor)
ANU (Answer Signal Unqualified)
message, associated with the SETUP
primitive.
Not supported.
Supported.
Charging messages:
CCC, CCG, CHA, CHG, PCC and TRG.
Not supported.
Supported.
Charging primitives:
CHARGING_REQ, CHARGING_IND,
CHARGING_RESP, and CHARGING_CONF.
Not supported.
Supported.
Length of CIC field.
12 bits (that is, 16
minus 4 bits for the
spare field).
12 bits (no spare
field).
Appendix B
759
TUP Addendum
Table B-1
Main Differences Between the CTUP and ITUP Flavors
Item
CTUP (China
Flavor)
ITUP (ITU-T
Flavor)
Closed User Group Information in IAI
message
Not supported.
Supported.
DPC and OPC formats.
Integer or a.b.c
format.
Integer (ITU-T)
format.
24 bits.
14 bits.
MAL (Malicious Call Identification)
message.
Supported
Not supported.
MPM (Metering Pulse Signal) message.
Supported.
Not supported.
METERING_PULSE_REQ primitive.
Supported.
Not supported.
OPR (Operator Signal) message.
Supported.
Not supported.
SLB (Subscriber Local Busy) message.
Supported.
Not supported.
Consequently, SLB is
not in the list of the
possible UBM
messages.
STB (Subscriber Toll Busy) message.
Supported.
Not supported.
Consequently, STB is
not in the list of
possible UBM
messages.
UBM (Unsuccessful Backward Setup)
messages.
The UBM messages
are:
ACB, ADI, CFL, CGC,
DPN, EUM, LOS, NNC,
SEC, SLB, SSB, SST,
STB, and UNN.
The UBM messages
are:
ACB, ADI, CFL, CGC,
DPN, EUM, LOS, NNC,
SEC, SSB, SST, and
UNN.
DPC and OPC range fields.
760
Appendix B
TUP Addendum
Introduction
Introduction
This section introduces the HP OpenCall SS7 TUP system.
Overview
HP OpenCall SS7 TUP supports applications requiring access to the SS7
network via TUP. It relies on MTP Level 3 functionality to transfer its
messages through the SS7 network to the destination end point. As a
member of the HP OpenCall SS7 family, HP OpenCall SS7 TUP accesses
the SS7 network via an HP OpenCall SS7 stack.
Currently HP OpenCall SS7 TUP does not interface with SCCP, as most
applications do not require end-to-end signaling using SCCP services.
Software Versions
HP OpenCall SS7 TUP software supports the following flavors:
•
CTUP (China flavor)
•
ITUP (ITU-T flavor)
The description in this addendum applies to both flavors except where
the contrary is explicitly stated.
See also “Flavors Supported by HP OpenCall SS7 TUP” on page 759.
Software Components
HP OpenCall SS7 TUP contains both generic software components and
version specific software components.
HP OpenCall SS7 TUP is similar to HP OpenCall SS7 ISUP except TUP
has just 2 flavors and no message sets.
See also “Flavors Supported by HP OpenCall SS7 TUP” on page 759.
Appendix B
761
TUP Addendum
Introduction
The diagrams in this chapter 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).
762
Appendix B
TUP Addendum
Application Development Guidelines
This section contains general guidelines for developing applications on
top of the HP OpenCall SS7 TUP API.
The equivalent information for HP OpenCall SS7 ISUP is in Chapter 2,
“General System Guidelines.”
Designing for System Predictability
This is as for HP OpenCall SS7 ISUP, see “Designing for System
Predictability” on page 58.
This is as for HP OpenCall SS7 ISUP, see “Optimizing OS Performance”
on page 59.
This is as for HP OpenCall SS7 ISUP, see “Techniques for Performance
Optimization” on page 60.
This is as for HP OpenCall SS7 ISUP, see “System Test and Validation”
on page 61.
This is as for HP OpenCall SS7 ISUP, see “Object Orientation
Guidelines” on page 763.
Appendix B
763
TUP Addendum
The TUP API is available both as an archive library and as a shared
library.
To know the compile and link directives to use for the archive and shared
libraries, refer to the TUP API tutorial (see “TUP Tutorial Programs” on
page 899).
764
Appendix B
TUP Addendum
Using the API
Using the API
This section describes how to open, close, and use the SS7 stack
connection via the HP OpenCall SS7 TUP API.
“Using the ISUP API.”
Introduction
This is as for HP OpenCall SS7 ISUP, see “Introduction” on page 444.
Connections
This is as for HP OpenCall SS7 ISUP, see “Connections” on page 450.
SS7 Stack Access
This is as for HP OpenCall SS7 ISUP, see “SS7 Stack Access” on
page 451.
API Structure
This is as for HP OpenCall SS7 ISUP, see “API Structure” on page 460.
This is as for HP OpenCall SS7 ISUP, see “Outline of the Basic
Application” on page 463.
Initializing the IsupMgr Object
This is as for HP OpenCall SS7 ISUP, see “Initializing the IsupMgr
object” on page 464.
This is as for HP OpenCall SS7 ISUP, see “Creating and Opening a
Probe Object” on page 465.
Appendix B
765
TUP Addendum
Using the API
This is as for HP OpenCall SS7 ISUP, see “Scheduling Probe Objects” on
page 474.
This is as for HP OpenCall SS7 ISUP, see“Using the Activity Object” on
page 477.
This is as for HP OpenCall SS7 ISUP, see “Exchanging Messages via
Probe Objects” on page 481.
Closing and Destroying a Probe Object
This is as for HP OpenCall SS7 ISUP, see “Closing and Destroying a
Probe” on page 482.
oamReceive()
This is as for HP OpenCall SS7 ISUP, see “Receiving Notifications” on
page 484. However, the defaultGroup() accessor (referenced in the
IsupAdditional::NotifCics row of Table 12-2 on page 484) is
available in CTUP but not available in ITUP.
For detailed description of the accessor return types, consult the
IsupAdditionalInfo.h file located in the /opt/OC/include/TUP
directory.
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.
766
Appendix B
TUP Addendum
Using the API
This is as for HP OpenCall SS7 ISUP, see “Return Status Values” on
page 491.
This is as for HP OpenCall SS7 ISUP, see “Using Dynamic
Configuration” on page 494.
Appendix B
767
TUP Addendum
Exchanging Messages
Exchanging Messages
This section describes how to create, manipulate and exchange standard
ITU-T messages. It also describes the various primitives provided for
IsupSMProbe and IsupBPProbe objects.
“Exchanging ISUP Messages.”
Introduction
This is as for HP OpenCall SS7 ISUP, see “Introduction” on page 502.
This is as for HP OpenCall SS7 ISUP, see “Exchanging Primitives” on
page 503.
HP OpenCall SS7 TUP Primitives
This is as for HP OpenCall SS7 ISUP, see “HP OpenCall SS7 ISUP
Primitives” on page 504, except that the list of TUP primitives for State
Machine Mode is given in Table B-2 (for CTUP) and Table B-3 (for
ITUP).
State Machine Mode Primitives
Table B-2 lists the CTUP primitives for State Machine Mode. Note that
the equivalent primitives for ITUP are listed in Table B-3.
Table B-2
State Machine Mode Primitives (CTUP Only)
Primitive
CTUP
Message
SETUP_REQ
IAM or IAI
SETUP_IND
IAM or IAI
SETUP_RESP
ANN or ANC
SETUP_CONF
ANN or ANC
768
Comments
Appendix B
TUP Addendum
Exchanging Messages
Table B-2
State Machine Mode Primitives (CTUP Only) (Continued)
Primitive
CTUP
Message
This is sent by the application to
SETUP_IND primitive.
SETUP_IND_ACK
Comments
COT or CCF
CCR
CONNECT_LOOP_IND
DISABLE_ECHO_IND
REMOVE_LOOP_IND
REMOVE_LOOP_IND_ACK
ENABLE_ECHO_IND
ENABLE_ECHO_IND_ACK
This primitive is used to ask the
application to connect its tone loop
(Continuity-check procedures).
application to disable its echo
suppressor (Continuity-check
procedures).
application to remove its tone loop
application to enable its echo
suppressor (Continuity-check
procedures).
This primitive is used by the
application to signal that the
backward tone has been checked
application to connect its
transceiver (Continuity-check
procedures).
Appendix B
769
TUP Addendum
Exchanging Messages
Table B-2
Primitive
CTUP
Message
Comments
application to remove its
procedures).
application to start checking the
backward tone (Continuity-check
procedures).
application to stop checking the
backward tone (Continuity-check
procedures).
STOP_CHECK_TONE_IND
application to signal the
disappearance of the backward
tone.
TONE_DISAPPEARS_ACK
SOLICITED_INFO_REQ
GRQ
SOLICITED_INFO_IND
GRQ
SOLICITED_INFO_RESP
GSM
SOLICITED_INFO_CONF
GSM
ACM
CIP_IND
ACC
This is used to indicate the TUP
congestion level. It is equivalent
to ISUP REL with ACL.
User message
or MAL.
This primitive is used for
messages defined using the
customizing facility.
Note that MAL is not supported in
ITUP.
CIP_REQ
TUP_USR_MSG_REQ
TUP_USR_MSG_IND
770
Appendix B
TUP Addendum
Exchanging Messages
Table B-2
Primitive
RELEASE_REQ
RELEASE_IND
RELEASE_RESP
RELEASE_CONF
CTUP
Message
CLF, CBK, CCL,
or UBM*
RLG
* = where UBM is one of the
following: ACB, ADI, CFL, CGC, DPN,
EUM, LOS,
NNC, SEC, SLB,SSB, SST, STB, or
UNN.
RLG
This primitive is used to inform
the application that the current
call is being released.
START_RELEASE_IND
the application that the associated
circuit is being reset.
START_RESET_IND
START_RESET_IND_ACK
RESET_REQ
RSC or CLF
RESET_IND
RSC or CLF
RESET_RESP
RLG
RESET_CONF
RLG
GROUP_RESET_REQ
GRS
GROUP_RESET_IND
GRS
GROUP_RESET_RESP
GRA
GROUP_RESET_CONF
GRA
BLOCKING_REQ
BLO
BLOCKING_IND
BLO
BLOCKING_RESP
BLA
BLOCKING_CONF
BLA
Appendix B
Comments
771
TUP Addendum
Exchanging Messages
Table B-2
Primitive
CTUP
Message
UNBLOCKING_REQ
UBL
UNBLOCKING_IND
UBL
UNBLOCKING_RESP
UBA
UNBLOCKING_CONF
UBA
GROUP_BLOCKING_REQ
MGB
GROUP_BLOCKING_IND
MGB
GROUP_BLOCKING_RESP
MGA
GROUP_BLOCKING_CONF
MGA
MGU
MGU
MUA
MUA
HGB
HGB
HBA
HBA
HGU
HGU
HUA
HUA
SW_GROUP_BLOCKING_REQ
SGB
SW_GROUP_BLOCKING_IND
SGB
SW_GROUP_BLOCKING_RESP
SBA
SW_GROUP_BLOCKING_CONF
SBA
772
Comments
Appendix B
TUP Addendum
Exchanging Messages
Table B-2
Primitive
CTUP
Message
SW_GROUP_UNBLOCKING_REQ
SGU
SW_GROUP_UNBLOCKING_IND
SGU
SW_GROUP_UNBLOCKING_RESP
SUA
SW_GROUP_UNBLOCKING_CONF
SUA
INFORMATION_IND
SAM or SAO
INFORMATION_REQ
SAM or SAO
the maintenance system of a
particular event.
FORWARD_TRANSFER_REQ
FOT
FOT
OPERATOR_SIGNAL_REQ
OPR
OPERATOR_SIGNAL_IND
OPR
REANSWER_REQ
RAN
REANSWER_IND
RAN
METERING_PULSE_REQ
MPM
METERING_PULSE_IND
MPM
STOP_REQ
STOP_CONF
Appendix B
Comments
Note that OPR is not supported in
ITUP.
This primitive is used to issue a
metering pulse message (MPM) to
the application or to the network.
Note that MPM is not supported in
ITUP.
application to ask the TUP library
to stop re-transmitting
CFL/CLF/RSC messages concerning
a circuit to the SS7 network.
773
TUP Addendum
Exchanging Messages
Table B-2
CTUP
Message
Primitive
Comments
application to ask the TUP library
to stop re-transmitting
CFL/CLF/RSC/GRS/MGB/HGB/SGB
messages concerning a circuit
group to the SS7 network.
GROUP_STOP_REQ
GROUP_STOP_CONF
Table B-3 lists the ITUP primitives for State Machine Mode. Note that
the equivalent primitives for CTUP are listed in Table B-2.
Table B-3
State Machine Mode Primitives (ITUP Only)
Primitive
SETUP_REQ
SETUP_IND
SETUP_RESP
SETUP_CONF
ITUP Message
IAM or IAI
IAM or IAI
ANN, ANC, or ANU
ANN, ANC, or ANU
COT or CCF
CCR
774
Note that ANU is not
supported in CTUP.
This is sent by the application
to acknowledge a SETUP_IND
primitive.
SETUP_IND_ACK
CONNECT_LOOP_IND
Comments
This primitive is used to ask
the application to connect its
tone loop (Continuity-check
procedures).
Appendix B
TUP Addendum
Exchanging Messages
Table B-3
State Machine Mode Primitives (ITUP Only) (Continued)
Primitive
ITUP Message
Comments
DISABLE_ECHO_IND
the application to disable its
echo suppressor
(Continuity-check
procedures).
REMOVE_LOOP_IND
REMOVE_LOOP_IND_ACK
the application to remove its
tone loop (Continuity-check
procedures).
ENABLE_ECHO_IND
ENABLE_ECHO_IND_ACK
the application to enable its
echo suppressor
(Continuity-check
procedures).
application to signal that the
backward tone has been
checked (Continuity-check
procedures).
the application to connect its
procedures).
the application to remove its
procedures).
the application to start
checking the backward tone
(Continuity-check
procedures).
Appendix B
775
TUP Addendum
Exchanging Messages
Table B-3
Primitive
ITUP Message
Comments
STOP_CHECK_TONE_IND
the application to stop
checking the backward tone
(Continuity-check
procedures).
TONE_DISAPPEARS_ACK
Primitive used by the
application to signal the
backward tone.
SOLICITED_INFO_REQ
SOLICITED_INFO_IND
SOLICITED_INFO_RESP
SOLICITED_INFO_CONF
GRQ
GRQ
GSM
GSM
ACM
CIP_IND
CIP_REQ
ACC
This primitive is used to
indicate the TUP congestion
level (equivalent to the ISUP
REL with ACL).
TUP_USR_MSG_REQ
TUP_USR_MSG_IND
User message
A message defined via the
TUP message customizing
facility.
RELEASE_REQ
RELEASE_IND
RELEASE_RESP
RELEASE_CONF
CLF, CBK, CCL or UBM*
CLF, CBK, CCL or UBM*
RLG
RLG
* = where UBM is one of the
following: ACB, ADI, CFL, CGC,
DPN, EUM, LOS, NNC, SEC, SSB,
SST, or UNN.
START_RELEASE_IND
776
inform the application that
the current call is being
released.
Appendix B
TUP Addendum
Exchanging Messages
Table B-3
Primitive
ITUP Message
inform the application that
the associated circuit is being
reset.
START_RESET_IND
START_RESET_IND_ACK
RESET_REQ
RESET_IND
RESET_RESP
RESET_CONF
RSC or CLF
RSC or CLF
RLG
RLG
GROUP_RESET_REQ
GROUP_RESET_IND
GROUP_RESET_RESP
GROUP_RESET_CONF
GRS
GRS
GRA
GRA
BLOCKING_REQ
BLOCKING_IND
BLOCKING_RESP
BLOCKING_CONF
BLO
BLO
BLA
BLA
UNBLOCKING_REQ
UNBLOCKING_IND
UNBLOCKING_RESP
UNBLOCKING_CONF
UBL
UBL
UBA
UBA
GROUP_BLOCKING_REQ
GROUP_BLOCKING_IND
GROUP_BLOCKING_RESP
GROUP_BLOCKING_CONF
MGB
MGB
MBA
MBA
MGU
MGU
MUA
MUA
HGB
HGB
HBA
HBA
Appendix B
Comments
777
TUP Addendum
Exchanging Messages
Table B-3
Primitive
ITUP Message
HGU
HGU
HUA
HUA
SGB
SGB
SBA
SBA
SGU
SGU
SUA
SUA
INFORMATION_REQ
INFORMATION_IND
SAM or SAO
SAM or SAO
inform the maintenance
system of a particular event.
FOT
FOT
REANSWER_REQ
REANSWER_IND
RAN
RAN
STOP_REQ
STOP_CONF
778
Comments
application to ask the TUP
library to stop
re-transmitting CFL/CLF/RSC
to the SS7 network.
Appendix B
TUP Addendum
Exchanging Messages
Table B-3
Primitive
ITUP Message
Comments
application to ask the TUP
library to stop
re-transmitting
CFL/CLF/RSC/GRS/MGB/HGB/SGB
group to the SS7 network.
GROUP_STOP_REQ
GROUP_STOP_CONF
CHG or CCG or TRG
CHG or CCG or TRG
CHA or CCC or PCC
CHA or CCC or PCC
CHARGING_REQ
CHARGING_IND
CHARGING_RESP
CHARGING_CONF
Note that these primitives
and messages are not
supported in CTUP.
Bypass Mode
This is as for HP OpenCall SS7 ISUP, see “Bypass Mode” on page 523.
This is as for HP OpenCall SS7 ISUP, see “MTP Related Primitives” on
page 528.
This is as for HP OpenCall SS7 ISUP, see “Additional Information” on
page 524, except that the list of TUP primitives requiring Additional
Information is given in Table B-4.
Appendix B
779
TUP Addendum
Exchanging Messages
Table B-4
HP OpenCall SS7 TUP Primitives Requiring Additional
Information
Primitives
SETUP_FAILURE_IND
Additional
Information
Field
SetupFailure
setupFailureCause
Used for:
determining the reason for failure.
DUAL_SEIZURE
FLOW_CONTROL
BLOCKING
COT_FAILURE
RELEASE
TWCCR_TIMEOUT
CPC_BUSY
CRCR_RESET
START_RELEASE_IND
StartRelease
releaseCause
determining the reason for the release.
BLOCKING
CONTINUITY_SUCCESS
T2_TIMEOUT
T1_TIMEOUT
TWCLR_TIMEOUT
TWRAN_TIMEOUT
TWANN_TIMEOUT
START_RESET_IND
StartReset
resetCause
NO_REASON
UNEXPECTED_MESSAGE
T5_TIMEOUT
T7_TIMEOUT
COT_CC_NOT_REQUIRED
GRS_RANGE0
TIMER_SHORTAGE
RESET_IND
RESET_RESP
Reset
resetEvent
determining whether or not it is part of a
Group Reset operation.
GROUP_RESET
780
Appendix B
TUP Addendum
Exchanging Messages
Table B-4
Primitives
STOP_CONF
Information (Continued)
Additional
Information
LocalReset
Field
LocalresetCause
Used for:
GROUP_STOP_CONF
START_RESET_IND
MTP_UNAVAILABLE
DPC_UNAVAILABLE
BLS_STOPPED
CRS_STOPPED
CRCR_STOPPED
CGRS_STOPPED
MGBS_STOPPED
HGBS_STOPPED
SGBS_STOPPED
CRCS_STOPPED
Appendix B
781
TUP Addendum
Exchanging Messages
Table B-4
Information (Continued)
Primitives
Additional
Information
MAINTENANCE_SYSTEM
_IND
Maintenance
System
Field
maintenance
SystemEvent
Used for:
defining the event.
RECV_ON_UNEQUIPPED_CIRCUITM
N_BLOCKING
HW_BLOCKING
SW_BLOCKING
MN_UNBLOCKING
HW_UNBLOCKING
SW_UNBLOCKING
MN_GROUP_BLOCKING
HW_GROUP_BLOCKING
SW_GROUP_BLOCKING
MN_GROUP_UNBLOCKING
HW_GROUP_UNBLOCKING
SW_GROUP_UNBLOCKING
T5_TIMEOUT
T7_TIMEOUT
T8_TIMEOUT
T13_TIMEOUT
T16_TIMEOUT
T19_TIMEOUT
T22_TIMEOUT
T27_TIMEOUT
T29_TIMEOUT
T33_TIMEOUT
T35_TIMEOUT
T39_TIMEOUT
T41_TIMEOUT
T12_NOT_RUNNING
T15_NOT_RUNNING
T21_NOT_RUNNING
T26_NOT_RUNNING
T28_NOT_RUNNING
T32_NOT_RUNNING
T34_NOT_RUNNING
T38_NOT_RUNNING
T40_NOT_RUNNING
COT_RECEIVED
CLF_RECEIVED
TIMER_SHORTAGE
782
Appendix B
TUP Addendum
Exchanging Messages
HP OpenCall SS7 TUP Message Management
Overview
The rules and hypothesis for the TUP message management are:
•
The encoder/decoder functions are flavor dependent (for example,
CTUP). The source code is not generated by software.
•
The new local representation mechanism is generic for TUP. It gives
fast access to each message parameter.
•
Specific message parameter accessors are available to:
— Get a parameter value.
— Set a parameter value.
— Mark an optional parameter as not present.
— Check optional parameter presence.
Appendix B
•
No method is provided to install new message parameters.
•
Supports non-standard TUP messages (User messages).
•
Segmented messages are not supported.
•
Multiple instances of a message parameter are not possible in the
TUP protocol and therefore it is not necessarily supported.
783
TUP Addendum
Exchanging Messages
Table B-5 lists the classes from the ISUP message module that have been
adapted for TUP.
Table B-5
Adaptation of HP OpenCall SS7 ISUP Message Classes
ISUP Class
TUP Class
Purpose
IsupInfoMgr
IsupInfoMgr
Used by the message module to manage its internal
global data.
IsupMsg
IsupMsg
Pure virtual class defining a generic interface to all
TUP messages. It is intended to be specialized to
define instances of specific TUP messages with a
specific accessor interface.
IsupIam,
IsupAcm,
...
TupXXX
(examples:
IsupIam, TupIAI,
TupAcm, …)
Specialization of the IsupMsg. Instances of specific
TUP messages with a specific accessor interface.
IsupUserMsg
TupUserMsg
Specialization of the IsupMsg. This class is used to
support non-standard TUP messages.
Encoding/Decoding TUP Messages
The decoding operation of a TUP message is done just once. After the
decoding operation, a local representation (LR) mechanism is
implemented to store all the parameters in memory. The parameter
values can then be accessed directly without having to do any more
decoding. Each message supported by the TUP library has its own local
representation (LR) in memory.
Operations Performed by the decode() Function
The decode() function performs the following operations:
Step 1. Decode the message type (H0/H1).
Step 2. Initialize the LR data corresponding to the current message type.
Step 3. Set the message LR description area to zero.
Step 4. Decode each parameter:
•
784
Read the PDU message.
Appendix B
TUP Addendum
Exchanging Messages
•
Update the LR description area.
•
Fill the LR data area.
Operations Performed by the encode() Function
The encode() function performs the following operations:
Step 1. Initialize the PDU data.
Step 2. Read the current message LR description area for each parameter (from
index 0 to the maximum number of parameters):
•
if the parameter is present, fill the PDU message with the data in LR
data area.
•
go to the next parameter.
Parameter Checking
The TUP encoder/decoder only checks that the message format is
compatible with the TUP format specification as regards parameter
lengths and the presence of mandatory parameters. However, the actual
parameter values are not verified (for example, reserved values are not
verified).
Encoding/decoding operations stop as soon as an error is detected. In this
case, an ENCODING_ERROR/DECODING_ERROR error is returned.
Accessors for TUP Messages
The TupXXX classes (for example: TupAcm) offer specific accessors to
message parameters. Two kinds of parameters are defined: mandatory
and optional.
The mandatory parameter accessors are used to get and set a parameter
value.
For optional parameters, two accessors are added. One accessor is to test
the presence of the parameter, and the other is to mark it as not being
present.
Parameters values are contained in ISUP::ParmValue class objects. The
access result is returned in ISUP::MsgStatus class objects. These object
are identical to those used in the ISUP library.
The specific accessors prototypes are shown below.
Appendix B
785
TUP Addendum
Exchanging Messages
Set Value Accessor
To set the paramName parameter value in a TupXXX message:
TupXXX * TupXXX::paramName(ISUP::ParmValue& P_sVal,
ISUP::MsgStatus& P_status)
Get Value Accessor
To get the paramName parameter value from a TupXXX message:
ISUP::ParmValue* TupXXX::paramName(ISUP::MsgStatus&
P_status) const
Check Value Accessor
To check for the presence of the paramName parameter in a TupXXX
message:
HPAIN::Boolean TupXXX::paramNameIsPresent(ISUP::MsgStatus&
P_status) const
Mark as Absent Accessor
To mark the paramName parameter as not present in a TupXXX message:
void TupXXX::paramNameSetAbsent(ISUP::MsgStatus& P_status)
Parameter With an Invalid Length
If a parameter value is given an invalid length, the API behaves as
follows:
•
If a parameter is given a value of length less than the minimum
parameter length, then the parameter value is extended with 0s to
the minimum parameter length. No error is returned.
•
If a parameter is given a value of length greater than the minimum
parameter length, then the error INVALID_LENGTH is returned.
TUP User Message
This is implemented as a TUP standard message with only two
parameters: UserParamMsgType and UserParam. These parameters,
supplied by the application, represent respectively the message type
(H0/H1) and the parameter area of the message the user wants to send to
the provider. No check is performed by the TUP encoder.
786
Appendix B
TUP Addendum
Exchanging Messages
The userParam parameter can contain any kind of TUP parameter. Its
maximum size is the maximum size of the parameter area in a TUP
message.
TUP Message Class Naming Convention
The TUP message class general naming convention is as follows:
•
All classes that correspond to messages that exist in both the ISUP
and the TUP protocols keep the name used in the ISUP library. For
example: IsupIam, IsupAcm, etc.
•
TUP messages that do not exist in ISUP have their corresponding
class named TupXXX. For example: TupIai, TupCcf, …
TUP Message Module Classes
Table B-6 lists the TUP message module classes.
Table B-6
TUP Message Module Classes
Item
Comment
TUP class: IsupInfoMgr
Corresponding ISUP
class
IsupInfoMgr
Purpose
Class used by message module to manage its internal global
data.
Main Changes
All methods related to message setting are deleted.
All methods related to ASN.1+ tags are deleted.
Main Methods
init(): initialize LR memory, call to the init() methods of
IsupMsg
end(): end with the IsupMsg class.
setTraceOn/Off(): start/stop decoding / encoding tracing;
call to the setTraceOn/Off() methods of IsupMsg.
TUP class: IsupMsg
Corresponding ISUP
class
Appendix B
IsupMsg
787
TUP Addendum
Exchanging Messages
Table B-6
TUP Message Module Classes (Continued)
Item
Comment
Purpose
Pure virtual class defining a generic interface to all TUP
messages. It is intended to be specialized to define instances
of specific TUP messages with a specific accessor interface.
Main Changes
TUP LR management: encoding / decoding, accessors.
All methods related to ASN.1+ tags are deleted.
IsupMsg is not an inherited class (from the BF class).
PDU data management: this is managed by the class itself.
Main Methods
init(): initialize LR memory for all message type supported
(call to init() methods of TupXXX).
end(): end with TupXXX classes.
encode(): encode PDU from message LR representation
(virtual method).
decode(): decode PDU and get message LR representation.
getPDU(): copy associate PDU into given buffer.
freePDU(): free the associated PDU memory.
setPDU(): associate given PDU to the message.
getMsgType(): get the type of the current message (IAM, …).
setMsgType(): set the message type.
setTraceOn/Off(): start/stop tracing in encode() and
decode() methods.
TUP class: TupXXX
(where XXX represents the message type, and the TUP message class general naming
convention (see “TUP Message Class Naming Convention” on page 787) applies.
Corresponding ISUP
class
788
IsupIam,...
Appendix B
TUP Addendum
Exchanging Messages
Table B-6
TUP Message Module Classes (Continued)
Item
Comment
Purpose
Specialization of the IsupMsg class. Instances of specific TUP
messages with a specific accessor interface.
Main Methods
castMsg(): casts a generic IsupMsg object into a TupXXX
object.
Specific accessors: get, set, check / set presence of a
parameter.
encode(): encode PDU from message LR representation.
init(): initialize the LR data pointers and areas.
end(): free associated LR memory.
TUP class: TupUserMsg
Corresponding ISUP
class
IsupUserMsg
Purpose
Specialization of the IsupMsg class. This class is used to
support non-TUP standard messages.
Main Changes
This class is defined in exactly the same way as the TupXXX
classes.
Main Methods
These are the same as for the TupXXX classes.
TUP Message Description (API)
When a parameter exists in both the ISUP and the TUP protocols, then
its name is the ISUP one. In this case, if the TUP parameter name is
different from the ISUP one, then the TUP name is given in the
Parameter Type column.
Appendix B
789
TUP Addendum
Exchanging Messages
The parameter formats are those defined in Q783. However, in order to
facilitate decoding and encoding, the format used for
calledPartyNumber and subsequentNumber parameters in the IAI, IAM
and SAM messages is as shown in Table B-7.
Table B-7
Format for calledPartyNumber and
subsequentNumber Parameters
Byte
first byte
Bits
bits HGFE
bits DCBA
subsequent bytes
Meaning
number of address signals
sub-field.
Not significant.
address digits
All mandatory parameters of a message must be set before sending the
message to the TUP library. Otherwise, an ENCODING_ERROR error is
returned.
Table B-8 lists all the CTUP messages classes and their associated
accessors provided by the HP OpenCall SS7 TUP API. The equivalent
information for ITUP is given in Table B-9.
Table B-8
Message Classes and Accessors (CTUP Only)
Message
Class
Parameter Name
Parameter Type
TupAcb
-
-
TupAcc
automCongestionLevel
Mandatory,
Fixed length, "Message Indicators"
IsupAcm
backwardCallIndicators
Mandatory,
Fixed length, "Message Indicators"
TupAdi
-
-
TupAnc
-
-
TupAnn
-
-
IsupBla
-
-
IsupBlo
-
-
790
Appendix B
TUP Addendum
Exchanging Messages
Table B-8
Message Classes and Accessors (CTUP Only) (Continued)
Message
Class
Parameter Name
Parameter Type
TupCbk
-
-
TupCcf
-
-
TupCcl
-
-
IsupCcr
-
-
TupCfl
-
-
TupCgc
-
-
TupClf
-
-
IsupCot
-
-
TupDpn
-
-
TupEum
octetIndicator
signallingPointCode
Mandatory, Fixed length
IsupFot
-
-
IsupGra
rangeAndStatus
Mandatory, Variable length
TupGrq
requestTypeIndicators
IsupGrs
rangeAndStatus
TupGsm
responseTypeIndicator
callingPartysCategory
callingPartyNumber
Optional, Fixed length
Optional, Variable length,
"Calling Line Identity"
subfield of "Incoming Trunk and
Transit Exchange Identity"
subfield of "Incoming Trunk and
Transit Exchange Identity"
Optional, Variable length, "Original
Called Address"
transitExchangeIdentity
incomingTrunkIdentity
originalCalledNumber
Appendix B
791
TUP Addendum
Exchanging Messages
Table B-8
Message
Class
Parameter Name
Parameter Type
TupHba
rangeAndStatus
TupHgb
rangeAndStatus
TupHgu
rangeAndStatus
TupHua
rangeAndStatus
TupIai
messageIndicators
calledPartyNumber
Mandatory, Variable length, "Number
Of Address Signals" + "Address Signals"
Optional, Variable length, "Calling Line
Identity"
Called Address"
callingPartyNumber
IsupIam
messageIndicators
calledPartyNumber
TupLos
-
-
TupMal
-
-
TupMba
rangeAndStatus
TupMgb
rangeAndStatus
TupMgu
rangeAndStatus
TupMpm
chargingInformation
TupMua
rangeAndStatus
TupNnc
-
-
TupOpr
-
-
TupRan
-
-
TupRlg
-
-
792
Appendix B
TUP Addendum
Exchanging Messages
Table B-8
Message
Class
Parameter Name
Parameter Type
IsupRsc
-
-
IsupSam
subsequentNumber
Mandatory, Variable length, "Address
Signals"
TupSao
subsequentNumber
Mandatory, Fixed length, "Address
Signals"
TupSba
rangeAndStatus
TupSec
-
-
TupSgb
rangeAndStatus
TupSgu
rangeAndStatus
TupSlb
-
-
TupSsb
-
-
TupSst
-
-
TupStb
-
-
TupSua
rangeAndStatus
IsupUba
-
-
IsupUbl
-
-
TupUnn
-
-
IsupUserMsg
messageType
userParam
Mandatory, Fixed length (H0/H1)
Optional, Variable length
Appendix B
793
TUP Addendum
Exchanging Messages
Table B-9 lists all the ITUP messages classes and their associated
accessors provided by the HP OpenCall SS7 TUP API. The equivalent
information for CTUP is given in Table B-8.
Table B-9
Message Classes and Accessors (ITUP Only)
Message
Class
Parameter Name
Parameter Type
TupAcb
-
-
TupAcc
automCongestionLevel
Mandatory, Fixed length, "Message
Indicators"
IsupAcm
backwardCallIndicators
Mandatory, Fixed length, "Message
Indicators"
TupAdi
-
-
TupAnc
-
-
TupAnn
-
-
TupAnu
-
-
IsupBla
-
-
IsupBlo
-
-
TupCbk
-
-
TupCcf
-
-
TupCcc
chargingUnitIndicators
Mandatory, Fixed length, "Charging
Unit field"
TupCcg
collectionIndicators
Mandatory, Fixed length, "Collection
field"
TupCcl
-
-
IsupCcr
-
-
TupCfl
-
-
TupCgc
-
-
TupCha
-
-
794
Appendix B
TUP Addendum
Exchanging Messages
Table B-9
Message Classes and Accessors (ITUP Only) (Continued)
Message
Class
Parameter Name
Parameter Type
packetChargingA
tariffIndicatorsA
tariffFactorA
timeIndicator (*see the
Note following this table)
packetChargingB
tariffIndicatorsB
tariffFactorB
Optional, Fixed length, "Packet
charging A"
Optional, Fixed length, "Tariff
Indicators A"
Optional, Fixed length, "Tariff Factor A"
Optional, Fixed length, "Time indicator"
TupClf
-
-
IsupCot
-
-
TupDpn
-
-
TupEum
octetIndicator
signallingPointCode
IsupFot
-
-
IsupGra
rangeAndStatus
TupGrq
requestTypeIndicators
IsupGrs
rangeAndStatus
TupChg
Appendix B
Optional, Fixed length, "Packet
charging B"
Optional, Fixed length, "Tariff
Indicators B"
Optional, Fixed length, "Tariff Factor B"
795
TUP Addendum
Exchanging Messages
Table B-9
Message
Class
TupGsm
Parameter Name
responseTypeIndicator
callingPartyNumber
transitExchangeIdentity
incomingTrunkIdentity
Parameter Type
Optional, Fixed length
Identity"
Optional, Variable length, subfield of
"Incoming Trunk and Transit Exchange
Identity"
Optional, Variable length, subfield of
"Incoming Trunk and Transit Exchange
Identity"
Called Address"
TupHba
rangeAndStatus
TupHgb
rangeAndStatus
TupHgu
rangeAndStatus
TupHua
rangeAndStatus
TupIai
messageIndicators
calledPartyNumber
Mandatory, Variable length, "Number
Of Address Signals" + "Address Signals"
Optional, Fixed length, "Closed User
Group Information "
Identity"
Called Address"
CUGinterlockCode
callingPartyNumber
IsupIam
messageIndicators
calledPartyNumber
TupLos
-
-
TupMba
rangeAndStatus
796
Appendix B
TUP Addendum
Exchanging Messages
Table B-9
Message
Class
Parameter Name
Parameter Type
TupMgb
rangeAndStatus
TupMgu
rangeAndStatus
TupMua
rangeAndStatus
TupNnc
-
-
TupPcc
chargingUnitIndicators
Mandatory, Variable length, "Charging
unit field"
TupRan
-
-
TupRlg
-
-
IsupRsc
-
-
IsupSam
subsequentNumber
Mandatory, Variable length, "Address
Signals"
TupSao
subsequentNumber
Mandatory, Fixed length, "Address
Signals"
TupSba
rangeAndStatus
TupSec
-
-
TupSgb
rangeAndStatus
TupSgu
rangeAndStatus
TupSsb
-
-
TupSst
-
-
TupSua
rangeAndStatus
TupTrg
tariffIndicators
tariffFactor
timeIndicator (*see the
Note following this table)
Mandatory, Fixed length, "Tariff
indicators"
Optional, Fixed length, "Tariff factor"
Mandatory, Fixed length, "Time
indicator"
Appendix B
797
TUP Addendum
Exchanging Messages
Table B-9
Message
Class
Parameter Name
Parameter Type
IsupUba
-
-
IsupUbl
-
-
TupUnn
-
-
IsupUserMsg
messageType
userParam
Mandatory, Fixed length (H0/H1)
Optional, Variable length
NOTE
(*) The timeIndicator parameter is coded on one byte. The shift of 2
bits is done by the encode() and decode() methods.
Rounding a Parameter Length
If a parameter length does not correspond to an exact number of bytes,
the length is rounded to the upper number of bytes.
In this case, the significant bits are placed starting from the least
significant bit of the parameter.
For example, in an IAI message the callingPartysCategory parameter
is 6 bits long. You set the callingPartysCategory parameter to 000001
in an IAI as follows:
TupIaiObject->callingPartysCategory(ParmValueObject->assign("\x01",1),
MsgStatusObject);
If the callingPartysCategory parameter is 000001 in a received IAI
message, the ParmValue returned by the get accessor will be one byte
long: 0x01:
ParmValueObject = TupIaiObject->callingPartysCategory (MsgStatusObject);
798
Appendix B
TUP Addendum
Exchanging Messages
HP OpenCall SS7 TUP 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 TUP API.
The decision to release a circuit is the responsibility of the application.
HP OpenCall SS7 TUP handles all new message exchanges on this
circuit by implementing an Automated Call Release (ACR) State
Machine. This state machine processes all the incoming messages
related to the circuit being released.
Figure B-1
Successful Automated Call Release
NOTE
In Figure B-1, the asterisk (*) after CFL means that this message type
can be configured using the ACRReleaseMessage field in the Tup_Global
section of the tup.conf file. The allowed message types are: ACB, CBK,
CFL, CGC, LOS, NNC, and SEC. The default message type is CFL.
Appendix B
799
TUP Addendum
Exchanging Messages
Figure B-2
Unsuccessful Automated Call Release
NOTE
In Figure B-2, the asterisk (*) after ACB means that this message type
can be configured using the ACRReleaseMessage field in the Tup_Global
section of the tup.conf file. The allowed message types are: ACB, CBK,
CFL, CGC, LOS, NNC, and SEC. The default message type is CFL.
The double asterisk (**) after T3 started means that if the message type
CFL is used, the timers started are T4 and T5 and not T3.
800
Appendix B
TUP Addendum
Exchanging Messages
ACR State Machine
When started, the ACR State Machine initiates a release by sending an
ACB message as shown in Figure B-2.
If no RLG arrives before T3 expires, HP OpenCall SS7 TUP sends a CFL.
If no RLG arrives before T4 expires, HP OpenCall SS7 TUP sends another
CFL. This is repeated for n attempts until T5 expires. If no RLG arrives
before T5 expires, HP OpenCall SS7 TUP sends an RSC. If no RLG arrives
before T18 expires, HP OpenCall SS7 TUP sends another RSC. This is
repeated for n attempts until T19 expires. If no RLG is received before
T19 expires, HP OpenCall SS7 TUP just locally resets the circuit (same
as a STOP_REQ procedure) and returns to idle. The circuit is now
available for future call attempts.
This is as for HP OpenCall SS7 ISUP, see in “Return Status Values” on
page 549.
Appendix B
801
TUP Addendum
Managing HP OpenCall SS7 TUP
This section contains management guidelines for use in developing the
application.
“Managing HP OpenCall SS7 ISUP.”
Overview
This is as for HP OpenCall SS7 ISUP, see “Overview” on page 552.
This is as for HP OpenCall SS7 ISUP, see “Managing Race Conditions”
on page 553.
This is as for HP OpenCall SS7 ISUP, see “Managing Memory Space” on
page 554.
This is as for HP OpenCall SS7 ISUP, see “Managing Object Memory” on
page 555.
This is as for HP OpenCall SS7 ISUP, see“Handling IPC Buffers” on
page 557.
802
Appendix B
TUP Addendum
Congestion and Flow Control
IPC Flow Control
This is as for HP OpenCall SS7 ISUP, see “IPC Flow Control” on
page 559, except for the section Outbound Path, which is as follows.
Outbound Path
The following primitives are accepted by HP OpenCall SS7 TUP in the
IPC congested state:
1. Primitives aimed at terminating a call:
RELEASE_RESP
2. Primitives aimed at resetting a circuit:
START_RESET_IND_ACK
RESET_RESP
3. Primitives aimed at stopping CFL/CLF/RSC retransmission on a circuit:
STOP_REQ
Automatic Congestion Control
The ACC message is sent from the overloaded end on reception of the CLF
message and before sending the RLG message. Two levels of congestion
can be indicated in the ACC message.
On receipt of the ACC message, the TUP layer sends a (CIP_IND)
Congestion Indication Primitive to the application that is to manage
traffic reduction. The procedure used to reduce traffic depends on the
implementation.
Appendix B
803
TUP Addendum
Figure B-3
Automatic Congestion Control - Outgoing Side
Figure B-4
Automatic Congestion Control - Incoming Side
804
Appendix B
TUP Addendum
This is as for HP OpenCall SS7 ISUP, see “Managing Circuit States” on
page 562, except for the state values (visible and manageable by
applications) shown below.
Available Circuit States
Appendix B
•
IDLE
•
IDLE_MN_LOCALLY_BLOCKED
•
IDLE_MN_REMOTELY_BLOCKED
•
IDLE_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
BUSY_INCOMING_ACTIVE
•
BUSY_INCOMING_MN_LOCALLY_BLOCKED
•
BUSY_INCOMING_MN_REMOTELY_BLOCKED
•
BUSY_INCOMING_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
BUSY_OUTGOING_ACTIVE
•
BUSY_OUTGOING_MN_LOCALLY_BLOCKED
•
BUSY_OUTGOING_MN_REMOTELY_BLOCKED
•
BUSY_OUTGOING_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_HW_LOCALLY_BLOCKED
•
IDLE_HW_REMOTELY_BLOCKED
•
IDLE_HW_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_HW_MN_LOCALLY_BLOCKED
•
IDLE_HW_MN_REMOTELY_BLOCKED
•
IDLE_HW_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_HW_LOCALLY_BLOCKED_MN_REMOTELY_BLOCKED
•
IDLE_HW_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED
•
IDLE_HW_LOCALLY_BLOCKED_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_HW_LOCALLY_AND_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED
•
IDLE_HW_LOCALLY_AND_REMOTELY_BLOCKED_MN_REMOTELY_BLOCKED
805
TUP Addendum
806
•
IDLE_HW_REMOTELY_BLOCKED_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_HW_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_HW_LOCALLY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_HW_MN_LOCALLY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_HW_MN_LOCALLY_AND_REMOTELY_BLOCKE
D
•
IDLE_SW_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED_HW_LOCALLY_AND
_REMOTELY_BLOCKED
•
IDLE_SW_REMOTELY_BLOCKED_HW_LOCALLY_BLOCKED_MN_LOCALLY_AND
_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_HW_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_HW_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_MN_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_HW_MN_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_HW_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_MN_REMOTELY_BLOCKED_HW_LOCALLY_AND
_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_BLOCKED_HW_REMOTELY_BLOCKED_MN_LOCALLY_AND
_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_HW_LOCALLY_BLOCKED
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_MN_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_HW_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_HW_MN_LOCALLY_BLOCKED
Appendix B
TUP Addendum
Appendix B
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_HW_MN_REMOTELY_BLOCKE
D
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_HW_LOCALLY_BLOCKED_MN
_REMOTELY_BLOCKED
•
IDLE_SW_LOCALLY_AND_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED_HW
_REMOTELY_BLOCKED
•
IDLE_SW_MN_REMOTELY_BLOCKED
•
IDLE_SW_MN_REMOTELY_BLOCKED_HW_LOCALLY_AND_REMOTELY_BLOCKE
D
•
IDLE_SW_MN_REMOTELY_BLOCKED_HW_LOCALLY_BLOCKED
•
IDLE_SW_MN_LOCALLY_BLOCKED
•
IDLE_SW_MN_LOCALLY_BLOCKED_HW_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_MN_LOCALLY_BLOCKED_HW_REMOTELY_BLOCKED
•
IDLE_SW_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_MN_LOCALLY_AND_REMOTELY_BLOCKED_HW_LOCALLY_BLOCKED
•
IDLE_SW_MN_LOCALLY_AND_REMOTELY_BLOCKED_HW_REMOTELY_BLOCKE
D
•
IDLE_SW_HW_REMOTELY_BLOCKED
•
IDLE_SW_HW_REMOTELY_BLOCKED_MN_LOCALLY_AND_REMOTELY_BLOCKE
D
•
IDLE_SW_HW_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED
•
IDLE_SW_HW_LOCALLY_BLOCKED
•
IDLE_SW_HW_LOCALLY_BLOCKED_MN_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_HW_LOCALLY_BLOCKED_MN_REMOTELY_BLOCKED
•
IDLE_SW_HW_LOCALLY_AND_REMOTELY_BLOCKED
•
IDLE_SW_HW_LOCALLY_AND_REMOTELY_BLOCKED_MN_LOCALLY_BLOCKED
•
IDLE_SW_HW_LOCALLY_AND_REMOTELY_BLOCKED_MN_REMOTELY_BLOCKE
D
•
IDLE_SW_HW_MN_REMOTELY_BLOCKED
•
IDLE_SW_HW_MN_LOCALLY_BLOCKED
•
IDLE_SW_HW_MN_LOCALLY_AND_REMOTELY_BLOCKED
807
TUP Addendum
These visible circuit states do not represent exactly the internal call
states, but are deduced from them by using the following rules:
808
•
The circuit is considered as IDLE until the setup procedure is
completed.
•
The circuit is considered as BUSY_INCOMING_XXX when the call state
(CPC) is IGC answered.
•
The circuit is considered as BUSY_OUTGOING_XXX when the call state
(CPC) is OGC answered.
•
The circuit is considered as XXX_LOCALLY_BLOCKED when the BLS
state is locally_blocked.
•
The circuit is considered as XXX_REMOTELY_BLOCKED when the BLR
state is remotely_blocked.
•
The circuit is considered as XXX_HW_LOCALLY_BLOCKED when the HLB
•
The circuit is considered as XXX_HW_REMOTELY_BLOCKED when the
HRB state is remotely_blocked.
•
The circuit is considered as XXX_SW_LOCALLY_BLOCKED when the SLB
•
The circuit is considered as XXX_SW_REMOTELY_BLOCKED when the
SRB state is remotely_blocked.
Appendix B
TUP Addendum
The SetCircuitState() and GetCircuitState() are methods of
IsupSMProbe object class. They are used by the application to set and get
the circuit states. The SetCircuitState() method works only on the
secondary HP OpenCall SS7 TUP connection.
This is as for HP OpenCall SS7 ISUP, see “Developing a Circuit Update
Mechanism” on page 564.
Appendix B
809
TUP Addendum
Introduction to TUP Procedures
This section contains information about TUP procedures, including
FSMs and interaction with the MTP layer.
“Introduction to ISUP Procedures.”
The supported State Machines are those described in ITU-T Q724.
Table B-10 lists the HP OpenCall SS7 TUP FSMs supported and
includes comments where applicable.
Table B-10
Supported Finite State Machines (FSMs)
Acronym
Comments
Signaling Procedure Control
MSDC
Does not exist in Q724; adapted from ISUP.
MDSC
Call Processing Control
CPCI
Does not exist in Q724.
CPCO
Does not exist in Q724.
Circuit Supervision Control
810
BLR
Blocking and unblocking signal reception.
BLS
Blocking and unblocking signal sending.
CCI
Continuity-check incoming.
CCO
Continuity-check outgoing.
CGRR
Circuit group reset receipt.
CGRS
Circuit group reset sending.
Appendix B
TUP Addendum
Table B-10
Supported Finite State Machines (FSMs)
Acronym
Appendix B
Comments
CRI
Continuity recheck incoming.
Equivalent to ISUP ITU-88 CRCR.
CRO
Continuity recheck outgoing.
Equivalent to ISUP ITU-88 CRCS.
CRR
Circuit reset receipt.
CRS
Circuit reset sending.
MBUR
Maintenance generated circuit group blocking and
unblocking receipt. Equivalent to ISUP ITU-88 MGBR.
MBUS
Maintenance generated circuit group blocking and
unblocking sending. Equivalent to ISUP ITU-88 MGBS.
HBUR
Hardware generated circuit group blocking and
unblocking receipt. Equivalent to ISUP ITU-88 HGBR.
HBUS
Hardware generated circuit group blocking and
unblocking sending. Equivalent to ISUP ITU-88 HGBS.
SBUR
Software generated circuit group blocking and
unblocking receipt.
SBUS
Software generated circuit group blocking and
unblocking sending.
HRB
Hardware remotely blocking.
HLB
Hardware locally blocking.
SRB
Software remotely blocking.
Equivalent to the HRB state machine except it is for a
software blocking operation.
SLB
Software locally blocking.
Equivalent to the SLB state machine except it is for a
software blocking operation.
811
TUP Addendum
This is as for HP OpenCall SS7 ISUP, see “Interaction Scenarios” on
page 573.
This is as for HP OpenCall SS7 ISUP, see “MTP3 Interaction Handling”
on page 574.
This is as for HP OpenCall SS7 ISUP, see “Remote DPC Status
Indications” on page 578.
Generic Primitive Processing (State Machine Probe)
This is as for HP OpenCall SS7 ISUP, see “Generic Primitive Processing
(State-machine Probe)” on page 581.
This is as for HP OpenCall SS7 ISUP, see “Generic Primitive Processing
(Bypass Probe)” on page 583.
Generic TUP Message Handling (State Machine
Probe)
This is as for HP OpenCall SS7 ISUP, see “Generic ISUP Message
Handling (State-machine Probe)” on page 585.
Generic TUP Message Handling (Bypass Probe)
This is as for HP OpenCall SS7 ISUP, see “Generic ISUP Message
Handling (Bypass Probe)” on page 586.
812
Appendix B
TUP Addendum
Generic TUP Circuit Group Message Handling
The circuit group messages that are supported in TUP are:
•
GRS/GRA (Group Reset)
•
HGB/HGA (Hardware Group Blocking)
•
HGU/HUA (Hardware Group Unblocking)
•
MGB/MGA (Maintenance Group Blocking)
•
MGU/MUA (Maintenance Group Unblocking)
•
SGB/SBA (Software Group Blocking)
•
SGU/SUA (Software Group Unblocking)
They all contain a rangeAndStatus parameter which determines which
circuits belong to the group. In addition to the generic processing
described above, the rangeAndStatus parameter in an incoming
message is interpreted as described below.
To be taken into account, group messages such as GRS, HGB, HGU, MGB,
MGU, SGB, and SGU must be sent twice in less than 5 seconds. At the
receiving side, if two messages of the same kind are received within 5
seconds but with different rangeAndStatus parameters, the first
message received is ignored and the HP OpenCall SS7 TUP layer will
wait for a message identical to the last one received.
In addition to the generic processing described above, the
rangeAndStatus parameter in an incoming message is interpreted as
follows:
•
range = 0 is a reserved value.
•
if range is not 0, its maximum value is 23 (national). The value 31
Table B-11 shows how the CIC label is interpreted in the
rangeAndStatus parameter.
Appendix B
813
TUP Addendum
Table B-11
Interpreting the CIC Label in the rangeAndStatus Parameter
TUP
Message
range = 0
CIC Label
range !=0
CIC Label
GRS
Representative
CIC within the
CIC group.
No status field
related to the
pre-determined
CIC group.
First CIC within
the CIC group,
or within that
part of the CIC
group.
No status field
related to whole
CIC group.
GRA
This is as for
GRS.
This is as for
GRS.
This is as for
GRS.
Related to a
whole CIC
group. Number
of consecutive
CICs to be
handled = Range
+ 1.
Domain =
[2..256].
Status field
indicates the
status for each
CIC in the Label
up to 256.
814
Appendix B
TUP Addendum
Table B-11
TUP
Message
Interpreting the CIC Label in the rangeAndStatus Parameter
range = 0
CIC Label
HGB, HGU,
MGB, MGU,
SGB, SGU
Representative
CIC within the
CIC group.
range !=0
CIC Label
No status field
included related
to the
pre-determined
CIC group.
First CIC within
the CIC group,
or within that
part of the CIC
group.
Related to a
whole CIC
group. Number
of consecutive
CICs to be
handled = Range
+ 1.
Domain =
[2..256].
Status field
indicates the
status for each
CIC in the Label
up to 256.
HGA, HUA,
MBA, MUA,
SBA, SUA
Representative
CIC within the
CIC group.
No status field
included related
to the
pre-determined
CIC group.
First CIC within
the CIC group,
or within that
part of the CIC
group.
Related to a
whole CIC
group. Number
of consecutive
CICs to be
handled = Range
+ 1.
Domain =
[2..256].
Status field
indicates the
status for each
CIC in the Label
up to 256.
Appendix B
815
TUP Addendum
Call Control
Call Control
This section describes how HP OpenCall SS7 TUP behaves when
controlling call setup and call teardown procedures.
The equivalent information for HP OpenCall SS7 ISUP is in the
following chapters:
•
Chapter 16, “ISUP Call Control - Procedures Common to ANSI and
ITU-T,”
•
•
Chapter 18, “ISUP Call Control - Procedures Specific to ITU-T.”
For each procedure, this section provides:
•
message and primitive flow
•
circuit states and timer activity
The diagrams in this section use the following convention:
Prmt_Name(xxx)
where: Prmt_Name is the primitive name and xxx is the message type.
Call setup is triggered when a message from the application is received
by the TUP library containing the SETUP_REQ primitive and IAM (or IAI).
The request to setup a call may be unsuccessful due to various factors,
such as failure to receive a specific TUP message or dual seizure.
The following scenarios illustrate the behavior of the TUP library in
these various circumstances.
Setup Request Locally Refused by HP OpenCall SS7 TUP
The application issues a SETUP_REQ to HP OpenCall SS7 TUP.
The primitive is locally rejected.
Refer to the HP OpenCall SS7 TUP API man pages for details on how
the failure condition is reported to the application.
This situation occurs in the following cases:
816
Appendix B
TUP Addendum
Call Control
Figure B-5
•
the (DPC, CIC) does not correspond to a valid configured circuit
•
the circuit is reserved for inbound traffic
•
the circuit is busy
•
the circuit is under reset
•
the IAM (or IAI) message cannot be encoded
•
the IPC flow control is active
•
the SS7 Stack underneath is unavailable or congested
Setup Request Locally Refused by HP OpenCall SS7 TUP
Setup Request - Dual Seizure Case 1
A dual seizure is detected the TUP layer when it receives an initial
address message for a circuit for which it has already sent an initial
address message.
In such a case, the call accepted is the one being processed by the
controlling side and the call being processed by the non-controlling side
is given up.
The controlling side is defined as follows:
•
It has a higher Signaling Point Code than the other side and the
current CIC is even.
•
It has a lower Signaling Point Code than the other side and the
current CIC is odd.
Having determined the controlling side, the other side is the
non-controlling side.
Appendix B
817
TUP Addendum
Call Control
The scenario shown in Figure B-6 and Figure B-7 corresponds to the case
where a circuit is seized on both sides at the same time.
In Figure B-6, as a result of the SETUP_REQ, HP OpenCall SS7 TUP
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 TUP. Consequently, HP OpenCall SS7 TUP
receives this IAM when already engaged in the processing of an outbound
call.
In this case, HP OpenCall SS7 TUP 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. There is no automatic call setup re-attempt as another
circuit has to be selected.
Figure B-6 shows the scenario on the non-controlling side.
Figure B-6
Setup - Dual Seizure Case 1 - Non-Controlling Side
Figure B-7 shows the same scenario on the controlling side.
818
Appendix B
TUP Addendum
Call Control
Figure B-7
Setup - Dual Seizure Case 1 - Controlling Side
Setup Request - Dual Seizure Case 2
In the scenario shown in Figure B-8, the application issues a SETUP_REQ
primitive on a circuit for which an incoming IAM message has just been
treated. The outgoing call is refused with a return status.
The most likely cause is that the SETUP_IND is queued in the Up List of
HP OpenCall SS7 TUP waiting for the application to read it.
The application may re-try a call setup on another circuit.
Figure B-8
Appendix B
Setup - Dual Seizure Case 2
819
TUP Addendum
Call Control
Setup - Failure to Receive ACM
In the scenario shown in Figure B-9, an ACM must be received as a
response to the IAM within T2.
If the ACM is not received within T2, HP OpenCall SS7 TUP abandons
the call attempt and issues a START_RELEASE_IND (T2_TIMEOUT)
primitive to the application.
Once the application acknowledges, a CLF is sent to the network.
Figure B-9
820
Setup - Failure to Receive ACM
Appendix B
TUP Addendum
Call Control
Setup Request - Failure to Receive ANN (or ANC)
In the scenario shown in Figure B-10, an ANN must be received as a
response to the IAM within Twann.
If the ANN is not received within Twann, HP OpenCall SS7 TUP
abandons the call attempt and issues a START_RELEASE_IND to the
application.
Once the application acknowledges, a CLF is sent to the network.
Figure B-10
Appendix B
Setup - Failure to Receive ANN (or ANC)
821
TUP Addendum
Call Control
Setup Request - Unsuccessful Backward Setup Message
When an unsuccessful backward setup message is received from the
network after the sending of an IAM message, then the TUP library
issues a RELEASE_IND primitive to the application.
In all cases, the TUP layer enters a state to wait for the application to
perform the release of the call using the RELEASE_REQ primitive.
However, in the special case of an SLB signal, the scenario given in
Figure B-46, “Re-answer Procedure - Outgoing Side - After SLB (CTUP
Only),” may also occur.
Figure B-11
Setup - Failure - Outgoing Side - Use of UBM
NOTE
In Figure B-11, UBM is one of the following messages: ACB, ADI, CFL, CGC,
DPN, EUM, LOS, NNC, SEC, SLB, SSB, SST, STB, or UNN.
822
Appendix B
TUP Addendum
Call Control
Figure B-12
Setup - Failure - Incoming Side - Use of UBM
NOTE
In Figure B-12, UBM is one of the following messages: ACB, ADI, CFL, CGC,
DPN, EUM, LOS, NNC, SEC, SLB, SSB, SST, STB, or UNN.
Appendix B
823
TUP Addendum
Call Control
Incoming Call Setup with Immediate Release
In the scenario shown in Figure B-13, a CLF message is received
immediately following the incoming IAM message.
Figure B-13
Incoming Call Setup With Immediate Release
In the scenario shown in Figure B-14, an IAM (or IAI) message is sent.
An ACM message is received before T2 expires.
An ANN (or ANC) message is received before Twann expires.
Figure B-14
824
Successful Call Setup - Outgoing Side
Appendix B
TUP Addendum
Call Control
Successful Call Setup for Incoming Side
In the scenario shown in Figure B-15, an IAM (or IAI) message is
received.
An ACM message is sent followed by an ANN (or ANC) message.
Figure B-15
Appendix B
825
TUP Addendum
Call Control
Use of SAM and SAO Messages
In the case where an overlap operation is used after the initial address
message has been sent, the remaining address signal may be sent in
one-digit subsequent address messages (SAO) or in a multi-digit message
(SAM). The INFORMATION_REQ and INFORMATION_IND primitive are used
to carry SAM or SAO messages between the application and the TUP layer.
Figure B-16
826
Use of SAM or SAO - Outgoing Side
Appendix B
TUP Addendum
Call Control
Figure B-17
Appendix B
Use of SAM or SAO - Incoming Side
827
TUP Addendum
Call Control
In the scenario shown in Figure B-18, an IAM message is sent to the
network. This is followed by 2 SAM messages.
Subsequently, a GRQ message is received from the network, and a GSM
message is sent in response.
After the information exchange, an ACM message is received followed by
an ANN message.
Figure B-19 shows the incoming side of this scenario.
Figure B-18
828
Solicited Information Exchange - Outgoing Side
Appendix B
TUP Addendum
Call Control
In the scenario shown in Figure B-19, an IAM message is received from
the network.
This is followed by 2 SAM messages (and an SAO message between the 2
SAM messages).
Subsequently, a GRQ message is sent and a GSM message is received in
response.
After the information exchange, the ACM and ANN messages are sent.
Figure B-18 shows the outgoing side of this scenario.
Figure B-19
Appendix B
Solicited Information Exchange - Incoming Side
829
TUP Addendum
Call Control
Use of GRQ and GSM Messages
This section describes the use of GRQ (General Request Message) and GSM
(General Forward Setup Information Message).
The GRQ/GSM protocol can be initiated only during call setup.
A unique GSM must be sent in response to a GRQ and must only contain
answers to all the requests contained in the GRQ.
This is shown in Figure B-20 and Figure B-21.
Figure B-20
Incoming IAM (or IAI) Leading to GRQ and GSM
Figure B-21
Outgoing IAM Leading to GRQ and GSM
Any information received in the GSM other than that specifically
requested in the associated GRQ is ignored.
If a second GSM is received (in response to a GRQ), it is ignored. This is
shown in Figure B-22.
830
Appendix B
TUP Addendum
Call Control
Figure B-22
Incoming IAM (or IAI) and Two GSMs Received
Normally, the side which sent the GRQ should wait until it receives the
GSM before sending an ACM. This is shown in Figure B-23.
However, there is an exception (shown in Figure B-24) for the case of an
international network that is completely SS7.
Figure B-23
ACM Sent After GSM Received
However, in a fully SS7 international network, the international transit
exchange is not required to delay sending the ACM even if the GRQ/GSM
cycle has not been completed (that is, it ignores the GSM). This is shown
in Figure B-24.
Appendix B
831
TUP Addendum
Call Control
Figure B-24
ACM Sent Before GSM Received
If a GRQ is received before the GSM is sent in reply, the second GRQ is
ignored. This is shown in Figure B-25.
Figure B-25
Second GRQ Received Before GSM Sent
If the call attempt fails (for example, a CGC, NNC, CFL, etc., is received)
during the period when an exchange is waiting for a GSM, then the
appropriate backward call failure is sent without waiting for the GSM.
This is shown in Figure B-26.
832
Appendix B
TUP Addendum
Call Control
Figure B-26
Call Failure During Wait for GSM
If the GSM is not sent before T2 expires (20 - 30 seconds, waiting to receive
ACM), the call attempt fails (a CLF is sent).
This is shown in Figure B-27.
Figure B-27
Appendix B
ACM Timeout Because of Failure to Send GSM
833
TUP Addendum
Call Control
requested, when supported by the selected flavor, in an IAM, an IAI, or a
CCR message. The following sections describe a number of Continuity
scenarios.
Continuity Check on This Circuit
on this circuit’.
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).
834
Appendix B
TUP Addendum
Call Control
Figure B-28
Appendix B
Continuity Check - Success - Outgoing Side
835
TUP Addendum
Call Control
Figure B-29
836
Continuity Check - Success - Incoming Side
Appendix B
TUP Addendum
Call Control
Failed Continuity Check
In the case presented below, the loopback tone is not detected by the application,
and consequently the T8 timer expires.
A CCF message indicating ContinuityFailure is sent by HP OpenCall SS7 TUP.
Figure B-30
Appendix B
Continuity Check - Outgoing Side - Failure
837
TUP Addendum
Call Control
Figure B-31
Continuity Check - Incoming Side - Failure
After a failed continuity check, a re-check is done automatically as depicted in
the Continuity Recheck.
Continuity Recheck
If the continuity recheck procedure is a success, only the outgoing side sends a
CLF message to finish the procedure.
838
Appendix B
TUP Addendum
Call Control
Figure B-32
Appendix B
Continuity Recheck - Outgoing Side - Success
839
TUP Addendum
Call Control
The timer Twccr is equivalent to the ISUP ITU 88 timer T27 (4 minutes):
"waiting for CCR message". Upon Twccr timeout a SETUP_FAILURE_IND
(TWCCR_TIMEOUT) primitive is sent to the application.
Figure B-33
840
Continuity Recheck - Incoming Side - Success
Appendix B
TUP Addendum
Call Control
Continuity Recheck - Test Call
An explicit request for continuity recheck can also be issued by the application to
HP OpenCall SS7 TUP. It is ignored if the circuit is not idle.
Figure B-34
Continuity Recheck - Outgoing Side - Test Call
Figure B-35
Continuity Recheck - Incoming Side - Test Call
Appendix B
841
TUP Addendum
Call Control
If the T8 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.
842
•
On the outgoing side, a CCF is issued to the network, and a
MAINTENANCE_SYSTEM_IND primitive indicating T8_TIMEOUT is issued to the
application after the second continuity failure (including the eventual call
setup continuity failure). The T10 timer is started to restart a continuity
recheck phase at its expiry.
•
On the incoming side, a CCF is received, and a MAINTENANCE_SYSTEM_IND
primitive indicating COT_RECEIVED is issued to the application after the
second continuity failure (including the eventual call setup continuity
failure). The Twccr timer is started to wait for a new incoming CCR.
Appendix B
TUP Addendum
Call Control
Figure B-36
Appendix B
843
TUP Addendum
Call Control
Figure B-37
844
Continuity Recheck - Incoming Side - CCF
Appendix B
TUP Addendum
Call Control
Continuity Check on the Previous Circuit
A Continuity Check is performed on the previous circuit if the
continuityCheckIndicator in the IAM (or IAI) message is set to
“Continuity Check required on the previous circuit”.
Figure B-38
Continuity Check on Previous Circuit - Outgoing Side - COT
Figure B-39
Continuity Check on Previous Circuit - Incoming Side - COT
Appendix B
845
TUP Addendum
Call Control
Figure B-40
Continuity Check on Previous Circuit - Outgoing Side - CCF
Figure B-41
Continuity Check on Previous Circuit - Incoming Side - CCF
846
Appendix B
TUP Addendum
Call Control
Re-answer Procedures
The re-answer procedures provided in the TUP protocol allow for a call to
be re-established after one of the following clear messages has been sent:
•
CBK (Clear backward message).
When the called side goes on-hook first, the CBK message is sent to
the calling side. If the called side goes off-hook immediately
afterwards, then the RAN message is issued to the calling side and the
call returns to the incoming answered state.
The Twran timer measures the delay in which the re-answer
procedure is allowed. It is started upon CBK receipt at the calling
side. On Twran expiry, the call is automatically released by sending a
START_RELEASE_IND to the primitive and a CLF to the network.
•
CCL (Calling party clear signal).
In some conditions (defined by the application), when the calling side
goes on-hook first, the CCL message is sent to the called side. If the
calling side goes off-hook immediately afterwards, then the RAN
message is issued to the called side and the call returns to the
incoming answered state.
The Twran timer measures the delay in which the re-answer
procedure is allowed. It is started upon CCL receipt at the called side.
On Twran expiry, the call is automatically released by sending a
START_RELEASE_IND to the primitive and a CBK to the network.
The OPR message may be used in case of operator calls, in order to
generate re-ringing of a subscriber who has just gone on-hook. The
objective is for an operator to get the subscriber to go off-hook. The OPR
signal is transparently transmitted to/from the application by means of
the primitives OPERATOR_SIGNAL_IND and OPERATOR_SIGNAL_REQ.
NOTE
The OPR message and the OPERATOR_SIGNAL_IND and
OPERATOR_SIGNAL_REQ primitives are not supported in ITUP.
In the following scenarios, the use of OPR is shown in italic font because it
is optional in the re-answer procedure.
Appendix B
847
TUP Addendum
Call Control
Called Side Goes On-hook First
The called side (shown in Figure B-42) goes on-hook first. It sends a CBK
message and starts Twclr (to wait for a CLR message). When it goes
off-hook again immediately afterwards, it stops Twclr and sends a RAN
message to the calling side (shown in Figure B-43).
Figure B-42
Re-answer Procedure - Incoming Side - RAN After CBK
The calling side (shown in Figure B-43), receives the CBK message and
starts Twran (to wait for a RAN message). It receives the RAN message
before Twran expires.
Figure B-43
848
Re-answer Procedure - Outgoing Side - RAN After CBK
Appendix B
TUP Addendum
Call Control
Calling Side Goes On-hook First
The calling side (shown in Figure B-44) goes on-hook first. It sends a CCL
message and starts Twclr (to wait for the CLR message). When it goes
off-hook again immediately afterwards, it stops Twclr and sends a RAN
message to the called side (shown in Figure B-45).
Figure B-44
Re-answer Procedure - Outgoing Side - RAN After CCL
The called side (shown in Figure B-45), receives a CCL message and
starts Twran (to wait for a possible RAN message). It receives the RAN
message before Twran expires.
Figure B-45
Appendix B
Re-answer Procedure - Incoming Side - RAN After CCL
849
TUP Addendum
Call Control
After Local Subscriber Busy (CTUP Only)
This procedure is available for operator calls when the operator provides
Trunk Offering. If an SLB message (not available in ITUP) is received as
a response to the setup message sent by the operator, the call may be
established after the busy called side goes on-hook.
The scenario is shown in Figure B-46 (for the outgoing side) and
Figure B-47 (for the incoming side).
Figure B-46
850
Re-answer Procedure - Outgoing Side - After SLB (CTUP Only)
Appendix B
TUP Addendum
Call Control
Figure B-47
Appendix B
Re-answer Procedure - Incoming Side - After SLB (CTUP Only)
851
TUP Addendum
Call Control
Call Release
If the application wishes to release a circuit, it will send a RELEASE_REQ
primitive with a CLF message containing the cause for releasing the
circuit. The circuit status is modified to TRANSIENT, and the CLF message
is sent to the SS7 network.
If the called part initiates the release, the application is notified with a
RELEASE_IND from the TUP library.
Normal Call Release
In scenario shown in Figure B-48, the application managing the call
initiates the release. The HP OpenCall TUP layer starts 2 timers when
sending the Clear Forward Message:
T6 Timer
"waiting for release-guard signal" (4-15 seconds).
T7 Timer
"stop sending clear-forward signal on timeout" (1
minute).
The CLF message is repeated every T6 until either an RLG is received or
T7 expires. If T7 expires, a reset circuit procedure is initiated.
Figure B-48
852
Normal Call Release - Initiated from Calling Party
Appendix B
TUP Addendum
Call Control
In the scenario shown in Figure B-49, the Clear-back signal is sent in the
backward direction indicating that the called party has cleared the call.
The call is not released immediately at the calling side to allow for the
possible reception of a re-answer signal as shown in “Re-answer
Procedures” on page 847.
Figure B-49
Appendix B
Normal Call Release - Initiated from Called Party
853
TUP Addendum
Call Control
In the scenario shown in Figure B-50, the called party does not go
on-hook and no RAN message is received from network. When Twran
expires, the call is automatically released by the TUP layer by issuing a
START_RELEASE_IND primitive to the application.
Figure B-50
854
Normal Call Release - Initiated from Called Party After Twran
Expiry
Appendix B
TUP Addendum
Call Control
In the scenario shown in Figure B-51, the application sends a Clear-back
signal in the backward direction indicating to the calling part that the
call is cleared.
The call is not released immediately at the calling side to allow for the
possible reception of a re-answer signal as shown in “Re-answer
Procedures” on page 847.
Figure B-51
Normal Call Release - Outgoing Release in Backward Direction
In the scenario shown in Figure B-52, a CFL message is received. A CLF is
sent and T6 and T7 are started. The release is completed (the circuit
returns to IDLE) when the RLG message is received.
Figure B-52
Normal Call Release - Call Failure Signal Received
In the scenario shown in Figure B-53, a CFL message is sent and T4 and
T5 are started. A CLF is received and T4 and T5 are stopped.
Appendix B
855
TUP Addendum
Call Control
When the release is completed (the circuit state returns to IDLE), the RLG
message is sent.
Figure B-53
856
Normal Call Release - Call Failure Signal Sent
Appendix B
TUP Addendum
Call Control
Abnormal Call Release
In the scenario shown in Figure B-54, a CLF message is sent and T6 and
T7 are started. T6 expires and another CLF message is sent.
When T7 expires, a MAINTENANCE_SYSTEM_IND primitive is sent to the
application. An RSC message is sent (and T18 and T19 are started).
When the RLG message is received, the reset is completed (the circuit
state returns to IDLE).
Figure B-54
Appendix B
Abnormal Call Release - Failure To Receive RLG After Sending
CLF
857
TUP Addendum
Call Control
In the scenario shown in Figure B-55, a CBK message is sent and Twclr is
started. Twclr expires and a CFL message is sent (and T4 and T5 are
started).
A CLF message is received (and T4 and T5 are stopped).
When the release is completed (the circuit state returns to IDLE), the RLG
message is sent.
Figure B-55
858
Abnormal Call Release - Failure To Receive CLF After Sending
CBK
Appendix B
TUP Addendum
Call Control
In the scenario shown in Figure B-56, a CFL message is sent and T4 and
T5 are started.
T4 expires and another CFL message is sent (and T4 is re-started).
T5 expires and a MAINTENANCE_SYSTEM_IND primitive is sent to the
application (and T4 is stopped).
An RSC message is sent (and T18 and T19 are started).
A CLF message is received (and T18 and T19 are stopped).
When the reset is completed (the circuit state returns to IDLE), the RLG
message is sent.
Figure B-56
Appendix B
Abnormal Call Release - Failure To Receive CLF After Sending
CFL
859
TUP Addendum
Call Control
Circuit Reset
The circuit reset mechanism is used to reset a circuit to an IDLE
condition, thereby making the circuit available for new traffic.
Successful Reset from Application - Incoming Exchange
In the scenario shown in Figure B-57 (case of an incoming call), the Reset
procedure is initiated by the application by issuing a RESET_REQ (RSC)
primitive. The TUP library sends an RSC message to the network.
A CLF message is received. When the circuit state is set to IDLE, an RLG
message is sent to the network.
Figure B-57
860
Successful Reset from Application- Incoming
Appendix B
TUP Addendum
Call Control
Successful Reset from Application - Outgoing Exchange
In the scenario shown in Figure B-58 (case of an outgoing call), the Reset
procedure is initiated by the application by issuing a RESET_REQ (RSC)
primitive. The TUP library sends an RSC message to the network.
When an RLG message is received, the circuit state is set to IDLE.
Figure B-58
Appendix B
Successful Reset from Application- Outgoing
861
TUP Addendum
Call Control
Reset from Network - Incoming Exchange - Successful
Procedure
In the scenario shown in Figure B-59 (case of an incoming call), the Reset
procedure is initiated by the network.
The TUP Layer accepts the signal as a clear-forward signal and responds
by sending a release-guard signal, after the circuit has been made idle.
This scenario is applicable to an incoming exchange in any phase of call
set-up or during a call.
The application has to reply promptly though HP OpenCall SS7 TUP
and does not set a timer (waiting for RESET_RESP from the application).
Figure B-59
862
Reset from Network - Incoming Exchange - Successful Procedure
Appendix B
TUP Addendum
Call Control
Reset from Network - Outgoing Exchange - Successful
Procedure
In the scenario shown in Figure B-60 (case of an outgoing call), the Reset
procedure is initiated by the network.
The TUP Layer accepts the signal as a clear-back or call failure signal
and responds by sending a clear forward signal. The circuit state is set to
IDLE when an RLG message is received. The application has to wait for
RESET_CONF.
Figure B-60
Appendix B
Reset from Network - Outgoing Exchange - Successful Procedure
863
TUP Addendum
Call Control
HP OpenCall SS7 TUP Initiated Reset - Successful Procedure
In the scenario shown in Figure B-61, HP OpenCall SS7 TUP initiates a
Reset procedure if it receives an unexpected message (a RAN message)
after it sends an IAM message.
As a result, it sends a START_RESET_IND primitive to the application.
The primitive contains an additional information (StartReset) 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.
On reception of the latter primitive, HP OpenCall SS7 TUP sends an RSC
message to the network and starts timers T18 and T19.
On receipt of the RLG message, a RESET_CONF primitive is sent to the
application.
Figure B-61
864
Circuit Reset - Successful Procedure
Appendix B
TUP Addendum
Call Control
HP OpenCall SS7 TUP Initiated Reset - Failure to Receive RLG
In the scenario shown in Figure B-62, HP OpenCall SS7 TUP initiates
the reset procedure because of the reception of an unexpected message.
The network fails to respond with an RLG message.
As a result, HP OpenCall SS7 TUP retransmits an RSC message every
T18, until the procedure is stopped by the application via a STOP_REQ
After T19:
Appendix B
•
A MAINTENANCE_SYSTEM_IND is sent to the application, informing the
application/operator about the error situation.
•
every T18 (typically 5 seconds) until a STOP_REQ primitive is received
from the application.
865
TUP Addendum
Call Control
Figure B-62
Circuit Reset - Failure to Receive RLG
Reset in Locally Blocked Conditions
This is the same as for ISUP, but instead of the RLC after the BLO, a CLF,
or RLG signal is sent depending on whether it is an incoming or an
outgoing call. The BLO message has to be acknowledged. If not, the
repetition procedure is applied.
Reset in Remotely Blocked Conditions
This is the same as for ISUP, but instead of an RLC, respond with a CLF
for outgoing call and RLG for all other cases.
866
Appendix B
TUP Addendum
Call Control
Dual Reset Circuit Conditions
This is the same as for ISUP, except an RLG is sent instead of an RLC.
Circuit Group Reset
See also “Generic TUP Circuit Group Message Handling” on page 813.
The GRS message is always sent twice to avoid erroneous group reset
operations. On the reception side, if only one message is received within
5 seconds, then the operation is canceled.
Table B-12 gives the timers used for group reset.
Table B-12
Timer
name
Appendix B
Timers Used for Group Reset
Group
Message
Operation
T20
GRS
Waiting for second GRS message.
T21
GRA
Waiting for GRA message.
T22
GRS
Delay before sending the GRS
message.
867
TUP Addendum
Call Control
Group Reset From Network - Normal Case
In the scenario shown in Figure B-63, a GRS message is received for 2
circuits for which the current state is not IDLE.
On the first GRS, a timer T20 is started, and the state is set to "Wait for
second GRS".
On the second GRS, a GROUP_RESET_IND primitive is sent to the
application, then a RESET_IND primitive is sent for each circuit.
The GRA group reset acknowledgment message is sent back only after all
the expected RESET_RESP and the GROUP_RESET_RESP (without the GRA
associated message) primitives have been received from the application
(when all the circuits are in the appropriate state).
Figure B-63
868
Group Reset From Network - Normal Case - Range Not Zero
Appendix B
TUP Addendum
Call Control
In the scenario shown in Figure B-64, a GRS message is received for 2
circuits for which the current state is not IDLE.
On the first GRS, a timer T20 is started, and the state is set to "Wait for
second GRS".
On the second GRS, a GROUP_RESET_IND primitive is sent to the
application, which responds with a GROUP_RESET_RESP (with GRA
associated message) primitive indicating to the remote end that a group
reset procedure is started.
Then, a START_RESET_IND primitive is sent to the application for each
circuit involved in the group.
For each START_RESET_IND_ACK primitive, an RSC message is sent to the
network, and the remote end will respond with an RLG message.
Figure B-64
Appendix B
Group Reset From Network - Normal Case - Range Zero
869
TUP Addendum
Call Control
Reset From User - Normal Case
In this scenario shown in Figure B-65, a GROUP_RESET_REQ request is
sent by the user. All the circuits of the group are remotely and locally
unblocked, and the GRS message is sent to the network. Then, TUP waits
for the Acknowledgment message GRA before returning the circuit state
to IDLE.
In the case where the range parameter value is 0 in the GRS sent, then
for all the circuits involved an RSC will be received from network, and a
RLG sent in response (see “Group Reset From Network - Normal Case” on
page 868).
Figure B-65
870
Group Reset From User - Normal Case
Appendix B
TUP Addendum
Call Control
Failure Case - No Acknowledgment Received From Network
In the scenario shown in Figure B-66, the application sends a
GROUP_RESET_REQ primitive. If no response is received from the remote
end, GRS messages are repeated according to the T21 and T22
mechanism.
Figure B-66
Appendix B
Group Reset - Failure Case - No Acknowledgment Received From
Network
871
TUP Addendum
Call Control
Failure Case - No Response Received From Application
In the case shown in Figure B-67, the GROUP_RESET_RESP primitive is
sent back by the application but not all RESET_IND primitives have been
acknowledged. The GRA message cannot be sent back to the network and
an error is returned to the application.
Figure B-67
872
Group Reset - Failure Case - No Response Received From
Application
Appendix B
TUP Addendum
Call Control
Double Reset - Normal Case
In the scenario shown in Figure B-68, a circuit is to be reset twice; first
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 TUP finds that circuit is already being reset,
therefore, it does not produce a RESET_IND for it.
The application responds to the first RESET_IND by a RESET_RESP, and
then to the other RESET_IND. On receipt of GROUP_RESET_RESP, as all the
circuits of the group are in the appropriate state, HP OpenCall SS7 TUP
can send the GRA.
Note that it is likely that the RESET_RESP corresponding to the Circuit
Reset contains an RLG message and no additional info, thus causing an
RLG message to be sent to the network.
Figure B-68
Appendix B
Double Reset - Normal Case - Range Not Zero
873
TUP Addendum
Call Control
In the scenario shown in Figure B-69, a circuit is to be reset twice; first
by a Circuit Reset RSC, then by a Circuit Group Reset (it belongs to the
group). RESET_IND procedure as well as the START_RESET_IND is
involved for it because at the remote end, group reset procedure is
waiting for an RSC for each circuit.
Figure B-69
874
Double Reset - Normal Case - Range Zero
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Maintenance
This section describes circuit maintenance processes.
“ISUP Circuit Maintenance - Procedures Specific to ANSI,” and
Chapter 20, “ISUP Circuit Maintenance - Procedures Specific to ITU-T.”
The circuit maintenance processes described in this section include:
•
•
Circuit Blocking/Unblocking
Circuit Blocking From Network - Normal Case
In the scenario shown in Figure B-70, a BLO message is received from the
network (requesting that a circuit be blocked).
A BLOCKING_IND primitive is issued to the application.
Once the application responds with a BLOCKING_RESP primitive, the
circuit state is set to IDLE_MN_REMOTELY_BLOCKED, and a BLA message is
sent to the network.
Figure B-70
Appendix B
Circuit Blocking From Network - Normal Case
875
TUP Addendum
Circuit Maintenance
Circuit Blocking From User - Normal Case
In the scenario shown in Figure B-71, a BLOCKING_REQ primitive is
issued by the application.
A BLO message is sent to the network.
Timer T11 is set to 0 to have the application alerted of the maintenance
blocking operation immediately on receipt of the BLA message.
Otherwise, the application will be alerted at T11 expiry if the circuit is
still locally blocked.
The circuit state is set to IDLE_MN_LOCALLY_BLOCKED, and a
BLOCKING_CONF primitive is issued to the application.
Figure B-71
Circuit Blocking From User - Normal Case
Circuit Unblocking From Network - Normal Case
In the case shown in Figure B-72, the UBL message only unblocks a
maintenance oriented blocked circuit.
Figure B-72
876
Circuit Unblocking From Network - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Unblocking From User - Normal Case
In the scenario shown in Figure B-73, an UNBLOCKING_REQ primitive is
issued by the application.
A UBL message is sent to the network.
Once the UBA message is received from the network, the circuit is
unblocked and the circuit state is set to IDLE.
Figure B-73
Circuit Unblocking From User - Normal Case
Circuit Unblocking From Network - On Reception of IAM
A blocked circuit can be unblocked only by unblocking or reset messages.
Circuit Blocking During the Setup Procedure
In the scenario shown in Figure B-74, a SETUP_REQ (IAM) primitive is
issued by the application. An IAM message is sent to the network.
Before the ACM message is received, a BLO message is received
(requesting that the circuit be blocked).
A MAINTENANCE_SYSTEM_IND primitive is issued to the application.
Once the application responds with a BLOCKING_RESP primitive, the
circuit state is set to IDLE_MN_REMOTELY_BLOCKED, and a BLA message is
sent to the network.
A START_RELEASE_IND primitive is issued to the application, and once it
is acknowledged, a CLF message is sent to the network. The release is
complete once the RLG message is received from the network.
In the case shown in Figure B-74, an automatic call re-attempt should be
made by the application on another circuit.
Appendix B
877
TUP Addendum
Circuit Maintenance
Figure B-74
Circuit Blocking During Setup Procedure - Outgoing Side
Figure B-75 shows the incoming side of the scenario whose outgoing side
is shown in Figure B-74.
In the case shown in Figure B-75, if the IAM message concerns a test call,
then the call would be accepted.
Figure B-75
878
Circuit Blocking During Setup Procedure - Incoming Side
Appendix B
TUP Addendum
Circuit Maintenance
HP OpenCall SS7 TUP handles tree types of Group Blocking messages:
•
Group Blocking for a maintenance reason.
•
Group Blocking for a hardware reason.
•
Group Blocking for a software reason.
All group blocking and unblocking messages are sent twice to prevent
erroneous blocking operations. On the reception side, if only one message
is received within 5 seconds, then the operation is canceled. The
corresponding timers are given in Table B-13.
Table B-13
Timer Name
Timers for Circuit Group
Blocking/Unblocking
Group Message
Type
Operation
T23
MGB
maintenance blocking
T24
MGU
maintenance
unblocking
T30
HGB
hardware blocking
T31
HGU
hardware unblocking
T36
SGB
software blocking
T37
SGU
software unblocking
See also “Generic TUP Circuit Group Message Handling” on page 813.
Appendix B
879
TUP Addendum
Circuit Maintenance
Circuit Group Blocking
Circuit Group Blocking From Network - Maintenance OrientedNormal Case
In the scenario shown in Figure B-76, 2 MGB messages are received from
the network in less than 5 seconds (timer T23). This specifies that
"maintenance group blocking" should be performed.
Consequently, HP OpenCall SS7 TUP:
Step 1. Issues a GROUP_BLOCKING_IND primitive to the application.
Step 2. Issues a MAINTENANCE_SYSTEM_IND indicating MN_GROUP_BLOCKING.
Step 3. Marks all the circuits concerned as "maintenance remotely blocked".
Step 4. Upon receipt of a GROUP_BLOCKING_RESP primitive, sends back the
acknowledgment message MBA.
Timer T25 is set to 0 to have the application alerted of the maintenance
blocking operation immediately on reception of the second MGB message.
If not, the application will be alerted at T25 expiry if no management
group unblocking has been performed on this circuit.
Figure B-76
880
Group Blocking from Network - MN - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Blocking from Network - Hardware Oriented Normal Case
In the scenario shown in Figure B-77, 2 HGB messages are received from
"hardware group blocking" should be performed.
Step 1. Issues a HW_GROUP_BLOCKING_IND primitive to the application.
Step 2. Issues a MAINTENANCE_SYSTEM_IND indicating HW_GROUP_BLOCKING.
Step 3. Marks all the circuits concerned as "hardware remotely blocked".
Step 4. Upon receipt of a HW_GROUP_BLOCKING_RESP primitive, sends back the
acknowledgment message HBA.
Figure B-77
Appendix B
Group Blocking from Network - HW - Normal Case
881
TUP Addendum
Circuit Maintenance
Circuit Group Blocking from Network - Software Oriented Normal Case
In the scenario shown in Figure B-78, two SGB messages are received
from the network in less than 5 seconds (timer T36). This specifies that
"software group blocking" should be performed.
Step 1. Issues a SW_GROUP_BLOCKING_IND primitive to the application.
Step 2. Issues a MAINTENANCE_SYSTEM_IND indicating SW_GROUP_BLOCKING.
Step 3. Marks all the circuits concerned as "software remotely blocked".
Step 4. Upon receipt of a SW_GROUP_BLOCKING_RESP primitive, sends back the
acknowledgment message SBA.
Figure B-78
882
Group Blocking from Network - SW - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Blocking from User - Maintenance Oriented Normal Case
In the scenario shown in Figure B-79, a GROUP_BLOCKING_REQ request is
sent by the user.
Step 1. Sends two MGB messages to the network.
Step 2. Upon receipt of an MBA message from the network, issues a
GROUP_BLOCKING_CONF(MBA) primitive to the application.
Step 3. Marks all the circuits concerned as "maintenance locally blocked".
Figure B-79
Appendix B
Group Blocking from User - MN - Normal Case
883
TUP Addendum
Circuit Maintenance
Circuit Group Blocking from User - Hardware Oriented - Normal
Case
In the scenario shown in Figure B-80, a HW_GROUP_BLOCKING_REQ
request is sent by the user.
Step 1. Sends two HGB messages to the network.
Step 2. Upon receipt of an HBA message from the network, issues a
HW_GROUP_BLOCKING_CONF(HBA) primitive to the application.
Step 3. Marks all the circuits concerned as "hardware locally blocked".
If one of the circuits concerned is seized by a call, then the call state is set
to IDLE, running timers are stopped, and a SETUP_FAILURE_IND
primitive or a RELEASE_IND primitive (without associated message) is
issued to the application.
Figure B-80
884
Group Blocking from User - HW - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Blocking from User - Software Oriented - Normal
Case
In the scenario shown in Figure B-81, a SW_GROUP_BLOCKING_REQ
Step 1. Sends two SGB messages to the network.
Step 2. Upon receipt of an SBA message from the network, issues a
SW_GROUP_BLOCKING_CONF(SBA) primitive to the application.
Step 3. Marks all the circuits concerned as "software locally blocked".
If one of the circuits concerned is seized by a call, then the call state is set
to IDLE, running timers are stopped, and a SETUP_FAILURE_IND
primitive or a RELEASE_IND primitive (without associated message) is
issued to the application.
Figure B-81
Appendix B
Group Blocking from User - SW - Normal Case
885
TUP Addendum
Circuit Maintenance
Circuit Group Blocking During Setup - Maintenance Oriented Normal Case
In the scenario shown in Figure B-82, two MGB messages arrive from the
network after an IAM message has been sent.
Figure B-82
886
Group Blocking During Call Setup - MN - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Blocking During Call Setup - Hardware Oriented Normal Case
In the scenario shown in Figure B-83, two HGB messages arrive from the
Figure B-83
Appendix B
Group Blocking During Call Setup - HW - Normal Case
887
TUP Addendum
Circuit Maintenance
Circuit Group Blocking During Call Setup - Software Oriented Normal Case
In the scenario shown in Figure B-84, two SGB messages arrive from the
Figure B-84
888
Group Blocking During Call Setup - SW - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Unblocking
Circuit Group Unblocking from Network (Maintenance
Oriented) - Normal Case
In the scenario shown in Figure B-85, 2 MGU messages are received from
"maintenance group unblocking" should be performed.
Step 1. Issues a GROUP_UNBLOCKING_IND primitive to the application.
Step 2. On receipt of a GROUP_UNBLOCKING_RESP primitive, sends back the
acknowledgment message MUA.
Step 3. Marks all the circuits concerned as "maintenance remotely unblocked".
A maintenance blocked condition can only be removed by a maintenance
oriented unblocking message.
Figure B-85
Appendix B
Group Unblocking from Network - MN - Normal Case
889
TUP Addendum
Circuit Maintenance
Circuit Group Unblocking from Network (Hardware Oriented) Normal Case
In the scenario shown in Figure B-86, 2 HGU messages are received from
"hardware group unblocking" should be performed.
Step 1. Issues a HW_GROUP_UNBLOCKING_IND primitive to the application.
Step 2. Upon receipt of a HW_GROUP_UNBLOCKING_RESP primitive, sends back the
acknowledgment message HUA.
Step 3. Marks all the circuits concerned as "hardware remotely unblocked".
Figure B-86
890
Group Unblocking from Network - HW - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Unblocking from Network (Software Oriented) Normal Case
In the scenario shown in Figure B-87, 2 SGU messages are received from
"software group unblocking" should be performed.
Step 1. Issues a SW_GROUP_UNBLOCKING_IND primitive to the application.
Step 2. Upon receipt of a SW_GROUP_UNBLOCKING_RESP primitive, sends back the
acknowledgment message SUA.
Step 3. Marks all the circuits concerned as "software remotely unblocked".
Figure B-87
Appendix B
Group Unblocking from Network - SW - Normal Case
891
TUP Addendum
Circuit Maintenance
Circuit Group Unblocking from User (Maintenance Oriented) Normal Case
In the scenario shown in Figure B-88, a GROUP_UNBLOCKING_REQ request
is sent by the user.
Step 1. Sends two MGU messages to the network.
Step 2. Upon receipt of an MUA message from the network, issues a
GROUP_UNBLOCKING_CONF(MUA) primitive to the application.
Step 3. Marks all the circuits concerned as "maintenance locally unblocked".
Figure B-88
892
Group Unblocking from User - MN - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Unblocking from User (Hardware Oriented) Normal Case
In the scenario shown in Figure B-89, a HW_GROUP_UNBLOCKING_REQ
Step 1. Sends two HGU messages to the network.
Step 2. Upon receipt of an HUA message from the network, issues a
HW_GROUP_UNBLOCKING_CONF(HUA) primitive to the application.
Step 3. Marks all the circuits concerned as "hardware locally unblocked".
Figure B-89
Appendix B
Group Unblocking from User - HW - Normal Case
893
TUP Addendum
Circuit Maintenance
Circuit Group Unblocking from User (Software Oriented) Normal Case
In the scenario shown in Figure B-90, a SW_GROUP_UNBLOCKING_REQ
Step 1. Sends two SGU messages to the network.
Step 2. Upon receipt of an SUA message from the network, issues a
SW_GROUP_UNBLOCKING_CONF(SUA) primitive to the application.
Step 3. Marks all the circuits concerned as "software locally unblocked".
Figure B-90
894
Group Unblocking from User - SW - Normal Case
Appendix B
TUP Addendum
Circuit Maintenance
Circuit Group Blocking/Unblocking - Acknowledgment
When a group blocking or unblocking message is sent to the network,
two timers Tx and Ty (Tx and Ty are given with the corresponding group
message type in Table B-14) are started to wait for the acknowledgment.
Their use is described as follows:
•
On Tx timeout (4-15 seconds), the group message is re-sent (twice) to
the network and Tx timer is restarted.
•
On Ty timeout (1 minute), the group message is re-sent (twice) to the
network and the Ty timer is restarted. If is the first Ty timeout, a
MAINTENANCE_SYSTEM_IND (Ty_TIMEOUT) primitive is issued to the
application, and timer Tx is stopped.
Acknowledgment Timers Used
Table B-14 lists the timers used to wait for acknowledgment during
group blocking/unblocking operations.
Table B-14
Acknowledgment Timers - Group Blocking
and Unblocking
Tx
Appendix B
Ty
Group Message Type
T26
T27
MGB
T28
T29
MGU
T32
T33
HGB
T34
T35
HGU
T38
T39
SGB
T40
T41
SGU
895
TUP Addendum
Circuit Maintenance
Example of Using the Acknowledgment Timers
Figure B-91 shows an example of the use of the Tx and Ty timers in the
case of sending an SGU message.
Figure B-91
896
Circuit Group Blocking or Unblocking - Acknowledgment Timers
Appendix B
TUP Addendum
Miscellaneous Procedures
Use of MPM Message (CTUP Only)
Note that the MPM message is not applicable to ITUP.
Figure B-92
Metering Pulse Message - Outgoing Side (CTUP Only)
Figure B-93
Metering Pulse Message - Incoming Side (CTUP Only)
Appendix B
897
TUP Addendum
Use of MAL Message (CTUP Only)
The use of the MAL message is not explained in the CTUP specification.
If received, then it will be issued to the application in a
TUP_USR_MSG_IND primitive without affecting the state-machines.
Use of FOT Message
Figure B-94
Forward Transfer Message - Outgoing Side
Figure B-95
Forward Transfer Message - Incoming Side
898
Appendix B
TUP Addendum
TUP Tutorial Programs
TUP Tutorial Programs
Four tutorials (that is, example programs) are provided with
HP OpenCall SS7 TUP. Their names are:
•
tupClientSM
•
tupServerSM
•
tupClientBP
•
tupServerBP
The tutorials show how to develop a simple call setup/release application
using the methods provided by the HP OpenCall SS7 TUP.
The source code of these tutorials is in the /opt/OC/tutorials/TUP
directory.
CAUTION
Using State-machine Access
The Caller and Called show how to develop an application by using the
state-machine mode of access (IsupSMProbe) and its associated methods.
Caller
tupClientSM
Called
tupServerSM
Using Bypass Access
The Caller and Called show how to develop an application specifically
using the bypass access mode (IsupBPProbe) and its associated methods.
Appendix B
Caller
tupClientBP
Called
tupServerBP
899
TUP Addendum
TUP Makefile
TUP Makefile
The makefile /opt/OC/tutorials/TUP/Makefile is provided with
HP OpenCall SS7 TUP.
CAUTION
900
Appendix B
Symbols
., 459
Numerics
16 bit values
assigning, 539
32 bit values
assigning, 539
8 bit values
assigning, 539
A
abnormal
call release (ISUP), 637, 639, 670, 671
aCC
definition, 308
access modes (ISUP)
bypass, 451, 462
state-machine, 451, 462
accessors (ISUP)
behavior, 536
description, 536
message parameters, 544
presence accessor, 536
read accessor, 536
specific accessors, 536
using parameter value objects, 555
write accessor, 536
accessors (TUP)
check value, 786
China TUP, 790
for messages, 785
get value, 786
ITU-T, 794
mark as absent, 786
set value, 786
ACM message (ISUP)
not received, 605, 607, 636
reception, 606, 666
ACM message (TUP)
not received, 820
ACR
state machine (TUP), 801
activating
standby application, 566
activity object
deleting, 482
function, 478
methods, 478
redefining methods, 478
activity object (TUP)
mechanism description, 766
activity object mechanism
description, 477
indication of IPC state, 561
receiving message, 544
scheduling, 476
AdditionalInfo values (ISUP)
ANSI, 746
ITU-T, 750
library values, 745
primitive (CTUP), 770
primitive (ISUP ANSI), 506
primitive (ISUP ITU), 514
primitive (ITUP), 776
AG
PIC/AG definition, 308, 309
ALERT_IND
ALERT_REQ
algorithm
loadsharing, 47
algorithms
round robin, 281, 289
user-supplied, 281
alias
definition of alias point code, 50
definition of local alias, 50
ALREADY_CLOSED, 493
ALREADY_DESTROYED, 492
ALREADY_OPEN, 493
ANC message (TUP)
not received, 821
ANN message (TUP)
not received, 821
ANSI
circuit reservation, 644
continuity check, 661
continuity recheck, 652
exit message, 648
Global Title types, 149
protocol, 445
901
software versions, 445
suspend resume messages, 646
TCAP versions, 204
ANSI messages, 280
ANSI-92
message set (ISUP), 445
standards (ISUP), 529
state-machines (ISUP), 447
ANSI-95
AP (ISUP)
rejection of primitives, 561
API
asychronous services, 72
combinations, 68
communication via IPC buffers, 77
concepts, 65
definition, 308
Execution API, 308
file descriptors, 73
general definition, 66
HA API, 308
independent of platform configuration, 66
mechanisms, 65
minimum timeout value, 73
PCA, 308
PIC/AG, 49
Registry API, 309
TCAP Application Message Dispatcher, 47
API (ISUP)
asynchronous services, 474
C++, 448
central processing, 461
creating additional information objects, 555
deleting additional information objects, 556
exchanging messages, 474, 541, 560
general relationship of object classes, 541
inbound indications queue, 545, 560
message classes, 447, 529
methods, 447
object-oriented, 448
objects, 447, 460
outbound message queue, 543, 561
recreating and reopening objects, 482
software components, 447
structure, 460
API (TUP)
structure, 765
API management (ISUP)
902
circuit states, 562
guidelines, 552
inbound indications queue, 560
memory space, 554
messages, 555
object management rules, 555
object memory, 555
outbound message queue, 560
parameter values, 555
redefining new(), 554
return status values, 556
API management (TUP)
guidelines, 802
IPC buffers, 557, 802
memory space, 802
object memory, 802
API_BUSY, 491, 493
APIs
ISUP, 44
M3UA, 44, 86
management, 44, 48
MTP-3, 44
MTP3, 86
multiple, 44, 68, 74
SCCP, 44
stack, 44, 46
TCAP, 44
TUP, 44
APP_TRANSPORT_IND
APP_TRANSPORT_REQ
application
accessing a protocol layer, 46
accessing an SS7 stack, 66
active, 564
basic structure (ISUP), 463
basic structure (TUP), 765
Call Control (ISUP), 573
centralized, 450
communicating via a connection, 448
communicating with SS7 stack, 71
connecting to an SS7 stack, 71
context, 202
creating message parameter value objects,
555
deleting additional information objects, 556
deleting message parameter values, 555
destroying entities belonging to a
connection, 76
developing circuit update mechanism, 564
effects of a switchover, 81
failure, 564
flow control, 79
gateway, 451
High Availability, 552
ITU-T Blue Book TCAP on a White Book
TCAP API, 214
location on a platform, 66
maintenance, 68
managing circuit states (ISUP), 562
managing file descriptors, 73
managing flow control, 559
managing return status value objects, 556
migration from development platforms, 68
optimizing performance, 60
primitives rejected, 561
priority, 59, 62
processing overhead, 448
receiving pending primitives, 560
receiving primitives, 75
receiving waiting indications, 80
reducing back-pressure, 80
reducing IPC calls, 78
reducing network back-pressure, 80
rescheduling, 76
response time, 560
returned messages, 555
scheduling, 71
scheduling and timeout value, 73
scheduling loop, 74
sending primitives, 75
share of CPU, 62
sharing CPU with SS7 stack, 62
sizing, 68
specific C++ guidelines (ISUP), 448
specific C++ guidelines (TUP), 763
standby, 562, 564
switchover mechanism, 562
synchronization between applications, 562
synchronizing with state-machines, 553
tuning IPC buffers, 78
upgrade, 68
using error codes, 83
using IPC buffers, 77
using the M3UA API, 86
using the MTP3 API, 86
using the OA&M API, 399
using the SCCP API, 115
using the TCAP API, 195
utilizing SS7 management functions, 48
application (TUP)
managing circuit states, 805
application connection, 458
AIG, 453
ASN.1 compiler, 207
assign() method, 539
aStatus parameter, 478
automated
call release (ISUP), 546
call release (TUP), 799
unsuccessful call release (TUP), 800
automatic
congestion control (TUP), 803, 804
autoSwitch parameter
MTP3/M3UA, 94
TCAP, 221
B
back-pressure, 79, 559, 560
BACKWARD_CHECK_TONE
backwardCallIndicators parameter, 628, 629
BAD_CNX_TYPE, 493
BAD_GLOBAL_CONFIG, 493
BAD_ISUP_CONFIG, 491
Berkeley socket mechanism, 72
bit masks, 73
blocking
circuit (ISUP), 699, 729
primitives, 579
BLOCKING_CONF
BLOCKING_IND
903
BLOCKING_REQ
BLOCKING_RESP
BP mode
examples (ISUP), 498
examples (TUP), 899
BP probes, 583, 586
buffer sizes, 59
bypass access
examples (TUP), 899
Bypass Mode
primitives (ITU-T TUP), 779
Bypass Mode (TUP)
primitives, 779
Bypass probes, 583, 586
bypass TCAP component layer, 200
C
C++
interface (ISUP), 447
Call Control (ISUP)
application, 450, 573
exchanging primitives, 503
call release
collision (ISUP), 610
call release (ISUP)
abnormal, 637, 639, 670, 671
abnormal inbound, 637, 670
abnormal outbound, 637, 670
automated, 546
collision, 609
normal, 608, 637, 670
normal incoming, 608
normal outgoing, 608
call release (TUP)
automated, 799
automated unsuccessful, 800
normal outgoing, 852
procedures, 852
call setup (ISUP), 606
ACM message use, 606
ACM reception, 666
904
successful for incoming side, 606
successful for outgoing side, 666
unsuccessful, 602
without ACM message, 607
without ACM reception, 636
call setup (TUP), 824, 825, 826, 827
dual seizure, 817, 818, 819
failure to receive ACM, 820
failure to receive ANC, 821
failure to receive ANN, 821
failure UBM received, 822
failure UBM sent, 823
immediate release, 824
locally refused, 816, 817
procedures, 816
UBM received, 822
unsuccessful, 816
call setup/release
examples (TUP), 899
call teardown (TUP)
procedures, 816
CALL_PROGRESS_IND
CALL_PROGRESS_REQ
calledPartyNumber
parameter (TUP), 790
calls to functions
castMsg() method, 544
CCR message (ISUP)
continuity check, 630, 649, 680
CCR message (TUP)
CFN messages (ISUP)
sending, 591
CGB message (ISUP)
receiving, 701
CHARGING_CONF
CHARGING_IND
CHARGING_REQ
CHARGING_RESP
CHARGING_UNIT_ACK
CHARGING_UNIT_CONF
CHARGING_UNIT_IND
CHARGING_UNIT_REQ
check value
accessor (TUP), 786
China TUP
accessors, 790
flavor, 759
message classes, 790
primitives (SM mode), 768
CIC-based distribution, 43, 444, 452, 455, 456
default distribution mode, 452
loopback mode, 459
outgoing ISUP messages, 456
Platform configuration, 452
TDi routing, 456
TDi routing tables, 456
using loopback mode, 459
CIP_IND
CIP_REQ
circuit (ISUP)
active and idle, 562
blocking during setup, 699, 729
information, 464, 533
manager, 447
manipulating, 447
objects, 450
reset, 613, 641, 673
circuit blocking (ISUP)
from network, 697, 725
circuit group (ISUP)
ANSI based messages, 589
blocking, 701, 730
ITU-T based messages, 590
message handling, 588
messages, 588
normal reset, 616
queries, 708, 741
reset, 616
unblocking, 701, 730
circuit group (TUP)
messages, 813
circuit group queries, 708, 741
circuit group queries (ISUP)
from a network, 708, 741
from application (ITU-T based), 742
circuit group reset (ISUP)
double reset, 618
failure, 617
from network, 616
from user, 643, 675
normal, 643, 675
circuit groups (ISUP)
blocking/unblocking, 580
circuit reservation
ANSI based, 644
T_CRA expiry, 645
circuit reset (ISUP)
successful, 613, 641, 673
circuit states
propagating, 564
synchronizing, 564, 565
TUP, 816
updating, 564, 567
circuit states (ISUP)
timer activity, 600
circuit states (TUP)
managing, 805
circuit unblocking (ISUP)
from network, 697, 698, 699, 725, 727, 728
from user, 698, 727
circuit update mechanism
activating stand-by application, 566
High Availability (ISUP), 552, 562
propagating states, 564
states (ISUP), 563
synchronizing states, 565
CIRCUIT_RESERVATION_IND
CIRCUIT_RESERVATION_RESP
CIRCUIT_VALIDATION_CONF
CIRCUIT_VALIDATION_IND
CIRCUIT_VALIDATION_REQ
CIRCUIT_VALIDATION_RESP
905
circuits
inbound, 573
outbound, 573
circuits (ISUP)
blocking/unblocking, 576
circuitStateIndicator parameter, 708, 741
classes
message (ITU-T TUP), 794
message (TUP), 790
classname, 465
CLOSE_FAILED, 493
closeOnCreate parameter
MTP3/M3UA, 94
TCAP, 221
closeOnEnable parameter
MTP3/M3UA, 94
TCAP, 221
CloseStatus, 493
CNX_CLOSED, 491
CnxStatus, 491
CnxStatus return status, 478
cnxStatus() method, 478
collision
call release (ISUP), 609, 610
combining linksets, 90
compiler
ASNI, 200
compilers
aCC, 308
compiling and linking
TCAP API, 197
CON message (ISUP)
incoming calls, 667
outgoing calls, 667
using, 667
conditions (ISUP)
IDLE, 613, 641, 673
conditions (TUP)
IDLE, 860
configuration
dynamic, 494
dynamic (TUP), 767
High Availability, 562
standby application, 562
switchover, 562
Configuration file
Application, 454
ISUP, 455
configuration file
contents, 464
declaring classnames, 465
906
errors in contents, 464
installation, 461
loading, 461, 464, 533
configurations
1-host cluster, 66
2-host cluster, 66
development, 66
Development Platform, 43
distributed, 66
FE/BE, 66
HA, 71, 208
CONFUSION_IND
congestion (TUP)
control, 803, 804
CONNECT_INIT, 493
CONNECT_LOOP_IND
connections
as file descriptors, 476
as service access points, 71, 75
closing, 76, 482
connecting to the active stack, 71
creating, 71
destroying related entities, 76
end-to-end, 573
exchange of information, 75
HP OpenCall SS7 Stack relationship, 450
identifiers, 71
receiving information, 75
sending information, 75
setting transit time, 78
used by application, 448
See also probe objects.
CONNNECT_LOOP_IND
CONNNECT_LOOP_IND_ACK
CONNNECT_TRANSCEIVER_IND
CONNNECT_TRANSCEIVER_IND_ACK
container
Plug-In, 309
containment tree, 410, 422
ANSI, 661
current circuit, 661
current circuit (ISUP), 630, 649, 680
failed, 630, 663
not required on this circuit, 664
previous circuit, 664
procedure (ISUP), 573
continuity check (ISUP)
CCR, 630, 649, 680
IAM, 630, 649, 680
continuity check (TUP)
CCR message, 834
current circuit, 834
failed, 837
IAM message, 834
successful, 834
continuity check request
CRM, 661
ANSI, 652
failed, 663
ITU-T, 684
outgoing side, 656, 658, 688
T24 expiry, 658, 688
TCCR expiry, 656
continuity recheck (TUP)
outgoing side, 842
successful, 838
T8 expiry, 842
controlling side
dual seizure (TUP), 819
CQR message (ISUP)
sending, 708, 741
CreateStatus, 492
CRM
continuity check request, 661
customized messages, 592
D
decode function
TUP, 784
Default platform configuration
CIC-based distribution, 452
Destination Point Code (DPC), 464, 533
status, 574
DestroyStatus, 492
dialogues
simultaneous TCAP, 267
DISABLE_ECHO_IND
dispatching
tables, 292
dispatching algorithms
round robin, 281
907
user-supplied, 281
double reset (ISUP)
circuit group reset, 618
doWork
scheduling, 476
DPC
object, 578
state changes, 578
states, 578
status, 574
DPC states, 578
dual seizure (ISUP)
SETUP request, 603, 604
dual seizure (TUP)
call setup, 818
controlling side, 819
detection, 817, 819
example, 819
non-controlling side, 818
outgoing refused, 819
dynamic configuration
using, 494
using (TUP), 767
E
ENABLE_ECHO_IND
ENABLE_ECHO_IND_ACK
encode function
TUP, 785
end-to-end connection, 573
environment
developer, 42
runtime, 42
error, 629
handling, 448
error codes, 83
examples
BP mode (ISUP), 498
BP mode (TUP), 899
bypass access (ISUP), 498
bypass access (TUP), 899
call setup/release (ISUP), 497
908
call setup/release (TUP), 899
closing IsupSMProbe object, 483
creating IsupSMProbe object, 469, 471
destroying IsupSMProbe object, 483
identifying a set of messages, 533
initializing IsupMgr object, 464
ISUP SM mode, 497
ISUP tutorials, 497
opening IsupSMProbe object, 469, 471
redefining activityObject methods, 480,
487, 489
SCCP tutorials, 192
TUP SM mode, 899
TUP tutorials, 899
using reload feature, 496
Execution API
definition, 308
exit message (ISUP)
ANSI, 648
normal, 648
EXIT_IND
F
facility exchange
failure, 694
succesful, 693
facility invocation, 693
FACILITY_ACCEPT_IND
FACILITY_ACCEPT_REQ
FACILITY_IND
FACILITY_REJECT_IND
FACILITY_REJECT_REQ
FACILITY_REQ
FACILITY_REQUEST_IND
FACILITY_REQUEST_REQ
failed
continuity check (TUP), 837
failure condition
reporting (ISUP), 602
fault
FTC, 308
file descriptors
bit masks, 73
processing, 74
files
sys.tcap, 274
TCAP_ansi.h, 243
TCAP_common.h, 272
Finite State Machines (ISUP)
implementation particularities, 570
limitations, 570
supported, 570
Finite State Machines (TUP)
implementation particularities, 810
limitations, 810
supported, 810
flavors
TUP, 759
flow control, 79
application, 559
application back-pressure, 561
back-pressure, 559
inbound path, 560
IPC, 543
network back pressure, 560
outbound path, 560
queued indications, 545, 559, 560
queued messages, 543, 559, 560
flow control (TUP)
IPC, 803
outbound path, 803
flush() method, 558
flushConditional() method, 558
forward transfer, 627
forward transfer message
normal, 627
FSM
definition, 308
FTC
definition, 308
functionality
primary/secondary, 574
functions
TCAProuter_trace(), 297
functions (TUP)
decode, 784
encode, 785
fusion method, 530, 542
G
get value
accessor (TUP), 786
getCircuitState() method, 562
getMsgType() method, 544
getNumberOfCircuit() method, 547
Global Title (GT)
local translation, 172
nature of address indicator, 166
numbering plan, 166
remote translation, 171
routing, 116
table, 166
translation, 116, 166, 171, 172, 177
translation table, 171, 172
translation type, 166
types used on hybrid stack, 205
group blocking (ISUP)
(hardware oriented) during call setup, 740
(hardware oriented) from Network, 732
(hardware oriented) from user, 734, 738
(maintenance oriented) during call setup,
739
(maintenance oriented) from user, 733, 737
during call setup, 706
from user, 704
hardware reasons, 730
maintenance reasons, 730
group unblocking (ISUP)
(hardware oriented) from network, 736
(hardware oriented) from user, 737, 738,
739, 740
(maintenance oriented) form network, 735
from network, 705
from user, 706
GROUP_BLOCKING_CONF
909
GROUP_BLOCKING_IND
GROUP_BLOCKING_REQ
GROUP_BLOCKING_RESP
GROUP_QUERY_CONF
GROUP_QUERY_IND
GROUP_QUERY_REQ
GROUP_QUERY_RESP
GROUP_RESET_CONF
GROUP_RESET_IND
GROUP_RESET_REQ
GROUP_RESET_RESP
GROUP_STOP_CONF
910
GROUP_STOP_REQ
guidelines
H
HA API
definition, 308
HA mechanisms, 74
HA process, 444
High Availability
configuration, 562
HA, 452
HP OpenCall ISUP
circuit manager, 447
core, 447
encoder/decoder mechanism, 530, 532
features, 47
forcing network back-pressure, 560
interaction scenarios, 573
IPC buffers, 557
metadata, 447
protocol behavior, 451
scheduling, 474
state-machines, 447, 504, 560
supported messagesSee also messages
timers, 461
HP OpenCall ISUP Library
access, 444
interface, 447, 460
services, 504
HP OpenCall SS7 family, 761
HP OpenCall SS7 Stack
access to SS7 network, 761
accessing network, 444
back-pressure, 560
classname, 465
closing connection, 482
connection objects, 462
connections, 448
deleting messages, 560
IPC buffers, 557
maximum number supported, 450
message exchange, 447
opening a connection, 466
releasing connections, 554
status, 479
HP OpenCall TUP
end-to-end signalling, 761
features, 47, 761, 763, 765, 766, 767, 801,
802, 803
scheduling, 766
HP-UX, 474
hybrid stack, 204, 205
hybrid stacks, 197, 205
I
I/O
activity, 474
multiplexing, 474
IAM message (ISUP)
circuit unblocking, 699, 728
continuity check, 630, 649, 680
length, 593
IAM message (TUP)
IDLE condition
ISUP, 613, 641, 673
TUP, 860
immediate release
TUP, 824
INAP service key, 290
inbound and outbound circuits, 573
inbound flow control, 79
incoming (SAM message), 827
incoming (SAO message), 827
incoming (TUP)
solicited information exchange, 829
incoming call (TUP)
immediate release, 824
successful setup, 825
unsuccessful setup, 823
incoming calls
suspend/resume messages, 646, 676
incoming messages from unassigned circuits
, 456
incoming reset
ISUP, 611
incoming with immediate release, 606
Inconsisent modes, 452
Inconsistent distribution, 452
inconsistent distribution modes, 452
information elements, 555
information exchange, 620
solicited, 621, 622
911
TUP, 828, 829
unsolicited, 623
information messages
solicited, 620
unsolicited, 620
INFORMATION_IND
INFORMATION_REQ
InitStatus return status, 491
interaction scenarios, 573
interactions handling, 574
interface
programming, 308
INTERNAL_ERROR, 491, 493
Inter-Process Communication (IPC)
buffer sizes, 78
buffering modes, 77, 78
buffers, 77
flow control, 79
flushing the send buffer, 77
optimizing, 60
reducing IPC calls, 78
reducing transit time, 78
SS7 stack communication, 72
tuning MTP3 buffers, 105
tuning performance, 78
tuning TCAP IPC buffers, 269
invalid length
INVALID_CLASSNAME, 492
INVALID_ISUP_MSG_IND
primitive (BP Mode), 523
INVALID_SET_NAME, 492
invocation
facility (ISUP), 693
IPC
buffers, 557, 558
configuration, 558
congested state, 561
default buffers, 558
definition, 308
flow control, 581
flow control (TUP), 803
optimizing performance, 558
IPC_SEND_FULL, 493
912
is, 452, 459
ISUP, 444, 452, 600
applications, 47
behavior, 447
makefiles, 499
messages, 585, 586
parameters, 447
primitives, 503
protocol event, 560
tutorials, 497
ISUP API
as stack API, 44
services provided, 47
ISUP CIC-based distribution
Traffic Discriminator, 454
ISUP traffic loss
traffic loss, 452
ISUP tutorials, 497
ISUP_MSG_IND
ISUP_MSG_REQ
ISUP_USR_MSG_IND
ISUP_USR_MSG_REQ
IsupBPProbe
accessing MTP3, 504
activity object, 478
creating, 465
description, 462
initialization, 462
interaction with HP OpenCall ISUP
Library, 504
methods, 460
sending messages, 462, 543
IsupBPProbe primitives
INVALID_ISUP_MSG_IND, 485, 523
ISUP_MSG_IND, 523
ISUP_MSG_REQ, 523
PASS_ALONG_IND, 523
PASS_ALONG_REQ, 523
UNKNOWN_MSG_IND, 523
UNKNOWN_MSG_REQ, 523
UNKNOWN_OPC_MSG_IND, 524
IsupInfoMgr
class (TUP), 787
IsupMgr
base class, 529
creating probe objects, 465
derived message classes, 529
function, 461
identifying sets of messages, 533
initializing, 464
initializing (TUP), 765
instance, 462
loading configuration file, 533
managing return status values, 549
methods, 460, 530
object description, 461
previously created, 464
relationship to message classes, 529
relationship to probe and message classes,
541
tracing the encoding/decoding mechanism,
532
See also scheduling
IsupMsg
class (TUP), 787
description, 529
methods, 530
receiving instance of, 544
IsupProbe
base class, 462
description, 462
methods, 460, 558
IsupSMProbe
accessing MTP3, 504
activity object, 478
circuit state updating, 562
creating, 465
description, 462
initialization, 462
interaction with HP OpenCall ISUP
Library, 504
methods, 460, 562
sending messages, 462, 543
IsupSMProbe object
closing and destroying, 483
IsupSMProbe primitives
RELEASE_RESP, 561
RESET_RESP, 561
START_RELEASE_IND_ACK, 561
START_RESET_IND_ACK, 561
STOP_REQ, 561
IsupUserMsg
description, 530
See also message customizing.
ITU messages, 280
ITU-T
Blue Book TCAP, 214
Global Title types, 149
protocol (ISUP), 445
recommendations, 149
software versions (ISUP), 445
suspend/resume messages, 676
TCAP versions, 204
TUP flavor, 759
White Book TCAP, 202, 214, 251
ITU-T 88
recommendations (ISUP), 529
state-machines (ISUP), 447, 451
ITU-T 97
flavor (ISUP), 683
ITU-T TUP
accessors, 794
message classes, 794
primitives (BP mode), 779
ITU-T93
ITU-T97
L
layer
TCAP component, 200
TCAP transaction, 200
layers
M3UA, 86, 87
SCTP, 87
length
invalid parameter length (TUP), 786
library
shared, 92, 197
shared (SCCP), 131
Timer, 309
limits
message size, 102
linksets
combining, 90
load balancing, 288
loadsharing, 210
913
algorithm, 47
MTP3, 106
multiple TCAP users and mutiple
connections, 211
round-robin algorithm, 211
single TCAP user with multiple
connections, 210
using SLS, 89
using SSN, 210
local alias
definition, 50
Local Point Code (LPC), 464, 533
Local Point Code (LPC) status, 574
LPC
object, 574
object states, 574
status, 574
LPC states, 574
LPC_NOT_FOUND, 492
M
M3UA
description, 86, 87
M3UA API
as stack API, 44
description, 86
M3UA-based platform
message size limit, 102
MAINTAINANCE_IND
MAINTENANCE_SYATEM_IND
T20_NOT_RUNNING, 749
MAINTENANCE_SYSTEM_IND values
BACKWARD_CHECK_TONE_ACK, 755
BLA_WHEN_IDLE, 756
COT_RECEIVED, 748, 755
CRS_STOP, 749
DCO_FAIL, 748
DCO_SUCCESS, 748
HW_BLOCKING, 754
HW_GROUP_BLOCKING, 753
HW_GROUP_UNBLOCKING, 753
HW_UNBLOCKING, 754
MN_BLOCKING, 754, 755, 756
MN_GROUP_BLOCKING, 753
914
MN_GROUP_UNBLOCKING, 753
MN_UNBLOCKING, 755, 756
PRIORITY_TO_GROUP_RESET, 754
RECV_ON_UNEQUIPPED_CIRCUIT,
749, 753
REL_RECEIVED, 755
RLC_AFTER_T17, 749, 754
RSC_AFTER_T17, 749
STOP_REQ, 749
T13_TIMEOUT, 748, 755
T15_TIMEOUT, 748, 755
T17_TIMEOUT, 749, 754
T18_NOT_RUNNING, 749, 754
T19_TIMEOUT, 749, 753
T21_TIMEOUT, 749, 754
T23_TIMEOUT, 748
T24_TIMEOUT, 755
T28_TIMEOUT, 755
T34_TIMEOUT, 755
T5_TIMEOUT, 748, 755, 756
TIMER_SHORTAGE, 749, 753
UBA_WHEN_LOCALLY_BLOCKED, 756
UNEQUIPPED_CIRCUIT, 749, 753
WRONG_STATUS_BITS, 749
makefiles
ISUP, 499
TUP, 900
management
APIs, 44, 48
application, 48
mark as absent
accessor (TUP), 786
MAX_PROBE_NUMBER_EXCEEDED, 492
memory
dynamic allocation (ISUP), 554
freeing, 555
requirements, 59
shortage (ISUP), 554
message
reassembly, 594
transfer optimizing, 208
transit time, 209
message classes (ISUP)
abstract interface, 447, 529
base class, 529
behavior, 530
casting an instance of, 544
constructors, 534, 539
for customized messages, 530
function, 447
generic component, 447
IsupIam, 536
IsupUserMsg, 530
message-specific interface, 529
relationship to IsupMgr, 529
relationship to metadata, 531
relationship to probe and IsupMgr classes,
541
representing messages, 447, 529
message customizing (ISUP)
modifying the metadata, 447
message flow, 600
TUP, 816
message parameter values
as objects, 539
assigning 16 bit values, 539
assigning values, 539
base class, 539
creating, 555
creating objects, 555
deleting, 555
management, 555
message parameters
accessing optional parameters (ISUP), 536
assigning values (ISUP), 539
in message classes, 529
mandatory (ISUP), 539
mandatory parameters, 534
optional parameters (ISUP), 539
message sets (ISUP)
ANSI-92, 445
ANSI-95, 445
ITU-T93, 445
ITU-T97, 445
message transfer
ISUP, 47
TUP, 47, 761
messages
buffering, 77
discriminating, 107
distributing, 107
identifying set of messages, 533
in-sequence transfer, 153
queued, 80
receiving, 75, 107, 173, 202, 257, 263
receiving (ISUP), 555
retransmitting, 177
routing, 106, 168, 198
SAM (ISUP), 669
sending, 75, 106, 153, 168, 202, 243, 254, 262
session, 309
size limits, 102
structure, 140, 202
waiting to be received, 80
See also message classes.
messages (ISUP)
accessing parameters, 529, 536
Bypass, 586
CFN handling, 591
CGB, 701
circuit group, 588
Circuit Query Response, 708, 741
CON, 667
creating instances, 534, 555
customized, 592
default message structure, 534, 539
defined for LPC/DPC pair, 533
deleting instances, 555
exit, 648
facility, 634
facility accepted, 693
facility reject, 693
facility request, 693
forward transfer, 627
generic processing, 585, 586
generic processing (BP), 586
generic processing (SM), 585
group blocking, 701, 730
identifying message type, 544
identifying messages for LPC/DPC pair, 533
in inbound queue, 545
in outbound queue, 543
internal structure, 534
ITU-T, 693
management, 555
MessageSetName, 533
operator specific, 530
pass-along, 628
processing parameters, 544
915
receiving, 560
SAM, 669
SAM message, 668
sending, 543, 555, 560
setting buffering mode, 557
SM probe, 585
standard metadata, 447
storing in internal buffers, 557
supported by API, 447
suspend/resume, 646, 676
tracing the encoding/decoding mechanism,
532
UCIC, 591
UCIC handling, 591
unknown, 597
unrecognized, 597
user defined, 592
messages (TUP)
circuit group, 813
classes (CTUP), 790
classes (ITU-T TUP), 794
module classes, 787
metadata
contents, 530
coordinating encoding/decoding, 532
governing encoding/decoding, 530
governing message classes, 530
software version, 531
specific component (ISUP), 447
standard (ISUP), 447, 531
METERING_PULSE_IND
METERING_PULSE_REQ
methods
assign(), 539
castMsg(), 544
cnxStatus(), 478
common probe methods, 462
failure, 549, 561
flush(), 558
flushConditional(), 558
getCircuitState(), 562
getMsgType(), 544
getNumberOfCircuit(), 547
new(), 554
receive(), 544
recvActivity(), 478
916
releaseCircuit(), 547
select(), 475
send(), 481
sendPossible(), 478, 561
setBufferingMode(), 558
setCircuitState(), 562
setHighTransitTime(), 558
setIPCRecvSize(), 558
setIPCSendSize(), 558
setLowTransitTime(), 558
setNonBufferingMode(), 558
setTraceOff(), 532
setTraceOn(), 532
success of, 549
modifying
configuration (dynamic), 494, 767
MPT3
interactions handling, 574
LPC states, 574
MTP
transfer indications, 577
MTP Level 3
DPC available, 108
DPC congestion, 109
DPC unavailable, 107
DPC uncongested, 110
features, 86
link management, 90, 108, 109
message handling, 89, 106
MSU functions, 89, 106
network management, 89
primitives, 98
restart procedure, 111
route management, 90, 106
routing label, 106
services, 46
traffic management, 90
MTP_AVAILABLE_IND primitive, 528
MTP_CONGESTED_IND, 528
MTP_DPC_CONGESTED_IND primitive,
528
MTP_DPC_UNCONGESTED_IND
primitive, 528
MTP_PAUSE_IND primitive, 528
MTP_RESTARTING_IND, 528
MTP_RESUME_IND primitive, 528
MTP_UNAVAILABLE_IND primitive, 528
MTP_UNCONGESTED_IND, 528
MTP_UPU_UNAVAILABLE_IND, 528
MTP2 OA&M API
array of active connections, 405
closing connections, 433
creating connections, 404
flow control, 409
function calls refused, 433
MTP2X_oamrecv(), 408, 409
no notifications received, 409
post-select phase, 405
pre-select phases, 405
receiving notifications, 409
requests, 408
scheduling connections, 405
MTP2 OA&M API functions
MTP2X_oamrecv(), 408, 409
SS7_ifclose(), 433
SS7_ifcnxhandler(), 405
MTP3, 574, 575
access (ISUP), 462, 504
access (TUP), 768
blocking (ISUP), 559
interactions handling (ISUP), 574
releasing connection (ISUP), 554
status (ISUP), 528
MTP-3 API
as stack API, 44
MTP3 API
connections, 93, 103
description, 86
DPC available, 108
DPC congestion, 109
DPC uncongested, 110
guidelines, 86
indications, 98
local MTP restart, 111
local MTP unavailable, 111
MSU primitives, 106, 107
pre-select phase, 95
primitives, 97, 108, 110, 111
receive IPC buffer, 100, 105
receiving MSUs, 106
requests, 98
return values, 108, 111
scheduling, 94
scheduling functions, 95
select(), 95
send IPC buffer, 102, 105
sending MSUs, 102, 106
terminating a service, 104
tuning IPC buffers, 105
MTP3 API functions
MTPL3_recv(), 100
MTPL3_send(), 102
SS7_ifclose(), 104
SS7_ifctrl(), 105
SS7_ifselectmask(), 95
MTP3 connections
closing, 104
cnxId, 94
creating, 93
destroying all related entities, 104
in an array, 96
scheduling, 95
MTP3 OA&M API
an array of active connections, 405
collecting statistics, 417
configuring entities, 410
requests, 416
ss7errno, 416, 419, 421, 427, 430, 432
MTP3 OA&M API functions
MTL3_oamstat(), 419
MTPL3_oamcmd(), 416, 419, 420, 427, 430,
431
SS7_if close(), 433
SS7_ifcnxahndler(), 405
MTP3 primitives, 574
MTP_AVAILABLE_IND, 528
MTP_CONGESTED_IND, 528
MTP_DPC_CONGESTED_IND, 528
MTP_DPC_UNCONGESTED_IND, 528
MTP_PAUSE_IND, 528
MTP_RESTARTING_IND, 528
MTP_RESUME_IND, 528
MTP_UNAVAILABLE_IND, 528
MTP_UNCONGESTED_IND, 528
MTP_UPU_UNAVAILABLE_IND, 528
MTP3 routing
917
providing the SIO, 102
MTP3/M3UA tutorials, 112
MTP3-based platform
message size limit, 102
multiple APIs, 44, 68, 74
N
network events, 553
Network Service Data Unit (NSDU), 118, 121
Network Service Part (NSP), 46, 116, 202
NETWORK_RESOURCE_MGT_IND
NETWORK_RESOURCE_MGT_REQ
new() method, 554
NO_CONFIG, 493
NO_ERROR, 493
NO_MORE_MEMORY
return status, 554
non-controlling side
NOP
definition, 308
normal
call release (ISUP), 608, 637, 670
number
of maximum invocations, 265
of maximum simultaneous dialogues, 267
of messages waiting to be received, 80
of scheduling loops, 74
O
OA&M
configuration, 400
control, 400, 416, 427
entities, 402
notifications, 403
requests, 403
services, 400
states, 402
statistics, 400
OA&M API
addressing, 424
array of active connections, 405, 436
closing connections, 433, 442
collecting MTP3 statistics, 417
collecting SCCP statistics, 428
collecting TCAP statistics, 440
configuring entities, 410
creating connections, 404, 435
918
flow control, 409
guidelines, 399
post-select phase, 405, 436
pre-select phase, 405, 436
receiving MTP2 notifications, 409
receiving MTP3 notifications, 420
receiving SCCP notifications, 431
scheduling connections, 405, 436
sending MTP2 requests, 408
sending requests, 416
sending SCCP requests, 427
sending TCAP requests, 437
ss7errno, 416, 419, 421, 427, 430, 432
OA&M API functions
MTL3_oamstat(), 419
MTP2X_oamrecv(), 409
MTPL3_oamcmd(), 416, 419, 420, 427, 430,
431
MTPL3_oamrecv(), 420
SCCP_oamcmd(), 427
SCCP_oamrecv(), 431
SCCP_oamstat(), 429
SS7_ifclose(), 433
TCX_cnx_handler(), 436
TCX_control(), 438
TCX_recv(), 440
TCX_select_mask(), 436
OA&M APIs
as management APIs, 44
OA&M entities
addressing, 402, 411, 424
configuring, 410
destroying entities, 433
managing the SS7 stack, 402
MTP3, 410
notifications, 403
object-oriented structure, 402
performing operations, 402
requests, 403
returning replies, 402
SCCP, 422
state of, 402
OA&M notifications
contents, 420
generated, 409
MTP2, 409
MTP3, 420
SCCP, 431
spontaneous, 403
OA&M requests
MTP2, 408
MTP3, 416
perform operation, 403
return notification, 403
SCCP, 427
TCAP, 438
OA&M states
changing, 402, 426
mode of notification, 402, 426
MTP3, 411
OA&M statistics
collecting, 440
entity relationship, 417, 428
immediate, 417, 428, 438
modes of collecting, 417, 428
MTP3, 417
on occurrence, 417
periodic, 417, 428, 438
report modes, 417, 428
SCCP, 428
TCAP, 440
OAM API
effect of VPC, 53
object
destination, 411
links, 411
linkset, 411
local_alias, 411
LPC, 574
mtp, 411
route, 411
SO_FAILED_DEST, 423
SO_GT_TRANSLATOR, 423
SO_LOCAL_USER, 423
SO_REMOTE_SP, 423
SO_REMOTE_USER, 423
SO_SCCP, 423
SO_VIRTUAL_USER, 423
virtual_pc, 411
object classes
ActivityObject, 476, 478
base class, 448
derived classes, 448
for ISUP messages, 447
inheritance, 448
IsupBPProbe, 462
IsupMgr, 461
IsupMsg, 529
IsupProbe, 462
IsupSMProbe, 462
IsupUserMsg, 530
parent classes, 448
ParmValue, 539, 555
probe classes, 462
object model
ISUP, 460
objects
additional information, 555
behavior of, 448
contents, 448
deleting (ISUP), 554
destroying, 448
DPC, 578
general guidelines, 448
inactive, 562
instantiation (ISUP), 554
lifespan, 448
management (ISUP), 555
memory shortage (ISUP), 554
message parameter values, 555
messages (ISUP), 555
parameter values (ISUP), 555
processing overhead, 448
representing connections, 448
return status values, 555, 556
objects (TUP)
management, 802
OC
definition, 308
Open Systems Interconnection (OSI), 46
OpenStatus, 493
OPERATOR_SIGNAL_IND
OPERATOR_SIGNAL_REQ
OUT_BUFFER_FLUSH, 208
outbound flow control, 79
outbound path
TUP, 803
outgoing (SAM message), 826
outgoing (SAO message), 826
outgoing (TUP)
information exchange, 828
normal release, 852
919
outgoing call
outgoing call (TUP)
successful setup, 824
unsuccessful setup, 822
outgoing calls (ISUP)
suspend and resume messages, 677
P
parameter
circuitStateIndicator, 708, 741
parameters
aProbe, 478
aStatus, 478
backwardCallIndicators, 628, 629
calledPartyNumber (TUP), 790
nbOfRecvToDo, 478
rangeAndStatus, 736
subsequentNumber (TUP), 790
SuspendResumeIndicator, 676
parameters (ISUP)
message, 544
rangeAndStatus, 588, 616, 704, 708, 733,
734, 735, 741
supported, 550
parameters (TUP), 798
invalid length, 786
rangeAndStatus, 813
partitioning, 287
PASS_ALONG_IND
PASS_ALONG_MSG_IND
PASS_ALONG_REQ
pass-along requests, 629
normal, 628
path
outbound (TUP), 803
paths
back-pressure, 559
flow control, 559
inbound, 559
outbound, 559
PCA
definition, 308
920
peer node, 637, 670
PIC
definition, 309
PIC Framework
definition, 309
PIC/AG
API, 49
definition, 308, 309
plug-in
definition, 309
Plug-In Container
definition, 309
Plug-In tutorials, 343
point code
alias, 50
PRE_REL_INFORMATION_IND
PRE_REL_INFORMATION_REQ
previous circuit
previous circuit (TUP)
primary/secondary functionality, 574
primitive, 98
primitive flow
TUP, 816
primitives
acknowledgment, 504
blocking/unblocking circuits, 579
categories (ISUP), 503
circuit related (ISUP), 504
description (ISUP), 503
dialogue (ISUP), 503
generic processing, 581, 583
MTP related, 528
MTP3, 574
race conditions (ISUP), 553
receiving, 560
rejection by API, 561
requiring additional information (ISUP),
524
resetting circuit groups, 576, 579
resetting circuits, 576, 579
side-effect of protocol events, 560
stopping REL/RSC retransmission, 577, 580
synchronizing with application (ISUP), 553
terminating calls, 576, 579
terminating primitive, 561
to synchronize with application, 504
primitives (ISUP)
acknowledgment, 504
additional information, 524, 555
blocking/unblocking circuit groups, 576, 580
blocking/unblocking circuits, 576
primitives (TUP)
BP mode, 779
China TUP (SM mode), 768
exchanging, 768
ITU-T TUP (BP mode), 779
ITU-T TUP (SM mode), 774
requiring additional information, 780
priority
application, 59, 62
SS7_Stack process, 62
probe
SM, 581
probe objects
activating, 466
base class, 462
bound to HP OpenCall SS7 Stack, 465
closing, 482
creating, 465
derived classes, 462
destroying, 482
exchanging primitives and messages, 481,
504
exchanging primitives and messages
(ISUP), 541
interaction with HP OpenCall Library, 504
lifespan, 482
memory shortage (ISUP), 554
opening, 465
recreating and re-opening, 482
relationship to message classes and
IsupMgr, 541
representing connections, 450
scheduling, 461, 474
selecting access modes (ISUP), 451
using activity object, 478
probe objects (TUP)
exchanging primitives and messages, 766
PROBE_NOT_OPEN, 493
probes
BP, 583
Bypass, 583
SM, 585
probes (ISUP)
BP, 586
procedures
call setup (ISUP), 600, 602
call teardown (ISUP), 600
continuity check (ISUP), 573
procedures (TUP)
call setup, 816
call teardown (TUP)
procedures, 816
processes
HA, 62
SS7_Stack, 62
programming
interface, 308
PROGRESS_IND
PROGRESS_REQ
propagating
states, 564
protocol event, 80, 524
protocols
ANSI, 445
protocols (ISUP)
ITU-T, 445
R
race condition
ISUP, 553
rangeAndStatus
parameter (ISUP), 588, 616, 704, 708, 733,
734, 735, 741
rangeAndStatus parameter, 736
REANSWER_IND
REANSWER_REQ
reassembly
incoming messages, 594
reassembly of incoming messages
failure, 594, 595
interacting with continuity check, 596
receive() method, 544
receiving
CFN messages, 591
UCIC messages, 591
921
refusal
setup locally refused (TUP), 816, 817
refused function calls, 104
Registry API
definition, 309
REL message
stopping retransmission, 577, 580
release (TUP)
successful call release, 799
RELEASE_CONF
RELEASE_IND
RELEASE_REQ
RELEASE_RESP
RELEASE_RESP primitive, 561
releaseCircuit() method, 547
remote DPC, 578
status indications, 578
REMOVE_LOOP_IND
REMOVE_LOOP_IND_ACK
922
rescheduling
See scheduling.
reset (ISUP)
ANSI standard, 613
circuit, 613, 618, 641, 673
circuit group, 616, 617
double, 618
failure to receive RLC, 641, 673
from application, 615
from network, 614
HP OpenCall initiated, 613, 641, 673
incoming, 611
ITU-T standard, 613
reset (TUP)
failure to receive RLC, 865
successful, 864
TUP initiated, 864, 865
RESET_CONF
RESET_IND
RESET_REQ
RESET_RESP
RESET_RESP primitive, 561
RESUME_IND
RESUME_REQ
return status
CloseStatus, 493
CnxStatus, 478, 491
CreateStatus, 492
DestroyStatus, 492
InitStatus, 491
OpenStatus, 493
return status values
ALREADY_CLOSED, 493
ALREADY_CREATED, 491
ALREADY_DESTROYED, 492
ALREADY_OPEN, 493
API_BUSY, 491, 493
BAD_CNX_TYPE, 493
BAD_GLOBAL_CONFIG, 493
BAD_ISUP_CONFIG, 491
CLOSE_FAILED, 493
CNX_CLOSED, 491
CONNECT_INIT, 493
for error handling, 448
in race conditions, 553
INTERNAL_ERROR, 491, 493
INVALID_CLASSNAME, 492
INVALID_SET_NAME, 492
IPC_SEND_FULL, 493, 561
LPC_NOT_FOUND, 492
managed by IsupMgr, 549
management, 556
MAX_PROBE_NUMBER_EXCEEDED,
492
NO_CONFIG, 493
NO_ERROR, 491, 493
NO_ISUP_CONFIG, 491
NO_MORE_MEMORY, 491, 554
PROBE_NOT_OPEN, 493
unexpected values, 553
WRONG_PROBE_TYPE, 492
WRONG_STATE, 553
return values
examining, 83
MTP3 API, 108, 111
TCAP API, 272
reverse hybrid stack, 204, 205
RLC message (TUP)
not received, 865
round robin algorithm, 281, 289
rounding
parameter length (TUP), 798
rounding length, 798
round-robin algorithm, 211
routing
MTP3 routing label, 106
SCCP end-to-end, 116
RSC message
stopping retransmission, 577, 580
S
SAM message
outgoing calls (ISUP), 669
SAM message (ISUP)
incoming calls, 669
using, 668
SAM message (TUP), 826, 827
incoming, 827
outgoing, 826
SAO message (TUP), 826, 827
incoming, 827
outgoing, 826
SCCP
addressing, 119, 126
application pairs, 126
connection oriented services, 121
connectionless services, 118
description, 116
end-to-end signalling, 761
features, 118
Global Title, 116, 119, 126, 148
message handling, 118
primitives, 137
relay, 121
restart, 119
retransmitting messages, 177
return option, 118, 177
routing, 116, 118
services, 46, 116, 761
signalling point status management, 119,
126, 180
subsystem management, 116, 119
subsystem status management, 183
subsystem status test, 119, 185
subsystems, 120, 187
traffic distribution, 129
traffic filtering, 127, 133
tutorials, 192
users, 116
SCCP API
addressing, 160, 171
ANSI Global Title structure, 149
as stack API, 44
confirmations, 138, 139
congested DPC, 182
connection oriented services, 153
923
connectionless services, 131, 153
connections, 132
effect of VPC, 53
Global Title, 149
guidelines, 115
indications, 138, 139
in-sequence message transfer, 153
IPC buffer values, 155
ITU-T Global Title structure, 149
masks, 95, 134
no GT translation, 171
primitives, 137, 168
receive IPC buffer, 150, 155
request, 139
requests, 138
rescheduling, 154
response, 138, 139
return option, 177
routing, 160
routing mechaism, 168, 173
scheduling, 134
send IPC buffer, 154, 155
sending SCCP primitives, 150, 168
signalling point, 180, 181, 182
structure of message parameters, 138
subsystems, 184, 185, 188, 190, 191
terminating a service, 154
SCCP API functions
SCCP_recv(), 150
SCCP_send(), 153
SS7_ifclose(), 154
SS7_ifcreate(), 404
SS7_ifctrl(), 155
SCCP connections
and their IPC buffers, 155
closing, 92, 131, 154
creating, 132
destroying all related entites, 154
forwarding, 122, 156
in an array, 135
scheduling, 134
SCCP OA&M API
924
addressing, 424
controlling, 427
notifications, 431
requests, 427
translator id, 425
SCCP OA&M API functions
SCCP_oamcmd(), 427
SCCP_oamrecv(), 432
SCCP_oamstat(), 429
SS7_ifclose(), 433
SS7_ifselect(), 405
SCCP routing
activate, 168, 173
DPC and SSN, 177
mechaism for incoming messages, 173
mechaism for outgoing messages, 168
routing indicator, 172
using a point code, 171
using backup signalling points, 180
using backup subsystems, 180
using DPC, 172
using DPC and GT, 171
using DPC and new SSN, 172
using DPC and SSN, 171, 172, 177
using local GT translation, 172, 177
using local SSN, 171, 172, 177
using LPC and SSN, 172
using MTP3 routing, 172
using new SSN, 172
using remote GT translation, 171
using remote point code, 171, 172
using remote SSN, 171, 172, 177
using routing indicator, 177
using SSN, 177
without GT translation, 170, 173
scheduling
active connections, 74
activity object mechanism, 476
analyzing the masks, 476
bit masks, 73
connections, 71
doWork(), 476
estimation of work, 476
file descriptors, 73
loop in application, 74
masks, 73, 474
mechanism, 72, 474
methods, 475
methods of IsupMgr, 461
minimizing select(), 60
MTP3 API, 95
multiple APIs, 68, 74
number of select(), 74
OA&M connections, 405
phases, 474
phases of, 72
post-select, 476
pre-select, 474
probe objects, 474
probe objects (TUP), 766
processing messages, 476
processing work, 476
rescheduling a connection, 76
select(), 73
sockets, 72
TCAP connections, 223
timeout value, 73, 474
work, 476
SCTP
description, 87
segmentation
mechanism, 593
outgoing messages, 593
seizure (TUP)
dual, 817, 818, 819
select
See scheduling
select() method, 475
send() method, 481
sending
CFN messages, 591
UCIC messages, 591
sendPossible() method, 478, 561
services
provided by MTP-3 API, 46
provided by OA&M APIs, 48
provided by SCCP API, 46
provided by TCAP API, 47
session
definition, 309
set value
accessor (TUP), 786
setBufferingMode() method, 558
setCircuitState() method, 562
setHighTransitTime() method, 558
setIPCRecvSize() method, 558
setIPCSendSize() method, 558
setLowTransitTime() method, 558
setNonBufferingMode() method, 558
setTraceOff() method, 532
setTraceOn method, 532
setup (TUP)
procedures, 816
unsuccessful, 816
SETUP request (ISUP)
dual seizure, 603, 604
failure to receive ACM, 605
locally refused, 602
SETUP_CONF
SETUP_FAILURE_IND
values, 746
SETUP_FAILURE_IND values
BLOCKING, 750
COT_FAILURE, 746, 750
CPC_BUSY, 750
CRCR_RESET, 751
DUAL_SEIZURE, 746, 750
FLOW_CONTROL, 746, 751
RELEASE, 750
T27_TIMEOUT, 750
SETUP_IND
SETUP_IND_ACK
925
SETUP_REQ
SETUP_RESP
shared library, 92, 197
SCCP, 131
signaling point code, 603
signalling links
activated, 111
unavailable, 111
signalling point
accessible, 182
congested, 182
prohibited, 180
status, 180
signalling points, 450
SIGTRAN
M3UA layer, 86, 87
SCTP layer, 87
simultaneous
TCAP dialogues, 267
size
buffers, 59
memory required, 59
SM mode
example (ISUP), 497
example (TUP), 899
SM probe, 581
SM probes, 585
sockets, 72
SOFT_RESET_REQ
SOFTRESET_REQ
software components
core (ISUP), 447
generic (ISUP), 446
HP OpenCall ISUP API, 446
HP OpenCall ISUP Circuit Manager, 447
HP OpenCall ISUP Supported Messages,
447
metadata (ISUP), 447
specific (ISUP), 447
software version
926
supplied metadata, 531
software versions
ANSI, 445
software versions (ISUP)
ITU-T, 445
solicited
information exchange (TUP), 828, 829
solicited information exchange
failure, 621, 622
SOLICITED_INFO_CONF
SOLICITED_INFO_IND
SOLICITED_INFO_REQ
SOLICITED_INFO_RESP
SS7 network
accessing, 444
accessing (ISUP), 47
accessing (TUP), 47, 761
exchanging information with API, 465, 541
sending queued messages, 543
SS7 network access
ANSI and ITU-T hybrid stack, 204
local, 66, 71
remote, 66, 68, 71
SS7 stack
className, 71
coexist with APIs and applications, 66
connections, 62, 71
generic name, 71
hybrid stack, 204, 205
network back-pressure, 80
reverse hybrid stack, 204, 205
sharing CPU with applications, 62
transparent replication, 209
unable to provide any service, 209
SSN, Subsystem Number, 47
standby application
activating, 566
START_CHECK_TONE_ACK
START_RELEASE_IND
START_RELEASE_IND values
BLOCKING, 748, 752
CONTINUITY_SUCCESS, 752
DCO_SUCCESS, 748
STOP_REQ, 748
T_CRA_TIMEOUT, 748
T1_TIMEOUT, 748
T2_TIMEOUT, 752
T33_TIMEOUT, 748, 752
T6_TIMEOUT, 747, 752
T9_TIMEOUT, 752
UNEXPECTED_RLC, 747, 752
START_RELEASE_IND_ACK primitive, 561
START_RESET_IND
START_RESET_IND values
BLOCKING_WITH_RELEASE, 746
COT_CC_NOT_REQUIRED, 746, 751
DCO_LPA_FAIL, 746
DPC_UNAVAILABLE, 746
MTP_UNAVAILBLE, 746
T27_TIMEOUT, 746
T34_TIMEOUT, 746
T5_TIMEOUT, 746
TCCRr_TIMEOUT, 746
TIMER_SHORTAGE, 747, 752
UNEQUIPPED_CIRCUIT, 747, 751
UNEXPECTED MESSAGE, 746
UNEXPECTED_MESSAGE, 751
START_RESET_IND_ACK
START_RESET_IND_ACK primitive, 561
state changes
DPC, 578
state machine access
example (ISUP), 497
example (TUP), 899
State Machine Mode
primitives (China TUP), 768
primitives (ITU-T TUP), 774
state machines (TUP)
ACR, 801
state transitions, 575, 578
state-machines
ISUP, 447, 451, 476
states
DPC, 578
LPC, 574
LPC objects, 574
propagating, 564
recovering, 567
synchronizing, 565
transitions, 575, 578
status
DPC, 574
LPC, 574
status classes
See return status.
status indications, 578
remote DPC, 578
STOP_CHECK_TONE_IND
927
STOP_CONF
STOP_REQ
STOP_REQ primitive, 561
stopping
retransmission of REL messages, 577, 580
retransmission of RSC messages, 577, 580
subsequentNumber
substate
changes, 575
substates
managed, 575
subsystems
backup, 180
graceful withdrawal, 191
in service, 119, 185
management functions, 116
out of service, 119, 184
refused withdrawal, 190
replicated, 120, 188
routing through backup, 180
status, 119, 184
status management, 184
status test, 186
successful withdrawal, 189
successful
continuity check (TUP), 834
continuity recheck (TUP), 838
incoming setup (TUP), 825
outgoing setup (TUP), 824
successful incoming, 825
successful outgoing, 824
suspend/resume
messages, 646
ANSI based, 646
incoming call, 646, 676
ITU-T based, 676
outgoing call, 646, 677
928
T2 expiry, 678
T6 expriy, 625
SUSPEND_IND
SUSPEND_REQ
SuspendResumeIndicator parameter, 676
switchover
configuration, 562
effects on an application, 81
ISUP API, 82
M3UA API, 82
MTP3 API, 82
SCCP API, 81
TCAP API, 81
TUP API, 82
switchoverMTP3 API, 82
synchronizing
circuit states, 564, 565
states, 565
system requirements
buffer sizes, 59
buffered I/O, 59
CPU usage, 61
IPC, 60
memory, 59
object management, 60
optimized performance, 59
optimized performance (TUP), 763
optimum performance, 60
performance, 58
performance path, 60
platform mechanism, 61
predictability, 58
resource access, 59
responding to SS7 network requests, 58
responding to STLM, 61
scheduling, 60, 62
T
T2 expiry
T24 expiry
continuity recheck, 658, 688
T6 expiry
T8 expiry (TUP)
T9 timer (ISUP), 666
tables
dispatching, 292
TACP Application Message Dispatcher
calls to functions, 294
TCAP
application context, 202, 206
component, 201
component portion, 202
component sublayer, 47, 198, 227
description, 198
dialogue, 201
dialogue portion, 202, 205
exchange of components, 202
invocation, 227
invoke ID, 227
multiple users, 210
operation, 198, 227
reply, 227
routing, 198
services, 47
sharing incoming dialogues, 211
simultaneous dialogues, 267
simultaneously active invocations, 227
TC-user, 198, 201
transaction, 202
transaction portion, 202
transaction sublayer, 47, 198, 261
TR-user, 201
tutorials, 275
versions, 204
TCAP AMD
tutorials, 306
TCAP API
accessing the component sublayer, 227
and ITU-T Blue Book applications, 214
application context, 251
as stack API, 44
automatic IPC channel, 209
compiling and linking, 197
connections, 220, 264, 435
decoding received components, 260
dialogue handling primitives, 244, 248
dialogue management, 265
disconnecting from SCCP, 264
guidelines, 196
how to use, 215
hybrid stacks, 197, 205
IPC buffer commands, 271
IPC buffer values, 270, 272
ITU-T White Book, 214
loadsharing, 209
managing IPC channels, 209
managing memory, 269
masks, 224
memory allocation, 236, 261, 265
memory handling, 261
modifying the wait-for-reject timer value,
265
non-disruptive service update, 206
primitives, 233
receive IPC buffer, 270
receiving TCAP messages, 263
rescheduling, 264
return values, 272
send IPC buffer, 270
sending TCAP primitives, 243
sending user data, 262, 263
stack switchover, 207
switchover, 208
929
tc_errno values, 272
TC-user, 243, 254, 257
terminating a service, 264, 442
timer mechanisms, 272
timer mechansims, 272
transaction handling primitives, 244
transaction management, 268
TR-user, 261
tuning TCAP IPC buffers, 269
TCAP API functions
TCX_alloc_buffer, 236
TCX_alloc_component, 236
TCX_close(), 264, 442
TCX_control(), 270
TCX_get_component(), 260
TCX_open(), 220, 224, 225, 236, 237, 240,
241, 242, 254, 257, 260, 262, 263, 264, 435
TCX_put_component(), 240
TCX_recv(), 257, 442
TCX_select_mask(), 224, 436
TCX_send(), 254, 442
TLX_recv(), 263
TLX_send(), 262
API, 47
disabling, 280
enabling, 280
functions, 286
guidelines, 299
header file, 285
INAP service key, 290
load balancing, 288
loadsharing, 210
partitioning, 287
shared library, 285
TCX_open function, 299
tracing, 297
uneven distribution, 290
TCAP component sublayer
bypassing, 268
enabled, 254
extracting components, 260
operation, 201
passing components, 236
providing dialogue handling functions, 202,
227
reply, 201
930
service of, 198
transaction, 202
user, 201
using, 226
TCAP components
and their order in message, 236
ASN.1 compiler, 207
component buffer, 265
component handling, 261
component handling primitives, 233
contents, 201
creating, 236
encoding and decoding, 260
exchanging, 202
invoke Id, 265
management, 265
non-standard, 47, 207
structure of, 232, 234
types of, 233
TCAP connections
and their IPC buffers, 270
assigned an SSN, 210
assigned an SSN value, 211
closing, 264
creating, 220
in an array, 225
loadsharing, 210, 211
scheduling, 224
service access point, 220, 435
TC-user, 220, 435
TR-user, 220, 261, 435
TCAP dialogues
and exchanging components, 202
between TC-users, 202, 227
concurrent, 202
concurrent dialogues, 267
destination address, 243
dialogue handling primitives, 206, 243
dialogue ID, 227
dialogue Id, 267
dialogue portion, 202, 206
management, 266
originating address, 243
p-abort cause, 253
point code status, 253
pointer to dialog portion, 244
primitive type, 243
provider dialogue id, 243
realtionship with transactions, 244
report types, 253
service quality, 243
structure of dialogue portion, 248
structure of dialogue primitives, 243
structure of primitives, 248
structured, 227
termination type, 253
u-abort cause, 253
unstructured, 227
user dialogue id, 243
u-status, 253
withdrawal information, 253
TCAP function parameter
cnxId, 270
command, 270
context, 270
max_fd, 224
parameters, 271
TCAP management
API memory, 268
component, 264
dialogue, 265
IPC buffers, 270
switchover, 209
timer mechanisms, 272
transaction, 268
TCAP OA&M API
creating connection, 435
TCAP OA&M API functions
TCX_close(), 442
TCX_control(), 438
TCX_recv(), 440
TCAP transaction sublayer
and ASN.1 compiler, 207
component handling, 261
direct access, 201, 207, 268
end-to-end connection, 202
exchange of user data, 261
exchange of user dataTR-user, 202
indirect access, 201
management, 268
memory allocation, 261
service of, 198
timers, 274
transaction handling, 261
transaction portion, 202
user, 201, 202
using, 261
TCAProuter_application_activate() function,
286
function, 286
TCAProuter_incoming_message() function,
286
TCAProuter_init() function, 286
TCAProuter_shutdown() function, 286
TCAProuter_trace() function, 297
TC-BEGIN message, 280, 283
TC-CONTINUE message, 280, 283
TC-CONVERSATION-xxx message, 280
TCCR expiry
TC-END message, 283
TCP/IP flow control, 208
TC-QUERY-xxx message, 280
TC-UNI message, 280, 283
TCX_cnx_handler, 208
TCX_recv, 208
TCX_select_mask, 208
teardown (TUP)
procedures, 816
terminating calls
primitives, 579
testing
application, 42
looback, 43
performance, 58
procedures, 58
subsystem status test procedure, 185
system, 61
timer activity
ISUP, 600
TUP, 816
TimerLib
definition, 309
timers
ISUP, 742
tolerant
FTC, 308
TONE_DISAPPEARS_ACK
931
tracing, 532
Traffic Discriminator
TDi, 444
transfer indications
MTP, 577
transitions
state, 575, 578
TTC flavor, 666
TUP
accessors, 785
applications, 47, 761
China flavor, 759
circuit states, 816
decode function, 784
differences between flavors, 759
encode function, 785
FSMs, 810
IsupInfoMgr class, 787
IsupMsg class, 787
ITU-T flavor, 759
makefile, 900
message flow, 816
message module classes, 787
primitives (BP mode), 779
primitives requiring additional
information, 780
timer activity, 816
TupUserMsg class, 789
TupXXX class, 788
tutorials, 899
user message, 786
TUP API
as stack API, 44
TUP_USR_MSG_IND
TUP_USR_MSG_REQ
TupUserMsg
class (TUP), 789
TupXXX
class (TUP), 788
932
TU-T TUP
primitives (SM mode), 774
tutorials
ISUP, 497
MTP3/M3UA, 112
Plug-In, 343
SCCP, 192
TCAP, 275
TCAP AMD, 306
TUP, 899
VPC, 53
U
UBM message (TUP)
received, 822
sent, 823
UCIC messages, 591
unblocking
primitives, 579
UNBLOCKING_CONF
UNBLOCKING_IND
UNBLOCKING_REQ
UNBLOCKING_RESP
uneven distribution, 290
unknown messages
handling, 597
primitives, 597
UNKNOWN_MESSAGE_IND
UNKNOWN_MESSAGE_REQ
UNKNOWN_MSG_IND
UNKNOWN_MSG_REQ
UNKNOWN_OPC_MSG_IND
unsolicited information exchange, 623
failure, 623
unsuccessful
backward setup message (TUP), 822
call setup (ISUP), 602
call setup (TUP), 816, 822, 823
updating
circuit states, 567
user defined messages, 592
User In Service (UIS), 119
user message
TUP, 786
User Out of Service (UOS), 119, 180, 184
user-supplied algorithm, 281
V
validation, 58, 61
values
SETUP_FAILURE_IND, 746
Virtual Point Code
definition, 52
Virtual User
definition, 53
VPC
definition, 52
OAM API, 53
SCCP API, 53
tutorials, 53
VU
definition, 53
W
work
measurement, 476
WRONG_PROBE_TYPE, 492
WRONG_STATE
return status, 553
933

HP OpenCall SS7 Application Developer`s Guide

Transcription

Similar documents

JPW - Made in the USA - Jack`s Plastic Welding

hands free, eyes free

Whitepages Pro Caller Identification API

APIs as a Foundation for Systems of Engagement

OMNITRAC LASER TRACKING SYSTEM

APAIT Health Center, by Noel Alumit

Xfinity Live! 90`s Fest, Saturday, July 19, 2014 | Events | 95.7 BEN

API and Mashup Tooklit - GeoJet Information Solutions

Active Electronically Scanned Array (AESA)

mastering the stone age