PreviousRebuild Miscellaneous TopicsNext

Chapter 10: File Handling Library Routines

This chapter describes the COBOL system library routines which you can use to manipulate files.

10.1 Overview

The following COBOL system library routines enable you to manipulate files from your COBOL applications.

CBL_CHANGE_DIR Changes the current directory
CBL_CHECK_FILE_EXIST Checks if a file exists
CBL_COPY_FILE Copies a file
CBL_CREATE_DIR Creates a directory
CBL_DELETE_DIR Deletes a directory
CBL_DELETE_FILE Deletes a file
CBL_GET_CURRENT_DIR Returns the current directory
CBL_JOIN_FILENAME Creates a filename by joining together its component parts
CBL_LOCATE_FILE Locates a file, expands path
CBL_READ_DIR Reads the current directory
CBL_RENAME_FILE Renames a file
CBL_SPLIT_FILENAME Splits a filename into its component parts
x"91" function 46 Enables null insertion
x"91" function 47 Disables null insertion
x"91" function 48 Enables tab insertion
x"91" function 49 Disables tab insertion
x"91" function 52 Specifies use of two-byte record terminators
x"91" function 53 Specifies use of one-byte record terminators

10.2 Key to File Handling Library Routines

Descriptions for all of the call-by-name routines appear alphabetically. These are followed by call-by-number routines in numeric order. Each description contains the routine name and function and the following entries (as appropriate):

Syntax: Shows the CALL statement you could use to call the routine.

The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.)

status-code must be a numeric data item capable of holding positive values from 0 to 65535; for example, PIC X(2) COMP-5.

The name of the routine must be coded in upper case.

Parameters: Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine.
On Entry: Indicates which of the parameters shown are passed on entry.
On Exit: Indicates which of the parameters shown are returned on exit.

Where bits of one or more bytes are referenced, bit 0 is the least significant (rightmost) bit.

Comments: Provides any additional information necessary for the successful use of the routine.
Related Topics: Lists other related topics.

10.3 Descriptions of Routines


CBL_CHANGE_DIR

Changes the current directory.

Syntax:
call "CBL_CHANGE_DIR"  using     path-name 
                       returning status-code
Parameters:

path-name           pic x(n).
status-code         See Key

On Entry:
path-name Relative or absolute pathname terminated by space or null (x"00"). This must be no longer than the maximum number of characters allowed by your operating system and must be valid from the directory that is current when the routine is called.
On Exit:

None


CBL_CHECK_FILE_EXIST

Checks whether a file exists and returns details if it does.

Syntax:
call "CBL_CHECK_FILE_EXIST" using     filename 
                                      file-details 
                            returning status-code
Parameters:

filename                       pic x(n).
file-details                   A group item predefined as cblt-exit-params,
                               containing the following subordinate items:
    cblte-fe-filesize          cblt-x8-compx.
    cblte-fe-date            Group item defined as:
        cblte-fe-day           cblt-x1-compx.
        cblte-fe-month         cblt-x1-compx.
        cblte-fe-year          cblt-x2-compx.
    cblte-fe-time            Group item defined as:
        cblte-fe-hours         cblt-x1-compx.
        cblte-fe-minutes       cblt-x1-compx.
        cblte-fe-seconds       cblt-x1-compx.
        cblte-fe-hundredths    cblt-x1-compx.
status-code                    See Key

On Entry:
filename The file to look for. The name can contain a path, and is terminated by a space. If no path is given, the current directory is assumed.
On Exit:
cblte-fe-filesize The size of the file in bytes.
cblte-fe-date The date the file was created.
cblte-fe-time The time the file was created.
Comments:

You cannot use wildcard characters in filenames.

CBL_CHECK_FILE_EXIST is not stripe-aware. If you use this routine on a file for which striping is enabled, the details returned refer to the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, please refer to the section File Striping in the chapter File Handler Configuration.


CBL_COPY_FILE

Copies a file.

Syntax:
call "CBL_COPY_FILE" using     filename1 
                               filename2 
                     returning status-code
