Book HomeManaging and Using MySQLSearch this book

Chapter 19. C Reference

Contents:

Data Types
Functions

The MySQL C API underlies all the APIs used by other languages to communicate with MySQL.

19.1. Data Types

The MySQL C API uses several defined data types beyond the standard C types. These types are defined in the mysql.h header file that must be included when compiling any program that uses the MySQL library.

MYSQL
A structure representing a connection to the database server. The program allocates a variable of this type, initializes the variable through the mysql_init call, and passes the variable to subsequent calls. The elements of the structure contain the name of the current database and information about the client connection, among other things.

MYSQL_FIELD
A structure containing all the information concerning a specific field in the table. Of all the types created for MySQL, this is the only one with member variables accessed directly from client programs. Therefore, you need to know the layout of the structure:

char *name
The name of the field.

char *table
The name of the table containing this field. For result sets that do not correspond to real tables, this value is null.

char *def
The default value of this field, if one exists. This value is always null unless mysql_list_fields is called, after which it is the correct value for fields that have defaults.

enum enum_field_types type
The type of the field. The type is one of the internal MySQL SQL data types. The following field types (along with their corresponding common MySQL SQL data types) are currently defined:

unsigned int length
The size of the field based on the field's type.

unsigned int max_length
If accessed after calling mysql_list_fields, this contains the length of the maximum value contained in the current result set. If the field is a BLOB-style field (e.g., BLOB, TEXT, LONGBLOB, MEDIUMTEXT, etc.), this value is always 8000 (~8 kB) if called before the actual data is retrieved from the result set (by using mysql_store_result( ), for example). Once the data has been retrieved, this field contains the actual maximum length.

unsigned int flags
Zero or more option flags. The following flags are currently defined:

NOT_NULL_FLAG
If defined, the field cannot contain a NULL value.

PRI_KEY_FLAG
If defined, the field is a primary key.

UNIQUE_KEY_FLAG
If defined, the field is part of a unique key.

MULTIPLE_KEY_FLAG
If defined, the field is part of a key.

BLOB_FLAG
If defined, the field is of type BLOB or TEXT.

UNSIGNED_FLAG
If defined, the field is a numeric type with an unsigned value.

ZEROFILL_FLAG
If defined, the application should fill any unused characters in a value of this field with zeros.

BINARY_FLAG
If defined, the field is of type CHAR or VARCHAR with the BINARY flag.

ENUM_FLAG
If defined, the field is of type ENUM.

AUTO_INCREMENT_FLAG
If defined, the field has the AUTO_INCREMENT attribute.

TIMESTAMP_FLAG
If defined, the field is of type TIMESTAMP.

SET_FLAG
If defined, the field is of type SET.

NUM_FLAG
If defined, the field is a numeric type (e.g., INT, DOUBLE, etc.).

PART_KEY_FLAG
If defined, the field is part of a key. This flag is not meant for use by clients, and its behavior may change in the future.

GROUP_FLAG
This flag is not meant for use by clients, and its behavior may change in the future.

UNIQUE_FLAG
This flag is not meant for use by clients, and its behavior may change in the future.

unsigned int decimals
When used with a numeric field, this lists the number of decimals used in the field.

The following macros are provided to help examine the MYSQL_FIELD data:

IS_PRI_KEY(flags)
Returns true if the field is a primary key. This macro takes the flags attribute of a MYSQL_FIELD structure as its argument.

IS_NOT_NULL(flags)
Returns true if the field is defined as NOT NULL. This macro takes the flags attribute of a MYSQL_FIELD structure as its argument.

IS_BLOB(flags)
Returns true if the field is of type BLOB or TEXT. This macro takes the flags attribute of a MYSQL_FIELD structure as its argument.

IS_NUM(type)
Returns true if the field type is numeric. This macro takes the type attribute of a MYSQL_FIELD structure as its argument.

IS_NUM_FIELD(field)
Returns true if the field is numeric. This macro takes a MYSQL_FIELD structure as its argument.

MYSQL_FIELD_OFFSET
A numerical type indicating the position of the "cursor" within a row.

MYSQL_RES
A structure containing the results of a SELECT (or SHOW) statement. The actual output of the query must be accessed through the MYSQL_ROW elements of this structure. A series of mysql_fetch calls are provided to retrieve results.

MYSQL_ROW
A single row of data returned from a SELECT query. Output of all MySQL data types are stored in this type (as an array of character strings).

my_ulonglong
A numerical type used for MySQL return values. The value ranges from 0 to 1.8E19, with -1 used to indicate errors.



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.