database/mariadb
1
0
Fork 0
mirror of https://github.com/MariaDB/server.git synced 2025-10-27 05:56:07 +03:00
Code Activity

Added all new changes (To be incorporated to main manual before the release)

Browse Source
This commit is contained in:
venu@myvenu.com
2003-02-05 22:29:42 -08:00
parent 03fd42e601
commit cde22b0247
1 changed files with 435 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

542
Docs/prepare.texi
View File

@@ -117,6 +117,8 @@
* C Prepared statement datatypes:: * C Prepared statement datatypes::
* C Prepared statements function overview:: * C Prepared statements function overview::
* C Prepared statement functions:: * C Prepared statement functions::
* multiple queries::
* date handling::
@end menu @end menu
@node C Prepared statements, C Prepared statement datatypes, MySQL prepared statements, MySQL prepared statements @node C Prepared statements, C Prepared statement datatypes, MySQL prepared statements, MySQL prepared statements
@@ -160,8 +162,10 @@ Prepared statements mainly uses the following two @code{MYSQL_STMT} and
@sp 1 @sp 1
@table @code @table @code
@tindex MYSQL C type @tindex MYSQL_STMT C type
@item MYSQL_STMT @item MYSQL_STMT
This structure represents a statement handle to prepared statements.It This structure represents a statement handle to prepared statements.It
is used for all statement related functions. is used for all statement related functions.
@@ -178,11 +182,14 @@ the system resources.
@sp 1 @sp 1
@tindex MYSQL_BIND C type @tindex MYSQL_BIND C type
@item MYSQL_BIND @item MYSQL_BIND
This structure is used in order to bind parameter buffers inorder to
send the parameters data to @code{mysql_execute()} call; as well as to This structure is used in order to bind parameter
bind row buffers to fetch the result set data using @code{mysql_fetch()}. buffers(@code{mysql_bind_param()}) inorder to the parameters data to
@end table @code{mysql_execute()} call; as well as to bind row
buffers(@code{mysql_bind_result()}) to fetch the result set data using
@code{mysql_fetch()}.
@sp 1 @sp 1
@@ -191,6 +198,7 @@ The @code{MYSQL_BIND} structure contains the members listed here:
@table @code @table @code
@item enum enum_field_types buffer_type [input] @item enum enum_field_types buffer_type [input]
The type of the buffer. The @code{type} value must be one of the following: The type of the buffer. The @code{type} value must be one of the following:
@@ -202,6 +210,10 @@ The type of the buffer. The @code{type} value must be one of the following:
@item @code{MYSQL_TYPE_LONGLONG} @item @code{MYSQL_TYPE_LONGLONG}
@item @code{MYSQL_TYPE_FLOAT} @item @code{MYSQL_TYPE_FLOAT}
@item @code{MYSQL_TYPE_DOUBLE} @item @code{MYSQL_TYPE_DOUBLE}
@item @code{MYSQL_TYPE_TIME}
@item @code{MYSQL_TYPE_DATE}
@item @code{MYSQL_TYPE_DATETIME}
@item @code{MYSQL_TYPE_TIMESTAMP}
@item @code{MYSQL_TYPE_STRING} @item @code{MYSQL_TYPE_STRING}
@item @code{MYSQL_TYPE_VAR_STRING} @item @code{MYSQL_TYPE_VAR_STRING}
@item @code{MYSQL_TYPE_TINY_BLOB} @item @code{MYSQL_TYPE_TINY_BLOB}
@@ -218,49 +230,62 @@ data when the structure is used for result set bind.
@sp 1 @sp 1
@item unsigned long buffer_length [input]
Length of the @code{*buffer} in bytes. For character and binary C data,
the buffer_length specifies the length of the @code{*buffer} to be used
as a parameter data in case if it is used with @code{mysql_bind_param()}
or to return that many bytes when fetching results when this is used
with @code{mysql_bind_result()}.
@item long *length [input/output] @item long *length [input/output]
Pointer to the buffer for the parameter's length. When the structure is Pointer to the buffer for the parameter's length. When the structure is
used as a input parameter data binding, then this argument points to a used as a input parameter data binding, then this argument points to a
buffer that, when @code{mysql_execute()} is called, contains one of the buffer that, when @code{mysql_execute()} is called, contains the length
following: of the parameter value stored in *buffer. This is ignored except for
character or binary C data.
@itemize @bullet
@item
The length of the parameter value stored in *buffer. This is ignored
except for character or binary C data.
@item
MYSQL_NULL_DATA. The parameter value is NULL.
@item
MYSQL_LONG_DATA. The parameter value is a long data and is supplied in
chunks through @code{mysql_send_long_data()}.
@end itemize
If the length is a null pointer, then the protocol assumes that all If the length is a null pointer, then the protocol assumes that all
input parameter values are non-NULL and that character and binary data character and binary data are null terminated.
are null terminated.
When this structure is used in output binding, then @code{mysql_fetch()} When this structure is used in output binding, then @code{mysql_fetch()}
return the following values in the length buffer: return the the length of the data that is returned.
@itemize @bullet @sp 1
@item
The length of the data that is returned
@item
MYSQL_NULL_DATA, indicating the data returned is a NULL data.
@end itemize
@item bool *is_null [input/output]
Indicates if the parameter data is NULL or fetched data is NULL.
@end table
@c @item bool is_null [input] @sp 1
@c To indicate the parameter data is NULL. This is same as supplying
@c MYSQL_NULL_DATA, -1 as the length in length pointer.
@tindex MySQL C type
@c @item bool is_long_data [input] @item MYSQL_TIME
@c To indicate the parameter data is a long data, and the data will be
@c supplied in chunks through @code{mysql_send_long_data()}.This is also This structure is used to send and receive DATE, TIME and
@c same as supplying MYSQL_LONG_DATA, -2 as the length in length pointer. TIMESTAMP data directly to/from server.
@c @end table
@sp 1
@noindent
The @code{MYSQL_TIME} structure contains the members listed here:
@multitable @columnfractions .20 .20 .68
@item @strong{Member} @tab @strong{Type} @tab @strong{Description}
@item @code{year} @tab unsigned int @tab Year.
@item @code{month} @tab unsigned int @tab Month of the year.
@item @code{day} @tab unsigned int @tab Day of the month.
@item @code{hour} @tab unsigned int @tab Hour of the day(TIME).
@item @code{minute} @tab unsigned int @tab Minute of the hour.
@item @code{second} @tab unsigned int @tab Second of the minute.
@item @code{neg} @tab my_bool @tab A boolean flag to
indicate if the time is negative.
@item @code{second_part} @tab unsigned long @tab Fraction part of the
second(not yet used)
@end multitable
@end table @end table
@@ -289,7 +314,10 @@ are described in greater detail in the later section.
@item @strong{mysql_stmt_affected_rows()} @tab Returns the number of rows changes/deleted/inserted by the last UPDATE,DELETE,or INSERT query @item @strong{mysql_stmt_affected_rows()} @tab Returns the number of rows changes/deleted/inserted by the last UPDATE,DELETE,or INSERT query
@item @strong{mysql_bind_result()} @tab Binds application data buffers to columns in the resultset. @item @strong{mysql_bind_result()} @tab Binds application data buffers
to columns in the resultset.
@item @strong{mysql_stmt_store_result()} @tab Retrieves the complete result set to the client
@item @strong{mysql_fetch()} @tab Fetches the next rowset of data from the result set and returns data for all bound columns. @item @strong{mysql_fetch()} @tab Fetches the next rowset of data from the result set and returns data for all bound columns.
@@ -315,6 +343,7 @@ are described in greater detail in the later section.
@end multitable @end multitable
@sp 1 @sp 1
Call @code{mysql_prepare()} to prepare and initialize the statement Call @code{mysql_prepare()} to prepare and initialize the statement
handle, then call @code{mysql_bind_param()} to supply the parameters handle, then call @code{mysql_bind_param()} to supply the parameters
data, and then call @code{mysql_execute()} to execute the query. You can data, and then call @code{mysql_execute()} to execute the query. You can
@@ -421,7 +450,7 @@ You can get the statement error code and message using
@code{mysql_stmt_errno()} and @code{mysql_stmt_error()} respectively. @code{mysql_stmt_errno()} and @code{mysql_stmt_error()} respectively.
@node C Prepared statement functions, , C Prepared statements function overview, MySQL prepared statements @node C Prepared statement functions, multiple queries, C Prepared statements function overview, MySQL prepared statements
@subsection C Prepared Statement Function Descriptions @subsection C Prepared Statement Function Descriptions
You need to use the following functions when you want to prepare and You need to use the following functions when you want to prepare and
@@ -429,21 +458,24 @@ execute the queries.
@menu @menu
* mysql_prepare:: * mysql_prepare:: @code{mysql_prepare()}
* mysql_param_count:: * mysql_param_count:: @code{mysql_param_count()}
* mysql_prepare_result:: * mysql_prepare_result:: @code{mysql_prepare_result()}
* mysql_bind_param:: * mysql_bind_param:: @code{mysql_bind_param()}
* mysql_execute:: * mysql_execute:: @code{mysql_execute()}
* mysql_stmt_affected_rows:: * mysql_stmt_affected_rows:: @code{mysql_stmt_affected_rows()}
* mysql_bind_result:: * mysql_bind_result:: @code{mysql_bind_result()}
* mysql_fetch:: * mysql_stmt_store_result:: @code{mysql_stmt_store_result()}
* mysql_send_long_data:: * mysql_fetch:: @code{mysql_fetch()}
* mysql_stmt_close:: * mysql_send_long_data:: @code{mysql_send_long_data()}
* mysql_stmt_errno:: * mysql_stmt_close:: @code{mysql_stmt_close()}
* mysql_stmt_error:: * mysql_stmt_errno:: @code{mysql_stmt_errno()}
* mysql_commit:: * mysql_stmt_error:: @code{mysql_stmt_error()}
* mysql_rollback:: * mysql_commit:: @code{mysql_commit()}
* mysql_autocommit:: * mysql_rollback:: @code{mysql_rollback()}
* mysql_autocommit:: @code{mysql_autocommit()}
* mysql_more_results:: @code{mysql_more_results()}
* mysql_next_result:: @code{mysql_next_result()}
@end menu @end menu
@node mysql_prepare, mysql_param_count, C Prepared statement functions, C Prepared statement functions @node mysql_prepare, mysql_param_count, C Prepared statement functions, C Prepared statement functions
@@ -488,6 +520,18 @@ occured.
@subsubheading Errors @subsubheading Errors
@item CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order
@item CR_OUT_OF_MEMORY
Out of memory
@item CR_SERVER_GONE_ERROR
The MySQL server has gone away
@item CR_SERVER_LOST
The connection to the server was lost during the query
@item CR_UNKNOWN_ERROR
An unkown error occured
@end table
If the prepare is not successful, i.e. when @code{mysql_prepare()} returned a If the prepare is not successful, i.e. when @code{mysql_prepare()} returned a
NULL statement, errors can be obtained by calling @code{mysql_error()}. NULL statement, errors can be obtained by calling @code{mysql_error()}.
@@ -573,6 +617,11 @@ the prepared query.
@subsubheading Errors @subsubheading Errors
@item CR_OUT_OF_MEMOR
Out of memory
@item CR_UNKNOWN_ERROR
An unknown error occured
None None
@@ -612,6 +661,14 @@ MYSQL_TYPE_FLOAT
@item @item
MYSQL_TYPE_DOUBLE MYSQL_TYPE_DOUBLE
@item @item
MYSQL_TYPE_TIME
@item
MYSQL_TYPE_DATE
@item
MYSQL_TYPE_DATETIME
@item
MYSQL_TYPE_TIMESTAMP
@item
MYSQL_TYPE_STRING MYSQL_TYPE_STRING
@item @item
MYSQL_TYPE_VAR_STRING MYSQL_TYPE_VAR_STRING
@@ -639,6 +696,10 @@ buffer type is non string or binary
@item CR_UNSUPPORTED_PARAM_TYPE @item CR_UNSUPPORTED_PARAM_TYPE
The conversion is not supported, possibly the buffer_type is illegal or The conversion is not supported, possibly the buffer_type is illegal or
its not from the above list of supported types. its not from the above list of supported types.
@item CR_OUT_OF_MEMOR
Out of memory
@item CR_UNKNOWN_ERROR
An unknown error occured
@end table @end table
@subsubheading Example @subsubheading Example
@@ -678,11 +739,9 @@ how to fetch the statement binary data, refer to @ref{mysql_fetch}.
@multitable @columnfractions .30 .65 @multitable @columnfractions .30 .65
@item @strong{Return Value} @tab @strong{Description} @item @strong{Return Value} @tab @strong{Description}
@item MYSQL_SUCCESS, 0 @tab Successful @item 0 @tab Successful
@item MYSQL_STATUS_ERROR, 1 @tab Error occured. Error code and @item 1 @tab Error occured. Error code and
message can be obtained by calling @code{mysql_stmt_errno()} and @code{mysql_stmt_error()}. message can be obtained by calling @code{mysql_stmt_errno()} and @code{mysql_stmt_error()}.
@item MYSQL_NEED_DATA, 99 @tab One of the parameter buffer is
indicating the data suppy in chunks, and the supply is not yet complete.
@end multitable @end multitable
@@ -693,10 +752,16 @@ indicating the data suppy in chunks, and the supply is not yet complete.
No query prepared prior to execution No query prepared prior to execution
@item CR_ALL_PARAMS_NOT_BOUND @item CR_ALL_PARAMS_NOT_BOUND
Not all parameters data is supplied Not all parameters data is supplied
@item CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
@item CR_OUT_OF_MEMORY
Out of memory.
@item CR_SERVER_GONE_ERROR @item CR_SERVER_GONE_ERROR
The MySQL server has gone away The MySQL server has gone away.
@item CR_SERVER_LOST
The connection to the server was lost during the query.
@item CR_UNKNOWN_ERROR @item CR_UNKNOWN_ERROR
An unkown error occured An unknown error occurred.
@end table @end table
@@ -714,7 +779,9 @@ ulonglong affected_rows;
long length; long length;
unsigned int param_count; unsigned int param_count;
int int_data; int int_data;
short small_data;
char str_data[50], query[255]; char str_data[50], query[255];
my_bool is_null;
/* Set autocommit mode to true */ /* Set autocommit mode to true */
mysql_autocommit(mysql, 1); mysql_autocommit(mysql, 1);
@@ -735,8 +802,8 @@ char str_data[50], query[255];
@} @}
/* Prepare a insert query with 3 parameters */ /* Prepare a insert query with 3 parameters */
strcpy(query, "INSERT INTO test_table(col1,col2,col3) values(?,?,?)"); strmov(query, "INSERT INTO test_table(col1,col2,col3) values(?,?,?)");
if(!(stmt = mysql_prepare(mysql,query,strlen(query)))) if(!(stmt = mysql_prepare(mysql, query, strlen(query))))
@{ @{
fprintf(stderr, "\n prepare, insert failed"); fprintf(stderr, "\n prepare, insert failed");
fprintf(stderr, "\n %s", mysql_error(mysql)); fprintf(stderr, "\n %s", mysql_error(mysql));
@@ -757,19 +824,25 @@ char str_data[50], query[255];
/* Bind the data for the parameters */ /* Bind the data for the parameters */
/* INTEGER PART */ /* INTEGER PART */
memset(bind,0,sizeof(bind));
bind[0].buffer_type= MYSQL_TYPE_LONG; bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (void *)&int_data; bind[0].buffer= (char *)&int_data;
bind[0].is_null= 0;
bind[0].length= 0;
/* STRING PART */ /* STRING PART */
bind[1].buffer_type= MYSQL_TYPE_VAR_STRING; bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
bind[1].buffer= (void *)str_data; bind[1].buffer= (char *)str_data;
bind[1].buffer_length= sizeof(str_data); bind[1].buffer_length= sizeof(str_data);
bind[1].is_null= 0;
bind[1].length= 0;
/* SMALLINT PART */ /* SMALLINT PART */
bind[2].buffer_type= MYSQL_TYPE_SHORT; bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (void *)&small_data; bind[2].buffer= (char *)&small_data;
bind[2].length= (long *)&length; bind[2].is_null= &is_null;
bind[2].length= 0;
is_null= 0;
/* Bind the buffers */ /* Bind the buffers */
if (mysql_bind_param(stmt, bind)) if (mysql_bind_param(stmt, bind))
@@ -782,8 +855,9 @@ char str_data[50], query[255];
/* Specify the data */ /* Specify the data */
int_data= 10; /* integer */ int_data= 10; /* integer */
strcpy(str_data,"MySQL"); /* string */ strcpy(str_data,"MySQL"); /* string */
/* INSERT SMALLINT data as NULL */ /* INSERT SMALLINT data as NULL */
length= MYSQL_NULL_DATA; is_null= 1;
/* Execute the insert statement - 1*/ /* Execute the insert statement - 1*/
if (mysql_execute(stmt)) if (mysql_execute(stmt))
@@ -808,7 +882,7 @@ char str_data[50], query[255];
int_data= 1000; int_data= 1000;
strcpy(str_data,"The most popular open source database"); strcpy(str_data,"The most popular open source database");
small_data= 1000; /* smallint */ small_data= 1000; /* smallint */
length= 0; is_null= 0; /* reset NULL */
/* Execute the insert statement - 2*/ /* Execute the insert statement - 2*/
if (mysql_execute(stmt)) if (mysql_execute(stmt))
@@ -843,7 +917,7 @@ char str_data[50], query[255];
fprintf(stderr, "\n %s", mysql_error(mysql)); fprintf(stderr, "\n %s", mysql_error(mysql));
exit(0); exit(0);
@} @}
fprintf(stdout, "Success, MySQL prepared statements are working great !!!"); fprintf(stdout, "Success, MySQL prepared statements are working!!!");
@end example @end example
@@ -885,7 +959,7 @@ from @ref{mysql_execute,mysql_execute()}.
@node mysql_bind_result, mysql_fetch, mysql_stmt_affected_rows, C Prepared statement functions @node mysql_bind_result, mysql_stmt_store_result, mysql_stmt_affected_rows, C Prepared statement functions
@subsubsection @code{mysql_bind_result()} @subsubsection @code{mysql_bind_result()}
@findex @code{mysql_bind_result()} @findex @code{mysql_bind_result()}
@@ -894,7 +968,7 @@ from @ref{mysql_execute,mysql_execute()}.
@subsubheading Description @subsubheading Description
@code{mysql_bind_result()} is ised to associate, or bind, columns in the @code{mysql_bind_result()} is used to associate, or bind, columns in the
resultset to data buffers and length buffers. When @code{mysql_fetch()} is resultset to data buffers and length buffers. When @code{mysql_fetch()} is
called to fetch data, the MySQL client protocol returns the data for the called to fetch data, the MySQL client protocol returns the data for the
bound columns in the specified buffers. bound columns in the specified buffers.
@@ -938,6 +1012,14 @@ MYSQL_TYPE_FLOAT
@item @item
MYSQL_TYPE_DOUBLE MYSQL_TYPE_DOUBLE
@item @item
MYSQL_TYPE_TIME
@item
MYSQL_TYPE_DATE
@item
MYSQL_TYPE_DATETIME
@item
MYSQL_TYPE_TIMESTAMP
@item
MYSQL_TYPE_STRING MYSQL_TYPE_STRING
@item @item
MYSQL_TYPE_VAR_STRING MYSQL_TYPE_VAR_STRING
@@ -956,12 +1038,17 @@ MYSQL_TYPE_LONG_BLOB
Zero if the bind was successful. Non-zero if an error occured. Zero if the bind was successful. Non-zero if an error occured.
@subsubheading Errors @subsubheading Errors
@table @code @table @code
@item CR_NO_PREPARE_STMT @item CR_NO_PREPARE_STMT
No prepared statement exists No prepared statement exists
@item CR_UNSUPPORTED_PARAM_TYPE @item CR_UNSUPPORTED_PARAM_TYPE
The conversion is not supported, possibly the buffer_type is illegal or The conversion is not supported, possibly the buffer_type is illegal or
its not from the list of supported types. its not from the list of supported types.
@item CR_OUT_OF_MEMOR
Out of memory
@item CR_UNKNOWN_ERROR
An unknown error occured
@end table @end table
@subsubheading Example @subsubheading Example
@@ -971,7 +1058,53 @@ For the usage of @code{mysql_bind_result()} refer to the Example from
@node mysql_fetch, mysql_send_long_data, mysql_bind_result, C Prepared statement functions
@node mysql_stmt_store_result, mysql_fetch, mysql_bind_result, C Prepared statement functions
@subsubsection @code{mysql_stmt_store_result()}
@findex code{mysql_stmt_store_result()}
@code{int mysql_stmt_store_result(MYSQL_STMT *stmt)}
@subsubheading Description
You must call @code{mysql_stmt_store_result()} for every query that
successfully retrieves
data(@code{SELECT},@code{SHOW},@code{DESCRIBE},@code{EXPLAIN}), and only
if you want to buffer the complete result set by the client, so that the
subsequent @code{mysql_fetch()} call returns buffered data.
@sp 1
You don't have to call @code{mysql_stmt_store_result()} for other
queries, but it will not harm or cause any notable performance in all
cases.You can detect if the query didn't have a result set by checking
if @code{mysql_prepare_result()} returns 0. For more information refer
to @ref{mysql_prepare_result}.
@subsubheading Return Values
@code{Zero} if the results are buffered successfully or @code{Non Zero} in case of an error.
@subsubheading Errors
@table @code
@item CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
@item CR_OUT_OF_MEMORY
Out of memory.
@item CR_SERVER_GONE_ERROR
The MySQL server has gone away.
@item CR_SERVER_LOST
The connection to the server was lost during the query.
@item CR_UNKNOWN_ERROR
An unknown error occurred.
@end table
@node mysql_fetch, mysql_send_long_data, mysql_stmt_store_result, C Prepared statement functions
@subsubsection @code{mysql_fetch()} @subsubsection @code{mysql_fetch()}
@findex code{mysql_fetch()} @findex code{mysql_fetch()}
@@ -982,7 +1115,9 @@ For the usage of @code{mysql_bind_result()} refer to the Example from
@code{mysql_fetch()} returns the next rowset in the result set. It can @code{mysql_fetch()} returns the next rowset in the result set. It can
be called only while the result set exists i.e. after a call to be called only while the result set exists i.e. after a call to
@code{mysql_execute()} that creates a result set. @code{mysql_execute()} that creates a result set or after
@code{mysql_stmt_store_result()}, which is called after
@code{mysql_execute()} to buffer the entire resultset.
@sp 1 @sp 1
@@ -994,11 +1129,12 @@ set and the lengths are returned to the length pointer.
Note that, all columns must be bound by the application. Note that, all columns must be bound by the application.
@sp 1 @sp 1
If the data fetched is a NULL data, then the length buffer will have a If the data fetched is a NULL data, then the @code{is_null} value from
value of @strong{MYSQL_NULL_DATA}, -1, else it will have the length of @code{MYSQL_BIND} contains TRUE, 1, else the data and its length is
the data being fetched based on the buffer type specified by the returned to @code{*buffer} and @code{*length} variables based on the
application. All numeric, float and double types have the buffer type specified by the application. All numeric, float and double
fixed length(in bytes) as listed below: types have the fixed length(in bytes) as listed below:
@multitable @columnfractions .10 .30 @multitable @columnfractions .10 .30
@item @strong{Type} @tab @strong{Length} @item @strong{Type} @tab @strong{Length}
@@ -1008,6 +1144,10 @@ fixed length(in bytes) as listed below:
@item MYSQL_TYPE_FLOAT @tab 4 @item MYSQL_TYPE_FLOAT @tab 4
@item MYSQL_TYPE_LONGLONG @tab 8 @item MYSQL_TYPE_LONGLONG @tab 8
@item MYSQL_TYPE_DOUBLE @tab 8 @item MYSQL_TYPE_DOUBLE @tab 8
@item MYSQL_TYPE_TIME @tab sizeof(MYSQL_TIME)
@item MYSQL_TYPE_DATE @tab sizeof(MYSQL_TIME)
@item MYSQL_TYPE_DATETIME @tab sizeof(MYSQL_TIME)
@item MYSQL_TYPE_TIMESTAMP @tab sizeof(MYSQL_TIME)
@item MYSQL_TYPE_STRING @tab data length @item MYSQL_TYPE_STRING @tab data length
@item MYSQL_TYPE_VAR_STRING @tab data_length @item MYSQL_TYPE_VAR_STRING @tab data_length
@item MYSQL_TYPE_BLOB @tab data_length @item MYSQL_TYPE_BLOB @tab data_length
@@ -1023,21 +1163,31 @@ where @code{*data_length} is nothing but the 'Actual length of the data'.
@multitable @columnfractions .30 .65 @multitable @columnfractions .30 .65
@item @strong{Return Value} @tab @strong{Description} @item @strong{Return Value} @tab @strong{Description}
@item MYSQL_SUCCESS, 0 @tab Successful, the data has been @item 0 @tab Successful, the data has been
fetched to application data buffers. fetched to application data buffers.
@item MYSQL_STATUS_ERROR, 1 @tab Error occured. Error code and @item 1 @tab Error occured. Error code and
message can be obtained by calling @code{mysql_stmt_errno()} and @code{mysql_stmt_error()}. message can be obtained by calling @code{mysql_stmt_errno()} and @code{mysql_stmt_error()}.
@item MYSQL_NO_DATA, 100 @tab No more rows/data exists @item 100, MYSQL_NO_DATA @tab No more rows/data exists
@end multitable @end multitable
@subsubheading Errors @subsubheading Errors
@table @code @table @code
@item CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
@item CR_OUT_OF_MEMORY
Out of memory.
@item CR_SERVER_GONE_ERROR
The MySQL server has gone away.
@item CR_SERVER_LOST
The connection to the server was lost during the query.
@item CR_UNKNOWN_ERROR
An unknown error occurred.
@item CR_UNSUPPORTED_PARAM_TYPE @item CR_UNSUPPORTED_PARAM_TYPE
If the field type is DATE,DATETIME,TIME,or TIMESTAMP; and the If the buffer type is MYSQL_TYPE_DATE,DATETIME,TIME,or TIMESTAMP; and if
application buffer type is non string based. the field type is not DATE, TIME, DATETIME or TIMESTAMP.
@item @item
All other un-supported conversions are returned from All other unsupported conversion errors are returned from
@code{mysql_bind_result()}. @code{mysql_bind_result()}.
@end table @end table
@@ -1054,6 +1204,7 @@ MYSQL_RES *result;
int int_data; int int_data;
long int_length, str_length; long int_length, str_length;
char str_data[50]; char str_data[50];
my_bool is_null[2];
query= "SELECT col1, col2 FROM test_table WHERE col1= 10)"); query= "SELECT col1, col2 FROM test_table WHERE col1= 10)");
if (!(stmt= mysql_prepare(&mysql, query, strlen(query))) if (!(stmt= mysql_prepare(&mysql, query, strlen(query)))
@@ -1082,19 +1233,20 @@ char str_data[50];
/* Execute the SELECT query */ /* Execute the SELECT query */
if (mysql_execute(stmt)) if (mysql_execute(stmt))
@{ @{
fprintf(stderr, "\n execute didn't retuned expected return code, MYSQL_NEED_DATA"); fprintf(stderr, "\n execute failed");
fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
exit(0); exit(0);
@} @}
/* Bind the result data buffers */ /* Bind the result data buffers */
bzero(bind, 0, sizeof(bind));
bind[0].buffer_type= MYSQL_TYPE_LONG; bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (void *)&int_data; bind[0].buffer= (char *)&int_data;
bind[0].is_null= &is_null[0];
bind[0].length= &int_length; bind[0].length= &int_length;
bind[1].buffer_type= MYSQL_TYPE_VAR_STRING; bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
bind[1].buffer= (void *)str_data; bind[1].buffer= (void *)str_data;
bind[1].is_null= &is_null[1];
bind[1].length= &str_length; bind[1].length= &str_length;
if (mysql_bind_result(stmt, bind)) if (mysql_bind_result(stmt, bind))
@@ -1112,8 +1264,16 @@ char str_data[50];
exit(0); exit(0);
@} @}
fprintf(stdout, "\n int_data: %d, length: %ld", int_data, int_length); if (is_null[0])
fprintf(stdout, "\n str_data: %s, length: %ld", str_data, str_length); fprintf(stdout, "\n Col1 data is NULL");
else
fprintf(stdout, "\n Col1: %d, length: %ld", int_data, int_length);
if (is_null[1])
fprintf(stdout, "\n Col2 data is NULL");
else
fprintf(stdout, "\n Col2: %s, length: %ld", str_data, str_length);
/* call mysql_fetch again */ /* call mysql_fetch again */
if (mysql_fetch(stmt) |= MYSQL_NO_DATA) if (mysql_fetch(stmt) |= MYSQL_NO_DATA)
@@ -1122,7 +1282,7 @@ char str_data[50];
exit(0); exit(0);
@} @}
/* Free the prepare result */ /* Free the prepare result meta information */
mysql_free_result(result); mysql_free_result(result);
/* Free the statement handle */ /* Free the statement handle */
@@ -1144,7 +1304,7 @@ char str_data[50];
@findex @code{mysql_send_long_data()}. @findex @code{mysql_send_long_data()}.
@code{int mysql_send_long_data(MYSQL_STMT *stmt, unsigned int @code{int mysql_send_long_data(MYSQL_STMT *stmt, unsigned int
parameter_number, const char *data, ulong length, my_bool is_last_data)} parameter_number, const char *data, ulong length)}
@subsubheading Description @subsubheading Description
@@ -1156,13 +1316,7 @@ binary data type.
@sp 1 @sp 1
The @code{data} is a pointer to buffer containing the actual data for The @code{data} is a pointer to buffer containing the actual data for
the parameter represendted by @code{parameter_number}. The @code{length} the parameter represendted by @code{parameter_number}. The @code{length}
indicates the amount of data to be sent in bytes, and @code{is_last_data} is a indicates the amount of data to be sent in bytes.
boolean flag to indicate the end of the data. If it is != 0, then the
current call will be the end of the data, else it waits for the
application to send all data. If the application doesn't ended the data
supply from @code{mysql_send_long_data()}, then the
@code{mysql_execute()} will return @strong{MYSQL_NEED_DATA}.
@subsubheading Return Values @subsubheading Return Values
@@ -1176,10 +1330,14 @@ occured.
@table @code @table @code
@item CR_INVALID_PARAMETER_NO @item CR_INVALID_PARAMETER_NO
Invalid parameter number Invalid parameter number
@item CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
@item CR_SERVER_GONE_ERROR @item CR_SERVER_GONE_ERROR
The MySQL server has gone away The MySQL server has gone away
@item CR_OUT_OF_MEMOR
Out of memory
@item CR_UNKNOWN_ERROR @item CR_UNKNOWN_ERROR
An unkown error occured An unknown error occured
@end table @end table
@subsubheading Example @subsubheading Example
@@ -1200,9 +1358,7 @@ long length;
memset(bind, 0, sizeof(bind)); memset(bind, 0, sizeof(bind));
bind[0].buffer_type= MYSQL_TYPE_STRING; bind[0].buffer_type= MYSQL_TYPE_STRING;
bind[0].length= &length; bind[0].length= &length;
bind[0].is_null= 0;
/* Indicate that the data supply is in CHUNKS */
length= MYSQL_LONG_DATA;
/* Bind the buffers */ /* Bind the buffers */
if (mysql_bind_param(stmt, bind)) if (mysql_bind_param(stmt, bind))
@@ -1212,22 +1368,16 @@ long length;
exit(0); exit(0);
@} @}
/* Execute the insert statement - It should return MYSQL_NEED_DATA */
if (mysql_execute(stmt) != MYSQL_NEED_DATA)
@{
fprintf(stderr, "\n execute didn't retuned expected return code, MYSQL_NEED_DATA");
exit(0);
@}
/* Supply data in chunks to server */ /* Supply data in chunks to server */
if (!mysql_send_long_data(stmt,1,"MySQL",5,0)) if (!mysql_send_long_data(stmt,1,"MySQL",5))
@{ @{
fprintf(stderr, "\n send_long_data failed"); fprintf(stderr, "\n send_long_data failed");
fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
exit(0); exit(0);
@} @}
/* Supply the last piece of data */
if (mysql_send_long_data(stmt,1," - The most popular open source database",40,1)) /* Supply the next piece of data */
if (mysql_send_long_data(stmt,1," - The most popular open source database",40))
@{ @{
fprintf(stderr, "\n send_long_data failed"); fprintf(stderr, "\n send_long_data failed");
fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
@@ -1260,6 +1410,9 @@ long length;
Closes the prepared statement. @code{mysql_stmt_close()} also Closes the prepared statement. @code{mysql_stmt_close()} also
deallocates the statement handle pointed to by @code{stmt}. deallocates the statement handle pointed to by @code{stmt}.
If the current query results are pending or un-read; this cancels the
query results; so that next call can be executed.
@subsubheading Return Values @subsubheading Return Values
Zero if the statement was freed successfully. Non-zero if an error occured. Zero if the statement was freed successfully. Non-zero if an error occured.
@@ -1398,7 +1551,7 @@ None.
@node mysql_autocommit, , mysql_rollback, C Prepared statement functions @node mysql_autocommit, mysql_more_results, mysql_rollback, C Prepared statement functions
@subsubsection @code{mysql_autocommit()} @subsubsection @code{mysql_autocommit()}
@@ -1419,4 +1572,165 @@ Zero if successful. Non-zero if an error occured
None. None.
@node mysql_more_results, mysql_next_result, mysql_autocommit, C Prepared statement functions
@subsubsection @code{mysql_more_results()}
@findex @code{mysql_more_results()}.
@code{my_bool mysql_more_results(MYSQL *mysql)}
@subsubheading Description
Returns true if more results exists from the currently executed query,
and the application must call @code{mysql_next_result()} to fetch the
results.
@subsubheading Return Values
@code{TRUE} if more results exists. @code{FALSE} if no more results exists.
@subsubheading Errors
None.
@node mysql_next_result, , mysql_more_results, C Prepared statement functions
@subsubsection @code{mysql_next_result()}
@findex @code{mysql_next_result()}.
@code{int mysql_next_result(MYSQL *mysql)}
@subsubheading Description
If more query results exists, then @code{mysql_next_result()} reads the
next query results and returns the status back to application.
@subsubheading Return Values
Zero if successful. Non-zero if an error occured
@subsubheading Errors
None.
@node multiple queries, date handling, C Prepared statement functions, MySQL prepared statements
@subsection Handling multiple query executions
From version 4.1 and above, MySQL supports the multi query execution
using the single command. In order to do this, you must set the client flag
@code{CLIENT_MULTI_QUERIES} option during the connection.
@sp 1
By default @code{mysql_query()} or @code{mysql_real_query()} returns
only the first query status and the subsequent queries status can
be processed using @code{mysql_more_results()} and
@code{mysql_next_result()}.
@example
/* Connect to server with option CLIENT_MULTI_QUERIES */
mysql_real_query(..., CLIENT_MULTI_QUERIES);
/* Now execute multiple queries */
mysql_query(mysql,"DROP TABLE IF EXISTS test_table;\
CREATE TABLE test_table(id int);\
INSERT INTO test_table VALUES(10);\
UPDATE test_table SET id=20 WHERE id=10;\
SELECT * FROM test_table;\
DROP TABLE test_table";
while (mysql_more_results(mysql))
{
/* Process all results */
mysql_next_result(mysql);
...
printf("total affected rows: %lld", mysql_affected_rows(mysql));
...
if ((result= mysql_store_result(mysql))
{
/* Returned a result set, process it */
}
}
@end example
@node date handling, , multiple queries, MySQL prepared statements
@subsection Handling DATE, TIME and TIMESTAMP
Using the new binary protocol from MySQL 4.1 and above, one can send and
receive the DATE, TIME and TIMESTAMP data using the @code{MYSQL_TIME}
structure.
@code{MYSQL_TIME} structure consites of the following members:
@itemize @bullet
@item year
@item month
@item day
@item hour
@item minute
@item second
@item second_part
@end itemize
In order to send the data, one must use the prepared statements through
@code{mysql_prepare()} and @code{mysql_execute()}; and must bind the
parameter using type as @code{MYSQL_TYPE_DATE} inorder to process date
value, @code{MYSQL_TYPE_TIME} for time and @code{MYSQL_TYPE_DATETIME} or
@code{MYSQL_TYPE_TIMESTAMP} for datetime/timestamp using
@code{mysql_bind_param()} when sending and @code{mysql_bind_results()}
while receiving the data.
@sp 1
Here is a simple example; which inserts the DATE, TIME and TIMESTAMP data.
@example
MYSQL_TIME ts;
MYSQL_BIND bind[3];
MYSQL_STMT *stmt;
strmov(query, "INSERT INTO test_table(date_field, time_field,
timestamp_field) VALUES(?,?,?");
stmt= mysql_prepare(mysql, query, strlen(query)));
/* setup input buffers for all 3 parameters */
bind[0].buffer_type= MYSQL_TYPE_DATE;
bind[0].buffer= (char *)&ts;
bind[0].is_null= 0;
bind[0].length= 0;
..
bind[1]= bind[2]= bind[0];
..
mysql_bind_param(stmt, bind);
/* supply the data to be sent is the ts structure */
ts.year= 2002;
ts.month= 02;
ts.day= 03;
ts.hour= 10;
ts.minute= 45;
ts.second= 20;
mysql_execute(stmt);
..
@end example
@bye @bye