# MaxDB PHP Extension

## Introduction

The MaxDB PHP extension allows you to access the functionality provided by MaxDB 7.5.0 and above. More information about the MaxDB Database server can be found at » http://www.mysql.com/products/maxdb/.

The MaxDB PHP extension is compatible to the MySQL mysqli extension. There are only minor differences in the behaviour of some functions due to the differences of the underlying database servers, MaxDB and MySQL.

The main differences to mysqli are in the following functions:

- maxdb_character_set_name() - Returns only ascii or unicode.
- maxdb_get_client_info() - Returns a different version string.
- maxdb_get_client_version() - Returns a different version string.
- maxdb_get_host_info() - Returns localhost or hostname.
- maxdb_get_server_info() - Returns a different version string.
- maxdb_get_server_version() - Returns a different version string.
- maxdb_kill() - Only disconnects the session.
- maxdb_multi_query() - Can not handle multiple SQL statements.
- maxdb_next_result() - Function returns always false.
- maxdb_options() - Supports a different set of options.
- maxdb_report() - Supports a different report mode.
- maxdb_stat() - Returns a different system status string.
- maxdb_stmt_store_result() - Is not necessary for MaxDB.
- maxdb_store_result() - Is not necessary for MaxDB.

Documentation for MaxDB can be found at » http://dev.mysql.com/doc/maxdb/.

## Requirements

In order to have these functions available, you must compile PHP with MaxDB support. Additionally, you must have the MaxDB SQLDBC runtime library available to access the MaxDB server.

Documentation for MaxDB SQLDBC can be found at » http://dev.mysql.com/doc/maxdb/.

Download the MaxDB SQLDBC package from » http://dev.mysql.com/downloads/maxdb/clients.html.

## Installation

By using the --with-maxdb[=DIR] configuration option you enable PHP to access MaxDB databases. [DIR] points to the directory that contains the installed MaxDB SQLDBC package.

Windows users will need to enable php_maxdb.dll inside of php.ini.

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

MaxDB Configuration Options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
maxdb.default_host | NULL | PHP_INI_ALL |
maxdb.default_db | NULL | PHP_INI_ALL |
maxdb.default_user | NULL | PHP_INI_ALL |
maxdb.default_pw | NULL | PHP_INI_ALL |
maxdb.long_readlen | "200" | PHP_INI_ALL |

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`maxdb.default_host` string

  The default server host to use when connecting to the database server if no other host is specified.

`maxdb.default_db` string

  The default server database to use when connecting if no other database is specified.

`maxdb.default_user` string

  The default user name to use when connecting to the database server if no other name is specified.

`maxdb.default_pw` string

  The default password to use when connecting to the database server if no other password is specified.

`maxdb.long_readlen` integer

  The default maximum length of bytes that is transferred to the client if long data is retrieved from the MaxDB database server.

## Predefined Classes

## maxdb

Represents a connection between PHP and a MaxDB database.

## Constructor

- maxdb - construct a new maxdb object

## Methods

- autocommit - turns on or off auto-commiting database modifications

- change_user - changes the user of the specified database connection

- character_set_name - returns the default character set for the database connection

- close - closes a previously opened connection

- commit - commits the current transaction

- connect - opens a new connection to MaxDB database server

- debug - performs debugging operations

- dump_debug_info - dumps debug information

- get_client_info - returns client version

- get_host_info - returns type of connection used

- get_server_info - returns version of the MaxDB server

- get_server_version - returns version of the MaxDB server

- init - initializes maxdb object

- info - retrieves information about the most recently executed query

- kill - asks the server to kill a MaxDB thread

- multi_query - performs multiple queries

- more_results - check if more results exist from currently executed multi-query

- next_result - reads next result from currently executed multi-query

- options - set options

- ping - pings a server connection or reconnects if there is no connection

- prepare - prepares a SQL query

- query - performs a query

- real_connect - attempts to open a connection to MaxDB database server

- escape_string - escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection

- rollback - rolls back the current transaction

- select_db - selects the default database

- ssl_set - sets ssl parameters

- stat - gets the current system status

- stmt_init- initializes a statement for use with maxdb_stmt_prepare

- store_result - transfers a resultset from last query

- use_result - transfers an unbuffered resultset from last query

- thread-safe - returns whether thread safety is given or not

## Properties

- affected_rows - gets the number of affected rows in a previous MaxDB operation

