The GapIO Structure

The main object passed around between the I/O functions is the GapIO structure. This is returned from the open_db function and is then passed around in much the same manner as a unix file descriptor or FILE pointer is. The structure, held in `gap4/IO.h', is as follows.

typedef struct {
    GapServer *server;		/* our server */
    GapClient *client;		/* ourselves */

    int Nviews;			/* number of locked views */
    Array views;		/* all locked views */

    GDatabase db;		/* main database record */
    Bitmap freerecs;		/* bitmap of unused */
    Array contigs;		/* list of contig */
    Array readings;		/* list of reading records */
    Array annotations;		/* list of annotation records */
    Array templates;		/* list of template records */
    Array clones;		/* list of clone records */
    Array vectors;		/* list of vector records */

    int4 *relpos;		/* relpg[] */
    int4 *length;		/* length[] */
    int4 *lnbr;			/* lnbr[] */
    int4 *rnbr;			/* rnbr[] */

    char db_name[DB_FILELEN];	/* database "file.version" */

    Array contig_order;		/* order of contigs */
    Array contig_reg;		/* Registration arrays for each contig */

#ifdef GAP_CACHE
    Array reading;		/* Array of GReading _structures_ */
    Array read_names;		/* Array of reading names */
#endif
    int freerecs_changed;	/* Whether to flush freerecs bitmap */
    Bitmap updaterecs;		/* bitmap of updated records */
    Bitmap tounlock;		/* bitmap of records to unlock at next flush */
} GapIO;

Many of the items held within this structure are used internally by the I/O functions. However it's worth describing all very briefly.

server

client

The server and client pointers are used in the low level g library communication. They need not be used by any external code.

Nviews

views

Each record in the database needs to be locked before it can be accessed. A view is returned for each independent lock of a record. These are used internally by the low level reading and writing function.

db

This is a direct copy of the GDatabase structure for this database. This needs to be kept up to date with the on disk copy whenever changes are made (eg by adding a new reading).

freerecs

This is a copy of the free records bitmap referenced by the io->db.freerecs field. It is kept up to date internally.

contigs

readings

annotations

templates

clones

vectors

These are lookup arrays to convert structure numbers to record numbers. For instance, all readings are numbered from 1 upwards. Similarly for contigs. However reading number 1 and contig number 1 will have their own unique record numbers in the g database. The extensible array package is used for storing this information. To translate from reading number N to the record number use "arr(GCardinal, io->readings, N-1)".

relpos

length

lnbr

rnbr

These are arrays of 4-byte integers of size io->db.actual_db_size. They hold information about both readings and contigs. For readings, the array contents hold copies of the position, sequence_length, left and right fields of the GReadings structures. Reading number R has this data stored in array elements R (counting from element 0, which is left blank). For contigs, the array contents hold copies of the length, left and right fields of the GContigs structure. For historical reasons the contig length is held in the relpos array with the length array left blank. Contig number C has this data stored in array elements io->db.actual_db_size-C. For ease of use and future compatibility several macros have been defined for accessing this data. See section IO.h Macros. These should be used instead of direct access. Thus to find the length of reading R we use io_length(io,R) and to find the length of contig C we use io_clength(io,C). NOTE: These arrays are not updated automatically. If you modify data using one of the write functions you also need to update the arrays in sync. This is one of the problems that the check database command looks for so mistakes should be obvious.

db_name

The name of the database in a file.version syntax. This array is allocated to be DB_FILELEN bytes long. The io_name macro should be used for accessing this field.

contig_order

An array loaded from io->db.contig_order. This holds the left to right ordering of contigs. It is automatically undated by the create and delete contig function.

contig_reg

The contig registration scheme information. There's an entire chapter on this topic. See section Contig Registration Scheme.

reading

read_names

These are cached copies of the GReadings structures and the reading names referenced by the GReadings.name fields. They are updated automatically when using the correct functions (gel_read and gel_write). Use of lower level functions is disallowed for accessing this data.

freerecs_changed

updaterecs

tounlock

These three are used internally for maintaining the update and data flushing scheme. freerecs_changed is a flag to state whether or not the freerecs bitmap needs writing to disk. updaterecs and tounlock are bitmaps with a bit per record to signify whether the record needs rewriting or unlocking. Their use is not required outside of the low level functions.