If...	lapddemo...
SETUP is received	Sends an ALERTING message, and then a CONNECT message.
CONNECT ACK is received	Starts timer T
Timer T expires	Sends a DISCONNECT message
DISCONNECT is received	Sends a RELEASE message.
RELEASE is received	Sends a RELEASE COMP message.

(Page 1 of 1 in this chapter)

Chapter 9

Demonstration Programs

9.1 Introduction

9.2 Demonstration Programs

9.3 Layer 3 Call Control Demonstration Program: isdndemo

: 9.3.1 Using the isdndemo NFAS Configuration Demonstration
: 9.3.2 Structure and Coding (Single-Threaded Version)
: 9.3.3 Structure and Coding (Multi-Threaded Version)
: 9.3.4 ISDN Call Control
: 9.3.5 Identifying Trunks

9.4 LAPD Demonstration Program: lapddemo

: 9.4.1 The lapddemo Configuration File
: 9.4.2 lapddemo Structure and Coding Features

9.1 Introduction

This chapter describes the functionality and structure of the demonstration programs supplied with your AG ISDN software package.
AG ISDN is shipped with source code for the demonstration programs. Each demonstration program is shipped as an executable program and with its source and makefiles.
Before you start the demonstration programs, ensure that: CT Access is properly installed. The AG board is executing. MVIP switching is correctly configured.
Refer to the appropriate installation manual for details on installation.

9.2 Demonstration Programs

The following demonstration programs provided with AG ISDN are documented in this chapter: Program Description isdndemo Uses AG ISDN Messaging API to place and receive calls on an ISDN trunk. lapddemo Establishes a data link and sends and receives Q.931 messages.
Other programs are supplied with AG ISDN which illustrate use of the software in the Natural Call Control configuration. These programs are documented in the AG ISDN for Natural Call Control Developer's Manual.

Program	Description
`isdndemo`	Uses AG ISDN Messaging API to place and receive calls on an ISDN trunk.
`lapddemo`	Establishes a data link and sends and receives Q.931 messages.

9.3 Layer 3 Call Control Demonstration Program: isdndemo

Option	Meaning	Defaults
`-?`	Display help screen, and terminate.	N/A
`-a`	Network access identifier of trunk to use.	`0`
`-b` boardno	AG board number.	`0`
`-d` dialstring	Digit string to dial.	`1234567`
`-I` time	Time (in milliseconds) to wait after releasing a outbound call before placing the next one.	`1000`
`-l`	Log ISDN messages. Messages are logged to the file `isdn`bb`.log`, where bb is the board number.	No logging.
`-n`	Run ISDN protocol stack as NT, not as TE.	TE
`-N` config	NFAS group (`0`, `1` or `2`). Use instead of `-b` option to run in NFAS configuration demonstration mode. For details, see Section 9.3.1.	`0` (None)
`-o` outlines	Number of lines on which to place outbound calls.	`0`
`-O` channel	Defines first B channel on which outbound calls will be placed. (For example, if `-O` is set to 10 and `-o` is set to 5, outbound calls will be placed on channels 10 through 14.)	`0`
`-p` protocol	Protocol variant to run. Allowed values: Value Protocol `3` France Telecom VN6 `8` Northern Telecom DMS 100 `9` INS-1500 NTT `11` EuroISDN ¹ `15` Australian Telecom 1 `16` QSIG `17` Hong Kong Telephone `20` US National ISDN 2 `23` AT&T 5ESS10 `24` AT&T 4ESS `25` Korea	T1 boards: `23` (AT&T 5ESS10) E1 boards: `11` (EuroISDN)
`-Q`	Receive buffer with message containing raw Q.931 version of message.	No extra buffer received.
`-t`	Demonstrates the transparent IE sending feature. Builds a codeset 7 IE (user-specific IE) and attaches it to the next `ACU_CLEAR_CO` (Connect message).	No indicator.
`-T`	Timer for duration of outbound call (in milliseconds), once the call has reached the CONNECTED state.	`15000`

Board Type	Default protocol
T1	AT&T 5ESS10
E1	EuroISDN

Procedure

