This document describes a generic interface to a set of routines designed to create, populate, read and modify any data files to which Open GENIE has access.
The generic specification here gives a fairly language independent specification of the data access interface. The API is divided into groups of similar operations. In this interface, Handle refers to string containing a name which the interface can then use to access the data.
Function | Return value | Description |
GX_activate_session(in default_format) | integer status code | Initialises the interface selecting a default data format. |
GX_deactivate_session() | integer status code | Deactivates the interface, frees storage |
Needed to initialise and terminate operation of the interface system.
Function | Return value | Description |
GX_select_source(in filename) | integer status code | Selects a data source for subsequent operations |
GX_select_destination(in filename) | integer status code | Selects a destination file for subsequent operations |
GX_directory(in filename, out dir_listing) | integer status code | Returns a directory of tagged fields available in a data file. |
Allows selection and investigation of the contents of data files. If "flag" is set to "NEW" calling GX_put will create a new data file. Normally, calling GX_put for a non-existent file will result in an error.
Function | Return value | Description |
GX_get(io handle, in tag, in object-id) | integer status code | Associates a handle with the referenced data file object. |
GX_put(io handle, in tag, in object-id, in flag) | integer status code | Writes data associated with a handle into a data file. |
References to an object in the data file can be made either by
a string tag or an object-id (number) for the data file. For an
GX_get, if both are specified, the tag must correspond to the tag
on the object selected by the object-id. Objects may also be
accessed by block number if the object-id is negative (eg -1 for
block 1).
For an GX_put, the object at the object-id specified may be overwritten with the new tag and associated handle value. If the "flag" parameter to GX_put is set to "OVERWRITE" , when the object-id corresponds with that already in an output file, the object and tag will be overwritten.
Function | Return value | Description |
GX_handle_assign(io h_expression) | integer status code | Allows structural assignment between handles. |
GX_release_handle(io handle) | integer status code | Deactivates the handle, releases storage. |
Handles allow an associated data item to be manipulated to allow operations such as structural parsing, and array slicing to get the exact data required by the calling application.