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.
