CONTENTS Title Page Copyright Page Preface Part I Installing DECmessageQ Software 1 Preparing for DECmessageQ Installation Overview Introduction In This Chapter DECmessageQ Basic Concepts and Terms Overview Supported Protocols Additional Terms User Processes DECmessageQ Server Processes Symbolic Names Global Memory Configuring Distributed Systems Using DECmessageQ Design Paradigms Traditional Functional Model Object-Oriented Methodology Determining Queue Sizes Simulating Worst-Case Load Scenario Failover Provisions Design Summary Getting Ready to Install DECmessageQ In This Section Checking Media Contents Reading Release Notes Verifying Required Operating System Components Installing Optional Software for OpenVMS Systems License Inclusion with Product Kit Licensing Requirements Registering the License Loading the License for a VMScluster System Parameters and Memory Allocation Requirements Checking System Parameter Values Calculating Values for GBLPAGES and GBLSECTIONS Installation Procedure Requirements In This Section Installation Time Privileges Disk Space Process Account Quotas VMSINSTAL Requirements System Backup Considerations for OpenVMS Systems Upgrade Concurrent Versions 2 Installing DECmessageQ Overview Introduction In This Chapter The Installation Procedure In This Section Simplified VMSINSTAL Log Invoking VMSINSTAL Confirming Backup Selecting Release Notes Option Selecting Kit Type Confirming License Registration Installing DECmessageQ Kits Installing OpenVMS Help Files Specifying a Device Selecting Run-Time Libraries on VAX Systems Running IVP Purging Files Viewing Informational Messages Installation Error Messages In This Section Major Failure Messages Error Conditions Additional Information Post-Installation Tasks for DECmessageQ Editing System Startup and Shutdown Files Configuring and Managing the System Determining and Reporting Problems Upgrading to DECmessageQ Version 3.0 In This Section Purpose of Upgrade Conversion Requirements Conversion Major Steps Executing DMQ$CVT_V2TO3 Utility Using the Conversion Main Menu Converting One Bus or Group Performing Manual Conversion Part II Configuring a DECmessageQ System 3 Defining the Message Queuing Environment Overview Introduction In This Chapter DECmessageQ Manager Account Privileges Basic Configuration Steps Creating a Message Queuing Group In This Section The DECmessageQ Message Queuing Network Assigning Bus and Group IDs Creating Message Queuing Groups Default Directory Names Connecting to the DECmessageQ Logical Name Table Editing DMQ$INIT To Configure a Group Setting Servers and Configuring Groups In the Profile Section Profile Section Parameters Setting Network Connections In the Cross-Group Section Configuring Client Lib Server in the CLS section Configuring Local Buffer Pools In the Buffer section. Defining Queues In the Queue Configuration Section Setting Broadcast System Parameters In the SBS section Setting Message Recovery System Parameters In the MRS Section Starting and Stopping DECmessageQ Groups In This Section Using DMQ$STARTUP to Invoke DECmessageQ Starting Groups Under an Older Version of DECmessageQ Starting Application Programs in a Message Queuing Group Application Startup Process Two Methods for Connecting Detaching a Process with DCL Context Detaching a Process Without DCL Context Copying a LNM Table Shutting Down a Running DECmessageQ Group Additional Configuration Tasks In This Section Configuring Event Logging Adding Queue Names to Network-Wide Namespace Changing Parameters in the Running Group Deleting Groups Defining Message Type and Class Codes DECmessageQ Hints and Tips Modifying Your Default Editor Defining DECmessageQ Symbols Startup Synchronization Redirecting Configuration and Log Files 4 Configuring Cross-Group Connections Overview Introduction In This Chapter Connecting to Other Message Queuing Groups Configuring the Cross-Group Connection Table In This Section Cross-Group Connection Table Overview Loading the Configuration Data Using Cross-Group Connection Table Fields Table Entry Guidelines Using Message Routing In This Section Routing Tables Configuring and Loading the Tables DMQ$INIT Routing Section Selecting the TCP/IP Link Driver to Startup Sharing Group Configuration Files Suppressing DECnet Intrusion Alarms from DECmessageQ Connect Attempts Configuring DMQ$GMT_OFFSET for Network Communications 5 Configuring Message Queues and Global Memory Overview Configuring Message Queues Queue Configuration Table Parameters Queue Configuration Table Guidelines Configuring Global Memory How DECmessageQ Uses Global Memory Using the Buffer Pool Configuration Table 6 Configuring Message Recovery Overview In this chapter How Message Recovery Services Works Using Recoverable Journal Files Using Auxiliary Journal Files Using the Dead Letter Journal Using the Post Confirmation Journal Starting MRS and JRN Servers Configuring MRS and JRN Servers Setting Parameters for MRS and JRN How DECmessageQ Manages Destination Queue Files Specifying the Location of MRS Files Sizing MRS Memory Space Sizing the Amount of Recovery File Space Sizing MRS Server In-Memory Data Structures at Startup Shortening MRS Server Startup Time in Large-Scale Applications MRS Internal Operation Tracing at Startup Confirming Message Removal from the Recovery System Using CONFIRM_STYLE Attribute for Confirmation Controlling Recovery System Response with DMQ$BLOCKING_CONFIRM Using RCVR_ONLY_CONFIRM Parameter 7 Setting Up Selective Broadcasting In This Chapter Starting the SBS Server Configuring Broadcasting Specifying Multipoint Outbound Target Addresses Multipoint Outbound Target Parameters Configuring Optimized Ethernet Mode Optimizing Ethernet Parameters Broadcasting Requirements and Restrictions 8 Assigning Symbolic Names Static Assignment of Symbolic Names Locating Symbolic Queue Names Configuring the Group Name Table Group Name Table Entries Restrictions on Use of Global Symbolic Queue Names How to Use Aliases Defining Type and Class Codes Dynamic Assignment of Symbolic Names Required Setup for DNS How to Maintain DNS Namespace Setting Confidence Levels Setting the DMQ$DNSROOT Logical Name Creating and Deleting DNS Names with DMQ$DNSLOAD Multiple Instances of Symbolic Queue Names 9 Configuring the DECmessageQ Client Lib Server In this chapter DECmessageQ Client Lib Server Overview Client Lib Server Installation and Transport Support Configuring the CLS section of DMQ$INIT.TXT File CLS Endpoints Setting Maximum Number of Clients for CLS Configuring One Client for Each CLS Server Option Special Queue Configuration Issues Attach Errors to Undefined Queues Starting and Stopping CLS Manually Starting CLS Stopping CLS CLS Event Logging and Tracing Part III Managing a DECmessageQ System 10 DECmessageQ Main Menu and Utilities Overview Introduction In This Chapter Using the DECmessageQ Main Menu Running the IVP Starting and Shutting Down the COM Server Verifying Buffer Pool Configuration (DMQ$LLS_VERIFY) Testing DECmessageQ Communications with DMQ$LOOP Purpose Running DMQ$LOOP Testing DECmessageQ Services with DMQ$TEST Running the CUSTOMIZE Command Procedure Restrictions on DMQ$LOADER Changing Bus and Group Numbers Shutting Down DECmessageQ Overview 11 Using DECmessageQ System Management Utilities Overview Major System Management Tasks Using the Monitor Utility (DMQ$MONITOR) Displaying Queue Counters Displaying Queue Quotas Displaying COM Server Status Displaying Queue-Specific Status Resetting COM Server Counters Displaying the Routing Table Shutting Down COM Server Process Displaying Link Summary Information Displaying Link Detail Information Displaying Link Connect Table Displaying Group Detail Information Resetting Cross-Group Connections Displaying Remote Groups Using the System Management Utility (DMQ$MGR_UTILITY) Displaying Queue Summary Information Displaying Queue Detail Information Flushing Queues Forcing a Process to Exit Redirecting Status and Trace Output Enabling Tracing Prior to Starting a Program Enabling Tracing When a Program is Running Event Logging Directing Error and Status Messages Prior to Starting a Program Redirecting Error and Status Logging When a Program is Running Using Event Log Control Storing Event Data Switching Event Log Files Displaying Group Name Table Journal Controls Managing DQF and SAF Journals Managing DLJ and PCJ Journals 12 Sizing and Tuning the DECmessageQ Environment Overview of the Sizing and Tuning Process Virtual Memory Global Memory I/O Channels Files Network Resources Other System Resources and Quotas Modifying DMQ$SET_SERVER_QUOTAS.COM Allocating Virtual Memory for DECmessageQ Servers Modeling Virtual Memory Needs Performing Testing A Memory Usage Model for Each DECmessageQ Server Example Memory Allocation Model for the MRS Server Global Memory Tuning TCP/IP for DECmessageQ Approximating the Nonpaged Pool Needs Computing the Number of TCP/IP Sockets 13 Troubleshooting in a DECmessageQ Environment Overview DECmessageQ Error Logging DECmessageQ Output DECmessageQ Stream Output Stream Destinations Stream Switches The Event Logger Console Output DECmessageQ Servers DECmessageQ Server Output Files DECmessageQ Server Logging/Debugging Tools for Troubleshooting DECmessageQ Problems Server Log Messages API Return Status Values Utility Programs DMQ$TEST DMQ$LOOP DMQ$LLS_VERIFY DMQ$MONITOR DMQ$MGR_UTILITY Troubleshooting Procedures Basic Troubleshooting Tasks Diagnosing Application Errors Enabling Server Tracing Verifying DECmessageQ Group Startup Troubleshooting DECmessageQ Startup Problems Troubleshooting Problems with Running Groups and Queues DECmessageQ Connectivity Troubleshooting DECmessageQ Recovery Troubleshooting DECmessageQ Application Troubleshooting 14 DECmessageQ Security Defining Access Control on Queues Securing Readout of Permanent Queues Securing the Creation of Temporary Queues Setting the Global Section Protection Mask Defining Protection Mask Logical Name Setting ACLs for Global Sections Controlling Network Access to Queuing Group 15 Managing Failover Failover Overview Group Failover Recoverable Queue Failover Managing and Planning for Failover ``Cold'' Failover ``Hot'' Failover to a Running ``Shadow'' Group Overview Implementing ``Hot'' Failover Detecting a Failure While the Failing Group Is Still Running Programming Considerations Failover of Recoverable Messaging to and from a Single Target Redirecting Recoverable Data Streams Merging Recoverable Data Streams Supporting Failover of SAF Files Part IV APPENDIXES A Sample Installation for OpenVMS VAX Full Development Kit for VAX Systems Running IVP B Sample Installation for OpenVMS Alpha Full Development Kit Installation Verification Procedure C Sample DMQ$INIT.TXT File D Sample DMQ$TYPCLS.TXT File E Parameter Tuning Guidelines F Directories and Logical Names Directories Logical Names G Error Log Messages COM Server and Link Driver Error Log Messages MRS Error Log Messages SBS Error Log Messages H Files Installed on Your System AXP Development Base Kit Files Alpha Run-Time Only Kit Files VAX Development Base Kit Files VAX Run-Time Only Kit Files EXAMPLES 1-1 Running the VMSLICENSE Utility 3-1 Invoking DMQ$CREATE_GROUP 3-2 Sample Profile Parameters 3-3 Cross-Group Connection Table 3-4 Client Lib 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 Accessing the Group Logical Name Table 3-10 Sample Output of DMQ$COPY_LNM_TABLE 3-11 Running DMQ$DNSLOAD 4-1 Cross-Group Connection Table 4-2 Sample Routing Table 4-3 Sharing Configuration Files 5-1 Queue Configuration Table Section 5-2 Buffer Pool Configuration Table Section 6-1 DMQ$INIT.TXT Profile Section Enable Parameters 6-2 MRS and JRN Server Initialization Section 7-1 SBS Enable Parameter 7-2 Multipoint Outbound Target Settings 7-3 Setting Ethernet Broadcasting Parameters 7-4 Setting Ethernet Broadcasting Parameters in QCT section 8-1 Group Name Table Section 8-2 DMQ$TYPCLS.TXT 8-3 Running DMQ$DNSLOAD 8-4 Changing DNS Names 8-5 Multiple Symbolic Queue Names 9-1 Sample Client Lib Server Configuration Table 9-2 Sample Client Queues for Queue Configuration Table 12-1 COM Server Quotas 13-1 COM Server Logical Name Settings 15-1 Sample Cross-Group Connection Table A-1 Sample Full Development Kit Installation for OpenvVMS VAX Systems B-1 Sample Full Development Kit Installation for OpenVMS Alpha Systems C-1 Sample DECmessageQ DMQ$INIT.TXT File D-1 Sample DECmessageQ DMQ$TYPCLS.TXT File FIGURES 1-1 DECmessageQ Multiplatform Support 1-2 Components of a DECmessageQ Message Queuing Group 7-1 DmQ Mode of Broadcasting 7-2 Ethernet LAN Mode of Broadcasting 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 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 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 Description of Multipoint Outbound Target Settings 7-2 Ethernet Optimization Fields 8-1 Group Name Table Fields 8-2 DMQ$TYPCLS.TXT Statements 8-3 DMQ$DNSLOAD Commands 10-1 DECmessageQ Main Menu Options 11-1 DMQ$MONITOR System Management Tasks 11-2 DMQ$MGR_UTILITY System Management Tasks 14-1 Sample Settings for DMQ$SET_GBLSEC_PROT 14-2 DECmessageQ Global Section Names E-1 Parameter Tuning Guidelines F-1 DECmessageQ Directories F-2 DECmessageQ Logical Names H-1 Standard Alpha Development Base Kit Files H-2 Optional Alpha Development Base Kit Files H-3 Standard Alpha Run-Time Only Kit Files H-4 Optional Alpha Run-Time Only Kit Files H-5 Standard VAX Development Base Kit Files H-6 Optional VAX Development Base Kit Files H-7 Standard VAX Run-Time Only Kit Files H-8 Optional VAX Run-Time Only Kit Files