/*---------------------------------------------------------------------------------*/ /* $RCSfile: database.h,v $ */ /*---------------------------------------------------------------------------------*/ /* $Revision: 1.1 $ */ /* $Name: $ */ /* $Date: 2006/02/28 23:28:21 $ */ /* $Author: agibert $ */ /*---------------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------------*/ /* This file is part of LibDataBase */ /* */ /* LibDataBase is free software; you can redistribute it and/or modify */ /* it under the terms of the GNU Lesser General Public Licence as published by */ /* the Free Software Foundation; either version 2.1 of the License, or */ /* (at your option) any later version. */ /* */ /* LibDataBase is distributed in the hope that it will be useful, */ /* but WITHOUT ANY WARRANTY; without even the implied warranty of */ /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */ /* GNU Lesser General Public License for more details. */ /* */ /* You should have received a copy of the GNU Lesser General Public License */ /* along with LibDataBase; if not, write to the Free Software */ /* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ /*---------------------------------------------------------------------------------*/ #ifndef DATABASE_H #define DATABASE_H #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /* API return codes */ typedef int DBT_Status; #define DB_ERROR(s) ((s) < 0) #define DBS_OK 1 /* OK */ #define DBS_END_OF_DATA 2 /* No more data available */ #define DBS_ERRAPI -1 /* Bad use of arguments */ #define DBS_ERROCI -2 /* OCI problem */ #define DBS_ERRMEM -3 /* Not enough memory */ #define ERROR_TO_STRING(e) \ ((e) == DBS_OK) ? "OK" : \ ((e) == DBS_END_OF_DATA) ? "END_OF_DATA" : \ ((e) == DBS_ERRAPI) ? "ERRAPI" : \ ((e) == DBS_ERROCI) ? "ERROCI" : \ ((e) == DBS_ERRMEM) ? "ERRMEM" : "Unknown Error" /* Library opening mode */ #define DBD_ERRMSG 1 #define DBD_DEBUG 2 /* DB type */ #define DBD_ORACLE 1 /* data types for host variables */ #define DBD_STRING 1 #define DBD_INTEGER 2 #define DBD_FLOAT 3 #define DBD_DOUBLE 4 #define DBD_DATE 5 #define DBD_ROWID 6 /* Types */ typedef sb2 DBT_Indicator; typedef void *DBT_Date_Ptr; /* Date is an abstract type, allocated only from the library */ typedef struct { int rowsProcessed; /* rows fetched/inserted/updated, always valid on SELECT statements, */ /* otherwise -1 if it couldn't be determined */ int errorIteration; /* iteration which caused the error; -1 if it couldn't be determined */ } DBT_Result; typedef struct { OCIEnv * envhp; /* Handle d'environnement */ OCIError * errhp; /* Handle d'erreur */ OCIServer * srvhp; /* Handle de serveur */ OCISvcCtx * svchp; /* Handle de context */ OCISession * authp; /* Handle de session ouverte */ OCITrans * transp; /* Handle de transaction */ int handlesAreValid; /* true if all handles are valid */ char error[512]; /* erreur OCI */ dword errorCode; /* code erreur OCI */ } DBT_Connection; typedef struct { DBT_Connection *connection; OCIStmt *handle; /* Handle de requête */ OCIError *errhp; /* Handle d'erreur */ char error[512]; /* erreur OCI */ dword errorCode; /* code erreur OCI */ int isPrepared; int isExecuted; int isSelect; int varsDefined; int varsBound; int rowsToFetch; int rowsBound; int rowsFetchedSoFar; /* total rows fetched so far for a query */ int isEOF; /* true if EOF reached fetching data (SELECT statements) */ } DBT_Statement; typedef struct { int type; /* type de la valeur */ int size; /* taille du buffer pour une valeur */ void *value; /* pointeur sur la valeur ou le tableau de valeurs */ DBT_Indicator *indicator; /* pointeur sur l'indicateur ou le tableau d'indicateurs */ } DBT_HostVar; /*------------------------------------------------------------------------------*/ /* Opens library and initializes OCI environment. */ /*------------------------------------------------------------------------------*/ /* (I) debugFlags: 0, DBD_ERRMSG, DBD_DEBUG or a binary OR-ed combination. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Library_Open(int debugFlags); /*------------------------------------------------------------------------------*/ /* Closes library and OCI environment. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Library_Close(void); /*------------------------------------------------------------------------------*/ /* Gets last error message generated by the library. */ /*------------------------------------------------------------------------------*/ const char *DB_Error_Message_Get (void); /*------------------------------------------------------------------------------*/ /* Connects to an Oracle database. */ /*------------------------------------------------------------------------------*/ /* (I/O) connection: Address of an uninitialized DBT_Connection. */ /* (I) Login : Login name of user. */ /* (I) Password : Password. */ /* (I) Database : Oracle SID of the target database. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Connect(DBT_Connection *connection, const char *Login, const char *Password, const char *Database); /*------------------------------------------------------------------------------*/ /* Disconnects from database. */ /* The current transaction, if any, is committed */ /*------------------------------------------------------------------------------*/ /* (I) connection: The DBT_Connection used to connect. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Disconnect(DBT_Connection *connection); /*------------------------------------------------------------------------------*/ /* Gets last error number and message as returned by Oracle while connecting. */ /*------------------------------------------------------------------------------*/ /* (I) connection: DBT_Connection used to connect. */ /* (O) errCode : Error code. */ /* (O) errStr : Error message. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Connection_SQLError_Get(DBT_Connection *connection, dword *errCode, char **errStr); /*------------------------------------------------------------------------------*/ /* Starts a new transaction. */ /* IMPORTANT: Two queries run simultaneously (multithread) must use two */ /* different DBT_Connection, i.e. you must call DB_Connect twice, one for each */ /* transaction. */ /*------------------------------------------------------------------------------*/ /* (I) connection: DBT_Connection used to connect. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Transaction_Start(DBT_Connection *connection); /*------------------------------------------------------------------------------*/ /* Commits transaction. */ /*------------------------------------------------------------------------------*/ /* (I) connection: DBT_Connection used to connect. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Transaction_Commit(DBT_Connection *connection); /*------------------------------------------------------------------------------*/ /* Rolls transaction back. */ /* The state of the database restored is the one that existed before */ /* DB_Transaction_Start() was called. */ /*------------------------------------------------------------------------------*/ /* (I) connection: DBT_Connection used to connect. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Transaction_Rollback(DBT_Connection *connection); /*------------------------------------------------------------------------------*/ /* Initializes an 'hostvar', variable that will be later associated to an */ /* input or output value. */ /*------------------------------------------------------------------------------*/ /* (I/O) HostVar: Address of an existing DBT_HostVar that will be filled in. */ /* (I) type : Type of data this hostvar refers to. */ /* (I) size : Size in bytes of the data type. Ex: DBD_INTEGER: sizeof(int); */ /* DBD_STRING: size of largest string + 1. */ /* (I) value : Pointer to input or output value (or array of values). */ /* (I) indicator: DBT_Indicator or array of DBT_Indicator. */ /* */ /* Type can be DBD_{INTEGER,STRING,FLOAT,DOUBLE,DATE}. */ /* */ /* Value points to an array of data (int[] for DBD_INTEGER, double[] for */ /* DBD_DOUBLE etc. Note: for strings, value points to a char[][] and not */ /* a char*[]) */ /* For DBD_DATE fields, the array must be allocated via DB_DateArray_Alloc. */ /* */ /* The value of indicator, for outgoing data, must be -1 for a null value */ /* and 0 otherwise. For incoming data, it is -1 if the value is null, 0 */ /* if the value was retrieved correctly, and >0 if the value is truncated */ /* (in the latter case, it is the real length of the data value). */ /*------------------------------------------------------------------------------*/ DBT_Status DB_HostVar_Setup(DBT_HostVar *HostVar, int type, int size, void *value, DBT_Indicator *indicator); /*------------------------------------------------------------------------------*/ /* The following functions are used to manipulate Oracle dates in their */ /* native format. */ /* Although less compact, it is often more simple to consider dates in a table */ /* as strings and to define hostvars in consequence. */ /* Ex: if col1 is a date, "SELECT col1 from TABLEX WHERE ..." or */ /* "SELECT TO_CHAR(col1, 'DD/MM/YYYY HH24:MI:SS') from TABLEX WHERE ..." */ /* will do the job with a hostvar's type of DBD_STRING with size 20. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_DateArray_Alloc(DBT_Date_Ptr *array, int size); DBT_Status DB_DateArray_Free(DBT_Date_Ptr dateArray); DBT_Status DB_String_To_Date(DBT_Date_Ptr dateArray, int idx, char *value, char *format); DBT_Status DB_Date_To_String(DBT_Date_Ptr dateArray, int idx, char *value, char *format); /*------------------------------------------------------------------------------*/ /* Initializes a statement. */ /*------------------------------------------------------------------------------*/ /* (I) connection: DBT_Connection used to connect. */ /* (I) statement : An uninitialized DBT_Statement. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_Init(DBT_Connection *connection, DBT_Statement *statement); /*------------------------------------------------------------------------------*/ /* Frees resources associated to a previously initialized statement. */ /*------------------------------------------------------------------------------*/ /* (I) statement : A DBT_Statement. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_Close(DBT_Statement *statement); /*------------------------------------------------------------------------------*/ /* Gets last error number and message as returned by Oracle while working on */ /* a statement. . . . . . . . . */ /*------------------------------------------------------------------------------*/ /* (I) statement : DBT_Statement. */ /* (O) errCode : Error code. */ /* (O) errStr : Error message. */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_SQLError_Get(DBT_Statement *statement, dword *errCode, char **errStr); /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_Prepare(DBT_Statement *statement, const char *query); /*------------------------------------------------------------------------------*/ /* Used to retrieve select-list results. */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_DefineVars(DBT_Statement *statement, int rows, ... /* HostVar *, ending with NULL */); /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_DefineVar(DBT_Statement *statement, int rows, int column, DBT_HostVar *hv); /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ /* Used for placeholders (like ":1" in "select * from TB where col = :1") */ /* */ /* Note: you cannot use the same placeholder more than once in a statement. */ /* */ /* Note: The bindings are done in the order of the placeholders in the */ /* statement from left to right, and the name of the placeholder (like :1, :2) */ /* has no influence. */ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_BindVars(DBT_Statement *statement, int rows, ... /* HostVar *, ending with NULL */); /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_BindVar(DBT_Statement *statement, int rowsBound, int placeHolderIndex, DBT_HostVar *hostVar); /*------------------------------------------------------------------------------*/ /* For SELECT statements, startingRow and endingRow must be 0 (array binds */ /* cannot be used). */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_Execute(DBT_Statement *statement, int startingRow, int count, DBT_Result *result); /*------------------------------------------------------------------------------*/ /* A shorthand for DB_Statement_Execute for SELECT statements. */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_ExecuteSelect(DBT_Statement *statement, DBT_Result *result); /*------------------------------------------------------------------------------*/ /* Retrieves next results after a query has been executed with */ /* DB_Statement_Execute(). */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_Fetch(DBT_Statement *statement, DBT_Result *result); /*------------------------------------------------------------------------------*/ /* Cancels implicit cursor associated to last fetch. */ /*------------------------------------------------------------------------------*/ /* */ /*------------------------------------------------------------------------------*/ DBT_Status DB_Statement_Fetch_Terminate(DBT_Statement *statement); /*------------------------------------------------------------------------------*/ /* Sets debug level for debug messages display. */ /*------------------------------------------------------------------------------*/ /* (I) level: 0 to disable display. */ /*------------------------------------------------------------------------------*/ void DB_Debug_Level_Set(int level); #ifdef __cplusplus } #endif #endif