Oracle Call Interface Programmer's Guide
Release 8.1.5

A67846-01

Library

Product

Contents

Index

Prev Next

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:

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 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 10%. 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 200k 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

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 *

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

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_COMPLEXOBJECT_COMP_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

See Also: For information about direct path loading and allocating the direct path handles, refer to "Direct Path Loading" .

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

Last row 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

Column array index of the last row processed. This attribute is valid only if the data was sourced from a column array.

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.

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




Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index