$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
Ns_Set *Ns_Db0or1Row(
Ns_DbHandle *handle,
char *sql,
int *nrows
);
Note that an SQL select statement that does not return a row is different from an SQL DML statement that does not return a row but modifies the database. In the former case, Ns_Db0or1Row still returns a newly allocated Ns_Set with the column names as the field key names of the rows that would have been returned had any of the rows in the database matched the select criteria. In the latter case, Ns_Db0or1Row returns an error.
If the SQL statement returns more than one row or some database error occurs, Ns_Db0or1Row returns NULL. Detailed error messages may have accumulated in an internal buffer in the Ns_DbHandle.
Ns_Set *row;
int nrows;
Ns_DbHandle *handle;
if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
row = Ns_Db0or1Row(handle, "select aName from aTable",
&nrows);
if (row != NULL && nrows == 1) {
char *value;
value = Ns_SetGet(row, "aName");
/* use `value' here */
Ns_SetFree(row);
}
}
Ns_Set *Ns_Db1Row(
Ns_DbHandle *handle,
char *sql
);
If the SQL statement returns zero rows or a database error has occurred, Ns_Db1Row returns NULL. Detailed error messages may have accumulated in an internal buffer in the Ns_DbHandle.
Ns_Set *row;
Ns_DbHandle *handle;
if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
row = Ns_Db1Row(handle, "select aName from aTable");
if (row != NULL) {
char *value;
value = Ns_SetGet(row, "aName");
/* use `value' here */
Ns_SetFree(row);
}
}
Ns_Set *Ns_DbBindRow (
Ns_DbHandle *handle
);
int Ns_DbBouncePool(
char *poolname
);
int Ns_DbCancel(
Ns_DbHandle *handle
);
int Ns_DbDML(
Ns_DbHandle *handle,
char *sql
);
Ns_DbHandle *handle;
int status;
if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
status = Ns_DbDML(handle,
"insert into aTable (colName1,colName2) values (1,2)");
if (status != NS_OK) {
/* handle error condition */
}
}
char* Ns_DbDriverDbType (
Ns_DbHandle* handle
);
char *Ns_DbDriverName(
Ns_DbHandle *handle
);
The storage for the string returned is owned by the database driver and must not be freed or modified in any way.
int Ns_DbExec (
Ns_DbHandle *handle,
char *sql
);
NS_ERROR
if the SQL command fails
NS_DML
if the SQL command is DML (Data Manipulation Language) or DDL (Data Definition Language)
NS_ROWS
if the SQL command will return rows (such as a SELECT command)
This function allows you to write a true ad hoc query tool and process SQL statements without knowing ahead of time if they return rows or are DDL or DML statements.
int Ns_DbFlush(
Ns_DbHandle *handle
);
Ns_DbFlush is called automatically when Ns_DbHandle's are returned to their pools with the Ns_DbPutHandle function to make sure the handle is ready the next time it is used.
Some database drivers will also cancel any active transactions when Ns_DbFlush is called.
int Ns_DbGetRow(
Ns_DbHandle *handle,
Ns_Set *row
);
NS_OK
A row has been fetched and more rows may be waiting.
NS_END_DATA
No row has been fetched and there are no more rows waiting.
NS_ERROR
A database error occurred, or the function has already returned NS_END_DATA but has been called again anyway.
You cannot call Ns_DbDML, Ns_Db1Row, or Ns_Db0or1Row with the same database handle while fetching rows from the database in an Ns_DbGetRow loop. Doing so flushes any waiting rows and a subsequent call to Ns_DbGetRow will fail. You can do so if you use separate database handles.
Ns_DbHandle *handle;
Ns_Set *row;
int status;
handle = Ns_DbPoolGetHandle("mypool");
row = Ns_DbSelect(handle, "select * from mytable");
if (row == NULL) {
/*... handle select error ...*/
}
while ((status = Ns_DbGetRow(handle, row)) == NS_OK) {
/*... process the row fetched from the database ...*/
}
if (status != NS_END_DATA) {
/*... handle get row error ...*/
}
int Ns_DbInterpretSqlFile (
Ns_DbHandle* handle,
char* filename
);
int Ns_DbPoolAllowable(
char *hServer,
char *poolname
);
char* Ns_DbPoolDefault (
char* server
);
char *Ns_DbPoolDescription
(
char *poolname
);
The storage for the string returned is located in the configuration data memory. You must not deallocate or modify this string in any way.
Ns_DbHandle *Ns_DbPoolGetHandle(
char *poolname
);
Ns_DbHandle *handle;
if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
Ns_Set *row;
row = Ns_DbSelect(handle, "select * from aTable");
...
}
int Ns_DbPoolGetMultipleHandles(
Ns_DbHandle **handles,
char *poolname,
int nhandles
);
#define NUM_HANDLES 5
Ns_DbHandle **handles;
handles = Ns_Malloc(NUM_HANDLES * sizeof (Ns_DbHandle *));
if (Ns_DbPoolGetMultipleHandles(handles, "aPoolName",
NUM_HANDLES) != NS_OK) {
Ns_Set *row;
row = Ns_DbSelect(handles[0], "select * from aTable");
...
} else {
/* handle error condition */
}
char *Ns_DbPoolList(
char *hServer
);
char *pools;
pools = Ns_DbPoolList("serverName");
while (*pools != '\0') {
printf("%s\n", pools);
pools += strlen(pools) + 1;
}
void Ns_DbPoolPutHandle(
Ns_DbHandle *handle
);
Ns_DbHandle *handle;
if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
Ns_Set *row;
row = Ns_DbSelect(handle, "select * from aTable");
...
Ns_DbPoolPutHandle(handle); /* done with handle */
}
Ns_DbHandle *Ns_DbPoolTimedGetHandle(
char *poolname,
int timeout
);
It returns NULL on error or if the attempt times out. Details relating to error conditions are written to the server log. You must request all the database handles you will need for a specific pool with one call to Ns_DbPoolTimedGetHandle (if you need only one handle) or Ns_DbPoolGetTimedMultipleHandles (if you need more than one handle). You must release all your database handles explicitly (with Ns_DbPoolPutHandle) before acquiring more.
int Ns_DbPoolTimedGetMultipleHandles(
Ns_DbHandle **handles,
char *poolname,
int nhandles,
int timeout
);
It returns NS_OK if all requested handles are returned, NS_TIMEOUT if the attempt timed out, or NS_ERROR on an error condition. You must request all the database handles you will need for a specific pool with one call to Ns_DbPoolTimedGetHandle (if you need only one handle) or Ns_DbPoolTimedGetMultipleHandles (if you need more than one handle). You must release all your database handles explicitly (with Ns_DbPoolPutHandle) before acquiring more.
void Ns_DbQuoteValue(
Ns_DString *pds,
char *string
);
int Ns_DbRegisterDriver(
char *hDriver,
Ns_DbProc *procs
);
Ns_Set *Ns_DbSelect(
Ns_DbHandle *handle,
char *sql
);
On error, Ns_DbSelect returns NULL. Detailed error message may have accumulated in an internal buffer in the Ns_DbHandle.
Ns_DbHandle *handle;
if ((handle = Ns_DbPoolGetHandle("aPoolName")) != NULL) {
Ns_Set *row;
row = Ns_DbSelect(handle, "select * from aTable");
if (row == NULL) {
/*... handle select error ...*/
}
while ((status = Ns_DbGetRow(handle, row)) == NS_OK) {
/*... process the row fetched from the database ...*/
}
if (status != NS_END_DATA) {
/*... handle get row error ...*/
}
Ns_DbPoolPutHandle(handle); /* done with handle */
}
void Ns_DbSetException(
Ns_DbHandle *handle,
char *code,
char *msg
);
int Ns_DbSpExec(
Ns_DbHandle *handle
);
Ns_Set * Ns_DbSpGetParams(
Ns_DbHandle *handle
);
int Ns_DbSpReturnCode(
Ns_DbHandle *handle,
char *returnCode,
int bufsize
);
int Ns_DbSpSetParam(
Ns_DbHandle *handle,
char *paramname,
char *paramtype,
char *inout,
char *value
);
int Ns_DbSpStart(
Ns_DbHandle *handle,
char *procname
);