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:

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

Using call prototype (see Key), a group item defined as :

01 actual-file-spec.
   03 buffer-len   cblt-x2-compx. 
   03 buffer       pic x(n).

Picture, a group item defined as :

01 actual-file-spec.
   03 buffer-len   pic x(2) comp-x. 
   03 buffer       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. The string can be space- or null-terminated, depending on bit 7 of user-mode.

Note: For filenames that contain spaces, enclose them in double quotation marks (").

user-mode

Specifies the action to perform on user-file-spec:

Bit pair 0 and 1 (value 0, 1, or 2)

00	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.
01	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.
10	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 the first two bits of `user-mode` set to 1 (01) or 2 (10). See `path-flag` below.
11	Reserved. Must not be used.

Bits 2-6

Reserved. Must be set to zeroes.

Bit 7

Determines the terminator type:

0	`user-file-spec` and `actual-file-spec` are both space-terminated.
1	`user-file-spec` and `actual-file-spec` are both null-terminated.

path-flag

If the first two bits of user-mode are set to 2 (10), this data item should contain the value that was returned in this item from the previous call where the first two bits of user-mode were either 1 (01) or 2 (10).

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, refer to File Striping.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

Example:

The user-file-spec can take the form:

Standard filename:	path\filename.ext (Windows), or path/filename.ext (UNIX)
Embedded environment variable:	$envname\filename.ext (Windows), or $envname/filename.ext (UNIX)
Embedded library name:	path\lbr-name.lbr\filename.ext (Windows), or path/lbr-name.lbr/filename.ext (UNIX)