Table 17-3 lists the Streams Advanced Queuing and publish-subscribe functions that are described in this section. Use functions that end in "2" for all new applications.
See Also:
"OCI Demonstration Programs" for Streams Advanced Queuing programsTable 17-3 Advanced Queuing and Publish-Subscribe Functions
| Function | Purpose |
|---|---|
|
Performs an Advanced Queuing dequeue operation |
|
|
Dequeue an array of messages |
|
|
Performs an Advanced Queuing enqueue operation |
|
|
Enqueue an array of messages |
|
|
Listen on one or more queues on behalf of a list of agents. Supports buffered messaging and persistent queues. |
|
|
Disable a subscription registration to turn off notifications |
|
|
Enable notifications on a subscription |
|
|
Post to a subscription to receive notifications |
|
|
Register a subscription |
|
|
Unregister a subscription |
sword OCIAQDeq ( OCISvcCtx *svch,
OCIError *errh,
OraText *queue_name,
OCIAQDeqOptions *dequeue_options,
OCIAQMsgProperties *message_properties,
OCIType *payload_tdo,
void **payload,
void **payload_ind,
OCIRaw **msgid,
ub4 flags );
OCI service context.
An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
The target queue for the dequeue operation.
The options for the dequeue operation; stored in an OCIAQDeqOptions descriptor, with OCI type constant OCI_DTYPE_AQDEQ_OPTIONS.
OCI_DTYPE_AQDEQ_OPTIONS has the additional attribute OCI_ATTR_MSG_DELIVERY_MODE (introduced in Oracle Database 10g Release 2) with the following values:
OCI_MSG_PERSISTENT (default)
OCI_MSG_BUFFERED
OCI_MSG_PERSISTENT_OR_BUFFERED
The message properties for the message; the properties are stored in an OCIAQMsgProperties descriptor, with OCI type constant OCI_DTYPE_AQMSG_PROPERTIES, which can have the following values:
OCI_AQ_PERSISTENT (default)
OCI_AQ_BUFFERED
The TDO (type descriptor object) of an object type. For a raw queue, this parameter should point to the TDO of SYS.RAW.
A pointer to a pointer to a program variable buffer that is an instance of an object type. For a raw queue, this parameter should point to an instance of OCIRaw.
Memory for the payload is dynamically allocated in the object cache. The application can optionally call OCIObjectFree() to deallocate the payload instance when it is no longer needed. If the pointer to the program variable buffer (*payload) is passed as NULL, the buffer is implicitly allocated in the cache.
The application may choose to pass NULL for payload the first time OCIAQDeq() is called, and let the OCI allocate the memory for the payload. It can then use a pointer to that previously allocated memory in subsequent calls to OCIAQDeq().
To obtain a TDO for the payload, use OCITypeByName(), or OCITypeByRef().
The OCI provides functions that allow the user to set attributes of the payload, such as its text. For information about setting these attributes, see "Manipulating Object Attributes".
A pointer to a pointer to the program variable buffer containing the parallel indicator structure for the object type.
The memory allocation rules for payload_ind are the same as those for payload.
The message ID.
Not currently used; pass as OCI_DEFAULT.
Users must have the AQ_USER_ROLE or privileges to execute the DBMS_AQ package to use this call. The OCI environment must be initialized in object mode (using OCIEnvCreate(), OCIEnvNlsCreate()), or OCIInitialize() (deprecated) to use this call.
OCIAQEnq(), OCIAQListen2(), OCIInitialize() (deprecated), OCIEnvCreate(), OCIEnvNlsCreate()
Dequeues an array of messages from a queue. All messages in the array are dequeued with the same option and have the same queue table payload column TDO.
sword OCIAQDeqArray ( OCISvcCtx *svchp,
OCIError *errhp,
OraText *queue_name,
OCIAQDeqOptions *deqopt,
ub4 *iters,
OCIAQMsgProperties **msgprop,
OCIType *payload_tdo,
void **payload,
void **payload_ind,
OCIRaw **msgid,
void *ctxp,
OCICallbackAQDeq (cbfp)
(
void *ctxp,
void **payload,
void **payload_ind
),
ub4 flags );
OCI service context (unchanged from OCIAQDeq()).
An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error (unchanged from OCIAQDeq()).
The name of the queue from which messages are dequeued (unchanged from OCIAQDeq()).
A pointer to an OCIAQDeqOptions descriptor (unchanged from OCIAQDeq()).
OCI_DTYPE_AQDEQ_OPTIONS OCI type constant has the additional attribute OCI_ATTR_MSG_DELIVERY_MODE (introduced in Oracle Database 10g Release 2) with the following values:
OCI_MSG_PERSISTENT (default)
OCI_MSG_BUFFERED
OCI_MSG_PERSISTENT_OR_BUFFERED
On input, the number of messages to dequeue. On output, the number of messages successfully dequeued.
An array of pointers to OCIAQMsgProperties descriptors, of OCI type constant OCI_DTYPE_AQMSG_PROPERTIES, which can have the following values:
OCI_AQ_PERSISTENT (default)
OCI_AQ_BUFFERED
A pointer to the TDO of the queue table's payload column.
An array of pointers to dequeued messages.
An array of pointers to indicators.
An array of pointers to the message ID of the dequeued messages.
The context that is passed to the callback function.
The callback that can be registered to provide a buffer pointer into which the dequeued message is placed. If NULL, then messages are dequeued into buffers pointed to by payload.
Not currently used; pass as OCI_DEFAULT.
Users must have the AQ_USER_ROLE or privileges to execute the DBMS_AQ package to use this call. The OCI environment must be initialized in object mode (using OCIEnvCreate(), OCIEnvNlsCreate()), or OCIInitialize() (deprecated) to use this call.
A nonzero wait time, as specified in the OCIAQDeqOptions, is recognized only when there are no messages in the queue. If the queue contains messages that are eligible for dequeuing, then the OCIAQDeqArray() function dequeues up to iters messages and returns immediately.
This function is not supported in nonblocking mode.
OCIAQDeq(), OCIAQEnqArray(), OCIAQListen2(), OCIInitialize() (deprecated), OCIEnvCreate(), OCIEnvNlsCreate()
sword OCIAQEnq ( OCISvcCtx *svch,
OCIError *errh,
OraText *queue_name,
OCIAQEnqOptions *enqueue_options,
OCIAQMsgProperties *message_properties,
OCIType *payload_tdo,
void **payload,
void **payload_ind,
OCIRaw **msgid,
ub4 flags );
OCI service context.
An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
The target queue for the enqueue operation.
The options for the enqueue operation; stored in an OCIAQEnqOptions descriptor.
The message properties for the message. The properties are stored in an OCIAQMsgProperties descriptor, of OCI type constant OCI_DTYPE_AQMSG_PROPERTIES, introduced in Oracle Database 10g Release 2.
Descriptor OCI_DTYPE_AQMSG_PROPERTIES has the attribute OCI_ATTR_MSG_DELIVERY_MODE, which has the following values:
OCI_MSG_PERSISTENT (default)
OCI_MSG_BUFFERED
The TDO (type descriptor object) of an object type. For a raw queue, this parameter should point to the TDO of SYS.RAW.
A pointer to a pointer to an instance of an object type. For a raw queue, this parameter should point to an instance of OCIRaw.
OCI provides functions that allow the user to set attributes of the payload, such as its text.
See Also:
"Manipulating Object Attributes" for information about setting these attributesA pointer to a pointer to the program variable buffer containing the parallel indicator structure for the object type.
The message ID.
Not currently used; pass as OCI_DEFAULT.
Users must have the AQ_USER_ROLE or privileges to execute the DBMS_AQ package to use this call.
The OCI environment must be initialized in object mode (using OCIEnvCreate(), OCIEnvNlsCreate()), or OCIInitialize() (deprecated) to use this call.
See Also:
"OCI and Streams Advanced Queuing" for more information about OCI and Advanced Queuing
To obtain a TDO for the payload, use OCITypeByName(), or OCITypeByRef().
OCIAQDeq(), OCIAQListen2(), OCIInitialize() (deprecated), OCIEnvCreate(), OCIEnvNlsCreate()
Enqueues an array of messages to a queue. The array of messages is enqueued with the same options and has the same payload column TDO.
sword OCIAQEnqArray ( OCISvcCtx *svchp,
OCIError *errhp,
OraText *queue_name,
OCIAQEnqOptions *enqopt,
ub4 *iters,
OCIAQMsgProperties **msgprop,
OCIType *payload_tdo,
void **payload,
void **payload_ind,
OCIRaw **msgid,
void *ctxp,
OCICallbackAQEnq (cbfp)
(
void *ctxp,
void **payload,
void **payload_ind
),
ub4 flags );
The service context (unchanged from OCIAQEnq()).
The error handle (unchanged from OCIAQEnq()).
The name of the queue in which messages are enqueued (unchanged from OCIAQEnq()).
A pointer to an OCIAQEnqOptions descriptor (unchanged from OCIAQEnq()).
On input, the number of messages to enqueue. On output, the number of messages successfully enqueued.
An array of pointers to OCIAQMsgProperties descriptors, of OCI type constant OCI_DTYPE_AQMSG_PROPERTIES, introduced in Oracle Database 10g Release 2.
OCI_DTYPE_AQMSG_PROPERTIES has the attribute OCI_ATTR_MSG_DELIVERY_MODE, which has the following values:
OCI_MSG_PERSISTENT (default)
OCI_MSG_BUFFERED
A pointer to the TDO of the queue table's payload column.
An array of pointers to messages to be enqueued.
An array of pointers to indicators, or a NULL pointer if indicator variables are not used.
An array of pointers to the message ID of the enqueued messages, or a NULL pointer if no message IDs are returned.
The context that is passed to the registered callback function.
A callback that can be registered to provide messages dynamically. If NULL, then all messages must be materialized before calling OCIAQEnqArray().
Not currently used; pass as OCI_DEFAULT.
OCIAQEnq(), OCIAQDeqArray(), OCIAQListen2(), OCIInitialize() (deprecated), OCIEnvCreate(), OCIEnvNlsCreate()
Listens on one or more queues on behalf of a list of agents. Supports buffered messaging and persistent queues. Introduced in Oracle Database 10g Release 2.
sword OCIAQListen2 (OCISvcCtx *svchp,
OCIError *errhp,
OCIAQAgent **agent_list,
ub4 num_agents,
OCIAQListenOpts *lopts,
OCIAQAgent **agent,
OCIAQLisMsgProps *lmops,
ub4 flags);
The service context handle.
An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
List of agents for which to monitor messages.
Number of agents in the agent list.
Type constant OCI_DTYPE_AQLIS_OPTIONS has the following attributes:
OCI_ATTR_WAIT - Maximum wait time, in seconds, for the listen call
OCI_ATTR_MSG_DELIVERY_MODE - Has one of these values:
OCI_MSG_PERSISTENT
OCI_MSG_BUFFERED
OCI_MSG_PERSISTENT_OR_BUFFERED
Agent for which there is a message. OCIAgent is an OCI descriptor.
OCI_DTYPE_AQLIS_MSG_PROPERTIES (listen message properties) has one attribute, OCI_ATTR_MSG_DELIVERY_MODE, which has the following values:
OCI_MSG_PERSISTENT
OCI_MSG_BUFFERED
Not currently used; pass as OCI_DEFAULT.
This is a blocking call that returns when there is a message ready for consumption for an agent in the list. If there are no messages found when the wait time expires, an error is returned.
A subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set.
See Also:
"Subscription Handle Attributes"An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
Call-specific mode. The only valid value is OCI_DEFAULT. OCI_DEFAULT executes the default call that discards all notifications on this subscription until the subscription is enabled.
This call is used to temporarily turn off notifications. This is useful when the application is running a critical section of the code and should not be interrupted.
The user need not be connected or authenticated to perform this operation. A registration must have been performed to the subscription specified by the subscription handle before this call is made.
All notifications after an OCISubscriptionDisable() are discarded by the system until an OCISubscriptionEnable() is performed.
Enables a subscription registration that has been disabled. This turns on all notifications.
A subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set.
See Also:
"Subscription Handle Attributes"An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
Call-specific mode. The only valid value is OCI_DEFAULT. This value executes the default call that buffers all notifications on this subscription until a subsequent enable is performed.
This call is used to turn on notifications after a subscription registration has been disabled.
The user need not be connected or authenticated to perform this operation. A registration must have been done for the specified subscription before this call is made.
Posts to a subscription that allows all clients who are registered for the subscription to get notifications.
ub4 OCISubscriptionPost ( OCISvcCtx *svchp,
OCISubscription **subscrhpp,
ub2 count,
OCIError *errhp
ub4 mode );
An OCI service context (after release 7). This service context should have a valid authenticated user handle.
An array of subscription handles. Each element of this array should be a subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set.
See Also:
"Subscription Handle Attributes"The OCI_ATTR_SUBSCR_PAYLOAD attribute must be set for each subscription handle before this call. If it is not set, the payload is assumed to be NULL and no payload is delivered when the notification is received by the clients that have registered interest. Note that the caller must preserve the payload until the post is done, as the OCIAttrSet() call keeps track of the reference to the payload but does not copy the contents.
The number of elements in the subscription handle array.
An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
Call-specific mode. The only valid value is OCI_DEFAULT. This value executes the default call.
Posting to a subscription involves identifying the subscription name and the payload if desired. If no payload is associated, the payload length can be set to 0.
This call provides a best-effort guarantee. A notification goes to registered clients at most once.
This call is primarily used for nonpersistent notification and is useful for several system events. If the application needs more rigid guarantees, it can use the Advanced Queuing functionality by enqueuing to the queue.
ub4 OCISubscriptionRegister ( OCISvcCtx *svchp,
OCISubscription **subscrhpp,
ub2 count,
OCIError *errhp
ub4 mode );
An OCI service context (after release 7). This service context should have a valid authenticated user handle.
An array of subscription handles. Each element of this array should be a subscription handle with all of the following attributes set:
OCI_ATTR_SUBSCR_NAME
OCI_ATTR_SUBSCR_NAMESPACE
OCI_ATTR_SUBSCR_RECPTPROTO
Otherwise, an error is returned.
One of the following attributes must also be set:
OCI_ATTR_SUBSCR_CALLBACK
OCI_ATTR_SUBSCR_CTX
OCI_ATTR_SUBSCR_RECPT
See Also:
"Subscription Handle Attributes" for information about the handle attributesWhen a notification is received for the registration denoted by subscrhpp[i], either the user-defined callback function (OCI_ATTR_SUBSCR_CALLBACK) set for subscrhpp[i] is invoked with the context (OCI_ATTR_SUBSCR_CTX) set for subscrhpp[i], or an email is sent to (OCI_ATTR_SUBSCR_RECPT) set for subscrhpp[i], or the PL/SQL procedure (OCI_ATTR_SUBSCR_RECPT) set for subscrhpp[i] is invoked in the database, provided the subscriber of subscrhpp[i] has the appropriate permissions on the procedure.
The number of elements in the subscription handle array.
An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
Call-specific mode. Valid values are:
OCI_DEFAULT - Use when there is only one server DN in the server DN descriptor. The registration request is sent to the database. If a database connection is not available, the registration request is detoured to the LDAP server.
OCI_REG_LDAPONLY - The registration request is sent directly to the LDAP server. Use this mode when there are multiple server DNs in the server DN descriptor, or you are certain that a database connection is not available.
Whenever a new client process comes up, or an old one goes down and comes back up, it must register for all subscriptions of interest. If the client stays up and the server first goes down and then comes back up, the client continues to receive notifications for registrations that are DISCONNECTED. However, the client does not receive notifications for CONNECTED registrations, as they are lost after the server goes down and comes back up.
This call is invoked for registration to a subscription that identifies the subscription name of interest and the associated callback to be invoked. Interest in several subscriptions can be registered simultaneously.
This interface is only valid for the asynchronous mode of message delivery. In this mode, a subscriber issues a registration call that specifies a callback. When messages are received that match the subscription criteria, the callback is invoked. The callback may then issue an explicit message_receive (dequeue) to retrieve the message.
The user must specify a subscription handle at registration time with the namespace attribute set to OCI_SUBSCR_NAMESPACE_AQ.
The subscription name is the string SCHEMA.QUEUE if the registration is for a single consumer queue and SCHEMA.QUEUE:CONSUMER_NAME if the registration is for a multiconsumer queue. The string should be in uppercase.
Each namespace has its own privilege model. If the user performing the registration is not entitled to register in the namespace for the specified subscription, an error is returned.
ub4 OCISubscriptionUnRegister ( OCISvcCtx *svchp,
OCISubscription *subscrhp,
OCIError *errhp
ub4 mode );
An OCI service context (after release 7). This service context should have a valid authenticated user handle.
A subscription handle with the OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes set.
See Also:
"Subscription Handle Attributes"An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.
Call-specific mode. Valid values are:
OCI_DEFAULT - Use when there is only one server DN in the server DN descriptor. The registration request is sent to the database. If a database connection is not available, the registration request is detoured to the LDAP server.
OCI_REG_LDAPONLY - The registration request is sent directly to the LDAP server. Use this mode when there are multiple server DNs in the server DN descriptor, or you are certain that a database connection is not available.
Unregistering a subscription ensures that the user does not receive notifications regarding the specified subscription in the future. If the user wants to resume notification, then the only option is to reregister for the subscription.
All notifications that would otherwise have been delivered are not delivered after a subsequent registration is performed because the user is no longer in the list of interested clients.