WHEN Directive

The WHEN directive is used when you want to include multiple record definitions or REDEFINES in the XFD file. It’s typically used when you want to force certain database columns to be built that would not be built by default (because you want to use them from the RDBMS side). It can also force certain fields to be displayed in the alfred record editor.

Note: You cannot use the WHEN directive in an OCCURS clause.

Recall that the key fields and the fields from the largest record are automatically included as explicit fields in the XFD file. All fields are stored and retrieved, whether they appear as explicit fields or not. So you do not need to use WHEN unless you want to ensure that some additional fields are explicitly listed by name in the XFD.

WHEN declares that the field (or subordinate fields, if it is a group item) that immediately follows the directive must appear as a field (or fields) in the XFD. It also states one condition under which the fields are to be used. WHEN thus guarantees you that the fields will be explicitly included in the XFD (as long as they are not FILLER and do not occupy the same area as key fields).

A WHEN directive may also be assigned an optional tablename. If you assign a tablename, then the data that immediately follows the WHEN directive and meets the specified condition will be considered as a separate table.

Syntax

$XFD WHEN field=value [TABLENAME=name] (equals)
$XFD WHEN field=OTHER [TABLENAME=name] (equals)
$XFD WHEN field<=value [TABLENAME=name] (is less than or equal)
$XFD WHEN field<value [TABLENAME=name] (is less than)
$XFD WHEN field>=value [TABLENAME=name] (is greater than or equal)
$XFD WHEN field>value [TABLENAME=name] (is greater than)
$XFD WHEN field!=value [TABLENAME=name] (is not equal to)

*((XFD WHEN field=value [TABLENAME=name])) (also <, <=, >, >=, !=)

The value may be an explicit data value (in quotes). The word OTHER, which can be used only with “=”, means “use the field(s) that are subject to the WHEN OTHER condition only if none of the other WHEN conditions listed for this field is met.”

Note: Keep in mind the distinction between a field subject to a condition and a field in a WHEN condition (i.e., the field for which a condition is listed). A field subject to a WHEN condition is one that immediately follows the WHEN directive or is subordinate to a group item that immediately follows the WHEN directive. The field in a WHEN condition is the field before the arithmetic operator and is a part of the directive itself.

In other words, a WHEN OTHER condition is true if all other WHEN conditions with the same field in them are false. If a WHEN condition is false, the fields subject to it are not written.

For example:

 01 ar-code-type.
*(( xfd when ar-code-type = "s" ))
  03 ship-code-record pic x(4).
*(( xfd when ar-code-type = "b" ))
  03 backorder-code-record redefines
    ship-code-record.
*(( xfd when ar-code-type = other ))
  03 obsolete-code-record redefines
    ship-code-record.

OTHER may be used before one record definition, and may be used once at each nesting level within each record definition.

Note: A WHEN directive with condition OTHER must be used if there is a possibility that the data in the field will not meet any of the explicit equality conditions specified in the other WHEN directives; if this is not done, results are undefined.

Example1

If the following code were compiled without directives, the underlined fields would appear explicitly in the XFD file. Note that the key fields, and the fields from the longest record, would be included automatically. FILLER would be ignored:

01 ar-codes-record.
  03 ar-codes-key.
    05 ar-code-type    pic x.
    05 ar-code-num     pic 999.
01 ship-code-record.
  03 filler            pic x(4).
  03 ship-instruct     pic x(15).
01 terms-code-record. 
  03 filler            pic x(4).
  03 terms-rate-1      pic s9v999.
  03 terms-days-1      pic 9(3).
  03 terms-rate-2      pic s9v999.
  03 terms-descript    pic x(15).

If you added the WHEN directive as shown below, it would cause the fields from the SHIP-CODE-RECORD to be included in the XFD file, and would determine when specific fields would be used. The underlined fields would appear as columns in a database table if you were using Acu4GL:

 01 ar-codes-record.
   03 ar-codes-key.
     05 ar-code-type      pic x.
     05 ar-code-num       pic 999.
$xfd when ar-code-type = "s"
 01 ship-code-record.
   03 filler              pic x(4).
   03 ship-instruct       pic x(15).
