<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Public Database Query Functions</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REL="HOME" TITLE="Database Independent Abstraction Layer for C" HREF="index.html"><LINK REL="UP" TITLE="Driver Functions" HREF="driverfuncs.html"><LINK REL="PREVIOUS" TITLE="Internal Database Query Functions" HREF="driverfuncs-dbquery.html"><LINK REL="NEXT" TITLE="DBD Helper Functions" HREF="helperfuncs.html"></HEAD ><BODY CLASS="SECTION" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Database Independent Abstraction Layer for C: libdbi Driver Author's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="driverfuncs-dbquery.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 3. Driver Functions</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="helperfuncs.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECTION" ><H1 CLASS="SECTION" ><A NAME="DRIVERFUNCS-PUBLICDBQUERY" >3.3. Public Database Query Functions</A ></H1 ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-GET-ENCODING" >3.3.1. dbd_get_encoding</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN303" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >const char *<B CLASS="FSFUNC" >dbd_get_encoding</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the character encoding used by the current connection.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ></DD ><DT >Returns</DT ><DD ><P >A zero-terminated string containing the IANA name of the character encoding.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-ENCODING-TO-IANA" >3.3.2. dbd_encoding_to_iana</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN322" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >const char *<B CLASS="FSFUNC" >dbd_encoding_to_iana</B ></CODE >(const char *<VAR CLASS="PDPARAM" >db_encoding</VAR >);</CODE ></P ><P ></P ></DIV ><P >Converts the database-engine-specific name of a character encoding to the corresponging IANA name.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >db_encoding</TT >: A pointer to a string containing the character encoding name.</P ></DD ><DT >Returns</DT ><DD ><P >A zero-terminated string containing the IANA name of the character encoding. If there is no equivalent IANA name, the original string will be returned.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-ENCODING-FROM-IANA" >3.3.3. dbd_encoding_from_iana</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN341" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >const char *<B CLASS="FSFUNC" >dbd_encoding_from_iana</B ></CODE >(const char *<VAR CLASS="PDPARAM" >iana_encoding</VAR >);</CODE ></P ><P ></P ></DIV ><P >Converts the IANA name of a character encoding to the corresponging database-engine-specific name.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >iana_encoding</TT >: A pointer to a string containing the character encoding name.</P ></DD ><DT >Returns</DT ><DD ><P >A zero-terminated string containing the database-engine-specific name of the character encoding. If there is no equivalent IANA name, the original string will be returned.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-GET-ENGINE-VERSION" >3.3.4. dbd_get_engine_version</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN360" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >char *<B CLASS="FSFUNC" >dbd_get_engine_version</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, char *<VAR CLASS="PDPARAM" >versionstring</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the version string of the database engine that serves the current connection.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The current connection.</P ><P ><TT CLASS="LITERAL" >versionstring</TT >: A pointer to a string that can hold at least VERSIONSTRING_LENGTH bytes, including the trailing NULL byte. The function will write the version string to this buffer.</P ></DD ><DT >Returns</DT ><DD ><P ><CODE CLASS="PARAMETER" >versionstring</CODE > which now contains a zero-terminated string representing the database engine version. This string contains only digits and periods. Returns an empty string in case of an error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-LIST-DBS" >3.3.5. dbd_list_dbs</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN384" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_result_t *<B CLASS="FSFUNC" >dbd_list_dbs</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >pattern</VAR >);</CODE ></P ><P ></P ></DIV ><P >Performs a query that retrieves the list of databases, with the database name as the first column in the result set. If <CODE CLASS="PARAMETER" >pattern</CODE > is non-NULL, only databases whose name match <CODE CLASS="PARAMETER" >pattern</CODE > are listed.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >pattern</TT >: A SQL regular expression that limits the search, or NULL to list all tables.</P ></DD ><DT >Returns</DT ><DD ><P >A DBI result object, or NULL if an error occurs.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-LIST-TABLES" >3.3.6. dbd_list_tables</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN409" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_result_t *<B CLASS="FSFUNC" >dbd_list_tables</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >db</VAR >, const char *<VAR CLASS="PDPARAM" >pattern</VAR >);</CODE ></P ><P ></P ></DIV ><P >Performs a query that retrieves the list of tables in the specified database, with the table name as the first column in the result set. If <CODE CLASS="PARAMETER" >pattern</CODE > is non-NULL, lists only the tables that match <CODE CLASS="PARAMETER" >pattern</CODE >.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >db</TT >: The name of the database where tables should be looked for.</P ><P ><TT CLASS="LITERAL" >pattern</TT >: A SQL regular expression that limits the search, or NULL to list all tables.</P ></DD ><DT >Returns</DT ><DD ><P >A DBI result object, or NULL if an error occurs.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-QUOTE-STRING" >3.3.7. dbd_quote_string</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN438" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbd_quote_string</B ></CODE >(dbi_driver_t *<VAR CLASS="PDPARAM" >driver</VAR >, const char *<VAR CLASS="PDPARAM" >orig</VAR >, char *<VAR CLASS="PDPARAM" >dest</VAR >);</CODE ></P ><P ></P ></DIV ><P >Given a string, wrap quotes around that string and escape any characters that the database server needs escaped.</P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >The use of this function in user programs is deprecated, but drivers must still implement it at the moment. If the quoting and escaping does not depend on the connection parameters, it is perfectly legal to let your implementation of <A HREF="driverfuncs-publicdbquery.html#DBD-CONN-QUOTE-STRING" >dbd_conn_quote_string</A > call this function (it is not possible to do it the other way). libdbi makes sure that both <CODE CLASS="PARAMETER" >orig</CODE > and <CODE CLASS="PARAMETER" >dest</CODE > are non-NULL before calling this function.</P ></BLOCKQUOTE ></DIV ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >driver</TT >: A pointer to the driver itself, which may be useful in weird cases.</P ><P ><TT CLASS="LITERAL" >orig</TT >: The string to quote and escape.</P ><P ><TT CLASS="LITERAL" >dest</TT >: The destination for the new string, which is already allocated as (strlen(orig)*2)+4+1. In the worst case, each character will need to be escaped, with two quote characters at both the beginning and end of the string, plus one for the terminating NULL.</P ></DD ><DT >Returns</DT ><DD ><P >The length of the new string.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-CONN-QUOTE-STRING" >3.3.8. dbd_conn_quote_string</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN470" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbd_conn_quote_string</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >orig</VAR >, char *<VAR CLASS="PDPARAM" >dest</VAR >);</CODE ></P ><P ></P ></DIV ><P >Given a string, wrap quotes around that string and escape any characters that the database server needs escaped.</P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >The use of this function in user programs is preferred over <A HREF="driverfuncs-publicdbquery.html#DBD-QUOTE-STRING" >dbd_quote_string</A >. If the quoting and escaping does not depend on the connection parameters, it is perfectly legal to let your implementation of this function call <A HREF="driverfuncs-publicdbquery.html#DBD-QUOTE-STRING" >dbd_quote_string</A >. libdbi makes sure that both <CODE CLASS="PARAMETER" >orig</CODE > and <CODE CLASS="PARAMETER" >dest</CODE > are non-NULL before calling this function.</P ></BLOCKQUOTE ></DIV ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: A pointer to the current connection.</P ><P ><TT CLASS="LITERAL" >orig</TT >: The string to quote and escape.</P ><P ><TT CLASS="LITERAL" >dest</TT >: The destination for the new string, which is already allocated as (strlen(orig)*2)+4+1. In the worst case, each character will need to be escaped, with two quote characters at both the beginning and end of the string, plus one for the terminating NULL.</P ></DD ><DT >Returns</DT ><DD ><P >The length of the new string.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-QUOTE-BINARY" >3.3.9. dbd_quote_binary</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN503" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbd_quote_binary</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >orig</VAR >, size_t <VAR CLASS="PDPARAM" >from_length</VAR >, char **<VAR CLASS="PDPARAM" >dest</VAR >);</CODE ></P ><P ></P ></DIV ><P >Given a binary string (which may contain NULL bytes and other non-printable characters), wrap quotes around that string and escape any characters that the database server needs escaped. If the function returns an error, *<CODE CLASS="PARAMETER" >dest</CODE > is not a valid pointer to a string.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: A pointer to the current connection.</P ><P ><TT CLASS="LITERAL" >orig</TT >: The string to quote and escape.</P ><P ><TT CLASS="LITERAL" >from_length</TT >: The length, in bytes, of the binary string.</P ><P ><TT CLASS="LITERAL" >dest</TT >: A pointer to the destination of the new zero-terminated string. The function allocates the required memory as required and updates the pointer that <CODE CLASS="PARAMETER" >dest</CODE > points to accordingly.</P ></DD ><DT >Returns</DT ><DD ><P >The length of the new string, or DBI_LENGTH_ERROR in case of an error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-QUERY" >3.3.10. dbd_query</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN536" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_result_t *<B CLASS="FSFUNC" >dbd_query</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >statement</VAR >);</CODE ></P ><P ></P ></DIV ><P >Performs a query and keeps track of meta-information about the query. Also see the <A HREF="helperfuncs.html#INTERNAL-DBD-RESULT-CREATE" >_dbd_result_create</A > helper function.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >statement</TT >: The zero-terminated query string to execute.</P ></DD ><DT >Returns</DT ><DD ><P >A DBI result object, or NULL on error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-QUERY-NULL" >3.3.11. dbd_query_null</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN560" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_result_t *<B CLASS="FSFUNC" >dbd_query_null</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const unsigned char *<VAR CLASS="PDPARAM" >statement</VAR >, size_t <VAR CLASS="PDPARAM" >st_length</VAR >);</CODE ></P ><P ></P ></DIV ><P >Performs a query using a binary query string and keeps track of meta-information about the query. Also see the <A HREF="helperfuncs.html#INTERNAL-DBD-RESULT-CREATE" >_dbd_result_create</A > helper function.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >statement</TT >: The query string to execute, which may contain NULL bytes and other non-printable characters.</P ><P ><TT CLASS="LITERAL" >st_length</TT >: The length of the binary query string.</P ></DD ><DT >Returns</DT ><DD ><P >A DBI result object, or NULL on error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-SELECT-DB" >3.3.12. dbd_select_db</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN588" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >const char *<B CLASS="FSFUNC" >dbd_select_db</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char* <VAR CLASS="PDPARAM" >db</VAR >);</CODE ></P ><P ></P ></DIV ><P >Selects a new database on the server.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >db</TT >: The name of the database to switch to.</P ></DD ><DT >Returns</DT ><DD ><P >The database name on success, NULL on error, or an empty string if the operation is not supported by the database server.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-GET-SEQ-LAST" >3.3.13. dbd_get_seq_last</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN611" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned long long <B CLASS="FSFUNC" >dbd_get_seq_last</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >sequence</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the row ID generated by the last <B CLASS="COMMAND" >INSERT</B > command.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >sequence</TT >: The name of the sequence if the database engine requires this, or NULL if it is not required.</P ></DD ><DT >Returns</DT ><DD ><P >The row ID if successful, otherwise 0.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-GET-SEQ-NEXT" >3.3.14. dbd_get_seq_next</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN635" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned long long <B CLASS="FSFUNC" >dbd_get_seq_next</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >sequence</VAR >);</CODE ></P ><P ></P ></DIV ><P >Increments the sequence counter by the preset increment, and returns the resulting row ID.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ><P ><TT CLASS="LITERAL" >sequence</TT >: The name of the sequence if the database engine requires this, or NULL if it is not required.</P ></DD ><DT >Returns</DT ><DD ><P >The row ID if successful, otherwise 0. Also return 0 if the database engine does not implement this feature.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBD-PING" >3.3.15. dbd_ping</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN658" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbd_ping</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >);</CODE ></P ><P ></P ></DIV ><P >Checks whether the database connection is still alive.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >conn</TT >: The target connection.</P ></DD ><DT >Returns</DT ><DD ><P >1 if the connection is alive, otherwise 0. This function may be implemented such that it automatically attempts to reconnect if the connection went down. If the reconnect is successful, the function should also return 1.</P ></DD ></DL ></DIV ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="driverfuncs-dbquery.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="helperfuncs.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Internal Database Query Functions</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="driverfuncs.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >DBD Helper Functions</TD ></TR ></TABLE ></DIV ></BODY ></HTML >