diff --git a/Docs/prepare.texi b/Docs/prepare.texi deleted file mode 100755 index 0b515012980..00000000000 --- a/Docs/prepare.texi +++ /dev/null @@ -1,1736 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c Copyright 1997-2002 TcX AB, Detron HB and MySQL Finland AB -@c -@c This manual is NOT distributed under a GPL style license. -@c Use of the manual is subject to the following terms: -@c - Conversion to other formats is allowed, but the actual -@c content may not be altered or edited in any way. -@c - You may create a printed copy for your own personal use. -@c - For all other uses, such as selling printed copies or -@c using (parts of) the manual in another publication, -@c prior written agreement from MySQL AB is required. -@c -@c Please e-mail docs@mysql.com for more information or if -@c you are interested in doing a translation. -@c -@c ********************************************************* -@c Note that @node names are used on our web site. -@c So do not change node names without checking -@c Makefile.am and SitePages first. -@c ********************************************************* -@c -@c %**start of header - -@c there's a better way to do this... i just don't know it yet -@c sed will remove the "@c ifnusphere " to make this valid -@c ifnusphere @set nusphere 1 - -@setfilename prepare.info - -@c We want the types in the same index -@c @syncodeindex tp fn - -@c Get version information. This file is generated by the Makefile!! -@include include.texi - -@ifclear tex-debug -@c This removes the black squares in the right margin -@finalout -@end ifclear - -@c Set background for HTML -@set _body_tags BGCOLOR=#FFFFFF TEXT=#000000 LINK=#101090 VLINK=#7030B0 -@c Set some style elements for the manual in HTML form. 'suggested' -@c natural language colors: aqua, black, blue, fuchsia, gray, green, -@c lime, maroon, navy, olive, purple, red, silver, teal, white, and -@c yellow. From Steeve Buehler -@set _extra_head - -@settitle MySQL Prepared Statements - -@c We want single-sided heading format, with chapters on new pages. To -@c get double-sided format change 'on' below to 'odd' -@ifclear nusphere -@setchapternewpage on -@end ifclear - -@ifset nusphere -@setchapternewpage odd -@end ifset - -@c @paragraphindent 0 - -@ifset nusphere -@smallbook -@end ifset - -@c @titlepage -@c @sp 10 -@c @center @titlefont{MySQL Prepared Statements} -@c @sp 10 -@c @right Copyright @copyright{} 1995-2003 MySQL AB -@c blank page after title page makes page 1 be a page front. -@c also makes the back of the title page blank. -@c @page -@c @end titlepage - -@c Short contents, blank page, long contents. -@c until i can figure out the blank page, no short contents. -@c @shortcontents -@c @page -@c @page -@contents - -@c This should be added. The HTML conversion also needs a MySQL version -@c number somewhere. - -@iftex -@c change this to double if you want formatting for double-sided -@c printing -@headings single -@end iftex - -@c @node Top, MySQL C API, (dir), (dir) - -@c @menu -@c * MySQL C API:: -@c @end menu - -@c @node MySQL C API, , Top, Top -@c @chapter MySQL C API - -@c @menu -@c * Prepared statements:: -@c @end menu - -@node Top, MySQL prepared statements, (dir), (dir) - -@menu -* MySQL prepared statements:: -@end menu - -@node MySQL prepared statements, , Top, Top -@chapter MySQL Prepared Statements - -@menu -* C Prepared statements:: -* C Prepared statement datatypes:: -* C Prepared statements function overview:: -* C Prepared statement functions:: -* multiple queries:: -* date handling:: -@end menu - -@node C Prepared statements, C Prepared statement datatypes, MySQL prepared statements, MySQL prepared statements -@subsection C Prepared Statements - -@sp 1 - -From MySQL 4.1 and above, you can also make use of the prepared -statements using the statement handler 'MYSQL_STMT', which supports -simultanious query executions along with input and output binding. - -@sp 1 - -Prepared execution is an efficient way to execute a statement more than -once. The statement is first parsed, or prepared. This is executed one -or more times at a later time using the statement handle that is -returned during the prepare. - -@sp 1 - -Another advantage of prepared statements is that, it uses a binary protocol -which makes the data tranfer between client and server in a more efficient -way than the old MySQL protocol. - -@sp 1 - -Prepared execution is faster than direct execution for statements -executed more than once, primarly becuase the query is parsed only -once; In the case of direct execution, the query is parsed every -time. Prepared execution also can provide a reduction in the network -traffic becuase during the execute call, it only sends the data for the -parameters. - - - -@node C Prepared statement datatypes, C Prepared statements function overview, C Prepared statements, MySQL prepared statements -@subsection C Prepared Statements DataTypes - -Prepared statements mainly uses the following two @code{MYSQL_STMT} and -@code{MYSQL_BIND} structures: -@sp 1 - -@table @code -@tindex MYSQL_STMT C type - -@item MYSQL_STMT - -This structure represents a statement handle to prepared statements.It -is used for all statement related functions. - -@sp 1 - -The statement is initialized when the query is prepared using -@code{mysql_prepare()}. - -@sp 1 - -One connection can have 'n' statement handles, and the limit depends up on -the system resources. - -@sp 1 - -@tindex MYSQL_BIND C type - -@item MYSQL_BIND - -This structure is used in order to bind parameter -buffers(@code{mysql_bind_param()}) inorder to the parameters data to -@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 - -@noindent -The @code{MYSQL_BIND} structure contains the members listed here: - - -@table @code - -@item enum enum_field_types buffer_type [input] -The type of the buffer. The @code{type} value must be one of the following: - - -@itemize @bullet -@item @code{MYSQL_TYPE_TINY} -@item @code{MYSQL_TYPE_SHORT} -@item @code{MYSQL_TYPE_LONG} -@item @code{MYSQL_TYPE_LONGLONG} -@item @code{MYSQL_TYPE_FLOAT} -@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_VAR_STRING} -@item @code{MYSQL_TYPE_TINY_BLOB} -@item @code{MYSQL_TYPE_MEDIUM_BLOB} -@item @code{MYSQL_TYPE_LONG_BLOB} -@item @code{MYSQL_TYPE_BLOB} -@end itemize -@sp 1 - -@item void *buffer [input/output] -A pointer to a buffer for the parameters data in case if it is used to -supply parameters data or pointer to a buffer in which to return the -data when the structure is used for result set bind. - -@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] -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 -buffer that, when @code{mysql_execute()} is called, contains the length -of the parameter value stored in *buffer. This is ignored except for -character or binary C data. - -If the length is a null pointer, then the protocol assumes that all -character and binary data are null terminated. - -When this structure is used in output binding, then @code{mysql_fetch()} -return the the length of the data that is returned. - -@sp 1 - -@item bool *is_null [input/output] -Indicates if the parameter data is NULL or fetched data is NULL. -@end table - -@sp 1 - -@tindex MySQL C type - -@item MYSQL_TIME - -This structure is used to send and receive DATE, TIME and -TIMESTAMP data directly to/from server. - -@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 - - -@node C Prepared statements function overview, C Prepared statement functions, C Prepared statement datatypes, MySQL prepared statements -@subsection C Prepared Statements Function Overview - -@cindex C Prepared statements API, functions -@cindex functions, C Prepared statements API - -The functions available in the prepared statements are listed here and -are described in greater detail in the later section. -@xref{C Prepared statement functions}. - -@multitable @columnfractions .32 .68 -@item @strong{Function} @tab @strong{Description} - -@item @strong{mysql_prepare()} @tab Prepares an SQL string for execution. - -@item @strong{mysql_param_count()} @tab Returns the number of parameters in a prepared SQL statement. - -@item @strong{mysql_prepare_result()} @tab Returns prepared statement meta information in the form of resultset. - -@item @strong{mysql_bind_param()} @tab Binds a buffer to parameter markers in a prepared SQL statement. - -@item @strong{mysql_execute()} @tab Executes the prepared statement. - -@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_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_stmt_close()} @tab Frees memory used by prepared statement. - -@item @strong{mysql_stmt_errno()} @tab Returns the error number for the last statement execution. - -@item @strong{mysql_stmt_error()} @tab Returns the error message for the last statement execution. - -@item @strong{mysql_send_long_data()} @tab Sends long data in chunks to server. - -@c TO BE MOVED TO MAIN C API FUCTIONS -@item @strong{mysql_commit()} @tab Commits the transaction. - -@item @strong{mysql_rollback()} @tab Rollbacks the transaction. - -@item @strong{mysql_autocommit()} @tab Toggles the autocommit mode to on/off. - -@item @strong{mysql_more_results()} @tab Returns if there are any more results exists - -@item @strong{mysql_next_result()} @tab Returns/Initiates the next result in the multi-query executions - -@end multitable - -@sp 1 - -Call @code{mysql_prepare()} to prepare and initialize the statement -handle, then call @code{mysql_bind_param()} to supply the parameters -data, and then call @code{mysql_execute()} to execute the query. You can -repeat the @code{mysql_execute()} by changing parameter values from the -respective buffer supplied through @code{mysql_bind_param()}. - -@sp 1 - - -In case if the query is a SELECT statement or any other query which -results in a resultset, then mysql_prepare() will also return the result -set meta data information in the form of @code{MYSQL_RES } result set -through @code{mysql_prepare_result()}. - -@sp 1 - -You can supply the result buffers using @code{mysql_bind_result()}, so -that the @code{mysql_fetch()} will automatically returns data to this -buffers. This is row by row fetching. - -@sp 1 - -You can also send the text or binary data in chunks to server using -@code{mysql_send_long_data()}, by specifying the option is_long_data=1 -or length=MYSQL_LONG_DATA or -2 in the MYSQL_BIND structure supplied -with @code{mysql_bind_param()}. - -@sp 1 - -Once the statement execution is over, it must be freed using -@code{mysql_stmt_close} so that it frees all the alloced resources for -the statement handle. - - -@subsubheading Execution Steps: - -To prepare and execute a statement, the application: - -@itemize @bullet -@item -Calls @strong{mysql_prepare()} and passes it a string containing the SQL -statement. On a successful prepare, mysql_prepare returns the valid statement -handle back to the application -@item -If the query results in a resultset, then @strong{mysql_prepare_result} -returns the result set meta info.. -@item -Sets the values of any parameters using @strong{mysql_bind_param}. All -parameters must be set; else it will return an error or produce -un-expected results -@item -Calls @strong{mysql_execute} to execute the statement. -@item -Repeat steps 2 and 3 as necessary, by changing the parameter values and -re-executing the statement. -@item -Bind the data buffers to return the row values, if it is a result set -query; using @strong{mysql_bind_result()}. -@item -Fetch the data to buffers row by row by calling @strong{mysql_fetch()} -repetedely until no more rows found. -@item -When @strong{mysql_prepare()} is called, in the MySQL client/server protocol: -@itemize @minus -@item -Server parses the query and sends the ok status back to client by -assinging a statement id. It also sends total number of parameters, -columns count and its meta information if it is a result set oriented -query. All syntax and symantecs of the query is checked during this call -by the server. -@item -Client uses this statement id for the further executions, so that server -identifies the statement back from the pool of statements. Now, client -allocates a statement handle with this id and returns back to -application. -@end itemize -@item -When @strong{mysql_execute()} is called, in the MySQL client/server protocol: -@itemize @minus -@item -Client uses the statement handle and sends the parameters data to -server. -@item -Server identifies the statement using the id provided by the client, and -replaces the parameter markers with the newly supplied data and executes -the query. If it results in a result set, then sends the data back to -client, else sends an OK status with total number of rows -changes/deleted/inserted. -@end itemize -@item -When @strong{mysql_fetch()} is called, in the MySQL client/server protocol: -@itemize @minus -@item -Client reads the data from the packet row by row and places it to -application data buffers by doing the necessary conversions. If the -application buffer type is same as that of field type, then the -conversions are stright forward. -@end itemize -@end itemize - - - -You can get the statement error code and message using -@code{mysql_stmt_errno()} and @code{mysql_stmt_error()} respectively. - - -@node C Prepared statement functions, multiple queries, C Prepared statements function overview, MySQL prepared statements -@subsection C Prepared Statement Function Descriptions - -You need to use the following functions when you want to prepare and -execute the queries. - - -@menu -* mysql_prepare:: @code{mysql_prepare()} -* mysql_param_count:: @code{mysql_param_count()} -* mysql_prepare_result:: @code{mysql_prepare_result()} -* mysql_bind_param:: @code{mysql_bind_param()} -* mysql_execute:: @code{mysql_execute()} -* mysql_stmt_affected_rows:: @code{mysql_stmt_affected_rows()} -* mysql_bind_result:: @code{mysql_bind_result()} -* mysql_stmt_store_result:: @code{mysql_stmt_store_result()} -* mysql_fetch:: @code{mysql_fetch()} -* mysql_send_long_data:: @code{mysql_send_long_data()} -* mysql_stmt_close:: @code{mysql_stmt_close()} -* mysql_stmt_errno:: @code{mysql_stmt_errno()} -* mysql_stmt_error:: @code{mysql_stmt_error()} -* mysql_commit:: @code{mysql_commit()} -* 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 - -@node mysql_prepare, mysql_param_count, C Prepared statement functions, C Prepared statement functions -@subsubsection @code{mysql_prepare()} - -@findex @code{mysql_prepare()} - -@code{MYSQL_STMT * mysql_prepare(MYSQL *mysql, const char *query, unsigned -long length)} - -@subsubheading Description - -Prepares the SQL query pointed to by the null-terminated string -'query'. The query must consist of a single SQL statement. You should -not add a terminating semicolon (`;`) or \g to the statement. - -@sp 1 -The application can include one or more parameter markers in the SQL -statement. To include a parameter marker, the appication embeds a -question mark (@code{?}) into the SQL string at the appropriate -position. - -@sp 1 -The markers are legal only in certain places in SQL statements. For -example, they are not allowed in the select list(the list of columns to -be returned by a SELECT statement), nor are they allowed as both -operands of a binary operator such as the equal sign (=), becuase it -would be impossible to determine the parameter type. In general, -parameters are legal only in Data Manipulation Languange(DML) -statements, and not in Data Defination Language(DDL) statements. - -@sp 1 -The parameter markers are then bound to application variables using -@code{mysql_bind_param()}. - - - -@subsubheading Return Values - -@code{MYSQL_STMT} if the prepare was successful. NULL if an error -occured. - -@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 -NULL statement, errors can be obtained by calling @code{mysql_error()}. - - -@subsubheading Example - -For the usage of @code{mysql_prepare()} refer to the Example from -@ref{mysql_execute,mysql_execute()}. - - - - -@node mysql_param_count, mysql_prepare_result, mysql_prepare, C Prepared statement functions -@subsubsection @code{mysql_param_count()} - -@findex @code{mysql_param_count()} - -@code{unsigned int mysql_param_count(MYSQL_STMT *stmt)} - -@subsubheading Description - -Returns the number of parameter markers present from the prepared query. - -@subsubheading Return Values - -An unsigned integer representing the number of parameters in a -statement. - -@subsubheading Errors - -None - -@subsubheading Example - -For the usage of @code{mysql_param_count()} refer to the Example from -@ref{mysql_execute,mysql_execute()}. - - - -@node mysql_prepare_result, mysql_bind_param, mysql_param_count, C Prepared statement functions -@subsubsection @code{mysql_prepare_result()} - - -@findex @code{mysql_prepare_result}. - -@code{MYSQL_RES *mysql_prepare_result(MYSQL_STMT *stmt)} - -@subsubheading Description - -If the @code{mysql_prepare()} resulted in a result set query, then -@code{mysql_prepare_result()} returns the result set meta data in the form of -@code{MYSQL_RES} structure; which can further be used to process the -meta information such as total number of fields and individual field -information. This resulted result set can be passed as an argument to -any of the field based APIs in order to process the result set meta data -information such as: - -@itemize @minus -@item -mysql_num_fields() -@item -mysql_fetch_field() -@item -mysql_fetch_field_direct() -@item -mysql_fetch_fields() -@item -mysql_field_count() -@item -mysql_field_seek() -@item -mysql_field_tell() and -@item -mysql_free_result() -@end itemize - - -@subsubheading Return Values - -A @code{MYSQL_RES} result structure. NULL if no meta information exists from -the prepared query. - - -@subsubheading Errors - -@item CR_OUT_OF_MEMOR -Out of memory -@item CR_UNKNOWN_ERROR -An unknown error occured - -None - - -@subsubheading Example - -For the usage of @code{mysql_prepare_result()} refer to the Example from -@ref{mysql_fetch,mysql_fetch()} - - - -@node mysql_bind_param, mysql_execute, mysql_prepare_result, C Prepared statement functions -@subsubsection @code{mysql_bind_param()} - -@findex @code{mysql_bind_param()} - -@code{int mysql_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)} - -@subsubheading Description - -@code{mysql_bind_param} is used to bind data for the parameter markers -in the SQL statement from @code{mysql_prepare}. It uses the structure -MYSQL_BIND to supply the data. - -The supported buffer types are: - -@itemize @bullet -@item -MYSQL_TYPE_TINY -@item -MYSQL_TYPE_SHORT -@item -MYSQL_TYPE_LONG -@item -MYSQL_TYPE_LONGLONG -@item -MYSQL_TYPE_FLOAT -@item -MYSQL_TYPE_DOUBLE -@item -MYSQL_TYPE_TIME -@item -MYSQL_TYPE_DATE -@item -MYSQL_TYPE_DATETIME -@item -MYSQL_TYPE_TIMESTAMP -@item -MYSQL_TYPE_STRING -@item -MYSQL_TYPE_VAR_STRING -@item -MYSQL_TYPE_TINY_BLOB -@item -MYSQL_TYPE_MEDIUM_BLOB -@item -MYSQL_TYPE_LONG_BLOB -@end itemize - -@subsubheading Return Values - -Zero if the bind was successful. Non-zero if an error occured. - -@subsubheading Errors -@table @code -@item CR_NO_PREPARE_STMT -No prepared statement exists -@item CR_NO_PARAMETERS_EXISTS -No parameters exists to bind -@item CR_INVALID_BUFFER_USE -Indicates if the bind is to supply the long data in chunks and if the -buffer type is non string or binary -@item CR_UNSUPPORTED_PARAM_TYPE -The conversion is not supported, possibly the buffer_type is illegal or -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 - -@subsubheading Example - -For the usage of @code{mysql_bind_param()} refer to the Example from -@ref{mysql_execute,mysql_execute()}. - - - -@node mysql_execute, mysql_stmt_affected_rows, mysql_bind_param, C Prepared statement functions -@subsubsection @code{mysql_execute()} - -@findex @code{mysql_execute()} - -@code{int mysql_execute(MYSQL_STMT *stmt}. - -@subsubheading Description - -@code{mysql_execute()} executes the prepared query associated with the -statement handle. The parameter marker values will be sent to server -during this call, so that server replaces markers with this newly -supplied data. - -@sp 1 - -If the statement is UPDATE,DELETE,or INSERT, the total number of -changed/deletd/inserted values can be found by calling -@code{mysql_stmt_affected_rows}. If this is a result set query, then one -must call @code{mysql_fetch()} to fetch the data prior to calling any -other calls which results in query processing. For more information on -how to fetch the statement binary data, refer to @ref{mysql_fetch}. - - -@subsubheading Return Values - -@code{mysql_execute()} returns the following return values: - -@multitable @columnfractions .30 .65 -@item @strong{Return Value} @tab @strong{Description} -@item 0 @tab Successful -@item 1 @tab Error occured. Error code and -message can be obtained by calling @code{mysql_stmt_errno()} and @code{mysql_stmt_error()}. -@end multitable - - -@subsubheading Errors - -@table @code -@item CR_NO_PREPARE_QUERY -No query prepared prior to execution -@item CR_ALL_PARAMS_NOT_BOUND -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 -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 - - -@subsubheading Example - -The following example explains the uasage of @code{mysql_prepare}, -@code{mysql_param_count}, @code{mysql_bind_param}, @code{mysql_execute} -and @code{mysql_stmt_affected_rows()}. - -@example - -MYSQL_BIND bind[3]; -MYSQL_STMT *stmt; -ulonglong affected_rows; -long length; -unsigned int param_count; -int int_data; -short small_data; -char str_data[50], query[255]; -my_bool is_null; - - /* Set autocommit mode to true */ - mysql_autocommit(mysql, 1); - - if (mysql_query(mysql,"DROP TABLE IF EXISTS test_table")) - @{ - fprintf(stderr, "\n drop table failed"); - fprintf(stderr, "\n %s", mysql_error(mysql)); - exit(0); - @} - if (mysql_query(mysql,"CREATE TABLE test_table(col1 int, col2 varchar(50), \ - col3 smallint,\ - col4 timestamp(14))")) - @{ - fprintf(stderr, "\n create table failed"); - fprintf(stderr, "\n %s", mysql_error(mysql)); - exit(0); - @} - - /* Prepare a insert query with 3 parameters */ - strmov(query, "INSERT INTO test_table(col1,col2,col3) values(?,?,?)"); - if(!(stmt = mysql_prepare(mysql, query, strlen(query)))) - @{ - fprintf(stderr, "\n prepare, insert failed"); - fprintf(stderr, "\n %s", mysql_error(mysql)); - exit(0); - @} - fprintf(stdout, "\n prepare, insert successful"); - - /* Get the parameter count from the statement */ - param_count= mysql_param_count(stmt); - - fprintf(stdout, "\n total parameters in insert: %d", param_count); - if (param_count != 3) /* validate parameter count */ - @{ - fprintf(stderr, "\n invalid parameter count returned by MySQL"); - exit(0); - @} - - /* Bind the data for the parameters */ - - /* INTEGER PART */ - bind[0].buffer_type= MYSQL_TYPE_LONG; - bind[0].buffer= (char *)&int_data; - bind[0].is_null= 0; - bind[0].length= 0; - - /* STRING PART */ - bind[1].buffer_type= MYSQL_TYPE_VAR_STRING; - bind[1].buffer= (char *)str_data; - bind[1].buffer_length= sizeof(str_data); - bind[1].is_null= 0; - bind[1].length= 0; - - /* SMALLINT PART */ - bind[2].buffer_type= MYSQL_TYPE_SHORT; - bind[2].buffer= (char *)&small_data; - bind[2].is_null= &is_null; - bind[2].length= 0; - is_null= 0; - - - /* Bind the buffers */ - if (mysql_bind_param(stmt, bind)) - @{ - fprintf(stderr, "\n param bind failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* Specify the data */ - int_data= 10; /* integer */ - strcpy(str_data,"MySQL"); /* string */ - - /* INSERT SMALLINT data as NULL */ - is_null= 1; - - /* Execute the insert statement - 1*/ - if (mysql_execute(stmt)) - @{ - fprintf(stderr, "\n execute 1 failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - fprintf(stderr, "\n send a bug report to bugs@@lists.mysql.com, by asking why this is not working ?"); - exit(0); - @} - - /* Get the total rows affected */ - affected_rows= mysql_stmt_affected_rows(stmt); - - fprintf(stdout, "\n total affected rows: %lld", affected_rows); - if (affected_rows != 1) /* validate affected rows */ - @{ - fprintf(stderr, "\n invalid affected rows by MySQL"); - exit(0); - @} - - /* Re-execute the insert, by changing the values */ - int_data= 1000; - strcpy(str_data,"The most popular open source database"); - small_data= 1000; /* smallint */ - is_null= 0; /* reset NULL */ - - /* Execute the insert statement - 2*/ - if (mysql_execute(stmt)) - @{ - fprintf(stderr, "\n execute 2 failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* Get the total rows affected */ - affected_rows= mysql_stmt_affected_rows(stmt); - - fprintf(stdout, "\n total affected rows: %lld", affected_rows); - if (affected_rows != 1) /* validate affected rows */ - @{ - fprintf(stderr, "\n invalid affected rows by MySQL"); - exit(0); - @} - - /* Close the statement */ - if (mysql_stmt_close(stmt)) - @{ - fprintf(stderr, "\n failed while closing the statement"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* DROP THE TABLE */ - if (mysql_query(mysql,"DROP TABLE test_table")) - @{ - fprintf(stderr, "\n drop table failed"); - fprintf(stderr, "\n %s", mysql_error(mysql)); - exit(0); - @} - fprintf(stdout, "Success, MySQL prepared statements are working!!!"); -@end example - - - - -@node mysql_stmt_affected_rows, mysql_bind_result, mysql_execute, C Prepared statement functions -@subsubsection @code{mysql_stmt_affected_rows()} - -@findex @code{mysql_stmt_affected_rows()} - -@code{ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)} - -@subsubheading Description - -Returns total number of rows changed by the last execute statement. May -be called immediatlely after mysql_execute() for UPDATE,DELETE,or INSERT -statements.For SELECT statements, mysql_stmt_affected rows works like -mysql_num_rows(). - -@subsubheading Return Values - -An integer greater than zero indicates the number of rows affected or -retrieved. Zero indicates that no records where updated for an UPDATE -statement, no rows matched the WHERE clause in the query or that no -query has yet been executed. -1 indicates that the query returned an -error or that, for a SELECT query, mysql_stmt_affected_rows() was called -prior to calling mysql_fetch(). - -@subsubheading Errors - -None. - -@subsubheading Example - -For the usage of @code{mysql_stmt_affected_rows()} refer to the Example -from @ref{mysql_execute,mysql_execute()}. - - - - - -@node mysql_bind_result, mysql_stmt_store_result, mysql_stmt_affected_rows, C Prepared statement functions -@subsubsection @code{mysql_bind_result()} - -@findex @code{mysql_bind_result()} - -@code{my_bool mysql_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)} - -@subsubheading Description - -@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 -called to fetch data, the MySQL client protocol returns the data for the -bound columns in the specified buffers. - -@sp 1 - -Note that all columns must be bound prior to calling @code{mysql_fetch()} -in case of fetching the data to buffers; else @code{mysql_fetch()} simply ignores -the data fetch; also the buffers should be sufficient enough to hold the -data as the ptotocol doesn't return the data in chunks. - -@sp 1 - -A column can be bound or rebound at any time, even after data has been -fetched from the result set. The new binding takes effect the next time -@code{mysql_fetch()} is called. For example, suppose an application binds -the columns in a result set and calls @code{mysql_fetch()}. The mysql -protocol returns data in the bound buffers. Now suppose the application -binds the columns to a different set of buffers, then the protocol does -not place the data for the just fetched row in the newly bound -buffers. Instead, it does when the next @code{mysql_fetch()} is called. - -@sp 1 - -To bind a column, an application calls @code{mysql_bind_result()} and -passes the type, address, and the address of the length buffer. - -The supported buffer types are: - -@itemize @bullet -@item -MYSQL_TYPE_TINY -@item -MYSQL_TYPE_SHORT -@item -MYSQL_TYPE_LONG -@item -MYSQL_TYPE_LONGLONG -@item -MYSQL_TYPE_FLOAT -@item -MYSQL_TYPE_DOUBLE -@item -MYSQL_TYPE_TIME -@item -MYSQL_TYPE_DATE -@item -MYSQL_TYPE_DATETIME -@item -MYSQL_TYPE_TIMESTAMP -@item -MYSQL_TYPE_STRING -@item -MYSQL_TYPE_VAR_STRING -@item -MYSQL_TYPE_BLOB -@item -MYSQL_TYPE_TINY_BLOB -@item -MYSQL_TYPE_MEDIUM_BLOB -@item -MYSQL_TYPE_LONG_BLOB -@end itemize - -@subsubheading Return Values - -Zero if the bind was successful. Non-zero if an error occured. - -@subsubheading Errors - -@table @code -@item CR_NO_PREPARE_STMT -No prepared statement exists -@item CR_UNSUPPORTED_PARAM_TYPE -The conversion is not supported, possibly the buffer_type is illegal or -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 - -@subsubheading Example - -For the usage of @code{mysql_bind_result()} refer to the Example from -@ref{mysql_fetch,mysql_fetch()} - - - - -@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()} - -@findex code{mysql_fetch()} - -@code{int mysql_fetch(MYSQL_STMT *stmt)} - -@subsubheading Description - -@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 -@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 - -If row buffers are bound using @code{mysql_bind_result()}, it returns -the data in those buffers for all the columns in the current row -set and the lengths are returned to the length pointer. - -@sp 1 -Note that, all columns must be bound by the application. - -@sp 1 -If the data fetched is a NULL data, then the @code{is_null} value from -@code{MYSQL_BIND} contains TRUE, 1, else the data and its length is -returned to @code{*buffer} and @code{*length} variables based on the -buffer type specified by the application. All numeric, float and double -types have the fixed length(in bytes) as listed below: - - -@multitable @columnfractions .10 .30 -@item @strong{Type} @tab @strong{Length} -@item MYSQL_TYPE_TINY @tab 1 -@item MYSQL_TYPE_SHORT @tab 2 -@item MYSQL_TYPE_LONG @tab 4 -@item MYSQL_TYPE_FLOAT @tab 4 -@item MYSQL_TYPE_LONGLONG @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_VAR_STRING @tab data_length -@item MYSQL_TYPE_BLOB @tab data_length -@item MYSQL_TYPE_TINY_BLOB @tab data_length -@item MYSQL_TYPE_MEDIUM_BLOB @tab data_length -@item MYSQL_TYPE_LONG_BLOB @tab data_length -@end multitable - -@* -where @code{*data_length} is nothing but the 'Actual length of the data'. - -@subsubheading Return Values - -@multitable @columnfractions .30 .65 -@item @strong{Return Value} @tab @strong{Description} -@item 0 @tab Successful, the data has been -fetched to application data buffers. -@item 1 @tab Error occured. Error code and -message can be obtained by calling @code{mysql_stmt_errno()} and @code{mysql_stmt_error()}. -@item 100, MYSQL_NO_DATA @tab No more rows/data exists -@end multitable - - -@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. -@item CR_UNSUPPORTED_PARAM_TYPE -If the buffer type is MYSQL_TYPE_DATE,DATETIME,TIME,or TIMESTAMP; and if -the field type is not DATE, TIME, DATETIME or TIMESTAMP. -@item -All other unsupported conversion errors are returned from -@code{mysql_bind_result()}. -@end table - -@subsubheading Example - -The following example explains the usage of @code{mysql_prepare_result}, -@code{mysql_bind_result()}, and @code{mysql_fetch()} - -@example - -MYSQL_STMT *stmt; -MYSQL_BIND bind[2]; -MYSQL_RES *result; -int int_data; -long int_length, str_length; -char str_data[50]; -my_bool is_null[2]; - - query= "SELECT col1, col2 FROM test_table WHERE col1= 10)"); - if (!(stmt= mysql_prepare(&mysql, query, strlen(query))) - @{ - fprintf(stderr, "\n prepare failed"); - fprintf(stderr, "\n %s", mysql_error(&stmt)); - exit(0); - @} - - /* Get the fields meta information */ - if (!(result= mysql_prepare_result(stmt))) - @{ - fprintf(stderr, "\n prepare_result failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - fprintf(stdout, "Total fields: %ld", mysql_num_fields(result)); - - if (mysql_num_fields(result) != 2) - @{ - fprintf(stderr, "\n prepare returned invalid field count"); - exit(0); - @} - - /* Execute the SELECT query */ - if (mysql_execute(stmt)) - @{ - fprintf(stderr, "\n execute failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* Bind the result data buffers */ - bind[0].buffer_type= MYSQL_TYPE_LONG; - bind[0].buffer= (char *)&int_data; - bind[0].is_null= &is_null[0]; - bind[0].length= &int_length; - - bind[1].buffer_type= MYSQL_TYPE_VAR_STRING; - bind[1].buffer= (void *)str_data; - bind[1].is_null= &is_null[1]; - bind[1].length= &str_length; - - if (mysql_bind_result(stmt, bind)) - @{ - fprintf(stderr, "\n bind_result failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* Now fetch data to buffers */ - if (mysql_fetch(stmt)) - @{ - fprintf(stderr, "\n fetch failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - if (is_null[0]) - 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 */ - if (mysql_fetch(stmt) |= MYSQL_NO_DATA) - @{ - fprintf(stderr, "\n fetch return more than one row); - exit(0); - @} - - /* Free the prepare result meta information */ - mysql_free_result(result); - - /* Free the statement handle */ - if (mysql_stmt_free(stmt)) - @{ - fprintf(stderr, "\n failed to free the statement handle); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - -@end example - - - -@node mysql_send_long_data, mysql_stmt_close, mysql_fetch, C Prepared statement functions -@subsubsection @code{mysql_send_long_data()} - - -@findex @code{mysql_send_long_data()}. - -@code{int mysql_send_long_data(MYSQL_STMT *stmt, unsigned int -parameter_number, const char *data, ulong length)} - -@subsubheading Description - -Allows an application to send the data in pieces or chunks to -server. This function can be used to send character or binary data -values in parts to a column(it must be a text or blob) with a character or -binary data type. - -@sp 1 -The @code{data} is a pointer to buffer containing the actual data for -the parameter represendted by @code{parameter_number}. The @code{length} -indicates the amount of data to be sent in bytes. - - -@subsubheading Return Values - -Zero if the data is sent successfully to server. Non-zero if an error -occured. - - -@subsubheading Errors - -@table @code -@item CR_INVALID_PARAMETER_NO -Invalid parameter number -@item CR_COMMANDS_OUT_OF_SYNC -Commands were executed in an improper order. -@item CR_SERVER_GONE_ERROR -The MySQL server has gone away -@item CR_OUT_OF_MEMOR -Out of memory -@item CR_UNKNOWN_ERROR -An unknown error occured -@end table - -@subsubheading Example -The following example explains how to send the data in chunks to text -column: -@example - -MYSQL_BIND bind[1]; -long length; - - query= "INSERT INTO test_long_data(text_column) VALUES(?)"); - if (!mysql_prepare(&mysql, query, strlen(query)) - @{ - fprintf(stderr, "\n prepare failed"); - fprintf(stderr, "\n %s", mysql_error(&stmt)); - exit(0); - @} - memset(bind, 0, sizeof(bind)); - bind[0].buffer_type= MYSQL_TYPE_STRING; - bind[0].length= &length; - bind[0].is_null= 0; - - /* Bind the buffers */ - if (mysql_bind_param(stmt, bind)) - @{ - fprintf(stderr, "\n param bind failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* Supply data in chunks to server */ - if (!mysql_send_long_data(stmt,1,"MySQL",5)) - @{ - fprintf(stderr, "\n send_long_data failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* 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 %s", mysql_stmt_error(stmt)); - exit(0); - @} - - /* Now, execute the query */ - if (mysql_execute(stmt)) - @{ - fprintf(stderr, "\n mysql_execute failed"); - fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); - exit(0); - @} - - This inserts the data, "MySQL - The most popular open source database" - to the field 'text_column'. -@end example - - - -@node mysql_stmt_close, mysql_stmt_errno, mysql_send_long_data, C Prepared statement functions -@subsubsection @code{mysql_stmt_close()} - -@findex @code{mysql_stmt_close()} - -@code{my_bool mysql_stmt_close(MYSQL_STMT *)} - -@subsubheading Description - -Closes the prepared statement. @code{mysql_stmt_close()} also -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 - -Zero if the statement was freed successfully. Non-zero if an error occured. - - -@subsubheading Errors - -@table @code -@item CR_SERVER_GONE_ERROR -The MySQL server has gone away -@item CR_UNKNOWN_ERROR -An unkown error occured -@end table - -@subsubheading Example - -For the usage of @code{mysql_stmt_close()} refer to the Example from -@ref{mysql_execute,mysql_execute()}. - - - -@node mysql_stmt_errno, mysql_stmt_error, mysql_stmt_close, C Prepared statement functions -@subsubsection @code{mysql_stmt_errno()} - - -@findex @code{mysql_stmt_errno()} - -@code{unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)} - -@subsubheading Description - -For the statement specified by @code{stmt}, @code{mysql_stmt_errno()} -returns the error code for the most recently invoked statement API -function that can succeed or fail. A return value of zero means that no -error occured. Client error message numbers are listed in the MySQL -errmsg.h header file. Server error message numbers are listed in -mysqld_error.h. In the MySQL source distribution you can find a complete -list of error messages and error numbers in the file Docs/mysqld_error.txt - -@subsubheading Return Values - -An error code value. Zero if no error occured. - -@subsubheading Errors - -None - - -@node mysql_stmt_error, mysql_commit, mysql_stmt_errno, C Prepared statement functions -@subsubsection @code{mysql_stmt_error()} - - -@findex @code{mysql_stmt_error()}. - -@code{char *mysql_stmt_error(MYSQL_STMT *stmt)} - -@subsubheading Description - -For the statement specified by @code{stmt}, @code{mysql_stmt_error()} -returns the error message for the most recently invoked statement API -that can succeed or fail. An empty string ("") is returned if no error -occured. This means the following two sets are equivalent: - -@example - -if (mysql_stmt_errno(stmt)) -@{ - // an error occured -@} - -if (mysql_stmt_error(stmt)) -@{ - // an error occured -@} -@end example - -The language of the client error messages many be changed by recompiling -the MySQL client library. Currently you can choose error messages in -several different languages. - - -@subsubheading Return Values - -A character string that describes the error. An empry string if no error -occured. - -@subsubheading Errors - -None - - - -@node mysql_commit, mysql_rollback, mysql_stmt_error, C Prepared statement functions -@subsubsection @code{mysql_commit()} - - -@findex @code{mysql_commit()}. - -@code{my_bool mysql_commit(MYSQL *mysql)} - -@subsubheading Description - -Commits the current transaction - -@subsubheading Return Values - -Zero if successful. Non-zero if an error occured. - -@subsubheading Errors - -None - - - -@node mysql_rollback, mysql_autocommit, mysql_commit, C Prepared statement functions -@subsubsection @code{mysql_rollback()} - - -@findex @code{mysql_rollback()}. - -@code{my_bool mysql_rollback(MYSQL *mysql)} - -@subsubheading Description - -Rollbacks the current transaction. - - -@subsubheading Return Values - -Zero if successful. Non-zero if an error occured. - -@subsubheading Errors - -None. - - - - -@node mysql_autocommit, mysql_more_results, mysql_rollback, C Prepared statement functions -@subsubsection @code{mysql_autocommit()} - - -@findex @code{mysql_autocommit()}. - -@code{my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)} - -@subsubheading Description - -Sets the autocommit mode to on or off. If the @code{mode} is '1', then it -sets the autocommit mode to on, else to off in case of '0'. - -@subsubheading Return Values - -Zero if successful. Non-zero if an error occured - -@subsubheading Errors - -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