Skip Headers
Oracle® Call Interface Programmer's Guide,
11g Release 1 (11.1)

Part Number B28395-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

A Handle and Descriptor Attributes

This appendix describes the attributes for OCI handles and descriptors, which can be read with OCIAttrGet(), and modified with OCIAttrSet().

This appendix contains these topics:

Conventions

For each handle type, the attributes which can be read or changed are listed. Each attribute listing includes the following information:

Mode

The following modes are valid:

READ - the attribute can be read using OCIAttrGet()

WRITE - the attribute can be modified using OCIAttrSet()

READ/WRITE - the attribute can be read using OCIAttrGet(), and it can be modified using OCIAttrSet().

Description

This is a description of the purpose of the attribute.

Attribute Datatype

This is the datatype of the attribute. If necessary, a distinction is made between the datatype for READ and WRITE modes.

Valid Values

In some cases, only certain values are allowed, and they are listed here.

Example

In some cases an example is included.

Environment Handle Attributes

OCI_ATTR_ALLOC_DURATION

Mode

READ/WRITE

Description

This attribute sets the value of OCI_DURATION_DEFAULT for allocation durations for the application associated with the environment handle.

Attribute Datatype

OCIDuration */OCIDuration

OCI_ATTR_BIND_DN

Mode

READ/WRITE

Description

The login name (DN) to use when connecting to the LDAP server.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_CACHE_ARRAYFLUSH

Mode

READ/WRITE

Description

When this attribute is set to TRUE, during OCICacheFlush() the objects that belong to the same table are flushed together, which can considerably improve performance. This mode should only be used when the order in which the objects are flushed is not important. During this mode it is not guaranteed that the order in which the objects are marked dirty is preserved.

Attribute Datatype

boolean */boolean

OCI_ATTR_CACHE_MAX_SIZE

Mode

READ/WRITE

Description

Sets the maximum size (high watermark) for the client-side object cache as a percentage of the optimal size. Usually you can set the value at 10%, the default, of the optimal size, OCI_ATTR_CACHE_OPT_SIZE. Setting this attribute to 0 results in a value of 10 being used. The object cache uses the maximum and optimal values for freeing unused memory in the object cache.

Attribute Datatype

ub4 */ub4

OCI_ATTR_CACHE_OPT_SIZE

Mode

READ/WRITE

Description

Sets the optimal size for the client-side object cache in bytes. The default value is 8M bytes. Setting this attribute to 0 results in a value of 8M bytes being used.

Attribute Datatype

ub4 */ub4

OCI_ATTR_ENV_CHARSET_ID

Mode

READ

Description

Local (client-side) character set ID. Users can update this setting only after creating the environment handle but before calling any other OCI functions. This restriction ensures the consistency among data and metadata in the same environment handle. In UTF-16 mode, an attempt to get this attribute is invalid.

Attribute Datatype

ub2 *

OCI_ATTR_ENV_NCHARSET_ID

Mode

READ

Description

Local (client-side) national character set ID. Users can update this setting only after creating the environment handle but before calling any other OCI functions. This restriction ensures the consistency among data and metadata in the same environment handle. In UTF-16 mode, an attempt to get this attribute is invalid.

Attribute Datatype

ub2 *

OCI_ATTR_ENV_UTF16

Mode

READ

Description

Encoding method is UTF-16. The value 1 means that the environment handle is created in UTF-16 mode, while 0 means that it is not. This mode can only be set by the call to OCIEnvCreate() and cannot be changed later.

Attribute Datatype

ub1 *

OCI_ATTR_EVTCBK

Mode

WRITE

Description

This attribute registers an event callback function.

Attribute Datatype

OCIEventCallback

OCI_ATTR_EVTCTX

Mode

WRITE

Description

This attribute registers a context passed to an event callback.

Attribute Datatype

void *

OCI_ATTR_HEAPALLOC

Mode

READ

Description

The current size of the memory allocated from the environment handle. This may help you track where memory is being used most in an application.

Attribute Datatype

ub4 *

OCI_ATTR_LDAP_AUTH

Mode

READ/WRITE

Description

The authentication mode. The following are the valid values:

0x0: No authentication; anonymous bind.

0x1: Simple authentication; user name and password authentication.

0x5: SSL connection with no authentication.

0x6: SSL: only server authentication required.

0x7: SSL: both server authentication and client authentication are required.

0x8: Authentication method will be determined at runtime.

Attribute Datatype

ub2 */ub2

OCI_ATTR_LDAP_CRED

Mode

READ/WRITE

Description

If the authentication method is "simple authentication" (user name and password authentication), then this attribute holds the password to use when connecting to the LDAP server.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_LDAP_CTX

Mode

READ/WRITE

Description

The administrative context of the client. This is usually the root of the Oracle RDBMS LDAP schema in the LDAP server.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_LDAP_HOST

Mode

READ/WRITE

Description

The name of the host on which the LDAP server runs.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_LDAP_PORT

Mode

READ/WRITE

Description

The port on which the LDAP server is listening.

Attribute Datatype

ub2 */ub2

OCI_ATTR_OBJECT

Mode

READ

Description

Returns TRUE if the environment was initialized in object mode.

Attribute Datatype

boolean *

OCI_ATTR_PINOPTION

Mode

READ/WRITE

Description

This attribute sets the value of OCI_PIN_DEFAULT for the application associated with the environment handle.

For example, if OCI_ATTR_PINOPTION is set to OCI_PIN_RECENT, then if OCIObjectPin() is called with the pin_option parameter set to OCI_PIN_DEFAULT, then the object is pinned in OCI_PIN_RECENT mode.

Attribute Datatype

OCIPinOpt */OCIPinOpt

OCI_ATTR_OBJECT_NEWNOTNULL

Mode

READ/WRITE

Description

When this attribute is set to TRUE, newly created objects have non-NULL attributes.

Attribute Datatype

boolean */boolean

OCI_ATTR_OBJECT_DETECTCHANGE

Mode

READ/WRITE

Description

When this attribute is set to TRUE, applications receive an ORA-08179 error when attempting to flush an object which has been modified in the server by another committed transaction.

Attribute Datatype

boolean */boolean

OCI_ATTR_PIN_DURATION

Mode

READ/WRITE

Description

This attribute sets the value of OCI_DURATION_DEFAULT for pin durations for the application associated with the environment handle.

Attribute Datatype

OCIDuration */OCIDuration

OCI_ATTR_SHARED_HEAPALLOC

Mode

READ

Description

Returns the size of the memory currently allocated from the shared pool. This attribute works on any environment handle but the process must be initialized in shared mode to return a meaningful value. This attribute is read as follows:

ub4 heapsz = 0;
OCIAttrGet((void *)envhp, (ub4)OCI_HTYPE_ENV,
           (void *) &heapsz, (ub4 *) 0,
           (ub4)OCI_ATTR_SHARED_HEAPALLOC, errhp);
Attribute Datatype

ub4 *

OCI_ATTR_WALL_LOC

Mode

READ/WRITE

Description

If the authentication method is SSL authentication, this attribute contains the location of the client wallet.

Attribute Datatype

oratext **/oratext *

Error Handle Attributes

OCI_ATTR_DML_ROW_OFFSET

Mode

READ

Description

Returns the offset (into the DML array) at which the error occurred.

Attribute Datatype

ub4 *

Service Context Handle Attributes

OCI_ATTR_ENV

Mode

READ

Description

This attribute returns the environment context associated with the service context.

Attribute Datatype

OCIEnv **

OCI_ATTR_IN_V8_MODE

Mode

READ

Description

Allows you to determine whether an application has switched to Oracle release 7 mode (for example, through an OCISvcCtxToLda() call). A nonzero (TRUE) return value indicates that the application is currently running in Oracle release 8 mode, a zero (false) return value indicates that the application is currently running in Oracle release 7 mode.

Attribute Datatype

ub1 *

Example

The following code sample shows how this attribute is used:

in_v8_mode = 0; 
OCIAttrGet ((void *)svchp, (ub4)OCI_HTYPE_SVCCTX, (ub1 *)&in_v8_mode,  
                    (ub4) 0, OCI_ATTR_IN_V8_MODE, errhp); 
if (in_v8_mode) 
     fprintf (stdout, "In V8 mode\n"); 
else 
     fprintf (stdout, "In V7 mode\n");

OCI_ATTR_SERVER

Mode

READ/WRITE

Description

When read, returns the pointer to the server context attribute of the service context.

When changed, sets the server context attribute of the service context.

Attribute Datatype

OCIServer ** / OCIServer *

OCI_ATTR_SESSION

Mode

READ/WRITE

Description

When read, returns the pointer to the authentication context attribute of the service context.

When changed, sets the authentication context attribute of the service context.

Attribute Datatype

OCISession **/ OCISession *

OCI_ATTR_STMTCACHESIZE

Mode

READ/WRITE

Description

The default value of the statement cache size is 20 statements, for a statement cache enabled session. The user can increase or decrease this value, by setting this attribute on the service context handle. This attribute can also be used to enable or disable statement caching for the session, pooled or non-pooled. Statement caching can be enabled by setting the attribute to a nonzero size and disabled by setting it to zero.

Attribute Datatype

ub4 */ ub4

OCI_ATTR_TRANS

Mode

READ/WRITE

Description

When read, returns the pointer to the transaction context attribute of the service context.

When changed, sets the transaction context attribute of the service context.

Attribute Datatype

OCITrans ** / OCITrans *

Server Handle Attributes

OCI_ATTR_ACCESS_BANNER

Mode

READ

Description

Display an unauthorized access banner from a file.

Attribute Datatype

oratext **

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the server context.

Attribute Datatype

OCIEnv **

OCI_ATTR_EXTERNAL_NAME

Mode

READ/WRITE

Description

The external name is the user-friendly global name stored in sys.props$.value$, where name = 'GLOBAL_DB_NAME'. It is not guaranteed to be unique unless all databases register their names with a network directory service.

Database names can be exchanged with the server in case of distributed transaction coordination. Server database names can only be accessed if the database is open at the time the OCISessionBegin() call is issued.

Attribute Datatype

oratext **/ oratext *

OCI_ATTR_FOCBK

Mode

READ/WRITE

Description
Attribute Datatype

OCIFocbkStruct *

OCI_ATTR_INTERNAL_NAME

Mode

READ/WRITE

Description

Sets the client database name that will be recorded when performing global transactions. The name can be used by the DBA to track transactions that may be pending in a prepared state due to failures.

Attribute Datatype

oratext ** / oratext *

OCI_ATTR_IN_V8_MODE

Mode

READ

Description

Allows you to determine whether an application has switched to Oracle release 7 mode (for example, through an OCISvcCtxToLda() call). A nonzero (TRUE) return value indicates that the application is currently running in Oracle release 8 mode, a zero (FALSE) return value indicates that the application is currently running in Oracle release 7 mode.

Attribute Datatype

ub1 *

OCI_ATTR_NONBLOCKING_MODE

Mode

READ/WRITE

Description

