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 Library Routines - 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 Library Routines - 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:
1
1 Strings are null-terminated
0 Strings are space-terminated
0
1 The new filename is folded to upper case
0 The original case is preserved
cblte-sj-split-join-flag2 Can be set as follows:
2
1 If bit 1 of cblte-sj-split-join-flag1 is set to 0, then this indicates that the length of each filename component is given exactly by cblte-sj-path-length, cblte-sj-basename-length and cblte-sj-extension-length. This flag can be used when there are known significant spaces in one of the filename components. If bit 1 of cblte-sj-split-join-flag1 is 1, then this is ignored,
0 Length of filename components is determined by bit 1 of cblte-sj-split-join-flag1.
1 Reserved.
0 Reserved.
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:
0 Success
1 Filename too big for join-buffer
4 Illegal filename
Comments:

The new filename is formed by concatenating the following:

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.

Filename Routines - Example

See Also: