To translate a logical name, the system searches the three tables in this order: (1) process, (2) group, (3) system. Therefore, you can override a systemwide logical name by defining it for your group or process.

Logical name translation is a recursive procedure: when the system translates a logical name, it uses the equivalence name as the argument for another logical name translation. It continues in this way until it cannot translate the equivalence name.

Assume that your program updates monthly sales files (for example, JAN.DAT, FEB.DAT, MAR.DAT, and so forth). Your SELECT statement could look like either of these:

SELECT SALES-FILE ASSIGN TO "MOSLS" SELECT SALES-FILE ASSIGN TO MOSLS

To update the January sales file, you can use this ASSIGN command to equate the equivalence name JAN.DAT with the logical name MOSLS:

$ ASSIGN JAN.DAT MOSLS

To update the February sales file, you can use this ASSIGN command:

$ ASSIGN FEB.DAT MOSLS

In the same way, all programs that access the monthly sales file can use the logical name MOSLS.

To disassociate the relationship between the file and the logical name, you can use this DEASSIGN command:

$ DEASSIGN MOSLS

If MOSLS is not set as a logical name, the system uses it as a file specification and looks for a file named MOSLS.DAT. <>

Using Environment Variables for File Specification

On Tru64 UNIX, environment variables can be used as aliases for file specification at run time. File name resolution follows these rules:

• Use contents of the ASSIGN TO clause or VALUE OF ID clause to find a match against an environment variable.
• If a match is found, substitute the value of the environment variable in the construction of the file specification.
• If a match was not found, take the file name as specified.

On Tru64 UNIX, you can also use the literal or alphanumeric item to specify a run-time environment variable set. See setenv(3) in the reference page. <>

Example 6-11 and the commands that follow it illustrate how to use the ASSIGN TO clause in conjunction with an environment variable.

Example 6-11 Using Environment Variables for File Specification

IDENTIFICATION DIVISION. PROGRAM-ID. ENVVAR-EXAMPLE. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT F-DISK ASSIGN TO "MYENV". DATA DIVISION. FILE SECTION. FD F-DISK. 01 DAT-RECORD PIC X(100). PROCEDURE DIVISION. P0. OPEN OUTPUT F-DISK. CLOSE F-DISK. PE. STOP RUN. END PROGRAM ENVVAR-EXAMPLE. % cobol -o envtest envvar-example.cob % setenv MYENV hello.dat % envtest % ls *.dat hello.dat % unsetenv MYENV % envtest % ls MY* MYENV

The flexibility of setting environment variables at run time will help you migrate OpenVMS Alpha applications to Tru64 UNIX because you can define environment variables that access files in a way similar to that in which you access files using logical names on OpenVMS systems.

Example 6-12 Using Environment Variables

IDENTIFICATION DIVISION. PROGRAM-ID. ENVVAR-EXAMPLE2. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT F-DISK ASSIGN TO "SYS$SCRATCH:envtest.dat". DATA DIVISION. FILE SECTION. FD F-DISK VALUE OF ID "SYS$DISK:". 01 DAT-RECORD PIC X(100). PROCEDURE DIVISION. P0. OPEN OUTPUT F-DISK. CLOSE F-DISK. PE. STOP RUN. END PROGRAM ENVVAR-EXAMPLE2.

Example 6-12, on OpenVMS Alpha, would produce a file with the name "ENVTEST.DAT". On Tru64 UNIX, "SYS$SCRATCH:" has no meaning because it is a OpenVMS Alpha logical. OpenVMS Alpha logicals are not defined on Tru64 UNIX. However, the "SYS$SCRATCH:" in the ASSIGN clause can be defined as an environment variable with the following command:

% setenv 'SYS$SCRATCH:' ./

This would make "SYS$SCRATCH" point to the home directory. This can be used for any OpenVMS logicals used in the Compaq COBOL source. When you declare an environment variable you should be careful to match the case of what is in the Compaq COBOL source with the setenv(3) line. <>

6.2.2 Specifying File Organization and Record Access Mode