To start two instances of isdndemo so one instance places calls to the other: Set up your AG boards in a configuration such that one trunk can "talk" to another. For example, install two AG-T1 boards, and connect a cable between their trunk connectors. Do not link the boards together over the MVIP bus. Or you can install a single AG Quad T or AG Dual T board, and connect a cable between two trunk connectors. Start agmon to configure your AG boards as described in your AG configuration file. Invoke one instance of isdndemo for each trunk you will use. Set up one to place calls, and the other to receive calls. Make sure to include the -n (lowercase) option to configure one instance as the NT side. For example: isdndemo -b 0 -n isdndemo -b 1 -p 20 -o 10 Each instance displays actions and events as it runs. In the display, commands from isdndemo to the protocol stack are preceded by: CALL CONTROL <= APPLICATION Events from the protocol stack are preceded by: CALL CONTROL => APPLICATION The arrow indicates the direction of information flow. Following is the text of a log trace of isdndemo receiving an inbound call: Wed Nov 13 16:45:30 CALL CONTROL => APPLICATION msg = ACU_CONN_IN Calling Phone Number = 5086501340 Called Phone Number = 1234567 Connection on physical channel 10 Got a SENDING COMPLETE. service = VOICE CRN 39 Wed Nov 13 16:45:30 CALL CONTROL <= APPLICATION msg = ACU_CONN_RS CRN 39 Wed Nov 13 16:45:30 CALL CONTROL => APPLICATION msg = ACU_ALERT_IN CRN 39 state = WAIT_INCOMING Wed Nov 13 16:45:30 CALL CONTROL => APPLICATION msg = ACU_CONN_CO CRN 39 state = WAIT_INCOMING Wed Nov 13 16:45:51 CALL CONTROL => APPLICATION msg = ACU_CLEAR_IN (network cause = 10) CRN 39 state = ACTIVE Wed Nov 13 16:45:51 CALL CONTROL <= APPLICATION msg = ACU_CLEAR_RS CRN 39 Wed Nov 13 16:45:51 CALL CONTROL => APPLICATION msg = ACU_CLEAR_CO (cause = hang up) (network cause = 10) CRN 39 state = WAIT_CLEARANCE Following is the log trace of isdndemo placing an outbound call: Wed Nov 13 16:40:44 CALL CONTROL <= APPLICATION msg = ACU_CONN_RQ CRN 1 Wed Nov 13 16:40:44 CALL CONTROL => APPLICATION msg = ACU_PROGRESS_IN CRN 1 state = NULL Wed Nov 13 16:40:44 CALL CONTROL => APPLICATION msg = ACU_ALERT_IN CRN 1 state = WAIT_OUTGOING Wed Nov 13 16:40:44 CALL CONTROL => APPLICATION msg = ACU_CONN_CO CRN 1 state = WAIT_OUTGOING Wed Nov 13 16:41:00 CALL CONTROL <= APPLICATION msg = ACU_CLEAR_RQ CRN 1 Wed Nov 13 16:41:00 CALL CONTROL => APPLICATION msg = ACU_CLEAR_CO (cause = hang up) (network cause = 10) CRN 1 state = ACTIVE Note: You may receive the error ctaCreateQueue failure 2a while running isdndemo on a Unix system. This is due to a default limitation on the number of file descriptors that one user process can open. If you receive this error, enter ulimit -n 120 and launch isdndemo again.

Compilation

isdndemo is supplied as executables as well as source code.
If you need to recompile isdndemo, do one of the following: Under this OS... Go to this directory... Enter... Windows NT c:\nms\ctaccess\demos\isdndemo\ nmake UNIX /opt/nms/ctaccess/demos/isdndemo/ make
For more information, see the readme file that came with the AG ISDN software package.

