ODBC Functions

ODBC Functions

odbc_autocommit

Name

odbc_autocommit — Toggle autocommit behaviour

Description

int odbc_autocommit(int connection_id, int [OnOff]);

Without the OnOff parameter, this function returns auto-commit status for connection_id. True is returned if auto-commit is on, false if it is off or an error occurs.

If OnOff is true, auto-commit is enabled, if it is false auto-commit is disabled. Returns true on success, false on failure.

By default, auto-commit is on for a connection. Disabling auto-commit is equivalent with starting a transaction.

See also odbc_commit and odbc_rollback.

odbc_binmode

Name

odbc_binmode — handling of binary column data

Description

int odbc_binmode(int result_id, int mode);

(ODBC SQL types affected: BINARY, VARBINARY, LONGVARBINARY)

• ODBC_BINMODE_PASSTHRU: Passthru BINARY data

• ODBC_BINMODE_RETURN: Return as is

• ODBC_BINMODE_CONVERT: Convert to char and return

When binary SQL data is converted to character C data, each byte (8 bits) of source data is represented as two ASCII characters. These characters are the ASCII character representation of the number in its hexadecimal form. For example, a binary 00000001 is converted to "01" and a binary 11111111 is converted to "FF".

Table 1. LONGVARBINARY handling

If odbc_fetch_into is used, passthru means that an empty string is returned for these columns. If result_id is 0, the settings apply as default for new results.

Default for longreadlen is 4096 and binmode defaults to ODBC_BINMODE_RETURN. Handling of binary long columns is also affected by odbc_longreadlen

odbc_close

Name

odbc_close — Close an ODBC connection

Description

void odbc_close(int connection_id);

odbc_close will close down the connection to the database server associated with the given connection identifier.

This function will fail if there are open transactions on this connection. The connection will remain open in this case.

odbc_close_all

Name

odbc_close_all — Close all ODBC connections

Description

void odbc_close_all(void);

odbc_close_all will close down all connections to database server(s).

This function will fail if there are open transactions on a connection. This connection will remain open in this case.

odbc_commit

Name

odbc_commit — Commit an ODBC transaction

Description

int odbc_commit(int connection_id);

Returns: true on success, false on failure. All pending transactions on connection_id are committed.

odbc_connect

Name

odbc_connect — Connect to a datasource

Description

int odbc_connect(string dsn, string user, string password);

Returns an ODBC connection id or 0 (false) on error.

The connection id returned by this functions is needed by other ODBC functions. You can have multiple connections open at once. For persistent connections see odbc_pconnect.

odbc_cursor

Name

odbc_cursor — Get cursorname

Description

string odbc_cursor(int result_id);

odbc_cursor will return a cursorname for the given result_id.

odbc_do

Name

odbc_do — synonym for odbc_exec

Description

string odbc_do(int conn_id, string query);

odbc_do will execute a query on the given connection

odbc_exec

Name

odbc_exec — Prepare and execute a SQL statement

Description

int odbc_exec(int connection_id, string query_string);

Returns false on error. Returns an ODBC result identifier if the SQL command was executed successfully.

odbc_exec will send an SQL statement to the database server specified by connection_id. This parameter must be a valid identifier returned by odbc_connect or odbc_pconnect.

See also: odbc_prepare and odbc_execute for multiple execution of SQL statements.

odbc_execute

Name

odbc_execute — execute a prepated statement

Description

int odbc_execute(int result_id, array [parameters_array]);

Executes a statement prepared with odbc_prepare. Returns true on successful execution, false otherwise. The array arameters_array only needs to be given if you really have parameters in your statement.

odbc_fetch_into

Name

odbc_fetch_into — Fetch one result row into array

Description

int odbc_fetch_into(int result_id, int [rownumber], array result_array);

Returns the number of columns in the result; false on error. result_array must be passed by reference, but it can be of any type since it will be converted to type array. The array will contain the column values starting at array index 0.

odbc_fetch_row

Name

odbc_fetch_row — Fetch a row

Description

int odbc_fetch_row(int result_id, int [row_number]);

If odbc_fetch_row was succesful (there was a row), true is returned. If there are no more rows,

false is returned.

odbc_fetch_row fetches a row of the data that was returned by odbc_do / odbc_exec. After

