Managing MessageQ

 

This chapter describes how to manage MessageQ software on your system by performing the following tasks:

• Using the Monitor Utility

• Connecting to the MessageQ Environment

• Starting a Message Queuing Group

• Shutting Down a Running Group

• Starting a Cross-Group Connection

• Stopping a Cross-Group Connection

• Running the Client Library Server (CLS)

• Restricting Remote Access to the CLS

• Managing Message Recovery Services (MRS)

• Changing Group Characteristics at Runtime

Using the Monitor Utility

The Monitor utility is a MessageQ application that allows you to monitor and control the performance of your MessageQ NT system.

This chapter describes how the Monitor utility lets you manage MessageQ functions such as:

• Connecting to the MessageQ Environment

• Starting and Stopping Queues

• Starting and Stopping Cross-Group Connections

• Managing Message Recovery Services

Connecting to the MessageQ Environment

Before running a program that uses MessageQ, you must set the environment to identify the message queuing bus and the message queuing group with which the program will be associated. Connecting to the MessageQ environment can be accomplished from the command line, or from the Monitor utility.

Connecting to a Group from the Command Line

A MessageQ program associates itself with a specified bus ID and group ID at run time by obtaining the values of the DMQ_BUS_ID and DMQ_GROUP_ID environment variables.

These values can be set from the command line, as follows:

SET DMQ_BUS_ID=bus_id

SET DMQ_GROUP_ID=group_id

where:

bus_id	Numeric bus ID; 1 to 9999
group_id	Numeric group ID; 1 to 32000

You can establish default values for these symbols by adding these environment variables to your profile with the System applet in the Control Panel. You can also add code to your MessageQ application that sets these environment variables using the WIN32 call SetEnvironment variable. See your Windows NT programmer's documentation for more information.

Connecting to a Running Group From the Monitor Utility

To use the Monitor Utility, you must have at least one group running in order to connect to the MessageQ environment. You can connect to a running group from the MessageQ Monitor utility using the following procedure:

1. Select the File pull-down menu and choose Connect.

   

2. Enter the Bus ID, Group ID, and click OK.

   

Starting a Message Queuing Group

There are several ways you can start a MessageQ for Windows NT message queuing group. You can start it from:

• The command line

• The Monitor utility

• A Group Control Process (GCP) icon

• The Startup program group

You can also start MessageQ as a Windows NT service. See Starting the MessageQ Service for Windows NT, for more information

Starting a Group from the Command Line

To start MessageQ you must invoke the MessageQ startup procedure (dmqstartup) to start each referenced group in the group initialization file.

The MessageQ startup procedure executable image is dmqstartup, and is run interactively by entering the following command:

dmqstartup -b bus_id -g group_id -f filespec -n group_name [-l logfile_name]

Where:

-b bus_id	Numeric bus ID; maximum of four digits
-g group_id	Numeric group ID; maximum of five digits
-f filespec	The pathname and file specification of the group initialization file
-n group_name	Descriptive alphanumeric name for this group. No spaces or special characters are allowed.
-l logfile_name	Optional log file name. You must specify a pathname and file specification. Note that if you do not use a log file, the output displays to the screen in an "unformatted" manner.

MessageQ for Windows NT uses the bus ID and group ID to locate configuration information in the Windows NT Registry. Note that when you start a group from the command line, the default log file dmqlog.log is placed in the current directory.

Starting a Group From the Monitor Utility

You can start a group from the MessageQ Monitor utility using the following procedure:

1. Select the Manage pull-down menu, choose the Group option and then select Start.

2. Enter the Bus Number ID

3. Enter the Group Number ID.

4. Enter the Group Name.

5. Enter the full path to the Group Initialization File.

   For example: C:\user3\users\jones\bigfile.init

6. Click OK.

Creating a Custom Group Startup Icon on the Desktop

Follow this procedure to create a custom Group Startup icon to start a message queuing group under MessageQ for Windows NT:

1. Position the cursor anywhere on the desktop and click the right mouse button.