Under this OS...	Go to this directory...	Enter...
Windows NT	`c:\nms\ctaccess\demos\isdndemo\`	`nmake`
UNIX	`/opt/nms/ctaccess/demos/isdndemo/`	`make`

Files

isdndemo consists of the following files: File Description isdndemo.c The main application program with event processing functions. isdndemo.h Header file for the isdndemo program. isdnstmc.c The ISDN state machine implementation. isdnccms.c Functions to build ISDN call control messages (request buffers). os_rts.c Operating-system-specific routines. os_rts.h Operating-system-specific header file. isdnlog.c ISDN event logging mechanism. getopt.c NMS standard distribution. decisdn.h Useful defines for creating and decoding Q.931 information elements.

File	Description
`isdndemo.c`	The main application program with event processing functions.
`isdndemo.h`	Header file for the `isdndemo` program.
`isdnstmc.c`	The ISDN state machine implementation.
`isdnccms.c`	Functions to build ISDN call control messages (request buffers).
`os_rts.c`	Operating-system-specific routines.
`os_rts.h`	Operating-system-specific header file.
`isdnlog.c`	ISDN event logging mechanism.
`getopt.c`	NMS standard distribution.
`decisdn.h`	Useful defines for creating and decoding Q.931 information elements.

9.3.1 Using the isdndemo NFAS Configuration Demonstration

You can set up two instances of isdndemo to demonstrate placing and receiving calls on trunks in Non-Facility Associated Signaling (NFAS) configurations. In this demonstration, one of the two instances places calls, and the other receives them.
isdndemo is hard-coded for a specific board configuration. In this configuration, there are two NFAS groups, designated NFAS_1 and NFAS_2: Configuration Description NFAS_1 Two AG boards: · Board 1, NAI 0, supports D channel · Board 2, NAI 1, no D channel NFAS_2 One AG Quad or AG Dual board: · Board 0, trunk 0, NAI 0, supports D channel · Board 0, trunk 1, NAI 1, no D channel
To run isdndemo in NFAS configuration: 1. Set up the board configuration as described in the table above. Define each NFAS group in your AG configuration file. (For more information, see your AG ISDN Installation Manual. (One of the sample AG configuration file listings in this manual matches the above configuration.) 2. Start agmon to configure your boards as described in your AG configuration file. 3. Invoke one instance of isdndemo for each NFAS group, using the -N option. Set up one to place calls, and the other to receive calls. (This option overrides the -b option.) In addition to the -N (uppercase) option, make sure to include the -n (lowercase) option to configure one instance as the NT side. For example: isdndemo -N NFAS_1 -n isdndemo -N NFAS_2 -p 20 -o 10
If you wish to set up the demonstration with a different NFAS configuration: 1. Modify the NFAS_1 and/or NFAS_2 data structures in isdndemo.c: struct NFAS_trunk NFAS_1[] = /* Option NFAS = 1 */ { { 1, 1, 0, 0, 1}, /* group, board, trunk, nai, D-Ch flag, etc. */ { 1, 2, 0, 1, 0} }; struct NFAS_trunk NFAS_2[] = /* Option NFAS = 2 */ { { 2, 0, 0, 0, 1}, { 2, 0, 1, 1, 0} }; Each structure specifies the NFAS group to be controlled by one instance of isdndemo. Each line in the structure specifies the configuration of a trunk in the group. Each line is formatted as follows: nfasgroup, board, trunk, nai, dchannel ... where: · nfasgroup is the NFAS group the trunk belongs to, · board is the board number (as specified in the AG configuration file), · trunk is the number of the trunk that the structure line specifies, · nai is the NAI number of the trunk, and · dchannel specifies whether the trunk carries the D channel for the group (1 for yes; 0 for no). 2. If you require more than two data structures to describe your NFAS configuration, change the NumberOfNFASTrunks value in isdndemo.c to a value greater than 2. Number your structures NFAS_3, NFAS_4, and so on. 3. Re-compile isdndemo as described under "Compilation" above. 4. Make sure your AG configuration file matches the configuration you described in the code.

Configuration	Description
`NFAS_1`	Two AG boards: · Board 1, NAI 0, supports D channel · Board 2, NAI 1, no D channel
`NFAS_2`	One AG Quad or AG Dual board: · Board 0, trunk 0, NAI 0, supports D channel · Board 0, trunk 1, NAI 1, no D channel

9.3.2 Structure and Coding (Single-Threaded Version)

The single-threaded version of isdndemo uses a single thread (process) to control multiple voice ports. This section discusses the generic structure of the program focusing on the single-threaded version.
Figure 36 illustrates the program structure of the single-threaded version of the demonstration program: Figure 36. Single-Threaded Demonstration Program Structure

Program Initialization

The demonstration program program creates and stores a number of application contexts. These contexts are kept in an array of structures stored in an allocated memory area. Each application context has its own handle to provide voice functionality to the voice line. Also in this allocated memory area are a number of flags and parameters global to the system. This data structure is called mem_area and is defined in the file isdndemo.h. A global pointer to this structure, SM, is maintained in the program.
isdndemo first parses the command-line options and determines whether they are valid for the AG board being used. For example, it ensures that the user is not attempting to utilize more voice channels than exist on the physical trunk. To do this, isdndemo calls adiGetBoardInfo immediately after the AG driver is opened with adiOpenDriver. If there are any inconsistencies, the program exits with a warning message.
It If the command line is valid, the isdndemo function open_port is called. open_port opens a number of CTA contexts. It opens one CTA context for each voice channel it will handle, plus one CTA context for the D channel. For example, for a T1 trunk, the application opens 24 CTA contexts (23 CTA contexts for B channels plus one for the D channel). For an E1 trunk, the application opens 31 CTA contexts (30 for voice and one for the D channel).
To open a CTA context, the stream and timeslot to be used by the DSP resource must be specified. The open_port function also requires the number of the B channel to associate with the opened CTA context. The B channel supplied with the DSP stream and timeslot is the default connection made by agmon¹ when the AG boards are loaded (see the installation manual for your AG board for more information). This binding in the CTA context structure makes it unnecessary to re-make any switching connections. If less than the full number of B channels are started, calls on B channel timeslots not associated with opened CTA contexts are rejected in this demonstration program.
Once the CTA contexts have been allocated, the application starts the "no call control" TCP (NOCC.tcp) on all CTA contexts except the last one. This enables voice processing capability on all CTA contexts except the one reserved as a communication path to the D channel.
When all of the TCPs have been started, isdn_start starts the ISDN protocol stack on the last CTA context, to activate the D channel. To start the protocol stack, the application invokes isdnStartProtocol with the NAI specified on the command line (or NAI 0 if not specified). If the protocol stack starts properly, the event ISDNEVN_START_PROTOCOL occurs with a return value of SUCCESS. (Any other return value indicates that a stack failed to start. isdndemo terminates if a problem occurs.) The ISDNEVN_START_ PROTOCOL event is processed by isdn_start. This function does not return until the ISDN protocol stack has been started.
Once the protocol stack has been started, isdndemo is ready to accept inbound calls.
If isdndemo is set up to dial out (via its command-line options), it places outbound calls by invoking make_call. Note that if the system is placing outbound calls on fewer timeslots than are available in the system, the first n timeslots are used, where n is the number of channels assigned to call placement with the -o command-line option. For example, if isdndemo is run with the command:

isdndemo-o 10
and the board is an AG-E1 board, outbound calls are placed on logical timeslots 0 through 9. isdndemo accepts inbound calls on any idle channel.
isdndemo is extremely simple. When an inbound call occurs, the system accepts the call, plays a prompt, and then waits for a disconnect. In outbound mode, isdndemo plays the same prompt but initiates hang up after hold_time seconds (hold_time is an internal program constant).

Main Program Loop

The main program loop is an infinite loop. At the top of the loop, it calls os_wait_event_sem. This function waits for an event. If no event occurs within a specified amount of time, os_wait_event_sem returns GOT_TIMEOUT.
If an event occurs, GOT_EVENT is returned. isdndemo retrieves the event by calling adiFetchAndProcess. isdndemo then identifies the CTA context associated with the event by checking the userid. isdndemo does so to determine whether the event is a call control event from the ISDN D channel or an ADI event directed to voice channel processing. If the event is an ISDN call control event, isdndemo proceeds as discussed in "Processing ISDN Call Control Events" below. Otherwise, isdndemo proceeds as discussed in "Processing ADI Events" below.

Processing ISDN Call Control Events

If the userid indicates that a received event is an ISDN call control event, the D channel state machine function, process_isdn_event, is called to process the event.
Each ISDN message is a composite event. Within the event is an ISDN packet, which contains an ISDN message. Each message is processed based on the following parts:

The sender and message codes. The combination of these codes forms a unique message. Consequently, the processing of all messages is based on who the sender is.
For call control messages (connection indication, hang up, etc.), the sender is always ENT_CC - the call control entity. If process_isdn_event determines that the sender is the call control entity, the function process_cc_state is called to process the event.
Note that a debugging routine called LogReceivedMessage is called in process_isdn_message. This function shows how to decode numerous ISDN message buffers in a single routine.

The connection ID. The connection id is a handle to a call on a B channel. It is used to identify the call in all communications between the ACU and the demonstration program. When an incoming call arrives, the protocol stack assigns it a connection id. When the program places a call, it assigns a connection id to the call. When a call is disconnected, the connection id is freed. The id can then be assigned to a new call by the protocol stack or the program.
The range of connection ids available for a trunk is between 0 and ACU_MX_CALLS (defined in isdnacu.h). In an NFAS group containing multiple trunks, there will be ACU_MX_CALLS connection ids for each NAI. The connection id and NAI together identify a particular call.
The connection id assigned to an incoming call by the protocol stack is the highest available unused value. For example, if 60 connection ids are available for a group, and connection ids 59 and 58 are already allocated to calls, the protocol stack assigns id 57 to the next call.
To avoid any chance of collision, when placing outgoing calls, the demonstration program assigns connection ids beginning with 0. It keeps track of which connection ids are in use and which are available.
The detailed processing of ISDN information is performed in the function process_cc_state. This state machine is described in a subsequent section.

Processing ADI Events

If the userid indicates that the event is associated with a voice channel, the B channel state machine, process_adi_event, is called. This routine processes the standard set of ADI events, such as ADIEVN_PLAYDONE. It also receives a special set of events that are generated by the D channel state machine, in order to maintain the functional partition between B and D channel processing. Refer to Section for more details on the meaning and usage of these events. No D channel events are passed to this routine.

Using Loopback Events

isdndemo uses ctaQueueEvent to maintain separation between call control processing of the message stream on the D channel and application (B channel) processing. Events received by the D channel are looped back to a B channel CTA context for application processing.
This application separates the application processing from the call control processing. Because of this, a mechanism is required for initiating application processing. This mechanism works as follows: when the D channel state machine connects to an incoming call (receiving, for example, an ACU_CONN_CO message from the D channel), a loop back event is created indicating the arrival of the call. When we exit the D channel processor to the main loop, the loopback event is waiting in the event queue. Since this event has a userid associated with a particular B channel event, the main loop invokes the B channel processing code in process_adi_event.
The following table gives the loopback events used in the demonstration program. Event Name Direction B Channel D Channel Description demo_connect_in Indicates receipt of an incoming call. demo_connect_out Indicates that outbound call is connected. demo_remote_hangup Indicates that a remote hang up has occurred. demo_make_call Requests the D channel state machine to place a call. demo_initiate_hangup Request the D channel state machine to hang up a call.

Event Name	Direction B Channel D Channel	Description
`demo_connect_in`		Indicates receipt of an incoming call.
`demo_connect_out`		Indicates that outbound call is connected.
`demo_remote_hangup`		Indicates that a remote hang up has occurred.
`demo_make_call`		Requests the D channel state machine to place a call.
`demo_initiate_hangup`		Request the D channel state machine to hang up a call.

9.3.3 Structure and Coding (Multi-Threaded Version)

The program structure of the multi-threaded version of isdndemo is fundamentally identical to that of the single threaded version described in Section 9.3.2. This section describes the differences in functionality of the multi-threaded version of the program.
Figure 37 shows the structure of the multi-thread demonstration program.

Program Initialization

The multi-threaded version of isdndemo is similar to the single-threaded version. The key difference is that each B channel CTA context is run in its own thread. Each thread allocates its own driver handle and muxhandle. These handles are placed in the same CTA context structure used by the single threaded version of the program. The initialization section creates a single thread for each of the requested application instances, passing the B channel timeslot owned by the thread during its lifetime. The functionality of each of these threads is identical to the ADI event processing code in the single-threaded version. Figure 37 illustrates the program structure of the multi-threaded version of the demonstration program. Figure 37. Multi-Threaded Demonstration Program Structure
If the application is placing outbound calls, these calls are initiated in the main thread.

Main Program Loop

The main process thread is an infinite while loop. This loop performs only D channel processing. All B channel processing is performed by the threads. As discussed above, when a call arrives on the D channel, a loop back event is created to "kick-off" application processing. In the multi-threaded version, this message is placed in the event queue of the appropriate B channel thread. The loopback event demo_connect_in is processed by the B channel process, just as in the single-threaded version of isdndemo.

9.3.4 ISDN Call Control

When an ISDN event occurs, the event ISDNEVN_RCV_MESSAGE is in the CT Access event ID in the event structure. To decode the message, the message code, sender, recipient, and connection ID information is unpacked. All messages also contain additional information in a message-specific buffer. The debugging function LogReceivedMessage provides an example of how to decode many of these messages. The actual processing of these buffers is done in the state functions contained in isdnstmc.c. For example, inbound call message buffers are decoded in process_wait_incoming.

isdndemo Call Control State Machine

In isdndemo, a simple state machine is implemented to handle ISDN call control. This is illustrated in Figure 38: Figure 38. isdndemo State Machine
This state machine is implemented in the module isdnstmc.c.
The following table shows the correspondence between the states shown above and the functions implemented in isdnstmc.c:

State Name

Description

Function

ST_NULL

Idle

process_null

ST_AWAITING_INCOMING_CALL

Wait for incoming call

process_wait_incoming

ST_AWAITING_CONNECT

Waiting to connect

process_wait_incoming

ST_AWAITING_OUTGOING_CALL

Wait for outgoing call

process_wait_out

ST_ACTIVE

Active - call connected

process_active

ST_AWAITING_CLEARANCE

Wait for clear confirmation

process_wait_clear

State Name	Description	Function
`ST_NULL`	Idle	process_null
`ST_AWAITING_INCOMING_CALL`	Wait for incoming call	process_wait_incoming
`ST_AWAITING_CONNECT`	Waiting to connect	process_wait_incoming
`ST_AWAITING_OUTGOING_CALL`	Wait for outgoing call	process_wait_out
`ST_ACTIVE`	Active - call connected	process_active
`ST_AWAITING_CLEARANCE`	Wait for clear confirmation	process_wait_clear

Sending Messages to the ISDN Protocol Stack

To send a message to the ISDN protocol stack, isdndemo first builds a message-specific data buffer. For example, to place an outbound call, cc_build_conn_rq builds the buffer for a connection request.
Note: The file isdnccms.c contains functions to build most requests. The functions implemented in this module use the macros defined in isdnacu.h to construct the messages. We strongly recommend that you use the macros given in this file to both encode and decode ISDN message buffers.
Once the message buffer for the protocol stack has been built, initialize_imsg builds an ISDN_MESSAGE structure. This structure contains information such as the message code, which entity the message is for, from whom it was sent, etc.
Finally, mySendMessage sends the message to the AG board via a call to isdnSendMessage.

Handling Inbound Calls

When an inbound call is first detected, an ACU_CONN_IN message (connection indication message) is detected coming from ENT_CC. This event causes the function process_cc_state to be called.
isdndemo requires that a CTA context exists for the B channel on which the call is taking place. This ensures that a DSP resource is available to handle the call. Once this is satisfied, a state transition from the NULL state to the state ST_AWAITING_INCOMING_CALL is assigned to the CTA context.
In the function process_wait_incoming, the called (DNIS) and calling number (ANI) are decoded. To accept the call, a connect response message (ACU_CONN_RS) is built. The event ACU_CONN_CO is a confirmation that the call has been established and causes a transition to the active state.

Placing Outbound Calls

To place an outbound call, cc_build_conn_rq builds the "setup" message. Once the command is built, initialize_imsg initializes the ISDN message structure and sends the message to the AG board by invoking isdnSendMessage. The message sent is ACU_CONN_RQ.
At this point, ACU_PROGRESS_IN may be received from the network followed by ACU_ALERT_IN. The connection ID associated with this event is the user ID supplied to initialize_imsg and passed in the element add.conn_id field. If the call is successfully connected, ACU_CONN_CO is received; otherwise a hang up indication, ACU_CLEAR_CO, is received.

Disconnecting Calls

If the remote end hangs up, an ACU_CLEAR_IN event is detected. The application responds to this with an ACU_CLEAR_RS. The final event is an ACU_CLEAR_CO. The first event is a clearing indication; the second is a clearing confirmation.
To initiate a hang up, the system issues an ACU_CLEAR_RQ. The expected response event is ACU_CLEAR_CO.
Note that in each CTA context for the B channels, a flag is kept to indicate whether or not the channel is playing. This is because CT Access does not automatically stop playing (or recording) if a disconnect occurs. If a hang up is detected and the system is still playing, adiStopPlaying is called to stop the function. There are alternative strategies to cope with this situation. For example, closing and reopening the CTA context will stop all DSP-related functions associated with the CTA context, including playing and recording.

9.3.5 Identifying Trunks

In the MVIP switching model, B channels are numbered from 0 to 23 on a T1 trunk and from 0 to 29 on an E1 trunk. These numbers are contiguous. The ISDN protocol stack requires the physical timeslot number and not the NMS logical number. The physical timeslot numbers on a T1 trunk are 1 to 24 with the D channel occupying channel 24. On an E1 trunk, the physical timeslot numbers are 0 to 31. Channel 0 is for synchronization, 1 through 15 are B channels, 16 is the D channel, and 17 through 31 are the remaining B channels. The functions NMS_logical_to_physical and NMS_physical_to_logical perform the necessary conversions.

9.4 LAPD Demonstration Program: lapddemo

Name

lapddemo

Purpose

Establishes a data link and sends and receives Q.931 messages. Demonstrates: How an application accessing the stack at the LAPD interface can establish a data link on an ISDN trunk. How to build raw Q.931 messages and send them to the trunk. Note: Messages built and sent with this demonstration program are based on standard Q.931 specifications (Blue Book) and may not be accepted or allowed in some switch variants.

Featured Functions

isdnReleaseBuffer, isdnSendMessage, isdnStartProtocol, isdnStopProtocol

Requirements

One or more AG digital trunk interface boards.
CT Access version 2.1 or later.
AG ISDN software.
The nocc.tcp TCP file.

Usage

lapddemo [options]
where options is one or more of the following:

Option

Meaning

Defaults

-b boardno

Number of AG board to use. (Board numbers are specified for AG boards in the AG configuration file.)

0

-n

Causes lapddemo to configure itself for the Network Terminator side.

Not specified (lapddemo configured for Terminal Equipment)

-v verboselevel

Verbosity level. Valid values are:
Value Meaning
0 Show no messages
1 Show SETUP messages only
2 Show all ISDN messages

2

-f filename

Name of configuration file to be read. This file describes the behavior of the program in terms of what Q.931 messages will be sent or received.
Note that specifications for outgoing calls are not given in the default configuration file. You must make additions to this file in order for the demonstration program to achieve the connected state for outbound calls.

lapddemo.cfg

Option	Meaning	Defaults
`-b` boardno	Number of AG board to use. (Board numbers are specified for AG boards in the AG configuration file.)	0
`-n`	Causes `lapddemo` to configure itself for the Network Terminator side.	Not specified (`lapddemo` configured for Terminal Equipment)
`-v` verboselevel	Verbosity level. Valid values are: Value Meaning 0 Show no messages 1 Show SETUP messages only 2 Show all ISDN messages	`2`
`-f` filename	Name of configuration file to be read. This file describes the behavior of the program in terms of what Q.931 messages will be sent or received. Note that specifications for outgoing calls are not given in the default configuration file. You must make additions to this file in order for the demonstration program to achieve the connected state for outbound calls.	`lapddemo.cfg`

Functional Overview

When lapddemo is launched, it does the following: It parses command-line arguments, and makes sure all arguments are valid and do not conflict. It initializes CT Access. It starts the ISDN protocol stack on the AG board specified on the command-line, either as Terminal Equipment (TE) or as Network Equipment (NT), with the specified network operator variant and country variant. It sends a SABME message on the trunk to establish the data link. If the user types s, the program sends a SETUP message to the trunk. Otherwise, it waits for messages from the line. If a Q.931 message is received, the program decodes information from the message, and responds with an appropriate message, specified in the configuration file. For example, after receiving a SETUP message, it might send an ALERTING message.

Procedure

To launch lapddemo: Set up your AG configuration file to describe your board and software configuration. For more information, see the AG ISDN Installation Manual and your AG Runtime Configuration and Developers Manual. Run agmon to initialize your hardware and to make your AG configuration file changes effective. If necessary, modify the demonstration configuration file lapddemo.cfg. For more information, see Section 9.4.1. To start the demonstration, enter: lapddemo [options] ... where options is one or more of the command line options described above. lapddemo sends a SABME message on the trunk to establish the data link. Press s. The program sends a SETUP message with a called number value, a calling number value, a B channel number and an encoding flag. These values are specified in the configuration file lapddemo.cfg. By default, they are the following: Called number: 12345 Calling number: 678 B channel: 12 Encoding: A law If the data link is established, the program exchanges Q.931 messages with the remote party, as described in the configuration file. By default, the following exchanges are made: If... lapddemo... SETUP is received Sends an ALERTING message, and then a CONNECT message. CONNECT ACK is received Starts timer T Timer T expires Sends a DISCONNECT message DISCONNECT is received Sends a RELEASE message. RELEASE is received Sends a RELEASE COMP message.

Compilation

lapddemo is supplied as executables as well as source code.
If you need to recompile lapddemo, do one of the following: Under this OS... Go to this directory... Enter... Windows NT c:\nms\ctaccess\demos\lapddemo\ nmake UNIX /opt/nms/ctaccess/demos/lapddemo/ make
For more information, see the readme file that came with the AG ISDN software package.

Under this OS...	Go to this directory...	Enter...
Windows NT	`c:\nms\ctaccess\demos\lapddemo\`	`nmake`
UNIX	`/opt/nms/ctaccess/demos/lapddemo/`	`make`

Files

lapddemo consists of the following files: File Description lapddemo.c The main application program code. isdnlib.c Contains a library of functions used by the main program to build correct Q.931 messages. lapdlib.h Contains the prototypes for the functions contained in isdnlib.c plus the definitions of the structures used by those functions. decisdn.h Contains the defines used to build Q.931 Information Elements and Messages. Can be found in c:\nms\ctaccess\demos\isdndemo\. lapddemo.cfg An example of a configuration file for this demonstration program.

File	Description
`lapddemo.c`	The main application program code.
`isdnlib.c`	Contains a library of functions used by the main program to build correct Q.931 messages.
`lapdlib.h`	Contains the prototypes for the functions contained in `isdnlib.c` plus the definitions of the structures used by those functions.
`decisdn.h`	Contains the defines used to build Q.931 Information Elements and Messages. Can be found in `c:\nms\ctaccess\demos\isdndemo`\.
`lapddemo.cfg`	An example of a configuration file for this demonstration program.

9.4.1 The lapddemo Configuration File

lapddemo reads a configuration file to determine what Q.931 messages to send, and how to respond to incoming messages. A sample configuration file, lapddemo.cfg, is supplied with the demonstration. The configuration file to use is specified on the command-line with the -f option. Note: Specifications for outgoing calls are not given in the default configuration file. You must make additions to this file in order for the demonstration program to achieve the connected state for outbound calls.
Two types of information appear in the file: Parameters, and associated values. Each parameter appears on a separate line, followed by whitespace and then the assigned value. The following parameters can be set in the configuration file: Parameter Meaning Allowed values Default !D Called number (applies to the SETUP message). One or more digits 12345 !A Calling number (applies to the SETUP message). One or more digits 678 !B B-channel (applies to the SETUP message). Decimal value 12 !E Encoding (applies to the SETUP message). 2=mu law, 3=A law 3 !C Cause (applies to the DISCONNECT message). Decimal value 16 Message exchanging rules. Each rule specifies a command for lapddemo to send or a task for lapddemo to perform when certain events happen (such as when a message is received or a timer expires). Each rule appears on a separate line. A rule is formatted as follows: cause direction response ...where: · cause is a message or event code, from the following table: Code Message/Event S SETUP A ALERTING K CALL PROCEEDING P PROGRESS C CONNECT c CONNECT ACK D DISCONNECT R RELEASE r RELEASE COMP T TIMER T (2 s) t TIMER T (1 s) · direction specifies whether lapddemo performs the response when a message is received, a message is sent, or a timer expires: Indicator Meaning i Incoming message or an expiring timer. lapddemo takes the action if message cause is received, or timer cause expires. o Outgoing message. lapddemo takes the action when it sends message cause. · command is the message for lapddemo to send or the timer for lapddemo to set when cause happens according to direction. command can be any value from the code table above.
The following syntax rules apply in the file: Text between a pound symbol (#) and the end of a line is ignored by the application. The character ! indicates that the following symbol is a parameter. Any line not beginning with a # or ! is a message exchange rule, formatted as described above. cause and command values are case-sensitive.
The following is a listing of the lapddemo.cfg file included with lapddemo: # File: lapddemo.cfg # configuration file for lapddemo ################################################################## # parameters # # !D = called number (applies to the SETUP msg) # !A = calling number (applies to the SETUP msg) # !B = B channel (decimal value) (applies to the SETUP msg) # !E = encoding ( 2 = mu Law, 3 = A Law) (applies to the SETUP msg) # !C = cause (decimal value) (applies to the DISCONNECT msg) # ################################################################## # parameter value !D 12345 !A 678 !B 12 !C 16 !E 3 ################################################################## # command list # # S = SETUP # A = ALERTING # K = CALL PROCEEDING # P = PROGRESS # C = CONNECT # c = CONNECT ACK # D = DISCONNECT # R = RELEASE # r = RELEASE COMP # T = TIMER T (2 s) # t = TIMER T (1 s) # ################################################################## # cause dir command S i A # send ALERTING after receiving a SETUP A o C # send CONNECT after sending ALERTING c i T # start timer T after receiving a CONNECT ACK T i D # send a DISCONNECT when timer T expires D i R # send a RELEASE after receiving DISCONNECT R i r # send a RELEASE COMP after receiving RELEASE

Parameter	Meaning	Allowed values	Default
`!D`	Called number (applies to the SETUP message).	One or more digits	`12345`
`!A`	Calling number (applies to the SETUP message).	One or more digits	`678`
`!B`	B-channel (applies to the SETUP message).	Decimal value	`12`
`!E`	Encoding (applies to the SETUP message).	2=mu law, 3=A law	`3`
`!C`	Cause (applies to the DISCONNECT message).	Decimal value	`16`

Code	Message/Event
`S`	SETUP
`A`	ALERTING
`K`	CALL PROCEEDING
`P`	PROGRESS
`C`	CONNECT
`c`	CONNECT ACK
`D`	DISCONNECT
`R`	RELEASE
`r`	RELEASE COMP
`T`	TIMER T (2 s)
`t`	TIMER T (1 s)

Indicator	Meaning
`i`	Incoming message or an expiring timer. `lapddemo` takes the action if message cause is received, or timer cause expires.
`o`	Outgoing message. `lapddemo` takes the action when it sends message cause.

9.4.2 lapddemo Structure and Coding Features

The main function (in lapddemo.c) accepts and parses the command line options, reads the configuration file and establishes the data link. At this point the program can either send a SETUP message to the trunk (if the user types s) or wait for messages from the line.
Note: The SETUP message sent by lapddemo contains the following information elements only: bearer capability, channel id, calling number and called number. Some switch variants may require additional information elements.
If a Q.931 message is received, the program decodes information from the message, such as the protocol discriminator (i.e. Q.931 CC), the call reference value, the message type (i.e. SETUP) and other data. It responds with an appropriate message, specified in the configuration file. For example, after receiving a SETUP message, it might send an ALERTING message.
The state machine is very simple and only takes into consideration the state of the data link. There are only two states: Idle and Data Link Established. The program has no knowledge of the "state of a call", so it can even be configured to break Q.931 message protocol rules (e.g.., by sending a SETUP message after receiving a SETUP message). It is the user's responsibility to configure the program properly.
Q.931 messages are built using functions from isdnlib.c, such as BuildSetup, BuildAlerting, and so on. lapdlib.h contains the prototypes for these functions, plus the definitions of the structures used by the functions. decisdn.h contains the defines used to build Q.931 information elements and messages.

(Page 1 of 1 in this chapter)

¹ Note that this presumes that ENABLEMVIP in the file ag.cfg is set to NO. For details, see Section 3.3.

tech_support@nmss.com