Oracle Call Interface Programmer's Guide
Release 8.1.6

Part Number A76975-01

Library

Product

Contents

Index

Go to previous page Go to next page

A
Handle and Descriptor Attributes

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

Conventions

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

Mode

The following modes are possible:

Description

This is a description of the purpose of the attribute.

Attribute Datatype

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

Possible Values

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

Example

In some cases an example is included.

Environment Handle Attributes

OCI_ATTR_CACHE_ARRAYFLUSH

Mode

READ/WRITE

Description

When this attribute is set to TRUE, during OCICacheFlush() the objects that belong to the same table are flushed together, which can considerably improve performance. This mode should only be used when the order in which the objects are flushed is not important. During this mode it is not guaranteed that the order in which the objects are marked dirty is preserved. See "Object Cache Parameters" and "Flushing Changes to Server" for more information.

Attribute Datatype

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. The default value is 110% of the optimal size. The object cache uses the maximum and optimal values for freeing unused memory in the object cache. See the section "Object Cache Parameters" for more information.

Attribute Datatype

ub4 *

OCI_ATTR_CACHE_OPT_SIZE

Mode

READ/WRITE

Description

Sets the optimal size for the client-side object cache in bytes. The default value is 8M bytes. See the section "Object Cache Parameters" for more information.

Attribute Datatype

ub4 *

OCI_ATTR_OBJECT

Mode

READ

Description

Returns TRUE if the environment was initialized in object mode.

Attribute Datatype

boolean *

OCI_ATTR_PINOPTION

Mode

READ/WRITE

Description

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

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

Attribute Datatype

OCIPinOpt *

OCI_ATTR_ALLOC_DURATION

Mode

READ/WRITE

Description

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

Attribute Datatype

OCIDuration *

OCI_ATTR_PIN_DURATION

Mode

READ/WRITE

Description

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

Attribute Datatype

OCIDuration *

OCI_ATTR_HEAPALLOC

Mode

READ

Description

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

Attribute Datatype

ub4 *

OCI_ATTR_OBJECT_NEWNOTNULL

Mode

READ/WRITE

Description

When this attribute is set to TRUE, newly created objects have non-NULL attributes. For more information refer to "Creating Objects".

Attribute Datatype

boolean *

OCI_ATTR_OBJECT_DETECTCHANGE

Mode

READ/WRITE

Description

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

For more information, refer to "Implementing Optimistic Locking".

Attribute Datatype

boolean *

OCI_ATTR_SHARED_HEAP_ALLOC

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((dvoid *)envhp, (ub4)OCI_HTYPE_ENV,
           (dvoid *) &heapsz, (ub4 *) 0,
           (ub4)OCI_ATTR_SHARED_HEAPALLOC, errhp);
Attribute Datatype

ub4 *

Error Handle Attributes

OCI_ATTR_DML_ROW_OFFSET

Mode

READ

Description

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

Attribute Datatype

ub4 *

Service Context Handle Attributes

OCI_ATTR_ENV

Mode

READ

Description

returns the environment context associated with the service context.

Attribute Datatype

OCIEnv **

OCI_ATTR_SERVER

Mode

READ/WRITE

Description

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

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

Attribute Datatype

OCIServer ** (READ) / OCIServer * (WRITE)

OCI_ATTR_SESSION

Mode

READ/WRITE

Description

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

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

Attribute Datatype

OCISession ** (READ) / OCISession * (WRITE)

OCI_ATTR_TRANS

Mode

READ/WRITE

Description

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

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

Attribute Datatype

OCITrans ** (READ) / OCITrans * (WRITE)

OCI_ATTR_IN_V8_MODE

Mode

READ

Description

Allows you to determine whether an application has switched to Oracle release 7 mode (e.g., through an OCISvcCtxToLda() call). A non-zero (true) return value indicates that the application is currently running in Oracle release 8 mode, a zero (false) return value indicates that the application is currently running in Oracle release 7 mode.

Attribute Datatype

ub1 *

Example

The following code sample shows how this 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");

Server Handle Attributes

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 non-blocking mode. When set, it toggles the non-blocking mode attribute. See "Non-Blocking Mode" for more information.

Attribute Datatype

The attribute value is of type ub1.

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the server context.

Attribute Datatype

OCIEnv **

OCI_ATTR_EXTERNAL_NAME

