Release 2 (9.2)
Part Number A96584-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle Call Interface Programmer's Guide Release 2 (9.2) Part Number A96584-01 |
|
This appendix describes the attributes for OCI handles and descriptors, which can be read with OCIAttrGet(), and modified with OCIAttrSet().
For each handle type, the attributes which 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 datatype of the attribute. If necessary, a distinction is made between the datatype 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.
READ/WRITE
The login name (DN) to use when connecting to the LDAP server.
text *
READ/WRITE
When this attribute is set to TRUE, during OCICacheFlush() the objects that belong to the same table are flushed together, which can considerably improve performance. This mode should only be used when the order in which the objects are flushed is not important. During this mode it is not guaranteed that the order in which the objects are marked dirty is preserved.
boolean
READ/WRITE
Sets the maximum size (high watermark) for the client-side object cache as a percentage of the optimal size. Set the value at 110% of the optimal size (OCI_ATTR_CACHE_OPT_SIZE). The object cache uses the maximum and optimal values for freeing unused memory in the object cache.
ub4 *
READ/WRITE
Sets the optimal size for the client-side object cache in bytes. The default value is 8M bytes.
ub4 *
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. In UTF-16 mode, an attempt to get this attribute is invalid.
ub2 *
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. In UTF-16 mode, an attempt to get this attribute is invalid.
ub2 *
READ
Encoding method is UTF-16. The value 1 means that the environment handle is created in UTF-16 mode, while 0 means that it is not. This mode can only be set by the call to OCIEnvCreate() and cannot be changed later.
ub1 *
READ/WRITE
The authentication mode. The following are the valid values:
0x0: No authentication; anonymous bind.
0x1: Simple authentication; username/password authentication.
0x5: SSL connection with no authentication.
0x6: SSL: only server authentication required.
0x7: SSL: both server authentication and client authentication are required.
0x8: Authentication method will be determined at runtime.
ub2
READ/WRITE
If the authentication method is "simple authentication" (username/password authentication), then this attribute holds the password to use when connecting to the LDAP server.
text *
READ/WRITE
The administrative context of the client. This is usually the root of the Oracle RDBMS LDAP schema in the LDAP server.
text *
READ/WRITE
The name of the host on which the LDAP server runs.
text *
READ/WRITE
The port on which the LDAP server is listening.
ub2
READ
Returns TRUE if the environment was initialized in object mode.
boolean *
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, then if OCIObjectPin() is called with the pin_option parameter set to OCI_PIN_DEFAULT, then the object is pinned in OCI_PIN_RECENT mode.
OCIPinOpt *
READ/WRITE
This attribute sets the value of OCI_DURATION_DEFAULT for allocation durations for the application associated with the environment handle.
OCIDuration *
READ/WRITE
This attribute sets the value of OCI_DURATION_DEFAULT for pin durations for the application associated with the environment handle.
OCIDuration *
READ
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.
ub4 *
READ/WRITE
When this attribute is set to TRUE, newly created objects have non-NULL attributes.
boolean *
READ/WRITE
When this attribute is set to TRUE, applications receive an ORA-08179 error when attempting to flush an object which has been modified in the server by another committed transaction.
boolean *
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((dvoid *)envhp, (ub4)OCI_HTYPE_ENV, (dvoid *) &heapsz, (ub4 *) 0, (ub4)OCI_ATTR_SHARED_HEAPALLOC, errhp);
ub4 *
READ/WRITE
If the authentication method is SSL authentication, this attribute contains the location of the client wallet.
text *
READ
Returns the offset (into the DML array) at which the error occurred.
ub4 *
READ
returns the environment context associated with the service context.
OCIEnv **
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 parameter might be used:
in_v8_mode = 0; OCIAttrGet ((dvoid *)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");
READ/WRITE
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.
OCIServer ** / OCIServer *
READ/WRITE
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.
OCISession **/ OCISession *
READ/WRITE
The default value of the statement cache size is 20, for a statement cache enabled session. The user can increase or decrease this value, by setting this attribute on the service context handle.
ub4 */ ub4
READ/WRITE
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.
OCITrans ** / OCITrans *
READ
Returns the environment context associated with the server context.
OCIEnv **
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 in case of distributed transaction coordination. Server database names can only be accessed if the database is open at the time the OCISessionBegin() call is issued.
text ** (READ) / text * (WRITE)
READ/WRITE
OCIFocbkStruct *
READ/WRITE
Sets the client database name that will be recorded when performing global transactions. The name can be used by the DBA to track transactions that may be pending in a prepared state due to failures.
text ** (READ) / text * (WRITE)
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 *
READ/WRITE
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.
ub1
READ/WRITE
An alpha-numeric string not exceeding 30 characters specifying the server group.
ub4
READ
Returns the current status of the server handle. Values are:
ub4
The following code sample shows how this parameter might be used:
ub4 serverStatus = 0 OCIAttrGet((dvoid *)srvhp, OCI_HTYPE_SERVER, (dvoid *)&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");
These attributes also apply to the user session handle.
These attributes also apply to the authentication information handle.
WRITE
Specifies a an attribute name of the externally initialized context.
text *
READ
Gets the application context list descriptor for the session.
text *
WRITE
Specifies the namespace of the externally initialized context.
text *
WRITE
Initializes the externally initialized context array size with the number of attributes.
text *
WRITE
Specifies a value of the externally initialized context.
text *
WRITE
Specifies the certificate of the client for use in proxy authentication.
ub1 *
WRITE
Specifies the type for proxy authentication. If not specified, the default type of X.509 is used.
text *
WRITE
Specifies the user identifier in the session handle. Used for auditing light-weight users. The first character of the identifier should not be ':'. If it is, the behavior is unspecified.
text *
OCIAttrSet(session, OCI_HTYPE_SESSION,(dvoid *)"appuser1", (ub4)strlen("appuser1"),OCI_ATTR_APPCTX_IDENTIFIER, error_handle) ;
WRITE
Specifies distinguished name of the client for use in proxy authentication.
text *
WRITE
Specifies the role or roles that the client is to initially possess when the application server connects to Oracle on its behalf.
ub4
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 machine or different machines. For a session to be cloned, the session must be authenticated as migratable.
ub1 *
The following code sample shows how this attribute might be used:
OCIAttrSet ((dvoid *) authp, (ub4) OCI_HTYPE_SESSION, (dvoid *) mig_session, (ub4) sz, (ub4) OCI_ATTR_MIGSESSION, errhp);
WRITE
Specifies a password to use for authentication.
text *
WRITE
Specifies that the credentials of the application server are to be used for proxy authentication.
ub4
WRITE
Specifies a username to use for authentication.
text *
READ/WRITE
Connections idle for more than this time value (in seconds) are terminated, to maintain an optimum number of open connections.This attribute can be set dynamically. If this attribute is not set, the connections are never timed out.
ub4 */ub4
READ/WRITE
This attribute determines if retrial for a connection has to be done when all connections in the pool are found to be busy and the number of connections has already reached the maximum.
If this attribute is set, an error is thrown when all the connections are busy and no more connections can be opened. Otherwise the call waits till it gets a connection.
When read, the attribute value is returned as TRUE if it has been set.
ub1 */ub1
READ
Returns the number of busy connections.
ub4 *
READ
Returns the number of open connections.
ub4 *
READ
Returns the number of minimum connections.
ub4 *
READ
Returns the number of maximum connections.
ub4 *
READ
Returns the connection increment parameter.
ub4 *
The attributes used for session pooling are:
READ
Returns the number of busy sessions.
ub4 *
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 already reached the maximum. Values are:
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 server. In this case, the server will return the following error:
ORA 00018 - Maximum number of sessions exceeded
In this case, the error will be propagated to the session pool user.
When read, the appropriate attribute value is returned.
ub1 */ ub1
READ
Returns the session increment parameter.
ub4 *
READ
Returns the number of maximum sessions.
ub4 *
READ
Returns the number of minimum sessions.
ub4 *
READ
Returns the number of open sessions.
ub4 *
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.
ub4 */ ub4
READ/WRITE
Can be used to establish or read a text string which identifies a transaction. This is an alternative to using the XID to identify the transaction. The text string can be up to 64 bytes long.
text ** (READ) / text * (WRITE)
READ/WRITE
Can set or read a timeout value used at prepare time.
ub4 * (READ) / ub4 (WRITE)
READ/WRITE
Can set or read an XID which identifies a transaction.
XID ** (READ) / XID * (WRITE)
READ
Indicates the current position in the result set. This attribute can only be retrieved. It cannot be set.
ub4 *
READ
Returns the environment context associated with the statement.
OCIEnv **
READ
Returns the number of errors in the DML operation.
ub4 *
READ
This attribute can be used to get the number of columns in the select-list for the statement associated with the statement handle.
ub4 *
The following code sample shows how this attribute might be used:
/* Describe of a select-list */
text *selstmt = "SELECT * FROM EMP";
ub4 parmcnt;
OCIParam *parmdp;
err = OCIStmtPrepare (stmhp, errhp, selstmt,
(ub4)strlen((char *)selstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
err = OCIStmtExecute (svchp, stmhp, errhp, (ub4)1, (ub4)0,
(const OCISnapshot*) 0, (OCISnapshot*)0, OCI_DESCRIBE_ONLY);
/* get the number of columns in the select list */
err = OCIAttrGet ((dvoid *)stmhp, (ub4)OCI_HTYPE_STMT, (dvoid *)
&parmcnt, (ub4 *) 0, (ub4)OCI_ATTR_PARAM_COUNT, errhp);
/* get describe information for each column */
for (i = 1; i < parmcnt; i++) {
OCIParamGet (dvoid *)stmhp, OCI_HTYPE_STMT, errhp, &parmdp, i);
/* get the attributes for each column */
}
READ
Returns the parse error offset for a statement.
ub2 *
WRITE
Sets the memory level for top level rows to be prefetched. Rows up to the specified top level row count are fetched if it occupies no more than the specified memory usage limit. The default value is 0, which means that memory size is not included in computing the number of rows to prefetch.
ub4 *
WRITE
Sets the number of top level rows to be prefetched. The default value is 1 row.
ub4 *
READ
Returns the number of rows processed so far. The default value is 1.
For non-scrollable cursors, OCI_ATTR_ROW_COUNT is the total number of rows fetched into user buffers with the OCIStmtFetch2() calls issued since this statement handle was executed. Since they are forward sequential only, this also represents the highest row number seen by the application.
For scrollable cursors, OCI_ATTR_ROW_COUNT will represent the maximum (absolute) row number fetched into the user buffers. Since the application can arbitrarily position the fetches, this need not be the total number of rows fetched into the user's buffers since the (scrollable) statement was executed.
ub4 *
READ
Returns the ROWID descriptor allocated with OCIDescriptorAlloc().
OCIRowid *
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 non-scrollable statement handles.
ub4 *
ub4 rows; ub4 sizep = sizeof(ub4); OCIAttrGet((dvoid *) stmhp, (ub4) OCI_HTYPE_STMT, (dvoid *)& rows, (ub4 *) &sizep, (ub4)OCI_ATTR_ROWS_FETCHED, errhp));
READ
Returns the function code of the SQL command associated with the statement.
ub2 *
| See Also:
The SQL command codes are listed in Table A-1, "SQL Command Codes" |
READ
Returns the text of the SQL statement prepared in a statement handle. In UTF-16 mode, the returned statement is in UTF-16 encoding. The length is always in bytes.
text *
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 we are in the middle of a fetch-execute cycle, then we do not want to release the session handle for another statement execution. Valid values are:
ub4 *
READ
The type of statement associated with the handle. Valid values are:
ub2 *
WRITE
ub4 *
READ/WRITE
Character set form of the bind handle. The default form is SQLCS_IMPLICIT. Setting this attribute will cause the bind handle to use the database or national character set on the client side. Set this attribute to SQLCS_NCHAR for the national character set or SQLCS_IMPLICIT for the database character set.
ub1 *
READ/WRITE
Character set ID of the bind handle. If the character set of the input data is UTF-16 (replaces the deprecated OCI_UCS2ID, which is retained for backward compatibility), the user has to set the character set ID to OCI_UTF16ID. The bind value buffer is assumed to be a utext buffer and length semantics for input length pointers and return values changes to character semantics (number of utexts). However the size of the bind value buffer in the preceeding OCIBind call has to be stated in bytes.
If OCI_ATTR_CHARSET_FORM is set, then OCI_ATTR_CHARSET_ID should be set only afterwards. Setting OCI_ATTR_CHARSET_ID prior to setting OCI_ATTR_CHARSET_FORM will cause unexpected results.
ub2 *
WRITE
Sets the number of characters that an application reserves on the server to store the data being bound.