The HEASARC Database System

Application Programming Interface

The purpose of this API is to allow C programmers to access the interface routines directly without spawning a process. The API consists of two C libraries, including over twenty C routines:

/heasarc/src/HDBio/libHDBIO.a (internal only):

int HDB_dbopen(char *database,char *command)
Opens a connection with the supplied database via the Ingres or Sybase SQL terminal server and executes the given command. Connection remains open until HDB_dbclose() is called.

int HDB_dbopen_opt(char *database,char *command, char *sql_options)
Same as HDB_dbopen except it allows you to specify the command line options for the Ingres or Sybase SQL terminal server.

int HDB_dbread(char *buffer,int length)
Reads length bytes of output from the Ingres or Sybase terminal server which are returned in buffer.

void HDB_dbclose(void)
Closes the connection with the Ingres or Sybase SQL terminal server.

int HDBlock(char *database)
Creates a pseudo-exclusive lock on a database by creating a temporary table in that database. The lock is pseudo-exclusive because all necessary software must support and recognize the lock on a voluntary basis. Anyone can easily bypass the lock if they want to by using the Ingres or Sybase SQL terminal server or the HDBsql() and HDB_dbopen() routines. This locking mechanism is really only intended to prevent multiple processes or users from modifying the metabase tables at the same time. It is not intended to prevent read access during ingest, but it could with some software modification.

int HDBunlock(char *database)
Relinquishes lock on the given database. Naturally, it first checks to see if the user is the one who created the lock in the first place.

char *HDBwho_lock(char *database)
Returns string pointer containing the e-mail userid of the person who currently holds the lock on the database.

char *HDBwhen_lock(char *database)
Returns string pointer containing the date and time the lock was acquired.

int HDBcheck_servers(void)
Returns non-zero value if the metabase server and the Ingres or Sybase terminal server are both up and operational.

unsigned long int HDBcount_rows(char *database,char *table)
Counts the number of rows in a given table of a given database. If the first argument is a NULL pointer, it queries the metabase server for this information instead of counting the number of rows directly.

char *HDBgetmax(char *database,char *table,char *parameter)
Returns a string pointer to the maximum value of a given field in a given database and table. If the first argument is a NULL pointer, it queries the metabase server for this information instead.

char *HDBgetmin(char *database,char *table,char *parameter)
Same as HDBgetmax, but it returns the minimum value.

char *HDBmctalk(char **output,char *command)
Connect to the metabase server (HDBmcs), execute the command, and return all output in a malloc()'ed buffer.

char *HDBsql(char **output,char *database,char *command)
Connect to the Ingres or Sybase SQL terminal server, execute the SQL command, and return all output in a malloc()'ed buffer.

int HDBparm_exists(char *table_name,char *parameter_name)
Returns non-zero value if the supplied parameter is column in the given table.

int HDBtable_exists(char *table_name)
Returns non-zero value if the table exists.

int HDBtable_exists_db(char *database,char *table_name)
Same as previous, but it allows you to specify which database.

/heasarc/src/HDBexgest/libEXGEST.a (internal only):

int exgest_table(char *table_name,char *outfile,char *tmpdir)
Exports a table in TDAT format to an ASCII file with the name outfile with tmpdir as the directory where temporary files are created.

TABLE_INFO *exgest_metabase_info(char *table_name)
Returns all known metabase information about a given table in a malloc()'ed TABLE_INFO structure (defined in the C header file at /heasarc/src/HDBexgest/HDBtable.h).

void exgest_free_table(TABLE_INFO *table)
Free()'s the memory allocated for a TABLE_INFO structure.

int exgest_security(char *database,char *table_name)
Returns an integer signifying the public/private access of a given table. A negative value indicates an error occurred while determining the access rights, a aero means the public can access the data, and a positive value means the table is private.

Documentation prepared by the HEASARC Database Group

HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

Last modified: Tuesday, 18-Apr-2006 19:42:47 EDT