FIELD command

This section provides an overview of the Auxiliary command FIELD.

Usage

Use the FIELD command to define exception conditions. You can then filter individual records meeting these conditions by using the INCLUDE or EXCLUDE subcommand option.

Usage notes

The FIELD command is used only with the INCLUDE and EXCLUDE subcommand option with RECTRACE. By using FIELD, you define the location of the data in a particular IFCID type, a comparison operator, and a value to compare the data against. The OMEGAMON AI for Db2 Record traces produced include or exclude those records that meet the comparison value. For example:
```
 
//SYSIN DD *
FIELD (
	  QW0018ID,
	  18,
	  2,
	  0,
	  3,
	  C,
	  EQ,
	  INDX
	 )
RECTRACE
   TRACE
      LEVEL   (SHORT)
      INCLUDE (IFCID(18)
FIELD   (QW0018ID))
 
EXEC
```
This example reads the scan end record IFCID 18, looking for all records that contain index data (INDX). It produces a short Record trace containing only those scan end records that meet this condition.
Effective use of the FIELD command requires a detailed knowledge of the Db2® IFCID record formats.
You can specify the following with FIELD:
- A value you want used as a comparison value.
- A location within a particular type of performance input record (identified by IFCID) that you want compared to the comparison value.
- The type of comparison that you want to make between the previous two values (that is, data in the record equal to the comparison value).

The decision to include a record in the trace is based on whether the comparison was true or false (see Table 1) and whether the field name for the field definition was referenced in an INCLUDE or an EXCLUDE statement.

Table 1. Comparison values
Comparison True?	Field name Location	Decision
Yes	in INCLUDE	Record is used in the trace.
No	in INCLUDE	Record is not used in the trace.
Yes	in EXCLUDE	Record is not used in the trace.
No	in EXCLUDE	Record is used in the trace.

Syntax

Parameters

The syntax diagram shows the parameters that are available with this subcommand. The following list gives additional or specific descriptions of selected parameters, where appropriate.

field name

An 8-character name identifying a particular field.

IFCID

The decimal IFCID number of the performance record.

self defining section number

The decimal number identifying the self-defining data section that points to the data section containing the field to be compared. If the value is 0, the self-defining section identified is the first one that points to the product section. If the value is 1, the self-defining section is the first one that points to a data section.

offset

The decimal offset into the data section of the starting byte of the record field to be compared.

repeating group number

The number of repeating data sections where the comparison is made. If this field contains a value of 0, the comparison is made in all repeating data sections. If the value is, for example, 12, the self-defining section is the twelfth one that points to a data section.

Valid values are 0-99.

field type

A character indicating the type of data to be compared:

C: Character data
X: Hexadecimal data
F: Fullword binary data
H: Halfword binary data
O: Offset based field
D: Doubleword binary data

comparison type

The type of comparison to be made between the field in the performance record and the comparison value in the definition:

EQ: Equal to
NE: Not equal to
GE: Greater than or equal to
LE: Less than or equal to
GT: Greater than
LT: Less than

comparison value

The value to be compared to the defined field in the performance record:

Character data: Up to 16 characters can be entered. Character data containing blanks must be enclosed in single quotation marks. The quotation marks cannot be part of the comparison value.
Hexadecimal data: This value or constant represents a hexadecimal value, such as 0001D0F2. Up to 8 characters can be specified. Do not enclose the value in quotation marks.
Fullword binary: This data is converted into a fullword binary value. It is limited to the maximum value allowed in a fullword field.
Halfword binary: This data is converted into a halfword binary value. It is limited to the maximum value allowed in a halfword field.
Doubleword binary: This data is converted into a doubleword binary value. It is limited to the maximum value allowed in a doubleword field.

Example using the FIELD command

This example requests the following:

The name attributed to this field comparison is QXSELECT.
The IFCID of the input record where this comparison is made is 003.
The data section containing the data to be compared is defined by the second self-defining section.
The data to be compared is at decimal offset 008 in the data section.
The comparison is to be made in all occurrences of that data section (0).
The data to be compared is a fullword binary value (F).
The comparison is made as to whether the data in the data section is greater than the comparison value.
The comparison value is 100 in fullword binary format.

FIELD (
	    QXSELECT,
	    003,
	    02,
	    008,
	    0,
	    F,
	    GT,
	    100
	   )

Example using the FIELD command with the offset (O) option

This example requests the following:

The name attributed to this field comparison is PROCNAME.
The IFCID of the input record where this comparison is made is 272.
The data section containing the data to be compared is defined by the second self-defining section.
The variable indicating the offset to the variable length string to be compared is located at decimal offset 136 in the data section.
The comparison is to be made in all occurrences of that data section (0).
The data to be compared is an offset based field (O).
The comparison is made as to whether the data in the data section is equal to the comparison value.
The comparison value is the pattern string 'NAM*ES'.
The pattern string should be enclosed in single quotes and can include wildcard characters:
- * – match any number of characters
- ? – match any single character

FIELD (
	    PROCNAME,
	    272,
	    1,
	    136,
	    0,
	    o,
	    EQ,
	    'NAM*ES'
	   )