Design overview

The trace domain consists of a set of modules that are used to record and manage trace information about internal, auxiliary, and GTF trace. The services of the trace domain are requested by making domain calls, described in Domain calls. The modules that handle these domain calls are DFHTRDM, DFHTRPT, and DFHTRSR.

Certain sub-functions of the trace domain are required by more than one of these modules. These sub-functions are packaged together in the DFHTRSU module, and are invoked by domain subroutine calls, described in Subroutine calls.

All processing directly related to the auxiliary trace data sets is carried out by the DFHTRAO module. DFHTRAO is loaded below the 16MB line so that it can run in 24-bit mode when calling BSAM and referencing the auxiliary trace data set data control block (DCB). The DFHTRAO functions are described in DFHTRAO functions.

TRACE_PUT handling

For performance reasons, it is important to minimize the path length of a request to write a trace entry. This is achieved for most TRACE_PUT requests by handling them in module DFHTRPX, which runs as a subroutine of the domain that is requesting the trace.

DFHTRPX runs in a very restricted environment. It has no working storage and can make no calls out. Nevertheless, it can still handle the majority of TRACE_PUT requests. When DFHTRPX cannot handle a request, it passes control to the TRPT gate of the trace domain for module DFHTRPT to process the request.

DFHTRPX passes control to DFHTRPT in the following situations:

Locking

The trace domain handles TRACE_PUT requests from many MVS™ task control blocks (TCBs), and so requires a locking mechanism to prevent overlapping or simultaneous access to its control blocks. This is an MVS TCB lock and is provided by the LOCK and UNLOCK functions of the DFHKERN macro.

DFHTRPX does not acquire the trace lock. It uses "compare double and swap" (CDS) logic to serialize the allocation of space for trace entries in the internal trace table.

Selectivity

The overall trace master flag is logically a combination of the flags controlling internal, auxiliary, and GTF trace. It is owned by the trace domain, and both the kernel and the common system area (CSA) have their own copies that are kept up-to-date by calls from the trace domain.

The user trace master flag is owned by the AP domain. The system trace master flag and the standard and special component trace flags are owned by the kernel. None of these flags is referenced by the trace domain.

Domain calls

This topic lists the process flows for the domain calls used for the trace domain services.

DMDM gate, PRE_INITIALIZE function

  1. Issue an MVS GETMAIN for the trace domain anchor block (TRA) and initialize it.
  2. Acquire startup information from the parameter manager (PA) domain and set it in the TRA. The relevant startup parameters are INTTR, TRTABSZ, AUXTR, AUXTRSW, and GTFTR.
  3. Call TRSU SET_UP_INTERNAL_TABLE to get and initialize the internal trace table.
  4. Call TRSU GET_GTF_BUFFER to initialize CICS tracing to GTF.
  5. Issue the KEDD ADD_GATE call for the DFHTRPT gate to inform the kernel that the trace domain is available.
  6. If internal trace or GTF trace is started, turn on the trace master flags in the TRA, the kernel, and the CSA.

DMDM gate, INITIALIZE_DOMAIN function

  1. If required, call TRSR ACTIVATE_TRAP to active the FE global trap/trace exit, DFHTRAP.
  2. If required, call TRSR START_AUXILIARY_TRACE to start auxiliary trace on DFHAUXT.

DMDM gate, QUIESCE_DOMAIN function

Do nothing.

DMDM gate, TERMINATE_DOMAIN function

If auxiliary trace is active, call TRSR STOP_AUXILIARY_TRACE.

KETI gate, NOTIFY_RESET function

Call KETI CONVERT_TO_STCK_FORMAT to get the new STCK value for the last local midnight, and store this in the TRA.

TRPT gate, TRACE_PUT function

  1. Acquire the trace lock.
  2. Calculate the length of the required entry.
  3. If the entry does not fit in the current trace block (TRBL) and auxiliary trace is active, call TRSU WRITE_AUX_BUFFER.
  4. Use "compare double and swap" (CDS) to update pointer and available length for next entry in the TRA.
  5. Build the entry in allocated space.
  6. If GTF trace is required, issue the GTRACE macro to write an entry to GTF, and if the entry is more than 256 bytes, split it into multiple entries.
  7. If the FE global trap/trace exit, DFHTRAP, has been activated as a result of using the CSFE DEBUG transaction, or specifying the TRAP=ON system initialization parameter, invoke the exit. See the CICS Problem Determination Guide for details of DFHTRAP.
  8. Release the trace lock.

