HP 3000 Manuals HP 3000 Manuals
Record Address Type (Column 31)
This field describes the key field used for accessing a file by key.
This field is required for MPE direct files and KSAM and TurboIMAGE files
that are chained files or are accessed by a RAF.
--------------------------------------------------------------------------------------------
| | |
| Column 31 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| A | This file is a KSAM or TurboIMAGE file processed by |
| | alphanumeric or numeric keys. Numeric fields are unpacked |
| | before chaining. |
| | |
| I | This file is a MPE direct, KSAM, or TurboIMAGE file that is |
| | processed by relative record number via chaining or a RAF; |
| | or this is a RAF. |
| | |
| K or P | This file is a KSAM or TurboIMAGE file processed by packed |
| | decimal numeric keys (do not use split chaining fields with |
| | the file); or this is an MPE direct file processed by |
| | relative record number. |
| | |
| | For TurboIMAGE files, the sign of numeric input fields is |
| | changed to C or D. Numeric Result Fields produced by |
| | Calculation Specifications have a C or D sign. Thus, if the |
| | sign of the key field in the TurboIMAGE file is not C or D, |
| | a record-not-found error occurs when chaining to the file. |
| | |
| blank | This is an MPE sequential file or a RAF; or it is an MPE |
| | direct, KSAM or TurboIMAGE file that is processed randomly |
| | by relative record number (the Processing Mode Field, column |
| | 28, is R). |
| | |
--------------------------------------------------------------------------------------------
File Organization/Additional I/O Area (Column 32)
This field specifies how the file is organized (for example, KSAM or
TurboIMAGE) and it lets you select the number of buffers to use.
--------------------------------------------------------------------------------------------
| | |
| Column 32 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| C | This is an input (only) KSAM file. The records are read |
| | chronologically. |
| | |
| D | This is an MPE direct file; assign two buffers to the file. |
| | (This entry is not required; it is provided for |
| | compatibility with other RPG systems.) |
| | |
| I or X | This is a KSAM file. An error occurs at run time if the |
| | file is not a KSAM file. (X provides compatibility with |
| | other RPG systems.) |
| | |
| M | This is a TurboIMAGE file; I, X, or any other entry defaults |
| | to M if IMAGE File Description Continuation lines are |
| | present. |
| | |
| T | This is an ADDROUT file, with two input/output buffers. |
| | |
| 1 - 7 | This is an MPE sequential or direct file; the specified |
| | number of buffers (1-7) are assigned to the file. Accepted |
| | (but not used) for TurboIMAGE files. The default number of |
| | buffers is 2. |
| | |
| 8 or 9, | This is an MPE sequential or direct file; assign two buffers |
| blank | to the file. (Entries 8 and 9 are available for |
| | compatibility with other RPG systems.) |
| | |
--------------------------------------------------------------------------------------------
C (Chronological)
Records that have been marked as deleted (the first two characters
are hexadecimal F's) are not bypassed when a KSAM file is read
chronologically. You must include code in the program to bypass them, if
necessary. You must reorganize the file to drop deleted records.
Table 4-1 summarizes the valid combination of entries for this field,
the Processing Mode Field (column 28) and the Record Address Type Field
(column 32).
Table 4-1. Valid Entries for Columns 28, 31, and 32
----------------------------------------------------------------------------------------------
| | | |
| Processing Mode | Record Address Type | File Organization |
| (Column 28) | (Column 31) | (Column 32) |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| blank (entire file) | blank (key not used) | blank (sequential) |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| blank (entire file) | A (alphanumeric key) | M (TurboIMAGE) |
| L (within limits) | P (packed key) | |
| R (randomly) | I (record number) | |
| | K (record key) | |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| R (randomly) | I (record number) | D (direct) |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| blank (ADDROUT file) | blank (ADDROUT file) | T (ADDROUT file) |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| blank (entire file) | A (alphanumeric key) | C or I (KSAM) |
| L (within limits) | P (packed key) | |
| R (randomly) | I (record number) | |
| | K (record key) | |
| | | |
----------------------------------------------------------------------------------------------
Overflow Indicator (Columns 33-34)
When you use an overflow indicator to enable or suppress the output of
overflow lines to a printer, you must name that overflow indicator using
this field.
Enter an indicator only for line printer files or for disk files
controlled by Line Counter Specifications and ultimately destined to be
printed. Enter just one indicator per file and do assign that indicator
to another file.
--------------------------------------------------------------------------------------------
| | |
| Columns 33-34 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| OA | } |
| OB | } |
| OC | } |
| OD | } |
| OE | }-Assign the named indicator |
| OF | } |
| OG | } |
| OV | } |
| | |
| blank | Do not assign an overflow indicator |
| | |
--------------------------------------------------------------------------------------------
You determine the lines where output begins and ends on a printed page by
entering a Line Counter Specification. The last line on a page is the
overflow line. When the overflow line is reached and no overflow
indicator is assigned to the file, the paper is advanced to top-of-form
and normal output continues. If the overflow line is reached and an
overflow indicator is assigned to the file, one of the following actions
takes place (the overflow indicator is turned ON and OFF by Input and
Calculation Specifications and it is turned ON each time the overflow
line is reached):
1. If the overflow indicator is ON, records associated with the
indicator in the Output Specifications are printed at the bottom
of the current page or at the top of the next page, or both.
Associating the overflow indicator with output records in this
manner is often used to condition the printing of totals and
subtotals at the bottom of a page, or to print headings at the top
of the following page.
2. If the overflow indicator is OFF, normal output continues on the
line following the overflow line. No output records are printed
and the paper is not advanced to top-of-form.
Key Field Starting Location (Columns 35-38)
This field defines the starting location of the key field in a KSAM file.
You can enter the starting location of any one of the possible 16 keys
for the file. This field is required when the file is processed by
record key. If this is a TurboIMAGE file, do not use this field.
--------------------------------------------------------------------------------------------
| | |
| Columns 35-38 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| 1 - 9999 | Starting position of the key field. |
| | |
| blank | A key field is not used. |
| | |
--------------------------------------------------------------------------------------------
Examples
Line 1 in Figure 4-2 shows how to specify sequential processing for
an entire KSAM file. The record with the lowest key is processed first
followed by records with successively higher keys, until end-of-file is
encountered. Columns 15-16 are IS to define the file as an input,
secondary file. Column 28 is blank to request sequential processing and
columns 29-31 are 10P to specify that the key is a ten-digit packed
field. Column 32 is I to indicate that this is a KSAM file. Column 38
is 4 to indicate that the key begins in position 4 of each input record.
Line 2 in Figure 4-2 shows how to specify sequential processing
between limits for a KSAM file. Processing begins with a lower limit key
in a RAF and continues sequentially until the record for the upper limit
key is processed. Columns 15-16 are IP to specify that this is an input
primary file. Column 28 is L to request sequential processing between
limits and columns 30-31 are 6A to define the key as a six-position
alphanumeric field. Column 32 is X (you can also use I) to define this
as a KSAM file. And finally, column 38 is 1 to indicate that the key
field starts in the first position of the KSAM file.
Line 3 in Figure 4-2 shows how to specify random processing for a
KSAM file. (The keys of records to be processed are stored in a RAF.)
Columns 15-16 contain UP to specify that this is an update, primary file.
Column 28 is R to indicate that the file is processed randomly. Columns
30-31 are 2A to specify that the key is a two-position alphanumeric
field. And finally, columns 37-38 contain the key field starting
location for each record, 10.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| 1 FFILE1 IS F 80 10PI 4 |
| 2 FFILE2 IP F 120 40L 6AX 1 |
| 3 FFILE3 UP F 104R 2AI 10 |
| |
| |
___________________________________________________________________________________
Figure 4-2. File Description Specifications for KSAM Files
Extension Code (Column 39)
This field indicates whether File Extension and Line Counter
Specifications are used for this file.
--------------------------------------------------------------------------------------------
| | |
| Column 39 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| E | File Extension Specifications are included for the file. |
| | You must enter File Extension Specifications for RAFs, |
| | chaining files and execution-time tables and arrays. |
| | |
| L | Line Counter Specifications are included for the file. You |
| | must enter a Line Counter Specification if the program uses |
| | overflow sensing. |
| | |
| blank | File Extension and Line Counter Specifications are not used |
| | for the file. If included, they are ignored and a warning |
| | message is displayed. |
| | |
--------------------------------------------------------------------------------------------
Device Class Name (Columns 40-46)
This field associates a device class name or device identifier to the
file. (Device class names and device identifiers are assigned during
system configuration by systems personnel. Contact these individuals for
specific assignments.)
This field is optional for display files, since the terminal is always
used in session mode and the job file in job mode.
--------------------------------------------------------------------------------------------
| | |
| Columns 40-46 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| Device identifier. | Device class name or logical device number of the device on |
| (This can contain up to | which the file resides. |
| seven letters, digits and | |
| special characters.) | |
| | |
| SPECIAL | The file is located on a device that requires a user-defined |
| | external subroutine to handle input/output. Enter the name |
| | of this routine in the Name of Label Exit Field (columns |
| | 54-59) and also furnish the routine itself. |
| | |
| $STDIN | A special device class that should only be used with input |
| | files. |
| | |
| $STDLST | A special device class that should only be used with display |
| | and output. |
| | |
| WORKSTN | A special device class used only with RPG for RPG Screen |
| | Interface (RSI) and VPLUS files (it is not defined by the |
| | operating system as a device class name). The file assigned |
| | to this device can have any legal file name, but must be |
| | defined as an update or combined file (WORKSTNC can have any |
| | file type). The file is usually designated as a demand |
| | file, but may be a primary file. For example, an update |
| | primary file might be used when an application is limited to |
| | a single cycle such as displaying a form, reading data |
| | entered on the form or writing data to a file. For most |
| | applications, you define WORKSTN as an update demand file. |
| | Update demand files are processed by the Calculation |
| | Specification operations READ and EXCPT. |
| | |
| | Assign only one file in a program to WORKSTN. Specify that |
| | the file has variable-length records. |
| | |
| blank | The device class name, DISK. |
| | |
--------------------------------------------------------------------------------------------
Device Identifier
The device identifier can be a device class name or a logical device
number. A device class name names the general type of device used for
the file (the compiler does not verify that it is a valid name). A
logical device number refers to a specific device, such as a particular
printer or tape unit.
While the operating system permits up to eight characters for the device
identifier, RPG permits only seven. If you're using a file that contains
eight characters, enter a :FILE command at run time to equate the file to
the device identifier.
You can override the name in this field by entering a :FILE command with
the DEV= parameter.
Interface Type (Column 47)
This field defines the WORKSTN Interface to be used in the program.
--------------------------------------------------------------------------------------------
| | |
| Column 47 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| C | This is an RPG Screen Interface (RSI) WORKSTN CONSOLE file. |
| | |
| R | This is an RPG Screen Interface (RSI) WORKSTN file. |
| | |
| blank | This is an RPG VPLUS Interface WORKSTN file. |
| | |
--------------------------------------------------------------------------------------------
Interface Control (Columns 48-52)
This field is used for options relating to WORKSTN file interfaces. See
Chapters 10 and 11 for information on how it is used with VPLUS and RPG
Screen Interface (RSI) files, respectively.
Disk Labels (Column 53)
This field indicates if a disk file has user labels and, if they do, how
to process them. You can read and write up to nine user labels.
--------------------------------------------------------------------------------------------
| | |
| Column 53 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| E | Process standard labels. Call a user-written routine to |
| | process a single user label, or bypass the label if the Name |
| | of Label Exit Field (columns 54-59) is blank. |
| | |
| S or blank | Process standard labels. |
| | |
| 2 - 9 | Process standard labels. Call a user-written routine to |
| | process the number of user labels specified by this entry or |
| | bypass them if the Name of Label Exit Field (columns 54 is |
| | blank). |
| | |
--------------------------------------------------------------------------------------------
Name of Label Exit (Columns 54-59)
This field names the user-written routine that processes user labels or
files for SPECIAL devices.
--------------------------------------------------------------------------------------------
| | |
| Columns 54-59 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| Routine name. (This name | The name of the user-written routine that processes user |
| contains up to six | labels or SPECIAL files. |
| characters, beginning | |
| with a letter; the | |
| remaining characters can | |
| be letters or digits.) | |
| | |
| blank | The program does not process user labels or SPECIAL files. |
| | |
--------------------------------------------------------------------------------------------
Although standard labels are not supported for magnetic tape, you can
process them with your own routine. Enter the name of the routine in
this field and leave the Disk Labels Field (column 53) blank. You may
want to use the system intrinsics, FREAD and FWRITE, in the routine to
perform reading and writing. See the MPE/iX Intrinsics Reference Manual
for details about these system intrinsics.
The following lines show how to enter statements in a routine written in
the C language. You can use the system intrinsics, FREADLABEL and
FWRITELABEL, in the procedure body to read and write the labels.
struct file_table {
.
.
};
void exitname (ptr)
struct file_table *ptr;
{
.
.
(procedure body)
.
.
}
exitname is the name of the procedure and ptr is the name of the pointer
that gives the entry in the File Table for the file. (The File Table is
an integer array and is described in the HP RPG Programmer's Guide.)
The following code shows how to enter a C language procedure to process a
SPECIAL file:
struct file_table {
.
.
};
void exitname (ptr,type,returncode);
struct file_table *ptr;
int *type, *returncode;
{
.
.
(procedure body)
.
.
}
NOTE When coding in C, the procedure name must be in lowercase. If
coding in Pascal, FORTRAN, or COBOL, the compilation process will
do any downshifting necessary.
exitname is the name of the procedure and *ptr is the name of the pointer
that gives the entry in the File Table for this file (see the File Table
in the HP RPG Programmer's Guide). TYPE is a pointer to an integer
parameter that contains one of the following: 0 (read a record), 1
(write a record), 2 (close the file), or 3 (open the file). returncode
is a pointer to an integer that passes the outcome of the routine back to
the RPG program. Ensure that it contains one of the following: 0
(normal file-processing occurred), -1 (the procedure encountered an
error), or +1 (the procedure encountered end-of-file while reading the
file).
After reading a record in the routine, place it in the buffer reserved
for it by RPG. The buffer's length is determined by the Block Length
Field (columns 20-23). The word-pointer to this buffer is found in the
26th word of the File Table.
For SPECIAL files with carriage controls specified in the Output
Specification, the FPARAM entry (word 54) in the File Table points to a
four-word integer array containing the skip-before, skip-after,
space-before and space-after options for the current record.
File Addition (Column 66)
This field determines whether records added to an existing sequential
file are written at the beginning (over-writing existing records) or are
appended to the end (following existing records). You may use this field
for KSAM and TurboIMAGE input and update files, though it is not
required.
When you add records to KSAM and TurboIMAGE input and update files, the
records do not have to be in key order nor do they have to be greater
than the highest key in the file.
--------------------------------------------------------------------------------------------
| | |
| Column 66 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| A | Append new records to the end of MPE sequential files; add |
| | new records to KSAM and TurboIMAGE files. |
| | |
| blank | Write new records to the beginning of MPE sequential and |
| | KSAM files; add new records to TurboIMAGE update files. Do |
| | not add records to other update files or to TurboIMAGE |
| | output files. |
| | |
--------------------------------------------------------------------------------------------
A (Append)
When you enter an A in this field, also enter ADD in Record
Addition/Deletion Field (columns 16-18) of the field with the same name
in the Output Specification. Alternatively, instead of entering an A in
this field and ADD in individual record descriptions, you can enter a
:FILE command at run time that includes the ACC=APPEND parameter.
Blank
If you're creating a KSAM file, enter a KEYFL File Description
Continuation line for it.
Extents (Columns 68-69)
This field specifies the number of extents to be used for disk output
files. (For disk input files, the number of extents comes from the disk
file label).
--------------------------------------------------------------------------------------------
| | |
| Columns 68-69 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| 1 - 15 | Create the disk file with this number of extents. |
| (right-justified, | |
| leading zeros are | |
| not required) | |
| | |
| blank | Create the disk file with eight disk extents. |
| | |
--------------------------------------------------------------------------------------------
The operating system manages each disk file as a set of extents. Each
extent is an integral number of contiguous disk sectors. All extents
(except possibly the last) are the same size. You can override the
extents entered in this field with a :FILE command containing the
NUMEXTENTS parameter.
File Conditioner (Columns 71-72)
This field identifies the user indicators that condition this file.
--------------------------------------------------------------------------------------------
| | |
| Columns 71-72 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| U1 - U8 | Use the file only when this user indicator is turned ON. |
| | |
| blank | Use the file unconditionally. |
| | |
--------------------------------------------------------------------------------------------
U1-U8
When you enter a user indicator in this field, it must be ON at run time
to read or write this file. You can enter a user indicator for any file
except display, WORKSTN, and SPECIAL files.
This field is commonly used to assign a user indicator to an optional
file. By turning the user indicator OFF before the program begins, you
can bypass (not process) the file.
You turn user indicators ON and OFF by setting them interactively or by
using USWITCH records or the system Job Control Word (JCW). Although you
can change a user indicator's setting with Input, Calculation, and Output
Specifications, its initial setting determines whether or not the file is
used. If you initialize the user indicator with the system JCW, the
final setting of the indicator is written back to the JCW when the
program ends.
Program Name (Columns 75-80)
This field contains the program name. The format of this field is
discussed in Chapter 2.