Open_M________________________________________ DSM for OpenVMS Installation and Management Guide Part Number: IS-DSM5B-VM Revision Date: January 1998 Software Version: DSM for OpenVMS VAX Version 7.0 DSM for OpenVMS Alpha Version 7.0 InterSystems Corporation Cambridge, Massachusetts __________________________________________________________ First Printing, June 1986 Revised, September 1987 Revised, November 1988 Revised, April 1989 Revised, November 1989 Revised, October 1993 Revised, January 1998 This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive, Cambridge MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part, without the express prior written consent of InterSystems Corporation. The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation. InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in such standard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of such software programs is limited in the manner set forth in such standard software license agreement(s). THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST. InterSystems Corporation disclaims responsibility for errors which may appear in this document and it reserves the right, in its sole discretion and without notice, to make substitutions and modifications in the products and practices described in this document. Caché, InterSystems, Caché SQL, Visual M, Caché ObjectScript, Caché Objects, DCP, ISM, DTM, DT-MAX, DT-Windows, DSM, DSM-DDP, and DASL are trademarks of InterSystems Corporation. OpenVMS Alpha, OpenVMS VAX, DEC, Digital, and the Digital Logo are trademarks of Digital Equipment Corporation. Microsoft Windows and Visual Basic are registered trademarks of Microsoft Corporation. All other trademarks and registered trademarks are the property of their respective holders. © InterSystems Corporation 1998 All rights reserved. IS-DSM5B-VM This document was prepared using VAX DOCUMENT, Version 2.1. ________________________________________________________________ Contents Preface.................................................. xi 1 Installing DSM Required Operating System Components ................. 1-1 DSM Distribution Kit ................................. 1-1 Space and Time Requirements for Installing DSM ....... 1-2 Installation Overview ................................ 1-3 DSM Installation ..................................... 1-4 Backing Up Your System............................. 1-4 Determining SYSGEN Requirements for Installation... 1-5 Disabling the VBSS_ENABLE Parameter (OpenVMS VAX)............................................ 1-6 Memory Resources for Granularity Hint Regions (OpenVMS Alpha)................................. 1-6 Installing DSM with VMSINSTAL...................... 1-7 DSM Shareable Images ................................. 1-11 Installing DSM as Shared Images.................... 1-12 Installing DSM Images as Resident (OpenVMS Alpha Only).............................................. 1-13 Overview........................................ 1-13 Configuring for Resident Images................. 1-14 Replacing DSM Images Already Installed as Resident........................................ 1-15 Installing DSM in a VMScluster Environment......... 1-15 Changes to Cluster Installation Licensing....... 1-16 Postinstallation Activities .......................... 1-17 Creating the DSM Environment Manager's Account..... 1-17 Running DSM$INIT.COM............................... 1-19 Configuring DSM.................................... 1-28 iii Establishing Your License.......................... 1-31 Entering a License.............................. 1-32 Specifying a License Server Address............. 1-35 Editing the Startup and Shutdown Command Procedures......................................... 1-36 The DSM Initialization Command Procedures....... 1-36 DSM$INSTALL.COM .............................. 1-36 DSM$INSTALL_SITE.COM ......................... 1-37 The OpenVMS System Startup Command Procedure.... 1-37 The DSM Shutdown Command Procedure.............. 1-38 Installing DSM in a VMScluster Environment......... 1-38 DSMCRASH.LOG Log File for Image Exits ................ 1-39 2 Managing DSM for OpenVMS Systems DSM Environment ...................................... 2-1 Environment Directories, Files, and Protection..... 2-2 DSM Baseline Mode.................................. 2-5 DSM Configurations................................. 2-6 DSM Accounts....................................... 2-7 Overview of DSM Databases ............................ 2-8 Configuration Management (^CONMAN) .................. 2-11 Starting Up and Shutting Down Configurations....... 2-33 Starting a Configuration........................ 2-33 Shutting Down a Configuration................... 2-36 Affects of Abnormal Image Termination.............. 2-37 Modifying Characteristics of a Configuration....... 2-38 Running Multiple DSM Configurations................ 2-39 Environmental Identifiers and Names............. 2-39 DSM$ID and DSM$DEFAULT.......................... 2-40 Selecting the Environment To Access............. 2-40 Setting a Default Environment................... 2-41 Initializing DSM in a VMScluster Environment ......... 2-42 Directory Structure in a VMScluster Environment.... 2-43 Defining VMScluster Configurations................. 2-45 Mastering a Cluster-Mounted Database Set........ 2-45 Enabling DDP in a VMScluster Environment........ 2-45 Checking System Volume Set Mounting across a Cluster............................................ 2-46 Running DSM in a Heterogeneous VMScluster Environment........................................ 2-46 ^DSMMGR......................................... 2-46 SYSUAF.DAT and RIGHTSLIST.DAT................... 2-47 iv DSM Detached Processes ............................... 2-48 Write Demon........................................ 2-49 Garbage Collector.................................. 2-49 Journal Process.................................... 2-50 Recovery Process................................... 2-50 DDP Servers........................................ 2-50 3 Controlling Access to DSM Controlling User Access .............................. 3-1 OpenVMS Access Control ............................... 3-4 Environment Access Control ........................... 3-5 Protecting Environment Files....................... 3-5 Maintaining Environment Security................... 3-7 Configuration Access Control ......................... 3-8 DSM Configuration Access Control System............ 3-8 Manager Mode Access............................. 3-9 Programmer Mode Access.......................... 3-11 Application Mode Access......................... 3-12 Programmer Mode and Application Mode Restrictions....................................... 3-12 Global Access Control ................................ 3-14 Establishing OpenVMS Accounts for Programmers and Application Users.................................... 3-15 Configuration Access Control Utilities ............... 3-17 Granting Access Interactively (^ACL).............. 3-17 Granting Access Noninteractively (^ACLCALL)....... 3-21 Creating Dedicated Application Accounts .............. 3-22 Setting Up a Captive Account....................... 3-23 Creating a Captive Command Procedure............... 3-24 Setting Up DSM Tied Routine and Port Tables........ 3-25 Controlling Access to the Callable Routines Interface............................................ 3-27 Using the Login Control Utility (^LOGIN) ............ 3-29 v 4 Using the DSM Security Audit Facility Overview of the DSM Security Audit Facility .......... 4-1 Security Audit Events ................................ 4-2 Object Class Names................................. 4-2 Message Event Codes................................ 4-3 DSM_LOGIN: Programmer Login..................... 4-3 DSM_LOGOUT: Programmer Logout................... 4-4 DSM_GLOBAL_SET: Global Sets .................... 4-5 DSM_GLOBAL_KILL: Global Kills................... 4-6 DSM_ROUTINE_SAVE: Modifications to Application Routines........................................ 4-7 DSM_GPROTECTION: Modifications to Global Protection...................................... 4-8 DSM_GJOURNAL: Modifications to Global Journaling...................................... 4-9 DSM_GCOLLATION: Modifications to Global Collation/Encoding.............................. 4-10 Enabling Security Auditing for a Configuration ....... 4-11 Running ^CONFIG to Enable DSM Support for Security Auditing........................................... 4-11 Making Sure OpenVMS is Enabled for Security Auditing........................................... 4-13 Analyzing the Security Audit Log File ................ 4-13 Selecting DSM Security Event Messages ................ 4-14 Example 1:......................................... 4-15 Example 2:......................................... 4-15 Example 3:......................................... 4-15 Example 4:......................................... 4-15 Example 5:......................................... 4-15 5 Tuning the OpenVMS Operating System for Use with DSM Overview ............................................. 5-1 Process Quotas for DSM Users ......................... 5-1 SYSGEN Parameters for DSM Configurations ............. 5-4 Using the ^MEMORY Utility.......................... 5-7 Modifying OpenVMS System Parameters................ 5-13 Page and Swap File Size............................ 5-15 Configuring DSM Shared Memory ........................ 5-15 Configuring Nonpaged Memory .......................... 5-17 vi 6 Optimizing DSM Optimizing DSM Applications .......................... 6-1 Using Mapped Routines ................................ 6-2 Mapped Routine Utilities (^RMAP).................. 6-3 Determining Mapped Routine Section Memory Requirements....................................... 6-4 Creating and Mapping Routine Sets.................. 6-6 Executing Mapped Routines.......................... 6-11 Disabling Individual Mapped Routines............... 6-13 Considerations When Using Mapped Routines.......... 6-14 Using the Global Statistics Utility (^GLSSTA) ....... 6-15 Performance Statistics (^PMF) ....................... 6-21 ^PMF and ^RTH...................................... 6-21 Using PMF to Monitor Performance................... 6-22 Including ^PMF Support in ^CONFIG.................. 6-22 Using the ^PMF Utility Set......................... 6-23 PMF Utility Conventions......................... 6-25 Accessing the PMF Utility Set...................... 6-26 Using the Collector Control Utilities (^PMFCOL).... 6-26 Starting Data Collector Processes (START^PMFCOL).................................. 6-27 Determining the Status of Data Collector Processes (STATUS^PMFCOL)....................... 6-27 Stopping Data Collector Processes (STOP^PMFCOL)................................... 6-28 Using the Data Collection Utilities (^PMFDAT)...... 6-29 Canceling In-Progress Data Collections (CANCEL^PMFDAT)................................. 6-29 Listing Completed Collections (LIST^PMFDAT)..... 6-30 Listing Scheduled Collections (QUEUED^PMFDAT)... 6-30 Purging Completed Collections (PURGE^PMFDAT).... 6-31 Purging Scheduled Collections (DQUEUE^PMFDAT)... 6-32 Scheduling a New Collection (^PMFMON)........... 6-33 Using the Reporting Utilities (^PMFREP)............ 6-34 Creating Reports (PMFGEN)....................... 6-34 Deleting Reports (DELETE^PMFREP)................ 6-36 Listing Reports (LIST^PMFREP)................... 6-36 Printing Reports (PRINT^PFMREP)................. 6-37 PMF Reports .......................................... 6-38 vii PMF Report Types................................... 6-38 Summary Reports................................. 6-39 Full Reports.................................... 6-39 Full Reports with Global Summaries.............. 6-40 Data Categories.................................... 6-40 Configuration Information....................... 6-40 Mounted Volume Set Information.................. 6-41 Cluster-Wide Statistics Summary................. 6-41 Cluster-Wide Derivative Ratios ............... 6-46 Cluster-Wide Volume Set Statistics Summary ... 6-47 Other Summary Histograms ..................... 6-47 Optimizing DSM Based on PMF Statistics............. 6-48 7 DSM System Utilities Overview of DSM Utilities ............................ 7-1 Library Utilities.................................. 7-1 System Utilities................................... 7-1 Utility Access..................................... 7-2 Utility Conventions................................ 7-2 Running the DSM System Utilities ..................... 7-4 Configuration Management Utilities (^CONMAN) ........ 7-4 Deleting Configurations (DELETE^CONFIG)........... 7-5 Displaying Configurations (DISPLAY^CONFIG)........ 7-6 Copying Configurations (COPY^CONFIG).............. 7-7 Modifying Configurations (MODIFY^CONFIG).......... 7-8 Database Set Management Utilities (^DBSMAN) ......... 7-9 After-Image Journaling Utilities (^JOURNAL)....... 7-10 Before-Image Journaling Utilities.................. 7-11 Database Set Utilities............................. 7-12 Volume Set Utilities (^VOLUTL).................... 7-12 Disk Block Tally (^DBT) ........................ 7-13 Distributed Data Processing Utilities (^DDP) ........ 7-14 Mapped Routine Utilities (^RMAP) .................... 7-15 Option File Management Utilities (^OPTMAN) .......... 7-16 Performance Utilities ................................ 7-16 System Management Utilities (^SYSMAN) ............... 7-17 Force Exit (^FORCEX).............................. 7-19 Cluster Lock Table Display and Lock Table Display (CLUSTER^LOCKTAB and ^LOCKTAB).................... 7-19 Login Control (^LOGIN)............................ 7-20 Shutdown (^SHUTDWN)............................... 7-20 viii 8 Using DSM as a Visual M Remote Application Server Overview of Visual M and DSM ......................... 8-1 Visual M Structure................................. 8-1 Visual M Client-Server Communications.............. 8-2 Configuring Visual M Server Support .................. 8-3 Installing TCP/IP.................................. 8-3 Installing the DSM Software........................ 8-3 Loading the Visual M Server Routines............... 8-4 Using ^CONFIG to Enable Support for Visual M....... 8-5 Defining UCIs and Volumes as Namespaces............ 8-7 Creating the Mapping on the Server.............. 8-7 Creating the Mapping on the Client.............. 8-7 Defining DSM Configurations as Remote Servers...... 8-7 Starting and Stopping the Visual M Server Process............................................ 8-8 Mapping Visual M Namespaces to DSM UCI and Volume Sets............................................... 8-8 Customizing the Visual M Application Server .......... 8-9 Creating Visual M Security ........................... 8-10 Visual M Information Sources ......................... 8-10 9 Installing Caché Weblink Introduction to Caché/Weblink ........................ 9-1 Installing Caché Weblink on DSM ...................... 9-2 10 Installing Graphic Library Utilities Overview of the Graphic Library Utilities ............ 10-1 Installing the Graphic Library Utilities ............. 10-1 Installing Visual M and GUI Routines in SYS$Library........................................ 10-2 Define UCIs and Volumes as Namespaces.............. 10-3 Creating the Mapping on the Server.............. 10-3 Creating the Mapping on the Client.............. 10-4 Defining DSM Configurations as Remote Servers...... 10-4 Using the Graphic Library Utilities .................. 10-4 ix A Installing DSM Software in an Alternate Root Using DSM from an Alternate System Root .............. A-1 Installing DSM in an Alternate Root .................. A-4 Running the DSM$ALTROOT_INSTALL.COM Procedure...... A-6 Installing DSM in an Alternate Root in a VMScluster Environment........................................ A-12 Shutting Down DSM Configurations That Use Alternate Root Software...................................... A-13 B Using the Configuration Option File Utility (^OPTMAN) Using the Configuration Option File .................. B-1 Invoking the Configuration Option File Utilities (^OPTMAN)........................................... B-3 Creating a Template Option File (^OPTBLD)......... B-3 Editing the Template Configuration Option File..... B-5 Converting the Edited Configuration Option File (^OPTCON)......................................... B-5 Starting Up a Configuration .......................... B-6 Configuration Option File Keywords ................... B-7 Definition Keywords................................ B-8 Data Keywords...................................... B-14 Minimum Entries in a Configuration Option File ....... B-40 Sample Configuration Option File ..................... B-40 C Using the ^RTH Performance Statistics Utility Overview of ^RTH ..................................... C-1 Using the Performance Statistics Utility ............. C-2 Database Event Counts and Derivative Ratios Histogram....................................... C-5 Individual Routine CPU Time as a Percentage of Total Routine CPU Time Histogram................ C-9 Individual Routine Loads as Percentage of Total Histogram....................................... C-9 Global References Per Second Histogram.......... C-9 Distributed Data Processing Activity Histogram.. C-10 x D Sample Listings for DSM Installation and IVP VMSINSTAL and IVP Procedure (Console Output)....... D-1 Index Examples 1-1 Running the DSM$INIT Command Procedure ....... 1-19 1-2 Running DSM$CONFIGURE.COM .................... 1-29 2-1 Running the ^CONFIG Utility .................. 2-12 6-1 Using ^CONFIG to Include Support for Mapped Routines...................................... 6-9 6-2 ^GLSSTA Report ............................... 6-16 6-3 ^GLSSTA Report (Synchronization Statistics) .. 6-18 B-1 Minimum Entries in Configuration Option File.......................................... B-40 B-2 Sample Configuration Option File ............. B-41 D-1 VMSINSTAL Console Output ..................... D-1 Tables 1-1 Space Requirements (in Blocks) for Installing DSM on VAX Systems............................ 1-2 1-2 Space Requirements (in Blocks) for Installing DSM on Alpha Systems.......................... 1-3 3-1 Bit Representation for Masks ................. 3-13 3-2 OpenVMS System Privileges Needed by DSM Programmers................................... 3-16 6-1 Routine Mapping Utilities .................... 6-3 A-1 Alternate Root Image Names ................... A-8 B-1 Definition Keywords .......................... B-8 B-2 Data Keywords ................................ B-15 xi ________________________________________________________________ Preface Intended Audience This manual is for DSM environment managers and operators who are responsible for installing the DSM for OpenVMS software, establishing DSM user accounts, and performing other privileged system operations. Document Purpose This manual describes how to install the DSM software and how to operate and manage DSM in a multi-iuser environment. It contains information for the following platforms: o DSM for OpenVMS VAX o DSM for OpenVMS Alpha This manual does not describe the language elements or syntax of the DSM language. See the DSM Language Reference Manual for a complete description of the DSM language elements and the Introduction to DSM for a description of the DSM language syntax. See the DSM for OpenVMS Programmer's Guide for information about programming with DSM. This manual also does not describe how to manage a DSM database. See the DSM for OpenVMS Database Operations Guide for information about: o Managing volume sets and globals o Maintaining the integrity of your database o Using journaling o Running DSM in a VMScluster[TM] environment xi o Using transaction processing Document Structure The DSM for OpenVMS Installation and Management Guide begins with installation and management information, followed by conceptual and detailed information that helps the system manager understand how DSM functions. This manual is structured as follows: o Chapter 1 describes how to install a new DSM system. o Chapter 2 contains tips for managing a DSM system, including instructions for defining a DSM environment and for creating configurations. o Chapter 3 describes how to control access to DSM and how to create application and programmer accounts. o Chapter 4 describes how to use the DSM security facility to achieve C2 security compliance. o Chapter 5 explains how to tune the OpenVMS operating system for use with DSM. o Chapter 6 describes how to optimize your DSM system. o Chapter 7 contains information on system utilities that perform system management functions. o Chapter 8 explains how to use your DSM system as a Visual M server. o Chapter 9 explains how to use your DSM system as a remote database server for World Wide Web-enabled tools through, Open M/Weblink, the Universal Network Gateway for M. o Chapter 10 explains how to install graphic utility routines that let you run DSM Library Utilities from a Windows-based InterSystems client system. o Appendix A provides instructions on how to install DSM in an alternate root. o Appendix B describes how to use the Configuration Option File Utility (^OPTMAN) to define configura- tions. xii o Appendix C describes how to use the ^RTH Performance Statistics Utility. o Appendix D presents a console dialog of the instal- lation procedure with a list of the files that are installed. Associated Documents The associated documents can be divided into three groups: o DSM specific documentation o Operating system documentation o Other publications DSM Documentation This manual is part of the DSM documentation set. For a complete description of the DSM for OpenVMS documentation set, see the Introduction to DSM. Operating System Documentation This manual does not describe how to perform OpenVMS system management functions except as they directly relate to DSM. Before reading this document, you should be familiar with the OpenVMS operating system, and with the topics covered in the following publications of Digital Equipment Corporation: o OpenVMS User's Manual. o The Software Product Description o The OpenVMS Glossary o The OpenVMS Master Index In addition, The OpenVMS System Manager's Manual and OpenVMS System Management Utilities Reference Manual, also published by Digital Equipment Corporation, provide information for those who have the overall responsibility for controlling the operations of an OpenVMS installation. If you are responsible for installing the DSM system software and establishing DSM user accounts, you should be familiar with the information in those manuals before reading this document. xiii Other Publications This manual refers to the following documents from Digital Equipment Corporations's OpenVMS documentation set that contain supplemental information relevant to DSM programming and system operations: o Building Dependable Systems: The OpenVMS Approach o DECnet for OpenVMS Guide to Networking o DECnet for OpenVMS Networking Manual o DECnet for OpenVMS Network Management Utilities o Guide to OpenVMS AXP Performance Management o Guidelines for VMScluster Configurations o OpenVMS Guide to System Security o OpenVMS DCL Dictionary o OpenVMS System Management Utilities Reference Manuals (I and II) o TCP/IP Networking on OpenVMS Systems o VMScluster Systems for OpenVMS Typographical Conventions This manual uses the following typographical conventions and symbols. xiv __________________________________________________________ Convention____Meaning_____________________________________ bold text Emphasizes important information. Indicates user input for online documenta- tion. italic text Introduces new terms. Indicates the title of a manual. "Section" Indicates a section title. Ctrl/x Indicates that you press the Ctrl key on the terminal keyboard while you simultaneously press some other key (represented here by x). Indicates that you press the Return key on the terminal keyboard. Indicates that a space must separate components of a command or command line. Indicates that you press the Tab key. [item] Indicates that the enclosed item is optional. (Brackets are not optional in the syntax of a directory name in an OpenVMS file specification.) {item} Indicates that the enclosed item is optional. filespec Indicates an OpenVMS file specification. . . . Indicates that additional command parameters can be added to the command line. . Indicates a break between two illustrated . lines of user input and that all user input . is not shown. OpenVMS_______Indicates_the_OpenVMS_operating_system._____ xv Where to Get Assistance and Information For support questions about DSM, contact the InterSystems Worldwide Response Center: US: Europe: On Line: Tel: (617) 621- Tel: +44(0)1-753- Internet: 0700 830-077 support@intersys.com Fax: (617) 374- Fax: +44(0)1-753- 9391 861-311 World Wide Web: BBS general BBS: +44(0)1-753- www.intersys.com users: 853-534 FTP Site: (617) 225-0475 ftp.intersys.com BBS developers (617) 494-0867 If you have support provided by Digital Equipment Corporation, contact Digital Support at 1-800-354-9000 xvi 1 ________________________________________________________________ Installing DSM This chapter provides information about the DSM for OpenVMS Version 7.1 distribution kits and the software installation procedures that are used by sites that have never previously installed DSM. Read the information in this chapter before you do a new installation of DSM for OpenVMS. This chapter does not describe procedures used to upgrade previous versions of the product. If you are upgrading from previous versions, follow the instructions in Chapter 2 of the DSM for OpenVMS Release Notes. Required Operating System Components You can install DSM for OpenVMS VAX on systems running OpenVMS VAX Version 6.2 or higher. You can install DSM for OpenVMS Alpha on systems running OpenVMS Alpha Version 6.2 or higher. If you plan to use the M Windowing API (MWAPI) or the X Window System interface, you must install DECwindows Motif for OpenVMS VAX or OpenVMS Alpha before you install the DSM distribution kit. DSM Distribution Kit The DSM distribution kit consists of software and documentation. DSM is distributed only by InterSystems Corporation. InterSystems distributes DSM software on the following media for both DSM for OpenVMS VAX and DSM for OpenVMS Alpha: o 9-track magnetic tape o TLZ06[TM] Installing DSM 1-1 o TK50[TM] tape cartridge o CD-ROM The DSM software consists of the following: o DSM interpreter and database handler image o DSM Distributed Data Processing (DDP) driver o Command procedures for managing a DSM application environment o DSM library utility routines and globals o Components needed to build user-defined functions Space and Time Requirements for Installing DSM To install and use DSM, you must have enough space on your system disk. Table 1-1 lists the total disk space requirements for DSM for OpenVMS on VAX systems. Keep in mnd that these figures are only approximate. Actual disk space use depends on the requirements of your particular system environment. Table 1-1 Space Requirements (in Blocks) for Installing __________DSM_on_VAX_Systems______________________________ Peak Installation Net Options_________________________Use___________________Use_ DSM Alone 28000 24000 With DASL 50000 38500 With M WAPI and Windows 30500 25500 With DASL, M WAPI, and Windows 52500 39500 With_all_previous_options_______53000_________________35500 Table 1-2 lists the total disk space requirements for DSM for OpenVMS on Alpha systems. 1-2 Installing DSM Table 1-2 Space Requirements (in Blocks) for Installing __________DSM_on_Alpha_Systems____________________________ Peak Installation Net Options_________________________Use___________________Use_ DSM Alone 39500 26000 With DASL 61500 39500 With M WAPI and Windows 43000 27500 With DASL, M WAPI, and Windows 65000 40500 With_all_previous_options_______66000_________________41500 ________________________Note ________________________ Both tables give the total space required for Version 7.0 of DSM for OpenVMS. They do not list incremental space beyond the requirements for previous versions of DSM. Keep in mind that these tables do not include the added space required for the DSM Bookreader Library. The DSM Bookreader Library increases the minimum required space for DSM installation by 53000 OpenVMS blocks. _____________________________________________________ It takes approximately 15 minutes to install the DSM kit. Actual time will vary depending on your hardware configuration. Installation Overview This section provides an outline of how to install, initialize, and start up DSM for OpenVMS. The installation and startup procedure describes how to set up a new installation and assumes that there is no previous release of DSM installed on your system. The remainder of this chapter describes the following procedures in detail: o DSM software kit installation activities - Back up your system. - Install the DSM distribution kit on your system using the SYS$UPDATE:VMSINSTAL.COM procedure. Installing DSM 1-3 - If you do not run the IVP during VMSINSTAL, install the DSM images as shared images using the SYS$STARTUP:DSM$INSTALL.COM procedure. o Postinstallation activities - If required, specify a License Server and enter license information. - Use the SYS$MANAGER:DSM$INIT.COM procedure to create a DSM environment manager's account for use with DSM. - Log in to the DSM environment manager's account and run the SYS$MANAGER:DSM$CONFIGURE.COM procedure to initialize DSM database volume sets and configurations. - Edit the operating system files to provide for automatic startup and shutdown of DSM configurations when your system is rebooted. - You can optionally install the ViewPoint performance monitor to track and analyze system and application performance statistics. See Chapter 1 of the DSM for OpemVMS Release Notes Version 7.1 for more information. DSM Installation This section provides detailed instructions for installing the DSM software kit on your OpenVMS system. Backing Up Your System InterSystems recommends that you do a system disk backup before installing any software on the operating system. Use the backup procedures that have been established at your site. For details on performing a system disk backup, see the OpenVMS System Management Utilities Reference Manual, published by Digital Equipment Corporation. 1-4 Installing DSM Determining SYSGEN Requirements for Installation During installation, the DSM installation procedure checks system resources to ensure that sufficient free GBLPAGES and GBLSECTIONS exist to install the DSM images as shared image files. If system resources are not sufficient, the installation procedure ends and notifies you. To install DSM successfully, you must have the following system resources available: o On DSM for OpenVMS VAX systems: - At least 750 global page table entries (GBLPAGES) - At least 23 global section descriptors (GBLSECTIONS) - At value of at least 50 for the TQElm quota for your environment manager account (for successful operation of the secondary DCP database servers). o On DSM for OpenVMS Alpha systems: - At least 2140 global page table entries (GBLPAGES) - At least 23 global section descriptors (GBLSECTIONS) - At value of at least 50 for the TQElm quota for your environment manager account (for successful operation of the secondary DCP database servers). You can use the F$GETSYI lexical function to display the number of free global pages and free global sections on your system. Enter the following DCL command line: $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLPAGES") 8858 $ WRITE SYS$OUTPUT F$GETSYI("FREE_GBLSECTS") 68 If the installation procedure fails because these SYSGEN values are too low, you have to modify the system parameters, reboot your system, and restart the installation procedure. Installing DSM 1-5 When adjusting system parameters, add at least the required amount of GBLPAGES or GBLSECTIONS to the current value of GBLPAGES and GBLSECTIONS. To do this, add the minimum values required by DSM to the current values in SYS$SYSTEM:MODPARAMS.DAT. For example, adjust the current values from the previous example in MODPARAMS.DAT using the following commands on an OpenVMS system: ADD_GBLPAGES = 750 ADD_GBLSECTIONS = 23 Next you need to run the SYS$UPDATE:AUTOGEN.COM procedure to update the SYSGEN parameters. Then reboot your system as follows: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT AUTOGEN makes the necessary SYSGEN changes and reboots your system. When the system reboots, you can rerun the software kit installation described in the next section. When you create new DSM configurations, you may also need additional GBLPAGES and GBLSECTIONS. See Chapter 5 for more information about how to determine appropriate values for these and other SYSGEN parameters. Disabling the VBSS_ENABLE Parameter (OpenVMS VAX) Because DSM for OpenVMS VAX uses PFN mapping and locks process pages and working set pages into memory, DSM processes are ineligible for VBSS selection. Therefore, you must disable the parameter VBSS_ENABLE on your system. The correct relationship between MAXPROCESSCNT and BALSETCNT is: BALSETCNT = MAXPROCESSCNT-2 Memory Resources for Granularity Hint Regions (OpenVMS Alpha) If you are installing DSM for OpenVMS Alpha on OpenVMS Alpha Version 6.2 or later and wish the DSM images to be installed as resident, you must also ensure that you have reserved sufficient memory resources in the OpenVMS granularity hint regions. See the section "Installing DSM Images as Resident (OpenVMS Alpha Only)" for complete information. 1-6 Installing DSM Installing DSM with VMSINSTAL Use the VMSINSTAL installation procedure to install DSM. This sample installation procedure uses device GANDY$DKA0. Enter the appropriate device mnemonic for your distribu- tion medium at the prompt, and follow the procedures for mounting your distribution medium. 1. Mount the distribution medium. 2. Log in to your system manager's account and enter the following command line: $@SYS$UPDATE:VMSINSTAL OpenVMS Software Product Installation Procedure Vn.n It is 16-Oct-1997 at 9:22. Enter a question mark (?) at any time for help. In the previous example: xxx VAX if you are installing on an OpenVMS VAX system AXP if you are installing on an OpenVMS Alpha system 3. VMSINSTAL then asks the following question: * Are you satisfied with the backup of your system disk [YES]? If you are satisfied, press Return to accept the default answer of YES. If you need to back up your system, get out of VMSINSTAL by entering N, back up your system, and then restart the installation procedure. 4. VMSINSTAL then asks: * Where will the distribution volumes be mounted: GANDY$DKA0:[DSMMGR] Enter the full specification of where you are going to mount the distribution kit. 5. VMSINSTAL then asks: Enter the products to be processed from the first distribution volume set. * Products: DSMVAX070 *Enter installation options you wish to use (none): Installing DSM 1-7 Enter the name of the kit, either DSMVAX070 for DSM for OpenVMS VAX or DSMAXP070 for DSM for OpenVMS Alpha. Choose the default for installation options (none). 6. VMSINSTAL displays the following: %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. 7. VMSINSTAL then asks: * Do you want to run the IVP after the installation [YES]? The DSM kit includes an Installation Verification Procedure (IVP) called SYS$TEST:DSM$IVP.COM. VMSINSTAL can optionally run the IVP to verify that DSM has been installed correctly. Press Return to run the IVP (Installation Verification Procedure) after installation. Enter N if you do not want to run the IVP after installation. You can run the IVP manually after running VMSINSTAL by entering @SYS$TEST:DSM$IVP at the DCL prompt. 8. VMSINSTAL asks if you want to include support for the M Windowing API and the X Window System Interface for DSM: * Include support for the M Windowing API and the X Window Interface [YES]? NO The default response is YES. Press Return to include support. Enter N if you do not want to include support. 9. VMSINSTAL asks if you want to install the DSM Application Software Library (DASL) files: * Include DASL files [YES]? The default response is YES. Press Return to include the DASL files. Enter N if you do not want to include the DASL files. ________________________Note ________________________ For more information about installing and setting up DASL, see the DASL Management Guide. _____________________________________________________ 1-8 Installing DSM 10.VMSINSTAL then displays the following question: * Do you want to purge files replaced by this installation [YES]? The default response to this question is YES. Press Return to accept the default and purge all previous DSM files that VMSINSTAL replaces with the new DSM files. If you allow old DSM files to remain on DISK, you are wasting valuable disk space. 11.VMSINSTAL then displays the following informational message: No further questions will be asked during this installation 12.VMSINSTAL then begins the installation and displays informational messages on your terminal during each phase of this part of the installation procedure. Beginning installation of DSMVAX V7.0 at 09:17 Begin installation of DSM base components ----------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set B ... Linking the DSM base images . . . Installing DSM 1-9 The following files will be created or updated . . . Begin installation of X Windows and M Windowing API components -------------------------------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set C ... . . . Begin installation of DASL components ------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set D ... . . . %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installing DSM$SHARE and DSM$SHRLIB images as shareable Calling DSM Installation Verification Procedure Installation Verification Procedure for DSM Copyright (c) Digital Equipment Corporation, 1997 DSM x.x for OpenVMS VAX DSMMGR [Baseline] DSM x.x for OpenVMS VAX IVP Successful %DSM-I-HALT, HALT command executed DSM installation is complete. You may enter the following command line to initialize a manager account for use with DSM: @SYS$MANAGER:DSM$INIT Installation of DSMVAX x.x completed at 09:20 1-10 Installing DSM 13.If the installation fails for any reason, VMSINSTAL displays an appropriate informational message. For information about installation failure messages, see the OpenVMS System Messages: Companion Guide for Help Message Users, published by Digital Equipment Corporation. Take any action required by the message. 14.The VMSINSTAL menu appears and asks if you have another kit to install. Press Ctrl/Z to exit. The DSM software kit installation procedure is now complete. During the installation process the file, DSM0xx.RELEASE_NOTES, is moved to the SYS$HELP directory. (Where xx is the version number of your DSM software.) DSM0xx.RELEASE_NOTES is identical to this document. You can display it on your terminal or monitor screen or print it on a printer. The DSM software installation kit also includes a save set containing a Bookreader vesion of the DSM manuals. During system installation, this save set is copied to the [SYS$LIB] directory (SYS$LIBRARY. However, it is not automatically unpacked and you can delete the save set it is in, LIBRARY.SAV, if you have no need for Bookreader documentation and want to save space. See the DSM for OpenVMS Release Notes for more information about how to set up and use the Bookreader library. DSM Shareable Images DSM is implemented as one main image and several shareable images. Shareable images allow multiple programs to call the same image. This organization reduces memory use and increases system performance. Figure 1-1 illustrates the relationship of the various images included with DSM. o DSM.EXE DSM.EXE is the main entry routine for all programmer and application users of DSM. It accepts the DSM command line qualifier and then calls the DSM$SHARE.EXE image to process the qualifier and initiate access to DSM. o DSM$SHARE.EXE Installing DSM 1-11 DSM$SHARE.EXE is the shareable, position-independent image that supplies the entry points for the callable interface. Most of the code that supports DSM capabilities resides within this image. External programs that interface to DSM link against this image. The DSM.EXE image is an example of an external program that calls DSM through the callable interface located in DSM$SHARE.EXE. o DSM$MESSAGE.EXE DSM$MESSAGE.EXE holds the DSM error message text. DSM includes the message text as a separate image so that external callable interface programs can have access to DSM error messages. o DSM$MT_EBCASC.EXE DSM$MT_EBCASC.EXE holds the DSM ASCII/EBCDIC conversion tables that the DSM magnetic tape handler uses for reading and writing IBM[R] formatted magnetic tapes. You can create a customized ASCII/EBCDIC conversion table to meet your site requirements. o DSM$ECALL.EXE DSM$ECALL.EXE is the external call package table image. This image describes the existence of all user-written external call packages. o DSM$SHRLIB.EXE DSM$SHRLIB.EXE is a library of calls that are used internally only by DSM. Installing DSM as Shared Images To run DSM, you must install the supplied DSM images as shared images. Image installation does the following: o Reduces memory utilization o Reduces DSM image activation time o Conserves system resources If you ran the IVP during kit installation, the images are installed as shared when the IVP executes. If you did not run the IVP, you must use the OpenVMS Install Utility to install all the DSM images as shared images. 1-12 Installing DSM Use the SYS$STARTUP:DSM$INSTALL.COM procedure to install the DSM images as shared images by taking the following steps: 1. Log in to a OpenVMS privileged account that has the CMKRNL privilege. 2. Run the DSM$INSTALL command procedure by entering the following command: $ @SYS$STARTUP:DSM$INSTALL Installing DSM Images as Resident (OpenVMS Alpha Only) When running under OpenVMS Alpha Version 6.2 or later, DSM for OpenVMS supports the installation of the SYS$SHARE:DSM$SHARE.EXE and SYS$SHARE:DSM$SHRLIB.EXE images as resident. Installation of the DSM images as resident can result in: o Reduction in memory usage o Increased system throughput Overview The OpenVMS Alpha Install Utility lets you install images and associated address fixup vectors as resident. The Install Utility places resident images in OpenVMS system address space and resolves all image address linkage sections at install time. The image and address linkages are loaded into OpenVMS memory sections known as granularity hint regions. Using granularity hint regions has two benefits: o The number of shareable image pages is increased. This reduces total physical memory utilization system wide. o The hardware efficiency of virtual address resolution is enhanced. The SYS$STARTUP:DSM$INSTALL.COM procedure attempts to install DSM$SHARE.EXE and DSM$SHRLIB.EXE images and associated OpenVMS system library images as resident when the following conditions are met: o The operating system is OpenVMS Alpha Version 6.2 or later. Installing DSM 1-13 o DSM$INSTALL.COM is invoked with the parameter RESIDENT. o Versions of the DSM images are not already installed as shared or resident. (See the section "Replacing DSM Images Already Installed as Resident" if you have already installed the DSM images as shared or resident.) o The OpenVMS granularity hint regions have sufficient memory resources. (See the section "Configuring for Resident Images.") If any of these conditions are not met, DSM$INSTALL.COM installs the DSM images as shareable, but not resident. You can operate DSM, but you do not receive the benefits of resident image installation. Configuring for Resident Images You must take the following steps to configure your OpenVMS Alpha system for the installation of DSM images as resident: 1. Add the following lines to your SYS$SYSTEM:MODPARAMS.DAT file: ADD_GH_RSRVPGCNT = 180 ADD_IMGREG_PAGES = 1500 2. Run the SYS$UPDATE:AUTOGEN.COM procedure to incorporate the changes into your OpenVMS Alpha environment and reboot the system: $@SYS$UPDATE:AUTOGEN GETDATA REBOOT NOFEEDBACK 3. Run the DSM$INSTALL.COM procedure with the RESIDENT parameter to install the DSM images as resident: $@SYS$STARTUP:DSM$INSTALL RESIDENT The OpenVMS Install procedure will fail to install DSM or system images as resident if sufficient memory does not exist in the OpenVMS resident image code region. On some configurations, the value of 180 pages may be too low for the GH_RSRVPGCNT system parameter. Therefore, use the DCL command SHOW MEMORY/GH_REGION after rebooting and before you run DSM$INSTALL.COM to evaluate whether you have sufficient memory in the resident image code region. 1-14 Installing DSM You may also have to increase the value of IMGREG_PAGES to greater than the suggested value of 1500. Replacing DSM Images Already Installed as Resident The Install utility does not permit the replacement of images already installed as resident. To install a new copy of DSM$SHARE.EXE and DSM$SHRLIB.EXE when existing images are already installed as resident, you must first reboot your OpenVMS system. Installing DSM in a VMScluster Environment If you are installing DSM on a node in a VMScluster environment, you must log in to the system manager's account on each node that will be running DSM and do the following tasks. If you are upgrading to DSM 7.x from a pre-DSM 7.0 release, and plan to use a cluster environment, see "Changes to Cluster Installation Licensing" before running VMSINSTAL. 1. Enter the following DCL command to rename any previous copies of DSM$INSTALL.COM that exist in the system- specific root: $ RENAME SYS$SPECIFIC:[SYS$STARTUP]DSM$INSTALL.COM;* .OLD;* Create DSM$INSTALL_SITE.COM in the system-specific root. You can merge any site-specific information from previous versions of DSM$INSTALL_SITE.COM into DSM$INSTALL_SITE.COM. $ COPY SYS$COMMON:[SYS$STARTUP]DSM$INSTALL.OLD SYS$SPECIFIC:[SYS$STARTUP] 2. Install DSM shared images by entering the following: $ @SYS$STARTUP:DSM$INSTALL Installation of the DSM images using the DSM$INSTALL command procedure requires minimum SYSGEN parameter values for GBLPAGES and GBLSECTIONS. If you are unable to successfully run DSM$INSTALL on all VMScluster nodes, you have to modify these SYSGEN parameters on the affected node and reboot that node. For more information, see the section "Determining SYSGEN Requirements for Installation" in this chapter. Installing DSM 1-15 You can also use the OpenVMS System Management Utility (SYSMAN) to perform these steps from your local node by defining your management environment to be: o A particular node o A group of nodes o A cluster For more information, see the OpenVMS System Manager's Manual. Changes to Cluster Installation Licensing In versions of DSM earlier than 7.0, it was possible to install DSM on one node of a cluster and allow other nodes with the same architecture and system directories to use the installed software. It was not necessary to run the VMSINSTAL procedure on each node. In DSM V7.0 and V7.1, this process remains essentially unchanged. However, changes in DSM 7.x licensing require that each node of the cluster has a directory named DSM$LICENSE in the SYS$SPECIFIC file area. The creation and protection of this directory is usually performed by the software installation, but the install procedure only creates this directory for the node on which it is run. Before attempting to install the license key on a node where VMSINSTAL has not been run, you must first run the procedure SYS$MANAGER:DSM$CD_LICENSE.COM to ensure that the DSM$LICENSE directory is created and given the proper protection. This command procedure should be run from the system manager's account, but will set the directory protection such that any DSM manager's account can enter and edit the license key. DSM$CD_LICENSE.COM only needs to be used for the first upgrade or install of DSM V7.x. Once the directory has been created, subsequent upgrades will not require this step. 1-16 Installing DSM Postinstallation Activities After DSM installation is complete, you enter your license information and create one or more DSM environment manager accounts for use with DSM configurations. The configuration completely controls access to global databases, DSM routines, and other DSM capabilities. This section provides detailed instructions for all activities required to enter license information, create a DSM environment, and initialize a OpenVMS account as a DSM environment manager's account. Procedures for creating and starting a DSM configuration are also briefly described. See Chapter 2 for complete information about DSM configurations. For more information about creating volume sets, UCIs, and after-image and before-image journal files, see the DSM for OpenVMS Database Operations Guide. Creating the DSM Environment Manager's Account To define and manage a DSM environment for development and applications, you must designate an OpenVMS account as a DSM environment manager account. The account provides a working area for enabling various DSM options and operations. Using this account, the DSM manager can perform tasks such as the following: o Creating and extending DSM database volume sets o Creating and editing DSM configurations o Managing UCIs, globals, and routines on DSM volume sets o Starting up and shutting down DSM configurations interactively You use the SYS$MANAGER:DSM$INIT.COM command procedure to create a new DSM environment manager account. You can also use DSM$INIT to designate an existing OpenVMS account as a DSM environment. Take the following steps: 1. Log in to a privileged system account. 2. Run the DSM$INIT command procedure. Enter the following: $ @SYS$MANAGER:DSM$INIT Installing DSM 1-17 The DSM$INIT command procedure does the following: o Asks you for the account name, UIC, password, login device, and log file directory of the DSM environment manager account you want to create. o Creates default directories to hold volume sets and journal files (before-image and after-image journal files) associated with this environment. o Creates an account initialization DCL command procedure to do the following: - Modify the user authorization file (UAF) to add the requested account - Create the account login directory - Create all directories required for use by DSM configurations - Create and grant an identifier for the DSM environment manager - Create an identifier for use by DSM environment users - Apply access control lists (ACLs) to all directo- ries and files created When the account initialization command procedure is created, DSM$INIT displays the procedure on your terminal. You can then select to run the initialization command procedure. If you do not run the procedure, it is saved in a file with the following name format: DSM$ADDMAN_ACCOUNT.COM where: ACCOUNT is the name of the DSM environment manager account being created If you choose to run the account initialization command procedure, all the operations that are displayed are performed. When the account initialization procedure completes successfully, DSM$INIT takes the following actions: 1-18 Installing DSM o It creates an entry in the ^DSMMGR system global de- scribing the manager account for the newly initialized environment. o It creates the ^SYS environment configuration global in the directory you designated as the DSM environment root directory. The ^SYS global is an RMS ISAM-based global that is used by DSM utilities to define and start DSM configurations. o It creates the ^DSMACC configuration access global in the DSM environment root directory. The ^DSMACC global is an RMS ISAM-based global used to store environment and DDP node access authorization information. You can run the DSM$INIT procedure multiple times on the same account. DSM$INIT only makes the changes necessary to produce a valid DSM environment. In a VMScluster environment, run DSM$INIT again whenever you add a new node to the cluster. This operation creates the required subdirectories for the new node. You can also rerun DSM$INIT to initialize new journal or database directories on additional disk drive units. Running DSM$INIT.COM Example 1-1 shows how to run the DSM$INIT.COM procedure to create a new OpenVMS account and initialize it as a DSM environment manager account. This example is run in a VMScluster environment. ________________________Note ________________________ You must log in to a privileged system account to run the DSM$INIT command procedure. _____________________________________________________ Example 1-1 Running the DSM$INIT Command Procedure (continued on next page) Installing DSM 1-19 Example 1-1 (Cont.) Running the DSM$INIT Command Procedure $ @SYS$MANAGER:DSM$INIT DSM Environment Manager Initialization The DSM environment manager must have an account to define and control DSM Configurations. This procedure allows you to create a new account or upgrade an existing account as a DSM environment manager. Enter the account name to use with DSM > DSMMGR The DSMMGR account does not currently exist Do you want to create and initialize this account [Y OR N] ? Each account must have a UIC identifier associated with it. A UIC is in the form: [group,member] The group is an octal number less than 37777 and the member is an octal number less than 177777. Enter the UIC for the DSM environment manager's account: Enter the UIC for this account > [250,500] An account password is required in order to add the account. Always select a password that is not obvious or easy to guess. Enter the account password (not echoed) > Enter the same password again for verification > Each account requires a default login directory. This procedure creates an account with a login device and directory name. The login directory name is always equivalent to the account name. Enter the login device for the DSM environment manager's account: Enter the login device for this account > DISK$USER DSM requires a directory to store log files, routine map files, RMS globals, and RMS routine files and to serve as the DSM environment root directory. This directory also holds subdirectories that are default storage locations for DSM volume sets and journal files. (continued on next page) 1-20 Installing DSM Example 1-1 (Cont.) Running the DSM$INIT Command Procedure You can select any directory or device as the DSM environment root directory. By default, new DSM environment directories are created as a tree of directories whose root is the manager's login directory. A file protection scheme is applied to all of these directories to control access to database, journal, and other files used by the environment. Enter the directory to use for DSM Use of DSM in a VMScluster environment requires the creation of a separate subdirectory for each cluster member. The subdirectories hold node-specific log files created by DSM configurations running on each of the VMScluster nodes. Appropriate subdirectories will be created as part of this initialization process. To do so, all cluster nodes must be identified at this time. The following VMScluster nodes are currently booted and will be initialized for use with DSM: CASEY ZORBA Are there any additional cluster members not currently booted that you would like to add to this list [Y OR N] ? This initialization process creates default directories to hold database and journal files associated with this environment. The default directories are created as subdirectories of the environment root directory. The following directories will be created if they do not already exist: DISK$USER:[DSMMGR.DATABASE] DISK$USER:[DSMMGR.JOURNAL] You may also want to create default directories for database and journal files on disk units other than the one used for the account login directory. You can optionally select to initialize these additional directories at this time. Create similar directories on other disk devices [Y OR N] ? Y (continued on next page) Installing DSM 1-21 Example 1-1 (Cont.) Running the DSM$INIT Command Procedure Enter the disk device name that will receive the new directories. The disk unit must currently be available to successfully initialize the directories. Enter ^L to see a list of disk devices currently mounted on your system. Enter an alternate disk for database/journal directories > DISK$DATA Enter an alternate disk for database/journal directories > The following command procedure has been created to update the new DSM manager's account and directories: ========================================================================== $ ! Command Procedure to Initialize DSMMGR $ ! for use as a DSM manager's account $ ! $ IF P1 .NES. "" THEN GOTO CONTINUE $ WRITE SYS$OUTPUT "You MUST enter with P1 = account password" $ EXIT $ ! $ CONTINUE: $ ! $ ON ERROR THEN GOTO ERROR $ UAF = "$AUTHORIZE" $ IF F$TRNLNM("SYSUAF") .EQS. "" THEN $ DEFINE SYSUAF SYS$SYSTEM:SYSUAF.DAT $ WRITE SYS$OUTPUT "Adding new Account for use as a DSM environment manager . . ." $ ! $ ! Add account and set password lifetime to 90 days, preexpired $ ! $ UAF ADD DSMMGR/PASSWORD='P1/UIC=[250,500]/OWNER=VAXDSM - /DEVICE=DISK$USER:/DIR=[DSMMGR] - /FLAGS=NODISUSER - /PWDEXPIRED/PWDLIFETIME=90-00 $ ! $ WRITE SYS$OUTPUT "Modifying Environment Manager Account Quotas . . ." $ UAF MODIFY DSMMGR/ENQLM=1000 $ UAF MODIFY DSMMGR/BYTLM=40960 $ UAF MODIFY DSMMGR/ASTLM=36 $ UAF MODIFY DSMMGR/DIOLM=18 $ UAF MODIFY DSMMGR/WSDEF=500 $ UAF MODIFY DSMMGR/WSQUOTA=1000 (continued on next page) 1-22 Installing DSM Example 1-1 (Cont.) Running the DSM$INIT Command Procedure $ UAF MODIFY DSMMGR/WSEXTENT=1200 $ UAF MODIFY DSMMGR/FILLM=150 $ UAF MODIFY DSMMGR/PRIV=TMPMBX $ UAF MODIFY DSMMGR/DEFPRIV=TMPMBX $ ! $ UAF SHO DSMMGR $ ! $ READ/PROMPT="Account initialized - press return to continue" SYS$COMMAND A $ ! $ UAF ADD/IDENTIFIER/ATTRIBUTE=RESOURCE DSM$MANAGER_DSMMGR $ ADD/IDENTIFIER DSM$USER_DSMMGR $ UAF GRANT/IDENTIFIER DSM$MANAGER_DSMMGR DSMMGR $ ! $ ! Setup environment root directory $ ! $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$USER:[DSMMGR] $ ! $ SET DIRECTORY DISK$USER:[DSMMGR] - /ACL=((DEFAULT_PROTECTION,S:RWED,O:RWED,G,W),- (IDENTIFIER=DSM$MANAGER_DSMMGR,OPTION=DEFAULT,- ACCESS=READ+WRITE+EXECUTE+DELETE),- (IDENTIFIER=DSM$MANAGER_DSMMGR,ACCESS=READ+WRITE+EXECUTE)) $ ! (continued on next page) Installing DSM 1-23 Example 1-1 (Cont.) Running the DSM$INIT Command Procedure $ ! $ ! Setup cluster node directories $ ! $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$USER:[DSMMGR.CASEY] $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$USER:[DSMMGR.ZORBA] $ ! $ ! Setup database/journal directories $ ! $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$DATA:[DSMMGR] $ SET DIRECTORY DISK$DATA:[DSMMGR] - /ACL=((DEFAULT_PROTECTION,S:RWED,O:RWED,G,W),- (IDENTIFIER=DSM$MANAGER_DSMMGR,OPTION=DEFAULT,- ACCESS=READ+WRITE+EXECUTE+DELETE),- (IDENTIFIER=DSM$MANAGER_DSMMGR,ACCESS=READ+WRITE+EXECUTE)) $ ! $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$DATA:[DSMMGR.DATABASE] $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$DATA:[DSMMGR.JOURNAL] $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$USER:[DSMMGR.DATABASE] $ CREATE/DIRECTORY/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) - DISK$USER:[DSMMGR.JOURNAL] $ ! $ ERROR: $ EXIT ========================================================================== Do you want to edit this command procedure [Y OR N] ? Type YES if you want to make modifications to this command procedure before it is run. The EDT [TM] editor is called to allow you to edit the file. Press Return if the command procedure is satisfactory. (continued on next page) 1-24 Installing DSM Example 1-1 (Cont.) Running the DSM$INIT Command Procedure Note that you should use care in reducing account parameters and privileges, or in modifying how directories are created. The proper initialization of the account depends on these account parameters. You can save the command procedure and run it at a later time by answering NO to the following question: Do you want to run this command procedure now [Y OR N] ? > Y Adding new Account for use as a DSM environment manager . . . %UAF-I-ADDMSG, user record successfully added %UAF-I-RDBADDMSGU, identifier DSMMGR value: [000503,000001] added to rights data base Modifying Environment Manager Account Quotas . . . %UAF-I-MDFYMSG, user record(s) updated . . . DSM$INIT now displays the updated account authorization record. (continued on next page) Installing DSM 1-25 Example 1-1 (Cont.) Running the DSM$INIT Command Procedure Username: DSMMGR Owner: VAXDSM Account: UIC: [250,500] ([DSMMGR]) CLI: DCL Tables: DCLTABLES Default: DISK$USER:[DSMMGR] LGICMD: LOGIN Login Flags: Primary days: Mon Tue Wed Thu Fri Secondary days: Sat Sun No access restrictions Expiration: (none) Pwdminimum: 6 Login Fails: 0 Pwdlifetime: 90 00:00 Pwdchange: (pre-expired) Last Login: (none) (interactive), (none) (non-interactive) Maxjobs: 0 Fillm: 150 Bytlm: 40960 Maxacctjobs: 0 Shrfillm: 0 Pbytlm: 0 Maxdetach: 0 BIOlm: 18 JTquota: 1024 Prclm: 2 DIOlm: 18 WSdef: 500 Prio: 4 ASTlm: 36 WSquo: 1000 Queprio: 0 TQElm: 10 WSextent: 1200 CPU: (none) Enqlm: 1000 Pgflquo: 10240 Authorized Privileges: TMPMBX NETMBX Default Privileges: TMPMBX NETMBX Account initialized - press return to continue %UAF-I-RDBADDMSG, identifier DSM$MANAGER_DSMMGR value: %X8001000F added to rights data base %UAF-I-RDBADDMSG, identifier DSM$USER_DSMMGR value: %X80010010 added to rights data base %UAF-I-GRANTMSG, identifier DSM$MANAGER_DSMMGR granted to DSMMGR %CREATE-I-CREATED, DISK$USER:[DSMMGR] created %CREATE-I-CREATED, DISK$USER:[DSMMGR.CASEY] created %CREATE-I-CREATED, DISK$USER:[DSMMGR.ZORBA] created %CREATE-I-CREATED, DISK$DATA:[DSMMGR] created %CREATE-I-CREATED, DISK$DATA:[DSMMGR.DATABASE] created %CREATE-I-CREATED, DISK$DATA:[DSMMGR.JOURNAL] created %CREATE-I-CREATED, DISK$USER:[DSMMGR.DATABASE] created %CREATE-I-CREATED, DISK$USER:[DSMMGR.JOURNAL] created (continued on next page) 1-26 Installing DSM Example 1-1 (Cont.) Running the DSM$INIT Command Procedure The DSM management globals will now be updated . . . Updating DSM Management Global: ^[SYS$LIBRARY]DSMMGR Initializing DSM Configuration Global: ^[DISK$USER:[DSM$DSMMGR]]SYS Account DSMMGR successfully initialized The account has been created with your specified password. However, for security reasons, the password has been set to expire. Please log in to the new account immediately and reset the account password. You can now log in to the DSM manager's account and use the SYS$MANAGER:DSM$CONFIGURE.COM command procedure to initialize DSM database volume sets, or create and start up new DSM configurations. See the "DSM Installation and Management Guide" for complete information about DSM configurations and the "DSM Database Operations Guide" for complete information about database volume sets. Creation of the OpenVMS account and its initialization as a DSM environment manager account is now complete. If you are running within a VMScluster environment, DSM$INIT initializes all nodes for use with DSM in a single operation. The process quotas and privileges used to create the DSM environment manager account in the previous example are generally good values for initial use. You may find that you need to adjust these values as your requirements change. It is important to set the values for WSQUOTA and WSEXTENT appropriately to ensure good performance. However, recommendations for these values depend entirely on the characteristics of the configuration that you intend to run. After you complete installation and initialization, read Chapter 2 and Chapter 5 carefully. They provide details on how you can establish the appropriate values for the DSM manager's and user's accounts, and how to tailor OpenVMS SYSGEN parameters for your site. Installing DSM 1-27 The DSM$INIT command procedure grants only the TMPMBX and NETMBX privileges during account creation and applies the default UAF record values. However, your site may require the OPER privilege. OPER is required to use the ZUSE command or the operator REPLY/TO command for coordinating after-image journal file use. You change privileges with the OpenVMS Authorize Utility. For details about the OpenVMS Authorize Utility, see the OpenVMS System Management Utilities Reference Manual. Configuring DSM After the DSM environment manager account is initialized, you must log in to the manager account and run the SYS$MANAGER:DSM$CONFIGURE.COM procedure. The DSM$CONFIGURE command procedure provides a simple introduction to the methods used to create DSM databases and define DSM configurations. When you become more familiar with these techniques, you can directly call standard DSM utilities to manage your configurations. The DSM$CONFIGURE command procedure optionally allows you to: o Create a new DSM database volume set o Define a DSM configuration o Start a DSM configuration in the newly initialized OpenVMS account ________________________Note ________________________ If you plan to use Before-Image and After-Image Journaling, use ^BIJINIT and ^JRNINIT to create before-image and after-image journal files before you run DSM$CONFIGURE.COM. For more information, see the DSM for OpenVMS Database Operations Guide. If you plan to use mapped routines, you must create a mapped routine section file before you run DSM$CONFIGURE.COM. For more information, see Chapter 6. _____________________________________________________ 1-28 Installing DSM To run DSM$CONFIGURE, log in to the DSM environment manager account and enter the following as shown in Example 1-2. Example 1-2 Running DSM$CONFIGURE.COM $ @SYS$MANAGER:DSM$CONFIGURE DSM Configuration Management Procedure This procedure is intended to be used while logged in to a newly initialized DSM manager account to configure and start DSM for the first time. It serves as an introduction to the techniques used to build DSM database volume sets, create new DSM configuration definitions, and start a fully functional DSM configuration. The following DSM utilities are called: ^VOLMAN - creates new DSM database volume sets ^CONFIG - builds DSM configuration definitions ^STU - starts a DSM configuration You can independently access any of these utilities at a later time to further modify the DSM environment. See the "Installation and Management Guide" for complete information about DSM configurations. See the "Database Operations Guide" for information about database sets and volume sets. Do you want to create a new DSM database volume set [Y OR N] ? You can elect to build a DSM database volume set at this time. If you want to create a new volume set answer YES. The "Database Operations Guide" contains complete information about DSM volume sets and the procedure used here to create new volume sets. Initialize a DSM database volume set Every DSM volume set must have a unique 3-character identifier. Enter the 3-character name for the volume set > EMP Create a DSM volume in which file ? Enter desired size of this volume in 1 KB DSM blocks > 20000 SYSTEM volume sets are initialized with an MGR UCI and a complete set of DSM system management globals and routines. (continued on next page) Installing DSM 1-29 Example 1-2 (Cont.) Running DSM$CONFIGURE.COM APPLICATION volume sets are created with a single empty UCI named LIB. APPLICATION volume sets cannot be mounted as the 1st (S0) volume set within a configuration. Initialize as a SYSTEM or APPLICATION volume set [S or A] Maximum number of globals allowable on this volume set <90> Allow expanded string lengths on this volume set [Y OR N] ? What would you like the new label on this volume to be ? (up to 20 characters) > EMP Volume 1 Initializing DISK$USER:[DSMMGR.DATABASE]EMPVOL1.GLS for use as a DSM volume... DISK$USER:[DSMMGR.DATABASE]EMPVOL1.GLS initialized as Volume 1 of DSM volume set EMP with 20000 1 KB blocks (50 DSM maps) Build DSM configuration Type ? for HELP at any time Would you like extended help [Y OR N] ? Enter the configuration identifier <1> PAYROLL Enter the name of the configuration that you want to create. See Chapter 2 for complete information about DSM configurations and the procedure used here to create a configuration. . . . Start up configuration PAYROLL [Y OR N] ? . . . After you create the startup configuration, you can start DSM. The startup procedure establishes all processes necessary for your DSM system environment. See Chapter 2 for information about these processes. 1-30 Installing DSM If DSM startup fails, an explanatory message appears on your terminal. Initialization often fails because of improper SYSGEN parameters such as global page quota or improper DSM environment manager account quotas. In many cases, the reason for failure is stored in the DSMDEMON.LOG file. To correct a failure, tailor SYSGEN parameters or account quotas as described in Chapter 5. The appropriate values for these parameters depend on the characteristics of the configuration you are attempting to start. The ^MEMREQ Utility provides these values for each configuration you build. After you change these parameters, run AUTOGEN and reboot your system before attempting to restart your DSM configuration. ________________________Note ________________________ If you intend to use DSM on multiple nodes of a cluster, you must define a node-specific con- figuration for each VMScluster node and start the configuration on the target node. For more information about how to run DSM in a VMScluster environment, see the section "Initializing DSM in a VMScluster Environment" in Chapter 2. In addition, see the DSM for OpenVMS Database Operations Guide. _____________________________________________________ Establishing Your License Starting with Version 7.0, DSM uses a new licensing procedure designed to simplify license configuration and add flexibility. This procedure introduces a new license key format that includes: o Customer order number o License key information o An authorization key that activates your system Installing DSM 1-31 All products feature incremental pricing rather than fixed system sizes. For small systems, the Workgroup license provides a cost-effective, efficient solution. (See the License Configuration Guide produced by InterSystems for more information about product licensing.) Unlike the licensing method used by Digital Equipment Corporation, you specify your license after installation of your DSM software. If you are using only terminal licenses for your system, you need only run the new ^SYSMAN utility, ^LMFEDIT in one configuration on each host in your network. ^LMFEDIT lets you enter new license information or edit existing license information. If there is, the license server informs the system that it can accept the connection and counts the connection towards the allowable user limit of the client. If there are no more available connections, the license server tells the server to refuse the connection. The Server sends the client a "no more license" error. To establish a license server, you take the following steps: 1. Establish a license server. Run the utility ^LMFEDIT in one configuration on one node in your network to enter the Workgroup, Division, Enterprise or Client/Server license. 2. Run ^CONFIG to specify the TPC/IP address of that license server for each configuration in your network that may need to use these licenses. The following sections describe how to run ^LMFEDIT for any type of license and how to use ^CONFIG to specify the address of your license server. Entering a License You use the ^LMFEDIT Utility to establish your licenses. Normally, you do so in one configuration on each host in your network. However, if you have Enterprise or Client /Server licenses, you must also run ^LMFEDIT to specify those licenses in one configuration on one node in your network. That node then becomes the license server for your entire network. 1-32 Installing DSM Take the following steps: 1. Invoke ^SYSMAN, the System Management Utilities. 2. Choose option 3, LICENSE EDIT. You see the current license data for this configuration, if any. 3. Specify that you want to edit the data If no license data exists, fill the required items in as prompted. If license data does exist, press Return to accept any existing data or enter new data as prompted. When you need to erase exising data, enter a dash ("-") to delete the data. 4. Save the data when prompted. You then return to the System Management Utilities menu. The following example shows how you use ^LMFEDIT to add or update license data for a configuration. System Management Utilities 1. ACCESS CONTROL (^ACL) 2. FORCE EXIT (^FORCEX) 3. LICENSE EDIT (^LMFEDIT) 4. LOCK TABLE CLUSTER DISPLAY (CLUSTER^LOCKTAB) 5. LOCK TABLE DISPLAY (^LOCKTAB) 6. LOGIN (^LOGIN) 7. MEMORY (^MEMORY) 8. SHOW DSM USERS (^%SY) 9. SHUTDOWN (^SHUTDWN) 10. STARTUP (^STU) 11. TIED ROUTINES (^TIED) Select Option > 3. LICENSE EDIT Current license values: Installing DSM 1-33 Customer Name = BIGDSM Order # = 0 Product Auth. Key = A52BF8C7199 Expiration Date = 2/25/2020 Machine Type = 41 Machine ID = Multi-User = 500 Single-User = 0 Server = 600 Workgroup = 0 Client-Server (Primary) = 700 Client-Server (Additional) = 0 Enterprise = 0 Division = 0 Edit these values now [Y OR N] ? Y Customer Name ? Enter the data for Customer Name from your DSM license. (enter "^" for previous question, enter "-" to erase default data) Customer Name Order # <0> Product Auth. Key Expiration Date <2/25/2020> Machine Type <41> Machine ID > Multi-User <500> Single-User <0> Server <600> Workgroup <0> Client-Server (Primary) <700> Client-Server (Additional) <0> Enterprise <0> Save data to license file [Y OR N] ? > Y License file updated. 1-34 Installing DSM Specifying a License Server Address If you have licenses that require a license server, you must then establish that license server for your network. Run ^CONFIG for each configuration that you want to be able to access Enterprise or Client/Server licenses. Then answer the questions concerning the license server. These questions include: o The TCP/IP address of the license server o The port number o Whether to automatically start the license server on system startup The TCP/IP address must be a real address. Do not use addresses such as "127.0.0.1" or "0.0.0.0." The port number must match the port number to which clients connect. The following shows an example of the ^CONFIG dialog for implementing a License server. . . . Include support for Visual M application serving [Y OR N] ? Include support for a license server [Y OR N] ? ? Enter "Y" if this configuration will use a license server Include support for a license server [Y OR N] ? Enter license server IP address <192.9.200.1> ? Enter the IP address of the license server this configuration will use NOTE: You must enter an IP address even if this system is the server. Enter license server IP address <192.9.200.1> Enter license server port <2002> ? Since license checking runs over TCP/IP, you must provide a port number. This number must be unique to the license server client and server. You must be careful not to use port numbers used by such processes as FTP, RPC, the Visual M Server and others. Enter license server port <2002> Auto-start server [Y OR N] ? ? Installing DSM 1-35 If "Y" then this configuration starts a license server process. If "N" then this configuration will not start a license server, but may connect to a license server as specified by the server address and port fields. Auto-start server [Y OR N] ? Y Include support for security auditing [Y OR N] ? You should make sure that the DSM batch startup command procedure, DSM$INSTALL_SITE.COM starts up the DSM configuration containing the license server before it starts any other configurations which depend on using licenses from the license server. See the section "DSM$INSTALL_SITE.COM" for more information. Editing the Startup and Shutdown Command Procedures You must edit the startup and shutdown command procedures to provide for automatic startup and shutdown of DSM configurations. These procedures are: o The DSM initialization command procedures o The system startup command procedure o The DSM shutdown command procedure The DSM Initialization Command Procedures DSM uses two command procedures: o DSM$INSTALL.COM o DSM$INSTALL_SITE.COM DSM$INSTALL.COM The SYS$STARTUP:DSM$INSTALL.COM procedure contains mandatory operations that install and initialize the DSM software at system boot time. These operations include the following: o Installing DSM images as shared o Loading the DSM DDP driver o Defining search lists for DSM logical name tables o Initializing the DEC DB Integrator Gateway for DSM environment o Calling the DSM$INSTALL_SITE.COM procedure 1-36 Installing DSM Do not modify DSM$INSTALL.COM. This procedure is updated every time you install new versions of DSM. DSM$INSTALL_SITE.COM SYS$STARTUP:DSM$INSTALL_SITE.COM is a template file. You edit it to include operations to be executed at system boot. You can customize a separate copy of DSM$INSTALL_ SITE.COM for each node in a VMScluster and place them in the system-specific roots. The following operations are included in this file: o Installing optional ECALL image o Running DSM in a heterogeneous VMScluster environment o Allocating physical pages for disk buffer use o Mounting DSM-11 compatible disks o Creating a batch queue for DSM startup o Starting up predefined DSM configurations DSM$INSTALL_SITE.COM contains a detailed description of how to customize the command procedure for your site and enable the relevant capacities listed previously. However, the actual DCL commands used in the examples are disabled with comment characters (!). The edits you make to DSM$INSTALL_SITE.COM are not lost when you install future versions of DSM. Any future upgrade will preserve the existing version of DSM$INSTALL_ SITE.COM. The OpenVMS System Startup Command Procedure You must edit your OpenVMS system startup command procedure, SYSTARTUP_VMS.COM (located in SYS$STARTUP:) to include the following command line: $ @SYS$STARTUP:DSM$INSTALL Installing DSM 1-37 The DSM Shutdown Command Procedure The SYS$MANAGER:DSM$SHUTDOWN.COM procedure shuts down a DSM configuration. You must edit the system shutdown command procedure, SYS$MANAGER:SYSHUTDWN.COM, to call the DSM$SHUTDOWN command procedure and automatically shut down running DSM configurations when your OpenVMS system is shut down. Include the following command line in the SYS$MANAGER:SYSHUTDWN.COM file: $ @SYS$MANAGER:DSM$SHUTDOWN p1 where: p1 is the name of the DSM environment manager's account Include the previous command line in the SYS$MANAGER:SYSHUTDWN.COM procedure for each DSM environment that is initialized. This ensures that any active DSM volumes are dismounted in an orderly fashion before the system shuts down. ________________________Note ________________________ If you fail to include @SYS$MANAGER:DSM$SHUTDOWN.COM in your system shutdown command file for each DSM environment, database degradation can result. _____________________________________________________ Installing DSM in a VMScluster Environment If you are installing DSM on a node in a VMScluster environment, you must log in to the system manager's account on each node that will be running DSM and do the following: 1. Install DSM as a shared image by entering the following: $ @SYS$STARTUP:DSM$INSTALL Installation of the DSM images using the DSM$INSTALL command procedure requires minimum SYSGEN parameter values for GBLPAGES and GBLSECTIONS. If you are unable to run DSM$INSTALL on all VMScluster nodes, modify these SYSGEN parameters on the affected node and reboot that node. To do this, follow the procedure described earlier in this chapter in the section "Determining SYSGEN Requirements for Installation." 1-38 Installing DSM You can also use the OpenVMS System Management Utility (SYSMAN) to perform these steps from your local node by defining your management environment to be: o A particular node o A group of nodes o A cluster For more information, see the Digital publication, OpenVMS System Management Utilities Reference Manual. DSMCRASH.LOG Log File for Image Exits If an image exits, the DSMCRASH.LOG file is written to your current OpenVMS directory. You can specify another location for DSMCRASH.LOG by defining the DSM$CRASH logical name. You must have write access to the directory specified by DSM$CRASH. Installing DSM 1-39 2 ________________________________________________________________ Managing DSM for OpenVMS Systems This chapter provides DSM managers with information about managing a DSM environment. It presents an overview of a DSM environment and detailed information about DSM configurations. This chapter assumes that you have already created or initialized a DSM environment manager account by following the procedures in Chapter 1. For additional information about OpenVMS system manage- ment, see the OpenVMS System Manager's Manual and the OpenVMS System Management Utilities Reference Manual, published by Digital Equipment Corporation. DSM Environment A DSM environment is the working area used by a DSM manager to enable and control DSM operations. The initialization of an environment configures the following resources to support DSM management: o OpenVMS account The DSM environment manager's account provides a secure operational account from which the manager can control DSM. Account quotas are propagated to the various supporting DSM system processes when DSM is fully configured. o DSM directories DSM directories and subdirectories are created for use by DSM processes and are the default location for the storage of database and journal files. o DSM environment identifier Managing DSM for OpenVMS Systems 2-1 An identifier is created for the environment and granted to the DSM manager's account. The identifier represents the privileges necessary to accomplish DSM management functions within the environment. Holders of the identifier can create volume sets, define configurations, and control other operations within the environment. o Environment configuration global (^SYS) The environment configuration global is an RMS-based global named ^SYS (file name SYS.GBL). The ^SYS global holds the complete database of DSM configurations that the DSM manager has defined for the environment. A configuration describes the various enabled DSM capabilities, available databases, and other parameters relevant to a fully operational DSM environment. After initialization, ^SYS is generally empty. o Configuration access global (^DSMACC) The configuration access global is an RMS global named ^DSMACC (file name DSMACC.GBL). The ^DSMACC global holds the list of accounts that are authorized to access DSM configurations running in this environment. After initialization, ^DSMACC is generally empty. Environment Directories, Files, and Protection When you initialize a DSM environment using DSM$INIT.COM, it creates a set of DSM directories as a tree of directories. The directories hold DSM log files, mapped routines, and database files. The top-level directory of the tree is known as the environment root directory. By default, DSM$INIT creates this directory as the environment manager's account login directory. However, DSM$INIT allows you to configure the environment root directory as a directory or subdirectory anywhere on your system. Several subdirectories of the environment root directory are also created to support the environment: o Default journal directory ([.JOURNAL]) The journal directory is the default location for after-image or before-image journal files. 2-2 Managing DSM for OpenVMS Systems o Default database directory ([.DATABASE]) The database directory is the default location for DSM database volume sets. o Cluster node directories In a VMScluster environment, a separate subdirectory is also created for each member of the cluster. For more information about VMScluster environments, see the section "Initializing DSM in a VMScluster Environment" later in this chapter. The environment root directory holds the ^SYS environment configuration global and ^DSMACC configuration access global. The root directory is also the default location for mapped routine files created using the ^RMBLD Utility. In a single-node configuration, log files, error files, and option files for the DSM detached processes are also located within the root directory. Figure 2-1 illustrates the relationship between the various directories in a single-node system. Database and journal subdirectories are default locations for the storage of DSM volume sets and journal files. DSM utilities that prompt for the location of a database or journal file always use one of these directories when creating a default response. You can always enter a different file specification to override the default. DSM$INIT optionally initializes additional database and journal directories on other system devices. For example: $ @SYS$MANAGER:DSM$INIT . . . This initialization process will create default directories to hold database and journal files associated with this environment. The default directories are created as subdirectories of the environment root directory. The following directories will be created if they do not already exist: Managing DSM for OpenVMS Systems 2-3 DISK$USER:[DSMMGR.DATABASE] DISK$USER:[DSMMGR.JOURNAL] You may also want to create default directories for database and journal files on disk units other than the one used for the account login directory. You can optionally select to initialize these additional directories at this time. Create similar directories on other disk devices [Y OR N] ? Y Enter the disk device name that will receive the new directories. The disk unit must currently be available to successfully initialize the directories. Enter ^L to see a list of disk devices currently mounted on your system. Enter an alternate disk for database/journal directories > DISK$DATA Enter an alternate disk for database/journal directories > . . . ______________________ Caution ______________________ Never place your volume set file on the same physical device as its after-image journal files. If the device fails, you need the after-image journal files to recover the backup copy of the volume set. You can place before-image journal files on the same physical disk device as the primary database. However, use disk performance to determine the proper placement of the before-image journal file. _____________________________________________________ OpenVMS UIC-based protection is applied to all directories and RMS global files initialized by DSM$INIT. DSM$INIT also creates a unique identifier for the new environment. The identifier is granted to the DSM environment manager's account and is then associated with each of the initialized files through the application of an access control list (ACL). Only the DSM environment manager or the alternate manager account that holds the identifier can access files protected by this method. 2-4 Managing DSM for OpenVMS Systems Default type ACLs are also applied to the directories so that new files created within the directories receive the same UIC and identifier-based protection. The applied protections prevent unauthorized access to sensitive environment, configuration, database, and journal files. See Chapter 3 for complete details about how to control access to DSM environments and configurations. The DSM$INIT procedure also creates an identifier for use in protecting access to DSM-11 disk drives and the DSM environment logical name table. DSM Baseline Mode After a DSM environment has been initialized for use, you can log in to the environment manager's account and use DSM in baseline mode. Use the DSM command with the /MANAGER command line qualifier to enter baseline mode: $ DSM/MANAGER This gives you direct access to the DSM command line interpreter. DSM displays the following banner: DSM for OpenVMS Alpha V7.1 DSMMGR [Baseline] > The [Baseline] access mode specifier indicates that there is no configuration running. In baseline mode, DSM offers only minimal services, and its primary function is intended for use in running DSM utilities. Baseline access has the following characteristics: o All DSM interpreter capabilities are available. o Globals are stored and accessible only in RMS globals. o Routines are stored and accessible only in RMS routine directories. o Journaling, Distributed Data Processing (DDP), and other advanced capabilities are not available. Managing DSM for OpenVMS Systems 2-5 In baseline mode, global and routine access is limited to utility globals and routine directories supplied by the DSM installation procedure. DSM managers use baseline mode for management activities such as: o Creating DSM volume sets o Defining DSM configurations o Starting defined DSM configurations DSM Configurations A DSM configuration is a database that describes the operational capabilities and characteristics of a fully functional DSM environment. A configuration definition specifies the following: o How many disk buffers are available for global data caching o Which DSM database sets are included, and the following: - Whether cluster-mounting is enabled. - Whether Before-Image Journaling is enabled. - Whether After-Image Journaling is enabled. - Which global references are translated. - Which mapped routines are installed. - Whether DDP is enabled. - What are the default values of the DSM command line qualifiers. As the DSM environment manager, use the Create Configuration Utility (^CONFIG) while logged in to the baseline system to name and define the capabilities of a configuration. After you finish defining a configuration, you start the configuration with the Configuration Startup Utility (^STU). You can start configurations only while logged in to the DSM environment manager account. A configuration is considered running when all the defined configuration capabilities are available to DSM environment users. 2-6 Managing DSM for OpenVMS Systems A running DSM configuration includes a set of shared data structures and detached DSM system processes that provide highly efficient access to global databases. The configuration establishes all capabilities available to DSM users. When a DSM system is running, programmers and application users can log in to it from various OpenVMS accounts. Users can accept the defaults established by the configuration or can override some of the defaults using qualifiers on the DSM command. A configuration is considered shut down when only the baseline capabilities are available. If no configuration is running, a programmer or appli- cation user who tries to run DSM without specifying the /MANAGER command line qualifier cannot access DSM. The system displays the following error message: %DSM-E-NOTRUN A DSM configuration is not running DSM Accounts You can establish any number of OpenVMS user accounts to provide access to a running configuration. There are three types of accounts that you can initialize for use with DSM: o DSM environment manager account The DSM$INIT.COM procedure creates the DSM environment managers account. DSM can be started only from this account. You can create or extend volume sets or perform the other management tasks described in this chapter from this account. You can also shut down DSM from this account and from the OpenVMS system account. The DSM environment manager can use the Access Control Utility (^ACL) to designate alternate environment manager accounts for an environment. o DSM programmer accounts These accounts are for the interactive users who develop DSM routines. You use the OpenVMS Authorize Utility to create programmer accounts. You can control programmer access to DSM configurations to limit access Managing DSM for OpenVMS Systems 2-7 to specific DSM volume sets and UCIs and disable access to DSM management functions. o DSM application user accounts These accounts are for users executing only particular DSM routines under controlled conditions. You use the OpenVMS Authorize Utility to create such application accounts. You can configure these accounts so that application users are tied to the DSM application and cannot interact directly with the DSM interpreter. The section "Establishing OpenVMS Accounts for Programmers and Application Users" in Chapter 3 describes how to set up the programmer and application user accounts. Overview of DSM Databases DSM databases are organized into named database sets. A database set is described by its three components: o DSM volume sets DSM volume sets are specially formatted OpenVMS files that hold DSM globals and routines. o After-image journal files Use after-image journal files to keep an audit trail of modifications made to globals within a running configuration. o Before-image journal file The before-image journal file maintains a record of the contents of a database block before a major database event occurs. Major database events include block splits caused by a global set operation or block merges caused by a global kill operation. Before defining DSM configurations, you must perform initializations as follows: __________________________________________________________ Use________________________To_Initialize__________________ The ^VOLMAN Utility DSM volume sets The ^BIJINIT Utility Before-image journal files 2-8 Managing DSM for OpenVMS Systems __________________________________________________________ Use________________________To_Initialize__________________ The_^JRNINIT_Utility_______After-image_journal_files______ This operation preallocates OpenVMS files and places them on system disk units in the various DSM directories you created during environment initialization. You can configure volume sets to consist of one to eight OpenVMS files. After you create and place the volume sets you want to use in your application, you can organize them into database sets. The database set definition includes all volume set file names and journal file names (after-image and before-image). The following characteristics of the database set are also included in the definition: o Cluster-mounted When this characteristic is enabled, the database set can be mounted and shared by multiple members in a VMScluster environment. o Transaction processing When this characteristic is enabled, you can organize related changes to the database set into transactions. The transactions are defined within application program recovery units. DSM supports three types of database sets: o DSM-11 compatible database sets The DSM-11 compatible database set includes one DSM-11 volume set mounted as OpenVMS foreign volumes, optional after-image journal files, and an optional before-image journal file. o OpenVMS DSM database sets A OpenVMS DSM database set consists of one DSM volume set, optional after-image journal files, and an optional before-image journal file. o Transaction database sets Managing DSM for OpenVMS Systems 2-9 A transaction database set includes one or more volume sets, required after-image journal files, and a required before-image journal file. DSM transaction recovery unit processing applies only to globals resident within transaction database sets. Each database set within a DSM environment is uniquely named and defined. You use the Create/Modify Database Set Utility (MODIFY^CONDBS) to create and modify the components of a named database set. When you create a configuration, you specify which database sets you want to make available to the configura- tion. MODIFY^CONDBS prompts for a name of the database set(s) to make available. You can specify a database set. You can also choose to display a list of all defined database sets by entering: o A wildcard (*) to specify you want all database sets or (if you include a character with the wildcard) all database sets that include that character. For example A*, to list all defined database sets containing A. o /P to indicate that the utility should display the choices 18 lines at a time with a prompt to press Return and display any further entries that match your choice. To make database set definition easier, the ^CONFIG Utility also allows you to create and modify database sets as you define a configuration. After you create all the database set definitions you intend to make available to a DSM configuration, you can use the ^CONFIG utility to identify which database sets to mount during startup. You also use ^CONFIG to include support for mountable database sets. After you create a database set, you can include it in multiple configurations. In a VMScluster environment, you need to define the database set only once. Each cluster member can then name the same database set for mounting on a clusterwide basis within the configurations defined for that node. If you modify the components of a database 2-10 Managing DSM for OpenVMS Systems set, the changes are reflected in each configuration that references the database set. For details about how to create and manage volume sets and database sets, see the DSM for OpenVMS Database Operations Guide. Configuration Management (^CONMAN) The ^CONMAN Utility provides utilities to create, copy, delete, display, and modify configurations and configuration information. Enter the following to run ^CONMAN: >D ^CONMAN The utility displays the following menu: Configuration Management 1. COPY CONFIGURATION (COPY^CONFIG) 2. CREATE CONFIGURATION (^CONFIG) 3. DELETE CONFIGURATION (DELETE^CONFIG) 4. DISPLAY CONFIGURATION (DISPLAY^CONFIG) 5. MODIFY EXISTING CONFIGURATION (MODIFY^CONFIG) Select Option > The following section describes the ^CONFIG Utility. For more information about the other ^CONMAN utilities, see Chapter 7. Use the Create Configuration Utility (^CONFIG) to define new configurations or modify the characteristics of an existing configuration. The ^CONFIG Utility stores configurations by a configuration identifier that you designate. You can create and store any number of configurations. After a configuration is stored, you can: 1. Retrieve it 2. Edit its characteristics 3. Start the configuration Managing DSM for OpenVMS Systems 2-11 To create a new DSM configuration, log in to the DSM environment manager's account and run DSM with the /MANAGER command line qualifier. Example 2-1 explains the various configuration options available and shows how to create a new configuration. References to more detailed documentation are provided for each question. ________________________Note ________________________ If you press Ctrl/C while using ^CONFIG, the utility aborts. This action leaves the configuration partially defined and inconsistent, and subsequent attempts to start the configuration may fail. Always answer all of the questions completely. _____________________________________________________ Example 2-1 Running the ^CONFIG Utility $ dsm/manager DSM V7.0 for OpenVMS VAX DSMMGR [Baseline] >D ^CONFIG Define a DSM Configuration Type ? for HELP at any time Would you like extended help [Y OR N] ? Y Enter the name of the configuration that you want to access. The name must consist of less than 12 uppercase alphabetic and numeric characters and cannot be equal to the number 0. Type ^L to see a list of currently defined configurations. Enter the configuration identifier <1> ERIN ERIN is not currently defined, define it now [Y OR N] ? Initializing ERIN as a new configuration . . . (continued on next page) 2-12 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility Disk buffers are 1KB in-memory buffers used to cache database disk data in memory. The buffer techniques used by DSM can significantly reduce physical disk I/O and increase system performance if the proper number of buffers is chosen. In environments with a large number of users, it is not uncommon to configure anywhere between 2000 to 6000 buffers. However, memory resources can limit this value. If you are creating a configuration for limited use and testing, choose a small number (300-600). This reduces the amount of process and OpenVMS system tuning required to get the configuration started. If you are creating a configuration for production use, it is advisable to increase this value significantly and enable the use of nonpaged memory. Enter the number of disk buffers > 1200 DSM can use nonpaged memory to contain the disk buffers that are used for shared global access. Because disk buffers are shared between all DSM users and require a significant amount of memory. Using nonpaged memory greatly reduces the amount of page fault activity each DSM process incurs and also reduces process working set sizes. If you are creating a stable production environment with greater than 600 disk buffers, it is advisable to use nonpaged memory. To use nonpaged memory, you must preallocate enough system physical memory to contain the disk buffers and other shared data structures for this configuration using the /PHYSICAL_PAGES=nnnn command line qualifier. Use the ^MEMREQ Utility to determine the nonpaged physical memory requirements for this configuration. Enter YES if you have allocated nonpaged memory and want to use it for the disk buffer cache. Answer NO if you want to use paged OpenVMS shared global sections for buffers and shared data structures. Use nonpaged memory for these buffers [Y OR N] ? (continued on next page) Managing DSM for OpenVMS Systems 2-13 Example 2-1 (Cont.) Running the ^CONFIG Utility Enter the maximum number of DSM users that you want to allow simultaneous access to this configuration. Note that the Garbage Collector, Write Demon, DDP processes, Recovery Process, and Journal Process are all considered DSM users. It is important to keep this number as small as possible because additional memory usage is required to support each potential user. Three is the minimum number of users allowed. Enter the maximum number of DSM users <128> Configuration access control provides a complete security system for a running configuration. DSM defines three modes of access: Manager mode - use of the /MANAGER qualifier Programmer mode - access as a programmer Application mode - access as an application user If you enable access control, you can use the ^ACL Utility to specify which users are permitted to log in to DSM for each of these access modes. You can restrict programmers to specific UCIs and restrict application users to specific routines. In addition, programmer mode users are not permitted to use the VIEW command, $VIEW function, privileged system external routines, or the /BYPASS command line qualifier. If you disable access control, any user can access any UCI in programmer mode or application mode. Programmer mode users have unrestricted access to the VIEW command, $VIEW function, privileged external routines, and the /BYPASS command line qualifier. Enable configuration access control [Y OR N] ? The ^PMF Utility produces detailed reports and histograms on the performance of your application within the DSM environment. Frequency of access and modification to specific globals is reported along with statistics on routine calls and CPU utilization. You must reserve additional memory at DSM startup for purposes of performance data collection. Enter YES if you intend to use the ^PMF Utility. Enter NO if you do not want to use the ^PMF Utility. (continued on next page) 2-14 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility Include support for Routine/Global Performance Histograms [Y OR N] ? Y Each running DSM process collects performance data within the PMF data buffer area. Entries in the PMF table require 28 bytes for every global and routine referenced during a data collection period. Globals and routines of the same name but from different volume sets or from different UCIs are considered unique. Enter the size in pages of the PMF buffer to reserve. Each page contains 512 bytes or enough space for approximately 18 entries. If PMF runs out of buffer space, a NO ROOM entry is made within the histogram report. You can then increase the buffer size and restart the configuration. Enter size in pages for the performance data buffer <50> DSM provides server support for the InterSystems' Visual M product. This permits PC applications written in Visual Basic to access DSM globals and routines. Answer YES to enable server support for Visual M. A Visual M server will be started at DSM configuration startup. Answer NO to disable server support for Visual M. Include support for Visual M application serving [Y OR N] ? When TCP/IP communications is chosen for connecting a Visual M desktop client to DSM for OpenVMS, a TCP/IP port number must be configured. This port will be used to initiate connections between the PC and the Visual M servers running under DSM. Enter a port number ranging from 1024 to 65535. Note that port numbers below 1024 are generally reserved by TCP/IP for use by privileged system processes. The port number selected must match the port number configured for your Visual M desktop environment. You can configure your PC to use the same port number by running the Visual M Server Setup utility located in the Visual M program group. Port number 6001 is the default port for both the server and the client. (continued on next page) Managing DSM for OpenVMS Systems 2-15 Example 2-1 (Cont.) Running the ^CONFIG Utility Enter the TCP/IP port for use by the Visual M server <6001> The Visual M server allocates a separate TCP/IP port for use by each application server process it starts. The port numbers are assigned sequentially starting with the port number configured for the Visual M server. Consequently, you must set aside a range of TCP/IP ports for use exclusively by Visual M. Enter the number of TCP/IP port numbers to reserve for use by Visual M application servers. You should reserve sufficient ports to handle the number of users you expect to be concurrently running Visual M applications. Enter the number of TCP/IP ports to reserve for Visual M <512> Include support for a license server [Y OR N] ? ? Enter "Y" if this configuration will use a license server Include support for a license server [Y OR N] ? Enter license server IP address <192.9.200.1> ? Enter the IP address of the license server this configuration will use NOTE: You must enter an IP address even if this system is the server. Enter license server IP address <192.9.200.1> Enter license server port <2002> ? Since license checking runs over TCP/IP, you must provide a port number. This number must be unique to the license server client and server. You must be careful not to use port numbers used by such processes as FTP, RPC, the Visual M Server and others. Enter license server port <2002> Auto-start server [Y OR N] ? ? If "Y" then this configuration starts a license server process. If "N" then this configuration will not start a license server, but may connect to a license server as specified by the server address and port fields. Auto-start server [Y OR N] ? burp (continued on next page) 2-16 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility The DSM security Audit facility allows you to monitor DSM programmer activity in a configuration by recording event messages in the security audit log file and enabling an operator terminal to receive event messages. Using the OpenVMS Audit Analysis utility ($ ANALYZE/AUDIT), the security audit log file can be examined or reviewed periodically. DSM allows the following types of auditing events to be tracked for programmer accesss such that suffieient information exists in order to investigate potential security breaches: Programmer login Programmer logout Modifications to global data Modifications to application routines Modifications to global characteristics Enter 'Y' to enable security auditing or 'N' to disable security auditing. Include support for security auditing [Y OR N] ? Y Specify a security audit name that consists of up to 12 uppercase, alpha-numeric characters. Enter ^L for a list. Enter the security audit name to load at startup > TEST Security audit name TEST is not currently defined. Are you sure you want to continue [Y OR N] ? Define security audit name TEST Enable DSM_LOGIN auditing [Y OR N] ? Enable DSM_LOGOUT auditing [Y OR N] ? Enable DSM_GLOBAL_SET auditing [Y OR N] ? Enable DSM_GLOBAL_KILL auditing [Y OR N] ? Enable DSM_ROUTINE_SAVE auditing [Y OR N] ? Enable DSM_GPROTECTION auditing [Y OR N] ? Enable DSM_GJOURNAL auditing [Y OR N] ? Enable DSM_GCOLLATION auditing [Y OR N] ? (continued on next page) Managing DSM for OpenVMS Systems 2-17 Example 2-1 (Cont.) Running the ^CONFIG Utility *** System Options updated Enter the number of database sets to be defined for this configuration. A configuration must mount at least one database set that includes at least one volume set. Number of database sets in this configuration <1> 2 Enter the name of a database set to define for this configuration. Enter ^L to get a list of the currently defined database sets within the environment. Use a wild card * in a database set to get a partial list and /P for paging option. Name of database set #1 > EMP A configuration can only reference database sets that are already defined. This database set has not been previously defined. Enter YES to define the database set now. Enter NO to go back and enter a different database set name for this configuration. EMP not defined. Define it now [Y or N] You can designate this database set as one of three types of database sets: DSM-11 volume set is comprised of DSM-11 foreign mounted disk volumes VMS volume set is comprised of DSM volume files Transaction comprised of one or more associated DSM volume sets that support transaction processing updates to resident globals Press Return to create a VMS database set. Enter T or D to create a transaction or DSM-11 database set. Is this a VMS, Transaction or DSM-11 database set [V, T OR D] (continued on next page) 2-18 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility Specify whether or not the volume set should be mounted as read-only. If you mount the volume set as read-only, then all global SETs and KILLs to the volume set are prohibited and return the following error: %DSM-E-NOWRITE, Volume set is mounted READ-ONLY Enter YES to mount the volume set as read only. Enter NO to mount the volume set for read/write and allow SETs and Kills to the volume set. Mount EMPLOYEE for READ-ONLY access [Y OR N] ? A Volume set mounted for read-only access is automatically available to other nodes in the cluster and is essentially already cluster-mounted. Furthermore, journaling is superfluous for a read-only volume set. Therefore, the questions that ask if you want to mount a volume set in a cluster and if you want to enable Before-Image Journaling and After-Image Journaling are not asked if you answer yes to this question. If all of the volume sets in the database set are to be mounted by two or more concurrently running configurations within a VMScluster environment, it must be declared as a cluster-mounted database set. Cluster-mounted database sets allow READ/WRITE access for all of the volume sets within this database set across a VMScluster environment. If this database set is to be mounted by only a single running configuration, it should not be declared as cluster mounted. Enter YES to cluster-mount this database set. Enter NO if you do not want to cluster-mount this database set. Mount EMP for clusterwide access [Y OR N] ? Y Use the ^UCIADD utlity to add UCIs to the volume set. You can use ^UCIADD to add UCIs on any volume set, either cluster or locally mounted. Keep in mind that the first mounted volume set must be a SYSTEM (S0) volume set. The system volume set (S0) must be the same cluster mounted volume set on all configurations in the cluster. (continued on next page) Managing DSM for OpenVMS Systems 2-19 Example 2-1 (Cont.) Running the ^CONFIG Utility Enter the name of the volume set within this database set that is to be mounted at configuration startup. The DSM volume set name is the name given to the volume set when it was prepared using the ^VOLMAN Utility. DSM volume set names must be 3 uppercase alphabetic characters. Name of the volume set > EMP DSM volume sets can consist of one to eight disk or file volumes. Enter the number of volumes in this volume set. Enter the number of volumes in volume set EMP <1> Enter the file specification of the volume to mount during configuration startup. To override the default file specification supplied in brackets, you only need to enter that portion of the default that you want to modify. You can selectively override the disk, directory, filename, or file extension. For example, to override the disk unit, enter a new disk unit. File name of EMP volume 1 If you are using DDP and After-Image Journaling on a cluster-mounted database set, at least one of the running configurations must be specified as a clusterwide database set master. The node that is the database set master serves DDP requests from nodes that do not have this database set cluster-mounted (for example, nodes outside the cluster). The node that is the database set master also serves After-Image Journaling requests. If you use After-Image Journaling for any globals within any volume sets of this database set, one running configuration must be the database set master. NOTE: When a database set master is shut down, both DDP and Journaling is disabled for that database set if there is no other running configuration that has also been specified as a master for this database set. Therefore, ensure that at least one running configuration is a master for this database set at any given time. (continued on next page) 2-20 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility Is this configuration a database set master for EMP [Y OR N] ? *** Database set information updated If you wish to be able to mount additional database sets into this configuration while it is running, enter YES. Otherwise, enter NO. Note that you can still dismount and remount database sets mounted during startup even if you disable this option. However, the first mounted database set may never be dismounted. Include support for mountable database sets [Y OR N] ? Y Enter the number of volume sets you expect to be able to mount into this configuration while it is running. This question specifically refers to the number of volume sets and not database sets. The volume set count is required because the DSM startup procedure must preallocate space in the DSM shared memory for each volume set which may be mounted after the configuration starts. However, some types of database sets, such as a Transaction Processing Database Set, may be comprised of multiple volume sets. This number represents the number of volume sets you anticipate mounting in excess of those mounted during configuration startup. Maximum number of additional mountable volume sets <1> 2 Enter the maximum number of globals found on any of the volume sets that you intend to mount after the configuration starts. This value will be used to preallocate space in the DSM shared memory for fast global directory lookups. Attempts to mount volume sets will fail if the volume set contains a larger number of globals than the value entered here. Maximum number of globals supported on any mountable volume set <90> *** Mountable database set information updated (continued on next page) Managing DSM for OpenVMS Systems 2-21 Example 2-1 (Cont.) Running the ^CONFIG Utility Default After-Image Journaling characteristics are as follows: Journal buffer size in 1KB DSM blocks: 8 Journal Process message terminal: CENTRL Journal log file directory: the DSM environment manager's directory Enter YES if you want to change the defaults. Enter NO if you want to leave the defaults unchanged. Modify default After-Image Journaling characteristics [Y OR N] ? DSM provides Distributed Cache Protocol (DCP) support over TCP or Ethernet network. You can configure DSM as the high-speed database server for Caché clients. Enter 'Y' to configure DCP. Include distributed database support for DCP clients [Y or N] Y Will DCP link use UDP or Raw Ethernet [U OR E] ? >U Enter the local UDP port number > 7500 Enter a UIC as two octal numbers < 400 separated by a comma (e.g 1,4). A UIC specifies a GROUP,USER code and is used to determine global protection by comparing it to the UIC of the process trying to access the global. You may also assign a UIC to individual DSM UCI,VOLs, which will override this default. For no default enter 0,0. For no default privileges (default to world access only), enter a minus sign "-". Enter the maximum number of client nodes <8> ? Specify a positive integer number to allow the DCP server to be connected to a group of remote DCP clients. You should select an appropriate number so that any unused network buffers will not be allocated during configuration startup. Default UIC for global protection ? <0,0> Edit UICs for individual DSM UIC,VOLs ? Y Enter a DSM UCI,VOL which you want translated to a UIC for global protection. You may enter ^L to get a list of UCI,VOLs which already have a UIC translation, or a UCI,VOL preceded by a '-' to delete an entry (UCI,VOL uses configuration default UIC). Just press RETURN when done entering translations. (continued on next page) 2-22 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility DSM UCI,VOL to translate > LIB,AAA Enter the UIC (two octal numbers < 400 separated by a comma) to be used for global protection for this UCI,VOL> Enter 0,0 for no protection (user access for all processes). UIC to use > 100,100 DSM UCI,VOL to translate > *** DCP options updated DDP must be included in configurations with cluster-mounted database sets Enter a 3 character, uppercase alphabetic node name for this DDP node. Each configuration within a DDP network must a have unique node name. Each time a DSM configuration is started, this node name is incorporated into the configuration and used to identify this DSM node. The DDP node name is not related to names of any mounted volume set names. Therefore you can choose to use an existing volume set name as a node name. Enter a unique 3 character DDP node name > ERN If you would like to have DDP started when a DSM configuration is started, enter YES. You can always start up and shut down DDP interactively after DDP startup using the ^DDP Utility. Start DDP servers during configuration startup [Y OR N] ? DDP servers are DSM processes that are responsible for servicing DDP requests from remote users. Received requests are entered into a queue of requests received from all remote nodes. The idle servers service these requests in a FIFO order. (continued on next page) Managing DSM for OpenVMS Systems 2-23 Example 2-1 (Cont.) Running the ^CONFIG Utility By default, DSM starts up a minimum of 3 servers so that if one server is busy waiting for disk, other servers can continue to handle requests. You can determine the optimal number of servers for your configuration by starting several servers and observing their states during normal system operation. If one or more servers are primarily in the HIBERNATE state, it would be reasonable to reduce the number of servers you have configured. Enter the number of DDP servers to start ? <3> Enter YES if you want to have the DDP servers send circuit and status messages to the operator's console. Enter NO to disable this feature. DDP servers always send error messages to the operator's console regardless of how you answer this question. Send DDP status messages to the operator's console [Y OR N] ? DDP groups provide a mechanism to partition groups of DSM nodes into multiple independent DDP networks even though the nodes may reside on the same physical network. DDP connections are established only between nodes that belong to the same group. A node can belong to one or more groups. Each node on the network rejects connections to nodes that do not have a DDP group enabled in common with its own. Enter one or more groups to enable for this node. Enter each group number to enable separated by a comma. Group numbers must be in the range from 0 to 15. Enter DDP GROUPS to enable <0> (continued on next page) 2-24 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility DDP incorporates a request retry mechanism to recover from instances where a DDP request is not answered by the remote node. The request is resent every 30 seconds until the request is answered, or the request retry maximum is exceeded. In these cases DSM signals a %DSM-E-DDPTIMO error to the application. You can choose to increase the retry maximum if your application needs to survive longer periods of DDP link unavailability. You can set the value to 0 to force DDP to retry endlessly. The value cannot exceed 255. Enter the REQUEST RETRY MAXIMUM <4> The request retry interval is the time DDP waits for a response to a DDP request. When the request retry interval expires, DDP resends the DDP request unless the request retry maximum has been exceeded. The request retry interval specifies 10 second time intervals. This value cannot be 0 and must be less than 255. Increase this value in environments that have very slow servers or fragile communications links. Enter the REQUEST RETRY INTERVAL <3> The request credit maximum is used for buffer flow control of DDP receive buffers. This value is sent to remote DDP nodes and specifies the maximum number of unanswered DDP requests that the remote node may have outstanding to this node at any one time. Increasing the maximum can improve performance of the remote node by allowing more efficient request generation and transmission. However, the local node is forced to allocate sufficient memory to buffer the incoming requests. This value cannot exceed 255, and cannot be less than 5. Enter the REQUEST CREDIT MAXIMUM <20> (continued on next page) Managing DSM for OpenVMS Systems 2-25 Example 2-1 (Cont.) Running the ^CONFIG Utility DDP servers periodically send control messages to all remote DDP nodes to communicate status information. These messages are known as multicast advertising messages. When circuits are created, the connecting DDP nodes exchange their advertising intervals with each other. Each node then knows when to expect the next multicast advertisement. If the advertisement does not occur when expected, DDP autoconfigure prints the error condition on the operator's console, deletes the timed out circuit, and releases all DSM locks outstanding from remote nodes. Enter the multicast advertising interval to use for this node. Each increment is equivalent to 10 seconds. You cannot exceed 255 increments. You may want to disable multicast advertising in environments where you do not want the DDP circuit timeouts to be detected and the circuit to be deleted. Enter a 0 to disable multicast advertisement. Enter the DDP MULTICAST ADVERTISING INTERVAL <6> DDP circuit connection security allows you to control which remote nodes on the network are allowed to connect to this node. Control is enforced by using DDP node passwords. Each incoming connection request is required to supply its node specific password. This password is checked against a database of node passwords that you have established using the ^DDPSEC Utility. If the password agrees, the connection is established. If the password is not correct, the connection request is rejected. Include CIRCUIT CONNECTION SECURITY [Y OR N] ? A DDP link provides a communications channel to one or more remote DDP nodes. DSM supports three types of links, Ethernet NULL, and DECnet. Enter the number of links that will be used in DDP communications. Count one link for each DECnet channel to configure and one link for each Ethernet controller that will be used. (continued on next page) 2-26 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility Note that the NULL link that is used for DDP communications between DSM configurations running on the same CPU, is always created. If you do not want to use Ethernet or DECnet links, answer 0 to this question and only the NULL link is created. Enter the number of DDP links in this configuration > 1 DSM supports three types of links, Ethernet, DECnet and TCP/IP. DSM Ethernet DDP is a dedicated, efficient communications protocol that can be used between any DSM-11, DSM for OpenVMS, or DSM for OSF/1 node connected via a common Ethernet link. It requires that the DSM Ethernet DDP driver be installed using OpenVMS SYSGEN, prior to configuration startup. DECnet DDP uses the DSM DDP protocol layered on a DECnet communications channel. DDP communications of this type can occur via any pathway that DECnet communication is possible. DECnet communications, while flexible, can incur costly system overhead, and cannot communicate to DSM-11. TCP/IP DDP uses the DSM DDP protocol layered on DEC TCP/IP Services for OpenVMS. Each system must have TCP/IP installed for communication to take place. It requires that the UCX SET SERVICE command be executed prior to configuration startup. Enter E to configure an Ethernet type link. Enter D to configure a DECnet type link. Enter T to configure a TCP/IP type link. Press to continue: Will link #1 use Ethernet, DECnet or TCP/IP [E, D OR T] ? > E (continued on next page) Managing DSM for OpenVMS Systems 2-27 Example 2-1 (Cont.) Running the ^CONFIG Utility Enter the device name of the Ethernet controller that you want to use for DDP communications. For example: XEA: XQA: ETA: ESA: EZA: EXA: EFA: FXA: ECA: ERA: Enter the Ethernet device to be used for link #1 > EMP: *** DDP configuration updated Default global characteristics are applied to all newly created globals on a configuration-wide basis. While these are the default characteristics, you can still create globals with different characteristics using the ^%GLOMAN Utility. Enter YES if you want to modify this configurations default global characteristics. Enter NO if you do not want to modify the default global characteristics. Modify GLOBAL characteristics [Y OR N] ? Mapped routines is a facility that allows you to lock a set of DSM application routines into virtual memory. These routines are mapped and referenced by applications' users, thereby reducing the system overhead that is usually required to load a disk resident copy of a routine into a user's process space. Mapped routine sets must first be created with the ^RMBLD Utility. Once created, you can use this utility to name those routine sets you want to have installed in memory during the startup procedure. Enter YES to include mapped routine sets. Enter NO if you do not want to include mapped routine sets. Include support for mapped routines [Y OR N] ? (continued on next page) 2-28 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility The DSM command accepts command line qualifiers that are used to define a specific DSM environment. The following are the command line qualifiers that you can modify: /BYPASS /ROUTINES=[UCI,VOL] /[NO]CENABLE /SOURCE_BUFFER_SIZE=n /EXTENSION=(keyword[,...]) /STACK_SIZE=n /LOCAL_DATA_SIZE=n /SYMBOL_TABLE_SIZE=n /[NO]MAPPED /TERMINAL_BUFFER_SIZE=n /[NO]PACK /[NO]TYPEAHEAD /[NO]PASSALL /UCI=name /PROMPT="string" /VOLUME_SET_NAME=name Enter YES if you want to modify the values of the default command line qualifiers for this configuration. Enter NO if you do not want to modify these values. Modify DSM default command line qualifiers [Y OR N] ? The global translation tables provide a flexible way to logically force global references to occur in a nondefault DSM directory (UCI,VOL). It provides transparent access to globals between DSM directories on any DSM for OpenVMS, DSM for OSF/1, or DSM-11 system, local or remote (using DDP). Modify Default Global Translation Tables [Y OR N] ? No default translation table defined for this configuration. Enter the translation table name to load at startup >TEST Default translation table for configuration NEW1 is now TEST Do you want to edit this translation table now [Y OR N] ? Do you want to edit this translation table now [Y OR N] ? If you choose to edit the translation table, ^CONFIG leads you through an interactive dialog identical to the one you follow when you use the TRANSLATION TABLE MANAGEMENT utilites, an option on the SYSTEM UTILITIES (^SYS) menu. See the DSM for OpenVMS Database Operations Guide for more information about how to manage global translation tables. (continued on next page) Managing DSM for OpenVMS Systems 2-29 Example 2-1 (Cont.) Running the ^CONFIG Utility If you choose to modify the global translation tables, ^CONFIG also asks if you want to modify volume set aliasing: Modify Volume set aliases for this configuration [Y OR N] ? To enhance the capability of using the same translation tables for multiple configurations in a cluster, DSM for OpenVMS allows you to implement volume set aliasing for individual configurations. Volume set aliasing allows the substitution of a local volume set name for a specific volume set name found in a translation table (thereby making a translation table used by multiple configurations equally applicable to all). This would typically be used to configure a local volume set for "scratch" globals. If you choose to modify volume aliases, ^CONFIG leads you through a dialog like that for SET VOLUME ALIAS (^CONVA), an option of the MODIFY EXISTING CONFIGURATION menu selection of ^CONMAN. See the DSM for OpenVMS Database Operations Guide for more information about SET VOLUME ALIAS. ^CONFIG continues. This option allows you to specify offsets for $HOROLOG in a DSM configuration. These offsets are added to the actual $HOROLOG when you use the $H special variable. For example, if the actual $H is 55000,56000 and you specify day offset 20 (or time offset 20) to the configuration, the returned $H value is 55020,56000 (or 55000,56020). Enter YES to specify $H offsets for the configuration or enter NO to continue. Modify $H date for this configuration [Y OR N] ? (continued on next page) 2-30 Managing DSM for OpenVMS Systems Example 2-1 (Cont.) Running the ^CONFIG Utility Disable process deletion by STOP/ID [Y OR N] > ? Enter YES to disable deletion of DSM processes with STOP/ID. Enter NO to enable deletion of DSM processes with STOP/ID. Disable process deletion by STOP/ID [Y OR N] > ERIN is the default configuration on node ERIN *** Configuration ERIN defined Enter YES to produce a comprehensive report on memory usage and suggested OpenVMS tuning parameters. The reports are generated by the ^MEMREQ Utility. The ^MEMREQ Utility uses the configuration data supplied to determine which SYSGEN parameters must be modified. It then displays the appropriate modifications. It also suggests process working set sizes and quotas for users of this configuration. Show configuration memory requirements [Y OR N] ? Enter YES if you want to start DSM with all of the options you have specified for this configuration. If you need to modify SYSGEN parameters, it is best to answer NO here, make the necessary modifications and reboot your system. You can then log back in to DSM and run the ^STU Utility to start the configuration. Startup configuration ERIN [Y OR N] ? Answer NO to this question to disable user logins into DSM after startup completes. Only users logging into DSM with the /MANAGER DSM command line qualifier will be allowed access to the running configuration. All other users will receive the "DSM logins are currently disabled" message. Enable user logins on startup [Y OR N] ? (continued on next page) Managing DSM for OpenVMS Systems 2-31 Example 2-1 (Cont.) Running the ^CONFIG Utility The configuration is now started, and DSM displays the following: Starting DSM configuration ERIN Initializing DSM environment for DSMMGR ... 3417 pages mapped DSM Write Demon ... Started as DSM_DEMON_1 (PID = 276000A8) DSM Garbage Collector ... Started as DSM_GARCOL_1 (PID = 276000A9) Volume set EMP ... mounted as "S0" $1$DKA0:[DSMMGR.DATABASE]EMPVOL1.GLS;1 (25 maps) $1$DKA0:[DSMMGR.JOURNAL]DSMEMP.BIJ;1 (25 maps) DSM Recovery process ... Started as DSM_RECOVER_1 (PID = 276000AA) DSM Journal process ... Started as DSM_JRNL_1 (PID = 276000AB) Starting DDP servers ... DDP server started as DSM_DDP01_1 (PID=276000AC) DDP server started as DSM_DDP02_1 (PID=276000AD) DDP server started as DSM_DDP03_1 (PID=276000AE) DDP startup completed DSM startup complete: User logins - enabled DDP services - enabled 2-32 Managing DSM for OpenVMS Systems Starting Up and Shutting Down Configurations After a DSM configuration is defined, you can interac- tively start it and shut it down. The following sections describe how to start up and shut down a configuration. Starting a Configuration To start up DSM interactively, log in to the DSM environment manager's account. Then run DSM with the /MANAGER command line qualifier and run the Configuration Startup Utility (^STU). For example: $ DSM/MANAGER DSM for OpenVMS Alpha V7.1 DSMMGR [Baseline] >D ^STU DSM Configuration Startup Enter the configuration identifier Enable user logins on startup [Y OR N] ? . . . If you do not enable user logins on startup and DDP is enabled for the configuration, the following question appears: Enable servicing of incoming DDP global requests [Y OR N] ? Y This gives you the option to enable or disable DDP global request servicing. ________________________Note ________________________ You cannot start configurations interactively while logged in to an alternate environment manager's account. _____________________________________________________ Managing DSM for OpenVMS Systems 2-33 You can also configure your system to start a configu- ration automatically at OpenVMS system boot time. The SYS$STARTUP:DSM$INSTALL_SITE.COM procedure is supplied as a template for DSM activities required at system startup. You can customize this procedure for your site. The relevant portions for configuration startup in this file accomplish the following tasks: o Creates the DSM$BATCH batch queue where the DSM startup procedure runs o Submits the SYS$STARTUP:DSM$STARTUP.COM procedure to DSM$BATCH to start a configuration To set up automatic configuration startup, locate and edit the portion of this file that starts the OpenVMS Queue Manager and creates the DSM$BATCH queue. You can remove the comment characters (!) from the following command lines to create and start a local batch queue: $ START/QUEUE/MAN $ NODE = "''F$EDIT(F$GETSYI("SCSNODE"),"COLLAPSE,TRIM,UPCASE")'" $ IF NODE .EQS. "" THEN QUEUE = "DSM$BATCH" $ IF NODE .NES. "" THEN QUEUE = "DSM$BATCH_''NODE'" $ INIT/QUEUE/BATCH/START/JOB_LIMIT=1 'QUEUE In a single-node configuration, the name of the queue created is DSM$BATCH. In a VMScluster environment, the name of the queue is in the following form: DSM$BATCH_nnn where: nnn is the local node's SCSNODE name Next, locate and edit the example commands that submit the procedure to start a configuration: SYS$STARTUP:DSM$STARTUP.COM. For each configuration you want to start: 1. Copy the example commands 2. Remove the comment character (!) 3. Edit the following fields to specify the configuration name and DSM manager's account name. 2-34 Managing DSM for OpenVMS Systems $ SUBMIT/USER=uuu/PARAMETER=ppp/QUEUE='QUEUE SYS$STARTUP:DSM$STARTUP Managing DSM for OpenVMS Systems 2-35 where: uuu is the environment name (DSM manager's account name) ppp is a three-piece parameter list delimited by a comma in the form: conf,login,ddpinh where: conf is the configuration name to start (if not supplied, the default configuration is started) login is DISABLE to disable user logins and ENABLE to enable user logins (if not supplied, user logins are enabled on startup) ddpinh is DISABLE to inhibit DDP global request servicing and ENABLE to allow global request servicing For each initialized environment, substitute the appropriate environment name for the DSM manager's account and supply the name of the configuration to start. Ensure that the DSM$INSTALL command procedure is called during system startup by inserting the following command in your site-specific startup file: $ @SYS$STARTUP:DSM$INSTALL If you do not specify a configuration name when you invoke or submit the SYS$STARTUP:DSM$STARTUP.COM procedure, the default configuration for the environment is started. The default configuration is designated when you run the ^CONFIG Utility. Shutting Down a Configuration You can shut down a DSM configuration interactively by running DSM with the /MANAGER command line qualifier. Then use the ^SHUTDWN Utility to stop all DSM user processes and complete an orderly shutdown of the DSM Write Demon and Garbage Collector. The ^SHUTDWN Utility also removes routine mapped sections and deletes DSM system logical names. Configurations can be shut down by alternate manager accounts or by other OpenVMS users with the SYSPRV privilege. For example: 2-36 Managing DSM for OpenVMS Systems $ DSM/MANAGER/ENVIRONMENT=DSMMGR DSM for OpenVMS Alpha V7.1 DSMMGR [MGR,DAS] >D ^SHUTDWN Processes in DSM Environment DSMMGR on 24-SEP-1997 15:47 PID Process Name State Device UCI,VOL Routine Cmds Refs DIO Login 24600390 DSMMGR LEF RTA9 APL,DAS 228164 38377 3700 10:12 24600120 DSM_GARCOL_42 HIB 8 15:35 2460011F DSM_DEMON_42 HIB 3834 15:35 Continue with shutdown ? (Y/N) > Y . . . You can also use the SYS$MANAGER:DSM$SHUTDOWN.COM procedure to shut down a configuration noninteractively. For more information about system shutdown, see the section "The DSM Shutdown Command Procedure" in Chapter 1. Affects of Abnormal Image Termination Abnormal termination of a process running DSM can cause the corresponding DSM environment to hang. This abnormal termination can be caused by: o Deleting a DSM process using the DCL command STOP/ID or STOP processname ________________________Note ________________________ Using the DCL STOP/ID command to stop DSM user or system processes can cause all other users accessing the same DSM volume set to hang, and can cause database degradation. Instead, use the DSM ^FORCEX Utility, which runs down a DSM user safely. For more information about how to use this utility, see Chapter 7. _____________________________________________________ o Deleting a batch queue in which a DSM process is running Managing DSM for OpenVMS Systems 2-37 o Logging out of a parent process that has a subprocess running DSM When DSM detects such an abnormal termination, it displays the following message on the operator console and records it in the operator log file: *** DSM Abnormal Process Termination *** Process with PID 20200244 deleted while in critical region If the process termination could possibly cause the DSM environment to hang, then the environment is immediately terminated instead. In this case, the following message is also displayed on the operator console: *** DSM Configuration Rundown *** Process with PID 20200244 forcing configuration rundown All other processes running that environment run down with the following error: %DSM-F-DEMONABORT, Local write demon exited Note that when an environment is terminated in this way, it is in danger of hanging and has to be terminated in any case. Modifying Characteristics of a Configuration When you initially created the DSM environment manager account, the SYS$MANAGER:DSM$INIT.COM procedure set the minimal account limits, quotas, and privileges necessary to run limited DSM configurations. As you modify your operating environment and configuration characteristics, you will need to adjust these values. The following list describes the recommended technique for setting up a DSM configuration that has all the capabilities you require. 1. Use the ^CONFIG Utility to establish a new configura- tion, including the new options or values. 2. Use the ^MEMREQ Utility to determine which OpenVMS SYSGEN parameters and account quotas need to be adjusted. 2-38 Managing DSM for OpenVMS Systems 3. Establish any new OpenVMS system or DSM environment manager account resources required for the planned configuration. Chapter 5 describes these resources, including account quotas for the DSM environment manager account and parameters set during OpenVMS SYSGEN. 4. Run AUTOGEN with the reboot option if you have modified any SYSGEN parameters. 5. Run DSM again, and start the configuration using the ^STU Utility. Treat configuration building as an iterative process; establish new capabilities or resources a few at a time, test the new configuration, then add new capabilities. This approach ensures that you understand and control the effects of the changes that you make to your DSM configuration. Running Multiple DSM Configurations You can run multiple DSM configurations at the same time on a OpenVMS system: one configuration for each DSM environment. To set up a configuration for an environment, initialize a DSM environment manager's account for each environment by logging in to a privileged OpenVMS system account and running the SYS$MANAGER:DSM$INIT.COM procedure. Chapter 1 describes this procedure. Environmental Identifiers and Names Each time you initialize a new DSM environment, the manager account is given a unique environment identifier and environment name. The environment identifier is an integer number that is used to form OpenVMS resource names that are associated with the environment and used internally by DSM. The environment name is a system-wide unique name that is equivalent to the DSM manager's account name. The environment name is used by application users and programmers to access a configuration running in an environment. Managing DSM for OpenVMS Systems 2-39 DSM$ID and DSM$DEFAULT When you define and start a configuration in an environ- ment, two system logical names are created: o DSM$ID_envnm The symbol envnm represents an environment name. Configuration startup equates the DSM$ID_envnm system logical name to the unique environment identifier. This value should never be redefined. o DSM$DEFAULT_envnm The symbol envnm represents an environment name. DSM$DEFAULT_envnm holds the default command line qualifiers for the environment specified by envnm. The default command line qualifiers are derived from the values you selected while running the ^CONFIG Utility. The defaults specify information such as the login UCI and volume set and default source buffer and symbol table sizes. You can override the defaults by appending explicit values when you enter the DSM command line. Selecting the Environment To Access Use the /ENVIRONMENT=envnm command line qualifier to select the environment that you want to access. For example, any user can gain access to the running configuration in the environment PRODUCTION by entering the following DSM command line: $ DSM/ENVIRONMENT=PRODUCTION DSM for OpenVMS Alpha V7.1 PRODUCTION [WRK,VBA] > As you can see, the DSM banner displays the environment selected along with the login UCI and volume set. 2-40 Managing DSM for OpenVMS Systems Setting a Default Environment When the DSM manager for environment PRODUCTION logs in to DSM without the /ENVIRONMENT=envnm command line qualifier, DSM attempts to access the current configuration running from the manager's account environment. $ DSM DSM for OpenVMS Alpha V7.1 PRODUCTION [WRK,VBA] > You can override this action by defining the DSM$ENVIRONMENT logical name to be equivalent to a default environment name. When you omit the /ENVIRONMENT=envnm command line qualifier, DSM attempts to translate DSM$ENVIRONMENT from the process, group, or system logical name tables to determine the target environment. If the name exists, DSM uses the equivalence of DSM$ENVIRONMENT for selecting the environment to access. If DSM$ENVIRONMENT is not defined, DSM attempts to log you in to the configuration running in your environment. If you access multiple environments from your account, you can define the DSM$DEFAULT_envnm logical name to select login defaults that are specific to the configurations running in each of the environments. For example, consider a situation in which two envi- ronments named PRODUCTION and DEVELOPMENT run separate configurations on the same OpenVMS system. You can set up different defaults for selecting the UCI and volume set to log in to when each environment is accessed. To define the defaults to access UCI WRK and volume set PRD in the PRODUCTION environment, enter the following: $ DEFINE/PROCESS DSM$DEFAULT_PRODUCTION "/UCI=WRK/VOL=PRD" $ DSM/ENVIRONMENT=PRODUCTION DSM for OpenVMS Alpha V7.1 PRODUCTION [WRK,PRD] > Managing DSM for OpenVMS Systems 2-41 To define the defaults to access UCI ARD and volume set DEV for the DEVELOPMENT environment, enter the following: $ DEFINE/PROCESS DSM$DEFAULT_DEVELOPMENT "/UCI=ARD/VOL=DEV" $ DSM/ENVIRONMENT=DEVELOPMENT DSM for OpenVMS Alpha V7.1 DEVELOPMENT [ARD,DEV] > The ^DSMMGR RMS global holds the database for all initialized DSM environment accounts on a OpenVMS system. By default, DSM searches the SYS$COMMON:[SYSLIB] directory for ^DSMMGR when utilities require environment information. The GETGRP^%SYSROU Utility performs this function. Because environment IDs are required to be unique, you can maintain only one active copy of ^DSMMGR. Initializing DSM in a VMScluster Environment Each DSM environment can extend over several processors joined in a VMScluster configuration. The process of initializing a DSM manager account for use within a VMScluster environment is similar to that used for a single-node system. You use the SYS$MANAGER:DSM$INIT.COM procedure to initialize a DSM environment for clusterwide use. You can run the DSM$INIT procedure while logged in to a privileged account on any node within the cluster. DSM$INIT creates the environment directories and applies the default protections as described in the section "Environment Directories, Files, and Protection." DSM$INIT also creates a separate directory for each cluster node as a subdirectory of the environment root directory. After the manager account is initialized, you can define and start DSM configurations on each VMScluster node. You can create a common set of DSM database sets and have all nodes share them simultaneously. 2-42 Managing DSM for OpenVMS Systems Directory Structure in a VMScluster Environment In a single-node configuration, the DSM environment root directory holds log files created by the DSM system processes such as the Write Demon and Garbage Collector. In a VMScluster environment, each node separately runs a DSM configuration. The cluster node subdirectories hold the log and error files generated by the DSM processes running on each of the nodes. In a cluster, the environment root directory still holds ^SYS, the configuration global, ^DSMACC, the configuration access global, and the routine map files. Placement of these files in the root directory allows them to be commonly accessible from all nodes in the cluster. Figure 2-2 shows an example of the VMScluster directory hierarchy. The directories created by DSM$INIT for the account DSMMGR are located on a cluster consisting of nodes ZORBA, CASEY, and WELBY. In Figure 2-2: o The DISK$USER:[DSMMGR.ZORBA] directory holds the error and log files for DSM processes running on VMScluster node ZORBA. o The DISK$USER:[DSMMGR.CASEY] directory holds the error and log files for DSM processes running on node CASEY. o The DISK$USER:[DSMMGR.WELBY] directory holds the error and log files for DSM processes running on node WELBY. o The environment root directory, DISK$USER:[DSMMGR], holds routine map files and any RMS globals or routine directories used by all three nodes. o The root directory contains the RMS global, SYS.GBL, which contains the configuration definitions created (using ^CONFIG) for all nodes of the cluster. o The DSM security global, DSMACC.GBL, holds user access information for all nodes of the cluster and also resides in the root directory. o The DISK$USER:[DSMMGR.JOURNAL] directory is the default storage location for after-image journal or before- image journal files. Managing DSM for OpenVMS Systems 2-43 o The DISK$USER:[DSMMGR.DATABASE] directory is used as the default storage location for DSM volume sets. When you run DSM$INIT in a VMScluster environment, the following question appears so DSM$INIT can correctly define the appropriate subdirectories: . . . Use of DSM in a VMScluster environment requires the creation of a separate subdirectory for each cluster member. The subdirectories hold node-specific log files created by DSM configurations running on each of the VMScluster nodes. Appropriate subdirectories will be created as part of this initialization process. To do so, all cluster nodes must be identified at this time. The following VMScluster nodes are currently booted and will be initialized for use with DSM: CASEY ZORBA Are there any additional cluster members not currently booted that you would like to add to this list [Y OR N] ? . . . DSM$INIT attempts to identify all nodes configured. However, nodes that are not booted at the time you run DSM$INIT do not appear in the list of recognized nodes. If you need to identify additional nodes, answer YES to the last question in the previous example then supply the additional node names. ________________________Note ________________________ If you add nodes to your cluster, you must run DSM$INIT again for all defined DSM environment manager accounts. This ensures that the proper subdirectories are created for the new node and the appropriate DSM management globals are updated. _____________________________________________________ 2-44 Managing DSM for OpenVMS Systems Defining VMScluster Configurations If you are running DSM in a VMScluster environment, you must create a separate configuration for each VMScluster node that is going to use DSM. However, the configurations can mount common DSM database sets so that DSM volume sets are accessible and shared across the cluster. Mastering a Cluster-Mounted Database Set When you mount a DSM database set for clusterwide access, the ^CONFIG Utility asks you whether the configuration is going to master the database set. You can designate one or more cluster members to master a database set. Database set masters provide DDP and After-Image Journaling services to all nodes inside and outside the cluster. Only one master actively serves the database set at any time. However, when a database set master is shut down or fails, a database set master on another cluster node becomes the active master. For these reasons, configure more than one node as a database set master for each of the database sets that are included. While the overhead required to actively master a database set is not substantial, choose cluster members with the most available system resources. Enabling DDP in a VMScluster Environment You must also enable DDP when you include clusterwide database sets. When configuring DDP, you must select a unique 3-character DDP node name for each running configuration. See the DSM for OpenVMS Database Operations Guide for information about how to use DDP in a VMScluster environment. The DSM for OpenVMS Database Operations Guide contains information about how to use and optimize cluster-mounted volume sets. It also contains information about how DSM journaling is implemented in a VMScluster environment. Become familiar with the information in the VMScluster Systems for OpenVMS before you attempt to run DSM in a VMScluster environment. Managing DSM for OpenVMS Systems 2-45 Checking System Volume Set Mounting across a Cluster When cluster mounting a system volume set (S0) at configuration start up, DSM determines whether all configurations running in the same environment on the cluster are using the same cluster-mounted system volume set (S0). If all other configurations in the cluster are running with the same cluster-mounted system volume set, DSM proceeds with startup. If another configuration is running with a different cluster-mounted system volume set (S0), DSM returns a DSM-E-GLSNOTS0 error message. DSM does not permit the current configuration to start. If the specified system volume set is mounted as a non-system volume set on another node, DSM returns a DSM-E-GLSALRMNT error message. DSM does not permit the configuration to start. DSM does not perform this check if it finds a system volume set mounted locally. DSM starts the configuration even if a node in the cluster has a different system volume set (S0) mounted locally. Running DSM in a Heterogeneous VMScluster Environment You can run DSM configurations in a heterogeneous VMScluster environment. The cluster can consist of any combination of VAX CPUs and Alpha CPUs. You must take care to set up the following correctly for use with DSM: o Master configuration global, ^DSMMGR o SYSUAF.DAT o RIGHTSLIST.DAT ^DSMMGR If you are running DSM in a heterogeneous VMScluster environment, multiple system disks are configured and each disk holds its own copy of the DSM master configuration global, ^DSMMGR. However, you can maintain only one active copy of ^DSMMGR. 2-46 Managing DSM for OpenVMS Systems You do this by: 1. Choosing the location and copy of ^DSMMGR that you will use throughout the cluster as the active copy of ^DSMMGR 2. Using the DSM$LIBRARY logical name to direct all DSM utility functions to that copy. You must define DSM$LIBRARY to be the same value on all nodes of the heterogeneous cluster. To define DSM$LIBRARY, remove the comment character (!) from the following line in SYS$STARTUP:DSM$INSTALL_ SITE.COM: $ DEFINE/SYSTEM/EXEC DSM$LIBRARY ddcu:[VMS$COMMON.SYSLIB] where: ddcu is the cluster system disk that holds the unique reference copy of DSMMGR.GBL. (This disk should be the same for all VMScluster nodes.) SYSUAF.DAT and RIGHTSLIST.DAT The configuration of a mixed architecture cluster requires separate system disks for the OpenVMS VAX and OpenVMS Alpha operating systems. Therefore, the VMScluster system could potentially be configured to use separate SYSUAF.DAT and RIGHTSLIST.DAT files. In a DSM environment, InterSystems recommends that you use a single copy of SYSUAF.DAT and RIGHTSLIST.DAT for the entire cluster. You can do this by assigning the RIGHTSLIST and SYSUAF system logical names to a commonly accessible disk within the cluster. For example, the OpenVMS startup files for each system could contain the following definitions: $ DEFINE/SYSTEM/EXECUTIVE SYSUAF ddcu:[SYSEXE]SYSUAF.DAT $ DEFINE/SYSTEM/EXECUTIVE RIGHTSLIST ddcu:[SYSEXE]RIGHTSLIST.DAT where: ddcu is the disk device that is commonly accessible by all nodes in the cluster Managing DSM for OpenVMS Systems 2-47 DSM Detached Processes When you start up a DSM configuration, DSM creates the following OpenVMS detached processes. o Write Demon (writes global data changes into the database) o Garbage Collector (reclaims disk space freed as a result of a global KILL operation) o Journal Process (records all SET and KILL operations, manages DSM transactions) o Recovery Process (starts an automatic recovery of the database) o Three or more DDP servers (directs communication to and from other DSM systems and allows access to remote system globals) o One or more DDP DECnet[TM] link servers (controls DECnet links to remote DSM configurations) The Write Demon and Garbage Collector always start when you start up a configuration. The Recovery Process starts only when you enable Before-Image Journaling for a database set. The Journal Process starts when you select After-Image Journaling for a database set included in the configuration. If you have enabled DDP, you can define DDP servers and DDP link servers to start during configuration startup or interactively at a later time using the ^DDP Utility. ________________________Note ________________________ Remember that each of these processes is counted as a DSM user. _____________________________________________________ The following sections describe these detached processes in more detail. Also, for additional information about these processes, see the DSM for OpenVMS Database Operations Guide. 2-48 Managing DSM for OpenVMS Systems Write Demon The Write Demon is a OpenVMS process that you must start before any DSM user can access globals or routines residing on DSM volume sets. The Write Demon creates and initializes a virtual memory section to the DSM shared data, including the disk buffers to hold global data for deferred writing to volumes. It then performs all writes to the volume using the data accumulated in the disk buffers. When the Write Demon starts, DSM creates a log file called DSMDEMON.LOG in the log file directory that is created when you run the procedure: SYS$MANAGER:DSM$INIT.COM. This file receives any errors generated by the Write Demon. Consult DSMDEMON.LOG if DSM startup fails because of a Write Demon initialization error. If the configuration being started contains any cluster- mounted volume sets or any volume sets for which Before- Image Journaling is active, this process resolves cross- node contention for common data blocks and controls access to the before-image journal file for each volume set. You can print or type the Write Demon log file while the Write Demon is running. The Write Demon logs occurrences of unrecoverable disk write errors and displays them on the operator console device. Garbage Collector The Garbage Collector is a OpenVMS process that you start when establishing DSM volume sets. The Garbage Collector deallocates blocks removed from the global structure by a kill of a large global subtree. It also drives periodic checkpointing of volume sets that have Before-Image Journaling enabled. When the Garbage Collector starts up, DSM creates a log file called DSMGARCOL.LOG in the log file directory that was created when the SYS$MANAGER:DSM$INIT.COM procedure was run. This file records error information about the Garbage Collector process. You can print or type the Garbage Collector's log file while the Garbage Collector is running. Managing DSM for OpenVMS Systems 2-49 Journal Process After-Image Journaling provides a way to keep a record of the SET and KILL commands that a DSM application performs on the global database. You can enable journaling for an application by selecting the appropriate startup options in ^CONFIG and starts up the configuration. You can then enable journaling on a global-by-global basis. As DSM manager, you can interact with the Journal Process during a DSM session to control journaling operations. You use the the Journal Process Utilities described in the DSM For OpenVMS Database Operations Guide. Recovery Process DSM starts the Recovery Process whenever you have a database set in your configuration that has Before- Image Journaling enabled. The Recovery Process performs automatic recovery whenever DSM restarts after a system or VMScluster node failure. If transaction database sets are configured, the Recovery Process is also responsible for recovery from a transaction abort. In some configurations, the Recovery Process can be started to perform a single recovery operation and can then be terminated. DDP Servers A DDP server is a OpenVMS process that manages the communications link between your DSM application and other DSM systems or applications. The DSM manager can select the number of DDP servers to start. The minimum number of DDP servers is three. 2-50 Managing DSM for OpenVMS Systems 3 ________________________________________________________________ Controlling Access to DSM This chapter provides information about the security capabilities available in DSM. It provides an overview of the different levels of access to DSM environments and a detailed discussion of how you can control access to DSM and your application. It also describes how to create application and programmer accounts. The information in this chapter describes standard application-level security procedures. If your security procedures need to meet the United States Department of Defense C2 security rating or its equivalent, see Chapter 4. Controlling User Access DSM can allow any OpenVMS user to directly access a configuration running in a DSM environment on the local system using the /ENVIRONMENT=envnm command line qualifier. This capability, along with the ability to run multiple configurations concurrently, provides flexibility when designing an application system. However, the DSM environment manager must also restrict users' access to various components of the application system to protect the database from unauthorized access. The modes of access and the access restrictions required vary greatly from one installation to another. Two models of application environments are common in DSM systems: o Dedicated application systems The dedicated application system views the underlying operating system as a support platform with the sole purpose of serving the M application. The application designer uses the components supplied by the system to construct a turnkey system. Access to the system is controlled from the point at which the user presses Controlling Access to DSM 3-1 Return to the point at which the application program gets control. In this model, the use of captive terminals and captive accounts completely secures access to DSM. It is likely that all application users actually use the same OpenVMS account to access the application. The application program holds the responsibility for granting access to the database. Very little access control is usually placed on a programmer account. The programmer is usually granted a separate OpenVMS account with access to all UCIs, volume sets, and configurations. This approach presents only two levels of access authority: privileged programmers and unprivileged users. It is an adequate approach in controlled operational environments that do not require any direct user interaction with the OpenVMS operating system. o General-purpose time-sharing systems Time-sharing systems use the underlying operating system for a large variety of DSM and non-DSM services. In this model, most users have their own OpenVMS account with direct access to the DCL command prompt ($). The DSM application system may be only one of the resources that is used. The user community comprises both privileged programmers and unprivileged users. In this environment, the DSM application system still retains its control over how the application user accesses the database once the user is running DSM. However, the DSM manager must be able to precisely identify which OpenVMS users can log in to a running configuration, what modes of access are allowed, and which UCIs, volume sets, and routines are accessible. Also, OpenVMS files used by DSM for storing database and journal information have to be protected from unauthorized change. Solutions to controlling access in time-sharing systems must provide many levels of access authority that are OpenVMS account based. 3-2 Controlling Access to DSM You can use many techniques to support security for both of these application models. Your site requirements deter- mine the selection of the most appropriate configuration of DSM security features. Regardless of the techniques you choose, the security of a DSM database ultimately depends on controlling access at the following levels: o OpenVMS access control Authorization to log in to a OpenVMS system as a user o Environment access control Authorization to read or write to database volume set files, journal files, and other DSM environment files such as DSMACC.GBL and SYS.GBL o Configuration access control Authorization to log in to a UCI and volume set within a running configuration o Global access control Authorization to read or modify specific DSM globals from the login UCI Figure 3-1 illustrates the relationship between the different levels of access and some of the utilities that you can use to provide access control. The following sections describe configuration access control methods available in DSM. They describe the utilities provided by DSM and the system conventions you can use to construct access methods for either dedicated application or time-sharing systems. For information about global access control, see the DSM for OpenVMS Database Operations Guide. It provides detailed information about the protection levels available for DSM globals and the utilities you can use to establish protection on a global-by-global basis. The Digital Equipment Corporation publication, OpenVMS Guide to System Security, contains a useful overview of evaluating the security needs of a site. Refer to this document for detailed information about OpenVMS system security. Controlling Access to DSM 3-3 OpenVMS Access Control OpenVMS user accounts and passwords allow the OpenVMS system manager to establish which individuals can log in to a system and what rights and privileges they are granted. Users with sufficient privileges can perform system management functions and access any file on the system. You can create different types of accounts for different purposes: o You can create less-privileged accounts to allow access to the DCL command line interpreter so that the user can run programs and access private files (as well as unprotected public files). o You can configure Captive accounts to allow users to log in to the system with or without a required password. However, the captive users are tied to a login command procedure and are not allowed to execute any general functions outside this procedure. These accounts serve as dedicated application accounts and generally exist for the sole purpose of running a specific application. In a DSM environment, you can use captive accounts to tie application users directly to a DSM application. You can create unprivileged programming accounts to allow a DSM application developer to access DSM from the DCL command line. The programmers can select several DSM login options, UCIs, or volume sets, but they would not have sufficient privilege to access other OpenVMS files or protected services. For complete information about creating accounts, see the OpenVMS System Manager's Manual by Digital Equipment Corporation. 3-4 Controlling Access to DSM Environment Access Control Directories, files, and management functions are objects within a DSM environment that you must protect from unauthorized access. Files, such as the database volumes or after-image journal files are subject to inspection by OpenVMS users using general-purpose OpenVMS utilities and system calls. Users can use the DCL commands COPY or DELETE to manipulate these files or the OpenVMS Dump Utility to display the contents of volume sets. Protecting Environment Files The OpenVMS operating system offers two primary mechanisms for use in protecting access to objects such as files: o UIC-based protection This protection is based on the user identification code (UIC) of the manager account and is applied to all user-owned files. Access privileges are controlled according to SYSTEM, OWNER, GROUP, and WORLD categories. READ, WRITE, EXECUTE, and DELETE access can be specified for each category. o Identifiers and access control lists (ACLs) OpenVMS identifiers are records defined in the system rights database, SYS$SYSTEM:RIGHTSLIST.DAT. System managers create and grant identifiers to specific accounts using the OpenVMS Authorize Utility. When you grant an identifier to an account, the account is considered a holder of the identifier. ACLs are access control structures that you can associate with an object such as a file. ACLs consist of a list of entries, known as access control entries or ACEs. Several types of ACEs exist. An identifier ACE describes the access rights granted or denied to holders of the identifier. You can control which users can access an object by creating an identifier then granting it to a user. An ACL that includes the appropriate identifier ACE is then applied to the object. All holders of the identifier can then access the object. Controlling Access to DSM 3-5 When you initialize a new DSM environment, the DSM$INIT.COM procedure in SYS$MANAGER creates an unprivileged OpenVMS account that is used to manage DSM operations within the environment. UIC-based ownership protections are applied to all directories and files created. The following is the UIC protection scheme: SYSTEM: READ, WRITE, EXECUTE OWNER: READ, WRITE, EXECUTE GROUP: NO ACCESS WORLD: NO ACCESS This scheme allows only OpenVMS system managers and users with the same UIC access to DSM environment files. An identifier that is unique to the environment is also created in the rights database during environment initialization. The identifier is placed as an entry in ACLs that are associated with each of the files in the environment. This scheme allows holders of the identifier to access files within a DSM environment. The DSM environment manager account is always granted the manager identifier. The manager can use the DSM Access Control Utility (^ACL) to grant the identifier to other OpenVMS users and designate them as alternate environment managers. The name of the identifier is in the form: DSM$MANAGER_envnm where: envnm is the name of the DSM environment manager account The ACL placed on each of the environment directories also contains an access control entry known as a default protection ACE. The placement of the default protection ACE along with the identifier ACE causes the proper UIC- and identifier-based protections to be propagated to all files created within the directories. This ensures that newly created volume set and journal files receive proper access protection. 3-6 Controlling Access to DSM Maintaining Environment Security The security of a DSM environment depends on ensuring that all of the files and directories within the environment are properly protected. Use the following guidelines to ensure that the protections are sufficient: o Create all new volume sets and journal files within directories created by DSM$INIT. o Inspect the protection of newly created files using the DCL command DIRECTORY/SECURITY. o Apply appropriate ACLs and UIC-based protections on all directories or files when necessary. The DSM$INIT command procedure applies appropriate pro- tections to all directories and files in the environment. Directory protections are propagated to files created within the directories. It is a good idea to always create and locate new volume set files and journal files within properly initialized directories. If you move or restore files to an environment directory, inspect the applied protections to ensure they are correct. The security placed on a properly configured environment root directory for the DSMMGR environment is shown in the following example: $ DIRECTORY/SECURITY DISK$USER:[0,0]DSMMGR.DIR DSMMGR.DIR;1 [DSMMGR] (RWE,RWE,,) (DEFAULT_PROTECTION,SYSTEM:RWED,OWNER:RWED,GROUP:,WORLD:) (IDENTIFIER=DSM$MANAGER_DSMMGR,OPTIONS=DEFAULT,ACCESS=READ+WRITE+ EXECUTE+DELETE) (IDENTIFIER=DSM$MANAGER_DSMMGR,ACCESS=READ+WRITE+EXECUTE) The security placed on a properly configured environment file for the environment DSMMGR is shown in the following example: $ DIRECTORY/SECURITY DISK$USER:[DSMMGR]SYS.GBL Directory DISK$USER:[DSMMGR] SYS.GBL;1 [DSMMGR] (RWE,RWE,,) (IDENTIFIER=DSM$MANAGER_DSMMGR,ACCESS=READ+WRITE+EXECUTE) Controlling Access to DSM 3-7 Some DCL operations, such as the DCL command RENAME, may not apply directory level protections when a file is moved into the directory. In these cases, you can apply the correct UIC and identifier protections. The following example shows the commands used to establish the correct file protection for the DSMMGR environment in UIC [250,1]: $ RENAME DISK$USER:[DATABASE]AAAVOL1.GLS - DISK$USER:[DSMMGR.DATABASE]AAAVOL1.GLS $ SET ACL/LIKE=(OBJECT_NAME=DISK$USER:[DSMMGR]SYS.GBL) - DISK$USER:[DSMMGR.DATABASE]AAAVOL1.GLS $ SET FILE/PROTECTION=(O:RWE,S:RWE,G,W) - DISK$USER:[DSMMGR.DATABASE]AAAVOL1.GLS/OWNER=[250,1] Configuration Access Control You must control access to a configuration to prevent unauthorized OpenVMS users from running DSM management procedures or accessing protected globals. The objective of configuration access control is to restrict a user to specific access modes, UCIs, and volume sets. DSM Configuration Access Control System The ^CONFIG Utility lets you enable the DSM configuration access control system. The configuration access control system gives you complete control over access to a DSM configuration. You can give selected OpenVMS users controlled access to DSM. The DCL command DSM controls access. You do not have to set up captive application accounts or programmer accounts to limit user access to the operating system. The access control system is particularly suitable for a general- purpose time-sharing environment in which the entire community of OpenVMS users are potential DSM users. The configuration access control system provides three modes of access for users logging in to a configuration: o Manager mode o Programmer mode o Application mode 3-8 Controlling Access to DSM If you do not enable the configuration access control system, any OpenVMS user can access the configuration in programmer mode or application mode without restriction. (Manager mode access is always protected.) If you enable the configuration access control system, you can use the ^ACL Utility to grant programmer mode or application mode access to individual OpenVMS accounts. You can restrict programmer mode access to specific UCIs and can restrict application mode access to specific UCIs and application routines. The following sections describe the access modes and their associated privileges in more detail. Manager Mode Access Enter manager mode by running DSM with the /MANAGER command line qualifier: $ DSM/MANAGER DSM for OpenVMS VAX V7.1 DSMMGR [MGR,AAA] Manager mode allows you to interact directly with the DSM interpreter for the purposes of creating volume sets, configurations, and other DSM management functions. When you run DSM in manager mode, DSM enforces the following default options, regardless of any other options specified on the command line: o UCI 1 on volume set 0 is used for default globals and routine access o RMS library routines in SYS$LIBRARY:UTILITIES.DSM o RMS application routines in SYS$LIBRARY:MANAGER.DSM o RMS library globals in SYS$LIBRARY:*.GBL o /NOPACK/NOPASSALL o /NOMAPPED - disables mapping to routines in virtual memory sections o /NOTRANSACTION - disables transaction recovery unit processing Controlling Access to DSM 3-9 o A minimum value of interpreter defaults are used for the following qualifiers: /SYMBOL_TABLE_SIZE=102336 /STACK_SIZE=8192 /SOURCE_BUFFER_SIZE=40960 DSM associates specific privileges to users who run DSM with the /MANAGER command line qualifier. Manager mode gives you access to: o DSM management utilities in the MGR UCI o Unrestricted use of the VIEW command and $VIEW function o Privileged system-supplied external routines including %SETUCI o DSM /BYPASS command line qualifier Manager mode access is available to an account only if the account meets one of the following criteria: o Initialized as the environment manager account using the DSM$INIT procedure (environment manager has access to its own environment) o Designated as an alternate environment manager account using the ^ACL Utility (environment manager has access to the environment from which ^ACL was run) o A privileged OpenVMS account with the SYSPRV or BYPASS privileges (environment manager has access to all environments) ________________________Note ________________________ The restrictions to manager mode access apply even if you use ^CONFIG to disable the configuration access control system. _____________________________________________________ 3-10 Controlling Access to DSM Programmer Mode Access Enter programmer mode by running DSM without specifying a routine reference on the DSM command line: $ DSM/UCI=PHA/ENVIRONMENT=PERSONNEL DSM for OpenVMS VAX V7.1 PERSONNEL [PHA,EMP] If you specify a routine directory that is different from the global directory, it is displayed in the sign-on banner. For example: $ DSM/ROUTINE=REF,EMP/ENVIRONMENT=PERSONNEL DSM for OpenVMS VAX V7.1 PERSONNEL [PHA,EMP][REF,EMP] Programmer mode allows you to interact directly with the DSM interpreter. The privileged operations associated with programmer mode include: o Create, store, and run DSM routines interactively o Set or kill any global data accessible from the current UCI o Run DSM Library Utility routines o Access DSM library external call functions directly If you enable the configuration access control system, you use the ^ACL Utility to grant users access to specific UCIs and volume sets. When the access control system is enabled, programmer mode users do not have access to the following capabilities: o VIEW command and $VIEW function o %SETUCI external routine library function to non- authorized UCIs o DSM /BYPASS command line qualifier o MGR UCI o DSM privileged external routines (DSM external call package) Controlling Access to DSM 3-11 o Editing Library (%) Utilities DSM always allows the use of these capabilities while running a library (%) utility. Application Mode Access Enter application mode by specifying a routine name on the DSM command line. For example: $ DSM/UCI=APP/ENVIRONMENT=PERSONNEL ^APPL In application mode, the user is tied directly to the application routine that is specified on the command line. This predefined application routine controls the ability to read or modify the DSM database or change the current volume set or UCI. Therefore, the user's access to sensitive data is completely defined by the application programs. If you enable the configuration access control system, you use the ^ACL Utility to grant OpenVMS users access to specific UCIs, volume sets, and routines. Application users who do not also have programmer mode access to the login UCI are not allowed to escape from the application routine into programmer mode using the ZESCAPE command. Programmer Mode and Application Mode Restrictions DSM uses two privilege bit masks to determine which programmer mode and application mode restrictions should be enforced. The bit masks are stored in the ^SYS configuration global: o ^SYS(ID,"RESTRICTION MASK1") o ^SYS(ID,"RESTRICTION MASK2") where: ID is the configuration identifier name MASK1 specifies the capabilities that are not available to programmer mode and application mode users when the access control system is enabled. MASK2 specifies the capabilities that are not available to programmer mode and application mode users when the access control system is disabled. 3-12 Controlling Access to DSM All restricted capabilities are always available to users if the function is performed from a library (%) routine. Table 3-1 describes the bit representation of restricted capabilities and the system-supplied defaults for each mask. Note that a value of 1 means that the restriction is applied. Table_3-1_Bit_Representation_for_Masks____________________ Bit Position Restriction when Default Default /Value________Set_________________MASK1_______MASK2_______ 0/1 Library (%) 1 0 routine editing 1/2 Use of VIEW and 1 0 $VIEW 2/4 Use of the /BYPASS 1 0 qualifier 3/8 Use of privileged 1 0 external routines 4/16 Use of %SETUCI 1 0 external routine 5/32 Use of %SPAWN 0 0 external routine 6/64 Use of ZESCAPE 0 0 ______________command_____________________________________ You can manually redefine either of the two privilege bit masks to support the requirements of your site. To restrict the user from bit positions 0, 1, 2, 3, and 4 when the access control system is enabled, set MASK1 = 31 (1+2+4+8+16). The value of each bit position is added to get the value set in MASK1 and MASK2). To restrict the user from bit positions 0, 1, 2, 3, and 4 when the access control system is disabled, set MASK2 = 31. Controlling Access to DSM 3-13 Global Access Control DSM uses a protection scheme that defines global access control based on a user's default (login) UCI name and volume set. The four classes of users are WORLD Users logged in to any UCI on any volume set GROUP Users logged in to a UCI with a name that begins with the same letter as the UCI name of the target global SYSTEM Users logged in to the first UCI on volume set 0 (MGR) UCI Users logged in to the UCI that holds the target global You can apply a separate protection level for each of these four classes of users to a global. The three protection levels defined are READ Global get operations WRITE Global SET operations PURGE Global directory KILL operations You can apply these protection levels to each class of user for each global in any combination. The ultimate objective of all these protection mechanisms is to control the access to globals in the DSM database. The application of appropriate global protections determines which users gain access to a global while logged in to a UCI and volume set. Login access to UCIs and volume sets is controlled by assigning OpenVMS account privileges, selecting configuration access control methods, and granting programmer or application user access to a specific UCI. For a complete description of DSM global protection, see the DSM for OpenVMS Database Operations Guide. 3-14 Controlling Access to DSM Establishing OpenVMS Accounts for Programmers and Application Users Each user accessing a OpenVMS system has an account. A user can be a DSM programmer or an application user. The OpenVMS system's user authorization file, SYS$SYSTEM:SYSUAF.DAT, contains information about each user account. The OpenVMS operating system uses this information to identify valid user accounts. For complete information about how to create accounts, see the OpenVMS System Manager's Manual by Digital Equipment Corporation. If you are the DSM environment manager, you are respon- sible for establishing programmer and application user accounts and ensuring the security of these accounts. To create a OpenVMS account, you must have READ/WRITE access to the SYSUAF.DAT file. The first step in setting up an account is to determine what you want to establish as the account's user name, password, default directory, and other identifying information. The next step is to create the account's main directory and (if appropriate) a login command file. Finally, enter information about the account into the operating system's User Authorization File (UAF) using the OpenVMS Authorize Utility. The Authorize Utility allows you to specify: o The user name o The password o The default device o The privileges o Other identifying information The following example shows how to use the OpenVMS Authorize Utility to create a programmer or application user account for the DSM configuration with a UIC of [215,7]. Controlling Access to DSM 3-15 $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> ADD TILLMAN/PASSWORD=GREMLINS/UIC=[215,7]- /DEVICE=DISK$USER:/DIRECTORY=[TILLMAN]- /BYTLM=40960/ENQLM=300/WSQUOTA=1000/WSEXTENT=1200/FILLM=150- /PRIV=TMPMBX/DEFPRIV=TMPMBX The Digital Equipment Corporation publication, OpenVMS System Manager's Manual, contains instructions on using the SYS$EXAMPLES:ADDUSER.COM procedure to add a new user to the UAF. This command procedure prompts for all categories of information about the user and runs the OpenVMS Authorize Utility. You may find it easier to copy and use this command procedure than to perform all the steps yourself. DSM users need larger quotas in some areas than the ordinary OpenVMS user. Make sure that you establish appropriate values for the BYTLM, ENQLM, WSQUOTA, FILLM, and WSEXTENT quotas, as described in the section "Process Quotas for DSM Users" in Chapter 5. DSM can not run unless these limits are adequate. DSM programmers must have specific privileges to perform some DSM operations as described in Table 3-2. Table_3-2_OpenVMS_System_Privileges_Needed_by_DSM_Programmers___ DSM_Command_____________________Description___________Privilege_ ZUSE $BRKTHRU to a OPER terminal JOB Starts a DSM process TMPMBX OPEN x:(MAILBOX:NEWVERSION) Creates a temporary TMPMBX mailbox OPEN x:(MAILBOX:NEWVERSION:SYSTECreates a permanent PRMMBX ________________________________mailbox_______________SYSNAM____ The %GETUAI external routine requires OpenVMS privileges. For more information about using the %GETUAI external routine and about creating mailboxes, see the DSM for OpenVMS Programmer's Guide. 3-16 Controlling Access to DSM Configuration Access Control Utilities If you enable configuration access control, you can grant programmer mode access to a specific list of volume sets and UCIs. The user can run DSM in programmer mode only in those volume set and UCI combinations to which access was granted. After DSM is running, the user can use the %SETUCI external routine to move to only those volume sets and UCIs for which login is authorized. The programmer mode user has access to all utilities in the library directory (routines that begin with %). Programmer mode access to a volume set and UCI includes application mode access to all of its routines. Application mode access is also granted to a specific list of volume sets and UCIs. Also, login is restricted to specified routines within the volume set and UCI combination. Users limited to application mode access can only log in to a DSM configuration with the following command line: $ DSM[/qualifier...] ^ROUTINENAME ________________________Note ________________________ When you use the ^ACL Utility to grant application mode access to an M routine, you cannot enter a routine label, only a startup routine name, when ^ACL prompts you for the routine name. _____________________________________________________ Users do not escape into programmer mode if the program they are running encounters the ZESCAPE command unless they also have programmer mode access to the current volume set and UCI. Granting Access Interactively (^ACL) The ^ACL Utility defines account access rights lists for any configuration started up in the DSM environment from which it is run. Controlling Access to DSM 3-17 Enter the following to run the ^ACL Utility: $ DSM/MANAGER DSM for OpenVMS VAX V7.1 DSMMGR [MGR,AAA] >D ^ACL The utility displays the following menu: Environment Access Utilities 1. ADD/MODIFY USER (ADD^ACL) 2. DELETE USER (DELETE^ACL) 3. MODIFY ACTIVE AUTHORIZATIONS (^ACLSET) 4. PRINT (PRINT^ACL) Select option > You can get help at any question by entering a question mark (?). You can get a list of current values by entering ^L. You can return to the previous question by entering a circumflex (^). All responses, except the user name, can contain trailing wildcard characters. You can delete any entry by prefixing a minus sign (-) to the entry. For example, you can remove access to UCI RAD by entering -RAD at the UCI prompt. The ADD/MODIFY USER option (ADD^ACL) allows you to edit the DSM access rights for a OpenVMS account. The following is an example of the ADD^ACL Utility: >D ADD^ACL OpenVMS User Name: > TILLMAN ACCESS MODE VOL UCI ROUTINE ----------- --- --- ------- No access rights for this user. 3-18 Controlling Access to DSM Access Mode ([M]ANAGER, [P]ROGRAMMER, or [A]PPLICATION): > A Volume set name: > LAB UCI: > PHA Routine: > RX Routine: > Access Mode ([M]ANAGER, [P]ROGRAMMER, or [A]PPLICATION): > A Volume set name: UCI: CHM Routine: > ORDER Routine: > INQUIRE Routine: > Access Mode ([M]ANAGER, [P]ROGRAMMER, or [A]PPLICATION): > A Volume set name: UCI: RAD ROUTINE: > INQUIRE ROUTINE: > Access Mode ([M]ANAGER, [P]ROGRAMMER, or [A]PPLICATION): > USER ACCESS MODE VOL UCI ROUTINE ---- ----------- --- --- ------- TILLMAN APPLICATION LAB CHM INQUIRE ORDER PHA RX RAD INQUIRE OK to file? OpenVMS User Name: > OK to activate changes now? ________________________Note ________________________ When running a configuration in a VMScluster environment, you must run the ^ACLSET Utility on each node to activate changes across the cluster. _____________________________________________________ In the previous example, a new user named TILLMAN is granted user (application mode) access to volume set LAB. TILLMAN is able to run program RX in the PHA UCI, programs ORDER and INQUIRE in the CHM UCI, and program INQUIRE in the RAD UCI. Controlling Access to DSM 3-19 After you enter the user name, the program lists the user's current access rights (in this case none). Each prompt shows the context of the current entry. For example, it shows the user name, access mode, and volume set for which you are being asked to grant access to a UCI. At the end of the session, you are shown the rights list before you are asked to file it. You can then enter information about another user or press Return. You can activate the changes immediately or answer NO to the last question. If you do not activate the changes, you must use the ^ACLSET Utility to activate those changes. The DELETE USER option (DELETE^ACL) allows you to delete the entire rights list associated with a user name, prohibiting access by that user to a DSM environment controlled by this rights database. For example: >D ADD^ACL OpenVMS User Name > TILLMAN ACCESS MODE VOL UCI ROUTINE ----------- --- --- ------- USER AAA CHM INQ REG PHA LAB RAD INQ OK to delete? TILLMAN DELETED The MODIFY ACTIVE AUTHORIZATIONS option (^ACLSET) takes the global created by ADD^ACL, writes it to a file, and maps it to a global section. You must run ^ACLSET if you do not answer YES to the following question at the end of ADD^ACL: OK to activate changes now? The PRINT option (PRINT^ACL) displays the rights lists of all users or writes it to a OpenVMS file. 3-20 Controlling Access to DSM Granting Access Noninteractively (^ACLCALL) The ^ACLCALL program provides a noninteractive alternate method of adding and deleting user access to a DSM environment. You can call this program from another program in the manager UCI or from the DCL command line. Use of this program requires DSM manager mode access to the environment. Add a user access by a call from an DSM program as follows: D ADD^ACLCALL(USER,MODE,VOL,UCI,ROUTINE) Delete a user access by a call from an DSM program as follows: D DELETE^ACLCALL(USER,MODE,VOL,UCI,ROUTINE) Add a user access from DCL as follows: $ DSM/MANAGER/DATA="USER,MODE,VOL,UCI,ROUTINE" DCLADD^ACLCALL Delete a user access from DCL as follows: $ DSM/MANAGER/DATA="USER,MODE,VOL,UCI,ROUTINE" DCLDEL^ACLCALL where: USER is the OpenVMS user name MODE is one of MANAGER, PROGRAMMER, or APPLICATION (can be abbreviated to one character (M, P, or A)) VOL is a 3-character volume set name (for example, AAA or RAD, or can be specified with a trailing wildcard AA* or R*) UCI is a 3-character UCI name (for example, AAA or RAD, or can be specified with a trailing wildcard AA* or R*) ROUTINE is an DSM routine name (required when granting application mode access) ________________________Note ________________________ The ^ACLCALL program updates the permanent access database for an environment. To update the active database you need to run the ^ACLSET Utility either from within DSM (D ^ACLSET), or from DCL ($ DSM Controlling Access to DSM 3-21 /MANAGER ^ACLSET). If you are adding or deleting a number of users, run ^ACLSET after all invocations of ^ACLCALL. _____________________________________________________ Creating Dedicated Application Accounts You can establish separate DSM application accounts for any of the following reasons: o To enable protected and dedicated startup of an application o To provide an easy-to-use interface for the application user o To prevent tampering with the data that is manipulated by an application Application accounts can be set up to effectively tie an application user to a specific application, which prevents any interaction with the OpenVMS operating system. The process of establishing dedicated application accounts and terminals requires that you configure several components in a manner that directly connects the application user to the application programs. These components include: o OpenVMS automatic login facility o OpenVMS captive user accounts o OpenVMS login command procedures o DSM command line qualifiers o DSM tied terminal utilities Two login methods are provided for application users: o Tied Application Accounts The application user enters a user name and password that correspond to a particular DSM application account. On login, a captive login command procedure is called directly. The DSM application is run from the login command procedure without further interaction 3-22 Controlling Access to DSM and logs the user out when the application session is complete. o Tied Terminals You can tie an application account to a terminal (or set of terminals) using the OpenVMS automatic login facility. The SYS$SYSTEM:SYSALF.DAT file (automatic login file, or ALF) is maintained by OpenVMS System Management Utility (SYSMAN) commands (ALF ADD, ALF REMOVE, ALF SHO). Use SYSMAN to set up a terminal that accepts automatic logins from authorized users (tied terminals). For a description of this facility, see the Digital publication, OpenVMS Guide to System Security. When you press control characters (such as Return or Ctrl/C) on a tied terminal, the login command procedure is called directly without further user interaction. Both of these login methods accomplish the same objective. The application user is granted access to a OpenVMS account that you have set up for dedicated application use. The remainder of this section describes how to set up captive accounts, create login command procedures, and use the ^TIED Utility to tie accounts to an application. Setting Up a Captive Account You can set up a captive account to provide a user account that is dedicated to running the DSM application. The OpenVMS captive account is set up by logging in to the OpenVMS system manager's account and using the OpenVMS Authorize Utility. For example: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> ADD TILLMAN/UIC=[215,7]- /DEVICE=DISK$USER:/DIRECTORY=[TILLMAN]- /BYTLM=40960/ENQLM=300/WSQUOTA=1000/WSEXTENT=1200/FILLM=150- /PRIV=TMPMBX/DEFPRIV=TMPMBX- /FLAGS=(CAPTIVE,DISWELCOME,DISCTLY,DISREPORT)/LGICMD=CAPTIVE.COM/NOPASSWORD The previous example sets the following flags and qualifiers: o The CAPTIVE flag indicates that the account user cannot change any login defaults or have direct access to DCL. Controlling Access to DSM 3-23 o The DISWELCOME flag disables the OpenVMS "Welcome to . . . " message. o The DISCTLY flag disables Ctrl/Y. o The DISREPORT flag disables the last login time reporting message. o The /NOPASSWORD qualifier sets up the account so that you do not need to enter a password after you enter the user name. o The /LGICMD= qualifier specifies that the CAPTIVE.COM procedure is run when the application user logs in. The Digital publication, OpenVMS System Manager's Manual, contains instructions on using the SYS$EXAMPLES:ADDUSER.COM procedure to add a new user to the UAF. This command procedure prompts for all categories of information about the user, runs the OpenVMS Authorize Utility, and cleans up after itself. You may find it more convenient to copy and use this command procedure than to perform all the steps yourself. Creating a Captive Command Procedure You can create a command procedure that runs when a user logs in to a captive account. The command procedure invokes DSM in application mode and runs a DSM routine. You can use the DSM Tied Terminal Utility (^TIED) to dispatch the process to the appropriate application routine or you can invoke your own routine. If you are using the ^TIED Utility, include the following lines in CAPTIVE.COM: $ DSM/INPUT=SYS$COMMAND/ENVIRONMENT=DSMMGR/VOL=XXX/UCI=MGR ^TIEDSTU $ LOGOUT To use the ^TIEDSTU Utility, the OpenVMS user account must be granted application mode access to the MGR UCI in the designated volume set. Also, because the ^TIED Utility stores tied terminal port and routine tables in the SYS.GBL RMS global, you must allow read access to SYS.GBL. 3-24 Controlling Access to DSM To configure proper protection for the environment root directory and the SYS.GBL global, you can apply ACL entries that use the DSM$USER_envnm identifier. For example, to allow read access to SYS.GBL in the environment root directory, DISK$USER:[DSMMGR], enter the following commands: $ SET DIRECTORY DISK$USER:[DSMMGR]/ACL= - (IDENTIFIER=DSM$USER_DSMMGR,ACCESS=EXECUTE) $ SET ACL DISK$USER:[DSMMGR]SYS.GBL/ACL = - (IDENTIFIER=DSM$USER_DSMMGR,ACCESS=READ) Alternatively, you can use an application-specific entry routine to control access by a captive account. Include the following lines in CAPTIVE.COM, substituting your environment, volume set name, UCI, and routine names: $ DSM/INPUT=SYS$COMMAND/ENVIRONMENT=DSMMGR/VOL=xxx/UCI=xxx ^ROUTINE $ LOGOUT ________________________Note ________________________ If you use a customized login method and the security system is enabled for the running configu- ration, you must also use the ^ACL Utility to grant the OpenVMS user account application mode access to the specified volume set, UCI, and routine. _____________________________________________________ Setting Up DSM Tied Routine and Port Tables The Tied Routine Utility (^TIED) dispatches to a user- defined application routine from the DSM manager's UCI. The user routine can be located in any UCI or volume set mounted in the currently running configuration. The routine dispatch is keyed to the name of the port that the user is logged in to by using the value of the $ZIO special variable. This facility allows the DSM manager to create a table of ports and associate the port with a specific application routine. Controlling Access to DSM 3-25 The ^TIED Utility provides a menu interface to all tied routines and port maintenance functions described. Enter the following to run the ^TIED Utility: >D ^TIED The utility displays the following menu: Tied Routine Utilities: 1. ADD PORT (ADD^TTPORT) 2. DELETE PORT (DELETE^TTPORT) 3. MODIFY ROUTINE TABLE (MODIFY^TTROU) 4. SHOW TIED PORTS (SHOW^TTPORT) 5. SHOW TIED ROUTINES (SHOW^TTROU) Enter Option > You can tie routines using the following procedure: 1. First, create a Tied Routine Table using the MODIFY^TTROU Utility. Each routine in the table is created and indexed by a unique number. Enter Option > 3 MODIFY ROUTINE TABLE Add Tied Routine Table Entries Enter tied routine index number <1> Table entry not currently defined Enter UCI name for routines> REB Enter Volume Set name for routines> REB Enter routine name > ^ACCT Enter UCI name for globals Enter Volume Set name for globals ^ACCT added as tied routine number 1 Enter tied routine index number <2> 2. Next, create a Tied Port Table entry for each port or group of ports you want to tie to an application routine. Do this by using the ADD^TTPORT Utility. For each port, the ADD^TTPORT Utility asks you to specify the Tied Routine index number associated with the tied routine. The organization of these two tables is designed to allow you to modify the routine name of an entry in the Tied Routine Table without having to rebuild the Tied Port Table. 3-26 Controlling Access to DSM When you build the Tied Port Table, use a wildcard to specify a port name to force ports of one type to be tied to one routine. For example, specifying TX* as a port to tie, forces all TX-type terminals to connect to a designated tied routine. Enter Option > 1 ADD PORT Add Tied Ports Enter tied routine number > 1 Enter port names to tie to ^ACCT Port(s) > TXA0: Port(s) > TXA0: tied to routine #1 Enter tied routine number > Use the DELETE PORT option (DELETE^TTPORT) to delete an entry from the table. For example: Enter Option > 2 DELETE PORT Delete Tied Ports Enter port names to delete Port(s) TXA1: TIED PORTS TABLE updated PORT(s) > Use the SHOW TIED PORTS option (SHOW^TTPORT) to display the Tied Ports Table and the SHOW TIED ROUTINES option (SHOW^TTROU) to display the Tied Routines Table entries. Controlling Access to the Callable Routines Interface The DSM callable interface allows you develop applications written in languages other than DSM that: o Call the DSM interpreter o Reference the DSM database The DSM callable interface is made up of standard entry points that can be referenced by any program written by a OpenVMS user. Therefore, to secure your DSM database, you should restrict the use of the callable interface. Controlling Access to DSM 3-27 Access control for the callable routines is provided for each of two classes of calls to DSM: o DSM$DSM routine The DSM$DSM routine provides a DCL command line type interface to DSM from external programs. Any valid DSM command line can be passed to the routine, but the command line must end with a valid M routine reference. Use of the DSM$DSM routine is granted depending on whether the user running the external routine has been authorized to run DSM in application mode. If you do not enable the DSM configuration access control system, authorization is not necessary. If you enable the access control system, you must use the ^ACL Utility to grant application mode access to the user. o DSM$INITIALIZE routine The DSM$INITIALIZE routine and associated routines allow access to all global and interpreter functions. The calling program supplies a login UCI and volume set. After DSM$INITIALIZE is complete, the calling program can set, kill, and read any DSM global within the UCI or data that is unprotected in the database. These functions are similar to the capabilities available to users entering DSM in programmer mode. Given these capabilities, use of the DSM$INITIALIZE routine is granted on the basis of whether the user running the external routine has the authorization to run DSM in programmer mode. If you do not enable the DSM configuration access control system, authorization is not necessary. If you enable the access control system, you must use the ^ACL Utility to grant programmer mode access to the user. DSM overrides the normal checks made to determine whether a user has the authorization to use the callable interface if: o The user has the SYSPRV or BYPASS privileges. o The user is the DSM environment manager. o The main calling image is installed with the TMPMBX privilege using the OpenVMS Install Utility. 3-28 Controlling Access to DSM Installation of the calling program allows you to let unprivileged OpenVMS users run an application program in a highly controlled fashion. The user can run the program, but cannot modify the actions of the calling program or write private programs that access DSM. Installation of a program can be done only by a privileged OpenVMS user with the CMKRNL privilege: $ SET PROCESS/PRIVILEGE=CMKRNL $ INSTALL ADD DISK$APPL:[APPL]APPLPROG.EXE/PRIVILEGE=TMPMBX During development of the calling program, you can grant the developer the appropriate access to the UCIs that are necessary for testing. Once the program is developed and debugged, you can install the program using the OpenVMS Install Utility to make it available for general use. Using the Login Control Utility (^LOGIN) Many operational and system management functions require that no application programmers or users are currently accessing the running configuration. Functions such as backup, database integrity checking, or database repair require standalone operations. The Login Access Control Utility (^LOGIN) allows you to control all user and programmer access to running DSM configurations. When login access is disabled, users who attempt to run DSM without the /MANAGER command line qualifier receive the following error message: %DSM-E-LOGINDIS, DSM logins are currently disabled Authorized DSM managers who run DSM with the /MANAGER command line qualifier are always granted access. You can use the ^LOGIN Utility to dynamically disable and re-enable user access. This allows you, as DSM manager, to disable DSM access without having to disable interactive logins to the OpenVMS operating system. Enter the following to run ^LOGIN: >D ^LOGIN Controlling Access to DSM 3-29 The utility displays the following options: Login Control Utilities 1. DISABLE (DISABLE^LOGIN) 2. ENABLE (ENABLE^LOGIN) Select Option > Select option 1 to disable logins and option 2 to enable logins. Using the ^STU Utility, you can disable user logins when configuration startup is complete. If user logins are disabled, DSM startup allows manager access only. When you are ready to allow application users back into DSM, you re-enable login access using the ^LOGIN Utility. You must use the DSM /MANAGER command line qualifier to run ^STU. >D ^STU DSM Configuration Startup Enter the configuration identifier Enable user logins on startup [Y OR N] ? N Enable servicing of incoming DDP global requests [Y OR N] ? Y Starting DSM configuration WRITER . . . DSM startup complete - User logins disabled Also, an optional input parameter can be used to disable user access on configuration startup when the SYS$MANAGER:DSM$STARTUP.COM procedure is called. The calling format for DSM$STARTUP.COM is as follows: $ @SYS$STARTUP:DSM$STARTUP p1 p2 p3 where: p1 is the name of the configuration to start or null ("") to start the default configuration p2 is DISABLE to disable user logins on startup and ENABLE to enable user logins (default) p3 is DISABLE to inhibit global request servicing 3-30 Controlling Access to DSM 4 ________________________________________________________________ Using the DSM Security Audit Facility This chapter describes how to use the DSM Security Audit facility. Overview of the DSM Security Audit Facility The Security Audit Facility allows DSM developers to build applications that meet C2 security requirements. C2 is part of the United States government's rating system for computer system security. The criteria for C2 (Division C, class 2) systems are defined in the Department of Defense Trusted Computer System Evaluation Criteria, published by the Department of Defense Computer Security Center (DOD 5200.28-STD). Although earlier versions of DSM supplied methods to control programmer access to globals and UCIs, none of these existing methods are sufficient to track and report programmer activities for C2 purposes. Because of the nature of their work, DSM programmers need to access potentially sensitive data to perform any of the following tasks: o Maintain an application o Repair a database o Investigate a problem You can use DSM Security Audit Facility to achieve a C2- level secure environment for programming and development work while still ensuring that site personnel can perform their duties. Through the Security Audit Facility, you can monitor programmer activity on your system by recording events in the OpenVMS Security Audit Log File. Using the OpenVMS Audit Analysis Utility ($ ANALYZE/AUDIT), you can periodically review the Security Audit Log File. Using the DSM Security Audit Facility 4-1 Security Audit Events Once started, the DSM Security Audit Facility begins recording security event messages in the OpenVMS Security Audit Log File. The OpenVMS Security Audit Log File is an operating-system level journal file that contains all the event messages generated by the OpenVMS operating system. The security event messages that the DSM Security Audit Facility records in the OpenVMS Security Audit Log File are programmer accesses to the database. Each security event message contains the following data: o The object class name o Message Event Codes (describing the type of event) o The date and time that the event occurred o The process identification (PID) of the process that caused the event o The name of the process that caused the event o The user name of the account o The owner of the process that caused the event o The name of the terminal (if applicable) o The name of the DSM image that is being executed The last seven items are specific to the system and are considered "data" that describe the security event logged. The first two items are specific to DSM and are described in the following sections: Object Class Names Object class names are the key to extracting DSM-specific information from the OpenVMS System Security Audit Log File. Each object class name is a character string with the following format: DSM$AUDIT_environment 4-2 Using the DSM Security Audit Facility Where: environment is the name of the DSM environment where the event took place You can use the object class name to: o Extract DSM-specific messages from the OpenVMS System Security Audit Log File. o Produce audit reports of DSM events at your site. Message Event Codes Message event codes are made up of the following elements: o A field-a code that describes the general type of event recorded o A subfield-a code that describes a specific type of event within the general type DSM allows the following types of access events to be tracked so that sufficient information exists to investigate potential security breaches: DSM_LOGIN: Programmer Login A security event message containing a programmer login (DSM_LOGIN) message event code records programmer access to a specific UCI. The access event recorded can be either: o A login to DSM in that UCI o A change from another UCI to that UCI A DSM_LOGIN message event code contains the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - None DSM_LOGIN NEW Login UCI and volume set DSM_LOGIN________ORIGINAL_________Not_specified___________ Example: Using the DSM Security Audit Facility 4-3 The following is an example of a DSM_LOGIN security event message: Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 14:15:08.16 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: None DSM_LOGIN: New: [MGR,TST] Original: - Status: %SYSTEM-S-NORMAL, normal successful completion DSM_LOGOUT: Programmer Logout A security event message containing a programmer logout (DSM_LOGOUT) message event code records a programmer's exit from a UCI. A DSM_LOGOUT message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - None DSM_LOGOUT NEW Login UCI and volume set DSM_LOGOUT_______ORIGINAL_________Not_specified___________ Example: The following is an example of a DSM_LOGOUT security event message: 4-4 Using the DSM Security Audit Facility Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive logout Event time: 14-JUL-1997 14:15:08.16 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: None DSM_LOGOUT: New: [MGR,TST] Original: - Status: %SYSTEM-S-NORMAL, normal successful completion DSM_GLOBAL_SET: Global Sets A security event message containing a global set (DSM_ GLOBAL_SET) message event code records a programmer's sets to accessible globals. A DSM_GLOBAL_SET message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - Extended global node reference to be set DSM_GLOBAL_SET NEW Global node data to be set DSM_GLOBAL_SET ORIGINAL UCI and volume set from which operation __________________________________is_performed____________ Using the DSM Security Audit Facility 4-5 Example: The following is an example of a DSM_GLOBAL_SET security event message: Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 14:15:28.07 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: ^["DEF","TST"]ABC(1,2,3) DSM_GLOBAL_SET: New: Hello Original: Operation performed from [MGR,TST] Status: %SYSTEM-S-NORMAL, normal successful completion DSM_GLOBAL_KILL: Global Kills A security event message containing a global kill (DSM_ GLOBAL_KILL) message event code records a programmer's kills to accessible globals. A DSM_GLOBAL_KILL message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - Extended global node reference to be killed DSM_GLOBAL_SET NEW Explanatory text string DSM_GLOBAL_SET ORIGINAL UCI and volume set from which operation __________________________________is_performed____________ Example: The following is an example of a DSM_GLOBAL_KILL security event message: 4-6 Using the DSM Security Audit Facility Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 14:15:28.07 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: ^["DEF","TST"]ABC(1,2,3) DSM_GLOBAL_KILL: New: Global data deleted Original: Operation performed from [MGR,TST] Status: %SYSTEM-S-NORMAL, normal successful completion DSM_ROUTINE_SAVE: Modifications to Application Routines A security event message containing a routine modification (DSM_ROUTINE_SAVE) message event code records programmer's modifications to accessible routines. A DSM_ROUTINE_SAVE message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - Routine name to be modified or deleted ([UCI,VOL]) DSM_ROUTINE_ NEW Explanatory text string SAVE DSM_ROUTINE_ ORIGINAL - SAVE______________________________________________________ Example: The following is an example of a DSM_ROUTINE_SAVE security event message: Using the DSM Security Audit Facility 4-7 Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 12:11:04.19 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: ^AUD ([MGR,TST]) DSM_ROUTINE_SAVE: New: DSM routine modified or deleted Original: - Status: %SYSTEM-S-NORMAL, normal successful completion DSM_GPROTECTION: Modifications to Global Protection A security event message containing a global protection modification (DSM_GPROTECTION) message event code records modifications to the protections on accessible globals. A DSM_GPROTECTION message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - Extended global name reference DSM_GPROTECTION NEW New global protection data DSM_GPROTECTION ORIGINAL UCI and volume set from which operation __________________________________is_performed____________ Example: The following is an example of a DSM_GPROTECTION security event message: 4-8 Using the DSM Security Audit Facility Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 12:11:04.19 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: ^["DEF","TST"]ABC DSM_GPROTECTION: New: System = R World = RW Group = R UCI = RWP Original: Operation performed from [MGR,TST] Status: %SYSTEM-S-NORMAL, normal successful completion DSM_GJOURNAL: Modifications to Global Journaling A security event message containing a global journaling modification (DSM_GJOURNAL) message event code records modifications to the journaling characteristics on accessible globals. A DSM_GJOURNAL message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - Extended global name reference DSM_GPROTECTION NEW New global journaling option DSM_GPROTECTION ORIGINAL UCI and volume set from which operation __________________________________is_performed____________ Example: The following is an example of a DSM_GPROTECTION security event message: Using the DSM Security Audit Facility 4-9 Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 12:11:04.19 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: ^["DEF","TST"]ABC DSM_GJOURNAL: New: Global journaling enabled Original: Operation performed from [MGR,TST] Status: %SYSTEM-S-NORMAL, normal successful completion DSM_GCOLLATION: Modifications to Global Collation/Encoding A security event message containing a global collation modification (DSM_GCOLLATION) message event code records modifications to the collating and encoding characteristics on accessible globals. A DSM_GJOURNAL message event code has the following elements: __________________________________________________________ Field____________Subfield_________Data____________________ OBJECT NAME - Extended global name reference DSM_GPROTECTION NEW New global collation and encoding data DSM_GPROTECTION ORIGINAL UCI and volume set from which operation __________________________________is_performed____________ Example: The following is an example of a DSM_GCOLLATION security event message: 4-10 Using the DSM Security Audit Facility Security audit (SECURITY) on ACV01, system id: 39248 Auditable event: Local interactive login Event time: 14-JUL-1997 12:11:04.19 PID: 20200189 Process name: DSMMGR Username: DSMMGR Process owner: [DSMMGR] Terminal name: RTA1: Image name: SYS$COMMON:[SYSLIB]DSM$SHARE.EXE;1 Object class name: DSM$AUDIT_DSMMGR Object name: ^["DEF","TST"]ABC DSM_GCOLLATION: New: Collating: Numeric Encoding: 8 bit Original: Operation performed from [MGR,TST] Status: %SYSTEM-S-NORMAL, normal successful completion Enabling Security Auditing for a Configuration You must take two steps to enable security auditing on a DSM configuration: o Run ^CONFIG to enable DSM support for security auditing o Make sure that OpenVMS is enabled for security auditing Running ^CONFIG to Enable DSM Support for Security Auditing You use ^CONFIG to configure DSM support for security auditing. The ^CONFIG utility allows you to: o Specify a security audit profile name o Define the security audit parameters associated with that named profile A security audit profile is a list of the message event codes for the type of events you want to log. You define the profile and give it an identifying profile name through ^CONFIG. The profile name you assign can be any string of up to 12 alphanumeric characters. After you list the message event codes for the type of events you want to log and assign an identifying profile name, DSM stores the security audit profile. That security audit profile is now "portable." You can specify the name of that security audit profile, through ^CONFIG, to different configurations, typically within the same cluster. Using the DSM Security Audit Facility 4-11 In the following example, the ^CONFIG utility is used to create a security audit profile that covers all security audit events currently supported for programmer access: $DSM/MANAGER DSM V7.0 for OpenVMS VAX DSMMGR [Baseline] >D CONFIG Define a DSM configuration Type ? for HELP at any time Would you like extended help [Y OR N] ? Enter the configuration identifier . . . Include support for Visual M application serving [Y OR N] ? Include support for security auditing [Y OR N] ? Y Enter the security audit name to load at startup > TEST Specify a security audit name that consists of up to 12 uppercase, alpha-numeric characters. Security audit name TEST is not currently defined. Are you sure you want to continue [Y OR N] ? Define security audit name TEST Enable DSM_LOGIN auditing [Y OR N] ? Enable DSM_LOGOUT auditing [Y OR N] ? Enable DSM_GLOBAL_SET auditing [Y OR N] ? Enable DSM_GLOBAL_KILL auditing [Y OR N] ? Enable DSM_ROUTINE_SAVE auditing [Y OR N] ? Enable DSM_GPROTECTION auditing [Y OR N] ? Enable DSM_GJOURNAL auditing [Y OR N] ? Enable DSM_GCOLLATION auditing [Y OR N] ? . . . 4-12 Using the DSM Security Audit Facility Making Sure OpenVMS is Enabled for Security Auditing Before you start up the configuration with security auditing enabled, you must make sure that the OpenVMS Audit Server and OPCOM are running on your system. All OpenVMS operating systems start the Audit Server process and OPCOM by default. If the Audit Server process and OPCOM are not running, you can restart them by executing the following DCL command procedure: $ SET PROCESS/PRIVILEGES=(OPER,BYPASS) $ @SYS$SYSTEM:STARTUP OPCOM $ @SYS$SYSTEM:STARTUP AUDIT_SERVER See the OpenVMS System Management Utilities Reference Manual, published by Digital Equipment Corporation, for more information about the Audit Server. Analyzing the Security Audit Log File You use the OpenVMS Audit Analysis Utility ($ ANALYZE /AUDIT) to examine the data in the Security Audit Log File. This section describes how to use the OpenVMS Audit Analysis Utility to generate a DSM auditing report from the log file. See the OpenVMS System Management Utilities Reference Manual, published by Digital Equipment Corporation, for complete documentation of the utility's commands and qualifiers. To invoke the Audit Analysis utility, use the following DCL commands: $ SET PROCESS/PRIVILEGES=SECURITY $ ANALYZE/AUDIT file-name Where: file-name The name of the file from which the audit reports are to be generated The default name of the Security Audit Log File is SECURITY.AUDIT$JOURNAL. You may use the following DCL command to find the Security Audit Log File name on your system: Using the DSM Security Audit Facility 4-13 $ SHOW AUDIT/JOURNAL List of audit journals: Journal name: SECURITY Journal owner: (system audit journal) Destination: SYS$COMMON:[SYSMGR]SECURITY.AUDIT$JOURNAL Monitoring: enabled Warning thresholds, Block count: 100 Duration: 2 00:00:00.0 Action thresholds, Block count: 25 Duration: 0 00:30:00.0 Ordinarily, all cluster events are written to a single Security Audit Log File. Thus, there is a single record of all audit events on this system. One cluster-wide log file is preferable to node-specific Security Audit Log Files. Node-specific Security Audit Log Files lose the interrelationship of events across the cluster, thus producing an incomplete analysis of security events. Selecting DSM Security Event Messages With the Audit Analysis Utility, you can perform the following: o Extract all or some of the DSM generated security event messages from a Security Audit Log File o Produce reports with various levels of detail The audit report reflects events from the set of event types your site has enabled. You can tailor the report so only a subset of events are extracted. The selection criteria can be based on: o Time o Message event code o A date field within the event message The following examples describe the procedure that can be used to select DSM auditing records: 4-14 Using the DSM Security Audit Facility Example 1: The following command procedure produces an audit report named DSM$AUDIT_ALL.DAT that contains descriptions of all the security event messages generated by DSM. $ ANA/AUDIT/SELECT=OBJECT=CLASS=DSM$*/OUTPUT=DSM$AUDIT_ALL.DAT/FULL - _$ SYS$MANAGER:SECURITY.AUDIT$JOURNAL Example 2: The following command procedure produces an audit report named DSM$AUDIT_PROD.DAT that contains descriptions of all the security event messages generated by the DSM environment named PROD. $ ANA/AUDIT/SELECT=OBJECT=CLASS=DSM$AUDIT_PROD/OUTPUT=DSM$AUDIT_PROD.DAT/FULL - _$ SYS$MANAGER:SECURITY.AUDIT$JOURNAL Example 3: The following command procedure produces an audit report named DSM$AUDIT_PROD.DAT that contains descriptions of all the security event messages generated by DSM global set and kill operations. $ ANA/AUDIT/SELECT=FIELD_NAME=DSM_GLOBAL*/OUTPUT=DSM$AUDIT_PROD.DAT/FULL - _$ SYS$MANAGER:SECURITY.AUDIT$JOURNAL Example 4: The following command procedure produces an audit report named DSM$AUDIT_PROD.DAT that contains descriptions of all the security event messages generated by the DSM global set and kill operations in the DSM environment named PROD. $ ANA/AUDIT/SELECT=(OBJECT=CLASS=DSM$AUDIT_PROD,FIELD_NAME=DSM_GLOBAL*) - _$ /OUTPUT=DSM$AUDIT_PROD.DAT/FULL SYS$MANAGER:SECURITY.AUDIT$JOURNAL Example 5: The following command procedure produces an audit report named DSM$AUDIT_PROD.DAT that contains descriptions of all the security event messages generated by the DSM environment named PROD since June 30, 1997. $ ANA/AUDIT/SELECT=OBJECT=CLASS=DSM$AUDIT_PROD/SINCE=30-JUN-1997 - _$ /OUTPUT=DSM$AUDIT_PROD.DAT/FULL SYS$MANAGER:SECURITY.AUDIT$JOURNAL Using the DSM Security Audit Facility 4-15 5 ________________________________________________________________ Tuning the OpenVMS Operating System for Use with DSM This chapter describes the relevant OpenVMS process and system parameter adjustments necessary to run DSM. It also describes how to configure shared and nonpaged memory. Overview Tuning the OpenVMS operating system for use with DSM involves adjusting the following: o Process quotas for DSM users o OpenVMS SYSGEN parameters The first two sections describe the process quotas and SYSGEN parameters that may require modification. The section "Using the ^MEMORY Utility" contains information on how you can use the ^MEMREQ Utility to determine the proper values to use when you modify process and system parameters. The section "Modifying OpenVMS System Parameters" describes the recommended method for modifying OpenVMS system parameters. The section "Page and Swap File Size" discusses considerations for creating page and swap files. Process Quotas for DSM Users Each OpenVMS user (including the DSM manager) must have set limits on certain system resources that affect system performance. Use the OpenVMS Authorize Utility to modify process quotas for each user. The following are the OpenVMS limits that directly affect DSM system operation. Recommended changes from the OpenVMS default values are indicated in boldface. o Buffered I/O Byte Count Limit (BYTLM) Tuning the OpenVMS Operating System for Use with DSM 5-1 The BYTLM process quota restricts the buffer space that a process can use for various operations, such as writes to terminals or mailboxes. Accessing files, particularly large files, also uses up the BYTLM quota. The default byte count limit is not adequate for DSM operations because of heavy use of buffer space for writes by DSM. Significantly increase the value of this limit. A value of 40960 is recommended. o Enqueue Quota (ENQLM) The ENQLM process quota establishes the maximum number of locks that a process can own. Set this limit to 300 on DSM user accounts. Set this limit to 1000 on the DSM manager account. o File and Logical Link Limit (FILLM) The FILLM process quota limits the number of files that a user's process can have open at one time. This limit includes the number of network logical links that can be active at the same time. DSM processes must have a sufficiently high FILLM quota to open all database files to access the DSM global system. Set this limit to 150 for all DSM users. This value should be higher if your application heavily uses RMS globals, other non-database files, or if you use more than 16 volume sets. o AST Queue Limit (ASTLM) The DSM Write Demon requires that the ASTLM process quota be at least double the direct I/O limit process quota (DIOLM) for the process performing the incremental backup. Use the following formula to determine the ASTLM value needed for the incremental backup process: ASTLM DIOLM * 2 o Default Working Set Size (WSDEFAULT) The WSDEFAULT process quota sets the initial working set size for a user's process. The appropriate size depends on the number of buffers used by the application. 5-2 Tuning the OpenVMS Operating System for Use with DSM Use the ^MEMREQ Utility to determine the minimum default working set size (WSDEFAULT) value for processes using nonpaged sections. o Working Set Size Limit (WSQUOTA) The WSQUOTA process quota restricts the size to which the working set of a user's process can expand when system-wide memory demand is significant. The proper value for this limit is highly sensitive to the characteristics of the configuration you are using. The number of disk buffers is the largest contributor to working set requirements. Symbol table and source buffer sizes also contribute. If you use nonpaged system memory for your disk cache and mapped routine sections, you can significantly re- duce your working set size requirements in environments that require many disk buffers. Use the ^MEMREQ Utility to determine the minimum working set limit (WSQUOTA) for processes. Note the paging that occurs while running your application and increase this value if paging is excessive. o Working Set Extent Limit (WSEXTENT) The WSEXTENT process quota specifies the maximum size to which a user's physical memory use can grow when the system has excess free pages. WSEXTENT is always greater than or equal to WSQUOTA. Use the ^MEMREQ Utility to determine the minimum working set extent limit (WSEXTENT) value for processes using nonpaged sections. For more information about using DSM to evaluate process quota requirements, see the section "Using the ^MEMORY Utility" in this chapter. For more information about process quota limits, see the Digital publication, OpenVMS System Manager's Manual. Tuning the OpenVMS Operating System for Use with DSM 5-3 SYSGEN Parameters for DSM Configurations DSM requires modified values for a few OpenVMS SYSGEN parameters. This section lists only those parameters that specifically affect the DSM user environment (either the programmer or the application). For a complete description of each SYSGEN parameter, see the publication OpenVMS System Management Utilities Reference Manual by Digital Equipment Corporation. The ^MEMREQ Utility displays suggested minimum values for the following parameters based on any configuration that you have previously set up using ^CONFIG. WSMAX This parameter should be greater than WSEXTENT (working set extent) for all DSM accounts. If the WSQUOTA and WSEXTENT values assigned to individual users in the UAF are lower than WSMAX, they are used as maximums. BALSETCNT This parameter sets the maximum number of processes you can have resident in memory on your OpenVMS system. If more processes than BALSETCNT log in, the system swaps out other processes to make memory available. Swapping adversely affects performance. You may need to increase this parameter for DSM if you intend to support many DSM processes. MAXPROCESSCNT This parameter sets the maximum number of processes allowed on the system. Make MAXPROCESSCNT at least 1 greater than BALSETCNT. LOCKIDTBL This parameter may have to be increased for DSM, particularly if you are using cluster-mounted volume sets. Use the ^MEMREQ Utility to determine the minimum amount to add to this value. To determine the best value, observe the number of lock entries under heavy load by running the LOCK option of the OpenVMS Monitor Utility. 5-4 Tuning the OpenVMS Operating System for Use with DSM LOCKIDTBL_MAX Whenever you increase LOCKIDTBL, increase LOCKIDTBL_MAX by the same amount. If you are using cluster-mounted volume sets, set LOCKIDTBL_MAX to at least 65535 entries. RESHASHTBL Whenever you increase LOCKIDTBL, increase RESHASHTBL by the same proportion, then round the number to the next higher power of two. GBLSECTIONS This parameter sets the number of global section descriptors allocated in the system at bootstrap time. The following describes other requirements for setting GBLSECTIONS: o If you use nonpaged memory for your DSM global buffers and mapped routine sections, you need one global section for DSM memory management, plus one global section for each mapped routine file. o If you are using paged memory for these sections, you need one global section for DSM memory management, plus one section for the DSM global buffers, plus two sections for each mapped routine file. o The ^%JOB Utility requires two global sections. o One section is required if you enable configuration access control. o Transaction processing requires an additional global section. Use the ^MEMREQ Utility to determine the number of global sections that you require when you start up your DSM configuration. GBLPAGES This parameter sets the number of global page table entries allocated at bootstrap time. If you are using nonpaged memory for your DSM global buffers and mapped routine sections, you need to allocate only enough global page table entries to map the DSM memory management and mapped routine data structures. Tuning the OpenVMS Operating System for Use with DSM 5-5 You must allocate eight plus one global page table entry for each mapped routine section. If you are using paged memory for your DSM global buffers and mapped routine sections, you need to allocate enough global page table entries to map all the global buffer section (DSM$CACHE) and each of the mapped routine sections. Use the ^MEMREQ Utility to determine the number of global page table entries that are required when you start up your DSM configuration. GBLPAGFIL This parameter defines the maximum number of system-wide pages allowed for global page-file sections (scratch global sections that use the primary page file for backing storage). If you are using paged memory for your DSM global buffers, increase the current value of this parameter. Use the ^MEMREQ Utility to determine how much to add to this parameter. If you increase this parameter, you may need to increase the size of the system page file, SYS$SYSTEM:PAGEFILE.SYS, by the same number of blocks. For more information about SYS$SYSTEM:PAGEFILE.SYS, see the Digital publication, OpenVMS System Management Utilities Reference Manual. LRPCOUNT This parameter establishes the number of large request packets allocated to the LRP lookaside list. DDP allocates and uses LRPs for DDP buffers. If LRPCOUNT is too low, system performance can be adversely affected.[1] PQL_DWSDEFAULT, PQL_DWSEXTENT, PQL_DWSQUOTA These parameters define the working set sizes used by detached processes that are started using the DCL RUN command. The ^MEMREQ Utility suggests minimum values for these parameters. ___________________ [1]Use the OpenVMS Monitor Utility or the DCL command SHOW MEMORY/POOL/FULL to determine the use of nonpaged dynamic pool, and of small, I/O, and large request packets. 5-6 Tuning the OpenVMS Operating System for Use with DSM Using the ^MEMORY Utility Use the Memory and System Parameter Evaluation Utility (^MEMORY) to determine the nominal SYSGEN, process quota, and DSM physical memory values that you need to run a DSM configuration efficiently. Enter the following to run ^MEMORY: >D ^MEMORY DSM displays the following menu: Physical Memory Management Menu 1. REQUIREMENT (^MEMREQ) 2. USAGE (^MEMUSE) Select Option > The ^MEMREQ Utility examines a specific configuration and determines the amount of memory and other system resources that are required. It also evaluates the amount of memory that is used by each process and suggests process quota requirements (WSMAX, WSQUOTA, and WSEXTENT). Use the ^MEMUSE Utility to determine the physical memory requirements for your configuration. For more information about the ^MEMUSE Utility, see the section "Configuring Nonpaged Memory." You can run the ^MEMREQ Utility during ^CONFIG when you have completed the definition of a configuration or by a direct call. In both cases, the configuration you are evaluating does not have to be running. However, ^MEMREQ requires that the configuration is completely defined. All volume set files, before-image journal files, and routine mapped files specified in the configuration must be present for the ^MEMREQ Utility to work properly. To invoke ^MEMREQ from the ^CONFIG Utility, answer YES to the show requirements question after the configuration has been built. For example: Tuning the OpenVMS Operating System for Use with DSM 5-7 >D ^CONFIG Would you like extended help [Y OR N] ? Enter the configuration identifier . . . Show configuration memory requirements [Y OR N] ? Y If you invoke ^MEMREQ directly, you must specify the configuration for which you want to evaluate SYSGEN and memory requirements. >D ^MEMREQ DSM Configuration Memory Requirements Enter the configuration identifier The ^MEMREQ Utility displays the parameters on several pages. Each page displays a group of comparable param- eters, such as physical memory requirements or minimum process quota values. The first page displays a summary of SYSGEN parameters and suggested values that are directly related to the efficient operation of the running DSM configuration: 5-8 Tuning the OpenVMS Operating System for Use with DSM SYSGEN requirements for configuration PAYROLL Parameter Name Value 1 Minimum SYSGEN Values BALSETCNT 50 LOCKIDTBL_MAX 65535 MAXPROCESSCNT 52 PQL_DWSDEFAULT 287 PQL_DWSEXTENT 387 PQL_DWSQUOTA 337 VIRTUALPAGECNT 3325 WSMAX 387 2 Configuration Resource Requirements ----------------------------------- GBLPAGES add 264 GBLPAGFIL add 264 GBLSECTIONS add 3 LOCKIDTBL add 160 SPTREQ add 221 SRPCOUNTV add 160 3 Allocated Nonpaged Memory DSM/PHYSICAL_PAGES 221 Press RETURN to continue, '^' to exit The following sections describe SYSGEN requirements: 1 Minimum SYSGEN Values You must set the SYSGEN parameters listed in this section to at least the displayed values. 2 Configuration Resource Requirements Add at least the values displayed in this section to whatever the OpenVMS operating system requires for basic system operation (usually these are the current SYSGEN values). For more information about the OpenVMS System Generation Utility (SYSGEN) and SYSGEN parameters, see the OpenVMS System Management Utilities Reference Manual, published by Digital Equipment Corporation. The values displayed for the SYSGEN parameters are minimum suggested values. You normally use larger values for the parameters displayed in the minimum requirements section. Tuning the OpenVMS Operating System for Use with DSM 5-9 Allocated nonpaged memory (3) refers to the amount of nonpaged memory that you must allocate, using the DSM /PHYSICAL_PAGES=nnnn command line, before you can start this configuration. For more information about how to set up nonpaged memory for use with DSM, see the section "Configuring Nonpaged Memory" in this chapter. The next page displayed by the utility contains minimum suggested process quota requirements. Process Quota requirements for configuration PAYROLL Process Quota Value BYTLM 40960 ENQLM 300 FILLM 150 WSDEF 500 WSEXT 1200 ** WSQUO 1000 ** NOTE: This is a suggested minimum value for WSEXTENT. If you notice excessive paging while the configuration is in use, use a higher value for WSEXTENT. You may also want to consider the use of Nonpaged Memory for global buffers and mapped routine sections. You can give all users of the configuration a minimum of these quota values. If you are using smaller values than those displayed, individual users' performance is affected. Some users will not be able to use DSM at all. If you use larger values, it will be at the expense of some amount of system memory. For more information about setting up process quotas for users, see the Digital publication, OpenVMS System Management Utilities Reference Manual. If the WSEXTENT value becomes large, ^MEMREQ suggests that you use nonpaged physical memory for the global buffers. Using nonpaged memory for global buffers and mapped routine sections enables you to reduce working set sizes for individual users while improving system performance. 5-10 Tuning the OpenVMS Operating System for Use with DSM The summary reports for setting process quotas and SYSGEN parameters are now complete. This constitutes most of the information that you need to adjust system parameters. If you would like to see a breakdown of how DSM uses memory, answer YES to the next question that ^MEMREQ displays. The first page of the detailed report is a summary of the resource requirements for the shared sections (the disk buffers, mapped routine sections, and other shared data). The SPTREQ, GBLPAGES, GBLPAGFIL, and GBLSECT values are the amounts used to compute summary values previously reported. The value indicated by the /PHYSICAL_PAGES=nnnn command line qualifier indicates the nonpaged memory that should be set aside for the exclusive use of this configuration. The following is an example of the next ^MEMREQ page: Display a detailed report of memory utilization ? [Y or N] Y Shared memory parameters for configuration PAYROLL Section Name Pages DSM/PHYS=x SPTREQ GBLPAGES GBLPAGFIL GBLSECT DSM$CACHE 731 *** *** 739 739 2 DSM$BAGAAA_SEC 123 123 123 1 1 1 %JOB 256 *** *** 256 256 2 TOTAL 1110 123 123 996 996 5 ** NOTE: This configuration requires 123 pages of real physical memory. If you have not done so already, please allocate at least this many pages using the DCL command line: $ DSM/PHYSICAL_PAGES=123 You need the CMKRNL and SYSGBL privileges. Press RETURN to continue, '^' to exit The next display is a summary of the virtual memory requirements for the configuration. The values displayed here were used to calculate the suggested SYSGEN parame- ters on the first display. Therefore, the configuration NEW, defined for 32 users, might display the following: Tuning the OpenVMS Operating System for Use with DSM 5-11 Virtual memory requirements for configuration NEW Section Name Pages x 32 users 1 Shared sections DSM Shared Image (Code) 886 886 Read-only VMS pages 1385 1385 PFN Mapped Gbl Sections 123 123 Read/Write Gbl Sections 996 996 2 Private sections DSM Shared Image (Data) 73 2336 Process-writable VMS pages 255 8160 Symbol Table 200 6400 Routine Buffers 41 1312 Total 3703 21342 Press RETURN to continue, '^' to exit The display is divided into two sets of values: 1 Shared sections Shared sections are pieces of virtual memory that different processes can access in common. 2 Private sections Private sections are those portions of virtual memory that are owned and used separately by each individual process. In the previous example, the shared memory requirement for the DSM image is 886 pages. Because this is a shared section, all 32 users share the same copy of the image, and only 886 pages of memory are required for all of them. Each process, however, has its own (unshared) symbol table. Because the symbol tables are not shared, each process needs its own memory for the symbol table and has 32 users * 200 pages or 6400 pages total. Note that ^MEMREQ assumes that DSM has been installed as a shared image, using the OpenVMS Install Utility. 5-12 Tuning the OpenVMS Operating System for Use with DSM Modifying OpenVMS System Parameters Once you have collected the necessary SYSGEN parameter value adjustments using the ^MEMREQ Utility, use the OpenVMS Autogen Utility to modify the relevant SYSGEN parameters. o If you plan to have only one configuration running on your system, run the ^MEMREQ Utility for that configuration. For all parameters listed under the heading Minimum SYSGEN Values, use the reported value only if it is higher than the current SYSGEN value. For all parameters listed under the heading Configuration Resource Requirements, use SYSGEN to determine whether there are sufficient system resources to support the configuration. If additional resources are necessary, add the required value to the current SYSGEN value to produce the new SYSGEN value. o If you plan to have multiple DSM environments running DSM configurations at the same time, you need to run ^MEMREQ on each configuration. For all parameters listed under the heading Minimum SYSGEN Values, select the highest value reported from all configurations as the new SYSGEN value, only if it is higher than the current SYSGEN value. For all parameters listed under the heading Configuration Resource Requirements, use SYSGEN to determine whether there are sufficient system resources to support the configuration. If additional resources are necessary, total the values for each parameter for all configurations and add this sum to the current SYSGEN value. Use SYSGEN to inspect the current value for any SYSGEN parameter. For example, to inspect the value of the SPTREQ parameter, use the following command sequence: $ RUN SYS$SYSTEM:SYSGEN SYSGEN> SHOW SPTREQ Tuning the OpenVMS Operating System for Use with DSM 5-13 Edit the file called SYS$SYSTEM:MODPARAMS.DAT to record site-specific SYSGEN parameter values. AUTOGEN uses this file to establish system parameters. For more information, see the OpenVMS System Manager's Manual, published by Digital Equipment Corporation. The following is an example of how some SYSGEN values are specified in MODPARAMS.DAT: ! ! Site specific AUTOGEN data file. In a VMScluster where a common ! system disk is being used, this file should reside in ! SYS$SPECIFIC:[SYSEXE], not a common system directory. ! ! Add modifications that you wish to make to AUTOGEN's hardware ! configuration data, system parameter calculations, and page, ! swap, and dump file sizes to the bottom of this file. ! ! Modification history: ! ! 8-September-1997 RSC - Digital ! Recommendations from ^MEMREQ ! GBLPAGES = 10000 GBLPAGFIL = 9000 GBLSECTIONS = 200 WSMAX = 2048 LOCKIDTBL = 4300 MAXPROCESSCNT = 402 BALSETCNT = 400 VIRTUALPAGECNT = 30000 SPTREQ = 16000 Use AUTOGEN to incorporate these values then reboot the system with the new values for these parameters. The OpenVMS Autogen Utility uses the values supplied within MODPARAMS.DAT to adjust other related parameters in a complementary fashion. Therefore, avoid using SYSGEN to directly manipulate SYSGEN parameters. Run AUTOGEN using the following command line to modify the system parameters and reboot the system: $ @SYS$UPDATE:AUTOGEN SAVPARAMS REBOOT 5-14 Tuning the OpenVMS Operating System for Use with DSM Page and Swap File Size Sufficient space in the OpenVMS page and swap files is critical to system performance. Insufficient swap file space can cause processes to enter the RWSWP state and prevent other DSM users from accessing DSM globals. Insufficient page or swap file space can cause the system to hang. Pageable global pages allocated for the Write Demon buffers are paged against the primary page file. This is important to be aware of when you set up secondary page and swap files. It can present a problem if you create a very small primary page file and intend to use a secondary page file for user processes. DSM startup fails if there are insufficient free global pages in the primary page file. By using the DCL command SHOW MEMORY/FILE/FULL, you can monitor page and swap file use on a running system. Use the command file SWAPFILES.COM in SYS$UPDATE to modify the size of the primary page and swap files. Adjust the page file so that its size is greater than twice the usage requirements. Adjust the swap file size so that at least one-fourth of the file is unused and reboot the system. For more information, see the Digital publication, OpenVMS System Manager's Manual. If you need to create secondary page or swap files, use the OpenVMS System Generation Utility (SYSGEN). For the procedures used to set up secondary page and swap files, see the Digital publication OpenVMS System Manager's Manual. Configuring DSM Shared Memory When you define a configuration using the ^CONFIG Utility, you can elect to use nonpaged memory to store all data structures that are shared by DSM users. Shared data includes: o Database disk buffers o Routine mapped sections o Volume set and UCI tables Tuning the OpenVMS Operating System for Use with DSM 5-15 o Miscellaneous process-specific data structures Nonpaged memory is an alternative to using shared global sections for storage of shared data. Each storage technique has different characteristics that you should consider when setting up your configuration. o Shared global sections Shared global sections are segments of virtual memory that are established at DSM startup time. - Shared global sections use memory in a dynamic fashion. Virtual memory is allocated at DSM startup and deallocated at shutdown. - Shared global section memory pages are pageable. Memory use for DSM use is traded against use of memory by other activities on the system. - The working set size of DSM processes is highly sensitive to the size of the shared global section. Large memory sections increase the paging incurred by DSM users if their working set sizes are too small. Large working set sizes increase real memory usage by each DSM user and require larger page and swap file allocations. - Use of shared global sections can require modifica- tions to the SYSGEN parameters, GBLPAGES, GBLPAGFIL, and GBLSECTIONS, depending on the size of disk cache and number of mapped routine sets. - The Write Demon is responsible for creating and initializing the shared global section during configuration startup. o Nonpaged memory Nonpaged memory uses dedicated physical memory for shared data and mapped routine sets. - Nonpaged memory is pre-allocated and dedicated for use by DSM. After it is allocated, nonpaged memory cannot be deallocated or used for anything but DSM shared data. Memory is allocated directly from the OpenVMS free list. 5-16 Tuning the OpenVMS Operating System for Use with DSM - Nonpaged memory is not paged, regardless of the number of buffers configured. Overall process paging is significantly reduced. - The working set size of DSM processes is not increased significantly if you increase the size of the shared data or buffers. This decreases real memory use by each DSM process and reduces the size of the page and swap files. - You must modify the SYSGEN parameter SPTREQ and allocate physical memory during OpenVMS system startup. - The Write Demon is responsible for partitioning a segment of the pre-allocated nonpaged memory for use with the starting configuration. InterSystems recommends that you use shared global sections in situations when flexibility and balanced resource sharing are the major objectives. Support for shared global sections is intended for development or test environments in which configuration characteristics are rapidly changing. Also consider use of global sections if you use your OpenVMS system primarily for anything other than a DSM application. InterSystems recommends use of nonpaged memory for situations where performance and efficient use of memory resources is necessary to support a large capacity DSM application. Support for nonpaged memory is intended primarily for use in stable, production-level application environments where memory requirements, work load, and capacities are well known. If you use your OpenVMS system primarily to support a DSM application, consider using nonpaged memory for shared data. Configuring Nonpaged Memory Options in the ^CONFIG Utility allow you to select the shared sections (disk buffers, mapped routines, or both) that will be resident in nonpaged memory. The disk buffers can be resident in nonpaged memory independently of whether any of the mapped routine sections are resident in nonpaged memory. Tuning the OpenVMS Operating System for Use with DSM 5-17 To use nonpaged memory, you must permanently allocate a fixed portion of contiguous physical memory from the OpenVMS free list for exclusive use by DSM. Allocate this memory with the DSM /PHYSICAL_PAGES=nnnn command line qualifier. The allocated memory serves as a pool of memory used by all running DSM configurations that have selected the nonpaged memory option. DSM manages this memory so that it is shared among one or more DSM configurations. The following command line allocates 10,000 pages (5MB) of physical memory: $ DSM/PHYSICAL_PAGES=10000 The CMKRNL and SYSGBL privileges are required to enter this command line. If you re-enter the DSM/PHYSICAL_ PAGES=nnnn command line with a larger number of pages specified, DSM allocates enough additional pages to reach the requested value. ________________________Note ________________________ After you allocate physical memory with the /PHYSICAL_PAGES=nnnn command line qualifier, you cannot deallocate it. You can reuse it and share it among various DSM environments on the same system, but no facility other than DSM can access it. Be sure to leave enough physical memory so that any other OpenVMS layered products can run properly. _____________________________________________________ You must configure one additional system page-table entry for each page allocated. Therefore, you must increase the SYSGEN parameter SPTREQ by an equal amount, then reboot your system. DSM allocates physically contiguous memory from the OpenVMS free list when you use the DSM/PHYSICAL_PAGES=nnnn command line. Because the free list becomes physically fragmented as the system runs, it is usually necessary to allocate the pages immediately following the reboot of your system. This is especially true if you are attempting to allocate a large number of pages. 5-18 Tuning the OpenVMS Operating System for Use with DSM You can configure your system to automatically al- locate the required pages at OpenVMS boot time. The SYS$STARTUP:DSM$INSTALL_SITE.COM procedure is supplied as a template for DSM activities required at OpenVMS system startup. You can customize this procedure for your site. Locate the relevant part of the DSM$INSTALL_SITE command procedure that allocates pages for nonpaged memory and make the appropriate changes. This section is shown in the following example. $ !------------------------------------------------------------------- $ ! $ ! PHYSICAL MEMORY ALLOCATION $ ! $ ! If you choose to use physically mapped disk buffers, then you must $ ! allocate contiguous system memory. Typically, this is done at OpenVMS $ ! boot time. The total number of pages to allocate is determined by $ ! summing the requirements of each configuration you plan to run $ ! simultaneously. In the following command line, remove the comment $ ! character (!), and edit the line so that: $ ! $ ! nn = Total # of pages to allocate $ ! $ ! DSM/MANAGER/PHYSICAL=nn $ ! $ !------------------------------------------------------------------- $ ! Create your configurations to use nonpaged memory using the following procedure: 1. Determine the number of physical pages and SPTREQs to allocate: a. Define all the configurations you plan to run at the same time. If you plan to run only one configuration that uses nonpaged memory, define only one configuration. b. Build any mapped routine sets you plan to install into nonpaged memory. c. Initialize the before-image journal file if you plan to use Before-Image Journaling. Tuning the OpenVMS Operating System for Use with DSM 5-19 d. For each configuration, use the ^MEMREQ Utility to display the number of physical pages and number of SPTREQs required by each configuration. e. Sum the requirements for physical pages and SPTREQs for all configurations. 2. Log in to the OpenVMS system manager account or a privileged account. 3. Edit the SYS$STARTUP:DSM$INSTALL.COM procedure to allocate the appropriate number of physical pages at system startup. 4. Determine the current value of SPTREQ. Edit MODPARAMS.DAT and add the value suggested by ^MEMREQ to the current value of SPTREQ. See the section "Modifying OpenVMS System Parameters" in this chapter to find out how to modify the SYS$SYSTEM:MODPARAMS.DAT file. 5. Run the OpenVMS AUTOGEN procedure with the REBOOT option. The system reboots when AUTOGEN is complete. If you have configured the DSM$INSTALL command procedure to run at system boot time, the nonpaged memory should be available for use by DSM configurations. If memory is allocated properly, a system global section is created with the name DSM$SYSBUF. Use the OpenVMS Install Utility to verify the existence of DSM$SYSBUF as a system permanent section (PRM SYS), using the following command line in a privileged account: $ INSTALL LIST/GLOBAL System Global Sections DSM$SYSBUF (73EAEFBE) PRM SYS Pagcnt/Refcnt=0 . . . 5-20 Tuning the OpenVMS Operating System for Use with DSM The DSM$SYSBUF section contains the database that manages the allocation of physical pages for use by various DSM configurations. You can use the ^MEMUSE Utility to display the nonpaged memory that has been allocated on a system and how much is currently in use by each running configuration. Use ^MEMUSE and ^MEMREQ to determine if you have set aside enough physical memory to start up your DSM configurations. Tuning the OpenVMS Operating System for Use with DSM 5-21 6 ________________________________________________________________ Optimizing DSM This chapter describes the following: o Optimizing DSM Applications o Using Mapped Routines o Using the Global Statistics Utility (^GLSSTA) For information about database concepts and for more detailed information about managing volume sets and globals, see the DSM for OpenVMS Database Operations Guide. Optimizing DSM Applications To optimize the throughput of an OpenVMS system running a DSM application, do the following: o Separate your system disk from your global database. o Make sure your DSM volumes are contiguous files. o Use DSM volume sets rather than RMS ISAM files for global storage. o Configure enough disk buffers for the global access rate of your applications. Configure a disk cache that is large enough to eliminate global buffer Write Waits. Add disk buffers to the configuration until there are zero buffer write waits (^GLSSTA) and until the number of physical reads does not decrease with the addition of new buffers. o Tune OpenVMS parameters for special DSM requirements using the OpenVMS AUTOGEN procedure. Be sure to make the working set quota (WSQUOTA) of the DSM manager adequate for the background processes that operate in the DSM run-time environment. Optimizing DSM 6-1 o Whenever possible, use low values for the following DSM command line qualifiers to reduce memory requirements: - /SOURCE_BUFFER_SIZE=n - /STACK_SIZE=n - /SYMBOL_TABLE_SIZE=n For more information about these qualifiers, see the DSM for OpenVMS Programmer's Guide. o Map frequently-used routines into virtual memory sections, as described in the section "Using Mapped Routines." Specify the average size of your mapped routines (in pages) using the ^CONFIG or ^RMINS Utility. o Favor certain DSM application programming techniques over others. For more information about programming optimization techniques, see the DSM for OpenVMS Programmer's Guide. o Use non-paged memory for shared memory. See Chapter 5 for more information. o Optimize disk access by placing heavily accessed volume files on separate disk units. o Place heavily modified globals in separate volume sets. The following sections describe routine mapping and out- line programming techniques that improve the performance of DSM. Using Mapped Routines You can map precompiled DSM routines in a OpenVMS virtual memory section using the DSM Mapped Routine Utilities (^RMAP). After you map a section, users can access its contents (read only) from the DSM image. Using mapped routines can improve the response time of your application. Mapped routines improve performance because of the following: o Virtual memory paging replaces loading a routine from disk. This improves response time because paging I/O is the fastest I/O on a OpenVMS system. 6-2 Optimizing DSM o The most frequently used DSM routines tend to remain in physical memory, page faults occur from the free page list rather than from the disk page file. The virtual memory sections used for mapped routines are permanent system global sections. All processes running under a DSM environment share the system global sections. Mapped Routine Utilities (^RMAP) The Routine Mapping Utility (^RMAP) provides the following utilities to help you manage mapped routines: >D ^RMAP Routine Mapping Utilities 1. BUILD (^RMBLD) 2. CONTENTS (^RMSHO) 3. DELETE (^RMDEL) 4. DIRECTORY (MAP^%RD) 5. DISABLE ROUTINE (^RMDIS) 6. INSTALL (^RMINS) 7. SHOW INSTALLED (MAPSET^RMSHO) Select Option > Table 6-1 describes each of the Routine Mapping utili- ties. Table_6-1_Routine_Mapping_Utilities_______________________ Routine_Name__Description_________________________________ ^RMBLD Builds a file containing precompiled DSM routines that can be mapped into a virtual memory section. ^RMSHO Lists the names of all routines contained in a specified mapped routine file. (continued on next page) Optimizing DSM 6-3 Table_6-1_(Cont.)_Routine_Mapping_Utilities_______________ Routine_Name__Description_________________________________ ^RMDEL Allows you to delete a routine set interactively. Normally, mapped routine sections are deleted when you run the ^SHUTDWN Utility. However, you can use ^RMDEL to delete a routine set without shutting down your DSM configuration. Note that the operating system marks sections for deletion, but does not actually delete a section until all processes cease mapping to it. MAP^%RD Displays a list of the routines that are mapped for your current application and library directories. ^RMDIS Disables individual routines in a mapped routine set. Use this utility if, after installing a routine set, you decide that you do not want to run the copy of a routine that is installed in the global section. This is useful when a bug is fixed in a routine, and you want your users to run the new version of the routine, which must be loaded from a volume set, rather than the old version of the precompiled routine, which is in the mapped routine set. ^RMINS Allows you to install a routine set interactively. You can map routine sets that were not specified in ^CONFIG. MAPSET^RMSHO Displays a list of currently installed ______________mapped_routine_sets.________________________ Determining Mapped Routine Section Memory Requirements Before you can install a permanent global section, you may need to modify the SYSGEN parameters GBLPAGES and GBLSECTIONS to accommodate all mapped routine files that are to be installed. GBLSECTIONS must be large enough to accommodate twice the number of simultaneously installed DSM mapped routine sections and all other 6-4 Optimizing DSM OpenVMS installed images and sections. GBLPAGES must be large enough to accommodate the additional total size in pages of all DSM mapped routine sections (plus one extra page per routine section) that are to be installed simultaneously. To install a paged mapped routine section successfully, you must be able to map the section in the OpenVMS global page table contiguously. Use the F$GETSYI lexical function to determine the number of contiguous global pages needed for mapping routines as follows: 1. Find the maximum size of a global section that can be created by entering the following: $ WRITE SYS$COMMAND F$GETSYI("CONTIG_GBLPAGES") 2. Find the allocation size of the mapped routine that you want to install by entering the following: $ DIR/SIZE=ALLOC filename where: filename is the name of the file that you intend to map as the routine section 3. For the mapped routine section to be installed, the number of contiguous global pages (from step 1) must be at least two greater than the allocation size of the file (from step 2). 4. Also, you must have at least two free global section descriptors available. You can determine this by entering the following: $ WRITE SYS$COMMAND F$GETSYI("FREE_GBLSECTS") To install a non-paged mapped routine section (one that uses memory allocated by the /PHYSICAL_PAGES=nnnn command line qualifier) there must be sufficient free pages in the DSM physical memory section. You can determine how much space remains in this section using the ^MEMUSE Utility. Also, you need one free global section descriptor (see step 4). Optimizing DSM 6-5 Use the ^MEMREQ Utility to determine the proper SYSGEN parameters to ensure that you have sufficient memory resources (either paged or non-paged). First, create all of the mapped routine files that you require and include them in a configuration. Then, run the ^MEMREQ Utility to get the total memory requirements for that configuration. For more information about tuning OpenVMS parameters, see Chapter 5. Creating and Mapping Routine Sets Routines are mapped in sets. To create a set of routines and map them, do the following: 1. Start up a DSM configuration. You can create mapped routine sets only when a configuration is running. You may want to disable user logins from DSM until after you have installed mapped routines. 2. Run DSM with the /MANAGER command line qualifier. 3. Build a mapped routine file with the ^RMBLD Utility. This utility builds a file containing precompiled DSM routines that can be mapped into a virtual memory section. The ^RMBLD Utility asks for the UCI and volume set (if more than one volume set is mounted in your configuration) where the routines you want to map reside. The ^RMBLD Utility then calls the ^%RSEL Utility to allow you to select the routines that you want to include in the mapped routine set. You can build a mapped routine file for each UCI on each volume set. You can also create mapped routine sets for Library Utilities (those with names starting with a %). A library mapped routine set is associated with a library UCI and volume set. Mapped routine files use the following naming convention: ucivol.vir 6-6 Optimizing DSM where: uci is a 3-character UCI name vol is a 3-character volume set name vir is the file extension In the following example, ^RMBLD creates a mapped routine set for an application routine directory. >D ^RMBLD Build a DSM Mapped Routine Set Enter the UCI name in which the routines reside > PHA routine(s) ? > BILL routine(s) ? > DICT routine(s) ? > MENU routine(s) ? > PAY routine(s) ? > REC routine(s) ? > Using mapped routine file: PHAEMP.VIR Device and directory to hold this file Writing mapped routines to: DISK$USER:[DSMMGR]PHAEMP.VIR;2 Setting up routine information ... Writing name subsection Writing descriptor subsection Writing program body section BILL 4248 bytes DICT 1325 bytes MENU 3737 bytes PAY 11417 bytes REC 8993 bytes Completing header information This mapped routine set contains 5 routines. The average routine size is 5944 bytes. The average routine will occupy 12 pages of memory. Installing this mapped routine set requires 65 pages of memory. Optimizing DSM 6-7 Note that the ^RMBLD Utility calls the ^%RSEL Utility, which allows you to specify existing mapped routine file names at the routine(s) ? > prompt. This allows you to select quickly all routines that have previously been included in a mapped routine set. To include an existing mapped routine file, enter a left angle bracket (<) before the file specification. For example: >D ^RMBLD Build a DSM Mapped Routine Set Enter the UCI name in which the routines reside > PHA routine(s) ? > routine(s) ? > ^L BILL DICT MENU PAY REC routine(s) ? > You can use the SAVE^RTHISTP Utility to create a file that contains the names of the most frequently accessed routines. This file name can then be entered at the routine(s) ? > prompt. For example: >D ^RMBLD Build a DSM Mapped Routine Set Enter the UCI name in which the routines reside > PHA routine(s) ? > routine(s) ? > ^L BILL DICT HIRE MENU PAY REC . . . VACAT routine(s) ? > For more information about the SAVE^RTHISTP Utility, see the section "Using the Performance Statistics Utility" in this chapter. 6-8 Optimizing DSM ________________________Note ________________________ To conserve system resources and memory, map only your most frequently called routines. Mapping routines that are rarely called wastes memory and does not improve the performance of your system. _____________________________________________________ 4. To include support for mapped routine sets on configuration startup, run ^CONFIG and answer all of the questions pertaining to mapped routines. Example 6-1 describes how to include mapped routines. Example 6-1 Using ^CONFIG to Include Support for Mapped Routines >D ^CONFIG Build DSM Configuration Type ? for HELP at any time Would you like extended help [Y OR N] ? Y Enter the configuration identifier . . . Include support for mapped routines [Y OR N] Y How many routines do you want to install > 1 Enter the number of routine sets you want to have installed during the startup process. The routine sets should already be built using the ^RMBLD Utility. Enter the UCI name in which the routines reside ? > PHA Enter the UCI name that holds the routines that you want to include in the mapped section. UCI names must be 3 uppercase alphabetic characters. The UCI and volume set names will be used to construct the OpenVMS global section name given to this routine set. Enter the volume set name in which the routines reside ? > EMP (continued on next page) Optimizing DSM 6-9 Example 6-1 (Cont.) Using ^CONFIG to Include Support for Mapped Routines Enter the volume set name that holds the routines you want to include in the mapped section. Volume set names must be 3 uppercase alphabetic characters. The UCI and volume set names will be used to construct the OpenVMS global section name given to the routine set. Using mapped routine file: PHAEMP.VIR Enter the device and directory that contains PHAEMP.VIR Enter a valid OpenVMS device and directory specification. Use non-paged memory for this routine section [Y OR N] ? Mapped routine sections, like disk cache, can be resident in non-paged memory. Because mapped routine sections are shared among many DSM users, and they can require a significant amount of memory, using non-paged memory reduces the amount of page fault activity each DSM process incurs. To use non-paged memory, you must have set aside enough real physical memory to contain the mapped routine sections for this configuration using the /PHYSICAL_PAGES=nnnn command line qualifier. Use the ^MEMREQ Utility to determine the non-paged physical memory requirements for this configuration. Answer YES if you have allocated, or will allocate, this memory and want to use it for non-paged access to this mapped routine section. Answer NO if the routine section should be mapped using paged memory. Page fault cluster size <8> The page fault cluster size is the number of 512-byte memory pages that will be paged in when access to a routine within this routine section causes a page fault. The optimal cluster size is roughly equivalent to the average size of an application routine. Assuming that an average routine size is 4KB, then a good page fault cluster size would be 8. . . . 5. Run the ^STU Utility to start DSM and install the mapped sections. 6-10 Optimizing DSM If you do not include support for mapped routines when you run the ^CONFIG Utility (step 4), you can use the ^RMINS Utility to install the mapped routine set. For example: >D ^RMINS Install Mapped Routine Sets Enter the UCI name in which the routines reside ? > PHA Using mapped routine file: PHAEMP.VIR Enter the device and directory that contains PHAEMP.VIR Use non-paged memory for this routine section [Y OR N] ? Page fault cluster size <8> DISK$USER:[DSMMGR]PHAEMP.VIR;2 installed as DSM$00001_MAPR_PHAEMP (62 blocks) Executing Mapped Routines DSM associates your application routine directory and library routine directory with specific system global sections. The global section names are as follows: o DSM$nnnnn_MAPR_UCIVOL - mapped routine set section o DSM$nnnnn_MAPT_UCIVOL - routine disable section where: nnnnn is the unique DSM environment identifier UCI is a 3-character UCI name VOL is a 3-character volume set name If a global section is installed for your application routine directory, DSM searches for a routine in the global section. If the routine is not present in the global section, DSM loads the routine from your application routine directory. If a global section is installed for your library routine directory, DSM searches for library routines (%) in the global section. If the library routine is not present in the global section, DSM loads the routine from your library routine directory. Optimizing DSM 6-11 If you change routine directories by executing the %SETUCI external routine and a mapped routine set is installed for your new routine directory, DSM automatically maps to the global section associated with your new routine directory. For example: >D MAP^%RD Output Device ? <0> No library routines mapped DSM mapped application routines 26-JUN-1997 12:08 DSM$00005_MAPR_PHAEMP BILL DICT MENU PAY REC 5 routines The following example displays the mapped routines associated with your new application routine directory. >W $&ZLIB.%SETUCI("DBS","BJL","R") 1 >D MAP^%RD Output Device ? <0> No library routines mapped DSM mapped application routines 26-JAN-1997 12:09 [DBS,BJL] DSM$00005_MAPR_DBSBJL ADBOOK STATE UPCASE 3 routines Use the MAPSET^RMSHO Utility to display a list of the currently installed routines. For example: >D MAPSET^RMSHO The following mapped routine sets are currently installed: Routine Directory Global Section Name [MGR,BJL] DSM$00005_MAPR_MGRBJL [DBS,BJL] DSM$00005_MAPR_DBSBJL [PHA,EMP] DSM$00005_MAPR_PHAEMP 6-12 Optimizing DSM The following example runs ^RMDEL to delete a mapped routine section: >D ^RMDEL Delete a Mapped Routine Section Enter the UCI name in which the routines reside > MGR DSM$00005_MAPR_MGRBJL - marked for deletion Disabling Individual Mapped Routines If you change a routine that resides in an installed mapped routine set, you can disable access to the mapped routine. When you disable access to a mapped routine, the precompiled code is loaded from the volume set, rather than from the virtual memory section. Use the ^RMDIS Utility to disable a mapped routine. For example: >D ^RMDIS Enable/Disable Mapped Routines Enter the UCI name in which the routines reside > DBS Enter ^D to display routines mapped to [DBS,BJL] Enter the name of the routine that you want to enable or disable mapped access to. The routine must be in the OpenVMS global section mapped by the UCI and volume set you selected. Enter ^D to see a display of all routines in this section. Enter * to select all routines in this section. Enter ^L to list currently selected routines. Routine(s) > ^D DSM mapped application routines 11-MAY-1997 11:09 [DBS,BJL] DSM$00005_MAPR_DBSBJL ADBOOK STATE UPCASE 3 routines Routine(s) > ADBOOK Routine(s) > Disable or Enable mapped access [D or E] > D Optimizing DSM 6-13 Enter D to disable mapped access to the routine(s), and force the routine(s) to be loaded from the routine directory. Enter E to enable mapped access to the routine(s). ADBOOK Disabled Do the following to include a new version of a routine in a mapped routine set: 1. Run the ^RMBLD Utility to build a new mapped routine file. 2. Run the ^RMDEL Utility to delete the old mapped routine section. 3. Run the ^RMINS Utility to install the new mapped routine set. Note that the OpenVMS operating system only marks the old mapped routine section for deletion, but does not actually delete a section until all processes cease mapping to it. Alternatively, you can wait until the next time you shut down and start up your configuration to install the new mapped routine set. Considerations When Using Mapped Routines Because mapped routine files contain precompiled code only, DSM must be able to load the source version of a routine to perform the following operations: o Executing the $TEXT function, unless the line starts with a double semicolon (;;). If a line starts with a double semicolon, the DSM precompiler includes the source line in the precompiled routine. o Generating a DSM error message that includes the line containing the error. When DSM performs either of these operations, it loads the source code, then continues to execute code from the mapped section. Frequent performance of these two operations adversely affects the performance of a mapped application. 6-14 Optimizing DSM Using the Global Statistics Utility (^GLSSTA) Use the Global Statistics Utility (^GLSSTA) to record information on global system performance. Enter the following to run ^GLSSTA: >D ^GLSSTA The utility displays the following menu: Global Statistics Menu 1. MONITOR (MONITOR^GLSSTA) 2. RECORD (RECORD^GLSSTA) 3. REPLAY (REPLAY^GLSSTA) Select Option > Note the following: o The MONITOR^GLSSTA Utility is used to interactively monitor global system performance. o The RECORD^GLSSTA Utility writes the global statistics to an output device. This option records statistics on all four groups. o The REPLAY^GLSSTA Utility allows you to replay the information that was recorded using RECORD^GLSSTA. This option lets you replay up to three of the options at a time. You can display read/write statistics, global access statistics, and synchronization statistics in separate reports by entering the letter of the option you want after the Display options: prompt. The default is . The reports are displayed interactively on your terminal. To stop the display, press Return. To display another report, enter the letter of the option you want after the Display options: prompt. To exit the routine, type a circumflex (^) and press Return. The following is an example of the MONITOR^GLSSTA Utility: Optimizing DSM 6-15 >D MONITOR^GLSSTA Monitor Global Statistics: Interval (in seconds): <3> A. Read/Write Statistics B. Global Access Statistics C. Synchronization Statistics D. Local Buffering Statistics Enter the group of statistics (A, B, C, or D) to gather and display. You can select up to 3 of the 4 groups of statistics at a time. Display options: ADB After you press Return, the report is displayed on your terminal as shown in Example 6-2. Example 6-2 ^GLSSTA Report DSM Global Statistics 22-JUN-1997 12:33:23.68 CUR AVE MIN MAX ABS LAST 1 Physical Reads 0.00 0.00 0.00 0.00 792 0 2 Logical Reads 2147.00 2661.69 2147.00 3194.14 6193767 6441 3 Physical Writes 86.67 67.80 48.28 86.67 15164 260 4 Logical Writes 55.33 193.90 55.33 337.24 60856 166 5 Search Last Tries 21.67 49.49 21.67 78.28 25446 65 6 Search Last Successes 0.33 0.17 0.00 0.33 72 1 7 Global Accesses 1593.67 1897.97 1593.67 2212.76 2093374 4781 8 Global Gets 1568.00 1821.02 1568.00 2082.76 2062266 4704 9 Global $DATAs 0.00 0.00 0.00 0.00 8 0 10 Global $NEXTs 0.00 0.00 0.00 0.00 16 0 11 Global Sets 22.67 50.17 22.67 78.62 25857 68 12 Global Kills 3.00 26.78 3.00 51.38 5227 9 13 Local Buffer Tries 1501.33 1747.97 1501.33 2003.10 1836860 4504 14 Local Buffer Successes 907.00 1090.00 907.00 1279.31 65391 2721 15 Local Buffer Invalidates 64.00 70.17 64.00 76.55 224874 192 16 Read Accesses 1568.00 1821.02 1568.00 2082.76 2062290 4704 17 Write Accesses 25.67 76.95 25.67 130.00 31084 77 The CUR, AVE, MIN, and MAX columns represent per-second averages. The entries displayed are interpreted as follows: 1 Physical Reads 6-16 Optimizing DSM The number of times a real physical disk read was performed to read a database block into DSM global buffer cache. 2 Logical Reads The number of times a database block was required for a global access. 3 Physical Writes The number of DSM blocks written to disk by the DSM Write Demon. 4 Logical Writes The number of times a disk block was modified by a DSM process and marked as needs writing. 5 Search Last Tries The number of times that a DSM process attempted to resolve a global reference by checking the last DSM block that it referenced. 6 Search Last Successes The number of times that a DSM process actually resolved a global reference by checking only the last DSM block that it referenced. 7 Global Accesses The total number of global GET, SET, KILL, $DATA, and $NEXT operations performed by the DSM global system. 8 Global Gets The total number of global variable reads done. For example: S A=^X(4) 9 Global $DATAs The total number of global variable $DATA operations done. For example: S A=$D(^X(4)) 10 Global $NEXTs Optimizing DSM 6-17 The total number of global variable $NEXT operations done. For example: S A=$N(^X(-1)) S A=$O(^X("")) 11 Global Sets The total number of global variable SET operations done. For example: S ^X(4)="PATIENT" 12 Global Kills The total number of global variable KILL operations done. For example: K ^X(4) 13 Local Buffer Tries The number of times a process attempted to resolve a reference in a private buffer. 14 Local Buffer Successes The number of times a process resolved a reference in a private buffer. 15 Local Buffer Invalidates The number of times a local buffer was invalidated because of a LOCK executed by the process that owned the buffer. 16 Read Accesses The total number of global get, $DATA, and $ORDER operations performed. 17 Write Accesses The total number of global set and kill operations performed. If you select group C (Synchronization Statistics), the report is displayed as shown in Example 6-3. Example 6-3 ^GLSSTA Report (Synchronization Statistics) (continued on next page) 6-18 Optimizing DSM Example 6-3 (Cont.) ^GLSSTA Report (Synchronization Statistics) DSM Global Statistics 22-JUN-1997 12:33:23.68 CUR AVE MIN MAX ABS LAST 1 Global Seizes 34.67 31.52 34.67 34.67 388 104 2 Global Seize Waits 8.67 7.88 8.67 8.67 124 26 3 Global Access Waits 21.00 19.09 21.00 21.00 285 63 4 Directory Searches 23.00 111.82 123.00 123.00 1209 369 5 Block Allocates 9.33 8.48 9.33 9.33 133 28 6 Block Deallocates 15.00 13.64 15.00 15.00 141 45 7 Global Synch Waits 0.00 0.00 0.00 0.00 29 0 8 Global List Waits 9.00 8.18 9.00 9.00 316 27 9 Global Buffer Waits 10.67 9.70 10.67 10.67 351 32 10 Buffer Write Waits 0.00 0.00 0.00 0.00 0 0 The entries displayed are interpreted as follows: 1 Global Seizes The number of times that a volume set was exclusively owned by a DSM process while it performed a multiple- block update to the DSM database (either a block split or merge operation). 2 Global Seize Waits The number of times that a DSM process had to gain exclusive access to a volume set because other processes were already accessing it concurrently. 3 Global Access Waits The number of times that a DSM process had to wait to access a volume set because another process had it seized (exclusively owned). 4 Directory Searches The number of times that DSM processes searched the global directory of a volume set to satisfy a global reference. 5 Block Allocates The number of DSM blocks added to a DSM global structure, as in the case of a split operation. Optimizing DSM 6-19 6 Block Deallocates The number of DSM blocks removed from a DSM global structure and marked as free, as in the case of a merge operation. 7 Global Synch Waits The number of times that a DSM process had to wait for exclusive access to a data structure other than the actual DSM global buffers. 8 Global List Waits The number of times that a DSM process had to wait before searching for a DSM database block in cache. 9 Global Buffer Waits The number of times that a DSM process had to wait for exclusive access to a cached DSM database block. 10 Buffer Write Waits The number of times that a DSM process had to wait to read a new block into cache because the cache was full of unwritten modified blocks. High LOGICAL/PHYSICAL READ and LOGICAL/PHYSICAL WRITE ratios indicate that cache efficiency is correspondingly high. Low LOGICAL/PHYSICAL ratios indicate insufficient cache or extremely scattered database references. A high number of SEARCH LAST SUCCESSES indicates that the application is making good use of the DSM most recently used checking algorithm. Note that if the SEARCH LAST algorithm fails for a global reference, DSM must trace the global reference from the topmost pointer block back to the data level. Because this operation involves upwards of two database block accesses, a SEARCH LAST SUCCESS represents a substantial performance savings. Any of the Wait statistics (Seize Waits, Access Waits, Synch Waits, List Waits, Buffer Waits, and Write Waits) indicate that processes are contending for various DSM resources. The more that processes are forced to wait, the less concurrence there is in the global system. Furthermore, system overhead is expended when processes are forced to wait to coordinate access to the resources. 6-20 Optimizing DSM Under extreme conditions, buffer Write Waits can cause severe performance degradation. In these cases, extending the disk cache usually eliminates these problems. The global handler arbitrates access on a per-volume set basis. Consequently, you can increase the concurrency and efficiency of the database handler by moving the most frequently modified globals to separate volume sets. The other statistics are indicators of how much work the global system is doing and are not indicators of database efficiency. Performance Statistics (^PMF) You can measure performance by using the Performance Monitoring Facility (^PMF). The ^PMF facility is a set of performance monitoring tools that you can use to report on DSM performance across multiple nodes of a VMScluster. PMF reports detailed statistics summarized: o By cluster o By system o By volume set o By global In addition, ^PMF reports response-time metrics in a histogram format that describes the elapsed prompt-to- prompt time experienced by application users. ^PMF and ^RTH The ^PMF replaces the existing routine histogram utility set, ^RTH. ^RTH is still included in DSM for operational compatibility with previous releases. See Appendix C for information about using ^RTH. If you continue to use ^RTH, you should be aware of the following restrictions: o You cannot run ^RTH and ^PMF data collectors at the same time. o You must shut down PMF data collectors before starting an ^RTH data collection. Optimizing DSM 6-21 o You cannot use PMF reporting programs to report data collected by ^RTH. Using PMF to Monitor Performance You take the following steps to use PMF to monitor performance: 1. Run ^CONFIG for all configurations on which you want performance statistics. Answer YES in response to the ^CONFIG queries about PMF. 2. Access the ^PMF Utility Set to collect, report, and manage performance data. Including ^PMF Support in ^CONFIG You use ^CONFIG to: o Include support for the performance monitoring facility o Configure adequate process buffer space for collecting performance data You must use ^CONFIG to include support for ^PMF in every configuration on which you want performance monitoring reports. The following example shows how to use ^CONFIG to support ^PMF: > D ^CONFIG . . . Include support for Routine/Global Performance Histograms [Y OR N] ? The ^PMF Utility produces detailed reports and histograms on the performance of your application within the DSM environment. Frequency of access and modification to specific globals is reported along with statistics on routine calls and CPU utilization. You must reserve additional memory at DSM startup for purposes of performance data collection. Enter YES if you intend to use the ^PMF Utility. Enter NO if you do not want to use the ^PMF Utility. Include support for Routine/Global Performance Histograms [Y OR N] 6-22 Optimizing DSM Enter size in pages for the performance data buffer <50> ? Each running DSM process collects performance data within the PMF data buffer area. Entries in the PMF table require 28 bytes for every global and routine referenced during a data collection period. Globals and routines of the same name but from different volume sets or from different UCIs are considered unique. Enter the size in pages of the PMF buffer to reserve. Each page contains 512 bytes or enough space for approximately 18 entries. If PMF runs out of buffer space, a NO ROOM entry is made within the histogram report. You can then increase the buffer size and restart the configuration. Enter size in pages for the performance data buffer <50> . . . When the configuration starts, DSM automatically starts the ^PMF data collector process. The ^PMF data collector process remains idle until you request a collection session. Using the ^PMF Utility Set ^PMF divides the task of performance monitoring and reporting into three parts: o Data collection You use the ^PMF data collector process, ^PMFCOL, to collect raw performance data and save the data in date and time stamped collection sessions. o Report generation You use the ^PMFGEN Utility to select one or more collection sessions to use in generating a report and saving it for printing later. o Report output You use the ^PMFREP Utility to print a saved report to a device or file. Optimizing DSM 6-23 Take the following steps to use the ^PMF Utility options to collect and report on system data. 1. Use the ^PMFCOL option ^PMFMON to schedule a data collection for any or all configurations. You can specify collection times and intervals between collections. See the section "Scheduling a New Collection (^PMFMON)" for more information. 2. Use the options under the ^PMFDAT menu to monitor and control the collection process. You can use these options to: - List completed collections - List scheduled collections You can also use the ^PMFDAT menu options to delete both scheduled and completed collections. See the section "Using the Data Collection Utilities (^PMFDAT)" for more information. 3. After collections are completed, use the ^PMFGEN option under the ^PMFREP menu to assemble specified collections into a report. You can print the report, save it to a file, or display it on your monitor. You can also use ^PMFGEN menu to do the following: - List all reports on file - Print already compiled reports - Delete reports you no longer need. See the section "Using the Reporting Utilities (^PMFREP)" for more information. 4. Because space is always a vital concern, you can use the ^PMFDAT menu options to delete: - All collections - All collections made before a specified date See the section "Using the Data Collection Utilities (^PMFDAT)" for more information. 6-24 Optimizing DSM 5. If required for operational reasons, you can stop a PMF data collector process with the ^PMFCOL option, STOP^PMFCOL. You can start a PMF data collector process again with the PMFCOL option, START^PMFCOL. See the section "Using the Collector Control Utilities (^PMFCOL)" for more information. PMF Utility Conventions The ^PMF options use the following conventions: o Many of the options require that you specify a date or accept a default date. ^PMF allows you to specify dates and time in the following formats: DD-MMM-YYYY The date in standard OpenVMS format, as in 05-Oct-1997. DD-MMM The date in standard OpenVMS format, as in 05-Oct. This assumes that the you are specifying a date in the current year. T Today. Y Yesterday. T-n Today - n number of days ago. o Many options require you to specify several items; for example, the numbers of several data collections you want to include in a report. You can enter multiple items: - As a series of numbers separated by commas (2,4,7) - As a range of numbers separated by dashes (7-14) - As a combination of these formats (4,5-9,11) o Press Ctrl/Z or Ctrl/C to exit from an option. o Type a question mark (?) and press Return for help at any input prompt. o Type a circumflex (^) and press Return to repeat the previous input prompt. o When an option prompts you to specify a list of collections, you can enter * (asterisk) to see a list of all collections. Optimizing DSM 6-25 o When an option prompts you to specify dates on which collections were made, you can enter ^L (the up arrow character followed by L). o ^PMF options mark all collections that are in progress or have been collected from an inconsistent list of nodes with an asterisk (*). Accessing the PMF Utility Set You access the PMF Utility set (^PMF) through a menu interface. You use ^PMF while logged into DSM with the /MANAGER qualifier. The following example shows how to access ^PMF: > D ^PMF Performance Monitoring Utilities 1. COLLECTOR CONTROL UTILITIES (^PMFCOL) 2. DATA COLLECTION UTILITIES (^PMFDAT) 3. REPORTING UTILITIES (^PMFREP) Select Option > Using the Collector Control Utilities (^PMFCOL) You use the Collector Control Utilities (^PMFCOL) to control the PMF data collector process on one or more nodes of a VMScluster. The following shows how to choose the Collector Control Utilities: Performance Monitoring Utilities 1. COLLECTOR CONTROL UTILITIES (^PMFCOL) 2. DATA COLLECTION UTILITIES (^PMFDAT) 3. REPORTING UTILITIES (^PMFREP) Select Option > 1 Performance Data Collector Control Utilities 1. START (START^PMFCOL) 2. STATUS (STATUS^PMFCOL) 3. STOP (STOP^PMFCOL) Select Option > 6-26 Optimizing DSM Starting Data Collector Processes (START^PMFCOL) You use the Start Utility (START^PMFCOL) to start a data collector process on all nodes or on specified nodes. If the data collector process was stopped, DSM displays the process ID (PID) of the started data collector process. If the data collector process was not stopped, DSM displays the following message: Unable to start PMF Collector, a collector is already running on this node The following example shows how to use Start: Performance Data Collector Control Utilities 1. START (START^PMFCOL) 2. STATUS (STATUS^PMFCOL) 3. STOP (STOP^PMFCOL) Select Option > 1. START Start collector process on which nodes MTWAIN,OZONE DSM Performance Collector ... Started as DSM_PMF_1 (PID = 282000B8) DSM Performance Collector on OZONE ... Started as DSM_PMF_1 (PID = 280000C3) Determining the Status of Data Collector Processes (STATUS^PMFCOL) You use the Status Utility (STATUS^PMFCOL) to determine the status of all data collector processes. STATUS^PMFCOL displays a table that includes: o The name of the node o The state of the node's data collector process o A number indicating which session is being collected (if any) o Collection start date and time Optimizing DSM 6-27 The following example shows how to use Status: Performance Data Collector Control Utilities 1. START (START^PMFCOL) 2. STATUS (STATUS^PMFCOL) 3. STOP (STOP^PMFCOL) Select Option > 2. STATUS Performance Monitor Collection Process Status on 12-OCT-1997 15:15:35 Collection Collection Node State Session Start Date Start Time ---- ----- ------- ---------- ---------- ZEUS IDLE MTWAIN Collection Process not Started OZONE COLLECTING 4 1-SEP-1997 2:50:50 PM "IDLE" indicates that the process is inactive. No collections are in process. "Collection Process not Started" indicates that the collector process has been stopped (with STOP^PMFCOL). Stopping Data Collector Processes (STOP^PMFCOL) You use the Stop Utility (STOP^PMFCOL) to stop data collector processes on all nodes or on specified nodes. The following example shows how to use Stop: Performance Data Collector Control Utilities 1. START (START^PMFCOL) 2. STATUS (STATUS^PMFCOL) 3. STOP (STOP^PMFCOL) Select Option > 3. STOP Stop collector process on which nodes MTWAIN,OZONE Collection process on node MTWAIN set to HALT Collection process on node OZONE set to HALT 6-28 Optimizing DSM Using the Data Collection Utilities (^PMFDAT) You use the Data Collection Utilities (^PMFDAT) to manage the database of collections created over time. The Data Collection Utilities allow you to: o List completed collections o List scheduled collections o Purge the collection database The following example shows how to select the Data Collection Utilities. Performance Monitoring Utilities 1. COLLECTOR CONTROL UTILITIES (^PMFCOL) 2. DATA COLLECTION UTILITIES (^PMFDAT) 3. REPORTING UTILITIES (^PMFREP) Select Option > 2 Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > Canceling In-Progress Data Collections (CANCEL^PMFDAT) You use the Cancel In-Progress Collections Utility (CANCEL^PMFDAT) to cancel data collections currently in progress on one or more nodes. The following example shows how to cancel data collections on one specified node: Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > 1. CANCEL IN-PROGRESS COLLECTIONS Optimizing DSM 6-29 Cancel in-progress collections on which nodes ZEUS Collection process on node ZEUS state set to CANCEL. Listing Completed Collections (LIST^PMFDAT) You use the List Completed Collections Utility (LIST^PMFDAT) to list completed collections. You can list all completed collections or all collections completed before a specific date. The following example shows how to list all completed collections: Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > 2. LIST COMPLETED COLLECTIONS List all collections to date [Y or N] PMF Data Collection Sessions Recorded as of 22-AUG-1997 10:39:09 AM # Collection Time Duration Collecting Nodes - --------------- -------- ---------------- 1. 22-APR-1997 10:39:09 AM 5 2. 22-APR-1996 10:46:09 AM 5 3. 22-APR-1997 10:52:28 AM 5 4. 22-APR-1997 10:59:28 AM 5 If the report does not show a node name associated with the collection, the node is the current node. Listing Scheduled Collections (QUEUED^PMFDAT) You use the List Scheduled Collections Utility (QUEUED^PMFDAT) to list all collections scheduled on one or more nodes of a VMScluster. The following example shows how to use List Scheduled Collections: 6-30 Optimizing DSM Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > 3. LIST SCHEDULED COLLECTIONS Queued Data Collection Sessions Node Date Time Session Duration ---- ---- ---- ------- -------- MTWAIN 22-SEP-1997 10:39:09 AM 1 5 OZONE 22-SEP-1997 10:39:09 AM 1 5 ZEUS 22-SEP-1997 10:39:09 AM 1 5 Purging Completed Collections (PURGE^PMFDAT) You use the Purge Completed Collections Utility (PURGE^PMFDAT) to purge all completed collections or all collections made before a specified date. If you specify "selected," the utility displays the current date. You can either purge all completed collections made before that date or enter another (past) date. If you enter another date, the utility purges all completed collections made before the date you specify. The following example shows how to purge all collections made before a specified date: Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > 4. PURGE COMPLETED COLLECTIONS Purge ALL or SELECTED data collections [A or S] > S Purge collections created before <22-OCT-1997> Y Purge all collections recorded before 22-Oct-1997 Are you sure [Y or N] ? > Y Optimizing DSM 6-31 Collections and reports are maintained separately. If you purge a collection, you still have any reports you generated from those collections. However, if you print any reports based on purged collection, the report lists only asterisks (*) for that collection in the table of included collections. See the section "Creating Reports (PMFGEN)" for more information. Purging Scheduled Collections (DQUEUE^PMFDAT) You use the Purge Scheduled Collections Utility (DQUEUE^PMFDAT) to purge all scheduled collections. The following example shows how to purge all scheduled collections. Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > 5. PURGE SCHEDULED COLLECTIONS Queued Data Collection Sessions Node Date Time Session Duration ---- ---- ---- ------- -------- MTWAIN 22-SEP-1997 10:39:09 AM 1 5 22-SEP-1997 10:44:09 AN 2 5 OZONE 22-SEP-1997 10:39:09 AM 1 5 22-SEP-1997 10:44:09 AN 2 5 ZEUS 22-SEP-1997 10:39:09 AM 1 5 22-SEP-1997 10:44:09 AN 2 5 Purge all scheduled collections - are you sure [Y or N] ? > Y Scheduled collections purged 6-32 Optimizing DSM Scheduling a New Collection (^PMFMON) You use the Schedule a New Collection Utility (^PMFMON) to schedule collections on one or more nodes of a VMScluster. You can choose to schedule multiple collections separated by equal intervals between collections. This allows you to schedule a series of short collections over a period of time. In this way, you can collect sequences of collections you can use to investigate your system's performance at various times of day. The following example schedules 5 collections on two nodes of a VMScluster. Each collection will last 10 minutes and be separated by a 30 minute delay: Performance Data Collection Utilities 1. CANCEL IN-PROGRESS COLLECTIONS (CANCEL^PMFDAT) 2. LIST COMPLETED COLLECTIONS (LIST^PMFDAT) 3. LIST SCHEDULED COLLECTIONS (QUEUED^PMFDAT) 4. PURGE COMPLETED COLLECTIONS (PURGE^PMFDAT) 5. PURGE SCHEDULED COLLECTIONS (DQUEUE^PMFDAT) 6. SCHEDULE A NEW COLLECTION (^PMFMON) Select Option > 6 Schedule System Performance Monitoring Enter duration of one monitor session (minutes) <1> 10 Enter the number of monitor sessions in this collection <1> 5 Enter the time delay between monitor sessions (minutes) <1> 30 Enter the start time of 1st session (DD-MMM-YYYY HH:MM:SS) <11-APR-1997 16:31:01> 11-APR-1997 16:31:01 16:31:02 Collection start time: 11-APR-1997 4:31:01 PM Session duration: 10 minutes Number of Sessions: 5 Delay Between Sessions: 30 minutes Monitored nodes: MTWAIN,ZEUS Proceed [Y OR N] ? > Y Optimizing DSM 6-33 Using the Reporting Utilities (^PMFREP) You use the Reporting Utilities (^PMFREP) to generate reports from specified data collections. After you have generated a report, the report stays on file so that you can keep it for later reference. You also use the REPORTING Utilities to list, print, or delete these previously-generated reports. The following example shows how to choose the Reporting Utilities: Performance Monitoring Utilities 1. COLLECTOR CONTROL UTILITIES (^PMFCOL) 2. DATA COLLECTION UTILITIES (^PMFDAT) 3. REPORTING UTILITIES (^PMFREP) Select Option > 3 Performance Data Reporting Utilities 1. CREATE (^PMFGEN) 2. DELETE (DELETE^PMFREP) 3. LIST (LIST^PMFREP) 4. PRINT (PRINT^PMFREP) Select Option > Creating Reports (PMFGEN) After you have collected data, you use the Create Utility (^PMFGEN) to select one or more sessions to incorporate into a report. The following example shows how to use Create: Performance Data Reporting Utilities 1. CREATE (^PMFGEN) 2. DELETE (DELETE^PMFREP) 3. LIST (LIST^PMFREP) 4. PRINT (PRINT^PMFREP) Select Option > 1 Select from data collections made since <3-APR-1997> PMF Data Collection Sessions Recorded as of 3-APR-1997 7:49:30 PM (* = incomplete or in-progress sessions) 6-34 Optimizing DSM # Collection Time Duration Collecting Nodes 1. 3-APR-1997 7:49:30 PM 10 BAC BAL BAQ BAR 2. 3-APR-1997 8:49:30 PM 10 BAC BAL BAQ BAR Enter the desired session number(s) > 1,2 PMF Data Collections Selected Session Node Start Time Completion Time 1 BAC 3-APR-1997 7:49:47 PM 3-APR-1997 8:00:29 PM BAL 3-APR-1997 7:49:47 PM 3-APR-1997 8:00:32 PM BAQ 3-APR-1997 7:49:47 PM 3-APR-1997 8:00:35 PM BAR 3-APR-1997 7:49:45 PM 3-APR-1997 8:00:17 PM 2 BAC 3-APR-1997 8:49:47 PM 3-APR-1997 9:00:29 PM BAL 3-APR-1997 8:49:47 PM 3-APR-1997 9:00:32 PM BAQ 3-APR-1997 8:49:47 PM 3-APR-1997 9:00:35 PM BAR 3-APR-1997 8:49:45 PM 3-APR-1997 9:00:17 PM Enter description field for report headings: . . . . Remember that reports generated by ^PMF have only configuration data that was gathered at the start of a collection. Therefore, if a volume set was mounted during the collection period, that set does not appear in the "Mounted Volume Set Information" summary. The "Volume Set Operations Summary" will list data for the maximum possible number (8) of volume sets. However, the report does include all data about accesses to the new volume set that were made during the collection period. Optimizing DSM 6-35 Deleting Reports (DELETE^PMFREP) The Delete Utility (DELETE^PMFREP) allows you to delete all or selected reports. The following example shows how to delete selected reports: Performance Data Reporting Utilities 1. CREATE (^PMFGEN) 2. DELETE (DELETE^PMFREP) 3. LIST (LIST^PMFREP) 4. PRINT (PRINT^PMFREP) Select Option > 2. DELETE Delete All or Selected reports [A or S] > S 4,5 Selected reports: #4 Summary of collection sessions 1 started on 23-OCT-1997 11:02:16 AM Generated on: 22_APR-1997 12:05:00 AM #5 Summary of collection sessions 2 started on 23-OCT-1997 11:12:16 AM Generated on: 22_APR-1997 12:15:00 AM Delete selected reports - are you sure [Y or N] ? > Y Listing Reports (LIST^PMFREP) The List Utility (PRINT^PMFREP) allows you to list all reports. The listing includes the name and date of each report. It also includes a list of the collections included. The following example shows how to use List: Performance Data Reporting Utilities 1. CREATE (^PMFGEN) 2. DELETE (DELETE^PMFREP) 3. LIST (LIST^PMFREP) 4. PRINT (PRINT^PMFREP) Select Option > 3. LIST Reports generated as of 23-OCT-1997 Summary or Full listing [S or F] > S #5 Summary of collection sessions 2 started on 23-OCT-1997 11:12:16 AM Generated on: 23-OCT-1997 12:15:00 AM 6-36 Optimizing DSM Session Node Start Time Completion Time ------- ---- ---------- --------------- 2 MTWAIN 22-OCT-1997 11:34:06 AM 22-OCT-1997 11:39:09 AM OZONE 22-OCT-1997 11:34:05 AM 22-OCT-1997 11:39:06 AM ZEUS 22-OCT-1997 11:34:06 AM 22-OCT-1997 11:39:07 AM Printing Reports (PRINT^PFMREP) The Print Utility (PRINT^PMFREP) allows you to send a generated report to your terminal screen, a printer, or a file. You can produce any of the following: o A summary report o A full report o A full report with global and routine summaries See the section "PMF Reports" for more information about these report types. The following example shows how to use PRINT^PFMREP: Performance Data Reporting Utilities 1. CREATE (^PMFGEN) 2. DELETE (DELETE^PMFREP) 3. LIST (LIST^PMFREP) 4. PRINT (PRINT^PMFREP) Select Option > 4. PRINT Summary or Full listing [S or F] F Reports generated as of 24-FEB-1997 #1 Summary of collection sessions 1 started on 15-FEB-1997 8:57:35 PM Generated on: 15-FEB-1997 9:08:16 PM Session Node Start Time Completion Time 1 VAXDSM 15-FEB-1997 8:57:44 PM 15-FEB-1997 9:07:48 PM Enter report number to print > 1 Report selected is: "Summary of collection sessions 1 started on 15-FEB-1997 8:57:35 PM" Session Node Start Time Completion Time Optimizing DSM 6-37 1 VAXDSM 15-FEB-1997 8:57:44 PM 15-FEB-1997 9:07:48 PM Output Device ? > 0 Summary or Full Report [S or F] ? ? Enter S to produce a SUMMARY report. SUMMARY reports include primary statistics collected for all globals and volume sets. In a VMScluster environment, node specific information is not included. Enter F to produce a FULL report. FULL reports include all statistics collected for all nodes. When you select a full report, you are permitted to report on only global and routines which represent a significant percentage of the system activity. Summary or Full Report [S or F] ? F Include a Summary or Full global data report [S or F] ? > F Enter the percentage of global and routine access to cover <95> ? Enter 100 to report on all globals and routines accessed during the collection period. If you enter a smaller value, the report will be limited to only those globals and routines that represent that percentage of the total routine or global access during the collection period. Enter the percentage of global and routine access to cover <95> PMF Reports The following sections discuss PMF report by: o Report Types o Data Categories PMF Report Types You can use PMF to produce three types of reports: o Summary reports o Full reports o Full reports with global summaries 6-38 Optimizing DSM Summary Reports Summary reports present summarized global data for a cluster and its volume sets. The summary report includes only summarized global references by access, set, and kill operations performed on the system globals. It does not present data about the individual globals themselves. The report does not include information broken out by node. All tables and histograms in a summary report consolidate data for the cluster. Full Reports The tables and histograms on a full report are the same as on a summary report. However, the tables and histograms break down the data not only for the cluster as a whole, but also for each node in the cluster. The full report also presents data on each of the most used globals. You can specify what percentage of the most used globals you want to include in the report. The Report Utility asks the question: Enter the percentage of global and routine access to cover <95>) If you accept the default, you receive a report on 95% of the most used globals. That means that if you have 100 globals on your DSM cluster, you the full global report covers 95 of the most accessed globals. If you enter another number, you receive a report that covers a percentage of global accesses represented by that number. For example, suppose you entered 40: for example: Enter the percentage of global and routine access to cover <95> 40 The report only includes those routines and globals that represent 40 percent of global access during the collection period. Optimizing DSM 6-39 Full Reports with Global Summaries A full report with global summary also represents all data collected on all nodes specified in the original collection. Like the full report, the full report with global summary breaks down data both by cluster and by individual node. However, the full report with global summary presents only summary data on the most used globals. As with full reports, you can specify what percentage of the most used globals you want to include in the summary global report. Data Categories All report types contain the same data categories. Each category is either a histogram or, in some cases, a table of data. In summary reports, the data is broken out only for the configuration. In full reports (of both kinds) the data is broken out for the configuration and for individual nodes. The following sections discuss each data category in detail. The sections note where there are presentation or formatting differences on the various types of report. Configuration Information The report includes configuration information in the header. Figure 6-1 shows the header. As Figure 6-1 shows, the configuration information includes: o The name of the OpenVMS node o The name of the DSM environment o The name of the configuration o The CPU type o The number of cache buffers o Whether non-paged memory is present o The version of DSM running o Whether DDP is running 6-40 Optimizing DSM Mounted Volume Set Information The mounted volume set information section gives general information about each mounted volume set. Figure 6-2 shows a sample of volume set information for one mounted volume set: As Figure 6-2 shows, the mounted volume set information includes information whether: o The volume set is cluster mounted o The volume set is mastered o The volume set is read only o The volume set is a TPU volume set o After-image journaling is enabled o Before-image journaling is enabled For each volume in the volume set, the mounted volume set information includes: o The number of maps o The device and file specification of the volume o The device and file specification of the BIJ file Cluster-Wide Statistics Summary The cluster-wide statistics summary presents statistics for the cluster in histogram format. The categories are classes of events for the cluster. The data represents averages of events per second. Optimizing DSM 6-41 Figure Figure 6-3 shows the cluster-wide statistics summary on a summary report. 6-42 Optimizing DSM Figure 6-4 shows a section of a sample cluster-wide statistics summary from a full report. This report is broken out by node. Despite the differences in format, the events described in this histogram are the same for both summary and full reports. The events described in this histogram are as follows: o Physical reads The number of times real physical disk reads performed to read a database block into DSM global buffer cache. o Logical reads The number of times database blocks required for global access. o Physical writes The number of DSM blocks written to disk by the WRITE Demon. o Logical writes The number of times DSM processes modified disk blocks and marked the disk blocks as needing writing. o Search last tries The number of times that DSM processes attempted to resolve a global reference by checking the last DSM block that they referenced. o Search last successes The number of times that DSM processes actually resolved a global reference by checking only the last DSM block that they referenced. o Local buffer tries The number of times that DSM process attempted to resolve a local reference by checking the local symbol table. o Local buffer successes The number of times that DSM processes actually resolved a local reference by checking the local symbol table. Optimizing DSM 6-43 o Local buffer invalidates The number of times that DSM processes invalidated a local reference by checking the local symbol table. o Global accesses The total number of global GET, SET, KILL, $DATA, and $NEXT operations performed by the DSM global system. o Global gets The total number of global variable reads done. For example: S SCRATCH=^S(4) o Global $DATAs The total number of global variable $DATA operations done. For example: S SCRATCH=$D(^S(4)) o Global $NEXTs The total number of global variable $NEXT operations done. For example: S A=$N(^X(-1)) S A=$O(^X("")) o Global sets The total number of global variable SET operations done. For example: S ^X(4)="PATIENT" o Global kills The total number of global variable KILL operations done. For example: K ^X(4) o Global allocates The number of nodes added to a DSM global structure. o Global deallocates The number of nodes removed from a DSM global structure. o Global seizes 6-44 Optimizing DSM The number of times that a volume set was exclusively owned by a DSM process while it performed a multiple- block update to the DSM database (either a block split or merge operation). o Global seize waits The number of times that DSM processes had to gain exclusive access to a volume set because other processes were already accessing it concurrently. o Global access waits The number of times DSM processes had to wait to access a volume set because another process had it seized (exclusively owned). o Directory searches The number of times that DSM processes searched the global directory of a volume set to satisfy a global reference. o Global synch waits The number of times DSM processes had to wait for exclusive access to a data structure other than the DSM global buffers. o Global list waits The number of times that DSM processes had to wait before searching for a DSM database block in cache. o Global buffer waits The number of times that DSM processes had to wait for exclusive access to a cache DSM database block. o Global write waits The number of times that DSM processes had to wait to read a new block into cache because cache was full of unwritten, modified blocks. Optimizing DSM 6-45 Cluster-Wide Derivative Ratios Derivative ratios show the effectiveness of the optimiza- tion algorithms of both the disk cache and the global database handler. These ratios are derived from the database event count statistics. Figure 6-5 shows an example of the cluster-wide derivative ratios page from a summary report: The following describes the derivation ratio statistics: o Actual block reads for each block read request - shows the effectiveness of the disk cache in minimizing disk reads. o Block requests for each global reference - shows the effectiveness of the global database handler. In general, global and routine references require more than one block request to get the data. The global database handler uses optimization algorithms to minimize the number of these block requests. When successive references (within a job) are to the same global, the second and following references can require fewer block requests. If global references within a job are grouped by global name, the ratio declines to approach the value of 1. o Block Write Requests for each SET/KILL command - must be at least 1. This ratio can be expected to increase as the rate of growth of the database increases. When a global block overflows, a split occurs, causing at least four block writes to the following: - Two resulting blocks - Ancestor pointer block - Map block o Actual blocks written for each block write request - shows the effectiveness of the disk cache and the Write Demon in minimizing disk writing. 6-46 Optimizing DSM Cluster-Wide Volume Set Statistics Summary The PMF reports also present histograms that show cluster- wide statistics for each volume set. Figure 6-6 shows an example of a cluster-wide statistics summary for a volume set. This example is from a summary report. The cluster-wide volume set statistics summary is similar to the cluster-wide statistics summary. However, the cluster-wide volume set statistics summary adds categories, including: 1. Write acc enqueues 2. Write acc converts 3. Deadlock aborts 4. Total new enqueues 5. Journal logical writes Other Summary Histograms A report also includes the following histograms. On a summary report, the data is rolled up for the entire cluster. On a full report (or full report with global summary), the data is rolled up for the entire cluster and also presented by node. These include: o Cluster-wide volume set operations summary for each volume set These histograms map the number of logical and physical reads and logical writes for the volume set. Figure 6-7 shows a sample from a full report: o Cluster-wide global accesses This histogram maps the number of global accesses each second for each global covered by the report. o Cluster-wide routine loads summary This histogram measures the routine loads for each global covered by the report o Cluster-wide routine map accesses This histogram measures the number of routine map accesses for each global covered by the report. o Cluster-wide routine commands executed summary Optimizing DSM 6-47 This histogram measures the number of routine commands executed for each global covered by the report. Figure 6-8 shows a sample from a full report: o Cluster-wide routine CPU seconds summary This histogram measures the CPU seconds routines took to run. o Cluster-wide system response time statistics These histograms measure: - Prompt-to-prompt command execution time in seconds for varying simultaneous command loads. - Prompt-to-prompt global reference completion time for varying simultaneous global reference loads. Figure 6-9 shows a sample global reference completion time histogram from a full report: o DDP activity for each volume set PMF does not provide this data as a histogram. Instead, it provides the data in report form. This report includes DDP activity on a node-by-node basis. The activity is formatted as a chart. Figure 6-10 shows a DDP activity table from a summary report: Optimizing DSM Based on PMF Statistics An advantage of ^PMF is that it gathers statistics while an application is running in a normal day-to-day environment, rather than in a test situation. You can use the statistics to accurately gauge where bottlenecks or performance problems are occurring. When a system reaches a saturation point, the first question you normally ask is whether the system is disk- bound or CPU-bound. You can determine the answer by: o Examining ^PMF reports o Using the OpenVMS Monitor Utility 6-48 Optimizing DSM If the system is CPU-bound, you can optimize DSM coding to improve performance. You can also refer to the PMF statistics to see which routines are consuming the most CPU time. You can then determine where your effort would produce the best results. If this is still insufficient, you may want to consider upgrading to a faster CPU. If the system is disk-bound, you can use these statistics to show: o How often each global is being referenced o How the references are split between reading and writing o Which routines, when mapped, could best minimize disk references Optimizing DSM 6-49 7 ________________________________________________________________ DSM System Utilities This chapter describes the DSM System Utilities that are useful to DSM managers and operators. Overview of DSM Utilities The DSM utilities are a collection of routines provided with your DSM system that perform tasks and provide needed information. The utilities fall into two categories: o Library Utilities o System Utilities Library Utilities In general, Library Utilities serve the needs of application programmers. There are two sets of Library Utilities: o CLI (command-line interpreter) Library Utilities you can use directly on OpenVMS VAX or OpenVMS Alpha o Graphic Library Utilities you can use on a Windows- based Caché client to manipulate routines and globals on a DSM server. The DSM for OpenVMS Programmer's Guide describes the CLI Library Utilities and the Graphic Library Utilities. System Utilities System Utilities, described in this chapter and elsewhere in this manual, are accessible only to users who enter the DSM command with the /MANAGER command line qualifier, or who log in to the MGR UCI. These utilities reside in the RMS routine directory, SYS$LIBRARY:MANAGER.DSM, when volume sets are not mounted. Otherwise, these utilities reside in the MGR UCI of the first mounted volume set. DSM System Utilities 7-1 Utility Access DSM provides access to all System and CLI Library Utilities through a menu. The menu displays options on your terminal, and you select the option you need for a particular task. The utilities also provide online help. If you are unsure of the appropriate response to a prompt, type a question mark (?) for help. DSM responds by listing your options or by asking you to identify the option about which you need further information. The ^%HELP Utility provides online information about all DSM commands, variables, and functions. You can run ^%HELP with the DO command or by typing a question mark (?) after the DSM prompt (>). Utility Conventions All utilities use the following conventions, unless the utility description specifies an exception: o To get information about a utility or utility prompt, type a question mark (?). In response, the system displays help text. o Each menu displays a list of numbers followed by options. Options can point to lower level menus or to actual utilities. To select an option, enter either its number or its name (enough characters to distinguish it from other names). The menu also displays the utility routine name in parentheses. o The correct way to exit a menu is to press Return, or to type a circumflex (^) and press Return after a prompt. To exit any utility, use the same procedure. If the utility interprets a Return as a default value, use the circumflex to back up or exit. o After a utility begins execution, do not stop the utility before execution is complete. You run the risk of leaving files open, leaving a VIEW buffer allocated, or leaving variables undefined. Let the utility run to completion, then rerun it correctly. 7-2 DSM System Utilities o When a utility requests an input or output file, it accepts any valid device specification. You can refer to your own terminal as 0, but you must specify all other devices by device name or logical name . If your OpenVMS installation spools the line printer, you can specify LP in the device field of the output file specification. When you include the line printer name in the file specification (for example, LPA0:EXAMPLE.DAT), the file name appears on the header page of your output. o For some utilities, such as those that manipulate routines or globals, you may want to specify more than one name in response to a utility prompt. You can use the asterisk (*) as a wildcard character. The asterisk by itself indicates ALL. When the asterisk is the last character in an alphanumeric string, the utility interprets that string as meaning all names with that string as their root. For example, to specify ALP, ALPHA, and ALP123, type ALP*. You can also do the following: - Type ^D in response to a prompt requesting a routine or global name. This response displays the contents of your global or routine directory (to help you make your selection). - Type ^L to produce a list of the routines or globals you have already selected. - Enter a range of names, for example, A-FZZZ. - To exclude a single name or a range of names from an operation, use a minus sign before the routine names, for example, -A* and -B-CZZ. Note the use of the wildcard. o DSM always returns numbers in a decimal format. You can, however, convert numbers to other bases using the numerical conversion Library Utilities described in the DSM for OpenVMS Programmer's Guide. DSM System Utilities 7-3 Running the DSM System Utilities You can access the DSM utilities in the following ways: o Enter the following to display a menu of the System Utilities: >D ^SYS The utility displays the following menu: System Utilities 1. CONFIGURATION MANAGEMENT (^CONMAN) 2. DATABASE SET MANAGEMENT (^DBSMAN) 3. DISTRIBUTED DATA PROCESSING (^DDP) 4. MAPPED ROUTINES (^RMAP) 5. OPTION FILE MANAGEMENT (^OPTMAN) 6. PERFORMANCE UTILITIES 7. SYSTEM MANAGEMENT (^SYSMAN) 8. TRANSLATION TABLE MANAGEMENT Select Option > o Enter the routine name of the DSM utility directly in programmer mode: >D ^CONMAN o Run DSM in application mode using the routine name of the utility as the DSM command parameter: $ DSM/MANAGER ^CONMAN Configuration Management Utilities (^CONMAN) Use the ^CONMAN Utilities to create and manage config- urations. You can access the following Configuration Management Utilities from the ^CONMAN Utility menu. __________________________________________________________ Utility_______________Routine_Name________________________ Copy Configuration COPY^CONFIG Build/Create ^CONFIG Configurations Delete Configuration DELETE^CONFIG Display Configuration DISPLAY^CONFIG 7-4 DSM System Utilities __________________________________________________________ Utility_______________Routine_Name________________________ Modify Existing MODIFY^CONFIG Configuration ____________________________________ Utility____________Routine_Name_____ $H Offsets ^CONHR After-Image ^CONAIJ Journaling Command Line ^CONCLQ Qualifiers Database Set ^CONDBS DDP Options ^CONDDP Default ^CONDEF Configuration Global Characterist^CONGLO Global Translation START^CONTR Mapped Routine ^CONMAP Sets Mountable MOUNT^CONDBS Database Sets System Options ^CONOPT Transaction ^CONTP Processing Volume_Set_Alias___^CONVA___________ __________________________________________________________ For information about the ^CONFIG Utility, see Chapter 2 in this manual. The following sections describe the other ^CONMAN Utilities. Deleting Configurations (DELETE^CONFIG) The DELETE^CONFIG Utility lets you delete an existing configuration. Enter the following to run the utility: >D DELETE^CONFIG WARNING *** This operation DELETES an entire configuration Enter the configuration identifier > MAIN Are you sure you want to delete the MAIN configuration [Y OR N] ? Y Deleting the MAIN configuration... done. DSM System Utilities 7-5 Displaying Configurations (DISPLAY^CONFIG) The following example describes the DISPLAY^CONFIG Utility. It displays information about the configuration that you defined to completion with the ^CONFIG Utility. For example, enter the following to display the PAYROLL configuration: >D DISPLAY^CONFIG Note that the utility asks if you want to display the translation tables for the selected configuration. The utility displays the following: *** CONFIGURATION DISPLAY Enter the configuration identifier Display all the translation tables [Y OR N] ? N Output Device ? <0> *** CONFIGURATION PAYROLL *** System options : -------------- Configuration access control enabled Y Number of disk buffers 1200 Memory for disk buffers Paged Maximum number of users 128 Support RTHIST performance histogram NO $H day offset in days 1 $H time offset in seconds 3600 Database sets: ------------ Database set #1 = EMPLOYEE OpenVMS database set Read/Write Not Cluster-Mounted EMP DISK$DATA:[DSM$DSMMGR.DATABASE]EMPVOL1.GLS No Before-Image Journaling No After-Image Journaling Send console message when database set is 90% full Configuration PAYROLL is the database set master for the following database sets: EMPLOYEE 7-6 DSM System Utilities DDP parameters: DDP not included -------------- Default global characteristics : ------------------------------ 8 Bit Subscripts Yes Journaling No Collating sequence Numeric Access privileges for non-% globals : System: RWP World: NONE Group: NONE UCI: RWP Access privileges for % globals : System: RWP World: R Group: R UCI: RWP DCP Parameters ------------- Network Type UDP Local UDP port number 7500 Default UIC for global protection None UIC protection for individual UIC,VOLs: LIB,AA = 1,4 AAA,RDA = 0,0 MGR,RDA = 0,0 Mapped routine sets to install: mapped routines not included ------------------------------ DSM default command line qualifiers: none defined TP options: TP not included ---------- After-Image Journaling: not enabled ---------------------- Copying Configurations (COPY^CONFIG) The COPY^CONFIG Utility allows you to copy all of the configuration information for an existing configuration to create another configuration definition. Enter the following to run COPY^CONFIG: >D COPY^CONFIG This operation creates a new configuration by copying the contents of an already existing configuration. Name of configuration to copy: Enter the configuration identifier > PAYROLL DSM System Utilities 7-7 Name of configuration to create: Enter the configuration identifier > BENEFITS Are you sure you want to copy configuration PAYROLL to BENEFITS [Y OR N] ? Y Copying configuration PAYROLL to a new configuration BENEFITS... Copy complete ________________________Note ________________________ DDP node names must be unique network-wide. You may need to change the DDP node and/or device name of this newly created configuration. _____________________________________________________ This utility is useful for creating configurations for nodes in a VMScluster environment. You can make copies of an existing configuration, then use the MODIFY^CONFIG Utility to make partial changes. Modifying Configurations (MODIFY^CONFIG) The MODIFY^CONFIG Utility allows you to modify parts of an existing configuration without having to run the entire ^CONFIG Utility. ________________________Note ________________________ Do not use MODIFY^CONFIG to modify a database set while that database set is still mounted. The result of such an action is upredictable and may lead to system hangs or access violations. _____________________________________________________ Enter the following to run MODIFY^CONFIG: >D MODIFY^CONFIG Modify Configuration Utilities 7-8 DSM System Utilities 1. $H OFFSETS (^CONHR) 2. AFTER-IMAGE JOURNALING (^CONAIJ) 3. COMMAND LINE QUALIFIERS (^CONCLQ) 4. DATABASE SET (^CONDBS) 5. DCP OPTIONS (^CONDCP) 6. DDP OPTIONS (^CONDDP) 7. DEFAULT CONFIGURATION (^CONDEF) 8. GLOBAL CHARACTERISTICS (^CONGLO) 9. GLOBAL TRANSLATION (^CONTR) 10. MAPPED ROUTINE SETS (^CONMAP) 11. MOUNTABLE DATABASE SETS (MOUNT^CONDBS) 12. SYSTEM OPTIONS (^CONOPT) 13. TRANSACTION PROCESSING (^CONTP) 14. VOLUME SET ALIAS (^CONVA) Select Option > Each option allows you to modify existing information. For example, if you select the ^CONDDP Utility, the DDP questions from ^CONFIG are displayed. Database Set Management Utilities (^DBSMAN) Use the ^DBSMAN Utilities for After-Image Journaling, Before-Image Journaling, and database and volume set management. You can access the following utilities from the ^DBSMAN Utility menu. __________________________________________________________ Utility_______________Routine_Name________________________ After-Image ^JOURNAL Journaling Before-Image Journaling Database Set Utilities Volume_Set_Utilities__^VOLUTL_____________________________ The following sections describe these utilities. DSM System Utilities 7-9 After-Image Journaling Utilities (^JOURNAL) The ^JOURNAL Utilities control the use of the After- Image Journaling process. To use the options on the ^JOURNAL menu, you must have the same UIC as the DSM Journal Process. You can access the following After-Image Journaling Utilities from the ^JOURNAL Utility menu. __________________________________________________________ Utility_______Routine_Name________________________________ Dejournal ^DEJRNL ____________________________________________ Utility_________________Routine_Name________ Dejournal from a DSM- DSM11^DEJRNL 11 Tape Dejournal from Journal LOG^DEJRNL Log Dejournal Selected FILE^DEJRNL Files_______________________________________ Files ____________________________________________ Utility_________________Routine_Name________ Add Journal File Name ADDFIL^JRNL Close Current Journal CLOSEFI^JRNL File Create New Log File NEWLOG^JRNL Display Journal File LABEL^JRNL Label Display Journal File DISPLAY^JRNL Names Initialize Journal ^JRNINIT File Open Current Journal OPENFIL^JRNL File________________________________________ Globals SETJRN^%GLOMAN List Journal ^JRNLIS 7-10 DSM System Utilities __________________________________________________________ Utility_______Routine_Name________________________________ Operator ____________________________________________ Utility_______________Routine_Name__________ Disable Journaling PAUSE^JRNL Disable Transactions TPOFF^JRNL Enable Journaling RESUME^JRNL Enable Transactions TPON^JRNL Journal_Status________STATUS^JRNL___________ __________________________________________________________ The DMS for OpenVMS Database Operations Guide describes the After-Image Journaling Utilities in detail. Before-Image Journaling Utilities Use the Before-Image Journaling Utilities to create a before-image journal (BIJ) file, examine the contents of the file, and apply the file to repair a corrupted database. You can access the following Before-Image Journaling Utilities from the ^DBSMAN Utility menu. __________________________________________________________ Utility__________Routine_Name_____________________________ Create ^BIJINIT Examine ^BIJEXAM Force ^BIJFORC _________________________________________ Utility_____________Routine_Name_________ Perform Before- NOAIJ^BIJFORC Image Recovery Only Perform No NOBIJ^BIJFORC Recovery_________________________________ __________________________________________________________ The DSM for OpenVMS Database Operations Guide describes the Before-Image Journaling Utilities in detail. DSM System Utilities 7-11 Database Set Utilities Use the Database Set Utilities to manage database sets. You can access the following utilities from the ^DBSMAN Utility menu. __________________________________________________________ Utility_______________Routine_Name________________________ Create/Modify MODIFY^CONDBS Database Set Delete Database Set DELETE^CONDBS Display_Database_Set__DISPLAY^CONDBS______________________ The DSM for OpenVMS Database Operations Guide describes the Database Set Utilities in detail. Volume Set Utilities (^VOLUTL) Use the ^VOLUTL Utilities to manage DSM volume sets and the UCIs and globals associated with them. The ^VOLUTL Utilities also provide backup and restore utilities and database integrity utilities. You can access the following utilities from the ^VOLUTL Utility menu. __________________________________________________________ Utility_______________Routine_Name________________________ Backup ^BACKUP ____________________________________ Utility_________Routine_Name________ Backup BCKUP^BACKUP Restore REST^BACKUP Update__________REV^BACKUP__________ Database Repair ____________________________________ Utility_________Routine_Name________ Block Dump ^BLDMP Fast IC ^FASTIC Fix ^FIX Integrity ^IC Checker_____________________________ Disk Block Tally ^DBT 7-12 DSM System Utilities __________________________________________________________ Utility_______________Routine_Name________________________ Global Management ^%GLOMAN Show Mounted Volume ^%VOLTAB Sets UCI Management ^UCIMAN ____________________________________ Utility_________Routine_Name________ Add UCI ^UCIADD Change UCI LIB^UCIEDIT Library Edit UCI Name ^UCIEDIT Show UCIs SHOW^UCIADD UCI_Growth______^UCIGAM_____________ Volume Management ^VOLMAN ____________________________________ Utility_________Routine_Name________ Add ADD^VOLMAN Create CREATE^VOLMAN Extend EXTEND^VOLMAN Maximum MAXGLO^VOLMAN2 Globals String_Length___EXPSTR^VOLMAN2______ Volume_Set_Access_____^VOLINH_____________________________ For information about ^BACKUP, the Database Repair Utilities, and the global management and volume set management utilities, see the DSM for OpenVMS Database Operations Guide. The following section describes the ^DBT Utility. Disk Block Tally (^DBT) The ^DBT Utility reports on the allocation of blocks within a volume set. You have the option to run a fast tally or a slow tally. The fast tally gives you a summary of the map number, the number of blocks available, and how the blocks are being used. The slow tally gives you a more detailed report. DSM System Utilities 7-13 You can use the ^DBT Utility to monitor the number of blocks that are available on a volume set. If a volume set is running out of space, you can allocate more space by either adding a volume to the volume set (ADD^VOLMAN) or extending the last volume of the volume set (EXTEND^VOLMAN). Distributed Data Processing Utilities (^DDP) Use the ^DDP Utilities to obtain information about DDP servers and to shut down a server. The ^DDP Utilities include options for controlling DDP operations and displaying information about DDP. You can access the following utilities from the ^DDP Utility menu. __________________________________________________________ Utility_________Routine_Name______________________________ Circuit ^DDPCIR Management __________________________________________ Utility____________Routine_Name___________ Circuit Status STA^DDPCIR Disable Circuit DISAB^DDPCIR Enable Circuit ENAB^DDPCIR Reset Circuit RESET^DDPCIR Counters Show Circuit COUNT^DDPCIR Counters__________________________________ Configure DDP ^CONDDP Control ^DDPUTL Utility Link Status ^DDPLNK Request ^DDPREQ Control __________________________________________ Utility____________Routine_Name___________ Disable DISABLE^DDPREQ Enable ENABLE^DDPREQ Status_____________STATUS^DDPREQ__________ 7-14 DSM System Utilities __________________________________________________________ Utility_________Routine_Name______________________________ Security ^DDPSEC __________________________________________ Utility____________Routine_Name___________ Add Node Password ADD^DDPSEC Delete Node DELETE^DDPSEC Password List Database LIST^DDPSEC Entries Modify Node MODIFY^DDPSEC Password__________________________________ Shutdown DDP STOP^DDPLNK Startup DDP START^DDPLNK Startup Links LINK^DDPLNK Statistics ^DDPSTA __________________________________________ Utility____________Routine_Name___________ Monitor MONITOR^DDPSTA Record RECORD^DDPSTA Replay_____________REPLAY^DDPSTA__________ __________________________________________________________ For information about the DDP Utilities, see the DSM for OpenVMS Database Operations Guide. Mapped Routine Utilities (^RMAP) Use the ^RMAP Utilities to map routines into virtual memory sections to improve system performance. You can access the following utilities from the ^RMAP Utility menu. __________________________________________________________ Utility_______________Routine_Name________________________ Build ^RMBLD Contents ^RMSHO Delete ^RMDEL Directory MAP^%RD Disable Routine ^RMDIS Install ^RMINS DSM System Utilities 7-15 __________________________________________________________ Utility_______________Routine_Name________________________ Show_Installed________MAPSET^RMSHO________________________ For information about mapped routines, see Chapter 2 and Chapter 6. Option File Management Utilities (^OPTMAN) Use the ^OPTMAN Utility to create a configuration definition file and apply that file to ^CONFIG. You can access the following utilities from the ^OPTMAN Utility menu. __________________________________________________________ Utility_______________Routine_Name________________________ Convert Option File ^OPTCON Create_Option_File____^OPTBLD_____________________________ For more information about the ^OPTMAN Utility, see Appendix B. Performance Utilities Use the Performance Utilities to gather statistics on DDP use, global and routine performance, and lock management. You can access the following utilities from the System Utilities menu (^SYS): 7-16 DSM System Utilities __________________________________________________________ Utility____________________Routine_Name___________________ DDP Statistics ^DDPSTA Global Statistics ^GLSSTA _______________________________ Utility_______Routine_Name_____ Monitor MONITOR^GLSSTA Record RECORD^GLSSTA Replay________REPLAY^GLSSTA____ Lock Management ^LKMSTA Statistics _______________________________ Utility_______Routine_Name_____ Monitor MONITOR^LKMSTA Record RECORD^LKMSTA Replay________REPLAY^LKMSTA____ Routine and Global ^RTH Histograms _______________________________ Utility_______Routine_Name_____ Help ^RTHELP Log ^RTHIST Print ^RTHISTP Save SAVE^RTHISTP Status STATUS^RTH Stop__________HALT^RTH_________ Transaction and ^TPSTA Journaling_Statistics_____________________________________ For information about ^GLSSTA and ^RTH, see Chapter 6. For information about ^DDPSTA, ^LKMSTA, and ^TPSTA, see the DSM for OpenVMS Database Operations Guide. System Management Utilities (^SYSMAN) Use the ^SYSMAN Utilities to start up and shut down DSM, to provide access control, and to display memory and system use. You can access the following System Management Utilities from the ^SYSMAN Utility menu. DSM System Utilities 7-17 __________________________________________________________ Utility_______________Routine_Name________________________ Access Control ^ACL ____________________________________ Utility_____________Routine_Name____ Add/Modify User ADD^ACL Delete User DELETE^ACL Modify Active ^ACLSET Authorizations Print_______________PRINT^ACL_______ Force Exit ^FORCEX License Edit ^LMFEDT Clusterwide Lock CLUSTER^LOCKTAB Table Display Lock Table Display ^LOCKTAB Login ^LOGIN Memory ^MEMORY ____________________________________ Utility_____________Routine_Name____ Requirement ^MEMREQ Usage_______________^MEMUSE_________ Show DSM Users ^%SY Shutdown ^SHUTDWN Startup ^STU Tied Routines ^TIED ____________________________________ Utility_____________Routine_Name____ Add Port ADD^TTPORT Delete Port DELETE^TTPORT Modify Routine MODIFY^TTROU Table Show Tied Ports SHOW^TTPORT Show_Tied_Routines__SHOW^TTROU______ __________________________________________________________ For information about the ^ACL, ^LOGIN, ^STU, and ^TIED Utilities, see Chapter 3. For information about the ^LMFEDIT Utility, see Chapter 1. For information about the ^MEMORY Utility, see Chapter 5. For information about the ^%SY Utility, see the DSM for OpenVMS Programmer's Guide. 7-18 DSM System Utilities The following sections describe the ^FORCEX, the ^LOCKTAB, and the ^SHUTDWN Utilities. Force Exit (^FORCEX) The ^FORCEX Utility forces image exit for a specified DSM user process locally or on any node of a cluster. When you invoke ^FORCEX, you can specify a process ID from any node in the cluster by responding to the prompt: Display local or cluster DSM processes [L, C, or N] ? Enter N if you do not want to display a list of processes and process IDs (PIDs). Enter L if you want to display a list of processes on the local node. Enter C if you want to display a list of processes on the cluster. After viewing the list of processes, you can specify the PID of the process you want to force exit from DSM. This ensures that the image exits properly from the DSM global subsystem. After the exit from DSM has been forced, you can use the DCL command STOP/ID to delete the process from the OpenVMS system. Cluster Lock Table Display and Lock Table Display (CLUSTER^LOCKTAB and ^LOCKTAB) The ^LOCKTAB Utility displays the DSM Lock Table for the current system. The Lock Table contains the following information: o Owner PID o Lock type o Variable name Starting with Version 7.0, ^LOCKTAB has a new entry point: CLUSTER^LOCKTAB This new entry point produces a lock table listing for all nodes in your cluster. The following shows examples of a local lock table list and of a cluster lock table listing: DSM System Utilities 7-19 > D ^LOCKTAB *** DSM LOCK TABLE *** OWNER PID LOCK TYPE VAR NAME --------------------------------------------- 22A000E3 Exclusive lock ^[MGR,AAA]PMF(NODE,DWE) > D CLUSTER^LOCKTAB *** DSM LOCK TABLE *** OWNER PID LOCK TYPE VAR NAME ------------------------------------------- 22A000E3 Exclusive lock ^[MGR,AAA]PMF(NODE,DWE) 2280019F Exclusive lock ^[MGR,AAA]%RPC(28,EXECUTOR) 2280018C Exclusive lock ^[MGR,AAA]PMF(NODE,DWV) Login Control (^LOGIN) The ^LOGIN Utility allows you to enable (ENABLE^LOGIN) and disable (DISABLE^LOGIN) user logins. Shutdown (^SHUTDWN) The ^SHUTDWN Utility shuts down a DSM configuration. When you shut down a configuration, background DSM processes are stopped, application processes are exited, and volume sets are dismounted. 7-20 DSM System Utilities 8 ________________________________________________________________ Using DSM as a Visual M Remote Application Server This chapter describes how to establish your DSM systems as a Visual M remote application server. Overview of Visual M and DSM DSM for OpenVMS can function as a remote application server and as a client to InterSystems' Visual M[TM]. Visual M is a graphical interface running on any of the following Microsoft Windows platforms: o Windows 3.1[TM] o Windows NT[TM] o Windows 95[TM] Visual M consists of Visual Basic controls and other elements that allow you to create Visual Basic[TM] programs with DSM applications operating in a DSM for OpenVMS environment to create distributed client-server applications. Visual M Structure Visual M has two major components: o The Visual M client software o The Visual M server process The Visual M client software allows you to create Visual M applications. The Visual M client software runs within a Microsoft Windows environment on a client machine. The client need only have the Visual M subsystem installed; it does not have to have a local implementation of M or Caché ObjectScript (unless you want to use the client machine as a local Visual M server). Using DSM as a Visual M Remote Application Server 8-1 Visual M applications communicate with M or Caché systems holding the routines and globals the application needs. Those M or Caché systems are Visual M servers and run Visual M server processes. If the M or Caché system is running on the same platform as the Visual M client, that system is a local Visual M server. Currently, only Open M [DTM] and Caché for Windows 95 and Windows NT platforms can function as local Visual M servers. If the M or Caché system is running on another platform from the Visual M client, that system is a remote Visual M server. DSM systems can only function as remote Visual M servers. When functioning as a remote Visual M server, a DSM system has a Visual M Remote server process running within the DSM environment. When requested by the Visual M client, the remote server process makes calls to the DSM interpreter. Visual M Client-Server Communications One or more Visual M clients running on personal computers access the remote DSM server using TCP/IP communications. Using DSM as a remote server, each client can: o Run DSM routines o Access DSM data o Control presentation attributes of the GUI (Graphical User Interface) Whenever a client requests to run an application, the remote Visual M server takes the following steps: o Spawns a server process to run in the DSM environment o Assigns the client to a TCP/IP port The Visual M remote server allocates a separate TCP/IP port for each application server process it starts. It assigns the port numbers sequentially, starting with the port following the port configured for the Visual M server. Consequently, you must set aside a range of TCP/IP ports for use exclusively by Visual M. 8-2 Using DSM as a Visual M Remote Application Server Configuring Visual M Server Support Take the following steps to run a remote Visual M server on DSM for OpenVMS: 1. Install and configure TCP/IP on your OpenVMS system. 2. Install the DSM software. 3. Load the Visual M server routines into your DSM configuration from the file SYS$LIBRARY:DSM$MVB.SAV. 4. Use the DSM ^CONFIG utility to select Visual M support. 5. Map Visual M namespace to the DSM UCI and volume set of the server. 6. Start the Visual M server process using the DSM ^STU or START^MVB utilities. This process, described in detail in the following sections, is provided as a convenience to you. This process is designed to start the first Visual M server for a configuration. To start additional Visual M servers on a configuration, follow the procedures described in the on-line help provided with Visual M. Installing TCP/IP To use DSM for OpenVMS with Visual M, you must first install and configure TCP/IP communications on your OpenVMS system. Currently, you can use the following implementations of TCP/IP with Visual M: o UCX TCP/IP[TM] o TCPware for OpenVMS[TM] o TGV Multinet[TM] See the documentation supplied with your TCP/IP software for the steps you must take to install and configure TPC /IP. Installing the DSM Software You must then install the DSM software. See Chapter 1 for more information about installing DSM software. The Visual M Server software is installed when you install DSM. Using DSM as a Visual M Remote Application Server 8-3 Loading the Visual M Server Routines As part of the DSM installation, Visual M server routines are placed into the SYS$LIBRARY directory in the file DSM$MVB.SAV. These routines are in the ^%PS utility format. The ^%PS format saves only the DSM interpreter code. Source code for these routines is not supplied. Each time you install a new release of DSM, you must load the Visual M server routines supplied with that DSM release. Take the following steps to load the Visual M server routines. 1. Log into DSM with the /MANAGER qualifier. 2. Use the ^CONCLQ utility to set the configuration-wide default routine buffer to a minimum value of 12000. (The Visual M server routines require a routine source buffer larger than the default value supplied with DSM.) 3. Start a DSM configuration using the ^STU utility and log into DSM with the /MANAGER command line qualifier. 4. Use the ^%PR utility to restore the routines, as follows: $ DSM/MAN DSM V7.x for OpenVMS VAX DSMMGR [MGR,MEL] >D ^%PR Precompiled Routine Restore Restore precompiled routines from Magtape or a File ? F <>Return Input File ? > SYS$LIBRARY:DSM$MVB.SAV Routines were saved on 1-JUN-1997 17:39 Header: DSM MVB - MVB server routines Restore All (A), Selected (S), or Confirm on overwrite (C) ? 8-4 Using DSM as a Visual M Remote Application Server The ^%PR utility then restores the Visual M server routines and lists the names of those routines on your screen as it restores them. The Visual M server routine names use the %mvb (lowercase) prefix. You should be aware of potential routine name conflicts with your own application routines that may use this naming convention before you restore the Visual M server routines. Make sure that you do not move the %mvb routines to the remote client(s). The %mvb routines must reside on the machine on which the Visual M server is running. Using ^CONFIG to Enable Support for Visual M You use the ^CONFIG utility to include support for Visual M serving. When you select support for Visual M through ^CONFIG, you must enter a TCP/IP port number that the Visual M server will use to receive connection requests from Visual M clients. The port number you choose must be the same on both the client and the server, otherwise communications can not take place. The following is an example of how to enable Visual M support: $ DSM/MANAGER DSM V7.x for OpenVMS VAX DSMMGR [Baseline] >D ^CONFIG Define a DSM configuration Type ? for HELP at any time Would you like extended help [Y OR N] ? Y Enter the configuration identifier <1> . . . Using DSM as a Visual M Remote Application Server 8-5 DSM provides server support for the InterSystems' Visual M product. This permits PC applications written in Visual Basic to access DSM globals and routines. Answer YES to enable server support for Visual M. A Visual M server will be started at DSM configuration startup. Answer NO to disable server support for Visual M. Include support for Visual M application serving [Y OR N] ? When TCP/IP communications is chosen for connecting a Visual M desktop client to DSM for OpenVMS, a TCP/IP port number must be configured. This port will be used to initiate connections between the PC and the Visual M servers running under DSM. Enter a port number ranging from 1024 to 65535. Note that port numbers below 1024 are generally reserved by TCP/IP for use by privileged system processes. The port number selected must match the port number configured for your Visual M desktop environment. You can configure your PC to use the same port number by running the Visual M Server Setup utility located in the Visual M program group. Port number 6001 is the default port for both the server and the client. Enter the TCP/IP port for use by the Visual M server <6001> The Visual M Server allocates a separate TCP/IP port for use by each application server process it starts. The port numbers are assigned sequentially starting with the port number configured for the Visual M server. Consequently, you must set aside a range of TCP/IP ports for use exclusively by Visual M. Enter the number of TCP/IP port numbers to reserve for use by Visual M application servers. You should reserve sufficient ports to handle the number of users you expect to be concurrently running Visual M applications. Enter the number of TCP/IP ports to reserve for Visual M <512> 8-6 Using DSM as a Visual M Remote Application Server Defining UCIs and Volumes as Namespaces The client system locates and accesses the DSM server using a namespace. With Visual M, namespaces are abstract names that you must map to a UCI and volume set. You map a namespace to a UCI and volume set through a global, ^%NSpace. This global resides in the manager's directory of the configuration that is the remote server. To perform the mapping, you must take two steps: o Create the mapping on the server o Create the mapping on the client Creating the Mapping on the Server To create the mapping on the server, log into the system manager's account in the configuration you want to use as a remote server and manually create a node in the ^%NSpace global: > S ^%NSpace(namespace)="UCI,VOL" Creating the Mapping on the Client You create a namespace mapping by using the Visual M Server Manager on one of the client computers. Follow the instructions for creating a namespace mapping contained in the System Manager's Guide provided with your InterSystems client implementation. Defining DSM Configurations as Remote Servers You define DSM configurations as remote servers through the Namespace/Network Configuration Editor on your client system. The Editor is accessible through an icon on the Open M Toolbar. See the System Manager's Guide provided with your InterSystems client implementation about how to perform this step. Using DSM as a Visual M Remote Application Server 8-7 Starting and Stopping the Visual M Server Process When you enable Visual M support using the ^CONFIG utility, a Visual M server process is automatically started during DSM configuration startup. The ^STU utility creates the MVBSTART.LOG file to hold events logged by the Visual M server. You should inspect this file if the Visual M server fails to start. You can also start the Visual M server while the configuration is already running. Log into DSM using the /MANAGER qualifier and use the START^MVB utility: $ DSM/MANAGER DSM V7.x for OpenVMS VAX DSMMGR [MGR,MEL] >D START^MVB Visual M server startup executing ... Visual M startup log file is: SYS$SYSDEVICE:[DSMMGR]MVBSTART.LOG To stop the Visual M server, you use the STOP^MVB utility as follows: > D STOP^MVB Mapping Visual M Namespaces to DSM UCI and Volume Sets The Visual M development and run-time environment locates and accesses an application on a remote server using a namespace. Visual M namespaces are abstract names that you must map into an application environment notation that is native to the M server being accessed. Under DSM for OpenVMS, a Visual M namespace is mapped to a DSM UCI and volume set. You can assign Visual M applications specific namespaces in which to run. When a Visual M application starts, the assigned namespace is translated to the UCI and volume set specified in the namespace table, ^%NSpace. A Visual M application server then starts in the target UCI and volume set. All global and routine references made by the Visual M application are treated as though the client application user were 8-8 Using DSM as a Visual M Remote Application Server logged into the DSM UCI and volume set represented by the namespace. You create a namespace mapping by using the Visual M Server Manager on one of the client computers. The Visual M Server Manager is located Caché Toolbar. Customizing the Visual M Application Server By default, DSM starts the Visual M remote server process with startup parameters that are suitable for most DSM environments. The supplied parameters are the same regardless of whether you start Visual M during configuration startup or by using the START^MVB utility. With these default parameters the Visual M server has the following operational characteristics: o The server is started with the /MANAGER command-line qualifier as a background DSM process. o New application server processes start for each client which connects. o The TCP/IP port number specified in ^CONFIG handles the connection requests. o TCP/IP port numbers are allocated to application server processes within the port number range specified in ^CONFIG. You can customize the operational characteristics of the Visual M server for your environment. To do this, write an M program that calls the Visual M Server routine, %mvb, directly. The %mvb routine provides a flexible application program interface (API) which supports the operation of a server process in a variety of environments. The Visual M help facility discusses the callable entry points and parameters for ^%mvb in detail. If you write your own customized startup procedure for the Visual M server, do not include configuration support for Visual M through the ^CONFIG utility. Using DSM as a Visual M Remote Application Server 8-9 Creating Visual M Security To create a security system, you invoke Visual M on any client computer and use the Visual M Server Manager, accessible from the Open M Toolbar. The Server Manager allows you to define user names and passwords for all client users. Users are then prompted for these names and passwords whenever they attempt to run a Visual M application. The Server Manager also allows you to define "trusted applications" that do not require a login. See the Visual M information listed in the following section for details. Visual M Information Sources For more information about how to configure and run a Visual M server from DSM, see the following InterSystems information sources: o Visual M Version 7.0 Release Information o The Visual M Help facility (accessible from the Help icon on the Caché Toolbar) 8-10 Using DSM as a Visual M Remote Application Server 9 ________________________________________________________________ Installing Caché Weblink This chapter describes how DSM for OpenVMS can function as a remote database server for World Wide Web-enabled tools through Caché WebLink[TM] and Caché WebLink TP[TM] Introduction to Caché/Weblink Weblink uses the TCP/IP TELNET remote login and communica- tions protocol to provide a high performance data exchange mechanism between M databases on a DSM machine and a World Wide Web server running under a Windows[TM] operating system. The basic process is as follows: 1. Web clients send Caché Weblink a request. 2. Caché Weblink passes the request to a DSM system. 3. The DSM system responds to the request. 4. Caché Weblink passes the response back to the requesting Web client. Figure 9-1 shows the architecture of using a World Wide Web tools with DSM database systems through Caché Weblink. As the previous figure shows, dynamic link libraries (DLLs) or object libraries manage communications between the client and the DSM database. They are responsible for network communications. The Caché Weblink Remote DSM Server (%MGW) on the DSM system interprets and responds to the requests received from the client. For a complete discussion of Caché Weblink, its capabili- ties, and how to install it, see the WebLink documentation provided on the Caché Weblink software CD-ROM or on the InterSystems Web site. Installing Caché Weblink 9-1 Installing Caché Weblink on DSM As Figure 9-1 shows, the Remote DSM Server, %MGW, is the only Weblink component residing on a DSM machine. To use Caché WebLink with DSM, you must install %MGW in the System Manager's UCI for the configuration you want to use for the Server. After you install, or upgrade to, Version 7.0 of DSM for OpenVMS, you can find two save sets in your SYS$LIBRARY directory: o DSM$MGW.SAV o DSM$MGW2.SAV DSM$MGW.SAV holds %MGW, the precompiled Remote DSM Server. DSM$MGW2.SAV holds %MGW2, the source Remote DSM Server. The %MGW2 routine is a template with HTML code. You must restore both of these routines to the manager UCI of a DSM configuration on the server. To restore %MGW, invoke ^%PR from the Manager UCI of the configuration you want to use, as follows: $dsm/man DSM X.X for OpenVMS VAX d^%PR Precompiled Routine Restore Restore precompiled routines from Magtape or a File ? F Input File ? > SYS$LIBRARY:DSM$MGW.SAV Header Information: DSM VX.X for OpenVMS VAX %PS Precompiled routines saved from xxxx on 23-OCT-1997 01:15:12 DSM PCODE for MGW Utilities (WEBLINK) Restore All (A), Selected (S), or Confirm on overwrite (C) ? %MGW 1 precompiled routine restored > 9-2 Installing Caché Weblink To restore MGW, invoke ^%RR from the Manager UCI of the configuration you want to use, as follows: > D ^%RR Routine Restore Input Device ? > SYS$LIBRARY:DSM$MGW2.SAV Restoring routines from SYS$SYSROOT:[SYSLIB]DSM$MGW2.SAV;1 Saved by %RS from xxxx on 23-OCT-1997 01:15:13.91 Header: DSM Source for MGW2 template (WEBLINK) Restore All (A), Selected (S), or Confirm on overwrite (C) ? %MGW2 1 routine restored Input Device ? > ________________________Note ________________________ You can also use Caché Weblink on DSM for OpenVMS Versions 6.4, 6.5, 6.5A. 6.6 6.6A, and 7.0 by installing MGW and MGW2 on those systems as described previously or by copying the appropriate DSM routines from the Caché Weblink self-extracting archive after you have downloaded the archive from the InterSystems Web page. See the Caché Weblink documentation for more information _____________________________________________________ After you have copied the files to the manager's UCI, you edit the %MGW2 template to customize it for your site. See the Caché Weblink documentation on the Caché Weblink CD-ROM or available from the InterSystems' Web site for more information. Installing Caché Weblink 9-3 10 ________________________________________________________________ Installing Graphic Library Utilities This chapter discusses how to install the DSM graphic library utilities on a Windows[TM]-based client machine. Overview of the Graphic Library Utilities Starting with Version 7.0, DSM for OpenVMS includes two sets of library utilities: o The command-line interface (CLI) Library Utilities o The graphic Library Utilities The CLI Library Utilities are the traditional DSM Library Utilities. You can use them when you are in programmer mode on any DSM system. The CLI utilities are described in detail in the DSM for OpenVMS Programmer's Guide. The new graphic Library Utilities allow you to perform various routine and global functions on a Windows[TM]- based Caché client system through a GUI interface. Installing the Graphic Library Utilities You take the following steps to install the Graphic Library Utilities: 1. Install the Visual M routines and GUI routines in SYS$LIBRARY on your DSM system. 2. Define UCIs and volumes you want to access as Namespaces 3. Define a DSM configuration on a VAX or Alpha as a remote server through the Network/Namespace Configuration Editor on the client system Installing Graphic Library Utilities 10-1 Installing Visual M and GUI Routines in SYS$Library To install Visual M and the GUI routines into your configuration, take the steps described in Chapter 8. That chapter describes the steps you need to take to prepare your system, including: o Installing and configuring TCP/IP on your OpenVMS system o Installing DSM o Loading the Visual M server routines into your DSM configuration from the File SYS$LIBRARY:DSM$MVB.SAV. At this point, you need to load the Graphic Library Utility routines. These routines are in a file called DSM$GUI.SAV in the SYS$LIBRARY directory. Like the routines in DSM$MVB.SAV, the routines in DSM$GUI.SAV are in ^%PS Utility format. The ^%PS format saves only the DSM interpreter code. Source code for these routines is not supplied. Each time you install a new release of DSM, you must load the Graphic Library Utility routines supplied with that DSM release. Take the following steps to load the Graphic Utilities routines. 1. Log into DSM with the /MANAGER qualifier. 2. Start a DSM configuration using the ^STU utility and log into DSM with the /MANAGER command line qualifier. 3. Use the ^%PR utility to restore the routines, as follows: $ DSM/MAN DSM V7.x for OpenVMS VAX DSMMGR [MGR,MEL] >D ^%PR Precompiled Routine Restore 10-2 Installing Graphic Library Utilities Restore precompiled routines from Magtape or a File ? F <>Return Input File ? > SYS$LIBRARY:DSM$GUI.SAV Routines were saved on 1-JUN-1997 17:39 Header: DSM GUI - GUI Utility routines Restore All (A), Selected (S), or Confirm on overwrite (C) ? The ^%PR utility then restores the Graphic Library Utility routines and lists the names of those routines on your screen as it restores them. The Graphic Library Utility routine names use the %w (lowercase) prefix. You should be aware of potential routine name conflicts with your own application routines that may use this naming convention before you restore the Graphic Library Utility routines. Make sure that you do not move the %w routines to the remote client(s). The %w routines must reside on the machine on which the Visual M server is running. Define UCIs and Volumes as Namespaces The client system locates and accesses the DSM server using a namespace. As with Visual M, namespaces are abstract names that you must map to a UCI and volume set. You map a namespace to a UCI and volume set through a global, ^%NSpace. This global resides in the manager's directory of the configuration that is the remote server. To perform the mapping, you must take two steps: o Create the mapping on the server o Create the mapping on the client Creating the Mapping on the Server To create the mapping on the server, log into the system manager's account in the configuration you want to use as a remote server and manually create a node in the ^%NSpace global: > S ^%NSpace(namespace)="UCI,VOL" Installing Graphic Library Utilities 10-3 Creating the Mapping on the Client You create a namespace mapping by using the Visual M Server Manager on one of the client computers. Follow the instructions for creating a namespace mapping contained in the System Manager's Guide provided with your InterSystems client implementation. Defining DSM Configurations as Remote Servers You define DSM configurations as remote servers through the Namespace/Network Configuration Editor on your client system. See the System Manager's Guide provided with your InterSystems client implementation about how to perform this step. Using the Graphic Library Utilities After installation, users at your site can use the Graphic Library Utilities from an InterSystems client system to view and manipulate routines and globals on the DSM server. To do so, they take the following steps: 1. Invoke the graphic utilities as described in the Programming Guide for your Caché system. 2. Where directed, specify Routine or Global Library Utilities. See the DSM for OpenVMS Programmer's Guide for a description of how to use these Graphic Library Utilities. 10-4 Installing Graphic Library Utilities A ________________________________________________________________ Installing DSM Software in an Alternate Root This appendix describes the procedure for installing DSM in an alternate root. Using DSM from an Alternate System Root If you want to install a new version of DSM and do not want to overwrite your existing DSM system software, you can install the new release in an alternate system root. The VMSINSTAL procedure normally copies the various command procedures, routine files, and executable images from the DSM software distribution kit to appropriate system directories. System directories are constructed as a hierarchy of directories, which are descendants of a primary system root. For example, the top-level directory of system root SYS0 is SYS$SYSDEVICE:[SYS0]. Figure A-1 describes some of the system directories that are descendants of the SYS0 system root. You can use an option provided by VMSINSTAL to distribute the software kit contents into an alternate root of directories. The alternate root directories are outside the hierarchy of primary system directories. An alternate root is a set of directories with a structure that is parallel to the primary system root directories. However, the top-level directory of the alternate root is not a OpenVMS system root. For example, an alternate root directory for a special distribution of DSM might be constructed as shown in Figure A-2. Installing DSM Software in an Alternate Root A-1 When installing the DSM software into this alternate root, files destined for SYS$LIBRARY are deposited by VMSINSTAL into the parallel directory of the alternate root, SYS$SYSDEVICE:[DSM070.SYSLIB]. Files destined for SYS$SYSTEM are deposited in SYS$SYSDEVICE:[DSM070.SYSEXE] and so on. Once the installation is complete, the alternate root software can be selectively run on a OpenVMS group basis. This is done by redefining system logical names as search lists within the target group logical name table. The following table is an example of how logical name search lists are used to redirect access to DSM software resident in the alternate root. ________________________________________________________________ Logical_Name________Search_List_Equivalent______________________ SYS$EXAMPLES SYS$SYSDEVICE:[DSM070.SYSHLP.EXAMPLES] ,SYS$SYSROOT:[SYSHLP.EXAMPLES] SYS$HELP SYS$SYSDEVICE:[DSM070.SYSHLP],SYS$SYSROOT:[SYSHLP] SYS$LIBRARY SYS$SYSDEVICE:[DSM070.SYSLIB],SYS$SYSROOT:[SYSLIB] SYS$LOADABLE_ SYS$SYSDEVICE:[DSM070.SYS$LDR],SYS$SYSROOT:[SYS$LDR] IMAGES SYS$MANAGER SYS$SYSDEVICE:[DSM070.SYSMGR],SYS$SYSROOT:[SYSMGR] SYS$MESSAGE SYS$SYSDEVICE:[DSM070.SYSMSG],SYS$SYSROOT:[SYSMSG] SYS$SHARE SYS$SYSDEVICE:[DSM070.SYSLIB],SYS$SYSROOT:[SYSLIB] SYS$STARTUP SYS$SYSDEVICE:[DSM070.SYS$STARTUP] ,SYS$SYSROOT:[SYS$STARTUP],SYS$SYSROOT:[SYSMGR] SYS$SYSTEM SYS$SYSDEVICE:[DSM070.SYSEXE],SYS$SYSROOT:[SYSEXE] SYS$TEST____________SYS$SYSDEVICE:[DSM070.SYSTEST],SYS$SYSROOT:[SYSTEST] When these search lists are active, an attempt to access a file in SYS$LIBRARY, SYS$MANAGER, or other system directories results in a search for the file in the alternate root first. If the file is not found in the alternate root, the file is accessed from the primary root. A-2 Installing DSM Software in an Alternate Root The DSM$ALTROOT.COM procedure initializes the group logical name table. Once the group logical name table is initialized with the search lists, any OpenVMS user logged in to an account within the group runs DSM from the alternate root. Users in other OpenVMS groups continue to run DSM from the primary root software. Installing software in an alternate root allows you access to the full functionality of the new software without impact to the currently installed version. It provides a safe environment in which you can test and debug until you are satisfied that your application code works under the new release. You can keep one or more releases of DSM on line within separate alternate roots and selectively enable each version for use by specific OpenVMS groups. Once you are satisfied that you have made all of the required changes to your application, you can reinstall the DSM image into the primary system root and delete the files in the alternate root. ________________________Note ________________________ You cannot start DDP from an alternate root when an incompatible DDP driver is already loaded into the system. _____________________________________________________ The following are the major steps involved in installing software in an alternate root: 1. Use the OpenVMS Backup Utility to extract a copy of the DSM$ALTROOT_INSTALL.COM procedure from the DSM software distribution kit. 2. Use DSM$ALTROOT_INSTALL.COM to create the alternate root directories and install the DSM software distribution kit. 3. Use DSM$ALTROOT.COM to create and initialize a DSM environment manager's account for the new alternate root. Installing DSM Software in an Alternate Root A-3 4. Use DSM$ALTROOT.COM to initialize the group logical name search lists for all users within the GROUP. 5. Log in to the new manager account and use the command procedure SYS$MANAGER:DSM$CONFIGURE.COM to create volume sets and define new configurations. 6. Edit your system startup files to initialize alternate root installation on system reboot. Installing DSM in an Alternate Root Use the following procedure to install DSM software in an alternate OpenVMS root: 1. Log in to the OpenVMS system manager's account. 2. Register and load a valid DSM Version 7.1 license. For detailed information, see Chapter 2 of the DSM for OpenVMS Release Notes. The DSM Version 7.1 license that you load is sufficient to operate DSM Version 7.1 and all previous versions of DSM. 3. Extract the DSM$ALTROOT_INSTALL.COM procedure from the DSM software distribution kit. Enter the following OpenVMS Backup Utility command line to do this: $ BACKUP/LOG KIT_DEVICE:DSM070.B/SAVE - _$ /SELECT=DSM$ALTROOT_INSTALL.COM SYS$MANAGER:*; where: KIT_DEVICE is a tape, disk, or CD-ROM device on which the DSM kit is located, for example, DKA400: (The device can be specified by a logical name.) 4. Install the DSM software into an alternate root using the DSM$ALTROOT_INSTALL.COM procedure by entering the following command line: $ @SYS$MANAGER:DSM$ALTROOT_INSTALL A-4 Installing DSM Software in an Alternate Root The DSM$ALTROOT_INSTALL procedure creates all required alternate root subdirectories. It then automatically runs the SYS$UPDATE:VMSINSTAL procedure with the appropriate options and parameters. The VMSINSTAL software kit installation procedure is identical to the procedure used for primary system root installations. Chapter 1 describes primary system root installation in detail. 5. Next, create one or more DSM manager accounts to use with the alternate root installation. You do this by entering the following command line: $ @ddcu:[root_dir]DSM$ALTROOT INIT MANAGER where: ddcu is the physical or logical name of the disk on which you installed the alternate root root_dir is the top-level directory name of the alternate root 6. Finally, use the DSM$ALTROOT command procedure to initialize the group logical name tables for the newly created DSM environment manager account. Do this by entering the following command: $ @ddcu:[root_dir]DSM$ALTROOT INIT group_number where: ddcu is the physical or logical name of the disk on which you installed the alternate root root_dir is the top-level directory name of the alternate root group_ is the OpenVMS group number of the number account you initialized for use within the alternate root 7. Edit your site-specific OpenVMS startup files so that the OpenVMS groups selected to use the alternate root software are properly initialized at boot time. This is accomplished by calling DSM$ALTROOT once for each group you want to ini- tialize. For example, add the following commands to SYS$STARTUP:SYSTARTUP_V5.COM (OpenVMS VAX systems) or to SYS$STARTUP:SYSTARTUP_VMS.COM (OpenVMS Alpha Installing DSM Software in an Alternate Root A-5 systems) to initialize groups 210 and 220 for use with alternate root software that is resident in SYS$SYSDEVICE:[DSM070]: $ @SYS$SYSDEVICE:[DSM070]DSM$ALTROOT INIT 210 $ @SYS$SYSDEVICE:[DSM070]DSM$ALTROOT INIT 220 You can also choose to start configurations from the alternate root accounts at OpenVMS boot time. In the following example, DSMMGR1 and DSMMGR2 are environment manager accounts that are located in groups 210 and 220 and, therefore, use alternate root software. Both groups have already been initialized using calls to DSM$ALTROOT. The following commands were added to SYS$STARTUP:SYSTARTUP_ V5.COM: $ SUBMIT/USER=DSMMGR1/QUEUE=DSM$BATCH - SYS$SYSDEVICE:[DSM070.SYS$STARTUP]DSM$STARTUP $ SUBMIT/USER=DSMMGR2/QUEUE=DSM$BATCH - SYS$SYSDEVICE:[DSM070.SYS$STARTUP]DSM$STARTUP Running the DSM$ALTROOT_INSTALL.COM Procedure The following example illustrates the installation of DSM into an alternate root and the initialization of accounts that use the alternate root. This example uses CD-ROM device NURSE$DKA400. $ BACKUP/LOG NURSE$DKA400:[DSM070.KIT]DSMxxx0nn.B/SAVE - _$ /SELECT=DSM$ALTROOT_INSTALL.COM SYS$MANAGER:*; BACKUP-S-CREATED, created SYS$SYSROOT:[SYSMGR]DSM$ALTROOT_INSTALL.COM;1 where: 0nn The version of DSM being installed. xxx VAX if you are installing on an OpenVMS VAX system. AXP if you are installing on an OpenVMS Alpha system. $ @SYS$MANAGER:DSM$ALTROOT_INSTALL DSM Alternate Root Installation Procedure A-6 Installing DSM Software in an Alternate Root This procedure will create the directories necessary to accomplish an alternate root installation of DSM and then optionally call the VMSINSTAL procedure to do the installation. Enter the device and root directory for the alternate root to install into using the format: ddcu:[directory] where: ddcu is the device or logical name of the device that will hold the alternate root [directory] is the root directory name for the alternate root (If the directory does not exist, it will be created.) Enter alternate root device and directory: SYS$SYSDEVICE:[DSMxxx06x] Enter alternate root device and directory: SYS$SYSDEVICE:[DSM070] %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSEXE] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSHLP] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSHLP.EXAMPLES] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSLIB] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSMGR] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSMSG] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSUPD] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYS$STARTUP] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSTEST] created %CREATE-I-CREATED, SYS$SYSDEVICE:[DSM070.SYSLDR] created The alternate root has been successfully created. To install DSM into this root, the following command will be executed: @SYS$UPDATE:VMSINSTAL DSM070 KIT_DEVICE OPTIONS R _ _DSM9$DUA0:[DSM070.] Do you want to install the DSM kit now [Y or N]: Y Enter the kit device name: DKA400: Installing DSM into root SYS$SYSDEVICE:[DSM070] Installing DSM Software in an Alternate Root A-7 Note that if you are installing the DSM kit on an OpenVMS Alpha system, the following question is displayed: Cannot determine the architecture of target device. This device is not a fully configured system disk. You may continue the installation at your own risk. If you chose to continue, you must specify the architecture of the target device. Options: 1 Exit 2 Alpha architecture 3 VAX architecture ************************************************************************ * Specify option number [1]: 2 Specify option number [1]: 2 The VMSINSTAL procedure continues as follows: OpenVMS Software Product Installation Procedure x.x It is 14-JUN-1997 at 12:32. Enter a question mark (?) at any time for help. . . . The VMSINSTAL procedure is similar to a primary system root installation at this point. You can answer all questions as though you were installing DSM into a primary system root. Note that the IVP does not run when installing DSM into an alternate root. DSM image files must be named uniquely as shown in Table A-1. Table_A-1_Alternate_Root_Image_Names______________________ Primary_Root_Name__________Alternate_Root_Name____________ DSM.EXE DSM070.EXE (continued on next page) A-8 Installing DSM Software in an Alternate Root Table_A-1_(Cont.)_Alternate_Root_Image_Names______________ Primary_Root_Name__________Alternate_Root_Name____________ DSM$SHARE.EXE DSM$SHARE070.EXE DSM$SHRLIB.EXE DSM$SHRLIB070.EXE DSM$MESSAGE.EXE DSM$MESSAGE070.EXE DSM$MT_EBCASC.EXE DSM$MT_EBCASC070.EXE DSM$XWIN_XLIB.EXE DSM$XWIN_XLIB070.EXE DSM$XWIN_XTOOLKIT.EXE DSM$XWIN_XTOOLKIT070.EXE DSM$XWIN_XMOTIF.EXE DSM$XWIN_XMOTIF070.EXE DSM$XWIN_XMOTIFRM.EXE DSM$XWIN_XMOTIFRM.EXE DSM$XWIN_ZXMUMPS.EXE DSM$XWIN_ZXMUMPS070.EXE DSM$XWIN_ZDAS.EXE__________DSM$XWIN_ZDAS070.EXE___________ When VMSINSTAL is complete, DSM$ALTROOT_INSTALL displays informational text that describes the steps required to initialize DSM environment manager accounts. . . . %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installation of DSM V7.1 completed at 12:48 VMSINSTAL procedure done at 12:48 Installation of the DSM software kit is now complete. To initialize one or more DSM environment manager's accounts that use the alternate root software, type the following command line while logged in to a privileged system account: @SYS$SYSDEVICE:[DSM070]DSM$ALTROOT INIT MANAGER Do you want to initialize a manager's account now [Y OR N]: Y The installation of the DSM software distribution kit into the alternate root is complete. You must now initialize a manager account for use with the alternate root. Manager account initialization within an alternate root is identical to the process used within a primary system root. However, you do not use the DSM$INIT command Installing DSM Software in an Alternate Root A-9 procedure to create the manager account. Instead, use the DSM$ALTROOT procedure with the INIT MANAGER parameters to initialize the manager account. DSM$ALTROOT_INSTALL initializes a manager account on completion of installation if you choose. $@SYS$SUSDEVICE:[DSM070]DSM$ALTROOT INIT MANAGER Installing DSM Alternate Root Images: _DSM5$DJA1:[DSM070.SYSEXE]DSM070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$SHARE070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$SHRLIB070.EXE _DSM5$DJA1:[DSM070.SYSMSG]DSM$MESSAGE070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$ECALL070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$MT_EBCASC070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$XWIN_XLIB070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$XWIN_XTOOLKIT070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$XWIN_XMOTIF070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$XWIN_XMOTIFRM070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$XWIN_ZXMUMPS070.EXE _DSM5$DJA1:[DSM070.SYSLIB]DSM$XWIN_ZDAS070.EXE Initializing Logical name table: LNM$PROCESS_TABLE DSM Environment Manager Initialization The DSM environment manager must have a OpenVMS account to define and control DSM configurations. This procedure allows you to create a new account or upgrade an existing OpenVMS account for use as a DSM environment manager. Enter the OpenVMS account name to use with DSM DSMALT The DSMALT account does not currently exist Do you wish to create and initialize this account [Y OR N] ? Each OpenVMS account must have a UIC identifier associated with it. A UIC is in the form: [GROUP,MEMBER] Where GROUP is an octal number less than 37777 and MEMBER is an octal number less than 177777 Enter the UIC to apply to this account when it is created. A-10 Installing DSM Software in an Alternate Root Enter the UIC for this account > [210,1] . . . Initialization of alternate root software is done on a OpenVMS group basis, so when you create an account for use with alternate root software, choose a OpenVMS group that does not have users currently using DSM software within the primary root. The remainder of the manager account initialization process for alternate root software is identical to the process used for primary root installations. Again, answer the remaining questions as though you were initializing an account for a primary root installation. For more detailed information, see Chapter 1. When DSM$ALTROOT completes, it describes the command required to set up the group logical name table for use with the alternate root. . . . The DSM management globals will now be updated . . . Updating DSM Management Global: ^[SYS$COMMON:[SYSLIB]]DSMMGR Initializing DSM Configuration Global: ^[DISK$USER:[DSMALT]]SYS Account DSMALT successfully initialized The account has been created with your specified password. However, for security reasons, the password has been set to expire. Please log in to the new account immediately and reset the account password. You can now log in to the DSM manager's account and use the SYS$MANAGER:DSM$CONFIGURE.COM command procedure to initialize DSM database volume sets, or create and start up DSM configurations. See the this manual for complete information about DSM configurations and see the DSM for OpenVMS Database Operations Guide for information about database volume sets. Before logging into the environment manager account, you must enter the following command from a privileged account: @SYS$SYSDEVICE:[DSM070]DSM$ALTROOT INIT 210 Installing DSM Software in an Alternate Root A-11 Keep in mind that this command must be re-entered each time you reboot your system to install the DSM alternate root images and create appropriate group logical names. The manager's account is initialized. You can initialize other environment manager accounts at a later time if necessary. To do so, enter the command: $ @SYS$SYSDEVICE:[DSM070]DSM$ALTROOT INIT MANAGER To prepare a OpenVMS group to use the alternate software, you must call the DSM$ALTROOT procedure again. This time the group number of the DSM environment manager's account just initialized is supplied as the input parameter. The DSM$ALTROOT procedure installs the DSM alternate root images as shareable, resident images using the OpenVMS Install Utility. It creates the appropriate logical name search lists for the group being initialized. The following dialogue is an example of how to use DSM$ALTROOT: $ @SYS$SYSDEVICE:[DSM070]DSM$ALTROOT INIT 210 Installing DSM Alternate Root Images: Initializing Logical name table: LNM$GROUP_000210 Alternate root successfully initialized for OpenVMS group 000210 You can now log in to the DSM manager's account (DSMALT) and run DSM Version 7.1 utilities and procedures just as though you were running from a primary system root. Installing DSM in an Alternate Root in a VMScluster Environment If you are installing DSM in a DSM environment, you must log in to the OpenVMS system manager's account on each node that will be running DSM and do the following: $ @SYS$DEVICE:[DSM070]DSM$ALTROOT INIT 210 This allows you to run DSM on that node in the cluster. A-12 Installing DSM Software in an Alternate Root Shutting Down DSM Configurations That Use Alternate Root Software When you shut down your OpenVMS system, ensure that all DSM configurations are shut down in an orderly manner. You can use the DSM$ALTROOT command procedure to shut down configurations that use alternate root software. To shut down a configuration running in an alternate root, include the following command line for each configuration in the SYS$MANAGER:SYSHUTDOWN.COM procedure: $ @ddcu:[root_dir]DSM$ALTROOT SHUTDOWN envnm where: ddcu is the physical or logical name of the disk on which you installed the alternate root root_ is the top-level directory name of the alternate dir root envnm is the OpenVMS user name of the DSM environment manager account Installing DSM Software in an Alternate Root A-13 B ________________________________________________________________ Using the Configuration Option File Utility (^OPTMAN) This appendix describes the Configuration Option File Utility (^OPTMAN). You can use ^OPTMAN to create a sequential file called a Configuration Option File.. The ^STU Utility can use the Configuration Option File to start up the configuration it defines. Using the Configuration Option File The Configuration Option File is a OpenVMS sequential file that defines a DSM configuration. It allows the DSM environment manager to redefine a configuration on a target system without using the ^CONFIG Utility. The Configuration Option File contains: o Definition keywords o Data keywords o Values that define a configuration The definition keywords are equivalent to many of the ^CONFIG questions. The data keywords are associated with definition keywords by function. You assign values to the data keywords to form the configuration definition. For example, DEFINE DDP is a definition keyword and NODE_NAME= is a data keyword associated with DEFINE DDP. You assign a value to the data keyword, for example: NODE_NAME="ABC" You create a Configuration Option File with a data value defined for each option just as you would answer questions in the ^CONFIG Utility. DSM assumes default data values for options that you do not define in the option file. Using the Configuration Option File Utility (^OPTMAN) B-1 The recommended procedure for creating and using a Configuration Option File is: 1. Invoke the ^OPTMAN Configuration Option File utility. Choose the ^OPTBLD utility to generate a template file built from an existing configuration. 2. Edit the template file to create a customized Configuration Option File that defines a configuration. You can use any OpenVMS editor to modify the contents of the option file. 3. Choose the ^OPTMAN option ^OPTCON to import the new Configuration Option File into the configuration database. DSM then uses the data imported from the file to start up a DSM configuration. The ^OPTMAN Configuration Option File utility does not cover global translation tables. To create OpenVMS files of global translation tables that you can edit at the DCL level, use the Translation Table File Utilities, an option on the Translation Table Management menu under ^SYS. The Translation Table File utilities, and the OpenVMS editor of your choice, allow you to o Modify a translation table at the OpenVMS level o import the table data into the configuration database The following sections describe the following topics: o How to invoke ^OPTMAN o How to create a configuration option file o How to use the option file to start a configuration The definition keywords and data keywords are described in Table B-1 and Table B-2. A DSM configuration option file example is shown in Example B-2. B-2 Using the Configuration Option File Utility (^OPTMAN) Invoking the Configuration Option File Utilities (^OPTMAN) Use the ^OPTMAN Utility to create a configuration option file and apply that file to ^CONFIG. You can use the Display Configuration Utility (DISPLAY^CONFIG) to display the characteristics of a defined configuration. Enter the following to run the ^OPTMAN Utility: >D ^OPTMAN The utility displays the following menu: Option File Management Utilities 1. CONVERT OPTION FILE (^OPTCON) 2. CREATE OPTION FILE (^OPTBLD) Select Option > The following sections describe these utilities. Creating a Template Option File (^OPTBLD) Use the Create Option File Utility (^OPTBLD) to create a template configuration option file from an existing configuration defined by the ^CONFIG Utility. Besides accessing ^OPTBLD from the ^OPTMAN menu, you can access ^OPTBLD through the System Utilities menu (^SYS), or invoke it directly by entering the following: >D ^OPTBLD Create Configuration Option File Enter the configuration identifier Enter the name of the configuration for which you want to create an option file. The name you enter must be a currently defined configuration. Press Return to accept the default or enter a circumflex (^) to exit. Enter ^L to display a list of the defined configurations. File name of option file Enter the OpenVMS file specification of the configuration option file to be created. You can specify a logical name that translates to a complete file specification. Creating option file DISK$USER:[DSM]DSM$CONFIG_PAYROLL.OPT;1 ... Using the Configuration Option File Utility (^OPTMAN) B-3 Option file DISK$USER:[DSM]DSM$CONFIG_PAYROLL.OPT;1 has been successfully created The following is an example of a configuration file created through ^OPTBLD: ! ! DSM configuration option file ! ! Name of file: DISK$USER:[DSM]DSM$CONFIG_PAYROLL.OPT;1 ! Configuration ID: PAYROLL ! Date of creation: 5-SEP-1997 11:21:36.00 ! ENABLE_ACCESS_CONTROL="Y" DEFINE AIJ_DEFAULT BUFFER_SIZE="8" LOG_FILE_DIRECTORY="DISK$USER:[DSM.JOURNAL]" OPERATOR_CONSOLE="CENTRL" DISK_BUFFERS="64" MAX_GLOBAL_NUMBER="90" MOUNTABLE_VOLUME_SET="1" DEFINE DATABASE_SET CLUSTER_WIDE_ACCESS="N" VOLUME_SET_MASTER="Y" DATABASE_SET_NAME="DSM" READ_ONLY="N" DATABASE_SET_TYPE="VMS DSM" DEFINE VOLUME_SET ALTERNATE_NAME="DSM" VOLUME_SET_NAME="DSM" DEFINE VOLUME FILE_NAME="DISK$USER:[DSM.DSMUTL]DSMVOL1.GLS" DEFINE GLOBAL_DEFAULT GLOBAL_JOURNAL="N" DEFINE PROTECTION %_GLOBAL_SYSTEM="RWD" %_GLOBAL_WORLD="R" %_GLOBAL_GROUP="R" %_GLOBAL_UCI="RWD" GLOBAL_SYSTEM="RWD" GLOBAL_WORLD="NONE" GLOBAL_GROUP="NONE" GLOBAL_UCI="RWD" B-4 Using the Configuration Option File Utility (^OPTMAN) NON_PAGED_MEMORY="N" RESTRICTION_MASK1="31" RESTRICTION_MASK2="0" USERS="128" Editing the Template Configuration Option File At this point, you edit the configuration data in the template configuration option file to create a customized option file that specifies the the new configuration you plan to use. Using any OpenVMS editor, you enter definition keywords and data keywords into the template file to specify new configuration options you want for the configuration. The definition keywords and data keywords are described in Table B-1 and Table B-2. Converting the Edited Configuration Option File (^OPTCON) Use the Convert Option File Utility (^OPTCON) to convert the configuration option file created by ^OPTBLD for use by the configuration database that is used to start up a DSM configuration. Besides accessing ^OPTCON from the ^OPTMAN menu, you can access ^OPTCON through the System Utilities menu (^SYS). You can also invoke it directly by entering the following: >D ^OPTCON Convert Configuration Option File Enter the configuration identifier Enter the name of the configuration identifier for which you want to convert an option file or press Return to accept the default. Enter a circumflex (^) to exit from the routine. Enter ^L to display a list of defined configurations. File name of option file Enter a valid OpenVMS file specification for the configuration option file. The option file is used to build a configuration database for starting up a DSM configuration. You can specify a logical name that translates to a complete specification. Building DSM startup options ... Using the Configuration Option File Utility (^OPTMAN) B-5 Option file DISK$USER:[DSM]DSM$CONFIG_PAYROLL.OPT;1 processing complete ^[DISK$USER:[DSM]]SYS("PAYROLL") created In the previous example, the ^OPTCON Utility creates a configuration database and assigns PAYROLL as the configuration ID. Each time you convert a new option file, DSM automatically updates the configuration information in the database. Starting Up a Configuration You can start a DSM configuration from the configuration option file by doing one of the following: o Use the ^OPTCON Utility to build a configuration database and start up the configuration using the ^STU Utility. For example: >D ^STU DSM Configuration Startup Enter the configuration identifier In the previous example, PAYROLL is the configuration ID created by the ^OPTCON Utility. o Use the OPT^STU Utility to start up the configuration. You must run the utility from the DCL command line using the DSM command. The OPT^STU entry point accepts two arguments (separated by a comma) for input data. The following is the format of the command line: $ DSM/MANAGER/DATA=arg1,arg2 OPT^STU where: arg1 is the name of a configuration option file arg2 is ENABLE to enable user logins on startup, and DISABLE to disable user logins on startup For example, enter the following: $ DSM/MANAGER/DATA="DSM$:[DSM]DSM$CONFIG_PAYROLL.OPT,ENABLE" OPT^STU When you enter an existing option file specification, the OPT^STU Utility automatically converts the file to the configuration database and starts up the DSM configuration. B-6 Using the Configuration Option File Utility (^OPTMAN) Configuration Option File Keywords The configuration option file contains two types of keywords: o Definition keywords o Data keywords Definition keywords separate the data keywords into different functional groups. Data keywords define the data value for a startup option. The ^OPTCON Utility aborts any attempt to convert an option file into the configuration database if one or more incorrect entries are present in the file. Note the following when you create an option file for a configuration: o Use definition keywords to define a group of data keywords that are placed under the same category and perform one startup function for a configuration, such as mapped routines or Distributed Data Processing (DDP). o Use data keywords to assign data values to a configura- tion startup option such as the number of disk buffers or the file name of a DSM volume. o Data keywords may or may not require a definition keyword. Use Table B-1 to look up the definition keywords and use Table B-2 to place the data keywords under the appropriate definition keyword. o Use data keywords and definition keywords to define startup options for a configuration. Default values are automatically assigned to those options that are not defined in the configuration option file. o The ^CONFIG Utility validates all data values assigned to the data keywords. o Enter an equals sign (=) and a data value after each data keyword. Leading and trailing space characters are ignored. o Enclose the data value with a pair of identical ASCII punctuation characters, for example, /300/ or "300". Using the Configuration Option File Utility (^OPTMAN) B-7 o Begin comment lines with a slash character (/) or an exclamation mark (!). You can place comment lines in the configuration option file for documentation purposes. o Do not use blank lines in the configuration option file. Definition Keywords Table B-1 describes the definition keywords. Table_B-1_Definition_Keywords___________________________________ Keyword_and_Description________Example__________________________ DEFINE_DATABASE_SET_____________________________________________ Specifies the configuration DEFINE DATABASE_SET startup options for a DSM VOLUME_SET_MASTER="Y" database set. CLUSTER_WIDE_ACCESS="N" DATABASE_SET_NAME="PAYROLL" DATABASE_SET_TYPE="DSM" ________________________________________________________________ DEFINE_VOLUME_SET_______________________________________________ Specifies the configuration startup options for a volume DEFINE VOLUME_SET set. This keyword must VOLUME_SET_NAME="EMP" appear under the DEFINE ALTERNATE_NAME="REC" DATABASE_SET definition keyword. (continued on next page) B-8 Using the Configuration Option File Utility (^OPTMAN) Table_B-1_(Cont.)_Definition_Keywords___________________________ ________________________________________________________________ DEFINE_VOLUME___________________________________________________ Specifies the configuration startup options for a DSM DEFINE VOLUME volume. There must be a FILE_NAME="DISK$USER:[DSM]EMPVOL1.GLS" DEFINE VOLUME section for each volume set that was DEFINE VOLUME created. This keyword must FILE_NAME="DISK$USER:[DSM]EMPVOL2.GLS" appear under the DEFINE VOLUME_SET definition keyword. ________________________________________________________________ DEFINE_AIJ______________________________________________________ Specifies the startup options for the After- DEFINE AIJ Image Journaling file. This FILE_NAME="DISK$USER:[DSM]EMPJRN1.DAT" keyword must appear under the DEFINE DATABASE_SET MESSAGE="THIS IS FOR AIJ" definition keyword. REPLY="N" DEFINE AIJ FILE_NAME="DISK$USER:[DSM]EMPJRN2.DAT" MESSAGE="MORE AFTER-IMAGE JOURNALING" REPLY="N" ________________________________________________________________ DEFINE_BIJ______________________________________________________ Specifies the startup options for the Before- DEFINE BIJ Image Journaling file. FILE_NAME="DISK$USER:[DSM]DSMEMP.BIJ" This keyword must appear under the DEFINE VOLUME_SET definition keyword. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-9 Table_B-1_(Cont.)_Definition_Keywords___________________________ Keyword_and_Description________Example__________________________ DEFINE_DDP______________________________________________________ Specifies the configuration DEFINE DDP startup options for NODE_NAME="ABC" Distributed Data Processing STARTUP="Y" (DDP). SERVERS="3" OPCOM="Y" GROUPS="0" RETRY="4" RETRY_INTERNAL="3" SECURITY="N" REQUEST_CREDIT="20" ADVERTISING_INTERVAL="6" ________________________________________________________________ DEFINE_DDP_LINK_________________________________________________ Specifies the configuration startup options for the DEFINE DDP_LINK DDP link type and device LINK_TYPE="ETHERNET" type. This keyword must appear under the DEFINE DDP LINK_DEVICE="XEA:" definition keyword. ________________________________________________________________ DEFINE_HISTOGRAM________________________________________________ Specifies the configuration DEFINE HISTOGRAM startup options for routine BUFFER_SIZE="50" and global performance histograms. (continued on next page) B-10 Using the Configuration Option File Utility (^OPTMAN) Table_B-1_(Cont.)_Definition_Keywords___________________________ ________________________________________________________________ DEFINE_MAPPED_ROUTINES__________________________________________ Specifies the configuration DEFINE MAPPED_ROUTINES startup options for a mapped UCI_NAME="MGR" routine set. VOLUME_SET_NAME="EMP" DIRECTORY_NAME="DISK$USER:[DSM]" SECTION_TYPE="P" PAGE_CLUSTER_SIZE="8" ________________________________________________________________ DEFINE_GLOBAL_DEFAULT___________________________________________ Specifies the configuration DEFINE GLOBAL_DEFAULT startup options for default GLOBAL_JOURNAL="Y" DSM global characteristics. ________________________________________________________________ DEFINE_PROTECTION_______________________________________________ Specifies the configuration startup options for global DEFINE PROTECTION protection defaults. It %_GLOBAL_ must appear under the DEFINE SYSTEM="RWP" GLOBAL_DEFAULT definition %_GLOBAL_WORLD="R" keyword. %_GLOBAL_GROUP="R" %_GLOBAL_UCI="RWP" GLOBAL_SYSTEM="RWP" GLOBAL_WORLD="NONE" GLOBAL_GROUP="NONE" GLOBAL_UCI="RWP" ________________________________________________________________ DEFINE_AIJ_DEFAULT______________________________________________ Specifies the configuration DEFINE AIJ_DEFAULT startup options for default BUFFER_SIZE="8" After-Image Journaling OPERATOR_CONSOLE="CENTRL" characteristics. LOG_FILE_DIRECTORY="DISK$USER:[DSM]" (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-11 Table_B-1_(Cont.)_Definition_Keywords___________________________ Keyword_and_Description________Example__________________________ DEFINE_TRANSACTION_PROCESSING___________________________________ Specifies the configuration DEFINE TRANSACTION_PROCESSING startup options for MAXIMUM_TRANSACTIONS="12" transaction processing (TP). TP_SINGLE_REFERENCE="Y" REDO_BUFFERS="64" ________________________________________________________________ DEFINE_TP_MONITOR_______________________________________________ Specifies the configuration startup options for the DEFINE TP_MONITOR transaction processing mon- CHECKPOINT_ itor. It must appear under TIMER="180" the DEFINE TRANSACTION_ CLUSTER_TRANSACTIONS="20" PROCESSING definition keyword. INTERLOCK_TABLE_ SIZE="96" (continued on next page) B-12 Using the Configuration Option File Utility (^OPTMAN) Table_B-1_(Cont.)_Definition_Keywords___________________________ ________________________________________________________________ DEFINE_LOGIN_DEFAULT____________________________________________ Specifies the qualifiers you DEFINE LOGIN_DEFAULT want to append to the DSM UCI_NAME="DEF" command line whenever the VOLUME_SET_NAME="EMP" DSM image is run. ROUTINES="[DEF,EMP]" SOURCE_BUFFER_SIZE="2048" SYMBOL_TABLE_SIZE="1024" TERMINAL_BUFFER_ SIZE="1024" STACK_SIZE="4096" MAPPED="Y" TYPEAHEAD="N" PACK="N" PASSALL="N" BYPASS="N" CENABLE="N" DPRECISION="Y" NOUNDEFINED="Y" SETFUNCTION="N" ________________________________________________________________ DEFINE_$H_OFFSET________________________________________________ Specifies offsets for DEFINE $H_OFFSET $HOROLOG in a DSM config- DAY_OFFSET="0" uration. These offsets are TIME_OFFSET="3600" added to the actual $HOROLOG when you use the $HOROLOG special variable. ________________________________________________________________ DEFINE_SEND_CONSOLE_MESSAGE_____________________________________ Specifies sending a console DEFINE SEND_CONSOLE_MESSAGE message when a database set DISK_FULL_PERCENTAGE="90" is nearly full. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-13 Table_B-1_(Cont.)_Definition_Keywords___________________________ Keyword_and_Description________Example__________________________ DEFINE_TRANSLATION______________________________________________ Specifies an entry in the DEFINE TRANSLATION Translation Table for a TABLE_NAME="NEW" configuration. ________________________________________________________________ DEFINE_VOLUME_SET_ALIAS_________________________________________ Specifies an alias for DEFINE VOLUME_SET_ALIAS a volume set name in the OLD_VOLUME_SET_NAME="OLD" global transaction table.. NEW_VOLUME_SET_NAME="NEW" When the table is loaded, any reference to the volume set name you specify will be replaced by the corresponding alias. ________________________________________________________________ DEFINE_VISUALM_SERVER___________________________________________ Specifies server support DEFINE VISUALM_SERVER for InterSystems' Visual M TCP_PORT_NUMBER="7006" product. This permits per- TCP_PORT_RANGE="512" sonal computer applications written in Visual Basic to access DSM globals and routines._______________________________________________________ Data Keywords Table B-2 describes the data keywords. B-14 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_Data_Keywords_________________________________________ Required Definition Keyword_and_Description_Example__________________Keyword________ DISK_BUFFERS____________________________________________________ The number of disk DISK_BUFFERS="300" None buffers used to cache database disk data in memory. ________________________________________________________________ NON_PAGED_MEMORY________________________________________________ Use nonpaged memory NON_PAGED_MEMORY="N" None to contain the disk buffers that are used for shared global access. ________________________________________________________________ USERS___________________________________________________________ The maximum number of USERS="128" None DSM users you want to allow simultaneous access to this configuration. ________________________________________________________________ DATABASE_SET_NAME_______________________________________________ Name of a database DATABASE_SET_ DEFINE set to mount during NAME="PAYROLL" DATABASE_SET configuration startup. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-15 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ DATABASE_SET_TYPE_______________________________________________ Specifies the DATABASE_SET_ DEFINE database set as one TYPE="DSM" DATABASE_SET of three types of database sets: DSM, DSM-11 compatible, or Transaction Processing. ________________________________________________________________ VOLUME_SET_NAME_________________________________________________ The name of the VOLUME_SET_NAME="EMP" DEFINE VOLUME_ volume set to be used SET for a configuration DEFINE MAPPED_ startup option. ROUTINES DSM volume set DEFINE LOGIN_ names must be 3 DEFAULT uppercase alphabetic characters. ________________________________________________________________ CLUSTER_WIDE_ACCESS_____________________________________________ The volume set CLUSTER_WIDE_ DEFINE is to be mounted ACCESS="N" DATABASE_SET by two or more concurrently running configurations within a VMScluster system. (continued on next page) B-16 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ READ_ONLY_______________________________________________________ Specifies if the READ_ONLY="N" DEFINE volume set is a read- DATABASE_SET only volume set. ________________________________________________________________ VOLUME_SET_MASTER_______________________________________________ The configuration VOLUME_SET_MASTER="Y" DEFINE is selected as the DATABASE_SET cluster-wide volume set master for this volume set if you are using After- Image Journaling on a cluster-mounted volume set. ________________________________________________________________ FILE_NAME_______________________________________________________ The OpenVMS file FILE_NAME= DEFINE VOLUME specification "DISK$USER:[DSM]EMPVOL1.GDEFINE AIJ of a DSM volume DEFINE BIJ or RMS file. The file name can be a OpenVMS logical name that translates to a complete specification. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-17 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ MESSAGE_________________________________________________________ The text of a message MESSAGE="THIS IS A DEFINE AIJ you want to transmit TEST" to an operator when the journal file is filled and journaling to the next file is ready to begin. ________________________________________________________________ REPLY___________________________________________________________ Demand an operator REPLY="Y" DEFINE AIJ reply to the Journal Process before allowing the Journal Process to go on to the next journal file. ________________________________________________________________ NODE_NAME_______________________________________________________ Specifies a unique NODE_NAME="ABC" DEFINE DDP 3-character node name for this DDP node. Each configuration within a DDP network must have a unique node name. (continued on next page) B-18 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ STARTUP_________________________________________________________ Start DDP servers STARTUP="Y" DEFINE DDP during DSM configura- tion startup. ________________________________________________________________ SERVERS_________________________________________________________ Specifies the number SERVERS="3" DEFINE DDP of DDP servers that are responsible for servicing DDP requests for remote users. ________________________________________________________________ OPCOM___________________________________________________________ Send DDP circuit OPCOM="Y" DEFINE DDP and status messages to the operator's console. ________________________________________________________________ GROUPS__________________________________________________________ Specifies the DDP GROUPS="0" DEFINE DDP groups to enable for this node. DDP connections are established only between nodes that belong to the same group. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-19 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition Keyword_and_Description_Example__________________Keyword________ RETRY___________________________________________________________ The DDP request retry RETRY="4" DEFINE DDP maximum mechanism is used to recover from instances where a DDP request is not answered by the remote node. The request is sent every 30 seconds until the request is answered or the request retry maximum is exceeded. ________________________________________________________________ RETRY_INTERVAL__________________________________________________ The DDP request retry RETRY_INTERVAL="3" DEFINE DDP interval is the time that DDP waits for a response to a DDP request. When the request retry interval expires, DDP keeps sending the DDP request unless the request retry maximum has been exceeded. (continued on next page) B-20 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ SECURITY________________________________________________________ The DDP circuit SECURITY="N" DEFINE DDP connection security facility allows the user to control which remote nodes on the network are permitted to connect to this node. Control is enforced through the use of DDP node passwords. ________________________________________________________________ REQUEST_CREDIT__________________________________________________ The DDP request REQUEST_CREDIT="20" DEFINE DDP credit maximum is used for buffer flow control of DDP receive buffers. ________________________________________________________________ ADVERTISING_INTERVAL____________________________________________ The multi-cast ADVERTISING_INTERVAL="6" DEFINE DDP advertising interval is used by the DDP servers to send control messages periodically to all remote DDP nodes to communicate status information. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-21 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition Keyword_and_Description_Example__________________Keyword________ LINK_TYPE_______________________________________________________ Configure an Ethernet LINK_TYPE="ETHERNET" DEFINE DDP_LINK type link or a DECnet type link for DDP. ________________________________________________________________ LINK_DEVICE_____________________________________________________ The OpenVMS device LINK_DEVICE="XEA:" DEFINE DDP_LINK name of the Ethernet controller that is used for DDP communications. ________________________________________________________________ DECNET_CHANNEL__________________________________________________ The DECnet channel DECNET_CHANNEL= DEFINE DDP specification for "DSM::"TASK=DSM$DDPEMP"" DECnet type DDP links. ________________________________________________________________ BUFFER_SIZE_____________________________________________________ The journal buffer BUFFER_SIZE="8" DEFINE AIJ_ size in 1KB DSM DEFAULT blocks or the size in DEFINE pages of the RTHIST HISTOGRAM buffer to reserve. (continued on next page) B-22 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ UCI_NAME________________________________________________________ Specifies the 3- UCI_NAME="MGR" DEFINE MAPPED_ character UCI name ROUTINES for a volume set. DEFINE LOGIN_ DEFAULT ________________________________________________________________ DIRECTORY_NAME__________________________________________________ Specifies the OpenVMS DIRECTORY_NAME="DISK$USER:[DSM]" global directory name DEFINE MAPPED_ for a mapped routine ROUTINES set. ________________________________________________________________ SECTION_TYPE____________________________________________________ Use nonpaged memory SECTION_TYPE="P" DEFINE MAPPED_ for a mapped routine ROUTINES section. ________________________________________________________________ PAGE_CLUSTER_SIZE_______________________________________________ The page cluster PAGE_CLUSTER_SIZE="8" DEFINE MAPPED_ size is the number ROUTINES of 512-byte memory pages that are paged in when access to a routine within the routine section causes a page fault. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-23 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ ENABLE_ACCESS_CONTROL___________________________________________ Enable configuration ENABLE_ACCESS_ None access control to CONTROL="Y" provide a complete security system for a running configuration. If you enable access control, you can use the ^ACL Utility to specify which OpenVMS users are permitted to log in to DSM for each of the access modes (Manager, Programmer, or Application). ________________________________________________________________ GLOBAL_JOURNAL__________________________________________________ Select globals to be GLOBAL_JOURNAL="Y" DEFINE GLOBAL_ journaled by default. DEFAULT ________________________________________________________________ %_GLOBAL_SYSTEM_________________________________________________ Select % global %_GLOBAL_SYSTEM="RWP" DEFINE protection system PROTECTION default. (continued on next page) B-24 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ %_GLOBAL_WORLD__________________________________________________ Select % global %_GLOBAL_WORLD="R" DEFINE protection world PROTECTION default. ________________________________________________________________ %_GLOBAL_GROUP__________________________________________________ Select % global %_GLOBAL_GROUP="R" DEFINE protection group PROTECTION default. ________________________________________________________________ %_GLOBAL_UCI____________________________________________________ Select % global %_GLOBAL_UCI="RWP" DEFINE protection UCI PROTECTION default. ________________________________________________________________ GLOBAL_SYSTEM___________________________________________________ Select non-% global GLOBAL_SYSTEM="RWP" DEFINE protection system PROTECTION default. ________________________________________________________________ GLOBAL_WORLD____________________________________________________ Select non-% global GLOBAL_WORLD="NONE" DEFINE protection world PROTECTION default. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-25 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ GLOBAL_GROUP____________________________________________________ Select non-% global GLOBAL_GROUP="NONE" DEFINE protection group PROTECTION default. ________________________________________________________________ GLOBAL_UCI______________________________________________________ Select non-% global GLOBAL_UCI="RWP" DEFINE protection UCI PROTECTION default. ________________________________________________________________ OPERATOR_CONSOLE________________________________________________ Specifies the name of OPERATOR_CONSOLE="CENTRL"DEFINE AIJ_ the operator console DEFAULT to receive journal process messages sent when a journal file is full and an operator reply is needed. ________________________________________________________________ LOG_FILE_DIRECTORY______________________________________________ Specifies the name LOG_FILE_DIRECTORY= DEFINE AIJ_ of the OpenVMS device "DISK$USER:[DSM.JOURNAL]"DEFAULT and directory that holds the journal log files. (continued on next page) B-26 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ TP_SINGLE_REFERENCE_____________________________________________ Specifies how non- TP_SINGLE_REFERENCE="Y" DEFINE transacted references TRANSACTION_ to the transaction PROCESSING database set should be handled. Enter Y if non-transacted references should return an error. ________________________________________________________________ MAXIMUM_TRANSACTIONS____________________________________________ The maximum number MAXIMUM_TRANSACTIONS="12"DEFINE of concurrent TRANSACTION_ transactions you PROCESSING want to allow for the node where this configuration will be started. A total of 128 transactions can be open at one time. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-27 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ REDO_BUFFERS____________________________________________________ The number of 1KB REDO_BUFFERS="64" DEFINE REDO BUFFERS to TRANSACTION_ be allocated on PROCESSING this node for use by the transaction processor. An insufficient number of REDO BUFFERS results in excessive writing to the before-image journal (BIJ) file and causes excessive checkpoint operations. ________________________________________________________________ CHECKPOINT_TIMER________________________________________________ The number of seconds CHECKPOINT_TIMER="180" DEFINE TP_ between transaction MONITOR processing system checkpoint events. It defines the maximum amount of data that needs to be recovered in a failure event such as a transaction abort or node failure. (continued on next page) B-28 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ CLUSTER_TRANSACTIONS____________________________________________ The maximum number CLUSTER_TRANSACTIONS="20"DEFINE TP_ of concurrent MONITOR transactions that can be supported by the transaction processing monitor. It defines the number of concurrent transactions allowed in the cluster at any one time. ________________________________________________________________ INTERLOCK_TABLE_SIZE____________________________________________ The number of entries INTERLOCK_TABLE_ DEFINE TP_ in the transaction SIZE="96" MONITOR processing monitor's interlock table. This table is used to keep track of the interdependencies between concurrent transactions. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-29 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ ROUTINES________________________________________________________ The /ROUTINES=[UCI,VOL] ROUTINES="[DEF,EMP]" DEFINE LOGIN_ command line DEFAULT qualifier selects a non-default routine directory. This qualifier allows you to separate the UCI and volume set that your globals are located in from the UCI and volume set that your routines are located in. ________________________________________________________________ SOURCE_BUFFER_SIZE______________________________________________ The /SOURCE_BUFFER_ SOURCE_BUFFER_ DEFINE LOGIN_ SIZE=n command line SIZE="2048" DEFAULT qualifier establishes the size, in bytes, of the DSM source routine buffer and precompiled routine buffer. (continued on next page) B-30 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ SYMBOL_TABLE_SIZE_______________________________________________ The /SYMBOL_TABLE_ SYMBOL_TABLE_ DEFINE LOGIN_ SIZE=n command line SIZE="1024" DEFAULT qualifier changes the size of your local DSM symbol table to the value specified. ________________________________________________________________ TERMINAL_BUFFER_SIZE____________________________________________ The /TERMINAL_BUFFER_ TERMINAL_BUFFER_ DEFINE LOGIN_ SIZE=n command line SIZE="1024" DEFAULT qualifier changes the size of your terminal's output buffer to the value specified. The size of this buffer determines the maximum size of a single physical write operation to the terminal. ________________________________________________________________ STACK_SIZE______________________________________________________ The /STACK_SIZE=n STACK_SIZE="4096" DEFINE LOGIN_ command line DEFAULT qualifier changes the size of the DSM call stack to the size specified. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-31 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition Keyword_and_Description_Example__________________Keyword________ MAPPED__________________________________________________________ The /MAPPED command MAPPED="Y" DEFINE LOGIN_ line qualifier DEFAULT establishes access to a set of DSM routines that are mapped in a global virtual memory section. ________________________________________________________________ TYPEAHEAD_______________________________________________________ The /TYPEAHEAD TYPEAHEAD="N" DEFINE LOGIN_ command line DEFAULT qualifier overrides the DSM default by which the READ literal command (READ "Value: ",X) causes the type-ahead buffer to be purged. /TYPEAHEAD always allows type-ahead regardless of the form of the READ command. (continued on next page) B-32 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ PACK____________________________________________________________ The /[NO]PACK command PACK="N" DEFINE LOGIN_ line qualifier DEFAULT applies only to terminal output. When /PACK is used, DSM does not perform a $QIO write for each WRITE command that is executed. Instead, DSM packs output strings into the terminal output buffer until the buffer is full, or until DSM executes a command that requires flushing the output buffer. ________________________________________________________________ PASSALL_________________________________________________________ The /PASSALL command PASSALL="N" DEFINE LOGIN_ line qualifier DEFAULT causes DSM to use unformatted output (IO$M_NOFORMAT) when writing to a terminal. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-33 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ BYPASS__________________________________________________________ The /BYPASS command BYPASS="N" DEFINE LOGIN_ line qualifier DEFAULT disables protection verification on volume set globals. /NOBYPASS enables protection verification, in which case you must run ^%GLOMAN to modify protection on a global-by-global basis. ________________________________________________________________ CENABLE_________________________________________________________ The /CENABLE command CENABLE="N" DEFINE LOGIN_ line qualifier DEFAULT enables Ctrl/C recognition. /NOCENABLE disables Ctrl/C recognition. ________________________________________________________________ DPRECISION______________________________________________________ The /EXTENSION=DPRECISIODPRECISION="N" DEFINE LOGIN_ command line DEFAULT qualifier enables extended (double) precision math. (continued on next page) B-34 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition Keyword_and_Description_Example__________________Keyword________ NOUNDEFINED_____________________________________________________ The /EXTENSION=NOUNDEFINNOUNDEFINED="N" DEFINE LOGIN_ command line DEFAULT qualifier forces DSM to return a null string on any attempt to retrieve the value of an undefined variable. ________________________________________________________________ SETFUNCTION_____________________________________________________ The /EXTENSION=SETFUNCTISETFUNCTION="N" DEFINE LOGIN_ command line DEFAULT qualifier enables the following non- ANSI standard forms of the SET command: SET $EXTRACT(string,start,end)=expression SET $FIND(string,substring,position)=expression (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-35 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ TCP_PORT_NUMBER_________________________________________________ Specifies a port TCP_PORT_NUMBER="6001" DEFINE VISUALM_ number ranging from SERVER 1024 to 65535. This port number will be used to initiate connection between the personal computer and the Visual M server running under DSM. ________________________________________________________________ TCP_PORT_RANGE__________________________________________________ Specifies the number TCP_PORT_RANGE="512" DEFINE VISUALM_ of TCP/IP port SERVER numbers to reserve for use by Visual M application servers. You should reserve sufficient ports to handle the number of concurrent users expected to be running Visual M applications served by this configuration. (continued on next page) B-36 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ DAY_OFFSET______________________________________________________ Specifies the DAY_OFFSET="2" DEFINE $H_ day offset as an OFFSET integer (positive or negative). Contains the number of days that you want to use as the $HOROLOG offset. ________________________________________________________________ TIME_OFFSET_____________________________________________________ Specifies the TIME_OFFSET="1800" DEFINE $H_ time offset as an OFFSET integer (positive or negative). Contains the number of seconds that you want to use as the $HOROLOG offset. ________________________________________________________________ DISK_FULL_PRECENTAGE____________________________________________ Sends a message to DISK_FULL_PERCENTAGE="90"DEFINE SEND_ the operator console CONSOLE_MESSAGE when one of the mounted volume sets becomes full at a specified percentage. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-37 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ RESTRICTION_MASK1_______________________________________________ Sets restriction bit RESTRICTION_MASK1="31" None mask for security to enabled. ________________________________________________________________ RESTRICTION_MASK2_______________________________________________ Sets restriction bit RESTRICTION_MASK1="0" None mask for security to disabled. ________________________________________________________________ MOUNTABLE_VOLUME_SET____________________________________________ Specifies the number MOUNTABLE_VOLUME_ None of volume sets you SET="1" expect to mount while the configuration is running. The volume set count is required because the DSM startup procedure must pre- allocate space in the shared memory for each volume set that may be mounted after configuration startup. (continued on next page) B-38 Using the Configuration Option File Utility (^OPTMAN) Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ MAX_GLOBAL_NUMBER_______________________________________________ Specifies the maximum MAX_GLOBAL_NUMBER="90" None number of globals allowed on any of the volume set that you intend to mount after configuration startup. This value will be used to pre- allocate space in the shared memory for fast global directory lookup. offset. ________________________________________________________________ TABLE_NAME______________________________________________________ Specifies the name TABLE_NAME="NEW" DEFINE for a translation TRANSLATION table. The name may consists of up to 12 uppercase, alphanumeric characters. ________________________________________________________________ OLD_VOLUME_SET_NAME_____________________________________________ Specifies name of OLD_VOLUME_SET_ DEFINE_VOLUME_ the volume set to NAME="NEW" SET_ALIAS be replaced in the translation table. (continued on next page) Using the Configuration Option File Utility (^OPTMAN) B-39 Table_B-2_(Cont.)_Data_Keywords_________________________________ Required Definition ________________________________________________________________ NEW_VOLUME_SET_NAME_____________________________________________ Specifies the volume NEW_VOLUME_SET_ DEFINE_VOLUME_ set name (alias) that NAME="NEW" SET_ALIAS is to replace the old volume set name in the translation table.__________________________________________________________ Minimum Entries in a Configuration Option File Example B-1 shows the minimum entries that need to be in the configuration option file. Example B-1 Minimum Entries in Configuration Option File ! DSM configuration option file ! ! Name of file: DISK$USER:[DSMMGR]DSM$CONFIG_PAYROLL.OPT;1 ! Configuration ID: PAYROLL ! Date of creation: 26-APR-1997 15:15:43.75 ! DISK_BUFFERS="300" DEFINE DATABASE_SET DATABASE_SET_NAME="PAYROLL" DEFINE VOLUME_SET VOLUME_SET_NAME="EMP" DEFINE VOLUME FILE_NAME="DISK$USER:[DSMMGR.DATABASE]EMPVOL1.GLS" Sample Configuration Option File Example B-2 shows a sample of what your Configuration Option File can look like. B-40 Using the Configuration Option File Utility (^OPTMAN) Example B-2 Sample Configuration Option File ! DSM configuration option file ! ! Name of file: DISK$USER:[DSMMGR]DSM$CONFIG_PAYROLL.OPT;1 ! Configuration ID: PAYROLL ! Date of creation: 27-APR-1997 10:32:03.52 ! ENABLE_ACCESS_CONTROL="Y" DEFINE AIJ_DEFAULT BUFFER_SIZE="8" LOG_FILE_DIRECTORY="DISK$USER:[DSMMGR.JOURNAL]" OPERATOR_CONSOLE="CENTRL" DISK_BUFFERS="300" MAX_GLOBAL_NUMBER="90" MOUNTABLE_VOLUME_SET="1" DEFINE DATABASE_SET DATABASE_SET_NAME="PAYROLL1" DATABASE_SET_TYPE="TP SET" CLUSTER_WIDE_ACCESS="Y" VOLUME_SET_MASTER="Y" DEFINE AIJ FILE_NAME="DISK$USER:[DSMMGR.JOURNAL]EMPJRN1.DAT" DEFINE AIJ FILE_NAME="DISK$USER:[DSMMGR.JOURNAL]EMPJRN2.DAT" MESSAGE="THIS IS A TEST" REPLY="Y" DEFINE VOLUME_SET VOLUME_SET_NAME="EMP" DEFINE BIJ FILE_NAME="DISK$USER:[DSMMGR.JOURNAL]DSMEMP.BIJ" DEFINE VOLUME FILE_NAME="DISK$USER:[DSMMGR.DATABASE]EMPVOL1.GLS" DEFINE VOLUME FILE_NAME="DISK$USER:[DSMMGR.DATABASE]EMPVOL2.GLS" DEFINE SEND_CONSOLE_MESSAGE DISK_FULL_PERCENTAGE="90" DEFINE $H_OFFSET DAY_OFFSET="0" TIME_OFFSET="3600" DEFINE DATABASE_SET DATABASE_SET_NAME="PAYROLL2" DATABASE_SET_TYPE="DSM" Using the Configuration Option File(Utilitye(^OPTMAN) pB-41 Example B-2 (Cont.) Sample Configuration Option File CLUSTER_WIDE_ACCESS="N" VOLUME_SET_MASTER="Y" DEFINE VOLUME_SET VOLUME_SET_NAME="TST" DEFINE VOLUME FILE_NAME="DISK$USER:[DSMMGR.DATABASE]TSTVOL1.GLS" DEFINE DDP ADVERTISING_INTERVAL="6" GROUPS="0" DEFINE DDP_LINK LINK_DEVICE="XEA:" LINK_TYPE="ETHERNET" REQUEST_CREDIT="20" RETRY="4" NODE_NAME="ABC" OPCOM="Y" RETRY_INTERVAL="3" SECURITY="N" SERVERS="3" STARTUP="Y" DEFINE LOGIN_DEFAULT CENABLE="Y" MAPPED="N" PACK="Y" PASSALL="Y" SOURCE_BUFFER_SIZE="20480" STACK_SIZE="4096" SYMBOL_TABLE_SIZE="204160" TERMINAL_BUFFER_SIZE="1024" TYPEAHEAD="Y" (continued on next page) B-42 Using the Configuration Option File Utility (^OPTMAN) Example B-2 (Cont.) Sample Configuration Option File DEFINE GLOBAL_DEFAULT GLOBAL_JOURNAL="N" DEFINE PROTECTION %_GLOBAL_SYSTEM="RWP" %_GLOBAL_WORLD="R" %_GLOBAL_GROUP="R" %_GLOBAL_UCI="RWP" GLOBAL_SYSTEM="RWP" GLOBAL_WORLD="NONE" GLOBAL_GROUP="NONE" GLOBAL_UCI="RWP" DEFINE MAPPED_ROUTINES PAGE_CLUSTER_SIZE="8" DIRECTORY_NAME="DISK$USER:[DSMMGR]" SECTION_TYPE="S" UCI_NAME="MGR" VOLUME_SET_NAME="EMP" NON_PAGED_MEMORY="N" DEFINE HISTOGRAM BUFFER_SIZE="50" DEFINE TRANSACTION_PROCESSING MAXIMUM_TRANSACTIONS="12" TP_SINGLE_REFERENCE="Y" REDO_BUFFERS="36" DEFINE TP_MONITOR CHECKPOINT_TIMER="180" CLUSTER_TRANSACTIONS="24" INTERLOCK_TABLE_SIZE="112" DEFINE TRANSLATION TABLE_NAME="NEW" USERS="128" DEFINE VISUALM_SERVER TCP_PORT_NUMBER="6001" TCP_PORT_RANGE="512" DEFINE VOLUME_SET_ALIAS OLD_VOLUME_SET_NAME="TST" NEW_VOLUME_SET_NAME="MUG" Using the Configuration Option File Utility (^OPTMAN) B-43 C ________________________________________________________________ Using the ^RTH Performance Statistics Utility The Performance Statistics Utility, ^RTH, has generally been replace by the new Performance Monitoring Facility (^PMF) described in Chapter 6. However, ^RTH is still included in DSM for operational compatibility with previous releases. Therefore, if you prefer to use ^RTH, you may continue to do so. However, you should be aware of the following restric- tions: o You cannot have the ^RTH and ^PMF data collectors running simultaneously. o You must shut down ^PMF data collectors before starting an ^RTH data collection. o Data collected by ^RTH cannot be read by the ^PMF reporting programs. The following sections of this appendix explain how to use the ^RTH utility. You should consult Chapter 6 for more information about interpreting the data produced by ^RTH Overview of ^RTH The ^RTH Utility generates graphs that display system use patterns that can help identify system bottlenecks. Histograms depict: o Global system performance parameters o Relative CPU use by routine o Relative frequency of routine loads o Global references per second by individual global Using the ^RTH Performance Statistics Utility C-1 o DDP activity You can use this information to decide which routines to map, to determine where to place globals for load balancing, and to identify those routines that are the best candidates for code optimization if system response time or throughput is unacceptable. Using the Performance Statistics Utility You can access ^RTH by entering the following: >D ^RTH The utility displays the following menu: RTH Utilities 1. LOG (^RTHIST) 2. PRINT (^RTHISTP) 3. SAVE (SAVE^RTHISTP) 4. STATUS (STATUS^RTH) 5. STOP (HALT^RTH) Enter option > The following conventions apply to the ^RTH Utility options: o Press Ctrl/Z or Ctrl/C to exit from the option. o Type a question mark (?) and press Return for help at any input prompt. o Type a circumflex (^) and press Return to repeat the previous input prompt. o Type a circumflex and the letter L (^L) and then press Return to list available choices where appropriate. The LOG option (^RTHIST) allows you to log performance data for a certain period of time (a session). The ^RTHIST option creates five different reports, which are described in the following sections. To run ^RTHIST, enter the following: C-2 Using the ^RTH Performance Statistics Utility >D ^RTHIST Log System performance statistics How many logging sessions <1> How many minutes will each logging session last <1> Delay how long (minutes) between sessions <5> Enter description field for report headings Begin collecting after <18-JUN-1997 13:18:20> The statistics logging session will now be started with a JOBBED process. The first session will be filed as #1. Collection will begin at 18-JUN-1997 13:18:20. You can check on the status of the statistics session by running STATUS^RTH. Do HALT^RTH to signal the statistics logger to stop after its next session. Press RETURN to continue You need to enter the number of logging sessions you want, the number of minutes each logging session should last (up to 480 minutes), the delay (up to 1440 minutes) between sessions, a descriptive text field for the report heading, and a date and time to begin collection. The PRINT option (^RTHISTP) lets you print out the reports that contain the data that was logged using the LOG option. Note that the reports are 132 columns wide. You can display the reports on your terminal or send them to a specific device. You can print multiple logging session reports in a single print session. If you choose to print multiple logging sessions, a consolidated report is also produced. The SAVE option (SAVE^RTHISTP) allows you to save the names of the most frequently loaded routines during the logging session for later use in building mapped routine global memory sections. The SAVE^RTHISTP Utility divides the routine names into a load distribution, which lists the number of routines that represents each 10 percent increment of total routine loads. You can then choose the percentage of total routine loads you want to cover with routine mapping. Using the ^RTH Performance Statistics Utility C-3 A load distribution is shown in the following example: >D SAVE^RTHISTP SAVE FREQUENTLY ACCESSED ROUTINES TO FILE(S) Node Identifier Which statistics session(s) <1> 3 routines account for 30 percent of loads. ( >= 0.49 loads/second) 15 routines account for 40 percent of loads. ( >= 0.13 loads/second) 30 routines account for 50 percent of loads. ( >= 0.11 loads/second) 70 routines account for 60 percent of loads. ( >= 0.11 loads/second) 90 routines account for 70 percent of loads. ( >= 0.10 loads/second) 120 routines account for 80 percent of loads. ( >= 0.10 loads/second) 200 routines account for 90 percent of loads. ( >= 0.05 loads/second) 320 routines account for 100 percent of loads. ( >= 0.02 loads/second) Cover what % of total routine loads with routine mapping? > 80 Saving 120 routine names (loaded more than 0.10 times/second). Output Device ? FILE: DSM$RTHIST_PHAEMP.DAT - 120 routine names saved. After choosing the sessions to use as a basis for mapping, the utility displays a routine load distribution and asks you for the percentage of total routine loads to be covered by mapping. The previous example covers 80 percent of the routines and saved 120 routine names. The files built for each volume set and UCI can be used as input at the routine selection prompt of the ^RMBLD Utility. This routine allows you to automate and improve the accuracy of choosing the appropriate routines for inclusion into a mapped routine set. Only the minimal number of routines are mapped to produce the greatest efficiency. The STATUS^RTH option shows if any statistics logging sessions are currently active. The HALT^RTH option signals a statistics logging process to stop collecting at the end of the current logging session. Data gathered on many statistics is displayed as histograms by the ^RTHIST option. C-4 Using the ^RTH Performance Statistics Utility The following is a list of the types of data that ^RTHIST reports on: o Database event counts o Derivative ratios o Routine execution time o Routine call counts o Global reference counts o Distributed Data Processing (DDP) activity The following sections describe each of the ^RTH histograms. Database Event Counts and Derivative Ratios Histogram The Database Event Counts and Derivative Ratios histogram displays global and routine statistic information that the database access handlers automatically accumulate. The data represents averages of events per second. Figure C-1 shows an example of the histogram that displays the database event counts and derivative ratios based on the database event count statistics. The database event count statistics displayed in this histogram are described as follows: 1 Routine Loads The number of times that routines are loaded because of DO, GOTO, ZLOAD, and ZSAVE commands. 2 Mapped Rtn Accesses The count of accesses to routines that are mapped in memory. 3 Physical Reads The number of times a real physical disk read was performed to read a database block into DSM global buffer cache. 4 Logical Reads The number of times a database block was required for a global access. Using the ^RTH Performance Statistics Utility C-5 5 Physical Writes The number of DSM blocks written to disk by the Write Demon. 6 Logical Writes The number of times a disk block was modified by a DSM process and marked as needs writing. 7 Search Last Tries The number of times that a DSM process attempted to resolve a global reference by checking the last DSM block that it referenced. 8 Search Last Successes The number of times that a DSM process actually resolved a global reference by checking only the last DSM block that it referenced. 9 Global Accesses The total number of global GET, SET, KILL, $DATA, and $NEXT operations performed by the DSM global system. 10 Global Gets The total number of global variable reads done. For example: S A=^X(4) 11 Global $DATAs The total number of global variable $DATA operations done. For example: S A=$D(^X(4)) 12 Global $NEXTs The total number of global variable $NEXT operations done. For example: S A=$N(^X(-1)) S A=$O(^X("")) 13 Global Sets The total number of global variable SET operations done. For example: S ^X(4)="PATIENT" C-6 Using the ^RTH Performance Statistics Utility 14 Global Kills The total number of global variable KILL operations done. For example: K ^X(4) 15 Global Seizes The number of times that a volume set was exclu- sively owned by a DSM process while it performed a multiple-block update to the DSM database (either a block split or merge operation). 16 Global Seize Waits The number of times that a DSM process had to gain exclusive access to a volume set because other processes were already accessing it concurrently. 17 Global Access Waits The number of times that a DSM process had to wait to access a volume set because another process had it seized (exclusively-owned). 18 Directory Searches The number of times that DSM processes searched the global directory of a volume set to satisfy a global reference. 19 Block Allocates The number of DSM blocks added to a DSM global structure, as in the case of a split operation. 20 Block Deallocates The number of DSM blocks removed from a DSM global structure and marked as free, as in the case of a merge operation. 21 Global Synch Waits The number of times that a DSM process had to wait for exclusive access to a data structure other than the actual DSM global buffers. 22 Global List Waits The number of times that a DSM process had to wait before searching for a DSM database block in cache. Using the ^RTH Performance Statistics Utility C-7 23 Global Buffer Waits The number of times that a DSM process had to wait for exclusive access to a cached DSM database block. 24 Buffer Write Waits The number of times that a DSM process had to wait to read a new block into cache because the cache was full of unwritten modified blocks. Derivative ratios show the effectiveness of the optimiza- tion algorithms of both the disk cache and the global database handler. These ratios are derived from the database event count statistics. Figure C-1 shows the derivative ratio statistics. The following describes the derivation ratio statistics: o Block Requests for each Global Reference - shows the effectiveness of the global database handler. In general, global and routine references require more than one block request to get the data. The global database handler uses optimization algorithms to minimize the number of these block requests. When successive references (within a job) are to the same global, the second and following references can require fewer block requests. If global references within a job are grouped by global name, the ratio declines to approach the value of 1. o Actual Block Reads for each Read Request - shows the effectiveness of the disk cache in minimizing disk reads. o Block Write Requests for each SET command - must be at least 1. This ratio can be expected to increase as the rate of growth of the database increases. When a global block overflows, a split occurs, causing at least four block writes to the following: - Two resulting blocks - Ancestor pointer block - Map block C-8 Using the ^RTH Performance Statistics Utility o Actual Block Writes for each Write Request - shows the effectiveness of the disk cache and the Write Demon in minimizing disk writing. Individual Routine CPU Time as a Percentage of Total Routine CPU Time Histogram The Individual Routine CPU Time as a Percentage of Total Routine CPU Time histogram shows the relative CPU cost of routines. This report can point to routines that are candidates for code optimization if your system is experiencing response time or throughput problems. Figure C-2 shows an example of the histogram that displays the time spent executing routines as a percentage of the total CPU time for the logging session. Individual Routine Loads as Percentage of Total Histogram The Individual Routine Loads as Percentage of Total histogram shows which routines have been loaded as the result of a DO, GOTO, or ZLOAD command, or as the result of a trap via the $ZTRAP mechanism. Choose routines that display the highest percentage of loads to maximize the performance improvement of routine mapping. Figure C-3 shows an example of the histogram that displays the individual routines as a percentage of total routine loads. Global References Per Second Histogram The Global References Per Second histogram is an analysis, by UCI and the global name, of the combined count of all references to global variables. This is actually a global-by-global breakdown of the counts recorded previously as Global GET, $DATA, or $NEXT operations (no sign following the global name), Global SET operations (plus sign (+) following the global name), and Global KILL operations (minus sign (-) following the global name). The statistics area has a limited amount of memory. Each routine and global referenced occupies one cell. When available space is filled, subsequent new unique references are logged in the No Room category. Using the ^RTH Performance Statistics Utility C-9 Figure C-4 shows an example of the histogram that displays the number of global references per second. Distributed Data Processing Activity Histogram The Distributed Data Processing Activity histogram provides a report of DDP traffic that occurs during the ^RTHIST logging session. The report supplies the following information about each node in the network: o Requests received per second o Requests sent per second o Packets sent during the session o Messages per packet o Bytes per packet o Requests retried during session o Requests out of SYNCH o Messages transmitted per second o Packets transmitted per second o Bytes transmitted per second For more information about these fields and the optimiza- tion implications of this information, see the DSM for OpenVMS Database Operations Guide. Figure C-5 shows an example of the report that displays the DDP activity on your system during the logging session. C-10 Using the ^RTH Performance Statistics Utility D ________________________________________________________________ Sample Listings for DSM Installation and IVP This appendix provides a listing for the OpenVMS Version 7.1 installation and Installation Verification Procedure (IVP). VMSINSTAL and IVP Procedure (Console Output) Example D-1 shows the console output of the VMSINSTAL procedure and IVP. It also lists the files that are created in the system directories. Example D-1 VMSINSTAL Console Output $@sys$update:vmsinstal OpenVMS VAX Software Product Installation Procedure V7.1 It is 1-JUL-1997 at 09:17. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES]? * Where will the distribution volumes be mounted: VAXDSM$DKA0:[DSMMGR] Enter the products to be processed from the first distribution volume set. * Products: DSMVAX070 * Enter installation options you wish to use (none): The following products will be processed: DSMVAX V7.0 Beginning installation of DSMVAX V7.0 at 09:17 (continued on next page) Sample Listings for DSM Installation and IVP D-1 Example D-1 (Cont.) VMSINSTAL Console Output %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. * Do you want to run the IVP after the installation [YES]? * Include support for the M Windowing API and the X Window Interface [YES]? NO * Include DASL files [YES]? NO * Include support for DEC DB Gateway for DSM [NO]? * Do you want to purge files replaced by this installation [YES]? No further questions will be asked during this installation Begin installation of DSM base components ----------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set B ... Linking the DSM base images %DSM-I-LINK, linking shareable image DSM$SHRLIB.EXE %DSM-I-LINK, linking shareable image DSM$SHARE.EXE %DSM-I-STB, creating DSM$SHARE.STB %DSM-I-LINK, linking main image DSM.EXE %DSM-I-LINK, linking DDP Driver image DSM$AADRIVER.EXE The following files will be created or updated directory [SYSEXE] DSM.EXE - DSM main image DSM$ECALL_DEBUG.EXE - Debug image for user written external routines directory [SYS$LDR] DSM$AADRIVER.EXE - DSM DDP driver directory [SYSLIB] (continued on next page) D-2 Sample Listings for DSM Installation and IVP Example D-1 (Cont.) VMSINSTAL Console Output DSM$SHARE.EXE - DSM shareable image DSM$SHRLIB.EXE - DSM protected shareable image DSM$SHARE.STB - Symbol table for DSM$SHARE.EXE DSM$MT_EBCASC.EXE - DSM EBCDIC/ASCII translation tables DSM$MT_EBCASC.MAR - Source file of DSM EBCDIC/ASCII conversion table DSM$MT_EBCASC.OPT - Linker option file for DSM$MT_EBCASC.EXE DSM$ECALL.EXE - DSM external call package table image DSM$ECALL.OPT - Linker option file for DSM$ECALL.EXE DSM$ECMACRO.MLB - Macro library for user written external routines DSM$ANASYS.SAV - DSM system analyzer utility DSM$GUI.SAV - OpenM GUI Utilities DSM$MGW.SAV - Web Server Utilities DSM$MGW2.SAV - Web Server template DSM$MVB.SAV - Visual M Server Utilities MANAGER.DSM - DSM Management routines UTILITIES.DSM - DSM Library routines DSMVOL1.GLS - DSM primary volume set MENU.GBL - Library utility menu global HELP.GBL - DSM HELP global ED.GBL - DSM editor global EDI.GBL - DSM editor EDI global EDIHELP.GBL - DSM editor EDI HELP global EDT.GBL - DSM EDT editor global TPU.GBL - DSM TPU editor global Q.GBL - DSM utility global for query generation REPLACE.GBL - DSM utility global for recompiling user routines RESTORE.GBL - DSM utility global for restoring DSM routines LIBREPL.GBL - DSM utility global for recompiling library routines MWE.GBL - Window Editor global MWE1.GBL - Window Editor colors and resources global DSM$GLOBAL.FDL - FDL file to CONVERT/FDL for RMS globals DSM$CALL.OPT - Linker option file for callable routines DSM$CALLDEF.H - Definition file for callable routines DSM$CALLDEF.FOR - Definition file for callable routines DSM$CALLDEF.ADA - Definition file for callable routines DSM$CALLDEF.BAS - Definition file for callable routines DSM$CALLDEF.MAR - Definition file for callable routines DSM$CALLDEF.MLB - Definition file for callable routines DSM$CALLDEF.PAS - Definition file for callable routines (continued on next page) Sample Listings for DSM Installation and IVP D-3 Example D-1 (Cont.) VMSINSTAL Console Output DSM$CALLDEF.PLI - Definition file for callable routines DSM$CALLDEF.R32 - Definition file for callable routines directory [SYSMGR] DSM$INIT.COM - Command procedure to initialize a DSM account DSM$CONFIGURE.COM - Command procedure to create a DSM configuration DSM$UPGRADE.COM - Command procedure to upgrade a DSM configuration DSM$VOLUPG.COM - Command procedure to upgrade a volume set DSM$SHUTDOWN.COM - Command procedure to shut down a DSM configuration DSM$MSG_BUILD.COM - Command procedure to create custom error messages DSM$MT_BUILD.COM - Command procedure to build EBCDIC/ASCII tables DSM$LNKINI.COM - Command procedure to start a DECnet DDP link server DSM$TCPINI.COM - Command procedure to start a TCP/IP DDP link server directory [SYSMSG] DSM$MESSAGE.MSG - DSM source file of error messages DSM$MESSAGE.EXE - DSM message file image DSM$MSGPTR.OBJ - DSM message pointer object file directory [SYS$STARTUP] DSM$STARTUP.COM - Command file to start a DSM environment DSM$INSTALL.COM - Command file to install DSM images at system boot DSM$INSTALL_SITE.COM - Command file for site-specific boot time operations directory [SYSHLP] HELPLIB.LIB - Add/update DSM help text DSM070.RELEASE_NOTES - Release Notes directory [SYSHLP.EXAMPLES] (continued on next page) D-4 Sample Listings for DSM Installation and IVP Example D-1 (Cont.) VMSINSTAL Console Output DSM$ECALL_USER_TABLE.MAR - Template source file for user ECALL table DSM$ECALL_EXAMPLE_TABLE.MAR - Example ECALL Table Source file DSM$ECALL_EXAMPLE_CTABLE.MAR - Example ECALL Table Source file DSM$ECALL_EXAMPLE_PKTAB.MAR - Example ECALL Package Table Source file DSM$ECALL_EXAMPLE_CODE.MAR - Example user-written ECALL routines DSM$ECALL_EXAMPLE_CCODE.C - Example user-written ECALL routines DSM$ECALL_EXAMPLE_BUILD.COM - Example user-written ECALL build procedure DSM$ADBOOK.PAS - Example of using the callable routines DSM$ADBOOK_C.C - Example of using the callable routines DSM$ORDER.FOR - Example of using the callable routines DSM$GLISTP.PAS - Example of using the callable routines DSM$GLIST_COBOL.COB - Example of using the callable routines DSM$GLIST_C.C - Example of using the callable routines DSM$GLIST_MACRO.MAR - Example of using the callable routines DSM$IOCTL.TABLE - Example I/O Control Mnemonic Table directory [SYSTEST] DSM$IVP.COM - Residual Installation Verification Procedure %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installing DSM$SHARE and DSM$SHRLIB images as shareable Calling DSM Installation Verification Procedure Installation Verification Procedure for DSM Copyright (c) Digital Equipment Corporation, 1992 DSM x.x for OpenVMS VAX DSMMGR [Baseline] DSM x.x for OpenVMS VAX IVP Successful %DSM-I-HALT, HALT command executed DSM installation is complete. You may enter the following command line to initialize a manager account for use with DSM: @SYS$MANAGER:DSM$INIT (continued on next page) Sample Listings for DSM Installation and IVP D-5 Example D-1 (Cont.) VMSINSTAL Console Output Installation of DSMVAX V7.0 completed at 09:20 Enter the products to be processed from the next distribution volume set. * Products: Exit VMSINSTAL procedure done at 09:21 D-6 Sample Listings for DSM Installation and IVP ________________________________________________________________ Index A Accounts ___________________________ application, 2-8, 3-15, Access control 3-22 application mode, 3-12, captive, 3-4, 3-23 3-17 environment manager, application systems, 3-1 1-17, 2-7 callable interface, 3-27 OpenVMS operating system, configurations, 3-3, 3-8 2-1 ^CONFIG Utility, 3-9 OpenVMS users, 3-4 DSM$DSM routine, 3-28 programmer, 2-7, 3-15 DSM$INITIALIZE routine, tied application, 3-22 3-28 ACE, 3-5 environment, 3-3, 3-5 default protection, 3-6 globals, 3-3, 3-14 ACL, 1-18, 2-4 manager mode, 3-9 file protection, 3-5 OpenVMS system, 3-3, 3-4 ^ACLCALL program, 3-21 programmer mode, 3-11, ^ACLSET Utility, 3-20, 3-17 7-18 relationships, 3-3 running in a VMScluster time-sharing system, 3-2 environment, 3-19 Access control entries using ^ACLCALL, 3-21 See ACE ^ACL Utility, 3-17, 7-18 Access control list creating alternate See ACL environment manager, Accessing the PMF utility 2-7 set, 6-26 granting application mode Access mode, 3-8 access, 3-9 application, 3-12, 3-17 granting programmer mode manager, 3-9 access, 3-9 programmer, 3-11, 3-17 using ^ACLCALL, 3-21 specifier, 2-5 Index-1 Adding UCIs to cluster- Application mode (cont'd) mounted volume sets, enforcing restrictions, 2-19 3-12 ADDUSER.COM Application user account, adding new users to UAF, 2-8, 3-15 3-16 dedicated, 3-22 ADD^ACL Utility, 3-18, establishing, 3-15 7-18 ASTLM process quota ADD^TTPORT Utility, 3-26 requirements for Write After-image journal file Demon, 5-2 placement, 2-4 Audit Analysis Utility After-Image Journaling OpenVMS, 4-1 Utilities Audit server ^DEJRNL, 7-10 OpenVMS, 4-13 FILES, 7-10 Audit server process, 4-13 ^JOURNAL, 7-10 AUTOGEN.COM ^JRNLIS, 7-10 modifying SYSGEN SETJRN^%GLOMAN, 7-10 parameters, 1-6, 5-13 Aliasing running, 1-6 volume set, 2-30 Alternate environment B__________________________ manager Backup creating, 2-7 system disk, 1-4 file access, 2-4 ^BACKUP Utility, 7-12 manager identifier, 3-6 BALSETCNT parameter, 5-4 starting a configuration, Baseline mode, 2-5 2-33 access mode specifier, Alternate root installation 2-5 , A-1 ^BIJEXAM Utility, 7-11 configuration shutdown, ^BIJFORC Utility, 7-11 A-13 ^BIJINIT Utility, 7-11 directory structure, A-1 BIJ Utilities DSM environment, A-12 ^BIJEXAM, 7-11 procedure, A-4 ^BIJFORC, 7-11 search lists, A-2 ^BIJINIT, 7-11 Application NOAIJ^BIJFORC, 7-11 access control, 3-1 NOBIJ^BIJFORC, 7-11 accounts, 2-8, 3-15, 3-22 Bit masks dedicated system, 3-1 programmer and optimizing, 6-1 application mode Application mode restrictions, 3-12 access control, 3-12, Bookreader Library 3-17 minimum size requirements with DSM, 1-3 Index-2 BYPASS qualifier Commands restricting access, 3-11 VIEW, 3-11 BYTLM process quota, 5-1 ZESCAPE, 3-12 ^CONDDP Utility, 7-14 C__________________________ Configuration access C2 control, 2-14 definition, 4-1 Configuration access global C2 security rating See ^DSMACC configuration definition of, 4-1 access global Caché Weblink Configuration identifier, basic Installation, 9-2 2-11 Remote DSM server, 9-1 Configuration Management World Wide Web server as Utilities, 7-4 a client, 9-1 ^ACL, 7-18 Caché/Weblink ^CONFIG, 7-4 overview, 9-1 COPY^CONFIG, 7-4 Caché Weblink installation ^DBSMAN, 7-9 %MGW, 9-2 DELETE^CONFIG, 7-4 %MGW2, 9-2 DISPLAY^CONFIG, 7-4 Callable interface ^FORCEX, 7-19 access control, 3-27 ^LOCKTAB, 7-19 Captive accounts ^LOGIN, 3-29, 7-18, 7-20 command procedure, 3-24 ^MEMORY, 5-7, 7-18 creating, 3-23 MODIFY^CONFIG, 7-5 definition of, 3-4 ^SHUTDWN, 2-36, 7-20 Checking system volume set ^STU, 2-6, 2-33, 7-18 mounting, 2-46 ^%SY, 7-18 Cluster-mounted system ^TIED, 3-25, 7-18 volume sets, 2-19 Configuration option file Cluster-mounted volume sets converting, B-5 adding UCIs, 2-19 creating, B-3 Clusterwide configuration, data keywords, B-1, B-7, 2-42 B-14 CMKRNL privilege definition keywords, B-1, installing shared images, B-7, B-8 1-13 example, B-40 Codes minimum entries, B-40 audit facility message using, B-1 event, 4-3 Configurations Command line qualifiers See also Configuration modifying with ^CONFIG, option file 2-28 access control, 3-3, 3-8 cluster, 2-42 database set master, 2-45 Index-3 Configurations (cont'd) default, 2-36 D__________________________ defining, 2-11, B-1 DASL software definition of, 2-6 installation, 1-8 enabling security Database auditing for, 4-11 degradation, 1-38 modifying, 2-38 overview, 2-8 option file, B-1 Database files running multiple, 2-39 default directory, 2-3 shutting down, 1-38, 2-36 Database set, 2-8 shutting down in an DSM-11 compatible, 2-9 alternate root, A-13 OpenVMS DSM, 2-9 starting, 2-33, B-6 transaction, 2-10 starting in alternate utilities, 7-12 manager account, 2-33 Database set master, 2-45 virtual memory Database set masters requirements, 5-11 effects of disabling, VMScluster environment, 2-21 2-45 specifying in ^CONFIG, Configuring for resident 2-21 images on Alpha, 1-14 with After-Image ^CONFIG Utility, 2-6, 7-4 Journaling requests, aborting with Ctrl/C, 2-21 2-12 Data keywords, B-1, B-14 access control, 3-9 ^DBSMAN Utility, 7-9 creating a configuration, ^DBT Utility, 7-13 2-11 to 2-32 DCL commands enabling mapped routines, DIRECTORY/SECURITY, 3-7 6-9 SHOW MEMORY, 5-15 implementing STOP/ID, 2-37 configuration access DDP control, 2-14 global request servicing, supporting performance 2-33 histograms, 2-15 multicast advertising supporting Visual M, 2-15 interval, 2-26 ^CONMAN Utility, 2-11, 7-4 request credit maximum, COPY^CONFIG Utility, 7-4, 2-25 7-7 request retry mechanism, Ctrl/C 2-24 aborting ^CONFIG Utility, servers, 2-50 2-12 ^DDPCIR Utility, 7-14 DDP groups description, 2-24 implementing, 2-24 Index-4 DDP links Definitions (cont'd) DECnet, 2-27 security audit profiles, Ethernet, 2-27 4-11 TCP/IP, 2-27 ^DEJRNL Utility, 7-10 types of, 2-27 DELETE^ACL Utility, 3-20, ^DDPLNK Utility, 7-14 7-18 DDP processes DELETE^CONDBS Utility, counting as a user, 2-14 7-12 ^DDPREQ Utility, 7-14 DELETE^CONFIG Utility, ^DDPSEC Utility, 7-15 7-4, 7-5 DDP servers DELETE^TTPORT Utility, description, 2-23 3-27 specifying through Detached process, 2-48 ^CONFIG, 2-23 DDP servers, 2-50 ^DDPSTA Utility, 7-15, Garbage Collector, 2-49 7-17 Journal Process, 2-50 DDP Utilities Recovery Process, 2-50 ^CONDDP, 7-14 Write Demon, 2-49 ^DDP, 7-14 DIOLM process quota, 5-2 ^DDPCIR, 7-14 Directories ^DDPLNK, 7-14 alternate root, A-1 ^DDPREQ, 7-14 cluster nodes, 2-3 ^DDPSEC, 7-15 database files, 2-3 ^DDPSTA, 7-15 DSM, 2-1 ^DDPUTL, 7-14 environment root, 2-2 LINK^DDPLNK, 7-15 hierarchy, 2-43 START^DDPLNK, 7-15 journal files, 2-2 STOP^DDPLNK, 7-15 single-node system, 2-3 ^DDP Utility, 7-14 system root, A-1 ^DDPUTL Utility, 7-14 VMScluster environment, DEC DB Integrator Gateway for DSM 2-43 initializing in DIRECTORY/SECURITY command DSM$INSTALL.COM, 1-36 (DCL), 3-7 DECnet links DISPLAY^CONDBS Utility, DDP, 2-27 7-12 Default global DISPLAY^CONFIG Utility, characteristics 7-4, 7-6 modifying in ^CONFIG, 2-28 Distributed Data Processing Definition keywords, B-1, Utilities B-8 See DDP Utilities Definitions Distribution kit, 1-1 C2, 4-1 Index-5 DSM$ALTROOT.COM, A-3 DSM$INSTALL.COM (cont'd) DSM$ALTROOT_INSTALL.COM, initializing A-3 DEC DB Integrator Gateway for DSM example, A-6 , 1-36 DSM$BATCH batch queue, initializing DSM, 1-36 2-34 installing shared images, DSM$CD_LICENSE.COM, 1-16 1-12, 1-36 DSM$CONFIGURE.COM loading DDP driver, 1-36 alternate root DSM$INSTALL_SITE.COM installation, A-4 allocating nonpaged configuring DSM, 1-28 memory, 5-19 running, 1-29 allocating physical pages DSM$CRASH logical name, , 1-37 1-39 configuration, starting, DSM$DEFAULT_envnm logical 2-34 name, 2-40 creating batch queues, DSM$DSM routine 1-37 access control, 3-28 heterogeneous VMScluster DSM$ECALL.EXE, 1-12 environment, 2-47 DSM$ENVIRONMENT logical installing ECALL image, name, 2-41 1-37 DSM$ID_envnm logical name, mounting DSM-11 2-40 compatible disks, 1-37 DSM$INIT.COM running in a command procedure, 1-18 heterogeneous creating a OpenVMS VMScluster environment, account, 3-6 1-37 creating directories, 2-3 starting up creating environment configurations, 1-37 manager account, 1-17 DSM$LIBRARY logical name, directory protection, 2-4 2-47 file protection, 2-4 DSM$MESSAGE.EXE, 1-12 running, 1-19 DSM$MT_EBCASC.EXE, 1-12 VMScluster environment, DSM$SHARE.EXE, 1-12 2-42 DSM$SHRLIB.EXE, 1-12 DSM$INITIALIZE routine DSM$SHUTDOWN.COM, 2-37 access control, 3-28 shutting down a DSM$INSTALL.COM configuration, 1-38 calling DSM$INSTALL_ DSM$STARTUP.COM, 2-34 SITE.COM, 1-36 DSM$SYSBUF global section, defining search lists, 5-20 1-36 Index-6 DSM.EXE, 1-11 Entering your license, DSM-11 compatible database 1-31 set, 2-9 Environment DSM-11 compatible disk See also Environment identifier, 1-18 manager account DSMACC.GBL configuration access control, 3-3, 3-5 access global alternate root See ^DSMACC configuration installation, A-12 access global definition of, 2-1 ^DSMACC configuration directories, 2-2 access global, 1-19, identifier, 2-2, 2-39 2-2 maintaining security, 3-7 DSMCRASH.LOG file, 1-39 name, 2-39 DSMDEMON.LOG, 2-49 ENVIRONMENT=envnm qualifier startup failure, 1-31 , 2-40 DSMGARCOL.LOG, 2-49 Environment configuration DSM image global abnormal termination, See ^SYS environment 2-37 configuration global DSM images Environment manager installing as resident on creating user accounts, Alpha, 1-13 3-15 ^DSMMGR system global, Environment manager account 1-19 , 2-1, 2-7 setting up in a alternate, 3-6 heterogeneous cluster, creating, 1-17 2-46 privileges, 1-28 DSM Security Audit Facility Environment root directory, introduction to, 4-1 2-2 DSM users Ethernet links defining the number of, DDP, 2-27 2-14 Event messages data, 4-2 E__________________________ fields, 4-3 Enabling security auditing, subfields, 4-3 4-11 Events Enabling the DSM Security security audit, 4-2 External routines Facility, 2-16 %SETUCI, 3-11, 6-12 ENQLM process quota, 5-2 Entering a license, 1-32 Index-7 Global performance F__________________________ histograms, 2-15 F$GETSYI lexical function, Globals 1-5, 6-5 access control, 3-3, 3-14 File protection ^%NSpace, 8-3 ACL protection, 3-5 performance, 6-15 identifiers, 3-5 global sections renaming files, 3-8 shared, 6-3 UIC-based, 2-4, 3-5 Global sections FILLM process quota, 5-2 shared, 5-16 ^FORCEX Utility, 2-37, Global translation tables 7-19 modifying with ^CONFIG, Functions 2-30 $VIEW, 3-11 ^%GLOMAN Utility, 7-13 ^GLSSTA Utility, 6-15, G 7-17 ___________________________ report example, 6-16 Garbage Collector granularity hint regions, counting as a user, 2-14 1-6 log file, 2-49 Granularity hint regions, process, 2-49 1-13 GBLPAGES parameter, 5-5, reserving memory 6-4 resources, 1-6 requirements for Graphic library utilities, installation on Alpha 10-1 systems, 1-5 installing, 10-1 requirements for GUI utilities installation on VAX installing, 10-2 systems, 1-5 GBLPAGFIL parameter, 5-6 H__________________________ GBLSECTIONS parameter, HALT^RTH Utility, C-4 5-5, 6-4 Help text, 7-2 requirements for ^%HELP Utility, 7-2 installation on Alpha Heterogeneous VMScluster systems, 1-5 environment requirements for running DSM in, 2-46 installation on VAX Histograms systems, 1-5 database event counts, Global characteristics C-5 default, 2-28 derivative ratios, C-5 modifying in ^CONFIG, Distributed Data 2-28 Processing activity, C-10 global references, C-10 Index-8 Histograms (cont'd) Installation Verification routine execution, C-9 Procedure routine loads, C-9 See IVP $HOROLOG date Installing Caché Weblink, modifying with ^CONFIG, 9-2 2-30 Installing Caché Weblink /master, 9-2 I__________________________ Installing DSM images as Identifiers resident, 1-13 DSM environment, 1-18, IVP, 1-10 2-2, 2-4 console output, D-1 file protection, 3-5 installing shared images, Image 1-12 installing shared, 1-12 main, 1-11 J__________________________ relationships, 1-11 Journal Process, 2-50 shareable, 1-11 counting as a user, 2-14 Installation ^JOURNAL Utility, 7-10 alternate root, A-1 ^JRNLIS Utility, 7-10 backing up system disk, 1-4 L__________________________ changes for VMScluster Lexical functions environment, 1-16 F$GETSYI, 6-5 DASL software, 1-8 Library utilities distribution kit, 1-1 command line, 10-1 documentation, xiii graphic, 10-1 editing system files, Library Utilities, 7-1 1-36 editing restrictions, OpenVMS version required, 3-12 1-1 ^%HELP, 7-2 overview, 1-3 with mapped routines, 6-6 post, 1-17 Licenses procedure, 1-4 editing, 1-32 shared images, 1-12 License servers, 1-31 software, 1-1 LINK^DDPLNK Utility, 7-15 space requirements, 1-2 ^LKMSTA Utility, 7-17 SYSGEN requirements, 1-5 ^LMFEDIT utility, 1-32 system shutdown, 1-38 LOCKIDTBL parameter, 5-4 system startup, 1-36 LOCKIDTBL_MAX parameter, time requirements, 1-2 5-5 VMScluster environment, ^LOCKTAB Utility, 7-19 1-15, 1-38 VMSINSTAL, 1-7 Index-9 Log files Mapped Routine Utilities DSMCRASH.LOG, 1-39 ^RMAP (cont'd) Garbage Collector MAPSET^RMSHO, 6-4, DSMGARCOL.LOG, 2-49 7-16 Write Demon MAP^%RD, 6-4, 7-15 DSMDEMON.LOG, 2-49 ^RMBLD, 6-3, 6-6, 7-15 Logical names ^RMDEL, 6-4, 7-15 DSM$CRASH, 1-39 ^RMDIS, 6-4, 7-15 DSM$DEFAULT_envnm, 2-40 ^RMINS, 6-4, 7-15 DSM$ENVIRONMENT, 2-41 ^RMSHO, 6-3, 7-15 DSM$ID_envnm, 2-40 MAPSET^RMSHO Utility, 6-4, DSM$LIBRARY, 2-47 6-12, 7-16 ^LOGIN Utility, 3-29, MAP^%RD Utility, 6-4, 7-18, 7-20 6-12, 7-15 LRPCOUNT parameter, 5-6 MAXPROCESSCNT parameter, M 5-4 ___________________________ ^MEMORY Utility, 5-7, 7-18 Main image, 1-11 ^MEMREQ Utility, 1-31, 5-7 Manager mode mapped routines access control, 3-9 requirements, 6-6 MANAGER qualifier, 2-12, private sections, 5-12 2-33 process quota controlling logins, 3-29 requirements, 5-10 manager mode, 3-9 resource requirements, Mapped routines, 6-2 5-11 changing routine shared sections, 5-12 directories, 6-12 SYSGEN parameters, 5-4, considerations, 6-14 5-8 creating, 6-6 ^MEMUSE Utility, 5-7, 5-21 disabling, 6-13 Message event codes enabling with ^CONFIG, DSM audit facility, 4-3 6-9 Minimum size requirements executing, 6-11 for DSM with Bookreader including support for, Library, 1-3 2-28 Mixed architecture Library Utilities, 6-6 VMScluster environment mapping, 6-6 running DSM in, 2-46 memory requirements, 6-4 setting up RIGHTSLIST.DAT modifying SYSGEN , 2-47 parameters, 6-4 setting up SYSUAF.DAT, utilities, 6-3 2-47 Mapped Routine Utilities ^RMAP, 6-2, 6-3, 7-15 Index-10 Modifying database sets OpenVMS Authorize Utility, with MODIFY^CONFIG, 7-8 2-7, 3-15 MODIFY^CONDBS Utility, creating captive accounts 2-10, 7-12 , 3-23 MODIFY^CONFIG modifying process quotas, modifying database sets, 5-1 7-8 OpenVMS DSM database set, MODIFY^CONFIG Utility, 2-9 7-5, 7-8 OpenVMS free list, 5-18 MODIFY^TTROU Utility, 3-26 OpenVMS identifier MODPARAMS.DAT, 1-6, 5-14 See Identifiers MONITOR^GLSSTA Utility, OpenVMS Install Utility, 6-15 1-5, 1-12, 3-28, 5-20 Multicast advertising OpenVMS Monitor Utility, interval, 2-26 5-6 M Windowing API OpenVMS operating system See WAPI accounts, 2-1 OpenVMS system N__________________________ access control, 3-3, 3-4 Namespaces modifying parameters, defining for graphic 5-13 utilities, 8-7, 10-3 process quotas, 5-1 Visual M, 8-8 tuning for DSM, 5-1 NOAIJ^BIJFORC Utility, OpenVMS System Management 7-11 Utility NOBIJ^BIJFORC Utility, See SYSMAN Utility 7-11 (OpenVMS) Nonpaged memory OpenVMS users configuring, 5-17 accounts, 2-7, 3-4 description, 5-16 OpenVMS Utilities using, 5-15 Authorize, 2-7, 3-15 automatic login facility, O__________________________ 3-23 Object class names Install, 1-5, 1-12, 3-28, definition of, 4-2 5-20 Online help Monitor, 5-6 ^%HELP Utility, 7-2 SYSGEN, 5-9 OpenVMS Audit Analysis SYSMAN, 1-39 Utility VMSINSTAL, 1-7 use of, 4-1 OPER privilege, 1-28, 3-16 OpenVMS audit server, 4-13 ^OPTBLD Utility, 7-16, B-3 Index-11 ^OPTCON Utility, 7-16, B-5 Physical memory Optimizing performance, determining with the 6-48 ^MEMORY Utility, 5-7 Option file PHYSICAL_PAGES=nnnn See Configuration option qualifier, 5-10, 5-18 file ^PMF Option File Management including support for, Utilities 6-22 ^OPTMAN utility set overview, ^OPTBLD, 7-16 6-23 ^OPTCON, 7-16 PMF reports ^OPTMAN Utility, B-3 data categories, 6-40 OPT^STU Utility description, 6-38 starting a configuration, full with global summary, B-6 6-40 optimizing performance P__________________________ from, 6-48 Page file, 5-15 report types, 6-38 monitoring usage, 5-15 summary, 6-39 Parameters PMF utilities canceling data See also SYSGEN collections, 6-29 parameters collector control GBLPAGES, 1-5 utilities, 6-26 GBLSECTIONS, 1-5 data collection, 6-29 modifying OpenVMS system, deleting reports, 6-36 5-13 determining collection SPTREQ, 5-18 status, 6-27 Password Incorporating data in a OpenVMS user accounts, report, 6-34 3-4 listing completed Performance data buffer, collections, 6-30 2-15 listing reports, 6-36 Performance monitoring listing scheduled facility collections, 6-30 and ^RTH, 6-21 managing and printing overview, 6-21 reports, 6-34 Performance Utilities, ^PMFCOL, 6-26 7-16 ^PMFDAT, 6-29 ^DDPSTA, 7-17 ^PMFGEN, 6-34 ^GLSSTA, 6-15, 7-17 ^PMFMON, 6-33 ^LKMSTA, 7-17 ^PMFREP, 6-34 ^RTH, 7-17, C-1 printing a report, 6-37 PRINT^PMFREP, 6-37 Index-12 PMF utilities (cont'd) Privileges (cont'd) purging completed TMPMBX, 1-28, 3-16 collections, 6-31 PRMMBX privilege, 3-16 purging scheduled Process quotas collections, 6-32 ASTLM, 5-2 schedule collections, BYTLM, 5-1 6-33 determining with the starting data collections ^MEMORY Utility, 5-7 , 6-27 determining with the stopping data collections ^MEMREQ Utility, 5-10 , 6-28 DIOLM, 5-2 PMF utility ENQLM, 5-2 summary report, 6-40 FILLM, 5-2 ^PMF Utility, 2-15 modifying, 5-1 PMF utility set WSDEFAULT, 5-2 accessing, 6-26 WSEXTENT, 5-3 usage conventions, 6-25 WSQUOTA, 5-3 Postinstallation Programmer account, 2-7 creating environment establishing, 3-15 manager's account, OpenVMS privileges, 3-16 1-17 Programmer mode PQL_DWSDEFAULT parameter, access control, 3-11, 5-6 3-17 PQL_DWSEXTENT parameter, access restrictions, 3-11 5-6 enforcing restrictions, PQL_DWSQUOTA parameter, 3-12 5-6 Q PRINT^ACL Utility, 3-20, ___________________________ 7-18 Qualifiers Private sections BYPASS, 3-11 ^MEMREQ Utility, 5-12 ENVIRONMENT=envnm, 2-40 Privileges MANAGER, 2-12, 2-33, 3-29 application users, 3-22 PHYSICAL_PAGES=nnnn, 5-18 CMKRNL, 1-13 environment manager, 1-28 R__________________________ for using DCL REPLY/TO RECORD^GLSSTA Utility, command, 1-28 6-15 for using ZUSE command, Recovery Process, 2-50 1-28 counting as a user, 2-14 OpenVMS system, 3-16 Remote DSM WebLink server OPER, 1-28, 3-16 %MGW, 9-1 PRMMBX, 3-16 programmers, 3-16 SYSNAM, 3-16 Index-13 REPLAY^GLSSTA Utility, Security 6-15 Visual M, 8-10 Request credit maximum, Security audit events 2-25 types of, 4-2 Request retry mechanism in Security Audit Facility DDP, 2-24 DSM, 4-1 Reserved slots, 2-14 overview, 4-1 RESHASHTBL parameter, 5-5 Security auditing Resident images enabling, 4-11 configuring on Alpha, enabling for a 1-14 configuration, 4-11 RIGHTSLIST.DAT file, 3-5 Security Audit Log File setting up in a mixed analyzing, 4-13 architecture cluster, Security audit profiles, 2-47 4-11 ^RMAP Utility, 6-2, 6-3, Security event messages 7-15 data, 4-2 ^RMBLD Utility, 6-3, 6-6, fields, 4-3 7-15 selecting, 4-14 ^RMDEL Utility, 6-4, 6-13, subfields, 4-3 7-15 Security Event types ^RMDIS Utility, 6-4, 7-15 global collation ^RMINS Utility, 6-4, 6-11, modifications, 4-10 7-15 global journaling ^RMSHO Utility, 6-3, 7-15 modifications, 4-9 Routine directory global kills, 4-6 displaying in sign-on global protection banner, 3-11 modifications, 4-8 ^RTHISTP Utility, C-3 global sets, 4-5 ^RTHIST Utility programmer login, 4-3 See also histograms programmer logout, 4-4 performance data, C-4 routine modifications, queue data, C-4 4-7 ^RTH Utility, 7-17, C-1 Security Facility enabling through ^CONFIG, S 2-16 ___________________________ Security ratings SAVE^RTHISTP Utility, C-3 C2, 4-1 SAVE^RTHIST Utility Selecting security event creating mapped routines, messages, 4-14 6-8 Server routines Search lists, A-2 Visual M, 8-4 Index-14 SETJRN^%GLOMAN Utility, Summary report (cont'd) 7-10 cluster-wide statistics %SETUCI external routine summary, 6-41 changing mapped routine cluster-wide volume set directories, 6-12 statistics summary, restricting access, 3-11 6-47 Shareable image, 1-11 configuration information Shared global sections, , 6-40 5-16 mounted volume set Shared image information, 6-41 installing DSM, 1-12 Swap file, 5-15 VMScluster environment, monitoring usage, 5-15 1-38 SWAPFILES.COM, 5-15 Shared memory SYS$EXAMPLES:ADDUSER.COM, nonpaged, 5-16 3-16 configuring, 5-17 SYS$MANAGER:DSM$CONFIGURE.COM shared global sections, , 1-28 5-16 alternate root using, 5-15 installation, A-4 Shared sections SYS$MANAGER:DSM$INIT.COM, ^MEMREQ Utility, 5-12 1-17, 2-42, 3-6 SHOW MEMORY command (DCL), running, 1-19 5-15 SYS$MANAGER:DSM$SHUTDOWN.COM SHOW^TTPORT Utility, 3-27 , 1-38, 2-37 SHOW^TTROU Utility, 3-27 SYS$MANAGER:SYSHUTDWN.COM ^SHUTDWN Utility, 2-36, shutting down DSM, 1-38 7-20 SYS$STARTUP:DSM$INSTALL.COM Sign-on banner , 1-13 displaying routine starting up DSM, 1-36 directory, 3-11 SYS$STARTUP:DSM$INSTALL_ SPTREQ parameter, 5-18 SITE.COM, 2-34 Startup command file, 2-11 SYS$SYSTEM:MODPARAMS.DAT, START^DDPLNK Utility, 7-15 1-6, 5-4, 5-14 STATUS^RTH Utility, C-4 SYS$SYSTEM:RIGHTSLIST.DAT, STOP/ID command (DCL), 2-37 3-5 STOP^DDPLNK Utility, 7-15 SYS$SYSTEM:SYSALF.DAT, ^STU Utility, 7-18 3-23 configuration startup, SYS$SYSTEM:SYSUAF.DAT, 2-6, 2-33 3-15 OPT^STU Utility, B-6 SYS$UPDATE:AUTOGEN.COM, Summary report 1-6, 5-13 cluster-wide derivative ratios, 6-46 Index-15 SYS.GBL global, 2-2 System Management Utilities SYSALF.DAT ^ACL, 3-17, 7-18 automatic login facility, ^FORCEX, 2-37, 7-19 3-23 ^LOCKTAB, 7-19 ^SYS environment ^LOGIN, 7-18, 7-20 configuration global, ^MEMORY, 7-18 1-19, 2-2 ^SHUTDWN, 7-20 SYSGEN, 5-4, 5-9 ^STU, 7-18 inspecting parameter ^%SY, 7-18 values, 5-13 ^TIED, 7-18 installation requirements System shutdown , 1-5 using DSM$SHUTDOWN.COM, SYSGEN parameters 1-38 BALSETCNT, 5-4 System startup determining with the using DSM$INSTALL.COM, ^MEMORY Utility, 5-7 1-36 GBLPAGES, 5-5, 6-4 System Utilities, 7-1 GBLPAGFIL, 5-6 ^ACL, 3-17, 7-18 GBLSECTIONS, 5-5, 6-4 ^ACLSET, 3-20, 7-18 LOCKIDTBL, 5-4 ADD^ACL, 3-18, 7-18 LOCKIDTBL_MAX, 5-5 ADD^TTPORT, 3-26 LRPCOUNT, 5-6 After-Image Journaling, MAXPROCESSCNT, 5-4 7-10 ^MEMREQ Utility values, FILES, 7-10 5-8 ^BACKUP, 7-12 modifying, 5-13 Before-Image Journaling, PQL_DWSDEFAULT, 5-6 7-11 PQL_DWSEXTENT, 5-6 ^BIJEXAM, 7-11 PQL_DWSQUOTA, 5-6 ^BIJFORC, 7-11 REHASHTBL, 5-5 ^BIJINIT, 7-11 SPTREQ, 5-18 ^CONDDP, 7-14 tailoring, 5-4 ^CONFIG, 2-6, 2-11 to WSMAX, 5-4 2-32, 3-9, 7-4 SYSHUTDWN.COM, 1-38 Configuration Management, ^SYSMAN utilities 7-4 ^LMFEDIT, 1-32 ^CONMAN, 2-11, 7-4 SYSMAN Utility (OpenVMS), conventions, 7-2 1-16, 1-39 COPY^CONFIG, 7-4, 7-7 SYSNAM privilege, 3-16 ^DBSMAN, 7-9 System files ^DBT, 7-13 editing, 1-36 ^DDP, 7-14 System Generation Utility ^DDPCIR, 7-14 See SYSGEN ^DDPLNK, 7-14 ^DDPREQ, 7-14 ^DDPSEC, 7-15 Index-16 System Utilities (cont'd) System Utilities (cont'd) ^DDPSTA, 7-15, 7-17 ^RMBLD, 6-3, 6-6, 7-15 ^DDPUTL, 7-14 ^RMDEL, 6-4, 6-13, 7-15 ^DEJRNL, 7-10 ^RMDIS, 6-4, 7-15 DELETE^ACL, 3-20, 7-18 ^RMINS, 6-4, 6-11, 7-15 DELETE^CONDBS, 7-12 ^RMSHO, 6-3, 7-15 DELETE^CONFIG, 7-4, 7-5 ^RTH, 7-17, C-1 DELETE^TTPORT, 3-27 ^RTHISTP, C-3 DISPLAY^CONDBS, 7-12 running, 7-4 DISPLAY^CONFIG, 7-4, 7-6 SAVE^RTHISTP, C-3 Distributed Data SETJRN^%GLOMAN, 7-10 Processing, 7-14 SHOW^TTPORT, 3-27 ^FORCEX, 2-37, 7-19 SHOW^TTROU, 3-27 ^%GLOMAN, 7-13 ^SHUTDWN, 2-36, 7-20 ^GLSSTA, 6-15, 7-17 START^DDPLNK, 7-15 HALT^RTH, C-4 STATUS^RTH, C-4 ^JOURNAL, 7-10 STOP^DDPLNK, 7-15 ^JRNLIS, 7-10 ^STU, 2-6, 2-33, 7-18, LINK^DDPLNK, 7-15 B-6 ^LKMSTA, 7-17 ^%SY, 7-18 ^LOCKTAB, 7-19 ^SYS, 7-4 ^LOGIN, 3-29, 7-18, 7-20 ^TIED, 3-24, 3-25, 7-18 Mapped Routines, 6-3, ^TIEDSTU, 3-24 7-15 ^UCIMAN, 7-13 MAPSET^RMSHO, 6-4, 6-12, ^VOLINH, 7-13 7-16 ^VOLMAN, 2-8, 7-13 MAP^%RD, 6-4, 6-12, 7-15 ^%VOLTAB, 7-13 ^MEMORY, 5-7, 7-18 Volume Set, 7-12 ^MEMREQ, 1-31, 5-7 SYSUAF.DAT file, 3-15 ^MEMUSE, 5-7, 5-21 setting up in a mixed MODIFY^CONDBS, 2-10, 7-12 architecture cluster, MODIFY^CONFIG, 7-5, 7-8 2-47 MODIFY^TTROU, 3-26 ^SYS Utility, 7-4 MONITOR^GLSSTA, 6-15 ^%SY Utility, 7-18 NOAIJ^BIJFORC, 7-11 NOBIJ^BIJFORC, 7-11 T__________________________ ^OPTBLD, 7-16, B-3 TCP/IP ^OPTCON, 7-16, B-5 with Visual M, 8-2 ^OPTMAN, 7-16, B-3 TCP/IP links OPT^STU, B-6 DDP, 2-27 Performance, 7-16 TCP/IP port PRINT^ACL, 3-20, 7-18 for Visual M, 2-16 RECORD^GLSSTA, 6-15 REPLAY^GLSSTA, 6-15 ^RMAP, 6-2, 6-3, 7-15 Index-17 TCP/IP TELNET User identification code with Caché/Weblink, 9-1 See UIC Tied application accounts, Using ^CONFIG to include 3-22 ^PMF support, 6-22 captive accounts, 3-23 Utilities captive command procedure ^CONFIG, 8-5 , 3-24 library, 7-1 establishing, 3-22 ^%PR, 8-4, 10-2 Tied routines START^MVB, 8-8 port tables, 3-25 ^STU, 8-4, 10-2 Tied Routine Table, 3-26 system, 7-1 Tied Routine Table ^UCIADD, 2-19 creating, 3-26 ^TIEDSTU Utility, 3-24 V__________________________ Tied terminals, 3-23 VBSS_ENABLE parameter captive accounts, 3-23 disabling, 1-6 captive command procedure VIEW command , 3-24 restricting access, 3-11 establishing, 3-22 $VIEW function ^TIED Utility, 3-24, 3-25, restricting access, 3-11 7-18 ViewPoint, 1-4 Time-sharing system Virtual memory access control, 3-2 requirements, 5-11 TMPMBX privilege, 1-28, Visual M, 8-1 3-16 client, 8-1 Transaction database set, implementing with ^CONFIG 2-10 , 2-15 information sources, 8-10 U__________________________ installing, 10-2 UAF, 3-15 installing TCP/IP, 8-3 ^UCIMAN Utility, 7-13 in ^CONFIG, 8-5 UIC loading server routines, file protection, 2-4, 3-5 8-4 User access namespaces, 8-8 controlling, 3-1 specifying TCP/IP port, User accounts 2-16 controlling access, 3-1 supported TCP/IP establishing, 3-15 implementations, 8-3 OpenVMS Authorize Utility TCP/IP communications, , 3-15 8-2 OpenVMS password, 3-4 Visual M remote server User authorization file ^%MVB, 8-3 See UAF starting, 8-8 Index-18 Visual M security, 8-10 ^BACKUP, 7-12 Visual M server Database Repair, 7-12 MVBSTART.LOG file, 8-8 ^%GLOMAN, 7-13 starting, 8-8 ^UCIMAN, 7-13 stopping, 8-8 ^VOLINH, 7-13 Visual M Server ^VOLMAN, 7-13 customizing, 8-9 ^%VOLTAB, 7-13 Visual M Server Manager, ^VOLUTL Utility, 7-12 8-9, 8-10 VMScluster environment W__________________________ ^ACLSET Utility, 3-19 World Wide Web server adding nodes, 2-44 as an Caché Weblink changes to installing, client, 9-1 1-16 Write Demon defining configurations, counting as a user, 2-14 2-45 log file, 2-49 directory structure, 2-43 page file considerations, enabling DDP, 2-45 5-15 heterogeneous, 2-46 process, 2-49 initializing DSM in, 2-42 WSDEFAULT process quota, installing DSM in, 1-15, 5-2 1-38 WSEXTENT process quota, shared image, 1-38 5-3 VMSINSTAL WSMAX parameter, 5-4 console output, D-1 WSQUOTA process quota, 5-3 installing DSM, 1-7 ^VOLINH Utility, 7-13 Z ^VOLMAN Utility, 2-8, 7-13 ___________________________ ^%VOLTAB Utility, 7-13 ZESCAPE command Volume set aliasing restricting access, 3-12 with ^CONFIG, 2-30 ZUSE command Volume sets OPER privilege, 1-28 initializing, 2-8 Volume Set Utilities Index-19