Your program must state---either explicitly or implicitly---a file's organization and record access mode before the program opens the file. The Environment Division ORGANIZATION and ACCESS MODE clauses, if present, specify these two characteristics.

In a Compaq COBOL program, each file is given a file name in a separate Environment Division SELECT statement. The compiler determines the file organization from the SELECT statement and its associated clauses.

For relative and indexed files, you must specify the ORGANIZATION IS RELATIVE or the ORGANIZATION IS INDEXED phrase, respectively. For sequential files you need not specify the ORGANIZATION IS SEQUENTIAL phrase. For line sequential files you must explicitly declare ORGANIZATION IS LINE SEQUENTIAL. When you omit the ORGANIZATION IS clause the file organization is sequential.

The ASSIGN clause, in the SELECT statement, associates the file name with a file specification. The file specification points the operating system to the file's physical and logical location on a specific hardware device.

The SELECT statement and the ASSIGN clause are further described in Section 6.2.1. For further reference, see the Compaq COBOL Reference Manual.

Each file is further described with a file description (FD) entry in the Data Division File Section. The FD entry is followed immediately by the file's record description.

You can specify additional file characteristics in the Environment and Data Divisions as follows:

• Use the Environment Division APPLY clause to specify file characteristics such as lock-holding, file extension factors, and preallocation factors. (See Chapter 15.)
• Use file description entries to specify record format and record blocking.
• Use record description entries to specify physical record size or sizes.

Examples 6-13, 6-14, and Example 6-15 illustrate how to specify the file organization and access mode for sequential, relative, and indexed files.

Example 6-13 Specifying Sequential File Organization and Sequential Access Mode for a Sequential File

IDENTIFICATION DIVISION. PROGRAM-ID. SEQ01. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MASTER-FILE ASSIGN TO "MASTER.DAT". SELECT TRANS-FILE ASSIGN TO "TRANS.DAT". SELECT REPRT-FILE ASSIGN TO "REPORT.DAT". DATA DIVISION. FILE SECTION. FD MASTER-FILE. 01 MASTER-RECORD. 02 MASTER-DATA PIC X(80). 02 MASTER-SIZE PIC 99. 02 MASTER-TABLE OCCURS 0 to 50 TIMES DEPENDING ON MASTER-SIZE. 03 MASTER-YEAR PIC 99. 03 MASTER-COUNT PIC S9(5)V99. FD TRANS-FILE. 01 TRANSACTION-RECORD PIC X(25). FD REPRT-FILE. 01 REPORT-LINE PIC X(132).

Example 6-14 Specifying Relative File Organization and Random Access Mode for a Relative File

IDENTIFICATION DIVISION. PROGRAM-ID. REL01. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT FLAVORS ASSIGN TO "BRAND" ORGANIZATION IS RELATIVE ACCESS MODE IS RANDOM RELATIVE KEY IS KETCHUP-MASTER-KEY. DATA DIVISION. FILE SECTION. FD FLAVORS. 01 KETCHUP-MASTER PIC X(50). WORKING-STORAGE SECTION. 01 KETCHUP-MASTER-KEY PIC 99.

Example 6-15 Specifying Indexed File Organization and Dynamic Access Mode for an Indexed File

IDENTIFICATION DIVISION. PROGRAM-ID. INDEX01. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT FLAVORS ASSIGN TO "DAIRY" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS ICE-CREAM-MASTER-KEY ALTERNATE RECORD KEY IS ICE-CREAM-STORE-STATE WITH DUPLICATES ALTERNATE RECORD KEY IS ICE-CREAM-STORE-CODE. DATA DIVISION. FILE SECTION. FD FLAVORS. 01 ICE-CREAM-MASTER. 02 ICE-CREAM-MASTER-KEY PIC XXXX. 02 ICE-CREAM-MASTER-DATA. 03 ICE-CREAM-STORE-CODE PIC XXXXX. 03 ICE-CREAM-STORE-ADDRESS PIC X(20). 03 ICE-CREAM-STORE-CITY PIC X(20). 03 ICE-CREAM-STORE-STATE PIC XX. PROCEDURE DIVISION. A00-BEGIN. . . .