This attribute determines the blocking mode. When read, the attribute value returns TRUE if the server context is in nonblocking mode. When set, it toggles the nonblocking mode attribute. You must set this attribute only after OCISessionBegin() or OCILogon2() has been called. Otherwise, an error will be returned.

Attribute Datatype

ub1 */ub1

OCI_ATTR_SERVER_GROUP

Mode

READ/WRITE

Description

An alpha-numeric string not exceeding 30 characters specifying the server group. This attribute can only be set after calling OCIServerAttach().

Attribute Datatype

oratext **/oratext *

OCI_ATTR_SERVER_STATUS

Mode

READ

Description

Returns the current status of the server handle. Values are:

Attribute Datatype

ub4 *

Example

The following code sample shows how this parameter is used:

ub4 serverStatus = 0
OCIAttrGet((void *)srvhp, OCI_HTYPE_SERVER,
        (void *)&serverStatus, (ub4 *)0, OCI_ATTR_SERVER_STATUS, errhp);
if (serverStatus == OCI_SERVER_NORMAL)
        printf("Connection is up.\n");
else if (serverStatus == OCI_SERVER_NOT_CONNECTED)
        printf("Connection is down.\n");

OCI_ATTR_TAF_ENABLED

Mode

READ

Description

Set to TRUE if the server handle is TAF-enabled and FALSE if not.

Attribute Datatype

boolean *

OCI_ATTR_USER_MEMORY

Mode

READ

Description

If the handle was allocated with extra memory, this attribute will return a pointer to the user memory. A NULL pointer will be returned for those handles not allocated with extra memory.

Attribute Datatype

void *

Authentication Information Handle

These attributes also apply to the user session handle.

User Session Handle Attributes

These attributes also apply to the authentication information handle.

OCI_ATTR_ACTION

Mode

WRITE

Description

The name of the current action within the current module. Can be set to NULL. When the current action terminates, set this attribute again with the name of the next action or NULL, if there is no next action. Can be up to 32 bytes long.

Attribute Datatype

oratext *

Example
OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"insert into employees",
           (ub4)strlen("insert into employees"), OCI_ATTR_ACTION, error_handle);

OCI_ATTR_APPCTX_ATTR

Note:

This attribute is not supported with database resident connection pooling.
Mode

WRITE

Description

Specifies an attribute name of the externally initialized context.

Attribute Datatype

oratext *

OCI_ATTR_APPCTX_LIST

Note:

This attribute is not supported with database resident connection pooling.
Mode

READ

Description

Gets the application context list descriptor for the session.

Attribute Datatype

OCIParam **

OCI_ATTR_APPCTX_NAME

Note:

This attribute is not supported with database resident connection pooling.
Mode

WRITE

Description

Specifies the namespace of the externally initialized context.

Attribute Datatype

oratext *

OCI_ATTR_APPCTX_SIZE

Note:

This attribute is not supported with database resident connection pooling.
Mode

WRITE

Description

Initializes the externally initialized context array size with the number of attributes.

Attribute Datatype

ub4

OCI_ATTR_APPCTX_VALUE

Note:

This attribute is not supported with database resident connection pooling.
Mode

WRITE

Description

Specifies a value of the externally initialized context.

Attribute Datatype

oratext *

OCI_ATTR_AUDIT_BANNER

Mode

READ

Description

Display a user actions auditing banner from a file.

Attribute Datatype

oratext **

OCI_ATTR_CALL_TIME

Mode

READ

Description

Returns the server-side time for the preceding call in microseconds.

Attribute Datatype

ub8 *

OCI_ATTR_CERTIFICATE

Mode

WRITE

Description

Specifies the certificate of the client for use in proxy authentication. Certificate-based proxy authentication using OCI_ATTR_CERTIFICATE will not be supported in future Oracle Database releases. Use OCI_ATTR_DISTINGUISHED_NAME or OCI_ATTR_USERNAME attribute instead.

Attribute Datatype

ub1 *

OCI_ATTR_CLIENT_IDENTIFIER

Mode

WRITE

Description

Specifies the user identifier in the session handle. Can be up to 64 bytes long. It can contain the user name, but you are asked not to include the password for security reasons. The first character of the identifier should not be ':'. If it is, the behavior is unspecified.

Attribute Datatype

oratext *

Example
OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"janedoe",
            (ub4)strlen("janedoe"), OCI_ATTR_CLIENT_IDENTIFIER,
            error_handle);

OCI_ATTR_CLIENT_INFO

Mode

WRITE

Description

Client application additional information. Can also be set by the DBMS_APPLICATION_INFO package. It is stored in the V$SESSION view. Up to 64 bytes long.

Attribute Datatype

oratext *

OCI_ATTR_COLLECT_CALL_TIME

Mode

READ/WRITE

Description

When set to TRUE, causes the server to measure call time, in milliseconds, for each subsequent OCI call.

Attribute Datatype

boolean */boolean

OCI_ATTR_CONNECTION_CLASS

Mode

READ/WRITE

Description

This attribute of OCIAuthInfo handle explicitly names the connection class (a string of up to 128 characters) for a database resident connection pool.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_CURRENT_SCHEMA

Mode

READ/WRITE

Description

Calling OCIAttrSet() with this attribute has the same effect as the SQL command ALTER SESSION SET CURRENT_SCHEMA, if the schema name and the session exist. The schema is altered on the next OCI call that does a round trip to the server, avoiding an extra round trip. If the new schema name does not exist, the same error is returned as the error returned from ALTER SESSION SET CURRENT_SCHEMA. The new schema name is placed before database objects in DML or DDL commands you then enter.

When a client using this attribute communicates with a server that has a software release earlier than 10g Release 2, the OCIAttrSet() call will be ignored. This attribute is also readable by OCIAttrGet().

Attribute Datatype

ub4/ub4

Example
text schema[] = "hr";
err = OCIAttrSet( (void ) mysessp, OCI_HTYPE_SESSION, (void *)schema,
      (ub4)strlen( (char *)schema), OCI_ATTR_CURRENT_SCHEMA, (OCIError *)myerrhp);

OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE

Mode

READ/WRITE

Description

Allows the user to enable prefetching for all the lob locators fetched in the session. Specifies the default prefetch buffer size for each LOB locator.

Attribute Datatype

ub4 */ub4

OCI_ATTR_DISTINGUISHED_NAME

Mode

WRITE

Description

Specifies distinguished name of the client for use in proxy authentication.

Attribute Datatype

oratext *

OCI_ATTR_DRIVER_NAME

Mode

READ/WRITE

Description

Specifies the name of the driver layer using OCI. (Such as JDBC, ODBC, PHP, SQL*Plus, and so on. Names starting with "ORA$" are reserved also.) A future application can choose its own name and set it as an aid to fault diagnosability. Set this attribute before executing OCISessionBegin(). Pass an array containing up to 9 single-byte characters, including the null terminator. This data is not validated and is passed directly to the server to be displayed in V$SESSION_CONNECT_INFO or GV$SESSION_CONNECT_INFO. OCI only ensures that the driver name array is not greater than 30 characters. If more than 9 characters are passed, only the first 8 characters are displayed.

Attribute Datatype

oratext **/oratext *

Example
...
oratext client_driver[9];
...
checkerr(errhp, OCIAttrSet(authp, OCI_HTYPE_SESSION,
                client_driver, (ub4)(strlen(client_driver)),
                OCI_ATTR_DRIVER_NAME, errhp));

checkerr(errhp, OCISessionBegin(svchp, errhp, authp, OCI_CRED_RDBMS, OCI_DEFAULT);
... 

OCI_ATTR_INITIAL_CLIENT_ROLES

Mode

WRITE

Description

Specifies the role or roles that the client is to initially possess when the application server connects to Oracle on its behalf.

Attribute Datatype

oratext **

OCI_ATTR_MIGSESSION

Mode

READ/WRITE

Description

Specifies the session identified for the session handle. Allows you to clone a session from one environment to another, in the same process or between processes. These processes can be on the same system or different systems. For a session to be cloned, the session must be authenticated as migratable.

Attribute Datatype

ub1 *

Example

The following code sample shows how this attribute is used:

OCIAttrSet ((void *) authp, (ub4)OCI_HTYPE_SESSION, (void *) mig_session,
            (ub4) sz, (ub4)OCI_ATTR_MIGSESSION, errhp);

OCI_ATTR_MODULE

Mode

WRITE

Description

The name of the current module running in the client application. When the current module terminates, call with the name of the new module, or NULL if there is no new module. Can be up to 48 bytes long.

Attribute Datatype

oratext *

Example
OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"add_employee",
           (ub4)strlen("add_employee"), OCI_ATTR_MODULE, error_handle); 

OCI_ATTR_PASSWORD

Mode

WRITE

Description

Specifies a password to use for authentication.

Attribute Datatype

oratext *

OCI_ATTR_PROXY_CLIENT

Mode

WRITE

Description

Specifies the target user name for access through a proxy.

Attribute Datatype

oratext *

OCI_ATTR_PROXY_CREDENTIALS

Mode

WRITE

Description

Specifies that the credentials of the application server are to be used for proxy authentication.

Attribute Datatype

OCISession

OCI_ATTR_PURITY

Mode

READ/WRITE

Description

An attribute of the OCIAuthInfo handle for database resident connection pooling. Values are OCI_ATTR_PURITY_NEW, the application requires a session not tainted with any prior session state; or OCI_ATTR_PURITY_SELF, the session can have been used before. If the application does not specify the purity when invoking OCISessionGet(), the purity value OCI_ATTR_PURITY_DEFAULT is assumed. This later translates to either OCI_ATTR_PURITY_NEW or OCI_ATTR_PURITY_SELF depending on the type of application.

Attribute Datatype

ub4 */ub4

OCI_ATTR_USERNAME

Mode

READ/WRITE

Description

Specifies a user name to use for authentication.

Attribute Datatype

oratext **/oratext *

Administration Handle Attributes

OCI_ATTR_ADMIN_PFILE

Mode

READ/WRITE

Description

Set this attribute before a call to OCIDBStartup() to specify the location of the client-side parameter file that is used to start up the database. If this attribute is not set then the server-side parameter file is used. If the server-side parameter file does not exist, an error is returned.

Attribute Datatype

oratext */oratext *

Connection Pool Handle Attributes

OCI_ATTR_CONN_TIMEOUT

Note:

Shrinkage of the pool only occurs when there is a network round trip. If there are no operations, then the connections stay alive.
Mode

READ/WRITE

Description

Connections idle for more than this time value (in seconds) are terminated, to maintain an optimum number of open connections. This attribute can be set dynamically. If this attribute is not set, the connections are never timed out.

Attribute Datatype

ub4 */ub4

OCI_ATTR_CONN_NOWAIT

Mode

READ/WRITE

Description

This attribute determines if retrial for a connection has to be done when all connections in the pool are found to be busy and the number of connections has already reached the maximum.

If this attribute is set, an error is thrown when all the connections are busy and no more connections can be opened. Otherwise the call waits till it gets a connection.

