# Monitoring a digital trunk

This topic presents:

- Trunk monitor objects

- Retrieving trunk status information

- Cooperative trunk monitoring

- Generating alarms

The DTM service maintains accumulator fields for T1/E1 trunks. It can monitor the following conditions:

Condition | Description
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. On a T1 trunk, they are preceded by 10 consecutive severely errored seconds. 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 that 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

For BRI trunks, the DTM service can also maintain accumulator fields for statistics and trunk state. It can monitor the following conditions:

- Slip

- Framing errors

- Received and transmitted frames

- Trunk state

- B channel status

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 or synchronization change.
DTM_REPORT_SLIPS | 8 | Any slip.
DTM_REPORT_ES | 0x10 | Change in errored seconds.
DTM_REPORT_SES | 0x20 | Change in severely errored seconds.
DTM_REPORT_UAS | 0x40 | Change in unavailable seconds.

Call dtmStopTrunkMonitor to terminate the trunk monitor.

## Trunk monitor objects

Calling dtmStartTrunkMonitor returns a DTM handle, dtmhd. The DTM handle uniquely identifies a trunk monitor object that represents the board-trunk pair that is being monitored. Only one board can be associated with a trunk monitor object. Create multiple trunk monitor objects to monitor multiple trunks. Use multiple trunk monitor objects 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 DTMEVN_MONITOR_DONE is returned to the application.

## 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 (or dtmGetBriTrunkStatus) to retrieve a snapshot of a specified trunk's status. DTM_TRUNK_STATUS (or DTM_BRI_TRUNK_STATUS) contains current information about alarms, trunk status, and error statistics. The same structure (DTM_TRUNK_STATUS) is used for both T1 and E1 trunks.

Complete the following steps to retrieve the trunk status:

Step | Action
1 | Call dtmRefreshTrunkStatus to force the board to refresh the cache on the host with the most recent information about the specified trunk. The board sends a trunk status event immediately upon receiving this request.
2 | Call dtmResetCounters to request that the board reinitialize the accumulator and start time fields and force a status event to be sent to the host from the board, which also refreshes the DTM_TRUNK_STATUS (or DTM_BRI_TRUNK_STATUS) structure. See DTM_TRUNK_STATUS structure for more details about the DTM_TRUNK_STATUS (or DTM_BRI_TRUNK_STATUS) structure.

## Cooperative trunk monitoring

Natural Access enables two or more applications to cooperate in the monitoring of a trunk using a shared context and a shared trunk monitor object. For example, one application can start trunk monitoring and another application can stop trunk monitoring.

To do so, one application must first create the trunk monitor object by invoking dtmStartTrunkMonitor. Then other applications must obtain a handle to that object in one of the following ways:

- The first application calls ctaGetObjDesc twice and obtains two descriptors: one for the context and the other for the trunk monitor object. The application passes both descriptors to the second application. The second application calls ctaAttachContext to attach to the context and invokes ctaAttachObject to obtain a dtmhd for the attached trunk monitor object.

For more information on descriptors, refer to the Natural Access Developer's Reference Manual.

- The first application calls ctaGetObjDesc and obtains a context descriptor for the context associated with the trunk monitor object. The application passes the board ID, trunk ID, and context descriptor to the other application.

The other application then calls ctaAttachContext to obtain a context handle.

The application invokes dtmAttachTrunkMonitor to attach to the trunk monitor object.

- The first application calls ctaGetObjDesc and obtains a context descriptor for the context associated with the trunk monitor object. The application passes the context descriptor to the other application.

The other application then calls ctaAttachContext to obtain a context handle.

The application receives an event containing the dtmhd in the objhd field of the CTA_EVENT structure.

In a context-sharing environment, DTMEVN_MONITOR_DONE is sent to all applications sharing a context. Upon receiving this event, the dtmhd is released and is no longer valid.

## 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 ones signal - blue alarms).
DTM_SEND_LOF | 2 | Send loss of frame (yellow alarm).
DTM_SEND_TS16AIS | 3 | Send TS16AIS (E1 only).

Note: BRI trunks do not support dtmSendAlarm.