1.1 Introduction

1.2 ISDN

1.2.1 ISDN Carriers

1.2.2 ISDN Service Messages

1.3 IMGT Service Software Components

1.3.1 The NMS ISDN Management API Function Library

1.3.2 The Header Files

1.3.3 IMGT Service Downloadable Object Module

1.3.4 The Demonstration Program

1.4 The readme File

1.5 Other Components

1.5.1 Natural Access

1.5.2 Contexts and Event Queues

1.5.3 oamsys and the OAM Configuration File

1.5.4 agmon and the AG Configuration File

1.6 Developing an IMGT Application

1.1 Introduction

The NMS ISDN Management API Developer's Reference Manual explains how to use the NMS ISDN management (IMGT) service library to interact with the ISDN stack to put B channels in and out of service in certain ISDN variants.

This manual is targeted to developers of telephony and voice applications who are using Natural Access, version 3.0 and higher. This document defines telephony terms where applicable, but assumes that the reader is familiar with telephony concepts and switching. It also assumes that the user is familiar with the C programming language.

1.2 ISDN

Integrated Services Digital Network (ISDN) is an evolving international standard for networking a wide range of services, including voice and non-voice services. The network is completely digital, from one end to the other: voice information is digitized and sent in digital form. Signaling information is sent separately from voice information, using a method called common channel signaling (CCS).

The NMS ISDN Management API is a Natural Access service that interacts with the NMS ISDN protocol stack to give access to information and/or messages that are not part of traditional call control. The Management API allows you to put B channels in and out of service and query the stack about the status of a particular B channel.

A Management application runs independently from a call control application, whether your call control application is based on the ISDN Messaging API or the Natural Call Control (NCC) API.

This chapter:

• Briefly discusses ISDN software and ISDN carriers.

• Lists and describes the IMGT software components.

• Lists and describes the other hardware and software components required.

• Outlines the application development process.

• Lists steps for developing a Management application.

1.2.1 ISDN Carriers

ISDN is transmitted over standard T1 and E1 carriers. These are typically four-wire digital transmission links. T1 is used mainly in the United States, Canada, Hong Kong, Taiwan, and Japan. E1 is used throughout most of the rest of the world.

Data on a T1 or E1 trunk is transmitted in channels. Each channel carries information digitized at 64000 bits per second (bps). For primary rate ISDN, T1 carries 24 channels. E1 carries 32 channels.

With primary-rate ISDN, the channels are usually used as follows:

• On a T1 trunk, 23 of the 24 channels carry data: voice, audio, data and/or video signals. These channels are called bearer channels (B channels). On an E1 trunk, 30 of the 32 channels are bearer channels.

• On a T1 or E1 trunk, one channel carries signaling information for all B channels. This is called the D channel.
  
  
  Figure 1. T1 Trunk (Standard Configuration)

In setups with multiple T1 ISDN trunks, a Non-Facility Associated Signaling (NFAS) configuration is often used. In this configuration, the D channel on one of the ISDN trunks carries signaling for all channels on several other trunks. This leaves channel 24 free on each of the other trunks to be used as another B channel. (See Figure 2.)

Figure 2. Sample NFAS Configuration

NFAS configurations are not supported on E1 trunks.

1.2.2 ISDN Service Messages

Service messages are layer 3 ISDN messages used by ISDN to put B channels in either the in or out of service state. These messages are only supported on North American variants: 4ESS, 5ESS, and DMS-100. For 5ESS only, service messages can also be used to place the entire interface in or out of service.

There are two types of IMGT service maintenance messages:

• SERVICE messages
  In some ISDN variants, SERVICE messages can be exchanged to put B channels in and out of service. Through the Management API library, the user can send SERVICE messages to the trunk and receive SERVICE or SERVICE ACKNOWLEDGE events. When a SERVICE message is received, the ISDN stack automatically sends a SERVICE ACKNOWLEDGE. (No primitives are needed to send a SERVICE ACKNOWLEDGE.) The application can also query the stack to learn the status of a particular B channel.
  The handling of SERVICE messages is implemented for the following variants:

  
  -	 DMS
  
  
  -	 AT&T 4ESS
  
  
  -	 AT&T 5ESS
  
  

• RESTART messages
  Through the Management library, the user can be notified whenever a RESTART message is received.
  When a RESTART message is received, the ISDN stack automatically sends a RESTART ACKNOWLEDGE.

For the DMS variant, the reception of a RESTART message resets the status of the B channel to the in service setting.

1.3 IMGT Service Software Components

The NMS ISDN software package includes the following IMGT service software components:

• The NMS ISDN Management function library

• Header files

• The downloadable object module

• A demonstration program, with source code file, makefile, and executable

The sections that follow briefly describe each of these components.

1.3.1 The NMS ISDN Management API Function Library

The Management source library runs on the host PC. The library is used by the application program to interact with the ISDN protocol stacks running on the board in order to put B channels in and out of service in certain ISDN variants.

The library is supplied as extensions to the ADI library. It is a dynamic-link library (DLL) under Windows NT and Windows 2000, and a shared object under UNIX. The libraries have different names under different operating systems.

Operating System	Natural Access Library Name(s)
Windows NT and Windows 2000	imgtapi.lib, imgtapi.dll
UNIX	libimgtapi.so

1.3.2 The Header Files

Two header files for the Management API are supplied with NMS ISDN software:

Filename	Description
imgtdef.h	Contains API function prototypes, event codes, and data structures associated with the API functions.
imgtsvc.h	Contains primitive codes and data structures associated with the primitives.

