|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
More OCI Relational Functions, 50 of 106
Registers a callback for message notification.
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:
Otherwise, an error will be returned.
One of attributes
must also be set.
For information about the handle attributes, see Subscription Handle Attributes
When a notification is received for the registration denoted by
subscrhpp[i], either the user-defined callback function (OCI_ATTR_SUBSCR_CBACK) set for
subscrhpp[i] will be invoked with the context (OCI_ATTR_SUBSCR_CTX) set for
subscrhpp[i], or an e-mail will be sent to (OCI_ATTR_SUBSCR_RECPT) set for
subscrhpp[i], or the PL/SQL procedure (OCI_ATTR_SUBSCR_RECPT) set for
subscrhpp[i], will be 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 you can pass to
OCIErrorGet() for diagnostic information in the event of an error.
Call-specific mode. Valid values:
Whenever a new client process comes up, or an old one goes down and comes back up, it needs to register for all subscriptions of interest. If the client stays up and the server first goes down and then comes back up, the client will continue to receive notifications for registrations that are DISCONNECTED. However, the client will not receive notifications for CONNECTED registrations as they will be lost once the server goes down and comes back up.
This call is invoked for registration to a subscription which identifies the subscription name of interest and the associated callback to be invoked. Interest in several subscriptions can be registered at one time.
This interface is only valid for the asynchronous mode of message delivery. In this mode, a subscriber issues a registration call which 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 'CONSUMER_NAME:SCHEMA.QUEUE' if the registration is for a multi-consumer queue. The string should be in uppercase.
Each namespace will have its own privilege model. If the user performing the register is not entitled to register in the namespace for the specified subscription, an error is returned.