Example 6-15 defines a dynamic access mode indexed file with one primary key and two alternate record keys. Note that one alternate record key allows duplicates. Any program using the identical entries in the SELECT clause as shown in Example 6-15 can reference the DAIRY file sequentially and randomly. Refer to the Compaq COBOL Reference Manual for information relating to the RECORD KEY and ALTERNATE RECORD KEY clauses.

Example 6-16 defines a line sequential file.

Example 6-16 Specifying Line Sequential File Organization with Sequential Access Mode

IDENTIFICATION DIVISION. PROGRAM ID. EX0616. ENVIRONMENT DIVISION. INOUT-OUTPUT SECTION. FILE-CONTROL. SELECT MUSIC ASSIGN TO "CLASSICAL" ORGANIZATION IS LINE SEQUENTIAL. DATA DIVISION. FILE SECTION. FD MUSIC. 01 OPERA PIC X(9). PROCEDURE DIVISION. A00-BEGIN. . . .

File organization is discussed in more detail in Section 6.1.1. Record access mode is discussed in the following section.

Record Access Mode

The methods for retrieving and storing records in a file are called record access modes. Compaq COBOL supports the following three types of record access modes:

• ACCESS MODE IS SEQUENTIAL
  • With sequential files, sequential access mode retrieves the records in the same sequence established by the WRITE statements that created the file.
  • With relative files, sequential access mode retrieves the records in the order of ascending record key values (or relative record numbers).
  • With indexed files, sequential access mode retrieves records in the order of record key values.
• ACCESS MODE IS RANDOM---The value of the record key your program specifies indicates the record to be accessed in Indexed and Relative files.
• ACCESS MODE IS DYNAMIC---With relative and indexed files, dynamic access mode allows you to switch back and forth between sequential access mode and random access mode while reading a file by using the the NEXT phrase on the READ statement. For more information about dynamic access mode, see READ and REWRITE statements in the Compaq COBOL Reference Manual.

When you omit the ACCESS MODE IS clause in the SELECT statement, the access mode is sequential.

Example 6-17 shows sample SELECT statements for sequential files with sequential access modes.

Example 6-17 SELECT Statements for Sequential Files with Sequential Access Mode

(1) (2) FILE-CONTROL. FILE-CONTROL. SELECT LIST-FILE SELECT PAYROLL ASSIGN TO "MAIL.LIS" ASSIGN TO "PAYROL.DAT". ORGANIZATION IS SEQUENTIAL ACCESS IS SEQUENTIAL.

Sample SELECT statements for relative files with sequential and dynamic access modes are shown in Example 6-18.

Example 6-18 SELECT Statements for Relative Files with Sequential and Dynamic Access Modes

(1) (2) FILE-CONTROL. FILE-CONTROL. SELECT MODEL SELECT PARTS ASSIGN TO "ACTOR.DAT" ASSIGN TO "PART.DAT" ORGANIZATION IS RELATIVE ORGANIZATION IS RELATIVE ACCESS MODE IS SEQUENTIAL. ACCESS MODE IS DYNAMIC RELATIVE KEY IS PART-NO.

Sample SELECT statements for indexed files with dynamic and sequential access modes are shown in Example 6-19.

Example 6-19 SELECT Statements for Indexed Files with Dynamic and Default Sequential Access Modes

(1) (2) FILE-CONTROL. FILE-CONTROL. SELECT A-GROUP SELECT TEAS ASSIGN TO "RFCBA.PRO" ASSIGN TO "TEA" ORGANIZATION IS INDEXED ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS LEAVES. RECORD KEY IS WRITER ALTERNATE RECORD KEY IS EDITOR.

Because the default file organization is also sequential, both the relative and indexed examples require the ORGANIZATION IS clause.

Sample SELECT statements for line sequential files with sequential access modes are shown in Example 6-20.

Example 6-20 SELECT Statements for Line Sequential Files with Sequential Access Modes

