d7 160 Api

1-1600-1003-01
Distributed7 API Reference Manual
NewNet Distributed7
API Reference Manual
Part No. 1-1600-1003-01
Release 1.6.0
February 12, 2009
35 Nutmeg Drive
Trumbull, CT 06611
Technical Assistance: (877) 698-5583
(203) 647-0580
fax: (203) 647-0580
email: support@newnet.com
Restrictions: This document contains proprietary information that is protected by copyright; it is intended for your internal use only,
it is not to be disclosed to third parties. All rights reserved. No part of this document may be photocopied or reproduced in any way
without the prior written permission of NewNet Communication Technologies, LLC. The information contained in this document is
subject to change without notice. NewNet makes no warranty of any kind with regard to this material. NewNet shall not be liable for
errors contained herein or for incidental or consequential damages in connection with the use of this material.
Copyright NewNet Communication Technologies
Page i
1-1600-1003-01
TRADEMARKS
NewNet and AccessMANAGER are registered trademarks of NewNet Communication Technologies, LLC
NewNet AccessMANAGER, NewNet Connect7, NewNet Disributed7, NewNet Easy7, NewNet SG, NewNet SGC,
OTAserver, SMserver are trademarks of NewNet Communication Technologies, LLC.
Sun, Sun-3, Sun-4, Sun386i, SunInstall, SunOS, and SPARC Sun Microsystems, and Sun Workstations are
trademarks of Sun Microsystems, Inc.
SPARC is a registered trademark of SPARC International, Inc. SPARC CPU-2CE is a trademark of SPARC International, Inc.
licensed to FORCE COMPUTERS, Inc.
Solaris is a registered trademark of Sun Microsystems, Inc.
Motorola and the Motorola logo are registered trademarks of Motorola, Inc. in the U.S.A. and other countries.
FX Series is a trademark of Motorola Computer Group.
AIX, PowerPC, RS/6000, and ARTIC960 are registered trademarks of IBM, Inc.
UNIX is a registered trademark of UNIX Systems Laboratories, Inc. in the U.S.A. and other countries.
VERITAS, VERITAS Cluster Server, VCS, and the VERITAS logo are registered trademarks of VERITAS Software
Corporation in the United States and other countries.
All the brand names and other products or services mentioned in this document are identified by the trademarks or service marks of
their respective companies or organizations.
SUCCESSOR IN INTEREST
NewNet Communication Technologies, LLC is the successor in interest to EBS, Inc.; NewNet, Inc.; ADC Enhanced Services Division;
ADC ESD, Inc. Any rights or title to the marks or copyrights of these entities, unless otherwise disclosed, are the property of NewNet
Communication Technologies, LLC.
NOTICES AND WARRANTY INFORMATION

The information in this document is subject to change without notice and should not be construed as commitment by NewNet
Communication Technologies, LLC. NewNet assumes no responsibility or makes no warranties for any errors that may appear in this
document and disclaims any implied warranty of merchantability or fitness for a particular purpose.
COPYRIGHT INFORMATION
Distributed7
The software and design described in this document is furnished under a license agreement. No part of this document may be used or
copied in any form or any means without any accordance with the terms of such license or prior written consent of NewNet
Communication Technologies, LLC.
CMU SNMP
Copyright 1988, 1989, 1991, 1992 by Carnegie Mellon UniversityAll Rights Reserved
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of CMU not be used in advertising or publicity pertaining to distribution of the software
without specific, written prior permission.
CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
SNMP SMIC
Copyright 1992 SynOptics Communications, Inc. All Rights Reserved.
SynOptics grants a non-exclusive license to use, copy, modify, and distribute this software for any purpose and without fee, provided
that this copyright notice and license appear on all copies and supporting documentation. SynOptics makes no representations about the
suitability of this software for any particular purpose. The software is supplied "AS IS", and SynOptics makes no warranty, either
Page ii
1-1600-1003-01
express or implied, as to the use, operation, condition, or performance of the software. SynOptics retains all title and ownership in the
software.
TCL/TK
This software is copyrighted by the Regents of the University of California; Sun Microsystems, Inc.; and other parties. The following
terms apply to all files associated with the software unless explicitly disclaimed in individual files.
The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose,
provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No
written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted
by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first
page of each file where they apply.
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS
DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS
HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only
"Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause
52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as
"Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (c) (1)
of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and
distribute the software in accordance with the terms specified in this license.
PERFORMANCE SPECIFICATIONS
NewNet Communication Technologies, LLC reserves all the rights to change the equipment performance specifications stated herein
at any time without notice. For OEM components, NewNet Communication Technologies, LLC relies on the specifications supplied by
the OEM vendors.
ALL RIGHTS RESERVED
Copyright 2007 - 2009

NewNet Communication Technologies, LLC
35 Nutmeg Drive
Trumbull, CT 06611
U.S.A.
Page iii
1-1600-1003-01
Page iv
1-1600-1003-01
Table of Contents
Introduction 1-1
1.1
General ............................................................................................................................. 1-1
1.2
1.2.1
1.2.2
Scope ................................................................................................................................. 1-1

Revisions and Updates ..................................................................................................... 1-2
Related Documents .......................................................................................................... 1-3
1.3
How to Use this Manual .................................................................................................. 1-3
1.3.3
Notations and Conventions .............................................................................................. 1-3
SPM API Library 2-1
2.1
Chapter Overview ............................................................................................................ 2-1
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8
2.2.9
2.2.10
2.2.11
2.2.12
2.2.13
2.2.14
2.2.15
2.2.16
2.2.17
2.2.18
2.2.19
2.2.20
2.2.21
2.2.22
2.2.23
2.2.24
2.2.25
2.2.26
2.2.27
2.2.28
2.2.29
2.2.30
2.2.31
2.2.32
SPM API Library ............................................................................................................ 2-1

spm_alarm() ..................................................................................................................... 2-2
spm_bind() ....................................................................................................................... 2-3
spm_broadcast() ............................................................................................................... 2-6
spm_close() ...................................................................................................................... 2-8
spm_detect()..................................................................................................................... 2-9
spm_display()................................................................................................................. 2-15
spm_errgroup()............................................................................................................... 2-15
spm_open()..................................................................................................................... 2-16
spm_forward()................................................................................................................ 2-16
spm_getalarm() .............................................................................................................. 2-18
spm_getdir() ................................................................................................................... 2-19
spm_gethiwat()............................................................................................................... 2-19
spm_getlowat()............................................................................................................... 2-20
spm_getoprmode() ......................................................................................................... 2-21
spm_getqinfo() ............................................................................................................... 2-23
spm_getqparams() .......................................................................................................... 2-24
spm_getqstat() ................................................................................................................ 2-25
spm_getregtime() ........................................................................................................... 2-26
spm_getsrvtype()............................................................................................................ 2-27
spm_getusrinfo() ............................................................................................................ 2-28
spm_getusrstat() ............................................................................................................. 2-30
spm_log() ....................................................................................................................... 2-31
spm_loop() ..................................................................................................................... 2-33
spm_notify()................................................................................................................... 2-34
spm_open()..................................................................................................................... 2-43
spm_palarm() ................................................................................................................. 2-45
spm_perror()................................................................................................................... 2-47
spm_rcv() ....................................................................................................................... 2-47
spm_sethiwat() ............................................................................................................... 2-50
spm_setlowat() ............................................................................................................... 2-51
spm_setoprmode().......................................................................................................... 2-52
spm_setqparams() .......................................................................................................... 2-53
Page v
1-1600-1003-01
Table of Contents
2.2.33
2.2.34
2.2.35
2.2.36
2.2.37
2.2.38
2.2.39
2.2.40
2.2.41
2.2.42
2.2.43
2.2.44
2.2.45
2.2.46
spm_setsrvtype() ............................................................................................................
spm_setusrinfo().............................................................................................................
spm_snd() .......................................................................................................................
spm_strerror().................................................................................................................
spm_trestart()..................................................................................................................
spm_tretrieve() ...............................................................................................................
spm_trigger() ..................................................................................................................
spm_tstart().....................................................................................................................
spm_tstop().....................................................................................................................
spm_unbind()..................................................................................................................
spm_xlate_ipckey() ........................................................................................................
spm_xlate_ipcaddr().......................................................................................................
spm_xlate_ipcmsg() .......................................................................................................
spm_xlate_reginfo() .......................................................................................................
2-54
2-55
2-56
2-58
2-59
2-60
2-61
2-63
2-64
2-65
2-66
2-67
2-67
2-68
2.3
Network Extensions to SPM API Library ................................................................... 2-70
2.3.1
spm_inet_addr().............................................................................................................. 2-70
2.3.2
spm_inet_ntoa().............................................................................................................. 2-70
2.3.3
spm_inet_ntoa_r() .......................................................................................................... 2-71
2.3.4
spm_inet_host() .............................................................................................................. 2-72
2.3.5
spm_inet_host_r()........................................................................................................... 2-72
2.3.6
spm_inet_host_mask().................................................................................................... 2-73
2.3.7
spm_inet_ntwk_mask() .................................................................................................. 2-73
2.3.8
spm_inet_host_id()......................................................................................................... 2-74
2.3.9
spm_inet_ntwk_id()........................................................................................................ 2-74
APM API Library 3-1
3.1
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
3.2.7
3.2.8
3.2.9
3.2.10
3.2.11
3.2.12
3.2.13
3.2.14
3.2.15
3.2.16
APM API Library ............................................................................................................ 3-2

apm_catcherr().................................................................................................................. 3-2
apm_catcherr_fatal() ........................................................................................................ 3-2
apm_catcherr_user()......................................................................................................... 3-3
apm_clearerr() .................................................................................................................. 3-3
apm_getstate() .................................................................................................................. 3-4
apm_getstate_r()............................................................................................................... 3-4
apm_init() ......................................................................................................................... 3-5
apm_init_default() ............................................................................................................ 3-7
apm_init_asvc() ................................................................................................................ 3-8
apm_init_crp() .................................................................................................................. 3-9
apm_kill() ....................................................................................................................... 3-10
apm_logerr()................................................................................................................... 3-11
apm_newerrid() .............................................................................................................. 3-12
apm_printerr() ................................................................................................................ 3-13
apm_printerr_r() ............................................................................................................. 3-14
apm_puterr()................................................................................................................... 3-14
Page vi
1-1600-1003-01
Table of Contents
3.2.17
apm_sendack() ...............................................................................................................
3.2.18
apm_setlogopts() ............................................................................................................
3.2.19
apm_setsigchld() ............................................................................................................
3.2.20
apm_setstate() ................................................................................................................
3.2.21
apm_spawn() ..................................................................................................................
3.2.22
apm_trace() ....................................................................................................................
3.2.23
apm_waitack()................................................................................................................
OAM API Library 4-1
3-16
3-17
3-17
3-18
3-19
3-20
3-21
4.1
4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.2.5
4.2.6
4.2.7
4.2.8
4.2.9
4.2.10
4.2.11
4.2.12
4.2.13
4.2.14
4.2.15
4.2.16
4.2.17
4.2.18
4.2.19
4.2.20
4.2.21
4.2.22
4.2.23
4.2.24
4.2.25
4.2.26
4.2.27
4.2.28
4.2.29
4.2.30
4.2.31
4.2.32
4.2.33
4.2.34
OAM API Library ........................................................................................................... 4-1

oam_alarm() ..................................................................................................................... 4-3
oam_alias()....................................................................................................................... 4-3
oam_almevent()................................................................................................................ 4-5
oam_almgrp()................................................................................................................... 4-6
oam_connection()............................................................................................................. 4-7
oam_cpc()......................................................................................................................... 4-8
oam_gt() ........................................................................................................................... 4-9
oam_gtentry()................................................................................................................. 4-10
oam_host()...................................................................................................................... 4-11
oam_isup()...................................................................................................................... 4-12
oam_isupcct()................................................................................................................. 4-14
oam_isupcgrp() .............................................................................................................. 4-15
oam_isupnode().............................................................................................................. 4-17
oam_isuptmr() ................................................................................................................ 4-19
oam_l2cs()...................................................................................................................... 4-20
oam_l2flow().................................................................................................................. 4-22
oam_l2timer()................................................................................................................. 4-24
oam_l3timer()................................................................................................................. 4-25
oam_line() ...................................................................................................................... 4-26
oam_link() ...................................................................................................................... 4-27
oam_linkstat() ................................................................................................................ 4-29
oam_localsubsys().......................................................................................................... 4-31
oam_lset()....................................................................................................................... 4-32
oam_lsetstat() ................................................................................................................. 4-34
oam_mate() .................................................................................................................... 4-35
oam_mtp() ...................................................................................................................... 4-36
oam_ntwk() .................................................................................................................... 4-38
oam_port()...................................................................................................................... 4-39
oam_retrieve() ................................................................................................................ 4-40
oam_retrieve_rec() ......................................................................................................... 4-41
oam_route() .................................................................................................................... 4-43
oam_rtset() ..................................................................................................................... 4-45
oam_sccp() ..................................................................................................................... 4-47
oam_sltimer() ................................................................................................................. 4-48
Page vii
1-1600-1003-01
Table of Contents
4.2.35
oam_snsp() .....................................................................................................................
4.2.36
oam_sp().........................................................................................................................
4.2.37
oam_ss7board() ..............................................................................................................
4.2.38
oam_strdalm() ................................................................................................................
4.2.39
oam_subsys()..................................................................................................................
4.2.40
oam_tcpcon()..................................................................................................................
DSM API Library 5-1
5.1
4-49
4-50
4-52
4-53
4-54
4-55
5.2
DSM API Library ............................................................................................................ 5-1
5.2.1
dsm_attach() ..................................................................................................................... 5-2
5.2.2
dsm_destroy()................................................................................................................... 5-4
5.2.3
dsm_detach() .................................................................................................................... 5-5
5.2.4
dsm_get().......................................................................................................................... 5-6
5.2.5
dsm_getopts() ................................................................................................................... 5-8
5.2.6
dsm_getstat() .................................................................................................................. 5-10
5.2.7
dsm_rdlock() .................................................................................................................. 5-12
5.2.8
dsm_rdlock_rec()............................................................................................................ 5-14
5.2.9
dsm_rdrule() ................................................................................................................... 5-16
5.2.10
dsm_rdrule_rec() ............................................................................................................ 5-17
5.2.11
dsm_wrrule() .................................................................................................................. 5-19
5.2.12
dsm_wrrule_rec() ........................................................................................................... 5-20
5.2.13
dsm_setopts().................................................................................................................. 5-22
5.2.14
dsm_setstat()................................................................................................................... 5-23
5.2.15
dsm_unlock().................................................................................................................. 5-25
5.2.16
dsm_unrule ..................................................................................................................... 5-26
5.2.17
dsm_wrlock().................................................................................................................. 5-27
5.2.18
dsm_wrlock_rec()........................................................................................................... 5-30
Alarm API Library 6-1
6.1
6.2
Alarm API Library .......................................................................................................... 6-1
6.2.1
alm_notify()...................................................................................................................... 6-2
6.2.2
alm_report()...................................................................................................................... 6-4
6.2.3
alm_trap() ......................................................................................................................... 6-6
MTP API Library 7-1
7.1
7.2
7.2.1
Using the MTP API Library ........................................................................................... 7-1

Routing Type Definition .................................................................................................. 7-2
7.3
7.3.1
7.3.2
7.3.3
MTP API Library ............................................................................................................ 7-2

mtp_decode_pc() .............................................................................................................. 7-4
mtp_dest_stat() ................................................................................................................. 7-5
mtp_encode_pc() ............................................................................................................. 7-6
Page viii
1-1600-1003-01
Table of Contents
7.3.4
mtp_flow_ind() ............................................................................................................... 7-7
7.3.5
mtp_info() ........................................................................................................................ 7-9
7.3.6
mtp_info_ind() .............................................................................................................. 7-10
7.3.7
mtp_init_api() ................................................................................................................ 7-11
7.3.8
mtp_intercept_req ()....................................................................................................... 7-12
7.3.9
mtp_intercept_ind ()....................................................................................................... 7-13
7.3.10
mtp_ni() ......................................................................................................................... 7-14
7.3.11
mtp_pc_bytes() .............................................................................................................. 7-15
7.3.12
mtp_pc_size() ................................................................................................................ 7-16
7.3.13
mtp_pc2cluster() ............................................................................................................ 7-17
7.3.14
mtp_pc2member() .......................................................................................................... 7-18
7.3.15
mtp_pc2network() .......................................................................................................... 7-19
7.3.16
mtp_protocol() ............................................................................................................... 7-20
7.3.17
mtp_spc() ....................................................................................................................... 7-21
7.3.18
mtp_subpc2pc().............................................................................................................. 7-22
7.3.19
mtp_up_offset() ............................................................................................................. 7-23
7.3.20
mtp_variant() ................................................................................................................. 7-24
7.3.21
mtp_xfer_ind() .............................................................................................................. 7-25
7.3.22
mtp_xfer_req() .............................................................................................................. 7-26
7.3.23
mtp_xfer2_req () ............................................................................................................ 7-27
Gateway API Library 8-1
8.1
8.2
Gateway API Library ...................................................................................................... 8-1
8.2.1
gw_isup_get_cic() ............................................................................................................ 8-2
8.2.2
gw_mtp_flow_ind().......................................................................................................... 8-2
8.2.3
gw_mtp_upu_req()........................................................................................................... 8-3
8.2.4
gw_mtp_xfer_ind() .......................................................................................................... 8-4
8.2.5
gw_mtp_xfer_req() .......................................................................................................... 8-5
8.2.6
gw_mtp_rct_ind()............................................................................................................. 8-6
8.2.7
gw_mtp_rct_req()............................................................................................................. 8-6
8.2.8
gw_mtp_tfc_req()............................................................................................................. 8-7
8.2.9
gw_mtp_tfa_req()............................................................................................................. 8-8
8.2.10
gw_mtp_tfr_req() ............................................................................................................. 8-8
8.2.11
gw_mtp_tfp_req() ............................................................................................................ 8-9
8.2.12
gw_mtp_dest_stat() ........................................................................................................ 8-10
8.2.13
gw_register() .................................................................................................................. 8-10
8.2.14
gw_sccp_modify_CdPA().............................................................................................. 8-12
8.2.15
gw_sccp_modify_CgPA().............................................................................................. 8-13
8.2.16
gw_sccp_parse_UDT() .................................................................................................. 8-14
8.2.17
gw_sccp_parse_UDTS() ................................................................................................ 8-15
SCCP API Library 9-1
9.1
9.2
SCCP API Library .......................................................................................................... 9-1
Page ix
1-1600-1003-01
Table of Contents
9.2.1
sccp_addr2pc_p() ............................................................................................................. 9-2
9.2.2
sccp_addr2ssn_p() ............................................................................................................ 9-3
9.2.3
sccp_ConnectCnf()........................................................................................................... 9-4
9.2.4
sccp_ConnectInd()............................................................................................................ 9-6
9.2.5
sccp_ConnectReq() .......................................................................................................... 9-7
9.2.6
sccp_ConnectRsp()........................................................................................................... 9-8
9.2.7
sccp_CoordCnf() .............................................................................................................. 9-9
9.2.8
sccp_CoordInd()............................................................................................................... 9-9
9.2.9
sccp_CoordReq()............................................................................................................ 9-10
9.2.10
sccp_CoordRsp() ............................................................................................................ 9-11
9.2.11
sccp_DataInd() ............................................................................................................... 9-12
9.2.12
sccp_DataReq() .............................................................................................................. 9-13
9.2.13
sccp_DisconnectInd()..................................................................................................... 9-14
9.2.14
sccp_DisconnectReq().................................................................................................... 9-15
9.2.15
sccp_get_pc().................................................................................................................. 9-15
9.2.16
sccp_is_ansi() ................................................................................................................. 9-18
9.2.17
sccp_is_ccitt()................................................................................................................. 9-19
9.2.18
sccp_NoticeInd() ............................................................................................................ 9-19
9.2.19
sccp_PCstateInd()........................................................................................................... 9-20
9.2.20
sccp_put_pc() ................................................................................................................. 9-21
9.2.21
sccp_reg() ....................................................................................................................... 9-23
9.2.22
sccp_StateInd()............................................................................................................... 9-25
9.2.23
sccp_StateReq().............................................................................................................. 9-26
9.2.24
sccp_UnidataInd() .......................................................................................................... 9-27
9.2.25
sccp_UnidataReq() ......................................................................................................... 9-28
TCAP API Library 10-1
10.1
Chapter Overview .......................................................................................................... 10-1
10.2
10.2.1
10.2.2
10.2.3
10.2.4
10.2.5
10.2.6
10.2.7
10.2.8
10.2.9
10.2.10
10.2.11
10.2.12
10.2.13
10.2.14
10.2.15
10.2.16
TCAP API Library ........................................................................................................ 10-1

tcm_close() ..................................................................................................................... 10-2
tcm_getcomp()................................................................................................................ 10-3
tcm_getdlgid() ................................................................................................................ 10-4
tcm_getdlgp() ................................................................................................................. 10-5
tcm_getdpa()/tcm_setdpa()............................................................................................. 10-6
tcm_getldflag() ............................................................................................................... 10-7
tcm_getldsopt()............................................................................................................... 10-9
tcm_get_msg_priority().................................................................................................. 10-9
tcm_getopa()/tcm_setopa()........................................................................................... 10-10
tcm_getpolicy() ............................................................................................................ 10-11
tcm_get_priority() ........................................................................................................ 10-12
tcm_notify ()................................................................................................................. 10-13
tcm_open().................................................................................................................... 10-15
tcm_putcomp() ............................................................................................................. 10-20
tcm_putdlgp() ............................................................................................................... 10-21
tcm_rcv() ...................................................................................................................... 10-22
Page x
1-1600-1003-01
Table of Contents
10.2.17
10.2.18
10.2.19
10.2.20
10.2.21
10.2.22
10.2.23
10.2.24
10.3
10.3.1
10.3.2
10.3.3
10.3.4
10.3.5
10.3.6
10.3.7
10.3.8
10.3.9
10.3.10
10.3.11
10.3.12
tcm_rlsdlgid()...............................................................................................................
tcm_rmtopen()..............................................................................................................
tcm_rmtclose() .............................................................................................................
tcm_setldflag() .............................................................................................................
tcm_setldsopt().............................................................................................................
tcm_setpolicy().............................................................................................................
tcm_set_priority().........................................................................................................
tcm_snd()......................................................................................................................
10-24
10-25
10-29
10-30
10-32
10-33
10-33
10-34
TCAP Transaction Recovery Functions .................................................................... 10-37

tcm_getcomp_n() ......................................................................................................... 10-37
tcm_gettrid()................................................................................................................. 10-39
tcm_getdlgp_n() ........................................................................................................... 10-40
tcm_open_n() ............................................................................................................... 10-41
tcm_putcomp_n() ......................................................................................................... 10-46
tcm_putdlgp_n()........................................................................................................... 10-48
tcm_rcv_n() .................................................................................................................. 10-49
tcm_rlstrid().................................................................................................................. 10-51
tcm_snd_n().................................................................................................................. 10-52
tcm_set_priority_n()..................................................................................................... 10-54
tcm_get_priority_n() .................................................................................................... 10-55
tcm_get_msg_priority_n()............................................................................................ 10-56
10.4
JAIN TCAP API Library ............................................................................................ 10-57
10.4.1
SS7 Factory .................................................................................................................. 10-57
10.4.2
JAIN Stack Interface .................................................................................................... 10-58
10.4.3
JAIN Provider Interface ............................................................................................... 10-58
Raw TCAP API Library 11-1
11.1
11.2
Raw TCAP API Library ............................................................................................... 11-1
11.2.1
tcr_open() ....................................................................................................................... 11-2
11.2.2
tcr_getldflag() / tcr_setldflag() ....................................................................................... 11-6
11.2.3
tcr_getldsopt() / tcrsetldsopt() ........................................................................................ 11-8
11.2.4
tcr_close()..................................................................................................................... 11-10
Extended TCAP API Library 12-1
12.1
12.2
12.2.1
12.2.2
12.2.3
12.2.4
12.2.5
12.2.6
12.2.7
Extended TCAP API Library ....................................................................................... 12-1

tcx_put_acg_ind() / tcx_get_acg_ind() .......................................................................... 12-2
tcx_put_bear_cap() / tcx_get_bear_cap()....................................................................... 12-2
tcx_put_bill_ind() / tcx_get_bill_ind()........................................................................... 12-3
tcx_put_buss_grp() / tcx_get_buss_grp()....................................................................... 12-4
tcx_put_ccsan() / tcx_get_ccsan().................................................................................. 12-5
tcx_put_cf_status() / tcx_get_cf_status() ....................................................................... 12-5
tcx_put_com_id() / tcx_get_com_id()............................................................................ 12-6
Page xi
1-1600-1003-01
Table of Contents
12.2.8
tcx_put_digits() / tcx_get_digits() .................................................................................. 12-7
12.2.9
tcx_put_dn_to_ls() / tcx_get_dn_to_ls() ........................................................................ 12-7
12.2.10
tcx_put_duration() / tcx_get_duration() ......................................................................... 12-8
12.2.11
tcx_put_ic_ind() / tcx_get_ic_ind()................................................................................ 12-9
12.2.12
tcx_put_octet_par() / tcx_get_octet_par() .................................................................... 12-10
12.2.13
tcx_put_par() / tcx_get_par()........................................................................................ 12-10
12.2.14
tcx_put_par_str() .......................................................................................................... 12-11
12.2.15
tcx_put_pin() / tcx_get_pin()........................................................................................ 12-12
12.2.16
tcx_put_priv_digits() / tcx_get_priv_digits() ............................................................... 12-13
12.2.17
tcx_put_ref_id() / tcx_get_ref_id()............................................................................... 12-13
12.2.18
tcx_put_tr_id() / tcx_get_tr_id()................................................................................... 12-14
12.2.19
tcx_put_tstamp_par() / tcx_get_tstamp_par() .............................................................. 12-15
ISUP API Library 13-1
13.1
13.2
13.2.20
ISUP Call Control Library ........................................................................................... 13-1

...................................................................................................................................... 13-22
13.3
JAIN ISUP API Library .............................................................................................. 13-29
13.3.1
SS7 Factory .................................................................................................................. 13-30
13.3.2
JAIN Stack Interface .................................................................................................... 13-31
13.3.3
JAIN Provider Interface ............................................................................................... 13-31
ISUP Advice of Charge (AoC) API Library 14-1
14.1
14.2
ISUP AoC API Library ................................................................................................. 14-1
DKM API Library 15-1
15.1
15.2
DKM API Library ......................................................................................................... 15-1
15.2.1
dkm_cancel() .................................................................................................................. 15-2
15.2.2
dkm_destroy() ................................................................................................................ 15-3
15.2.3
dkm_extend().................................................................................................................. 15-5
15.2.4
dkm_get() ....................................................................................................................... 15-8
15.2.5
dkm_gethostaddr()........................................................................................................ 15-11
15.2.6
dkm_gethostid()............................................................................................................ 15-12
15.2.7
dkm_getlist() ................................................................................................................ 15-13
15.2.8
dkm_lock() ................................................................................................................... 15-14
15.2.9
dkm_notify()................................................................................................................. 15-17
15.2.10
dkm_query() ................................................................................................................. 15-19
15.2.11
dkm_schedule() ............................................................................................................ 15-20
15.2.12
dkm_shrink() ................................................................................................................ 15-23
15.2.13
dkm_sync()................................................................................................................... 15-25
15.2.14
dkm_unlock() ............................................................................................................... 15-26
DRA API Library 16-1
Page xii
1-1600-1003-01
Table of Contents
16.1
16.2
DRA API Library .......................................................................................................... 16-1
16.2.1
dra_construct() ............................................................................................................... 16-2
16.2.2
dra_del_locked() ............................................................................................................ 16-5
16.2.3
dra_del_record()............................................................................................................. 16-6
16.2.4
dra_destroy() .................................................................................................................. 16-7
16.2.5
dra_find_inseq() ............................................................................................................. 16-8
16.2.6
dra_find_record() ........................................................................................................... 16-9
16.2.7
dra_get_dkm_addr()..................................................................................................... 16-11
16.2.8
dra_get_dkm_id()......................................................................................................... 16-12
16.2.9
dra_get_num_recs()...................................................................................................... 16-12
16.2.10
dra_lock_seg_priv() ..................................................................................................... 16-13
16.2.11
dra_new_record() ......................................................................................................... 16-13
16.2.12
dra_relock_async()....................................................................................................... 16-15
16.2.13
dra_relock_sync()......................................................................................................... 16-16
16.2.14
dra_rls_lock() ............................................................................................................... 16-17
16.2.15
dra_rls_seg_priv() ........................................................................................................ 16-18
16.2.16
dra_validate() ............................................................................................................... 16-19
Passive Monitoring API Library 17-1
17.1
17.2
17.2.1
17.2.2
17.2.3
17.2.4
17.2.5
17.2.6
PM API Library ............................................................................................................. 17-1

pm_register() .................................................................................................................. 17-2
pm_deregister() .............................................................................................................. 17-4
pm_status()..................................................................................................................... 17-5
pm_listen() ..................................................................................................................... 17-5
pm_notify() .................................................................................................................... 17-6
pm_admin() .................................................................................................................... 17-9
Page xiii
1-1600-1003-01
Table of Contents
Page xiv
1-1600-1003-01
Revision History
The following table lists the revision history of this manual. The date column is the date a revised
manual was published. The Associated Software Release column is the software release number for
which the updated manual was published.
Date
Pages
Replaced
9/09/08
All
Updated the part number and version.
1.6.0
1/09/08
All
Updated the company name, logo, address, and contact information. Updated the
trademark and copyright information.
1.5.0
All
Updated the document version for the GA release.
1.5.0
7/20/07
Description of Changes
Assoc SW
Release
Chapter 10
General edits to 10.3.
6/15/2007
Chapter 10
Updated TCAP API Library, sections: 10.2.2, 10.2.4, 10.2.13, 10.2.14, 10.2.15, 10.2.16,
10.2.17, 10.2.22, 10.2.24, and all of 10.3.
1.5.0 beta
9/12/06
Chapter 8
Updated Section 8.2.13 gw_register() for the addition of Monitor mode (CRSnn16266).
1.4.0
7/26/05
Chapter 7
Section 7.3.13 mtp_pc2cluster(): under Synopsis "int" replaces "byte_t", and under Return
Values "int" replaces "byte_t" and "-1" replaces "0xff" (CR 15599).
1.4.0
Section 7.3.14 mtp_pc2member(): under Synopsis "int" replaces "byte_t", and under
Return Values "int" replaces "byte_t" and "-1" replaces "0xff" (CR 15599).
Section 7.3.15 mtp_pc2network(): under Synopsis "int" replaces "byte_t", and under
Return Values "int" replaces "byte_t" and "-1" replaces "0xff" (CR 15599).
4/30/05
All
Updated version and dates for D7 1.4 0.
1/31/05
All
Updated version and dates for D7 1.4 0 beta.
1/28/04
Chapter 13
Section 13.2.19 isup_get_var_no(): revised ITU and ANSI variant lists.
6/30/03
Chapter 10
Section 10.2.24: added line, "L_TC_C_CONTINUE_CONFIRM - Continue to Confirm a

New Dialogue (CCITT)", and for all with CCITT (three instances) replaced "conversation"
with "dialogue".
Chapter 17
Section 17.2.5 pm_notify(): changed data structure of MSU Transfer Indication: replaced
unsigned char filler with unsigned short length.
1.4.0
1.4.0 beta
1.3.1
1.3.1 beta
Page xv
1-1600-1003-01
Revision History
Date
Pages
Replaced
11/14/02
Chapter 2
Section 1.2 Scope Added bullet for new Chapter 17 Passive Monitoring API Library
Chapter 7
Section 7.3.8 mtp_intercept_req () Added new section
Assoc SW
Release
1.3.0
Section 7.3.9 mtp_intercept_ind () Added new section

Section 7.3.23 mtp_xfer2_req () Added new section
Chapter 10
Section 10.1 Chapter Overview Updated paragraph text

Section 10.2.6 tcm_getldflag() tcm_getldinfo function in the TCAP API library has
been replaced by tcm_getldflag function; edited flags in SYNOPSIS
Section 10.2.13 tcm_open() Updated synopsis; added EMAXDLG error code to
ERRORS list and edited EMAXUSR
Section 10.2.18 tcm_rmtopen() Updated synopsis; added EMAXDLG error code to
ERRORS list and edited EMAXUSR
Section 10.2.20 tcm_2etldflag() tcm_setldinfo function in the TCAP API library has
been replaced by tcm_setldflag function
Section 10.3 JAIN TCAP API Library Added new section
Chapter 11
Section 11.1.2 tcr_getldflag() / tcr_setldflag() tcr_getldinfo/tcr_setldinfo() functions in

the raw TCAP API library have been replaced by tcr_getldflag/tcr_setldflag() functions,
respectively; updated references to both throughout chapter
Section 11.2.1 tcr_open() Updated EMAXUSR error code
Chapter 13
Section 13.1 Chapter Overview Updated paragraph text

Section 13.2.26 isup_reg_req Deleted first note in section
Section 13.3 JAIN ISUP API Library Added new section
09/24/02
Chapter 17
Added new Chapter 17 Passive Monitoring API Library
Chapter 8
Section 8.2.3 gw_mtp_upu_req() Added cause parameter to synopsis and return values
1.2.1
Added new sections and functions: 8.2.6 gw_mtp_rct_ind(); 8.2.7 gw_mtp_rct_req();

8.2.8 gw_mtp_tfc_req(); 8.2.9 gw_mtp_tfa_req(); 8.2.10 gw_mtp_tfr_req(); 8.2.11
gw_mtp_tfp_req(); 8.2.12 gw_mtp_dest_stat()
Page xvi
1-1600-1003-01
Revision History
Date
Pages
Replaced
04/19/02
Chapter 1
Section 1.2 Scope Added bullet for new Chapter 14 ISUP Advice of Charge (AoC) API
Library; updated headings of linked API Library chapters for consistency
Chapter 2
Section 2.2.1 spm_alarm () Updated synopsis with new alarm information and SEE
ALSO reference
Assoc SW
Release
1.2.0
Section 2.2.10 spm_getalarm () Updated synopsis with new alarm information

Section 2.2.26 spm_palarm () Updated synopsis with new alarm information
Section 2.2.37 spm_trestart () Modified ENOTID error message text
Section 2.2.38 spm_tretrieve () Deleted EMSGSIZE, ESRCH, EDESTBLKD,
ENOTID, ENOMEM and EAGAIN error messages
Section 2.2.40 spm_tstart () Modified description (deleted last sentence) and modified
ENOTID error message text
Section 2.2.41 spm_tstop () Deleted EMSGSIZE, ESRCH, EDESTBLKD, ENOTID,
ENOMEM and EAGAIN error messages
Chapter 3
Section 3.1 Chapter Overview Added note about APM API multi-threaded applications
and updated MT Level information for all APM API functions in 3.2 sub-sections
Section 3.2.4 apm_clearerr() Updated function description
Section 3.2.5 apm_getstate() Added new section
Section 3.2.6 apm_getstate_r() Added new section
Section 3.2.7 apm_init() Updated synopsis with new alarm information
Section 3.2.8 apm_init_default() Updated synopsis with new alarm information
Section 3.2.12 apm_logerr() Updated description and synopsis with new alarm
information, and updated SEE ALSO reference
Section 3.2.13 apm_newerrid() Updated description, synopsis and return values with
new alarm information
Section 3.2.15 apm_printerr_r() Added new section
Section 3.2.18 apm_setlogopts() Updated description and synopsis with new alarm
information
Section 3.2.20 apm_setstate_r() Added new section
Section 3.2.22 apm_trace() Updated synopsis with new trace message information, and
updated SEE ALSO reference
Section 3.2.23 apm_waitack() Updated SEE ALSO reference
Page xvii
1-1600-1003-01
Revision History
Date
Pages
Replaced
04/19/02
Chapter 5
Section 5.2 OA&M API Library Added note about OA&M API multi-threaded
applications and updated MT Level information for all OA&M API functions in 5.2 subsections; updated all header files names listed in description notes in 5.2 sub-sections as
follows: <spm_oam.h> is now <oam_spm.h>; <alarm_oam.h> is now <oam_alarm.h>;
<netd_oam.h> is now <oam_netd.h>; <mtp_oam.h> is now <oam_mtp.h>;
<sccp_oam.h> is now <oam_sccp.h>; <isup_oam.h> is now <oam_isup.h>
Assoc SW
Release
1.2.0
Section 5.2.29 oam_retrieve() Updated MT Level to MT-Unsafe

Section 5.2.30 oam_retrieve_rec() Updated MT Level to MT-Unsafe
Chapter 6
Section 6.2.1 alm_notify() Updated synopsis (replacing type with num parameter
throughout) and replacing type parameter text with num
Section 6.2.2 alm_report() Updated synopsis with new parameters and alarm values
Section 6.2.3 alm_trap() Updated description with new alarm severity value
L_ALMLVL_CRITICAL
Chapter 7
Section 7.3.14 mtp_protocol() Modified return values

Section 7.3.18 mtp_variant() Added bullets for BELL, ETSI97; updated OPT_ATT
Chapter 9
Section 9.2.17 sccp_is_ccitt() Modified return values
Chapter 10
Section 10.2.22 tcm_setpolicy() Modified default recovery policy from

L_TC_POLICY_ABORT.to L_TC_POLICY_PURGE
Chapter 13
Section 13.2 ISUP Call Control Library Modified note about multi-threaded
applications to refer to ISUP API instead of SCCP API; updated reference section for
consistency
Section 13.2.19 Updated isup_get_var_no() with Czech variant info
Chapter 14
Added new Chapter 14 ISUP Advice of Charge (AoC) API Library
10/29/01
Chapter 9
Section 9.2.6 gw_register() Added int cap_access parameter
09/27/01
Chapter 1
Section 1.2.2 Related Documents Added citations for ANSI 96 and ITU 97 support
1.1.0 B
09/27/01
Chapter 2
Entire chapter Indicated which calls are multi-thread safe, as appropriate; added
spm_inet_ntoa_r() and spm_inet_host__r() calls
1.1.0 B
09/27/01
Chapter 4
Entire chapter Indicated which calls are multi-thread safe, as appropriate
1.1.0 B
09/27/01
Chapter 7
1.1.0 B
09/27/01
Chapter 8
1.1.0 B
09/27/01
Chapter 9
1.1.0 B
09/27/01
Chapter 10
Sections 10.2.12, 10.2.14, and 10.2.25 Added optional parameter importance to

sccp_DataReq(), sccp_Disconnect(), and sccp_UnidataReq() calls
1.1.0 B
1.1.0
Section 10.2.19 Added the field ril to the sccp_PCstateInd() call

09/27/01
Chapter 11
Entire chapter Updated to reflect ITU White Book, ITU 97, ETST 97, and ANSI 96
support; indicated which calls are multi-thread safe, as appropriate
1.1.0 B
Sections 11.2.13 and 11.2.18 Updated the structure of tcmopt_t in the Synopsis of the
tcm_open() and tcm_rmtopen() calls
09/27/01
Chapter 12
1.1.0B
09/27/01
Chapter 13
1.1.0 B
04/16/01
Chapter 5
Section 5.2.2 oam_alias() Added section.
1.0.5 B
04/16/01
Chapter 9
Section 9.2.1 gw_isup_get_cic() Added section.
1.0.5 B
Section 9.2.2 gw_mtp_flow_ind() Added section.

Section 9.2.3 gw_mtp_upu_req() Added section.
Page xviii
1-1600-1003-01
Revision History
Date
Pages
Replaced
04/16/01
Chapter 11
01/15/01
Chapter 14
Section 11.2.13 tcm_open() Modified "opts" parameter
Assoc SW
Release
1.0.5 B
Section 11.2.18 tcm_rmtopen() Modified "opts" parameter

Sections 14.2.3 - 14.2.6, 14.2.15, and 14.2.16 added alert messages, and reformatted
related API subheadings throughout chapter
1.0.4
Section 14.2 ISUP Call Control Library corrected text for <isup_api.h>, removed
paragraph on ISUP and SPM library paths, and added answer.c and call.c to the list of
sample source code files.
09/27/00
Chapter 4
DSM Library Sections 4.2.9 - 4.2.12 and 4.2.16 are newly added MMLs; Sections 4.2.7,
4.2.8, 4.2.17. and 4.2.18 updated
09/27/00
Chapter 12
Entire chapter "Raw TCAP Library" added
08/18/00
Chapter 11
Section 11.2.5 tcm_getdpa/tcm_setdpa
1.0.1 B
08/04/00
Chapter 1
Section 1.2.: Scope, "ISUP API Library Reference" bullet item added
1.0.1.B
08/04/00
Chapter 14
Entire chapter "ISUP API Library Reference" added
1.0.1.B
06/19/00
Full Manual
General Availability release
03/17/00
Full Manual
Beta release
1.0.2
1.0.2
1.0.0
1.0.0 B
Page xix
1-1600-1003-01
Revision History
Page xx
1-1600-1003-01
Chapter 1:
1.1
Scope
Introduction
General
Distributed7 software is used for control and configuration of Signaling System 7 (SS7)
network nodes and devices. The Distributed7 software and supporting hardware
components are designed, assembled and shipped by NewNet Communication
Technologies, LLC, Inc.
Distributed7 features a UNIX STREAMS-based Application Programming Interface (API)
that gives customers the flexibility to develop SS7 User Parts or Applications using TCAP/
SCCP or message transfer part (MTP) services. Distributed7 also provides efficient,
connectionless STREAMS-based inter-process communication (IPC) capabilities among
multiple processes comprising your application.
1.2
Scope
This API reference manual forms part of a complete documentation package that describes
the NewNet Communication Technologies, LLC Distributed7 software. This manual is
organized so that all the information the user needs to know is presented in a logical
sequence, consisting of eleven chapters covering the following topics:
Chapter 1: Introduction - provides an introduction to the manual and NewNet
Communication Technologies, LLC documentation.
Chapter 2: SPM API Library - provides the Service Provider Module (SPM)
Application Programming Interface (API) library calls for NewNet Communication
Technologies, LLC Distributed7 software products.
Chapter 3: APM API Library - provides reference information for the APM API
function calls.
Chapter 5: DSM API Library - provides the Distributed Shared Memory (DSM)
Chapter 4: OAM API Library - describes the Operations, Administration &
Maintenance (OA&M) library, which supports the Operations Maintenance and
Administration Part (OMAP)a user part of Distributed7 SS7.
Chapter 6: Alarm API Library - provides the alarm (ALM) Application Programming
Interface (API) library calls for NewNet Communication Technologies, LLC
Distributed7 software products.
Page 1 - 1
1-1600-1003-01
Scope
Chapter 7: MTP API Library - provides the alphabetical listings of the Message
Transfer Part (MTP) Application Programming Interface (API) library calls for
NewNet Communication Technologies, LLC, Inc. Distributed7 software products.
Chapter 8: Gateway API Library - provides the gateway (GW) Application
Programming Interface (API) library calls for NewNet Communication Technologies,
LLC Distributed7 software products.
Chapter 9: SCCP API Library - provides the alphabetical listings of the Signaling
Connection Control Point (SCCP) Application Programming Interface (API) library
calls for NewNet Communication Technologies, LLC, Inc. Distributed7 software
products.
Chapter 10: TCAP API Library - describes and defines the individual TCAP API
function calls for NewNet Communication Technologies, LLC, Inc. Distributed7
software products.
Chapter 12: Extended TCAP API Library. This chapter provides a listing of the TCAP
extended library Application Program Interface (API).
Chapter 13: ISUP API Library - describes and defines the individual ISUP API
function calls for NewNet Communication Technologies, LLC, Inc. Distributed7
software products.
Chapter 14: ISUP Advice of Charge (AoC) API Library - describes the ChargingApplication Service Element (ASE) and Application Transport MechanismApplication Service Element (ASE) Application Programming Interface (API) library
calls.
Chapter 15: DKM API Library - provides the Distributed Kernel Memory (DKM)
Chapter 16: DRA API Library - provides the Distributed Record Access (DRA)
Chapter 17: Passive Monitoring API Library - provides the Passive Monitoring (PM)
Application Programming Interface (API) library calls for Distributed7 software
products.
It is assumed that the hardware and software are installed, and the user is familiar with the
SS7 protocol. The SS7 protocol and network architecture are covered in NewNet
Communication Technologies, LLC, Inc. training courses.
1.2.1
Revisions and Updates

NewNet Communication Technologies, LLC seeks to provide total quality and customer
satisfaction through continuous improvement. Toward that goal, revisions to the manual will
occur from time to time due to software enhancements or documentation enhancements. The
revisions will be in change packets that contain only the pages that have modifications.
Change packets are automatically sent with software fix packages.
Page 1 - 2
1-1600-1003-01
How to Use this Manual
NewNet Communication Technologies, LLC requests that you register your manuals for
update notices. Customers may register their manual ownership via e-mail
(docteam@NewNet.com) or the NewNet Communication Technologies, LLC Web site.
Please include the documentation number, your name, address, and e-mail address.
1.2.2
Related Documents
This paragraph lists the related documents or materials that are beyond the scope of the
NewNet Communication Technologies, LLC family of manuals provided with your system.
These materials contain additional information that may be helpful to the user:
CCITT Blue Book (1988) Q.701 - Q.707
CCITT Blue Book (1988) Q.711- Q.714
ITU White Book (1993) Q.711- Q.714
ITU White Book (1992) Q.730 group
ITU White Book (1992) Q.761- Q.764
ITU-T Recommendation (1996) Q.711 - Q.714
ITU White Book (1993) Q.771 - Q.775
ITU (1997) Q.771 - Q.775
Bellcore Computer Based Training - SS7: A Brief Look, CCS/SS7 Reference
ANSI T1.114.x, 1992
ANSI T1.112.x, 1996
ANSI T1.114.x 1996
1.3

The Distributed7 API Reference Manual is part of a complete family of publications that
describe the Distributed7 products. These manuals are published separately and bound
together in two 3-ring binders for your convenience. To find the information you need, refer
to the list above and the Table of Contents or Index of this or any other NewNet
Communication Technologies, LLC manual.
The Distributed7 API Reference Manual is intended for use during operation of your
system. This manual, together with the additional documentation shipped with your unit and
documents referenced herein, is required for proper operation of your system.
1.3.3
Notations and Conventions

This section describes the notations and conventions that have been used consistently
throughout this manual.
Page 1 - 3
1-1600-1003-01
1.3.3.1
Acronyms and Mnemonics

Acronyms and mnemonics are introduced in this manual at first usage as follows ... the
Integrated Services Digital Network (ISDN). The acronyms or mnemonics are used
thereafter throughout the related manual without further introduction. Additionally, each
acronym used in this manual is referenced in the Index and is listed together with its
introduction in the Glossary to refresh the reader as necessary.
1.3.3.2
Alert Messages
ANSI A535 specifications define specific words and icons that alert the reader to dangerous
situations that may result in injury to a person or the equipment. These have been adapted
for use with NewNet Communication Technologies, LLC software.
Important: Recommendations, guidance, hints, tips, and shortcuts to alert readers to
situations and procedures that, if not followed properly, may complicate or prevent proper
operation of the software.
Notice: Situations that, if not avoided, may cause damage to the equipment.
Caution: Situations that, if not avoided, may corrupt the software or stop it entirely.
Page 1 - 4
1-1600-1003-01
Chapter 2:
2.1
SPM API Library
SPM API Library
Chapter Overview
This chapter provides the Service Provider Module (SPM) Application Programming
Interface (API) library calls for NewNet Communication Technologies, LLC Distributed7
software products. Also refer to the Distributed7 Application Development Manual for
more information on the usage of function calls.
2.2
SPM API Library

The SPM API library is the lowest level library, used directly by user processes and by other
NewNet Communication Technologies, LLC libraries. It is primarily used for interprocess
communication (IPC) between processes.
Every library call is described in detail on the following pages, including information on
input parameters, declarations, and return values. All the type definitions and structures can
be found in the api.h file. The following header files must be included at the beginning of
the application in the given order:
#include <api_sys.h>
#include <api.h>
#include <api_proto.h>
#include <api_macro.h>
The SPM library must be linked with the application if any of the library calls are used. The
SPM library should be the last library in the command line if other Distributed7 libraries are
also used. See the Distributed7 Application Development Manual for more information.
The SPM library (libspm.a) should be accessed using the $EBSHOME/access/lib path, and
linked with a user application (called file.c in the examples), as shown below. ($EBSHOME
is an environment variable holding the pathname of where the SS7 software is installed.)
cc
-I $EBSHOME/access/include
-L $EBSHOME/access/lib -lspm
Sample source code files, ebs_apidemo.c and ebs_oldapidemo.c, are provided to
demonstrate the use of Distributed7 SPM literals and functions. They should be compiled
with the MAKEFILE in the $EBSHOME/access/sample/spm directory. After it is
compiled, the executable will be located in the $EBSHOME/access/demo directory.
On-line reference manuals for the API library calls are provided in the form of manual
pages so that the user can invoke the UNIX standard man(1) utility to review the
Page 2 - 1
1-1600-1003-01
SPM API Library
information contained in them. The user should expand the MANPATH environment
variable to include the $EBSHOME/access/manpages directory in the search path.
Important: Distributed7 1.2. SPM API is multi-thread (MT) Safe, and can be used with
multi-threaded application programs. When compiling multi-threaded applications, the
-D_REENTRANT flag must be specified.
2.2.1
spm_alarm()
DESCRIPTION
spm_alarm()
Generates a user-specified alarm condition by populating and
sending an IPC message to the Distributed7 platform alarm handler process,
ALM_MNGR, if it is active. The message is sent via the first service endpoint that was
established by the user process with the spm_open() function. The function adds other
information, such as date and time stamps, to the supplied information and sends the
message as a normal (non-expedited) IPC message.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_alarm(byte_t sev, int type, char *buf);
level
Specifies the severity of the generated alarm, which must be either:
L_ALMLVL_INFO
for INFORMATIONAL
L_ALMLVL_MINOR for MINOR
L_ALMLVL_MAJOR for MAJOR
L_ALMLVL_CRITICAL for CRITICAL
L_ALMLVL_FATAL for FATAL
type
Identifies the full alarm type of the message which has the following
format:
Byte 3(MSB)
Byte 2
Byte 1
Byte 0
unused
group-id
module-id
alarm-no.
User-defined alarms must be previously defined with the Group IDs in

the Alarm Group Definition file and the module IDs and text definitions
in an Alarm Text file (see the User Manual for more details).
buf
Points to a user buffer containing a null-terminated character string of
alarm text which overwrites the default alarm text message. The string is
copied to the data portion of the IPC message. If the argument passes
null, then the default alarm text from the Alarm Text file will be used by
the ALM_MNGR process.
If parameters must be passed, spm_palarm() should be used instead of this call.
Page 2 - 2
1-1600-1003-01
SPM API Library
RETURN VALUES
0
-1
On success.
On failure; errno is set to indicate the error.
ERRORS
<EBADF>::There is no service endpoint established currently.
<EINVAL>::Invalid function argument is supplied.
<ENOALM>::The alarm handler process is not running.
<EDESTBLKD>::The alarm handler process is in blocked state.
SEE ALSO spm_snd(), alm_report(), ebs_alarm
2.2.2
spm_bind()
DESCRIPTION
spm_bind()
Binds the user-specified address at req with a service endpoint
identified as fd, then activates that service endpoint. This call makes the user process at
the given address known to other processes running under the Distributed7 environment.
Only after this call can messages be exchanged and logging and loopback capabilities be
used.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_bind(int fd, spmbind_t *req);
fd
File descriptor that was returned by the spm_open() call.
req
Points to the spmbind_t structure which contains the following members
and is defined in api.h:
ipcaddr_t ipcaddr;
ipckey_t ipckey;
void (*catcher)();
word_t srvtyp;
word_t flags;
word_t sntytmr;
dword_t uid;
dword_t gid;
The req->ipcaddr field specifies the addressing method (in req>ipcaddr.adrtyp) and any supplementary address information. Currently,
L_NMDOBJ and L_SS7OBJ are the only two valid address types.
Depending on the address type chosen, the user must populate the
appropriate supplementary address information field - req-
Page 2 - 3
1-1600-1003-01
SPM API Library
>ipcaddr.un.nmdobj (nmdobj_t structure) or req->ipcaddr.un.ss7obj

(ss7obj_t structure).
Note: SS7 objects (L_SS7OBJ) are processes that are users of the SS7
protocol, e.g. SS7 user parts defined in SS7 specifications. Named objects
(L_NMDOBJ) are processes that do not directly use the SS7 protocol and
will not send or receive SS7 message signaling units (MSUs). This
category includes the Distributed7 system processes, or daemons. The
two categories simply exist to help differentiate UNIX processes.
The req->ipckey field (ipckey_t structure) is automatically populated by
the system upon successful return from the call. It contains the host
Internet Protocol (IP) address and the UNIX process ID associated with
the user process, as well as the internal key assigned to the user process
by the system. The user process can use this information to specify its
address in the L_IPCKEY address type for other calls.
The req->*catcher field is a pointer to a user-defined function that
should be invoked if the Distributed7 software stops while the user
process is running. This function should provide a graceful termination of
the application processes running under the Distributed7 environment. If
the *catcher field is set to NULL, the user process would be terminated
immediately by the exit(2) function.
The req->srvtyp field (word_t type) contains the services to be provided
for the user process by the Distributed7 platform. The available types are
defined in api.h as L_IPC, L_MTP, L_SCCP, L_TCAP, and L_TEST.
The req->flags field (word_t type) specifies the desired operation mode
of the user process and can be constructed by OR-ing flags from the
following list (L_ACTIVE and L_STANDBY cannot be ORed together):
L_ACTIVE: Active mode of operation. User can receive and send
messages. This is the default mode.
L_STANDBY: Standby mode of operation. User can send messages
but is unable to receive messages unless the destination address for
the message was specified with the L_IPCKEY address type by the
message originator.
L_LOCAL: Local accessibility only. The user process can only be
addressed by processes on the local machine. Other machines in the
distributed network do not have information on the process. If this
flag is not set, then information on the user process is broadcast to all
machines in the network, and the user process can be addressed
across the network.
L_EXCLUSIVE: Exclusive binding. No other user can bind the
address specified by the user. If the L_LOCAL flag is also set, this
restriction applies to users on the local machine only. If the
L_LOCAL flag is not set, no users in the entire network can bind the
address. (This flag prevents multiple instances of the same object
from existing.)
Page 2 - 4
1-1600-1003-01
SPM API Library
The req->sntytmr field is reserved for future implementation of an

automatic sanity check mechanism.
The req->uid field contains the user ID and the req->gid field contains
the group ID of the user process. They are populated by the system
automatically. These two fields are planned to be used for forming closed
work groups among user processes and/or implementing security
measures in future releases of the Distributed7 product.
RETURN VALUES
0
-1
On success.
On failure, and errno is set to indicate the error.
ERRORS
<EBADF>::The file descriptor specified is invalid.
<EINVPORT>::The endpoint specified does not support address
binding.
<EBOUND>::The endpoint specified already has an address associated
with it.
<EXCLUSIVE>::Exclusive address binding is not permitted since the
user-specified address is currently in use by another user
process on local machine or across the network.
<ENONETD>::Network-based address binding is not permitted since
the netd process on local machine is not running.
<EMAXUSR>::Maximum number of user processes allowed to co-exist on
local machine is exceeded. This number is controlled by
the NMAXPROC parameter setting on the system.
<EMAXINST>::Maximum number of instances allowed to co-exist for a
named object or SS7 object is exceeded. This number is
controlled by the NMAXINST parameter setting on the
system.
<ESYSDOWN>::Unable to service user request since system software
is in the process of being shutdown.
<EINTR>::A signal was caught during processing of the user
request.
Page 2 - 5
1-1600-1003-01
SPM API Library
SEE ALSO spm_unbind(), spm_open(), spm_close()
2.2.3
spm_broadcast()
DESCRIPTION
spm_broadcast()
Sends the same user-specified IPC message to all selected
instances of a named object operating under the Distributed7 environment. The messages
are sent through the service endpoint identified by fd.
The function conducts various sanity checks on the destination user (e.g. verifies that the
user exists within the Distributed7 environment and is not currently in the blocked state)
prior to sending the broadcast message. This prevents against unattended STREAMS
message queues being flooded with broadcast messages.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_broadcast(int fd, ipcmsg_t *msgp, size_t nbytes, int acktime, int flags);
fd
msgp
Points to the ipcmsg_t structure which contains the message to be
broadcasted. The message type field [msgp->msghdr.msgtyp] and the
destination field [msgp->msghdr.dest] must be populated as well as the
user data (if any) [msgp->data]. The msgp->msghdr.orig address field is
automatically populated using the L_IPCKEY format.
nbytes
Specifies the number of bytes of user data included within the message.
This value should be less than the L_IPCDATASIZE system setting.
acktime
Specifies whether or not an acknowledgment is expected from the
destination, and the length of time to wait for one, if it is expected.
Acknowledgments confirm the receipt of the message at a particular
destination. The broadcast acknowledgment mechanism ensures that all
appropriate destination objects have received a copy of the message.
Usually, broadcast messages are sent without requiring an
acknowledgment. However, the acktime argument can be one of the
following:
L_NOWAIT (or 0): No acknowledgment is required. The function
returns immediately after the messages are sent.
Positive value (in milliseconds): An acknowledgment from each
destination, upon receipt of the message, is required. The function
will block and not return until all the acknowledgments are received
or the specified time limit has expired. The acknowledgments will be
collected and counted. When the expected number of
acknowledgments are received, the function returns to the process. If
Page 2 - 6
1-1600-1003-01
flags
SPM API Library
the time limit expires before the expected number are received, the
function returns and sets errno to EFAULT.
L_WAIT: An acknowledgment from each destination is required and
the function will block until all are received. At least one instance
must be able to receive the message, i.e., is not blocked.
Flag that limits the scope of a broadcast as well as specifies whether the
broadcast message should be sent as a normal or expedited IPC message.
By default, a broadcast message is sent as a normal message to all
instances of the destination object (standby and active instances on local
and remote hosts). To change the defaults, the flags argument is
constructed by OR-ing flags from the following list (L_ACTIVE and
L_STANDBY cannot be ORed together):
L_ACTIVE: Broadcast the message only to active instances of the
destination object. The message will not be delivered to any instances
of the destination object that are in standby mode. The default is all
instances, regardless of their mode of operation.
L_STANDBY: Broadcast the message only to standby instances of
the destination object. The message will not be delivered to any
instances of the destination object that are in active mode. The
default is all instances, regardless of their mode of operation.
L_LOCAL: Broadcast the message only to local instances of the
destination object, i.e., instances executing on the local host. In case
the destination object also features instances that are executing on
remote hosts at the time of the broadcast request, a copy of the userspecified message will not be sent to those instances. The default is
all instances, regardless of the host.
L_EXPEDITED: Broadcast the message as an expedited IPC
message. By default, the message is in normal mode.
Note: If the originator of a broadcast message is also a recipient of the message, a copy of
the broadcast message will not be delivered to it. Thus, if the message originator turns out
to be the only candidate to receive the message, the function will return a value and the
errno will be set to ESRCH or EDESTBLKD accordingly.
RETURN VALUES
The errno variable should always be checked to determine whether an error occurred.
SUCCESSES
number of expected recipientsOn success when acktime is set to L_NOWAIT ().
number of acknowledgmentsOn success when acktime is set to a positive value. (acktime
did not expire)

number of acknowledgmentsOn success when acktime is set to L_WAIT.
Page 2 - 7
1-1600-1003-01
SPM API Library
FAILURES
0
On failure and errno is set to ESRCH or EDESTBLKD when acktime is

set to 0 or a positive value.
# of acks received On failure and errno is set to EFAULT when acktime is set to a positive
value and acktime did expire.
-1
On failure for any other cases, and errno is set to indicate the error.
ERRORS
<ENBOUND>::The specified service endpoint does not have an address
associated with it.
<EMSGSIZE>::Message size specified is invalid. The maximum size of
user data that can be included as part of an L_IPCMSG
message is controlled by the L_IPCDATASIZE parameter
setting on the system.
<ESRCH>::Unable to locate the process table entry for the receiver
process.
<ESRCH>::The receiver process does not currently have an instance
as specified by the flags argument. (no recipients found)
<EDESTBLKD>::The receiver processes are in a blocked state.
<EFAULT>::The number of acknowledgment messages received is
different from the number of messages expected. Some
instances of destination may not have received the message
broadcasted or were unable to return an acknowledgment to
the sender within the time specified.
request.
<EAGAIN>::A priority-band message was specified. However, the
O_NDELAY or O_NONBLOCK flag is set and the write-side
queue is full due to internal flow control conditions.
SEE ALSO spm_snd(), spm_forward()
2.2.4
spm_close()
DESCRIPTION
spm_close()
Closes a previously established service endpoint, specified by fd,
that will no longer be used by the user process. The device file associated with the service
endpoint will be closed and any local library resources associated with it will be freed.
Normally, this function should be called after unbinding the address associated with the
endpoint using spm_unbind(). However, state information is not checked, so the function
may be called from any state. This call results in the close(2) call. The close(2) call is
Page 2 - 8
1-1600-1003-01
SPM API Library
abortive and will cause an automatic cleanup of any resources associated with the
endpoint, including automatic removal of any address information for that endpoint.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_close(int fd);
fd
RETURN VALUES
0
-1
On success.
On failure, and errno is set to indicate the error.
ERRORS
request.
SEE ALSO spm_unbind(), spm_open(), spm_bind()
2.2.5
spm_detect()
DESCRIPTION
spm_detect()
Detects occurrence of a particular set of non-STREAMS events
in a synchronous manner while operating under the Distributed7 environment. This
function is an alternative to the spm_notify() function which allows application programs
to detect STREAMS and/or non-STREAMS events in an asynchronous manner.
This function also responds to heartbeat request messages from the apmd daemon. The
function responds with an appropriate heartbeat response message, eliminating the need
for an application program to do so.
Note: The spm_notify() call takes precedence over this call. Asynchronous event handlers
should be disabled to use this function.
MT LEVEL
MT-Safe
Page 2 - 9
1-1600-1003-01
SPM API Library
SYNOPSIS
int spm_detect(int fd,long events, spmevent_t * req, spmevent_t * ret, int timeout);
fd
Specifies the service endpoint through which the request is sent. The fd
argument can be set to L_ANYSTREAM to detect the specified events at
any of the active service endpoints when a process has multiple
endpoints.
req
Supplies additional information that is needed to identify a particular
instance (e.g. individual host machine, process, board, etc.) of a nonSTREAMS event. Using req allows the user process to limit notifications
to only the occurrences of the event for the specified instance. To specify
an instance for an event, req must point to an appropriately populated
spmevent_t data structure. If req is set to NULL, then the user process
will be notified of all occurrences of the event type. Populating
spmevent_t is described in the events paragraphs on page 2-38. The
spmevent_t data structure is defined in api.h to contain the following
members:
long event; /* event type */
union {
struct e_shutdown shutdown;
struct e_dev dev;
struct e_tcpip tcpip;
struct e_env env;
struct e_alarm alarm;
struct e_usr usr;
struct e_sys sys;
struct e_queue queue;
} data;
/* event specific data */
ret
Holds specific information about a non-STREAMS event that just
occurred. To be able to retrieve additional information about specific
events, ret must point to an allocated data structure of type spmevent_t.
If ret is NULL, then no additional information about the specified event,
is retrieved.
events
Identifies the non-STREAMS events to be detected. The events
argumentand req->eventmust be set by bitwise OR-ing
combinations of the following flags:
M_SHUTDOWN: The Distributed7 system software on one of the
host machines is in the process of being shut down.
The req->data.shutdown.inetaddr field identifies a particular host. If
req is NULL, then the shutdown of any host in the network will be
detected. If ret was not set to NULL in the request, ret>data.shutdown.inetaddr will identify which host has caused the
M_SHUTDOWN event.
M_DEV_LOCAL: A status change has occurred in one of the SS7
boards configured on the local host machine. This event indicates the
Page 2 - 10
1-1600-1003-01
SPM API Library
establishment or removal of one of the STREAMS connections, i.e.,

links, between the SPM and the device drivers for the individual SS7
boards on the local host machine.
The req->data.dev.device field should identify a particular SS7
board. If req is NULL, the status changes on any SS7 board on the
local host will be detected. If ret was not set to NULL in the request,
ret->data.dev.device will identify which SS7 board has caused the
M_DEV_LOCAL event and ret->data.dev.status will hold the
boards status (L_ATTACHED or L_DETACHED).
M_DEV_REMOTE: A status change has occurred in one of the SS7
boards configured on a remote host machine in a distributed
environment. This event indicates the establishment or removal of
one of the STREAMS connections between the SPM and the device
drivers for the individual SS7 boards on a remote machine. This
event may also be generated as a result of a heartbeat failure on a
kernel-level TCP/IP connection maintained by the local machine.
The req->data.dev.inetaddr and req->data.dev.device fields should
identify a particular remote host and SS7 board. If req is NULL, the
status changes for any SS7 board on a remote host will be detected. If
ret was not set to NULL in the request, ret->data.dev.inetaddr and
ret->data.dev.device will identify which host and SS7 board has
caused the M_DEV_REMOTE event and ret->data.dev.status will
hold the boards status (L_ATTACHED or L_DETACHED).
M_DEV: A status change has occurred in any one of the SS7 boards
configured on any one of the host machines (local or remote) of the
distributed Distributed7 environment. This event is constructed by
bitwise OR-ing M_DEV_LOCAL and M_DEV_REMOTE.
The req->data.dev.inetaddr and req->data.dev.device fields should
identify a particular host and SS7 board. If req is NULL, the status
changes for any SS7 board in the network will be detected. If ret was
not set to NULL in the request, ret->data.dev.inetaddr and
ret->data.dev.device will identify which host and SS7 board has
caused the M_DEV event and ret->data.dev.status will hold the
boards status (L_ATTACHED or L_DETACHED).
M_TCPIP: A status change has occurred in one of the kernel-level
TCP/IP connections maintained between the individual host
machines. This event may result from the establishment or removal
of one of several TCP/IP connections.
The req->data.tcpip.inetaddr[2] field should identify a particular
TCP/IP connection (i-net addresses) and req->data.tcpip.pad must be
initialized to zero. If req is NULL, the status changes for any TCP/IP
connection maintained between any two host machines in the
network will be detected. If ret was not set to NULL in the request,
ret->data.tcpip.inetaddr[2] will identify the i-net addresses of the
TCP/IP connection that has caused the M_TCPIP event and
Page 2 - 11
1-1600-1003-01
Page 2 - 12
SPM API Library
ret->data.tcpip.status will hold the connection status

(L_ESTABLISHED or L_REMOVED).
M_ENV_LOCAL: A change in operational environment has
occurred on the local host machine. This event indicates a change in
the contents of the process table maintained on the local host
machine. The change may be due to the startup of a new process, the
termination of an existing process, or a change in the status, operation
mode, or service type of an executing process.
The req->data.env.ipcaddr field should identify a particular process
and req->data.env.pad must be initialized to zero. If req is NULL, the
status changes for any process on the local host will be detected. If ret
was not set to NULL in the request, ret->data.env.ipcaddr will
identify which process has caused the M_ENV_LOCAL event. The
ret->data.env.srvtype, oprmode, and usrstat fields will hold service
type, operation mode (L_ACTIVE, L_STANDBY), and status
(L_USR_OKAY, L_USR_BLKD, L_USR_NONE).
M_ENV_REMOTE: A change in operational environment has
occurred on a remote host machine of a distributed environment. This
event indicates a change in the contents of the process table
maintained on a remote machine. The change may be due to the
startup of a new process, the termination of an existing process, or a
change in the status, operation mode, or service type of an executing
process. This event may also be generated as a result of a heartbeat
failure on a kernel-level TCP/IP connection maintained by the local
machine.
Only changes to globally registered processes will cause an
M_ENV_REMOTE event. Changes in the status of locally registered
processes on remote host machines cannot be detected.
status changes for any process on a remote host is detected. If ret was
not set to NULL in the request, ret->data.env.ipcaddr will identify
which process has caused the M_ENV_REMOTE event. The
M_ENV: A change in operational environment has occurred on one
of the host machines (local or remote) of the distributed Distributed7
environment. The change may be due to the startup of a new process,
the termination of an existing process, or a change in the status,
operation mode, or service type of an executing process. This event is
constructed by bitwise OR-ing M_ENV_LOCAL and
M_ENV_REMOTE.
1-1600-1003-01
SPM API Library
status changes for any process in the network will be detected. If ret
was not set to NULL in the request, ret->data.env.ipcaddr will
identify which process has caused the M_ENV event. The
M_ALARM: An alarm event has occurred on one of the host
machines in the network. This event is triggered by ALM_MNGR
daemon using spm_trigger() and signifies the occurrence of an alarm
condition.
The req->data.alarm.group, module, type, and severity fields should
identify a particular alarm event. Group, module, and type specify the
entire alarm number that is defined in the Alarm Group Definition
and Alarm Text files. Severity can be L_SEVINFO, L_SEVMINOR,
L_SEVMAJOR, L_SEVCRITICAL, or L_SEVFATAL. If req is
NULL, all alarm events in the network will be detected. If ret was not
set to NULL in the request, ret->data.alarm.inetaddr will contain the
host that triggered the M_ALARM condition and
ret->data.alarm.group, module, type, and severity will identify the
specific alarm.
M_USR: A user-defined event has occurred on one of the host
machines in the network. This event is triggered by an application
program using spm_trigger() and signifies the occurrence of an event
whose meaning and importance are application-specific.
The req->data.usr.number field should identify a particular userdefined event number. If req is NULL, all user-defined events on the
local host or across the network (depends on the scope defined for an
event) will be detected. If ret was not set to NULL in the request,
ret->data.usr.scope will contain the event scope (L_LOCALSCOPE,
L_GLOBALSCOPE), ret->data.usr.number will contain the event
number, and ret->data.usr.info will hold event information about the
M_USR event.
M_SYS: A system event has occurred on one of the host machines in
the network. System events report fault conditions to application
programs. The faults occur during operation of the Distributed7
system software.
The req->data.sys.type field should identify a particular system
event, i.e., L_NONEXCLUSIVE. The req->data.sys.data field
should specify the address of a particular object. If req is NULL, all
system events on the local host or across the network will be
detected. If ret was not set to NULL in the request, ret->data.sys.type
will hold the event type.
M_QUEUE: A queue management event has occurred. Queue
management events are generated by the system to indicate that there
Page 2 - 13
1-1600-1003-01
timeout
SPM API Library
is a build-up in the applications read-side STREAMS queues or that

incoming messages buffered by the system are becoming out-of-date.
When such events occur, Distributed7 will take an appropriate action
as described in the spm_setqparams() on page 2-53.
The req->data.queue.reason field should identify a particular set of
queue management events. If req is NULL, all queue management
events will be detected. If ret was not set to NULL in the request,
ret->data.queue.reason will hold the queue management event
(L_HIGHMARK, L_LOWQSIZE, L_MAXQSIZE, L_LOWQTIME,
or L_MAXQTIME) and ret->data.queue.action will hold the action
that the system took (L_DISCARDED or L_FLOWCNTLD).
M_ALL: A non-STREAMS related event has occurred. This event is
constructed simply by bitwise OR-ing all non-STREAMS events
(those starting with M_) listed in this section.
Indicates the amount of time to wait for the specified event(s), if one has
not occurred. The timeout values are as follows:
L_WAIT: the call will wait indefinitely for the event, unless it is
interrupted by a UNIX signal.
L_NOWAIT: the call will immediately return if no event occurs (with
an error of ENOMSG).
Any positive value (in milliseconds): the call will wait the specified
length of time for the event before returning.
RETURN VALUES
0
-1
On success.
ERRORS
<EBADF>::An fd value of L_ANYSTREAM (or -1) is supplied but there
are no endpoints established currently.
associated with it.
<ETIME>::Events specified have not occurred within timeout
milliseconds.This is also known as a timeout condition.
request.
Page 2 - 14
1-1600-1003-01
SPM API Library
SEE ALSO spm_notify(), spm_qparams
2.2.6
spm_display()
DESCRIPTION
spm_display()
Creates an IPC message with the contents of buf as the data
portion and sends it to the display handler. It is sent to the display handler via the first
established service endpoint associated with the user process. At least one service
endpoint must have already been established using the spm_open().
MT LEVEL
MT-Safe
SYNOPSIS
int spm_display(char *buf);
buf
Set to point to a user buffer containing a null-terminated character string.
The string is copied to the data portion of the IPC message.
Other information for the IPC message is automatically populated. The
message is sent as a normal message, if the display handler is running.
RETURN VALUES
0
-1
On success.
ERRORS
<ENOCMI>::The display handler process is not running.
<EDESTBLKD>::The display handler process is in blocked state.
2.2.7
spm_errgroup()
DESCRIPTION
spm_errgroup()
Identifies the error category, i.e., Distributed7 software module
through which the error is generated, associated with the error code specified in errnum
and returns a pointer to the corresponding character string.
MT LEVEL
MT-Safe
Page 2 - 15
1-1600-1003-01
SPM API Library
SYNOPSIS
char *spm_errgroup(int errnum);
errnum
Specifies the error code associated with a particular software module.
For a list of platform-specific error messages that can be generated by the
Distributed7 software components, and the categories associated with
them, refer to the <api_errno.h> header file.
SEE ALSO ebs_explain(), spm_strerror()
2.2.8
spm_open()
DESCRIPTION
spm_fopen()
Opens a file supplied as part of the Distributed7 product software
and associates a pointer with it for subsequent file operations.
MT LEVEL
MT-Safe
SYNOPSIS
FILE *spm_fopen(char *pathname, char *oflag);
pathname
Points to a character string that contains the relative path name of the file
to be opened. The path must be relative to the $EBSHOME environment
variable.
oflag
Points to a character string that specifies the type of operation to be
performed on the file. (See fopen(3) for acceptable values.)
RETURN VALUES
null pointer
On failure. (pathname is inaccessible or oflag is invalid.)
ERRORS
None
SEE ALSO spm_getdir()
2.2.9
spm_forward()
DESCRIPTION
spm_forward()
Forwards an SS7 or IPC message that was received through the
service endpoint, identified by fd, to a new destination address. The contents of the
original message are not modified. Before sending the message, the function verifies that
the destination exists within the Distributed7 environment and is not in the blocked state.
Page 2 - 16
1-1600-1003-01
SPM API Library
This check prevents an unattended STREAMS message queue from being flooded with
messages from various sources.
These checks can be bypassed by setting the L_NOCHECK flag. This approach improves
the performance of the spm_forward() function call, however, failures do not occur when
an attempt is made to forward a message to a non-existing destination. Therefore, some
other method should be used to ensure that the destination exists and is not in a blocked
state prior to using the spm_forward() function.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_forward(int fd, ipcmsg_t *msgp, ipcaddr_t *addr, int flags);
fd
msgp
Points to the ipcmsg_t user buffer which contains the message to be
forwarded.
addr
Specifies the new destination in ipcaddr_t to which the message is to be
forwarded.
flags
Flag for message priority or validity check. Valid settings are:
L_EXPEDITED: The message is sent to its new destination as an
expedited message, regardless of its original priority level. Unless the
L_EXPEDITED flag is set, no change occurs in the priority level of
the message to be forwarded.
L_NOCHECK: Bypass checks for the validity/availability of the
destination address before sending the message.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
process.
<ESRCH>::The receiver process does not currently have an "active"
instance.
<EDESTBLKD>::Unable to send message to its destination since
destination is currently in blocked state.
Page 2 - 17
1-1600-1003-01
SPM API Library

request.
SEE ALSO spm_rcv(), spm_snd(), spm_broadcast()
2.2.10 spm_getalarm()
DESCRIPTION
spm_getalarm()
Analyzes the contents of an IPC message at msgp which contains
information about a specific alarm condition. The msgp->msghdr.msgtyp field must
contain SPM_ALARM for the IPC message to be an alarm message. This call extracts the
severity, type of the alarm, and the text from the data portion of the message. This call is
normally used by the external alarm interface when customizing the Alarm object.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getalarm(ipcmsg_t *msgp, byte_t *level, int *type, char *buf);
msgp
Points to the buffer containing the IPC message.
level
Points to a user variable containing one of the following severity levels:
L_ALMLVL_INFO
for INFORMATIONAL
type
buf
Points to a user variable that holds the full alarm ID number. The alarm
ID number of the message includes group ID, module ID, and the alarm
number in the following format:
Byte 3(MSB)
Byte 2
Byte 1
Byte 0
unused
group-id
module-id
alarm-no.
Points to a user buffer where the NULL-terminated character string

[specifying the actual alarm text] that was retrieved from the data portion
of the IPC message is copied.
RETURN VALUES
length of
On success.
character string
-1
Page 2 - 18
1-1600-1003-01
SPM API Library
ERRORS
2.2.11 spm_getdir()
DESCRIPTION
spm_getdir()
Retrieves the pathname of the directory where the Distributed7
product software has been installed.
This function looks up the current value of the $EBSHOME environment variable to
determine the directory. Therefore, $EBSHOME must have been set appropriately.
MT LEVEL
MT-Safe
SYNOPSIS
char *spm_getdir(void);
RETURN VALUES
pathname
The default directory, /home/EBS, will be returned instead of the actual directory in any
of the following circumstances:
$EBSHOME is not set.

$EBSHOME is set to an invalid directory.
$EBSHOME is set to a directory that does not have the +rwx
permissions.
ERRORS
None
2.2.12 spm_gethiwat()
DESCRIPTION
spm_gethiwat()
Retrieves the current high water mark for a priority band at a
service endpoints streamhead read-side queue.
Water marks control the amount of data that can be placed on a particular STREAMS
queue or a priority band of the queue. By default, after spm_bind(), the high and low
Page 2 - 19
1-1600-1003-01
SPM API Library
water marks of a service endpoints streamhead read-side queue are initialized to the
settings of the service providers read-side queue.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_gethiwat(int fd, unsigned long *valptr, int flags);
fd
Identifies the service endpoint.
valptr
Points to a user space variable that will hold the data.
flags
Specifies the priority band as shown below (Either L_SS7MSG or
L_IPCMSG must be used. L_EXPEDITED may be ORed with either.):
L_SS7MSG: Retrieves settings for the priority band used for
receiving normal SS7 messages.
L_IPCMSG: Retrieves settings for the priority band used for
receiving normal IPC messages.
L_EXPEDITED: Retrieves streamhead water mark settings for the
priority band used for receiving expedited IPC or SS7 messages.
RETURN VALUES
0
-1
On success.
On failure; sets errno to indicate the error.
ERRORS
associated with it.
<ENOSR>::Unable to allocate kernel-level resources for
manipulating the streamhead options.
2.2.13 spm_getlowat()
DESCRIPTION
spm_getlowat()
Retrieves the current low water mark for a priority band at a
Page 2 - 20
1-1600-1003-01
SPM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getlowat(int fd, unsigned long *valptr, int flags);
fd
valptr
Points to a user space variable that will hold the data.
flags
Specifies the priority band as shown below (Either L_SS7MSG or
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
2.2.14 spm_getoprmode()
DESCRIPTION
spm_getoprmode()
Retrieves the operation mode of a user-specified process. The
process must be operating under the Distributed7 environment via an available service
endpoint that was previously established with spm_open(). If multiple endpoints were
established, the very first endpoint that was established will be used.
MT LEVEL
MT-Safe
Page 2 - 21
1-1600-1003-01
SPM API Library
SYNOPSIS
int spm_getoprmode(ipcaddr_t *addr, int *oprmode);
addr
Specifies the address of the target process. If addr points to a named
object that has multiple instances operating in the distributed
environment, then the operation mode of all active instances will be
returned and placed next to each other in the buffer. The user process
must select the information of the desired instance.
oprmode
Points to the array where the function will place the retrieved
information. The user buffer must be large enough to hold the
information from all instances when the target process has multiple
instances. The maximum number of instances is set by NMAXINST.
Operation mode (oprmode) can be:
messages.
message originator.
across the network.
address.
RETURN VALUES
# of instances
-1
On success.
If no instances are active (all standby), then no information will be
returned.
ERRORS
<ESRCH>::Unable to locate the process table entry for the userspecified process.
<EINTR>::A signal was caught during processing of the I_GETUSRINFO
ioctl(2) request.
Page 2 - 22
1-1600-1003-01
SPM API Library
2.2.15 spm_getqinfo()
DESCRIPTION
spm_getqinfo()
Allows an application to retrieve the total number of messages [as
well as the total number of bytes contained in these messages] posted on the read-side
STREAMS queues associated with itself.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getqinfo(int fd , spmqinfo_t *req );
fd
Identifies the service endpoint associated with the application and should
be obtained with a previous call to the spm_open() function.
req
Points to a user-space data structure of type spmqinfo_t and it specifies
where to copy the information to be retrieved. The contents of the
spmqinfo_t data structure are as follows:
typedef struct {
ulong rqsize;
ulong sh_rqsize;
ulong rqcount;
ulong sh_rqcount;
} spmqinfo_t;
RETURN VALUES
0
-1
On success.
Upon successful return from the call, the rqsize field of the data structure pointed to by the
req argument contains the total number of messages waiting on the upper read-side queue
of the STREAMS multiplexer associated with the application. The number of bytes
currently posted on that queue is accessible via the rqcount field. Information returned via
the sh_rqsize and sh_rqcount fields is very much similar to what is available through the
rqsize and rqcount fields; however, they identify the total number of messages as well the
byte count for the streamhead read-side queue associated with the application.
ERRORS
associated with it.
Page 2 - 23
1-1600-1003-01
SPM API Library
SEE ALSO spm_stroptions(), spm_getqparams(), spm_getqstat(), ebs_qinfo
2.2.16 spm_getqparams()
DESCRIPTION
spm_getqparams()
Retrieves the current settings of the queue management
parameters. for handling messages buffered by the system in the STREAMS multiplexer's
upper read-side queue that is associated with the calling application. This queue is used to
buffer messages when the number of messages accumulated on the applications
streamhead read-side queue has reached its high water mark.
Buffering on the multiplexers queue puts a load on STREAMS resources and long-term
buffering can result in system-wide performance degradation.
Note: Settings for the applications streamhead read-side queue are changed with the
spm_setlowat() and spm_sethiwat() calls.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_setqparams(int fd, spmqparams_t *req);
fd
Identifies the service endpoint. The value is returned by the spm_open()
call.
req
Points to the structure containing the returned queue management data.
This structure is spmqparams_t and is defined in api.h with the
following fields:
int low_qsize;
int max_qsize;
int low_qtime;
int max_qtime;
These fields are described in spm_setqparams() on page 2-53.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
Page 2 - 24
1-1600-1003-01
SPM API Library
SEE ALSO spm_setqparams(), spm_notify(), spm_sethiwat(), spm_setlowat()
2.2.17 spm_getqstat()
DESCRIPTION
spm_getqstat()
Allows an application to retrieve various pieces of statistical
information regarding the messages sent/received by that application while operating
under the Distributed7 environment.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getqstat(int fd , spmqstat_t *req);
fd
Identifies the service endpoint associated with the application and should
be obtained via a previous call to the spm_open() function.
req
Points to a user-space data structure of type spmqstat_t and it specifies
where to copy the information to be retrieved. The contents of this data
structure is as follows:
typedef struct {
ulong msgs_injd;
ulong msgs_dfrd;
ulong msgs_dlvd;
ulong msgs_blkd;
ulong msgs_aged;
ulong msgs_disc;
} spmqstat_t;
RETURN VALUES
0
-1
On success.
Upon successful return from the call, the individual fields of the data structure pointed to
by the req argument will be initialized by the system to contain the current value of the
corresponding measurement count. The following is a complete list of different types of
measurement peg counts maintained by the Distributed7 platform on behalf of each
application:
total number of messages injected by the application,
total number of deferred messages originated by the application,
total number of messages submitted to the application,
Page 2 - 25
1-1600-1003-01
SPM API Library
total number of times execution of the STREAMS upper-read service procedure has
been suspended due to accumulation in the streamhead read-side queue of the
application,
total number of messages that have been discarded by the platform due to aging,
total number of messages that have been discarded by the platform to help prevent
excess message accumulation in the read-side queues associated with the application.
Distributed7 initializes the measurement peg counts associated with each endpoint, i.e.,
STREAMS connection, when the endpoint is established, i.e., during an spm_open() call,
and maintains them until the endpoint is removed.
ERRORS
associated with it.
SEE ALSO spm_stroptions(), spm_qparams(), spm_getqinfo(), ebs_qstat
2.2.18 spm_getregtime()
DESCRIPTION
spm_getregtime()
Retrieves the time of registration (in seconds) of the individual
instances of a user-specified process. The user-specified process must be operating under
the Distributed7 environment via an available service endpoint that was previously
established with spm_open(). If multiple endpoints were established, the very first
endpoint that was established will be used.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getregtime(ipcaddr_t *addr, time_t *regtime);
addr
environment, then the time of registration of all active instances will be
regtime
Page 2 - 26
1-1600-1003-01
SPM API Library
RETURN VALUES
# of instances
-1
On success.
returned.
ERRORS
ioctl(2) request.
2.2.19 spm_getsrvtype()
DESCRIPTION
spm_getsrvtype()
Retrieves the service type of a user-specified process. The userspecified process must be operating under the Distributed7 environment via an available
service endpoint that was previously established with spm_open(). If multiple endpoints
were established, the very first endpoint that was established will be used.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getsrvtype(ipcaddr_t *addr, int *srvtype);
addr
environment, then the service type of all active instances will be returned
and placed next to each other in the buffer. The user process must select
the information of the desired instance.
srvtype
instances. The maximum number of instances is set by NMAXINST. The
service type can be L_IPC, L_MTP, L_SCCP, or L_TCAP, as defined in
spm_bind() and api.h.
Page 2 - 27
1-1600-1003-01
SPM API Library
RETURN VALUES
# of instances
-1
On success.
returned.
ERRORS
ioctl(2) request.
2.2.20 spm_getusrinfo()
DESCRIPTION
spm_getusrinfo()
Retrieves the L_IPCKEY address, current status, service type,
operation mode, and registration time of a user-specified process. The user-specified
process must be operating under the Distributed7 environment via an available service
endpoint that was previously established with spm_open(). If multiple endpoints were
established, the very first endpoint that was established will be used.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getusrinfo(ipcaddr_t *addr, spmuser_t *userinfo);
addr
environment, then the user information of all active instances will be
returned in an array of spmuser_t structures at userinfo. The user
process must select the information of the desired instance.
userinfo
The userinfo argument points to an spmuser_t structure with the
following fields:
ipcaddr_t ipcaddr;
time_t regtime;
word_t srvtyp;
Page 2 - 28
1-1600-1003-01
SPM API Library
word_t status;
word_t flags;
The IPC key of the process is returned in
userinfo->ipcaddr.un.ipckey (in L_IPCKEY format).
The userinfo->regtime field holds the time at which the process
registered.
The processs current status is returned in userinfo->status and can be:
L_USR_OKAY: process exists and is in normal operation.
L_USR_BLKD: process is blocked, meaning the read-side queue is
full (could be a hung process or overflow).
L_USR_WAIT: process is in a transient wait state during the
procedure of binding itself as a network object. It is receiving
confirmations on the binding from all the machines in the network.
L_USR_NONE: process does not exist.
Service type is returned in userinfo->srvtype and can be L_MTP or
L_SCCP, as defined in spm_bind() and api.h.
Operation mode is returned in userinfo->flags and can be:
messages.
message originator.
across the network.
address.
Current status, operation mode, service type, and registration time can be
retrieved individually with their respective calls: spm_getusrstat(),
spm_getoprmode(), spm_getsrvtype(), and spm_getregtime().
RETURN VALUES
# of instances
On success.
returned.
Page 2 - 29
1-1600-1003-01
-1
SPM API Library
ERRORS
<EHOSTOTHER>::Unable to retrieve information about the userspecified process which is located on a host that is not
running AccessMANAGER software.
2.2.21 spm_getusrstat()
DESCRIPTION
spm_getusrstat()
Retrieves the current status of a user-specified process. The target
processs address is provided in the addr argument. The function places the retrieved
information in the array pointed to by the userstat argument. The user-specified process
must be operating under the Distributed7 environment via an available service endpoint
that was previously established with spm_open(). If multiple endpoints were established,
the very first endpoint that was established will be used.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_getusrstat(ipcaddr_t *addr, int *userstat);
addr
environment, then the current status of all active instances will be
userstat
The current status of the process can be:
L_USR_OKAY: process exists and is in normal operation.
L_USR_BLKD: process is blocked, meaning the read-side queue is
full (could be a hung process or overflow).
L_USR_WAIT: process is in a transient wait state during the
procedure of binding itself as a network object. It is receiving
confirmations on the binding from all the machines in the network.
Page 2 - 30
1-1600-1003-01
SPM API Library
L_USR_NONE: process does not exist.
RETURN VALUES
# of instances
-1
On success.
ERRORS
ioctl(2) request.
2.2.22 spm_log()
DESCRIPTION
spm_log()
Activates and deactivates the Distributed7 message logging
capabilities for a service endpoint, either of the calling process or some other process. An
address must already have been bound to the service endpoint with the spm_bind() call.
After activation, the messages to be logged are forwarded to the logger process
(LOG_MNGR or process specified by where) for display to the console or for logging to
a user-specified file.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_log(int fd, int cmd, ipcaddr_t *where, ipcaddr_t *who);
fd
Identifies the service endpoint through which the request will be sent. If
the who argument is NULL, then fd is also the service endpoint where
logging will be activated/deactivated.
cmd
Specifies whether the call is an activation or deactivation of logging. The
command should be one of the following:
L_LOGOFF: deactivate message logging. (An attempt to deactivate
logging at an endpoint that does not have logging activated will have
no effect.)
L_LOGON: activate logging of all messages, both received and sent
through the service endpoint.
L_LOGON_RDONLY: only activate logging of messages received
Page 2 - 31
1-1600-1003-01
SPM API Library
who
where
L_LOGON_WRONLY: only activate logging of messages sent

Identifies the process to be logged. It must be NULL to log messages of
the calling process. If the who argument points to a filled ipcaddr_t
structure, then logging will be activated/deactivated for the service
endpoint at that address.
Identifies the process that will receive the log messages. It must be
NULL to send the log messages to the Distributed7 LOG_MNGR
process. If the where argument points to a filled ipcaddr_t structure,
then the log messages will be sent to that process instead of the
LOG_MNGR daemon. Whether LOG_MNGR or another process is
used, the logger process must be active and running.
RETURN VALUES
0
-1
On success.
ERRORS
<ENBOUND>::The service endpoint specified does not have an address
associated with it.
<ENOLOG>::The log daemon process is not running.
<ESRCH>::The user-specified process for which message logging
should be (de)activated is not running.
<ESRCH>::The user-specified logger process is not running.
<EFAULT>::The user-specified process for which message logging
should be (de)activated has more than one instance
running. The L_IPCKEY addressing method should be used to
identify the instance of interest.
<EFAULT>::The user-specified process by which messages should be
logged has more than one instance running. The L_IPCKEY
addressing method should be used to identify the instance
of interest.
<EFAULT>::The user-specified process by which messages should be
logged is a hidden object and is not located on the same
host that the object for which message logging is to be
activated.
<EFAULT>::The user-specified process for which message logging
should be activated is the same as the process by which
messages should be logged. This results in an infinite
loop; therefore, is not permitted.
Page 2 - 32
1-1600-1003-01
SPM API Library
2.2.23 spm_loop()
DESCRIPTION
spm_loop()
Activates and deactivates the Distributed7 message loopback
capabilities for a service endpoint. Addresses of all involved processes must already have
been bound to service endpoints with the spm_bind() call. When loopback is activated, all
messages sent and/or about to be received through the specified service endpoint
(depending on cmd) are routed to a selected process (through where) instead of their
normal destinations (as given in the dest field of each message). When loopback is
deactivated, messages are no longer diverted.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_loop(int fd, int cmd, ipcaddr_t *where, ipcaddr_t *who);
fd
Identifies the service endpoint through which the request will be sent. If
the who argument is NULL, then fd is also the service endpoint where
loopback will be activated/deactivated.
cmd
Specifies whether the call is an activation or deactivation of loopback.
The command should be one of the following:
L_LOOPOFF: deactivate message loopback. (An attempt to
deactivate loopback at an endpoint that does not have loopback
activated will have no effect.)
L_LOOPON: activate loopback for all messages, both those that are
sent and those about to be received through the service endpoint.
L_LOOPON_RDONLY: only activate loopback for messages about
to be received through the service endpoint.
L_LOOPON_WRONLY: only activate loopback for messages sent
who
Identifies the process for which the loopback command should be
applied. To specify the calling process, who must be NULL. If who
points to a filled ipcaddr_t structure, then loopback will be activated/
deactivated for the service endpoint at that address.
where
Points to the address of the process to which the messages should be sent.
A NULL address for where indicates that the loopback capability should
be deactivated at the specified endpoint.
RETURN VALUES
0
-1
On success.
Page 2 - 33
1-1600-1003-01
SPM API Library
ERRORS
<ENBOUND>::The service endpoint specified does not have an address
associated with it.
<ESRCH>::The user-specified process for which message loopback
should be (de)activated is not running.
<ESRCH>::The user-specified process to which messages should be
routed is not running.
<EFAULT>::The user-specified process for which message loopback
should be (de)activated has more than one instance
running. The L_IPCKEY addressing method should be used to
identify the instance of interest.
<EFAULT>::The user-specified process to which messages should be
routed has more than one instance running. The L_IPCKEY
addressing method should be used to identify the instance
of interest.
<EFAULT>::The user-specified process to which messages should be
routed is a hidden object and is not located on the same
host that the object for which message loopback is to be
activated.
<EFAULT>::An attempt is made to loopback messages destined for a
particular service endpoint to itself.
2.2.24 spm_notify()
DESCRIPTION
spm_notify()
Allows an application program to do asynchronous input/output
processing, i.e., the application can be interrupted from local processing when a pending
event occurs so that special actions can take place. The pending event may be system-wide
or associated with service endpoints, i.e., STREAMS-related. The spm_notify() function
can also be used to cancel the request for notification of pending events (see page 2-43).
Notifications can be received for multiple occurrences of a specific non-STREAMS event
and the application can invoke different user-level functions for different instances of that
event. Different functions can be invoked by making several successive spm_notify() calls
and specifying a different func argument each time. There is no limitation on the number
of spm_notify() calls an application can issue.
The spm_notify() function detects and responds to a heartbeat request message from the
apmd daemon with an appropriate heartbeat response message. Therefore, the application
does not need the logic to handle heartbeat request messages.
A synchronous version of this function that detects non-STREAMS events as they occur is
available through the spm_detect() function. However, spm_notify() takes precedence
over spm_detect().
Page 2 - 34
1-1600-1003-01
SPM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int spm_notify(int fd, dword_t events, spmevent_t *req, spmevent_t *ret, void
(*func)(int));
fd
Identifies a service endpoint. For system-wide eventsthose events
beginning with M_ in the events listfd specifies the service endpoint
through which the request is sent. For STREAMS-related eventsthose
events beginning with S_ in the events listfd identifies the service
endpoint with which the events are associated. The fd argument can be
set to L_ANYSTREAM to indicate that the specified events should
trigger the actions if they occur at any of the active service endpoints
when a process has multiple endpoints. However, when
L_ANYSTREAM is used, the service endpoint can only be identified
through the file descriptor value that is passed as an argument to the userdefined function at func.
req
Supplies additional information that is needed to identify a particular
instance, e.g., individual host machine, process, board, etc., of a nonSTREAMS event. req allows the user process to limit notifications to
only the occurrences of the event for the specified instance. To specify an
instance for an event, req must point to an appropriately populated
spmevent_t data structure. If req is NULL, then the user process is
notified of all occurrences of the event type. For STREAMS events, the
pointer must be set to NULL. Populating spmevent_t is described in the
events paragraphs on page 2-38. The spmevent_t data structure is
defined in api.h to contain the following members:
union {
struct e_dev dev;
struct e_env env;
struct e_usr usr;
struct e_sys sys;
} data;
where event-specific data structures are defined as follows:
/* struct used for M_SHUTDOWN event notification */
struct e_shutdown {
dword_t inetaddr;
/* i-net address associated */
};
Page 2 - 35
1-1600-1003-01
SPM API Library
/* struct used for M_DEV [and derivatives] event notification */

struct e_dev {
dword_t inetaddr;
word_t device;
/* device number */
word_t status;
/* device status */
#define L_ATTACHED
0x0001
/* device detached */
#define L_DETACHED
0x0002
/* device attached */
};
/* struct used for M_TCPIP event notification */

struct e_tcpip {
dword_t inetaddr[2];
/* i-net addresses associated */
word_t status;
/* connection status */
#define L_ESTABLISHED
0x0001
/* connection established */
#define L_REMOVED
0x0002
/* connection removed */
word_t pad;
/* padding space */
};
/* struct used for M_ENV [and derivatives] event notification */

struct e_env {
pcaddr_t ipcaddr;
word_t srvtype;
/* service type */
word_t oprmode;
/* operation mode */
#define L_ACTIVE
0x0100
/* active */
#define L_STANDBY
0x0200
/* standby */
word_t usrstat;
/* operational status */
#define L_USR_OKAY
0x0001
/* not blocked */
#define L_USR_BLKD
0x0002
/* blocked */
#define L_USR_NONE
0xffff
/* does not exist */
word_t pad;
Page 2 - 36
/* address info */
/* padding space */
1-1600-1003-01
SPM API Library
};
/* struct used for M_ALARM event notification */

struct e_alarm {
dword_t inetaddr;
byte_t group;
/* group number */
byte_t module;
/* module number */
byte_t type;
/* alarm type */
byte_t severity;
/* severity (bit-mask) */
#define L_SEVINFO
0x01
/* informational */
#define L_SEVMINOR
0x02
/* minor */
#define L_SEVMAJOR
0x04
/* major */
#define L_SEVCRITICAL
0x08
/* critical */
#define L_SEVFATAL
0x10
/* fatal */
};
/* struct used for M_USR event notification */

struct e_usr {
#define MAXINLEN
long scope;
24
/* event scope */
#define L_LOCALSCOPE
0x00000001
/* local host only */
#define L_GLOBALSCOPE
0x00000002
/* across the network */
long number;
/* event number */
char info[MAXINLEN];
/* event-specific info */
};
/* struct used for M_SYS event notification */

struct e_sys {
long type;
#define L_NONEXCLUSIVE
dword_t inetaddr;
/* event type */
0x00000001
/* exclusiveness violation */
union {
Page 2 - 37
1-1600-1003-01
SPM API Library
spmuser_t usrinfo; /* address info */
} data;
};
/* struct used for M_QUEUE event notification */

struct e_queue {
word_t
reason;
/* reason event generated */
#define L_HIGHMARK
0x0001
/* high water mark exceeded */
#define L_LOWQSIZE
0x0002
/* low queue size exceeded */
#define L_MAXQSIZE
0x0004
/* max queue size exceeded */
#define L_LOWQTIME
0x0008
/* low age of congestion exceeded */
#define L_MAXQTIME
0x0010
/* max age of congestion exceeded */
word_t
action;
/* action taken by the system */
#define L_DISCARDED
0x0001
/* msg discarded */
#define L_FLOWCNTLD
0x0002
/* msg buffered internally */
};
ret
func
events
Page 2 - 38
Holds specific information about a non-STREAMS event that just

occurred. To be able to retrieve additional information about specific
events, ret must point to an allocated data structure of type spmevent_t.
If ret is NULL, then no additional information about the specified event
is retrieved. For STREAMS events, the pointer must be set to NULL.
Points to the user-defined function that is automatically called when the
specified events occur. When func is called, the file descriptor of the
service endpoint where the event occurred is passed as an argument to the
user-defined function. Passing the file descriptor allows the function to
identify the service endpoint, which may not be known if
L_ANYSTREAM was used with this call.
Specifies the category of STREAMS or non-STREAMS events for which
the user-specified function at func is automatically called. eventsand
req->eventis constructed by bitwise OR-ing any combination of the
following flags:
S_INPUT: A message other than a high-priority message is at the
front of the streamhead read-side queue. This event is maintained for
compatibility reasons.
S_RDNORM: A non-priority message is at the front of the
streamhead read-side queue. Only non-expedited L_SS7MSG
1-1600-1003-01
SPM API Library
messages travel as non-priority messages. All other messages travel

as priority-band messages.
S_RDBAND: A priority-band message is at the front of the
streamhead read-side queue. All messages except non-expedited
L_SS7MSG messages travel as priority-band messages.
S_OUTPUT: A write-side queue used for non-priority messages is no
longer full. Room now exists on the write-side queue for sending
non-priority messages downstream.
S_WRNORM: Same as S_OUTPUT.
S_WRBAND: A write-side queue used for priority-band messages is
no longer full. Room now exists on the write-side queue for sending
priority-band messages downstream.
S_ERROR: An M_ERROR message reached the streamhead readside queue.
S_HANGUP: An M_HANGUP message reached the streamhead
read-side queue.
M_SHUTDOWN: The Distributed7 system software on one of the
host machines is being shut down. The req argument can be used to
specify a particular host. If req is NULL, then notification occurs
when any host machine in the network shuts down. If ret is not
NULL, then ret->data.shutdown.inetaddr identifies which host
caused the M_SHUTDOWN event.
M_DEV_LOCAL: A status change occurred in one of the SS7 boards
configured on the local host machine. This event indicates the
establishment or removal of one of the STREAMS connections
between the SPM and the device drivers for the individual SS7
boards on the local host machine. The req->data.dev.device field
identifies an SS7 board when notification is required for that
particular board. If req is NULL, then the application is notified
when the status changes on an SS7 board on the local host. If ret is
not NULL, then ret->data.dev.device identifies which SS7 board
caused the M_DEV_LOCAL event, and ret->data.dev.status holds
the boards status as L_ATTACHED or L_DETACHED.
M_DEV_REMOTE: A status change occurred in one of the SS7
boards configured on a remote host machine in a distributed
environment. This event indicates the establishment or removal of
one of the STREAMS connections between the SPM and the device
drivers for the individual SS7 boards on a remote machine. This
The req->data.dev.inetaddr and req->data.dev.device fields identify
a remote host and SS7 board if notification is required for that
particular board. If req is NULL, then the application is notified
Page 2 - 39
1-1600-1003-01
Page 2 - 40
SPM API Library
when the status changes for an SS7 board on a remote host. If ret is
not NULL, then ret->data.dev.inetaddr and ret->data.dev.device
identify which host and SS7 board has caused the
M_DEV_REMOTE event, and ret->data.dev.status holds the boards
status as L_ATTACHED or L_DETACHED.
M_DEV: A status change occurred in one of the SS7 boards
configured on one of the local or remote host machines of a
distributed environment. This event is constructed by bitwise OR-ing
M_DEV_LOCAL and M_DEV_REMOTE events.
The req->data.dev.inetaddr and req->data.dev.device fields identify
a host and SS7 board if notification is required for that particular
board. If req is NULL, then the application is notified when the status
changes for an SS7 board in the network. If ret is not NULL, then the
ret->data.dev.inetaddr and ret->data.dev.device identify which host
and SS7 board caused the M_DEV event, and ret->data.dev.status
holds the boards status as L_ATTACHED or L_DETACHED.
M_TCPIP: A status change occurred in one of the kernel-level TCP/
IP connections maintained between the individual host machines,
possibly as a result of establishing or removing a TCP/IP connection.
The req->data.tcpip.inetaddr[2] field identifies a particular TCP/IP
connection, i.e., i-net addresses, from which it receives notification if
req->data.tcpip.pad is initialized to zero. If req is NULL, then the
application is notified when the status changes for a TCP/IP
connection maintained between two host machines in the network. If
ret is not NULL, then ret->data.tcpip.inetaddr[2] identifies the i-net
addresses of the TCP/IP connection that caused the M_TCPIP event,
and ret->data.tcpip.status holds the connection status as
L_ESTABLISHED or L_REMOVED.
M_ENV_LOCAL: A change in operational environment occurred on
the local host machine. This event indicates a change in the contents
of the process table maintained on the local host machine. The change
may be due to the startup of a new process, the termination of an
existing process, or a change in the status, operation mode, or service
type of an executing process. The req->data.env.ipcaddr field
identifies a process if notification is required for that particular
process, and if req->data.env.pad is initialized to zero. If req is
NULL, then the application is notified when the status changes for a
process on the local host. If ret is not NULL, then
ret->data.env.ipcaddr identifies which process caused the
M_ENV_LOCAL event. The ret->data.env.srvtype, oprmode, and
usrstat fields hold service type, operation mode, i.e., L_ACTIVE and
L_STANDBY, and status, i.e., L_USR_OKAY, L_USR_BLKD, and
L_USR_NONE.
1-1600-1003-01
SPM API Library
M_ENV_REMOTE: A change in operational environment occurred

on a remote host machine of a distributed environment. This event
indicates a change in the contents of the process table maintained on
a remote machine. The change may be due to the startup of a new
process, the termination of an existing process, or a change in the
status, operation mode, or service type of an executing process. This
Only changes to globally registered processes cause an
M_ENV_REMOTE event. Changes in the status of locally registered
processes on remote host machines cannot be detected.
The req->data.env.ipcaddr field identifies a process if notification is
required for that particular process, and if req->data.env.pad is
initialized to zero. If req is NULL, then the application is notified
when the status changes for a process on a remote host. If ret is not
NULL, then ret->data.env.ipcaddr identifies which process caused
the M_ENV_REMOTE event. The ret->data.env.srvtype, oprmode,
and usrstat fields hold service type, operation mode, i.e., L_ACTIVE
and L_STANDBY, and status, i.e., L_USR_OKAY, L_USR_BLKD,
and L_USR_NONE.
M_ENV: A change in operational environment occurred on one of
the local or remote host machines of a distributed environment. The
change may be due to the startup of a new process, the termination of
an existing process, or a change in the status, operation mode, or
service type of an executing process. This event is constructed by
bitwise OR-ing M_ENV_LOCAL and M_ENV_REMOTE.
The req->data.env.ipcaddr field identifies a process if a notification
is required for that particular process, and if req->data.env.pad is
initialized to zero. If req is NULL, then the application is notified
when the status changes for a process in the network. If ret is not
NULL, then ret->data.env.ipcaddr identifies which process caused
the M_ENV event. The ret->data.env.srvtype, oprmode, and usrstat
fields hold service type, operation mode, i.e., L_ACTIVE and
L_STANDBY, and status, i.e., L_USR_OKAY, L_USR_BLKD, and
L_USR_NONE.
M_ALARM: An alarm event occurred on one of the host machines in
the network. This event is triggered by the ALM_MNGR daemon
process using spm_trigger(), and signifies the occurrence of an alarm
condition. The req->data.alarm.group, module, type, and severity
fields identify an alarm event if notification is required for that
particular alarm event. Group, module, and type specify the entire
alarm number that is defined in the Alarm Group Definition and
Alarm Text files. Severity can be L_SEVINFO, L_SEVMINOR,
L_SEVMAJOR, L_SEVCRITICAL, or L_SEVFATAL. If req is
NULL, then the applicatin is notified for all alarm events in the
Page 2 - 41
1-1600-1003-01
Page 2 - 42
SPM API Library
network. If ret is not NULL, then ret->data.alarm.inetaddr contains

the host that triggered the M_ALARM condition, and
ret->data.alarm.group, module, type, and severity identify the
specific alarm.
M_USR: A user-defined event occurred on one of the host machines
in the network. This event is triggered by an application program
using spm_trigger(), and signifies the occurrence of an event for
which the meaning and importance are application-specific.
The req->data.usr.number field identifies a user-defined event
number if notification is required for that single user-defined event. If
req is NULL, then, depending on the scope defined for the event, the
application is notified for all user-defined events on the local host, or
across the network. If ret is not NULL, then ret->data.usr.scope
contains the event scope, i.e., L_LOCALSCOPE and
L_GLOBALSCOPE, ret->data.usr.number contains the event
number, and ret->data.usr.info holds event information about the
M_USR event.
M_SYS: A system event occurred on one of the host machines in the
network. System events report fault conditions to application
programs. The faults occur during operation of Distributed7 system
software. When they are detected, the system software automatically
notifies all appropriate processes. By default, the affected processes
de-register and close the associated endpoints. An example is the
violation of network-based exclusive registration rules that guarantee
that a process registered with a platform in the network-exclusive
mode is unique. Such an event is probably the result of heartbeat loss
across kernel-level TCP/IP interfaces between one or more host
machines, or from LAN hardware/software problems, i.e.,
partitioning LAN into multiple segments. Application programs can
elect to overwrite the default system response by running
spm_notify() to detect L_NONEXCLUSIVE system events, and then
specifying their own functions.
M_QUEUE: A queue management event occurred. Queue
management events are generated by the system to indicate a buildup in the applications read-side STREAMS queues, or that incoming
messages buffered by the system are out-of-date. When such events
occur, Distributed7 takes appropriate action, as described in
spm_setqparams() on page 2-53. Application programs need to run
spm_notify() well in advance to detect M_QUEUE events and
process them.
The req->data.queue.reason field identifies a particular set of queue
management events. If req is NULL, then all queue management
events are detected. If ret is not NULL, then ret->data.queue.reason
holds the queue management event, i.e., L_HIGHMARK,
L_LOWQSIZE, L_MAXQSIZE, L_LOWQTIME, or
1-1600-1003-01
SPM API Library
L_MAXQTIME, and ret->data.queue.action holds the action that

the system took, i.e., L_DISCARDED or L_FLOWCNTLD.
M_ALL: A non-STREAMS related event occurred. This event is
constructed by bitwise OR-ing all non-STREAMS events, i.e., those
starting with M_ listed in this section.
A previously placed spm_notify() request can be cancelled by calling the function again
with the same values for the events and req arguments, but with a NULL func argument.
Calling the function with events specified and NULL req and func arguments cancels all
formerly placed spm_notify() requests for the specified events.
A request can be modified, such as function called, by running spm_notify() with the
same req argument value as in the initial request, but with the new func argument.
Important: The Distributed7 environment uses high-priority [M_PCPROTO] messages
internally for providing optional acknowledgments to user application messages sent using
the spm_snd() function. Therefore, application programs cannot specify the S_HIPRI event
when calling this function.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it. For non-STREAMS events other than
M_SHUTDOWN, it is required that an address is bound to all
appropriate endpoints associated with the user process
prior to calling the spm_notify() function.
<ENOMEM>::Unable to register the user-specified event due to lack
of memory space.
<EINTR>::A signal was caught during the I_SETSIG or I_PEEK
2ioctl(2) function.
SEE ALSO spm_trigger()
2.2.25 spm_open()
DESCRIPTION
spm_open()
Establishes a service endpoint. The function call opens a special
file that identifies a particular service provider and returns a file descriptor that identifies
the service endpoint. This function is the first step in the initialization of a service
endpoint under the Distributed7 environment. The file descriptor (fd) returned by this call
is used by all subsequent functions that have a need to identify the particular service
endpoint.
Page 2 - 43
1-1600-1003-01
SPM API Library
Multiple service endpoints may be initiated by a single user process in the Distributed7
architecture by issuing multiple spm_open() calls. The user process can establish multiple
connections to a single service provider. It is also possible for a user process to establish
concurrent connections to several different service providers.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_open(const char *path, int oflag, spmopen_t *req);
path
Points to a user buffer that holds the identity of the service provider, i.e.,
the functional SS7 protocol layer, for the endpoint. Valid values are:
SPM_DEV - Indicates that the service endpoint is not associated with
a specific signaling point (SP) and is not intended to perform SS7related tasks. Since the user is not an SS7 user, it can only use the
non-SS7 capabilities offered by the platform.
UPM_DEV - Indicates that the service endpoint is associated with the
Message Transfer Part (MTP) Layer 3 protocol for a specific SP. The
user may or may not be an SS7 user. If the user is an SS7 user, MTP
Signaling Message Handling (SMH) related tasks may be performed.
SCCP_DEV - Indicates that the service endpoint is associated with
the Signaling Connection Control Part (SCCP) protocol for a specific
SP. The user may or may not be an SS7 user. If the user is an SS7
user, the connectionless or connection-oriented transport services
provided by the SCCP protocol layer may be used.
TCAP_DEV - Indicates that the service endpoint is associated with
the Transaction Capabilities Application Part (TCAP) protocol based
on either SCCP or TCP/IP transport services. To use TCAP_DEV
services, the tcm_open() function must be called.
These macros are defined in the api_macro.h header file.
oflag
Identifies any open flagsas in open(2)and may be constructed from
either the O_NDELAY or O_NONBLOCK flags ORed bitwise with the
O_RDWR flag. These flags are defined in the fcntl.h header file.
req
Points to the spmopen_t structure. For all service providers except
SPM_DEV, the user must specify the SP number, the MTP user part
number, and, in some cases, the SCCP subsystem number with which the
end point is associated. The spmopen_t structure contains the following
elements:
word_t sp; /*signaling point number */
word_t up; /*MTP user part number */
word_t ssn; /*SCCP subsystem number */
word_t opt; /* device options [for TCAP only] */
Page 2 - 44
1-1600-1003-01
SPM API Library
For endpoints established at UPM_DEV and SCCP_DEV, the req->sp

and other fields must be filled in as described below:
UPM_DEV - The req->up field must have an appropriate MTP user
part number other than 3. User part 3 is reserved for the SCCP
protocol layer.
SCCP_DEV - The req->up field must contain 3 since the SCCP is an
MTP user, i.e., user part 3 per SS7 protocol specifications. The ssn
field must be set to 0.
For endpoints established at SPM_DEV, the req argument must be set to
NULL.
Note: Normally, the tcm_open() function should be used when registering a TCAP
application. The tcm_open() call uses the spm_open() call, but performs other functions
automatically, such as allocating TCAP resources, that would not be done by the
spm_open() call.
RETURN VALUES
file descriptor
-1
On success.
ERRORS
<EMFILE>::There are no more file descriptors available.
<EINTR>::A signal was caught during processing of during
processing of the user request.
SEE ALSO spm_bind(), spm_close(), tcm_open()
2.2.26 spm_palarm()
DESCRIPTION
spm_palarm()
Generates a user-specified alarm condition by populating and
sending an IPC message to the Distributed7 platform alarm handler process,
ALM_MNGR, if it is active. This call provides the user more control in specifying the
alarm condition than spm_alarm(). The message is sent via the first service endpoint that
was established by the user process with the spm_open() function. The function adds
other information, such as date and time stamps, to the supplied information and sends the
message as a normal (non-expedited) IPC message.
MT LEVEL
MT-Safe
Page 2 - 45
1-1600-1003-01
SPM API Library
SYNOPSIS
int spm_palarm(byte_t level, byte_t grpid, byte_t modid, byte_t type, int par1,
int par2, char *buf);
level
Specifies the severity of the generated alarm. The severity level must be
one of the following:
L_ALMLVL_INFO
for INFORMATIONAL
grpid, modid, type

Specify the group ID (grpid), module ID (modid), and alarm
number (type) of the full alarm identification number, similar to the
system alarms listed in the Maintenance Manual. The type argument is
equivalent to byte 0 (LSB) of spm_alarm()s type argument. Similarly,
grpid is equivalent to byte 2 and modid is equivalent to byte 3 of that
argument. User-defined alarms must be previously defined with the
Group IDs in the Alarm Group Definition file and the module IDs and
text definitions in an Alarm Text file (see the User Interface Manual and
the Maintenance Manual for more details).
par1 and par2 Specify the optional parameters that should be used when populating the
message.
buf
Points to a user buffer containing a null-terminated character string of
alarm text which overwrites the default alarm text message. The string is
copied to the data portion of the IPC message. If the argument passes
null, then the default alarm text from the Alarm Text file will be used by
the ALM_MNGR process.
RETURN VALUES
0
-1
On success.
ERRORS
Page 2 - 46
1-1600-1003-01
SPM API Library
SEE ALSO spm_alarm()
2.2.27 spm_perror()
DESCRIPTION
spm_perror()
Prints the last error encountered during an Distributed7 API
library call to the standard error output.
MT LEVEL
MT-Safe
SYNOPSIS
void spm_perror(const char *str);
str
Points to an optional user-supplied string which can be used to provide
context to the error. (To be of most use, the argument string should
include the name of the program that incurred the error.)
The format of error messages generated by the this function is as follows:
str@pid(id): [err] one-line of error text
The id is the UNIX process ID of the process that incurred the error and
err contains the current value of the external errno variable. A one-line
description of the error follows. If str of this call points to a null string, a
value of spmerr is substituted for the variable str in the above error
message.
Distributed7 software, refer to the api_errno.h header file.
SEE ALSO spm_strerror()
2.2.28 spm_rcv()
DESCRIPTION
spm_rcv()
Retrieves application messages through an Distributed7 service
endpoint. In addition to receiving messages, spm_rcv() performs three other functions
automatically:
Acknowledges the receipt of a message, if an acknowledgment is requested by the
message sender. Acknowledgment messages are high-priority STREAMS messages.
Before sending the acknowledgment, spm_rcv() checks the current system time to see
whether the acknowledgment is already late and checks whether the sender is still alive.
If it is late, the call fails with an ELATEMSG error, but the contents of the message
retrieved will still be valid and copied to msgp. If the message sender is not alive, the
acknowledgment message will be discarded and the spm_rcv() call will succeed.
Page 2 - 47
1-1600-1003-01
SPM API Library
Detects internal events and takes appropriate action. This action consists of invoking a
user-specified event handler function, i.e., specified earlier using the spm_notify()
function.
Responds to heartbeat request messages from the apmd daemon. The function
responds with an appropriate heartbeat response message, eliminating the need for an
application program to differentiate between heartbeat request messages and respond
with correctly populated heartbeat response messages.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_rcv(int fd, ipcmsg_t *msgp, size_t nbytes, int timeout, int *flags);
fd
Identifies the service endpoint through which to receive the messages. If
the user process has multiple endpoints established, the fd argument can
be set to L_ANYSTREAM to allow the message to be retrieved through
any of the endpoints that are currently active. This capability eliminates
the need for the user process to periodically poll each endpoint.
msgp
Points to an ipcmsg_t user buffer that will hold the message. After return
from the call, the buffer can be parsed. The message type is in msgp>msghdr.msgtyp, the message size is in msgp->msghdr.msize, and the
data is in msgp->data. The address of the sending process is found in
msgp->msghdr.orig.
nbytes
Specifies the maximum size of the message, in bytes. The message will
be truncated to nbytes bytes, if it is larger than nbytes. The truncated part
of the message is lost and no indication of truncation is given to the
calling process.
Important: The user space buffer pointed to by msgp must contain at least nbytes of storage
space to be able to hold the contents of the retrieved message.
timeout
flags
Page 2 - 48
Specifies the amount of time to wait for an incoming message, of the type
specified with flags, if one is not present. The timeout values are as
follows:
L_WAIT: the call will wait indefinitely for a message, unless it is
interrupted by a UNIX signal.
L_NOWAIT: the call will immediately return if no messages exist
(with an error of ENOMSG).
length of time for a message before returning.
Points to a user buffer that must provide the message type to be retrieved
at the specified endpoint. On return from the call, it will also hold the
1-1600-1003-01
SPM API Library
actual message type. To set flags, one of the first three valid flag values
described in the following list must be used. The L_EXPEDITED flag
can be ORed with one of them to specify an expedited message.
L_IPCMSG: Retrieve the first available IPC message.
L_SS7MSG: Retrieve the first available SS7 message.
L_ANYMSG: Retrieve the first available message, regardless of its
type.
L_EXPEDITED: Retrieve the first available expedited message of
the specified type.
On return from the call, the flags field will be populated by the system to
hold the actual type of the message retrieved and whether the message
retrieved is a normal or an expedited message. The bits of the field will
be set as follows:
Bit 0 (L_EXPEDITED) will be set if the message is expedited.
Bit 2 (L_IPCMSG) will be set for an IPC message.
Bit 3 (L_SS7MSG) will be set for an SS7 message.
This selective message retrieval capability has some limitations. Setting
the flags argument to a certain combination of flags only guarantees that
a message at a priority level that is equivalent or higher than the specified
value will be retrieved. Even though an application only wants to receive
messages at a particular priority level, it may still receive messages with
higher priority levels but not lower ones. Therefore, application
programs must always check the flags value on return from the call to
find out the exact message type so it can decide whether to handle a
message that has a higher priority than the desired priority level. See
spm_snd() on page 2-56 for more information about the priority levels
used by different types of messages.
RETURN VALUES
# of bytes receivedOn success. (Header and data portions)
-1
ERRORS
<EBADF>::An fd value of L_ANYSTREAM is supplied but there are no
endpoints established currently.
associated with it.
<ETIME>::Unable to retrieve message since no messages of desired
type have arrived within timeout milliseconds. This is
also known as a timeout condition.
Page 2 - 49
1-1600-1003-01
SPM API Library
<ENOMSG>::Unable to retrieve message since no messages of desired

type are readily available and a timeout value of L_NOWAIT
is specified.
<ELATEMSG>::Unable to acknowledge message retrieved on time. The
contents of the message retrieved will still be copied to
the user buffer pointed to by the msgp argument.
request.
SEE ALSO spm_snd()
2.2.29 spm_sethiwat()
DESCRIPTION
spm_sethiwat()
Changes the default high water mark for a priority band at a
MT LEVEL
MT-Safe
SYNOPSIS
int spm_sethiwat(int fd, unsigned long value, int flags);
fd
value
Holds the new water mark setting, in bytes.
flags
Specifies the priority band of the new settings. (Either L_SS7MSG or
RETURN VALUES
0
-1
Page 2 - 50
On success.
1-1600-1003-01
SPM API Library
ERRORS
associated with it.
2.2.30 spm_setlowat()
DESCRIPTION
spm_setlowat()
Changes the default low water mark for a priority band at a
MT LEVEL
MT-Safe
SYNOPSIS
int spm_setlowat(int fd, unsigned long value, int flags);
fd
value
Holds the new water mark setting, in bytes.
flags
Specifies the priority band of the new settings. (Either L_SS7MSG or
RETURN VALUES
0
-1
On success.
ERRORS
Page 2 - 51
1-1600-1003-01
SPM API Library

associated with it.
2.2.31 spm_setoprmode()
DESCRIPTION
spm_setoprmode()
environment.
Updates the operation mode of a user process in the Distributed7
MT LEVEL
MT-Safe
SYNOPSIS
int spm_setoprmode(int fd, int mode);
fd
Identifies the service endpoint associated with the user process.
mode
Holds the new operation mode of the process. Valid values are:
messages.
the message is specified in the L_IPCKEY format by the message
originator.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
<ESRCH>::Unable to locate the process table entry for the user
process associated with the specified service endpoint.
Page 2 - 52
1-1600-1003-01
SPM API Library
SEE ALSO spm_setusrinfo()
2.2.32 spm_setqparams()
DESCRIPTION
spm_setqparams()
Manipulates the queue management parameters for handling
messages buffered by the system in the STREAMS multiplexer's upper read-side queue
that is associated with the calling application. This queue is used to buffer messages when
the number of messages accumulated on the applications streamhead read-side queue has
reached its high water mark.
Buffering on the multiplexers queue puts a load on STREAMS resources and long-term
buffering can result in system-wide performance degradation.
Note: Settings for the applications streamhead read-side queue are changed with the
spm_setlowat() and spm_sethiwat() calls.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_setqparams(int fd, spmqparams_t *req);
fd
Identifies the service endpoint. The value is returned by the spm_open()
call.
req
Points to the structure containing the queue management data. This
structure is spmqparams_t and is defined in api.h with the following
fields:
int low_qsize;
int max_qsize;
int low_qtime;
int max_qtime;
The req-> low_qsize field holds the number of buffered messages which
must be exceeded to trigger an M_QUEUE event to the application. The
event indicates that the queue is getting full. The event is only triggered
if an spm_notify() call was made by the application for this event. This
type of notification can be used to activate a user-defined flow control
mechanism to prevent the message build-up. A value of L_INFQSIZE
indicates that no warning is required.The default value is
L_DEF_LOWQSIZE.
The req-> max_qsize field holds the number of buffered messages which
must be exceeded to cause the system to discard new messages. An
M_QUEUE event will be triggered for each discarded message if an
spm_notify() call was made by the application for this event. If the call
was not made, the application will not know messages are being
Page 2 - 53
1-1600-1003-01
SPM API Library
discarded. A value of L_INFQSIZE indicates that messages should never

be discarded. The default value is L_DEF_MAXQSIZE.
The req-> loq_qtime field is set if the application should be notified that
the message about to be placed from the multiplexer queue to the
streamhead queue may be to old. The field is the length of storage time. If
the message has been buffered for longer than the value of this field and
an spm_notify() call was made by the application for an M_QUEUE
event, then the event will be triggered just before the message is placed
on the streamhead queue. A value of L_INFQSIZE indicates that no
warning is required, which is the default.
The req-> max_qtime field holds the maximum storage time for a
message on the multiplexer queue. When a message is ready to go from
the multiplexer queue to the streamhead queue, the system checks the
length of time that the message has been buffered. If the message has
been buffered for longer than the value of this field and an spm_notify()
call was made by the application for an M_QUEUE event, then the
message will be discarded and the event will be triggered. If the
spm_notify() call was not made, the application will not know messages
are being discarded. A value of L_INFQSIZE indicates that no messages
will be discarded due to age, which is the default.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
SEE ALSO spm_notify(), spm_sethiwat(), spm_setlowat()
2.2.33 spm_setsrvtype()
DESCRIPTION
spm_setsrvtype()
environment.
Updates the service type of a user process in the Distributed7
MT LEVEL
MT-Safe
Page 2 - 54
1-1600-1003-01
SPM API Library
SYNOPSIS
int spm_setsrvtype(int fd, int srvtyp);
fd
srvtyp
Specifies the new service type and can be L_MTP or L_SCCP, as defined
in api.h.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
SEE ALSO spm_setusrinfo()
2.2.34 spm_setusrinfo()
DESCRIPTION
spm_setusrinfo()
Updates both the service type and operation mode of a user
process in the Distributed7 environment. This information was specified during the
spm_bind() request.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_setusrinfo(int fd, spmuser_t *user);
fd
user
Points to the spmuser_t structure which must be filled in appropriately.
The structure has the following fields:
ipcaddr_t ipcaddr; /*populated internally*/
time_t regtime; /*used in spm_getusrinfo()*/
word_t srvtyp; /*service type*/
word_t status; /*used in spm_getusrinfo()*/
word_t flags; /*operation mode*/
The user->srvtyp field must be populated by the user. It specifies the
services that are expected to be provided to the user process by the
Page 2 - 55
1-1600-1003-01
SPM API Library
Distributed7 platform. Valid values are L_MTP or L_SCCP as defined in

api.h.
The user->flags field must be populated with a valid operation mode for
the process. Valid values, as described in spm_bind(), are:
messages.
the message is specified in the L_IPCKEY format by the message
originator.
The operation mode and service type can also be updated individually
with the function calls, spm_setoprmode() and spm_setsrvtype(),
respectively.
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
2.2.35 spm_snd()
DESCRIPTION
spm_snd()
Sends a user-specified message through an Distributed7 service
endpoint. Before sending the message, this function verifies that the destination is
registered with Distributed7 and in an unblocked state. This verification prevents an
unattended message queue from being flooded with messages.
These checks can be bypassed by setting the L_NOCHECK flag. This approach improves
the performance of the spm_snd() function call, however, failures do not occur when an
attempt is made to send a message to a non-existing destination. Therefore, some other
method should be used to ensure that the destination exists and is not in a blocked state
prior to using the spm_snd() function with this flag set.
MT LEVEL
MT-Safe
Page 2 - 56
1-1600-1003-01
SPM API Library
SYNOPSIS
int spm_snd(int fd, ipcmsg_t *msgp, size_t nbytes, int acktime, int flags);
fd
Specifies the service endpoint to send the message through. The fd value
for the service endpoint was returned by spm_open().
msgp
Points to the buffer containing the IPC message. The user data is placed
in the msgp->data field. The destination field (msgp->msghdr.dest) must
be populated. The origination field (msgp->msghdr.orig) must uniquely
identify the calling process.
nbytes
Specifies the size, in bytes, of the data portion of the message. This
parameter will be copied into the msgp->msghdr.msize field. The
EMSGSIZE error will be returned if the value is too large.
acktime
Specifies whether an acknowledgment message should be requested
from the destination and the length of time to wait for it.
(Acknowledgment messages confirm that the destination received the
sent message.) Valid values are:
L_WAIT: the call waits indefinitely, i.e., blocks until
acknowledgment is received
L_NOWAIT: the call immediately returns after the delivery of the
message (no acknowledgment requested).
length of time for an acknowledgment before returning. If the time
limit expires, the call will fail with an ETIME error.
flags
Identifies the type of message to be sent, and whether the message should
be sent as a normal or an expedited message. The flags field is
constructed by OR-ing message type with delivery type from the
following list (either L_IPCMSG or L_SS7MSG must be present):
L_IPCMSG: Send message as an IPC message. The default priority
is 1 unless L_EXPEDITED is also set.
L_SS7MSG: Send message as an SS7 message. The default priority
L_EXPEDITED: Send message of the specified type as an expedited
message. With this flag set, an L_IPCMSG message will be sent with
priority 4 and an L_SS7MSG message will be sent with priority 3.
L_NOCHECK: Bypass checks for the validity/availability of the
destination address before sending the message.
Sending a message in an expedited manner allows a user process to
originate application-specific out-of-band messages that signify the
occurrence of certain events. Processes can retrieve normal and/or
expedited messages in a selective manner using the spm_rcv() function
call.
Note: A named object application registered to the SPM mutltiplexor [selected SPM_DEV
in spm_open()] cannot send an SS7 message, so it should never set flags to L_SS7MSG.
Page 2 - 57
1-1600-1003-01
SPM API Library
RETURN VALUES
0
-1
On success.
ERRORS
associated with it.
user data that can be included as part of an L_IPCMSG or
an L_SS7MSG message is controlled by the L_IPCDATASIZE and
L_MSUDATASIZE parameter settings on the system.
process.
instance.
<ETIME>::Unable to receive acknowledgment from destination within
specified time.
<EMSGNAK>::An invalid acknowledgment is received.
request.
SEE ALSO spm_rcv()
2.2.36 spm_strerror()
DESCRIPTION
spm_strerror()
number.
Retrieves the Distributed7 error message of the given error
MT LEVEL
MT-Safe
Page 2 - 58
1-1600-1003-01
SPM API Library
SYNOPSIS
char *spm_strerror(int errnum);
errnum
Specifies the error number.
This function uses the identical set of error messages as spm_perror().
Distributed7 software components, refer to the api_errno.h header file.
RETURN VALUES
pointer to string
On success. The string is the error message associated with the

provided error number. The returned error message string should not be
overwritten.
The function behaves identically to strerror(3C) for error numbers that are not meaningful
to the Distributed7 software.
SEE ALSO strerror(3C), spm_perror()
2.2.37 spm_trestart()
DESCRIPTION
spm_trestart()
Stops and restarts an unexpired deferred message timer that was
previously set up through the fd service endpoint with the spm_tstart() call.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_trestart(int fd, int tid, int time);
tid
Specifies the timer ID to be restarted. It was obtained from the return
value of the spm_tstart() call. The timer is restarted with this same timer
id.
time
Identifies the new time interval, in milliseconds, that should pass before
the message is sent. If the time argument is set to , then the message is
delivered immediately.
RETURN VALUES
0
-1
On success.
On failure.
ERRORS
associated with it.
Page 2 - 59
1-1600-1003-01
SPM API Library

L_SS7MSG message is set by the L_IPCDATASIZE and
L_MSUDATASIZE system parameters respectively.
process.
instance.
<EINVTID>::The timer ID specified is invalid.
<ENOTID>::No timer is currently available.
<ENOSR>::Unable to allocate kernel-level STREAMS buffers to copy
the contents of the user-specified message.
<ENOMEM>::Unable to copy the contents of the user-specified
message to the kernel-level STREAMS buffers allocated.
<EAGAIN>::Unable to schedule a request to send message in the
deferred mode. The timer ID as well as the kernel-level
STREAMS buffers allocated will be freed.
SEE ALSO spm_tstart()
2.2.38 spm_tretrieve()
DESCRIPTION
spm_tretrieve()
Cancels a deferred message timer request that was previously set
up through a particular service endpoint with the spm_tstart() call and optionally retrieves
the message contents for the user process. The message is not sent to the destination.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_tretrieve(int fd, int tid, ipcmsg_t *msgp);
fd
Identifies the service endpoint that the timer was set through.
tid
Identifies the timer ID to be cancelled. It was obtained from the return
value of the spm_tstart() call.
msgp
Points to an ipcmsg_t structure in user space that should hold the
message that will be retrieved from the kernel space. If msgp is NULL,
the timer will be cancelled and the message will not be retrieved.
Page 2 - 60
1-1600-1003-01
SPM API Library
RETURN VALUES
message size
-1
On success.
On failure.
ERRORS
associated with it.
SEE ALSO spm_tstop(), spm_tstart()
2.2.39 spm_trigger()
DESCRIPTION
spm_trigger()
Generates a user-specified event out through a service endpoint.
The user process must be operating under the Distributed7 environment. The generated
events are automatically detected by other applications that have used spm_notify() to
request notification of these events.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_trigger(int fd, spmevent_t *req);
fd
Identifies the service endpoint to send the event through.
req
Points to an spmevent_t data structure which contains the type and
specific data of the event to be generated. Any unused fields must be
zeroed out. The spmevent_t structure contains the following members:
union {
struct e_dev dev;
struct e_env env;
struct e_usr usr;
struct e_sys sys;
} data;
Page 2 - 61
1-1600-1003-01
SPM API Library
The req->event field can only contain M_ALARM or M_USR. They are
described below:
M_ALARM: Signifies generation of a local alarm event. The details
of the M_ALARM event must be defined in req->data.alarm
(e_alarm structure). The e_alarm structure contains the following
members:
dword_t inetaddr; /* i-net address associated */
byte_t group; /* group number */
byte_t module; /* module number */
byte_t type; /* alarm type */
byte_t severity; /* severity (bit-mask) */
The req->data.alarm.inetaddr field identifies the host associated
with the alarm. The req->data.alarm.group, module, type, and
severity fields respectively identify the group number, module
number, type, and severity level of the alarm condition. Group,
module, and type specify the entire alarm number that is defined in
the Alarm Group Definition and Alarm Text files. Severity can be
L_SEVINFO, L_SEVMINOR, L_SEVMAJOR, L_SEVCRITICAL,
or L_SEVFATAL. If any portions of the e_alarm structure are
unused, they must be initialized to zeros prior to issuing this call.
M_USR: Signifies generation of an application-specific event. The
details of the M_USR event must be defined in req->data.usr (e_usr
structure). The e_usr structure contains the following members:
long scope;
/* event scope */
long number;
/* event number */
char info[MAXINLEN]; /* event-specific info */
The req->data.usr.scope field identifies the events scope, on the
local host (L_LOCALSCOPE) or across the network
(L_GLOBALSCOPE). The req->data.usr.number field identifies the
user-defined event number. (Event numbers above the
L_MAX_USR_EVENT value are reserved for internal use only.) The
req->data.usr.info array contains any additional event-specific
information. (The maximum size of the array is 24 elements.) If any
portions of the e_usr structure are unused, they must be initialized to
zeros prior to issuing this call.
RETURN VALUES
0
-1
On success.
On failure.
ERRORS
associated with it.
Page 2 - 62
1-1600-1003-01
SPM API Library
SEE ALSO spm_notify()
2.2.40 spm_tstart()
DESCRIPTION
spm_tstart()
Starts a timer for deferred message delivery. This call is a kernellevel request to schedule a user-defined message to be sent through a service endpoint
after a specific time interval. The function copies the message from the buffer into kernel
space, starts a kernel-level timer, and returns the timers ID to the user process. The
message will be sent from the kernel space when the timer expires, so the user buffer is
free for use. After expiration, the timer ID will be reused by the system.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_tstart(int fd, ipcmsg_t *msgp, size_t nbytes, int time, int flags);
fd
Identifies the service endpoint that the deferred message should be sent
through.
msgp
Points to the buffer containing the IPC message. The user data is placed
in the msgp->data field. The destination field (msgp->msghdr.dest) must
be populated. The origination field (msgp->msghdr.orig) must uniquely
identify the calling process.
nbytes
Specifies the size, in bytes, of the data portion of the message. This
parameter will be copied into the msgp->msghdr.msize field. The
EMSGSIZE error will be returned if the value is too large.
time
Specifies the duration of the timer in milliseconds. If the time argument
is set to 0, the message will be delivered immediately.
The timing accuracy of the deferred messaging capability is controlled
by a system parameter which specifies the number of clock ticks per
second. Currently, this setting is equal to 100 ticks/sec - meaning that the
deferred messaging capability only has a 10 millisecond resolution.
Therefore, specifying a time value of less than 10 will result in a message
being sent immediately (as if 0 had been specified).
flags
Identifies the type of message to be sent, and whether the message should
be sent as a normal or an expedited message. The flags field is
constructed by OR-ing message type with delivery type from the
following list (either L_IPCMSG or L_SS7MSG must be present):
L_IPCMSG: Send message as an IPC message. The default priority
L_SS7MSG: Send message as an SS7 message. The default priority
Page 2 - 63
1-1600-1003-01
SPM API Library
L_EXPEDITED: Send message of the specified type as an expedited

message. With this flag set, an L_IPCMSG message will be sent with
priority 4 and an L_SS7MSG message will be sent with priority 3.
RETURN VALUES
timer id
-1
On success (from 0 to NMAXTIMERS - 1).

On failure.
ERRORS
associated with it.
L_SS7MSG message is controlled by the L_IPCDATASIZE and
L_MSUDATASIZE parameter settings on the system,
respectively.
process.
instance.
<ENOTID>::No timer is currently available.
<ENOMEM>::Unable to copy the contents of the user-specified
message to the kernel-level STREAMS buffers allocated.
<EAGAIN>::Unable to schedule a request to send message in the
deferred mode. The timer ID as well as the kernel-level
STREAMS buffers allocated will be freed.
SEE ALSO spm_snd(), spm_tstop(), spm_trestart()
2.2.41 spm_tstop()
DESCRIPTION
spm_tstop()
Cancels a deferred message timer request that was previously set
up through a certain service endpoint with the spm_tstart() call. The message is deleted
from the kernel buffer. It is not sent to the destination or retrieved for the user process.
Page 2 - 64
1-1600-1003-01
SPM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int spm_tstop(int fd, int tid);
fd
Identifies the service endpoint that the timer was set up through.
tid
Specifies the timer ID to be cancelled. It was obtained from the return
value of the spm_tstart() call.
RETURN VALUES
0
-1
On success.
On failure.
ERRORS
associated with it.
SEE ALSO spm_tretrieve(), spm_tstart()
2.2.42 spm_unbind()
DESCRIPTION
spm_unbind()
Deactivates a service endpoint by unbinding the address that was
bound to it with the spm_bind() function. Upon successful completion of this call, the user
process associated with the service endpoint can no longer exchange messages or use the
Distributed7 message logging and message loopback capabilities. Any memory resources
previously allocated will be freed (e.g. resources allocated with spm_notify() and used to
store event-specific information).
MT LEVEL
MT-Safe
SYNOPSIS
int spm_unbind(int fd);
fd
Identifies the service endpoint that should be deactivated.
Page 2 - 65
1-1600-1003-01
SPM API Library
RETURN VALUES
0
-1
On success.
On failure.
ERRORS
<ENBOUND>::The specified endpoint does not have an address
associated with it.
<EAGAIN>::An internal error has occurred during processing of the
user request.
<ESYSDOWN>::Unable to service user request since system software
is in the process of being shutdown.
SEE ALSO spm_bind(), spm_close()
2.2.43 spm_xlate_ipckey()
DESCRIPTION
spm_xlate_ipckey()
Converts between oldRelease 3.4.xand new Distributed7
IPCkey data structures. The function converts data in an IPCkey_t structure to the
ipckey_t structure, or vice versa. The new ipckey_t structure was created to hold
additional fields that support the distributed architecture.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_xlate_ipckey(int cmd, IPCkey_t *IPCkey, ipckey_t *ipckey);
cmd
Specifies which direction the conversion is to take place. A value of
L_OLD2NEW means a conversion from IPCkey_t to ipckey_t
(Distributed7) occurs. A value of L_NEW2OLD means Release 3.4.x
data in ipckey_t will be converted to IPCkey_t.
IPCkey
Points to the IPCkey_t structure that either contains the data to be
converted (if cmd=L_OLD2NEW) or is the destination of data that will
be converted from ipckey_t (if cmd=L_NEW2OLD).
ipckey
Points to the ipckey_t structure that either is the destination of data to be
converted from IPCkey_t (if cmd=L_OLD2NEW) or contains the source
of data to be converted (if cmd=L_NEW2OLD).
RETURN VALUES
0
-1
Page 2 - 66
On success.
On failure.
1-1600-1003-01
SPM API Library
2.2.44 spm_xlate_ipcaddr()
DESCRIPTION
spm_xlate_ipcaddr() Converts between old and new (Distributed7) IPC address data
structures. The function converts data in an IPCaddr_t structure to the ipcaddr_t
structure, or vice versa. The new ipcaddr_t structure was created to hold additional fields
which support the distributed architecture.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_xlate_ipcaddr(int cmd, IPCaddr_t *IPCaddr, ipcaddr_t *ipcaddr);
cmd
L_OLD2NEW means a conversion from IPCaddr_t to ipcaddr_t
(Distributed7) occurs. A value of L_NEW2OLD means Distributed7
data in ipcaddr_t is converted to IPCaddr_t.
IPCaddr
Points to the IPCaddr_t structure that either contains the data to be
be converted from ipcaddr_t (if cmd=L_NEW2OLD).
ipcaddr
Points to the ipcaddr_t structure that either is the destination of data to
be converted from IPCaddr_t (if cmd=L_OLD2NEW) or contains the
source of data to be converted (if cmd=L_NEW2OLD).
RETURN VALUES
0
-1
On success.
On failure.
2.2.45 spm_xlate_ipcmsg()
DESCRIPTION
spm_xlate_ipcmsg() Converts between old and new Distributed7 IPC message data
structures. The function converts data in an IPCmsg_t structure to the ipcmsg_t structure,
or vice versa. The new ipcmsg_t structure was created to hold additional fields which
support the distributed architecture.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_xlate_ipcmsg(int cmd, ipcmsg_t *IPCmsg, ipcmsg_t *ipcmsg);
Page 2 - 67
1-1600-1003-01
cmd
IPCmsg
ipcmsg
SPM API Library

L_OLD2NEW means a conversion from IPCmsg_t to ipcmsg_t
(Distributed7) occurs. A value of L_NEW2OLD means Distributed7 data
in ipcmsg_t is converted to IPCmsg_t.
Points to the IPCmsg_t structure that either contains the data to be
be converted from ipcmsg_t (if cmd=L_NEW2OLD).
Points to the ipcmsg_t structure that either is the destination of data to be
converted from IPCmsg_t (if cmd=L_OLD2NEW) or contains the
RETURN VALUES
0
-1
On success.
On failure.
2.2.46 spm_xlate_reginfo()
DESCRIPTION
spm_xlate_reginfo() Converts between old and new (Distributed7) registration data
structures. The function converts data in an SPMreg_t structure to the spmbind_t
structure, or vice versa. The new spmbind_t structure was created to hold additional
fields which support the distributed architecture.
MT LEVEL
MT-Safe
SYNOPSIS
int spm_xlate_reginfo(int cmd, SPMreg_t *SPMreg, spmbind_t *spmbind);
cmd
L_OLD2NEW means a conversion from SPMreg_t to spmbind_t
(Distributed7) is occur. A value of L_NEW2OLD means Distributed7
data in spmbind_t is converted to SPMreg_t.
SPMreg
Points to the SPMreg_t structure that either contains the data to be
be converted from spmbind_t (if cmd=L_NEW2OLD).
spmbind
Points to the spmbind_t structure that either is the destination of data to
be converted from SPMreg_t (if cmd=L_OLD2NEW) or contains the
RETURN VALUES
0
Page 2 - 68
On success.
1-1600-1003-01
-1
SPM API Library
On failure.
Page 2 - 69
1-1600-1003-01
2.3
Network Extensions to SPM API Library

Distributed7 SPM API Library contains a small set of functions that allow distributed
applications to obtain the Internet Protocol (IP) address of a specified host. These functions
are collectively referred to as the Network Extensions to the SPM API Library; however,
they are packaged separately as part of the libinet.a library.
Applications interested in using these functions should be compiled/linked as follows:
cc file.c-I $EBSHOME/access/include
-L $EBSHOME/access/lib -lspm -linet -nsl
Important: All functions listed here are multi-thread (MT) Safe with the exception of
spm_inet_ntoa() and spm_inet_host. These two functions use static internal storage that
gets reused in each call, and this makes them unsafe for use in multi-threaded application
progarms.
2.3.1
spm_inet_addr()
DESCRIPTION
spm_inet_addr()
Returns the network number associated with the Internet Protocol
(IP) address of a host machine which is operating in the Distributed7 environment.
MT LEVEL
MT-Safe
SYNOPSIS
dword_t spm_inet_addr(char *hostname);
hostname
Points to name of host machine.
RETURN VALUES
network number On success.
-1
On failure.
2.3.2
spm_inet_ntoa()
DESCRIPTION
spm_inet_ntoa()
Converts the network number of a host machine that is operating
in the Distributed7 environment to its internet address.
The function returns a pointer to a character string of the Internet Protocol (IP) address in
the IP dotted decimal notation (base 256 notation a.b.c.d). The internal buffer holding the
information is overwritten by subsequent calls of this function or of spm_inet_host().
Page 2 - 70
1-1600-1003-01
MT LEVEL
Not MT-Safe
SYNOPSIS
char *spm_inet_ntoa(dword_t inetaddr);
inetaddr
Host machines network number. The output of spm_inet_addr() can be
used as an input to this call for obtaining the IP address.
RETURN VALUES
pointer to IP address
null pointer
2.3.3
On success.
On failure.
spm_inet_ntoa_r()
DESCRIPTION
spm_inet_ntoa_r()
Provides identical functionality as spm_inet_ntoa(), but is
specifically designed for use in multi-threaded applications.
MT LEVEL
MT-Safe
SYNOPSIS
char *spm_inet_ntoa_r (dword_t inetaddr, char *buf, int len);
inetaddr
buf
len
Host machines network number. The output of spm_inet_addr() is used

as input to this call for obtaining the IP address.
Points to a user-space memory location, i.e., buffer, the size of which is
set by the len arguement. On successful completion, the
spm_inet_ntoa_r() function copies the retrieved information to this
memory location.
Byte size, i.e., length, of memory allotted to buf.
Note: It is the users responsibility to ensure that the buffer is larger enough to store the
information retrieved.
RETURN VALUES
pointer to IP address
On success
null pointer
On failure
Page 2 - 71
1-1600-1003-01
2.3.4
spm_inet_host()
DESCRIPTION
spm_inet_host()
Converts the network number of a host machine that is operating
in the Distributed7 environment to its host name.
The function returns a pointer to a character string that contains the host name. The
internal buffer holding the information is overwritten by subsequent calls of this function
or of spm_inet_ntoa().
MT LEVEL
Not MT-Safe
SYNOPSIS
char *spm_inet_host(dword_t inetaddr);
DESCRIPTION
inetaddr
Host machines network number.
RETURN VALUES
pointer to hostname
null pointer
2.3.5
On success.
On failure.
spm_inet_host_r()
DESCRIPTION
spm_inet_host_r()
Provides identical functionality as spm_inet_host(), but is
specifically designed for use in multi-threaded applications.
MT LEVEL
MT-Safe
SYNOPSIS
char *spm_inet_host(dword_t inetaddr, char *buf, int len);
inetaddr
buf
len
Page 2 - 72

Points to a user-space memory location, i.e., buffer, the size of which is
set by the len arguement. On successful completion, the
spm_inet_host_r() function copies the retrieved information to this
memory location.
Byte size, i.e., length, of memory allotted to buf.
1-1600-1003-01
Note: It is the users responsibility to ensure that the buffer is larger enough to store the
information retrieved.
RETURN VALUES
pointer to IP hostname On success
null pointer
2.3.6
On failure
spm_inet_host_mask()
DESCRIPTION
spm_inet_host_mask Allows the user to retrieve the bit-mask to use to extract host
identifier information from the network number specified. These masks differ for class A,
B, or C type networks.
MT LEVEL
MT-Safe
SYNOPSIS
dword_t spm_inet_host_mask(dword_t inetaddr);
inetaddr
RETURN VALUES
non-negative value
On success. This value represents the host identifier associated
with the IP address for the user-specified host machine.
-1
2.3.7
On failure.
spm_inet_ntwk_mask()
DESCRIPTION
spm_inet_ntwk_mask Allows the user to retrieve the bit-mask to use to extract network
identifier information from the network number specified. These masks differ for class A,
B, or C type networks.
MT LEVEL
MT-Safe
SYNOPSIS
dword_t spm_inet_ntwk_mask(dword_t inetaddr);
inetaddr
Page 2 - 73
1-1600-1003-01
RETURN VALUES
bit-mask
-1
2.3.8
On success. This value will be the 32-bit mask to be used to extract the
network identifier information from a user-specified network number.
On failure. An unsigned value.
spm_inet_host_id()
DESCRIPTION
spm_inet_host_id
Takes the host number returned by the spm_inet_addr() function
as an argument and returns the host identifier associated. This alleviates the need for user
to be concerned about class A, B, or C type network addressing methods.
MT LEVEL
MT-Safe
SYNOPSIS
spm_inet_host_id(dword_t inetaddr);
inetaddr
RETURN VALUES
non-negative value
On success. This value represents the host identifier associated
with the IP address for the user-specified host machine.
-1
On failure
2.3.9
spm_inet_ntwk_id()
DESCRIPTION
spm_inet_ntwk_id
Takes the network number returned by the spm_inet_addr()
function as an argument and returns the network identifier associated. This alleviates the
need for user to be concerned about class A, B, or C type network addressing methods.
MT LEVEL
MT-Safe
SYNOPSIS
spm_inet_ntwk_id(dword_t inetaddr);
inetaddr
Page 2 - 74
1-1600-1003-01
RETURN VALUES
non-negative value
On success. This value represents the network identifier
associated with the IP address for the user-specified host machine.
-1
On failure
Page 2 - 75
1-1600-1003-01
This page is intentionally blank.
Page 2 - 76
1-1600-1003-01
Chapter 3:
3.1
APM API Library
Chapter Overview
This chapter provides reference information for the APM API function calls. All
applications that use any of these calls must include the following header files:
#include <api.h>
#include <apm.h>
The APM library (libapm.a) must be accessed using the $EBSHOME/access/lib path, and
linked with a user applicationcalled file.c in the examples below. $EBSHOME is an
environment variable holding the pathname of where the SS7 software is installed.
cc
-L $EBSHOME/access/lib -lapm
Sample source code files (see list below) are provided to demonstrate the use of
Distributed7 APM literals and functions. They should be compiled with the MAKEFILE in
the $EBSHOME/access/sample/apm directory. After they are compiled, the executables
are located in the $EBSHOME/access/demo directory.
Makefile
Apm_Child.C
apm_child.c
Apm_Log.C
apm_log.c
Apm_Parent.C
apm_parent.c
Apm_Trace.C
apm_trace.c
Apm_Wait.C
apm_wait.c
Page 3 - 1
1-1600-1003-01
APM API Library
Important: Distributed7 1.2. APM API is multi-thread (MT) Safe, and can be used with
3.2
APM API Library
3.2.1
apm_catcherr()
DESCRIPTION
apm_catcherr()
Detects and catches E_User and/or E_Fatal type error messages
from within a program and then calls the specified function to take a pre-planned course of
action.
MT LEVEL
MT-Safe
SYNOPSIS
void apm_catcherr(void (*f1) (void), void (*f2) (void));
f1
Specifies the function to call when E_User type messages occur. If the
argument is a NULL value, the system will ignore all occurrences of
E_User error messages.
f2
Specifies the function to call when E_Fatal type error messages occur.
The system normally terminates program execution, with a non-zero exit
code, when E_Fatal errors occur and no function has been specified.
However, if a NULL value is specified for f2, the system will ignore all
occurrences of the E_Fatal error messages.
SEE ALSO apm_catcherr_fatal(), apm_catcherr_user(), apm_puterr(),
apm_logerr(), apm_printerr()
3.2.2
apm_catcherr_fatal()
DESCRIPTION
apm_catcherr_fatal() Detects and catches E_Fatal type error messages from within a
program and then calls the specified function to take a pre-planned course of action.
MT LEVEL
MT-Safe
SYNOPSIS
void apm_catcherr_fatal(void (*f2) (void));
Page 3 - 2
1-1600-1003-01
f2
APM API Library
Specifies the function to call when E_Fatal type error messages occur. If
E_Fatal errors are not caught, the system normally terminates program
execution, with a non-zero exit code. A NULL value for f2 causes the
system to ignore all occurrences of the E_Fatal error messages.
SEE ALSO apm_catcherr(), apm_puterr(), apm_logerr(), apm_printerr()
3.2.3
apm_catcherr_user()
DESCRIPTION
apm_catcherr_user() Detects and catches E_User type error messages from within a
program and then calls the specified function to take a pre-planned course of action.
E_User errors are generated by application programs.
MT LEVEL
MT-Safe
SYNOPSIS
void apm_catcherr_user(void (*f1) (void));
f1
Specifies the function to call when E_User type messages occur. If the
argument is a NULL value or a function is not specified, the system will
ignore all occurrences of E_User error messages.
SEE ALSO apm_catcherr(), apm_puterr(), apm_logerr(), apm_printerr()
3.2.4
apm_clearerr()
DESCRIPTION
apm_clearerr()
Discards all error messages that have been generated and queued,
but have not been delivered to the mlogd daemon. An application program had previously
sent the error messages to the queue with the M_PutErr and/or M_PutErrDef macros.
This call has no effect on messages that have already been delivered to the mlogd daemon
using the M_LogErr, M_LogPutErr, M_LogAlm and M_LogPutAlm macros.
MT LEVEL
MT-Safe
SYNOPSIS
void apm_clearerr(void);
Page 3 - 3
1-1600-1003-01
APM API Library
SEE ALSO apm_puterr(), apm_logerr()
3.2.5
apm_getstate()
DESCRIPTION
apm_getstate()
Places a request to retrieve the current run state of the apmd
daemon process on a specified host, identified via the host argument.
MT LEVEL
MT-Unsafe
SYNOPSIS
char *apm_getstate(const char *host);
host
The specified host. A NULL value of host is interpreted to mean the local
host. apmd daemons on all involved hosts must be operational.
SEE ALSO apmd, apm_getstate_r(), apm_getstate, apm_setstate(), apm_setstate,
apmconfig
3.2.6
apm_getstate_r()
DESCRIPTION
apm_getstate_r()
Places a request to retrieve the current run state of the apmd
daemon process on a specified host, identified via the host argument. A NULL value of
host is interpreted to mean the local host. apmd daemons on all involved hosts must be
operational.
The apm_getstate_r function is identical to apm_getstate(), however it has been
specifically designed for use in multi-threaded application programs.
MT LEVEL
MT-Safe
SYNOPSIS
char *apm_getstate_r(const char *host, char *buf);
host
buf
Points to a user-space memory location. Upon successful completion, the
apm_getstate_r function will copy the information retrieved to this
memory location. It is the user's responsibility to ensure that buf buffer is
large enough to store the information to be retrieved.
SEE ALSO apmd, apm_getstate(), apm_getstate, apm_setstate(), apm_setstate,
apmconfig
Page 3 - 4
1-1600-1003-01
3.2.7
APM API Library
apm_init()
DESCRIPTION
apm_init
Attaches a process to the apmd environment and performs all
necessary initialization tasks. This function must be called once at the beginning of the
application program. Attempts to use any libapm functions prior to calling this function
will cause the program to terminate.
Initialization includes allocating system resourcesIPC message queues, shared memory
segments, and semaphoresfor the libapm trace and error log capabilities and specifying
the treatment of errors generated during program execution. System resources are used in
tracing program execution and in communicating with the apmd and mlogd daemons, i.e.,
placing requests to apmd via other libapm functions and logging errors via mlogd.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_init(const char * progname , unsigned int progid , int * version, int opts,
apmopts_t fatalsev apmopts_t warnsev );
progname
Identifies the name of the executable program. The argument should not
contain the / character because only the characters to the right of it will
be used. The program name is generally used only for identification in
trace and log records. However, it is required in the apm_setlogopts()
function to identify the program for which to set the error log options.
progid
An integer between 0 and 255 that identifies trace and/or error log
records of a program or a group of programs. If the progid value is not
the same as the value defined in the configuration file, i.e., apmconfig,
then apmconfig overwrites the progid value.
version
Points to an integer which identifies the apmd version the program will
use, since multiple versions may co-exist on a single host. Valid values
are defined by the apmvers_t enumeration defined in the <apm.h> file
and are as follows:
E_Exclusive invokes the basic Distributed7 version of apmd. The
$EBSHOME environment variable must be set to an appropriate
value prior to program execution. Multiple instances of this version
of apmd may not co-exist on a single host.
E_AccessServices invokes the AccessSERVICES version of apmd.
The $DOMID environment variable must be set prior to program
execution. Multiple instances of this version of apmd may co-exist on
a host (multiple application domains).
E_CRP invokes the AccessCRP (Call Routing Point) version of
apmd. The $PRODID and $RUNID environment variables must be
Page 3 - 5
1-1600-1003-01
opts
fatalsev
warnsev
Page 3 - 6
APM API Library
set to appropriate values prior to program execution. Multiple

instances of this version of apmd may co-exist on a host.
E_Undetermined lets the Distributed7 system software determine the
version of apmd. The version argument will point to the value that
identifies the version upon successful completion of the call. The
system determines the version based on the following logic:
- If $DOMID is set, it assumes an AccessSERVICES
environment (E_AccessServices).
- If $DOMID is not set, but $PRODID and $RUNID are set, it
assumes an AccessCRP environment (E_CRP).
- If none of the above environment variables are set, but
$EBSHOME is set, it assumes the basic
Distributed7 environment (E_Exclusive).
Specifies the default destination for log messages that will be generated
by the program. This default destination may be overwritten later using
the M_LogErr, M_LogPutErr or M_LogPutAlm macro. A valid
setting is any combination of the following flags:
E_MLog: Saves messages in the master log file.
E_ALog: Saves messages in the alternate log file.
E_MMI: Sends messages to the mml daemon.
E_Console: Prints messages on the system console.
E_GUI: Sends messages to the Graphical User Interface process.
E_Printer: Prints messages on the local printer.
E_Alarm: Sends messages to the alarmd daemon.
Specifies the single default severity level for E_Fatal type log messages
that will be generated by the program. If no value or an invalid value is
provided, E_Critical will be assigned as the default severity value.
Default severity values can always be overwritten using the M_LogErr
macro, the M_LogPutErr macro, the M_LogAlm macro, the
M_LogPutAlm macro or the apm_setlogopts() function call.
Specifies the single default severity level for E_Warning type log
messages that will be generated by the program. If no value or an invalid
value is provided, E_Major will be assigned as the default severity
value. Default severity values can always be overwritten using the
M_LogErr macro, the M_LogPutErr macro, the M_LogAlm macro,
the M_LogPutAlm macro or the apm_setlogopts() function call.
Both fatalsev and warnsev may be one of the values from the following
list (if multiple severity values are OR'ed together, the system will select
the one with the smallest value.):
E_Info: Informational security level.
E_Minor: Minor severity level (default).
1-1600-1003-01
APM API Library
E_Major: Major severity level.

E_Critical: Critical severity level.
RETURN VALUES
0
-1
On success
On failure; sets errno to indicate the error
ERRORS
<EBADARG>::Invalid function argument is supplied.
<EBADENV>::Environment variable(s) not set or corrupted.
Also see the errno values for the msgget(2), shmget(2), shmat(2), semget(2), and semop(2)
system calls.
ENVIRONMENT
The following environment variables must be set:
For AccessSERVICES: $DOMID
For AccessCRP: $PRODID and $RUNID.
For basic Distributed7: $EBSHOME.
SEE ALSO apm_trace(), apm_puterr(), apm_logerr()
3.2.8
apm_init_default()
DESCRIPTION
apm_init_default()
Attaches a process to the apmd environment and performs all
necessary initialization tasks, using default settings. This function is an alternative to
apm_init() and must be called once at the beginning of the application program, instead of
apm_init().
MT LEVEL
MT-Safe
SYNOPSIS
int apm_init_default(const char * progname , unsigned int progid, int * version);
The arguments for this call are described in apm_init(). This call uses the
default error log handling options instead of allowing the user to set
them. Error messages generated by the application program will be
logged in the master log file. The default severity value for E_Fatal is set
to E_Critical and the default severity value of E_Warning is set to
E_Major.
Page 3 - 7
1-1600-1003-01
APM API Library
Any of these default settings may be modified by the M_LogErr macro,

the M_LogPutErr macro, the M_LogPutAlm macro or the
apm_setlogopts() function call.
RETURN VALUES
0
-1
On success
ERRORS
system calls.
ENVIRONMENT
The following environment variables must be set:
For AccessSERVICES: $DOMID
For AccessCRP: $PRODID and $RUNID.
For basic Distributed7: $EBSHOME.
SEE ALSO apm_init(), apm_trace(), apm_puterr(), apm_logerr()
3.2.9
apm_init_asvc()
DESCRIPTION
apm_init_asvc()
Attaches a process to the AccessSERVICES apmd environment
and performs all necessary initialization tasks. This function can be used as an alternative
to apm_init() if in an AccessSERVICES environment. However, it is supported for
backward compatibility reasons only.
apm_init_asvc_default() Attaches a process to the AccessSERVICES apmd environment
and performs all necessary initialization tasks, using default settings. This function can be
used as an alternative to apm_init_asvc() or apm_init() if in an AccessSERVICES
environment. However, it is supported for backward compatibility reasons only.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_init_asvc(const char * progname, int opts, apmopts_t fatalsev,
apmopts_t warnsev);
int apm_init_asvc_default(const char * progname);
Page 3 - 8
1-1600-1003-01
APM API Library
The arguments are described in apm_init() on page 3-5.

Important: The $DOMID environment variable must be set!
RETURN VALUES
0
-1
On success
ERRORS
Note: Also see the errno values for the msgget(2), shmget(2), shmat(2), semget(2), and
semop(2) system calls.
3.2.10 apm_init_crp()
DESCRIPTION
apm_init_crp()
Attaches a process to the AccessCRP apmd environment and
performs all necessary initialization tasks. This function can be used as an alternative to
apm_init() if in an AccessCRP environment. However, it is supported for backward
compatibility reasons only.
apm_init_crp_default() Attaches a process to the AccessCRP apmd environment and
performs all necessary initialization tasks, using default settings. This function can be
used as an alternative to apm_init_crp() or apm_init() if in an AccessCRP environment.
However, it is supported for backward compatibility reasons only.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_init_crp(const unsigned int progid, const char * progname, int opts,
apmopts_t fatalsev, apmopts_t warnsev);
int apm_init_crp_default(const unsigned int progid, const char * progname);
The arguments are described in apm_init() on page 3-5.
Important: The $PRODID and $RUNID environment variables must be set!
Page 3 - 9
1-1600-1003-01
APM API Library
RETURN VALUES
0
-1
On success
ERRORS
system calls.
3.2.11 apm_kill()
DESCRIPTION
apm_kill()
Sends a UNIX signal to a process, or a group of processes,
executing on a specified host. The apmd daemons on both the local and remote hosts must
be in operation since the request goes through the local apmd to the remote apmd.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_kill(const char * host , pid_t pid , int signum);
host
Identifies the host machine on which the process or process group is
executing. A NULL value implies the local host.
pid
Identifies the process ID for the process or process group. A positive
value indicates the signal should be sent to the process with that UNIX
process ID. A negative value indicates that the signal should be sent to all
processes on the host whose group ID is equal to the absolute value of
pid. The process group ID is the value specified in the apmd
configuration file, and it could be different from the UNIX group ID of
the process.
signum
Identifies the UNIX signal to be sent. It can be any value that is valid for
the UNIX kill system call. A value of 0 doesnt send a signal but finds out
whether pid on host belongs to a currently executing process.
RETURN VALUES
0
-1
Page 3 - 10
On success
1-1600-1003-01
APM API Library
ERRORS
<ENOAPM>::The apmd daemon is not running.
Also see the errno values for the kill(2) system call and the spm_snd() function call.
SEE ALSO apm_init(), apm_spawn(), apm_sendack(), apm_kill() user commands
3.2.12 apm_logerr()
DESCRIPTION
M_LogErr
Logs all error messages waiting in queue by sending them to the
mlogd daemon of the local host. These error messages have been previously generated
using the M_PutErr and/or M_PutErrDef macros.
M_LogPutErr
Generates an error message, places it on the queue, and
immediately sends this message to the mlogd daemon.
M_LogAlm
Allows a user-specified almtype, as shown in spm_alarm(), to be
used when triggering an alarm condition. By default, an alarm type of 0 is used for
M_LogErr when the E_Alarm destination category is specified.
M_LogPutAlm
Allows a user-specified almtype, as shown in spm_alarm(), to be
used when triggering an alarm condition. By default, an alarm type of 0 is used for
M_LogPutErr when the E_Alarm destination category is specified.
MT LEVEL
MT-Safe
SYNOPSIS
void M_LogErr(int opts);
void M_LogPutErr(int opts,void *errid ,const char *fmt," ..." );
void M_LogAlm(int opts int almtype);
void M_LogPutAlm(int opts,void *errid, int almtype, const char *fmt," ..." );
opts
Identifies the destination, the severity value, and the message type for the
error message(s) to be sent to the mlogd daemon. If no options are
specified for this argument, the values provided in apm_init() will be
used as the default.
Severity Level
If specified, the value is used for all messages sent, regardless of type
(only one may be specified). If none is specified, all error message(s) are
assigned the severity values specified in the apm_init() call.
E_Info
Informational severity level.
E_Minor Minor severity level.
Page 3 - 11
1-1600-1003-01
errid
fmt
APM API Library
E_Major Major severity level.

E_CriticalCritical severity level.
Message Type
(only one may be specified)
E_Warning Warning message. The error will only be reported to the
specified destination(s). The severity value supplied in warnsev
during apm_init() or the default, E_Major, is used if a severity is not
specified.
E_Fatal Fatal message. The process will be terminated with a nonzero exit value unless the apm_catcherr_fatal() function is used. The
severity value supplied in fatalsev during apm_init() or the default,
E_Critical, is used if a severity is not specified.
E_User User-defined message. The error will only be reported to
the specified destination(s) unless the apm_catcherr_user() function
is used to specify some action. The default severity value is E_None
if a severity is not specified.
Destinations
E_MLog Saves messages in the master log file.
E_ALog Saves messages in the alternate log file.
E_MMI Sends messages to the mml daemon
E_ConsolePrints messages on the system console.
E_GUI Sends messages to the Graphical User Interface process.
E_Printer Prints messages on the local printer.
E_Alarm Sends messages to alarmd daemon.
Specifies the error type of the message to be generated, as defined in
M_PutErr.
Points to the error text in printf format.
FILES
$EBSHOME/access/RUN/mlog/MLog.mmddyy
$EBSHOME/access/RUN/alog/ALog.mmddyy
SEE ALSO mlogd, apm_init(), apm_puterr(), apm_newerrid(), apm_clearerr(),
apm_catcherr(), apm_setlogopts(), spm_alarm()
3.2.13 apm_newerrid()
DESCRIPTION
apm_newerrid()
Creates new error IDs that can be used with the M_PutErr,
M_PutErrDef, M_LogPutErr or M_LogPutAlm macros in addition to the error ID
values defined in the <apm.h> header file.
Page 3 - 12
1-1600-1003-01
APM API Library
MT LEVEL
MT-Safe
SYNOPSIS
void *apm_newerrid(const char * errname , const char * deftext,
unsigned int errnum);
errname
Identifies the error ID in the mlogd error log records.
deftext
Points to the default text string to be associated with the new error ID.
This default text can be overwritten by the M_PutErr, M_PutErrDef,
M_LogPutErr or M_LogPutAlm macros.
errnum
Contains the UNIX errno value to be associated with the new error ID.
The value must be equal to or greater than the
L_ERROR_USER_ERRNO_BASE literal defined in the <apm.h>
header file.
RETURN VALUES
void pointer to new ID On success. This pointer can be used with the M_PutErr,
M_PutErrDef, M_LogPutErr and M_LogPutAlm macros.
NULL pointer
ERRORS
SEE ALSO mlogd, apm_logerr(), apm_puterr()
3.2.14 apm_printerr()
DESCRIPTION
apm_printerr() Returns a pointer to the error message string associated with the current
value of the errno variable. The returned error message string should not
be overwritten.
MT LEVEL
MT-Unsafe
SYNOPSIS
char *apm_printerr(void);
This functions behavior is identical to that of the spm_strerror()
function, which retrieves text for error numbers that fall into the range of
the Distributed7 SPM API Library (defined in the <api_errno.h> header
file). It also behaves like the standard UNIX strerror function, which is
for errors that are not meaningful to the Distributed7 software.
Page 3 - 13
1-1600-1003-01
APM API Library
SEE ALSO spm_strerror(), strerror(3C)
3.2.15 apm_printerr_r()
DESCRIPTION
apm_printerr_r()Returns a pointer to the error message string associated with the current
value of the errno variable. The returned error message string should not
be overwritten.
The apm_printerr_r function is identical to apm_printerr(), however it
has been specifically designed for use in multi-threaded application
programs.
MT LEVEL
MT-Safe
SYNOPSIS
char *apm_printerr_r(char *buf);
This functions behavior is identical to that of the spm_strerror()
function, which retrieves text for error numbers that fall into the range of
the Distributed7 SPM API Library (defined in the <api_errno.h> header
file). It also behaves like the standard UNIX strerror function, which is
for errors that are not meaningful to the Distributed7 software.
buf
Points to a user-space memory location. Upon successful completion, the
apm_printerr_r function will copy the information retrieved to this
memory location. It is the user's responsibility to ensure that buf buffer is
large enough to store the information to be retrieved.
SEE ALSO spm_strerror(), strerror(3C)
3.2.16 apm_puterr()
DESCRIPTION
M_PutErr
Generates one or more error messages with a specified error text, and
then queues them They remain in the queue until they are sent to the
mlogd daemon on the local host by the M_LogErr macro. The messages
may be cleared from the queue before being sent to mlogd by calling
apm_clearerr().
M_PutErrDef Generates one or more error messages with the default text, and then
queues them They remain in the queue until they are sent to the mlogd
daemon on the local host by the M_LogErr macro. The messages may
be cleared from the queue before being sent to mlogd by calling
apm_clearerr().
Page 3 - 14
1-1600-1003-01
APM API Library
MT LEVEL
MT-Safe
SYNOPSIS
void M_PutErr(void * errid, const char *fmt, " ..." );
void M_PutErrDef(void * errid);
errid
Specifies the error ID. It may contain pre-defined values or values
defined with apm_newerrid(). The pre-defined values and their
associated default text are as follows:
LG_NOERR_C
No error.
LG_BADARG_C
Invalid argument.
LG_BADENV_C
Environment variable not set or
corrupted.
LG_BADOP_C
Invalid operation on an object
in the current state.
LG_CORRUPT_C
Stored data corrupted - manual
recovery required.
LG_END_C
End of procedure.
LG_EXISTS_C
Item already exists.
LG_INTERRUPT_C Procedure interrupted.
LG_INVAL_C
Invalid input.
LG_NOMEMORY_C Program memory exhausted.
LG_NOPERMIT_C Not permitted to do operation.
LG_NOSPACE_C
Limit exceeded.
LG_NOTCODED_C Feature not implemented yet.
LG_NOTENAB_C
Feature not enabled.
LG_NOTFOUND_C Item not found.
LG_STARTED_C
Program/thread/procedure started.
LG_STATUS_C
Information only.
LG_TERM_C
Program/thread/procedure
terminated.
LG_USER_C
User error.
LG_WARNING_C
Warning.
LG_NOAPM_C
apmd daemon not running.
LG_SYSTEM_C
System error: ... (error details)
LG_SPM_C
Platform error: ... (error details)
fmt
Points to text in the printf format to be substituted for the default error
text associated with the error ID.
Page 3 - 15
1-1600-1003-01
APM API Library
Note: For a list of UNIX errno values associated with a particular errid value, refer to the
<api_errno.h> header file.
SEE ALSO mlogd, apm_init(), apm_logerr(), apm_newerrid(), apm_clearerr()
3.2.17 apm_sendack()
DESCRIPTION
apm_sendack()
Sends an acknowledgment containing the calling processs startup status to a parent process or to apmd, depending on which one spawned the calling
process.
This function is used by a process to request apmd to send an acknowledgment message to
its parent. This message notifies the parent of the status of the start-up. A parent is either
apmd or the process which called apm_spawn() to start this process. While apmd is
actually the parent of all processes spawned through it, it is only considered the direct
parent if it spawned the process from an entry in the configuration file. Therefore, if apmd
is the direct parent, then the acknowledgment message of this call is sent to apmd. If the
direct parent is a process that called apm_spawn(), then the acknowledgment message is
sent to the process, through apmd not to apmd. In addition, if the parent is a process, the
parent process must have issued the apm_waitack() call in advance to receive any
acknowledgment messages. If it did not, the message will be discarded.
A parent may be on a remote host. Since this request is always placed through the apmd
daemon on the local host and then to the apmd on the remote host, the apmd daemons on
all involved hosts must be operational.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_sendack(int status);
status
Holds either ACK_STATE for a positive acknowledgment or
NAK_STATE for a negative one.
RETURN VALUES
0
-1
On success
ERRORS
<ESRCH>::Parent process does not exist.
Also see the errno values for the msgsnd(2) system call and the spm_snd() function call.
Page 3 - 16
1-1600-1003-01
APM API Library
SEE ALSO apm_init(), apm_spawn(), apm_waitack()
3.2.18 apm_setlogopts()
DESCRIPTION
apm_setlogopts()
Resets the default log options that were previously set when the
application program attached to apmd with apm_init(). The default destination and
severity values for error log messages are set for the specified program. The apm_init() or
apm_init_default() functions must already have been called in the program. These default
settings can be changed on an individual basis with the M_LogErr, M_LogPutErr,
M_LogAlm or M_LogPutAlm macros.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_setlogopts(const char * progname, int opts, apmopts_t fatalsev,
apmopts_t warnsev);
progname
Identifies the executable program for which the settings are being
changed. It must be identical to the name used in the apm_init() call.
The opts, fatalsev, and warnsev arguments are defined in apm_init() on page 3-5.
RETURN VALUES
0
-1
On success
ERRORS
SEE ALSO apm_init(), apm_logerr()
3.2.19 apm_setsigchld()
DESCRIPTION
apm_setsigchld()
Catches the termination signal from a child process and calls the
specified function. The calling process must have previously spawned the child process
with apm_spawn().
MT LEVEL
MT-Safe
Page 3 - 17
1-1600-1003-01
APM API Library
SYNOPSIS
int apm_setsigchld(void (*func) (const char * host, pid_t pid, int status ));
func
Specifies the function to be invoked when the termination of a child
process is detected. When func is invoked, the name of the child
processs host machine, its UNIX process ID, and its termination reason
will be automatically supplied to the function as arguments. The
information can be analyzed by the program to determine which process
was terminated and why. For a list of termination reasons, refer to
apm_waitack() on page 3-21. A NULL value of func disables this type of
notification.
A child process may be on a remote host. Since this request is always
placed through the apmd daemon on the local host and then to the apmd
on the remote host, the apmd daemons on all involved hosts must be
operational.
RETURN VALUES
0
-1
On success
ERRORS
Note: Also see the errno values for the msgrcv(2) system call.
SEE ALSO apm_init(), apm_spawn(), apm_kill(), apm_waitack()
3.2.20 apm_setstate()
DESCRIPTION
apm_setstate()
Manipulates the apmd run state. The function places a request to
manipulate the current run state of the apmd daemon process on a specified host,
identified via the host argument.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_setstate(const char *host, const char *newstate);
host
newstate
Specifies the desired run state the user wishes apmd to switch to. Based
on the current run state and contents of the apmd configuration file in
Page 3 - 18
1-1600-1003-01
APM API Library
use, this request may result in the execution of new scenarios, such as
spawning new processes and/or terminating existing processes.
RETURN VALUES
0
-1
On success
ERRORS
<ENOPERMIT>::Not permitted to do operation.
Note: The apmd daemon may reject a request to manipulate its current run state while it is
busy executing a scenario, possibly at a different run state. If this happens, apm_setstate()
will fail with ENOPERMIT error code.
SEE ALSO apmd, apm_getstate(), apm_getstate, apm_setstate, apmconfig
3.2.21 apm_spawn()
DESCRIPTION
apm_spawn()
Requests apmd to start a program on the specified host.
When this function is called, the apmd on the specified host creates a process and executes
the program using the fork and execvp UNIX system calls. The apmd is actually the
parent of the created process because it monitors its operations on behalf of the program
that invoked this call. Thus, the parameters inherited by the child process are those of its
apmd, not the ones of the program that invoked this function. However, the program
calling this function is also considered the parent process because it would receive any
acknowledgments (see apm_sendack() on page 3-16) and can receive the termination
signal from the created process (see apm_setsigchld() on page 3-17).
MT LEVEL
MT-Safe
SYNOPSIS
pid_t apm_spawn(const char *host, char *path, "..." , char * /*NULL*/ );
host
Identifies the host machine where the process will be started. A NULL
value of host means the local host will be used.
path
Identifies the UNIX path name of the program to be executed. It locates
the executable object file on host.
...
Up to L_MAXARGCNT arguments may be passed to the program as
char * type function arguments. This list of arguments must be
terminated with a NULL pointer.
Page 3 - 19
1-1600-1003-01
APM API Library
RETURN VALUES
process ID
-1
On success.
(The UNIX process ID of the child process on its host.)
ERRORS
Note: Also see the errno values for the fork(2) and execvp(2) system calls, and the
spm_snd() function call.
SEE ALSO fork(2), execvp(2), apm_init(), apm_sendack(), apm_waitack(),
apm_kill(), apm_setsigchld()
3.2.22 apm_trace()
DESCRIPTION
M_Trace
Generates a trace message from within the program, which allows realtime tracing of program execution. The trace message is copied to the
shared memory segment only if the trace category is part of the systems
trace mask. If it is not, the message is ignored by the system.
M_TraceVital Generates an unconditional trace message from within the program. The
trace message is always copied to the shared memory segment, regardless
of the systems trace mask. Therefore, it should only be used for cases
which rarely occur since these trace messages cannot be turned off.
MT LEVEL
MT-Safe
SYNOPSIS
void M_Trace(apmtrmask_t category) (const char *fmt, " ..." );
void M_TraceVital(const char *fmt, " ..." );
category
Holds the trace category for the message. Each application program can
define up to 64 trace categories of its own. Sixteen (16) categories are
reserved in the global trace mask for internal use. (See <apm.h> for the
list of 16 reserved categories that are only used by Distributed7 daemon
processes.) Thus, each application program can define up to 48 trace
categories of its own by using the lower 48 bits of the global trace mask
(bits 0-47).
fmt
Points to the trace message, in the printf format, that is sent to the IPC
shared memory segment on the local host.
Page 3 - 20
1-1600-1003-01
APM API Library
The shared memory is maintained by the apmd daemon on the local host. It can be viewed
off-line using the apm_trshow utility and/or captured and saved in log files using the
apm_trcapture utility. The global trace mask is manipulated with the apm_trsetmask
utility. This utility turns any combination of trace categories on or off, and can also be
used to specify trace patterns to perform selective tracing under a particular trace category.
SEE ALSO apm_trinit, apm_trclear, apm_trgetmask, apm_trsetmask, apm_trshow,
apm_trcapture.
3.2.23 apm_waitack()
DESCRIPTION
apm_waitack()
Waits for an acknowledgment from a child process that the
calling process just created using the apm_spawn() function. The child process sends the
acknowledgment with the apm_sendack() function.
The processes may be on different hosts. Since this request is always placed through the
apmd daemon on the local host and then to the apmd on the remote host, the apmd
daemons on all involved hosts must be operational.
MT LEVEL
MT-Safe
SYNOPSIS
int apm_waitack(const char *host, pid_t pid, int timeout, int *status);
host
Identifies the host machine that the child process was spawned on. A
NULL value means the process is on the local host.
pid
Identifies the UNIX process ID of the child process. The value was
returned by the apm_spawn() function.
timeout
Specifies the length of time, in seconds, that the calling process will wait
for the acknowledgment message. Valid values are:
-1: the call waits indefinitely, i.e., blocks until acknowledgment is
received or child process terminates
Any positive value (in seconds): the call waits the specified length of
time for an acknowledgment before returning, i.e., blocks until
acknowledgment is received, time limit expires, or child process
terminates
status
Points to an integer that is set upon return from the call. The contents of
the integer is one of the following values:
L_CSTAT_ACK
Received positive acknowledgment
message from child process.
L_CSTAT_NAK
Received negative acknowledgment
message from child process.
Page 3 - 21
1-1600-1003-01
APM API Library
L_CSTAT_ABNORMAL_EXIT
Child process has
terminated with a non-zero exit code.
L_CSTAT_NORMAL_EXIT
Child process has
terminated with a zero exit code.
L_CSTAT_KILLED
Child process has terminated as a result of
an unexpected signal.
L_CSTAT_NO_CHILD Child process does not exist or is not a
child of the calling process.
L_CSTAT_TIMEOUT Received no response from child process
within specified time.
RETURN VALUES
0
-1
On receipt of a positive acknowledgment message. The status argument

will be set to L_CSTAT_ACK.
If a positive acknowledgment is not received. The errno variable is set to
indicate the error. The status argument will be set to a value from the
defined list.
ERRORS
<ECHILD>::Child process does not exist.
Also see the errno values for the msgrcv system call, and the spm_snd() function call.
SEE ALSO apm_init(), apm_spawn(), apm_sendack(), apm_setsigchld()
Page 3 - 22
1-1600-1003-01
Chapter 4:
4.1
OAM API Library
OAM API Library
Chapter Overview
This chapter describes the Operations, Administration, and Maintenance (OAM) library,
which supports the Operations, Maintenance, and Administration Part (OMAP)a user part
of Distributed7 SS7. The OMAP user part provides the SS7 node operations maintenance
and administration functions.
The OMAP software package is an available option which is connected to each layer
defined in the Distributed7 SS7 stack, providing end-to-end administrative services to the
SS7 network.
4.2
OAM API Library

The OAM library enables users to retrieve measurement data and to configure and
manipulate the Signaling Point operation. The OMAP and OAM library relationship is
depicted in Figure 4-1.
Every library call is described in detail, including information on input parameters,
declarations, return values, and operation. All the type definitions can be found in the
referenced header files. Each library call is individually described within this chapter.
Distributed7 comes with an OMAP user part. OMAP can be started at system startup. It
collects the measurement information, as specified by ITU (CCITT) recommendation Q.791
and ANSI. These measurements are available to an application for any of the logical
signaling points on the system via use of a proper OAM library call. The application may
also request delivery of on-occurrence measurements. The library also allows activation/
deactivation of measurements activated on demand.
All the OMAP measurements can also be accessed through compiling the omap_report.c
source code file with the MAKEFILE in the $EBSHOME/access/sample/omap directory.
Execution of the file displays a report of the contents of all the OMAP files existing in the
$EBSHOME/access/RUN*/omaplog directory.
The OAM library also enables an application to configure the SS7 operation-related
parameters. These are protocol-related parameters such as linksets, route sets, subsystems.
To use the OAM function calls, the following header files must be included at the beginning
of the application in the given order:
#include <api.h>
Page 4 - 1
1-1600-1003-01
OAM API Library
#include <ss7_oam.h>
#include <oam_uproto.h>
User programs (e.g. userfile.c) must be linked as follows:
cc -I$EBSHOME/access/include userfile.c -o userfile userfile.o
-L$EBSHOME/access/lib -loam -lcnfg -ldbms -lapm -lspm
Important: Distributed7 1.2. OAM API is multi-thread (MT) Safe, and can be used with
SS7 APP
SS7 APP
OMAP
OAM API LIBRARY
ISUP
TCAP
SCCP
MTP-L3
MTP-L2
MTP-L1
Figure 4-1: OMAP AND OAM LIBRARY
Page 4 - 2
1-1600-1003-01
4.2.1
OAM API Library
oam_alarm()
DESCRIPTION
oam_alarm
Performs a multitude of managed object (MO) related operations
on the alarm MO that is associated with a user-specified signaling point. These operations
involve modification of an alarm instance or retrieving a list of alarm information.
NOTE: This function call must include the <oam_alarm.h> header file.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_alarm(int sp , oam_opers_e oper , const oam_alarm_t * data);
sp
This argument specifies the signaling point that is of interest and may
assume a value within the [0, 7] range.
oper
This argument specifies the operation to be performed on the alarm MO
and may assume a value from the following list:
E_OPER_MODIFY - Modify alarm parameters.
E_OPER_DISPLAY - Retrieve/display alarm information.
data
This argument points to the user-space buffer of type oam_alarm_t
which contains information about the alarm of interest. Prior to calling
the oam_alarm() function, all appropriate fields within the oam_alarm_t
structure should be initialized by the application.
RETURN VALUES
0
-1
4.2.2
On success. If a display operation is specified, the retrieved information

is copied to the user-space buffer pointed by the data argument.
On failure; errno is set to indicate the reason for failure.
oam_alias()
DESCRIPTION
oam_alias()
This funtion is used to perform operations on alias managed
objects associated with a user-specified signalling point. Operations involve addition of a
new alias point code, modification or deletion of an existing alias point code, or retrieving
the currently configured alias point code.
Important: Prior to calling any MTP related OAM library function, make sure that the
oam_mtp() function is called to perform a E_OPER_ADD operation. That is because the
oam_mtp() function initializes the MTP database for further MO requests. Otherwise, all
MTP related OAM functions are bound to fail.
Page 4 - 3
1-1600-1003-01
OAM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int oam_alias(int sp, oam_opers_e oper, const oam_alias_t *data);
sp
Specifies the signalling point that is of interest, and may assume a value
within the [0, 7] range.
oper
Specifies the operation to be performed on the alias MO, and may assume
a value from the following list:
E_OPER_ADD - Add a new alias point code to the signaling point
specified.
E_OPER_DELETE - Delete an existing alias point code for the
signalling point specified.
E_OPER_MODIFY - Modify parameters associated with an
existing alias point code.
E_OPER_DISPLAY - Retrieve/display information about the alias
point code specified.
E_OPER_GET_FIRST - Retrieve/display information about the first
instance for the alias point code specified.
data
Points to the user-space buffer of type oam_alias_t, which contains
information about the alias point code of interest.
Note: Prior to calling the oam_alias() function, all appropriate fields within the
oam_alias_t structure should be initialized by the application.
RETURN VALUES
0
-1

is copied to the user-space buffer pointed to by the data argument.
ERRORS
<EUEXISTALIAS>::ALIAS MO instance already exists.
<EUNOTEXALIAS>::ALIAS MO instance does not exist.
<EUZEROLIST>::Nothing to list.
<EUINVSUBTYP>::Invalid sub-type for this MO.
<EUINVOPER>::Invalid operation for this MO.
Page 4 - 4
1-1600-1003-01
OAM API Library
IMPORTANT NOTES
The following parameters of the alias managed object are optional in specified operations.
Masks field of oam_alias_t must be set with appropriate literal masks if they are to be
used in these operations.
Parameter Field
Operations
Mask
apc
Modify
OAM_ALIAS_APC_MASK
ogpc
Add, Modify
OAM_ALIAS_OGPC_MASK
in-fltr
Add, Modify
OAM_ALIAS_INFLTR_MASK
fltr-act
Add, Modify
OAM_ALIAS_FLTRACT_MASK
SEE ALSO oam_mtp()
4.2.3
oam_almevent()
DESCRIPTION
oam_almevent()
on the almevent MO that is associated with a user-specified signaling point. These
operations involve retrieving a list of alarm events currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_almevent(int sp , oam_opers_e oper , const oam_almevent_t * data );
sp
oper
This argument specifies the operation to be performed on the almevent
MO and may assume a value from the following list:
E_OPER_DISPLAY - Retrieve/display information about the alarm
event specified.
alarm event for the signaling point specified.
E_OPER_GET_NEXT - Retrieve/display information about the next
alarm event for the signaling point specified.
In order to retrieve information about all the alarm events associated with
a signaling point, an application should perform a
E_OPER_GET_FIRST operation followed by a series of
E_OPER_GET_NEXT operations until the oam_almevent() function
fails with an errno value of EUZEROLIST.
Page 4 - 5
1-1600-1003-01
data
OAM API Library
This argument points to the user-space buffer of type oam_almevent_t

which contains information about the alarm event of interest. Prior to
calling the oam_almevent() function, all appropriate fields within the
oam_almevent_t structure should be initialized by the application.
RETURN VALUES
0
-1
4.2.4

oam_almgrp()
DESCRIPTION
oam_almgrp()
on the almgrp MO that is associated with a user-specified signaling point. These
operations involve modification of an existing alarm group, or retrieving a list of alarm
group currently exist.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_almgrp(int sp, oam_opers_e oper, const oam_almgrp_t * data );
sp
assume a value within the [0,7] range.
oper
argument specifies the operation to be performed on the almgrp MO and
may assume a value from the following list:
E_OPER_MODIFY - Modify parameters associated with an existing
alarm group.
E_OPER_DISPLAY - Retrieve/display information about the alarm
group specified.
alarm group for the signaling point specified.
alarm group for the signaling point specified.
In order to retrieve information about all the alarm groups associated
with a signaling point, an application should perform a
E_OPER_GET_NEXT operations until the oam_almgrp() function fails
with an errno value of EUZEROLIST.
Page 4 - 6
1-1600-1003-01
data
OAM API Library
This argument points to the user-space buffer of type oam_almgrp_t

which contains information about the alarm group of interest. Prior to
calling the oam_almgrp() function, all appropriate fields within the
oam_almgrp_t structure should be initialized by the application.
RETURN VALUES
0
-1
4.2.5

oam_connection()
DESCRIPTION
oam_connection()
on the connection MO that is associated with a user-specified signaling point. These
operations involve retrieving a list of connections currently configured.
NOTE: This function call must include the <oam_sccp.h> header file.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_connection(int sp, oam_opers_e oper, const oam_connection * data );
sp
oper
This argument specifies the operation to be performed on the connection
E_OPER_DISPLAY - Retrieve/display information about the
connection specified.
connection for the signaling point specified.
connection for the signaling point specified.
In order to retrieve information about all the connections associated with
E_OPER_GET_NEXT operations until the oam_connection() function
fails with an errno value of ESCNOTLIST).
data
This argument points to the user-space buffer of type oam_connection_t
which contains information about the connection of interest. Prior to
Page 4 - 7
1-1600-1003-01
OAM API Library
calling the oam_connection() function, all appropriate fields within the

oam_connection_t structure should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
<ESCNOTLIST>::Nothing to list.
4.2.6
oam_cpc()
DESCRIPTION
oam_cpc()
on the cpc MO that is associated with a user-specified signaling point. These operations
involve addition of a new concerned point code, deletion of an existing concerned point
code, or retrieving a list of concerned point codes currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_cpc(int sp , oam_opers_e oper , const oam_cpc_t * data );
sp
oper
This argument specifies the operation to be performed on the cpc MO
E_OPER_ADD - Add a new concerned point code to the signaling
point specified.
E_OPER_DELETE - Delete an existing concerned point code for the
signaling point specified.
concerned point code specified.
concerned point code for the signaling point specified.
concerned point code for the signaling point specified.
In order to retrieve information about all the concerned point codes
associated with a signaling point, an application should perform a
Page 4 - 8
1-1600-1003-01
data
OAM API Library

E_OPER_GET_NEXT operations until the oam_cpc() function fails
with an errno value of ESCNOTLIST.
This argument points to the user-space buffer of type oam_cpc_t which
contains information about the concerned point code of interest. Prior to
calling the oam_cpc() function, all appropriate fields within the
oam_cpc_t structure should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
4.2.7
oam_gt()
DESCRIPTION
oam_gt()
on the gt MO that is associated with a user-specified signaling point. These operations
involve addition of a new global title, or deletion of an existing global title, or retrieving a
list of global titles currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_gt(int sp, oam_opers_e oper, const oam_gt_t * data );
sp
oper
This argument specifies the operation to be performed on the gt MO and
E_OPER_ADD - Add a new global title to the signaling point
specified.
E_OPER_DELETE - Delete an existing global title for the signaling
point specified.
E_OPER_DISPLAY - Retrieve/display information about the global
title specified.
Page 4 - 9
1-1600-1003-01
OAM API Library
data

global title for the signaling point specified.
global title for the signaling point specified.
In order to retrieve information about all the global titles associated with
a signaling point, an application should perform a E_OPER_GET_FIRST
operation followed by a series of E_OPER_GET_NEXT operations until
the oam_gt() function fails with an errno value of ESCNOTLIST.
This argument points to the user-space buffer of type oam_gt_t which
contains information about the global title of interest. Prior to calling the
oam_gt() function, all appropriate fields within the oam_gt_t structure
should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
4.2.8
oam_gtentry()
DESCRIPTION
oam_gtentry()
on the gtentry MO that is associated with a user-specified signaling point. These
operations involve addition of a new global title entry, or deletion of an existing global
title entry, or retrieving a list of global title entries currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_gtentry(int sp, oam_opers_e oper, const oam_gtentry_t * data );
sp
oper
This argument specifies the operation to be performed on the gtentry MO
E_OPER_ADD - Add a new global title entry to the signaling point
specified.
Page 4 - 10
1-1600-1003-01
OAM API Library
data
E_OPER_DELETE - Delete an existing global title entry for the

E_OPER_DISPLAY - Retrieve/display information about the global
title entry specified.
global title entry for the signaling point specified.
global title entry for the signaling point specified.
In order to retrieve information about all the global title entries
E_OPER_GET_NEXT operations until the oam_gtentry() function fails
This argument points to the user-space buffer of type oam_gtentry_t
which contains information about the global title entry of interest. Prior
to calling the oam_gtentry() function, all appropriate fields within the
oam_gtentry_t structure should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
4.2.9
oam_host()
DESCRIPTION
oam_host()
on the host MO that is associated with a user-specified signaling point. These operations
involve addition of a new host, modification or deletion of an existing host, or retrieving a
list of hosts currently configured.
NOTE: This function call must include the <oam_netd.h> header file.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_host(int sp, oam_opers_e oper, const oam_host_t * data );
Page 4 - 11
1-1600-1003-01
sp
oper
data
OAM API Library
This argument specifies the operation to be performed on the host MO
E_OPER_ADD - Add a new host to the signaling point specified.
E_OPER_DELETE - Delete an existing host for the signaling point
specified.
host.
E_OPER_DISPLAY - Retrieve/display information about the host
specified.
host for the signaling point specified.
host for the signaling point specified.
In order to retrieve information about all the hosts associated with a
signaling point, an application should perform a E_OPER_GET_FIRST
the oam_host() function fails with an errno value of ECNFGNOINST.
This argument points to the user-space buffer of type oam_host_t which
contains information about the host of interest. Prior to calling the
oam_host() function, all appropriate fields within the oam_host_t
RETURN VALUES
0
-1

4.2.10 oam_isup()
DESCRIPTION
oam_isup()
on the isup MO that is associated with a user-specified signaling point. These operations
involve modification an existing isup MO parameters, or retrieving the isup MO
information currently configured.
Prior to calling the oam_isup() function, make sure that the MTP configuration has been
completed.
NOTE: This function call must include the <oam_isup.h> header file.
Page 4 - 12
1-1600-1003-01
OAM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int oam_isup(int sp, oam_opers_e oper, const oam_isup_t * data );
sp
oper
This argument specifies the operation to be performed on the isup MO
isup instance.
E_OPER_DISPLAY - Retrieve/display information about the isup
specified.
isup for the signaling point specified (There is always one isup MO
instance per signaling point).
isup for the signaling point specified. (There is always one isup MO
instance per signaling point).
data
This argument points to the user-space buffer of type oam_isup_t which
contains information about the isup of interest. Prior to calling the
oam_isup() function, all appropriate fields within the oam_isup_t
Following parameters of isup MO are optional in specified operations.
The mask field of oam_isup_t must be set with appropriate literal masks
if they are going to be used in these operations.
PARAMETER FIELD
OPERATIONS MASK
-----------------------------------------------------variant
MOD
OAM_ISUP_VARIANT_MASK
mntcind
MOD
OAM_ISUP_MNTCIND_MASK
congestion
MOD
OAM_ISUP_CONGESTION_MASK
parc3ind
MOD
OAM_ISUP_PARC3IND_MASK
xlate
MOD
OAM_ISUP_XLATE_MASK
upmind
MOD
OAM_ISUP_UPMIND_MASK
recmode
MOD
OAM_ISUP_RECMODE_MASK
RETURN VALUES
0
-1

ERRORS
<ENOAPPCMD>::Non-applicable command.
Page 4 - 13
1-1600-1003-01
OAM API Library
<ENOPCNO>::PCNO does not exist.

<EPCNOMISS>::Missing PCNO parameter.
<ENOCFGNM>::CFGNAME does not exist.
<EINVVRNT>::Invalid VARIANT value.
<EINTDBERR>::Internal database error.
<ENOLIST>::Nothing to list.
SEE ALSO oam_isupnode(), oam_isupcgrp(), oam_isupcct(), oam_isuptmr()
4.2.11 oam_isupcct()
DESCRIPTION
oam_isupcct()
on the isupcct MO that is associated with a user-specified signaling point. These
operations involve addition of a new isup circuit, modification or deletion of an existing
isup circuit, or retrieving a list of isup circuits currently configured.
Prior to calling oam_isupcct() function, make sure that the oam_isupcgrp() function is
called to perform a E_OPER_ADD operation. Otherwise oam_isupcct() function is bound
to fail.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_isupcct(int sp, oam_opers_e oper, const oam_isupcct_t * data );
sp
oper
This argument specifies the operation to be performed on the isupcct MO
E_OPER_ADD - Add a new isup circuit to the signaling point
specified.
E_OPER_DELETE - Delete an existing isup circuit for the signaling
point specified.
isup circuit.
circuit specified.
isup circuit for the signaling point specified.
Page 4 - 14
1-1600-1003-01
OAM API Library
data

isup circuit for the signaling point specified.
In order to retrieve information about all the isup circuit associated with a
the oam_isupcct() function fails with an errno value of ENOLIST.
This argument points to the user-space buffer of type oam_isupcct_t
which contains information about the isup circuit of interest. Prior to
calling the oam_isupcct() function, all appropriate fields within the
oam_isupcct_t structure should be initialized by the application.
Following parameter of isupcct MO is optional in specified operations.
The mask field of oam_isupcct_t must be set with appropriate literal
masks if it is going to be used in these operations.
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------range
ADD,DEL,MOD
OAM_ISUPCCT_RANGE_MASK
RETURN VALUES
0
-1

ERRORS
<EGRPMISS>::Missing GRPID parameter.
<ECCTMISS>::Missing CCTNUM parameter.
<ENOGRP>::GRPID does not exist.
<ECCTEXIST>::CCTNUM already exists.
<ECCTOOR>::CCTNUM out of range.
<ENOCCT>::CCTNUM does not exist.
SEE ALSO oam_isup(), oam_isupnode(), oam_isupcgrp(), oam_isuptmr()
4.2.12 oam_isupcgrp()
DESCRIPTION
oam_isupcgrp()
on the isupcgrp MO that is associated with a user-specified signaling point. These
Page 4 - 15
1-1600-1003-01
OAM API Library
operations involve addition of a new isup circuit group, modification or deletion of an

existing isup circuit group, or retrieving a list of isup circuit groups currently configured.
Prior to calling oam_isupcgrp() function, make sure that the oam_isupnode() function is
called to perform a E_OPER_ADD operation. Otherwise oam_isupcgrp() function is
bound to fail.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_isupcgrp(int sp, oam_opers_e oper, const oam_isupcgrp_t * data );
sp
oper
This argument specifies the operation to be performed on the isupcgrp
E_OPER_ADD - Add a new isup circuit group to the signaling point
specified.
E_OPER_DELETE - Delete an existing isup circuit group for the
isup circuit group.
circuit group specified.
isup circuit group for the signaling point specified.
isup circuit group for the signaling point specified.
In order to retrieve information about all the isup circuit group associated
E_OPER_GET_NEXT operations until the oam_isupcgrp() function
fails with an errno value of ENOLIST.
data
This argument points to the user-space buffer of type oam_isupcgrp_t
which contains information about the isup circuit group of interest. Prior
to calling the oam_isupcgrp() function, all appropriate fields within the
oam_isupcgrp_t structure should be initialized by the application.
The following parameters of isupcgrp MO are optional in specified
operations. The mask field of oam_isupcgrp_t must be set with
appropriate literal masks if they are going to be used in these operations.
PARAMETER FIELD
Page 4 - 16
OPERATIONS
MASK
1-1600-1003-01
OAM API Library
-------------------------------------------------------trnkgrpid
MOD
OAM_ISUPCGRP_TRNKGRPID_MASK
scgaind
ADD,MOD
OAM_ISUPCGRP_SCGAIND_MASK
RETURN VALUES
0
-1

ERRORS
<EGRPEXIST>::GRPID already exists.
<EGRPMISS>::Missing GRPID parameter.
<ECCTMISS>::Missing CCTNUM parameter.
<ETRNKMISS>::Missing TRNKGRPID parameter.
<ETRNKOOR>::TRNKGRPID out of range.
<ETRNKEXIST>::TRNKGRPID already exists.
<EGRPOOR>::GRPID out of range.
<EGRPHASCCTS>::GRPID contains CCTs.
<ENOGRP>::GRPID does not exist.
SEE ALSO oam_isup(), oam_isupnode(), oam_isupcct(), oam_isuptmr()
4.2.13 oam_isupnode()
DESCRIPTION
oam_isupnode()
on the isupnode MO that is associated with a user-specified signaling point. These
operations involve addition of a new isup node, modification or deletion of an existing
isup node, or retrieving a list of isup node currently configured.
Prior to calling the oam_isupnode() function, make sure that the MTP configuration has
been completed.
Page 4 - 17
1-1600-1003-01
OAM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int oam_isupnode(int sp, oam_opers_e oper, const oam_isupnode_t * data );
sp
oper
This argument specifies the operation to be performed on the isupnode
E_OPER_ADD - Add a new isup node to the signaling point
specified.
E_OPER_DELETE - Delete an existing isup node for the signaling
point specified.
isup node.
node specified.
isup node for the signaling point specified.
isup node for the signaling point specified.
In order to retrieve information about all the isup node associated with a
the oam_isupnode() function fails with an errno value of ENOLIST.
data
This argument points to the user-space buffer of type oam_isupnode_t
which contains information about the isup node of interest. Prior to
calling the oam_isupnode() function, all appropriate fields within the
oam_isupnode_t structure should be initialized by the application.
The following parameters of isup MO are optional in specified
operations. The mask field of oam_isup_t must be set with appropriate
literal masks if they are going to be used in these operations.
PARAMETER FIELD OPERATIONS MASK
------------------------------------------------------dpc
MOD
OAM_ISUPNODE_DPC_MASK
anmoff
ADD,MOD OAM_ISUPNODE_ANMOFF_MASK
acmoff
ADD,MOD OAM_ISUPNODE_ACMOFF_MASK
crgoff
ADD,MOD OAM_ISUPNODE_CFGOFF_MASK
ciccontrol
ADD,MOD OAM_ISUPNODE_CICCONTROL_MASK
Page 4 - 18
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

ERRORS
<EDPCUNDEF>::DPC not defined in MTP network. Add route set first.
<EDPCEXIST>::DPC already exists.
<EPCNOEXIST>::PCNO already exists.
<EINVCICCNT>::Invalid CICCONTROL value.
<EDPCMISS>::Missing DPC parameter.
<ENODEHASGRPS>::ISUPNODE contains CCTGRPs.
SEE ALSO oam_isup(), oam_isupcgrp(), oam_isupcct(), oam_isuptmr()
4.2.14 oam_isuptmr()
DESCRIPTION
oam_isuptmr()
on the isuptmr MO that is associated with a user-specified signaling point. These
operations involve modification of an existing isup timer value or retrieving a list of isup
timers currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_isuptmr(int sp, oam_opers_e oper, const oam_isuptmr_t * data );
sp
oper
This argument specifies the operation to be performed on the isuptmr
Page 4 - 19
1-1600-1003-01
OAM API Library
data

isup timer.
timer specified.
isup timer for the signaling point specified.
isup timer for the signaling point specified.
In order to retrieve information about all the isup timer associated with a
the oam_isuptmr() function fails with an errno value of ENOLIST.
This argument points to the user-space buffer of type oam_isuptmr_t
which contains information about the isup timer of interest. Prior to
calling the oam_isuptmr() function, all appropriate fields within the
oam_isuptmr_t structure should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
<ETMROOR>::TIMERID out of range.
<ETMRMISS>::Missing TIMERID parameter.
<EVALMISS>::Missing VALUE parameter.
<EVALOOR>::VALUE out of range
SEE ALSO oam_isup(), oam_isupnode(), oam_isupcgrp(), oam_isupcct()
4.2.15 oam_l2cs()
DESCRIPTION
oam_l2cs()
on the l2cs MO that is associated with a user-specified signaling point. These operations
involve retrieving a list of link cumulative status data currently configured.
Prior to calling any MTP related OAM library function, make sure that the oam_mtp()
function is called to perform a E_OPER_ADD operation. That is because the oam_mtp()
Page 4 - 20
1-1600-1003-01
OAM API Library
function initializes the MTP database for further MO requests. Otherwise all MTP related
OAM functions are bound to fail.
NOTE: This function call must include the <oam_mtp.h> header file.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_l2cs(int sp, oam_opers_e oper, const oam_l2cs_t * data );
sp
oper
This argument specifies the operation to be performed on the l2cs MO
E_OPER_DISPLAY - Retrieve/display cumulative status
information about the link specified.
E_OPER_GET_FIRST - Retrieve/display cumulative status
information about the first link for the signaling point specified.
E_OPER_GET_NEXT - Retrieve/display cumulative status
information about the next link for the signaling point specified.
In order to retrieve information about all the link cumulative status
instances associated with a signaling point, an application should
perform a E_OPER_GET_FIRST operation followed by a series of
E_OPER_GET_NEXT operations until the oam_l2cs() function fails
data
This argument points to the user-space buffer of type oam_l2cs_t which
contains information about the link of interest. Prior to calling the
oam_l2cs() function, all appropriate fields within the oam_l2cs_t
RETURN VALUES
0
-1

ERRORS
<EUNOTEXLINK>::LINK MO instance does not exist.
Page 4 - 21
1-1600-1003-01
OAM API Library
SEE ALSO oam_mtp()
4.2.16 oam_l2flow()
DESCRIPTION
oam_l2flow()
on the l2flow MO that is associated with a user-specified signaling point. These operations
involve modification flow control data of an existing link, or retrieving a flow control
information of links currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_l2flow(int sp, oam_opers_e oper, const oam_l2flow_t * data );
sp
oper
This argument specifies the operation to be performed on the l2flow MO
E_OPER_MODIFY - Modify flow control parameters associated
with an existing link.
E_OPER_DISPLAY - Retrieve/display flow control information
about the link specified.
E_OPER_GET_FIRST - Retrieve/display flow control information
about the first link for the signaling point specified.
E_OPER_GET_NEXT - Retrieve/display flow control information
about the next link for the signaling point specified.
In order to retrieve flow control information about all the links associated
E_OPER_GET_NEXT operations until the oam_l2flow() function fails
data
This argument points to the user-space buffer of type oam_l2flow_t
which contains information about the link of interest. Prior to calling the
oam_l2flow() function, all appropriate fields within the oam_l2flow_t
Page 4 - 22
1-1600-1003-01
OAM API Library
The following parameters of l2flow MO are optional in specified

operations. The mask field of oam_l2flow_t must be set with appropriate
PARAMETER FIELD
OPERATIONS MASK
------------------------------------------------------congonval
MOD
OAM_L2FLOW_CONGONVAL_MASK
congabval
MOD
OAM_L2FLOW_CONGABVAL_MASK
disconval
MOD
OAM_L2FLOW_DISCONVAL_MASK
discabval
MOD
OAM_L2FLOW_DISCABVAL_MASK
RETURN VALUES
0
-1

ERRORS
<EUFLWCOLTPR>::CONGONVAL is less than previous level value.
<EUFLWCOGTNX>::CONGONVAL is greater than next level value.
<EUFLWCOLTCA>::CONGONVAL is less than CONGABVAL.
<EUFLWCOGTDO>::CONGONVAL is greater than DISCONVAL.
<EUFLWCALTPR>::CONGABVAL is less than previous level value.
<EUFLWCAGTNX>::CONGABVAL is greater than next level value.
<EUFLWCAGTCO>::CONGABVAL is greater than CONGONVAL.
<EUFLWCALTDA>::CONGABVAL is greater than DISCABVAL.
<EUFLWDOLTPR>::DISCONVAL is less than previous level value.
<EUFLWDOGTNX>::DISCONVAL is greater than next level value.
<EUFLWDOLTDA>::DISCONVAL is less than DISCABVAL.
<EUFLWDOLTCO>::DISCONVAL is less than CONGONVAL.
<EUFLWDALTPR>::DISCABVAL is less than previous level value.
<EUFLWDAGTNX>::DISCABVAL is greater than next level value.
<EUFLWDAGTDO>::DISCABVAL is greater than DISCONVAL.
<EUFLWDALTCA>::DISCABVAL is less than CONGABVAL.
<EUFLWVRANGE>::Threshold value is out of range.
<EUFLWRANGE>::Threshold level is out of range.
Page 4 - 23
1-1600-1003-01
OAM API Library
SEE ALSO oam_mtp()
4.2.17 oam_l2timer()
DESCRIPTION
oam_l2timer()
on the l2timer MO that is associated with a user-specified signaling point. These
operations involve modification of an existing mtp level-2 timer, or retrieving a list of mtp
level-2 timers currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_l2timer(int sp, oam_opers_e oper, const oam_l2timer_t * data );
sp
oper
This argument specifies the operation to be performed on the l2timer MO
level-2 timer.
E_OPER_DISPLAY - Retrieve/display information about the level-2
timer specified.
level-2 timer for the signaling point specified.
level-2 timer for the signaling point specified.
In order to retrieve information about all the mtp level-2 timer associated
E_OPER_GET_NEXT operations until the oam_l2timer() function fails
data
This argument points to the user-space buffer of type oam_l2timer_t
which contains information about the level-2 timer of interest. Prior to
calling the oam_l2timer() function, all appropriate fields within the
oam_l2timer_t structure should be initialized by the application.
Page 4 - 24
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

ERRORS
<EUPARAMVAL>::Parameter value is out of range.
<EUPROTNOTSET>::Mtp protocol is not set.
SEE ALSO oam_mtp()
4.2.18 oam_l3timer()
DESCRIPTION
oam_l3timer()
on the l3timer MO that is associated with a user-specified signaling point. These
operations involve modification of an existing mtp level-3 timer, or retrieving a list of mtp
level-3 timers exist.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_l3timer(int sp, oam_opers_e oper, const oam_l3timer_t * data );
sp
oper
This argument specifies the operation to be performed on the l3timer MO
mtp level-3 timer.
E_OPER_DISPLAY - Retrieve/display information about the mtp
level-3 timer specified.
Page 4 - 25
1-1600-1003-01
OAM API Library
data

mtp level-3 timer for the signaling point specified.
mtp level-3 timer for the signaling point specified.
In order to retrieve information about all the mtp level-3 timers
E_OPER_GET_NEXT operations until the oam_l3timer() function fails
This argument points to the user-space buffer of type oam_l3timer_t
which contains information about the mtp level-3 timer of interest. Prior
to calling the oam_l3timer() function, all appropriate fields within the
oam_l3timer_t structure should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
<EUNOTEXL3TIMER>::L3TIMER MO instance does not exist.
SEE ALSO oam_mtp()
4.2.19 oam_line()
DESCRIPTION
oam_line()
on the line MO that is associated with a user-specified signaling point. These operations
involve modification E1/T1 line, or retrieving a list of E1/T1 lines currently configured.
NOTE: This function call must include the <oam_spm.h> header file.
Page 4 - 26
1-1600-1003-01
OAM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int oam_line(int sp, oam_opers_e oper, const oam_line_t * data );
sp
oper
This argument specifies the operation to be performed on the line MO
E1/T1 line.
E_OPER_DISPLAY - Retrieve/display information about the E1/T1
line specified.
E1/T1 line for the signaling point specified.
E1/T1 line for the signaling point specified.
In order to retrieve information about all the E1/T1 lines associated with
E_OPER_GET_NEXT operations until the oam_line() function fails
with an errno value of ECNFGNOINST.
data
This argument points to the user-space buffer of type oam_line_t which
contains information about the E1/T1 line of interest. Prior to calling the
oam_line() function, all appropriate fields within the oam_line_t
RETURN VALUES
0
-1

4.2.20 oam_link()
DESCRIPTION
oam_link()
on the link MO that is associated with a user-specified signaling point. These operations
involve addition of a new link, modification or deletion of an existing link, or retrieving a
list of links currently configured.
Prior to adding a new link, be sure that the corresponding SS7BOARD MO instance is
added and the state of the SS7BOARD is set to ON.
Page 4 - 27
1-1600-1003-01
OAM API Library
Upon adding a new link; a LINKSTAT MO instance which includes the status information
of the link, L2TIMER MO instances (mtp level-2 timers) and L2FLOW MO instances
(flow control threshold) will automatically be added. Upon deletion of a the link, the
previously added LINKSTAT, L2TIMER and L2FLOW instances will automatically be
deleted as well.
Prior to deleting a link, be sure that the link is neither nor available.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_link(int sp, oam_opers_e oper, const oam_link_t * data );
sp
oper
This argument specifies the operation to be performed on the link MO
E_OPER_ADD - Add a new link to the signaling point specified.
E_OPER_DELETE - Delete an existing link for the signaling point
specified.
link.
E_OPER_DISPLAY - Retrieve/display information about the link
specified.
link for the signaling point specified.
link for the signaling point specified.
In order to retrieve information about all the links associated with a
the oam_link() function fails with an errno value of EUZEROLIST.
data
This argument points to the user-space buffer of type oam_link_t which
contains information about the link of interest. Prior to calling the
oam_link() function, all appropriate fields within the oam_link_t
Page 4 - 28
1-1600-1003-01
OAM API Library
The following parameters of link MO are optional in specified

operations. The mask field of oam_link_t must be set with appropriate
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------priority
MOD
OAM_LINK_PRIORITY_MASK
RETURN VALUES
0
-1

ERRORS
<EUNOROOM>::No room for new entry.
<EUDEVISNOTCONF>::Device is not configured.
<EUNOLININFO>::Link information can not be retrieved.
<EUINVSTREAMNO>::Invalid stream no is retrieved from spmd.
<EUEXISTLINK>::LINK MO instance already exists.
<EUHOSTNOTDEF>::HOSTNAME is not defined in the network.
<EUNOTEXLSET>::LSET MO instance does not exist.
<EULINKGTLOAD>::Attempt to add more links than loaded.
<EUPREUSLINK>::Pre-used HOSTNAME+DEVNAME+LINK combination.
<EUPREUSSLC>::Pre-used SLC value.
<EUPREUSPRIO>::Pre-used PRIORITY value.
<EUMOL2FAIL>::Mtpl2 MO operation failed.
<EULINKACTIVE>::Link is activated.
<EURECISMARKED>::Instance is marked by another MO server.
SEE ALSO oam_mtp()
4.2.21 oam_linkstat()
DESCRIPTION
oam_linkstat()
on the linkstat MO that is associated with a user-specified signaling point. These
operations involve modification of an existing link status, or retrieving a list of link status
instances currently configured.
Page 4 - 29
1-1600-1003-01
OAM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int oam_linkstat(int sp, oam_opers_e oper, const oam_linkstat_t * data );
sp
oper
This argument specifies the operation to be performed on the linkstat MO
E_OPER_MODIFY - Modify status parameters associated with an
existing link.
E_OPER_DISPLAY - mRetrieve/display status information about the
link specified.
E_OPER_GET_FIRST - Retrieve/display status information about
the first link for the signaling point specified.
E_OPER_GET_NEXT - Retrieve/display status information about
the next link for the
In order to retrieve status information about all the links associated with a
the oam_linkstat() function fails with an errno value of EUZEROLIST.
data
This argument points to the user-space buffer of type oam_linkstat_t
which contains information about the link of interest. Prior to calling the
oam_linkstat() function, all appropriate fields within the oam_linkstat_t
RETURN VALUES
0
-1

ERRORS
<EUNOTEXLINKSTAT>::LINKSTAT MO instance does not exist.
Page 4 - 30
1-1600-1003-01
OAM API Library
SEE ALSO oam_mtp()
4.2.22 oam_localsubsys()
DESCRIPTION
oam_localsubsys()
on the localsubsys MO that is associated with a user-specified signaling point. These
operations involve retrieving a list of local subsystems currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_localsubsys(int sp, oam_opers_e oper, const oam_localsubsys_t * data );
sp
oper
This argument specifies the operation to be performed on the localsubsys
E_OPER_DISPLAY - Retrieve/display information about the local
subsystem specified.
local subsystem for the signaling point specified.
local subsystem for the signaling point specified.
In order to retrieve information about all the local subsystems associated
E_OPER_GET_NEXT operations until the oam_localsubsys() function
fails with an errno value of ESCNOTLIST.
data
This argument points to the user-space buffer of type oam_localsubsys_t
which contains information about the local subsystem of interest. Prior to
calling the oam_localsubsys() function, all appropriate fields within the
oam_localsubsys_t structure should be initialized by the application.
RETURN VALUES
0
-1

Page 4 - 31
1-1600-1003-01
OAM API Library
ERRORS
4.2.23 oam_lset()
DESCRIPTION
oam_lset()
on the lset MO that is associated with a user-specified signaling point. These operations
involve addition of a new link set, modification or deletion of an existing link set, or
retrieving a list of link sets currently configured.
Prior to adding a lset, be sure that a route set, having the same destination point code, has
already been added.
The parameter LOADED can not be greater than the parameter ACTIVE.
Upon addition of a new lset, a LSETSTAT MO instance which includes the status
information of the link set, will automatically be added. Upon deletion of the lset, the
previously added LSETSTAT instance will automatically be deleted, as well.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_lset(int sp, oam_opers_e oper, const oam_lset_t * data );
sp
oper
This argument specifies the operation to be performed on the lset MO
E_OPER_ADD - Add a new link set to the signaling point specified.
E_OPER_DELETE - Delete an existing link set for the signaling
point specified.
link set.
E_OPER_DISPLAY - Retrieve/display information about the link set
specified.
link set for the signaling point specified.
Page 4 - 32
1-1600-1003-01
OAM API Library
data

link set for the signaling point specified.
In order to retrieve information about all the link sets associated with a
the oam_lset() function fails with an errno value of EUZEROLIST.
This argument points to the user-space buffer of type oam_lset_t which
contains information about the link set of interest. Prior to calling the
oam_lset() function, all appropriate fields within the oam_lset_t
The following parameters of lset MO are optional in specified
operations. The mask field of oam_lset_t must be set with appropriate
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------loaded
MOD
OAM_LSET_LOADED_MASK
active
MOD
OAM_LSET_ACTIVE_MASK
type
MOD
OAM_LSET_LSTYPE_MASK
RETURN VALUES
0
-1

ERRORS
<EUEXISTLSET>::LSET MO instance already exists.
<EUOWNPCSAME>::Own point code is the same.
<EULSETSAMEPC>::LSET MO instance with the same point code exists.
<EURTSETSAMEPC>::RTSET MO instance with the same point code
exists.
<EULOADGTACT>::Parameter LOADED is greater than parameter ACTIVE.
<EULSETUBLINK>::Linkset is been used by a link instance.
<EULSETUBROUTE>::Linkset is been used by a route instance.
<EULSETACTIVE>::Linkset is activated.
<EULOADLTLINK>::More links than this LOADED value in this linkset.
Page 4 - 33
1-1600-1003-01
OAM API Library
SEE ALSO oam_mtp()
4.2.24 oam_lsetstat()
DESCRIPTION
oam_lsetstat()
on the lsetstat MO that is associated with a user-specified signaling point. These
operations involve modification of an existing link set status instance, or retrieving a list
of link set status instances currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_lsetstat(int sp, oam_opers_e oper, const oam_lsetstat_t * data );
sp
oper
This argument specifies the operation to be performed on the lsetstat MO
E_OPER_MODIFY - Modify status parameters associated with an
existing link set.
E_OPER_DISPLAY - Retrieve/display status information about the
link set specified.
E_OPER_GET_FIRST - Retrieve/display status information about
the first link set for the signaling point specified.
E_OPER_GET_NEXT - Retrieve/display status information about
the next link set for the signaling point specified.
In order to retrieve status information about all the link sets associated
E_OPER_GET_NEXT operations until the oam_lsetstat() function fails
data
This argument points to the user-space buffer of type oam_lsetstat_t
which contains status information about the link set of interest. Prior to
calling the oam_lsetstat() function, all appropriate fields within the
oam_lsetstat_t structure should be initialized by the application.
Page 4 - 34
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

ERRORS
<EUNOTEXLSETSTAT>::LSETSTAT MO instance does not exist.
SEE ALSO oam_mtp()
4.2.25 oam_mate()
DESCRIPTION
oam_mate()
on the mate MO that is associated with a user-specified signaling point. These operations
involve addition of a new mate, or deletion of an existing mate, or retrieving a list of
mates currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_mate(int sp, oam_opers_e oper, const oam_mate_t * data );
sp
oper
This argument specifies the operation to be performed on the mate MO
E_OPER_ADD - Add a new mate to the signaling point specified.
E_OPER_DELETE - Delete an existing mate for the signaling point
specified.
E_OPER_DISPLAY - Retrieve/display information about the mate
specified.
mate for the signaling point specified.
mate for the signaling point specified.
Page 4 - 35
1-1600-1003-01
data
OAM API Library
In order to retrieve information about all the mates associated with a

the oam_mate() function fails with an errno value of ESCNOTLIST.
This argument points to the user-space buffer of type oam_mate_t which
contains information about the mate of interest. Prior to calling the
oam_mate() function, all appropriate fields within the oam_mate_t
RETURN VALUES
0
-1

ERRORS
4.2.26 oam_mtp()
DESCRIPTION
oam_mtp()
on the mtp MO that is associated with a user-specified signaling point. These operations
involve addition of a new mtp layer, modification or deletion of an existing mtp layer, or
retrieving a list of mtp layer currently configured.
Upon addition of an mtp instance, an SP (Signaling point), L3TIMER (mtp layer-3 timer),
and SLTIMER (SLTM timer) instances will automatically be added. Upon deletion of an
mtp instance, the previously added SP, L3TIMER, and SLTIMER instances will
automatically be deleted as well.
Prior to deleting an mtp instance, be sure that the all other MTP related MO instances have
been deleted.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_mtp(int sp, oam_opers_e oper, const oam_mtp_t * data );
Page 4 - 36
1-1600-1003-01
sp
oper
data
OAM API Library
This argument specifies the operation to be performed on the mtp MO
E_OPER_ADD - Add a new mtp layer to the signaling point
specified.
E_OPER_DELETE - Delete an existing mtp layer for the signaling
point specified.
mtp layer.
E_OPER_DISPLAY - Retrieve/display information about the mtp
layer specified.
mtp layer for the signaling point specified.
This argument points to the user-space buffer of type oam_mtp_t which
contains information about the mtp layer of interest. Prior to calling the
oam_mtp() function, all appropriate fields within the oam_mtp_t
If the protocol member of oam_mtp_t structure is set to any value which
identifies ANSI networks, then the following settings must also be
assured.
pcsize = E_PCSIZE_24
mcong = E_ON
mprio = E_ON
rtrc = E_ON
rpo2lpo = E_OFF
Following parameters of mtp MO are optional in specified operations.

The mask field of oam_mtp_t must be set with appropriate literal masks
if they are going to be used in these operations.
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------variant
ADD,MOD
OAM_MTP_VARIANT_MASK
mcong
ADD,MOD
OAM_MTP_MCONG_MASK
mprio
ADD,MOD
OAM_MTP_MPRIO_MASK
rtrc
ADD,MOD
OAM_MTP_RTRC_MASK
rpo2lpo
ADD,MOD
OAM_MTP_RPO2LPO_MASK
sltc
ADD,MOD
OAM_MTP_SLTC_MASK
restart
MOD
OAM_MTP_RESTART_MASK
RETURN VALUES
0
-1

Page 4 - 37
1-1600-1003-01
OAM API Library
ERRORS
<EUINVANSIPC>::Only 24_BIT pointcode is valid for ansi protocols.
<EUINCOMPATANSI>::Parameters are incompatible with ansi protocols.
<EUEXISTMTP>::MTP MO instance already exists.
<EURSTADD>::RESTART parameter is not allowed in add operation.
<EUNOTEXMTP>::MTP MO instance does not exist.
<EU1RTSETINUSE>::At least one routeset is in use.
<EUPROTNOMOD>::PROTOCOL parameter can not be modified.
<EUPCSIZENOMOD>::PCSIZE parameter can not be modified.
4.2.27 oam_ntwk()
DESCRIPTION
oam_ntwk()
on the ntwk MO that is associated with a user-specified signaling point. These operations
involve modification of network information, or retrieving network information.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_ntwk(int sp, oam_opers_e oper, const oam_ntwk_t * data );
sp
oper
This argument specifies the operation to be performed on the ntwk MO
network.
network MO.
data
This argument points to the user-space buffer of type oam_ntwk_t which
contains information about the network MO of interest. Prior to calling
the oam_ntwk() function, all appropriate fields within the oam_ntwk_t
Page 4 - 38
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

4.2.28 oam_port()
DESCRIPTION
oam_port()
on the port MO that is associated with a user-specified signaling point. These operations
involve modification of an existing port, or retrieving a list of ports currently configured.
SYNOPSIS
int oam_port(int sp, oam_opers_e oper, const oam_port_t * data );
sp
oper
This argument specifies the operation to be performed on the port MO
port.
E_OPER_DISPLAY - Retrieve/display information about the port
specified.
port for the signaling point specified.
port for the signaling point specified.
In order to retrieve information about all the ports associated with a
the oam_port() function fails with an errno value of ECNFGNOINST.
data
This argument points to the user-space buffer of type oam_port_t which
contains information about the port of interest. Prior to calling the
oam_port() function, all appropriate fields within the oam_port_t
RETURN VALUES
0
-1

Page 4 - 39
1-1600-1003-01
OAM API Library
4.2.29 oam_retrieve()
DESCRIPTION
oam_retrieve()
This function retrieves measurements data collected by the
AccessOMAP daemon process. The data contains the 30-minute measurements reported
through MTP Level 2, 5- and 30-minute measurements reported through MTP Level 3,
30-minute measurements reported through SCCP, and 30-minute measurements reported
through the TCAP layer.
NOTE: This function call must include the <oam.h> and <omap.h> header files.
MT LEVEL
MT-Unsafe
SYNOPSIS
int oam_retrieve(char * lfile, time_t mtime, oam_meas_t * msmt);
lfile
Specifies the full UNIX path name of the log file used by the
AccessOMAP daemon process to store the measurements information
reported by the individual layers of the SS7 protocol stack. See the
FILES section for a listing of naming conventions used by AccessOMAP
to differentiate categories of measurements data collected.
mtime
Specifies the calendar time, i.e., the number of seconds since 00:00:00
UTC, January 1, 1970, for which collected measurements data must be
retrieved. The log file specified through the lfile argument contains
measurements data for the entire day, as identified by the mmddyy tag.
This makes the lfile argument useful for searching selectively through the
log file for measurements data from a specific time of day.
msmt
Points to a user-space data buffer of type oam_meas_t to which
information about the retrieved measurements is copied. For further
information about the oam_meas_t data type, refer to the
<omap_ss7_meas.h> header file.
RETURN VALUES
0
-1
On success. Information about the measurements retrieved is copied to

the user-space buffer pointed to by the msmt argument.
ERRORS
<EINVAL>::Invalid function argument specified.
<EINVRECTYP>::Invalid measurements record type encountered.
<ERECNOTFOUND>::Measurements record not found.
<ECORRUPTREC>::Measurements record corrupted.
Page 4 - 40
1-1600-1003-01
OAM API Library
<EINVMODMEASTYP>::Cannot determine measurements type from the log

file name specified.
FILES
$EBSHOME/access/RUN[0-7]/omaplog/mtp2_30min.mmddyy
$EBSHOME/access/RUN[0-7]/omaplog/sccp_30min.mmddyy
$EBSHOME/access/RUN[0-7]/omaplog/tcap_30min.mmddyy
$EBSHOME/access/RUN/omaplog/tcap_30min.mmddyy
$EBSHOME/access/sample/omap/omap_report.c
$EBSHOME/access/sample/omap/Makefile
NOTES
When the TCAP over TCP/IP feature is in use, the TCAP layer reports its OMAP statistics
to the AccessOMAP instance associated with the signaling point 0. Unless this instance of
AccessOMAP is alive, no OMAP measurements data is collected for TCAP over TCP/IP
applications. Since this data is not associated with any signaling point, it is saved under the
$EBSHOME/access/RUN/omaplog directory instead of to the $EBSHOME/access/
RUN[0-7]/omaplog directory. The omap_report utility contains built-in intelligence to
search through all appropriate directories to locate the log files maintained by the
AccessOMAP daemon process.
SEE ALSO omapd
4.2.30 oam_retrieve_rec()
DESCRIPTION
oam_retrieve_rec()
This function is used to retrieve the measurements data collected
by the AccessOMAP daemon process in a selective and more efficient
manner than the oam_retrieve() function.
NOTE: This function call must include the <oam.h> and <omap.h> header files.
MT LEVEL
MT-Unsafe
SYNOPSIS
int oam_retrieve_rec(char * lfile, int type, time_t mtime, oam_meas_t * msmt);
type
Specifies whether the user is interested in retrieving the first, next, or a
specified record in the log file. It assumes one of the following values:
L_OMAP_REC_FIRST
Page 4 - 41
1-1600-1003-01
lfile
mtime
msmt
OAM API Library
L_OMAP_REC_NEXT
L_OMAP_REC_SPECIFIED
The efficiency in using this function is that users can retrieve all records
contained in a log fileregardless of the timeusing the
L_OMAP_REC_FIRST type value the first time the call is issued, and
then the L_OMAP_REC_NEXT type value for the remaining log file
records until an errno value of ERECNOTFOUND is returned. To
perform the same task using the oam_retrieve() function, the user needs
to issue this call around the clock, as well as search the log file for all
possible time values. Such a procedure wastes time and resources
especially if the log file does not contain records for the specified time.
When the value of L_OMAP_REC_SPECIFIED is used, this function
operates identically to oam_retrieve().
Specifies the full UNIX path name of the log file used by the
AccessOMAP daemon process to store the measurements information
reported by the individual layers of the SS7 protocol stack. See the
FILES section for a listing of naming conventions used by AccessOMAP
to differentiate categories of measurements data collected.
Specifies the calendar time, i.e., the number of seconds since 00:00:00
UTC, January 1, 1970, for which collected measurements data need be
retrieved. The log file specified through the lfile argument contains
measurements data for the entire day, as identified by the mmddyy tag.
The mtime argument is useful for searching selectively through the log
file for measurements data from a specific time of day. If the type
argument is specified as L_OMAP_REC_FIRST or
L_OMAP_REC_NEXT, then mtime points to a user-space buffer to
which the time associated with the retrieved record is copied upon
successful return from the function call.
Points to a user-space data buffer of type oam_meas_t to which
information about the retrieved measurements must be copied. For more
information about the oam_meas_t data type, refer to the
<omap_ss7_meas.h> header file.
RETURN VALUES
0
-1
On success; information about the measurements retrieved is copied to

the user-space buffer identified in the msmt argument.
ERRORS
<EINVRECTYP>::Invalid measurements record type encountered.
<ERECNOTFOUND>::Measurements record not found.
<ECORRUPTREC>::Measurements record corrupted.
Page 4 - 42
1-1600-1003-01
OAM API Library
<EINVMODMEASTYP>::Cannot determine measurements type from the log

file name specified.
FILES
$EBSHOME/access/RUN[0-7]/omaplog/sccp_30min.mmddyy
$EBSHOME/access/RUN[0-7]/omaplog/tcap_30min.mmddyy
$EBSHOME/access/RUN/omaplog/tcap_30min.mmddyy
$EBSHOME/access/sample/omap/omap_report.c
$EBSHOME/access/sample/omap/Makefile
NOTES
When the TCAP over TCP/IP feature is in use, the TCAP layer will report its OMAP statistics to the AccessOMAP instance associated with the signaling point 0. Unless this instance
of AccessOMAP is alive, no OMAP measurements data is collected for TCAP over TCP/IP
applications. Since this data is not associated with any signaling point, it is saved under the
$EBSHOME/access/RUN/omaplog directory instead of to the $EBSHOME/access/
RUN[0-7]/omaplog directory. The omap_report utility contains built-in intelligence to
search through all appropriate directories to locate the log files maintained by the AccessOMAP daemon process.
SEE ALSO omap [-q report_frequency] sp
4.2.31 oam_route()
DESCRIPTION
oam_route()
on the route MO that is associated with a user-specified signaling point. These operations
involve addition of a new route, deletion of an existing route, or retrieving a list of routes
currently configured.
Page 4 - 43
1-1600-1003-01
OAM API Library
MT LEVEL
MT-Safe
SYNOPSIS
int oam_route(int sp, oam_opers_e oper, const oam_route_t * data );
sp
oper
This argument specifies the operation to be performed on the route MO
E_OPER_ADD - Add a new route to the signaling point specified.
E_OPER_DELETE - Delete an existing route for the signaling point
specified.
E_OPER_DISPLAY - Retrieve/display information about the route
specified.
route for the signaling point specified.
route for the signaling point specified.
In order to retrieve information about all the routes associated with a
the oam_route() function fails with an errno value of EUZEROLIST.
data
This argument points to the user-space buffer of type oam_route_t which
contains information about the route of interest. Prior to calling the
oam_route() function, all appropriate fields within the oam_route_t
The following parameters of route MO are optional in specified
operations. The mask field of oam_route_t must be set with appropriate
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------priority
ADD
OAM_ROUTE_PRIORITY_MASK
If the priority field of oam_route_t structure is not provided in the

E_OPER_ADD operation, then the first available priority in the route set
will be used.
The maximum number of routes that can have the same priority in a route
set is two. These routes are called load-sharing routes (combined).
RETURN VALUES
0
Page 4 - 44

1-1600-1003-01
-1
OAM API Library
ERRORS
<EURTPRINULL>::Route priority is null.
<EUNOTEXROUTE>::ROUTE MO instance does not exist.
<EUEXISTROUTE>::ROUTE MO instance does not exist.
<EUNOTEXRTSET>::RTSET MO instance does not exist.
<EUNOROOMINRTS>::No room for new route entry in this routeset.
<EURTEQUALPRIO>::No more room for equal priority routes.
SEE ALSO oam_mtp()
4.2.32 oam_rtset()
DESCRIPTION
oam_rtset()
on the rtset MO that is associated with a user-specified signaling point. These operations
involve addition of a new route set, modification or deletion of an existing route set, or
retrieving a list of route sets currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_rtset(int sp, oam_opers_e oper, const oam_rtset_t * data );
sp
oper
This argument specifies the operation to be performed on the rtset MO
E_OPER_ADD - Add a new route set to the signaling point
specified.
Page 4 - 45
1-1600-1003-01
OAM API Library
data
E_OPER_DELETE - Delete an existing route set for the signaling

point specified.
route set.
E_OPER_DISPLAY - Retrieve/display information about the route
set specified.
route set for the signaling point specified.
route set for the signaling point specified.
In order to retrieve information about all the route sets associated with a
the oam_rtset() function fails with an errno value of EUZEROLIST.
This argument points to the user-space buffer of type oam_rtset_t which
contains information about the route set of interest. Prior to calling the
oam_rtset() function, all appropriate fields within the oam_rtset_t
The following parameters of rtset MO are optional in specified
operations. The mask field of oam_rtset_t must be set with appropriate
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------rtype
ADD
OAM_RTSET_RTYPE_MASK
If the protocol is set to ITU, then the rtype field of oam_rtset_t structure
must be set to E_RTYPE_MEMBER.
RETURN VALUES
0
-1

ERRORS
<EUEXISTRTSET>::RTSET MO instance already exists.
<EUNOTEXRTSET>::RTSET MO instance does not exist.
<EUOWNPCSAME>::Own point code is the same.
<EURTSETSAMEPC>::RTSET MO instance with the same point code
exists.
<EUINVITURTYPE>::Only member routing is valid for ITU protocols.
Page 4 - 46
1-1600-1003-01
OAM API Library
SEE ALSO oam_mtp()
4.2.33 oam_sccp()
DESCRIPTION
oam_sccp()
on the sccp MO that is associated with a user-specified signaling point. These operations
involve retrieving a list of sccp layers currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_sccp(int sp, oam_opers_e oper, const oam_sccp_t * data );
sp
oper
This argument specifies the operation to be performed on the sccp MO
E_OPER_DISPLAY - Retrieve/display information about the sccp
layer specified.
sccp layer for the signaling point specified.
sccp layer for the signaling point specified.
In order to retrieve information about all the sccp layers associated with a
the oam_sccp() function fails with an errno value of ESCNOTLIST.
data
This argument points to the user-space buffer of type oam_sccp_t which
contains information about the sccp layer of interest. Prior to calling the
oam_sccp() function, all appropriate fields within the oam_sccp_t
RETURN VALUES
0
-1

Page 4 - 47
1-1600-1003-01
OAM API Library
ERRORS
4.2.34 oam_sltimer()
DESCRIPTION
oam_sltimer()
on the sltimer MO that is associated with a user-specified signaling point. These
operations involve modification of an existing SLTM timer, or retrieving a list of SLTM
timers currently exist.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_sltimer(int sp, oam_opers_e oper, const oam_sltimer_t * data );
sp
oper
This argument specifies the operation to be performed on the sltimer MO
SLTM timer.
E_OPER_DISPLAY - Retrieve/display information about the SLTM
timer specified.
SLTM timer for the signaling point specified.
SLTM timer for the signaling point specified.
In order to retrieve information about all the SLTM timers associated
E_OPER_GET_NEXT operations until the oam_sltimer() function fails
data
This argument points to the user-space buffer of type oam_sltimer_t
which contains information about the SLTM timer of interest. Prior to
Page 4 - 48
1-1600-1003-01
OAM API Library
calling the oam_sltimer() function, all appropriate fields within the

oam_sltimer_t structure should be initialized by the application.
RETURN VALUES
0
-1

ERRORS
<EUNOTEXSLTIMER>::SLTIMER MO instance does not exist.
SEE ALSO oam_mtp()
4.2.35 oam_snsp()
DESCRIPTION
oam_snsp()
on the snsp MO that is associated with a user-specified signaling point. These operations
involve addition of a new snsp (SCCP network signaling point), or deletion of an existing
snsp, or retrieving a list of snsp instances currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_snsp(int sp, oam_opers_e oper, const oam_snsp_t * data );
sp
oper
This argument specifies the operation to be performed on the snsp MO
E_OPER_ADD - Add a new snsp to the signaling point specified.
E_OPER_DELETE - Delete an existing snsp for the signaling point
specified.
E_OPER_DISPLAY - Retrieve/display information about the snsp
specified.
Page 4 - 49
1-1600-1003-01
OAM API Library
data

snsp for the signaling point specified.
snsp for the signaling point specified.
In order to retrieve information about all the snsp instances associated
E_OPER_GET_NEXT operations until the oam_snsp() function fails
This argument points to the user-space buffer of type oam_snsp_t which
contains information about the snsp of interest. Prior to calling the
oam_snsp() function, all appropriate fields within the oam_snsp_t
RETURN VALUES
0
-1

ERRORS
4.2.36 oam_sp()
DESCRIPTION
oam_sp()
on the sp MO that is associated with a user-specified signaling point. These operations
involve modification of an existing signaling point instance, or retrieving a list of
signaling point instances currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_sp(int sp, oam_opers_e oper, const oam_sp_t * data );
Page 4 - 50
1-1600-1003-01
sp
oper
data
OAM API Library
This argument specifies the operation to be performed on the sp MO and
signaling point.
instance for the signaling point specified.
This argument points to the user-space buffer of type oam_sp_t which
contains information about the signaling point of interest. Prior to calling
the oam_sp() function, all appropriate fields within the oam_sp_t
The following parameters of sp MO are optional in specified
operations.The mask field of oam_sp_t must be set with appropriate
PARAMETER FIELD
OPERATIONS
MASK
-------------------------------------------------------spc
MOD
OAM_SP_SPC_MASK
ni
MOD
OAM_SP_NI_MASK
type
MOD
OAM_SP_TYPE_MASK
name
MOD
OAM_SP_NAME_MASK
RETURN VALUES
0
-1

ERRORS
<EUNOTEXSP>::SP MO instance does not exist.
<EUUPEXISTS>::In order to modify SPC/NI parameters all user parts
must terminate.
Page 4 - 51
1-1600-1003-01
OAM API Library
SEE ALSO oam_mtp()
4.2.37 oam_ss7board()
DESCRIPTION
oam_ss7board()
on the ss7board MO that is associated with a user-specified signaling point. These
operations involve addition of a new SS7 board, modification or deletion of an existing
SS7 board, or retrieving a list of SS7 boards currently configured.
NOTE: This function call must include the <oam_spm.h> header file.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_ss7board(int sp, oam_opers_e oper, const oam_ss7board_t * data );
sp
oper
This argument specifies the operation to be performed on the ss7board
E_OPER_ADD - Add a new SS7 board to the signaling point
specified.
E_OPER_DELETE - Delete an existing SS7 board for the signaling
point specified.
SS7 board.
E_OPER_DISPLAY - Retrieve/display information about the SS7
board specified.
SS7 board for the signaling point specified.
SS7 board for the signaling point specified.
In order to retrieve information about all the SS7 boards associated with a
the oam_ss7board() function fails with an errno value of
ECNFGNOINST.
data
This argument points to the user-space buffer of type oam_ss7board_t
which contains information about the SS7 board of interest. Prior to
calling the oam_ss7board() function, all appropriate fields within the
oam_ss7board_t structure should be initialized by the application.
Page 4 - 52
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

4.2.38 oam_strdalm()
DESCRIPTION
oam_strdalm()
on the strdalm MO that is associated with a user-specified signaling point. These
operations involve deletion of an existing stored alarm, or retrieving a list of stored alarms
currently available.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_strdalm(int sp, oam_opers_e oper, const oam_strdalm_t * data );
sp
oper
This argument specifies the operation to be performed on the strdalm
E_OPER_DELETE - Delete an existing stored alarm for the
E_OPER_DISPLAY - Retrieve/display information about the stored
alarm specified.
stored alarm for the signaling point specified.
stored alarm for the signaling point specified.
In order to retrieve information about all the stored alarms associated
E_OPER_GET_NEXT operations until the oam_strdalm() function fails
data
This argument points to the user-space buffer of type oam_strdalm_t
which contains information about the stored alarm of interest. Prior to
calling the oam_strdalm() function, all appropriate fields within the
oam_strdalm_t structure should be initialized by the application.
Page 4 - 53
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

4.2.39 oam_subsys()
DESCRIPTION
oam_subsys()
on the subsys MO that is associated with a user-specified signaling point. These operation
involve the addition of a new subsystem, deletion of an existing subsystem, or retrieving a
list of subsystems.
NOTE: This function call must include the <oam_sccp.h> and the <oam.h> header files.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_subsys(int sp, oam_opers_e oper, const oam_subsys_t * data);
sp
oper
This argument specifies the operation to be performed on the subsys MO
E_OPER_ADD - Add a new subsystem to the signaling point
specified.
E_OPER_DELETE - Delete an existing subsystem from the
subsystem specified.
subsystem for the signaling point specified.
subsystem for the signaling point specified.
data
This argument points to the user-space buffer of type oam_subsys_t
which contains information about the subsystem of interest. Prior to
calling the oam_subsys() function, all appropriate fields within the
oam_subsys_t structure should be initialized by the application.
In order to retrieve information about all subsystems associated with a signaling point, an
application should perform an E_OPER_GET_FIRST operation followed by a series of
E_OPER_GET_NEXT operations, i.e., until the oam_subsys() function fails with an
errno value of ESCNOTLIST.
Page 4 - 54
1-1600-1003-01
OAM API Library
RETURN VALUES
0
-1

ERRORS
4.2.40 oam_tcpcon()
DESCRIPTION
oam_tcpcon()
on the tcpcon MO that is associated with a user-specified signaling point. These
operations involve modification of an existing TCP/IP connection, or retrieving a list of
TCP/IP connections currently configured.
MT LEVEL
MT-Safe
SYNOPSIS
int oam_tcpcon(int sp, oam_opers_e oper, const oam_tcpcon_t * data );
sp
oper
This argument specifies the operation to be performed on the tcpcon MO
TCP/IP connections.
E_OPER_DISPLAY - Retrieve/display information about the TCP/IP
connections specified.
TCP/IP connections for the signaling point specified.
TCP/IP connections for the signaling point specified.
In order to retrieve information about all the TCP/IP connections
E_OPER_GET_NEXT operations until the oam_tcpcon() function fails
with an errno value of ECNFGNOINST.
data
This argument points to the user-space buffer of type oam_tcpcon_t
which contains information about the TCP/IP connections of interest.
Page 4 - 55
1-1600-1003-01
OAM API Library
Prior to calling the oam_tcpcon() function, all appropriate fields within

the oam_tcpcon_t structure should be initialized by the application.
RETURN VALUES
0
-1
Page 4 - 56

1-1600-1003-01
Chapter 5:
5.1
DSM API Library
DSM API Library
Chapter Overview
This chapter provides the Distributed Shared Memory (DSM) Application Programming
5.2
DSM API Library

The DSM library is used to create and manage shared memory segments under a
distributed computing environment. Every library call is described in detail on the
following pages, including information on input parameters, declarations, and return
values. These function calls require the following header files to be included in the
application:
#include <dsm.h>
#include <dsm_proto.h>
The DSM library must be linked with the application if any of its functions are used. See
the Distributed7 Application Development Manual for more information.
The DSM library (libdsm.a) should be accessed using the $EBSHOME/access/lib path,
and linked with a user application (called file.c in the examples), as shown below.
($EBSHOME is an environment variable holding the pathname of where the SS7
software is installed.)
cc
-L $EBSHOME/access/lib -ldsm
A sample source code file, dsm_apidemo.c, is provided to demonstrate the use of
Distributed7 DSM literals and functions. It should be compiled with the MAKEFILE in
the $EBSHOME/access/sample/dsm directory. After it is compiled, the executable will
be located in the $EBSHOME/access/demo directory.
Page 5 - 1
1-1600-1003-01
DSM API Library
Important: Distributed7 1.2. DSM API is multi-thread (MT) Safe, and can be used with
5.2.1
dsm_attach()
DESCRIPTION
dsm_attach()
This function is used to attach the local copy of a distributed
shared memory (DSM) segment to the data segment of the calling process. Once attached,
the calling process can read/write data through the segment as allowed by the permission
flags specified during the attach operation. A DSM segment may be attached multiple
times by the same process by calling the dsm_attach() function multiple times. When a
process that has one or more DSM segments attached to its data segment spawns a new
process, using the fork() system call, the spawned child process cannot readily access
these segments using the address information inherited from the parent process. Under
such circumstances, the child process is required to invoke the dsm_attach() call explicitly
to attach the DSM segment to its data segment.
MT LEVEL
MT- Safe
SYNOPSIS
void *dsm_attach(int dsmid , void * addr , int flags );
dsmid
This argument identifies an existing DSM segment that is acquired by the
calling process previously using the dsm_get() function call.
addr
This argument is the memory address at which a local copy of the DSM
segment should be attached and is interpreted by the system using the
following criteria:
If addr = NULL, the segment is attached to the first available address
as selected by the system.
If addr = NULL and the DSM_SHARE_MMU flag is set [and is
supported by the operating system], then the segment is attached to
the first available aligned address. Determination of the aligned
address is made based on the mapping size of the virtual memory
system.
If addr NULL and the DSM_ROUND flag is set, the segment is
attached to the address given by (addr - (addr % SHMLBA).
If addr NULL and the DSM_ROUND flag is not set, the segment is
attached to the address specified via addr .
flags
This argument is a control flag that may be constructed by OR-ing flags
from the following list:
DSM_RDONLY
Calling process can read from the DSM
segment; however, is not authorized to write to the segment. Unless
Page 5 - 2
1-1600-1003-01
DSM API Library
this flag is set, the DSM segment will be attached for reading and
writing.
DSM_SHARE_MMU
Share the virtual memory (VM) resources
(such as page tables) associated with the shared memory segment on
the local host as long as the operating system supports such sharing.
This option has no effect if the local operating system does not
support VM resource sharing. When this flag is set, the access
permissions specified during the dsm_get() function call determine
whether the DSM segment is attached for reading only or reading and
writing.
DSM_ROUND
Round attach address specified via the
addr argument to the nearest page size as long as the operating
system supports this operation. This option has no effect if the local
operating system does not support address rounding.
Important: Application programs concerned about portability across different platforms

should leave up to the system, the decision to determine the address to which a DSM segment is to be attached by specifying a NULL value of addr.
RETURN VALUES
pointer to segment On success, a pointer to the beginning of the attached DSM segment is
returned to the user.
-1
ERRORS
<EIO>::Cannot relay user request to the dsmd daemon. Make sure
that the local dsmd daemon is running.
<EBADMSG>::An invalid and/or corrupted response has been received
from the dsmd daemon.
<EACCES>::Operation permission is denied to the calling process.
<EBADF>::dsmid specified is invalid.
<EINVAL>::Invalid function argument is specified.
<EINVAL>::addr is not equal to zero and the value of (addr (addr % SHMLBA)) is an illegal address.
<EINVAL>::addr is not equal to zero, (flags &DSM_ROUND) is false,
and the value of addr is an illegal address.
<EINVAL>::addr is not equal to zero, (flags &DSM_SHARE_MMU) is
true, and addr is not aligned properly.
<EMFILE>::The number of DSM segments attached to the calling
process would exceed the system-imposed limit for
the IPC shared memory subsystem.
<ENOMEM>::The available data space for the calling process is not
large enough to accommodate the DSM segment to be
attached.
Page 5 - 3
1-1600-1003-01
DSM API Library
<ENOMEM>::Unable to fulfill user request due to a failure to

allocate internal memory. Note that the dsmd daemon
allocates various pieces of dynamic memory to store
information associated with the user requests,
segments acquired, processes attached to a specific
segment, and locks acquired at a given time.
SEE ALSO dsmd, dsm_get(), dsm_detach(), dsm_stat, dsm_list, dsm_audit
5.2.2
dsm_destroy()
DESCRIPTION
dsm_destroy()
This function is used to remove the distributed shared memory
(DSM) segment identifier specified by the dsmid argument from the system and destroy
the DSM segment and data structures associated with it. When a DSM segment is
destroyed, all processes attached to that segment will automatically be detached and all
locks pertaining to that segment will automatically be released by the system. This
function can be executed only by a process that has an effective user ID equal to that of
super user (root) or to the owner (the process that created the segment in the first place) of
the DSM segment.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_destroy(int dsmid);
dsmid
Segment identifier argument, specifies the DSM segment and associated
data structures to be removed from the system.
RETURN VALUES
0
On success.
-1
ERRORS
<EPERM>::Effective user ID of the calling process is neither equal
to that of super user (root) or the owner (the
process that created the segment in the first place)
of the DSM segment.
Page 5 - 4
1-1600-1003-01
DSM API Library

<EDESTBLKD>::At least one of the dsmd daemon processes is in
blocked state.
<ETIME>::Unable to process request specified on time due to
communication failure between dsmd daemon processes
involved.
SEE ALSO dsmd, dsm_get(), dsm_attach(), dsm_detach(), dsm_list, dsm_rm
5.2.3
dsm_detach()
DESCRIPTION
dsm_detach()
Detach DSM segment. This function is used to detach the local
copy of a distributed shared memory (DSM) segment (which has been attached previously
using the dsm_attach() function call) from the data segment of the calling process. After a
DSM segment has been detached, the calling process can no longer perform read/write
operations through the segment as the addr argument will no longer point to the beginning
of the DSM segment. When a DSM segment is detached, all locks acquired by the calling
process, pertaining to that segment, will automatically be released by the system.
Important: If a DSM segment has been attached multiple times by a process, it needs to be
detached multiple times as well to eliminate all references to it by that process as this may
prevent other applications from accessing the segment for read-write purposes concurrently.
Note that the dsmd daemon allocates various pieces of dynamic memory to store
information associated with user requests, segments acquired, processes attached to a
specific segment, and locks acquired at a given time.
Under normal circumstances, processes are expected to detach all copies of a DSM
segment that have been previously attached when they no longer needed. If and when a
process that has one or more copies of a DSM segment exits prematurely, without
detaching all attached copies of the segment, the system will automatically detach these
copies on behalf of the calling process.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_detach(int dsmid, void * addr );
dsmid
Identifies an existing DSM segment that has been previously acquired by
the calling process using the dsm_get() function call.
Page 5 - 5
1-1600-1003-01
addr
DSM API Library
Pointer value, specifies the beginning address of the DSM segment that
has been previously attached by the calling process using the
dsm_attach() function call.
RETURN VALUES
0
On success.
-1
On Failure; errno is set to indicate the error.
ERRORS
allocate internal memory.
SEE ALSO dsmd, dsm_get(), dsm_attach(), dsm_destroy(), dsm_list, dsm_audit
5.2.4
dsm_get()
DESCRIPTION
dsm_get
Get DSM segment identifier. This function call is used to create a
new and/or obtain access to an existing distributed shared memory (DSM) segment
associated with the key argument and return an identifier to that segment.
A DSM segment allows processes executing on multiple hosts operating under a
distributed Distributed7 environment to attach local copies of the segment, i.e., physical
memory replicated on the individual hosts, to their virtual address space and share
information by reading/writing from/to these segments. To prevent inconsistencies and/or
collisions when reading/writing through a DSM segment, processes must always use
synchronization variables, i.e., read/write locks, when reading/writing through local
copies of the segment.
A process operating under Distributed7 environment creates a DSM segment by invoking
the dsm_get() function with an appropriate value of key argument and specifying the size
of the segment to be created as well as the access permissions to the segment. If the DSM
segment associated with key has already been created by another process, dsm_get() will
simply return the identifier for that segment.
Once created, a DSM segment can be attached to the virtual address space of a process
using the dsm_attach() function call. After attaching a DSM segment to its address space,
a process must use the dsm_lock() and dsm_unlock() function calls to facilitate consistent
read/write operations through the local copy of the shared memory segment available on
the local host. When a DSM segment is no longer needed by a particular process, it can be
detached from that process's address space using the dsm_detach() function. Alternatively,
a DSM segment that is no longer needed across the system can be removed from all hosts
using the dsm_destroy() function.
Page 5 - 6
1-1600-1003-01
DSM API Library
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_get(key_t key , size_t size , int flags );
key
Identifies an existing distributed shared memory (DSM) segment.
size
Specifies the size of the DSM segment to be created. Provided that
dsm_get() function call succeeds, the system guarantees that shared
memory segments of at least size bytes are created on the individual host
machines comprising a distributed Distributed7 environment.
flags
Specifies access permissions to a DSM segment. This argument can be
constructed by OR-ing flags from the following list:
DSM_RD_OWN
Read by the owner.
DSM_WR_OWN
Write by the owner.
DSM_RD_GRP
Read by processes in the same group.
DSM_WR_GRP
Write by processes in the same group.
DSM_RD_OTH
Read by all processes.
DSM_WR_OTH
Write by all processes.
DSM_CREATE
Create DSM segment if it does not exist.
DSM_EXCLUSIVE
Fail if an attempt is made to create a DSM
segment that already exists.
The access permissions to a DSM segment are controlled during the
attach operations by the individual processes.
RETURN VALUES
int
-1
On success; a non-negative integer that is the DSM segment identifier.

ERRORS
<EACCES>::A DSM segment identifier exists for key but operation
permissions as specified by the flags would not be
granted.
<EINVAL>::key is equal to IPC_PRIVATE.
<EINVAL>::key specified is associated with an IPC shared memory
segment; thus, cannot be used for acquiring a DSM
segment.
Page 5 - 7
1-1600-1003-01
DSM API Library
<EINVAL>::size specified is less than the system-imposed minimum

or greater than the system-imposed maximum for the
IPC shared memory subsystem.
<EINVAL>::A DSM segment identifier exists for key but the size of
the segment associated with it is less than size.
<EEXIST>::A DSM segment identifier already exists for key but
flags &DSM_CREATE and &DSM_EXCLUSIVE are both true.
<ENOENT>::A DSM segment identifier does not exist for key and
flags &DSM_CREATE is false.
<ENOMEM>::The available data space for the dsmd daemon is not
large enough to accommodate the DSM segment to be
created by the calling process.
<ENOSPC>::A DSM segment identifier is to be created but the
system-imposed limit on the maximum number of
allowed IPC shared memory identifier system-wide
would be exceeded.
<EMFILE>::The number of DSM segments attached to the dsmd daemon
process would exceed the system-imposed limit for
the IPC shared memory subsystem.
blocked state.
involved.
SEE ALSO dsmd, dsm_attach(), dsm_getstat(), dsm_setstat(), dsm_getopts(),

dsm_setopts(), dsm_lock(), dsm_unlock(), dsm_detach(), dsm_destroy(), dsm_stat,
and dsm_list.
5.2.5
dsm_getopts()
DESCRIPTION
dsm_getopts()
Get DSM optional parameters. This function call is used to
retrieve the current settings of distributed shared memory (DSM) related optional
parameters that are associated with a particular DSM segment and are in use by the calling
process. These parameters include the data block (record) size and the read-write lock
options for all copies of the DSM segment currently attached by the calling process.
Page 5 - 8
1-1600-1003-01
DSM API Library
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_getopts(int dsmid , dsmopts_t * opts );
dsmid
Identifies an existing DSM segment that has been previously acquired
and attached by the calling process using the dsm_get() and dsm_attach()
function calls, respectively.
opts
Pointer value; indicates location of returned information in the data
structure. The members of this structure are as follows:
typedef struct {
size_t dsm_blksize;
word_t dsm_lockopt;
#define DSM_BACKUP
#define DSM_NOBACKUP
word_t dsm_pad;
} dsmopts_t;
/* data block size */

/* read-write lock options */
0
0x0001
/* auto backup */
/* disable auto backup */
/* reserved for future use */
The data block size information about a DSM segment is useful only
when the application programmer is interested in exercising the recordbased DSM lock capabilities (via the dsm_rdlock_rec() and
dsm_wrlock_rec() function calls). The data block size allows an
application programmer to find out the current size (in bytes) of the
individual records associated with a particular DSM segment.
Information about the read-write lock options is useful only in standalone configurations. The read-write lock options simply indicate
whether an automatic backup of the affected portions of a DSM segment
should be generated by the system when a read-write lock is acquired by
an application program. This option is always set to DSM_BACKUP in
the distributed mode of operation.
Parameter settings retrieved via the dsm_getopts() function can be
overwritten subsequently using the dsm_setopts() function call.
RETURN VALUES
0
-1
On success. The information retrieved is copied to the data structure

indicated by the opts argument.
ERRORS
Page 5 - 9
1-1600-1003-01
DSM API Library

<EACCES>::DSM segment specified is not attached to the data
segment of the calling process.
SEE ALSO dsmd, dsm_setopts()
5.2.6
dsm_getstat()
DESCRIPTION
dsm_getstat()
Get DSM segment status. This function is used to retrieve
various pieces of information about a distributed shared memory (DSM) segment. The
information retrieved includes the key associated with the segment, access permissions,
segment size, total number of processes currently attached to the segment, and
information about the owner of the segment.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_getstat(int dsmid , dsmstat_t * stat );
dsmid
stat
Pointer value to memory location where returned information stored in
the data structure. The members of this structure are as follows:
typedef struct {
key_t dsm_key; /* key associated */
int dsm_shmid; /* local shared memory id */
int dsm_mode; /* access permissions */
size_t dsm_size; /* segment size [in bytes] */
int dsm_nattch; /* total # processes attached */
dword_t dsm_inetaddr; /* owner's i-net address */
pid_t dsm_pid; /* owner's process id */
uid_t dsm_uid; /* owner's effective user id */
gid_t dsm_gid; /* owner's effective group id */
} dsmstat_t;
RETURN VALUES
0
-1
Page 5 - 10
On success. The information retrieved is copied to the data structure

pointed by the stat argument.
1-1600-1003-01
DSM API Library
ERRORS
<EACCES>::Calling process is not permitted to read data structures
associated with the DSM segment specified.
blocked state.
involved.
SEE ALSO dsmd, dsm_setstat(), dsm_stat
Page 5 - 11
1-1600-1003-01
5.2.7
DSM API Library
dsm_rdlock()
DESCRIPTION
dsm_rdlock()
This function is used to instantiate a read-only lock across a userspecified region of a distributed shared memory (DSM) segment so that the calling
process can safely read data from this region. Multiple processes can hold read-only locks
across overlapping regions of a DSM segment, so that multiple processes can read data
from overlapping regions of the same DSM segment in a concurrent manner.
MT LEVEL
MT- Safe
int dsm_rdlock(int dsmid , void * addr , size_t size , int opt );
dsmid
and attached by the calling process, using the dsm_get() and
dsm_attach() function calls, respectively.
addr
Specifies the beginning address, within the DSM segment, for the region
about to be locked. This address should be specified on the basis of a
previous dsm_attach() function call, as this call will normally return the
beginning address of the attached DSM segment.
size
Specifies the overall size, in bytes, of the region about to be locked.
opt
Control flag that assumes a value from the following list:
DSM_WAIT
Suspend execution of the calling process
indefinitely if the lock requested cannot be granted by the system
immediately; another lock that interferes with the operation of the
lock requested is in place. When all interfering locks are released, the
lock requested will be granted and process execution will continue.
This is the default option.
DSM_NOWAIT Do not suspend execution of the calling process if
the lock requested cannot be granted by the system immediately. If
the lock requested can be established right away, do so. Otherwise, do
not wait and simply return an error.
Under normal circumstances, all locks acquired by the DSM framework require inter-host
communication between the individual instances of dsmd() daemon running on individual
hosts; thus, they are costly from a performance point of view. One exception to this is rulebased DSM locks -- see man pages for dsm_rule(). Rule-based read-only locks have
local-only context; therefore, they can be directly granted by the dsmd() daemon on the
local host. Note however that rule-based DSM locks may not be appropriate for all
applications. Nevertheless, provided that it makes sense for an application to use rulebased DSM locking and the application has established all appropriate read-only rules
using an appropriate dsm_rule() function upfront, it can acquire read-only locks with
local-only context simply by setting the DSM_RULE flag as part of the opt argument.
Unless the DSM_RULE flag is set, DSM framework interprets all lock requests as global
lock requests.
Page 5 - 12
1-1600-1003-01
DSM API Library
RETURN VALUES
int
-1
On success, a non-negative integer, namely a lock identifier, is returned

to the user.
ERRORS
<EPERM>::Cannot acquire a read-write lock on a DSM segment that is
attached with read-only permissions.
<EAGAIN>::Region specified is currently locked and (opt &
DSM_NOWAIT) is true.
blocked state.
SEE ALSO dsmd, dsm_unlock(), dsm_getopts(), dsm_setopts(), dsm_list,

dsm_audit
Page 5 - 13
1-1600-1003-01
5.2.8
DSM API Library
dsm_rdlock_rec()
DESCRIPTION
dsm_rdlock_rec()
This function call is provided to acquire read-only and read-write
locks under those circumstances where the data stored in a DSM segment can be viewed
as a collection of fixed-size data blocks (records). This function call allows the application
programmer to simply specify the starting record number and the total number of records
to be locked using the from and cnt function arguments respectively, instead of specifying
the starting address and size information. Records in each DSM segment are numbered by
the system in a sequential manner, starting from 1.
Application programmers interested in using the record-based DSM locking capabilities
should specify the size of individual records within a particular DSM segment after a
segment identifier is acquired using the dsm_get() function call. By default, the record size
for each DSM segment will be initialized to the value of the DSM_DEFBLKSIZE
parameter on the system. By using the dsm_setopts() function however, this information
can be overwritten to meet the needs of a specific application.
A noteworthy point in using the record-based DSM locking capabilities is the behavior of
record-based locks when there are multiple attachments of a particular DSM segment by
the calling process. Since record-based DSM locks are not associated with a particular
attachment, detaching individual copies of the segment does not cause automatic release
of the locks established by the calling process across the corresponding segment. Only
when all attached copies of a DSM segment are detached, will the record-based locks for
that segment be released.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_rdlock_rec(int dsmid , int from , int cnt , int opt );
dsmid
from
Specifies the first record number from a set of records to be locked.
cnt
Specifies the total number of records to be locked. Records in each DSM
segment are numbered by the system in a sequential manner, starting
from 1.
opt
DSM_WAIT
Page 5 - 14
1-1600-1003-01
DSM API Library

the lock requested can be established right away, do so. Otherwise,
do not wait and simply return an error.
hosts; thus, they are costly from a performance point of view. One exception to this is
rule-based DSM locks -- see man pages for dsm_rule(). Rule-based read-only locks have
applications. Nevertheless, provided that it makes sense for an application to use rulebased DSM locking and the application has established all appropriate read-only rules
using an appropriate dsm_rule() function upfront, it can acquire read-only locks with
lock requests.
RETURN VALUES
int
-1

to the user.
ERRORS
blocked state.
Page 5 - 15
1-1600-1003-01
DSM API Library

dsm_audit
5.2.9
dsm_rdrule()
DESCRIPTION
dsm_rdrule()
The dsm_rdrule() function is used to establish a read-only rule
across a user-specified region of a distributed shared memory (DSM) segment so that the
calling process can read data from this region with improved performance. Under normal
circumstances, all read-only locks acquired by the DSM framework require coordination
between the individual instances of the dsmd() daemon. Ruled read-only locks however
do not require such communication provided that the process/thread acquiring the lock is
the one that is in charge of a read-only or read-write rule. Ruled read-only locks have
local-only context; therefore, can be directly granted by the dsmd() daemon on the local
host. Note that ruled read-only locks may not be suitable for all applications as they
implicitly assume that read-only access to the specified region(s) of a DSM segment is by
processes/threads on a specified host. If this is not the case, one should neither establish
read-only rules nor attempt to acquire read-only locks with local-only context.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_rdrule(int dsmid, void *addr, size_t size);
dsmid
Identifies an existing DSM segment that is acquired and attached by the
calling process that previously used the dsm_get() and dsm_attach()
addr
Specifies the beginning address [within the DSM segment] for the region
about to be ruled. This address should be specified on the basis of a
previous dsm_attach() function call as this call will normally return the
beginning address of the DSM segment attached.
size
Specifies the overall size [in bytes] of the region about to be ruled.
RETURN VALUES
ri
-1
Upon successful completion, a non-negative integer, namely a rule

identifier, is returned to the user.
ERRORS
On failure, errno will be set to one of the following:
EIO
Page 5 - 16
Cannot relay user request to the dsmd(1D) daemon.

Make sure that the local dsmd(1D) daemon is running.
1-1600-1003-01
EBADMSG
EBADF
EINVAL
EPERM
EAGAIN
EACCES
ENOMEM
DSM API Library
An invalid and/or corrupted response has been

received from the dsmd(1D) daemon.
dsmid\fP specified is invalid.
Invalid function argument is specified.
Cannot acquire a read-write rule on a DSM segment
that is attached with read-only permissions.
Region specified is currently ruled by another
process/thread.
Operation permission is denied to the calling
process.
Unable to fulfill user request due to a failure to
Note: The dsmd() daemon allocates various pieces of dynamic memory to store information
associated with the user requests, segments acquired, processes attached to a specific segment, and rules established at a given time.
EDESTBLKD
At least one of the dsmd(1D) daemon processes is in

blocked state.
SEE ALSO dsmd, dsm_unrule (), dsm_getopts (), dsm_setopts (), dsm_lock (),
dsm_unlock (), dsm_list, dsm_audit
5.2.10 dsm_rdrule_rec()
DESCRIPTION
dsm_rdrule_rec()
This function call is intended for use (i.e., to establish read-only)
under those circumstances where the data stored in a DSM segment can be viewed as a
collection of fixed size data blocks (i.e., "records"); thus, instead of specifying the starting
address and size information, application programmer can simply specify the starting
record number as well as the total number of records to be ruled using the from and cnt
function arguments, respectively. Records in each DSM segment are numbered by the
system in a sequential manner, starting from 1.
Application programmers interested in using the record-based DSM ruling capabilities
segment identifier is acquired using the dsm_get() function call. By default, the record
size for each DSM segment will be initialized to the value of the DSM_DEFBLKSIZE
A noteworthy point in using the record-based DSM ruling capabilities is in regard to the
behavior of record-based rules in the existence of multiple attaches of a particular DSM
segment (i.e., by the calling process). Since record-based DSM rules are not associated
with a particular attachment, detaching individual copies of the segment does not cause
automatic removal of the rules established by the calling process across the corresponding
Page 5 - 17
1-1600-1003-01
DSM API Library
segment. It is only when all attached copies of a DSM segment are detached, the recordbased rules for that segment will be removed.
MT LEVEL
MT- Safe
SYSNOPIS
int dsm_rdrule_rec(int dsmid, int from, int cnt);
dsmid
from
The staring record number to be viewed.
cnt
The total number of records tobe viewed.
RETURN VALUES
ri
-1
Upon successful completion, a non-negative integer, namely a rule

identifier, is returned to the user.
ERRORS
EIO
EBADMSG
EBADF
EINVAL
EPERM
EAGAIN
EACCES
ENOMEM

dsmid\fP specified is invalid.
process/thread.
process.
EDESTBLKD
Page 5 - 18

blocked state.
1-1600-1003-01
DSM API Library
SEE ALSO dsmd (), dsm_unrule (), dsm_getopts (), dsm_setopts (), dsm_lock (),
dsm_unlock (), dsm_list (), dsm_audit ()
5.2.11 dsm_wrrule()
DESCRIPTION
dsm_wrrule()
This function, is used to establish a read-write rule across a userspecified region of a DSM segment so that the calling process can read/write data from/to
this region with improved performance. Under normal circumstances, all read-write locks
acquired by the DSM framework require coordination between the individual instances of
the dsmd() daemon. Ruled read-write locks however do not require such communication
provided that the process/thread acquiring the lock is the one that is in charge of a readwrite rule. Ruled read-write locks have local-only context; therefore, can be directly
granted by the dsmd() daemon on the local host. Note that ruled read-write locks may not
be suitable for all applications as they implicitly assume that read-write access to the
specified region(s) of a DSM segment is by processes/threads on a specified host. If this is
not the case, one should neither establish read-write rules nor attempt to acquire readwrite locks with local-only context. When a particular process is in charge of a read-write
rule across a specified region of a DSM segment, no other process is allowed to establish
a read and/or write rule through overlapping regions of the same DSM segment.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_wrrule(int dsmid, void *addr, size_t size);
dsmid
addr
Specifies the beginning address [within the DSM segment] for the region
about to be ruled. This address should be specified on the basis of a
beginning address of the DSM segment attached.
size
Specifies the overall size [in bytes] of the region about to be ruled.
RETURN VALUES
ri
-1
On success; a non-negative integer, namely a rule identifier is returned

ERRORS
EIO

Page 5 - 19
1-1600-1003-01
EBADMSG
EBADF
EINVAL
EPERM
EAGAIN
EACCES
ENOMEM
DSM API Library

dsmid specified is invalid.
process/thread.
process.
Note: Note that the dsmd() daemon allocates various pieces of dynamic memory to store
information associated with the user requests, segments acquired, processes attached to a
specific segment, and rules established at a given time.
EDESTBLKD

blocked state.
dsm_unlock (), dsm_list,dsm_audit
5.2.12 dsm_wrrule_rec()
DESCRIPTION
dsm_wrrule_rec()
This function call is intended for use (i.e., to establish read-write
rules) under those circumstances where the data stored in a DSM segment can be viewed
as a collection of fixed size data blocks (i.e., "records"); thus, instead of specifying the
starting address and size information, application programmer can simply specify the
starting record number as well as the total number of records to be ruled using the from
and cnt function arguments, respectively. Records in each DSM segment are numbered by
Application programmers interested in using the record-based DSM ruling capabilities
segment identifier is acquired using the dsm_get() function call. By default, the record
size for each DSM segment will be initialized to the value of the DSM_DEFBLKSIZE
A noteworthy point in using the record-based DSM ruling capabilities is in regard to the
behavior of record-based rules in the existence of multiple attaches of a particular DSM
segment (i.e., by the calling process). Since record-based DSM rules are not associated
with a particular attachment, detaching individual copies of the segment does not cause
automatic removal of the rules established by the calling process across the corresponding
Page 5 - 20
1-1600-1003-01
DSM API Library
segment. It is only when all attached copies of a DSM segment are detached, the recordbased rules for that segment will be removed.
MT LEVEL
MT- Safe
SYSNOPIS
int dsm_wrrule_rec(int dsmid, int from, int cnt);
dsmid
from
The staring record number to be viewed.
cnt
The total number of records tobe viewed.
RETURN VALUES
ri
-1
On success; a non-negative integer, namely a rule identifier is returned

On failure; and errno is set to indicate the error.
ERRORS
EIO
EBADMSG
EBADF
EINVAL
EPERM
EAGAIN
EACCES
ENOMEM

process/thread.
process.
Note: Note that the dsmd() daemon allocates various pieces of dynamic memory to store
information associated with the user requests, segments acquired, processes attached to a
specific segment, and rules established at a given time.
EDESTBLKD

blocked state.
dsm_unlock (), dsm_list,dsm_audit
Page 5 - 21
1-1600-1003-01
DSM API Library
5.2.13 dsm_setopts()
DESCRIPTION
dsm_setopts()
Set DSM optional parameters. This function call is used to
manipulate (according to data supplied by the calling process) the current settings of
distributed shared memory (DSM) related parameters associated with a particular DSM
segment and in use by the calling process. These parameters include the data block
(record) size and the read-write lock options for all copies of the DSM segment attached
by the calling process.
The data block size information about a DSM segment should be manipulated only when
the application programmer is interested in exercising the record-based DSM lock
capabilities (via the dsm_rdlock_rec() and dsm_wrlock_rec() function calls) and the
default block size specified via the DSM_DEFBLKSIZE parameter is not suitable.
Information about the read-write lock options for a DSM segment should only be
manipulated in stand-alone configurations, to improve overall DSM performance. Note
that these options control whether an automatic backup of the affected portions of a DSM
segment should be generated by the system when a read-write lock is acquired by an
application. An attempt to set the read-write lock options to DSM_NOBACKUP in the
distributed mode of operation shall result in the failure of the dsm_setopts() function as
this setting will jeopardize the release-consistency model employed by the Distributed7
DSM framework.
Note that if a DSM segment has been attached multiple times by the calling process, the
dsm_setopts() function call shall cause the aforementioned parameters associated with all
copies of the DSM segment to be modified.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_setopts(int dsmid , dsmopts_t * opts );
dsmid
opts
Pointer value that indicates the location of a data structure as follows:
typedef struct {
size_t dsm_blksize; /* data block size */
word_t dsm_lockopt; /* read-write lock options */
#define DSM_BACKUP 0
/* auto backup */
#define DSM_NOBACKUP 0x0001 /* disable auto backup */
word_t dsm_pad;
} dsmopts_t;
Page 5 - 22
/* reserved for future use */
1-1600-1003-01
DSM API Library
RETURN VALUES
0
-1
On success; data structures associated with all copies of the DSM

segment currently attached by the calling process are manipulated to set
optional parameters as specified in the data structure pointed to by the
opts argument.
ERRORS
<EACCES>::DSM segment specified is not attached to the data
segment of the calling process.
<EAGAIN>::Operation is not permitted at this time since the
calling process currently has locks established
across the DSM segment specified.
SEE ALSO dsmd, dsm_getopts()
5.2.14 dsm_setstat()
DESCRIPTION
dsm_setstat()
Set DSM segment status. This function call is used to manipulate
selected pieces of information about a distributed shared memory (DSM) segment
according to data supplied by the calling process. This information includes the access
permissions and the effective user/group ID's for the segment.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_setstat(int dsmid , dsmstat_t * dsmstat );
dsmid
dsmstat
Pointer value; indicates location of a data structure whose selected
members are used when manipulating the DSM segment information.
These members are as follows:
typedef struct {
...
int dsm_mode; /* access permissions */
Page 5 - 23
1-1600-1003-01
uid_t dsm_uid;
gid_t dsm_gid;
} dsmstat_t;
DSM API Library
/* owner's effective user id */

/* owner's effective group id */
This command can be executed only by a process that has an effective user ID of super
user (root) or to the owner of the DSM segment (the process that created the segment in
the first place).
RETURN VALUES
0
-1
On success; the appropriate members of the data structure associated

with the DSM segment are set to the corresponding values found in the
data structure pointed to by the stat argument.
ERRORS
<EPERM>::Effective user ID of the calling process is neither equal
to that of super user (root) or the owner (the
process that created the segment in the first place)
of the DSM segment.
blocked state.
involved.
SEE ALSO dsmd, dsm_getstat(), dsm_stat
Page 5 - 24
1-1600-1003-01
DSM API Library
5.2.15 dsm_unlock()
DESCRIPTION
dsm_unlock()
Unlock DSM segment. This function call is used to release a
read-only or read-write lock established earlier by the calling process across a distributed
shared memory (DSM) segment.
Under normal circumstances, a lock that has been acquired by a particular process should
be released by the very same process by issuing the dsm_unlock() function call. Note that
a failure to do so may result in lock requests by other processes being placed on hold
indefinitely. If a process that is in charge of one or more locks exits prematurely, without
releasing all the locks acquired earlier, the system will automatically release these locks
on behalf of the calling process.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_unlock(int dsmid , int lockid , int opt );
dsmid
lockid
Identifies a read-only or read-write lock that has been previously
established by the calling process using the dsm_rdlock() or
dsm_wrlock() function calls (or their equivalents).
opt
Control flag that may assume a value from the following list:
DSM_COMMIT Commit and distribute changes (if any)
incorporated in the contents of the locked region of the DSM
segment. This is the default option.
DSM_REVERT Discard changes (if any) incorporated in the
contents of the local copy of the locked region of the DSM segment.
Important: The DSM_COMMIT and DSM_REVERT options are only meaningful when
releasing a read-write lock. Since write operations are not permitted when holding readonly locks, either option has no meaning for read-only locks; thus, will simply be ignored if
specified. Also note that the DSM_REVERT option assumes that a backup copy of the
appropriate region of the segment has been generated by the system at the time of acquiring
the lock. Note however that this backup/revert capability can be disabled on a stand-alone
system using the dsm_setopts() function. It is important to emphasize here that the
Distributed7 DSM framework is release-consistent; changes made to a local copy of a DSM
segment (after acquiring a read-write lock) will not be propagated to other hosts in the network until the process holding the read-write lock releases it by issuing the dsm_unlock()
function call.
Page 5 - 25
1-1600-1003-01
DSM API Library
RETURN VALUES
0
-1
On success.
ERRORS
Important: The dsmd daemon allocates various pieces of dynamic memory to store information associated with the user requests, segments acquired, processes attached to a specific
blocked state.
SEE ALSO dsmd, dsm_lock(), dsm_getopts(), dsm_setopts(), dsm_list, dsm_audit
5.2.16 dsm_unrule
DESCRIPTION
dsm_unrule
Used to delete a read-only or read-write rule established earlier by the

calling process across a distributed shared memory (DSM) segment.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_unrule(int dsmid,int ruleid);
dsmid
calling process previously using the dsm_get() and dsm_attach()
ruleid
Identifies a read-only or read-write rule that is established by the calling
process previously using the dsm_rdrule() or dsm_wrrule() function
calls [or their equivalents].
RETURN VALUES
0
On success.
-1
Page 5 - 26
1-1600-1003-01
DSM API Library
ERRORS
EIO
EBADMSG
EBADF
EINVAL
EACCES
ENOMEM

received from thedsmd(1D) daemon.
process.
EDESTBLKD

blocked state.
SEE ALSO dsmd, dsm_rule (), dsm_getopts (), dsm_setopts (), dsm_list, dsm_audit
Note: Under normal circumstances, a rule that has been established by a particular process
should be deleted by the very same process by issuing the dsm_unrule() function call. Note
that a failure to do so may result in rule requests by other processes to be placed on hold
indefinitely. If and when a process that is in charge of one or more rules exits prematurely
(i.e., without deleting all the rules established earlier), the system will automatically delete
these rules on behalf of the calling process.
5.2.17 dsm_wrlock()
DESCRIPTION
dsm_wrlock() This function call is used to instantiate a read-write lock across a userspecified region of a DSM segment so that the calling process can safely read/write data
from/to this region. When a particular process holds a read-write lock across a specified
region of a DSM segment, no other process is allowed to read and/or write data through
overlapping regions of the same DSM segment, ensuring that write operations through
overlapping regions of a DSM segment are exclusive.
When the individual processes attached to a DSM segment make use of the dsm_rdlock()
and dsm_wrlock() functions (in conjunction with the dsm_unlock() function call), every
single time they read and/or write through a DSM segment, the consistency of the
segment is guaranteed by the system. Attempts to read/write from/to a DSM segment
without acquiring appropriate locks are strictly discouraged, because these operations are
likely to result in severe corruptions and/or inconsistencies in data across the individual
hosts.
Page 5 - 27
1-1600-1003-01
DSM API Library
It is important to emphasize here that the Distributed7 DSM framework is releaseconsistent. Changes made to a local copy of a DSM segment (after acquiring a read-write
lock) are not propagated to other hosts in the network until the process holding the readwrite lock releases the lock by invoking the dsm_unlock() function call. Also note that
when an attempt is made by a process to acquire a read-write lock, the system will
normally create a backup copy of the data in the region spanned by the lock requested by
the process; refer to dsm_setopts() regarding exceptions to this rule. Through this
mechanism, the calling process has the option to either discard all changes made in the
contents of the locked region (if contents are deemed invalid) or alternatively commit and
distribute the contents to other hosts in the network at a later time, by invoking the
dsm_unlock() function call.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_wrlock(int dsmid , void * addr , size_t size , int opt );
dsmid
addr
Specifies the beginning address, within the DSM segment, for the region
about to be locked. This address should be specified on the basis of a
beginning address of the attached DSM segment.
size
Specifies the overall size, in bytes, of the region about to be locked.
opt
DSM_WAIT
the lock requested can be established right away, do so. Otherwise, do
not wait and simply return an error.
hosts; thus, they are costly from a performance point of view. One exception to this is rulebased DSM locks -- see man pages for dsm_rule(). Rule-based read-write locks have
applications. Nevertheless, provided that it makes sense for an application to use rule-
Page 5 - 28
1-1600-1003-01
DSM API Library
based DSM locking and the application has established all appropriate read-write rules
using an appropriate dsm_rule() function upfront, it can acquire read-write locks with
lock requests.
RETURN VALUES
int
-1

to the user.
ERRORS
<EDESTBLK>::At least one of the dsmd daemon processes is in
blocked state.

dsm_audit
Page 5 - 29
1-1600-1003-01
DSM API Library
5.2.18 dsm_wrlock_rec()
DESCRIPTION
dsm_wrlock_rec()
This function call is provided to acquire read-write locks under
those circumstances where the data stored in a DSM segment can be viewed as a
collection of fixed-size data blocks (records). This function call allows the application
programmer to simply specify the starting record number and the total number of records
to be locked using the from and cnt function arguments respectively, instead of specifying
the starting address and size information. Records in each DSM segment are numbered by
Application programmers interested in using the record-based DSM locking capabilities
segment identifier is acquired using the dsm_get() function call. By default, the record size
for each DSM segment will be initialized to the value of the DSM_DEFBLKSIZE
A noteworthy point in using the record-based DSM locking capabilities is in regard to the
behavior of record-based locks in the existence of multiple attaches of a particular DSM
segment by the calling process. Since record-based DSM locks are not associated with a
particular attachment, detaching individual copies of the segment does not cause
automatic release of the locks established by the calling process across the corresponding
segment. Only when all attached copies of a DSM segment are detached, will the recordbased locks for that segment be released.
MT LEVEL
MT- Safe
SYNOPSIS
int dsm_wrlock_rec(int dsmid , int from , int cnt , int opt );
dsmid
from
Specifies the first record number from a set of records to be locked.
cnt
Specifies the total number of records to be locked. Records in each DSM
segment are numbered by the system in a sequential manner, starting
from 1.
opt
DSM_WAIT
Page 5 - 30
1-1600-1003-01
DSM API Library

the lock requested can be established right away, do so. Otherwise,
do not wait and simply return an error.
hosts; thus, they are costly from a performance point of view. One exception to this is
rule-based DSM locks -- see man pages for dsm_rule(). Rule-based read-write locks have
applications. Nevertheless, provided that it makes sense for an application to use rulebased DSM locking and the application has established all appropriate read-write rules
using an appropriate dsm_rule() function upfront, it can acquire read-write locks with
lock requests.
RETURN VALUES
int
-1

to the user.
ERRORS
blocked state.
Page 5 - 31
1-1600-1003-01
DSM API Library

dsm_audit
Page 5 - 32
1-1600-1003-01
Chapter 6:
6.1
Alarm API Library
Alarm API Library
Chapter Overview
This chapter provides the alarm (ALM) Application Programming Interface (API) library
calls for NewNet Communication Technologies, LLC Distributed7 software products.
6.2
Alarm API Library

The alarm API library allows application programmers with a small set of function calls to
report and/or detect alarm conditions while operating under the Distributed7 environment.
The most noteworthy function included in the alarm API library is the alm_notify() function
call which allows an application program to detect alarm conditions of interest in an
asynchronous manner and act upon them. This function is based on the general-purpose
spm_notify() function that is part of the SPM API library and is intended for automatic
detection of M_ALARM events only. Using the alm_notify() function, an application can
equip itself with the logic to detect all alarm conditions of interest under a distributed
Distributed7 environment and perform local processing until an alarm condition of interest
occurs. Note that the use of this function alleviates the need for customizing the behavior of
the alarmd daemon by editing and customizing the AlarmExt.c source file that is provided
under the $EBSHOME/access/sample/alarm product directory and re-compiling/linking
the alarmd daemon in order for the changes made to take effect. It also allows different
applications to express interest in different alarm conditions and be informed about such
conditions in an independent as well as transparent manner.
Other functions included in the alarm API library allow applications to report their alarm
conditions to the local alarmd daemon and have the alarmd daemon to notify the SNMP
agent on the local host about specified alarm conditions so that traps can be generated/sent
to external network management entities if and when appropriate.
Application programs interested in using the functions included as part of the alarm API
library are required to include the following header files in the given order:
#include <api.h>
#include <alarm.h>
The alarm API library is located under the $EBSHOME/access/lib directory is called
libalarm.a. Applications programmers interested in using the capabilities of this library
should be compiled/linked as follows:
Page 6 - 1
1-1600-1003-01
Alarm API Library
Programs written in the C language should be compiled first using the cc compiler and
then linked with the libalarm.a library using the CC command:
cc -c file.c -I $EBSHOME/access/include
CC file.o -L $EBSHOME/access/lib-lalarm -lcnfg -ldbms -lapm -lspm -linet -lnsl
Programs written in the C++ language should be compiled/linked directly with the
libalarm.a library using the CC command:
CC file.C -I $EBSHOME/access/include
-L $EBSHOME/access/lib-lalarm -lcnfg -ldbms -lapm -lspm -linet -lnsl
On-line reference manuals for the API library calls are provided in the form of manual pages
so that the user can invoke the UNIX standard man(1) utility to review the information
contained in them. The user should expand the MANPATH environment variable to include
the $EBSHOME/access/manpages directory in the search path.
Important: Distributed7 1.2. ALARM API is multi-thread (MT) Safe, and can be used with
6.2.1
alm_notify()
DESCRIPTION
alm_notify()
This function is used for alarm event notification. It can be used
by an application program to express interest in a particular set of alarm events that can
occur while operating under the Distributed7 environment and specify what action should
take place if, and when, one of the pending alarm events occurs. Thus, it enables an
application program to do asynchronous input/output processing, i.e., an application
program may wish to do some local processing and be interrupted when a pending alarm
event occurs. It is important to emphasize here that application programs interested in
performing asynchronous I/O operations through a service endpoint should specify the
0_NONBLOCK flag when establishing that endpoint using the spm_open() function.
MT LEVEL
MT-Safe
SYNOPSIS
int alm_notify(int fd, char * hostname, int grp, int mod, int num, int sev,
void (*func) (int) );
fd
hostname
This argument is a character string that specifies the name of the host that
the process calling alm_notify() is interested in. hostname may be the
name of the local host, if the process is interested in alarms occurring on
the local host, or any other host in the network. A NULL value or "*"
specifies that the process is interested in alarms occurring on all hosts. If
the alarm, as specified by other arguments, occurs on a host that is
Page 6 - 2
1-1600-1003-01
grp
mod
num
sev
Alarm API Library
specified by hostname, the user-specified func function should

automatically be invoked.
This argument is an integer that specifies the group of alarms which the
process is interested in. The system alarms have been categorized into
various groups. Each group is responsible for different types of alarms.
The system alarm categories range from hexadecimal value 0x80 to
0xFF. All the user alarms should be defined below 0x80. Information
about alarm groups can be found within the alarmGroups file under the
$EBSHOME/access/RUN/config/ALARM directory. The grp argument
accepts decimal values. A wildcard can be used, if -1 is entered, it is
assumed that the process is interested in all groups. If the wildcard is
used for grp, both the mod and num arguments are also assumed to have
wildcard values. That is, if grp is a wildcard, mod and num cannot have
specific values.
This argument is an integer that specifies the module of the alarm, in a
particular alarm group specified by the grp argument, which the user is
interested in. Each alarm group has several modules. Information about
the modules in an alarm group can be found within the
GroupName_almTxt files under the $EBSHOME/access/RUN/config/
ALARM directory. The mod argument accepts decimal values. A
wildcard can be used, if -1 is entered it is assumed that the process is
interested in all modules in a specific alarm group. If a wildcard is used
for mod, then the num argument is assumed to have a wildcard value.
That is, if mod is a wildcard, num cannot have a specific value.
This argument is an integer that specifies the number of the alarm in a
particular group specified by the grp argument and a particular module
specified by the mod argument, which the user process is interested in.
Information about alarm types can be found within the
ALARM directory. The num argument accepts decimal values. A
wildcard can be used, if -1 is entered, it is assumed that the process in
interested in all alarms in a specific alarm group and module.
This argument is a bitmask that specifies the severities in which the user
is interested. Alarm text files may be different on different hosts, that is,
an alarm may have a severity value of MAJOR on one host and a value of
CRITICAL on another host. A wildcard, -1, may be used to specify that
the process is interested in all severity levels, or when the user calls the
alm_notify() function, the sev argument can be constructed by bitwise
OR-ing any combination flags from the following list:
L_SEVINFO (0x01) - The user process wants to be notified if the
specified alarm with severity level INFO occurs.
L_SEVMINOR (0x02) - The user process wants to be notified if the
specified alarm with severity level MINOR occurs.
Page 6 - 3
1-1600-1003-01
Alarm API Library
L_SEVMAJOR (0x04) - The user process wants to be notified if the

specified alarm with severity level MAJOR occurs.
L_SEVCRITICAL (0x08) - The user process wants to be notified if
the specified alarm with severity level CRITICAL occurs.
L_SEVFATAL (0x10) - The user process wants to be notified if the
specified alarm with severity level FATAL occurs.
This argument specifies the user function that should be automatically
called when the user specified alarm event occurs on the specified host.
At the time func is invoked, the file descriptor that is associated with the
service endpoint at which a particular alarm event has occurred, will be
passed as an argument to func.
func
EXAMPLES
A TCAP alarm definition:
@@Alarm
950101
CRITICAL
EVENT
TCAP: TCMD daemon is not executing
If the user process is interested in this alarm, with severity CRITICAL on all hosts, it should
call:
alm_notify(fd, "*", 149, 1, 1, L_SEVCRITICAL, func);
If the user process is interested in all TCAP alarms with severity CRITICAL on all hosts, it
should call:
alm_notify(fd, "*", 149, -1, -1, L_SEVCRITICAL, func);
If the user process is interested in all MAJOR alarms on "host_x", it should call:
alm_notify(fd, "host_x", -1, -1, -1, L_SEVMAJOR, func);
SEE ALSO alm_report(), spm_notify(), spm_trigger()
6.2.2
alm_report()
DESCRIPTION
alm_report()
This function can be used for generating a user-specified alarm
condition by populating and sending a message to the Distributed7 alarm handler process
via a specified service endpoint associated with the user process identified by the fd
argument.
MT LEVEL
MT-Safe
SYNOPSIS
int alm_report(int fd, int sp, int grp, int mod, int typ, int sev, optparam_t param1,
optparam_t param2, almparam_t * paramrest, char * buf);
Page 6 - 4
1-1600-1003-01
fd
sp
grp
mod
typ
sev
param1
param2
paramrest
buf
Alarm API Library

This argument identifies the signaling point associated, if any. If no
signaling point is associated with the alarm specified, an sp value of
L_SP_NA should be specified.
This argument specifies the group of the alarm which the process is
interested in generating. The system alarms have been categorized into
various groups. Each group is responsible for different types of alarms.
The system alarm categories range from hexadecimal value 0x80 to
0xFF. Therefore, all user alarms should be defined below 0x80.
Information about alarm groups can be found within the alarmGroups
file under the $EBSHOME/access/RUN/config/ALARM directory.
This argument specifies the module of the alarm, in a particular alarm
groups specified by the grp argument, which the user is interested in
generating. Each alarm group may have several modules. Information
about the modules in an alarm group can be found within the
ALARM directory.
This argument specifies the type of the alarm, in a particular group
specified by the grp argument and a particular module specified by the
mod argument, which user process is interested in generating.
Information about alarm types can be found within the
ALARM directory.
This argument specifies the severity of the alarm message to be
generated. The value is assumed from the following list:
L_ALMLVL_INFO - trigger an alarm with the severity INFO
L_ALMLVL_MINOR - trigger an alarm with the severity MINOR
L_ALMLVL_MAJOR - trigger an alarm with the severity MAJOR
L_ALMLVL_CRITICAL - trigger an alarm with the severity
CRITICAL
L_ALMLVL_FATAL - trigger an alarm with the severity FATAL
These arguments can be used to specify the values of application specific
parameters associated with the alarm and their use is optional. User
applications can specify a param1 and/or param2 value of NO_PARAM
to indicate the lack of either or both parameters. Similarly, a NULL value
of paramrest indicates to the system that the rest of the parameters are not
applicable.
This argument points to a user buffer which contains the NULLterminated character string that gets copied into the data portion of the
IPC message to be sent to the alarm handler process. The remainder of
the alarm message is populated by the alm_report() function
automatically and is routed to its destination as a normal (non-expedited)
Page 6 - 5
1-1600-1003-01
Alarm API Library
IPC message using the spm_snd() function. However, a check is

conducted prior to sending the message to verify that the alarm handler
process is currently running.
RETURN VALUES
0
-1
On success.
On failure, errno is set to indicate the error.
ERRORS
<EBADF>::File descriptor specified is invalid.
<ESRCH>::The alarm handler process is not running.
SEE ALSO alm_notify(), spm_alarm()
6.2.3
alm_trap()
DESCRIPTION
alm_trap()
This function can be used to notify the Simple Network
Management Protocol (SNMP) agent on the local host so that a trap can be generated and
sent to external network management entities regarding an alarm condition encountered
on the local host.
This function should only be invoked from the P_AlarmExt() function, whose definition
is given in the AlarmExt.c source file that can be used to customize the behavior of the
alarmd daemon process. Under normal circumstances, SNMP traps should be generated
for alarm conditions of severity value L_ALMLVL_CRITICAL or higher; however, it is
up to the programmer to determine the specifics of conditions about which external
network management entities should be notified via SNMP traps.
MT LEVEL
MT-Safe
SYNOPSIS
int alm_trap(int fd, APIalarm_t * alarm);
fd
This argument identifies the endpoint to be used to communicate with the
local SNMP agent.
alarm
This argument points to a user-space buffer which contains information
about the alarm condition that occurred.
RETURN VALUES
0
Page 6 - 6
On success.
1-1600-1003-01
-1
Alarm API Library
ERRORS
<EINVAL>:: Alarm condition is not associated with a particular
signaling point.
<ESRCH>::The SNMP agent is not running.
<EDESTBLKD>::The SNMP agent is in blocked state.
FILES
$EBSHOME/access/sample/alarm/AlmExt.c
$EBSHOME/access/sample/alarm/README
SEE ALSO alarmd
Page 6 - 7
1-1600-1003-01
Alarm API Library
Page 6 - 8
1-1600-1003-01
Chapter 7:
7.1
Using the MTP API Library
MTP API Library
Chapter Overview
This chapter provides the alphabetical listings of the Message Transfer Part (MTP)
Technologies, LLC, Inc. Distributed7 software products.
7.2
Using the MTP API Library

The MTP API library is provided for decoding and encoding of MTP primitives. These calls
are typically made in the following cases:
to send an MSU to the SS7 network

after an spm_rcv() call indicating that an MTP indication is received
get information of the current MTP configuration
pointcode encode/decode operation with the current MTP setting
Prior to calling any MTP API library function, the mtp_init_api() function must be called in
order to initialize the MTP library. If mtp_init_api() fails, the process must immediately
terminate (do not continue operation). Once mtp_init_api() succeeds, any MTP API library
function can be used.
When sending an MSU, the user fills in the parameter block mtpxfer_t and makes the
mtp_xfer_req() call.
When an MTP indication is received, the user passes the pointer to a parameter block
matching with the indication type (e.g. mtpflow_t structure pointer for MTP_STATUS,
MTP_PAUSE, and MTP_RESUME primitives, mtpinfo_t structure pointer for MTP_INFO
primitive, mtpxfer_t for MTP_TRANSFER primitive) and makes the proper call.
When the user wants to retrieve information about the current MTP configuration, the
proper function is called with the signaling point number (mtp_spc(), mtp_ni(),
mtp_pc_bytes(), ...).
When a pointcode conversion (encoding/decoding) is necessary, the current pointcode size
and protocol of MTP database must be used. To do this the user must call the pointcode
conversion functions the MTP API Library.
Page 7 - 1
1-1600-1003-01
7.2.1
MTP API Library
Routing Type Definition

For the functions which use the mtpxfer_t structure, the routing type is an important piece of
information. The adpc_rttype field of the structure identifies the routing type of the
concerned destination. The routing type determines the scope of the effected destination.
The application must evaluate this information to determine the status of the individual
destinations.
If an indication is received for a destination which has NETWORK routing, all destinations
having the same network ID are affected. If the routing type is CLUSTER, then all
destinations having the same network ID and cluster ID combination in their point code are
affected. However, if the routing type is MEMBER, then only the single concerned
destination is affected.
The possible values for the adpc_rttype field are defined in the <sap_mtp.h> header file as
follows:
#define MEMBER_TYPE
0 (Single destination)
#define CLUSTER_TYPE
1 (All destinations in Network-Cluster-* cluster)
#define NETWORK_TYPE
2 (All destinations in Network-*-* network)
Important: In generic CCITT, only the MEMBER type is valid. In ANSI and CHINA
networks, all routing types are valid.
Example 1
If a user receives a PAUSE indication for a destination with point code 3-14-0 and routing
type is CLUSTER, then all the following destinations must be marked inaccessible:
3-14-0, 3-14-1, 3-14-2, 3-14-3, 3-14-4, 3-14-5,..., 3-14-255
Example 2
If a user receives a RESUME indication for a destination with point code 254-0-0 and
routing type is NETWORK, then all the following destinations must be marked accessible:
254-0-0, 254-0-1, 254-0-2,..., 254-0-255
254-1-0, 254-1-1, 254-1-2,..., 254-1-255
....
254-255-0, 254-255-1, 254-255-2,..., 254-255-255
Example 3
If a user receives a STATUS indication for a destination with point code 7-123-5 and routing
type is MEMBER, then the congestion status of only this destination has changed.
7.3
MTP API Library

MTP primitives are designed to operate with ITU (CCITT) and ANSI MTP. To use the MTP
function calls, the following header files must be included at the beginning of the
Page 7 - 2
1-1600-1003-01
MTP API Library
application in the given order:

#include <api.h>
#include <mtp.apiproto.h>
#include <sap_mtp.h>
The MTP library (libmtp.a) should be accessed using the $EBSHOME/access/lib path and
linked with a user application (called file.c in the examples) as shown below. ($EBSHOME
is an environment variable holding the pathname of where the Distributed7 software is
installed.)
Example:
cc file.c
-I$EBSHOME/access/include
-L$EBSHOME/access/lib
-lmtp -lspm -lnsl
A sample source code file, mtptest.c, is provided to demonstrate the use of Distributed7
MTP literals and functions. It should be compiled with the MAKEFILE in the
$EBSHOME/access/sample/mtp directory. After it is compiled, the executable will be
located in the $EBSHOME/access/demo directory.
Important: Distributed7 1.2. MTP API is multi-thread (MT) Safe, and can be used with
Page 7 - 3
1-1600-1003-01
7.3.1
MTP API Library
mtp_decode_pc()
DESCRIPTION
mtp_decode_pc()
Converts a string pointcode, pointed to by str_pc, to an integer
value pointed to by int_pc.
The mtp_init_api() function must be called before this function is used.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_decode_pc(int sp , char * str_pc , int * int_pc );
sp
The format of the string pointcode must be three numbers separated by dashes: zid-aid-sid.
zid identifies the zone (network)
aid identifies the area (cluster)
sid identifies the signaling point (member).
The valid range of a pointcode value depends on the pointcode size of the signaling point.
14 bit pointcode - Bit map is (3-8-3), the valid range is from 0-0-1 to 7-255-7
The pointcodes 0-0-0 and 0-0-2 are reserved and are not allowed to be used.
RETURN VALUE
0
-1
On success.
ERRORS
<EPROTNOTSET>::MTP protocol has not been set.
<EINVPC>::Invalid point code is given.
<EPCNOTVALID>::Pointcode is not compatible with the current MTP
protocol of the signaling point.
SEE ALSO mtp_init_api(), mtp_encode_pc()
Page 7 - 4
1-1600-1003-01
7.3.2
MTP API Library
mtp_dest_stat()
DESCRIPTION
mtp_dest_stat()
Retrieves the state (tsrc) of the requested destination.

MT-LEVEL
MT-Safe
SYNOPSIS
mtp_dest_stat (sp, dword_t, pc, fd);
sp
pc
fd
Specifies the signaling point. It is an unsigned integer from to 7.

The dword_t formatted point code of the destination.
Valid file descriptor bound to the UPM service provider.
RETURN VALUE
MTP_DPC_INACCESSIBLE
MTP_DPC_ACCESSIBLE
MTP_DPC_RESTRICTED
On success.
-1
ERRORS
<EBADF>::Invalid File Descriptor
<EINVAL>::Invalid sp number associated with the given file
descriptor fd
<EPROTNOTSET>::MTP protocol has not been set
SEE ALSO mtp_init_api(), mtp_subpc2pc(), mtp_pc2network(), mtp_pc2member(),

mtp_pc2cluster().
Page 7 - 5
1-1600-1003-01
7.3.3
MTP API Library
mtp_encode_pc()
DESCRIPTION
mtp_encode_pc()
Converts an integer pointcode, pointed to by int_pc, to a string
pointcode pointed by str_pc.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_encode_pc(int sp , int int_pc , char * str_pc );
sp
This function features the reverse operation of mtp_decode_pc(). This is to say that the
integer pointcode int_pc must previously be decoded by mtp_decode_pc().
The format of the string pointcode must be three numbers separated by dashes: zid-aid-sid.
zid identifies the zone (network)

aid identifies the area (cluster)
sid identifies the signaling point (member).
RETURN VALUE
0
-1
On success.
ERRORS
<EINVPC>::Invalid point code is given.
<EPCNOTVALID>::Pointcode is not compatible with the current MTP
protocol of the signaling point.
SEE ALSO mtp_init_api(), mtp_decode_pc()
Page 7 - 6
1-1600-1003-01
7.3.4
MTP API Library
mtp_flow_ind()
DESCRIPTION
mtp_flow_ind()
flow primitive.
Extracts flow data from an incoming message having an MTP

MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_flow_ind(ipcmsg_t * msg , mtpflow_t * mtpflow );
msg
This argument points the user buffer which includes the incoming
message received by the spm_rcv() library function.
mtpflow
This argument points a user buffer where the MTP primitive data will be
filled to.
The possible MTP flow primitives are as follows;
MTP_PAUSE - Received when a remote destination becomes inaccessible.
MTP_RESUME - Received when a remote destination becomes accessible.
MTP_STATUS - Received when a remote destination becomes congested or a user part
on a remote destination is not available.
The adpc_rttype field of the structure mtpflow_t indicates the routing type of the
destination affected. The valid routing types and the action that the user must take are
defined below.
MEMBER_TYPE - The remote destination is a member, apply the change only on this
destination.
CLUSTER_TYPE - The remote destination is a cluster, apply the change on all the
destinations in this cluster.
NETWORK_TYPE - The remote destination is a network, apply the change on all the
destinations in this network.
The type field of the structure mtpflow_t indicates two different condition of a remote
destination. In each case the status field has different meaning.
CONG_TYPE - The congestion status of the remote destination has changed. In this
case the status field indicates the new congestion status.
UPU_TYPE - The user part on the remote destination is currently not available. In this
case the status field indicates the cause of the remote users unavailability.
Page 7 - 7
1-1600-1003-01
MTP API Library
RETURN VALUE
0
-1
On success.
ERRORS
<EINVAL>::Invalid sp number in message
SEE ALSO mtp_init_api(), spm_rcv()
Page 7 - 8
1-1600-1003-01
7.3.5
MTP API Library
mtp_info()
DESCRIPTION
mtp_info()
Retrieves the current MTPL3 information of the signaling point.

MT-LEVEL
MT-Safe
SYNOPSIS
void mtp_info(int sp, mtpinfo_t * mtpinfo );
sp
This argument is the signaling point to retrieve the MTP information for.
It can be any value from 0 to 7.
mtpinfo
This argument points to a user buffer where the MTP data will be placed.
The structure is defined in the <sap_mtp.h> header file.
SEE ALSO mtp_init_api()
Page 7 - 9
1-1600-1003-01
7.3.6
MTP API Library
mtp_info_ind()
DESCRIPTION
mtp_info_ind()
Extracts MTP level-3 specific data from an incoming message
carries the MTP_INFO primitive.
SYNOPSIS
void mtp_info_ind(ipcmsg_t * msg , mtpinfo_t * mtpinfo );
msg
mtpinfo
This argument points a user buffer where the MTP primitive data will be
placed. The structure is defined in the <sap_mtp.h> header file.
Page 7 - 10
1-1600-1003-01
7.3.7
MTP API Library
mtp_init_api()
DESCRIPTION
mtp_init_api()
Initializes the MTP library.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_init_api(int sp , int fd );
sp
fd
This argument specifies a valid file descriptor which has been bound to
Distributed7 environment. The bind operation makes use of the SPM
library functions spm_open() and spm_bind().
This function will initialize an internal structure which includes the MTP
level-3 (MTP/L3) specific information of the signaling point. This
information will be used to perform the other MTP library functions
which requires some MTP/L3 information such as; protocol, own point
code, network indicator and pointcode size.
This argument is optional. If fd is valid, then the MTP library sets a
notification which will be informed whenever a modification in MTP/
L3m is done. Consequently all other MTP library calls will retrieve/use
the latest MTP/L3 information. If fd is set to NULL, then only the current
MTP/L3 data will be retrieved once, and the subsequent modifications in
MTP/L3 will not be reflected to the MTP library.
RETURN VALUE
0
-1
On success.
ERRORS
<EINVAL>::Invalid sp number given
<EBADF>::Bad file descriptor.
SEE ALSO spm_bind(), spm_open()
Page 7 - 11
1-1600-1003-01
7.3.8
MTP API Library
mtp_intercept_req ()
DESCRIPTION
mtp_intercept_req () This function is used to send an intercept request for the user part
messages. The user part information is extracted using fd. The mtp_init_api() function
must be called before this function is used.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_intercept_req (int fd, int cmnd);
fd
This argument must be a valid file descriptor bound to the UPM service
provider.
cmnd
This argument gives the information about whether interception of the
messages needs to be started or stopped. The values that can be used are:
L_START_INTERCEPT
L_STOP_INTERCEPT
RETURN VALUE
0
-1
On success.
ERRORS
<EBADF>::Invalid file descriptor.
SEE ALSO mtp_intercept_ind (), mtp_init_api()
Page 7 - 12
1-1600-1003-01
7.3.9
MTP API Library
mtp_intercept_ind ()
DESCRIPTION
mtp_intercept_ind ()
This function is used to parse an MSU (Message Signal Unit)
and extracts MTP (Message Transfer Part) specific data into a user buffer. The
mtp_init_api() function must be called before this function is used.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_intercept_ind (ipcmsg_t *msg, mtpxfer2_t *mtpxfer);
msg
mtpxfer
This argument points a user buffer where the MTP user data will be filled
to. This function must only be called if the primitive of the incoming
message is set to MTP_INTERCEPT_IND. The primitive is carried into
the msgtyp field of the ipcmsg_t structure.
RETURN VALUE
0
-1
On success.
ERRORS
<EPMTCH>::Primitive type mismatch
<EMSGSIZE>::Incoming MSU size exceeds maximum MSU size
SEE ALSO mtp_intercept_req (), mtp_init_api(), spm_snd()
Page 7 - 13
1-1600-1003-01
MTP API Library
7.3.10 mtp_ni()
DESCRIPTION
mtp_ni()
This function is used to retrieve the network indicator of the MTP
layer-3 of the signaling point.
MT-LEVEL
MT-Safe
SYNOPSIS
unsigned char mtp_ni(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the network indicator.

The network indicator value can be one of the following:
NI_INTNW - international network.

NI_INTSPARE - International network, with spare bit set.
NI_NATNW - National network.
NI_NATSPARE - National network with spare bit set.
ERRORS
<EINVAL>::Invalid sp number.
<EPROTNOTSET>::MTP protocol is not set.
Page 7 - 14
1-1600-1003-01
MTP API Library
7.3.11 mtp_pc_bytes()
DESCRIPTION
mtp_pc_bytes()
Retrieves the pointcode size of the MTP layer-3, in bytes.

MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_pc_bytes(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the pointcode size, in bytes.

The pointcode size in bytes value can be one of the following:

2 - for 14 bit and 16 bit pointcodes
3 - for 24 bit pointcodes
ERRORS
Page 7 - 15
1-1600-1003-01
MTP API Library
7.3.12 mtp_pc_size()
DESCRIPTION
mtp_pc_size()
Retrieves the pointcode size type of the MTP layer-3.

MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_pc_size(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the pointcode size type.

The return value can be one of the following:

OPT_PC14 - 14 bit point code
ERRORS
Page 7 - 16
1-1600-1003-01
MTP API Library
7.3.13 mtp_pc2cluster()
DESCRIPTION
mtp_pc2cluster()
Extracts the cluster portion of a point code on a specified
signaling point. If the point code is in xxx-yyy-zzz format, then the cluster is the yyy
portion.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_pc2cluster(int sp, dword_t pc);
sp
This argument is the selected signaling point. It can be any value from 0
to 7, as long as that signaling point exists.
pc
This argument is the point code from which the cluster portion will be
extracted.
RETURN VALUE
cluster
-1
On success, a positive integer in the int format which is the cluster

portion of the point code.
On failure.
SEE ALSO mtp_init_api(), mtp_pc2member(), mtp_pc2network(), mtp_subpc2pc()
Page 7 - 17
1-1600-1003-01
MTP API Library
7.3.14 mtp_pc2member()
DESCRIPTION
mtp_pc2member()
Extracts the member portion of a pointcode on a specified
signaling point. If the point code is in xxx-yyy-zzz format, then the member is the zzz
portion.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_pc2member(int sp, dword_t pc);
sp
This argument is the selected signaling point. It can be any value from
pc
This argument is the point code where the member portion will be
extracted out of.
RETURN VALUE
member
-1
On success, a positive integer in the int format which is the member

On failure.
SEE ALSO mtp_init_api(), mtp_pc2cluster(), mtp_pc2network(), mtp_subpc2pc()
Page 7 - 18
1-1600-1003-01
MTP API Library
7.3.15 mtp_pc2network()
DESCRIPTION
mtp_pc2network()
Extracts the network portion of a pointcode on a specified
signaling point. (If point code is in xxx-yyy-zzz format, network is the xxx portion.)
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_pc2network(int sp, dword_t pc);
sp
pc
This argument is the point code where the network portion will be
extracted out of.
RETURN VALUE
network
-1
On success, a positive integer in the int format which is the network

On failure.
SEE ALSO mtp_init_api(), mtp_pc2member(), mtp_pc2cluster(), mtp_subpc2pc()
Page 7 - 19
1-1600-1003-01
MTP API Library
7.3.16 mtp_protocol()
DESCRIPTION
mtp_protocol()
point.
Retrieves the protocol type of the MTP layer-3 of the signaling

MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_protocol(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the protocol type.

The return value can be one of the following:
OPT_ITU93 - ITU 1993 (white book)

OPT_ITU97 - ITU 1997
OPT_ANSI92 - ANSI 1992
OPT_ANSI96 - ANSI 1996
ERRORS
Page 7 - 20
1-1600-1003-01
MTP API Library
7.3.17 mtp_spc()
DESCRIPTION
mtp_spc()
form of an integer.
Retrieves the own signaling point code of the MTP layer-3, in the

MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_spc(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the own point code.

ERRORS
Page 7 - 21
1-1600-1003-01
MTP API Library
7.3.18 mtp_subpc2pc()
DESCRIPTION
mtp_subpc2pc()
Constructs a point code on a signaling point according to the
current MTPL3 protocol in use.
MT-LEVEL
MT-Safe
SYNOPSIS
dword_t mtp_subpc2pc(int sp, byte_t zid, byte_t aid, byte_t sid);
sp
zid
This argument is the zone ID of a point code. If the point code is in xxxyyy-zzz format, the zone ID is the xxx portion.
aid
This argument is the area ID of a point code. If the point code is in xxxyyy-zzz format, the area ID is the yyy portion.
sid
This argument is the signaling point ID of a point code. If the point code
is in xxx-yyy-zzz format, the signaling point ID is the zzz portion.
RETURN VALUE
point code
0xffffffff
On success, the point code in dword_t format.

On failure.
SEE ALSO mtp_init_api(), mtp_pc2member(), mtp_pc2network(), mtp_pc2cluster()
Page 7 - 22
1-1600-1003-01
MTP API Library
7.3.19 mtp_up_offset()
DESCRIPTION
mtp_up_offset()
This function is used to retrieve the offset value of the user part
message in an MSU. The offset value is the pointer in an MSU, starting just after the
routing label of MTP layer-3.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_up_offset(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the offset value.

ERRORS
Page 7 - 23
1-1600-1003-01
MTP API Library
7.3.20 mtp_variant()
DESCRIPTION
mtp_variant()
Retrieves the variant type of the MTP layer-3.

MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_variant(int sp);
sp
RETURN VALUE
int
-1
On success, a positive integer indicating the variant type.

The variant value can be one of the following:
OPT_GENERIC - No variant is set (generic option)

OPT_NZ - New Zealand (reserved for now)
OPT_ATT - AT&T (valid only for ANSI)
OPT_GTE - GTE (reserved for now)
OPT_BELL - BELL (valid only for ANSI)
OPT_ETSI97 - ETSI97 (valid only for ITU97)
ERRORS
Page 7 - 24
1-1600-1003-01
MTP API Library
7.3.21 mtp_xfer_ind()
DESCRIPTION
mtp_xfer_ind()
This function is used to parse an MSU (Message Signal Unit) and
extracts MTP (Message Transfer Part) specific data into a user buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_xfer_ind(ipcmsg_t * msg , mtpxfer_t * mtpxfer );
msg
mtpxfer
This argument points a user buffer where the MTP user data will be filled
to.
This function must only be called if the primitive of the incoming
message is set to MTP_TRANSFER. The primitive is carried into the
msgtyp field of the ipcmsg_t structure.
RETURN VALUE
0
-1
On success.
ERRORS
<EPMTCH>::Primitive type mismatch
SEE ALSO mtp_xfer_req(), mtp_init_api(), spm_rcv()
Page 7 - 25
1-1600-1003-01
MTP API Library
7.3.22 mtp_xfer_req()
DESCRIPTION
mtp_xfer_req()
This function is used to send an SS7 message through a service
endpoint, identified by fd, under the Distributed7 environment.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_xfer_req(int fd , mtpxfer_t * mtpxfer );
fd
provider.
mtpxfer
This argument points a user buffer which contains information about the
SS7 message to be sent out. Prior to calling the mtp_xfer_req() function,
all appropriate fields within the mtpxfer_t structure should be initialized
by the application.
RETURN VALUE
0
-1
On success.
ERRORS
SEE ALSO mtp_xfer_ind(), mtp_init_api(), spm_snd()
Page 7 - 26
1-1600-1003-01
MTP API Library
7.3.23 mtp_xfer2_req ()
DESCRIPTION
mtp_xfer2_req ()
This function is used to send an SS7 message with a given
originating point code through a service endpoint, identified by fd, under the Distributed7
environment. This function works the same way as mtp_xfer_req() with the only
difference that mtp_xfer_req () populates own point code as the originating point code
and mtp_xfer2_req () populates the point code given in mtpxfer structure as the
originating point code. The mtp_init_api() function must be called before this function is
used.
MT-LEVEL
MT-Safe
SYNOPSIS
int mtp_xfer2_req (int fd , mtpxfer2_t * mtpxfer );
fd
provider.
mtpxfer
This argument points a user buffer which contains information about the
SS7 message to be sent out. Prior to calling the mtp_xfer2_req ()
function, all appropriate fields within the mtpxfer2_t structure should be
initialized by the application.
RETURN VALUE
0
-1
On success.
ERRORS
SEE ALSO mtp_xfer_req(), mtp_xfer_ind(), mtp_init_api(), spm_snd()
Page 7 - 27
1-1600-1003-01
MTP API Library
Page 7 - 28
1-1600-1003-01
Chapter 8:
8.1
Gateway API Library
Gateway API Library
Chapter Overview
This chapter provides the gateway (GW) Application Programming Interface (API) library
calls for NewNet Communication Technologies, LLC Distributed7 software products.
8.2
Gateway API Library

The GW library is used to do something with the gateway. Every library call is described in
detail on the following pages, including information on input parameters, declarations, and
return values. These function calls require the following header files to be included in the
application:
#include <api.h>
#include <alarm.h>
The GW library must be linked with the application if any of its functions are used. See the
Distributed7 Application Development Manual for more information.
The GW library (libgw.a) should be accessed using the $EBSHOME/access/lib path, and
cc file.c-I $EBSHOME/access/include
-L $EBSHOME/access/lib -lgw
A sample source code file, gwtest.c, is provided to demonstrate the use of Distributed7 GW
literals and functions. It should be compiled with the MAKEFILE in the $EBSHOME/
access/sample/gw directory. After it is compiled, the executable will be located in the
$EBSHOME/access/demo directory.
Important: Distributed7 1.2. GW API is multi-thread (MT) Safe, and can be used with
Page 8 - 1
1-1600-1003-01
8.2.1
Gateway API Library
gw_isup_get_cic()
DESCRIPTION
gw_isup_get_cic
This function is used to parse an ISUP message and extract the
circuit identification code (CIC) information from within the message.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_isup_get_cic(msudata_t *msudata, word_t *cic);
msudata
Points to the user buffer which contains the received ISUP message.
cic
Points to the user buffer that the retrieved CIC information is copied to.
RETURN VALUES
0
-1
On success; CIC information is copied to the memory location pointed to

by cic.
ERRORS
<EINVAL>::Given sp value is invalid
8.2.2
gw_mtp_flow_ind()
DESCRIPTION
gw_mtp_flow_ind
This function is used to extract flow data from an incoming
message having an MTP flow primitive.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_mtp_flow_ind(ipcmsg_t *msg, gw_mtpflow_t *flowp);
msg
Points the user buffer which includes the incoming message received by
the spm_rcv() library function.
flowp
Points a user buffer where the MTP primitive data will be filled to. The
possible MTP flow primitives are as follows:
MTP_PAUSE - Received when a remote destination becomes
inaccessible.
Page 8 - 2
1-1600-1003-01
Gateway API Library
MTP_RESUME - Received when a remote destination becomes

accessible.
MTP_STATUS - Received when a remote destination becomes
congested or a user part on a remote destination is not available.
The adpc_rttype field of the structure gw_mtpflow_t indicates the routing
type of the destination affected. The valid routing types and the action
that the user must take are defined below:
MEMBER_TYPE - The remote destination is a member, apply the
change only on this destination.
CLUSTER_TYPE - The remote destination is a cluster, apply the
change on all the destinations in this cluster.
NETWORK_TYPE - The remote destination is a network, apply the
change on all the destinations in this network.
The type field of the structure gw_mtpflow_t indicates two different
conditions of a remote destination:
CONG_TYPE - The congestion status of the remote destination has
changed. In this case the status field indicates the new congestion
status.
UPU_TYPE - The user part on the remote destination is currently not
available. In this case the status field indicates the `cause' of the
remote user's unavailability.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO mtp_init_api(), mtp_flow_ind(), and spm_rcv()
8.2.3
gw_mtp_upu_req()
DESCRIPTION
gw_mtp_upu_req()
user part.
This function is used to send out a UPU message for a capability

MT-LEVEL
MT-Safe
Page 8 - 3
1-1600-1003-01
Gateway API Library
SYNOPSIS
int gw_mtp_upu_req(int fd, dword_t dest_pc, dword_t cap_pc,
int service_ind, int cause);
fd
Must be a valid file descriptor bound to the UPM sevice provider.
dest_pc
Gives the point code for the target SS7 endpoint.
cap_pc
Indicates the point-code for the capability node.
service_ind
Identifies the unavailable MTP user part, i.e, 3 for or SCCP, 5 for ISUP.
cause
Identifies the cause of unavailability.
RETURN VALUES
0
-1
On success.
On failure; errno is set to indicate the reason for the failure.
ERRORS
descriptor fd.
SEE ALSO mtp_init_api() and spm_snd()
8.2.4
gw_mtp_xfer_ind()
DESCRIPTION
gw_mtp_xfer_ind()
This function is used to parse an MSU (Message Signal Unit) and
extracts MTP (Message Transfer Part) specific data into a user buffer in the form of
gw_mtpxfer_t structure.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_mtp_xfer_ind(ipcmsg_t * msgp, gw_mtpxfer_t * xferp);
msgp
Points to the user buffer which contains the received message.
xferp
Points to the user buffer which the parsed data will be filled.
RETURN VALUES
0
-1
Page 8 - 4
On success.
1-1600-1003-01
Gateway API Library
ERRORS
<EPMTCH>::Primitive type mismatch.
<EINVAL>::Invalid sp number in message.
<EMSGSIZE>::Incoming MSU size exceeds the maximum MSU size.
SEE ALSO gw_mtp_xfer_req(), mtp_init_api(), mtp_xfer_ind()
8.2.5
gw_mtp_xfer_req()
DESCRIPTION
gw_mtp_xfer_req()
This function is used to send an SS7 message through a service
endpoint, identified by fd, under the Distributed7 environment.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_mtp_xfer_req(int fd, gw_mtpxfer_t * xferp);
fd
File descriptor bound to the UPM service provider.
xferp
Points to the user-space buffer of type gw_mtpxfer_t which contains
information about the SS7 message to be sent. Prior to calling the
gw_mtp_xfer_req() function, all appropriate fields within the
gw_mtpxfer_t structure should be initialized by the application.
RETURN VALUES
0
-1
On success.
ERRORS
descriptor fd.
<EMSGSIZE>::Given MSU size exceeds the maximum MSU size.
Page 8 - 5
1-1600-1003-01
Gateway API Library
SEE ALSO mtp_init_api(), gw_mtp_xfer_ind(), spm_snd()
8.2.6
gw_mtp_rct_ind()
DESCRIPTION
gw_mtp_rct_ind
This function is used to extract RCT data from an incoming
message having an MTP congestion test primitive.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_mtp_rct_ind (ipcmsg_t *msg, gw_mtprct_t *rctp);
msg
rctp
Points to the user buffer which contains the received message.

Points to the user buffer where the MTP primitive data will be filled.
Thepossible MTP congestion test primitive is as follows:
MTP_CONG_TEST - Received when a remote destination sends a
RCT message.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO gw_mtp_rct_req(), mtp_init_api(), and spm_rcv()
8.2.7
gw_mtp_rct_req()
DESCRIPTION
gw_mtp_rct_req()
destination.
This function is used to send out a RCT message for a congested

MT-LEVEL
MT-Safe
Page 8 - 6
1-1600-1003-01
Gateway API Library
SYNOPSIS
int gw_mtp_rct_req (int fd, dword_t dpc, dword_t opc, int cong);
fd
dpc
opc
cong

Indicates the point-code for the target SS7 endpoint.
Indicates the point-code originating the message.
Indicates the congestion value.
RETURN VALUES
0
-1
On success.
ERRORS
descriptor fd.
SEE ALSO gw_mtp_rct_ind(), mtp_init_api() and spm_snd()
8.2.8
gw_mtp_tfc_req()
DESCRIPTION
gw_mtp_tfc_req()
capability node.
This function is used to send out a TFC message regarding a

MT-LEVEL
MT-Safe.
SYNOPSIS
int gw_mtp_tfc_req (int fd, dword_t dpc, dword_t opc, dword_t cpc, int cong);
fd
dpc
opc
cpc
cong

Indicates the point-code for the target SS7 endpoint.
Indicates the point-code originating the message.
Indicates the capability point-code that is congested.
Indicates the congestion value.
RETURN VALUES
0
-1
On success.
Page 8 - 7
1-1600-1003-01
Gateway API Library
ERRORS
descriptor fd.
SEE ALSO gw_mtp_flow_ind(), mtp_init_api() and spm_snd()
8.2.9
gw_mtp_tfa_req()
DESCRIPTION
gw_mtp_tfa_req()
capability node.
This function is used to send out a TFA message regarding a

MT-LEVEL
MT-Safe.
SYNOPSIS
int gw_mtp_tfa_req (int fd, dword_t cpc);
fd
cpc
Indicates the affected capability point-code.
RETURN VALUES
0
-1
On success.
ERRORS
descriptor fd.
SEE ALSO gw_mtp_tfr_req(), gw_mtp_tfp_req(), mtp_init_api() and spm_snd()
8.2.10 gw_mtp_tfr_req()
DESCRIPTION
gw_mtp_tfr_req()
capability node.
This function is used to send out a TFR message regarding a
Page 8 - 8
1-1600-1003-01
Gateway API Library
MT-LEVEL
MT-Safe.
SYNOPSIS
int gw_mtp_tfr_req (int fd, dword_t cpc);
fd
cpc
RETURN VALUES
0
-1
On success.
ERRORS
descriptor fd.
SEE ALSO gw_mtp_tfa_req(), gw_mtp_tfp_req(), mtp_init_api() and spm_snd()
8.2.11 gw_mtp_tfp_req()
DESCRIPTION
gw_mtp_tfp_req()
capability node.
This function is used to send out a TFP message regarding a

MT-LEVEL
MT-Safe.
SYNOPSIS
int gw_mtp_tfp_req (int fd, dword_t cpc);
fd
cpc
RETURN VALUES
0
-1
On success.
ERRORS
Page 8 - 9
1-1600-1003-01
Gateway API Library

descriptor fd.
SEE ALSO gw_mtp_tfa_req(), gw_mtp_tfr_req(), mtp_init_api() and spm_snd()
8.2.12 gw_mtp_dest_stat()
DESCRIPTION
gw_mtp_dest_stat()
destination.
This function is used to retrieve the state (tsrc) of the requested

MT-LEVEL
MT-Safe.
SYNOPSIS
int gw_mtp_dest_stat (int fd, dword_t pc);
fd
pc
Indicates the point-code in cocern.
RETURN VALUES
MTP_DPC_INACCESSIBLE
MTP_DPC_ACCESSIBLE
On success.
MTP_DPC_RESTRICTED
-1
ERRORS
descriptor fd.
SEE ALSO mtp_init_api() and spm_snd()
8.2.13 gw_register()
DESCRIPTION
gw_register()
This function is used to register a Gateway or Monitor user
process to the Distributed7 environment. Prior to performing any Distributed7 operation,
gw_register() must be called.
Page 8 - 10
1-1600-1003-01
Gateway API Library
A user process, using gw_register(), can register as a gateway between different networks
(Gateway mode), or act as an active monitor (Monitor mode), hence intercepting all the
messages received by Distributed7 (from SS7 or SIGTRAN networks). The same set of
message send/receive APIs is used both in Gateway and Monitor modes of registration.
Please see the action argument for further details about Gateway/Monitor registraton
modes.
The gw_register function performs initialization activities in Distributed7 environment on
behalf of the calling process, establishes a service endpoint (spm_open), binds a daemon
object called Gateway_<sp> (for Gateway mode) or Monitor_<sp> (for Monitor mode) to
this endpoint (spm_bind), checks if the corresponding upmd is running (spm_getusrstat),
handshakes with upmd in order to control the current system resources and configuration,
(spm_snd, spm_rcv), and initializes the mtp library (mtp_init_api).
For both modes of registration (Gateway and Monitor), messages received at the MTP
layer are sent to the local instance, if there exists such an instance. In case a local instance
cannot be found, the messages are distributed among the remote instances in a roundrobin fashion.
In Gateway mode, all messages (MTP management and user part) destined for capability
point codes are sent to the endpoints registered through gw_register. In this mode, the
Gateway process simulates an adjacent point code which provides routes to the capability
point codes.
In Monitor mode, all user part messages received from the SS7/SIGTRAN networks are
routed to the processes registered through gw_register. Messages which are not received
from an external network, but generated through local user parts, are not received by the
Monitor processes. It is up to the receiving Monitor process to decide whether a message
needs to be looped back to the network, discarded, or modified. These actions can be
performed through the message send/receive APIs, which are included with the gw
library.
Prior to calling the gw_register() function, make sure that the signaling point type is set to
STP. Otherwise the function will fail.
For a particular sp-host pair, only one Gateway and one Monitor registration is allowed.
Trying to register a second time with the same mode will result in a failure.
The pointcode "0-0-2" is reserved for the internal use of Distributed7. Adding capability
nodes with this point code is prohibited.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_register(int sp, void * (func) () ,int action);
sp
This argument specifies the signaling point that is of interest, and may
Page 8 - 11
1-1600-1003-01
func
action
Gateway API Library
Upon termination of the UPM driver daemon (upmd), processes

registered through gw_register() will also terminate. Before termination,
the function specified by the func argument will be called and the file
descriptor associated with registration will be passed as an argument to
the function called. If func argument is given as NULL, then no action
will be taken. Please note that the function provided with the func
argument may not perform any Distributed7 related operation, since the
UPM service provider will not be available at the termination time.
The action argument specifies the registration mode and assumes a value
from the following list:
Table 8-1: int gw_register function
GW_DISABLED_CAP
Gateway mode, make capability point codes inaccessible.
GW_ENABLED_CAP
Gateway mode, make capability point codes accessible.
GW_MONITOR
Monitor mode.
RETURN VALUES
gw_register()
-1
On success, returns a valid file descriptor.

ERRORS
<ENOENT>::Invalid function argument is specified.
UPM driver is not installed on the system.
<ENLINKED>::Distributed7 system software has not been started yet.
<EXCLUSIVE>::Exclusive registration of Gateway process.
<ESRCH>::Daemon process of UPM driver is not available.
<ETIME>::Daemon process of UPM driver does not respond.
<EMTPCONF>::MTP configuration generic error.
<ENOTSTP>::SP is not configured as STP.
SEE ALSO spm_open(3E), spm_bind(3E), spm_getusrstat(3E), spm_snd(3E),

spm_rcv(3E), mtp_init_api(3M)
8.2.14 gw_sccp_modify_CdPA()
DESCRIPTION
gw_sccp_modify_CdPA() This function is used for modifying the called part address off
an SCCP message.
MT-LEVEL
MT-Safe
Page 8 - 12
1-1600-1003-01
Gateway API Library
SYNOPSIS
int gw_sccp_modify_CdPA(int sp, msudata_t * msudata, cpa_t * CdPA);
sp
This argument specifies the signaling point number which the application
is registered with.
msudata
Points to the user buffer which contains the SCCP message (starting from
the "SCCP message type" octet).
CdPA
Points to the user buffer which contains the called party address that will
be modified to the SCCP message.
RETURN VALUES
int
-1
On success, returns a a positive value specifying the new SCCP message

size.
ERRORS
<EINVAL>::Given sp value is invalid.
<EINVADDIND>::Invalid address indication.
<EPMTCH>::Prototype mismatch.
SEE ALSO gw_sccp_modify_CgPA()
8.2.15 gw_sccp_modify_CgPA()
DESCRIPTION
gw_sccp_modify_CgPA() This function is used for modifying the calling party address off
an SCCP message.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_sccp_modify_CgPA(int sp, msudata_t * msudata, cpa_t * CgPA);
sp
is registered with.
msudata
CgPA
Points to the user buffer which contains the calling party address that will
be modified to the SCCP message.
Page 8 - 13
1-1600-1003-01
Gateway API Library
RETURN VALUES
int
-1
On success, returns a a positive value specifying the new SCCP message

size.
ERRORS
<EINVADDIND>::Invalid address indication.
SEE ALSO gw_sccp_modify_CdPA()
8.2.16 gw_sccp_parse_UDT()
DESCRIPTION
gw_sccp_parse_UDT() This function is used to parse a UnidataInd (Unit Data Indication)
message from an SCCP message.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_sccp_parse_UDT(int sp, msudata_t * msudata, N_UnitdataInd_t * Unidata);
sp
is registered with.
msudata
unidata
Points to the user buffer which the Unit data message will be filled with.
RETURN VALUES
0
-1
On success.
ERRORS
Page 8 - 14
1-1600-1003-01
Gateway API Library
SEE ALSO gw_sccp_parse_UDTS()
8.2.17 gw_sccp_parse_UDTS()
DESCRIPTION
gw_sccp_parse_UDTS() This function is used to parse a Notice Indication message from
an SCCP message.
MT-LEVEL
MT-Safe
SYNOPSIS
int gw_sccp_parse_UDTS(int sp, msudata_t * msudata, N_NoticeInd_t * notice);
sp
is registered with.
msudata
notice
Points to the user buffer which the Notice Indication message will be
filled with.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO gw_sccp_parse_UDT()
Page 8 - 15
1-1600-1003-01
Page 8 - 16
Gateway API Library
1-1600-1003-01
Chapter 9:
9.1
SCCP API Library
SCCP API Library
Chapter Overview
This chapter provides the alphabetical listings of the Signaling Connection Control Point
(SCCP) Application Programming Interface (API) library calls for NewNet Communication
9.2
SCCP API Library

The SCCP API library is provided for decoding and encoding of SCCP primitives. SCCP
primitives are designed to operate with ITU (CCITT) and ANSI MTP, depending on which
library is linked with the application.
To use the SCCP function calls, the following header files must be included at the beginning
of the application in the given order:
#include <api.h>
#include <mtp_apiproto.h>
#include <sccp_scpa.h>
#include <sccp_sccl.h>
#include <sccp_prim.h>
#include <sccp_scoc.h>
#include <sccp_macro.h>
#include <sccp_api_proto.h>
Note: All applications which need to use the SCCP API must make a call to mtp_init_api
prior to calling any function from the SCCPAPI.
The SCCP library (libsccp.a) should be accessed using the $EBSHOME/access/lib path,
($EBSHOME is an environment variable holding the pathname of where the SS7 software
is installed.)
cc
-L $EBSHOME/access/lib -l sccp -l mtp -l spm -lnsl
A sample source code file, sccptest.c, is provided to demonstrate the use of Distributed7
SCCP literals and functions. It should be compiled with the MAKEFILE in the
Page 9 - 1
1-1600-1003-01
SCCP API Library
$EBSHOME/access/sample/sccp directory. After it is compiled, the executable will be

so that the user can invoke the UNIX standard man(1) utility to review the information
Important: Distributed7 1.2. SCCP API is multi-thread (MT) Safe, and can be used with
9.2.1
sccp_addr2pc_p()
DESCRIPTION
sccp_addr2pc_p()
Locates and returns a pointer to the starting address of signalling
point code information embedded within a CPA3_t type address structure.
Signalling point code information is stored at different memory locations for ANSI and
ITU protocols. The sccp_addr2pc_p() function supports writing portable programs that
can locate the starting address of signalling point code information within a CPA3_t type
address structure, regardless of the protocol being used.
This function is typically used in conjunction with the sccp_get_pc() and sccp_put_pc()
functions. For details, refer to the man pages of these functions.
MT-LEVEL
MT-Safe
SYNOPSIS
byte_t *sccp_addr2pc_p(byte_t sp, CPA3_t *cpa)
sp
Identifies the signalling point of interest and may assume a value in the
[0, 7] range.
cpa
Points to a user-space buffer of type CPA3_t in which the signalling
point code information stored.
The CPA3_t type is defined in <sccp_scpa.h> as follows:
typedef struct {
union {
CPA3_ansi_t
CPA3_ccitt_t
} un;
} CPA3_t;
CPA3_ansi;
CPA3_ccitt;
where the aforementioned data types are defined as follows:

typedef struct {
byte_t
Page 9 - 2
ssn;
1-1600-1003-01
SCCP API Library
byte_t spc[L_ANSI_PCSIZE];
} CPA3_ansi_t;
typedef struct {
byte_t spc[L_CCITT_PCSIZE];
byte_t ssn;
} CPA3_ccitt_t;
RETURN VALUE
Upon successful completion, the starting address of the signalling point code embedded
in a CPA3_t type address structure is retrieved and returned to the user.
ERRORS
<EINVAL>::Invalid sp number specified.
SEE ALSO sccp_get_pc() and sccp_put_pc()
9.2.2
sccp_addr2ssn_p()
DESCRIPTION
sccp_addr2ssn_p()
Locates and returns a pointer to the starting address of SCCP
subsystem information embedded within a CPA3_t type address structure.
Subsystem number information is stored at different memory locations for ANSI and ITU
protocols. The sccp_addr2ssn_p() function supports writing portable programs that can
locate the starting address of subsystem number information within a CPA3_t type
address structure, regardless of the protocol being used.
This function is typically used in conjunction with the sccp_get_pc() and sccp_put_pc()
functions. For details, refer to the man pages of these functions.
MT-LEVEL
MT-Safe
SYNOPSIS
byte_t *sccp_addr2ssn_p(byte_t sp, CPA3_t *cpa)
sp
[0, 7] range.
cpa
Points to a user-space buffer of type CPA3_t in which the SCCP
subsystem number stored.
The CPA3_t type is defined in <sccp_scpa.h> as follows:
typedef struct {
union {
CPA3_ansi_t
CPA3_ccitt_t
CPA3_ansi;
CPA3_ccitt;
Page 9 - 3
1-1600-1003-01
SCCP API Library
} un;
} CPA3_t;

typedef struct {
byte_t ssn;
} CPA3_ansi_t;
typedef struct {
byte_t ssn;
} CPA3_ccitt_t;
RETURN VALUE
Upon successful completion, the starting address of the subsystem number embedded in a
CPA3_t type address structure is retrieved and returned to the user.
ERRORS
<EINVAL>::Invalid sp number specified
SEE ALSO sccp_get_pc() and sccp_put_pc()
9.2.3
sccp_ConnectCnf()
DESCRIPTION
sccp_ConnectCnf()
Unpacks a connection confirmation from the remote peer SCCP.
This call is used when the msgtyp (msgp->msghdr.msgtyp) field of the IPC message is
N_CONNECT_confirmation.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_ConnectCnf(int fd, ipcmsg_t *msgp, N_ConnectCnf_t *N_ConnectCnf)
fd
File descriptor received from a previous sccp_reg() call.
msgp
Pointer to the IPC message that was received.
N_ConnectCnf Pointer to the N_ConnectCnf_t structure which will hold the parameters
that were extracted from the message. The responding_address,
connection_id, receipt_cnf_sel, expedata_sel, protocol_class, and credit
parameters as well as the associated MSUs user data portion will be
placed into the fields of this structure. The flags field will be set to
indicate whether or not the optional parameter, responding_address, is
included. The datasize field of N_ConnectCnf_t indicates the size of
Page 9 - 4
1-1600-1003-01
SCCP API Library
user data received. A non-zero datasize indicates that the optional data
part is present in the message.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 5
1-1600-1003-01
9.2.4
SCCP API Library
sccp_ConnectInd()
DESCRIPTION
sccp_ConnectInd()
Unpacks a connection request. This call is used when the msgtyp
(msgp->msghdr.msgtyp) field of the IPC message is N_CONNECT_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_ConnectInd (int fd, ipcmsg_t *msgp, N_ConnectInd_t *N_ConnectInd)
fd
msgp
N_ConnectInd Pointer to the N_ConnectInd_t structure which will hold the data from
the connection request message. The data is placed in the called_address,
calling_address, receipt_cnf_sel, expedata_sel, protocol_class, credit,
connection_id, and usr_data fields. The datasize field of
N_ConnectInd_t indicates the size of user data received. Non-zero
datasize indicates that the optional data part is present in the message.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 6
1-1600-1003-01
9.2.5
SCCP API Library
sccp_ConnectReq()
NAME
sccp_ConnectReq()
Initiates the set-up of a connection to a remote SCCP peer entity.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_ConnectReq(int fd, N_ConnectReq_t *N_ConnectReq)
fd
msgp
N_ConnectReq Pointer to the N_ConnectReq_t structure that must be populated with
the information needed to set up the connection. For SCCP to transmit
optional parameters in a connection request message, the corresponding
bits in the flags field of the N_ConnectReq_t structure must be set using
the mask literals defined in sccp_prim.h. If the datasize field is zero, it
will be assumed that the optional data part is not present.
RETURN VALUE
0
-1
On success.
ERRORS
<EAGAIN>::Stream write queue is full due to internal flow control
conditions. Buffer could not be allocated for the message that
was to be created.
<ETIME>::Timeout has occurred waiting for an acknowledgment.
<EMSGNAK>::Message not acknowledged.
<EINTR>::The system call was interrupted by the delivery of a signal.
<EMSGSIZE>::Message is too large.
<ENXIO>::A hang-up condition was generated downstream.
SEE ALSO sccp_reg()
Page 9 - 7
1-1600-1003-01
9.2.6
SCCP API Library
sccp_ConnectRsp()
DESCRIPTION
sccp_ConnectRsp()
Responds to a connection request by packing the specified
information into an MSU and transmitting it to the remote SCCP peer entity.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_ConnectRsp(int fd, N_ConnectRsp_t *N_ConnectRsp)
fd
N_ConnectRsp Pointer to the N_ConnectRsp_t structure that has been properly
populated for a connection request. For SCCP to transmit optional
parameters in a connection confirmation message, the corresponding bits
in the flags field of the N_ConnectRsp_t structure must be set using the
mask literals defined in sccp_prim.h. If the datasize field is zero, it will
be assumed that the optional data part is not present.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
SEE ALSO sccp_reg()
Page 9 - 8
1-1600-1003-01
9.2.7
SCCP API Library
sccp_CoordCnf()
DESCRIPTION
sccp_CoordCnf()
Unpacks a message that confirms a request for permission to go
out of service. The subsystem can now start procedures to go out of service. This call is
used when the msgtyp (msgp->msghdr.msgtyp) field of the IPC message is
N_COORD_confirmation.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_CoordCnf(int fd, ipcmsg_t *msgp, N_CoordCnf_t *N_CoordCnf)
fd
msgp
N_CoordCnf Pointer to the N_CoordCnf_t structure which will hold the confirmation
information. The affected_subsystem and the subsystem_mult_ind fields
hold the subsystem number and instance number.
RETURN VALUE
None
SEE ALSO sccp_reg()
9.2.8
sccp_CoordInd()
DESCRIPTION
sccp_CoordInd()
Unpacks a request to go out of service from a replicate
subsystem. This call is used when the msgtyp (msgp->msghdr.msgtyp) field of the IPC
message is N_COORD_indication. The calling application would respond using
sccp_CoordRsp()
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_CoordInd(int fd, ipcmsg_t *msgp, N_CoordInd_t *N_CoordInd)
fd
msgp
N_CoordInd
Pointer to the N_CoordInd_t structure which will hold the information
to identify the requester. The affected_subsystem and the
Page 9 - 9
1-1600-1003-01
SCCP API Library
subsystem_mult_ind fields hold the subsystem number and instance

number.
RETURN VALUE
None
SEE ALSO sccp_reg()
9.2.9
sccp_CoordReq()
DESCRIPTION
sccp_CoordReq()
Packs an MSU that requests permission to go out of service from
a replicate SCCP subsystem.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_CoordReq(int fd, N_CoordReq_t *N_CoordReq)
fd
N_CoordReq Pointer to the N_CoordReq_t structure which must have the
affected_subsystem field populated.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
SEE ALSO sccp_reg()
Page 9 - 10
1-1600-1003-01
SCCP API Library
9.2.10 sccp_CoordRsp()
DESCRIPTION
sccp_CoordRsp()
Packs MSU that grants permission to a replicate subsystem to go
out of service. The subsystem should have sufficient resources to allow the requesting
replicate to go out of service.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_CoordRsp(int fd, N_CoordRsp_t *N_CoordRsp)
fd
N_CoordRsp Pointer to the N_CoordRsp_t structure which must have the
affected_subsystem field populated.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
SEE ALSO sccp_reg()
Page 9 - 11
1-1600-1003-01
SCCP API Library
9.2.11 sccp_DataInd()
DESCRIPTION
sccp_DataInd()
Unpacks the user data and connection ID that was delivered to the
system by an MSU. This call is used when the msgtyp (msgp->msghdr.msgtyp) field of
the IPC message is N_DATA_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_DataInd(int fd, ipcmsg_t *msgp, N_DataInd_t *N_DataInd)
fd
msgp
N_DataInd
Pointer to the N_DataInd_t structure that will hold the information from
the message. The connection ID is placed in the connection_id field. The
datasize field is set to indicate the size of the user data received and the
size of the dynamic memory that is allocated by the library. The address
of this memory is in the msp_data field. The application must free this
memory after the message is processed.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 12
1-1600-1003-01
SCCP API Library
9.2.12 sccp_DataReq()
DESCRIPTION
sccp_DataReq()
data request.
Packs an MSU with the provided information to form an SCCP
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_DataReq(int fd, N_DataReq_t *N_DataReq)
fd
N_DataReq
Pointer to the N_DataReq_t structure which must be have the datasize,
connection_id, and confirm_req fields populated. The flags field will be
set to indicate whether or not the optional parameter, importance, is
included. The datasize field must be set to indicate the size of the user
data.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
SEE ALSO sccp_reg()
Page 9 - 13
1-1600-1003-01
SCCP API Library
9.2.13 sccp_DisconnectInd()
DESCRIPTION
sccp_DisconnectInd() Unpacks the information that was delivered to the system by an
MSU during the release phase. This call is used when the msgtyp
(msgp->msghdr.msgtyp) field of the IPC message is
N_DISCONN_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_DisconnectInd(int fd, ipcmsg_t *msgp, N_DisconnectInd_t
*N_DisconnectInd)
fd
msgp
N_DisconnectInd
Pointer to the N_DisconnectInd_t structure that will hold the
information from the message. The data is placed in the
responding_address, connection_id, originator, reason, and usr_data
fields. The datasize field indicates the size of the user data received. The
flags field will be set to indicate whether or not the optional parameter
responding_address is included. A non-zero datasize indicates that
optional user data exists in the received MSU.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 14
1-1600-1003-01
SCCP API Library
9.2.14 sccp_DisconnectReq()
DESCRIPTION
sccp_DisconnectReq() Packs an MSU with a request for a connection release.
MT-LEVEL
MT-Safe
SYNOPSIS
viod sccp_DisconnectReq(int fd, N_DisconnectReq_t *N_DisconnectReq)
fd
N_DisconnectReq
Pointer to the N_DisconnectReq_t structure with the usr_data,
responding_address, connection_id, and reason fields populated. The
flags field must be set with the appropriate literal defined in sccp_prim.h
to cause SCCP to send the optional fields, responding_address and
importance, in the message. A non-zero value in the datasize field
indicates that the optional data part is included in the message.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
SEE ALSO sccp_reg()
9.2.15 sccp_get_pc()
DESCRIPTION
sccp_get_pn()
Retrieves the signalling point code information from within a
cpa_t type address structure and returns it to the user in the form of an unsigned integer.
MT-LEVEL
MT-Safe
Page 9 - 15
1-1600-1003-01
SCCP API Library
SYNOPSIS
dword_t sccp_get_pc(byte_t sp, byte_t *label)
sp
[0, 7] range.
label
Identifies the address location within a cpa_t type data structure at which
the signalling point code information resides.
The cpa_t type is defined in <sccp_scpa.h> as follows:
typedef struct {
byte_t
address_t
GT_t
} cpa_t;
address_indicator;
address;
global_title;
where the address_indicator field contains information about the exact

nature of information embedded within the address portion, and
global_title field contains global-title translation information, if any, for
use by the SCCP layer.
The address_indicator field gets constructed as a bit mask using the
following literals defined in the <sccp_scpa.h> file:
#define
#define
#define
#define
L_AI_InternationalNetwork 0x00 /* ITU */

L_AI_NationalNetwork 0x80 /* ANSI */
L_AI_RouteOnGT 0x00 /* route on GT */
L_AI_RouteOnDPCssn 0x40 /* route on SPC+SSN */
L_ADDIND_PCI_MASK_ANSI 0x02 /* SPC present */

L_ADDIND_PCI_MASK_CCITT 0x01 /* SPC present */
L_ADDIND_SSN_MASK_ANSI 0x01 /* SSN present */
L_ADDIND_SSN_MASK_CCITT 0x02 /* SSN present */
When analyzing the contents of the address_indicator field within a

cpa_t type structure at hand, application programmers may find it
convenient to use the following macros defined in the <sccp_macro.h>
file:
M_sccp_intl_ntwk(address_indicator) /* ITU? */
M_sccp_route_on_gt(address_indicator) /* route on GT? */
M_sccp_route_on_dpc_ssn(address_indicator)
/* route on SPC+SSN? */
M_sccp_pc_present(sp, address_indicator)
/* SPC present? */
M_sccp_ss_present(sp, address_indicator) /* SSN present? */
The use of these macros allow application programmers to write portable

programs that run across ANSI or ITU versions of the MTP3/SCCP
protocol in use.
Page 9 - 16
1-1600-1003-01
SCCP API Library
The address_t type is defined as a union container in <sccp_scpa.h> as

follows:
typedef struct {
union {
CPA1_t
CPA2_t
CPA3_t
CPA4_t
} type;
} address_t;
cpa1;
cpa2;
cpa3;
cpa4;
where CPA1_t, CPA2_t, CPA3_t, and CPA4_t types store the actual
address information that may contain different pieces of data, e.g.,
signalling point code, subsystem number, and can be in different formats,
depending on the MTP3/SCCP protocol in use. Out of these data types,
CPA1_t and CPA3_t are the only ones that contain signalling point code
information. This is to accommodate a variety of different types of
addressing methods, e.g., based on signalling point code only, on
signalling point code plus subsystem number, on global title, etc., that
may be employed by SCCP users when running under ANSI or ITU
versions of the MTP3/SCCP protocols.
When CPA1_t type of addressing is in use, label argument can be set
directly to point to the signalling point code field contained in the address
structure, as this is the only field within that data type.
typedef struct {
byte_t spc[L_MAX_PCSIZE];
} CPA1_t;
When CPA3_t type of addressing is in use, however, the CPA3_t type is

a union container for the CPA3_ansi_t and CPA3_ccitt_t types, as
follows.
typedef struct {
union {
CPA3_ansi_t
CPA3_ccitt_t
CPA3_ansi;
CPA3_ccitt;
} un;
} CPA3_t;
where the data types are defined as follows:

typedef struct {
byte_t ssn;
} CPA3_ansi_t
typedef struct {
byte_t ssn;
} CPA3_ccitt_t;
Page 9 - 17
1-1600-1003-01
SCCP API Library
If and when CPA3_t type of addressing is in use, label argument is

expected to be set to point to the spc field within the appropriate CPA3_t
data structure. To write portable application programs that work under
ANSI as well as ITU protocols, the sccp_addr2pc_p() function must be
used to locate the starting address location for the signalling point code
information first. Only after the starting address is located can the label
argument be initialized to point to that address to retrieve the actual
signalling point code information using the sccp_get_pc() function call.
RETURN VALUE
Upon successful completion, signalling point code embedded in a cpa_t type address
structure is retrieved and returned to the user in the form of an unsigned integer.
ERRORS
SEE ALSO sccp_put_pc() and sccp_addr2pc_p()
9.2.16 sccp_is_ansi()
DESCRIPTION
sccp_is_ansi()
Determines if the MTP3 and MTP3 user parts of the SS7 stack
associated a user-specified signalling point are currently configured to run an ANSI
variant of the SS7 protocol.
MT-LEVEL
MT-Safe
SYNOPSIS
int sccp_is_ansi(byte_t sp);
sp
Identifies the signalling point of interest, and may assume a value in the
[0, 7] range.
RETURN VALUE
1
0
If the MTP3 protocol is set to an ANSI variant, e.g., OPT_ANSI92,

OPT_ANSI96.
Otherwise.
ERRORS
Page 9 - 18
1-1600-1003-01
SCCP API Library
SEE ALSO sccp_is_ccitt()
9.2.17 sccp_is_ccitt()
DESCRIPTION
sccp_is_ccitt()
Determines if the MTP3 and MTP3 user parts of the SS7 stack
associated a user-specified signalling point are currently configured to run an ITU variant
of the SS7 protocol.
SYNOPSIS
int sccp_is_ccitt(byte_t sp);
sp
[0, 7] range.
RETURN VALUE
1
0
If the MTP3 protocol is set to an ITU variant, e.g., OPT_ITU93 or

OPT_ITU97.
Otherwise.
ERRORS
SEE ALSO sccp_is_ansi()
9.2.18 sccp_NoticeInd()
DESCRIPTION
sccp_NoticeInd()
Unpacks a notice indication message which notifies a process that
an MSU was returned because it could not get to its destination address. This call is used
when the msgtyp (msgp->msghdr.msgtyp) field of the IPC message is
N_NOTICE_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_NoticeInd(int fd, ipcmsg_t *msgp, N_NoticeInd_t *N_NoticeInd)
fd
msgp
N_NoticeInd Pointer to the N_NoticeInd_t structure which will hold the
called_address, calling_address, reason_for_return, and usr_data. The
datasize field indicates the size of user data retrieved.
Page 9 - 19
1-1600-1003-01
SCCP API Library
RETURN VALUE
None
SEE ALSO sccp_reg()
9.2.19 sccp_PCstateInd()
DESCRIPTION
sccp_PCstateInd()
Unpacks the signaling point status information from a
message. This call is used when the msgtyp field (msgp->msghdr.msgtyp) of the IPC
message contains N_PCSTATE_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_PCstateInd(int fd, ipcmsg_t *msgp, N_PCstateInd_t *N_PCstateInd)
fd
msgp
N_PCstateInd Pointer to the N_PCstateInd_t structure which will hold the affectedPC,
signaling_point_status and remote_sccp_status and ril.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 20
1-1600-1003-01
SCCP API Library
9.2.20 sccp_put_pc()
DESCRIPTION
sccp_put_pc()
Encodes and inserts a user-specified signalling point code into a
cpa_t type address structure.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_put_pc(byte_t sp, dword_t spc, byte_t *label);
sp
[0, 7] range.
spc
Identifies the signalling point code to encode and insert into the address
structure, and it is assumed to be in the form of an unsigned integer.
label
Identifies the starting address location within a cpa_t type data structure
at which the signalling point code information resides.
The cpa_t type is defined in <sccp_scpa.h> as follows:
typedef struct {
byte_t
address_t
GT_t
} cpa_t;
address_indicator;
address;
global_title;
where the address_indicator field contains information about the exact

nature of information contained in the address portion, and the
global_title field contains global-title translation information, if any, for
use by the SCCP layer.
The address_indicator field gets constructed as a bit mask using the
following literals defined in the <sccp_scpa.h> file:
#define
#define
#define
#define
L_AI_InternationalNetwork 0x00
/* ITU */
L_AI_NationalNetwork 0x80
/* ANSI */
L_AI_RouteOnGT 0x00
/* route on GT */
L_AI_RouteOnDPCssn 0x40
/* route on SPC+SSN */
#define
#define
#define
#define
L_ADDIND_PCI_MASK_ANSI 0x02
L_ADDIND_PCI_MASK_CCITT 0x01
L_ADDIND_SSN_MASK_ANSI 0x01
L_ADDIND_SSN_MASK_CCITT 0x02
/* SPC present */
/* SPC present */
/* SSN present */
/* SSN present */
With respect to the bottom four flags listed above, when writing portable
application programs to run across ANSI and ITU versions of the MTP3/
SCCP protocol, the M_sccp_ss_present_bit and M_sccp_pc_present_bit
macros defined in the <sccp_macro.h> file must be used to set the
Page 9 - 21
1-1600-1003-01
SCCP API Library
corresponding bits in address_indicator and avoid hard coding the SPC

and/or SSN present literals in their programs.
The address_t type is defined as a union container in <sccp_scpa.h> as
follows:
typedef struct {
union {
CPA1_t
CPA2_t
CPA3_t
CPA4_t
} type;
} address_t;
cpa1;
cpa2;
cpa3;
cpa4;
where CPA1_t, CPA2_t, CPA3_t, and CPA4_t types store the actual
address information that may contain different pieces of data, e.g.,
signalling point code, subsystem number, and can be in different formats,
depending on the MTP3/SCCP protocol in use. Out of these data types,
CPA1_t and CPA3_t are the only ones that contain signalling point code
information. This is to accommodate a variety of different types of
addressing methods, e.g., based on signalling point code only, on
signalling point code plus subsystem number, on global title, etc., that
may be employed by SCCP users when running under ANSI or ITU
versions of the MTP3/SCCP protocols.
When CPA1_t type of addressing is in use, label argument can be set
directly to point to the spc field contained in the address structure, as this
is the only field within that data type.
typedef struct {
byte_t spc[L_MAX_PCSIZE];
} CPA1_t;
When CPA3_t type of addressing is in use, however, the CPA3_t type is

a union container for the CPA3_ansi_t and CPA3_ccitt_t types, as
follows.
typedef struct {
union {
CPA3_ansi_t
CPA3_ccitt_t
} un;
} CPA3_t;
CPA3_ansi;
CPA3_ccitt;

typedef struct {
byte_t ssn;
} CPA3_ansi_t;
typedef struct {
Page 9 - 22
1-1600-1003-01
SCCP API Library
byte_t ssn;
} CPA3_ccitt_t;
If and when CPA3_t type of addressing is in use, label argument is

expected to be set to point to the spc field within the appropriate CPA3_t
data structure. When CPA3_t type of addressing is in use, the
sccp_addr2pc_p() function must be used to locate the starting address
location for the signalling point code information first to write portable
application programs that work under ANSI as well as ITU protocols.
Only after the starting address is located can the label argument be set to
point to that address to insert the actual signalling point code information
using the sccp_put_pc function call. Once sccp_put_pc() function is
used to encode and insert signalling point code into a cpa_t type address
structure, the address_indicator field within the cpa_t type should be
marked to that effect, i.e., by setting the appropriate address indicator
flag. This can be accomplished using the M_sccp_pc_present_bit macro
defined in the <sccp_macro.h> header file.
RETURN VALUE
None
SEE ALSO sccp_get_pc() and sccp_addr2pc_p()
9.2.21 sccp_reg()
DESCRIPTION
sccp_reg()
This function is used to register a process with the SCCP protocol layer
as an SCCP subsystem by establishing a service end-point through the
SCCP multiplexer and binding the subsystem address to that endpoint.
MT-LEVEL
MT-Safe
SYNOPSIS
int sccp_reg(sccp_reg_t *reg_p)
reg_p
This argument points to a sccp_reg_t structure containing the following
members:
word_t sp;
word_t ssn;
word_t recovery;
word_t load_share;
unsigned conn_size;
Page 9 - 23
1-1600-1003-01
SCCP API Library
The sp and ssn fields specify the address of the subsystem, being the
logical signaling point index and the subsystem number, respectively.
The recovery field is used to indicate the connection recovery policy for
the subsystem. This policy defines how to handle the active connections
of a terminating instance of the subsystem. This field can assume one of
the following reasons:
L_REC_RESUME - Resume connection. Connections are kept in
active state and the messages for those connections are routed to
another instance of the subsystem.
L_REC_ABORT - Connection release is initiated and connection
resources are de-allocated.
L_REC_CLEAR - Connection resources are de-allocated without
connection release.
The load_share flag defines the SCCP message distribution policy
towards subsystems.
L_LOADSHARE - All Class 0 connectionless messages and
Connection Request messages which are destined to a local
subsystem are distributed to different instances of the subsystem in a
round-robin fashion by the receiving SCCP. Class 1 messages are
distributed to the closest (own host or the next in chain) instance of
the subsystem.
L_ROUTE2CLOSEST - All messages which are destined to a local
subsystem are routed to the closest (own host or the next in chain)
instance of the subsystem by the receiving SCCP.
L_ROUTE2MASTER - All messages which are destined to a local
subsystem are routed to a fixed instance of the subsystem throughout
the SP.
The conn_size field indicates the average number of expected
simultaneous connections for the subsystem. This information is used to
allocate subsystem resources and optimize access to connection related
data.
RETURN VALUES
file descriptor
-1
On success.
On failure. Sets errno to indicate the error.
ERRORS
<EINVAL>::NULL pointer passed for reg_p
Also, see errors for spm_open() and spm_bind().

SEE ALSO spm_open() and spm_bind()
Page 9 - 24
1-1600-1003-01
SCCP API Library
9.2.22 sccp_StateInd()
DESCRIPTION
sccp_StateInd()
Unpacks information from SCCP management about the status of
another SCCP subsystem. This call is used when the msgtyp (msgp->msghdr.msgtyp)
field of the IPC message is N_STATE_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_StateInd(IPCmsg_t *msgp, N_StateInd_t *N_StateInd);
fd
msgp
N_StateInd
Pointer to the N_StateInd_t structure that will hold the status information
its affected_subsystem, user_status, and subsystem_mult_ind fields.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 25
1-1600-1003-01
SCCP API Library
9.2.23 sccp_StateReq()
DESCRIPTION
sccp_StateReq()
Sends message to inform SCCP management about the status of
the calling subsystem process. Status can be in service or out of service.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_StateReq(int fd, N_StateReq_t *N_stateReq);
fd
N_StateReq
Pointer to the N_State_Req_t structure with the affected_subsystem and
user_status fields filled appropriately. The valid user_status values are
the literals L_UIS (in service) and L_UOS (out of service), as defined in
sccp_prim.h.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
<EINVUSTAT>::Invalid user status.
SEE ALSO sccp_reg()
Page 9 - 26
1-1600-1003-01
SCCP API Library
9.2.24 sccp_UnidataInd()
DESCRIPTION
sccp_UnidataInd()
Unpacks a message that contains a received MSU. This call is
used when the msgtyp (msgp->msghdr.msgtyp) field of the IPC message is
N_UNITDATA_indication.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_UnidataInd(int fd, ipcmsg_t *msgp, N_UnidataInd_t *N_UnidataInd)
fd
msgp
N_UnidataInd Pointer to the N_UnidataInd_t structure that will hold the parsed data.
The information placed in the called_address, calling_address, and
usr_data fields. The datasize field holds the size of the user data
received.
RETURN VALUE
None
SEE ALSO sccp_reg()
Page 9 - 27
1-1600-1003-01
SCCP API Library
9.2.25 sccp_UnidataReq()
DESCRIPTION
sccp_UnidataReq()
Packs an MSU.
MT-LEVEL
MT-Safe
SYNOPSIS
void sccp_UnidataReq(int fd, N_UnidataReq_t *N_UnidataReq)
fd
N_UnidataReq Pointer to the N_UnidataReq_t structure that has been populated with
the data for the MSU. The user must fill the called_address,
calling_address, seq_control, and return_opt fields properly. The
seq_control field should be set to L_protocolCLbasic or
L_protocolCLsequence depending on what class of service is desired.
The datasize field must be set to indicate the size of user data. The
combined size for user data, called party address, calling party address
and the length indicators is limited by the literal L_MAXDATA, which is
defined in sccp_sccl.h. If the total size for the parameters exceeds
L_MAXDATA, N_UnidataReq() will fail with the EUDT2LRG error.
The flags are set to indicate if the optional parameter, importance, is
included.
RETURN VALUE
0
-1
On success.
ERRORS
was to be created.
<EINVADDIND>::Invalid address indicator.
<EUDT2LRG>::Unidata is too large.
<EDESTBLK>::Segmentation service is requested to a destination that is
not deliverable.
SEE ALSO sccp_reg()
Page 9 - 28
1-1600-1003-01
SCCP API Library
Page 9 - 29
1-1600-1003-01
Page 9 - 30
SCCP API Library
1-1600-1003-01
Chapter 10:
10.1
TCAP API Library
TCAP API Library
Chapter Overview
This chapter describes and defines the individual TCAP API function calls that are
discussed in the Distributed7 Application Development Manual. The arguments, return
values, and possible errors are defined for each call. Starting with Distributed7 Rel. 1.3.0,
JAIN (Java APIs for the Integrated Network) TCAP is supported.
10.2
TCAP API Library

For a TCAP application to execute properly, the function calls must be used as defined and
the following header files must be included:
#include <api.h>
#include <tcap.h>
In addition, the application must be compiled properly and the tcmd system process must be
already active.
Refer to the Distributed7 Application Development Manual for information on the use of
these function calls.
The TCAP library (libtcap.a) should be accessed using the $EBSHOME/access/lib path,
($EBSHOME is an environment variable holding the pathname of where the Distributed7
software is installed.)
cc
-L $EBSHOME/access/lib -l tcap -l mtp -l spm -lnsl
Sample source code files, (see list below) are provided to demonstrate the use of
Distributed7 SCCP literals and functions. They should be compiled with the MAKEFILE in
the $EBSHOME/access/sample/tcap directory. After it is compiled, the executable will be
tcm_apidemo.c / tcm_rmtuser.c
TC_query.c
TC_begin.c
Page 10 - 1
1-1600-1003-01
TCAP API Library
Important: Distributed7 1.2. TCAP API is multi-thread (MT) Safe, and can be used with
10.2.1 tcm_close()
DESCRIPTION
tcm_close()
Closes a previously established connection. It de-registers a TC
application, closes the service endpoint associated with the application, and releases any
local library resources (including memory resources) allocated for the application when
the tcm_open() function was called.
Important: This should be the last call made by any TC application when the application is
no longer needed for exchanging TCAP messages. Failure to invoke this function by an
application will cause the resources allocated by the TCAP API Library (on behalf of the
application) to remain allocated indefinitely.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_close(int fd );
fd
The fd argument identifies the service end point associated with the
application and should obtained via a previous tcm_open() call.
RETURN VALUES
0
-1
On success.
ERRORS
<ESYSDOWN>::Unable to service user request since the system software is
in the process of being shut down.
SEE ALSO
tcm_open()
Page 10 - 2
1-1600-1003-01
TCAP API Library
10.2.2 tcm_getcomp()
DESCRIPTION
tcm_getcomp()
Retrieves an individual component contained in a received TCAP
message. Used for non-adopted dialogues only. The message was previously received
and initialized with the spm_rcv() and tcm_rcv() function calls. Before calling this
function, it should be determined that components are present. For example, the
component present field of the tcmdlg_t data structure will be set on return from the
tcm_rcv() call if a component is present.
More than one component can be in the message. Each one is retrieved by a separate call
of this function. The components will be retrieved in the order that they were placed by
the remote end. To retrieve all the components, this call can be issued repetitively until it
fails with the ENOCMP error.
This function performs various sanity checks on the components before submitting them
to the TC application. This enables abnormal situations to be detected and acted upon by
the system. When an abnormal situation is detected, both local and remote ends will be
informed automatically through reject components generated by the system. The system
will discard the erroneous component and return a reject component instead of the
component from the message. The system will put the reject component for the remote
end in the next message that is generated and sent to the remote end by the calling
application. If the invoke ID can be retrieved by the system successfully, the operation to
which the component is related will also be cancelled.
Important: For ITU White Book, ITU 97, ETSI 97, and ANSI 96 applications, if the
dialogue portion present field of tcmdlg_t indicates the dialogue portion is present, the
tcm_getdlgp() function MUST be called first.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getcomp(int fd , ipcmsg_t * msg , tcmcomp_t * comp );
fd
Identifies the service endpoint through which the TCAP message was
received.
msg
Points to the TCAP message that was retrieved by spm_rcv(), initialized
by tcm_rcv(), and was determined to have one or more components.
comp
Points to a user data structure into which the function should put the
retrieved component. The last component field of this structure will be
set to 0 if more components are present. The following component type
identifiers are supported: With this call, the dlgid field of the structure is
filled with the dialogue id of the transaction but the tr_id is left
unassigned:
L_TC_A_INVOKE_L: Invoke Last [ANSI].
Page 10 - 3
1-1600-1003-01
TCAP API Library
L_TC_A_INVOKE_NL: Invoke Not Last [ANSI].

L_TC_A_RESULT_L: Return Result Last [ANSI].
L_TC_A_RESULT_NL: Return Result Not Last [ANSI].
L_TC_A_ERROR: Return Error [ANSI].
L_TC_A_REJECT: Reject [ANSI].
L_TC_A_LOC_CANCEL: Local Cancel [ANSI].
L_TC_C_INVOKE: Invoke [CCITT].
L_TC_C_RESULT_L: Return Result Last [CCITT].
L_TC_C_RESULT_NL: Return Result Not Last [CCITT].
L_TC_C_ERROR: Return Error [CCITT].
L_TC_C_REJECT: Reject [CCITT].
L_TC_C_LOC_CANCEL: Local Cancel [CCITT].
RETURN VALUES
0
-1
On success.
ERRORS
<EDLGID>::Invalid dialogue identifier.
<ENOCMP>::No more components left in the message.
<ENODLGPOR>::Dialogue portion is not available.
SEE ALSO
tcm_rcv(), tcm_putcomp(), tcm_putdlgp(),tcm_rcv_n(), tcm_putcomp_n(),
tcm_putdlgp_n()
10.2.3 tcm_getdlgid()
DESCRIPTION
tcm_getdlgid()
Obtains a new unused dialogue identifier, also called a transaction
identifier, from the system so that the requesting application can start a new dialogue
(transaction) through the specified service endpoint.
When an acquired dialogue identifier is no longer used, it should be released using the
tcm_rlsdlgid() function call.
MT-LEVEL
MT-Safe
Page 10 - 4
1-1600-1003-01
TCAP API Library
SYNOPSIS
int tcm_getdlgid(int fd);
fd
Identifies the service endpoint through which the dialogue will occur. It
is the file descriptor that was returned by the tcm_open() call when the
service endpoint was established.
RETURN VALUES
dialogue id
-1
On success.
ERRORS
<ENDR>::All dialogue identifiers are currently in use. Distributed7
allows each TC user process to open up to L_TC_NUMBER_OF_DLGS
dialogs concurrently.
SEE ALSO
tcm_open(), tcm_putcomp(), tcm_putdlgp(), tcm_snd(), tcm_rlsdlgid()
10.2.4 tcm_getdlgp()
DESCRIPTION
tcm_getdlgp()
Retrieves the contents of the dialogue portion from a received
TCAP message. Used for non-adopted dialogues only. The message was previously
received and initialized with the spm_rcv() and tcm_rcv() function calls. Before calling
this function, it should be determined that the dialogue portion is present. For example,
the dialogue portion present field of the tcmdlg_t data structure will be set on return from
the tcm_rcv() call if the dialogue portion is present. This function must be called before
retrieving any components with tcm_getcomp().
Important: This function is only used by TC applications that follow the ITU White Book
(WB), ITU 97, ETSI 97, and ANSI 96 recommendations.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getdlgp(int fd , ipcmsg_t * msg , tcmdlgp_t * dlgp );
fd
received.
Page 10 - 5
1-1600-1003-01
msg
dlgp
TCAP API Library
Points to the TCAP message that was retrieved and has a dialogue
portion.
retrieved dialogue portion. With this call, the dlgid field of the structure is
filled with the dialogue id of the transaction but the tr_id is left
unassigned. The following dialogue type identifiers are supported:
L_TC_C_DIALOGUE_REQ: Dialogue Request [CCITT].

L_TC_C_DIALOGUE_RESP: Dialogue Response [CCITT].
L_TC_C_DIALOGUE_ABORT: Dialogue Abort [CCITT].
L_TC_C_DIALOGUE_UNI: Unidirectional Dialogue [CCITT].
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcm_rcv(), tcm_putcomp(), tcm_putdlgp(),tcm_rcv_n(), tcm_putcomp_n(),
tcm_putdlgp_n()
10.2.5 tcm_getdpa()/tcm_setdpa()
DESCRIPTION
tcm_getdpa() Allows a TC application to retrieve the default setting of the destination party
address associated with a particular dialogue. The fd and dlgid arguments identify the
endpoint and dialogue ID of interest, respectively. Upon successful execution, tcm_getdpa()
copies the information retrieved to a user space memory location that is pointed to by the
cpa argument.
TC applications that are designed to manipulate the default destination party address
information associated with a particular dialogue must invoke the tcm_setdpa() function
call, and pass the desired address information to it using the cpa argument. Upon successful
execution of tcm_setdpa() function call, destination party address information maintained
by the TCAP API library is overwritten by the user-specified address.
By default, destination party address information is extracted and saved internally by the
TCAP API library as follows:
Page 10 - 6
1-1600-1003-01
TCAP API Library
Incoming:
ANSI L_TC_A_QWP or L_TC_A_QWOP messages
CCITT L_TC_C_BEGIN messages
Outgoing:
ANSI L_TC_A_QWP, L_TC_A_QWOP, or L_TC_A_UNI messages
CCITT L_TC_C_BEGIN or L_TC_C_UNI messages
Thus, TC applications interested in manipulating the default destination address information
for an active transaction should invoke the tcm_setdpa() function after an appropriate
tcm_rcv() or tcm_snd() call.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getdpa/int tcm_setdpa(int fd,int dlgid,cpa_t * cpa);
fd
Identifies the endpoint.
dlgid
Identifies the dialogue ID of interest.
cpa
Points to a user space memory location
RETURN VALUES
0
-1
On success.
ERRORS
<EDLGID>::The dialogue identifier specified is invalid.
SEE ALSO
tcmd, tcm_rcv(), and tcm_snd()
10.2.6 tcm_getldflag()
DESCRIPTION
tcm_getldflag()Retrieves the current settings of the load-sharing flags for all the instances
of a TC application and places them as a bit-mask in a user-specified memory location. Each
bit of the bit-mask indicates whether load-sharing is enabled or disabled for a certain
instance (1s indicate load-sharing enabled, 0s indicate load-sharing disabled). The leastsignificant bit of this bit-maskbit position 0corresponds to instance number 0, i.e., the
tcmd daemon process responsible for setting up and maintaining the TCAP multiplexer, and
is instrumental in identifying whether or not host-based load-sharing is currently enabled. If
Page 10 - 7
1-1600-1003-01
TCAP API Library
the least-significant bit position contains a value of 1, this should be interpreted to mean that
host-based load-sharing is currently enabled. Alternatively, a value of 0 in this bit position
should be interpreted to mean that host-based load-sharing is currently disabled.
Applications interested in finding out about the load-sharing flags associated with their
individual instances should always start from the bit position 1 (which corresponds to the
instance number 1) and go up when interpreting the load-sharing flag settings for their
instances.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getldflag(int fd, tcmflag_t *flags);
fd
Identifies the service endpoint of the application. The value was returned
by the tcm_open() call.
flags
Points to the memory location where the bit-mask should be stored.
Analysis should include bits 1 through 63 to determine the settings for
instances 1 through 63. Bit 0 should be ignored. A 1 for the bit means
load-sharing is enabled while a 0 means it is disabled.
RETURN VALUES
0
-1
On success.
ERRORS
On failure, errno is set to one of the following:
SEE ALSO
tcmd, tcm_open(), tcm_setldflag(), tcm_setldsopt()
Page 10 - 8
1-1600-1003-01
TCAP API Library
10.2.7 tcm_getldsopt()
DESCRIPTION
tcm_getldsopt() Retrieves the current settings of the instance-based load-sharing
algorithm that is used and saves it in a user-specified memory location
pointed to by the opts argument.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getldsopt(int fd, int * opts);
fd
opts
Points to the memory location which will contain an integer value.
Acceptable values are:
L_TC_INST_LOAD_SHARE_OPT_LB (for least-busy)
L_TC_INST_LOAD_SHARE_OPT_RR (for round-robin)
RETURN VALUES
0
-1
On success. Also returns the current setting of the instance-based loadsharing algorithm that is in use.
ERRORS
SEE ALSO
tcmd, tcm_open(), tcm_ldshare()
10.2.8 tcm_get_msg_priority()
DESCRIPTION
tcm_get_msg_priority() Allows a TC application to retrieve the priority level of the last
incoming message associated with a specific dialogue.
MT-LEVEL
MT-Safe
Page 10 - 9
1-1600-1003-01
TCAP API Library
SYNOPSIS
int tcm_get_msg_priority(int fd,int dlgid,byte_t* prio);
fd
Identifies the service endpoint through which the message is received.
dlgid
Dialogue ID that is stipulated for the last incoming message.
prio
Points to a user-space memory location to which the retrieved priority
level is copied. The priority level retrieved is that of the message that has
been processed through the last tcm_rcv() call by that application.
RETURN VALUES
0
-1
On success.
ERRORS
<EBADF>::Invalid file descriptor is specified.
<EDLGID>:: Invalid dialogue identifier is specified.
<EACCES>:: Operation permission to the calling process is denied.
SEE ALSO
tcmd, tcm_snd(), tcm_rcv(), tcm_get_priority(), and tcm_set_priority().
10.2.9 tcm_getopa()/tcm_setopa()
DESCRIPTION
tcm_getopa()Allows a TC application to retrieve the default setting of origination party
address associated with a particular dialogue. The fd and dlgid arguments identify the
endpoint and dialogue ID of interest, respectively. Upon successful execution, tcm_getopa()
copies the information retrieved to a user space memory location that is pointed to by the
cpa argument.
TC applications interested in manipulating the default origination party address information
associated with a particular dialogue should invoke the tcm_setopa() function call and pass
the desired address information to it using the \f2cpa\fP argument. Upon successful
execution of tcm_setopa() function call, origination party address information maintained
by TCAP API library will be overwritten by the user-specified address.
By default, origination party address information is extracted and saved internally by the
TCAP API library as follows:
Incoming:
ANSI L_TC_A_QWP or L_TC_A_QWOP messages
CCITT L_TC_C_BEGIN messages
Outgoing:
ANSI L_TC_A_QWP, L_TC_A_QWOP, or L_TC_A_UNI messages
CCITT L_TC_C_BEGIN or L_TC_C_UNI messages
Page 10 - 10
1-1600-1003-01
TCAP API Library
Thus, TC applications interested in manipulating the default origination address information

for an active transaction should invoke the tcm_setopa() function after an appropriate
tcm_rcv() or tcm_snd() call.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getdpa/int tcm_setdpa(int fd,int dlgid,cpa_t * cpa);
fd
Identifies the endpoint.
dlgid
Identifies the dialogue ID of interest.
cpa
Points to a user space memory location
RETURN VALUES
0
On success.
-1On failure; errno is set to indicate the error.
ERRORS
SEE ALSO
tcmd, tcm_rcv(), and tcm_snd()
10.2.10 tcm_getpolicy()
DESCRIPTION
tcm_getpolicy()This function allows a TC application to find out about the transaction
recovery policy that is in effect. Information about the current policy setting is copied to the
memory space pointed to by the flags argument.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getpolicy(int fd , int * flags );
fd
This argument identifies the service endpoint associated with the TC
application and should be obtained through a previous call to the
tcm_open() function.
Page 10 - 11
1-1600-1003-01
flags
TCAP API Library
Specifies the desired recovery policy in the case of a fatal failure, i.e.,
when the TC application that is in charge terminates its execution
prematurely. The permissible values of flags argument are as follows:
L_TC_POLICY_PURGE - Terminate all active transactions owned
by the TC application and release transaction ID's associated.
L_TC_POLICY_ABORT - Terminate all active transactions owned
by the TC application and notify the remote end via abort indicator
messages.
L_TC_POLICY_ADOPT - Adopt all active transactions owned by
the TC application and re-distribute their ownership among the
surviving instances of the application.
RETURN VALUES
0
-1
On success. Also returns the current recovery policy setting to the user
via the flags argument.
ERRORS
SEE ALSO
tcmd, tcm_open ()
10.2.11 tcm_get_priority()
DESCRIPTION
tcm_get_priority()
Retrieves the last priority level associated with outgoing
messages for a specified dialogue.
MT-LEVEL
MT-Safe
SYNOPSIS
fd
Identifies the service endpoint through which the message is transmitted.
dlgid
Dialogue ID that is stipulated for the last outgoing message.
prio
level is copied.
Page 10 - 12
1-1600-1003-01
TCAP API Library
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcmd, tcm_snd(), tcm_rcv(), tcm_get_msg_priority(), and tcm_set_priority().
10.2.12 tcm_notify ()
DESCRIPTION
tcm_notify()
The tcm_notify() function can be used by a TC application
program to express interest in TCAP related events that may occur while operating under
the Distributed7 environment and specify what action should take place if and when one
of the pending events occurs. Thus, it enables TC applications to perform asynchronous
processing.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_notify(int fd,dword_t event,void * arg,void(*func)(int));
event
Specifies the particular event for which the user-specified func function
should automatically be invoked. At the time func is invoked, file
descriptor associated with the service endpoint at which the event has
occurred will be passed as an argument to it. This is useful especially if
the TC application is interested in detecting TCAP related events via
multiple endpoints and specifies the same func address during multiple
calls to tcm_notify().
The event argument assumes a value from the following list:
M_USR_TCAP_DLG_HIMARK
The number of dialogue IDs allocated by the TCAP layer in
associated with the local TC application exceeded a user-specified
high mark. By default, each application can allocate up to a
maximum of L_TC_NUMBER_OF_DLGS dialogues at a given
time. When all dialogue ID's are in use, an attempt toacquire a new
dialogue ID for an outgoing transaction using tcm_getdlgid() would
Page 10 - 13
1-1600-1003-01
TCAP API Library
result in a failure with an appropriate error code; thus, it is possible

for a TC application to detect dialogue ID depletion for outgoing
transactions. Note however that for transactions originated by the
remote end, depletion of dialogue IDs on D7 goes undetectedby the
receiving TC application as the D7 product will simply return an
abort indicator to the remote end with an appropriate abort cause and
will nottake any further action. Thus, without using tcm_notify(), it
becomes impossible for an application to detect dialogue ID
depletion when handling incoming TCAP transactions.
Setting a high mark on dialogue ID utilization helps TC application
programs to detect abnormal situations where dialogue IDs get
allocated but not freedfor one reason or anotherunder all
circumstances, i.e., regardless of who originates the transaction.
The arg argument sets the high mark to a particular value and it
should be constructed as a pointer to an integer variable that holds the
desired high mark value.
M_USR_TCAP_DLG_LOMARK
The number of dialogue IDs allocated by the TCAP layer in
associated with the local TC application fell below a user-specified
low mark. Setting a low mark on dialogue ID utilization helps
application programs to detect when abnormal situations described
above disappear and things return back to normal.
The arg argument sets the low mark to a particular value and it
should be constructed as a pointer to an integer variable that holds the
desired low mark value. Note that a low mark setting can never
exceed the current high mark setting.
An application can cancel a previously placed tcm_notify() request by
re-invoking the tcm_notify() function with the exact same values of the
event and arg arguments as before but with a NULL func argument this
time.
RETURN VALUES
0
-1
On success.
ERRORS
<EINVAL>::The high/low value specified is beyond the permissible [0,
L_TC_NUMBER_OF_DLGS] range.
<ERANGE>::The low mark value specified contradicts with the current high
mark setting or vice versa.
<ENOMEM>::Unable to register the user-specified event due to lack of
memory space.
<EINTR>::A signal was caught during processing of the user request.
Page 10 - 14
1-1600-1003-01
TCAP API Library
SEE ALSO
tcm_getdlgid(), tcm_rlsdlgid(), and spm_notify().
10.2.13 tcm_open()
DESCRIPTION
tcm_open()
Registers a TC application process with the Distributed7
environment by establishing a connection at the TCAP multiplexer and allocating the
local library resources necessary for the application to communicate with other
applications using the TCAP protocol. This should be the very first function call invoked
by all TC application programs executing under Distributed7. The tcmd process must be
running to be able to call this or any other TCAP functions. This function returns a file
descriptor that will be used with other TCAP function calls to identify the connection. A
TC application can establish multiple connections with the system by issuing multiple
tcm_open() calls. Thus, it is possible for a given application to communicate concurrently
with multiple entities through separate connections and possibly using different transport
service providers and/or TCAP protocol variants. This call is deprecated and does not
support policy settings during user registration. Please note that tcm_setpolicy()
function is also deprecated as of this release. Use tcm_open_n to use registration time
policy settings. When tcm_open is called, the default transaction recovery policy of
purge is applied.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_open(tcmbuf_t * buf , tcmopts_t * opts , tcmaddr_t * addr , tcmaddr_t *
rmtaddr );
buf
Points to the tcmbuf_t structure which defines the TCAP buffers for the
application. The structure is as follows:
typedef struct {
int
int
} tcmbuf_t;
bufcnt;
bufsize;
where bufcnt specifies the total number of internal buffers that should be
allocated by the TCAP library on behalf of the calling process.
where bufsize specifies the size, in bytes, of each buffer that should be
allocated by the TCAP library on behalf of the calling process. The
actual buffer size is four times the value specified. The size is based on
the maximum size of a component the process will submit in a
transaction. Internal buffers are used by the TCAP API library to store
TCAP components and/or dialogue-related information temporarily
Page 10 - 15
1-1600-1003-01
TCAP API Library
(before they are submitted to the TCAP multiplexer for transmission).

The actual buffer size allocated by tcm_open() is four times the value
specified via the bufsize argument.
Important: The calling process is responsible to specify the correct number and size of
buffers, based on the maximum size and number of components the application plans to
submit within individual transactions. Insufficient internal buffers will result in failures of
subsequent tcm_putcomp() function calls with an errno value of ENOBUF.
optsPoints to the tcmopts_t user data structure. The structure is as follows:
typedef struct {
typedef struct {
word_t trproto; /* underlying transport protocol */
#define L_TC_TPRO_UNDEFINED 0x0000 /* protocol not specified */
#define L_TC_TPRO_SCCP 0x0100 /* use SCCP transport services
*/
#define L_TC_TPRO_TCPIP 0x0200 /* use TCP/IP transport
services */
#define L_TC_TPRO_SCCP_RMT 0x0400 /* use remote SCCP transport
services */
/* transport protocol bit masks */
#define L_TC_OPT_TRPROTO_MASK 0xff00 /* protocol */
word_t version; /* TCAP protocol version */
/* base protocol versions */
#define L_TC_VERS_UNDEFINED 0x0000 /* version not specified */
#define L_TC_VERS_ANSI_88 0x0001 /* ANSI 88 */
#define L_TC_VERS_ITU_WB 0x0004 /* CCITT/ITU white book */
#define L_TC_VERS_ITU_BB 0x0005 /* CCITT/ITU blue book */
#define L_TC_VERS_ITU_97 0x0006 /* CCITT/ITU 97 */
#define L_TC_VERS_ETSI_97 0x0007 /* ETSI 97 */
/* customer specific protocol versions */
#define L_TC_VERS_ITU_ATTL 0x0010 /* CCITT/ITU AT&T variant 1
*/
#define L_TC_VERS_ITU_ATT2 0x0020 /* CCITT/ITU AT&T variant 2
*/
/* version bit masks */
#define L_TC_OPT_VERSION_MASK 0x00ff /* base + customer version
*/
#define L_TC_OPT_VERSION_BASE_MASK 0x000f /* base version */
#define L_TC_OPT_VERSION_SPEC_MASK 0x00f0 /* customer version */
dword_t maxdlgs; /* max # dialogue identifiers */
dword_t rmtuser; /* reserved for tcm_rmtopen() use */
} tcmopts_t;
where trproto specifies the transport service provider, i.e., SCCP or TCP/
IP, to utilize when exchanging TCAP messages between two TC
applications.
Page 10 - 16
1-1600-1003-01
TCAP API Library
where version specifies the TCAP protocol variant, i.e., ANSI/CCITT

variants of the TCAP protocol that the applications are interested in using.
The version must include a base protocol version, i.e.,
L_TC_VERS_ITU_WB, and can optionally include a customer specific
protocol version (e.g., L_TC_VERS_ITU_ATTL).
Examples:
/* set version to ITU White Book */version =
L_TC_VERS_ITU_WB;
/* set version to AT&T variant of ITU White Book */version =
L_TC_VERS_ITU_WB | L_TC_VERS_ITU_ATTL;
where maxdlgs specifies the maximum number of dialogue identifiers that

can be concurrently acquired by TC user process. Distributed7 allows each
TC user process to acquire up to a maximum of
L_TC_NUMBER_OF_DLGS dialogues concurrently.
where rmtuser is used by the tcm_rmtopen() function.
addr
Points to the tcmaddr_t user data structure which identifies the calling
process. This structure is equivalent to the ipcaddr_t data type defined in
the <api.h> header file. The structure is as follows:
typedef struct {
union {
ss7obj_t ss7obj;
tcpobj_t tcpobj;
...
} un;
word_t adrtyp;
} ipcaddr_t;
typedef ipcaddr_t tcmaddr_t;
The two addressing types available when registering with the

Distributed7 environment as a TC application are L_SS7OBJ and
L_TCPOBJ. The L_SS7OBJ address type is reserved for TC
applications which plan to utilize the services of the SCCP protocol when
exchanging TCAP messages, whereas the L_TCPOBJ address type is
reserved for TC applications interested in using transport services of the
TCP/IP protocol. Note that based on the address information specified
via the adrtyp argument, the calling process is also expected to provide
the detailed address information associated with itself by populating the
data structure of type ss7obj_t or tcpobj_t. These data structures contain
the following fields:
typedef struct {
Page 10 - 17
1-1600-1003-01
TCAP API Library
word_t sp; /* signaling point number */

word_t up; /* user part number */
word_t ssn; /* sub-system number */
word_t inst; /* instance number */
} ss7obj_t;
typedef struct {
dword_t inetaddr; /* machine i-net address */
word_t port; /* port identifier */
} tcpobj_t;
rmtaddr
Page 10 - 18
One noteworthy point in both data structures involves the use of the inst
field. The Distributed7 environment allows multiple instances of a TC
application associated with a particular SCCP subsystem or a particular
TCP/IP port identifier to coexist, i.e., in order to process TCAP messages
received by the TC application in a collaborative manner. At the time of
registration, each such application will be assigned a unique number, i.e.,
the instance number, to be able to differentiate it from other instances of
the same application. Thus, information in the inst field of either data
structure is meaningful upon successful return from the tcm_open()
function call, as it contains the instance number assigned to the calling
process. TC applications interested in finding out the instance number
assigned to them by the system should check on the value of the inst field
upon successful return from the tcm_open() function call.
When the L_TCPOBJ addressing method is in use, information specified
via the port argument will be used by the system as a local reference
number to a particular TC application. This information is used to associate
incoming TCAP messages, i.e., messages generated by the remote end,
with a particular application. The permissible values of the port argument
lie between [0, L_TC_MAX_PORT_ID - 1]. If and when a TC application
features multiple instances, all such instances should register with the
system using the same port value.
number to a particular TC application. This information is used to associate
incoming TCAP messages, i.e., messages generated by the remote end,
with a particular application. The permissible values of the port argument
lie between [0, L_TC_MAX_PORT_ID - 1]. If and when a TC application
This argument points to a user data structure that identifies the remote
entity that the calling process intends to exchange TCAP messages with. At
this time, information contained in this field is meaningful only when the
underlying transport service protocol is designated to be TCP/IP, i.e., as it
informs the system about the details of the destination address for TCAP
1-1600-1003-01
TCAP API Library
messages to be generated by the calling process. If and when the calling

process designates SCCP as the transport service provider (instead of TCP/
IP), information specified via the rmtaddr argument is not used by the
system; therefore, rmtaddr may be set to NULL in such cases.
Important: When TCAP over SCCP is in use, following registration with the Distributed7
environment, a TC application is expected to invoke the sccp_StateReq() function call to
indicate to the SCCP layer that the local SSN associated is now in service. A failure to do so
will cause the SSN status to remain prohibited which in return will result in the SCCP layer
not to deliver any incoming messages to the TC application. Similarly, prior to termination
of all instances of a TC application, sccp_StateReq() function call needs to be invoked one
more time to indicate to the SCCP layer that the SSN associated is now going out-ofservice;
therefore, the local SSN status should be marked as prohibited.
RETURN VALUES
file descriptor
-1
On success. (non-negative integer)

The file descriptor returned by tcm_open() should be used by the calling
process to refer to the particular connection established when performing
TCAP related activities (e.g. assembling/disassembling/exchanging
TCAP messages) via other functions comprising the TCAP library.
ERRORS
<ESRCH>::The tcmd daemon on the local host is not running.
<EMFILE>::There is no more file descriptor available.
<EMAXUSR>::Maximum number of user processes allowed to co-exist for a
given SCCP subsystem or TCP/IP port identifier is exceeded.
Distributed7 environment allows up to 63 instances of a
particular TC application to coexist at a given time.
<EBADMSG>::An invalid and/or corrupted response has been received from
the tcmd(1E) daemon.
<ETIME>::Unable to process request specified on time due to a
communication failure with the tcmd(1E) daemon process.
<ENORES>::Unable to allocate buffer space specified.
<ENOMEM>::Unable to allocate kernel-space memory to store transaction
data.
<ESSN>::Invalid subsystem number is specified
<EMAXDLG>::Maximum number of concurrent dialogue IDs permissible is
exceeded.
Note: For a list of additional errno values, refer to the spm_open() and spm_bind()
function calls.
Page 10 - 19
1-1600-1003-01
TCAP API Library
NOTES
Successful operation of the tcm_open() function call, as well as all other function calls
comprising the TCAP API library, requires the tcmd daemon process to be up and running.
SEE ALSO
tcmd, spm_open(), spm_bind(), tcm_close(), tcm_getdlgid(), tcm_get(), tcm_ldshare(),
tcm_put(), tcm_rcv(), tcm_snd(), tcm_rlsdlgid(), tcm_open_n()
10.2.14 tcm_putcomp()
DESCRIPTION
tcm_putcomp()
Assembles and submits one or more components (next to each
other) to the TCAP layer for inclusion within a dialogue (transaction). Used for nonadopted dialogues only. After all appropriate components associated with a dialogue are
assembled and submitted, the TC application should invoke the tcm_snd() function to
transmit the dialogue.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_putcomp(int fd , tcmcomp_t * comp );
fd
Identifies the service endpoint through which the dialogue will be
transmitted.
comp
Points to the tcmcomp_t data structure which contains the component.
With this call, the dlgid field of the structure is the relevant transaction
identification information and must be filled properly with the dialogue
identification. The full transaction id information is not used and tr_id
field is ignored. All relevant fields must be populated, as described in the
Distributed7 Application Development Manual.
RETURN VALUES
# of bytes added to dialogue On success.
-1
ERRORS
<EINVID>::Invalid invoke identifier.
<ECMPPAR>::Error in component parameters.
<ECMPTYPE>::Invalid component type.
Page 10 - 20
1-1600-1003-01
TCAP API Library
<EIMSGSIZE>::Reserved buffer size is not large enough to store the

information submitted.
<ENOBUF>::No more free buffers.
<EINVDLGTAG>::Invalid dialogue portion tag.
<EINVAPPCNTINF>::Invalid application context information.
<EINVUSERINF>::Invalid user information.
<EINVRSLTVAL>::Invalid result value.
<EINVDLGSRVVAL>::Invalid dialogue service value.
<EINVDLGSRVTYP>::Invalid dialogue service type.
<EINVABRTVAL>::Invalid abort value.
<EINAPDLGTYP>::Invalid application dialogue type.
SEE ALSO
tcm_snd(),tcm_putcomp_n()
10.2.15 tcm_putdlgp()
DESCRIPITON
tcm_putdlgp()Assembles and submits the optional dialogue portion to the TCAP layer to be
put in a dialogue (transaction). Used for non-adopted dialogues only. When including the
dialogue portion, the dialogue portion present field must be set in the tcmdlg_t data
structure of the tcm_snd() call so that the receiver of the message can retrieve its contents.
Note: This function is only used by TC applications which follow the ITU White Book (WB),
ITU 97, ETSI 97, and ANSI 96 recommendations.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_putdlgp(int fd , tcmdlgp_t * dlgp );
fd
Identifies the service endpoint through which the dialogue will be
transmitted.
dlgp
Points to the tcmdlgp_t data structure which contains the dialogue
portion. With this call, the dlgid field of the structure is the relevant
transaction identification information and must be filled properly with
the dialogue identifier. The full transaction id information is not used and
tr_id field is ignored. All relevant fields must be populated, as described
in the Distributed7 Application Development Manual.
RETURN VALUES
# of bytes added to dialogue On success.
-1
Page 10 - 21
1-1600-1003-01
TCAP API Library
ERRORS
SEE ALSO
tcm_getcomp(), tcm_getdlgp(), tcm_snd(),tcm_getcomp_n(), tcm_getdlgp_n(),
tcm_snd_n(),tcm_putdlgp_n()
10.2.16 tcm_rcv()
DESCRIPTION
tcm_rcv()
Unbundles the transaction portion of a TCAP message that was
retrieved using the spm_rcv() call. Used for non-adopted dialogues only. TC
applications should call this function only when the type of the IPC message received by
the spm_rcv() call is equal to N_UNITDATA_indication (for TCAP over SCCP) or
L_TC_DLG_MSG (for TCAP over TCP/IP), or L_TC_ADOPTED_DLG_MSG (for
either transportation protocol), as these are the only types of TCAP transaction-layer
messages.
Each time the function is called, the component pointers associated with that TCAP
message are reset. After this call, either tcm_getcomp() or tcm_getdlgp() can be called
next, depending on the TCAP information retrieved by this call, to retrieve the contents of
the individual components and/or optional dialogue portion contained within the message.
The decision to invoke either function should be made on the basis of "component
present" and "dialogue portion present" indicators contained within the dialogue retrieved
by the tcm_rcv() function.
Please see the Distributed7 Application Development Manual for more details.
Page 10 - 22
1-1600-1003-01
TCAP API Library
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_rcv(int fd , ipcmsg_t * msg , tcmdlg_t * dlg );
fd
Identifies the service endpoint through which the message was received.
msg
Points to the message data structure whose contents have been retrieved
using the spm_rcv() call.
dlg
Points to the tcmdlg_t data structure where the contents of the
transaction portion should be placed. With this call, the dlgid field of the
structure is filled with the dialogue id of the transaction but the tr_id is
left unassigned.
In case the remote node initiates a dialogue, i.e., by sending a Query
With Permission [ANSI] or Begin [CCITT] message, the TCAP layer
automatically generates a new dialogue identifier and returns this
identifier to the user within the tcmdlg_t data structure. For
unidirectional dialogue types, a NULL dialogue identifier is returned.
With this call, the dlgid field of the structure is filled with the dialogue id
of the transaction but the tr_id field is left unassigned.
This function supports the following dialogue identifiers:
L_TC_A_UNI - Unidirectional (ANSI)
L_TC_A_QWP - Query With Permission (ANSI)
L_TC_A_QWOP - Query Without Permission (ANSI)
L_TC_A_RESPONSE - Response (ANSI)
L_TC_A_CWP - Conversation With Permission (ANSI)
L_TC_A_CWOP - Conversation Without Permission (ANSI)
L_TC_A_ABORT - Abort (ANSI)
L_TC_C_UNI - Unidirectional (CCITT)
L_TC_C_BEGIN - Begin Conversation (CCITT)
L_TC_C_END - End Conversation (CCITT)
L_TC_C_ CONTINUE - Continue Conversation (CCITT)
L_TC_C_ABORT - Abort (CCITT)
RETURN VALUES
0
-1
On success.
On failure; errno is set to an appropriate value.
ERRORS
Page 10 - 23
1-1600-1003-01
TCAP API Library

<EDLGPAR>::Error in dialogue parameters.
SEE ALSO
tcm_snd(),tcm_snd_n(),spm_rcv(),tcm_rcv_n()
10.2.17 tcm_rlsdlgid()
DESCRIPTION
tcm_rlsdlgid()
Releases and returns a dialogue identifier (transaction identifier)
to the pool of available dialogue IDs when a dialogue cannot be completed successfully,
for example due to a timer expiration or a delivery failure. Used for non-adopted
dialogues only. Normally, this call is not needed because the system automatically
releases the dialogue ID when a dialogue successfully completes (with an end or an abort).
Any components associated with the dialogue ID being released will be discarded by the
system.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_rlsdlgid(int fd, int dlgid);
fd
Identifies the service endpoint through which the dialogue identifier was
acquired using the tcm_getdlgid() call.
dlgid
Indicates the dialogue ID to be released.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcm_getdlgid(), tcm_rlstrid()
Page 10 - 24
1-1600-1003-01
TCAP API Library
10.2.18 tcm_rmtopen()
DESCRIPTION
tcm_rmtopen()
This call can be used to register a TC application process with the
Distributed7 environment by establishing a connection at the TCAP multiplexer and
allocating all necessary system resources for the application to communicate with other
applications using the transport services provided by the SCCP protocol layer on a remote
host. These system configurations are also referred to as "front-end/back-end"
configurations where the lower layers of SS7 protocol stack, i.e., MTP and SCCP layers,
execute on one or more "front-end" machine and the upper layers of SS7 stack, i.e., TCAP
layer, and/or application-layer software execute on one or more "back-end" machine, and
both groups of host machines are considered to be part of the same distributed
Distributed7 environment.
The functionality provided by this function is very much similar to that of the tcm_open()
function call. The only difference between the two functions being the support for socalled remote TC applications by the former one. This function call is intended to serve
the needs of programmers who plan on starting up TC applications on host machines
where the SCCP layer transport services are not locally available, possibly because the
SCCP software is not running on the local host. By specifying the name of the remote host
machine via the rmthost argument, users of the tcm_rmtopen() function call request from
the Distributed7 platform all necessary arrangements to be made in order for the specified
TC application to execute on the local host, yet use the transport services provided by the
SCCP layer on the designated remote host to exchange TCAP messages. A NULL value
of rmthost instructs the system to use the local SCCP transport services, and therefore
makes the tcm_rmtopen() and tcm_open() functions equivalent from an operational point
of view. Keep in mind that the only category of transport services supported by the
tcm_rmtopen() function is that of the SCCP layer, and not that of the TCP/IP protocol
suite.
Application programs interested in using this function call should always be linked with
the APM library (which is an API library written in C++ language). Note that this in
return necessitates the use of the C++ compiler for all such applications at compile/link
time.
Important: Successful operation of the tcm_rmtopen() function call, as well as all other
function calls comprising the TCAP API library, requires the tcmd daemon process to be up
and running. tcm_rmtopen() further requires the scmd daemon associated with the
signaling point of interest to be up and running on the remote host specified.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_rmtopen(tcmbuf_t * buf, tcmopts_t * opts, tcmaddr_t addr, char * rmthost);
Page 10 - 25
1-1600-1003-01
buf
TCAP API Library
typedef struct {
int
int
} tcmbuf_t;
bufcnt;
bufsize;
allocated by the TCAP library on behalf of the calling process. The actual
buffer size is four times the value specified. The size is based on the
maximum size of a component the process will submit in a transaction.
Internal buffers are used by the TCAP API library to store TCAP
components and/or dialogue-related information temporarily (before they
are submitted to the TCAP multiplexer for transmission). The actual
buffer size allocated by tcm_open() is four times the value specified via
the bufsize argument.
Important: The calling process is responsible to specify the correct number and size of
subsequent tcm_putcomp() function calls with an errno value of ENOBUF.
opts
Points to the tcmopts_t user data structure. The structure is as follows:
typedef struct {
word_t
trproto;
#define L_TC_TPRO_UNDEFINED
#define L_TC_TPRO_SCCP
#define L_TC_TPRO_TCPIP
*/
#define L_TC_TPRO_SCCP_RMT
services */
/* underlying transport protocol */

0x0000
0x0100
0x0200
/* protocol not specified */

/* use SCCP transport services */
/* use TCP/IP transport services
0x0400
/* use remote SCCP transport

#define L_TC_OPT_TRPROTO_MASK 0xff00
word_t
/* base
#define
#define
#define
#define
#define
#define
Page 10 - 26
version;
protocol versions */
L_TC_VERS_UNDEFINED
L_TC_VERS_ANSI_88
L_TC_VERS_ANSI_92
L_TC_VERS_ANSI_96
L_TC_VERS_ITU_WB
L_TC_VERS_ITU_BB
/* protocol */
/* TCAP protocol version */
0x0000
0x0001
0x0002
0x0003
0x0004
0x0005
/*
/*
/*
/*
/*
/*
version not specified */

ANSI 88 */
ANSI 92 */
ANSI 96 */
CCITT/ITU white book */
CCITT/ITU blue book */
1-1600-1003-01
#define L_TC_VERS_ITU_97
#define L_TC_VERS_ETSI_97
TCAP API Library

0x0006
0x0007
/* CCITT/ITU 97 */
/* ETSI 97 */

#define L_TC_VERS_ITU_ATTL
0x0010 /* CCITT/ITU AT&T variant 1 */
#define L_TC_VERS_ITU_ATT2
0x0020 /* CCITT/ITU AT&T variant 2 */
#define L_TC_OPT_VERSION_MASK
*/
#define L_TC_OPT_VERSION_BASE_MASK
#define L_TC_OPT_VERSION_SPEC_MASK
dword_t maxdlgs;
dword_t rmtuser;
0x00ff
0x000f
0x00f0
/* base + customer version

/* base version */
/* customer version */
/* max # dialogue identifiers */

/* reserved for tcm_rmtopen() use */
} tcmopts_t;
where trproto specifies the transport service provider, i.e., SCCP or TCP/
IP, to utilize when exchanging TCAP messages between two TC
applications.
variants of the TCAP protocol that the applications are interested in
using. The version must include a base protocol version, i.e.,
L_TC_VERS_ITU_WB, and can optionally include a customer
specific protocol version (e.g., L_TC_VERS_ITU_ATTL).
Examples:
/* set version to ITU White Book */
version = L_TC_VERS_ITU_WB;
/* set version to AT&T variant of ITU White Book */
version = L_TC_VERS_ITU_WB | L_TC_VERS_ITU_ATTL;
When populating the individual fields of the data structure pointed to by

the opts argument, users of the tcm_rmtopen() function are expected to
populate the value of the rmtuser field as well as (which is not required
in the case of the tcm_open() function). This field assumes a value from
the above list and is instrumental in determining the message routing
policy of the remote TCAP agent, i.e., the tcm_agent daemon process, to
be spawned on the user-specified host machine. For more information
regarding the above rmtuser settings and how they impact the message
routing policy of the remote TCAP agent, refer to the man pages of the
tcm_agent daemon.
where maxdlgs specifies the maximum number of dialogue identifiers
that can be concurrently acquired by TC user process. Distributed7
allows each TC user process to acquire up to a maximum of
Page 10 - 27
1-1600-1003-01
addr
TCAP API Library
typedef struct {
union {
ss7obj_t ss7obj;
tcpobj_t tcpobj;
...
} un;
word_t adrtyp;
} ipcaddr_t;
With the tcm_rmtopen() function, only one addressing type is available

when registering with the Distributed7 environment as a TC application:
L_SS7OBJ. The L_SS7OBJ address type is reserved for TC
applications which plan to utilize the services of the SCCP protocol when
exchanging TCAP messages. Users of the tcm_rmtopen() function are
expected to populate the addr argument using the L_SS7OBJ addressing
method at all times. Note that based on the address information specified
via the adrtyp argument, the calling process is also expected to provide
the detailed address information associated with itself by populating the
data structure of type ss7obj_t. This data structure contains the following
fields:
typedef struct {
} ss7obj_t;
rmthost
Page 10 - 28
structure is meaningful upon successful return from the tcm_rmtopen()
upon successful return from the tcm_rmtopen() function call.
This argument is the name of the remote host machine. This requests
from the Distributed7 platform all necessary arrangements to be made in
order for the specified TC application to execute on the local host, yet use
the transport services provided by the SCCP layer on the designated
1-1600-1003-01
TCAP API Library
remote host to exchange TCAP messages. A NULL value for this

argument instructs the system to use the local SCCP transport services.
This would make the tcm_rmtopen() and tcm_open() functions
equivalent from an operational point of view.
RETURN VALUES
fd
-1
On success. A non-negative integer which should be used by the calling

process to refer to the particular connection established when performing
TCAP related activities (e.g., assembling/disassembling/exchanging
TCAP messages) via other functions comprising the TCAP library.
ERRORS
given SCCP subsystem or TCP/IP port identifier is exceeded.
AccessMANAGER environment allows up to 63 instances of a
particular TC application to coexist on a specified host at a
given time.
the tcmd daemon.
communication failure with the tcmd daemon process.
data.
exceeded.
For a list of additional errno values, refer to the manual pages of spm_open(), spm_bind(),
and apm_spawn() function calls.
SEE ALSO tcmd, tcm_agent(), tcm_rmtclose(), tcm_open()
10.2.19 tcm_rmtclose()
DESCRIPTION
tcm_rmtclose()
This function call is used to de-register a remote TC application,
close the service endpoint associated with the application, and release any local/remote
system resources (including memory resources allocated by the local libraries) allocated
for the TC application at the time of a tcm_rmtopen() function call.
Page 10 - 29
1-1600-1003-01
TCAP API Library
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_rmtclose(int fd);
fd
This argument identifies the service endpoint associated with the
application and should be obtained via a previous tcm_rmtopen() call.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO tcmd, tcm_rmtopen(), tcm_close()
10.2.20 tcm_setldflag()
DESCRIPTION
tcm_setldflag()
Manipulates the parameters that control the load-sharing
capability of the calling TCAP application process. The TCAP load-sharing capability
allows multiple instances of a TC application to be associated with a particular SCCP
subsystem or a particular host and port identifier, to collaborate when processing the first
occurrence of L_TC_A_QWP, L_TC_A_QWOP, and L_TC_A_UNI messages for ANSI
or L_TC_C_BEGIN and L_TC_C_UNI messages for CCITT.
All other types of TCAP messages and the successive occurrences of the above listed
messages are assigned to a specific instance of a TC application. They will always be
routed to that instance and will not be load-shared among multiple instances of the
application.
A maximum of 63 instances of a particular TC application can be created on a specific
host. Each instance can originate and send out TCAP messages. It can only receive
unassigned TCAP messages if it invokes the tcm_setldflag() function call and specifies a
flags value of L_TC_INST_LOAD_SHARE_ON. If unassigned messages are not desired,
the tcm_setldflag() function call should be invoked with a flags value of
L_TC_INST_LOAD_SHARE_OFF. By default, the load-sharing flag for the very first
instance of a TC application (instance 1) on a specified host, will always be set to
L_TC_INST_LOAD_SHARE_ON but the load-sharing flags for all other local instances
will be set to L_TC_INST_LOAD_SHARE_OFF. This default ensures that each TC
application has at least one local instance available to receive and process incoming TCAP
messages received through a particular host.
Page 10 - 30
1-1600-1003-01
TCAP API Library
When multiple instances are load-sharing, the system determines which instance should
get the next unassigned TCAP message based on the total number of bytes waiting to be
retrieved from the read-side STREAMS queue of the first instance. If the first instance of
the application clears its read-side queue fast enough, other instances may not receive any
incoming messages. If all local instances of a TC application set their load-sharing flags to
off, the TCAP messages destined for the application will be aborted at the TCAP layer
with the reason, not enough resources.
Starting with Release 1.0.0 of Distributed7, an additional layer of control has been placed
over the aforementioned TCAP load-sharing mechanism. This layer of control involves
load-sharing all incoming and unassigned messages between qualified hosts in a roundrobin fashion first. It is only after the target host is identified, that an incoming message
will be delivered to the least-busy instance running on that host. Application control over
the newly introduced load-sharing mechanism is through the
L_TC_HOST_LOAD_SHARE_ON and L_TC_HOST_LOAD_SHARE_OFF flags,
which can be used in conjunction with the L_TC_INST_LOAD_SHARE_ON and
L_TC_INST_LOAD_SHARE_OFF flags. By default, the system will assume a setting of
L_TC_HOST_LOAD_SHARE_ON as long as the TC application in consideration
features multiple instances across multiple hosts and at least one instance on each host
with a setting of L_TC_INST_LOAD_SHARE_ON. As an automatic result of this, all
incoming and unassigned messages received through a particular host will be load-shared
with all other hosts first, then distributed to the least-busy instance of the application on
the selected host. Note, however, it is possible to disable this mechanism simply by
invoking the tcm_setldflag() function with a flags setting of
L_TC_HOST_LOAD_SHARE_OFF on all appropriate hosts.
MT-LEVEL
MT-Safe
SYNOPSIS
#include <api.h>
#include <tcap.h>
int tcm_setldflag(int fd, tcmflag_t flags);
fd
flags
Indicates whether the application will load-share. The value should be:
L_TC_INST_LOAD_SHARE_ON - instance load sharing on
L_TC_INST_LOAD_SHARE_OFF - no instance load sharing
L_TC_HOST_LOAD_SHARE_ON - host load sharing on
L_TC_HOST_LOAD_SHARE_OFF - no host load sharing
Page 10 - 31
1-1600-1003-01
TCAP API Library
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO tcmd, tcm_open(), tcm_getldflag(), tcm_setldsopt()
10.2.21 tcm_setldsopt()
DESCRIPTION
tcm_setldsopt()This function is designed to manipulate parameters associated with the
instance-based load-sharing capability that is available for use by TC applications running
under the Distributed7 environment.
Users can establish control over the instance-based load-sharing algorithm used by the
TCAP transaction layer by invoking this call.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_setldsopt(int fd, int * opts);
fd
opts
Points to the memory location which will contain an integer value.
Acceptable values are:
L_TC_INST_LOAD_SHARE_OPT_LB (for least-busy) default for
newly registered TC applications
L_TC_INST_LOAD_SHARE_OPT_RR (for round-robin)
RETURN VALUES
0
-1
On success.
ERRORS
Page 10 - 32
1-1600-1003-01
TCAP API Library

SEE ALSO tcmd, tcm_open(), tcm_ldshare()
10.2.22 tcm_setpolicy()
DESCRIPTION
tcm_setpolicy()
As of 1.5.0, this function is deprecated, and the only way to set
the transaction recovery policy is through the newly introduced tcm_open_n() function.
SEE ALSO
tcmd, tcm_open_n()
10.2.23 tcm_set_priority()
DESCRIPTION
tcm_set_priority()
Allows a TC application to set the priority for all outgoing
messages associated with a specified dialogue. This function can be run multiple times
during the life-cycle of a dialogue to send different messages at different priority levels.
MT-LEVEL
MT-Safe
SYNOPSIS
fd
dlgid
Dialogue ID that is stipulated for the last outgoing message.
prio
The prio argument is constructed by bitwise OR-ing values from the
following list:
L_SIO_Priority_0
L_SIO_Priority_1
L_SIO_Priority_2
L_SIO_Priority_3
This argument must be called before the tcm_snd() function sends an
outgoing message for that dialogue at a user-specified priority level.
Important: By default, the outgoing message priority for each new dialogue is set to a value
of L_SIO_Priority_0 at the time of the corresponding tcm_getdlgid() function call.
Therefore, the tcm_set_priority() function is used only if the TC application needs to send
messages at a different priority level.
Page 10 - 33
1-1600-1003-01
TCAP API Library
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO tcmd, tcm_snd(), tcm_rcv(), tcm_get_msg_priority(), tcm_get_priority(),

and tcm_getdlgid().
10.2.24 tcm_snd()
DESCRIPTION
tcm_snd()
Assembles and sends a TCAP message that has been constructed
by a TC application. Used for non-adopted dialogues only.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_snd(int fd, tcmdlg_t * dlg , int err);
fd
Identifies the service end point through which the message should be
transmitted.
dlg
Points to the tcmdlg_t data structure whose contents should be
populated, per ANSI or ITU recommendations, by the application prior
to invoking this function (tcm_snd()). With this call, the dlgid field of the
structure is the relevant transaction identification information and must
be filled properly with the dialogue identification. The full transaction id
information is not used and tr_id field is ignored.
Important: Applications that use the tcm_putcomp() and/or tcm_putdlgp() function calls
prior to invoking the tcm_snd() function, should set accordingly the "component present"
and/or "dialogue portion present" fields within the tcmdlg_t data structure.
err
Enables TC applications to originate incorrect TCAP messages, and its

use should be restricted to testing/development environments.Under
normal circumstances, this argument should always be initialized to 0.
The following dialogue identifiers are supported:
Page 10 - 34
1-1600-1003-01
TCAP API Library

L_TC_C_BEGIN - Begin Dialogue (CCITT)
L_TC_C_END - End Dialogue (CCITT)
L_TC_C_CONTINUE - Continue Dialogue (CCITT)
L_TC_C_CONTINUE_CONFIRM - Continue to Confirm a New
Dialogue (CCITT)
When the SCCP transport protocol services are in use, messages injected
by a TC application using the tcm_snd() call will be handled according to
the "quality-of-service" parameter setting within the dialogue as follows:
L_TC_SCCP_CLTS_NS_NR - Deliver message injected using

connectionless SCCP transport services. There is no need to preserve
message sequencing. In the case of an error, message need not be
returned.
L_TC_SCCP_CLTS_NS_RE - Deliver message injected using
message sequencing. In the case of an error, message should be
returned.
L_TC_SCCP_CLTS_S_NR_NL - Deliver message injected using
connectionless SCCP transport services. Message sequencing needs
to be preserved. Do not load-share messages for different dialogues
across available signalling links. In the case of an error, message need
not be returned.
L_TC_SCCP_CLTS_S_RE_NL - Deliver message injected using
to be preserved. Do not load-share message for different dialogues
across available signaling links. In the case of an error, message
should be returned.
L_TC_SCCP_CLTS_S_NR_LS - Deliver message injected using
to be preserved. Messages for different dialogues should be
loadshared across signalling links available. In the case of an error,
message need not be returned.
L_TC_SCCP_CLTS_S_RE_LS - Deliver message injected using
Page 10 - 35
1-1600-1003-01
TCAP API Library

message should be returned.
RETURN VALUES
0
-1
On success.
ERRORS
<EUSRVC>::Undefined SCCP service type.
<EUDT2LRG>::Message size exceeds the maximum permissible TCAP message
size.
<ENODLGPOR>::Optional dialogue portion is not included within the
message although the "dialogue portion present" indicator has
been set.
SEE ALSO
tcm_putcomp(), tcm_putdlgp(), tcm_rcv(),tcm_putcomp_n(), tcm_putdlgp_n(),
tcm_rcv_n(), tcm_snd_n
Page 10 - 36
1-1600-1003-01
10.3
TCAP Transaction Recovery Functions

To be able to benefit from transaction recovery features of the TCAP layer, a different set of
functions have to be used for sending/receiving messages as well as retrieving and storing
component and dialogue information. These functions use the full transaction identifier
rather than the local dialogue identifier (which is a portion of the transaction identifier) and
mostly have the suffix _n attached to the end of their names. The portions of the TCAP
library which are not used for message, dialogue and component send/receive purposes can
be used together with TCAP Transaction Recovery Functions (tcm_getopa, tcm_notify,
etc.). From this point on, the term "TCAP Transaction Recovery Functions" will be used for
functions which can be used to retrieve/send message, dialogue or component information
about dialogues which are adopted from a failing instance as well as for dialogues which are
originated or initially terminated by the calling application instance (which "belong" to the
calling instance).
All the recovery function are a part of the TCAP library and they can be linked to the user
applications as described in the previous chapter.
10.3.1 tcm_getcomp_n()
tcm_getcomp_n()Retrieves an individual component contained in a received TCAP
message. Used for both adopted and non-adopted dialogues. Retrieves an individual
component contained in a received TCAP message. The message was previously received
and initialized with the spm_rcv() and tcm_rcv_n() function calls. Before calling this
function, it should be determined that components are present. For example, the component
present field of the tcmdlg_t data structure will be set on return from the tcm_rcv_n() call if
a component is present.
More than one component can be in the message. Each one is retrieved by a separate call of
this function. The components will be retrieved in the order that they were placed by the
remote end. To retrieve all the components, this call can be issued repetitively until it fails
with the ENOCMP error.
This function performs various sanity checks on the components before submitting them to
the TC application. This enables abnormal situations to be detected and acted upon by the
system. When an abnormal situation is detected, both local and remote ends will be
informed automatically through reject components generated by the system. The system
will discard the erroneous component and return a reject component instead of the
component from the message. The system will put the reject component for the remote end
in the next message that is generated and sent to the remote end by the calling application. If
the invoke ID can be retrieved by the system successfully, the operation to which the
component is related will also be cancelled.
Important: For ITU White Book, ITU 97, ETSI 97, and ANSI 96 applications, if the
dialogue portion present field of tcmdlg_t indicates the dialogue portion is
present, the tcm_getdlgp_n() function MUST be called first.
Page 10 - 37
1-1600-1003-01
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getcomp_n(int fd , ipcmsg_t * msg , tcmcomp_t * comp );
fd
received.
msg
Points to the TCAP message that was retrieved by spm_rcv(), initialized
by tcm_rcv_n(), and was determined to have one or more components.
comp
retrieved component. The last component field of this structure will be set
to 0 if more components are present. The following component type
identifiers are supported: With this call, the dlgid field of the structure is
filled with the dialogue id of the transaction and the tr_id is also
initialized with the full transaction id.
L_TC_A_INVOKE_L: Invoke Last [ANSI].
L_TC_A_INVOKE_NL: Invoke Not Last [ANSI].
L_TC_A_RESULT_L: Return Result Last [ANSI].
L_TC_A_RESULT_NL: Return Result Not Last [ANSI].
L_TC_A_ERROR: Return Error [ANSI].
L_TC_A_REJECT: Reject [ANSI].
L_TC_A_LOC_CANCEL: Local Cancel [ANSI].
L_TC_C_INVOKE: Invoke [CCITT].
L_TC_C_RESULT_L: Return Result Last [CCITT].
L_TC_C_RESULT_NL: Return Result Not Last [CCITT].
L_TC_C_ERROR: Return Error [CCITT].
L_TC_C_REJECT: Reject [CCITT].
L_TC_C_LOC_CANCEL: Local Cancel [CCITT].
RETURN VALUES
0
-1
On success.
ERRORS
Page 10 - 38
1-1600-1003-01
SEE ALSO
tcm_getcomp()
10.3.2 tcm_gettrid()
DESCRIPTION
tcm_gettrid()Obtains a new full transaction identifier from the system, so that the
requesting application can start a new dialogue. All the applications which require
transaction recovery functionality have to work with full transaction identifiers (as opposed
to dialogue identifiers) and store that information in the tr_id field of the appropriate
structure (tc_a_dialogue_t, tc_c_dialogue_t, tc_a_comp_t, tc_c_comp_t, tc_a_dlg_por_t,
tc_c_dlg_por_t) before calling a transaction recovery function.
When an acquired transaction identifier is no longer used, it should be released using the
tcm_rlstrid() function call.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_gettrid(int fd);
fd
Identifies the service endpoint through which the dialogue will occur. It is the file
descriptor that was returned by the tcm_open() call when the service endpoint was
established.
RETURN VALUES
Transaction ID On success.
-1
ERRORS
<ENDR>::All dialogue identifiers are currently in use. Distributed7
allows each TC user process to open up to L_TC_NUMBER_OF_DLGS dialogs
concurrently.
SEE ALSO
tcm_getdlgid()
Page 10 - 39
1-1600-1003-01
10.3.3 tcm_getdlgp_n()
DESCRIPTION
tcm_getdlgp_n()Retrieves the contents of the dialogue portion contained in a received
TCAP message. Used for both adopted and non-adopted dialogues.
The message was previously received and initialized with the spm_rcv() and tcm_rcv_n()
function calls. Before calling this function, it should be determined that the dialogue portion
is present. For example, the dialogue portion present field of the tcmdlg_t data structure
will be set on return from the tcm_rcv_n() call if the dialogue portion is present. This
function must be called before retrieving any components with tcm_getcomp_n().
Important: This function is only used by TC applications that follow the ITU White Book
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_getdlgp_n(int fd , ipcmsg_t * msg , tcmdlgp_t * dlgp );
fd
Identifies the service endpoint through which the TCAP message was received.
msg
Points to the TCAP message that was retrieved and has a dialogue portion.
dlgp
Points to a user data structure into which the function should put the retrieved
dialogue portion. With this call, the dlgid field of the structure is filled with the
dialogue id of the transaction and the tr_id is also initialized with the full
transaction id.. The following dialogue type identifiers are supported:
L_TC_C_DIALOGUE_REQ: Dialogue Request [CCITT].
L_TC_C_DIALOGUE_RESP: Dialogue Response [CCITT].
L_TC_C_DIALOGUE_ABORT: Dialogue Abort [CCITT].
L_TC_C_DIALOGUE_UNI: Unidirectional Dialogue [CCITT].

RETURN VALUES
0
-1
On success.
ERRORS
Page 10 - 40
1-1600-1003-01
SEE ALSO
tcm_rcv(), tcm_putcomp(), tcm_putdlgp()
10.3.4 tcm_open_n()
DESCRIPTION
tcm_open_n()Registers a TC application process with the Distributed7 environment by
establishing a connection at the TCAP multiplexer and allocating the local library resources
necessary for the application to communicate with other applications using the TCAP
protocol. This (or the deprecated tcm_open) should be the very first function call invoked
by all TC application programs executing under Distributed7. The tcmd process must be
running to be able to call this or any other TCAP functions. This function returns a file
descriptor that will be used with other TCAP function calls to identify the connection. A TC
application can establish multiple connections with the system by issuing multiple
tcm_open_n() calls. Thus, it is possible for a given application to communicate
concurrently with multiple entities through separate connections and possibly using
different transport service providers and/or TCAP protocol variants. Since tcm_setpolicy
api is deprecated, this function is also the only way of setting the transaction recovery
policy.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_open_n(tcmbuf_t * buf , tcmopts_t * opts , tcmaddr_t * addr ,tcmaddr_t *
rmtaddr , tcm_policy_t *policy);
buf
typedef struct {
int bufcnt;
int bufsize;
} tcmbuf_t;
allocated by the TCAP library on behalf of the calling process. The
actual buffer size is four times the value specified. The size is based on
the maximum size of a component the process will submit in a
transaction.
Internal buffers are used by the TCAP API library to store TCAP
components and/or dialogue-related information temporarily (before
they are submitted to the TCAP multiplexer for transmission). The actual
Page 10 - 41
1-1600-1003-01
buffer size allocated by tcm_open_n() is four times the value specified

via the bufsize argument.
IImportant:The calling process is responsible to specify the correct number and size of
subsequent tcm_putcomp_n() function calls with an errno value of ENOBUF.
opts
Points to the tcmopts_t user data structure. The structure is as follows:

typedef struct {
word_t trproto; /* underlying transport protocol */
#define L_TC_TPRO_UNDEFINED 0x0000 /* protocol not specified */
#define L_TC_TPRO_SCCP 0x0100 /* use SCCP transport services
*/
#define L_TC_TPRO_TCPIP 0x0200 /* use TCP/IP transport
services */
#define L_TC_TPRO_SCCP_RMT 0x0400 /* use remote SCCP transport
services */
#define L_TC_OPT_TRPROTO_MASK 0xff00 /* protocol */
word_t version; /* TCAP protocol version */
/* base protocol versions */
#define L_TC_VERS_UNDEFINED 0x0000 /* version not specified */
#define L_TC_VERS_ITU_WB 0x0004 /* CCITT/ITU white book */
#define L_TC_VERS_ITU_BB 0x0005 /* CCITT/ITU blue book */
#define L_TC_VERS_ITU_97 0x0006 /* CCITT/ITU 97 */
#define L_TC_VERS_ETSI_97 0x0007 /* ETSI 97 */
#define L_TC_VERS_ITU_ATTL 0x0010 /* CCITT/ITU AT&T variant 1
*/
#define L_TC_VERS_ITU_ATT2 0x0020 /* CCITT/ITU AT&T variant 2
*/
#define L_TC_OPT_VERSION_MASK 0x00ff /* base + customer version
*/
#define L_TC_OPT_VERSION_BASE_MASK 0x000f /* base version */
#define L_TC_OPT_VERSION_SPEC_MASK 0x00f0 /* customer version */
dword_t maxdlgs; /* max # dialogue identifiers */
dword_t rmtuser; /* reserved for tcm_rmtopen() use */
} tcmopts_t;
where trproto specifies the transport service provider, i.e., SCCP or

TCP/IP, to utilize when exchanging TCAP messages between two TC
applications.
variants of the TCAP protocol that the applications are interested in
Page 10 - 42
1-1600-1003-01
using. The version must include a base protocol version, i.e.,

L_TC_VERS_ITU_WB, and can optionally include a customer specific
protocol version (e.g., L_TC_VERS_ITU_ATTL).
Examples:
/* set version to ITU White Book */
version = L_TC_VERS_ITU_WB;
/* set version to AT&T variant of ITU White Book */
version = L_TC_VERS_ITU_WB | L_TC_VERS_ITU_ATTL;
addr
where maxdlgs specifies the maximum number of dialogue identifiers

that can be concurrently acquired by TC user process. Distributed7
allows each TC user process to acquire up to a maximum of
typedef struct {
union {
ss7obj_t ss7obj;
tcpobj_t tcpobj;
...
} un;
word_t adrtyp;
} ipcaddr_t;

Distributed7 environment as a TC application are L_SS7OBJ and
L_TCPOBJ. The L_SS7OBJ address type is reserved for TC applications
which plan to utilize the services of the SCCP protocol when exchanging
TCAP messages, whereas the L_TCPOBJ address type is reserved for TC
applications interested in using transport services of the TCP/IP protocol.
Note that based on the address information specified via the adrtyp
argument, the calling process is also expected to provide the detailed
address information associated with itself by populating the data
structure of type ss7obj_t or tcpobj_t. These data structures contain the
following fields:
typedef struct {
} ss7obj_t;
typedef struct {
word_t port; /* port identifier */
Page 10 - 43
1-1600-1003-01
} tcpobj_t;
structure is meaningful upon successful return from the tcm_open_n()
upon successful return from the tcm_open_n() function call.
number to a particular TC application. This information is used to
associate incoming TCAP messages, i.e., messages generated by the
remote end, with a particular application. The permissible values of the
port argument lie between [0, L_TC_MAX_PORT_ID - 1]. If and when a
TC application features multiple instances, all such instances should
register with the system using the same port value.
rmtaddr
policy
This argument points to a user data structure that identifies the remote
entity that the calling process intends to exchange TCAP messages with.
At this time, information contained in this field is meaningful only when
the underlying transport service protocol is designated to be TCP/IP, i.e.,
as it informs the system about the details of the destination address for
TCAP messages to be generated by the calling process. If and when the
calling process designates SCCP as the transport service provider
(instead of TCP/IP), information specified via the rmtaddr argument is
not used by the system; therefore, rmtaddr may be set to NULL in such
cases.
Specifies the desired recovery policy (and necessary recovery
parameters) in the case of a fatal failure, i.e., when the TC application that
is in charge terminates its execution prematurely.
typedef struct {
int policy;
int maxmsgsize;
for ADOPT */
} tcmpolicy_t;
/* max begin message size can be stored
The policy field defines the requested recovery policy whereas the
maxmsgsize field defines the maximum BEGIN/QUERY message size
for a transaction when the ADOPT recovery policy is in effect.
The permissible values of policy field are as follows:
Page 10 - 44
1-1600-1003-01
L_TC_POLICY_PURGE - Terminate all active transactions owned

by the TC application and release transaction ID's associated. This is
the default recovery policy enforced by the system for any newly
starting TC application.
L_TC_POLICY_ABORT - Terminate all active transactions owned
by the TC application and notify the remote end via abort indicator
messages for all transactions initiated by the remote end.
L_TC_POLICY_ADOPT - Adopt all active transactions owned by
the TC application and re-distribute their ownership among the
surviving instances of the application.
Important:When TCAP over SCCP is in use, following registration with the Distributed7
environment, a TC application is expected to invoke the sccp_StateReq() function call to
indicate to the SCCP layer that the local SSN associated is now in service. A failure to do so
will cause the SSN status to remain prohibited which in return will result in the SCCP layer
not to deliver any incoming messages to the TC application. Similarly, prior to termination
of all instances of a TC application, sccp_StateReq() function call needs to be invoked one
more time to indicate to the SCCP layer that the SSN associated is now going out-ofservice;
therefore, the local SSN status should be marked as prohibited.
RETURN VALUES
file descriptor
-1
On success. (non-negative integer)

The file descriptor returned by tcm_open_n() should be used by the
calling process to refer to the particular connection established when
performing TCAP related activities (e.g. assembling/disassembling/
exchanging TCAP messages) via other functions comprising the TCAP
library.
ERRORS
given SCCP subsystem or TCP/IP port identifier is exceeded. Distributed7
environment allows up to 63 instances of a particular TC application to
coexist at a given time.
the tcmd(1E) daemon.
communication failure with the tcmd(1E) daemon process.
data.
Page 10 - 45
1-1600-1003-01

<ESSN>::Invalid subsystem number is specified
exceeded.
Note: For a list of additional errno values, refer to the spm_open() and spm_bind()
function calls.
NOTES
Successful operation of the tcm_open_n() function call as well as all other function calls
comprising the TCAP API library requires the tcmd daemon process to be up and running.
SEE ALSO
tcmd, spm_open(), spm_bind(), tcm_close(), tcm_gettrid(), tcm_getcomp_n(),
tcm_ldshare(), tcm_putcomp_n(), tcm_rcv_n(), tcm_snd_n(), tcm_rlstrid()
10.3.5 tcm_putcomp_n()
DESCRIPTION
tcm_putcomp_n() Assembles and submits one or more components (next to each other) to
the TCAP layer for inclusion within a dialogue (transaction). Used for both adopted and
non-adopted dialogues. After all appropriate components associated with a dialogue are
assembled and submitted, the TC application should invoke the tcm_snd_n() function to
transmit the dialogue.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_putcomp_n(int fd , tcmcomp_t * comp );
fd
Identifies the service endpoint through which the dialogue will be transmitted.
comp
Points to the tcmcomp_t data structure which contains the component. With this
call, the tr_id field of the structure is the relevant transaction identification
information and must be filled properly with the transaction identifier. The
dialogue id information is not used and dlgid field is ignored.
All relevant fields must be populated, as described in the Distributed7 Application
Development Manual.
RETURN VALUES
# of bytes added to dialogueOn success.
-1
Page 10 - 46
1-1600-1003-01
ERRORS
SEE ALSO
tcm_snd()
Page 10 - 47
1-1600-1003-01
10.3.6 tcm_putdlgp_n()
DESCRIPITON
tcm_putdlgp_n()Assembles and submits the optional dialogue portion to the TCAP layer to
be put in a dialogue (transaction). Used for both adopted and non-adopted dialogues. When
including the dialogue portion, the dialogue portion present field must be set in the
tcmdlg_t data structure of the tcm_snd_n() call so that the receiver of the message can
retrieve its contents.
Note: This function is only used by TC applications which follow the ITU White Book
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_putdlgp_n(int fd , tcmdlgp_t * dlgp );
fd
Identifies the service endpoint through which the dialogue will be transmitted.
dlgp
Points to the tcmdlgp_t data structure which contains the dialogue portion. With
this call, the tr_id field of the structure is the relevant transaction identification
information and must be filled properly with the transaction identifier. The
dialogue id information is not used and dlgid field is ignored.
All relevant fields must be populated, as described in the Distributed7 Application
Development Manual.
RETURN VALUES
# of bytes added to dialogueOn success.
-1
ERRORS
Page 10 - 48
1-1600-1003-01

SEE ALSO
tcm_getcomp(), tcm_getdlgp(), tcm_snd()
10.3.7 tcm_rcv_n()
DESCRIPTION
tcm_rcv_n()
Unbundles the transaction portion of a TCAP message that was retrieved
using the spm_rcv() call. Used for both adopted and non-adopted dialogues. TC
applications should call this function only when the type of the IPC message received by the
spm_rcv() call is equal to N_UNITDATA_indication (for TCAP over SCCP) or
L_TC_DLG_MSG (for TCAP over TCP/IP), or L_TC_ADOPTED_DLG_MSG (for
either transportation protocol), as these are the only types of TCAP transaction-layer
messages.
Each time the function is called, the component pointers associated with that TCAP
message are reset. After this call, either tcm_getcomp_n() or tcm_getdlgp_n() can be
called next, depending on the TCAP information retrieved by this call, to retrieve the
contents of the individual components and/or optional dialogue portion contained within the
message. The decision to invoke either function should be made on the basis of "component
present" and "dialogue portion present" indicators contained within the dialogue retrieved
by the tcm_rcv_n() function.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_rcv_n(int fd , ipcmsg_t * msg , tcmdlg_t * dlg );
fd
Identifies the service endpoint through which the message was received.
msg
Points to the message data structure whose contents have been retrieved using the
spm_rcv() call.
dlg
Points to the tcmdlg_t data structure where the contents of the transaction portion
should be placed. With this call, the dlgid field of the structure is filled with the
dialogue id of the transaction and the tr_id is also initialized with the full
transaction id..
In case the remote node initiates a dialogue, i.e., by sending a Query With
Permission [ANSI] or Begin [CCITT] message, the TCAP layer automatically
Page 10 - 49
1-1600-1003-01
generates a new dialogue identifier and returns this identifier to the user within the
tcmdlg_t data structure. For unidirectional dialogue types, a NULL dialogue
identifier is returned.
This function supports the following dialogue identifiers:
L_TC_C_BEGIN - Begin Conversation (CCITT)
L_TC_C_END - End Conversation (CCITT)
L_TC_C_ CONTINUE - Continue Conversation (CCITT)
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcm_snd(), spm_rcv()
Page 10 - 50
1-1600-1003-01
10.3.8 tcm_rlstrid()
DESCRIPTION
tcm_rlstrid() Releases and returns a full transaction identifier (acquired through a
tcm_gettrid call or through and adopted transaction) to the pool of available dialogue IDs
when a dialogue cannot be completed successfully, for example due to a timer expiration or
a delivery failure. Normally, this call is not needed because the system automatically
releases the dialogue ID when a dialogue successfully completes (with an end or an abort).
Any components associated with the dialogue ID being released will be discarded by the
system.
All the applications which require transaction recovery functionality have to work with full
transaction identifiers (as opposed to dialogue identifiers) and store that information in the
tr_id field of the appropriate structure (tc_a_dialogue_t, tc_c_dialogue_t, tc_a_comp_t,
tc_c_comp_t, tc_a_dlg_por_t, tc_c_dlg_por_t) before calling a transaction recovery
function.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_rlstr(int fd, int dlgid );
fd
Identifies the service endpoint through which the dialogue identifier was acquired
using the tcm_gettrid() call or through which the the dialogue initiation message was
received (unitdata or adopted dialogue).
dlgid
Indicates the dialogue ID to be released.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcm_getdlgid() and tcm_getdlgid().
Page 10 - 51
1-1600-1003-01
10.3.9 tcm_snd_n()
DESCRIPTION
tcm_snd_n() Assembles and sends a TCAP message that has been constructed by a TC
application. Used for both adopted and non-adopted dialogues.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_snd_n(int fd, tcmdlg_t * dlg , int err );
fd
Identifies the service end point through which the message should be
transmitted.
dlg
Points to the tcmdlg_t data structure whose contents should be
populated, per ANSI or ITU recommendations, by the application prior
to invoking this function (tcm_snd_n()).With this call, the tr_id field of
the structure is the relevant transaction identification information and
must be filled properly with the transaction identifier. The dialogue id
information is not used and dlgid field is ignored.
IImportant:
Applications that use the tcm_putcomp_n() and/or tcm_putdlgp_n()
function calls prior to invoking the tcm_snd_n() function, should set accordingly the
"component present" and/or "dialogue portion present" fields within the tcmdlg_t data
structure.
err
Page 10 - 52
Enables TC applications to originate incorrect TCAP messages, and its

use should be restricted to testing/development environments.Under
normal circumstances, this argument should always be initialized to 0.
The following dialogue identifiers are supported:
L_TC_C_BEGIN - Begin Dialogue (CCITT)
L_TC_C_END - End Dialogue (CCITT)
L_TC_C_CONTINUE - Continue Dialogue (CCITT)
L_TC_C_CONTINUE_CONFIRM - Continue to Confirm a New
1-1600-1003-01
Dialogue (CCITT)
When the SCCP transport protocol services are in use, messages injected
by a TC application using the tcm_snd() call will be handled according to
the "quality-of-service" parameter setting within the dialogue as follows:
L_TC_SCCP_CLTS_NS_NR - Deliver message injected using

message sequencing. In the case of an error, message need not be
returned.
L_TC_SCCP_CLTS_NS_RE - Deliver message injected using
message sequencing. In the case of an error, message should be
returned.
L_TC_SCCP_CLTS_S_NR_NL - Deliver message injected using
to be preserved. Do not load-share messages for different dialogues
across available signalling links. In the case of an error, message need
not be returned.
L_TC_SCCP_CLTS_S_RE_NL - Deliver message injected using
to be preserved. Do not load-share message for different dialogues
across available signaling links. In the case of an error, message
should be returned.
L_TC_SCCP_CLTS_S_NR_LS - Deliver message injected using
message need not be returned.
L_TC_SCCP_CLTS_S_RE_LS - Deliver message injected using
message should be returned.
RETURN VALUES
0
-1
On success.
ERRORS
Page 10 - 53
1-1600-1003-01

<EUSRVC>::Undefined SCCP service type.
<EUDT2LRG>::Message size exceeds the maximum permissible TCAP message
size.
<ENODLGPOR>::Optional dialogue portion is not included within the
message although the "dialogue portion present" indicator has been set.
SEE ALSO
tcm_putcomp_n(), tcm_putdlgp_n(), tcm_rcv_n()
10.3.10 tcm_set_priority_n()
DESCRIPTION
tcm_set_priority_n()Allows a TC application to set the priority for all outgoing messages
associated with a dialogue specified by a full transaction identifier. This function is used for
non-adopted dialogues only when the adopt recovery policy is applied, for adopted
dialogues, system will assign a priority for them automatically. tcm_setpriority_n can be
run multiple times during the life-cycle of a dialogue to send different messages at different
priority levels.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_get_msg_priority_n(int fd,int tr_id,byte_t* prio);
fd
tr_id
Transaction ID that is stipulated for the last outgoing message.
prio
The prio argument is constructed by bitwise OR-ing values from the
following list:
L_SIO_Priority_0
L_SIO_Priority_1
L_SIO_Priority_2
L_SIO_Priority_3
This argument must be called before the tcm_snd_n() function sends an
outgoing message for that dialogue at a user-specified priority level.
Important: By default, the outgoing message priority for each new dialogue is set to a value
of L_SIO_Priority_0 at the time of the corresponding tcm_gettrid() function call. Therefore,
the tcm_set_priority_n() function is used only if the TC application needs to send messages
at a different priority level.
Page 10 - 54
1-1600-1003-01
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcmd, tcm_snd_n(), tcm_rcv_n(), tcm_get_msg_priority_n(), tcm_get_priority_n(),and
tcm_gettrid().
10.3.11 tcm_get_priority_n()
DESCRIPTION
tcm_get_priority_n()Retrieves the last priority level associated with outgoing messages for
the dialogue specified by a full transaction identifier.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcm_get_msg_priority_n(int fd,int tr_id,byte_t* prio);
fd
tr_id
Transaction ID that is stipulated for the last outgoing message.
prio
level is copied.
RETURN VALUES
0
-1
On success.
ERRORS
Page 10 - 55
1-1600-1003-01
SEE ALSO
tcmd, tcm_snd_n(), tcm_rcv_n(), tcm_get_msg_priority_n(), and tcm_set_priority_n().
10.3.12 tcm_get_msg_priority_n()
DESCRIPTION
tcm_get_msg_priority_n()Allows a TC application to retrieve the priority level of the last
incoming message associated with the dialogue specified by a full transaction identifier.
MT-LEVEL
MT-Safe
SYNOPSIS
fd
Identifies the service endpoint through which the message is received.
tr_id
Transaction ID that is stipulated for the last incoming message.
prio
level is copied. The priority level retrieved is that of the message that has
been processed through the last tcm_rcv_n() call by that application.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO
tcmd, tcm_snd_n(), tcm_rcv_n(), tcm_get_priority_n(), and tcm_set_priority_n().
Page 10 - 56
1-1600-1003-01
10.4
JAIN TCAP API Library

JAIN TCAP API is implemented based on JAIN APIs for the Integrated Network, JAIN
Transaction and Capabilities Part (TCAP) Specification Version 1.1. The following
sections describe the major interfaces defined by JAIN APIs.
10.4.1 SS7 Factory

The JAIN SS7 Factory is a singleton class by which JAIN SS7 applications can obtain a
proprietary (peer: a particular platform-specific implementation of a Java interface or API)
JAIN SS7 Object.
A peer JAIN SS7 Object can be obtained from the JAIN SS7 Factory by:
instantiating a new Peer JAIN SS7 Object using the createSS7Object() method
selecting from the list of JAIN SS7 Objects returned by the getJainObjectList() method
The JAIN SS7 Factory utilizes a naming convention defined for each JAIN SS7 API to
identify the location of proprietary JAIN SS7 Objects. Under this convention the lowerlevel package structure and classname of a Peer JAIN SS7 Object is mandated by a
convention defined within the JAIN SS7 API from which the Object originates. For
example, within the JAIN TCAP API, the lower-level package structure and classname of a
proprietary implementation of jain.protocol.ss7.tcap.JainTcapStack interface must be:
jain.protocol.ss7.tcap.JainTcapStackImpl
Under the JAIN naming convention, the upper-level package structure (pathname) can be
used to differentiate between proprietary implementations from different SS7 Vendors. The
pathname used by each SS7 Vendor must be the domain name assigned to the Vendor in
reverse order. For NewNet Communication Technologies this name is 'com.NewNet'. It
follows that a proprietary implementation of a JAIN SS7 Object can be located at:
'pathname'.'lower-level package structure and classname'
Where:
pathname = 'com.NewNet'
lower-level package structure and classname = mandated naming convention for the JAIN
SS7 Object in question
For example, jain.protocol.ss7.tcap.JainTcapStackImpl is the mandated naming convention
for jain.protocol.ss7.tcap.JainTcapStack
The resulting Peer JAIN SS7 Object would be located at:
com.NewNet.jain.protocol.ss7.tcap.JainTcapStackImp
Because the space of domain names is managed, this scheme ensures that collisions
between two different vendor's implementations will not happen. The pathname may be set
using the setPathName() method. This allows a JAIN application to switch between
different Vendor implementations, as well as providing the capability to use the default or
current pathname.
Page 10 - 57
1-1600-1003-01
The JAIN SS7 Factory is a Singleton class. This means that there will only be one instance
of the class with a global point of access to it. The single instance of the JAIN SS7 Factory
can be obtained using the getInstance() method. In this way, the JAIN SS7 Factory acts a
single point for obtaining JAIN SS7 Objects.
10.4.2 JAIN Stack Interface

This interface defines methods for representing a proprietary JAIN TCAP protocol stack
implementation. This interface and the Provider interface is provided by NewNet
Communication Technologies. NewNet protocol stack creates an object that implements
this interface to control the creation/deletion of proprietary Provider and the attaching/
detaching of that Provider to this Stack implementation. Application creates a StackImpl
object by calling JainSS7Factory.createJainSS7Object method. A Stack represents a
single point code.
10.4.3 JAIN Provider Interface

This interface represents the JAIN layer which interfaces directly with a proprietary
(Distributed7) implementation of the SS7 stack. Any object that interfaces between a JAIN
application and an SS7 stack must implement this interface. This interface defines the
methods that will be used to send and receive Events by any registered User application
implementing the Jain Listener interface. An Event is java event version of protocol
messages and other interface related information exchanged between the Provider and the
Listener.
Henceforth, the object implementing the Jain Listener and Jain Provider interface will be
referred to as Jain Listener object and Jain Provider object. Jain Listener object registers
with a Jain Provider object for receiving Events. At the time of registration, the Listener
object supplies a User Address to the Provider object.
A Jain Provider object encapsulates the received protocol messages from Distributed7
stack into java events and passes this information to the Listener. One or more Provider
objects can exist on a single SS7 specific layer (Figure 10-2).
Page 10 - 58
1-1600-1003-01
StackStack Stack
Provider
Listener
Provider
Listener
Figure 10-2: Stack-Provider-Listener Association

The implementation of the JAIN TCAP Provider interface provides the ability to
communicate with the TCAP layer of the Distributed7 stack. The Provider is responsible
for keeping and maintaining a list of registered JAIN TCAP Listeners. There can be
multiple providers and one listener can register to multiple providers by using different
user addresses.
JNI (Java Native Interface) is used to make native calls from Java side and calling Java
methods from native side.
A JAIN TCAP User-Address consists of a signaling point code, along with a subsystem
number or a global title information element. A JainTcapListener object can add more
User-Addresses by invoking the addJainTcapListener method, and can remove UserAddresses by invoking the removeJainTcapListener method (Figure 10-3). The
ListenerNotRegisteredException is thrown if the removeJainTcapListener method is
invoked on a specific JAIN TCAP Listener, which is not registered with that JAIN TCAP
Provider.
Page 10 - 59
1-1600-1003-01
User Address
(1-1-1, 100)
Listener
User Address
(2-2-2, 200)
Provider 1
Provider 2
TCAP Layer
TCAP Layer
Distributed7
Distributed7
Figure 10-3: Multiple Provider Architecture

A JainTcapListener calls the sendComponentReqEvent and the sendDialogueReqEvent
methods on the JainTcapProvider to send TCAP Components and Dialogue Primitives to
the TCAP SS7 Layer. The API implementation supports the exchange of TCAP messages
and TCAP specific timeout indications between the JAIN TCAP Provider and the JAIN
TCAP Listener. Each message is encapsulated individually in an event. When a received
TCAP message arrives at the Distributed7 stack, the JAIN TCAP Provider forwards the
TCAP message as a JAIN TCAP Component and Dialogue Event to the Listener that has
registered for that User-Address. Events that are not associated with a User-Address are
discarded by the JAIN TCAP Provider. Further information on JAIN TCAP API can be
found at http://www.jcp.org/jsr/detail/11.jsp.
Sample JainTcapListener implementation is located under the $EBSHOME/access/sample/
jain/tcap directory. Distributed7 JAIN TCAP API requires Java version 1.4 or higher.
JAIN mandates the naming convention for the lower level package structure and class
name of the proprietary implementation. Package structures for TCAP are as follows:
jain
jain.protocol
jain.protocol.ss7
jain.protocol.ss7.tcap
jain.protocol.ss7.tcap.component
jain.protocol.ss7.tcap.dialogue
com.NewNet.jain.protocol.ss7.tcap
Packages starting with com.NewNet are for the proprietary implementation. The
JainTcapListener application requires the libJainTcap.so library, which is located underthe
$EBSHOME/access/lib directory. To make use of this library the LD_LIBRARY_PATH
environment variable needs to be set on Solaris systems. The jar file for generic classes is
named as JainTcapGeneric.jar. The NewNet Communication Technologies proprietary
implementation is named as JainTcapNewNet.jar. Both of these jar files are located under
the $EBSHOME/access/lib directory. The CLASSPATH environment variable should be
set to include the directory path that contains the jar files.
Page 10 - 60
1-1600-1003-01
Page 10 - 61
1-1600-1003-01
Page 10 - 62
1-1600-1003-01
Chapter 11:
11.1
Raw TCAP API Library
Chapter Overview
This chapter provides a listing of the raw TCAP library Application Program Interface
(API). Each API library call is listed with its name, synopsis, description, and return
values.
11.2

The raw TCAP API library allows application programs to take advantage of the
registration, message distribution, and load-sharing capabilities that are available as part
of the Distributed7 TCAP layer without getting involved in any of the transaction and/or
component handling capabilities associated with the TCAP layer. Raw TCAP users are
registered with the Distributed7 TCAP layer in a transparent manner with the
expectation that TCAP protocol related functionality [if any] will be provided directly by
them. Raw TCAP users are not required to be TCAP protocol users. They can be SCCP
layer applications.
The raw TCAP API library consists of calls that allow applications to establish a
connection to the Distributed7 TCAP layer and register as raw users, state whether they
are interested in load-sharing incoming message traffic, choose between different loadsharing algorithms, and remove an endpoint established earlier and de-register
themselves.
To use the raw TCAP function calls, the following header files must be included at the
beginning of the application in the given order:
#include <api.h>
#include <tcap_raw.h>
In addition the application must be compiled properly and the tcmd daemon process must
be active.
The raw TCAP library (libtcapraw.a) should be accessed using the $EBSHOME/access/lib
Page 11 - 1
1-1600-1003-01
path and linked with a user application as shown below:

cc -I $EBSHOME/access/include
-L $EBSHOME/access/lib -ltcapraw -lsccp -lmtp -lspm -linet -lnsl
A sample source code file [named tcr_apidemo.c] is provided to demonstrate the use of
the Distributed7 raw TCAP API library routines. This file should be compiled using the
Makefile in the $EBSHOME/access/sample/tcapraw directory.
After it is compiled, the executable will be located in the $EBSHOME/access/demo
directory.
On-line reference manuals for the raw TCAP API library calls are provided in the form of
manual pages so that the user can invoke the UNIX standard man(1) utility to review the
Important: Distributed7 1.2. Raw TCAP API is multi-thread (MT) Safe, and can be used
with multi-threaded application programs. When compiling multi-threaded applications, the
11.2.1 tcr_open()
NAME
tcr_open
Establishes a raw connection.
SYNOPSIS
int tcr_open(tcropts_t *opts, tcraddr_t *addr, tcraddr_t *rmtaddr);
MT-LEVEL
MT-Safe
DESCRIPTION
Registers a raw TCAP user with Distributed7 and establishes a connection at the TCAP
multiplexor that allocates the local library resources necessary for users to communicate
with other users.
Note: While raw TCAP users can take advantage of the registration, message distribution,
and load-sharing capabilities available as part of the D7 TCAP layer, they cannot exercise
any of the transaction and/or component handling related capabilities associated with the
TCAP layer. That is because raw TCAP users are registered with the TCAP layer in a
transparent manner with the expectation that TCAP protocol related functionality [if any]
will be provided directly by them. Also note that a raw TCAP user is not required to bea
TCAP protocol user. For example, it is perfectly feasible for an SCCP subsystem to
Page 11 - 2
1-1600-1003-01
declare itself as a raw TCAP user so that it can take advantage of the registration,
message distribution, and load-sharing capabilities provided by the D7 TCAP layer. As a
matter of fact, under Distributed7, an SCCP subsystem can instantiate multiple local
instances of itself only by declaring itself as a raw TCAP user and invoking the tcr_open()
call during registration with the Distributed7 platform.
opts
Points to a user data structure of type tcropts_t() as follows:

typedef struct {
word_t
trproto; /* transport provider */
word_t
notused; /* reserved for internal use */
} tcropts_t;
trproto
addr
Specifies the transport service provider (i.e., SCCP or TCP/IP) to utilize

when exchanging messages.
Points to a user data structure of type tcraddr_t as follows:
typedef struct {
union {
ss7obj_t ss7obj;
tcpobj_t tcpobj;
...
} un;
word_t
adrtyp;
} ipcaddr_t;
typedef ipcaddr_t tcraddr_t;
Note: The user data structure of type tcraddr_t is in essence equivalent to the ipcaddr_t
data type defined in the <api.h> header file.
adrtyp

Distributed7 environment as a raw TCAP user are L_SS7OBJ and
L_TCPOBJ. The L_SS7OBJ address type is reserved for raw TCAP
users which plan to utilize the services of the SCCP protocol when
exchanging messages whereas the L_TCPOBJ address type is reserved
for raw TCAP users interested in using transport services of the TCP/IP
protocol.
Note that based on the address information specified via the adrtyp
argument, the calling process is also expected to provide the detailed
address information associated with itself by populating a data structure
of type ss7obj_t or tcpobj_t. These data structures contain the following
fields:
typedef struct {
word_t
sp;
/* signalling point number */
word_t
up;
/* user part number */
word_t
ssn;
/* sub-system number */
Page 11 - 3
1-1600-1003-01

word_t
inst;
/* instance number */
} ss7obj_t;
typedef struct {
word_t
port;
/* port identifier */
word_t
inst;
/* instance number */
} tcpobj_t;
inst
port
rmtaddr
Page 11 - 4
field. The Distributed7 environment allows multiple instances of a raw
TCAP user associated with a particular SCCP subsystem or a particular
TCP/IP port identifier to coexist (i.e., in order to process messages
received by the raw TCAP user in a collaborative manner). At the time
registration, each such user will be assigned a unique number (i.e., the
instance number) to be able to differentiate it from other instances of the
same user. Thus, information in the inst field of either data structure is
meaningful upon successful return from the tcr_open() function call as it
contains the instance number assigned to the calling process. Raw TCAP
users interested in finding out the instance number assigned to them by
the system should check on the value of the inst field upon successful
return from the tcr_open() function call.
number to a particular raw TCAP user. This information is used to
associate incoming messages (i.e., messages generated by the remote
end) with a particular user. The permissible values of port argument lie
between [0, L_TCR_MAX_PORT_ID - 1]. If and when a raw TCAP user
Last but not the least, the rmtaddr argument points to a user data
structure that identifies the remote entity that the calling process intends
to exchange messages with. At this time, information contained in this
field is meaningful only when the underlying transport service protocol is
designated to be TCP/IP (i.e., as it informs the system about the details of
the destination address for messages to be generated by the calling
process). If and when the calling process designates SCCP as the
transport service provider (i.e., instead of TCP/IP), information specified
via the rmtaddr argument is not used by the system; therefore, rmtaddr
may be set to NULL in such cases.
The Distributed7 environment allows a given raw TCAP user to establish
multiple connections with the system by issuing multiple tcr_open()
calls. Thus, it is possible for a given user to communicate concurrently
with multiple entities through separate connections [possibly using
different transport service providers].
1-1600-1003-01
Note: When SCCP transport services are in use, following registration with the
Distributed7 environment, a raw TCAP user is expected to invoke the sccp_StateReq() function call to indicate to the SCCP layer that the local SSN associated is now in service. A
failure to do so will cause the SSN status to remain prohibited which in return will result in
the SCCP layer not to deliver any incoming messages to the raw TCAP user. Similarly, prior
to termination of all instances of a raw TCAP user, sccp_StateReq() function call needs to
be invoked one more time to indicate to the SCCP layer that the SSN associated is now
going out-of-service; therefore, the local SSN status should be marked as prohibited.
RETURN VALUES
fd
-1
On success, a non-negative integer, namely a file descriptor.

On Failure; errno is set to indicate the error.
ERRORS
<ESRCH>::The tcmd() daemon on the local host is not running.
<ENLINKED>::The Distributed7 software architecture necessary for
TCAP level registration to be performed is not yet set up,
possibly because SCCP layer on local host is not ready.
Check to see if scmd() daemon is running on local host.
<EMAXUSR>::Maximum number of user processes allowed to co-exist
for a given SCCP subsystem or TCP/IP port identifier is
exceeded. Distributed7environment allows up to 63
instances of a particular raw TCAP user to coexist on a
specified host at a given time.
from the tcmd() daemon.
communication failure with the tcmd() daemon process.
<ESYSDOWN>::Unable to service user request since the system
software is in the process of being shut down.
Note: For a list of additional errno values, refer to the manual pages of spm_open() and
spm_bind() function calls.
NOTES
Important: Successful operation of the tcr_open() function call as well as all other function
calls comprising the raw TCAP API library requires the tcmd() daemon process to be up
and running.
SEE ALSO tcmd (), spm_open(), spm_bind(), tcr_close (), tcr_getldflag(),
Page 11 - 5
1-1600-1003-01
tcr_setldflag(), tcr_getldsopt (), tcr_setldsopt, sccp_StateReq ()
11.2.2 tcr_getldflag() / tcr_setldflag()

NAME
tcr_getldflag
tcr_setldflag
Gets load-sharing flags.

Sets load-sharing flags.
SYNOPSIS
#include <api.h>
#include <tcap_raw.h>
int tcr_getldflag(int fd, tcrflag_t * flags);
int tcr_setldflag(int fd, tcrflag_t flags);
MT-LEVEL
MT-Safe
DESCRIPTION
These functions are designed to retrieve and/or manipulate parameters associated with the
load-sharing capability that is available for use by raw TCAP users running under the
Distributed7 environment. The TCAP load-sharing capability allows multiple instances [if
any] of a raw TCAP user associated with a particular SCCP subsystem [or a particular
host and a port identifier] to collaborate when processing incoming messages destined to
that user.
When operating under the Distributed7 environment, users can create up to a maximum of
63 instances of a particular raw TCAP user, e.g., for signalling point and SCCP
subsystem number 254, on a specified host. While each of these instances can originate
and send out messages, whether they should receive any incoming messages is determined
on the basis of load-sharing flags as follows: If a particular instance is not interested in
receiving any incoming messages, then it should invoke the tcr_setldflag() function call
up-front with a flags value of L_TCR_INST_LOAD_SHARE_OFF. However, if it is
interested in receiving and processing incoming messages, then it should specify a flags
value of L_TCR_INST_LOAD_SHARE_ON instead.
By default, the load-sharing flags for the very first instance of a raw TCAP user (i.e.,
instance number 1) on a specified host will always be set to
L_TCR_INST_LOAD_SHARE_ON whereas the load-sharing flags for all other local
instances of that user will be set to L_TCR_INST_LOAD_SHARE_OFF.
Page 11 - 6
1-1600-1003-01
This is to allow that each raw TCAP user has at least one local instance available to
receive and process incoming messages received through a particular host.
The instance-based TCAP load-sharing capability can be programmed to support one of
the two message distribution algorithms as follows: [1] least-busy [default]; and [2]
round-robin. To obtain more information about these algorithms, refer to the
tcr_getldsopt() and tcr_setldsopt() man pages.
If all local instances of a raw TCAP user set their load-sharing flags to
L_TCR_INST_LOAD_SHARE_OFF at a given time, incoming messages destined to this
user will be discarded by the TCAP layer with no indication given to the user.
Starting with Release 1.0.0 of the Distributed7 product, an additional layer of control has
been introduced over the aforementioned TCAP load-sharing mechanism. This new layer
of control involves load-sharing all incoming messages between qualified hosts in a
round-robin fashion first. It is only after the target host is identified, an incoming message
will be delivered to an appropriate instance running on that host. Application control over
the newly introduced load-sharing mechanism is via the
L_TCR_HOST_LOAD_SHARE_ON and L_TCR_HOST_LOAD_SHARE_OFF flags
[which of course can be used in conjunction with the L_TCR_INST_LOAD_SHARE_ON
and L_TCR_INST_LOAD_SHARE_OFF flags mentioned earlier]. By default, the system
will assume a setting of L_TCR_HOST_LOAD_SHARE_ON as long as the raw TCAP
user in consideration features multiple instances across multiple hosts and that there is at
least one instance on each host with a setting of L_TCR_INST_LOAD_SHARE_ON. As
an automatic result of this, all incoming messages received through a particular host will
first be load-shared with all other hosts first and then distributed to an appropriate instance
of the user on the selected host. Note however that it is possible to disable this mechanism
simply by invoking the tcr_setldflag() function with a flags setting of
L_TCR_HOST_LOAD_SHARE_OFF on all appropriate hosts.
The tcr_getldflag() function call is used to retrieve the current settings of the load-sharing
flags for the individual instances of a raw TCAP user and save them in a user-specified
memory location pointed to by the flags argument. Upon successful return from a
tcr_getldflag() function call, memory location pointed to by the flags argument will
contain a bit-mask where the individual bits indicate whether load-sharing is enabled or
disabled for the corresponding instance (i.e., 1's indicate that load-sharing is enabled
whereas 0's indicate that it is disabled).
It must be noted here that the least-significant bit of this bit-mask (i.e., bit position 0)
corresponds to instance number 0 (i.e., tcmd daemon process which is responsible for
setting up and maintaining the TCAP multiplexor) and it is instrumental in identifying
whether host-basedload-sharing is currently enabled or not. If the least-significant bit
position contains a value of 1, this should be interpreted to mean that host-based loadsharing is currently enabled. Alternatively a value of 0 in this bit position should be
interpreted to mean that host-based load-sharing is currently disabled. Applications
Page 11 - 7
1-1600-1003-01
interested in finding out about the load-sharing flags associated with their individual
instances should always start from bit position 1 [which corresponds to the instance
number 1] and go up when interpreting the load-sharing flag settings for their individual
instances.
RETURN VALUES
0
-1
On success. Also the current setting of the load-share flags for the
individual instances associated with the user are returned, in the form of a
bit-mask within the flags argument.
ERRORS
SEE ALSO tcmd (), tcr_open (), tcr_getldsopt (), tcr_setldsopt ()
11.2.3 tcr_getldsopt() / tcrsetldsopt()

NAME
tcr_getldsopt
Gets the load-sharing algorithm.
tcr_setldsopt
Sets the load-sharing algorithm.
MT-LEVEL
MT-Safe
SYNOPSIS
tcr_getldsopt(int fd, int *opts);
tcr_setldsopt(int fd, int opts);
DESCRIPTION
These functions are designed to retrieve (get) parameters (flags) associated with the
instance-based load-sharing capability that is available for use by raw TCAP users
running under Distributed7 environment.
The instance-based load-sharing capability allows multiple instances [if any] of a raw
TCAP user associated with a particular SCCP subsystem [or a particular host and a port
identifier] to collaborate when processing incoming messages destined to that user - refer
to the tcr_getldsopt() and tcr_setldsopt() man pages for more information. When
operating under the Distributed7 environment, users can create up to a maximum of 63
Page 11 - 8
1-1600-1003-01
instances of a particular raw TCAP user (e.g., for signalling point 0 and SCCP subsystem
number 254) on a specified host.
While each one of these instances can originate and send out messages, whether they
should receive any incoming messages is determined on the basis of so-called instancebased load-sharing flags. These flags can be retrieved or manipulated using the
tcr_getldflag() and tcr_setldflag() functions, respectively.
Assuming that multiple instances of a raw TCAP user have all enabled their instancebased load-sharing flags, the question is how to distribute incoming messages among
these instances. The answer depends on the instance-based load-sharing algorithm that is
in use. The current implementation allows either least-busy or round-robin message
distribution algorithms to be used for load-sharing purposes.
Users can establish control over the instance-based load-sharing algorithm used by
invoking the tcr_setldsopt() call as follows:
+ specifying an opts value of L_TCR_INST_LOAD_SHARE_OPT_LB indicates that
the least-busy message distribution algorithm should be used. This is the default setting
for a newly registered raw TCAP user.
+ specifying an opts value of L_TCR_INST_LOAD_SHARE_OPT_RR indicates that
the round-robin message distribution should be used.
The least-busy load-sharing algorithm uses information regarding the total number of
bytes waiting to be retrieved from the read-side STREAMS queue by a particular instance
when determining which instance of a raw TCAP user should be the one receiving the
next incoming message. Provided that there are multiple instances of a raw TCAP user on
a specified host, if the first instance of the user attends its read-side queue fast enough,
other local instances of this user may not receive any incoming messages. It is only when
messages accumulate on the read-side queue of the first instance, other instances of this
user will receive incoming messages.
The round-robin load-sharing algorithm, on the other hand, will result in equal
distribution of incoming messages between all interested instances of a raw TCAP user.
The tcr_getldsopt() function call is used to retrieve the current setting of the instancebased load-sharing algorithm that is use and save it in a user-specified memory location
pointed to by the opts argument. Upon successful return from a tcr_getldsopt() function
call, memory location pointed to by the opts argument will contain an integer value of
either L_TCR_INST_LOAD_SHARE_OPT_LB [for least-busy] or
L_TCR_INST_LOAD_SHARE_OPT_RR [for round-robin].
RETURN VALUES
0
On success. Also the current setting of the instance-based load-share

algorithm that is used, is returned.
Page 11 - 9
1-1600-1003-01
-1
ERRORS
SEE ALSO tcmd (), tcr_open (), tcr_getldflag (), tcr_setldflag ()
11.2.4 tcr_close()
NAME
tcr_close
Closes a previously established raw connection.
SYNOPSIS
int tcr_close(int fd);
MT-LEVEL
MT-Safe
DESCRIPTION
Used to de-register a raw TCAP user, close the service endpoint associated with the user,
and release any local library resources [including memory resources] allocated for the user
at the time of a tcr_open() function call.
fd
Identifies the service endpoint associated with the user and should be
obtained via a previous tcr_open() call.
Note: This should be the last call made by any raw TCAP user when the user is no longer
interested in exchanging messages.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO tcmd (), tcr_open ()
Page 11 - 10
1-1600-1003-01
Page 11 - 11
1-1600-1003-01
Page 11 - 12
1-1600-1003-01
Chapter 12:
Extended TCAP API Library
12.1 Chapter Overview

This chapter provides a listing of the TCAP extended library Application Program Interface
(API). The extended TCAP API group consists of put and get commands which are listed
together. Each API library call is listed with its name, synopsis, description, and return values.
12.2 Extended TCAP API Library

This section provides a reference for putting or getting parameters into or from the data
portion of the TCAP messages as defined in the ANSI TCAP specification. They all have
the same structure, except the generic calls for parameters which are only one octet long,
unspecified, or involve strings (see tcx_put_octet_par())
In general the put() functions first argument is a pointer to where the parameter is going to
be placed, and the second argument is a pointer to the parameter, usually a structure. The
function then places the parameter tag, parameter length, and the parameter itself, beginning
from the address passed to the function, and then returns the length in octets that the whole
information takes. The return value length of the parameter contains the identifier and
length information as well. This return value should be used to increment the position to the
end of the parameter information so that the successive parameters can be placed easily.
To use the Extended TCAP function calls, the following header files must be included at the
beginning of the application in the given order:
#include <api.h>
#include <api.proto.h>
#include <tcap.h>
#include <tcap_ext.h>
The generic calls are listed first, followed by the parameter-specific calls in alphabetical
order.
Important: Distributed7 1.2. Extended TCAP API is multi-thread (MT) Safe, and can be
used with multi-threaded application programs. When compiling multi-threaded
applications, the -D_REENTRANT flag must be specified.
Page 12 - 1
1-1600-1003-01
12.2.1 tcx_put_acg_ind() / tcx_get_acg_ind()

DESCRIPTION
tcx_put_acg_ind()
This function allows a TC user to build the automatic call gap
(ACG) indicator parameter and insert it into the data portion of a TCAP message.
tcx_get_acg_ind()
This function allows a TC user to retrieve the ACG indicator
parameter from within the data portion of a TCAP message and copy it to a user specified
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_acg_ind(byte_t * msg , acg_indicator_t * par );
msg
This argument points to the data portion of the message to which the
parameter built should be copied to.
par
This argument points to a user space data buffer of type acg_indicator_t
from which the parameter contents can be obtained
int tcx_get_acg_ind(byte_t * msg , acg_indicator_t * par );
msg
This argument points to the data portion of the message from which the
parameter should be retrieved.
par
This argument points to a user space data buffer of type acg_indicator_t
to which the parameter contents should be copied.
RETURN VALUES
int
-1
On success. A non-negative integer value which corresponds to the

length of the parameter being built or retrieved.
On failure.
12.2.2 tcx_put_bear_cap() / tcx_get_bear_cap()

DESCRIPTION
tcx_put_bear_cap()
This function allows a TC user to build the bearer capability
requested parameter and insert it into the data portion of a TCAP message.
tcx_get_bear_cap()
This function allows a TC user to retrieve the bearer capability
requested parameter from within the data portion of a TCAP message and copy it to a user
specified data buffer.
MT-LEVEL
MT-Safe
Page 12 - 2
1-1600-1003-01
SYNOPSIS
int tcx_put_bear_cap(byte_t * msg , bearer_cap_req_t * par );
msg
par
This argument points to a user space data buffer of type
bearer_cap_req_t from which the parameter contents can be obtained.
int tcx_get_bear_cap(byte_t * msg , bearer_cap_req_t * par );
msg
par
bearer_cap_req_t to which the parameter contents should be copied.
RETURN VALUES
int
-1

On failure.
12.2.3 tcx_put_bill_ind() / tcx_get_bill_ind()

DESCRIPTION
tcx_put_bill_ind()
This function allows a TC user to build the billing indicator
parameter and insert it into the data portion of a TCAP message.
tcx_get_bill_ind()
This function allows a TC user to retrieve the billing indicator
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_bill_ind(byte_t * msg , billing_ind_t * par );
msg
par
This argument points to a user space data buffer of type billing_ind_t
from which the parameter contents can be obtained.
int tcx_get_bill_ind(byte_t * msg , billing_ind_t * par );
msg
par
This argument points to a user space data buffer of type billing_ind_t to
which the parameter contents should be copied.
Page 12 - 3
1-1600-1003-01
RETURN VALUES
int
-1

On failure.
12.2.4 tcx_put_buss_grp() / tcx_get_buss_grp()

DESCRIPTION
tcx_put_buss_grp()
This function allows a TC user to build the business group
number parameter and insert it into the data portion of a TCAP message.
tcx_get_buss_grp()
This function allows a TC user to retrieve the business group
number parameter from within the data portion of a TCAP message and copy it to a user
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_buss_grp(byte_t * msg , buss_grp_t * par );
msg
par
This argument points to a user space data buffer of type buss_grp_t from
which the parameter contents can be obtained.
int tcx_get_buss_grp(byte_t * msg , buss_grp_t * par );
msg
par
This argument points to a user space data buffer of type buss_grp_t to
RETURN VALUES
int
-1
Page 12 - 4

On failure.
1-1600-1003-01
12.2.5 tcx_put_ccsan() / tcx_get_ccsan()

DESCRIPTION
tcx_put_ccsan()
This function allows a TC user to build the CCSAN indicator
tcx_get_ccsan()
This function allows a TC user to retrieve the CCSAN indicator
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_ccsan(byte_t * msg , byte_t * par );
msg
par
This argument points to a user space data buffer from which the
parameter contents can be obtained.
int tcx_get_ccsan(byte_t * msg , byte_t * par );
msg
par
This argument points to a user space data buffer to which the parameter
contents should be copied.
RETURN VALUES
int
-1

On failure.
12.2.6 tcx_put_cf_status() / tcx_get_cf_status()

DESCRIPTION
tcx_put_cf_status()
This function allows a TC user to build the call forwarding status
tcx_get_cf_status()
This function allows a TC user to retrieve the call forwarding
status parameter from within the data portion of a TCAP message and copy it to a user
MT-LEVEL
MT-Safe
Page 12 - 5
1-1600-1003-01
SYNOPSIS
int tcx_put_cf_status(byte_t * msg , call_forw_status_t * par );
msg
par
call_forw_status_t from which the parameter contents can be obtained.
int tcx_get_cf_status(byte_t * msg , call_forw_status_t * par );
msg
par
call_forw_status_t to which the parameter contents should be copied.
RETURN VALUES
int
-1

On failure.
12.2.7 tcx_put_com_id() / tcx_get_com_id()

DESCRIPTION
tcx_put_com_id()
This function allows a TC user to build the company ID
tcx_get_com_id()
This function allows a TC user to retrieve the company indicator
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_com_id(byte_t * msg , char * par );
msg
par
int tcx_get_com_id(byte_t * msg , byte_t * par );
msg
par
Page 12 - 6
1-1600-1003-01
RETURN VALUES
int
-1

On failure.
12.2.8 tcx_put_digits() / tcx_get_digits()

DESCRIPTION
tcx_put_digits()
This function allows a TC user to build the digits parameter and
insert it into the data portion of a TCAP message.
tcx_get_digits()
This function allows a TC user to retrieve the digits parameter
from within the data portion of a TCAP message and copy it to a user specified data
buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_digits(byte_t * msg , digits_t * par );
msg
par
This argument points to a user space data buffer of type digits_t from
int tcx_get_digits(byte_t * msg , digits_t * par );
msg
par
This argument points to a user space data buffer of type digits_t to which
the parameter contents should be copied.
RETURN VALUES
int
-1

On failure.
12.2.9 tcx_put_dn_to_ls() / tcx_get_dn_to_ls()

DESCRIPTION
tcx_put_dn_to_ls()
This function allows a TC user to build the directory number to
line service type mapping parameter and insert it into the data portion of a TCAP
message.
Page 12 - 7
1-1600-1003-01
tcx_get_dn_to_ls()
This function allows a TC user to retrieve the directory number to
line service type mapping parameter from within the data portion of a TCAP message and
copy it to a user specified data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_dn_to_ls(byte_t * msg , dn_to_line_t * par );
msg
par
This argument points to a user space data buffer of type dn_to_line_t
from which the parameter contents can be obtained.
int tcx_get_dn_to_ls(byte_t * msg , dn_to_line_t * par );
msg
par
This argument points to a user space data buffer of type dn_to_line_t to
RETURN VALUES
int
-1

On failure.
12.2.10tcx_put_duration() / tcx_get_duration()
DESCRIPTION
tcx_put_duration()
This function allows a TC user to build the duration parameter
and insert it into the data portion of a TCAP message.
tcx_get_duration()
This function allows a TC user to retrieve the duration parameter
buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_duration(byte_t * msg , duration_t * par );
msg
Page 12 - 8
1-1600-1003-01
par
This argument points to a user space data buffer of type duration_t from
int tcx_get_duration(byte_t * msg , duration_t * par );

msg
par
This argument points to a user space data buffer of type duration_t to
RETURN VALUES
int
-1

On failure.
12.2.11tcx_put_ic_ind() / tcx_get_ic_ind()
DESCRIPTION
tcx_put_ic_ind()
This function allows a TC user to build the inter-exchange carrier
(IC) indicator parameter and insert it into the data portion of a TCAP message.
tcx_get_ic_ind()
This function allows a TC user to retrieve the IC indicator
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_ic_ind(byte_t * msg , IC_ind_t * par );
msg
par
This argument points to a user space data buffer of type IC_ind_t from
int tcx_get_ic_ind(byte_t * msg , IC_ind_t * par );
msg
par
This argument points to a user space data buffer of type IC_ind_t to
RETURN VALUES
int
-1

On failure.
Page 12 - 9
1-1600-1003-01
12.2.12tcx_put_octet_par() / tcx_get_octet_par()
DESCRIPTION
tcx_put_octet_par()
This function allows a TC user to build an octet-sized parameter
tcx_get_octet_par()
This function allows a TC user to retrieve an octet-sized
data buffer.
SYNOPSIS
int tcx_put_octet_par(byte_t * msg , dword_t par_id , byte_t par );
msg
par_id
This argument specifies the parameter ID associated with the parameter
to be built.
par
parameter contents can be obtained. Information in par buffer is placed in
the message after par_id.
int tcx_get_octet_par(byte_t * msg , dword_t par_id , byte_t * par );
msg
par_id
to be retrieved.
par
RETURN VALUES
int
-1

On failure.
12.2.13tcx_put_par() / tcx_get_par()
DESCRIPTION
tcx_put_par()
This function allows a TC user to build a non-standard parameter
tcx_get_par()
This function allows a TC user to retrieve a non-standard
data buffer.
Page 12 - 10
1-1600-1003-01
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_par(byte_t * msg , dword_t par_id , byte_t par_len , byte_t * par );
msg
par_id
to be built.
par_len
This argument specifies the length of the parameter in bytes. This value
is placed in the message after par_id.
par
parameter contents can be obtained. Information in par buffer is placed
in the message after par_len.
int tcx_get_par(byte_t * msg , dword_t par_id , byte_t * par_len , byte_t * par );
msg
par_id
to be retrieved.
par_len
This argument gives information about the length of the parameter
retrieved (the number of octets retrieved from the message and copied
into par).
par
RETURN VALUES
int
-1

On failure.
12.2.14tcx_put_par_str()
DESCRIPTION
tcx_put_par_str()
This function allows a TC user to build a string parameter and
insert it into the data portion of a TCAP message.
MT-LEVEL
MT-Safe
Page 12 - 11
1-1600-1003-01
SYNOPSIS
int tcx_put_par_str(byte_t * msg , dword_t par_id , byte_t * par );
msg
par_id
to be built.
par
parameter contents can be obtained. Information in par buffer is placed in
the message after par_id.
RETURN VALUES
int
-1

On failure.
12.2.15tcx_put_pin() / tcx_get_pin()
DESCRIPTION
tcx_put_pin()
This function allows a TC user to build the personal identification
number (PIN) identifier parameter and insert it into the data portion of a TCAP message.
tcx_get_pin()
This function allows a TC user to retrieve the PIN identifier
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_pin(byte_t * msg , priv_pin_t * par );
msg
par
This argument points to a user space data buffer of type priv_pin_t from
int tcx_get_pin(byte_t * msg , priv_pin_t * par );
msg
par
This argument points to a user space data buffer of type priv_pin_t to
Page 12 - 12
1-1600-1003-01
RETURN VALUES
int
-1

On failure.
12.2.16tcx_put_priv_digits() / tcx_get_priv_digits()
DESCRIPTION
tcx_put_priv_digits() This function allows a TC user to build the private digits
tcx_get_priv_digits() This function allows a TC user to retrieve the private digits
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_priv_digits(byte_t * msg , digits_t * par );
msg
par
This argument points to a user space data buffer of type digits_t from
int tcx_get_priv_digits(byte_t * msg , digits_t * par );
msg
par
This argument points to a user space data buffer of type digits_t to which
the parameter contents should be copied.
RETURN VALUES
int
-1

On failure.
12.2.17tcx_put_ref_id() / tcx_get_ref_id()
DESCRIPTION
tcx_put_ref_id()
This function allows a TC user to build the reference ID
Page 12 - 13
1-1600-1003-01
tcx_get_ref_id()
This function allows a TC user to retrieve the reference ID
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_ref_id(byte_t * msg , dword_t par );
msg
par
int tcx_get_ref_id(byte_t * msg , dword_t * par );
msg
par
RETURN VALUES
int
-1

On failure.
12.2.18tcx_put_tr_id() / tcx_get_tr_id()
DESCRIPTION
tcx_put_tr_id()
This function allows a TC user to build the transaction ID
tcx_get_tr_id()
This function allows a TC user to retrieve the transaction ID
data buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_tr_id(byte_t * msg , dword_t par );
msg
Page 12 - 14
1-1600-1003-01
par
int tcx_get_tr_id(byte_t * msg , dword_t * par );

msg
par
RETURN VALUES
int
-1

On failure.
12.2.19tcx_put_tstamp_par() / tcx_get_tstamp_par()
DESCRIPTION
tcx_put_tstamp_par() This function allows a TC user to build a time-stamp parameter
tcx_get_tstamp_par() This function allows a TC user to retrieve a time-stamp parameter
buffer.
MT-LEVEL
MT-Safe
SYNOPSIS
int tcx_put_tstamp_par(byte_t * msg , byte_t * par );
msg
par
int tcx_get_tstamp_par(byte_t * msg , byte_t * par );
msg
par
RETURN VALUES
int
-1

On failure.
Page 12 - 15
1-1600-1003-01
Page 12 - 16
1-1600-1003-01
Chapter 13:
ISUP Call Control Library
ISUP API Library

This chapter describes the function calls of the ISUP-Call Control Interface API library.
Starting with Distributed7 Rel. 1.3.0, JAIN (Java APIs for the Integrated Network) ISUP is
supported. More information on the ISUP interface and JAIN ISUP API support can be
found in the Distributed7 Application Development Manual.
13.2 ISUP Call Control Library

A Call Control Interface library is provided to aid Call Control in the packing and
unpacking of ISUP messages. The SPM library (libspm.a) and the ISUP Call Control library
(libisup.a), must be linked with the Call Control application.The API prototypes are defined
in isup_api.h, which must be included for compilers to check the usage of the function calls.
#include <isup_api.h>
Sample source code files, (see list below) are provided to demonstrate the use of
Distributed7 ISUP literals and functions. They should be compiled with the MAKEFILE in
the $EBSHOME/access/sample/isup directory. After they are compiled, the executables are
Makefile
answer.c
call.c
CCsim.c
RDparam_ansi.c
RDparam_itu.c
parseTBL.c
Templates_ansi
Templates_itu
Templates_ansi.0
Templates_ansi.1
Templates_itu.0
Templates_itu.1
Page 13 - 1
1-1600-1003-01
Important: Distributed7 1.2. ISUP API is multi-thread (MT) Safe, and can be used with
isup_dereg_req()
Allows ISUP users, i.e., Call Control and maintenance users, to
de-register with the ISUP layer so that they no longer send and receive protocol messages
through the SS7 network.
Important: Before calling the isup_dereg_req() function, all appropriate fields of the
isup_dereg_req_t data structure must be populated.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_dereg_req(int fd, int sp, ipcaddr_t *addr, isup_dereg_req_t *req);
fd
Identifies the file descriptor acquired through an earlier spm_open() call.
sp
Identifies the signalling point with which the ISUP user as well as the
isupd daemon is associated, and may assume a value in the [0, NSP - 1]
range.
addr
Identifies the IPC address of the ISUP user established through an earlier
call to spm_bind(), and it allows the isupd() daemon to perform
necessary clean-up work to stop handling message traffic through
specified trunk groups.
req
Points to a user-space memory location that contains de-registration
related information.
isup_dereg_req_tThe contents of the isup_dereg_req_t structure is as follows:
typedef struct {
word_t trunkgrpid;
word_t usertype;
word_t reserved;
dword_t inetaddr;
} isup_dereg_req_t;
where the trunkgrpid field identifies the trunk group(s) that the user is no
longer interested in using, the usertype field identifies the user category,
i.e., Call Control or maintenance application, and the inetaddr field
identifies the IP address of the host on which the isupd() daemon is
running. The reserved field is not currently used.
The permissible values of trunkgrpid are in the [0,
L_MAX_NUMBER_OF_TRKGROUPS - 1] range. Alternatively, a
trunkgrpid value of L_ALL_TRNKGRPS can be specified to indicate
Page 13 - 2
1-1600-1003-01
that de-registration of the user spans all trunk groups currently

configured.
Important: The Distributed7 ISUP layer requires each trunk group to be used to have an
ISUP user registered to it. Otherwise, all protocol messages pertaining to such trunk groups
are discarded by the isupd() daemon. Therefore, all trunk groups must be used for network
message exchange to have an ISUP user registered to it.
The inetaddr field is instrumental in identifying the isupd() daemon
instance to communicate through in a distributed product configuration.
An inetaddr value of 0 specifies that the services of the isupd() daemon
on the local host are to be used. By specifying the inetaddr of a remote
host, users can construct front-end/back-end configurations in which the
user application runs on a back-end machine and the ISUP layer as well
as the rest of the Distributed7 stack runs on front-end machine(s).
When an application tries to de-register with the ISUP layer using the
isup_dereg_req() function, results of this de-registration request are
returned to the application in the form an IPC message that contains an
ISUP_DEACTIVATE_CONF primitive. Upon receipt of this message,
applications call the isup_dereg_rsp() function to find out about the
results of the earlier de-registration attempt.
Important: For an ISUP user to de-register from multiple trunk groups but not from all
trunk groups configured it needs to invoke the isup_dereg_req() function multiple times.
There is no inherent system limit to the number of successive isup_dereg_req() calls a user
can place. However, each isup_dereg_req() call results in a corresponding
ISUP_DEACTIVATE_CONF primitive being returned to the user; the user must check the
results of each de-registration attempt, i.e., by calling the isup_dereg_rsp() function each
time an ISUP_DEACTIVATE_CONF primitive is received.
RETURN VALUES
0
-1
On success.
On failure, andthe errno variable is set to an appropriate value.
ERRORS
<EINVAL>::An invalid function argument is specified.
<ENOGRP>::Cannot locate trunk group specified.
<ENOTRNK>::Trunk group specified is not currently activated.
<EACCES>::Trunk group specified is owned by another application.
Important: For additional errno values that may be returned, see man pages for the
spm_snd() function.
SEE ALSO spm_open(), spm_bind(), spm_snd(), isup_dereg_rsp(),
Page 13 - 3
1-1600-1003-01
isup_reg_req(), isup_reg_rsp(), isup_reg(), isup_mtc_dereg(), isup_snd_msg()

isup_dereg_rsp()
Returns to the application the results of earlier de-registration
attempts when the application tries to de-register with the ISUP layer using the
isup_dereg_req() function. The results of the de-registration request are returned in the
form an IPC message that contains an ISUP_DEACTIVATE_CONF primitive.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_dereg_rsp(int fd, ipcmsg_t *msg, int *grp );
fd
Identifies the file descriptor through which the earlier isup_dereg_req()
call is placed.
msg
Points to an ipcmsg_t structure that contains the IPC message with the
ISUP_DEACTIVATE_CONF primitive.
grp
Returns to the user the number of the trunk group associated with a
particular ISUP_DEACTIVATE_CONF primitive. Upon successful
return from the isup_dereg_rsp() function, user-space memory pointed to
by the grp argument is initialized by the ISUP API library to contain the
trunk group number associated with the particular de-registration
attempt.
RETURN VALUES
0
-1
On success.
On failure, and the errno variable is set to an appropriate value.
ERRORS
<ENOTRNK>::Trunk group specified is not currently activated.
<EACCES>::Trunk group specified is owned by another application.
spm_snd() function.
SEE ALSO spm_open(), spm_bind(), spm_snd(), isup_reg_req(),
isup_dereg_req(), isup_reg_rsp(), isup_dereg(), isup_mtc_dereg(),
isup_snd_msg()isup_flex_get_hdr()Retrieves the header information, i.e., trunk ID,
circuit ID and the ISUP message type, from an IPC message that contains an ISUP Call
Control primitive. This function is introduced to support 256K CIC.
Page 13 - 4
1-1600-1003-01
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_flex_get_hdr(int fd, ipcmsg_t *msg , isup_flex_hdr_t *hdr);
fd
msg
Points to an ipcmsg_t structure that contains the IPC message.
hdr
Points to the user-space memory location to which the retrieved Call
Control header information is copied.
Upon completion of the call, the trnkid field in isup_flex_hdr_t contains
the trunk id, the cctid filed contains the circuit id, the msgtyp field
contains the ISUP message type, and the prmtvtyp field contains the Call
Control primitive type.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_mtc_hdr(), isup_get_prm(), isup_put_hdr(), isup_get_hdr(),

isup_flex_put_hdr(), isup_put_prm(), isup_snd_msg()
isup_flex_get_mtc_hdr()Retrieves the header information, i.e., trunk id, circuit id, and
the ISUP message type, from an IPC message that contains an ISUP maintenance
indication.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_mtc_hdr(int fd, ipcmsg_t *msg, isup_flex_mtc_hdr_t *hdr);
fd
msg
hdr
Points to a user-space memory location to which the retrieved
maintenance header information is copied.
Upon completion of the call, the trnkid field in isup_mtc_hdr_t contains
the trunk id, cctid contains the circuit id, the msgtyp field contains the
ISUP message type, the moduleID field contains the ISUP module
Page 13 - 5
1-1600-1003-01
number that originated the maintenance request, and the prmtvtyp field
contains the maintenance primitive type.
After an IPC message is received and identified to be an ISUP
maintenance system indication, and its header information is extracted
using the isup_flex_get_mtc_hdr() function, its contents can be analyzed
using the isup_get_prm() function.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_hdr(), isup_get_prm(), isup_put_hdr(), isup_put_flex_hdr(),

isup_get_mntc_hdr(), isup_put_prm()
isup_flex_get_tmr_info()Retrieves timer-related ISUP maintenance information
embedded within an IPC message.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_flex_get_tmr_info(int fd, ipcmsg_t *msg, isup_flex_tmr_t *tmr);
fd
msg
tmr
Points to a user-space memory location to which retrieved timer-related
maintenance information is copied.
The contents of the isup_flex_tmr_t structure is as follows:
typedef struct {
word_t msgtyp;
#define L_MNTCTMR_TIMER_STOPPED
1
#define L_MNTCTMR_TIMER_NOT_RUNNING 2
#define L_MNTCTMR_TIMER_EXPIRED
3
word_t trnkid;
word_t cctid;
word_t timerID;
word_t moduleID;
} isup_tmr_t;
where the msgtyp field identifies the nature of the maintenance timer
event, the trnkid field contains the identification code for the trunk and
Page 13 - 6
1-1600-1003-01
cctid field contains the affected circuit number, the timerID field
indicates the timer identification code, and the moduleID field identifies
the ISUP module sending the maintenance message.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_hdr(), isup_get_mtc_hdr(), isup_put_hdr(),

isup_flex_get_hdr(), isup_flex_get_mntc_hdr(), isup_flex_put_hdr(),
isup_get_tmr_info()
isup_flex_put_hdr()
Places the trunk identification, circuit identification and the ISUP
message type in the data portion of an IPC message.
MT-LEVEL
MT-Safe
Important: Before calling isup_flex_put_hdr(), all appropriate fields of the isup_flex_hdr_t
data structure must be populated properly.
SYNOPSIS
int isup_flex_put_hdr(int fd, ipcmsg_t *msg, isup_flex_hdr_t *hdr);
fd
msg
Points to an ipcmsg_t structure that contains the IPC message. The
msgtyp field of the ipcmsg_t is set to indicate the ISUP primitive type
contained in the prmtvtyp field of the isup_flex_hdr_t.
hdr
Points to a user-space memory location of type isup_flex_hdr_t that
contains information about the specifics of the header to be placed in the
IPC message.
The ISUP message type field must be filled out whether or not an ISUP
message type exists for the primitive being used in the message. If no
ISUP message type is associated with a particular primitive, then any
valid ISUP message type can be put into the field. Tables in the
Distributed7 Application Development Manual provide the valid
message types associated with ISUP primitives. Other valid ISUP
message types can also be used. ISUP does use the information in the
field, but it does not accept an empty field or an invalid type in the field.
Page 13 - 7
1-1600-1003-01
RETURN VALUES
0
-1
On success.
ERRORS
<EINVMSGTYP>::The message type contained within hdr is unrecognized.
SEE ALSO isup_get_hdr(), isup_flex_get_hdr(), isup_get_mtc_hdr(),

isup_flex_get_mntc_hdr(), isup_get_prm(), isup_put_hdr(), isup_flex_put_hdr(),
isup_snd_msg()
isup_get_cct_no()
Returns the circuit number associated with a user-specified
Circuit Identification Code (CIC).
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_cct_no(int fd, int cic);
fd
cic
Identifies the CIC of interest.
RETURN VALUES
Non-negative integerOn success.
-1
On failure.
Important: isup_get_cct() is invoked only after registration with the ISUP layer is
completed, confirmed, and processed by the application program. Attempts to invoke
isup_get_cct() before those processes result in incorrect circuit number information. For
details,refer to the man pages for the isup_reg_req() and isup_reg_rsp() functions.
ERRORS
SEE ALSO isup_get_grp_no(), isup_get_cic_no(), isup_get_var(),

isup_get_var_no()isup_get_var_no() Retrieves the current ISUP variant, i.e., ANSI/
ITU, setting and returns it in the form of unsigned integer for application use.
isup_get_cic_no()
Builds and returns the Circuit Identication Code (CIC) for a userspecified pair of circuit and circuit group number.
Page 13 - 8
1-1600-1003-01
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_cic_no(int fd, int cct, int grp);
fd
cct
Identifies the circuit number of interest.
grp
Identifies the circuit group number of interest.
RETURN VALUES
non-negative integer On success.
-1
Important: isup_get_cic_no() is invoked only after registration with the ISUP layer is
isup_get_cic_no() before those processes result in incorrect circuit number information.
For details,refer to the man pages for the isup_reg_req() and isup_reg_rsp() functions.
ERRORS
SEE ALSO SEE ALSO spm_open(), spm_bind(), spm_snd(), isup_reg_req(),

isup_snd_msg(), isup_get_grp_no(), isup_get_var(),
isup_get_dpc_stat()
Retrieves Destination Point Code (DPC) information embedded
within an IPC message that is in the form of an ISUP_DPCSTATUS indication.
Important: The isupd() daemon uses ISUP_DPCSTATUS indication messages to inform
Call Control applications about changes in the congestion status for the ISUP layer at the
remote end of a trunk group.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_dpc_stat(int fd, ipcmsg_t *msg, isup_dpc_t *dpc);
fd
msg
Points to an ipcmsg_t structure that contains the IPC message received.
dpc
Points to a user-space memory location to which retrieved DPC
information is copied.
The contents of the isup_dpc_t structure is as follows:
Page 13 - 9
1-1600-1003-01
typedef struct {
int trkid;
int cctnum;
int conglvl;
} isup_dpc_t;
where the trkid field identifies the trunk group number, the cctnum field
identifies the circuit number within that group, and the conglvl field
contains congestion level information.
RETURN VALUES
0
On success.
-1
Important: isup_get_dpc_stat() is invoked only after registration with the ISUP layer is
isup_get_dpc_stat() before those processes result in incorrect circuit number information.
ERRORS

isup_snd_msg(), isup_get_grp_no()
isup_get_grp_no()
Returns the circuit group number associated with a user-specified
Circuit Identification Code (CIC).
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_grp_no(int fd, int cic);
fd
cic
Identifies the CIC of interest.
RETURN VALUES
non-negative integerOn success.
-1
Important: isup_get_grp_no() is invoked only after registration with the ISUP layer is
Page 13 - 10
1-1600-1003-01
isup_get_grp_no() before those processes result in incorrect circuit number information.

ERRORS

isup_snd_msg(), isup_get_cic_no(), isup_get_var(),
isup_get_hdr()
Retrieves the header information, i.e., CIC and the ISUP message
type, from an IPC message that contains an ISUP Call Control primitive.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_hdr(int fd, ipcmsg_t *msg , isup_hdr_t *hdr);
fd
msg
hdr
Points to the user-space memory location to which the retrieved Call
Control header information is copied.
Upon completion of the call, the CIC field in isup_hdr_t contains the
CIC, the msgtyp field contains the ISUP message type, and the prmtvtyp
field contains the Call Control primitive type.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_mtc_hdr(), isup_get_prm(), isup_put_hdr(), isup_put_prm(),

isup_snd_msg()
isup_get_mtc_hdr()
Retrieves the header information, i.e., CIC and the ISUP message
type, from an IPC message that contains an ISUP maintenance indication.
SYNOPSIS
int isup_get_mtc_hdr(int fd, ipcmsg_t *msg, isup_mtc_hdr_t *hdr);
Page 13 - 11
1-1600-1003-01
fd
msg
hdr

Points to a user-space memory location to which the retrieved
maintenance header information is copied.
Upon completion of the call, the CIC field in isup_mtc_hdr_t contains the
CIC, the msgtyp field contains the ISUP message type, the moduleID
field contains the ISUP module number that originated the maintenance
request, and the prmtvtyp field contains the maintenance primitive type.
After an IPC message is received and identified to be an ISUP
maintenance system indication, and its header information is extracted
using the isup_get_mtc_hdr() function, its contents can be analyzed
using the isup_get_prm() function.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_hdr(), isup_get_prm(), isup_put_hdr(),

isup_put_prm()isup_get_prm()Retrieves a parameter from an IPC message.
Upon return from isup_get_prm(), the nameOFparam field of the prm structure is set to
indicate the retrieved parameter name.
If the parameter retrieved from the message is recognized, and its length is found to be
of appropriate size, then the parameter is placed in an appropriate field of the parameter
union within prm structure, even if its format is determined to be invalid.
If the parameter retrieved from the message is not recognized, then it is placed in the
UndefParameter field of the parameter union.
In all cases, the typeOFparam field indicates whether the retrieved parameter is fixed,
variable, or optional.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_prm(int fd, ipcmsg_t *msg, isup_prm_t *prm);
fd
msg
Points to the IPC message of interest.
Page 13 - 12
1-1600-1003-01
prm
Points to a user-space memory to which information about a parameter

from an IPC message is copied.
RETURN VALUES
-1
ERRORS
<EINVPARCOD>::The parameter name contained within the MSU is not recognized.
<EINVPARFMT>::The parameter contained within the MSU contains reserved values.
<EINVPARSIZE>::The length of the variable or optional parameter retrieved from within the
MSU is out of range.
<EINVPARTYP>::Parameter type specified is invalid.
<ELONGM>::Parsed data size became more than the incoming message size.
<ESHORTM>::Parsing finished in a data size less than the incoming message size.
<EVARPTRMM>::Variable pointer(s) mismatch.
<EOPTPTRMM>::Optional parameter mismatch.
<ELASTPARAM>::There is no other parameter left in the message or an optional pointer exists
but no EOP can be found. If the optional parameter exists, parsing will finish when
EOP is found. If the message still continues, parsing will be finished and
ELASTPARAM error will be returned.
SEE ALSO isup_put_prm(), isup_get_prm(), isup_get_mtc_prm()

isup_get_reg_type()
Retrieves the registration type associated with an ISUP user, i.e.,
Call Control or maintenance application.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_reg_type(int fd);
fd
RETURN VALUES
-1
ERRORS
Page 13 - 13
1-1600-1003-01
SEE ALSO isup_reg(), isup_mtc_reg(), isup_set_reg_type()isup_get_tmr_info()

Retrieves timer-related ISUP maintenance information embedded within an IPC message.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_get_tmr_info(int fd, ipcmsg_t *msg, isup_tmr_t *tmr);
fd
msg
tmr
Points to a user-space memory location to which retrieved timer-related
maintenance information is copied.
The contents of the isup_tmr_t structure is as follows:
typedef struct {
word_t msgtyp;
#define L_MNTCTMR_TIMER_STOPPED
1
#define L_MNTCTMR_TIMER_NOT_RUNNING 2
#define L_MNTCTMR_TIMER_EXPIRED
3
dword_t CIC;
word_t timerID;
word_t moduleID;
} isup_tmr_t;
where the msgtyp field identifies the nature of the maintenance timer
event, the CIC field contains the identification code for the affected
circuit, the timerID field indicates the timer identification code, and the
moduleID field identifies the ISUP module sending the maintenance
message.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_hdr(), isup_get_mtc_hdr(), isup_put_hdr()

isup_get_trk_list()
Retrieves a list of trunks involved upon receipt of an IPC message
that contains an ISUP_ACCEPT_TRUNK or ISUP_RELEASE_TRUNK indication.
MT-LEVEL
MT-Safe
Page 13 - 14
1-1600-1003-01
SYNOPSIS
int isup_get_trk_list(int fd, ipcmsg_t *msg, int *trknum, int *list);
fd
msg
trknum
Points to a user-space memory to which, upon successful return from the
call, the number of trunks involved are copied.
list
Points to a user-space memory to which, upon successful return from the
call, the actual list of trunks involved are copied .
Important: It is the responsibility of the calling process to make sure that list points to a
user-space memory of sufficient size.
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO isup_get_cct_no() and isup_get_grp_no().

isup_get_usr_type()
Retrieves information about an ISUP user, i.e., Call Control or
maintenance application.
SYNOPSIS
int isup_get_usr_type(int fd);
fd
RETURN VALUES
-1
ERRORS
SEE ALSO isup_reg(), isup_mtc_reg(), isup_get_reg_type()

isup_get_var()
Retrieves ISUP variant information in the form of a bit-mask.
SYNOPSIS
dword_t isup_get_var(int fd);
fd
Page 13 - 15
1-1600-1003-01
Important: To determine which ISUP variants are currently in use, the flag settings defined
in the internal <isup_lits.h> header file must be checked. This function is currently reserved
for internal use.
RETURN VALUES
non-zero unsigned integer
On success
0
Important: isup_get_var() is invoked only after registration with the ISUP layer is
isup_get_var() before those processes result in incorrect circuit number information. For
details,refer to the man pages for the isup_reg_req() and isup_reg_rsp() functions.
ERRORS
SEE ALSO isup_get_var_no()isup_get_var_no() Retrieves the current ISUP

variant, i.e., ANSI/ITU, setting and returns it in the form of unsigned integer for
application use.
isup_get_var_no()isup_get_var_no()Retrieves the current ISUP variant, i.e.,

ANSI/ITU, setting and returns it in the form of unsigned integer for application use.
To determine which ISUP variant is currently in use, application programmers should
compare the value returned by isup_get_var_no() to those defined in the <isup_api.h>
header file as follows:
/* ITU variant definitions */
#define L_VRNT_GENERIC_ITU
#define L_VRNT_Q767
#define L_VRNT_NORWAY
#define L_VRNT_TURKEY
#define L_VRNT_UAE
#define L_VRNT_HONGKONG
#define L_VRNT_NEW_ZEALAND
#define L_VRNT_SPAIN
#define L_VRNT_CHILE
#define L_VRNT_THAILAND
#define L_VRNT_SINGAPORE
#define L_VRNT_PHILIPPINES
#define L_VRNT_SWEDEN
#define L_VRNT_FRANCE
#define L_VRNT_CHI24
#define L_VRNT_BELGIUM
Page 13 - 16
1
2
3
4
5
6
7
8
9
10
11
14
15
16
17
18
1-1600-1003-01
#define L_VRNT_ITALY
#define L_VRNT_UNIPAC
#define L_VRNT_GERMANY
#define L_VRNT_SWITZERLAND
#define L_VRNT_RUSSIA
#define L_VRNT_GENERIC_ITU97
#define L_VRNT_AUSTRALIA
#define L_VRNT_SWEDENV1
#define L_VRNT_FINLAND
#define L_VRNT_ETSI97
#define L_VRNT_MEXICO
#define L_VRNT_CZECH
/* ANSI variant definitions */
#define L_VRNT_GENERIC_ANSI
#define L_VRNT_GENERIC_ANSI96
#define L_VRNT_BELL
#define L_VRNT_DSC
#define L_VRNT_MCI
19
20
21
22
23
24
25
26
27
28
29
30
100
100
101
102
103
MT-LEVEL
MT-Safe
SYNOPSIS
dword_t isup_get_var_no(int fd);
fd
RETURN VALUES
non-zero unsigned integer
On success.
0
Important: isup_get_var_no() is invoked only after registration with the ISUP layer is
isup_get_var_no() before those processes result in incorrect circuit number information.
ERRORS
SEE ALSO isup_get_var()

isup_mtc_reg()
Allows maintenance applications to register with the ISUP layer
so that they can send and receive protocol messages through the SS7 network. An
Page 13 - 17
1-1600-1003-01
application must be registered with the Distributed7 platform using the spm_open() and
spm_bind() calls prior to calling this function.
When isup_mtc_reg() is implemented,it results in an implicit call to isup_reg_req(), with
the isup_reg_req_t structure of the latter function to be populated as follows:
typedef struct {
word_t trunkgrpid; /* set to `grp` specified */
word_t usertype; /* set to ISUP_MAINT */
word_t regtype; /* set to `regtype` in use */
word_t reserved; /* not used */
dword_t inetaddr; /* set to 0 *
} isup_reg_req_t;
Important: Since isup_mtc_reg() function provides no control over the regtype field setting,
the isup_get_regtype() and isup_set_regtype() functions must be called in advance to make
sure that the current regtype field setting is accurate prior to calling the isup_mtc_reg()
function for registration.
Important: For more information about the meaning and exact use of the individual fields
listed above, refer to the man pages of the isup_reg_req() function.
When an attempt is made by an application to register with the ISUP layer using the
sup_mtc_reg() function, results of this registration request are returned to the application
in the form an IPC message that contains an ISUP_ACTIVATE_CONF primitive. Upon
receipt of this message, applications are expected to call the isup_reg_rsp() function to
find out about the results of the earlier registration attempt.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_mtc_reg(int fd, int sp, ipcaddr_t *addr, int grp);
fd
sp
isupd() daemon is associated, and may assume a value in the [0, NSP 1] range.
addr
Identifies the IPC address of the maintenance application established
through an earlier call to spm_bind(), and it allows the isupd() daemon to
determine how to address the application when sending messages to it.
grp
Identifies the trunk group(s) to which the application is interested in
registering.
RETURN VALUES
0
-1
Page 13 - 18
On success.
1-1600-1003-01
ERRORS
isup_req_req() and isup_dereq_req() functions.
SEE ALSO spm_open(), spm_bind(), isup_reg_req(), isup_reg_rsp(), isup_reg(),
isup_dereg(), isup_get_reg_type(), isup_set_reg_type(), isup_get_usr_type()
isup_mtc_dereg()
layer.
Allows maintenance applications to de-register with the ISUP
When isup_mtc_dereg() is implemented, it results in an implicit call to isup_dereg_req()

with the isup_dereg_req_t structure in the latter function to be populated as follows:
typedef struct {
word_t usertype; /* set to ISUP_MAINT */
dword_t inetaddr; /* set to 0 */
} isup_dereg_req_t;
Important: For more information about the meaning and exact use of the individual fields
listed above, application programmers are referred to the man pages of the
isup_dereg_req() function.
When an attempt is made by an application to de-register with the ISUP layer using the
isup_mtc_dereg() function, results of this de-registration request are returned to the
application in the form an IPC message that contains an ISUP_DEACTIVATE_CONF
primitive. Upon receipt of this message, applications are expected to call the
isup_dereg_rsp() function to find out about the results of the earlier de-registration
attempt.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_mtc_dereg(int fd, int sp, int grp);
fd
sp
grp
Identifies the trunk group(s) to which the application is interested in
registering.
Page 13 - 19
1-1600-1003-01
RETURN VALUES
0
-1
On success.
ERRORS
SEE ALSO spm_open(), spm_bind(), isup_reg_req(), isup_reg_rsp(), isup_reg(),
isup_dereg(), isup_get_reg_type(), isup_set_reg_type(), isup_get_usr_type()
isup_put_hdr()
Places the circuit identification code (CIC) and the ISUP message
type in the data portion of an IPC message.
Important: Before calling isup_put_hdr(), all appropriate fields of the isup_hdr_t data
structure must be populated properly.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_put_hdr(int fd, ipcmsg_t *msg, isup_hdr_t *hdr);
fd
msg
Points to an ipcmsg_t structure that contains the IPC message. The
msgtyp field of the ipcmsg_t is set to indicate the ISUP primitive type
contained in the prmtvtyp field of the isup_hdr_t.
hdr
Points to a user-space memory location of type isup_hdr_t that contains
information about the specifics of the header to be placed in the IPC
message.
The ISUP message type field must be filled out whether or not an ISUP
message type exists for the primitive being used in the message. If no
ISUP message type is associated with a particular primitive, then any
valid ISUP message type can be put into the field. Tables in the
Distributed7 Application Development Manual provide the valid
message types associated with ISUP primitives. Other valid ISUP
message types can also be used. ISUP does use the information in the
field, but it does not accept an empty field or an invalid type in the field.
RETURN VALUES
0
-1
Page 13 - 20
On success.
1-1600-1003-01
ERRORS
<EINVMSGTYP>::The message type contained within hdr is unrecognized.
SEE ALSO isup_get_hdr(), isup_get_mtc_hdr(), isup_get_prm(), isup_put_hdr(),

isup_snd_msg()
isup_put_prm()
Inserts a user-specified parameter into an IPC message.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_put_prm(int fd, ipcmsg_t *msg, isup_prm_t *prm);
fd
msg
prm
Points to a user-space memory location that contains information about
the specifics of the parameter to be inserted.
Important: Before calling isup_put_prm(), all appropriate fields of the isup_prm_t data
structure must be populated, the parameter union must contain information about the
parameter corresponding to nameOFparam, and the typeOFparam field must indicate
whether the parameter is fixed, variable, or optional.
The fixed parameters of the ISUP message must first be put in the
required order.
The mandatory variable parameters must be placed before the
optional parameters.
All mandatory parameters must be put in the order defined in the
specifications of the ISUP protocol being used, i.e., ANSI
Recommendations 113 (92) or ITU Recommendations Q761-Q764.
User-defined parameters may also be placed in the MSU using
UsrDefParam field of the parameter union in prm. In this case, the
nameOFparam field must indicate the user-defined parameter code,
and the usrDEFprm_FLG field must be initialized to
L_UsrDEFparameter.
User-defined parameters are only allowed as optional parameters.
RETURN VALUES
non-negative integer On success.
-1
Page 13 - 21
1-1600-1003-01
ERRORS
<EINVPARCOD>::The parameter name indicated in the nameOFparam field of prm is
unrecognized.
<EINVPARFMT>::The parameter contained within prm contains reserved values.
<EINVPARTYP>::The value specified in the typeOFparam field is unrecognized, or the parameter
indicated cannot be of the indicated type.
<EINVPARMSG>::The specified mandatory parameter is not allowed in the indicated message
type, or the specified mandatory parameter has already been placed in the message
signalling unit.
<ELASTFPAR>::All required fixed parameters for the message type indicated have been placed.
<EFPAREXIST>::The message type indicated requires at least one more fixed parameter.
<ELASTVPAR>::All required mandatory variable parameters for the message type indicated have
been placed.
<EVPAREXIST>::The message type indicated requires at least one more mandatory variable
parameter.
<ELASTOPAR>::There are no more optional parameters to be put. The user must issue the
isup_snd_msg() call.
<EEOPPUT>::EOP has already been put, when another isup_put_prm() occurs. The user must
issue the isup_snd_msg() call.
<EEOPNOOP>::Optional pointer is put, but no optional parameter is put, instead EOP follows.
The library has made optional pointer zero. The message may be sent out to the SS7
network as the error has been fixed by the ISUP API library. The user must issue the
isup_snd_msg() call.
SEE ALSO isup_get_prm(), isup_get_hdr(), isup_get_mtc_hdr(), isup_put_hdr(),

isup_snd_msg()
13.2.20
isup_reg()
Allows Call Control applications to register with the ISUP layer
so that they can send and receive protocol messages through the SS7 network.
Important: It is required that an application be registered with the Distributed7 platform
using the spm_open() and spm_bind() calls prior to calling this function.
When isup_reg() is implemented, it results in an implicit call to isup_reg_req() with the
isup_reg_req_t structure of the latter function populated as follows:
typedef struct {
word_t usertype; /* set to ISUP_CC */
Page 13 - 22
1-1600-1003-01

} isup_reg_req_t;
Important: Since isup_reg() provides no control over the regtype field setting,
isup_get_regtype() must be called in advance. isup_set_regtype() makes sure that the
current regtype field setting is accurate prior to calling the isup_reg() function for
registration. For more information about the meaning and exact use of the individual fields
listed above, refer to the man pages of the isup_reg_req() function.
isup_reg() function, results of this registration request are returned to the application in
the form an IPC message that contains an ISUP_ACTIVATE_CONF primitive. Upon
find out the results of the earlier registration attempt.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_reg(int fd, int sp, ipcaddr_t *addr, int grp);
fd
sp
addr
Identifies the IPC address of the call control application established
The grp field identifies the trunk group(s) that to which the application is
interested in registering.
RETURN VALUES
0
-1
On success.
On failure, and the errno variable is set to an appropriate value
ERRORS
SEE ALSO spm_open(), spm_bind(), isup_reg_req(), isup_reg_rsp(),
isup_mtc_reg(), isup_mtc_dereg(), isup_get_reg_type(), isup_set_reg_type(),
Page 13 - 23
1-1600-1003-01
isup_get_usr_type()
isup_dereg()
layer.
Allows Call Control applications to de-register with the ISUP
When isup_dereg() is implemented, it results in an implicit call to isup_dereg_req() with

the isup_dereg_req_t structure in the latter function populated as follows:
typedef struct {
word_t usertype; /* set to ISUP_CC */
} isup_dereg_req_t;
When an attempt is made by an application to de-register with the ISUP layer using the
isup_dereg() function, results of this de-registration request are returned to the application
in the form an IPC message that contains an ISUP_DEACTIVATE_CONF primitive.
Upon receipt of this message, applications are expected to call the isup_dereg_rsp()
function to find out the results of the earlier de-registration attempt.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_dereg(int fd, int sp, int grp);
fd
sp
addr
Identifies the IPC address of the call control application established
The grp field identifies the trunk group(s) that to which the application is
interested in registering.
RETURN VALUES
0
-1
On success.
On failure, and the errno variable is set to an appropriate value
ERRORS
Page 13 - 24
1-1600-1003-01
SEE ALSO spm_open(), spm_bind(), isup_reg_req(), isup_reg_rsp(),
isup_mtc_reg(), isup_mtc_dereg(), isup_get_reg_type(), isup_set_reg_type(),
isup_get_usr_type()
isup_reg_req()
Allows ISUP users, i.e., Call Control and maintenance users, to
register with the ISUP layer so that they can send and receive protocol messages through
the SS7 network.
Important: It is required that the user is registered with the Distributed7 platform using the
spm_open() and spm_bind() calls prior to calling this function.
Important: Before calling the isup_reg_req() function, all appropriate fields of the
isup_reg_req_t data structure must be populated.
The contents of the isup_reg_req_t structure is as follows:
typedef struct {
word_t trunkgrpid;
word_t usertype;
#define ISUP_CC
0
#define ISUP_MAINT 1
word_t regtype;
#define L_SOFTREG
#define L_HARDREG
0
1
word_t reserved;
dword_t inetaddr;
} isup_reg_req_t;
where trunkgrpid field identifies the trunk group(s) that the user is interested in using,
usertype field identifies the user category, i.e., Call Control or maintenance application,
regtype identifies so-called registration type, and inetaddr field identifies the IP address of
the host on which the isupd() daemon is running. The reserved field is not currently used.
Permissible values of trunkgrpid are in the [0, L_MAX_NUMBER_OF_TRKGROUPS 1] range. Alternatively, one can specify a trunkgrpid value of L_ALL_TRNKGRPS to
indicate that registration of the user should span all trunk groups currently configured.
Page 13 - 25
1-1600-1003-01
Important: The Distributed7 ISUP layer requires each trunk group to be used to have an
ISUP user registered to it. Otherwise, all protocol messages pertaining to such trunk groups
are discarded by the isupd() daemon. Thus, it is essential for all trunk groups to be used for
network message exchange to have an ISUP user registered to it.
Permissible values of usertype are ISUP_CC for Call Control applications and
ISUP_MAINT for maintenance applications.
Permissible values for regtype are L_SOFTREG or L_HARDREG.
If the regtype field is set to L_SOFTREG, isup_reg_req() fails if the indicated trunk
groups are already registered to by other ISUP users running on other hosts.
If the regtype is set to L_HARDREG, attempts made to register to a trunk group that is
already in use by another user on another host do not fail. Under these circumstances,
the local isupd() daemon initiates and sends an ISUP_RELEASE_TRUNK indication
to its peer on the remote host to request it to stop all events associated with the effected
trunks, and pass their control/ownership to itself. The remote isupd() daemon
subsequently passes the ISUP_RELEASE_TRUNK indication to its local users to
inform them that the indicated trunk(s) no longer belong to them, and that ownership of
the trunk(s) were passed on to another user on another host.
The inetaddr field is instrumental in identifying the isupd() daemon instance to
communicate through in a distributed product configuration. An inetaddr value of 0
specifies that the services of the isupd() daemon on the local host are to be used.
Specifying the inetaddr of a remote host, users can construct front-end/back-end
configurations where the user application runs on a back-end machine and the ISUP layer
as well as the rest of the Distributed7 stack runs on front-end machine(s).
isup_reg_req() function, results of this registration request are returned to the application
in the form an IPC message that contains an ISUP_ACTIVATE_CONF primitive. Upon
find out the results of the earlier registration attempt.
Important: For an ISUP user to register to multiple trunk groups, but not to all trunk groups
configured, it needs to invoke the isup_reg_req() function multiple times. There is no
inherent system limit to the number of successive isup_reg_req() calls a user can place.
However, each isup_reg_req() call results in a corresponding ISUP_ACTIVATE_CONF
primitive to be returned to the user in return, and it is the user's responsibility to check on
the results of each registration attempt, i.e., by calling the isup_reg_rsp() function each time
an ISUP_ACTIVATE_CONF primitive is received.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_reg_req(int fd, int sp, ipcaddr_t *addr, isup_reg_req_t *req);
fd
Page 13 - 26
1-1600-1003-01
sp
addr
req
Identifies the IPC address of the ISUP user established through an earlier
call to spm_bind(), and it allows the isupd() daemon to determine how to
address the user when sending messages to it.
Points to a user-space memory location that contains registration related
information.
RETURN VALUES
0
-1
On success.
ERRORS
<ETRNKINUSE>::Trunk group specified is already in use by another application.
<EMNTCOFF>::MNTCIND attribute associated with the trunk group specified is OFF.
SEE ALSO spm_open(), spm_bind(), spm_snd(), isup_reg_rsp(),

isup_dereg_req(), isup_dereg(), isup_mtc_dereg(), isup_snd_msg()
isup_reg_rsp()
Analyzes the results of the registration attempt placed earlier by
the isup_reg_req() function call.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_reg_rsp(int fd, ipcmsg_t *msg, int *grp);
fd
Identifies the file descriptor through which the earlier isup_reg_req() call
is placed.
msg
Points to an ipcmsg_t structure that contains the IPC message with the
ISUP_ACTIVATE_CONF primitive.
grp
Points to a user-space memory to which the number of the trunk group
associated with a particular registration attempt is returned.
RETURN VALUES
0
-1
On success.
Page 13 - 27
1-1600-1003-01
ERRORS
<ETRNKINUSE>::Trunk group specified is already in use by another application.
<EMNTCOFF>::MNTCIND attribute associated with the trunk group specified is OFF.
<EMAXUSR>::Multiple instances of specified application exist.
SEE ALSO spm_open(), spm_bind(), spm_snd(), isup_reg_rsp(), isup_dereg_rsp(),

isup_dereg(), isup_mtc_dereg(), isup_snd_msg()
isup_get_reg_type()
Allows application programmers to set and/or modify the user
registration type associated with an ISUP user, i.e., Call Control or maintenance
application.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_set_reg_type(int fd, int regtype);
fd
regtype
Specifies the desired user registration type. In this release of
Distributed7, an ISUP user can choose between two registration types:
L_SOFTREG
If the user registration type is set to L_SOFTREG and the user wishes
to register to a trunk that is already activated by another user on
another host, then the registration attempt fails. In some cases, this
may be undesirable outcome, i.e., ISUP user may wish to register to
an already activated trunk for recovery purposes.
L_HARDREG
If the user registration type is set to L_HARDREG, then attempts
made to register to a trunk that is already in use by another user on
another host do not fail. Under these circumstances, the local isupd()
daemon initiates and sends an ISUP_RELEASE_TRUNK indication
to its peer on the remote host to request it to stop all events associated
with the effected trunks and pass their control/ownership to itself.
The remoteisupd() subsequently passes the
ISUP_RELEASE_TRUNK indication to its local users to inform
them that the indicated trunk(s) no longer belong to them, and
ownership of the trunk(s) were passed on to another user on another
host.
Page 13 - 28
1-1600-1003-01
JAIN ISUP API Library
RETURN VALUES
0
-1
On success.
On failure, the errno variable is set to an appropriate value.
ERRORS
SEE ALSO isup_reg(), isup_mtc_reg(), isup_get_reg_type()

isup_snd_msg()
Sends an IPC message that contains the data for a message
signalling unit (MSU) to the isupd() daemon for subsequent delivery to the SS7 network.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_snd_msg(int fd, int sp, ipcaddr_t *addr, ipcmsg_t *msg);
fd
sp
Identifies the signalling point associated with the application as well as
the isupd() daemon and assumes a value in the [0, NSP -1] range.
addr
Points to user-space memory that contains the address of the calling
process in the ipcaddr_t format.
msg
Points to an ipcmsg_t structure that contains the IPC message to be sent.
RETURN VALUES
0
-1
On success.
ERRORS
spm_snd() function.
SEE ALSO spm_snd()
13.3

JAIN ISUP API is implemented based on JSR 17 JAINTM ISUP Specification Proposed
Final Draft dated November 30, 2001. Since there is not a generic class implementation
available for JAIN ISUP API yet, NewNet Communication Technologies, LLC
Page 13 - 29
1-1600-1003-01
implementation includes them as well. The following sections describe the major interfaces
defined by JAIN APIs.
13.3.1 SS7 Factory

The JAIN SS7 Factory is a singleton class by which JAIN SS7 applications can obtain a
proprietary (Peer, "a particular platform-specific implementation of a Java interface or
API") JAIN SS7 Object.
A Peer JAIN SS7 Object can be obtained from the JAIN SS7 Factory by:
instantiating a new Peer JAIN SS7 Object using the createSS7Object() method
selecting from the list of JAIN SS7 Objects returned by the getJainObjectList() method
The JAIN SS7 Factory utilizes a naming convention defined for each JAIN SS7 API to
identify the location of proprietary JAIN SS7 Objects.
Under this convention the lower-level package structure and classname of a Peer JAIN
SS7 Object is mandated by a convention defined within the JAIN SS7 API from which the
Object originates.
For example, within the JAIN ISUP API, the lower-level package structure and classname
of a proprietary implementation of javax.jain.ss7.isup.JainIsupStack interface must be
javax.jain.ss7.isup.JainIsupStackImpl
Under the JAIN naming convention, the upper-level package structure (pathname) can be
used to differentiate between proprietary implementations from different SS7 Vendors. The
pathname used by each SS7 Vendor must be the domain name assigned to the Vendor in
reverse order. For NewNet Communication Technologies, LLC this name is 'com.NewNet'.
It follows that a proprietary implementation of a JAIN SS7 Object can be located at:
'pathname'.'lower-level package structure and classname'
Where:
pathname = 'com.NewNet'
lower-level package structure and classname = mandated naming convention for the JAIN
SS7 Object in question
For example, javax.jain.ss7.isup.JainIsupStackImpl is the mandated naming convention for
javax.jain.ss7.isup.JainIsupStack
The resulting Peer JAIN SS7 Object would be located at:
com.NewNet. javax.jain.ss7.isup.JainIsupStackImp
Because the space of domain names is managed, this scheme ensures that collisions between
two different vendor's implementations will not happen.
The pathname may be set using the setPathName() method. This allows a JAIN application
to switch between different Vendor implementations, as well as providing the capability to
use the default or current pathname.
The JAIN SS7 Factory is a Singleton class. This means that there will only be one instance
of the class with a global point of access to it. The single instance of the JAIN SS7 Factory
can be obtained using the getInstance() method. In this way, the JAIN SS7 Factory acts a
single point for obtaining JAIN SS7 Objects.
Page 13 - 30
1-1600-1003-01
13.3.2 JAIN Stack Interface

This interface defines methods for representing a proprietary JAIN ISUP protocol stack
implementation. This interface and the Provider interface is provided by NewNet
Communication Technologies, LLC. NewNet protocol stack creates an object that
implements this interface to control the creation/deletion of proprietary Provider and the
attaching/detaching of that Provider to this Stack implementation. Application creates a
StackImpl object by calling JainSS7Factory.createJainSS7Object method. A Stack
represents a single point code.
13.3.3 JAIN Provider Interface

This interface represents the JAIN layer which interfaces directly with a proprietary
(Distributed7) implementation of the SS7 stack. Any object that interfaces between a JAIN
application and an SS7 stack must implement this interface. This interface defines the
methods that will be used to send and receive Events by any registered User application
implementing the Jain Listener interface. An Event is java event version of protocol
messages and other interface related information exchanged between the Provider and the
Listener.
Henceforth, the object implementing the Jain Listener and Jain Provider interface will be
referred to as Jain Listener object and Jain Provider object. Jain Listener object registers
with a Jain Provider object for receiving Events. At the time of registration, the Listener
object supplies a User Address to the Provider object.
A Jain Provider object encapsulates the received protocol messages from Distributed7 stack
into java events and passes this information to the Listener. One or more Provider objects
can exist on a single SS7 specific layer (Figure 13-4).
StackStack
Stack
Provider
Listener
Listener
Provider
Listener
Listener
Listener
Figure 13-4: Stack-Provider-Listener Association
Page 13 - 31
1-1600-1003-01
The implementation of the JAIN ISUP Provider interface provides the ability to
communicate with the ISUP layer of the Distributed7 stack. The Provider is responsible for
keeping and maintaining a list of registered JAIN ISUP Listeners. There can be multiple
providers and one listener can register to multiple providers by using different user
addresses.
JNI (Java Native Interface) is used to make native calls from Java side and calling Java
methods from native side.
A JAIN ISUP User-Address consists of a destination point code, a network indicator for
indicating whether the point code belongs to national or international network, and a set of
CICs. A JainIsupListener object can add more User-Addresses by invoking the
addIsupListener method, and can remove User-Addresses by invoking the
removeIsupListener method (Figure 13-5). The ListenerNotRegisteredException is thrown
if the removeIsupListener method is invoked on a specific JAIN ISUP Listener, which is
not registered with that JAIN ISUP Provider.
User Address
(1,1,0,1,0)
Listener
User Address
(2,1,0,1,0)
Provider 1
Provider 2
ISUP Layer
ISUP Layer
Distributed7
Distributed7
Figure 13-5: Multiple Provider Architecture

A JainIsupListener calls the sendIsupEvent method on the JainIsupProvider to send an
ISUP message to the network. The API implementation supports the exchange of ISUP
messages, ISUP specific timeout indications and network element status indications
between the JAIN ISUP Provider and the JAIN ISUP Listener. Each message is
encapsulated individually in an event. When a received ISUP message arrives at the
Distributed7 stack, the JAIN ISUP Provider forwards the ISUP message as a JAIN ISUP
Event to the Listener that has registered for that User-Address. Events that are not associated
with a User-Address are discarded by the JAIN ISUP Provider. Further information on JAIN
ISUP API can be found at http://www.jcp.org/aboutJava/communityprocess/first/jsr017.
Sample JainIsupListener implementation is located under the $EBSHOME/access/sample/
jain/isup directory. Distributed7 JAIN ISUP API requires Java version 1.4 or higher.
JAIN mandates the naming convention for the lower level package structure and class name
of the proprietary implementation. Package structures for ISUP are as follows:
Page 13 - 32
1-1600-1003-01
javax.jain
javax.jain.ss7
javax.jain.ss7.isup
javax.jain.ss7.isup.ansi
javax.jain.ss7.isup.itu
com.NewNet.javax.jain.ss7.isup
Packages starting with com.NewNet are for the proprietary implementation.
JainIsupListener application requires the JainIsup.so library, which is located under the
$EBSHOME/access/lib directory. To make use of this library the LD_LIBRARY_PATH
environment variable needs to be set on Solaris systems. The jar file for generic classes is
named as JainIsupGeneric.jar. The NewNet Communication Technologies proprietary
implementation is named as JainIsupNewNet.jar. Both of these jar files are located under
the $EBSHOME/access/lib directory. The CLASSPATH environment variable should be
set to include the directory path that contains the jar files.
Page 13 - 33
1-1600-1003-01
Page 13 - 34
1-1600-1003-01
Chapter 14:
ISUP AoC API Library
ISUP Advice of Charge

(AoC) API Library

This chapter describes the Charging-Application Service Element (ASE) and Application
Transport Mechanism-Application Service Element (ASE) Application Programming
Interface (API) library calls for Distributed7 Advice of Charge (AoC) software products.
More information can be found in the Distributed7 Application Development Manual.
14.2 ISUP AoC API Library

ISUP support of AoC consists of two functional modules for the transfer of AoC application
information over ISUP. The main functional modules are shown below, and are described in
Section 14.2.1 and Section 14.2.2:
Charging-Application Service Element (ASE) Module
This modules tasks include understanding and encoding charging-related information.
Application Transport Mechanism Module
This module provides a generic mechanism to transport application messages over
ISUP.
A sample ISUP-AoC Call Control Interface library is provided to aid the Call Control in the
packing and unpacking of AoC-related information in the Application Transport Message
and Pre-Release Information messages. The SPM library (libspm.a) and the ISUP-AoC Call
Control Library (libisupaoc.a) must be linked with the Call Control Application.
Sample source code files (see list below) are provided to demonstrate the use of
Distributed7 ISUP-AoC literals and functions. They should be compiled with the
MAKEFILE in the $EBSHOME/access/sample/isupaoc directory. After they are compiled,
the executables are located in the $EBSHOME/access/demo directory.
Makefile
CCsim.c
Dsim_api.c
Esim_api.c
RDparam_ansi.c
RDparam_itu.c
parseTBL.c
Templates_itu
Page 14 - 1
1-1600-1003-01
Templates_itu.0
Templates_itu.1
that allow the user to invoke the UNIX standard man(1) utility to review the information
Important: Distributed7 1.2. ISUP AoC API Library is multi-thread (MT) Safe, and can
be used with multi-threaded application programs. When compiling multi-threaded applications, the -D_REENTRANT flag must be specified.
The Charging-Application Service Element (ASE) is an ATM-user Application Service
Element for the AoC application. It provides functionality for the Basic Encoding Rule
(BER) encoding and decoding of AoC-related information. The BER-encoded information
is a sequence of octets.
The Call Control passes AoC application information to the Charging-ASE module using
the interface structures defined by the isupaoc library in the isup_aoc_crgcallcont.h and
isup_aoc_crgtypes.h files. This must be included for compilers to check the usage of the
function calls, as shown below:
#include <isup_aoc_crgcallcont.h>
#include <isup_aoc_crgtypes.h>
MESSAGES
Seven messages are defined for the Charging-ASE:
CRGT-CURRENCY Charging Tariff Information in Currency format
CRGT-PULSE Charging Tariff Information in Pulse format
AOCRG-CURRENCY Add-on Charging Information in Currency format
AOCRG-PULSE Add-on Charge Information in Pulse format
CRGA Charging Information Acknowledgement information
START Start Charging information
STOP Stop Charging Information
14.2.3.1 isup_aoc_crgase_encode()
isup_aoc_crgase_encode()
This function encodes AoC charging message
information. The function takes the AoC charging message information as input, and
produces encapsulated BER-encoded sequence of bytes as output.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_aoc_crgase_encode(U_ChargingMsg_t * crg_ msg, char * buffer, int buffer
size);
Page 14 - 2
1-1600-1003-01
crg_msg
buffer
buffer size
The AoC charging message.

The BER-encoded sequence of bytes corresponding to the charging
message is returned in this buffer. The maximum size of the BERencoded sequence of bytes is 2K.
The size of the buffer provide.
RETURN VALUES
0, >0
-0
On success; length of encoded octet string.

On failure; errno is set to one of the following errors.
ERRORS
<E_INVALID_MSGTYP>::The message type specified is invalid.
<E_INSUFFICIENT_BUFFER_SIZE>::The buffer provided is not sufficient to contain the BERencoded sequence of bytes.
<E_INVALID_NUMBER_OF_NETWORK_OPERS>::The number of network operators
specified is outside the valid range [0...6].
<E_INVALID_NUMBER_OF_SUBTARIFFS>::The number of subtariffs specified is outside the
valid range [0...4].
<E_INVALID_TARIFF_SWITCH_OVER_TIME>::Tariff Switch Over Time is outside the valid
range [0...96].
<E_INVALID_CURRENCY_FACTOR>::Currency factor is outside the valid range [0...999999].
<E_INVALID_CURRENCY_SCALE>::Currency scale value is outside the valid range [-7...3].
<E_INVALID_TARIFF_DURATION>::Tariff Duration Value is outside the valid range
[0...36000].
<E_INVALID_CHARGE UNIT_TIME_INTERVAL>::Charge Unit Time Interval is outside the
<E_INVALID_CURRENCYUNIT_TYPE>::Currency Unit Type is outside the valid range
[0...27].
<E_INVALID_SIZE_OF_EXTENSION_FIELD>::Size of ASN.1 extension field is too large.
SEE ALSO isup_aoc_crgase_decode(), isup_aoc_crgase_displ_error()

isup_aoc_crgase_decode()
This function decodes AoC charging message
information, taking the BER-encoded sequence of bytes as input and producing the AoC
charging message information as the output.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_aoc_crgase_decode(char * encoded_ msg, int msg_size, U_ChargingMsg_t *
msg);
encoded_msg The BER-encoded sequence of bytes that is to be decoded.
Page 14 - 3
1-1600-1003-01
msg_size
msg
The size of the BER-encoded sequence of bytes corresponding to the

charging message. The maximum size of the BER-encoded sequence of
bytes is 2K.
The AoC charging message into which the decoded information is
written.
RETURN VALUES
0, >0
-0
On success; length of BER-encoded message used.

ERRORS
<E_INVALID_MSGTYP>::The message type specified is invalid.
<E_INSUFFICIENT_BUFFER_SIZE>::The buffer provided is not sufficient to contain the BERencoded sequence of bytes.
<E_INVALID_NUMBER_OF_NETWORK_OPERS>::The number of network operators
specified is outside the valid range [0...6].
<E_INVALID_NUMBER_OF_SUBTARIFFS>::The number of subtariffs specified is outside the
<E_INVALID_TARIFF_SWITCH_OVER_TIME>::Tariff Switch Over Time is outside the valid
range [0...96].
<E_INVALID_CURRENCY_FACTOR>::Currency factor is outside the valid range [0...999999].
<E_INVALID_CURRENCY_SCALE>::Currency scale value is outside the valid range [-7...3].
<E_INVALID_TARIFF_DURATION>::Tariff Duration Value is outside the valid range
[0...36000].
<E_INVALID_CHARGE UNIT_TIME_INTERVAL>::Charge Unit Time Interval is outside the
<E_INVALID_CURRENCYUNIT_TYPE>::Currency Unit Type is outside the valid range
[0...27].
<E_INVALID_CONSTRUCTED TYPE>::A constructed type has been wrongly constructed.
Unable to decode.
<TAG_VALUE_TOO_LONG>::Encoded ASN.1 TAG value is too large. Unable to decode.
<LEN_VALUE_TOO_LONG>::Encoded ASN.1 LENGTH value is too large. Unable to decode.
<INT_VALUE_TOO_LONG>::Encoded ASN.1 INT value is too large. Unable to decode.
<ENUM_VALUE_TOO_LONG>::Encoded ASN.1 ENUM value is too large. Unable to decode.
<BITSTRING_TOO_LONG>::Encoded ASN.1 BITSTRING is too long (greater than 8 bits).
Unable to decode.
<BITSTRING_TOO_SHORT>::Encoded ASN.1 BITSTRING is too short. Unable to decode.
<OID_SUBFIELD_VALUE_TOO_LONG>::Encoded ASN.1 OID type subfield value is too
large. Unable to decode.
<OID_VALUE_INVALID_LENGTH>::Encoded ASN.1 OID type is improper. Unable to decode.
<E_INVALID_SIZE_OF_EXTENSION_FIELD>::Size of ASN.1 extension field is too large.
Unable to decode.
Page 14 - 4
1-1600-1003-01
SEE ALSO isup_aoc_crgase_encode(), isup_aoc_crgase_displ_error()

isup_aoc_crgase_displ_error()
This function helps debug errors during decoding.
The isup_aoc_crgase_displ_error() function returns detailed information by printing to
screen information of the nested levels ASN.1 structures that indicate the exact point of
error.
MT-LEVEL
Not MT-Safe
Notice: isup_aoc_crgase_displ_error() is for offline debugging only. It uses global data
and is not, therefore, MT-safe.
SYNOPSIS
int isup_aoc_crgase_displ_error(void);
RETURN VALUES
0
Always returns zero.
SEE ALSO isup_aoc_crgase_encode(), isup_aoc_crgase_decode()

The Application Transport Mechanism-ASE module supports wrapping ATM-user
application data into one or more Application Transport Parameters (APPs) through
segmentation. These APPs can then be transported through ISUP messages. On the
incoming side, ATM-ASE supports analyzing APPs, checking them for Charging-ASEspecific APPs, and re-assembling APP segments to recover the ATM-user application data.
During wrapping, the BER-encoded AoC application information can be segmented into a
maximum of ten (10) APPs. The size of each parameter is provided by the user. During
unwrapping, the segmented APPs are re-assembled to form the original BER message.
The Call Control passes the BER-encoded AoC application information to the ATM-ASE
module using the interface structures defined by isupaoc library in the
isup_aoc_aptmcallcont.h. This must be included for compilers to check the usage of the
function calls, as shown below:
#include <isup_aoc_aptmcallcont.h>
14.2.3.1 isup_aoc_apmase_analyse()
isup_aoc_apmase_analyse() Function analyzes the incoming Application Transport
(APP) parameter to determine the Application Context Identifier (ACI). The ACI is
encoded within the APP and identifies the APM-user to which the parameter belongs. If
the APP belongs to Charging-ASE, then the ACI is set to a value of 3, i.e., the value of the
Charging-ASE.
MT-LEVEL
MT-Safe
Page 14 - 5
1-1600-1003-01
SYNOPSIS
int isup_aoc_apmase_analyse(isup_prm_t *app_param, int *app_context_id);
app_param
The incoming Application Transport (APP) parameter.
app_context_id The Application Context ID (ACI) value obtained from the APP.
RETURN VALUES
0
<0
On success.
On failure; the return value is negative, and errno is set to one of the
following errors.
ERRORS
<EAPM_PARAM_NOT_APP>::The parameter is not APP parameter.
<EAPM_APP_PARAM_TOO_SHORT>::The APP parameter is too short.
SEE ALSO isup_aoc_apmase_reset(), isup_aoc_apmase_unwrap(),

isup_aoc_apmase_wrap()
isup_aoc_apmase_reset()
Function resets the fields of the U_ApmUserMsg_t
structure. This function must be called before using the U_ApmUserMsg_t structure for
the isup_aoc_apmase_wrap and isup_aoc_apmase_unwrap API functions.
MT-LEVEL
MT-Safe
SYNOPSIS
int isup_aoc_apmase_reset(U_ApmUserMsg_t *crg_msg);
crg_msg
The U_ApmUserMsg_t structure to be reset.
RETURN VALUES
0
-1
On success.
On failure; cause of error.
SEE ALSO isup_aoc_apmase_analyse(), isup_aoc_apmase_unwrap(),

Function segments the given APM-user ASE information
and wraps the segments to form APPs. This API takes the APM-user information in the
U_ApmUserMsg_t structure, along with the segmentation information, and creates one or
more APPs in the U_appParamList_t structure.
MT-LEVEL
MT-Safe
Page 14 - 6
1-1600-1003-01
SYNOPSIS
int isup_aoc_apmase_wrap(U_ApmUserMsg_t *crg_msg, U_appParamList_t
*app_params);
app_params
The list of APPs.
crg_msg
The APM-user information to be passed for wrapping. The fields to be
filled are as follows:
application_context_information: the ACI value [0...3]
atii: the ATI indicators/bit fields
apmUserMsg_size: the size of the APM-user message
apmUserMsg_contents[]: the data of the APM-user message
segmentationLocalRef: the SLR for the APM-user message
no_of_segments: the number of segments into which the APM-user
message has to be partitioned
segment_size[]: the size of each segment
RETURN VALUES
0, >0
<0
On success; number of APPs created.

ERRORS
<EAPM_MSG_TOO_LONG>::The APM-user message is too long.
<EAPM_INVALID_NUMBER_OF_SEGMENTS>::The number of segments specified is invalid.
<EAPM_INVALID_SEGMENT_SIZE>::The size of the segment specified is invalid.
<EAPM_IMPROPER_SEGMENTATION>::The APM-user message is improperly segmented.
<EAPM_INVALID_ACI_VALUE>::Invalid ACI value.
<EAPM_INVALID_SLR_VALUE>::Invalid SLR value or SLR value out of range [0...127].
SEE ALSO isup_aoc_apmase_analyse(), isup_aoc_apmase_reset(),

isup_aoc_apmase_unwrap()
isup_aoc_apmase_unwrap() Function unwraps an APP and reassembles the segments
to get the APM-user information. If the received APP is not the final segment of the
APM-user message the APM-user information extracted from the APP is stored within the
U_ApmUserMsg_t structure. To properly append all subsequent APPs until the complete
APM-user message is received, this API is run with the same U_ApmUserMsg_t
structure.
MT-LEVEL
MT-Safe
Page 14 - 7
1-1600-1003-01
SYNOPSIS
int isup_aoc_apmase_unwrap(isup_prm_t *app_param, U_ApmUserMsg_t
*crg_msg);
app_param
The incoming APP to be unwrapped.
crg_msg
The APM-user information structure that is filled up by the API. The
fields filled on return are as follows:
application_context_information: the ACI value [0...3]
atii: the ATI indicators/bit fields
apmUserMsg_size: the size of the APM-user message
apmUserMsg_contents[]: the data of the APM-user message
segmentationLocalRef: the SLR for the APM-user message
no_of_segments: the number of segments into which the APM-user
message has to be partitioned
segment_size[]: the size of each segment
RETURN VALUES
0, >0
<0
On success; number of segments to follow.

ERRORS
<EAPM_MSG_TOO_LONG>::The APM-user message is too long.
<EAPM_INVALID_NUMBER_OF_SEGMENTS>::The number of segments specified is invalid.
<EAPM_INVALID_SEGMENT_SIZE>::The size of the segment specified is invalid.
<EAPM_IMPROPER_SEGMENTATION>::The APM-user message is improperly segmented.
<EAPM_APP_PARAM_TOO_SHORT>::The APP parameter is too short.
<EAPM_APP_PARAM_TOO_LONG>::The APP parameter is too long.
<EAPM_APP_INVALID_EXT_BIT>::Invalid use of extension bit.
<EAPM_INCOMPLETE_PREV_MSG>::New message arrived before all of the segments of the
previous message are received.
<EAPM_UNEXPECTED_SEGMENT>::Unexpected segment received.
<EAPM_APMUSER_MSG_OVERFLOW>::APM-user message is too long, greater than 2K
octets.
<EAPM_INVALID_SEGMENT_NUMBER>::Segment number invalid.
<EAPM_INVALID_ACI_VALUE>::Invalid ACI value.
<EAPM_INVALID_SLR_VALUE>::Invalid SLR value or SLR value out of range [0...127].
SEE ALSO isup_aoc_apmase_analyse(), isup_aoc_apmase_reset(),

Page 14 - 8
1-1600-1003-01
Page 14 - 9
1-1600-1003-01
Page 14 - 10
1-1600-1003-01
Chapter 15:
DKM API Library
DKM API Library

This chapter provides the Distributed Kernel Memory (DKM) Application Programming
15.2 DKM API Library

The DKM library is used to create and manage shared memory segments under a distributed
computing environment. Every library call is described in detail on the following pages,
including information on input parameters, declarations, and return values. These function
calls require the following header file to be included in the application:
#include <dkm.h>
Page 15 - 1
1-1600-1003-01
DKM API Library
15.2.1 dkm_cancel()
DESCRIPTION
dkm_cancel()
This function is used to allows a kernel thread to cancel a pending
asynchronous Distributed Kernel Memory (DKM) lock request.
SYNOPSIS
int dkm_cancel(int dkmid , int timerid , int * reason );
dkmid
This argument identifies the DKM segment of interest and should be
obtained through a previous call to the dkm_get() function.
timerid
This argument is instrumental in identifying the pending asynchronous
lock request and should be obtained through a previous call to the
dkm_schedule() function.
The timerid argument in this function is of type integer and not of type
dkmtimer_t. These two types are equal to each other and may be used
interchangeably for all practical purposes.
RETURN VALUES
0
-1
On success
On failure; reason is set to indicate the error.
ERRORS
<E_DKM_INVAL> Invalid function argument is specified.
<E_DKM_NOENT> Unable to locate the DKM segment and/or timer
identifier specified.
<E_DKM_ACCES> Request is denied because the DKM multiplexer on the
local host is not in a state to service its users,
possibly because the system is being initialized or shut
down.
<E_DKM_PERM> Request is denied because the lock specified is in
the process of being acquired.
SEE ALSO dkmd, dkm_schedule(), dkm_unlock(), dkm_destroy(), dkm_shrink()
Page 15 - 2
1-1600-1003-01
DKM API Library
15.2.2 dkm_destroy()
DESCRIPTION
dkm_destroy()
Allows a kernel thread to destroy an existing Distributed Kernel
Memory (DKM) segment and remove the segment identifier associated with it from the
system. If the kernel-space memory for the segment is allocated by the DKM freamework,
then destroying the segment removes the segment identifier and de-allocates the dynamic
memory that the system previously assigned.
When a DKM segment is destroyed, all segment extensions are automatically deleted
from the system. Locks associated with the segment and/or its extensions are also deleted
from the system.
SYNOPSIS
int dkm_destroy(int dkmid , int flags , int * reason );
dkmid
This argument identifies the DKM segment and is obtained through a
previous call to the dkm_get() function.
flags
This argument can be constructed by ORing flags from the following
list:
DKM_WAIT (default option)
Suspend running the calling thread until the destroy operation is
complete and all local copies of the DKM segment specified are
removed. This argument cannot be used in conjunction with
DKM_NOWAIT.
DKM_NOWAIT
Do not wait for completion of the destroy operation and release the
calling thread immediately after conducting a basic set of sanity
checks to make sure that the DKM segment specified exists. This
argument cannot be used in conjunction with DKM_WAIT.
DKM_LOCALONLY
Destroy local copy of the DKM segment, i.e., do not destroy
replicated copies of the segment on remote hosts. When all local
copies of a segment are destroyed, the segment identifier is
automatically removed from the system.
DKM_TRIGGER
Trigger an M_DKM event upon successful deletion of the segment.
Note that if the DKM_LOCALONLY flag is also specified, then the
M_DKM event is only triggered on the local host.
RETURN VALUES
0
-1
On success.
Page 15 - 3
1-1600-1003-01
DKM API Library
ERRORS
On failure, the field pointed to by the reason argument will be set to one of the following:
<E_DKM_NOSR> Unable to fulfill user request due to a failure in
kernel-space message block allocation. Message blocks are
allocated by the DKM API library to relay user requests to
the local DKM multiplexer or establish communication with
DKM multiplexers on remote hosts.
<E_DKM_NOENT> Unable to locate the DKM segment specified.
<E_DKM_AGAIN> All local DKM resources are currently in use. Try
again later.
<E_DKM_BADMSG> An invalid and/or corrupted response was received
from the local DKM multiplexer.
<E_DKM_NOMEM> Unable to fulfill user request due to a failure in
kernel-space memory allocation. Note that the DKM
multiplexer on each host allocates various pieces of
kernel-space memory to store information about pending
user/system requests, segments allocated, extensions made,
locks acquired, etc.
<E_DKM_ACCES> Request is denied because the DKM multiplexer on
the local host is not in a state to service its users,
down.
<E_DKM_COMM> A communication error occurred while the DKM
multiplexer on the local host was in the process of
sending messages to its peers located on remote hosts.
SEE ALSO dkmd, dkm_rm, dkm_get(), dkm_shrink(), dkm_unlock(), dkm_cancel()
Page 15 - 4
1-1600-1003-01
DKM API Library
15.2.3 dkm_extend()
DESCRIPTION
dkm_extend()
This function allows a kernel thread to make dynamic extensions
to an existing Distributed Kernel Memory (DKM) segment.
SYNOPSIS
int dkm_extend(int dkmid , size_t size , dkmopts_t * opts , int flags ,
dkmextinfo_t * extinfo , int * reason );
dkmid
size
This argument specifies the actual size (in terms of bytes) of kernel-space
memory to be allocated for the extension use.
opts
This argument is of type dkmopts_t (which is defined in the <dkm.h>
header file) and is used to supply additional information to the system
about the extension to be created (as in the case of creating the segment).
The elements of the dkmopts_t data structure are as follows:
typedef struct {
dword_t
int
} dkmopts_t;
blksize;
wrbywho;
Where the blksize field specifies (in terms of bytes) the size of the data
blocks comprising the DKM segment extension and the wrbywho field
specifies the planned method of read-write access to the contents of the
extension. Currently, the two permissible methods of access are
DKM_WRITEBYALL and DKM_WRITEBYONE
DKM_WRITEBYALL Read-write access to the data contained in the
segment extension is permitted only after acquiring a "global" readwrite lock across the effected region of the extension. This translates
to the fact that only one kernel thread (across all hosts within the
network) will be allowed to manipulate the data contained in the
extension. During this manipulation no other thread can access this
data even for read-only purposes.
The DKM_WRITEBYALL access method should be used when the
data within a DKM segment extension is expected to be manipulated
in a concurrent manner by multiple kernel threads executing on
different hosts, as opposed to threads executing on a specified host.
DKM_WRITEBYONE Kernel threads executing on different hosts
are allowed to acquire "local" read-write locks across nonoverlapping regions of the segment extension concurrently. Thus,
while a region of the extension is locked for read-write purposes on a
specified host, kernel threads executing on other hosts will still be
allowed to access replicated copies of this data in read-only mode.
Note that the copy of the extension being accessed for read-only
Page 15 - 5
1-1600-1003-01
flags
DKM API Library
purposes may differ from the copy of the extension being

manipulated; however, the integrity of the data is guaranteed by the
system throughout each read/write operation.
The DKM_WRITEBYONE access method should be used when the
by kernel threads executing on a specified host, as opposed to threads
executing on different hosts.
For "record-based" kernel applications where the data is stored in a DKM
segment and/or segment extension, and can be viewed as a collection of
records, the use of this argument is essential, as it allows the user to
specify the exact size of each record and the planned method of write
access to these records, whether local read-write access to the data should
be permitted or not. In all other cases, the use of the opts argument is
optional. If a NULL value of the opts argument is specified, the settings
associated with the DKM segment are considered to be valid for the
extension to be made as well.
This argument can be constructed by OR-ing flags from the following
list:
DKM_LOCALONLY - Destroy local copy of the DKM segment (do
not destroy replicated copies of the segment on remote hosts).
DKM_TRIGGER - Trigger an M_DKM event upon successful
creation of the extension specified.
The contents of a DKM segment extension will be initialized to all
zeros by the system.
RETURN VALUES
0
-1
On success. Information about the extension made, i.e., extension

identifier, starting address of the extension, is returned to the calling
thread via the extinfo argument that is of type dkmextinfo_t
On Failure; reason is set to indicate the error.
ERRORS
again later.
<E_DKM_BADMSG> An invalid and/or corrupted response has been
received from the local DKM multiplexer.
Page 15 - 6
1-1600-1003-01
DKM API Library

<E_DKM_NOSPC> Failed to allocate kernel-space memory associated
with the extension on one or more hosts.
down.
<E_DKM_COMM> A communication error has occurred while the DKM
SEE ALSO dkmd, dkm_get(), dkm_shrink(), dkm_lock(), dkm_schedule(),

dkm_query(), dkm_getlist()
Page 15 - 7
1-1600-1003-01
DKM API Library
15.2.4 dkm_get()
DESCRIPTION
dkm_get()
Allows a kernel thread to create a new Distributed Kernel
Memory (DKM) segment or obtain access to an existing DKM segment.
A DKM segment consists of replicated copies of kernel-space memory allocated, either
statically or dynamically, on the individual host machines comprising a distributed
Distributed7 environment. Kernel threads executing on the individual hosts can share
information with each other by reading/writing data through local copies of a DKM
segment. To prevent inconsistencies and/or collisions when reading/writing through a
DKM segment, kernel threads must always use explicit synchronization variables (read/
write locks) when reading/writing data through local copies of the segment.
A kernel thread can instantiate a DKM segment in one of two different ways:
it may pre-allocate the kernel-space for the DKM segment privately and request from
the system that this space be treated as a DKM segment from now on,
it may request from the system to allocate the kernel-space memory for the segment
dynamically.
In the former case, the memory space may have been allocated either statically or
dynamically. It is important to note that the memory allocation is performed by the calling
thread in advance (prior to invoking the dkm_get() function call). In the latter case,
memory allocation is fully dynamic and is performed by the DKM framework on behalf of
the calling thread.
DKM users can use information regarding number of extensions associated with the
segment (returned within the extno field of the data structure pointed to by the info
argument) to find out if the DKM segment specified has just been created or not. An extno
value of -1 indicates that the segment specified has just been created.
SYNOPSIS
int dkm_get(key_t key , size_t size , dkmopts_t * opts , int flags , dkminfo_t * info
, int * reason);
key
Identifies an existing distributed kernel memory (DKM) segment.
size
Specifies the actual size (in terms of bytes) of kernel-space memory to be
allocated for the DKM segment, whether it is pre-allocated or not. Note
that if the kernel-space memory for the segment has been pre-allocated,
the starting address of the segment must be provided as part of the
dkminfo_t data structure pointed to by the info argument.
opts
This argument is of type dkmopts_t (which is defined in the <dkm.h>
header file) and is used to supply additional information to the system
about the extension to be created (as in the case of creating the segment).
The elements of the dkmopts_t data structure are as follows:
typedef struct {
dword_t blksize;
Page 15 - 8
1-1600-1003-01
DKM API Library

int
wrbywho;
} dkmopts_t;
flags
Where the blksize field specifies (in terms of bytes) the size of the data
blocks comprising the DKM segment extension and the wrbywho field
specifies the planned method of read-write access to the contents of the
extension. Currently, the two permissible methods of access are
DKM_WRITEBYALL and DKM_WRITEBYONE
DKM_WRITEBYALL Read-write access to the data contained in the
segment extension is permitted only after acquiring a "global" readwrite lock across the effected region of the extension. This translates
to the fact that only one kernel thread (across all hosts within the
network) will be allowed manipulate the data contained in the
extension and during this manipulation no other thread can access
this data, even for read-only purposes.
The DKM_WRITEBYALL access method should be used when the
in a concurrent manner by multiple kernel threads executing on
different hosts (as opposed to threads executing on a specified host).
DKM_WRITEBYONE Kernel threads executing on different hosts
are allowed to acquire "local" read-write locks across nonoverlapping regions of the segment extension concurrently. Thus,
while a region of the extension is locked for read-write purposes on a
specified host, kernel threads executing on other hosts will still be
allowed to access replicated copies of this data in read-only mode.
Note that the copy of the extension being accessed for read-only
purposes may differ from the copy of the extension being
manipulated; however, the integrity of the data is guaranteed by the
system throughout each read/write operation.
The DKM_WRITEBYONE access method should be used when the
by kernel threads executing on a specified host (as opposed to threads
executing on different hosts).
For "record-based" kernel applications, where the data is stored in a
DKM segment and/or segment extension, and can be viewed as a
collection of records, the use of this argument is essential as it allows the
user to specify the exact size of each record and the planned method of
write access to these records (whether local read-write access to the data
should be permitted or not). In all other cases, the use of opts argument is
optional. If a NULL value of opts argument is specified, the settings
associated with the DKM segment are considered to be valid for the
extension to be made as well.
list:
Page 15 - 9
1-1600-1003-01
DKM API Library
DKM_CREATE - Create segment specified if it does not exist. The

contents of a DKM segment that is just created will be initialized to
all zeros by the system. If a DKM segment identifier already exists
for the key specified, no data initialization will take place.
DKM_ALLOC - Allocate kernel-space memory for the segment
dynamically. This option should be specified unless the kernel-space
memory for the segment has been pre-allocated. In the latter case, the
starting address information must be provided as part of the info
argument.
DKM_LOCALONLY - Create segment on the local host only (do not
allocate kernel-space memory for the segment on remote hosts). This
option is meaningful only when it is used in conjunction with the
DKM_CREATE flag.
DKM_EXCLUSIVE - Fail if the segment specified already exists.
This option is meaningful only when it is used in conjunction with the
DKM_CREATE flag.
creation of the segment specified. If the segment already exists, no
event will be triggered by the system.
RETURN VALUES
0
-1
On success. Information about the segment made, i.e., segment identifier,

starting address of the segment, number of segment extensions, is
returned to the calling thread by the info argument that is of type
dkminfo_t
On Failure; reason is set to indicate the error.
ERRORS
<E_DKM_EXIST> A DKM segment identifier already exists for key but
(flags DKM_CREATE) and (flags DKM_EXCLUSIVE) are both
true.
<E_DKM_NOENT> A DKM segment identifier does not exist for key and
(flags DKM_CREATE) is false.
again later.
Page 15 - 10
1-1600-1003-01
DKM API Library

<E_DKM_NOSPC> Failed to allocate kernel-space memory associated
with the segment on one or more hosts and (flags
DKM_ALLOC) is true.
down.
SEE ALSO dkmd, dkm_destroy(), dkm_extend(), dkm_lock(), dkm_schedule(),

dkm_query()
15.2.5 dkm_gethostaddr()
DESCRIPTION
dkm_gethostaddr()
Allows a kernel thread to retrieve the Internet Protocol (IP)
address associated with a specified host. The hostid argument is instrumental in
identifying the host via its logical host identifier.
The so-called logical host identifiers are initialized by the DKM multiplexer at start-up
time and are guaranteed not to change until the dkmd daemon processes across the entire
network are terminated.
SYNOPSIS
dword_t dkm_gethostaddr (int hostid, int * reason);
RETURN VALUES
int
-1
On success. An unsigned long value which represents the IP address of

the host specified is returned.
ERRORS
down.
Page 15 - 11
1-1600-1003-01
DKM API Library
SEE ALSO dkmd, dkm_list, dkm_gethostid()
15.2.6 dkm_gethostid()
DESCRIPTION
dkm_gethostid()
Allows a kernel thread to retrieve the logical host number
associated with a specified host. The inetaddr argument is instrumental in identifying the
host by its Internet Protocol (IP) address. An inetaddr value of 0 is interpreted as the local
host.
The so-called logical host identifiers are initialized by the DKM multiplexer at start-up
time and are guaranteed not to change until the dkmd daemon processes across the entire
network are terminated.
SYNOPSIS
int dkm_gethostid(dword_t inetaddr , int * reason );
RETURN VALUES
int
-1
On success. A non-negative integer represents the "logical host number"

assigned to the host specified. This value is guaranteed to be within the
[DKM_HOSTID_MIN, DKM_HOSTID_MAX] range at all times.
ERRORS
On failure, the field pointed to by the reason argument will be set to one of the following:
<E_DKM_NOENT> Unable to locate the host specified.
down.
SEE ALSO dkmd, dkm_list
Page 15 - 12
1-1600-1003-01
DKM API Library
15.2.7 dkm_getlist()
DESCRIPTION
dkm_getlist()
Allows a kernel thread to retrieve various pieces of information
about the extensions of a Distributed Kernel Memory (DKM) segment and copy this
information to a specified kernel-space address. Among the information retrieved are the
extension number and starting kernel-space address for each segment extension. To
interpret the information retrieved by the dkm_getlist() function, users should cast a
pointer of type dkmextinfo_t (which is defined in the <dkm.h> header file) to the address
specified by the addr argument and increment this pointer accordingly to access
information about the individual segment extensions.
SYNOPSIS
int dkm_getlist(int dkmid , void * addr , size_t size , int reason );
dkmid
addr
This argument specifies the kernel-space address to which the
information retrieved should be copied.
size
This argument specifies the maximum amount of information (in terms
of bytes) that can be copied starting from the addr value.
RETURN VALUES
int
-1
On success. A non-negative integer represents the actual amount of data

copied (in terms of bytes). Note that the actual number of bytes copied
will always be a multiple of the size of the dkmextinfo_t data type,
provided that the DKM segment specified contains one or more
extensions. (always set to E_DKM_NOERR)
ERRORS
<E_DKM_NOENT> Unable to locate the segment specified.
<E_DKM_NOSPC> Unable to copy information about all extensions of
the segment because the total number of bytes copied will
exceed the value of the size argument specified. This
indicates a partial information retrieval.
down.
Page 15 - 13
1-1600-1003-01
DKM API Library
NOTES
If the size argument specified by the calling thread is not large enough to retrieve
information about all extensions of the segment, the system will be able to retrieve only a
portion of the extension related information. To help identify such circumstances, users
should always check the error code of the dkm_getlist() function, in addition to its return
value. The fact that dkm_getlist() returns a non-negative value does not necessarily mean
that it has retrieved/copied information about all segment extensions. It is only when a nonnegative return code coupled with an error code value of E_DKM_NOERR, can the user be
sure that information about all extensions of the segment has been retrieved/copied
successfully.
SEE ALSO dkmd, dkm_list, dkm_extend(), dkm_shrink(), dkm_query()
15.2.8 dkm_lock()
DESCRIPTION
dkm_lock()
This function allows a kernel thread to lock a specified region of a
Distributed Kernel Memory (DKM) segment or segment extension for read-only or readwrite purposes.
The DKM framework allows multiple kernel threads on a given host, or across multiple
hosts, to hold read-only locks across overlapping regions of a DKM segment. The readwrite locks on a given host are always exclusive. While a kernel thread is holding a readwrite lock across a specified region of a DKM segment, no other kernel thread on that host
will be granted a lock of any type across overlapping regions of the segment. However,
kernel threads executing on other hosts may be permitted, under selected circumstances,
to acquire read-only locks across overlapping regions of a DKM segment while a kernel
thread on a specified host is in possession of a non-exclusive read-write lock.
The locking mechanism employed by the Distributed7 DKM framework is highly
efficient and involves minimal overhead when acquiring/releasing read-only or read-write
locks. The specifics of this mechanism in regard to lock allocation is as follows:
When a kernel thread issues a request to acquire a read-only type lock, a check is made,
by the DKM API library on behalf of the calling thread, to find out if the specified
region of memory is currently accessed by another kernel thread for read-write
operations or is in the process of being updated. Provided that neither condition is true,
the lock requested will be granted immediately (without even a need to communicate
with the local DKM multiplexer). Otherwise, the lock request will be filed with the
local DKM multiplexer for later processing. Under no circumstances will processing of
a read-only lock request necessitate inter-host communication among the DKM
multiplexers on the individual hosts.
When a kernel thread issues a request to acquire a non-exclusive read-write lock, a
check is made, by the DKM API library on behalf of the calling thread, to find out if the
last write access to the region specified was by kernel threads executing on the local
host. If this is true, further checks will be made to verify that the effected region is not
Page 15 - 14
1-1600-1003-01
DKM API Library
currently locked and its contents are not in the process of being updated. Subsequently,
the lock requested will be granted (without even a need to communicate with the local
DKM multiplexer). Otherwise, the lock request will be filed with the local DKM
multiplexer for later processing.
An attempt to acquire a non-exclusive read-write lock when the last write access to the
specified region was by kernel threads executing on remote hosts will result in some
amount of inter-host communication, to re-acquire the ownership of the effected region
first and then grant the lock. But the nature of non-exclusive read-write locks suggests
that such circumstances should rather be the exception and not the norm.
When a kernel thread issues a request to acquire an exclusive read-write lock, a fair
amount of inter-host communication is necessary among the DKM multiplexers on the
individual hosts and that is exactly why there is a considerable performance penalty
associated with the use exclusive read-write locks in general. This communication is to
ensure that the specified region of memory is neither locked by other kernel threads nor
in the process of being updated.
SYNOPSIS
int dkm_lock(int dkmid , void * addr , size_t size , int flags , dkmlock_t * lock , int
* reason);
dkmid
addr
This argument specifies the beginning address of the DKM region to be
locked and should be a valid kernel-space address on the local host.
size
This argument specifies the actual size (in terms of bytes) of contiguous
memory to be locked starting from addr.
flags
list:
DKM_RDONLY - Lock region specified for read-only purposes
only. This option cannot be used in conjunction with the
DKM_RDWR flag.
DKM_RDWR - Lock region specified for read-write purposes. This
is the default option. This option cannot be used in conjunction with
the DKM_RDONLY flag.
DKM_WAIT - Suspend execution of the calling thread indefinitely if
the lock requested cannot be granted immediately, because either
another lock that interferes with the operation of the lock requested
exists or an update operation is in progress. When conditions allow,
the lock requested will be granted and the calling thread will resume
its execution. This is the default option. It cannot be used in
conjunction with the DKM_NOWAIT flag.
DKM_NOWAIT - Do not suspend execution of the calling thread if
the lock specified cannot be granted by the system immediately. If
the lock specified can be acquired right away, acquire the lock.
Page 15 - 15
1-1600-1003-01
DKM API Library
Otherwise, return an error so that the calling thread can continue its
execution. This option cannot be used in conjunction with the
DKM_WAIT flag.
DKM_NOTSOEXCL - Acquire a non-exclusive read-write lock with
local context only (as opposed to acquiring an exclusive read-write
lock with global context, which is the default option). Note that nonexclusive read-write locks allow kernel threads executing on remote
hosts to hold read-only locks across overlapping regions of the
segment; thus, result in a more efficient scheme where kernel-space
data can be accessed through multiple hosts in a concurrent manner.
This option is meaningful only when it is used in conjunction with the
DKM_RDWR flag. In order for local read-write locks across a DKM
segment or segment extension to be permitted, the DKM segment or
the extension must have been created with the
DKM_WRITEBYONE option (indicating that, under normal
circumstances, the contents of the segment and/or segment extension
are expected to be manipulated by kernel threads executing on a
designated host).
Unless this option is specified, all read-write locks are considered to
be exclusive across the network, which prevents any type of lock to
be acquired by kernel threads executing on any host across
overlapping regions of a DKM segment or segment extension. Due to
this restrictive nature of the exclusive read-write locks, their use
should be restricted to cases where the read/write operation is almost
instantaneous.
DKM_TRIGGER - Trigger an M_DKM event when the lock
specified is granted. This option is meaningful only when it is used in
conjunction with the DKM_RDWR flag. DKM users have no other
means of triggering M_DKM events upon successful instantiation of
read-only locks.
RETURN VALUES
0
-1
On success, information about the lock acquired (lock identifier) is

returned to the calling thread by the lock argument which is of type
dkmlock_t.
ERRORS
Page 15 - 16
1-1600-1003-01
DKM API Library

again later.
<B E_DKM_ACCES> Request is denied because the DKM multiplexer on
the local host is not in a state to service its users,
down.
<E_DKM_FAULT> The address range specified via the addr and size
arguments is found to be invalid. The DKM framework
expects the entire memory space to be locked to be
contained within the main DKM segment or within an
extension of the segment.
SEE ALSO dkmd, dkm_get(), dkm_extend(), dkm_unlock(), dkm_query(),

dkm_sync()
15.2.9 dkm_notify()
DESCRIPTION
dkm_notify()
This function call allows a kernel thread to be informed about
Distributed7 Distributed Kernel Memory (DKM) related events that are optionally
triggered by other kernel threads. Examples of such events include creation of a new
DKM segment and/or segment extension, destruction of an existing DKM segment and/or
segment extension, allocation or destruction of a DKM lock, and synchronization of
contents of a DKM region.
SYNOPSIS
int dkm_notify(queue_t * q , int flags , int * reason );
q
This argument specifies the address of the STREAMS queue associated
with the calling thread. Information provided in this field is essential
since the notification of the calling thread by the DKM will be performed
by M_DKM eventsessentially STREAMS messagesposted on this
queue. Not all DKM users have physical STREAMS connections to the
Page 15 - 17
1-1600-1003-01
flags
DKM API Library
DKM STREAMS multiplexer; therefore, the q address specified provides

the only means of back-communication with such DKM users.
This argument assumes a value from the following list:
DKM_SIGNUP - Calling thread is interested in being notified about
the M_DKM events that may be triggered by other threads; thus, the
DKM multiplexer should notify the calling thread by STREAMS
messages posted on q each time such an event occurs.
DKM_CANCEL - Calling thread is no longer interested in being
notified about M_DKM events that may be triggered by others; thus,
the DKM multiplexer should stop posting STREAMS messages on
the q specified.
NOTES
The STREAMS messages generated by the DKM multiplexer to notify interested parties
about M_DKM events are always of type M_CTL. To obtain more information about the
specifics of an M_DKM event, users should cast the data portion of the M_CTL message
received to the dkmevent_t data type that is defined in the <dkm.h> header file. It should be
noted here that DKM users have no means of specifying interest in a sub-category of
M_DKM events. Thus, it is up to the user to determine which M_DKM events are of interest
as they occur, i.e., based on the event type information contained in the message. It is also
important to note here that if a kernel thread that has been registered for M_DKM event
notification triggers a M_DKM event itself, a notification [regarding the event triggered]
will also be given to that thread.
When a kernel thread that has been registered for M_DKM event notification loses interest
in such events [for whatever reason], it should cancel its former registration by invoking the
dkm_notify() function call with the DKM_CANCEL argument. Note that the DKM
multiplexer has no other means of knowing when the STREAMS queue address specified
during a DKM_SIGNUP attempt by a particular kernel thread becomes invalid. A failure to
de-register by even one of the threads is likely to result in system crashes [when an attempt
is made by the DKM multiplexer to post a M_CTL message on this queue].
RETURN VALUES
0
-1
On success.
ERRORS
<E_DKM_EXIST> A DKM_SIGNUP request is denied because the q address
specified is already included on the list of users
interested in being notified about M_DKM events.
<E_DKM_NOENT> A DKM_CANCEL request is denied because the q address
specified is not on the list of users interested in being
notified about M_DKM events.
Page 15 - 18
1-1600-1003-01
DKM API Library
<E_DKM_NOMEM> Unable to service a DKM_SIGNUP request due to

failure in kernel-space memory allocation.
down.
SEE ALSO dkmd, dkm_list, dkm_get(), dkm_destroy(), dkm_extend(),

dkm_shrink(), dkm_lock(), dkm_unlock(), dkm_schedule(), dkm_sync()
15.2.10dkm_query()
DESCRIPTION
dkm_query()
This function allows a kernel thread to retrieve various pieces of
information about the data blocks that comprise a Distributed Kernel Memory (DKM)
segment and/or segment extension. Among the information retrieved are the current status
of the block (whether it is locked or not) and its last modification time.
SYNOPSIS
int dkm_query(int dkmid , void * addr , dkmstat_t * stat , int reason );
dkmid
addr
This argument specifies the local kernel-space address about which the
calling thread is interested in obtaining information and is instrumental in
identifying the data block within the DKM segment and/or segment
extension specified.
stat
This argument specifies the kernel-space address into which information
returned by dkm_query() will be copied. It is of type dkmstat_t. For
more information about this data type, refer to the <dkm.h> header file.
RETURN VALUES
0
-1
On success; information retrieved is copied to the kernel-space address

pointed to by the stat argument.
ERRORS
<E_DKM_NOENT> Unable to locate the segment specified.
down.
Page 15 - 19
1-1600-1003-01
DKM API Library
<E_DKM_FAULT> The address specified by the addr argument is found

to be invalid.
SEE ALSO dkmd, dkm_list, and dkm_stat.
15.2.11dkm_schedule()
DESCRIPTION
dkm_schedule()
This function allows a kernel thread to initiate an asynchronous
request to acquire a Distributed Kernel Memory (DKM) lock and it provides an alternative
to the dkm_lock() function which has been designed to initiate synchronous lock requests
only.
By initiating an asynchronous lock request, a kernel thread essentially declares that it
cannot afford to be suspended for the lock specified to be acquired but nevertheless wants
it to be acquired by the system sooner or later. The only real interest of the calling thread is
to be notified immediately after the lock specified has been acquired and this notification
can either be by having the system invoke a kernel-resident function directly, i.e., on
behalf of the calling thread, or posting an M_DKM event of type
DKM_SCHEDULE_IND on a specified STREAMS queue.
SYNOPSIS
int dkm_schedule(int dkmid , void * addr , size_t size , int flags , queue_t * q , void
(*func)(int , void *) , void * arg , dkmtimer_t * timer , int * reason );
dkmid
addr
This argument specifies the beginning address of the DKM region to be
locked and should be a valid kernel-space address on the local host.
size
This argument specifies the actual size (in terms of bytes) of contiguous
memory to be locked starting from addr.
flags
list:
DKM_RDONLY - Lock region specified for read-only purposes only.
This option cannot be used in conjunction with the DKM_RDWR
flag.
DKM_RDWR - Lock region specified for read-write purposes. This
is the default option. This option cannot be used in conjunction with
the DKM_RDONLY flag.
DKM_WAIT - Suspend execution of the calling thread indefinitely if
the lock requested cannot be granted immediately, because either
another lock that interferes with the operation of the lock requested
exists or an update operation is in progress. When conditions allow,
the lock requested will be granted and the calling thread will resume
Page 15 - 20
1-1600-1003-01
DKM API Library
its execution. This is the default option. It cannot be used in

conjunction with the DKM_NOWAIT flag.
DKM_NOWAIT - Do not suspend execution of the calling thread if
the lock specified cannot be granted by the system immediately. If
the lock specified can be acquired right away, acquire the lock.
Otherwise, return an error so that the calling thread can continue its
execution. This option cannot be used in conjunction with the
DKM_WAIT flag.
DKM_NOTSOEXCL - Acquire a non-exclusive read-write lock with
local context only (as opposed to acquiring an exclusive read-write
lock with global context, which is the default option). Note that nonexclusive read-write locks allow kernel threads executing on remote
hosts to hold read-only locks across overlapping regions of the
segment; thus, result in a more efficient scheme where kernel-space
data can be accessed through multiple hosts in a concurrent manner.
This option is meaningful only when it is used in conjunction with
the DKM_RDWR flag. In order for local read-write locks across a
DKM segment or segment extension to be permitted, the DKM
segment or the extension must have been created with the
DKM_WRITEBYONE option (indicating that, under normal
circumstances, the contents of the segment and/or segment extension
are expected to be manipulated by kernel threads executing on a
designated host).
Unless this option is specified, all read-write locks are considered to
be exclusive across the network, which prevents any type of lock to
be acquired by kernel threads executing on any host across
overlapping regions of a DKM segment or segment extension. Due to
this restrictive nature of the exclusive read-write locks, their use
should be restricted to cases where the read/write operation is almost
instantaneous.
DKM_TRIGGER - Trigger an M_DKM event when the lock
specified is granted. This option is meaningful only when it is used in
conjunction with the DKM_RDWR flag. DKM users have no other
means of triggering M_DKM events upon successful instantiation of
read-only locks.
This optional argument instructs the system that the calling thread is
interested in being notified by a M_CTL message posted on the
STREAMS queue whose address is given when the lock specified is
acquired by the system (on behalf of the calling thread). When the
M_CTL message is received, the calling thread is expected to cast the
data portion to the dkmevent_t data type (defined in the <dkm.h> header
file) and determine the specifics of the lock acquired (e.g. lock
identifier). A NULL value of q instructs the system that the calling thread
is not interested in being notified about lock availability by M_DKM
Page 15 - 21
1-1600-1003-01
func / arg
DKM API Library
events posted on a STREAMS queue but instead wishes an appropriate

kernel-resident function to be invoked by the system directly.
The address of the kernel function to be invoked as well as the optional
function argument (the second argument) are respectively specified by
the func and arg arguments. At the time func is invoked, the lock
identifier corresponding to the asynchronous lock acquired will
automatically be passed to it as the first argument. This allows the calling
thread to find out about the identity of the lock acquired as the calling
thread is ultimately responsible for releasing this lock.
RETURN VALUES
0
-1
On success; information about the asynchronous request made (timer

identifier) is returned to the calling thread by the timer argument that is
of type dkmtimer_t (which, in essence, is equal to the integer type).
This information is of critical use when the calling thread wishes to
cancel a pending asynchronous lock request at a later time through the
dkm_cancel() function call.
ERRORS
down.
<E_DKM_FAULT> The address range specified by the addr and size
expects the entire memory space to be locked to be
SEE ALSO dkmd, dkm_lock(), dkm_cancel()
Page 15 - 22
1-1600-1003-01
DKM API Library
15.2.12dkm_shrink()
DESCRIPTION
dkm_shrink()
Allows a kernel thread to delete an existing Distributed Kernel
Memory (DKM) extension, i.e., de-allocate the kernel-space memory associated with the
segment extension, and remove the identifier associated with the extension from the
system.
When a DKM segment extension is deleted from the system using the dkm_shrink()
function call, identifiers assigned to other extensions of the segment are not re-assigned.
This is to say an extension identifier that is assigned during a dkm_extend() function call
remains valid until the corresponding extension is deleted from the system using the
dkm_shrink() function call.
SYNOPSIS
int dkm_shrink(int dkmid , int extid , int flags , int * reason );
dkmid
extid
This argument identifies the segment extension of interest and should be
obtained through a previous call to the dkm_extend() function.
flags
list:
DKM_WAIT (default option)
Suspend running the calling thread until the destroy operation is
complete and all local copies of the DKM segment specified are
removed. This argument cannot be used in conjunction with
DKM_NOWAIT.
DKM_NOWAIT
Do not wait for completion of the destroy operation and release the
calling thread immediately after conducting a basic set of sanity
checks to make sure that the DKM segment specified exists. This
argument cannot be used in conjunction with DKM_WAIT.
DKM_LOCALONLY
Delete local copy of the segment extension (do not delete replicated
copies of the extension on remote hosts).
DKM_TRIGGER
Trigger an M_DKM event upon successful deletion of the extension.
Note that if the DKM_LOCALONLY flag is also specified, the
M_DKM event will only be triggered on the local host.
RETURN VALUES
0
-1
On success.
Page 15 - 23
1-1600-1003-01
DKM API Library
ERRORS
<E_DKM_NOENT> Unable to locate the DKM segment and/or extension
specified.
again later.
<E_DKM_BADMSG> An invalid and/or corrupted response was received
from the local DKM multiplexer.
down.
<E_DKM_COMM> A communication error occurred while the DKM
SEE ALSO dkmd, dkm_rm, dkm_extend(), dkm_destroy(), dkm_unlock(),

dkm_cancel(), dkm_getlist()
Page 15 - 24
1-1600-1003-01
DKM API Library
15.2.13dkm_sync()
DESCRIPTION
dkm_sync()
This function call allows a kernel thread to initiate a manual
request to propagate the changes made to the contents of a Distributed Kernel Memory
(DKM) segment or segment extension to all involved hosts while in possession of a readwrite lock. Note that the read-write lock held by the calling thread will not be released by
the system following propagation of the changes made. This method of data
synchronization provides an alternative to releasing the read-write lock held and have the
system propagate the data changes incurred automatically.
In theory, the manual data synchronization capability can be exercised by any kernel
thread that is in charge of read-write lock (non-exclusive or exclusive). In practice
however, this capability should be used only when the calling thread is in charge of a nonexclusive read-write lock. That is because as a rule of thumb the use of exclusive readwrite locks should be restricted to those cases where the read/write operation is almost
instantaneous.
SYNOPSIS
int dkm_sync(int dkmid , void * addr , size_t size , int flags , int * reason );
dkmid
Identifies the DKM segment of interest that must be obtained through a
previous call to the dkm_get() function.
addr
Specifies the beginning address of the DKM region to be synchronized;
must be a valid kernel-space address on the local host.
size
specifies the actual sizebytesof contiguous memory to be
synchronized, starting from addr.
flags
list:
DKM_TRIGGER - Trigger an M_DKM event when the data
synchronization operation is complete.
RETURN VALUES
0
-1
On success.
ERRORS
Page 15 - 25
1-1600-1003-01
DKM API Library

again later.
down.
<E_DKM_FAUL> The address range specified via the addr and size
expects the entire memory space to be synced to be
SEE ALSO dkmd, dkm_lock(), dkm_unlock()
15.2.14dkm_unlock()
DESCRIPTION
dkm_unlock()
This function call allows a kernel thread to release a Distributed
Kernel Memory (DKM) lock that has been acquired previously and propagate the data
changes incorporated (if any) to all hosts involved.
SYNOPSIS
int dkm_unlock(int dkmid , int lockid , int flags , int * reason );
dkmid
lockid
This argument identifies the lock to be released and should be obtained
through a previous call to the dkm_lock() function.
flags
This argument can be constructed by OR-ing flags from the following list
and should be used within the context of read-write locks only (only one
of the first three flags listed below may be used):
DKM_SYNCFIRST - Propagate data changes made to all involved
hosts prior to releasing the read-write lock specified. This is the
default option. Note that the use of this option will cause the
Page 15 - 26
1-1600-1003-01
DKM API Library
execution of the calling thread to be suspended until the contents of

the replicated copies of the segment on individual hosts are put back
in sync.
DKM_SYNCLATER - Release read-write lock specified first and
propagate data changes made to all involved hosts subsequently. Note
that while the calling thread can continue its execution right after
releasing the lock, the effected DKM region becomes inaccessible
[on all involved hosts] until the corresponding data changes are
incorporated.
This option is applicable to read/write locks with local context only
and cannot be used within the context of global read/write locks.
Stated in other words, to be able to specify the DKM_SYNCLATER
option during an unlock attempt, the DKM_NOTSOEXCL flag
should have been set during the corresponding dkm_lock() call.
DKM_NOCHANGES - No data changes have occurred; therefore,
release the read-write lock associated without synchronizing the data.
completion of the synchronization process and removal of the readwrite lock associated.
RETURN VALUES
0
-1
On success.
ERRORS
<E_DKM_NOENT> Unable to locate the DKM segment and/or lock
identifier specified.
again later.
Page 15 - 27
1-1600-1003-01
DKM API Library

down.
SEE ALSO dkmd, dkm_lock(), dkm_destroy(), dkm_cancel()
Page 15 - 28
1-1600-1003-01
Chapter 16:
DRA API Library
DRA API Library

This chapter provides the Distributed Record Access (DRA) Application Programming
16.2 DRA API Library

The DRA library is used to create and manage shared memory segments under a distributed
calls require the following header files to be included in the application:
#include <dra_cmn.h>
#include <dra_proto.h>
Page 16 - 1
1-1600-1003-01
DRA API Library
16.2.1 dra_construct()
DESCRIPTION
dra_construct()
This function allows a kernel thread to create a new Distributed
Record Access (DRA) segment or to obtain access to an existing DRA segment associated
with the key argument. DRA organizes/presents kernel memory in a record oriented
fashion. DRA records have distributed and non-distributed (private) counterparts.
Distributed portions of DRA records are kept in a DKM segment (or DKM extension
segment). DRA maintains the record private portions. DRA keeps record indexes in nondistributed memory and relies on DKM events to keep this data up-to-date. Memory for
DKM segments used by DRA are always allocated by DKM.
SYNOPSIS
int dra_construct(dra_seg_def * seg_def , dra_idx_def * prim_def ,
dra_idx_def * secn_def , dra_callbacks * callbacks ,
int * dkm_id_ref , dra_seg_p * dra_seg_ref );
seg_def
This argument is of type dra_seg_def and is used to provide segment
related information.
seg_name field is used to provide an ASCII string to identify the
segment, this field is provided for debug purposes only.
seg_key field is the key for the DRA segment which is also used as
the DKM segment key.
size_seg_priv field is the size of the segment private data area in
octets, this area can be used to store segment specific information.
rsize_dist field gives the size of record distributed portion, whereas
rsize_priv field gives the size of record private (non-distributed)
portion (both in octets).
nrecs_sseg field gives the number of records that must fit into a DRA
extension chunk. DRA records are allocated and deallocated in
chunks. An initial chunk is created along with segment creation, and
an additional chunk is created every time a new record request is
received and all the existing records are in use.
seg_flags field is the set of segment flags to be used for the dkm_get()
call. DRA always sets the DKM_CREATE and DKM_ALLOC flags
prior to DKM segment creation.
prim_def /
These arguments are both of type dra_idx_def and are used to provide
secn_def
information about the primary and secondary index definitions of the
segment, respectively. If no secondary index exists secn_def should be
given as NULL, a primary index is mandatory for all DRA segments.
type specifies the index type which can assume the values e_sort or
e_hash, for creating sorted or hashed indexes, respectively.
Page 16 - 2
1-1600-1003-01
DRA API Library
callbacks
key_begin gives the offset of the record key with respect to the
beginning of the record distributed part (DRA keys always belong to
the record distributed part), and key_size gives the size of the record
key (both in octets). For hashed indexes only sizes 1,2,3 and 4 are
valid.
The sort portion of dra_idx_def is used only for sorted indexes.
When a sorted index has no more index records left, a bigger index
area is allocated and existing index information is copied onto this
new area, extend_fraction is used to calculate the size of the new
index area (i.e, if extend_fraction is 50, new index area size is the 1.5
times the original index area).
min_pref is the size of the minimum prefix to be used with
dra_find() when DRA_GETPREF key is specified.
The hash portion of dra_idx_def is used for information specific to
hashed indexes.
prim_num_recs is the number of records in the primary hash area,
and sec_num_recs is the initial number of records in the secondary
hash area (secondary hash area can be extended during run-time).
ref_val is the arbitration value used by DRA when allocating hashed
keys, i.e., dra_new_record(), typically host index or some other host
specific value must be provided for this field.
This argument is of type dra_callbacks and is used to provide user
callbacks for handling various asynchronous events.
user_ptr is a user specific pointer passed back with every callback
invoked.
segment_id, and segment_key contain the DKM segment id, and
segment key information.
dist_part and priv_part point to the distributed and private portions
of the record (if a DRA record is involved in the action).
init_func is called every time a record is added to the segment (via a
remote host)
del_func is called every time record is deleted from the segment (via
a remote host). del_func does not contain a pointer to record
distributed part (because the distributed portion of the record is
invalidated at the time of callback invocation) but provides a pointer
to a copy of deleted record's primary key.
lock_func is called for asynchronous lock requests (see
dra_relock_async()). lock_func callback receives the result of the
lock request in result, and if the result is e_dra_ok, lock_ref points to
the DRA lock information (see dra_new_record() for details).
error_func is called every time an error is received during DKM
event handling. reason gives the failure reason (see dra_cmn.h), and
error shows the type of the error, which can be one of the following:
Page 16 - 3
1-1600-1003-01
DRA API Library
dkm_id_ref /
dra_seg_ref
e_dra_ext_fail - Error encountered during the handling of a DKM

extend event.
e_dra_sched_fail - Error encountered during the handling of a DKM
sync. event.
e_dra_sync_fail - Error encountered during the handling of a DKM
schedule event.
Arguments fail - Error encountered during the handling of a DKM
extend event.
e_dra_sched_fail - Error encountered during the handling of a DKM
sync. event.
e_dra_sync_fail - Error encountered during the handling of a DKM
schedule event.
are used to store the DKM id of the corresponding DKM segment,
and the instance pointer for the constructed (or attached) DRA segment,
respectively.
RETURN VALUES
e_dra_ok
int
On success. The value of e_dra_ok is defined as 0. Upon successful

completion, dkm_id_ref points to the DKM id of the corresponding
DKM segment, and the dra_seg_ref points to the corresponding DRA
segment.
On failure; a non-zero integer which represents the actual error code.
ERRORS
<e_dra_nomem>::Not enough memory to construct the requested
segment.
<e_dra_null_seg>::SEG_KEY_NULL (0) passed as the key for segment
creation.
<e_dra_dkm_err>::Inconsistent DKM segment/extension segment info.
<e_dra_nil_size>::0 specified as the size of record distributed
part or as number of records in a DRA extension chunk.
<e_dra_null_ptr>::NULL pointer passed for dra_seg_ref.
<e_dra_no_prim>::No primary index specified.
<e_dra_inv_idxtyp>::An index type different than e_sort or e_hash
specified.
<e_dra_inv_idxsz>::0 specified as the size of primary or secondary
key.
<e_dra_long_key>::Definition of primary or secondary key exceeds
record size.
<e_idx_nomem>::Not enough memory to construct the index.
<e_idx_long_record>::Key size exceeds IDX_MAX_REC_SIZE
Page 16 - 4
1-1600-1003-01
DRA API Library
<e_idx_ill_num_recs>::Incorrect number of records for hashed

index primary area (<=1).
<e_idx_ill_key_size>::Hashed index key size outside permissible
boundaries (1 - 4).
For additional error codes, refer to dkm_get(), dkm_lock(), dkm_unlock(), dkm_getlist().

SEE ALSO dra_new_record(), dra_del_record(), dra_del_locked(),
dra_find_record(), dra_find_inseq(), dra_validate(), dra_relock_sync(),
dra_relock_async(), dra_rls_lock(), dra_lock_seg_priv(), dra_rls_seg_priv(),
dra_get_dkm_id(), dra_destroy(), dkm_get(), dkm_getlist()
16.2.2 dra_del_locked()
DESCRIPTION
dra_del_locked()
This function allows a kernel thread to delete an already locked
record. The type of the previously acquired lock is not important (it could even be one
acquired using the DRA_NOLOCK flag). If the record being deleted is the last used
record on a DRA extension chunk, the resources for that chunk are released (along with a
call to dkm_shrink()).
SYNOPSIS
int dra_del_locked(dra_seg_p seg_ref , dra_lockinfo * lock_ref , unsigned int flags );
seg_ref
This argument is the instance pointer of the related DRA segment,
received via a dra_construct() call.
lock_ref
This argument points to DRA lock information received from an earlier
call to dra_new_record(), dra_find_record(), dra_find_inseq(),
dra_relock_sync() or dra_relock_async().
flags
This argument specifies the flags to be used along with record deletion.
The only flag allowed is DRA_SAFE_LOCK. If this flag is specified,
the DRA record is marked as `being modified`, and this information is
synchronized throughout the network before proceeding with record
deletion. DRA functions (dra_find_record(), dra_find_inseq() and
dra_validate()) fail with e_dra_conflict when operated on a DRA record
in state `being modified`. This flag should be used when deleting records
normally accessed with the DRA_NOLOCK flag.
RETURN VALUES
e_dra_ok
int
On success. The value of e_dra_ok is defined as 0.

ERRORS
<e_dra_bad_inst>::Incorrect DRA instance pointer.
<e_dra_inv_ref>::Invalid lock information passed.
Page 16 - 5
1-1600-1003-01
DRA API Library
<e_dra_nonexist>::Record already deleted by remote host.

<e_dra_seg_del>::DRA segment deleted during action.
<e_idx_key_not_found>::Record pointed by lock_ref does not exist
anymore (only if the lock is acquired using DRA_NOLOCK
flag).
For additional error codes, refer to dkm_shrink(), dkm_lock() and dkm_unlock().

SEE ALSO dra_construct(), dra_new_record(), dra_del_record(), dkm_shrink(),
dkm_lock(), dkm_unlock()
16.2.3 dra_del_record()
DESCRIPTION
dra_del_record()
This function allows a kernel thread to locate and delete a DRA
record with the specified key value. If the record being deleted is the last used record on a
DRA extension chunk, the resources for that chunk are released (along with a call to
dkm_shrink()).
SYNOPSIS
int dra_del_record(dra_seg_p seg_ref , dra_key * key , unsigned int flags );
seg_ref
key
This argument is of type dra_key and is used to identify the key of the
DRA record to be deleted.
val_p is a pointer to the value of the key
idx_type shows the index type to perform the search. If idx_type is
e_dra_prim primary index is used for search, and secondary index is
used if idx_type assumes the value e_dra_sec.
key_size field is not used.
flags
This argument specify the flags to be used along with record deletion.
The only flag allowed is DRA_SAFE_LOCK. If this flag is specified,
the DRA record is marked as being modified, and this information is
synchronized throughout the network before proceeding with record
deletion. DRA functions (dra_find_record(), dra_find_inseq() and
dra_validate()) fail with e_dra_conflict when operated on a DRA record
in state `being modified`. This flag should be used when deleting records
normally accessed with the DRA_NOLOCK flag.
RETURN VALUES
e_dra_ok
int
Page 16 - 6

1-1600-1003-01
DRA API Library
ERRORS
<e_no_sec_idx>::Secondary index specified for search in a DRA
segment which does not have a secondary index.
<e_dra_null_key>::NULL value passed for key.
<e_dra_bad_key>::key->val_p set to NULL.
specified.
<e_dra_nonexist>::Record already deleted by remote host.
<e_idx_key_not_found>::Record key not found.
For a list of additional error codes, refer to the manual pages for the dkm_shrink(),
dkm_lock() and dkm_unlock() function calls.
SEE ALSO dra_construct(), dra_new_record(), dra_del_record(), dkm_shrink(),
dkm_lock(), dkm_unlock()
16.2.4 dra_destroy()
DESCRIPTION
dra_destroy()
This function allows a kernel thread to locally destroy a
Distributed Record Access (DRA) segment. Segment resources are removed, along with a
call to dkm_destroy(). If the DKM_EXCLUSIVE flag was not specified during segment
creation, DKM is instructed to destroy only the local copy of the corresponding DKM
segment.
SYNOPSIS
int dra_destroy(dra_seg_p seg_ref );
seg_ref
RETURN VALUES
e_dra_ok
int

ERRORS
For a list of additional error codes, refer to the manual pages for the dkm_destroy()
function call.
SEE ALSO dra_construct(), dkm_destroy()
Page 16 - 7
1-1600-1003-01
DRA API Library
16.2.5 dra_find_inseq()
DESCRIPTION
dra_find_inseq()
This function allows a kernel thread to locate and lock DRA
records which match a specified partial key (sorted only). To find all records that match
the requested partial key, the user must make successive dra_find_inseq() calls until a
return code of e_idx_key_not_found is received. For hashed indexes dra_find_inseq()
can be used to locate all records in the segment.
SYNOPSIS
int dra_find_inseq(dra_seg_p seg_ref , dra_key * key , unsigned int flags ,
dra_record * out_rec , dra_lockinfo * lock_ref ,
dra_inseq * inseq_info );
seg_ref
key
This argument is of type dra_key and is used to identify the partial key to
be used.
val_p
This is a pointer to the value of the partial key.
idx_type This shows the index type to perform the search. If
idx_type is e_dra_prim primary index is used for search, and
secondary index is used if idx_type assumes the value e_dra_sec.
key_size This gives the size of the partial key. val_p and key_size
are ignored for hashed indexes.
flags
This argument specify the lock flags to be used by DRA and DKM, and it
can be constructed by OR-ing the related DKM flags (see <dkm.h>) with
the following DRA flags;
DRA_PRIVNON - Do not lock record private part
DRA_DISTNON - Do not lock record distributed part (similar effect
can be achieved without specifying any DKM related flags).
DRA_NOLOCK - Retrieve the record without locking.
DRA_SAFE_LOCK - Mark the DRA record as `being modified` and
synchronize throughout the network before returning to user. DRA
functions (dra_find_record(), dra_find_inseq() and dra_validate())
fail with e_dra_conflict when operated on a DRA record in state
`being modified`. This flag is only effective if DKM_RDWR flag is
set, and should be used when modifying records normally accessed
with the DRA_NOLOCK flag.
out_rec
This argument points to the record pointers (distributed part pointer in
dist_part and private part pointer in priv_part) after successful
completion.
lock_ref
This argument points to DRA lock information. This information is for
DRA use only and should not be modified by the user. It must be passed
Page 16 - 8
1-1600-1003-01
inseq_info
DRA API Library
intact to any other DRA function (dra_rls_lock(), dra_relock_sync(),

dra_relock_async(), dra_del_locked()) that needs to operate on the
locked record.
This argument is of type dra_inseq. Prior to the first dra_find_inseq()
call (for a particular partial key), the inseq_ref field of this structure must
be set to NULL, and the information in this structure must not be
modified in the following dra_find_inseq() calls.
RETURN VALUES
e_dra_ok
int

ERRORS
<e_dra_conflict>::Record is safe-locked by some other user
(received only if DRA_DISTNON flag is set).
specified.
<e_dra_nonexist>::Record deleted by remote host.
SEE ALSO dra_construct(), dra_find_record(), dkm_lock()
16.2.6 dra_find_record()
DESCRIPTION
dra_find_record()
This function allows a kernel thread to locate and lock a DRA
record with the specified key value.
SYNOPSIS
int dra_find_record(dra_seg_p seg_ref , dra_key * key , unsigned int flags ,
dra_record * out_rec , dra_lockinfo * lock_ref );
seg_ref
key
This argument is of type dra_key and is used to identify the key of the
DRA record to be located.
val_p is a pointer to the value of the key.
Page 16 - 9
1-1600-1003-01
DRA API Library
flags
out_rec
lock_ref
idx_type shows the index type to perform the search. If idx_type is

e_dra_prim primary index is used for search, and secondary index is
used if idx_type assumes the value e_dra_sec.
key_size field is not used.
This argument specify the lock flags to be used by DRA and DKM, and it
can be constructed by OR-ing the related DKM flags (see <dkm.h>) with
the following DRA flags;
DRA_GETPREF - If an exact match can not be found, return the
record with the key that has the longest matching prefix. For a
successful match, the matching prefix size must be greater than the
min_pref value given during dra_construct(). In case of a prefix
match, non-matching part of the found key must be all -0's. This flag
can only be used for sorted indexes.
This points to the record pointers (distributed part pointer in dist_part
and private part pointer in priv_part) after successful completion.
This points to DRA lock information. This information is for DRA use
only and should not be modified by the user. It must be passed intact to
any other DRA function (dra_rls_lock(), dra_relock_sync(),
dra_relock_async(), dra_del_locked()) that needs to operate on the
locked record.
RETURN VALUES
e_dra_ok
int

ERRORS
Page 16 - 10
1-1600-1003-01
DRA API Library

specified.
SEE ALSO dra_construct(), dra_find_inseq(), dkm_lock()
16.2.7 dra_get_dkm_addr()
DESCRIPTION
dra_get_dkm_addr() This function allows a kernel thread to retrieve the corresponding
DKM address for a DRA record together with the id of the corresponding DKM segment.
This information can be used to invoke DKM services directly. The record needs to be
located first by using the DRA services (dra_find_record() or dra_find_inseq()).
SYNOPSIS
int dra_get_dkm_addr(dra_seg_p seg_ref , dra_lockinfo * lock_ref ,
int * dkm_id_ref , void ** dkm_rec );
seg_ref
received by a dra_construct() call.
lock_ref
dkm_id_ref
This argument is used to store the DKM id of the corresponding DKM
segment.
dkm_rec
This argument stores the address of the corresponding DKM region.
RETURN VALUES
e_dra_ok
int

ERRORS
SEE ALSO dra_new_record(), dra_find_record(), dra_find_inseq(),

dra_get_dkm_id()
Page 16 - 11
1-1600-1003-01
DRA API Library
16.2.8 dra_get_dkm_id()
DESCRIPTION
dra_get_dkm_id()
This function allows a kernel thread to retrieve the id of the
corresponding DKM segment for a DRA segment instance. This information can be used
to invoke DKM services directly.
SYNOPSIS
int dra_get_dkm_id(dra_seg_p seg_ref , int * dkm_id_ref );
seg_ref
dkm_id_ref
This argument is used to store the DKM id of the corresponding DKM
segment.
RETURN VALUES
e_dra_ok
int

ERRORS
SEE ALSO dra_get_dkm_addr()
16.2.9 dra_get_num_recs()
DESCRIPTION
dra_get_num_recs() This function allows a kernel thread to retrieve the number of
(used) records in a DRA segment instance.
SYNOPSIS
int dra_get_num_recs(dra_seg_p seg_ref , int * num_recs_ref );
seg_ref
num_recs_ref This argument is used to store the number of records information.
RETURN VALUES
e_dra_ok
int

ERRORS
Page 16 - 12
1-1600-1003-01
DRA API Library
16.2.10dra_lock_seg_priv()
DESCRIPTION
dra_lock_seg_priv() This function allows a kernel thread to lock and access segment
private data area. This area is intended to store user specific global information about the
related DRA segment.
SYNOPSIS
int dra_lock_seg_priv(dra_seg_p seg_ref , void ** seg_priv_ref );
seg_ref
seg_priv_ref
This argument is a user provided address to store the segment private
data area address.
RETURN VALUES
e_dra_ok
int

ERRORS
<e_dra_nonexist>::Segment does not have a private data area.
SEE ALSO dra_construct(), dra_rls_seg_priv()
16.2.11dra_new_record()
DESCRIPTION
dra_new_record()
This function allows a kernel thread to create and lock a DRA
record. If there are no idle records left, a new chunk of DRA records is allocated (along
with a call to dkm_extend()).
SYNOPSIS
int dra_new_record(dra_seg_p seg_ref , byte_t * prim_key , byte_t * secn_key ,
dra_record * out_rec , dra_lockinfo * lock_ref );
seg_ref
prim_key
This argument is the address of the primary key for the record to be
created. If the primary index is sorted, a non-NULL prim_key must be
provided. If the primary index is hashed, a NULL value for prim_key
indicates a request for the allocation of record primary key by DRA. In
this case DRA checks for unused slots in the primary hash area and
allocates keys accordingly.
Page 16 - 13
1-1600-1003-01
secn_key
out_rec
lock_ref
DRA API Library
This argument is the secondary key address for the record, if a secondary
index is also defined during construction. There is no DRA provided key
allocation for secondary indexes.
This argument points to the record pointers (distributed part pointer in
dist_part and private part pointer in priv_part) after successful
completion.
This argument points to DRA lock information if record creation is okay.
This information is for DRA use only and should not be modified by the
user. It must be passed intact to any other DRA function (dra_rls_lock(),
dra_relock_sync(), dra_relock_async(), dra_del_locked()) that needs to
operate on the locked record.
RETURN VALUES
e_dra_ok
int

ERRORS
<e_dra_nomem>::Insufficient memory for DRA record creation
(allocation failed for a new chunk of DRA records).
<e_dra_dkm_err>::Inconsistent DKM extension segment info.
<e_dra_null_key>::NULL value passed for mandatory key pointer.
<e_dra_null_ptr>::NULL value passed for lock_ref.
<e_dra_max_idle>::When allocating idle records DRA checks for
usage conflicts between the private usage data and the
distributed record. In case of a usage conflict, it reinitiates the idle record search. If these retries exceed
a predefined limit (20), this error code is returned.
<e_idx_nomem>::Re-allocation of index area failed.
<e_idx_rec_exists>::A record with the same key is already defined.
For a list of additional error codes, refer to the manual pages for the dkm_lock() and
dkm_extend() function calls.
SEE ALSO dra_construct(), dra_del_record(), dra_del_locked(), dkm_lock(),
dkm_extend()
Page 16 - 14
1-1600-1003-01
DRA API Library
16.2.12dra_relock_async()
DESCRIPTION
dra_relock_async() This function allows a kernel thread to asynchronously upgrade a
previously acquired lock. Records can also be located without locking (DRA_PRIVNON
and no DKM flags) Record is first unlocked (if need be) and a read/write re-lock is
requested from DKM.
The user is informed about the completion of the action with the lock_func callback
provided at segment construction. Currently, only one user per DRA segment can use the
async. lock service. If the async lock operation succeeds, i.e., the rc argument of lock_func
is e_dra_ok, then the requested DRA record is properly locked when the user callback is
activated.
SYNOPSIS
int dra_relock_async(dra_seg_p seg_ref , dra_lockinfo * lock_ref , dkmtimer_t *
usr_timer );
seg_ref
lock_ref
usr_timer
This argument is used to store the timer idif non-NULLwhich can
be used to cancel the aysnc lock request using the dkm_cancel() call.
RETURN VALUES
e_dra_ok
int

ERRORS
anymore (only if the lock is acquired using DRA_NOLOCK
flag).
For a list of additional error codes, refer to the manual pages for the dkm_unlock() and
dkm_schedule() function calls.
dra_relock_sync(), dkm_unlock(), dkm_schedule()
Page 16 - 15
1-1600-1003-01
DRA API Library
16.2.13dra_relock_sync()
DESCRIPTION
dra_relock_sync()
This function allows a kernel thread to upgrade/downgrade a
previously acquired lock. Records can also be located without locking (DRA_PRIVNON
and no DKM flags). A record is first unlocked (if need be) and re-locked with the lock
mode specified in flags.
SYNOPSIS
int dra_relock_sync(dra_seg_p seg_ref , dra_lockinfo * lock_ref ,
unsigned int flags );
seg_ref
flags
This argument specify the re-lock flags to be used by DRA and DKM,
and it can be constructed by OR-ing the related DKM flags (see
<dkm.h>) with the following DRA flags;
lock_ref
RETURN VALUES
e_dra_ok
int

ERRORS
Page 16 - 16
1-1600-1003-01
DRA API Library

anymore (only if the lock is acuired using DRA_NOLOCK
flag).
For a list of additional error codes, refer to the manual pages for the dkm_unlock() and
dkm_lock() function calls.
dra_relock_async(), dkm_lock(), dkm_unlock()
16.2.14dra_rls_lock()
DESCRIPTION
dra_rls_lock()
acquired lock.
This function allows a kernel thread to release a previously
SYNOPSIS
int dra_rls_lock(dra_seg_p seg_ref , dra_lockinfo * lock_ref , unsigned int flags );
seg_ref
lock_ref
flags
This argument specify the release (unlock) flags to be used by DRA and
DKM, and it can be constructed by OR-ing the related DKM flags (see
<dkm.h>) with the following DRA flags;
DRA_PRIVNON - Do not unlock record private part. Record private
part can be unlocked (or re-locked) later on by other DRA calls (the
same lock_ref must be used for performing the deferred private part
unlock).
DRA_DISTNON - Do not unlock record distributed part. Record
distributed part can be unlocked (or re-locked) later on by other DRA
calls (the same lock_ref must be used for performing the deferred
distributed part unlock).
There are some cases where DRA overrides the DKM related flag
definitions provided by the user;
New record unlock: - In this case DRA sets the
DKM_TRIGGER_RMT flag prior to dkm_unlock() call.
Safe lock unlock: - When unlocking a record locked with the safe
mode of operation, DRA clears the `being modified` state of the
record and calls dkm_unlock() by resetting any
DKM_NOCHANGES and DKM_SYNCLATER flags that might
be set by the user.
Page 16 - 17
1-1600-1003-01
DRA API Library
RETURN VALUES
e_dra_ok
int

ERRORS
For a list of additional error codes, refer to the manual pages for the dkm_unlock()
function call.
SEE ALSO dra_new_record(), dra_find_record(), dra_find_inseq(), dkm_unlock()
16.2.15dra_rls_seg_priv()
DESCRIPTION
dra_rls_seg_priv()
This function allows a kernel thread to unlock segment private
data which was locked previously by using the dra_lock_seg_priv() call.
SYNOPSIS
int dra_rls_seg_priv(dra_seg_p seg_ref );
seg_ref
RETURN VALUES
e_dra_ok
int

ERRORS
<e_dra_nonexist>::Segment does not have a private data area.
SEE ALSO dra_construct(), dra_lock_seg_priv()
Page 16 - 18
1-1600-1003-01
DRA API Library
16.2.16dra_validate()
DESCRIPTION
dra_validate()
This function allows a kernel thread to verify the sanity of
information about a DRA record that is acquired by using the DRA_DISTNON flag. The
call will fail if the record is deleted or being modified (modifier must use the
DRA_SAFE_LOCK flag). If a record is located using the DRA_DISTNON flag, this
function should be called at certain points (i.e, at the beginning of every function) to
verify the validity of record information.
SYNOPSIS
int dra_validate(dra_lockinfo * lock_ref );
lock_ref
dra_relock_sync() or dra_relock_async()
RETURN VALUES
e_dra_ok
int

ERRORS
SEE ALSO dra_find_record(), dra_find_inseq()
Page 16 - 19
1-1600-1003-01
DRA API Library
Page 16 - 20
1-1600-1003-01
Chapter 17:
PM API Library
Passive Monitoring API

Library

This chapter provides the Passive Monitoring (PM) Application Programming Interface
(API) library calls for Distributed7 software products. More information can be found in the
Distributed7 Application Development Manual.
17.2 PM API Library

The PM library is used to create and manage passive monitoring links under a distributed
calls require the following header files to be included at the beginning of the application in
the given order:
#include <api.h>
#include <api_macro.h>
#include <pm_api.h>
The PM library (libpm.a) should be accessed using the $EBSHOME/access/lib path, and
cc
[flags] file(s) -I $EBSHOME/access/include
-L $EBSHOME/access/lib -lpm -loam -lcnfg -ldbms
-lspm -linet -lnsl [.library ]
The sample source code file, pmtest.c, is provided to demonstrate the use of Distributed7
PM literals and functions. They should be compiled with the MAKEFILE in the
$EBSHOME/access/sample/pm directory. After it is compiled, the executable will be
located in the $EBSHOME/access/sample/pm directory.
Page 17 - 1
1-1600-1003-01
PM API Library
17.2.1 pm_register()
DESCRIPTION
pm_register()
This function is used to register a process with the Distributed7
Passive Monitor. Applications are required to register before using the Distributed7
Passive Monitor services.
MT-LEVEL
MT-Safe
SYNOPSIS
int pm_register(pm_reg_t *pmreg_p);
The pmreg_p argument points to a pm_reg_t structure containing the following members:
char hostname[L_NAME_LENGTH_HOSTNAME];
int boardname;
int instance;
int portlo;
int porthi;
int userlo;
int userhi;
void (*catcher)(int);
hostname
This field specifies the ss7board where passive monitor link(s) exist.
hostname[] is a string of L_NAME_LENGTH_HOSTNAME characters
and must hold the machine nodename.
boardname
boardname identifies the type of ss7board and takes an oam_boardnm_e
type value which is defined in $EBSHOME/access/include/oam.h.
Currently only pci3xpq, pci3xapq, pmc8260 and artic8260 boards are
supported by Distributed7 Passive Monitor.
instance
instance is the instance number of the board among other boards of its
type. This number can be obtained by getcfg command.
portlo
This field is the port number that the application will monitor. If the
application will only monitor a single link, then both the portlo and
porthi fields should hold that port number. When several or all ports will
be monitored by the application, the first port number is entered in the
portlo field and the last port number is entered in the porthi field to
specify all the ports in that inclusive range.
porthi
This field is the port number that the application will monitor. If the
application will only monitor a single link, then both the portlo and
porthi fields should hold that port number. When several or all ports will
be monitored by the application, the first port number is entered in the
Page 17 - 2
1-1600-1003-01
userlo
userhi
catcher()
PM API Library
portlo field and the last port number is entered in the porthi field to
specify all the ports in that inclusive range.
This field specifies the user parts that the application should receive
MSUs for. If the application should only receive MSUs from one user
part, then the userlo and userhi fields should both hold the number for
that user part. If the application should receive MSUs for several or all
user parts, then the lowest user part number is entered in userlo and the
highest user part number is entered in userhi. If user part numbers are
not consecutive, separate registration requests must be sent for the
individual user parts.
This field specifies the user parts that the application should receive
MSUs for. If the application should only receive MSUs from one user
part, then the userlo and userhi fields should both hold the number for
that user part. If the application should receive MSUs for several or all
user parts, then the lowest user part number is entered in userlo and the
highest user part number is entered in userhi. If user part numbers are
not consecutive, separate registration requests must be sent for the
individual user parts.
This field in the pm_reg_t structure identifies the user function to invoke
in case the Distributed7 software is stopped or if the ss7board that was
registered goes to offline state while the user process is running. This
field is intended for providing a means of graceful termination for the
application processes running under the Distributed7 environment. At
the time the catcher() function is invoked, the file descriptor of the
corresponding service endpoint will normally be passed as an argument
to it.
If the catcher() field is set to NULL and the user process is in charge of
multiple endpoints, the system will simply close the endpoint associated
with specified file descriptor (i.e., on behalf of the user process) and take
no further action (until all endpoints owned by the process are closed).
When the last endpoint is closed, the user process will be terminated
prematurely by calling the exit function.
RETURN VALUES
File descriptor
-1
On success.
On failure.
ERRORS
Upon failure, errno is set to one of the following error codes (or any other error code set
by spm_open, spm_bind, oam_ss7board, spm_snd, spm_rcv or spm_notify):
<EUSERS>::Too many users.
<EBADMSG>::Trying to read an unreadable message.
Page 17 - 3
1-1600-1003-01
PM API Library
<ENOMEM>::Not enough memory.

<EPARAMVAL>::Parameter value out of range.
<EALREG>::Service already registered.
<EOFAIL>::Operation failed.
SEE ALSO pm_deregister(), pm_notify(), pm_listen(), pm_status(), pm_admin().
17.2.2 pm_deregister()
DESCRIPTION
pm_deregister()
This function is used to deregister a process that has registered
with the Distributed7 Passive Monitor by using the pm_register() function call.
Deregistration informs the Distributed7 Passive Monitor layer that it no longer needs to
send MSUs to the application.
Upon successful return from the call, the service endpoint associated with the user process
will be deactivated (i.e., the device file associated with the endpoint will be closed and any
local library resources allocated previously will be freed).
MT-LEVEL
MT-Safe
SYNOPSIS
int pm_deregister(int fd);
RETURN VALUES
0
-1
On success.
On failure.
ERRORS
by spm_snd, spm_rcv, spm_notify or spm_close):
<EBADF>::Bad file descriptor
<EBADMSG>::Trying to read an unreadable message.
<EPARAMVAL>::Parameter value out of range.
<EALDEREG>::Service already deregistered.
<EINCOMP>::Incompatible with the service.
<ENTOWN>::User is not the owner.
<EOFAIL>::Operation failed.
Page 17 - 4
1-1600-1003-01
PM API Library
SEE ALSO pm_register(), pm_notify(), pm_listen(), pm_status(), pm_admin().
17.2.3 pm_status()
DESCRIPTION
pm_status()
This function is used to used to request information on the status
of the links associated with the Passive Monitor service endpoint, identified by fd. If the
call returns with succes, application receives status indication messages for each
registered link. See pm_notify() for the structure of a link status indication message.
MT-LEVEL
MT-Safe
SYNOPSIS
int pm_status (int fd);
RETURN VALUES
0
-1
On success.
On failure.
ERRORS
by spm_snd).
SEE ALSO pm_register(), pm_notify(), pm_listen(), pm_deregister(), pm_admin().
17.2.4 pm_listen()
DESCRIPTION
pm_listen()
This function can be used by an application program to retrieve
messages syncronously through a Passive Monitor service endpoint, identified by fd.
The retrieved message and its type are copied into user buffers pointed by pmmsgp and
msgtyp respectively. For a description of the Passive Monitor message structure see
pm_notify().
pm_notify is an asynchronous way of processing messages captured by Distributed7
Passive Monitor. It is important that applications should not use pm_listen if they have
registered a callback function with Passive Monitor services via pm_notify.
When called, pm_listen() will wait until a Passive Monitor message arrives or until the
call is interrupted by a UNIX signal. The retrieved message is either a Passive Monitor
link status message or an MSU transfer indication message (captured MSU).
Page 17 - 5
1-1600-1003-01
PM API Library
MT-LEVEL
MT-Safe
SYNOPSIS
int pm_listen(int fd, pm_msg_t *pmmsgp, int *msgtyp);
RETURN VALUES
Upon successful completion, the retrieved message message and its type are placed into
user buffers.
0
-1
On success.
On failure.
ERRORS
Upon failure, errno is set to one of the following error codes (or any other error code set by
spm_rcv).
<ECBFUNC>::There is already a callback function registered via pm_notify(3p)
SEE ALSO pm_register(), pm_notify(), pm_status(), pm_deregister(), pm_admin().
17.2.5 pm_notify()
DESCRIPTION
pm_notify()
This function can be used by an application program to process
the messages orginited by Distributed7 Passive Monitor asynchronously. A synchronous
version of this function is available via the pm_listen() function.
MT-LEVEL
MT-Safe
SYNOPSIS
int pm_notify(int fd, void (*func)(int, pm_msg_t *, int));
func
This function is invoked when a captured MSU or a passive monitor link
status message appears on the stream associated with the file descriptor.
The file descriptor is passed to func as the first argument. Second
argument of func is a pointer to a passive monitor message union:
/* passive monitor message union */
typedef union {
pm_status_ind_t status;
pm_transfer_ind_t transfer;
Page 17 - 6
1-1600-1003-01
PM API Library
} pm_msg_t;
where data structures for link status messages and captured MSUs are
defined as follows:
/* structure for PMLINK Status Indication */
typedef struct {
unsigned char portid;
unsigned char admin_state;
#define L_PMLINK_DEACTIVATE0
#define L_PMLINK_ACTIVATE1
unsigned char oper_state;
#define L_PMLINK_SHUT_OFF0
#define L_PMLINK_INACTIVE1
#define L_PMLINK_IDLE2
#define L_PMLINK_OUT_OF_SERVICE 3
#define L_PMLINK_ALIGNING4
#define L_PMLINK_INSERVICE5
#define L_PMLINK_PROC_OUTAGE6
unsigned char filler;
unsigned int time; /* time (in miliseconds) */
} pm_status_ind_t;
/* structure for MSU Transfer Indication */

typedef struct {
unsigned char portid;
unsigned char userid;/* user part number */
unsigned short length; /* MSU size in bytes, includes bsn+fsn+li+sio */
unsigned int time; /* time MSU read (in miliseconds) */
pm_msu_t msu;
/* SS7 Message Signal Unit */
} pm_transfer_ind_t;
/* structure that holds the captured SS7 Signalling Message Unit */

typedef struct {
unsigned char bsn; /* bib, bsn */
unsigned char fsn; /* fib, fsn */
unsigned char li; /* length indicator, 6 bits */
unsigned char sio; /* service information octet */
#define L_SI_SNM 0
/* Signaling Network
Management */
Page 17 - 7
1-1600-1003-01
PM API Library
#define L_SI_NTMR 1 /* Signaling Testing &
Maintenance Regular */
#define L_SI_NTMS 2 /* Signaling Testing &
Maintenance Special */
#define L_SI_SCCP 3 /* SCCP */
#define L_SI_TUP 4
/* Telephone User Part */
#define L_SI_ISUP 5 /* ISDN User Part */

#define L_SI_DUPCC 6 /* Data User Part (Call &
Circuit related) */
#define L_SI_DUPFRC 7 /* Data User Part (Facility
Registration & Cancellation related) */
#define L_SI_MTPTST 8 /* MTP Testing User Part */
#define L_SI_BIUP 9 /* Broadband ISDN User Part */
#define L_SI_SIUP 10 /* Satellite ISDN User Part */
#define L_SIF_SIZE 272 /* max MSU-SIF size */
unsigned char sif[L_SIF_SIZE]; /* signalling information
field */
} pm_msu_t;
Third argument of func is an integer that holds the message type pointed
by the second argument. Possible values are:
/* passive monitoring message types */
typedef enum {
E_PMMSG_STATUS = 0,
E_PMMSG_TRANSFER
} pm_msgtyp_e;
E_PMMSG_STATUS If the message type is E_PMMSG_STATUS then the user

application should type cast the message pointer to a pm_status_ind_t
data structure and then process it.
E_PMMSG_TRANSFERIf the message type is E_PMMSG_TRANSFER then the user
application should type cast the message pointer to a pm_transfer_ind_t
data structure and then process it.
RETURN VALUES
user buffers.
0
-1
Page 17 - 8
On success.
On failure.
1-1600-1003-01
PM API Library
ERRORS
by spm_notify).
SEE ALSO pm_register(), pm_admin(), pm_status(), pm_deregister(), pm_listen().
17.2.6 pm_admin()
DESCRIPTION
pm_admin()
This function is used to send administrative requests to the links
associated with the Passive Monitor service end point identified by fd. Two possible
requests that can be sent in the cmd field are:
L_PMLINK_DEACTIVATE
L_PMLINK_ACTIVATE
Causes passive monitor link to be deactivated.

MSUs are not received on this link.
Causes passive monitor link to be activated. In this
state, link is ready to capture and pass on MSUs
and registered applications receive indications
indications of any administrative or operational
changes.
As a result of change in the status of a passive monitor link, all applications registered
with that particular link receive link status indications.
MT-LEVEL
MT-Safe
SYNOPSIS
int pm_admin(int fd, int cmd);
RETURN VALUES
user buffers.
0
-1
On success.
On failure.
ERRORS
by spm_rcv).
Page 17 - 9
1-1600-1003-01
PM API Library
SEE ALSO pm_register(), pm_notify(), pm_status(), pm_deregister(), pm_listen().
Page 17 - 10
1-1600-1003-01
Index
A
Acronyms 1-4
Alarm
API 6-1
header files 6-1
linking library 6-1
Alert Messages 1-4
alm_notify() 6-2
alm_report() 6-4
alm_trap() 6-6
API
Alarm 6-1
APM 3-1
DKM 15-1
DRA 16-1
DSM 5-1
GW 8-1
ISUP 13-1
ISUP AoC 14-1
MTP 7-1
OAM 4-1
SCCP 9-1
SPM 2-1
TCAP 10-1
TCAP extended 12-1
API, Application Programming Interface 1-1
APM
API 3-1
header files 3-1
linking library 3-1
apm 3-3
apm_catcherr() 3-2
apm_catcherr_fatal() 3-2
apm_catcherr_user 3-3
apm_clearerr() 3-3
apm_getstate() 3-4
apm_getstate_r() 3-4
apm_init() 3-5
apm_init_asvc() 3-8
apm_init_asvc_default() 3-8
apm_init_crp() 3-9
apm_init_crp_default() 3-9
apm_init_default() 3-7
apm_kill() 3-10
apm_logerr() 3-11
apm_newerrid() 3-12
apm_printerr() 3-13, 3-14
apm_printerr_r() 3-14
apm_puterr() 3-14
apm_sendack() 3-16
apm_setlogopts() 3-17
apm_setsigchld() 3-17, 3-18
apm_setstate() 3-18
apm_spawn() 3-19
apm_trace() 3-20
apm_waitack() 3-21
C
Conventions 1-3
D
Distributed Kernel Memory (DKM) 15-1
Distributed Record Access (DRA) 16-1
Distributed Shared Memory (DSM) 5-1
DKM
API 15-1
header files 15-1
dkm_cancel() 15-2
dkm_destroy() 15-3
dkm_extend() 15-5
dkm_get() 15-8
dkm_gethostaddr() 15-11
dkm_gethostid() 15-12
dkm_getlist() 15-13
dkm_lock() 15-14
dkm_notify() 15-17
dkm_query() 15-19
dkm_schedule() 15-20
dkm_shrink() 15-23
dkm_sync() 15-25
dkm_unlock() 15-26
DRA
API 16-1
header files 16-1
dra_construct() 16-2
dra_del_locked() 16-5
dra_del_record() 16-6
dra_destroy() 16-7
Index - 1
1-1600-1003-01
Index
dra_find_inseq() 16-8
dra_find_record() 16-9
dra_get_dkm_addr() 16-11
dra_get_dkm_id() 16-12
dra_get_num_recs() 16-12
dra_lock_seg_priv() 16-13
dra_new_record() 16-13
dra_relock_async() 16-15
dra_relock_sync() 16-16
dra_rls_lock() 16-17
dra_rls_seq_priv() 16-18
dra_validate() 16-19
DSM
API 5-1
header files 5-1
linking library 5-1
dsm_attach() 5-2
dsm_destroy() 5-4
dsm_detach() 5-5
dsm_get() 5-6
dsm_getopts() 5-8
dsm_getstat() 5-10
dsm_rdlock() 5-12
dsm_rdlock_rec() 5-14
dsm_rdrule() 5-16
dsm_rdrule_rec() 5-17
dsm_setopts() 5-22
dsm_setstat() 5-23
dsm_unlock() 5-25
dsm_unrule 5-26
dsm_wrlock() 5-27
dsm_wrlock_rec() 5-30
dsm_wrrule() 5-19
dsm_wrrule_rec() 5-20
G
GW
API 8-1
header files 8-1
linking library 8-1
gw_isup_get_cic() 8-2
gw_mtp_dest_stat() 8-10
gw_mtp_flow_ind() 8-2
gw_mtp_rct_ind 8-6
Index - 2
gw_mtp_rct_req() 8-6
gw_mtp_tfa_req() 8-8
gw_mtp_tfc_req() 8-7
gw_mtp_tfp_req() 8-9
gw_mtp_tfr_req() 8-8
gw_mtp_upu_req() 8-3
gw_mtp_xfer_ind() 8-4
gw_mtp_xfer_req() 8-5
gw_register() 8-10
gw_sccp_modify_CdPA() 8-12
gw_sccp_modify_CgPA() 8-13
gw_sccp_parse_UDT() 8-14
gw_sccp_parse_UDTS() 8-15
H
header files
Alarm 6-1
APM 3-1
DKM 15-1
DRA 16-1
DSM 5-1
GW 8-1
MTP 7-2
OAM 4-1
SCCP 9-1
SPM 2-1
TCAP 10-1
TCAP extended 12-1
I
ISDN-UP Call Control Library 13-1
ISUP
API 13-1
ISUP AoC
API 14-1
linking 14-1
isup_aoc_apmase_analyse() 14-5
J
JAIN ISUP API Library 13-29
JAIN Provider Interface 13-31
JAIN Stack Interface 13-31
1-1600-1003-01
Index
JAIN TCAP API library 10-57
L
linking
Alarm library 6-1
APM library 3-1
DSM library 5-1
GW library 8-1
ISUP AoC 14-1
MTP library 7-3
OAM library 4-2
SCCP library 9-1
SPM library 2-1
network extensions 2-70
TCAP library 10-1
M
Mnemonics 1-4
MTP
API 7-1
header files 7-2
linking library 7-3
routing type definition 7-2
MTP, Message Transfer Part 7-1
mtp_decode_pc() 7-4
mtp_encode_pc() 7-6
mtp_flow_ind() 7-7
mtp_info() 7-9
mtp_info_ind() 7-10
mtp_init_api() 7-11
mtp_intercept_ind () 7-13
mtp_intercept_req () 7-12
mtp_ni() 7-14
mtp_pc_bytes() 7-15
mtp_pc_size() 7-16
mtp_pc2cluster() 7-17
mtp_pc2member() 7-18
mtp_pc2network() 7-19
mtp_protocol() 7-20
mtp_spc() 7-21
mtp_subpc2pc() 7-22
mtp_up_offset() 7-23
mtp_variant() 7-24
mtp_xfer_ind() 7-25
mtp_xfer_req() 7-26
mtp_xfer2_req () 7-27
N
network extensions
SPM 2-70
Notations and Conventions 1-3
O
OAM
API 4-1
header files 4-1
linking library 4-2
oam_alarm() 4-3
oam_alias 4-3
oam_almevent() 4-5
oam_almgrp() 4-6
oam_connection() 4-7
oam_cpc() 4-8
oam_gt() 4-9
oam_gtentry() 4-10
oam_host() 4-11
oam_isup() 4-12
oam_isupcct() 4-14
oam_isupcgrp() 4-15
oam_isupnode() 4-17
oam_isuptmr() 4-19
oam_l2cs() 4-20
oam_l2flow() 4-22
oam_l2timer() 4-24
oam_l3timer() 4-25
oam_line() 4-26
oam_link() 4-27
oam_linkstat() 4-29
oam_localsubsys() 4-31
oam_lset() 4-32
oam_lsetstat() 4-34
oam_mate() 4-35
oam_mtp() 4-36
oam_ntwk() 4-38
oam_port() 4-39
oam_retrieve() 4-40, 4-41
Index - 3
1-1600-1003-01
Index
oam_route() 4-43
oam_rtset() 4-45
oam_sccp() 4-47
oam_sltimer() 4-48
oam_snsp() 4-49
oam_sp() 4-50
oam_ss7board() 4-52
oam_strdalm() 4-53
oam_subsys() 4-54
oam_tcpcon() 4-55
OMAP, Operations Maintenance and
Administration Part 4-1
P
PM API Library 17-1
pm_admin() 17-9
pm_deregister() 17-4
pm_listen() 17-5
pm_notify() 17-6
pm_register() 17-2
pm_status() 17-5
R
Related Documents 1-3
S
SCCP
API 9-1
header files 9-1
linking library 9-1
sccp_ConnectCnf() 9-4
sccp_ConnectInd() 9-6
sccp_ConnectReq() 9-7
sccp_ConnectRsp() 9-8
sccp_CoordCnf() 9-9
sccp_CoordInd() 9-9
sccp_CoordReq() 9-10
sccp_CoordRsp() 9-11
sccp_DataInd() 9-12
sccp_DataReq() 9-13
sccp_DisconnectInd() 9-14
sccp_DisconnectReq() 9-15
Index - 4
sccp_NoticeInd 9-19
sccp_PCstateInd() 9-20
sccp_reg() 9-23
sccp_StateInd() 9-25
sccp_StateReq() 9-26
sccp_UnidataInd() 9-27
sccp_UnidataReq() 9-28
Signaling Connection Control Part (SCCP) 9-1
Signaling System 7 (SS7) 1-1
SPM
API 2-1
header files 2-1
linking library 2-1
SPM, Service Provider Module 2-1
spm_alarm() 2-2
spm_display() 2-15
spm_fopen() 2-16
spm_getalarm() 2-18
spm_gethiwat() 2-19
spm_getlowat() 2-20
spm_getoprmode() 2-22
spm_getregtime() 2-26
spm_getsrvtype() 2-27
spm_getusrinfo() 2-28
spm_getusrstat() 2-30
spm_inet_addr() 2-70
spm_inet_host() 2-72
spm_inet_ntoa() 2-70
spm_log() 2-31
spm_loop() 2-33
spm_notify() 2-34
spm_open() 2-44
spm_palarm() 2-45
spm_rcv() 2-47
spm_sethiwat() 2-50
spm_setlowat() 2-51
spm_setusrinfo() 2-55
spm_snd() 2-56
spm_strerror() 2-58
spm_trigger() 2-61
spm_tstart() 2-63
spm_unbind() 2-65
spm_xlate_ipcaddr() 2-67
1-1600-1003-01
Index
spm_xlate_ipckey() 2-66
spm_xlate_ipcmsg() 2-67
spm_xlate_reginfo() 2-68
SS7 Factory 13-30
T
TCAP
API 10-1
header files 10-1
linking library 10-1
TCAP extended
API 12-1
header files 12-1
TCAP Transaction Recovery Functions 10-37
tcm_get_msg_priority_n() 10-56
tcm_get_priority_n() 10-55
tcm_getcomp_n() 10-37
tcm_getdlgp_n() 10-40
tcm_getrid() 10-39
tcm_open_n() 10-41
tcm_putcomp_n() 10-46
tcm_putdlgp_n() 10-48
tcm_rcv_n() 10-49
tcm_rlstrid() 10-51
tcm_set_priority_n() 10-54
tcm_snd_n() 10-52
tcm_close() 10-2
tcm_getcomp() 10-3
tcm_getdlgid() 10-4
tcm_getdlgp() 10-5
tcm_getldflag() 10-7
tcm_getldsopt() 10-9
tcm_getpolicy() 10-11
tcm_open() 10-15
tcm_putcomp() 10-20
tcm_putdlgp() 10-21
tcm_rcv() 10-22
tcm_rlsdlgid() 10-24
tcm_rmtclose() 10-29
tcm_rmtopen() 10-25
tcm_setldflag() 10-30
tcm_setldsopt() 10-32
tcm_setpolicy() 10-33
tcm_snd() 10-34
tcr_close 11-10
tcr_getldflag 11-6
tcr_getldsopt 11-8
tcr_open 11-2
tcr_setldflag 11-6
tcr_setldsopt 11-8
tcx_get_acg_ind() 12-2
tcx_get_bear_cap() 12-2
tcx_get_bill_ind() 12-3
tcx_get_buss_grp() 12-4
tcx_get_ccsan() 12-5
tcx_get_cf_status() 12-5
tcx_get_com_id() 12-6
tcx_get_digits() 12-7
tcx_get_dn_to_ls() 12-8
tcx_get_duration() 12-8
tcx_get_ic_ind() 12-9
tcx_get_octet_par() 12-10
tcx_get_par() 12-10
tcx_get_pin() 12-12
tcx_get_priv_digits() 12-13
tcx_get_ref_id() 12-14
tcx_get_tr_id() 12-14
tcx_get_tstamp_par() 12-15
tcx_put_acg_ind() 12-2
tcx_put_bear_cap() 12-2
tcx_put_bill_ind() 12-3
tcx_put_buss_grp() 12-4
tcx_put_ccsan() 12-5
tcx_put_cf_status() 12-5
tcx_put_com_id() 12-6
tcx_put_digits() 12-7
tcx_put_dn_to_ls() 12-7
tcx_put_duration() 12-8
tcx_put_ic_ind() 12-9
tcx_put_octet_par() 12-10
tcx_put_par() 12-10
tcx_put_par_str() 12-11
tcx_put_pin() 12-12
tcx_put_priv_digits() 12-13
tcx_put_ref_id() 12-13
tcx_put_tr_id() 12-14
tcx_put_tstamp_par() 12-15
Index - 5

d7 160 Api

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

d7 160 Api

Încărcat de

Drepturi de autor:

Formate disponibile

1-1600-1003-01

Distributed7 API Reference Manual

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

NOTICES AND WARRANTY INFORMATION

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

ALL RIGHTS RESERVED

Copyright 2007 - 2009

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

General ............................................................................................................................. 1-1

Scope ................................................................................................................................. 1-1

Chapter Overview ............................................................................................................ 2-1

SPM API Library ............................................................................................................ 2-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview ............................................................................................................ 3-1

APM API Library ............................................................................................................ 3-2

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview ............................................................................................................ 4-1

OAM API Library ........................................................................................................... 4-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview ............................................................................................................ 5-1

Chapter Overview ............................................................................................................ 6-1

Chapter Overview ............................................................................................................ 7-1

Using the MTP API Library ........................................................................................... 7-1

MTP API Library ............................................................................................................ 7-2

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview ............................................................................................................ 8-1

Chapter Overview ............................................................................................................ 9-1

SCCP API Library .......................................................................................................... 9-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview .......................................................................................................... 10-1

TCAP API Library ........................................................................................................ 10-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

TCAP Transaction Recovery Functions .................................................................... 10-37

Chapter Overview .......................................................................................................... 11-1

Chapter Overview .......................................................................................................... 12-1

Extended TCAP API Library ....................................................................................... 12-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview .......................................................................................................... 13-1

ISUP Call Control Library ........................................................................................... 13-1

Chapter Overview .......................................................................................................... 14-1

Chapter Overview .......................................................................................................... 15-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Chapter Overview .......................................................................................................... 16-1

Chapter Overview .......................................................................................................... 17-1

PM API Library ............................................................................................................. 17-1

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Copyright NewNet Communication Technologies

Distributed7 API Reference Manual

Updated the part number and version.