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
or an MFDBFH folder URL (such as
sql://myserver/mydstore?type=folder;folder=/myfolder); see
The Datastore URL for more information on MFDBFH URLs..
-
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.
If
path-buffer contained an MFDBFH folder URL, the returned
join-buffer is a complete datastore URL; see
The Datastore URL for more information.
-
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 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.