Index: /trunk/archive/psdb/psDB.h =================================================================== --- /trunk/archive/psdb/psDB.h (revision 3229) +++ /trunk/archive/psdb/psDB.h (revision 3230) @@ -10,6 +10,6 @@ * @author Joshua Hoblitt * - * @version $Revision: 1.7 $ $Name: not supported by cvs2svn $ - * @date $Date: 2005-02-15 07:28:50 $ + * @version $Revision: 1.8 $ $Name: not supported by cvs2svn $ + * @date $Date: 2005-02-15 22:11:21 $ * * Copyright 2005 Joshua Hoblitt, University of Hawaii @@ -25,39 +25,234 @@ /// @{ +/** Database handle + * + * An opaque object representing a database connection. + * + */ typedef struct { MYSQL *mysql; ///< MySQL database handle } psDB; -psDB *psDBInit(const char *host, const char *user, const char *passwd, const char *dbname); - -void psDBCleanup(psDB *dbh); - -bool psDBCreate(psDB *dbh, const char *dbname); - -bool psDBChange(psDB *dbh, const char *dbname); - -bool psDBDrop(psDB *dbh, const char *dbname); - -bool psDBCreateTable(psDB *dbh, const char *tableName, psMetadata *md); - -bool psDBDropTable(psDB *dbh, const char *tableName); - -psArray *psDBSelectColumn(psDB *dbh, const char *tableName, const char *col, const psU64 limit); - -psVector *psDBSelectColumnNum(psDB *dbh, const char *tableName, const char *col, psElemType pType, const psU64 limit); - -psArray *psDBSelectRows(psDB *dbh, const char *tableName, psMetadata *where); - -bool psDBInsertOneRow(psDB *dbh, const char *tableName, psMetadata *row); - -bool psDBInsertRows(psDB *dbh, const char *tableName, psArray *rowSet); - -psArray *psDBDumpRows(psDB *dbh, const char *tableName); - -psMetadata *psDBDumpCols(psDB *dbh, const char *tableName); - -psS64 psDBUpdateRows(psDB *dbh, const char *tableName, psMetadata *where, psMetadata *values); - -psS64 psDBDeleteRows(psDB *dbh, const char *tableName, psMetadata *where); +/** Opens a new database connection + * + * @return A new psDB object if the database connection is successful or NULL on + * failure. + */ +psDB *psDBInit( + const char *host, ///< Database server hostname + const char *user, ///< Database username + const char *passwd, ///< Database password + const char *dbname ///< Database namespace +); + +/** Closes a database connection + */ +void psDBCleanup( + psDB *dbh ///< Database handle +); + +/** Creates a new database namespace + * + * @return true on success + */ +bool psDBCreate( + psDB *dbh, ///< Database handle + const char *dbname ///< New database namespace +); + +/** Changes the current database namespace + * + * @return true on success + */ +bool psDBChange( + psDB *dbh, ///< Database handle + const char *dbname ///< Database namespace +); + +/** Drops a database namespace + * + * @return true on success + */ +bool psDBDrop( + psDB *dbh, ///< Database handle + const char *dbname ///< Database namespace +); + +/** 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. + * + * @return true on success + */ +bool psDBCreateTable( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + psMetadata *md ///< Column names, types, and indexes +); + +/** Deletes a database table + * + * @return true on success +*/ +bool psDBDropTable( + psDB *dbh, ///< Database handle + const char *tableName ///< Table name +); + +/** 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. + * + * @return A psArray of strings or NULL on failure + */ +psArray *psDBSelectColumn( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + const char *col, ///< Column name + const psU64 limit ///< Maximum number of elements to return +); + +/** 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". + * + * @return A psVector or NULL on failure + */ +psVector *psDBSelectColumnNum( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + const char *col, ///< Column name + psElemType pType, ///< Resulting psVector type + const psU64 limit ///< Maximum number of elements to return +); + +/** 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. + * + * @return A psArray of psMetadata or NULL on failure + */ +psArray *psDBSelectRows( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + psMetadata *where ///< Row match criteria +); + +/** 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 maybe 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. + * + * @return true on success + */ +bool psDBInsertOneRow( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + psMetadata *row ///< Row description +); + +/** 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(). + * + * @return true on success + */ +bool psDBInsertRows( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + psArray *rowSet ///< Set of rows to insert +); + +/** 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(). + * + * @return A psArray of psMetadata or NULL on failure + */ +psArray *psDBDumpRows( + psDB *dbh, ///< Database handle + const char *tableName ///< Table name +); + +/** 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. + * + * @return A psMetadata containing either a psArrays or psVector per column + */ +psMetadata *psDBDumpCols( + psDB *dbh, ///< Database handle + const char *tableName ///< Table name +); + +/** 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. + * + * @return The number of rows modified or a negative value on error + */ +psS64 psDBUpdateRows( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + psMetadata *where, ///< Row match criteria + psMetadata *values ///< new field values +); + +/** 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. + * + * @return The number of rows removed or a negative value on error + */ +psS64 psDBDeleteRows( + psDB *dbh, ///< Database handle + const char *tableName, ///< Table name + psMetadata *where ///< Row match criteria +); /// @}