Remap Group Item

Each group item that is included from the data set is identified using a remap group item. Group items can appear exactly as they do in the data set, can be redescribed with one or more changes, or can be omitted altogether.

When only the name of the group is designated in the remap, the group appears in the remap exactly as it does in the data set.

Group items can be redescribed when they are included in the remap. The reserved word GROUP is optional. Changes can be made as follows:

The name and contents of the group can be changed.
The options that apply to the entire group can be changed.
When the content of the group is changed, the entire group must be redescribed and the following changes can be made:
The order of the items in the group can be changed.
Virtual data items and virtual group items can be added.
Items that are outside of the group must not be moved inside the group.
The order of the items in the group can be changed.
A group item can be omitted from the remap without omitting the elementary items of that group.
Items that are in a certain group in the physical data set can be moved out of it in the remap, even though the group can be included in the remap.
Items can be deleted from the group in two ways: they can be declared hidden, or they can be omitted when the group is redescribed. In either event, the item cannot be accessed by the user, and it is not present in the user work area.
Existing items within the group can be given new names and attributes. When the attributes of an item are changed, the item must be completely redescribed.
Virtual data items and virtual group items can be added to the group. When the OCCURS option is specified for the group, virtual items in the group must not be assigned a value.
When group options are changed, the entire group must be redescribed. Groups can be made hidden, read only, or required in the remap. All other options must remain the same.

The following diagrams illustrate the syntax for a remap group item:

<remap group item>

──┬──────────────────┬─<group item name>─┬───────────┬─────────────────►
  └─ <identifier> = ─┘                   └─<comment>─┘

►─┬────────────────────────────┬───────────────────────────────────────┤
  └─<group item redescription>─┘

<group item redescription>

            ┌◄─────────── ; ───────────┐
── GROUP ( ─┴─┬─<remap data item>────┬─┴─┬─────┬─ ) ───────────────────►
              ├─<remap group item>───┤   └─ ; ─┘
              ├─<virtual data item>──┤
              ├─<virtual group item>─┤
              └─<remap regrouping>───┘

►─┬───────────────────────────────────────────────┬────────────────────┤
  │ ┌◄──────────────────── , ───────────────────┐ │
  └─┴─┬─/1\─┬─<occurs clause>─────────────────┬─┴─┘
      │     ├─ REQUIRED ──────────────────────┤
      │     └─<stored clause>─────────────────┤
      └─/1\─┬─ HIDDEN ────────────────────────┤
            └─ READONLY ─┬────────────────────┤
                         ├─ GIVING EXCEPTION ─┤
                         └─ NO EXCEPTION ─────┘

The following table explains the elements of the syntax diagram:

Option	Description
<group item name>	A group item name is an identifier that names the group. The name of a group item is changed by using the <identifier> = option. The new name cannot exceed 30 characters. Only the name of the group is changed. All other attributes remain the same.
REQUIRED	Specifying REQUIRED for the group is equivalent to specifying REQUIRED for each item in the group for which the option is valid. Groups which are not required in the data set can be required in the remap. This causes the system to ensure the items in the group are nonnull when a record is stored using the remap, but not when it is stored using the data set. Groups which are required in the data set are checked, whether the record is stored using the data set or the remap.
HIDDEN	The HIDDEN option makes the group item and the items within it inaccessible and eliminates them from the user work area. This same effect can be achieved by simply leaving the group out of the remap altogether, but the HIDDEN option has the following advantages: It documents the omission. It permits initial values to be assigned to items within the group. This is especially valuable if items are required and a user program is adding new records using the remap. It allows the items to be referenced in SELECT and VERIFY conditions.
READONLY	The READONLY option indicates that the value of the items in the group can be accessed but not altered. The message “Mutually exclusive options requested” is given when an occurring remap item is declared as read only. When READONLY or READONLY GIVING EXCEPTION is specified, a DATAERROR exception occurs at store time if a program attempts to change the value of the item. If READONLY NO EXCEPTION is stipulated, no exception is returned but the store operation is prevented. A create and store operation always stores the initial or null value for a read-only item. A lock and store operation always causes the item to retain its previous value. When READONLY is specified for individual items within the record, READONLY ALL must not be specified for the entire record.

