OCILIB (C and C++ Driver for Oracle)  4.7.5
Open source and cross platform Oracle Driver delivering efficient access to Oracle databases.
Loading...
Searching...
No Matches
Oracle Advanced Queuing (A/Q)

Detailed Description

OcilibCApiDirectPath

OCILIB supports Oracle Advanced Queues features

Let's Oracle talk about this features !

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

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

OCILIB implementation

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

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

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

Example
#include "ocilib.h"
/* requires script demo/queue.sql */
void err_handler(OCI_Error *err)
{
printf("%s\n", OCI_ErrorGetString(err));
}
int main(int argc, char *argv[])
{
OCI_Msg *msg;
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_Commit(con);
msg = OCI_DequeueGet(deq);
obj = OCI_MsgGetObject(msg);
printf("MSG '%s' => %s\n", OCI_ObjectGetString(obj, "title"), OCI_ObjectGetString(obj, "content"));
OCI_QueueStop(con, "message_queue", TRUE, TRUE, FALSE);
OCI_QueueDrop(con, "message_queue");
OCI_QueueTableDrop(con, "message_queue_table", TRUE);
return EXIT_SUCCESS;
}
OCI_SYM_PUBLIC OCI_Object *OCI_API OCI_MsgGetObject(OCI_Msg *msg)
Get the object payload of the given message.
OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTableDrop(OCI_Connection *con, const otext *queue_table, boolean force)
Drop the given queue table.
OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueuePut(OCI_Enqueue *enqueue, OCI_Msg *msg)
Enqueue a message on the queue associated to the Enqueue object.
OCI_SYM_PUBLIC boolean OCI_API OCI_QueueStop(OCI_Connection *con, const otext *queue_name, boolean enqueue, boolean dequeue, boolean wait)
Stop enqueuing or dequeuing or both on the given queue.
OCI_SYM_PUBLIC OCI_Msg *OCI_API OCI_MsgCreate(OCI_TypeInfo *typinf)
Create a message object based on the given payload type.
OCI_SYM_PUBLIC boolean OCI_API OCI_QueueStart(OCI_Connection *con, const otext *queue_name, boolean enqueue, boolean dequeue)
Start the given queue.
OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueFree(OCI_Dequeue *dequeue)
Free a Dequeue object.
OCI_SYM_PUBLIC OCI_Msg *OCI_API OCI_DequeueGet(OCI_Dequeue *dequeue)
Dequeue messages from the given queue.
OCI_SYM_PUBLIC boolean OCI_API OCI_MsgFree(OCI_Msg *msg)
Free a message object.
OCI_SYM_PUBLIC boolean OCI_API OCI_QueueDrop(OCI_Connection *con, const otext *queue_name)
Drop the given queue.
OCI_SYM_PUBLIC boolean OCI_API OCI_QueueCreate(OCI_Connection *con, const otext *queue_name, const otext *queue_table, unsigned int queue_type, unsigned int max_retries, unsigned int retry_delay, unsigned int retention_time, boolean dependency_tracking, const otext *comment)
Create a queue.
OCI_SYM_PUBLIC OCI_Enqueue *OCI_API OCI_EnqueueCreate(OCI_TypeInfo *typinf, const otext *name)
Create a Enqueue object for the given queue.
OCI_SYM_PUBLIC boolean OCI_API OCI_QueueTableCreate(OCI_Connection *con, const otext *queue_table, const otext *queue_payload_type, const otext *storage_clause, const otext *sort_list, boolean multiple_consumers, unsigned int message_grouping, const otext *comment, unsigned int primary_instance, unsigned int secondary_instance, const otext *compatible)
Create a queue table for messages of the given type.
OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetObject(OCI_Msg *msg, OCI_Object *obj)
Set the object payload of the given message.
OCI_SYM_PUBLIC OCI_Dequeue *OCI_API OCI_DequeueCreate(OCI_TypeInfo *typinf, const otext *name)
Create a Dequeue object for the given queue.
OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueFree(OCI_Enqueue *enqueue)
Free a Enqueue object.
OCI_SYM_PUBLIC boolean OCI_API OCI_ConnectionFree(OCI_Connection *con)
Close a physical connection to an Oracle database server.
OCI_SYM_PUBLIC OCI_Connection *OCI_API OCI_ConnectionCreate(const otext *db, const otext *user, const otext *pwd, unsigned int mode)
Create a physical connection to an Oracle database server.
struct OCI_Enqueue OCI_Enqueue
OCILIB encapsulation of A/Q enqueuing operations.
Definition: types.h:480
struct OCI_Dequeue OCI_Dequeue
OCILIB encapsulation of A/Q dequeuing operations.
Definition: types.h:470
struct OCI_Connection OCI_Connection
Oracle physical connection.
Definition: types.h:124
struct OCI_Object OCI_Object
Oracle Named types representation.
Definition: types.h:309
struct OCI_Error OCI_Error
Encapsulates an Oracle or OCILIB exception.
Definition: types.h:390
struct OCI_Msg OCI_Msg
OCILIB encapsulation of A/Q message.
Definition: types.h:450
struct OCI_TypeInfo OCI_TypeInfo
Type info metadata handle.
Definition: types.h:366
OCI_SYM_PUBLIC const otext *OCI_API OCI_ErrorGetString(OCI_Error *err)
Retrieve error message from error handle.
OCI_SYM_PUBLIC boolean OCI_API OCI_Cleanup(void)
Clean up all resources allocated by the library.
OCI_SYM_PUBLIC boolean OCI_API OCI_Initialize(POCI_ERROR err_handler, const otext *lib_path, unsigned int mode)
Initialize the library.
OCI_SYM_PUBLIC OCI_TypeInfo *OCI_API OCI_TypeInfoGet(OCI_Connection *con, const otext *name, unsigned int type)
Retrieve the available type info information.
OCI_SYM_PUBLIC boolean OCI_API OCI_Commit(OCI_Connection *con)
Commit current pending changes.
OCI_SYM_PUBLIC boolean OCI_API OCI_ObjectSetString(OCI_Object *obj, const otext *attr, const otext *value)
Set an object attribute of type string.
OCI_SYM_PUBLIC boolean OCI_API OCI_ObjectFree(OCI_Object *obj)
Free a local object.
OCI_SYM_PUBLIC const otext *OCI_API OCI_ObjectGetString(OCI_Object *obj, const otext *attr)
Return the string value of the given object attribute.
OCI_SYM_PUBLIC OCI_Object *OCI_API OCI_ObjectCreate(OCI_Connection *con, OCI_TypeInfo *typinf)
Create a local object instance.

Functions

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

Function Documentation

◆ OCI_MsgCreate()

OCI_SYM_PUBLIC OCI_Msg *OCI_API OCI_MsgCreate ( OCI_TypeInfo typinf)

#include <api.h>

Create a message object based on the given payload type.

Parameters
typinf- Type info handle
Note
OCILIB supports 2 type of message payload :
  • Oracle types (UDT)
  • RAW data
Oracle Type AnyData is not supported in the current version of OCILIB
the parameter 'typinf' indicates the type of payload :
  • For object payload, retrieve the object type information handle with OCI_TypeInfoGet() using the object type name
  • For RAW payload, you MUST pass the object type information retrieved with OCI_TypeInfoGet() using "SYS.RAW" as object type name
Warning
Newly created Message handles have NULL payloads. For Message handling Objects payloads, OCI_MsgGetObject() returns NULL until an object handle is assigned to the message.
Note
When a local OCI_Msg handle is enqueued, it keeps its attributes. If it's enqueued again, another identical message is posted into the queue. To reset a message and empty all its properties, call OCI_MsgReset() Note that OCI_MsgReset() clears the message payload.
Returns
Return the message handle on success otherwise NULL on failure

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

◆ OCI_MsgFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgFree ( OCI_Msg msg)

#include <api.h>

Free a message object.

Parameters
msg- Message handle
Warning
Only message handles created with OCI_MsgCreate() should be freed by OCI_MsgFree()
Returns
TRUE on success otherwise FALSE

◆ OCI_MsgReset()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgReset ( OCI_Msg msg)

#include <api.h>

Reset all attributes of a message object.

Parameters
msg- Message handle
Note
This function calls OCI_MsgSetxxx() with default or NULL attributes
Warning
OCI_MsgReset() clears the message payload and set it to NULL For messages handling objects payloads, OCI_MsgSetObject() must be called again to assign a payload.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetObject()

OCI_SYM_PUBLIC OCI_Object *OCI_API OCI_MsgGetObject ( OCI_Msg msg)

