HP 3000 Manuals HP 3000 Manuals
The File Description Specification Fields
The fields you can use in the File Description Specification are
described in the sections which follow in this chapter. Each field has a
unique name and occupies specific positions (columns) in the
specification.
Sequence Number (Columns 1-5)
The Sequence Number Field contains the source record sequence number,
described in Chapter 2.
Specification Type (Column 6)
This field contains an F to identify this line as a File Description
Specification.
File Name (Columns 7-14)
This field assigns a name to a file. Use this name throughout the
program to reference the file.
You can process MPE (sequential and direct), KSAM, and TurboIMAGE files
in the program.
For compile-time tables and arrays, use the File Extension Specification
to name them. If the tables and arrays are contained in a file, use
Array/Table File Name Specifications to name the files.
--------------------------------------------------------------------------------------------
| | |
| Columns 7-14 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| File name | Valid file name. (File names contain from one to eight |
| | characters, beginning with a letter. The remaining characters |
| | can be letters or digits. Embedded blanks are not allowed.) |
| | For TurboIMAGE files, this entry is the data set name. |
| | |
--------------------------------------------------------------------------------------------
You can process MPE files sequentially or randomly by relative record
number.
You can process KSAM files both randomly and sequentially using a primary
record key or one of fifteen alternate record keys. You can also process
KSAM files in record number or chronological order. Each KSAM file has a
key file and a data file. The key file contains a record directory
(index) to the data file. KSAM files are analogous to Indexed Sequential
Access Method (ISAM) files on other computer systems. For information
about the structure and details of KSAM files, see the KSAM/3000
Reference Manual.
TurboIMAGE files are databases and their associated data sets and
schemas. The TurboIMAGE subsystem (that interfaces RPG to TurboIMAGE)
consists of a set of library procedures for accessing, modifying, and
reporting database data. For details about TurboIMAGE, see the
TurboIMAGE/iX Database Management System manual. When using TurboIMAGE
files, these restrictions apply:
* Because data is retrieved on a record basis, you must have an
access level equal to or higher than the highest access level
field of the records that you're reading. (See the TurboIMAGE/iX
Database Management System manual for a discussion of access
levels.)
* Because TurboIMAGE files are accessible only at execution time,
you cannot save compile-time or preexecution arrays and tables in
them.
RPG supports all TurboIMAGE input modes (except Re-read) of the DBGET
operation. Since some operations use DBFIND, RPG provides an additional
input mode. It lets you read down a chain until the search key changes.
You can enter a TurboIMAGE data set name in either this field or in a
DSNAME line (see the Data Set Name (DSNAME) Line in the File Description
Continuation line). You must also enter the database name in a Database
Name (IMAGE) File Description Continuation line.
Example
The following names are examples of valid file names.
PRINTER
A
TAPE2
D1234567
LIMBO
File Type (Column 15)
This field indicates how the file is used in the program. This field is
required for all files.
--------------------------------------------------------------------------------------------
| | |
| Column 15 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| C | Combined file |
| | |
| D | Display file |
| | |
| I | Input file |
| | |
| O | Output file |
| | |
| U | Update file |
| | |
--------------------------------------------------------------------------------------------
C (Combined File)
A combined file is used for both input and output. Existing records are
read and records that are written are appended to the end of the file.
Since input records remain unchanged, combined files are ideal for
applications that accumulate data records.
When you use a combined file, enter Input and Output Specifications for
it. The input and output records definitions can be different. The
input definition determines the data that is read and the output record
definition determines the data that is written.
Do not define KSAM or TurboIMAGE files as combined files.
D (Display File)
When using display files, you must enter DSPLY and DSPLM Calculation
Specifications to read data from and to write data to them.
Display files use $STDLIST. If the program is running in session mode,
$STDLIST is the user terminal; in job mode, it is the system console.
You cannot change these assignments; MPE FILE equations are ignored for
display files.
Do not enter Input or Output Specifications for display files and do not
define KSAM and TurboIMAGE files as display files.
I (Input File)
Input files contain data that is read by the program. An input file can
reside on tape or disk. Input files include preexecution time (but not
compile-time) table and array files and Record Address Files (RAFs).
You must include one or more Input Specifications for each input file.
If the input file contains a preexecution-time table or array or is a
Record Address File, enter a File Extension Specification for it.
O (Output File)
Output files are used to write data to tape, disk, a printer or a
terminal. They cannot be used to read data. Output files can contain
preexecution-time tables and arrays.
Enter one or more Output Specifications for each output file. If you're
using preexecution-time table and array output files, you must include
File Extension Specifications for them. If you're creating a KSAM file,
include a KEYFL File Description Continuation line to define its key file
name and build parameters.
U (Update File)
Records in an update file can be read and updated. When a record is
updated, it is read, modified, and written back to the same location in
the file overwriting the old record. Update files can reside on disk or
on any device with the device class name SPECIAL (see the Device Class
Name Field, columns 40-46).
If you use update files, include Input and Output Specifications for
them. The record definitions in the Input and Output Specifications
should be the same.
File Designation (Column 16)
This field indicates the function of a file. You can use it for input,
update, and combined files (see the File Type Field, column 15) and for
output files used for chaining.
--------------------------------------------------------------------------------------------
| | |
| Column 16 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| C | Chained file |
| | |
| D | Demand file |
| | |
| F | Full procedural file |
| | |
| P | Primary file |
| | |
| R | Record Address File (input only) |
| | |
| S | Secondary file |
| | |
| T | Preexecution-time table/array file (input only) |
| | |
| blank | Sequential output or display file |
| | |
--------------------------------------------------------------------------------------------
C (Chained File)
Chained files are input, output, and update disk files that are accessed
randomly via Input Specification chaining fields or that are read
directly by the Calculation Specification CHAIN operation. When you use
CHAIN, input and update files are read and output files are written. You
can write update files using Output Specifications or the Calculation
Specification EXCPT operation.
Chained files cannot reside on devices with the device class name
SPECIAL.
D (Demand File)
This is an input or update file that is processed sequentially by a
Calculation Specification READ operation. For input demand files, use
only the READ operation. For update demand files, use the READ operation
for input and normal indicator processing for output.
F (Full Procedural File)
A full procedural file is an input or update file that can be processed
both sequentially and randomly by the same key field.[REV DEL] You can
read records from a full procedural file using both the Calculation
Specification CHAIN and READ operations. For example, you can use CHAIN
to randomly read a record, then use READ to sequentially retrieve records
from that point forward in the file.[REV BEG] Specifying a file as full
procedural is easier than specifying both a chained and a sequential
file, and then equating them with two DSNAME File Continuation lines.[REV
END]
P (Primary File)
Primary files are the main files used for input. Use only one primary
file in a program. A primary file can have an input, update, or combined
file type. When there is only one input file, it is usually the primary
file. However, it can also be a chained or demand file. If there are
other input files in the program, the primary file is processed first and
it controls the order in which the others are processed. See the
Matching/Chaining Fields Field (columns 61-62) of the Input Specification
for details about how primary files are processed during file matching.
R (Record Address File)
This is a sequential input file containing record numbers or keys. The
record numbers or keys select records in another file. You can use
Record Address Files (RAFs) to access records in KSAM and TurboIMAGE
files.
Use only one RAF in a program and include a File Extension Specification
for it. Do not enter Input Specifications for it or define it with the
device class name SPECIAL (see the Device Class Name Field, columns
40-46).
You can create a RAF using any standard word processor or editor. The
way that you enter record numbers or keys into lines in the RAF depends
on how you're using them to access records.
If you want to use the RAF to access records sequentially within record
number or key limits, enter a lower limit record number or key into the
first position of a RAF line. Immediately follow it with the record
number or key for the upper limit, with no intervening spaces. Enter as
many lines as necessary. If you're entering record keys and the ones
that you're accessing are in packed decimal format, enter the RAF keys in
packed decimal format also. When a RAF is used to process a KSAM file
within limits, processing begins with the lower limit record (or if it
does not exist, the next higher record in sequence) and proceeds
sequentially
until a record that matches or exceeds the upper limit is read or until
end-of-file is encountered in the KSAM file. Since you can enter any
number of upper and lower limit lines in a RAF, you can process the same
records more than once, if necessary.
If you want to use the RAF to access records randomly, enter a record key
in the first position of a RAF line. You can enter more than one key per
line but do not separate them with spaces (spaces causes RPG to read the
next RAF line). The number of keys per RAF line can vary, but the length
of the keys must be the same. Keys in a RAF must have the same format
and length as the keys in the file you're accessing. When you use a RAF
to process a KSAM file randomly, RPG retrieves each key in the RAF and
accesses the corresponding record in the KSAM file. Processing continues
until end-of-file is encountered in the RAF.
See the HP RPG Programmer's Guide for examples of how to process a KSAM
file sequentially and randomly using a RAF.
S (Secondary File)
You use a secondary file in programs that have more than one input file,
to indicate that it is not the most important file in the input
processing sequence. Secondary files can have input, update, or combined
file types. You can enter as many secondary files in a program as you
need. If you're not using matching files, secondary files are processed
in the order in which you enter their File Description Specifications.
T (Preexecution Array/Table File)
This file contains one or more array or table. They are read into memory
before the program begins execution. If you use preexecution
tables/arrays, include File Extension Specifications for them.
End-of-File (Column 17)
For an input, update, or combined file, this field determines whether the
program can end before all records in the file are processed. Do not use
this field for demand, chained, or preexecution-time array/table files.
--------------------------------------------------------------------------------------------
| | |
| Column 17 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| E | The program cannot end until it reads all records from this |
| | file. |
| | |
| blank | If other files contain an E in this field, the program can end |
| | whether or not it reads all records from this file. |
| | |
| | If this field is blank for input, update, and combined files, |
| | the program ends only when it reads all records from all of |
| | these files. |
| | |
--------------------------------------------------------------------------------------------
Use this field for files that you want to process in their entirety. For
example, when producing a student attendance report for a certain time
period, you need to read all student records in a master student
enrollment file, those that have attendance transactions for the period
and those that do not. You would enter an E in this field for the master
student enrollment file and leave this field blank for the attendance
transaction file.
Input Sequence (Column 18)
This field determines whether matching files are sequence-checked. Use
this field only for update, combined, primary, and secondary input files.
This field is ignored if you do not use matching fields in the Input
Specification.
--------------------------------------------------------------------------------------------
| | |
| Column 18 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| A or blank | If this is a matching file, check the records for ascending |
| | sequence. |
| | |
| D | If this is a matching file, check the records for descending |
| | sequence. |
| | |
--------------------------------------------------------------------------------------------
The Matching/Chaining Fields (columns 61-62) of the Input Specification
let you compare two or more input, update, or combined files to determine
whether their records match. Records in all matching files must be in
the same sequence (ascending or descending). When a record is out of
sequence, an error message is printed. Depending on the entry in the
Error Response Field (columns 56-71) of the Header Specification, the
program either bypasses the record and continues, or it terminates.
The ASCII collating sequence is used for sequence-checking unless you
define an alternate collating sequence or request the EBCDIC collating
sequence (see Alternate Collating Sequence, column 26, and EBCDIC
Zone/Digit Tests, column 39, in the Header Specification).
Record Format (Column 19)
This field specifies whether records in the file are fixed-length or
variable-length. This field is required.
--------------------------------------------------------------------------------------------
| | |
| Column 19 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| F | Fixed-length record format. Use this format for all printer and |
| | TurboIMAGE files. |
| | |
| V | Variable-length record format. Use this format for all WORKSTN, |
| | WORKSTN and WORKSTNC files. |
| | |
--------------------------------------------------------------------------------------------
Block Length (Columns 20-23)
This field determines the length of the blocks (physical groups of
records) read from or written to tape files or written to disk files.
This field is ignored for disk input files; records are blocked according
to the blocking information in the file label. It is also ignored for
line printer and terminal files. In these cases, the block length is
determined by the device type. The block length for a line printer file
is one line (either 80 or 132 characters).
--------------------------------------------------------------------------------------------
| | |
| Columns 20-23 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| 1 - 9999 | For tape and disk files, the length of the block in characters. |
| (right-justified, | |
| leading zeros are | |
| not required) | |
| | |
| blank | No blocking; the block and logical record lengths are identical. |
| | |
--------------------------------------------------------------------------------------------
Data is read from files, and written to them, in units known as blocks.
A block is transferred as a unit between the file's device and main
memory. For tape or disk files, a block can consist of one or more
logical records. For instance, a block can consist of 2 records or 256
records. Blocking for tape files reduces execution time and the amount
of space required for the file on tape.
Be sure to enter the logical length of records in the Logical Record
Length Field (columns 24-27). RPG uses the block and logical record
lengths to determine the number of records in each block. This number is
called the blocking factor and is always an integer.
By using the :FILE command with the REC parameter you can enter a
different block length at run time to override the block length that you
enter in this field (see the MPE/iX Commands Reference Manual). RPG does
all the input/output for you when using a file equation to override
compile-time options. For example, do not specify NOBUF in your file
equation because you cannot do your own buffering.
Logical Record Length (Columns 24-27)
This field specifies the length of logical records in the file. This
field is required.
--------------------------------------------------------------------------------------------
| | |
| Columns 24-27 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| 1 - 9999 | For fixed-length records, enter the length of the record. For |
| (right-justified, | variable-length records, enter the length of the longest record |
| leading zeros are | in the file. |
| not required) | |
| | |
--------------------------------------------------------------------------------------------
See the Record Length Check Field (column 49) of the Header Specification
for information on how record length errors are handled at run time.
Processing Mode (Column 28)
This field determines whether records are processed sequentially from
beginning to end, sequentially between specified limits or randomly.
--------------------------------------------------------------------------------------------
| | |
| Column 28 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| L | Sequential processing between limits. |
| | |
| R | Random processing (by relative record number or record key). |
| | |
| blank | Sequential processing for the entire file. |
| | |
--------------------------------------------------------------------------------------------
L (Sequential Processing Between Limits)
You can process portions of KSAM files by processing them sequentially
within limits. You supply the limits (boundaries) by entering the record
key values for them. You can specify the lower limit using the
Calculation Specification SETLL operation or you can enter sets of lower
and upper limits in a RAF. Record keys do not have to match existing keys
in the file. If a record for the lower limit key does not exist, the
record with the next higher key is selected.
R (Random Processing)
You can access records directly in this mode; you do have to pass over
records in order to Locate the records you want to process. Depending on
the file organization (see the File Organization/Additional I/O Area
Field, column 32), you can access a record randomly by supplying either a
relative record number or a record key.
You can access KSAM, TurboIMAGE, and MPE direct files by relative record
number. The File Organization/Additional I/O Area Field (column 32) must
be blank for these files or contain a digit 1-7 or the letter D. You can
use an ADDROUT file, the Calculation Specification CHAIN operation or a
chaining file to supply the relative record numbers.
A relative record number is a series of digits that identifies the
position of a record relative to the first record in the file. For
TurboIMAGE files, the first record is Record 1. For KSAM files, the
first record is either Record 0 or 1, depending on which one you choose
when you create the file. For all other files, the first record is
Record 0 (for example, record 0 is the first record in the file). You
can change the beginning relative record number to 1 by entering a 1 in
the Record Number Adjust Field (column 22) of the Header Specification.
You can use an ADDROUT file for storing relative record numbers. An
ADDROUT file is a special type of RAF that contains four-character
relative record numbers in fixed-length, binary records. ADDROUT files
are created by XSORT (see the RPG Utilities Reference Manual). When
using an ADDROUT or chaining file, RPG reads relative record numbers
until the end-of-file in ADDROUT is reached.
You can access KSAM and TurboIMAGE files by record key. (A key is a
string of characters that is used for finding individual records in a
file; the string is matched with a field in the record.) To access a
file by record key, the File Organization/Additional I/O Area Field
(column 32) must contain I, M, or X. You can use a RAF or a chaining file
to supply key values.
KSAM files have key files containing indexes that let you access records
directly. KSAM indexes are updated automatically when you process the
file. Record keys can be alphanumeric, packed, or unpacked numeric
fields. Define the key field type using the Record Address Type Field
(column 31). Specify the length of the key field and its starting
position using the Record Address or Key Field Length Field (columns
29-30) and the Key Field Starting Location Field (columns 35-38).
Blank (Sequential Processing)
Sequential files are processed from beginning to end. If this is
an MPE file, an ADDROUT file or in input KSAM file (the File
Organization/Additional I/O Area Field, column 32, is blank, a digit 1-7,
T, or C), records are processed in their physical order. If this is a
KSAM or TurboIMAGE file (the File Organization/Additional I/O Area Field
is I, M, or X), records are processed in key sequence.
Record Address or Key Field Length (Columns 29-30)
If this file is an input RAF, specify the length of the relative record
numbers. If this is an input KSAM or TurboIMAGE file, enter the number
of positions occupied by the record key.
--------------------------------------------------------------------------------------------
| | |
| Columns 29-30 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| 1 - 99 | For a RAF, enter the length (in characters) of the relative |
| (right-justified, | record number or key field in the RAF; for an ADDROUT file, |
| leading zeros are | enter 4. |
| not required) | |
| | |
| | For a KSAM or TurboIMAGE file, enter the length of the key |
| | field (the maximum key length is 99). If this is an input |
| | file controlled by a RAF, use the same key length as the |
| | RAF. |
| | |
| blank | This is not a RAF, KSAM, or TurboIMAGE file. Or, this is a |
| | KSAM or MPE file controlled by an ADDROUT RAF. |
| | |
--------------------------------------------------------------------------------------------