Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals

DataBase


Files

file  psDB.h
 database types and functions

Data Structures

struct  psDB
 Database handle. More...

Functions

psDB * psDBInit (const char *host, const char *user, const char *passwd, const char *dbname)
 Opens a new database connection.
void psDBCleanup (psDB *dbh)
 Closes a database connection.
bool psDBCreate (psDB *dbh, const char *dbname)
 Creates a new database namespace.
bool psDBChange (psDB *dbh, const char *dbname)
 Changes the current database namespace.
bool psDBDrop (psDB *dbh, const char *dbname)
 Drops a database namespace.
bool p_psDBRunQuery (psDB *dbh, const char *query)
 Executes a SQL query.
bool psDBCreateTable (psDB *dbh, const char *tableName, psMetadata *md)
 Creates a new database table.
bool psDBDropTable (psDB *dbh, const char *tableName)
 Deletes a database table.
psArray * psDBSelectColumn (psDB *dbh, const char *tableName, const char *col, const psU64 limit)
 Selects a column from a table.
psVector * psDBSelectColumnNum (psDB *dbh, const char *tableName, const char *col, psElemType pType, const psU64 limit)
 Selects a column from a table and casts it to a given type.
psArray * psDBSelectRows (psDB *dbh, const char *tableName, psMetadata *where, const psU64 limit)
 Selects a set of rows from a table.
bool psDBInsertOneRow (psDB *dbh, const char *tableName, psMetadata *row)
 Insert a single row into a table.
bool psDBInsertRows (psDB *dbh, const char *tableName, psArray *rowSet)
 Insert a set of rows into a table.
psArray * psDBDumpRows (psDB *dbh, const char *tableName)
 Retrieves all rows from a table.
psMetadata * psDBDumpCols (psDB *dbh, const char *tableName)
 Retrieves all columns from a table.
psS64 psDBUpdateRows (psDB *dbh, const char *tableName, psMetadata *where, psMetadata *values)
 Updates the field values, as specified, in a table.
psS64 psDBDeleteRows (psDB *dbh, const char *tableName, psMetadata *where)
 Deletes rows, as specified, in a table.

Function Documentation

bool p_psDBRunQuery (  psDB *  dbh,
const char *  query
) 
 

Executes a SQL query.

This function will execute a string as a raw SQL query. No additional processing of the string or abstraction of the underlying database's SQL dialect is provided. Caveat emptor.

Returns:
true on success
Parameters:
dbh  Database handle
query  SQL string to execute

bool psDBChange (  psDB *  dbh,
const char *  dbname
) 
 

Changes the current database namespace.

Returns:
true on success
Parameters:
dbh  Database handle
dbname  Database namespace

void psDBCleanup (  psDB *  dbh  ) 
 

Closes a database connection.

Parameters:
dbh  Database handle

bool psDBCreate (  psDB *  dbh,
const char *  dbname
) 
 

Creates a new database namespace.

Returns:
true on success
Parameters:
dbh  Database handle
dbname  New database namespace

bool psDBCreateTable (  psDB *  dbh,
const char *  tableName,
psMetadata *  md
) 
 

Creates a new database table.

This function generates and executes the SQL needed to create a table named "tableName", with the column names and data types as described in "md". Each data item in the psMetadata collection represents a single table field. The name of the field is given by the name of the psMetadataItem and the data type is give by the psMetadataItem.type and psMetadataItem.ptype entries. A lookup table should be used to convert from PSLib types into MySQL compatible SQL data types. For example, a PS_META_STR would map to an SQL99 varchar. If the value of type is PS_META_STR then the psMetadataItem.data element is set to a string with the length for the field written as a text string. The value of the psMetadataItem.data element is unused for the PS_META_PRIMITIVE types. Other psMetadata types beyond PS_META_STR and PS_META_PRIMITIVE are not allowed in a table definition.

Database indexes can be specified setting the "comment" field to "Primary Key" or "Key". Comments are otherwise ignored.

Returns:
true on success
Parameters:
dbh  Database handle
tableName  Table name
md  Column names, types, and indexes

psS64 psDBDeleteRows (  psDB *  dbh,
const char *  tableName,
psMetadata *  where
) 
 

Deletes rows, as specified, in a table.

Delete the rows that are matched by "where" using the same semantics for "where" as in psDBUpdateRow().

If "where" is NULL, all rows in the table will be removed and regardless of the number of rows that were dropped, only 1 will be returned on success.

Returns:
The number of rows removed or a negative value on error
Parameters:
dbh  Database handle
tableName  Table name
where  Row match criteria

bool psDBDrop (  psDB *  dbh,
const char *  dbname
) 
 

Drops a database namespace.

Returns:
true on success
Parameters:
dbh  Database handle
dbname  Database namespace

bool psDBDropTable (  psDB *  dbh,
const char *  tableName
) 
 

Deletes a database table.

Returns:
true on success
Parameters:
dbh  Database handle
tableName  Table name

psMetadata* psDBDumpCols (  psDB *  dbh,
const char *  tableName
) 
 

Retrieves all columns from a table.

This function fetches all columns, as either a psVector or a psArray depending on whether or not the column is numeric, and return them in a psMetadata structure where psMetadataItem.name contains the column's name.

Returns:
A psMetadata containing either a psArrays or psVector per column
Parameters:
dbh  Database handle
tableName  Table name

psArray* psDBDumpRows (  psDB *  dbh,
const char *  tableName
) 
 

Retrieves all rows from a table.

This function fetches all rows as an psArray of psMetadata. The rows are in the same psMetadata format as used in psDBInsertOneRow() & psDBInsertRows().

Returns:
A psArray of psMetadata or NULL on failure
Parameters:
dbh  Database handle
tableName  Table name

psDB* psDBInit (  const char *  host,
const char *  user,
const char *  passwd,
const char *  dbname
) 
 

Opens a new database connection.

Returns:
A new psDB object if the database connection is successful or NULL on failure.
Parameters:
host  Database server hostname
user  Database username
passwd  Database password
dbname  Database namespace

bool psDBInsertOneRow (  psDB *  dbh,
const char *  tableName,
psMetadata *  row
) 
 

Insert a single row into a table.

This function inserts the data from "row" into "tableName".

The "row" specification uses the psMetadataItem name as the column name. The field values may be specified in any order. psMetadata types beyond PS_META_STR and PS_META_PRIMITIVE are not supported. If fields are specified in "row" that do not exist in "tableName", the insert will fail.

Returns:
true on success
Parameters:
dbh  Database handle
tableName  Table name
row  Row description

bool psDBInsertRows (  psDB *  dbh,
const char *  tableName,
psArray *  rowSet
) 
 

Insert a set of rows into a table.

This function inserts the data from "rowSet" into "tableName".

"rowSet" is a psArray of psMetadata containing row specifications identical to those used in psDBInsertOneRow().

Returns:
true on success
Parameters:
dbh  Database handle
tableName  Table name
rowSet  Set of rows to insert

psArray* psDBSelectColumn (  psDB *  dbh,
const char *  tableName,
const char *  col,
const psU64  limit
) 
 

Selects a column from a table.

This function generates and executes the SQL needed to select an entire column from a table or up to "limit" rows from it. If "limit" is 0, the entire range is returned.

Returns:
A psArray of strings or NULL on failure
Parameters:
dbh  Database handle
tableName  Table name
col  Column name
limit  Maximum number of elements to return

psVector* psDBSelectColumnNum (  psDB *  dbh,
const char *  tableName,
const char *  col,
psElemType  pType,
const psU64  limit
) 
 

Selects a column from a table and casts it to a given type.

This function generates and executes the SQL needed to select an entire column from a table or up to "limit" rows from it. If "limit" is 0, the entire range is returned. The data in the column is cast to to "pType".

Returns:
A psVector or NULL on failure
Parameters:
dbh  Database handle
tableName  Table name
col  Column name
pType  Resulting psVector type
limit  Maximum number of elements to return

psArray* psDBSelectRows (  psDB *  dbh,
const char *  tableName,
psMetadata *  where,
const psU64  limit
) 
 

Selects a set of rows from a table.

This function returns rows from the specified table which match the restrictions given by "where". The restrictions are specified as field / value pairs. The psMetadata collection "where" must consist of valid database fields. The selected rows are returned as a psArray of psMetadata values, one per row.

Currently, the "where" specification only supports the PS_META_STR type. The string value can be a SQL match pattern, e.g. "%foo%", or an empty string, e.g. "", to match NULL field values.

Returns:
A psArray of psMetadata or NULL on failure
Parameters:
dbh  Database handle
tableName  Table name
where  Row match criteria
limit  Maximum number of elements to return

psS64 psDBUpdateRows (  psDB *  dbh,
const char *  tableName,
psMetadata *  where,
psMetadata *  values
) 
 

Updates the field values, as specified, in a table.

This function updates the fields contained in "values" in the row(s) that have a field with the value indicated by "where". Where "where" is in the same format as used in psDBSelectRows().

The "values" specification uses the same format as the row specification used in psDBInsertOneRow(), etc.

Returns:
The number of rows modified or a negative value on error
Parameters:
dbh  Database handle
tableName  Table name
where  Row match criteria
values  new field values

Generated on Wed Jun 15 11:01:15 2005 for Pan-STARRS Foundation Library by  doxygen 1.4.1