When read, the attribute value is returned as TRUE if it has been set.

Attribute Datatype

ub1 */ub1

OCI_ATTR_CONN_BUSY_COUNT

Mode

READ

Description

Returns the number of busy connections.

Attribute Datatype

ub4 *

OCI_ATTR_CONN_OPEN_COUNT

Mode

READ

Description

Returns the number of open connections.

Attribute Datatype

ub4 *

OCI_ATTR_CONN_MIN

Mode

READ

Description

Returns the number of minimum connections.

Attribute Datatype

ub4 *

OCI_ATTR_CONN_MAX

Mode

READ

Description

Returns the number of maximum connections.

Attribute Datatype

ub4 *

OCI_ATTR_CONN_INCR

Mode

READ

Description

Returns the connection increment parameter.

Attribute Datatype

ub4 *

Session Pool Handle Attributes

The attributes used for session pooling are:

OCI_ATTR_SPOOL_BUSY_COUNT

Mode

READ

Description

Returns the number of busy sessions.

Attribute Datatype

ub4 *

OCI_ATTR_SPOOL_GETMODE

Mode

READ/WRITE

Description

This attribute determines the behavior of the session pool when all sessions in the pool are found to be busy and the number of sessions has already reached the maximum. Values are:

Attribute Datatype

ub1 */ ub1

OCI_ATTR_SPOOL_INCR

Mode

READ

Description

Returns the session increment parameter.

Attribute Datatype

ub4 *

OCI_ATTR_SPOOL_MAX

Mode

READ

Description

Returns the number of maximum sessions.

Attribute Datatype

ub4 *

OCI_ATTR_SPOOL_MIN

Mode

READ

Description

Returns the number of minimum sessions.

Attribute Datatype

ub4 *

OCI_ATTR_SPOOL_OPEN_COUNT

Mode

READ

Description

Returns the number of open sessions.

Attribute Datatype

ub4 *

OCI_ATTR_SPOOL_TIMEOUT

Mode

READ/WRITE

Description

The sessions idle for more than this time (in seconds) are terminated periodically, to maintain an optimum number of open sessions. This attribute can be set dynamically. If this attribute is not set, the least recently used sessions may be timed out if and when space in the pool is required. OCI only checks for timed out sessions when it releases one back to the pool.

Attribute Datatype

ub4 */ ub4

OCI_ATTR_SPOOL_STMTCACHESIZE

Mode

READ/WRITE

Description

Sets the default statement cache size for each of the sessions in a session pool, to this value. The statement cache size for a particular session in the pool can, at any time, be overridden by using OCI_ATTR_STMTCACHESIZE on that session.

Attribute Datatype

ub4 */ ub4

Transaction Handle Attributes

OCI_ATTR_TRANS_NAME

Mode

READ/WRITE

Description

Can be used to establish or read a text string which identifies a transaction. This is an alternative to using the XID to identify the transaction. The oratext string can be up to 64 bytes long.

Attribute Datatype

oratext ** (READ) / oratext * (WRITE)

OCI_ATTR_TRANS_TIMEOUT

Mode

READ/WRITE

Description

Can set or read a timeout interval value used at prepare time.

Attribute Datatype

ub4 * (READ) / ub4 (WRITE)

OCI_ATTR_XID

Mode

READ/WRITE

Description

Can set or read an XID which identifies a transaction.

Attribute Datatype

XID ** (READ) / XID * (WRITE)

Statement Handle Attributes

OCI_ATTR_BIND_COUNT

Mode

READ

Description

Returns the number of bind positions on the statement handle.

Attribute Datatype

ub4 *

Example
OCIHandleAlloc(env,(void **) &pStatement, OCI_HTYPE_STMT, (size_t)0, (void **)0);
OCIStmtPrepare (pStatement, err, pszQuery, (ub4)strlen(pszQuery),
                (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT); 
OCIAttrGet(pStatement, OCI_HTYPE_STMT, &iNbParameters, NULL, OCI_ATTR_BIND_COUNT,
           err); 

OCI_ATTR_CHNF_REGHANDLE

Mode

WRITE

Description

When this attribute is set to the appropriate subscription handle, execution of the query will also create the registration of the query for continuous query notification.

Attribute Datatype

OCISubscription *

Example
/* Associate the statement with the subscription handle */
OCIAttrSet (stmthp, OCI_HTYPE_STMT, subscrhp, 0,
            OCI_ATTR_CHNF_REGHANDLE, errhp); 

OCI_ATTR_CQ_QUERYID

Mode

READ

Description

Obtains the query id of a registered query after registration is made by the call to OCIStmtExecute().

Attribute Datatype

ub8 *

OCI_ATTR_CURRENT_POSITION

Mode

READ

Description

Indicates the current position in the result set. This attribute can only be retrieved. It cannot be set.

Attribute Datatype

ub4 *

OCI_ATTR_ENV

Mode

READ

Description

Indicates the current position in the result set. This attribute can only be retrieved. It cannot be set.

Attribute Datatype

ub4 *

OCI_ATTR_FETCH_ROWID

Mode

READ/WRITE

Description

Specifies that the ROWIDs will be fetched after doing a define at position 0, and a SELECT...FOR UPDATE statement.

Attribute Datatype

boolean */boolean

OCI_ATTR_NUM_DML_ERRORS

Mode

READ

Description

Returns the number of errors in the DML operation.

Attribute Datatype

ub4 *

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

This attribute can be used to get the number of columns in the select-list for the statement associated with the statement handle.

Attribute Datatype

ub4 *

Example
...
int i = 0;
ub4 parmcnt = 0;
ub2 type = 0;
OCIParam *colhd = (OCIParam *) 0;   /* column handle */

/* Describe of a select-list */ 
OraText *sqlstmt = (OraText *)"SELECT * FROM employees WHERE employee_id = 100";

checkerr(errhp, OCIStmtPrepare(stmthp, errhp, (OraText *)sqlstmt,
                    (ub4)strlen((char *)sqlstmt),
                    (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));

checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, 1, 0,
        (OCISnapshot *)0, (OCISnapshot *)0, OCI_DESCRIBE_ONLY));

/* Get the number of columns in the select list */
checkerr(errhp, OCIAttrGet((void *)stmthp, OCI_HTYPE_STMT, (void *)&parmcnt,
                      (ub4 *)0, OCI_ATTR_PARAM_COUNT, errhp));

/* go through the column list and retrieve the datatype of each column. We
   start from pos = 1 */
for (i = 1; i <= parmcnt; i++)
{
  /* get parameter for column i */
  checkerr(errhp, OCIParamGet((void *)stmthp, OCI_HTYPE_STMT, errhp, 
           (void **)&colhd, i));

  /* get data-type of column i */
  type = 0;
  checkerr(errhp, OCIAttrGet((void *)colhd, OCI_DTYPE_PARAM,
          (void *)&type, (ub4 *)0, OCI_ATTR_DATA_TYPE, errhp));

}
...

OCI_ATTR_PARSE_ERROR_OFFSET

Mode

READ

Description

Returns the parse error offset for a statement.

Attribute Datatype

ub2 *

OCI_ATTR_PREFETCH_MEMORY

Mode

WRITE

Description

Sets the memory level for top level rows to be prefetched. Rows up to the specified top level row count are fetched if it occupies no more than the specified memory usage limit. The default value is 0, which means that memory size is not included in computing the number of rows to prefetch.

Attribute Datatype

ub4 *

OCI_ATTR_PREFETCH_ROWS

Mode

WRITE

Description

Sets the number of top level rows to be prefetched. The default value is 1 row.

Attribute Datatype

ub4 *

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Returns the number of rows processed so far after SELECT statements. For INSERT, UPDATE, and DELETE statements, it is the number of rows processed by the most recent statement. The default value is 1.

For non-scrollable cursors, OCI_ATTR_ROW_COUNT is the total number of rows fetched into user buffers with the OCIStmtFetch2() calls issued since this statement handle was executed. Since they are forward sequential only, this also represents the highest row number seen by the application.

For scrollable cursors, OCI_ATTR_ROW_COUNT will represent the maximum (absolute) row number fetched into the user buffers. Since the application can arbitrarily position the fetches, this need not be the total number of rows fetched into the user's buffers since the (scrollable) statement was executed.

Attribute Datatype

ub4 *

OCI_ATTR_ROWID

Mode

READ

Description

Returns the ROWID descriptor allocated with OCIDescriptorAlloc().

Attribute Datatype

OCIRowid *

OCI_ATTR_ROWS_FETCHED

Mode

READ

Description

Indicates the number of rows that were successfully fetched into the user's buffers in the last fetch or execute with nonzero iterations. It can be used for both scrollable and non-scrollable statement handles.

Attribute Datatype

ub4 *

Example
ub4 rows;
ub4 sizep = sizeof(ub4);
OCIAttrGet((void *) stmhp, (ub4) OCI_HTYPE_STMT,
           (void *)& rows, (ub4 *) &sizep, (ub4)OCI_ATTR_ROWS_FETCHED,
           errhp);

OCI_ATTR_SQLFNCODE

Mode

READ

Description

Returns the function code of the SQL command associated with the statement.

Attribute Datatype

ub2 *

Notes

See Also:

The SQL command codes are listed in Table A-1.

Table A-1 SQL Command Codes

Code SQL Function Code SQL Function Code SQL Function

01

CREATE TABLE

43

DROP EXTERNAL DATABASE

85

TRUNCATE TABLE

02

SET ROLE

44

CREATE DATABASE

86

TRUNCATE CLUSTER

03

INSERT

45

ALTER DATABASE

87

CREATE BITMAPFILE

04

SELECT

46

CREATE ROLLBACK SEGMENT

88

ALTER VIEW

05

UPDATE

47

ALTER ROLLBACK SEGMENT

89

DROP BITMAPFILE

06

DROP ROLE

48

DROP ROLLBACK SEGMENT

90

SET CONSTRAINTS

07

DROP VIEW

49

CREATE TABLESPACE

91

CREATE FUNCTION

08

DROP TABLE

50

ALTER TABLESPACE

92

ALTER FUNCTION

09

DELETE

51

DROP TABLESPACE

93

DROP FUNCTION

10

CREATE VIEW

52

ALTER SESSION

94

CREATE PACKAGE

11

DROP USER

53

ALTER USER

95

ALTER PACKAGE

12

CREATE ROLE

54

COMMIT (WORK)

96

DROP PACKAGE

13

CREATE SEQUENCE

55

ROLLBACK

97

CREATE PACKAGE BODY

14

ALTER SEQUENCE

56

SAVEPOINT

98

ALTER PACKAGE BODY

15

(NOT USED)

57

CREATE CONTROL FILE

99

DROP PACKAGE BODY

16

DROP SEQUENCE

58

ALTER TRACING

157

CREATE DIRECTORY

17

CREATE SCHEMA

59

CREATE TRIGGER

158

DROP DIRECTORY

18

CREATE CLUSTER

60

ALTER TRIGGER

