Version

Appendix A

Event and Error Summary

Introduction

The DTM service API has a specific set of events associated with it. This appendix summarizes these codes. Since DTM is a Natural Access service, its functions can also receive Natural Access events, errors, and reasons. Refer to the Natural Access Developer's Reference Manual for listings and descriptions of the Natural Access events, errors, and reasons.

Events

All events in the Natural Access environment are represented by a C data structure, as shown in the generic CTA_EVENT below: typedef struct { DWORD id; /* event id (LIBEVN_xxx in 'libdef.h') */ CTAHD ctahd; /* CTA context handle */ DWORD timestamp; /* timestamp */ DWORD userid; /* use-supplied id */ DWORD size; /* size of buffer if buffer is not NULL */ /* otherwise, may contain event-specific data */ void *buffer; /* buffer pointer */ DWORD value; /* Event status or event-specific data */ DWORD reserved; /* must be 0 */ } CTA_EVENT;
This structure, returned by ctaWaitEvent, informs the application which event occurred on which context, and provides additional information specific to the event. The LIB prefix in LIBEVN relates the event to a specific Natural MicroSystems library of functions. For example, the CTA prefix indicates Natural Access and DTM indicates the DTM service.
The event structure contains the following fields:

Field

Description

id

Contains an event code defined in the library header file. All DTM events are prefixed with DTMEVN_ (for example, DTMEVN_SOMETHING_HAPPENED).

ctahd

Contains the context handle (returned from ctaCreateContext).

timestamp

Contains the time when the event was created in milliseconds since midnight. The resolution for AG board events is 10 milliseconds.

userid

Contains the user-supplied ID. This field is unaltered by Natural Access and facilitates asynchronous programming. Its purpose is to correlate a context with an application object/context when events occur.

size

The size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may be used to hold an event-specific value.

buffer

This field points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer.

value

This is an event-specific value. This field can hold a reason code or an error code.

Field	Description
id	Contains an event code defined in the library header file. All DTM events are prefixed with DTMEVN_ (for example, DTMEVN_SOMETHING_HAPPENED).
ctahd	Contains the context handle (returned from ctaCreateContext).
timestamp	Contains the time when the event was created in milliseconds since midnight. The resolution for AG board events is 10 milliseconds.
userid	Contains the user-supplied ID. This field is unaltered by Natural Access and facilitates asynchronous programming. Its purpose is to correlate a context with an application object/context when events occur.
size	The size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may be used to hold an event-specific value.
buffer	This field points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer.
value	This is an event-specific value. This field can hold a reason code or an error code.

DTM Service Events

The following events are specific to the DTM service: Event Hex Decimal Description DTMEVN_MONITOR_DONE 0XC2101 794881 Monitoring ended. DTMEVN_MONITOR_STARTED 0XC2001 794625 Monitoring has started on a specified trunk. DTMEVN_TRUNK_STATUS 0XC2002 794626 Trunk status information is available.

Event	Hex	Decimal	Description
DTMEVN_MONITOR_DONE	0XC2101	794881	Monitoring ended.
DTMEVN_MONITOR_STARTED	0XC2001	794625	Monitoring has started on a specified trunk.
DTMEVN_TRUNK_STATUS	0XC2002	794626	Trunk status information is available.

Errors

All Natural Access and Natural Access service functions return a status code. If this not SUCCESS (0), it is an error code indicating that the function has failed, and a reason for the failure.
There are no specific DTM service error codes because the DTM service functions use Natural Access error codes.
Natural Access error codes are defined in the include files ctaerr.h, swidef.h, and vcedef.h. The error codes are prefixed with CTAERR, SWIERR, or VCEERR, respectively. Error codes can also appear in the value field of a DONE event. Use the CTA_IS_ERROR macro to determine if a value is an error.
Refer to the Natural Access Developer's Reference Manual for a description of the Natural Access errors.

Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com