<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >DBD Helper 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="Public Database Query Functions" HREF="driverfuncs-publicdbquery.html"><LINK REL="NEXT" TITLE="GNU Free Documentation License" HREF="copying-fdl.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-publicdbquery.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="copying-fdl.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECTION" ><H1 CLASS="SECTION" ><A NAME="HELPERFUNCS" >3.4. DBD Helper Functions</A ></H1 ><P >libdbi implements a couple of functions which come in handy when implementing database engine drivers. Call them from your driver code if appropriate.</P ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-RESULT-CREATE" >3.4.1. _dbd_result_create</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN680" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_result_t *<B CLASS="FSFUNC" >_dbd_result_create</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, void *<VAR CLASS="PDPARAM" >handle</VAR >, unsigned long long <VAR CLASS="PDPARAM" >numrows_matched</VAR >, unsigned long long <VAR CLASS="PDPARAM" >numrows_affected</VAR >);</CODE ></P ><P ></P ></DIV ><P >Allocates a new dbi_result_t, filling the number of rows matched and affected, storing the database-specific result handle, and allocating room for rows to be stored.</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" >handle</TT >: The database-specific result handle used internally by the driver.</P ><P ><TT CLASS="LITERAL" >numrows_matched</TT >: The number of rows matched by the query.</P ><P ><TT CLASS="LITERAL" >numrows_affected</TT >: The number of rows affected by the query.</P ></DD ><DT >Returns</DT ><DD ><P >A new DBI result object.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-RESULT-SET-NUMFIELDS" >3.4.2. _dbd_result_set_numfields</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN711" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >void <B CLASS="FSFUNC" >_dbd_result_set_numfields</B ></CODE >(dbi_result_t *<VAR CLASS="PDPARAM" >result</VAR >, unsigned int <VAR CLASS="PDPARAM" >numfields</VAR >);</CODE ></P ><P ></P ></DIV ><P >Sets a result's number of fields and allocates memory for field information to be stored.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >result</TT >: The target result.</P ><P ><TT CLASS="LITERAL" >numfields</TT >: The number of fields in the result set.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-RESULT-ADD-FIELD" >3.4.3. _dbd_result_add_field</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN730" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >void <B CLASS="FSFUNC" >_dbd_result_add_field</B ></CODE >(dbi_result_t *<VAR CLASS="PDPARAM" >result</VAR >, unsigned int <VAR CLASS="PDPARAM" >idx</VAR >, char *<VAR CLASS="PDPARAM" >name</VAR >, unsigned short <VAR CLASS="PDPARAM" >type</VAR >, unsigned int <VAR CLASS="PDPARAM" >attribs</VAR >);</CODE ></P ><P ></P ></DIV ><P >Stores information about the target field into the result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >result</TT >: The target result.</P ><P ><TT CLASS="LITERAL" >idx</TT >: The numeric field index.</P ><P ><TT CLASS="LITERAL" >name</TT >: The name of the field.</P ><P ><TT CLASS="LITERAL" >type</TT >: The datatype of the field.</P ><P ><TT CLASS="LITERAL" >attribs</TT >: The attributes of the field.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-ROW-ALLOCATE" >3.4.4. _dbd_row_allocate</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN761" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_row_t *<B CLASS="FSFUNC" >_dbd_row_allocate</B ></CODE >(unsigned int <VAR CLASS="PDPARAM" >numfields</VAR >);</CODE ></P ><P ></P ></DIV ><P >Allocates a new row, ready to be filled with data.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >numfields</TT >: The number of fields in the result set.</P ></DD ><DT >Returns</DT ><DD ><P >A new DBI row, or NULL on error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-ROW-FINALIZE" >3.4.5. _dbd_row_finalize</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN780" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >void <B CLASS="FSFUNC" >_dbd_row_finalize</B ></CODE >(dbi_result_t *<VAR CLASS="PDPARAM" >result</VAR >, dbi_row_t *<VAR CLASS="PDPARAM" >row</VAR >, unsigned long long <VAR CLASS="PDPARAM" >rowidx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Associates and stores the row with the result set, once the row's data has been filled.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >result</TT >: The target result set.</P ><P ><TT CLASS="LITERAL" >row</TT >: The target row object.</P ><P ><TT CLASS="LITERAL" >rowidx</TT >: The index of the row.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-INTERNAL-ERROR-HANDLER" >3.4.6. _dbd_internal_error_handler</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN803" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >void <B CLASS="FSFUNC" >_dbd_internal_error_handler</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >errmsg</VAR >, const int <VAR CLASS="PDPARAM" >errno</VAR >);</CODE ></P ><P ></P ></DIV ><P >Saves error message information. libdbi makes this information available to the software to check the error status after each call to a libdbi API function. If an old error message string exists, it will be freed.</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" >errmsg</TT >: The error message to store. This will be stdup'd by libdbi so it has its own copy. If NULL, libdbi will attempt to provide an appropriate message string.</P ><P ><TT CLASS="LITERAL" >errno</TT >: The error number to store. Use only the predefined (in <TT CLASS="FILENAME" >include/dbi/dbi.h</TT >) constants DBI_ERROR_*. If the error number is DBI_ERROR_DBD, libdbi will replace the error number and message by calling the driver function <CODE CLASS="FUNCTION" >dbd_geterror</CODE > which retrieves the error code and message from the database client library. If errmsg is NULL and errno is any other of the predefined constants, libdbi will provide its own message string.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-RESULT-CREATE-FROM-STRINGARRAY" >3.4.7. _dbd_result_create_from_stringarray</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN828" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_result_t *<B CLASS="FSFUNC" >_dbd_result_create_from_stringarray</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, unsigned long long <VAR CLASS="PDPARAM" >numrows_matched</VAR >, const char **<VAR CLASS="PDPARAM" >stringarray</VAR >);</CODE ></P ><P ></P ></DIV ><P >Creates a result object from an array of strings which contains the data of a single field for each row.</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" >numrows_matched</TT >: The number of rows contained in the <CODE CLASS="PARAMETER" >stringarray</CODE >.</P ><P ><TT CLASS="LITERAL" >stringarray</TT >: A pointer to an array of strings with <CODE CLASS="PARAMETER" >numrows_matched</CODE > members.</P ></DD ><DT ><EM >Returns</EM ></DT ><DD ><P >A result object, or NULL if there is an error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-REGISTER-DRIVER-CAP" >3.4.8. _dbd_register_driver_cap</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN858" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >void <B CLASS="FSFUNC" >_dbd_register_driver_cap</B ></CODE >(dbi_driver_t *<VAR CLASS="PDPARAM" >driver</VAR >, const char *<VAR CLASS="PDPARAM" >capname</VAR >, int <VAR CLASS="PDPARAM" >value</VAR >);</CODE ></P ><P ></P ></DIV ><P >Adds a key-value pair to the list of driver capabilities.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >driver</TT >: The target driver.</P ><P ><TT CLASS="LITERAL" >capname</TT >: The key.</P ><P ><TT CLASS="LITERAL" >value</TT >: The value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-REGISTER-CONN-CAP" >3.4.9. _dbd_register_conn_cap</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN881" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >void <B CLASS="FSFUNC" >_dbd_register_conn_cap</B ></CODE >(dbi_conn_t *<VAR CLASS="PDPARAM" >conn</VAR >, const char *<VAR CLASS="PDPARAM" >capname</VAR >, int <VAR CLASS="PDPARAM" >value</VAR >);</CODE ></P ><P ></P ></DIV ><P >Adds a key-value pair to the list of connection capabilities.</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" >capname</TT >: The key.</P ><P ><TT CLASS="LITERAL" >value</TT >: The value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-PARSE-DATETIME" >3.4.10. _dbd_parse_datetime</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN904" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >time_t <B CLASS="FSFUNC" >_dbd_parse_datetime</B ></CODE >(const char *<VAR CLASS="PDPARAM" >raw</VAR >, unsigned int <VAR CLASS="PDPARAM" >attribs</VAR >);</CODE ></P ><P ></P ></DIV ><P >Parses the input time, date, or datetime string and converts the value into a time_t value.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >raw</TT >: A zero-terminated string containing a time, date, or datetime value. Accepted formats are YYYY-MM-DD for date values, HH:MM:SS for time values, and YYYY-MM-DD HH:MM:SS for datetime values. The separators must be present, but can be any character.</P ><P ><TT CLASS="LITERAL" >attribs</TT >: The field attributes of raw.</P ></DD ><DT ><EM >Returns</EM ></DT ><DD ><P >The numeric equivalent of the input based on UTC. In case of an error, this function returns the start of the Unix epoch.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-ESCAPE-CHARS" >3.4.11. _dbd_escape_chars</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN928" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >_dbd_escape_chars</B ></CODE >(char *<VAR CLASS="PDPARAM" >dest</VAR >, const char *<VAR CLASS="PDPARAM" >orig</VAR >, size_t <VAR CLASS="PDPARAM" >orig_size</VAR >, const char *<VAR CLASS="PDPARAM" >toescape</VAR >);</CODE ></P ><P ></P ></DIV ><P >Escapes the characters contained in <CODE CLASS="PARAMETER" >toescape</CODE > in the string <CODE CLASS="PARAMETER" >orig</CODE > and puts the result into the allocated memory pointed to by <CODE CLASS="PARAMETER" >dest</CODE >. The size of <CODE CLASS="PARAMETER" >dest</CODE > must be at least (<CODE CLASS="PARAMETER" >orig_size</CODE >*2)+5. The characters are escaped by preceding them with a backslash.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >dest</TT >: Pointer to allocated memory which will receive the escaped string.</P ><P ><TT CLASS="LITERAL" >orig</TT >: The string to escape.</P ><P ><TT CLASS="LITERAL" >orig_size</TT >: The length of the string to escape.</P ><P ><TT CLASS="LITERAL" >toescape</TT >: A string containing all characters that need escaping.</P ></DD ><DT ><EM >Returns</EM ></DT ><DD ><P >The length, in bytes, of the escaped string.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-ENCODE-BINARY" >3.4.12. _dbd_encode_binary</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN965" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >_dbd_encode_binary</B ></CODE >(const unsigned char *<VAR CLASS="PDPARAM" >in</VAR >, size_t <VAR CLASS="PDPARAM" >n</VAR >, unsigned char *<VAR CLASS="PDPARAM" >out</VAR >);</CODE ></P ><P ></P ></DIV ><P >Encodes a binary string as a zero-terminated string which can be safely included in a SQL query. Use <A HREF="helperfuncs.html#INTERNAL-DBD-DECODE-BINARY" >_dbd_decode_binary</A > to decode the string again.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >in</TT >: Pointer to the binary string.</P ><P ><TT CLASS="LITERAL" >n</TT >: Length, in bytes, of the binary string <CODE CLASS="PARAMETER" >in</CODE >.</P ><P ><TT CLASS="LITERAL" >out</TT >: Pointer to allocated memory which will receive the escaped string. The size must be at least 2 +(257*<CODE CLASS="PARAMETER" >n</CODE >)/254 bytes.</P ></DD ><DT ><EM >Returns</EM ></DT ><DD ><P >The length, in bytes, of the escaped string.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="INTERNAL-DBD-DECODE-BINARY" >3.4.13. _dbd_decode_binary</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN996" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >_dbd_decode_binary</B ></CODE >(const unsigned char *<VAR CLASS="PDPARAM" >in</VAR >, unsigned char *<VAR CLASS="PDPARAM" >out</VAR >);</CODE ></P ><P ></P ></DIV ><P >Decodes a zero-terminated string with escaped characters as created by <A HREF="helperfuncs.html#INTERNAL-DBD-ENCODE-BINARY" >_dbd_encode_binary</A >.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >in</TT >: Pointer to the input string.</P ><P ><TT CLASS="LITERAL" >out</TT >: Pointer to allocated memory which will receive the unescaped string. The output string is always shorter than the input string, i.e. if the size of <CODE CLASS="PARAMETER" >out</CODE > is the same as the size of <CODE CLASS="PARAMETER" >in</CODE >, you're on the safe side. The implementation allows to decode the string in place, i.e. <CODE CLASS="PARAMETER" >out</CODE > may be the same as <CODE CLASS="PARAMETER" >in</CODE >.</P ></DD ><DT ><EM >Returns</EM ></DT ><DD ><P >The length, in bytes, of the unescaped binary string.</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-publicdbquery.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="copying-fdl.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Public 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" >GNU Free Documentation License</TD ></TR ></TABLE ></DIV ></BODY ></HTML >