159

CREATE LIBRARY

19

CREATE USER

61

DROP TRIGGER

160

CREATE JAVA

20

CREATE INDEX

62

ANALYZE TABLE

161

ALTER JAVA

21

DROP INDEX

63

ANALYZE INDEX

162

DROP JAVA

22

DROP CLUSTER

64

ANALYZE CLUSTER

163

CREATE OPERATOR

23

VALIDATE INDEX

65

CREATE PROFILE

164

CREATE INDEXTYPE

24

CREATE PROCEDURE

66

DROP PROFILE

165

DROP INDEXTYPE

25

ALTER PROCEDURE

67

ALTER PROFILE

166

ALTER INDEXTYPE

26

ALTER TABLE

68

DROP PROCEDURE

167

DROP OPERATOR

27

EXPLAIN

69

(NOT USED)

168

ASSOCIATE STATISTICS

28

GRANT

70

ALTER RESOURCE COST

169

DISASSOCIATE STATISTICS

29

REVOKE

71

CREATE SNAPSHOT LOG

170

CALL METHOD

30

CREATE SYNONYM

72

ALTER SNAPSHOT LOG

171

CREATE SUMMARY

31

DROP SYNONYM

73

DROP SNAPSHOT LOG

172

ALTER SUMMARY

32

ALTER SYSTEM SWITCH LOG

74

CREATE SNAPSHOT

173

DROP SUMMARY

33

SET TRANSACTION

75

ALTER SNAPSHOT

174

CREATE DIMENSION

34

PL/SQL EXECUTE

76

DROP SNAPSHOT

175

ALTER DIMENSION

35

LOCK

77

CREATE TYPE

176

DROP DIMENSION

36

NOOP

78

DROP TYPE

177

CREATE CONTEXT

37

RENAME

79

ALTER ROLE

178

DROP CONTEXT

38

COMMENT

80

ALTER TYPE

179

ALTER OUTLINE

39

AUDIT

81

CREATE TYPE BODY

180

CREATE OUTLINE

40

NO AUDIT

82

ALTER TYPE BODY

181

DROP OUTLINE

41

ALTER INDEX

83

DROP TYPE BODY

182

UPDATE INDEXES

42

CREATE EXTERNAL DATABASE

84

DROP LIBRARY

183

ALTER OPERATOR


OCI_ATTR_STATEMENT

Mode

READ

Description

Returns the text of the SQL statement prepared in a statement handle. In UTF-16 mode, the returned statement is in UTF-16 encoding. The length is always in bytes.

Attribute Datatype

oratext *

OCI_ATTR_STMT_STATE

Mode

READ

Description

Returns the fetch state of that statement. This attribute can be used by the caller to determine if the session can be used in another service context or if it is still needed in the current set of data access calls. Basically, if we are in the middle of a fetch-execute cycle, then we do not want to release the session handle for another statement execution. Valid values are:

Attribute Datatype

ub4 *

OCI_ATTR_STMT_TYPE

Mode

READ

Description

The type of statement associated with the handle. Valid values are:

Attribute Datatype

ub2 *

Bind Handle Attributes

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description
Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

Character set form of the bind handle. The default form is SQLCS_IMPLICIT. Setting this attribute will cause the bind handle to use the database or national character set on the client side. Set this attribute to SQLCS_NCHAR for the national character set or SQLCS_IMPLICIT for the database character set.

Attribute Datatype

ub1 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

Character set ID of the bind handle. If the character set of the input data is UTF-16 (replaces the deprecated OCI_UC2SID, which is retained for backward compatibility), the user has to set the character set ID to OCI_UTF16ID. The bind value buffer is assumed to be a utext buffer and length semantics for input length pointers and return values changes to character semantics (number of utexts). However the size of the bind value buffer in the preceding OCIBind call has to be stated in bytes.

If OCI_ATTR_CHARSET_FORM is set, then OCI_ATTR_CHARSET_ID should be set only afterward. Setting OCI_ATTR_CHARSET_ID prior to setting OCI_ATTR_CHARSET_FORM will cause unexpected results.

Attribute Datatype

ub2 *

OCI_ATTR_MAXCHAR_SIZE

Mode

WRITE

Description

Sets the number of characters that an application reserves on the server to store the data being bound.

Attribute Datatype

sb4 *

OCI_ATTR_MAXDATA_SIZE

Mode

READ/WRITE

Description
Attribute Datatype

sb4 *

OCI_ATTR_PDPRC

Mode

WRITE

Description

Specifies packed decimal precision. For SQLT_PDN values, the precision should be equal to 2*(value_sz-1). For SQLT_SLS values, the precision should be equal to (value_sz-1).

After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these values needs to be changed, a rebind/redefine should be done first, and then the two attributes should be reset in order.

Attribute Datatype

ub2 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Specifies the scale for packed decimal values.

After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these values needs to be changed, a rebind/redefine should be done first, and then the two attributes should be reset in order.

Attribute Datatype

sb2 *

OCI_ATTR_ROWS_RETURNED

Mode

READ

Description

This attribute returns the number of rows that are going to be returned in the current iteration when we are in the OUT callback function for binding a DML statement with RETURNING clause.

Attribute Datatype

ub4 *

Define Handle Attributes

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

This attribute is deprecated.

Sets the number of characters in a character type data. This specifies the number of characters desired in the define buffer. The define buffer length as specified in the define call must be greater than number of characters.

Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

The character set form of the define handle. The default form is SQLCS_IMPLICIT. Setting this attribute will cause the define handle to use the database or national character set on the client side. Set this attribute to SQLCS_NCHAR for the national character set or SQLCS_IMPLICIT for the database character set.

Attribute Datatype

ub1 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

The character set ID of the define handle. If the character set of the output data should be UTF-16, the user has to set the character set IDOTT to OCI_UTF16ID. The define value buffer is assumed to be a utext buffer and length semantics for indicators and return values changes to character semantics (number of utexts). However the size of the define value buffer in the preceding OCIDefine call has to be stated in bytes.

If OCI_ATTR_CHARSET_FORM is set, then OCI_ATTR_CHARSET_ID should be set only afterward. Setting OCI_ATTR_CHARSET_ID prior to setting OCI_ATTR_CHARSET_FORM will cause unexpected results.

Attribute Datatype

ub2 *

OCI_ATTR_LOBPREFETCH_LENGTH

Mode

READ/WRITE

Description

Specifies the prefetch length and chunk size for the LOB locators to be fetched from a particular column.

Attribute Datatype

boolean */boolean

OCI_ATTR_LOBPREFETCH_SIZE

Mode

READ/WRITE

Description

Overrides the default cache buffer size for the LOB locators to be fetched from a particular column.

Attribute Datatype

ub4 */ub4

OCI_ATTR_MAXCHAR_SIZE

Mode

WRITE

Description

Specifies the maximum number of characters the client application allows in the define buffer.

Attribute Datatype

sb4 *

OCI_ATTR_PDPRC

Mode

WRITE

Description

Specifies packed decimal precision. For SQLT_PDN values, the precision should be equal to 2*(value_sz-1). For SQLT_SLS values, the precision should be equal to (value_sz-1).

After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these values needs to be changed, a rebind/redefine should be done first, and then the two attributes should be reset in order.

Attribute Datatype

ub2 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Specifies the scale for packed decimal values.

After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these values needs to be changed, a rebind/redefine should be done first, and then the two attributes should be reset in order.

Attribute Datatype

sb2 *

Describe Handle Attributes

OCI_ATTR_PARAM

Mode

READ

Description

Points to the root of the description. Used for subsequent calls to OCIAttrGet() and OCIParamGet().

Attribute Datatype

ub4 *

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

Returns the number of parameters in the describe handle. When the describe handle is a description of the select list, this refers to the number of columns in the select list.

Attribute Datatype

ub4 *

Parameter Descriptor Attributes

See Also:

For a detailed list of parameter descriptor attributes, refer to Chapter 6, "Describing Schema Metadata"

LOB Locator Attributes

OCI_ATTR_LOBEMPTY

Mode

WRITE

Description

Sets the internal LOB locator to empty. The locator can then be used as a bind variable for an INSERT or UPDATE statement to initialize the LOB to empty. Once the LOB is empty, OCILobWrite() can be called to populate the LOB with data. This attribute is only valid for internal LOBs (that is, BLOB, CLOB, NCLOB).

Applications should pass address of a ub4 which has a value of 0; for example, declare:

ub4 lobEmpty = 0

then pass the address: &lobEmpty.

Attribute Datatype

ub4 *

Complex Object Attributes

Complex Object Retrieval Handle Attributes

OCI_ATTR_COMPLEXOBJECT_LEVEL

Mode

WRITE

Description

The depth level for complex object retrieval.

Attribute Datatype

ub4 *

OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE

Mode

WRITE

Description

Whether to fetch collection attributes in an object type out-of-line.

Attribute Datatype

ub1 *

Complex Object Retrieval Descriptor Attributes

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE

Mode

WRITE

Description

A type of REF to follow for complex object retrieval.

Attribute Datatype

void *

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL

Mode

WRITE

Description

Depth level for following REFs of type OCI_ATTR_COMPLEXOBJECTCOMP_TYPE.

Attribute Datatype

ub4 *

Streams Advanced Queuing Descriptor Attributes

OCIAQEnqOptions Descriptor Attributes

The following attributes are properties of the OCIAQEnqOptions descriptor:

OCI_ATTR_MSG_DELIVERY_MODE

Mode

WRITE

Description

The enqueue call can enqueue a persistent or a buffered message into a queue, by setting the OCI_MSG_DELIVERY_MODE attribute in the OCIAQEnqOptions descriptor to OCI_MSG_PERSISTENT or OCI_MSG_BUFFERED, respectively. The default value for this attribute is OCI_MSG_PERSISTENT.

Attribute Datatype

ub2

OCI_ATTR_RELATIVE_MSGID

Mode

READ/WRITE

Description

This feature is deprecated and may be removed in a future release.

Specifies the message identifier of the message which is referenced in the sequence deviation operation. This value is valid if and only if OCI_ENQ_BEFORE is specified in OCI_ATTR_SEQUENCE_DIVISION. This value is ignored if the sequence deviation is not specified.

Attribute Datatype

OCIRaw *

OCI_ATTR_SEQUENCE_DEVIATION

Mode

READ/WRITE

Description

This feature is deprecated for new applications, but it is retained for compatibility.

Specifies whether the message being enqueued should be dequeued before other message(s) already in the queue.

Attribute Datatype

ub4

Valid Values

The only valid values are:

  • OCI_ENQ_BEFORE - the message is enqueued ahead of the message specified by OCI_ATTR_RELATIVE_MSGID.

  • OCI_ENQ_TOP - the message is enqueued ahead of any other messages.

OCI_ATTR_VISIBILITY

Mode

READ/WRITE

Description

Specifies the transactional behavior of the enqueue request.

Attribute Datatype

ub4

Valid Values

