Composite fields: the GRPNAME option
The GRPNAME option is used to generate symbolic storage definitions and to combine specific fields under one group name. The same group name must be specified for each field that is to belong to the group.
About this task
Sometimes, you have to refer to subfields within a single
field on the display. For example, you can have a date field that
appears on the screen as follows:
03-17-92
It
is one field on the screen (with one attributes byte, just before
the digit “0”), but you must be able to manipulate the month, day,
and year components separately in your program.
You can do this
with a “group field”, using the GRPNAME option of the DFHMDF macro.
To create one, you code a DFHMDF macro for each of the component
subfields;
each definition names the same group field in the GRPNAME option.
To define the previous date as a group field starting at the beginning
of line 10, for example, we would write:
MO DFHMDF POS=(10,1),LENGTH=2,ATTRB=BRT,GRPNAME=DATE
SEP1 DFHMDF POS=(10,3),LENGTH=1,GRPNAME=DATE,INITIAL='-'
DAY DFHMDF POS=(10,4),LENGTH=2,GRPNAME=DATE
SEP2 DFHMDF POS=(10,6),LENGTH=1,GRPNAME=DATE,INITIAL='-'
YR DFHMDF POS=(10,7),LENGTH=2,GRPNAME=DATE
These
definitions produce the following in the symbolic output map:
02 DATE.
03 FILLER PICTURE X(2).
03 MOA PICTURE X.
03 MOO PIC X(2).
03 SEP1 PIC X(1).
03 DAO PIC X(2).
03 SEP2 PIC X(1).
03 YRO PIC X(2).
Several rules
must be observed when using a group field:
- There is only one attributes byte; it precedes the whole group field and applies to the whole field. You specify it just once, on the DFHMDF macro for the first subfield, MO here.
- Because there is only one attributes byte, the cursor behaves as if the group field were a single field. In our example, the cursor does not move from the last position of month to the first of day, or day to year, skipping over the hyphens. This is because the group really is a single field as far as the hardware goes; it is subdivided only for program access to the component subfields.
- Although subfields after the first do not have an attributes byte, you define the POS option as if they did, as shown in the example. That is, POS points to one character before the subfield begins, and can overlap the last character of the previous subfield, as occurs in our example.
- Although all the component subfields are adjacent in this example, they do not have to be. There can be gaps between the subfields, provided you do not define any other field in the gap. The group field spans all the columns from its first subfield to its last, and you must put the component DFHMDF macros in the order the subfields appear on the screen. The group ends with the first DFHMDF macro that does not specify its name.
- You must assign a field name to every subfield, even if you do not intend to refer to it (as we did in the SEP1 and SEP2 subfields in the example).
- You cannot use the OCCURS option (explained in the next section) for a group field or any of its components.