Controls the V5 library-tracing mechanism.

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)

trace_mask Trace mask that specifies the level of tracing performed by the NMS V5 library. Applications can specify the following trace masks:

Trace Mask	Description
NMSV5_TRACEMASK_NONE	No tracing.
NMSV5_TRACEMASK_ FUNCTIONS	Trace function calls and returns.
NMSV5_TRACEMASK_ERRORS	Trace errors.
NMSV5_TRACEMASK_ALL	Trace functions and errors.

user_trace_callback Pointer to an application-defined callback (NULL if tracing to a file). The NMS V5 library uses this callback every time it has 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);

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.

• NMSV5_SUCCESS
• NMSV5_NOT_INITIALIZED
  The NMS V5 library was not initialized with NMS_V5Intialize.
• NMSV5_INVALID_PARMS
  An invalid argument has been passed.
• NMSV5_INVALID_STATE
  The interface has not been started.
• NMSV5_INTERNAL_FAILURE
  Failed to set up tracing.

• None.

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.

When defining a callback, the application specifies the following:

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 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:

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 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 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.

NMS_V5Initialize

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