INCLUDE/OMIT Control Statement - mfx - 3.1

Syncsort™ MFX Programmers Guide
Product type
Software
Portfolio
Integrate
Product family
Syncsort™ Software
Product
Syncsort™ MFX > MFX
Version
3.1
Language
English
ContentType
Programmer’s Guide
Product name
Syncsort™ MFX
Title
Syncsort™ MFX Programmers Guide
Topic type
How Do I
Copyright
2024
First publish date
2010
ft:lastEdition
2024-08-27
ft:lastPublication
2024-08-27T08:14:56.318001

The INCLUDE/OMIT control statement selects records from an input file based on comparisons testing the contents of one or more fields within the record. A field can be compared to a constant or to another field within the record. Furthermore, a binary field may enter into comparisons that involve testing the individual bits in the field. Only one INCLUDE/OMIT control statement can be specified for an application, either as an INCLUDE or as an OMIT control statement.

Locale-Based Comparison Processing

MFX supports alternative sets of collating rules based on a specified national language. The alternative collating applies to INCLUDE/OMIT (and OUTFIL INCLUDE/OMIT) comparison processing as well as to SORT/MERGE processing. A locale defines single and multi-character collating rules for a cultural environment.

Locale-based INCLUDE/OMIT processing applies only to character (CH) fields and character or hexadecimal constants compared to character fields. When LOCALE is active, a CH to BI (or BI to CH) comparison is not allowed. The illegal comparison will cause MFX to terminate with an error message.

For more information on locale-based processing, see LOCALE.

INCLUDE/OMIT Control Statement Format

The format of the INCLUDE/OMIT control statement follows.
Figure 1. INCLUDE/OMIT Control Statement Format

COND Parameter (Required)

The COND parameter controls how records are included or omitted from an application. There are three forms of the COND parameter:
COND=ALL

All of the input records are to be included. This is the default.
COND=NONE None of the input records are to be included.
COND=comparison(s)
Specifies one or more comparisons that determine which records are to be included or omitted. Two types of comparisons are possible:

  • A standard comparison, between two record fields or between a record field and a constant. A binary input field also allows comparison by bit mask or bit pattern.

  • A substring comparison, which allows the search for a constant within a field, or for a field value within a constant, or for a pattern constant (wildcard) within a field. Use SS as the format to indicate a substring comparison.

The following several pages describe standard comparisons. For information on substring comparisons, see Substring Comparisons.

Each field specified in the COND parameter is identified by its position (p), length(l) and format (f). When processing variable-length records, by default all fields specified must be contained within the record. If an application is expected to reference fields not completely contained within the record, refer to VLTEST. VLTESTI provides for processing of records that do not contain all fields.
p

The position value indicates the first byte of the field relative to the beginning of the input record after E15 or E32 processing, if specified, has completed. The field must begin on a byte boundary. (Keep in mind that if a variable-length file is being referenced, the first 4 bytes must be reserved for the Record Descriptor Word.)
l

The length value indicates the length of the field. The length must be an integer number of bytes. See the table below for permissible field lengths by format.
f

The format value indicates the format of the field. The permissible formats for standard comparisons are indicated in the following table. If all data fields have the same format, the FORMAT=f subparameter can be specified instead of the individual f values. If both are specified, the individual f values will be used for fields where they are specified.
Table 1. Valid Formats and Lengths of Include/Omit Fields
Code Data Format

Acceptable Field Length (Bytes)
AC

EBCDIC characters are translated to their ASCII equivalents before merging.

 1 to 256
AQ

Character. Records are merged according to an alternate sequence specified either in the ALTSEQ control statement or as an installation default.

 1 to 256
ASF ASCII signed free format. Decimal digits (0-9) are extracted from right to left to form a positive or negative number value. A character of '–' or ')' found within the field will cause the value to be treated as a negative number. All other non-decimal digit values other than 0-9, '–' or ')' in the field are ignored. 1 to 44
ASL

Leading separate sign. An ASCII + or - precedes numeric field. One digit per byte.

 2 to 256
AST

Trailing separate sign. An ASCII + or - trails numeric field. One digit per byte.

 2 to 256