Mode

READ/WRITE

Description

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

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

Attribute Datatype

text ** (READ) / text * (WRITE)

OCI_ATTR_INTERNAL_NAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text ** (READ) / text * (WRITE)

OCI_ATTR_IN_V8_MODE

Mode

READ

Description

Allows you to determine whether an application has switched to Oracle release 7 mode (e.g., through an OCISvcCtxToLda() call). A non-zero (true) return value indicates that the application is currently running in Oracle release 8 mode, a zero (false) return value indicates that the application is currently running in Oracle release 7 mode.

Attribute Datatype

ub1 *

OCI_ATTR_FOCBK

Mode

READ/WRITE

Description

See "Application Failover Callbacks" for more information.

Attribute Datatype

OCIFocbkStruct *

OCI_ATTR_SERVER_GROUP

Mode

READ/WRITE

Description

An alpha-numeric string not exceeding 30 characters specifying the server group. See "Password and Session Management" for more information.

Attribute Datatype

ub4

OCI_ATTR_SERVER_STATUS

Mode

READ

Description

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

Attribute Datatype

ub4

Example

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");

User Session Handle Attributes

OCI_ATTR_USERNAME

Mode

WRITE

Description

Specifies a username to use for authentication.

Attribute Datatype

text *

OCI_ATTR_MIGSESSION

Mode

READ/WRITE

Description

Specifies the session identified for the session handle. Allows you to clone a session from one environment to another, in the same process or between processes. These processes can be on the same machine or different machines. For a session to be cloned, the session must be authenticated as migratable. See "Password and Session Management" for more information.

Attribute Datatype

ub1 *

Example

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

OCI_ATTR_PASSWORD

Mode

WRITE

Description

Specifies a password to use for authentication.

Attribute Datatype

text *

OCI_ATTR_PROXY_CREDENTIALS

Mode

READ

Description

Specifies the credentials of the application server to use for authentication.

Attribute Datatype

ub4

OCI_ATTR_EXTERNAL_NAME

Mode

READ

Description

Specifies the external name of the client for midddlie-tier applivations.

Attribute Datatype

ub4

OCI_ATTR_INITIAL_CLIENT_ROLES

Mode

READ

Description

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

Attribute Datatype

ub4

Transaction Handle Attributes

OCI_ATTR_TRANS_NAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text ** (READ) / text * (WRITE)

OCI_ATTR_TRANS_TIMEOUT

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4 * (READ) / ub4 (WRITE)

OCI_ATTR_XID

Mode

READ/WRITE

Description

Can set or read an XID which identifies a transaction.

Attribute Datatype

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

Statement Handle Attributes

OCI_ATTR_NUM_DML_ERRORS

Mode

READ

Description

Returns the number of errors in the DML operation.

Attribute Datatype

ub4 *

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Returns the number of rows processed so far. The default value is 1.

Attribute Datatype

ub4 *

OCI_ATTR_SQLFNCODE

Mode

READ

Description

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

Attribute Datatype

ub2 *

Notes

The SQL command codes are listed in Table A-1, "SQL Command Codes".

Table A-1 SQL Command Codes  
Code  SQL Function  Code  SQL Function  Code  SQL Function 

01 

CREATE TABLE 

43 

DROP EXTERNAL DATABASE 

85 

TRUNCATE TABLE 

02 

SET ROLE 

44 

CREATE DATABASE 

86 

TRUNCATE CLUSTER 

03 

INSERT 

45 

ALTER DATABASE 

87 

CREATE BITMAPFILE 

04 

SELECT 

46 

CREATE ROLLBACK SEGMENT 

88 

ALTER VIEW 

05 

UPDATE 

47 

ALTER ROLLBACK SEGMENT 

89 

DROP BITMAPFILE 

06 

DROP ROLE 

48 

DROP ROLLBACK SEGMENT 

90 

SET CONSTRAINTS 

07 

DROP VIEW 

49 

CREATE TABLESPACE 

91 

CREATE FUNCTION 

08 

DROP TABLE 

50 

ALTER TABLESPACE 

92 

ALTER FUNCTION 

09 

DELETE 

51 

DROP TABLESPACE 

93 

DROP FUNCTION 

10 

CREATE VIEW 

52 

ALTER SESSION 

94 

CREATE PACKAGE 

11 

DROP USER 

