src/hg/inc/metaTbl.h 1.2
1.2 2010/03/18 23:36:18 tdreszer
Extended API for query and print functions
Index: src/hg/inc/metaTbl.h
===================================================================
RCS file: /projects/compbio/cvsroot/kent/src/hg/inc/metaTbl.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -b -B -U 1000000 -r1.1 -r1.2
--- src/hg/inc/metaTbl.h 18 Mar 2010 01:48:53 -0000 1.1
+++ src/hg/inc/metaTbl.h 18 Mar 2010 23:36:18 -0000 1.2
@@ -1,194 +1,228 @@
/* 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 -------------------------------- */
+#define METATBL_DEFAULT_NAME "metaTbl"
+
+
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
+struct metaByVar
// When searching metadata var->val->object this is the top struct
{
- struct metaRootVar* next; // Next in singly linked list of variables
+ struct metaByVar* 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 *metadataLineParse(char *line);
+/* Parses a single formatted metadata line into metaObj for updates or queries. */
+
+struct metaObj *metaObjCreate(char *obj,char *type,char *var, char *varType,char *val);
+/* Creates a singular metaObj query object based on obj and all other optional params. */
+
+struct metaByVar *metaByVarsLineParse(char *line);
+/* Parses a line of "var1=val1 var2=val2 into a metaByVar object for queries. */
+
+struct metaByVar*metaByVarCreate(char *var, char *varType,char *val);
+/* Creates a singular var=val pair struct for metadata queries. */
+
+
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 *metaObjQuery(struct sqlConnection *conn,char *table,struct metaObj *metaObj);
+// Query the metadata table by obj and optional vars and vals in metaObj struct. If metaObj is NULL query all.
+// Retruns new metaObj struct fully populated and sorted in obj,var order.
+#define metaObjsQueryAll(conn,table) metaObjQuery((conn),(table),NULL)
+
+struct metaObj *metaObjQueryByObj(struct sqlConnection *conn,char *table,char *objName,char *varName);
+// Query a single metadata object and optional var from a table (default metaTbl).
+
+
+struct metaByVar *metaByVarsQuery(struct sqlConnection *conn,char *table,struct metaByVar *metaByVars);
+// Query the metadata table by vars and vals in metaByVar struct. If metaByVar is NULL query all.
+// Retruns new metaByVar struct fully populated and sorted in var,val,obj order.
+#define metaByVarsQueryAll(conn,table) metaByVarsQuery((conn),(table),NULL)
+
+struct metaByVar *metaByVarQueryByVar(struct sqlConnection *conn,char *table,char *varName,char *val);
+// Query a single metadata variable and optional val from a table (default metaTbl) for searching val->obj.
+
+
+void metaObjPrint(struct metaObj *metaObjs,boolean printLong);
+// prints objs and var=val pairs as formatted metadata lines or long view
+
+void metaByVarPrint(struct metaByVar *metaByVars,boolean printLong);
+// prints var=val pairs and objs that go with them single lines or long view
-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
+int metaObjCount(struct metaObj *metaObjs);
+// returns the count of vars belonging to this obj or objs;
-struct metaRootVar *metaRootVarsLoadAllFromTbl(struct sqlConnection *conn,char *tableName);
-// Load all metaVars from a table (default metaTbl) for searching var->val->obj. Will build objHash.
+int metaByVarCount(struct metaByVar *metaByVars);
+// returns the count of objs belonging to this set of vars;
-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);
+void metaByVarsFree(struct metaByVar **metaByVarsPtr);
// Frees one or more metadata vars and any contained vals and objs. Will free any hashes as well.
#endif /* METATBL_H */