#include <api.h>

Get the object payload of the given message.

Parameters
msg- Message handle
Returns
Return the object handle on success otherwise NULL on failure or if payload is NULL

◆ OCI_MsgSetObject()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetObject ( OCI_Msg msg,
OCI_Object obj 
)

#include <api.h>

Set the object payload of the given message.

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

◆ OCI_MsgGetRaw()

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

#include <api.h>

Get the RAW payload of the given message.

Parameters
msg- Message handle
raw- Input buffer
size- Input buffer maximum size
Note
On output, parameter 'size' holds the number of bytes copied into the given buffer
Returns
TRUE on success otherwise FALSE on failure or if payload is object based.

◆ OCI_MsgSetRaw()

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

#include <api.h>

Set the RAW payload of the given message.

Parameters
msg- Message handle
raw- Raw data
size- Raw data size
Returns
TRUE on success otherwise FALSE on failure or if payload is object based.

◆ OCI_MsgGetAttemptCount()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetAttemptCount ( OCI_Msg msg)

#include <api.h>

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

Parameters
msg- Message handle

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

◆ OCI_MsgGetEnqueueDelay()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetEnqueueDelay ( OCI_Msg msg)

#include <api.h>

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

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

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

◆ OCI_MsgSetEnqueueDelay()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetEnqueueDelay ( OCI_Msg msg,
int  value 
)

#include <api.h>

set the number of seconds to delay the enqueued message

Parameters
msg- Message handle
value- Delay in seconds
Note
The delay represents the number of seconds after which a message is available for dequeuing. When the message is enqueued, its state is set to OCI_AMS_WAITING. When the delay expires, its state is set to OCI_AMS_READY.
If parameter 'value' is set to zero (default value), the message will be immediately available for dequeuing
Warning
Dequeuing by Message ID overrides the delay specification.
Delaying processing requires the queue monitor to be started.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetEnqueueTime()

OCI_SYM_PUBLIC OCI_Date *OCI_API OCI_MsgGetEnqueueTime ( OCI_Msg msg)

#include <api.h>

return the time the message was enqueued

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

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

◆ OCI_MsgGetExpiration()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetExpiration ( OCI_Msg msg)

#include <api.h>

Return the duration that the message is available for dequeuing.

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

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

◆ OCI_MsgSetExpiration()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetExpiration ( OCI_Msg msg,
int  value 
)

#include <api.h>

set the duration that the message is available for dequeuing

Parameters
msg- Message handle
value- duration in seconds
Note
This parameter is an offset from the delay (see OCI_MsgSetEnqueueDelay()) While waiting for expiration, the message state is set to OCI_AMS_READY. If the message is not dequeued before it expires, it will be moved to the exception queue with the state OCI_AMS_EXPIRED.
If parameter 'value' is set to -1 (default value), the message will not expire
Warning
Expiration processing requires the queue monitor to be started.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetState()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_MsgGetState ( OCI_Msg msg)

#include <api.h>

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

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

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

◆ OCI_MsgGetPriority()

OCI_SYM_PUBLIC int OCI_API OCI_MsgGetPriority ( OCI_Msg msg)

#include <api.h>

Return the priority of the message.

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

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

◆ OCI_MsgSetPriority()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetPriority ( OCI_Msg msg,
int  value 
)

#include <api.h>

Set the priority of the message.

Parameters
msg- Message handle
value- Message priority
Note
  • The priority can be any number, including negative numbers.
  • A smaller number indicates higher priority.
  • Default value is zero.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetID()

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

#include <api.h>

Return the ID of the message.

Parameters
msg- Message handle
id- Input buffer
len- Input buffer maximum size
Note
The message ID is :
  • generated when the message is enqueued in the queue
  • retrieved when the message is dequeued from the queue
On output, parameter 'len' holds the number of bytes copied into the given buffer
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetOriginalID()

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

#include <api.h>

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

Parameters
msg- Message handle
id- Input buffer
len- Input buffer maximum size
Warning
When a message is propagated from/to different queues, this ID is the one generated for the message in the previous queue.
Note
On output, parameter 'len' holds the number of bytes copied into the given buffer
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgSetOriginalID()

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

#include <api.h>

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

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

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

◆ OCI_MsgGetSender()

