2.6 OCI Function Reference

Table of Contents Previous Next


2 Open Client Library : 2.6 OCI Function Reference

The OCIServerAttach method uses a connection descriptor specified in the dblink parameter of the tnsnames.ora file. Use the tnsnames.ora file, compatible with Oracle databases, to specify database connection addresses. Advanced Server searches the user's home directory for a file named tnsnames.ora. If Advanced Server doesn't find the tnsnames.ora file in the user's home directory, it searches the path specified by TNS_ADMIN.
The sample tnsnames.ora file contains:
Any parameters not included in the sample, are ignored by the Open Client Library. In the sample, SID refers to the database named edb, in the cluster running on server 'localhost' at port 5444.
A C program call to OCIServerAttach that uses the tnsnames.ora file will look like:
If you don't have a tnsnames.ora file, supply the connection string parameter in the form //localhost:5444/edbx.
Get handle attributes. Advanced server supports the following handle attributes: OCI_ATTR_USERNAME, OCI_ATTR_PASSWORD, OCI_ATTR_SERVER, OCI_ATTR_ENV, OCI_ATTR_SESSION, OCI_ATTR_ROW_COUNT, OCI_ATTR_CHARSET_FORM, OCI_ATTR_CHARSET_ID, EDB_ATTR_STMT_LEVEL_TX, OCI_ATTR_MODULE
Set handle attributes. Advanced server supports the following handle attributes: OCI_ATTR_USERNAME, OCI_ATTR_PASSWORD, OCI_ATTR_SERVER, OCI_ATTR_ENV, OCI_ATTR_SESSION, OCI_ATTR_ROW_COUNT, OCI_ATTR_CHARSET_FORM, OCI_ATTR_CHARSET_ID, EDB_ATTR_STMT_LEVEL_TX, OCI_ATTR_MODULE, OCI_ATTR_PREFETCH_ROWS
By default, Advanced Server will treat an empty string as a NULL value. You can use the EDB_ATTR_EMPTY_STRINGS environment attribute to control the behavior of the OCI connector when mapping empty strings. To modify the mapping behavior, use the OCIAttrSet() function to set EDB_ATTR_EMPTY_STRINGS to one of the following:
To find the value of EDB_ATTR_EMPTY_STRINGS, query OCIAttrGet().
Advanced Server supports statements that execute as WITH HOLD cursors. The EDB_ATTR_HOLDABLE attribute specifies which statements execute as WITH HOLD cursors. The EDB_ATTR_HOLDABLE attribute can be set to any of the following three values:
EDB_WITH_HOLD - execute as a WITH HOLD cursor
EDB_WITHOUT_HOLD - execute using a protocol-level prepared statement
OCI_DEFAULT - see the definition that follows
You can set the attribute in an OCIStmt handle or an OCIServer handle. When you create an OCIServer handle or an OCIStmt handle, the EDB_ATTR_HOLDABLE attribute for that handle is set to OCI_DEFAULT.
You can change the EDB_ATTR_HOLDABLE attribute for a handle by calling OCIAttrSet() and retrieve the attribute by calling OCIAttrGet().
When Advanced Server executes a SELECT statement, it examines the EDB_ATTR_HOLDABLE attribute in the OCIServer handle. If that attribute is set to EDB_WITH_HOLD, the query is executed as a WITH HOLD cursor.
If the EDB_ATTR_HOLDABLE attribute in the OCIServer handle is set to EDB_WITHOUT_HOLD, the query is executed as a normal prepared statement.
If the EDB_ATTR_HOLDABLE attribute in the OCIServer handle is set to OCI_DEFAULT, Advanced Server uses the value of the EDB_ATTR_HOLDABLE attribute in the OCIServer handle (if the EDB_ATTR_HOLDABLE attribute in the OCIServer is set to EDB_WITH_HOLD, the query executes as a WITH HOLD cursor, otherwise, the query executes as a protocol-prepared statement).
The EDB_HOLD_CURSOR_ACTION attribute alters the way WITH HOLD cursors are created using the OCI interface. You can set this attribute to any of the following values:
EDB_COMMIT_AFTER_CURSOR – commit the transaction after creating the cursor
EDB_CURSOR_WITHOUT_XACT_BLK – do not begin a new transaction chain
OCI_DEFAULT - see the definition that follows
Each time you execute a statement, the OCI examines the transaction state on the database server. If a transaction is not already in progress, the OCI executes a BEGIN statement to create a new transaction block, and then executes the statement that you provide. The transaction block remains open until you call OCITransCommit() or OCITransRollback().
By default, the database server closes any open cursors when you commit or rollback. If you (or the OCI) declare a cursor that includes the WITH HOLD clause, the cursor result set is persisted on the database server, and you may continue to fetch from that cursor. However, the database server will not persist open cursors when you roll back a transaction. If you try to fetch from a cursor after a ROLLBACK, the database server will report an error.
If your application must read from a WITH HOLD cursor after rolling back a transaction, you can arrange for the OCI to commit the transaction immediately after creating the cursor by setting EDB_HOLD_CURSOR_ACTION to EDB_COMMIT_AFTER_CURSOR prior to creating such a cursor. For example:
It is important to understand that using EDB_COMMIT_AFTER_CURSOR will commit any pending changes.
If your application will not run properly with the extra commits added by EDB_COMMIT_AFTER_CURSOR, you may try setting EDB_ATTR_HOLD_CURSOR_ACTION to EDB_CURSOR_WITHOUT_XACT_BLK. With this action, the OCI will not begin a new transaction chain. If you create a WITH HOLD cursor immediately after committing or rolling back a transaction, the cursor will be created in its own transaction, the database server will commit that transaction, and the cursor will persist.
It is important to understand that you may still experience errors if the cursor declaration is not the first statement within a transaction – if you execute some other statement before declaring the cursor, the WITH HOLD cursor will be created in a transaction block and may be rolled back if an error occurs (or if your application calls OCITransRollback()).
Please note that you can set the EDB_HOLD_CURSOR_ACTION on the server level (OCIServer) or for each statement handle (OCIStmt). If the statement attribute is set to a value other than OCI_DEFAULT, the value is derived from the statement handle, otherwise (if the statement attribute is set to OCI_DEFAULT), the value is taken from the server handle. So you can define a server-wide default action by setting the attribute in the server handle, and leaving the attribute set to OCI_DEFAULT in the statement handles. You can use different values for each statement handle (or server handle) as you see fit.
Unless otherwise instructed, the OCI connector will ROLLBACK the current transaction whenever the server reports an error. If you choose, you can override the automatic ROLLBACK with the edb_stmt_level_tx parameter, which preserves modifications within a transaction, even if one (or several) statements raise an error within the transaction.
You can use the OCIServer attribute with OCIAttrSet() and OCIAttrGet()to enable or disable EDB_ATTR_STMT_LEVEL_TX. By default, edb_stmt_level_tx is disabled. To enable edb_stmt_level_tx, the client application must call OCIAttrSet():
To disable edb_stmt_level_tx:
2.6.6.1 xaoSvcCtx
In order to use the xaoSvcCtx function, extensions in the xaoSvcCtx or xa_open connection string format must be provided as follows:
Oracle_XA{+required_fields ...}
Where required_fields are the following:
HostName=host_ip_address specifies the IP address of the Advanced Server database.
PortNumber=host_port_number specifies the port number on which Advanced Server is running.
SqlNet=dbname specifies the database name.
Acc=P/username/password specifies the database username and password. password may be omitted in which case the field is specified as Acc=P/username/.
AppName=app_id specifies a number that identifies the application.
Convert an array of size OCI_DT_ARRAYLEN to an OCIDateTime descriptor.
Convert the given string to Oracle datetime type in the OCIDateTime descriptor according to the specified format.
Convert an OCIDateTime descriptor to an array.
Implements division of OCIInterval values by OCINumber values.
Implements multiplication of OCIInterval values by OCINumber values.
Converts an OCIInterval value into a OCINumber value.
Converts a OCINumber value into an OCIInterval value.
Adds an OCIInterval value to an OCIDatetime value, resulting in an OCIDatetime value.
Subtracts an OCIInterval value from an OCIDatetime value, resulting in an OCIDatetime value.
Adds NUMBERs.
Assign one NUMBER to another.
Compare NUMBERs.
Divide two NUMBERs.
Test if a NUMBER is an integer.
Test if a NUMBER is zero.
Multiply NUMBERs.
Negate a NUMBER
Round a NUMBER to a specified number of decimal places.
Round a NUMBER to a specified decimal place.
Initialize a NUMBER to Pi.
Initialize a NUMBER to zero.
Subtract NUMBERs.
Convert a NUMBER to an integer.
Convert a NUMBER to a real.
Convert an array of NUMBER to a real array.
Converts a NUMBER to a string.
Truncate a NUMBER at a specified decimal place.
Initialize the OCIFile package.
Terminate the OCIFile package.
Write buflen bytes into the file.

2 Open Client Library : 2.6 OCI Function Reference

Table of Contents Previous Next