HP 3000 Manuals

Tables and Arrays [ HP RPG/iX Reference Manual ] MPE/iX 5.0 Documentation

HP RPG/iX Reference Manual

Tables and Arrays

The table and array sections which follow in this chapter explain how to
create and use tables and arrays in an RPG program.

Creating Tables and Arrays

Compile-time and preexecution-time tables and arrays reside in disk files
and are loaded before a program begins execution. Execution-time arrays
can reside in files on disk or you can create them with Calculation
Specification operations at run time.

When creating a table or array, ensure that:

* Each entry in the table or array has the same field length, data
type, and the same number of decimal positions.

* Each alphanumeric entry contains 256 characters or less.

* Each numeric entry contains 15 digits or less.

* Entries are not split between records.

* There are no blanks between entries. All entries must be
continuous on each record. (You can, however, embed blanks as
part of an entry.)

* The entries are in the appropriate sequence - ascending,
descending or random.

Creating Compile-Time and Preexecution-Time Tables and Arrays.

In addition to the guidelines in the previous section, when you create
compile-time and preexecution-time tables and arrays, ensure that:

* The first entry in each record starts in position 1.

* All records (except the last) contain the same number of entries.
The last record can contain fewer entries, but it cannot contain
more. For example, if the first record contains seven entries,
all but the last record must contain seven entries. The last
record can contain from one to seven entries.

* There are the same or fewer entries in the table or array than the
number you enter in the Entries Per Table/Array Field (columns
36-39) of the File Extension Specification. A full table or array
contains the same number of entries as you specify in the File
Extension Specification. Tables and arrays containing fewer
entries than specified, are called short tables and arrays and the
unused entries are automatically set to zeros. The unused entries
in short alphanumeric tables and arrays contain blanks. Short
tables and arrays let you start with only a few entries, then add
to them at a later time. You must include at least one entry.

* The number of entries in each input record matches the number in
the Entries Per Record Field (columns 33-35) of the File Extension
Specification and the previous rule. You can fill an entire
record if necessary. Leave the remaining positions blank, or use
them for comments.

* When entering input records for tables and arrays and their
alternating tables and arrays, start with the first entry of the
table or array (named in columns 27-32 of the File Extension
Specification) and follow it by the first entry in the alternating
table or array (named in columns 46-51 of the File Extension
Specification). End all records, including the last, with an
entry from the alternating table or array.

* The table or array file has fixed-length records and is a
sequential file.

Defining Tables and Arrays

The next two sections explain how to use the File Extension Specification
to define tables and arrays. If you're using compile-time tables or
arrays on disk, you must also enter an Array/Table File Name
Specification that names the disk file containing the table or array.

Defining Compile-Time and Preexecution-Time Tables and Arrays.

Use this checklist when you define compile-time and preexecution-time
tables and arrays:

* To sequence check the table or array when it is loaded, enter A or
D in the Table/Array Sequence Field (column 45) of the File
Extension Specification.

If you're going to use the LOKUP operation with high and low
indicators in a Calculation Specification, you must specify
sequence-checking.

* If the table or array entry contains a leading or trailing sign,
enter the appropriate character in the Data Format Field (column
43), and allow for the sign when specifying the Entry Length Field
(columns 40-42).

* For table and array files having a T in the File Designation Field
(column 16) of the File Description Specification, enter a
fixed-length record format in the Record Format Field (column 19)
of that specification.

* For numeric tables and arrays, specify the data format in the Data
Format Field (column 43) of the File Extension Specification and
the the number of decimal positions in the Decimal Positions Field
(column 44) of that specification.

Example

Figure 5-4 shows how to define two arrays using File Extension
Specifications. ARRA is a compile-time array containing 10 entries (2
per record). Each entry is 12 digits long, has two decimal places, and
is in unpacked decimal format. ARRB is a preexecution-time array,
residing in the disk file DISKER. It contains 300 entries (10 per
record). Each entry is 6 positions long, has no decimal places, and is
in unpacked decimal format.
________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| E ARRA 2 10 12 2 COMPILE-TIME |
| . |
| . |
| . |
| |
| E DISKER ARRB 10 300 6 0 PREEXEC-TIME |
| |
| |
________________________________________________________________________________