The only valid values are:

  • OCI_ENQ_ON_COMMIT - the enqueue is part of the current transaction. The operation is complete when the transaction commits. This is the default case.

  • OCI_ENQ_IMMEDIATE - the enqueue is not part of the current transaction. The operation constitutes a transaction of its own.

OCIAQDeqOptions Descriptor Attributes

The following attributes are properties of the OCIAQDeqOptions descriptor:

OCI_ATTR_CONSUMER_NAME

Mode

READ/WRITE

Description

Name of the consumer. Only those messages matching the consumer name are accessed. If a queue is not set up for multiple consumers, this field should be set to null.

Attribute Datatype

oratext *

OCI_ATTR_CORRELATION

Mode

READ/WRITE

Description

Specifies the correlation identifier of the message to be dequeued. Special pattern matching characters, such as the percent sign (%) and the underscore (_) can be used. If more than one message satisfies the pattern, the order of dequeuing is undetermined.

Attribute Datatype

oratext *

OCI_ATTR_DEQ_MODE

Mode

READ/WRITE

Description

Specifies the locking behavior associated with the dequeue.

Attribute Datatype

ub4

Valid Values

The only valid values are:

  • OCI_DEQ_BROWSE - read the message without acquiring any lock on the message. This is equivalent to a SELECT statement.

  • OCI_DEQ_LOCKED - read and obtain a write lock on the message. The lock lasts for the duration of the transaction. This is equivalent to a SELECT FOR UPDATE statement.

  • OCI_DEQ_REMOVE - read the message and update or delete it. This is the default. The message can be retained in the queue table based on the retention properties.

  • OCI_DEQ_REMOVE_NODATA - confirm receipt of the message, but do not deliver the actual message content.

OCI_ATTR_DEQ_MSGID

Mode

READ/WRITE

Description

Specifies the message identifier of the message to be dequeued.

Attribute Datatype

OCIRaw *

OCI_ATTR_MSG_DELIVERY_MODE

Mode

WRITE

Description

You can specify the dequeue call to dequeue persistent, buffered, or both kinds of messages from a queue, by setting the OCI_MSG_DELIVERY_MODE attribute in the OCIAQDeqOptions descriptor to OCI_MSG_PERSISTENT, OCI_MSG_BUFFERED, or OCI_MSG_PERSISTENT_OR_BUFFERED, respectively. The default value for this attribute is OCI_MSG_PERSISTENT.

Attribute Datatype

ub2

OCI_ATTR_NAVIGATION

Mode

READ/WRITE

Description

Specifies the position of the message that will be retrieved. First, the position is determined. Second, the search criterion is applied. Finally, the message is retrieved.

Attribute Datatype

ub4

Valid Values

The only valid values are:

  • OCI_DEQ_FIRST_MSG - retrieves the first message which is available and matches the search criteria. This will reset the position to the beginning of the queue.

  • OCI_DEQ_NEXT_MSG - retrieves the next message which is available and matches the search criteria. If the previous message belongs to a message group, AQ will retrieve the next available message which matches the search criteria and belongs to the message group. This is the default.

  • OCI_DEQ_NEXT_TRANSACTION - skips the remainder of the current transaction group (if any) and retrieves the first message of the next transaction group. This option can only be used if message grouping is enabled for the current queue.

  • OCI_DEQ_FIRST_MSG_ONE_GROUP - indicates that a call to OCIAQDeqArray() will reset the position to the beginning of the queue and dequeue messages from a single transaction group that are available and match the search criteria. If the number of messages in the single transaction group exceeds iters, then you must make a subsequent call to OCIAQDeqArray() using the OCI_DEQ_NEXT_MSG_ONE_GROUP navigation.

  • OCI_DEQ_NEXT_MSG_ONE_GROUP - indicates that a call to OCIAQDeqArray() will dequeue the next set of messages (up to iters) that are available, match the search criteria and belong to the message group.

  • OCI_DEQ_FIRST_MSG_MULTI_GROUP - indicates that a call to OCIAQDeqArray() will reset the position to the beginning of the queue and dequeue messages (possibly across different transaction groups) that are available and match the search criteria, until reaching the iters limit. To distinguish between transaction groups, a new message property, OCI_ATTR_TRANSACTION_NO, will be defined. All messages belonging to the same transaction group will have the same value for this message property.

  • OCI_DEQ_NEXT_MSG_MULTI_GROUP - indicates that a call to OCIAQDeqArray() will dequeue the next set of messages (possibly across different transaction groups) that are available and match the search criteria, until reaching the iters limit. To distinguish between transaction groups, a new message property, OCI_ATTR_TRANSACTION_NO, will be defined. All messages belonging to the same transaction group will have the same value for this message property.

OCI_ATTR_VISIBILITY

Mode

READ/WRITE

Description

Specifies whether the new message is dequeued as part of the current transaction.The visibility parameter is ignored when using the BROWSE mode.

Attribute Datatype

ub4

Valid Values

The only valid values are:

  • OCI_DEQ_ON_COMMIT - the dequeue will be part of the current transaction. This is the default case.

  • OCI_DEQ_IMMEDIATE - the dequeued message is not part of the current transaction. It constitutes a transaction on its own.

OCI_ATTR_WAIT

Mode

READ/WRITE

Description

Specifies the wait time if there is currently no message available which matches the search criteria. This parameter is ignored if messages in the same group are being dequeued.

Attribute Datatype

ub4

Valid Values

Any ub4 value is valid, but the following predefined constants are provided:

  • OCI_DEQ_WAIT_FOREVER - wait forever. This is the default.

  • OCI_DEQ_NO_WAIT - do not wait.

Note:

If the OCI_DEQ_NO_WAIT option is used to poll a queue, then messages are not dequeued after polling an empty queue. Use the OCI_DEQ_FIRST_MSG option instead of the default OCI_DEQ_NEXT_MSG setting of OCI_ATTR_NAVIGATION. You can also use a nonzero wait setting (1 is suggested) of OCI_ATTR_WAIT for the dequeue.

OCIAQMsgProperties Descriptor Attributes

The following attributes are properties of the OCIAQMsgProperties descriptor:

OCI_ATTR_ATTEMPTS

Mode

READ

Description

Specifies the number of attempts that have been made to dequeue the message. This parameter cannot be set at enqueue time.

Attribute Datatype

sb4

Valid Values

Any sb4 value is valid.

OCI_ATTR_CORRELATION

Mode

READ/WRITE

Description

Specifies the identification supplied by the producer for a message at enqueuing.

Attribute Datatype

oratext *

Valid Values

Any string up to 128 bytes is valid.

OCI_ATTR_DELAY

Mode

READ/WRITE

Description

Specifies the number of seconds to delay the enqueued message. The delay represents the number of seconds after which a message is available for dequeuing. Dequeuing by msgid overrides the delay specification. A message enqueued with delay set will be in the WAITING state, when the delay expires the messages goes to the READY state. DELAY processing requires the queue monitor to be started. Note that delay is set by the producer who enqueues the message.

Attribute Datatype

sb4

Valid Values

Any sb4 value is valid, but the following predefined constant is available:

  • OCI_MSG_NO_DELAY - indicates the message is available for immediate dequeuing.

OCI_ATTR_ENQ_TIME

Mode

READ

Description

Specifies the time the message was enqueued. This value is determined by the system and cannot be set by the user.

Attribute Datatype

OCIDate

OCI_ATTR_EXCEPTION_QUEUE

Mode

READ/WRITE

Description

Specifies the name of the queue to which the message is moved to if it cannot be processed successfully. Messages are moved in two cases: If the number of unsuccessful dequeue attempts has exceeded max_retries; or if the message has expired. All messages in the exception queue are in the EXPIRED state.

The default is the exception queue associated with the queue table. If the exception queue specified does not exist at the time of the move the message will be moved to the default exception queue associated with the queue table and a warning will be logged in the alert file. If the default exception queue is used, the parameter will return a NULL value at dequeue time.

This attribute must refer to a valid queue name.

Attribute Datatype

oratext *

OCI_ATTR_EXPIRATION

Mode

READ/WRITE

Description

Specifies the expiration of the message. It determines, in seconds, the duration the message is available for dequeuing. This parameter is an offset from the delay. Expiration processing requires the queue monitor to be running.

While waiting for expiration, the message remains in the READY state. If the message is not dequeued before it expires, it will be moved to the exception queue in the EXPIRED state.

Attribute Datatype

sb4

Valid Values

Any sb4 value is valid, but the following predefined constant is available:

  • OCI_MSG_NO_EXPIRATION - the message will not expire.

OCI_ATTR_MSG_DELIVERY_MODE

Mode

READ

Description

After a dequeue call, the OCI client can read the OCI_MSG_DELIVERY_MODE attribute in the OCIAQMsgProperties descriptor to determine whether a persistent or buffered message was dequeued. The value of the attribute is OCI_MSG_PERSISTENT for persistent messages and OCI_MSG_BUFFERED for buffered messages.

Attribute Datatype

ub2

OCI_ATTR_MSG_STATE

Mode

READ

Description

Specifies the state of the message at the time of the dequeue. This parameter cannot be set at enqueue time.

Attribute Datatype

ub4

Valid Values

These are the only values which are returned:

  • OCI_MSG_WAITING - the message delay has not yet been reached.

  • OCI_MSG_READY - the message is ready to be processed.

  • OCI_MSG_PROCESSED - the message has been processed and is retained.

  • OCI_MSG_EXPIRED - the message has been moved to the exception queue.

OCI_ATTR_PRIORITY

Mode

READ/WRITE

Description

Specifies the priority of the message. A smaller number indicates higher priority. The priority can be any number, including negative numbers.

The default value is zero.

Attribute Datatype

sb4

OCI_ATTR_RECIPIENT_LIST

Mode

WRITE

Description

This parameter is only valid for queues which allow multiple consumers. The default recipients are the queue subscribers. This parameter is not returned to a consumer at dequeue time.

Attribute Datatype

OCIAQAgent **

OCI_ATTR_SENDER_ID

Mode

READ/WRITE

Description

Identifies the original sender of a message.

Attribute Datatype

OCIAgent *

OCI_ATTR_TRANSACTION_NO

Mode

READ

Description

For transaction-grouped queues, this identifies the transaction group of the message. This attribute is populated after a successful OCIAQDeqArray() call. All messages in a group have the same value for this attribute. This attribute cannot be used by the OCIAQEnqArray() call to set the transaction group for an enqueued message.

Attribute Datatype

oratext *

OCI_ATTR_ORIGINAL_MSGID

Mode

READ/WRITE

Description

The ID of the message in the last queue that generated this message. When a message is propagated from one queue to another, this attribute identifies the ID of the queue from which it was last propagated. When a message has been propagated through multiple queues, this attribute identifies the ID of the message in the last queue that generated this message, not the first queue.

Attribute Datatype

OCIRaw *

OCIAQAgent Descriptor Attributes

The following attributes are properties of the OCIAQAgent descriptor:

OCI_ATTR_AGENT_ADDRESS

Mode

READ/WRITE

