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

Filename Conventions

This COBOL system, and applications created with it, use the standard filename conventions of the operating system on which it runs.

This COBOL system also supports the New Technology File System (NTFS) file naming conventions. This means that each file or directory can consist of up to 254 characters and contain both space characters, other special characters and any number of periods (.). This COBOL system regards any text following the final period as an extension (or a trailing period as a space extension) and may remove it when creating its own names.

If you are thinking of using the new file naming conventions, you should be aware of the following:

Avoid using the following characters when you are creating Internet applications: % # ( ) @.
The Oracle 1.8 version of Pro*Cobol does not support filenames that contain spaces.

Assigning Filenames

The ASSIGN clause in the SELECT clause 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
DYNAMIC
The filename is specified as a data-item in the ASSIGN clause, and so can be changed by the program at run time
EXTERNAL
The filename is specified as EXTERNAL in the ASSIGN clause and is resolved at run time

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

Static Filename Assignment

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

 select filename
     assign to literal.

If the filename of the physical file that you are creating contains spaces, the filename is automatically surrounded by quotes for you.

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

 select stockfile
     assign to "b:warehs.buy".

In this example, a WRITE statement causes data to be output to prn:, the first parallel printer:

 select printfile
     assign to "prn:".

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

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

Dynamic Filename Assignment

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

 select filename
     assign to dynamic data-item

where the parameters are:

filename	The filename of the file that is to be assigned.
data-item	The name of a COBOL data item. If the data item is not explicitly declared in your program, the Compiler creates one for you, with a picture of PIC X(255). Before the OPEN statement for the file is executed, the program must give a value to the data item.

If the filename of the physical file that you are creating contains spaces, you should surround the filename with quotes (see Example 3-2 below).

Example 1

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.

Example 2

The following example shows how to use quotes to create the file spacey filename.dat, where the filename contains spaces:

 select f1
      assign to dynamic f1-name.
... 
working-storage section.
01 f1     pic x(30).
...
move """spacey  filename.dat""" to f1-name
....
open output f1.

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

External Filename Assignment

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

 select filename
     assign to external external-file-reference

where the parameters are:

filename	The filename of the file that is to be assigned.
external-file-reference	A COBOL word that identifies the specified file to the external environment for possible further mapping. If external-file-reference contains one or more hyphens, all characters up to and including the last hyphen are ignored.

For further details on run-time system filename mapping, see the section Filename Mapping.

Library Names in Paths

You can include a library name in the name of a file you want to open. The file specification is of the form:

 device\library-name.lbr\filename.ext

Example

c:\appdir\applib.lbr\app.dat

This type of filename is only valid when used as the name of a data file being opened in read-only mode, using either OPEN INPUT syntax or the CBL_OPEN_FILE byte stream routine. If the library is not already open, this call will open that library on the given device and leave it open after the call. If the library does not exist, or if the given filename.ext does not exist in that library, a "file not found" error is returned.

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. These rely on the use of environment variables.

In the following discussion the term "environment variable" should be read as including the Micro Focus extended environment variables which are enabled via use of the External File Mapper (see the section External File Mapper (Mfextmap) later in this chapter).

Before you run the program, you should give any environment varables you are using an appropriate value using the operating system SET command, for example:

set dir=d2

When 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), the File Handler follows this procedure:

Isolates the first element of the filename, 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.
If the first element begins with two dollar characters ($$), indicating that the file is located on a Fileshare server, switches the search process to that Fileshare server, and continues the filename mapping process with the next element.
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 element began with a dollar character, looks for an environment variable with the same name as the element (minus the leading dollar character if present).
If the search is unsuccessful, leaves the element unchanged, except in the case where the element begins with a dollar character and the whole filename 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.

This procedure is then repeated for the next element in the filename, and continues until all the elements in the name have been processed. The result is then considered to be the filename of the physical file.

Consider the following examples:

Filename in ASSIGN Clause	Environment Variables Searched For	Contents of Environment Variable	Filename of Physical File
dir\file1	dd_dir	d2	d2\file1
$dir\file1	dd_dir;dir	d2\d4	d2\d4\file1
dir1\dir2\file1	dd_dir1	d4	d4\dir2\file1
$dir1\$dir2\file1	First iteration: dd_dir1;dir1 Second iteration: dd_dir2;dir2	dd_dir1 or dir1: d2\d4 dd_dir2 or dir2: d3	d2\d4\d3\file1
file1	dd_file1	d2	d2

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:

If an existing file is being opened, using OPEN INPUT, OPEN I-O, OPEN EXTEND or the CBL_OPEN_FILE byte stream routine, the environment variable is expanded to the first path on which the file is found.
If a new file is being created, using OPEN OUTPUT, OPEN I-O, OPEN EXTEND, or the CBL_CREATE_FILE byte stream routine, the environment variable is expanded to the first path named. For files which are opened with OPEN OUTPUT, you can override this behavior by setting the SEARCHONCREATE File Handler configuration option to ON.
The length of each path in a path list in an environment variable must be less than or equal to the permitted maximum number of characters for a path.

