DosSysTrace (Add a Trace Record to the System Trace Buffer)

DosSysTrace allows a subsystem or system extension to add information to the system trace buffer.

Note: DosSysTrace is a 16-bit API.

Coding Examples.

          EXTRN  DosSysTrace:FAR

          PUSH     WORD     MajorCode     ; major trace event code (240-255)
          PUSH     WORD     Length        ; length of the variable length
                                          ; area to be recorded (0-512)
          PUSH     WORD     MinorCode     ; minor trace event code (0-255)
          PUSH@    OTHER    Data          ; pointer to the area to be traced
                                          ; (address parameter)
          CALL     DOSSYSTRACE
16-bit MASM Example

     APIRET16 APIENTRY16 DosSysTrace(USHORT MajorCode, USHORT Length,
                                     USHORT MinorCode, PCHAR pData);
32-bit code Example using CSet/2

Parameters

MajorCode

The major code to be placed in the trace buffer. Only the low order byte is used. The high order byte should be 0 for future compatibility reasons, but no error checking of the high order byte is performed.
Length
The length of the area pointed to by the address parameter. If a length greater than 512 is specified, only 512 bytes will be recorded. If a length of 0 is specified, the address parameter will not be used; however, a dummy doubleword must be pushed on the stack so that all calls use the same stack space.
MinorCode
The minor code to be placed in the trace buffer. This code identifies the specific trace event. Only the low order byte is used. The high order byte should be 0 for future compatibility reasons, but no error checking of the high order byte is performed.
pData
The address of the variable length data area which contains additional information that the system trace function will add to the trace buffer. If a length of 0 is specified, the address will not be used, but a value must still be added to the stack.

Results.

DosSysTrace returns the following vaules:

• NO_ERROR

  150

  ERROR_SYSTEM_TRACE (Trace is disabled for that event)

           IF AX = 0               Data traced
           ELSE
              AX = Error_System_Trace
                 Data not traced
  

  Note: An example of when data would not be traced is if the major event code is not currently selected for tracing.

  Remarks.

  All trace records consist of a header and optional data. The header record is built by DosSysTrace and contains:

  • Major event code
    
  • Minor event code
    
  • Process ID of caller
    
  • Time stamp when the time is different from the previous trace record
    
  • Flag field
    
  • Data field (optional)

  The optional data field contains the variable-length data as passed by the caller.

  The trace facility maintains an array of 32 bytes (256 bits), in which each bit represents a major event code. This array is updated each time the user enables or disables tracing of a major event. The trace facility checks this array each time it is called to ensure that the major event specified is currently enabled for tracing. The array is located in the Global Information Segment.

  A prototype definition for DosSysTrace may be found under RAS API Prototypes.

  ---

  [Back: DosSysTrace (Static Trace Event Recording)]
  [Next: DevHlp_RAS (Add a Trace Record to the System Trace Buffer)]