Oracle Call Interface Programmer's Guide, Volumes 1 & 2 Release 8.0 A58234-01 |
Library | Product | Contents | Index

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

- Environment Handle Attributes
- Service Context Handle Attributes
- Server Handle Attributes
- User Session Handle Attributes
- Transaction Handle Attributes
- Statement Handle Attributes
- Bind Handle Attributes
- Define Handle Attributes
- Describe Handle Attributes
- Parameter Descriptor Attributes
- LOB Locator Attributes
- Complex Object Attributes
- Advanced Queueing Descriptor Attributes

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

- OCI_STMT_SELECT
- OCI_STMT_UPDATE
- OCI_STMT_DELETE
- OCI_STMT_INSERT
- OCI_STMT_CREATE
- OCI_STMT_DROP
- OCI_STMT_ALTER
- OCI_STMT_BEGIN (PL/SQL statement)
- OCI_STMT_DECLARE (PL/SQL statement) Attribute Datatype

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_ENQ_BEFORE - the message is enqueued ahead of the message specified by OCI_ATTR_RELATIVE_MSGID.
- OCI_ENQ_TOP - the message is enqueued ahead of any other messages.

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

- OCI_ENQ_ON_COMMIT - the enqueue is part of the current transaction. The operation is complete when the transaction commits. This is the default case.
- OCI_ENQ_IMMEDIATE - the enqueue is not part of the current transaction. The operation constitutes a transaction of its own.

## 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_DEQ_BROWSE - read the message without acquiring any lock on the message. This is equivalent to a SELECT statement.
- OCI_DEQ_LOCKED - read and obtain a write lock on the message. The lock lasts for the duration of the transaction. This is equivalent to a SELECT FOR UPDATE statement.
- OCI_DEQ_REMOVE - read the message and update or delete it. This is the default. The message can be retained in the queue table based on the retention properties.

### 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_DEQ_FIRST_MSG - retrieves the first message which is available and matches the search criteria. This will reset the position to the beginning of the queue.
- OCI_DEQ_NEXT_MSG - retrieves the next message which is available and matches the search criteria. If the previous message belongs to a message group, AQ will retrieve the next available message which matches the search criteria and belongs to the message group. This is the default.
- OCI_DEQ_NEXT_TRANSACTION - skips the remainder of the current transaction group (if any) and retrieves the first message of the next transaction group. This option can only be used if message grouping is enabled for the current queue.

### 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_DEQ_ON_COMMIT - the dequeue will be part of the current transaction. This is the default case.
- OCI_DEQ_IMMEDIATE - the dequeued message is not part of the current transaction. It constitutes a transaction on its own.

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

- OCI_DEQ_WAIT_FOREVER - wait forever. This is the default.
- OCI_DEQ_NO_WAIT - do not wait.

## 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_MSG_NO_DELAY - indicates the message is available for immediate dequeuing.

### 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_MSG_NO_EXPIRATION - the message will not expire.

### 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_MSG_WAITING - the message delay has not yet been reached.
- OCI_MSG_READY - the message is ready to be processed.
- OCI_MSG_PROCESSED - the message has been processed and is retained.
- OCI_MSG_EXPIRED - the message has been moved to the exception queue.

### 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
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index