VAX DSM Installation and Management Guide AA-HM24F-TE July 1990 This document describes how to install and manage VAX DSM systems (Digital Standard MUMPS systems layered on the VMS operating system). It is intended for VAX DSM managers, operations personnel, and systems programmers with knowledge of the VMS operating system. Revision/Update Information: This is a revised document. Operating System and Version: VMS Version 5.2 and higher Software Version: VAX DSM Version 6.0 Digital Equipment Corporation Maynard, Massachusetts Digital Confidential ii The information this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. Any software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software or equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1986, 1987, 1988, 1989 All Rights Reserved. Printed in U.S.A. The Reader's Comments form at the end of this document requests your critical evaluation to assist in preparing future documenta- tion. The following are trademarks of Digital Equipment Corporation: CI DEQNA VAX DOCUMENT VAX DSM DASL DSM-11 RA81 VAX RMS DDCMP EDT RA82 VAX Volume Shadowing DEC HSC TK50 VMS DECnet MicroVAX VAX VT II DECnet-VAX Packetnet VAXcluster DELUA RA60 PDP-11 DIGITAL MUMPS is a registered trademark of Massachusetts General Hospital. This document was prepared using VAX DOCUMENT, Version 1.2. Digital Confidential Chapter 1 Installing VAX DSM This chapter provides information on the VAX DSM distribution kit and the software installation procedure which is used by sites that have never previously installed VAX DSM. Read the information in this chapter before you do a new installation of VAX DSM Version 6.0. This chapter does not describe procedures used to upgrade previous versions of VAX DSM. If you are upgrading from VAX DSM 5.0, 5.1, or 5.2, follow the instructions in Chapter 2 of the VAX DSM Version 6.0 Release Notes. For more information about the VMS operating system, see the Introduction to VMS System Management and the Guide to Setting Up a VMS System. Required Operating System Components You can install VAX DSM Version 6.0 on systems running VMS Version 5.2 or higher. For information on VMS Tailoring Classes, please refer to the Software Support Addendum (SSA). Installing VAX DSM 1-1 VAX DSM Distribution Kit The VAX DSM distribution kit consists of software and documenta- tion. Digital distributes the VAX DSM software on the following media: o Magnetic Tape o TK50 Tape Cartridge 1-2 Installing VAX DSM The VAX 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 In addition to this manual, the documentation for VAX DSM Version 6.0 consists of: o Introduction to DSM This document introduces the common syntax and language elements of DSM-11 (Digital Standard MUMPS on the PDP-11 computer) and VAX DSM (Digital Standard MUMPS layered on the VMS operating system). o VAX DSM Callable Routines Reference Manual This document describes the callback interface, which allows routines written in software languages that run layered on the VMS operating system to access a subset of the functionality offered by VAX DSM. o VAX DSM Database Operations Guide This document describes how to maintain the integrity and reliability of the VAX DSM database. It also describes transaction processing. o VAX DSM Language Pocket Reference This document summarizes VAX DSM language elements, the DSM command syntax, and I/O options. o VAX DSM Language Reference Manual Installing VAX DSM 1-3 This document describes the syntax and elements of the VAX DSM language. o VAX DSM Programmer's Guide This document describes how to use the programming capabilities of VAX DSM. 1-4 Installing VAX DSM o VAX DSM Version 6.0 Master Index This document contains index entries for manuals in the VAX DSM documentation set (excluding DASL manuals). o VAX DSM Version 6.0 Release Notes This document contains new features, enhancements, and upgrade information for Version 6.0 of VAX DSM. o DASL Handbook This document, for first-time users of DASL applications, describes how to use applications that were created with the DASL software. It also describes how to use the application environment options such as the Report Directory, the Message Center, and the Query Database Menu. o DASL Management Guide This document provides information on DASL system management tasks such as setting up your terminal, initializing the DASL software, and performing database conversions. o DASL Pocket Reference This document provides a summary of DASL commands and input conventions. o DASL Programmer's Guide This document introduces the DSM Application Software Library (DASL) and explains how to create a simple application using DASL. o DASL Reference Manual This document describes the six major modules of the DASL software and provides related reference material, including the syntax and elements of DASL commands. Installing VAX DSM 1-5 o DASL Version 6.0 Master Index This document contains index entries for manuals in the DASL documentation set. 1-6 Installing VAX DSM Space and Time Requirements for Installing VAX DSM To install and use VAX DSM, you must have enough space on your system disk. Table 1-1 shows the amount of space required for installing VAX DSM. Table 1-1 Space Requirements for Installing VAX DSM __________________________________________________________________ ______________________________With_DASL_________Without_DASL______ Peak Installation Utilization 24,400 blocks 15,250 blocks Net_Utilization_______________24,400_blocks_____14,000_blocks_____ Actual disk space utilization depends on the requirements of your particular system environment. On a MicroVAX II system, it takes approximately 15 minutes to install VAX DSM. Installation Overview This section provides an outline of how to install, initialize, and start up VAX DSM Version 6.0. The installation and startup procedure describes how to set up a new installation and assumes that there is no previous release of VAX DSM installed on your VMS system. Note: You must be running VMS Version 5.2 or higher to install VAX DSM Version 6.0. The remainder of this chapter describes the following procedures in detail: Installing VAX DSM 1-7 o VAX DSM software kit installation activities - Back up your system. - Register your VAX DSM license. - Install the VAX DSM distribution kit onto your VMS system using the SYS$UPDATE:VMSINSTAL.COM procedure. - Install the VAX DSM images as shared images using the SYS$STARTUP:DSM$INSTALL.COM procedure. o Postinstallation activities - Use the SYS$MANAGER:DSM$INIT.COM procedure to create a VAX DSM environment manager's account for use with VAX DSM. - Edit the VMS system files to provide for automatic startup and shutdown of VAX DSM configurations when your system is rebooted. - Log in to the VAX DSM environment manager's account and run the SYS$MANAGER:DSM$CONFIGURE.COM procedure to initialize VAX DSM database volume sets and configurations. VAX DSM Installation This section provides detailed instructions for installing the VAX DSM Version 6.0 software kit on your VMS system. Backing Up Your System Digital 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 VMS Backup Utility Manual in the VMS documentation set. 1-8 Installing VAX DSM Registering Your VAX DSM License To run VAX DSM Version 6.0, you must register your software license by using the VMS License Management Facility (LMF). The license registration information you need is contained in the Product Authorization Key (PAK) that is shipped with VAX DSM. The PAK is a paper certificate that includes the data needed to authorize access to VAX DSM on your system. The VMSINSTAL installation procedure asks if you have regis- tered and loaded the DSM license. The VAX DSM kit includes an Installation Verification Procedure (IVP) that verifies if VAX DSM is installed correctly. You must register and load your DSM license before you start the installation in order to run the IVP during the installation. If you choose not to register and load your license, you can install DSM, but the IVP does not run. To register a license, log in to the VMS system manager's account. Do one of the following to register the VAX DSM license: o Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When it prompts you for information, enter the data from your PAK. o Type the DCL LICENSE REGISTER command with the appropriate qualifiers that correspond to information on the PAK. After you register the license, you must load the license to activate it. Enter the following to load the license: $ LICENSE LOAD DSM See the VMS License Management Utility Manual for additional information on using LMF, or type HELP LICENSE at the DCL prompt. Installing VAX DSM 1-9 SYSGEN Requirements for Installation During the VAX DSM installation procedure, system resources are checked to ensure that sufficient free GBLPAGES, GBLPAGFIL, and GBLSECTIONS exist in order to install the DSM image as a shared image file. If system resources are not sufficient, the installation procedure terminates and notifies you. To successfully install VAX DSM, you must have the following system resources available: o GBLPAGES You need at least 600 global page table entries available. o GBLSECTIONS You need at least 10 global section descriptors available. 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 The F$GETSYI lexical function displays the number of free global pages and free global sections that are available on your system. If the installation procedure fails because these SYSGEN values are too low, you have to modify the system parameters, reboot your VMS system, and restart the installation procedure. When adjusting system parameters, add at least 600 to the current value of GBLPAGES and at least 10 to the current value of GBLSECTIONS. To do this, examine the current system values using the SYSGEN Utility: 1-10 Installing VAX DSM $ RUN SYS$SYSTEM:SYSGEN SYSGEN> SHOW GBLSECTIONS Parameter Name Current Default Minimum Maximum Unit Dynamic -------------- ------- ------- ------- ------- ---- ------- GBLSECTIONS 250 250 20 4095 Sections SYSGEN> SHOW GBLPAGES Parameter Name Current Default Minimum Maximum Unit Dynamic -------------- ------- ------- ------- ------- ---- ------- GBLPAGES 20000 10000 512 -1 Pages SYSGEN>EXIT Then, add the minimum values required by VAX DSM to the current values and place the new values in the SYS$SYSTEM:MODPARAMS.DAT. For example, the current values from the previous example are adjusted in MODPARAMS.DAT using the following commands: GBLSECTIONS = 250+10 ! 10 additional sections required by VAX DSM GBLPAGES = 20000+600 ! 600 additional pages required by VAX DSM Now 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 modifications and reboots your system. When the system reboots, you can rerun the software kit installation described in the next section. Note that, when you create new VAX DSM configurations, you may also need additional GBLPAGES and GBLSECTIONS. See Chapter 3 for more information on determining appropriate values for these SYSGEN parameters and others. Installing VAX DSM 1-11 Installing VAX DSM Using VMSINSTAL The following is an example VMSINSTAL procedure used to install VAX DSM Version 6.0: 1. To begin the installation procedure, log in to your VMS system account and enter the following command line: $ @SYS$UPDATE:VMSINSTAL 2. VMSINSTAL displays the following on the terminal: VAX/VMS Software Product Installation Procedure V5.2 It is 16-OCT-1990 at 09:23. Enter a question mark (?) at any time for help. Note: You can print a copy of the release notes using the OPTIONS N parameter when you enter the VMSINSTAL command line. For example: $ @SYS$UPDATE:VMSINSTAL OPTIONS N 3. VMSINSTAL then asks the following questions: * Are you satisfied with the backup of your system disk [YES]? * Where will the distribution volumes be mounted: MUA0: This sample installation procedure uses magnetic tape device MUA0. Enter the appropriate device mnemonic for your distribution medium at the prompt, and follow the procedures for mounting your distribution medium. 4. VMSINSTAL continues by displaying a prompt asking for the products you want to install from the first distribution volume set. 1-12 Installing VAX DSM Type DSM after the following prompt and press Return: * Products: DSM If you did not specify OPTIONS N on the DCL command line, you can print a copy of the release notes by typing N after the Options prompt. * Enter installation options you wish to use (none): N 5. The following prompts tell you to mount the first volume of the set and ask when you are ready. Type YES after the prompt and press Return. VMSINSTAL displays a message when the volume set is mounted: Please mount the first volume of the set on MUA0: *Are you ready? YES %MOUNT-I-MOUNTED, DSM mounted on MUA0: 6. VMSINSTAL displays the following on the terminal: The following products will be processed: DSM V6.0 Beginning installation of DSM V6.0 at 09:24 %VMSINSTAL-I-RESTORE, Restoring product save set A ... If you typed an N after the prompt for installation options, VMSINSTAL displays the following: Release Notes Options: 1. Display release notes 2. Print release notes 3. Both 1 and 2 4. Copy release notes to SYS$HELP 5. Do not display, print or copy release notes Installing VAX DSM 1-13 * Select option [2]: * Queue name [SYS$PRINT]: Job DSM060 (queue SYS$PRINT, entry 25) started on SYS$PRINT * Do you want to continue the installation? Y Select the appropriate responses. 7. VMSINSTAL displays the following: %VMSINSTAL-I-RELMOVED, The products release notes have been successfully moved to SYS$HELP. 8. The following question asks if you have an authorization key registered and loaded. If you have an authorization key loaded, answer Y. If you do not have a key registered, answer N. If you answer N, you cannot run the IVP procedure. Product: DSM Producer: DEC Version: 6.0 Release Date: 15-JAN-1990 *Does this product have an authorization key registered and loaded?Y 9. The VAX DSM kit includes an Installation Verification Procedure (IVP) called SYS$TEST:DSM$IVP.COM. VMSINSTAL optionally runs the IVP to verify that VAX DSM has been installed correctly. You can also run the IVP after running VMSINSTAL by entering @SYS$TEST:DSM$IVP at the DCL prompt. If you do not have a PAK loaded, VMSINSTAL will not run the IVP during the installation. * Do you want to run the IVP after the installation [YES]? 10.VMSINSTAL asks if you want to install the DSM Application Software Library (DASL) files with the following prompt: * Do you want to include DASL files [YES]? 1-14 Installing VAX DSM The default response to the prompt is YES. Press Return if you want to include DASL files; type N if you do not want to include DASL files. 11.VMSINSTAL continues the VAX DSM Version 6.0 installation procedure by displaying the following prompt: *Do you want to purge files replaced by this installation[YES]? The default response to this prompt is YES. Answer YES in response to this prompt to purge all previous VAX DSM files that VMSINSTAL replaces with new VAX DSM files. Allowing the previous VAX DSM files to remain on disk takes up valuable disk space that you may need. 12.VMSINSTAL prints the following informational message: No further questions will be asked during this installation 13.VMSINSTAL continues the installation procedure by copying the VAX DSM Version 6.0 images, utilities, globals and supporting DCL command procedures. If you answer YES to installing DASL, VMSINSTAL creates DASL files in SYS$LIBRARY. VMSINSTAL displays informational messages on your terminal during each phase of this part of the installation procedure. %VMSINSTAL-I-RESTORE, Restoring product save set B ... The following files will be created or updated . . . %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... 14.VMSINSTAL moves all of the VAX DSM Version 6.0 files to their appropriate directories and then executes the VAX DSM IVP. Installing VAX DSM 1-15 If the installation is successful, VMSINSTAL displays the following informational messages: Calling VAX DSM Installation Verification Procedure VAX DSM V6.0 SYSTEM [Baseline] VAX DSM V6.0 IVP Successful %DSM-I-HALT command executed VAX DSM installation is complete. You may enter the following command line to initialize a manager account for use with VAX DSM: @SYS$MANAGER:DSM$INIT Installation of DSM V6.0 completed at 9:37 If the installation fails for any reason, VMSINSTAL displays an appropriate informational message. See VMS System Messages and Recovery Procedures: Part I and Part II for information on installation failure messages. Take action based on the informational message. 15.VMSINSTAL prompts for additional software products to install: * Products : EXIT VMSINSTAL procedure done at 09:37 Enter another product to install from the next distribution volume set, or enter a ? for help. To exit the routine, press Ctrl/z, or type EXIT and press Return. 1-16 Installing VAX DSM The VAX DSM software kit installation procedure is now complete. During the installation process the DSM060.RELEASE_NOTES are moved to the SYS$HELP directory. You can type or print these files to obtain the latest information about VAX DSM Version 6.0. VMSINSTAL Procedure Example 1-1 shows the console output of the VMSINSTAL procedure. Example 1-1 VMSINSTAL Console Output $ SET DEF SYS$UPDATE $ @VMSINSTAL It is 16-FEB-1990 at 09:23. 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: MUA0: Enter the products to be processed from the first distribution volume set. * Products: DSM * Enter installation options you wish to use (none): The following products will be processed: DSM V6.0 Beginning installation of DSM V6.0 at 09:24 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED , The product's release notes have been successfully moved to SYS$HELP. Example 1-1 Cont'd on next page Installing VAX DSM 1-17 Example 1-1 (Cont.) VMSINSTAL Console Output Product: DSM Producer: DEC Version: 6.0 Release Date: 15-JAN-1990 * Does this product have an authorization key registered and loaded? Y * Do you want to run the IVP after the installation [YES]? * Do you want to include DASL files [YES]? * Do you want to purge files replaced by this installation [YES]? No further questions will be asked during this installation %VMSINSTAL-I-RESTORE, Restoring product save set B ... The following files will be created or updated directory [SYSEXE] DSM.EXE - VAX DSM main image DSMDDPDRV.EXE - VAX DSM DDP driver directory [SYSLIB] Example 1-1 Cont'd on next page 1-18 Installing VAX DSM Example 1-1 (Cont.) VMSINSTAL Console Output DSM$SHARE.EXE - VAX DSM shareable image DSM$SHARE.STB - Symbol table for DSM$SHARE.EXE DSM$MT_EBCASC.EXE - VAX DSM EBCDIC/ASCII translation tables DSM$MT_EBCASC.MAR - Source file of DSM EBCDIC/ASCII conversion table DSM$ZCALL.EXE - VAX DSM ZCALL package table DSM$ZCMACRO.MLB - Macro library for user written ZCALL packages DSM$CALLDEF.ADA - Definition file for callable routines DSM$CALLDEF.BAS - Definition file for callable routines DSM$CALLDEF.FOR - Definition file for callable routines DSM$CALLDEF.H - Definition file for callable routines DSM$CALLDEF.MAR - Definition file for callable routines DSM$CALLDEF.PAS - Definition file for callable routines DSM$CALLDEF.PLI - Definition file for callable routines DSM$CALLDEF.R32 - Definition file for callable routines DSM$CALL.OPT - Linker option file for callable routines 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 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 directory [SYSMGR] Example 1-1 Cont'd on next page Installing VAX DSM 1-19 Example 1-1 (Cont.) VMSINSTAL Console Output DSM$INIT.COM - Command procedure to initialize a DSM account DSM$CONFIGURE.COM - Command procedure to create a DSM configuration DSM$VOLUPG.COM - Command procedure to upgrade a volume set DSM$SHUTDOWN.COM - Command procedure to shutdown 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 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 procedure to start a DSM environment DSM$INSTALL.COM - Command file to install VAX DSM at VMS boot time directory [SYSHLP] HELPLIB.LIB - add/update VAX DSM help text DSM060.RELEASE_NOTES - VAX DSM Version 6.0 Release Notes directory [SYSHLP.EXAMPLES] DSM$ADBOOK.PAS - Example of using the callable routines DSM$GLISTP.PAS - Example of using the callable routines DSM$ZCALL_USER_TABLE.MAR - Template source file for USER ZCALL table DSM$ZCALL_EXAMPLE_TABLE.MAR - Example ZCALL Table Source file DSM$ZCALL_EXAMPLE_PKTAB.MAR - Example ZCALL Package Table Source file DSM$ZCALL_EXAMPLE_CODE.MAR - Example user-written ZCALL procedures DSM$ZCALL_EXAMPLE_BUILD.COM - Example user-written ZCALL build procedure Example 1-1 Cont'd on next page 1-20 Installing VAX DSM Example 1-1 (Cont.) VMSINSTAL Console Output directory [SYSTEST] DSM$IVP.COM - Residual Installation Verification Procedure The following DASL files will be created in [SYSLIB] DSM$DASL_ROUTINES.SAV DSM$DASL_GLOBALS.SAV DSM$DASL_DEMO.SAV DSM$DASL_PRTD.ROV DSM$DASL_PRTF.GLO %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Calling VAX DSM Installation Verification Procedure VAX DSM V6.0 SYSTEM [Baseline] VAX DSM V6.0 IVP Successful %DSM-I-HALT, HALT command executed VAX DSM installation is complete. You may enter the following command line to initialize a manager account for use with VAX DSM: @SYS$MANAGER:DSM$INIT Installation of DSM V6.0 completed at 09:37 Enter the products to be processed from the next distribution volume set. * Products: EXIT Example 1-1 Cont'd on next page Installing VAX DSM 1-21 Example 1-1 (Cont.) VMSINSTAL Console Output VMSINSTAL procedure done at 09:37 VAX DSM Shareable Images VAX DSM is implemented as one main image and several VMS shareable images. VMS shareable images allow multiple programs to call the same image. This organization reduces memory utilization and increases system performance. The relationship of the various images included with VAX DSM is described in Figure 1-1. o DSM.EXE DSM.EXE is the main entry routine for all programmer and application users of VAX DSM. It accepts the DSM command line qualifier and then calls the DSM$SHARE image to process the qualifier and initiate access to VAX DSM. o DSM$SHARE.EXE DSM$SHARE.EXE is the shareable, position-independent, image that supplies the entry points for the callable interface. A majority of the code that supports VAX DSM capabilities resides within this image. External programs that interface to VAX DSM link against this image. The DSM.EXE image is an example of an external program that calls VAX DSM through the callable interface located in DSM$SHARE.EXE. o DSM$MESSAGE.EXE DSM$MESSAGE.EXE holds the VAX DSM error message text. VAX DSM Version 6.0 includes the message text as a separate image so that external callable interface programs can have access to VAX DSM error messages. o DSM$MT_EBCASC.EXE 1-22 Installing VAX DSM DSM$MT_EBCASC.EXE holds the VAX DSM ASCII/EBCDIC conversion tables that are used by the VAX DSM magnetic tape handler for reading and writing IBM formatted magnetic tapes. You can create a customized ASCII/EBCDIC conversion table to meet your site requirements. Installing VAX DSM 1-23 o DSM$ZCALL.EXE DSM$ZCALL.EXE is the ZCALL package table image. This image describes the existence of all user written $ZCALL packages. Installing VAX DSM as Shared Images The supplied VAX DSM images must be installed as VMS shared images in order to run VAX DSM. This is accomplished using the VMS Install Utility. 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 install all of the VAX DSM images, as shared images. This reduces memory utilization, enhances VAX DSM image activation time, and applies required image privileges. Use the SYS$STARTUP:DSM$INSTALL.COM procedure to install the VAX DSM images as a shared images by logging in to a privileged VMS account that has the VMS CMKRNL privilege. Run the DSM$INSTALL command procedure by entering the following command: $ @SYS$STARTUP:DSM$INSTALL Installing VAX DSM in a VAXcluster Environment If you are installing VAX DSM on a node in a VAXcluster environ- ment, you must log in to the VMS system manager's account on each node that will be running VAX DSM and do the following: 1. Load the VAX DSM Product Authorization Key (PAK) by entering the following: $ LICENSE LOAD DSM See the VMS License Management Utility Manual for additional information on using LMF, or type HELP LICENSE at the DCL prompt. 1-24 Installing VAX DSM 2. Install VAX DSM as a shared image by entering the following: $ @SYS$STARTUP:DSM$INSTALL Installation of the VAX 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 VAXcluster nodes, you have to 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 "SYSGEN Requirements for Installation." You can also use the VMS System Management Utility (SYSMAN) to perform these steps from your local node by defining your management environment to be a particular node, a group of nodes, or a cluster. See the VMS SYSMAN Utility Manual for more information. Postinstallation Activities Once VAX DSM installation is complete, you can create one or more VAX DSM environment manager accounts for use with VAX DSM configurations. The configuration completely controls access to global databases, DSM routines, and other VAX DSM capabilities. This section provides detailed instructions for all activities required to create a VAX DSM environment and initialize a VMS account as a VAX DSM environment manager's account for use with VAX DSM. Procedures for creating and starting a VAX DSM configuration are also briefly described. See Chapter 2 for complete information about VAX DSM configurations. Installing VAX DSM 1-25 VAX DSM Environment Manager's Account To define and manage the VAX DSM environment for development and applications, the VAX DSM manager must have a VMS account. Using this account, the VAX DSM manager can perform such tasks as the following: o Creating and extending VAX DSM volumes o Creating and editing VAX DSM configurations o Managing UCIs, globals, and routines on VAX DSM volume sets o Starting up and shutting down VAX DSM configurations interac- tively Creating the VAX DSM Environment Manager's Account You use the SYS$MANAGER:DSM$INIT.COM command procedure to prepare a VMS account for use as a VAX DSM environment manager account. To do this: 1. Log in to a privileged system account. 2. Run the DSM$INIT command procedure. Enter the following: $ @SYS$MANAGER:DSM$INIT The DSM$INIT command procedure allows you to create a new VMS account for use as a VAX DSM environment manager account. You can also use DSM$INIT to designate an existing VMS account as a VAX DSM environment manager account. 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 VAX DSM manager account you want to create. 1-26 Installing VAX DSM o Creates default directories to hold volume sets and journal files (Before-Image and After-Image Journaling 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 VAX DSM configurations - Create a DSM manager rights identifier and grant it to the account - Apply Access Control Lists (ACLs) to all directories and files created When the account initialization command procedure is completely created, DSM$INIT displays the procedure on your terminal. You can then optionally 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 manager account being created If you choose to run the initialization command procedure, all of the operations that are displayed are performed. When the initialization procedure completes successfully, DSM$INIT takes the following actions: o It creates a unique environment. Installing VAX DSM 1-27 o It creates an entry in the ^DSMMGR system global describing the manager account for the newly initialized environment. o It creates the ^SYS global in the directory you designated as the VAX DSM environment root directory. The ^SYS global is an RMS ISAM-based global that is used by DSM utilities to define and start VAX DSM configurations. o Creates the ^DSMACC global in the VAX DSM environment root directory. The ^DSMACC global is an RMS ISAM-based global used to store environment and DDP node access authorization information. Running DSM$INIT.COM Example 1-2 shows how to run the DSM$INIT.COM procedure to create a new VMS account and initialize it as a VAX DSM environment manager account. Note: You must be logged in to a privileged system account in order to run the DSM$INIT command procedure. Enter the following to run DSM$INIT: 1-28 Installing VAX DSM Example 1-2 Running the DSM$INIT Command Procedure $ @SYS$MANAGER:DSM$INIT VAX DSM 6.0 Environment Manager Initialization The VAX DSM environment manager must have a VMS account to define and control VAX DSM Configurations. This procedure allows you to create a new account or upgrade an existing VMS account as a VAX DSM environment manager. Enter the VMS account name to use with VAX DSM > The DSMMGR account does not currently exist Do you want to create and initialize this account [Y OR N] ? Each VMS 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 VAX 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 > Example 1-2 Cont'd on next page Installing VAX DSM 1-29 Example 1-2 (Cont.) Running the DSM$INIT Command Procedure Each VMS 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 VAX DSM environment manager's account: Enter the login device for this account >DISK$USER VAX DSM requires a VMS directory to store log files, routine map files, and RMS global and routine files to serve as the VAX DSM environment root directory. This directory also holds subdirectories which are default storage locations for VAX DSM volume sets and journal files. By default, the VAX DSM environment directories are created as a tree of directories whose root is separate from the manager's login directory. This default is chosen because the VAX DSM directories and associated files created by VAX DSM, use a VMS protection scheme which may not be compatible for general use. You can select any directory or device as the VAX DSM environment root directory. However, the root directory you specify must be a top level directory. Enter the directory to use for VAX DSM Example 1-2 Cont'd on next page 1-30 Installing VAX DSM Example 1-2 (Cont.) Running the DSM$INIT Command Procedure Use of VAX DSM in a VAXcluster environment requires the creation of a separate subdirectory for each cluster member. The subdirectories hold node-specific log files created by VAX DSM configurations running on each of the VAXcluster nodes. Appropriate subdirectories will be created as part of this initialization process. In order to do so, all cluster nodes must be identified at this time. The following VAXcluster nodes are currently booted and will be initialized for use with VAX 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 will create default directories to hold database and journal files associated with this environment. The default directories are created as subdirectories of the VAX DSM environment root directory. You may also want to create directories which are default storage locations for VAX DSM volume sets and journal file on other disk units in your system. You can optionally select to initialize these additional directories at this time. The following directories will always be created if they do not already exist: DISK$USER:[DSM$DSMMGR.DATABASE] DISK$USER:[DSM$DSMMGR.JOURNAL] Create similar directories on other disk devices [Y OR N] ?Y Example 1-2 Cont'd on next page Installing VAX DSM 1-31 Example 1-2 (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 VAX DSM manager's account and directories: ========================================================================== Example 1-2 Cont'd on next page 1-32 Installing VAX DSM Example 1-2 (Cont.) Running the DSM$INIT Command Procedure $ ! Command Procedure to Initialize DSMMGR $ ! for use as a VAX 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 the rights identifier for this environment" $ ! $ UAF ADD/IDENTIFIER/ATTRIBUTE=RESOURCE DSM$00001_MANAGER $ ! $ WRITE SYS$OUTPUT "Adding new Account for use as a VAX DSM environment manager . . ." $ ! $ ! Add account and set password lifetime to 365 days, preexpired $ ! $ UAF ADD DSMMGR/PASSWORD='P1/UIC=[250,500]/OWNER=VAXDSM - /DEVICE=DISK$USER:/DIR=[DSMMGR] - /PWDEXPIRED/PWDLIFETIME=365-00 $ ! $ UAF GRANT/IDENTIFIER/ATTRIBUTE=RESOURCE DSM$00001_MANAGER DSMMGR $ ! $ WRITE SYS$OUTPUT "Modifying Environment Manager Account Quotas . . ." $ UAF MODIFY DSMMGR/ENQLM=1000 MODIFY DSMMGR/BYTLM=40960 MODIFY DSMMGR/ASTLM=36 MODIFY DSMMGR/DIOLM=18 MODIFY DSMMGR/WSDEF=500 MODIFY DSMMGR/WSQUOTA=1000 MODIFY DSMMGR/WSEXTENT=1200 MODIFY DSMMGR/FILLM=150 MODIFY DSMMGR/PRIV=TMPMBX Installing VAX DSM 1-33 MODIFY DSMMGR/DEFPRIV=TMPMBX EXIT Example 1-2 Cont'd on next page Example 1-2 (Cont.) Running the DSM$INIT Command Procedure $ ! $ UAF SHO DSMMGR $ ! $ READ/PROMPT="VAX DSM manager's account initialized - press return to continue" SYS$COMMAND A $ ! $ WRITE SYS$OUTPUT "Creating Account directory . . ." $ ! $ CREATE/DIR/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) DISK$USER:[DSMMGR] $ ! $ WRITE SYS$OUTPUT "Creating VAX DSM environment root directory . . ." $ ! $ CREATE/DIR/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) DISK$USER:[DSM$DSMMGR] $ ! $ SET DIRECTORY DISK$USER:[DSM$DSMMGR]/ACL=(- (DEFAULT_PROTECTION,S:RWED,O:RWED,G,W),- (IDENTIFIER=DSM$00001_MANAGER,ACCESS=READ+WRITE+EXECUTE),- (IDENTIFIER=DSM$00001_MANAGER,OPTION=DEFAULT,- ACCESS=READ+WRITE+EXECUTE+DELETE)) $ ! $ WRITE SYS$OUTPUT "Creating default database/journal directories . . ." $ ! Example 1-2 Cont'd on next page 1-34 Installing VAX DSM Example 1-2 (Cont.) Running the DSM$INIT Command Procedure $ CREATE/DIR/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) DISK$DATA:[DSM$DSMMGR] $ SET DIRECTORY DISK$DATA:[DSM$DSMMGR]/ACL=(- (DEFAULT_PROTECTION,S:RWED,O:RWED,G,W),- (IDENTIFIER=DSM$00001_MANAGER,ACCESS=READ+WRITE+EXECUTE),- (IDENTIFIER=DSM$00001_MANAGER,OPTION=DEFAULT,- ACCESS=READ+WRITE+EXECUTE+DELETE)) $ ! $ CREATE/DIR/LOG/OWN=[250,500] DISK$DATA:[DSM$DSMMGR.DATABASE] $ CREATE/DIR/LOG/OWN=[250,500] DISK$DATA:[DSM$DSMMGR.JOURNAL] $ ! $ CREATE/DIR/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) DISK$USER:[DSM$DSMMGR] $ SET DIRECTORY DISK$USER:[DSM$DSMMGR]/ACL=(- (DEFAULT_PROTECTION,S:RWED,O:RWED,G,W),- (IDENTIFIER=DSM$00001_MANAGER,ACCESS=READ+WRITE+EXECUTE),- (IDENTIFIER=DSM$00001_MANAGER,OPTION=DEFAULT,- ACCESS=READ+WRITE+EXECUTE+DELETE)) $ ! $ CREATE/DIR/LOG/OWN=[250,500] DISK$USER:[DSM$DSMMGR.DATABASE] $ CREATE/DIR/LOG/OWN=[250,500] DISK$USER:[DSM$DSMMGR.JOURNAL] $ ! $ SET DEFAULT DISK$USER:[DSM$DSMMGR] $ CREATE/DIR/LOG/OWN=[250,500]/PROT=(S:RWE,O:RWE,G,W) [.DSM5] $ ! $ ERROR: $ EXIT ========================================================================== Do you want to edit this command procedure [Y OR N]? Example 1-2 Cont'd on next page Installing VAX DSM 1-35 Example 1-2 (Cont.) Running the DSM$INIT Command Procedure Type YES if you want to make modifications to this command procedure before it is run. The EDT editor is called to allow you to edit the file. Type NO if the command procedure is satisfactory. 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 Example 1-2 Cont'd on next page 1-36 Installing VAX DSM Example 1-2 (Cont.) Running the DSM$INIT Command Procedure Adding the rights identifier for this environment %UAF-I-RDBADDMSG, identifier DSM$00001_MANAGER value: %X80010005 added to rights data base Adding new Account for use as a VAX DSM environment manager . . . %UAF-I-ADDMSG, user record successfully added %UAF-I-RDBADDMSGU, identifier DSMMGR value: [000250,000500] added to rights data base %UAF-I-GRANTMSG, identifier DSM$00001_MANAGER granted to DSMMGR Modifying Environment Manager Account Quotas . . . %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-MDFYMSG, user record(s) updated %UAF-I-DONEMSG, system authorization file modified %UAF-I-RDBNOMODS, no modifications made to rights data base The updated account authorization record is now displayed. Example 1-2 Cont'd on next page Installing VAX DSM 1-37 Example 1-2 (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: 365 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 Identifier Value Attributes DSM$00001_MANAGER %X80010005 RESOURCE NODYNAMIC VAX DSM manager's account initialized - press return to continue Example 1-2 Cont'd on next page 1-38 Installing VAX DSM Example 1-2 (Cont.) Running the DSM$INIT Command Procedure Creating Account directory . . . %CREATE-I-CREATED, DISK$USER:[DSMMGR] created Creating VAX DSM environment root directory . . . %CREATE-I-CREATED, DISK$USER:[DSM$DSMMGR] created Creating default database/journal directories . . . %CREATE-I-CREATED, DISK$DATA:[DSM$DSMMGR] created %CREATE-I-CREATED, DISK$DATA:[DSM$DSMMGR.DATABASE] created %CREATE-I-CREATED, DISK$DATA:[DSM$DSMMGR.JOURNAL] created %CREATE-I-CREATED, DISK$USER:[DSM$DSMMGR] already exists %CREATE-I-CREATED, DISK$USER:[DSM$DSMMGR.DATABASE] created %CREATE-I-CREATED, DISK$USER:[DSM$DSMMGR.JOURNAL] created %CREATE-I-CREATED, DISK$USER:[DSM$DSMMGR.DSM5] created 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 VAX DSM manager's account and use the SYS$MANAGER:DSM$CONFIGURE.COM command procedure to initialize VAX DSM database volume sets, or create and start up VAX DSM configurations. See the "VAX DSM Installation and Management Guide" for complete information about VAX DSM database volume sets and configurations. Creation of the VMS account and its initialization as a VAX DSM manager account is now complete. If you are running within a Installing VAX DSM 1-39 VAXcluster environment, DSM$INIT initializes all nodes for use with VAX DSM in a single operation. The process quotas and privileges used to create the VAX DSM manager account in the previous example are generally good values for initial use. You may find that you want 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 3 carefully. They provides details on how you can establish the appropriate values for the VAX DSM manager's and user's accounts, as well as how to tailor VMS SYSGEN parameters for your site. See the VMS Authorize Utility Manual for details on the VMS Authorize Utility. The DSM$INIT command procedure grants only the VMS TMPMBX privilege during account creation. However, your site may require the OPER privilege. OPER is required to use the %OPCOM $ZCALL, the ZUSE MUMPS command, or operator REPLY/TO command for coordinating Journal Output File usage. Configuring VAX DSM Once the VAX DSM manager account is initialized, you can 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 VAX DSM databases and define VAX DSM configurations. Once you become more familiar with these techniques, you may choose to directly call standard VAX DSM utilities to manage your configurations. The DSM$CONFIGURE command procedure optionally allows you to: o Create a new VAX DSM database volume set. 1-40 Installing VAX DSM o Define a VAX DSM configuration. o Start a VAX DSM configuration in the newly initialized VMS account. To use DSM$CONFIGURE, log in to the VAX DSM environment manager account and enter the following: $ @SYS$MANAGER:DSM$CONFIGURE VAX DSM Configuration Management Procedure This procedure is intended to be used while logged in to a newly initialized VAX DSM manager account to configure and start DSM for the first time. It serves as an introduction to the techniques used to build VAX DSM database volume sets, create new DSM configuration definitions, and start a fully functional VAX DSM configuration. The following VAX DSM utilities are called: ^VOLMAN - creates new VAX DSM database volume sets ^CONFIG - builds VAX DSM configuration definitions ^STU - starts a VAX DSM configuration You can independently access any of these utilities at a later time to further modify the VAX DSM environment. See the VAX DSM Installation and Management Guide for complete information about database volume sets and DSM configurations. Do you want to create a new VAX DSM database Volume Set [Y OR N] ? . . . You can elect to build a VAX DSM database volume set at this time. If you want to create a new volume set answer YES. Chapter 4 contains complete information on VAX DSM volume sets and the procedure used here to create new volume sets. Installing VAX DSM 1-41 Do you want to create and start a VAX DSM configuration [Y or N] ? . . . If you want to create a VAX DSM configuration and start a fully functional VAX DSM environment, answer YES. See Chapter 2 for complete information on VAX DSM configurations and the procedure used here to create a configuration. Once you create the startup configuration, you can start VAX DSM. The startup procedure establishes all processes necessary for your VAX DSM system environment. See Chapter 2 for information about these processes. If VAX DSM startup fails, an explanatory message is displayed on your terminal. Initialization failure is often due to improper VMS SYSGEN parameters such as global page quota, or improper VAX DSM 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 3. The appropriate values for these parameters differ depending 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, reboot VMS before attempting to restart your VAX DSM configuration. Note: If you intend to use VAX DSM on multiple nodes of a cluster, you must define a node-specific configuration for each VAXcluster node and start the configuration on the target node. See the section "Initializing VAX DSM in a VAXcluster Environment" in Chapter 2 and see the VAX DSM Database Operations Guide for more information on running VAX DSM in a VAXcluster environment. 1-42 Installing VAX DSM Editing the VMS System Files You need to edit the VMS system startup and shutdown files to provide for automatic startup and shutdown of VAX DSM configurations when your system is rebooted. The following sections describe the procedures for system startup and shutdown. System Startup The SYS$STARTUP:DSM$INSTALL.COM procedure is supplied as a template for use at VMS boot time to initialize VAX DSM. This procedure has examples of a number of activities that many sites need to do to enable VAX DSM capabilities. These activities include: o Installing DSM images as shared o Allocating physical pages for disk buffer usage o Loading the VAX DSM DDP driver o Creating a batch queue for DSM startup o Starting up predefined VAX DSM configurations The only activity initially enabled with the procedure provided is the installation of DSM images as shared. Examples of how to accomplish the remaining activities are provided, but the actual DCL commands used are disabled by preceding each command line with a comment character (!). The procedure has a detailed description of how to customize DSM$INSTALL for your site and enable the relevant capabilities. Once you have edited DSM$INSTALL, edit the VMS system startup command procedure, SYS$STARTUP:SYSTARTUP_ V5.COM, to include the following command: $ @SYS$STARTUP:DSM$INSTALL Installing VAX DSM 1-43 System Shutdown The SYS$MANAGER:DSM$SHUTDOWN.COM procedure shuts down a VAX 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 VAX DSM configurations when your VMS 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 VAX DSM environment manager's account Include the previous command line in the SYS$MANAGER:SYSHUTDWN.COM procedure for each VAX DSM environment that is initialized. This ensures that any active VAX DSM volumes are dismounted in an orderly fashion before VMS shuts down. Note: If you fail to include @SYS$MANAGER:DSM$SHUTDOWN.COM in your system shutdown command file for each VAX DSM environment, database degradation may result. 1-44 Installing VAX DSM Chapter 2 Managing VAX DSM This chapter provides VAX DSM managers with information about managing a VAX DSM system. It is assumed that you have already initialized a VMS environment for use with VAX DSM by following the procedures in Chapter 1. This chapter presents an overview of a VAX DSM environment and detailed information about VAX DSM configurations. It explains how to: o Create a new VAX DSM configuration. o Start up and shut down a VAX DSM configuration. o Establish accounts for VAX DSM programmers and applications users. o Control user access to VAX DSM and to application environments. Chapter 6 contains information about optimizing the performance of VAX DSM. Experienced DSM programmers can find information to improve system performance in the VAX DSM Programmer's Guide. Managing VAX DSM 2-1 Chapter 3 describes how to tune VMS for use with VAX DSM. For background information on VAX DSM volume sets, read Chapter 4 of this manual. For detailed information about volume sets and database integrity, see the VAX DSM Database Operations Guide. For additional information about VMS system management, see the Introduction to VMS System Management and the Guide to Setting Up | a VMS System. | | | VAX DSM Environments | | A VAX DSM environment is the working area used by a VAX DSM | manager for the purposes of enabling and controlling the | operations of VAX DSM. The initialization of an environment | configures the following resources to support VAX DSM management: | | o VMS account | | The VAX DSM manager's VMS account provides a secure operational | account from which the manager can control DSM. Account | quotas are propagated to the various supporting VAX DSM system | processes when VAX DSM is fully configured. | | o VAX DSM directories | | VAX DSM default directories are created to hold log files, | database files, journal files, and RMS globals. | | By default, the VAX DSM environment directories are created as | a tree of directories whose root is separate from the manager's | login directory. This default is chosen because the directories | and associated files created by VAX DSM use a VMS protection | scheme that controls access to the various database and journal | files. This scheme may not be compatible for general use. | | In a VAXcluster environment, a separate subdirectory is created | for each member of the cluster. The subdirectories are used | to hold node specific log files generated by VAX DSM system | processes running on each of the nodes. 2-2 Managing VAX DSM | o Environment configuration global | | The environment configuration global is an RMS based global | named ^SYS (SYS.GBL), which resides in the environment root | directory. The ^SYS global holds the complete database of VAX | DSM configurations that the VAX DSM manager has defined for | the environment. A configuration describes the various enabled | VAX DSM capabilities, available databases, and other parameters | relevant to a fully operational VAX DSM environment. After | initialization, ^SYS is generally empty. | | o Configuration access global | | The configuration access global is an RMS global named ^DSMACC | (DSMACC.GBL), which resides in the environment root directory. | The ^DSMACC global holds the database of VMS accounts that are | authorized to access VAX DSM configurations running in this | environment. After initialization, ^DSMACC is generally empty. | | The remainder of this section provides an overview of VAX DSM | environments and defines VAX DSM terms used to describe the | various modes of access available when you use VAX DSM. VAX DSM Baseline Mode Once a VAX DSM environment has been initialized for use, you can log in to the VAX DSM environment manager's account and use VAX 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. VAX DSM displays the following banner: Managing VAX DSM 2-3 VAX DSM V6.0 DSMMGR [Baseline] > The [Baseline] access mode specifier indicates that there is no configuration running. In baseline mode, VAX DSM offers only minimal services, and its primary function is intended for use in running VAX DSM utilities. Baseline access has the following characteristics: o All VAX 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, DDP, and other advanced capabilities are not available. In baseline mode, global and routine access is limited to utility globals and routine directories that are supplied by the VAX DSM installation procedure. VAX DSM managers use baseline mode for management activities such as: o Creating VAX DSM volume sets o Defining VAX DSM configurations o Starting defined VAX DSM configurations 2-4 Managing VAX DSM VAX DSM Configurations A VAX DSM configuration is a database that describes the enabled VAX DSM operational capabilities and characteristics of an environment. A configuration definition specifies the following: o How many disk buffers are available for global data caching o Which DSM database sets are mounted, and if the following are true: - Cluster-mounting is enabled. - Before-Image Journaling is enabled. - After-Image Journaling is enabled. o Which global references are translated. o Which mapped routines are installed. o Whether Distributed Data Processing (DDP) is enabled. o What the default values of the DSM command line qualifiers are. As the VAX DSM manager, use the Create Configuration Utility (^CONFIG) while logged in to the baseline system to name and define the capabilities of a configuration. Once a configuration definition is complete, the configuration is started using the Configuration Startup Utility (^STU). Configurations can only be started while logged in to a VAX DSM environment manager account. A configuration is considered running when all the defined configuration capabilities are available to VAX DSM environment users. A running VAX DSM configuration includes a set of shared data structures and detached VAX DSM system processes that provide highly efficient access to global databases. The configuration establishes all capabilities available to DSM users. Managing VAX DSM 2-5 When a VAX DSM system is running, programmers and application users can log in to it from various VMS accounts. Users can accept the defaults established by the configuration, or can override some of the defaults through qualifiers on the DSM command. A configuration is considered shutdown when only the baseline capabilities are available. If a programmer or application user tries to run VAX DSM without the /MANAGER command line qualifier when no configuration is running, the user cannot access DSM. The system displays the following error message: %DSM-E-NOTRUN A VAX DSM configuration is not running VAX DSM Accounts | You can establish any number of VMS user accounts in order to | provide access to a running configuration. There are three types | of accounts that can be initialized for use with VAX DSM: | | o VAX DSM environment manager's account | | Only a person logged in to this account can start up and | shut down VAX DSM, create or extend volume sets, or perform | the other management tasks described in this chapter. The | DSM$INIT.COM procedure creates the VAX DSM environment | manager's account. | | o VAX DSM programmer accounts | | These accounts are for the interactive users who develop VAX | DSM routines. | | o VAX DSM application user accounts 2-6 Managing VAX DSM | These accounts are for users executing only particular VAX DSM | routines under controlled conditions. The VAX DSM manager sets | up these accounts so that application users are tied to the | DSM application and can not interact directly with the VAX DSM | interpreter. | | The section "Establishing User Accounts" later in this chapter | describes how to set up the programmer and application user | accounts. Overview of VAX DSM Databases VAX 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 VMS files that hold DSM globals and routines. o After-Image Journal files After-image Journal files are used to keep an audit trail of modifications made to globals within a running configuration. o Before-Image Journal files The Before-Image Journal Output 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 that are caused by a global kill operation. Before defining VAX DSM configurations, you initialize VAX DSM volume sets using the ^VOLMAN Utility. This operation preallocates VMS files and places them on system disk units in the various VAX DSM directories you created during environment initialization. Volume sets can be configured to consist of 1 to 16 VMS files. Managing VAX DSM 2-7 Once the volume sets you want to use in your application are created and placed, 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 VAXcluster environment. o Transaction processing When this characteristic is enabled, related modifications to the database set can be organized into well-formed transactions. The transactions are defined within application program recovery units. Three types of database sets are supported: o DSM-11 compatible database sets The DSM-11 compatible database set includes one DSM-11 volume set mounted as foreign volumes, optional After-Image Journal files, and an optional Before-Image Journal Output File. o VAX DSM database sets A VAX DSM database set consists of one VAX DSM volume set, optional After-Image Journal files, and an optional Before- Image Journal Output File. o Transaction database sets A transaction database set includes one or more volume sets, required After-Image Journal files, and a required Before- Image Journal Output File. VAX DSM Version 6.0 transaction 2-8 Managing VAX DSM recovery unit processing only applies to globals resident within transaction database sets. Each database set within a VAX 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 to include for mounting. To make database set definition easier, the ^CONFIG Utility also permits you to create and modify database sets as you define a configuration. Once a database set is created, it can be included in multiple configurations. In a VAXcluster environment, you only need to define the database set once. Each cluster member can then name the same database set for mounting on a cluster-wide basis within the configurations defined for that node. If you modify the components of a database set, the modifications are reflected in each configuration that references the database set. See the VAX DSM Database Operations Guide for details about how to create and manage volume sets and database sets. Defining a VAX DSM Configuration 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 name (configuration identifier) that you designate. You can create and store any number of configurations. Once a configuration is stored, you can retrieve it, edit its characteristics, and then start the configuration. Managing VAX DSM 2-9 Running the ^CONFIG Utility To create a new VAX DSM configuration, log in to the VAX DSM environment manager's account and run VAX 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: Pressing Ctrl/c while using ^CONFIG aborts the utility. This leaves the configuration partially defined and inconsistent, and subsequent attempts to start the configuration may fail. Always answer all of the questions presented by the utility to completely define a configura- tion. Enter the following to run the ^CONFIG Utility: Example 2-1 Running the ^CONFIG Utility $ DSM/MANAGER VAX DSM V6.0 DSMMGR [Baseline] >D ^CONFIG Build VAX DSM Configuration Type ? for HELP at any time Would you like extended help [Y OR N] ?Y Example 2-1 Cont'd on next page 2-10 Managing VAX DSM Example 2-1 (Cont.) Running the ^CONFIG Utility Enter YES if you want help text displayed for every question asked. Press Return to continue without extended help. Name of configuration identifier <1>PAYROLL Enter the name of the configuration that you want to create, or modify. You will use this name whenever you want to refer to this configuration. The name must consist of less than 12 uppercase alphabetic and numeric characters and cannot contain the number 0. Type ^L to see a list of currently defined configurations. If you press Ctrl/c while running ^CONFIG, the utility aborts. This leaves the configuration partially defined and inconsistent, and subsequent attempts to start the configuration can fail. Always answer all of the questions presented by the utility to completely define a configuration. Disk buffers are 1Kb in-memory buffers used to cache database disk data in memory. The buffer techniques used by VAX 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. Example 2-1 Cont'd on next page Managing VAX DSM 2-11 Example 2-1 (Cont.) Running the ^CONFIG Utility If you are creating a configuration for limited use and testing, choose a small number (300-600). This reduces the amount of process and VMS 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. A minimum of 64 buffers is allowed. Enter the number of disk buffers >1200 Reference: "Configuring VAX DSM Shared Memory" in Chapter 3 Use nonpaged memory for these buffers [Y OR N] ? VAX DSM can use nonpaged memory to contain the disk buffers that are used for shared global access. Because disk buffers are shared between all VAX DSM users and require a significant amount of memory. Using nonpaged memory greatly reduces the amount of page fault activity each VAX 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. In order 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 VMS shared global sections for buffers and shared data structures. Example 2-1 Cont'd on next page 2-12 Managing VAX DSM Example 2-1 (Cont.) Running the ^CONFIG Utility Reference: "Configuring VAX DSM Shared Memory" in Chapter 3 Enter the maximum number of DSM users <128> 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. Configuration access control method The following configuration access control methods are available: GROUP Permit access only from accounts in the VAX DSM manager account's VMS group WORLD Permit access from any VMS account AUTHORIZED Permit access only from accounts with authorized access rights Enter the access control method NAME that you want to use for this configuration. Reference: Controlling User Access in this chapter Restrict use of the VIEW command [Y OR N] ? Example 2-1 Cont'd on next page Managing VAX DSM 2-13 Example 2-1 (Cont.) Running the ^CONFIG Utility If you want to restrict the use of the $VIEW function, the VIEW command, the %SETUCI $ZCALL, and the %SPAWN $ZCALL to users logged in to the manager's UCI or % utilities, answer YES. Any user not logged in to the manager's UCI receives a protection error when attempting to use these functions. The VIEW command and associated restrictions are required when you select the AUTHORIZED access control method. However, you can choose to enable this capability for all UCIs when selecting any of the other configuration access control methods. Include support for Routine/Global Performance Histograms [Y OR N] ? The ^RTH Utility produces detailed reports and histograms on the performance of your application within the VAX 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 ^RTHIST data collection. Enter YES if you intend to use the ^RTH Utility. Reference: Chapter 6 Number of database sets in this configuration <1> Enter the number of database sets for this configuration to mount during startup. A configuration must mount at least 1 database set that includes at least one volume set. However, the total number of volume sets defined by all of the database sets included within the configuration can not exceed 16. Example 2-1 Cont'd on next page 2-14 Managing VAX DSM Example 2-1 (Cont.) Running the ^CONFIG Utility Name of database set #1 >EMPLOYEE Enter the name of a database set for this configuration to mount during startup. Enter ^L to get a list of the currently defined database sets within the environment. EMPLOYEE not defined. Define now [Y OR N] ? This named database set is not currently defined. If you have already created volume sets, you can choose to define the database set now. Enter YES to define the database set. Enter NO to go back and enter a different database set name for this configuration. Is this a VAX DSM, Transaction or DSM-11 database set [V, T OR D] 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 VAX DSM volume set is comprised of VAX DSM volume files Transaction comprised of one or more associated VAX DSM volume sets that support transaction processing updates to resident globals Press Return to create a VAX DSM database set. Enter T or D to create a Transaction or DSM-11 database set. Mount EMPLOYEE for clusterwide access Example 2-1 Cont'd on next page Managing VAX DSM 2-15 Example 2-1 (Cont.) Running the ^CONFIG Utility If all of the volume sets in the database set are to be mounted by two or more concurrently running configurations within a VAXcluster 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 VAXcluster 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. Reference: See the VAX DSM Database Operations Guide Name of the volume set >EMP 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. Reference: See the VAX DSM Database Operations Guide Enter the number of volumes in volume set EMP <1> VAX DSM volume sets can consist of one to eight disk or file volumes. Enter the number of volumes in this volume set. Reference: Chapter 4 and the VAX DSM Database Operations Guide Example 2-1 Cont'd on next page 2-16 Managing VAX DSM Example 2-1 (Cont.) Running the ^CONFIG Utility Enter the file name of EMP volume #1 DISK$DATA: Enter the VMS 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. Reference: Chapter 4 Enable Before-Image Journaling for this database set [Y or N] ? Before-Image Journaling saves separate copies of physical database blocks as they appeared before a major modification of the database is attempted. A major modification includes SET operations that cause a new block to be allocated (split) or KILL operations that cause the deallocation of a database block (merge). This approach to journaling provides a high performance safeguard against database degradation if your system should fail with unwritten, modified blocks remaining in the disk buffer cache. Because only a few blocks are journaled, and the Before-Image Journal Output File is continually recycled, restoration of a database is extremely fast. Enter YES to enable physical Before-Image Journaling for the volume set in this database set. Enter NO if you do not want to use Before-Image Journaling. Example 2-1 Cont'd on next page Managing VAX DSM 2-17 Example 2-1 (Cont.) Running the ^CONFIG Utility Reference: See the VAX DSM Database Operations Guide Enable After-Image Journaling for this database set [Y or N] ? After-Image Journaling is a facility that allows you to save critical global database transactions to a sequential disk file. After-Image Journaling saves a separate physical record of all SET and KILL operations that occur to the database. This trace can be used in conjunction with BACKUP and RESTORE to completely recover a database to its current state should a media failure (for example, disk failure) occur. Answer YES to include After-Image Journaling support for all of the volume sets in this database set. Reference: See the VAX DSM Database Operations Guide Include support for Distributed Data Processing [Y OR N] ? Distributed Data Processing (DDP) is a facility that allows you to access global arrays on another VAX DSM or DSM-11 system connected using DEUNA/DEQNA Ethernet controllers. A routine can request data from a remote system using an extended global reference syntax, or global translation. Enter YES to include support for DDP. Enter NO if you do not want to include support for DDP. Reference: Chapter 7 Example 2-1 Cont'd on next page 2-18 Managing VAX DSM Example 2-1 (Cont.) Running the ^CONFIG Utility Modify global characteristics [Y OR N] ? 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. Reference: See the VAX DSM Database Operations Guide Install mapped routines [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. Reference: Chapter 6 Modify DSM default command line qualifiers [Y OR N] ? Example 2-1 Cont'd on next page Managing VAX DSM 2-19 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 /SOURCE_BUFFER_SIZE=n /[NO]CENABLE /STACK_SIZE=n /EXTENSION=(keyword[,...]) /SYMBOL_TABLE_SIZE=n /[NO]MAPPED /TERMINAL_BUFFER_SIZE=n /[NO]PACK /TYPEAHEAD /[NO]PASSALL /UCI=name /ROUTINES=[UCI,VOL] /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. Reference: See the VAX DSM Programmer's Guide, Chapter 2 Modify the Global Translation Tables for this configuration [Y OR N]? The Global Translation Tables provide a flexible way to logically force global references to occur in a non-default DSM directory (UCI,VOL). It provides transparent access to globals between DSM directories on any VAX DSM or DSM-11 system, local or remote (using DDP). Reference: Chapter 5 Make PAYROLL the new default configuration [Y OR N] ? Y If you want to make this configuration the new default configuration to use when starting up VAX DSM, enter YES. Enter NO, if you do not want this to be the default configuration. Example 2-1 Cont'd on next page 2-20 Managing VAX DSM Example 2-1 (Cont.) Running the ^CONFIG Utility Show configuration memory requirements [Y OR N] ? Enter YES to produce a comprehensive report on memory usage and suggested VMS tuning parameters. The reports are generated by the ^MEMREQ Utility. The ^MEMREQ Utility uses the configuration data supplied to determine which VMS 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. Reference: Chapter 3 Start up configuration PAYROLL [Y OR N] ? Enter YES if you want to start VAX DSM with all of the options you have specified for this configuration. If you need to modify VMS SYSGEN parameters, it is best to answer NO here, make the necessary modifications and reboot your system. You can then log back in to VAX DSM and run the ^STU Utility to start the configuration. The configuration is now completely defined and ready to be started. If you answered YES to the previous question, the following question appears: Enable user logins on startup [Y OR N] ? It is useful to disable logins in situations where system management tasks require you to have exclusive access to a fully functional VAX DSM configuration. Example 2-1 Cont'd on next page Managing VAX DSM 2-21 Example 2-1 (Cont.) Running the ^CONFIG Utility Answer NO to this question to disable user logins into VAX DSM after startup completes. Only users logging in to VAX DSM with the /MANAGER command line qualifier are allowed access to the running configuration. All other users receive the "VAX DSM logins are currently disabled" message. Answer YES to this question to start VAX DSM and make it immediately available to all application users. The configuration is now started, and VAX DSM displays the following: Starting VAX DSM configuration PAYROLL VAX DSM Database Set EMPLOYEE Mounting volume set EMP with 1 volume DISK$DATA:[DSM$DSMMGR.DATABASE]EMPVOL1.GLS as volume 1 with 5 maps 1 Volume Set mounted DSM Write Demon ... Started as DSM_DEMON_1 (PID = 21E00B4E) DSM Garbage Collector ... Started as DSM_GARCOL_1 (PID = 21E00A4F) VAX DSM startup complete - User logins enabled Displaying Configuration Information (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: 2-22 Managing VAX DSM $ DSM/MAN VAX DSM V6.0 DSMMGR [MGR,TES] >D DISPLAY^CONFIG *** CONFIGURATION DISPLAY Name of configuration identifier Output Device ? <0> *** CONFIGURATION PAYROLL *** System options : Configuration access mechanism MANAGER Number of disk buffers 1200 Memory for disk buffers Paged Maximum number of users 128 Restrict use of the VIEW command NO Support RTHIST performance histogram NO Database set #1 = EMPLOYEE VAX DSM database set Not Cluster-Mounted Managing VAX DSM 2-23 EMP DISK$DATA:[DSM$DSMMGR.DATABASE]EMPVOL1.GLS No Before-Image Journaling No After-Image Journaling Database set master for the following database sets: NONE DDP: not included Default global characteristics : 8 Bit Subscripts Yes Journaling No Collating sequence Numeric Access privileges for non-% globals : System: RWD World: R Group: R UCI: RWD Access privileges for % globals : System: RWD World: NONE Group: NONE UCI: RWD Mapped routine sets to install at startup : mapped routines not included DSM default command line : DSM/UCI=MGR TP options : TP not included 2-24 Managing VAX DSM Establishing Detached Processes for Global Operations When you start up DSM using VAX DSM volume sets for global storage, the following VMS detached processes are created for your environment: o Write Demon (writes global data modifications into the database) o Garbage Collector (reclaims disk space freed as a result of a global KILL) o VAX DSM Journal Process (records all SETs and KILLs, manages DSM transactions) o VAX DSM Recovery Process (initiates an automatic recovery of the database) o One 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 link servers (controls DECnet links to remote VAX DSM configurations) The Write Demon and Garbage Collector are always started when you start up a configuration. The Recovery Process is started up when Before-Image Journaling is enabled for a database set. The DSM Journal Process and DDP Servers are optional. You can inhibit startup of these processes if you do not intend to use their services. The following sections describe these detached processes in greater detail. Managing VAX DSM 2-25 Write Demon The Write Demon is a VMS process that must be started before any DSM user can access globals or routines residing on VAX 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 up, VAX DSM creates a log file called DSMDEMON.LOG in the log file directory that was created when the SYS$MANAGER:DSM$INIT.COM procedure was run. 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 if the configuration contains 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 Output Files 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 VMS process that the VAX DSM manager starts up when establishing VAX DSM volume sets. This process handles the asynchronous task of making blocks containing deleted data available for reallocation. When the Garbage Collector starts up, VAX 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. 2-26 Managing VAX DSM You can print or type the Garbage Collector's log file while the Garbage Collector is running. VAX DSM Journal Process After-Image Journaling provides a way to keep a record of the SET and KILL commands that a VAX DSM application performs on the global database. The VAX DSM manager enables journaling for an application by selecting the appropriate startup options in ^CONFIG, and starts up the configuration. Journaling can then be enabled on a global-by-global basis. The VAX DSM manager can interact with the DSM Journal Process during a DSM session to control Journaling operations. To do this, the VAX DSM manager uses the Journal Process Utilities described in the VAX DSM Database Operations Guide. Recovery Process The VAX DSM Recovery Process is started whenever you have a database set in your configuration that has Before-Image Journaling enabled. The Recovery Process performs automatic recovery when one of the following occurs: o You mount a database set that was protected by Before-Image Journaling and was mounted when a system failure occurred. o A database set is a surviving member of a cluster where one node suffered a system failure. o A recovery unit abort occurs on a transaction database set. In all cases, the Recovery Process also applies the most recent After-Image Journal data for the affected database sets if After- Image Journaling was enabled. Managing VAX DSM 2-27 Note that, if all database sets are non-transaction datatbase sets, and none are cluster-mounted, the Recovery Process performs any database recovery that is necessary and then terminates. DDP Servers A DDP Server is a VMS process that manages the communications link between your DSM application and other DSM systems or applications. The VAX DSM manager can select the number of DDP Servers to start. DDP DECnet Link Servers The DDP DECnet link servers are responsible for establishing DECnet connections to remote VAX DSM configurations. For DECnet DDP operations, DDP DECnet link servers transmit and receive DDP messages to the remote configuration across the DECnet circuit for all local DDP users. One DDP DECnet link server is created for each DECnet DDP link configured in ^CONFIG. Running Multiple VAX DSM Configurations You can run multiple VAX DSM configurations simultaneously on a VMS system: one configuration for each VAX DSM environment. To set up a configuration for an environment, initialize a VAX DSM environment manager's account for each environment by logging in to a privileged VMS system account and running the SYS$MANAGER:DSM$INIT.COM procedure. This procedure is described in Chapter 1. Each time you initialize a new VAX 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 VMS resource names that are associated with the environment and used internally by VAX DSM. 2-28 Managing VAX DSM The environment name is a system-wide unique name that is always equivalent to the manager's account name. The environment name is used by application users and programmers to access a configuration running in an environment. When you define and start a configuration in an environment, 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 Create Configuration Utility (^CONFIG). The defaults specify information such as the login UCI and volume set as well as default source buffer and symbol table sizes. Users can always override the defaults by appending explicit values on the DSM command line. The /ENVIRONMENT=envnm command qualifier is used to select the environment that you want to access. For example, any VMS user can gain access to the running configuration in the environment, PRODUCTION, by entering the following DSM command line: $ DSM/ENVIRONMENT=PRODUCTION VAX DSM V6.0 PRODUCTION [WRK,VBA] > Managing VAX DSM 2-29 Note that, the environment selected is displayed in the VAX DSM banner along with the login UCI and volume set. When the VAX DSM manager for environment PRODUCTION logs in to VAX DSM without the /ENVIRONMENT=envnm command line qualifier, VAX DSM attempts to access the current configuration running from the manager's account environment. $ DSM VAX DSM V6.0 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, VAX DSM attempts to translate DSM$ENVIRONMENT from the process, group, or system logical name tables to determine the target environment. If the name exists, the equivalence of DSM$ENVIRONMENT is used for selecting the environment. If DSM$ENVIRONMENT is not defined, then VAX 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 log in defaults that are specific to the configurations running in each of the environments. For example, consider a situation in which two environments named PRODUCTION and DEVELOPMENT run separate configurations concurrently on the same VMS 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: 2-30 Managing VAX DSM $ DEFINE/PROCESS DSM$DEFAULT_PRODUCTION"/UCI=WRK/VOL=PRD" $ DSM/ENVIRONMENT=PRODUCTION VAX DSM V6.0 PRODUCTION [WRK,PRD] > 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 VAX DSM V6.0 DEVELOPMENT [ARD,DEV] > Initializing VAX DSM in a VAXcluster Environment Each VAX DSM configuration can extend over several processors joined in a VAXcluster configuration. For each VMS account that uses DSM in a cluster, you must initialize the default file directories that are to be used to run the configuration on each member in the cluster. Use the SYS$MANAGER:DSM$INIT.COM procedure to initialize a VAX DSM manager's account for cluster-wide usage. For each VMS account you intend to use with VAX DSM, run DSM$INIT from a privileged account. You can run DSM$INIT while logged in to any node of the cluster. DSM$INIT initializes all nodes within the cluster for use with VAX DSM. Managing VAX DSM 2-31 DSM$INIT creates the manager's account and associates three separate classes of environment directories with the account. By default, the directories are created as a tree of directories whose root is separate from the manager's login directory. This default is chosen because the VAX DSM directories and associated files created by VAX DSM, use a VMS protection scheme that might not be compatible for general use. The following types of directories are created: o A cluster common directory is created to hold any data that can be shared between running configurations on all VAXcluster members. This is the environment root directory for all other VAX DSM environment directories. The cluster common directory contains the RMS globals or routine files used by the DSM application and routine map files (.VIR files). By default it is named: ddcu:[DSM$envnm] where: ddcu is the login device of the manager's account envnm is equivalent to the environment (manager's account name) When this directory is initialized, DSM$INIT places RMS access protection on the directory in order to prohibit unauthorized access. The directory is generally not equivalent to the account login directory and must always be a top-level directory. It is important to maintain these conventions so that access privileges applied to this directory can be propagated down into the files and other subdirectories within the environment directory tree. 2-32 Managing VAX DSM o A node specific subdirectory is used to contain the log files from the background DSM processes (for example, the DSM Write Demon and the Garbage Collector) and any error files they generate. Node specific directories are created by DSM$INIT as subdirectories of the cluster common directory. The SCSNODE name of a cluster member is used as the node specific subdirectory. o VAX DSM also creates default file directories as subdirectories of the cluster common directory. These serve as storage locations for VAX DSM volume sets, After-Image Journal files, and Before-Image Journal Output files. The directories created by DSM$INIT for the account VAXDSM are located on a cluster consisting of nodes ZORBA, CASEY, and WELBY. Figure 2-1 shows an example of the directory hierarchy. In the previous figure: o DISK$USER:[VAXDSM.ZORBA] holds the error and log files for DSM processes running on VAXcluster node ZORBA. o DISK$USER:[VAXDSM.CASEY] holds the error and log files for DSM processes running on node CASEY. o DISK$USER:[VAXDSM.WELBY] holds the error and log files for node WELBY. o The VAXcluster common directory, DISK$USER:[VAXDSM], holds routine map files and any RMS globals or routine directories used by all three nodes. o The common directory contains the RMS global, SYS.GBL, which contains the configuration definitions created (using ^CONFIG) for all nodes of the cluster. o The VAX DSM security global, DSMACC.GBL, holds user access information for all nodes of the cluster and also resides here. Managing VAX DSM 2-33 o The DISK$USER:[VAXDSM.JOURNAL] directory is the default storage location for After-Image Journal files or Before-Image Journal files. o The DISK$USER:[VAXDSM.DATABASE] directory is used as the default storage location for VAX DSM volume sets. When you run DSM$INIT in a VAXcluster environment, the following questions appear so DSM$INIT can correctly define the appropriate subdirectories: . . . VAX DSM requires a VMS directory to store log files, routine map files, and RMS global and routine files to serve as the VAX DSM environment root directory. This directory also holds subdirectories which are default storage locations for VAX DSM volume sets and journal files. By default, the VAX DSM environment directories are created as a tree of directories whose root is separate from the manager's login directory. This default is chosen because the VAX DSM directories and associated files created by VAX DSM, use a VMS protection scheme which may not be compatible for general use. You can select any directory or device as the VAX DSM environment root directory. However, the root directory you specify must be a top level directory. Enter the directory to use for VAX DSM 2-34 Managing VAX DSM Use of VAX DSM in a VAXcluster environment requires the creation of a separate subdirectory for each cluster member. The subdirectories hold node-specific log files created by VAX DSM configurations running on each of the VAXcluster nodes. Appropriate subdirectories will be created as part of this initialization process. In order to do so, all cluster nodes must be identified at this time. The following VAXcluster nodes are currently booted and will be initialized for use with VAX 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 will create default directories to hold database and journal files associated with this environment. The default directories are created as subdirectories of the VAX DSM environment root directory. You may also want to create directories which are default storage locations for VAX DSM volume sets and journal file on other disk units in your system. You can optionally select to initialize these additional directories at this time. The following directories will always be created if they do not already exist: DISK$USER:[DSM$DSMMGR.DATABASE] DISK$USER:[DSM$DSMMGR.JOURNAL] Create similar directories on other disk devices [Y OR N] ?Y Managing VAX DSM 2-35 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 > . . . 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 and then supply the additional node names. Note: If you add nodes to your cluster, you have to run DSM$INIT again for all defined VAX DSM manager accounts. This ensures that the proper subdirectories are created for the new node, and updates the appropriate DSM management globals. Defining VAXcluster Configurations After initializing the VAX DSM environment manager's account, you can log in to the account and create VAX DSM configurations. A unique configuration must be created for each VAXcluster node. When you mount a VAX DSM database set for use by all cluster members, the ^CONFIG Utility asks you to designate one or more cluster members to master database sets mounted cluster-wide. If you enable DDP, you are also required to select a unique 3- character DDP node name for each running configuration. Attempts to simultaneously run multiple configurations that have the same DDP node name will fail. 2-36 Managing VAX DSM For these reasons, it is necessary to define a uniquely named configuration for each member of a cluster. A separate con- figuration on each VAXcluster node is created and selected as the default configuration for the node. When you use the SYS$STARTUP:DSM$STARTUP.COM procedure to start a configuration and do not specify a configuration name as an input parameter, the default configuration for the local VAXcluster node is started. See Chapter 7 for information about using DDP in a VAXcluster environment. The VAX DSM Database Operations Guide contains information about using and optimizing cluster-mounted volume sets. It also contains information on how VAX DSM Journaling is implemented in a VAXcluster environment. Become familiar with the information in the VMS VAXcluster Manual before you attempt to run VAX DSM in a VAXcluster environment. Modifying Your VAX DSM Configuration When you initially created the VAX DSM manager account, the SYS$MANAGER:DSM$INIT.COM procedure set minimal account limits, quotas, and privileges necessary to run limited VAX DSM configura- tions. It is necessary to adjust these values as you modify your operating environment and configuration characteristics. The following list describes the recommended technique for setting up a VAX DSM configuration that has all of the capabilities you require. 1. Use the ^CONFIG Utility to establish a new configuration, including the new options or values. 2. Use the ^MEMREQ Utility to determine which VMS SYSGEN parameters and account quotas need to be adjusted. 3. Establish any new VMS system or environment manager account resources required for the planned configuration. These resources, including account quotas for the VAX DSM environment manager account and parameters set during VMS SYSGEN, are described in Chapter 3. Managing VAX DSM 2-37 4. Reboot the VMS operating system if you have modified SYSGEN parameters. 5. Run VAX 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, and then add new capabilities. This approach ensures that you understand and control the effects of the changes that you make to your VAX DSM configuration. Starting Up and Shutting Down a VAX DSM Configuration You must be logged in to VAX DSM with the DSM/MANAGER command to interactively start up or shut down a VAX DSM configuration. You must be logged in to the VAX DSM environment manager's account to start a configuration. Starting Up a VAX DSM Configuration You can interactively select a VAX DSM configuration and start it by logging in to VAX DSM and running the Configuration Startup Utility (^STU). You can also configure your VMS system to automatically start a configuration at VMS system boot time. The SYS$STARTUP:DSM$INSTALL.COM procedure is supplied as a template for VAX DSM activities required at VMS system startup. You can customize this procedure for your site. The relevant portions for configuration startup in this file accomplish the following: o Creates the DSM$BATCH batch queue where the VAX DSM startup procedure runs o Submits the SYS$STARTUP:DSM$STARTUP.COM procedure to DSM$BATCH to start a configuration 2-38 Managing VAX DSM To set up automatic configuration startup, locate and edit the portion of this file that starts the VMS 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 non-VAXcluster environment, the name of the queue created is DSM$BATCH. In a VAXcluster 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 SYS$STARTUP:DSM$STARTUP.COM procedure to start a configuration. For each configuration you want to start, copy these commands, remove the comment character (!), and edit the following fields to specify the configuration name and VAX DSM manager's account name: $ SUBMIT/USER=uuu/PARAMETER=ccc/QUEUE='QUEUE SYS$STARTUP:DSM$STARTUP where: uuu is the VAX DSM environment manager's account name ccc is the VAX DSM configuration name (You can make this value null ("") to start the default configuration.) Managing VAX DSM 2-39 For each initialized VMS group, substitute the appropriate user name for the VAX DSM manager's account, and supply the configuration name 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 Shutting Down a VAX DSM Configuration You can interactively shut down a VAX DSM configuration by logging in to VAX 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 group logical names. Note: Using the DCL STOP/ID command to stop VAX DSM user or system processes can cause all other users accessing the same VAX DSM volume set to hang, and can cause database degradation. Instead, use the VAX DSM ^FORCEX Utility, which runs down a VAX DSM user safely. See Chapter 8 for more information about how to use this utility. See the section "System Shutdown" in Chapter 1 for more informa- tion on system shutdown. Establishing User Accounts Each user accessing a VMS system has an account. A user can be a DSM programmer or an application user. The VMS system's user authorization file, SYS$SYSTEM:SYSUAF.DAT, contains information about each VMS user account. The VMS operating system uses this information to identify valid user accounts. 2-40 Managing VAX DSM The VAX DSM manager is responsible for establishing user accounts and ensuring the security of these accounts. To set up an account for a VMS user, 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 system's user authorization file (UAF), using the VMS Authorize Utility. Use the VMS Authorize Utility to specify the user name, password, default device, and other identifying information. The following example shows how to use the VMS Authorize Utility to create a user account for the VAX DSM configuration with a UIC of 215. $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF>ADD JOHNSON/PASSWORD=GREMLINS/UIC=[215,7]- /DEVICE=DISK$USER:/DIRECTORY=[JOHNSON]- /BYTLM=40960/ENQLM=300/WSQUOTA=1000/WSEXTENT=1200/FILLM=150- /PRIV=TMPMBX/DEFPRIV=TMPMBX The Guide to Setting Up a VMS System contains instructions for using the SYS$EXAMPLES:ADDUSER.COM procedure for adding a new user to the UAF. This command procedure prompts for all categories of information about the user, runs the VMS Authorize Utility, and cleans up after itself. You may find that if you copy and use this command procedure, it is more convenient than performing all of the steps yourself. Managing VAX DSM 2-41 Establishing Accounts for VAX DSM Programmers When you establish an account for a VAX DSM programmer, follow the guidelines for establishing an account for VMS interactive users. See the Introduction to VMS System Management for complete details. VAX DSM users need larger quotas in some areas than the ordinary VMS 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 VAX DSM Users" in Chapter 3. VAX DSM does not run unless these limits are adequate. VAX DSM programmers must have specific privileges to perform some VAX DSM operations as described in Table 2-1. Table 2-1 VMS System Privileges Needed by VAX DSM Programmers __________________________________________________________________ DSM_Command__________________Description_____________Privilege____ ZUSE $BRKTHRU to a terminal OPER JOB Starts a DSM process TMPMBX OPEN x:(MAILBOX:NEW) Creates a temporary TMPMBX mailbox OPEN x:(MAILBOX:NEW:SYSTEM) Creates a permanent PRMMBX _____________________________mailbox_________________SYSNAM_______ The %OPCOM $ZCALL and the %GETUAI $ZCALL require VMS privileges. See the VAX DSM Programmer's Guide for more information on using these $ZCALLs. 2-42 Managing VAX DSM Establishing Accounts for VAX DSM Applications Users The VAX DSM manager can establish separate VAX 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 effectively tie an application user to a specific application, which prevents any interaction with VMS. Controlling User Access VAX DSM can allow any VMS user to directly access a configuration running in a VAX DSM environment on the local VMS system using the /ENVIRONMENT=envnm command line qualifier. This capability, along with the ability to run multiple configurations concurrently, provides a great deal of flexibility when designing an application system. However, the VAX DSM manager must also restrict users access to various components of the application system to protect the database from unauthorized access. The modes of access as well as the access restrictions required vary greatly from one installation to another. Two models of application environments are common in MUMPS systems: o Dedicated application systems The dedicated application system views the underlying operating system solely as a support platform with a singular purpose of serving the MUMPS 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 Return to the point at which the application program gets control. Managing VAX DSM 2-43 In this model, the use of captive terminals and accounts totally secures access to VAX DSM. It is likely that all application users actually use the same VMS 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 VMS account with access to all UCIs, volume sets, and configurations. This approach presents only two levels of access authority: privileged programmer and unprivileged user. It is an adequate approach in controlled operational environments that do not require any direct user interaction with the VMS system. o Multiuse systems The multiuse system uses the underlying operating system for a large variety of MUMPS and non-MUMPS services. In this model, most users have their own VMS account with direct access to the DCL command prompt ($). The MUMPS application system may be only one of the resources that is used. The user community is comprised of both privileged programmers and unprivileged users. In this environment, the MUMPS application system still retains its control over how the application user accesses the database once the user is logged in to VAX DSM. However, the VAX DSM manager must be able to precisely identify which VMS users can log in to a running configuration, what modes of access are permitted, and which UCIs, volume sets, and routines are accessible. In addition, VMS files used by VAX DSM for storing database and journal information have to be protected from unauthorized modification. 2-44 Managing VAX DSM Solutions to controlling access in the multiuse systems must provide many levels of access authority that are VMS account based. VAX DSM provides a number of methods for establishing database security depending on your site requirements. Regardless of the techniques you choose, access to the DSM database is ultimately based on a two level access authorization system: 1. Configuration access control Authorization to log in to a UCI and volume set 2. Global access control Authorization to read or modify specific DSM globals from the login UCI The following sections describe configuration access control methods available in VAX DSM. They describe the utilities provided by VAX DSM as well as system conventions you can use to construct access methods for either dedicated or multiuse systems. Refer to the VAX DSM Database Operations Guide for information about global access control. 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 Guide to VMS System Security contains a useful overview of evaluating the security needs of a site. Refer to this manual for detailed information about VMS system security. Managing VAX DSM 2-45 Configuration Access Modes Maintaining the required level of security in a computer installation depends on placing the appropriate level of data access restrictions on users. In a VAX DSM environment three modes of configuration access are provided. They are: o Manager access DSM manager access is the least restrictive. A user with DSM manager access can invoke DSM with the /MANAGER command line qualifier and have full access to the DSM utility programs in the MGR UCI. You have unrestricted use of the VIEW command and $VIEW function and have access to all volume sets and UCIs through the %SETUCI $ZCALL. You have use of privileged system supplied $ZCALLs. This access level gives control over all aspects of the DSM environment, including the ability to define DSM configurations, to shut down a configuration, and to establish the security mechanism for a DSM database and grant access rights to other users. DSM manager access includes Programmer and Application Mode access to all volume sets and UCIs. o Programmer access Programmer Mode access to DSM allows the user to interact directly with the VAX DSM interpreter. This gives complete control of data and programs within any volume set and UCI to which the programmer has access. This level of access includes the ability to set or kill DSM globals, the ability to create, modify, and run DSM routines, and the ability to change the current volume set or UCI to another volume set and UCI for which access is permitted. Programmer Mode access includes Application Mode access to all volume sets and UCIs for which Programmer Mode is available. o User access 2-46 Managing VAX DSM Application mode access to DSM allows the user to run DSM routines. The ability to the read or modify the DSM database or change the current volume set or UCI is controlled by predefined DSM routines. Therefore, the user's access to sensitive data is completely defined by the application programs. This most restrictive mode of access to VAX DSM should be granted to users of DSM applications who have no knowledge of programming or no need for programmer access. Configuration Access Control Methods The method used to control access to a VAX DSM environment is defined by the configuration that is running. You use the ^CONFIG Utility to select the access control method that is most suitable for your application system. A VAX DSM configuration can support the following access control methods: o GROUP - permits access only from accounts in the VAX DSM manager account's VMS group Restricting access to accounts in the VAX DSM manager account's group allows you to create multiple application environments partitioned by VMS group. This mechanism limits which users can access a DSM configuration, but it does not limit the access mode (DSM manager, programmer, or user) in which the user can run DSM. o WORLD - permits access from any VMS account WORLD access allows any VMS user to access the running configuration in any access mode. No security restrictions are supplied by VAX DSM. o AUTHORIZED - permits access only from accounts with authorized access rights Managing VAX DSM 2-47 Restricting access to accounts with authorized access rights allows you the most control over access to a VAX DSM configuration. Access is granted on an individual VMS account basis using the Access Authorization Utility (^ACL). Each account can be granted VAX DSM manager access to the configuration, or limited to Programmer or Application Mode access, or both. Any of the access control methods described are appropriate for use in a dedicated application system. Tied terminals and captive accounts can be organized to directly connect application users to the application thus providing the desired configuration access control. In a dedicated application environment, you only need to consider the access restrictions relative to privileged programmers when choosing the access control method. Authorized Access Control The AUTHORIZED access control method provides the most flexible configuration control technique and is the only suitable method for a multiuse environment. Using AUTHORIZED access control, manager mode access to the VAX DSM configuration can be granted to one or more VMS accounts. Programmer mode access is granted to a specific list of volume sets and UCIs. The user can only log in to DSM in programmer mode in those volume set and UCI combinations to which access was granted. Once logged in to DSM, the user can use the %SETUCI $ZCALL 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. 2-48 Managing VAX DSM Application Mode access is also granted to a specific list of volume sets and UCIs. In addition, 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[/qualifiers] [LABEL]^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. Access Utilities for Authorized Access Control (^ACL) The ^ACL Utility defines account access rights lists for any configuration started up in the DSM environment from which it is run. Enter the following to run the ^ACL Utility: $ DSM/MANAGER VAX DSM V6.0 DSMMGR [MGR,AAA] >D ^ACL VAX DSM displays the following menu: Environment Access Utilities 1. ADD/MODIFY USER (ADD^ACL) 2. DELETE USER (DELETE^ACL) 3. HELP (HELP^ACL) 4. PRINT (PRINT^ACL) Select option > Managing VAX DSM 2-49 You can get help at any question by entering a question mark (?), you can get a listing of current values by entering ^L, and you can return to the previous question by entering a circumflex (^). All responses, except the user name, can contain trailing wildcard characters. Any entry can be deleted 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 allows you to edit the DSM access rights for a VMS account. The following is an example of the ADD /MODIFY option: Select option >1 VMS User Name >SMITH No current access rights for this user. User: SMITH, Access Mode >USER User: SMITH, Access Mode: USER, VOL >LAB User: SMITH, Access Mode: USER, VOL: LAB, UCI >PHA User: SMITH, Access Mode: USER, VOL: LAB, UCI: PHA, Routine >RX User: SMITH, Access Mode: USER, VOL: LAB, UCI: PHA, Routine > User: SMITH, Access Mode: USER, VOL: LAB, UCI >CHM User: SMITH, Access Mode: USER, VOL: LAB, UCI: CHM, Routine >ORDER User: SMITH, Access Mode: USER, VOL: LAB, UCI: CHM, Routine >INQUIRE User: SMITH, Access Mode: USER, VOL: LAB, UCI: CHM, Routine > User: SMITH, Access Mode: USER, VOL: LAB, UCI >RAD User: SMITH, Access Mode: USER, VOL: LAB, UCI: RAD, Routine >INQUIRE 2-50 Managing VAX DSM User: SMITH, Access Mode: USER, VOL: LAB, UCI: RAD, Routine > User: SMITH, Access Mode: USER, VOL: AAA, UCI > User: SMITH, Access Mode: USER, VOL > User: SMITH, Access Mode > USER ACCESS MODE VOL UCI ROUTINE ---- ----------- --- --- ------- SMITH USER AAA CHM INQ REG PHA LAB RAD INQ OK to file? In the previous example, a new user named SMITH is granted user (Application Mode) access to volume set LAB. Smith 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. After you enter the user name, the program lists the users current access rights (in this case none). Each prompt shows the context of the current entry. For example, 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. 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: Managing VAX DSM 2-51 Select option >2 VMS User Name >SMITH ACCESS MODE VOL UCI ROUTINE ----------- --- --- ------- USER AAA CHM INQ REG PHA LAB RAD INQ OK to delete? SMITH DELETED The HELP option (HELP^ACL) displays online help. The PRINT option (PRINT^ACL) prints the rights lists of all users on your terminal, or writes it to a VMS file. Establishing Tied Application Accounts and Terminals In the dedicated application system, it is necessary to control the method in which an application user accesses the system from the moment Return is pressed on the terminal keyboard. The process of establishing tied application accounts and terminals requires that you configure a number of components in a manner that directly connects the application user to the application programs. These components include: o VMS auto-login facility o VMS captive user accounts 2-52 Managing VAX DSM o VMS login command procedures o VAX DSM command line qualifiers o VAX DSM tied terminal utilities Two access methods are provided for application users: o Tied Application Accounts The application user enters a user name and password that correspond to a particular VAX 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, 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) through the VMS Automatic Login Facility. Use the SYS$MANAGER:ALFMAINT.COM procedure to tie terminals. See the Guide to VMS System Security for a description of this facility. 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 techniques described previously accomplish the same objective. The application user is granted access to a VMS 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 Managing VAX DSM 2-53 You can set up a VMS captive account to provide a user account that is dedicated to running the DSM application. The VMS captive account is set up by logging in to the VMS system manager's account and using the VMS Authorize Utility, for example: $ SET DEFAULT SYS$SYSTEM $ RUN AUTHORIZE UAF> ADD SMITH/UIC=[215,8]- /DEVICE=DISK$USER:/DIRECTORY=[SMITH]- /BYTLM=40960/ENQLM=300/WSQUOTA=1000/WSEXTENT=1200/FILLM=150- /PRIV=TMPMBX/DEFPRIV=TMPMBX- /FLAGS=(CAPTIVE,DISWELCOME,DISCTLY,DISREPORT) /LGICMD=CAPTIVE.COM/NOPASSWORD The CAPTIVE flag indicates that the account user cannot change any login defaults. The DISWELCOME flag disables the VMS "Welcome to . . . " message. The DISCTLY qualifier disables Ctrl/y. The DISREPORT flag disables the last login time reporting message. The /NOPASSWORD qualifier sets up the account so that you do not need to enter a VMS password after you enter the VMS user name. The /LGICMD= qualifier specifies that the CAPTIVE.COM procedure is run when the application user logs in. Creating the Captive Command Procedure You can create a command procedure that runs when you log in to the captive account. The command procedure invokes DSM in application mode and runs the VAX DSM START^TIED Utility. The START^TIED Utility starts the user application routine that was defined for the login port. Include the following lines in CAPTIVE.COM: $ DSM/MANAGER/INPUT=SYS$COMMAND START^TIED $ LOGOUT 2-54 Managing VAX DSM Setting Up the VAX DSM Tied Routine and Port Tables The Tied Routine Utility (^TIED) dispatches to a user-defined application routine from the VAX 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 VAX DSM manager to create a table of ports and associate the port with a specific application routine. 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 system 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 > 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. Managing VAX DSM 2-55 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. When you build the Tied Port Table, use a wild card to specify a port name to force ports of one type to be tied to one routine. For example, specifying RT* as a port to tie, forces all remote terminals (users with access by the DECnet SET HOST command) to connect to a designated tied routine. 2-56 Managing VAX DSM 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 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 to display the Tied Ports Table and the SHOW TIED ROUTINES option to display the Tied Routines Table entries. Managing VAX DSM 2-57 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 the VAX DSM manager to control all user and programmer access to running VAX DSM configurations. When login access is disabled, users who attempt to run VAX DSM without the /MANAGER command line qualifier receive the following error message: %DSM-E-LOGINDIS, VAX DSM logins are currently disabled Authorized VAX DSM managers who run VAX DSM with the /MANAGER command line qualifier are always granted access. User access can dynamically be disabled and reenabled through use of the ^LOGIN utility. This permits the VAX DSM manager to disable VAX DSM access without having to disable interactive logins to VMS. Enter the following to run ^LOGIN: >D ^LOGIN 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. 2-58 Managing VAX DSM Using the ^STU Utility, you can now optionally choose to have user logins disabled when configuration startup is complete. This starts VAX DSM in a manager access only mode. When you are ready to allow application users back into VAX DSM, you reenable login access using the ^LOGIN utility. In addition, 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 where: p1 is the name of the configuration to start or "" to start the default configuration p2 is "DISABLE" to disable user logins on startup and "ENABLE" to enable user logins (default) Managing VAX DSM 2-59