Description

Protocol-specific address of the recipient. If the protocol is 0 (default), the address is of the form [schema.]queue[@dblink].

Attribute Datatype

oratext *

Valid Values

Can be any string up to 128 bytes.

OCI_ATTR_AGENT_NAME

Mode

READ/WRITE

Description

Name of a producer or consumer of a message.

Attribute Datatype

oratext *

Valid Values

Can be any Oracle identifier, up to 30 bytes.

OCI_ATTR_AGENT_PROTOCOL

Mode

READ/WRITE

Description

Protocol to interpret the address and propagate the message. The default (and currently the only supported) value is 0.

Attribute Datatype

ub1

Valid Values

The only valid value is zero, which is also the default.

OCIServerDNs Descriptor Attributes

The following attributes are properties of the OCIServerDNs descriptor:

OCI_ATTR_DN_COUNT

Mode

READ

Description

The number of database servers in the descriptor.

Attribute Datatype

ub2

OCI_ATTR_SERVER_DN

Mode

READ/WRITE

Description

For read mode, this attribute returns the list of database server distinguished names that are already inserted into the descriptor.

For write mode, this attribute takes the distinguished name of a database server.

Attribute Datatype

oratext **/oratext *

Subscription Handle Attributes

OCI_ATTR_SERVER_DNS

Mode

READ/WRITE

Description

The distinguished names of the database servers that the client is interested in for the registration.

Attribute Datatype

OCIServerDNs *

OCI_ATTR_SUBSCR_CALLBACK

Mode

READ/WRITE

Description

Subscription callback. If the attribute OCI_ATTR_SUBSCR_RECPTPROTO is set to OCI_SUBSCR_PROTO_OCI or is left not set, then this attribute needs to be set before the subscription handle can be passed into the registration call OCISubscriptionRegister().

Attribute Datatype

ub4 (void *, OCISubscription *, void *, ub4, void *, ub4)

OCI_ATTR_SUBSCR_CQ_QOSFLAGS

Mode

WRITE

Description

Sets QOS (quality of service flags) specific to continuous query (CQ) notifications. For the possible values you can pass:

Attribute Datatype

ub4 *

OCI_ATTR_SUBSCR_CTX

Mode

READ/WRITE

Description

Context that the client wants to get passed to the user callback denoted by OCI_ATTR_SUBSCR_CALLBACK when it gets invoked by the system. If the attribute OCI_ATTR_SUBSCR_RECPTPROTO is set to OCI_SUBSCR_PROTO_OCI or is left not set, then this attribute needs to be set before the subscription handle can be passed into the registration call OCI Subscription Register().

Attribute Datatype

void *

OCI_ATTR_SUBSCR_NAME

Mode

READ/WRITE

Description

Subscription name. All subscriptions are identified by a subscription name. A subscription name consists of a sequence of bytes of specified length. The length in bytes of the name needs to be specified as it is not assumed that the name will be NULL-terminated. This is important because the name could contain multibyte characters.

Clients will be able to set the subscription name attribute of a Subscription handle using an OCIAttrSet() call and by specifying a handle type of OCI_HTYPE_SUBSCR and an attribute type of OCI_ATTR_SUBSCR_NAME.

All of the subscription callbacks need a subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set. If the attributes are not set, an error is returned. The subscription name that is set for the subscription handle must be consistent with its namespace.

Attribute Datatype

oratext *

OCI_ATTR_SUBSCR_NAMESPACE

Mode

READ/WRITE

Description

Namespace in which the subscription handle is used. The valid values for this attribute are OCI_SUBSCR_NAMESPACE_AQ, OCI_SUBSCR_NAMESPACE_DBCHANGE, and OCI_SUBSCR_NAMESPACE_ANONYMOUS.

The subscription name that is set for the subscription handle must be consistent with its namespace.

Attribute Datatype

ub4 *

Note:

OCI_OBJECT mode is required when using grouping notifications.

OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS

Mode

READ/WRITE

Description

Notification grouping class. If set to 0 (the default) all other notification grouping attributes must be 0. It is implemented for time in the latest release and is the only current criterion for grouping. Can be set to OCI_SUBSCR_NTFN_GROUPING_CLASS_TIME.

Attribute Datatype

ub1 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT

Mode

READ/WRITE

Description

How many times to do the grouping. Notification repeat count. Positive integer. Can be set to OCI_SUBSCR_NTFN_GROUPING_FOREVER to send grouping notifications forever.

Attribute Datatype

sb4 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_START_TIME

Mode

READ/WRITE

Description

The time grouping starts. Set to a valid TIMESTAMP WITH TIME ZONE. The default is the current TIMESTAMP WITH TIME ZONE.

Attribute Datatype

OCIDateTime */OCIDateTime **

OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE

Mode

READ/WRITE

Description

The format of the grouping notification: whether a summary of all events in the group or just the last event in the group. Use OCIAttrSet() to set to one of the following notification grouping types: OCI_SUBSCR_NTFN_TYPE_SUMMARY or OCI_SUBSCR_NTFN_TYPE_LAST. Summary of notifications is the default. The other choice is the last notification.

Attribute Datatype

ub1 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE

Mode

READ/WRITE

Description

Specifies the value of for the grouping class. For time, this is the time-period of grouping notifications specified in seconds, that is, the time after which grouping notification is sent periodically until OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT is exhausted.

Attribute Datatype

ub4 *

OCI_ATTR_SUBSCR_PAYLOAD

Mode

READ/WRITE

Description

Buffer that corresponds to the payload that needs to be sent along with the notification. The length of the buffer can also be specified in the same set attribute call. This attribute needs to be set before a post can be performed on a subscription. For this release, only an untyped (ub1 *) payload is supported.

Attribute Datatype

ub1 *

OCI_ATTR_SUBSCR_PORTNO

Mode

READ/WRITE

Description

Port number on the server, set on the environment handle. The port number is sent to clients by OCISessionBegin().

Attribute Datatype

ub4 *

OCI_ATTR_SUBSCR_QOSFLAGS

Mode

READ/WRITE

Description

Quality of service levels of the server. The possible settings are:

  1. OCI_SUBSCR_QOS_RELIABLE - Reliable. If database crashes, do not lose notification. Not supported for nonpersistent queues or buffered messaging.

  2. OCI_SUBSCR_QOS_PURGE_ON_NTFN - Once received, purge notification and remove subscription.

  3. OCI_SUBSCR_QOS_PAYLOAD - Payload notification.

Attribute Datatype

ub4 *

OCI_ATTR_SUBSCR_RECPT

Mode

READ/WRITE

Description

The name of the recipient of the notification when the attribute OCI_ATTR_SUBSCR_RECPTPROTO is set to OCI_SUBSCR_PROTO_MAIL, OCI_SUBSCR_PROTO_HTTP, or OCI_SUBSCR_PROTO_SERVER.