Figure 5-4. Defining Compile-Time and Preexecution-Time Arrays

Defining Execution-Time Arrays.

To define an execution-time array, leave columns 7-26 and the Entries Per
Record Field (columns 33-35) blank in the File Extension Specification.

If it is a numeric array, enter the data format in the Data Format Field
(column 43) and the number of decimal positions in the Decimal Positions
Field (column 44).

Example

Figure 5-5 shows how the execution-time array ARRC is defined. It
has 10 alphanumeric entries, each 2 positions long.
________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| E ARRC 10 2 0A EXEC-TIME |
| |
| |
________________________________________________________________________________

Figure 5-5. Defining Execution-Time Arrays

Loading Tables and Arrays

The next three sections describe how RPG loads table and arrays. (Tables
and arrays must be loaded before you can access them in the program.)

Loading Compile-Time Tables and Arrays.

The RPG compiler makes compile-time tables and arrays an integral part of
the object program and they are loaded along with it at run time.

You can place compile-time tables and arrays at the end of the source
program, keep them in files on disk, or any combination of the two.
Additionally, the same disk file can contain more than one table or
array. If this is the case, you must enter the File Extension
Specifications in the same order as the tables and arrays appear in the
job stream or disk file.

ALTSEQ records and file translation records are also processed at
compile-time. ALTSEQ records, file translation records and compile-time
tables and arrays are loaded in the following order:

1. ALTSEQ (alternate collating sequence) records.

2. Compile-time tables and arrays, in the same order as the File
Extension Specifications.

3. File translation records.

Loading Compile-Time Tables and Arrays Appended to the Source Program

When tables, arrays, ALTSEQ, and file translation records are appended to
the source program or when they are contained in a job file, enter them
as follows:

1. After the last record in the source program, enter a separator
record containing **_ (where _ represents a blank) in columns 1-3.

2. ALTSEQ records, if any.

End the ALTSEQ records by a separator line containing **_ in
columns 1-3. (Only use the separator line when there are ALTSEQ
records.)

3. Enter compile-time tables and arrays according to the format
discussed in the "Creating Tables and Arrays" section of this
chapter. Be sure the format conforms to the entries in the File
Extension Specifications. End each table or array with a
separator record (**_ in columns 1-3).

4. If you're using file translation records, enter a separator line
(**_ in columns 1-3). Enter the file translation records,
separating each new file name record with a separator record (**_
in columns 1-3).

Example

The following source program file contains two alternate collating
sequence records, four array records and a file translation record.

.
. Source program
.
**_
ALTSEQ 51415942
ALTSEQ 5843 Alternate collating sequence records

**_
ALPHA
BETA
GAMMA Compile-time array
DELTA
**_
OUTPUT 58445745 File translation record

Loading Compile-Time Tables and Arrays from Disk Files

When you want to place ALTSEQ records, compile-time tables and arrays,
and file translation records into a disk file, enter them as follows:

1. Enter the ALTSEQ records, tables, arrays, and file translation
records into a disk file according to the instructions in the
preceding section "Loading Compile-Time Tables and Arrays Appended
to the Source Program". Use separator records as needed but do
not start the file with a separator record.

2. Enter Array/Table File Name Specifications (as described in Table
5-1) after the last specification in the program. For instance,
if you have Output Specifications, the Array/Table File Name
Specifications follow the last one. Do not place a separator
record between the last specification and the first Array/Table
File Name Specification.

Table 5-1. Array/Table File Name Specification Format

-----------------------------------------------------------------------------------------------
| | | |
| Columns | Values | Description |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| 1-5 | 00000-99999 | Sequence number, as defined in Chapter 2. |
| | | |
| 6 | A | This is an Array/Table File Name |
| | | Specification. |
| | | |

The following lines show how to enter three Array/Table File Name
Specifications:

.
. Source program
.

ADISKFILE
ATABFILE1 Array/Table File Name Specifications
ATABFILE2

When you compile the program, the ALTSEQ records, file translation
records and the tables and arrays are made part of the program.

Example

The following lines show how to place two ALTSEQ records, four
compile-time array records and one file translation record in a disk
file.

ALTSEQ 51415942
ALTSEQ 5843 Alternate collating sequence records

**_
ALPHA
BETA
GAMMA Compile-time array
DELTA
**_
OUTPUT 58445745 File translation record

