- remove old api-txt, this was some weeks ago converted to doxygen

git-svn-id: https://openser.svn.sourceforge.net/svnroot/openser/trunk@3608 689a6050-402a-0410-94f2-e92a70836424

lib/srdb1/doc/db-api.txt

@@ -1,295 +0,0 @@
-# $Id$
-# 
-# History:
-# --------
-#  2004-06-06  updated (bind_dbmod and obsoleted db_* macros)  (andrei)
-
-1 Data types
-
-There are several new data types. All of them are defined in header file db.h,
-a client must include the header file to be able to use them.
-
-1.1 Type db_con_t
-
-1.1.1 Description
-
-This type represents a database connection, all database functions (described 
-below) use a variable of this type as one argument. In other words, variable 
-of db_con_t type serves as a handle for a particular database connection.
-
-1.1.2 Definition
-
-   typedef struct db_con {
-        char* table;     /* Default table to use */
-        void* con;       /* Database connection */
-        void* res;       /* Result of previous operation */
-        void* row;       /* Internal, not for public use */
-        int connected;   /* 1 if connection is established */
-   } db_con_t;
-
-1.1.3 Macros
-
-There are no macros for db_con_t type.
-
-
-1.2 Type db_key_t
-
-1.2.1 Description
-
-This type represents a database key. Every time you need to specify a key 
-value, this type should be used. In fact, this type is identical to const 
-char*.
-
-1.2.2 Definition
-   
-   typedef const char* db_key_t;
-
-1.2.3 Macros
-
-There are no macros (It is not needed).
-
-
-1.3 Type db_type_t
-
-1.3.1 Description
-
-Each cell in a database table can be of a different type. To distinguish
-among these types, the db_type_t enumeration is used. Every value of the
-enumeration represents one datatype that is recognized by the database
-API. This enumeration is used in conjunction with db_type_t. For more
-information, see the next section.
-
-1.3.2 Definition
-
-   typedef enum {
-       DB_INT,       /* Integer number */
-       DB_DOUBLE,    /* Decimal number */
-       DB_STRING,    /* String */
-       DB_STR,       /* str structure */
-       DB_DATETIME   /* Date and time */
-       DB_BLOB       /* Binary large object */
-       DB_BITMAP     /* Bitmap, one-dimensional array of flags */
-   } db_type_t;
-
-1.3.3 Macros
-
-There are no macros.
-
-
-1.4 Type db_val_t
-
-1.4.1 Description
-
-This structure represents a value in the database. Several datatypes are
-recognized and converted by the database API:
-
-DB_INT      - Value in the database represents an integer number
-DB_DOUBLE   - Value in the database represents a decimal number
-DB_STRING   - Value in the database represents a string
-DB_STR      - Value in the database represents a string
-DB_DATETIME - Value in the database represents date and time
-DB_BLOB     - Value in the database represents binary large object
-DB_BITMAP   - Value in the database represents an array of flags
-
-These datatypes are automaticaly recognized, converted from internal database
-representation and stored in the variable of corresponding type.
-
-1.4.2 Definition
-
-    typedef struct db_val {
-         db_type_t type;              /* Type of the value */
-         int nul;                     /* NULL flag */
-         union {                      
-             int int_val;             /* Integer value */
-             double double_val;       /* Double value */
-             time_t time_val;         /* Unix time_t value */
-             const char* string_val;  /* Zero terminated string */
-	     str str_val;             /* str structure */
-             str blob_val;            /* Structure describing blob */
-             unsigned int bitmap_val; /* Array of flags */
-         } val;
-    } db_val_t;
-
-1.4.3 Macros
-
-Note: All macros expect reference to db_val_t variable as the parameter.
-
-1.4.3.1 VAL_TYPE(value) Macro
-
-Use this macro if you need to set/get the type of the value
-
-Example: VAL_TYPE(val) = DB_INT;
-         if (VAL_TYPE(val) == DB_FLOAT) ...
-
-1.4.3.2 VAL_NULL(value) Macro
-
-Use this macro if you need to set/get the null flag. Non-zero flag means that 
-the corresponding cell in the database contained no data (NULL value in MySQL
-terminology).
-
-Example: if (VAL_NULL(val) == 1) {
-             printf("The cell is NULL");
-         }
-
-1.4.3.3 VAL_INT(value) Macro
-
-Use this macro if you need to access integer value in the db_val_t structure.
-
-Example: if (VAL_TYPE(val) == DB_INT) {
-             printf("%d", VAL_INT(val));
-         }
-
-1.4.3.4 VAL_DOUBLE(value) Macro 
-
-Use this macro if you need to access double value in the db_val_t structure.
-
-Example: if (VAL_TYPE(val) == DB_DOUBLE) {
-             printf("%f", VAL_DOUBLE(val));
-         }
-
-1.4.3.5 VAL_TIME(value) Macro 
-
-Use this macro if you need to access time_t value in the db_val_t structure.
-
-Example: time_t tim;
-         if (VAL_TYPE(val) == DB_DATETIME) {
-             tim = VAL_TIME(val);
-         }
-
-1.4.3.6 VAL_STRING(value) Macro 
-
-Use this macro if you need to access string value in the db_val_t structure.
-
-Example: if (VAL_TYPE(val) == DB_STRING) {
-             printf("%s", VAL_STRING(val));
-         }
-
-1.4.3.7 VAL_STR(value) Macro
-
-Use this macro if you need to access str structure in the db_val_t structure.
-
-Example: if (VAL_TYPE(val) == DB_STR) {
-             printf("%.*s", VAL_STR(val).len, VAL_STR(val).s);
-         }
-
-1.4.3.8 VAL_BLOB(value) Macro
-
-Use this macro if you need to access blob value in the db_val_t structure.
-
-Example: if (VAL_TYPE(val) == DB_BLOB) {
-	     printf("%.*s", VAL_BLOB(val).len, VAL_BLOB(val).s);
-         }
-
-1.4.3.9 VAL_BITMAP(value) Macro
-
-Use this macro if you need to access bitmap value in the db_val_t structure.
-
-Example: if (VAL_TYPE(val) == DB_BITMAP) {
-	    printf("%d", VAL_BITMAP(val));
-	 }
-
-1.5 Type db_row_t
-
-1.5.1 Description
-
-This type represents one row in a database table. In other words, the row is an
-array of db_val_t variables, where each db_val_t variable represents exactly 
-one cell in the table.
-
-1.5.2 Definition
-
-   typedef struct db_row {
-       db_val_t* values;    /* Array of values in the row */
-       int n;               /* Number of values in the row */
-   } db_val_t;
-
-1.5.3 Macros
-
-1.5.3.1 ROW_VALUES(row) Macro 
-
-Use this macro to get pointer to the array of db_val_t structures.
-
-Example: db_val_t* v = ROW_VALUES(row);
-         if (VAL_TYPE(v) == DB_INT) ....
-
-1.5.3.2 ROW_N(row) Macro 
-
-Use this macro to get number of cells in the row.
-
-Example: db_val_t* val = ROW_VALUES(row);
-         for(i = 0; i < ROW_N(row); i++) {
-             switch(VAL_TYPE(val + i)) {
-             case DB_INT: ...; break;
-             case DB_DOUBLE: ...; break;
-             ...
-             }
-         }
-
-
-1.6 Type db_res_t
-
-1.6.1 Description
-
-This type represents a result returned by db_query function (see below). The 
-result can consist of zero or more rows (see db_row_t description).
-
-Note: A variable of type db_res_t returned by db_query function uses dynamicaly
-      allocated memory, don't forget to call db_free_result if you don't need 
-      the variable anymore. You will encounter memory leaks if you fail to do 
-      this !
-
-In addition to zero or more rows, each db_res_t object contains also an array 
-of db_key_t objects. The objects represent keys (names of columns).
-
-1.6.2 Definition
-
-   typedef struct db_res {
-       struct {
-           db_key_t* keys;    /* Array of column names */
-           db_type_t* types;  /* Array of column types */
-           int n;             /* Number of columns */
-       } col;
-       struct db_row* rows;   /* Array of rows */
-       int n;                 /* Number of rows */
-   } db_res_t;
-
-1.6.3 Macros
-
-1.6.3.1 RES_NAMES(res) Macro 
-
-Use this macro if you want to obtain pointer to the array of cell names.
-
-Example: db_key_t* column_names = ROW_NAMES(row);
-
-1.6.3.2 RES_COL_N(res) Macro 
-
-Use this macro if you want to get the number of columns in the result.
-
-Example: int ncol = RES_COL_N(res)
-         for(i = 0; i < ncol; i++) {
-             /* do something with the column */
-         }
-
-1.6.3.3 RES_ROWS(res) Macro 
-
-Use this macro if you need to obtain pointer to array of rows.
-
-Example: db_row_t* rows = RES_ROWS(res);
- 
-1.6.3.4 RES_ROW_N(res) Macro 
-
-Use this macro if you need to obtain the number of rows in the result
-
-Example: int n = RES_ROW_N(res);
-
-
-1.7 Type db_op_t
-
-1.7.1 Description
-
-This type represents an expression operator. In fact, this type is 
-identical to const char*.
-
-1.7.2 Definition
-   
-   typedef const char* db_op_t;