Converting Files | Miscellaneous Facilities |
This chapter describes the COBOL System Library routines which you can use to manipulate files.
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. |
Changes the current directory.
call "CBL_CHANGE_DIR" using path-name returning status-code
path-name
pic
x(n). status-code
See
Key in the Preface.
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. |
None
Checks whether a file exists and returns details if it does.
call "CBL_CHECK_FILE_EXIST" using filename file-details returning status-code
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.
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. |
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. |
You cannot use wildcard characters in filenames.
Copies a file.
call "CBL_COPY_FILE" using filename1 filename2 returning status-code
filename1
pic
x(n). filename2
pic
x(n). status-code
See
Key in the Preface.
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. |
None.
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.
Creates a subdirectory. All the directories in the given path, except the last, must already exist.
call "CBL_CREATE_DIR" using path-name returning status-code
path-name
pic
x(n). status-code
See
Key in the Preface.
path-name |
Relative or absolute path-name terminated by space or null (x"00"). |
None
Deletes a directory. The directory is only deleted if it is empty.
call "CBL_DELETE_DIR" using path-name returning status-code
path-name
pic
x(n). status-code
See
Key in the Preface.
path-name |
Relative or absolute path-name terminated by space or null (x"00"). |
None
Deletes a file.
call "CBL_DELETE_FILE" using filename returning status-code
filename
pic
x(n). status-code
See
Key in the Preface.
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. |
None
You cannot use wildcard characters in filenames.
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.
call "CBL_LOCATE_FILE" using user-file-spec user-mode actual-file-spec exist-flag path-flag returning status-code
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.
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:
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.
|
||||||
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. |
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.
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.
|
||||||||||||
status-code |
Return status:
|
With the static linked run-time system (16-bit COBOL system only) this routine does not search libraries for files.
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 |
Returns the current directory or path.
call "CBL_READ_DIR" using path-name path-name-length returning status-code
path-name
pic
x(n). path-name-length
pic x
comp-x. status-code
See
Key in the Preface.
path-name-length |
Length of path-name to be used. If this is too small for the path-name, the routine fails. |
path-name |
Relative or absolute path-name terminated by space or null (x"00"). |
Changes the name of a file.
call "CBL_RENAME_FILE" using old-filename new-filename returning status-code
old-filename
pic
x(n). new-filename
pic
x(n). status-code
See
Key in the Preface.
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 |
None
Returns all the valid drives on a PC.
call "PC_FIND_DRIVES" using drive-info returning status-code
drive-info
pic
x(4) comp-x. status-code
See
Key in the Preface.
None
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. |
This routine is only available in the DOS, Windows and OS/2 environments.
Returns the current default drive letter.
call "PC_READ_DRIVE" using drive returning status-code
drive
pic
x. status-code
See
Key in the Preface.
None.
drive |
Drive letter, upper or lower case. |
This routine is only available in the DOS, Windows and OS/2 environments.
Sets the default drive letter.
call "PC_SET_DRIVE" using drive returning status-code
drive
pic
x. status-code
See
Key in the Preface.
drive |
Drive letter, upper or lower case. |
None
This routine is only available in the DOS, Windows and OS/2 environments.
Enables insertion of a null character (x"00") before data characters whose value is less than x"20" in line sequential files.
call x"91" using result function-code parameter
result
pic
x comp-x function-code
pic
x comp-x parameter
FD
name of file
function |
Value 46 |
parameter |
The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open. |
result |
Set to zero if the call was successful, non-zero otherwise. |
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.
fd payroll-file ... call x"91" using result function-code payroll-file
Disables insertion of a null character (x"00") before data characters whose value is less than x"20" in line sequential files.
call x"91" using result function-code parameter
result
pic
x comp-x function-code
pic
x comp-x parameter
FD
name of file
function |
Value 47 |
parameter |
The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open. |
result |
Set to zero if the call was successful, non-zero otherwise. |
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.
Enables insertion of tab characters in line sequential files.
call x"91" using result function-code parameter
result
pic
x comp-x function-code
pic
x comp-x parameter
FD
name of file
function |
Value 48 |
parameter |
The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open. |
result |
Set to zero if the call was successful, non-zero otherwise. |
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.
Disables insertion of tab characters in line sequential files.
call x"91" using result function-code parameter
result
pic
x comp-x function-code
pic
x comp-x parameter
FD
name of file
function |
Value 49 |
parameter |
The file-identifier specified in the File Description (FD). Must refer to a line sequential file which is currently open. |
result |
Set to zero if the call was successful, non-zero otherwise. |
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.
Uses two-byte record terminators in the specified line sequential or relative file.
call x"91" using result function-code parameter
result
pic
x comp-x function-code
pic
x comp-x parameter
FD
name of file
function |
Value 52 |
parameter |
The file-identifier specified in the File Description (FD). |
result |
Set to zero if the call was successful, non-zero otherwise. |
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.
Restores the UNIX default of one-byte record terminators when writing records to a line sequential or relative file.
call x"91" using result function-code parameter
result
pic
x comp-x function-code
pic
x comp-x parameter
FD
name of file
function |
Value 53 |
parameter |
The file-identifier specified in the File Description (FD). |
result |
Indicates the result of the call. Set to zero if successful, non-zero if not successful. |
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.
Searches a directory for a given file specification.
call X"91" using result function-code parameter
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)
function-code |
Contains 69. | ||||||||||||||||
f-action |
Defines the action to perform:
|
||||||||||||||||
f-attrin |
Attribute byte. Bits set indicate that only files with
those attributes are to be included.
|
||||||||||||||||
f-filein |
The space-terminated filename specification of the file(s) required. This can contain a drive/directory or any wildcard characters. |
f-error |
Contains a status of the result:
|
||||||||||||||||
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:
|
||||||||||||||||
f-time |
Time file was created, in DOS format:
|
||||||||||||||||
f-date |
Date file was created, in DOS format:
|
||||||||||||||||
f-size |
The size of the file in bytes. | ||||||||||||||||
f-fileout |
The name of the file found, space-terminated. |
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.
Converting Files | Miscellaneous Facilities |