BEA MessageQ
Installation and Configuration Guide for OpenVMS

Contents (summary)

• Part 1
• Chapter 1 Preparing for MessageQ Installation
• Chapter 2 Installing MessageQ
• Part 2 Configuring a MessageQ System
• Chapter 3 Defining the Message Queuing Environment
• Chapter 4 Configuring Cross-Group Connections
• Chapter 5 Configuring Message Queues and Global Memory
• Chapter 6 Configuring Message Recovery
• Chapter 7 Setting Up Selective Broadcasting
• Chapter 8 Creating Global Names
• Chapter 9 Configuring the MessageQ Client Library Server
• Part 3 Managing a MessageQ System
• Chapter 10 MessageQ Main Menu and Utilities
• Chapter 11 Using MessageQ System Management Utilities
• Chapter 12 Sizing and Tuning the MessageQ Environment
• Chapter 13 Troubleshooting in a MessageQ Environment
• Chapter 14 MessageQ Security
• Chapter 15 Managing Failover
• Part 4 APPENDIXES
• Appendix A Sample DMQ$INIT.TXT File
• Appendix B Sample DMQ$TYPCLS.TXT File
• Appendix C Parameter Tuning Guidelines
• Appendix D Directories and Logical Names
• Appendix E Error Log Messages
• Appendix F Files Installed on Your System
• Index
• Figures
• Examples
• Tables

Contents

• ---

  Part 1

• ---

  Chapter 1 Preparing for MessageQ Installation
  • 1.1 Overview
  • 1.2 MessageQ Basic Concepts and Terms
    • 1.2.1 Supported Network Protocols
    • 1.2.2 Message Queues
    • 1.2.3 MessageQ Server Processes
    • 1.2.4 Naming
    • 1.2.5 Global Memory
  • 1.3 Configuring Distributed Systems Using MessageQ
    • 1.3.1 Design Paradigms
      • 1.3.1.1 Traditional Functional Model
      • 1.3.1.2 Object-Oriented Methodology
    • 1.3.2 Determining Queue Sizes
    • 1.3.3 Simulating Worst-Case Load Scenario
    • 1.3.4 Failover Provisions
    • 1.3.5 Design Summary
  • 1.4 Getting Ready to Install MessageQ
    • 1.4.1 Checking the Software Distribution Kit
    • 1.4.2 Reading Release Notes
    • 1.4.3 Verifying Required Operating System Components
    • 1.4.4 Installing Optional Software for OpenVMS Systems
    • 1.4.5 Licensing
    • 1.4.6 Checking System Parameter Values
    • 1.4.7 Calculating Values for GBLPAGES and GBLSECTIONS
  • 1.5 Installation Procedure Requirements
    • 1.5.1 Installation Time
    • 1.5.2 Privileges
    • 1.5.3 Disk Space
    • 1.5.4 Process Account Quotas
    • 1.5.5 VMSINSTAL Requirements
    • 1.5.6 System Backup

• ---

  Chapter 2 Installing MessageQ
  • 2.1 Overview
  • 2.2 The Installation Procedure
    • 2.2.1 Invoking VMSINSTAL
    • 2.2.2 Confirming Backup
    • 2.2.3 Specify Where Distribution Media is Mounted
    • 2.2.4 Specify the Product to Install
    • 2.2.5 Enter VMSinstall Options
    • 2.2.6 Installing MessageQ for OpenVMS Online Documentation
    • 2.2.7 Selecting Kit Type
    • 2.2.8 Confirming License Registration
    • 2.2.9 Select Target Device for Installation
    • 2.2.10 Running IVP
    • 2.2.11 Purging Files
    • 2.2.12 Viewing Informational Messages
  • 2.3 Installation Error Messages
    • 2.3.1 Major Failure Messages
    • 2.3.2 Error Conditions
  • 2.4 PostInstallation Tasks for MessageQ
    • 2.4.1 Editing System Startup and Shutdown Files
    • 2.4.2 Configuring and Managing the System
    • 2.4.3 Determining and Reporting Problems
  • 2.5 Upgrading to MessageQ Version 4.0A
    • 2.5.1 Purpose of Upgrade
    • 2.5.2 Conversion Requirements
    • 2.5.3 Conversion Major Steps
    • 2.5.4 Executing the MessageQ Conversion Utility
    • 2.5.5 Using the Conversion Main Menu

