Description
array ldap_get_values(int link_identifier, int result_entry_identifier, string attribute);
Returns an array of values for the attribute on success and false on error.
ldap_get_values() function is used to read all the values of the attribute in the entry in the result. entry is specified by the result_entry_identifier. The number of values can be found by indexing "count" in the resultant array. Individual values are accessed by integer index in the array. The first index is 0.
This call needs a result_entry_identifier, so needs to be preceded by one of the ldap search calls and one of the calls to get an individual entry.
You application will either be hard coded to look for certain attributes (such as "surname" or "mail") or you will have to use the ldap_get_attributes() call to work out what attributes exist for a given entry.
LDAP allows more than one entry for an attribute, so it can, for example, store a number of email addresses for one person's directory entry all labeled with the attribute "mail"
return_value["count"] = number of values for attribute
return_value[0] = first value of attribute
return_value[i] = ith value of attribute
Example 1. List all values of the "mail" attribute for a directory entry
// $ds is a valid link identifier for a directory server
// $sr is a valid search result from a prior call to
// one of the ldap directory search calls
// $entry is a valid entry identifier from a prior call to
// one of the calls that returns a directory entry
$values = ldap_get_values($ds, $entry,"mail");
echo $values["count"]." email addresses for this entry.<p>";
for ($i=0; $i < $values["count"]; $i++)
echo $values[$i]."<br>";
ldap_list
ldap_list -- Single-level search
Description
int ldap_list(int link_identifier, string base_dn, string filter);
Returns a search result identifier or false on error.
ldap_list() performs the search for a specified filter on the directory with the scope LDAP_SCOPE_ONELEVEL.
LDAP_SCOPE_ONELEVEL means that the search should only return information that is at the level immediately below the base dn given in the call. (Equivalent to typing "ls" and getting a list of files and folders in the current working directory.)
This call takes an optional fourth parameter which is an array of the attributes required. See ldap_search() notes.
Example 1. Produce a list of all organizational units of an organization
// $ds is a valid link identifier for a directory server
$basedn = "o=My Company, c=US";
$justthese = array("ou");
$sr=ldap_list($ds, $basedn, "ou=*", $justthese);
$info = ldap_get_entries($ds, $sr);
for ($i=0; $i<$info["count"]; $i++)
echo $info[$i]["ou"][0] ;
ldap_modify
ldap_modify -- Modify an LDAP entry
Description
int ldap_modify(int link_identifier, string dn, array entry);
Returns true on success and false on error.
ldap_modify() function is used to modify the existing entries in the LDAP directory. The structure of the entry is same as in ldap_add().
ldap_next_attribute
ldap_next_attribute -- Get the next attribute in result
Description
string ldap_next_attribute(int link_identifier, int result_entry_identifier, int ber_identifier);
Returns the next attribute in an entry on success and false on error.
ldap_next_attribute() is called to retrieve the attributes in an entry. The internal state of the pointer is maintained by the ber_identifier. It is passed by reference to the function. The first call to ldap_next_attribute() is made with the result_entry_identifier returned from ldap_first_attribute().
see also ldap_get_attributes()
ldap_next_entry
ldap_next_entry -- Get next result entry
Description
int ldap_next_entry(int link_identifier, int result_entry_identifier);
Returns entry identifier for the next entry in the result whose entries are being read starting with ldap_first_entry(). If there are no more entries in the result then it returns false.
ldap_next_entry() function is used to retrieve the entries stored in the result. Successive calls to the ldap_next_entry() return entries one by one till there are no more entries. The first call to ldap_next_entry() is made after the call to ldap_first_entry() with the result_identifier as returned from the ldap_first_entry().
see also ldap_get_entries()
ldap_read
ldap_read -- Read an entry
Description
int ldap_read(int link_identifier, string base_dn, string filter, array [attributes]);
Returns a search result identifier or false on error.
ldap_read() performs the search for a specified filter on the directory with the scope LDAP_SCOPE_BASE. So it is equivalent to reading an entry from the directory.
An empty filter is not allowed. If you want to retrieve absolutely all information for this entry, use a filter of "objectClass=*". If you know which entry types are used on the directory server, you might use an appropriate filter such as "objectClass=inetOrgPerson".
This call takes an optional fourth parameter which is an array of the attributes required. See ldap_search() notes.
ldap_search
ldap_search -- Search LDAP tree
Description
int ldap_search(int link_identifier, string base_dn, string filter, array [attributes]);
Returns a search result identifier or false on error.
ldap_search() performs the search for a specified filter on the directory with the scope of LDAP_SCOPE_SUBTREE. This is equivalent to searching the entire directory. base_dn specifies the base DN for the directory.
There is a optional fourth parameter, that can be added to restrict the attributes and values returned by the server to just those required. This is much more efficient than the default action (which is to return all attributes and their associated values). The use of the fourth parameter should therefore be considered good practice.
The fourth parameter is a standard PHP string array of the required attributes, eg array("mail","sn","cn") Note that the "dn" is always returned irrespective of which attributes types are requested.
Note too that some directory server hosts will be configured to return no more than a preset number of entries. If this occurs, the server will indicate that it has only returned a partial results set.
The search filter can be simple or advanced, using boolean operators in the format described in the LDAP doumentation (see the Netscape Directory SDK for full information on filters).
The example below retrieves the organizational unit, surname, given name and email address for all people in "My Company" where the surname or given name contains the substring $person. This example uses a boolean filter to tell the server to look for information in more than one attribute.
Example 1. LDAP search
// $ds is a valid link identifier for a directory server
// $person is all or part of a person's name, eg "Jo"
$dn = "o=My Company, c=US";
$filter="(|(sn=$person*)(givenname=$person*))";
$justthese = array( "ou", "sn", "givenname", "mail");
$sr=ldap_search($ds, $dn, $filter, $justthese);
$info = ldap_get_entries($ds, $sr);
print $info["count"]." entries returned<p>";
When you perform a search, and too much data comes back (alot of entries) you will get a warning, and ldap_get_entries() will fail. The trick here is to turn off the warnings, then check the return value.
$normerr = error_reporting ();
error_reporting (0); // turn off warnings!
$sr = ldap_search ($ds, $dn, $searchfor);
$normerr = error_reporting ($normerr);
if (!$sr) {
print "too many entries!";
} else .....
You could try narrowing the scope, by adding an extra filter eg. (cn=a*), but It would be nicer to be able to grab the results in bits (eg. 1-100, 101-200...).
ldap_unbind
ldap_unbind -- Unbind from LDAP directory
Description
int ldap_unbind(int link_identifier);
Returns true on success and false on error.
ldap_unbind() function unbinds from the LDAP directory.
XXII. Mail Functions
Table of Contents
mail
The mail() function allows you to send mail.
mail
mail -- send mail
Description
bool mail(string to, string subject, string message, string additional_headers);
Mail() automatically mails the message specified in message to the receiver specified in to. Multiple recipients can be specified by putting a space between each address in to.
Example 1. Sending mail.
mail("rasmus@lerdorf.on.ca", "My Subject", "Line 1\nLine 2\nLine 3");
If a fourth string argument is passed, this string is inserted at the end of the header. This is typically used to add extra headers. Multiple extra headers are separated with a newline.
Example 2. Sending mail with extra headers.
mail("ssb@guardian.no", "the subject", $message,
"From: webmaster@$SERVER_NAME\nReply-To: webmaster@$SERVER_NAME\nX-Mailer: PHP/" . phpversion());
XXIII. Mathematical Functions
Table of Contents
Abs
Acos
Asin
Atan
Atan2
base_convert
BinDec
Ceil
Cos
DecBin
DecHex
DecOct
Exp
Floor
getrandmax
HexDec
Log
Log10
max
min
mt_rand
mt_srand
mt_getrandmax
number_format
OctDec
pi
pow
rand
round
Sin
Sqrt
srand
Tan
--------------------------------------------------------------------------------
Introduction
These math functions will only handle values within the range of the long and double types on your computer. If you need to handle bigger numbers, take a look at the arbitrary precision math functions.
--------------------------------------------------------------------------------
Math constants
The following values are defined as constants in PHP by the math extension:
Table 1. Math constants
Constant Value Description
M_PI 3.14159265358979323846 The value of ?(pi)
Abs
Abs -- absolute value
Description
mixed abs(mixed number);
Returns the absolute value of number. If the argument number is float, return type is also float, otherwise it is int.
Acos
Acos -- arc cosine
Description
float acos(float arg);
Returns the arc cosine of arg in radians.
See also asin() and atan().
Asin
Asin -- arc sine
Description
float asin(float arg);
Returns the arc sine of arg in radians.
See also acos() and atan().
Atan
Atan -- arc tangent
Description
float atan(float arg);
Returns the arc tangent of arg in radians.
See also acos() and atan().
Atan2
Atan2 -- arc tangent of two variables
Description
float atan2(float y, float x);
This function calculates the arc tangent of the two variables x and y. It is similar to calculating the arc tangent of y / x, except that the signs of both arguments are used to determine the quadrant of the result.
The function returns the result in radians, which is between -PI and PI (inclusive).
See also acos() and atan().
base_convert
base_convert -- convert a number between arbitrary bases
Description
strin base_convert(string number, int frombase, int tobase);
Returns a string containing number represented in base tobase. The base in which number is given is specified in frombase. Both frombase and tobase have to be between 2 and 36, inclusive. Digits in numbers with a base higher than 10 will be represented with the letters a-z, with a meaning 10, b meaning 11 and z meaning 36.
Example 1. base_convert()
$binary = base_convert($hexadecimal, 16, 2);
BinDec
BinDec -- binary to decimal
Description
int bindec(string binary_string);
Returns the decimal equivalent of the binary number represented by the binary_string argument.
OctDec converts a binary number to a decimal number. The largest number that can be converted is 31 bits of 1's or 2147483647 in decimal.
See also the decbin() function.
Ceil
Ceil -- round fractions up
Description
int ceil(float number);
Returns the next highest integer value from number. Using ceil() on integers is absolutely a waste of time.
NOTE: PHP/FI 2's ceil() returned a float. Use: $new = (double)ceil($number); to get the old behaviour.
See also floor() and round().
Cos
Cos -- cosine
Description
float cos(float arg);
Returns the cosine of arg in radians.
See also sin() and tan().
DecBin
DecBin -- decimal to binary
Description
string decbin(int number);
Returns a string containing a binary representation of the given number argument. The largest number that can be converted is 2147483647 in decimal resulting to a string of 31 1's.
See also the bindec() function.
DecHex
DecHex -- decimal to hexadecimal
Description
string dechex(int number);
Returns a string containing a hexadecimal representation of the given number argument. The largest number that can be converted is 2147483647 in decimal resulting to "7fffffff".
See also the hexdec() function.
DecOct
DecOct -- decimal to octal
Description
string decoct(int number);
Returns a string containing an octal representation of the given number argument. The largest number that can be converted is 2147483647 in decimal resulting to "17777777777". See also octdec().
Exp
Exp -- e to the power of...
Description
float exp(float arg);
Returns e raised to the power of arg.
See also pow().
Floor
Floor -- round fractions down
Description
int floor(float number);
Returns the next lowest integer value from number. Using floor() on integers is absolutely a waste of time.
NOTE: PHP/FI 2's floor() returned a float. Use: $new = (double)floor($number); to get the old behaviour.
See also ceil() and round().
getrandmax
getrandmax -- show largest possible random value
Description
int getrandmax(void );
Returns the maximum value that can be returned by a call to rand().
See also rand(), srand() mt_rand(), mt_srand() and mt_getrandmax().
HexDec
HexDec -- hexadecimal to decimal
Description
int hexdec(string hex_string);
Returns the decimal equivalent of the hexadecimal number represented by the hex_string argument. HexDec converts a hexadecimal string to a decimal number. The largest number that can be converted is 7fffffff or 2147483647 in decimal.
See also the dechex() function.
Log
Log -- natural logarithm
Description
float log(float arg);
Returns the natural logarithm of arg.
Log10
Log10 -- base-10 logarithm
Description
float log10(float arg);
Returns the base-10 logarithm of arg.
max
max -- find highest value
Description
mixed max(mixed arg1, mixed arg2, mixed argn);
max() returns the numerically highest of the parameter values.
If the first parameter is an array, max() returns the highest value in that array. If the first parameter is an integer, string or double, you need at least two parameters and max() returns the biggest of these values. You can compare an unlimited number of values.
If one or more of the values is a double, all the values will be treated as doubles, and a double is returned. If none of the values is a double, all of them will be treated as integers, and an integer is returned.
min
min -- find lowest value
Description
mixed min(mixed arg1, mixed arg2, mixed argn);
min() returns the numerically lowest of the parameter values.
If the first parameter is an array, min() returns the lowest value in that array. If the first parameter is an integer, string or double, you need at least two parameters and min() returns the lowest of these values. You can compare an unlimited number of values.
If one or more of the values is a double, all the values will be treated as doubles, and a double is returned. If none of the values is a double, all of them will be treated as integers, and an integer is returned.
mt_rand
mt_rand -- generate a better random value
Description
int mt_rand([int min], [int max]);
Many random number generators of older libcs have dubious or unknown characteristics and are slow. By default, PHP uses the libc random number generator with the rand() function. mt_rand() function is a drop-in replacement for this. It uses a random number generator with known characteristics, the Mersenne Twister, which will produce random numbers that should be suitable for cryptographic purposes and is four times faster than what the average libc provides. The Homepage of the Mersenne Twister can be found at http://www.math.keio.ac.jp/~matumoto/emt.html, and an optimized version of the MT source is available from http://www.scp.syr.edu/~marc/hawk/twister.html.
If called without the optional min,max arguments mt_rand() returns a pseudo-random value between 0 and RAND_MAX. If you want a random number between 5 and 15 (inclusive), for example, use mt_rand(5,15).
Remember to seed the random number generator before use with mt_srand().
See also mt_srand(), mt_getrandmax(), srand(), rand() and getrandmax().
mt_srand
mt_srand -- seed the better random number generator
Description
void mt_srand(int seed);
Seeds the random number generator with seed.
// seed with microseconds since last "whole" second
mt_srand((double)microtime()*1000000);
$randval = mt_rand();
See also mt_rand(), mt_getrandmax(), srand(), rand() and getrandmax().
mt_getrandmax
mt_getrandmax -- show largest possible random value
Description
int mt_getrandmax(void );
Returns the maximum value that can be returned by a call to mt_rand().
See also mt_rand(), mt_srand() rand(), srand() and getrandmax().
number_format
number_format -- format a number with grouped thousands
Description
string number_format(float number, int decimals, string dec_point, string thousands_sep);
number_format() returns a formatted version of number. This function accepts either one, two or four parameters (not three):
If only one parameter is given, number will be formatted without decimals, but with a comma (",") between every group of thousands.
If two parameters are given, number will be formatted with decimals decimals with a dot (".") in front, and a comma (",") between every group of thousands.
If all four parameters are given, number will be formatted with decimals decimals, dec_point instead of a dot (".") before the decimals and thousands_sep instead of a comma (",") between every group of thousands.
OctDec
OctDec -- octal to decimal
Description
int octdec(string octal_string);
Returns the decimal equivalent of the octal number represented by the octal_string argument. OctDec converts an octal string to a decimal number. The largest number that can be converted is 17777777777 or 2147483647 in decimal.
See also decoct().
pi
pi -- get value of pi
Description
double pi(void );
Returns an approximation of pi.
pow
pow -- exponential expression
Description
float pow(float base, float exp);
Returns base raised to the power of exp.
See also exp().
rand
rand -- generate a random value
Description
int rand([int min], [int max]);
If called without the optional min,max arguments rand() returns a pseudo-random value between 0 and RAND_MAX. If you want a random number between 5 and 15 (inclusive), for example, use rand(5,15).
Remember to seed the random number generator before use with srand().
See also srand(), getrandmax(), mt_rand(), mt_srand() and mt_getrandmax().
round
round -- Rounds a float.
Description
double round(double val);
Returns the rounded value of val.
$foo = round( 3.4 ); // $foo == 3.0
$foo = round( 3.5 ); // $foo == 4.0
$foo = round( 3.6 ); // $foo == 4.0
See also ceil() and floor().
Sin
Sin -- sine
Description
float sin(float arg);
Returns the sine of arg in radians.
See also cos() and tan().
Sqrt
Sqrt -- square root
Description
float sqrt(float arg);
Returns the square root of arg.
srand
srand -- seed the random number generator
Description
void srand(int seed);
Seeds the random number generator with seed.
// seed with microseconds since last "whole" second
srand((double)microtime()*1000000);
$randval = rand();
See also rand(), getrandmax(), mt_rand(), mt_srand() and mt_getrandmax().
Tan
Tan -- tangent
Description
float tan(float arg);
Returns the tangent of arg in radians.
See also sin() and cos().
XXIV. Miscellaneous Functions
Table of Contents
eval
die
exit
iptcparse
leak
pack
register_shutdown_function
serialize
sleep
unpack
unserialize
uniqid
usleep
These functions were placed here because none of the other categories seemed to fit.
eval
eval -- Evaluate a string as PHP code
Description
void eval(string code_str);
eval() evaluates the string given in code_str as PHP code. Among other things, this can be useful for storing code in a database text field for later execution.
There are some factors to keep in mind when using eval(). Remember that the string passed must be valid PHP code, including things like terminating statements with a semicolon so the parser doesn't die on the line after the eval(), and properly escaping things in code_str.
Also remember that variables given values under eval() will retain these values in the main script afterwards.
Example 1. eval() example - simple text merge
<?php
$string = 'cup';
$name = 'coffee';
$str = 'This is a $string with my $name in it.<br>';
echo $str;
eval( "\$str = \"$str\";" );
echo $str;
?>
The above example will show:
This is a $string with my $name in it.
This is a cup with my coffee in it.
die
die -- Output a message and terminate the current script
Description
void die(string message);
This language construct outputs a message and terminates parsing of the script. It does not return.
Example 1. die example
<?php
$filename = '/path/to/data-file';
$file = fopen($filename, 'r')
or die "unable to open file ($filename)";
?>
exit
exit -- Terminate current script
Description
void exit(void);
This language construct terminates parsing of the script. It does not return.
iptcparse
iptcparse -- Parse a binary IPTC http://www.xe.net/iptc/ block into single tags.
Description
array iptcparse(string iptcblock);
This function parses a binary IPTC block into its single tags. It returns an array using the tagmarker as an index and the value as the value. It returns false on error or if no IPTC data was found. See GetImageSize() for a sample.
leak
leak -- Leak memory
Description
void leak(int bytes);
Leak() leaks the specified amount of memory.
This is useful when debugging the memory manager, which automatically cleans up "leaked" memory when each request is completed.
pack
pack -- pack data into binary string
Description
string pack(string format, mixed [args]...);
Pack given arguments into binary string according to format. Returns binary string containing data.
The idea to this function was taken from Perl and all formatting codes work the same as there. The format string consists of format codes followed by an optional repeater argument. The repeater argument can be either an integer value or * for repeating to the end of the input data. For a, A, h, H the repeat count specifies how many characters of one data argument are taken, for @ it is the absolute position where to put the next data, for everything else the repeat count specifies how many data arguments are consumed and packed into the resulting binary string. Currently implemented are
a NUL-padded string
A SPACE-padded string
h Hex string, low nibble first
H Hex string, high nibble first
c signed char
C unsigned char
s signed short (always 16 bit, machine byte order)
S unsigned short (always 16 bit, machine byte order)
n unsigned short (always 16 bit, big endian byte order)
v unsigned short (always 16 bit, little endian byte order)
i signed integer (machine dependant size and byte order)
I unsigned integer (machine dependant size and byte order)
l signed long (always 32 bit, machine byte order)
L unsigned long (always 32 bit, machine byte order)
N unsigned long (always 32 bit, big endian byte order)
V unsigned long (always 32 bit, little endian byte order)
f float (machine dependent size and representation)
d double (machine dependent size and representation)
x NUL byte
X Back up one byte
@ NUL-fill to absolute position
Example 1. pack format string
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
The resulting binary string will be 6 bytes long and contain the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
Note that the distinction between signed and unsigned values only affects the function unpack(), where as function pack() gives the same result for signed and unsigned format codes.
Also note that PHP internally stores integral values as signed values of a machine dependant size. If you give it an unsigned integral value too large to be stored that way it is converted to a double which often yields an undesired result.
register_shutdown_function
register_shutdown_function -- Register a function for execution on shutdown.
Description
int register_shutdown_function(string func);
Registers the function named by func to be executed when script processing is complete.
serialize
serialize -- generates a storable representation of a value
Description
string serialize(mixed value);
serialize() returns a string containing a byte-stream representation of value that can be stored anywhere.
This is useful for storing or passing PHP values around without losing their type and structure.
To make the serialized string into a PHP value again, use unserialize(). serialize() handles the types integer, double, string, array (multidimensional) and object (object properties will be serialized, but methods are lost).
Example 1. serialize example
// $session_data contains a multi-dimensional array with session
// information for the current user. We use serialize() to store
// it in a database at the end of the request.
$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn,
"UPDATE sessions SET data = ? WHERE id = ?");
$sqldata = array(serialize($session_data), $PHP_AUTH_USER);
if (!odbc_execute($stmt, &$sqldata)) {
$stmt = odbc_prepare($conn,
"INSERT INTO sessions (id, data) VALUES(?, ?)");
if (!odbc_execute($stmt, &$sqldata)) {
/* Something went wrong. Bitch, whine and moan. */
}
}
sleep
sleep -- Delay execution
Description
void sleep(int seconds);
The sleep function delays program execution for the given number of seconds.
See also usleep().
unpack
unpack -- unpack data from binary string
Description
array unpack(string format, string data);
Unpack from binary string into array according to format. Returns array containing unpacked elements of binary string.
Unpack works slightly different from Perl as the unpacked data is stored in an associative array. To accomplish this you have to name the different format codes and separate them by a slash /.
Example 1. unpack format string
$array = unpack("c2chars/nint", $binarydata);
The resulting array will contain the entries "chars1", "chars2" and "int".
For an explanation of the format codes see also: pack()
Note that PHP internally stores integral values as signed. If you unpack a large unsigned long and it is of the same size as PHP internally stored values the result will be a negative number even though unsigned unpacking was specified.
unserialize
unserialize -- creates a PHP value from a stored representation
Description
mixed unserialize(string str);
unserialize() takes a single serialized variable (see serialize()) and converts it back into a PHP value. The converted value is returned, and can be an integer, double, string, array or object. If an object was serialized, its methods are not preserved in the returned value.
Example 1. unserialize example
// Here, we use unserialize() to load session data from a database
// into $session_data. This example complements the one described
// with serialize().
$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array($PHP_AUTH_USER);
if (!odbc_execute($stmt, &$sqldata) || !odbc_fetch_into($stmt, &$tmp)) {
// if the execute or fetch fails, initialize to empty array
$session_data = array();
} else {
// we should now have the serialized data in $tmp[0].
$session_data = unserialize($tmp[0]);
if (!is_array($session_data)) {
// something went wrong, initialize to empty array
$session_data = array();
}
}
uniqid
uniqid -- generate a unique id
Description
int uniqid(string prefix);
uniqid() returns a prefixed unique identifier based on current time in microseconds. The prefix can be useful for instance if you generate identifiers simultaneously on several hosts that might happen to generate the identifier at the same microsecond. The prefix can be up to 114 characters long.
If you need a unique identifier or token and you intend to give out that token to the user via the network (i.e. session cookies), it is recommended that you use something along the lines of
$token = md5(uniqid("")); // no random portion
$better_token = md5(uniqid(random())); // better, difficult to guess
This will create a 32 character identifier (a 128 bit hex number) that is extremely difficult to predict.
usleep
usleep -- Delay execution in microseconds
Description
void usleep(int micro_seconds);
The sleep function delays program execution for the given number of micro_seconds.
See also sleep().
XXV. mSQL Functions
Table of Contents
msql
msql_affected_rows
msql_close
msql_connect
msql_create_db
msql_createdb
msql_data_seek
msql_dbname
msql_drop_db
msql_dropdb
msql_error
msql_fetch_array
msql_fetch_field
msql_fetch_object
msql_fetch_row
msql_fieldname
msql_field_seek
msql_fieldtable
msql_fieldtype
msql_fieldflags
msql_fieldlen
msql_free_result
msql_freeresult
msql_list_fields
msql_listfields
msql_list_dbs
msql_listdbs
msql_list_tables
msql_listtables
msql_num_fields
msql_num_rows
msql_numfields
msql_numrows
msql_pconnect
msql_query
msql_regcase
msql_result
msql_select_db
msql_selectdb
msql_tablename
msql
msql -- send mSQL query
Description
int msql(string database, string query, int link_identifier);
Returns a positive mSQL query identifier to the query result, or false on error.
msql() 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 mSQL server and if no such link is found it'll try to create one as if msql_connect() was called with no arguments (see msql_connect()).
msql_affected_rows
msql_affected_rows -- returns number of affected rows
Description
int msql_affected_rows(int query_identifier);
Returns number of affected ("touched") rows by a specific query (i.e. the number of rows returned by a SELECT, the number of rows modified by an update, or the number of rows removed by a delete).
See also: msql_query()
msql_close
msql_close -- close mSQL connection
Description
int msql_close(int link_identifier);
Returns true on success, false on error.
msql_close() closes the link to a mSQL database that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed.
Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
msql_close() will not close persistent links generated by msql_pconnect().
See also: msql_connect() and msql_pconnect().
msql_connect
msql_connect -- open mSQL connection
Description
int msql_connect(string hostname);
Returns a positive mSQL link identifier on success, or false on error.
msql_connect() establishes a connection to a mSQL server. The hostname argument is optional, and if it's missing, localhost is assumed.
In case a second call is made to msql_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 link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling msql_close().
See also msql_pconnect(), msql_close().
msql_create_db
msql_create_db -- create mSQL database
Description
int msql_create_db(string database name, int [link_identifier] );
msql_create_db() attempts to create a new database on the server associated with the specified link identifier.
See also: msql_drop_db().
msql_createdb
msql_createdb -- create mSQL database
Description
int msql_createdb(string database name, int [link_identifier] );
Identical to msql_create_db().
msql_data_seek
msql_data_seek -- move internal row pointer
Description
int msql_data_seek(int query_identifier, int row_number);
Returns true on success, false on failure.
msql_data_seek() moves the internal row pointer of the mSQL result associated with the specified query identifier to pointer to the specifyed row number. The next call to msql_fetch_row() would return that row.
See also: msql_fetch_row().
msql_dbname
msql_dbname -- get current mSQL database name
Description
string msql_dbname(int query_identifier, int i);
msql_dbname() returns the database name stored in position i of the result pointer returned from the msql_listdbs() function. The msql_numrows() function can be used to determine how many database names are available.
msql_drop_db
msql_drop_db -- drop (delete) mSQL database
Description
int msql_drop_db(string database_name, int link_identifier);
Returns true on success, false on failure.
msql_drop_db() attempts to drop (remove) an entire database from the server associated with the specified link identifier.
See also: msql_create_db().
msql_dropdb
msql_dropdb -- drop (delete) mSQL database
Description
See msql_drop_db().
msql_error
msql_error -- returns error message of last msql call
Description
string msql_error( );
Errors coming back from the mSQL database backend no longer issue warnings. Instead, use these functions to retrieve the error string.
msql_fetch_array
msql_fetch_array -- fetch row as array
Description
int msql_fetch_array(int query_identifier);
Returns an array that corresponds to the fetched row, or false if there are no more rows.
msql_fetch_array() is an extended version of msql_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.
Be careful if you are retrieving results from a query that may return a record that contains only one field that has a value of 0 (or an empty string, or NULL).
An important thing to note is that using msql_fetch_array() is NOT significantly slower than using msql_fetch_row(), while it provides a significant added value.
For further details, also see msql_fetch_row()
msql_fetch_field
msql_fetch_field -- get field information
Description
object msql_fetch_field(int query_identifier, int field_offset);
Returns an object containing field information
msql_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 retreived by msql_fetch_field() is retreived.
The properties of the object are:
name - column name
table - name of the table the column belongs to
not_null - 1 if the column cannot be null
primary_key - 1 if the column is a primary key
unique - 1 if the column is a unique key
type - the type of the column
See also msql_field_seek().
msql_fetch_object
msql_fetch_object -- fetch row as object
Description
int msql_fetch_object(int query_identifier);
Returns an object with properties that correspond to the fetched row, or false if there are no more rows.
msql_fetch_object() is similar to msql_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).
Speed-wise, the function is identical to msql_fetch_array(), and almost as quick as msql_fetch_row() (the difference is insignificant).
See also: msql_fetch_array() and msql_fetch_row().
msql_fetch_row
msql_fetch_row -- get row as enumerated array
Description
array msql_fetch_row(int query_identifier);
Returns an array that corresponds to the fetched row, or false if there are no more rows.
msql_fetch_row() fetches one row of data from the result associated with the specified query identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0.
Subsequent call to msql_fetch_row() would return the next row in the result set, or false if there are no more rows.
See also: msql_fetch_array(), msql_fetch_object(), msql_data_seek(), and msql_result().
msql_fieldname
msql_fieldname -- get field name
Description
string msql_fieldname(int query_identifier, int field);
msql_fieldname() returns the name of the specified field. query_identifier is the query identifier, and field is the field index. msql_fieldname($result, 2); will return the name of the second field in the result associated with the result identifier.
msql_field_seek
msql_field_seek -- set field offset
Description
int msql_field_seek(int query_identifier, int field_offset);
Seeks to the specified field offset. If the next call to msql_fetch_field() won't include a field offset, this field would be returned.
See also: msql_fetch_field().
msql_fieldtable
msql_fieldtable -- get table name for field
Description
int msql_fieldtable(int query_identifier, int field);
Returns the name of the table field was fetched from.
msql_fieldtype
msql_fieldtype -- get field type
Description
string msql_fieldtype(int query_identifier, int i);
msql_fieldtype() is similar to the msql_fieldname() function. The arguments are identical, but the field type is returned. This will be one of "int", "string" or "real".
msql_fieldflags
msql_fieldflags -- get field flags
Description
string msql_fieldflags(int query_identifier, int i);
msql_fieldflags() returns the field flags of the specified field. Currently this is either, "not null", "primary key", a combination of the two or "" (an empty string).
msql_fieldlen
msql_fieldlen -- get field length
Description
int msql_fieldlen(int query_identifier, int i);
msql_fieldlen() returns the length of the specified field.
msql_free_result
msql_free_result -- free result memory
Description
int msql_free_result(int query_identifier);
msql_free_result() frees the memory associated with query_identifier. When PHP completes a request, this memory is freed automatically, so you only need to call this function when you want to make sure you don't use too much memory while the script is running.
msql_freeresult
msql_freeresult -- free result memory
Description
See msql_free_result()
msql_list_fields
msql_list_fields -- list result fields
Description
int msql_list_fields(string database, string tablename);
msql_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 msql_fieldflags(), msql_fieldlen(), msql_fieldname(), and msql_fieldtype(). A query 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 @msql_list_fields() then this error string will also be printed out.
See also msql_error().
msql_listfields
msql_listfields -- list result fields
Description
See msql_list_fields().
msql_list_dbs
msql_list_dbs -- list mSQL databases on server
Description
int msql_list_dbs(void);
msql_list_dbs() will return a result pointer containing the databases available from the current msql daemon. Use the msql_dbname() function to traverse this result pointer.
msql_listdbs
msql_listdbs -- list mSQL databases on server
Description
See msql_list_dbs().
msql_list_tables
msql_list_tables -- list tables in an mSQL database
Description
int msql_list_tables(string database);
msql_list_tables() takes a database name and result pointer much like the msql() function. The msql_tablename() function should be used to extract the actual table names from the result pointer.
msql_listtables
msql_listtables -- list tables in an mSQL database
Description
See msql_list_tables().
msql_num_fields
msql_num_fields -- get number of fields in result
Description
int msql_num_fields(int query_identifier);
msql_num_fields() returns the number of fields in a result set.
See also: msql(), msql_query(), msql_fetch_field(), and msql_num_rows().
msql_num_rows
msql_num_rows -- get number of rows in result
Description
int msql_num_rows(int query_identifier);
msql_num_rows() returns the number of rows in a result set.
See also: msql(), msql_query(), and msql_fetch_row().
msql_numfields
msql_numfields -- get number of fields in result
Description
int msql_numfields(int query_identifier);
Identical to msql_num_fields().
msql_numrows
msql_numrows -- get number of rows in result
Description
int msql_numrows(void);
Identical to msql_num_rows().
msql_pconnect
msql_pconnect -- open persistent mSQL connection
Description
int msql_pconnect(string hostname);
Returns a positive mSQL persistent link identifier on success, or false on error.
msql_pconnect() acts very much like msql_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. If one is found, an identifier for it 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 (msql_close() will not close links established by msql_pconnect()).
This type of links is therefore called 'persistent'.
msql_query
msql_query -- send mSQL query
Description
int msql_query(string query, int link_identifier);
msql_query() sends a query to the currently active database on the server that's associated with the specified link identifier. If the 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 msql_connect() was called, and use it.
Returns a positive mSQL query identifier on success, or false on error.
See also: msql(), msql_select_db(), and msql_connect().
msql_regcase
msql_regcase -- make regular expression for case insensitive match
Description
See sql_regcase().
msql_result
msql_result -- get result data
Description
int msql_result(int query_identifier, int i, mixed field);
Returns the contents of the cell at the row and offset in the specified mSQL result set.
msql_result() returns the contents of one cell from a mSQL result set. The field argument can be the 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.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than msql_result(). Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.
Recommended high-performance alternatives: msql_fetch_row(), msql_fetch_array(), and msql_fetch_object().
msql_select_db
msql_select_db -- select mSQL database
Description
int msql_select_db(string database_name, int link_identifier);
Returns true on success, false on error.
msql_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 msql_connect() was called, and use it.
Every subsequent call to msql_query() will be made on the active database.
See also: msql_connect(), msql_pconnect(), and msql_query().
msql_selectdb
msql_selectdb -- select mSQL database
Description
See msql_select_db().
msql_tablename
msql_tablename -- get table name of field
Description
string msql_tablename(int query_identifier, int field);
msql_tablename() takes a result pointer returned by the msql_list_tables() function as well as an integer index and returns the name of a table. The msql_numrows() function may be used to determine the number of tables in the result pointer.
Example 1. msql_tablename() example
<?php
msql_connect ("localhost");
$result = msql_list_tables("wisconsin");
$i = 0;
while ($i < msql_numrows($result)) {
$tb_names[$i] = msql_tablename($result, $i);
echo $tb_names[$i] . "<BR>";
$i++;
}
?>
XXVI. MySQL Functions
Table of Contents
mysql_affected_rows
mysql_close
mysql_connect
mysql_create_db
mysql_data_seek
mysql_db_query
mysql_drop_db
mysql_errno
mysql_error
mysql_fetch_array
mysql_fetch_field
mysql_fetch_lengths
mysql_fetch_object
mysql_fetch_row
mysql_field_name
mysql_field_seek
mysql_field_table
mysql_field_type
mysql_field_flags
mysql_field_len
mysql_free_result
mysql_insert_id
mysql_list_fields
mysql_list_dbs
mysql_list_tables
mysql_num_fields
mysql_num_rows
mysql_pconnect
mysql_query
mysql_result
mysql_select_db
mysql_tablename
These functions allow you to access MySQL database servers.
More information about MySQL can be found at
http://www.mysql.com/.mysql_affected_rows
mysql_affected_rows -- Get number of affected rows in previous MySQL operation
Description
int mysql_affected_rows(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.
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.
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().
mysql_close
mysql_close -- close MySQL connection
Description
int mysql_close(int [link_identifier] );
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.
Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
mysql_close() will not close persistent links generated by mysql_pconnect().
See also: mysql_connect(), and mysql_pconnect().
mysql_connect
mysql_connect -- Open a connection to a MySQL Server
Description
int mysql_connect(string [hostname] [:port] , string [username] , string [password] );
Returns: A positive MySQL link identifier on success, or false on 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). The hostname string can also include a port number. eg. "hostname:port"
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 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().
See also mysql_pconnect(), and mysql_close().
mysql_create_db
mysql_create_db -- Create a MySQL database
Description
int mysql_create_db(string database name, int [link_identifier] );
mysql_create_db() attempts to create a new database on the server associated with the specified link identifier.
See also: mysql_drop_db(). For downwards compatibility mysql_createdb() can also be used.
mysql_data_seek
mysql_data_seek -- Move internal result pointer
Description
int mysql_data_seek(int result_identifier, int row_number);
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.
mysql_db_query
mysql_db_query -- Send an MySQL query to MySQL
Description
int mysql_db_query(string database, string query, int [link_identifier] );
Returns: A positive MySQL result identifier to the query result, 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
See also mysql_connect(). For downwards compatibility mysql() can also be used.
mysql_drop_db
mysql_drop_db -- Drop (delete) a MySQL database
Description
int mysql_drop_db(string database_name, int [link_identifier] );
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.
See also: mysql_create_db(). For downward compatibility mysql_dropdb() can also be used.
mysql_errno
mysql_errno -- Returns the number of the error message from previous MySQL operation
Description
int mysql_errno(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
mysql_connect("marliesle");
echo mysql_errno().": ".mysql_error()."<BR>";
mysql_select_db("nonexistentdb");
echo mysql_errno().": ".mysql_error()."<BR>";
$conn = mysql_query("SELECT * FROM nonexistenttable");
echo mysql_errno().": ".mysql_error()."<BR>";
?>
See also: mysql_error()
mysql_error
mysql_error -- Returns the text of the error message from previous MySQL operation
Description
string mysql_error(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
mysql_connect("marliesle");
echo mysql_errno().": ".mysql_error()."<BR>";
mysql_select_db("nonexistentdb");
echo mysql_errno().": ".mysql_error()."<BR>";
$conn = mysql_query("SELECT * FROM nonexistenttable");
echo mysql_errno().": ".mysql_error()."<BR>";
?>
See also: mysql_errno()
mysql_fetch_array
mysql_fetch_array -- Fetch a result row as an associative array
Description
array mysql_fetch_array(int result);
Returns an array that corresponds to the fetched row, or false if there are no more rows.
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.
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.
For further details, also see mysql_fetch_row()
Example 1. mysql fetch array
<?php
mysql_connect($host,$user,$password);
$result = mysql_db_query("database","select * from table");
while($row = mysql_fetch_array($result)) {
echo $row["user_id"];
echo $row["fullname"];
}
mysql_free_result($result);
?>
mysql_fetch_field
mysql_fetch_field -- Get column information from a result and return as an object
Description
object mysql_fetch_field(int result, int [field_offset] );
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.
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 it 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()
mysql_fetch_lengths
mysql_fetch_lengths -- Get max data size of each output in a result
Description
array mysql_fetch_lengths(int 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.
mysql_fetch_lengths() stores the lengths of each result column in the last row returned by mysql_fetch_row() in an array, starting at offset 0.
See also: mysql_fetch_row().
mysql_fetch_object
mysql_fetch_object -- Fetch a result row as an object
Description
object mysql_fetch_object(int result);
Returns an object with properties that correspond to the fetched 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).
Speed-wise, the function is identical to mysql_fetch_array(), and almost as quick as mysql_fetch_row() (the difference is insignificant).
Example 1. mysql fetch object
<?php
mysql_connect($host,$user,$password);
$result = mysql_db_query("database","select * from table");
while($row = mysql_fetch_object($result)) {
echo $row->user_id;
echo $row->fullname;
}
mysql_free_result($result);
?>
See also: mysql_fetch_array() and mysql_fetch_row().
mysql_fetch_row
mysql_fetch_row -- Get a result row as an enumerated array
Description
array mysql_fetch_row(int result);
Returns: An array that corresponds to the fetched row, or false 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.
Subsequent call to mysql_fetch_row() would return the next row in the result set, or false if there are no more rows.
See also: mysql_fetch_array(), mysql_fetch_object(), mysql_data_seek(), mysql_fetch_lengths(), and mysql_result().
mysql_field_name
mysql_field_name -- Get the name of the specified field in a result
Description
string mysql_field_name(int result, int field_index);
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);
Will return the name of the second field in the result associated with the result identifier.
For downwards compatibility mysql_fieldname() can also be used.
mysql_field_seek
mysql_field_seek -- Set result pointer to a specified field offset
Description
int mysql_field_seek(int result, int field_offset);
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.
See also: mysql_fetch_field().
mysql_field_table
mysql_field_table -- Get name of the table the specified field is in
Description
string mysql_field_table(int result, int field_offset);
Get the table name for field. For downward compatibility mysql_fieldtable() can also be used.
mysql_field_type
mysql_field_type -- Get the type of the specified field in a result
Description
string mysql_field_type(int result, int field_offset);
mysql_field_type() is similar to the mysql_field_name() function. The arguments are identical, but the field type is returned. This will be one of "int", "real", "string", "blob", or others as detailed in the MySQL documentation.
Example 1. mysql field types
<?php
mysql_connect("localhost:3306");
mysql_select_db("wisconsin");
$result = mysql_query("SELECT * FROM onek");
$fields = mysql_num_fields($result);
$rows = mysql_num_rows($result);
$i = 0;
$table = mysql_field_table($result, $i);
echo "Your '".$table."' table has ".$fields." fields and ".$rows." records <BR>";
echo "The table has the following fields <BR>";
while ($i < $fields) {
$type = mysql_field_type ($result, $i);
$name = mysql_field_name ($result, $i);
$len = mysql_field_len ($result, $i);
$flags = mysql_field_flags ($result, $i);
echo $type." ".$name." ".$len." ".$flags."<BR>";
$i++;
}
mysql_close();
?>
For downward compatibility mysql_fieldtype() can also be used.
mysql_field_flags
mysql_field_flags -- Get the flags associated with the specified field in a result
Description
string mysql_field_flags(int result, int field_offset);
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().
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".
For downward compatibility mysql_fieldflags() can also be used.
mysql_field_len
mysql_field_len -- Returns the length of the specified field
Description
int mysql_field_len(int result, int field_offset);
mysql_field_len() returns the length of the specified field. For downward compatibility mysql_fieldlen() can also be used.
mysql_free_result
mysql_free_result -- Free result memory
Description
int mysql_free_result(int result);
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.
For downward compatibility mysql_freeresult() can also be used.
mysql_insert_id
mysql_insert_id -- Get the id generated from the previous INSERT operation
Description
int mysql_insert_id(int [link_identifier] );
mysql_insert_id() returns the ID generated for an AUTO_INCREMENTED field. This function takes no arguments. It will return the auto-generated ID returned by the last INSERT query performed.
mysql_list_fields
mysql_list_fields -- List MySQL result fields
Description
int mysql_list_fields(string database_name, string table_name, 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(), mysql_field_name(), and 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.
For downward compatibility mysql_listfields() can also be used.
mysql_list_dbs
mysql_list_dbs -- List databases available on on MySQL server
Description
int mysql_list_dbs(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.
For downward compatibility mysql_listdbs() can also be used.
mysql_list_tables
mysql_list_tables -- List tables in a MySQL database
Description
int mysql_list_tables(string database, int [link_identifier] );
mysql_list_tables() takes a database name and 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.
For downward compatibility mysql_listtables() can also be used.
mysql_num_fields
mysql_num_fields -- Get number of fields in result
Description
int mysql_num_fields(int result);
mysql_num_fields() returns the number of fields in a result set.
See also: mysql_db_query(), mysql_query(), mysql_fetch_field(), mysql_num_rows().
For downward compatibility mysql_numfields() can also be used.
mysql_num_rows
mysql_num_rows -- Get number of rows in result
Description
int mysql_num_rows(int result);
mysql_num_rows() returns the number of rows in a result set.
See also: mysql_db_query(), mysql_query() and, mysql_fetch_row().
For downward compatibility mysql_numrows() can also be used.
mysql_pconnect
mysql_pconnect -- Open a persistent connection to a MySQL Server
Description
int mysql_pconnect(string [hostname] [:port] , string [username] , string [password] );
Returns: A positive MySQL persistent link identifier on success, or false on error
mysql_pconnect() acts very much like 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.
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()).
This type of links is therefore called 'persistent'.
mysql_query
mysql_query -- Send an SQL query to MySQL
Description
int mysql_query(string query, int [link_identifier] );
mysql_query() sends a query to the currently active database on the server that's associated with the specified link identifier. If 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, and use it.
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 mysql_free_result().
See also: mysql_db_query(), mysql_select_db(), and mysql_connect().
mysql_result
mysql_result -- Get result data
Description
int mysql_result(int result, int row, mixed field);
mysql_result() returns the contents of one cell from a MySQL result set. The field argument can be the 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.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one 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.
Calls mysql_result() should not be mixed 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_select_db
mysql_select_db -- Select a MySQL database
Description
int mysql_select_db(string database_name, int [link_identifier] );
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.
Every subsequent call to mysql_query() will be made on the active database.
See also: mysql_connect(), mysql_pconnect(), and mysql_query()
For downward compatibility mysql_selectdb() can also be used.
mysql_tablename
mysql_tablename -- get table name of field
Description
string mysql_tablename(int result, int i);
mysql_tablename() takes a result pointer returned by the mysql_list_tables() function 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.
Example 1. mysql_tablename() example
<?php
mysql_connect ("localhost:3306");
$result = mysql_listtables ("wisconsin");
$i = 0;
while ($i < mysql_num_rows ($result)) {
$tb_names[$i] = mysql_tablename ($result, $i);
echo $tb_names[$i] . "<BR>";
$i++;
}
?>
XXVII. Sybase Functions
Table of Contents
sybase_affected_rows
sybase_close
sybase_connect
sybase_data_seek
sybase_fetch_array
sybase_fetch_field
sybase_fetch_object
sybase_fetch_row
sybase_field_seek
sybase_free_result
sybase_num_fields
sybase_num_rows
sybase_pconnect
sybase_query
sybase_result
sybase_select_db
sybase_affected_rows
sybase_affected_rows -- get number of affected rows in last query
Description
int sybase_affected_rows(int [link_identifier] );
Returns: The number of affected rows by the last query.
sybase_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.
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 sybase_num_rows().
sybase_close
sybase_close -- close Sybase connection
Description
int sybase_close(int link_identifier);
Returns: true on success, false on error
sybase_close() closes the link to a Sybase database that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed.
Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution.
sybase_close() will not close persistent links generated by sybase_pconnect().
See also: sybase_connect(), sybase_pconnect().
sybase_connect
sybase_connect -- open Sybase server connection
Description
int sybase_connect(string servername, string username, string password);
Returns: A positive Sybase link identifier on success, or false on error.
sybase_connect() establishes a connection to a Sybase server. The servername argument has to be a valid servername that is defined in the 'interfaces' file.
In case a second call is made to sybase_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 link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling sybase_close().
See also sybase_pconnect(), sybase_close().
sybase_data_seek
sybase_data_seek -- move internal row pointer
Description
int sybase_data_seek(int result_identifier, int row_number);
Returns: true on success, false on failure
sybase_data_seek() moves the internal row pointer of the Sybase result associated with the specified result identifier to pointer to the specifyed row number. The next call to sybase_fetch_row() would return that row.
See also: sybase_data_seek().
sybase_fetch_array
sybase_fetch_array -- fetch row as array
Description
int sybase_fetch_array(int result);
Returns: An array that corresponds to the fetched row, or false if there are no more rows.
sybase_fetch_array() is an extended version of sybase_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.
An important thing to note is that using sybase_fetch_array() is NOT significantly slower than using sybase_fetch_row(), while it provides a significant added value.
For further details, also see sybase_fetch_row()
sybase_fetch_field
sybase_fetch_field -- get field information
Description
object sybase_fetch_field(int result, int field_offset);
Returns an object containing field information.
sybase_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 retreived by sybase_fetch_field() is retreived.
The properties of the object are:
name - column name. if the column is a result of a function, this property is set to computed#N, where #N is a serial number.
column_source - the table from which the column was taken
max_length - maximum length of the column
numeric - 1 if the column is numeric
See also sybase_field_seek()
sybase_fetch_object
sybase_fetch_object -- fetch row as object
Description
int sybase_fetch_object(int result);
Returns: An object with properties that correspond to the fetched row, or false if there are no more rows.
sybase_fetch_object() is similar to sybase_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).
Speed-wise, the function is identical to sybase_fetch_array(), and almost as quick as sybase_fetch_row() (the difference is insignificant).
See also: sybase_fetch-array() and sybase_fetch-row().
sybase_fetch_row
sybase_fetch_row -- get row as enumerated array
Description
array sybase_fetch_row(int result);
Returns: An array that corresponds to the fetched row, or false if there are no more rows.
sybase_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.
Subsequent call to sybase_fetch_rows() would return the next row in the result set, or false if there are no more rows.
See also: sybase_fetch_array(), sybase_fetch_object(), sybase_data_seek(), sybase_fetch_lengths(), and sybase_result().
sybase_field_seek
sybase_field_seek -- set field offset
Description
int sybase_field_seek(int result, int field_offset);
Seeks to the specified field offset. If the next call to sybase_fetch_field() won't include a field offset, this field would be returned.
See also: sybase_fetch_field().
sybase_free_result
sybase_free_result -- free result memory
Description
int sybase_free_result(int result);
sybase_free_result() only needs to be called if you are worried about using too much memory while your script is running. All result memory will automatically be freed when the script, you may call sybase_free_result() with the result identifier as an argument and the associated result memory will be freed.
sybase_num_fields
sybase_num_fields -- get number of fields in result
Description
int sybase_num_fields(int result);
sybase_num_fields() returns the number of fields in a result set.
See also: sybase_db_query(), sybase_query(), sybase_fetch_field(), sybase_num_rows().
sybase_num_rows
sybase_num_rows -- get number of rows in result
Description
int sybase_num_rows(string result);
sybase_num_rows() returns the number of rows in a result set.
See also: sybase_db_query(), sybase_query() and, sybase_fetch_row().
sybase_pconnect
sybase_pconnect -- open persistent Sybase connection
Description
int sybase_pconnect(string servername, string username, string password);
Returns: A positive Sybase persistent link identifier on success, or false on error
sybase_pconnect() acts very much like sybase_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.
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 (sybase_close() will not close links established by sybase_pconnect()).
This type of links is therefore called 'persistent'.
sybase_query
sybase_query -- send Sybase query
Description
int sybase_query(string query, int link_identifier);
Returns: A positive Sybase result identifier on success, or false on error.
sybase_query() sends a query to the currently active database on the server that's associated with the specified link identifier. If the 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 sybase_connect() was called, and use it.
See also: sybase_db_query(), sybase_select_db(), and sybase_connect().
sybase_result
sybase_result -- get result data
Description
int sybase_result(int result, int i, mixed field);
Returns: The contents of the cell at the row and offset in the specified Sybase result set.
sybase_result() returns the contents of one cell from a Sybase result set. The field argument can be the 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.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than sybase_result(). Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.
Recommended high-performance alternatives: sybase_fetch_row(), sybase_fetch_array(), and sybase_fetch_object().
sybase_select_db
sybase_select_db -- select Sybase database
