HP 3000 Manuals HP 3000 Manuals
Operation
When your program opens a file, the system prefixes "DD_" to that file's
name. "dd_" is also recognized. The system then extracts the first
element of the file-name and looks for an environment variable with that
name. The first element of the file-name consists of either all the text
before the first "/" character, all the text if the name does not include
such a character, or nothing if the file-name actually starts with the
"/" character. So, for example, if you try to open a file named
dir/file1, the system searches for the environment variable dd_dir; if
you try to open a file named dir1/dir2/file1, the system searches for
dd_dir1 and if the file is named file1, the system searches for dd_file1.
If the system finds the environment variable it is searching for, it then
takes the value of that environment variable and prefixes this to the
remaining elements of the original file-name; that is, the name in the
SELECT ASSIGN statement. This name is then considered to be the physical
file for which the system is to search.
Consider the following examples:
--------------------------------------------------------------------------
| | | | |
| File-name | Environment | Environment | Physical File-name |
| ASSIGNed in | variable | variable | |
| program | searched for | contents | |
| | | | |
--------------------------------------------------------------------------
| | | | |
| dir/file1 | dd_dir | d2 | d2/file1 |
| | | | |
--------------------------------------------------------------------------
| | | | |
| dir/file1 | dd_dir | d4 | d4/file1 |
| | | | |
--------------------------------------------------------------------------
| | | | |
| dir/file1 | dd_dir | d2/d4 | d2/d4/file1 |
| | | | |
--------------------------------------------------------------------------
| | | | |
| dir1/dir2/file1 | dd_dir1 | d2 | d2/dir2/file1 |
| | | | |
--------------------------------------------------------------------------
| | | | |
| dir1/dir2/file1 | dd_dir1 | d4 | d4/dir2/file1 |
| | | | |
--------------------------------------------------------------------------
| | | | |
| dir1/dir2/file1 | dd_dir1 | d2/d4 | d2/d4/dir2/file1 |
| | | | |
--------------------------------------------------------------------------
Following these rules, if the original SELECT ASSIGN file-name consists
of a single element, the value contained in the associated environment
variable is used as the physical file-name. For example:
----------------------------------------------------------------------
| | | | |
| File-name | Environment | Environment | Physical |
| ASSIGNed in | variable | variable | File-name |
| program | searched for | contents | |
| | | | |
----------------------------------------------------------------------
| | | | |
| file1 | dd_file1 | d2 | d2 |
| | | | |
----------------------------------------------------------------------
File-names which begin with a slash ( / ), a hyphen ( - ) or the digits 0
to 9 are not mapped.
The rules for file-name mapping described above enable you to put all
files connected with one application in the same directory and to be
certain that this COBOL system will be able to find all of them. You
achieve this by defining each file as application-name/file-name and by
setting up an environment variable which points to the name of the
directory which contains all these files.
If the system fails to find the environment variable it is searching for,
or it finds the environment variable but the contents of this are not
set, the system assumes that the physical name of the file is the same as
its logical name. For this reason, you must ensure that the logical
file-names do not contain any special characters that cannot be included
in environment variable names.
However, although the period ( . ) is not allowed in the names of
environment variables, it is often used in file-names, so you may want to
map logical file-names containing this character. In this case, you must
replace the "." with an underscore ( _ ). For example:
dd_file_PNT=/usr/qa/myfile_pnt
refers to the logical file-name "file.PNT".
NOTE If you set up dd_ environment variables so that they cause commands
to be executed by the operating system shell, the shell used is
that defined in the environment variable SHELL or, if this has not
been set, by /bin/sh.
The ASSIGN TO PRINTER clause does not send output to a printer; it
sends it to LPT1. To send output to a physical printer, you must
use the dd_LPT1 environment variable or, if your system supports
the lp printer spooler, you should use:
dd_LPT1=">>lp";export dd_LPT1
Setting up Multiple Paths
You can specify multiple paths in the contents of environment variables
for file-name mappings for files OPENed for INPUT or I/O. This causes the
system to search for subsequent files specified in the path if a "file
not found" condition is returned for the first file in the path.
If the first component of a path is a directory, the first component of
the environment variable searched for must also be a directory.
Similarly, if the first component is a file, the dd_ component must also
be a file.
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. In this example, the quotation
marks are as typed into the shell. They are not actually present in the
value of the environment variable. The same is true for all of the
examples in this section.
Consider the following examples:
-------------------------------------------------------------------------
| | | | |
| File-name | Environment | Environment | Physical File-name |
| ASSIGNed in | variable | variable | |
| program | searched for | contents | |
| | | | |
-------------------------------------------------------------------------
| | | | |
| dir1/file1 | dd_dir1 | d1:d2 | d1/file1 \if this |
| | | | is not found then: |
| | | | \d2/file1 |
| | | | |
-------------------------------------------------------------------------
| | | | |
| file1 | dd_file1 | d1/f1:d2/f2 | d1/f1 \if this is |
| | | | not found then: |
| | | | \d2/f2 |
| | | | |
-------------------------------------------------------------------------
| | | | |
| file1 | dd_file1 | f1:f2 | f1 \if this is not |
| | | | found then: \f2 |
| | | | |
-------------------------------------------------------------------------
| | | | |
| dir1/file1 | dd_dir1 | :d1/d2 | current |
| | | | directory/file1 |
| | | | \if this is not |
| | | | found then: |
| | | | \d1/d2/file1 |
| | | | |
-------------------------------------------------------------------------
For files OPENed I/O or OUTPUT, 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 name in a dd_ path list can be up to the
permitted maximum number of characters for a path. Should this limit be
exceeded, you will receive either the run-time system error:
188 Filename too large
or, if the file is an indexed file, the error:
75 Indexed data file name too long
See your Release Notes for details of the maximum number characters
allowed in a path name.
Additionally, you can map files on a global basis by setting the COBDATA
environment variable. See the section Global File-name Mapping later in
this chapter for further information on the COBDATA environment variable.
Search Sequence
The overall search sequence employed by the RTS, or the run-time system
support libraries to find a specified file, is dependent on the file
assignment of that file.
The search order for files ASSIGNed DYNAMIC is:
1. dd_ environment variables
2. environment variables defined in cobconfig
3. any COBDATA environment mappings
4. unmapped name on disk
NOTE If you dynamically change such environment variables using a call
to "SYSTEM", they are not reaccessed by this COBOL system after the
start of its run. However, changing them using COBOL syntax causes
the updated setting to be used.
For files ASSIGNed EXTERNAL, only the last element of the file-name
following the final hyphen is significant for file-name mapping.
The search order for file ASSIGNed EXTERNAL is:
1. dd_ environment variables
2. environment variables defined in cobconfig
3. $filename environment variables
4. file-name literals (variables which may or may not be preceded by
"dd_" but which map external file-names)
5. any COBDATA environment mappings
6. unmapped name on disk
In this case, the file-name literals are reaccessed by this COBOL system
after the start of a run. This is for compatibility with previous
versions of this COBOL system.
%NLS% Characters in File-names
This feature is applicable only if your COBOL system has National
Language Support implemented.
If the physical file-name in your program starts with the characters
"%NLS%", the file is processed in accordance with the rules for National
Language Support (NLS) facilities. Consider the following example
contents of a SELECT statement:
Select file-name assign "%NLS%file1"
This causes the system to process file1 in accordance with NLS rules.
You can then map file1 using the environment variable dd_file1 as
described earlier in this chapter. In this case, the mapped file is
processed in accordance with NLS rules.
Alternatively, a file assigned without the "%NLS%" characters can be
processed in accordance with NLS rules, if you specify a mapping for the
file which is preceded by the characters "%NLS%".
Consider the following example:
---------------------------------------------------------------------
| | | | |
| File-name | Environment | Environment | Physical |
| ASSIGNed in | variable | variable | File-name |
| program | searched for | contents | |
| | | | |
---------------------------------------------------------------------
| | | | |
| file2 | dd_file2 | %NLS%file3 | file3 |
| | | | |
---------------------------------------------------------------------
This causes file3 to be processed in accordance with NLS rules.
See the chapter National Language Support (NLS) for UNIX later in this
manual for full details of NLS facilities.
"&" Character in Environment Variables
When you are specifying the contents of an environment variable you can
place an ampersand (&) character at the start to indicate that an indexed
sequential file is to have its index and its data files in separate
directories (and, by implication, on separate disks). You cannot use
this character when specifying multiple paths.
NOTE As the "&" character has this special meaning when used in
environment variables, if you want to reference any file whose name
begins with this character you must precede the name with a
backslash ( \ ) character.
Consider the following example contents of an environment variable named
dd_dir:
dd_dir="&/disk1/data.dat&/disk2/data.idx ..."
This causes the system to place the data part of the original ASSIGNed
indexed file in /disk1/data, while the index part of the file is placed
in /disk2/data.idx.
"$" Character in File-names
If the physical file-name in your program starts with a dollar ($) sign,
this forces the system to attempt to map the specified file. If no
mapping exists, the system returns a "file not found" condition and does
not search for the unmapped file-name.
Consider the following example contents of a SELECT statement:
select file-name assign "$file1"
This causes the system to search for the environment variable "dd_file1"
then "$file1". If this is found, the system follows the rules for
file-name mapping given in the previous sections. If this is not found,
the system returns a "file not found" condition and does not attempt to
search for "file1".
Forcing the system to attempt to map the specified file in this way is
supported only when mapping is to a file-name. It is not supported to a
directory path list, pipes or to split index and data-names.
Setting up Pipes
When you specify the contents of an environment variable, you can use the
following three characters to set up pipes or named pipes:
* >
* <
* |
The meanings of these characters when used in the value of an environment
variable are described below.
NOTE
* These special characters are only recognized by this COBOL
system if they appear at the start of an environment
variable.
* The OPEN...EXTEND operation on a dd_pipe or named pipe
matches that of an OPEN...OUTPUT.
* You CANNOT use these characters with:
* multiple paths
* variable length records
* multiple LEVEL-01 data-items
* a RECORDING MODE clause.
* As these three characters do have a special meaning in
environment variables, if you want to reference any file
whose name begins with any of these characters, you must
precede the name with a "\" character.
"<" Character.
The less than (<) character defines the specified file as a pipe
connected to the standard output of the given command. The file ASSIGNed
within your program must be either sequential or line sequential, and
must be OPENed for INPUT. Its name can be only one element long; that is,
it must not contain a "/" character.
Consider the following example contents of an environment variable named
dd_dir:
dd_dir="<ls -l ..."
This causes every READ statement in the program of the original ASSIGNed
file to return the value of the next line of the output from the ls -l
command.
The pipe is set up using the UNIX "popen()" library routine.
">" Character.
The greater than (&>) character defines the specified file as a pipe
connected to the standard input of the given command. The file ASSIGNed
within your program must be either sequential or line sequential and must
be OPENed for OUTPUT. Its name can be only one element long; that is, it
must not contain a "/" character.
Consider the following example contents of an environment variable named
dd_dir:
dd_dir="&>pr -h Title ..."
This causes every WRITE to the file in the program to be passed to the
standard input of the pr -h Title command.
"|" Character.
The pipe ( | ) character defines the specified file as a two-way pipe to
the specified process. The file ASSIGNed within your program must be
either sequential or line sequential and must be OPENed for I/O.
Consider the following example contents of an environment variable named
dd_file:
dd_file="|proc"
This defines the file file as a two-way pipe to the process proc, that
is, all the READ operations on that file will read the standard output of
the process proc.
NOTE You will receive an error if you attempt to write to a line
sequential file, or sequential file OPENed for I/O unless the file
has been mapped using the "|" character.
Global File-name Mapping
The COBDATA environment variable enables you to globally map groups of
files to different file-names and file organizations. This enables you
to place working data files in a directory whose name is not known until
run-time.
The format of the COBDATA environment variable is:
COBDATA=:directory:directory... export COBDATA where:
directory is the name of a directory to which you want COBDATA
to point.
For example:
COBDATA=:demo:user:progs
export COBDATA
COBDATA is considered set if there is an environment variable of this
name in your environment space and its value is non-empty.
If you specify an empty directory, this is equivalent to specifying the
current directory using the "." character.
For global file-name mapping, the search order for files ASSIGNed DYNAMIC
and EXTERNAL is as described in the section Search Sequence earlier in
this chapter. However, for directory paths specified either in the
COBDATA environment variable or a dd_ environment variable, the system
searches the first directory specified followed by a slash ( / )
character as a prefix to the user name. If the file is not found, or is
not readable, the search continues until the final directory has been
searched. If no file is found and the OPEN mode is I/O or OUTPUT, the
first directory is used if a file is to be created.
The COBDATA value string must begin with a colon ( : ) character or the
search will not work. All mappings are ignored for any file-name
starting with a hyphen ( - ) character or a "/". It is also illegal to
have a "-" anywhere within an environment variable name.
When using COBDATA for file-name mapping, you should not specify a
file-name that starts with "COB..." as words beginning with this are
reserved for the COBOL system.
You can use COBDATA for files OPENed in any mode and for fixed or
variable length files. If you are using indexed files, both the data and
indexed files will be in the same directory.
COBDATA affects file deletions, using the rules given here, and file
opens.
If you use COBOL development system programs, we recommend that you first
unset COBDATA, as many of these programs open data files and are
therefore affected by the value of COBDATA.