OCI_SYM_PUBLIC OCI_Agent *OCI_API OCI_MsgGetSender ( OCI_Msg msg)

#include <api.h>

Return the original sender of a message.

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

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

◆ OCI_MsgSetSender()

OCI_SYM_PUBLIC boolean OCI_API OCI_MsgSetSender ( OCI_Msg msg,
OCI_Agent sender 
)

#include <api.h>

Set the original sender of a message.

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

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

◆ OCI_MsgSetConsumers()

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

#include <api.h>

Set the recipient list of a message to enqueue.

Parameters
msg- Message handle
consumers- Recipients list (array of agent handles)
count- Number of recipients
Warning
This function should only be used for queues which allow multiple consumers. The default recipients are the queue subscribers.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetCorrelation()

OCI_SYM_PUBLIC const otext *OCI_API OCI_MsgGetCorrelation ( OCI_Msg msg)

#include <api.h>

Get the correlation identifier of the message.

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

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

◆ OCI_MsgSetCorrelation()

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

#include <api.h>

set the correlation identifier of the message

Parameters
msg- Message handle
correlation- Message correlation text
Note
see OCI_DequeueSetCorrelation() for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_MsgGetExceptionQueue()

OCI_SYM_PUBLIC const otext *OCI_API OCI_MsgGetExceptionQueue ( OCI_Msg msg)

#include <api.h>

Get the Exception queue name of the message.

Parameters
msg- Message handle
Warning
When calling this function on a message retrieved with OCI_DequeueGet(), the returned value is NULL if the default exception queue associated with the current queue is used (e.g. no user defined specified at enqueue time for the message)
Note
see OCI_MsgSetExceptionQueue() for more details

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

◆ OCI_MsgSetExceptionQueue()

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

#include <api.h>

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

Parameters
msg- Message handle
queue- Exception queue name
Warning
From Oracle Documentation :

"Messages are moved into exception queues in two cases : - If the number of unsuccessful dequeue attempts has exceeded the attribute 'max_retries' of given queue - if the message has expired. All messages in the exception queue are in the EXPIRED state. The default is the exception queue associated with the queue table. If the exception queue specified does not exist at the time of the move the message will be moved to the default exception queue associated with the queue table and a warning will be logged in the alert file. This attribute must refer to a valid queue name."

Returns
TRUE on success otherwise FALSE

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

◆ OCI_EnqueueCreate()

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

#include <api.h>

Create a Enqueue object for the given queue.

Parameters
typinf- Type info handle
name- Queue name
Note
OCILIB supports 2 type of message payload :
  • Oracle types (UDT)
  • RAW data
Oracle Type AnyData is not supported in the current version of OCILIB
the parameter 'typinf' indicates the type of payload to enqueue to the given queue :
  • For object payload, retrieve the object type information handle with OCI_TypeInfoGet() using the object type name
  • For RAW payload, you MUST pass the object type information retrieved with OCI_TypeInfoGet() using "SYS.RAW" as object type name
Returns
Return the Enqueue handle on success otherwise NULL on failure

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

◆ OCI_EnqueueFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueueFree ( OCI_Enqueue enqueue)

#include <api.h>

Free a Enqueue object.

Parameters
enqueue- Enqueue handle
Returns
TRUE on success otherwise FALSE

◆ OCI_EnqueuePut()

OCI_SYM_PUBLIC boolean OCI_API OCI_EnqueuePut ( OCI_Enqueue enqueue,
OCI_Msg msg 
)

#include <api.h>

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

Parameters
enqueue- Enqueue handle
msg- Message handle to enqueue
Returns
TRUE on success otherwise FALSE

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

◆ OCI_EnqueueSetSequenceDeviation()

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

#include <api.h>

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

Parameters
enqueue- Enqueue handle
sequence- enqueuing sequence
Note
Possible values for parameter 'sequence' :
  • OCI_ASD_BEFORE : enqueue message before another message
  • OCI_ASD_TOP : enqueue message before all messages
Default value is OCI_ASD_TOP
if the parameter 'sequence' is set to OCI_ASD_BEFORE, the application must call OCI_EnqueueSetRelativeMsgID() before enqueuing the next message in the queue.
In order to stop enqueuing message using a sequence deviation, call OCI_EnqueueSetSequenceDeviation() with the value OCI_ASD_TOP
Returns
TRUE on success otherwise FALSE

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

