DEFINED and POSITION attributes

The DEFINED attribute specifies that the declared variable is associated with some or all of the storage associated with the designated base variable.

The UNION attribute allows you to achieve the same end in a much cleaner manner and also allows variables with different attributes and precisions to be overlaid. Also, while the DEFINED attribute guarantees that access through defined or base variables is reflected in all defined variables, in a union only one member of the union is valid at any given time. For syntax information for the UNION attribute, see UNION attribute.

Read syntax diagramSkip visual syntax diagramDEFINEDreference( reference)POSITION( expression)

Abbreviations: DEF for DEFINED, POS for POSITION

reference
To the variable (the base variable) whose storage is associated with the declared variable; the latter is the defined variable. The base variable can be EXTERNAL or INTERNAL. It can be a parameter (in string overlay defining, the parameter must refer to connected storage). It cannot be BASED or DEFINED. A change to the base variable's value is a corresponding change to the value of the defined variable, and vice versa.

If the base variable is a data aggregate, a defined variable can comprise all the data or only a specified part of it.

The defined variable does not inherit any attributes from the base variable. The defined variable must be INTERNAL and a level-1 identifier. It can have the dimension attribute. It cannot be INITIAL, AUTOMATIC, BASED, CONTROLLED, STATIC, or a parameter.

There are three types of defining: simple, iSUB, and string overlay.

The type of defining in effect is determined as follows:

  1. If the POSITION attribute is specified, string overlay defining is in effect.
  2. If the subscripts specified in the base variable contain references to iSUB variables, iSUB defining is in effect.
  3. If neither an iSUB variable nor the POSITION attribute is present and if the base variable and defined variable match according to the criteria given below, simple defining is in effect.
  4. Otherwise, string overlay defining is in effect.

If the POSITION attribute is specified, the base variable must not contain iSUB references.

A base variable and a defined variable match if the base variable when passed as an argument matches a parameter that has the attributes of the defined variable (except for the DEFINED attribute). For this purpose, the parameter is assumed to have all array bounds, string lengths, and area sizes specified by asterisks.

For simple defining and iSUB defining, a PICTURE attribute can only be matched by a PICTURE attribute that is identical except for repetition factors. For a reference to specify a valid base variable in string overlay defining, the reference must be in connected storage. You can override the matching rule completely, but this can cause unwanted side effects within your program.

The values specified or derived for any array bounds, string lengths, or area sizes in a defined variable do not always have to match those of the base variable. However, the defined variable must be able to fit into the corresponding base array, string, or area.

In references to defined data, the STRINGRANGE, SUBSCRIPTRANGE, and STRINGSIZE conditions are raised for the array bounds and string lengths of the defined variable, not the base variable.

The determination of values and the interpretation of names occurs in the following sequence:

  1. The array bounds, string lengths, and area sizes of a defined variable are evaluated on entry to the block that declares the variable.
  2. A reference to a defined variable is a reference to the current generation of the base variable. When a defined variable is passed as an argument without creation of a dummy, the corresponding parameter refers to the generation of the base variable that is current when the argument is passed. This remains true even if the base variable is reallocated within the invoked procedure.
  3. When a reference is made to the defined variable, the order of evaluation of the subscripts of the base and defined variable is undefined.

If the defined variable is a structure or union containing any elements that are unaligned nonvarying BIT, all array bounds and string lengths in the defined variable must be specified as constants.

If the defined variable has the BIT attribute, unpredictable results can occur under the following conditions:
  • The base variable is not on a byte boundary.
  • The defined variable is not defined on the first position of the base variable, and the defined variable is used as follows:
    • A parameter in a subroutine call (that is, referenced as internally stored data)
    • An argument in a PUT statement
    • An argument in a built-in function (library call)
    • If the base variable is controlled, and the defined variable is dimensioned and is declared with variable array bounds.
  • If the defined variable consists entirely of unaligned nonvarying bit strings, the array bounds, string lengths, and area sizes of the defined variable must be known at compile time.