Parameters:

filename1           pic x(n).
filename2           pic x(n).
status-code         See Key

On Entry:
filename1 The file to copy. The name can contain a path and is terminated by a space. If no path is given, the current directory is assumed.
filename2 The name of the new file. The name can contain a path and is terminated by a space. If no path is given, the current directory is assumed.
On Exit:

None.

Comments:

You cannot use wildcard characters in filenames.

CBL_COPY_FILE emulates the equivalent operating system call. Therefore, the new file is stamped with the current date and time.

CBL_COPY_FILE is not stripe-aware. If you use this routine on a striped file, the routine copies the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, please refer to the section File Striping in the chapter File Handler Configuration.


CBL_CREATE_DIR

Creates a subdirectory. All the directories in the given path, except the last, must already exist.

Syntax:
call "CBL_CREATE_DIR" using     path-name 
                      returning status-code
Parameters:

path-name           pic x(n).
status-code         See Key

On Entry:
path-name Relative or absolute pathname terminated by space or null (x"00").
On Exit:

None


CBL_DELETE_DIR

Deletes a directory. The directory is deleted only if it is empty.

Syntax:
call "CBL_DELETE_DIR"  using     path-name 
                       returning status-code
Parameters:

path-name           pic x(n).
status-code         See Key

On Entry:
path-name Relative or absolute pathname terminated by space or null (x"00").
On Exit:

None


CBL_DELETE_FILE

Deletes a file.

Syntax:
call "CBL_DELETE_FILE" using     filename 
                       returning status-code
Parameters:

filename            pic x(n).
status-code         See Key

On Entry:
filename The file to delete. The name can contain a pathname, and is terminated by a space. If no path is given, the current directory is assumed.
On Exit:

None

Comments:

You cannot use wildcard characters in filenames.

CBL_DELETE_FILE is not stripe-aware. If you use this routine on a striped file, the routine deletes the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, please refer to the section File Striping in the chapter File Handler Configuration.


CBL_GET_CURRENT_DIR

Returns the current directory.

Syntax:
call "CBL_GET_CURRENT_DIR" using 
                                by value     flags 
                                by value     name-length 
                                by reference directory-name 
                                returning    status-code
Parameters:
flags cblt-os-flags.
name-length cblt-os-size.
directory-name pic x(n).
status-code See Key.
On Entry:
flags Reserved. Must be set to zero
name-length The size, in bytes, of the directory-name parameter. This parameter must be at least as big as the longest directory name that can be returned.
On Exit:
directory-name Contains the current working directory in space-terminated format. If the directory-name contains embedded spaces then it will be returned delimited by a pair of double quotes. This parameter must be large enough to also hold these quotes.
status-code A return code:
0 Success. directory-name contains the current working directory.
128 The size of directory-name specified by name-length is not large enough to hold the name of the current working directory.

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 A group item predefined as cblt-splitjoin-buf, containing the following subordinate items:
cblte-sj-param-length cblt-x2-compx.
cblte-sj-split-join-flag1 cblt-x1-compx.
cblte-sj-split-join-flag2 cblt-x1-compx.
cblte-sj-device-offset cblt-x2-compx.
cblte-sj-device-length cblt-x2-compx.
cblte-sj-basename-offset cblt-x2-compx.
cblte-sj-basename-length cblt-x2-compx.
cblte-sj-extension-offset cblt-x2-compx.
cblte-sj-extension-length cblt-x2-compx.
cblte-sj-total-length cblt-x2-compx.
cblte-sj-split-buf-len cblt-x2-compx.
cblte-sj-join-buf-len cblt-x2-compx.
cblte-sj-first-component-length cblt-x2-compx.
join-buffer pic x(n).
path-buffer pic x(n).
basename-buffer pic x(n).
extension-buffer pic x(n).
status-code See 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 Value Meaning
1 1
0
Strings are null-terminated
Strings are space-terminated
0 1
0
The new filename is folded to upper case
The original case is preserved
cblte-sj-split-join-flag2 Can be set as follows:
Bit Value Meaning
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-len 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.