AUF ASCII Unsigned free format. Decimal digits (0-9) are extracted from right to left to form a positive number value. All non-decimal digit values in the field are ignored. Any combination of characters is valid, but characters other than 0-9 are ignored. 1 to 44
BI Binary. Unsigned. 1 to 256
CH Character. Unsigned. 1 to 256

CLO

OL

Leading overpunch sign. Hexadecimal F,C,E, or A in the first 4 bits of your field indicates a positive number. Hexadecimal D or B in the first 4 bits indicates a negative number. One digit per byte. CMP=CLC is forced.

 1 to 256

CSF

FS

Floating sign format. An optional leading sign may be specified immediately to the left of the digits. If the sign is a -, the number is treated as negative. For other characters, the number is treated as positive. Characters to the left of the sign are ignored.

 1 to 32*

CSL

LS

Leading separate sign. An EBCDIC + or - precedes numeric field. One digit per byte. CMP=CLC is forced.

 2 to 256

CST

TS

Trailing separate sign. An EBCDIC + or - follows numeric field. One digit per byte. CMP=CLC is forced.

 2 to 256

CTO

OT

Trailing overpunch in the first 4 bits of the rightmost byte gives the sign. Hexadecimal F,C,E, or A indicates a positive number. Hexadecimal D or B indicates a negative number. One digit per byte. CMP=CLC is forced.

 1 to 256
FI Fixed point. Signed. (Equivalent to Signed Binary.) 1 to 256
PD Packed decimal. Signed. 1 to 255
PD0

Packed decimal. 2-8-byte packed decimal data with the first digit and trailing sign ignored. The remaining bytes are treated as packed decimal digits. Typically PD0 is used with century window processing and Y2P format; Y2P processes the year, while PD0 processes month and day.

 2 to 8
SFF

Signed free format. Decimal digits (0-9) are extracted from right to left to form a number value. A character of – or ) found within the field will cause the value to be treated as a negative number. All other non-decimal digit values in the field are ignored. A maximum of 31 digits can be provided. When more than 31 digits are found in the field, the leftmost digits will be ignored.

 1 to 44
SS Substring format. 1 to 32752
UFF

Unsigned free format. Decimal digits (0-9) are extracted from right to left to form a positive number value. All non-decimal digit values in the field are ignored. A maximum of 31 digits can be provided. When more than 31 digits are found in the field, the leftmost digits will be ignored.

 1 to 44
UTF8 Unicode data format. Unicode data field contains UTFn characters, where n is 8, 16, or 32.
Note: A UTFn data field can only be compared with another UTFn data field of the same length. It cannot be compared to a constant or to another UTFm data field where m is different than n.

1 to 256

Unicode characters
UTF16
UTF32
Y2B

Binary. 2-digit, 1-byte binary year data treated as a 4-digit year by CENTWIN (century window) processing.

 1
Y2C

Character. 2-digit character year data treated as a 4-digit year by CENTWIN (century window) processing. Processing is identical to Y2Z fields.

 2
Y2D

Packed decimal. 2-digit, 1-byte packed decimal year data treated as a 4- digit year by CENTWIN (century window) processing.

 1
Y2P

Packed decimal. 2-digit, 2-byte packed decimal year data. Of the four packed digits contained in the 2 bytes, the first digit and trailing sign are ignored; the two inner digits are treated as a 4-digit year by CENTWIN processing.

 2
Y2S

Character or zoned decimal. 2-digit, 2-byte valid numeric data treated as a 4-digit year by CENTWIN (century window) processing, as for Y2C and Y2Z. However, certain data are not treated as year data. Data with binary zeros (X'00') or a blank (X'40') in the first byte will be collated before valid numeric year data for ascending order (after year data for descending order). Data with all binary ones (X'FF') in the first byte will be collated after valid numeric year data for ascending order (before year data for descending order). Zones are ignored, as for Y2C and Y2Z, except for data where the first byte begins with X'00', X'40' or X'FF'.

 2

Y2T

Y2U

Y2V

Y2W

Y2X

Y2Y

Full-date, character, binary, or packed decimal formats. Full-date data formats can be used to merge a variety of date fields. They can process dates ending or starting with year digits (x...xyy or yyx...x). They can also process non-date data commonly used with dates.

 2 to 6
Y2Z

Zoned decimal. 2-digit, 2-byte zoned decimal year data treated as a 4-digit year by CENTWIN (century window) processing. The zones are ignored. Processing is identical to Y2C fields.

 2
