Rocket® Enterprise Developer (formerly a product of Micro Focus or formerly a product of Open Text) documentation, created before Rocket Software acquired certain products from OpenText, may include outdated references to "Micro Focus" or "OpenText", both of which are trademarks of OpenText or its affiliates. Rocket Software is not affiliated with Micro Focus or OpenText and has since rebranded these products as Rocket® products. You may also encounter outdated links in this documentation. If you do, please contact Rocket Support (support@rocketsoftware.com) for assistance.
CBL_FILENAME_CONVERT
Converts a filename between space-terminated and null-terminated format.
Syntax:
call 'CBL_FILENAME_CONVERT' using fnc-func
filename-in
filename-out
by value fnc-in-length
by value fnc-out-length
returning fnc-ret
Parameters
- fnc-func
- Using call prototype (see Key): cblt-x1-compx
- Picture: pic x comp-x.
- filename-in
- Using call prototype (see Key): pic x(n).
- Picture: pic x(n).
- filename-out
- Using call prototype (see Key): pic x(n).
- Picture: pic x(n).
- fnc-in-length
- Using call prototype (see Key): cblt-os-size
- Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
- fnc-out-length
- Using call prototype (see Key): cblt-os-size
- Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
- fnc-ret
- Using call prototype (see Key): cblt-rtncode
On Entry:
- fnc-func
- Defines how the conversion will proceed:
- Bit 0
-
0 Convert from space-terminated to null-terminated format. 1 Convert from null-terminated to space-terminated format. - Bit 1
-
0 If bit 0 is set to 0, the length of filename-in is determined using the space-termination character at the end of the filename. 1 If bit 0 is set to 0, fnc-in-length exactly determines the length of filename-in. All characters are treated as part of the filename. - Bit 2
-
0 Do not fold filename to upper case. 1 Fold filename to upper case. - Bit 3
-
0 Behavior determined by bits 0 to 2. 1 Bits 0 to 2 are ignored, and the length of filename-in is determined by scanning the filename as a space-terminated filename. You can also specify a list of other termination characters; see below. - Bits 4-7
- Reserved. Must be set to zero.
- filename-in
- Input filename.
- filename-out
- If bit 3 of fnc-func is set to 1, a list of characters that if encountered unquoted terminate the filename. If there are no additional characters, then a null pointer should be passed.
- filename-in-length
- Length of filename-in.
- filename-out-length
- If bit 3 of fnc-func is set to 0, the size of the buffer for the converted filename.
If bit 3 of fnc-func is set to 1, the number of characters in filename-out (if supplied).
On Exit:
- filename-out
- If bit 3 of fnc-func is set to 0, the converted filename. If filename-in is invalid, this parameter is set to an empty filename (a null if bit 0 was set to 0, else a space).
- fnc-ret
- If 0, an error occurred, otherwise, the length of the space terminated name that was either input or output.
Comments:
A space-terminated filename consists of a filename terminated by a space character. If the filename contains any embedded spaces then they should be escaped by including the whole filename between a pair of double quotes.
A null-terminated filename has any double quotes stripped out, but retains any embedded spaces.