You can use this routine to change the case of a filename 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-device-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 of 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 cblt-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 the path field 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.

See Also:

CBL_SPLIT_FILENAME

Example:
************************************************************
*                                                          *
*               (C) MERANT International Ltd 2000          *
*                                                          *
*                     SPLTJOIN.CBL                         *
*                                                          *
*  This program demonstrates the use of the routines that  *
*  enable you to separate a filename into its component    *
*  strings (CBL_SPLIT_FILENAME), and to join strings       *
*  together to form a filename (CBL_JOIN_FILENAME).        *
*                                                          *
************************************************************

 working-storage section.

 78 environ          value "dos".

 01 split-buffer                     pic x(65).
 01 split-params                          cblt-splitjoin-buf.
     03  cblte-sj-param-length            cblt-x2-compx value 24.
     03  cblte-sj-split-join-flag1        cblt-x1-compx value 0.
     03  cblte-sj-split-join-flag2        cblt-x1-compx.
     03  cblte-sj-device-offset           cblt-x2-compx.
     03  cblte-sj-device-length           cblt-x2-compx.
     03  cblte-sj-basename-offset         cblt-x2-compx.
     03  cblte-sj-basename-length         cblt-x2-compx.
     03  cblte-sj-extension-offset        cblt-x2-compx.
     03  cblte-sj-extension-length        cblt-x2-compx.
     03  cblte-sj-total-length            cblt-x2-compx.
     03  cblte-sj-split-buf-len           cblt-x2-compx value 65.
     03  cblte-sj-join-buf-len            cblt-x2-compx value 65.
     03  cblte-sj-first-component-length  cblt-x1-compx.

 01 join-buffer              pic x(65).
 01 path-buffer              pic x(65).
 01 basename-buffer          pic x(65).
 01 extension-buffer         pic x(3) value "cbl".

 procedure division.

* Set up lengths
     move 65 to cblte-sj-split-buf-len
                cblte-sj-join-buf-len

* Set flag for space-terminated, fold to upper
     move 1 to cblte-sj-split-join-flag1

$if environ = "unix"
     move "/dir/file.ext" to split-buffer
$else
     move "a:\dir\file.ext" to split-buffer

$end
     move 1 to cblte-sj-split-join-flag1
     call "CBL_SPLIT_FILENAME" using split-params
                                     split-buffer

* This sets up most of the parameters you need for a join

* The join below replaces the original extension in 
* split-buffer with the extension in extension-buffer, and
* puts the result in join-buffer.
     move 1 to cblte-sj-extension-offset
     move 3 to cblte-sj-extension-length
     call "CBL_JOIN_FILENAME" using split-params
                                    join-buffer
                                    split-buffer
                                    split-buffer
                                    extension-buffer

$if environ = "unix"
     if join-buffer = "/DIR/FILE.CBL" then
$else
     if join-buffer = "A:\DIR\FILE.CBL" then
$end
         display "first test passed"
     else
         display "first test failed"
     end-if

* It is harder to set up a join without doing a split first,
* but this is what you would need to do.

     move 1 to cblte-sj-device-offset
               cblte-sj-basename-offset
               cblte-sj-extension-offset

     move length of path-buffer to cblte-sj-device-length
     move length of basename-buffer 
                                to cblte-sj-basename-length
     move length of extension-buffer 
                                to cblte-sj-extension-length
     move length of join-buffer to cblte-sj-join-buf-len

     move 0 to cblte-sj-split-join-flag1
     move 24 to cblte-sj-param-length

$if environ = "unix"
     move "/path" to path-buffer
$else
     move "c:\path" to path-buffer
$end
     move "basename" to basename-buffer

     move "ext" to extension-buffer

     call "CBL_JOIN_FILENAME" using split-params
                                    join-buffer
                                    path-buffer
                                    basename-buffer
                                    extension-buffer