Library Names

You can include library names in a multiple path environment variable. For example, if you have issued the command:

set test=c:\apdir;d:\aplbr\aplbr.lbr;d:\aplbr\aplbr1.lbr

the filename $test\app.dat would be resolved to d:\aplbr\aplbr.lbr\app.dat if c:\apdir\app.dat did not exist.

The libraries are searched in the order they appear in the environment variable.

You can also specify a library as part of the search path for program calls. For example, if you have issued the command

set appath=d:\apdir\progs1.lbr;d:\appdir\progs2.lbr

you can use the format:

call "$appath\prog"

Your COBOL development system will search the libraries progs1.lbr and progs2.lbr for the program prog1. The libraries are searched in the order they appear in the environment variable. Any library searched remains open during the execution of the application, unless the application itself explicitly closes it.

Assigning 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.

You can specify the following device-names using static, dynamic or external filename assignment:

Device-name	Description
CON	Console keyboard or screen
PRN	First parallel printer
LPT1	First parallel printer
LPT2	Second parallel printer
LPT3	Third parallel printer
COM1	First asynchronous communications port
COM2	Second asynchronous communications port

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 the next 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.

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.

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 ">cmd /c sort"
     organization is line sequential.
 fd output-file. 
 01 output-file-record pic x(10).
 procedure division.
     open output output-file
     write output-file-record from "Charles"
     write output-file-record from "Bill"
     write output-file-record from "Alan"
     close output-file.

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 "<cmd /c dir"
     organization is line sequential.
  ...
     open input input-file
     read input-file

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

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 inpit-output i-o.

For example:

 select i-o-file
     assign to "| cmd /c sort"
     organization is line sequential.
 fd i-o-file.
 01 i-o-file-record pic x(20).
 procedure division.
     open i-o i-o-file
     write i-o-file-record from "Hello world"
     write i-o-file-record from all "A"
     write i-o-file-record from all "Z"
     write i-o-file-record from x"1a"
     perform until exit
         read i-o-file
          at end
             exit perform
         end-read
         display i-o-file-record
     end-perform
     close i-o-file

In this example, the program launches the sort process and passes it three lines of text, followed by an end-of-file marker. The program then reads all three lines back from the standard output of the sort process.

External File Mapper (Mfextmap)

You can assign filenames externally using the External File Mapper (Mfextmap). This provides a flexible method of mapping the assigned filename used in your COBOL program to a physical filename, by enabling filename mapping to be resolved in a text file (the mapper file). Filename mappings can be altered subsequently, simply by editing the file.

select filename
   assign to external assigned-name

where the parameters are:

filename	The logical (internal) filename used by your program.
assigned-name	An entry in the mapper file.

Using the External File Mapper, rather than resolving filename assignments via operating system environment variables, reduces the amount of memory required for environment space.

Mapper File Structure

Before you can use the External File Mapper, you must create an ordinary text file (use a text editor such as Notepad to do this) and call that text file mfextmap.dat.

Each line in this file contains a filename assignment and takes the following form:

assigned-name physical-name

where the parameters are:

assigned-name	The assigned filename used in your program.
physical-name	The actual name of the physical file, including the pathname.

In this file:

Only one assignment is allowed per line
At least one space must separate the assigned and physical filenames
There can be any number of spaces preceding the assigned filename and following the physical filename
Filenames that include embedded spaces must be enclosed in double-quotes: for example, myfile "my file name"
Where you need to specify a file handler option for a filename that includes embedded spaces, it must be included within the double-quotes enclosing the name: for example, myfile "my file name(printer)"

You can alter the contents of the mapper file during the execution of your program. The mapping information in the current version of the mapper file is always used.

Mapper File Location

If you create a mapper file, it must be called mfextmap.dat and it must be located in one of the following places:

In the current directory (the directory in which your program is running)
In a directory on the COBOL system path (pointed to by the environment variable COBDIR)
In a directory on the path pointed to by the environment variable MFEXTMAP

Both MFEXTMAP and COBDIR can have multiple paths defined.

If MFEXTMAP is set but the mapper file does not exist in the directory or directories to which it points, the system tries to resolve the filename by searching for an environment variable with the same name as the assigned filename used in the program.

If MFEXTMAP is not set, the system searches for the mapper file in the current directory and then along the COBDIR path. If the mapper file is not found, the system tries to resolve the filename by searching for an environment variable with the same name as the assigned filename used in the program.

Activating the External File Mapper

To use the External File Mapper, you must:

Link your program with the shared run-time system
Create a valid mapper file

Then, to activate the External File Mapper you must set the run-time system tunable environment_mapper to TRUE. You do this by adding the following line:

set environment_mapper=TRUE

to a configuration file pointed to by the COBCONFIG_ environment variable.

For more information on run-time tunables, see the topic Run-time Tunables.

Disabling The External File Mapper

By disabling the External File Mapper you will increase the speed of your system as no disk accesses are required to search for the current version of the mapper file.

To disable the External File Mapper set the run-time system tunable environment_mapper to FALSE.