---

lookdbinterface.h File Reference

The interface layer. More...

#include <stddef.h>

Go to the source code of this file.

Defines
#define	DB_TYPE_ERROR   -1
	Error in getting database type.
#define	DB_UNKNOWN   0
	Unknown.
#define	DB_INGRES   1
	Ingres.
#define	DB_SQL_SERVER   2
	SQL Server.
#define	DB_ORACLE   3
	Oracle.
#define	DB_POSTGRES   4
	PostgreSQL.
#define	LOOK_CHAR   0
	A string.
#define	LOOK_INTEGER   1
	An integer (precision determines size).
#define	LOOK_FLOAT   2
	A floating point value (precision determines size).
#define	LOOK_MONEY   3
	A currency type - 2dp number.
#define	LOOK_VARCHAR   4
	A string.
#define	LOOK_DATE   5
	A date/time.
#define	LOOK_LONGVARCHAR   6
	A long string (LONG).
#define	LOOK_NUMERIC   7
	A numeric - number held as string.
#define	LOOK_RAWDATA   8
	Raw data.
#define	LOOK_LONGRAWDATA   9
	Long raw data.
#define	lookDcValueAs(T, DC, X)   *((T*)lookDcValue(DC,X))
	lookDcValue cast to the appropriate type T. DC is theDescriptor, X is theIndex.
Functions
int	lookdbabf ()
	lookdbabf. More...
LOOK_DBC	lookDbConnect (const char *theDatabaseName, const char *theUser, const char *thePassword, int isAutoCommit)
	Connect to the database. More...
void	lookDbDisconnect (LOOK_DBC theSession)
	Disconnect from the database. More...
LOOK_STMT	lookDbPrepare (LOOK_DBC theSession, const char *theStatement)
	Prepare a SQL statement for execution. More...
BOOLEAN	lookDbExecute (LOOK_STMT theStmt, int *theRowsAffected)
	Execute a SQL statement. More...
BOOLEAN	lookDbDescribe (LOOK_STMT theStmt)
	Describe a SQL statement. More...
BOOLEAN	lookDbOpenCursor (LOOK_STMT theStmt)
	Open a cursor. More...
BOOLEAN	lookDbFetchCursor (LOOK_STMT theStmt)
	Fetch a row. More...
void	lookDbCloseCursor (LOOK_STMT theStmt)
	Close a cursor. More...
void	lookDbDestroyStatement (LOOK_STMT theStmt)
	Destroy a statement. More...
BOOLEAN	lookDbCommit (LOOK_DBC theSession)
	Commit. More...
BOOLEAN	lookDbRollback (LOOK_DBC theSession)
	Rollback. More...
BOOLEAN	lookDbSetActiveSession (LOOK_DBC theSession)
	Set the active session. More...
void	lookDsPutInteger (LOOK_STMT theStmt, int theIndex, int theValue)
	Put an integer parameter. More...
void	lookDsPutFloat (LOOK_STMT theStmt, int theIndex, double theValue)
	Put a float parameter. More...
void	lookDsPutString (LOOK_STMT theStmt, int theIndex, const char *theValue, size_t theLength)
	Put an string parameter. More...
void	lookDsPutLongString (LOOK_STMT theStmt, int theIndex, const char *theValue, size_t theLength)
	Put an long string parameter. More...
void	lookDsPutLongRawData (LOOK_STMT theStmt, int theIndex, const char *theValue, size_t theLength)
	Put long raw data. More...
void	lookDsPutRawData (LOOK_STMT theStmt, int theIndex, const char *theValue, size_t theLength)
	Put raw data. More...
void	lookDsPutNULLInteger (LOOK_STMT theStmt, int theIndex)
	Put NULL integer. More...
void	lookDsPutNULLFloat (LOOK_STMT theStmt, int theIndex)
	Put NULL float. More...
void	lookDsPutNULLString (LOOK_STMT theStmt, int theIndex)
	Put NULL string. More...
void	lookDsPutNULLLongString (LOOK_STMT theStmt, int theIndex)
	Put NULL long string. More...
void	lookDsPutNULLLongRawData (LOOK_STMT theStmt, int theIndex)
	Put NULL long raw data. More...
void	lookDsPutNULLRawData (LOOK_STMT theStmt, int theIndex)
	Put NULL raw data. More...
int	lookDsColCount (LOOK_STMT theStmt)
	Count Columns. More...
BOOLEAN	lookDsHasResults (LOOK_STMT theStmt)
	Does the statement return results. More...