◆ OCI_EnqueueGetSequenceDeviation()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_EnqueueGetSequenceDeviation ( OCI_Enqueue enqueue)

#include <api.h>

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

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

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

◆ OCI_EnqueueSetVisibility()

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

#include <api.h>

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

Parameters
enqueue- Enqueue handle
visibility- Enqueuing visibility
Note
Possible values for parameter 'visibility' :
  • OCI_AMV_IMMEDIATE : enqueue is an independent transaction
  • OCI_AMV_ON_COMMIT : enqueue is part of current transaction
Default value is OCI_AMV_ON_COMMIT
Returns
TRUE on success otherwise FALSE

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

◆ OCI_EnqueueGetVisibility()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_EnqueueGetVisibility ( OCI_Enqueue enqueue)

#include <api.h>

Get the enqueuing/locking behavior.

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

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

◆ OCI_EnqueueSetRelativeMsgID()

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

#include <api.h>

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

Parameters
enqueue- Enqueue handle
id- message identifier
len- pointer to message identifier length
Note
This call is only valid if OCI_EnqueueSetSequenceDeviation() has been called with the value OCI_ASD_BEFORE
Warning
if the function cannot assign the message id, the content of the parameter 'len' is set to zero.
Note
see OCI_EnqueueSetSequenceDeviation() for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_EnqueueGetRelativeMsgID()

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

#include <api.h>

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

Parameters
enqueue- Enqueue handle
id- buffer to receive the message identifier
len- pointer to buffer max length
Warning
When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id'
Note
see OCI_EnqueueGetRelativeMsgID() for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueCreate()

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

#include <api.h>

Create a Dequeue object for the given queue.

Parameters
typinf- Type info handle
name- Queue name
Note
OCILIB supports 2 type of message payload :
  • Oracle types (UDT)
  • RAW data
Oracle Type AnyData is not supported in the current version of OCILIB
the parameter 'typinf' indicates the type of payload to dequeue from the given queue :
  • For object payload, retrieve the object type information handle with OCI_TypeInfoGet() using the object type name
  • For RAW payload, you MUST pass the object type information retrieved with OCI_TypeInfoGet() using "SYS.RAW" as object type name
Returns
Return the Dequeue handle on success otherwise NULL on failure

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

◆ OCI_DequeueFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueFree ( OCI_Dequeue dequeue)

#include <api.h>

Free a Dequeue object.

Parameters
dequeue- Dequeue handle
Returns
TRUE on success otherwise FALSE

◆ OCI_DequeueGet()

OCI_SYM_PUBLIC OCI_Msg *OCI_API OCI_DequeueGet ( OCI_Dequeue dequeue)

#include <api.h>

Dequeue messages from the given queue.

Parameters
dequeue- Dequeue handle
Warning
The returned message is handled by the dequeue object. Do not release it with OCI_MsgFree()
When dequeuing from a multiple consumer queue, you need to set the navigation mode to OCI_ADN_FIRST_MSG using OCI_DequeueSetNavigation()
Returns
Message handle on success otherwise NULL on failure or on timeout

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

◆ OCI_DequeueSubscribe()

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

#include <api.h>

Subscribe for asynchronous messages notifications.

Parameters
dequeue- Dequeue handle
port- Port to use for notifications
timeout- notification timeout
callback- User handler callback fired when messages are ready to be dequeued
Note
OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use asynchronous messages notifications
Requires Oracle Client 10gR2 or above
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueUnsubscribe()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueUnsubscribe ( OCI_Dequeue dequeue)

#include <api.h>

Unsubscribe for asynchronous messages notifications.

Parameters
dequeue- Dequeue handle
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueSetConsumer()

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

#include <api.h>

Set the current consumer name to retrieve message for.

Parameters
dequeue- Dequeue handle
consumer- consumer name
Warning
If a queue is not set up for multiple consumers, OCI_DequeueSetConsumer() should not be called or called with parameter 'consumer' set to NULL
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetConsumer()

OCI_SYM_PUBLIC const otext *OCI_API OCI_DequeueGetConsumer ( OCI_Dequeue dequeue)

#include <api.h>

Get the current consumer name associated with the dequeuing process.

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

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

◆ OCI_DequeueSetCorrelation()

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

#include <api.h>

set the correlation identifier of the message to be dequeued

