HP 3000 Manuals HP 3000 Manuals
File Control Clauses The various clauses of the FILE-CONTROL paragraph can be specified in five separate formats, depending upon the type of file being described. These formats follow:Click here to view figure.
NOTE The ANSI standard defines the relative key value as an unsigned integer data item; however, HP COBOL II extends the standard and allows the use of signed integers for efficiency of code. Because a 32-bit integer is used for relative record numbers, a definition of "USAGE COMPUTATIONAL SYNCHRONIZED PIC S9(9)" would allow for maximum code efficiency and record access.
Even if you want to access a relative file sequentially, you must specify the RELATIVE KEY phrase in order to reference the associated file in a START statement. For three of the four file types to which this clause pertains (sequential, relative, and indexed), you must specify an ACCESS MODE clause or sequential access is assumed. You must specify the ACCESS MODE clause exactly as it is shown for random access files. The three access modes are defined as follows: * Sequential access means that existing records are accessed in ascending order. The relative key is used for relative files, and a prime or alternate record key is used for indexed files. Random access files may not be accessed sequentially. * Dynamic access means that your program may alternate between sequential and random access modes by selectively using different forms of various input-output statements. This type of access may only be used for relative and indexed files. * Random access means that the records are accessed directly by using a record key data item (for indexed files) or by using the relative record numbers of records (for relative and random access files). For details on how sequential, dynamic, and random access is performed on the various file types, refer to the overview on preceding pages of this chapter. ACTUAL KEY Clause (an HP extension to the ANSI COBOL standard) The ACTUAL KEY clause names the data item to be used in accessing records of a random access file and applies only to random access files. Syntax. This clause has the following format: ACTUAL KEY IS data-name-1 Parameters. data-name-1 an integer item of one to nine digits. Example. For greatest efficiency, the variable data-name-1 should have a PICTURE clause in the following form: PIC S9(9) USAGE COMPUTATIONAL SYNCHRONIZED. This data item must be defined in either the FILE SECTION or the WORKING-STORAGE SECTION of the DATA DIVISION. It corresponds to a relative record number. Record numbers in random access files begin with 0. To ensure the accessibility of all records, the data item must be large enough to contain the greatest record number in the file. ALTERNATE RECORD KEY Clause Each use of the ALTERNATE RECORD KEY clause names an alternate record key for an indexed file. The number of alternate keys for a file must be the same as the number used when the file was created. Syntax. This clause has the following format: [ALTERNATE RECORD KEY IS data-name-2 [WITH DUPLICATES]]... Parameters. data-name-2 the name of a data item described as alphanumeric in a record description entry for the file with which it is associated. It must not reference an item whose first character begins in the same position as the first character of any other key, whether alternate or prime. DUPLICATES Phrase. The DUPLICATES phrase specifies that the named alternate key may be duplicated within any of the records of the file. If this phrase is unused, the contents of the data item referenced by data-name-2 must be unique among records of the file. As an extension to ANSI COBOL'85, HP COBOL II also allows the use of computational, numeric display (without the optional SIGN clause), COMPUTATIONAL-3, BINARY, and PACKED-DECIMAL data types for data-name-2. FILE STATUS Clause The FILE STATUS clause allows you to name a data item to be used in obtaining information about the success or failure of input-output operations performed using the file being described. This clause is optional, and may be used for all types of files except sort-merge files. Syntax. The FILE STATUS clause has the following format: [FILE STATUS IS stat-item]. Parameters. stat-item a two character alphanumeric data item defined in the WORKING-STORAGE SECTION of the DATA DIVISION. Description. When an input or output operation has been performed on a file that has a FILE STATUS data-item associated with it, the data item is updated with two characters that indicate the status of the operation. These two characters are the file status code. The leftmost character of this data item is called status-key-1. The rightmost character is called status-key-2. The values that can be placed in status-key-1 and status-key-2, and their meanings, are shown in Table 6-2 and Table 6-3 . Table 6-2 and Table 6-3 , respectively contain information about the ANSI COBOL'85 and ANSI COBOL'74 I-O status-codes. Key terms used in those tables are defined below. EOF The program attempted to read a record following the last record in the file. AT END A sequential READ statement was unsuccessfully executed as a result of an AT END condition. INVALID KEY The input-output operation failed because a duplicate key existed, a boundary violation occurred, the record sought could not be found, or a sequence error occurred (for indexed files only). PERMANENT The input-output statement was unsuccessfully executed as ERROR the result of an error that precluded further processing of the file. LOGIC ERROR The input-output statement was unsuccessfully executed as a result of an improper sequence of input-output operations that were performed on the file, or as a result of violating a user-defined limit. IMPLEMENTOR The implementor defined codes are 9x. When status-key-1 DEFINED is set to 9, an unexpected error has occurred. In this case, the value placed in status-key-2 is a binary integer quantity corresponding to a file system error. Since this quantity can range from 0 to 255, and since the status key item is alphanumeric, your program will interpret this integer as some character from the ASCII collating sequence.[REV BEG] For an example, see the section "File Status Codes" in Chapter 5 of the HP COBOL II/XL Programmer's Guide.[REV END] FIXED FILE ATTRIBUTE Information about a file that is established when a file is created and cannot subsequently be changed during the file's existence. These attributes include the following: * Organization of the file (sequential, relative, or indexed). * Prime record key. * Alternate record keys. * Code-set. * Minimum and maximum record size. * Record type (fixed or variable). * Collating sequence of the keys for indexed files. * Blocking factor. * Padding character. * Record delimiter. The ANSI COBOL'85 file status codes are potentially incompatible with the ANSI COBOL'74 status codes. * Some 9x values have been changed to other codes. For example, the ANSI COBOL'85 file status 38 was previously a 9x code. * In order to provide more information to you, some additional values have been specified for status-key-2. Table 6-2. ANSI COBOL'85 File Status Codes -------------------------------------------------------------------------------- | | | | | | | | RANDOM ACCESS or | | | | SEQUENTIAL | RELATIVE | INDEXED | | | | | | -------------------------------------------------------------------------------- | | | | | | S | 00-Successful. No | 00-Successful. No | 00-Successful. No | | U | more information | more information | more information | | C | available. | available. | available. | | C | 04-READ length of | 04-READ length of | 02-READ current key | | E | record doesn't | record doesn't | = next key value | | S | match file. | match file. | -WRITE or REWRITE | | S | 05-OPEN. Optional | 05-OPEN. Optional | creates duplicate | | F | file not present, | file not | key for alternate | | U | created. | present, created. | key in which | | L | 07-File is not a | | duplicates are | | | tape as the OPEN/ | | allowed. | | | CLOSE phrase | | 04-READ length of | | | implies. | | record doesn't | | | | | match file. | | | | | 05-OPEN. Optional | | | | | file not present, | | | | | created. | | | | | | -------------------------------------------------------------------------------- | | | | | | A | 10-EOF or optional | 10-EOF or optional | 10-EOF or optional | | T | file not present | file not present | file not present | | E | on READ. | on READ. | on READ. | | N | | 14-Record number too | | | D | | big for relative | | | | | key data item on | | | | | READ. | | | | | | | -------------------------------------------------------------------------------- | | | | | | I | | 22-WRITE a duplicate | 21-Sequence error. | | N | | key. * | 22-WRITE OR REWRITE | | V | | 23-Record does not | a duplicate key. | | A | | exist. | 23-Record does not | | L | | -START OR READ on | exist. | | I | | missing optional | -START OR READ on | | D | | file. | missing optional | | K | | 24-WRITE beyond file | file. | | E | | boundary. | 24-WRITE beyond file | | Y | | -Sequential WRITE | boundary. | | | | record number too | | | | | big for relative | | | | | key data item. | | | | | | | -------------------------------------------------------------------------------- * Does not apply to random files. Table 6-2. ANSI COBOL'85 File Status Codes (continued) -------------------------------------------------------------------------------- | | | | | | | | RANDOM ACCESS or | | | | SEQUENTIAL | RELATIVE | INDEXED | | | | | | -------------------------------------------------------------------------------- | | | | | | P | 30-No more informa- | 30-No more | 30-No more | | E | tion available.[REV|BEG]information | information | | R | 31-OPEN, SORT, or | available.[REV BEG]| available.[REV BEG]| | M | MERGE of dynamic | 31-OPEN, SORT, or | 31-OPEN, SORT, or | | A | file failed due to | MERGE of dynamic | MERGE of dynamic | | N | file attribute | file failed due to | file failed due to | | E | conflict.[REV END] | file attribute | file attribute | | N | 34-Boundary | conflict.[REV END] | conflict.[REV END] | | T | violation. | 35-Nonoptional file | 35-Nonoptional file | | E | 35-Nonoptional file | not present for | not present for | | R | not present for | OPEN. | OPEN. | | R | OPEN. | 37-EXTEND or OUTPUT | 37-EXTEND or OUTPUT | | O | 37-EXTEND or OUTPUT | on unwritable file.| on unwritable | | R | on unwritable | -I-O for file that | file. | | | file. | does not support | -I-O for file that | | | -I-O for file that | it. | does not support | | | does not support | -INPUT on invalid | it. | | | it. | device for input. | -INPUT on invalid | | | -INPUT on invalid | 38-OPEN on file | device for input. | | | device for input. | closed with LOCK. | 38-OPEN on file | | | 38-OPEN on file | 39-OPEN unsuccessful | closed with LOCK. | | | closed with LOCK. | due to fixed file | 39-OPEN unsuccessful | | | 39-OPEN unsuccessful | attribute | due to fixed file | | | due to fixed file | conflict. | attribute | | | attribute | | conflict. | | | conflict. | | | | | | | | -------------------------------------------------------------------------------- | | | | | | L | 41-OPEN on file that | 41-OPEN on file that | 41-OPEN on file that | | O | is already open. | is already open. | is already open. | | G | 42-CLOSE for file | 42-CLOSE for file | 42-CLOSE for file | | I | not open. | not open. | not open. | | C | 43-No READ before | 43-No READ before | 43-No READ before | | E | REWRITE. | REWRITE/DELETE. | REWRITE/DELETE. | | R | 44-Boundary | 44-Boundary | 44-Boundary | | R | violation. | violation. | violation. | | O | -Record too big or | -Record too big or | -Record too big or | | R | too small. | too small. | too small. | | | -Rewrite record | 46-READ after AT END | 46-READ after AT END | | | not same size. | or after | or after | | | 46-READ after AT END | unsuccessful | unsuccessful | | | or after | READ or START. | READ or START. | | | unsuccessful | 47-READ or START on | 47-READ or START on | | | READ. | file not open for | file not open for | | | 47-READ on file not | input or I-O. | input or I-O. | | | open for input. | 48-WRITE on file not | 48-WRITE on file not | | | 48-WRITE on file | open for output | open for output | | | not open for | or I-O. | or I-O. | | | output. | 49-REWRITE or DELETE | 49-REWRITE/DELETE | | | 49-REWRITE on file | on file not open | on file not | | | not open for I-O. | for I-O. | open for I-O. | | | | | | -------------------------------------------------------------------------------- Table 6-3. ANSI COBOL'74 File Status Codes -------------------------------------------------------------------------------- | | | | | | | | RANDOM ACCESS or | | | | SEQUENTIAL | RELATIVE | INDEXED | | | | | | -------------------------------------------------------------------------------- | | | | | | S | 00-Successful. NO | 00-Successful. No | 00-Successful. No | | U | more information | more information | more information | | C | available. | available. | available. | | C | | | 02-READ current key | | E | | | = next key value. | | S | | | -WRITE or REWRITE | | S | | | creates duplicate | | F | | | key for alternate | | U | | | key in which | | L | | | duplicates are | | | | | allowed. | | | | | | -------------------------------------------------------------------------------- | | | | | | A | 10-EOF or optional | 10-EOF or optional | 10-EOF or optional | | T | file not present. | file not present. | file not present. | | E | | | | | N | | | | | D | | | | | | | | | -------------------------------------------------------------------------------- | | | | | | I | | 22-WRITE | 21-Sequence error. | | N | | a duplicate key. | 22-WRITE OR REWRITE | | V | | 23-Record does not | a duplicate key. | | A | | exist. | 23-Record does not | | L | | -START OR READ on | exist | | I | | missing optional | -START OR READ on | | D | | file. | missing optional | | K | | 24-WRITE beyond file | file. | | E | | boundary. | 24-WRITE beyond file | | Y | | -Sequential WRITE | boundary. | | | | record number too | | | | | big for relative | | | | | key data item. | | | | | | | -------------------------------------------------------------------------------- | | | | | | P | 30-No more | 30-No more | 30-No more | | E | information | information | information | | R | available. | available. | available. | | M | 34-Boundary | | | | A | violation. | | | | N | | | | | E | | | | | N | | | | | T | | | | | E | | | | | R | | | | | R | | | | | O | | | | | R | | | | | | | | | -------------------------------------------------------------------------------- ORGANIZATION Clause The ORGANIZATION clause specifies the logical structure of the file being described. It can be used in sequential, relative, and indexed files. Syntax. The three formats of the ORGANIZATION clause are shown below. [ORGANIZATION IS] SEQUENTIAL [ORGANIZATION IS] RELATIVE [ORGANIZATION IS] INDEXED Description. The ORGANIZATION clause is required for relative and indexed files. It is optional for sequential files. This clause cannot be used for sort-merge and random access files. RECORD KEY Clause The RECORD KEY clause is used for indexed files only. It is required, because it provides the means (data-name-1) by which the associated indexed file is accessed. Syntax. RECORD KEY IS data-name-1 [WITH DUPLICATES] [REV BEG] The WITH DUPLICATES phrase in the record key clause is an HP extension to the ANSI COBOL standard.[REV END] Parameters. data-name-1 the name of an alphanumeric data item defined in a record description entry associated with the file being described. As an HP extension to ANSI COBOL'85, HP COBOL II also allows the use of computational, numeric display (sign overpunched on least significant digit), COMPUTATIONAL-3, BINARY, and PACKED-DECIMAL data types for data-name-1. Data-name-1 is the prime record key for the file. The data-description for data-name-1, and its relative position within a record must be the same as that used when the file was created. DUPLICATES Phrase. The DUPLICATES phrase specifies that the named prime record key may be duplicated within any of the records of the file. If, however, you do not specify that duplicates may exist, then the value of the key must be unique among records of the file.
NOTE If an indexed file has the DUPLICATES phrase specified for its primary key, the REWRITE/DELETE statement should be used only when the indexed file is in sequential access mode. This is because a REWRITE/DELETE statement issued for a file whose access mode is dynamic or random only rewrites/deletes the first record of a DUPLICATE primary key chain.
RESERVE Clause The RESERVE clause allows you to indicate the number of input-output buffers to be allocated for the file being described. Its use is optional. If you do not specify it, the number of buffers allocated is the operating system default. This clause may be used for sequential, relative, indexed, and random access files. It may not be used for sort-merge files. Syntax. The format of the RESERVE clause is shown below.