2. Select the New and then Shortcut option to create a desktop shortcut.

3. On the Create Shortcut menu, enter the appropriate syntax to start the MessageQ Group Control Process (dmqgcp.exe) supplying the necessary information to startup the selected group. For example:

   c:\...\bin\dmqgcp.exe -b 1 -g 9 -f init.txt -n group9

   Click the Next button to proceed to the next screen.

4. On the Select a Title for the Program screen enter a name for the desktop shortcut and and press Finish. The newly created icon will appear on your desktop.

5. Now you can start this group at any time by doubleclicking the icon.

Starting a Group from the Startup Program Group

Follow this procedure to add the message queuing group to the startup menu to be started automatically when you log in to your Windows NT user account.

1. From the start menu select the Settings and then the Taskbar option.

2. On the Taskbar Properties menu, select the Start Menu Programs tab and click the Add button.

3. On the Create Shortcut menu, enter the appropriate syntax to start the MessageQ Group Control Process (dmqgcp.exe) supplying the necessary information to startup the selected group. For example:

   c:\...\bin\dmqgcp.exe -b 1 -g 9 -f init.txt -n group9

   Click the Next button to proceed to the next screen.

4. On the Select Program Folder menu, select the Startup folder as the location for the shortcut.

5. On the Select a Title for the Program screen enter a name for the desktop shortcut and press Finish. The shortcut will be available in the Startup folder and the group will automatically start each time you log in to your account.

Shutting Down a Running Group

MessageQ offers a shutdown procedure to shut down a running group from the command line, the Monitor Utility, or from the Group Control Process system menu.

Shutting Down a Group from the Command Line

The MessageQ shutdown procedure executable image is dmqshutdown, and is run interactively by entering the following command:

dmqshutdown -b bus_id -g group_id [-f]

Where:

-b bus_id	Numeric bus ID; maximum of four digits
-g group_id	Numeric group ID; maximum of five digits
-f	Fast shutdown. If you select this option, MessageQ terminates all MessageQ processes in the group immediately. When the group is stopped, messages can no longer be delivered to the queues and all pending messages in the queues are lost.

The group shutdown procedure, with the -f option not selected, stops all queues immediately without draining the messages in the queues. Further, it stops all links immediately and provides an orderly shutdown of all MessageQ processes.

Shutting Down a Group From the Monitor Utility

Use the following procedure to shutdown a group from the Monitor Utility:

1. Select the Manage pull-down menu.

2. Select Group.

3. Select Stop Fast or Stop.

   If you select Stop, MessageQ stops all queues in the group, allowing them to be emptied. Applications can continue to read messages from the queues until all are empty. However, applications cannot place messages in the queues. After all the queues are empty, the MessageQ processes in the group will terminate.

   If you select Stop Fast, MessageQ terminates all MessageQ processes in the group immediately. When the group is stopped, messages can no longer be delivered to the queues and all pending messages in the queues are lost.

4. MessageQ displays a warning:

   Do you really want to stop group n?

5. Click OK.

Shutting Down a Group From the Group Control Process System Menu

Use the following procedure to stop a message queuing group from the Group Control Process system menu:

1. Select the GCP icon for the running group on the desktop to display the System menu.

2. Select Close from the System menu to remove the GCP icon.

   Only icons for the GCP and CLS processes are displayed on the status bar. To check for any orphaned group processes, use the Windows NT Task Manager utility.

   Note: All MessageQ processes can be closed by selecting Close from their respective system menus. However, this should only be done if the GCP shutdown fails to terminate a process normally.

Starting a Cross-Group Connection

You can start a cross-group connection, also called a link, using the MessageQ Monitor utility.

The following procedure describes how to start a Cross-Group connection:

1. Select the Manage pull-down menu.

2. Select Link.

3. Select Start.

4. Select a link number from the list.

5. Click OK.

Stopping a Cross-Group Connection

You can stop a cross-group connection using the MessageQ Monitor utility.

The following procedure describes how to stop a cross-group connection:.