53 

ALTER USER 

95 

ALTER PACKAGE 

12 

CREATE ROLE 

54 

COMMIT (WORK) 

96 

DROP PACKAGE 

13 

CREATE SEQUENCE 

55 

ROLLBACK 

97 

CREATE PACKAGE BODY 

14 

ALTER SEQUENCE 

56 

SAVEPOINT 

98 

ALTER PACKAGE BODY 

15 

(NOT USED) 

57 

CREATE CONTROL FILE 

99 

DROP PACKAGE BODY 

16 

DROP SEQUENCE 

58 

ALTER TRACING 

157 

CREATE DIRECTORY 

17 

CREATE SCHEMA 

59 

CREATE TRIGGER 

158 

DROP DIRECTORY 

18 

CREATE CLUSTER 

60 

ALTER TRIGGER 

159 

CREATE LIBRARY 

19 

CREATE USER 

61 

DROP TRIGGER 

160 

CREATE JAVA 

20 

CREATE INDEX 

62 

ANALYZE TABLE 

161 

ALTER JAVA 

21 

DROP INDEX 

63 

ANALYZE INDEX 

162 

DROP JAVA 

22 

DROP CLUSTER 

64 

ANALYZE CLUSTER 

163 

CREATE OPERATOR 

23 

VALIDATE INDEX 

65 

CREATE PROFILE 

164 

CREATE INDEXTYPE 

24 

CREATE PROCEDURE 

66 

DROP PROFILE 

165 

DROP INDEXTYPE 

25 

ALTER PROCEDURE 

67 

ALTER PROFILE 

166 

ALTER INDEXTYPE 

26 

ALTER TABLE 

68 

DROP PROCEDURE 

167 

DROP OPERATOR 

27 

EXPLAIN 

69 

(NOT USED) 

168 

ASSOCIATE STATISTICS 

28 

GRANT 

70 

ALTER RESOURCE COST 

169 

DISASSOCIATE STATISTICS 

29 

REVOKE 

71 

CREATE SNAPSHOT LOG 

170 

CALL METHOD 

30 

CREATE SYNONYM 

72 

ALTER SNAPSHOT LOG 

171 

CREATE SUMMARY 

31 

DROP SYNONYM 

73 

DROP SNAPSHOT LOG 

172 

ALTER SUMMARY 

32 

ALTER SYSTEM SWITCH LOG 

74 

CREATE SNAPSHOT 

73 

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_ENV

Mode

READ

Description

Returns the environment context associated with the statement.

Attribute Datatype

OCIEnv **

OCI_ATTR_STMT_TYPE

Mode

READ

Description

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

Attribute Datatype

ub2 *

OCI_ATTR_ROWID

Mode

READ

Description

Returns the ROWID descriptor allocated with OCIDescriptorAlloc(). For additional information, see "Positioned Updates and Deletes" and "ROWID".

Attribute Datatype

OCIRowid *

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

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

Attribute Datatype

ub4 *

Example

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 = 0; i < parmcnt; i++) { 
    OCIParamGet (dvoid *)stmhp, OCI_HTYPE_STMT, errhp, &parmdp, i); 
/* get the attributes for each column */ 
        } 

OCI_ATTR_PREFETCH_ROWS

Mode

WRITE

Description

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

Attribute Datatype

ub4 *

OCI_ATTR_PREFETCH_MEMORY

Mode

WRITE

Description

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

Attribute Datatype

ub4 *

OCI_ATTR_PARSE_ERROR_OFFSET

Mode

READ

Description

Returns the parse error offset for a statement.

Attribute Datatype

ub2 *

Bind Handle Attributes

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

See "Character Count Attribute".

Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

Character set ID of the bind handle. If the character set of the input data is UCS-2 (Unicode), the user has to set the character set Id to OCI_UCS2ID. 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. For more information, see "Fixed Width Unicode Support".

When changing the character set on an bind handle, it is necessary to explicitly state the maximum length of the corresponding column in the database (schema definition). This is done using OCIAttrSet() and specifying the value of the OCI_ATTR_MAXDATA_SIZE attribute on the define handle.

Attribute Datatype

ub2 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

Character set form of the bind handle.

Attribute Datatype

ub1 *

OCI_ATTR_MAXDATA_SIZE

Mode

READ/WRITE

Description

