Oracle Call Interface Programmer's Guide, Volumes 1 & 2
Release 8.0

A58234-01

Library

Product

Contents

Index

Prev Next

B
Handle and Descriptor Attributes

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

The following handle types are included:


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_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" on page 11-5 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" on page 11-5 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_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

The OCI function codes are listed in Table B-1 on page B - 5.

Attribute Datatype

ub4 *

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 *

Table B-1 OCI Function Codes
#   OCI Routine   #   OCI Routine   #   OCI Routine  

1  

OCIInitialize  

27  

OCIDefineArrayOfStruct  

53  

(NOT USED)  

2  

OCIHandleAlloc  

28  

OCIStmtFetch  

54  

OCIAttrGet  

3  

OCIHandleFree  

29  

OCIStmtGetBindInfo  

55  

OCIAttrSet  

4  

OCIDescriptorAlloc  

30  

(NOT USED)  

56  

OCIParamSet  

5  

OCIDescriptorFree  

31  

(NOT USED)  

57  

OCIParamGet  

6  

OCIEnvInit  

32  

OCIDescribeAny  

58  

OCIStmtGetPieceInfo  

7  

OCIServerAttach  

33  

OCITransStart  

59  

OCILdaToSvcCtx  

8  

OCIServerDetach  

34  

OCITransDetach  

60  

(NOT USED)  

9  

(NOT USED)  

35  

OCITransCommit  

61  

OCIStmtSetPieceInfo  

10  

OCISessionBegin  

36  

(NOT USED)  

62  

OCITransForget  

11  

OCISessionEnd  

37  

OCIErrorGet  

63  

OCITransPrepare  

12  

OCIPasswordChange  

38  

OCILobFileOpen  

64  

OCITransRollback  

13  

OCIStmtPrepare  

39  

OCILobFileClose  

65  

OCIDefineByPos  

14  

(NOT USED)  

40  

(NOT USED)  

66  

OCIBindByPos  

15  

(NOT USED)  

41  

(NOT USED)  

67  

OCIBindByName  

16  

(NOT USED)  

42  

OCILobCopy  

68  

OCILobAssign  

17  

OCIBindDynamic  

43  

OCILobAppend  

69  

OCILobIsEqual  

18  

OCIBindObject  

44  

OCILobErase  

70  

OCILobLocatorIsInit  

19  

(NOT USED)  

45  

OCILobGetLength  

71  

OCILobEnableBuffering  

20  

OCIBindArrayOfStruct  

46  

OCILobTrim  

72  

OCILobCharSetID  

21  

OCIStmtExecute  

47  

OCILobRead  

73  

OCILobCharSetForm  

22  

(NOT USED)  

48  

OCILobWrite  

74  

OCILobFileSetName  

23  

(NOT USED)  

49  

(NOT USED)  

75  

OCILobFileGetName  

24  

(NOT USED)  

50  

OCIBreak  

76  

OCILogon  

25  

OCIDefineObject  

51  

OCIServerVersion  

77  

OCILogoff  

26  

OCIDefineDynamic  

52  

(NOT USED)  

78  

OCILobDisableBuffering  

 

79  

OCILobFlushBuffer  

80  

OCILobLoadFromFile  

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 *


Service Context Handle Attributes

OCI_ATTR_SQLCODE

Mode

READ

Description

Returns the code of the last SQL command processed on the service context handle. Each SQL command has a ub4 value.

The SQL command codes are listed in Table B-2 on page B - 8.

Attribute Datatype

ub2 *

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)

Table B-2 SQL Command Codes
Code   SQL Function   Code   SQL Function   Code   SQL Function  

01  

CREATE TABLE  

35  

LOCK  

69  

(NOT USED)  

02  

SET ROLE  

36  

NOOP  

70  

ALTER RESOURCE COST  

03  

INSERT  

37  

RENAME  

71  

CREATE SNAPSHOT LOG  

04  

SELECT  

38  

COMMENT  

72  

ALTER SNAPSHOT LOG  

05  

UPDATE  

39  

AUDIT  

73  

DROP SNAPSHOT LOG  

06  

DROP ROLE  

40  

NO AUDIT  

74  

CREATE SNAPSHOT  

07  

DROP VIEW  

41  

ALTER INDEX  

75  

ALTER SNAPSHOT  

08  

DROP TABLE  

42  

CREATE EXTERNAL DATABASE  

76  

DROP SNAPSHOT  

09  

DELETE  

43  

DROP EXTERNAL DATABASE  

77  

CREATE TYPE  

10  

CREATE VIEW  

44  

CREATE DATABASE  

78  

DROP TYPE  

11  

DROP USER  

45  

ALTER DATABASE  

79  

ALTER ROLE  

12  

CREATE ROLE  

46  

CREATE ROLLBACK SEGMENT  

80  

ALTER TYPE  

13  

CREATE SEQUENCE  

47  

ALTER ROLLBACK SEGMENT  

81  

CREATE TYPE BODY  

14  

ALTER SEQUENCE  

48  

DROP ROLLBACK SEGMENT  

82  

ALTER TYPE BODY  

15  

(NOT USED)  

49  

CREATE TABLESPACE  

83  

DROP TYPE BODY  

16  

DROP SEQUENCE  

50  

ALTER TABLESPACE  

84  

DROP LIBRARY  

17  

CREATE SCHEMA  

51  

DROP TABLESPACE  

85  

TRUNCATE TABLE  

18  

CREATE CLUSTER  

52  

ALTER SESSION  

86  

TRUNCATE CLUSTER  

19  

CREATE USER  

53  

ALTER USER  

87  

CREATE BITMAPFILE  

20  

CREATE INDEX  

54  

COMMIT (WORK)  

88  

ALTER VIEW  

21  

DROP INDEX  

55  

ROLLBACK  

89  

DROP BITMAPFILE  

22  

DROP CLUSTER  

56  

SAVEPOINT  

90  

SET CONSTRAINTS  

23  

VALIDATE INDEX  

57  

CREATE CONTROL FILE  

91  

CREATE FUNCTION  

24  

CREATE PROCEDURE  

58  

ALTER TRACING  

92  

ALTER FUNCTION  

25  

ALTER PROCEDURE  

59  

CREATE TRIGGER  

93  

DROP FUNCTION  

26  

ALTER TABLE  

60  

ALTER TRIGGER  

94  

CREATE PACKAGE  

27  

EXPLAIN  

61  

DROP TRIGGER  

95  

ALTER PACKAGE  

28  

GRANT  

62  

ANALYZE TABLE  

96  

DROP PACKAGE  

29  

REVOKE  

63  

ANALYZE INDEX  

97  

CREATE PACKAGE BODY  

30  

CREATE SYNONYM  

64  

ANALYZE CLUSTER  

98  

ALTER PACKAGE BODY  

31  

DROP SYNONYM  

65  

CREATE PROFILE  

99  

DROP PACKAGE BODY  

32  

ALTER SYSTEM SWITCH LOG  

66  

DROP PROFILE  

157  

CREATE DIRECTORY  

33  

SET TRANSACTION  

67  

ALTER PROFILE  

158  

DROP DIRECTORY  

34  

PL/SQL EXECUTE  

68  

DROP PROCEDURE  

159  

CREATE LIBRARY  

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 Oracle7 mode (e.g., through an OCISvcCtxToLda() call). A non-zero (true) return value indicates that the application is currently running in Oracle8 mode, a zero (false) return value indicates that the application is currently running in Oracle7 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_ENV

Mode

READ

Description

Returns the environment context associated with the server context.

Attribute Datatype

OCIEnv **

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

The OCI function codes are listed in Table B-1 on page B-5.

Attribute Datatype

ub4 *

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 Oracle7 mode (e.g., through an OCISvcCtxToLda() call). A non-zero (true) return value indicates that the application is currently running in Oracle8 mode, a zero (false) return value indicates that the application is currently running in Oracle7 mode.

Attribute Datatype

ub1 *

OCI_ATTR_FOCBK

Mode

READ/WRITE

Description

See "Application Failover Callbacks" on page 7-36 for more information.

Attribute Datatype

OCIFocbkStruct *


User Session Handle Attributes

OCI_ATTR_USERNAME

Mode

WRITE

Description

Specifies a username to use for authentication.

Attribute Datatype

text *

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_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value. The OCI function codes are listed in Table B-1 on page B-5.

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 B-2 on page B - 8.

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:

ub2 *

OCI_ATTR_ROWID

Mode

READ

Description

Returns the rowid of the current row inserted, updated or fetched in a character string format. If execute had been a multiple row operation then, len should contain the iteration number of the row the application is interested in. When connected to an Oracle7 Server only the rowid of the last row inserted, updated, or fetched can be obtained.

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 *


Bind Handle Attributes

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value. The OCI function codes are listed in Table B-1 on page B-5.

Attribute Datatype

ub4 *

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

See "Character Count Attribute" on page 5-26.

Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

Character set ID of the bind 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" on page 5-26.

Attribute Datatype

sb4 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Sets the number of digits to the right of the decimal point for fields where the data type is SQLT_PDN.

Attribute Datatype

ub2 *

OCI_ATTR_PDFMT

Mode

WRITE

Description

Specifies a format string.

Attribute Datatype

text **

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_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

The OCI function codes are listed in Table B-1 on page B-5.

Attribute Datatype

ub4 *

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.

Attribute Datatype

ub2 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

The character set form of the define handle.

Attribute Datatype

ub1 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Sets the number of digits to the right of the decimal point for fields where the data type is SQLT_PDN.

Attribute Datatype

ub2 *

OCI_ATTR_PDFMT

Mode

WRITE

Description

Specifies a format string.

Attribute Datatype

text **


Describe Handle Attributes

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" on page 8-21.

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 Oracle8 Application Developer's Guide.

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

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.




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index