Micro Focus Visual COBOL 2.3 Update 1 for Eclipse (UNIX) > General Reference > Library Routines > Alphabetical List of Library Routines > CBL_JOIN_FILENAME

Micro Focus Visual COBOL 2.3 Update 1 for Eclipse (UNIX) > General Reference > Library Routines > File and Filename Routines > CBL_JOIN_FILENAME

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 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.