Functions

Oracle Advanced Queuing (A/Q)


Detailed Description

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

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

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 :

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 informations on these privileges)

Example
#include "ocilib.h"

int main(int argc, char *argv[])
{
    OCI_Connection *con;
    OCI_Enqueue    *enq;
    OCI_Dequeue    *deq;
    OCI_Msg        *msg;
    OCI_TypeInfo   *inf;
    OCI_Object     *obj;
   
    OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT);
     
    con = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);

    inf = OCI_TypeInfoGet(con, "MY_MESSAGE", OCI_TIF_TYPE);
    
    enq = OCI_EnqueueCreate(inf, "my_queue");
    deq = OCI_DequeueCreate(inf, "my_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_ConnectionFree(con);

    OCI_Cleanup();

   return EXIT_SUCCESS;
}

Functions

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

Function Documentation

OCI_EXPORT OCI_Msg* OCI_API OCI_MsgCreate ( OCI_TypeInfo typinf  ) 

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_MsgSetObject() 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 enqeued 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

Definition at line 46 of file msg.c.

References OCI_MsgFree(), and OCI_ObjectCreate().

Referenced by OCI_DequeueCreate().

OCI_EXPORT boolean OCI_API OCI_MsgFree ( OCI_Msg msg  ) 

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

Definition at line 116 of file msg.c.

References OCI_AgentFree(), and OCI_ObjectFree().

Referenced by OCI_DequeueFree(), and OCI_MsgCreate().

OCI_EXPORT boolean OCI_API OCI_MsgReset ( OCI_Msg msg  ) 

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

Definition at line 156 of file msg.c.

References OCI_MsgSetConsumers(), OCI_MsgSetCorrelation(), OCI_MsgSetEnqueueDelay(), OCI_MsgSetExceptionQueue(), OCI_MsgSetExpiration(), OCI_MsgSetObject(), OCI_MsgSetOriginalID(), OCI_MsgSetPriority(), OCI_MsgSetRaw(), and OCI_MsgSetSender().

Referenced by OCI_DequeueGet().

OCI_EXPORT OCI_Object* OCI_API OCI_MsgGetObject ( OCI_Msg msg  ) 

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

Definition at line 196 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetObject ( OCI_Msg msg,
OCI_Object obj 
)

Set the object payload of the given message.

Parameters:
msg - Message handle
obj - Object handle
Returns:
TRUE on success otherwise FALSE

Definition at line 220 of file msg.c.

References OCI_ObjectAssign().

Referenced by OCI_MsgReset().

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

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.

Definition at line 257 of file msg.c.

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

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.

Definition at line 295 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT int OCI_API OCI_MsgGetAttemptCount ( OCI_Msg msg  ) 

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

Parameters:
msg - Message handle

Definition at line 334 of file msg.c.

OCI_EXPORT int OCI_API OCI_MsgGetEnqueueDelay ( OCI_Msg msg  ) 

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

Parameters:
msg - Message handle
Note:
see OCI_MsgSetEnqueueDelay() for more details

Definition at line 365 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetEnqueueDelay ( OCI_Msg msg,
int  value 
)

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

Definition at line 396 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT OCI_Date* OCI_API OCI_MsgGetEnqueueTime ( OCI_Msg msg  ) 

return the time the message was enqueued

Parameters:
msg - Message handle
Note:
Only use this function for message dequeued from queues

Definition at line 428 of file msg.c.

OCI_EXPORT int OCI_API OCI_MsgGetExpiration ( OCI_Msg msg  ) 

Return the duration that the message is available for dequeuing.

Parameters:
msg - Message handle
Note:
see OCI_MsgSetExpiration() for more details

Definition at line 468 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetExpiration ( OCI_Msg msg,
int  value 
)

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

Definition at line 499 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT unsigned int OCI_API OCI_MsgGetState ( OCI_Msg msg  ) 

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

Definition at line 531 of file msg.c.

OCI_EXPORT int OCI_API OCI_MsgGetPriority ( OCI_Msg msg  ) 

Return the priority of the message.

Parameters:
msg - Message handle
Note:
see OCI_MsgSetPriority() for more details

Definition at line 573 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetPriority ( OCI_Msg msg,
int  value 
)

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

Definition at line 604 of file msg.c.

Referenced by OCI_MsgReset().

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

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

Definition at line 637 of file msg.c.

