For descriptions of the error messages generated by these conditions,
refer to the OpenVMS documentation on system messages, recovery
procedures, and OpenVMS software installation. For information on
installation requirements, see Chapter 1 .
2.4 PostInstallation Tasks for MessageQ
This section describes the tasks to be performed after installing MessageQ :
After MessageQ is installed, you can add automatic startup and
shutdown command procedures to the SYSTARTUP and SYSHUTDOWN command
procedures. Placing the MessageQ startup commands in SYSTARTUP
automatically starts MessageQ when the OpenVMS system boots.
Placing the MessageQ shutdown commands in SYSHUTDOWN causes a
clean MessageQ shutdown on a OpenVMS system shutdown.
2.4.2 Configuring and Managing the System
See Part 2 and Part 3 of this guide for information on the following tasks:
If you encounter a problem while using MessageQ , report it to
technical support using the contact information provided in the preface
of this manual.
2.5 Upgrading to MessageQ Version 4.0A
The following topics are covered in this section:
To continue to use your MessageQ data files created with previous versions of MessageQ, you must perform the upgrade conversion before you can run your applications using MessageQ for OpenVMS, Version 4.0A.
After you have successfully installed MessageQ for OpenVMS, Version
4.0A, use the MessageQ conversion utility (DMQ$CVT.COM) to upgrade the
group initialization file for a MessageQ Version V3.X message queuing
group to the new MessageQ for OpenVMS Version 4.0A format. You can also
build new MessageQ data files from the beginning by running the
MessageQ management utilities as described in Chapter 3 ,
Chapter 10 , and Chapter 11 .
2.5.2 Conversion Requirements
The conversion utility has the following requirements:
The Conversion utility performs the following functions with some user input:
To execute the conversion utility, enter at the DCL prompt:
$ @DMQ$DISK:[DMQ$V40.CVT]DMQ$CVT.COM
This command invokes the MessageQ Conversion Utility and allows you to
access the utility's menus.
2.5.5 Using the Conversion Main Menu
After you invoke the utility, the system displays the Conversion main menu as shown in Figure 2-1 .
Figure 2-1 MessageQ Version 4.0 Conversion Utility
----------------------------------------------------------------------------
Welcome to the BEA MessageQ V4 Conversion Utility
Option Description
------ -----------------------------------------------------
HELP Display information about the conversion
SETUP Setup the conversion environment. **DO THIS FIRST**
ALL Convert all known BUS and GROUPs.
CONVERT Convert one BUS or GROUP at a time.
MANUAL Select each phase of the conversion.
EXIT Return to DCL
Please select a menu option:
----------------------------------------------------------------------------
The main menu provides the following options:
| Option | Use it to... |
|---|---|
| HELP | Provide online help information about the utility. |
| SETUP | Locate the groups on the desired disk. Run the setup FIRST, before starting any conversions. |
| This option asks you the needed questions to determine what disk drive holds the MessageQ Version 2 and Version 3 directories. The specified disk is then searched for MessageQ groups. A list of the groups is created and placed in a configuration file. This configuration file is used throughout the conversion process to track the process. The configuration file is named DMQ$CVT_V3TO4_'node'.CFG. | |
Each group entry in the configuration file carries a status field which is updated on the successful completion of each phase of the conversion. The states are described as follows:
|
|
| ALL | Convert all groups to the new format. This menu option begins the automatic conversion of all MessageQ groups that were located in the SETUP. The conversion continues until all groups reach the DONE status, indicating completion. |
| CONVERT | This menu option allows the user to pick a specific MessageQ BUS or GROUP to convert. By selecting a BUS, the conversion utility automatically converts any GROUPs matching the desired BUS number. By selecting a GROUP, the user selects a single BUS/GROUP for conversion. |
| MANUAL | Select each phase of the conversion for every group allowing you to walk through each phase of the conversion.
|
For more detailed information about each option, you can select Help from each of the conversion utility menus.
Part II contains the following information:
| Chapter | Describes... |
|---|---|
| 3 | How to configure MessageQ during initial system configuration. |
| 4 | How to establish communication among applications running in different message queuing groups in a networked environment. |
| 5 | How to configure the message queues and global sections that MessageQ uses to send, store, and retrieve messages. |
| 6 | How to configure MessageQ systems to use recoverable messaging. |
| 7 | How to configure MessageQ systems to use message broadcasting. |
| 8 | How to use MessageQ shared local and global symbols. |
| 9 | How to communicate with MessageQ PC-based clients. |
To use MessageQ , begin by configuring a message queuing group on your local system. For MessageQ to exchange messages between networked systems, you must configure cross-group connections.
This chapter describes the initial configuration steps you must take to make MessageQ operational at a minimum level. As you use MessageQ and add new applications, you must upgrade the MessageQ message queuing environment to satisfy new requirements. This chapter describes additional configuration and system management that are described in more detail in Chapter 4 through Chapter 9 .
This chapter provides answers to key questions such as:
Before performing the tasks described in this chapter, use the Authorize Utility (AUTHORIZE) to create a MessageQ system management account with the following privileges:
| ALTPRI | CMKRNL | DETACH | EXQUOTA |
| GROUP | GRPNAM | NETMBX | OPER |
| PSWAPM | SYSGBL | SYSLCK | SYSNAM |
| SYSPRV | TMPMBX | WORLD |
After you install MessageQ software using SYS$UPDATE:VMSINSTAL, you must perform several initial configuration steps. The executables and command procedures necessary to perform these can be found in:
disk:[DMQ$Vnn.EXE]
where disk: is the disk drive on which MessageQ was installed and Vnn is the version (for example, V40). After the initial configuration steps have been performed, the logical name DMQ$EXE: will point to this directory. Until then you need to specify the directory name.
The initial configuration steps are:
| Step | Function | Use step to... |
|---|---|---|
| 1 | Run DMQ$CREATE_GROUP | Create the directory and initial configuration tables for a new MessageQ group. This step is not required if you performed conversion to MessageQ Version 4.0A from an earlier version. |
| 2 | Run DMQ$STARTUP.COM (without starting up servers) | Creates the required MessageQ logical name table allowing group configuration. |
| 3 | Edit DMQ$INIT.TXT file | Enter the configuration information (such as queue definitions, which servers to startup and inter-group message communications). |
| 4 | Run DMQ$STARTUP.COM | Start the MessageQ group. |
| 5 | Run DMQ$SHUTDOWN.COM | Shut down a running MessageQ group. |
To maintain group configurations, you may need to perform the following tasks:
The following topics are covered in this section:
Note:
If you have upgraded an earlier version of MessageQ to Version 4.0A using the conversion utility (see Section 2.5 ), your messaging groups have already been created.
A MessageQ message queuing network consists of one or more systems running MessageQ . Each instance of MessageQ running on a system is known as a MessageQ group. Each group consists of queues, servers, and shared resources.
All queues within a group reside on the same system, share inter-process communications mechanisms (such as global memory, files and locks) and are handled by the same set of server processes. The servers, in turn, communicate to queues within their group, as well as to servers in other groups on the bus.
Before a group can start operation, the group's resources need to be configured. In MessageQ for OpenVMS, each group has the following resources:
A message queuing group can consist of many message queues. A message queuing bus can have many message queuing groups. A networked system of computers may contain several message queuing buses which provide separate messaging domains.
The assignment of MessageQ bus and group IDs should be done as part of the application system design. A well-planned design for bus and group IDs for the message queuing environment is similar to planning the topology of a network. If planned well, the network can handle changes as applications are added and changed. If planned poorly, it can be difficult to accomplish even minor changes and those changes can cause interruptions to network users.
In some situations, you may need to run more than one MessageQ message queuing bus. A common situation for running multiple buses is when a test and production environment exist in the same network. MessageQ allows multiple, concurrent MessageQ buses to exist while ensuring that messages from different buses do not get mixed.
To create a bus, you create groups using the DMQ$CREATE_GROUP.COM command procedure and specify a new bus ID. The new bus will start running as soon as the groups within that message queuing bus are started. If more than one bus is required, the assignment of bus IDs should be designed using valid bus IDs in the range from 0001 to 9998.
Note:
Bus IDs 0 and 9999 are reserved. We recommend that application developers and system designers control the assignment of bus and group IDs to applications.
An orderly assignment of group IDs may correlate group IDs to some functional, application, or organizational strategy. This strategy should allow the addition of future functional, application, or organizational areas.
Every group connected to a message queuing bus must have a unique group
ID. MessageQ allows up to 32000 group IDs per message queuing bus.
A process for the registration and assignment of group IDs should
ensure that each group ID is unique and does not conflict with other
groups.
3.2.3 Creating Message Queuing Groups
Use the DMQ$CREATE_GROUP.COM command procedure to create message queuing groups. Execute DMQ$CREATE_GROUP once for each group to be created. This command procedure is located in the [DMQ$V40.EXE] directory.
DMQ$CREATE_GROUP has the following format:
$ DMQ$CREATE_GROUP bus_id group_id " " " " " " user_area log_area
where:
| bus_id | Required; It Defines the message queuing bus domain and is an integer between 1 and 9998 |
| group_id | Required; It defines a particular group within the message queuing bus and is an integer between 1 and 32000 |
| " " | Not used. |
| " " | Not used. |
| " " | Not used. |
| user_area | Optional: Allows you to share other groups' configuration files and is an OpenVMS directory or logical name containing a directory (See Section 4.5 .) |
| log_area | Optional: It provides a directory location of log files and is an OpenVMS directory or logical name containing a directory |
If you specify only the bus ID and group ID, DMQ$CREATE_GROUP creates the following default directories, where bbbb is the 4-digit bus ID and ggggg is the 5-digit group ID:
Example 3-1 shows how a group (bus 15 and group 1) is created.
Example 3-1 Invoking DMQ$CREATE_GROUP
$ @DUA1:[DMQ$V40.EXE]DMQ$CREATE_GROUP 15 1 %CREATE-I-CREATED, DUA1:[DMQ$V40.USER.0015_00001] created %CREATE-I-CREATED, DUA1:[DMQ$V40.LOG.0015_00001] created %CREATE-I-CREATED, DUA1:[DMQ$V40.MRS.0015_00001] created %DMQ-I-COPYFILE, Copying DMQ$BOOT.COM %DMQ-I-COPYFILE, Copying DMQ$INIT.TXT %DMQ-I-COPYFILE, Copying DMQ$TYPCLS.TXT %DMQ-I-COPYFILE, Copying HIDDEN_DATA_TYPES.PAS %DMQ-I-COPYFILE, Copying PAIENTBLI.TXT %DMQ-I-COPYFILE, Copying PAIENTPAS.TXT . . . %DMQ-I-COPYFILE, Copying PAITYPBLI.TXT %DMQ-I-COPYFILE, Copying PAITYPPAS.TXT %DMQ-I-COPYFILE, Copying PAMS_ADA_ENTRY_POINT_.ADA . . . %DMQ-I-COPYFILE, Copying PAMS_ADA_TYPE_CLASS_.ADA %DMQ-I-COPYFILE, Copying P_ENTRY.H . . %DMQ-I-COPYFILE, Copying P_TYPECL.H %DMQ-I-COPYFILE, Copying SYCUSTOMIZE.COM %DMQ-I-COPYFILE, Copying DMQ.TLB %DMQ-I-COPYFILE, Copying DMQ.MLB
MessageQ creates and utilizes a group logical name table for each MessageQ group. The logical names contained in each table are used by MessageQ to uniquely define the group.
The group logical name table is created when you run DMQ$STARTUP.COM. Once created, this logical name table will exist until either the system is rebooted or the DMQ$DEASSIGN.COM procedure is run.
To create the MessageQ group logical name table, execute DMQ$STARTUP without starting DMQ Servers.
MessageQ places all the logical names that a group requires in this group logical name table. The table is named DMQ$LNM_bbbb_ ggggg, where bbbb is the 4-digit bus ID and ggggg is the 5-digit group ID.
After the group logical name table is created, other processes (user or application) must run DMQ$SET_LNM_TABLE.COM to access the group table. A process must run this procedure in order to do the following:
Note:
We recommend that the DMQ$SET_LNM_TABLE command procedure be added to the user's LOGIN.COM file.
DMQ$SET_LNM_TABLE has the following format:
$ DMQ$SET_LNM_TABLE bus_id group_id [UNSET/NOEXEC]
where:
| bus ID | Required; Specifies the bus ID (an integer between 1-9998). |
| group ID | Required; Specifies the group ID (an integer between 1-32000) |
| UNSET/NOEXEC | Optional; specifies alternate processing (a character string of either UNSET or NOEXEC). |
If UNSET is used, the routine does the following:
|
|
| If NOEXEC is used, the routine will enter DMQ$LNM_TBL in the LNM$FILE_DEV logical name list and the LNM$PROCESS_DIRECTORY table in supervisory mode. |
For example, if MessageQ is installed on disk DUA1:, access the group with bus ID 15 and group ID 1 as follows:
$ @DUA1:[DMQ$V40.EXE]DMQ$SET_LNM_TABLE 15 1 %DMQ-I-SETLNM, Set to MessageQ LNM table DMQ$LNM_0015_00001
To create and maintain a MessageQ group configuration, you need to perform the initial configuration, add new queues, maintain queue characteristics, maintain cross-group connections, maintain group tables, and modify group performance characteristics. Group configuration information is stored in the DMQ$INIT.TXT file which is located in the DMQ$USER's directory.
The DMQ$INIT.TXT file contains information about:
Edit the DMQ$INIT.TXT file to add and change group configuration information. This file should be maintained by the system manager or other individual responsible for maintaining and managing the MessageQ environment. The file can be edited by any of the standard system provided editors or through the DMQ$MENU utility procedure (refer to Chapter 10 for more information on DMQ$MENU).
The DMQ$INIT.TXT file contains the following sections that you must customize for each group. Each section begins with a percent sign (%) and the name or an abbreviation for the name of the section. Table 3-1 describes each section of DMQ$INIT.TXT and tells you where to find more information about how to configure each section of the file.
| Section Header | Name | Description |
|---|---|---|
| %PROFILE | Profile | Must precede all other sections and specifies global or COM Server-specific parameters (See Section 3.2.6.1 .) |
| %XGROUP | Cross-Group Communications | Provides the COM Server with the information it needs to connect to other message queuing groups. The Cross-Group section should contain a entry for the node on which the group is running. (See Chapter 4 .) |
| %ROUTE | Message Routing | Enables cross-group communications paths among nodes with no direct network links (See Chapter 4 .) |
| %CLS | Client Library Server | Enables the support of multiple Microsoft Windows ® Client connections to a single OpenVMS process using DECnet and TCP/IP transports (See Chapter 9 .) |
| %BUFFER | Buffer Pool Configuration Table | Controls the size of the buffer pool where messages are stored (See Chapter 5 .) |
| %QCT | Queue Configuration Table | Contains the specifications for all permanent and temporary queues. The default QCT section is sufficient to run test programs but will require tailoring to meet you application needs. (See Chapter 5 .) |
| %SBS | Selective Broadcast Services (SBS) | Controls the operation of the local SBS Server (See Chapter 7 .) |
| %MRS | Message Recovery System (MRS) | Controls the operation of the local MRS Server (See Chapter 6 .) |
| %GNT | Group Name Table | Contains generic queue names and their addresses (See Chapter 8 .) |
| %NAM | Naming Agent | Contains the group numbers in which the Naming Agent will run. (See Chapter 8 .) |
A MessageQ group includes a number of server processes. Each server process is dedicated to a specific function or set of functions. The main overseer of each MessageQ message queuing group is the communications server (COM Server). During startup, the COM Server process starts up subsidiary servers depending upon the contents of the Profile section.