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 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 informations 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_EXPORT OCI_Msg *OCI_API | OCI_MsgCreate (OCI_TypeInfo *typinf)
| Create a message object based on the given payload type. More...
OCI_EXPORT boolean OCI_API | OCI_MsgFree (OCI_Msg *msg)
| Free a message object. More...
OCI_EXPORT boolean OCI_API | OCI_MsgReset (OCI_Msg *msg)
| Reset all attributes of a message object. More...
OCI_EXPORT OCI_Object *OCI_API | OCI_MsgGetObject (OCI_Msg *msg)
| Get the object payload of the given message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetObject (OCI_Msg *msg, OCI_Object *obj)
| Set the object payload of the given message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgGetRaw (OCI_Msg *msg, void *raw, unsigned int *size)
| Get the RAW payload of the given message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetRaw (OCI_Msg *msg, const void *raw, unsigned int size)
| Set the RAW payload of the given message. More...
OCI_EXPORT int OCI_API | OCI_MsgGetAttemptCount (OCI_Msg *msg)
| Return the number of attempts that have been made to dequeue the message. More...
OCI_EXPORT int OCI_API | OCI_MsgGetEnqueueDelay (OCI_Msg *msg)
| Return the number of seconds that a message is delayed for dequeuing. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetEnqueueDelay (OCI_Msg *msg, int value)
| set the number of seconds to delay the enqueued message More...
OCI_EXPORT OCI_Date *OCI_API | OCI_MsgGetEnqueueTime (OCI_Msg *msg)
| return the time the message was enqueued More...
OCI_EXPORT int OCI_API | OCI_MsgGetExpiration (OCI_Msg *msg)
| Return the duration that the message is available for dequeuing. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetExpiration (OCI_Msg *msg, int value)
| set the duration that the message is available for dequeuing More...
OCI_EXPORT unsigned int OCI_API | OCI_MsgGetState (OCI_Msg *msg)
| Return the state of the message at the time of the dequeue. More...
OCI_EXPORT int OCI_API | OCI_MsgGetPriority (OCI_Msg *msg)
| Return the priority of the message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetPriority (OCI_Msg *msg, int value)
| Set the priority of the message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgGetID (OCI_Msg *msg, void *id, unsigned int *len)
| Return the ID of the message. More...
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. More...
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. More...
OCI_EXPORT OCI_Agent *OCI_API | OCI_MsgGetSender (OCI_Msg *msg)
| Return the original sender of a message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetSender (OCI_Msg *msg, OCI_Agent *sender)
| Set the original sender of a message. More...
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. More...
OCI_EXPORT const otext *OCI_API | OCI_MsgGetCorrelation (OCI_Msg *msg)
| Get the correlation identifier of the message. More...
OCI_EXPORT boolean OCI_API | OCI_MsgSetCorrelation (OCI_Msg *msg, const otext *correlation)
| set the correlation identifier of the message More...
OCI_EXPORT const otext *OCI_API | OCI_MsgGetExceptionQueue (OCI_Msg *msg)
| Get the Exception queue name of the message. More...
OCI_EXPORT 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. More...
OCI_EXPORT OCI_Enqueue *OCI_API | OCI_EnqueueCreate (OCI_TypeInfo *typinf, const otext *name)
| Create a Enqueue object for the given queue. More...
OCI_EXPORT boolean OCI_API | OCI_EnqueueFree (OCI_Enqueue *enqueue)
| Free a Enqueue object. More...
OCI_EXPORT boolean OCI_API | OCI_EnqueuePut (OCI_Enqueue *enqueue, OCI_Msg *msg)
| Enqueue a message on the queue associated to the Enqueue object. More...
OCI_EXPORT boolean OCI_API | OCI_EnqueueSetSequenceDeviation (OCI_Enqueue *enqueue, unsigned int sequence)
| Set the enqueuing sequence of messages to put in the queue. More...
OCI_EXPORT unsigned int OCI_API | OCI_EnqueueGetSequenceDeviation (OCI_Enqueue *enqueue)
| Return the sequence deviation of messages to enqueue to the queue. More...
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. More...
OCI_EXPORT unsigned int OCI_API | OCI_EnqueueGetVisibility (OCI_Enqueue *enqueue)
| Get the enqueuing/locking behavior. More...
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. More...
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. More...
OCI_EXPORT OCI_Dequeue *OCI_API | OCI_DequeueCreate (OCI_TypeInfo *typinf, const otext *name)
| Create a Dequeue object for the given queue. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueFree (OCI_Dequeue *dequeue)
| Free a Dequeue object. More...
OCI_EXPORT OCI_Msg *OCI_API | OCI_DequeueGet (OCI_Dequeue *dequeue)
| Dequeue messages from the given queue. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueSubscribe (OCI_Dequeue *dequeue, unsigned int port, unsigned int timeout, POCI_NOTIFY_AQ callback)
| Subscribe for asynchronous messages notifications. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueUnsubscribe (OCI_Dequeue *dequeue)
| Unsubscribe for asynchronous messages notifications. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueSetConsumer (OCI_Dequeue *dequeue, const otext *consumer)
| Set the current consumer name to retrieve message for. More...
OCI_EXPORT const otext *OCI_API | OCI_DequeueGetConsumer (OCI_Dequeue *dequeue)
| Get the current consumer name associated with the dequeuing process. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueSetCorrelation (OCI_Dequeue *dequeue, const otext *pattern)
| set the correlation identifier of the message to be dequeued More...
OCI_EXPORT const otext *OCI_API | OCI_DequeueGetCorrelation (OCI_Dequeue *dequeue)
| Get the correlation identifier of the message to be dequeued. More...
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. More...
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. More...
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. More...
OCI_EXPORT unsigned int OCI_API | OCI_DequeueGetVisibility (OCI_Dequeue *dequeue)
| Get the dequeuing/locking behavior. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueSetMode (OCI_Dequeue *dequeue, unsigned int mode)
| Set the dequeuing/locking behavior. More...
OCI_EXPORT unsigned int OCI_API | OCI_DequeueGetMode (OCI_Dequeue *dequeue)
| Get the dequeuing/locking behavior. More...
OCI_EXPORT boolean OCI_API | OCI_DequeueSetNavigation (OCI_Dequeue *dequeue, unsigned int position)
| Set the position of messages to be retrieved. More...
OCI_EXPORT unsigned int OCI_API | OCI_DequeueGetNavigation (OCI_Dequeue *dequeue)
| Return the navigation position of messages to retrieve from the queue. More...
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 More...
OCI_EXPORT int OCI_API | OCI_DequeueGetWaitTime (OCI_Dequeue *dequeue)
| Return the time that OCIDequeueGet() waits for messages if no messages are currently available. More...
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. More...
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. More...
OCI_EXPORT OCI_Agent *OCI_API | OCI_AgentCreate (OCI_Connection *con, const otext *name, const otext *address)
| Create an AQ agent object. More...
OCI_EXPORT boolean OCI_API | OCI_AgentFree (OCI_Agent *agent)
| Free an AQ agent object. More...
OCI_EXPORT boolean OCI_API | OCI_AgentSetName (OCI_Agent *agent, const otext *name)
| Set the given AQ agent name. More...
OCI_EXPORT const otext *OCI_API | OCI_AgentGetName (OCI_Agent *agent)
| Get the given AQ agent name. More...
OCI_EXPORT boolean OCI_API | OCI_AgentSetAddress (OCI_Agent *agent, const otext *address)
| Set the given AQ agent address. More...
OCI_EXPORT const otext *OCI_API | OCI_AgentGetAddress (OCI_Agent *agent)
| Get the given AQ agent address. More...
OCI_EXPORT 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. More...
OCI_EXPORT 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. More...
OCI_EXPORT boolean OCI_API | OCI_QueueDrop (OCI_Connection *con, const otext *queue_name)
| Drop the given queue. More...
OCI_EXPORT boolean OCI_API | OCI_QueueStart (OCI_Connection *con, const otext *queue_name, boolean enqueue, boolean dequeue)
| Start the given queue. More...
OCI_EXPORT 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. More...
OCI_EXPORT 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. More...
OCI_EXPORT 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. More...
OCI_EXPORT boolean OCI_API | OCI_QueueTableDrop (OCI_Connection *con, const otext *queue_table, boolean force)
| Drop the given queue table. More...
OCI_EXPORT 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. More...
OCI_EXPORT boolean OCI_API | OCI_QueueTableMigrate (OCI_Connection *con, const otext *queue_table, const otext *compatible)
| Migrate a queue table from one version to another. More...