See "OCI_ATTR_MAXDATA_SIZE Attribute".

Attribute Datatype

sb4 *

OCI_ATTR_PDPRC

Mode

WRITE

Description

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

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

Attribute Datatype

ub2 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Specifies the scale for packed decimal values.

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

Attribute Datatype

sb2 *

OCI_ATTR_ROWS_RETURNED

Mode

READ

Description

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

Attribute Datatype

ub4 *

Define Handle Attributes

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

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

Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

The character set ID of the define handle. If the character set of the output data should be UCS-2 (Unicode), the user has to set the character set Id to OCI_UCS2ID. The define value buffer is assumed to be a utext buffer and length semantics for indicators and return values changes to character semantics (number of utexts). However the size of the define value buffer in the preceeding OCIDefine call has to be stated in bytes. For more information, see "Fixed Width Unicode Support".

Attribute Datatype

ub2 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

The character set form of the define handle.

Attribute Datatype

ub1 *

OCI_ATTR_PDPRC

Mode

WRITE

Description

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

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

Attribute Datatype

ub2 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Specifies the scale for packed decimal values.

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

Attribute Datatype

sb2 *

Describe Handle Attributes

OCI_ATTR_PARAM

Mode

READ

Description

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

Attribute Datatype

ub4 *

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

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

Attribute Datatype

ub4 *

Parameter Descriptor Attributes

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

LOB Locator Attributes

OCI_ATTR_LOBEMPTY

Mode

WRITE

Description

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

Applications should pass address of a ub4 which has a value of 0; e.g., declare

ub4 lobEmpty = 0

then pass address &lobEmpty.

Attribute Datatype

ub4 *

Complex Object Attributes

For information about complex object retrieval, see "Complex Object Retrieval".

Complex Object Retrieval Handle Attributes

OCI_ATTR_COMPLEXOBJECT_LEVEL

Mode

WRITE

Description

The depth level for complex object retrieval.

Attribute Datatype

ub4 *

OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE

Mode

WRITE

Description

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

Attribute Datatype

ub1 *

Complex Object Retrieval Descriptor Attributes

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE

Mode

WRITE

Description

A type of REF to follow for complex object retrieval.

Attribute Datatype

dvoid *

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL

Mode

WRITE

Description

Depth level for following REFs of type OCI_ATTR_COMPLEXOBJECTCOMP_TYPE.

Attribute Datatype

ub4 *

Advanced Queueing Descriptor Attributes

For more information about Advanced Queueing, properties, and options, refer to the Advanced Queueing chapter of the Oracle8i Application Developer's Guide - Fundamentals.

OCIAQEnqOptions Descriptor Attributes

The following attributes are properties of the OCIAQEnqOptions descriptor:

OCI_ATTR_RELATIVE_MSGID

Mode

READ/WRITE

Description

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

Attribute Datatype

OCIRaw *

OCI_ATTR_SEQUENCE_DEVIATION

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4

Possible Values

The only valid values are:

OCI_ATTR_VISIBILITY

Mode

READ/WRITE

Description

Specifies the transactional behavior of the enqueue request.

Attribute Datatype

ub4

Possible Values

The only valid values are:

OCIAQDeqOptions Descriptor Attributes

The following attributes are properties of the OCIAQDeqOptions descriptor:

OCI_ATTR_CONSUMER_NAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

OCI_ATTR_CORRELATION

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

OCI_ATTR_DEQ_MODE

Mode

READ/WRITE

Description

Specifies the locking behavior associated with the dequeue.

Attribute Datatype

ub4

Possible Values

The only valid values are:

OCI_ATTR_DEQ_MSGID

Mode

READ/WRITE

Description

Specifies the message identifier of the message to be dequeued.

Attribute Datatype

OCIRaw *

OCI_ATTR_NAVIGATION

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4

Possible Values

The only valid values are:

OCI_ATTR_VISIBILITY

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4

Possible Values

The only valid values are:

OCI_ATTR_WAIT

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4

Possible Values

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

OCIAQMsgProperties Descriptor Attributes

The following attributes are properties of the OCIAQMsgProperties descriptor:

OCI_ATTR_ATTEMPTS

Mode

READ

Description

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

Attribute Datatype

sb4

Possible Values

Any sb4 value is valid.

OCI_ATTR_CORRELATION

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

Possible Values

Any string up to 128 bytes is valid.