• ---

  Part 2 Configuring a MessageQ System

• ---

  Chapter 3 Defining the Message Queuing Environment
  • 3.1 Overview
    • 3.1.1 MessageQ Manager Account Privileges
    • 3.1.2 Basic Configuration Steps
  • 3.2 Creating a Message Queuing Group
    • 3.2.1 The MessageQ Message Queuing Network
    • 3.2.2 Assigning Bus and Group IDs
    • 3.2.3 Creating Message Queuing Groups
    • 3.2.4 Default Directory Names
    • 3.2.5 Connecting to the MessageQ Logical Name Table
    • 3.2.6 Editing DMQ$INIT To Configure a Group
      • 3.2.6.1 Setting Servers and Configuring Groups In the Profile Section
      • 3.2.6.2 Profile Section Parameters
      • 3.2.6.3 Setting Network Connections In the Cross-Group Section
      • 3.2.6.4 Configuring Client Library Server in the CLS section
      • 3.2.6.5 Configuring Local Buffer Pools In the Buffer section.
      • 3.2.6.6 Defining Queues In the Queue Configuration Section
      • 3.2.6.7 Setting Broadcast System Parameters In the SBS section
      • 3.2.6.8 Setting Message Recovery System Parameters In the MRS Section
      • 3.2.6.9 Assigning the Groups in Which the Naming Agent will Run
  • 3.3 Starting and Stopping MessageQ Groups
    • 3.3.1 Using DMQ$STARTUP to Invoke MessageQ
    • 3.3.2 Starting Groups Under an Older Version of MessageQ
    • 3.3.3 Starting Application Programs in a Message Queuing Group
      • 3.3.3.1 Application Startup Process
      • 3.3.3.2 Two Methods for Connecting
      • 3.3.3.3 Detaching a Process with DCL Context
      • 3.3.3.4 Detaching a Process Without DCL Context
    • 3.3.4 Shutting Down a Running MessageQ Group
  • 3.4 Additional Configuration Tasks
    • 3.4.1 Configuring Event Logging
    • 3.4.2 Adding Queue Names to Network-Wide Namespace
    • 3.4.3 Changing Parameters in the Running Group
    • 3.4.4 Deleting Groups
    • 3.4.5 Defining Message Type and Class Codes
    • 3.4.6 MessageQ Hints and Tips
      • 3.4.6.1 Modifying Your Default Editor
      • 3.4.6.2 Defining MessageQ Symbols
      • 3.4.6.3 Startup Synchronization
      • 3.4.6.4 Redirecting Configuration and Log Files

• ---

  Chapter 4 Configuring Cross-Group Connections
  • 4.1 Overview
    • 4.1.1 Connecting to Other Message Queuing Groups
  • 4.2 Configuring the Cross-Group Connection Table
    • 4.2.1 Cross-Group Connection Table Overview
    • 4.2.2 Loading the Configuration Data
    • 4.2.3 Using Cross-Group Connection Table Fields
    • 4.2.4 Table Entry Guidelines
  • 4.3 Using Message Routing
    • 4.3.1 Routing Tables
    • 4.3.2 Configuring and Loading the Tables
    • 4.3.3 DMQ$INIT Routing Section
  • 4.4 Selecting the TCP/IP Link Driver to Startup
  • 4.5 Sharing Group Configuration Files
  • 4.6 Suppressing DECnet Intrusion Alarms from MessageQ Connect Attempts
  • 4.7 Configuring DMQ$GMT_OFFSET for Network Communications

• ---

  Chapter 5 Configuring Message Queues and Global Memory
  • 5.1 Overview
  • 5.2 Configuring Message Queues
    • 5.2.1 Queue Configuration Table Parameters
    • 5.2.2 Queue Configuration Table Guidelines
  • 5.3 Configuring Global Memory
    • 5.3.1 How MessageQ Uses Global Memory
    • 5.3.2 Using the Buffer Pool Configuration Table