odbc_fetch_row is called, the fields of that row can be accessed with odbc_result.

If row_number is not specified, odbc_fetch_row will try to fetch the next row in the result set. Calls to odbc_fetch_row with and without row_number can be mixed.

To step through the result more than once, you can call odbc_fetch_row with row_number 1, and then continue doing odbc_fetch_row without row_number to review the result. If a driver doesn't support fetching rows by number, the row_number parameter is ignored.

odbc_field_name

Name

odbc_field_name — Get the columnname

Description

string odbc_fieldname(int result_id, int field_number);

odbc_field_name will return the name of the field occupying the given column number in the given ODBC result identifier. Field numbering starts at 1. false is returned on error.

odbc_field_num

Name

odbc_field_num — return column number

Description

int odbc_fieldnum(int result_id, string field_name);

odbc_field_num will return the number of the column slot that corresponds to the named field in the given ODBC result identifier. Field numbering starts at 1. false is returned on error.

odbc_field_type

Name

odbc_field_type — datatype of a field

Description

string odbc_field_type(int result_id, mixed field);

odbc_field_type will return the SQL type of the field referecend by name or number in the given ODBC result identifier. Field numbering runs from 1.

odbc_free_result

Name

odbc_free_result — free resources associated with a result

Description

int odbc_free_result(int result_id);

Always returns true.

odbc_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 is finished. But, if you are sure you are not going to need the result data anymore in a script, you may call odbc_free_result, and the memory associated with result_id will be freed.

If auto-commit is disabled (see odbc_autocommit) and you call odbc_free_result before commiting, all pending transactions are rolled back.

odbc_longreadlen

Name

odbc_longreadlen — handling of LONG columns

Description

int odbc_longreadlen(int result_id, int length);

(ODBC SQL types affected: LONG, LONGVARBINARY) The number of bytes returned to PHP is controled by the parameter length. If it is set to 0, Long column data is passed thru to the client.

Handling of LONGVARBINARY columns is also affected by odbc_binmode

odbc_num_fields

Name

odbc_num_fields — number of columns in a result

Description

int odbc_num_fields(int result_id);

odbc_num_fields will return the number of fields (columns) in an ODBC result. This function will return -1 on error. The argument is a valid result identifier returned by odbc_exec.

odbc_pconnect

Name

odbc_pconnect — Open a persistent database connection

Description

int odbc_pconnect(string dsn, string user, string password);

Returns an ODBC connection id or 0 (false) on error. This function is much like odbc_connect, except that the connection is not really closed when the script has finished. Future requests for a connection with the same dsn, user, password combination (via odbc_connect and odbc_pconnect) can reuse the persistent connection.

Persistent connections have no effect if PHP is used as a CGI program.

For more information on persistent connections, refer to the PHP3 FAQ.

odbc_prepare

Name

odbc_prepare — Prepares a statement for execution

Description

int odbc_prepare(int connection_id, string query_string);

Returns false on error.

Returns an ODBC result identifier if the SQL command was prepared successfully. The result identifier can be used later to execute the statement with odbc_execute.

odbc_num_rows

Name

odbc_num_rows — Number of rows in a result

Description

int odbc_num_rows(int result_id);

odbc_num_rows will return the number of rows in an ODBC result. This function will return -1 on error. For INSERT, UPDATE and DELETE statements odbc_num_rows returns the number of rows affected. For a SELECT clause this can be the number of rows available.

Note: Using odbc_num_rows to determine the number of rows available after a SELECT will return -1 with many drivers.

odbc_result

Name

odbc_result — get result data

Description

string odbc_result(int result_id, mixed field);

Returns the contents of the field.

Field indices start from 1. Regarding the way binary or long column data is returned refer to

odbc_binmode and odbc_longreadlen.

odbc_result_all

Name

odbc_result_all — Print result as HTML table

Description

int odbc_result_all(int result_id, string [format]);

Returns the number of rows in the result or false on error.

odbc_result_all will print all rows from a result identifier produced by odbc_exec. The result is printed in HTML table format. With the optional string argument format, additional overall table formatting can be done.

odbc_rollback

Name

odbc_rollback — Rollback a transaction

Description

int odbc_rollback(int connection_id);

Rolls back all pending statements on connection_id. Returns true on success, false on failure.