Merge sinisa@work.mysql.com:/home/bk/mysql-4.1

into sinisa.nasamreza.org:/mnt/work/mysql-4.1

Docs/prepare.texi

+\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 <ahr@YogElements.com>
+@set _extra_head <style> code {color:purple} tt {color:green} samp {color:navy} pre {color:maroon} </style>
+
+@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::  
+@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 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 inorder to
+send the parameters data to @code{mysql_execute()} call; as well as to
+bind row buffers to fetch the result set data using @code{mysql_fetch()}.
+@end table
+
+@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_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 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 one of the 
+following:
+
+@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
+input parameter values are non-NULL and that character and binary data
+are null terminated.
+
+
+When this structure is used in output binding, then @code{mysql_fetch()}
+return the following values in the length buffer:
+
+@itemize @bullet
+@item
+The length of the data that is returned
+@item
+MYSQL_NULL_DATA, indicating the data returned is a NULL data.
+@end itemize
+
+
+@c @item bool is_null [input]
+@c To indicate the parameter data is NULL. This is same as supplying
+@c MYSQL_NULL_DATA, -1 as the length in length pointer.
+
+
+@c @item bool is_long_data [input]
+@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
+@c same as supplying MYSQL_LONG_DATA, -2 as the length in length pointer.
+@c @end table
+@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_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,  , 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::               
+* mysql_param_count::           
+* mysql_prepare_result::        
+* mysql_bind_param::            
+* mysql_execute::               
+* mysql_stmt_affected_rows::    
+* mysql_bind_result::           
+* mysql_fetch::                 
+* mysql_send_long_data::        
+* mysql_stmt_close::            
+* mysql_stmt_errno::            
+* mysql_stmt_error::            
+* mysql_commit::                
+* mysql_rollback::              
+* mysql_autocommit::            
+@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
+
+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
+
+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_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.
+@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 MYSQL_SUCCESS,      0            @tab Successful
+@item MYSQL_STATUS_ERROR, 1            @tab Error occured. Error code and
+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
+
+
+@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_SERVER_GONE_ERROR
+The MySQL server has gone away
+@item CR_UNKNOWN_ERROR
+An unkown error occured
+@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;
+char         str_data[50], query[255];
+
+  /* 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 */
+  strcpy(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 */
+  memset(bind,0,sizeof(bind));
+  bind[0].buffer_type= MYSQL_TYPE_LONG;
+  bind[0].buffer= (void *)&int_data;
+ 
+  /* STRING PART */
+  bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
+  bind[1].buffer= (void *)str_data;
+  bind[1].buffer_length= sizeof(str_data);
+ 
+  /* SMALLINT PART */
+  bind[2].buffer_type= MYSQL_TYPE_SHORT;
+  bind[2].buffer= (void *)&small_data;       
+  bind[2].length= (long *)&length;
+
+  /* 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 */
+  length= MYSQL_NULL_DATA;
+
+  /* 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 */
+  length= 0;
+
+  /* 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 great !!!");
+@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_fetch, 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 ised 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_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.
+@end table
+
+@subsubheading Example
+
+For the usage of @code{mysql_bind_result()} refer to the Example from
+@ref{mysql_fetch,mysql_fetch()}
+
+
+
+@node mysql_fetch, mysql_send_long_data, mysql_bind_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.
+
+@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 length buffer will have a
+value of @strong{MYSQL_NULL_DATA}, -1, else it will have the length of
+the data being fetched 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_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 MYSQL_SUCCESS,      0            @tab Successful, the data has been
+fetched to application data buffers.
+@item MYSQL_STATUS_ERROR, 1            @tab Error occured. Error code and
+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
+@end multitable
+
+
+@subsubheading Errors
+@table @code
+@item CR_UNSUPPORTED_PARAM_TYPE
+If the field type is DATE,DATETIME,TIME,or TIMESTAMP; and the
+application buffer type is non string based.
+@item
+All other un-supported conversions 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];
+
+  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 didn't retuned expected return code, MYSQL_NEED_DATA");
+    exit(0);
+  @}
+
+  /* Bind the result data buffers */
+  bzero(bind, 0, sizeof(bind));
+
+  bind[0].buffer_type= MYSQL_TYPE_LONG;
+  bind[0].buffer= (void *)&int_data;
+  bind[0].length= &int_length;
+
+  bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
+  bind[1].buffer= (void *)str_data;
+  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);
+  @}  
+   
+  fprintf(stdout, "\n int_data: %d, length: %ld", int_data, int_length);
+  fprintf(stdout, "\n str_data: %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 */
+  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, my_bool is_last_data)}
+
+@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, and @code{is_last_data} is a
+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
+
+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_SERVER_GONE_ERROR
+The MySQL server has gone away
+@item CR_UNKNOWN_ERROR
+An unkown 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;
+
+   /* Indicate that the data supply is in CHUNKS */
+   length= MYSQL_LONG_DATA;
+
+  /* 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);
+  @}
+
+  /* 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 */
+   if (!mysql_send_long_data(stmt,1,"MySQL",5,0))
+  @{
+    fprintf(stderr, "\n send_long_data failed");
+    fprintf(stderr, "\n %s", mysql_stmt_error(stmt));
+    exit(0);
+  @}
+   /* Supply the last piece of data */
+   if (mysql_send_long_data(stmt,1," - The most popular open source database",40,1))
+  @{
+    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}.
+
+@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_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.
+
+@bye