Google

NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.77">

3.5. Retrieving field data

3.5.1. dbi_result_get_field_size

unsigned int dbi_result_get_field_size(dbi_result Result, const char *fieldname)

Returns the size in bytes of the value stored in the specified field. This is especially useful for string and binary data fields, which may have a dynamic size.

Arguments

Result: The target query result.

fieldname: The name of the target field.

Returns

The size in bytes of the target field data.

3.5.2. dbi_result_get_field_size_idx

unsigned int dbi_result_get_field_size_idx(dbi_result Result, unsigned int idx)

Returns the size in bytes of the value stored in the specified field. This is especially useful for string and binary data fields, which may have a dynamic size.

Arguments

Result: The target query result.

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

Returns

The size in bytes of the target field data.

3.5.3. dbi_result_get_field_length

unsigned int dbi_result_get_field_length(dbi_result Result, const char *fieldname)

Returns the length in bytes of the value stored in the specified field. This is always one less than the size, and is probably only useful for fields containing strings.

Arguments

Result: The target query result.

fieldname: The name of the target field.

Returns

The length in bytes of the target field data.

3.5.4. dbi_result_get_field_length_idx

unsigned int dbi_result_get_field_length_idx(dbi_result Result, unsigned int idx)

Returns the length in bytes of the value stored in the specified field. This is always one less than the size, and is probably only useful for fields containing strings.

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.

3.5.5. dbi_result_get_field_idx

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.

3.5.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.

3.5.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.

3.5.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.

3.5.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.

3.5.10. dbi_result_get_field_attrib