Remap Group Items Examples

The following 11 examples illustrate the DASDL syntax for remap group items.

Example 1

Records R1 and R2 both remap items A and G. However, record R2 maps item G to item H. Record R3 remaps data set D and adds virtual item V to the remap.

D DATA SET
 (
  A ALPHA(8);
  G GROUP
   (
    W ALPHA(2);
    X BOOLEAN OCCURS 10 TIMES;
    Y NUMBER(S5,2) INITIALVALUE 0;
    Z REAL;
  );
 );
R1 REMAPS D
 (
  A;
  G;
 );
R2 REMAPS D
 (
  A;
  H = G;
 );
R3 REMAPS D
 (
  A;
  G GROUP
   (
    W ALPHA(2) INITIALVALUE BLANKS, REQUIRED;
    Y NUMBER(S5,2) INITIALVALUE 1, HIDDEN;
    B = X;
    V VIRTUAL NUMBER(S6,2) = Y*2;
    Z REAL READONLY;
   );
 );

Example 2

Records R and D are identical.

D DATA SET
 (
  A ALPHA(2);
  G GROUP
   (
    H GROUP
     (
      W BOOLEAN;
      X NUMBER(5);
     );
    Q REAL;
   );
 );
R REMAPS D
 (
  A;
  G;
 );

Example 3

Record R contains four items: data items A, I, and J, and group item H.

D DATA SET
 (
  A ALPHA(10);
  G GROUP
   (
    I REAL;
    J BOOLEAN INITIALVALUE FALSE;
   );
 );
R REMAPS D
 (
  A;
  H = G;
 );

Example 4

In the remap the order of the items in the group has been changed.

D DATA SET
 (
  X NUMBER(3);
  Y BOOLEAN;
  Z REAL;
 );
R REMAPS D
 (
  Z;
  Y;
  X;
 );

Example 5

The elementary items STREET, CITY, ZIP, PHONE, CONTRACT-NO, and LIAISON are accessible through the remap CUSTOMER even though the groups which contain them in the data set, BILLING-ADDR, and CUST-INFO, are omitted from the remap.

CUST DATA SET
(NAME                    ALPHA(20);
 BILLING-ADDR            GROUP
    (STREET              ALPHA(20);
     CITY                ALPHA(15);
     ZIP                 NUMBER(9);
    );
 CUST-INFO               GROUP
    (CONTRACT-NO         NUMBER(9);
     LIAISON             ALPHA(20);
     PHONE               ALPHA(10);
    );
);
CUSTOMER REMAPS CUST
(NAME                    ALPHA(20);
 STREET                  ALPHA(20);
 CITY                    ALPHA(15);
 ZIP                     NUMBER(9);
 PHONE                   ALPHA(10);
 CONTRACT-NO             NUMBER(9);
 LIAISON                 ALPHA(20);
);

Example 6

Although CUST-INFO contains PHONE in the data set, it does not contain it in the remap.

CUST DATA SET
(NAME                         ALPHA(20);
 BILLING-ADDR                 GROUP
    (STREET                   ALPHA(20);
     CITY                     ALPHA(15);
     ZIP                      NUMBER(9);
    );
 CUST-INFO                    GROUP
    (CONTRACT-NO              NUMBER(9);
     LIAISON                  ALPHA(20);
     PHONE                    ALPHA(10);
    );
);
CUSTOMER REMAPS CUST
(NAME                         ALPHA(20);
 BILLING-ADDR                 GROUP
    (STREET                   ALPHA(20);
     CITY                     ALPHA(15);
     ZIP                      NUMBER(9);
    );
 PHONE                        ALPHA(10);
 CUST-INFO                    GROUP
    (CONTRACT-NO              NUMBER(9);
     LIAISON                  ALPHA(20);
    );
);

