Chapter 1 Jaguar Configuration

Setting up the message service

The message service allows you to publish or send messages to a queue, where they are stored until they can be delivered to the message queue's recipient, which is either a client or a component. You can also subscribe to scheduled messages.

The message service provides transient and persistent message storage for message consumers and allows message producers to send messages to a particular message queue, or to publish messages with specific topics, available to all message queues.

For persistent message storage, use a database that is tuned for frequent inserts and deletes. For example, if you are using Adaptive Server Enterprise, use a database other than the master database and ensure that the transaction log is large enough to accommodate frequent transactions. See your database documentation for more information.

After you have configured the message service, it starts automatically when you start a Jaguar server.

See Chapter 31, "Using the Message Service" in the Jaguar CTS Programmer's Guide for information on publishing, sending, and receiving messages.

To configure the message service:

1. Make these changes to the MessageService.props file, located in %JAGUAR%\Repository\Component\CtsComponents (NT) $JAGUAR/Repository/Component/CtsComponents (UNIX):
   • To specify the connection cache, change the line cms.cache=MessageServiceCache to cms.cache=yourCache , where yourCache is the name of a user-defined JDBC connection cache that allows cache-by-name access.
   • To enable the JCM_FORCE option for access to the connection cache, change the line cms.force=false to cms.force=true .
   • To enable message service debugging at server start-up, change the line cms.debug=false to cms.debug=true .
   • If your database server does not accept the default syntax, change the SQL commands in the XX.YYYYYY statements. If the database does not have an image type, change image to unbounded (large) binary. If the database driver cannot handle character-set conversions, change the datatype of the varchar columns in the SQL schemas to varbinary.
   
   
   
2. On the All Properties tab in Jaguar Manager's Server Properties dialog, add "CtsComponents/MessageService" to the com.sybase.jaguar.server.services server property.
   
   
3. If your server is in a cluster:
   • For each server in the cluster, copy MessageService.props to $JAGUAR/Repository/Component/CtsComponents.
   • Synchronize the cluster. See Chapter 3, "Jaguar Clusters and Synchronization".
   
   
   
4. Restart the Jaguar server. Message service starts automatically when you start the server.
   
   

Administering the message service

You can administer the message service using the graphical interface.

To start the message service graphical interface:

1. Run one of these scripts:
   
   
   • UNIX - $JAGUAR/html/classes/msgadmin.sh
   • NT - %JAGUAR%\html\classes\msgadmin.bat
   
   
   
2. In the login window, enter the:
   
   
   • User Name Name authorized to access the message service.
   • Password Password for the user name.
   • Host Name Name of the machine where the message service resides.
   • Port Number Port number through which the connection to the message service is made.
   • Service CtsComponents/MessageService
   
   
   
3. Click Connect.
   
   

To enable debugging, in the Message Service Administration window, click Enable Debugging.

Adding the message service parts

Once you have configured the message service, add the message service parts using the Message Service Administration window:

• Message queues - add one message queue for each message recipient.
• Message topics - to identify the subject of messages that you publish or send, define message topics.
• Message queue selectors - to specify the topics of the published messages you want to receive, add a message queue selector for each topic.
• Listeners - to notify a component when a message arrives in its queue, add a listener for each message queue.
• Access roles - to restrict access to a message queue or to grant one user access to another user's queue, add access roles for the message queue. To restrict access to messages with a particular topic, add access roles for the topic.
• Thread pools - define thread pools to handle client and component notification.

To add a message queue:

1. Select the Configured Queues tab.
   
   
2. Click Add.
   
   
3. In the New Queue dialog, enter a name for the message queue.
   
   
4. Click OK.
   
   

To add a topic:

1. Select the Configured Topics tab.
   
   
2. Click Add.
   
   
3. In the New Topic dialog, enter the topic name.
   
   
4. Click OK.
   
   

To add a message queue selector:

1. If you are adding a selector to an active queue, select the Active Queues tab; if you are adding a selector to an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, click on the Selectors tab.
   
   
5. Click Add.
   
   
6. In the Add Selector dialog, enter the message queue selector. A selector is an expression that contains an equality condition for a topic and conforms to the Java Message Service (JMS) selector specification, which is a subset of the SQL-92 syntax. For example, to receive all published messages with the topic "StockPrice.SYBS", add this selector to the message queue:
   
   

   "topic = 'StockPrice.SYBS'"

   You can also set the selector to "TRUE" to match all message topics.
   
   
7. Click OK.
   
   

To add a listener for a message queue:

1. If you are adding a listener for an active queue, select the Active Queues tab; if you are adding a listener for an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, click on the Listeners tab.
   
   
5. Click Add.
   
   
6. In the Add Listener dialog, enter a listener that has been installed in Jaguar, in this format: package_name/component_name.
   
   
7. Click OK.
   
   

To add an access role for a message queue or message topic:

1. To add an access role for an active queue, select the Active Queues tab; to add an access role for an inactive queue, select the Configured Queues tab.
   
   To add an access role for an active topic, select the Active Topics tab; to add an access role for an inactive topic, select the Configured Topics tab.
   
   
