The GROUP-USAGE Clause
A GROUP-USAGE clause with a NATIONAL phrase specifies that the group item defined by the subject of the entry is to be treated as an elementary item of usage national and category national, unless otherwise specified.
A GROUP-USAGE clause with a UTF-81 phrase specifies that the group item defined is a UTF-8 group item. The data items within the group and subordinate groups
are all UTF-8 items.
General Format
Syntax Rules
- The GROUP-USAGE clause may be specified only if the subject of the entry is a group item that is not strongly typed.
- When the BIT phrase is specified, USAGE BIT is implied for the subject of the entry. A USAGE clause shall not be specified
for the subject of the entry. All elementary items subordinate to the subject of the entry shall be explicitly or implicitly
described as usage bit, class and category boolean. All subordinate group items shall be explicitly or implicitly described
as GROUP-USAGE BIT.
The maximum number of characters allowed in the group is 64.
- When the NATIONAL phrase is specified, USAGE NATIONAL is implied for the subject of the entry. A USAGE clause shall not be specified for the subject of the entry. All elementary items subordinate to the subject of the entry shall be explicitly or implicitly described as usage national. Any signed numeric data items shall be described with the SIGN IS SEPARATE clause. All subordinate group items shall be explicitly or implicitly described as GROUP-USAGE NATIONAL.
- When the UTF-8 phrase is specified, USAGE UTF-8 is implied for the subject of the entry. A USAGE clause shall not be specified
for the subject of the entry. All elementary items subordinate to the subject of the entry shall be explicitly or implicitly
described as usage UTF-8 and must be defined with the BYTE-LENGTH clause.
General Rules
- When the BIT phrase is specified:
- The subject of the entry is a bit group and also a bit data item; its class and category are boolean.
- Unless stated otherwise, a bit group is treated as though it were an elementary data item of usage bit and class and category boolean described with PICTURE 1(m), where m is the bit length of the group.
- Data items contained within a bit group are allocated in storage in accordance with the rules specified in the topic Aligning Bit Data Items.
- When the NATIONAL phrase is specified:
- The subject of the entry is a national group; its class and category are national.
- Unless stated otherwise, a national group is treated as though it were an elementary data item of usage national and class
and category national described with PICTURE N(n), where
n is the length of the group.
Note: The GROUP-USAGE NATIONAL clause is needed so that groups containing only national characters can be properly truncated and padded with national characters and can be correctly processed for operations such as INSPECT. Without the GROUP-USAGE NATIONAL clause, the content of such a group item would be treated as category alphanumeric, possibly leading to corruption or invalid handling of data.
- When the UTF-8 phrase is specified:
- The subject of the entry is a UTF-8 group; its class and category are UTF-8.
- The GROUP-USAGE UTF-8 clause is implied for any subordinate groups that do not explicitly specify the GROUP-USAGE UTF-8 clause.
- The JUSTIFIED clause must not be specified.
- Unless stated otherwise, a UTF-8 group item is treated as though it were an elementary data item of USAGE UTF-8 and class and category UTF-8, and defined with PICTURE U BYTE-LENGTH n, where n is the length of the group, in bytes.
- If a GROUP-USAGE clause is not specified or implied for a group item that is not strongly typed, that group item is an alphanumeric
group item.
Any UTF-8 data items within those groups will be treated as alphanumeric, which could lead to invalid truncation or mishandling
of UTF-8 data. (For groups defined as GROUP-USAGE UTF-8, the Compiler is able to correctly handle truncation and padding of
group items during statements such as a MOVE.)