MQSubscribe() function

Syntax

1  MQSUBSCRIBE (?  subscriber_name ,?  policy_name ,  topic )

subscriber_name

Optional parameter. Refers to the value in the pubsubname column of the "informix".mqiservice table. If subscriber_name is not specified, IDS.DEFAULT.SUBSCRIBER is used as the subscriber. The maximum size of subscriber_name is 48 bytes.

policy_name

Optional parameter. Refers to the value in the policyname column of the "informix".mqipolicy table. If policy_name is not specified, IDS.DEFAULT.PUB.SUB.POLICY is used as the policy. The maximum size of policy_name is 48 bytes.

topic

Required parameter. A string containing the topic for the message publication. The maximum size of a topic is 40 bytes. Multiple topics can be specified in one string (up to 40 characters 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. If no topic is specified, none are associated with the message.

Usage

The MQSubscribe() function is used to register interest in WMQ messages published on a specified topic. The subscriber_name specifies a logical destination for messages that match the specified topic. Messages published on the topic are placed on the queue referred by the service pointed to by the receiver column for the subscriber (subscriber_name parameter). These messages can be read or received through subsequent calls to the MQRead() and MQReceive() functions on the receiver service.

This function requires the installation of the WMQ Publish/Subscribe Component of WMQ and that the Message Broker must be running.

Return codes

1

The operation was successful.

Error

The operation was unsuccessful.

Examples

Example 1

The following table contains sample rows and columns in the "informix".mqipubsub table.

Sample rows	pubsubname column	receiver column	pubsubtype column
Sample row 1	'IDS.DEFAULT. PUBLISHER'	''	'Publisher'
Sample row 2	'IDS.DEFAULT. SUBSCRIBER'	'IDS.DEFAULT. SUBSCRIBER.RECEIVER'	'Subscriber'

begin;
EXECUTE FUNCTION MQSubscribe('IDS.DEFAULT.SUBSCRIBER',
   'IDS.DEFAULT.PUB.SUB.POLICY', 'Weather');
commit;

This statement demonstrates a subscriber registering an interest in messages containing the topic "Weather" with the following parameters:

• subscriber_name: "IDS.DEFAULT.SUBSCRIBER"
• policy_name: "IDS.DEFAULT.PUB.SUB.POLICY"
• topic: "Weather"

begin;
EXECUTE FUNCTION MQPublish('IDS.DEFAULT.PUBLISHER',
'IDS.DEFAULT.PUB.SUB.POLICY', 'Rain', 'Weather');
commit;

This statement publishes the message with the following parameters:

• publisher_name: "IDS.DEFAULT.PUBLISHER"
• policy_name: "IDS.DEFAULT.PUB.SUB.POLICY"
• msg_data: "Rain"
• topic: "Weather"
• correl_id: none

begin;
EXECUTE FUNCTION MQReceive('IDS.DEFAULT.SUBSCRIBER.RECEIVER',
'IDS.DEFAULT.PUB.SUB.POLICY');
commit;

This statement receives the message with the following parameters (it returns "Rain"):

• service_name: "IDS.DEFAULT.SUBSCRIBER.RECEIVER"
• policy_name: "IDS.DEFAULT.PUB.SUB.POLICY"

Example 2

begin;
EXECUTE FUNCTION MQSubscribe('Weather');
commit;

This example demonstrates a subscriber registering an interest in messages containing the topics "Weather" with the following parameters:

• subscriber_name: default subscriber
• policy_name: default policy
• topic: "Weather"

Example 3

begin;
EXECUTE FUNCTION MQSubscribe('PORTFOLIO-UPDATES',
 'BASIC-POLICY', 'Stocks:Bonds');
commit;

This example demonstrates a subscriber registering an interest in messages containing the topics "Stocks" and "Bonds" with the following parameters:

• subscriber_name: "PORTFOLIO-UPDATES"
• policy_name: "BASIC-POLICY"
• topic: "Stocks", "Bonds"