$if environ = "unix"
     if join-buffer = "/path/basename.ext" then
$else
     if join-buffer = "c:\path\basename.ext" then
$end
         display "second test passed"
     else

         display "second test failed"
     end-if
  stop run.

CBL_LOCATE_FILE

This routine has two uses. It can be used to expand an environment variable in a file specification, where the environment variable contains a list of several paths. It can also determine whether an OPEN INPUT statement using a particular file specification finds the file in a library file or as a separate disk file.

Syntax:
call "CBL_LOCATE_FILE" using     user-file-spec 
                                 user-mode 
                                 actual-file-spec 
                                 exist-flag 
                                 path-flag 
                      returning  status-code
Parameters:

user-file-spec      pic x(n).
user-mode           cblt-x1-compx.
actual-file-spec    Group item defined as:
    buffer-len          pic x(2) comp-x.
    buffer              pic x(n).
exist-flag          pic x comp-x.
path-flag           pic x comp-x.
status-code         See Key

On Entry:
user-file-spec Contains the filename specification; this can include an embedded environment variable or library name.
user-mode Specifies what to do with user-file-spec:
0 Check whether the file exists in a library or as a separate disk file.

If user-file-spec includes an embedded library-name, that library is opened (if it exists) and searched for the file. The library is left open afterwards.

If user-file-spec includes an embedded environment variable, the file is searched for along each path specified in the environment variable.

If the file is found, then on exit, actual-file-spec contains the actual file specification with the environment variable expanded to the successful path. If the file is not found, then on exit, actual-file-spec contains the file specification with the environment variable expanded to the first path it contained.

Otherwise, actual-file-spec on exit contains the file specification with the environment variable expanded to the first path it contained.

1 If user-file-spec includes an environment variable, actual-file-spec on exit contains the file specification with the environment variable expanded to the first path it contained. The file is not searched for.
2 If user-file-spec includes an environment variable, actual-file-spec on exit contains the file specification with the environment variable expanded to the next path it contained. The file is not searched for. This option should only be used after a successful call with user-mode = 1 or 2. See path-flag below.
path-flag If user-mode = 2, this data item should contain the value that was returned in this item from the previous user-mode = 1 or 2 call.
buffer-len Size of buffer.
On Exit:
buffer Buffer to contain the resolved file specification, as described under user-mode. If the resolved file specification is larger than the size specified by buffer-len, the contents of the buffer remain unchanged and status-code is set accordingly.
exist-flag If user-mode = 0, then on exit, this data item shows whether the file specified in user-file-spec exists.
0 File not found or not searched for
1 File was found in a library that was already open
2 File was found in a library specified in user-file-spec
3 File was found as a separate disk file

If user-mode is not 0 this data item is always 0 on exit.

path-flag Shows whether user-file-spec contained an embedded environment variable that has been expanded in actual-file-spec.
0 actual-file-spec does not include an expanded environment variable
>0 actual-file-spec contains an expanded environment variable
status-code Return status:
0 Success
1 The environment variable does not exist
2 There is no next path
3 The resolved filename is too large for the buffer
4 Resulting filename is illegal
255 Other error
Example:

user-file-spec can take the form:

path/filename.ext
$envname/filename.ext
path/lbr-name.lbr/filename.ext 
Comments:

CBL_LOCATE_FILE is not stripe-aware. If you use this routine on a striped file, the routine locates the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, please refer to the section File Striping in the chapter File Handler Configuration.


CBL_READ_DIR

Returns the current directory or path.

Syntax:
call "CBL_READ_DIR" using     path-name 
                              path-name-length 
                    returning status-code
Parameters:

path-name           pic x(n).
path-name-length    cblt-x1-compx.
status-code         See Key

On Entry:
path-name-length Length of path-name to be used. If this is too small for the pathname, the routine fails.
On Exit:
path-name Relative or absolute pathname terminated by space or null (x"00").

CBL_RENAME_FILE

Changes the name of a file.

