Data Structure Examples

Using a Data structure to subdivide a field

DCL-DS Partno;
   Manufactr CHAR(4);
   Drug CHAR(6);
   Strength CHAR(3);
   Count ZONED(3);
END-DS;

You can refer to the entire data structure by using Partno, or by using the individual subfields Manufactr, Drug, Strength or Count.

D Partno          DS
D  Manufactr                     4
D  Drug                          6
D  Strength                      3
D  Count                         3  0
D

Using a data structure to group fields from an input record

Another file ITEMMASTER has a single field ITEM_NBR which contains the LOCATION, PARTNO, and TYPE data.

You can use a data structure to group the 3 fields from the TRANSACTN file so they match the ITEM_NBR field in the ITEMMASTER file.

When you use a data structure to group fields, fields from non-adjacent locations on the input record can be made to occupy adjacent internal locations. The area can then be referred to by the data structure name or individual subfield name.

DCL-DS Partkey;
   Location;
   Partno;
   Type;
END-DS;

READ ITEMMASTER;
. . .
READ TRANSACTN;
IF Partkey = Item_Nbr;
  . . .
ENDIF;

Using Keywords QUALIFIED, LIKEDS and DIM with data structures

     D CustomerInfo     DS                         QUALIFIED TEMPLATE
     D    Name                               20A
     D    Address                            50A

     D ProductInfo      DS                         QUALIFIED TEMPLATE
     D    Number                              5A
     D    Description                        20A
     D    Cost                                9P 2

     D SalesTransaction...
     D                  DS                         QUALIFIED
     D    Buyer                                    LIKEDS(CustomerInfo)
     D    Seller                                   LIKEDS(CustomerInfo)
     D    NumProducts                        10I 0
     D    Products                                 LIKEDS(ProductInfo)
     D                                             DIM(10)
          TotalCost = 0;
          for i = 1 to SalesTransation. Numproducts;
              TotalCost = TotalCost + SalesTransaction.Products(i).Cost;
              dsply SalesTransaction.Products(i).Cost;
          endfor;
          dsply ('Total cost is ' + %char(TotalCost));
 

Data structure with absolute and length notation

D FRED            DS
D  Field1                 1    700    DIM(70)
D  Field2               701    730
D   Field3              701    715
D    Field5             701    704B 2
D   Field4              716    730

DCL-DS FRED;
   Field1 CHAR(10) DIM(70);
   Field2 CHAR(30);
      Field3 CHAR(15) OVERLAY(Field2);
         Field5 BINDEC(4:2) OVERLAY(Field3);
      Field4 CHAR(15) OVERLAY(Field2:16);
END-DS;

D FRED            DS
D  Field1                       10    DIM(70)
D  Field2                       30
D   Field3                      15    OVERLAY(Field2)
D    Field5                      4B 2 OVERLAY(Field3)
D   Field4                      15    OVERLAY(Field2:16)

Rename and initialize an externally described data structure

• Define an externally described data structure with internal name FRED and external name EXTDS.
• Rename field CUST to CUSTNAME.
• Initialize CUSTNAME to 'GEORGE' and PRICE to 1234.89.
• Specify the DIM keyword for subfield ITMARR. The ITMARR subfield is defined in the external description as a 100 byte character field. This divides the 100 byte character field into 10 array elements, each 10 bytes long.
  Warning: Using the DIM keyword on an externally described numeric subfield should be done with caution, because it will divide the field into array elements which might not have valid numeric data for each element of the array.

DCL-DS Fred EXTNAME('EXTDS');
   CUSTNAME EXTFLD('CUST') INZ('GEORGE');
   PRICE EXTFLD INZ(1234.89);
   ITMARR EXTFLD DIM(10);
END-DS;

D Fred          E DS                  EXTNAME(EXTDS)
D   CUSTNAME    E                     EXTFLD(CUST) INZ('GEORGE')
D   PRICE       E                     INZ(1234.89)
D   ITMARR      E                     DIM(10)

Using PREFIX to rename all fields in an external data structure

In the following data structure definition, the external subfield names are prefixed with 'CU_' unless the subfield has been renamed using the EXTFLD keyword.

The free-form definition for the data structure

The EXTFLD is used to identify external subfields. The EXTFLD keyword can be used to rename the subfield by specifying the new name as the parameter for the keyword. In the following example, external field NUMBER is renamed to Custnum.

DCL-DS extds1 EXTNAME('CUSTDATA')
              PREFIX(CU_);
   Name EXTFLD INZ('Joe''s Garage');
   Custnum EXTFLD('NUMBER');
END-DS;

The fixed-definition of the same data structure

Specify 'E' in column 22 to identify the subfield as an external subfield. Use the EXTFLD keyword to specify a new name for the subfield.

... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords++++++++++++
D extds1        E DS                  EXTNAME (CUSTDATA)
D                                     PREFIX (CU_)
D   Name        E                     INZ ('Joe''s Garage')
D   Custnum     E                     EXTFLD (NUMBER)

