Compaq COBOL
Reference Manual
Previous Contents Index

4.2.3 BLOCK CONTAINS

Function

On OpenVMS Alpha systems, the BLOCK CONTAINS clause specifies the size of a physical record. <>

On Tru64 UNIX systems, block size for INDEXED organization is for documentation purposes only. <>

smallest-block

is an integer literal. It specifies the minimum physical record size.

blocksize

is an integer literal. It specifies the exact or maximum physical record size.

Syntax Rule

The BLOCK CONTAINS clause can be in the file's Data Division file description entry. However, it cannot be in both the SELECT clause and the file description entry for the same file.

General Rules

  1. The BLOCK CONTAINS clause specifies physical record size.
  2. The compiler ignores smallest-block.
  3. The RECORDS phrase specifies physical record size in terms of logical records.
  4. The CHARACTERS phrase specifies physical record size in terms of characters.
    The physical record size is the maximum of: (1) blocksize bytes, and (2) the size of the largest logical record; plus any overhead bytes for variable-length records.
  5. If there is no BLOCK CONTAINS clause, physical record size assumes a default value.
    The physical record size is the size of the largest record plus any overhead bytes.
  6. The size of physical records (in characters) must be a multiple of four. Otherwise, the I/O system rounds up the physical record size to the next multiple of four.

4.2.4 CODE-SET

Function

The CODE-SET clause specifies the representation of data on external media.

alpha-name

is the name of a character set defined in the SPECIAL-NAMES paragraph. It cannot be described with literals in the ALPHABET clause.

Syntax Rules

  1. The CODE-SET clause can be in the file's Data Division file description entry. However, it cannot be in both the SELECT clause and the file description entry for the same file.
  2. The CODE-SET clause applies only to files with sequential organization.

General Rules

  1. The CODE-SET clause identifies alpha-name as the character set used to represent the file data externally.
  2. alpha-name specifies how to convert character codes in the file to and from native character codes.
  3. Code conversion occurs during execution of an input or output operation. Conversion occurs as if the data were USAGE DISPLAY.
  4. Successful OPEN statement execution establishes the character set for code conversion. The set used is the one specified by alpha-name in the FILE-CONTROL paragraph implied by the OPEN statement.
  5. If there is no CODE-SET clause, no character conversion occurs during input-output operations. The native character set is the default.

Additional Reference

See the Section 4.1.3, SPECIAL-NAMES paragraph.

Example

In this example, the CODE-SET clause specifies that the data in INFILE is coded in the EBCDIC character code set as specified by an alphabet named EB. The SPECIAL-NAMES paragraph defines EB as the EBCDIC character set. 


SPECIAL-NAMES. 
    ALPHABET EB IS EBCDIC. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
    SELECT INFILE ASSIGN TO INFILE 
      CODE-SET IS EB.

4.2.5 LOCK MODE (Alpha)

Function

The LOCK MODE clause specifies a locking technique to use for a file. LOCK MODE is part of the X/Open COBOL standard.

Syntax Rules

  1. X/Open standard and Compaq standard syntax cannot both be specified for the same file connector. Hence, if LOCK MODE is specified, the ALLOWING, APPLY LOCK-HOLDING, and REGARDLESS phrases cannot be specified for that file.
  2. The WITH LOCK ON RECORD clause is for documentation purposes only.
  3. The LOCK MODE IS MANUAL clause is not available for sequential or line sequential files.

General Rules

  1. When you specify LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL, an OPEN statement (without the WITH LOCK phrase) opens the file in shareable mode. The LOCK MODE clause can be overridden by the WITH LOCK phrase of the OPEN statement.
  2. When you specify LOCK MODE IS EXCLUSIVE, a successful OPEN statement opens the file in exclusive mode. The OPEN statement cannot override LOCK MODE IS EXCLUSIVE.
  3. If you omit the LOCK MODE clause, opening the file causes it to become exclusive, unless you open it for INPUT, in which case the file becomes shareable.
  4. When you specify LOCK MODE IS AUTOMATIC for a file, a record lock is acquired by the successful execution of the READ statement and released on the successful execution of a subsequent I/O statement.
    If you specify LOCK MODE IS MANUAL, a record lock is acquired by the READ WITH LOCK statement.
  5. On Tru64 UNIX, the ROLLBACK phrase is used by ACMSxp applications to specify a recoverable file. You must compile with the -tps option to specify a recoverable file. <>
  6. A file that is opened in exclusive mode cannot be opened by any other access stream.
  7. A file that is in shareable mode can be opened by any number of access streams that do not require exclusive use.
  8. A file that does not reside on a mass storage device cannot be opened in shareable mode. <>

