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 Data Type

This is the data type of the attribute. If necessary, a distinction is made between the data type 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.

The following attributes are used for the environment handle.

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 Data Type

OCIDuration */OCIDuration

OCI_ATTR_BIND_DN

Mode

READ/WRITE

Description

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

Attribute Data Type

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, which can considerably improve performance. An attribute value of TRUE should only be used when the order in which the objects are flushed is not important. When the attribute value is set to TRUE, it is not guaranteed that the order in which the objects are marked dirty is preserved.

See Also:

Object Cache Parameters and About Flushing Changes to the Server

Attribute Data Type

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.

See Also:

Object Cache Parameters

Attribute Data Type

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 8 megabytes (MB). Setting this attribute to 0 results in a value of 8 MB being used.

See Also:

Object Cache Parameters

Attribute Data Type

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. When character set ID is UTF-16, an attempt to get this attribute is invalid.

Attribute Data Type

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. When character set ID is UTF-16, an attempt to get this attribute is invalid.

Attribute Data Type

ub2 *

OCI_ATTR_ENV_NLS_LANGUAGE

Mode

READ/WRITE

Description

The name of the language used for the database sessions created from the current environment handle. While getting this value, users should pass an allocated buffer, which will be filled with the language name.

Attribute Data Type

oratext ** or oratext *

OCI_ATTR_ENV_NLS_TERRITORY

Mode

READ/WRITE

Description

The name of the territory used for the database sessions created from the current environment handle. While getting this value, users should pass an allocated buffer, which will be filled with the territory name.

Attribute Data Type

oratext ** or oratext *

OCI_ATTR_ENV_UTF16

Mode

READ

Description

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

Attribute Data Type

ub1 *

OCI_ATTR_EVTCBK

Mode

WRITE

Description

This attribute registers an event callback function.

See Also:

HA Event Notification

Attribute Data Type

OCIEventCallback

OCI_ATTR_EVTCTX

Mode

WRITE

Description

This attribute registers a context passed to an event callback.

See Also:

HA Event Notification

Attribute Data Type

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 Data Type

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 is determined at run time.

Attribute Data Type

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 Data Type

oratext **/oratext *

OCI_ATTR_LDAP_CTX

Mode

READ/WRITE

Description

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

Attribute Data Type

oratext **/oratext *

OCI_ATTR_LDAP_HOST

Mode

READ/WRITE

Description

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

Attribute Data Type

oratext **/oratext *

OCI_ATTR_LDAP_PORT

Mode

READ/WRITE

Description

The port on which the LDAP server is listening.

Attribute Data Type

ub2 */ub2

OCI_ATTR_SODA_METADATA_CACHE

Mode

READ/WRITE

Description

By default, SODA metadata caching is not enabled. If this attribute value is set to TRUE, then it turns on caching of collection descriptors. If the value is set to FALSE, then it disables and purges any pre-existing collection descriptor cache entries.

Attribute Data Type

boolean */boolean

OCI_ATTR_OBJECT

Mode

READ

Description

Returns TRUE if the environment was initialized in object mode.

Attribute Data Type

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, and OCIObjectPin() is called with the pin_option parameter set to OCI_PIN_DEFAULT, the object is pinned in OCI_PIN_RECENT mode.

Attribute Data Type

OCIPinOpt */OCIPinOpt

OCI_ATTR_OBJECT_NEWNOTNULL

Mode

READ/WRITE

Description

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

See Also:

About Creating Objects

Attribute Data Type

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 that has been modified in the server by another committed transaction.

See Also:

About Implementing Optimistic Locking

Attribute Data Type

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 Data Type

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 Data Type

ub4 *

OCI_ATTR_SUBSCR_PORTNO

Mode

READ/WRITE

Description

The client port used to receive notifications. It is set on the client's environment handle.

Attribute Data Type

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 Data Type

oratext **/oratext *

The following attributes are used for the error handle.

OCI_ATTR_DML_ROW_OFFSET

Mode

READ

Description

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

Attribute Data Type

ub4 *

OCI_ATTR_ERROR_IS_RECOVERABLE

Mode

READ

Description

This attribute is set to TRUE if the error in the error handle is recoverable. If the error is not recoverable, it is set to FALSE.

Attribute Data Type

Boolean *

The following attributes are used for service context handle.

OCI_ATTR_CALL_TIMEOUT

Mode

READ/WRITE

Description

A database round-trip call using the service context times out within the specified time in milli-seconds, if not completed. When the call times out, a network timeout error is returned. This attribute can be set dynamically. Setting this value stays effective for all subsequent round-trip calls executed using the same service context until a different value is set. To remove the timeout, the value must be set to 0.

This is a client-only change. So, for using this feature, you must use a release 18c client. This feature is database version agnostic, that is, you can use this feature with any supported version of the database.

