Open GENIE Data Access Interface

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.

Generic Routine Interface

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.

Session Control

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.

File operations

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.

Data reading/writing

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.

Handle Manipulation

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.