![](dblue_rule.gif) |
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 FunctionsTRACE 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).
|