CBL_LOCATE_FILE
This routine has two uses. It can be used to expand an environment variable
in a file specification, where the environment variable contains a list of
several paths. It can also determine whether an OPEN INPUT statement using
a particular file specification finds the file in a library file or as a separate
disk file.
Syntax:
call "CBL_LOCATE_FILE" using user-file-spec
user-mode
actual-file-spec
exist-flag
path-flag
returning status-code
Parameters:
|
Using call prototype (see Library Routines - Key) |
Picture (32-bit systems) |
user-file-spec |
pic x(n). |
pic x(n). |
user-mode |
cblt-x1-compx |
pic x comp-x. |
actual-file-spec |
Group item defined as: |
Group item defined as: |
|
buffer-len |
|
cblt-x2-compx |
|
pic x(2) comp-x. |
|
buffer |
|
pic x(n). |
|
pic x(n). |
exist-flag |
cblt-x1-compx |
pic x comp-x. |
path-flag |
cblt-x1-compx |
pic x comp-x. |
status-code |
See Library Routines - Key |
On Entry:
user-file-spec |
Contains the filename specification; this can include an embedded environment
variable or library name. |
user-mode |
Specifies what to do with user-file-spec:
0 |
Check whether the file exists in a library or as a separate disk file.
If user-file-spec includes
an embedded library-name, that library is opened (if it exists) and searched
for the file. The library is left open afterward.
If user-file-spec includes an embedded environment variable, the file is
searched for along each path specified in that variable.
If the file is found, actual-file-spec on exit contains the file specification
with the environment variable expanded to the successful path. Otherwise,
actual-file-spec on exit contains the file specification with the environment
variable expanded to the first path it contained. |
1 |
If user-file-spec includes an environment variable, actual-file-spec
on exit contains the file specification with the environment variable expanded
to the first path it contained. The file is not searched for. |
2 |
If user-file-spec includes an environment variable, actual-file-spec
on exit contains the file specification with the environment variable expanded
to the next path it contained. The file is not searched for. This option should
only be used after a successful call with user-mode = 1 or 2. See path-flag
below. | |
path-flag |
If user-mode = 2, this data item should contain the value that was returned
in this item from the previous user-mode = 1 or 2 call. |
buffer-len |
Size of buffer. |
On Exit:
buffer |
Buffer to contain the resolved file specification, as described under user-mode.
If the resolved file specification is larger than the size specified by buffer-len,
the contents of buffer remain unchanged and status-code is set accordingly. |
exist-flag |
If user-mode = 0, this data item on exit shows whether the file specified
in user-file-spec exists.
0 |
File not found or not searched for |
1 |
File was found in a library that was already open |
2 |
File was found in a library specified in user-file-spec |
3 |
File was found as a separate disk file |
If user-mode is not 0 this data item is always 0 on exit. |
path-flag |
Shows whether user-file-spec contained an embedded environment variable
that has been expanded in actual-file-spec.
0 |
actual-file-spec does not include an expanded environment variable |
>0 |
actual-file-spec contains an expanded environment variable | |
status-code |
Return status:
0 |
Success |
1 |
The environment variable does not exist |
2 |
There is no next path |
3 |
The resolved filename is too large for the buffer |
4 |
Resulting filename is illegal |
255 |
Other error | |
Comments:
CBL_LOCATE_FILE is not stripe-aware. If you use this routine on a striped
file, the routine locates the first stripe only. Therefore, use this routine
on an individual stripe only and refer to the stripe by the stripe name. For
more information on the use of striped files, please refer to the section
File Striping in the chapter File Handler Configuration of your File
Handling book.
Example:
The user-file-spec can take the form:
Standard filename: |
path\filename.ext |
Embedded environment variable: |
$envname\filename.ext |
Embedded library name: |
path\lbr-name.lbr\filename.ext |
See Also: