WHEN directive

Use the WHEN directive when you want to include multiple record definitions or REDEFINES in the XFD. The WHEN directive typically is used to force certain columns of data to be available that wouldn't be available otherwise. (For information about REDEFINES, see the section REDEFINES Clause in the chapter Preparing your COBOL.)

Note: You cannot use the WHEN directive in an OCCURS clause. (For information about the OCCURS clause, see the section OCCURS Clause in the chapter Preparing Your COBOL.)

Recall that the key fields and the fields from the largest record are automatically included as explicit columns in the indexed file database table. So you should use the WHEN directive if you want the user to be able to access all the data in the COBOL file in a way that is understandable. (For details about how fields are included in the database table, see the section How XFDs are Formed in the chapter Preparing Your COBOL.

WHEN declares that the field (or subordinate fields, if it is a group item) that immediately follows the directive must appear as a column (or columns) in the indexed file database table. It also states one condition under which the columns are to be used. The WHEN directive thus guarantees that the fields will be explicitly included in the table (as long as they aren't FILLER and don't occupy the same area as key fields).

Syntax

$XFD WHEN field operator value

where

`field`	Specifies the name of a data item that corresponds to a field; if there is a NAME directive for this data item, the name used in the WHEN directive is the name given to the item by the NAME directive, not its COBOL name
`operator`	Specifies the relation between the field value and the alphanumeric literal that satisfies the condition; `operator` can be one of the following: `=` - The field value is equal to the literal value `!=` - The field value is not equal to the literal value `>` - The field value is greater than the literal value `<` - The field value is less than the literal value `>=` - The field value is greater than or equal to the literal value `< =` - The field value is less than or equal to the literal value
`value`	Is one of the following: An alphanumeric literal (if the field is alphanumeric) A numeric literal (if the field is numeric) The special word `other`; `other` is used only with the `=` operator: $XFD WHEN field = other `other` is true only when all other conditions for the same field are false; for example, if your FD contains the following lines of code: $XFD WHEN ATYPE = "C" $XFD WHEN ATYPE = "D" $XFD WHEN ATYPE = other the `other` condition holds true only if both `atype = 'c'` and `atype = 'd'` are false

Example

The following code is an example of using the WHEN directive.

       01  key-record.
      * employee-number is a key data item
           03  employee-number     pic 99999.
           03  emp-type            pic x.
      $xfd when emp-type="1"
      * record has this form when emp-type="1"
       01  data-record-1.
           03  filler              pic 99999.
           03  filler              pic x.
           03  name-1              pic x(35).
           03  pay-rate-1          pic 99.99.
      $xfd when emp-type="2"
      * record has this form when emp-type="2"
       01  data-record-2
           03  filler              pic 99999.
           03  filler              pic x.
           03  name-2              pic x(35).
           03  pay-rate-2          pic 999.99.
           03  subordinates        pic 999.
           03  position            pic x(50).

The effect of these directives is to force emp-type, name-1, and pay-rate-1 to correspond to columns, even though they are not in the largest record description. Therefore, the corresponding table has the following columns:

EMPLOYEE_NUMBER
EMP_TYPE
NAME_1
PAY_RATE_1
NAME_2
PAY_RATE_2
SUBORDINATES
POSITION

If each data item is subordinate to at most one WHEN directive, as in this example, the following occurs:

When the condition is true, the data item appears in the database table in the usual way
When the condition is false, the special value NULL appears in the corresponding column in the database table, and any value written into the column in the database table is not written to the COBOL data file. The exact meaning of a NULL value depends on the database. In some databases, NULL is a blank or zero value. In others, NULL is a special value on which no arithmetic or string operations can be performed, although a value can be tested to determine whether it is NULL

If a data item is subordinate to two or more WHEN directives, the following applies:

When all conditions are true, the data item appears in the database table in the usual way
When at least one condition is false, the special value NULL appears in the corresponding column in the database table, and any value written into the column in the database table is not written to the COBOL data file