Table of Contents Index NMS Glossary Previous Page Next Page (Page 12 of 32 in this chapter) Version

NMS_GR303SetTrace

Description

Configures NMS GR303 library tracing.

Prototype

NMS_GR303_RESULT_T NMS_GR303SetTrace
(NMS_GR303_TRACEMASK_T trace_mask,
 NMS_GR303_TRACE_CALLBACK_T user_trace_callback,
 void *user_trace_buffer,
 DWORD user_trace_buffersize,
 char *user_file_name)

trace_mask Trace mask controlling the information level reported to the application. Applications can specify the following trace masks:
Trace Mask

 Description

NMSGR303_TRACEMASK_NONE

 No tracing.

NMSGR303_TRACEMASK_
FUNCTIONS

 Trace function calls and returns.

NMSGR303_TRACEMASK_
ERRORS

 Trace errors.

NMSGR303_TRACEMASK_ALL

 Trace functions and errors.

user_trace_callback Pointer to an application-defined callback function. Set this value to NULL if the library is saving tracing information to a file. The library invokes when it has a trace buffer to pass to the application. The callback is defined in the following way:

      typedef void (*NMS_GR303_TRACE_CALLBACK_T)
        (char *tracebuffer,
         DWORD datasize);
user_trace_buffer Pointer to the application-allocated memory that the NMS GR303 library uses to pass trace data to the application.

user_trace_buffersize Size of the application-allocated buffer specified by user_trace_buffer. The minimum requirement for the user_trace_buffersize is set by NMS_GR303_MIN_TRACE_BUF_SIZE.

user_file_name Name of the log file if the NMS GR3030 library is logging trace information in a file. This value specifies the size of the trace blocks that the library uses to write to the file.

Return Values

Events

Details

Applications can use NMS_GR303SetTrace to configure the NMS GR303 library to return trace information through a defined callback function, or to log trace information into a specified file.

When defining a callback function, the application specifies the following information:
Parameter

 Description

tracebuffer

 A pointer to the beginning of the trace information inside the application-allocated memory.

datasize

 The size of the data returned in the tracebuffer.

To initiate the callback mode, the application must pass a callback function pointer user_trace_callback, allocate a buffer, and specify the buffer address (tracebuffer) and size (user_trace_buffersize) as NMS_GR303SetTrace arguments.

If the GR303 library receives a user_trace_callback value (and this value is not NULL), the library sets up the callback tracing mode and ignores the user_file_name value.

Note: After the user_trace_callback function returns, the library assumes that the application is finished using the data inside the tracebuffer, and that the library can reuse the memory. For this reason, applications must release user_trace_callback buffers as quickly as possible.

If the application decides to log trace information into a file, the application must set user_trace_callback and tracebuffer to NULL. If the application wants the library to perform internal buffering before logging tracing information in the file, the application must set the user_trace_buffersize to the trace block size. user_trace_buffersize specifies the size of an application-allocated buffer reserved for trace messages returned to the application. The size of user_trace_buffersize must either be greater than the value specified by the NMS_GR303_MIN_TRACE_BUFFER_SIZE parameter, equal to NMS_GR303_MIN_TRACE_BUFFER_SIZE, or zero.

If the applications sets user_trace_buffersize to zero, the NMS GR303 library sends each trace message to the application immediately. However, even when the NMS GR303 library sends individual trace messages, the application must still reserve an amount of memory greater than or equal to the size of NMS_GR303_MIN_TRACE_BUFFER_SIZE.

The NMS GR303 library can return the following tracing messages:
Message

 Hex

 Description

PHYERR_INVALID_DEVICE

 0x01

 Board failed to define the HDLC or framer device type.

PHYERR_DEVICE_USED

 0x02

 The specified HDLC framer already exists in the NMS GR303 library.

PHYERR_INVALID_HANDLE

 0x03

 Invalid HDLC of framer handle passed. The board doesn't have a HDLC device configured with this handle.

PHYERR_BOARD_MESSAGE_
FAILED

 0x04

 Failed to send a message to the board. Internal communication problem.

PHYERR_BOARD_RESPONSE_
TIMEOUT

 0x05

 The board failed to respond to a message within a specified time interval.

PHYERR_INTERNAL_FAILURE

 0x06

 Failed to initialize or exit the NMS GR303 library.

PHYERR_INVALID_PARMS

 0x07

 Invalid input parameters.

PHYERR_NO_MEMORY

 0x08

 Failed to allocate memory.

PHYERR_ALREADY_INITIALIZED

 0x09

 The NMS GR303 library has already been initialized.

PHYERR_NO_BUFFER_DEFINED

 0x0A

 No buffer provided for requested data.

PHYERR_OUTOFRESOURCE

 0x0B

 Cannot create more HDLC instances on the board.

See Also

NMS_GR303Initialize

Example

void  SetTrace( void )
{
    NMS_GR303_RESULT_T      NmsResult;
    NMS_GR303_TRACEMASK_T      TraceMask;
    BYTE      FileName[64];
    char      Selection;
printf("NMS_GR303SetTrace:\n"); prompthex("Enter TraceMask", &TraceMask); TraceBufferSize = NMS_GR303_MIN_TRACE_BUF_SIZE; /* Allocate buffer size not less than required minimum */ g_pTraceBuffer = calloc( TraceBufferSize, 1); /* Set trace to a file */ strcpy( FileName, "nms_gr303.log" ); NmsResult = NMS_GR303SetTrace( TraceMask, NULL, NULL, TraceBufferSize, FileName); printf ("NMS_GR303SetTrace: Result=%s\n",PRINT_RESULT(NmsResult)); }

Table of Contents Index NMS Glossary Previous Page Next Page (Page 12 of 32 in this chapter) Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com
Copyright © 2001, NMS Communications Corporation. All rights reserved.