• ---

  Chapter 6 Configuring Message Recovery
  • 6.1 Overview
  • 6.2 How Message Recovery Services Works
    • 6.2.1 Using Recoverable Journal Files
    • 6.2.2 Using Auxiliary Journal Files
      • 6.2.2.1 Using the Dead Letter Journal
      • 6.2.2.2 Using the Post Confirmation Journal
      • 6.2.2.3 Retrieving Journaled Messages
  • 6.3 Starting MRS and JRN Servers
  • 6.4 Configuring MRS and JRN Servers
    • 6.4.1 Setting Parameters for MRS and JRN
    • 6.4.2 How MessageQ Manages Destination Queue Files (DQFs)
    • 6.4.3 Specifying the Location of MRS Files
  • 6.5 Sizing MRS File Space
    • 6.5.1 Sizing the Amount of Recovery File Space
    • 6.5.2 Sizing the Journal File Chunk Size
    • 6.5.3 Sizing MRS Server In-Memory Data Structures at Startup
    • 6.5.4 Shortening MRS Server Startup Time in Large-Scale Applications
  • 6.6 MRS Internal Operation Tracing at Startup
  • 6.7 Confirming Message Removal from the Recovery System
    • 6.7.1 Using CONFIRM_STYLE Attribute for Confirmation
    • 6.7.2 Controlling Recovery System Response with DMQ$BLOCKING_CONFIRM
    • 6.7.3 Using RCVR_ONLY_CONFIRM Parameter

• ---

  Chapter 7 Setting Up Selective Broadcasting
  • 7.1 Overview
  • 7.2 Starting the SBS Server
  • 7.3 Configuring Broadcasting
    • 7.3.1 Specifying Multipoint Outbound Target Addresses
    • 7.3.2 Configuring Optimized Ethernet Mode
    • 7.3.3 Broadcasting Requirements and Restrictions

• ---

  Chapter 8 Creating Global Names
  • 8.1 Configuring MessageQ Global Naming
    • 8.1.1 Configure Groups to Run or Use the Naming Agent
    • 8.1.2 Configure a Lightweight Namespace
    • 8.1.3 Configure a Default Namespace Path for Each Group
    • 8.1.4 Define the Queue Names in the Group Initialization File
    • 8.1.5 Using DNS with Global Naming
    • 8.1.6 Using the Naming Agent Manager Utility to Manage the Global Namespace
    • 8.1.7 Using the Manager Utility to View the Group's Cache
  • 8.2 Defining Type and Class Codes

• ---

  Chapter 9 Configuring the MessageQ Client Library Server
  • 9.1 Overview
  • 9.2 MessageQ Client Library Server Overview
  • 9.3 Client Library Server Installation and Transport Support
  • 9.4 Configuring the CLS section of DMQ$INIT.TXT File
    • 9.4.1 CLS Endpoints
    • 9.4.2 Setting Maximum Number of Clients for CLS
    • 9.4.3 Configuring One Client for Each CLS Server Option
    • 9.4.4 Restricting Remote Access to CLS
  • 9.5 Special Queue Configuration Issues
    • 9.5.1 Attach Errors to Undefined Queues
  • 9.6 Starting and Stopping CLS Manually
    • 9.6.1 Starting CLS from the Manager Utility
    • 9.6.2 Starting CLS from DCL
    • 9.6.3 Stopping CLS from the Manager Utility
  • 9.7 CLS Event Logging and Tracing

• ---

  Part 3 Managing a MessageQ System

• ---

  Chapter 10 MessageQ Main Menu and Utilities
  • 10.1 Overview
  • 10.2 Using the MessageQ Main Menu
  • 10.3 Running the IVP
  • 10.4 Starting and Shutting Down the COM Server
  • 10.5 Verifying Buffer Pool Configuration (DMQ$LLS_VERIFY)
  • 10.6 Testing MessageQ Communications with DMQ$LOOP
    • 10.6.1 Running DMQ$LOOP
  • 10.7 Testing MessageQ Services with DMQ$TEST
  • 10.8 Running the CUSTOMIZE Command Procedure
    • 10.8.1 Customization Options
    • 10.8.2 About the DMQ$BOOT Command Procedure
    • 10.8.3 About the DMQ$INIT.TXT File
    • 10.8.4 About the DMQ$TYPCLS.TXT File
  • 10.9 Running the DMQ$LOADER Utility
    • 10.9.1 Starting the LOADER Utility
    • 10.9.2 Restrictions on DMQ$LOADER
  • 10.10 Changing Bus and Group Numbers
  • 10.11 Shutting Down MessageQ

