gcobol supplies replaceable I/O functionality via gcobol_fileops(). It returns a pointer to a structure
of C function pointers that implement sequential, relative, and indexed file operations over files whose
On Disk Format (ODF) is defined by gcobol. A user wishing to use another library that implements the
same functionality over a different ODF must supply a different implementation of gcobol_fileops(), plus
7 functions, as described in this document. The pointers to those user-implemented functions are placed
in a C++ object of type gcobol_io_t and an instantiation of that type is returned by gcobol_fileops().
The compiled program initializes I/O operations by calling that function the first time any file is
opened.
Each function takes as its first argument a pointer to a cblc_file_t object, which is analogous to a FILE
object used in the C stdio functions. The cblc_file_t structure acts as a communication area between the
compiled program and the I/O library. Any information needed about the file is kept there. Notably, the
outcome of any operation is stored in that structure in the file_status member, not as a return code.
Information about the operation (as opposed to the file) appear as parameters to the function.
cblc_file_t has one member, not used by gcobol, that is reserved for the user:
void*implementation.
User-supplied I/O functions may assign and dereference implementation. gcobol will preserve the value,
but never references it.
The 7 function pointers in gcobol_io_t are
Open voidopen_t(cblc_file_t*file, char*filename, intmode_char, intis_quoted)
parameters:
filename is the filename, as known to the OS
mode_char is one of
‘r’ OPEN INPUT: read-only mode
‘w’ OPEN OUTPUT: create a new file or overwrite an existing one
‘a’ EXTEND: append to sequential file
‘+’ modify existing file
is_quoted If true, filename is taken literally. If false, filename is interpreted as the name
of an environment variable, the contents of which, if extant, are taken as the name
of the file to be opened. If no such variable exists, then filename is used
verbatim.
Close voidclose_t(cblc_file_t*file, inthow)
parameters:
how A value of 0x08 closes a “REEL unit”. Because no such thing is supported, the function
sets the file status to “07”, meaning notatape.
Start voidstart_t(cblc_file_t*file, intrelop, intfirst_last_key, size_tlength)
parameters:
relop is one of
0 means ‘<’
1 means ‘<=’
2 means ‘=’
3 means ‘!=’
4 means ‘>=’
5 means ‘>’
first_last_key
is the key number (starting at 1) of the key within the cblc_file_t structure.
length is the size of the key (TODO: per the START statement?)
Read voidread_t(cblc_file_t*file, intwhere) parameters:
where-2 PREVIOUS
-1 NEXT
N represents a key number, starting with 1, in the cblc_file_t structure. The value of
that key is used to find the record, and read it.
Write voidwrite_t(cblc_file_t*file, unsignedchar*data, size_tlength, intafter, intlines, intis_random)
parameters:
data address of in-memory buffer to write
length length of in-memory buffer to write
after has the value 1 if the
AFTER ADVANCING n LINES
phrase was present in the WRITE statement, else 0
lines may be one of
-666 ADVANCING PAGE
-1 no ADVANCING phrase appeared
0 ADVANCING 0 LINES is valid
>0 the value of n in ADVANCING n LINES
is_random is true if the accessmode is RANDOM
Rewrite voidrewrite_t(cblc_file_t*file, size_tlength, boolis_random) parameters:
length number of bytes to write
is_randomtrue if accessmode is RANDOM
Delete voiddelete_t(cblc_file_t*file, boolis_random) parameters:
is_randomtrue if accessmode is RANDOM
The library implements one function that the gcobol-produced binary calls directly:
gcobol_io_t*gcobol_fileops()
This function populates a gcobol_io_t object with the above function pointers. The compiled binary
begins by calling gcobol_fileops(), and then uses the supplied pointers to effect I/O.
Install Now
PNG Icons
