CBL_JOIN_FILENAME
Forms a filename by joining together its component parts; that is, the pathname, basename and extension.
Syntax:
call "CBL_JOIN_FILENAME" using sj-param join-buffer path-buffer basename-buffer extension-buffer returning status-code
Parameters:
| Using call prototype (see Key) | Picture (32-bit systems) | ||||
|---|---|---|---|---|---|
| sj-param | A group item predefined as cblt-splitjoin-buf, containing the following subordinate items: | Group containing: | |||
| cblte-sj-param-length | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-split-join-flag1 | cblt-x1-compx | pic x comp-x. | |||
| cblte-sj-split-join-flag2 | cblt-x1-compx | pic x comp-x. | |||
| cblte-sj-device-offset | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-device-length | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-basename-offset | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-basename-length | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-extension-offset | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-extension-length | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-total-length | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-split-buf-len | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-join-buf-len | cblt-x2-compx | pic x(2) comp-x. | |||
| cblte-sj-first-component-length | cblt-x2-compx | pic x(2) comp-x. | |||
| join-buffer | pic x(n). | pic x(n). | |||
| path-buffer | pic x(n). | pic x(n). | |||
| basename-buffer | pic x(n). | pic x(n). | |||
| extension-buffer | pic x(n). | pic x(n). | |||
| status-code | See Key | ||||
On Entry:
| cblte-sj-param-length | Length of sj-param in bytes, including the two bytes for cblte-sj-param-length. The normal value for cblte-sj-param-length is 24. | ||||||||||||
| cblte-sj-split-join-flag1 | Can be set as follows:
|
||||||||||||
| cblte-sj-split-join-flag2 | Can be set as follows:
|
||||||||||||
| cblte-sj-device-offset | Offset of the start of the path in path-buffer, indexed from one. | ||||||||||||
| cblte-sj-device length | Length of path if not space- or null-terminated. | ||||||||||||
| cblte-sj-basename-offset | Offset of the start of the basename in basename-buffer, indexed from one. | ||||||||||||
| cblte-sj-basename-length | Length of basename if not space- or null-terminated. | ||||||||||||
| cblte-sj-extension-offset | Offset of the start of the extension in extension-buffer, indexed from one. | ||||||||||||
| cblte-sj-extension-length | Length of extension if not space- or null-terminated. | ||||||||||||
| path-buffer | Pathname. | ||||||||||||
| basename-buffer | Basename. | ||||||||||||
| extension-buffer | Extension. | ||||||||||||
| cblte-sj-join-buf-len | Length of join-buffer. |
On Exit:
| cblte-sj-total-length | Total number of characters in the filename. | ||||||
| join-buffer | The joined-up filename. | ||||||
| status-code | Return status:
|
Comments:
The new filename is formed by concatenating the following:
- The first cblte-sj-device-length bytes (starting from cblte-sj-device-offset) of path-buffer
- The first cblte-sj-basename-length bytes (starting from cblte-sj-basename-offset) of basename-buffer
- The first cblte-sj-extension-length bytes (starting from cblte-sj-extension-offset) of extension-buffer
It is placed in join-buffer with length cblte-sj-total-length.
This routine can be made to fold to upper case by setting the least significant bit (bit 0) of cblte-sj-split-join-flag1. If this bit is not set, the case is preserved.
This routine can accept either null-terminated or space-terminated strings. Setting the second least significant bit (bit 1) of cblte-sj-split-join-flag1 results in the routine expecting null-terminated strings. If this bit is not set, space-terminated strings are expected.
The path, basename and extension fields can be shorter than the lengths specified by cblte-sj-path-length, cblte-sj-basename-length, and cblte-sj-extension-length respectively, if they are terminated with either a space or a null, depending on the setting bit 1 of cblte-sj-split-join-flag1.
path-buffer, basename-buffer, extension-buffer, and join-buffer do not have to be four distinct buffers. This means that this routine can be used with CBL_SPLIT_FILENAME to replace one component of a filename.
If path-buffer is not empty and does not have a trailing backslash (\) or slash (/) or colon (:) and basename-buffer is not empty, the routine inserts a backslash (\) between the path and basename in join-buffer.
If extension is ".", the string returned in join-buffer has an extension of spaces; that is, the filename has a trailing period (.).
If cblte-sj-total-length is less than cblte-sj-join-buf-len, the characters after the end of the filename are nulls or spaces depending on bit 1 of cblte-sj-split-join-flag1.
If path consists of a valid drive letter, but no colon (:), the routine adds one. It does not do this for a device (for example LPT1) that does not need one. You cannot join a device (as opposed to a drive letter) to a non-empty basename.
Example of the use of CBL_JOIN_FILENAME