OCI_ATTR_DELAY

Mode

READ/WRITE

Description

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

Attribute Datatype

sb4

Possible Values

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

OCI_ATTR_ENQ_TIME

Mode

READ

Description

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

Attribute Datatype

OCIDate

OCI_ATTR_EXCEPTION_QUEUE

Mode

READ/WRITE

Description

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

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

This attribute must refer to a valid queue name.

Attribute Datatype

text *

OCI_ATTR_EXPIRATION

Mode

READ/WRITE

Description

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

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

Attribute Datatype

sb4

Possible Values

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

OCI_ATTR_MSG_STATE

Mode

READ

Description

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

Attribute Datatype

ub4

Possible Values

These are the only values which are returned:

OCI_ATTR_PRIORITY

Mode

READ/WRITE

Description

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

The default value is zero.

Attribute Datatype

sb4

OCI_ATTR_RECIPIENT_LIST

Mode

WRITE

Description

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

Attribute Datatype

OCIAQAgent **

OCI_ATTR_SENDER_ID

Mode

READ/WRITE

Description

Identifies the original sender of a message.

Attribute Datatype

OCIAgent *

OCI_ATTR_ORIGINAL_MSGID

Mode

READ/WRITE

Description

The ID of 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 last queue, not the first queue.

Attribute Datatype

OCIRaw *

OCIAQAgent Descriptor Attributes

The following attributes are properties of the OCIAQAgent descriptor:

OCI_ATTR_AGENT_ADDRESS

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

Possible Values

Can be any string up to 128 bytes.

OCI_ATTR_AGENT_NAME

Mode

READ/WRITE

Description

Name of a producer or consumer of a message.

Attribute Datatype

text *

Possible Values

Can be any Oracle identifier, up to 30 bytes.

OCI_ATTR_AGENT_PROTOCOL

Mode

READ/WRITE

Description

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

Attribute Datatype

ub1

Possible Values

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

Subscription Handle Attributes

See Also: For information about direct path loading and allocating the direct path handles, refer to "Publish-Subscribe Notification".

OCI_ATTR_SUBSCR_CALLBACK

Mode

READ/WRITE

Description

Subscription callback. This attribute needs to be set before the subscription handle can be passed into the registration call OCISubscriptionRegister().

Attribute Datatype

OCISubscriptionNotify *

OCI_ATTR_SUBSCR_CTX

Mode

READ/WRITE

Description

Context that the client wants to get passed to the user callback denoted by OCI_ATTR_SUBSCR_CALLBACK when it gets invoked by the system. This attribute needs to be set before the subscription handle can be passed into the registration call OCISubscriptionRegister().

Attribute Datatype

dvoid *

OCI_ATTR_SUBSCR_NAMESPACE

Mode

READ/WRITE

Description

Namespace in which the subscription handle is used. This release only supports OCI_SUBSCR_NAMESPACE_AQ and that value must be set explicitly. The subscription name that is set for the subscription handle must be consistent with its namespace.

Attribute Datatype

ub4 *

OCI_ATTR_SUBSCR_NAME

Mode

READ/WRITE

Description

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

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

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

Attribute Datatype

text *

OCI_ATTR_SUBSCR_PAYLOAD

Mode

READ/WRITE

Description

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

Attribute Datatype

ub1 *

Direct Path Loading Handle Attributes

Direct Path Context Handle Attributes

OCI_ATTR_BUF_SIZE

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4 */ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

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

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_DATEFORMAT

Mode

READ/WRITE

Description

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

Attribute Datatype

text **/text *

OCI_ATTR_DIRPATH_MODE

Mode

READ/WRITE

Description

Mode of the direct path context:

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_NOLOG

Mode

READ/WRITE

Description

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

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_DIRPATH_PARALLEL

Mode

READ/WRITE

Description

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

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_LIST_COLUMNS

Mode

READ

Description

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

Attribute Datatype

OCIParam* *

OCI_ATTR_NAME

Mode

READ/WRITE

Description

Name of the table to be loaded.

Attribute Datatype

text**/text *

OCI_ATTR_NUM_COLS

Mode

READ/WRITE

Description

Number of columns being loaded in the table.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_SCHEMA_NAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text **/text *

OCI_ATTR_SUB_NAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text **/text *

Direct Path Column Array Handle Attributes

OCI_ATTR_COL_COUNT

Mode

READ

Description

Last column of the last row processed.

Attribute Datatype

ub2 *

OCI_ATTR_NUM_COLS

Mode

READ

Description

Column dimension of the column array.

Attribute Datatype

ub2 *

OCI_ATTR_NUM_ROWS

Mode

READ

Description

Row dimension of the column array.

Attribute Datatype

ub4 *

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Number of rows processed.

Attribute Datatype

ub4 *

Direct Path Stream Handle Attributes

OCI_ATTR_BUF_ADDR

Mode

READ

Description

Buffer address of the beginning of the stream data.

Attribute Datatype

ub1 **

OCI_ATTR_BUF_SIZE

Mode

READ

Description

Size of the stream data in bytes.

Attribute Datatype

ub4 *

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Number of rows processed by previous OCIDirPathLoadStream() call.

Attribute Datatype

ub4 *

OCI_ATTR_STREAM_OFFSET

Mode

READ

Description

Offset into the stream buffer of the last processed row.

Attribute Datatype

ub4 *

Direct Path Column Parameter Attributes

The application specifies which columns are to be loaded, and the external format of the data by setting attributes on each column parameter descriptor. The column parameter descriptors are obtained as parameters of the column parameter list via OCIParamGet(). The column parameter list is obtained from the OCI_ATTR_LIST_COLUMNS attribute of the direct path context. Note that all parameters are 1-based.

Accessing Column Parameter Attributes

The following code sample illustrates the use of the direct path column parameter attributes. 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 the data structures defined in the listings in Direct Path Load Example.

  /* set number of columns to be loaded */
  OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
            OCIAttrSet((dvoid *)dpctx, (ub4)OCI_HTYPE_DIRPATH_CTX,
                       (dvoid *)&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((dvoid *)dpctx, 
                       OCI_HTYPE_DIRPATH_CTX,
                       (dvoid *)&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 dvoid *)ctlp->colLstDesc_ctl,
                          (ub4)OCI_DTYPE_PARAM, ctlp->errhp_ctl,
                          (dvoid **)&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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)&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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)&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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)&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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)&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((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
                         (dvoid *)&colp->csid_col, (ub4)0,
                         (ub4)OCI_ATTR_CHARSET_ID, ctlp->errhp_ctl));
    }
    /* free the parameter handle to the column descriptor */
    OCI_CHECK((dvoid *)0, 0, ociret, ctlp,
              OCIDescriptorFree((dvoid *)colDesc, OCI_DTYPE_PARAM));
  }

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

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

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_DATA_SIZE

Mode

READ/WRITE

Description

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

Attribute Datatype

ub4 */ub4 *

OCI_ATTR_DATA_TYPE

Mode

READ/WRITE

Description

Returns or sets the external datatype of the column. Valid datatypes are: SQLT_CHR, SQLT_DAT, SQLT_INT, SQLT_UIN, SQLT_FLT, SQLT_PDN, SQLT_BIN, or SQLT_NUM.

Attribute Datatype

ub2 */ub2 *

OCI_ATTR_DATEFORMAT

Mode

READ/WRITE

Description

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

Attribute Datatype

text **/text *

OCI_ATTR_NAME

Mode

READ/WRITE

Description

Returns or sets the name of the column that is being loaded.

Attribute Datatype

text **/text *

OCI_ATTR_PRECISION

Mode

READ/WRITE

Description

Returns of sets the precision.

Attribute Datatype

ub1 */ub1 *

OCI_ATTR_SCALE

Mode

READ/WRITE

Description

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

Attribute Datatype

sb1 */sb1 *

Process Handle Attributes

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

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 possible settings of the attributes for specific behaviors:

OCI_ATTR_MEMPOOL_APPNAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

OCI_ATTR_MEMPOOL_HOMENAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

OCI_ATTR_MEMPOOL_INSTNAME

Mode

READ/WRITE

Description

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

Attribute Datatype

text *

OCI_ATTR_MEMPOOL_SIZE

Mode

READ/WRITE

Description

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

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

ub4 *

OCI_ATTR_PROC_MODE

Mode

READ

Description

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

ub4 mode;
boolean is_shared;

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

is_shared = (mode & OCI_SHARED);
Attribute Datatype

ub4 *


Go to previous page Go to next page
Oracle
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index