For OCI_SUBSCR_PROTO_HTTP, OCI_ATTR_SUBSCR_RECPT denotes the HTTP URL (for example, http://www.oracle.com:80) to which notification is sent. The validity of the HTTP URL is never checked by the database.

For OCI_SUBSCR_PROTO_MAIL, OCI_ATTR_SUBSCR_RECPT denotes the e-mail address (for example, xyz@oracle.com) to which the notification is sent. The validity of the e-mail address is never checked by the database system.

For OCI_SUBSCR_PROTO_SERVER, OCI_ATTR_SUBSCR_RECPT denotes the database procedure (for example: schema.procedure) that will be invoked in the event of a notification. The subscriber should have appropriate permissions on the procedure for it to be executed.

See Also:

For information about procedure definition, see "Notification Procedure"
Attribute Datatype

oratext *

OCI_ATTR_SUBSCR_RECPTPRES

Mode

READ/WRITE

Description

The presentation with which the client wants to receive the notification. The valid values for this are OCI_SUBSCR_PRES_DEFAULT and OCI_SUBSCR_PRES_XML.

If not set, this attribute defaults to OCI_SUBSCR_PRES_DEFAULT.

If the event notification is desired in XML presentation then this attribute should be set to OCI_SUBSCR_PRES_XML. Otherwise, it should be left not set or set to OCI_SUBSCR_PRES_DEFAULT.

Attribute Datatype

ub4

OCI_ATTR_SUBSCR_RECPTPROTO

Mode

READ/WRITE

Description

The protocol with which the client wants to receive the notification. The valid values for this are

If an OCI client is interested in receiving the event notification, then this attribute should be set to OCI_SUBSCR_PROTO_OCI.

If you want an e-mail to be sent on event notification, then set this attribute to OCI_SUBSCR_PROTO_MAIL. If you want a PL/SQL procedure to be invoked in the database on event notification, then set this attribute to OCI_SUBSCR_PROTO_SERVER. If you want a HTTP URL to be posted to on event notification, then set this attribute to OCI_SUBSCR_PROTO_HTTP.

If not set, this attribute defaults to OCI_SUBSCR_PROTO_OCI.

For OCI_SUBSCR_PROTO_OCI, the attributes OCI_ATTR_SUBSCR_CALLBACK and OCI_ATTR_SUBSCR_CTX must be set before the subscription handle can be passed into the registration call OCISubscriptionRegister().

For OCI_SUBSCR_PROTO_MAIL, OCI_SUBSCR_PROTO_SERVER, and OCI_SUBSCR_PROTO_HTTP, the attribute OCI_ATTR_SUBSCR_RECPT must be set before the subscription handle can be passed into the registration call OCISubscriptionRegister().

Attribute Datatype

ub4 *

OCI_ATTR_SUBSCR_TIMEOUT

Mode

READ/WRITE

Description

Registration timeout interval in seconds. If 0 or not specified, then the registration lives until explicitly unregistered.

Attribute Datatype

ub4 *

Continuous Query Notification Attributes

OCI_ATTR_CHNF_CHANGELAG

Mode

WRITE

Description

The number of transactions that the client is to lag in continuous query notifications.

Attribute Datatype

ub4 *

OCI_ATTR_CHNF_OPERATIONS

Mode

WRITE

Description

Used to filter notifications based on operation type.

Attribute Datatype

ub4 *

See Also:

"Continuous Query Notification" for details about the flag values

OCI_ATTR_CHNF_ROWIDS

Mode

WRITE

Description

If TRUE, the continuous query notification message includes row level details such as operation type and ROWID. The default is FALSE.

Attribute Datatype

boolean *

OCI_ATTR_CHNF_TABLENAMES

Mode

READ

Description

Attributes provided to retrieve the list of table names that were registered. These attributes are available from the subscription handle, after the query is executed.

Attribute Datatype

OCIColl **

Continuous Query Notification Descriptor Attributes

OCI_ATTR_CHDES_DBNAME

Mode

READ

Description

Name of the database.

Attribute Datatype

oratext **

OCI_ATTR_CHDES_NFTYPE

Mode

READ

Description

Flags describing the notification type.

Attribute Datatype

ub4 *

See Also:

"Continuous Query Notification" for the flag values

OCI_ATTR_CHDES_ROW_OPFLAGS

Mode

READ

Description

Operation type: INSERT, UPDATE, DELETE, or OTHER.

Attribute Datatype

ub4 *

OCI_ATTR_CHDES_ROW_ROWID

Mode

READ

Description

String representation of a ROWID.

Attribute Datatype

oratext **

OCI_ATTR_CHDES_TABLE_CHANGES

Mode

READ

Description

A collection type describing operations on tables. Each element of the collection is a table continuous query descriptors (OCITableChangeDesc *) of type OCI_DTYPE_TABLE_CHDES which has the attributes that begin with OCI_ATTR_CHDES_TABLE. See the following entries.

Attribute Datatype

OCIColl **

OCI_ATTR_CHDES_TABLE_NAME

Mode

READ

Description

Schema and table name. HR.EMPLOYEES, for example.

Attribute Datatype

oratext **

OCI_ATTR_CHDES_TABLE_OPFLAGS

Mode

READ

Description

Flags describing the operations on the table.

Attribute Datatype

ub4 *

See Also:

"OCI_DTYPE_TABLE_CHDES" for the flag values

OCI_ATTR_CHDES_TABLE_ROW_CHANGES

Mode

READ

Description

An embedded collection describing the changes to the rows of the table. Each element of the collection is a row continuous query descriptor (OCIRowChangeDesc *) of type OCI_DTYPE_ROW_CHDES which has the attributes OCI_ATTR_CHDES_ROW_OPFLAGS and OCI_ATTR_CHDES_ROW_ROWID.

Attribute Datatype

OCIColl **

Notification Descriptor Attributes

Attributes of the descriptor OCI_DTYPE_AQNFY:

OCI_ATTR_AQ_NTFN_GROUPING_COUNT

Mode

READ

Description

For AQ namespace. Count of notifications received in the group.

Attribute Datatype

ub4 *

OCI_ATTR_AQ_NTFN_GROUPING_ MSGID_ARRAY

Mode

READ

Description

For AQ namespace. The group: an OCI Collection of message ids.

Attribute Datatype

OCIColl **

OCI_ATTR_CONSUMER_NAME

Mode

READ

Description

Consumer name of the notification.

Attribute Datatype

oratext *

OCI_ATTR_NFY_FLAGS

Mode

READ

Description

0 = regular, 1 = timeout notification, 2 = grouping notification.

Attribute Datatype

ub4 *

OCI_ATTR_NFY_MSGID

Mode

READ

Description

Message ID.

Attribute Datatype

OCIRaw *

OCI_ATTR_MSG_PROP

Mode

READ

Description

Message properties.

Attribute Datatype

OCIAQMsgProperties **

OCI_ATTR_QUEUE_NAME

Mode

READ

Description

The queue name of the notification.

Attribute Datatype

oratext *

Invalidated Query Attributes

This section describes OCI_DTYPE_CQDES attributes.

Direct Path Loading Handle Attributes

See Also:

For information about direct path loading and allocating the direct path handles, see "Direct Path Loading Overview" and"Direct Path Loading of Object Types"

OCI_ATTR_CQDES_OPERATION

Mode

READ

Description

The operation which occurred on the query. It can be one of the two values: OCI_EVENT_QUERYCHANGE (query result set change) or OCI_EVENT_DEREG (query unregistered).

Attribute Datatype

ub4 *

OCI_ATTR_CQDES_QUERYID

Mode

READ

Description

Query id of the query which was invalidated.

Attribute Datatype

ub8 *

OCI_ATTR_CQDES_TABLE_CHANGES

Mode

READ

Description

A collection of table continuous query descriptors describing DML or DDL operations on tables which caused the query result set change. Each element of the collection is of type OCI_DTYPE_TABLE_CHDES.

Attribute Datatype

OCIColl *

Direct Path Context Handle (OCIDirPathCtx) Attributes

OCI_ATTR_BUF_SIZE

Mode

READ/WRITE

Description

Sets the size of the stream transfer buffer. Default value is 64KB.

Attribute Datatype

ub4 */ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

Default character set ID for the character data. Note that the character set ID can be overridden at the column level. If character set ID is not specified at the column level or the table level, then the Global support environment setting is used.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_DATEFORMAT

Mode

READ/WRITE

Description

Default date format string for SQLT_CHAR to DTYDAT conversions. Note that the date format string can be overridden at the column level. If date format string is not specified at the column level or the table level, then the Global Support environment setting is used.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_DIRPATH_DCACHE_DISABLE

Mode

READ/WRITE

Description

Setting this attribute to 1 indicates that the date cache will be disabled if exceeded. The default value is 0, which means that lookups in the cache will continue on cache overflow.

See Also:

"Using a Date Cache in Direct Path Loading of Dates in OCI" for a complete description of this attribute and of the four following attributes.
Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_DCACHE_HITS

Mode

READ

Description

Queries the number of date cache hits.

Attribute Datatype

ub4 *

OCI_ATTR_DIRPATH_DCACHE_MISSES

Mode

READ

Description

Queries the current number of date cache misses.

Attribute Datatype

ub4 *

OCI_ATTR_DIRPATH_DCACHE_NUM

Mode

READ

Description

Queries the current number of entries in a date cache.

Attribute Datatype

ub4 *

OCI_ATTR_DIRPATH_DCACHE_SIZE

Mode

READ/WRITE

Description

Sets the date cache size (in elements) for a table. To disable the date cache, set to 0, which is the default value.

Attribute Datatype

ub4 */ub4 *

OCI_ATTR_DIRPATH_INDEX_MAINT_METHOD

Mode

READ/WRITE

Description

Performs index row insertion on a per-row basis.

Valid value is:

OCI_DIRPATH_INDEX_MAINT_SINGLE_ROW

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_MODE

Mode

READ/WRITE

Description

Mode of the direct path context:

  • OCI_DIRPATH_LOAD-load operation (default)

  • OCI_DIRPATH_CONVERT - convert only operation

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_NOLOG

Mode

READ/WRITE

Description

The NOLOG attribute of each segment determines whether image redo or invalidation redo is generated:

  • 0 - Use the attribute of the segment being loaded.

  • 1 - No logging. Overrides DDL statement, if necessary.

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_OBJ_CONSTR

Mode

READ/WRITE

Description

Indicates the object type of a substitutable object table:

OraText *obj_type; /* stores an object type name */
OCIAttrSet((void *)dpctx,
                           (ub4)OCI_HTYPE_DIRPATH_CTX,
                           (void *) obj_type,
                           (ub4)strlen((const char *) obj_type),
                           (ub4)OCI_ATTR_DIRPATH_OBJ_CONSTR, errhp);
Attribute Datatype

oratext **/oratext *

OCI_ATTR_DIRPATH_PARALLEL

Mode

READ/WRITE

Description

Setting this value to 1 allows multiple load sessions to load the same segment concurrently. The default is 0 (not parallel).

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_SKIPINDEX_METHOD

Mode

READ/WRITE

Description

Indicates how the handling of unusable indexes will be performed.

Valid values are:

  • OCI_DIRPATH_INDEX_MAINT_SKIP_UNUSABLE (skip unusable indexes)

  • OCI_DIRPATH_INDEX_MAINT_DONT_SKIP_UNUSABLE (do not skip unusable indexes)

  • OCI_DIRPATH_INDEX_MAINT_SKIP_ALL (skip all index maintenance)

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_LIST_COLUMNS

Mode

READ

Description

Returns the handle to the parameter descriptor for the column list associated with the direct path context. The column list parameter descriptor can be retrieved after the number of columns is set with the OCI_ATTR_NUM_COLS attribute.

Attribute Datatype

OCIParam* *

OCI_ATTR_NAME

Mode

READ/WRITE

Description

Name of the table to be loaded into.

Attribute Datatype

oratext**/oratext *

OCI_ATTR_NUM_COLS

Mode

READ/WRITE

Description

Number of columns being loaded in the table.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_NUM_ROWS

Mode

READ/WRITE

Description

Read: The number of rows loaded so far.

Write: The number of rows to be allocated for the direct path and the direct path function column arrays.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_SCHEMA_NAME

Mode

READ/WRITE

Description

Name of the schema where the table being loaded resides. If not specified, the schema defaults to that of the connected user.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_SUB_NAME

Mode

READ/WRITE

Description

Name of the partition, or subpartition, to be loaded. If not specified, the entire table is loaded. The name must be a valid partition or subpartition name which belongs to the table.

Attribute Datatype

oratext **/oratext *

Direct Path Function Context Handle (OCIDirPathFuncCtx) Attributes

For further explanations of these attributes:

OCI_ATTR_DIRPATH_EXPR_TYPE

Mode

READ/WRITE

Description

Indicates the type of expression specified in OCI_ATTR_NAME in the function context of a non-scalar column.

Valid values are:

  • OCI_DIRPATH_EXPR_OBJ_CONSTR (the object type name of a column object)

  • OCI_DIRPATH_EXPR_REF_TBLNAME (table name of a reference object)

  • OCI_DIRPATH_EXPR_SQL (a SQL string to derive the column value)

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_LIST_COLUMNS

Mode

READ

Description

Returns the handle to the parameter descriptor for the column list associated with the direct path function context. The column list parameter descriptor can be retrieved after the number of columns (number of attributes or arguments associated with the non-scalar column) is set with the OCI_ATTR_NUM_COLS attribute.

Attribute Datatype

OCIParam**

OCI_ATTR_NAME

Mode

READ/WRITE

Description

The object type name if the function context is describing a column object, a SQL function if the function context is describing a SQL string, or a reference table name if the function context is describing a REF column.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_NUM_COLS

Mode

READ/WRITE

Description

The number of the object attributes to load if the column is a column object, or the number of arguments to process if the column is a SQL string or a REF column. This parameter must be set before the column list can be retrieved.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_NUM_ROWS

Mode

READ

Description

The number of rows loaded so far.

Attribute Datatype

ub4 *

Direct Path Function Column Array Handle (OCIDirPathColArray) Attributes

OCI_ATTR_COL_COUNT

Mode

READ

Description

Last column of the last row processed.

Attribute Datatype

ub2 *

OCI_ATTR_NUM_COLS

Mode

READ

Description

Column dimension of the column array.

Attribute Datatype

ub2 *

OCI_ATTR_NUM_ROWS

Mode

READ

Description

Row dimension of the column array.

Attribute Datatype

ub4 *

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Number of rows successfully converted in the last call to OCIDirPathColArrayToStream().

Attribute Datatype

ub4 *

Direct Path Stream Handle (OCIDirPathStream) Attributes

OCI_ATTR_BUF_ADDR

Mode

READ

Description

Buffer address of the beginning of the stream data.

Attribute Datatype

ub1 **

OCI_ATTR_BUF_SIZE

Mode

READ

Description

Size of the stream data in bytes.

Attribute Datatype

ub4 *

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Number of rows successfully loaded by the last OCIDirPathLoadStream() call.

Attribute Datatype

ub4 *

OCI_ATTR_STREAM_OFFSET

Mode

READ

Description

Offset into the stream buffer of the last processed row.

Attribute Datatype

ub4 *

Direct Path Column Parameter Attributes

The application specifies which columns are to be loaded, and the external format of the data by setting attributes on each column parameter descriptor. The column parameter descriptors are obtained as parameters of the column parameter list by OCIParamGet(). The column parameter list of the table is obtained from the OCI_ATTR_LIST_COLUMNS attribute of the direct path context. If a column is non-scalar, then its column parameter list is obtained from the OCI_ATTR_LIST_COLUMNS attribute of its direct path function context.

Note that all parameters are 1-based.

Accessing Column Parameter Attributes

The following code example illustrates the use of the direct path column parameter attributes for scalar columns. Before the attributes are accessed, you must first set the number of columns to be loaded and get the column parameter list from the OCI_ATTR_LIST_COLUMNS attribute.

See Also:

See the data structures defined in the listings in Direct Path Load Example for Scalar Columns
...
  /* set number of columns to be loaded */
  OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
            OCIAttrSet((void *)dpctx, (ub4)OCI_HTYPE_DIRPATH_CTX,
                       (void *)&tblp->ncol_tbl,
                       (ub4)0, (ub4)OCI_ATTR_NUM_COLS, ctlp->errhp_ctl));

  /* get the column parameter list */
  OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
            OCIAttrGet((void *)dpctx, OCI_HTYPE_DIRPATH_CTX,
                       (void *)&ctlp->colLstDesc_ctl, (ub4 *)0,
                       OCI_ATTR_LIST_COLUMNS, ctlp->errhp_ctl));

