Opening, Closing and Copying Databases

Before any database accessing can take place the gap4 database must be opened. This is done using the open_db call. This returns an io handle which should be passed to all other functions accessing the database.

open_db
 -name          database_name
?-version       version?
?-create        boolean?
?-access        access_mode?

This opens a database named database_name. The actual files used will be database_name.version. The routine is used for both creating a new database and opening an existing database. The value returned is the io handle of the opened database. More than one database may be opened at one time.

-name database_name

Specifies the database name. The name is the start component of the two filenames used for storing the database and so is the section up to, but not including, the full stop. This is not an optional argument.

-version version

This optional parameter specifies the database version. The version is the single character after the full stop in the UNIX database filenames. It is expected to be a single character. The default value (as used for newly created databases) is "0".

-create boolean

Whether to open an existing database (-create 0) or a new database (-create 1). The default here is 0; to open an existing database.

-access access_mode

The access_mode specifies whether the database is to be opened in read-only mode or read-write mode. Valid arguments are "r", "READONLY", "rw" and "WRITE". If a database is opened in "rw" or "WRITE" mode a BUSY file will be created. If the BUSY file already exists then the database is opened in read-only mode instead. Either way, the read_only Tcl variable is set to 0 for read-write and 1 for read-only mode.

close_db
 -io            io_handle

This closes a previously opened database. Returns nothing, but produces a Tcl error for failure.

-io io

Specifies which database to close. The io is the io handle returned from a previous open_db call. Attempting to close databases that have not been opened will lead to undefined results.

copy_db
 -io            io_handle
 -version       version
?-collect       boolean?

This command copies a currently open database to a new version number. The currently opened database is not modified. After copying the current open database referred to by io_handle is still the original database.

-io io

Specifies which database to copy. The io is the io handle returned from a previous open_db call. Attempting to copy databases that have not been opened will lead to undefined results.

-version version

This parameter specifies the database version to create to place the copy in.

-collect boolean

This optional parameter specifies whether to perform garbage collection when copying the file. A value of 0 means no garbage collection; which is simply to do a raw byte-by-byte copy of the two database files. A non zero value will read and write each reading, contig, (etc) in turn to the new database, thus resolving any database fragmentation. The default value is "0".