/usr/share/doc/libdbi-doc/driver-guide/helperfuncs.html

<!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="AEN729"
></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="AEN760"
></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="AEN779"
></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="AEN810"
></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="AEN829"
></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="AEN852"
></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="AEN877"
></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="AEN907"
></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="AEN930"
></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="AEN953"
></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="AEN977"
></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="AEN1014"
></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="AEN1045"
></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
>
libdbi-doc 0.9.0-5 / usr / share / doc / libdbi-doc / driver-guide / helperfuncs.html
