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 Change the current directory
CBL_CHECK_FILE_EXIST Check if a file exists
CBL_COPY_FILE Copy a file
CBL_CREATE_DIR Create a directory
CBL_DELETE_DIR Delete a directory
CBL_DELETE_FILE Delete a file
CBL_GET_CURRENT_DIR Returns the current directory
CBL_JOIN_FILENAME Create a filename by joining together its component parts
CBL_LOCATE_FILE Locate a file, expand path
CBL_READ_DIR Read the current directory
CBL_RENAME_FILE Rename a file
CBL_SPLIT_FILENAME Split a filename into its component parts
x"91" function 46 Enable null insertion
x"91" function 47 Disable null insertion
x"91" function 48 Enable tab insertion
x"91" function 49 Disable tab insertion
x"91" function 52 Use two-byte record terminators
x"91" function 53 Use one-byte record terminators

10.2 Key to File Handling Library Routines

Descriptions for all of the call-by-name routines appear alphabetically. 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 path-name 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        Group item defined as:
    file-size           pic x(8) comp-x.
    file-date           Group item defined as:
        day                 pic x comp-x.
        month               pic x comp-x.
        year                pic x(2) comp-x.
    file-time           Group item defined as:
        hours               pic x comp-x.
        minutes             pic x comp-x.
        seconds             pic x comp-x.
        hundredths          pic x comp-x.
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:
file-size The size of the file in bytes.
file-date The date the file was created.
file-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 path-name terminated by space or null (x"00").
On Exit:

None


CBL_DELETE_DIR

Deletes a directory. The directory is only deleted 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 path-name 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 path-name, 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 pic x(4) comp-5.
name-length pic x(4) comp-5.
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     split-join-param
                                        join-buffer
                                        path-buffer
                                        basename-buffer
                                        extension-buffer
                              returning status-code
Parameters:
split-join-param Group item defined as:
param-length pic x(2) comp-x.
splitjoin-flg1 pic x comp-x
splitjoin-flg2 pic x comp-x.
path-strt pic x(2) comp-x.
path-len pic x(2) comp-x.
basename-strt pic x(2) comp-x.
basename-len pic x(2) comp-x.
extension-strt pic x(2) comp-x.
extension-len pic x(2) comp-x.
total-length pic x(2) comp-x.
split-buf-len pic x(2) comp-x.
join-buf-len pic x(2) comp-x.
first-path-len pic x(2) comp-x.
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:
param-length Length of split-join-param in bytes, including the two bytes for param-length. The normal value for param-length is 24.
splitjoin-flg1 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
spltjoin-flg2 Can be set as follows:
Bit Value Meaning
2 1 If bit 1 of spltjoin-flg1 is set to 0, then this indicates that the length of each filename component is given exactly by path-len, basename-len and extension-len. This flag can be used when there are known significant spaces in one of the filename components. If bit 1 of spltjoin-flg1 is 1, then this is ignored,
0 Length of filename components is determined by bit 1 of splitjoin-flg1.
1 Reserved.
0 Reserved.
path-strt Offset of the start of the path in path-buffer, indexed from one.
path-len Length of path if not space- or null-terminated.
basename-strt Offset of the start of the basename in basename-buffer, indexed from one.
basename-len Length of basename if not space- or null-terminated.
extension-strt Offset of the start of the extension in extension-buffer, indexed from one.
extension-len Length of extension if not space- or null-terminated.
path-buffer Pathname.
basename-buffer Basename
extension-buffer Extension.
join-buf-len Length of join-buffer.
On Exit:
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 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 splitjoin-flg1. 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 splitjoin-flg1 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 path-len, basename-len, and extension-len respectively, if they are terminated with either a space or a null, depending on the setting bit 1 of splitjoin-flg1.

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 total-length is less than join-buf-len, the characters after the end of the filename are nulls or spaces depending on bit 1 of splitjoin-flg1.

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.

See Also:

CBL_SPLIT_FILENAME

