FORMAT INCLUDE

Load Format from Data Dictionary into Memory

This directive loads the format attributes from the data dictionary into memory, and then initializes the format’s data area.

Syntax

FORMAT INCLUDE format-name [, OPT=option-str ]
[,ERR=line-ref|,ERC=error-code]

FORMAT INCLUDE format-name [, OPT=”ALIAS=alias-name” ]
[,ERR=line-ref|,ERC=error-code]

format-name: is the name of a format defined in the data dictionary.
option-str: is either the initialization mode to perform on the format's data area, "INIT", "DEFAULT", or "NONE", or a special include mode to perform on the format, "DESC_TBL" OR "ALIAS=alias-name". If no option is specified, the data area is initialized.
line-ref: is the program line number or label to branch to if an error is produced.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.
alias-name: is the name of the format alias to be created.

Remarks

The information is loaded into memory from the data dictionary as follows:

the fixed attribute table
the variable-sized attribute table, if one exists
the data element name table
a data description table (see below for more information).

A format remains in memory until it is removed with the FORMAT DELETE directive.

An attempt to INCLUDE a format that does not exist in the data dictionary results in an ERR=161.

An attempt to INCLUDE a format without a data dictionary results in an ERR=168.

An attempt to specify an option-str other than “INIT”, “DEFAULT”, “NONE”, or “DESC_TBL” results in an ERR=17.

An attempt to INCLUDE a format when the format structure table is already full results in an ERR=37.

An attempt to INCLUDE a format that has not already been INCLUDEd with an OPT=“NONE” option will INCLUDE the format and ignore the OPT=“NONE” option, thus initializing the format’s data area.

Starting with release 8.3.0, the fixed attributes (i.e., length, precision, numeric type, date type, etc.) of all the data elements for a format not already loaded into memory are validated. If a format is found to contain a corrupt data element, one with an invalid combination of fixed attributes, the format will not be INCLUDEd, the DNE system variable will be set to the corrupt data element, and the INCLUDE will result in an ERR=169.

Starting with release 8.3.0, a data description table for a format is loaded based on the current language code as defined in Thoroughbred Dictionary-IV. If a data description table does not exist for a format in the current language, a data description table in one of the other 11 language codes will be loaded starting with the first language code (English). If the current language code cannot be determined, the data description table loading will not be attempted.

OPT=“DESC_TBL” will reload only the data description table for a format.

An attempt to INCLUDE a format that has not already been INCLUDEd with an OPT=“DESC_TBL” option will ignore the OPT=“DESC_TBL” option and INCLUDE the format.

Starting with release 8.5.0, a format alias, second image of a format, can be created by using the “ALIAS=” OPTion. The scope of a format alias is global, however hard coded references to a format alias can only be used in the program where the alias was created. To reference a format alias outside of the program where it was defined, variables must be used.

A format alias remains in memory until it is removed with the FORMAT DELETE directive.

An attempt to create a format alias from a format that has not been INCLUDEd results in an ERR=162.

An attempt to create a format alias from another format alias results in an ERR=175.

An attempt to create a #format alias from a %format or create a %format alias from a #format results in an ERR=176.

An attempt to create a format alias that has already been created results in an ERR=177.

An attempt to create a format alias that exists in the data dictionary results in an ERR=178.

Examples

FORMAT INCLUDE #DNFFMT

loads the format, named “DNFFMT”, from the data dictionary into memory and initializes the data area.

FORMAT INCLUDE #DNFFMT, OPT="INIT", ERR=7000

has the same result as the previous example, except that if an error occurs, statement 7000 is executed.

FORMAT INCLUDE #DNFFMT, OPT="DEFAULT", ERR=7000

loads the format, named “DNFFMT”, from the data dictionary into memory, initializes and then loads any existing defaults from the variable attribute table into the data area. If an error occurs, statement 7000 is executed.

FORMAT INCLUDE #DNFFMT;
CLEAR ERC;
FORMAT DELETE #DNAFMT,ERC=86;
FORMAT INCLUDE #DNFFMT, OPT=”ALIAS=#DNAFMT”, ERR=7000

loads the format named “DNFFMT”, deletes the format alias named “DNAFMT” and then creates the format alias “DNAFMT” from the format named “DNFFMT”. If an error occurs, statement 7000 is executed.

FORMAT INCLUDE

Syntax

Remarks

Examples

See also