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:In the FILE-CONTROL paragraph body, the SELECT clause must be specified first. The remaining clauses may appear in any order. Each of the clauses of the FILE-CONTROL paragraph are described on the following pages in alphabetical order, except the SELECT and ASSIGN clauses. Since these clauses must be specified first for any file type, they are discussed first. SELECT Clause The SELECT clause is used to identify a file to be used in your program. Syntax. The SELECT clause has two formats:Parameters. file-name-1 any valid user-defined COBOL word. File-name-1 is the name you use later in OPEN, CLOSE, USE, and other statements in the PROCEDURE DIVISION. It must also be used in an FD or an SD entry in the DATA DIVISION. OPTIONAL Phrase. The purpose of the OPTIONAL phrase is to allow you to specify an input file in the SELECT statement that may not be present during a particular execution of the program in which it is named. If the file is not present and the OPTIONAL phrase has been specified, when the first READ statement naming that file is executed, the imperative statement in the associated AT END phrase is executed. If no AT END phrase has been specified, then a USE procedure must be defined, either explicitly or implicitly, and this procedure is executed. When the file is not present and it is opened in I-O or extend mode with the OPTIONAL phrase, a new file is created. Otherwise, file status 35 is returned. ASSIGN Clause The ASSIGN clause associates a file with the storage medium on which the file resides.[REV BEG] With the USING phrase, you can assign logical files to physical files dynamically (that is, at run time).[REV END] Syntax. [REV BEG] ASSIGN { [TO file-info-1] [USING data-name-1] }[REV END] Parameters. file-info-1 a nonnumeric literal of the form: name [,[class] [,[recording mode] [, [device [(CCTL)] ] [,[file-size] [, [formsmessage.] [,L]]]]]] The meanings of each parameter of file-info-1 are given below. name the operating system file designator. Refer to Appendix H , "MPE XL System Dependencies", for detailed information about this file designator. [REV BEG] If you use the USING phrase of the ASSIGN clause, this parameter is ignored. The operating system file designator must be supplied in data-name-1 instead.[REV END] class the class of device on which the file resides. This parameter is not used by the file system and is ignored if it is specified. However, if specified, the class parameter can be one of the following three mnemonics: DA, implying a mass-storage device. UT, implying a utility device such as a tape drive. UR, implying a unit-record device, such as a card reader. If the class parameter is omitted, DA is assigned by default. recording mode the recording mode of the file. It may be either ASCII or binary. If the file is an ASCII file, recording mode must be A. If the file is binary, the recording mode must be B. If the recording mode parameter is omitted, ASCII is assigned by default. device the type of device on which the file resides. Refer to Appendix H , "MPE XL System Dependencies", for further details. CCTL the carriage control option for an output file, indicating that carriage control directives are supplied in write operations referencing line printer files. If omitted, your program uses the file system default for the device or file. file-size the number of records in the file. Refer to Appendix H , "MPE XL System Dependencies", for further details. formsmessage for a listing device, a request for the operator to provide special forms, such as blank checks or inventory report forms, on the printer. For any other device, this parameter is ignored. This entry may contain a maximum of 49 characters and must be terminated with a period. L enables your program to dynamically lock and unlock a disk file. However, this feature is provided only to assist in the conversion of COBOL'68 programs to COBOL II. It is recommended that the EXCLUSIVE and UN-EXCLUSIVE statements be used instead for file locking and unlocking. L is not a required parameter if the EXCLUSIVE and UN-EXCLUSIVE statements are used. Otherwise, it enables your program to dynamically lock and unlock a disk file. [REV BEG] data-name-1 an alphanumeric data item containing the operating system file designator (see name above). data-name-1 must not be subordinate to the file description entry for the file described in the enclosing SELECT clause. If the TO phrase is also specified, all the information in file-info-1 except the file designator, name, is used when the file is opened. See Appendix H , "MPE XL System Dependencies," for detailed information about this file designator. The USING data-name-1 form of the ASSIGN clause is an HP extension to the ANSI COBOL standard.[REV END] [REV BEG] Description. You associate a file with a storage medium in the ASSIGN clause. When you use the TO phrase, this association occurs at compile time and cannot be changed unless you modify your program and recompile it. When you use the USING phrase, the association occurs at run time. You can change the association in the PROCEDURE DIVISION by changing the contents of data-name-1. data-name-1 contains the operating system file designator for the file. See the HP COBOL II/XL Programmer's Guide for an example of the USING clause. If you use both the TO and USING phrases, the name parameter of file-info-1 is ignored. The name specified in data-name-1 is used instead. Any other parameters specified in file-info-1 also apply to the file named in data-name-1. File Status Code. File status code 31 indicates a permanent error where an OPEN, SORT, or MERGE of a file specified in data-name-1 has failed. The operation may have failed because the contents of data-name-1 were not consistent with the contents of file-info-1 in the TO phrase. This error also occurs if data-name-1 contains an invalid file name.[REV END] ACCESS MODE Clause The ACCESS MODE clause specifies the way in which your program is to access the associated file. Syntax. There are four formats of this clause, depending upon the type of file being described. This clause cannot be used for sort-merge files. The four formats are shown below.Parameters. data-name-1 a data item that must not be defined in the record description entry for the relative file being described. Furthermore, the item must be defined as an unsigned integer. Such a data item might be defined as the following where n is an integer in the range 5 to 9: USAGE COMPUTATIONAL SYNCHRONIZED PIC 9(n),
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.Parameters. integer-1 a nonnegative integer in the range zero to 16. AREA and each are equivalent, and can be used interchangeably. AREAS Description. If you specify zero, the operating system still allocates the default number. Also, although you can specify more than two, any more than three buffers does not usually increase input-output efficiency. See your operating system reference manual for more information on buffers. Example. The following example shows a FILE-CONTROL paragraph for an indexed file and a sequential file, as well as important data items associated with the files. ENVIRONMENT DIVISION. : INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT INDXFILE ASSIGN TO "KFILE,DA,A,DISC,5000,,L" RESERVE 3 AREAS ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS FIRST-CHARS ALTERNATE RECORD KEY IS SECOND-CHARS WITH DUPLICATES FILE STATUS IS CHECK-KFILE. SELECT TAPEIN ASSIGN TO "READTAPE,UT,TAPE,,HANG TAPE 001." RESERVE 2 AREAS FILE STATUS IS CHECK-TAPE. : DATA DIVISION. FILE SECTION. FD INDXFILE LABEL RECORDS ARE OMITTED. 01 RECORD-IN. 02 FIRST-CHARS PIC X(8). 02 SECOND-CHARS PIC X(24). : FD TAPEIN LABEL RECORDS ARE OMITTED. 01 TAPE-REC PIC X(80). : WORKING-STORAGE SECTION. 77 CATCHNUM PIC 9(4) USAGE DISPLAY. 01 CHECK-KFILE. 02 STAT-KEY-1 PIC X. 02 STAT-KEY-2 PIC X. 01 CHECK-TAPE. 02 STAT-KEY-1 PIC X. 02 STAT-KEY-2 PIC X.
![[]](../../pic3k/M011820/FFN223c50.gif)
![[]](../../pic3k/M011820/FFN233c50.gif)
![[]](../../pic3k/M011820/FFN243c50.gif)
![[]](../../pic3k/M011820/FFN253c50.gif)
![[]](../../pic3k/M011820/FFN263c50.gif)
![[]](../../pic3k/M011820/FFN273c50.gif)