Compaq COBOL
User Manual
Previous Contents Index

In this example, the variable record's fixed portion size is 113 characters. (This is the sum of P-PART-NUM, P-PART-INFO, and P-BIN-INDEX.) If P-BIN-INDEX contains a 7 at execution time, P-BIN-NUMBER will be 35 characters long. Therefore, PARTS-REC's length will be 148 characters; the fixed portion's length is 113 characters, and the table entry's length at execution time is 35 characters.

Example 6-6 Creating Variable-Length Records and Using the OCCURS Clause with the DEPENDING ON Phrase 

     . 
     . 
     . 
FILE SECTION. 
FD  PARTS-MASTER 
    RECORD VARYING 118 TO 163 CHARACTERS. 
01  PARTS-REC. 
    03  P-PART-NUM     PIC X(10). 
    03  P-PART-INFO    PIC X(100). 
    03  P-BIN-INDEX    PIC 999. 
    03  P-BIN-NUMBER   PIC X(5) 
        OCCURS 1 TO 10 TIMES DEPENDING ON P-BIN-INDEX. 
     . 
     . 
     .

If you describe a record with both the RECORD VARYING...DEPENDING ON phrase on data-name-1 and the OCCURS clause with the DEPENDING ON phrase on data-name-2, Compaq COBOL specifies record length as the value of data-name-1.

If you have multiple record-length descriptions for a file and omit either the RECORD VARYING clause or the RECORD CONTAINS TO clause, all records written to the file will have a fixed length equal to the length of the longest record described for the file, as in Example 6-7.

Example 6-7 Defining Fixed-Length Records with Multiple Record Descriptions 

    . 
    . 
    . 
FD PARTS-MASTER. 
01  PARTS-REC-1   PIC X(200). 
01  PARTS-REC-2   PIC X(300). 
01  PARTS-REC-3   PIC X(400). 
01  PARTS-REC-4   PIC X(500). 
    . 
    . 
    . 
PROCEDURE DIVISION. 
    . 
    . 
    . 
100-WRITE-REC-1. 
    MOVE IN-REC TO PARTS-REC-1. 
    WRITE PARTS-REC-1. 
    GO TO ... 
200-WRITE-REC-2. 
    MOVE IN-REC TO PARTS-REC-2. 
    WRITE PARTS-REC-2. 
    GO TO ... 
    .                              
    . 
    .

Writing PARTS-REC-1, PARTS-REC-2, PARTS-REC-3 or PARTS-REC-4 produces records equal in length to the longest record, PARTS-REC-4. Note that this is not variable-length I/O.

6.1.3 Print-Control Records

Print-control files contain record-advancing information with each record. These files are intended for eventual printing, but are created on disk by your Compaq COBOL program. The compiler generates print-control records when you use the WRITE AFTER ADVANCING, the LINAGE, or the APPLY PRINT-CONTROL clause, or if you create a Report Writer file or use ASSIGN TO PRINTER (on Tru64 UNIX systems).

On OpenVMS Alpha, in any of the preceding cases, if you compile /NOVFC, the compiler does not generate print-control records, but generates stream files instead.

On OpenVMS, Compaq COBOL places explicit form-control bytes directly into the file. You must use the /NOFEED option on the DCL PRINT command to print a print-control file. <>

Stream (Alpha)

Stream files contain records of different length, delimited by a record terminator.

The compiler generates a stream record formatted file when you use the ORGANIZATION IS LINE SEQUENTIAL clause in the File-Control Division. This record format is useful for files created by text editors.

On OpenVMS Alpha, a stream file will also be generated under certain situations if you compiled /NOVFC. See Section B.4.3 for more information. <>

6.1.4 File Design

The difficulty of design is proportional to the complexity of the file organization. Before you create your sequential, relative, or indexed file applications, you should design your files based on these design considerations:

On OpenVMS, for more information about file design, see Chapter 15. For OpenVMS Alpha systems you can also refer to the Guide to OpenVMS File Applications. <> Chapter 15 contains instructions on optimizing the file design for indexed files. With indexed files, in particular, if you accept all the file defaults instead of carefully designing your file, your application may run more slowly than you expect.