2. Select a queue or topic from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, select the Roles tab.
   
   
5. Click Add.
   
   
6. In the Add Role dialog, enter the role name. You can use a wildcard character ("*") when the queue or topic does not require a specific role. For subtopics that do not require a specific role, the name can end with the wildcard character.
   
   
7. Select the role type:
   • Consumer To receive messages from the queue, or to receive messages with the specified topic.
   • Producer To publish or send messages to the queue, or to publish or send messages with the specified topic.
   • Security To administer the message queue or topic.
   
   
   
8. Click OK.
   
   

If more than one access role is assigned to a message queue or message topic, a client needs to possess only one of the roles to access the queue or topic. If a message queue or topic has no assigned roles, any client can access it.

To add a thread pool:

1. Select the Thread Pool tab.
   
   
2. Click Add.
   
   
3. In the New Thread Pool dialog, enter the name of the thread pool.
   
   
4. Click OK.
   
   

Configuring message queue and thread pool properties

To edit a message queue's configuration properties:

1. To edit properties for an active queue, select the Active Queues tab; to edit properties for an inactive queue, select the Configured Queues tab.
   
   
2. Select a queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, select the Configuration tab.
   
   
5. Edit the configuration properties:
   
   

   Property	Datatype	Default value	Description
   maximum	long	0	The maximum number of messages held in the queue; if set to zero or a negative number, there is no limit.
   timeout	long	0	The number of seconds the queue remains in memory when it is not being accessed by either a client or a listener; set to zero or a negative number for no timeout.
   receive	boolean	true	Indicates whether clients can receive messages from the queue. This is useful for shared queues that are accessed with list and move operations.
   store	boolean	true	Indicates whether to retain persistent messages when the queue is inactive.
   qop	string	"none"	Indicates the quality of protection required for the message queue object.

6. Click Set.
   
   

To deactivate a message queue:

1. Select the Active Queues tab.
   
   
2. Select a queue from the list.
   
   
3. Click Close.
   
   

To modify the number of threads in a thread pool:

1. Select the Thread Pool tab.
   
   
2. Select a thread pool from the list.
   
   
3. Click Properties.
   
   
4. Edit the number of threads.
   
   

   Property	Datatype	Default value	Description
   readers	long	0	The number of reader threads in the thread pool, which are used for client notification.
   writers	long	0	The number of writer threads in the thread pool, which are used for client notification.
   worker	long	0	The number of worker threads in the thread pool, which are used for component notification.

5. Click Save.
   
   

Viewing messages and statistics for queues and topics

To view a list of the messages in a queue:

1. To view messages in an active queue, select the Active Queues tab; to view messages in an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click List.
   
   

To view statistics for all message queues and topics:

1. Select the Statistics tab.
   
   

To view a message queue's statistics:

1. To view statistics for an active queue, select the Active Queues tab; to view statistics for an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, select the Statistics tab.
   
   

To view a message topic's statistics:

1. To view the statistics of an active topic, select the Active Topics tab; to view the statistics of an inactive topic, select the Configured Topics tab.
   
   
2. Select a topic from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, select the Statistics tab.
   
   

Deleting message service parts

To delete all the messages in a queue:

1. Select the Active Queues tab.
   
   
2. Select a queue from the list.
   
   
3. Click Flush.
   
   

To delete a message queue:

1. If you are deleting an active queue, select the Active Queues tab; if you are deleting an inactive queue, select the Configured Queues tab.
   
   
2. Select a queue from the list.
   
   
3. Click Delete.
   
   
4. In the Delete Queue confirmation dialog, click Yes.
   
   

If you are deleting an active queue, it must also be configured, otherwise, there is nothing to delete.

To delete a topic:

1. Select the Configured Topics tab.
   
   
2. Select a topic from the list.
   
   
3. Click Delete.
   
   
4. In the Delete Topic confirmation dialog, click Yes.
   
   

To delete an access role from a message queue:

1. If you are deleting an access role from an active queue, select the Active Queues tab; if you are deleting an access role from an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, select the Role tab.
   
   
5. Select a role from the list.
   
   
6. Click Delete.
   
   
7. In the Delete Role confirmation dialog, click Yes.
   
   

To delete a message queue selector:

1. If you are deleting a selector from an active queue, select the Active Queues tab; if you are deleting a selector from an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, click on the Selectors tab.
   
   
5. Choose a selector from the list.
   
   
6. Click Delete.
   
   
7. In the Delete Selector confirmation dialog, click Yes.
   
   

To delete a thread pool:

1. Select the Thread Pools tab.
   
   
2. Select a thread pool from the list.
   
   
3. Click Delete.
   
   
4. In the Delete Thread Pool confirmation dialog, click Yes.
   
   

To delete a listener:

1. If you are deleting a listener from an active queue, select the Active Queues tab; if you are deleting a listener from an inactive queue, select the Configured Queues tab.
   
   
2. Select a message queue from the list.
   
   
3. Click Properties.
   
   
4. In the Properties dialog, click on the Listeners tab.
   
   
5. Choose a listener from the list.
   
   
6. Click Delete.
   
   
7. In the Delete Listener confirmation dialog, click Yes.
   
   

Closing the graphical interface

To close the message service graphical interface, in the Message Service Administration window, click Exit.

Copyright © 2000 Sybase, Inc. All rights reserved.