Timeout values set in different places are effective according to the following order of precedence (where 1 is the highest precedence):

1. Call timeout set on the OCI handle using OCIAttrSet().

2. Timeout set with the OCI attributes, OCI_ATTR_SEND_TIMEOUT and OCI_ATTR_RECEIVE_TIMEOUT.

3. Timeout set in the sqlnet.ora file with the parameters, SQLNET.RECV_TIMEOUT and SQLNET.SEND_TIMEOUT.

Error returned to the application:

ORA-03136 inbound connection timed out

The Call timeout is on each individual round-trip between OCI and Oracle Database. Each OCI method or operation may require zero or more round-trips to Oracle Database. The timeout value applies to each round-trip individually, not to the sum of all round-trips. Time spent processing in OCI before or after the completion of each round-trip is not counted.

• If the time from the start of any round-trip to the completion of the same round-trip exceeds the timeout value, then the operation is halted and an Oracle error is returned.

• In the case where an OCI operation requires more than one round-trip and each round-trip takes less than the timeout value, then no timeout occurs, even if the sum of all round-trip calls exceeds the timeout value.

• If no round-trip is required, the operation will never be interrupted.

After a timeout occurs, OCI attempts to clean up the internal connection state. The cleanup is allowed to take another timeout value. If the cleanup was successful, an ORA-3136 will be returned and the application can continue to use the connection.

For small values of the timeout value, the connection cleanup may not complete successfully within the additional timeout period. In this case an ORA-3114 is returned and the connection will no longer be usable. It should be released.

Alternatively, the OCI_ATTR_BREAK_ON_NET_TIMEOUT attribute can additionally be set to FALSE. This setting drops the connection, eliminating calls to OCIBreak() and OCIReset() when a timeout occurs.

Attribute Data Type

ub4*/ub4

Example

