DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(mysql.info.gz) C API Prepared statement datatypes

Info Catalog (mysql.info.gz) C API Prepared statements (mysql.info.gz) C (mysql.info.gz) C API Prepared statement function overview
 
 22.2.5 C API Prepared Statement Data types
 ------------------------------------------
 
 * Some incompatible changes were made in MySQL 4.1.2.  See 
 C API Prepared statement functions for details.
 
 Prepared statements mainly use the `MYSQL_STMT' and `MYSQL_BIND' data
 structures. A third structure, `MYSQL_TIME', is used to transfer
 temporal data.
 
 `MYSQL_STMT'
      This structure represents a prepared statement.  A statement is
      created by calling `mysql_stmt_init()', which returns a statement
      handle, that is, a pointer to a `MYSQL_STMT'.  The handle is used
      for all subsequent statement-related functions until you close it
      with `mysql_stmt_close()'.
 
      The `MYSQL_STMT' structure has no members that are for application
      use.
 
      Multiple statement handles can be associated with a single
      connection.  The limit on the number of handles depends on the
      available system resources.
 
 `MYSQL_BIND'
      This structure is used both for statement input (data values sent
      to the server) and output (result values returned from the
      server). For input, it is used with `mysql_stmt_bind_param()' to
      bind parameter data values to buffers for use by
      `mysql_stmt_execute()'. For output, it is used with
      `mysql_stmt_bind_result()' to bind result set buffers for use in
      fetching rows with `mysql_stmt_fetch()'.
 
      The `MYSQL_BIND' structure contains the following members for use
      by application programs.  Each is used both for input and for
      output, although sometimes for different purposes depending on the
      direction of data transfer.
 
     `enum enum_field_types buffer_type'
           The type of the buffer. The allowable `buffer_type' values
           are listed later in this section. For input, `buffer_type'
           indicates what type of value you are binding to a statement
           parameter. For output, it indicates what type of value you
           expect to receive in a result buffer.
 
     `void *buffer'
           For input, this is a pointer to the buffer in which a
           statement parameter's data value is stored. For output, it is
           a pointer to the buffer in which to return a result set
           column value.  For numeric column types, `buffer' should
           point to a variable of the proper C type.  (If you are
           associating the variable with a column that has the
           `UNSIGNED' attribute, the variable should be an `unsigned' C
           type.  Indicate whether the variable is signed or unsigned by
           using the `is_unsigned' member, described later in this list.)
           For date and time column types, `buffer' should point to a
           `MYSQL_TIME' structure.  For character and binary string
           column types, `buffer' should point to a character buffer.
 
     `unsigned long buffer_length'
           The actual size of `*buffer' in bytes. This indicates the
           maximum amount of data that can be stored in the buffer. For
           character and binary C data, the `buffer_length' value
           specifies the length of `*buffer' when used with
           `mysql_stmt_bind_param()', or the maximum number of data
           bytes that can be fetched into the buffer when used with
           `mysql_stmt_bind_result()'.
 
     `unsigned long *length'
           A pointer to an `unsigned long' variable that indicates the
           actual number of bytes of data stored in `*buffer'.  `length'
           is used for character or binary C data.  For input parameter
           data binding, `length' points to an `unsigned long' variable
           that indicates the length of the parameter value stored in
           `*buffer'; this is used by `mysql_stmt_execute()'.  For
           output value binding, `mysql_stmt_fetch()' places the length
           of the column value that is returned into the variable that
           `length' points to.
 
           `length' is ignored for numeric and temporal data types
           because the length of the data value is determined by the
           `buffer_type' value.
 
     `my_bool *is_null'
           This member points to a `my_bool' variable that is true if a
           value is `NULL', false if it is not `NULL'. For input, set
           `*is_null' to true to indicate that you are passing a `NULL'
           value as a statement parameter. For output, this value will
           be set to true after you fetch a row if the result set column
           value returned from the statement is `NULL'.
 
     `my_bool is_unsigned'
           This member is used for integer types.  (These correspond to
           the `MYSQL_TYPE_TINY', `MYSQL_TYPE_SHORT', `MYSQL_TYPE_LONG',
           and `MYSQL_TYPE_LONGLONG' type codes.)  `is_unsigned' should
           be set to true for unsigned types and false for signed types.
 
     `my_bool error'
           For output, this member is used output to report data
           truncation errors.  Truncation reporting must be enabled by
           calling `mysql_options()' with the
           `MYSQL_REPORT_DATA_TRUNCATION' option.  When enabled,
           `mysql_stmt_fetch()' returns `MYSQL_DATA_TRUNCATED' and
           `error' is true in the `MYSQL_BIND' structures for parameters
           in which truncation occurred. Truncation indicates loss of
           sign or significant digits, or that a string was too long to
           fit in a column.  The `error' member was added in MySQL 5.0.3.
 
 
      To use a `MYSQL_BIND' structure, you should zero its contents to
      initialize it, and then set the members just described
      appropriately.  For example, to declare and initialize an array of
      three `MYSQL_BIND' structures, use this code:
 
           MYSQL_BIND    bind[3];
           memset(bind, 0, sizeof(bind));
 
 `MYSQL_TIME'
      This structure is used to send and receive `DATE', `TIME',
      `DATETIME', and `TIMESTAMP' data directly to and from the server.
      This is done by setting the `buffer_type' member of a `MYSQL_BIND'
      structure to one of the temporal types, and setting the `buffer'
      member to point to a `MYSQL_TIME' structure.
 
      The `MYSQL_TIME' structure contains the following members:
 
     `unsigned int year'
           The year.
 
     `unsigned int month'
           The month of the year.
 
     `unsigned int day'
           The day of the month.
 
     `unsigned int hour'
           The hour of the day.
 
     `unsigned int minute'
           The minute of the hour.
 
     `unsigned int second'
           The second of the minute.
 
     `my_bool neg'
           A boolean flag to indicate whether the time is negative.
 
     `unsigned long second_part'
           The fractional part of the second.  This member currently is
           unused.
 
 
      Only those parts of a `MYSQL_TIME' structure that apply to a given
      type of temporal value are used: The `year', `month', and `day'
      elements are used for `DATE', `DATETIME', and `TIMESTAMP' values.
      The `hour', `minute', and `second' elements are used for `TIME',
      `DATETIME', and `TIMESTAMP' values.   C API date handling.
 
 
 The following table shows the allowable values that may be specified in
 the `buffer_type' member of `MYSQL_BIND' structures.  The table also
 shows those SQL types that correspond most closely to each
 `buffer_type' value, and, for numeric and temporal types, the
 corresponding C type.
 
 `buffer_type' *Value*    *SQL Type*               *C Type*
 `MYSQL_TYPE_TINY'        `TINYINT'                `char'
 `MYSQL_TYPE_SHORT'       `SMALLINT'               `short int'
 `MYSQL_TYPE_LONG'        `INT'                    `int'
 `MYSQL_TYPE_LONGLONG'    `BIGINT'                 `long long int'
 `MYSQL_TYPE_FLOAT'       `FLOAT'                  `float'
 `MYSQL_TYPE_DOUBLE'      `DOUBLE'                 `double'
 `MYSQL_TYPE_TIME'        `TIME'                   `MYSQL_TIME'
 `MYSQL_TYPE_DATE'        `DATE'                   `MYSQL_TIME'
 `MYSQL_TYPE_DATETIME'    `DATETIME'               `MYSQL_TIME'
 `MYSQL_TYPE_TIMESTAMP'   `TIMESTAMP'              `MYSQL_TIME'
 `MYSQL_TYPE_STRING'      `CHAR'                   
 `MYSQL_TYPE_VAR_STRING'  `VARCHAR'                
 `MYSQL_TYPE_TINY_BLOB'   `TINYBLOB/TINYTEXT'      
 `MYSQL_TYPE_BLOB'        `BLOB/TEXT'              
 `MYSQL_TYPE_MEDIUM_BLOB' `MEDIUMBLOB/MEDIUMTEXT'  
 `MYSQL_TYPE_LONG_BLOB'   `LONGBLOB/LONGTEXT'      
 
 Implicit type conversion may be performed in both directions.
 
Info Catalog (mysql.info.gz) C API Prepared statements (mysql.info.gz) C (mysql.info.gz) C API Prepared statement function overview
automatically generated byinfo2html