HP 3000 Manuals

HP RPG/XL Programmer's Guide

Using Data Structures 

A data structure is an area of storage that contains subfields.  You can
use data structures to describe input areas in more than one way.  You
may want to do this because:

 *  You need to process records in the same file and they have different
    formats.

 *  You need to reference subfields of fields as well as the fields
    themselves.

 *  You can process input fields more conveniently if they are
    rearranged.

Data structures can also be used to exchange information between other
RPG programs.

You use Input Specifications to define a data structure.  Place data
structures at the end of all of the other Input Specifications in the
program.

The "data structure" sections which follow in this chapter discuss the
ways you can use data structures to accomplish the objectives listed
above.


NOTE  HP implements data structures differently from some RPG vendors.
      Data structures occupy separate memory areas from the areas they
      redefine.  Thus, you should not use data structures simply to
      reduce memory requirements in your program.


Using Data Structures to Define Data More Than One Way 

This section explains how to use data structures to describe the same
data areas in more than one way.  This enables you to use the same data
several different ways.  For example, you can use data structures to
describe different record formats within a file.  Or you can use data
structures to redefine numeric fields in order to process them
differently.

Figure 5-6 and Figure 5-7 show how to describe three different input
records in the same file.  The example in Figure 5-6 does not use data
structures and the example in Figure 5-7 does.  In Figure 5-6, the second
and third records redescribe the first, using different field names and
definitions.  This method of defining data more than one way keeps field
definitions near the fields being redefined which improves readability
and maintainability.


          Figure 5-6.  Defining Different Record Formats Without Using Data Structures 

            Comments 

 1       This line defines the first record, SREC, in the file.  SREC is
         described in detail in the lines that follow.

 2       This line defines the second record, PREC. PREC is described in
         detail in the lines that follow.

 3       This line defines the third record, TREC. TREC is described in
         detail in the lines that follow.

Figure 5-7 is the same example as Figure 5-6 except that it uses data
structures to describe the three input records.


          Figure 5-7.  Defining Different Record Formats Using Data Structures 

            Comments 

 1       This line defines the sales record, SREC. SREC is described in
         detail starting with line 4.  There are 32 characters in SREC.

 2       This line defines the purchase record, PREC. PREC is described
         in detail starting with line 5.  There are 35 characters in
         PREC.

 3       This line defines the transaction record, TREC. TREC is
         described in detail starting with line 6.  There are 40
         characters in TREC.

 4       This line names SREC as the first record to be redefined as a
         data structure.

 5       This line names PREC as the second record to be redefined as a
         data structure.

 6       This line names TREC as the third record to be redefined as a
         data structure.

Using Data Structures to Define Subfields Within a Field 

This section tells you how to use data structures to divide a field or
array into subfields.  You can then refer to the subfields in Calculation
and Output Specifications.  In addition, you can use data structure names
to refer to the subfields as one unit.

Figure 5-8 and Figure 5-9 show how to define subfields two different
ways.  Figure 5-8 shows an input area that uses two data structures.  The
first data structure, PRODID, defines the subfields in positions 31-40 of
the input TRANS record.  The second data structure, CATLOG, is a nested
data structure.  That is, it is a data structure defining subfields
within another data structure (in this case, PRODID).


          Figure 5-8.  Using Data Structures to Define Subfields within a Field 

            Comments 

 1       This line defines the field PRODID. It occupies positions 31 to
         40 in the input record.

 2       This line marks the beginning of the data structure PRODID. The
         next three lines define the subfields of the PRODID field.

 3       This line defines the first subfield of PRODID. Notice that
         CATLOG is defined further by the next data structure (line 4).

 4       This line is the beginning of the data structure CATLOG. The
         next two lines define the subfields of the CATLOG field.

 5       The first subfield of CATLOG is CLASS. It is a one-character
         field starting with the first position of CATLOG.

 6       The second subfield of CATLOG is REFNO. It is also a
         one-character field starting with the second position of CATLOG.


NOTE  You can nest data structures to the number of levels necessary.
      This feature is unavailable in most implementations of RPG.


Figure 5-9 shows subfields defined in a different way from those shown in
the previous figure.  However, the end results of the two examples are
identical.


          Figure 5-9.  Alternate Way to Define Subfields within a Field 

            Comments 

 1       This line defines the input field, PRODID, whose subfields are
         defined in the data structure starting on line 2.  PRODID
         occupies positions 31-40 of the input record.

 2       This line starts the data structure, PRODID. It describes the
         subfields of PRODID in the input record.

 3       This line defines the field, CATLOG, that occupies positions 1
         and 2 of the field PRODID. Notice that the next two fields are
         subfields of CATLOG.

 4       This lines defines the field, CLASS, that occupies position 1 of
         the field PRODID.

 5       This line defines the field, REFNO, that occupies position 2 of
         the field PRODID.

Using Data Structures to Reorganize Fields in an Input Record 

This section explains how data structures can be used to rearrange input
record fields so that you can use them more readily in a program.

Two examples are presented.  The first shows how to reorder one field and
the second shows how to reorganize several fields at once.

