src/hg/inc/metaTbl.h 1.1
1.1 2010/03/18 01:48:53 tdreszer
Finally making progress on a metadata table.
Index: src/hg/inc/metaTbl.h
===================================================================
RCS file: src/hg/inc/metaTbl.h
diff -N src/hg/inc/metaTbl.h
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ src/hg/inc/metaTbl.h 18 Mar 2010 01:48:53 -0000 1.1
@@ -0,0 +1,194 @@
+/* metaTbl.h was originally generated by the autoSql program, which also
+ * generated metaTbl.c and metaTbl.sql. This header links the database and
+ * the RAM representation of objects. */
+
+#ifndef METATBL_H
+#define METATBL_H
+
+#include "jksql.h"
+#define METATBL_NUM_COLS 5
+
+struct metaTbl
+/* This contains metadata for a table, file or other predeclared object type. */
+ {
+ struct metaTbl *next; // Next in singly linked list.
+ char *objName; // Object name or ID.
+ char *objType; // table | file
+ char *var; // Metadata variable name.
+ char *varType; // txt | binary
+ char *val; // Metadata value.
+ };
+
+void metaTblStaticLoad(char **row, struct metaTbl *ret);
+/* Load a row from metaTbl table into ret. The contents of ret will
+ * be replaced at the next call to this function. */
+
+struct metaTbl *metaTblLoadByQuery(struct sqlConnection *conn, char *query);
+/* Load all metaTbl 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 metaTblFreeList(). */
+
+void metaTblSaveToDb(struct sqlConnection *conn, struct metaTbl *el, char *tableName, int updateSize);
+/* Save metaTbl 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 metaTblSaveToDbEscaped() */
+
+void metaTblSaveToDbEscaped(struct sqlConnection *conn, struct metaTbl *el, char *tableName, int updateSize);
+/* Save metaTbl 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 metaTblSaveToDb().
+ * For example automatically copies and converts:
+ * "autosql's features include" --> "autosql\'s features include"
+ * before inserting into database. */
+
+struct metaTbl *metaTblLoad(char **row);
+/* Load a metaTbl from row fetched with select * from metaTbl
+ * from database. Dispose of this with metaTblFree(). */
+
+struct metaTbl *metaTblLoadAll(char *fileName);
+/* Load all metaTbl from whitespace-separated file.
+ * Dispose of this with metaTblFreeList(). */
+
+struct metaTbl *metaTblLoadAllByChar(char *fileName, char chopper);
+/* Load all metaTbl from chopper separated file.
+ * Dispose of this with metaTblFreeList(). */
+
+#define metaTblLoadAllByTab(a) metaTblLoadAllByChar(a, '\t');
+/* Load all metaTbl from tab separated file.
+ * Dispose of this with metaTblFreeList(). */
+
+struct metaTbl *metaTblCommaIn(char **pS, struct metaTbl *ret);
+/* Create a metaTbl out of a comma separated string.
+ * This will fill in ret if non-null, otherwise will
+ * return a new metaTbl */
+
+void metaTblFree(struct metaTbl **pEl);
+/* Free a single dynamically allocated metaTbl such as created
+ * with metaTblLoad(). */
+
+void metaTblFreeList(struct metaTbl **pList);
+/* Free a list of dynamically allocated metaTbl's */
+
+void metaTblOutput(struct metaTbl *el, FILE *f, char sep, char lastSep);
+/* Print out metaTbl. Separate fields with sep. Follow last field with lastSep. */
+
+#define metaTblTabOut(el,f) metaTblOutput(el,f,'\t','\n');
+/* Print out metaTbl as a line in a tab-separated file. */
+
+#define metaTblCommaOut(el,f) metaTblOutput(el,f,',',',');
+/* Print out metaTbl as a comma separated list including final comma. */
+
+/* -------------------------------- End autoSql Generated Code -------------------------------- */
+
+enum metaObjType
+// metadata Obects are only certain declared types
+ {
+ otUnknown=0, // Unknown type
+ otTable =1, // Table is default
+ otFile =2 // Some are files
+ };
+
+enum metaVarType
+// metadata Variavble are only certain declared types
+ {
+ vtUnknown=0, // Unknown type
+ vtTxt =1, // Txt is default
+ vtBinary =2 // Could support binary blobs
+ };
+
+struct metaVar
+// The metadata var=val construct. This is contained by metaObj
+ {
+ struct metaVar* next; // Next in singly linked list of variables
+ char *var; // Metadata variable name.
+ enum metaVarType varType; // txt | binary
+ char *val; // Metadata value.
+ };
+
+struct metaObj
+// The standard container of a single object's metadata.
+// Also: when searching metadata obj->var->val this is the top struct.
+ {
+ struct metaObj* next; // Next in singly linked list of objects
+ char *objName; // Object name or ID
+ enum metaObjType objType; // table | file
+ boolean deleteThis; // Used when loading formatted file which may contain delete requests
+ struct metaVar* vars; // if NOT NULL: list of variables belonging to this object
+ struct hash* varHash; // if NOT NULL: variables are also hashed! (var str to metaVar struct)
+ };
+
+struct metaLeafObj
+// When searching var->val->obj this is the bottom-level obj struct.
+ {
+ struct metaLeafObj* next; // Next in singly linked list of variables
+ char *objName; // Object name or ID
+ enum metaObjType objType; // table | file
+ };
+
+struct metaLimbVal
+// When searching var->val->obj this is the mid-level val->obj struct.
+ {
+ struct metaLimbVal* next; // Next in singly linked list of variables
+ char *val; // Metadata value.
+ struct metaLeafObj* 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 metaRootVar
+// When searching metadata var->val->object this is the top struct
+ {
+ struct metaRootVar* next; // Next in singly linked list of variables
+ char *var; // Metadata variable name.
+ enum metaVarType varType; // txt | binary
+ struct metaLimbVal* vals; // list of values associated with this var
+ struct hash* valHash; // if NOT NULL: hash of vals (val str to limbVal struct)
+ };
+
+enum metaObjType metaObjTypeStringToEnum(char *objType);
+// Convert metadata objType string to enum
+
+char *metaObjTypeEnumToString(enum metaObjType objType);
+// Convert metadata objType enum string
+
+enum metaVarType metaVarTypeStringToEnum(char *varType);
+// Convert metadata varType string to enum
+
+char *metaVarTypeEnumToString(enum metaVarType varType);
+// Convert metadata varType enum string
+
+struct metaObj *metaObjsLoadFromFormattedFile(char *fileName);
+// Load all metaObjs from a file containing metadata formatted lines
+
+int metaObjsSetToDb(struct sqlConnection *conn,char *tableName,struct metaObj *metaObjs,boolean replace);
+// Adds or updates metadata obj/var pairs into the named table. Returns total rows affected
+
+struct metaObj *metaObjsLoadAllFromTbl(struct sqlConnection *conn,char *tableName);
+// Load all metaObjs from a table (default metaTbl). Will build varHash.
+
+struct metaObj *metaObjLoadFromTbl(struct sqlConnection *conn,char *tableName,char *objName);
+// Load a metaObj from a table (default metaTbl). Will build varHash.
+
+struct metaObj *metaObjVarLoadFromTbl(struct sqlConnection *conn,char *tableName,char *objName,char *varName);
+// Load a single metadata obj/var pair from a table (default metaTbl). No objHash build
+
+struct metaRootVar *metaRootVarsLoadAllFromTbl(struct sqlConnection *conn,char *tableName);
+// Load all metaVars from a table (default metaTbl) for searching var->val->obj. Will build objHash.
+
+struct metaRootVar *metaRootVarLoadFromTbl(struct sqlConnection *conn,char *tableName,char *varName);
+// Load a metaVar from a table (default metaTbl) for searching val->obj. Will build objHash
+
+void metaObjsFree(struct metaObj **metaObjsPtr);
+// Frees one or more metadata objects and any contained metaVars. Will free any hashes as well.
+
+void metaRootVarsFree(struct metaRootVar **metaRootVarsPtr);
+// Frees one or more metadata vars and any contained vals and objs. Will free any hashes as well.
+
+#endif /* METATBL_H */
+