- client_info - returns the MaxDB client version as a string

- client_version - returns the MaxDB client version as an integer

- errno - returns the error code for the most recent function call

- error - returns the error string for the most recent function call

- field_count - returns the number of columns for the most recent query

- host_info - returns a string representing the type of connection used

- info - retrieves information about the most recently executed query

- insert_id - returns the auto generated id used in the last query

- protocol_version - returns the version of the MaxDB protocol used

- sqlstate - returns a string containing the SQLSTATE error code for the last error

- thread_id - returns the thread ID for the current connection

- warning_count - returns the number of warnings generated during execution of the previous SQL statement

## maxdb_stmt

Represents a prepared statement.

## Methods

- bind_param - binds variables to a prepared statement

- bind_result - binds variables to a prepared statement for result storage

- close - closes a prepared statement

- data-seek - seeks to an arbitrary row in a statement result set

- execute - executes a prepared statement

- fetch - fetches result from a prepared statement into bound variables

- free_result - frees stored result memory for the given statement handle

- result_metadata - retrieves a resultset from a prepared statement for metadata information

- prepare - prepares a SQL query

- send_long_data - sends data in chunks

- close_long_data - end sending long data

- reset - resets a prepared statement

- store_result - buffers complete resultset from a prepared statement

## Properties

- affected_rows - returns affected rows from last statement execution

- errno - returns errorcode for last statement function

- errno - returns errormessage for last statement function

- param_count - returns number of parameter for a given prepare statement

- sqlstate - returns a string containing the SQLSTATE error code for the last statement function

## maxdb_result

Represents the result set obtained from a query against the database.

## Methods

- close - closes resultset

- data_seek - moves internal result pointer

- fetch_field - gets column information from a resultset

- fetch_fields - gets information for all columns from a resulset

- fetch_field_direct - gets column information for specified column

- fetch_array - fetches a result row as an associative array, a numeric array, or both.

- fetch_assoc - fetches a result row as an associative array

- fetch_object - fetches a result row as an object

- fetch_row - gets a result row as an enumerated array

- close - frees result memory

- field_seek - set result pointer to a specified field offset

## Properties

- current_field - returns offset of current fieldpointer

- field_count - returns number of fields in resultset

- lengths - returns an array of columnlengths

- num_rows - returns number of rows in resultset

## Resource Types

This extension defines resources.

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

The following constants to use with maxdb_options() are defined. For further description of these constants see » http://dev.mysql.com/doc/maxdb/.

MaxDB PHP client constants
Constant | Description
--- | ---
MAXDB_COMPNAME | The component name used to initialise the SQLDBC runtime environment.
MAXDB_APPLICATION | The application to be connected to the database.
MAXDB_APPVERSION | The version of the application.
MAXDB_SQLMODE | The SQL mode.
MAXDB_UNICODE | TRUE, if the connection is an unicode (UCS2) client or FALSE, if not.
MAXDB_TIMEOUT | The maximum allowed time of inactivity after which the connection to the database is closed by the system.
MAXDB_ISOLATIONLEVEL | Specifies whether and how shared locks and exclusive locks are implicitly requested or released.
MAXDB_PACKETCOUNT | The number of different request packets used for the connection.
MAXDB_STATEMENTCACHESIZE | The number of prepared statements to be cached for the connection for re-use.
MAXDB_CURSORPREFIX | The prefix to use for result tables that are automatically named.

The function maxdb_fetch_array() uses a constant for the different types of result arrays. The following constants are defined:

MaxDB fetch constants
Constant | Description
--- | ---
MAXDB_ASSOC | Columns are returned into the array having the fieldname as the array index.
MAXDB_ASSOC_UPPER | Columns are returned into the array having the upper case fieldname as the array index.
MAXDB_ASSOC_LOWER | Columns are returned into the array having the lower case fieldname as the array index.
MAXDB_BOTH | Columns are returned into the array having both a numerical index and the fieldname as the array index.
MAXDB_NUM | Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result.

## Examples

All examples in the MaxDB PHP documentation use the HOTELDB demo database from MaxDB. More about this database can be found at » http://dev.mysql.com/doc/maxdb/en/98/11b83fa6b33c17e10000000a114084/frameset.htm.

To use the examples in the MaxDB PHP documentation, you have to load the tutorial data into your database. Then you have to set maxdb.default_db in php.ini to the database that contains the tutorial data.