OCI_EXPORT 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.

Parameters:
msg - Message handle
id - Input buffer
len - Input buffer maximum size
Warning:
When a message is propagated from/to differents 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

Definition at line 675 of file msg.c.

OCI_EXPORT 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.

Parameters:
msg - Message handle
id - Message ID
len - Message ID size
Warning:
When a message is propagated from/to differents queues, this ID is the one generated for the message in the previous queue.
Returns:
TRUE on success otherwise FALSE

Definition at line 726 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT OCI_Agent* OCI_API OCI_MsgGetSender ( OCI_Msg msg  ) 

Return the original sender of a message.

Parameters:
msg - Message handle
Returns:
Sender Handle (OCI_Agent *) on success (if set at rnqueue time) otherwise NULL

Definition at line 873 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetSender ( OCI_Msg msg,
OCI_Agent sender 
)

Set the original sender of a message.

Parameters:
msg - Message handle
sender - Message sender
Returns:
TRUE on success otherwise FALSE

Definition at line 910 of file msg.c.

Referenced by OCI_MsgReset().

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

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

Definition at line 941 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT const mtext* OCI_API OCI_MsgGetCorrelation ( OCI_Msg msg  ) 

Get the correlation identifier of the message.

Parameters:
msg - Message handle
Note:
see OCI_MsgSetCorrelation() for more details

Definition at line 767 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetCorrelation ( OCI_Msg msg,
const mtext *  correlation 
)

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

Definition at line 794 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT const mtext* OCI_API OCI_MsgGetExceptionQueue ( OCI_Msg msg  ) 

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 (eg. no user defined specified at enqueue time for the message)
Note:
see OCI_MsgSetExceptionQueue() for more details

Definition at line 820 of file msg.c.

OCI_EXPORT boolean OCI_API OCI_MsgSetExceptionQueue ( OCI_Msg msg,
const mtext *  queue 
)

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

"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

Definition at line 847 of file msg.c.

Referenced by OCI_MsgReset().

OCI_EXPORT OCI_Enqueue* OCI_API OCI_EnqueueCreate ( OCI_TypeInfo typinf,
const mtext *  name 
)

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

Definition at line 46 of file enqueue.c.

References OCI_EnqueueFree().

OCI_EXPORT boolean OCI_API OCI_EnqueueFree ( OCI_Enqueue enqueue  ) 

Free a Enqueue object.

Parameters:
enqueue - Enqueue handle
Returns:
TRUE on success otherwise FALSE

Definition at line 105 of file enqueue.c.

Referenced by OCI_EnqueueCreate().

OCI_EXPORT boolean OCI_API OCI_EnqueuePut ( OCI_Enqueue enqueue,
OCI_Msg msg 
)

Enqueue a message on queue associated to the Enqueue object.

Parameters:
enqueue - Enqueue handle
msg - Message handle to enqueue
Returns:
Message handle on success otherwise NULL on failure or on timeout

Definition at line 126 of file enqueue.c.

OCI_EXPORT boolean OCI_API OCI_EnqueueSetSequenceDeviation ( OCI_Enqueue enqueue,
unsigned int  sequence 
)

Set the enqueing 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

Definition at line 284 of file enqueue.c.

OCI_EXPORT unsigned int OCI_API OCI_EnqueueGetSequenceDeviation ( OCI_Enqueue enqueue  ) 

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

Parameters:
enqueue - Enqueue handle
Note:
see OCI_EnqueueSetSequenceDeviation() for more details

Definition at line 253 of file enqueue.c.

OCI_EXPORT boolean OCI_API OCI_EnqueueSetVisibility ( OCI_Enqueue enqueue,
unsigned int  visibility 
)

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

Parameters:
enqueue - Enqueue handle
visibility - Equeueing mode
Note:
Possible values for parameter 'mode' :
  • 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

Definition at line 221 of file enqueue.c.

OCI_EXPORT unsigned int OCI_API OCI_EnqueueGetVisibility ( OCI_Enqueue enqueue  ) 

Get the enqueueing/locking behavior.

Parameters:
enqueue - Enqueue handle
Note:
see OCI_EnqueueSetVisibility() for more details

Definition at line 190 of file enqueue.c.

OCI_EXPORT 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.

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

Definition at line 367 of file enqueue.c.

OCI_EXPORT 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.

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

