Handle and Descriptor Attributes

A Handle and Descriptor Attributes

This appendix describes the attributes for OCI handles and descriptors.

OCI handles and descriptors can be read with OCIAttrGet(), and modified with OCIAttrSet().

This appendix contains these topics:

A.1 Conventions

For each handle type, the attributes that can be read or changed are listed.

Each attribute listing includes the following information:

Mode

The following modes are valid:

READ - The attribute can be read using OCIAttrGet().

WRITE - The attribute can be modified using OCIAttrSet().

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

Description

This is a description of the purpose of the attribute.

Attribute 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.

A.2 Environment Handle Attributes

Lists and describes environment handle attributes.

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_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 *

A.3 Error Handle Attributes

Lists and describes error handle attributes.

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 *

A.4 Service Context Handle Attributes

Lists and describes service context handle attributes.

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):

Call timeout set on the OCI handle using OCIAttrSet().
Timeout set with the OCI attributes, OCI_ATTR_SEND_TIMEOUT and OCI_ATTR_RECEIVE_TIMEOUT.
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 *

A.5 Server Handle Attributes

Lists and describes server handle attributes.

The following attributes are used for the server handle.

See Also:

The following event handle attributes are also available for the server handle:

OCIXStreamOutLCRReceive() for more information about using the following attributes

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

See Also:

Nonblocking Mode in OCI

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 *

A.5.1 Authentication Information Handle Attributes

Lists and describes authentication information handle attributes.

These attributes also apply to the user session handle.

See Also:

User Session Handle Attributes

OCI_ATTR_FIXUP_CALLBACK

Mode

READ/WRITE

Description

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 Also:

Session Pool Handle Attributes for more information
PL/SQL Callback for Session State Fix Up for more information

Attribute Data Type

oratext * to be provided in the format schma.package.callback_function

A.5.2 User Session Handle Attributes

Lists and describes user session handle attributes.

The following user session handle attributes also apply to the authentication information handle.

OCI_ATTR_ACTION

Mode

WRITE

Description

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

Attribute Data Type

oratext *

Example

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

OCI_ATTR_APPCTX_ATTR

Note: