bk commit - mysqldoc tree (1.645)

Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.645 03/07/30 14:05:24 paul@xxxxxxxxxxxxxxxxxx +1 -0
  Replace the first two (long) C prepared statement code examples.

  Docs/manual.texi
    1.606 03/07/30 14:05:24 paul@xxxxxxxxxxxxxxxxxx +315 -242
    Replace the first two (long) C prepared statement code examples.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User: paul
# Host: teton.kitebird.com
# Root: /home/paul/mysqldoc

--- 1.605/Docs/manual.texi      Wed Jul 30 11:03:04 2003
+++ 1.606/Docs/manual.texi      Wed Jul 30 14:05:24 2003
@@ -53514,6 +53514,11 @@
 @item @code{mysql_free_result()}
 @end itemize
 
+The result set structure should be freed when you are done with it, which
+you can do by passing it to @code{mysql_free_result()}. This is similar
+to the way you free a result set obtained from a call to
+@code{mysql_store_result()}.
+
 
 @subsubheading Return Values
 
@@ -53661,155 +53666,150 @@
 and @code{mysql_stmt_affected_rows()}. The @code{mysql} variable is assumed
 to be a valid connection handle.
 
-@c TODO: replace this with current code
-
 @example
+#define STRING_SIZE 50
 
-MYSQL_BIND   bind[3];
-MYSQL_STMT   *stmt;
-my_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 */
+#define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table"
+#define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\
+                                                 col2 VARCHAR(40),\
+                                                 col3 SMALLINT,\
+                                                 col4 TIMESTAMP)"
+#define INSERT_SAMPLE "INSERT INTO test_table(col1,col2,col3) VALUES(?,?,?)"
+
+MYSQL_STMT    *stmt;
+MYSQL_BIND    bind[3];
+my_ulonglong  affected_rows;
+int           param_count;
+short         small_data;
+int           int_data;
+char          str_data[STRING_SIZE];
+unsigned long str_length;
+my_bool       is_null;
+
+if (mysql_query(mysql, DROP_SAMPLE_TABLE))
+@{
+  fprintf(stderr, " DROP TABLE failed\n");
+  fprintf(stderr, " %s\n", mysql_error(mysql));
+  exit(0);
+@}
+
+if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
+@{
+  fprintf(stderr, " CREATE TABLE failed\n");
+  fprintf(stderr, " %s\n", mysql_error(mysql));
+  exit(0);
+@}
+
+/* Prepare an INSERT query with 3 parameters */
+/* (the TIMESTAMP column is not named; it will */
+/* be set to the current date and time) */
+stmt = mysql_prepare(mysql, INSERT_SAMPLE, strlen(INSERT_SAMPLE));
+if (!stmt)
+@{
+  fprintf(stderr, " mysql_prepare(), INSERT failed\n");
+  fprintf(stderr, " %s\n", mysql_error(mysql));
+  exit(0);
+@}
+fprintf(stdout, " prepare, INSERT successful\n");
+
+/* Get the parameter count from the statement */
+param_count= mysql_param_count(stmt);
+fprintf(stdout, " total parameters in INSERT: %d\n", param_count);
+
+if (param_count != 3) /* validate parameter count */
+@{
+  fprintf(stderr, " invalid parameter count returned by MySQL\n");
+  exit(0);
+@}
+
+/* Bind the data for all 3 parameters */
+
+/* INTEGER PARAM */
+/* This is a number type, so there is no need to specify buffer_length */
+bind[0].buffer_type= MYSQL_TYPE_LONG;
+bind[0].buffer= (char *)&int_data;
+bind[0].is_null= 0;
+bind[0].length= 0;
+
+/* STRING PARAM */
+bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
+bind[1].buffer= (char *)str_data;
+bind[1].buffer_length= STRING_SIZE;
+bind[1].is_null= 0;
+bind[1].length= &str_length;
  
