From b0ef9283428a6d6316a5ecc09a58653f78074c8f Mon Sep 17 00:00:00 2001 From: Egon Schmid Date: Mon, 13 Dec 1999 21:20:53 +0000 Subject: [PATCH] Some cosmetic changes before I add examples to every function. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@17149 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/mysql.xml | 692 +++++++++++++++++++++++++++----------------- 1 file changed, 434 insertions(+), 258 deletions(-) diff --git a/functions/mysql.xml b/functions/mysql.xml index 4d6c14a7b6..95476fccd9 100644 --- a/functions/mysql.xml +++ b/functions/mysql.xml @@ -3,9 +3,12 @@ MySQL - These functions allow you to access MySQL database servers. + These functions allow you to access MySQL database servers. + - More information about MySQL can be found at http://www.mysql.com/. + More information about MySQL can be found at http://www.mysql.com/. + @@ -18,29 +21,37 @@ Description int mysql_affected_rows - int link_identifier - + int + + link_identifier + + mysql_affected_rows returns the number of rows affected by the last INSERT, UPDATE or DELETE query on the server associated with the specified link identifier. If the - link identifier isn't specified, the last opened link is assumed. + link identifier isn't specified, the last opened link is assumed. + 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. + function will return zero. + This command is not effective for SELECT statements, only on statements which modify records. To retrieve the number of rows - returned from a SELECT, use mysql_num_rows. + returned from a SELECT, use mysql_num_rows. + - mysql_change_user - Change logged in user on active connection + mysql_change_user + + Change logged in user on active connection + Description @@ -48,19 +59,27 @@ int mysql_change_user string user string password - string database - - int link_identifier - + string + + database + + + int + + link_identifier + + - mysql_change_user changes the logged in user on the current - active connection, or, if specified on the connection given by the link identifier. - If a database is specified, this will default or current database after the - user has been changed. If the new user/password combination fails to be authorized - the current connected user stays active. - Note that this function was introduced in PHP 3.0.13 and requires MySQL - 3.23.3 or higher. + mysql_change_user changes the logged in user + on the current active connection, or, if specified on the + connection given by the link identifier. If a database is + specified, this will default or current database after the user + has been changed. If the new user/password combination fails to + be authorized the current connected user stays active. + Note that this function was introduced in PHP 3.0.13 and + requires MySQL 3.23.3 or higher. + @@ -73,26 +92,34 @@ Description int mysql_close - int link_identifier - + int + + link_identifier + + - Returns: true on success, false on error + Returns: true on success, false on error. + mysql_close closes the link to a MySQL database that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is - assumed. + assumed. + Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's - execution. + execution. + mysql_close will not close persistent links - generated by mysql_pconnect. + generated by mysql_pconnect. + See also: mysql_connect, and - mysql_pconnect. + mysql_pconnect. + @@ -113,42 +140,56 @@ - string username - - string password - + string + + username + + + string + + password + + Returns: A positive MySQL link identifier on success, or false on - error. + error. + mysql_connect establishes a connection to a MySQL server. All of the arguments are optional, and if they're missing, defaults are assumed ('localhost', user name of the user - that owns the server process, empty password). + that owns the server process, empty password). + The hostname string can also include a port number. eg. "hostname:port" or a path to a socket eg. ":/path/to/socket" for the localhost. - Support for ":port" wass added in 3.0B4. + Support for ":port" wass added in 3.0B4. + Support for the ":/path/to/socket" was added in - 3.0.10. - + 3.0.10. + + + In case a second call is made to mysql_connect with the same arguments, no new link will be established, but instead, the link identifier of - the already opened link will be returned. + the already opened link will be returned. + The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling - mysql_close. + mysql_close. + See also mysql_pconnect, and - mysql_close. + mysql_close. + @@ -162,17 +203,22 @@ int mysql_create_db string database name - int link_identifier - + int + + link_identifier + + mysql_create_db attempts to create a new database on the server associated with the specified link - identifier. + identifier. + See also: mysql_drop_db. For downwards compatibility mysql_createdb can also be - used. + used. + @@ -189,18 +235,20 @@ int row_number - Returns: true on success, false on failure + Returns: true on success, false on failure. + mysql_data_seek 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 mysql_fetch_row would return that row. + to mysql_fetch_row would return that row. + - Row_number starts at 0. + Row_number starts at 0. + - mysql_db_query @@ -212,26 +260,31 @@ int mysql_db_query string database string query - int link_identifier - + int + + link_identifier + + Returns: A positive MySQL result identifier to the query result, - or false on error. + or false on error. + mysql_db_query selects a database and executes a query on it. If the optional link identifier isn't specified, the function will try to find an open link to the MySQL server and if no such link is found it'll try to create one as if mysql_connect was called with no - arguments + arguments + See also mysql_connect. For downwards - compatibility mysql can also be used. + compatibility mysql can also be used. + - mysql_drop_db @@ -242,22 +295,27 @@ int mysql_drop_db string database_name - int link_identifier - + int + + link_identifier + + - Returns: true on success, false on failure. + Returns: true on success, false on failure. + mysql_drop_db attempts to drop (remove) an entire database from the server associated with the specified - link identifier. + link identifier. + See also: mysql_create_db. For downward - compatibility mysql_dropdb can also be used. + compatibility mysql_dropdb can also be used. + - mysql_errno @@ -268,14 +326,16 @@ Description int mysql_errno - int link_identifier - + int + + link_identifier + + Errors coming back from the mySQL database backend no longer issue warnings. Instead, use these functions to retrieve the error number. - <?php @@ -286,11 +346,12 @@ echo mysql_errno().": ".mysql_error()."<BR>"; $conn = mysql_query("SELECT * FROM nonexistenttable"); echo mysql_errno().": ".mysql_error()."<BR>"; ?> - - - + + + - See also: mysql_error + See also: mysql_error + @@ -304,14 +365,16 @@ echo mysql_errno().": ".mysql_error()."<BR>"; Description string mysql_error - int link_identifier - + int + + link_identifier + + Errors coming back from the mySQL database backend no longer issue warnings. Instead, use these functions to retrieve the error string. - <?php @@ -322,26 +385,31 @@ echo mysql_errno().": ".mysql_error()."<BR>"; $conn = mysql_query("SELECT * FROM nonexistenttable"); echo mysql_errno().": ".mysql_error()."<BR>"; ?> - - - + + + - See also: mysql_errno + See also: mysql_errno + - mysql_fetch_array - Fetch a result row as an associative array + mysql_fetch_array + + Fetch a result row as an associative array + Description array mysql_fetch_array int result - int - result_type + int + + result_type + @@ -351,28 +419,34 @@ echo mysql_errno().": ".mysql_error()."<BR>"; mysql_fetch_array is an extended version of mysql_fetch_row. In addition to storing the data in the numeric indices of the result array, it also stores - the data in associative indices, using the field names as keys. + the data in associative indices, using the field names as keys. + If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must the numeric index of the column or make an alias for the column. - + + select t1.f1 as foo t2.f1 as bar from t1, t2 - + + + An important thing to note is that using mysql_fetch_array is NOT significantly slower than using mysql_fetch_row, while it - provides a significant added value. + provides a significant added value. + - The optional second argument result_type in - mysql_fetch_array is a constant and can take - the following values: MYSQL_ASSOC, MYSQL_NUM, and MYSQL_BOTH. (This - feature was added in PHP 3.0.7) + The optional second argument result_type + in mysql_fetch_array is a constant and can + take the following values: MYSQL_ASSOC, MYSQL_NUM, and + MYSQL_BOTH. (This feature was added in PHP 3.0.7) + - For further details, also see - mysql_fetch_row + For further details, see also + mysql_fetch_row. mysql fetch array @@ -386,85 +460,115 @@ while($row = mysql_fetch_array($result)) { } mysql_free_result($result); ?> - + - mysql_fetch_field - Get column information from a result and return as an - object + + Get column information from a result and return as an object + Description object mysql_fetch_field int result - int field_offset - + int + + field_offset + + - Returns an object containing field information. + Returns an object containing field information. + mysql_fetch_field can be used in order to obtain information about fields in a certain query result. If the field offset isn't specified, the next field that wasn't yet - retrieved by mysql_fetch_field is retrieved. + retrieved by mysql_fetch_field is retrieved. + The properties of the object are: - - + + name - column name - - + + + + table - name of the table the column belongs to - - + + + + max_length - maximum length of the column - - + + + + not_null - 1 if the column cannot be null - - + + + + primary_key - 1 if the column is a primary key - - + + + + unique_key - 1 if the column is a unique key - - + + + + multiple_key - 1 if the column is a non-unique key - - + + + + numeric - 1 if the column is numeric - - + + + + blob - 1 if the column is a BLOB - - + + + + type - the type of the column - - + + + + unsigned - 1 if the column is unsigned - - + + + + zerofill - 1 if the column is zero-filled - - - + + + + - See also mysql_field_seek - + See also mysql_field_seek + - mysql_fetch_lengths - Get the length of each output in a result + mysql_fetch_lengths + + Get the length of each output in a result + Description @@ -475,16 +579,19 @@ mysql_free_result($result); Returns: An array that corresponds to the lengths of each field in the last row fetched by mysql_fetch_row, - or false on error. + or false on error. + mysql_fetch_lengths stores the lengths of each result column in the last row returned by mysql_fetch_row, mysql_fetch_array, and mysql_fetch_object in an array, starting at - offset 0. + offset 0. + - See also: mysql_fetch_row. + See also: mysql_fetch_row. + @@ -498,29 +605,36 @@ mysql_free_result($result); object mysql_fetch_object int result - int result_typ + int + + result_typ + + Returns an object with properties that correspond to the fetched - row, or false if there are no more rows. + row, or false if there are no more rows. + mysql_fetch_object is similar to mysql_fetch_array, with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by - their offsets (numbers are illegal property names). + their offsets (numbers are illegal property names). + The optional argument result_typ is a constant and can take the following values: MYSQL_ASSOC, - MYSQL_NUM, and MYSQL_BOTH. + MYSQL_NUM, and MYSQL_BOTH. + Speed-wise, the function is identical to mysql_fetch_array, and almost as quick as mysql_fetch_row (the difference is insignificant). - - mysql fetch object - + + mysql fetch object + <?php mysql_connect($host,$user,$password); $result = mysql_db_query("database","select * from table"); @@ -530,11 +644,13 @@ while($row = mysql_fetch_object($result)) { } mysql_free_result($result); ?> - - - - See also: mysql_fetch_array and - mysql_fetch_row. + + + + + See also: mysql_fetch_array and + mysql_fetch_row. + @@ -551,30 +667,35 @@ mysql_free_result($result); Returns: An array that corresponds to the fetched row, or false - if there are no more rows. + if there are no more rows. + mysql_fetch_row fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an - array offset, starting at offset 0. + array offset, starting at offset 0. + Subsequent call to mysql_fetch_row would return the next row in the result set, or false if there are no - more rows. + more rows. + See also: mysql_fetch_array, - mysql_fetch_object, - mysql_data_seek, - mysql_fetch_lengths, and - mysql_result. + mysql_fetch_object, + mysql_data_seek, + mysql_fetch_lengths, and + mysql_result. + mysql_field_name - Get the name of the specified field in a - result + + Get the name of the specified field in a result + Description @@ -587,21 +708,25 @@ mysql_free_result($result); mysql_field_name returns the name of the specified field. Arguments to the function is the result identifier and the field index, ie. - mysql_field_name($result,2); + mysql_field_name($result,2); + Will return the name of the second field in the result associated - with the result identifier. + with the result identifier. + For downwards compatibility mysql_fieldname - can also be used. + can also be used. + - mysql_field_seek - Set result pointer to a specified field offset + + Set result pointer to a specified field offset + Description @@ -613,17 +738,20 @@ mysql_free_result($result); Seeks to the specified field offset. If the next call to mysql_fetch_field won't include a field - offset, this field would be returned. + offset, this field would be returned. + - See also: mysql_fetch_field. + See also: mysql_fetch_field. + mysql_field_table - Get name of the table the specified field is - in + + Get name of the table the specified field is in + Description @@ -634,16 +762,17 @@ mysql_free_result($result); Get the table name for field. For downward compatibility - mysql_fieldtable can also be used. + mysql_fieldtable can also be used. + - mysql_field_type - Get the type of the specified field in a - result + + Get the type of the specified field in a result + Description @@ -658,10 +787,9 @@ mysql_free_result($result); identical, but the field type is returned. This will be one of "int", "real", "string", "blob", or others as detailed in the MySQL documentation. - - - mysql field types - + + mysql field types + <?php mysql_connect("localhost:3306"); mysql_select_db("wisconsin"); @@ -682,22 +810,22 @@ while ($i < $fields) { } mysql_close(); ?> - - - + + + For downward compatibility mysql_fieldtype - can also be used. - + can also be used. + - mysql_field_flags - Get the flags associated with the specified field in a - result + + Get the flags associated with the specified field in a result + Description @@ -710,22 +838,26 @@ mysql_close(); mysql_field_flags returns the field flags of the specified field. The flags are reported as a single word per flag separated by a single space, so that you can split the - returned value using explode. + returned value using explode. + The following flags are reported, if your version of MySQL is current enough to support them: "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", - "binary", "enum", "auto_increment", "timestamp". + "binary", "enum", "auto_increment", "timestamp". + For downward compatibility mysql_fieldflags - can also be used. + can also be used. + - - mysql_field_len - Returns the length of the specified field + mysql_field_len + + Returns the length of the specified field + Description @@ -742,7 +874,6 @@ mysql_close(); - mysql_free_result @@ -758,34 +889,40 @@ mysql_close(); mysql_free_result only needs to be called if you are worried about using too much memory while your script is running. All associated result memory for the specified result - identifier will automatically be freed. + identifier will automatically be freed. + For downward compatibility mysql_freeresult - can also be used. + can also be used. + - mysql_insert_id - Get the id generated from the previous INSERT - operation + + Get the id generated from the previous INSERT operation + Description int mysql_insert_id - int link_identifier - + int + + link_identifier + + mysql_insert_id returns the ID generated for an AUTO_INCREMENTED field. It will return the auto-generated ID - returned by the last INSERT query performed using the given + returned by the last INSERT query performed using the given link_identifier. If - link_identifier isn't specified, the last - opened link is assumed. + link_identifier isn't specified, the last + opened link is assumed. + @@ -800,55 +937,65 @@ mysql_close(); int mysql_list_fields string database_name string table_name - int link_identifier - + int + + link_identifier + + mysql_list_fields retrieves information about the given tablename. Arguments are the database name and the table name. A result pointer is returned which can be used - with - mysql_field_flags, - mysql_field_len, + with mysql_field_flags, + mysql_field_len, mysql_field_name, and - mysql_field_type. + mysql_field_type. + A result identifier is a positive integer. The function returns -1 if a error occurs. A string describing the error will be placed in $phperrmsg, and unless the function was called as @mysql() then this error string - will also be printed out. + will also be printed out. + For downward compatibility mysql_listfields - can also be used. + can also be used. + - - mysql_list_dbs - List databases available on on MySQL server + mysql_list_dbs + + List databases available on on MySQL server + Description int mysql_list_dbs - int link_identifier - + int + + link_identifier + + mysql_list_dbs will return a result pointer containing the databases available from the current mysql daemon. Use the mysql_tablename function to - traverse this result pointer. + traverse this result pointer. + For downward compatibility mysql_listdbs can - also be used. + also be used. + - mysql_list_tables @@ -860,7 +1007,8 @@ mysql_close(); int mysql_list_tables string database int - link_identifier + + link_identifier @@ -869,14 +1017,15 @@ mysql_close(); returns a result pointer much like the mysql_db_query function. The mysql_tablename function should be used to - extract the actual table names from the result pointer. + extract the actual table names from the result pointer. + For downward compatibility mysql_listtables - can also be used. + can also be used. + - mysql_num_fields @@ -890,7 +1039,8 @@ mysql_close(); mysql_num_fields returns the number of - fields in a result set. + fields in a result set. + See also: mysql_db_query, @@ -899,11 +1049,11 @@ mysql_close(); mysql_num_rows. For downward compatibility mysql_numfields - can also be used. + can also be used. + - mysql_num_rows @@ -917,19 +1067,21 @@ mysql_close(); mysql_num_rows returns the number of rows in - a result set. + a result set. + See also: mysql_db_query, mysql_query and, - mysql_fetch_row. + mysql_fetch_row. + For downward compatibility mysql_numrows can - also be used. + also be used. + - mysql_pconnect @@ -958,38 +1110,47 @@ mysql_close(); Returns: A positive MySQL persistent link identifier on success, - or false on error + or false on error. + mysql_pconnect establishes a connection to a MySQL server. All of the arguments are optional, and if they're missing, defaults are assumed ('localhost', user name of the user - that owns the server process, empty password). + that owns the server process, empty password). + The hostname string can also include a port number. eg. "hostname:port" or a path to a socket eg. ":/path/to/socket" for the localhost. - Support for ":port" wass added in 3.0B4. + Support for ":port" wass added in 3.0B4. + Support for the ":/path/to/socket" was added in - 3.0.10. - + 3.0.10. + + + mysql_pconnect acts very much like - mysql_connect with two major differences. + mysql_connect with two major differences. + First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it - will be returned instead of opening a new connection. + will be returned instead of opening a new connection. + Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (mysql_close will not - close links established by mysql_pconnect). + close links established by mysql_pconnect). + - This type of links is therefore called 'persistent'. + This type of links is therefore called 'persistent'. + @@ -1014,20 +1175,22 @@ mysql_close(); link_identifier isn't specified, the last opened link is assumed. If no link is open, the function tries to establish a link as if mysql_connect was - called with no arguments, and use it. + called with no arguments, and use it. + - The query string should not end with a semicolon. + The query string should not end with a semicolon. + mysql_query 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. + to succeed but affect no rows or return no rows. + The following query is syntactically invalid, so mysql_query fails and returns FALSE: - <function>mysql_query</function> @@ -1036,14 +1199,13 @@ $result = mysql_query ("SELECT * WHERE 1=1") or die ("Invalid query"); ?> - - + + The following query is semantically invalid if my_col is not a column in the table my_tbl, so mysql_query fails and returns FALSE: - <function>mysql_query</function> @@ -1052,12 +1214,13 @@ $result = mysql_query ("SELECT my_col FROM my_tbl") or die ("Invalid query"); ?> - - + + mysql_query will also fail and return FALSE if you don't have permission to access the table(s) referenced by - the query. + the query. + Assuming the query succeeds, you can call mysql_affected_rows to find out how many @@ -1067,14 +1230,16 @@ $result = mysql_query ("SELECT my_col FROM my_tbl") that you can pass to mysql_result. When you are done with the result set, you can free the resources associated with it by calling - mysql_free_result. + mysql_free_result. + See also: mysql_affected_rows, mysql_db_query, mysql_free_result, mysql_result, mysql_select_db, and - mysql_connect. + mysql_connect. + @@ -1101,7 +1266,8 @@ $result = mysql_query ("SELECT my_col FROM my_tbl") field's offset, or the field's name, or the field's table dot field's name (fieldname.tablename). If the column name has been aliased ('select foo as bar from...'), use the alias instead of - the column name. + the column name. + When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As @@ -1109,15 +1275,18 @@ $result = mysql_query ("SELECT my_col FROM my_tbl") function call, they're MUCH quicker than mysql_result. Also, note that specifying a numeric offset for the field argument is much quicker than - specifying a fieldname or tablename.fieldname argument. + specifying a fieldname or tablename.fieldname argument. + Calls mysql_result should not be mixed - with calls to other functions that deal with the result set. + with calls to other functions that deal with the result set. + Recommended high-performance alternatives: mysql_fetch_row, mysql_fetch_array, and - mysql_fetch_object. + mysql_fetch_object. + @@ -1131,32 +1300,39 @@ $result = mysql_query ("SELECT my_col FROM my_tbl") int mysql_select_db string database_name - int link_identifier - + int + + link_identifier + + - Returns: true on success, false on error + Returns: true on success, false on error. + mysql_select_db sets the current active database on the server that's associated with the specified link identifier. If no link identifier is specified, the last opened link is assumed. If no link is open, the function will try to establish a link as if mysql_connect was - called, and use it. + called, and use it. + Every subsequent call to mysql_query will be - made on the active database. + made on the active database. + See also: mysql_connect, mysql_pconnect, and - mysql_query + mysql_query. + For downward compatibility mysql_selectdb - can also be used. + can also be used. + - mysql_tablename @@ -1175,9 +1351,8 @@ $result = mysql_query ("SELECT my_col FROM my_tbl") as well as an integer index and returns the name of a table. The mysql_num_rows function may be used to determine the number of tables in the result pointer. - - - <function>mysql_tablename</function> example + + <function>Mysql_tablename</function> Example <?php mysql_connect ("localhost:3306"); @@ -1189,8 +1364,9 @@ while ($i < mysql_num_rows ($result)) { $i++; } ?> - - + + + @@ -1206,7 +1382,7 @@ sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" +sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil