Moved to new doc style; and other misc. changes including use of new entities.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@183139 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2005-03-30 05:05:08 +00:00
parent 5c81df9797
commit c315196775
6 changed files with 423 additions and 168 deletions

View file

@ -1,65 +1,70 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.2 -->
<!-- $Revision: 1.20 $ -->
<refentry id="function.mysql-affected-rows">
<refnamediv>
<refname>mysql_affected_rows</refname>
<refpurpose>Get number of affected rows in previous MySQL
operation</refpurpose>
<refpurpose>Get number of affected rows in previous MySQL operation</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>mysql_affected_rows</methodname>
<methodparam choice="opt"><type>resource</type><parameter>
link_identifier
</parameter></methodparam>
</methodsynopsis>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>mysql_affected_rows</methodname>
<methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
<function>mysql_affected_rows</function> returns the number
of rows affected by the last INSERT, UPDATE or DELETE query
associated with <parameter>link_identifier</parameter>. If the
link identifier isn't specified, the last link opened by
<function>mysql_connect</function> is assumed.
Get the number of affected rows by the last INSERT, UPDATE or DELETE query
associated with <parameter>link_identifier</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>link_identifier</parameter></term>
<listitem>
&mysql.linkid.description;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the number of affected rows on success, and -1 if the last query
failed.
</para>
<note>
<para>
If you are using transactions, you need to call
<function>mysql_affected_rows</function> after your INSERT,
UPDATE, or DELETE query, not after the commit.
</para>
</note>
<para>
If the last query was a DELETE query with no WHERE clause, all
of the records will have been deleted from the table but this
function will return zero with MySQL versions prior to 4.1.2.
</para>
<note>
<para>
When using UPDATE, MySQL will not update columns where the new
value is the same as the old value. This creates the possibility
that <function>mysql_affected_rows</function> may not actually
equal the number of rows matched, only the number of rows that
were literally affected by the query.
</para>
<para>
The REPLACE statement first deletes the record with the same primary key and
then inserts the new record. This function returns the number of deleted
records plus the number of inserted records.
</para>
</note>
<para>
To retrieve the number of rows returned by a SELECT, it is possible to
use also <function>mysql_num_rows</function>.
When using UPDATE, MySQL will not update columns where the new value is the
same as the old value. This creates the possibility that
<function>mysql_affected_rows</function> may not actually equal the number
of rows matched, only the number of rows that were literally affected by
the query.
</para>
<para>
If the last query failed, this function will return -1.
The REPLACE statement first deletes the record with the same primary key
and then inserts the new record. This function returns the number of
deleted records plus the number of inserted records.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Delete-Query</title>
<title><function>mysql_affected_rows</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
/* connect to database */
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
@ -76,9 +81,7 @@ printf("Records deleted: %d\n", mysql_affected_rows());
?>
]]>
</programlisting>
<para>
The above example would produce the following output:
</para>
&example.outputs.similar;
<screen>
<![CDATA[
Records deleted: 10
@ -89,14 +92,15 @@ Records deleted: 0
</para>
<para>
<example>
<title>Update-Query</title>
<title><function>mysql_affected_rows</function> example using transactions</title>
<programlisting role="php">
<![CDATA[
<?php
/* connect to database */
mysql_connect("localhost", "mysql_user", "mysql_password") or
die("Could not connect: " . mysql_error());
mysql_select_db("mydb");
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
if (!$link) {
die('Could not connect: ' . mysql_error());
}
mysql_select_db('mydb');
/* Update records */
mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
@ -105,19 +109,42 @@ mysql_query("COMMIT");
?>
]]>
</programlisting>
<para>
The above example would produce the following output:
</para>
&example.outputs.similar;
<screen>
<![CDATA[
Updated Records: 10
]]>
</screen>
</example>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<title>Transactions</title>
<para>
If you are using transactions, you need to call
<function>mysql_affected_rows</function> after your INSERT, UPDATE, or
DELETE query, not after the COMMIT.
</para>
</note>
<note>
<title>SELECT Statements</title>
<para>
To retrieve the number of rows returned by a SELECT, it is possible to
use <function>mysql_num_rows</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>mysql_num_rows</function>, and
<function>mysql_info</function>.
<simplelist>
<member><function>mysql_num_rows</function></member>
<member><function>mysql_info</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,26 +1,20 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.2 -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.mysql-change-user">
<refnamediv>
<refname>mysql_change_user</refname>
<refpurpose>
Change logged in user of the active connection
</refpurpose>
<refpurpose>Change logged in user of the active connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>mysql_change_user</methodname>
<methodparam><type>string</type><parameter>user</parameter></methodparam>
<methodparam><type>string</type><parameter>password</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>
database
</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>
link_identifier
</parameter></methodparam>
</methodsynopsis>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>mysql_change_user</methodname>
<methodparam><type>string</type><parameter>user</parameter></methodparam>
<methodparam><type>string</type><parameter>password</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>database</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
<function>mysql_change_user</function> changes the logged in user
of the current active connection, or the connection given by the
@ -28,16 +22,102 @@
database is specified, this will be the current database after
the user has been changed. If the new user and password
authorization fails, the current connected user stays active.
</para>
<para>
This function is deprecated and no longer exists in PHP.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>user</parameter></term>
<listitem>
<para>
The new MySQL username.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>password</parameter></term>
<listitem>
<para>
The new MySQL password.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>database</parameter></term>
<listitem>
<para>
The MySQL database. If not specified, the current selected database
is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>link_identifier</parameter></term>
<listitem>
&mysql.linkid.description;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>3.0.14</entry>
<entry>
This function was removed from PHP.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<title>Requirements</title>
<para>
This deprecated function is only available in PHP 3 and requires MySQL
3.23.3 or higher.
This function requires MySQL 3.23.3 or higher.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>mysql_connect</function></member>
<member><function>mysql_select_db</function></member>
<member><function>mysql_query</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

View file

@ -1,46 +1,74 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.100 -->
<!-- $Revision: 1.8 $ -->
<refentry id="function.mysql-client-encoding">
<refnamediv>
<refname>mysql_client_encoding</refname>
<refpurpose>Returns the name of the character set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>mysql_client_encoding</methodname>
<methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
<function>mysql_client_encoding</function> returns the default
character set name for the current connection.
Retrieves the <literal>character_set</literal> variable from MySQL.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>link_identifier</parameter></term>
<listitem>
&mysql.linkid.description;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the default character set name for the current connection.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysql_client_encoding</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
$charset = mysql_client_encoding($link);
printf("current character set is %s\n", $charset);
echo "The current character set is: $charset\n";
?>
]]>
</programlisting>
<para>
The above example would produce the following output:
</para>
&example.outputs.similar;
<screen>
<![CDATA[
current character set is latin1
The current character set is: latin1
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also
<function>mysql_real_escape_string</function>
<simplelist>
<member><function>mysql_real_escape_string</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,26 +1,22 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.2 -->
<!-- $Revision: 1.10 $ -->
<refentry id="function.mysql-close">
<refnamediv>
<refname>mysql_close</refname>
<refpurpose>Close MySQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>mysql_close</methodname>
<methodparam choice="opt"><type>resource</type><parameter>
link_identifier
</parameter></methodparam>
</methodsynopsis>
<para>
&return.success;
</para>
<para> <function>mysql_close</function> closes the connection to
the MySQL server that's associated with the specified link
identifier. If <parameter>link_identifier</parameter> isn't
specified, the last opened link is used.
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>mysql_close</methodname>
<methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
<function>mysql_close</function> closes the non-persistent connection to
the MySQL server that's associated with the specified link identifier. If
<parameter>link_identifier</parameter> isn't specified, the last opened
link is used.
</para>
<para>
Using <function>mysql_close</function> isn't usually necessary,
@ -29,12 +25,31 @@
<link linkend="language.types.resource.self-destruct">freeing
resources</link>.
</para>
<note>
<para>
<function>mysql_close</function> will not close persistent links
created by <function>mysql_pconnect</function>.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>link_identifier</parameter></term>
<listitem>
&mysql.linkid.description;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysql_close</function> example</title>
@ -50,11 +65,33 @@ mysql_close($link);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Connected successfully
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
<function>mysql_close</function> will not close persistent links
created by <function>mysql_pconnect</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>mysql_connect</function> and
<function>mysql_pconnect</function>.
<simplelist>
<member><function>mysql_connect</function></member>
<member><function>mysql_free_result</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,38 +1,62 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.2 -->
<!-- $Revision: 1.14 $ -->
<refentry id="function.mysql-create-db">
<refnamediv>
<refname>mysql_create_db</refname>
<refpurpose>Create a MySQL database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>mysql_create_db</methodname>
<methodparam><type>string</type><parameter>database_name</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>
link_identifier
</parameter></methodparam>
</methodsynopsis>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>mysql_create_db</methodname>
<methodparam><type>string</type><parameter>database_name</parameter></methodparam>
<methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
<function>mysql_create_db</function> attempts to create a new
database on the server associated with the specified link
identifier.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>database_name</parameter></term>
<listitem>
<para>
The name of the database being created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>link_identifier</parameter></term>
<listitem>
&mysql.linkid.description;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
<note>
<para>
The function <function>mysql_create_db</function> is deprecated. It
is preferable to use <function>mysql_query</function> to issue a sql
<literal>CREATE DATABASE</literal> statement instead.
</para>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysql_create_db</function> alternative example</title>
<para>
The function <function>mysql_create_db</function> is deprecated. It is
preferable to use <function>mysql_query</function> to issue a sql
<literal>CREATE DATABASE</literal> statement instead.
</para>
<programlisting role="php">
<![CDATA[
<?php
@ -50,20 +74,39 @@ if (mysql_query($sql, $link)) {
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Database my_db created successfully
]]>
</screen>
</example>
</para>
<para>
For downwards compatibility <function>mysql_createdb</function>
can also be used. This is deprecated, however.
</para>
<warning>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
This function will not be available
if the MySQL extension was built against a MySQL 4.x client library.
</para>
</warning>
For downwards compatibility <function>mysql_createdb</function>
can also be used. This is deprecated, however.
</para>
</note>
<note>
<para>
This function will not be available if the MySQL extension was built
against a MySQL 4.x client library.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>mysql_query</function>.
<simplelist>
<member><function>mysql_query</function></member>
<member><function>mysql_select_db</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

View file

@ -1,6 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.2 -->
<!-- $Revision: 1.15 $ -->
<refentry id="function.mysql-data-seek">
<refnamediv>
<refname>mysql_data_seek</refname>
@ -8,20 +7,17 @@
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>mysql_data_seek</methodname>
<methodparam><type>resource</type><parameter>result_identifier</parameter></methodparam>
<methodparam><type>int</type><parameter>row_number</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>bool</type><methodname>mysql_data_seek</methodname>
<methodparam><type>resource</type><parameter>result_identifier</parameter></methodparam>
<methodparam><type>int</type><parameter>row_number</parameter></methodparam>
</methodsynopsis>
<para>
<function>mysql_data_seek</function> moves the internal row
pointer of the MySQL result associated with the specified result
identifier to point to the specified row number. The next call
to <function>mysql_fetch_row</function> would return that row.
</para>
<para>
&return.success;
</para>
<para>
<parameter>row_number</parameter> starts at 0. The
<parameter>row_number</parameter> should be a value in the range from 0 to
@ -30,13 +26,41 @@
fail with a <link linkend="e-warning">E_WARNING</link> and
<function>mysql_data_seek</function> will return &false;.
</para>
<note>
<para>
The function <function>mysql_data_seek</function> can be used in
conjunction only with <function>mysql_query</function>, not with
<function>mysql_unbuffered_query</function>.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>result_identifier</parameter></term>
<listitem>
<para>
The MySQL result identifier that is being seeked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>row_number</parameter></term>
<listitem>
<para>
The desired row number of the new result pointer.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysql_data_seek</function> example</title>
@ -76,14 +100,30 @@ mysql_free_result($result);
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
The function <function>mysql_data_seek</function> can be used in
conjunction only with <function>mysql_query</function>, not with
<function>mysql_unbuffered_query</function>.
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also
<function>mysql_query</function>,
<function>mysql_num_rows</function>,
<function>mysql_fetch_row</function>,
<function>mysql_fetch_assoc</function>,
<function>mysql_fetch_array</function>, and
<function>mysql_fetch_object</function>.
<simplelist>
<member><function>mysql_query</function></member>
<member><function>mysql_num_rows</function></member>
<member><function>mysql_fetch_row</function></member>
<member><function>mysql_fetch_assoc</function></member>
<member><function>mysql_fetch_array</function></member>
<member><function>mysql_fetch_object</function></member>
</simplelist>
</para>
</refsect1>
</refentry>