TRSR gate, SET_INTERNAL_TABLE_SIZE function

  1. If the call is from the parameter manager (during initialization), set the required size in the TRA and return.
  2. Acquire the trace lock.
  3. If auxiliary trace is active, call TRSU WRITE_AUX_BUFFER to write the current TRBL.
  4. If the new table size is smaller, free part of the old table and reset chaining and pointers.
  5. If a larger table is required, free all but 16KB (KB equals 1024 bytes) of the old table. Call TRSU SET_UP_INTERNAL_TABLE. If this completes correctly, free the 16KB that was kept back. If it does not work, make the 16KB piece the new table.
  6. Release the trace lock.

TRSR gate, START_INTERNAL_TRACE function

  1. Set the required status in the TRA.
  2. If the call is from the parameter manager (during initialization), return.
  3. If required, change the kernel and CSA copies of the trace master flag.

TRSR gate, STOP_INTERNAL_TRACE function

  1. Set the required status in the TRA.
  2. If the call is from the parameter manager (during initialization), return.
  3. If required, change the kernel and CSA copies of the trace master flag.

TRSR gate, INQUIRE_INTERNAL_TRACE function

Get the internal status and internal table size from the TRA.

TRSR gate, START_AUXILIARY_TRACE function

  1. If the call is from the parameter manager (during initialization), set the status in the TRA and return.
  2. If already started, return immediately.
  3. If auxiliary trace is currently stopped (rather than paused):
    1. Issue an MVS GETMAIN for an auxiliary trace buffer, DCB, and DECB storage.
    2. Issue LDLD ACQUIRE_PROGRAM for DFHTRAO.
    3. Call DFHTRAO to OPEN the auxiliary trace data set.
  4. Acquire the trace lock.
  5. Skip the current TRBL pointer in the TRA to the next TRBL to avoid entries from before start appearing in the auxiliary trace.
  6. Release the trace lock.
  7. Set the auxiliary trace status in the TRA to started.
  8. If required, change the kernel and CSA copies of the trace master flag.

TRSR gate, STOP_AUXILIARY_TRACE function

  1. If the call is from the parameter manager (during initialization), set the status in the TRA and return.
  2. If already stopped, return immediately.
  3. Acquire the trace lock.
  4. If auxiliary trace is started (rather than paused), call TRSU WRITE_AUX_BUFFER to output the current TRBL to the auxiliary trace data set, and move the current TRBL pointer in the TRA to the next TRBL.
  5. Call TRSU WRITE_AUX_BUFFER to write an end-of-file indication on the auxiliary trace data set.
  6. Call DFHTRAO to ensure (CHECK) that output is complete.
  7. Call DFHTRAO to CLOSE the auxiliary trace data set.
  8. Call TRSU TERMINATE_AUXILIARY_TRACE.
  9. Release the trace lock.
  10. Issue LDLD RELEASE_PROGRAM for DFHTRAO.

TRSR gate, PAUSE_AUXILIARY_TRACE function

  1. If auxiliary trace is stopped, return with error.
  2. If auxiliary trace is paused, return ‘OK’.
  3. Acquire the trace lock.
  4. Call TRSU WRITE_AUX_BUFFER to output the current TRBL to the auxiliary trace data set, and move the current TRBL pointer in the TRA to the next TRBL.
  5. Release the trace lock.
  6. Change the kernel and CSA copies of the trace master flag if required.

TRSR gate, SET_AUX_TRACE_AUTOSWITCH function

Set the new autoswitch status in the TRA.

TRSR gate, SWITCH_AUXILIARY_EXTENTS function

  1. If auxiliary trace is started or paused:
    1. Acquire the trace lock.
    2. Call TRSU WRITE_AUX_BUFFER to write an end-of-file indication on the auxiliary trace data set.
    3. Call DFHTRAO to ensure (CHECK) that output is complete.
    4. Call DFHTRAO to close the auxiliary trace data set.
  2. Change the name of the current extent in the TRA from DFHAUXT to DFHBUXT or from DFHBUXT to DFHAUXT.
  3. If auxiliary trace is started or paused:
    1. Call DFHTRAO to OPEN the auxiliary trace data set.
    2. Release the trace lock.

TRSR gate, INQUIRE_AUXILIARY_TRACE function

Get the auxiliary trace status, current extent name, and autoswitch status from the TRA.

TRSR gate, START_GTF_TRACE function

  1. If the call is from the parameter manager (during initialization), set the required status in the TRA and return.
  2. If already started, return immediately.
  3. Call TRSU GET_GTF_BUFFER.
  4. Set the status in the TRA to started.
  5. If required, change the kernel and CSA copies of the trace master flag.