1. Select the Manage pull-down menu.

2. Select Link.

3. Select Stop Fast.

4. Select a link number from the list.

5. Click OK.

Starting a Queue

You can restart a queue that has been previously stopped using the MessageQ Monitor utility.

The following procedures describe how to start a queue:

1. Select the Manage pull-down menu.

2. Select Queue.

3. Select Start.

4. Select a queue number from the list.

5. Click OK.

Stopping a Queue

You can stop a queue using the MessageQ Monitor utility.

The following procedure describes how to stop a queue:

1. Select the Manage pull-down menu.

2. Select Queue.

3. Select Stop Fast or Stop

   If you select Stop, MessageQ stops all queues in the group, allowing them to be emptied. Applications can continue to read messages from the queues until all are empty. However, applications cannot place messages in the queues. After all the queues are empty, the MessageQ processes in the group will terminate.

   If you select Stop Fast, MessageQ terminates all MessageQ processes in the group immediately. When the group is stopped, messages can no longer be delivered to the queues and all pending messages in the queues are lost.

4. Select a queue number from the list.

5. Click OK.

Running the Client Library Server

The Client Library Server (CLS) runs as a Windows NT application program that uses MessageQ for Windows NT. It is important to define the environment variables described in Connecting to the MessageQ Environment earlier in this chapter, because they identify the MessageQ Server group where the Windows clients connect. Additionally, the message queues used by Windows clients must be defined in the MessageQ for Windows NT group configuration.

The CLS creates a thread for each client connection from a MessageQ Windows Client. The CLS window displays a count of the number of clients currently connected, and for each client displays the server thread ID, client host name, client task ID, and queue number attached.

For convenience and ease of application management, CLS servers are normally started when a MessageQ group starts, and are stopped when the MessageQ group is shut down. Once the MessageQ group is started ou can start a CLS server from the Monitor utility.

Starting CLS

Use the following procedure to start the CLS:

1. Select the Manage pull-down menu.

2. Select CLS.

3. Select Start.

4. Enter the endpoint number.

Stopping the CLS

Use the following procedure to stop the CLS:

1. Select the Manage pull-down menu.

2. Select CLS.

3. Select Stop Fast.

4. Enter the endpoint number.

Restricting Remote Access to CLS

The CLS security file is a text file containing a table of client entries. Each client entry contains a list of endpoints and queues which the client may use. CLS uses the security file to restrict access by remote clients to those endpoints and queues. MessageQ groups can have their own separate security files, or can share one file jointly.

You can create a security file in one of two ways:

• Edit the template file that is distributed in the \TEMPLATES directory of the media kit.

• On Windows systems, you can use the Security Utility to edit the security file.

For LIBRARY client servers on NT systems, a template security file is available at the following location:

Program Files\BEA Systems\MessageQ\TEMPLATES\dmqclsec.txt

Begin by making a copy of the template security file. Then, edit the copy to remove the sample entries and add entries for the client systems in your environment. Copy the file to its target location and then associate the security file with the message queuing group.

When a CLS is started, it loads the security file specified in the %CLS section of the group initialization file. If no security file is specified, CLS will not restrict access by remote clients. Each CLS can have a separate security file, or a security file can be shared by multiple CLS processes.

For information about the CLS Security Utility, refer to the MessageQ Client for Windows User's Guide.

Managing Message Recovery Services

MessageQ Message Recovery Services (MRS) provide a mechanism for guaranteed message delivery by storing messages on disk and automatically attempting redelivery until the message is received by the target system.

If you enabled MRS as part of your group configuration, you can replay the contents of postconfirmation or dead letter journals using the Journal Replay utility. You may also print the contents of postconfirmation, dead letter, destination queue, or store and forward journals using the Journal Dump utility.

All journal file names are 16 characters long. Each journal file name contains a 12-digit filename, a dot, and a 3-character extension that identifies the journal type. Note that journal file names are unique within a group, but not between groups. Therefore, message queuing environments running more than one message queuing bus must ensure that journal files are not accidentally shared by groups running on different message queuing buses.