• ---

  Chapter 11 Using MessageQ System Management Utilities
  • 11.1 Overview
  • 11.2 Major System Management Tasks
  • 11.3 Using the Monitor Utility (DMQ$MONITOR)
    • 11.3.1 Displaying Queue Counters
    • 11.3.2 Displaying Queue Quotas
    • 11.3.3 Displaying COM Server Status
    • 11.3.4 Displaying Queue-Specific Status
    • 11.3.5 Resetting COM Server Counters
    • 11.3.6 Displaying the Routing Table
    • 11.3.7 Shutting Down COM Server Process
    • 11.3.8 Displaying Link Summary Information
    • 11.3.9 Displaying Link Detail Information
    • 11.3.10 Displaying Link Connect Table
    • 11.3.11 Displaying Group Detail Information
    • 11.3.12 Resetting Cross-Group Connections
    • 11.3.13 Displaying Remote Groups
  • 11.4 Using the System Management Utility (DMQ$MGR_UTILITY)
    • 11.4.1 Displaying Queue Summary Information
    • 11.4.2 Displaying Queue Detail Information
    • 11.4.3 Flushing Queues
    • 11.4.4 Stopping Queues
    • 11.4.5 Starting Queues
    • 11.4.6 Forcing a Process to Exit
    • 11.4.7 Redirecting Status and Trace Output
      • 11.4.7.1 Enabling Tracing Prior to Starting a Program
      • 11.4.7.2 Enabling Tracing When a Program is Running
    • 11.4.8 Event Logging
      • 11.4.8.1 Directing Error and Status Messages Prior to Starting a Program
      • 11.4.8.2 Redirecting Error and Status Logging When a Program is Running
    • 11.4.9 Using Event Log Control
      • 11.4.9.1 Storing Event Data
      • 11.4.9.2 Switching Event Log Files
    • 11.4.10 Displaying Group Name Table
    • 11.4.11 Journal Controls
      • 11.4.11.1 Managing DQF and SAF Journals
      • 11.4.11.2 Managing DLJ and PCJ Journals

• ---

  Chapter 12 Sizing and Tuning the MessageQ Environment
  • 12.1 Overview
  • 12.2 Sizing and Tuning Processes
    • 12.2.1 Virtual Memory
    • 12.2.2 Global Memory
    • 12.2.3 I/O Channels
    • 12.2.4 Files
    • 12.2.5 Network Resources
    • 12.2.6 Other System Resources and Quotas
    • 12.2.7 Modifying DMQ$SET_SERVER_QUOTAS.COM
  • 12.3 Allocating Virtual Memory for MessageQ Servers
    • 12.3.1 Modeling Virtual Memory Needs
    • 12.3.2 Performing Testing
    • 12.3.3 A Memory Usage Model for Each MessageQ Server
    • 12.3.4 Example Memory Allocation Model for the MRS Server
  • 12.4 Global Memory
  • 12.5 Tuning TCP/IP for MessageQ
    • 12.5.1 Approximating the Nonpaged Pool Needs
    • 12.5.2 Computing the Number of TCP/IP Sockets