This simple example shows how to connect, execute a query, print resulting rows and disconnect from a MaxDB database.

Example#1 MaxDB extension overview example

`<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (maxdb_connect_errno()) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Performing SQL query */
$query = "SELECT * FROM hotel.city";
$result = maxdb_query($link, $query) or die("Query failed : " . maxdb_error());
/* Printing results in HTML */
echo "<table>\n";
while ($line = maxdb_fetch_array($result, MAXDB_ASSOC)) {
echo " <tr>\n";
foreach ($line as $col_value) {
echo " <td>$col_value</td>\n";
}
echo " </tr>\n";
}
echo "</table>\n";
/* Free resultset */
maxdb_free_result($result);
/* Closing connection */
maxdb_close($link);
?>`

The following example shows how to bind variables to a SELECT INTO statement.

Example#2 Example for use of SELECT INTO statements

`<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "SELECT percentage INTO ? FROM hotel.countrylanguage where language = ?");
if (!$stmt) {
printf ("Prepare failed: %s\n", maxdb_error($link));
}
$name = "Mbundu";
maxdb_stmt_bind_param($stmt, 'ds', $percentage, $name);
maxdb_stmt_execute($stmt);
printf ("%f\n", $percentage);
maxdb_stmt_close ($stmt);
?>`

The following example shows how to use MaxDB database procedures.

Example#3 Example fore using database procedures

`<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
/* check connection */
if (!$link) {
printf("Connect failed: %s\n", maxdb_connect_error());
exit();
}
maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP DBPROC test_proc");
maxdb_report (MAXDB_REPORT_ERROR);
$query = "create dbproc test_proc (INOUT e_text char(72)) AS select * from SYSDBA.DUAL; fetch into :e_text;";
maxdb_query($link, $query);
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "CALL test_proc (?)");
if (!$stmt) {
printf ("Prepare failed: %s\n", maxdb_error($link));
}
maxdb_stmt_bind_param($stmt, 's', $result);
maxdb_stmt_execute($stmt);
printf ("%s\n", $result);
maxdb_stmt_close ($stmt);
?>`

## Table of Contents

