HP OpenVMS Systems Documentation

HP COBOL
Reference Manual

Function

The PADDING CHARACTER clause specifies the character to be used to pad blocks in sequential files.

pad-char

is a one-character nonnumeric literal or the data-name of a one-character data item. The data-name can be qualified.

General Rule

The PADDING CHARACTER clause is for documentation only.

4.2.8 RECORD DELIMITER (OpenVMS)

Function

The RECORD DELIMITER clause indicates the method of determining the length of a variable record on the external medium. It is for documentation only.

General Rule

On OpenVMS, STANDARD-1 is the I/O system (OpenVMS Record Management System [RMS]) default for tape files. It is the method used for determining the length of a variable-length record. This method is specified in the American National Standard X3.27-1978, "Magnetic Tape Labels and File Structure for Information Interchange," and International Standard 1001 1979, "Magnetic Tape Labels and File Structure for Information Interchange."

Additional Reference

For OpenVMS systems, refer to the OpenVMS Record Management Services Reference Manual for more information. <>

4.2.9 RESERVE

Function

On OpenVMS systems, the RESERVE clause specifies the number of input-output buffers for a file. <>

On Tru64 UNIX systems, RESERVE is for documentation purposes only. <>

reserve-num

is an integer literal from 1 to 127. It specifies the number of input-output areas for the file.

General Rule

On OpenVMS systems, if there is no RESERVE clause, the number of input-output areas equals the I/O system default.

Technical Note

For OpenVMS systems, two DCL commands change and display the defaults for block count: SET RMS DEFAULT and SHOW RMS DEFAULT. The number of areas is stored in the MBF field of the RAB.

Additional References

Refer to the RMS documentation for field RAB$B_MBF. <>

4.2.10 I-O-CONTROL

Function

The I-O-CONTROL paragraph specifies the input-output techniques to use for a file.

On Tru64 UNIX systems, a number of the elements in the I-O-CONTROL paragraph are for documentation only. See the Technical Notes for more information. <>

extend-amt

is an integer from 0 to 65,535. It specifies the number of blocks in each extension of a disk file.

file-name

is the internal name of a file connector. Each file-name must have a file description (or Sort-Merge File Description) entry in the Data Division. The same file-name cannot appear more than once in the FILE-CONTROL paragraph.

preall-amt

is an integer from 0 to 4,294,967,295. It specifies the number of blocks to initially allocate when the program creates a disk file.

window-ptrs

is an integer from 0 to 127. Its value can also be 255. It specifies the number of retrieval pointers in the window that maps the disk file.

same-area-file

names a file described in a Data Division file description entry to share storage areas with every other same-area-file.

rec-count

is an integer specifying the number of records to process before writing the rerun information.

clock-count

is an integer specifying an interval of time to elapse before writing the rerun information.

condition-name

names a switch status which, when set, causes the rerun information to be written. The switch is defined in the Section 4.1.3 paragraph of Section 4.1, CONFIGURATION Section.

multiple-file

is a file described in a Data Division file description. It specifies that the file shares storage on a reel/unit device with other files. No more than 255 files can be specified.

pos-integer

is an integer from 1 to 255. It specifies the relative location of a file on a tape that contains multiple files.

Syntax Rules

1. The I-O-CONTROL clauses can appear in any order.
2. As the following table shows, each phrase of the APPLY clause can refer only to some file types.

   Phrase	File Type
   EXTENSION	Disk file
   FILL-SIZE	Indexed organization
   LOCK-HOLDING	Disk file
   MASS-INSERT	Indexed organization
   PREALLOCATION	Disk file
   PRINT-CONTROL	Sequential organization
   WINDOW	Disk file

3. More than one APPLY clause can refer to the same file-name.
4. The phrases of the APPLY clause can appear in any order. However, each phrase can be used only once for each file-name.
5. You can specify the LOCK-HOLDING phrase only if you specify the ALLOWING option of the OPEN statement.
6. The RERUN and MULTIPLE FILE clauses cannot refer to a sort or merge file.
7. In the SAME AREA clause, SORT and SORT-MERGE are equivalent.
8. If same-area-file refers to a sort or merge file, you must use the SORT, SORT-MERGE, or RECORD phrase.
9. A program can contain more than one SAME clause. However, the following conditions apply:
   • A same-area-file cannot be in more than one SAME RECORD AREA clause.
   • A same-area-file that refers to a sort or merge file cannot be in more than one SAME SORT AREA or SAME SORT-MERGE AREA clause.
     same-area-files cannot have the global or the external attribute if the program specifies the SAME RECORD AREA phrase.
