HLLAPI Parameter Tracing

The COM_TRC_HLLAPI macro can be used within an HLLAPI (High-Level Language API) library to trace the parameters supplied to an HLLAPI function and the returned values. It should be used at the following times:

• At the start of the HLLAPI library routine, to trace the four parameters supplied by the HLLAPI application before beginning to process them.
• At the end of the HLLAPI library routine, to trace the values to be returned in each of the four parameters before control is returned to the application.

The format of the COM_TRC_HLLAPI call is as follows:

COM_TRC_HLLAPI (type, func, data, len, retc);

Parameters

type (USHORT)

Either REQUEST or RESPONSE; use REQUEST when tracing the parameters supplied by the user application at the start of the library routine and RESPONSE when tracing the parameters to be returned to the user application.

func, len, and retc (USHORT)

The values of the parameters func_number, data_length, and return_code that were supplied to HLLAPI by the user application, or the values to be returned to the application. Note that the user application supplies pointers to these values, but the actual values are required for the COM_TRC_HLLAPI call.

data (UCHAR FAR)

The data_string parameter supplied to HLLAPI by the user application, or the string to be returned to the application in this parameter.

Remarks

To turn on tracing for an HLLAPI application, the environment variable COMTRC is used; see the Microsoft SNA Server Administration Guide for more information on the use of COMTRC. Tracing can also be turned on and off from within the HLLAPI user application using the trace control parameters of the Set Session Parameters function; see the HLLAPI Specification for more information.

The trace output lists the following:

• The name of the HLLAPI function being called (this is determined from the function number, the first of the four parameters to the HLLAPI call).
• Whether the trace refers to a request or a response (determined from the type parameter to the COM_TRC_HLLAPI call).
• The data_length and return_code/ps_position parameters to the HLLAPI call.
• If the data_string parameter is used for this HLLAPI function, the address of the data as supplied to HLLAPI, followed by a listing of the data in both hexadecimal and ASCII characters.

Note that Microsoft® SNA Server's HLLAPI tracing is designed for use with the SNA Server implementation of HLLAPI on OS/2, which is compatible with the implementation provided by OS/2 Extended Edition version 1.2. If your HLLAPI implementation differs from this (for example, by including function numbers that are not supported by the SNA Server implementation, by using a different name for a given function number, or in the usage of the data_string parameter for different verbs), the tracing output obtained may not be correct.

For Microsoft® Windows NT® and Microsoft® Windows® 95, you can use SNATRACE.EXE to dynamically control HLLAPI and FMI tracing.