Use the main menu to restart the MessageQ Servers.
3.4 Additional Configuration Tasks
The following topics are covered in this section:
MessageQ offers a variety of options for capturing and viewing system events. Event logging captures important information regarding the success and failure of MessageQ operations. You can use the information in MessageQ event logs to troubleshoot system problems. MessageQ allows you to configure a variety of event logging options, including the ability to:
If you are having problems with a MessageQ Server, look at the log
files for that server. Refer to Chapter 13 for more information on
how to locate and view server log files. If you are having difficulty
starting the MessageQ group, look at the COM Server log file. This
may include informative messages if the COM Server is having difficulty
during startup.
3.4.2 Adding Queue Names to Network-Wide Namespace
MessageQ includes a capability for creating a maintaining a global name space and for providing runtime look up of name-to-queue address translations. These services are provided by the MessageQ Naming Agent.
In addition to using the MessageQ global naming capability, you can
continue to use Distributed Namespace names using the DMQ$NA_MGR
utility. Refer to Chapter 8 for complete information on how to
configure and use the MessageQ global naming feature.
3.4.3 Changing Parameters in the Running Group
MessageQ allows you to change some group characteristics at runtime. To do so, you must edit the DMQ$INIT.TXT file for the group and then run the DMQ$LOADER program to modify queues, links, names, and other modifiable group characteristics. The ability to modify some group characteristics is dependent upon the state of the object being modified.
Group initialization file parameters that are removed from the DMQ$INIT.TXT file will not be removed from the running group. To remove characteristics, you must stop the group and then restart it after modifying the group initialization file to delete the unwanted characteristics.
MessageQ allows a limited number of multi-reader queues to be added to a running group without restarting the group. The limit is twice the initial number of MRQ entries or 20, whichever is greater. In addition, links to a remote group can be added to a group initialization file and activated by running the DMQ$LOADER program.
You can run the DMQ$LOADER from the MessageQ main menu by selecting Option 10. DMQ$LOADER also runs during the servers startup (@DMQ$STARTUP). Table 3-3 describes the parameters in the group initialization file that can be modified at runtime.
| Init File Section | Parameter | Runtime Restriction? |
|---|---|---|
| %PROFILE | ACCEPT_KILL_COMMAND | NO |
| ATTACH_TMO | NO | |
| DEFAULT_NAMESPACE_PATH | NO | |
| %CLS | MAX_CLIENTS | YES. CLS must be stopped. This parameter applies only to OpenVMS systems. |
| SECURITY_FILE | YES. CLS must be stopped. | |
| %XGROUP | RECONNECT | YES. The link must be disabled. |
| RECONN_TIMER | YES. The link must be disabled. | |
| WINDOW_DELAY | YES. The link must be disabled. | |
| WINDOW_SIZE | NO | |
| %QCT | BYTE_QUOTA | NO |
| MESSAGE_QUOTA | NO | |
| MESSAGE_QUOTA_ENABLE | NO | |
| BYTE_QUOTA_ENABLED | NO | |
| TYPE | 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. | |
| OWNER | 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. | |
| MRS_CONFIRM_STYLE | NO | |
| PERM_ACTIVE | YES. The queue must be empty and have no processes attached. | |
| SECURITY_ENABLED | NO |
To delete a message queuing group, take the following steps:
| Step | Action |
|---|---|
| 1. Bring down the group's servers | Run DMQ$SHUTDOWN.COM and specify the bus ID, group ID, and "Y" to remove installed images. |
| 2.Delete the group | Run DMQ$DELETE_GROUP.COM specifying the bus and group ID of the group to delete. If the group shares directories with another group, do NOT run DMQ$DELETE_GROUP.COM. Instead, delete the files specific to that group (see Section 4.5).
These files are:
|
MessageQ software customization includes defining the symbolic
usage of type and class codes within MessageQ application programs
and the MessageQ script facility. The DMQ$TYPCLS.TXT file contains
symbolic definitions of type and class codes. Refer to Chapter 8
for more information on how to edit this file to create or change
application-specific type and class codes.
3.4.6 MessageQ Hints and Tips
This section provides some helpful hints for configuring your MessageQ environment, including how to:
The default editor used by MessageQ command procedures is DECTPU. To change the default editor, change the global symbol DMQ$$EDITOR. For example, enter the following command to change the default editor to invoke your own customized DECTPU section file:
$ DMQ$$EDITOR:==EDIT/TPU/SECTION=SYS$LOGIN:MY_SEC.TPU$SECTION
You can define symbols that execute the command procedures commonly used by MessageQ application developers. We recommend that you define these symbols in the SYS$MANAGER:SYLOGIN command procedure.
Define the following symbol for setting the logical name table:
$ DMQ_SET :== @DUA1:[DMQ$V40.EXE]DMQ$SET_LNM_TABLE
Define the following symbol for invoking the MessageQ main menu:
$ DMQ :== @DMQ$EXE:DMQ$MENU
The DMQ$STARTUP.COM command procedure will not exit until all requested
servers have started and initialized. DMQ$STARTUP uses
DMQ$WAIT_FOR_SERVICE.EXE, which accepts one of the following keywords:
MRS, SBS, EVL, JRN, DECNET, TCPIP, ALL. If the service was specified
for startup in DMQ$INIT.TXT, then DMQ$WAIT_FOR_SERVICE will block until
the service has indicated to MessageQ that it is ready; or until
it times out (2 minutes).
3.4.6.4 Redirecting Configuration and Log Files
The user area and log area parameters allow you to redirect the location of the group's configuration and log files. Usually, you do this if you want the group to share configuration files with another group or for performance reasons. See Chapter 4 for cross-group communications.
If these parameters are not specified, DMQ$STARTUP uses the files in the following directories where the variable bbbb is the 4-digit bus ID and the variable ggggg is the 5-digit group ID.
To enable message queuing between different systems in a network, you must create MessageQ message queuing groups on each system and establish cross-group connections. Section 10.8 describes how to create message queuing groups. This chapter discusses cross-group connections.
Note:
Refer to Chapter 10 for detailed information on group customization.
The following topics are covered in this chapter:
Messages can be exchanged between message queuing groups through:
Groups can exchange messages directly or indirectly, as shown in the following table:
The following topics are covered in this section:
The cross-group connection table provides link drivers with the
information it needs to connect to other MessageQ message queuing
groups through DECnet or TCP/IP network communications.
4.2.2 Loading the Configuration Data
You can load this static routing table either by using the startup or by running the DMQ$LOADER utility (refer to Chapter 10 ).
When a queuing group is started, it parses the cross-group connection table and attempts to establish DECnet and TCP/IP links with all the other groups listed in the table. The link drivers maintain these links by reconnecting to them as specified by a timer that is set for each link.
The link drivers also attempt to reconnect to all the groups defined in
the cross-group connection table. A request for reconnection can be
sent to the link drivers using the
MONITOR utility (see Chapter 11 ) or link management messages (see
the BEA MessageQ Programmer's Guide ).
4.2.3 Using Cross-Group Connection Table Fields
The cross-group connection table in Example 4-1 begins with %XGROUP and contains the fields shown in Table 4-1 . Note that you can enter --1 in any field to designate the default entry.
Example 4-1 Cross-Group Connection Table
--------------------------------------------------------------------------- %XGROUP ***** Cross-Group Connection Table ****** * * gen buf buf recon win dly transport *gname gnumber node cnt warn max type endpt * sec sec *--------- ------- ---------------- --- --- --- --- --- --- ----- ----- ONE_TCPIP 1 sneezy.abc.com Y -1 -1 -1 -1 -1 TCPIP 2001 ONE_TCPIP 1 dopey.abc.com Y -1 -1 -1 -1 -1 TCPIP 2001 ONE_DECNET 1 sneezy Y 75000 -1 -1 -1 -1 DECNET ONE_DECNET 1 dopey Y 75000 -1 -1 -1 -1 DECNET * TWO_TCPIP 2 sleepy.abc.com Y -1 -1 -1 -1 -1 TCPIP 2002 TWO_TCPIP 1 sleepy.abc.com Y -1 -1 -1 -1 -1 TCPIP 2002 TWO_DECNET 2 sleepy Y 75000 -1 -1 -1 -1 DECNET TWO_FAILOVER 2 doc Y 75000 -1 -1 -1 -1 DECNET * * %EOS ---------------------------------------------------------------------------
| Field | Description | ||||||
|---|---|---|---|---|---|---|---|
| Gname | Specifies the MessageQ internal group name that is used to generate the include files. The MessageQ group name is a 1- to 16-character name. | ||||||
| Gnumber | Specifies the MessageQ internal number of the group. This number must be between 1 and 32000. | ||||||
| Node | Specifies the name of a system to connect to. Successive lines with various system names specify the backup systems for the group. A total of three lines for each transport may be specified. The first entry for each group determines the type of ne | ||||||
| Gen Cnt | Specifies the generate connection field that indicates how cross-group connections are reestablished after a network failure.
|
||||||
| Buf Warn | Also known as Threshold. Specifies the value for dynamic memory consumption at which congestion control will begin for this cross-group connection. This is not supported in MessageQ for OpenVMS V4.0A. | ||||||
| Buf Max | Also known as Buffer pool. Specifies the optional parameter that overrides the default write buffer pool size for a communications link. It is specified in 1024-byte increments and the default value is 100 (giving a total of 100 x 1024 bytes). The | ||||||
| Recon |
|
||||||
| Win | Specifies the maximum transmission window size, in messages, for this cross-group link. The default value for this field is 250. | ||||||
| Dly | Specifies the delay, in seconds, that a sender must wait before using a new window when the receiver is congested. The default value for this field is 1. Its minimum value is 0 and maximum is 2147483647 | ||||||
| Transport Type | Indicates the transport mechanism used for cross-group connections. Valid entries are DECNET and TCPIP. | ||||||
| Endpt | For TCP/IP, this field is the Internet port number. For DECnet communications, this field represents the user identification code (UIC) of the remote DECnet group. The default is 0. |
The local group in the cross-group connection table must have data entered for each transport mechanism used within the group. You can use DECnet or TCP/IP as transport mechanisms. When TCP/IP is defined as the transport for the local group that is booting, the COM Server automatically starts up the TCP/IP link driver. When DECnet is specified, the COM Server automatically starts up the DECnet link drivers.
There are two types of DECnet transports:
Under normal situations, the MessageQ protocol handshake correctly chooses between these two transports and establishes the link. Specify DECNET as the transport section of the Cross-Group Connection table to allow MessageQ to determine which DECnet link driver to use.
You can explicitly choose a specific driver for a Cross-Group connection by specifying DECNETV2 or DECNETV3 as the transport type rather than DECNET. DECNETV2 selects the COM Server for the trasport, while DECNETV3 selects the DECNET link driver (DECNET_LD). DECNETV2 is not supported when attempting to connect to a non-VMS platforms.
There can be a maximum of three entries for the same group/transport pair. Example 4-2 shows the cross-group connection table for a group named CENTRAL with a group number of ten. The is a maximum of three possible hosts for a group named GROUP1.
Example 4-2 Maximum Entries in Cross-Group Connection Table
--------------------------------------------------------------------------- %XGROUP ***** Cross-Group Connection Table ****** * * gen buf buf recon win dly transport *gname gnumber node cnt warn max type en * sec sec *--------- ------- ---------- --- --- --- --- --- --- ----- -- CENTRAL 10 myhost Y -1 -1 -1 -1 -1 TCPIP 10010 GROUP1 1 host1 Y -1 -1 -1 -1 -1 TCPIP 10001 GROUP1 1 host2 Y -1 -1 -1 -1 -1 TCPIP 10001 GROUP1 1 host3 Y -1 -1 -1 -1 -1 TCPIP 10001 GROUP1 1 host1 Y 75000 -1 -1 -1 -1 DECNET GROUP1 1 host2 Y 75000 -1 -1 -1 -1 DECNET GROUP1 1 host3 Y 75000 -1 -1 -1 -1 DECNET * * %EOS ---------------------------------------------------------------------------
Remote groups that are not listed in the Cross-Group Connection Table
can connect to your group if the XGROUP_VERIFY parameter in the Profile
section is set to NO. In the previous example, if cross-group verify is
disabled, connections from GROUP1 on any host will be accepted by
CENTRAL. To limit access by unlisted groups, set XGROUP_VERIFY to YES.
(See Chapter 14 .)
4.3 Using Message Routing
MessageQ uses message routing to exchange messages between systems that do not have a direct network link.
The following topics are covered in this section:
MessageQ message routing uses either static or dynamic tables as shown below:
| Method | Description |
|---|---|
| Static tables | These are the cross-group connection table and routing table of the DMQ$INIT.TXT file. |
| Dynamic tables | These tables are built out of the incoming cross-group messages from previously unknown groups. Through the process of route discovery, the local system learns the return path of a message sent from an unknown group. |
Figure 4-1 shows a sample configuration requiring full message routing capabilities. It describes the next hop that a message must take to reach the target group. It contains three message server groups capable of performing message routing. Each server group has a direct connection to each of the other server groups. The client groups each have a single connection to a server group. They depend on the server group to route all message traffic to the correct target group and learn the backlink from the route messages they are sending back.
Figure 4-1 shows a sample configuration that uses message routing.
Figure 4-1 Sample System Routing Configuration
Groups 3, 4, and 5 are server groups that provide message routing
services to the other groups.
4.3.2 Configuring and Loading the Tables
Groups can be defined in either the cross-group connection table or the routing table but not both. Duplicated entries are automatically deleted from the routing table.
All routing information entered in cross-group connection table and the routing table is loaded when the group starts up. There are two ways the routing table is loaded: using either the DMQ$LOADER or route discovery.
Once you have determined your routing configuration, you can create the appropriate entries in the cross-group connection and routing table sections of the DMQ$INIT.TXT file. Create a routing table for each group by editing the routing table section of the DMQ$INIT.TXT file.
All routing information entered in the cross-group connection and
routing table sections is loaded when the group starts up.
4.3.3 DMQ$INIT Routing Section
The %ROUTE section of the DMQ$INIT.TXT file is used to load the initial routing configuration. This section contains two columns of information.
| Column | Purpose of... |
|---|---|
| Target group | Specifies the number of the remote group that is the intended destination of messages. |
| Route-thru-group | Lists the group number which forms the network link between the local group and the remote target group. |
Note:
Refer to Section 3.2.6 on how to access and edit the cross-group connection table of the DMQ$INIT.TXT file.
For example, in order to build a DMQ$INIT.TXT file for the group 3 (configuration shown in Figure 4-1 ), entries are needed for all groups directly connected to it. All other groups will require an entry in the Routing Table in order to compute the next hop for the message.
Example 4-3 shows a sample of the cross-group connection and routing table sections.
Example 4-3 Sample Routing Table
--------------------------------------------------------------------------------
%XGROUP ***** Cross-Group Connection Table ******
*
* gen buf buf recon win dly transport
*gname gnumber node cnt warn max type endpt
* sec sec
*--------- ------- ------------------- --- ----- --- --- --- --- ----- -----
Server_1 3 Moe Y -1 -1 -1 -1 -1 DECNET
Server_2 4 Larry Y -1 -1 -1 -1 -1 DECNET
Server_3 5 Curly Y -1 -1 -1 -1 -1 DECNET
*
*Client_1 1 Sleepy N -1 -1 -1 -1 -1 DECNET
*Client_2 2 Doc N -1 -1 -1 -1 -1 DECNET
*Client_3 6 Dopey N -1 -1 -1 -1 -1 DECNET
*Client_4 7 Grumpy N -1 -1 -1 -1 -1 DECNET
*
%EOS
*
%ROUTE * initial routing table
*
* Target Route-Thru
* Group Group
* ------ ----------
1 3 * Group 1 is routed thru Group 3
2 3 * Group 2 is routed thru Group 3
6 5 * Group 6 is routed thru Group 5
7 5 * group 7 is routed thru Group 5
%EOS
-------------------------------------------------------------------------------
MessageQ for OpenVMS offers link drivers for several popular TCP/IP products including:
You must select one TCP/IP link driver because they are mutually exclusive. The "DMQ$TCPIP_LD" logical name indicates the selection and must exist prior to starting the group. This logical can be defined manually, or is defined automatically by the DMQ$BOOT.COM procedure. Define the DMQ$TCPIP_LD logical name as "DEC" to start the DEC/UCX link driver or "PSC" to start the TCPware link driver.
You can edit the DMQ$BOOT.COM procedure to start any of these drivers by changing the value associated with the DMQ$TCPIP_LD logical name. Access the DMQ$BOOT.COM procedure using the CUSTOMIZE option on the MessageQ main menu (see Chapter 10 or the DMQ$STARTUP procedure (Chapter 3 ).