GCOBOL(3) | 3 (gcc cobol compiler) | GCOBOL(3) |
gcobol
—
GCC COBOL Front-end I/O function
API
libgcobol
#include
<symbols.h>
#include <io.h>
#include <gcobolio.h>
gcobol_io_t
gcobol_fileops
();
class gcobol_io_t { public: static const char constexpr marquee[64]; typedef void (open_t)( cblc_file_t *file, char *filename, int mode_char, int is_quoted ); typedef void (close_t)( cblc_file_t *file, int how ); typedef void (start_t)( cblc_file_t *file, int relop, // needs enum int first_last_key, size_t length ); typedef void (read_t)( cblc_file_t *file, int where ); typedef void (write_t)( cblc_file_t *file, unsigned char *data, size_t length, int after, int lines, int is_random ); typedef void (rewrite_t)( cblc_file_t *file, size_t length, bool is_random ); typedef void (delete_t)( cblc_file_t *file, bool is_random ); open_t *Open; close_t *Close; start_t *Start; read_t *Read; write_t *Write; rewrite_t *Rewrite; delete_t *Delete; ... };
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_t
(cblc_file_t
*file, char *filename, int
mode_char, int is_quoted)
close_t
(cblc_file_t
*file, int how)
start_t
(cblc_file_t
*file, int relop, int
first_last_key, size_t length)
read_t
(cblc_file_t
*file, int where) parameters:
write_t
(cblc_file_t
*file, unsigned char *data,
size_t length, int after,
int lines, int is_random)
rewrite_t
(cblc_file_t
*file, size_t length, bool
is_random) parameters:
delete_t
(cblc_file_t
*file, bool is_random) parameters:
The library implements one function that the
gcobol
-produced binary calls directly:
gcobol_fileops
()
gcobol_fileops
(), and then uses the supplied
pointers to effect I/O.I/O functions return
void.
gcobol_fileops
() returns
gcobol_io_t*.
The I/O library supplied by gcobol
,
libgcobolio.so, supports the I/O semantics defined by ISO
COBOL. It is not intended to be compatible with any other ODF. That is,
libgcobolio.so cannot be used to exchange data with any
other COBOL implementation.
The purpose of the gcobol_io_t structure is to allow the use of other I/O implementations with other ODF representations.
The library is not well tested, not least because it is not implemented.
The future is yet to come.
March 2024 | Linux |