Syntax:
call "CBL_RENAME_FILE" using     old-filename 
                                 new-filename 
                       returning status-code
Parameters:

old-filename        pic x(n).
new-filename        pic x(n).
status-code         See Key

On Entry:
old-filename The file to rename. The name can contain a pathname, and is terminated by a space. If no path is given, the current directory is assumed.

This routine does not work with filenames containing wildcard characters.

new-filename The new name, terminated by a space. If old-filename contains a pathname, this must contain the same pathname. Some operating systems do not allow you to rename a file if a file of the name in new-filename already exists
On Exit:

None

Comments:

CBL_RENAME_FILE is not stripe-aware. If you use this routine on a striped file, the routine renames the first stripe only. Therefore, use this routine on an individual stripe only and refer to the stripe by the stripe name. For more information on the use of striped files, please refer to the section File Striping in the chapter File Handler Configuration.


CBL_SPLIT_FILENAME

Splits a filename into its component parts; that is, the pathname, basename and extension.

Syntax:
call "CBL_SPLIT_FILENAME" using     sj-param
                                         split-buffer
                               returning status-code
Parameters:
sj-param A group item predefined as cblt-splitjoin-buf, containing the following subordinate items:
cblte-sj-param-length cblt-x2-compx.
cblte-sj-split-join-flag1 cblt-x1-compx.
cblte-sj-split-join-flag2 cblt-x1-compx.
cblte-sj-device-offset cblt-x2-compx.
cblte-sj-device-length cblt-x2-compx.
cblte-sj-basename-offset cblt-x2-compx.
cblte-sj-basename-length cblt-x2-compx.
cblte-sj-extension-offset cblt-x2-compx.
cblte-sj-extension-length cblt-x2-compx.
cblte-sj-total-length cblt-x2-compx.
cblte-sj-split-buf-len cblt-x2-compx.
cblte-sj-join-buf-len cblt-x2-compx.
cblte-sj-first-component-length cblt-x2-compx.
split-buffer pic x(n).
status-code See 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
Bit Value Meaning
1 1 The strings are null-terminated
0 The strings are space-terminated
0 1 The new filename is folded to upper case
0 The original case is preserved.
cblte-sj-split-buf-len Length of split-buffer.
split-buffer The string to split.
On Exit:
cblte-sj-split-join-flag2 bit 2    Set if there is a significant space in the filename
bit 1    Set if there is a wildcard in the path
bit 0    Set if there is a wildcard in basename or extension
cblte-sj-device-offset Start of pathname in split-buffer, from one.
cblte-sj-device-length Length of pathname; zero if there is none. This includes any following colon (:).
cblte-sj-basename-offset Start of basename in split-buffer, from one.
cblte-sj-basename-length Length of basename; zero if there is none. This does not include the following period (.).
cblte-sj-extension-offset Start of extension in split-buffer, from one.
cblte-sj-extension-length Length of extension; zero if there is none. This does not include the preceding period (.).
cblte-sj-total-length Total number of characters in the string.
cblte-sj-first-component-length Number of characters up to and including the first backslash (\) or slash (/) or colon (:); if split-buffer contains none of these, this parameter = path-len.
split-buffer If bit 0 of cblte-sj-split-join-flag1 is set then this routine folds to upper case. If bit 1 of cblte-sj-split-join-flag1 is unset and split-buffer was a quoted name, possibly containing embedded spaces/quotes, then any unrequired quote characters are removed.
status-code Return status:
0 Success
4 Illegal filename
Comments:

You can use this routine to change the case of a filename 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.

If there are two or more periods (.) in the filename (not counting periods (.) in the pathname), the extension returned consists of the characters between the last period (.) and the end of the filename. The basename contains everything up to, but not including, the last period (.).

To make a distinction between filenames with no extension and filenames with spaces extension (that is, basenames whose last character is a period (.)), if the extension is spaces cblte-sj-extension-len is 1 and cblte-sj-extension-offset points to the last period (.).

See Also:

CBL_JOIN_FILENAME