6.2 Identifying Files and Records from Within Your Compaq COBOL Program

Before your program can perform I/O on a file, your program must identify the file to the operating system and specify the file's organization and access modes. A program must follow these steps whenever creating a new file or processing an existing file.

You use a file description entry to define a file's logical structure and associate the file with a file name that is unique within the program. The program uses this file name in the following COBOL statements:

The program uses the record name for the WRITE and REWRITE statements.

6.2.1 Defining a File Connector

You must establish a link between the file connector your program uses and the file specification that the I/O system uses. You create this link and define a file connector by using the SELECT statement with the ASSIGN clause and optionally specifying the VALUE OF ID clause or by using logical names or environment variables.

A file connector is a Compaq COBOL data structure that contains information about a file. The file connector links a file name and its associated record area to a physical file.

Defining a File Connector with SELECT and ASSIGN

Your program must include a SELECT statement, including an ASSIGN clause, for every file description entry (FD) it contains. The file name you specify in the SELECT statement must match the file name in the file description entry.

In the ASSIGN clause, you specify a nonnumeric literal or data name that associates the file name with a file specification. This value must be a complete file specification.

Example 6-8 and Example 6-9 show the relationships between the SELECT statement, the ASSIGN clause, and the FD entry.

In Example 6-8, because the file name specified in the FD entry is DAT-FILE, all I/O statements in the program referring to that file or to its associated record must use the file name DAT-FILE or the record name DAT-RECORD. The I/O system uses the ASSIGN clause to interpret DAT-FILE as REPORT.DAT on OpenVMS systems, and REPORT on Tru64 UNIX systems. The default directory will be used on OpenVMS systems, and the current working directory will be used on Tru64 UNIX systems.

Example 6-8 Defining a Disk File 

ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
    SELECT DAT-FILE 
           ASSIGN TO "REPORT". 
           . 
           . 
           . 
DATA DIVISION. 
FILE SECTION. 
FD  DAT-FILE. 
01  DAT-RECORD PIC X(100). 
           . 
           . 
           .

Note
On OpenVMS systems, if no file type is supplied, Compaq COBOL supplies the default file extension DAT. On Tru64 UNIX systems, the extensions dat and idx are appended, but only in the case of indexed files.

The I/O statements in Example 6-9 refer to MYFILE-PRO, which the ASSIGN clause identifies to the operating system as MARCH.311. Additionally, the operating system looks for the file in the current directory on the magnetic tape mounted on MTA0: on an OpenVMS system.

Example 6-9 Defining a Magnetic Tape File (OpenVMS) 

ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
    SELECT MYFILE-PRO 
           ASSIGN TO "MTA0:MARCH.311" 
           . 
           . 
           . 
DATA DIVISION. 
FILE SECTION. 
FD  MYFILE-PRO. 
01  DAT-RECORD PIC X(100). 
           . 
           . 
           . 
PROCEDURE DIVISION. 
A000-BEGIN. 
    OPEN INPUT MYFILE-PRO. 
           . 
           . 
           . 
    READ MYFILE-PRO AT END DISPLAY "end". 
           . 
           . 
           . 
    CLOSE MYFILE-PRO.   <>

Example 6-10 achieves the same result as Example 6-9, but on Tru64 UNIX. The I/O statements in Example 6-10 refer to MYFILE-PRO, which the ASSIGN clause identifies to the operating system as a magnetic tape file. The file is named in the Data Division VALUE OF ID clause as MARCH.311.

Example 6-10 Defining a Magnetic Tape File (Tru64 UNIX) 

ENVIRONMENT DIVISION 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 
    SELECT MYFILE-PRO 
           ASSIGN TO REEL. 
           . 
           . 
           . 
DATA DIVISION. 
FILE SECTION. 
FD MYFILE-PRO VALUE OF ID "MARCH.311". 
01  DAT-RECORD PIC X(100). 
           . 
           . 
           . 