Figure 5-10 shows how to reorder the field, KEY05, so that it is the
second part of a key field.  The key field will be used for reading a
KSAM file.  This example initializes the data structure field, ALPHA, to
A at line 5.  When the TRANS file is READ, KEY05 is automatically moved
to the input field and to the data structure.  Line 6 shows the KSAM disc
read operation that uses the new key, KEY06.


          Figure 5-10.  Using a Data Structure to Build a Key Field 

            Comments 

 1       This line defines the input field, KEY05.  It occupies positions
         71 to 75 in the input record, TRANS.

 2       This line begins the data structure, KEY06.

 3       This line defines the first subfield, ALPHA, in the data
         structure.  ALPHA occupies the first position of KEY06.

 4       This line defines the position in the data structure that KEY05
         occupies.  It is the second field and occupies positions 2
         through 6.

 5       This line is part of the initialization operations.  It sets the
         field, ALPHA, to A (it remains A for the duration of the
         program).

 6       This line reads the file, FILE1, by key value.  The specific key
         value used has already been placed into the data structure,
         KEY06, by previous operations.

Figure 5-11 shows how to reorganize an input record so that its fields
closely match those of an output record.  When TRANS is read, RPG
automatically moves its input fields to the appropriate areas in the
KEYDS data structure.  Notice that the input fields, QTY and CODE, are
not included in the data structure.  The PRTKEY field is optional.  It
can be used to refer to all 16 positions of the KEYDS data structure
(KEYDS also refers to these positions).


          Figure 5-11.  Using a Data Structure to Reorganize Input Fields 

            Comments 

 1       This line begins the description of the data structure, KEYDS.

 2       This line defines LOCATN as the first field in KEYDS. Since
         LOCATN is also defined in the input record, its value is moved
         here when the file is read.

 3       This line specifies that the second field in the data structure
         is PARTNO and its value comes from the field by the same name in
         the input record, TRANS.

 4       This line defines the third field, TYPE, in the data structure.
         Its value comes from the field by the same name in the input
         record, TRANS.

 5       This line defines the field, PRTKEY. PRTKEY refers to all of the
         fields in the data structure (positions 1-16).

Using Data Structures for Interprogram Communication 

This section discusses how to receive information from other programs and
how to pass information to them using a standard RPG file, the Local Data
Area file (LDAFILE). To use a Local Data Area file, you must define it
using a data structure.

When you use a Local Data Area in your program, RPG begins by reading the
file into your data structure.  You can use that data during the first
cycle (1P) output.  When your program ends, RPG automatically writes the
data structure back to the Local Data Area file.

Before you can use a Local Data Area file in a program, you must create
it using the RPGINIT utility (see the RPG Utilities Reference Manual for
more detailed information).

Figure 5-12 lists a logon User Defined Command (UDC) that creates a Local
Data Area file automatically.  The UDC creates a file consisting of two
records, each containing 256 characters.  The records are initialized to
blanks.  The FCOPY command copies the file, SYSCTL, to the newly-created
Local Data Area file.  SYSCTL contains one record with the company name
in positions 1 to 40.  The company name is used in the next example as a
report heading.
_________________________________________________________
|                                                       |
|     START                                             |
|     OPTION  LOGON                                     |
|     COMMENT  INITIALIZE  LOCAL  DATA  AREA  AND  WRITE|
|     COMMENT  COMPANY  NAME  TO  POSITION  ONE         |
|     COMMENT  OF  LDA  FOR  USE  BY  REPORT  PROGRAMS  |
|     RUN RPGINIT.PUB.SYS                               |
|     FCOPY FROM=SYSCTL;TO=LDAFILE                      |
|                                                       |
|                                                       |
_________________________________________________________

          Figure 5-12.  Creating a Local Data Area File (LDAFILE) with a UDC 

Once you create a Local Data Area file, you can use it in any RPG
program.  Figure 5-13 shows how to process the Local Data Area file
created in Figure 5-12.  The company name (CNAME), contained in the Local
Data Area file, is used in a report heading.  Also, a transaction record
count is accumulated in the field, COUNT. This field is also saved in the
Local Data Area file.


          Figure 5-13.  Using a Local Data Area File (LDAFILE) 

            Comments 

 1       This line defines the file used for printing the report.

 2       This line defines the Local Data Area file and begins the data
         structure description for it.  Notice that you do not use a File
         Description Specification for a Local Data Area file.

         Columns 7-14 contain LDA to identify this structure as a Local
         Data Area structure.  You must use LDA; other names are ignored.

         Column 18 contains U to specify that this is a User Data
         Structure (the data structure for the Local Data Area file).

         Columns 19-20 contain DS to identify this as a data structure.

 3       This line defines the first field, CNAME, of the data structure.
         It is 40 characters long and starts in the first position of the
         record.  CNAME contains the company name.

 4       This line defines the second field, COUNT, of the data
         structure.  It is 5 positions long and starts in position 101.
         It contains the count of transactions.

 5       This line increments the COUNT field.

 6       This line begins the Output Specification that writes the
         company name, CNAME, to the report file.

MPE/iX 5.0 Documentation