10. Files specified in a MULTIPLE FILE TAPE clause must be sequential.
11. A file cannot be specified in more than one MULTIPLE FILE TAPE clause.

General Rules

APPLY Clause

1. An APPLY clause remains active for a file-name until the image terminates.
2. If the file connector referenced by file-name is an external file connector, all file control entries in the run unit that reference this file must have the same APPLY clause.
3. The DEFERRED-WRITE phrase causes a physical write operation to occur only when the input-output buffer for file-name is full. If there is no DEFERRED-WRITE phrase, a physical write occurs each time an output statement executes for file-name.
4. The EXTENSION phrase specifies the number of disk blocks to be added each time a file is extended. The I/O system extends a file when it needs more file space to add a record.
   If extend-amt equals zero, the I/O system extends the file by its default value.
5. The FILL-SIZE phrase causes the I/O system to use the fill size specified when an indexed file is created to fill the file's buckets. If there is no FILL-SIZE phrase, the I/O system fills buckets completely. The FILL-SIZE phrase applies only to indexed files.
6. The LOCK-HOLDING phrase declares the Hewlett-Packard standard manual record-locking attribute for a sequential, relative, or indexed file in a file-sharing environment on disk.
   Once a record is manually locked (see the Section 6.8.26, Section 6.8.30, Section 6.8.34, and Section 6.8.43 statements in Chapter 6, Procedure Division), it remains locked until one of the following occurs:
   • An UNLOCK statement executes.
   • A CLOSE statement executes for the subject file.
   • The image terminates.
   
   Usage of the APPLY LOCK-HOLDING option requires additional syntax for the OPEN, READ, REWRITE, START, and WRITE verbs. Table 4-2 summarizes the additional syntax required for Procedure Division I/O statements accessing a file possessing the manual record-locking attribute.
7. X/Open standard and Hewlett-Packard standard syntax cannot both be specified for the same file connector. Hence, APPLY LOCK-HOLDING cannot be specified if LOCK MODE was specified for that file in the SELECT statement.

   Table 4-2 Required Manual Record-Locking Phrases (Hewlett-Packard Standard)

   	Procedure Division Options Required by the Manual Record-Locking Facility (Hewlett-Packard Standard)
   I/O Operation	ALLOWING ...	*REGARDLESS OF LOCK
   OPEN	X	N/A
   READ	X	X
   REWRITE	X	N/A
   START	X	X
   WRITE	X	N/A

   ---

   Legend:

   X---Required
   N/A---Not Applicable
   *---If the ALLOWING option is not specified

   ---

8. The MASS-INSERT phrase is for documentation only. It has no effect on program execution.
9. On OpenVMS the PREALLOCATION phrase causes the I/O system to allocate preall-amt disk blocks when it creates the file.
   • The CONTIGUOUS phrase specifies that the preallocated disk blocks must be contiguous. If the I/O system cannot find preall-amt contiguous disk blocks, the OPEN operation fails.
   • The CONTIGUOUS-BEST-TRY phrase causes the I/O system to try to preallocate disk blocks contiguously. If the I/O system cannot find preall-amt contiguous disk blocks, it preallocates disk blocks in the largest possible contiguous areas.
10. The PRINT-CONTROL phrase specifies that the file has print file format. Additionally, the PRINT-CONTROL phrase applies only to sequentially organized files.
    The PRINT-CONTROL phrase is redundant if:
    • The file description entry contains a LINAGE clause
    • The program contains a WRITE statement with the ADVANCING phrase for the file
    • The Report Writer Control System is in effect
11. The WINDOW phrase causes the I/O system to use window-ptrs number of retrieval pointers in mapping the files. window-ptrs must fall in the range of 0 to 127 inclusive or be equal to 255. If window-ptrs is 255, then the I/O system attempts to map the entire file. <>