Linux Certif

Toute la documentation sur la certification Linux LPI

yada

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 statements, 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]. Once 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 executing 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 storage 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 letter 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

l

number 64 bit, signed or unsigned

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)