-  /* 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);
-  @}
+/* SMALLINT PARAM */
+bind[2].buffer_type= MYSQL_TYPE_SHORT;
+bind[2].buffer= (char *)&small_data;       
+bind[2].is_null= &is_null;
+bind[2].length= 0;
+
+/* Bind the buffers */
+if (mysql_bind_param(stmt, bind))
+@{
+  fprintf(stderr, " mysql_bind_param() failed\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
+
+/* Specify the data values for the first row */
+int_data= 10;             /* integer */
+strncpy(str_data, "MySQL", STRING_SIZE); /* string  */
+str_length= strlen(str_data);
+
+/* INSERT SMALLINT data as NULL */
+is_null= 1;
+
+/* Execute the INSERT statement - 1*/
+if (mysql_execute(stmt))
+@{
+  fprintf(stderr, " mysql_execute(), 1 failed\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
+  
+/* Get the total number of affected rows */   
+affected_rows= mysql_stmt_affected_rows(stmt);
+fprintf(stdout, " total affected rows(insert 1): %ld\n", affected_rows);
+
+if (affected_rows != 1) /* validate affected rows */
+@{
+  fprintf(stderr, " invalid affected rows by MySQL\n");
+  exit(0);
+@}
+
+/* Specify data values for second row, then re-execute the statement */
+int_data= 1000;             
+strncpy(str_data, "The most popular open source database", STRING_SIZE); 
+str_length= strlen(str_data);
+small_data= 1000;         /* smallint */
+is_null= 0;               /* reset */
+
+/* Execute the INSERT statement - 2*/
+if (mysql_execute(stmt))
+@{
+  fprintf(stderr, " mysql_execute, 2 failed\n");
+  fprintf(stderr, " %s\n", 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!!!");
+/* Get the total rows affected */   
+affected_rows= mysql_stmt_affected_rows(stmt);
+fprintf(stdout, " total affected rows(insert 2): %ld\n", affected_rows);
+
+if (affected_rows != 1) /* validate affected rows */
+@{
+  fprintf(stderr, " invalid affected rows by MySQL\n");
+  exit(0);
+@}
+
+/* Close the statement */
+if (mysql_stmt_close(stmt))
+@{
+  fprintf(stderr, " failed while closing the statement\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
 @end example
 
 @strong{Note}: For complete examples on the use of prepared
@@ -54195,106 +54195,177 @@
 @code{mysql_bind_result()}, and @code{mysql_fetch()}.
 The @code{mysql} variable is assumed to be a valid connection handle.
 
-@c TODO: replace this example. It won't even compile.
-
 @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(mysql));
-    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].buffer_length= 20;
-  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);
-  @}  
-  
+#define STRING_SIZE 50
+
+#define SELECT_SAMPLE "SELECT col1, col2, col3, col4 FROM test_table"
+
+MYSQL_STMT    *stmt;
+MYSQL_BIND    bind[4];
+MYSQL_RES     *prepare_meta_result;
+MYSQL_TIME    ts;
+unsigned long length[4];
+int           param_count, column_count, row_count;
+short         small_data;
+int           int_data;
+char          str_data[STRING_SIZE];
+my_bool       is_null[4];
+
+/*
+  Sample which is incorporated directly in the manual under Prepared 
+  statements section (Example from mysql_fetch()
+*/
+
+/* Prepare a SELECT query to fetch data from test_table */
+stmt = mysql_prepare(mysql, SELECT_SAMPLE, strlen(SELECT_SAMPLE));
+if (!stmt)
+@{
+  fprintf(stderr, " mysql_prepare(), SELECT failed\n");
+  fprintf(stderr, " %s\n", mysql_error(mysql));
+  exit(0);
+@}
+fprintf(stdout, " prepare, SELECT successful\n");
+
+/* Get the parameter count from the statement */
+param_count= mysql_param_count(stmt);
+fprintf(stdout, " total parameters in SELECT: %d\n", param_count);
+
+if (param_count != 0) /* validate parameter count */
+@{
+  fprintf(stderr, " invalid parameter count returned by MySQL\n");
+  exit(0);
+@}
+
+/* Fetch result set meta information */
+prepare_meta_result = mysql_prepare_result(stmt);
+if (!prepare_meta_result)
+@{
+  fprintf(stderr, " mysql_prepare_result(), retured no meta information\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
+
+/* Get total columns in the query */
+column_count= mysql_num_fields(prepare_meta_result);
+fprintf(stdout, " total columns in SELECT statement: %d\n", column_count);
+
+if (column_count != 4) /* validate column count */
+@{
+  fprintf(stderr, " invalid column count returned by MySQL\n");
+  exit(0);
+@}
+
+/* Execute the SELECT query */
+if (mysql_execute(stmt))
+@{
+  fprintf(stderr, " mysql_execute(), failed\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
+
+/* Bind the result buffers for all 3 columns before fetching them */
+
+/* INTEGER COLUMN */
+bind[0].buffer_type= MYSQL_TYPE_LONG;
+bind[0].buffer= (char *)&int_data;
+bind[0].is_null= &is_null[0];
+bind[0].length= &length[0];
+
+/* STRING COLUMN */
+bind[1].buffer_type= MYSQL_TYPE_VAR_STRING;
+bind[1].buffer= (char *)str_data;
+bind[1].buffer_length= STRING_SIZE;
+bind[1].is_null= &is_null[1];
+bind[1].length= &length[1];
+ 
+/* SMALLINT COLUMN */
+bind[2].buffer_type= MYSQL_TYPE_SHORT;
+bind[2].buffer= (char *)&small_data;       
+bind[2].is_null= &is_null[2];
+bind[2].length= &length[2];
+ 
+/* TIMESTAMP COLUMN */
+bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
+bind[3].buffer= (char *)&ts;       
+bind[3].is_null= &is_null[3];
+bind[3].length= &length[3];
+
+/* Bind the result buffers */
+if (mysql_bind_result(stmt, bind))
+@{
+  fprintf(stderr, " mysql_bind_result() failed\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
+
+/* Now buffer all results to client */
+if (mysql_stmt_store_result(stmt))
+@{
+  fprintf(stderr, " mysql_stmt_store_result() failed\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
+
+/* Fetch all rows */
+row_count= 0;
+fprintf(stdout, "Fetching results ...\n");
+while (!mysql_fetch(stmt))
+@{
+  row_count++;
+  fprintf(stdout, "  row %d\n", row_count);
+
+  /* column 1 */
+  fprintf(stdout, "   column1 (integer)  : ");
   if (is_null[0])
-    fprintf(stdout, "\n Col1 data is NULL");
+    fprintf(stdout, " NULL\n");
   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);
-  @}  
- 
+    fprintf(stdout, " %d(%ld)\n", int_data, length[0]);
+
+  /* column 2 */
+  fprintf(stdout, "   column2 (string)   : ");
+  if (is_null[1])
+    fprintf(stdout, " NULL\n");
+  else
+    fprintf(stdout, " %s(%ld)\n", str_data, length[1]);
+
+  /* column 3 */
+  fprintf(stdout, "   column3 (smallint) : ");
+  if (is_null[2])
+    fprintf(stdout, " NULL\n");
+  else
+    fprintf(stdout, " %d(%ld)\n", small_data, length[2]);
+
+  /* column 4 */
+  fprintf(stdout, "   column4 (timestamp): ");
+  if (is_null[3])
+    fprintf(stdout, " NULL\n");
+  else
+    fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n",
+                                               ts.year, ts.month, ts.day,
+                                               ts.hour, ts.minute, ts.second,
+                                               length[3]);
+  fprintf(stdout, "\n");
+@}
+
+/* Validate rows fetched */
+fprintf(stdout, " total rows fetched: %d\n", row_count);
+if (row_count != 2)
+@{
+  fprintf(stderr, " MySQL failed to return all rows\n");
+  exit(0);
+@} 
+
+/* Free the prepared result metadata */
+mysql_free_result(prepare_meta_result);
+
+
+/* Close the statement */
+if (mysql_stmt_close(stmt))
+@{
+  fprintf(stderr, " failed while closing the statement\n");
+  fprintf(stderr, " %s\n", mysql_stmt_error(stmt));
+  exit(0);
+@}
 @end example
 
 
@@ -54344,6 +54415,8 @@
 It inserts the data value ``MySQL - The most popular open source database'' 
 into the @code{text_column} column.
 The @code{mysql} variable is assumed to be a valid connection handle.
+
+@c TODO: replace this example?
 
 @example
   

-- 
MySQL Internals Mailing List
For list archives: http://lists.mysql.com/internals
To unsubscribe:    
http://lists.mysql.com/internals?unsub=gcdmd-internals@xxxxxxxxxxx