<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Retrieving Field Meta-data</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="libdbi API Reference" HREF="reference.html"><LINK REL="PREVIOUS" TITLE="Managing Results" HREF="reference-results.html"><LINK REL="NEXT" TITLE="Retrieving Field Data by Name" HREF="reference-field.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 Programmer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="reference-results.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 7. libdbi API Reference</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="reference-field.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECTION" ><H1 CLASS="SECTION" ><A NAME="REFERENCE-FIELD-META" >7.7. Retrieving Field Meta-data</A ></H1 ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-LENGTH" >7.7.1. dbi_result_get_field_length</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2467" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbi_result_get_field_length</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >const char *fieldname</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the length of the value stored in the specified field which contains a string or a binary string.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldname</TT >: The name of the target field.</P ></DD ><DT >Returns</DT ><DD ><P >The length in bytes of the target field data, excluding the terminating zero byte, or DBI_LENGTH_ERROR in case of an error. The return value is 0 for field types other than string or binary string. In case of an error the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-LENGTH-IDX" >7.7.2. dbi_result_get_field_length_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2491" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbi_result_get_field_length_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned int <VAR CLASS="PDPARAM" >idx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the length of the value stored in the specified field which contains a string or a binary string.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >idx</TT >: The index of the target field (starting at 1).</P ></DD ><DT >Returns</DT ><DD ><P >The length in bytes of the target field data, excluding the terminating zero byte, or DBI_LENGTH_ERROR in case of an error. The return value is 0 for field types other than string or binary string. In case of an error the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-SIZE" >7.7.3. dbi_result_get_field_size</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2515" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbi_result_get_field_size</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >fieldname</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the size in bytes of the value stored in the specified field.</P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >This function is deprecated. Use <A HREF="reference-field-meta.html#DBI-RESULT-GET-FIELD-LENGTH" >dbi_result_get_field_length</A > instead.</P ></BLOCKQUOTE ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-SIZE-IDX" >7.7.4. dbi_result_get_field_size_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2529" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >size_t <B CLASS="FSFUNC" >dbi_result_get_field_size_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned long <VAR CLASS="PDPARAM" >idx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the size in bytes of the value stored in the specified field.</P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >This function is deprecated. Use <A HREF="reference-field-meta.html#DBI-RESULT-GET-FIELD-LENGTH-IDX" >dbi_result_get_field_length_idx</A > instead.</P ></BLOCKQUOTE ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-IDX" >7.7.5. dbi_result_get_field_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2543" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned int <B CLASS="FSFUNC" >dbi_result_get_field_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >fieldname</VAR >);</CODE ></P ><P ></P ></DIV ><P >Given a field's name, return that field's numeric index.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldname</TT >: The name of the target field.</P ></DD ><DT >Returns</DT ><DD ><P >The index (starting at 1) of the target field, or 0 in case of an error. In that case, the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-NAME" >7.7.6. dbi_result_get_field_name</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2567" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >const char *<B CLASS="FSFUNC" >dbi_result_get_field_name</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned int <VAR CLASS="PDPARAM" >idx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Given a field's numeric index, return that field's name.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >idx</TT >: The index of the target field (starting at 1).</P ></DD ><DT >Returns</DT ><DD ><P >The target field's name, or NULL in case of an error. In that case the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-NUMFIELDS" >7.7.7. dbi_result_get_numfields</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2591" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned int <B CLASS="FSFUNC" >dbi_result_get_numfields</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the number of fields in the query result.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >The number of fields in the query result, or DBI_FIELD_ERROR in case of an error.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-TYPE" >7.7.8. dbi_result_get_field_type</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2610" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned short <B CLASS="FSFUNC" >dbi_result_get_field_type</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >fieldname</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the target field's data type. The constants returned by this function are defined in dbi.h with the prefix "DBI_TYPE_".</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldname</TT >: The target field's name.</P ></DD ><DT >Returns</DT ><DD ><P >The target field's data type, or DBI_TYPE_ERROR in case of an error. In the latter case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-TYPE-IDX" >7.7.9. dbi_result_get_field_type_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2634" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned short <B CLASS="FSFUNC" >dbi_result_get_field_type_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned int <VAR CLASS="PDPARAM" >idx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the target field's data type. The constants returned by this function are defined in dbi.h with the prefix "DBI_TYPE_".</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >idx</TT >: The index of the target field (starting at 1).</P ></DD ><DT >Returns</DT ><DD ><P >The target field's data type, or DBI_TYPE_ERROR in case of an error. In the latter case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-ATTRIB" >7.7.10. dbi_result_get_field_attrib</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2658" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned int <B CLASS="FSFUNC" >dbi_result_get_field_attrib</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >fieldname</VAR >, unsigned int <VAR CLASS="PDPARAM" >attribmin</VAR >, unsigned int <VAR CLASS="PDPARAM" >attribmax</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the target field's data type attributes in the specified range. The constants returned by this function are defined in <TT CLASS="FILENAME" >include/dbi/dbi.h</TT > with the prefix "DBI_", followed by the name of the field's datatype.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldname</TT >: The target field's name.</P ><P ><TT CLASS="LITERAL" >attribmin</TT >: The first attribute value in the range of attributes to extract.</P ><P ><TT CLASS="LITERAL" >attribmax</TT >: The last attribute value in the range of attributes to extract. This may be the same as attribmin if you are only trying to extract a single attribute value.</P ></DD ><DT >Returns</DT ><DD ><P >The target field's requested attribute range, or DBI_ATTRIBUTE_ERROR in case of an error. In the latter case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-ATTRIB-IDX" >7.7.11. dbi_result_get_field_attrib_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2691" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned int <B CLASS="FSFUNC" >dbi_result_get_field_attrib_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned int <VAR CLASS="PDPARAM" >idx</VAR >, unsigned int <VAR CLASS="PDPARAM" >attribmin</VAR >, unsigned int <VAR CLASS="PDPARAM" >attribmax</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the target field's data type attributes in the specified range. The constants returned by this function are defined in dbi.h with the prefix "DBI_", followed by the name of the field's datatype.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >idx</TT >: The index of the target field (starting at 1).</P ><P ><TT CLASS="LITERAL" >attribmin</TT >: The first attribute value in the range of attributes to extract.</P ><P ><TT CLASS="LITERAL" >attribmax</TT >: The last attribute value in the range of attributes to extract. This may be the same as attribmin if you are only trying to extract a single attribute value.</P ></DD ><DT >Returns</DT ><DD ><P >The target field's requested attribute range, or DBI_ATTRIBUTE_ERROR in case of an error. In the latter case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-ATTRIBS" >7.7.12. dbi_result_get_field_attribs</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2723" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned int <B CLASS="FSFUNC" >dbi_result_get_field_attribs</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >fieldname</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the target field's data type attributes. The constants returned by this function are defined in dbi.h with the prefix "DBI_", followed by the name of the field's datatype.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldname</TT >: The target field's name.</P ></DD ><DT >Returns</DT ><DD ><P >The target field's attributes, or DBI_ATTRIBUTE_ERROR in case of an error. In case of an error the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-FIELD-ATTRIBS-IDX" >7.7.13. dbi_result_get_field_attribs_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2747" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned int <B CLASS="FSFUNC" >dbi_result_get_field_attribs_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned int <VAR CLASS="PDPARAM" >fieldidx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the target field's data type attributes. The constants returned by this function are defined in dbi.h with the prefix "DBI_", followed by the name of the field's datatype.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldidx</TT >: The index of the target field (starting at 1).</P ></DD ><DT >Returns</DT ><DD ><P >The target field's attributes, or DBI_ATTRIBUTE_ERROR in case of an error. In that case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-FIELD-IS-NULL" >7.7.14. dbi_result_field_is_null</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2771" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_field_is_null</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, const char *<VAR CLASS="PDPARAM" >fieldname</VAR >);</CODE ></P ><P ></P ></DIV ><P >Determines whether the indicated field contains a NULL value.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldname</TT >: The name of the target field.</P ></DD ><DT >Returns</DT ><DD ><P >1 if the field contains a NULL value, otherwise 0, or DBI_FIELD_FLAG_ERROR in case of an error. In the latter case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-FIELD-IS-NULL-IDX" >7.7.15. dbi_result_field_is_null_idx</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2795" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_field_is_null_idx</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned int <VAR CLASS="PDPARAM" >fieldidx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Determines whether the indicated field contains a NULL value.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >fieldidx</TT >: The index of the target field (starting at 1).</P ></DD ><DT >Returns</DT ><DD ><P >1 if the field contains a NULL value, otherwise 0, or DBI_FIELD_FLAG_ERROR in case of an error. In the latter case the <A HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.</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="reference-results.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="reference-field.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Managing Results</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="reference.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Retrieving Field Data by Name</TD ></TR ></TABLE ></DIV ></BODY ></HTML >