MUP NUMBER: DSM103 ----------- PRODUCT: DSM Version 1.0 for DEC OSF 1/AXP -------- UPDATED PRODUCT: DSM Version 1.0 for DEC OSF 1/AXP 1.0C ---------------- APPRX BLCK SIZE: 22719 ---------------- DIGITAL Read Before Installing DSM Version 1.0C for DEC OSF/1 AXP AV-PZR2D-TE Dear DSM customer: This document describes the DSM[TM] software distribution kit and provides information that supplements the DSM documentation set. DSM Version 1.0C for DEC OSF/1 AXP is a maintenance update to Version 1.0 of Digital Standard M, for Digital's Alpha AXP[TM] systems and the DEC OSF/1 AXP operating system. You must be run- ning DEC OSF/1 AXP Version 3.0 to run DSM Version 1.0C for DEC OSF /1 AXP. The DSM distribution kit is provided on CD-ROM. Documentation is available in hard copy and on the Online Documentation Library Compact Disc (to be used with the Bookreader[TM] for DEC OSF/1 AXP). DSM supports the License Management Facility (LMF), which al- lows licensed users access to DSM. The DSM distribution kit also includes a Product Authorization Key (PAK). The information con- tained in your PAK must be registered using LMF. If you are installing DSM for the first time, please read the DSM Installation and Management Guide before installing the DSM soft- ware. It describes the installation procedure in detail. Chapter 1 contains information on software requirements and registering your DSM license. Chapter 2 contains information about configur- ing DEC OSF/1 AXP systems for use with DSM. Refer to Attachment A for additional system configuration information and documenta- tion corrections and to Attachment B for an updated installation example. If you are upgrading to Version 1.0C from Version 1.0, or Version 1.0A, or Version 1.0B follow the upgrade procedure provided in Attachment C. Refer to Attachment D for a description of ECO's fixed by this kit. A copy of the DSM Release Notes is distributed in hard copy with the documentation set and on line as a file with the DSM distri- bution kit. You can obtain a copy of these release notes when you install DSM by installing the release note subset DSMREL103. The following files are installed: /usr/opt/DSM103/relnotes/dsm_relnotes.txt /usr/opt/DSM103/relnotes/dsm103.cover_letter Thank you for purchasing DSM. Sincerely, The DSM Product Group ©Digital Equipment Corporation. 1993,1994. All rights reserved. The following are trademarks of Digital Equipment Corporation: Alpha AXP, AlphaGeneration, AXP, Bookreader, DEC, Digital, DSM, the AlphaGeneration design mark, and the DIGITAL logo. OSF and OSF /1 are registered trademarks of the Open Software Foundation, Inc. 2 Attachment A - Additional Product Information This section contains additional product information and documen- tation corrections. System Parameters that Affect DDP The following section was omitted from the DSM Database Operations Guide. The DSM DDP driver process uses message queues to communicate with DSM user processes and DDP server processes. The default values of the system parameters shown in Table 1 are too low for use with DDP. ___________________________________________________________________ Table_1:__Message_Queue_Parameters_________________________________ Parameter______Default______Description____________________________ msgtql 40 Number of system message headers msgmnb 16384 Maximum number of bytes on a message ____________________________queue__________________________________ If these parameters are too low, DSM user processes can hang in- definitely waiting for a response from the DDP driver. In addi- tion, you will see error messages that contain the following text in the DDP driver log file /usr/tmp/dsmddpdrv.log: EAGAIN error, increase system parameters MSGTQL and MSGMNB. Use the following to determine new values for these parameters: msgtql = (maximum DDP job number * 2) msgmnb = (maximum DDP job number * 1000) The default value for the maximum DDP job number is 128. The mini- mum is 10 and the maximum is 512. You can override the default by specifying the -j command line switch in /usr/sbin/dsmddpstartup.sh. To establish new values for msgtql and msgmnb you must modify the configuration file in /usr/sys/conf and rebuild the kernel. For example, if the maximum DDP job number is 64, you should add the following lines to the configuration file: msgtql 128 msgmnb 64000 Note that you may need to specify a larger value for msgtql if you use message queues in applications other than DSM. To display the current values of msgtql and msgmnb, log in as root and enter the following: # dbx -k /vmunix (dbx) print msginfo (dbx) quit 3 Additional DDP Driver Log File The following section was omitted from the DSM Database Operations Guide. The DSM DDP driver process redirects standard output and stan- dard error to /usr/tmp/dsmddpdrv.out. This file is used to log unexpected system call errors or DDP driver errors. The file /usr/tmp/dsmddpdrv.log is used to log DDP status information. Both files are initialized when you run /usr/sbin/dsmddpstartup.sh to start the DDP driver process. Disk Space Requirements Table 1-1 in the DSM Installation and Management Guide contains an error in the disk space requirements. The following table corrects this error. DSM Major Components (DSMBASE103) 16,000 Kbytes DSM_XMUMPS_DICTIONARY Environment Variable is Obsolete Chapter 1 in the X and Motif Reference and Programming Guide for DSM incorrectly states that you must define the DSM_XMUMPS_DICTIONARY environment variable before you can use the X Windows System In- terface. It not necessary to define this environment variable. DSM automatically uses /usr/lib/dsm/xwin/dsm_xmumps_dictionary.dat. 4 Application Programming Interface (API) Routines The following section was omitted from the DSM Programmer's Guide. DSM supplies API routines that allow you to call back the inter- preter from a user-written external routine. Include these API routines as follows: #include These API routines allow you to do the following: o Retrieve the value of a MUMPS local variable: int dsm_api_local_get( DSM_CSTRING *argi_local_variable, DSM_CSTRING *argo_get_value ); o Delete a MUMPS local variable from the local symbol table: int dsm_api_local_kill( DSM_CSTRING *argi_local_variable ); o Assign a value to a MUMPS local variable: int dsm_api_local_set( DSM_CSTRING *argi_local_variable, DSM_CSTRING *argi_set_value ); o Execute a line of MUMPS code with the XECUTE command: int dsm_api_xecute( DSM_CSTRING *argi_code ); The parameters and return values are as follows: PARAMETERS argi_local_variable Points to a DSM_CSTRING containing the name of a MUMPS local variable. argo_get_value Points to a DSM_CSTRING that receives the value of the local variable. argi_set_value Points to a DSM_CSTRING that specifies the value to assign to the local variable. argi_code Points to a DSM_CSTRING containing a line of DSM code that is a valid argument to the MUMPS XECUTE command. RETURN VALUES All routines return 0 to indicate success and -1 to indicate an error. The DSM_CSTRING typedef and the function prototypes for the API routines are defined in /usr/include/dsmapi.h. To use the API routines you must first call a user-written external routine. The external routine can then call back the API routines. An example that demonstrates calling all the API routines is available on line in these files: /usr/examples/dsm/dsm_example_eccode.c /usr/examples/dsm/dsm_example_ectable.tab 5 Table to Control Outbound Terminal Connections The following information supplements the information in the DSM Programmer's Guide. o The following section was omitted from Chapter 9: The process of initializing an account as a DSM environment manager creates a template file, dsm_remote_ttys.dat, in the dsmdir subdirectory of the manager account home directory. This file is used to establish initial serial line characteristics (baud rate, parity, stop bits, 7 or 8 bit character size) for terminal devices opened by the M OPEN command. (This file is not used for the login terminal device - $PRINCIPAL). The file contains a description of its format. Each line of this file not beginning with a semicolon (;) con- tains three fields. The first field is the path of the character special file being opened, for example: /dev/tty07. The second field is the speed label (first field) of an en- try in /etc/gettydefs that describes the serial line char- acteristics to use when opening the terminal. See reference pages for /etc/gettydefs for details. The entry in dsm_remote_ ttys.dat should point to an entry in /etc/gettydefs that in- cludes the HUPCL keyword. This will ensure that the operating system forces the line to be disconnected when closed. This is especially important for modems and LAT ports. The third field is the terminal type in the terminfo database that describes escape sequences appropriate for the terminal connected to the port. An example file is provided: /usr/examples/dsm/dsm_remote_ttys.example o On page 9-20, the following sentence is incorrect: This is done by editing the appropriate lines in /etc/ttys so that the fourth field reads off instead of on. This sentence should be corrected to read: This is done by putting "off" in the third ":" delimited field in /etc/inittab. 6 String Collation of Globals The following was enabled for V1.0C-019. The V1.0C kit of DSM for DEC OSF/1 AXP provides string (ASCII) collating sequence support in addition to the numeric collating sequence supported by V1.0A and V1.0B. A collating sequence is the order in which the nodes of a global array are returned by the $ORDER and $QUERY functions. In numeric collating sequence, DSM sorts nodes in the following order: 1. DSM sorts all nodes with canonic numbers as subscripts in the ascending numeric order of their subscripts. Negative canonic subscripts sort first, then a subscript of zero, and finally positive canonic subscripts. 2. DSM sorts all nodes with subscripts consisting of alphanumeric strings (such as "B9") or noncanonic numbers (such as -0.5) in the ascending order of the total ASCII value of their subscript characters. In string (ASCII) collating sequence, DSM returns all nodes in the ascending order of the ASCII values of their subscript characters. One of the following procedures should be used to set the collat- ing sequence on your system: 1. The ^CONFIG utility allows you to change the default collating sequence for a configuration as follows: >D ^CONFIG . . . Modify Database Sets included in this configuration [Y OR N] ? Modify Distributed Data Processing parameters [Y OR N] ? Modify GLOBAL attributes [Y OR N] ? Y Enable journaling attribute [Y OR N] ? Keep global attributes after KILL [Y OR N] ? Set collating attribute [S=String/N=Numeric] S . . . 2. You may choose the ^%GLOMAN utility to set the collating sequence on a global-by-global basis after configuration startup: >D ^%GLOMAN Global Management Utility Enter volume set name > AAA Enter UCI name > LIB Global > ^A 7 ^A is currently not defined Do you want to create and place ^A [Y OR N] ? Enter new global attribute information Set collating attribute [S=String/N=Numeric] S . . . Global Attributes for: ^A Journaling: DISABLED Keep: NO Collating: STRING . . . 3. When the global is only defined on the top level with no descendant nodes, its collating sequence can be reset by the ^%GLOMAN utility as shown in the following example: >K ^B >S ^B="" >D ^%GLOMAN Global Management Utility Enter volume set name > AAA Enter UCI name > LIB Global > ^B Global Attributes for: ^B Journaling: DISABLED Keep: NO Collating: NUMERIC Starting Ending Growth Area Volume:Map:Block Volume:Map:Block ----------- ---------------- ---------------- Global Data Growth 1:0:0 NONE Global Pointer Growth 1:0:0 NONE Access Privileges System World Group UCI Modify global attributes [Y OR N] ? > Set collating attribute [S=String/N=Numeric] S Enable journaling attribute [Y OR N] ? Keep global attributes after KILL [Y OR N] ? . . . 8 Attachment B - Updated Product Installation Example The following example supersedes the installation example in the DSM Installation and Management Guide. # /usr/sbin/setld -l /dev/nrmt0h Please make sure your installation tape is mounted and on-line. Are you ready (y/n)? y Positioning Tape The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1) DSM V1.0C for DEC OSF/1 AXP DASL Subset 2) DSM V1.0C for DEC OSF/1 AXP Reference Page 3) DSM V1.0C for DEC OSF/1 AXP Release Notes 4) DSM V1.0C-001 for DEC OSF/1 AXP X Window Subset 5) DSM V1.0C-019 for DEC OSF/1 AXP Base Subset Enter your choices or press RETURN to display the next screen. Choices (for example, 1 2 4-6): Or you may choose one of the following options: 6) ALL of the above 7) CANCEL selections and redisplay menus 8) EXIT without installing any subsets Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6):6 You are installing the following optional subsets: DSM V1.0C for DEC OSF/1 AXP DASL Subset DSM V1.0C for DEC OSF/1 AXP Reference Page DSM V1.0C for DEC OSF/1 AXP Release Notes DSM V1.0C-001 for DEC OSF/1 AXP X Window Subset DSM V1.0C-019 for DEC OSF/1 AXP Base Subset Is this correct? (y/n): y Checking file system space required to install selected subsets: File system space checked OK. DSM V1.0C for DEC OSF/1 AXP Release Notes Copying from /dev/nrmt0h (tape) Verifying DSM V1.0C for DEC OSF/1 AXP Reference Page Copying from /dev/nrmt0h (tape) Verifying 9 DSM V1.0C-001 for DEC OSF/1 AXP X Window Subset Copying from /dev/nrmt0h (tape) Verifying DSM V1.0C-019 for DEC OSF/1 AXP Base Subset Copying from /dev/nrmt0h (tape) Working....Sun Jan 2 05:37:11 EST 1994 Verifying DSM V1.0C for DEC OSF/1 AXP DASL Subset Copying from /dev/nrmt0h (tape) Working....Sun Jan 2 05:37:49 EST 1994 Verifying Release notes for DSM103 may be found at : /usr/opt/DSM103/relnotes/dsm_relnotes.txt A list of problems corrected in this release may be found at: /usr/opt/DSM103/relnotes/dsm103.cover_letter Linking the dsm image with X Windows packages .... NOTE: If you are upgrading from a previous release of DSM, the following command must be executed by each DSM environment manager. /usr/sbin/dsmupgrade.sh This will update library and manager routines and globals in the DSM baseline and other mounted volume sets. Installation of DSM V1.0C for DEC OSF/1 AXP completed. Do you want to run the IVP for DSMBASE103 now [y or n] ? y DSM V1.0C-019 for DEC OSF/1 AXP Base Subset (DSMBASE103) Copyright (c) Digital Equipment Corporation 1993,1994. All rights reserved. DSMBASE103: Starting Installation Verification Procedure (IVP). If this fails, please include the following when submitting a report: 1 This subset name, which is DSMBASE103 2) The /tmp/DSMBASE103/dsmdir/dsmivp.output file that was generated 3) This setld session 0 verification errors encountered. 0 corrections performed. Created scratch directory : /tmp/DSMBASE103 Executing dsm in IVP mode... Executing dsm in IVP mode using current output device... DSM V1.0C-019 for DEC OSF/1 AXP root [NoVolume] Subset = DSMBASE103 10 Installation of DSM for DEC OSF/1 AXP is successful. *********************************************************************** * * IVP for DSMBASE103 was successful. * *********************************************************************** 11 Attachment C - Procedure for Upgrading From a Previous Version of DSM The following procedure describes how to upgrade from a previous version of DSM. Note that subset identifiers in examples apply to DSM V1.0 for DEC OSF/1 AXP. 1. Check the integrity of every volume set for each DSM environ- ment on your system. To do this, start a configuration in each DSM environment that mounts all known volume sets and use the ^IC Utility to ensure that each volume set (including the DSM baseline volume set) is clean. If errors are detected, do not continue with this upgrade pro- cedure until the errors are fixed using the ^FIX Utility and the integrity checker runs cleanly. 2. Back up all of your volume sets. 3. Use the ^SHUTDWN Utility to shut down every DSM environment. This includes environments that are running in baseline mode. 4. Verify that all environments have been shut down before con- tinuing with the upgrade procedures. For example, enter the following: % ps aux | grep dsm dsmmgr 1347 ... 0:00 dsm -S garcol -E dsmmgr dsmmgr 1346 ... 0:00 dsm -S demon -E dsmmgr dsmmgr 1348 ... 0:00 grep dsm The previous example shows that baseline mode is still running for the dsmmgr DSM environment. The following example indicates that there are no DSM environments running a configuration or baseline mode: % ps aux | grep dsm dsmmgr 1342 0.0 0.3 8.14M 96K p0 S 0:00 grep dsm 5. Log in to the root account on your system and change your di- rectory to the root directory (/). 6. Shut down DDP as follows: # /usr/bin/dsmddpdrv -S 7. The following files are overwritten during the upgrade proce- dure: /usr/sbin/dsmddpstartup.sh /usr/sbin/dsmshutdown.sh /usr/sbin/dsmstartup.sh /usr/sbin/dsmshut_script.sh /usr/sbin/dsmstart_script.sh If these files have been modified and you want to keep copies of these files for reference, you can copy them to another directory. For example: 12 # cp /usr/sbin/dsmddpstartup.sh /scratch # cp /usr/sbin/dsmshutdown.sh /scratch # cp /usr/sbin/dsmstartup.sh /scratch # cp /usr/sbin/dsmshut_script.sh /scratch # cp /usr/sbin/dsmstart_script.sh /scratch NOTE Do not restore these files after you complete the in- stallation of DSM for DEC OSF/1 AXP. You must edit the newly installed files if you want to include site-specific information. 8. Determine which of the DSM for DEC OSF/1 AXP subsets are in- stalled on your system. # /usr/sbin/setld -i | grep DSM DSMBASE100 installed DSM V1.0 for DEC OSF/1 AXP Base Subset DSMDASL100 installed DSM V1.0 for DEC OSF/1 AXP DASL Subset DSMMAN100 installed DSM V1.0 for DEC OSF/1 AXP Reference Page DSMREL100 installed DSM V1.0 for DEC OSF/1 AXP Release Notes DSMXWIN100 installed DSM V1.0 for DEC OSF/1 AXP X Window Subset 9. Delete each of the installed DSM for DEC OSF/1 AXP subsets from your system. It is recommended, but not mandatory, that you delete the files in the following order: # /usr/sbin/setld -d DSMREL100 Deleting DSM V1.0 for DEC OSF/1 AXP Release Notes (DSMREL100). # /usr/sbin/setld -d DSMMAN100 Deleting DSM V1.0 for DEC OSF/1 AXP Reference Page (DSMMAN100). # /usr/sbin/setld -d DSMXWIN100 Deleting DSM V1.0 for DEC OSF/1 AXP X Window Subset (DSMXWIN100). # /usr/sbin/setld -d DSMDASL100 Deleting DSM V1.0 for DEC OSF/1 AXP DASL Subset (DSMDASL100). # /usr/sbin/setld -d DSMBASE100 Deleting DSM V1.0 for DEC OSF/1 AXP Base Subset (DSMBASE100). 10.Install the new DSM V1.0C for DEC OSF/1 AXP kit. For details about the installation procedure, see the DSM Installation and Management Guide. Refer to Attachment B for an updated installation example. 11.Log in to each DSM environment manager account and execute the /usr/sbin/dsmupgrade.sh shell script to upgrade your baseline volume sets, configuration definitions, application volume sets, and routines. If you are upgrading from DSM V1.0 or V1.0A or V1.0B for DEC OSF/1 AXP you do not need to recompile your application rou- tines. The following example describes how to run dsmupgrade.sh. 13 Example 1: Using dsmupgrade.sh to Upgrade Volume Sets % /usr/sbin/dsmupgrade.sh DSM V1.0C-019 for DEC OSF/1 AXP dsmmgr [Baseline] Loading globals from /usr/sbin/dsmglobals.upg ... Loading routines from /usr/sbin/dsmroutines.upg ... Removing obsolete utilities ... Volume label upgraded for /usr/users/dsmmgr/dsmdir/dsmbaseline.gls Finished upgrading the baseline volume set Initializing baseline mode... DSM Configuration Upgrade This utility updates configuration definitions for compatibility with the current version of DSM. All volume sets mounted by a configuration will be upgraded, and application routines can be recompiled. ... Compiling routines in all application volume sets Compiling routines in [LIB,MSS] 0 routines recompiled Compiling routines in [MSS,MSS] ... Shutting down DSM configuration Shutdown complete. % 14 Attachment D - ECO Descriptions The following information describes known problems in previous versions of DSM for DEC OSF/1 AXP. These problems have been fixed in DSM V1.0C for DEC OSF/1 AXP. The following table describes DSM ECOs (DSMBASE subset). ___________________________________________________________________ ECO_____DSM_Problem_Description____________________________________ DSM Version 1.0A-008 1 DSM uses a suboptimal byte transfer mechanism during a routine load operation. This compromises application per- formance, especially in applications that are routine load intensive. 2 DSM incorrectly allows a lowercase e to indicate exponen- tial notation in a numeric literal. DSM should only allow an uppercase E to indicate exponential notation. 3 DSM sometimes mishandles a KILL of a local variable array subtree. The result is unpredictable, but an OSF segmenta- tion fault is typical. 4 DSM incorrectly accounts for a date change between Green- wich Mean Time (GMT) and the system local time. $H will be incorrect in the time period before or after midnight GMT equal to the local time offset from GMT. The error affects ^%D, ^%T, $H, $ZH. 5 When medium-sized kills done by one process are adjacent to locations in a global that are being set into by another process, some of the sets can become part of the killed data. This can result in those sets not appearing in the global. 6 The file (dsm_remote_ttys.dat), which is in the dsmdir subdirectory of the environment manager's home directory and describes default terminal characteristics for outbound connections, is not opened when a secondary (other than $PRINCIPAL) terminal is accessed by the OPEN command. The system instead tries to open a file named remote.ttys in the same directory. When this file is not found, unuseful default values for baud rate, parity, and other serial line characteristics are used, making host initiated connections to LAT terminals difficult or impossible to establish. This ECO causes the system to open the correct file (dsm_remote_ ttys.dat). Use of this file is described in Attachment A. 7 The ^FORCEX Utility has no effect on a job that is per- forming I/O to a serial device and is waiting for I/O to complete because X/OFF is in effect. The job persists until an X/ON is received. This is problematic when the source of the XOFF is noise on the line and the intent is to use ^FORCEX to clear the line. 15 ___________________________________________________________________ ECO_____DSM_Problem_Description____________________________________ 8 $EXTRACT, $PIECE, and possibly other functions are affected by differences in integral promotion rules induced by com- piler switch changes made during kitting of DSM Version 1.0B-006 for DEC OSF/1 AXP. DSM Version 1.0B-011 9 When issuing a READ with timeout on a TCP channel, the timeout may fail to occur. 10 M READ *X command returns incorrect values when the high bit is set in the byte being read. 11 Opening a TCP channel as a client fails when the value of the last "." delimited field is greater than 127. DSM Version 1.0C-019 12 The $PRINCIPAL special variable returns "" if the principal input device has been redirected. For consistency with ULTRIX DSM, it should return "0". When this occurs and an attempt is made to "USE $PRINCIPAL", an error occurs. 13 Using the inetd mechanism described on page 11-17 of the Programmer's Guide causes the following error to be re- turned by the invoked DSM server when dsm for OSF V1.0B is run on a version 3.0 of OSF: %DSM-E-OPENERR, error opening device or file unsupported stdio device type In addition, the same error is reported when I/O is redirected to a pipe. 14 Improper use of %VIEWBUFFER can corrupt certain fields in volume set labels causing some DSM utilitities, including ^DBT, to fail. 15 ECO 15 corrected the following four problems; 1. Interruptions of read from pipe caused fetch of port and server name to be unreliable. 2. Invalid handling of error return from (1) caused an open file descriptor to be stranded, causing the port to become unusable until the process logged out of DSM. 3. A memory leak in the close command was corrected. 4. A control C interrupt in the dsm_mio_flock() function could result in the timer remaining set. This could lead to a spurious "timeout" error at a subsequent programmer read. 16 This ECO enables string collation of globals. See Attach- ment A for additional details. 17 AIJ file labels get corrupted preventing the subsequent use. Error was "INVALID AIJ FILE" 18 ^%GTO acts differently than ^%GBS for subcripted global save. 19 When running in application mode (dsm -a ^menu), if a use command does not preceed the first read or write operation, ________a_core_dump_results._______________________________________ 16 The following table describes X Windows Interface ECOs (XWIN sub- set). ___________________________________________________________________ ECO_____X_Windows_Interface_Problem_Description____________________ 1 The supplied X Window interface examples may fail to ex- ecute on OSF/1 Version 2.0 because of an uninitialized ________memory_problem.____________________________________________ Copyright Digital Equipment Corporation 1994. All Rights reserved. This software is proprietary to and embodies the confidential technology of Digital Equipment Corporation. Possession, use, or copying of this software and media is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. This ECO has not been through an exhaustive field test process. Due to the experimental stage of this ECO/workaround, Digital makes no representations regarding its use or performance. The customer shall have the sole responsibility for adequate protection and back-up data used in conjunction with this ECO/workaround. 17 ADDHERE