NMS_V5SetTrace

Controls the V5 library tracing mechanism.

Prototype

NMS_V5_RESULT_T NMS_V5SetTrace ( NMS_V5_TRACEMASK_T trace_mask NMS_V5_TRACE_CALLBACK_T *user_trace_callback void *user_trace_buffer DWORD user_trace_buffersize char *user_file_name)

Argument	Description
trace_mask	Trace mask that specifies the level of tracing performed by the NMS V5 library. Refer to the Details section for a list of trace masks that applications can specify.
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 NMS V5 library uses this callback function each time it has a trace buffer to pass to the application. The callback function is defined in the following way: typedef void (NMS_V5_TRACE_CALLBACK_T) (char tracebuffer, DWORD datasize); See the Details section for field descriptions.
user_trace_buffer	Pointer to the application-allocated memory that the NMS V5 library uses to pass trace data to the application.
user_trace_buffersize	Size of the application-allocated buffer user_trace_buffer. The minimum requirement for the user_trace_buffersize is set by the NMS_V5_MIN_TRACE_BUF_SIZE value.
user_file_name	Pointer to the name of a file if the NMS V5 library is logging trace information. This value specifies the size of the trace blocks that the NMS V5 library uses when writing trace information to the file.

Return values

Return value	Description
NMSV5_SUCCESS
NMSV5_INTERNAL_FAILURE	Failed to set up tracing.
NMSV5_INVALID_PARMS	Invalid argument has been passed.
NMSV5_INVALID_STATE	Interface has not been started.
NMSV5_NOT_INITIALIZED	NMS V5 library was not initialized with NMS_V5Initialize.

Details

Applications can use NMS_V5SetTrace to configure tracing so that the NMS V5 library returns trace information through a defined callback function or logs trace information into a specified file. The following table lists the trace masks that applications can specify:

Trace mask	Description
NMSV5_TRACEMASK_NONE	No tracing.
NMSV5_TRACEMASK_FUNCTIONS	Trace function calls and returns.
NMSV5_TRACEMASK_ERRORS	Trace errors.
NMSV5_TRACEMASK_RX_BUF	Log received HDLC frames.
NMSV5_TRACEMASK_TX_BUF	Log transmitted HDLC frames.
NMSV5_TRACEMASK_HDLCERR	Log HDLC transmit/receive errors.
NMSV5_TRACEMASK_E1_STATUS	Log E1 status reports.

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

Field	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 the callback function pointer user_trace_callback, allocate a buffer, and pass the buffer address (tracebuffer) and size (user_trace_buffersize) of the buffer as arguments for NMS_V5SetTrace.

When the NMS V5 library receives a user_trace_callback value (and this value is not NULL), it configures the callback tracing mode and ignores the user_file_name value. After the user_trace callback function returns, the library assumes that the application is done with the data inside the tracebuffer and it can overwrite its contents. Therefore, the application should release buffers associated with user_trace callback functions as soon as possible.

Applications can log trace information into a file by setting the user_trace_callback and tracebuffer values to NULL. Applications can also have the V5 library perform internal buffering before logging tracing information into the file, by setting the user_trace_buffersize value to the trace block size. user_trace_buffersize specifies the size of the application-allocated memory 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_V5_MIN_TRACE_BUFFER_SIZE parameter, equal to NMS_V5_MIN_TRACE_BUFFER_SIZE, or set to zero.

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

The NMS V5 library can return the following tracing messages with NMSV5_INTERNAL_FAILURE errors:

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 V5 library.
PHYERR_INVALID_HANDLE	0x03	Invalid HDLC framer handle passed. The board does not have an 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 V5 library.
PHYERR_INVALID_PARMS	0x07	Invalid input parameters.
PHYERR_NO_MEMORY	0x08	Failed to allocate memory.
PHYERR_ALREADY_INITIALIZED	0x09	The NMS V5 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.

Example

void  SetTrace( void )
{
    NMS_V5_RESULT_T      NmsResult;
    NMS_V5_TRACEMASK_T   TraceMask;
    BYTE                 FileName[64];
    DWORD                TraceBufferSize;
    char                 Selection;

    printf("NMS_V5SetTrace:\n");

    /* Set to print error mesages */

    prompthex("Enter TraceMask", &TraceMask);

    TraceBufferSize = NMS_V5_MIN_TRACE_BUF_SIZE;

    /* Allocate buffer size not less than required minimum */
    g_pTraceBuffer = calloc(TraceBufferSize, 1);

    /* Log trace information to a file */
        strcpy( FileName, "nms_v5.log" );
        NmsResult =  NMS_V5SetTrace(TraceMask,
                                    NULL,
                                    NULL,
                                    TraceBufferSize,
                                    FileName);

    printf ("NMS_V5SetTrace: Result=%s\n",PRINT_RESULT(NmsResult));

}