3.1 CBL_JOIN_FILENAME

This routine joins the file name components (i.e., device name, basic name, extension) to each other to create a file name.

Specification

Parameter data definition

01  split-join-parameters.
    02  parameter-length                     PIC 9(4) BINARY.
    02  split-join-flag-1                    PIC 9(2) BINARY.
    02  split-join-flag-2                    PIC 9(2) BINARY.
    02  relative-address-of-device-name      PIC 9(4) BINARY.
    02  device-name-length                   PIC 9(4) BINARY.
    02  relative-address-of-basic-name       PIC 9(4) BINARY.
    02  basic-name-length                    PIC 9(4) BINARY.
    02  relative-address-of-extension        PIC 9(4) BINARY.
    02  extension-length                     PIC 9(4) BINARY.
    02  total-length                         PIC 9(4) BINARY.
    02  split-name-buffer-size               PIC 9(4) BINARY.
    02  joined-name-buffer-size              PIC 9(4) BINARY.
    02  length-of-first-path-name-component  PIC 9(4) BINARY.
01  joined-name-buffer  PIC X(n).
01  device-name-buffer  PIC X(n).
01  basic-name-buffer   PIC X(n).
01  extension-buffer    PIC X(n).
01  status-code         PIC S9(4) COMP-5.

Calling format

CALL "CBL_JOIN_FILENAME"
    USING split-join-parameters
          joined-name-buffer
          device-name-buffer
          basic-name-buffer
          extension-buffer
    RETURNING status-code.

Interface

split-join-parameters

parameter-length: Specifies the length of split/join parameters. The standard value is 24.

split-join-flag-1

Specifies the information of split/join flag 1 in units of bits as follows:

Bit 0

ON: The file name using uppercase characters is returned.
OFF: The file name using specified characters is returned.

Bit 1

ON: The file name string ends with a null character.
OFF: The file name string ends with a blank character.

split-join-flag-2: Specifies the information of split-join-flag-2 in units of bits.

relative-address-of-device-name: Specifies the relative address of device name from the head of the device-name-buffer.

device-name-length: Specifies the length of device name, not including any ending blank or null character. The maximum value is 255.

relative-address-of-basic-name: Specifies the relative address of basic name from the head of the basic-name-buffer.

basic-name-length: Specifies the length of basic name, not including any ending blank or null character. The maximum value is 255.

relative-address-of-extension: Specifies the relative address of extension from the head of the extension-buffer.

extension-length: Specifies the length of the extension, not including any ending blank or null character. The maximum value is 255.

total-length: Specifies the area to store the total number of file name characters.

split-name-buffer-size: Specifies the size of the split-name-buffer.

joined-name-buffer-size: Specifies the size of the joined-name-buffer.

length-of-first-path-name-component: Specifies the length of the first path name component.

joined-name-buffer: Specifies the area to store the joined file name.

device-name-buffer

Specifies the device name.

The device names that need not ":" are as follows.

CON, AUX, COM1, PUN, COM2, LPT1, LPT, LST, PRN, LPT2, LPT3, ERR, NULL

basic-name-buffer: Specifies the basic name.

extension-buffer: Specifies the extension.

Return code

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

status-code

0: Successful
1: Overflow of joined-name-buffer
4: File name invalid

Example

On the following case, this subroutine builds "A:\Example\Master.Doc" into join-name-buffer.

device-name-buffer is "A:\Example".
Basic-name-buffer is "Master".
Extension-buffer is "Doc".