MIRA MicroVAX Software Installation Guide Order Number: AA-KK07C-TN Software Version: MIRA V2.2 digital equipment france, annecy ________________________ September 1990 __________ The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. __________ Copyright ©1990 by Digital Equipment France All Rights Reserved. __________ The following are trademarks of Digital Equipment Corporation: DEC DIBOL UNIBUS DEC/CMS EduSystem VAX DEC/MMS IAS VAXcluster DECnet MASSBUS VMS DECsystem-10 PDP VT DECSYSTEM-20 PDT DECUS RSTS DECwriter RSX DIGITAL This document was prepared using VAX DOCUMENT, Version 1.1 _______________________________________________________ 1 Introduction to MicroVAX/VMS MIRA Software Installation This guide tells you how to install the MicroVAX/VMS MIRA software on your MIRA system. Before you install this software, the VMS operating system (V5.3 or later) must be installed. The MIRA installation takes about 15 minutes. Begin by following the instructions in this guide. After you have followed the preliminary instructions in this guide, you must follow instructions from your terminal to complete the installation. The MicroVAX/VMS MIRA software is distributed on a single TK50 cartridge or one tape. This cartridge or tape contains all the required components to properly install the MIRA software. The MIRA software should be installed on both MIRA systems. It requires 3800 blocks of disk space during installation, but when the installation is complete it only occupies 800 blocks. For more information about the MIRA software, see the following manuals: - MIRA MicroVAX User's guide (Order Number: AA-KK07D- TN) - MIRA Release Notes (in the file SYS$HELP:MRA022.RELEASE_NOTES) The steps to install the VMS software are listed below: 1 Boot the system. 2 Run the VMSINSTAL command file. 1-1 Introduction to MicroVAX/VMS MIRA Software Installation 3 Log out after the installation has completed. Examples of a complete installation and verification procedure, and the list of the files provided by the installation procedure are given in the appendices to this manual. Convention: The symbol means that you must press the RETURN key. 1-2 _______________________________________________________ 2 Installing the MIRA Software __________________________________________________________________ 2.1 Invoking the Installation Command File Log into the SYSTEM account and execute the command file VMSINSTAL in the directory SYS$UPDATE with the following command: @SYS$UPDATE:VMSINSTAL The system asks you if your system disk is backed up, and asks for the device where the cartridge or tape will be mounted. The system reminds you to put the cartridge or tape in the drive and you confirm that the medium is in place by entering "Y". The system asks you for the product name. Then you type MRA. With VMS V5.3, after all the MIRA software has been copied to the disk, the system asks you whether a licence has been registered or not. You should confirm this by entering "Y". If you enter "N", then the installation procedure is aborted and the appropriate licence should be registered before re- installing. Refer to Chapter 6 for details of the licence registration. The system asks you whether MIRA-Ada interface is required or not. If you answer "Y" to this question (which is the default), VAX Ada must be already installed on your processor, otherwise the MIRA installation will fail. 2-1 Installing the MIRA Software The system asks you whether you want to purge the files replaced by this installation. You should confirm by entering , otherwise type "N". __________________________________________________________________ 2.2 Verifying the Installation ___________________________ 2.2.1 * Do you want to run the IVP? This question is asked only if the MIRA-Ada procedure interface is not needed. It is recommended that you run the Installation Verification Procedure in all cases. It is compulsory if the MIRA-Ada procedure interface is installed. The Installation Verification Procedure checks: 1 the MIRA Driver software 2 the MIRA Operator Interface software 3 the MIRA Application Interface software 4 the MIRA-Ada Procedure Interface (if present). Note: The Installation Verification Procedure calls two command files: SYS$TEST:MRA$IVP.COM SYS$TEST:MRA$ADA_IVP.COM You can execute these files at any time as a confidence test. Only the first file should be executed if MIRA-Ada has not been installed. If a problem occurs during the IVP, you should compare two files located in the SYS$TEST directory. One of these files contains the intended (correct) results of a given test, and the other will contain the actual results obtained. Table 2-1 gives the names of these files for each IVP test that is run. 2-2 Installing the MIRA Software Table 2-1 IVP Test Result Files in SYS$TEST: _______________________________________________________ IVP_Test____________Actual_Output_____Intended_Output__ MIRA Driver MRA$DRVOUTPUT.DAT MRA$DRVRESULT.DAT MIRA Operator MRA$OIOUTPUT.DAT MRA$OIRESULT.DAT Interface MIRA Application MRA$AIOUTPUT.DAT MRA$AIRESULT.DAT Interface _______________________________________________________ __________________________________________________________________ 2.3 Post-installation Procedures Do not forget to log out, in order to delete all the logical names and global symbols created by the VMSINSTAL.COM command file. 2-3 _______________________________________________________ 3 System Configuration When the MIRA software installation is complete and the Installation Verification Procedure have been successfully executed, you should configure your system. This is done from the SYSTEM account, by executing the command file SYS$MANAGER:MRA$CONFIG.COM. __________________________________________________________________ 3.1 Questions about the Hardware ___________________________ 3.1.1 * CSR address of the MIRA device? The MIRA device address should be entered in octal notation. If the MIRA device address on your system is different from the standard one, enter the correct address in octal notation (enter only the octal digits, for example: 760400 ), otherwise press . ___________________________ 3.1.2 * Interrupt vector of the MIRA device? The MIRA device interrupt vector, in the range 300- 774, should be entered in octal notation. If the interrupt vector of the MIRA device on your system is different from the standard one, enter the correct vector address (only the octal digits, e.g. 310 ), otherwise press . If you enter a value, the system checks that this value is in the range from 300(8) to 774(8). 3-1 System Configuration __________________________________________________________________ 3.2 Customising the MIRA Software The following questions concern local variations to the setup of the MIRA software. ___________________________ 3.2.1 * Is the Application Interface needed? Enter "N" if you do not need the Application Interface. Otherwise press . ___________________________ 3.2.2 * Directory name for the Switch Map file? The Switch-Map file will be placed in this directory. The default is SYS$MANAGER. ___________________________ 3.2.3 * Do you want to create this directory on your target system directory? The system asks you this question if you enter a directory which does not already exist on the disk. The system will create the directory, if requested. __________________________________________________________________ 3.3 Questions about the Application Interface The questions below are needed to generate the MRA$STARTUP.COM command file. The corresponding answers will be the qualifiers of the MIRA_CONTROL START command. ___________________________ 3.3.1 * Timer value to start MIRA? You should enter a value in seconds, in decimal or integer format. Your answer will be truncated to one place of decimals. The default answer is 5 seconds. Minimum value is 300 milliseconds (0.3 second). Maximum value is 27 seconds. 3-2 System Configuration ___________________________ 3.3.2 * Delay value to start MIRA? You should enter a value in seconds, in decimal or integer format. Your answer will be truncated to one place of decimals. The default answer is 20 seconds. Minimum value is 300 milliseconds (0.3 second). Maximum value is 27 seconds. ___________________________ 3.3.3 * Do you want the MIRA software to start with the ALARM enabled? The default answer corresponds to the command qualifier "/ALARM" for the MIRA_CONTROL START command. ___________________________ 3.3.4 * Do you want the MIRA software to start with the Flag file management enabled? The default answer corresponds to the command qualifier "/FLAGFILE" for the MIRA_CONTROL START command. ___________________________ 3.3.5 * Do you want the MIRA software to start with the standard Master/Standby mode of operation enabled? The default answer corresponds to the command qualifier "/RELEASELINES" for the MIRA_CONTROL START command. ___________________________ 3.3.6 * Maximum delay for line reconnexion attempts? This question is asked only if you have answered "N" to the previous question. You should enter a value in VMS Delta Time format (for example, ":30:00" would specify "thirty minutes". The default answer is 20 seconds. Minimum value is 1 second. There is no maximum value. 3-3 System Configuration ___________________________ 3.3.7 * Do you want the MIRA software to start with automatic clocks synchronization? The default answer corresponds to the command qualifier "/NOCLOCKSYNCHRONIZATION" for the MIRA_CONTROL START command. ___________________________ 3.3.8 * Should clock synchronization be periodically rescheduled? This question is asked only if you have answered "Y" to the previous question. ___________________________ 3.3.9 * Clock synchronization reschedule interval? This question too is asked only if you have answered "Y" to the previous question. You should enter a value in VMS Delta Time format. The default answer is one day (24 hours). Minimum value is 1 minute. There is no maximum value. ___________________________ 3.3.10 * Application Interface Control process priority? You should enter a value in the range 0-15. The default priority is 15. In most cases, you do not need to modify this priority, in which case just press . If you supply a value that is different from the default value, this will have a serious impact on the behaviour of the MIRA system. You should only do this after having acquired an in-depth understanding of how the MIRA software runs. Refer to MIRA MicroVAX User's guide for more information. 3-4 System Configuration ___________________________ 3.3.11 * Is the MIRA-ADA procedure interface needed? If you answer "Y" to this question (this is the default), VAX Ada must be already installed on your processor. Otherwise, the MIRA installation will fail. __________________________________________________________________ 3.4 Mistakes when Answering the Questions ___________________________ 3.4.1 * Do you validate all your previous responses If you are satisfied with all your answers press . Otherwise enter "N". The system then asks you all the questions again. __________________________________________________________________ 3.5 Entering the Switch-Map File Content After building the MIRA software components and if the Application Interface is needed, you are asked for the Switch-Map File content. Refer to "MIRA User's guide" for the structure of this file. 3-5 _______________________________________________________ 4 The Elaborate-Switch-Map Utility This tool is provided to create or alter the Switch- Map file. __________________________________________________________________ 4.1 Components of the Elaborate-Switch-Map Utility It consists of: 1 Two programs which reside on the directory SYS$SYSTEM o MRA$SWITCHMAP_CREATE This program creates a new Switch-Map file. o MRA$SWITCHMAP_MODIFY This program modifies an existing Switch-Map file. 2 One command file which resides on the directory SYS$MANAGER o MRA$SWITCHMAP.COM This command file asks you for the file specification of the Switch-Map to be created or modified. The default answer is the "Default Switch-Map" which is located in the directory defined during configuration (see Section 3.2.2). The system then attempts to find this file on the local computer. If the file is found, the system runs the MRA$SWITCHMAP_MODIFY program to modify the existing switch-map file; if not, the system runs the MRA$SWITCHMAP_CREATE program to create a new switch-map file. 4-1 The Elaborate-Switch-Map Utility __________________________________________________________________ 4.2 Invoking the Elaborate-Switch-Map Utility To invoke the Elaborate-Switch-Map Utility, you must have the SYSPRV privilege. You can invoke this utility, whether the MIRA software is running or not, with the following command: $ @SYS$MANAGER:MRA$SWITCHMAP.COM [switch-map-filename] If you omit the switch-map-filename parameter, you will be asked to supply one. If you then just press , then the default value will be the "Default Switch-Map" if it is defined; there is no default when the "Default Switch-Map" is not defined. Note: You should always have the same Switch-Map file on both systems. To ensure this, you can either create it in the same way on each system, or create it on one system and copy it to the other system via DECnet (if available). __________________________________________________________________ 4.3 Specifying Logical Names for Management of Switch-Map File Four logical names handle the Switch-Map File: 1 Switch-Map Directory The logical name MRA$SWITCHMAP_DIR refers to the directory, containing the switch-map file(s), defined during configuration. 2 Default Switch-Map The logical name MRA$DEF_SWITCHMAP refers to the Switch-Map File MRA$SWITCHMAP.DAT defined during configuration. 3 Working Switch-Map The logical name MRA$SWITCHMAP refers to the Switch-Map used by the Operator Interface and the Application Interface. 4-2 The Elaborate-Switch-Map Utility This logical name is created by the Operator Interface after a MIRA_CONTROL START command, according to the following rules: - If START command contains a /SWITCHMAP qualifier, the "working Switch-Map" equates to that given by the /SWITCHMAP qualifier. - If START command does not contain any /SWITCHMAP qualifier and if the "default Switch-Map" is defined, the "working Switch-Map" equates to the "default Switch-Map". - if START command does not contain any /SWITCHMAP qualifier and if the "default Switch-Map" is not defined, the "working Switch-Map" equates to SYS$MANAGER:MRA$SWITCHMAP.DAT If you start MIRA with an unmodified MRA$STARTUP.COM command file, the "Working Switch-Map" equates to the "Default Switch- Map". 4 Elaborate Switch-Map The logical name MRA$ELAB_SWITCHMAP refers to the Switch-Map used by the "Elaborate Switch-Map" utility. It only exists while MRA$SWITCHMAP.COM is executing. 4-3 _______________________________________________________ 5 Installing in a Cluster Environment This software can be installed on a MIRA system belonging to a VAXcluster. The following should be noted: 1 The installation procedure will put executable files, Switch-Map files and general command files in the common root directories. 2 The installation procedure will put the Switch-Map file and MIRA specific procedures in the specific root directories. 3 The MIRA system, once running, will put the flag file and the events log file in the specific root directories. It is recommended that the software installation procedure be run on each licensed MIRA MicroVAX in your cluster. However, you may greatly speed up this process by observing the following: 1 If your MIRA system is the only MIRA system in your cluster, you can perform the installation once, on either MIRA MicroVAX. Then the specific MIRA startup procedures put into the specific [SYSMGR] directory (MRA$STARTUP.COM, MRA$MASTERSTARTUP.COM, MRA$STANDBY.COM and UTSTARTUP.COM) by the installation procedure, should be moved to the other specified [SYSMGR] directories. The systems will use the same hardware and startup parameters and the same Switch-Map file. 5-1 Installing in a Cluster Environment 2 If you have more than one MIRA system on your cluster, you can perform the installation only once, on either MIRA MicroVAX of any MIRA system of the cluster. In this case, however, you should carry out the following steps. It is assumed that the pairs of MIRA systems have not the same hardware configuration and will not be started with the same MIRA_CONTROL START parameters: i The specific MIRA startup procedures, put into the specific [SYSMGR] directory (MRA$STARTUP.COM, MRA$MASTERSTARTUP.COM, MRA$STANDBYSTARTUP.COM and UTSTARTUP.COM) by the installation procedure, should be moved to the other specific [SYSMGR] directories and edited to reflect the hardware configuration of each pair of MIRA MicroVAX (UTSTARTUP.COM with correct MIRA logic CSR and Vector addresses) and the desired START command parameters (MRA$STARTUP.COM). ii The Switch-Map files should be moved to their respective specific directories in each processor of each MIRA system and then modified as required on the appropriate MIRA MicroVAX computers using the cluster-wide MRA$SWITCHMAP.COM procedure. This will ensure that the right files are found for each MIRA processor in your cluster. Note: If your cluster is a Local Area VAXcluster with two system disks, at least one installation should be performed per disk. 5-2 _______________________________________________________ 6 Software Licensing Versions 5.0 and above of the VMS operating system include the Licence Management Facility (LMF). This is a software feature which prevents customers from using software for which they have not purchased a licence. Version 2.2 of MIRA incorporates an interface to LMF. This has the following repercussions: o If you install MIRA V2.2 for use with VMS Version 5.0 or above, you will have to supply the appropriate key at installation time. o If you install MIRA V2.2 for use with VMS Version 4.x, and you subsequently update VMS to Version 5.3 or above without supplying the MIRA key at VMS installation time, you will get an error when you execute the MIRA_CONTROL command-that is, you will not be able to execute commands at the MIRA> prompt. 6-1 _______________________________________________________ 7 Licence Registration Procedure On VMS V5.3, you should register your MIRA licence before install it. For this purpose, you should enter the following command: @SYS$UPDATE:VMSLICENSE The systems asks you the characteristics of the MIRA Software to be registered. Use the PAK provided with the software to register the licence. 7-1 _______________________________________________________ A Example of VMS V5.0 Installation and Verification Process $@SYS$UPDATE:VMSINSTAL VAX/VMS Software Product Installation Procedure V5.3-0 It is 14-SEP-1990 at 16:50. Enter a question mark (?) at any time for help. * Are you satisfied with the backup of your system disk [YES] ? * Where will the distribution volumes be mounted: $2$DIA3:[0,0] Enter the products to be processed from the first distribution volume set. * Products: MRA022 * Enter installation options you wish to use (none): The following products will be processed: MRA V2.2 Beginning installation of MRA V2.2 at 16:50 %VMSINSTAL-I-RESTORE, Restoring product save set A ... %VMSINSTAL-I- RELMOVED, Product's release notes have been moved to SYS$HELP. Product: MIRA-SWITCH-CONTROL Producer: DEC Version: 2.2 Release Date: 01-JUL-1990 * Does this product have an authorization key registered and loaded? Y Your MIRA driver is loaded. Until the system can be rebooted to activate the new driver, the Installation Verification Procedure (IVP) is not testing the newly installed driver.To properly test the new driver, please reboot the system and run the IVP. You should reboot your system when your installation is complete and run the Installation Verification Procedure with the following command : @SYS$TEST:MRA$IVP A-1 Example of VMS V5.0 Installation and Verification Process * Is MIRA-ADA interface needed (VAX- ADA must be already installed) [YES]? N * Do you want to purge files replaced by this installation [YES]? * Do you want to run the IVP after the installation [YES]? We have now to build the MIRA software components. This can take 10 to 20 minutes, depending on your quotas. Please, wait ... The MRA$STOP.COM command file which stops the MIRA software is located on the SYS$MANAGER directory. If you want to stop the MIRA software at system shut- down, you have to add the invocation of this file in your SYS$MANAGER:SYSHUTDWN.COM command file. The MRA$STARTUP.COM command file which starts the MIRA software is generated by the MRA$CONFIG.COM procedure. If you want to start the MIRA software at system start- up,you have to add the invocation of this file in your SYS$MANAGER:SYSTARTUP_ V5.COM Please ensure that you logout after the installation is complete in order that the products logicals are correctly defined. After this installation, please execute the MRA$CONFIG.COM procedure to ensure a correct configuration of your system. This procedure is located in the SYS$MANAGER directory. %VMSINSTAL-I- MOVEFILES, Files will now be moved to their target directories... * Beginning the MIRA Installation Verification Procedure. The MIRA V2.2 Driver Software has been tested successfully. The MIRA V2.2 Operator Interface Software has been tested successfully. The MIRA V2.2 Application Interface Software has been tested successfully. The MIRA V2.2 standard Installation Verification Procedure has been tested successfully A-2 Example of VMS V5.0 Installation and Verification Process * The MIRA V2.2 installation has been installed successfully Installation of MRA V2.2 completed at 16:55 Enter the products to be processed from the next distribution volume set. * Products: EXIT VMSINSTAL procedure done at 16:56 A-3 _______________________________________________________ B List of the files provided by MIRA installation The following files are provided by the Installation Procedure: _______________________________________________________ Directory:_SYS$SYSTEM__________________________________ UTDRIVER.EXE MIRA Driver UTTESTER.EXE Driver Tester for Installation Verification Procedure MRA$OPERATOR.EXE Operator Interface program MRA$CONTROL.EXE Application Interface program MRA$TRIGGER.EXE Trigger program MRA$DEMO.EXE Application Interface Tester for Installation Verification Procedure MRA$SWITCHMAP_ Program to create a new Switch- CREATE Map .EXE MRA$SWITCHMAP_ Program to modify an existing MODIFY Switch-Map .EXE B-1 List of the files provided by MIRA installation _______________________________________________________ Directory:_SYS$SYSTEM__________________________________ MRA$SAMPADA.EXE Application Interface Tester written in Ada for Installation Verification Procedure (if MIRA- Ada procedure interface required) _______________________________________________________ Directory:_SYS$MANAGER_________________________________ UTSTARTUP.COM Loads the driver MRA$STARTUP.COM Starts the MIRA Application Interface MRA$MASTERSTARTUP.COMInvoked each time the system starts as MASTER MRA$STANDBYSTARTUP.COInvoked each time the system starts as STANDBY MRA$STOP.COM Stops the MIRA Application Interface MRA$SWITCHMAP.COM "Elaborate Switch-Map" command file B-2 List of the files provided by MIRA installation _______________________________________________________ Directory:_SYS$HELP____________________________________ MRATESTHELP.HLB Help Messages File for the Driver Tester MRADEMOHELP.HLB Help Messages File for the Application Interface Tester MRAHELP.HLB Help Messages File for the Operator Interface _______________________________________________________ Directory:_MRA$SWITCHMAP_DIR___________________________ MRA$SWITCHMAP.DAT Switch-Map File _______________________________________________________ Directory:_SYS$MESSAGE_________________________________ MRAMSG.EXE MIRA Software Messages file B-3 List of the files provided by MIRA installation _______________________________________________________ Directory:_SYS$LIBRARY_________________________________ UTDEF.BAS Symbols and statuses used by the MIRA Driver (for BASIC programs) UTDEF.FOR Symbols and statuses used by the MIRA Driver. (for FORTRAN programs) UTDEF.H Symbols and statuses used by the MIRA Driver (for VAX-C programs) UTDEF.MAR Symbols and statuses used by the MIRA Driver. (for MACRO programs) UTDEF.PAS Symbols and statuses used by the MIRA Driver. (for Pascal programs) B-4 List of the files provided by MIRA installation _______________________________________________________ Directory:_SYS$LIBRARY_________________________________ UTDEF.PLI Symbols and statuses used by the MIRA Driver (for PL1 programs) UTDEF.R32 Symbols and statuses used by the MIRA Driver (for BLISS programs) UT_SSDEF.OBJ MIRA software module to be linked with user applications. It contains all the statuses returned by the MIRA Driver. (refer to MIRA User's guide Manual) MRA$USER.OBJ MIRA software module to be linked with user applications. It contains the code of the functions MRACON, MRAENA, MRADIS and MRASWA. B-5 List of the files provided by MIRA installation _______________________________________________________ Directory:_SYS$LIBRARY_________________________________ MRAMSGPNTR.OBJ MIRA software module to be linked with user applications. It contains all the statuses returned by the MIRA Application Interface. (refer to MIRA User's Guide) [MIRA_ADALIB...] Ada objects and ACU files necessary to compile an user application program written in Ada with the two packages MIRA and MIRA_STATUS (if MIRA-Ada required) UTDEF.ADA Symbols and statuses used by the MIRA Driver. for Ada programs (if MIRA-Ada required) B-6 List of the files provided by MIRA installation _______________________________________________________ Directory:_SYS$TEST____________________________________ MRA$IVP.COM MIRA Installation Verification Procedure MRA$DRVTEST.COM Driver Tester command file MRA$DRVRESULT.DAT Driver Tester expected results MRA$OITEST.COM Operator Interface test command file MRA$OIRESULT.DAT Operator Interface test expected results MRA$AITEST.COM Application Interface Tester command file MRA$AIRESULT.DAT Application Interface Tester expected results MRA$ADA_IVP.COM MIRA-Ada Installation Verification Procedure if MIRA- Ada required MRA$ADA_ MIRA-Ada Interface Tester AIRESULT.DAT expected results if MIRA-Ada required B-7