int	lookDsParameterCount (LOOK_STMT theStmt)
	Count the number of parameters. More...
void	lookDsSetParameterCount (LOOK_STMT theStmt, int theCount)
	Set the number of parameters. More...
char*	lookDcFieldName (LOOK_STMT theStmt, int theIndex)
	What is the name of the field/column. More...
BOOLEAN	lookDcNullable (LOOK_STMT theStmt, int theIndex)
	Is the column nullable. More...
BOOLEAN	lookDcIsNull (LOOK_STMT theStmt, int theIndex)
	Is the field null? More...
LOOK_TYPE	lookDcType (LOOK_STMT theStmt, int theIndex)
	What type is the column? More...
char*	lookDcValue (LOOK_STMT theStmt, int theIndex)
	Get the column data. More...
int	lookDcPrecision (LOOK_STMT theStmt, int theIndex)
	What precision is the column? More...
const char*	lookDbGetLastError (long *theErrorNumber)
	Get the last error. More...
int	lookDbGetDatabaseType (LOOK_DBC theSession)
	Database Type. More...
BOOLEAN	lookDbSetInterfaceLibrary (const char *theLibraryName)
	Load up the interface library. More...

---

Detailed Description

The interface layer.

This file defines the dbms interface layer, which is a pile of 'C' functions.

dbinterface.cpp defines the version liblookdb is linked with. This is responsible for loading the appropriate dbms-specific shared library/dll at run time and calling the appropriate functions.

The dbms-specific shared library/dll needs implementation of all the functions except lookDbSetInterfaceLibrary. (although if you promise you're not going to use eg raw data functions, you may get away with only a placeholder).

The functions are enough to provide an interface on various dbms - so some of them may well do nothing. When writing a new dbms interface library it is probably wise to look quite hard at the existing ones to see what is necessary.

---

Function Documentation

void lookDbCloseCursor ( LOOK_STMT theStmt )

Close a cursor. Close the cursor for the given statement handle. Parameters: theStmt   The statement handle (from lookDbPrepare()) Returns: None

BOOLEAN lookDbCommit ( LOOK_DBC theSession )

Commit. Commit a session/connection. Parameters: theSession   Session/connection to commit Returns: TRUE for success, FALSE otherwise.

LOOK_DBC lookDbConnect ( const char * theDatabaseName, const char * theUser, const char * thePassword, int isAutoCommit )

Connect to the database. Connect to the database. If your database login is handled elsewhere (eg a unix login) theUser and thePassword will probably be empty strings. Parameters: theDatabaseName   The database to connect to theUser   The database user thePassword   The database password isAutoCommit   FALSE (0) for no auto commit Returns: A session handle. -1 indicates failure.

BOOLEAN lookDbDescribe ( LOOK_STMT theStmt )

Describe a SQL statement. Describe a prepared SQL statement. You must do this after preparing it. Parameters: theStmt   The statement handle (from lookDbPrepare()). Returns: TRUE for success, FALSE for failure

void lookDbDestroyStatement ( LOOK_STMT theStmt )

Destroy a statement. Destroy the statement (from lookDbPrepare()) Parameters: theStmt   The statement. Returns: None

void lookDbDisconnect ( LOOK_DBC theSession )

Disconnect from the database. Disconnect from the database. Parameters: theSessionNumber   A session handle (from lookDbConnect()) Returns: None

BOOLEAN lookDbExecute ( LOOK_STMT theStmt, int * theRowsAffected )

Execute a SQL statement. Execute a previously prepared statement. Use this for updates, deletes etc - use lookDbOpenCursor() for selects. Parameters: theStmt   The statement handle (from lookDbPrepare()). theRowsAffected   Pointer to an int to receive the number of rows affected. This int must be valid. Returns: TRUE for success, FALSE for failure.

BOOLEAN lookDbFetchCursor ( LOOK_STMT theStmt )

Fetch a row. Fetch a row for a statement handle/descriptor. After a row is fetched the data can be retrieved using lookDcValue() etc, one column at a time. Parameters: theStmt   The statement handle (from lookDbPrepare()) Returns: TRUE for success, FALSE if there was no more data.

int lookDbGetDatabaseType ( LOOK_DBC theSession )

Database Type. Get the database type. This can be eg DB_INGRES, DB_ORACLE. (DB_*, listed in the Defines section) The session handle is required because ODBC for example needs this as it doesn't know what sort of database it is until it is connected. If 0 is passed for theSession, DB_UNKNOWN will be returned if the interface is unable to determine what sort of database it uses until it is connected. Parameters: theSession   A session handle from lookDbConnect. Returns: Database type

const char* lookDbGetLastError ( long * theErrorNumber )

Get the last error. Obtain the error string and error number for the last interface error. Parameters: theErrorNumber   Pointer to a long to recieve the error number. Returns: Pointer to error string. This is valid until the next call to the interface layer.

BOOLEAN lookDbOpenCursor ( LOOK_STMT theStmt )

Open a cursor. Open a fetch cursor given a statement handle and a statement descriptor. Ie execute the statement and prepare it for fetch. Parameters: theStmt   The statement handle (from lookDbPrepare()) Returns: TRUE for success, FALSE otherwise.

LOOK_STMT lookDbPrepare ( LOOK_DBC theSession, const char * theStatement )

Prepare a SQL statement for execution. Prepare a SQL Statement for execution. After preparation you can add any required parameters. You must destroy the returned statement handle with lookDbDestroyStatement when you have finished with it. Parameters: theStatement   The SQL statement - a C-style string. "?" marks parameter placeholders. theSession   A session handle from lookDbConnect() Returns: A statement handle. -1 indicates failure.

BOOLEAN lookDbRollback ( LOOK_DBC theSession )

Rollback. Rollback a session/connection. Parameters: theSession   Session/connection to commit Returns: TRUE for success, FALSE otherwise.

BOOLEAN lookDbSetActiveSession ( LOOK_DBC theSession )

Set the active session. Set the current active session/connection. This is only for use with external database programs eg those which use ESQLC. Other use is now deprecated. Parameters: theSession   The session handle from lookDbConnect(). Returns: TRUE for success, FALSE otherwise.

BOOLEAN lookDbSetInterfaceLibrary ( const char * theLibraryName )

Load up the interface library. Load the appropriate dbms-specific interface library. theLibraryName can be either a) nothing (empty string) b) a short name, eg oci, ingres-ii, odbc or c) a library name, eg liblookdbmsoci.so or fredsoci.so (or dll) If nothing is passed in, a default is chosen. The environment variable LOOKDBINTERFACE is checked and used if present. Otherwise odbc under windows and ingres-oi under unix are used. (one of these is more useful than the other!) The short names are expanded to liblookdbmsXXXX.so (or dll). A library name can be a full path or just the library name. The library found by the normal rules of dlopen or LoadLibrary is used. This may only be called successfully once. Parameters: theLibraryName   Null-terminated string. Returns: TRUE for success, FALSE for failure. look::DbError is set appropriately.