Loading Compile-Time Tables and Arrays from the Source Program and Disk

You can load ALTSEQ records, tables, arrays, and file translation records
from the source program and from disk in the same program.

Make sure that the order of the data records, whether loaded from the
source program or from disk is: ALTSEQ records, table and array records,
then file translation records.

The compiler loads data records in the order in which you enter
the Array/Table File Name Specifications. When entering these
specifications, be careful not to enter a separator record before them.
If you do, they will be treated as data.

Example

The following lines show how to load ALTSEQ records from a disk file
TABFILE, and how to load four compile-time array records and two file
translation records from records appended to the source program.

.
. Source program
.
File containing ALTSEQ records
ATABFILE (can also contain compile-time
tables or arrays).
**_
ABLE
BAKER Another compile-time array
CHARLIE
DOG
**_
OUTPUT 58445745 File translation record
**_
INPUT 59426043 File translation record

Loading Preexecution-Time Tables and Arrays.

Preexecution-time tables and arrays can reside on the same device or on
different devices. They are loaded before the program is executed and in
the order in which they are listed in the File Extension Specifications.
When you create table and array files, observe these rules:

* If you're sequence-checking a table or array, ensure that the last
record in the table or array is not blank. The last entry for a
table or array in ascending sequence has the highest value. For
descending sequence, the last entry has the lowest value.

* Ensure that the tables and arrays are in the same order on disk as
shown in the File Extension Specifications.

* Follow each table or array in an input file with a separator
record (containing asterisks in columns 1-2 and a blank in column
3). This record delimits the tables or arrays; it is not treated
as data.

* When input data follows a table or array in a file, place a
separator record (two asterisks and a blank) between the table or
array and the data.

Loading Execution-Time Arrays.

There are two ways to load execution-time arrays.

You can create the array entries and place them in a file on disk, then
define the array entries using an Input Specification. Or you can create
the array entries yourself at run time using Calculation Specification
operations.

If you load the array using Input Specifications, entries may occupy
consecutive positions in the input records or they can be scattered
throughout the records with intervening spaces. When an array is
contained on one input record and has consecutive entries, enter just one
Input Specification. When the entries are scattered, enter an Input
Specification for each entry.

When entering Input Specifications for execution-time arrays, follow
these rules (see Chapter 7 for details about the Input Specification
fields):

* Enter I in the File Type Field (Column 6).

* Leave columns 7-42 blank.

* Enter the appropriate value in the Data Format Field (column 43).

* For arrays containing consecutive entries, enter the field
location of the entire array in columns 44-51. For arrays
containing scattered entries, enter the field location of each
entry in columns 44-51. Enter the beginning location in the From
Field (columns 44-47) and the ending location in the To Field
(columns 48-51).

* If you indicated in the Decimal Position Field of the File
Extension Specification that the entries have one or more decimal
positions, enter the same value in the Decimal Position Field of
the Input Specification (column 52). Otherwise, leave the Decimal
Position Field blank.

* Enter the name of the array in the Field Name Field (columns
53-58). This must be the same name entered in the Table/Array
Name Field (columns 27-32) of the File Extension Specification.
To define an individual entry in the array, enter an index (see
the section which follows titled "Searching Arrays" for
information on indexing.)

* Leave columns 59-62 blank.

* Enter the field record relation indicator, if you're using one, in
the Field Record Relation Field (columns 63-64).

When an array requires two or more input records, you can define the
array entries collectively or individually in the Input Specification.
Use variable indexes and (or) record-identifying indicators to avoid
overlaying the entries in one record with those in another.

Since the HP RPG logic cycle processes only one record at a time, several
cycles are required to load a multirecord array. Because of this, you
may need to suppress calculations and output until the entire array has
been read. To do this, enter indicators in the Indicators Field of
Calculation Specifications and the Output Indicators Field (columns
23-31) of Output Specifications.

Example

