File Name Interpretation

ACUCOBOL-GT employs a rich set of rules when translating a file name specified in an ASSIGN clause to an actual file name used on the host system. These rules provide a great deal of flexibility in placing files and dynamically reassigning them. These rules also allow for convenient handling of printers and other special devices. See Device Locking Under UNIX for examples that illustrate many of the rules listed below.

When interpreting a file name, runcbl performs the following steps in order:

1. The initial name is taken from the ASSIGN clause of the file. If not specified in the ASSIGN clause, then the internal name specified by the SELECT clause is used instead.
2. The name is examined to see if FILE_ALIAS_PREFIX should be applied.
   • The file name is constructed by prepending the first string listed in FILE_ALIAS_PREFIX to the file name. The runtime searches for that name in the environment or the configuration file.
   • If the name is not found, the runtime constructs a new name by prepending the second string in FILE_ALIAS_PREFIX and searches for that alias.
   • The process is repeated with each string in FILE_ALIAS_PREFIX until a file alias name is found or the end of the list is reached.

   If the file name includes a dollar sign ($) and EXPAND_ENV_VARS is set to one (1), the FILE_ALIAS_PREFIX logic is applied to the environment variable name. So, for example, $FILE1 and FILE1 are treated the same.

3. If this name does not start with a hyphen, then it is searched for in the environment. First the runtime system's configuration variables are searched, followed by the host system's environment. The value of the variable found becomes the new name. This search is then repeated until either no new translation is found or the new name starts with a hyphen. Note that when the runtime system's configuration variables are initially loaded, any name found in both the runtime's configuration file and the user's environment is taken from the user's environment.

   For example, if the name PRINT-FILE is assigned to PRINTER1 in the ACUCOBOL-GT configuration file, and you have PRINTER1 assigned to /dev/lp in the host's environment, then opening a file called PRINT-FILE will actually open the file /dev/lp. PRINT-FILE is first translated to PRINTER1 and then "PRINTER1" is subsequently translated to /dev/lp.

4. If the name starts with a hyphen, it is interpreted in a special fashion described below. If it does not start with a hyphen, then it is considered to be a normal file name. This name is further processed as follows.
5. If the FILE_CASE configuration variable has been specified, the change to upper case or lower case is applied if appropriate.
6. The name is examined to see if it has an extension (zero to three characters following a period). If it does not, and the FILE_SUFFIX configuration variable has been defined, then the value of the FILE_SUFFIX is added to the name, with an intervening period if necessary.
7. The name is examined to see if FILE_PREFIX should be applied.
   • If the name contains a disk drive designation, or begins with a \ (back slash), processing continues at step 8.
   • If the name begins with a / (forward slash) and the configuration variable APPLY_FILE_PATH is set to off (0), processing continues at step 8.
   • If the name begins with a / (forward slash) and the configuration variable APPLY_FILE_PATH is set to on (1), the current FILE_PREFIX is applied to the name and processing continues at step 8.
   • If the name does not contain a full path or drive designation, the current FILE_PREFIX is applied to it and processing continues at step 8.

     FILE_PREFIX is a configuration variable that contains one or more strings that are prefixed to the filename. After each string is prefixed and the EXPAND_ENV_VARS variable is checked (see step 8), runcbl tries to find a file by that name. If it finds the file, processing of the name stops. If it does not, the next prefix is tried until no more prefixes are available. A prefix consisting of a single period (.) is treated as an empty prefix (i.e., the current directory is used).

8. Before the runtime tries to find the file, if EXPAND_ENV_VARS is set to on (1), the runtime expands any environment variables found in the name. A file specification that includes a $ character will have all the characters from $ to the end of the name or to the next / or \ replaced with the value of the matching environment variable. The runtime now attempts to find the file. If the file is found, processing stops. If the file is not found and there is another FILE_PREFIX to apply, the prefix is applied and step 8 is repeated. If all the prefixes have been tried and the file has not been found, the first prefix is re-applied, and processing of the name stops. This means that files newly created by runcbl will reside, by default, in the first directory specified in the FILE_PREFIX configuration variable.

Upper or lower case in a file name is significant if it is significant to the host operating system. The same is true when the host environment is searched for a translation. Upper or lower case is not significant when runcbl's local environment is searched for a translation.