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.
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. This feature is designed for use with Version 1.1 of AcuODBCTM, the Vision ODBC driver, and is explained in more detail in the AcuODBC User's Guide for Version 1.1.
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 equals) $XFD WHEN field<value [TABLENAME=name] (is less than) $XFD WHEN field>=value [TABLENAME=name] (is greater than or equals) $XFD WHEN field>value [TABLENAME=name] (is greater than) $XFD WHEN field!=value [TABLENAME=name] (is not equal to)
or
*(( 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 following field(s) only if the WHEN condition(s) listed at the level of this field are not met."
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 level within each record definition.
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.)
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.
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
| 10
|
| a
| yy
| null |