Figure 5-6 shows the File Extension and Input Specifications for three
different kinds of arrays. ARR1 contains eight entries (each 10
positions long) that are loaded from a single record in the disk file
FILEA. ARR2 contains five entries, all in a single input record. The
entries are five positions long and have intervening blanks. (Note that
the entries are listed individually on the Input Specification.) ARR3
contains 30 entries each 10 positions long. The first four input records
contain seven entries each (in columns 3-72). The fifth input record
contains two entries (in columns 3-22).
________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| E ARR1 8 10 |
| E ARR2 5 5 |
| E ARR3 30 10 |
| . |
| . |
| . |
| |
| IFILEA AA 01 |
| I 1 80 ARR1 |
| IFILEA AA 01 |
| I 1 5 ARR2,1 |
| I 7 11 ARR2,2 |
| I 13 17 ARR2,3 |
| I 19 23 ARR2,4 |
| I 25 29 ARR2,5 |
| IFILEA AA 01 |
| I 1 20X |
| I 3 72 ARR3,X |
| |
| |
________________________________________________________________________________

Figure 5-6. Loading Execution-Time Arrays

Searching Tables

The Calculation Specification LOKUP operation lets you search tables for
specific values.

When you use LOKUP, enter the same name for the table that you used in a
File Extension Specification. The table is searched sequentially (unless
you request a binary search and the entries are in sequence) until an
entry is found that matches the search argument. The entry can then be
used in calculations. Subsequently, when you reference the table name as
an operand in a Calculation Specification operation, the entry found by
the most recent LOKUP operation is selected.

You can use the SORTA Calculation Specification operation to ensure that
a table or array is sequenced properly.

Searching Arrays

You can search arrays using the LOKUP Calculation Specification operation
(see the previous section, "Searching Tables"). In addition, you can
access individual entries in an array by using an index.

When referencing an entire array, use the array name entered in the File
Extension Specification.

When you want to access a specific entry in an array using a Calculation
Specification, enter the array name followed by a comma and an index.
The index can be a number or the name of a numeric field containing the
number of the entry you want to access. The index value for the first
entry is 1 (not zero). An index field must not have decimal positions
and can be no longer than 9 digits.

For example, to reference the fourth entry in the array XARY, enter:

XARY,4

Alternatively, if N is an index field containing the number 4, you can
reference the fourth entry by entering:

XARY,N

Table 5-2 shows which Calculation Specification operations allow
indexing and which do not.

Table 5-2. Indexing with Calculation Specification Operations

When you enter an array name without an index, the following rules apply:

* When you enter arrays in one of the Factor Fields and the Result
Field, they are searched sequentially. If the arrays do not
contain the same number of entries, the search ends when the last
entry in the shortest array is processed.

* When one Factor Field is a field or constant and the other Factor
Field and the Result Field are both arrays, the search continues
until every entry in the shorter array has been processed. The
same field or constant is used in all of the operations.

* Since multiple operations are performed, resulting indicators can
only be used with the XFOOT and LOKUP operations.

Changing Table and Array Entries During Execution

You can temporarily change table or array values by entering the table or
array name in the Result Field of an arithmetic or move Calculation
Specification operation. Additionally, you can add or modify table or
array values using Input or Calculation Specifications. Changes that you
make remain in effect for the duration of the program; when the program
ends, they are lost.

To permanently change table or array values, you can save the updated
table or array into a file on disk (see the section which follows,
"Writing Tables and Arrays") or you can manually modify the original
table or array file.

You can add entries to short tables and arrays using Calculation
Specification operations or you can read them from new input records at
run time.

NOTE If a run-time array indexing error is detected (index < one or >
array size) and a "continue" response is selected, HP RPG/iX will
reset the index to one before continuing.

Writing Tables and Arrays

You can write a table or array to a disk file, terminal, or to the line
printer.

To write an entire table or array (except an execution-time array),
including temporary modifications, enter the name of the table or array
output file in the To File Name Field (columns 19-26) of the File
Extension Specification. To write an execution-time array, enter Output
Specifications for it.

To write individual entries in a table or array, enter Output
Specifications only for those entries. Describe them just as you would
normal output fields. Using the table name in the Output Specification
causes the last entry found (not the entire table) to be written.

When you specify editing for an output array, the editing applies to all
entries in the array. If entries have different editing requirements,
reference them individually. When you enter an edit code for the entire
array in an Output Specification, RPG separates edited array entries by
two blanks to help you distinguish one from another. However, if the
table or array is directed to a line printer, array entries are separated
by two blanks regardless of the edit code.

MPE/iX 5.0 Documentation