4.13 CBL_LOCATE

When the file specification includes an environment variable, this routine returns the name of the file into which the environment variable is expanded. This routine also determines whether a file on another disk is to be used.

Specification

Parameter data definition

01  user-file-specification  PIC X(n).
01  user-mode                PIC 9(4) BINARY.
01  real-file-specification.
    02  buffer-size          PIC 9(4) BINARY.
    02  buffer               PIC X(n).
01  existence-flag           PIC 9(4) BINARY.
01  path-flag                PIC 9(4) BINARY.
01  status-code              PIC S9(4) COMP-5.

Calling format

CALL "CBL_LOCATE_FILE"
    USING user-file-specification
          user-mode
          real-file-specification
          existence-flag
          path-flag
    RETURNING status-code.

Interface

user-file-specification

Specifies a user file, ending with a blank or null character. Specification contents are as follows:

When specifying a standard file name:
```
device-name\file-name.extension
```
When specifying an embedded environment variable:
```
$environment\file-name.extension
```

The maximum size of the file name is 255.

user-mode

Specifies one of the following modes to handle the user-file specification:

0: The file is checked to determine whether it exists on another disk. When the user-file specification includes an environment variable, files are searched sequentially along the path specified by the environment variable. If the file is found, the file path name is expanded and set in real-file-specification (to be output by this routine). If the file is not found, the result of expansion using the first path name specified by the environment variable is set in the real-file-specification.
1: When the user-file specification includes an environment variable, the file is not searched, but the result of expansion using the first path name is set in the real-file-specification.
2: When the user-file specification does not include an environment variable, the file is not searched, but the result of expansion using the next path name is set in the real-file-specification.

real-file-specification: Specifies the size of the next buffer in the buffer-size parameter, and the area to store the expanded file path name in the buffer parameter.

existence-flag

Specifies the area to store the existence flag. The information to be set is as follows:

When user-mode is 0:
- 0: The file is not found.
- 3: The file is found on another disk.
When user-mode is other than 0:
- The routine returns 0.

path-flag

Specifies the area to store the path flag. The information to be set is as follows:

0: The real-file-specification does not include an expanded environment variable.
1: The real-file-specification includes an expanded environment variable.

Return code

The return code is set in the status-code specified in the RETURNING clause.

status-code

0: Successful
1: Environment variable not found
2: Next path not found
3: Expanded path name longer than buffer size
255: Other error

Note

This subroutine supports the environment variable, which has 1 to 255 bytes of right parts.

4.13 CBL_LOCATE_ FILE