TRSR gate, STOP_GTF_TRACE function

  1. Set the status in the TRA to stopped.
  2. If the call is from the parameter manager (during initialization), return.
  3. If required, change the kernel and CSA copies of the trace master flag.
  4. If the GTF buffer is present:
    1. Acquire the trace lock.
    2. Issue an MVS FREEMAIN for the GTF buffer.
    3. Release the trace lock.

TRSR gate, INQUIRE_GTF_TRACE function

Get the GTF status from the TRA.

TRSR gate, ACTIVATE_TRAP function

  1. If the call is from the parameter manager (during initialization), set the required status in the TRA and return.
  2. If the trap is already active, check whether it is marked unusable because a program check occurred while the trap was in control:
    1. If the trap is unusable, return with error.
    2. If the trap is usable, set the required status in the TRA and return.
  3. Issue LDLD ACQUIRE_PROGRAM for DFHTRAP.
  4. Issue an MVS GETMAIN for the DFHTRAP work area (TRGTW).
  5. Acquire the trace lock.
  6. Check whether another task has activated the trap:
    1. If the trap is not active, update the trap status in the TRA, release the trace lock, and return.
    2. If the trap has been activated by another task, release the trace lock, issue LDLD RELEASE_PROGRAM for DFHTRAP, issue an MVS FREEMAIN for the DFHTRAP work area, and return.

TRSR gate, DEACTIVATE_TRAP function

  1. If the call is from the parameter manager (during initialization), set the required status in the TRA and return.
  2. If the trap is not active, return.
  3. Acquire the trace lock.
  4. Update the trap status in the TRA.
  5. Release the trace lock.
  6. Issue LDLD RELEASE_PROGRAM for DFHTRAP.
  7. Issue an MVS FREEMAIN for the DFHTRAP work area.

Subroutine calls

This topic lists the process flows for the domain subroutine calls used for the trace domain sub-functions.

TRSU format, WRITE_AUX_BUFFER function

  1. If output to the auxiliary trace data set is pending, call DFHTRAO with a CHECK request to allow output to complete.
  2. If there was no output pending or the output completed successfully, call DFHTRAO to write the current TRBL, and return.
  3. If an ‘end of extent’ was encountered on the BSAM CHECK:

  4. Call DFHTRAO to close the auxiliary trace data set.
  5. If autoswitch is not required:
    1. Issue an MVS FREEMAIN for the auxiliary trace buffer, DCB, and DECB.
    2. Set auxiliary trace status in the TRA to stopped.
    3. Change the kernel and CSA copies of the trace master flag if required.
    4. Return.
  6. If autoswitch next is specified, change to autoswitch off.
  7. Change the name of the current extent in the TRA from DFHAUXT to DFHBUXT or from DFHBUXT to DFHAUXT.
  8. Call DFHTRAO to OPEN the auxiliary trace data set.
  9. Call DFHTRAO with a WRITE request to rewrite the block that caused the end-of-extent.
  10. Go back to the top of this function’s processing to issue the write that was originally requested in this call.

TRSU format, TERMINATE_AUXILIARY_TRACE function

  1. Issue an MVS FREEMAIN for the auxiliary trace buffer, DCB, and DECB.
  2. Set the auxiliary trace status in the TRA to stopped.
  3. If required, change the kernel and CSA copies of the trace master flag.

TRSU format, GET_GTF_BUFFER function

  1. Issue an MVS GETMAIN for the GTF buffer.
  2. Save the address in the TRA.

TRSU format, SET_UP_INTERNAL_TABLE function

  1. Issue an MVS V-type GETMAIN for the required size.
  2. Initialize all TRBL headers within the acquired area.

DFHTRAO functions

This topic lists the process flows for the DFHTRAO functions for auxiliary trace data sets.

DFHTRAO, OPEN function

  1. If the DCB indicates already open, return ‘OK’.
  2. Issue the BSAM OPEN macro.

DFHTRAO, CLOSE function

  1. If the DCB indicates already closed, return ‘OK’.
  2. Issue the BSAM CLOSE macro.

DFHTRAO, CHECK function

  1. Issue the BSAM CHECK macro.
  2. If an end-of-extent is caused by the write for which this CHECK is issued, the DCB ABEND exit is driven and causes DFHTRAO to return an end-of-extent indication to the caller.
  3. Clear output pending status in TRA.

DFHTRAO, WRITE function

  1. Move the specified TRBL to the auxiliary trace buffer.
  2. Issue the BSAM WRITE macro.
  3. Set output pending status in the TRA.
[[ Contents Previous Page | Next Page Index ]]