FILEIO Subroutines
Open or close a file.
call OpenFile(FILE_ID_IV, FILE_NAME_SV, ACCESS_MODE_SV)
call CloseFile(FILE_ID_IV)
FILE_ID_IV
A user-defined name that follows the rules for an ESL identifier. FILE_ID_IV must have been declared previously by a integer statement.
FILE_NAME _SV
A string variable that is the name of the file you want to open.
ACCESS_MODE _SV
A string variable that contains one of the following file modes, indicating how the file can be accessed after it is opened:
"read-only" or "read" or "r" or "e"
These indicate that the file will not be modified. An error message is generated when an attempt is made to open a non-existent file with read access specified. If the access mode is "e", then the file will be read using the EBCDIC character set.
"write-only" or "write" or "w" or "b"
These indicate that the file will be created if it does not exist. If an existing file is opened write-only, and it is not previously set as write-protected, the contents of the file will be erased. An error message is generated when a write-protected file is opened with write access specified. If the access mode is "b", then the file will be written using the EBCDIC character set.
"append" or "a" or "c"
If you open a file with append access, the file is preserved, and any output produced is appended to the end of the file. The file is created if it does not exist. An error message is generated when a write-protected file is opened with append access specified.If the access mode is "c", then the file will be read and written using the EBCDIC character set.
Description
Use these subroutines to open or close files.
The file identifier is actually a file descriptor, or handle, which is used internally to identify the file. This provides a more efficient means of accessing the file.
A call to OpenFile( ) associates the file identifier with the file to be opened. Therefore, whenever I/O is to be performed on the file, the file identifier is used instead of the filename, and it is always the first argument in all of the File I/O Library subroutines.
A call to CloseFile( ) disassociates the file identifier from the file.
If a file is opened twice for output, the one opened last will be the one that is actually written. Opening a file twice for reading is acceptable, as long as each call to OpenFile( ) specifies a unique file identifier. Opening a file for both reading and writing will produce different results depending on which one is opened and closed first. (See "Example.")
Errors (OpenFile( ))
The following errors can be returned by the OpenFile( ) subroutine.
FIO_E_ALREADYOPEN
File already open. This error occurs when you call OpenFile( ) twice using the same file identifier or when another process had already opened the file. Either use a unique file identifier for each call to OpenFile( ) or call CloseFile( ) for that file identifier before you open it again.
FIO_E_BADMODE
Unrecognized file mode specifier. Make sure file access mode begins with one of the following: "r", "R", "w", "W", "e", "E", "b", "B", "c", "C", "a", or "A".
FIO_E_BADPATH
File path does not exist.
FIO_E_CANTAPPEND
File is write-protected. Check file's access permission.
FIO_E_CANTREAD
File is read-protected. Check the access rights of the file's directory.
FIO_E_CANTWRITE
File is write-protected. Check file's access permission.
FIO_E_FILEHANDLE
Invalid file handle - internal error.
FIO_E_FILESHARING
File-sharing violation. Retry the command later.
FIO_E_OUTOFMEM
Insufficient system memory. System memory is too low to allocate.
Errors (CloseFile( ))
The following errors can be returned by the CloseFile( ) subroutine.
FIO_E_FILEHANDLE
Invalid file handle - internal error.
FIO_E_NOTOPEN
File has not been opened. This error occurs when you try to close a file that has not been opened.
Example
The following example of an ESL program shows the declaration of the FILE_ID, FILE_NAME, and ACCESS_MODE variables, and how they are used in calls to the OpenFile( ) and CloseFile( ) subroutines:
integer FileIDin
integer FileIDout
string FileName is "input.txt"
string FileNameOut is "output.txt"
string ReadIn is "read-only"
string WriteTo is "write-only"
include "fileio.inc"
key File at position 50 50
...
response to File is
call OpenFile(FileIDin, FileName, ReadIn)
if (errorlevel>0) then
... # Appropriate error
# handling
end if
call OpenFile (FileIDoutin, FileNameOut, WriteTo) # Using
if (errorlevel>0) then # string constants.
... # Appropriate error
# handling.
end if
... # Perform read and
# write operations.
call CloseFile (FileIDin)
if (errorlevel>0) then
... # Appropriate error
# handling.
end if
call CloseFile (FileIDout)
if (errorlevel>0) then
... # Appropriate error
# handling.
end if