Valid journal filenames are of the format:

Format	Journal Type
ggggqqqqssss.DQF	Destination Queue File
ggggrrrrssss.SAF	Store and Forward
ggggssssssss.PCJ	Postconfirmation Journal
ggggssssssss.DLJ	Dead Letter Journal

Where:

g	Four-digit local group number in hexadecimal
q	Four-digit queue number in hexadecimal
r	Four-digit remote group number in hexadecimal
s	File sequence number in hexadecimal within a set of files

Replaying Journal Messages

The Journal Replay utility lets you resend the contents of postconfirmation or dead letter journals. The Journal Replay utility can use live recovery journals; however, if the journal file is currently in use, you must make a copy of the file before you can replay it. The Journal Replay utility can resend the entire journal file.

Messages sent from the postconfirmation or dead letter journal will be sent using the same source address, target address, delivery mode, and user notification. If the original message requested notification, the notification message is directed to the journal replay process instead of the original sender program.

To invoke the Journal Replay utility, enter the following command syntax. Switches enclosed in parentheses indicate optional command qualifiers.

dmqjplay -b bus -g group -m mode -t journal_type -j journal_path [-l log_path]

Table 3-1 describes the command options for dmqjplay.

Table 3-1 Journal Replay Utility Command Options

Switch	Argument	Description
-b	bus	Numeric Bus ID; maximum of 4 digits
-g	group	Numeric Group ID; maximum of 5 digits
-m	mode	A constant identifying the selected processing mode, as follows: r=replay ­ Retransmit the contents of the journal file and delete each message when it reaches the delivery interest point. t=transfer ­ Retransmit the contents of the journal file and delete each message when it reaches the delivery interest point. d=delete ­ Delete the contents of the selected journal.
-t	journal_type	A constant that designates the file to be replayed, as follows: d ­ Dead letter p ­ Postconfirmation
-j	journal_path	The pathname of the dead letter journal or postconfirmation journal that is to be replayed
-l	log_path	Optional log file. You must specify a pathname and file specification.

Printing Journal Files

The Journal Dump utility lets you produce a formatted report of the contents of a dead letter journal, postconfirmation journal, destination queue file, or a store and forward file. The Journal Dump utility can be used to print a live journal file if it is not in use. If the journal file is in use, you must halt the message recovery system for the group, and then use the Journal Dump utility to print the contents of the journal file.

To run the Journal Dump utility, enter the following command syntax (switches enclosed in parentheses indicate optional command qualifiers):

dmqjdump -b bus -g group -q queue -t journal_type -h header_type -m message_format -j journal_path [-d] [-l log_path] [-o output_file] [-n number]

Table 3-2 describes the command options for dmqjdump.

Table 3-2 Journal Dump Utility Command Options

Switch	Argument	Description
-b	bus	Numeric Bus ID; maximum of 4 digits
-g	group	Numeric Group ID; maximum of 5 digits
-q	queue	Queue number
-t	journal_type	A constant that designates the type of journal to be replayed, as follows: dlj ­ dlj - Dead letter journal dqf ­ dqf - Destination queue file pcj ­ pcj - Postconfirmation journal saf ­ saf - Store and forward file
-h	header_type	A constant that designates the header type, as follows: summary ­ Displays the source target, type and class of each message that is dumped. detail ­ Displays internal header fields of each message that is dumped.
-m	message_format	Specifies a valid message format, as follows: hex ­ Displays output in hexadecimal bytes with ASCII translation. script ­ Displays output in MessageQ script format.
-j	journal_path	The pathname of the dead letter journal, postconfirmation journal, destination queue, or store and forward file that is to be dumped.
-d		Deletes messages from the journal as they are dumped. Note: This option should be used with caution.
-l	log_path	Optional log file. You must specify a pathname and file specification.
-o	output_file	A pathname and file specification to receive the dump output
-n	number	The number of messages in the file you want to print, starting with the first message

Changing Group Characteristics at Runtime