- maxdb_affected_rows — Gets the number of affected rows in a previous MaxDB operation
- maxdb_autocommit — Turns on or off auto-commiting database modifications
- maxdb_bind_param — Alias of maxdb_stmt_bind_param
- maxdb_bind_result — Alias of maxdb_stmt_bind_result
- maxdb_change_user — Changes the user of the specified database connection
- maxdb_character_set_name — Returns the default character set for the database connection
- maxdb_client_encoding — Alias of maxdb_character_set_name
- maxdb_close_long_data — Alias of maxdb_stmt_close_long_data
- maxdb_close — Closes a previously opened database connection
- maxdb_commit — Commits the current transaction
- maxdb_connect_errno — Returns the error code from last connect call
- maxdb_connect_error — Returns a string description of the last connect error
- maxdb_connect — Open a new connection to the MaxDB server
- maxdb_data_seek — Adjusts the result pointer to an arbitary row in the result
- maxdb_debug — Performs debugging operations
- maxdb_disable_reads_from_master — Disable reads from master
- maxdb_disable_rpl_parse — Disable RPL parse
- maxdb_dump_debug_info — Dump debugging information into the log
- maxdb_embedded_connect — Open a connection to an embedded MaxDB server
- maxdb_enable_reads_from_master — Enable reads from master
- maxdb_enable_rpl_parse — Enable RPL parse
- maxdb_errno — Returns the error code for the most recent function call
- maxdb_error — Returns a string description of the last error
- maxdb_escape_string — Alias of maxdb_real_escape_string
- maxdb_execute — Alias of maxdb_stmt_execute
- maxdb_fetch_array — Fetch a result row as an associative, a numeric array, or both
- maxdb_fetch_assoc — Fetch a result row as an associative array
- maxdb_fetch_field_direct — Fetch meta-data for a single field
- maxdb_fetch_field — Returns the next field in the result set
- maxdb_fetch_fields — Returns an array of resources representing the fields in a result set
- maxdb_fetch_lengths — Returns the lengths of the columns of the current row in the result set
- maxdb_fetch_object — Returns the current row of a result set as an object
- maxdb_fetch_row — Get a result row as an enumerated array
- maxdb_fetch — Alias of maxdb_stmt_fetch
- maxdb_field_count — Returns the number of columns for the most recent query
- maxdb_field_seek — Set result pointer to a specified field offset
- maxdb_field_tell — Get current field offset of a result pointer
- maxdb_free_result — Frees the memory associated with a result
- maxdb_get_client_info — Returns the MaxDB client version as a string
- maxdb_get_client_version — Get MaxDB client info
- maxdb_get_host_info — Returns a string representing the type of connection used
- maxdb_get_metadata — Alias of maxdb_stmt_result_metadata
- maxdb_get_proto_info — Returns the version of the MaxDB protocol used
- maxdb_get_server_info — Returns the version of the MaxDB server
- maxdb_get_server_version — Returns the version of the MaxDB server as an integer
- maxdb_info — Retrieves information about the most recently executed query
- maxdb_init — Initializes MaxDB and returns an resource for use with maxdb_real_connect
- maxdb_insert_id — Returns the auto generated id used in the last query
- maxdb_kill — Disconnects from a MaxDB server
- maxdb_master_query — Enforce execution of a query on the master in a master/slave setup
- maxdb_more_results — Check if there any more query results from a multi query
- maxdb_multi_query — Performs a query on the database
- maxdb_next_result — Prepare next result from multi_query
- maxdb_num_fields — Get the number of fields in a result
- maxdb_num_rows — Gets the number of rows in a result
- maxdb_options — Set options
- maxdb_param_count — Alias of maxdb_stmt_param_count
- maxdb_ping — Pings a server connection, or tries to reconnect if the connection has gone down
- maxdb_prepare — Prepare a SQL statement for execution
- maxdb_query — Performs a query on the database
- maxdb_real_connect — Opens a connection to a MaxDB server
- maxdb_real_escape_string — Escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection
- maxdb_real_query — Execute an SQL query
- maxdb_report — Enables or disables internal report functions
- maxdb_rollback — Rolls back current transaction
- maxdb_rpl_parse_enabled — Check if RPL parse is enabled
- maxdb_rpl_probe — RPL probe
- maxdb_rpl_query_type — Returns RPL query type
- maxdb_select_db — Selects the default database for database queries
- maxdb_send_long_data — Alias of maxdb_stmt_send_long_data
- maxdb_send_query — Send the query and return
- maxdb_server_end — Shut down the embedded server
- maxdb_server_init — Initialize embedded server
- maxdb_set_opt — Alias of maxdb_options
- maxdb_sqlstate — Returns the SQLSTATE error from previous MaxDB operation
- maxdb_ssl_set — Used for establishing secure connections using SSL
- maxdb_stat — Gets the current system status
- maxdb_stmt_affected_rows — Returns the total number of rows changed, deleted, or inserted by the last executed statement
- maxdb_stmt_bind_param — Binds variables to a prepared statement as parameters
- maxdb_stmt_bind_result — Binds variables to a prepared statement for result storage
- maxdb_stmt_close_long_data — Ends a sequence of maxdb_stmt_send_long_data
- maxdb_stmt_close — Closes a prepared statement
- maxdb_stmt_data_seek — Seeks to an arbitray row in statement result set
- maxdb_stmt_errno — Returns the error code for the most recent statement call
- maxdb_stmt_error — Returns a string description for last statement error
- maxdb_stmt_execute — Executes a prepared Query
- maxdb_stmt_fetch — Fetch results from a prepared statement into the bound variables
- maxdb_stmt_free_result — Frees stored result memory for the given statement handle
- maxdb_stmt_init — Initializes a statement and returns an resource for use with maxdb_stmt_prepare
- maxdb_stmt_num_rows — Return the number of rows in statements result set
- maxdb_stmt_param_count — Returns the number of parameter for the given statement
- maxdb_stmt_prepare — Prepare a SQL statement for execution
- maxdb_stmt_reset — Resets a prepared statement
- maxdb_stmt_result_metadata — Returns result set metadata from a prepared statement
- maxdb_stmt_send_long_data — Send data in blocks
- maxdb_stmt_sqlstate — Returns SQLSTATE error from previous statement operation
- maxdb_stmt_store_result — Transfers a result set from a prepared statement
- maxdb_store_result — Transfers a result set from the last query
- maxdb_thread_id — Returns the thread ID for the current connection
- maxdb_thread_safe — Returns whether thread safety is given or not
- maxdb_use_result — Initiate a result set retrieval
- maxdb_warning_count — Returns the number of warnings from the last query for the given link