$xfd when ar-code-type = "t"
 01 terms-code-record.
   03 filler              pic x(4).
   03 terms-rate-1        pic s9v999. 
   03 terms-days-1        pic 9(3) 
   03 terms-rate-2        pic s9v999.
   03 terms-descript      pic x(15).

FILLER data items do not have unique names and are thus not used to form field names in the XFD. You could use the NAME directive to give them a name if you really need to have them in the XFD. However, in this example the FILLER data items implicitly redefine key fields. Thus, they would be disregarded even if you provided a name for them.

Example 2

In the following code, in which no WHEN directives are used, the underlined fields will be explicitly named in the XFD. (Key fields have the suffix key in their names in this example.)

Note: REDEFINES records simply re-map the same data area and are not explicitly included in the XFD by default.

01 archive-record.
  03 filler               pic x(33).
  03 archive-code         pic 9(6).
  03 archive-location     pic 9(2).
  03 filler               pic x(10).
01 master-record.
  03 animal-id-key.
    05 patient-id         pic 9(6).
    05 species-code-type  pic 9(5).
    05 species-name       pic x(6).
  03 service-code-key.
    05 service-code-type  pic 9(6).
    05 service-name       pic x(10).
  03 billing-code.
    05 billing-code-type  pic 9(4).
    05 plan-name          pic x(8).
  03 office-info.
    05 date-in-office     pic 9(8).
    05 served-by-name     pic x(10).
  03 remote-info redefines office-info.
    05 van-id             pic 9(4).
    05 proc-code          pic 9(8).
    05 vet-name           pic x(6).

If you added the WHEN directives shown below, you would add several fields to the XFD. The fields that would appear are underlined:

*(( xfd when animal-id-key = "00000000000000000" ))
 01 archive-record.
   03 filler              pic x(33).
   03 archive-code        pic 9(6).
   03 archive-location    pic 9(2).
   03 filler              pic x(10).
*(( xfd when animal-id-key = other ))
 01 master-record.
*(( xfd use group ))
   03 animal-id-key.
     05 patient-id        pic 9(6).
     05 species-code-type pic 9(5).
     05 species-name      pic x(6).
   03 service-code-key.
     05 service-code-type pic 9(6).
     05 service-name      pic x(10).
   03 billing-code.
     05 billing-code-type pic 9(4).
     05 plan-name         pic x(8).
*(( xfd when billing-code-type = "1440" ))
   03 office-info.
     05 date-in-office    pic 9(8).
     05 served-by-name    pic x(10).
*(( xfd when billing-code-type = other ))
   03 remote-info redefines office-info. 
     05 van-id            pic 9(4).
     05 proc-code         pic 9(8). 
     05 vet-name          pic x(6).

Example 3

If your application has a REDEFINES whose field names are more meaningful than the fields they redefine, you might consider switching the order of your code, rather than using a WHEN directive. Use the less significant field names in the REDEFINES. For example, you might change this:

   03 code-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).
   03 patient-info redefines code-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).

to this:

   03 patient-info.
     05 patient-id    pic 9(4).
     05 service-code  pic 9(8).
     05 server-name   pic x(6).
   03 code-info redefines patient-info.
     05 filler        pic 9(8).
     05 code-1        pic x(10).

The fields that would appear in the XFD by default are underlined above. This shows how the XFD field names might become more meaningful when the order is reversed. Your application operates the same either way.

Note: When a WHEN directive condition is met, COBOL record definitions or REDEFINES records that are subordinate to other WHEN directives are not used. Database columns in rows which correspond to those records are set to the special database value “NULL”. This means that there is no value provided for those columns. “NULL” is not equivalent to zero, and it has special properties in the RDBMS. For example, you can select all rows for which a given column is NULL.

Example 4

This COBOL code:

 01 example4-record.
   03 col-type            pic x.
$xfd when col-type = "a"
   03 def1                pic x(2).
$xfd when col-type = "b"
   03 def2 redefines def1 pic 9(2).

will result in this database table:

col_type	def1	def2
a	xx	null
b	null	xx
a	yy	null