Read Before Installing Version 6.6B of DSM for OpenVMS VAX and Alpha IS-DSMLC-VM This document describes the distribution kits for the following software: o Version 6.6B of DSM for OpenVMS VAX[TM] o Version 6.6B of DSM for OpenVMS Alpha[TM] It also provides product information that supplements the DSM for OpenVMS Release Notes. This document has three attachments: o Attachment A, "Installing the DSM 6.6B kit," describes how to install this MUP kit. o Attachment B, "Additional Product Information," provides prod- uct information you need to know to use DSM. o Attachment C, "ECO Descriptions," is a list of problems fixed in Versions 6.6A and 6.6B. Version Compatibility Version 6.6B of DSM for OpenVMS is a maintenance update (MUP) to Version 6.6A. Version 6.6B is compatible with DSM[TM] applications written under previous versions of DSM for OpenVMS[TM]. You need to be using OpenVMS VAX Version 6.1, Version 6.2, Version 7.0 or Version 7.1 to install and run Version 6.6B of DSM for OpenVMS VAX. You need to be using OpenVMS Alpha Version 6.1, Version 6.2, Version 7.0 or Version 7.1 to install and run Version 6.6B of DSM for OpenVMS Alpha. Distribution DSM is distributed by both InterSystems Corporation and Digi- tal Equipment Corporation. InterSystems distributes DSM software on the following media for both DSM for OpenVMS VAX and DSM for OpenVMS Alpha: o 9-track magnetic tape o TLZ06[TM] o TK50[TM] tape cartridge Digital Equipment Corporation distributes DSM software on the following media: o DSM for OpenVMS VAX: - 9-track magnetic tape - TLZ06[TM] - TK50[TM] tape cartridge - CD-ROM o DSM for OpenVMS Alpha: - CD-ROM DSM supports the OpenVMS License Management Facility (LMF), that allows licensed users access to DSM. If you are a first-time DSM customer, the DSM distribution kit also includes a Product Autho- rization Key (PAK). The information contained in your PAK must be registered using LMF. For additional information, see the DSM In- stallation and Management Guide and the OpenVMS System Manager's Manual. If you are upgrading from a previous release of DSM, see the DSM for OpenVMS Release Notes for information about LMF. Installation Information If you are installing DSM software for the first time, read Chap- ter 1 of the DSM for OpenVMS Installation and Management Guide. This chapter describes the installation procedure in detail. If you are upgrading from a previous release of DSM, you must upgrade your existing configurations and volume sets. After you complete your software installation, the upgrade procedure will load Version 6.6B manager utilities and globals. You must recom- pile application routines, create new mapped routine files, and reinitialize the journal files. A copy of the DSM for OpenVMS Release Notes is distributed in printed form and on line as a file with the DSM distribution kit. You can obtain a copy of these release notes when you install DSM by using the "OPTIONS N" parameter with the VMSINSTAL procedure. For example: $ @SYS$UPDATE:VMSINSTAL DSM OPTIONS N If you are using CD-ROM media, you can obtain a copy of the re- lease notes using the CDMENU Utility. After installation, the DSM for OpenVMS Release Notes is available in SYS$HELP:DSM066.RELEASE_ NOTES, and a copy of this cover letter and attachments is avail- able in the file SYS$HELP:DSM066B.COVER_LETTER. Thank you for purchasing DSM for OpenVMS. The DSM Product Group 2 InterSystems Corporation. 1996 3 Attachment A - Installing the DSM Version 6.6B Kit The following sections contain information about installing the DSM kit. Installing DSM for the First Time If you are installing DSM software for the first time, read Chap- ter 1 of the DSM for OpenVMS Installation and Management Guide. That chapter describes the installation procedure in detail. Take the following steps to install the DSM Version 6.6B MUP kit: 1. Back up your system. 2. Install the MUP kit. Run the SYS$UPDATE:VMSINSTAL procedure. On an OpenVMS VAX system, specify DSMVAXMUPB066 as the product name. On an OpenVMS Alpha system, specify DSMAXPMUPB066 as the product name. 3. If you do not run the IVP during VMSINSTAL, install the DSM for OpenVMS images as shared using the SYS$STARTUP:DSM$INSTALL.COM procedure. Postinstallation Activities: 1. Use the SYS$MANAGER:DSM$INIT.COM procedure to create a DSM for OpenVMS environment manager's account. 2. Edit the OpenVMS system files to provide for automatic startup and shutdown of DSM for OpenVMS configurations when your system is rebooted. 3. Log in to the DSM for OpenVMS environment manager's account and run the SYS$MANAGER:DSM$CONFIGURE.COM procedure to initialize DSM for OpenVMS database volume sets and configurations. Upgrading From a Previous Version of DSM If you are upgrading from a previous release of DSM you must up- grade your existing configurations and volume sets. Read the DSM for OpenVMS Release Notes in addition to the following informa- tion. Take the following steps to upgrade from a previous version of DSM to DSM for OpenVMS Version 6.6B: 1. Shut down all running DSM for OpenVMS configurations. 2. Back up your system. 3. Install the MUP kit. Run the SYS$UPDATE:VMSINSTAL procedure. On an OpenVMS VAX system, specify DSMVAXMUPB066 as the product name. On an OpenVMS Alpha system, specify DSMAXPMUPB066 as the product name. 4 4. If you do not run the IVP during VMSINSTAL, install the DSM for OpenVMS images as shared using the SYS$STARTUP:DSM$INSTALL.COM procedure. Postinstallation Activities: 1. Use the SYS$MANAGER:DSM$INIT.COM procedure from a privileged OpenVMS system account to upgrade DSM for OpenVMS manager ac- counts to DSM for OpenVMS Version 6.6B environment manager accounts. 2. Log in to the DSM for OpenVMS environment manager's account and run the SYS$MANAGER:DSM$UPGRADE.COM procedure. If you are upgrading from Version 6.6 or 6.6A, you do not need to recompile your application routines. If you are upgrading from a version of DSM prior to 6.6 you must recompile your application routines. DSM$UPGRADE optionally reinitializes before-image and after- image journal files and optionally upgrades mapped routine sets. You can also use ^BIJINIT, ^JRNINIT, and ^RMBLD to reini- tialize your journal files and rebuild your mapped routines at a later time. 3. Edit the OpenVMS system files to provide for automatic startup and shutdown of DSM for OpenVMS configurations when your system is rebooted. 4. If you are using DDP, reboot your OpenVMS system to reload the DDP driver. 5. Start up the upgraded configurations. Alternate Root Installation If you are installing DSM in an alternate root, read Appendix A of the DSM Installation and Management Guide. It describes the alternate root installation in detail. Do the following to install the DSM Version 6.6B MUP kit: 1. Log in to the system account. 2. Shut down all running DSM configurations. In a VMScluster envi- ronment, shut down configurations running on each node. 3. Extract the DSM$ALTROOT_INSTALL.COM procedure from the kit saveset. On an OpenVMS VAX system, use the following command: $ BACKUP/LOG kit_device:DSMVAXMUPB066.B/SAVE/SELECT=3DDSM$- ALTROOT_INSTALL.COM; * On an OpenVMS Alpha system, use the following command: $ BACKUP/LOG kit_device:DSMAXPMUPB066.B/SAVE/SELECT=3DDSM$- ALTROOT_INSTALL.COM; * Where kit_device is the distribution tape, CD-ROM, or disk where the DSM MUP kit is located. 4. Use the DSM$ALTROOT_INSTALL.COM procedure to create the alter- nate root directories and install the DSM software distribution kit. 5 5. Use the DSM$ALTROOT.COM procedure to create and initialize a DSM environment manager's account for the new alternate root. 6. Use the DSM$ALTROOT.COM procedure to initialize the group logi- cal name search lists for all users within the GROUP. 7. Log in to the new manager account and use the SYS$MANAGER:DSM$- CONFIGURE.COM procedure to create volume sets and to define new configurations. 8. Edit system startup files to initialize alternate root instal- lation on system reboot. 6 Attachment B - Additional Product Information The following sections contain additional information about doc- umentation and functionality that is not included in the DSM Re- lease Notes. Documentation Notes and Corrections This section contains notes about and corrections to the DSM docu- mentation set. o The DSM for OpenVMS Programmer's Guide left out the description of the %SETUCI utility. The following is the missing descrip- tion of this utility: %SETUCI Changes your default UCI and volume set. If you omit the flag argument, then DSM changes the UCI and volume set for both globals and routines. If you do not specify the volume set name (VOL), DSM uses the volume set S0. You can control access to this external routine by enabling configuration access control using the ^CONFIG Utility. Format: SET X=3D$&ZLIB.%SETUCI(UCI,{VOL},{flag}) UCI New UCI name VOL New volume set name flag G =3D change UCI and VOL for globals R =3D change UCI and VOL for routines o Chapter 9 of the DSM for OpenVMS Database Operations Guide contains a typographical error. Please replace every occurrence of the word "rambles" in Chapter 9 with the word "re-enables." Additional Technical Information This section contains notes about DSM technical changes. o DSM for OpenVMS has implemented the following behavior for handling year dates: DSM will interpret that all year dates entered as two-digit numeric values refer to a year within the century in which the value is entered. For example, when you enter a year date of "99" before Dec 31, 1999 at 11:59:59, DSM will interpret that year date as 1999. When you enter a year date of "99" after Dec 31, 1999 at 11:59:59, DSM will interpret that year date as 2099. The $HOROLOG special variable, however, will continue to keep the correct absolute date. 7 o A partial remedy for the BIJ file overflow issue was included in Version 6.6 of DSM for OpenVMS. Version 6.6B of DSM for OpenVMS includes a more complete solution to the problem (doc- umented as ECO 5 in Attachment C) that greatly decreases the likelihood of a BIJ file overflow. This solution does not pre- clude the environment system manager's responsibility to size the BIJ file properly, according to the information previously published about sizing files. o To resolve the issue documented as ECO 6 in Attachment C, security auditing now allows users to disable auditing for non-journaled globals. To do so, run ^CONFIG and answer the following prompts: Modify security audit name definition [Y OR N] ? Y . . . Disable security auditing for non-journaled globals [Y OR N] ? - Y o In an attempt to prevent DSM environment managers from dis- mounting a database set while that set is being dejournaled, Version 6.6 of DSM for OpenVMS inadvertently removed the abil- ity of running concurrent processes to dejournal separate vol- ume sets (as documented in ECO 7). This condition has been corrected in Version 6.6B. Dejournaling to separate volume sets can once again run concurrently. The ability to mount and dismount database sets has given DSM environment managers greater flexibility over the maintenance of their DSM configurations. Along with that flexibility comes the responsibility to: o Properly manage the environment o Keep track of the state of any given database set before attempting to perform certain maintenance functions on that database. For example, attempts to dismount a database set while it is being dejournaled will bring about unexpected results. o For backwards compatibility, the $ZV special variable again reports the string "VAX DSM." (See ECO 15 in Attachment C for a description of the original issue.) o 8 Attachment C - ECO Descriptions The following table describes DSM ECOs. ___________________________________________________________________ ECO____DSM_Problem_Description_____________________________________ DSM Version 6.6A-020 1 If a multiple-volume-set TP set is mounted in non- contiguous slots (for example: S2 and S4), the AIJ con- trol for the volume sets after the "gap" are not correctly associated with the preceding TP volume set. 2 The recovery process can loop in HIB status in the event of a cluster state transition due to another node going down, while the database set is dismounted. This only occurs when the database set has been dismounted from the master node and the node attempting to perform a recovery is not capable of being master. 3 If you use a global reference with a $D value of 10 as the first argument of $GET and you supply a second argument, $GET always ignores the second argument and returns null. >k ABC S ABC("TEST")=3D"TEST" W $G(ABC,1) 1 >k ^ABC S ^ABC("TEST")=3D"TEST" W $G(^ABC,1) 4 If you issue the following command with a reference to a volume set in a different DSM environment you get a DSM-E- NOSUCHVOLSET error, even though you can see the global with ^%G and $D (that is, the DDP connection to the volume set is working properly). W $ZS(^["UCI","VOL"]GLOBAL) 5 A possible BIJ FULL error may occur if a volume set has a large number of blocks allocated for globals. The routine used to search the global directory for top level dele- tions, creations, and modifications would perform before- image journaling on each of the blocks it scanned while searching for the block that contained the global's data. DSM for OpenVMS Version 6.6 logs an error to DSMCRASH.LOG indicating the BIJ file overflow. 6 Security auditing cannot be turned off for non-journaled globals. 7 Starting with DSM for OpenVMS Version 6.6, you can no longer run concurrent processes to dejournal. 8 If a "user open call" routine is defined, an inadvertent attempt to close a previously-closed journal file may hang the process. 9 ___________________________________________________________________ ECO____DSM_Problem_Description_____________________________________ 9 You may get a GDT allocation error because of corruption in free memory chain when smaller sized segments are al- located from an existing larger segment; for example: if a volume set containing x number of globals is dismounted and another volume set with x-n globals is mounted in the same slot. 10 %ERRCHK fails to report a warning for using SET $FIND and SET $EXTRACT as described in the following extract from help text: The ^%ERRCHK Utility has been modified to detect occurrences of SET $EXTRACT and SET $FIND in your application. The utility prints a warning for each SET $EXTRACT occurrence when the /EXTENSION=3DSETFUNCTION command line qualifier is in force. However, it always prints a warning for each occurrence of SET $FIND. 11 Modifying the "ALTERNATE" field in the database description for mounting using an alternate name does not work. 12 A user can get an when accessing the top level node of a global right after creating the global causes . JRNTEST4>K ^X S ^X(1)=3D0,^X=3D9,^Y(0)=3D9 S ^Y(0)=3D^Y(0)_^X %DSM-E-UNDEF, undefined variable ^X 13 With a multi-volume transaction processing database set, you can experience a process hang when writing to the AIJ file. The problem is caused when the TP monitor, DSM_JRNL, attempts to write to the AIJ for a non-base (any volume set that is not first) TP volume set from the timer AST routine. 14 DSM reports an erroneous DDP error message when dismounting a database set. 15 The $ZV string no longer reports "VAX DSM." 16 If you try to display the current line of a % routine be- ing executed in a non "MGR" UCI, from any non "MGR" UCI, it fails with "(cannot display routine line -source is unavailable)". 17 Under certain conditions, a process may go into a COM 0 state while running ^%JOB on another process. For example, suppose ^%JOB is run for a process that defined a large symbol by a process that has not defined a symbol table of the same size or larger. If the process running ^%JOB tries to load the symbol table of the first process, that process goes into a COM 0 state. 10 ___________________________________________________________________ ECO____DSM_Problem_Description_____________________________________ 18 Under OpenVMS Alpha V6.2 only: The %BASEDIT Ecall sub- function 32 (convert lower to uppercase) does not work correctly for certain German characters. 19 Errors occur in the ^CONTR utility in the following situa- tions: o When using the wildcard as the last entry in a subscript range list. o When an entry being inserted has more subscripts than the entry that follows. 20 In prior versions of DSM, TP database sets could not be mounted as read-only. DSM Version 6.6B-033 21 Starting in DSM for OpenVMS V6.5, the interpreter will hang if more than 64 different local variables are used as an XECUTE command argument. The following reproduces the problem: >f i=3D1:1:65 s x(i)=3D"Q" >f i=3D1:1:65 x x(i) 22 Starting in DSM for OpenVMS V6.4 an access violation will occur if the DSM debugger is used to debug an applica- tion that has more than a combined total of 15 extrinsic function and direct mode frames on the M call stack. 23 Starting in DSM for OpenVMS V6.4, the DSM interpreter started checking for maximum indirection nesting level to avoid infinite indirection recursion. However, DSM errantly counted any indirection which results in a call stack level change as an indirection nesting level. The following rou- tine, which uses one level of indirection in a DO command argument, demonstrates the problem: DOTEST S LABEL=3D"A" D @LABEL Q A W !,"At call stack level ",$ST Q:$ST>70 D @LABEL Q 24 Starting in DSM V6.5 for OpenVMS a %DSM-E-SYSERR error occurs if you make a $TEXT reference to a local line label after the routine buffer has been cleared by the ZREMOVE command. The following demonstrates the problem: >ZR >W $T(AAA) 11 ___________________________________________________________________ ECO____DSM_Problem_Description_____________________________________ 25 Several problems with journaling routines have been corrected: o A was inadvertently inserted in the error mes- sage printed to the OPCOM in the ^USROPN routine. o $$PUTLIST^JRNLIB can return erroneous status value rather than the appropriate messages ERRACC, NOTJRN, or OTHRVS. o A syntax error has been corrected which caused the fol- lowing error: %DSM-E-ZJOBRPYERR, Error from JOB process %DSM-E-SYNTAX, DSM command line syntax error 26 An APPLICATION volume set turns into SYSTEM volume set after running ^LABEL to change the label name. This occurs after the volume set had been dismounted with ^DISMOUNT and can prevent the volume set from being re-mounted. 27 When doing a $O (both forward and reverse) from a remote node (DDP) through a global, defined as a Subscript Range translated to multiple volume sets, it is possible to error with a message, such as: %DSM-E-STRLEN, string too long 28 If you run ^DISMOUNT to do a cluster-wide dismount of a database set, the dismount will hang if the database set is already off-line on the local node and still cluster- mounted on any other node in the DSM cluster. 29 Starting with DSM V6.6A, for those still using ZJRNOPN, the new journal file may not open automatically. OPENFIL^JRNL will need to be run for the system to continue journaling. 12 ___________________________________________________________________ ECO____DSM_Problem_Description_____________________________________ 30 Starting in V6.5, DSM implemented a new memory management scheme that required a new object code sequence for an ar- gumented QUIT command. However DSM failed to update the object code sequence for the implicit argumented QUIT en- coded at the end of a $ETRAP error handler. The result is is an access violation when a $ETRAP error handler without a GOTO is invoked in an extrinsic function context. The following demonstrates the problem: test() S $ET=3D"W !,$ZE" Q 1/0 >W $$test test+1:1, %DSM-E-NUMBER, Attempt to perform division by zero, -DSM-I-ECODE, MUMPS error code: M9 ******************* Fatal Error *********************** etc... A workaround is to include an argumented QUIT in the $ETRAP value. For example: test() S $ET=3D"W !,$ZE Q:$Q """" Q" 31 When an invalid watchpoint is set into the $ZWATCH special variable with the ZDEBUG switch on, DSM for OpenVMS gener- ates a %DSM-E-ILLWATCH error for every command typed in at the programmer mode prompt. It is then necessary to type Y or use ^FORCEX to exit the DSM process. 32 The JRNLIB routine can produce 2 duplicate error codes: NOFIL and NOFILE. However, $$ERROR^JRNLIB only contained the NOFIL error code. NOFILE has now been added to the error code descriptions. 33 DSM improperly allocates memory for a parameter passed to an M routine or function when the parameter is a local or special variable string value that is longer than 2044 characters. The result is unpredictable, but an access violation or a %DSM-E-ALLOC error is typical. This problem originates with DSM V6.5 for OpenVMS when DSM extended the maximum local data string length from 2040 to 32767. Enter DSM with /LOCAL_DATA_SIZE=3D2045 and type the following to reproduce the problem: >S $P(A,"Z",2046)=3D"" ___________>W_$$F^%HD(A)___________________________________________ 13