The MQSUBSCRIBE function is used
to register interest in MQSeries® messages published on a specified topic. Successful execution of
this function causes the publish and subscribe server to forward messages
matching the topic to the service point defined by subscriber-service.
The
subscriber-service specifies
a logical destination for messages that match the specified topic.
Messages that match
topic are placed on the queue
defined by
subscriber-service, and can be read
or received through a subsequent call to MQREAD, MQRECEIVE, MQREADALL,
or MQRECEIVEALL. For more details, visit
http://www.ibm.com/software/mqseries/.
The data type of the result is VARCHAR(1). The result
of the function is '1' if successful or '0' if unsuccessful.
Syntax
>>-MQSUBSCRIBE--(----------------------------------------------->
>--+----------------------------------------------+--topic--)--><
'-subscriber-service--,--+-------------------+-'
'-service-policy--,-'
The schema is DB2MQ for non-transactional message
queuing functions, and DB2MQ1C for one-phase commit transactional
MQ functions.
Function parameters
- subscriber-service
- A string containing the logical MQSeries subscription point to where messages matching topic will be sent. If specified, the subscriber-service must refer to a Subscribers
Service Point defined in the DB2MQ.MQPUBSUB table that has a type
value of 'S' for publisher service. If subscriber-service is not specified, then the DB2.DEFAULT.SUBSCRIBER will be used instead.
The maximum size of subscriber-service is 48 bytes.
- service-policy
- A string containing the MQSeries Service Policy to be used in handling the message.
If specified, the service-policy must refer
to a Policy defined in the DB2MQ.MQPOLICY table. A Service Policy
defines a set of quality of service options to be applied to this
messaging operation. These options include message priority and message
persistence. If service-policy is not specified,
then the default DB2.DEFAULT.POLICY will be used instead. The maximum size of
service-policy is 48 bytes.
- topic
- A string defining the types of messages to receive. Only messages
published with the specified topics will be received by this subscription.
Multiple subscriptions can coexist. The maximum size of topic is 40
bytes. Multiple topics can be specified in one string (up to 40 bytes
long). Each topic must be separated by a colon. For example, "t1:t2:the
third topic" indicates that the message is associated with all three
topics: t1, t2, and "the third topic".
Authorization
One of the following authorities is required
to execute the function:
- EXECUTE privilege on the function
- DATAACCESS authority
- DBADM authority
- SQLADM authority
Default PUBLIC privilege
In a non-restrictive database, EXECUTE privilege is granted to PUBLIC
when the function is automatically created.
Examples
Example 1: This example registers
an interest in messages containing the topic "Weather". The default
subscriber-service (DB2.DEFAULT.SUBSCRIBER) is registered as the subscriber and
the default service-policy (DB2.DEFAULT.POLICY) specifies the quality of
service.
VALUES MQSUBSCRIBE('Weather')
Example 2: This example demonstrates a subscriber registering
interest in messages containing "Stocks". The subscriber registers
as "PORTFOLIO-UPDATES" with policy "BASIC-POLICY".
VALUES MQSUBSCRIBE('PORTFOLIO-UPDATES','BASIC-POLICY','Stocks')