MQSUBSCRIBE scalar function

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 the IBM MQ product page.

The data type of the result is VARCHAR(1). The result of the function is '1' if successful or '0' if unsuccessful.

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.

Syntax

Read syntax diagramSkip visual syntax diagramMQSUBSCRIBE(subscriber-service,service-policy,topic)

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".

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