yada(3)                                                                yada(3)

NAME
       yada - yet another database abstraction

SYNOPSIS
       #include <yada.h>

       yada_t* yada_init(char *db_str, unsigned int flags);

       int connect(yada_t *yada, char *user, char *pass);
       void disconnect(yada_t *yada);
       void destroy(yada_t *yada);

       yada_rc_t* prepare(yada_t *yada, char *fmt, int *len);
       int execute(yada_t *yada, void *magic, ...);
       yada_rc_t* query(yada_t *yada, void *magic, ...);
       char* dumpexec(yada_t *yada, int *retlen,  yada_rc_t *prep, ...);

       yada_rc_t* bind(yada_t *yada, char *fmt, ...);
       yada_rc_t* fetch(yada_t *yada, yada_rc_t *res, yada_rc_t *bindset);

       void free(yada_t *yada, yada_rc_t *yada_rc);
       void freeall(yada_t *yada, int type);"

DESCRIPTION
       Yada  is  a  database abstraction library aimed at allowing transparent
       use of multiple databases.  To accomplish this, it uses a compatability
       layer  of  functions to bind input and output variables, prepare state-
       ments, and retreive data.

       To use yada, you must first initialize  the  library  with  yada_init()
       which  will  return  a  pointer to a yada object (yada_t *) of database
       type specified in db_str.  The object may then  be  used  to  call  the
       other  functions as pointers from the base obj (i.e., yada->connect()).

       If at any time a yada function returns an  error,  error  code  may  be
       checked   at  (int)  yada->error  and  error  message  at  (const  char
       *)yada->errmsg, except for yada_init,  in  which  case  error  will  be
       stored in errno.

       yada_init()  initializes  the  yada  library and returns a pointer to a
       yada object of the database type specified in db_str, a string made  up
       of  <database  type>:[type  specific  connection options].   ce this is
       done, you may call the  other  functions  from  this  base  obj  (i.e.,
       yada->connect()).

       destroy()  closes  the  database  connection,  frees all memory used by
       yada, and therefore invalidates the yada struct.

       connect() attempts to connect to the database  defined  in  the  db_str
       passed  to  yada_init(),  using  user and  pass if used by the database
       type you're connecting to.  Returns 0 on failure, non 0 on success.

       prepare() prepares a string for execution, allowing  mapping  of  input
       variables to be passed to execute.

       execute() and query() can both be used be multiple ways.  If magic is a
       string, the next argument should be the length of the string, or 0  for
       a  NULL  terminated  one.  If magic is a prepared statement yada_rc, it
       expects the placeholder  variables  to  follow.   On  success,  query()
       returns  a  yada resource containing a result set and execute() returns
       the number of rows affected.  On failure,  query()  returns  NULL,  and
       execute() returns -1.

       dumpexec()  functions exactly the same as execute, only instead of exe-
       cuting the final statement, returns it as a string.  If not  NULL,  the
       length of the returned string is put into retlen.

       bind()  maps variables to results.  It expects pointers to actual stor-
       age space to put the variable into.  On null results, it sets the first
       byte  of the string to 0.  If the type is preceeded by 'p' it expects a
       pointer to a pointer which it will set to retreived data.  On null,  it
       sets the pointer to 0.

       fetch()  retrieves  the next row of results into the variables bound by
       bind().  Binary length variables will be unset if the field is NULL.

       free() frees the resource pointed to by yada_rc.

       freeall() frees all memory used by yada resources  of  type  type.   If
       type  is  -1,  it will free all resources, type maybe be an OR'd set of
       multiple types.

       type may be any of the following:

       YADA_STATEMENT
              prepared statements returned from prepare()

       YADA_RESULT
              result sets returned from query()

       YADA_BINDSET
              bind sets as returned from bind()

       Yada tokens are used to define variable types  in  both  prepare()  and
       bind().  Tokens are specified with a question mark followed by the let-
       ter for the type.  To specify the variable is a pointer, use a question
       mark followed by a 'p' and then followed by the type letter.  Currently
       this is only used in bind().

       token types are as follows:

       a      escaped binary string

       b      binary string - a binary string is a pair of variables, a char *
              string,  and an unsigned long length.  Whenever you need to pass
              the string variable, you should pass the length  variable  next.
              When used with bind() and an execute function is called, the len
              variable is always just an unsigned long and  never  a  pointer,
              even if the binary string is a pointer (?pb).

       d      number 32 bit, signed or unsigned

       e      escaped string

       s      string - NULL terminated char *

       v      variable - a variable is like an escaped string except yada will
              surroung it with single quotes (') if  it's  set,  or  with  the
              string NULL if null.

       Escaped  variables  are the same as the variable, except any characters
       needing escaping are escaped (this differs with the type of database it
       is).

EXAMPLES
       Coming soon!  For now, the best place to check is test/yada_test.c

SEE ALSO
       yada.trx(3)

                                                                       yada(3)