char* lookDcFieldName ( LOOK_STMT theStmt, int theIndex )

What is the name of the field/column. Returns the field/column name. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The column index (start at 0). Returns: Null terminated string with the name in it. The string will be valid either until the statement is destroyed or the next call to lookDcFieldName()

BOOLEAN lookDcIsNull ( LOOK_STMT theStmt, int theIndex )

Is the field null? Is theIndexth column null? This must be called after a fetch. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The column index (start at 0). Returns: TRUE for yes, FALSE otherwise.

BOOLEAN lookDcNullable ( LOOK_STMT theStmt, int theIndex )

Is the column nullable. Is theIndexth column nullable or not (NOT NULL)? Parameters: theStmt   The statement from lookDbPrepare() theIndex   The column index (start at 0). Returns: TRUE for yes, FALSE otherwise.

int lookDcPrecision ( LOOK_STMT theStmt, int theIndex )

What precision is the column? Before a fetch, this is the precision of theIndexth column? After a fetch it is the data size. Eg int, float are (often!) 4. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The column index (start at 0). Returns: The precision.

LOOK_TYPE lookDcType ( LOOK_STMT theStmt, int theIndex )

What type is the column? What type is theIndexth column? Valid types are LOOK_CHAR, LOOK_INTEGER, etc. (LOOK_*, listed in the Defines section) Parameters: theStmt   The statement from lookDbPrepare() theIndex   The column index (start at 0). Returns: The type.

char* lookDcValue ( LOOK_STMT theStmt, int theIndex )

Get the column data. Get the column data. This is valid intil the statement is closed, the next fetch or the next lookDcValue(). The data is char*, however it needs casting to an appropriate type based on lookDcType() and lookDcPrecision(). Parameters: theStmt   The statement from lookDbPrepare() theIndex   The column index (start at 0). Returns: Data

int lookDsColCount ( LOOK_STMT theStmt )

