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 (). 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 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 (as opposed to the ) 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
void (cblc_file_t *file, char *filename, int mode_char, int is_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 , 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
void (cblc_file_t *file, int how)
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 .
Start
void (cblc_file_t *file, int relop, int first_last_key, size_t length)
parameters:
relop
is one of
means ‘<’
means ‘<=’
means ‘=’
means ‘!=’
means ‘>=’
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
void (cblc_file_t *file, int where) parameters:
where
PREVIOUS
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
void (cblc_file_t *file, unsigned char *data, size_t length, int after, int lines, int is_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 statement, else 0
lines
may be one of
ADVANCING PAGE
  -1
no phrase appeared
   0
ADVANCING 0 LINES is valid
  >0
the value of n in ADVANCING n LINES
is_random
is true if the access mode is RANDOM
Rewrite
void (cblc_file_t *file, size_t length, bool is_random) parameters:
length
number of bytes to write
is_random
if access mode is RANDOM
Delete
void (cblc_file_t *file, bool is_random) parameters:
is_random
if access mode is RANDOM

The library implements one function that the gcobol-produced binary calls directly:

I/O functions return . 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.

Copyright (c) 2021-2026 Symas Corporation

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of the Symas Corporation nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
March 2024 Linux