OCL function reference v15.2.0.1

The following tables list the functions supported by the EDB OCL connector. Any and all header files must be supplied by the user. EDB Postgres Advanced Server doesn't supply any such files.

Connect, authorize, and initialize functions

Using the tnsnames.ora file

The OCIServerAttach and OCILogon methods use NET_SERVICE_NAME as 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 details. OCL searches your home directory for a file named .tnsnames.ora. If OCL doesn't find the .tnsnames.ora file in the home directory, it searches for tnsnames.ora on the path specified in TNS_ADMIN environment variable.

You can specify multiple descriptors (NET_SERVICE_NAME) in the tnsnames.ora file.

The sample tnsnames.ora file contains:

EDBX =
(DESCRIPTION =
 (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 5444))
 (CONNECT_DATA = (SERVER = DEDICATED)(SID = edb))
)

Any parameters not included in the files are ignored by the Open Client Library. In the example, SID refers to the database named edb in the cluster running on localhost on port 5444.

A C program call to OCIServerAttach that uses the tnsnames.ora file looks like:

static text* username = (text*)"enterprisedb";
static text* password = (text*)"edb";
static text* attach_str = "EDBX";
OCIServerAttach(srvhp,
                errhp,
                attach_str,
                strlen(attach_str),
                0);

If you don't have a tnsnames.ora file, supply the connection string in the form //localhost:5444/edbx.

Handle and descriptor functions

EDB_ATTR_EMPTY_STRINGS

By default, EDB Postgres Advanced Server treats an empty string as a NULL value. You can use the EDB_ATTR_EMPTY_STRINGS environment attribute to control the behavior of the OCL 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().

EDB_ATTR_HOLDABLE

EDB Postgres Advanced Server supports statements that execute as WITH HOLD cursors. The EDB_ATTR_HOLDABLE attribute specifies the statements that execute as WITH HOLD cursors. You can set the EDB_ATTR_HOLDABLE attribute to any of the following 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 EDB Postgres 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, EDB Postgres 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).

EDB_HOLD_CURSOR_ACTION

The EDB_HOLD_CURSOR_ACTION attribute alters the way WITH HOLD cursors are created using the OCL 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 — Don't begin a new transaction chain.
• OCI_DEFAULT — See the definition that follows.

The following describes the attribute values.

OCI_DEFAULT

Each time you execute a statement, the OCL examines the transaction state on the database server. If a transaction isn't already in progress, the OCL 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 roll back. If you (or the OCL) declare a cursor that includes the WITH HOLD clause, the cursor result set is persisted on the database server, and you can continue to fetch from that cursor. However, the database server doesn't persist open cursors when you roll back a transaction. If you try to fetch from a cursor after a ROLLBACK, the database server reports an error.

EDB_COMMIT_AFTER_CURSOR

If your application must read from a WITH HOLD cursor after rolling back a transaction, you can arrange for the OCL 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:

ub4 action = EDB_COMMIT_AFTER_CURSOR;

OCIAttrSet(stmt,
           OCI_HTYPE_STMT,
           &action,
           sizeof(action),
           EDB_ATTR_HOLD_CURSOR_ACTION,
           err);

OCIStmtExecute(...);

OCIServer* server = myServer;
ub1 enabled = 1;

OCIAttrSet(server,
           OCI_HTYPE_SERVER,
           &enabled,
           sizeof(enabled),
           EDB_ATTR_STMT_LEVEL_TX,
           err);

OCIServer* server = myServer;
ub1 enabled = 0;

OCIAttrSet(server,
           OCI_HTYPE_SERVER,
           &enabled,
           sizeof(enabled),
           EDB_ATTR_STMT_LEVEL_TX,
           err);

Oracle_XA+HostName=192.168.1.1+PortNumber=1533+SqlNet=XE+Acc=P/user/password+AppName=1234

• On this page
• Connect, authorize, and initialize functions
• Handle and descriptor functions