BEA Logo BEA MessageQ Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy


   MessageQ Doc Home   |   Installation Guide for OpenVMS   |   Previous Topic   |   Next Topic   |   Contents   

Installing BEA MessageQ


This chapter provides a detailed description of the BEA MessageQ installation procedure and related topics.

The following topics are covered in this chapter:

The Installation Procedure

BEA MessageQ for OpenVMS is installed by invoking the VMSINSTAL utility. This command procedure will prompt you for various installation options. When it is complete, the BEA MessageQ for OpenVMS application is installed on your system. Then you can perform system configuration as described in Part II of this manual.

Note: To end the installation procedure at any time, press Ctrl + Y. When you press Ctrl + Y, the installation procedure deletes all files it has created up to that point and exits. You can then restart the installation.

This section describes the installation procedure, as summarized in Table 2-1

Table 2-1 Installation Steps




Shut Down Running BEA MessageQ Groups




Confirming Backup


Specifying Where Distribution Media is Mounted


Specifying the Product to Install


Entering VMSINSTAL Options


Selecting Kit Type


Selecting Target Device for Installation


Purging Files


Viewing Informational Messages

Shut Down Running BEA MessageQ Groups

If you are installing over an existing BEA MessageQ installation, ensure that no BEA MessageQ groups are running on the target machine, and that run-time libraries and images are deinstalled. Shut down running groups by issuing the following command, where bbbb is the bus ID, ggggg is the group ID, and Y inidicates that run-time libraries and images for the group are to be deinstalled:



To invoke VMSINSTAL, use the following command:


To start the installation, invoke the VMSINSTAL command procedure from a privileged account, such as the SYSTEM account. VMSINSTAL is in the SYS$UPDATE directory. VMSINSTAL issues a warning notifying you of any active processes on the system and prompts you for a confirmation before proceeding.

Confirming Backup

The procedure requests that you confirm system backup:

* Are you satisfied with the backup of your system disk [YES]?

We recommend that you always back up your system disk before performing an installation.

If you are satisfied with the backup of your system disk, press Return. Otherwise, enter NO to discontinue the installation. After you back up your system disk, you can restart the installation.

Note: BEA MessageQ software can be installed on any disk. Be sure to backup the disk on which BEA MessageQ is installed.

Specifying Where Distribution Media is Mounted

You are prompted to enter the location where the distribution CDROM is mounted. Insert the CDROM distribution media into the system's CDROM drive. Enter the file specification for the distribution media including the device name of the CDROM drive and the directory name from the software distribution medium as follows:

* Where will the distribution volumes be mounted: 

and press Return.

Specifying the Product to Install

The installation procedure then prompts for the name of the product that you want to install as follows:

Enter the products to be processed from the first distribution
volume set.

* Products: 

The following table shows the product kit names by platform.


Kit Name

Compaq Alpha systems


Compaq VAX systems


Entering VMSINSTAL Options

After you select the product to install, you can choose to enter one of the VMSINSTAL options. For example, option -N which enables users to view or print the release notes before the installation.

An alternate working device (AWD) may be specified as part of the VMSINSTAL procedure. This option may be used when the system disk does not have the device space needed to install BEA MessageQ for OpenVMS. However, even with the AWD option the installation requires at least 1,000 blocks of space on the system disk. The following sample shows VMSINSTAL being run with the AWD option:

@SYS$UPDATE:VMSINSTAL MQVAX050 source_device: OPTIONS AWD=device: 

Next, VMSINSTAL begins the installation, displaying the following information:

The following products will be processed:


Beginning installation of MQAXP V5.0 at 14:45

%VMSINSTAL-I-RESTORE, Restoring product save set A ...
%VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP

The release notes are copied to a file in the SYS$HELP directory as SYS$HELP:MQAXP050.RELEASE_NOTES or SYS$HELP:MQVAX050.RELEASE_NOTES.

Selecting Kit Type

Choose the kit to be installed: the Base Kit or the Client Library. The Base Kit includes the BEA MessageQ sever and client and an option to install the MessageQ / Tuxedo Bridge. The Client Library includes that portion of the Base Kit software which supports the BEA MessageQ Client for OpenVMS. If the Base Kit is selected, the procedure notifies you that client support is included in the Base Kit. The installation procedure displays the following options:

