File Organizations

File Status

Chapter 3: Filenames

This chapter covers:

• Filename conventions
  
  
• Assigning filenames
  
  
• Filename mapping
  
  
• The search sequence employed by the run-time system to find dynamically or externally assigned files.

3.1 Filename Conventions

This COBOL system, and applications created with it, use the standard UNIX filename conventions.

3.2 Assigning Filenames

The ASSIGN clause in the SELECT statement is used to specify either a physical filename or a logical name which can be mapped to a physical name at run time.

There are three types of filename assignment:

• STATIC

  The filename is specified as a literal in the ASSIGN clause of the SELECT statement.

• DYNAMIC

  The filename is specified as a data-item in the ASSIGN clause of the SELECT statement, and so can be changed by the program at run time.

• EXTERNAL

  The filename is specified as EXTERNAL in the ASSIGN clause of the SELECT statement and is resolved at run time.

Run-time mapping of filenames is available for all three types of filename assignment.

3.2.1 Static Filename Assignment

With static filename assignment, the filename is specified in the SELECT statement as a literal:

select filename
   assign to literal.

In the following example, opening stockfile causes the warehs.buy file in the current directory to be opened:

select stockfile
   assign to "warehs.buy".

In this example, opening input-file opens the file prog in the data directory (relative to the current directory):

select input-file
   assign to "data/prog".

3.2.2 Dynamic Filename Assignment

With dynamic filename assignment, the filename is specified in the SELECT statement as a COBOL data item:

select filename
   assign to dynamic data-item

where the parameter is:

If you use the ASSIGN"DYNAMIC" Compiler directive, you can omit the word DYNAMIC from the ASSIGN clause.

In the following example, the file input.dat is created in the current directory:

...
select fd-in-name
   assign to dynamic ws-in-file.
...
working-storage section.
01 ws-in-file     pic x(30).
...
move "input.dat" to ws-in-file.
...
open output fd-in-name.

3.2.3 External Filename Assignment

With external filename assignment, the filename is specified in the SELECT statement as follows:

select filename
   assign to external external-file-reference

where the parameter is:

See the section Filename Mapping for further details on run-time filename mapping.

3.3 Filename Mapping

This COBOL system provides several ways of mapping the filename supplied by the program via the ASSIGN clause onto a different name, for greater flexibility at run time.

When the File Handler is presented with a filename (which may be a literal, the contents of a data item, or, in the case of the ASSIGN TO EXTERNAL syntax, an external reference), it isolates the first element of that name, that is, all the text before the first slash character (/), all the text if the name does not include such a character, or nothing if the filename starts with a slash character. Having done that, it:

• Removes the leading dollar character ($) if it is present, prefixes the characters "dd_" to this first element and searches for an environment variable with this name.
  
  
• If it does not find this environment variable and either the ASSIGN EXTERNAL syntax was used or the first element of the filename began with a dollar character, it looks for an environment variable with the same name as the first element (minus the leading dollar character if present).
  
  
• If the search is unsuccessful, the original filename is left unchanged, except in the case where the name begins with a dollar character and contains at least one slash character. In this case, the whole of the first element, together with the first slash is removed from the name.

The result is then considered to be the filename of the physical file.

Consider the following examples:

Although the period ( . ) is not allowed in the names of environment variables, it is often used in filenames, so you may want to map logical filenames containing this character. In this case, you must replace the "." with the underscore character ( _ ). For example:

dd_file_PNT=/usr/qa/myfile.pnt

refers to the logical filename file.PNT.

3.3.1 Multiple Paths

An environment variable used for filename mapping can specify multiple pathnames. This causes the system to search for subsequent files if a "file not found" condition is returned for the first path specified by the environment variable.

Consider the following example contents of an environment variable named dd_dir:

dd_dir=/a/b;/c/d;

This causes the system to search /c/d for the assigned file if a "file not found" condition is returned on /a/b.

Notes:

• For files opened I/O, OUTPUT, or EXTEND, if the file is not found on any part of the path, it will be created in the first directory in the search sequence.
  
  
• The length of each path in a dd_ path list must be less than or equal to the permitted maximum number of characters for a path.

3.4 Assignment of Operating System Device Names

You can write a COBOL program to send a report directly to the printer, or to transfer data across a communications port. To do this, you need to assign a device-name to your COBOL filename.

The following device-names can be specified using static, dynamic or external filename assignment:

When specifying any of these device-names, a trailing colon(:) is optional.

In the following example, read or write operations on fd-name cause data to be read from or written to the console screen:

select fd-name
   assign to "con".

In this example, write operations on fd-name cause data to be output to lpt1:, the first parallel printer:

select fd-name
   assign to dynamic ws-filename.
   ...
   move "lpt1:" to ws-filename.

3.4.1 Setting Up Pipes

You can use COBOL file syntax to launch another process (such as the dir command) and either write data to the standard input of that other process, or read data coming from the standard output of the other process. The COBOL file organization must be either LINE SEQUENTIAL or RECORD SEQUENTIAL.

3.4.1.1 Output Pipes

To launch a process and write data to its standard input, the filename must consist of the > sign followed by the name of the command. The file should be opened for output.

For example:

select output-file
   assign to ">lpr"
   organization is line sequential.
...
open output output-file
write output-file-record from "Hello world".

In this example the program passes the characters "Hello world" to the standard input of the print process.

3.4.1.2 Input Pipes

To launch a process and read data from its standard output, the filename must consist of the "lt" symbol followed by the name of the command. The file should be opened for input.

For example:

select input-file
   assign to "<ls"
   organization is line sequential.
...
open input input-file
read input-file

In this example the program launches the ls process and reads in the first line which that process writes to its standard output.

3.4.1.3 Two-way Pipes

Two-way pipes combine the functions of input and output pipes. To use a two-way pipe the filename must consist of the pipe symbol (|) followed by the name of the command. The file should be opened for input-output (i-o).

For example:

select i-o-file
   assign to "| sort"
   organization is line sequential.
...
   open i-o i-o-file
   write i-o-file-record from "Hello world"
   read i-o-file

In this example the program launches the sort process and passes the line "Hello world" to its standard input. It then reads one record from the standard output of the sort process.

File Organizations

File Status