(1) (2) FILE-CONTROL. FILE-CONTROL. SELECT MAMMALS SELECT VACATION-SPOTS ASSIGN TO "DOLPHINS" ASSIGN TO "BAHAMAS" ORGANIZATION IS LINE SEQUENTIAL ORGANIZATION IS LINE SEQUENTIAL. ACCESS MODE IS SEQUENTIAL.

6.3 Creating and Processing Files

Creating and processing sequential, line sequential, relative, and indexed files includes the following tasks:

1. Opening the file
2. Executing valid I/O statements
3. Closing the file

Sections 6.3.2, 6.3.3, and 6.3.4 describe the specific tasks involved in creating and processing sequential, relative, and indexed files.

6.3.1 Opening and Closing Files

A Compaq COBOL program must open a file with an OPEN statement before any other I/O or Report Writer statement can reference it. Files can be opened more than once in the same program as long as they are closed before being reopened.

Sample OPEN and CLOSE statements are shown in Example 6-21.

Example 6-21 OPEN and CLOSE Statements

. . . OPEN INPUT MASTER-FILE. OPEN OUTPUT REPORT-FILE. OPEN I-O MASTER-FILE2 TRANS-FILE OUTPUT REPORT-FILE2. CLOSE MASTER-FILE. CLOSE TRANS-FILE, MASTER-FILE2 REPORT-FILE, REPORT-FILE2. . . .

The OPEN statement must specify one of the following four open modes:

INPUT
OUTPUT
I-O {Not for LINE SEQUENTIAL}
EXTEND

Your choice, along with the file's organization and access mode, determines which I/O statements you can use. Sections 6.3.2, 6.3.3, and 6.3.4 discuss the I/O statements for sequential, relative, and indexed files, respectively. Section 12.8.4, Case Sensitivity on Tru64 UNIX and Windows NT explains the importance of attention to case.

When your program performs an OPEN statement, the following events take place:

1. The I/O system builds a file specification by using the contents of the VALUE OF ID clause, if any, to alter or complete the file specification in the ASSIGN clause. Logicals and environment variables are translated.
2. The I/O system checks the file's current status. If the file is unavailable, or if it was closed WITH LOCK, the OPEN statement fails. (See Chapter 8 for information on file sharing.)
3. If the file specification names an invalid device, or contains any other errors, the I/O system generates an error message and the OPEN statement fails.
4. The I/O system takes one of the following actions if it cannot find the file:
   1. If the file's OPEN mode is OUTPUT, the file is created.
   2. If the file's OPEN mode is EXTEND, or I-O, the OPEN statement fails, unless the file's SELECT clause includes the OPTIONAL phrase. If the file's SELECT clause includes the OPTIONAL phrase, the file is created.
   3. If the file's OPEN mode is INPUT, and its SELECT clause includes the OPTIONAL phrase, the OPEN statement is successful. The first read on that file causes the AT END or INVALID KEY condition.
   4. If none of the previous conditions is met, the OPEN fails and the Declarative USE procedure (if any) gains control. If no Declarative USE procedure exists, the I/O system aborts the program.
5. If the file's OPEN mode is OUTPUT, and a file by the same name already exists, a new version is created.
6. If the file characteristics specified by the program attempting an OPEN operation differ from the characteristics specified when the file was created, the OPEN statement fails.

If the file is on magnetic tape, the I/O system rewinds the tape. (To close a file on tape without rewinding the tape, use the NO REWIND phrase.) This speeds processing when you want to write another file beyond the end of the first file, as in the following example:

CLOSE MASTER-FILE NO REWIND.

You can also close a file and prevent your program from opening that file again in the same run, as in the following example:

CLOSE MASTER-FILE WITH LOCK.

6.3.2 File Handling for Sequential and Line Sequential Files

Creating a sequential or line sequential file involves the following:

1. Opening the file for OUTPUT or EXTEND
2. Executing valid I/O statements
3. Closing the file

By default, Compaq COBOL assumes sequential organization and sequential access mode. (See Example 6-22.)

Example 6-22 Creating a Sequential File