Example:
***************************************************************
*                                                             *
*               (C) Micro Focus Ltd. 1991                     *
*                                                             *
*                     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.
     03  param-length        pic xx comp-x   value 24.
     03  splitjoin-flg1      pic x  comp-x   value 0.

     03  splitjoin-flg2      pic x  comp-x.
     03  path-strt           pic xx comp-x.
     03  path-len            pic xx comp-x.
     03  basename-strt       pic xx comp-x.
     03  basename-len        pic xx comp-x.
     03  extension-strt      pic xx comp-x.
     03  extension-len       pic xx comp-x.
     03  total-length        pic xx comp-x.
     03  split-buf-len       pic xx comp-x   value 65.
     03  join-buf-len        pic xx comp-x   value 65.
     03  first-path-len      pic xx comp-x.

 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 split-buf-len
                join-buf-len

* Set flag for space-terminated, fold to upper
     move 1 to splitjoin-flg1

$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 path-strt
               basename-strt
               extension-strt

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

     move 0 to splitjoin-flg1
     move 24 to param-length

$if environ = "unix"
     move "/path" to pat-buffer
$else
     move "c:\path" to pat-buffer
$end
     move "basename" to bas-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           pic x comp-x.
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 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    pic x comp-x.
status-code         See Key

On Entry:
path-name-length Length of path-name to be used. If this is too small for the path-name, the routine fails.
On Exit:
path-name Relative or absolute path-name 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 path-name, 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 path-name, this must contain the same path-name. 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     split-join-param
                                         split-buffer
                               returning status-code
Parameters:
split-join-param Group item defined as:
param-length pic x(2) comp-x.
splitjoin-flg1 pic x comp-x.
splitjoin-flg2 pic x comp-x.
path-strt pic x(2) comp-x.
path-len pic x(2) comp-x.
basename-strt pic x(2) comp-x.
basename-len pic x(2) comp-x.
extension-strt pic x(2) comp-x
extension-len pic x(2) comp-x.
total-length pic x(2) comp-x.
split-buf-len pic x(2) comp-x.
join-buf-len pic x(2) comp-x
first-path-len pic x(2) comp-x
split-buffer pic x(n).
status-code See Key.
On Entry:
param-length Length of split-join-param in bytes, including the two bytes for param-length. The normal value for param-length is 24.
splitjoin-flg1
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.
split-buf-len Length of split-buffer.
split-buffer The string to split.
On Exit:
splitjoin-flg2 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
path-strt Start of pathname in split-buffer, from one.
path-len Length of pathname; zero if there is none. This includes any following colon (:).
basename-strt Start of basename in split-buffer, from one.
basename-len Length of basename; zero if there is none. This does not include the following period (.).
extension-strt Start of extension in split-buffer, from one.
extension-len Length of extension; zero if there is none. This does not include the preceding period (.).
total-length Total number of characters in the string.
first-path-len 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 splitjoin-flg1 is set then this routine folds to upper case. If bit 1 of splitjoin-flg1 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 splitjoin-flg1. 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 splitjoin-flg1 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 extension-len is 1 and extension-strt points to the last period (.).

See Also:

CBL_JOIN_FILENAME

Example:
***************************************************************
*                                                             *
*               (C) Micro Focus Ltd. 1991                     *
*                                                             *
*                     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.
     03  param-length        pic xx comp-x   value 24.
     03  splitjoin-flg1      pic x  comp-x   value 0.

     03  splitjoin-flg2      pic x  comp-x.
     03  path-strt           pic xx comp-x.
     03  path-len            pic xx comp-x.
     03  basename-strt       pic xx comp-x.
     03  basename-len        pic xx comp-x.
     03  extension-strt      pic xx comp-x.
     03  extension-len       pic xx comp-x.
     03  total-length        pic xx comp-x.
     03  split-buf-len       pic xx comp-x   value 65.
     03  join-buf-len        pic xx comp-x   value 65.
     03  first-path-len      pic xx comp-x.

 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 split-buf-len
                join-buf-len

* Set flag for space-terminated, fold to upper
     move 1 to splitjoin-flg1

$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 path-strt
               basename-strt
               extension-strt

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

     move 0 to splitjoin-flg1
     move 24 to param-length

$if environ = "unix"
     move "/path" to pat-buffer
$else
     move "c:\path" to pat-buffer
$end
     move "basename" to bas-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 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 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 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 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 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:

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