Count Columns. Count the columns in a result set. Parameters: theStmt   The statement from lookDbPrepare() Returns: The number of columns

BOOLEAN lookDsHasResults ( LOOK_STMT theStmt )

Does the statement return results. Updates, inserts and deletes don't have results, selects do. This tells you which you have. (so you know whether to execute or opencursor). Parameters: theStmt   The statement from lookDbPrepare() Returns: TRUE for yes, FALSE otherwise.

int lookDsParameterCount ( LOOK_STMT theStmt )

Count the number of parameters. Count the number of parameters in the SQL Statement referred to by theStmt. (these are marked by "?" in the original statement) I think Ingres can't count them on its own, hence the set function. Parameters: theStmt   The statement from lookDbPrepare() Returns: Number of parameters

void lookDsPutFloat ( LOOK_STMT theStmt, int theIndex, double theValue )

Put a float parameter. Bind a double float to theIndexth parameter for the given parameter descriptor. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. theValue   The double to bind. Returns: None

void lookDsPutInteger ( LOOK_STMT theStmt, int theIndex, int theValue )

Put an integer parameter. Bind an integer to theIndexth parameter for the given parameter descriptor. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. theValue   The integer to bind. Returns: None

void lookDsPutLongRawData ( LOOK_STMT theStmt, int theIndex, const char * theValue, size_t theLength )

Put long raw data. Bind some binary data to theIndexth parameter for the given parameter descriptor. The data can include nulls. This is for LONG RAW columns. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. theValue   The data to bind. theLength   The length of the data. Returns: None

void lookDsPutLongString ( LOOK_STMT theStmt, int theIndex, const char * theValue, size_t theLength )

Put an long string parameter. Bind an string to theIndexth parameter for the given parameter descriptor. The string shouldn't contain embedded nulls. This variant is for LONG columns. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. theValue   The string to bind. theLength   The length of the string (not including terminating null) Returns: None

void lookDsPutNULLFloat ( LOOK_STMT theStmt, int theIndex )

Put NULL float. Bind a NULL value to theIndexth parameter for the given parameter descriptor. The parameter was otherwise a float (double). Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. Returns: None

void lookDsPutNULLInteger ( LOOK_STMT theStmt, int theIndex )

Put NULL integer. Bind a NULL value to theIndexth parameter for the given parameter descriptor. The parameter was otherwise an integer. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. Returns: None

void lookDsPutNULLLongRawData ( LOOK_STMT theStmt, int theIndex )

Put NULL long raw data. Bind a NULL value to theIndexth parameter for the given parameter descriptor. The parameter was otherwise an LONG RAW Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. Returns: None

void lookDsPutNULLLongString ( LOOK_STMT theStmt, int theIndex )

Put NULL long string. Bind a NULL value to theIndexth parameter for the given parameter descriptor. The parameter was otherwise a LONG. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. Returns: None

void lookDsPutNULLRawData ( LOOK_STMT theStmt, int theIndex )

Put NULL raw data. Bind a NULL value to theIndexth parameter for the given parameter descriptor. The parameter was otherwise a RAW. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. Returns: None

void lookDsPutNULLString ( LOOK_STMT theStmt, int theIndex )

Put NULL string. Bind a NULL value to theIndexth parameter for the given parameter descriptor. The parameter was otherwise a string. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. Returns: None

void lookDsPutRawData ( LOOK_STMT theStmt, int theIndex, const char * theValue, size_t theLength )

Put raw data. Bind some binary data to theIndexth parameter for the given parameter descriptor. The data can include nulls. This is for RAW columns. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. theValue   The data to bind. theLength   The length of the data. Returns: None

void lookDsPutString ( LOOK_STMT theStmt, int theIndex, const char * theValue, size_t theLength )

Put an string parameter. Bind an string to theIndexth parameter for the given parameter descriptor. The string shouldn't contain embedded nulls. Parameters: theStmt   The statement from lookDbPrepare() theIndex   The number of the parameter. 0 is the first one. theValue   The string to bind. theLength   The length of the string (not including terminating null) Returns: None

void lookDsSetParameterCount ( LOOK_STMT theStmt, int theCount )

Set the number of parameters. Set the number of parameters in the SQL Statement referred to by theStmt. (these are marked by "?" in the original statement) Ingres needs this setting, others ignore it. Parameters: theStmt   The statement from lookDbPrepare() theCount   The number of parameters.

int lookdbabf ( )

lookdbabf. Something to do with ingres 4gl? Returns: something

---