1.3.3 IMGT Service Downloadable Object Module

The ISDN Management service downloadable object module file contains the basic low-level software that a board requires to support the ISDN Management service. The module is loaded from the host into on-board memory when the board boots.

In order to use the IMGT service, download the ISDN Management module and the appropriate ISDN downloadable module for your ISDN variant. For details, see the NMS ISDN Installation Manual.

1.3.4 The Demonstration Program

A demonstration program (imgtdemo) is included, with its source code file, makefile, and executable. Use this demonstration program to start the IMGT service. You can then monitor B-channel status and put it in and out of service. For specific details, see Chapter 5.

1.4 The readme File

Information about the Management API that does not appear in the documentation appears in the readme file for the NMS ISDN software package. The file is named readme_isdn.txt. Consult this file to learn where the IMGT service software components are located after installation.

1.5 Other Components

In addition to the NMS ISDN software, you will need the following components to build an IMGT application:

• One or more NMS board with a T1 or E1 trunk interface.

• Natural Access version 4.0 or later. (Natural Access 3.x is supported, but new features, such as multiple CCID configurations, are not available.)

• oamsys - the board loading program. This utility is supplied with boards and with Natural Access 4.0 and later.

• agmon - for use with Natural Access 3.x. This utility is used in place of oamsys

  WARNING:

  Natural MicroSystems obtains board-level approvals certificates for supported countries. Some countries require that you obtain system-level approvals before connecting a system to the public network. To learn what approvals you require, contact the appropriate regulatory authority in the target country.

  .

1.5.1 Natural Access

Natural Access is a complete development environment for telephony applications. It provides a standard set of telephony functions grouped into logical services, each of which has a standard API. Natural Access services provide functions for telephony-related tasks such as call control, tone generation and detection, and voice playing and recording.

Natural Access includes a service that controls switching on MVIP-compliant devices. Use this service to make or break connections, send patterns, sample data, etc. This service supports both MVIP-95 and MVIP-90 specifications. Alternatively, you can use the swish standalone utility to control switching interactively or in a batch mode.

For general information about installing and using Natural Access, see the Natural Access documentation.

1.5.2 Contexts and Event Queues

A context organizes services and accompanying resources around a single processing context. A context usually represents an application instance controlling a single telephone call.

Natural Access provides multi-processing support. Multiple Natural Access application processes can perform tasks on behalf of the same context (referred to as context sharing). Natural Access applications can transfer control of contexts (for example, contexts associated with individual telephone calls) to other Natural Access applications (referred to as context hand-off).

An event queue is the communication path from a Natural Access service to an application. A Natural Access service generates events indicating certain conditions or state changes and sends them to applications through the event queue.

The Natural Access Server (ctdaemon) must be running for the NMS OAM service to be available. If ctdaemon is stopped, all dependent applications receive an error.

For detailed information about Natural Access, see the Natural Access Developer's Reference Manual.

1.5.3 oamsys and the OAM Configuration File

When you set up your system, you specify configuration information for all boards in the system in an OAM system configuration file. This configuration file references keyword files that specify if a board performs MVIP switching, which board is the MVIP clock master, which software modules to transfer to the board's memory on startup (including which TCPs to load), and other settings. To learn how to modify NMS OAM configuration files to set up your NMS ISDN software, see the NMS ISDN Installation Manual and the NMS OAM System User's Manual.

Run oamsys to configure your boards based on the information in the OAM configuration file. oamsys transfers all software modules specified in the file to each board, and performs any other configuration activities needed. You should also start oammon, which monitors the boards for errors and other events.

Use oamcfg to change system information or board parameters after the system is running.

oamsys, oamcfg, and oammon are installed with Natural Access and require Natural Access to run in Server mode. For more information, see the NMS OAM System User's Manual Manual.

1.5.4 agmon and the AG Configuration File

For systems running versions of Natural Access prior to 4.0, agmon is used instead of OAM. When you set up your system, specify configuration information for all boards in the system in an AG configuration file. This information specifies if a board performs MVIP switching, which board is the MVIP clock master, which software modules to transfer to the board's memory on startup (including which TCPs to load), and other settings. To learn how to modify your AG configuration file to set up your NMS ISDN software, see the NMS ISDN Installation Manual and the AG Runtime Configuration and Developer's Manual.

Run agmon to configure your boards based on the information in the AG configuration file. agmon transfers all software modules specified in the file to each board, and performs any other configuration activities needed. Leave it running so that it can monitor the boards for errors and other events.

Whenever you make a change to your AG configuration file, restart agmon to make your changes effective.

agmon is installed with versions of Natural Access prior to 4.0. For more information, see the AG Runtime Configuration and Developer's Manual.

1.6 Developing an IMGT Application

Perform the following steps to create an IMGT application:

Step	Where Step is Documented
1. Install digital trunk interface boards in a system and any other boards you need in your application.	The installation manuals for your boards
2. Install Natural Access.	Natural Access Developer's Reference Manual or the Natural Access installation booklet
3. Install the NMS ISDN software for each target country or variant that your application will be used in.	NMS ISDN Installation Manual
4. Edit your configuration file so it describes all boards in your system.	The NMS ISDN Installation Manual, the installation manuals for your boards, and the NMS OAM System User's Manual (prior to Natural Access 4.0, the AG Runtime Configuration and Developer's Manual)
5. Test your hardware installation.	The installation manuals for your boards
6. Write your management application.	This manual and the Natural Access documentation set