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:

• FIELD_TYPE_TINY (TINYINT)

• FIELD_TYPE_SHORT (SMALLINT)

• FIELD_TYPE_LONG (INTEGER)

• FIELD_TYPE_INT24 (MEDIUMINT)

• FIELD_TYPE_LONGLONG (BIGINT)

• FIELD_TYPE_DECIMAL (DECIMAL or NUMERIC)

• FIELD_TYPE_FLOAT (FLOAT)

• FIELD_TYPE_DOUBLE (DOUBLE or REAL)

• FIELD_TYPE_TIMESTAMP (TIMESTAMP)

• FIELD_TYPE_DATE (DATE)

• FIELD_TYPE_TIME (TIME)

• FIELD_TYPE_DATETIME (DATETIME)

• FIELD_TYPE_YEAR (YEAR)

• FIELD_TYPE_STRING (CHAR or VARCHAR)

• FIELD_TYPE_BLOB (BLOB or TEXT)

• FIELD_TYPE_SET (SET)

• FIELD_TYPE_ENUM (ENUM)

• FIELD_TYPE_NULL (NULL)

• FIELD_TYPE_CHAR (TINYINT) (Deprecated, replaced by FIELD_TYPE_TINY)

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.