• ---

  Chapter 13 Troubleshooting in a MessageQ Environment
  • 13.1 Overview
  • 13.2 MessageQ Error Logging
    • 13.2.1 MessageQ Output
      • 13.2.1.1 MessageQ Stream Output
      • 13.2.1.2 Stream Destinations
      • 13.2.1.3 Stream Switches
      • 13.2.1.4 The Event Logger
      • 13.2.1.5 Console Output
    • 13.2.2 MessageQ Servers
      • 13.2.2.1 MessageQ Server Output Files
      • 13.2.2.2 MessageQ Server Logging/Debugging
  • 13.3 Tools for Troubleshooting MessageQ Problems
    • 13.3.1 Server Log Messages
    • 13.3.2 API Return Status Values
    • 13.3.3 Utility Programs
      • 13.3.3.1 DMQ$TEST
      • 13.3.3.2 DMQ$LOOP
      • 13.3.3.3 DMQ$LLS_VERIFY
      • 13.3.3.4 DMQ$MONITOR
      • 13.3.3.5 DMQ$MGR_UTILITY
  • 13.4 Troubleshooting Procedures
    • 13.4.1 Basic Troubleshooting Tasks
      • 13.4.1.1 Diagnosing Application Errors
      • 13.4.1.2 Enabling Server Tracing
    • 13.4.2 Verifying MessageQ Group Startup
    • 13.4.3 Troubleshooting MessageQ Startup Problems
    • 13.4.4 Troubleshooting Problems with Running Groups and Queues
    • 13.4.5 MessageQ Connectivity Troubleshooting
    • 13.4.6 MessageQ Recovery Troubleshooting
    • 13.4.7 MessageQ Application Troubleshooting

• ---

  Chapter 14 MessageQ Security
  • 14.1 Overview
  • 14.2 Rights Identifiers Used By MessageQ
  • 14.3 Defining Access Control on Queues
    • 14.3.1 Securing Readout of Permanent Queues
    • 14.3.2 Securing the Creation of Temporary Queues
  • 14.4 Setting the Global Section Protection Mask
    • 14.4.1 Defining Protection Mask Logical Name
    • 14.4.2 Setting ACLs for Global Sections
  • 14.5 Controlling Network Access to Queuing Group

• ---

  Chapter 15 Managing Failover
  • 15.1 Overview
    • 15.1.1 Group Failover
    • 15.1.2 Recoverable Queue Failover
    • 15.1.3 Managing and Planning for Failover
  • 15.2 Cold Failover
  • 15.3 Hot Failover to a Running Shadow Group
    • 15.3.1 Automatic Synchronized Cluster Failover
      • 15.3.1.1 Implementing Automatic Synchronized Failover
    • 15.3.2 Non-Automatic Hot Failover
      • 15.3.2.1 Implementing Non-Automatic Hot Failover
      • 15.3.2.2 Detecting a Failure While the Failing Group Is Still Running
    • 15.3.3 Programming Considerations
  • 15.4 Failover of Recoverable Messaging to and from a Single Target
    • 15.4.1 Redirecting Recoverable Data Streams
    • 15.4.2 Merging Recoverable Data Streams
    • 15.4.3 Supporting Failover of SAF Files

• ---

  Part 4 APPENDIXES

• ---

  Appendix A Sample DMQ$INIT.TXT File

• ---

  Appendix B Sample DMQ$TYPCLS.TXT File

• ---

  Appendix C Parameter Tuning Guidelines

• ---

  Appendix D Directories and Logical Names
  • D.1 Directories
  • D.2 Logical Names

• ---

  Appendix E Error Log Messages
  • E.1 COM Server and Link Driver Error Log Messages
    • E.1.1 Additional Information on Link Drivers Error Status Reporting
  • E.2 MRS Server Error Log Messages
  • E.3 SBS Error Log Messages

• ---

  Appendix F Files Installed on Your System
  • F.1 AXP Development Base Kit Files
  • F.2 Alpha Run-Time Only Kit Files
  • F.3 VAX Development Base Kit Files
  • F.4 VAX Run-Time Only Kit Files

• ---

  Index

