Oracle Advanced Queuing (A/Q)

Detailed Description

OcilibCApiDirectPath

OCILIB supports Oracle Advanced Queues features

Let's Oracle talk about this features !

Oracle Queues (from Oracle Streams - Advanced Queuing User's Guide)

Oracle Streams AQ provides database-integrated message queuing functionality. It is built on top of Oracle Streams and leverages the functions of Oracle Database so that messages can be stored persistently, propagated between queues on different computers and databases, and transmitted using Oracle Net Services and HTTP(S). Because Oracle Streams AQ is implemented in database tables, all operational benefits of high availability, scalability, and reliability are also applicable to queue data. Standard database features such as recovery, restart, and security are supported by Oracle Streams AQ. You can use database development and management tools such as Oracle Enterprise Manager to monitor queues. Like other database tables, queue tables can be imported and exported.

OCILIB implementation

OCILIB provides a (nearly) full C implementation of Advanced Queues available in Oracle OCI and proposes the following data types :

• OCI_Msg : Implementation of message to enqueue/dequeue from/to queues
• OCI_Enqueue : Implementation of enqueuing process
• OCI_Dequeue : Implementation of dequeuing process
• OCI_Agent : Implementation of Advanced queues Agents

OCILIB support AQ messages notification with Oracle Client 10gR2 or above

Note that the only AQ features not supported yet by OCILIB are :

• Payloads of type AnyData
• Enqueuing/dequeuing arrays of messages
• Optional delivery mode introduced in 10gR2

OCILIB provides as well a C API to administrate queues and queue tables initially reserved to PL/SQL and Java (wrappers around PL/SQL calls). This API, based on internal PL/SQL calls wrapping the DBMS_AQADM packages procedures, allow the following actions :

• create, alter, drop and purge queue tables (OCI_QueueTableXXX calls)
• create, alter, drop, start, stop queues (OCI_QueueXXX calls)

Note that the user connected to the database needs particular privileges to manipulate or administrate queues (See Oracle Streams - Advanced Queuing User's Guide for more information on these privileges)

Example

#include "ocilib.h"
 
/* requires script demo/queue.sql */
 
void err_handler(OCI_Error *err)
{
    printf("%s\n", OCI_ErrorGetString(err));
}
 
int main(int argc, char *argv[])
{
    OCI_Connection *con;
    OCI_Enqueue    *enq;
    OCI_Dequeue    *deq;
    OCI_Msg        *msg;
    OCI_TypeInfo   *inf;
    OCI_Object     *obj;
 
    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
    {
        return EXIT_FAILURE;
    }
 
    con = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
 
    OCI_QueueTableCreate(con, "message_queue_table", "message_t", NULL, NULL, FALSE, OCI_AGM_NONE, NULL,  0, 0, NULL);
    OCI_QueueCreate(con, "message_queue", "message_queue_table", OCI_AQT_NORMAL, 0, 0, 0, FALSE, NULL);
    OCI_QueueStart(con, "message_queue", TRUE, TRUE);
  
    inf = OCI_TypeInfoGet(con, "message_t", OCI_TIF_TYPE);
 
    enq = OCI_EnqueueCreate(inf, "message_queue");
    deq = OCI_DequeueCreate(inf, "message_queue");
 
    msg = OCI_MsgCreate(inf);
    obj = OCI_ObjectCreate(con, inf);
 
    OCI_ObjectSetString(obj, "title", "NEXT MEETING");
    OCI_ObjectSetString(obj, "content", "12:00 PM IN STARBUCKS");
 
    OCI_MsgSetObject(msg, obj);
 
    OCI_EnqueuePut(enq, msg);
 
    OCI_MsgFree(msg);
    OCI_ObjectFree(obj);
 
    OCI_Commit(con);
 
    msg = OCI_DequeueGet(deq);
    obj = OCI_MsgGetObject(msg);
 
    printf("MSG '%s' => %s\n", OCI_ObjectGetString(obj, "title"),  OCI_ObjectGetString(obj, "content"));
 
    OCI_EnqueueFree(enq);
    OCI_DequeueFree(deq);
 
    OCI_QueueStop(con, "message_queue", TRUE, TRUE, FALSE);
    OCI_QueueDrop(con, "message_queue");
    OCI_QueueTableDrop(con, "message_queue_table", TRUE);
 
    OCI_ConnectionFree(con);
 
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Functions
OCI_SYM_PUBLIC OCI_Msg *OCI_API	OCI_MsgCreate (OCI_TypeInfo *typinf)
	Create a message object based on the given payload type.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgFree (OCI_Msg *msg)
	Free a message object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgReset (OCI_Msg *msg)
	Reset all attributes of a message object.
OCI_SYM_PUBLIC OCI_Object *OCI_API	OCI_MsgGetObject (OCI_Msg *msg)
	Get the object payload of the given message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetObject (OCI_Msg *msg, OCI_Object *obj)
	Set the object payload of the given message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgGetRaw (OCI_Msg *msg, void *raw, unsigned int *size)
	Get the RAW payload of the given message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetRaw (OCI_Msg *msg, const void *raw, unsigned int size)
	Set the RAW payload of the given message.
OCI_SYM_PUBLIC int OCI_API	OCI_MsgGetAttemptCount (OCI_Msg *msg)
	Return the number of attempts that have been made to dequeue the message.
OCI_SYM_PUBLIC int OCI_API	OCI_MsgGetEnqueueDelay (OCI_Msg *msg)
	Return the number of seconds that a message is delayed for dequeuing.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetEnqueueDelay (OCI_Msg *msg, int value)
	set the number of seconds to delay the enqueued message
OCI_SYM_PUBLIC OCI_Date *OCI_API	OCI_MsgGetEnqueueTime (OCI_Msg *msg)
	return the time the message was enqueued
OCI_SYM_PUBLIC int OCI_API	OCI_MsgGetExpiration (OCI_Msg *msg)
	Return the duration that the message is available for dequeuing.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetExpiration (OCI_Msg *msg, int value)
	set the duration that the message is available for dequeuing
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_MsgGetState (OCI_Msg *msg)
	Return the state of the message at the time of the dequeue.
OCI_SYM_PUBLIC int OCI_API	OCI_MsgGetPriority (OCI_Msg *msg)
	Return the priority of the message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetPriority (OCI_Msg *msg, int value)
	Set the priority of the message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgGetID (OCI_Msg *msg, void *id, unsigned int *len)
	Return the ID of the message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgGetOriginalID (OCI_Msg *msg, void *id, unsigned int *len)
	Return the original ID of the message in the last queue that generated this message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetOriginalID (OCI_Msg *msg, const void *id, unsigned int len)
	Set the original ID of the message in the last queue that generated this message.
OCI_SYM_PUBLIC OCI_Agent *OCI_API	OCI_MsgGetSender (OCI_Msg *msg)
	Return the original sender of a message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetSender (OCI_Msg *msg, OCI_Agent *sender)
	Set the original sender of a message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetConsumers (OCI_Msg *msg, OCI_Agent **consumers, unsigned int count)
	Set the recipient list of a message to enqueue.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_MsgGetCorrelation (OCI_Msg *msg)
	Get the correlation identifier of the message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetCorrelation (OCI_Msg *msg, const otext *correlation)
	set the correlation identifier of the message
OCI_SYM_PUBLIC const otext *OCI_API	OCI_MsgGetExceptionQueue (OCI_Msg *msg)
	Get the Exception queue name of the message.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MsgSetExceptionQueue (OCI_Msg *msg, const otext *queue)
	Set the name of the queue to which the message is moved to if it cannot be processed successfully.
OCI_SYM_PUBLIC OCI_Enqueue *OCI_API	OCI_EnqueueCreate (OCI_TypeInfo *typinf, const otext *name)
	Create a Enqueue object for the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_EnqueueFree (OCI_Enqueue *enqueue)
	Free a Enqueue object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_EnqueuePut (OCI_Enqueue *enqueue, OCI_Msg *msg)
	Enqueue a message on the queue associated to the Enqueue object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_EnqueueSetSequenceDeviation (OCI_Enqueue *enqueue, unsigned int sequence)
	Set the enqueuing sequence of messages to put in the queue.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_EnqueueGetSequenceDeviation (OCI_Enqueue *enqueue)
	Return the sequence deviation of messages to enqueue to the queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_EnqueueSetVisibility (OCI_Enqueue *enqueue, unsigned int visibility)
	Set whether the new message is enqueued as part of the current transaction.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_EnqueueGetVisibility (OCI_Enqueue *enqueue)
	Get the enqueuing/locking behavior.
OCI_SYM_PUBLIC boolean OCI_API	OCI_EnqueueSetRelativeMsgID (OCI_Enqueue *enqueue, const void *id, unsigned int len)
	Set a message identifier to use for enqueuing messages using a sequence deviation.
OCI_SYM_PUBLIC boolean OCI_API	OCI_EnqueueGetRelativeMsgID (OCI_Enqueue *enqueue, void *id, unsigned int *len)
	Get the current associated message identifier used for enqueuing messages using a sequence deviation.
OCI_SYM_PUBLIC OCI_Dequeue *OCI_API	OCI_DequeueCreate (OCI_TypeInfo *typinf, const otext *name)
	Create a Dequeue object for the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueFree (OCI_Dequeue *dequeue)
	Free a Dequeue object.
OCI_SYM_PUBLIC OCI_Msg *OCI_API	OCI_DequeueGet (OCI_Dequeue *dequeue)
	Dequeue messages from the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSubscribe (OCI_Dequeue *dequeue, unsigned int port, unsigned int timeout, POCI_NOTIFY_AQ callback)
	Subscribe for asynchronous messages notifications.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueUnsubscribe (OCI_Dequeue *dequeue)
	Unsubscribe for asynchronous messages notifications.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetConsumer (OCI_Dequeue *dequeue, const otext *consumer)
	Set the current consumer name to retrieve message for.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_DequeueGetConsumer (OCI_Dequeue *dequeue)
	Get the current consumer name associated with the dequeuing process.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetCorrelation (OCI_Dequeue *dequeue, const otext *pattern)
	set the correlation identifier of the message to be dequeued
OCI_SYM_PUBLIC const otext *OCI_API	OCI_DequeueGetCorrelation (OCI_Dequeue *dequeue)
	Get the correlation identifier of the message to be dequeued.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetRelativeMsgID (OCI_Dequeue *dequeue, const void *id, unsigned int len)
	Set the message identifier of the message to be dequeued.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueGetRelativeMsgID (OCI_Dequeue *dequeue, void *id, unsigned int *len)
	Get the message identifier of the message to be dequeued.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetVisibility (OCI_Dequeue *dequeue, unsigned int visibility)
	Set whether the new message is dequeued as part of the current transaction.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_DequeueGetVisibility (OCI_Dequeue *dequeue)
	Get the dequeuing/locking behavior.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetMode (OCI_Dequeue *dequeue, unsigned int mode)
	Set the dequeuing/locking behavior.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_DequeueGetMode (OCI_Dequeue *dequeue)
	Get the dequeuing/locking behavior.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetNavigation (OCI_Dequeue *dequeue, unsigned int position)
	Set the position of messages to be retrieved.
OCI_SYM_PUBLIC unsigned int OCI_API	OCI_DequeueGetNavigation (OCI_Dequeue *dequeue)
	Return the navigation position of messages to retrieve from the queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetWaitTime (OCI_Dequeue *dequeue, int timeout)
	set the time that OCIDequeueGet() waits for messages if no messages are currently available
OCI_SYM_PUBLIC int OCI_API	OCI_DequeueGetWaitTime (OCI_Dequeue *dequeue)
	Return the time that OCIDequeueGet() waits for messages if no messages are currently available.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DequeueSetAgentList (OCI_Dequeue *dequeue, OCI_Agent **consumers, unsigned int count)
	Set the Agent list to listen to message for.
OCI_SYM_PUBLIC OCI_Agent *OCI_API	OCI_DequeueListen (OCI_Dequeue *dequeue, int timeout)
	Listen for messages that match any recipient of the associated Agent list.
OCI_SYM_PUBLIC OCI_Agent *OCI_API	OCI_AgentCreate (OCI_Connection *con, const otext *name, const otext *address)
	Create an AQ agent object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_AgentFree (OCI_Agent *agent)
	Free an AQ agent object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_AgentSetName (OCI_Agent *agent, const otext *name)
	Set the given AQ agent name.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_AgentGetName (OCI_Agent *agent)
	Get the given AQ agent name.
OCI_SYM_PUBLIC boolean OCI_API	OCI_AgentSetAddress (OCI_Agent *agent, const otext *address)
	Set the given AQ agent address.
OCI_SYM_PUBLIC const otext *OCI_API	OCI_AgentGetAddress (OCI_Agent *agent)
	Get the given AQ agent address.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueCreate (OCI_Connection *con, const otext *queue_name, const otext *queue_table, unsigned int queue_type, unsigned int max_retries, unsigned int retry_delay, unsigned int retention_time, boolean dependency_tracking, const otext *comment)
	Create a queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueAlter (OCI_Connection *con, const otext *queue_name, unsigned int max_retries, unsigned int retry_delay, unsigned int retention_time, const otext *comment)
	Alter the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueDrop (OCI_Connection *con, const otext *queue_name)
	Drop the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueStart (OCI_Connection *con, const otext *queue_name, boolean enqueue, boolean dequeue)
	Start the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueStop (OCI_Connection *con, const otext *queue_name, boolean enqueue, boolean dequeue, boolean wait)
	Stop enqueuing or dequeuing or both on the given queue.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueTableCreate (OCI_Connection *con, const otext *queue_table, const otext *queue_payload_type, const otext *storage_clause, const otext *sort_list, boolean multiple_consumers, unsigned int message_grouping, const otext *comment, unsigned int primary_instance, unsigned int secondary_instance, const otext *compatible)
	Create a queue table for messages of the given type.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueTableAlter (OCI_Connection *con, const otext *queue_table, const otext *comment, unsigned int primary_instance, unsigned int secondary_instance)
	Alter the given queue table.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueTableDrop (OCI_Connection *con, const otext *queue_table, boolean force)
	Drop the given queue table.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueTablePurge (OCI_Connection *con, const otext *queue_table, const otext *purge_condition, boolean block, unsigned int delivery_mode)
	Purge messages from the given queue table.
OCI_SYM_PUBLIC boolean OCI_API	OCI_QueueTableMigrate (OCI_Connection *con, const otext *queue_table, const otext *compatible)
	Migrate a queue table from one version to another.

Function Documentation

OCI_MsgCreate()

OCI_SYM_PUBLIC OCI_Msg *OCI_API OCI_MsgCreate

(

OCI_TypeInfo *

typinf

)

#include <api.h>

Create a message object based on the given payload type.

Parameters

typinf

- Type info handle

Note

OCILIB supports 2 type of message payload :

• Oracle types (UDT)
• RAW data

Oracle Type AnyData is not supported in the current version of OCILIB

the parameter 'typinf' indicates the type of payload :

• For object payload, retrieve the object type information handle with OCI_TypeInfoGet() using the object type name
• For RAW payload, you MUST pass the object type information retrieved with OCI_TypeInfoGet() using "SYS.RAW" as object type name

Warning

Newly created Message handles have NULL payloads. For Message handling Objects payloads, OCI_MsgGetObject() returns NULL until an object handle is assigned to the message.

Note

When a local OCI_Msg handle is enqueued, it keeps its attributes. If it's enqueued again, another identical message is posted into the queue. To reset a message and empty all its properties, call OCI_MsgReset() Note that OCI_MsgReset() clears the message payload.

Returns

Return the message handle on success otherwise NULL on failure

Referenced by ocilib::Message::Message().

OCI_MsgFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgFree

(

OCI_Msg *

msg

)

#include <api.h>

Free a message object.

Parameters

msg	- Message handle

Warning

Only message handles created with OCI_MsgCreate() should be freed by OCI_MsgFree()

Returns

TRUE on success otherwise FALSE

OCI_MsgReset()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgReset

(

OCI_Msg *

msg

)

#include <api.h>

Reset all attributes of a message object.

Parameters

msg	- Message handle

Note

This function calls OCI_MsgSetxxx() with default or NULL attributes

Warning

OCI_MsgReset() clears the message payload and set it to NULL For messages handling objects payloads, OCI_MsgSetObject() must be called again to assign a payload.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::Reset().

OCI_MsgGetObject()

OCI_SYM_PUBLIC OCI_Object *OCI_API OCI_MsgGetObject

(

OCI_Msg *

msg

)

#include <api.h>

Get the object payload of the given message.

Parameters

msg	- Message handle

Returns

Return the object handle on success otherwise NULL on failure or if payload is NULL

OCI_MsgSetObject()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetObject	(	OCI_Msg *	msg,
		OCI_Object *	obj
	)

#include <api.h>

Set the object payload of the given message.

Parameters

msg	- Message handle
obj	- Object handle

Returns

TRUE on success otherwise FALSE

OCI_MsgGetRaw()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgGetRaw	(	OCI_Msg *	msg,
		void *	raw,
		unsigned int *	size
	)

#include <api.h>

Get the RAW payload of the given message.

Parameters

msg	- Message handle
raw	- Input buffer
size	- Input buffer maximum size

Note

On output, parameter 'size' holds the number of bytes copied into the given buffer

Returns

TRUE on success otherwise FALSE on failure or if payload is object based.

OCI_MsgSetRaw()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetRaw	(	OCI_Msg *	msg,
		const void *	raw,
		unsigned int	size
	)

#include <api.h>

Set the RAW payload of the given message.

Parameters

msg	- Message handle
raw	- Raw data
size	- Raw data size

Returns

TRUE on success otherwise FALSE on failure or if payload is object based.

OCI_MsgGetAttemptCount()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetAttemptCount

(

OCI_Msg *

msg

)

#include <api.h>

Return the number of attempts that have been made to dequeue the message.

Parameters

msg	- Message handle

Referenced by ocilib::Message::GetAttemptCount().

OCI_MsgGetEnqueueDelay()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetEnqueueDelay

(

OCI_Msg *

msg

)

#include <api.h>

Return the number of seconds that a message is delayed for dequeuing.

Parameters

msg	- Message handle

Note

see OCI_MsgSetEnqueueDelay() for more details

Referenced by ocilib::Message::GetEnqueueDelay().

OCI_MsgSetEnqueueDelay()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetEnqueueDelay	(	OCI_Msg *	msg,
		int	value
	)

#include <api.h>

set the number of seconds to delay the enqueued message

Parameters

msg	- Message handle
value	- Delay in seconds

Note

The delay represents the number of seconds after which a message is available for dequeuing. When the message is enqueued, its state is set to OCI_AMS_WAITING. When the delay expires, its state is set to OCI_AMS_READY.

If parameter 'value' is set to zero (default value), the message will be immediately available for dequeuing

Warning

Dequeuing by Message ID overrides the delay specification.

Delaying processing requires the queue monitor to be started.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetEnqueueDelay().

OCI_MsgGetEnqueueTime()

OCI_SYM_PUBLIC OCI_Date *OCI_API OCI_MsgGetEnqueueTime

(

OCI_Msg *

msg

)

#include <api.h>

return the time the message was enqueued

Parameters

msg	- Message handle

Note

Only use this function for message dequeued from queues

Referenced by ocilib::Message::GetEnqueueTime().

OCI_MsgGetExpiration()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetExpiration

(

OCI_Msg *

msg

)

#include <api.h>

Return the duration that the message is available for dequeuing.

Parameters

msg	- Message handle

Note

see OCI_MsgSetExpiration() for more details

Referenced by ocilib::Message::GetExpiration().

OCI_MsgSetExpiration()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetExpiration	(	OCI_Msg *	msg,
		int	value
	)

#include <api.h>

set the duration that the message is available for dequeuing

Parameters

msg	- Message handle
value	- duration in seconds

Note

This parameter is an offset from the delay (see OCI_MsgSetEnqueueDelay()) While waiting for expiration, the message state is set to OCI_AMS_READY. If the message is not dequeued before it expires, it will be moved to the exception queue with the state OCI_AMS_EXPIRED.

If parameter 'value' is set to -1 (default value), the message will not expire

Warning

Expiration processing requires the queue monitor to be started.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetExpiration().

OCI_MsgGetState()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_MsgGetState

(

OCI_Msg *

msg

)

#include <api.h>

Return the state of the message at the time of the dequeue.

Parameters

msg	- Message handle

Returns

• OCI_UNKNOWN : the function has failed to get the message state
• OCI_AMS_READY : the message is ready to be processed
• OCI_AMS_WAITING : the message delay has not yet completed
• OCI_AMS_PROCESSED : the message has been processed
• OCI_AMS_EXPIRED : the message has moved to exception queue

Referenced by ocilib::Message::GetState().

OCI_MsgGetPriority()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetPriority

(

OCI_Msg *

msg

)

#include <api.h>

Return the priority of the message.

Parameters

msg	- Message handle

Note

see OCI_MsgSetPriority() for more details

Referenced by ocilib::Message::GetPriority().

OCI_MsgSetPriority()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetPriority	(	OCI_Msg *	msg,
		int	value
	)

#include <api.h>

Set the priority of the message.

Parameters

msg	- Message handle
value	- Message priority

Note

• The priority can be any number, including negative numbers.
• A smaller number indicates higher priority.
• Default value is zero.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetPriority().

OCI_MsgGetID()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgGetID	(	OCI_Msg *	msg,
		void *	id,
		unsigned int *	len
	)

#include <api.h>

Return the ID of the message.

Parameters

msg	- Message handle
id	- Input buffer
len	- Input buffer maximum size

Note

The message ID is :

• generated when the message is enqueued in the queue
• retrieved when the message is dequeued from the queue

On output, parameter 'len' holds the number of bytes copied into the given buffer

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::GetID().

OCI_MsgGetOriginalID()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgGetOriginalID	(	OCI_Msg *	msg,
		void *	id,
		unsigned int *	len
	)

#include <api.h>

Return the original ID of the message in the last queue that generated this message.

Parameters

msg	- Message handle
id	- Input buffer
len	- Input buffer maximum size

Warning

When a message is propagated from/to different queues, this ID is the one generated for the message in the previous queue.

Note

On output, parameter 'len' holds the number of bytes copied into the given buffer

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::GetOriginalID().

OCI_MsgSetOriginalID()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetOriginalID	(	OCI_Msg *	msg,
		const void *	id,
		unsigned int	len
	)

#include <api.h>

Set the original ID of the message in the last queue that generated this message.

Parameters

msg	- Message handle
id	- Message ID
len	- Message ID size

Warning

When a message is propagated from/to different queues, this ID is the one generated for the message in the previous queue.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetOriginalID().

OCI_MsgGetSender()

OCI_SYM_PUBLIC OCI_Agent *OCI_API OCI_MsgGetSender

(

OCI_Msg *

msg

)

#include <api.h>

Return the original sender of a message.

Parameters

msg	- Message handle

Returns

Sender Handle (OCI_Agent *) on success (if set at enqueue time) otherwise NULL

Referenced by ocilib::Message::GetSender().

OCI_MsgSetSender()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetSender	(	OCI_Msg *	msg,
		OCI_Agent *	sender
	)

#include <api.h>

Set the original sender of a message.

Parameters

msg	- Message handle
sender	- Message sender

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetSender().

OCI_MsgSetConsumers()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetConsumers	(	OCI_Msg *	msg,
		OCI_Agent **	consumers,
		unsigned int	count
	)

#include <api.h>

Set the recipient list of a message to enqueue.

Parameters

msg	- Message handle
consumers	- Recipients list (array of agent handles)
count	- Number of recipients

Warning

This function should only be used for queues which allow multiple consumers. The default recipients are the queue subscribers.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetConsumers().

OCI_MsgGetCorrelation()

OCI_SYM_PUBLIC const otext *OCI_API OCI_MsgGetCorrelation

(

OCI_Msg *

msg

)

#include <api.h>

Get the correlation identifier of the message.

Parameters

msg	- Message handle

Note

see OCI_MsgSetCorrelation() for more details

Referenced by ocilib::Message::GetCorrelation().

OCI_MsgSetCorrelation()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetCorrelation	(	OCI_Msg *	msg,
		const otext *	correlation
	)

#include <api.h>

set the correlation identifier of the message

Parameters

msg	- Message handle
correlation	- Message correlation text

Note

see OCI_DequeueSetCorrelation() for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetCorrelation().

OCI_MsgGetExceptionQueue()

OCI_SYM_PUBLIC const otext *OCI_API OCI_MsgGetExceptionQueue

(

OCI_Msg *

msg

)

#include <api.h>

Get the Exception queue name of the message.

Parameters

msg	- Message handle

Warning

When calling this function on a message retrieved with OCI_DequeueGet(), the returned value is NULL if the default exception queue associated with the current queue is used (e.g. no user defined specified at enqueue time for the message)

Note

see OCI_MsgSetExceptionQueue() for more details

Referenced by ocilib::Message::GetExceptionQueue().

OCI_MsgSetExceptionQueue()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetExceptionQueue	(	OCI_Msg *	msg,
		const otext *	queue
	)

#include <api.h>

Set the name of the queue to which the message is moved to if it cannot be processed successfully.

Parameters

msg	- Message handle
queue	- Exception queue name

Warning

From Oracle Documentation :

"Messages are moved into exception queues in two cases : - If the number of unsuccessful dequeue attempts has exceeded the attribute 'max_retries' of given queue - 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. This attribute must refer to a valid queue name."

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Message::SetExceptionQueue().

OCI_EnqueueCreate()

OCI_SYM_PUBLIC OCI_Enqueue *OCI_API OCI_EnqueueCreate	(	OCI_TypeInfo *	typinf,
		const otext *	name
	)

#include <api.h>

Create a Enqueue object for the given queue.

Parameters

typinf	- Type info handle
name	- Queue name

Note

OCILIB supports 2 type of message payload :

• Oracle types (UDT)
• RAW data

Oracle Type AnyData is not supported in the current version of OCILIB

the parameter 'typinf' indicates the type of payload to enqueue to the given queue :

• For object payload, retrieve the object type information handle with OCI_TypeInfoGet() using the object type name
• For RAW payload, you MUST pass the object type information retrieved with OCI_TypeInfoGet() using "SYS.RAW" as object type name

Returns

Return the Enqueue handle on success otherwise NULL on failure

Referenced by ocilib::Enqueue::Enqueue().

OCI_EnqueueFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueFree

(

OCI_Enqueue *

enqueue

)

#include <api.h>

Free a Enqueue object.

Parameters

enqueue

- Enqueue handle

Returns

TRUE on success otherwise FALSE

OCI_EnqueuePut()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueuePut	(	OCI_Enqueue *	enqueue,
		OCI_Msg *	msg
	)

#include <api.h>

Enqueue a message on the queue associated to the Enqueue object.

Parameters

enqueue	- Enqueue handle
msg	- Message handle to enqueue

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Enqueue::Put().

OCI_EnqueueSetSequenceDeviation()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueSetSequenceDeviation	(	OCI_Enqueue *	enqueue,
		unsigned int	sequence
	)

#include <api.h>

Set the enqueuing sequence of messages to put in the queue.

Parameters

enqueue	- Enqueue handle
sequence	- enqueuing sequence

Note

Possible values for parameter 'sequence' :

• OCI_ASD_BEFORE : enqueue message before another message
• OCI_ASD_TOP : enqueue message before all messages

Default value is OCI_ASD_TOP

if the parameter 'sequence' is set to OCI_ASD_BEFORE, the application must call OCI_EnqueueSetRelativeMsgID() before enqueuing the next message in the queue.

In order to stop enqueuing message using a sequence deviation, call OCI_EnqueueSetSequenceDeviation() with the value OCI_ASD_TOP

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Enqueue::SetMode().

OCI_EnqueueGetSequenceDeviation()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_EnqueueGetSequenceDeviation

(

OCI_Enqueue *

enqueue

)

#include <api.h>

Return the sequence deviation of messages to enqueue to the queue.

Parameters

enqueue

- Enqueue handle

Note

see OCI_EnqueueSetSequenceDeviation() for more details

Referenced by ocilib::Enqueue::GetMode().

OCI_EnqueueSetVisibility()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueSetVisibility	(	OCI_Enqueue *	enqueue,
		unsigned int	visibility
	)

#include <api.h>

Set whether the new message is enqueued as part of the current transaction.

Parameters

enqueue	- Enqueue handle
visibility	- Enqueuing visibility

Note

Possible values for parameter 'visibility' :

• OCI_AMV_IMMEDIATE : enqueue is an independent transaction
• OCI_AMV_ON_COMMIT : enqueue is part of current transaction

Default value is OCI_AMV_ON_COMMIT

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Enqueue::SetVisibility().

OCI_EnqueueGetVisibility()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_EnqueueGetVisibility

(

OCI_Enqueue *

enqueue

)

#include <api.h>

Get the enqueuing/locking behavior.

Parameters

enqueue

- Enqueue handle

Note

see OCI_EnqueueSetVisibility() for more details

Referenced by ocilib::Enqueue::GetVisibility().

OCI_EnqueueSetRelativeMsgID()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueSetRelativeMsgID	(	OCI_Enqueue *	enqueue,
		const void *	id,
		unsigned int	len
	)

#include <api.h>

Set a message identifier to use for enqueuing messages using a sequence deviation.

Parameters

enqueue	- Enqueue handle
id	- message identifier
len	- pointer to message identifier length

Note

This call is only valid if OCI_EnqueueSetSequenceDeviation() has been called with the value OCI_ASD_BEFORE

Warning

if the function cannot assign the message id, the content of the parameter 'len' is set to zero.

Note

see OCI_EnqueueSetSequenceDeviation() for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Enqueue::SetRelativeMsgID().

OCI_EnqueueGetRelativeMsgID()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueGetRelativeMsgID	(	OCI_Enqueue *	enqueue,
		void *	id,
		unsigned int *	len
	)

#include <api.h>

Get the current associated message identifier used for enqueuing messages using a sequence deviation.

Parameters

enqueue	- Enqueue handle
id	- buffer to receive the message identifier
len	- pointer to buffer max length

Warning

When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id'

Note

see OCI_EnqueueGetRelativeMsgID() for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Enqueue::GetRelativeMsgID().

OCI_DequeueCreate()

OCI_SYM_PUBLIC OCI_Dequeue *OCI_API OCI_DequeueCreate	(	OCI_TypeInfo *	typinf,
		const otext *	name
	)

#include <api.h>

Create a Dequeue object for the given queue.

Parameters

typinf	- Type info handle
name	- Queue name

Note

OCILIB supports 2 type of message payload :

• Oracle types (UDT)
• RAW data

Oracle Type AnyData is not supported in the current version of OCILIB

the parameter 'typinf' indicates the type of payload to dequeue from the given queue :

• For object payload, retrieve the object type information handle with OCI_TypeInfoGet() using the object type name
• For RAW payload, you MUST pass the object type information retrieved with OCI_TypeInfoGet() using "SYS.RAW" as object type name

Returns

Return the Dequeue handle on success otherwise NULL on failure

Referenced by ocilib::Dequeue::Dequeue().

OCI_DequeueFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueFree

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Free a Dequeue object.

Parameters

dequeue

- Dequeue handle

Returns

TRUE on success otherwise FALSE

OCI_DequeueGet()

OCI_SYM_PUBLIC OCI_Msg *OCI_API OCI_DequeueGet

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Dequeue messages from the given queue.

Parameters

dequeue

- Dequeue handle

Warning

The returned message is handled by the dequeue object. Do not release it with OCI_MsgFree()

When dequeuing from a multiple consumer queue, you need to set the navigation mode to OCI_ADN_FIRST_MSG using OCI_DequeueSetNavigation()

Returns

Message handle on success otherwise NULL on failure or on timeout

Referenced by ocilib::Dequeue::Get().

OCI_DequeueSubscribe()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSubscribe	(	OCI_Dequeue *	dequeue,
		unsigned int	port,
		unsigned int	timeout,
		POCI_NOTIFY_AQ	callback
	)

#include <api.h>

Subscribe for asynchronous messages notifications.

Parameters

dequeue	- Dequeue handle
port	- Port to use for notifications
timeout	- notification timeout
callback	- User handler callback fired when messages are ready to be dequeued

Note

OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use asynchronous messages notifications

Requires Oracle Client 10gR2 or above

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::Subscribe().

OCI_DequeueUnsubscribe()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueUnsubscribe

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Unsubscribe for asynchronous messages notifications.

Parameters

dequeue

- Dequeue handle

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::Unsubscribe().

OCI_DequeueSetConsumer()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetConsumer	(	OCI_Dequeue *	dequeue,
		const otext *	consumer
	)

#include <api.h>

Set the current consumer name to retrieve message for.

Parameters

dequeue	- Dequeue handle
consumer	- consumer name

Warning

If a queue is not set up for multiple consumers, OCI_DequeueSetConsumer() should not be called or called with parameter 'consumer' set to NULL

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetConsumer().

OCI_DequeueGetConsumer()

OCI_SYM_PUBLIC const otext *OCI_API OCI_DequeueGetConsumer

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Get the current consumer name associated with the dequeuing process.

Parameters

dequeue

- Dequeue handle

Note

see OCI_DequeueSetConsumer() for more details

Referenced by ocilib::Dequeue::GetConsumer().

OCI_DequeueSetCorrelation()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetCorrelation	(	OCI_Dequeue *	dequeue,
		const otext *	pattern
	)

#include <api.h>

set the correlation identifier of the message to be dequeued

Parameters

dequeue	- Dequeue handle
pattern	- correlation identifier

Note

Special pattern matching characters, such as "%" or "_" can be used. If more than one message satisfies the pattern, the order of dequeuing is undetermined.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetCorrelation().

OCI_DequeueGetCorrelation()

OCI_SYM_PUBLIC const otext *OCI_API OCI_DequeueGetCorrelation

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Get the correlation identifier of the message to be dequeued.

Parameters

dequeue

- Dequeue handle

Note

see OCI_DequeueSetCorrelation() for more details

Referenced by ocilib::Dequeue::GetCorrelation().

OCI_DequeueSetRelativeMsgID()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetRelativeMsgID	(	OCI_Dequeue *	dequeue,
		const void *	id,
		unsigned int	len
	)

#include <api.h>

Set the message identifier of the message to be dequeued.

Parameters

dequeue	- Dequeue handle
id	- message identifier
len	- size of the message identifier

Warning

if the function cannot assign the message id, the content of the parameter 'len' is set to zero.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetRelativeMsgID().

OCI_DequeueGetRelativeMsgID()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueGetRelativeMsgID	(	OCI_Dequeue *	dequeue,
		void *	id,
		unsigned int *	len
	)

#include <api.h>

Get the message identifier of the message to be dequeued.

Parameters

dequeue	- Dequeue handle
id	- message identifier
len	- size of the message identifier

Warning

When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id'

Note

see OCI_DequeueSetRelativeMsgID() for more details

Referenced by ocilib::Dequeue::GetRelativeMsgID().

OCI_DequeueSetVisibility()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetVisibility	(	OCI_Dequeue *	dequeue,
		unsigned int	visibility
	)

#include <api.h>

Set whether the new message is dequeued as part of the current transaction.

Parameters

dequeue	- Dequeue handle
visibility	- dequeuing mode

Warning

The visibility parameter is ignored when using the OCI_ADM_BROWSE dequeuing mode (see OCI_DequeueSetMode())

Note

Possible values for parameter 'mode' :

• OCI_AMV_IMMEDIATE : dequeue is an independent transaction
• OCI_AMV_ON_COMMIT : dequeue is part of current transaction

Default value is OCI_AMV_ON_COMMIT

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetVisibility().

OCI_DequeueGetVisibility()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_DequeueGetVisibility

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Get the dequeuing/locking behavior.

Parameters

dequeue

- Dequeue handle

Note

see OCI_DequeueSetVisibility() for more details

Referenced by ocilib::Dequeue::GetVisibility().

OCI_DequeueSetMode()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetMode	(	OCI_Dequeue *	dequeue,
		unsigned int	mode
	)

#include <api.h>

Set the dequeuing/locking behavior.

Parameters

dequeue	- Dequeue handle
mode	- dequeuing mode

Note

Possible values for parameter 'mode' :

• OCI_ADM_BROWSE : read message without acquiring a lock
• OCI_ADM_LOCKED : read and obtain write lock on message
• OCI_ADM_REMOVE : read the message and delete it
• OCI_ADM_REMOVE_NODATA : confirm receipt of the message, but do not deliver the actual message content

Default value is OCI_ADM_REMOVE

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetMode().

OCI_DequeueGetMode()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_DequeueGetMode

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Get the dequeuing/locking behavior.

Parameters

dequeue

- Dequeue handle

Note

see OCI_DequeueSetMode() for more details

Referenced by ocilib::Dequeue::GetMode().

OCI_DequeueSetNavigation()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetNavigation	(	OCI_Dequeue *	dequeue,
		unsigned int	position
	)

#include <api.h>

Set the position of messages to be retrieved.

Parameters

dequeue	- Dequeue handle
position	- navigation position

Note

The dequeuing uses the following sequence :

• find messages using the navigation position
• apply search criteria (message correlation)
• get message

Possible values for parameter 'position' :

• OCI_ADN_FIRST_MSG : retrieves the first message which is available
• OCI_ADN_NEXT_MSG : retrieves the next message which is available
• OCI_ADN_NEXT_TRANSACTION : skips the remainder of the current transaction group (if any) and retrieves the first message of the next transaction group.

Default value is OCI_ADN_NEXT_MSG

Warning

OCI_ADN_NEXT_TRANSACTION can only be used if message grouping is enabled for the given queue.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetNavigation().

OCI_DequeueGetNavigation()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_DequeueGetNavigation

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Return the navigation position of messages to retrieve from the queue.

Parameters

dequeue

- Dequeue handle

Note

see OCI_DequeueSetNavigation() for more details

Referenced by ocilib::Dequeue::GetNavigation().

OCI_DequeueSetWaitTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetWaitTime	(	OCI_Dequeue *	dequeue,
		int	timeout
	)

#include <api.h>

set the time that OCIDequeueGet() waits for messages if no messages are currently available

Parameters

dequeue	- Dequeue handle
timeout	- timeout in seconds

Note

• Any positive values in seconds are valid.
• The value 0 is accepted and means OCIDequeueGet() does not wait for messages and returns immediately if no messages are available
• The value -1 is accepted and means OCIDequeueGet() waits for ever (until a message is available in the queue)

Default value is -1 (wait for ever)

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetWaitTime().

OCI_DequeueGetWaitTime()

OCI_SYM_PUBLIC int OCI_API OCI_DequeueGetWaitTime

(

OCI_Dequeue *

dequeue

)

#include <api.h>

Return the time that OCIDequeueGet() waits for messages if no messages are currently available.

Parameters

dequeue

- Dequeue handle

Note

see OCI_DequeueSetWaitTime() for more details

Referenced by ocilib::Dequeue::GetWaitTime().

OCI_DequeueSetAgentList()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetAgentList	(	OCI_Dequeue *	dequeue,
		OCI_Agent **	consumers,
		unsigned int	count
	)

#include <api.h>

Set the Agent list to listen to message for.

Parameters

dequeue	- Dequeue handle
consumers	- Agent handle array
count	- Number of agents the array

Returns

return TRUE on success otherwise FALSE

Referenced by ocilib::Dequeue::SetAgents().

OCI_DequeueListen()

OCI_SYM_PUBLIC OCI_Agent *OCI_API OCI_DequeueListen	(	OCI_Dequeue *	dequeue,
		int	timeout
	)

#include <api.h>

Listen for messages that match any recipient of the associated Agent list.

Parameters

dequeue	- Dequeue handle
timeout	- Timeout in second

Note

If an Agent handle is returned, messages are available for this agent. In order to retrieve its messages :

• call OCI_DequeueSetConsumer() with the name of agent using OCI_AgentGetName()
• call OCI_DequeueGet() to dequeue it's pending messages

Warning

The return value is valid only until:

• OCIDequeueListen() is called again
• OCI_DequeueFree(à is called to free the Dequeue object So Do not store the handle value across calls to OCIDequeueListen()

Returns

An Agent handle for who messages are available on success otherwise NULL

Referenced by ocilib::Dequeue::Listen().

OCI_AgentCreate()

OCI_SYM_PUBLIC OCI_Agent *OCI_API OCI_AgentCreate	(	OCI_Connection *	con,
		const otext *	name,
		const otext *	address
	)

#include <api.h>

Create an AQ agent object.

Parameters

con	- Connection handle
name	- Agent name
address	- Agent address

Note

An AQ agent object is :

• used as recipient information when enqueuing a message
• used as sender information when dequeuing a message
• used for listening message only from identified senders

the AQ agent address can be any Oracle identifier, up to 128 bytes. the AQ agent name can be any Oracle identifier, up to 30 bytes.

Returns

AQ agent handle on success otherwise NULL

Referenced by ocilib::Agent::Agent().

OCI_AgentFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_AgentFree

(

OCI_Agent *

agent

)

#include <api.h>

Free an AQ agent object.

Parameters

agent

- AQ agent handle

Warning

Only AQ agent handle created with OCI_AgentCreate() should be freed by OCI_AgentFree()

Returns

TRUE on success otherwise FALSE

OCI_AgentSetName()

OCI_SYM_PUBLIC boolean OCI_API OCI_AgentSetName	(	OCI_Agent *	agent,
		const otext *	name
	)

#include <api.h>

Set the given AQ agent name.

Parameters

agent	- AQ agent handle
name	- AQ agent name

Note

the AQ agent name is used to identified an message send or recipient when enqueuing/dequeuing a message

the AQ agent name can be any Oracle identifier, up to 30 bytes.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Agent::SetName().

OCI_AgentGetName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_AgentGetName

(

OCI_Agent *

agent

)

#include <api.h>

Get the given AQ agent name.

Parameters

agent

- AQ agent handle

Returns

AQ agent name on success otherwise NULL on failure

Referenced by ocilib::Agent::GetName().

OCI_AgentSetAddress()

OCI_SYM_PUBLIC boolean OCI_API OCI_AgentSetAddress	(	OCI_Agent *	agent,
		const otext *	address
	)

#include <api.h>

Set the given AQ agent address.

Parameters

agent	- AQ agent handle
address	- AQ agent address

Note

the parameter 'address' must be of the form : [schema.]queue_name[@dblink]

the AQ agent address can be any Oracle identifier, up to 128 bytes.

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Agent::SetAddress().

OCI_AgentGetAddress()

OCI_SYM_PUBLIC const otext *OCI_API OCI_AgentGetAddress

(

OCI_Agent *

agent

)

#include <api.h>

Get the given AQ agent address.

Parameters

agent

- AQ agent handle

Note

See OCI_AgentSetAddress()

Returns

AQ agent address on success otherwise NULL on failure

Referenced by ocilib::Agent::GetAddress().

OCI_QueueCreate()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueCreate	(	OCI_Connection *	con,
		const otext *	queue_name,
		const otext *	queue_table,
		unsigned int	queue_type,
		unsigned int	max_retries,
		unsigned int	retry_delay,
		unsigned int	retention_time,
		boolean	dependency_tracking,
		const otext *	comment
	)

#include <api.h>

Create a queue.

Parameters

con	- Connection handle
queue_name	- Queue name
queue_table	- Queue table name
queue_type	- Queue type
max_retries	- Maximum number of attempts to dequeue a message
retry_delay	- Number of seconds between attempts to dequeue a message
retention_time	- number of seconds a message is retained in the queue table after being dequeued from the queue
dependency_tracking	- Parameter reserved for future use by Oracle (MUST be set to FALSE)
comment	- Description of the queue

Note

Parameter 'queue_name' can specify the schema where to create to queue ([schema.]queue_name) Queue names cannot be longer than 24 characters (Oracle limit for user queues)

Possible values for parameter 'queue_type' :

• OCI_AQT_NORMAL : Normal queue
• OCI_AQT_EXCEPTION : Exception queue
• OCI_AQT_NON_PERSISTENT : Non persistent queue

To set default values, pass :

• queue_type : OCI_AQT_NORMAL
• max_retries : 0
• retry_delay : 0
• retention_time : 0
• comment : NULL

Note

this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Queue::Create().

OCI_QueueAlter()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueAlter	(	OCI_Connection *	con,
		const otext *	queue_name,
		unsigned int	max_retries,
		unsigned int	retry_delay,
		unsigned int	retention_time,
		const otext *	comment
	)

#include <api.h>

Alter the given queue.

Parameters

con	- Connection handle
queue_name	- Queue name
max_retries	- Maximum number of attempts to dequeue a message
retry_delay	- Number of seconds between attempts to dequeue a message
retention_time	- number of seconds a message is retained in the queue table after being dequeued from the queue
comment	- Description of the queue

Note

See OCI_QueueCreate() for more details

Warning

This function updates all attributes handled in the parameter list !

Note

this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Queue::Alter().

OCI_QueueDrop()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueDrop	(	OCI_Connection *	con,
		const otext *	queue_name
	)

#include <api.h>

Drop the given queue.

Parameters

con	- Connection handle
queue_name	- Queue name

Warning

A queue can be dropped only if it has been stopped before.

Note

this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Queue::Drop().

OCI_QueueStart()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueStart	(	OCI_Connection *	con,
		const otext *	queue_name,
		boolean	enqueue,
		boolean	dequeue
	)

#include <api.h>

Start the given queue.

Parameters

con	- Connection handle
queue_name	- Queue name
enqueue	- Enable enqueue
dequeue	- Enable dequeue

Warning

For exception queues, only enqueuing is allowed

Note

this call wraps the PL/SQL procedure DBMS_AQADM.START_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Queue::Start().

OCI_QueueStop()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueStop	(	OCI_Connection *	con,
		const otext *	queue_name,
		boolean	enqueue,
		boolean	dequeue,
		boolean	wait
	)

#include <api.h>

Stop enqueuing or dequeuing or both on the given queue.

Parameters

con	- Connection handle
queue_name	- Queue name
enqueue	- Disable enqueue
dequeue	- Disable dequeue
wait	- Wait for current pending enqueues/dequeues

Warning

A queue cannot be stopped if there are pending transactions against the queue.

Note

this call wraps the PL/SQL procedure DBMS_AQADM.STOP_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::Queue::Stop().

OCI_QueueTableCreate()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTableCreate	(	OCI_Connection *	con,
		const otext *	queue_table,
		const otext *	queue_payload_type,
		const otext *	storage_clause,
		const otext *	sort_list,
		boolean	multiple_consumers,
		unsigned int	message_grouping,
		const otext *	comment,
		unsigned int	primary_instance,
		unsigned int	secondary_instance,
		const otext *	compatible
	)

#include <api.h>

Create a queue table for messages of the given type.

Parameters

con	- Connection handle
queue_table	- Queue table name
queue_payload_type	- Message type name
storage_clause	- Additional clauses for the table storage
sort_list	- Additional columns name to use for sorting
multiple_consumers	- Enable multiple consumers for each messages
message_grouping	- Specifies if messages are grouped within a transaction
comment	- Description of the queue table
primary_instance	- primary owner (instance) of the queue table
secondary_instance	- Owner of the queue table if the primary instance is not available
compatible	- lowest database version with which the queue table is compatible

Note

Parameter 'queue_table' can specify the schema where to create to queue table ([schema.]queue_table) Queue table names cannot be longer than 24 characters (Oracle limit for user queue tables)

Possible values for parameter 'queue_payload_type' :

• For Oracle types (UDT) : use the type name ([schema.].type_name)
• For RAW data : use "SYS.RAW" or "RAW" (depending on Oracle versions - For latest ones, use "RAW")

Possible values for parameter 'message_grouping' :

• OCI_AGM_NONE : each message is treated individually
• OCI_AGM_TRANSACTIONNAL : all messages enqueued in one transaction are considered part of the same group and can be dequeued as a group of related messages.

Possible values for parameter 'compatible' :

• "8.0", "8.1", "10.0"

To set default values, pass :

• storage_clause : NULL
• sort_list : NULL
• message_grouping : OCI_AGM_NONE
• comment : NULL
• primary_instance : 0
• primary_instance : 0
• compatible : NULL

Note

this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::QueueTable::Create().

OCI_QueueTableAlter()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTableAlter	(	OCI_Connection *	con,
		const otext *	queue_table,
		const otext *	comment,
		unsigned int	primary_instance,
		unsigned int	secondary_instance
	)

#include <api.h>

Alter the given queue table.

Parameters

con	- Connection handle
queue_table	- Queue table name
comment	- Description of the queue table
primary_instance	- primary owner (instance) of the queue table
secondary_instance	- Owner of the queue table if the primary instance is not available

Note

See OCI_QueueTableCreate() from more details

this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::QueueTable::Alter().

OCI_QueueTableDrop()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTableDrop	(	OCI_Connection *	con,
		const otext *	queue_table,
		boolean	force
	)

#include <api.h>

Drop the given queue table.

Parameters

con	- Connection handle
queue_table	- Queue table name
force	- Force the deletion of objects related to the queue table

Note

Possible values for 'force' :

• TRUE : all queues using the queue table and their associated propagation schedules are dropped automatically
• FALSE : All the queues using the given queue table must be stopped and dropped before the queue table can be dropped.

this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::QueueTable::Drop().

OCI_QueueTablePurge()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTablePurge	(	OCI_Connection *	con,
		const otext *	queue_table,
		const otext *	purge_condition,
		boolean	block,
		unsigned int	delivery_mode
	)

#include <api.h>

Purge messages from the given queue table.

Parameters

con	- Connection handle
queue_table	- Queue table name
purge_condition	- Optional SQL based conditions (see notes)
block	- Lock all queues using the queue table while doing the purge
delivery_mode	- Type of message to purge

Note

Possible values for parameter 'delivery_mode' :

• OCI_APM_BUFFERED : purge only buffered messages
• OCI_APM_PERSISTENT : purge only persistent messages
• OCI_APM_ALL : purge all messages

For more information about the SQL purge conditions, refer to Oracle Streams - Advanced Queuing User's Guide for more details

Warning

This feature is only available from Oracle 10gR2. This function does nothing and returns TRUE is the server version is < Oracle 10gR2

Note

this call wraps the PL/SQL procedure DBMS_AQADM.PURGE_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::QueueTable::Purge().

OCI_QueueTableMigrate()

OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTableMigrate	(	OCI_Connection *	con,
		const otext *	queue_table,
		const otext *	compatible
	)

#include <api.h>

Migrate a queue table from one version to another.

Parameters

con	- Connection handle
queue_table	- Queue table name
compatible	- Database version with witch the queue table has to migrate

Note

Possible values for parameter 'compatible' :

• "8.0", "8.1", "10.0"

this call wraps the PL/SQL procedure DBMS_AQADM.MIGRATE_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details

Returns

TRUE on success otherwise FALSE

Referenced by ocilib::QueueTable::Migrate().