(Page 1 of 1 in this chapter)

Chapter 2

Using the DTM Service

2.1 Introduction
2.2 Setting up the CT 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 About DTM Handles
2.4.2 Retrieving the Trunk Status
2.4.3 Generating Alarms
2.5 About the Development Environment

2.1 Introduction

The Digital Trunk Monitor is a C function library component of CT 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 CT Access, including the ADI service, installed on your system to build and run applications using the DTM service. This chapter presents a programming model for using the DTM service in the CT Access environment.

2.2 Setting up the CT Access Environment

Application setup for CT Access consists of the following steps:

  1. Initialize CT Access for the process.

    

  2. Create event queues.
    

    

  3. Create CTA contexts for each event queue.
    

    

  4. Open services on each CTA context.
    




Services are opened on a CTA context by calling ctaOpenServices, passing a CTA 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. CT 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 CTA context. Once the DTM service is opened, the application can make function calls from the DTM API. The following figure shows an example CTA context with the DTM and ADI services open; the DTM service is associated with trunks on two telephony boards:


 



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




ctaCloseServices closes one or more services on a CTA 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 CTA context. All currently opened services on the CTA 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 CTA context is destroyed and resources are released.



ctaDestroyQueue destroys the queue and all CTA 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 CTA 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 CTA context by calling ctaCreateContext. 
    







2.3.2	 Opening the DTM Service





The DTM service must be opened on a CTA context in order to use the DTM service's library of C 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 CTA context. 


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



To open the DTM service on a CTA 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;




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 excerpt demonstrates opening 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 accumulator fields for, and can monitor, the following conditions:




  • 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 which specifies which of the following conditions the monitor will report:
      

      


       

      


      
 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	 About 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 CTA context as needed, and report events from each of those trunks on a single event queue associated with the CTA 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 the Trunk Status
      

      


      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. 
      


      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.
      


      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. For example, the AG-T1 and AG-E1 boards generate yellow alarms by default. 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 1's signal - blue alarms).
      


      
 DTM_SEND_LOF
      

      		
 2
      

      		
 Send Loss of Frame (yellow alarm).
      


      
 DTM_SEND_TS16AIS 
      

      		
 3
      

      		
 Send TS16AIS (E1 only).
      



      


      

      

      

      

      

      

      

      2.5	 About the Development Environment
      

      


      This section describes how to compile applications that use the DTM service. Refer to the CT Access documentation for details about CT Access header files, import libraries, and dynamic link libraries. 
      


      Your directory structure may vary slightly according to your operating system and installation. Refer to the CT Access Installation 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. In order to use the DTM service functions, an application must:
      

      

      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.
      


      

      

      


      
 
    (Page 1 of 1 in this chapter)
      


      
 



      
tech_support@nmss.com

      

Copyright © 1999, Natural MicroSystems, Inc.   All rights
reserved.