Definition at line 316 of file enqueue.c.

OCI_EXPORT OCI_Dequeue* OCI_API OCI_DequeueCreate ( OCI_TypeInfo typinf,
const mtext *  name 
)

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

Definition at line 46 of file dequeue.c.

References OCI_DequeueFree(), and OCI_MsgCreate().

OCI_EXPORT boolean OCI_API OCI_DequeueFree ( OCI_Dequeue dequeue  ) 

Free a Dequeue object.

Parameters:
dequeue - Dequeue handle
Returns:
TRUE on success otherwise FALSE

Definition at line 111 of file dequeue.c.

References OCI_AgentFree(), and OCI_MsgFree().

Referenced by OCI_DequeueCreate().

OCI_EXPORT OCI_Msg* OCI_API OCI_DequeueGet ( OCI_Dequeue dequeue  ) 

Dequeue messages from the given queue.

Parameters:
dequeue - Dequeue handle
Returns:
Message handle on success otherwise NULL on failure or on timeout

Definition at line 212 of file dequeue.c.

References OCI_MsgReset().

OCI_EXPORT boolean OCI_API OCI_DequeueSetConsumer ( OCI_Dequeue dequeue,
const mtext *  consumer 
)

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

Definition at line 332 of file dequeue.c.

OCI_EXPORT const mtext* OCI_API OCI_DequeueGetConsumer ( OCI_Dequeue dequeue  ) 

Get the current consumer name associated with the dequeueing process.

Parameters:
dequeue - Dequeue handle
Note:
see OCI_DequeueSetConsumer() for more details

Definition at line 305 of file dequeue.c.

OCI_EXPORT boolean OCI_API OCI_DequeueSetCorrelation ( OCI_Dequeue dequeue,
const mtext *  pattern 
)

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

Definition at line 385 of file dequeue.c.

OCI_EXPORT const mtext* OCI_API OCI_DequeueGetCorrelation ( OCI_Dequeue dequeue  ) 

Get the correlation identifier of the message to be dequeued.

Parameters:
dequeue - Dequeue handle
Note:
see OCI_DequeueSetCorrelation() for more details

Definition at line 358 of file dequeue.c.

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

Set the message identifier of the message to be dequeued.

Parameters:
dequeue - Dequeue handle
id - message identitier
len - size of the message identitier
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

Definition at line 462 of file dequeue.c.

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

Get the message identifier of the message to be dequeued.

Parameters:
dequeue - Dequeue handle
id - message identitier
len - size of the message identitier
Warning:
When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id'
Note:
see OCI_DequeueSetRelativeMsgID() for more details

Definition at line 411 of file dequeue.c.

OCI_EXPORT boolean OCI_API OCI_DequeueSetVisibility ( OCI_Dequeue dequeue,
unsigned int  visibility 
)

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

Parameters:
dequeue - Dequeue handle
visibility - dequeueing 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

Definition at line 534 of file dequeue.c.

OCI_EXPORT unsigned int OCI_API OCI_DequeueGetVisibility ( OCI_Dequeue dequeue  ) 

Get the dequeueing/locking behavior.

Parameters:
dequeue - Dequeue handle
Note:
see OCI_DequeueSetVisibility() for more details

Definition at line 503 of file dequeue.c.

OCI_EXPORT boolean OCI_API OCI_DequeueSetMode ( OCI_Dequeue dequeue,
unsigned int  mode 
)

Set the dequeueing/locking behavior.

Parameters:
dequeue - Dequeue handle
mode - dequeueing 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

Definition at line 597 of file dequeue.c.

OCI_EXPORT unsigned int OCI_API OCI_DequeueGetMode ( OCI_Dequeue dequeue  ) 

Get the dequeueing/locking behavior.

Parameters:
dequeue - Dequeue handle
Note:
see OCI_DequeueSetMode() for more details

Definition at line 566 of file dequeue.c.

