9.1 Introduction

9.2 Demonstration Programs and Utilities

9.3 Layer 3 Call Control Demonstration: isdndemo

9.3.1 Using NFAS With isdndemo

9.3.2 Structure and Coding (Single-Threaded Version)

Program Initialization

Main Program Loop

Processing ISDN Call Control Events

Processing ADI Events

Using Loopback Events

9.3.3 Structure and Coding (Multi-Threaded Version)

Program Initialization

Main Program Loop

9.3.4 ISDN Call Control

isdndemo Call Control State Machine

Sending Messages to the ISDN Protocol Stack

Handling Inbound Calls

Placing Outbound Calls

Disconnecting Calls

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.5 Stack Traffic Analysis Tool: dectrace

9.5.1 Creating a Log File for dectrace

9.5.2 Messages Decoded by dectrace

Q.931/Q.932 Message Types

Information Elements

9.5.3 Sample dectrace Output

9.6 Stack Traffic Filtering Tool: itrace

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 board is executing.

• MVIP switching is correctly configured.

Refer to the appropriate installation manual for details on installation.

9.2 Demonstration Programs and Utilities

The following demonstration programs and utilities 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.
dectrace	Decoding tool for messages sent or received by the AG ISDN protocol stack.
itrace	Filtering tool for AG ISDN stack messages captured by the board monitoring utility.

Other programs that illustrate use of the software in the Natural Call Control configuration are supplied with AG ISDN. These programs are documented in the AG ISDN for Natural Call Control Developer's Manual.

9.3 Layer 3 Call Control Demonstration: isdndemo

isdndemo

Uses the AG ISDN Messaging API to place and receive calls on an ISDN trunk. Shows:

• An example of a digital trunk application that uses the layer 3 ISDN signaling interface.

• How to use the AG ISDN Messaging API to perform call control on a primary rate ISDN trunk.

• An example of an application that uses Non-Facility Associated Signaling (NFAS) group configurations.

• An example of an application that supports duplicate NAI values in the configurations.

The program supports a single T1 or E1 trunk or NFAS group. Multiple instances of the program can be run to support multiple trunks or groups. With a command-line option, the user can specify the ISDN country/signaling system variant to use.

isdndemo creates multiple threads to handle B channel processing (voice channel processing) and a separate thread to handle all processing of the D channel message stream. A single-threaded version of the program that uses a single process to control all channels on the trunk or NFAS group is also supplied.

The default behavior of the program is to accept inbound calls. Outbound calls can be generated by specifying the appropriate command-line option.

isdnReleaseBuffer, isdnSendMessage, isdnStartProtocol

• One or more digital trunk interface boards.

• CT Access version 4.0 or later. (CT Access 3.x is supported, except when there are multiple NAI values.)

• AG ISDN software.

• The nocc.tcp file.

isdndemo [options]

where options is one or more of the following:

Option	Meaning	Defaults
-?	Display help screen, and terminate.	N/A
-a	Network access identifier of trunk to use.	0
-b boardno	Board number.	0
-d dialstring	Digit string to dial.	1234567
-I time	Time (in milliseconds) to wait after releasing an outbound call before placing the next one.	1000
-l	Log ISDN messages. Messages are logged to the file isdnbb.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 EuroISDN1 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 50 Taiwan	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

1 Use for the following countries: Austria, Denmark, Finland, Greece, Iceland, Ireland, Italy, Liechtenstein, Luxembourg, Netherlands, Norway, Portugal, Russia, Spain, Switzerland. Also use for China and Singapore.

For example, the following command line specifies USA National ISDN 2 on the second board in a system and places calls on the first 10 channels:

isdndemo -b 1 -p 20 -o 10

When isdndemo is run with no command-line options, the program defaults to board 0. (The board number for each board is specified in the configuration file.) The program automatically determines the board type, and runs one of the following protocols:

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

When no command-line options are specified, the program assumes that it is not placing any outbound calls but is only accepting inbound calls.

To start two instances of isdndemo so one instance places calls to the other:

1. Set up your boards in a configuration that allows one trunk to talk with another.
   For example, install two boards, and connect a cable between their trunk connectors. Do not link the boards together over the MVIP bus. For NFAS configurations, you can also install a single CG 6000C, AG Quad or AG Dual board, and connect a cable between two trunk connectors.

2. Start oamsys to configure your boards as described in your configuration file (use agmon for CT Access versions prior to 4.0).

3. 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 -p 20
                  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.

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.

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.