D EXTDS1        E DS
D   CU_NAME     E               20A   EXTFLD (NAME)
D                                     INZ ('Joe's Garage')
D   CU_ADDR     E               50A   EXTFLD (ADDR)
D   CUSTNUM     E                9S 0 EXTFLD (NUMBER)
D   CU_SALESMN  E                7P 0 EXTFLD (SALESMN)

Defining a multiple occurrence data structure

The subfields are defined with absolute notation using begin and end positions

Named constant Max_Occur is used to define the number of occurrences.

D Max_Occur       C                   CONST(20)
D
DDataStruct       DS                  OCCURS (Max_Occur)
D field1                  1     20
D field2                 21     40
D  field21               22     31
D field3                 41     60

The subfields are defined with a mixture of absolute notation and length notation

D DataStruct      DS                  OCCURS(20)
D  field1                       20
D  field2                       20
D   field21              22     31
D  field3                41     60

Aligning Data Structure Subfields

See ALIGN{(*FULL)} for information about alignment.

D MyDS            DS                  ALIGN  1 
D    Subf1                33    34I 0  2 
D    Subf2                37    40I 0  2 
D    Subf3                       5I 0  3 
D    Subf4                      10I 0  3 
D    Group               101   120A    4 
D      Subf6                     5I 0 OVERLAY (Group: 3)  4 
D      Subf7                    10I 0 OVERLAY (Group: 5)  4 
D      Subf8                     5U 0 OVERLAY (Group: 9)  4 
D    SubfX1               10    11I 0  4 
D    SubfX2               15    18I 0  4 
D    BadGroup            101   120A    6 
D      SubfX3                    5I 0 OVERLAY (BadGroup: 2)   6 
D      SubfX4                   10I 0 OVERLAY (BadGroup: 6)   6 
D      SubfX5                   10U 0 OVERLAY (BadGroup: 11)  6 
D    WorseGroup          200   299A    7 
D      SubfX6                    5I 0 OVERLAY (WorseGroup)     7 
D      SubfX7                   10I 0 OVERLAY (WorseGroup: 3)  7 

Defining a *LDA data area data structure

Define a data area data structure based on the *LDA.

A data area data structure with no name is based on the *LDA.

The free-form definition, with *AUTO specified for the DTAARA keyword:

DCL-DS *N DTAARA(*AUTO);
   SUBFLD CHAR(600);
END-DS;

The equivalent fixed-form definition with definition-type U. In this case, the DTAARA keyword does not have to be used.

D                UDS
D  SUBFLD                 1    600A

The data structure is explicitly based on the *LDA. Since it is not a data area data structure, it must be handled using IN and OUT operations.

The free-form definition:

DCL-DS LDA_DS DTAARA(*LDA);
   SUBFLD CHAR(600);
END-DS;

IN LDA_DS;
OUT LDA_DS;

The equivalent fixed-form definition of the data structure:

D LDA_DS          DS                  DTAARA(*LDA)
D  SUBFLD                 1    600A

The data structure is explicitly based on the *LDA. It is a data area data structure, so it is read in during initialization and written out during termination. It can also be handled using IN and OUT operations.

The free-form definition. The *AUTO parameter defines it as a data area data structure. The *USRCTL parameter specifies that it can be handled using IN and OUT operations.

1. Display the value of the data structure at the beginning of the program after the data area has been read into the data structure during program initialization.
2. Change the value of the data structure.
3. Write out the data area

DCL-DS LDA_DS DTAARA(*LDA : *AUTO : *USRCTL);
   SUBFLD CHAR(50);
END-DS;

DSPLY SUBFLD;          1 
SUBFLD = 'New value';  2 
OUT LDA_DS;            3 

The equivalent fixed-form definition of the data structure. The U definition type defines it as a data area data structure. The DTAARA keyword specifies that it can be handled using IN and OUT operations.

D LDA_DS         UDS                  DTAARA(*LDA)
D  SUBFLD                 1     50A

Using data area data structures to communicate between programs

Program 1: This program uses a data area data structure to save the accumulate values of a series of totals.

1. The data area is read into the data structure during program initialization.
2. The data area subfields are then added to fields from the file SALESDTA.
3. Indicator *INLR is set on so that the data area is written out when the program ends.

DCL-F SALESDTA;

DCL-DS Totals DTAARA(*AUTO);       //  1 
   Tot_amount ZONED(8:2);
   Tot_gross  ZONED(10:2);
   Tot_net    Zoned(10:2);
END-DS;
. . .
Tot_amount = Tot_amount + amount;  //  2 
Tot_gross = Tot_gross + gross;
Tot_net = Tot_net + net;
. . .
*INLR = *ON;                       //  3 

Program 2: This program processes the totals that were calculated in Program 1.

1. The data area is read into the data structure during program initialization.
2. The data area subfields are used in calculations.

DCL-DS Totals DTAARA(*AUTO);     //  1 
   Tot_amount ZONED(8:2);
   Tot_gross  ZONED(10:2);
   Tot_net    Zoned(10:2);
END-DS;
. . .
*IN91 =  (Amount2 <> Tot_amount);//  2 
*IN92 =  (Gross2 <> Tot_gross);
*IN93 =  (Net2   <> Tot_net);
. . .

Using an indicator data structure

1. The INDDS keyword identifies the DispInds data structure as the indicator data structure for file Disp.
2. Indicator data structure DispInds is defined. The position for each subfield is the same as the indicator number used to control the display file. For example, if the display file refers to indicator 21, specify 21 as the position for the indicator in the data structure.
3. Set the indicators to control the subfile.
4. The indicators in the indicator data structure are used to control the EXFMT operations.
5. Using an indicator data structure allows readable names to be used for the indicators set by the EXFMT operation.

DCL-F Disp WORKSTN INDDS(DispInds); //  1 

DCL-DS DispInds; //  2 
   // Format QUERY
   ShowName IND POS(21);
   Exit IND POS(3);
   Cancel IND POS(12);
   BlankNum IND POS(31);

   // Format DISPSFLCTL
   SFLDSP IND POS(42);
   SFLEND IND POS(43);
   SFLCLR IND POS(44);
END-DS;
. . .

SFLDSP = *ON;       //  3 
SFLEND = *OFF;
SFLCLR = *OFF;
EXFMT DispSFLCTL;   //  4 

EXFMT Query;
IF  Exit or Return; //  5 
   *INLR = *ON;
   RETURN;
ENDIF;

Using a multiple-occurrence indicator data structure

When you use a multiple-occurrence data structure as the indicator data structure for a file, you can use a different occurrence for each record format in the file.

1. The QUERY format prompts the user for a name. The format has 3 response indicators, 03, 05, and 12.
2. The ERRMSG format shows an error message. The format has 3 conditioning indicators, 01, 02, and 03, to control which error message is displayed.

   Indicator 03 is used for both formats.

3. The INDDS keyword identifies the DispInds data structure as the indicator data structure for file Disp.
4. Indicator data structure DispInds is defined as a multiple occurrence data structure with one occurrence for each record format in the file. The number of occurrences is set by named constant NUM_FORMATS.
5. Both formats use indicator 03 for different purposes.
6. Constants are defined for the values that might be returned by the CheckName procedure. The constants can be used
7. The first occurrence of the data structure is used when showing the QUERY format which might set response indicators 03, 05, and 12.
8. The second occurrence of the data structure is used when showing the ERRMSG format which might have set conditioning indicator 01, 02, or 03.

     A                                      INDARA
     A          R QUERY                     CA03(03) CA05(05) CA12(12)  1 
     A                                  3  2'Enter the name'
     A            NAME          20A  B  3 30CHECK(LC)
     A                                 23  2'03=Exit  05=Refresh  12=Return'
     A                                      COLOR(BLU)
     A          R ERRMSG                                                       2 
     A            NAME          20A  O  4  2
     A  01                              4 30'Not found'
     A  02                              4 30'Not valid'
     A  02                              4 30'Not valid'
     A  03                              5  3'Not unique'

DCL-F Disp WORKSTN INDDS(DispInds);      //  3 

DCL-C NUM_FORMATS 2;                     //  4 
DCL-DS DispInds OCCURS(NUM_FORMATS) INZ; //  4 
   // Format QUERY
   Exit IND POS(3);                      //  5 
   Refresh IND POS(5);
   Cancel IND POS(12);

   // Format ERRMSG
   NotFound IND POS(1);
   NotValid IND POS(2);
   NotUnique IND POS(3);                 //  5 
END-DS;

DCL-C NameOk        0;                   //  6 
DCL-C NameNotFound  1;
DCL-C NameNotValid  2;
DCL-C NameNotUnique 3;

DCL-S rc INT(10);

DOU Exit or Cancel;
   %OCCUR(DispInds) = 1;  //  7 
   EXFMT QUERY;

   SELECT;     //  7 
   WHEN Exit or Cancel;
      *INLR = *ON;
      RETURN;
   WHEN Refresh;
      RESET QUERY;
   ITER;
   ENDSL;

   rc = CheckName (name);
   IF rc <> NameOk;
      %OCCUR(DispInds) = 2;  //  8 
      CLEAR DispInds;

      SELECT rc;
      WHEN-IS NameNotFound;
         NotFound = *ON;
      WHEN-IS NameNotValid;
         NotValid = *ON;
      WHEN-IS NameNotUnique;
         NotUnique = *ON;
      ENDSL;
      EXFMT ERRMSG;
   ENDIF;
ENDDO;

Defining a constant data structure

1. Data structure info_defaults is defined with CONST. The compiler does not allow the subfields of the data structure to be changed.
2. Data structure info is defined to have the same subfields and initialization values as info_defaults.
3. If subfield info.branch is not the same as the default value for the branch subfield, procedure changeBranch is called.
4. The subfields of data structure info are assigned their default values.

DCL-DS info_defaults CONST QUALIFIED;            //  1 
   branch VARCHAR(20) INZ('Main branch');
   address VARCHAR(40) INZ('123 Elm St');
END-DS;

DCL-DS info LIKEDS(info_defaults) INZ(*LIKEDS);  //  2 

. . .
getBranchInfo (info);
if info.branch <> info_defaults.branch;          //  3 
   changeBranch (info);
endif;
. . .
EVAL-CORR info = info_defaults;                  //  4