# dtmStartTrunkMonitor

Starts monitoring a specified trunk.

#### Prototype

DWORD dtmStartTrunkMonitor ( CTAHD ctahd, unsigned board, unsigned trunk, DTMHD *dtmhd, DTM_START_PARMS *parms)

Argument | Description
ctahd | Handle returned by ctaCreateContext or ctaAttachContext.
board | Board number.
trunk | Specific trunk on the board. The first trunk is 0.
dtmhd | Pointer to the returned monitor handle.
parms | Pointer to a parameter structure. Set this to NULL to use default values. The DTM_START_PARMS structure is: typedef struct { DWORD size; DWORD maxevents; DWORD reportmask; } DTM_START_PARMS; Refer to the Details section for a description of these fields.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | Specified trunk number is invalid.
CTAERR_FUNCTION_ACTIVE | Already monitoring the specified trunk in the current context.
CTAERR_SVR_COMM | Communication error in server environment.

#### Events

Event | Description
DTMEVN_MONITOR_DONE | Monitoring ended. The size field contains a board number in the high word and a trunk number in the low word. The value field of the event contains an error code. The objHd field of this event contains the dtmhd.
DTMEVN_MONITOR_STARTED | Monitoring started. The value, size, and objHd fields are the same as for DTMEVN_TRUNK_STATUS.
DTMEVN_TRUNK_STATUS | The value field contains a 4-byte DTM_TRUNK_STATE structure. When the trunk is operational, all bytes are set to 0. The objHd field contains the dtmhd.

#### Details

dtmStartTrunkMonitor starts monitoring a particular digital trunk and returns a DTM handle, dtmhd. Monitoring is active until it is stopped with dtmStopTrunkMonitor, until the DTM service is closed, or until the context associated with ctahd is destroyed. The dtmhd is valid until the application receives the DTMEVN_MONITOR_DONE event from the call to dtmStopTrunkMonitor.

dtmStartTrunkMonitor can be called multiple times on the same context for different trunks. The same trunk can be simultaneously monitored by multiple contexts.

If the context is being shared by another application, the application receives DTMEVN_MONITOR_STARTED. When this event is received, the other application automatically attaches to the trunk monitor service object. The objhd field in DTMEVN_MONITOR_STARTED contains a unique handle that the application can use.

Note: For more information on shared service objects, refer to the Natural Access Service Developer's Reference Manual.

parms points to a DTM_START_PARMS parameter structure. If parms is NULL, the default parameter values are used. Use NMS parameter management functions to change default parameter values for a processing context.

The DTM_START_PARMS structure includes the following fields:

- maxevents defines the maximum number of status events that the DTM service can generate in a one-second interval. Its default setting is 1. If status changes occur after the event limit is reached, there will be an event at the beginning of the next one-second interval. Events that are solely the result of changes in the errored seconds counters are not included in the event limit.

- reportmask controls when the DTM services sends events. Its default setting is 1. It can be set to any of the following values:

Value | Sends events...
--- | ---
0 | Only in response to dtmRefreshTrunkStatus.
1 | Only when going in or out of alarm (ignoring type).
2 | On any change in received alarms.
4 | On any status or synchronization change (including loss of signal).
8 | On any slip.
0x10 | On change in errored seconds counter.
0x20 | On change in failed seconds counter.
0x40 | On change in severely errored seconds counter.

In an application that wants to know when a trunk fails and when it is restored, use the default value of 1 for reportmask. Set reportmask to 0x7F to get events when anything changes.

DTMEVN_MONITOR_STARTED containing the current alarm status is always sent as soon as the monitoring is started.

dtmStartTrunkMonitor fails if the board type does not support monitoring.