OCI_EXPORT boolean OCI_API OCI_DequeueSetNavigation ( OCI_Dequeue dequeue,
unsigned int  position 
)

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 criterias (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 transactiong roup.
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

Definition at line 660 of file dequeue.c.

OCI_EXPORT unsigned int OCI_API OCI_DequeueGetNavigation ( OCI_Dequeue dequeue  ) 

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

Parameters:
dequeue - Dequeue handle
Note:
see OCI_DequeueSetNavigation() for more details

Definition at line 629 of file dequeue.c.

OCI_EXPORT boolean OCI_API OCI_DequeueSetWaitTime ( OCI_Dequeue dequeue,
int  timeout 
)

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

Definition at line 723 of file dequeue.c.

OCI_EXPORT int OCI_API OCI_DequeueGetWaitTime ( OCI_Dequeue dequeue  ) 

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

Definition at line 692 of file dequeue.c.

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

Set the Agent list to listen to message for.

Parameters:
dequeue - Dequeue handle
consumers - Agent handle array
count - Number of agents the the array
Warning:
Note:
Returns:
return TRUE on success otherwise FALSE

Definition at line 755 of file dequeue.c.

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

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

Definition at line 154 of file dequeue.c.

OCI_EXPORT OCI_Agent* OCI_API OCI_AgentCreate ( OCI_Connection con,
const mtext *  name,
const mtext *  address 
)

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

Definition at line 126 of file agent.c.

OCI_EXPORT boolean OCI_API OCI_AgentFree ( OCI_Agent agent  ) 

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

Definition at line 150 of file agent.c.

Referenced by OCI_DequeueFree(), and OCI_MsgFree().

OCI_EXPORT boolean OCI_API OCI_AgentSetName ( OCI_Agent agent,
const mtext *  name 
)

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

Definition at line 205 of file agent.c.

OCI_EXPORT const mtext* OCI_API OCI_AgentGetName ( OCI_Agent agent  ) 

Get the given AQ agent name.

Parameters:
agent - AQ agent handle
Returns:
AQ agent name on success otherwise NULL on failure

Definition at line 178 of file agent.c.

OCI_EXPORT boolean OCI_API OCI_AgentSetAddress ( OCI_Agent agent,
const mtext *  address 
)

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[].
the AQ agent address can be any Oracle identifier, up to 128 bytes.
Returns:
TRUE on success otherwise FALSE

Definition at line 255 of file agent.c.

OCI_EXPORT const mtext* OCI_API OCI_AgentGetAddress ( OCI_Agent agent  ) 

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

Definition at line 228 of file agent.c.

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

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

Definition at line 46 of file queue.c.

References OCI_BindInt(), OCI_BindString(), OCI_BindUnsignedInt(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

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

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

Definition at line 132 of file queue.c.

References OCI_BindString(), OCI_BindUnsignedInt(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

OCI_EXPORT boolean OCI_API OCI_QueueDrop ( OCI_Connection con,
const mtext *  queue_name 
)

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

Definition at line 201 of file queue.c.

References OCI_BindString(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

OCI_EXPORT boolean OCI_API OCI_QueueStart ( OCI_Connection con,
const mtext *  queue_name,
boolean  enqueue,
boolean  dequeue 
)

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

Definition at line 250 of file queue.c.

References OCI_BindInt(), OCI_BindString(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

OCI_EXPORT boolean OCI_API OCI_QueueStop ( OCI_Connection con,
const mtext *  queue_name,
boolean  enqueue,
boolean  dequeue,
boolean  wait 
)

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

Definition at line 314 of file queue.c.

References OCI_BindInt(), OCI_BindString(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

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

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 - Additionnal 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 shema 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"
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

Definition at line 385 of file queue.c.

References OCI_BindInt(), OCI_BindString(), OCI_BindUnsignedInt(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

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

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

Definition at line 501 of file queue.c.

References OCI_BindString(), OCI_BindUnsignedInt(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

OCI_EXPORT boolean OCI_API OCI_QueueTableDrop ( OCI_Connection con,
const mtext *  queue_table,
boolean  force 
)

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

Definition at line 567 of file queue.c.

References OCI_BindInt(), OCI_BindString(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

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

Purge messages from the given queue table.

Parameters:
con - Connection handle
queue_table - Queue table name
purge_condition - Optionnal 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 onyl 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

Definition at line 625 of file queue.c.

References OCI_BindInt(), OCI_BindString(), OCI_BindUnsignedInt(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().

OCI_EXPORT boolean OCI_API OCI_QueueTableMigrate ( OCI_Connection con,
const mtext *  queue_table,
const mtext *  compatible 
)

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

Definition at line 705 of file queue.c.

References OCI_BindString(), OCI_Execute(), OCI_Prepare(), OCI_StatementCreate(), and OCI_StatementFree().