2.1 Introduction

2.2 Setting Up the Natural Access Environment

2.3 Setting Up the DTM Service

2.3.1 Initializing the DTM Service

2.3.2 Opening the DTM Service

2.4 Monitoring a Digital Trunk

2.4.1 DTM Handles

2.4.2 Retrieving Trunk Status Information

2.4.3 Generating Alarms

2.5 The Development Environment

2.1 Introduction

The Digital Trunk Monitor is a C function library component of Natural Access. It is implemented as the DTM service, managed by the ADI service manager.

The DTM service is a DLL under Windows NT, and it is a shared library under UNIX. You must have Natural Access, including the ADI service, installed on your system to build and run applications using the DTM service. This chapter describes a programming model for using the DTM service in the Natural Access environment.

2.2 Setting Up the Natural Access Environment

Application setup for Natural Access consists of the following steps:

1. Initialize Natural Access for the process.

2. Create event queues.

3. Create contexts for each event queue.

4. Open services on each context.

Services are opened on a context by calling ctaOpenServices, passing a context handle and a list of service descriptors. Each service descriptor specifies the name of the service, service manager, and service-specific arguments.

The call to ctaOpenServices is asynchronous and returns immediately. When all services have been opened, CTAEVN_OPENSERVICES_DONE is returned to the application. Natural Access supports opening and closing services on an as-needed basis to share scarce resources.

There can be only one open instance of each service per context. Once the DTM service is opened, the application functions invoke the DTM service. The following figure shows an example context with the DTM and ADI services open; the DTM service is associated with trunks on two telephony boards:

Figure 1. Natural Access With the ADI Service and the DTM Service

ctaCloseServices closes one or more services on a context. The function is asynchronous and returns immediately. You must wait for the completion event, CTAEVN_CLOSE_SERVICES_DONE, to be returned on the event queue before you can assume that the specified services are closed. An application can close or re-open one service at a time, without affecting other open services.

ctaDestroyContext destroys a context. All currently opened services on the context are closed. The function is asynchronous and returns immediately. You must wait for the CTAEVN_DESTROY_CONTEXT_DONE event to be returned on the event queue before assuming that the context is destroyed and resources are released.

ctaDestroyQueue destroys the queue and all contexts associated with the queue. This is a synchronous function, so the application will remain blocked until all cleanup and close activity has completed. If the services and contexts were already closed, the function will return immediately.

2.3 Setting Up the DTM Service

Before you can call functions from the DTM service, the application must initialize and open the DTM service on an open context.

2.3.1 Initializing the DTM Service

To open the DTM service, include the DTM service and the ADI Service Manager in the call to ctaInitialize.

The following code excerpt demonstrates initializing the DTM service together with the ADI and Voice Message services:

void MyServiceInit()
    {
        DWORD ret;
        CTA_INIT_PARMS initparms = { 0 };
        CTA_ERROR_HANDLER hdlr;
        CTA_SERVICE_NAME InitServices[] =    /* for ctaInitialize */
        {    { "ADI", "ADIMGR" },
    { "DTM", "ADIMGR" },
    { "VCE", "VCEMGR" },
        };
   /* Initialize size of init parms structure */
        initparms.size = sizeof(CTA_INIT_PARMS);

   if ( ( ret = ctaInitialize(
                          InitServices,
                          sizeof(InitServices)/sizeof(InitServices[0]),
                          &initparms)) != SUCCESS)
   {
   /* ... handle error conditions here.... */

   }
}

After the call to ctaInitialize:

1. Create an event queue attached to the ADI Service Manager by calling ctaCreateQueue. ADIMGR can be explicitly specified in the call. If NULL is passed, all service managers specified in ctaInitialize are attached.

2. Create a context by calling ctaCreateContext.

2.3.2 Opening the DTM Service

The DTM service must be opened on a context in order to use DTM service functions. Opening the DTM service starts the trunk monitor software on the board, and enables it to make status information accessible to the application at specific intervals.

Note: Only one instance of the DTM service can be opened on each context.

When the application opens a service, it specifies a board number. When the application opens the trunk monitor, it binds the board to a context.

To open the DTM service on a context, call ctaOpenServices. This function takes an array of CTA_SERVICE_DESC structures as an input argument. Each CTA_SERVICE_DESC structure defines a service (in this case, the DTM service). If the service(s) is opened successfully, a CTAEVN_OPEN_SERVICES_DONE event with the reason CTA_REASON_FINISHED is delivered to the application. The CTA_SERVICE_DESC structure is defined as follows:

typedef struct CTA_SERVICE_DESC
{
  CTA_SERVICE_NAME name;       /* service name          */
  CTA_SERVICE_ADDR svcaddr;       /* reserved          */
  CTA_SERVICE_ARGS svcargs;       /* passes service-specific arguments                     */
  CTA_MVIP_ADDR mvipaddr;       /* AG board #, stream, timeslot, mode          */
  
}CTA_SERVICE_DESC;

Note: The DTM service does not take any information from the MVIP_ADDR structure. You specify which board, stream, and timeslot to monitor in a DTM function call when you start the trunk monitor, not when you open the DTM service. The CTA_SERVICE_ARGS structure is not used by the DTM service.

