msgsubscribe and msgunsubscribe

Description

Provides a SQL interface to subscribe or unsubscribe to a topic.

Syntax

 msg_subscribe::= msgsubscribe (subscription_name)
 msg_unsubscribe::=msgunsubscribe 
     (subscription_name [with {remove | retain}])
 subscription_name::=basic_character_expression

Parameters

subscription_name

The name of the subscription to which you are subscribing. A basic_character_expression.

with{remove | retain}

Removes or retains the durable subscription from the JMS message provider.

Examples

Example 1

Tells the JMS messaging provider to begin holding messages published to the topic registered as “subscription_1”:

select msgsubscribe (’subscription_1’)

Example 2

Tells the JMS messaging provider to stop holding messages published to the topic registered as “subscription_1”:

select msgunsubscribe(’subscription_1’)

Usage

• Before you specify a subscription with msgsubscribe or msgunscunscribe, you must register the subscription with sp_msgadmin. This example registers the durable subscription 'subscription_1':

  sp_msgadmin ’register’, ’subscription’, ’subscription_1’, 
       ’my_jms_provider?topic=topic.sample,user=user1,password=pwd’,
       ’Supplier=12345’, null, ’durable1’, ’client1’
  

• Once msgsubscribe is called, all messages published on the specified topic that qualify for the selector are held until msgconsume is called to read the messages. If you do not want to hold messages that arrive before you are ready to consume them, do not call msgsubscribe. Calling msgconsume without previously calling msgsubscribe starts the subscription when msgconsume is called.

• msgsubscribe starts a subscription for the client to receive messages defined by the endpoint and filter specified by subscription_name. It returns a 0 if it succeeds, or 1 if it fails.

• msgunsubscribe stops any current subscription for the client to the endpoint and filter specified by subscription_name. It returns a 0 if it succeeds, or 1 if it fails.

• If you specify with retain, the connection to the JMS messaging provider is terminated so that another subscription can connect, using the same subscriber client_id specified in the subscription. The durable subscriber remains defined within Adaptive Server and within the JMS message provider. If you specify with remove, the durable subscriber definition is removed from the JMS message provider. The default value is with retain.

  When you unsubscribe a subscription using with remove, it is possible to miss messages:

  <login>
  select msgsubscribe(’subscription_1’)
  select msgconsume(’subscription_1’)
  ...
  select msgconsume(’subscription_1’)
  select msgunsubscribe(’subscription_1’ WITH REMOVE)
  <logout>
  
  ----Messages published to the topic registered as subscription_1 are no
  ----longer held by the JMS provider
  
  <login>
  select msgsubscribe(’subscription_1’)
  select msgconsume(’subscription_1’)
  ...
  select msgconsume(’subscription_1’)
  select msgunsubscribe(’subscription_1’ WITH REMOVE)
  

  In a separate scenario, a SQL session releases a subscription so that another session can consume messages. This example shows session 1 releasing the subscription, so that Session 2 can begin consuming from it.

  Table 5-4: SQL sessions

  Session 1	Session 2
  select msgunsubscribe (’subscription_1’WITH RETAIN)
  selectmsgconsume (’subscription_1’)
  ...
  selectmsgconsume      ('subscription_1’)
  select msgunsubscribe (’subscription_1’ WITH RETAIN)
  ...
  	select msgsubscribe(’subscription_1’)
  	select msgconsume(’subscription_1’)
  	...
  	select msgconsume(’subscription_1’)
  	select msgunsubscribe(’subscription_1’      WITH RETAIN)

• The following example shows msgsubscribe used before the application logic is ready to read the messages that force the JMS client to hold messages. The application subscribes:

  select msgsubscribe (’subscription_1’)
  

  The client consumes the message multiple times, and uses other application logic not related to messaging. Then it is ready to read messages, and it receives all the messages that have arrived since msgsubscribe was called:

  select msgconsume(’subscription_1’)
  select msgconsume(’subscription_1’)
  

  The client application is finished with this subscription, and unsubscribes:

  select msgunsubscribe(’subscription_1’)
  

Copyright © 2004. Sybase Inc. All rights reserved.

View this book as PDF