9.3.1 Using NFAS With isdndemo

You can set up two instances of isdndemo to demonstrate placing and receiving calls on trunks in Non-Facility Associated Signaling (NFAS) with duplicate NAI values in the 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	· Board 0, trunk 0, NAI 4, supports D channel · Board 0, trunk 1, NAI 5, no D channel
NFAS_2	· Board 0, trunk 2, NAI 4, supports D channel · Board 0, trunk 3, NAI 5, no D channel

To run isdndemo in NFAS configuration:

1. Set up the board configuration as described in the previous table.
   Define each NFAS group in your configuration file. (For more information, see your AG ISDN Installation Manual. (One of the sample configuration file listings in this manual matches the previously illustrated configuration.)

2. Start oamsys to configure your boards as described in your configuration file. (Use agmon for CT Access versions prior to 4.0.)

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 1 -n -p 20
          isdndemo -N 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 */
         {
         { 0, 0, 0, 4, 1},       /* group, board, trunk, nai, D-Ch flag, etc. */
         { 0, 0, 1, 5, 0}
         };
   
         struct NFAS_trunk NFAS_2[] =  /* Option NFAS = 2 */
         {
         { 1, 0, 2, 4, 1},
         { 1, 0, 3, 5, 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 configuration file).

   • trunk is the number of the trunk that the structure line specifies.

   • nai is the NAI number of the trunk.

   • 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 on page 242.

4. Make sure your configuration file matches the configuration you described in the code.

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 board being used. For example, it ensures that the user is not attempting to utilize more voice channels than exist on the physical trunk.

If the command line is valid, the isdndemo function open_port is called. open_port opens one CTA context for each voice channel it will handle, and 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 oamsys¹ when the boards are loaded (see the installation manual for your board for more information). This binding in the CTA context structure makes it unnecessary to remake 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. 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 ctaWaitEvent. This function waits for an event.

If an event occurs, ctaWaitEvent returns. 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 the next section, Processing ISDN Call Control Events. Otherwise, isdndemo proceeds as discussed in the following section, Processing ADI Events.

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.
  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_cta_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 the Using Loopback Events 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_cta_event.

The following table gives the loopback events used in the demonstration program.

Event Name		Direction		Description
demo_connect_in	--------------B Channel-----------		--------------D Channel-----------	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				Requests 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, they 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 previously discussed, when a call arrives on the D channel, a loop back event is created to begin 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 in Figure 38 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

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 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, ensuring that a DSP resource is available to handle the call. Then, 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 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, 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, vcedStop 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

lapddemo

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.

• How to access the stack if duplicate NAI values are configured.¹
  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. ¹CT Access 4.0 and later.

isdnReleaseBuffer, isdnSendMessage, isdnStartProtocol, isdnStopProtocol

• One or more digital trunk interface boards.

• CT Access version 3.0 or later.

• AG ISDN software.

• The nocc.tcp file.

lapddemo [options]

where options are one or more of the following:

Option	Meaning	Defaults
-b boardno	Number of board to use. (Board numbers are specified for boards in the configuration file.)	0
-n	Causes lapddemo to configure itself for the Network Terminator side.	Not specified (lapddemo configured for Terminal Equipment)
-a nai	Network Access Identifier (NAI)	None.
-g nfas_group	NFAS group number, for duplicate NAI values. (CT Access 4.0 and later.)	None.
-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. 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

When lapddemo is launched, it does the following:

1. It parses command-line arguments, and makes sure all arguments are valid and do not conflict.

2. It initializes CT Access.

3. It starts the ISDN protocol stack on the 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.

4. It sends a SABME message on the trunk to establish the data link.

5. If the user types s, the program sends a SETUP message to the trunk. Otherwise, it waits for messages from the line.

6. 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.

To launch lapddemo:

1. Set up your configuration file to describe your board and software configuration. For more information, see the AG ISDN Installation Manual and the OAM System User's Manual (or the AG Runtime Configuration and Developers Manual for CT Access 3.x).

2. Run oamsys to initialize your hardware and make your configuration file changes effective. (Use agmon for CT Access versions prior to 4.0.)

3. If necessary, modify the demonstration configuration file lapddemo.cfg. For more information, see Section 9.4.1.

4. To start the demonstration, enter:
   lapddemo [options]
   ... where options is one or more of the command line options described in the Usage section.
   lapddemo sends a SABME message on the trunk to establish the data link.

5. 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.

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.

lapddemo consists of the following files:

File	Description
lapddemo.c	The main application program code.
isdnlib.c	A library of functions used by the main program to build correct Q.931 messages.
lapdlib.h	The prototypes for the functions contained in isdnlib.c plus the definitions of the structures used by those functions.
decisdn.h	The definitions used to build Q.931 Information Elements and Messages. Can be found in c:\nms\ctaccess\demos\isdndemo\ (for Windows NT) opt/nms/ctaccess/demos/isdndemo/ (for UNIX)
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 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 command
  ...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.

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 previously described.

• cause and command values are case-sensitive.

The following is 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      K      # send CALL PROCEEDING after receiving a SETUP
    K      o      C      # send CONNECT after sending CALL PROCEEDING
    C      o      T      # start timer T after receiving a CONNECT
    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

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 and the definitions of the structures used by the functions. decisdn.h contains the defines used to build Q.931 information elements and messages.

9.5 Stack Traffic Analysis Tool: dectrace

dectrace

Decodes and displays messages sent or received by the AG ISDN protocol stack, that were previously captured in a log file by the board monitoring utility (oammon, or agmon for CT Access 3.x).

dectrace decodes:

• Q.931/Q.921 messages sent/received by the stack (when the stack is running in any mode).

• ACU primitives exchanged by the application and the stack (when the stack is running in ACU stack mode).
  Note: By default, the log file does not contain stack message data. In order to provide data in this file that dectrace can process, the agtrace and/or itrace utilities must be used. For details, see Section 9.5.1.

dectrace [-f srcfile] [-d tmask] [-b boardno] [-a nai] [-g group]
[-c callref]

...where:

Option	Meaning	Default
-a nai	Decode only the messages on the specified NAI.	All NAIs.
-b boardno	Decode only the messages from/to board boardno.	All boards.
-c callref	Decode only the messages with call reference callref.	All call references.
-d tmask	Decoding mask (for Q.931 decoding). See below for possible values.	TIME STAMP + MESSAGE + CALL_REF + IE + IE CONT + ISDN_MSG
-f srcfile	File to be decoded.	agerror.log
-g group	Decode only the messages for the specified NFAS group.	All NFAS groups.

The following table describes tmask:

mask	Mnemonic	Description
8000	BUFFER	Prints the whole hex buffer.
2000	PROTOCOL DISC	Decodes the protocol discriminator.
1000	CALL REF	Decodes the call reference.
0800	MESSAGE	Decodes the message type.
0400	INFO ELEM	Decodes the information element ID.
0200	INFO ELEM CONT	Decodes the data contents of the IE.
0100	DATA LINK	Decodes the commands/events at the DL interface.
0080	TIME STAMP	Includes a time stamp before the messages.
0008	ISDN_MSG	Decodes the ISDN messages.
0004	ACU_MSG	Decodes the ACU messages.

To run dectrace:

1. Run agtrace and/or itrace to instruct the AG driver to send AG ISDN protocol stack trace messages to the board monitoring utility.

2. Run the board monitoring utility to configure your boards as described in your configuration file, and to enable error logging.

3. Exercise the AG ISDN protocol stack.

4. Run dectrace, specifying the log file on the command line. By default, the name of this file is agerror.log.

dectrace is supplied as executables as well as source code. If you need to recompile dectrace, do one of the following:

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

For more information, see the readme file that came with the AG ISDN software package.

Source files for this program are:

• dectrace.c

• dectrace.h

• decisdn.c

• decisdn.h

9.5.1 Creating a Log File for dectrace

dectrace reads the log file created by agmon (agerror.log). By default, this file does not contain AG ISDN protocol stack messages. To enable the board monitoring utility to log messages from the stack, use either (or both) of the following utilities:

• agtrace -- agtrace takes, as parameters, a bitmask, the board number (default 0) and the channel number (default 0). To trace the AG ISDN protocol stack, set the 0x80000 bit. To enable oammon to display/log the trace, use the -f option.
  If using CT Access versions prior to 4.0, set the 0x1000 bit to enable agmon to display/log the trace. When preparing a log file for the dectrace utility, setting other bits is not recommended because, when two processes send messages to agmon to be logged at the same time, the result is undefined (e.g. the printed buffers/messages may be "merged").

• itrace -- The ISDN stack includes many entities (layer 1 entities, layer 2 entities, layer 3 entities, management entities, timer entities, etc.) which send debug messages to the board monitoring utility. itrace limits the number of ISDN entities that send debug messages to the board monitoring utility (by default all the entities are enabled). itrace takes as arguments a flag (on/off), board number, NAI number and a list of entities (from the file isdntype.h). An exclamation point (!) before the entity list enables the sending of buffers along with the messages.

For example, to prepare an agerror.log for board 0, NAI 1, containing Q.931 buffers, enter the following:

agtrace 801000 0
itrace off 0 1 *
itrace on 0 1 !Dd

... and then run your application.

To prepare an agerror.log for board 0, NAI 1, containing only ACU messages, enter the following:

agtrace 801000 0
itrace off 0 1*
itrace on 0 1 AC

... and then run your application.

The agerror.log file can be found:

• In the directory you ran oammon from (or agmon for CT Access 3.x) in NT systems

• Under /var/opt/nms/ag in Unix systems

Tracing is not recommended when performing very heavy load tests, because the high number of accesses to the log file caused by tracing may dramatically decrease the coprocessor's capability to handle the messages.

Note: Embedded errors in agerror.log (likely in case of load tests or if you do not follow the indications given in this section about limiting the number of messages or buffers sent to the board monitoring utility) may not be handled correctly by dectrace. Note: When reporting a potential problem in the AG ISDN stack, please include the whole agerror.log file (do not use itrace in this case) and not the output of dectrace.

9.5.2 Messages Decoded by dectrace

dectrace decodes ISDN layer 3 messages in accordance with Q.931/Q.932 specifications, except where differently noted (see the following table).

Q.931/Q.932 Message Types

All the message types defined in the Q.931/Q.932 specifications are decoded by dectrace. They are shown in the following table:

Message	Hex Value	Notes
Escape to nationally specific message type:
MSG_ESCAPE	0x00	Q.931
Call establishing messages:
MSG_ALERTING	0x01	Q.931
MSG_CALL_PROC	0x02	Q.931
MSG_PROGRESS	0x03	Q.931
MSG_SETUP	0x05	Q.931
MSG_CONNECT	0x07	Q.931
MSG_SETUP_ACK	0x0D	Q.931
MSG_CONNECT_ACK	0x0F	Q.931
Call information phase messages:
MSG_USER_INFO	0x20	Q.931
MSG_SUSPEND_REJ	0x21	Q.931
MSG_RESUME_REJ	0x22	Q.931
MSG_HOLD	0x24	Q.932
MSG_SUSPEND	0x25	Q.931
MSG_RESUME	0x26	Q.931
MSG_HOLD_ACK	0x28	Q.932
MSG_SUSPEND_ACK	0x2D	Q.931
MSG_RESUME_ACK	0x2E	Q.931
MSG_HOLD_REJ	0x30	Q.932
MSG_RETRIEVE	0x31	Q.932
MSG_RETRIEVE_ACK	0x33	Q.932
MSG_RETRIEVE_REJ	0x37	Q.932
Call clearing messages:
MSG_DISCONNECT	0x45	Q.931
MSG_RESTART	0x46	Q.931
MSG_RELEASE	0x4D	Q.931
MSG_RESTART_ACK	0x4E	Q.931
MSG_RELEASE_COMP	0x5A	Q.931
Miscellaneous messages:
MSG_SEGMENT	0x60	Q.931
MSG_FACILITY	0x62	Q.931
MSG_REGISTER	0x34	Q.932
MSG_NOTIFY	0x6E	Q.931
MSG_STATUS_ENQ	0x75	Q.931
MSG_CONGESTION_CTRL	0x79	Q.931
MSG_INFO	0x7B	Q.931
MSG_STATUS	0x7D	Q.931
Messages not defined in Q.931/Q.932:
MSG_SERVICE	0x0F	According with 235-900-342 (5ESS)
MSG_SERVICE_ACK	0x07	According with 235-900-342 (5ESS)

Information Elements

All the information element identifiers defined in the Q.931/Q.932 specifications are decoded. They are shown in the following table:

Message	Hex Value	Notes
Single octet information elements:
IE_SHIFT	0x90	All values from 0x90 to 0x9F indicate shift
IE_MORE_DATA	0xA0	More data
IE_SENDING_COMPL	0xA1	Sending complete
IE_CONG_LEVEL	0xB0	All values from 0xB0 to 0xBF indicate congestion level
IE_REPEAT_IND	0xD0	All values from 0xD0 to 0xDF indicate repeat indicator
Variable length information elements:
IE_SEGMENTED	0x00	Segmented message
IE_BC	0x04	Bearer capability
IE_CAUSE	0x08	Cause
IE_CALL_ID	0x10	Call identity
IE_CALL_STATE	0x14	Call state
IE_CHANNEL_ID	0x18	Channel identification
IE_FACILITY	0x1C	Facility
IE_PROGRESS_IND	0x1E	Progress indicator
IE_NSF	0x20	Network-specific facilities
IE_NOTIFY_IND	0x27	Notification indicator
IE_DISPLAY	0x28	Display
IE_DATE_TIME	0x29	Date/time
IE_KEYPAD	0x2C	Keypad facility
IE_INFO_RQ	0x32	Information request
IE_SIGNAL	0x34	Signal
IE_SWITCHHOOK	0x36	Switchhook
IE_FEATURE_ACK	0x38	Feature activation
IE_FEATURE_IND	0x39	Feature indication
IE_SERVICE_PROF	0x3A	Service profile identification
IE_ENDPOINT_ID	0x3B	Endpoint identifier
IE_INFO_RATE	0x40	Information rate
IE_END_TO_END_DELAY	0x42	End to end transit delay
IE_TDSI	0x43	Transit delay selection and indication
IE_PKT_BIN_PAR	0x44	Packet layer binary parameters
IE_PKT_WIN_SIZE	0x45	Packet layer window size
IE_PKT_SIZE	0x46	Packet size
IE_MIN_THR_CLASS	0x47	Minimum throughput class
IE_CALLING	0x6C	Calling party number
IE_CALLING_SUB	0x6D	Calling party subaddress
IE_CALLED	0x70	Called party number
IE_CALLED_SUB	0x71	Called party subaddress
IE_REDIRECTING	0x74	Redirecting number
IE_TRANSIT_SEL	0x78	Transit network selection
IE_REST_IND	0x79	Restart indicator
IE_LLC	0x7C	Low layer compatibility
IE_HLC	0x7D	High layer compatibility
IE_UUI	0x7E	User-user info
IE_ESCAPE	0xFF	Escape for extension
Information elements not defined in Q.931/Q.932:
IE_CHANGE_STATUS	0x01	Change status according to 235-900-342 (5ESS)

The following information elements contents are fully decoded according with the Q.931/Q.932 specifications:

Message	Hex Value	Notes
Single octet information elements:
IE_SHIFT	0x90	All values from 0x90 to 0x9F indicate shift
IE_SENDING_COMPL	0xA1	Sending complete
Variable length elements:
IE_BC1	0x04	Bearer capability
IE_CAUSE2	0x08	Cause
IE_CALL_STATE	0x14	Call state
IE_CHANNEL_ID	0x18	Channel identification
IE_PROGRESS_IND	0x1E	Progress indicator
IE_NSF	0x20	Network-specific facilities
IE_DISPLAY	0x28	Display
IE_CALLING	0x6C	Calling party number
IE_CALLING_SUB	0x6D	Calling party subaddress
IE_CALLED	0x70	Called party number
IE_CALLED_SUB	0x71	Called party subaddress
IE_REDIRECTING	0x74	Redirecting number
IE_REST_IND	0x79	Restart indicator
IE_LLC1	0x7C	Low layer compatibility
IE_HLC1	0x7D	High layer compatibility
IE_UUI	0x7E	User-user info
Information elements not defined in Q.931/Q.932:
IE_CHANGE_STATUS	0x01	Change status according with 235-900-342 (5ESS)

1 Some rarely used octets in these IEs are not decoded by the program (in this case the program prints "octet xx not decoded" where xx is the octet number). 2 Some variant-specific call values have been added to the list of Q.931-specified values.

If the program does not decode the contents of an information element, it prints:

IE ie_name: NOT DECODED

If the program does not decode the contents of one octet inside one information element, it prints:

octet octet_number: NOT DECODED

If the program encounters a value (whether in the message type, in the information element ID or in the information element contents) that is not in accordance with the Q.931/Q.932 specifications (except where differently noted), it prints: RESERVED.

If the program encounters a value (whether in the message type, in the information element ID, or in the information element contents) that the program does not recognize, it prints: UNKNOWN. (Unknown represents a legal value for several fields.)

Note: The presence of RESERVED or UNKNOWN fields in the output of the program does not necessarily indicate a failure: the variant you are running may consider values legal which are illegal in the Q.931/Q.932 specifications.

9.5.3 Sample dectrace Output

The following is a sample of the output of dectrace. In the output text, the arrow after the board number shows if the message was received (<--) or sent (-->).

    43.61 
          protocol discriminator = Q.931 Call Control
          call reference = 01 00  flag = 0
00000101  message type = SETUP   board 00  nai 00  group 00  -->
00000100    IE bearer capability
00000011        length = 0x03 
              octet 3
1-------        extension bit
-00-----        coding standard = CCITT
---00000        information transfer capability = speech
              octet 4
1-------        extension bit
-00-----        transfer mode = circuit mode
---10000        information transfer rate = 64 Kbit/s
              octet 5
1-------        extension bit
-01-----        layer 1 id = layer 1 id
---00010        user info layer 1 = mu law
00011000    IE channel identification
00000011        length = 0x03 
              octet 3
1-------        extension bit
-0------        interface identifier = implicitly identified
--1-----        interface type = PRI
---0----        spare bits = spare bits
----1---        pref/excl = exclusive
-----0--        D-channel ind = not
------01        info channel selection = B1 channel
              octet 3.2
1-------        extension bit
-00-----        coding standard = CCITT
---0----        number/map = number
----0011        channel type = B channel
              octet 3.3
1-------        extension bit
-0000001        channel number = 0x01 
01110000    IE called party number
00000100        length = 0x04 
              octet 3
1-------        extension bit
-000----        type of number = unknown
----0000        numbering plan = unknown
              octet 4 etc
                number = 12.

channel number = 0x01 

    43.67   
          protocol discriminator = Q.931 Call Control
          call reference = 01 00  flag = 1
00000010  message type = CALL_PROCEEDING   board 00  nai 00  group 00  <--
00011000    IE channel identification
00000011        length = 0x03 
              octet 3
1-------        extension bit
-0------        interface identifier = implicitly identified
--1-----        interface type = PRI
---0----        spare bits = spare bits
----1---        pref/excl = exclusive
-----0--        D-channel ind = not
------01        info channel selection = B1 channel
              octet 3.2
1-------        extension bit
-00-----        coding standard = CCITT
---0----        number/map = number
----0011        channel type = B channel
              octet 3.3
1-------        extension bit
-0000001        channel number = 0x01 


    45.84   
          protocol discriminator = Q.931 Call Control
          call reference = 01 00  flag = 1
00000001  message type = ALERTING   board 00  nai 00  group 00  <--

9.6 Stack Traffic Filtering Tool: itrace

itrace

The utility is used in order to limit the amount of debug ISDN messages sent to the monitoring utility. The ISDN stack includes many entities (layer 1 entities, layer 2 entities, layer 3 entities, management entities, timer entities, etc.) which exchange messages. The debug information is sent to the monitoring utility when the agtrace bit 0x800000 is set, and can be filtered by this utility based on board number, NAI number, NFAS group number and entity. By default, all the entities are enabled.

itrace [on|off] [board#] [nai#] [entity_list|*] [<nfas_ group#>]

...where:

Option	Meaning
on|off	Enables or disables logging.
board#	Board number.
nai#	Network Access Identifier.
entity_list	String of entity IDs (as defined in isdntype.h.). If the string starts with !, the buffers associated with the messages will also be sent to the monitoring utility.
*	Used to refer to all entities.
nfas_ group#	NFAS group number for configurations with duplicate NAI values.

To run itrace:

1. Run agtrace with mask 801000 to enable the ISDN protocol stack messages to be passed to the board monitoring utility.

2. Run itrace utility to enable or disable messages from/to entities in the entity_list string.
   Note: itrace can be run at any time of execution. Message logging is changed dynamically.

itrace is supplied as an executable and located in:

• WindowsNT: c:\nms\bin\itrace.exe

• UNIX: /opt/nms/bin/itrace

Example 1

Enable messages only between ENT_APPLI and ENT_CC on board 0, nai 1:

agtrace 801000 0   Start tracing
itrace off 0 1 *   Disable all ISDN stack traffic on board0, nai 1.
itrace on 0 1 AC  Enable logging messages between `A' and `C'
                   entities on board 0, nai 1
(`A' = ENT_APPLI = application entity and 
`C' = ENT_CC = Call Control Entity.)

Example 2

Enable messages and buffers between ENT_DL_D and ENT_PH_D on board 0, nai 1, nfas group 0:

agtrace 801000 0    Start tracing
itrace off 0 1 * 0  Disable all ISDN stack truffic on board0, 
                    nai 1, NFAS group 0.
itrace on 0 1 !Dd 0 Enable logging messages between `D' and `d'
                    entities on board 0, nai 1, NFAS group 0