Now you can set the parameter attributes.

/* set the attributes of each column by getting a parameter handle on each
   * column, then setting attributes on the parameter handle for the column.
   * Note that positions within a column list descriptor are 1-based. */

   for (i = 0, pos = 1, colp = tblp->col_tbl, fldp = tblp->fld_tbl;
       i < tblp->ncol_tbl;
       i++, pos++, colp++, fldp++)
  {
    /* get parameter handle on the column */
    OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
              OCIParamGet((const void  *)ctlp->colLstDesc_ctl,
                          (ub4)OCI_DTYPE_PARAM, ctlp->errhp_ctl,
                          (void  **)&colDesc, pos));

    colp->id_col = i;                  /* position in column array */

    /* set external attributes on the column */
    /* column name */
    OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
              OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)colp->name_col,
                         (ub4)strlen((const char *)colp->name_col),
                         (ub4)OCI_ATTR_NAME, ctlp->errhp_ctl));

    /* column type */
    OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
              OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)&colp->exttyp_col, (ub4)0,
                         (ub4)OCI_ATTR_DATA_TYPE, ctlp->errhp_ctl));

    /* max data size */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
              OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)&fldp->maxlen_fld, (ub4)0,
                         (ub4)OCI_ATTR_DATA_SIZE, ctlp->errhp_ctl));

    if (colp->datemask_col)    /* set column (input field) date mask */
    {
      OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
                OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)colp->datemask_col,
                         (ub4)strlen((const char *)colp->datemask_col),
                         (ub4)OCI_ATTR_DATEFORMAT, ctlp->errhp_ctl));
    }
    if (colp->prec_col)
    {
      OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
                OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)&colp->prec_col, (ub4)0,
                         (ub4)OCI_ATTR_PRECISION, ctlp->errhp_ctl));
    }
    if (colp->scale_col)
    {
      OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
                OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)&colp->scale_col, (ub4)0,
                         (ub4)OCI_ATTR_SCALE, ctlp->errhp_ctl));
    }
    if (colp->csid_col)
    {
      OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
                OCIAttrSet((void  *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (void  *)&colp->csid_col, (ub4)0,
                         (ub4)OCI_ATTR_CHARSET_ID, ctlp->errhp_ctl));
    }
    /* free the parameter handle to the column descriptor */
    OCI_CHECK((void  *)0, 0, ociret, ctlp,
              OCIDescriptorFree((void  *)colDesc, OCI_DTYPE_PARAM));
  }
...

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

Character set ID for character column. If not set, the character set ID defaults to the character set ID set in the direct path context.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_DATA_SIZE

Mode

READ/WRITE

Description

Maximum size in bytes of the external data for the column. This can affect conversion buffer sizes.

Attribute Datatype

ub4 */ub4 *

OCI_ATTR_DATA_TYPE

Mode

READ/WRITE

Description

Returns or sets the external datatype of the column. Valid datatypes are:

  • SQLT_CHR

  • SQLT_DATE

  • SQLT_TIMESTAMP

  • SQLT_TIMESTAMP_TZ

  • SQLT_TIMESTAMP_LTZ

  • SQLT_INTERVAL_YM

  • SQLT_INTERVAL_DS

  • SQLT_INT

  • SQLT_UIN

  • SQLT_FLT

  • SQLT_PDN

  • SQLT_BIN

  • SQLT_NUM

  • SQLT_NTY

  • SQLT_REF

  • SQLT_VST

  • SQLT_VNU

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_DATEFORMAT

Mode

READ/WRITE

Description

Date conversion mask for the column. If not set, the date format defaults to the date conversion mask set in the direct path context.

Attribute Datatype

oratext **/oratext *

OCI_ATTR_DIRPATH_OID

Mode

READ/WRITE

Description

Indicates that the column to load into is an object table's object id column.

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_SID

Mode

READ/WRITE

Description

Indicates that the column to load into is a nested table's setid column.

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_NAME

Mode

READ/WRITE

Description

Returns or sets the name of the column that is being loaded. Initialize both the column name and the column name length to 0 before calling OCIAttrGet().

Attribute Datatype

oratext **/oratext *

OCI_ATTR_PRECISION

Mode

READ/WRITE

Description

Returns or sets the precision.

Attribute Datatype

ub1 */ub1 * for explicit describes

sb2 */sb2 * for implicit describes

OCI_ATTR_SCALE

Mode

READ/WRITE

Description

Returns or sets the scale (number of digits to the right of the decimal point) for conversions from packed and zoned decimal input datatypes.

Attribute Datatype

sb1 */sb1 *

Process Handle Attributes

The parameters for the shared system can be set and read using the OCIAttrSet() and OCIAttrGet() calls. The handle type to be used is the process handle OCI_HTYPE_PROC.

The OCI_ATTR_MEMPOOL_APPNAME, OCI_ATTR_MEMPOOL_HOMENAME, and OCI_ATTR_MEMPOOL_INSTNAME attributes specify the application, home, and instance names that can be used together to map the process to the right shared pool area. If these attributes are not provided, internal default values are used. The following are valid settings of the attributes for specific behaviors:

OCI_ATTR_MEMPOOL_APPNAME

Mode

READ/WRITE

Description

Executable name or fully-qualified path name of the executable.

Attribute Datatype

oratext *

OCI_ATTR_MEMPOOL_HOMENAME

Mode

READ/WRITE

Description

Directory name where the executables that use the same shared subsystem instance are located.

Attribute Datatype

oratext *

OCI_ATTR_MEMPOOL_INSTNAME

Mode

READ/WRITE

Description

Any user-defined name to identify an instance of the shared subsystem.

Attribute Datatype

oratext *

OCI_ATTR_MEMPOOL_SIZE

Mode

READ/WRITE

Description

Size of the shared pool in bytes. This attribute is set as follows:

ub4 plsz = 1000000;
OCIAttrSet((void  *)0, (ub4) OCI_HTYPE_PROC,
           (void  *)&plsz, (ub4) 0, (ub4) OCI_ATTR_POOL_SIZE, 0);
Attribute Datatype

ub4 *

OCI_ATTR_PROC_MODE

Mode

READ

Description

Returns all the currently set process modes. The value read contains the OR'ed value of all the currently set OCI process modes. To determine if a specific mode is set, the value should be OR'ed with that mode. For example:

ub4 mode;
boolean is_shared;

OCIAttrGet((void  *)0, (ub4)OCI_HTYPE_PROC,
           (void  *) &mode, (ub4 *) 0,
           (ub4)OCI_ATTR_PROC_MODE, 0);

is_shared = mode | OCI_SHARED;
Attribute Datatype

ub4 *

Event Handle Attributes

The OCIEvent handle encapsulates the attributes from the event payload. This handle is implicitly allocated prior to calling the event callback.

The event callback obtains the attributes of an event using OCIAttrGet() with the following attributes:

OCI_ATTR_DBDOMAIN

Mode

READ

Description

When called with this attribute, OCIAttrGet() retrieves the name of the database domain that has been affected by this event.

Attribute Datatype

oratext **

OCI_ATTR_DBNAME

Mode

READ

Description

When called with this attribute, OCIAttrGet() retrieves the name of the database that has been affected by this event.

Attribute Datatype

oratext **

OCI_ATTR_EVENTTYPE

Mode

READ

Description

The type of event that occurred, OCI_EVENTTYPE_HA.

Attribute Datatype

ub4 *

OCI_ATTR_HA_SOURCE

Mode

READ

Description

If the event type is OCI_EVENTTYPE_HA, get the source of the event with this attribute. Valid values are:

  • OCI_HA_SOURCE_DATABASE

  • OCI_HA_SOURCE_NODE

  • OCI_HA_SOURCE_INSTANCE

  • OCI_HA_SOURCE_SERVICE

  • OCI_HA_SOURCE_SERVICE_MEMBER

  • OCI_HA_SOURCE_ASM_INSTANCE

  • OCI_HA_SOURCE_SERVICE_PRECONNECT

Attribute Datatype

ub4 *

OCI_ATTR_HA_SRVFIRST

Mode

READ

Description

When called with this attribute, OCIAttrGet() retrieves the first server handle in the list of server handles affected by a Real Application Clusters (RAC) HA DOWN event.

Attribute Datatype

OCIServer **

OCI_ATTR_HA_SRVNEXT

Mode

READ

Description

When called with this attribute OCIAttrGet() retrieves the next server handle in the list of server handles affected by a Real Application Clusters (RAC) HA DOWN event.

Attribute Datatype

OCIServer **

OCI_ATTR_HA_STATUS

Mode

READ

Description

Valid value is OCI_HA_STATUS_DOWN. Only DOWN events are subscribed to currently.

Attribute Datatype

ub4 *

OCI_ATTR_HA_TIMESTAMP

Mode

READ

Description

The time that the HA event occurred.

Attribute Datatype

OCIDateTime **

OCI_ATTR_HOSTNAME

Mode

READ

Description

When called with this attribute, OCIAttrGet() retrieves the name of the host that has been affected by this event.

Attribute Datatype

oratext **

OCI_ATTR_INSTNAME

Mode

READ

Description

When called with this attribute, OCIAttrGet() retrieves the name of the instance that has been affected by this event.

Attribute Datatype

oratext **

OCI_ATTR_SERVICENAME

Mode

READ

Description

When called with this attribute, OCIAttrGet() retrieves the name of the service that has been affected by this event.

Attribute Datatype

oratext **