• ---

  Examples
  • 3-1 Invoking DMQ$CREATE_GROUP
  • 3-2 Sample Profile Parameters
  • 3-3 Cross-Group Connection Table
  • 3-4 Client Library Server Configuration Table
  • 3-5 Buffer Pool Configuration Table
  • 3-6 Queue Configuration Table
  • 3-7 SBS Server Initialization Section
  • 3-8 MRS Server Initialization Section
  • 3-9 Naming Agent Initialization Section
  • 3-10 Accessing the Group Logical Name Table
  • 4-1 Cross-Group Connection Table
  • 4-2 Maximum Entries in Cross-Group Connection Table
  • 4-3 Sample Routing Table
  • 4-4 Sharing Configuration Files
  • 5-1 Queue Configuration Table Section
  • 5-2 Buffer Pool Configuration Table Section
  • 6-1 Example Journal History
  • 6-2 DMQ$INIT.TXT Profile Section Enable Parameters
  • 6-3 MRS and JRN Server Initialization Section
  • 7-1 SBS Enable Parameter
  • 7-2 %SBS Initialization File Section
  • 7-3 Ethernet Broadcasting Parameters in%QCT Initialization File Section
  • 8-1 Sample%NAM Section
  • 8-2 Sample Group Name Table for Global Naming
  • 8-3 DMQ$MGR_UTILITY Display Group Name Table
  • 8-4 DMQ$TYPCLS.TXT
  • 9-1 Sample Client Library Server Configuration Table
  • 9-2 Sample Client Queues for Queue Configuration Table
  • 9-3 Manager Utility Remote Client Management Menu
  • 9-4 Starting CLS from Remote Client Management Menu
  • 9-5 Stopping CLS from Remote Client Management Menu
  • 9-6 Stopping CLS from Force Process Menu
  • 11-1 Default MRS section in DMQ$USER:DMQ$SET_SERVER_LOGICALS.COM
  • 12-1 COM Server Quotas
  • 13-1 COM Server Logical Name Settings
  • 15-1 Sample Cross-Group Connection Table
  • A-1 Sample|hotspot#916|DMQ$INIT.TXT File
  • B-1 Sample|hotspot#921|DMQ$TYPCLS.TXT File

• ---

  Figures
  • 1-1 Components of a MessageQ Message Queuing Group
  • 2-1 MessageQ Version 4.0 Conversion Utility
  • 4-1 Sample System Routing Configuration
  • 15-1 Cold Failover For Non-Clustered Environment
  • 15-2 Cold Failover For Clustered Environment
  • 15-3 Normal File Sharing for a Running Group
  • 15-4 Hot Failover for a Running Group
  • 15-5 DQF or SAF Redirecting for Failover
  • 15-6 Data Stream Merging for Failover

• ---

  Tables
  • 1-1 Minimum Required System Parameter Values
  • 2-1 Installation Steps
  • 3-1 Sections of the DMQ$INIT.TXT File
  • 3-2 Profile Parameters
  • 3-3 Modifiable Parameters in the Group Initialization File
  • 4-1 Cross-Group Connection Table Fields
  • 4-2 GMT Offset
  • 5-1 Queue Configuration Table Fields
  • 5-2 Message Control Sections
  • 5-3 Buffer Pool Global Sections
  • 5-4 Buffer Pool Configuration Table Fields
  • 6-1 MRS/JRN Initialization Fields
  • 6-2 Determining Journal File Size
  • 7-1 %SBS MOT Address Ranges
  • 7-2 %SBS Section Parameters
  • 7-3 %QCT Section Parameters for Ethernet Broadcasting
  • 8-1 Sample Global Names and Their Resolution
  • 8-2 DMQ$TYPCLS.TXT Statements
  • 10-1 |hotspot#588|Main Menu Options
  • 11-1 DMQ$MONITOR System Management Tasks
  • 11-2 DMQ$MGR_UTILITY System Management Tasks
  • 12-1 COM Server
  • 12-2 Link Drivers
  • 12-3 MRS Server
  • 12-4 Journal Server
  • 12-5 SBS Server
  • 12-6 Memory Allocation Model for MRS Server
  • 14-1 Sample Settings for DMQ$SET_GBLSEC_PROT
  • 14-2 |hotspot#885|Global Section Names
  • C-1 Parameter Tuning Guidelines
  • D-1 MessageQ Directories
  • D-2 MessageQ Logical Names
  • F-1 Standard Alpha Development Base Kit Files
  • F-2 Optional Alpha Development Base Kit Files
  • F-3 Standard Alpha Run-Time Only Kit Files
  • F-4 Optional Alpha Run-Time Only Kit Files
  • F-5 Standard VAX Development Base Kit Files
  • F-6 Optional VAX Development Base Kit Files
  • F-7 Standard VAX Run-Time Only Kit Files
  • F-8 Optional VAX Run-Time Only Kit Files