PROCEDURE DIVISION. 
A000-BEGIN. 
    OPEN INPUT MYFILE-PRO. 
           . 
           . 
           . 
    READ MYFILE-PRO AT END DISPLAY "end". 
           . 
           . 
           . 
    CLOSE MYFILE-PRO.

For each OPEN verb referring to a file assigned to magnetic tape, the user is prompted to assign the file to a magnetic tape device. These device names are in the form /dev/rmt0(a,l,m,h) ... /dev/rmt31(a,l,m,h) and correspond to special files on the system that refer to mass storage tape devices. For more information on tape devices, refer to the mtio(7) Tru64 UNIX manual page.

As an alternative to prompting, each file assigned to a magnetic tape can have its associated tape device defined through a shell environment variable. The name of this environment variable is the concatenation of COBOL_TAPE_ and the base of the file name used in the COBOL program. The value of this environment variable is the name of the desired tape device. The environment variable needed in Example 6-10 to assign the MARCH.311 file to tape device /dev/rmt0a is: 


 % setenv COBOL_TAPE_MARCH /dev/rmt0a     <>

Establishing File Names with ASSIGN and VALUE OF ID

If the file specification is subject to change, you can use a partial file specification in the ASSIGN clause and complete it by using the optional VALUE OF ID clause of the FD entry. In the VALUE OF ID clause, you can specify a nonnumeric literal or an alphanumeric WORKING-STORAGE item to supplement the file specification.

VALUE OF ID can complete a file name specified in ASSIGN TO: 


  ASSIGN TO "filename" 
  VALUE OF ID ".ext"

In the above example, OPEN would create a file with the name "filename.ext".

VALUE OF ID can override a file name specified in ASSIGN TO: 


  ASSIGN TO "oldname" 
  VALUE OF "newname"
In the above example, OPEN would create a file with the name newname.

VALUE OF ID can be a directory/device specification and ASSIGN TO can provide the file name, as in the following example: 


  ASSIGN TO "filename.dat" 
  VALUE OF ID "/usr/" 
       
       or 
       
  ASSIGN TO "filename" 
  VALUE OF ID "DISK:[DIRECTORY]"

On OpenVMS, with this code OPEN would create a file with the name DISK:[DIRECTORY]FILENAME.DAT. <>

On Tru64 UNIX, with this code OPEN would create a file with the name "/usr/filename.dat". <>

Establishing Device and File Independence with Logical Names on OpenVMS

On OpenVMS, logical names let you write programs that are device and file independent and provide a brief way to refer to frequently used files.

You can assign logical names with the ASSIGN command. When you assign a logical name, the logical name and its equivalence name (the name of the actual file or device) are placed in one of three logical name tables; the choice depends on whether they are assigned for the current process, on the group level, or on a systemwide basis. Refer to the OpenVMS DCL Dictionary for more information on DCL and a description of logical name tables.

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

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

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

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

Example 6-11 Using Environment Variables (Tru64 UNIX) or Logical Names (OpenVMS) 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. 
 
       On Tru64 UNIX, set an environment variable as follows: 
      
       % cobol -o envtest envvar-example.cob 
       % setenv MYENV hello.dat 
       % envtest 
       % ls *.dat 
       hello.dat 
       % unsetenv MYENV 
       % envtest 
       % ls MY* 
       MYENV   <>

Setting environment variables at run time can help in moving applications between OpenVMS Alpha and Tru64 UNIX platforms without having to modify their source COBOL programs. 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. Thus, in Example 6-11, the program is applicable to either Tru64 UNIX or to OpenVMS, because MYENV can refer to an environment variable or to a logical name.

Example 6-12 is another program that can be used on either system, depending on the definition at system level of an environment variable or logical name, as appropriate.

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, would produce a file with the name "ENVTEST.DAT". On Tru64 UNIX, "SYS$SCRATCH:" has no meaning because it is a OpenVMS logical. OpenVMS 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 (Alpha), 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 information, refer to 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:

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 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-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-16 defines a line sequential (Alpha) file.

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

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.

Previous Next Contents Index