## Function Documentation

## OCI_MsgCreate()

OCI_EXPORT OCI_Msg* OCI_API OCI_MsgCreate | ( | OCI_TypeInfo * | typinf | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgFree | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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

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

## OCI_MsgReset()

OCI_EXPORT boolean OCI_API OCI_MsgReset | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT OCI_Object* OCI_API OCI_MsgGetObject | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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

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

## OCI_MsgSetObject()

OCI_EXPORT boolean OCI_API OCI_MsgSetObject | ( | OCI_Msg * | msg,
|  | OCI_Object * | obj
| ) |  |

`#include <ocilib.h>`

Set the object payload of the given message.

Parameters

  msg | - Message handle
  obj | - Object handle

Returns
  TRUE on success otherwise FALSE

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

## OCI_MsgGetRaw()

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

`#include <ocilib.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.

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

## OCI_MsgSetRaw()

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

`#include <ocilib.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.

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

## OCI_MsgGetAttemptCount()

OCI_EXPORT int OCI_API OCI_MsgGetAttemptCount | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT int OCI_API OCI_MsgGetEnqueueDelay | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetEnqueueDelay | ( | OCI_Msg * | msg,
|  | int | value
| ) |  |

`#include <ocilib.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_EXPORT OCI_Date* OCI_API OCI_MsgGetEnqueueTime | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT int OCI_API OCI_MsgGetExpiration | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetExpiration | ( | OCI_Msg * | msg,
|  | int | value
| ) |  |

`#include <ocilib.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_EXPORT unsigned int OCI_API OCI_MsgGetState | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT int OCI_API OCI_MsgGetPriority | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetPriority | ( | OCI_Msg * | msg,
|  | int | value
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgGetID | ( | OCI_Msg * | msg,
|  | void * | id,
|  | unsigned int * | len
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgGetOriginalID | ( | OCI_Msg * | msg,
|  | void * | id,
|  | unsigned int * | len
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetOriginalID | ( | OCI_Msg * | msg,
|  | const void * | id,
|  | unsigned int | len
| ) |  |

`#include <ocilib.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_EXPORT OCI_Agent* OCI_API OCI_MsgGetSender | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetSender | ( | OCI_Msg * | msg,
|  | OCI_Agent * | sender
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetConsumers | ( | OCI_Msg * | msg,
|  | OCI_Agent ** | consumers,
|  | unsigned int | count
| ) |  |

`#include <ocilib.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_EXPORT const otext* OCI_API OCI_MsgGetCorrelation | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetCorrelation | ( | OCI_Msg * | msg,
|  | const otext * | correlation
| ) |  |

`#include <ocilib.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_EXPORT const otext* OCI_API OCI_MsgGetExceptionQueue | ( | OCI_Msg * | msg | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_MsgSetExceptionQueue | ( | OCI_Msg * | msg,
|  | const otext * | queue
| ) |  |

`#include <ocilib.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_EXPORT OCI_Enqueue* OCI_API OCI_EnqueueCreate | ( | OCI_TypeInfo * | typinf,
|  | const otext * | name
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_EnqueueFree | ( | OCI_Enqueue * | enqueue | ) |

`#include <ocilib.h>`

Free a Enqueue object.

Parameters

  enqueue | - Enqueue handle

Returns
  TRUE on success otherwise FALSE

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

## OCI_EnqueuePut()

OCI_EXPORT boolean OCI_API OCI_EnqueuePut | ( | OCI_Enqueue * | enqueue,
|  | OCI_Msg * | msg
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_EnqueueSetSequenceDeviation | ( | OCI_Enqueue * | enqueue,
|  | unsigned int | sequence
| ) |  |

`#include <ocilib.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_EXPORT unsigned int OCI_API OCI_EnqueueGetSequenceDeviation | ( | OCI_Enqueue * | enqueue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_EnqueueSetVisibility | ( | OCI_Enqueue * | enqueue,
|  | unsigned int | visibility
| ) |  |

`#include <ocilib.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_EXPORT unsigned int OCI_API OCI_EnqueueGetVisibility | ( | OCI_Enqueue * | enqueue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_EnqueueSetRelativeMsgID | ( | OCI_Enqueue * | enqueue,
|  | const void * | id,
|  | unsigned int | len
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_EnqueueGetRelativeMsgID | ( | OCI_Enqueue * | enqueue,
|  | void * | id,
|  | unsigned int * | len
| ) |  |

`#include <ocilib.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_EXPORT OCI_Dequeue* OCI_API OCI_DequeueCreate | ( | OCI_TypeInfo * | typinf,
|  | const otext * | name
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueFree | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.h>`

Free a Dequeue object.

Parameters

  dequeue | - Dequeue handle

Returns
  TRUE on success otherwise FALSE

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

## OCI_DequeueGet()

OCI_EXPORT OCI_Msg* OCI_API OCI_DequeueGet | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSubscribe | ( | OCI_Dequeue * | dequeue,
|  | unsigned int | port,
|  | unsigned int | timeout,
|  | POCI_NOTIFY_AQ | callback
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueUnsubscribe | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.h>`

Unsubscribe for asynchronous messages notifications.

Parameters

  dequeue | - Dequeue handle

Returns
  TRUE on success otherwise FALSE

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

## OCI_DequeueSetConsumer()

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

`#include <ocilib.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_EXPORT const otext* OCI_API OCI_DequeueGetConsumer | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetCorrelation | ( | OCI_Dequeue * | dequeue,
|  | const otext * | pattern
| ) |  |

`#include <ocilib.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_EXPORT const otext* OCI_API OCI_DequeueGetCorrelation | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetRelativeMsgID | ( | OCI_Dequeue * | dequeue,
|  | const void * | id,
|  | unsigned int | len
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueGetRelativeMsgID | ( | OCI_Dequeue * | dequeue,
|  | void * | id,
|  | unsigned int * | len
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetVisibility | ( | OCI_Dequeue * | dequeue,
|  | unsigned int | visibility
| ) |  |

`#include <ocilib.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_EXPORT unsigned int OCI_API OCI_DequeueGetVisibility | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetMode | ( | OCI_Dequeue * | dequeue,
|  | unsigned int | mode
| ) |  |

`#include <ocilib.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_EXPORT unsigned int OCI_API OCI_DequeueGetMode | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetNavigation | ( | OCI_Dequeue * | dequeue,
|  | unsigned int | position
| ) |  |

`#include <ocilib.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_EXPORT unsigned int OCI_API OCI_DequeueGetNavigation | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetWaitTime | ( | OCI_Dequeue * | dequeue,
|  | int | timeout
| ) |  |

`#include <ocilib.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_EXPORT int OCI_API OCI_DequeueGetWaitTime | ( | OCI_Dequeue * | dequeue | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_DequeueSetAgentList | ( | OCI_Dequeue * | dequeue,
|  | OCI_Agent ** | consumers,
|  | unsigned int | count
| ) |  |

`#include <ocilib.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_EXPORT OCI_Agent* OCI_API OCI_DequeueListen | ( | OCI_Dequeue * | dequeue,
|  | int | timeout
| ) |  |

