CVS update: phpdoc/functions

Date: Wednesday June 30, 1999 @ 15:47 Author: eschmid Update of /repository/phpdoc/functions In directory php:/tmp/cvs-serv9297 Modified Files: mysql.sgml Log Message: Another variant of mysql_query(). This was worked out by Paul DuBois <paul@snake.net>. If something is not correct please don't flame him. Index: phpdoc/functions/mysql.sgml diff -u phpdoc/functions/mysql.sgml:1.2 phpdoc/functions/mysql.sgml:1.3 --- phpdoc/functions/mysql.sgml:1.2 Sat Jun 19 23:04:56 1999 +++ phpdoc/functions/mysql.sgml Wed Jun 30 15:47:18 1999 @@ -964,14 +964,79 @@ to establish a link as if <function>mysql_connect</function> was called, and use it. <para> - This function returns TRUE or FALSE to indicate the success of - UPDATE, INSERT, and DELETE queries. For SELECT queries it returns - a new result identifier. The resources used by the query can - then be freed by calling <function>mysql_free_result</function>. - <para> - See also: - <function>mysql_db_query</function>, - <function>mysql_select_db</function>, and + The query string should not end with a semicolon. + <para> + <function>mysql_query</function> returns TRUE (non-zero) or FALSE + to indicate whether or not the query succeeded. A return value + of TRUE means that the query was legal and could be executed by + the server. It does not indicate anything about the number of + rows affected or returned. It is perfectly possible for a query + to succeed but affect no rows or return no rows. + <para> + The following query is syntactically invalid, so + <function>mysql_query</function> fails and returns FALSE: + + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +&lt;?php +$result = mysql_query ("SELECT * WHERE 1=1") + or die ("Invalid query"); +?> + </programlisting> + </example> + + <para> + The following query is semantically invalid if + <literal>my_col</literal> is not a column in the table + <literal>my_tbl</literal>, so <function>mysql_query</function> + fails and returns FALSE: + + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +&lt;?php +$result = mysql_query ("SELECT * WHERE 1=1") + or die ("Invalid query"); +?> + </programlisting> + </example> + <para> + The following query is semantically invalid if + <literal>my_col</literal> is not a column in the table + <literal>my_tbl</literal>, so <function>mysql_query</function> + fails and returns FALSE: + + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +&lt;?php +$result = mysql_query ("SELECT my_col FROM my_tbl") + or die ("Invalid query"); +?> + </programlisting> + </example> + + <para> + <function>mysql_query</function> will also fail and return FALSE + if you don't have permission to access the table(s) referenced by + the query. + <para> + Assuming the query succeeds, you can call + <function>mysql_affected_rows</function> to find out how many + rows were affected (for DELETE, INSERT, REPLACE, or UPDATE + statements). For SELECT statements, + <function>mysql_query</function> returns a new result identifier + that you can pass to <function>mysql_result</function>. When you + are done with the result set, you can free the resources + associated with it by calling + <function>mysql_free_result</function>. + <para> + See also: <function>mysql_affected_rows</function>, + <function>mysql_db_query</function>, + <function>mysql_free_result</function>, + <function>mysql_result</function>, + <function>mysql_select_db</function>, and <function>mysql_connect</function>. </refsect1> </refentry>