4.2.6 ORGANIZATION

Function

The ORGANIZATION clause specifies a file's logical structure.

On Alpha systems, the ORGANIZATION IS LINE SEQUENTIAL clause specifies a variant of sequential files compatible with the system text editor. <>

General Rules

  1. File organization is established when the file is created. It cannot be subsequently changed.
  2. If there is no ORGANIZATION clause, the default is SEQUENTIAL.
  3. On Alpha systems, when LINE SEQUENTIAL organization is specified, the file is treated as consisting of variable length records, with each record containing one line of data. A line is a sequence of characters ending with a record terminator ( \n or x'0A'). The terminator is not counted in the length of the record.
  4. On Alpha systems, a file with LINE SEQUENTIAL organization should only contain printable characters and the record terminator.
  5. On Alpha systems, a file with LINE SEQUENTIAL organization may not be opened in I-O mode. <>
  6. All programs that open an existing file must specify the same organization with which the file was created.

Note
On Tru64 UNIX, a third-party product is required for INDEXED run-time support. Refer to the Release Notes for the latest details on how to obtain the INDEXED run-time support. <>

4.2.7 PADDING CHARACTER

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 Alpha systems, STANDARD-1 is the I/O system (OpenVMS Alpha 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 Alpha 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 Alpha systems, if there is no RESERVE clause, the number of input-output areas equals the I/O system default.

Technical Note

For OpenVMS Alpha 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:
  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 Compaq 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:
    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 Compaq 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 (Compaq Standard)
      Procedure Division Options Required by the Manual Record-Locking Facility (Compaq 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.
  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:
  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. <>

SAME AREA Clause

  1. The SAME AREA clause is for documentation only.

SAME RECORD AREA Clause

  1. The SAME RECORD AREA clause causes two or more files named by same-area-file to share the same memory area for the current logical records.
  2. If you specify the SAME RECORD AREA clause, more than one same-area-file (or all of them) can be open at the same time.
  3. Any record in the shared area becomes the current logical record of:
    The logical records start with the same leftmost character position. Thus, the SAME RECORD AREA clause is equivalent to an implicit redefinition of the shared area.

SAME SORT (SORT-MERGE) AREA Clause

  1. The SAME SORT (SORT-MERGE) AREA clause is for documentation only.

RERUN Clause

  1. The RERUN clause is for documentation only. It has no effect on program execution.

MULTIPLE FILE TAPE Clause

  1. The MULTIPLE FILE TAPE clause specifies the location of a file or files on a reel/unit device. The location of the file or files can be specified as a relative location by providing a multiple-file series. The specific file location can be specified by the POSITION phrase.
  2. The MULTIPLE FILE TAPE clause specifies the location of a file or files when more than one file shares the same physical reel of tape. If the files in the multiple-file sequence are listed in consecutive order, the POSITION phrase is not required. If the files in the multiple-file sequence are not listed in consecutive order, the position of the file or files (relative to the beginning of the tape) must be specified in the POSITION phrase.
  3. Only those multiple-files referenced by the program need to be specified in a MULTIPLE FILE TAPE clause.
  4. If a file is specified with a POSITION phrase of a MULTIPLE FILE TAPE clause, subsequent files listed in that MULTIPLE FILE TAPE clause which are not specified with a POSITION phrase are assumed to be in the next higher position.
  5. Only one file listed in a MULTIPLE FILE TAPE clause sequence can be open at any one time.
  6. If, at run-time, the run-time system determines that the files referenced are not located on a reel device, the MULTIPLE FILE TAPE clause is ignored.

Technical Notes