src/hg/inc/mdb.h 1.1

Index: src/hg/inc/mdb.h
===================================================================
RCS file: src/hg/inc/mdb.h
diff -N src/hg/inc/mdb.h
--- /dev/null	1 Jan 1970 00:00:00 -0000
+++ src/hg/inc/mdb.h	13 Apr 2010 19:49:20 -0000	1.1
@@ -0,0 +1,293 @@
+/* mdb.h was originally generated by the autoSql program, which also
+ * generated mdb.c and mdb.sql.  This header links the database and
+ * the RAM representation of objects. */
+
+#ifndef MDB_H
+#define MDB_H
+
+#include "jksql.h"
+#define MDB_NUM_COLS 4
+
+struct mdb
+/* This contains metadata for a table, file or other predeclared object type. */
+    {
+    struct mdb *next;  /* Next in singly linked list. */
+    char *obj;	/* Object name or ID. */
+    char *var;	/* Metadata variable name. */
+    char *varType;	/* txt | binary */
+    char *val;	/* Metadata value. */
+    };
+
+void mdbStaticLoad(char **row, struct mdb *ret);
+/* Load a row from mdb table into ret.  The contents of ret will
+ * be replaced at the next call to this function. */
+
+struct mdb *mdbLoadByQuery(struct sqlConnection *conn, char *query);
+/* Load all mdb from table that satisfy the query given.
+ * Where query is of the form 'select * from example where something=something'
+ * or 'select example.* from example, anotherTable where example.something =
+ * anotherTable.something'.
+ * Dispose of this with mdbFreeList(). */
+
+void mdbSaveToDb(struct sqlConnection *conn, struct mdb *el, char *tableName, int updateSize);
+/* Save mdb as a row to the table specified by tableName.
+ * As blob fields may be arbitrary size updateSize specifies the approx size
+ * of a string that would contain the entire query. Arrays of native types are
+ * converted to comma separated strings and loaded as such, User defined types are
+ * inserted as NULL. Note that strings must be escaped to allow insertion into the database.
+ * For example "autosql's features include" --> "autosql\'s features include"
+ * If worried about this use mdbSaveToDbEscaped() */
+
+void mdbSaveToDbEscaped(struct sqlConnection *conn, struct mdb *el, char *tableName, int updateSize);
+/* Save mdb as a row to the table specified by tableName.
+ * As blob fields may be arbitrary size updateSize specifies the approx size.
+ * of a string that would contain the entire query. Automatically
+ * escapes all simple strings (not arrays of string) but may be slower than mdbSaveToDb().
+ * For example automatically copies and converts:
+ * "autosql's features include" --> "autosql\'s features include"
+ * before inserting into database. */
+
+struct mdb *mdbLoad(char **row);
+/* Load a mdb from row fetched with select * from mdb
+ * from database.  Dispose of this with mdbFree(). */
+
+struct mdb *mdbLoadAll(char *fileName);
+/* Load all mdb from whitespace-separated file.
+ * Dispose of this with mdbFreeList(). */
+
+struct mdb *mdbLoadAllByChar(char *fileName, char chopper);
+/* Load all mdb from chopper separated file.
+ * Dispose of this with mdbFreeList(). */
+
+#define mdbLoadAllByTab(a) mdbLoadAllByChar(a, '\t');
+/* Load all mdb from tab separated file.
+ * Dispose of this with mdbFreeList(). */
+
+struct mdb *mdbCommaIn(char **pS, struct mdb *ret);
+/* Create a mdb out of a comma separated string.
+ * This will fill in ret if non-null, otherwise will
+ * return a new mdb */
+
+void mdbFree(struct mdb **pEl);
+/* Free a single dynamically allocated mdb such as created
+ * with mdbLoad(). */
+
+void mdbFreeList(struct mdb **pList);
+/* Free a list of dynamically allocated mdb's */
+
+void mdbOutput(struct mdb *el, FILE *f, char sep, char lastSep);
+/* Print out mdb.  Separate fields with sep. Follow last field with lastSep. */
+
+#define mdbTabOut(el,f) mdbOutput(el,f,'\t','\n');
+/* Print out mdb as a line in a tab-separated file. */
+
+#define mdbCommaOut(el,f) mdbOutput(el,f,',',',');
+/* Print out mdb as a comma separated list including final comma. */
+
+void mdbJsonOutput(struct mdb *el, FILE *f);
+/* Print out mdb in JSON format. */
+
+/* -------------------------------- End autoSql Generated Code -------------------------------- */
+
+#include "trackDb.h"
+
+#define MDB_DEFAULT_NAME "mdb"
+
+// The mdb holds metadata primarily for tables.
+//   Many types of objects could be supported, though currently files are the only other type.
+// It is easy to imagine using the current mdb to support hierarchical trees of metadata.
+// For example a composite type object called "myComposte" could have metadata that is valid for
+// all tables that have the var=composite val=myComposte metadata defined.
+//
+// There are 2 ways to look at the metadata: By Obj: obj->[var=val] and By Var: var->[val->[obj]].
+// By Obj: an object has many var/val pairs but only one val for each unique var.  Querying by
+//         object creates a single (2 level) one to many structure.
+// By Var: a variable has many possible values and each value may be defined for more than one object.
+//         Therefore, querying by var results in a (3 level) one to many to many structure.
+
+enum mdbVarType
+// metadata Variavble are only certain declared types
+    {
+    vtTxt     =0,  // Txt is default
+    vtBinary  =1,  // Could support binary blobs
+    vtUnknown =99  // Not determined.
+    };
+
+struct mdbVar
+// The metadata var=val construct. This is contained by mdbObj
+    {
+    struct mdbVar* next;     // Next in singly linked list of variables
+    char *var;               // Metadata variable name.
+    enum mdbVarType varType; // txt | binary
+    char *val;               // Metadata value.
+    };
+
+struct mdbObj
+// The standard container of a single object's metadata.
+// Also: when searching metadata obj->var->val this is the top struct.
+    {
+    struct mdbObj* next;     // Next in singly linked list of objects
+    char *obj;               // Object name or ID
+    boolean deleteThis;      // Used when loading formatted file which may contain delete requests
+    struct mdbVar* vars;     // if NOT NULL: list of variables belonging to this object
+    struct hash* varHash;    // if NOT NULL: variables are also hashed! (var str to mdbVar struct)
+    };
+
+struct mdbLeafObj
+// When searching var->val->obj this is the bottom-level obj struct.
+    {
+    struct mdbLeafObj* next; // Next in singly linked list of variables
+    char *obj;               // Object name or ID
+    };
+
+struct mdbLimbVal
+// When searching var->val->obj this is the mid-level val->obj struct.
+    {
+    struct mdbLimbVal* next; // Next in singly linked list of variables
+    char *val;               // Metadata value.
+    struct mdbLeafObj* objs; // if NOT NULL: list of Objects which have this variable
+    struct hash* objHash;    // if NOT NULL: hash of objects  (val str to leafObj struct)
+    };
+
+struct mdbByVar
+// When searching metadata var->val->object this is the top struct
+    {
+    struct mdbByVar* next;   // Next in singly linked list of variables
+    char *var;               // Metadata variable name.
+    enum mdbVarType varType; // txt | binary
+    boolean notEqual;        // For querying only
+    struct mdbLimbVal* vals; // list of values associated with this var
+    struct hash* valHash;    // if NOT NULL: hash of vals  (val str to limbVal struct)
+    };
+
+// -------------- Enum to Strings --------------
+enum mdbVarType mdbVarTypeStringToEnum(char *varType);
+// Convert metadata varType string to enum
+
+char *mdbVarTypeEnumToString(enum mdbVarType varType);
+// Convert metadata varType enum string
+
+// ------ Parsing lines ------
+struct mdbObj *metadataLineParse(char *line);
+/* Parses a single formatted metadata line into mdbObj for updates or queries. */
+
+struct mdbByVar *mdbByVarsLineParse(char *line);
+/* Parses a line of "var1=val1 var2=val2 into a mdbByVar object for queries. */
+
+
+// ------ Loading from args, hashes ------
+struct mdbObj *mdbObjCreate(char *obj,char *var, char *varType,char *val);
+/* Creates a singular mdbObj query object based on obj and all other optional params. */
+
+struct mdbByVar *mdbByVarCreate(char *var, char *varType,char *val);
+/* Creates a singular var=val pair struct for metadata queries. */
+
+struct mdbObj *mdbObjsLoadFromHashes(struct hash *objsHash);
+// Load all mdbObjs from a file containing metadata formatted lines
+
+
+// ------ Loading from files ------
+struct mdbObj *mdbObjsLoadFromFormattedFile(char *fileName,boolean *validated);
+// Load all mdbObjs from a file containing metadata formatted lines
+// If requested, will determine if a magic number at the end of the file matches contents
+
+struct mdbObj *mdbObjsLoadFromRAFile(char *fileName,boolean *validated);
+// Load all mdbObjs from a file containing RA formatted 'metaObjects'
+// If requested, will determine if a magic number at the end of the file matches contents
+
+
+
+// ------ Table name and creation ------
+void mdbReCreate(struct sqlConnection *conn,char *tblName,boolean testOnly);
+// Creates ore Recreates the named mdb.
+
+char*mdbTableName(struct sqlConnection *conn,boolean mySandBox);
+// returns the mdb table name or NULL if conn supplied but the table doesn't exist
+
+
+// -------------- Updating the DB --------------
+int mdbObjsSetToDb(struct sqlConnection *conn,char *tableName,struct mdbObj *mdbObjs,boolean replace,boolean testOnly);
+// Adds or updates metadata obj/var pairs into the named table.  Returns total rows affected
+
+
+// ------------------ Querys -------------------
+struct mdbObj *mdbObjQuery(struct sqlConnection *conn,char *table,struct mdbObj *mdbObj);
+// Query the metadata table by obj and optional vars and vals in mdbObj struct.  If mdbObj is NULL query all.
+// Returns new mdbObj struct fully populated and sorted in obj,var order.
+#define mdbObjsQueryAll(conn,table) mdbObjQuery((conn),(table),NULL)
+
+struct mdbObj *mdbObjQueryByObj(struct sqlConnection *conn,char *table,char *obj,char *var);
+// Query a single metadata object and optional var from a table (default mdb).
+
+struct mdbByVar *mdbByVarsQuery(struct sqlConnection *conn,char *table,struct mdbByVar *mdbByVars);
+// Query the metadata table by one or more var=val pairs to find the distinct set of objs that satisfy ANY conditions.
+// Returns new mdbByVar struct fully populated and sorted in var,val,obj order.
+#define mdbByVarsQueryAll(conn,table) mdbByVarsQuery((conn),(table),NULL)
+
+struct mdbByVar *mdbByVarQueryByVar(struct sqlConnection *conn,char *table,char *varName,char *val);
+// Query a single metadata variable and optional val from a table (default mdb) for searching val->obj.
+
+struct mdbObj *mdbObjsQueryByVars(struct sqlConnection *conn,char *table,struct mdbByVar *mdbByVars);
+// Query the metadata table by one or more var=val pairs to find the distinct set of objs that satisfy ALL conditions.
+// Returns new mdbObj struct fully populated and sorted in obj,var order.
+
+
+// ----------- Printing and Counting -----------
+void mdbObjPrint(struct mdbObj *mdbObjs,boolean raStyle);
+// prints objs and var=val pairs as formatted metadata lines or ra style
+
+void mdbByVarPrint(struct mdbByVar *mdbByVars,boolean raStyle);
+// prints var=val pairs and objs that go with them single lines or ra style
+
+int mdbObjCount(struct mdbObj *mdbObjs, boolean objs);
+// returns the count of vars belonging to this obj or objs;
+
+int mdbByVarCount(struct mdbByVar *mdbByVars,boolean vars, boolean vals);
+// returns the count of objs belonging to this set of vars;
+
+
+// ----------------- Utilities -----------------
+char *mdbObjFindValue(struct mdbObj *mdbObj, char *var);
+// Finds the val associated with the var or retruns NULL
+
+boolean mdbObjContains(struct mdbObj *mdbObj, char *var, char *val);
+// Returns TRUE if object contains var, val or both
+
+boolean mdbByVarContains(struct mdbByVar *mdbByVar, char *val, char *obj);
+// Returns TRUE if var contains val, obj or both
+
+void mdbObjReorderVars(struct mdbObj *mdbObjs, char *vars,boolean back);
+// Reorders vars list based upon list of vars "cell antibody treatment".  Send to front or back.
+
+void mdbObjRemoveVars(struct mdbObj *mdbObjs, char *vars);
+// Prunes list of vars for an object, freeing the memory.  Doesn't touch DB.
+
+void mdbObjSwapVars(struct mdbObj *mdbObjs, char *vars,boolean deleteThis);
+// Replaces objs' vars with var=vap pairs provided, preparing for DB update.
+
+void mdbObjTransformToUpdate(struct mdbObj *mdbObjs, char *var, char *varType,char *val,boolean deleteThis);
+// Turns one or more mdbObjs into the stucture needed to add/update or delete.
+
+struct mdbObj *mdbObjClone(const struct mdbObj *mdbObj);
+// Clones a single mdbObj, including hash and maintining order
+
+
+// --------------- Free at last ----------------
+void mdbObjsFree(struct mdbObj **mdbObjsPtr);
+// Frees one or more metadata objects and any contained mdbVars.  Will free any hashes as well.
+
+void mdbByVarsFree(struct mdbByVar **mdbByVarsPtr);
+// Frees one or more metadata vars and any contained vals and objs.  Will free any hashes as well.
+
+
+// ----------------- CGI specific routines for use with tdb -----------------
+const struct mdbObj *metadataForTable(char *db,struct trackDb *tdb,char *table);
+// Returns the metadata for a table.  NEVER FREE THIS STRUCT!
+// This is the main routine for CGIs to access metadata
+
+const char *metadataFindValue(struct trackDb *tdb, char *var);
+// Finds the val associated with the var or retruns NULL
+
+
+#endif /* MDB_H */
+