INCLUDE control statement


>>-INCLUDE--COND=--+-(logical expression)-+----------+-+-------><
                   |                      '-FORMAT=f-' |   
                   +-ALL-------------------------------+   
                   '-NONE------------------------------'

Use an INCLUDE statement if you want only certain records to appear in the output data set. The INCLUDE statement selects the records you want to include.

You can specify either an INCLUDE statement or an OMIT statement in the same DFSORT run, but not both.

The way in which DFSORT processes short INCLUDE/OMIT compare fields depends on the settings for VLSCMP/NOVLSCMP and VLSHRT/NOVLSHRT. A short field is one where the variable-length record is too short to contain the entire field, that is, the field extends beyond the record. For details about including or omitting short records, see the discussion of the VLSCMP and NOVLSCMP options in OPTION control statement.

A logical expression is one or more relational conditions logically combined, based on fields in the input record, and can be represented at a high level as follows:


>>-relational condition1---------------------------------------->

>--+----------------------------------------+------------------><
   | .-.----------------------------------. |   
   | V                                    | |   
   '---,--+-AND-+--,relational condition2-+-'   
          '-OR--'

If the logical expression is true for a given record, the record is included in the output data set.

Five types of relational conditions can be used as follows:

Comparisons:
Compare two compare fields or a compare field and a decimal, hexadecimal, character, or current, future, or past date constant.

For example, you can compare the first 6 bytes of each record with its last 6 bytes, and include only those records in which those fields are identical. Or you can compare a date field with today's date, yesterday's date, or tomorrow's date, and include records accordingly.

See Comparisons for information about comparisons.
Substring Comparison Tests:
Search for a constant within a field value or a field value within a constant.

For example, you can search the value in a 6-byte field for the character constant C'OK', and include only those records for which C'OK' is found somewhere in the field. Or you can search the character constant C'J69,L92,J82' for the value in a 3-byte field, and include only those records for which C'J69', C'L92', or C'J82' appears in the field.

See Substring comparison tests for information about substring comparison tests.
Bit Logic Tests:
Test the state (on or off) of selected bits in a binary field using a bit or hexadecimal mask or a bit constant.

For example, you can include only those records which have bits 0 and 2 on in a 1-byte field. Or you can include only those records which have bits 3 and 12 on and bits 6 and 8 off in a 2-byte field.

See Bit logic tests for information about bit logic tests.
Date Comparisons:
Compare a two-digit year date field to a two-digit year date constant, a current, future or past two-digit year date, or to another two-digit year date field, using the century window in effect.

For example, you can include only those records for which a Z'yymm' date field is between January 1996 and March 2005. Or you can include only those records for which a P'dddyy' field is less than another P'dddyy' field. Or you can include only those records for which a C'yyddd' field is between today's date and 5 days earlier than today's date.

See Date comparisons for information about date comparisons.
Numeric Tests:
Test a field for numerics or non-numerics in character, zoned decimal or packed decimal format.

For example, you can include only those records in which a 5-byte field contains only '0'-'9' characters (that is, numerics). Or you can include only those records in which a 9-byte field contains invalid ZD numeric data (that is, non-numerics). Or you can include only those records in which a 12-byte field contains valid PD numeric data (that is, numerics).

See Numeric tests for information about numeric tests.
Alphanumeric Tests:
Test a field for alphanumerics or non-alphanumerics in character format. Various combinations of uppercase characters (A-Z), lowercase characters (a-z) and numeric characters (0-9) can be used.

For example, you can include only those records in which a 10-byte field contains only 'A'-'Z' characters (that is, uppercase characters) or '0'-'9' characters (that is, numeric characters). Or you can include only those records in which a 20-byte field contains characters other than 'a'-'z' (that is, lowercase characters).

See Alphanumeric tests for information about aphanumeric tests.

By nesting relational conditions within parentheses, you can create logical expressions of higher complexity.

Although comparisons, substring comparison tests, bit logic tests, date comparisons, numeric tests, and alphanumeric tests are explained separately later in this section for clarity, they can be combined to form logical expressions.

The INCLUDE control statement differs from the INCLUDE parameter of the OUTFIL statement in the following ways:

The INCLUDE statement applies to all input records; the INCLUDE parameter applies only to the OUTFIL input records for its OUTFIL group.
FORMAT=f can be specified with the INCLUDE statement but not with the INCLUDE parameter. Thus, you can use FORMAT=f and p,m or p,m,f fields with the INCLUDE statement, but you must only use p,m,f fields with the INCLUDE parameter. For example:
```
  INCLUDE FORMAT=BI,
     COND=(5,4,LT,11,4,OR,21,4,EQ,31,4,OR,
        61,20,SS,EQ,C'FLY')

  OUTFIL INCLUDE=(5,4,BI,LT,11,4,BI,OR,21,4,BI,EQ,31,4,BI,OR,
        61,20,SS,EQ,C'FLY')
```
D2 format can be specified with the INCLUDE statement but not with the INCLUDE parameter.

See OUTFIL control statements for more details on the OUTFIL INCLUDE parameter.

COND


>>-COND=--+-(logical expression)-+-----------------------------><
          +-ALL------------------+   
          '-NONE-----------------'

logical expression: specifies one or more relational conditions logically combined, based on fields in the input record. If the logical expression is true for a given record, the record is included in the output data sets.
ALL: specifies that all of the input records are to be included in the output data sets.
NONE: specifies that none of the input records are to be included in the output data sets.

Default: ALL. See Specification/override of DFSORT options for full override details.

Applicable Functions: See Specification/override of DFSORT options.

FORMAT


>>-FORMAT=f----------------------------------------------------><

FORMAT=f can be used to specify a particular format for one or more compare fields. f from FORMAT=f is used for p,m fields. f from FORMAT=f is ignored for p,m,f fields. For example, the following are all equivalent:

  INCLUDE COND=(5,5,ZD,EQ,12,3,PD,OR,21,3,PD,NE,35,5,ZD)
  INCLUDE FORMAT=ZD,COND=(5,5,EQ,12,3,PD,OR,21,3,PD,NE,35,5)
  INCLUDE COND=(5,5,ZD,EQ,12,3,OR,21,3,NE,35,5,ZD),FORMAT=PD

The permissible field formats for comparisons are shown in Table 1. SS (substring) is the only permissible field format for substring comparison tests. BI (unsigned binary) is the only permissible field format for bit logic tests. The Y2x formats are the only permissible field formats for date comparisons. The FS or CSF (floating sign), ZD (zoned decimal), and PD (packed decimal) formats are the only permissible field formats for numeric tests. BI (unsigned binary) is the only permissible format for alphanumeric tests.

Default: None. FORMAT=f must be specified if any field is specified as p,m rather than p,m,f. See Specification/override of DFSORT options for full override details.

Applicable Functions: See Specification/override of DFSORT options.

Note: DFSORT issues an informational message and ignores FORMAT=f if all of the fields are specified as p,m,f.