Starting the record management trace function

You must take the following steps to use trace:
  1. Activate GTF on your system. When you start GTF, specify USR or USRP with an AM01 event identifier, which is X'FF5'. If neither USR or USRP is specified, GTF ignores the data passed to it by trace.
  2. Place an AMP=('TRACE=(subparameters)') on the DD statement of the data set that you want to trace.

The AMP=('TRACE=(subparameters)') specifies to VSAM that you want to trace the control blocks associated with the data set identified by the DD statement. For complete syntax information on the AMP parameter, see the section on coding the DD statement in z/OS MVS JCL Reference.

The following are the valid subparameters for trace, including their brief descriptions.
  • HOOK=(n,n,...) specifies where in the VSAM R/M code tracing is to occur. The default is HOOK=(1). HOOK is an optional subparameter.

    Table 1 lists the predefined trace point IDs, their associated modules, and their functions.

    Table 1. Predefined trace IDs, modules, and functions. Predefined trace IDs, modules, and functions
    Trace point ID Module Description
    0000 IDA019R1 Entry to VSAM.
    0001 IDA019R1 Exit from VSAM.
    0002 IDAM19R3 Prior to SVC 121 for writes of CIs (no reads).
    0003 IDA019RZ After I/O, wait for CI reads and writes.
    0004 IDA019SE Prior to call to EOV (SVC 55).
    0005 IDA019SE After return from EOV.
    0006 IDA019RE Start of a CI split.
    0007 IDA019RE After completion of a CI split.
    0008 IDA019R3 All I/O occurring during a CI split.
    0009 IDA019RF Start of a CA split.
    0010 IDA019RF After completion of a CA split.
    0011 IDA019R3 All I/O occurring during a CA split.
    0012 IDA019RJ Prior to index CI split (IDA019RJ entry).
    0013 IDA019RI After call to IDA019RJ (index split).
    0014 IDA019RU After completion of an upgrade request.
    0015 IDA019RW, IDA019SY Shared resources—after I/O, no errors.
      IDA019RZ Non-shared resources—after I/O, no errors.
    0016 IDA019RW, IDA019SY Shared resources—after I/O, error occurred.
      IDA019RZ Non-shared resources—after I/O, error occurred.
    0017 IDA019RP After return from JRNAD exit.
    0018 IDA019S7 Before SVC 109 call to update the VSI block.
    0019 IDA019S7 Before control blocks are updated from VSI.
    0020 IDA019R4 Before data record is compressed.
    0021 IDA019R4 After data record is compressed.
    0022 IDA019R4 Before data record is decompressed.
    0023 IDA019R4 After data record is decompressed.
    0024 IDAM19R3 Prior to SVC 121 for reads of CIS.
    0025 through 0099   Reserved.
    0100 through 0255   User trace points.
    Note:
    1. There is no limit to the number of trace points you can specify to trace.
    2. The HOOK subparameter must be enclosed in parentheses, even if only one trace point ID is specified (for example, HOOK=(1)).
  • ECODE=ANY|codenumber Limits tracing. When used, tracing occurs only if an error code is being returned to the caller. If ANY is specified, tracing is performed for any nonzero return code. If codenumber (a specific error code) is provided, tracing occurs only if the RPLFDBK code matches that error code.

    ECODE is an optional subparameter. If ECODE is not used, the RPLFDBK code will not determine if tracing is to occur.

    When an error code (codenumber) is given, it must be a positive decimal number. For example, ECODE=12 causes tracing when one of the following situations occurs:
    • A buffer needs to be written
    • An attempt was made to store a record out of ascending order sequence
    • A physical read error occurred for an index component sequence set.
    The three error situations are indicated by the RPLFDBK code of X'0C' and the content of register 15 which is 0, 8, or 12, respectively.
    Note: If the user's LERAD or SYNAD exit routine resets the return code before VSAM returns to the caller, this exit routine may fail. Its failure depends on which trace point is active, and when the call to the user's exit routine is made. See z/OS DFSMS Installation Exits for more information on user exit routines.
  • KEY=keydata|lowRBA-highRBA Limits tracing. When used, tracing only occurs if the record key matches keydata, or if the record's RBA value is within the range of the lowRBA and highRBA values. Keydata is the EBCDIC representation of the whole key or the first few characters of a range of keys. KEY is an optional subparameter.

    If KEY=keydata is specified, the keydata may be any length up to 44 bytes. The keydata value does not need to be the same length as the record's key length. The shorter key length is used to determine the amount of bytes to be compared; this allows you to use generic key values and specify a range of keys.

    If KEY=lowRBA-highRBA is specified, tracing occurs only if the RBA of the record being processed is within the range of lowRBA and highRBA values.

    PARM1, byte 5 bit 5 determines the value of the KEY. If this bit is 0, the KEY field contains a key value; if this bit is 1, the KEY field contains an 8-byte lowRBA value, a dash, and an 8-byte highRBA value.

    Note: The KEY subparameter must not contain quotes, commas, or parentheses.
  • PARM1=trace options

    PARM1 controls the tracing of any user-opened data sets.

    The PARM1 subparameter specifies which VSAM Record Management data areas are to be traced. It controls the tracing of the user-opened data sets.

    PARM1 is required. If TRACE is specified without any subparameters, only VSAM Open/Close/EOV GTF records are built.

    For an extended format data set, the CPA is not a valid control block to trace. If specified, the CPA will be ignored.

    For a compressed data set, the buffers might contain data in a compressed format.

    The PARM1 value must be entered in hexadecimal. Each bit in the subparameter represents a trace option. If the bit is active (1), the corresponding control block is traced or, in the case of bits in byte 5, the corresponding condition is taken. The bits are as follows:

    Table 2. PARM1 subparameter bits, byte 0. PARM1 subparameter bits, byte 0
    Byte 0 Notes Description
    1... .... 1 ABP–actual block processor.
    .1.. .... 1 ACB–access method control block.
    ..1. ....   AMB–access method block.
    ...1 .... 1 AMBL–access method block list.
    .... 1...   AMBXN–access method block extension.
    .... .1..   AMDSB–access method data set statistics block.
    .... ..1. 1 ARDB–address range definition block.
    .... ...1 1 BIB–base information block.

     

    Table 3. PARM1 subparameter bits, byte 1. PARM1 subparameter bits, byte 1
    Byte 1 Notes Description
    1... .... 2 BSPH–buffer subpool header.
    .1.. .... 2 BUFC–buffer control block.
    ..1. .... 1 CMB–cluster management block.
    ...1 .... 7 CPA–channel program area.
    .... 1... 1 CSL–core save list.
    .... .1..   DIWA–data insert work area.
    .... ..1. 1 EDB–extent definition block.
    .... ...1 1 HEB–header element block.

     

    Table 4. PARM1 subparameter bits, byte 2. PARM1 subparameter bits, byte 2
    Byte 2 Notes Description
    1... ....   ICWA–index create work area.
    .1.. ....   IICB–ISAM interface control block.
    ..1. ....   IMWA–index modification work area.
    ...1 ....   IOMB–I/O management block.
    .... 1... 7 IOSB–I/O supervisor block.
    .... .1..   IXSPL–index search parameter list.
    .... ..1. 1 LPMB–logical-to-physical mapping block.
    .... ...1 2 PLH–placeholder.

     

    Table 5. PARM1 subparameter bits, byte 3. PARM1 subparameter bits, byte 3
    Byte 3 Notes Description
    1... ....   RPL–request parameter list.
    .1.. ....   SRA–sphere record area.
    ..1. ....   UPT–upgrade table.
    ...1 .... 1 VAT–valid AMBL table.
    .... 1... 1 VMT–volume mount table.
    .... .1..   VSI–VSAM shared information block.
    .... ..1. 1 VVT–VSRT vector table.
    .... ...1   VSRT–VSAM shared resources table.

     

    Table 6. PARM1 subparameter bits, byte 4. PARM1 subparameter bits, byte 4
    Byte 4 Notes Description
    1... ....   WAX–work area for path processing.
    .1.. ....   WSHD–working storage header.
    ..1. .... 2 Buffers.
    ...1 ....   User's search argument or key
    .... 1...   User's record.
    ... .1..   Caller's registers.
    ... ..1. 6 Compression blocks
    ... ...x   Reserved.

     

    Table 7. PARM1 subparameter bits, byte 5. PARM1 subparameter bits, byte 5
    Byte 5 Notes Description
    1... ....   Do not trace data control blocks.
    .1.. ....   Do not trace index control blocks.
    ..1. .... 2 Trace all control blocks.
    ...1 .... 1 Limit: one trace of control blocks.
    .... 0...   KEY=keydata (the KEY contains a key value).
    .... 1...   KEY=lowRBA-highRBA (the KEY contains RBA values).
    .... .1..   Trace AIX, PATH, or UPGRADE processing (PARM2 required).
    .... ..1. 3 Validity-check control blocks; trace if bad.
    .... ...x   Reserved.
  • PARM2=trace options

    PARM2 controls the tracing of any VSAM-opened data sets.

    The PARM2 subparameter is used to control the tracing of:
    • An alternate index's base cluster when opened as a path
    • A base cluster's UPG (upgrade) data set.

    PARM2 is used only if PARM1, byte 5 bit 5 (X'04') is specified. It has the same options as PARM1's except for the last byte (byte 5), which Table 8 shows.

    Table 8. PARM2 subparameter bits. PARM2 subparameter bits
    Byte 5 Notes Description
    xxxx ....   Same usage as in PARM1.
    .... xx..   Reserved.
    .... ..1. 4 Trace all associated data sets.
    .... ...1 5 Trace UPGRADE control blocks.
    Notes:
    1. When limit: one trace of control blocks (byte 5 bit 3) is specified, the control blocks indicated with note 1 are traced only on the first call to R/M trace. These control blocks, generally, do not change after the data set is opened.
    2. When trace all control blocks (byte 5 bit 2) is specified, the control blocks indicated with note 2 are traced even when the current request does not use them. If this bit is off, only those control blocks directly associated with the active request are traced.

      Attention: Turning this bit on can cause a large amount of GTF data, depending on the number of strings and buffers and the size of buffers.

    3. This option causes R/M trace to validity-check the pointers in the VSAM R/M control blocks, and if a chaining error is detected, the trace is taken.
    4. When byte 5 bit 6 of PARM2 is off, only the data set being processed when R/M trace was called is traced. When this bit is on, R/M trace locates and traces data sets associated with the calling data set.
      • If the calling or associated data set was user-opened, PARM1 is used.
      • If the calling or associated data set was VSAM-opened, PARM2 is used.
      • When byte 5 bit 7 of PARM2 is off, UPGRADE data sets are not traced unless the UPGRADE was the calling data set. When byte 5 bit 7 of PARM2 is on, R/M trace treats UPGRADES as associated data sets; they are traced when the calling data set is a path, alternate index, or base.
      • When byte 4 bit 6 of PARM1 is on, tracing of compression related control blocks will occur. This includes control blocks CMSP, CMWA, and PCB. The data buffers for a compressed data set will not be traced unless both the buffers and compression block bits are set on.
      • Tracing of the CPA and IOSB is ignored for data sets defined as extended format or compressed.
Parent topic: VSAM record management trace facility (non-RLS access)