IDENTIFICATION DIVISION. PROGRAM-ID. SEQ01. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT TRANS-FILE ASSIGN TO "TRANS.DAT". DATA DIVISION. FILE SECTION. FD TRANS-FILE. 01 TRANSACTION-RECORD PIC X(25). PROCEDURE DIVISION. A000-BEGIN. OPEN OUTPUT TRANS-FILE. PERFORM A010-PROCESS-TRANS UNTIL TRANSACTION-RECORD = "END". CLOSE TRANS-FILE. STOP RUN. A010-PROCESS-TRANS. DISPLAY "Enter next record - X(25)". DISPLAY "enter END to terminate the session". DISPLAY "-------------------------". ACCEPT TRANSACTION-RECORD. IF TRANSACTION-RECORD NOT = "END" WRITE TRANSACTION-RECORD.

Example 6-23 Creating a Line Sequential File

IDENTIFICATION DIVISION. PROGRAM-ID. LINESEQ01. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT LINESEQ-FILE ASSIGN TO "LINESEQ.DAT". DATA DIVISION. FILE SECTION. FD LINESEQ-FILE. 01 LINESEQ-RECORD PIC X(25). PROCEDURE DIVISION. A000-BEGIN. OPEN OUTPUT LINESEQ-FILE. CLOSE LINESEQ-FILE. STOP RUN.

By default, Compaq COBOL assumes sequential access mode when the line sequential organization is specified. (See Example 6-23.)

Statements for Sequential and Line Sequential File Processing

Processing a sequential or line sequential file involves the following:

1. Opening the file
2. Processing the file with valid I/O statements
3. Closing the file

Table 6-3 lists the valid I/O statements for sequential files, and Table 6-4 lists the valid I/O statements for line sequential files. Both tables illustrate the following relationships:

• Organization determines valid access modes.
• Organization and access mode determine valid open modes.
• All three (organization, access, and open mode) enable or disable I/O statements.

Table 6-3 Valid I/O Statements for Sequential Files

			Open Mode
File Organization	Access Mode	Statement	INPUT	OUTPUT	I/O	EXTEND
SEQUENTIAL	SEQUENTIAL	READ	Yes	No	Yes	No
		REWRITE	No	No	Yes	No
		WRITE	No	Yes	No	Yes
		UNLOCK	Yes	Yes	Yes	Yes

Writing a Sequential File

Each WRITE statement appends a logical record to the end of an output file, thereby creating an entirely new record in the file. The WRITE statement appends records to files that are OPEN for the following modes:

• OUTPUT---Output mode can create the following two kinds of files:
  • Storage files---A storage file remains on tape or disk for future reference or processing.
  • Print-control files---The Data Division LINAGE clause, the Environment Division APPLY PRINT-CONTROL clause, the Procedure Division ADVANCING phrase (in the WRITE statement), or Report Writer statements and phrases designates a file as a print-control file.
    On OpenVMS Alpha, each record in a print-control file contains a header that performs line spacing. On Tru64 UNIX and Windows NT, line spacing is done with blank records in print-control files.
• EXTEND---Extend mode permits new records to be added in sequence after the last record of an existing file (see Extending a Sequential or Line Sequential File in Section 6.5.1).

Table 6-4 Valid I/O Statements for Line Sequential Files

			Open Mode
File Organization	Access Mode	Statement	INPUT	OUTPUT	EXTEND
LINE SEQUENTIAL	SEQUENTIAL	READ	Yes	No	No
		WRITE	No	Yes	Yes
		UNLOCK	Yes	Yes	Yes

Writing a Line Sequential File

Each WRITE statement appends a logical record to the end of an output file, thereby creating an entirely new record in the file. The WRITE statement appends records to files that are OPEN for the following modes:

• OUTPUT---Output mode creates a new file or overwrites an already existing file.
• EXTEND---Extend mode permits new records to be added in sequence after the last record of an existing file (see Extending a Sequential or Line Sequential File.

You can write records in the following two ways:

• WRITE record-name FROM source-area
• WRITE record-name