File Concepts: SELECT and FD

The program lists the book master. It has one SELECT with a literal assignment name, one FD that pulls in the BOOKREC copybook, and the usual read loop, with FILE STATUS examined after OPEN and CLOSE.

Compiled with cobc -x -Wall and run in the directory that holds BOOKMAST:

Source: Enterprise COBOL for z/OS 6.5 Language Reference: FILE-CONTROL paragraph; GnuCOBOL 3.2 manual

On z/OS the same SELECT is written with an unquoted ddname, and the job supplies the file. Compare the two ways of writing the assignment name before moving on.

The JCL above is z/OS; not run here. The BOOKMAST DD statement is what the assignment name BOOKMAST refers to; the data set name never appears in the program. On z/OS the book master is a fixed-length QSAM data set, so the example uses ORGANIZATION IS SEQUENTIAL; the line-sequential organization would need a z/OS UNIX file. The Language Reference allows exactly two meanings for the name: the name on the DD statement for the file, or the name of an environment variable that holds file allocation information.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: ASSIGN clause; Programming Guide: Defining QSAM files and records in COBOL

The assignment name can be a user-defined word or an alphanumeric literal, and has an optional organization prefix.

The name is one to eight characters, starts with a letter and uses letters and digits (a literal may also use @, # and $). It cannot contain an underscore, and the compiler folds it to uppercase to form the ddname. This is the first thing a GnuCOBOL programmer must unlearn: BOOK_MASTER is a fine GnuCOBOL name and an illegal Enterprise COBOL assignment name. When there are several assignment names, only the first one has any effect.

The name is looked up in this order. It is first treated as a ddname. If the job step has no DD statement by that name, Enterprise COBOL treats it as the name of an environment variable, which is read at every OPEN. The variable must be named in uppercase and must hold a DSN(...) option for a QSAM or VSAM data set, or a PATH(...) option with an absolute path for a z/OS UNIX file. A line-sequential file accepts only PATH. If the variable is missing, malformed, or the dynamic allocation fails, the OPEN leaves file status 98.

The two lines are z/OS UNIX shell syntax in the style of the Language Reference; z/OS; not run here. The Language Reference recommends always coding a disposition (NEW, OLD, SHR or MOD) with DSN rather than relying on a system default.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: ASSIGN clause, assignment name for environment variable

GnuCOBOL accepts three kinds of assignment name, and a compiler dialect decides how an unquoted word is read.

The next program opens the same file the three ways and shows the first record’s title each time. The data file is in a data directory next to the program.

The output was identical with -std=ibm. DISPLAY ... UPON ENVIRONMENT-NAME and UPON ENVIRONMENT-VALUE set the environment variable from inside the program; in a shell script one would run export BOOKEXT=data/BOOKMAST before the program instead.

Source: GnuCOBOL 3.2 manual: SELECT ASSIGN TO; GnuCOBOL Programmer’s Guide: SELECT statement

When the compiler configuration has filename-mapping: yes (the default, and the setting in the default, -std=ibm and -std=mf dialects tried here), the run-time system does not use the assignment name as a path straight away. It looks for the first existing environment variable in this order, using the assignment name as the base:

The value of the variable that is found is the path and file name. If none exists, or if filename mapping is off (-fno-filename-mapping), the assignment name itself is the path. A relative path is then prefixed with the directory in the run-time setting COB_FILE_PATH (the current directory when it is not set), and an absolute path is used as it is. These are the same two ideas as the ddname and the DD statement on z/OS, with the shell standing in for the JCL: export DD_BOOKMAST=/data/circ/bookmast.dat is the GnuCOBOL spelling of a BOOKMAST DD statement.

The next program shows the order. BOOKS is a file that exists in the current directory; plain.dat, lower.dat and upper.dat are three other one-line files made for the test. The program adds one variable at a time and opens the file again, then points DD_BOOKS at a file that does not exist.

Each variable overrides the previous one, in the documented order, and the environment is read again at every OPEN. A variable that is set always wins: when DD_BOOKS points at missing.dat, GnuCOBOL does not fall back to the file called BOOKS, it fails with status 35. That is the behaviour of a DD statement that names a data set that does not exist, and it is usually what a batch job wants.

Source: GnuCOBOL Programmer’s Guide: SELECT statement, file location strings; GnuCOBOL 3.2 manual: compiler configuration (filename-mapping, assign-clause)

A relative path is also affected by COB_FILE_PATH. With BOOKMAST moved into a directory data, a program that has ASSIGN TO BOOKMAST found nothing in the current directory and, run as COB_FILE_PATH=data ./prog, opened data/BOOKMAST. When DD_BOOKMAST held an absolute path, COB_FILE_PATH was ignored (it was set to a directory that does not exist, and the file was still opened); when DD_BOOKMAST held the relative name BOOKMAST, COB_FILE_PATH=data was put in front of it.

The three lines are alternatives, not a script; the first two are two ways to write DD_BOOKMAST, and the last one sets the directory for relative names.

Enterprise COBOL lets the assignment name start with a documentation label such as UT-S- or WS-, and ignores it. GnuCOBOL applies a similar rule only under the IBM dialect, and that rule can swallow part of a data-name. The program below is deliberately wrong for -std=ibm: it writes the variable form as ASSIGN TO WS-PATH instead of ASSIGN USING WS-PATH.

The only change to the assignforms.cob program above is the second SELECT:

Compiled with cobc -x -Wall -std=ibm, the program reports the problem as a warning and then reads nothing from that file:

Under the IBM rules WS- is taken as a label and the assignment name becomes PATH, so the item WS-PATH is never used; the default dialect reads the word as a data-name. The fix is to use ASSIGN USING for the variable form (the assignforms.cob program above uses it and behaves the same in both dialects) and ASSIGN TO name only for the ddname form. A prefix is honoured only for an unquoted name under -std=ibm. With the unquoted ASSIGN TO S-BOOKMAST, cobc -std=ibm printed warning: ASSIGN S-BOOKMAST interpreted as 'BOOKMAST' [-Wadditional] and opened the file, the default dialect ended with status 35, and a quoted "S-BOOKMAST" ended with status 35 in both dialects even with BOOKMAST set in the environment. On GnuCOBOL write the plain name.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: ASSIGN clause; GnuCOBOL 3.2 manual: -fassign-clause

An FD may be followed by more than one level-01 record description. All of them describe the same storage: the record area of the file. The program does not choose among them; it uses whichever fits the record just read. This is an implicit redefinition, and it is how files with several record types (header, detail, trailer) are processed. If the records have different lengths the file is a variable-length file with the shortest and longest record derived from the descriptions, and the record area is as big as the longest.

The next program gives the loan transaction file two views of the same record: the structured LOAN-RECORD from the copybook and an alphanumeric LOAN-RAW that sees the whole 30 bytes.

The same record area is reached through both names, so a MOVE to LOAN-RAW changes LOAN-TYPE and vice versa. Two things follow. First, the record area belongs to the file, so after a READ it is valid only while the file is open and the record has not been replaced by the next READ; copy what the program needs with READ ... INTO or a MOVE to WORKING-STORAGE. Second, nothing in the 01 records tells the program which record type it holds; the program tests a field (here LOAN-TYPE) and then uses the matching description.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: DATA DIVISION file description entries; Processing files with variable-length records or multiple record descriptions

A file whose records differ in length is declared with the RECORD IS VARYING format, optionally with a DEPENDING ON item. The item is an unsigned integer that carries the length between the program and the file: the program sets it before every output statement, and the run time sets it after every successful READ. The program below writes three notes of different lengths to a record-sequential file, then reads them back, using the item to display only the bytes that belong to each record.

With -std=ibm the lengths were printed with five digits (00011), because the dialect makes PIC 9(4) BINARY a halfword and changes how DISPLAY formats it; the records are the same. The first 48 bytes of the file, dumped with od -A d -c, show how GnuCOBOL stores variable records: each record is preceded by a prefix of two length bytes (big-endian) and two zero bytes, and the length does not include the prefix.

The prefix layout is the COB_VARSEQ_FORMAT setting of the run time (value 0 is the default; other values give four-byte lengths), and the manual states that the length it records does not include the prefix. A z/OS format-V file has its own four-byte record-length field in front of each record and a four-byte block descriptor in front of each block, which the Language Reference says are not described in the data division and not available to the program. The two layouts are therefore not interchangeable, which matters when files are moved between the platforms (see Data Sets and Mainframe Utilities).

Source: Enterprise COBOL for z/OS 6.5 Language Reference: RECORD clause; Programming Guide: Establishing record formats; GnuCOBOL 3.2 manual: runtime configuration, COB_VARSEQ_FORMAT

On z/OS the physical layout of a QSAM file is a property of the data set, and the program should not hard-code it. The usual FD for a fixed-length batch file therefore has RECORDING MODE IS F, BLOCK CONTAINS 0 RECORDS and the record length, and the DD statement supplies RECFM, LRECL and the block size. A typical z/OS FD for the book master therefore looks like this (z/OS; not run here). GnuCOBOL, which has no blocks, is not expected to use BLOCK CONTAINS or RECORDING MODE.

For a line-sequential file the RECORD CONTAINS clause has no meaning: cobc -x -Wall compiled the first program of this page with RECORD CONTAINS 60 CHARACTERS on the FD and printed warning: RECORD clause ignored for LINE SEQUENTIAL [-Wadditional], which is why the FD of that program has no clause.

On z/OS, BLOCK CONTAINS 0 lets the system choose an optimal block size when the file is created; without it the compiler assumes the file is not blocked, and even BLOCK CONTAINS 1 RECORD produces fixed blocked records. Setting BLOCK0 as a compiler option applies BLOCK CONTAINS 0 to all QSAM files that have no clause of their own.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: BLOCK CONTAINS clause; RECORDING MODE clause; LABEL RECORDS clause; Programming Guide: BLOCK0

If a file has neither a FILE STATUS item nor a USE AFTER ERROR declarative, an OPEN failure ends the program. This is a deliberately fragile program: the file NOSUCHBOOKS does not exist and nothing watches the status.

GnuCOBOL printed the run-time message and exit status 1; the line not reached was never displayed. On z/OS the same program fails with a Language Environment condition and an abend or a non-zero return code, depending on the options. The remedy is the one the examples above use: always code FILE STATUS, and test it after OPEN and CLOSE as well as after READ and WRITE.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: OPEN statement; OPEN statement notes; CLOSE statement; GnuCOBOL Programmer’s Guide: OPEN, CLOSE and file status values

CLOSE file-name ends the program’s use of the file. Afterwards the record area is no longer available and an OPEN is needed before any other file statement. A successful CLOSE writes any buffered records out (and, for a GnuCOBOL line-sequential file, the final line delimiter). Several files may be named in one statement. The extra phrases belong to z/OS tape and QSAM practice: REEL or UNIT and FOR REMOVAL apply to multi-volume or tape files, WITH NO REWIND to tape, and WITH LOCK prevents the file from being opened again in the same run unit. None of REEL, UNIT or NO REWIND is valid for a VSAM file, and a new program on a disk should use plain CLOSE.

The program must close what it opened, in particular before it ends. Do not rely on the run time to close files at the end of the run: an implicit close hides errors, and an output file that was not closed properly may be missing its last records. STOP RUN after an explicit CLOSE leaves no doubt.

COBOL 2002 added record locking, and GnuCOBOL implements it: a LOCK MODE IS MANUAL or AUTOMATIC clause in the SELECT, WITH LOCK and WITH KEPT LOCK on READ, and the UNLOCK statement, with SHARING WITH to say who else may open the file. The manual says that record locking for indexed files needs a Berkeley DB build, and that a MinGW build gives up part of file sharing because the operating-system routines it needs do not exist there. The Enterprise COBOL 6.5 Language Reference has no LOCK MODE clause: sharing on z/OS is controlled by the DD statement (DISP=SHR or OLD) and, for VSAM, by the SHAREOPTIONS of the cluster, which are on Indexed Files and VSAM. A program that uses record locks is therefore not portable to z/OS.

Source: GnuCOBOL Programmer’s Guide: record locking; GnuCOBOL 3.2 manual