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
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')