Example:
************************************************************
*                                                          *
*               (C) MERANT International Ltd               *
*                                                          *
*                     SPLTJOIN.CBL                         *
*                                                          *
*  This program demonstrates the use of the routines that  *
*  enable you to separate a filename into its component    *
*  strings (CBL_SPLIT_FILENAME), and to join strings       *
*  together to form a filename (CBL_JOIN_FILENAME).        *
*                                                          *
************************************************************

 working-storage section.

 78 environ          value "dos".

 01 split-buffer                          pic x(65).
 01 split-params                          cblt-splitjoin-buf.
     03  cblte-sj-param-length            cblt-x2-compx value 24.
     03  cblte-sj-split-join-flag1        cblt-x1-compx value 0.
     03  cblte-sj-split-join-flag2        cblt-x1-compx.
     03  cblte-sj-device-offset           cblt-x2-compx.
     03  cblte-sj-device-length           cblt-x2-compx.
     03  cblte-sj-basename-offset         cblt-x2-compx.
     03  cblte-sj-basename-length         cblt-x2-compx.
     03  cblte-sj-extension-offset        cblt-x2-compx.
     03  cblte-sj-extension-length        cblt-x2-compx.
     03  cblte-sj-total-length            cblt-x2-compx.
     03  cblte-sj-split-buf-len           cblt-x2-compx value 65.
     03  cblte-sj-join-buf-len            cblt-x2-compx value 65.
     03  cblte-sj-first-component-length  cblt-x1-compx.

 01 join-buffer              pic x(65).
 01 path-buffer              pic x(65).
 01 basename-buffer          pic x(65).
 01 extension-buffer         pic x(3) value "cbl".

 procedure division.

* Set up lengths
     move 65 to cblte-sj-split-buf-len
                cblte-sj-join-buf-len

* Set flag for space-terminated, fold to upper
     move 1 to cblte-sj-split-join-flag1

$if environ = "unix"
     move "/dir/file.ext" to split-buffer
$else
     move "a:\dir\file.ext" to split-buffer

$end
     move 1 to splitjoin-flg1
     call "CBL_SPLIT_FILENAME" using split-params
                                     split-buffer

* This sets up most of the parameters you need for a join

* The join below replaces the original extension in 
* split-buffer with the extension in extension-buffer, and 
* puts the result in join-buffer.
     move 1 to extension-strt
     move 3 to extension-len
     call "CBL_JOIN_FILENAME" using split-params
                                    join-buffer
                                    split-buffer
                                    split-buffer
                                    extension-buffer

$if environ = "unix"
     if join-buffer = "/DIR/FILE.CBL" then
$else
     if join-buffer = "A:\DIR\FILE.CBL" then
$end
         display "first test passed"
     else
         display "first test failed"
     end-if

* It is harder to set up a join without doing a split first,
* but this is what you would need to do.

     move 1 to cblte-sj-device-offset
               cblte-sj-basename-offset
               cblte-sj-extension-offset

     move length of path-buffer to cblte-sj-device-length
     move length of basename-buffer 
                                to cblte-sj-basename-length	
     move length of extension-buffer 
                                to cblte-sj-extension-length
     move length of join-buffer to cblte-sj-join-buf-len

     move 0 to cblte-sj-split-join-flag1
     move 24 to cblte-sj-param-length

$if environ = "unix"
     move "/path" to path-buffer
$else
     move "c:\path" to path-buffer
$end
     move "basename" to basename-buffer

     move "ext" to extension-buffer

     call "CBL_JOIN_FILENAME" using split-params
                                    join-buffer
                                    path-buffer
                                    basename-buffer
                                    extension-buffer

$if environ = "unix"
     if join-buffer = "/path/basename.ext" then
$else
     if join-buffer = "c:\path\basename.ext" then
$end
         display "second test passed"
     else

         display "second test failed"
     end-if
  stop run.

X"91" function 46 - Enable Null Insertion

Enables insertion of a null character (x"00") before data 4characters whose value is less than x"20" in line sequential files.