`#include <ocilib.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_EXPORT OCI_Agent* OCI_API OCI_AgentCreate | ( | OCI_Connection * | con,
|  | const otext * | name,
|  | const otext * | address
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_AgentFree | ( | OCI_Agent * | agent | ) |

`#include <ocilib.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

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

## OCI_AgentSetName()

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

`#include <ocilib.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_EXPORT const otext* OCI_API OCI_AgentGetName | ( | OCI_Agent * | agent | ) |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_AgentSetAddress | ( | OCI_Agent * | agent,
|  | const otext * | address
| ) |  |

`#include <ocilib.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_EXPORT const otext* OCI_API OCI_AgentGetAddress | ( | OCI_Agent * | agent | ) |

`#include <ocilib.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_EXPORT 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 <ocilib.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_EXPORT 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 <ocilib.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_EXPORT boolean OCI_API OCI_QueueDrop | ( | OCI_Connection * | con,
|  | const otext * | queue_name
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_QueueStart | ( | OCI_Connection * | con,
|  | const otext * | queue_name,
|  | boolean | enqueue,
|  | boolean | dequeue
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_QueueStop | ( | OCI_Connection * | con,
|  | const otext * | queue_name,
|  | boolean | enqueue,
|  | boolean | dequeue,
|  | boolean | wait
| ) |  |

`#include <ocilib.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_EXPORT 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 <ocilib.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"
  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_EXPORT boolean OCI_API OCI_QueueTableAlter | ( | OCI_Connection * | con,
|  | const otext * | queue_table,
|  | const otext * | comment,
|  | unsigned int | primary_instance,
|  | unsigned int | secondary_instance
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_QueueTableDrop | ( | OCI_Connection * | con,
|  | const otext * | queue_table,
|  | boolean | force
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_QueueTablePurge | ( | OCI_Connection * | con,
|  | const otext * | queue_table,
|  | const otext * | purge_condition,
|  | boolean | block,
|  | unsigned int | delivery_mode
| ) |  |

`#include <ocilib.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_EXPORT boolean OCI_API OCI_QueueTableMigrate | ( | OCI_Connection * | con,
|  | const otext * | queue_table,
|  | const otext * | compatible
| ) |  |

`#include <ocilib.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().