ZD

Zoned decimal. Trailing overpunch in the first 4 bits of the rightmost byte gives the sign. Hexadecimal F,C,E, or A indicates a positive number. Hexadecimal D or B indicates a negative number. One digit per byte. CTO forces CMP=CLC.

 1 to 256
Note: *1 to 256 when used with the NUM subparameter.

For information on the year data formats (Y2B, Y2C, Y2D, Y2P, Y2S and Y2Z) plus the related data format PD0, see CENTWIN Parameter (Optional) and Converting Year Data with Century Window Processing on INREC, OUTREC, or OUTFIL OUTREC. Also, see Specifying Field-to-Field Standard Comparisons for Year Fields.

The constant to which a field can be compared may be one of the following types:
decimal

A decimal constant can be any length. It should not be enclosed in single quotes. It may or may not include a leading + or - sign. For example, 100 is a valid decimal constant. The following numeric data compare as equal: +0, -0, 0. The &DATExP date parameter represents the current date as a decimal number (+n) to which a field can be compared. See Decimal fields for more details.
hexadecimal

A hexadecimal constant should be preceded by an X and specified in pairs of valid hexadecimal values which must be enclosed in single quotes: X'hh...hh'. For example, X'ACBF05' is a valid hexadecimal constant. The sign of the field is implicit in the representation.
character

A character constant should be preceded by a C and enclosed in single quotes: C'literal'. For example, C'SALES' is a valid character constant.

The &DATEx and &DATEx(c) date parameters represent the current date as a character string (C'string') to which a field can be compared. See Current Date Constant Specification for more details.

You can also include or omit records based on whether their dates fall within a specified time frame before or after the current date. See The forms of current date constants for more details.

To include an apostrophe in a character constant, specify it as two apostrophes; for example, C'D''AGOSTINO'. If a character constant must be continued on a second card image, place a continuation character in column 72 and then begin the continuation of the constant in column 16 of the next card image.
There are two methods in which the bit level characteristics of a binary input field can be used to include or omit records. One is to compare the binary field to a bit mask; the other is to compare the binary field to a bit pattern.
bit mask

A bit mask is a string of bits, specified in terms of either hexadecimal or binary digits. The bit mask indicates which bits in the input field are to be tested. Each bit in the mask whose value is 1 (ON) is tested against the corresponding bit in the input field. If the value of a mask bit is 0 (OFF), the corresponding bit in the input field is ignored.

The hexadecimal format of a bit mask is X'hh...hh,' where each 'hh' represents any pair of hexadecimal digits.

The binary format of a bit mask is B'bbbbbbbb...bbbbbbbb', where each 'bbbbbbbb' represents 8 bits or a byte. Each bit is 1 or 0. The number of bits in a binary bit mask must be a multiple of 8. The maximum length of a binary bit mask is 256 bytes (2048 bits).

A bit mask is truncated or padded on the right to the byte length of the binary field. The pad character is X'00' or B'00000000'.
bit pattern

The binary format of a bit pattern is B'bbbbbbbb...bbbbbbbb', where each 'bbbbbbbb' represents 8 bits or a byte. Each bit is 1, 0, or period (.). If the value of a bit in the bit pattern is 1 or 0, the corresponding bit in the binary input field is compared to 1 or 0. If a . (period) occurs in a bit position in the bit pattern, the corresponding bit in the input field is ignored.

The number of bit positions in a bit pattern must be a multiple of 8. The maximum length of a bit pattern is 256 bytes (2048 bits).

A bit pattern is truncated or padded rightward to the byte length of the binary input field. The pad character is B'00000000'.
The comparison operators represent the following conditions:
EQ Equal to
NE Not equal to
GT Greater than
GE Greater than or equal to
LT Less than
LE Less than or equal to
BO (or ALL) All mask bits are 1s (ON) in the input field
BM (SOME) Some but not all mask bits are 1s (ON) in the input field
BZ (NONE) None of the mask bits is 1 (ON) in the input field
BNO (NOTALL) Some or no mask bits are 1s (ON) in the input field
BNM (NOTSOME) All or no mask bits are 1s (ON) in the input field
BNZ (NOTNONE) All or some mask bits are 1s (ON) in the input field