The following code sample demonstrates how an application opens the DTM service :

    DWORD ret ;
    CTA_EVENT event ;
    CTA_SERVICE_DESC service[] =
    {
       { {"DTM", "ADIMGR"}, { 0 }, { 0 }, { 0 } } ,
    } ;
   
                 /* open the DTM service */
    ret = ctaOpenServices(  ctahd,                /* a CTA context handle */
                            services,
                            1 );
    if(ret != SUCCESS)
    {
                  /* opening DTM service failed */
        DemoShowError( "ctaOpenServices", ret );
    }
    else
    {
               /* wait for the CTAEVN_OPEN_SERVICES_DONE event */
         DemoWaitForSpecificEvent(ctahd,
                                     CTAEVN_OPEN_SERVICES_DONE,
                                     & event ) ;

                  /* check the reason of completion */
         if (event.value != CTA_REASON_FINISHED)
         {
             DemoShowError( "ctaOpenServices", event.value );
         }
    }

2.4 Monitoring a Digital Trunk

The DTM service maintains and monitors accumulator fields for the following conditions:

• Errored seconds - one second intervals containing one or more of the following errors:

• Loss of frame

• Framing error

• Bipolar violation

• AIS (all ones)

• Slip

• E1 CRC error

Severely errored seconds - one second intervals in which the bit error rate exceeds 10^-3, or an out-of-frame error occurred.

Unavailable seconds - one second intervals, during which, on a T1 trunk, were preceded by 10 consecutive Severely Errored seconds, and on an E1 trunk, loss of signal occurred, out-of-frame occurred, or excessive bit error rate was detected. Unavailable seconds also indicate a failure state, which includes any of the following conditions:

Far end alarm (Yellow alarm on T1)

Loss of frame (Red alarm on T1)

AIS (all ones)

Loss of signal

To start monitoring a digital trunk, call dtmStartTrunkMonitor. dtmStartTrunkMonitor takes a pointer to DTM_START_PARMS as one of its arguments. The maxevents field in DTM_START_PARMS determines the maximum number of events that can be sent from the board per second. The reportmask field in the DTM_START_PARMS structure specifies which of the following conditions the monitor reports:

Name	Value	Condition Monitored
DTM_REPORT_GO_NOGO	1	Going in or out of alarm state.
DTM_REPORT_ALARMS	2	Any change in received alarms.
DTM_REPORT_STATUS	4	Any status/sync change.
DTM_REPORT_SLIPS	8	Any slip.
DTM_REPORT_ES	0x10	Change in errored seconds.
DTM_REPORT_SES	0x20	Change in severe errored seconds.
DTM_REPORT_UAS	0x40	Change in unavailable seconds.

Call dtmStopTrunkMonitor to terminate the trunk monitor.

2.4.1 DTM Handles

Calling dtmStartTrunkMonitor returns a DTM handle, dtmhd. The DTM handle uniquely identifies the board-trunk pair that is being monitored. Only one trunk and one board can be associated with a dtmhd. Create multiple dtmhds to monitor multiple trunks. Use multiple dtmhds to monitor multiple boards. An application can monitor as many trunks per context as it needs, and report events from each of those trunks on a single event queue associated with the context. The dtmhd is the unique identifier for each trunk.

A dtmhd is valid until a dtmStopTrunkMonitor function call stopping the monitor on the specified trunk has completed and the DTMEVN_MONITOR_DONE event is returned to the application.

2.4.2 Retrieving Trunk Status Information

The DTM service maintains a cache on the host computer for each trunk, where the trunk's status is stored. Call dtmGetTrunkStatus to retrieve a snapshot of a specified trunk's status. The DTM_TRUNK_STATUS contains current information about alarms, trunk status, and error statistics. The same structure is used for both T1 and E1 trunks.

To retrieve the trunk status:

1. Call dtmRefreshTrunkStatus to force the board to refresh the cache on the host with the most recent information about the specified trunk. A trunk status event will be sent by the board immediately upon receiving this request.

2. Call dtmResetCounters to request the board to re-initialize the accumulator and start time fields and force a status event to be sent to the host from the board, which will also refresh the DTM_TRUNK_STATUS structure. See Section 4.3 for more details about the DTM_TRUNK_STATUS structure.

2.4.3 Generating Alarms

Call dtmSendAlarm to start sending remote alarms on the specified trunk, or to turn off any specific configuration to send remote alarms. The remote alarms are what the other end of the trunk "sees," and are not necessarily the same alarms that are sent from the board to the application. Any alarms that are automatically generated are unaffected by dtmSendAlarm. dtmSendAlarm accepts the following values for its alarm argument:

Name	Value	Alarm
DTM_SEND_NO_ALARMS	0	Stop sending alarms (automatic alarms can still occur).
DTM_SEND_AIS	1	Send AIS (all 1s signal - blue alarms).
DTM_SEND_LOF	2	Send Loss of Frame (yellow alarm).
DTM_SEND_TS16AIS	3	Send TS16AIS (E1 only).

2.5 The Development Environment

To use the DTM service functions, an application must link with

• The DTM service header file dtmdef.h.

• The import library adidtm.lib (named libadidtm.so under UNIX).

• The DTM service Windows NT dynamic link library adidtm.dll, or the UNIX shared library libadidtm.so.

Looking at the annotated source code for the demonstration programs is a good way to start developing your own applications. They are installed in the \nms\ctaccess\demos directory (/opt/nms/ctaccess/demos under UNIX). Each demonstration program has its own subdirectory, which has the same name as the demonstration program.

Note: Your directory structure may vary slightly according to your operating system and installation. Refer to the Natural Access Developer's Reference Manual for specific information about the appropriate text file to examine to retrieve the exact path to the header and library files on your system.