static void func1( )
{
sword status = 0;
  OCIStmt *stmthp = (OCIStmt *)0;
  OraText *sqlStmt = (OraText *)"SELECT EMPNO FROM SCOTT.EMP";
  ub4 set_timeout= 200; /* in milliseconds */
  ub4 get_timeout = 0;

  Checkerr (errhp, \
      OCIStmtPrepare2 ((OCISvcCtx *)svchp, (OCIStmt **)&stmthp, \
      (OCIError *)errhp, (OraText *)sqlStmt, (ub4)strlen((char *)sqlStmt), \
      (OraText *)NULL, (ub4) 0, (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT), \
      (OraText *)"OCIStmtPrepare2");

  /* Set the call Timeout (in milliseconds) */
    Checkerr (errhp, 
    OCIAttrSet(svchp, (ub4) OCI_HTYPE_SVCCTX,
     (dvoid *) &set_timeout, (ub4) 0,
     (ub4) OCI_ATTR_CALL_TIMEOUT, errhp),
     "OCIAttrSet OCI_ATTR_CALL_TIMEOUT");

    if ((status = OCIStmtExecute ((OCISvcCtx *)svchp, \
      (OCIStmt *)stmthp, (OCIError *)errhp, (ub4)1, (ub4)0, \
      (OCISnapshot *)0, (OCISnapshot *)0, (ub4)OCI_DEFAULT)) \
      != OCI_SUCCESS)
    {
      printf ( "OCIStmtExecute Failed with timeout: %dms\n", set_timeout);
      Checkerr (errhp, status,(OraText *)"OCIStmtExecute");
    }

  /* Get the call Timeout (in milliseconds) */
    Checkerr (errhp,
    OCIAttrGet(svchp, (ub4) OCI_HTYPE_SVCCTX,
     (dvoid *) &get_timeout, (ub4) 0,
     (ub4) OCI_ATTR_CALL_TIMEOUT, errhp),
     "OCIAttrGet OCI_ATTR_CALL_TIMEOUT");

  Checkerr (errhp, \
      OCIStmtRelease ((OCIStmt *)stmthp, (OCIError *)errhp,(dvoid *)NULL, \
      0, OCI_DEFAULT), (oratext *)"StmtRelease");
} /* End of func1 */

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the service context.

Attribute Data Type

OCIEnv **

OCI_ATTR_INSTNAME

See the OCI_ATTR_INSTNAME attribute in Shard Instance Descriptor Attributes for more information about its use on the service context.

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 Data Type

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_MAX_CHARSET_RATIO

Mode

READ

Description

Returns the maximum character set expansion ratio from server to client character set. Using these attributes is useful in scenarios where there are different character sets between server and client. This is useful to allocate optimal memory of buffers before conversion so that when data is returned from the database, sufficient space can be allocated to hold it.

Attribute Data Type

ub4 *

Example

size_t   cratio;
OCIAttrGet((void *)svchp, (ub4)OCI_HTYPE_SVCCTX, (size_t *)&cratio, (ub4) 0, OCI_ATTR_MAX_CHARSET_RATIO, errhp);
printf("Conversion ratio from server to client character set is %d\n", cratio);

OCI_ATTR_MAX_NCHARSET_RATIO

Mode

READ

Description

Returns the maximum character set expansion ratio from server to client national character set. Using these attributes is useful in scenarios where there are different national character sets between server and client. This is useful to allocate optimal memory of buffers before conversion so that when data is returned from the database, sufficient space can be allocated to hold it.

Attribute Data Type

ub4 *

Example

size_t   cratio;
OCIAttrGet((void *)svchp, (ub4)OCI_HTYPE_SVCCTX, (size_t *)&cratio, (ub4) 0, OCI_ATTR_MAX_NCHARSET_RATIO, errhp);
printf("Conversion ratio from server to client ncharset is %d\n", cratio); 

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 Data Type

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 Data Type

OCISession **/ OCISession *

OCI_ATTR_STMTCACHE_CBK

Mode

READ/WRITE

Description

Used to get and set the application's callback function on the OCISvcCtx handle. This function, if registered on OCISvcCtx, is called when a statement in the statement cache belonging to this service context is purged or when the session is ended.

The callback function must be of this prototype:

sword (*OCICallbackStmtCache)(void *ctx, OCIStmt *stmt, ub4 mode)

ctx: IN argument. This is the same as the context the application has set on the current statement handle.

stmt: IN argument. This is the statement handle that is being purged from the cache.

mode: IN argument. This is the mode in which the callback function is being called. Currently only one value is supported, OCI_CBK_STMTCACHE_STMTPURGE, which means the callback is being called during purging of the current statement.

Attribute Data Type

sword (*OCICallbackStmtCache)(void *ctx, OCIStmt *stmt, ub4 mode)

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 nonpooled. Statement caching can be enabled by setting the attribute to a nonzero size and disabled by setting it to zero.

Attribute Data Type

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 Data Type

OCITrans ** / OCITrans *

OCI_ATTR_VARTYPE_MAXLEN_COMPAT

Mode

READ

Description

Returns OCI_ATTR_MAXLEN_COMPAT_EXTENDED if the init.ora parameter max_string_size = extended or returns OCI_ATTR_MAXLEN_COMPAT_STANDARD if the init.ora parameter max_string_size = standard.

Attribute Data Type

ub1 *

The following attributes are used for the server handle.

OCI_ATTR_ACCESS_BANNER

Mode

READ

Description

Displays an unauthorized access banner from a file.

Attribute Data Type

oratext **

OCI_ATTR_BREAK_ON_NET_TIMEOUT

Mode

READ/WRITE

Description

This attribute determines whether OCI sends a break after a network time out or not.

Attribute Data Type

ub1 *

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the server context.

Attribute Data Type

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 for distributed transaction coordination. Server database names can only be accessed only if the database is open at the time the OCISessionBegin() call is issued.

Attribute Data Type

oratext **/ oratext *

OCI_ATTR_FOCBK

Mode

READ/WRITE

Description

Sets the failover callback to the callback definition structure of type OCIFocbkStruct as part of failover callback registration and unregistration on the server context handle.

See Also:

Transparent Application Failover in OCI

Attribute Data Type

OCIFocbkStruct *

OCI_ATTR_INTERNAL_NAME

Mode

READ/WRITE

Description

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

Attribute Data Type

oratext ** / oratext *

OCI_ATTR_INSTNAME

See the OCI_ATTR_INSTNAME attribute in Shard Instance Descriptor Attributes for more information about its use as a server handle attribute.

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 Data Type

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 is returned.

Attribute Data Type

ub1 */ub1

OCI_ATTR_RECEIVE_TIMEOUT

Mode

READ/WRITE

Description

Time specified in milliseconds that a client waits for response data from the database server. When set to a value of zero, the timeout functionality is disabled and the client may wait a long period of time for a response from a database server.

The semantics of this attribute is the same as that of SQLNET.RECV_TIMEOUT that can be specified in the sqlnet.ora file. When set on the server handle, the value overrides the one specified in the sqlnet.ora file.

Attribute Data Type

ub4*/ub4

OCI_ATTR_SEND_TIMEOUT

Mode

READ/WRITE

Description

Time specified in milliseconds that a client waits to complete send operations to the database server. When set to a value of zero, the timeout functionality is disabled and the client may wait a long period of time to complete sending the data to the database server.

The semantics of this attribute is the same as that of SQLNET.SEND_TIMEOUT that can be specified in the sqlnet.ora file. When set on the server handle, the value overrides the one specified in the sqlnet.ora file.

Attribute Data Type

ub4*/ub4

OCI_ATTR_SERVER_GROUP

Mode

READ/WRITE

Description

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

See Also:

Password and Session Management

Attribute Data Type

oratext **/oratext *

OCI_ATTR_SERVER_STATUS

Mode

READ

Description

Returns the current status of the connection by doing a light weight connection health check. Values are:

• OCI_SERVER_NORMAL - The connection is alive.

• OCI_SERVER_NOT_CONNECTED - The connection has been terminated.

Attribute Data Type

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.

See Also:

Custom Pooling: Tagged Server Handles

Attribute Data Type

boolean *

OCI_ATTR_USER_MEMORY

Mode

READ

Description

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

See Also:

Custom Pooling: Tagged Server Handles

Attribute Data Type

void *

The following attributes are used for the administration handle.

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 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 Data Type

oratext */oratext *

The following attributes are used for the connection pool handle.

OCI_ATTR_CONN_TIMEOUT

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 Data Type

ub4 */ub4

OCI_ATTR_CONN_NOWAIT

Mode

READ/WRITE

Description

This attribute determines if retrial for a connection must be performed when all connections in the pool are found to be busy and the number of connections has 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 until it gets a connection.

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

Attribute Data Type

ub1 */ub1

OCI_ATTR_CONN_BUSY_COUNT

Mode

READ

Description

Returns the number of busy connections.

Attribute Data Type

ub4 *

OCI_ATTR_CONN_OPEN_COUNT

Mode

READ

Description

Returns the number of open connections.

Attribute Data Type

ub4 *

OCI_ATTR_CONN_MIN

Mode

READ

Description

Returns the number of minimum connections.

Attribute Data Type

ub4 *

OCI_ATTR_CONN_MAX

Mode

READ

Description

Returns the number of maximum connections.

Attribute Data Type

ub4 *

OCI_ATTR_CONN_INCR

Mode

READ

Description

Returns the connection increment parameter.

Attribute Data Type

ub4 *

The following attributes are used for the transaction handle.

OCI_ATTR_TRANS_NAME

Mode

READ/WRITE

Description

Can be used to establish or read a text string that 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 Data Type

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 Data Type

ub4 * (READ) / ub4 (WRITE)

OCI_ATTR_XID

Mode

READ/WRITE

Description

Can set or read an XID that identifies a transaction.

Attribute Data Type

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

The following attributes are used for the statement handle.

OCI_ATTR_BIND_COUNT

Mode

READ

Description

Returns the number of bind positions on the statement handle.

Attribute Data Type

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 also creates the registration of the query for continuous query notification.

See Also:

Continuous Query Notification Attributes

Attribute Data Type

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 Data Type

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 Data Type

ub4 *

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the statement.

Attribute Data Type

OCIEnv **

OCI_ATTR_FETCH_ROWID

Mode

READ/WRITE

Description

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

See Also:

Implicit Fetching of ROWIDs

Attribute Data Type

boolean */boolean

OCI_ATTR_IMPLICIT_RESULT_COUNT

Mode

READ

Description

Returns the total number of implicit results available on the top-level OCI statement handle.

Attribute Data Type

ub4 *

OCI_ATTR_NUM_DML_ERRORS

Mode

READ

Description

Returns the number of errors in the DML operation.

Attribute Data Type

ub4 *

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

Gets the number of columns in the select-list for the statement associated with the statement handle.

Attribute Data Type

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 data type of each column. You
   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 Data Type

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 the memory level 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 Data Type

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 Data Type

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 nonscrollable 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. Because they are forward sequential only, this also represents the highest row number seen by the application.

For scrollable cursors, OCI_ATTR_ROW_COUNT represents the maximum (absolute) row number fetched into the user buffers. Because 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.

Beginning with Oracle Database Release 12.1, using the attribute OCI_ATTR_UB8_ROW_COUNT is preferred to using the attribute OCI_ATTR_ROW_COUNT if row count values can exceed the value of UB4MAXVAL for an OCI application. If the row count exceeds the value of UB4MAXVAL and the application uses the attribute OCI_ATTR_ROW_COUNT, a call using OCIAttrGet() will return an error.

Attribute Data Type

ub4 *

OCI_ATTR_DML_ROW_COUNT_ARRAY

Mode

READ

Description

Returns an array of row counts affected by each iteration of an array DML statement. The row count for iteration i can be obtained by looking up array[i-1].

Without OCI_BATCH_ERRORS mode, OCIStmtExecute() stops execution with the first erroneous iteration. In such a scenario, the array returned by the OCI_ATTR_DML_ROW_COUNT_ARRAY attribute only contains valid row counts up to and including the last successful iteration. When OCI_RETURN_ROW_COUNT_ARRAY mode is used in conjunction with OCI_BATCH_ERRORS mode, the returned row-count array contains the actual number of rows affected per successful iteration and 0 for iterations that resulted in errors.

This attribute works only when the statement is executed in mode OCI_RETURN_ROW_COUNT_ARRAY at the time of using OCIStmtExecute().

Use this attribute only after an array DML operation and while using OCI_RETURN_ROW_COUNT_ARRAY mode in OCIStmtExecute().

Any attempt to query this attribute after any other operation (other than an array DML) or without passing this mode will result in an OCI_ERROR (ORA-24349).

Attribute Data Type

ub8 *

Example

int deptarray[]={10,20,30}; 
int iters = 3;
ub8 *rowcounts;
ub4 rowCountArraySize; 
/*Statement prepare */ 
text *updatesal = (text *)"UPDATE EMP set sal = sal+100 where deptno = :dept"
OCIStmtPrepare2 ((OCISvcCtx *)svchp,(OCIStmt **)&stmthp,
(OCIError *)errhp, (text *)updatesal, (ub4)sizeof(updatesal)-1,
(oratext *)NULL, (ub4) 0, (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
/*Array bind*/
OCIBindByPos (stmthp, &bndhp, errhp, 1, deptarray,  sizeof(deptarray[0]),
         SQLT_INT, (ub2 *) 0, (ub2 *) 0, (ub4)   0, (ub4)   0, (ub4 *) 0,
         (ub4)   OCI_DEFAULT);
/* Pass new MODE for Array DML rowcounts; also, if an error occurred for any iteration and you want to get the number of rows updated for the rest of the iterations.*/
OCIStmtExecute(svchp, stmthp, errhp, iters,  (ub4) 0, 0, 0, OCI_BATCH_ERRORS | OCI_RETURN_ROWCOUNT_ARRAY);
OCIAttrGet (stmthp, (ub4) OCI_HTYPE_STMT,
            (ub8 *)&rowcounts, &rowCountArraySize,
            OCI_ATTR_DML_ROW_COUNT_ARRAY, errhp);

OCI_ATTR_ROWID

Mode

READ

Description

Returns the ROWID descriptor allocated with OCIDescriptorAlloc().

See Also:

Positioned Updates and Deletes and ROWID Descriptor

Attribute Data Type

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 nonscrollable statement handles.

Attribute Data Type

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_SQL_ID

Mode

READ

Dexcription

Gets the SQL_ID for a specific SQL statement from the server and makes it available on the client in a statement handle.

Attribute Data Type

ub4 *

Example

In an OCIStmtPrepare2(), specify OCI_PREP2_GET_SQL_ID as the mode. This OCI_PREP2_GET_SQL_ID mode should be ORed with any other mode. For example:

OCIStmtPrepare2((dvoid *)ctxptr->svchp, &stmthp,
                               (dvoid *)ctxptr->errhp,
                               insStmt, sizeof(insStmt),
                               (const oratext *)0, (ub4)0,
                               OCI_NTV_SYNTAX,
                               OCI_DEFAULT | OCI_PREP2_GET_SQL_ID);

You can do a bind or define operation and then execute on the statement.

The following code example shows how to obtain the SQL_ID.

  ub4         sqlidLen;
  oratext    *sqlid;
                 OCIAttrGet(stmthp, OCI_HTYPE_STMT,
                                 &sqlid, (ub4 *)&sqlidLen,
                                 OCI_ATTR_SQL_ID,
                                 ctxptr->errhp); 

OCI_ATTR_SQLFNCODE

Mode

READ

Description

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

Attribute Data Type

ub2 *

Notes

Table A-1 lists the SQL command codes.

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 Data Type

oratext *

OCI_ATTR_STMTCACHE_CBKCTX

Mode

READ/WRITE

Description

Used to get and set the application's opaque context on the statement handle. This context can be of any type that the application defines. It is primarily used for encompassing the bind and define buffer addresses.

Attribute Data Type

void *

OCI_ATTR_STMT_IS_RETURNING

Mode

READ

Description

Determines whether the given SQL Statement has a RETURNING INTO clause.

Attribute Data Type

ub1

Example

returning_into_clause = OCIAttrGet ( stmthp, OCI_HTYPE_STMT, (ub1*)&isReturning, NULL, OCI_ATTR_STMT_IS_RETURNING, errhp);

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 you are in the middle of a fetch-execute cycle, then you do not want to release the session handle for another statement execution. Valid values are:

• OCI_STMT_STATE_INITIALIZED

• OCI_STMT_STATE_EXECUTED

• OCI_STMT_STATE_END_OF_FETCH

Attribute Data Type

ub4 *

OCI_ATTR_STMT_TYPE

Mode

READ

Description

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

• OCI_STMT_SELECT

• OCI_STMT_UPDATE

• OCI_STMT_DELETE

• OCI_STMT_INSERT

• OCI_STMT_CREATE

• OCI_STMT_DROP

• OCI_STMT_ALTER

• OCI_STMT_BEGIN (PL/SQL statement)

• OCI_STMT_DECLARE (PL/SQL statement)

• OCI_STMT_CALL (PL/SQL statement)

• OCI_STMT_MERGE (PL/SQL statement)

Attribute Data Type

ub2 *

OCI_ATTR_UB8_ROW_COUNT (Recommended over OCI_ATTR_ROW_COUNT)

Mode

READ

Description

For SELECT statements, returns the cumulative number of rows fetched from a result set. For INSERT, UPDATE, and DELETE statements, this attribute returns the number of rows processed by the statement. The default value is 1.

For non-scrollable cursors, OCI_ATTR_UB8_ROW_COUNT is the total number of rows fetched into user buffers with the OCIStmtFrtch() or OCIStmtFetch2() calls issued since this statement handle was executed. For these non-scrollable cursors, this also represents the highest row number seen by the application.

If using the attribute OCI_ATTR_ROW_COUNT and the row count returned is larger than UB4MAXVAL, then one or both of the following errors may be returned:

ORA-03148. OCI_ATTR_ROW_COUNT cannot see row counts larger than UB4MAXVAL

Attribute Data Type

ub8 *

The following attributes are used for the bind handle.

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

Sets the number of characters in character type data.

See Also:

Buffer Expansion During OCI Binding

Attribute Data Type

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 causes 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 Data Type

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, the user must set the character set ID to OCI_UTF16ID (replaces the deprecated OCI_UC2SID, which is retained for backward compatibility). The bind value buffer is assumed to be a utext buffer, so 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 must 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 before setting OCI_ATTR_CHARSET_FORM causes unexpected results.

See Also:

Character Conversion in OCI Binding and Defining

Attribute Data Type

ub2 *

OCI_ATTR_COLLATION_ID

Mode

READ/WRITE

Description

Sets the derived collation of a placeholder expression corresponding to this bind handle in a SQL statement. The attribute is relevant only for bind variables with character data types.

You can set the OCI_ATTR_COLLATION_ID attribute on a bind variable handle to any of the supported collation IDs. Collation IDs of both named collations and pseudo-collations are allowed. The attribute value is passed to the server with other bind information and the corresponding bind variable reference, formally known as SQL placeholder expression, assumes the provided collation at the coercibility level 0. If the attribute value is OCI_COLLATION_NONE (the default value), the collation of the bind variable is USING_NLS_COMP at the coercibility level 4.

OCI does not check whether the collation is valid for a given data type of a bind variable. If OCI_ATTR_COLLATION_ID is set for a non-character data type variable, it is ignored by the server.

Collation of bind variables is currently ignored in PL/SQL expressions. For forward compatibility reasons, the OCI_ATTR_COLLATION_ID attribute should not be set for bind variables passed to an anonymous PL/SQL block, unless the variables are referenced exclusively in SQL statements.

Note:

You can use the SQL built-in functions NLS_COLLATION_ID and NLS_COLLATION_NAME to map between values of the attribute, which are collation IDs, and collation names used in SQL syntax.

See Also:

• Column Attributes

• Oracle Database Globalization Support Guide for information on how this set collation influences query processing

Attribute Data Type

ub4 *

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.

See Also:

About Using the OCI_ATTR_MAXCHAR_SIZE Attribute

Attribute Data Type

sb4 *

OCI_ATTR_MAXDATA_SIZE

Mode

READ/WRITE

Description

Sets the maximum number of bytes allowed in the buffer on the server side to accommodate client-side bind data after character set conversions.

See Also:

About Using the OCI_ATTR_MAXDATA_SIZE Attribute

Attribute Data Type

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 must be changed, first perform a rebind/redefine operation, and then reset the two attributes in order.

Attribute Data Type

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 must be changed, first perform a rebind/redefine operation, and then reset the two attributes in order.

Attribute Data Type

sb2 *

OCI_ATTR_ROWS_RETURNED

Mode

READ

Description

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

Attribute Data Type

ub4 *

The following attributes are used for the define handle.

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

This attribute is deprecated.

Sets the number of characters in 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 Data Type

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 causes 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 Data Type

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 must set the character set IDOTT to OCI_UTF16ID. The define value buffer is assumed to be a utext buffer, so 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 must 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 before setting OCI_ATTR_CHARSET_FORM causes unexpected results.

See Also:

Character Conversion in OCI Binding and Defining

Attribute Data Type

ub2 *

OCI_ATTR_LOBPREFETCH_LENGTH

Mode

READ/WRITE

Description

Specifies if the LOB length and the chunk size for the LOB locators should be prefetched along with the descriptor if the column is a LOB column. Setting it to TRUE will enable the prefetching and this attribute setting is also required for prefetching the LOB data using the attribute OCI_ATTR_LOBPREFETCH_SIZE.

Attribute Data Type

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 along with the descriptor. This requires the attribute OCI_ATTR_LOBPREFETCH_LENGTH to be set to TRUE.

Attribute Data Type

ub4 */ub4

OCI_ATTR_MAXCHAR_SIZE

Mode

WRITE

Description

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

See Also:

About Using the OCI_ATTR_MAXCHAR_SIZE Attribute

Attribute Data Type

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 must be changed, first perform a rebind/redefine operation, and then reset the two attributes in order.

Attribute Data Type

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 must be changed, first perform a rebind/redefine operation, and then reset the two attributes in order.

Attribute Data Type

sb2 *

The following attributes are used for the describe handle.

OCI_ATTR_PARAM

Mode

READ

Description

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

Attribute Data Type

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 Data Type

ub4 *

OCI_ATTR_SHOW_INVISIBLE_COLUMNS

Mode

WRITE

Description

This attribute requests OCIDescribeAny() to also get the metadata for invisible columns. You can use OCIAttrGet() to determine whether a column is invisible or not.

Attribute Data Type

boolean *

Example

boolean showInvisibleCols = TRUE;
ub1 colInvisible[MAX_COLS];
OCIAttrSet(descHandle, OCI_HTYPE_DESCRIBE, &showInvisibleCols, 0,
            OCI_ATTR_SHOW_INVISIBLE_COLUMNS, errHandle);
if (rc = OCIDescribeAny(svcHandle, errHandle, (dvoid*)table,
                        strlen(table), OCI_OTYPE_NAME, 1,
                        OCI_PTYPE_TABLE, descHandle))
{
  OCIHandleFree(descHandle, OCI_HTYPE_DESCRIBE);
  return OCI_ERROR;
}
 
/* Get the number of columns. */
 
OCIAttrGet(parHandle, OCI_DTYPE_PARAM, &nCols, 0,
           OCI_ATTR_NUM_COLS, errHandle);
 
/* Get the column list. */
 
OCIAttrGet(parHandle, OCI_DTYPE_PARAM, &lstHandle, 0,
           OCI_ATTR_LIST_COLUMNS, errHandle);
 
/* Loop through the columns. */
for (i = 1; i <= nCols; i++) 
{
  OCIParamGet(lstHandle, OCI_DTYPE_PARAM, errHandle,
              (dvoid*)&colHandle, i);
  OCIAttrGet(colHandle, OCI_DTYPE_PARAM, &colName[i-1], &len,
              OCI_ATTR_NAME, errHandle);
  OCIAttrGet(colHandle, OCI_DTYPE_PARAM, &(colType[i-1]), 0,
              OCI_ATTR_DATA_TYPE, errHandle);
  OCIAttrGet(colHandle, OCI_DTYPE_PARAM, &colInvisible[i-1], 0,
              OCI_ATTR_SHOW_INVISIBLE_COLUMNS, errHandle);
  if (colInvisible & OCI_ATTR_SHOW_INVISIBLE_COLUMNS)
     printf("Column is invisible\n");
}

The following attributes are used for the parameter descriptor.

This descriptor is returned by OCIShardInstancesGet() used only by custom pools, which essentially contains the instance name where the data matching the provided sharding key resides, and an indication if that shard is writable on that instance.

The following attributes are used for the shard instance descriptor.

OCI_ATTR_INSTNAME

Mode

READ

Description

This attribute can be used to find the shard instance name out of a shard instance descriptor that is filed by an OCIShardInstancesGet() call. This attribute can also be used on the service context to return the shard instance name for a given connection. When called as an event handle attribute, OCIAttrGet() retrieves the name of the instance that has been affected by this event. This is also a server handle attribute.

Attribute Data Type

oratext **

Example

 OCIAttrGet(shardInstance,
           (ub4) OCI_DTYPE_SHARD_INST,(dvoid *)&iName, (ub4 *)&iNameLen,
           OCI_ATTR_INSTNAME, (OCIError *)errhp);

OCI_ATTR_SHARD_HAS_WRITABLECHUNK

Mode

READ

Description

Returns TRUE if the shard instance has writable chunks. For custom pool implementations, this helps the pool to determine if a connection to that particular shard instance can be dispensed. If the application can work with read only shards instead of writable chunks, the pool can dispense it; otherwise, it can implement a retrial logic to try OCIShardInstancesGet() until it returns shard instance information having writable chunks. This feature is helpful during chunk migrations.

Attribute Data Type

boolean *

The following attributes are used for the parameter descriptor.

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, OCILobWrite2() or OCILobWrite() (deprecated) 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 the address of a ub4 that has a value of 0; for example, declare the following:

ub4 lobEmpty = 0

Then they should pass the address: &lobEmpty.

Attribute Data Type

ub4 *

OCI_ATTR_LOB_REMOTE

Mode

READ

Description

Determines whether the LOB locator belongs to a local database table or a remote database table. The value TRUE indicates that the LOB locator is from a remote database table. The application must fetch the LOB descriptor from the database before using this attribute.

Only the server can set this value. If an application tries to set this attribute, then an ORA-24315 error is raised.

Attribute Data Type

boolean

OCI_ATTR_LOB_TYPE

Mode

READ

Description

Gets the LOB type from the LOB descriptor.

Attribute Data Type

ub2

The following attributes are used for complex objects.

The following attributes are used for the database advanced queuing descriptor.

The following attributes are used for the subscription handle.

OCI_ATTR_SERVER_DNS

Mode

READ/WRITE

Description

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

Attribute Data Type

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 must be set before the subscription handle can be passed into the registration call OCISubscriptionRegister().

Attribute Data Type

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, see the section on using OCI subscription handle attributes for CQN in Oracle Database Development Guide.

Attribute Data Type

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 must be set before the subscription handle can be passed into the registration call OCI Subscription Register().

Attribute Data Type

void *

OCI_ATTR_SUBSCR_HOSTADDR

Mode

READ/WRITE

Description

Before registering for notification using OCISubscriptionRegister(), specify the client IP (in either IPv4 or IPv6 format) of the listening endpoint of the OCI notification client to which the notification is sent. Enter either IPv4 addresses in dotted decimal format, for example, 192.0.2.34, or IPv6 addresses in hexadecimal format, for example, 2001:0db8:0000:0000:0217:f2ff:fe4b:4ced.

See Also:

Oracle Database Net Services Administrator's Guide for more information about the IPv6 format for IP addresses

Attribute Data Type

text *

Example

/* Set notification client address*/
text ipaddr[16] = "192.0.2.34";
(void) OCIAttrSet((dvoid *) envhp, (ub4) OCI_HTYPE_ENV,
                  (dvoid *) ipaddr, (ub4) strlen(ipaddr),
                  (ub4) OCI_ATTR_SUBSCR_HOSTADDR, errhp);

OCI_ATTR_SUBSCR_IPADDR

Mode

READ/WRITE

Description

The client IP address (IPv4 or IPv6) on which an OCI client registered for notification listens, to receive notifications. For example, IPv4 address in dotted decimal format such as 192.1.2.34 or IPv6 address in hexadecimal format such as 2001:0db8:0000:0000:0217:f2ff:fe4b:4ced.

See Also:

Oracle Database Net Services Administrator's Guide for more information about the IPv6 format for IP addresses

Attribute Data Type

oratext *

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 must be specified as it is not assumed that the name is NULL-terminated. This is important because the name could contain multibyte characters.

Clients can 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 Data Type

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 Data Type

ub4 *

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.

Note:

OCI_OBJECT mode is required when using grouping notifications.

Attribute Data Type

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_NTFN_GROUPING_FOREVER to send grouping notifications forever.

Attribute Data Type

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 Data Type

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 Data Type

ub1 *

OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE

Mode

READ/WRITE

Description

Specifies the value 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 Data Type

ub4 *

OCI_ATTR_SUBSCR_PAYLOAD

Mode

READ/WRITE

Description

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

Attribute Data Type

ub1 *

OCI_ATTR_SUBSCR_QOSFLAGS

Mode

READ/WRITE

Description

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

• OCI_SUBSCR_QOS_RELIABLE - Reliable. If the database fails, it does not lose notification. Not supported for nonpersistent queues or buffered messaging.

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

• OCI_SUBSCR_QOS_PAYLOAD - Payload notification.

Attribute Data Type

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 email address (for example, xyz@oracle.com) to which the notification is sent. The validity of the email 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 is invoked when there is a notification. The subscriber must have appropriate permissions on the procedure for it to be executed.

See Also:

Notification Procedure for information about procedure definition

Attribute Data Type

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.

For event notification in XML presentation, set this attribute to OCI_SUBSCR_PRES_XML. XML presentation is limited to 2000 bytes. Otherwise, leave it unset or set it to OCI_SUBSCR_PRES_DEFAULT.

Attribute Data Type

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:

• OCI_SUBSCR_PROTO_OCI

• OCI_SUBSCR_PROTO_MAIL

• OCI_SUBSCR_PROTO_SERVER

• OCI_SUBSCR_PROTO_HTTP

If an OCI client wants to receive the event notification, then you should set this attribute to OCI_SUBSCR_PROTO_OCI.

If you want an email 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 an 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 Data Type

ub4 *

OCI_ATTR_SUBSCR_TIMEOUT

Mode

READ/WRITE

Description

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

Attribute Data Type

ub4 *

The following attributes are used for the direct path loading handle.