HP 3000 Manuals HP 3000 Manuals
The File Description Continuation Line
When you use KSAM, TurboIMAGE, or WORKSTN files in a program, you must
enter one or more File Description Continuation lines for them. The
Continuation lines give additional information about the files, such as
file locking requirements and database and data set names.
The remaining sections of this chapter give details about the
Continuation lines that you can use. There are four different types of
Continuation lines, each distinguished by the fields located in columns
54-74. These lines are summarized below:
* General lines.
This line contains fields that specify error-handling procedures,
exit routines, file locking, ASCII/EBCDIC conversion and partial
field translation for a file. Enter as many of these lines as
required for the file.
* File-sharing line.
This line contains fields that associate more than one name to a
single KSAM or TurboIMAGE file. Enter one of these lines per
file.
* Database lines.
This line contains fields that define KSAM files, TurboIMAGE
databases, and TurboIMAGE data sets. Enter as many of these lines
as required for the file.
* WORKSTN interface lines.
This line contains fields that name the files and fields
associated with the RPG Screen and VPLUS Interfaces. Enter as
many of these lines as necessary for the file.
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.
Leave columns 7-19 and 52 of each Continuation line blank.
Long Name Option Target (Columns 20-51)
This field is a longer alternative to the Option Target Field (columns
60-74). Use it only in DSNAME and ITEM Continuation lines when you need
to enter more than 15 characters for a file or key name. Enter up to 16
characters in columns 20-35. Also enter an asterisk in column 60 to
signal that you're using this field instead of the Option Target Field
for the file or key name.
Continuation Code (Column 53)
This field identifies this as a File Description Continuation line. It
is required.
--------------------------------------------------------------------------------------------
| | |
| Column 53 | Description |
| | |
--------------------------------------------------------------------------------------------
| | |
| K | This is a File Description Continuation line. |
| | |
--------------------------------------------------------------------------------------------
General Fields (Columns 54-74)
There are two general fields: the Option Type Field (columns 54-59) and
the Option Target Field (columns 60-65). The entries in the Option Type
Field determines the values that you can enter in the Option Target
Field. For example, if you enter ERROR in the Option Type Field, you
must enter an error routine name in the Option Target Field. The Option
Type Field is described in detail in the pages which follow.
-------------------------------------------------------------------------------------------------
| | | | |
| Option Type | Description | Option Target | Description |
| (Columns 54-59) | | (Columns 60-65) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| ASCII | The file is in ASCII | (Not applicable) | (Not applicable) |
| | format. (This entry | | |
| | is not required; it | | |
| | is provided for | | |
| | compatibility with | | |
| | other RPG compilers.) | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| BUFCHK | Enable/Disable the | N (in column 60) | Disables Current Data |
| | buffer integrity | | Checking (CDC). A |
| | checking options CDC, | | blank enables CDC. |
| | NRC, and UPC. | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| | | N (in column 61) | Disables No-Read |
| | | | Checking (NRC). A |
| | | | blank enables NRC. |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| | | N (in column 62) | Disables |
| | | | Update-Protect |
| | | | Checking (UPC). A |
| | | | blank enables UPC. |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| BYPASS | If an input/output | Field name.(This can | The name of the error |
| | error occurs, bypass | contain up to six | counter field. It |
| | the current logical | characters, beginning | must be a five-digit |
| | record and increment | with a letter or @, | numeric field with |
| | the error counter | $, or #; the | zero decimal |
| | named in the Option | remaining characters | positions. |
| | Target Field by one. | can be letters or | |
| | | digits.) | |
| | | | |
-------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------
| | | | |
| Option Type | Description | Option Target | Description |
| (Columns 54-59) | | (Columns 60-65) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| EBCDIC | The file is in EBCDIC | P (in column 60) | A partial field |
| | format. If it is an | | translation is |
| | input file, it is | | performed; input and |
| | translated into ASCII | | output packed decimal |
| | before processing. | | and binary fields are |
| | If it is an output | | not translated. |
| | file, it is | | |
| | translated into | | |
| | EBCDIC before being | | |
| | written. | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| EBCDIK | The file is in EBCDIK | P (in column 60) | A partial field |
| | format. If it is an | | translation is |
| | input file, it is | | performed; input and |
| | translated to JIS | | output packed decimal |
| | before processing. | | and binary fields are |
| | If it is an output | | not translated. |
| | file, it is | | |
| | translated into | | |
| | EBCDIK before being | | |
| | written. | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| ERROR | If an input/output | Routine name. (This | The name of the |
| | error occurs, | can contain up to six | routine that handles |
| | transfer control to | characters, beginning | error processing. |
| | the user-written | with a letter; the | |
| | routine (named in the | remaining characters | |
| | Option Target Field) | can be letters or | |
| | to handle the error. | digits.) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| FATAL | Provide user control | Enter 0-5 in column | See H specs columns |
| | over run-time fatal | 60. | 56-71 for a |
| | file errors. | | description of the |
| | | | response. |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| LOCK | Lock this file during | (Not applicable) | (Not applicable) |
| | input and output | | |
| | operations. (LOCK | | |
| | applies only to KSAM | | |
| | and MPE files.) | | |
| | | | |
-------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------
| | | | |
| Option Type | Description | Option Target | Description |
| (Columns 54-59) | | (Columns 60-65) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| NOLOCK | Open this file so | (Not applicable) | (Not applicable) |
| | that concurrent users | | |
| | of the file can use | | |
| | LOCK. This option | | |
| | does not dynamically | | |
| | lock and unlock the | | |
| | file. (NOLOCK | | |
| | applies only to KSAM | | |
| | and MPE files.) | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| PARTTR | When you use file | (Not applicable) | (Not applicable) |
| | translation records | | |
| | to translate a record | | |
| | containing packed | | |
| | decimal or binary | | |
| | fields, those fields | | |
| | are not translated. | | |
| | (A partial file | | |
| | translation occurs.) | | |
| | If this is an EBCDIC | | |
| | input file, use the | | |
| | EBCDIC entry. | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| RDEXIT | Each time a record is | Routine name. (This | The name of the |
| | read, transfer | can contain up to six | routine that retains |
| | control to a | characters, beginning | or bypasses the |
| | user-written routine | with a letter; the | record. |
| | (named in the Option | remaining characters | |
| | Target Field) that | can be letters or | |
| | retains or bypasses | digits.) | |
| | the record. | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| RDSEQ | After adding records | (Not applicable) | (Not applicable) |
| | to a sequential | | |
| | chained file, | | |
| | reposition the record | | |
| | pointer to the next | | |
| | sequential record; do | | |
| | not leave the record | | |
| | pointer positioned to | | |
| | the record that was | | |
| | added. | | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| blank | Options not used. | (Not applicable) | (Not applicable) |
| | | | |
-------------------------------------------------------------------------------------------------
Option Type (Columns 54-59)
The following paragraphs describe certain options that you can enter in
this field:
BUFCHK
If the Option Target Field contains a value other than blank or N, a
compiler warning (2086W, 2087W, or 2089W) is displayed and the
corresponding option is enabled. If you do not enter a BUFCHK
Continuation line, the buffer option is determined by the BUFCHK Defaults
Field (column 28) of the Header Specification. The buffer integrity
checking options are described in the following paragraphs.
You may want to use Current Data Checking (CDC) when two or more files
are equated to the same physical file via the MPE FILE command. CDC
performs special input/output processing to ensure that all data buffers
have current data. Current Data Checking is available only for KSAM and
MPE files that have the locking facility enabled (the LOCK or NOLOCK
Continuation lines are used).
You should use Current Data Checking when the same physical file is an
update, output, or update/output file in the same program. When the
physical file is equated to two or more files in the program using an MPE
FILE equation, multiple access paths to the physical file are created.
Since the operating system maintains separate data buffers for each of
these access paths, output, and update operations may not be
synchronized. Writing data from one buffer to the physical file can
inadvertently overlay data (including records and record pointers)
previously written from another buffer. This can result in corruption of
the KSAM or MPE file.
No-Read Checking (NRC) ensures that output operations for the first
record in an update file are executed only after the record is read.
Update-Protect Checking (UPC) ensures that the appropriate input record
is placed in the file buffer before update operations (in Output
Specifications) are performed on it. UPC prevents the following
situations:
* Two or more consecutive update operations with no new input.
* For an update file having records added to it (the File Addition
Field (column 66) of the File Description Specification is A), the
interference of add and update operations for the same file. For
example, since add and update operations share the same buffer, an
add operation may "dirty" the buffer as follows: an update
operation reads the record to be updated; the add operation adds a
record to the file; the update operation formats the added record,
rather than the original record, and writes it. If Update-Protect
Checking is not specified for this file, this compiler message
(2081I) results:
FOR UPDATE-ADD FILES WITHOUT 'UPDATE-PROTECT CHECK', ENSURE THAT
NO UPDATE IS INTERRUPTED BY AN ADD.
When you specify UPC, and a buffer conflict occurs, the program aborts
with a NO RECORD FOUND run-time error and this message is displayed:
Attempted update on same record, or on intervening Add record.
ERROR, RDEXIT
The ERROR and RDEXIT routines must have a procedure head and body format
similar to that shown below. The procedure shown below is written in the
C language:
struct file_table {
.
.
};
void exitname (ptr,returncode);
struct file_table *ptr;
int *returncode;
{
.
.
(procedure body)
.
.
}
The procedure name is exitname. The pointer to the pertinent File Table
(File Table formats are discussed in the HP RPG/iX Programmer's Guide)
for this file is ptr. 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 (continue the program without rewriting
the record), 1 (bypass or rewrite the record), or 2 (abort the program).
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.
FATAL
You may use the FATAL continuation record option to pre-program an error
response to RPG run-time error number one, FATAL FILE ERROR. The error
responses allowed are 0-5, exactly the same options that are available
for other run-time errors. If you specify FATAL, but put an invalid
error response in column 60 or leave column 60 blank, RPG will default
your error response to 0 (=CONTINUE). Note that this is different from
not specifying FATAL at all, in which case RPG would default fatal file
errors to error response 5 (=IMMEDIATE TERMINATION WITH DUMP).
The FATAL option is intended go give control to the RPG user at run-time
in the event of a FATAL FILE ERROR. You must, therefore, specify a STATUS
array to go with it. You would do this on a following continuation
record, using the same syntax as the STATUS array for IMAGE files. Once
a fatal file error occurs, RPG will post the error number from KSAM, MPE,
or IMAGE to the first word of your status array. You then have the
capability to check this word in your calculation specs, and perhaps take
a variety of actions depending on the particular file error.
RPG will also post an "F" to the *ERROR field when a fatal file error
occurs. You may wish to use this feature in conjunction with the STATUS
array in your calculation specifications.
Note that the FATAL option is effective once your program enters the RPG
cycle and not during RPG initialization time. FATAL allows you to catch
and take action on file errors that occur once a program has begun
execution (for example, I/O errors, IMAGE errors, etc.). If RPG cannot
find or build a file at initialization time, it is assumed that the
safest course to take is to abort the program, as there may be data
integrity issues related to running with some of the expected files open.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| H |
| FINPUTA IP F 80 DISK |
| FOUT2 O F 80 DISK |
| F KFATAL 0 |
| F KSTATUSSA |
| INPUTA NS |
| I 2 6 FLD1 |
| C EXCPT |
| C *ERROR DSPLY |
| C SA,1 DSPLY |
| OOUT2 E 20 "REC OUT" |
| |
| |
___________________________________________________________________________________
Figure 4-3. RPG Program Using the KFATAL Option
LOCK
LOCK obtains exclusive access to a file during input/output operations.
Use LOCK for programs that run concurrently and that update the same
file. LOCK prevents simultaneous update of the same records in the file.
When LOCK is used, RPG opens the file with the dynamic locking facility
enabled (to allow the file to be shared with other programs that enable
locking) and performs automatic locking and unlocking each time a record
is accessed as follows:
* It locks an input file before reading a record from it and unlocks
it after reading the record.
* It locks an output file before writing a record and unlocks it
after writing the record.
* It locks an update file before reading a record and unlocks it
after the record is updated or before it locks and reads the file
again.
If an update file has been locked and read but not updated (and
thus not unlocked), RPG unlocks the file when the program next
attempts to lock and read from it. This allows other programs,
which may be waiting for the file, to lock and access it.
When you use a DSNAME Continuation line (see the File-Sharing Fields
(columns 54-74)) to link files to one physical file, enter one LOCK
Continuation line following the first file that uses a DSNAME
Continuation line (the first DSNAME line determines how the file is
opened at run time and whether or not the dynamic locking facility is
enabled). If you enter a LOCK Continuation line for some other file in
the same DSNAME group, the following run-time error occurs:
FATAL FILE ERROR, FILENAME= (Name of file)
KLOCK/KNOLOCK NOT SPECIFIED FOR THIS FILE TO
ENABLE LOCKING FOR OTHER DSNAME'D FILE ACCESS
NOLOCK
NOLOCK opens the file with the dynamic locking facility enabled (to allow
other programs that enable locking to share the file), but does not lock
and unlock the file (as described for the LOCK option above). If you
want to lock and unlock the file, you must do so manually by using the
LOCK and UNLCK Calculation Specification operations.
When you use a DSNAME Continuation line (see the File-Sharing Fields,
columns 54-74) to link files to another physical file, enter one NOLOCK
Continuation line following the first file that uses a DSNAME
Continuation line (the first DSNAME line determines how the file is
opened at run time and whether or not the dynamic locking facility is
enabled). If you enter a NOLOCK Continuation line for some other file in
the same DSNAME group, the following run-time error occurs:
FATAL FILE ERROR, FILENAME= (Name of file)
KLOCK/KNOLOCK NOT SPECIFIED FOR THIS FILE TO
ENABLE LOCKING FOR OTHER DSNAME'D FILE ACCESS
File-Sharing Fields (Columns 54-74)
The File-Sharing Fields in the Continuation line let you assign the same
file name to two or more files. You can then process the same physical
file more than one way in the program. For instance, you can process it
randomly by relative record number and sequentially by key. To do this,
enter two File Description Specifications in the program and specify the
appropriate type of access for each. Then, equate the file names in one
of the following ways:
* Equate the file names by using an MPE FILE command. When you do
this, RPG treats the files as separate entities, each having its
own unique file number (assigned by the operating system) and
current record pointer.
* Use a DSNAME Continuation line to equate the file names (see the
DSNAME Field below). Enter a DSNAME line for each file to be
equated. RPG opens one logical file (identified by one file
number), to which both names apply. The file is opened once and
all references to it use the same file number. The program can
access the file using different access methods.
-------------------------------------------------------------------------------------------------
| | | | |
| DSNAME | Description | File Name | Description |
| (Columns 54-59) | | (Columns 60-74) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| DSNAME | This is a DSNAME line | Qualified file name. | Override the file |
| | for file sharing. | (This can contain | name specified in |
| | | from one to 15 | columns 7-14 of the |
| | | characters, beginning | File Description |
| | | with a letter. The | Specification when |
| | | remaining characters | opening the file; |
| | | can be letters or | share the file number |
| | | digits. Embedded | with other files |
| | | blanks are not | having the same |
| | | allowed.) | DSNAME file name. |
| | | | (These files access |
| | | | the same same logical |
| | | | file.) |
| | | | |
| DSNAME | This is a DSNAME line | * (in column 60) | Use the file name (up |
| | for file sharing. | | to 16 characters) |
| | | | specified in columns |
| | | | 20-35 of the Long |
| | | | Name Option Target |
| | | | Field. |
| | | | |
-------------------------------------------------------------------------------------------------
When equating files using DSNAME, be sure you understand the affects of
different access methods on the current record pointer (that keeps track
of file accesses). For instance, a program cannot read a KSAM file
sequentially by key and then chain to it by key without altering the
sequential current record pointer. A program can read a KSAM file
sequentially and chain to it by relative record number without affecting
the sequential current record pointer. Table 4-2 shows how the type of
access affects the setting of the current record pointer. (TurboIMAGE
files are the same except that direct access by relative record number
does affect the current record pointer.)
Table 4-2. How Access Type for KSAM Files Affects the Record Pointer
-----------------------------------------------------------------------------------------------
| | | |
| Input/Output Type | Current Record Pointer | Next Update Applies To |
| | Setting | |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Sequential read | Record read | Record read |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Random access by relative | Not affected | Record read |
| record number | | |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Random access by record key | Record read | Record read |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Write | Record written | Record written |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Update | Record updated | Record previously updated; |
| | | each successive update updates|
| | | the same record. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Delete | Next key sequential record | Next record |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Add | Not affected | Record added |
| | | |
-----------------------------------------------------------------------------------------------
Because of the nature of the RPG logic cycle, special care must be used
when processing DSNAMEd files, particularly when one or more of them are
used as primary or secondary files. During the initialization phase, the
first record of the primary file and each secondary file is read into its
local buffer. Processing then proceeds with the primary file, followed
by the secondary files in the order given in the F-specifications. For
example, assume we have a program with four files; A, B, C, and D. A is
the input primary, B and C are input secondary (in that order in the F
specifications), and D is input chained, DSNAMEd to C. The files are then
processed by the logic cycle in order A, B, C. If either A or B use a
field to chain to D, the record pointer is altered to C, since C and D
share the same MPE file number. When it is time to process C as
the second secondary, we will obtain its first record (from the
initialization phase), followed by those records starting with the last
setting of the record pointer. This may be avoided for non-IMAGE files
by using MPE file equations to equate the files rather than DSNAMEing
them, or by naming all files to be processed sequentially earlier in F
specifications, before their use as a chained file.
Another approach when using DSNAME with an IMAGE data set is to enter an
IMAGE and a DSNAME Continuation line for each file accessing the same
data set. Enter the IMAGE lines with different dummy DB names, and the
DSNAME lines with the name of the appropriate data set. Then use file
equations to equate all the dummy DB names to the actual database name.
A separate DBOPEN is executed for each access path to the database and
data set and separate current record pointers are established.
Example
Figure 4-4 shows how to access a KSAM file two different ways. FILEA
is a KSAM file that is processed sequentially by key (see line 1). FILEB
is the same physical KSAM file but is defined as a separate file (see
line 3). FILEB is processed randomly by relative record number. After
each File Description Specification, include a DSNAME Continuation line
that associates the same DSNAME file name to each file. In this example,
the DSNAME file name is FILEK (lines 2 and 4). All file descriptions
followed by a DSNAME record for FILEK share the same file number.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| 1 FFILEA IP F 80 AI 10 DISK |
| 2 F KDSNAMEFILEK |
| 3 FFILEB IC F 80R II DISK |
| 4 F KDSNAMEFILEK |
| |
| |
___________________________________________________________________________________
Figure 4-4. KSAM File Sharing
Database Fields (Columns 54-74)
The Database Fields require several Continuation lines. They give
information about how KSAM files are locked and accessed. For TurboIMAGE
databases, they give the database name, locking and access information.
Each of the Continuation lines are described in the sections which follow
and are listed below along with a brief description:
* Database Name (IMAGE) Line
Used to name TurboIMAGE databases.
* Item Name (ITEM) Line
Identifies TurboIMAGE databases key fields.
* Password (LEVEL) Line
Designates passwords for TurboIMAGE databases.
* Data Set (DSNAME) Line
Identifies the TurboIMAGE data sets to be processed.
* Input/Output Status Array (STATUS) Line
Allows user-error handling with TurboIMAGE databases.
* Key File Name (KEYFL) Line
Identifies KSAM key files and specifies KSAM duplicate key
processing.
Database Name (IMAGE) Line.
This line names TurboIMAGE databases and specifies how they are accessed.
It also specifies whether the database or data set is used concurrently
by other programs and whether locking is used.
-----------------------------------------------------------------------------------------------
| | | |
| Column | Value | Description |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Record Type: | IMAGE | This is a TurboIMAGE database name |
| (columns 54-50) | | line. |
| | | |
| Database Name: | Database name | Name of the database being |
| (columns 60-65) | | accessed. The name can be six |
| | | characters long. |
| | | |
| Open Mode: | B | Read/Write Shared Mode. The |
| (column 66) | | database is locked for the |
| | | duration of the program. |
| | | |
| | S | Read/Write Shared Mode. The data |
| | | set is locked for the duration of |
| | | the program. |
| | | |
| | 1 | Read/Write Shared Mode. The |
| | | database is locked and unlocked |
| | | whenever a record is accessed in |
| | | it. |
| | | |
| | 9 | Read/Write Shared Mode. The data |
| | | set is locked and unlocked |
| | | whenever a record is accessed in |
| | | it. |
| | | |
| | R | Read/Write Shared Mode. The data |
| | | record is locked and unlocked |
| | | whenever it is accessed. |
| | | |
| | L | Read/Write Shared Mode. Enable |
| | | dynamic locking for the database. |
| | | |
| | 2 | Update Shared Mode. |
| | | |
| | 3 or blank | Exclusive Mode. |
| | | |
| | 4 | Semi-exclusive Modify Access Mode. |
| | | |
| | 5 | Shared Read Access Mode |
| | | (concurrent with Open Modes B, S, |
| | | 1, 9, R, and L). |
| | | |
| | 6 | Shared Read Access Mode |
| | | (concurrent with Open Mode 4). |
| | | |
| | 7 | Exclusive Read Access Mode. |
| | | |
| | 8 | Shared Read Access Mode |
| | | (concurrent with Open Mode 6). |
| | | |
-----------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------
| | | |
| Column | Value | Description |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Input/Output Mode: | 2 | Serial read. Records are read in |
| (column 67) | | their physical sequence (not key |
| | | sequence). |
| | | |
| | 3 | Backward serial read (the reverse |
| | | of mode 2). |
| | | |
| | 4 | Directed read. Records are read |
| | | by relative record numbers. |
| | | |
| | 5 | Chained read. |
| | | |
| | 6 | Backward chained read. |
| | | |
| | 7 | Calculated read. |
| | | |
| | 8 | Primary calculated read. |
| | | |
| | C | Chained sequential read. |
| | | |
| | R | Backward chained sequential read. |
| | | |
| | blank | Write, Output File. Data is |
| | | written to the output file. |
| | | |
-----------------------------------------------------------------------------------------------
Open Mode Field (Column 66)
Open Modes 2-8 are equivalent to the MPE open modes 2-8. Open Modes B,
S, 1, 9, R, and L are equivalent to MPE open mode 1 with the added
capability of allowing automatic and user-controlled locking and
unlocking at the database, data set, and data record level. (Open Mode 2
also allows locking and unlocking.)
Additional details about some of the values you can enter in this field
follow:
1 (Read/Write Shared Mode)
Other programs that access the database concurrently must use Open Modes
B, S, 1, 9, R, L, or 5. An input file (or record) is locked before the
record is read, and unlocked after it is read. An output file (or
record) is locked before the record is written, and unlocked after it is
written. An update file (or record) is locked before the record is read,
and unlocked after it is updated or before the next lock and read. If
the file has been locked and read, but not updated (and thus not
unlocked), RPG unlocks it before the next lock and read.
9 (Read/Write Shared Mode)
An input file (or record) is locked before the record is read, and
unlocked after it is read. An output file (or record) is locked before
the record is written, and unlocked after it is written. An update file
(or record) is locked before the record is read, and unlocked after it is
updated or before the next lock and read. If the file has been locked
and read, but not updated (and thus not unlocked), RPG unlocks it before
the next lock and read.
R (Read/Write Shared Mode)
When you use R, enter 5, 6, C, or R in the Input/Output Mode Field
(column 67). If you do not, the database is opened with Open Mode 1
(database locking per record). You must also enter an ITEM Continuation
line for the file.
An input file (or record) is locked before the record is read, and
unlocked after it is read. An output file (or record) is locked before
the record is written, and unlocked after it is written. An update file
(or record) is locked before the record is read, and unlocked after it is
updated or before the next lock and read. If the file has been locked
and read, but not updated (and thus not unlocked), RPG unlocks it before
the next lock and read.
L (Read/Write Shared Mode)
This mode lets you control all locking and unlocking (RPG does not
perform automatic locking or unlocking). This mode is equivalent to
using the KNOLOCK Continuation line for KSAM and other non-TurboIMAGE
files.
2 (Update-Shared Mode)
The program cannot add or delete records or perform locking. Other
programs that run concurrently and update the database must use Open Mode
2 or 6.
3 (Exclusive Mode)
This program, only, can read, write, and update the database.
4 (Semi-exclusive Modify Access Mode)
This is the same as Open Mode 3 except that other programs using Open
Mode 6 can read the database.
5 (Shared Read Access Mode)
The program has read-only access to the database. Other programs running
concurrently with Open Mode 1 have read/write shared access to it.
6 (Shared Read Access Mode)
The program has read-only access to the database. Other programs running
concurrently must use Open Modes 2, 4, 6, or 8.
7 (Exclusive Read Access Mode)
This program, only, can read the database. It cannot write to the
database.
8 (Shared Read Access Mode)
This program has read-only access to the database. Other programs using
Open Mode 6 or TurboIMAGE DBSTORE routines also have read-only access to
it.
Locking Precedence
If you define a database or data set more than once in a program, you
must use the same locking precedence level (Open Modes B, S, 1, 9, R, and
L) for each definition. For example, if a database is first defined with
database locking for duration (Open Mode B) and later defined with
record-level locking (Open Mode R), a conflict occurs. There is no
reason to perform record-level locking on the database when the entire
database is already locked for the duration of the program. When the
Open Modes do not have the same locking precedence level, the compiler
issues a warning and defaults the record-level locking to the locking
precedence level of the first Open Mode specified (in this case, B).
The locking precedence levels follow. To avoid locking precedence level
conflicts, consistently use the same locking precedence levels for the
database or data set for each definition in the program. For example, if
the highest locking level needed in the program is B, then all file
definitions for the database or dataset should also be B.
B - Highest level
S - Middle level
1, 9, R, L - Lowest level
When a locking precedence level error occurs, the compiler makes the
following adjustments:
* If the first Open Mode is of higher precedence than all of the
succeeding Open Modes, the compiler issues a warning and defaults
all lower precedence locking levels to the first one specified.
* If the first Open Mode is of lower precedence than the other
locking precedence levels, a compiler error results.
If you need more than one outstanding lock, you must have Multiple RIN
special capability. Be very careful to prevent deadlocks when executing
with Multiple RIN. (See the TurboIMAGE/iX Database Management System
manual for information on the MR capability.)
The TurboIMAGE/iX Database Management System manual has more information
on locking levels and strategies.
Input/Output Mode Field (Column 67)
Additional details on some of the values you can enter in this field are
listed below:
4 (Directed Read)
The chaining or record address fields must contain numeric relative
record numbers. If no record exists for the record number, the H0
indicator is turned ON. (For the CHAIN operation in the Calculation
Specification, the error indicator is turned ON.) The first record in the
file is Record 1 (unlike MPE files, where the first record in the file is
Record 0).
5 (Chained Read)
You must provide the key for each record read. Using the same key more
than once causes the same record to be read. A DBFIND operation is done
before each record is read. You must enter an ITEM Continuation line.
If you want to read down a chain, use Input/Output Mode C.
6 (Backward Chained Read)
This is the same as Input/Output Mode 5 except that if duplicate keys
exist, the last record having this key is read. You must enter an ITEM
Continuation line. If you want to read up a chain, use Input/Output Mode
R.
7 (Calculated Read)
This was formerly Associative Read. Use it with master data sets only.
The record with a matching key is read.
8 (Primary Calculated Read)
This was formerly Primary Associative Read. It applies to master data
sets only. The record key is used to locate the place where a record
should be, then reads whatever record it finds at that location. Because
of the way TurboIMAGE keys are hashed, the record that is read may not
have the same key as that expected.
C (Chained Sequential Read)
This mode lets you use chaining or Record Address Files. With chaining,
consecutive duplicate keys cause RPG to read sequentially down the chain.
When there are no more records in the chain, the low resulting indicator
(columns 56-57 of the Calculation Specification CHAIN operation) is
turned ON. For input chaining, H0 is turned ON. With Record Address
Files, RPG reads down the entire chain before processing the next key.
Enter an ITEM Continuation line for this mode.
R (Backward Chained Sequential Read)
This is the same as Input/Output Mode C except that the chains are read
in reverse sequence.
Item Name (ITEM) Line.
This Continuation line defines TurboIMAGE item (key) names.
This line is required when the database has a Database Name (IMAGE)
Continuation line containing 5, 6, 7, 8, C, or R in the Input/Output
Modes Field (column 67).
-------------------------------------------------------------------------------------------------
| | | | |
| Record Type | Description | Item Name | Description |
| (Columns 54-59) | | (Columns 60-74) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| ITEM | This is an IMAGE | Item (key) name | The name of the key |
| | item (key) name line. | | used for accessing this |
| | | | file. Use the same name|
| | | | defined in the database |
| | | | schema. |
| | | | |
| ITEM | This is an IMAGE | *(in column 60) | The item name (up to |
| | item (key) name line. | | 16 characters) is |
| | | | specified in columns |
| | | | 20-35 of the Long |
| | | | Name Option Target |
| | | | Field. |
| | | | |
-------------------------------------------------------------------------------------------------
Password (LEVEL) Line.
This Continuation line specifies the passwords that permit access to the
database.
Since RPG processes TurboIMAGE records, not individual fields, the
password must include permission to read and write entire records.
-------------------------------------------------------------------------------------------------
| | | | |
| Record Type | Description | Password | Description |
| (Columns 54-59) | | (Columns 60-67) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| LEVEL | This is a password | Password. (Maximum | A password that |
| | line | length of eight | establishes a user-class |
| | | characters.) | identification that lets |
| | | | the program access the |
| | | | database. |
| | | | |
-------------------------------------------------------------------------------------------------
If you do not enter this Continuation line, User Class 0 is used. (See
the TurboIMAGE/iX Database Management System Manual for information on
passwords.)
Data Set Name (DSNAME) Line.
This Continuation line has two purposes:
1. It lets you process the same data set more than one way. For
instance, you can process a data set randomly by relative record
number and sequentially by key. To do this, you must define two
files and use DSNAME Continuation lines to equate these files to
the same physical data set.
2. It lets you use a longer data set name than the eight-character
file name allowed in the File Name Field (columns 7-14) of the
File Description Specification. The name that you enter overrides
columns 7-14.
-------------------------------------------------------------------------------------------------
| | | | |
| DSNAME | Description | File Name | Description |
| (Columns 54-59) | | (Columns 60-74) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| DSNAME | This is a DSNAME | Qualified file name. | Override the file name |
| | line for file sharing.| (This can contain from| specified in columns |
| | | one to 15 characters, | 7-14 of the File |
| | | beginning with a | Description |
| | | letter. The remaining| Specification when |
| | | characters can be | opening the file; share |
| | | letters or digits. | the file number with |
| | | Embedded blanks are | other files having the |
| | | not allowed.) | same DSNAME file |
| | | | name. (These files |
| | | | access the same |
| | | | logical file.) |
| | | | |
| DSNAME | This is a DSNAME | *(in column 60) | Use the file name (up to|
| | line for file sharing.| | 16 characters) specified|
| | | | in columns 20-35 of the |
| | | | Long Name Option |
| | | | Target Field. |
| | | | |
-------------------------------------------------------------------------------------------------
Input/Output Status Array (STATUS) Line.
This Continuation line lets you use TurboIMAGE status arrays. Status
arrays let you control processing for certain input TurboIMAGE errors.
When you use this Continuation line, RPG does not automatically terminate
the program when the positive errors 10, 11, and 14-17 are encountered.
These errors are treated as exceptions; they turn ON the H0 indicator.
You must process these errors yourself or leave the H0 indicator ON. If
you leave it ON, the program ends on the next cycle unless you specify
otherwise in the Error Response Field (columns 56-71) of the Header
Specification. Negative errors and output errors always cause the
program to terminate.
-------------------------------------------------------------------------------------------------
| | | | |
| Record Type | Description | Array Name | Description |
| (Column 54-59) | | (Columns 60-65) | |
| | | | |
-------------------------------------------------------------------------------------------------
| | | | |
| STATUS | This is an | Array name. | The name of the array.|
| | input/output status | | The array must be a |
| | array line. | | six-element numeric |
| | | | array; each element |
| | | | containing ten digits |
| | | | with zero decimals |
| | | | positions. |
| | | | |
-------------------------------------------------------------------------------------------------
Define the status array with the six elements (words) shown below. You
do not need to define it further with a File Extension Specification.
1. Condition word. This is zero if no exception conditions occur.
(Exception conditions are defined in the TurboIMAGE/iX Database
Management System manual.) Otherwise, this word contains the
TurboIMAGE error number (see Appendix B).
2. Length (in words) or the record read or written.
3. Record number of the record read or written.
4. Zero (for read operations on non-primary entries).
Synonym chain count (for read operations on primary entries).
Synonym chain length (for write operations).
5. Record number of predecessor entry in this chain of the current
path.
6. Record number of the successor entry in this chain of the current
path.
Key File Name (KEYFL) Line.
This Continuation line defines the name of the KSAM key file and, if the
KSAM file is being created, the duplicate key options for the file.
-----------------------------------------------------------------------------------------------
| | | |
| Column | Value | Description |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Record Type: | KEYFL | This is a KSAM key file name line. |
| (columns 54-59) | | |
| | | |
| Key File Name: | Key file name | Name to be given to the KSAM key |
| (columns 60-67) | | file. Enter an 8-character name |
| | | that conforms to MPE file naming |
| | | conventions. |
| | | |
| First Record Option: | 1 | The first record is 1. |
| (column 68) | | |
| | | |
| | 0 or blank | The first record is 0. |
| | | |
| Duplicate Key Option: | D | Allow duplicate keys. |
| (column 69) | | |
| | | |
| | blank | Do not allow duplicate keys. |
| | | |
| Chronological Option: | C | Maintain the chronological order |
| (column 70) | | of duplicate keys. Use this |
| | | option only when the Duplicate Key |
| | | Option Field is D. |
| | | |
| | R | Add duplicate keys randomly to the |
| | | key file (this improves |
| | | performance; see the KSAM/3000 |
| | | Reference Manual.) |
| | | |
| | blank | The file does not have duplicate |
| | | keys, or records are being added |
| | | to it randomly (see R above). |
| | | |
-----------------------------------------------------------------------------------------------
WORKSTN Interface Fields (Columns 54-74)
This Continuation line specifies control parameters, files, and field
names associated with WORKSTN (terminal) files. See Chapters 10 and 11
and the HP RPG Programmer's Guide for examples of how to use WORKSTN
(VPLUS and RSI) files.
--------------------------------------------------------------------------------------------------
| | | | |
| Option Type | Description | Option Target | Description |
| (Columns 54-59) | | (Columns 60-74) | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BATCH | The file name specified | File name. | File name of the VPLUS |
| | in the Option Target | | batch file. |
| | Field is the file to | | |
| | which data entered on | | |
| | the form is written | | |
| | during standard VPLUS | | |
| | data entry operations. | | |
| | | | |
| FIRST | The RSI form named in | RSI form name. | The name of an RSI form |
| | the Option Target Field | | contained in an RSI |
| | is displayed during | | forms file. The forms |
| | program initialization. | | file must be declared |
| | (This option speeds the | | by a FORMS File |
| | display of the first | | Description |
| | form in a program. | | Continuation line. |
| | | | |
| FORMDL | The number of forms | A three-digit number in | Maximum number of forms |
| | specified in the Option | columns 60-62. The | to be held |
| | Target Field determines | number must be in the | simultaneously in |
| | the size of the VPLUS | range 1-255. | terminal memory. |
| | "form storage | | |
| | directory" used in | | |
| | forms downloading. | | |
| | | | |
| FORMS | The file name specified | File name. (This can | File name of the forms |
| | in the Option Target | be up to 8 characters | library. |
| | Field is the VPLUS | beginning with a | |
| | forms file created with | letter. The remaining | |
| | FORMSPEC, or is the RPG | characters can be | |
| | Screen Interface Forms | letters or digits. | |
| | Library created with | Embedded blanks are not | |
| | SIGEDITOR. | allowed. | |
| | | | |
--------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------
| | | | |
| Option Type | Description | Option Target | Description |
| (Columns 54-59) | | (Columns 60-74) | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| LOADFM | The array name in the | Array name. (This may | Compile-time array |
| | Option Target Field | be a name up to six | containing the forms to |
| | contains the names of | characters beginning | download. You can |
| | forms to download using | with a letter or @, $, | modify the contents of |
| | the LOADFM VPLUS action | or #; the remaining | the array at run time. |
| | (Do not use it for RPG | characters can be | Form names must not |
| | Screen Interface | letters or digits.) | exceed 15 characters |
| | files). The array is | | and must be followed by |
| | predefined as an | | a blank. |
| | alphanumeric | | |
| | compile-time array. | | |
| | Each entry is 16 | | |
| | characters long and the | | |
| | number of entries is | | |
| | determined by the | | |
| | number of forms that | | |
| | you enter in the FORMDS | | |
| | File Description | | |
| | Continuation line. | | |
| | | | |
| START | The field name | Field name. (This may | Starting line number |
| | specified in the Option | be a name up to six | field. |
| | Target Field determines | characters beginning | |
| | the starting line | with a letter or @, $, | |
| | number for RPG Screen | or #; the remaining | |
| | Interface (not RPG | characters can be | |
| | VPLUS Interface) forms | letters or digits.) | |
| | which have a variable | | |
| | starting line number. | | |
| | The field is predefined | | |
| | as a two-digit numeric | | |
| | field. | | |
| | | | |
--------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------
| | | | |
| Option Type | Description | Option Target | Description |
| (Columns 54-59) | | (Columns 60-74) | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| STATUS | The array name | Array name. (This may | Array that contains RPG |
| | specified in the Option | be a name up to six | Screen and VPLUS |
| | Target Field is used by | characters beginning | Interface status |
| | the RPG Screen and | with a letter or @, $, | information. |
| | VPLUS Interfaces to | or #; the remaining | |
| | return status | characters can be | |
| | information. The field | letters or digits.) | |
| | is predefined as a | | |
| | six-element, ten-digit | | |
| | array with zero decimal | | |
| | places. | | |
| | | | |
| TRACE | The file name specified | File name. | File name of VPLUS |
| | in the Option Target | | trace file. |
| | Field is the VPLUS | | |
| | trace file which | | |
| | contains a record for | | |
| | every action, event or | | |
| | run-time error | | |
| | occurring during | | |
| | execution of the RPG | | |
| | VPLUS Interface. | | |
| | | | |
| TRMID | The field name | Field name. (This may | Field in which the |
| | specified in the Option | be a name up to six | terminal ID is |
| | Target Field is the | characters beginning | returned. |
| | field which the RPG | with a letter or @, $, | |
| | Screen Interface (not | or #; the remaining | |
| | RPG VPLUS Interface) | characters can be | |
| | initializes with the | letters or digits.) | |
| | terminal identification | | |
| | of the WORKSTN file. | | |
| | This is predefined as a | | |
| | two-character | | |
| | alphanumeric field. | | |
| | | | |
--------------------------------------------------------------------------------------------------
Program Name (Columns 75-80)
This field contains the program name. The format of this field is
discussed in Chapter 2.