Version

Appendix A

Event and Error Summary

: Introduction
: NMS ISDN Management API Events
: Numerical Events Summary
: NMS ISDN Management API Errors
: Alphabetical Error Summary
: Numerical Error Summary

Introduction

The IMGT service API has a specific set of events associated with it. This appendix summarizes these codes. Note that since IMGT is a Natural Access service, its functions can also receive Natural Access events, errors, and reasons.
All Natural Access and Natural Access service functions return a status code. If the status code is not SUCCESS (0), it is an error code indicating that the function has failed, and a reason for the failure.
Refer to the Natural Access Developer's Reference Manual for listings and descriptions of the Natural Access events, errors, and reasons.

NMS ISDN Management API 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 objHd; /* Service client-side object handle */ } 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 IMGT indicates the IMGT service.
The event structure contains the following fields: Field Description id Contains an event code defined in the library header file. All IMGT events are prefixed with IMGTEVN_ (for example, IMGTEVN_SOMETHING_HAPPENED). ctahd Contains the context handle (returned from ctaCreateContext). timestamp Contains the time when the event was created, in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for board events is ten 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 and context when events occur. size The size (in 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. 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. objHd Contains the call handle, if the event concerns a particular call. If the event concerns the line and not a particular call, objHd is NULL.

Field	Description
id	Contains an event code defined in the library header file. All IMGT events are prefixed with IMGTEVN_ (for example, IMGTEVN_SOMETHING_HAPPENED).
ctahd	Contains the context handle (returned from ctaCreateContext).
timestamp	Contains the time when the event was created, in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for board events is ten 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 and context when events occur.
size	The size (in 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. 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.
objHd	Contains the call handle, if the event concerns a particular call. If the event concerns the line and not a particular call, objHd is NULL.

Numerical Events Summary

The following events are specific to the NMS ISDN Management API: Event Hex Decimal Description IMGTEVN_STARTED 0x00182001 1581057 Configuration finished. IMGTEVN_STOPPED 0x00182002 1581058 Reset configuration. IMGTEVN_SEND_MESSAGE 0x00182003 1581059 Message has been sent and failed. IMGTEVN_RCV_MESSAGE 0x00182005 1581061 Received message from the trunk.

Event	Hex	Decimal	Description
IMGTEVN_STARTED	0x00182001	1581057	Configuration finished.
IMGTEVN_STOPPED	0x00182002	1581058	Reset configuration.
IMGTEVN_SEND_MESSAGE	0x00182003	1581059	Message has been sent and failed.
IMGTEVN_RCV_MESSAGE	0x00182005	1581061	Received message from the trunk.

NMS ISDN Management API Errors

This section provides a summary of NMS ISDN Management API error codes. The error codes are presented in two tables: · Alphabetical, by error code name, including a description of the problem and a possible solution. · Numerical, by hexadecimal value, decimal value, and error name.
All Natural Access functions return a status code. If the return code is not SUCCESS (0), it is an error code indicating that the function has failed and the reason for failure.
NMS ISDN Management API error codes are defined in the include file imgtdef.h. The error codes are prefixed with IMGT.
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.

Alphabetical Error Summary

The following table is an alphabetical listing of errors. All errors are 32 bits.

Error Name

Hex

Decimal

Description

IMGTERR_BAD_NAI

0x00181001

1576961

Bad NAI specification.

IMGTERR_BUFFER_TOO_BIG

0x00181004

1576964

Buffer is too big.

IMGTERR_DRIVER_ERROR

0x00181007

1576967

Driver error.

IMGTERR_INVALID_BUFFER

0x00181008

1576968

Invalid buffer.

IMGTERR_INVALID_CONFIG

0x00181002

1576962

Invalid IMGT_CONFIG field.

IMGTERR_IMGT_NOT_STARTED

0x00181016

1576982

Management session has not been initialized.

IMGTERR_NAI_IN_USE

0x00181006

1576966

NAI is already configured.

IMGTERR_NO_UP_BUFFER

0x00181003

1576963

No incoming buffer.

IMGTERR_ISDN_NOT_STARTED

0x00181015

1576981

ISDN stack is not started.

IMGTERR_RCV_BUFFER_TOO_BIG

0x00181005

1576965

Incoming buffer is too big.

Error Name	Hex	Decimal	Description
IMGTERR_BAD_NAI	0x00181001	1576961	Bad NAI specification.
IMGTERR_BUFFER_TOO_BIG	0x00181004	1576964	Buffer is too big.
IMGTERR_DRIVER_ERROR	0x00181007	1576967	Driver error.
IMGTERR_INVALID_BUFFER	0x00181008	1576968	Invalid buffer.
IMGTERR_INVALID_CONFIG	0x00181002	1576962	Invalid IMGT_CONFIG field.
IMGTERR_IMGT_NOT_STARTED	0x00181016	1576982	Management session has not been initialized.
IMGTERR_NAI_IN_USE	0x00181006	1576966	NAI is already configured.
IMGTERR_NO_UP_BUFFER	0x00181003	1576963	No incoming buffer.
IMGTERR_ISDN_NOT_STARTED	0x00181015	1576981	ISDN stack is not started.
IMGTERR_RCV_BUFFER_TOO_BIG	0x00181005	1576965	Incoming buffer is too big.

Numerical Error Summary

The following table is a list of NMS ISDN Management API errors in numerical order: Hex Decimal Error Name 0x00181001 1576961 IMGTERR_BAD_NAI 0x00181002 1576962 IMGTERR_INVALID_CONFIG 0x00181003 1576963 IMGTERR_NO_UP_BUFFER 0x00181004 1576964 IMGTERR_BUFFER_TOO_BIG 0x00181005 1576965 IMGTERR_RCV_BUFFER_TOO_BIG 0x00181006 1576966 IMGTERR_NAI_IN_USE 0x00181007 1576967 IMGTERR_DRIVER_ERROR 0x00181008 1576968 IMGTERR_INVALID_BUFFER 0x00181015 1576981 IMGTERR_ISDN_NOT_STARTED 0x00181016 1576982 IMGTERR_IMGT_NOT_STARTED

Hex	Decimal	Error Name
0x00181001	1576961	IMGTERR_BAD_NAI
0x00181002	1576962	IMGTERR_INVALID_CONFIG
0x00181003	1576963	IMGTERR_NO_UP_BUFFER
0x00181004	1576964	IMGTERR_BUFFER_TOO_BIG
0x00181005	1576965	IMGTERR_RCV_BUFFER_TOO_BIG
0x00181006	1576966	IMGTERR_NAI_IN_USE
0x00181007	1576967	IMGTERR_DRIVER_ERROR
0x00181008	1576968	IMGTERR_INVALID_BUFFER
0x00181015	1576981	IMGTERR_ISDN_NOT_STARTED
0x00181016	1576982	IMGTERR_IMGT_NOT_STARTED

Version

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