Example 7

Items I and L are included in the remap, while items J and K are omitted.

D DATA SET
 (
  A ALPHA(10);
  G GROUP
   (
    I BOOLEAN INITIALVALUE TRUE;
    J NUMBER(S7,1) OCCURS 10 TIMES;
    K FIELD(10);
    L REAL NULL LOW-VALUE;
   );
 );
R REMAPS D
 (
  A;
  G GROUP
   (
    I;
    K FIELD(10) HIDDEN;
    L REAL NULL LOW-VALUE;
   );
  );

Example 8

Record R remaps all of data set D except item W.

D DATA SET
 (
  N NUMBER(2);
  G GROUP
   (
    A ALPHA(4) INITIALVALUE BLANKS;
    F FIELD
     (
      F1 BOOLEAN;
      F2 BOOLEAN;
     );
    S REAL OCCURS 10 TIMES;
    P NUMBER(6);
    W FIELD(6);
   );
 );
R REMAPS D
 (
  N;
  G GROUP
   (
    A ALPHA(4) INITIALVALUE LOW-VALUE;
    C = F;
    S REAL OCCURS 10 TIMES, HIDDEN;
    P NUMBER(6) READONLY;
   );
 );

Example 9

Record R remaps all of data set D, and adds a virtual item and a virtual group to group G.

D DATA SET
 (
  C REAL;
  G GROUP
   (
    X NUMBER(3);
    Y NUMBER(3);
    Z FIELD(10);
   );
 );
R REMAPS D
 (
 (
  C;
  G GROUP
    V VIRTUAL NUMBER(4,1) = (X + Y)/2;
    W VIRTUAL GROUP
     (
      M ALPHA(3) = "ABC";
      N NUMBER(2) = 2;
     );
    X;
    Y;
    Z;
   );
 );

Example 10

Record R remaps all of data set D and adds read only and required attributes to item G.

D DATA SET
 (
  A ALPHA(1);
  G GROUP
   (
    X REAL NULL IS 0, INITIALVALUE IS 1;
    Y NUMBER(4);
   );
 );
R REMAPS D
 (
  A;
  G GROUP
   (
    X;
    Y;
   ) READONLY,REQUIRED;
 );

Example 11

Only item A is present in the remap. Items G, M, and N are not accessible.

D DATA SET
 (
  A ALPHA(1);
  G GROUP
   (
    M FIELD(7);
    N REAL OCCURS 10 TIMES;
   );
 );
R REMAPS D
 (
  A;
 );

Restrictions on Remap Group Items

Special restrictions apply to groups which are keys. They can be included in the remap without change, can be included with a new name, can be redescribed with item options changed, or can be omitted altogether. However, if the group is redescribed, the items must remain in the original sequence, no new items can be added to the group, and no existing items can be omitted from the group.

When the group is omitted from the remap, it is not available to user programs and it is not present in the user work area.

The following restrictions apply to the changes that can be made to the group structure of a remap:

No changes can be made to an item that is stored conditionally (OCCURS DEPENDING, STORED DEPENDING, and so forth) if such changes would obscure the fact that it is stored conditionally. Therefore, items that are members of an OCCURS DEPENDING or STORED DEPENDING group must remain members of that group in the remap.
If a given item is not in a particular group in a data set, then it cannot be in a remap group item of that group in a remap.
Items that have been taken out of a group or moved in a new group in the remap must be completely redescribed.
Items that are members of group keys or group key data can only appear in a remap if they are members of a remap group item of the original group that owns them in the data set.

Subscript Changes

A multiple subscripted item can be remapped to an item that has only one subscript. This capability is necessary to access databases that have multiple subscripted items from an RPG program.

Example

In this example, N-SINGLE, which occurs 27 times, remaps item N, which is a multiple subscripted item:

