PreviousConverting Files Miscellaneous FacilitiesNext"

Chapter 11: Directory Handling

This chapter describes the COBOL System Library routines which you can use to manipulate files.

11.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_LOCATE_FILE Locate a file, expand path
CBL_READ_DIR Read the current directory
CBL_RENAME_FILE Rename a file
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

DOS, Windows and OS/2:
The following PC_ routines are only available in the DOS, Windows and OS/2 environments.

PC_FIND_DRIVES Find valid drives
PC_READ_DRIVE Read the current drive
PC_SET_DRIVE Set the current drive
x"91" function 69 Scan a directory.

11.2 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 in the Preface.

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 in the Preface.

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_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 in the Preface.

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.

DOS, Windows and OS/2:
CBL_COPY_FILE emulates the equivalent operating system call. On DOS, Windows and OS/2, therefore, the new file is stamped with the same date and time as the original file.

UNIX:
CBL_COPY_FILE emulates the equivalent operating system call. On UNIX, therefore, the new file is stamped with the current date and time.


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 in the Preface.

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 in the Preface.

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 in the Preface.

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_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 in the Preface.

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

Comments:

With the static linked run-time system (16-bit COBOL system only) this routine does not search libraries for files.

Example:

user-file-spec can take the form:

DOS, Windows and OS/2 UNIX
Standard filename:
    path\filename.ext
path/filename.ext
Embedded environment variable:
    $envname\filename.ext
$envname/filename.ext
Embedded library name:
    path\lbr-name.lbr\filename.ext
path/lbr-name.lbr/filename.ext


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 in the Preface.

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 in the Preface.

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


PC_FIND_DRIVES

Returns all the valid drives on a PC.

Syntax:
call "PC_FIND_DRIVES" using     drive-info 
                      returning status-code
Parameters:

drive-info          pic x(4) comp-x.
status-code         See Key in the Preface.

On Entry:

None

On Exit:

drive-info The 26 least-significant bits correspond to drives a: to z:, with a: represented by bit 0 (the least significant bit) and z: represented by bit 25. The corresponding bit is set for each valid drive.

Comments:

This routine is only available in the DOS, Windows and OS/2 environments.


PC_READ_DRIVE

Returns the current default drive letter.

Syntax:
call "PC_READ_DRIVE" using     drive 
                     returning status-code
Parameters:

drive               pic x.
status-code         See Key in the Preface.

On Entry:

None.

On Exit:

drive Drive letter, upper or lower case.

Comments:

This routine is only available in the DOS, Windows and OS/2 environments.


PC_SET_DRIVE

Sets the default drive letter.

Syntax:
call "PC_SET_DRIVE" using     drive 
                    returning status-code
Parameters:

drive               pic x.
status-code         See Key in the Preface.

On Entry:

drive Drive letter, upper or lower case.

On Exit:

None

Comments:

This routine is only available in the DOS, Windows and OS/2 environments.


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

You should be aware that, on UNIX, 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.

You should be aware that, on UNIX, 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).

You should be aware that, on UNIX, 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).

You should be aware that, on UNIX, 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).

This routine is only available on UNIX.

You should be aware that, on UNIX, 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).

This routine is only available on UNIX.

You should be aware that, on UNIX, 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 69 - Scan Directory

Searches a directory for a given file specification.

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

result              Group item defined as:
    f-error             pic x comp-x
    f-handle            pic x(2) comp-x
    f-attrout           pic x comp-x
    f-time              pic x(2) comp-x
    f-date              pic x(2) comp-x
    f-size              pic x(4) comp-x
    f-fileout           pic x(n)
function-code       pic x comp-x
parameter           Group item defined as:
    f-action            pic x comp-x
    f-attrin            pic x comp-x
    f-filein            pic x(m)

On Entry:

function-code Contains 69.
f-action Defines the action to perform:

0 Find the first matching file
1 Find the next matching file
2 Terminate the search early
3 Find one matching file
f-attrin Attribute byte. Bits set indicate that only files with those attributes are to be included.

bit 7 Unused
bit 6 Unused
bit 5 Archived file
bit 4 Subdirectory
bit 3 Volume label
bit 2 System file

bit 1 Hidden file
bit 0 Read-only file
f-filein The space-terminated filename specification of the file(s) required. This can contain a drive/directory or any wildcard characters.

On Exit:

f-error Contains a status of the result:

0 Success/file found
1 No more files
2 Error
f-handle The find handle. This field is set by the find-first function (see f-action above) and should not be altered until the corresponding terminate search has been done.
f-attrout Attribute byte of file found:

bit 7 Unused
bit 6 Unused
bit 5 Archived file
bit 4 Subdirectory
bit 3 Volume label
bit 2 System file
bit 1 Hidden file
bit 0 Read-only file
f-time Time file was created, in DOS format:

bits 15-11 Hour, 0-23
bits 10-5 Minute, 0-59
bits 4-0 Bi-second, 0-29
f-date Date file was created, in DOS format:

bits 15-9 Year, 0-119 (1980-2099)
bits 8-5 Month, 1-12
bits 4-0 Day, 1-31
f-size The size of the file in bytes.
f-fileout The name of the file found, space-terminated.

Comments:

This routine is only available in the DOS, Windows and OS/2 environments.

Bit 3 of f-attrin (volume label) cannot be used on OS/2.

To find a single file, use the find-one function.

To find several files, use the find-first function and then use the find-next function repeatedly. When there are no more matching files, find-next returns 1 in f-error. If you do not keep calling find-next until this happens, you must finish by calling the terminate-search function.

The f-handle field should be set to zero before you execute the find first or find-one function. After that, if you are using the first/next/terminate sequence this field should not be changed until after the terminate search. If you are using the find-one function this field is automatically reset to 0 after that call.

If at any time f-error returns 1 or 2, a terminate search has been carried out automatically, and you should not execute the terminate-search function.

This routine cannot be used to check the existence of a network share resource, such as \\server1\share1, but it can be used to locate files or directories on that share, such as \\server1\share1\*.


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

PreviousConverting Files Miscellaneous FacilitiesNext"