CBL_LOCATE_FILE

Syntax:

call "CBL_LOCATE_FILE" using     user-file-spec
                                 user-mode
                                 actual-file-spec
                                 exist-flag
                                 path-flag
                       returning status-code

Parameters:

user-file-spec
Using call prototype (see Key): pic x(n)
Picture: pic x(n).
user-mode
Using call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
actual-file-spec
Group item defined as
01 actual-file-spec
   03 buffer-len   cblt-x2-compx   pic x(2) comp-x. 
   03 buffer       pic x(n).       pic x(n).
exist-flag
Using call prototype (see Key): cblt-x1-compx
Picture: pic x comp-x.
path-flag
Using call prototype (see Key): cblt-x1-compx
Picture: 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 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.

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