unsigned long dbi_result_get_field_attrib(dbi_result Result, const char *fieldname, unsigned long attribmin, unsigned long 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.

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.

3.5.11. dbi_result_get_field_attrib_idx

unsigned long dbi_result_get_field_attrib_idx(dbi_result Result, unsigned int idx, unsigned long attribmin, unsigned long 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.

3.5.12. dbi_result_get_field_attribs

unsigned long 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.

3.5.13. dbi_result_get_field_attribs_idx

unsigned long dbi_result_get_field_attribs_idx(dbi_result Result, unsigned int idx)

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.

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

Returns

The target field's attributes.

3.5.14. dbi_result_get_fields

int dbi_result_get_fields(dbi_result Result, const char *format, ...)

Fetch multiple fields from the current result set, using a printf-like syntax. The formatter string specified field names and types, and each field's associated destination variable is passed as an argument following the format string. Fields in the formatter string are separated by spaces, and follow the format "a.%b", where "a" is the name of the field, and "b" is the field type specifier. Make sure you pass the destination variables' memory addresses by prepending the & operator to each variable's name.

Field type specifiers:

  • %c / %uc: A signed/unsigned character

  • %h / %uh: A signed/unsigned short integer

  • %l / %ul: A signed/unsigned long integer

  • %i / %ui: A signed/unsigned long integer

  • %L / %uL: A signed/unsigned long long integer

  • %f: A floating point number

  • %d: A double-precision number

  • %s: A read-only string

  • %S: A local copy of a string (must be freed by program)

  • %b: A read-only pointer to binary data

  • %B: A local copy of binary data (must be freed by program)

  • %t: A read-only string representing a SET

  • %e: A read-only string representing an ENUM

  • %m: A time_t value representing a DATE and/or TIME

Example usage: dbi_result_get_fields(result, "idnum.%ul lastname.%s", &id_number, &name)

Arguments

Result: The target query result.

format: The field format string as described above.

ARG: (...) Pointers to the destination variables corresponding with each field in the format string.

Returns

The number of fields fetched, or -1 if there was an error. If an invalid field name was specified it will not cause -1 to be returned, and the other fetched fields will work as usual.

3.5.15. dbi_result_bind_fields

int dbi_result_bind_fields(dbi_result Result, const char *format, ...)

Bind multiple fields in the current result set, using a printf-like syntax. See dbi_result_get_fields for a detailed explanation of the syntax.

Arguments

Result: The target query result.

format: The field format string as described above.

ARG: (...) Pointers to the destination variables corresponding with each field in the format string.

Returns

The number of field binding set up, or -1 if there was an error.

3.5.16. dbi_result_get_char

signed char dbi_result_get_char(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a character.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.17. dbi_result_get_uchar

unsigned char dbi_result_get_uchar(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains an unsigned character.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.18. dbi_result_get_short

short dbi_result_get_short(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a short integer.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.19. dbi_result_get_ushort

unsigned short dbi_result_get_ushort(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains an unsigned short integer.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.20. dbi_result_get_long

long dbi_result_get_long(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.21. dbi_result_get_ulong

unsigned long dbi_result_get_ulong(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains an unsigned long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.22. dbi_result_get_longlong

long long dbi_result_get_longlong(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a long long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.23. dbi_result_get_ulonglong

unsigned long long dbi_result_get_ulonglong(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains an unsigned long long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.24. dbi_result_get_float

float dbi_result_get_float(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a floating-point number.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.25. dbi_result_get_double

double dbi_result_get_double(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a double-precision fractional number.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.26. dbi_result_get_string

const char *dbi_result_get_string(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a string. The string may not be modified, and may not necessairly persist between row fetches.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.27. dbi_result_get_binary

const unsigned char *dbi_result_get_binary(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains binary BLOB data. The data may not be modified, and may not necessarily persist between row fetches.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.28. dbi_result_get_string_copy

char *dbi_result_get_string_copy(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a string. The newly allocated string may be modified by the host program, but the program is responsible for freeing the string.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.29. dbi_result_get_binary_copy

unsigned char *dbi_result_get_binary_copy(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains binary BLOB data. The newly allocated memory may be modified by the host program, but the program is responsible for freeing the data.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.30. dbi_result_get_enum

const char *dbi_result_get_enum(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains an ENUM (which will be represented as a read-only string).

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.31. dbi_result_get_set

const char *dbi_result_get_set(dbi_result Result, const char *fieldname)

Fetch the data stored in the speficied field, which contains a SET (which will be represented as a read-only string).

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.32. dbi_result_get_datetime

time_t dbi_result_get_datetime(dbi_result Result, const char *fieldname)

Fetch the data stored in the specified field, which contains a DATE and/or TIME value.

Arguments

Result: The target query result.

fieldname: The name of the field to fetch.

Returns

The data stored in the specified field.

3.5.33. dbi_result_bind_char

int dbi_result_bind_char(dbi_result Result, const char *fieldname, char *bindto)

Bind the specified variable to the specified field, which holds a character.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.34. dbi_result_bind_uchar

int dbi_result_bind_uchar(dbi_result Result, const char *fieldname, unsigned char *bindto)

Bind the specified variable to the specified field, which holds an unsigned character.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.35. dbi_result_bind_short

int dbi_result_bind_short(dbi_result Result, const char *fieldname, short *bindto)

Bind the specified variable to the specified field, which holds a short integer.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.36. dbi_result_bind_ushort

int dbi_result_bind_ushort(dbi_result Result, const char *fieldname, unsigned short *bindto)

Bind the specified variable to the specified field, which holds an unsigned short integer.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.37. dbi_result_bind_long

int dbi_result_bind_long(dbi_result Result, const char *fieldname, long *bindto)

Bind the specified variable to the specified field, which holds a long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.38. dbi_result_bind_ulong

int dbi_result_bind_ulong(dbi_result Result, const char *fieldname, unsigned long *bindto)

Bind the specified variable to the specified field, which holds an unsigned long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.39. dbi_result_bind_longlong

int dbi_result_bind_longlong(dbi_result Result, const char *fieldname, long long *bindto)

Bind the specified variable to the specified field, which holds a long long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.40. dbi_result_bind_ulonglong

int dbi_result_bind_ulonglong(dbi_result Result, const char *fieldname, unsigned long long *bindto)

Bind the specified variable to the specified field, which holds an unsigned long long integer.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.41. dbi_result_bind_float

int dbi_result_bind_float(dbi_result Result, const char *fieldname, float *bindto)

Bind the specified variable to the specified field, which holds a floating-point number.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.42. dbi_result_bind_double

int dbi_result_bind_double(dbi_result Result, const char *fieldname, double *bindto)

Bind the specified variable to the specified field, which holds a double-precision fractional number.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.43. dbi_result_bind_string

int dbi_result_bind_string(dbi_result Result, const char *fieldname, const char **bindto)

Bind the specified variable to the specified field, which holds a string. The string must not be modified.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.44. dbi_result_bind_binary

int dbi_result_bind_binary(dbi_result Result, const char *fieldname, const unsigned char **bindto)

Bind the specified variable to the specified field, which holds binary BLOB data. The data must not be modified.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.45. dbi_result_bind_string_copy

int dbi_result_bind_string_copy(dbi_result Result, const char *fieldname, char **bindto)

Bind the specified variable to the specified field, which holds a string. The newly allocated string may be modified by the host program, but the program is responsible for freeing the string.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.46. dbi_result_bind_binary_copy

int dbi_result_bind_binary_copy(dbi_result Result, const char *fieldname, unsigned char **bindto)

Bind the specified variable to the specified field, which holds binary BLOB data. The newly allocated data may be modified by the host program, but the program is responsible for freeing the data.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.47. dbi_result_bind_enum

int dbi_result_bind_enum(dbi_result Result, const char *fieldname, const char **bindto)

Bind the specified variable to the specified field, which holds an ENUM (which is represented as a read-only string).

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.48. dbi_result_bind_set

int dbi_result_bind_set(dbi_result Result, const char *fieldname, const char **bindto)

Bind the specified variable to the specified field, which holds a SET (which is represented as a read-only string).

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.49. dbi_result_bind_datetime

int dbi_result_bind_datetime(dbi_result Result, const char *fieldname, time_t *bindto)

Bind the specified variable to the specified field, which holds a DATE and/or TIME value.

Arguments

Result: The target query result.

fieldname: The name of the field to bind to.

bindto: A pointer to the variable that will be updated with the specified field's value.

Returns

0 upon success, -1 if there was an error

3.5.50. dbi_result_get_char_idx

signed char dbi_result_get_char_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a character.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.51. dbi_result_get_uchar_idx

unsigned char dbi_result_get_uchar_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains an unsigned character.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.52. dbi_result_get_short_idx

short dbi_result_get_short_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a short integer.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.53. dbi_result_get_ushort_idx

unsigned short dbi_result_get_ushort_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains an unsigned short integer.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.54. dbi_result_get_long_idx

long dbi_result_get_long_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a long integer.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.55. dbi_result_get_ulong_idx

unsigned long dbi_result_get_ulong_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains an unsigned long integer.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.56. dbi_result_get_longlong_idx

long long dbi_result_get_longlong_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a long long integer.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.57. dbi_result_get_ulonglong_idx

unsigned long long dbi_result_get_ulonglong_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains an unsigned long long integer.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.58. dbi_result_get_float_idx

float dbi_result_get_float_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a floating-point number.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.59. dbi_result_get_double_idx

double dbi_result_get_double_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a double-precision fractional number.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.60. dbi_result_get_string_idx

const char *dbi_result_get_string_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a string. The string may not be modified, and may not necessairly persist between row fetches.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.61. dbi_result_get_binary_idx

const unsigned char *dbi_result_get_binary_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains binary BLOB data. The data may not be modified, and may not necessarily persist between row fetches.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.62. dbi_result_get_string_copy_idx

char *dbi_result_get_string_copy_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a string. The newly allocated string may be modified by the host program, but the program is responsible for freeing the string.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.63. dbi_result_get_binary_copy_idx

unsigned char *dbi_result_get_binary_copy_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains binary BLOB data. The newly allocated memory may be modified by the host program, but the program is responsible for freeing the data.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.64. dbi_result_get_enum_idx

const char *dbi_result_get_enum_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains an ENUM (which will be represented as a read-only string).

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.65. dbi_result_get_set_idx

const char *dbi_result_get_set_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the speficied field, which contains a SET (which will be represented as a read-only string).

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.

3.5.66. dbi_result_get_datetime_idx

time_t dbi_result_get_datetime_idx(dbi_result Result, unsigned int idx)

Fetch the data stored in the specified field, which contains a DATE and/or TIME value.

Arguments

Result: The target query result.

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

Returns

The data stored in the specified field.