FIELD

Trigger field syntax

To specify a trigger field, you must assign the field a number prefixed by FIELD, then specify the location of the field on the report.

Multiplatforms syntax:

FIELDn=record,column,length,(TRIGGER=n,BASE={0 | TRIGGER}[,MASK='@#=¬^%' | REGEX='regular expression'][,DEFAULT=X'value]')

z/OS® syntax:

FIELDn=record,column,length,(TRIGGER=n,BASE={0 | TRIGGER}[,MASK='@#=¬^%'][,DEFAULT=X'value]')

Trigger field options and values

n

The field parameter identifier. When adding a field parameter, use the next available number, beginning with 1 (one).

record

The relative record number from the trigger on which the field is based. This is the record number where ACIF begins to search for the field. The supported range of values are ±0 to 255.

column

The relative column number from the BASE. This is the column number where ACIF begins to search for the field. A value of 1 (one) refers to the first byte in the record. For files containing carriage-control characters, column one refers to the carriage-control. For those applications that use a specific carriage-control character to define page boundaries (for example, skip-to-channel one), consider defining the value of the carriage-control character as one of the TRIGGER parameters. If you specify BASE=0, the column value can be 1 to 32756. If you specify BASE=TRIGGER, the column value can be -32756 to 32756.

When you specify the column number of the field, if the specified value exceeds the physical length of the record, ACIF reports an error condition and terminates processing unless you specify a DEFAULT value.

length

The number of contiguous bytes (characters) that compose the field. The supported range of values are 1 to 250. The field can extend outside the record length if the column where it begins is within the record length. In this case, ACIF adds padding blanks to complete the record. If the field begins outside the maximum length of the record, ACIF reports an error condition and terminates processing unless you specify a DEFAULT value.

TRIGGER=n

Identifies the trigger parameter ACIF uses to locate the field. This is an optional parameter, but the default is TRIGGER1. Replace n with the number of a defined TRIGGER parameter.

BASE={0|TRIGGER}

Determines whether ACIF uses the starting column number of the trigger string value to locate the field data. Choose from 0 (zero) or TRIGGER. If BASE=0, ACIF adds zero to the field column offset. If BASE=TRIGGER, ACIF adds the starting column number of the trigger string value to the field column offset.

Use BASE=0 if the field data always starts in a specific column. Use BASE=TRIGGER if the field data does not always start in a specific column, but is always offset from the trigger string value a specific number of columns.

For example, a trigger occurs in the second record on a page. The trigger string value can begin in any column in the record. A field based on this trigger occurs in the trigger record. The starting column number of the field is always ten bytes from the starting column number of the trigger. Specify BASE=TRIGGER and a column offset of ten so that ACIF correctly locates the field, regardless of the starting column of the trigger string value.

MASK='@#=¬^%'

Specifies a pattern of symbols that ACIF uses to match data located in the field columns. If the data matches the MASK, then ACIF selects the field. Important: If you specify a MASK, then the field must be based on a floating trigger. An INDEX parameter that is based on the field cannot include any other fields and must not create grouprange or pagerange indexes.

You can specify the following symbols in the MASK:

@

Matches alphabetic characters.

#

Matches numeric characters.

=

Matches any character.

¬

Matches any non-blank character.

^

Matches any non-blank character.

%

Matches the blank character and numeric characters.

For example, given the following definitions:

TRIGGER2=*,25,'SOURCE',(TYPE=FLOAT)
FIELD2=0,38,4,(TRIGGER=2,BASE=0,MASK='####')

ACIF selects the field only if the data in the field columns contains numeric characters.

REGEX='regular expression'

ACIF extracts the text specified by the column and length values. After the field is extracted, ACIF applies the regular expression to the text. Any text that matches the regular expression is extracted for the field. If the matching text is shorter than the length specified in the FIELD, it is padded with blanks until it equals the length. If the regular expression does not match any text in the field, the following occurs:

For a field based on a Group trigger the default value specified on the FIELD is used. If no default value is specified, ACIF ends with error message APK488.

For a field based on a Float trigger, there is no error and the default value specified on the FIELD is not used. In this case the load process will use the default value specified in the Application.

If the record is only long enough to contain part of the field, the regular expression is applied only to the portion of the record that is present.

The regular expression must be specified in the code page given by the CPGID parameter. It can be specified in hexadecimal.

The maximum length of the regular expression is 250 bytes. A mask and a regular expression cannot both be specified on the same FIELD parameter.

Restriction: The REGEX parameter is not available on z/OS operating systems.

DEFAULT='value'

Determines the default value for the index when a record is not long enough to contain the field data, or (on Content Manager OnDemand for Multiplatforms systems only) if a regular expression does not match any field data. The default value can be specified either as a character string or a hexadecimal string. If the data to be indexed is anything other than ASCII, then the default value must be specified as a hexadecimal string, for example, X'value'. Given the following definition:

FIELD2=1,77,4,(DEFAULT=X'D5D6D5C5')

ACIF assigns the index associated with FIELD2 the value D5D6D5C5 (NONE), if a record is not 77 bytes in length.

Remember: If a record is not long enough to contain the field data and you do not specify a default value, ACIF will fail.

Trigger field examples

TRIGGER1=*,1,X'F1',(TYPE=GROUP)
FIELD1=0,83,8,(TRIGGER=1,BASE=0)

TRIGGER2=*,*,X'E2A482A396A38193',(TYPE=FLOAT)
FIELD2=0,10,12,(TRIGGER=2,BASE=TRIGGER)

TRIGGER1=*,1,'1'
FIELD1=0,13,18,(REGEX='[A-Z][a-z]+ [0-9]+, [0-9]{4}')

Constant field syntax

A constant field cannot be concatenated in an index with a field that is based on a floating trigger. A constant field is a field for which you specify the actual index value that will be stored in the database.

It is possible to generate an index value by concatenating or combining the value that you specify for a constant field with the value that ACIF extracts from a document by using a trigger field. The trigger field cannot be based on a floating trigger.

Constant field options and values

n

The field parameter identifier. When adding a field parameter, use the next available number, beginning with 1 (one).

constant

The literal (constant) string value of the field. This is the index value stored in the database. If the input data contains unformatted ASCII data, the constant can be specified either as character data or hexadecimal data. Specify a hexadecimal value by using the format X'constant' where constant is hexadecimal data. If the input data contains EBCDIC data, the constant must be specified as hexadecimal data. The constant value can be 1 to 250 bytes in length. The constant value can be 250 bytes of character data, or 125 hexadecimal characters, since each hexadecimal character contains 2 bytes. ACIF does not validate the actual content of the supplied data.

Constant field examples

FIELD3=X'F0F0F0F0F0F0F0F0F0'
INDEX3=X'D5D6D6D7',FIELD3,(TYPE=GROUP,BREAK=NO)

The following field parameters cause ACIF to concatenate a constant value with the index value extracted from the data. ACIF concatenates the constant value specified in the FIELD3 parameter to each index value located by using the FIELD4 parameter. The concatenated string value is stored in the database.

FIELD3=X'F0F0F0F060'
FIELD4=0,66,14
INDEX3=X'818383A36D95A494',FIELD3,FIELD4,(TYPE=GROUP,BREAK=YES)

Transaction field syntax

To specify a transaction field, the syntax must include a field name and the location on the report to obtain the field value.

Multiplatforms syntax:

FIELDn=*,*,length, (OFFSET=(start1:end1[,...start8:end8]) ,MASK='@#=?^%' |REGEX='regular expression'[,ORDER={BYROW | BYCOL}])

z/OS syntax:

FIELDn=*,*,length, (OFFSET=(start1:end1[,...start8:end8]) ,MASK='@#=¬^%'[,ORDER={BYROW | BYCOL}])

Transaction field options and values

n

The field parameter identifier. When adding a field parameter, use the next available number, beginning with 1 (one).

*

The record number where ACIF begins searching for the field. A transaction field must specify an asterisk, meaning ACIF searches every record in the group.

*

The column number where ACIF begins searching for the field. A transaction field must specify an asterisk. The OFFSET specification determines the column or columns where ACIF locates the field.

Note: If you enter a value other than an asterisk, ACIF ignores the value. When you specify the OFFSET keyword of the FIELD parameter, ACIF always uses the starting column number(s) from the OFFSET keyword to determine the location of the field value(s).

length

The number of contiguous bytes (characters) that compose the field. The supported range of values are 1 to 250. The field can extend outside the record length, if the column where it begins lies within the record length. In this case, ACIF adds padding blanks to fill out the record. If the field begins outside the maximum length of the record, ACIF reports an error condition and terminates processing.

OFFSET=(start:end)

Determines the location of the field value from the beginning of the record. The start is the column where the field begins. The end is the last column of field data. A maximum of eight pairs of beginning and ending offset values are allowed. Separate the pairs with a comma. When you specify the OFFSET keyword, you must also specify the MASK or REGEX keyword. The implied length of an OFFSET value must be the same as the number of characters in the MASK, or ACIF will not detect a match.

MASK='*@#=¬^%'

Determines the pattern of symbols that ACIF matches with data located in the field columns. You can specify either a mask or a regular expression, but not both. When you specify the MASK keyword, you must also specify the OFFSET keyword. When you define a transaction field that includes a mask, an INDEX parameter based on the field cannot reference any other fields. An INDEX parameter based on a transaction field that includes a mask must create grouprange or pagegrange indexes. Valid mask symbols include:

*

Not literal; matches a user-defined mask.

@

Matches alphabetic characters.

#

Matches numeric characters.

¬

Matches any nonblank character.

^

Matches any nonblank character.

%

Matches the blank character and numeric characters.

=

Matches any character.

Code page 850 is the default code page for the symbols in the MASK. If you specify a different code page (on the CPGID parameter), ACIF translates all characters in the MASK value, except the MASK symbols. ACIF then matches the input characters against the MASK value. For example, the following definitions cause ACIF to search for a hexadecimal C1 followed by four numeric characters (hexadecimal F0-F9), a hexadecimal 60, and two numeric characters (hexadecimal F0-F9):

CPGID=500
     FIELD3=*,*,8,(OFFSET=(10:17),MASK='A####-##',ORDER=BYROW)

REGEX='regular expression'

The regular expression that ACIF matches with data located in the field columns. The regular expression must be specified in the code page given by the CPGID parameter, and can be from 1 to 250 bytes in length. The regular expression can be specified in hexadecimal. You can specify either a mask or a regular expression, but not both.

When you specify the REGEX keyword, you must also specify the OFFSET keyword. When you define a transaction field that includes a regular expression, an INDEX parameter based on the field cannot reference any other fields. An INDEX parameter based on a transaction field that includes a regular expression must create grouprange or pagegrange indexes. Here are some examples of common regular expressions:

Table 1. Common regular expressions

Regular expression	Results
Account	Finds the characters "Account." By default searches are case sensitive.
[A-Z]	Finds one uppercase letter.
[A-Z]{3}	Finds three consecutive uppercase letters.
[0-9]{5}	Finds five consecutive digits.
[0-9]+	Finds one or more digits.
[^a-z]	Finds everything except lowercase a to z.
\s	Finds one whitespace character (space, tab, etc).
\S	Finds any character except for whitespace.

For example, the following definitions:

CPGID=850
FIELD3=*,*,8,(OFFSET=(10:17),REGEX=’A[0-9]{4}-[0-9]{2}’,ORDER=BYROW)

Cause ACIF to search columns ten through seventeen for a hexadecimal 41 followed by four numeric characters (hexadecimal 30-39), a hexadecimal 2D, and two numeric characters (hexadecimal 30-39). The match must begin in the first column specified by the OFFSET parameter.

Restriction: The REGEX parameter is not available on z/OS operating systems.

ORDER={BYROW|BYCOL}

Identifies where ACIF can locate the smallest value and the largest value of a group of sorted values arranged in either rows or columns on the page. The default ORDER is BYROW.

For ORDER=BYROW, ACIF extracts the first value in the first row and the last value in the last row that match the MASK. Data with a row orientation might appear as follows:

1 2 3
4 5 6
7 8

For ORDER=BYCOL, ACIF extracts the first value in the first column and the last value in the last column that match the MASK. Data with a column orientation might appear as follows:

1 4 7
2 5 8
3 6

Transaction field examples

FIELD4=*,*,10,(OFFSET=(3:12),MASK='##########',ORDER=BYROW)

The following field parameter causes ACIF to locate three digits followed by a dash, followed by four digits, that begin in column 59 of any record in the group. This format of the FIELD parameter is used to create indexes for the beginning and ending sorted values of each group.

FIELD3=*,*,12,(OFFSET=(59:70),ORDER=BYROW, REGEX='[0-9]{3}-[0-9]{4}')

Related parameters

• CPGID
• INDEX
• TRIGGER