mSQL Functions

mSQL Functions

msql

Name

msql — send mSQL query

Description

int msql(string database, string query, int link_identifier);

Returns a positive mSQL result 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_close

Name

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

Name

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

Name

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

Name

msql_createdb — create mSQL database

Description

int msql_createdb(string database name, int [link_identifier] );

Identical to msql_create_db.

msql_data_seek

Name

msql_data_seek — move internal row pointer

Description

int msql_data_seek(int result_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 result 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

Name

msql_dbname — get current mSQL database name

Description

string msql_dbname(string result, 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

Name

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

Name

msql_dropdb — drop (delete) mSQL database

Description

See msql_drop_db.

msql_error

Name

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

Name

msql_fetch_array — fetch row as array

Description

int msql_fetch_array(int result);

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.

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

Name

msql_fetch_field — get field information

Description

object msql_fetch_field(int result, 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

Name

msql_fetch_object — fetch row as object

Description

int msql_fetch_object(int result);

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

Name

msql_fetch_row — get row as enumerated array

Description

array msql_fetch_row(int result);

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 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 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

Name

msql_fieldname — get field name

Description

string msql_fieldname(int result, int field);

msql_fieldname() returns the name of the specified field. result is the result 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

Name

msql_field_seek — set field offset

Description

int msql_field_seek(int result, 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

Name

msql_fieldtable — get table name for field

Description

int msql_fieldtable(int result, int field);

Returns the name of the table field was fetched from.

msql_fieldtype

Name

msql_fieldtype — get field type

Description

string msql_fieldtype(string result, 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

Name

msql_fieldflags — get field flags

Description

string msql_fieldflags(string result, 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

Name

msql_fieldlen — get field length

Description

int msql_fieldlen(string result, int i);

msql_fieldlen() returns the length of the specified field.

msql_free_result

Name

msql_free_result — free result memory

Description

int msql_free_result(int result);

msql_free_result frees the memory associated with result. 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

Name

msql_freeresult — free result memory

Description

See msql_free_result

msql_list_fields

Name

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 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 @msql_list_fields() then this error string will also be printed out.

See also msql_error.

msql_listfields

Name

msql_listfields — list result fields

Description

See msql_list_fields.

msql_list_dbs

Name

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

Name

msql_listdbs — list mSQL databases on server

Description

See msql_list_dbs.

msql_list_tables

Name

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

Name

msql_listtables — list tables in an mSQL database

Description

See msql_list_tables.

msql_num_fields

Name

msql_num_fields — get number of fields in result

Description

int msql_num_fields(int result);

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

Name

msql_num_rows — get number of rows in result

Description

int msql_num_rows(string result);

msql_num_rows() returns the number of rows in a result set. See also: msql, msql_query, and msql_fetch_row.

msql_numfields

Name

msql_numfields — get number of fields in result

Description

int msql_numfields(int result);

Identical to msql_num_fields.

msql_numrows

Name

msql_numrows — get number of rows in result

Description

int msql_numrows(void);

Identical to msql_num_rows.

msql_pconnect

Name

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

Name

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 result identifier on success, or false on error. See also: msql, msql_select_db, and msql_connect.

msql_regcase

Name

msql_regcase — make regular expression for case insensitive match

Description

See sql_regcase.

msql_result

Name

msql_result — get result data

Description

int msql_result(int result, 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

Name

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

Name

msql_selectdb — select mSQL database

Description

See msql_select_db.

msql_tablename

Name

msql_tablename — get table name of field

Description

string msql_tablename(int result, 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++;

}

?>