****************************************************************************** * Function: dbutil_table_new * Purpose: Creates a new instance of a dbtable_t type, giving it the name * Purpose: supplied in the tablename argument. The tablename should * Purpose: correspond to a database table name. * Purpose: * Arguments: char *tablename - Name of the table in the database system. * ReturnType: dbtable_t * * Returns: On success, returns the newly allocated dbtable structure. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** dbtable_t * dbutil_table_new(char *tablename); ****************************************************************************** * Function: dbutil_table_free * Purpose: Frees the memory pointed to by the dbtable argument. This * Purpose: function should be called when the structure is no longer * Purpose: needed. * Purpose: * Arguments: dbtable_t *dbtable - Pointer to the structure to be freed. * ReturnType: void ****************************************************************************** void dbutil_table_free(dbtable_t *dbtable); ****************************************************************************** * Function: dbutil_table_add_field * Purpose: Add the field pointed to by the dbfield argument to the * Purpose: dbtable specified by the dbtable pointer argument. * Purpose: * Purpose: * Arguments: dbtable_t *dbtable - The dbtable to add the dbfield to. * dbfield_t *dbfield - The dbfield to be added to the dbtable. * ReturnType: gint * Returns: On success, returns 0 on success. * Returns: On error, returns -2 if field already exists in the table. ****************************************************************************** gint dbutil_table_add_field(dbtable_t *dbtable, dbfield_t *dbfield); ****************************************************************************** * Function: dbutil_table_get_primary_field * Purpose: Returns a pointer to the dbfield which has DBF_PRIMARYKEY set * Purpose: in it's flags. The dbtable argument pointes to the dbtable * Purpose: to search for the primary key field in. * Purpose: * Arguments: dbtable_t *dbtable - The dbtable to search for a primary key in. * ReturnType: dbfield_t * * Returns: On success, returns a pointer to the primary key dbfield. * Returns: On error, returns NULL if no primary key field was found. ****************************************************************************** dbfield_t * dbutil_table_get_primary_field(dbtable_t *dbtable); ****************************************************************************** * Function: dbutil_table_get_field * Purpose: Search a dbtable for a field with the given name and returns * Purpose: a pointer to the dbfield structure if found. * Purpose: * Purpose: * Arguments: dbtable_t *dbtable - The dbtable to search for the dbfield in. * gchar *fieldname - The name of the field to find in the dbtable. * ReturnType: dbfield_t * * Returns: On success, returns a pointer to the dbfield structure. * Returns: On error, returns NULL if the field was not found. ****************************************************************************** dbfield_t * dbutil_table_get_field(dbtable_t *dbtable, gchar *fieldname); ****************************************************************************** * Function: dbutil_table_required_fields_filled * Purpose: For the given dbtable, checks for the presence of data in all * Purpose: fields with the DBF_REQUIRED flag set. * Purpose: * Purpose: * Arguments: dbtable_t * dbtable - * ReturnType: gint * Returns: 1 if all required fields contain data. * Returns: 0 if any required fields contain no data. ****************************************************************************** gint dbutil_table_required_fields_filled(dbtable_t * dbtable); ****************************************************************************** * Function: dbutil_table_set_flags * Purpose: ORs the given flags with the flags in the given dbtable. * Purpose: * Purpose: * Purpose: * Arguments: dbtable_t *dbtable - the dbtable to set the flags for. * gint flags - An ORed list of DBT_* flags to set in the dbtable. * ReturnType: void ****************************************************************************** void dbutil_table_set_flags(dbtable_t *dbtable, gint flags); ****************************************************************************** * Function: dbutil_table_clear_flags * Purpose: Clears the given list of flags for the dbtable specified. * Purpose: * Purpose: * Purpose: * Arguments: dbtable_t *dbtable - The dbtable to clear the flags in. * gint flags - An ORed list of flags to clear in the dbtable. * ReturnType: void ****************************************************************************** void dbutil_table_clear_flags(dbtable_t *dbtable, gint flags); ****************************************************************************** * Function: dbutil_table_set_widget * Purpose: Sets the UI widget to be associated with the given dbtable. * Purpose: This function sets the DBT_MULTIROW flag in the dbtable. This * Purpose: function is normally called with a UI widget which may display * Purpose: multiple rows from the database table it is associated with. * Arguments: dbtable_t *dbtable - The dbtable to set the UI widget for. * gpointer widget - The UI widget to associate with the dbtable. * ReturnType: void ****************************************************************************** void dbutil_table_set_widget(dbtable_t *dbtable, gpointer widget); ****************************************************************************** * Function: dbutil_tableset_new * Purpose: Allocates a new tableset structure. * Purpose: * Purpose: * Purpose: * Arguments: char *tablesetname - The name for the new tableset. * ReturnType: dbtableset_t * * Returns: On success, returns a pointer to the newly allocated tableset. * Returns: On error, returns NULL if unable to allocated enough memory. ****************************************************************************** dbtableset_t * dbutil_tableset_new(gchar *tablesetname); ****************************************************************************** * Function: dbutil_tableset_free * Purpose: Frees the memory used by the tableset when the structure is no * Purpose: longer needed. It does NOT free the dbtable structures which * Purpose: are referenced in the tableset. * Purpose: * Arguments: dbtableset_t *dbtableset - Pointer to the dbtableset to free. * ReturnType: void ****************************************************************************** void dbutil_tableset_free(dbtableset_t *dbtableset); ****************************************************************************** * Function: dbutil_tableset_add_table * Purpose: Adds a reference to the given table in the tableset. The table * Purpose: reference will NOT be added if the table is already referenced * Purpose: in the tableset. * Purpose: * Arguments: dbtableset_t *dbtableset - The tableset to add the reference to. * dbtable_t *dbtable - The table to be added to the tableset. * ReturnType: gint * Returns: On success, returns 0 * Returns: On error, return -1 if the table reference could not be added. ****************************************************************************** gint dbutil_tableset_add_table(dbtableset_t *dbtableset, dbtable_t *dbtable); ****************************************************************************** * Function: dbutil_tableset_get_table * Purpose: Search a tableset for the given tablename and, if found, * Purpose: returns a pointer to the dbtable structure. * Purpose: * Purpose: * Arguments: dbtableset_t *dbtableset - The tableset to search. * gchar *tablename - The name of the table to search for. * ReturnType: dbtable_t * * Returns: On success, returns a pointer to the found dbtable structure. * Returns: On error, returns NULL if the table was not found. ****************************************************************************** dbtable_t * dbutil_tableset_get_table(dbtableset_t *dbtableset, gchar *tablename); ****************************************************************************** * Function: dbutil_field_new * Purpose: Allocates a new dbfield structure. The field argument should * Purpose: correspond to the name of a database field. * Purpose: * Purpose: * Arguments: void *widget - The UI widget to associate with this dbfield. * gchar *field - The name for the new dbfield. * ReturnType: dbfield_t * * Returns: On success, returns a pointer to the newly allocated structure. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** dbfield_t * dbutil_field_new(void *widget, gchar *field); ****************************************************************************** * Function: dbutil_field_free * Purpose: Frees the memory for the given dbfield when the structure is * Purpose: no longer needed. * Purpose: * Purpose: * Arguments: dbfield_t *dbfield - A pointer to the dbfield to free. * ReturnType: void ****************************************************************************** void dbutil_field_free(dbfield_t *dbfield); ****************************************************************************** * Function: dbutil_field_set_data * Purpose: Sets the data in the given dbfield. This function sets the * Purpose: DBF_HASDATA flag in the dbfield. * Purpose: * Purpose: * Arguments: dbfield_t *dbfield - The dbfield to set the data in. * gpointer data - The data to be set in the dbfield. * ReturnType: void ****************************************************************************** void dbutil_field_set_data(dbfield_t *dbfield, gpointer data); ****************************************************************************** * Function: dbutil_field_clear_data * Purpose: Clears the data in the given dbfield. This function clears the * Purpose: DBF_HASDATA flag in the dbfield. * Purpose: * Purpose: * Arguments: dbfield_t *dbfield - The field to clear data from. * ReturnType: void ****************************************************************************** void dbutil_field_clear_data(dbfield_t *dbfield); ****************************************************************************** * Function: dbutil_field_set_primary * Purpose: Set the DBF_PRIMARYKEY flag for a given dbfield. * Purpose: * Purpose: * Purpose: * Arguments: dbfield_t *dbfield - The dbfield to set as the primary key. * ReturnType: void ****************************************************************************** void dbutil_field_set_primary(dbfield_t *dbfield); ****************************************************************************** * Function: dbutil_field_set_flags * Purpose: Set the given flags for a dbfield. * Purpose: * Purpose: * Purpose: * Arguments: dbfield_t *dbfield - The dbfield to set the flags for. * gint flags - An ORed list of flags to set in the dbfield. * ReturnType: void ****************************************************************************** void dbutil_field_set_flags(dbfield_t *dbfield, gint flags); ****************************************************************************** * Function: dbutil_field_clear_flags * Purpose: Clears the given flags in a dbfield. * Purpose: * Purpose: * Purpose: * Arguments: dbfield_t *dbfield - The dbfield to clear the flags in. * gint flags - An ORed list of flags to clear in the dbfield. * ReturnType: void ****************************************************************************** void dbutil_field_clear_flags(dbfield_t *dbfield, gint flags); ****************************************************************************** * Function: dbutil_relation_new * Purpose: Allocate a new relation structure. The function requires a * Purpose: pointer to the primary and foreign fields for the relation. * Purpose: * Purpose: * Arguments: gchar *name - The name for the new relationship. * dbfield_t *primary - Pointer to the relation primary dbfield. * dbfield_t *foreign - Pointer to the relation foreign dbfield. * ReturnType: dbrelation_t * * Returns: On success, returns a pointer to the newly allocated structure. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** dbrelation_t * dbutil_relation_new(gchar *name, dbfield_t *primary, dbfield_t *foreign); ****************************************************************************** * Function: dbutil_relation_free * Purpose: Frees the memory for a given dbrelation when the structure is * Purpose: no longer needed. The primary and foreign dbfield structures * Purpose: are NOT freed by this function. * Purpose: * Arguments: dbrelation_t *dbrelation - Pointer to the structure to free. * ReturnType: void ****************************************************************************** void dbutil_relation_free(dbrelation_t *dbrelation); ****************************************************************************** * Function: dbutil_relation_set_data * Purpose: Set the data member in a given dbrelation structure. * Purpose: * Purpose: * Purpose: * Arguments: dbrelation_t *dbrelation - The dbrelation to set the data in. * gpointer data - The data to set in the dbrelation. * ReturnType: void ****************************************************************************** void dbutil_relation_set_data(dbrelation_t *dbrelation, gpointer data); ****************************************************************************** * Function: dbutil_relationset_new * Purpose: Allocate a new dbrelationset structure with a given name and * Purpose: associated with a given tableset. * Purpose: * Purpose: * Arguments: gchar *relationsetname - The name for the new relationset. * dbtableset_t *tableset - The tableset for the new relationset. * ReturnType: dbrelationset_t * * Returns: On success, returns a pointer to the newly allocated structure. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** dbrelationset_t * dbutil_relationset_new(gchar *relationsetname, dbtableset_t *tableset); ****************************************************************************** * Function: dbutil_relationset_free * Purpose: Frees the given dbrelationset when the structure is no longer * Purpose: needed. This function does NOT free the tableset it is * Purpose: associated with. * Purpose: * Arguments: dbrelationset_t *dbrelationset - The relationset to free. * ReturnType: void ****************************************************************************** void dbutil_relationset_free(dbrelationset_t *dbrelationset); ****************************************************************************** * Function: dbutil_relationset_full_free * Purpose: Frees the given dbrelationset when the structure is no longer * Purpose: needed. This function frees all relations, tables, fields and * Purpose: the tableset associated with this relationset. * Purpose: * Arguments: dbrelationset_t *dbrelationset - The relationset to free. * ReturnType: void ****************************************************************************** void dbutil_relationset_full_free(dbrelationset_t *dbrelationset); ****************************************************************************** * Function: dbutil_relationset_add_relation * Purpose: Add the given relation to a relationset. * Purpose: * Purpose: * Purpose: * Arguments: dbrelationset_t *dbrelationset - The relationset to add the * Arguments: relation to. * dbrelation_t *dbrelation - The relation to be added. * ReturnType: gint * Returns: On success, returns 0 if the relation was added. * Returns: On error, returns -2 if the relation already exists in the * Returns: relationset. ****************************************************************************** gint dbutil_relationset_add_relation(dbrelationset_t *dbrelationset, dbrelation_t *dbrelation); ****************************************************************************** * Function: dbutil_relationset_select * Purpose: Create a SELECT SQL statement from the given relationset. The * Purpose: data used to create the SQL statement is taken from the * Purpose: children structures in the dbrelationset structure. The given * Purpose: primarytable will be used as the anchor for the SQL statement * Purpose: and must exist in the tableset associated with the relationset. * Purpose: If userelations is set to 0, the SQL will only use constraints * Purpose: from the primarytable. If set to 1, the SQL will use all * Purpose: constraints contained in the relations and tables associated * Purpose: with this relationset. * Arguments: dbrelationset_t *relationset - The relationset to create the * Arguments: SQL statement from. * gchar *primarytable - The table name used to anchor the SQL. * gint userelations - Set to 1 to use relation constraints. * ReturnType: GString * * Returns: On success, returns a newly allocated SQL statement string. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** GString * dbutil_relationset_select(dbrelationset_t *relationset, gchar *primarytable, gint userelations); ****************************************************************************** * Function: dbutil_relationset_insert * Purpose: Create an INSERT SQL statement from the given relationset. The * Purpose: data used to create the SQL statement is taken from the * Purpose: children structures in the dbrelationset structure. The given * Purpose: primarytable will be used as the anchor for the SQL statement * Purpose: and must exist in the tableset associated with the relationset. * Purpose: * Arguments: dbrelationset_t *relationset - The relationset to create the * Arguments: SQL statement from. * gchar *primarytable - The table name used to anchor the SQL. * ReturnType: GString * * Returns: On success, returns a newly allocated SQL statement string. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** GString * dbutil_relationset_insert(dbrelationset_t *relationset, gchar *primarytable); ****************************************************************************** * Function: dbutil_relationset_update * Purpose: Create an UPDATE SQL statement from the given relationset. The * Purpose: data used to create the SQL statement is taken from the * Purpose: children structures in the dbrelationset structure. The given * Purpose: primarytable will be used as the anchor for the SQL statement * Purpose: and must exist in the tableset associated with the relationset. * Purpose: * Arguments: dbrelationset_t *relationset - The relationset to create the * Arguments: SQL statement from. * gchar *primarytable - The table name used to anchor the SQL. * ReturnType: GString * * Returns: On success, returns a newly allocated SQL statement string. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** GString * dbutil_relationset_update(dbrelationset_t *relationset, gchar *primarytable); ****************************************************************************** * Function: dbutil_relationset_delete * Purpose: Create a DELETE SQL statement from the given relationset. The * Purpose: data used to create the SQL statement is taken from the * Purpose: children structures in the dbrelationset structure. The given * Purpose: primarytable will be used as the anchor for the SQL statement * Purpose: and must exist in the tableset associated with the relationset. * Purpose: * Arguments: dbrelationset_t *relationset - The relationset to create the * Arguments: SQL statement from. * gchar *primarytable - The table name used to anchor the SQL. * ReturnType: GString * * Returns: On success, returns a newly allocated SQL statement string. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** GString * dbutil_relationset_delete(dbrelationset_t *relationset, gchar *primarytable); ****************************************************************************** * Function: dbutil_relationset_select_free * Purpose: Frees a relselect structure when it is no longer needed. * Purpose: * Purpose: * Purpose: * Arguments: relselect_t *relselect - The relselect structure to free. * ReturnType: void ****************************************************************************** void dbutil_relationset_select_free(relselect_t *relselect); ****************************************************************************** * Function: dbutil_browser_new * Purpose: Allocate a new dbbrowser structure associated with the given * Purpose: dbrelationset and having primarytable set as the anchor table. * Purpose: * Purpose: * Arguments: gchar *browsername - Name for the newly allocated dbbrowser. * dbrelationset_t *relationset - The relationset to create the * SQL statement from. * gchar *primarytable - The table name used to anchor the SQL. * ReturnType: dbbrowser_t * * Returns: On success, returns a newly allocated dbbrowser structure. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** dbbrowser_t * dbutil_browser_new(gchar *browsername, dbrelationset_t *dbrelationset, gchar *primarytable); ****************************************************************************** * Function: dbutil_browser_free * Purpose: Frees the memory allocated for a dbbrowser structure when no * Purpose: longer needed. * Purpose: * Purpose: * Arguments: dbbrowser_t *dbbrowser - Pointer to the dbbrowser to free. * ReturnType: void ****************************************************************************** void dbutil_browser_free(dbbrowser_t *dbbrowser); ****************************************************************************** * Function: dbutil_browser_add_field * Purpose: Add the given dbfield to a dbbrowser. The dbfield must be part * Purpose: of one of the dbtables in the dbtableset of the dbrelationset * Purpose: that is associated with the dbbrowser. * Purpose: * Arguments: dbbrowser_t *dbbrowser - The dbbrowser to add the dbfield to. * dbfield_t *dbfield - The dbfield to be added to the dbbrowser. * ReturnType: gint * Returns: On success, returns 0. * Returns: On error, returns -2 if the dbfield does not belong to a table * Returns: in the dbbrowser's tableset. ****************************************************************************** gint dbutil_browser_add_field(dbbrowser_t *dbbrowser, dbfield_t *dbfield); ****************************************************************************** * Function: dbutil_browser_get_primary_field_offset * Purpose: Returns the 0-indexed offset of the primary field from the * Purpose: dbbrowser's list of fields. The primary field is the primary * Purpose: key from the dbtable set as the primarytable for the dbbrowser. * Purpose: * Arguments: dbbrowser_t *dbbrowser - The dbbrowser to find the dbfield in. * ReturnType: gint * Returns: On success, returns the 0-indexed dbfield offset. * Returns: On error, returns -2 if the primary table has no primary key. * Returns: returns -3 if the primary field is not in the * Returns: dbbrowser's field list. ****************************************************************************** gint dbutil_browser_get_primary_field_offset(dbbrowser_t *dbbrowser); ****************************************************************************** * Function: dbutil_browser_select * Purpose: Create a SELECT SQL statement for the given dbbrowser. The * Purpose: data used to create the SQL statement is taken from the * Purpose: children structures in the dbrelationset structure associated * Purpose: with the dbbrowser. The primary table assigned to the dbbrowser * Purpose: will be used as the anchor for the SQL statement. * Purpose: * Arguments: dbbrowser_t *dbbrowser - The dbbrowser to generate the SQL for. * ReturnType: GString * * Returns: On success, returns a newly allocated SQL statement string. * Returns: On error, returns NULL if unable to allocate enough memory. ****************************************************************************** GString * dbutil_browser_select(dbbrowser_t *dbbrowser);