Parameters
dequeue- Dequeue handle
pattern- correlation identifier
Note
Special pattern matching characters, such as "%" or "_" can be used. If more than one message satisfies the pattern, the order of dequeuing is undetermined.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetCorrelation()

OCI_SYM_PUBLIC const otext *OCI_API OCI_DequeueGetCorrelation ( OCI_Dequeue dequeue)

#include <api.h>

Get the correlation identifier of the message to be dequeued.

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

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

◆ OCI_DequeueSetRelativeMsgID()

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

#include <api.h>

Set the message identifier of the message to be dequeued.

Parameters
dequeue- Dequeue handle
id- message identifier
len- size of the message identifier
Warning
if the function cannot assign the message id, the content of the parameter 'len' is set to zero.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetRelativeMsgID()

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

#include <api.h>

Get the message identifier of the message to be dequeued.

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

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

◆ OCI_DequeueSetVisibility()

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

#include <api.h>

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

Parameters
dequeue- Dequeue handle
visibility- dequeuing mode
Warning
The visibility parameter is ignored when using the OCI_ADM_BROWSE dequeuing mode (see OCI_DequeueSetMode())
Note
Possible values for parameter 'mode' :
  • OCI_AMV_IMMEDIATE : dequeue is an independent transaction
  • OCI_AMV_ON_COMMIT : dequeue is part of current transaction
Default value is OCI_AMV_ON_COMMIT
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetVisibility()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_DequeueGetVisibility ( OCI_Dequeue dequeue)

#include <api.h>

Get the dequeuing/locking behavior.

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

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

◆ OCI_DequeueSetMode()

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

#include <api.h>

Set the dequeuing/locking behavior.

Parameters
dequeue- Dequeue handle
mode- dequeuing mode
Note
Possible values for parameter 'mode' :
  • OCI_ADM_BROWSE : read message without acquiring a lock
  • OCI_ADM_LOCKED : read and obtain write lock on message
  • OCI_ADM_REMOVE : read the message and delete it
  • OCI_ADM_REMOVE_NODATA : confirm receipt of the message, but do not deliver the actual message content
Default value is OCI_ADM_REMOVE
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetMode()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_DequeueGetMode ( OCI_Dequeue dequeue)

#include <api.h>

Get the dequeuing/locking behavior.

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

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

◆ OCI_DequeueSetNavigation()

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

#include <api.h>

Set the position of messages to be retrieved.

Parameters
dequeue- Dequeue handle
position- navigation position
Note
The dequeuing uses the following sequence :
  • find messages using the navigation position
  • apply search criteria (message correlation)
  • get message
Possible values for parameter 'position' :
  • OCI_ADN_FIRST_MSG : retrieves the first message which is available
  • OCI_ADN_NEXT_MSG : retrieves the next message which is available
  • OCI_ADN_NEXT_TRANSACTION : skips the remainder of the current transaction group (if any) and retrieves the first message of the next transaction group.
Default value is OCI_ADN_NEXT_MSG
Warning
OCI_ADN_NEXT_TRANSACTION can only be used if message grouping is enabled for the given queue.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetNavigation()

OCI_SYM_PUBLIC unsigned int OCI_API OCI_DequeueGetNavigation ( OCI_Dequeue dequeue)

#include <api.h>

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

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

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

◆ OCI_DequeueSetWaitTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DequeueSetWaitTime ( OCI_Dequeue dequeue,
int  timeout 
)

#include <api.h>

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

Parameters
dequeue- Dequeue handle
timeout- timeout in seconds
Note
  • Any positive values in seconds are valid.
  • The value 0 is accepted and means OCIDequeueGet() does not wait for messages and returns immediately if no messages are available
  • The value -1 is accepted and means OCIDequeueGet() waits for ever (until a message is available in the queue)
Default value is -1 (wait for ever)
Returns
TRUE on success otherwise FALSE

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

◆ OCI_DequeueGetWaitTime()

OCI_SYM_PUBLIC int OCI_API OCI_DequeueGetWaitTime ( OCI_Dequeue dequeue)

#include <api.h>

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

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

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

◆ OCI_DequeueSetAgentList()

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

#include <api.h>

Set the Agent list to listen to message for.

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

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

◆ OCI_DequeueListen()

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

#include <api.h>

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

