(mysql.info) mysql-use-result

 
 22.2.3.68 `mysql_use_result()'
 ..............................
 
 `MYSQL_RES *mysql_use_result(MYSQL *mysql)'
 
 *Description*
 
 You must call `mysql_store_result()' or `mysql_use_result()' for every
 query that successfully retrieves data (`SELECT', `SHOW', `DESCRIBE',
 `EXPLAIN').
 
 `mysql_use_result()' initiates a result set retrieval but does not
 actually read the result set into the client like
 `mysql_store_result()' does.  Instead, each row must be retrieved
 individually by making calls to `mysql_fetch_row()'. This reads the
 result of a query directly from the server without storing it in a
 temporary table or local buffer, which is somewhat faster and uses much
 less memory than `mysql_store_result()'. The client allocates memory
 only for the current row and a communication buffer that may grow up to
 `max_allowed_packet' bytes.
 
 On the other hand, you shouldn't use `mysql_use_result()' if you are
 doing a lot of processing for each row on the client side, or if the
 output is sent to a screen on which the user may type a `^S' (stop
 scroll). This ties up the server and prevent other threads from
 updating any tables from which the data is being fetched.
 
 When using `mysql_use_result()', you must execute `mysql_fetch_row()'
 until a `NULL' value is returned, otherwise, the unfetched rows are
 returned as part of the result set for your next query. The C API gives
 the error `Commands out of sync; you can't run this command now' if you
 forget to do this!
 
 You may not use `mysql_data_seek()', `mysql_row_seek()',
 `mysql_row_tell()', `mysql_num_rows()', or `mysql_affected_rows()' with
 a result returned from `mysql_use_result()', nor may you issue other
 queries until `mysql_use_result()' has finished. (However, after you
 have fetched all the rows, `mysql_num_rows()' accurately returns the
 number of rows fetched.)
 
 You must call `mysql_free_result()' once you are done with the result
 set.
 
 When using the `libmysqld' embedded server, the memory benefits are
 essentially lost because memory usage incrementally increases with each
 row retrieved until `mysql_free_result()' is called.
 
 *Return Values*
 
 A `MYSQL_RES' result structure.  `NULL' if an error occurred.
 
 *Errors*
 
 `mysql_use_result()' resets `mysql_error()' and `mysql_errno()' if it
 succeeds.
 
    * `CR_COMMANDS_OUT_OF_SYNC'
 
      Commands were executed in an improper order.
 
    * `CR_OUT_OF_MEMORY'
 
      Out of memory.
 
    * `CR_SERVER_GONE_ERROR'
 
      The MySQL server has gone away.
 
    * `CR_SERVER_LOST'
 
      The connection to the server was lost during the query.
 
    * `CR_UNKNOWN_ERROR'
 
      An unknown error occurred.
Info Catalog
(mysql.info) mysql-thread-id
(mysql.info) c-api-functions
(mysql.info) mysql-warning-count
automatically generated byinfo2html