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:
For each handle type, the attributes that can be read or changed are listed. Each attribute listing includes the following information:
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().
This is a description of the purpose of the attribute.
This is the data type of the attribute. If necessary, a distinction is made between the data type for READ and WRITE modes.
In some cases, only certain values are allowed, and they are listed here.
In some cases an example is included.
The following attributes are used for the environment handle.
OCI_ATTR_ALLOC_DURATION
OCI_ATTR_BIND_DN
OCI_ATTR_CACHE_ARRAYFLUSH
READ/WRITE
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"
OCI_ATTR_CACHE_MAX_SIZE
READ/WRITE
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:
OCI_ATTR_CACHE_OPT_SIZE
OCI_ATTR_ENV_CHARSET_ID
READ
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.
ub2 *
OCI_ATTR_ENV_NCHARSET_ID
READ
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.
ub2 *
OCI_ATTR_ENV_NLS_LANGUAGE
OCI_ATTR_ENV_NLS_TERRITORY
OCI_ATTR_ENV_UTF16
OCI_ATTR_EVTCBK
OCI_ATTR_EVTCTX
OCI_ATTR_HEAPALLOC
OCI_ATTR_LDAP_AUTH
READ/WRITE
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.
ub2 */ub2
OCI_ATTR_LDAP_CRED
OCI_ATTR_LDAP_CTX
OCI_ATTR_LDAP_HOST
OCI_ATTR_LDAP_PORT
OCI_ATTR_OBJECT
OCI_ATTR_PINOPTION
READ/WRITE
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.
OCIPinOpt */OCIPinOpt
OCI_ATTR_OBJECT_NEWNOTNULL
OCI_ATTR_OBJECT_DETECTCHANGE
OCI_ATTR_PIN_DURATION
OCI_ATTR_SHARED_HEAPALLOC
READ
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);
ub4 *
OCI_ATTR_WALL_LOC
The following attributes are used for the error handle.
OCI_ATTR_DML_ROW_OFFSET
OCI_ATTR_ERROR_IS_RECOVERABLE
The following attributes are used for service context handle.
OCI_ATTR_ENV
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
READ
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.
ub1 *
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
READ
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.
ub4 *
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
READ
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.
ub4 *
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
OCI_ATTR_SESSION
OCI_ATTR_STMTCACHE_CBK
READ/WRITE
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.
sword (*OCICallbackStmtCache)(void *ctx, OCIStmt *stmt, ub4 mode)
OCI_ATTR_STMTCACHESIZE
READ/WRITE
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.
ub4 */ ub4
OCI_ATTR_TRANS
OCI_ATTR_VARTYPE_MAXLEN_COMPAT
The following attributes are used for the server handle.
See Also:
The following event handle attributes are also available for the server handle:
OCI_ATTR_ACCESS_BANNER
OCI_ATTR_BREAK_ON_NET_TIMEOUT
OCI_ATTR_ENV
OCI_ATTR_EXTERNAL_NAME
READ/WRITE
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.
oratext **/ oratext *
OCI_ATTR_FOCBK
OCI_ATTR_INTERNAL_NAME
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
READ
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.
ub1 *
OCI_ATTR_NONBLOCKING_MODE
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.
See Also:
OCI_ATTR_RECEIVE_TIMEOUT
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.
OCI_ATTR_SEND_TIMEOUT
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.
OCI_ATTR_SERVER_GROUP
OCI_ATTR_SERVER_STATUS
READ
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.
ub4 *
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
OCI_ATTR_USER_MEMORY
READ
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:
See Also:
"OCIXStreamOutLCRReceive()" for more information about using the following attributes
OCI_ATTR_FIXUP_CALLBACK
READ/WRITE
Specifies on the authentication handle attribute the callback passed to OCISessionGet() for applications not using an OCISessionPool or using custom pools. For applications using OCISessionPool, this attribute must be set on the authentication handle, which in turn must be set on the session pool handle as the attribute OCI_ATTR_SPOOL_AUTH. See Session Pool Handle Attributes and PL/SQL Callback for Session State Fix Up for more information.
oratext * to be provided in the format schma.package.callback_function
These attributes also apply to the user session handle.
See Also:
The following user session handle attributes also apply to the authentication information handle.
OCI_ATTR_ACTION
WRITE
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.
oratext *
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.
OCI_ATTR_APPCTX_LIST
Note:
This attribute is not supported with database resident connection pooling.
OCI_ATTR_APPCTX_NAME
Note:
This attribute is not supported with database resident connection pooling.
OCI_ATTR_APPCTX_SIZE
Note:
This attribute is not supported with database resident connection pooling.
OCI_ATTR_APPCTX_VALUE
Note:
This attribute is not supported with database resident connection pooling.
OCI_ATTR_AUDIT_BANNER
OCI_ATTR_CALL_TIME
OCI_ATTR_CERTIFICATE
WRITE
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.
ub1 *
OCI_ATTR_CLIENT_IDENTIFIER
WRITE
Specifies the user identifier in the session handle. Can be up to 64 bytes long. The value is automatically truncated if the supplied input is more than 64 bytes. It can contain the user name, but do not include the password for security reasons. The first character of the identifier should not be ':'. If it is, the behavior is unspecified.
oratext *
OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"janedoe",
(ub4)strlen("janedoe"), OCI_ATTR_CLIENT_IDENTIFIER,
error_handle);
OCI_ATTR_CLIENT_INFO
OCI_ATTR_COLLECT_CALL_TIME
OCI_ATTR_CONNECTION_CLASS
OCI_ATTR_CURRENT_SCHEMA
READ/WRITE
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 that you then enter.
When a client using this attribute communicates with a server that has a software release earlier than Oracle Database 10g Release 2, the OCIAttrSet() call is ignored. This attribute is also readable by OCIAttrGet().
oratext */oratext *
text schema[] = "hr";
err = OCIAttrSet( (void ) mysessp, OCI_HTYPE_SESSION, (void *)schema,
(ub4)strlen( (char *)schema), OCI_ATTR_CURRENT_SCHEMA, (OCIError *)myerrhp);
OCI_ATTR_DBOP
Write
The name of the database operation set by the client application to be monitored in the database. When you want to end monitoring the current running database operation, set the value to NULL. Can be up to 30 bytes long.
oratext *
(void) OCIAttrSet((dvoid *) sess1, (ub4) OCI_HTYPE_SESSION,
(dvoid *) dbopname, (ub4) strlen((char *)dbopname),
(ub4) OCI_ATTR_DBOP, errhp);
OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE
OCI_ATTR_DISTINGUISHED_NAME
OCI_ATTR_DRIVER_NAME
READ/WRITE
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 a V$SESSION_CONNECT_INFO or GV$SESSION_CONNECT_INFO view. 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.
oratext **/oratext *
...
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_EDITION
OCI_ATTR_INITIAL_CLIENT_ROLES
OCI_ATTR_LTXID
READ
This attribute is defined for the session handle and is used to override the default LTXID (logical transaction ID). Applications that associate the logical session with the web user may want to explicitly attach the LTXID to a physical session and explicitly detach the LTXID when the request is complete.
In READ mode, this attribute is used to retrieve the LTXID embedded in the OCISession handle.
ub1 * (with length; value is copied; is really a ub1 array)
OCI_ATTR_MAX_OPEN_CURSORS
READ
The maximum number of SQL statements that can be opened in one session. On the server's parameter file, this value is set using the parameter open_cursors. The OCI user should leave some threshold and not reach this limit because the server can also open internal statements (cursors) as part of processing user calls. Applications can use this attribute to limit the number of statement handles opened on a given session. This attribute returns a proper value only when connected to a 12.1 server or later.
If the cursors in the server session exceed the open cursor setting, then the server returns an error to the client saying that the value for max cursors is exceeded.
Also, note that this value should only be looked at from the session handle after an OCISessionGet() or equivalent login call has been done.
ub4 *
OCIAttrGet((void *)usrhp, OCI_HTYPE_SESSION, (void *)&ub4localvariable, (ub4 *)0, OCI_ATTR_MAX_OPEN_CURSORS, errhp);
OCI_ATTR_MIGSESSION
READ/WRITE
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.
See Also:
OCI_ATTR_MODULE
WRITE
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 use NULL if there is no new module. Can be up to 48 bytes long.
oratext *
OCIAttrSet(session, OCI_HTYPE_SESSION,(void *)"add_employee",
(ub4)strlen("add_employee"), OCI_ATTR_MODULE, error_handle);
OCI_ATTR_ORA_DEBUG_JDWP
WRITE
Specifies the external debugger's location the database session is to connect to after logon. This allows the user to initiate debugging of the database application.
The format of the attribute is a list of parameter names and values separated by semi-colons. The parameters will be passed to the DBMS_ DEBUG_JDWP_CUSTOM.CONNECT_DEBUGGER package API to connect the database session to the debugger. The parameter name can be a quoted or unquoted PL/SQL identifier. The parameter value is a character string, either quoted by single-quotes, or unquoted, which is terminated by a semi-colon. To escape a single quote in a quoted string, use two consecutive single quotes. No space is allowed anywhere between the parameter names and their values.
The attribute should contain at least the host and port parameters that specify the Internet Protocol dotted address or host name of the computer the debugger is running, and the TCP port number the debugger is listening to for debug connections.
oratext *
OCIAttrSet(session,
OCI_HTYPE_SESSION,
(void *)"janedoe",
(ub4)strlen("janedoe"),
OCI_ATTR_CLIENT_IDENTIFIER,
error_handle);
OCI_ATTR_PASSWORD
OCI_ATTR_PROXY_CLIENT
OCI_ATTR_PROXY_CREDENTIALS
OCI_ATTR_PURITY
READ/WRITE
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(), then 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.
ub4 */ub4
OCI_ATTR_SESSION_STATE
READ/WRITE
Specifies the current state of the database session. Set to OCI_SESSION_STATEFUL if the session is required to perform a database task. If the application is no longer dependent on the current session for subsequent database activity, set to OCI_SESSION_STATELESS. This attribute is currently applicable only when connected to a Database Resident Connection Pool. It should be used if the application does custom session pooling and does not use OCISessionPool().
ub1 */ ub1
OCI_ATTR_SHARDING_KEY
WRITE
For the shard and chunk, specifies the sharding key for the connection request from an OCI session pool or standalone connection.
The OCIShardingKey * supplied to OCIAttrSet() needs to be created with OCIDescriptorAlloc() specifying the sharding descriptor and then using as many calls as is needed to OCIShardingKeyColumnAdd() to create the compound sharding key. See OCIShardingKeyColumnAdd() for more information and an example.
For custom pools, this attribute associates a sharding key to a given connection.
OCIShardingKey *
/* Allocate the super sharding key descriptor. */
OCIDescriptorAlloc(envhp,(dvoid **)&shardKey,
OCI_DTYPE_SHARDING_KEY, 0,(dvoid **)0)))
text *name = “KK”;
text *gname = “GOLD”;
int empid = 150;
/* Add all the columns of the key to form the final shard key. */
OCIShardingKeyColumnAdd(shardKey,(ub1*)&empid, sizeof(empid),
SQLT_INT, errhp, OCI_DEFAULT);
OCIShardingKeyColumnAdd(shardKey, name, strlen(name),
SQLT_CHAR, errhp, OCI_DEFAULT));
OCIShardingKey *shardKey;
OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
shardKey, sizeof(shardKey),
OCI_ATTR_SHARDING_KEY, errhp);
OCI_ATTR_SHARDING_KEY_B64
WRITE
Gets the base64 representation of sharding key and super sharding key values for diagnostic purposes.
Oratext *
char * skeyValue;
ub4 skeyValueLen;
OCIAttrGet((dvoid *) OCIShardingKey,
(ub4) OCI_DTYPE_SHARDING_KEY,
(dvoid *) &skeyValue,
(ub4 *) &skeyValueLen,
OCI_ATTR_SHARDING_KEY_B64,
(OCIError * ) errhp);
OCI_ATTR_SUPER_SHARDING_KEY
WRITE
For the shard and group of chunks, specifies the super sharding key for the connection request from an OCI session pool or standalone connection.
The OCIShardingKey * supplied to OCIAttrSet() needs to be created with OCIDescriptorAlloc() specifying the sharding descriptor and then using as many calls as is needed to OCIShardingKeyColumnAdd() to create the compound shard key. See OCIShardingKeyColumnAdd() for more information and an example.
For custom pools, this attribute associates a shard group key to a given connection.
OCIShardingKey *
/* Allocate the sharding key descriptor. */
OCIDescriptorAlloc(envhp,(dvoid **)&shardGroupKey,
OCI_DTYPE_SHARDING_KEY, 0, (dvoid **)0));
/* Add the column of the key to form the final super sharding key. */
OCIShardingKeyColumnAdd(shardGroupKey, errhp, gname, strlen(gname),
SQLT_CHAR, OCI_DEFAULT));
OCIShardingKey *shardGroupKey;
OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
shardGroupKey, sizeof(shardGroupKey),
OCI_ATTR_SUPER_SHARDING_KEY, errhp));
OCI_ATTR_TRANS_PROFILE_FOREIGN
READ
Specifies whether a SQL translation profile for translation of foreign SQL syntax is set in the current session or not.
boolean
status = OCIAttrGet(authp,
OCI_HTYPE_SESSION,
(void *)&foreign_sql_syntax,
(ub4 *)NULL,
OCI_ATTR_TRANS_PROFILE_FOREIGN,
errhp);
OCI_ATTR_TRANSACTION_IN_PROGRESS
READ
If TRUE, then the referenced session has a currently active transaction.
If FALSE, then the referenced session does not have a currently active transaction.
boolean *
{ boolean txnInProgress;
OCIAttrGet(usrhp, OCI_HTYPE_SESSION,
&txnInProgress, (ub4 *)0,
OCI_ATTR_TRANSACTION_IN_PROGRESS,
errhp);
}
OCI_ATTR_USERNAME
The following attributes are used for the administration handle.
OCI_ATTR_ADMIN_PFILE
READ/WRITE
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.
oratext */oratext *
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 remain active.
OCI_ATTR_CONN_NOWAIT
READ/WRITE
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.
ub1 */ub1
OCI_ATTR_CONN_BUSY_COUNT
OCI_ATTR_CONN_OPEN_COUNT
OCI_ATTR_CONN_MIN
OCI_ATTR_CONN_MAX
OCI_ATTR_CONN_INCR
The following attributes are used for the session pool handle.
OCI_ATTR_SPOOL_AUTH
WRITE
To make pre-session creation attributes effective on the sessions being retrieved from the session pool, this attribute can be set on the session pool handle. Currently only the following attributes can be set on this OCIAuthInfo handle:
OCI_ATTR_DRIVER_NAME
OCI_ATTR_EDITION
OCI_ATTR_FIXUP_CALLBACK
If any other attributes are set on the OCIAuthInfo handle and the OCIAuthInfo handle is set on the session pool handle, an error results. Moreover, the OCIAuthInfo handle should be set on the session pool handle only before calling OCISessionPoolCreate() with the session pool handle. Setting it after OCISessionPoolCreate() results in an error.
OCIAuthInfo *
OCI_ATTR_SPOOL_BUSY_COUNT
OCI_ATTR_FOCBK
READ/WRITE
On OCIAttrSet(), defines a TAF callback and context to be associated with each session in the OCI session pool.
On OCIAttrGet(), populates the OCIFocbkStruct with the TAF callback and context defined for the session pool.
Note:
This attribute is already supported for handles of type OCIServer and OCICPool.
A TAF callback set on the server handle will override the callback set on the session pool.
OCIFocbkStruct *
OCI_ATTR_SPOOL_GETMODE
READ/WRITE
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 reached the maximum. Values are:
OCI_SPOOL_ATTRVAL_WAIT - The thread waits and blocks until a session is freed. This is the default value.
OCI_SPOOL_ATTRVAL_TIMEDWAIT - Keep trying internally for a free session until the time out set by OCI_ATTR_SPOOL_WAIT_TIMEOUT expires.
OCI_SPOOL_ATTRVAL_NOWAIT - An error is returned.
OCI_SPOOL_ATTRVAL_FORCEGET - A new session is created even though all the sessions are busy and the maximum number of sessions has been reached. OCISessionGet() returns a warning. In this case, if new sessions are created that have exceeded the maximum, OCISessionGet() returns a warning.
Note that if this value is set, it is possible that there can be an attempt to create more sessions than can be supported by the instance of the Oracle database. In this case, the server returns the following error:
ORA 00018 - Maximum number of sessions exceeded
In this case, the error is propagated to the session pool user.
When read, the appropriate attribute value is returned.
OCI_ATTR_SPOOL_INCR
OCI_ATTR_SPOOL_MAX
OCI_ATTR_SPOOL_MAX_LIFETIME_SESSION
READ/WRITE
This attribute sets the lifetime (in seconds) for all the sessions in the pool. Sessions in the pool are terminated when they have reached their lifetime. In the case when OCI_ATTR_SPOOL_TIMEOUT is also set, the session will be terminated if either the idle time out happens or the max lifetime setting is exceeded.
ub4 */ ub4
OCI_ATTR_SPOOL_MIN
OCI_ATTR_SPOOL_OPEN_COUNT
OCI_ATTR_SPOOL_STMTCACHESIZE
READ/WRITE
Sets the default statement cache size to this value for each of the sessions in a session pool. 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.
See Also:
ub4 */ ub4
OCI_ATTR_SPOOL_TIMEOUT
READ/WRITE
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. See OCI_ATTR_SPOOL_MAX_LIFETIME_SESSION for more information.
ub4 */ ub4
OCI_ATTR_SPOOL_WAIT_TIMEOUT
READ/WRITE
This is the time out applied for the OCISessionGet() call while waiting for a free session, when the OCI_ATTR_SPOOL_GETMODE property is set to OCI_SPOOL_ATTRVAL_TIMEDWAIT. This is also applicable in case of sharding, where the OCISessionGet() call waits for a free session to an instance with writable chunks.
ub4 */ ub4
The following attributes are used for the transaction handle.
OCI_ATTR_TRANS_NAME
OCI_ATTR_TRANS_TIMEOUT
OCI_ATTR_XID
The following attributes are used for the statement handle.
OCI_ATTR_BIND_COUNT
READ
Returns the number of bind positions on the statement handle.
ub4 *
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
WRITE
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.
OCISubscription *
/* Associate the statement with the subscription handle */
OCIAttrSet (stmthp, OCI_HTYPE_STMT, subscrhp, 0,
OCI_ATTR_CHNF_REGHANDLE, errhp);
See Also:
OCI_ATTR_CQ_QUERYID
OCI_ATTR_CURRENT_POSITION
OCI_ATTR_ENV
OCI_ATTR_FETCH_ROWID
READ/WRITE
Specifies that the ROWIDs are fetched after doing a define at position 0, and a SELECT...FOR UPDATE statement.
boolean */boolean
See Also:
OCI_ATTR_IMPLICIT_RESULT_COUNT
OCI_ATTR_NUM_DML_ERRORS
OCI_ATTR_PARAM_COUNT
READ
Gets the number of columns in the select-list for the statement associated with the statement handle.
ub4 *
...
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
OCI_ATTR_PREFETCH_MEMORY
WRITE
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.
ub4 *
OCI_ATTR_PREFETCH_ROWS
OCI_ATTR_ROW_COUNT
READ
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.
ub4 *
OCI_ATTR_DML_ROW_COUNT_ARRAY
READ
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).
ub8 *
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
OCI_ATTR_ROWS_FETCHED
READ
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.
ub4 *
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
READ
Gets the SQL_ID for a specific SQL statement from the server and makes it available on the client in a statement handle.
ub4 *
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
READ
Returns the function code of the SQL command associated with the statement.
ub2 *
Table A-1 lists the SQL command codes.
Table A-1 Function Code of the SQL Command Associated with the SQL Statement
| Function Code | SQL Statement | Function Code | SQL Statement | Function Code | SQL Statement |
|---|---|---|---|---|---|
|
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
OCI_ATTR_STMTCACHE_CBKCTX
OCI_ATTR_STMT_IS_RETURNING
OCI_ATTR_STMT_STATE
READ
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
OCI_ATTR_STMT_TYPE
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_ATTR_UB8_ROW_COUNT (Recommended over OCI_ATTR_ROW_COUNT)
READ
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
ub8 *
The following attributes are used for the bind handle.
OCI_ATTR_CHAR_COUNT
OCI_ATTR_CHARSET_FORM
READ/WRITE
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.
ub1 *
OCI_ATTR_CHARSET_ID
READ/WRITE
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 must set the character set ID to OCI_UTF16ID. 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:
OCI_ATTR_MAXCHAR_SIZE
OCI_ATTR_MAXDATA_SIZE
OCI_ATTR_PDPRC
WRITE
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.
ub2 *
OCI_ATTR_PDSCL
WRITE
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.
sb2 *
OCI_ATTR_ROWS_RETURNED
The following attributes are used for the define handle.
OCI_ATTR_CHAR_COUNT
WRITE
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.
ub4 *
OCI_ATTR_CHARSET_FORM
READ/WRITE
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.
ub1 *
OCI_ATTR_CHARSET_ID
READ/WRITE
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:
OCI_ATTR_LOBPREFETCH_LENGTH
READ/WRITE
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.
OCI_ATTR_LOBPREFETCH_SIZE
OCI_ATTR_MAXCHAR_SIZE
OCI_ATTR_PDPRC
WRITE
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.
ub2 *
OCI_ATTR_PDSCL
WRITE
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.
sb2 *
The following attributes are used for the describe handle.
OCI_ATTR_PARAM
READ
Points to the root of the description. Used for subsequent calls to OCIAttrGet() and OCIParamGet().
ub4 *
OCI_ATTR_PARAM_COUNT
OCI_ATTR_SHOW_INVISIBLE_COLUMNS
WRITE
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.
boolean *
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.
For a detailed list of parameter descriptor attributes, see Describing Schema Metadata.
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
READ
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.
oratext **
OCIAttrGet(shardInstance,
(ub4) OCI_DTYPE_SHARD_INST,(dvoid *)&iName, (ub4 *)&iNameLen,
OCI_ATTR_INSTNAME, (OCIError *)errhp);
OCI_ATTR_SHARD_HAS_WRITABLECHUNK
READ
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.
boolean *The following attributes are used for the parameter descriptor.
OCI_ATTR_LOBEMPTY
WRITE
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.
ub4 *
OCI_ATTR_LOB_REMOTE
READ
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.
booleanThe following attributes are used for complex objects.
See Also:
OCI_ATTR_COMPLEXOBJECT_LEVEL
OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE
The following attributes are used for the streams advanced queuing descriptor.
The following attributes are properties of the OCIAQEnqOptions descriptor.
OCI_ATTR_MSG_DELIVERY_MODE
WRITE
The enqueue call can enqueue a persistent or buffered message into a queue, by setting the OCI_ATTR_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.
ub2
OCI_ATTR_RELATIVE_MSGID
READ/WRITE
This feature is deprecated and may be removed in a future release.
Specifies the message identifier of the message that 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.
OCIRaw *
OCI_ATTR_SEQUENCE_DEVIATION
READ/WRITE
This feature is deprecated for new applications, but it is retained for compatibility.
It specifies whether the message being enqueued should be dequeued before other messages in the queue.
ub4
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_TRANSFORMATION
OCI_ATTR_VISIBILITY
READ/WRITE
Specifies the transactional behavior of the enqueue request.
ub4
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.
The following attributes are properties of the OCIAQDeqOptions descriptor.
OCI_ATTR_CONSUMER_NAME
OCI_ATTR_CORRELATION
READ/WRITE
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 multiple messages satisfy the pattern, the order of dequeuing is undetermined.
oratext *
OCI_ATTR_DEQ_MODE
READ/WRITE
Specifies the locking behavior associated with the dequeue.
ub4
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
OCI_ATTR_DEQCOND
READ/WRITE
This attribute is a Boolean expression similar to the WHERE clause of a SQL query. This Boolean expression can include conditions on message properties, user data properties (object payloads only), and PL/SQL or SQL functions.
To specify dequeue conditions on a message payload (object payload), use attributes of the object type in clauses. You must prefix each attribute with tab.user_data as a qualifier to indicate the specific column of the queue table that stores the payload.
The attribute cannot exceed 4000 characters. If multiple messages satisfy the dequeue condition, then the order of dequeuing is indeterminate, and the sort order of the queue is not honored.
oratext *
checkerr(errhp, OCIAttrSet(deqopt, OCI_DTYPE_AQDEQ_OPTIONS,
(dvoid *)"tab.priority between 2 and 4" ,
strlen("tab.priority between 2 and 4"),
OCI_ATTR_DEQCOND, errhp));
OCI_ATTR_MSG_DELIVERY_MODE
WRITE
You can specify the dequeue call to dequeue persistent, buffered, or both kinds of messages from a queue, by setting the OCI_ATTR_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.
ub2
OCI_ATTR_NAVIGATION
READ/WRITE
Specifies the position of the message that is retrieved. First, the position is determined. Second, the search criterion is applied. Finally, the message is retrieved.
ub4
The only valid values are:
OCI_DEQ_FIRST_MSG - Retrieves the first available message that matches the search criteria. This resets the position to the beginning of the queue.
OCI_DEQ_NEXT_MSG - Retrieves the next available message that matches the search criteria. If the previous message belongs to a message group, AQ retrieves the next available message that 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_MULTI_GROUP - Indicates that a call to OCIAQDeqArray() resets 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, is defined. All messages belonging to the same transaction group have the same value for this message property.
OCI_DEQ_NEXT_MSG_MULTI_GROUP - Indicates that a call to OCIAQDeqArray() dequeues 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, is defined. All messages belonging to the same transaction group have the same value for this message property.
OCI_ATTR_TRANSFORMATION
OCI_ATTR_VISIBILITY
READ/WRITE
Specifies whether the new message is dequeued as part of the current transaction. The visibility parameter is ignored when using the BROWSE mode.
ub4
The only valid values are:
OCI_DEQ_ON_COMMIT - The dequeue is part of the current transaction. This is the default.
OCI_DEQ_IMMEDIATE - The dequeued message is not part of the current transaction. It constitutes a transaction on its own.
OCI_ATTR_WAIT
READ/WRITE
Specifies the wait time if no message is currently available that matches the search criteria. This parameter is ignored if messages in the same group are being dequeued.
ub4
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.
The following attributes are properties of the OCIAQMsgProperties descriptor.
OCI_ATTR_ATTEMPTS
OCI_ATTR_CORRELATION
OCI_ATTR_DELAY
READ/WRITE
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 message ID (msgid) overrides the delay specification. A message enqueued with delay set is 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 the delay is set by the producer who enqueues the message.
sb4
Any sb4 value is valid, but the following predefined constant is available:
OCI_ATTR_ENQ_TIME
OCI_ATTR_EXCEPTION_QUEUE
READ/WRITE
Specifies the name of the queue to which the message is moved 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 is moved to the default exception queue associated with the queue table, and a warning is logged in the alert file. If the default exception queue is used, the parameter returns a NULL value at dequeue time.
This attribute must refer to a valid queue name.
oratext *
OCI_ATTR_EXPIRATION
READ/WRITE
Specifies the expiration of the message. It determines, in seconds, how long 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 is moved to the exception queue in the EXPIRED state.
sb4
Any sb4 value is valid, but the following predefined constant is available:
OCI_ATTR_MSG_DELIVERY_MODE
READ
After a dequeue call, the OCI client can read the OCI_ATTR_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.
ub2
OCI_ATTR_MSG_STATE
READ
Specifies the state of the message at the time of the dequeue. This parameter cannot be set at enqueue time.
ub4
Only the following values 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_ORIGINAL_MSGID
READ/WRITE
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.
OCIRaw *
OCI_ATTR_PRIORITY
OCI_ATTR_RECIPIENT_LIST
OCI_ATTR_SENDER_ID
OCI_ATTR_TRANSACTION_NO
READ
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.
oratext *
The following attributes are properties of the OCIAQAgent descriptor.
OCI_ATTR_AGENT_ADDRESS
OCI_ATTR_AGENT_NAME
OCI_ATTR_AGENT_PROTOCOL
The following attributes are used for the subscription handle.
OCI_ATTR_SERVER_DNS
OCI_ATTR_SUBSCR_CALLBACK
READ/WRITE
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().
ub4 (void *, OCISubscription *, void *, ub4, void *, ub4)
OCI_ATTR_SUBSCR_CQ_QOSFLAGS
WRITE
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.
ub4 *
OCI_ATTR_SUBSCR_CTX
READ/WRITE
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().
void *
OCI_ATTR_SUBSCR_HOSTADDR
READ/WRITE
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
text *
/* 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
READ/WRITE
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
oratext *
OCI_ATTR_SUBSCR_NAME
READ/WRITE
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.
oratext *
OCI_ATTR_SUBSCR_NAMESPACE
READ/WRITE
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.
ub4 *
Note:
OCI_OBJECT mode is required when using grouping notifications.
OCI_ATTR_SUBSCR_NTFN_GROUPING_CLASS
READ/WRITE
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.
ub1 *
OCI_ATTR_SUBSCR_NTFN_GROUPING_REPEAT_COUNT
OCI_ATTR_SUBSCR_NTFN_GROUPING_START_TIME
OCI_ATTR_SUBSCR_NTFN_GROUPING_TYPE
READ/WRITE
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.
ub1 *
OCI_ATTR_SUBSCR_NTFN_GROUPING_VALUE
READ/WRITE
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.
ub4 *
OCI_ATTR_SUBSCR_PAYLOAD
READ/WRITE
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.
ub1 *
OCI_ATTR_SUBSCR_PORTNO
OCI_ATTR_SUBSCR_QOSFLAGS
READ/WRITE
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.
ub4 *
OCI_ATTR_SUBSCR_RECPT
READ/WRITE
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
OCI_ATTR_SUBSCR_RECPTPRES
READ/WRITE
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.
ub4
OCI_ATTR_SUBSCR_RECPTPROTO
READ/WRITE
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().
OCI_ATTR_SUBSCR_TIMEOUT
The following attributes are used for continuous query notification.
OCI_ATTR_CHNF_CHANGELAG
OCI_ATTR_CHNF_OPERATIONS
WRITE
Used to filter notifications based on operation type.
ub4 *
See Also:
About Continuous Query Notification for details about the flag values
OCI_ATTR_CHNF_ROWIDS
OCI_ATTR_CHNF_TABLENAMES
The following attributes are used for the continuous query notification descriptor.
OCI_ATTR_CHDES_DBNAME
OCI_ATTR_CHDES_NFTYPE
READ
Flags describing the notification type.
ub4 *
See Also:
About Continuous Query Notification for the flag values
OCI_ATTR_CHDES_ROW_OPFLAGS
OCI_ATTR_CHDES_ROW_ROWID
OCI_ATTR_CHDES_TABLE_CHANGES
READ
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 that has the attributes that begin with OCI_ATTR_CHDES_TABLE. See the following entries.
OCIColl **
OCI_ATTR_CHDES_TABLE_NAME
OCI_ATTR_CHDES_TABLE_OPFLAGS
READ
Flags describing the operations on the table.
ub4 *
See Also:
Oracle Database Development Guide for information about the flag values for the OCI_DTYPETABLE_CHDES continuous query notification descriptor
OCI_ATTR_CHDES_TABLE_ROW_CHANGES
READ
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 that has the attributes OCI_ATTR_CHDES_ROW_OPFLAGS and OCI_ATTR_CHDES_ROW_ROWID.
OCIColl **
The following are attributes of the descriptor OCI_DTYPE_AQNFY.
OCI_ATTR_AQ_NTFN_GROUPING_COUNT
OCI_ATTR_AQ_NTFN_GROUPING_ MSGID_ARRAY
OCI_ATTR_CONSUMER_NAME
OCI_ATTR_MSG_PROP
OCI_ATTR_NFY_FLAGS
OCI_ATTR_NFY_MSGID
OCI_ATTR_QUEUE_NAME
This section describes OCI_DTYPE_CQDES attributes. See Oracle Database Development Guide for more information about the OCI_DTYPE_CQDES continuous query notification descriptor.
OCI_ATTR_CQDES_OPERATION
OCI_ATTR_CQDES_QUERYID
OCI_ATTR_CQDES_TABLE_CHANGES
The following attributes are used for the direct path loading handle.
See Also:
"Direct Path Loading Overview" and"Direct Path Loading of Object Types" for information about direct path loading and allocating the direct path handles
The following attributes are used for the direct path context handle.
OCI_ATTR_BUF_SIZE
OCI_ATTR_CHARSET_ID
READ/WRITE
Default character set ID for the character data. Note that the character set ID can be overridden at the column level. If the character set ID is not specified at the column level or the table level, then the Global support environment setting is used.
ub2 */ub2 *
OCI_ATTR_DATEFORMAT
READ/WRITE
Default date format string for SQLT_CHR 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.
oratext **/oratext *
OCI_ATTR_DIRPATH_DCACHE_DISABLE
READ/WRITE
Setting this attribute to 1 indicates that the date cache is to be disabled if exceeded. The default value is 0, which means that lookups in the cache continue on cache overflow.
See Also:
"About 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
OCI_ATTR_DIRPATH_DCACHE_HITS
OCI_ATTR_DIRPATH_DCACHE_MISSES
OCI_ATTR_DIRPATH_DCACHE_NUM
OCI_ATTR_DIRPATH_DCACHE_SIZE
OCI_ATTR_DIRPATH_DEF_EXP_CACHE_SIZE
READ/WRITE
Specifies the number of default expressions that are evaluated at a time. The default is 100. For default expressions that must be evaluated for every row, increasing this value may improve performance.
Valid values: UB4
ub4 */ub4 *
ub4 default_cache = 200;
OCIAttrSet ((void *)dpctx,
(ub4)OCI_HTYPE_DIRPATH_CTX,
(void *)&default_cache,
(ub4)0, (ub4)OCI_ATTR_DIRPATH_DEF_EXP_CACHE_SIZE, errhp);
OCI_ATTR_DIRPATH_DEFAULTS
Read/Write
Specifies how the direct path API handles default expressions for columns that are not explicitly being loaded.
OCI_DIRPATH_DEFAULTS_DEFAULT
Evaluate once, unless a sequence is involved, then evaluate every row.
Error if an unsupported default value is seen. This is the default.
OCI_DIRPATH_DEFAULTS_EVALUATE_ONCE
Evaluate once, at the start of the load. Error if an unsupported default value is seen.
OCI_DIRPATH_DEFAULTS_EVALUATE_EVERY_ROW
Evaluate every row. Error if an unsupported default value is seen.
OCI_DIRPATH_DEFAULTS_IGNORE
Ignore all defaults, load NULLs.
OCI_DIRPATH_DEFAULTS_IGNORE_UNSUPPORTED_EVALUATE_ONCE
Ignore unsupported defaults, load NULLS, evaluate supported once.
OCI_DIRPATH_DEFAULTS_IGNORE_UNSUPPORTED_EVALUATE_EVERY_ROW
Ignore unsupported defaults, load NULLS, evaluate supported every row.
ub1 */ub1 *
ub1 dirpath_handling = OCI_DIRPATH_DEFAULTS_EVALUATE_EVERY_ROW;
OCIAttrSet ((void *)dpctx,
(ub4)OCI_HTYPE_DIRPATH_CTX,
(void *)&dirpath_handling,
(ub4)0, (ub4)OCI_ATTR_DIRPATH_DEFAULTS, errhp);
OCI_ATTR_DIRPATH_FLAGS
READ/WRITE
Flags used to control behavior of the load.
OCI_DIRPATH_FLAGS_VLDT 0x01 – validate format for Oracle NUMBER and DATE data when the stream is parsed on the server. The default value is to not set this flag because it is an expensive operation. It can be used when you suspect that there is a problem with OCIDirPath generating invalid internal representation of dates and numbers.
ub4 dirpath_flags = OCI_ATTR_DIRPATH_FLAGS_VLDT;
OCIAttrSet ((void *)dpctx,
(ub4)OCI_HTYPE_DIRPATH_CTX,
(void *)&dirpath_flags,
(ub4)0, (ub4)OCI_ATTR_DIRPATH_FLAGS, errhp);
ub4 */ub4 *
OCI_ATTR_DIRPATH_INDEX_MAINT_METHOD
OCI_ATTR_DIRPATH_MODE
OCI_DIRPATH_LOAD - Load operation (default)
OCI_DIRPATH_CONVERT - Convert-only operation
OCI_ATTR_DIRPATH_NO_INDEX_ERRORS
OCI_ATTR_DIRPATH_NOLOG
READ/WRITE
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.
OCI_ATTR_DIRPATH_OBJ_CONSTR
READ/WRITE
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);
oratext **/oratext *
OCI_ATTR_DIRPATH_PARALLEL
OCI_ATTR_DIRPATH_PGA_LIM
OCI_ATTR_DIRPATH_REJECT_ROWS_REPCH
OCI_ATTR_DIRPATH_SKIPINDEX_METHOD
READ/WRITE
Indicates how the handling of unusable indexes is 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)
OCI_ATTR_DIRPATH_SPILL_PASSES
READ
The number of passes required to load all partitions. If the direct path PGA limit is exceeded, this will likely be greater than one. Increasing the PGA limit, using the attribute OCI_ATTR_DIRPATH_PGA_LIM, can decrease the number of passes, but can also exceed available memory.
ub4 *
OCI_ATTR_LIST_COLUMNS
OCI_ATTR_NAME
OCI_ATTR_NUM_COLS
OCI_ATTR_NUM_ROWS
OCI_ATTR_SCHEMA_NAME
OCI_ATTR_SUB_NAME
For further explanations of these attributes, see "Direct Path Function Context and Attributes".
OCI_ATTR_DIRPATH_EXPR_TYPE
READ/WRITE
Indicates the type of expression specified in OCI_ATTR_NAME in the function context of a nonscalar 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)
OCI_ATTR_LIST_COLUMNS
READ
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 nonscalar column) is set with the OCI_ATTR_NUM_COLS attribute.
See Also:
OCI_ATTR_NAME
OCI_ATTR_NUM_COLS
OCI_ATTR_NUM_ROWS
The following attributes are used for the direct path function column array handle.
OCI_ATTR_COL_COUNT
OCI_ATTR_NUM_COLS
OCI_ATTR_NUM_ROWS
OCI_ATTR_ROW_COUNT
The following attributes are used for the direct path stream handle.
OCI_ATTR_BUF_ADDR
OCI_ATTR_BUF_SIZE
OCI_ATTR_ROW_COUNT
OCI_ATTR_STREAM_OFFSET
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 nonscalar, 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.
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:
"Direct Path Load Examples for Scalar Columns" for the data structures defined in the listings
...
/* 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
OCI_ATTR_DATA_SIZE
OCI_ATTR_DATA_TYPE
READ/WRITE
Returns or sets the external data type of the column. Valid data types are:
SQLT_CHR
SQLT_DATE
SQLT_TIMESTAMP
SQLT_TIMESTAMP_TZ
SQLT_TIMESTAMP_LTZ
SQLT_INTERVAL_YM
SQLT_INTERVAL_DS
SQLT_CLOB
SQLT_BLOB
SQLT_INT
SQLT_UIN
SQLT_FLT
SQLT_PDN
SQLT_BIN
SQLT_NUM
SQLT_NTY
SQLT_REF
SQLT_VST
SQLT_VNU
OCI_ATTR_DATEFORMAT
OCI_ATTR_DIRPATH_OID
OCI_ATTR_DIRPATH_SID
OCI_ATTR_NAME
OCI_ATTR_PRECISION
OCI_ATTR_SCALE
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.
See Also:
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:
Instance name, application name (unqualified): This allows only executables with a specific name to attach to the same shared subsystem. For example, this allows an OCI application named Office to connect to the same shared subsystem regardless of the directory Office resides in.
Instance name, home name: This allows a set of executables in a specific home directory to attach to the same instance of the shared subsystem. For example, this allows all OCI applications residing in the ORACLE_HOME directory to use the same shared subsystem.
Instance name, home name, application name (unqualified): This allows only a specific executable to attach to a shared subsystem. For example, this allows one application named Office in the ORACLE_HOME directory to attach to a given shared subsystem.
OCI_ATTR_MEMPOOL_APPNAME
OCI_ATTR_MEMPOOL_HOMENAME
OCI_ATTR_MEMPOOL_INSTNAME
OCI_ATTR_MEMPOOL_SIZE
OCI_ATTR_PROC_MODE
READ
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 AND'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;
ub4 *
The OCIEvent handle encapsulates the attributes from the event payload. This handle is implicitly allocated before the event callback is called.
See Also:
The event callback obtains the attributes of an event using OCIAttrGet() with the following attributes.
OCI_ATTR_DBDOMAIN
OCI_ATTR_DBNAME
OCI_ATTR_EVENTTYPE
OCI_ATTR_HA_SOURCE
READ
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
ub4 *
OCI_ATTR_HA_SRVFIRST
OCI_ATTR_HA_SRVNEXT
OCI_ATTR_HA_STATUS
OCI_ATTR_HA_TIMESTAMP
OCI_ATTR_HOSTNAME
OCI_ATTR_INSTNAME
READ
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. This attribute can also be used on service context to return the shard instance name for a given connection. This attribute can be used to find the shard instance name out of a shard instance descriptor that is filed by an OCIShardInstancesGet() call.
oratext **
The following example shows for a given connection (svchp) how to get the shard instance name.
Oratext instanceName [OCI_INSTNAME_MAXLEN];
ub4 instanceNameLen;
OCIATTRGet(svchp,
OCI_HTYPE_SVCCTX,
instanceName,
(ub4 *) &instanceNameLen,
OCI_ATTR_INSTNAME,
errhp);
OCI_ATTR_INSTSTARTTIME
OCI_ATTR_SERVICENAME