Subparameters for trace

This topic describes the subparameters for trace.

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
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	IDA019RZ	All I/O occurring during a CI split.
0009	IDA019RF	Start of a CA split.
0010	IDA019RF	After completion of a CA split.
0011	IDA019RZ	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.
	IDA019R2	Non-shared resources—after I/O, no errors.
0016	IDA019RW, IDA019SY	Shared resources—after I/O, error occurred.
	IDA019R2	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	IDAVCCMS	Before data record is compressed.
0021	IDAVCCMS	After data record is compressed.
0022	IDAVCCMS	Before data record is decompressed.
0023	IDAVCCMS	After data record is decompressed.
0024	IDAM19R3	Prior to SVC 121 for reads of CIS.
0025		Reserved.
0026	IDA019SC	Start of a CI reclaim.
0027	IDA019SC	After completion of a CI reclaim.
0028–0255		Reserved.

Note:

There is no limit to the number of trace points you can specify to trace.
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

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)
Byte 0	Notes	Description
1... ....		Reserved.
.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)
Byte 1	Notes	Description
1... ....	2	BSPH–buffer subpool header.
.1.. ....	2	BUFC–buffer control block.
..1. ....	1	CMB–cluster management block.
...1 ....		CMWA-Compression work 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)
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...		IXT-Index Trap Save area.
.... .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)
Byte 3	Notes	Description
1... ....		RPL–request parameter list.
.x.. ....		Reserved.
..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)
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.
... ..x.		Reserved.
... ...1		No PLH suppression.

Table 7. 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

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) that is shown in Table 8.

Table 8. PARM2 Subparameter Bits (Byte 5)
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:

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.
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.
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.
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.
- The compression work area, CMWA, will only be captured while tracing at Hook 20 through 23 during compression processing.
The VSAM Index Trap save area, IXT, will only be captured while tracing at Hook 8 (All I/O occurring during a CI split) and Hook 11 (All I/O occurring during a CA split).