The MessageQ for OpenVMS Alpha installation is divided into two parts:
Part 1: Base kit installation
Part 2: Client Library installation
--- Part 1: Select Base Kit Support ---
* Install the Base kit (195000 blks) [NO]: y
* Install the MessageQ/Tuxedo Bridge (1000 blks) [NO]: n
--- Part 2: Select Client Library Kit Support ---

%MQAXP-I-CLSUPPORT, Client Library support is included with the Base kit

%MQAXP-I-BLKSREQ, Blocks required for installation is 195000
%MQAXP-I-DECTCP, DEC TCP/IP support will be built
Confirming License Registration

Selecting Target Device for Installation

Next, enter the name of the device on which you want to install BEA MessageQ software as follows:

* Device where MessageQ will reside [SYS$SYSDEVICE]: 

Press return to install BEA MessageQ on the default target device SYS$SYSDEVICE. Or, enter the name of the device on which you want to install BEA MessageQ and press Return.

Note: Installing BEA MessageQ software on rooted directories will produce unpredictable results. Specify a device name or a logical name of a device.

Purging Files

You have the option to purge files from previous versions of BEA MessageQ that are superseded by this installation.

* Do you want to purge files replaced by this installation [YES]? 

Purging is recommended; however, if you need to keep files from a previous installation of this version of BEA MessageQ software, enter NO in response to the question.

Viewing Informational Messages

The installation procedure now displays a number of informational messages that report on the progress of the installation. There are no further questions that require a user response.

If the installation procedure has been successful up to this point, VMSINSTAL moves the new or modified files to their target directories, updates help files, and updates DCL tables, if necessary. If you chose to have files purged, that work is done now.

When the installation completes successfully, the installation procedure displays the following information:

 The MessageQ for OpenVMS Alpha Installation has completed successfully.

Please refer to the "MessageQ for VMS Configuration Guide" for details
on how to setup and access MessageQ for OpenVMS.

The Installation Verification Procedure DMQ$IVP.COM has been
placed in $111$DKC300:[DMQ$V50.EXE].

A copy of the Release Notes MQAXP050.RELEASE_NOTES has been
placed in $111$DKC300:[DMQ$V50.DOC].

Please don't forget to fill out and send in your registration card. =====================================================================

%VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories...
Installation of MQAXP V5.0 completed at 15:06


Creating installation data file: VMI$ROOT:[SYSUPD]MQAXP050.VMI_DATA

These messages indicate that the entire installation procedure is complete.

Note: VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the system manager's account and you want to restore these symbols, log out and log in again.

Note: The BEA MessageQ message header format has been revised, requiring that journal files from release 4.0A or earlier be converted before they are used with BEA MessageQ release 5.0. See Upgrading to BEA MessageQ Version 5.0 for instructions on upgrading your BEA MessageQ for OpenVMS installation.

Warning: If you have been using a previous version of BEA MessageQ and wish to continue to use your user areas, you MUST perform the upgrade conversion before you can run your applications using BEA MessageQ for OpenVMS, Version 5.0. Refer to Upgrading to BEA MessageQ Version 5.0, for more information.

Installation Error Messages

The following topics are covered in this section:

Major Failure Messages

If errors occur during the installation, VMSINSTAL displays failure messages. If the installation fails, you see the following message:

%VMSINSTAL-E-INSFAIL, The installation of MessageQ Version 5.0
has failed.

Error Conditions

Any of the following error conditions may cause the installation to fail:

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 Preparing for BEA MessageQ Installation.

PostInstallation Tasks for BEA MessageQ

This section describes the tasks to be performed after installing BEA MessageQ:

Editing System Startup and Shutdown Files

After BEA MessageQ is installed and properly configured, you can add automatic startup and shutdown command procedures to the SYSTARTUP and SYSHUTDOWN command procedures. Placing the BEA MessageQ startup commands in SYSTARTUP automatically starts BEA MessageQ when the OpenVMS system boots. Placing the BEA MessageQ shutdown commands in SYSHUTDOWN causes a clean BEA MessageQ shutdown on a OpenVMS system shutdown.

Configuring and Managing the System

See the BEA MessageQ Configuration Guide for OpenVMS for information on the following tasks:

Determining and Reporting Problems

If you encounter a problem while using BEA MessageQ, report it to technical support using the contact information provided in the preface of this manual.

Upgrading to BEA MessageQ Version 5.0