D DATA SET
(G1 GROUP
   (G2 GROUP
      (N NUMBER(2) OCCURS 3 TIMES;
      )OCCURS 3 TIMES;
   )OCCURS 3 TIMES;
 N1 NUMBER(2);
);
R REMAPS D
(N-SINGLE = N NUMBER(2) OCCURS 27 TIMES;
);

When remapping a multiple subscripted item to an item with only one subscript, the Enterprise Database Server maps each occurrence of the item in the physical data set onto an occurrence of the remap item one at a time. This is done by varying the subscripts from one to their respective limits, with the rightmost subscript varying first. The following table illustrates this mapping using the DASDL description in the preceding example:

Physical Data Item	Remap Data Item
N(1,1,1)	N-SINGLE(1)
N(1,1,2)	N-SINGLE(2)
N(1,1,3)	N-SINGLE(3)
N(1,2,1)	N-SINGLE(4)
N(1,2,2)	N-SINGLE(5)
N(1,2,3)	N-SINGLE(6)
.	.
.	.
.	.
N(3,2,3)	N-SINGLE(24)
N(3,3,1)	N-SINGLE(25)
N(3,3,2)	N-SINGLE(26)
N(3,3,3)	N-SINGLE(27)

If the total number of occurrences of an item is N less in the remap than it is in the data set, then the last N occurrences of the item are not accessible through the remap. In the preceding example, if N-SINGLE were declared to have only 25 occurrences, then N(3,3,2) and N(3,3,3) would not be accessible through the remap.

Restrictions on Subscripts

The following restrictions apply to the changes that can be made to subscripted items:

The number of subscripts of a remap item either must be equal to the number of subscripts of its related data set item or must be equal to 1. If an item has the same number of subscripts in the remap and in the data set, then each of the subscript limits of the item must be the same in the remap and in the data set.
When a multiple subscripted item is remapped to a singly subscripted item, its total number of occurrences in the remap cannot exceed the total number of occurrences in the physical data set. The total number of occurrences of an item is the product of the number of times the item itself occurs and the number of occurrences of each of the nested occurring groups that contains the item.

As with data set items, the unsigned integer that follows the OCCURS keyword cannot exceed 1023 in a remap item. If an item has a total number of occurrences in the data set that exceeds 1023, and if it is necessary to remap that item to an item that has only one subscript, then it is not possible to access the occurrences beyond 1023 through the remap.
If an item that is subscripted in the data set is included in a remap, it must be subscripted in the remap. In other words, it is illegal to remap an occurring item as a nonoccurring item.
If an item that has an OCCURS clause in the data set is included in a remap, it must have an OCCURS clause in the remap. This means that the following remap is illegal:
```
D DATA SET
(N NUMBER(3) OCCURS 2;
 A ALPHA(2) REQUIRED;
);
R REMAPS D
 (NEW-G GROUP
   (N NUMBER(3);
   )OCCURS 2;
  A ALPHA(2) REQUIRED;
);
```
No changes can be made to an item that is stored conditionally (OCCURS DEPENDING, STORED DEPENDING, SIZE VARYING, and so forth) if such changes would obscure the fact that it is stored conditionally. Therefore, if an occurring item, J, is a member of a group whose existence depends on another item, the data set to which J belongs cannot be remapped in such a manner that J is not within the original OCCURS DEPENDING group. In other words, J cannot be remapped to a singly subscripted item.
If subscript changes are made to an item in a remap, the item must be completely redescribed in the remap. The only item attribute that can be changed in a remap without requiring the item to be completely redescribed is the name of the item.
Items that are listed in the DATA clause of a set declaration cannot have an OCCURS clause. However, it is legal to have a group key data item that contains occurring items. Subscript changes are not allowed for such items.

Prev	Up	Next
Remap Filler Item	Home	Remap Link Item

Enterprise Database Server Data and Structure Definition Language (DASDL) Programming Reference ManualRemap Record Description

Remap Group Item

Enterprise Database Server Data and Structure Definition Language (DASDL) Programming Reference Manual
Remap Record Description