You can use the Loader utility to dynamically reload the group initialization file without having to shutdown and restart MessageQ. The Loader utility lets you enter modified settings or parameter values into a running group initialization file.

To run the Loader utility, enter the following command format:

dmqloader -b n -g n -f init_file_path [-l logfile]

Where:

-b	Numeric Bus ID; maximum of 4 digits
-g	Numeric Group ID; maximum of 5 digits
-f	The pathname and file specification of the group initialization file
-l	Optional log file. You must specify a pathname and file specification

Table 3-3 describes the parameters in the group initialization file that can be modified at runtime.

Table 3-3 Modifiable Parameters in the Group Initialization File

Section in Initialization File	Parameter	Runtime Restriction?
%PROFILE	ACCEPT_KILL_COMMAND ATTACH_TMO DEFAULT_NAMESPACE_PATH	NO NO NO
%CLS	MAX_CLIENTS SECURITY_FILE	YES. CLS must be stopped. This parameter applies to OpenVMS systems only. YES. CLS must be stopped.
%XGROUP	RECONNECT RECONN_TIMER WINDOW_DELAY WINDOW_SIZE	YES. The link must be disabled. YES. The link must be disabled. YES. The link must be disabled. NO
%QCT	BYTE_QUOTA MESSAGE_QUOTA MESSAGE_QUOTA_ENABLE BYTE_QUOTA_ENABLED TYPE OWNER MRS_CONFIRM_STYLE PERM_ACTIVE SECURITY_ENABLED	NO NO NO NO YES. The queue must be empty and have no processes attached. When changing a primary queue to a secondary queue, the primary queue cannot have any secondary queues defined. YES. The queue must be empty and have no processes attached. To set this parameter to a value other than zero, the queue must be defined as a secondary queue, and the owning queue must be defined and be a primary queue. NO YES. The queue must be empty and have no processes attached. NO

Enabling or Disabling Quotas

The MessageQ Monitor utility lets you enable or disable quotas on permanent queues that you previously defined in the %QCT section of the group initialization file. You can enforce quotas on the maximum number of collected messages and bytes that can reside in a given queue.

If you are not concerned whether your application exceeds quotas, you should disable quotas to increase performance and reduce screen clutter.

Use the following procedure to enable or disable quotas:

1. Select the Manage pull-down menu.

2. Select Quotas.

3. Select Enable or Disable.

Setting Quotas for Dynamic Queues

Queue numbers with a number greater than Temporary Queue (FIRST_TEMP_QUEUE) are dynamically assigned. The BYTE_QUOTA and MSG_QUOTA values for dynamically assigned queues are set from the TEMPLATE entry in the %QCT section. Do not change any other value in the TEMPLATE queue entry.

Enabling Queue Quotas for Selective Queues

Previous versions of MessageQ required you to enable or disable queue quotas for an entire message queuing group. However, you can now enable queue quotas on a per queue basis on UNIX systems. You can enable or disable message and byte quotas for a selected queue at startup by setting the Quota Enable field for each entry in the %QCT section of the group initialization file. Table 2-9 contains the values that you can specify for the QUOTA_ENABLED attribute.

You can use the Monitor utility to enable or disable message and byte quotas for a selected queue at runtime. (See the Enabling or Disabling Quotas topic for more information.)

Defining Timeout Intervals for Link Drivers

The MessageQ link drivers provide parameters that let you define timeout intervals for testing the state of a cross-group connection, or aborting a connection with a cross-group link. These parameters are implemented as the following environment variables:

DMQLD_PING_INTERVAL	Specifies the amount of time a Link Sender process should wait before issuing another ping message to test the state of a connection. The ping interval is the number of seconds between tests. The default value is 30 seconds.
DMQLD_PING_TIMEOUT	Specifies the amount of time a Link Sender should wait for a response to a ping message before aborting. The default value is 60 seconds.

When tracing is enabled, the Link Receiver logs successful ping responses to the group log file.

If you must use a value other than the default, set both environment variables before starting your group.