Using the template

To use the template, press F4. The VIT Extraction Template is displayed as shown in Figure 1.

All fields are optional. Any explicitly specified VIT entries, and VIT entries created by a specified option, are eligible for extraction if found in the trace. Only those eligible entries that meet all other specified selection criteria are extracted.

Figure 1. VIT extraction template

 ISTT0014                 VIT Extraction Template
 
 Type information in one or more fields, then press Enter. This information
 will be appended to the full expression.
 
 VIT options/entries _______  _______  _______  _______  _______  +
                     _______  _______  _______  _______  _______
 
 Address . . . . . . ___________  (Hexadecimal)
 Offset  . . . . . . _____  (Decimal or Hexadecimal)
 
 Character string  . ______________________________
 Offset  . . . . . . _____  (Decimal or Hexadecimal)
 
 Hexadecimal string  ________________________________
                     _______________________________
 Offset  . . . . . . _____  (Decimal or Hexadecimal)
 
 
 
 
 Command ===> ______________________________________________________________
⋮

The fields on the template are described below. Fill in the template and press Enter.

The template is checked for proper data type and length of data and saved. The resulting Boolean expression is then added to the VIT Extraction Boolean Expression panel. You can append multiple instances of the template, and a VIT entry that matches any of the templates will be extracted (when VIT extraction is invoked). The length of the resulting expression is limited to the input area on the VIT Extraction Boolean Expression panel.

Press F3 to exit, and you are given the option to save the expression you have created.

The fields on the extraction template are described as follows:

VIT options/entries

You may specify VIT options or entries to limit extraction to particular VIT entries. If you specify a VIT option, VIT entries created when the designated options are active are eligible for extraction if found in the trace. For example, the LOCK option generates the LKEX, LKSH, ULKA, and UNLK trace entries. If you specify LOCK and the LOCK option was used when the VIT was started, any LKEX, LKSH, ULKA, and UNLK entries found in the trace are eligible for extraction.

Note: User-defined (SNAP) entries are allowed. For further information, see z/OS Communications Server: SNA Diagnosis Vol 2, FFST Dumps and the VIT.

You may also specify particular VIT entries (for example, LKEX or LKSH), and an asterisk (*) may be used in a VIT entry name to match any character (for example, LK* matches VIT entries LKEX and LKSH). If an entry with multiple parts is specified, all parts are extracted (for example, if AI2 is specified, AI1, AI2, and AI3 are extracted).

If no VIT options or entries are specified, all VIT entries are eligible for extraction.

Address

Entries with this address are eligible for extraction. Specify up to 8 hex characters for an address. If fewer than eight digits are specified, the address is padded on the left with zeros. The low-order 31 bits of the address are then used to compare on all word boundaries if an offset is not specified. If an offset is specified, then only the offset is checked for a match. Address X'00000000' is allowed only when an offset for the address is also provided.

Address offset

The offset for an address is a word boundary offset into a trace record where a comparison should be made for the address. The offset must be one of the following values:

X'04', 4
X'08', 8
X'0C', 12
X'10', 16
X'14', 20
X'18', 24
X'1C', 28

Character string

Entries containing this character string are eligible for extraction. Enter a search string of 1–30 alphanumeric characters, which includes special characters (except a single quotation mark). Data entered is not converted to uppercase. Data is case-sensitive. By default, a comparison is made at all offsets.

Character string offset

You may include a byte offset into the VIT entries where comparisons should be made. The offset can be decimal or hex. The offset range is 2–31 or X'02'–X'1F'.

Note: The length of the character string determines the offset allowed. For example, if the character string entered consists of 8 characters, the valid offset range is 2–24. The string cannot start after byte 24, because a VIT entry is 32 bytes long (byte 0 through byte 31) and 8 bytes are needed to represent the string (bytes 24 – 31).

Hexadecimal string

Entries containing this hex string are eligible for extraction. Enter a search string of 2–60 hex characters representing 1–30 bytes of data. By default, a comparison is made at all offsets.

If you code an odd number of hex digits, they are padded to the left with a 0 to make 1 byte. For example; X'D' is equivalent to X'0D'.

Hexadecimal string offset

You may include an offset into the VIT entries where comparisons should be made. The offset can be decimal or hex. The offset range is 2–31 or X'02'–X'1F'.

Note:

The length of the hex string divided by 2 determines the offset allowed, because two hex digits represent one byte. For example, if the hex string entered consists of 8 hex digits, 4 bytes are needed to store the string, and the valid offset range is 2 – 28. The string cannot start after byte 28, because a VIT entry is 32 bytes long (byte 0 through byte 31) and 4 bytes are needed to represent the string (bytes 28 – 31).
Character and hex strings will not be found if they cross VIT entry boundaries. If a PIU is represented in the VIT as a PIU entry plus a series of PIU2 entries, and a string is requested that spans the end of one PIU2 and the beginning of a second PIU2, it will not be found.