DEFINE_TRACE

The DEFINE_TRACE verb enables or disables tracing for specified APIs and controls the amount of tracing.

The following structure describes the verb control block used by the DEFINE_TRACE verb.

struct define_trace {
    unsigned short       opcode;
    unsigned char        opext;
    unsigned char        reserv2;
    unsigned short       primary_rc;
    unsigned long        secondary_rc;
    unsigned char        reserv3[8];
    unsigned char        dt_set;
    unsigned char        appc;
    unsigned char        reserv4;
    unsigned char       srpi;
    unsigned char       sdlc;
    unsigned char       tkn_rng_dlc;
    unsigned char       pcnet_dlc;
    unsigned char       dft;
    unsigned char       acdi;
    unsigned char       reserv5;
    unsigned char       ehllapi;
    unsigned char       x25_api;
    unsigned char       x25_dlc;
    unsigned char       twinax;
    unsigned char       reserv6;
    unsigned char       lua_api;
    unsigned char       etherand;
    unsigned char       subsym;
    unsigned char       reserv7[8];
    unsigned char       reset_trc;
    unsigned short      trunc;
    unsigned short      strg_size;
    unsigned char       reserv8;
    unsigned char       phys_link[8];
    unsigned char       reserv9[56];
}; 
 

Members

opcode

Supplied parameter. The verb identifying the operation code, SV_DEFINE_TRACE.

opext

A reserved field.

reserv2

A reserved field.

primary_rc

Returned parameter. Specifies the primary return code set by APPC at the completion of the verb. The valid return codes vary depending on the APPC verb issued. See Return Codes for valid error codes for this verb.

secondary_rc

Returned parameter. Specifies the secondary return code set by APPC at the completion of the verb. The valid return codes vary depending on the APPC verb issued. See Return Codes for valid error codes for this verb.

reserv3

A reserved field.

dt_set

Supplied parameter. Sets the trace state.

• Use SV_ON to enable tracing for a particular API if the parameter pertaining to the API (such as appc or comm_serv) is set to SV_CHANGE.
• Use SV_OFF to disable tracing for a particular API if the parameter pertaining to the API is set to SV_CHANGE.

appc

Supplied parameter. Indicates whether tracing of APPC is desired.

• Use SV_CHANGE to enable or disable tracing for APPC, depending on the dt_set parameter.
• Use SV_IGNORE to leave tracing in its current state for APPC.

The allowed values turn bit 0 on or off; bits 1 through 7 are reserved.

reserv4

A reserved field.

srpi

Supplied parameter. Indicates whether tracing of SRPI is desired.

• Use SV_CHANGE to enable or disable tracing for APPC, depending on the dt_set parameter.
• Use SV_IGNORE to leave tracing in its current state for APPC.

sdlc

• A reserved field.

tkn_rng_dlc

• A reserved field.

pcnet_dlc

• A reserved field.

dft

• A reserved field.

acdi

• A reserved field.

reserv5

A reserved field.

comm_serv

Supplied parameter. Indicates whether tracing of COMM_SERV_API is desired.

• Use SV_CHANGE to enable or disable tracing for APPC, depending on the dt_set parameter.
• Use SV_IGNORE to leave tracing in its current state for APPC.

ehllapi

• A reserved field.

x25_api

• A reserved field.

x25_dlc

• A reserved field.

twinax

• A reserved field.

reserved6

• A reserved field.

lua_api

• A reserved field.

etherand

• A reserved field.

subsym

• A reserved field.

reserved7

• A reserved field.

reset_trc

Supplied parameter. Indicates whether the trace file pointer should be reset.

• Use SV_NO to not reset the trace file pointer to the start of the trace file. Previous trace records are not overwritten.
• Use SV_YES to reset the trace file pointer to the start of the trace file. Previous trace records are overwritten.

trunc

Supplied parameter. Specifies the maximum number of bytes for each trace record. Excess bytes are truncated. Set this value to zero if you do not want truncation.

strg_size

• A reserved field.

reserved8

• A reserved field.

phys_link

• A reserved field.

reserved9

• A reserved field.

Return Codes

sv_ok

Primary return code; the verb executed successfully.

sv_parameter_check

Primary return code; the verb did not execute because of a parameter error.

sv_invalid_reset_trace

Secondary return code; the reset_trc parameter contained an invalid value.

sv_invalid_set

Secondary return code; the dt_set parameter contained an invalid value.

sv_state_check

Primary return code; the verb did not execute because it was issued in an invalid state.

sv_copy_trace_in_progress

Secondary return code; a previously issued COPY_TRACE_TO_FILE is still in progress. Traces cannot be active while using DEFINE_TRACE.

sv_comm_subsystem_not_loaded

Primary return code; a required component could not be loaded or terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

sv_invalid_verb

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

sv_invalid_verb_segment

Primary return code; the VCB extended beyond the end of the data segment.

sv_unexpected_dos_error

Primary return code; one of the following conditions occurred:

• The Microsoft® Windows NT®, Microsoft® Windows® 95, Windows version 3.x, Microsoft® MS-DOS®, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.
• A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.
• A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

Remarks

For information on how to run and use traces, see the appropriate manual for your product.