Syntax:
call x"91" using result                   function-code     
               parameter
Parameters:

result              pic x comp-x
function-code       pic x comp-x
parameter           FD name of file

On Entry:
function-code Value 46
parameter The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.
On Exit:
result Set to zero if the call was successful, non-zero otherwise.
Comments:

If you want to include non-ASCII data in a file, you must enable null insertion. This function enables null insertion for individual files regardless of the setting of the null insertion run-time switch (N).

A large number of support routines are required by x"91" and so, if you include this function in your program, the executable file will be very big.

Example:
 fd payroll-file 
      ... 
     call x"91" using result 
                      function-code 
                      payroll-file 

X"91" function 47 - Disable Null Insertion

Disables insertion of a null character (x"00") before data characters whose value is less than x"20" in line sequential files.

Syntax:
call x"91" using result                   function-code     
             parameter
Parameters:

result              pic x comp-x
function-code       pic x comp-x
parameter           FD name of file

On Entry:
function-code Value 47
parameter The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.
On Exit:
result Set to zero if the call was successful, non-zero otherwise.
Comments:

This function enables you to disable null insertion for individual files regardless of the setting of the null insertion run-time switch (N).

This function cannot be used if the file is declared as EXTERNAL.

A large number of support routines are required by x"91" and so, if you include this function in your program, the executable file will be very big.


X"91" function 48 - Enable Tab Insertion

Enables insertion of tab characters in line sequential files.

Syntax:
call x"91" using result                   function-code     
             parameter
Parameters:

result              pic x comp-x
function-code       pic x comp-x
parameter           FD name of file

On Entry:
function-code Value 48
parameter The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.
On Exit:
result Set to zero if the call was successful, non-zero otherwise.
Comments:

On input, all tab characters are expanded to the correct number of spaces, while on output to disk, multiple spaces before a tab stop position are contracted to a tab character. This function enables tab insertion for individual files regardless of the setting of the tab compression run-time switch (T).

A large number of support routines are required by x"91" and so, if you include this function in your program, the executable file will be very big.


X"91" function 49 - Disable Tab Insertion

Disables insertion of tab characters in line sequential files.

Syntax:
call x"91" using result                   function-code     
             parameter
Parameters:

result              pic x comp-x
function-code       pic x comp-x
parameter           FD name of file

On Entry:
function-code Value 49
parameter The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open.

On Exit:
result Set to zero if the call was successful, non-zero otherwise.
Comments:

This function enables you to disable null insertion for individual files regardless of the setting of the null insertion run-time switch (N).

A large number of support routines are required by x"91" and so, if you include this function in your program, the executable file will be very big.


X"91" function 52 - Use Two-byte Record Terminators

Uses two-byte record terminators in the specified line sequential or relative file.

Syntax:
call x"91" using result 
                 function-code 
                 parameter
Parameters:

result              pic x comp-x
function-code       pic x comp-x
parameter           FD name of file

On Entry:
function-code Value 52
parameter The file-identifier specified in the File Description (FD).
On Exit:
result Set to zero if the call was successful, non-zero otherwise.
Comments:

The record terminator used is x"0D0A" (carriage return, line feed).

A large number of support routines are required by x"91" and so, if you include this function in your program, the executable file will be very big.


X"91" function 53 - Use One-byte Record Terminators

Restores the UNIX default of one-byte record terminators when writing records to a line sequential or relative file.

Syntax:
call x"91" using result                   function-code     
             parameter
Parameters:

result              pic x comp-x
function-code       pic x comp-x
parameter           FD name of file

On Entry:
function-code Value 53
parameter The file-identifier specified in the File Description (FD).
On Exit:
result Indicates the result of the call. Set to zero if successful, non-zero if not successful.
Comments:

The one-byte record terminator used is x"0A" (line feed).

A large number of support routines are required by x"91" and so, if you include this function in your program, the executable file will be very big.



Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousRebuild Miscellaneous TopicsNext