Open_M________________________________________ DSM for OpenVMS Release Notes Part Number: IS-DSM4F-VM Revision Date: January 1999 Software Version: DSM for OpenVMS VAX V7.2 DSM for OpenVMS Alpha V7.2 InterSystems Corporation Cambridge, Massachusetts __________________________________________________________ First Printing, October 1983 Revised, June 1986 Revised, September 1987 Revised, November 1988 Revised, March 1992 Revised, February 1993 Revised, October 1993 Revised, October 1995 Revised, June 1996 Revised, October 1996 Revised, November 1997 Revised, January 1998 Revised, March 1998 Revised, January 1999 This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive, Cambridge MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part, without the express prior written consent of InterSystems Corporation. The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation. InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in such standard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of such software programs is limited in the manner set forth in such standard software license agreement(s). THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST. InterSystems Corporation disclaims responsibility for errors which may appear in this document and it reserves the right, at its sole discretion and without notice, to make substitutions and modifications in the products and practices described in this document. Caché, InterSystems, Caché SQL, Visual M, Caché ObjectScript, Caché Objects, DCP, ISM, DTM, DT-MAX, DT-Windows, DSM, DSM-DDP, and DASL are trademarks of InterSystems Corporation. TCPware for OpenVMS is a trademark of Process Software Corporation. OpenVMS for Alpha, OpenVMS for VAX, Digital UNIX, DEC, Digital, and the Digital Logo are trademarks of Digital Equipment Corporation. All other trademarks and registered trademarks are the property of their respective holders. IS-DSM4F-VM This document was prepared using VAX DOCUMENT, Version 2.1. ________________________________________________________________ Contents 1 Updates to Version 7.2 of DSM for OpenVMS Prerequisites ........................................ 1-1 New Features ......................................... 1-1 ViewPoint User-Defined Metrics ....................... 1-2 Command-line Recall .................................. 1-2 ZRECALL Command.................................... 1-2 Command-line Recall Qualifiers..................... 1-3 Key Definitions Files.............................. 1-4 Notes on Using Command-line Recall................. 1-4 $LIST Functions ...................................... 1-5 Reverse $QUERY Function .............................. 1-5 %DUMP Utility ........................................ 1-6 Changes to Existing Functionality .................... 1-7 Precompiled Code Changes........................... 1-7 Documentation Corrections ............................ 1-7 %PRINT Format...................................... 1-7 2 Upgrading Your DSM System DSM Distribution Kit ................................. 2-2 DSM Installation Requirements ........................ 2-2 Disk Space Requirements............................ 2-3 System Resource Requirements....................... 2-4 Disabling the VBSS_ENABLE Parameter (OpenVMS VAX)............................................ 2-4 Memory Resources for Granularity Hint Regions (OpenVMS Alpha)................................. 2-4 DSM Time Requirements.............................. 2-5 Installation Prerequisites ........................... 2-5 Installation Overview ................................ 2-5 DSM Preinstallation Steps ............................ 2-5 iii Shutting Down Running DSM Configurations........... 2-6 Backing Up Your System............................. 2-6 Disabling Interactive Logins....................... 2-6 Determining SYSGEN Requirements for Installation... 2-6 DSM Installation Activities .......................... 2-8 Installing the DSM Distribution Kit................ 2-8 Installing DSM Shared Images....................... 2-12 Installing DSM Images as Resident (OpenVMS Alpha Only).............................................. 2-13 Overview........................................ 2-13 Configuring for Resident Images................. 2-14 Replacing DSM Images Already Installed as Resident........................................ 2-15 Installing DSM in a VMScluster Environment......... 2-16 Changes to Cluster Installations................ 2-17 DSM Postinstallation Activities ...................... 2-17 Establishing Your License.......................... 2-18 Entering/Editing a License...................... 2-19 Upgrading DSM Configurations and Volume Sets....... 2-21 Running DSM$UPGRADE.COM............................ 2-22 Editing the Startup and Shutdown Command Procedures......................................... 2-27 The DSM Initialization Command Procedures....... 2-28 DSM$INSTALL.COM .............................. 2-28 DSM$INSTALL_SITE.COM ......................... 2-28 Editing the Procedures.......................... 2-29 The System Startup Command Procedure............ 2-29 The DSM Shutdown Command Procedure.............. 2-29 A New Intrinsic Functions $LIST Function ....................................... A-2 Syntax............................................. A-2 Description........................................ A-2 Parameters......................................... A-2 Examples........................................... A-3 Notes.............................................. A-3 Errors for Invalid Lists........................ A-3 Differences between Two-Argument $LIST and Three-Argument $LIST............................ A-3 Related Topics..................................... A-4 $LISTBUILD Function .................................. A-5 Syntax............................................. A-5 iv Description........................................ A-5 Parameters......................................... A-5 Examples........................................... A-5 Notes.............................................. A-5 Omitting Arguments.............................. A-5 Using Zero Arguments............................ A-6 Nesting Lists................................... A-6 Concatenating Lists............................. A-6 Related Topics..................................... A-7 $LISTDATA Function ................................... A-8 Syntax............................................. A-8 Description........................................ A-8 Parameters......................................... A-8 Examples........................................... A-8 Notes.............................................. A-9 Errors for Invalid Lists........................ A-9 Related Topics..................................... A-9 $LISTFIND Function ................................... A-10 Syntax............................................. A-10 Description........................................ A-10 Parameters......................................... A-10 Examples........................................... A-10 Notes.............................................. A-12 Errors for Invalid Lists........................ A-12 Related Topics..................................... A-12 $LISTGET Function .................................... A-13 Syntax............................................. A-13 Description........................................ A-13 Parameters......................................... A-13 Notes.............................................. A-13 Errors for Invalid Lists........................ A-13 Related Topics..................................... A-14 $LISTLENGTH Function ................................. A-15 Syntax............................................. A-15 Description........................................ A-15 Parameters......................................... A-15 Examples........................................... A-15 Notes.............................................. A-15 Errors for Invalid Lists........................ A-15 $LISTLENGTH and Nested Lists.................... A-15 Related Topics..................................... A-16 $QUERY Function ...................................... A-17 Syntax............................................. A-17 v Description........................................ A-17 Parameters......................................... A-17 Examples........................................... A-18 Notes.............................................. A-18 Related Topics..................................... A-18 B ViewPoint User-defined Counters Overview of User-defined Counters .................... B-1 User-defined Counters at Startup................... B-1 Creating Application Counters ........................ B-2 Syntax............................................. B-3 Parameters......................................... B-3 Example............................................ B-3 Modifying Application Counters ....................... B-4 Syntax............................................. B-4 Parameters......................................... B-4 Example............................................ B-4 Showing or Hiding Counter Tables ..................... B-4 Syntax............................................. B-5 Parameters......................................... B-5 Retrieving Table and Counter Definitions ............. B-5 Syntax............................................. B-5 Parameters......................................... B-5 Incrementing and Decrementing Counters ............... B-6 Syntax............................................. B-6 Parameters......................................... B-6 Setting Counter Values ............................... B-7 Syntax............................................. B-7 Parameters......................................... B-7 Example............................................ B-7 Retrieving Table Data ................................ B-7 Syntax............................................. B-7 Parameters......................................... B-8 Enabling and Disabling Metrics ....................... B-8 Syntax............................................. B-8 Parameters......................................... B-8 %VPUSER Errors ....................................... B-8 Example of a User-defined Routine .................... B-9 vi C Command-line Recall Feature ZRECALL .............................................. C-2 Format............................................. C-2 Parameters......................................... C-2 Explanation........................................ C-2 Comments........................................... C-4 Related............................................ C-5 /RECALL Command-line Qualifier ....................... C-6 /KEYDEFS Command-line Qualifier ...................... C-6 D WRITE Command for TCP/IP Devices Command Syntax for a DSM Process to Function as a Client............................................. D-1 Command Syntax for a DSM Process to Function as a Server............................................. D-3 Notes.............................................. D-3 Examples 2-1 Running the DSM$UPGRADE Command Procedure .... 2-23 Tables 2-1 Space Requirements (in Blocks) for Installing DSM on VAX Systems............................ 2-3 2-2 Space Requirements (in Blocks) for Installing DSM on Alpha Systems.......................... 2-3 vii 1 ________________________________________________________________ Updates to Version 7.2 of DSM for OpenVMS This chapter describes the new features for Version 7.2 of DSM for OpenVMS. These new features are covered in the following sections: o Prerequisites o New Features o Changes to Existing Functionality Prerequisites DSM is layered on Digital Equipment Corporation's OpenVMS operating systems for VAX and Alpha processors. __________________________________________________________ You_need_to_be_using...____To_install_and_run...__________ OpenVMS VAX Version 6.2, 7.2 of DSM for OpenVMS VAX 7.0, or 7.1 OpenVMS Alpha Version 7.2 of DSM for OpenVMS Alpha 6.2,_7.0,_or_7.1__________________________________________ New Features The following sections discuss new features in Version 7.2 of DSM for OpenVMS. New features include: o ViewPoint User-Defined Metrics o $LIST Functions o Command-line Recall o Reverse $QUERY Function o %DUMP Utility Updates to Version 7.2 of DSM for OpenVMS 1-1 ViewPoint User-Defined Metrics Version 7.1 of DSM for OpenVMS introducted the interface to the ViewPoint performance monitor. ViewPoint is a third-party monitoring utility that provides a graphical user interface for monitoring trends of system activity and analyzing system performance. Version 7.2 of DSM for OpenVMS adds the ability for users to define their own counters. A detailed description of this feature is in Appendix B, ViewPoint User-defined Counters of this document. Command-line Recall DSM V7.2 now implements command-line recall for commands entered in Direct Mode or Break Mode. By default, up to the last 20 command lines entered in these modes are saved in the recall buffer and can be recalled by using the up-arrow key or the DSM ZRECALL command. The command-line recall functionality consists of three elements: o ZRECALL command o /RECALL and /NORECALL command-line qualifiers for DSM command o key definitions file A detailed description of this feature is in Appendix C, Command-line Recall Feature. The following sections provide a brief overview. ZRECALL Command The ZRECALL command, modeled after the OpenVMS DCL RECALL command, recalls lines by number or by specifying the first few characters in the command line to recall. The argumentless form of the command is used to display lines in the recall buffer, starting with the most recent. In the following example, the "D ^CONFIG" command (number 1) is the most recent command while "W $ZV" (number 20) is the oldest: 1-2 Updates to Version 7.2 of DSM for OpenVMS > ZRECALL 1 D ^CONFIG 2 D ^JRNINIT 3 D ^SYS . . 20 W $ZV This example recalls commands that begin with the characters "SE": > ZRECALL SE 3 SET %HD="FF" Command-line Recall Qualifiers The DSM command has been enhanced with two command-line qualifiers that control the number of lines saved in the recall buffer. The DSM /RECALL=n command line qualifier allows you to adjust the maximum number of lines in the recall buffer from 2 lines to 254 lines. For example, use this command to save up to 50 command lines in the recall buffer: $ DSM/RECALL=50 Another qualifier, /NORECALL, allows you to disable the command-line recall feature. For details on the DSM command, see the DSM for OpenVMS Programmer's Guide. ________________________Note ________________________ For applications that start in Application Mode but ZESCAPE to Programmer Mode, you must specify the /RECALL[=n] qualifier to enable the feature. _____________________________________________________ Updates to Version 7.2 of DSM for OpenVMS 1-3 Key Definitions Files Coupled with the command-line recall feature is the ability to equate keyboard keys with DSM command-line strings by loading key definitions from a file. A key definitions file contains DCL DEFINE/KEY commands that associate an equivalence string with a key on the terminal keyboard. To load the key definitions in the file, the DSM command has been enhanced with the /KEYDEFS command-line qualifier. The syntax of this qualifier is: /KEYDEFS=filespec DSM V7.2 provides DSM$DEBUG.KEYDEFS, a sample key definitions file in SYS$EXAMPLES, that equates keys with command strings that are useful in interacting with the DSM debugger. After loading the DSM$DEBUG.KEYDEFS file, press the PF2 key followed by a keypad key to determine the function of the keypad key. Do the same to get help on the "Find", "Insert Here", "Remove", "Select", "Prev Screen", and "Next Screen" keys (if your keyboard is equipped with those keys. For a keypad layout, see Appendix C, Command-line Recall Feature. Notes on Using Command-line Recall Keep the following two caveats in mind when using the DSM command-line recall feature: o When the DSM command line feature is enabled, terminal characteristics are saved upon entry into DSM and then restored when you exit DSM. Therefore, terminal characteristic changes made inside DSM do not persist when the DSM process is terminated. o Due to a problem with an OpenVMS Screen Management routine used to implement command-line recall, the last few characters in a line with one or more characters may continue to be displayed when the up- arrow or down-arrow key is pressed to recall another line. Such characters may be cleared by typing Ctrl/R. Even if you do not clear the characters, they will not be included in the command line when you press Return. 1-4 Updates to Version 7.2 of DSM for OpenVMS $LIST Functions Version 7.2 of DSM for OpenVMS includes six new list functions: o $LIST o $LISTBUILD o $LISTDATA o $LISTFIND o $LISTGET o $LISTLENGTH For a fully detailed description of these functions, see Appendix A, New Intrinsic Functions. Reverse $QUERY Function DSM V7.2 now implements reverse $QUERY to allow applica- tions to perform a reverse physical scan of an array. The $QUERY function takes a new optional integer code argument that indicates the direction of the physical scan: $Q{UERY}(name{,integer_code}) Specifying 1 as the integer code value causes $QUERY to perform a forward scan and is equivalent to the one- argument form of $QUERY. Specifying -1 as the integer code value causes $QUERY to perform a reverse or backward scan of the array. Note that reverse $QUERY support for structured system variable names (SSVNs) has not been implemented. For a detailed description of the enhanced $QUERY function, see Appendix A, New Intrinsic Functions. ________________________Note ________________________ Attempting reverse $QUERY in DSM 7.2 via DDP to earlier 7.x releases will produce erroneous results. Therefore, you should not attempt this operation over DDP with DSM versions earlier than 7.2. _____________________________________________________ Updates to Version 7.2 of DSM for OpenVMS 1-5 %DUMP Utility DSM V7.2 supports a new ^%DUMP utility that dumps the contents of a specified data value in a hexadecimal format. The utility can be invoked in two ways. The first method is to set the variable %DUMP with the data value to dump and execute the default utility entrypoint as follows: > SET %DUMP="ABCDEFGHIJKLMNOPQRSTUVWXYZ" DO ^%DUMP 504F4E4D 4C4B4A49 48474645 44434241 ABCDEFGHIJKLMNOP 0000 00000000 00005A59 58575655 54535251 QRSTUVWXYZ...... 0010 ^^ ^ The second method is to execute the ^%DUMP utility formal list entrypoint as follows: > DO D^%DUMP("ABCDEFGHIJKLMNOPQRSTUVWXYZ") 504F4E4D 4C4B4A49 48474645 44434241 ABCDEFGHIJKLMNOP 0000 00000000 00005A59 58575655 54535251 QRSTUVWXYZ...... 0010 ^^ ^ Note that "^" characters in the last display line identify the last byte in the data value. 1-6 Updates to Version 7.2 of DSM for OpenVMS Changes to Existing Functionality The following sections discuss changes to existing functionality in Version Version 7.2 of DSM for OpenVMS. The changes include: o Precompiled Code Changes Precompiled Code Changes DSM 7.2 changes to the DSM interpreter will require your application routines to be recompiled. The size of precompiled code routines in DSM 7.2 will be slightly increased compared to previous DSM 7.x releases. The actual increase depends on the number of $QUERY, $ZNEXT, and $ZORDER function references and the number of MERGE command references in a particular routine. Documentation Corrections %PRINT Format The format of the DSM %PRINT external routine in the DSM for OpenVMS Language Reference Manual) should be: SET dummy=$&ZLIB.%PRINT(arg1{,arg2,arg3 ... arg10}) where: arg1 name of the file to be printed arg2 optional DCL PRINT command qualifiers arg3 ... up to eight optional /PARAMETER qualifier arg10 parameter values to be passed to the print job Updates to Version 7.2 of DSM for OpenVMS 1-7 2 ________________________________________________________________ Upgrading Your DSM System This chapter provides information about upgrading your system to Version 7.2 of DSM for OpenVMS. It describes the DSM distribution kit and explains the steps you need to take in upgrading your current DSM system. ________________________Note ________________________ You can install Version 7.2 of DSM directly on a DSM for OpenVMS Version 6.4, 6.5, 6.6, 7.0, or 7.1 system. You do not have incrementally install these previous versions before you install Version 7.2. _____________________________________________________ This chapter does not describe the procedures used to install a new DSM system. If you are installing DSM for OpenVMS for the first time, please follow the instructions in Chapter 1 of the DSM for OpenVMS Installation and Management Guide. For more information about managing your DSM system and installing DSM in an alternate root, see the DSM for OpenVMS Installation and Management Guide. For more information about the OpenVMS operating system, see the OpenVMS User's Manual and the OpenVMS System Manager's Manual, published by Digital Equipment Corporation. _______________________ Notes _______________________ DSM for OpenVMS no longer supports versions of OpenVMS prior to OpenVMS Version 6.2. If you are running a version of OpenVMS issued before Version 6.2, you must upgrade your operating system before you can upgrade DSM. Upgrading Your DSM System 2-1 If you are upgrading to DSM 7.x from a pre-DSM 7.0 release, and plan to use a cluster environment, see "Changes to Cluster Installations." _____________________________________________________ DSM Distribution Kit The DSM distribution kit consists of software and documentation. This software and documentation supersedes all material supplied with your previous version of DSM. DSM Version 7.2 is distributed by InterSystems Corporation and through Digital's Condist. InterSystems distributes DSM software on the following media for both DSM for OpenVMS VAX and DSM for OpenVMS Alpha: o 9-track magnetic tape o TLZ06[TM] o TK50[TM] tape cartridge o CD-ROM The DSM software consists of the following: o The DSM interpreter and database handler images o The 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 rebuild user-defined external routines DSM Installation Requirements Installation requirements for DSM are divided into three categories: o Disk space o System resources o Time 2-2 Upgrading Your DSM System Disk Space Requirements To install and use DSM, you must have enough space on your system disk. Table 2-1 lists the total disk space requirements for Version 7.2 of DSM for OpenVMS on VAX systems. Table 2-1 Space Requirements (in Blocks) for Installing __________DSM_on_VAX_Systems______________________________ Peak Installation Net Options_________________________Use___________________Use_ DSM Alone 28000 24000 With DASL 50000 38500 With MWAPI and Windows 30500 25500 With DASL, MWAPI, and Windows 52500 39500 With_all_previous_options_______53000_________________39500 Table 2-2 lists the total disk space requirements for Version 7.2 of DSM for OpenVMS on Alpha systems. Table 2-2 Space Requirements (in Blocks) for Installing __________DSM_on_Alpha_Systems____________________________ Peak Installation Net Options_________________________Use___________________Use_ DSM Alone 39500 26000 With DASL 61500 39500 With MWAPI and Windows 43000 27500 With DASL, MWAPI, and Windows 65000 40500 With_all_previous_options_______66000_________________41500 ________________________Note ________________________ Both tables give the total space required for Version 7.2 of DSM for OpenVMS. They do not list incremental space beyond the requirements for previous versions of DSM. Keep in mind that these tables do not include the added space required for the DSM Bookreader Library. The DSM Bookreader Upgrading Your DSM System 2-3 Library increases the minimum required space for DSM installation by 53000 OpenVMS blocks. _____________________________________________________ System Resource Requirements To successfully install DSM for OpenVMS, you must have the following system resources available: o On DSM for OpenVMS VAX systems: - At least 750 global page table entries - At least 23 global section descriptors - A value of at least 50 as the TQElm quota of the environment manager account (for successful operation of the secondary DCP servers) o On DSM for OpenVMS Alpha systems: - At least 2140 global page table entries - At least 23 global section descriptors - A value of at least 50 as the TQElm quota of the environment manager account (for successful operation of the secondary DCP servers) Disabling the VBSS_ENABLE Parameter (OpenVMS VAX) Because DSM for OpenVMS VAX uses PFN mapping and locks process pages and working set pages into memory, DSM processes are ineligible for VBSS selection. Therefore, you must disable the parameter VBSS_ENABLE on your system. The correct relationship between MAXPROCESSCNT and BALSETCNT is: BALSETCNT = MAXPROCESSCNT-2 Memory Resources for Granularity Hint Regions (OpenVMS Alpha) If you are installing DSM for OpenVMS Alpha on OpenVMS Alpha Version 6.2 or later and wish the DSM images to be installed as resident, you must also ensure that you have reserved sufficient memory resources in the OpenVMS granularity hint regions. See the section "Configuring for Resident Images" for more information. 2-4 Upgrading Your DSM System DSM Time Requirements The time it takes you to install the DSM kit depends on your hardware configuration. However, the average installation takes approximately 15 minutes. Installation Prerequisites The installation and upgrade procedure described in this chapter assumes the following prerequisites: o You have already installed and fully initialized a previous version of DSM. o If you are installing DSM for OpenVMS VAX, you are running OpenVMS VAX Version 6.2 or later. o If you are installing DSM for OpenVMS Alpha, you are running OpenVMS Alpha Version 6.2 or later. Installation Overview The installation and upgrade procedure is divided into three parts: o Preinstallation steps o Installation steps o Postinstallation steps For alternate root installation instructions, see the DSM for OpenVMS Installation and Management Guide. DSM Preinstallation Steps The preinstallation activities consist of the following: o Shut down all running DSM configurations. o Back up your system disk. o Back up the database disks (if possible). o Optionally, disable interactive logins. o Ensure sufficient system resources. The following sections describe these steps in detail. Upgrading Your DSM System 2-5 Shutting Down Running DSM Configurations You must shut down all running DSM configurations down before you install Version 7.2 of DSM for OpenVMS. If you are running DSM in a VMScluster[TM] environment, shut down all running configurations on all nodes of the cluster. See the DSM for OpenVMS Installation and Management Guide for the version of DSM currently running on your system for more information about shutting down configurations. Backing Up Your System InterSystems recommends that you backup your system disk before installing any software layered on the operating system. This is particularly important for upgrade procedures such as this where the existing software is being replaced by the software being installed. Use the backup procedures established at your site. For details about performing a system disk backup, see the OpenVMS System Management Utilities Reference Manual, published by Digital Equipment Corporation. Disabling Interactive Logins You may want to disable interactive logins during the installation procedure. To do so, log into the system manager's account and issue the following DCL command: $ SET LOGINS/INTERACTIVE=0 Determining SYSGEN Requirements for Installation During installation, the DSM for OpenVMS installation procedure checks system resources to ensure that sufficient free GBLPAGES and GBLSECTIONS exist for it to install the DSM images as shared image files. If these system resources are not sufficient, the installation procedure terminates, informing you how much you must increase GBLPAGES or GBLSECTIONS, or both. Check the requirements listed in the section "System Resource Requirements" for the GBLPAGES and GBLSECTIONS requirements. You can compare these requirements for 2-6 Upgrading Your DSM System GBLPAGES and GBLSECTIONS with those of your current version of DSM and increase these parameters accordingly. 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 lines: $ 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 the values for GBLPAGES and GBLSECTIONS are too low, you must take the following steps: 1. Modify your system parameters. 2. Reboot your OpenVMS system 3. Restart the Installation Procedure When adjusting system parameters, add at least the required amount of additional GBLPAGES or GBLSECTIONS needed to the current value of GBLPAGES and GBLSECTIONS. To do this, place the following commands at the end of your SYS$SYSTEM:MODPARAMS.DAT file: ADD_GBLPAGES = n ADD_GBLSECTIONS = n where: n The additional number of GBLPAGES and GBLSECTIONS needed Then, run the SYS$UPDATE:AUTOGEN command procedure to update the SYSGEN parameters, and reboot your system as follows: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT Upgrading Your DSM System 2-7 AUTOGEN makes the necessary SYSGEN modifications and reboots your system. When the system reboots, you can run the software kit installation described in the next section. When you create new DSM configurations, you may also need additional GBLPAGES and GBLSECTIONS. For more information about determining appropriate values for these and other SYSGEN parameters, see the DSM for OpenVMS Installation and Management Guide. DSM Installation Activities The installation activities include the following: o Install the DSM distribution kit on your system using the VMSINSTAL procedure in SYS$UPDATE. If you are upgrading to DSM 7.x from a pre-DSM 7.0 release, and plan to use a cluster environment, see "Changes to Cluster Installations" before running VMSINSTAL. o If you do not run the Installation Verification Procedure (IVP) during VMSINSTAL, install the DSM images as shared images using the DSM$INSTALL.COM procedure in SYS$STARTUP. o Edit the initialization command procedures, DSM$INSTALL.COM and DSM$INSTALL_SITE.COM. o Edit the system startup and shutdown files. Installing the DSM Distribution Kit Use the VMSINSTAL installation procedure to install DSM. The following is a sample installation procedure. Before you begin, mount your distribution medium. Wherever prompted, use the appropriate device mnemonic for that medium. This sample installation procedure uses the device GANDY$DKA0:. 1. Mount the distribution medium. 2-8 Upgrading Your DSM System 2. Log in to your system manager's account and enter the following command line: $@SYS$UPDATE:VMSINSTAL OpenVMS Software Product Installation Procedure Vn.n It is 16-Jan-1999 at 9:22. Enter a question mark (?) at any time for help. In the previous example: xxx VAX if you are installing on an OpenVMS VAX system AXP if you are installing on an OpenVMS Alpha system 3. VMSINSTAL then asks the following question: * Are you satisfied with the backup of your system disk [YES]? If you are satisfied, press Return to accept the default answer of YES. If you need to back up your system, get out of VMSINSTAL by entering N, back up your system, and then restart the installation procedure. 4. VMSINSTAL then asks: * Where will the distribution volumes be mounted: GANDY$DKA0:[DSMMGR] Enter the full specification of where you are going to mount the distribution kit. 5. VMSINSTAL then asks: Enter the products to be processed from the first distribution volume set. * Products: DSMVAX071 *Enter installation options you wish to use (none): Enter the name of the kit, either DSMVAX071 for DSM for OpenVMS VAX or DSMAXP071 for DSM for OpenVMS Alpha. Choose the default for installation options (none). 6. VMSINSTAL displays the following: %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I-RELMOVED, Product's release notes have been moved to SYS$HELP. Upgrading Your DSM System 2-9 7. VMSINSTAL then asks: * Do you want to run the IVP after the installation [YES]? The DSM kit includes an Installation Verification Procedure (IVP) called SYS$TEST:DSM$IVP.COM. VMSINSTAL can optionally run the IVP to verify that DSM has been installed correctly. Press Return to run the IVP (Installation Verification Procedure) after installation. Enter N if you do not want to run the IVP after installation. You can run the IVP manually after running VMSINSTAL by entering @SYS$TEST:DSM$IVP at the DCL prompt. 8. VMSINSTAL asks if you want to include support for the M Windowing API and the X Window System Interface for DSM: * Include support for the M Windowing API and the X Window Interface [YES]? NO The default response is YES. Press Return to include support. Enter N if you do not want to include support. 9. VMSINSTAL asks if you want to install the DSM Application Software Library (DASL) files: * Include DASL files [YES]? The default response is YES. Press Return to include the DASL files. Enter N if you do not want to include the DASL files. ________________________Note ________________________ For more information about installing and setting up DASL, see the DASL Management Guide. _____________________________________________________ 10.VMSINSTAL then displays the following question: * Do you want to purge files replaced by this installation [YES]? The default response to this question is YES. Press Return to accept the default and purge all previous DSM files that VMSINSTAL replaces with the new DSM files. If you allow old DSM files to remain on DISK, you are wasting valuable disk space. 2-10 Upgrading Your DSM System 11.VMSINSTAL then displays the following informational message: No further questions will be asked during this installation 12.VMSINSTAL then begins the installation and displays informational messages on your terminal during each phase of this part of the installation procedure. Beginning installation of DSMVAX V7.2 at 09:17 Begin installation of DSM base components ----------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set B ... Linking the DSM base images . . . The following files will be created or updated . . . Begin installation of X Windows and M Windowing API components -------------------------------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set C ... . . . . Begin installation of DASL components ------------------------------------- %VMSINSTAL-I-RESTORE, Restoring product save set D ... . . . %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... Installing DSM$SHARE and DSM$SHRLIB images as shareable Calling DSM Installation Verification Procedure Upgrading Your DSM System 2-11 Installation Verification Procedure for DSM Copyright (c) Digital Equipment Corporation, 1992 DSM x.x for OpenVMS VAX DSMMGR [Baseline] DSM x.x for OpenVMS VAX IVP Successful %DSM-I-HALT, HALT command executed DSM installation is complete. You may enter the following command line to initialize a manager account for use with DSM: @SYS$MANAGER:DSM$INIT Installation of DSMVAX x.x completed at 09:20 13.If the installation fails for any reason, VMSINSTAL displays an appropriate informational message. For information about installation failure messages, see the OpenVMS System Messages: Companion Guide for Help Message Users, published by Digital Equipment Corporation. Take any action required by the message. 14.The VMSINSTAL menu appears and asks if you have another kit to install. Press Ctrl/Z to exit. The DSM software kit installation procedure is now complete. During the installation process the file, DSM071.RELEASE_NOTES, is moved to the SYS$HELP directory. DSM071.RELEASE_NOTES is identical to this document. You can print it on a printer. Installing DSM Shared Images To run DSM, you must install the supplied DSM images as shared images. Image installation reduces memory utilization, reduces DSM image activation time, and conserves system resources. If you ran the IVP during kit installation, the images are installed before the IVP executes. If you did not run the IVP during kit installation, use the 2-12 Upgrading Your DSM System SYS$STARTUP:DSM$INSTALL.COM procedure to install the DSM images. Log in to a privileged OpenVMS account that has the CMKRNL privilege. Run the DSM$INSTALL command procedure by entering the following command: $ @SYS$STARTUP:DSM$INSTALL Installing DSM Images as Resident (OpenVMS Alpha Only) When running under OpenVMS Alpha Version 6.2 and later, Version 7.2 of DSM for OpenVMS supports the installation of the SYS$SHARE:DSM$SHARE.EXE and SYS$SHARE:DSM$SHRLIB.EXE images as resident. Installation of the DSM images as resident can result in significant reduction in memory usage as well as increased system throughput. Overview The OpenVMS Alpha Version 6.2 Install procedure allows you to install images and associated address fixup vectors as resident. The Install procedure places resident images in OpenVMS Alpha system address space and resolves all image address linkage sections at install time. The image and address linkages are loaded into OpenVMS memory sections known as granularity hint regions. Using granularity hint regions has the following benefits: o The number of shareable image pages is increased, resulting in a reduction of total physical memory utilization system-wide. o The hardware efficiency of virtual address resolution is greatly enhanced. The SYS$STARTUP:DSM$INSTALL.COM procedure attempts to in- stall the SYS$SHARE:DSM$SHARE.EXE and SYS$SHARE:DSM$SHRLIB.EXE images, along with other associated OpenVMS system library images, as resident when the following conditions are met: o The operating system is OpenVMS Alpha Version 6.2 or later. o Versions of the DSM images are not already installed as shared or resident. (See the section "Replacing DSM Images Already Installed as Resident" if you have already installed DSM images as shared or resident.) Upgrading Your DSM System 2-13 o The OpenVMS granularity hint regions have suffi- cient memory resources reserved. (See the section "Configuring for Resident Images.") If any of these conditions are not met, DSM$INSTALL.COM installs the DSM images as shareable, but not resident. DSM operations are possible; but the benefits of resident image installation will not be realized. Configuring for Resident Images You must take the following steps to configure your OpenVMS Alpha Version 6.2 system for the installation of DSM images as resident. 1. Add the following lines to your SYS$SYSTEM:MODPARAMS.DAT file: ADD_GH_RSRVPGCNT = 180 ADD_IMGREG_PAGES = 1500 2. Run the SYS$UPDATE:AUTOGEN.COM procedure to incorporate the changes into your OpenVMS environment and reboot the system: $ @SYS$UPDATE:AUTOGEN GETDATA REBOOT NOFEEDBACK 3. Run the SYS$STARTUP:DSM$INSTALL.COM procedure to install the DSM images as resident: $ @SYS$STARTUP:DSM$INSTALL The VMSINSTAL procedure will fail to install DSM or system images as resident if sufficient memory does not exist in the OpenVMS resident image code region. In some configurations, the value of 180 pages may be too low for the GH_RSRVPGCNT system parameter. Therefore, use the DCL command, SHOW MEMORY/GH_REGION, after rebooting and before you run DSM$INSTALL.COM to evaluate whether sufficient memory in the resident image code region is available. The value listed for free resident image code region pages must be at least 180. If this is not the case, take the following steps: 1. Increase the value of GH_RSRVPGCNT accordingly in your MODPARAMS.DAT file. 2. Run SYS$UPDATE:AUTOGEN. 2-14 Upgrading Your DSM System 3. Reboot your system. You may also have to increase the value of IMGREG_PAGES greater than the suggested value of 1500. Replacing DSM Images Already Installed as Resident The Install procedure does not permit the replacement of images already installed as resident. To install a new copy of DSM$SHARE.EXE and DSM$SHRLIB.EXE when existing versions of these images are already installed resident, you must first deinstall the previous versions as resident. You can Reboot your OpenVMS system to deinstall the images as resident. See the Digital Equipment Corporation publication, OpenVMS System Manager's Manual: Essentials for more information. Upgrading Your DSM System 2-15 Installing DSM in a VMScluster Environment If you are upgrading to DSM 7.x from a pre-DSM 7.0 release and plan to use a cluster environment, see "Changes to Cluster Installations" before running VMSINSTAL. If you are installing DSM on a node in a VMScluster environment, you must log in to the system manager's account on each node that will be running DSM and do the following: 1. Enter the following DCL command to rename any previous copies of DSM$INSTALL.COM that exist in the system- specific root: $ RENAME SYS$SPECIFIC:[SYS$STARTUP]DSM$INSTALL.COM;* .OLD;* Create DSM$INSTALL_SITE.COM in the system-specific root. You can merge any site-specific information from previous versions of DSM$INSTALL_SITE.COM into DSM$INSTALL_SITE.COM. $ COPY SYS$COMMON:[SYS$STARTUP]DSM$INSTALL.OLD SYS$SPECIFIC:[SYS$STARTUP] 2. Install DSM shared images by entering the following: $ @SYS$STARTUP:DSM$INSTALL Installation of the DSM images using the DSM$INSTALL command procedure requires minimum SYSGEN parameter values for GBLPAGES and GBLSECTIONS. If you are unable to successfully run DSM$INSTALL on all VMScluster nodes, you have to modify these SYSGEN parameters on the affected node and reboot that node. For more information, see the section "Determining SYSGEN Requirements for Installation" in this chapter. You can also use the OpenVMS System Management Utility (SYSMAN) to perform these steps from your local node by defining your management environment to be: o A particular node o A group of nodes o A cluster 2-16 Upgrading Your DSM System For more information, see the OpenVMS System Manager's Manual. Changes to Cluster Installations In versions of DSM earlier than 7.0, it was possible to install DSM on one node of a cluster and allow other nodes with the same architecture and system directories to use the installed software. It was not necessary to run the VMSINSTAL procedure on each node. In DSM V7.x, this process remains essentially unchanged. However, changes in DSM 7.x licensing require that each node of the cluster has a directory named DSM$LICENSE in the SYS$SPECIFIC file area. The creation and protection of this directory is usually performed by the software installation, but the install procedure only creates this directory for the node on which it is run. Before attempting to install the license key on a node where VMSINSTAL has not been run, you must first run the procedure SYS$MANAGER:DSM$CD_LICENSE.COM to ensure that the DSM$LICENSE directory is created and given the proper protection. This command procedure should be run from the system manager's account, but will set the directory protection such that any DSM manager's account can enter and edit the license key. DSM$CD_LICENSE.COM only needs to be used for the first upgrade or install of DSM V7.x. Once the directory has been created, subsequent upgrades will not require this step. DSM Postinstallation Activities The postinstallation activities consist of the following: 1. Upgrading the external call package table image to include user-written external routines. 2. Logging in to the DSM environment manager's account and running the SYS$MANAGER:DSM$UPGRADE.COM procedure. This procedure upgrades configuration definitions and volume sets created under previous versions of DSM. Upgrading Your DSM System 2-17 Optionally, you can have it reinitialize Before Image Journaling (BIJ) and After Image Journaling (AIJ) files and rebuild mapped routine sets. ________________________Note ________________________ If you do not choose to have DSM$UPGRADE.COM reini- tialize BIJ and AIJ files and rebuild mapped routine sets, run ^BIJINIT to reinitialize the before-image journal file, run ^JRNINIT to reinitialize the after-image journal files, and run ^RMBLD to rebuild mapped routine sets. _____________________________________________________ 3. Editing the startup and shutdown command procedures to provide for automatic startup and shutdown of DSM configurations when your system is booted. 4. Rebooting your OpenVMS system to reload the DDP driver (if you are using DDP). 5. Starting the upgraded configurations. Establishing Your License Unlike the licensing method used by Digital Equipment Corporation, you specify your license after installation /upgrade of your DSM software. If you are using only terminal licenses for your system, you need only run the new ^SYSMAN utility, ^LMFEDIT, in one configuration on each host in your network. ^LMFEDIT lets you enter new license information or edit existing license information. If you are upgrading to DSM 7.x from a pre-DSM 7.0 release, and plan to use a cluster environment, see "Changes to Cluster Installations." You must run DSM$CD_ LICENSE.COM before establishing your license. The following sections describe how to run ^LMFEDIT for any type of license. 2-18 Upgrading Your DSM System Entering/Editing a License You use the ^LMFEDIT utility to establish your licenses. You do so once for each host in any configuration that will run DSM for Open VMS 7.x. You only need to enter the license once on each node, even if that node is running multiple DSM environments. All environments on the node will share the same license. Take the following steps: 1. Invoke ^SYSMAN, the System Management Utilities. 2. Choose option 3, LICENSE EDIT. You see the current license data for this configuration, if any. 3. Specify that you want to edit the data If no license data exists, fill the required items in as prompted. If license data does exist, press Return to accept any existing data or enter new data as prompted. When you need to erase exising data, enter a dash ("-") to delete the data. 4. Save the data when prompted. You then return to the System Management Utilities menu. The following example shows how you use ^LMFEDIT to add or update license data for a configuration. System Management Utilities 1. ACCESS CONTROL (^ACL) 2. FORCE EXIT (^FORCEX) 3. LICENSE EDIT (^LMFEDIT) 4. LOCK TABLE CLUSTER DISPLAY (CLUSTER^LOCKTAB) 5. LOCK TABLE DISPLAY (^LOCKTAB) 6. LOGIN (^LOGIN) 7. MEMORY (^MEMORY) 8. SHOW DSM USERS (^%SY) 9. SHUTDOWN (^SHUTDWN) 10. STARTUP (^STU) 11. TIED ROUTINES (^TIED) Select Option > 3. LICENSE EDIT Current license values: Upgrading Your DSM System 2-19 Customer Name = BIGDSM Order # = 0 Product Auth. Key = A52BF8C7199 Expiration Date = 2/25/2020 Machine Type = 41 Machine ID = Terminal = 500 Multi-User = 0 Single-User = 0 Server = 0 Workgroup = 0 Client-Server (Primary) = 0 Client-Server (Additional) = 0 Enterprise = 0 Division = 0 Edit these values now [Y OR N] ? Y Customer Name ? Enter the data for Customer Name from your DSM license. (enter "^" for previous question, enter "-" to erase default data) Customer Name Order # <0> Product Auth. Key Expiration Date <2/25/2020> Machine Type <41> Machine ID > Multi-User <0> Terminal <500> Single-User <0> Server <0> Workgroup <0> Client-Server (Primary) <0> Client-Server (Additional) <0> Enterprise <0> Save data to license file [Y OR N] ? > Y License file updated. 2-20 Upgrading Your DSM System Upgrading DSM Configurations and Volume Sets You must upgrade configuration definitions, volume sets, mapped routine sets, and journal files created under previous DSM releases. They are not compatible with Version 7.x of DSM for OpenVMS. To do so, you use the SYS$MANAGER:DSM$UPGRADE.COM. The DSM$UPGRADE command procedure automates the upgrade procedure. DSM$UPGRADE takes the following steps: 1. Modifies database set definitions DSM$UPGRADE upgrades database set definitions for each volume set. DSM$UPGRADE makes minor modifications and adds field definitions to the existing database set definitions. 2. Reinitializes after-image and before-image journal files. You must reinitialize after-image journal (AIJ) files and before-image journal (BIJ) files used with previous versions of DSM. You can choose to reinitialize the before-image and the after-image journal files: o Now, while running DSM$UPGRADE.COM o Later, using the ^BIJINIT utility to upgrade the BIJ files and ^JRNINIT to upgrade the AIJ files 3. Recompiles application routines Because of internal changes, you need to recompile all of your DSM routines after you upgrade to Version 7.2 of DSM for OpenVMS from any previous version. 4. Upgrades mapped routine sets (not necessary when upgrading from DSM V7.x to DSM V7.2.) You must rebuild mapped routine sets either: o Now, while running DSM$UPGRADE.COM o Later, running the ^RMBLD utility After the configuration upgrade is complete, DSM$UPGRADE generates DCL command procedures to upgrade each of the volume sets in the configuration. (DSM$UPGRADE creates one command procedure for each volume set.) Each command Upgrading Your DSM System 2-21 procedure take the following steps to upgrade its specific volume set: 1. Removes obsolete utilities from the manager UCI. 2. Replaces DSM System and Library Utilities in the manager UCI of the volume set. 3. Recompiles all volume-set routines in all UCIs so that they are compatible with Version 7.2 of DSM for OpenVMS. 4. Marks the volume set as upgraded, so that it can be mounted as part of a Version 7.2 configuration. The amount of time that this procedure takes depends on the size of the volume set and, in particular, the number of volume set routines that must be recompiled. ________________________Note ________________________ You must have at least 5200 free blocks on all volume sets that you want to upgrade to system volume sets. Use the fast ^DBT Utility to determine the number of free blocks. Use the EXTEND^VOLMAN Utility to extend the volume set if you do not have enough free blocks. A volume set that was upgraded on DSM for OpenVMS VAX can be mounted on a DSM for OpenVMS Alpha system and vice versa without having to upgrade the volume set again. Note that the volume label only reflects the machine that the volume set was upgraded on. _____________________________________________________ Running DSM$UPGRADE.COM Example 2-1 shows how to use the DSM$UPGRADE command procedure to upgrade a configuration and its associated volume sets. If your application includes user-written external routines, then you should rebuild and install your private external routine package table (DSM$ECALL.EXE) before starting the upgrade. This allows proper recompilation of all application routines during the upgrade. 2-22 Upgrading Your DSM System Example 2-1 Running the DSM$UPGRADE Command Procedure $ @SYS$MANAGER:DSM$UPGRADE DSM Configuration Upgrade Enter the configuration identifier MAIN Configuration MAIN is not compatible with the current version of DSM Do you want to upgrade this configuration now [Y OR N] ? > Y CONFIGURATION UPGRADE Do not modify ANY configurations or database sets until this upgrade has completed. An upgrade report is generated and displayed. At that time, you can abort this upgrade procedure without having made any changes to configuration MAIN. Output Device ? Copying configuration MAIN into temporary area... Generating upgrade report for configuration MAIN Sending report to DSM$CONUPG_MAIN.TXT Displaying generated upgrade report ** GENERATED UPGRADE REPORT FOR CONFIGURATION MAIN ** Are you ready to upgrade configuration MAIN [Y OR N] ? Y Copying upgraded configuration to MAIN... Upgrade has completed successfully for configuration MAIN. The configuration definition has been upgraded to the current DSM configuration format. You must answer the following questions in order to complete the upgrade process. You can use the default responses in all cases. (continued on next page) Upgrading Your DSM System 2-23 Example 2-1 (Cont.) Running the DSM$UPGRADE Command Procedure Enter the number of disk buffers <800> Use nonpaged memory for these buffers [Y OR N] ? Enter the maximum number of DSM users <128> Enable configuration access control [Y OR N] ? > Y Include support for Routine/Global Performance Histograms [Y OR N] ? Modify database sets included in this configuration [Y OR N] ? Include support for Distributed Data Processing [Y OR N] ? Modify global characteristics [Y OR N] ? Include support for mapped routines [Y OR N] ? Modify DSM default command line qualifiers [Y OR N] ? Modify Global Translation Tables [Y OR N] ? Modify $H data for this configuration [Y OR N] ? *** Configuration MAIN defined Volume set upgrade procedures will now be created for each volume set included in the configuration. You can direct the upgrade procedure to initialize your AIJ and BIJ files, to recompile your application routines, or to rebuild your mapped routine files. SYSTEM volume sets are initialized with an MGR UCI and a complete set of DSM system management globals and routines. APPLICATION volume sets are created with a single empty UCI named LIB. APPLICATION volume sets cannot be mounted as the 1st (S0) volume set within a configuration. Enter YES to upgrade all volume sets as SYSTEM volume sets, loading all new DSM utilities and globals in each configuration volume set. Enter NO to upgrade only the first mounted volume set as a SYSTEM volume set. Existing routines and globals will be removed from all other volume sets making them APPLICATION volume sets. Upgrade all volume sets as SYSTEM volume sets [Y OR N] ? N **** WARNING **** ! THIS OPERATION REMOVES ALL USER GLOBALS AND ROUTINES FROM UCI #1 (MGR) ! ----------------------------------------------------------------------- (continued on next page) 2-24 Upgrading Your DSM System Example 2-1 (Cont.) Running the DSM$UPGRADE Command Procedure This operation will REMOVE ALL user as well as system supplied globals and routines from UCI #1 of each volume set upgraded to an application volume set. If UCI #1 was previously named MGR, it will be renamed to LIB. IF YOU HAVE APPLICATION SPECIFIC DATA OR ROUTINES STORED IN UCI #1, DISCONTINUE THIS OPERATION AND CHOOSE SYSTEM VOLUME SET UPGRADE. Do you want to continue [Y OR N] ? > Y Do you want to reinitialize associated AIJ and BIJ files [Y OR N] ? > Y Do you want to recompile your application routines [Y OR N] ? > Y Do you want to rebuild mapped routine files [Y OR N] ? > Y Writing upgrade procedure for volume set AAA in file DISK$USER:[DSMMGR]DSM$VOLUPG_AAA.COM;1 DSM$VOLUPG_AAA.COM Procedure Complete Writing master upgrade procedure for all volume sets in file DISK$USER:[DSMMGR]DSM$ALLUPG_MAIN.COM;16 DSM$ALLUPG_MAIN.COM procedure complete You can use the generated command procedures to upgrade each of the volume sets individually at any time. If you want to upgrade all of the volume sets included in configuration MAIN, you can do so now. Upgrade configuration volume sets now [Y OR N] ? > Y The following information will be used to upgrade this volume set to DSM for OpenVMS VAX Version 7.2: Volume Set: AAA Type: OpenVMS Upgrading to: DSM for OpenVMS VAX V7.2 system volume set Volume Files: DISK$DATA:[DSMMGR.DATABASE]AAAVOL1.GLS DISK$DATA:[DSMMGR.DATABASE]AAAVOL2.GLS DISK$DATA:[DSMMGR.DATABASE]AAAVOL3.GLS ALL FURTHER QUESTIONS WILL BE AUTO-ANSWERED. ======================================================================= (continued on next page) Upgrading Your DSM System 2-25 Example 2-1 (Cont.) Running the DSM$UPGRADE Command Procedure DSM volume set upgrade Type ? for HELP at any time Enter the name of the volume set to upgrade > Do you have a satisfactory backup copy of this volume set [Y OR N] ? > Is this a DSM-11 compatible disk [Y OR N] ? SYSTEM volume sets are initialized with an MGR UCI and a complete set of DSM system management globals and routines. APPLICATION volume sets are created with a single empty UCI named LIB. APPLICATION volume sets cannot be mounted as the 1st (S0) volume set within a configuration. Upgrade all volume sets as SYSTEM volume sets [Y OR N] ? **** WARNING **** This operation removes all system and user globals and routines from the MGR UCI of volume sets upgraded to an application volume set. The MGR UCI is then renamed to LIB. Do you want to continue [Y OR N] ? > Enter the number of volumes in this volume set <3> File name of AAA volume 1 File name of AAA volume 2 File name of AAA volume 3 Starting DSM configuration V71UPG Mounting Volume Set AAA with 3 volumes Mounting DISK$DATA:[DATABASE.DATABASE]AAAVOL1.GLS as Volume 1 with 10 maps Mounting DISK$DATA:[DATABASE.DATABASE]AAAVOL2.GLS as Volume 2 with 5 maps Mounting DISK$DATA:[DATABASE.DATABASE]AAAVOL3.GLS as Volume 2 with 5 maps 1 Volume Set mounted (continued on next page) 2-26 Upgrading Your DSM System Example 2-1 (Cont.) Running the DSM$UPGRADE Command Procedure DSM Write Demon ... Started as DSM_DEMON_1 (PID = 20200158) DSM Garbage Collector ... Started as DSM_GARCOL_1 (PID = 20200159) Starting DSM volume set upgrade... Removing obsolete utilities ... Loading system utilities ... Loading library utilities ... Loading library globals ... Initializing DISK$USER:[DSMMGR.JOURNAL]AAAJRN1.DAT;1 for use as a DSM Journal file ... Total size of file in 512 byte blocks = 100 Initializing DISK$USER:[DSMMGR.JOURNAL]DSMAAA.BIJ ... Do you want to recompile your application routines [Y OR N] ? Y Compiling routines in [MGR,AAA] %APPL1 %APPL2 %APPL3 %APPL4 %APPL5 %APPL6 %APPL7 %APPL8 %APPL9 9 routines recompiled Compiling routines in [AAA,AAA] AAAPGM1 AAAPGM2 AAAPGM3 AAAPGM4 AAAPGM5 AAAPGM6 AAAPGM7 AAAPGM8 PGM1 PGM2 PGM3 PGM4 12 routines recompiled DSM shutdown complete Volume set upgrade complete Editing the Startup and Shutdown Command Procedures You need to edit the system startup and shutdown command procedures to provide for automatic startup and shutdown of DSM configurations. The procedures you edit are: o The DSM initialization command procedures Upgrading Your DSM System 2-27 o The OpenVMS system startup command procedure o The DSM shutdown command procedure The DSM Initialization Command Procedures DSM uses two command procedures: o DSM$INSTALL.COM o DSM$INSTALL_SITE.COM DSM$INSTALL.COM The DSM$INSTALL.COM procedure contains mandatory operations that install and initialize the DSM software at system boot time. These operations include the following: o Installing DSM images as shared o Loading the DSM DDP driver o Defining search lists for DSM logical name tables o Initializing the DEC DB Integrator Gateway for DSM environment o Calling the DSM$INSTALL_SITE.COM procedure Do not edit DSM$INSTALL.COM. DSM$INSTALL.COM is replaced with a new version by the DSM installation procedure when you upgrade to future releases of DSM. DSM$INSTALL_SITE.COM DSM$INSTALL_SITE.COM is a template procedure. You edit it to execute site- and system-specific capabilities at system boot. You can customize a separate copy of DSM$INSTALL_SITE.COM for each node in a VMScluster and place them in the system-specific root. DSM$INSTALL_SITE.COM can perform the following operations: o Install the optional ECALL default package table image o Run DSM in a heterogeneous VMScluster environment o Allocate physical pages for disk buffer use o Mount DSM-11 compatible disks o Create a batch queue for DSM startup o Start up predefined DSM configurations 2-28 Upgrading Your DSM System DSM$INSTALL_SITE.COM has a detailed description of how you can customize it for your site and enable the relevant capabilities. However, the actual DCL commands used in the examples are disabled with a comment character at the beginning of each line. When you install future versions of DSM, the changes you make to this file will not be lost as future upgrade procedures will continue to preserve past DSM$INSTALL_ SITE.COM files. Editing the Procedures DSM$INSTALL_SITE.COM is a procedure introduced in Version 6.2 of DSM for OpenVMS. Previous versions required you to modify DSM$INSTALL.COM to include site-specific commands. When you install Version 7.2 of DSM for OpenVMS, your existing DSM$INSTALL_SITE.COM is not replaced during installation. Any changes you have already made to DSM$INSTALL_SITE.COM are preserved. You must merge your edits from the old copy of DSM$INSTALL_SITE.COM into the version of DSM$INSTALL_SITE.COM supplied with Version 7.2. The System Startup Command Procedure You must edit your OpenVMS system startup command procedure, SYSTARTUP_VMS.COM, in SYS$STARTUP: to include the following command line to execute DSM$INSTALL.COM: $ @SYS$STARTUP:DSM$INSTALL The DSM Shutdown Command Procedure The SYS$MANAGER:DSM$SHUTDOWN.COM procedure shuts down a DSM configuration. You must edit the system shutdown command procedure, SYS$MANAGER:SYSHUTDWN.COM, to call the DSM$SHUTDOWN procedure and automatically shut down running DSM configurations when your system is shut down. Include the following command line in the SYS$MANAGER:SYSHUTDWN.COM file: $ @SYS$MANAGER:DSM$SHUTDOWN p1 where: p1 The name of the DSM environment manager's account Upgrading Your DSM System 2-29 You must include the previous command line in the SYS$MANAGER:SYSHUTDWN.COM procedure for each DSM environment that is initialized. This ensures that any active DSM volumes are dismounted in an orderly fashion before the system shuts down. ________________________Note ________________________ If you fail to include @SYS$SYSTEM:DSM$SHUTDOWN in your system shutdown command file for each DSM environment, database degradation can result. _____________________________________________________ 2-30 Upgrading Your DSM System A ________________________________________________________________ New Intrinsic Functions This appendix provides reference descriptions of the six new list functions: o $LIST o $LISTBUILD o $LISTDATA o $LISTFIND o $LISTGET o $LISTLENGTH The revised description of the $QUERY function is also included in this appendix. New Intrinsic Functions A-1 $LIST Function Syntax $LIST(list{,position{,end}}) Description $LIST returns elements from a list. The elements returned depend on the parameters you use: o $LIST(list) returns the first element in list. o $LIST(list,position) returns the value of the element indicated by position. The position argument must evaluate to an integer. o $LIST(list,position,end) returns a sublist containing the position through end elements of list. Parameters list An expression that evaluates to a valid list, otherwise a %DSM-E-LIST error can occur. position An expression interpreted as a position. If position is 0 and end is specified, the effective position is 1. If position is 0 and end is not specified, the SET command has no effect. If position is -1, it is equivalent to specifying the final element of the list. If position is less than -1, you receive a %DSM-E-FUNC error. If position is greater than $LISTLENGTH(list), you receive a zero-element list. end An expression interpreted as a position. If end is less than -1, you receive a %DSM-E-FUNC error. If end is -1 or is greater than the number of elements in the list, end is the position of the final element in the list. If the effective end is less than the effective position, the SET command will have no effect. A-2 New Intrinsic Functions Examples The following example returns the value "Blue": SET X=$LISTBUILD("Red","Blue","Green") WRITE $LIST(X,2) The following example returns a two-element list whose elements are "Brown" and "Black": SET X=$LISTBUILD("Red","Blue","Green") WRITE $LIST(X,2) Notes Errors for Invalid Lists If the list argument is not a valid list, you can receive a %DSM-E-LIST error. If you specify an invalid position or end (as specified above), you can receive a %DSM-E-FUNC error. With the one- and two-argument forms of $LIST, if position is 0, then a %DSM-E-NULLVALUE error occurs. In addition, if position identifies an element with an undefined value, a %DSM-E-NULLVALUE error occurs. For example, if X is initialized as follows: SET X=$LISTBUILD("A",,"C") Then the following yield %DSM-E-NULLVALUE errors: $LIST("") $LIST(X,2) Differences between Two-Argument $LIST and Three-Argument $LIST $LIST(list,1) is not equivalent $LIST(list,1,1) because the left-hand side returns a string while the right-hand side returns a single-element list. Furthermore, the left- hand side can receive a %DSM-E-NULLVALUE error whereas the right-hand side can not. New Intrinsic Functions A-3 Related Topics o $LISTBUILD function o $LISTDATA function o $LISTFIND function o $LISTGET function o $LISTLENGTH function A-4 New Intrinsic Functions $LISTBUILD Function Syntax $LISTBUILD(element,...) $LB(element,...) Description $LISTBUILD takes a variable number of arguments and returns a list with one element for each argument. Parameters element Any expression. Examples The following examples produce three-element lists: $LISTBUILD("Red","Blue","Green") $LISTBUILD(1,12.45,"Hello") Notes Omitting Arguments Omitting an argument yields an element whose value is undefined. For example, the following statement produces a three-element list whose second element has an undefined value. (Referencing the second element with $LIST produces a %DSM-E-NULLVALUE error.) $LISTBUILD("Red",,"Green") Note that this is not the same as the statement: $LISTBUILD("Red","","Green") This last statement produces a three-element list whose second element is a zero-length string. Similarly, the following statement produces a two-element list whose first element is "Red" and whose second element has an undefined value: $LISTBUILD("Red",) New Intrinsic Functions A-5 If a $LISTBUILD argument is undefined, the corresponding list element has an undefined value. This example produces the same two-element list whose first element is "Red" and whose second element has an undefined value: KILL Z SET X=$LISTBUILD("Red",Z) Using Zero Arguments Calling $LISTBUILD with zero arguments, that is, $LISTBUILD(), returns a list with one element whose data value is undefined. Nesting Lists You can nest lists. In other words, an element of a list may itself be a list. For instance, the following statement produces a three-element list whose third element is a two-element list: $LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan")) Concatenating Lists The result of concatenating two lists with the binary Concatenation operator is another list. For example, consider the following concatenation operation: $LISTBUILD("A","B")_$LISTBUILD("C") This operation produces a result that is equivalent to: $LISTBUILD("A","B","C") Keep in mind also that a zero-length string is an empty (zero-length) list. Consider the following operation: $LISTBUILD("A","B")_"" This is equivalent to the following: $LISTBUILD("A","B") Note that: o $LISTBUILD("A","B")_$LISTBUILD("") is not equivalent to $LISTBUILD("A","B") o $LISTBUILD("A","B")_$LISTBUILD() is not equivalent to $LISTBUILD("A","B"). This is because the left-hand expressions produce three- element lists while the right-hand expressions produce two-element lists. A-6 New Intrinsic Functions Related Topics o $LIST function o $LISTDATA function o $LISTFIND function o $LISTGET function o $LISTLENGTH function New Intrinsic Functions A-7 $LISTDATA Function Syntax $LISTDATA(list{,position}) $LD(list{,position}) Description $LISTDATA indicates whether an element is present in list and has a value. $LISTDATA returns a value of 1 if the element indicated by position is in list and has a data value. $LISTDATA returns a value of a 0 if the element indicated by position is not in list or does not have a data value. If you omit position, position one (1) is assumed. If position is 0 or is greater than the number of elements in list, then $LISTDATA returns a zero (0). Parameters list An expression that evaluates to a valid list, otherwise a %DSM-E-LIST error can occur. position An expression interpreted as a position. If position is -1, position is equal to the last element of the list. If position is 0, $LISTDATA returns 0. If position is less than -1, you receive a %DSM-E-FUNC error. Examples The following examples show how position affects your results. For instance, consider a situation in which X is initialized as follows: SET X=$LISTBUILD("Red","Green") The following statements return a value of zero (0): W $LISTDATA(X,2) W $LISTDATA(X,4) W $LISTDATA("") W $LISTDATA(X,0) A-8 New Intrinsic Functions The following statements return a value of one (1): W $LISTDATA(X,3) W $LISTDATA(X,-1) Notes Errors for Invalid Lists If you specify an invalid position (as specified above), you can receive a %DSM-E-FUNC error. Related Topics o $LIST function o $LISTBUILD function o $LISTFIND function o $LISTGET function o $LISTLENGTH function New Intrinsic Functions A-9 $LISTFIND Function Syntax $LISTFIND(list{,value{,startafter}}) $LF(list{,value{,startafter}}) Description $LISTFIND searches list for value. The search begins with the element after startafter. If you omit startafter, $LISTFIND assumes a startafter value of zero (0) and starts the search with the first element. If value is found, $LISTFIND returns the position of the matching element. If value is not found, $LISTFIND returns a zero (0). If startafter equals -1 or if startafter is greater or equal to $LISTLENGTH(value), $LISTFIND returns zero (0). Parameters list An expression that evaluates to a valid list, otherwise a %DSM-E-LIST error can occur. value An expression containing the element to find. startafter An expression interpreted as a position. If startafter equals -1 or if startafter is greater than or equal to the number of elements in the list, $LISTFIND returns 0. If startafter is less than -1, you receive a %DSM-E-FUNC error. Examples The following example displays all occurrences of the string "val" within a list: SET X=0 FOR SET X=$LISTFIND(list,val,X) QUIT:X=0 WRITE !,"Found",$LIST(list,X) Keep in mind that $LISTFIND only matches complete elements within the string. Thus, the following example returns zero (0) because no element of the list is equal to the string "A": $LISTFIND($LISTBUILD("ABC","DEF"),"A") A-10 New Intrinsic Functions New Intrinsic Functions A-11 Notes Errors for Invalid Lists If the list argument is not a valid list, you can receive a %DSM-E-LIST error. If you specify an invalid startafter (as specified above), you can receive a %DSM-E-FUNC error. Related Topics o $LIST function o $LISTBUILD function o $LISTDATA function o $LISTGET function o $LISTLENGTH function A-12 New Intrinsic Functions $LISTGET Function Syntax $LISTGET(list{,position{,default}}) $LG(list{,position{,default}}) Description $LISTGET is identical to the one- and two-argument forms of $LIST except that, under circumstances that would cause $LIST to produce a %DSM-E-NULLVALUE error, $LISTGET returns default or, if you omit default, a zero-length string. For example, the following returns a question mark (?): W $LISTGET($LISTBUILD("A",,"C"),2,"?") The following returns a zero-length string: W $LISTGET($LISTBUILD("A",,"C"),2) Parameters list An expression that evaluates to a valid list. position An expression interpreted as a position. If position is -1, position is equal to the last element of the list. If position is less than 1, you receive a %DSM-E-FUNC error. value An expression that provides the value to return is the list element has an undefined value. Notes Errors for Invalid Lists If the list argument is not a valid list, you can receive a %DSM-E-LIST error. If you specify an invalid position, you can receive a %DSM-E-FUNC error. New Intrinsic Functions A-13 Related Topics o $LIST function o $LISTBUILD function o $LISTDATA function o $LISTFIND function o $LISTLENGTH function A-14 New Intrinsic Functions $LISTLENGTH Function Syntax $LISTLENGTH(list) $LL(list) Description $LISTLENGTH returns the number of elements in list. Parameters list Any expression that evaluates to a list. Examples The following example returns a three: W $LISTLENGTH($LISTBUILD("Red","Blue","Green")) The following example returns a zero (0) because a zero- length string is a valid (zero-element) list: W $LISTLENGTH("") Notes Errors for Invalid Lists If list is not a valid list, you may receive a %DSM-E-LIST error. $LISTLENGTH and Nested Lists $LISTLENGTH does not recognize nested lists. Therefore, the following example returns a three: > SET X=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan")) > W $LISTLENGTH(X) 3 New Intrinsic Functions A-15 Related Topics o $LIST function o $LISTBUILD function o $LISTDATA function o $LISTFIND function o $LISTGET function A-16 New Intrinsic Functions $QUERY Function Syntax $QUERY(name{,integer_code}) Description $QUERY returns a full reference (name and subscripts) to the next or previous defined node in collating sequence to the array node you specify in the name argument. If no such array node exists, $QUERY returns a null string. To scan through all array nodes in a forward direction with $QUERY, you start by specifying either an unsub- scripted name argument or a name argument with a single null string subscript. To scan through all array nodes in a reverse direction with $QUERY, you must start by specifying a name argument with a single null string subscript. If you specify an unsubscripted name argument in the reverse direction, $QUERY will always return a null string result. In the reverse direction, the last node to be returned will be unsubscripted if the unsubscripted node contains data. Parameters name The name and subscripts of a local, global, or structured system variable, or an indirect reference that evaluates to a variable name or to another indirect reference. integer_ The value 1 to indicate the next defined node code (forward scan) or -1 to indicate the previous defined node (reverse scan). Note that a -1 integer code is not supported for structured system variables. New Intrinsic Functions A-17 Examples The following example lists all nodes in the local variable X array in a forward direction: >S NAM="X("""")" F S NAM=$Q(@NAM) Q:NAM="" W !,NAM The following example lists all nodes in the local variable X array in a reverse direction: >S NAM="X("""")" F S NAM=$Q(@NAM,-1) Q:NAM="" W !,NAM Notes When you use the $QUERY function, keep in mind that the two-argument format returns the next or previous defined node depending on the value of the integer_code argument. If you do not specify the integer_code argument, DSM returns the next defined node in collating sequence (that is, $QUERY behaves as if you specified 1 for the integer_ code argument). The integer_code argument must evaluate to 1 or -1, otherwise DSM returns an error. You should also refer to the existing comments for $QUERY in the DSM Language Reference Manual. Related Topics o $ORDER function o $ZPREVIOUS function o $ZREFERENCE special variable A-18 New Intrinsic Functions B ________________________________________________________________ ViewPoint User-defined Counters An application counter allows you to extend performance monitoring to application-defined values. This allows you to track instances or events within your database. For example, a patient adminsitration application might track the number of patients admitted or bills printed, and then receive performance information for those counters at a database or operating system-level. Overview of User-defined Counters A new DSM external routine, %VPUSER, is the programming interface to user-defined counters. By using this routine, a programmer can make a series of external calls to create a named table containing numbered, integer counters. The contents of the counters may be set, incremented or decremented, and retrieved using the appropriate external call. The contents of the counters are passed to the ViewPoint collector for analysis. User-defined Counters at Startup User-defined metrics are handled at system startup as follows: o The shared memory necessary for implementing the tables /counters is allocated at system startup. The design allows for a maximum of 255 tables and 1024 (aggregate) counters. Once memory has been reserved for a table /counter definition, it cannot be extended or reduced. The configuration must be restarted to re-initialize memory. ViewPoint User-defined Counters B-1 o The allocation of shared memory will be optional. A configuration question will ask if user metrics will be active. If the answer is "No", then all user metrics external calls will be treated as no-ops. It will be necessary to re-start the configuration to activate the user metrics feature. o The current version of ViewPoint does not support dy- namically changing metric definitions. The definitions are passed when communication is initiated and only the corresponding metrics may be passed after that. Consequently, only the user-defined counters which are defined in memory when communications begin will appear in ViewPoint. Tables and counters may be added to memory while the server process is running, but they will not be communicated to ViewPoint until the ViewPoint collector is restarted and requests metric definitions. o Because the DSM-ViewPoint server may be automatically started at system startup, DSM provides a mechanism for pre-defining user metrics which should be in memory when the server is auto-started. This mechanism uses a configuration question (following the auto-start question) which accepts a routine entry point to be called just before the server startup. The routine that contains the user-defined counters must be placed in the DSM baseline so that it can be loaded at system startup. Keep in mind that if you later upgrade to another DSM release, you should first save the routine file because an upgrade will delete the routine. Creating Application Counters Application counters are stored in a table. A maximum of 255 tables may be created. When you counter-enable an application, you first have to create the table. You can also look up (find) an existing table by omitting the last three parameters. B-2 ViewPoint User-defined Counters ________________________Note ________________________ Keep in mind that when a table is created, it is disabled. Therefore, you must explicitly enable the table before the counters are available to ViewPoint. See the section below, Showing or Hiding Counter Tables. _____________________________________________________ Syntax SET tablenum=$&ZLIB.%VPUSER(1,tablename{,entries,prefix,description}) Parameters tablenum A positive numeric identifier for the counter table. A value of 0 means the table is disabled. For errors, see section %VPUSER Errors of this appendix. tablename The name of the counter table. The maximum table length is 20 characters. entries The number of counters in the table. There is no explicit maximum value, however there is a limit of 1024 total counters across all counter tables. prefix A string used to uniquely identify the table and its associated counters. The maximum string length is 3 characters. description A description of the counter table. If the table already exists, only the description may be changed. If the description is changed, the version number of the table is incremented. Example The following example shows how to define a table named "Billing" that has 100 counters: ; Create counter table n table set table=$&ZLIB.%VPUSER(1,"Billing",100,"BCT","My Billing Counters") ViewPoint User-defined Counters B-3 Modifying Application Counters Modifying the name or description of an application- counter table is similar to creating one. You can also add a metric counter to the table. Syntax SET rval=$&ZLIB.%VPUSER(2,tablenum,counterID,countername,description) Parameters rval A positive index entry if the add/change was success. A negative value if an error occurred. For errors, see section %VPUSER Errors of this appendix. tablenum The numeric identifier of the table in which the counter will be changed. counterID The index number of the counter to be changed. countername The new name of the counter. Use an empty string ("") to hide this counter. description The new description of the counter. Note that if the name or description is changed, the version number of the table is incremented. Example The following example shows how to add two counters to a table: ; Modify counter table set table=$&ZLIB.%VPUSER(2,table,1,"TTime","number of today's minutes") set table=$&ZLIB.%VPUSER(2,table,2,"Timestu","number of minutes since startup") Showing or Hiding Counter Tables The ViewPoint client shows the counter tables. You can show (enable) or hide (disable) a counter table. Hidden counter tables are disabled, which means that the values in the counter table are still incremented appropriately but are unavailable to ViewPoint. B-4 ViewPoint User-defined Counters Syntax SET rval=$&ZLIB.%VPUSER(3,tablenum{,status}) Parameters rval The previous status of the table or the current state if status is omitted. Always 0 if the table is not defined. tablenum The numeric identifier of the table that will be enabled or disabled. status 1 to enable, 0 to disable the table. If the status is changed, the version number of the table is incremented. Retrieving Table and Counter Definitions You can return the definition of tables and counters. Syntax SET rval=$&ZLIB.%VPUSER(4{,tablenum{,counterID}}) Parameters rval Contains values that depend on which parameters were used, as described below. tablenum A numeric identifier for the counter table. counterID The identification number of the counter. If both tablenum and counterID are omitted, the value of rval is the number of tables. If only tablenum is specified, the value of rval is: cnums_$C(1)_ctnam_$C(1)_size_$C(1)_ctdesc_$C(1)_ctsts where: cnums The number of counters in the table. ctnam The name of the counter table. size The number of counters defined for the table. ctdesc A description of the counter table. ViewPoint User-defined Counters B-5 ctsts The status name of the table: 1 if enabled, 0 if disabled. If both tablenum and counterID are specified, the value of rval is: ctnam_$C(1)_ctdesc where: ctnam The name of the counter table. ctdesc A description of the counter table. Incrementing and Decrementing Counters You can increment or decrement the value of a counter. Syntax SET cval=$&ZLIB.%VPUSER(5,tablenum,counterID{,value}) Parameters cval The value of the counter after being incremented or decremented. tablenum A numeric identifier for the counter table. counterID The identification number of the counter. value The numeric value to be added to or subtracted from the counter. If value is omitted, +1 is used. B-6 ViewPoint User-defined Counters Setting Counter Values Counters start with a zero value by default and increment by one when incremented. You can, however, set the initial value to any value and or return the value of the counter. Syntax SET rval=$&ZLIB.%VPUSER(6,tablenum,counterID{,value}) Parameters rval The returned value of the counter before being changed. tablenum A numeric identifier for the counter table. counterID The identification number of the counter. value The numeric value to which the counter is to be set. If omitted, the counter is not changed. Example The following example shows how to set the value of a counter: set table=$&ZLIB.%VPUSER(6,table,1,1,0) set table=$&ZLIB.%VPUSER(6,table,1,2,$p($h,",",2)) Retrieving Table Data You can return a string of information about the counters in a format specifically for ViewPoint, i.e., contains $C(26) as a delimiter. This call can return either a list of the names (vp header info) or a list of the counter values. Only enabled (non-hidden) tables and named counters are returned. For the list of values, only those counters that have been communicated to ViewPoint are returned. Note that the first $PIECE is the version number (change counter) which is not a ViewPoint parameter. Syntax SET rval=$&ZLIB.%VPUSER(7,type{,tablenum}) ViewPoint User-defined Counters B-7 Parameters rval The returned data based on type. The data is a $Pieced string delimited by $C(26), the first piece being the table version, followed by either a list of names or values. type The the type of request: o 1 - variable names o 2 - values o 3 - reserved (descriptions) tablenum A numeric identifier for the counter table. Enabling and Disabling Metrics You can enable or disable all $&ZLIB.%VPUSER(*) calls, except for this call. When metrics are disabled, all calls are treated as NOOPs. Syntax SET rval=$&ZLIB.%VPUSER(8{,flag}) Parameters rval The previous or current status if flag is omitted. flag A flag to enable or disable the metric calls: 0 to disable, 1 to enable. %VPUSER Errors When creating or manipulating tables, the %VPUSER interface may return one of the following negative values if an error occurs: o -1: Exceeded maximum number of tables allowed o -2: Exceeded maximum number of counters allowed o -3: Invalid prefix, already exists for a different table o -4: Invalid table/counter name, either too long or duplicate B-8 ViewPoint User-defined Counters o -5: Invalid number of counters, must be greater than 0 o -6: No heap shared memory available If a description is too long, no error is returned and the description is always truncated. Example of a User-defined Routine The following routine is a simple example of a user- defined counter table. VPTEST ; Test routines for ViewPoint user metrics ; RFD ; 11/2/98 ; ; Functions: 1 = Create/find table ; 2 = Add/change a counter ; 3 = Enable/disable table ; 4 = Retrieve table/counter definitions ; 5 = Increment/decrement counter ; 6 = Set/retrieve counter ; 7 = Retrieve table/counters ; 8 = Enable/disable metrics ; ; Create tables and define counters. ; Test max sizes and error conditions S TNMLEN=20,TPRELEN=3,DESLEN=64,CNMLEN=10 S MAXTAB=256,MAXCNT=1024 S STRING="ABCDEFGHIJKLMNOPQRSTUVWXYZ" S DES=$TR($J("A",512)," ","A") S ERR="",D=$C(1) ; ; Initialize tables and counters S X=$&ZLIB.%VPUSER(8,1) ; Make sure VP is enabled S X=$&ZLIB.%VPUSER(0,"DOIT") ; Clear all memory ; ; Test error conditions for table creation S X=$&ZLIB.%VPUSER(1,"Table1",0,"XXX","Description") I X'=-5 S ERR="invalid counter number" G FAIL S X=$&ZLIB.%VPUSER(1,$E(STRING,1,TNMLEN+1),1,"XXX","Description") I X'=-4 S ERR="table name too long" G FAIL S X=$&ZLIB.%VPUSER(1,"Table1",1,$E(STRING,1,TPRELEN+1),"Description") I X'=-3 S ERR="prefix name too long" G FAIL S X=$&ZLIB.%VPUSER(1,"Table1",MAXCNT+1,"XXX","Description") I X'=-2 S ERR="too many counters" G FAIL S X=$&ZLIB.%VPUSER(1,"Table1",1,"XXX","Description") ViewPoint User-defined Counters B-9 I X'=1 S ERR="normal table create" G FAIL S X=$&ZLIB.%VPUSER(1,"Table1",1,"XXX","Description2") I X'=1 S ERR="table description edit" G FAIL S X=$&ZLIB.%VPUSER(1,"Table1") I X'=1 S ERR="table lookup" G FAIL S X=$&ZLIB.%VPUSER(1,"Table2",1,"XXX","Description") I X'=-3 S ERR="duplicate prefix name" G FAIL S X=$&ZLIB.%VPUSER(1,$E(STRING,1,TNMLEN),1,"XYZ","Description") I X'=2 S ERR="max table name" G FAIL S X=$&ZLIB.%VPUSER(1,$E(STRING,1,TNMLEN)) I X'=2 S ERR="lookup max table name" G FAIL F I=3:1:MAXTAB D Q:ERR]"" .S X=$&ZLIB.%VPUSER(1,"Table"_I,1,$E("XX",1,TPRELEN-$L(I))_I,"Description"_I) .I X'=I S ERR="maximum tables at "_I G:ERR]"" FAIL S I=MAXTAB+1,X=$&ZLIB.%VPUSER(1,"Table"_I,1,"XX"_I,"Description") I X'=-1 S ERR="too many tables" G FAIL F I=3:1:MAXTAB D Q:ERR]"" .S X=$&ZLIB.%VPUSER(4,I) .I X'=("0"_D_"Table"_I_D_"1"_D_"Description"_I_D_"0") S ERR="table def at "_I G:ERR]"" FAIL ; Enable all tables, make sure it works and doesn't affect other data F I=3:1:MAXTAB D Q:ERR]"" .S X=$&ZLIB.%VPUSER(3,I,1) ; Enable table .I X'=0 S ERR="tables enable at "_I G:ERR]"" FAIL F I=3:1:MAXTAB D Q:ERR]"" .S X=$&ZLIB.%VPUSER(4,I) .I X'=("0"_D_"Table"_I_D_"1"_D_"Description"_I_D_"1") S ERR="table enabled def at "_I G:ERR]"" FAIL ; ; Tests for counter add/change S X=$&ZLIB.%VPUSER(0,"DOIT") ; Clear tables S X=$&ZLIB.%VPUSER(1,"Table1",MAXCNT,"XXX","Description") I X'=1 S ERR="maximum counters" G FAIL S X=$&ZLIB.%VPUSER(1,"Table2",1,"XYZ","Description2") I X'=-2 S ERR="too many counters (again)" G FAIL S X=$&ZLIB.%VPUSER(2,1,1,$E(STRING,1,CNMLEN+1),"Description") I X'=-4 S ERR="counter name too long" G FAIL S X=$&ZLIB.%VPUSER(2,1,1,"Count1","Description1") I X'=1 S ERR="normal counter add" G FAIL S X=$&ZLIB.%VPUSER(2,1,2,"Count1","Description1") I X'=-4 S ERR="duplicate counter name" G FAIL B-10 ViewPoint User-defined Counters F I=2:1:MAXCNT D Q:ERR]"" .S X=$&ZLIB.%VPUSER(2,1,I,"Count_"_I,"Description_"_I) .I X'=I S ERR="set all (max) counters" G:ERR]"" FAIL F I=2:1:MAXCNT D Q:ERR]"" .S X=$&ZLIB.%VPUSER(4,1,I) .I X'=("Count_"_I_D_"Description_"_I) S ERR="counter def at "_I G:ERR]"" FAIL ; Try to set and retrieve for max counters F I=2:1:MAXCNT D Q:ERR]"" .S X=$&ZLIB.%VPUSER(6,1,I,10) .I X'=0 S ERR="counter 'set' at "_I G:ERR]"" FAIL S X=$&ZLIB.%VPUSER(3,1,1) ; Enable table S X=$&ZLIB.%VPUSER(7,1,1,"SEND") ; Retrieve counter names (set 'sent' flag) F I=2:1:MAXCNT D Q:ERR]"" .I $P(X,$C(26),I+1)'=("XXX-Count_"_I) S ERR="retrieve counter names at "_I G:ERR]"" FAIL S X=$&ZLIB.%VPUSER(7,2,1) ; Retrieve counter values F I=2:1:MAXCNT D Q:ERR]"" .I $P(X,$C(26),I+1)'=10 S ERR="retrieve counter values at "_I G:ERR]"" FAIL ; Test for all "0"s on a disabled table S X=$&ZLIB.%VPUSER(3,1,0) ; Disable table S X=$&ZLIB.%VPUSER(7,2,1) ; Retrieve counter values F I=2:1:MAXCNT D Q:ERR]"" .I $P(X,$C(26),I+1)'=0 S ERR="retrieve disabled counter values at "_I G:ERR]"" FAIL ; ; Set up some tables/counters for increment/set/retrive functions S X=$&ZLIB.%VPUSER(0,"DOIT") ; Clear tables S TABLES=20,CNT=20 F I=1:1:TABLES D Q:ERR]"" .S X=$&ZLIB.%VPUSER(1,"Table"_I,CNT,$E("XX",1,TPRELEN-$L(I))_I,"Description"_I) .I X'=I S ERR="tables set up at "_I .S X=$&ZLIB.%VPUSER(3,I,1) ; Enable table .I X'=0 S ERR="table set up enable at "_I .F C=1:1:CNT S X=$&ZLIB.%VPUSER(2,I,C,"Count"_C,"Description"_C) D Q:ERR]"" ..I X'=C S ERR="counter set up at table "_I_" counter "_C G:ERR]"" FAIL ; Test increment and decrement F I=1:1:TABLES D Q:ERR]"" .F C=1:1:CNT S X=$&ZLIB.%VPUSER(5,I,C) D Q:ERR]"" ViewPoint User-defined Counters B-11 ..I X'=1 S ERR="increment counters at table "_I_" counter "_C G:ERR]"" FAIL F I=1:1:TABLES D Q:ERR]"" .F C=1:1:CNT S X=$&ZLIB.%VPUSER(5,I,C,-1) D Q:ERR]"" ..I X'=0 S ERR="decrement counters at table "_I_" counter "_C G:ERR]"" FAIL ; Disable all metrics and try each functions S X=$&ZLIB.%VPUSER(8,0) I X'=1 S ERR="disable metrics" G FAIL S X=$&ZLIB.%VPUSER(8) I X'=0 S ERR="metrics status" G FAIL S X=$&ZLIB.%VPUSER(1,"test",20,"ABC","test") I X'=0 S ERR="disabled create table" G FAIL S X=$&ZLIB.%VPUSER(2,1,1,"test","test") I X'=0 S ERR="disabled add counter" G FAIL S X=$&ZLIB.%VPUSER(3,1,1) I X'=0 S ERR="disabled enable table" G FAIL S X=$&ZLIB.%VPUSER(4,1,1) I X'=0 S ERR="disabled retrieve def" G FAIL S X=$&ZLIB.%VPUSER(5,1,1) I X'=0 S ERR="disabled increment" G FAIL S X=$&ZLIB.%VPUSER(6,1,1) I X'=0 S ERR="disabled set" G FAIL S X=$&ZLIB.%VPUSER(7,1,1) I X'=0 S ERR="disabled table data" G FAIL ; W !!,"** All tests passed **",! Q ; SETUP ; Entry point to set up 20 tables with 20 counters (enabled) S X=$&ZLIB.%VPUSER(0,"DOIT") ; Clear tables S ERR="" F I=1:1:20 D Q:ERR]"" .S X=$&ZLIB.%VPUSER(1,"Table"_I,20,$E("XX",1,3-$L(I))_I,"Description"_I) .I X'=I S ERR="tables set up at "_I .S X=$&ZLIB.%VPUSER(3,I,1) ; Enable table .I X'=0 S ERR="table set up enable at "_I .F C=1:1:20 S X=$&ZLIB.%VPUSER(2,I,C,"Count"_C,"Description"_C) D Q:ERR]"" ..I X'=C S ERR="counter set up at table "_I_" counter "_C I ERR]"" W !!,"Error in - ",ERR,! Q ; ; FAIL ; Write error message (in ERR) and quit B-12 ViewPoint User-defined Counters W !,"Failed VP test for - ",ERR Q ViewPoint User-defined Counters B-13 C ________________________________________________________________ Command-line Recall Feature This appendix provides reference descriptions of the following: o ZRECALL command o /RECALL and /NORECALL command-line qualifiers for DSM command o /KEYDEFS command-line qualifier for DSM command Command-line Recall Feature C-1 ZRECALL ZRECALL recalls or displays command lines in the recall buffer when the DSM command-line recall feature is enabled. Format ZRE{CALL}{:postcond}{argument} Parameters postcond A postconditional expression. argument Can be one of the following: o line number - is the recall number of the line to recall (numbered from 1, the most recently entered command line, to n, the nth most recently entered command line, where n is the maximum number of lines in the recall buffer). o line characters - are the first few characters in the command line to recall. o /A{LL} - a command-line qualifier that displays all lines in the recall buffer (starting with the most recent) and is equivalent to the argumentless form of the command. o /R{EMOVE} - a command-line qualifier removes the command line in which it appears from the recall buffer. Explanation The ZRECALL command is primarily used to display and recall lines currently in the DSM command-line recall buffer. By default, when you run DSM in programmer mode, DSM will save command lines that you enter in Direct Mode and Break Mode in a recall buffer. A previously-entered command line can be recalled by pressing the up-arrow key until the desired line is displayed. C-2 Command-line Recall Feature Alternatively, you can display all lines in the recall buffer by typing the argumentless form of the ZRECALL command and then immediately recall a particular line by specifying its line number or its first few characters as a ZRECALL command argument. For example, suppose you typed in the following command and then some other commands: >S %HD="FF" ... Assuming the command is still in the recall buffer, you can recall it by repeatedly pressing the up-arrow key until the line is displayed. You can also directly recall the command as follows: >ZRE . . 14 W %HD 15 D ^%HD 16 S %HD="FF" >ZRE 16 If no other more recently entered command started with the letter 'S' (either upper- or lowercase), you can also recall the command by typing: >ZRE S Other forms of the ZRECALL command perform functions associated with the command-line recall feature. The ZRECALL /ALL command displays all lines in the recall buffer and is equivalent to the argumentless form of the command. The ZRECALL /REMOVE command removes the command line in which it appears from the recall buffer. It can be used in key definitions where the command line equivalenced with the key should not be inserted into the recall buffer. In general, command lines that contain a ZRECALL command will not be placed in the recall buffer. Command-line Recall Feature C-3 Comments Keep the following points in mind when you use the ZRECALL command: o The command line recall feature is enabled by default when you run DSM in Programmer Mode. It may be disabled by specifying the /NORECALL commmand line qualifier when you run DSM. For applications that start in Application Mode but ZESCAPE to Programmer Mode, you must specify the /RECALL[=n] qualifier to enable the feature. o By default, DSM saves the 20 most recently entered command lines in the recall buffer. You can set that number as low as 2 or as high as 254 by specifying the /RECALL=n commmand-line qualifier when you run DSM. o The ZRECALL argument is not an M language expression. You cannot set a variable to an argument value and then use the variable as the argument. o When the first ZRECALL argument character is not the slash (/) character, DSM interprets that character and all the remaining characters on the command line as ZRECALL argument characters, regardless of any space characters that may be present. o If all ZRECALL argument characters are numeric, then DSM interprets the argument as a line number. If the number exceeds the maximum possible number of lines in the recall buffer, then DSM returns a %DSM-E-NUMBER error. If the number doesn't exceed that maximum but exceeds the number of previously entered command lines, then DSM just redisplays the command prompt. o If all ZRECALL argument characters are not numeric (and the first character is not "/"), then DSM interprets all argument characters as the first few characters in the command line to recall. Specify enough characters to distinguish the desired line from other lines in the recall buffer, keeping in mind that a case-insensitive search is performed, and do not surround the specified characters with quotes. If DSM cannot find a line in the recall buffer starting with those characters, then a %DSM-E-LINNOTFND error is returned. C-4 Command-line Recall Feature o When the first ZRECALL argument character is the '/' character, DSM scans for a valid keyword. o The ZRECALL command is only valid when entered in Direct Mode or Break Mode, and when command-line recall is enabled. Related o Postconditional expressions Command-line Recall Feature C-5 /RECALL Command-line Qualifier The DSM command has been enhanced with two command-line qualifiers that control the recall buffer storage. /[NO]RECALL[=n] The /RECALL[=n] qualifier enables DSM command line recall and optionally sets the maximum number of commands lines that can be saved in the recall buffer. By default, the maximum is set to 20. You can reset the default by specifying n to be a value from 2 to 254. The /NORECALL qualifier disables DSM command-line recall. The default in Programmer Mode is /RECALL. The default in Application Mode is /NORECALL. Not having command line recall in Application Mode is not an issue unless the ZESCAPE command is used to escape from Application Mode into Programmer Mode. /KEYDEFS Command-line Qualifier The DSM command has been enhanced with the /KEYDEFS qualifier that allows you to load key definitions from a file. /KEYDEFS=filespec The filespec parameter is the name of a file containing DCL DEFINE/KEY commands that equate a keyboard key with a DSM command line string. The key definitions are loaded only if DSM command line recall is enabled. Note that when a key definitions file is loaded and an invalid key definition command is found in the file, the valid key definition commands up to that point in the file are applied before DSM returns a %DSM-E-KEYDEFS error. DSM provides DSM$DEBUG.KEYDEFS, a sample key definitions file in SYS$EXAMPLES. The keypad definitions of this file are as follows: C-6 Command-line Recall Feature +------------+------------+------------+ |Find |Insert Here |Remove | | Show | Set | Clear | | Call Stack | Breakpoint | Breakpoint | | |@current loc|@current loc| +------------+------------+------------+ |Select |Prev Screen |Next Screen | | Show | Show | Show | | Current | Previous | Next | | Location | Lines | Lines | +------------+------------+------------+ +------------+------------+------------+------------+ |PF1 |PF2 |PF3 |PF4 | | Set GOLD | Set HELP | ZDEBUG ON | ZDEBUG OFF | | State | State | | | | | | | | +------------+------------+------------+------------+ |7 |8 |9 |- | | Set a | Clear a | List | Clear All | | Watchpoint | Watchpoint |Watchpoints |Watchpoints | | | | | | +------------+------------+------------+------------+ |4 |5 |6 |, | | Set a | Clear a | List | Clear All | | Breakpoint | Breakpoint |Breakpoints |Breakpoints | | | | | | +------------+------------+------------+------------+ |1 |2 |3 |Enter | | ZSTEP | ZSTEP | ZSTEP | | | LINE,OVER | OUTOF |COMMAND,OVER| | | | | | | +------------+------------+------------+ ZGO | |0 |. | | | ZSTEP LINE | ZSTEP | | | | COMMAND | | | | | | +------------+------------+------------+------------+ Command-line Recall Feature C-7 D ________________________________________________________________ WRITE Command for TCP/IP Devices This appendix describes a feature that was introduced with DSM V7.2.1. It is included for customers who are upgrading from a pre-7.2.1 version and have not seen the description of this feature. The "WRITE *-3" command has been implemented for a TCP/IP device. The DSM application for TCP/IP network communication can use the new-line formatting character (!) or the form-feed character (#) to terminate the current record and cause a physical write to occur. The output characters are copied to a buffer and then physically written to the network when a flush (WRITE ! or WRITE #) is received. The new implementation allows the output buffer flush for a TCP/IP device to be deferred until you issue the next "WRITE *-3" command. To select this option, you have to specify the FLUSHWAIT parameter in the OPEN or USE command for a TCP/IP port as described below. Command Syntax for a DSM Process to Function as a Client OPEN port:(TCPCHAN:ADDRESS="address"{:[NO]FLUSHWAIT}{:timeout}) where: port evaluates to an integer in the range of 1 to 65535. TCPCHAN:ADDRESS keywords that must be supplied. address a valid Internet address in the form: nnn.nnn.nnn.nnn [NO]FLUSHWAIT defers output buffer flush until the next "WRITE *-3" command. WRITE Command for TCP/IP Devices D-1 timeout a time specification for a timeout. D-2 WRITE Command for TCP/IP Devices The FLUSHWAIT option can be modified by a USE command for the same port: USE port{:[NO]FLUSHWAIT} where: port evaluates to an integer in the range of 1 to 65535. [NO]FLUSHWAIT defers output buffer flush until the next "WRITE *-3" command. Command Syntax for a DSM Process to Function as a Server OPEN port:(TCPCHAN{:[NO]FLUSHWAIT}{:timeout}) where: port evaluates to an integer in the range of 1 to 65535. TCPCHAN a keyword that must be supplied. [NO]FLUSHWAIT defers output buffer flush until the next "WRITE *-3" command. timeout a time specification for a timeout. The FLUSHWAIT option can be modified by a USE command for the same port: USE port{:[NO]FLUSHWAIT} where: port evaluates to an integer in the range of 1 to 65535. [NO]FLUSHWAIT defers output buffer flush until the next "WRITE *-3" command. Notes When you use the FLUSHWAIT option, the "WRITE !" and "WRITE #" commands are ignored until the next "WRITE *-3" command. The buffer is never implicitly flushed. If you attempt to write more characters into the buffer than it can hold, you receive the following error: %DSM-E-WRITERR, error writing to 'port number' -DSM-E-STRLEN, string too long WRITE Command for TCP/IP Devices D-3 TCP/IP ignores all writes with a record length of 0. This means that issuing a "WRITE *-3" when the output buffer is empty is not valid. DSM treats this as an error and returns the following error message: %DSM-E-WRITERR, error writing to 'port number' -DSM-E-ILLOPT, illegal I/O option D-4 WRITE Command for TCP/IP Devices