Parameters
dequeue- Dequeue handle
timeout- Timeout in second
Note
If an Agent handle is returned, messages are available for this agent. In order to retrieve its messages :
Warning
The return value is valid only until:
  • OCIDequeueListen() is called again
  • OCI_DequeueFree(à is called to free the Dequeue object So Do not store the handle value across calls to OCIDequeueListen()
Returns
An Agent handle for who messages are available on success otherwise NULL

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

◆ OCI_AgentCreate()

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

#include <api.h>

Create an AQ agent object.

Parameters
con- Connection handle
name- Agent name
address- Agent address
Note
An AQ agent object is :
  • used as recipient information when enqueuing a message
  • used as sender information when dequeuing a message
  • used for listening message only from identified senders
the AQ agent address can be any Oracle identifier, up to 128 bytes. the AQ agent name can be any Oracle identifier, up to 30 bytes.
Returns
AQ agent handle on success otherwise NULL

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

◆ OCI_AgentFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_AgentFree ( OCI_Agent agent)

#include <api.h>

Free an AQ agent object.

Parameters
agent- AQ agent handle
Warning
Only AQ agent handle created with OCI_AgentCreate() should be freed by OCI_AgentFree()
Returns
TRUE on success otherwise FALSE

◆ OCI_AgentSetName()

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

#include <api.h>

Set the given AQ agent name.

Parameters
agent- AQ agent handle
name- AQ agent name
Note
the AQ agent name is used to identified an message send or recipient when enqueuing/dequeuing a message
the AQ agent name can be any Oracle identifier, up to 30 bytes.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_AgentGetName()

OCI_SYM_PUBLIC const otext *OCI_API OCI_AgentGetName ( OCI_Agent agent)

#include <api.h>

Get the given AQ agent name.

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

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

◆ OCI_AgentSetAddress()

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

#include <api.h>

Set the given AQ agent address.

Parameters
agent- AQ agent handle
address- AQ agent address
Note
the parameter 'address' must be of the form : [schema.]queue_name[@dblink]
the AQ agent address can be any Oracle identifier, up to 128 bytes.
Returns
TRUE on success otherwise FALSE

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

◆ OCI_AgentGetAddress()

OCI_SYM_PUBLIC const otext *OCI_API OCI_AgentGetAddress ( OCI_Agent agent)

#include <api.h>

Get the given AQ agent address.

Parameters
agent- AQ agent handle
Note
See OCI_AgentSetAddress()
Returns
AQ agent address on success otherwise NULL on failure

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

◆ OCI_QueueCreate()

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

#include <api.h>

Create a queue.

Parameters
con- Connection handle
queue_name- Queue name
queue_table- Queue table name
queue_type- Queue type
max_retries- Maximum number of attempts to dequeue a message
retry_delay- Number of seconds between attempts to dequeue a message
retention_time- number of seconds a message is retained in the queue table after being dequeued from the queue
dependency_tracking- Parameter reserved for future use by Oracle (MUST be set to FALSE)
comment- Description of the queue
Note
Parameter 'queue_name' can specify the schema where to create to queue ([schema.]queue_name) Queue names cannot be longer than 24 characters (Oracle limit for user queues)
Possible values for parameter 'queue_type' :
  • OCI_AQT_NORMAL : Normal queue
  • OCI_AQT_EXCEPTION : Exception queue
  • OCI_AQT_NON_PERSISTENT : Non persistent queue

To set default values, pass :

  • queue_type : OCI_AQT_NORMAL
  • max_retries : 0
  • retry_delay : 0
  • retention_time : 0
  • comment : NULL
Note
this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueAlter()

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

#include <api.h>

Alter the given queue.

Parameters
con- Connection handle
queue_name- Queue name
max_retries- Maximum number of attempts to dequeue a message
retry_delay- Number of seconds between attempts to dequeue a message
retention_time- number of seconds a message is retained in the queue table after being dequeued from the queue
comment- Description of the queue
Note
See OCI_QueueCreate() for more details
Warning
This function updates all attributes handled in the parameter list !
Note
this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueDrop()

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

#include <api.h>

Drop the given queue.

Parameters
con- Connection handle
queue_name- Queue name
Warning
A queue can be dropped only if it has been stopped before.
Note
this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueStart()

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

#include <api.h>

Start the given queue.

Parameters
con- Connection handle
queue_name- Queue name
enqueue- Enable enqueue
dequeue- Enable dequeue
Warning
For exception queues, only enqueuing is allowed
Note
this call wraps the PL/SQL procedure DBMS_AQADM.START_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueStop()

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

#include <api.h>

Stop enqueuing or dequeuing or both on the given queue.

Parameters
con- Connection handle
queue_name- Queue name
enqueue- Disable enqueue
dequeue- Disable dequeue
wait- Wait for current pending enqueues/dequeues
Warning
A queue cannot be stopped if there are pending transactions against the queue.
Note
this call wraps the PL/SQL procedure DBMS_AQADM.STOP_QUEUE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueTableCreate()

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

#include <api.h>

Create a queue table for messages of the given type.

Parameters
con- Connection handle
queue_table- Queue table name
queue_payload_type- Message type name
storage_clause- Additional clauses for the table storage
sort_list- Additional columns name to use for sorting
multiple_consumers- Enable multiple consumers for each messages
message_grouping- Specifies if messages are grouped within a transaction
comment- Description of the queue table
primary_instance- primary owner (instance) of the queue table
secondary_instance- Owner of the queue table if the primary instance is not available
compatible- lowest database version with which the queue table is compatible
Note
Parameter 'queue_table' can specify the schema where to create to queue table ([schema.]queue_table) Queue table names cannot be longer than 24 characters (Oracle limit for user queue tables)
Possible values for parameter 'queue_payload_type' :
  • For Oracle types (UDT) : use the type name ([schema.].type_name)
  • For RAW data : use "SYS.RAW" or "RAW" (depending on Oracle versions - For latest ones, use "RAW")
Possible values for parameter 'message_grouping' :
  • OCI_AGM_NONE : each message is treated individually
  • OCI_AGM_TRANSACTIONNAL : all messages enqueued in one transaction are considered part of the same group and can be dequeued as a group of related messages.
Possible values for parameter 'compatible' :
  • "8.0", "8.1", "10.0"

To set default values, pass :

  • storage_clause : NULL
  • sort_list : NULL
  • message_grouping : OCI_AGM_NONE
  • comment : NULL
  • primary_instance : 0
  • primary_instance : 0
  • compatible : NULL
Note
this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueTableAlter()

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

#include <api.h>

Alter the given queue table.

Parameters
con- Connection handle
queue_table- Queue table name
comment- Description of the queue table
primary_instance- primary owner (instance) of the queue table
secondary_instance- Owner of the queue table if the primary instance is not available
Note
See OCI_QueueTableCreate() from more details
this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueTableDrop()

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

#include <api.h>

Drop the given queue table.

Parameters
con- Connection handle
queue_table- Queue table name
force- Force the deletion of objects related to the queue table
Note
Possible values for 'force' :
  • TRUE : all queues using the queue table and their associated propagation schedules are dropped automatically
  • FALSE : All the queues using the given queue table must be stopped and dropped before the queue table can be dropped.
this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueTablePurge()

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

#include <api.h>

Purge messages from the given queue table.

Parameters
con- Connection handle
queue_table- Queue table name
purge_condition- Optional SQL based conditions (see notes)
block- Lock all queues using the queue table while doing the purge
delivery_mode- Type of message to purge
Note
Possible values for parameter 'delivery_mode' :
  • OCI_APM_BUFFERED : purge only buffered messages
  • OCI_APM_PERSISTENT : purge only persistent messages
  • OCI_APM_ALL : purge all messages
For more information about the SQL purge conditions, refer to Oracle Streams - Advanced Queuing User's Guide for more details
Warning
This feature is only available from Oracle 10gR2. This function does nothing and returns TRUE is the server version is < Oracle 10gR2
Note
this call wraps the PL/SQL procedure DBMS_AQADM.PURGE_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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

◆ OCI_QueueTableMigrate()

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

#include <api.h>

Migrate a queue table from one version to another.

Parameters
con- Connection handle
queue_table- Queue table name
compatible- Database version with witch the queue table has to migrate
Note
Possible values for parameter 'compatible' :
  • "8.0", "8.1", "10.0"
this call wraps the PL/SQL procedure DBMS_AQADM.MIGRATE_QUEUE_TABLE(). Refer to Oracle Streams - Advanced Queuing User's Guide for more details
Returns
TRUE on success otherwise FALSE

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