Retrieving Field Meta-data

Database Independent Abstraction Layer for C: libdbi Programmer's Guide
Prev | Chapter 4. libdbi API Reference | Next

# 4.7. Retrieving Field Meta-data

## 4.7.1. dbi_result_get_field_length

``size_t dbi_result_get_field_length`(dbi_result Result, const char *const char *fieldname);`

Returns the length of the value stored in the specified field which contains a string or a binary string.

Arguments

  `Result`: The target query result.

  `fieldname`: The name of the target field.

Returns

  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 error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.

## 4.7.2. dbi_result_get_field_length_idx

``size_t dbi_result_get_field_length_idx`(dbi_result Result, unsigned int idx);`

Returns the length of the value stored in the specified field which contains a string or a binary string.

Arguments

  `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

Returns

  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 error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.

## 4.7.3. dbi_result_get_field_size

``size_t dbi_result_get_field_size`(dbi_result Result, const char *fieldname);`

Returns the size in bytes of the value stored in the specified field.

> Note: This function is deprecated. Use dbi_result_get_field_length instead.

## 4.7.4. dbi_result_get_field_size_idx

``size_t dbi_result_get_field_size_idx`(dbi_result Result, unsigned long idx);`

Returns the size in bytes of the value stored in the specified field.

> Note: This function is deprecated. Use dbi_result_get_field_length_idx instead.

## 4.7.5. dbi_result_get_field_idx

``unsigned int dbi_result_get_field_idx`(dbi_result Result, const char *fieldname);`

Given a field's name, return that field's numeric index.

Arguments

  `Result`: The target query result.

  `fieldname`: The name of the target field.

Returns

  The index (starting at 1) of the target field, or 0 in case of an error. In that case, the error number is DBI_ERROR_BADPTR.

## 4.7.6. dbi_result_get_field_name

``const char *dbi_result_get_field_name`(dbi_result Result, unsigned int idx);`

Given a field's numeric index, return that field's name.

Arguments

  `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

Returns

  The target field's name, or NULL in case of an error. In that case the error number is one of DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, or DBI_ERROR_BADIDX.

## 4.7.7. dbi_result_get_numfields

``unsigned int dbi_result_get_numfields`(dbi_result Result);`

Returns the number of fields in the query result.

Arguments

  `Result`: The target query result.

Returns

  The number of fields in the query result, or DBI_FIELD_ERROR in case of an error.

## 4.7.8. dbi_result_get_field_type

``unsigned short dbi_result_get_field_type`(dbi_result Result, const char *fieldname);`

Returns the target field's data type. The constants returned by this function are defined in dbi.h with the prefix "DBI_TYPE_".

Arguments

  `Result`: The target query result.

  `fieldname`: The target field's name.

Returns

  The target field's data type, or DBI_TYPE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.9. dbi_result_get_field_type_idx

``unsigned short dbi_result_get_field_type_idx`(dbi_result Result, unsigned int idx);`

Returns the target field's data type. The constants returned by this function are defined in dbi.h with the prefix "DBI_TYPE_".

Arguments

  `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

Returns

  The target field's data type, or DBI_TYPE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.10. dbi_result_get_field_attrib

``unsigned int dbi_result_get_field_attrib`(dbi_result Result, const char *fieldname, unsigned int attribmin, unsigned int attribmax);`

Returns the target field's data type attributes in the specified range. The constants returned by this function are defined in `include/dbi/dbi.h` with the prefix "DBI_", followed by the name of the field's datatype.

Arguments

  `Result`: The target query result.

  `fieldname`: The target field's name.

  `attribmin`: The first attribute value in the range of attributes to extract.

  `attribmax`: 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.

Returns

  The target field's requested attribute range, or DBI_ATTRIBUTE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.11. dbi_result_get_field_attrib_idx

``unsigned int dbi_result_get_field_attrib_idx`(dbi_result Result, unsigned int idx, unsigned int attribmin, unsigned int attribmax);`

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.

Arguments

  `Result`: The target query result.

  `idx`: The index of the target field (starting at 1).

  `attribmin`: The first attribute value in the range of attributes to extract.

  `attribmax`: 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.

Returns

  The target field's requested attribute range, or DBI_ATTRIBUTE_ERROR in case of an error. In the latter case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.12. dbi_result_get_field_attribs

``unsigned int dbi_result_get_field_attribs`(dbi_result Result, const char *fieldname);`

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.

Arguments

  `Result`: The target query result.

  `fieldname`: The target field's name.

Returns

  The target field's attributes, or DBI_ATTRIBUTE_ERROR in case of an error. In case of an error the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.13. dbi_result_get_field_attribs_idx

``unsigned int dbi_result_get_field_attribs_idx`(dbi_result Result, unsigned int fieldidx);`

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.

Arguments

  `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

  The target field's attributes, or DBI_ATTRIBUTE_ERROR in case of an error. In that case the error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.14. dbi_result_field_is_null

``int dbi_result_field_is_null`(dbi_result Result, const char *fieldname);`

Determines whether the indicated field contains a NULL value.

Arguments

  `Result`: The target query result.

  `fieldname`: The name of the target field.

Returns

  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 error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

## 4.7.15. dbi_result_field_is_null_idx

``int dbi_result_field_is_null_idx`(dbi_result Result, unsigned int fieldidx);`

Determines whether the indicated field contains a NULL value.

Arguments

  `Result`: The target query result.

  `fieldidx`: The index of the target field (starting at 1).

Returns

  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 error number is DBI_ERROR_BADPTR, DBI_ERROR_BADOBJECT, DBI_ERROR_BADIDX, or DBI_ERROR_BADNAME.

Prev | Home | Next
Managing Results | Up | Retrieving Field Data by Name