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

sj-param
Group predefined as cblt-splitjoin-buf containing:
01 cblt-splitjoin-buf                typedef.
  03 cblte-sj-param-length           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-split-join-flag1       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-sj-split-join-flag2       cblt-x1-compx. 	*> pic x comp-x.
  03 cblte-sj-device-offset          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-device-length          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-basename-offset        cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-basename-length        cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-extension-offset       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-extension-length       cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-total-length           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-split-buf-len          cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-join-buf-len           cblt-x2-compx. 	*> pic x(2) comp-x.
  03 cblte-sj-first-component-length cblt-x2-compx. 	*> pic x(2) comp-x.
join-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
path-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
basename-buffer
Call prototype (see Key): pic x(n).
Picture: pic x(n).
extension-buffer
Call prototype (see Key): pic x(n).
Picture: 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:
Bit 1
1 Strings are null-terminated
0 Strings are space-terminated
Bit 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:
Bit 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.
Bit 1
Reserved
Bit 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:

  • 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 forwardslash (/) or colon (:) and basename-buffer is not empty, the routine inserts a backslash (Windows), or forwardslash (UNIX) 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. This applies to Windows environments (local development) only.