The following topics are covered in this section:

Purpose of Upgrade

To continue to use your BEA MessageQ groups created with previous versions of BEA MessageQ, you must perform the upgrade conversion before you can run your applications using BEA MessageQ for OpenVMS, Version 5.0.

After you have successfully installed BEA MessageQ for OpenVMS, Version 5.0, use the BEA MessageQ conversion utility (DMQ$CVT.COM) to upgrade the group initialization file for a BEA MessageQ Version message queuing group created with a previous version to the new BEA MessageQ for OpenVMS Version 5.0 format. You can also build new BEA MessageQ groups from the beginning by running the BEA MessageQ management utilities as described in the BEA MessageQ Configuration Guide for OpenVMS.

Conversion Requirements

The conversion utility has the following requirements:

Conversion Major Steps

The Conversion utility performs the following functions with some user input:

Conversion Utility Considerations

Running the conversion utility affects some aspects of the BEA MessageQ configuration in the following areas:

Some reserved queues are removed when the conversion program is run. These reserved queues are removed for reasons related to the loader and the naming agent. For example, older DMQ$INIT.TXT files on VMS can include multiple alias names for the COM server, which could be loaded inconsistently, therefore resulting in incorrect name resolution. In addition, these queues (without alias) are included in the DMQ$INIT.TXT template file shipped with BEA MessageQ V5.0.

When the conversion utility is run, the definition for queues 93-96, 98-100, 150, 152, 153, 155, and 156 is removed, as well as the definition for MOT queues in the range 4000-6000. The MOT queue names are relocated to the Group Name Table (GNT).

The conversion utility limits node names in the cross group (%XGROUP) section to a maximum of 20 characters. Node names longer than 20 characters are truncated during the conversion.

The conversion utility expects the Message Recovery System (MRS) files to be located in the default directory. The location of the MRS files may have been changed during configuration. The following logical names are defined if the standard DMQ$MRS logical has been redefined to an alternate location:

Executing the BEA MessageQ Conversion Utility

To execute the conversion utility, enter at the DCL prompt:


This command invokes the BEA MessageQ Conversion Utility and allows you to access the utility's menus.

Using the Conversion Main Menu

After you invoke the utility, the system displays the Conversion main menu as shown in Listing 2-1.

Listing 2-1 BEA MessageQ Version 4.0 Conversion Utility


Welcome to the BEA MessageQ V5 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:


Table 2-2 describes the conversion utility main menu options:

Table 2-2 Conversion Utility Menu Options


Use it to...


Provide online help information about the utility.


Locate the groups on the desired disk. Run the setup first, before starting any conversions.

This option asks you questions to determine what disk drive holds the BEA MessageQ Version 2, Version 3, and Version 4 directories. The specified disk is then searched for BEA MessageQ groups. A list of the groups is created and placed in a configuration file. This configuration file is used throughout the conversion to track the process. The configuration file is named DMQ$CVT_V5_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:

  • NONE-Nothing has been done.

  • FILE-The new files have been created with DMQ$CREATE_GROUP.

  • INIT-The DMQ$INIT.TXT file has been converted.

  • SYMB-The DMQ$TYPCLS.TXT file has been converted.

  • MAKE-The include files and text libraries have been created.

  • RMSG-Recoverable messages in the DQF and SAF files have been converted.

  • DONE-Group conversion is completed.


Convert all groups to the new format. This menu option begins the automatic conversion of all BEA MessageQ groups that were located in the SETUP. The conversion continues until all groups reach the DONE status, indicating completion.


This menu option allows the user to pick a specific BEA 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.


Select each phase of the conversion for every group allowing you to walk through each phase of the conversion. The phases of a manual conversion are as follows:

  • PICK-Select a BUS/GROUP from the configuration file created in the SETUP phase.

  • FILE-Execute the DMQ$CREATE_GROUP procedure to create the directory tree and populate the DMQ$USER files.

  • INIT-Convert the DMQ$INIT.TXT file. All user-supplied information in the file is preserved. It is highly recommended to review this file before restarting the group.

  • SYMB-Convert the DMQ$TYPCLS.TXT file.

  • RMSG-Read any recoverable messages remaining in the SAF and/or DQF files and transfer these messages to the new MRS format.

For more detailed information about each option, you can select Help from each of the conversion utility menus.