GROUP-USAGE clause

A GROUP-USAGE clause with the NATIONAL phrase specifies that the group item defined by the entry is a national group item. A national group item contains national characters in all subordinate data items and subordinate group items. A GROUP-USAGE clause with the UTF-8 phrase specifies that the group item defined by the entry is a UTF-8 group item. A UTF-8 group item contains UTF-8 characters in all subordinate data items and subordinate group items.

Format

Read syntax diagramSkip visual syntax diagramGROUP-USAGEIS NATIONALUTF-8
When GROUP-USAGE NATIONAL is specified:
  • The subject of the entry is a national group item. The class and category of a national group are national.
  • A USAGE clause must not be specified for the subject of the entry. A USAGE NATIONAL clause is implied.
  • A USAGE NATIONAL clause is implied for any subordinate elementary data items that are not described with a USAGE NATIONAL clause.
  • All subordinate elementary data items must be explicitly or implicitly described with USAGE NATIONAL.
  • Any signed numeric data items must be described with the SIGN IS SEPARATE clause.
  • A GROUP-USAGE NATIONAL clause is implied for any subordinate group items that are not described with a GROUP-USAGE NATIONAL clause.
  • All subordinate group items must be explicitly or implicitly described with a GROUP-USAGE NATIONAL clause.
  • The JUSTIFIED clause must not be specified.

Unless stated otherwise, a national group item is processed as though it were an elementary data item of usage national, class and category national, described with PICTURE N(m), where m is the length of the group in national character positions.

Usage note: When you use national groups, the compiler can ensure proper truncation and padding of group items for statements such as MOVE and INSPECT. Groups defined without a GROUP-USAGE NATIONAL clause are alphanumeric groups. The content of alphanumeric groups, including any national characters, is treated as alphanumeric data, possibly leading to invalid truncation or mishandling of national character data.

The table below summarizes the cases where a national and UTF-8 group items are processed as a group item.

When GROUP-USAGE UTF-8 is specified:
  • The subject of the entry is a UTF-8 group item. The class and category of a UTF-8 group are UTF-8.
  • A USAGE clause must not be specified for the subject of the entry. A USAGE UTF-8 clause is implied.
  • A USAGE UTF-8 clause is implied for any subordinate elementary data items that are not described with a USAGE UTF-8 clause.
  • All subordinate elementary data items must be explicitly or implicitly described with USAGE UTF-8 and must be defined with either the BYTE-LENGTH phrase of the PICTURE clause or the DYNAMIC LENGTH clause.
  • A GROUP-USAGE UTF-8 clause is implied for any subordinate group items that are not described with a GROUP-USAGE UTF-8 clause.
  • All subordinate group items must be explicitly or implicitly described with a GROUP-USAGE UTF-8 clause.
  • The JUSTIFIED clause must not be specified.

Unless stated otherwise, a UTF-8 group item is processed as though it were an elementary data item of usage UTF-8, class and category UTF-8, and defined with PICTURE U BYTE-LENGTH m, where m is the length of the group in bytes.

Usage note: When you use UTF-8 groups, the compiler can ensure proper truncation and padding of group items for statements such as MOVE. Groups defined without a GROUP-USAGE UTF-8 or GROUP-USAGE NATIONAL clause are alphanumeric groups. The content of alphanumeric groups, including any UTF-8 characters, is treated as alphanumeric data, possibly leading to invalid truncation or mishandling of UTF-8 character data.

The table below summarizes the cases where a national and UTF-8 group items are processed as a group item.

Table 1. Where national and UTF-8 group items are processed as groups
Language feature Processing of national group items
Name qualification The names of national and UTF-8 group items can be used to qualify the names of elementary data items and subordinate group items in national and UTF-8 groups. The rules of qualification for national and UTF-8 groups are the same as the rules of qualification for an alphanumeric group.
RENAMES clause The rules for national and UTF-8 group items specified in the THROUGH phrase are the same as the rules for an alphanumeric group item specified in the THROUGH phrase. The result is an alphanumeric group item.
CORRESPONDING phrase National and UTF-8 group items are processed as a group in accordance with the rules of the CORRESPONDING phrase. Elementary data items within a national or UTF-8 group are processed the same as they would be if defined within an alphanumeric group.
INITIALIZE statement National and UTF-8 group items are processed as a group in accordance with the rules of the INITIALIZE statement. Elementary items within the national or UTF-8 group are initialized the same as they would be if defined within an alphanumeric group.
XML GENERATE statement A national group item specified in the FROM phrase is processed as a group in accordance with the rules of the XML GENERATE statement. Elementary items within the national group are processed the same as they would be if defined within an alphanumeric group.
JSON GENERATE statement A national group item specified in the FROM phrase is processed as a group in accordance with the rules of the JSON GENERATE statement. Elementary items within the national group are processed the same as they would be if defined within an alphanumeric group.