| Rebuild | Miscellaneous Topics | |
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 |
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.
Changes the current directory.
call "CBL_CHANGE_DIR" using path-name
returning status-code
path-name pic
x(n).
status-code See
Key
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
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.
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.
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
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.
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.
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
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
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
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.
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.
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
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:
|
user-file-spec can take the form:
path/filename.ext $envname/filename.ext path/lbr-name.lbr/filename.ext
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.
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
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
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
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.
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).
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.
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).
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).
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).
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).
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 © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Rebuild | Miscellaneous Topics | |