Home

OpenVMS Developer`s Guide to VMSINSTAL

1. Return In examples a key name enclosed in a box indicates that you press a key on the keyboard In text a key name is not endosed in a box A horizontal ellipsis in examples indicates one of the following possibilities e Additional optional arguments in a statement have been omitted e The preceding item or items can be repeated one or more times e Additional parameters values or other information can be entered A vertical ellipsis indicates the omission of items from a code example or command format the items are omitted because they are not important to the topic being discussed In format descriptions parentheses indicate that if you choose more than one option you must enclose the choices in parentheses boldface text italic text UPPERCASE TEXT numbers In format descriptions brackets indicate optional elements You can choose one none or all of the options Brackets are not optional however in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement In format descriptions braces surround a required choice of options you must choose one of the options listed Boldface text represents the introduction of a new term or the name of an argument an attribute or a reason Boldface text is also used to show user input in Bookreader versions of the manual Italic text emphasizes importa
2. IF DECRAM_ARCH EQ 1 THEN GOTO DECRAM_AXP DECRAM_LINK 1 IF DECRAM_LATEST THEN GOTO DECRAM_LOADLATEST IF VVER EQS V5 2 THEN GOTO DECRAM_LOAD52 IF VVER EQS V5 3 THEN GOTO DECRAM_LOAD53 DECRAM_LOADLATEST VMISCALLBACK RESTORE_SAVESET F DECRAM_CLD 0 GOTO DECRAM_INST_COM Ur Ur Ur Ur Ur Ur Ur Ur Ur continued on next page B 5 Sample OpenVMS Installation Procedure Example B 1 Cont Sample DIGITAL OpenVMS KITINSTAL COM DECRAM_LOAD53 VMISCALLBACK RESTORE_SAVESET E DECRAM_CLD 1 VMISCALLBACK RENAME_FILE V53X_INIT CLD INIT CLD GOTO DECRAM_INST_COM DECRAM_LOAD52 VMISCALLBACK RESTORE_SAVESET D DECRAM_CLD 1 GOTO DECRAM_INST_COM DECRAM_AXP VMISCALLBACK RESTORE_SAVESET G DECRAM_CLD 0 DECRAM_LINK 0 GOTO DECRAM_INST_COM DECRAM_INST_COM VMISCALLBACK TELL_QA DECRam Executables IVP are placed in SYSSSPECIFIC IF DECRAM LINK EQ 0 THEN GOTO DECRAM_NOLINK LINK NOSYSSHR NOTRACEBACK NODEBUG SHARE VMISKWD MDDRIVER CONTIGUOUS MAP VMISKWD MDDRIVER FULL CROSS VMISKWD MDDRIVER T sys system SYS STB SELECTIVE VMISKWD MDDRIVER OPTION DECRAM_NOLI IF NOT DECRAM_CLD THEN GOTO DECRAM_INST_COM05 IF NOT DECRAM_ADDCLD THEN GOTOT DECRAM_INST_COM01 VMISCALLBACK PROVIDE_DCL_COMMAND V53X_INIT CLD GOTO DECRAM_INST_COM02 DECRAM_INST_COMO1 VMISCALLBACK PROVIDE_DCL_COMMAND INIT CLD DECRAM_INST_COM02 VMISCALLBAC DECRAM_INST_COM0
3. This local symbol is also equated to the name of the product being installed however it is implemented for internal logic functions only When a file is to be printed VMSINSTAL assigns this process logical name to the specified file before issuing the PRINT command When this global Boolean symbol is set true files that have been replaced during the installation should be deleted This Boolean symbol is set true if the Q option has been selected in the command that calls VMSINSTAL This global Boolean symbol is set true if the installation fails This symbol is defined to be the queue to which release notes are printed See the RELEASE_NOTES callback for more information When this global Boolean symbol is true VMSINSTAL will automatically reboot the system upon completion of the installation This local symbol is defined to be the name of the release notes file This local Boolean symbol is set true when the distribution volume is located on a remote node This local Boolean symbol is set true when the console distribution volume is mounted on a console device or mounted FOREIGN on a disk device Upon completion of the installation the console distribution volume must be remounted This process logical name is assigned to a subroutine used by KITINSTAL to clean up files using minimal overhead This logical name is assigned the value of the root directory being used for the installation The value is SYS COMMON if y
4. s files but does not invoke the product you can use the FIND _FILE callback to verify the product s existence and to set up a logical name for accessing the file e If the procedure must invoke another product you can use the FIND FILE callback to determine the existence of the product then invoke the product with the appropriate command Because this usually involves implicit references to the other product s files VMSINSTAL assumes that these files are in the system root or on a user disk e Ifa product requires a minimum version of another product to be installed on the system use the CHECK_PRODUCT_ VERSION callback See Section 5 5 for more information on this callback 2 8 Changing Global State If your installation procedure changes the global state of the system except in reference to callbacks it must restore that state before terminating For example if the installation procedure needs to invoke the Install utility to install an image that is needed for completing the installation it must deinstall the image before exiting Any use of the Install utility following installation of the product should be provided by a product specific startup command procedure For more information refer to the the SET STARTUP option description in Section 5 28 12 2 9 Verifying Installation Your product kit should include an Installation Verification Procedure IVP which is a procedure for checking the completeness and accuracy of t
5. 3 5 KITINSTAL Command Procedure 3 3 Summary of KITINSTAL Design Specifications 3 3 Summary of KITINSTAL Design Specifications As a minimum requirement your KITINSTAL COM must do the following Handle errors and Ctrl Y interrupts Process the request code passed to it in the first parameter P1 it should exit with VMI UNSUPPORTED status if it does not recognize the request code Currently VMSINSTAL may pass one of three request codes VMI INSTALL to initiate the installation VMI POSTINSTALL to initiate work required after the installation phase is complete VMI IVP to initiate the IVP However because additional request codes may be implemented by VMSINSTAL in the future your KITINSTAL should make explicit tests on P1 For example do not assume that if VMSINSTAL is not passing VMI INSTALL or VMI POSTINSTALL it must be passing VMI _IVP Also note that subprocedures can be used to invoke KITINSTAL for services by passing the appropriate string in P1 For example the ASK callback may use KITINSTAL to get some help text from the HELP_DEVICE subroutine by passing the string HELP_DEVICE in P1 Verify that it is compatible with the version of OpenVMS running on the target system Determine whether the target system has sufficient free disk space for the product and for specified safety mode operations Determine whether to retain old copies of files that have been replaced Where applicable restore s
6. Digital recommends you use the new format whenever possible VMSINSTAL Callbacks 5 6 CHECK_VMS_VERSION Callback option The following options are currently available for P4 e F Limits the product installation to a specific field test version This option is intended for use only if a layered product is conducting field test in conjunction with an OpenVMS field test If you choose option F use P3 to specify the field test version to which the product installation is limited e S Suppresses message output during installation This option is intended for range checking of the OpenVMS version messages are not output to the screen maximum_version Use this parameter where appropriate to specify the maximum OpenVMS version required to install the product Specify maximum version in the following format vv u m where vv indicates a version u indicates an update m indicates a maintenance release For example 5 2 1 would indicate that the version is 5 the update is 2 and the maintenance level is 1 To specify Version 5 2 you would enter 5 2 This parameter continues to accept the old format vvu for example you can specify 052 to indicate Version 5 2 however to specify a particular maintenance release you must use the new format Digital recommends you use the new format whenever possible The following is an example of the command line for the CHECK_VMS_VERSION callback VMISCALLBACK CHECK_VMS_VERSION for_ve
7. If it is VMSINSTAL records the command in VMIDEFER COM logically referred to as VMISDEFER_FILE otherwise the command is executed immediately When the installation progresses to the second phase each of the deferred commands is executed in the order in which it was originally issued You set the required level of safety for the installation by specifying the SAFETY option with the SET callback By default VMSINSTAL automatically implements safety mode operations unconditionally regardless of whether you use the SET SAFETY option However unconditional safety mode requires a higher peak disk space If you use the SET SAFETY option you can specify the keyword CONDITIONAL to implement safety mode only if there is sufficient disk space to support it Your installation procedure should use the SET SAFETY option to help the installers of your product select a feasible level of safety for their particular situation See Section 5 28 9 for more information on this option 1 9 Recovery from System Failure In addition to providing the safety feature implemented through deferred operations VMSINSTAL creates a marker file in the system update directory to aid in recovery from system failures that occur during the installation The marker file is named VMIMARKERpid DAT where pid is the process identification and logically referred to as VMISMARKER FILE This file periodically records state information as the installation progresses By
8. Il o l DONE_ARCH At this point DECRAM_ARCH is 0 if VAX or 1 if AXP WRITE SYS OUTPUT WRITE SYS OUTPUT Copyright c 1992 Digital Equipment Corporation All rights reserved WRITE SYS OUTPUT l Before starting anything OpenVMS version 1 DKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KK RA AAA Must be OpenVMS V5 2 or later DKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK RARA KK KK KK AAA 1 continued on next page B 2 Sample OpenVMS Installation Procedure Example B 1 Cont Sample DIGITAL OpenVMS KITINSTAL COM UY Ur Ur Ur Ur Ur Ur Ur UU HMM HNN UA UY VN UY N MMH UY UY UY UY UY UY UY UY UY UY UY UY Y Y UY Y Ur Ur Ur Ur Ur Ur Ur Ur IF DECRAM_ARCH EQ 1 THEN GOTO DECRAM_VERSION_DONE CHECK_VMS_VERSION ON ERROR THEN GOTO DECRAM_VERSION_ERROR Version check may blow up on pre V4 system I Q heck OpenVMS version for supported release Define earliest released version of OpenVMS supported by DECRAM DECRAMSREL_VERSION 052 Define earliest field test version of OpenVMS supported by DECRAM DECRAMSFT_VERSION 052 l Extract current running version number of OpenVMS DECRAMSVMS_VERSION FSELEMENT 0 VMIS VMS_VERSION DECRAMSVMI_VERSION FSELEMENT 1 VMISVMS_VERSION DECRAM_RELEASED l Check for RELEASED version y NOTE use String comparison to check in case version number c
9. P6 to list qualifiers You can specify any of the qualifiers available for the DCL command SET ACL Enclose the qualifier list with quotation marks Following is an example of the command line for the SET ACL option VMISCALLBACK SET ACL FILE _ identifier NODEA IDENT ACCESS NONE VMISROOT SYSUPD FRED DAT In this example the SET ACL option adds an ACE to the ACL for the file FRED DAT This callback returns VMI SUCCESS if the ACL is successfully modified The callback returns VMI FAILURE if the ACL is not successfully modified 5 28 2 SET ASK_CASE Option The SET ASK_CASE option determines the default case for example upper or lower in which input from the installer is returned to the installation procedure By default input is returned in uppercase You can override the default case for a specific ASK callback by specifying the appropriate ASK option U L or M Use the following command line format to invoke the SET ASK_CASE option VMISCALLBACK SET ASK_CASE case case Use this parameter P 3 to specify the default case You can specify the following values for case e UPPER When you specify UPPER all input is returned in uppercase LOWER When you specify LOWER all input is returned in lowercase MAINTAIN When you specify MAINTAIN all input is returned in the same case as that entered by the installer The SET ASK_CASE option always returns VMI SUCCESS 5 28 3 SET_FILE Option AXP Onl
10. The status returned by the PRODUCT callback is the status returned by the product specific callback Conventions for coding a product specific callback procedure are given in Appendix C 5 20 PROVIDE_DCL_COMMAND Callback AXP The PROVIDE_DCL_COMMAND callback either adds a command to the system DCL command tables and the command tables for the current process or replaces an existing DCL command The callback does this by creating an updated version of DCLTABLES EXE in the installation working directory using the appropriate command language description CLD file which you must include in the installation kit On AXP systems PROVIDE_DCL_CALLBACK checks for the logical definition DCLTABLES If a logical definition for DCLTABLES is present this callback uses the table defined by this logical On both AXP and VAX systems when the installation progresses beyond safety mode the callback moves the updated version of DCLTABLES EXE tothe system directory The callback can be invoked as often as needed to add more commanas If the callback finds an existing version of DCLTABLES EXE in the working directory it assumes the image was created by a previous call that has already provided for transfer of the image when the installation is completed In this way multiple updates can be made to the DCLTABLES E XE image during the installation without requiring redundant transfers of the image to the system directory Use the following command line f
11. VMI SUCCESS is returned if the callback executed without error VMI FAILURE is returned if errors occurred Begin each invocation of a callback with the symbol VMISCALLBACK followed by the callback s name as the first parameter Separate all parameters with spaces The following is an example of a command line for invoking a VMSINSTAL callback VMISCALLBACK FIND_FILE CHECKTRAN_ VMISROOT SYSEXE FED EXE S CHECKTRAN_V1FED 5 1 VMSINSTAL Callbacks See Example 3 1 and Example B 1 for KITINSTAL command procedures that demonstrate the use of callbacks Note Currently VMSINSTAL callbacks related to Digital s Distributed Software License Architecture DDSLA and License Management F acility LMF are not supported for third party non Digital developers of layered products 5 1 ADD_IDENTIFIER Callback The ADD_IDENTIFIER callback adds an identifer to the rights database You can use this callback with the SET ACL DEVICE SET ACL DIRECTORY and SET ACL FILE callbacks to allow access to devices and files See Section 5 28 1 for information on the SET ACL callback options See the OpenVMS System Management Utilities Reference Manual for more information about identifiers Use the following command line format to invoke the ADD_IDENTIFIER callback VMI CALLBACK ADD_IDENTIFIER id_name qualifiers Parameters on the command line indicate the following id_name Use this parameter P2 to specify the name of t
12. the product Section 5 16 describes how to use the MESSAGE callback to display a message Digital recommends using the CHECK_VMS VERSION callback instead of the VMI VMS VERSION symbol to test the version of the operating system This callback is useful when the developer knows that specific versions of OpenVMS will break the product Use the following command line format to invoke the CHECK_VMS_VERSION callback VMI CALLBACK CHECK_VMS_VERSION symbol minimum_version option maximum_version Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that VMSINSTAL defines as true 1 when the running version meets the criterion specified in P3 minimum_ version and P5 maximum_version When the running system does not meet the criteria VMSINSTAL defines this symbol as false 0 minimum_version Use this parameter P3 to specify the minimum OpenVMS version required to install the product Specify minimum version in the following format vv u m where vv indicates a version u indicates an update m indicates a maintenance release For example 5 2 1 would indicate that the version is 5 the update is 2 and the maintenance level is 1 To specify Version 5 2 you would enter 5 2 This parameter continues to accept the old format vvu for example you can specify 052 to indicate Version 5 2 however to specify a particular maintenance release you must use the new format
13. 3 Invoking VMSINSTAL Invoke VMSINSTAL using the following command line format SYS UPDATE VMSINSTAL product_list source options option list alternate_dir qualifiers 1 6 product_list Use this parameter P1 to enter a list of the products to be installed Separate multiple entries in P1 with commas If you use a wildcard character as the product_list parameter all versions and updates of all products from the distribution source are installed in alphabetical order If you do not specify a product using this parameter VMSINSTAL prompts for it This parameter is required source Use this parameter P2 to identify the source of the software product as one of the following A device that holds the distribution medium e A storage directory where the product save set has been transferred from the distribution media for later installation this occurs when you specify the get save set option described in Section 1 4 1 e A disk directory on another node if DE Cnet software is installed on both nodes If you do not specify the source VMSINSTAL prompts for it You can use a logical name to specify the source This parameter is required options Use this parameter P3 to enter the keyword OPTIONS when VMSINSTAL options are to be listed in the next parameter P4 The installation aborts if P4 contains an option list and the options keyword is omitted Using this keyword minimizes that possibility Introduc
14. AXP systems the SET PRODUCT_NAME option defines the global symbol VMI PRODUCT_NAME as the value of the passed parameter Use this value in the name column of the history file Use the following command line format to invoke the SET PRODUCT_NAME option SET PRODUCT_NAME string 5 33 VMSINSTAL Callbacks 5 28 SET Callback Parameters on the command line indicate the following string Use this parameter P3 to specify a string that represents the value you want to assign to VMI PRODUCT_ NAME This string can be one word or several words If the string is more than one word or if the string is case sensitive this parameter must be passed to VMISPRODUCT_ NAME as a quoted string Following are examples of command lines for the SET PRODUCT NAME option VMISCALLBACK SET PRODUCT_NAME RDB VMISCALLBACK SET PRODUCT_NAME OpenVMS AXP Rdb This option always returns VMI SUCCESS 5 28 7 SET PURGE Option 5 34 The SET PURGE option specifies whether files replaced during the installation are to be purged Files accessed by callbacks that specify the KEEP K option are not purged by the installation procedure regardless of whether the SET PURGE option was selected If you do not use the SET PURGE option VMSINSTAL purges replacement files Use the following command line format to invoke the SET PURGE option VMI CALLBACK SET PURGE keyword help Parameters on the command line indicate the following keyword Use this paramet
15. If the library type is RSX the target system must have VAX 11 RSX installed If a OpenVMS library is being updated enter one of the following HELP e MACRO e OBJ ECT SHARE TEXT You must make an entry in this parameter qualifiers Use this parameter P5 to list qualifiers for the LIBRARY command Enclose the list in quotation marks See the OpenVMS Command Definition Librarian and Message Utilities Manual for more information on the Librarian utility source file Where applicable use this parameter P6 to enter the full specification for the source file being used to update the library You can use wildcards If you need to save disk space you can delete this file when the callback finishes Following is an example of the command line for the UPDATE_LIBRARY callback VMISCALLBACK UPDATE_LIBRARY VAXFMS STARLET VMISROOT SYSLIB STARLET OLB OBJECT DELETE FDV FDVMSG FDVDAT FDVERR FDVTIO FDVXFR HLL HLLDFN The UPDATE_LIBRARY callback returns VMI SUCCESS If the file is not found it returns VMI FAILURE 5 43 A Symbols and Logical Names This appendix lists and briefly describes the symbols and logical names used by VMSINSTAL VMI VMI ALTERNATE_ROOT VMI ARCHITECTURE VMI AUTO FILE VMI AUTO_OPTION VMI BACKUP_OPENIN VMI BOOTING VMI CALLBACK VMI CALL_FILE VMI CLD VMI COM VMI COMMAND P1 VMI COMMON_ROOT VMI CONSOL E VMI DEBUG VMI DEFER_FILE VMI DEMON VM
16. JULIE EXE VMISROOT SYSEXE KO ECO list Where applicable use this parameter P6 to enter a comma separated list of ECOs that you want applied to the new image file The ECO numbers are maintained in the image header and can be examined using the DCL command ANALY ZE IMAGE See the OpenVMS DCL Dictionary for more information on the ANALY ZE IMAGE command The callback ignores this parameter if P5 does not specify the E option Following are two examples of the command line for the PROVIDE_IMAGE callback VMISCALLBACK PROVIDE_IMAGE TEST_ TEST EXE VMISROOT SYSMSG KE 1 2 3 This example includes options K and E and ECOs 1 2 and 3 VMISCALLBACK PROVIDE_IMAGE INPUT DAT T This example shows how to use the T option to include an input file This callback returns VMI SUCCESS unless the callback cannot find the source image file or a subordinate callback fails VMSINSTAL Callbacks 5 24 RENAME_FILE Callback 5 24 RENAME_FILE Callback The RENAME FILE callback changes the file name and type for all versions of the designated file You can use this callback to rename a file within a directory or to relocate a file in another directory on the same device by changing its directory specification You cannot use the RENAME FILE callback to relocate a file from one device to another If the installation is in safety mode the name change is deferred until the installation progresses beyond safety mode Use the following co
17. ON WARNING THEN EXIT STATUS l Determine course of action l IF Pl EQS VMIS_INSTALL THEN GOTO CHECKTRAN_INSTALL IF P1 EQS VMIS_POSTINSTALL THEN GOTO CHECKTRAN_POSTINSTALL IF P1 EQS VMIS_IVP THEN GOTO CHECKTRAN_IVP EXIT VMIS_UNSUPPORTED l Set the product name AXP Systems Only l VMI CALLBACK SET PRODUCT_NAME CHECKTRAN nstall the product CHECKTRAN_INSTALL or 1 0 for OpenVMS AXP For VAX systems only PRODUCTSVERSION 5 0 a l Check that OpenVMS version is 5 0 or later for OpenVMS VAX For AXP systems only l l l l l l l l l l PRODUCT VERSION 1 0 VMISCALLBACK CHECK_VMS_VERSION CHECKTRANSVERSION PRODUCTSVERSION IF CHECKTRANSVERSION THEN GOTO V_OK Ur Ur UY UY UY UY UY UY UY UY U7 MMMM UY UY UY MM LU Ur UY UY UY UY LU UY UY UY U7 MMMM MM continued on next page 3 7 KITINSTAL Command Procedure 3 4 Basic KITINSTAL Command Procedure 3 8 Example 3 1 Cont Basic KITINSTAL COM 5 5 5 5 5 Ur UY UY WA UY UY LAMM UY UY UY UY UY MMMM UY UY UY UY UY UY UN UY MMMM M Ur Ur UY 47 UY Ur Ur Ur int in Ur nt irr UY HMM MD 1 Indicate wrong version and exit 1 WRONG_VERSION VMISCALLBACK MESSAGE E VERSION This kit must be installed on an existing OpenVMS product version system EXIT VMIS_FAILURE V_OK Check for disk space exit if not enough 1 VMISCALLBACK CHECK_NET_UTILIZATION CHECKTRAN_SPACE 1000 500 600 IF NOT CHEC
18. Y when you are ready to proceed The device is then mounted and allocated The following message appears Save set A must contain the KITINSTAL COM procedure If you specified a data file for SPKITBLD to use proceed to step 7 Otherwise the following prompt appears Which files Respond to this prompt by specifying the files to be included in the save set and press Return The following message appears Resetting protection on all files to S RWED O RWED G RWED and W RE After the save set has been created the following prompt appears Is there another save set to create Y N N If another save set is to be created specify Y Then specify Y or N in response to the following prompt Does it need to start on a new volume Y N N If no other save set is to be created press Return After all save sets have been created the following message is returned to indicate a successful product kit build Kit Build Completed Successfully 1 2 VMSINSTAL Functional Overview The following list provides an overview of the functions performed by VMSINSTAL when it installs a layered product 1 VMSINSTAL initializes the software environment defines logical names and symbols makes validity checks and gives you an opportunity to back up your current system disk All user defined global and local symbols are deleted at this point VMSINSTAL then prompts for the distribution device if you do not include it in the comma
19. assigned default values by another callback If the installation is in safety mode this action is deferred until the installation has progressed beyond safety mode When the callback looks for the specified file it looks first in the installation working directory It then goes to the system area to ensure the proper protection of the file regardless of the safety mode Use the following command line format to invoke the SECURE_FILE callback VMI CALLBACK SECURE FILE filespec owner protection Parameters on the command line indicate the following filespec Use this parameter P2 to enter the specification of the file being assigned special security owner Where applicable use this parameter P3 to assign the file a specific owner UIC value using the standard group member format 5 29 VMSINSTAL Callbacks 5 27 SECURE_FILE Callback protection Where applicable use this parameter P4 to assign the file a specific protection code Use the standard format but omit the parentheses Following is an example of the command line for the SECURE_FILE callback VMISCALLBACK SECURE_FILE VMISROOT CHECKTRAN DAT 111 333 S RED O RWED G W This callback returns VMI SUCCESS unless it cannot find the file 5 28 SET Callback Use the SET callback to specify installation conditions by supplying the appropriate SET option in parameter 2 Currently VMSINSTAL provides the following SET options SET ACL SET ASK_CASE SET FIL
20. be stored in SYS UPDATE To enable another product to invoke the INCREMENT callback it must include the following line in its installation procedure VMISCALLBACK PRODUCT NEWAIDINSTALL INCREMENT PRODSINC _ COUNTFILE DAT VMISROOT SYSUPD 2 In this example NEWAIDINSTALL COM parses the following parameters e P1 INCREMENT e P2 PROD INC e P3 COUNTFILE DAT e P4 VMI ROOT SYSUPD e P5 2 e P6 e P7 e Pg8 The parameter order for product specific callbacks should follow those of standard callbacks Use a standard callback that is similar to the one you are designing as a model for parameter order The following conventions must be adhered to when designing a product specific callback procedure e The procedure must establish a Ctrl Y handler that eventually invokes the CONTROL _Y callback e The procedure must establish an error handler that eventually exits with the status that caused the handler to be invoked Warnings are not trapped because they are routinely returned from other callbacks e The first parameter to the procedure is the callback request code Use a GOTO statement with this parameter to branch to the appropriate callback C 1 Product Specific Callback Conventions e The code to implement a callback must follow all of the conventions outlined elsewhere in this manual In particular files must be referenced with standard callbacks The FIND_FILE callback can be used to d
21. but no default value is specified e R Rings the bell before displaying the prompt e S The response can be any character string this is the default response data type e U Returns input from the installer in uppercase e Z Allows the installer to respond with Ctrl Z The return value is the two character string Z help Use this parameter P6 to specify help text that may be used in conjunction with the prompt Either you can enter actual help text or you can enter a call toa command procedure typically KITINSTAL to provide the text by way of a help callback If you enter a call to a command procedure you must also specify the name of the help callback that is found in P1 request code of the call as follows VMISKWD KITINSTAL HELP_WHATEVER There is no conflict with VMSINSTAL request codes because the request code is not prefixed with the string VMI To illustrate the use of the ASK callback following is an example of a typical command line that includes all six parameters PL P2 P3 P4 P5 P6 VA VMISCALLBACK ASK TST_DIGIT Enter a number 3 I VMISKWD KITINSTAL help_type In response to the preceding command line the callback displays the following prompt Enter a number 3 If the installer enters the following help message appears Type a digit The global symbol TST_DIGIT P2 is assigned the value of the entered integer If the installer presses the Return key TST DIGIT is assigned the
22. create system directories system specific directories common directories user directories for your product System directories are created in the common area and the specific area System specific directories are created in the system root of the installing system not the common area Common directories are created in the common area only The prefix SYS is reserved and should not be used to specify a product directory The way you invoke the callback depends on the type of directory you are creating 5 11 VMSINSTAL Callbacks 5 10 CREATE_DIRECTORY Callback 5 10 1 Creating a System Directory To create a system directory use the following command line format VMI CALLBACK CREATE_DIRECTORY SYSTEM name qualifiers Parameters on the command line indicate the following SYSTEM When you enter the keyword SYSTEM in this parameter P2 the product directory is created under the system root directory and the common directory name Use this parameter to specify the name of the system directory The callback recognizes the keyword SYSTEM and makes it a rooted directory Therefore do not specify the system device designation and do not include the brackets usually used in directory name specifications qualifiers Use this parameter P4 to specify one or more of the CREATE DIRECTORY command qualifiers OWNER_UIC PROTECTION VVERSION_LIMIT The entire parameter must be specified as a character string that is within quotati
23. follows Chapter 1 presents an overview of the VMSINSTAL command procedure including the command line for invoking it and a description of the available installation options Chapter 2 discusses the various guidelines and conventions used to design installation procedures that are compatible with VMSINSTAL Chapter 3 describes the basic steps of the installation procedure Because KITINSTAL has a generic structure the specifics might differ slightly from one product to another Chapter 4 describes the eleven functional steps and the two special steps of the VMSINSTAL logical sequence Chapter 5 describes the VMSINSTAL callbacks which are specialized subroutines that execute the various installation tasks Appendix A lists and briefly describes the symbols and logical names used by VMSINSTAL Appendix B provides an example of a KITINSTAL COM installation procedure for an actual Digital product This command procedure serves as a sample for writing product specific command procedures Appendix C provides an example of a product specific callback Installation designers can develop their own product specific callbacks as long as they follow the explicit guidelines Appendix D provides a template for using VMI VMS_VERSION a symbolic value used to verify that the product being installed is compatible with the target system Appendix E explains how to register a product Associated Documents For information on specific system
24. installation and upgrade procedures see the installation and operations guide for your processor For information about writing OpenVMS command procedures see the OpenVMS User s Manual vii Conventions viii In this manual every use of OpenVMS AXP means the OpenVMS AXP operating system every use of OpenVMS VAX means the OpenVMS VAX operating system and every use of OpenVMS means both the OpenVMS AXP operating system and the OpenVMS VAX operating system The following conventions are used to identify information specific to OpenVMS AXP or to OpenVMS VAX The AXP icon denotes the beginning of information specific to OpenVMS AXP specific to OpenVMS VAX The diamond symbol denotes the end of a section of information specific to OpenVMS AXP or to OpenVMS VAX AXP ZD The VAX icon denotes the beginning of information The following conventions are also used in this manual Ctrl x A sequence such as Ctrl x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button PF1x A sequence such as PF 1 x indicates that you must first press and release the key labeled PF1 then press and release another key or a pointing device button GOLD x A sequence such as GOLD x indicates that you must first press and release the key defined GOLD then press and release another key GOLD key sequences can also have a slash dash or underscore _ as a delimiter in EVE commands
25. is optional VMSINSTAL only prompts the installer for options when both of the following conditions are true e Options are not specified on the command line e VMSINSTAL must also prompt for either the product or source device parameters 1 4 Choosing VMSINSTAL Options The VMSINSTAL command procedure permits the use of twelve options six that apply to the installer and six that are used for testing the installation procedures during development and acceptance testing When invoking VMSINSTAL specify options by entering the appropriate letters in the option list parameter of the command line 1 4 1 Installer s Options 1 8 Following is a description of the six VMSINSTAL installer s options These options can also be used when testing an installation procedure A The auto answer option makes it easier to reinstall a product by providing responses to VMSINSTAL questions and prompts during the reinstallation The auto answer option is used most often for reinstalling products after a system is upgraded If you specify the auto answer option when initially installing the product VMSINSTAL creates an answer file in the SYS UPDATE directory The name of the answer file is in the following format product_name ANS where product_name is a file name that reflects the product list parameter in the call to VMSINSTAL The answer file records responses to questions and prompts from VMSINSTAL during the installation When you su
26. logical patch_file image options Parameters on the command line indicate the following logical Use this parameter P2 to assign a process logical name to the image being patched Use this logical name in all subsequent references to the file patch_file Use this parameter P3 to enter a partial file specification of the patch file its name and type The patch file must include only the commands needed to patch the image Since the device and directory are not included in the file specification the file must reside in the kit s working directory If disk space is critical the file can be deleted upon completion of the callback image Where applicable use this parameter P4 to specify the image being patched If the image is specified as a comment in the patch file enter a null string in this parameter 5 19 VMSINSTAL Callbacks 5 17 PATCH_IMAGE Callback VAX Only options Where applicable use this parameter P5 to specify options for patching and subsequent disposition of the image Select the options from the following list of characters If you specify multiple options do not use spaces between them e Use this option to move a shareable image s symbol table to the system s shareable image library SYS LIBRARY IMAGELIB OLB when the patch is completed e J Use this option to create a journal file of the patch or update an existing journal file in the same directory as the image e K Use this opti
27. save set does not include the KITINSTAL command procedure the installation is aborted The program branches to step 11 for general housekeeping before looking for the next product to be installed Step 8 begins by updating the marker file to indicate that the installation of the current product has begun and to establish the appropriate safety level Then VMSINSTAL invokes KITINSTAL to install the product If the installation succeeds the program proceeds to step 9 If not an appropriate message is displayed The program branches to step 11 for general housekeeping before looking for the next product in the kit Step 9 is used to execute any callbacks that were deferred if the installation was done in safety mode VMSINSTAL then informs the installer that the deferred files are being moved to their target directories The marker file is updated to indicate that the deferred callbacks are being executed Next safety mode terminates and the deferred callback file is opened for reading deferred callback records If any deferred callback fails the installation is aborted an appropriate message is displayed and the program prepares to install the next product If the deferred callbacks execute properly the deferred callback file is closed and the marker file is updated to indicate that the product installation is essentially complete If the product installation indicated a postinstall phase then KITINSTAL COM is invoked again so the
28. specify a system shutdown is not required or cancelled symbol Use this parameter P4 to specify a global symbol that indicates whether the installer is allowing the system to shut down VMSINSTAL defines this symbol as a Boolean true or false installation action Use this parameter P5 to specify the action the installation procedure will take if the shutdown is not allowed This parameter is only required with the keyword option ASK EXIT Usethis keyword to indicate that the product installation procedure will exit immediately thereby not placing the product files on the system e CONTINUE Use this keyword to indicate that the product installation procedure will continue installing the product on the system but requires the system to be rebooted before the product is completely installed and available for use The SET SHUTDOWN option always returns VMI SUCCESS 5 28 12 SET STARTUP Option The SET STARTUP option specifies a product specific startup command procedure VMSINSTAL executes the product specific startup command procedure immediately following the installation and just prior to running the IVP where applicable Before invoking this option use the PROVIDE_FILE callback to store the product specific startup command procedure in the SYS STARTUP directory Use the following command line format to invoke the SET STARTUP option VMI CALLBACK SET STARTUP filename parameters The parameters on the command line indi
29. the IVP phase Naming conventions All global symbols and logical names created by VMSINSTAL have the prefix VMI Your product global symbols and logical names must use a prefix consisting of the product name followed by an underscore For example each global symbol and logical name created by the product CHECKTRAN requires the CHECKTRAN_ prefix Local symbols can take any name Logical references Your installation procedure must use the following logical references VMI KWD The logical name VMSINSTAL creates for the kit working directory Any reference your product makes to the kit working directory must use this logical name VMI ROOT The logical name VMSINSTAL creates for the target system s root directory Again all references to this directory must use the logical name assigned by VMSINSTAL not the usual system logical names For example your installation procedure must refer to the system library directory using VMI ROOT SYSLIB rather than SYS LIBRARY VMI SPECIFIC The logical name VMSINSTAL creates to reference the target system s system specific top level directory VMI SPECIFIC points to the system specific top level system directory whereas VMI ROOT points to the common top level system directory Your installation procedure must use this reference instead of using SYS SPECIFIC 3 1 KITINSTAL Command Procedure 3 1 Guidelines for Writing a KITINSTAL Command Procedure Subprocedures You can include product s
30. the target device the device that will hold the images and command files associated with the product VMSINSTAL Callbacks 5 4 CHECK_NET_UTILIZATION Callback If you choose the highest safety level for your installation the disk must have sufficient space to accommodate the highest number of blocks used at one time peak utilization See Section 5 28 9 for more information on the SET SAFETY option Use the following command line format to invoke the CHECK_NET_ UTILIZATION callback VMI CALLBACK CHECK_NET_UTILIZATION symbol blocks trg blocks awd blocks Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that the callback uses to indicate whether the disk or disks have sufficient net free space to install your product The callback returns the value true 1 for this symbol if there are sufficient net free blocks available otherwise its value is false 0 blocks Use this parameter P3 to specify the number of net free blocks required for your product The figure should be equal to the total number of blocks required to perform the installation including the temporary working directory on the target device trg blocks Use this parameter P4 to specify the number of free blocks that must be available on the target device VMI ROOT in order to accommodate the completed installation This number does not include the number of blocks required for the temporary w
31. type are required because the callback assumes that the file resides in the installation working directory Do not specify a version number If you specify the T option in P5 enter the name of the input file in P3 destination Use this parameter P4 to specify the disk and directory where the new image file is to reside You must specify the null string for this parameter if you also specify the T option options Where applicable use this parameter P5 to specify options using the appropriate letters from the following list If you list more than one option do not use spaces between the selected letters e C Use this option if the file must reside in more than one location When you specify option C the file is copied from VMI KWD to its destination A copy of the file remains in VMI KWD e E Outstanding ECOs listed in the next parameter P6 are to be patched dynamically into the new image file The callback builds a temporary file containing the patch commands in the following form SET ECO nnn UPDATE SET ECO nnn UPDATE It extracts the variable values nnn from the ECO list in P6 Then the completed file is used as the input to the Patch utility which sets the ECO numbers in the specified image Only ECO numbers are set You must use the PATCH callback to apply instruction or data patches e Use this option to move a shareable image s symbol table to the system s shareable image library SYS LIBRARY IMAGELIB
32. 2 2 Creating magnetic tape kit 2 3 Creating TU58 cartridge kit 2 3 D DCL command abbreviation restriction 2 3 Debugging tools 1 11 Defaults KITINSTAL 3 2 Index 1 Defer file 1 13 DELETE _FILE callback 5 14 Device number restriction 5 1 Directory creating using callbacks 3 5 restrictions on creating 3 5 Diskette kit 2 2 specifying BACKUP qualifiers 2 2 Disk space utilization 1 11 1 13 5 5 5 35 E Internationalization generating VMSINSTAL messages for 2 5 IVP installation verification procedure definition 1 2 IVP Installation Verification Procedure 3 2 exit requirements 3 3 guidelines for 2 4 K Error handling KITINSTAL 2 3 F Facility code 2 1 registration 2 1 Failures 1 13 4 8 File log option L 1 9 File protection 2 2 Files marker 1 13 4 5 using callbacks to access 3 3 using callbacks to delete 3 5 using callbacks to move 3 4 using callbacks to update 3 4 FIND_FILE callback 5 15 G Kit debug option K 1 11 KITINSTAL procedure compatibility mode 2 4 defaults 3 2 design specifications 3 6 error handling requirement 2 3 example 3 7 B 1 guidelines and conventions 3 1 IVP phase 3 2 installation for 3 1 location in kit 4 2 logical references 3 1 name prefixes 2 3 request codes 3 6 requirements of 3 6 Kits diskette 2 2 magnetic tape 2 3 TU58 cartridge 2 3 L Get save set option G 1 7 1 9 4 10 GET_IMAGE_ID call
33. 3 5 logical name use 5 1 Root specifying alternate 1 7 RSP option See Restore save set and pause option RSP RUN_IMAGE callback 5 28 S PATCH_IMAGE callback 5 19 PRINT_FILE callback 5 20 Procedure checking products installed 1 12 PRODUCT callback 5 21 Product file protection code 2 2 Product identification 2 1 Product installation file 1 12 Product kit 1 2 2 1 Product name registration 2 1 Product referencing options 2 4 Product save set identification 2 1 Product specific callback 3 1 C 1 Prompting for input 2 5 5 2 Protection code for product files 2 2 PROVIDE_DCL_COMMAND callback 5 21 PROVIDE_DCL_HELP callback 5 22 PROVIDE_FILE callback 5 23 PROVIDE_IMAGE callback 5 24 Q QA Quality Assurance mode option Q 1 11 R Release notes guidelines for including 2 6 in Help library 2 6 Safety mode 1 13 Save set copying to disk 1 9 4 10 identification 1 2 naming 2 1 restoring 1 11 4 6 sequence identifier 2 2 SECURE_FILE callback 5 29 Sequence identifier See Save set SET ACL option 5 2 5 30 SET ASK_CASE option 5 31 SET callback 5 30 to 5 37 SET command restriction 3 2 SET IVP option 5 32 SET POSTINSTALL option 5 33 SET PRODUCT_NAME option 5 33 SET PURGE option 5 34 SET REBOOT option 5 35 SET SAFETY option 5 35 SET SHUTDOWN option 5 36 SET STARTUP option 5 37 SET_FILE option 5 31 SET_SEMANTICS option 5 36 SHOW command restriction 3 2 SPKITBL
34. 4 2 4 2 1 Step Laynee ae aa D a AA ean Halen A apace sea ah Ras 4 2 4 2 2 STEP Li A Sk Mace Ba gle Rane Gok Mas aad Rea 4 3 4 2 3 Step 3 prre a aii eee aie dah ahaa a Eaa aa dasa atkeeeg Sadie age 4 4 4 2 4 SEPA alat E ea Ae eye iad See ie ides 4 4 4 2 5 SO NS cide eee ee 4 5 4 2 6 NA 4 5 4 2 7 SE Psi Saya EE canes tana Gri aw whee ecw Bane na eee E epee Bae earn 4 6 4 2 8 AN 4 6 4 2 9 Step RR 4 6 4 2 10 Step A Shey aaea Sits Siti ow A ee Sc ce Sheesh ee a ee 4 7 4 2 11 Step ii aie bee hace Mine ba tle bee AA tia 4 7 4 2 12 All DONG tata AAA 4 7 4 3 Special Steps 2 6 of cessed aa Del dr ash A pec a Mattel a a A ee Se el ale 4 8 4 3 1 Step Zi E eee eek AN eid Eee OES 4 8 4 3 2 Step TB tin oh belied aes aia ewe eens dared eek ee ee 4 10 5 VMSINSTAL Callbacks 5 1 ADD _IDENTIFIER Callback 0 0 0 0 cece 5 2 5 2 ASK Callback ios be eee ebb ee Oe Oe ea oe ee ee ae 5 2 5 3 CHECK NETWORK Callback 0 0 0 0 0 5 5 5 4 CHECK_NET_ UTILIZATION Callback 0 0 00 0000 0 00s 5 5 5 5 CHECK PRODUCT VERSION Callback o o oooooooooo 5 7 5 6 CHECK_VMS VERSION Callback 0 0 0 cee 5 8 5 7 COMPARE_IMAGE Callback nunnana uaaa 5 9 5 8 CONTROL_Y Callback ee 5 10 5 9 CREATE ACCOUNT Callback 2 cee 5 11 5 10 CREATE DIRECTORY Callback 0 0 0 ccs 5 11 5 10 1 Creating a System Directory 5 12 5 10 2 Creating a System Specific Directory 0000000 5 12 5 10 3 Creating a Common Directo
35. 5 VMISCALLBACK PROVIDE_FILE FUD2A DECRAMSIVP COM VMISROOT SYSTEST O IF DECRAM_ARCH EQ 1 THEN GOTO DECRAM_INST_AXP VMISCALLBACK PROVIDE_IMAGE FUD2 MDDRIVER EXE VMISROOT SYSSLDR O GOTO INST_SUCCESS DECRAM_INST_AXP VMISCALLBACK PROVIDE_IMAGE FUD2 SYSSMDDRIVER EXE VMISROOT SYSSLDR O GOTO INST_SUCCESS 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 INST_SUCCESS S 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 ng a w o lt DE_IMAGE FUD1 DECRAMSSIZE EXE VMISROOT SYSEXE O Successful exit 1 EXIT VMI _SUCCESS l DECRAM_NO_INSTALL EXIT VMI _FAILURE ERR_EXIT S STATUS EXIT S l CONTROL_Y VMISCALLBACK CONTROL_Y DECRAM_RUN_IVP sysStest decramS ivp if status then exit vmi _success exit vmi _failure C Product Specific Callback Conventions A callback is a recursive invocation of a specialized subroutine in VMSINSTAL Example C 1 in this appendix provides a product specific callback procedure used with the VMSINSTAL PRODUCT callback See Section 5 19 for more information about the PRODUCT callback Assume that NEWAID is the hypothetical base product for a product group NEWAID must provide a command procedure containing a callback INCREMENT which increments quantities passed to it The command procedure should be named NEWAIDINSTALL COM to reflect the product name followed by the word INSTALL The command procedure should
36. 5 33 5 28 7 SET PURGE OptiON ary traca ds A 5 34 5 28 8 SET REBOOT Option vairi ia iaa i a cece ee ee 5 35 5 28 9 SET SAFETY Optom i Ai Sie lose e Sa ak ok A AR aude Ni 5 35 5 28 10 SET_SEMANTICS Option AXP Only 0 000 eee eee 5 36 5 28 11 SET SHUTDOWN Option raice aspe tia a ee 5 36 5 28 12 SET STARTUP Optima a ating aged Seats Ras E as 5 37 5 29 SUMSLP_TEXT Callback o o oocoooooorcrrrnra ee 5 38 5 30 TELL QA Callback caos aro a dai a 5 40 5 31 UNWIND Callback oooooocccroororarr ee 5 40 5 32 UPDATE_ACCOUNT Callback 0 eee ee 5 40 5 33 UPDATE_FILE Callback a oi ai en ea ea a e a ee 5 41 5 34 UPDATE_IDENTIFIER Callback ooooooooorrorrrnn o 5 42 5 35 UPDATE_LIBRARY Callback mis e enai a a ea a a a e aa e 5 43 A Symbols and Logical Names B Sample OpenVMS Installation Procedure C Product Specific Callback Conventions D How to Use the VMISVMS_VERSION Symbol E Product Registration Index Examples 3 1 Basic KITINSTAL COM 0 ccc cee eens 3 7 B 1 Sample DIGITAL OpenVMS KITINSTAL COM 00005 B 2 C 1 Product Specific Callback Procedure 0 0c cece eee eee C 2 D 1 Template for Using the VMI VMS VERSION Symbol D 1 Preface Intended Audience This manual is intended for developers who design installation procedures for optional products that layer on the OpenVMS operating system Document Structure Information in this manual is organized as
37. ASK_IVP 51 TYPE SYSSINPUT A DECram Driver is already installed on the system It is recommended that you reboot your system rather than doing a SYSGEN RELOAD to cause the new DECram Driver software to be invoked 5 DECRAM_IVP 0 GOTO DECRAM_NO_ASK_IVP SDECRAM_ASK_IVP Dual SDECRAM_NO_ASK_IVP 5 DECRAM_DOCS Here s where we move in the documentation VMISCALIBACK RESTORE_SAVESET B VMISCALLBACK PROVIDE_FILE FUD3 DECRAM_INSTAL_GUIDE PS VMISROOT SYSHLP VMISCALLBACK PROVIDE_FILE FUD4 DECRAM_INSTAL_GUIDE TXT VMISROOT SYSHLP VMISCALLBACK PROVIDE_FILE FUD5 DECRAM_DRIVER_MANUAL PS VMISROOT SYSHLP VMISCALLBACK PROVIDE_FILE FUD6 DECRAM_DRIVER_MANUAL TXT VMISROOT SYSHLP Here s where we move in the examples VMISCALLBACK RESTORE_SAVESET C Don t do EXAMPLES for File Test VMISCALLBACK PROVIDE_F UD7 RAMDISKS STARTUP COM 5 VMISROOT SYSHLP EXAMPLES VMISCALLBACK PROVIDE_F UD8 RAMDISKSNODE DAT VMISROOT SYSHLP EXAMPLES VMI CALLBACK PROVIDE_F UD8 SCRATCHRAM STARTUP COM VMISROOT SYSHLP EXAMPLES VMI CALLBACK PROVIDE_F UD8 SCRATCHRAMSNODE DAT F aj al O al O al DHA WE J VMISROOT SYSHLP EXAMPLES VMI CALLBACK PROVIDE_F UD9 DECRAMSCONFIG COM VMISROOT SYSHLP EXAMPLES O al ORMOROROROE o Oo I H WE
38. BVMS for which a data file exists SYSSUPDATE INSTALLED_PRDS R This procedure lists information for all versions of products whose name begins with the letter R 1 12 Introduction 1 7 List Installed Products Procedure AXP Only The following is a sample listing SYSSUPDATE INSTALLED_PRDS RDBVMS Node AZSUN Installed products 2 APR 1992 13 13 Product AXP RDB VMS Mnemonic RDBVMS Version 3 0 Installed 12 SEP 1992 Installed by SOMMER on node AZSUN 1 8 Safety Mode On both AXP and VAX systems VMSINSTAL is designed to minimize the risk of installation failure by executing the installation in two phases A safety mode feature allows the installer to defer critical operations until the second phase of the installation During the initial installation phase operations that may severely impact your system if a failure occurs are deferred until the second phase These critical operations include moving new files into the system directories updating existing files and patching system images Note however that system libraries are updated immediately because they may be required by the installation process itself The primary tool for deferring critical operations is called the defer file This is a command file VMIDEFER COM that VMSINSTAL creates in the work directory to record deferred commands If the installation is in safety mode VMSINSTAL checks to see whether or not an installation command is critical
39. CKTRAN_IVP l run the ivp l VMISKWD CHECKTRAN_IVP COM ivp completed indicate results l EXIT STATUS Ur UY Ur Ur Ur Ur Mt UY U7 MAMAN MM U7 LU UY UY UY UY UU UY UN Ur MMM UF See Appendix B for a KITINSTAL command procedure for an actual Digital product 3 9 4 VMSINSTAL Functional Description VMSINSTAL is structured in a sequence of 11 functional steps These steps are labeled in the command procedure Two additional steps apply only to special installation conditions Step 12 attempts to recover from system failures that occur during the installation and Step 13 implements the GET save set option This chapter provides a functional overview of VMSINSTAL and a summary of the 13 steps 4 1 Overview When you invoke VMSINSTAL it announces itself gives the time and date and provides instructions for getting help if you need it during the installation It also does the following initial tasks all of which are transparent to the installer e Deletes all user DCL symbols e Assigns symbols and defines logical names needed to do the installation These are all prefixed by VMI e Verifies that you are running the installation from the SYSTEM account and that you have sufficient privileges and quotas e Verifies that there are no other users on the system e Checks the validity of parameters that you include in the calling command If any of the checks fail VMSINSTAL displays an appropriate message If VM
40. D command procedure 1 2 invoking 1 4 Statistics option S 1 11 4 5 Statistics subprocess 4 5 Subroutines See also Callbacks ALL_DONE 4 7 limitations 2 3 naming conventions 2 3 Index 3 SUMSLP_TEXT callback 5 38 Symbols definitions A 1 naming conventions 2 3 SYS HELP 2 6 SYS LIBRARY restriction 3 1 SY S SPECIFIC restriction 3 1 System failure recovery 4 8 Recovery 1 13 T TELL_QA callback 5 40 TU58 cartridge kit specifying BACKUP qualifiers 2 3 U UNWIND callback 5 40 UPDATE_ACCOUNT callback 5 40 UPDATE FILE callback 5 41 UPDATE_IDENTIFIER callback 5 42 UPDATE_LIBRARY callback 3 5 5 43 V Verification disabling 1 11 using SET commands 3 2 VMI 4 1 VMI ALTERNATE_ROOT 4 5 VMI BOOTING 4 2 4 8 VMI CALLBACK 3 1 4 7 for invoking callbacks 5 1 VMI COMMON_ROOT 4 5 VMI DEFER_FILE 1 13 VMI FREE_BLOCKS 4 5 VMI KWD 3 1 5 1 VMI KWD_FREE_BLOCKS 4 5 VMI LIST 4 4 VMI MARKER FILE 1 13 VMI PLACE 4 4 VMI prefix 2 3 VMI PRODUCT 4 5 VMI ROOT 3 1 5 1 VMI SAVED_DIR 4 8 VMI SAVED_MSG 4 8 VMI SAVED_PRIVS 4 8 VMI SAVED_PROT 4 8 VMI SAVED_UIC 4 8 VMI SPECIFIC 3 1 4 5 VMI TERMINAL FILE 4 2 VMI VERSION 4 2 Index 4 VMI VMS VERSION 4 2 guidelines for using D 1 VMI FAILURE status 5 1 VMI IVP request code 3 3 VMI SUCCESS status 5 1 VMIDEFER COM 1 13 VMIMARKERpid DAT 1 13 VMSINSTAL command procedure alternate root 1 10 answer file 1 8 fu
41. DENTIFIER 5 2 ASK 5 2 CHECK_NETWORK 5 5 CHECK_NET_UTILIZATION 5 5 CHECK_PRODUCT_VERSION 5 7 CHECK_VMS_VERSION 5 8 COMPARE_IMAGE 5 9 CONTROL_Y 5 10 CREATE_ACCOUNT 5 11 CREATE_DIRECTORY 5 11 definition 1 1 DELETE_FILE 5 14 examples 3 7 FIND_FILE 5 15 for creating directories 3 5 for deleting files 3 5 for moving files 3 4 for updating files 3 4 for updating libraries 3 5 GET_IMAGE_ID 5 16 GET_PASSWORD 5 17 GET_SYSTEM_ PARAMETER 5 17 guidelines for 5 1 invoking 3 1 MESSAGE 5 18 parameter restrictions 5 1 PATCH_IMAGE 5 19 PRINT_FILE 5 20 PRODUCT 5 21 Index Callbacks cont d product specific 3 1 conventions for C 1 PROVIDE_DCL_COMMAND 5 21 PROVIDE_DCL_HELP 5 22 PROVIDE_FILE 5 23 PROVIDE_IMAGE 5 24 RENAME FILE 5 27 RESTORE_SAVESET 5 27 RUN_IMAGE 5 28 SECURE_FILE 5 29 SET 5 30 SET PRODUCT_NAME 5 33 SET SEMANTICS 5 36 specifying keywords for 5 1 SUMSLP_TEXT 5 38 TELL_QA 5 40 tracing 1 11 4 6 UNWIND 5 40 UPDATE_ACCOUNT 5 40 UPDATE_FILE 5 41 UPDATE_IDENTIFIER 5 42 UPDATE_LIBRARY 5 43 Callback trace option C 1 11 4 6 CHECK_NETWORK callback 5 5 CHECK_NET_UTILIZATION callback 5 5 CHECK_PRODUCT_VERSION callback 5 7 CHECK_VMS_VERSION callback 5 8 Command abbreviation restriction 2 3 COMPARE_IMAGE callback 5 9 Compatibility mode 2 4 CONTROL_Y callback 5 10 CREATE_ACCOUNT callback 5 11 CREATE_DIRECTORY callback 5 11 restrictions 3 5 Creating diskette kit
42. E AXP only SETIVP SET POSTINSTALL SET PRODUCT_NAME AXP only SET PURGE SET REBOOT SET SAFETY SET SEMANTICS AXP only SET SHUTDOWN SET STARTUP The options are invoked using SET as the first parameter and the appropriate option name for example IVP as the second parameter 5 28 1 SET ACL Option 5 30 The SET ACL option invokes the DCL command SET ACL to modify the access control list ACL of a device directory or file For information about modifying ACLs see the SET ACL command in the OpenVMS DCL Dictionary Use the following command line format to invoke the SET ACL option VMI CALLBACK SET ACL object_type aces object_name qualifiers Parameters on the command line indicate the following object_type Use this parameter P3 to specify the object for which you are modifying an ACL You can specify the following objects DEVICE To modify the ACL of a device e DIRECTORY To modify the ACL of a directory e FILE To modify the ACL of a file VMSINSTAL Callbacks 5 28 SET Callback aces Use this parameter P4 to list the ACEs that you are adding or modifying Endose the list with quotation marks object_name Use this parameter P5 to specify the name of the device directory or file for which you are modifying the ACL If you specify multiple file names or directory specifications separate them with commas You cannot specify multiple device names qualifiers Use this parameter
43. E symbols At the completion of the IVP KITINSTAL COM exits back to VMSINSTAL with VMI SUCCESS if the IVP is successful or with VMI FAILURE if the IVP was unsuccessful VMSINSTAL does not attempt to undo an installation if the IVP fails For specific guidelines for creating an IVP see Section 3 1 2 2 10 Prompting the Installer for Input When you design an installation procedure keep in mind that the procedure should prompt the installer for most input at the beginning of the installation This minimizes installer interaction when the installation is in progress 2 11 Internationalization of VMSINSTAL Messages AXP All messages generated by VMSINSTAL are defined as symbols in the file SY S MESSAGE VMSINSTAL_LANGUAGE COM Customers developing applications for non English speaking markets might want to change these symbol values to make installations understandable for the intended market On AXP systems you can specify a language file that is appropriate for your needs To specify a special language file define the logical VMSINSTAL _ LANGUAGE to point to that specific language file For example DEFINE VMSINSTAL LANGUAGE SYSSMESSAGE VMSINSTAL_LANGUAGE_GERMAN COM This file must be compatible with the provided VMSINSTAL_LANGUAGE file Message numbers must not be reassigned to different functions Only the text portion of the messages should be modified Guidelines and Conventions 2 11 Internationalization of VMSINSTAL Me
44. EN EXIT STATUS If some housekeeping is needed the error routine could be structured as follows ON WARNING THEN GOTO ERROR SERROR 5 S STATUS 5 5 Use this routine to do your housekeeping 5 to close any files that are open and 5 to handle errors that might occur during 5 housekeeping 5 EXIT S Guidelines and Conventions 2 6 Compatibility Mode VAX Only 2 6 Compatibility Mode VAX Only lt gt On VAX systems the KITINSTAL procedure must sometimes check for compatibility mode Compatibility mode was distributed as a separate layered product on VAX systems beginning with VMS Version 4 0 See the following section for more information about referring to other products in your KITINSTAL procedure To check for compatibility mode add the following line to your KITINSTAL COM file VMISCALLBACK FIND_FILE rsx vmi root sysexe rsx exe se If this file is present you can assume that compatibility mode can be used on the system 2 7 Referencing Other Products On AXP and VAX systems your installation procedure may need to refer to other products in one of the following ways e If the installation procedure must alter its logical flow because of the existence of another product but does not need to refer to that product you can use the FIND_FILE callback to verify the existence of the product See Section 5 12 for more information on this callback e If the procedure refers to another product
45. IC VMI SAVED_UIC e Privileges VMI SAVED_PRIVS e The system message format VMI SAVED_MSG If the last product installed requires a system reboot ALL_DONE does a minimal shutdown after alerting the installer It then executes the reboot VMSINSTAL returns a status in the DCL symbol STATUS If the installation failed a failure status is returned if it succeeded a success status is returned As its final task VMSINSTAL deassigns the installation specific logical names VMI ROOT VMI SPECIFIC VMI KWD if applicable and displays the completion message 4 3 Special Steps Steps 12 and 13 are invoked only under certain conditions The normal logical sequence has step 11 yielding control to ALL_DONE which finishes the installation When the system is booting if the startup procedures find a marker data file in SYS UPDATE it assumes that the system crashed during an installation and immediately invokes VMSINSTAL with the booting option B Step 1 tests for the booting option in symbol VMI BOOTING and branches to step 12 if VMI BOOTING is true VMSINSTAL is invoked with the GET save set option G if the installer chooses to copy the kit save sets rather than installing the kit After determining the product list step 3 tests the option parameter and immediately branches to step 13 if the G option is active 4 3 1 Step 12 4 8 Step 12 is a special step that performs recovery procedures if the system crashes during an ins
46. ILE NUMBER LOSE VMISPRODUCT_FILE UY UY UN UY I UN UY LL LM NM MMMM MMMMM MMMM DM ADO continued on next page Product Specific Callback Conventions Example C 1 Cont Product_Specific Callback Procedure Create a new version of the file in the working directory and put the incremented number in it OPEN WRITE VMISPRODUCT_FILE VMISKWD P3 WRITE VMISPRODUCT_FILE FSINT FSINT NUMBER FSINT P5 CLOSE VMISPRODUCT_FILE Also define the logical name to point at the final file 5 5 5 5 5 Provide the new file which will replace the old one 5 5 5 VMISCALLBACK PROVIDE_FILE P2 P3 P4 EXIT STATUS C 3 D How to Use the VMISVMS_VERSION Symbol Example D 1 shows some techniques for using the VMI VMS VERSION symbol to determine whether your product is compatible with the version level of the target system Although this example only checks for a specific version the techniques shown here may be adapted to check for a range of versions For more information about the CHECK_VMS VERSION callback see Section 5 6 Example D 1 Template for Using the VMISVMS_VERSION Symbol LN GF LU 4 0 UY UE AN ANS UY UN AN AS GS LU SY UY SY E ANY AN GS UY EN KKK KKK KKK KK KEK KKK KK KEK KKK KK KKK KK XK KK KK KEK KKK KK KEK KKK KK z VMISVMS_VERSION Template KKK KKK KKK KK KEK KKK KK KK KKK KK KKK KK KEK KEK KKK KEK KKK KK ARK KK KKK Modify the definitions of PRODUCTSREL_VERSIO
47. ION S RD O RW If you specify the VMI ROOT value for the user directory the callback alerts the installer by displaying the following message This product creates system disk directory This callback always returns VMI SUCCESS 5 11 DELETE_FILE Callback 5 14 The DELETE FILE callback deletes all versions of the specified file typically an obsolete file created by a previous installation You may need to set privileges or change the protection to delete certain files because the BYPASS privilege is not enabled for callbacks Note Do not include the version number of the specified file name All versions of a file are deleted If the callback is invoked while the installation is in safety mode the command line is written to the defer file for subsequent execution If you are deleting a file that has been installed with the Install utility the callback uses the Install utility to delete the image from the known file data base See the OpenVMS Systen Management Utilities Reference Manual for more information Use the following command line format to invoke the DELETE_FILE callback VMI CALLBACK DELETE_FILE filename VMSINSTAL Callbacks 5 11 DELETE_FILE Callback Parameters on the command line indicate the following filename Use this parameter P2 to enter the complete file specification device directory name and type of the file to be deleted Wildcard characters may be used in the filename This c
48. KTRAN_SPACE THEN EXIT VMIS_FAILURE Set up for a conditional safe installation VMISCALLBACK SET SAFETY CONDITIONAL 3000 1 Restore secondary savesets 1 VMISCALLBACK RESTORE_SAVESET B VMISCALLBACK RESTORE_SAVESET C N 1 l Check for purging and for IVP 1 VMISCALLBACK SET PURGE ASK VMISCALLBACK SET IVP ASK 1 Move the product image to SYSEXE 1 VMISCALLBACK PROVIDE_IMAGE CHECKTRAN_IMAGE CHECKTRAN EXE VMISROOT SYSEXE 1 Make the product callable from DCL 1 VMISCALLBACK PROVIDE_DCL_COMMAND CHECKTRAN CLD 1 Move the help files 1 VMISCALLBACK PROVIDE_DCL_HELP CHECKTRAN HLP l Move the startup command VMISCALLBACK PROVIDE_FILE CHECKTRAN_STARTUP CHECKTRAN_STARTUP COM VMISROOT SYSSSTARTUP Create IVP dirctory l VMISCALLBACK CREATE_DIRECTORY COMMON SYSTEST CHECKTRAN 1 Move IVP file l VMISCALLBACK PROVIDE_FILE CHECKTRAN_ CHECKTRAN_IVP COM VMISROOT SYSTEST l Identify the startup command file 1 VMISCALLBACK SET STARTUP CHECKTRAN_STARTUP COM continued on next page KITINSTAL Command Procedure 3 4 Basic KITINSTAL Command Procedure Example 3 1 Cont Basic KITINSTAL COM Move data file I VMISCALLBACK PROVIDE_FILE CHECKTRAN_DATA CHECKTRAN DAT VMISROOT SYSEXE ij Installation completed exit EXIT VMI _SUCCESS Post install phase ij CHECKTRAN_POSTINSTALL I No postinstall work I EXIT VMS _SUCCESS Verify installation CHE
49. LICENSE AND MAY BE USED AND COPIED ONLY IN ACCORDANCE OF THE TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE THIS SOFTWARE OR ANY OTHER COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON O TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL FACILITY VMSINSTAL ABSTRACT This procedure installs the DECRam_for_OpenVMS Product using VMSINSTAL ENVIRONMENT DCL Setup error handling l l l l l l l l l ON CONTROL_Y THEN GOTO CONTROL_Y l Handle INSTALL IVP and unsupported parameters passed by VMSINSTAL 1 DECRAMSVERSION T1 1 F Pl EQS VMIS_INSTALL THEN GOTO INSTALL F P1 EQS VMIS_IVP then goto DECRAM_RUN_IVP EXIT VMIS_UNSUPPORTED NSTALL DECRAM_TMP FSTYPE VMISARCHITECTURE DECRAM_ARCH 0 Initialize to VAX F DECRAM_TMP EQS THEN DECRAM_ARCH 0 F DECRAM_TMP EQS INTEGER THEN DECRAM_ARCH 0 F DECRAM_ TMP NES STRING THEN GOTO DONE_ARCH F VMISARCHITECTURE EQS AXP THEN DECRAM_ARCH F VMISARCHITECTURE EQS VAX THEN DECRAM_ARCH Il m
50. N and PRODUCTSFT_VERSION to define any version restrictions required for your product Define earliest released version of OpenVMS supported by the product PRODUCTSREL_VERSION 040 Define earliest field test version of OpenVMS supported by the product PRODUCTSFT_VERSION 041 Extract current running version number of OpenVMS PRODUCTSTYPE FSELEMENT 0 VMISVMS_VERSION V_RELEASED continued on next page How to Use the VMISVMS_VERSION Symbol Example D 1 Cont Template for Using the VMISVMS_VERSION Symbol Check for RELEASED version of OpenVMS Ss NOTE use String comparison to check in case version number contains Sal characters s IF PRODUCTSTYPE NES RELEASED THEN GOTO V_UPDATE IF FSELEMENT 1 FSELEMENT 1 VMISVMS_VERSION GES PRODUCTSREL_ VERSION THEN GOTO V_OK Sa SV_REL10 Ss VER V FSEXTRACT 1 1 PRODUCTSREL_VERSION FSEXTRACT 2 2 PRODUCTSREL_VERSION VMI CALLBACK MESSAGE E VERSION THIS PRODUCT REQUIRES OpenVMS VERSION VER OR LATER TO INSTALL S EXIT VMI _FAILURE V_UPDATE Sol Ss Check for Field Test version of OpenVMS 1 IF PRODUCTSTYPE NES UPDATE FT THEN GOTO V_BASELEVEL IF FSELEMENT 1 FSELEMENT 1 VMISVMS_VERSION GES PRODUCTSFT_VERSION THEN GOTO V_OK SV_UPD10 1 VER T FSEXTRACT 1 1 PRODUCTSFT_VERSION FSEXTRACT 2 2 PRODUCTSFT_VERSION VMISCALLBACK MESSAGE E FIELDTEST THIS PRODUCT REQ
51. OLB 5 25 VMSINSTAL Callbacks 5 23 PROVIDE_IMAGE Callback 5 26 e K Use this option to keep old copies of the image file do not purge e O Use this option to move the file to SYS SPECIFIC However you should only use this option if absolutely necessary If your product requires the option be sure to use the TELL_QA callback to inform the Digital OpenVMS Software Quality Management group e T Use this option to specify an input file that contains a list of logical names for the source image files and their respective destinations This option offers faster file processing however the system does not return file specific error messages That is if there is an error in one of the files listed in the input file the system only returns the general message File Not Found rather than identifying the specific file that contains the error The input file must conform to the following rules The file must reside in VMI KWD Each source file entry must use the same format as the command line as follows logical filename_type destination options ECO_list Each source file entry must be on a separate line in the input file You can include comment lines and blank lines in the input file The following is an example of the contents of an input file for the product named TEST PROVIDE_IMAGE data file TEST_FRED FRED EXE VMISROOT SYSEXE CKE 1 2 3 TEST_RALPH RALPH EXE VMISROOT SYSEXE TEST_JULIE
52. OpenVMS Developer s Guide to VMSINSTAL Order Number AA PWBXA TE May 1993 This manual describes the VMSINSTAL command procedure and gives developers information about using VMSINSTAL to design their own installation procedures Digital recommends that all installation procedures for products that layer on the OpenVMS operating system use VMSINSTAL The OpenVMS Devdoper s Guide to VMSINSTAL is available as an optional OpenVMS manual it is not included in the standard OpenVMS documentation set Revision Update Information This document supersedes the OpenVMS Devdoper s Guide to VMSINSTAL Version 5 5 It also supersedes the OpenVMS AXP Version 1 5 Operating System and Version OpenVMS VAX Version 6 0 OpenVMS AXP Version 1 5 Digital Equipment Corporation Maynard Massachusetts May 1993 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 Digital Equipment Corporation 1993 All Rights Reserved The postpaid Reader s C
53. SINSTAL MESSAGE VMSINSTAL VMSINSTAL uses this symbol to call the MESSAGE callback when an error message is required When an image is moved from the installation directory to a system directory VMSINSTAL assigns this process logical name to the specified image VMI NO_ERROR VMI NO_OUTPUT VMI NO_SUCH_SAVESET VMI OLD VMI PID VMI PLACE VMI PRETTY VMI PRODUCT VMI PRT VMI PURGE VMI QA VMI QA_FAIL VMI QUE VMI REBOOT VMIS REL VMI REMOTE VMI REMOUNT VMI REN VMI ROOT VMI SAFETY Symbols and Logical Names This local symbol is equated to DEFINE USER SYS ERROR NL and is used by VMSINSTAL to turn off error messages until the next DCL mage executes This local symbol is equated to DEFINE USER SYS OUTPUT NL and is used by VMSINSTAL to turn off the output until the next DCL image executes VMSINSTAL sets this Boolean flag to true when it cannot find the first save set for a product When a file is copied from the installation working directory toa system directory VMSINSTAL assigns this process logical name to the specified file This local symbol contains the process ID of the current process VMSINSTAL uses this global symbol to indicate the location of the distribution volume VMSINSTAL equates this local symbol to the name of the product being installed VWMI PRETTY is structured as formatted ASCII output and is used primarily for outputting product related messages during the installation
54. SINSTAL assigns this variable global symbol to user responses and to command line parameters that will have only short term use When active this local symbol indicates that the product is being installed in a root on a disk other than the running system disk VMSINSTAL uses this global symbol to indicate the architecture Alpha AXP or VAX of the target disk VMSINSTAL uses this logical name to access the auto answer file VMSINSTAL stores the value of the auto answer mode read or write in this local symbol This global symbol is used to store the value of the target system s BACKUP E OPENIN error message This local Boolean symbol is true only if the startup procedure calls VMSINSTAL to recover from a crash during the installation VMSINSTAL equates this local symbol to GSYSSUPDATE VMSINSTAL The KITINSTAL command procedure uses it to call various VMSINSTAL subroutines also referred to as callbacks VMSINSTAL uses this logical name to access the callback trace file When a new command is to be added to the system VMSINSTAL assigns this process logical name to the command table file that is to be modified This is the process logical name assigned to the patch file when it is found by the PATCH_IMAGE callback VMSINSTAL uses this local symbol to determine when all products have been installed VMSINSTAL uses this Boolean symbol to determine the root directory for the installation This Boolean symbol is set true i
55. SINSTAL can construct the correct name of the release notes file The file can then be restored and copied to the SYS HELP directory without adding a callback statement to KITINSTAL to provide the name of the file VMSINSTAL relies on this file name format when purging the release notes files if the installer chooses this option This recommended format also helps users to easily find release notes files in SYS HELLP or to find all files for a particular product Do not include the release notes text in the product Help files Instead include the release notes file in the kit s primary saveset saveset name A along with the KITINSTAL procedure and any other command procedures invoked by KITINSTAL This permits the user to view or print the information at the beginning of the installation The product s Help library may contain selected release note topics However the entire text of the release notes should still be supplied in a separate file The product s Help file might contain a reference that points to this file For example a user might enter the command HELP CHECKTRAN RELEASE_NOTES to see the following Help text release notes for CHECKTRAN are contained in the file SYSSHELP CHECKTRAN_042 RELEASE_NOTES You can type or print this file to read the release note information The product specific Help file could also include directions for using the DIRECTORY command to find the file and earlier versions of it Guidelines a
56. SINSTAL is called by the system startup procedure indicating an aborted previous attempt at installation the procedure branches to a special crash recovery routine Step 12 At this point VMSINSTAL gives the installer the opportunity to back up the system disk before doing the installation Then VMSINSTAL asks for the name of the device that will hold the distribution volumes during the installation and verifies the validity of the device gt On VAX systems if the distribution kit is to be mounted on the console device VMSINSTAL connects it using the System Generation utility SYSGEN dismounts the console volume if necessary and then allocates the console device for the installation VMSINSTAL also sets a flag to remount the console volume when the installation is completed On both AXP and VAX systems VMSINSTAL next asks for the name of the products to be installed If a product is distributed on tape or disk VMSINSTAL asks you to physically mount the distribution volume and then waits for an indication that you are ready to continue Next VMSINSTAL asks for any options that you might want to invoke 4 1 VMSINSTAL Functional Description 4 1 Overview VMSINSTAL then installs the kit and checks to see if any other kits are to be installed The installation follows this general sequence 1 VMSINSTAL sets up the environment needed to install the product including the creation of a working directory for the installation p
57. SION on OpenVMS baselevel VVER DECRAM_LATEST 1 Set LATEST to TRUE force installation of V54 version of DECRAM GOTO DECRAM_VERSION_DONE continued on next page B 3 Sample OpenVMS Installation Procedure Example B 1 Cont Sample DIGITAL OpenVMS KITINSTAL COM DECRAM_VERSION_OK VMISCALLBAC MESSAGE I VMSOK Installing DECram DECRAMSVERSION on OpenVMS Version VVER DECRAM_LATEST 0 Set LATEST to False use VVER to determine what to install VMISCALLBACK CHECK_VMS_VERSION DECRAM_ADDCLD 5 3 1 S 5 3 2 SDECRAM_VERSION_DONE ON WARNING THEN GOTO ERR_EXIT ON ERROR THEN GOTO ERR_EXIT back to normal error mode j Check for enough free blocks on system disk eed a minimum of j DECRAM MIN_BLOCK 1300 VMISCALLBACK CHECK_NET_UTILIZATION DECRAMS DECRAMSMIN_BLOCK IF NOT DECRAMS THEN VMISCALLBACK MESSAGE E NOSPACE This kit requires at least DECRAMSMIN_BLOCK free disk blocks Wt WAM MO OH Ur IF NOT DECRAMS THEN EXIT VMIS_FAILURE 5 1 Let VMSINSTAL ask about the files to be purged Sal VMI CALLBACK SET PURGE ASK vmi callback SET IVP ASK License Management Facility Registration SA IF DECRAM_ARCH EQ 1 THEN GOTO DECRAM_AXP_LICENSE ON ERROR THEN GOTO license_err don t quit if license not installed vmi callback CHECK_LICENSE DECRAM license_confirmed DECRAM DEC 1 0 Version updated every release 24 Jun 1991 Produc
58. These options are usually used for test purposes C The callback trace option traces all callbacks to VMSINSTAL during the installation and lists them in the file SY SUPD facvwu CBT See Chapter 2 for an explanation of the product identification facility code facvvu I The inhibit initial prompts option is used to suppress the following initial VMSINSTAL prompts Do you want to continue anyway NO Are you satisfied with the backup of your system disk YES Where will the distribution volumes be mounted K The kit debug option directs VMSINSTAL to pass a Boolean value that may be used as a debugging tool by KITINSTAL The kit debug option disables verification SET NOVERIFY while VMSINSTAL processes callbacks Verification is reactivated after callbacks are processed Q The quality assurance mode QA mode option specifies that the installation is being done in test mode It enables various functions that are peculiar to the test environment and ignores other functions that are not required in the test environment For example TELL_QA callbacks are performed and logged to the controlling terminal RSP The restore save set and pause option is a debugging option that causes the installation procedure to pause after restoring each save set At the pause you can either press Return at the prompt to resume or log in to another terminal if you want to create a subprocess This option lets you test a kit without rebui
59. UIRES OpenVMS VERSION VER OR LATER TO INSTALL EXIT VMIS_FAILURE o V_BASELEVEL Sol Always allow installations on baselevels of OpenVMS Required to ensure Ss early testing of the product by Digital Ss BASELEVEL F ELEMENT 1 FSELEMENT 1 VMISVMS_VERSION IF PRODUCTSTYPE NES UPGRADE FT THEN EXIT VMIS_FAILURE VMISCALLBACK MESSAGE I BASELEVEL INSTALLING ON OpenVMS BASELEVEL BASELEVEL INSTALLATION CONTINUING V_OK E Product Registration Product registration is a free service offered by Digital to customers Product registration prevents software conflicts among layered products by ensuring that the following elements of each product are unique e Facility code e Logical name prefixes Shareable image names Participation in registration is voluntary However Digital cannot guarantee that nonregistered products will not conflict with other products For more information about product registration including an application form contact the Registrar at the following address Digital Equipment Corporation Attn OpenVMS Product Registrar 110 Spit Brook Road Nashua NH 03062 9987 A ADD_IDENTIFIER callback 5 2 ALL_DONE subroutine 4 7 Alternate root option R 1 7 1 10 Alternate working device option AWD 1 9 Answer file 1 8 ASK callback 5 2 Auto answer option A 1 8 4 6 Booting option B 1 14 C Callbacks accessing files 3 3 ADD_I
60. VMISKWD NEWCHECK DAT WRITE 4 a o CLOSE OLDCHECK CLOSE NEWCHECK Move the file back to the source directory VMISCALLBACK PROVIDE_FILE NEW NEWCHECK DAT VMISROOT SYSTEST Has Ue USE Be careful not to use the same logical name in the PROVIDE_FILE callback as that used in the FIND_FILE callback 3 2 4 Updating a Library Use the UPDATE_LIBRARY callback to update libraries The following example updates the library in SYSLIB named CHECKTRAN TLB by adding a text file from the product kit Using the logical name CHECKDOC update the library VMISCALLBACK UPDATE_LIBRARY CHECKTLB _S VMISROOT SYSLIB CHECKTRAN TLB TEXT INSERT CHECKDOC 3 2 5 Deleting a File Use the DELETE FILE callback to delete a file For example if you want to delete the command language description file CHECKTRAN CLD after you use it to update the DCL tables use the following command VMISCALLBACK DELETE_FILE VMISROOT SYSHLP CHECKTRAN HLP Where applicable the DELETE FILE callback automatically removes known images created by INSTALL 3 2 6 Creating a Directory Use the CREATE_DIRECTORY callback to create a directory Note the following restrictions e You cannot create a top level directory on the system disk e You cannot create a directory or a subdirectory beginning with the string SYS The following example creates a new directory under the system manager directory VMISCALLBACK CREATE_DIRECTORY SYSTEM SYSMGR CHECKTRAN
61. a message stating that the system will be rebooted VMSINSTAL determines whether all products have been installed If some products have not been installed the procedure displays the message Products that have not been installed will be skipped 7 WMSINSTAL then proceeds to the ALL_DONE subroutine 4 2 12 All Done The ALL_DONE subroutine provides the functions required for normal completion of a product kit installation The subroutine begins by disabling the command interpreter error checking function and then turning off the statistics generator if applicable After allowing time for the completion of the statistics report VMSINSTAL closes any working files that may still be open including the following e VMI CALL_FILE e VMI DEFER_FILE e VMI MARKER_FILE e VMI PRODUCT_FILE e VMI TEMP FILE It then searches for and deletes any existing marker data files and restores the user s original file environment VMSINSTAL Functional Description 4 2 Functional Steps Following this the distribution volume is dismounted If the kit was installed from the console device ALL_DONE remounts the console volume The following files are closed after the console volume is remounted e VMI AUTO_FILE e VMI TERMINAL_FILE Next ALL_DONE restores the rest of the user s environment that was saved at the beginning of the installation including the following e Default directory VMI SAVED_DIR e Default protection VMI SAVED_PROT e U
62. ailure Because implementation of the safety feature requires a higher peak utilization of disk space parameters should be selected only after weighing the need for installation safety against anticipated space availability The SET SAFETY option also records the level of safety in the marker file to establish appropriate crash recovery procedures If you omit this option VMSINSTAL automatically specifies safety mode unconditionally that is without regard to available disk space If the system does not have sufficient disk space to support it the installation terminates with failure status Use the following command line format to invoke the SET SAFETY option VMI CALLBACK SET SAFETY keyword peak Parameters on the command line indicate the following keyword Use this parameter P3 to specify the required safety level for the installation from the following list Note that an entry is required in P4 if you select CONDITIONAL e YES Specifies safety mode You may specify a required peak disk space utilization as the fourth parameter in the command line If there is insufficient disk space the option returns VMI FAILURE and the installation terminates If you enter YES note that the safety sensitive callbacks will defer action that would otherwise jeopardize the safety level of the installation For example the PROVIDE_FILE callback defers movement of the new file until the installation progresses beyond safety mode Deferr
63. al Description 4 3 Special Steps 4 3 2 Step 13 4 10 Step 13 is a special step that handles the GET save set option G This option is used when the installer does not want to install a product immediately Instead the product save sets are copied from the distribution volume into a disk directory where they are available for future installation When save sets are copied using the G option the directory structure originally assigned to files within the save set are not maintained Because the directory structure is lost this option cannot be used to copy OpenVMS operating system kits First step 13 determines the target directory that is the directory into which the product save sets are to be copied It then verifies that the disk or magnetic tape is mounted and ready If the installer omits the target directory in P5 of the VMSINSTAL command line Step 13 prompts for it If no such directory exists step 13 provides a suitable display and prompts for the proper directory Then the procedure parses the answer to determine the full device specification If necessary the procedure creates a top level work directory VMIWORK pid where pid is the current process ID This directory is created on the system disk to restore the save sets so that new save sets can be created in the target directory Following this the installer is told to ignore redundant BACKUP error messages Because VMSINSTAL does not know how many save sets com
64. allback returns VMI SUCCESS unless it is unable to find the specified file in which case a VMI FAILURE status is returned 5 12 FIND FILE Callback VMSINSTAL uses the FIND_FILE callback to locate files either in a system directory or in the installation working directory Typically this callback is used to assign a logical name to the located file or to indicate whether the file exists and if so where it is located Files in the kit s working directory VMI KWD may be referenced without using the FIND FILE callback but any attempt to reference a system file without using a callback is likely to fail Use the following command line format to invoke the FIND_FILE callback VMI CALLBACK FIND_FILE logical filespec default spec locate symbol Parameters on the command line indicate the following logical Use this parameter P2 to assign a process logical name to the located file and use this logical name in all subsequent references to the file filespec Use this parameter P 3 to specify either fully or partly the file to be located default spec Where applicable use this parameter P4 to provide a default for partially specifying the file to be located Typically this parameter provides a default value for the device directory and type parts of the file specification The parameter value is then used with the previous parameter P3 value to derive the full file specification If you do not use this parameter be sure
65. ation guide text Use these parameters P4 through P8 to specify in quotation marks up to five message lines The first line is prefixed with a percent sign and the remaining lines are prefixed with a hyphen The hyphen serves as a line delimiter Use P5 P6 P7 and P8 as quoted parameters for additional message lines Following is an example of the command line for the MESSAGE callback VMISCALLBACK MESSAGE W NOFILE File does not exist Please read the manual The preceding example produces the following output for a product named PAI X010 SPAIX010 W NOFILE File does not exist PAIX010 W NOFILE Please read the manual This callback always returns VMI SUCCESS 5 17 PATCH_IMAGE Callback VAX Only T On VAX systems the PATCH_IMAGE callback patches existing native mode images as part of the product installation For each patch the installation kit must contain a patch file that includes the commands needed to patch the specified image Specify the image to be patched either in the image parameter or as a comment on the first line of the patch file The PATCH_IMAGE callback invokes the following callbacks UPDATE_FILE to update an existing patch journal file e PROVIDE _FILE to store a newly created patch journal file in a system directory e PROVIDE_IMAGE to store the patched image in a system directory Use the following command line format to invoke the PATCH_IMAGE callback VMI CALLBACK PATCH_IMAGE
66. back 5 16 GET_PASSWORD aallback 5 17 GET_SYSTEM_ PARAMETER callback 5 17 Global state changing 2 4 H Help libraries 2 6 History file 1 12 Inhibit initial prompts option 1 1 11 Installation achieving design goals 1 1 creating a work directory 1 5 installation phase 3 1 IVP phase 2 4 3 2 Installation Verification Procedure See IVP Install utility INSTALL 2 4 Index 2 Libraries using callbacks to update 3 5 Logical names definitions A 1 naming conventions 2 3 prefixing 5 1 use restrictions 5 1 VMI AUTO FILE 4 8 VMI CALL_FILE 4 7 VMI DEFER_FILE 1 13 4 7 VMI KWD 1 5 3 1 5 1 VMI MARKER FILE 1 13 4 7 4 8 VMI PRODUCT FILE 4 7 VMI ROOT 3 1 4 3 4 5 5 1 VMI SPECIFIC 3 1 4 3 VMI TEMP_FILE 4 7 VMI TERMINAL FILE 4 8 Magnetic tape kit specifying BACKUP qualifiers 2 3 Marker file 1 13 4 5 MESSAGE callback 5 18 Messages internationalization of 2 5 M odes compatibility 2 4 N Naming convention global symbol and logical name 2 3 3 1 KITINSTAL 3 1 product 2 1 release notes 2 6 save set 2 1 subroutine 2 3 Network checking status of 5 5 O Options See VMSINSTAL command procedure Options P Release notes option N 1 2 1 9 2 2 2 6 RENAME FILE callback 5 27 Request code KITINSTAL 3 6 VMI _IVP 3 3 Restore save set and pause option RSP 1 11 RESTORE_SAVESET callback 5 27 Restrictions callback 2 3 3 1 CREATE_DIRECTORY callback
67. back returns the current value of any system SYSGEN parameter by using the F GETSYI lexical function See the OpenVMS Systen Management Utilities Reference Manual for a list of system parameters and the OpenVMS DCL Dictionary for more information on the FSGETSYI lexical function Use the following command line format to invoke the GET_SYSTEM_ PARAMETER callback VMI CALLBACK GET_SYSTEM_PARAMETER symbol filename_type name option Parameters on the command line indicate the following symbol filename_type Use this parameter P2 to equate a global symbol to the value of the SYSGEN parameter If you specify the T option in P4 use parameter P2 to specify a file name 5 17 VMSINSTAL Callbacks 5 15 GET SYSTEM_PARAMETER Callback name Use this parameter P3 to specify the full name of the SYSGEN parameter being evaluated If you specify the T option in P4 enter a null string in P3 option Where applicable use this parameter P4 to specify options by entering the appropriate option letter Currently the only available option for this callback is the T option Use the T option to supply an input file filename type in P2 containing a list of global symbols and names The input file must conform to the following rules e The file must reside in VMI KWD e Each symbol and name must be separated by a space Each symbol and name entry must be on a separate line in the input file e You can indude comment lines and blan
68. bsequently reinstall the product and specify the auto answer option typically after a system upgrade VMSINSTAL reads the answer file instead of prompting the installer for responses Introduction 1 4 Choosing VMSINSTAL Options You should be familiar with the questions asked during a particular product installation before using the auto answer option Many products ask different questions depending on the environment If the questions change format or if questions are added or skipped when you are using answer files the installation terminates To create a new answer file when reinstalling a product you must first delete or rename the existing answer file AWD The alternate working device option lets you specify an alternate working device for the temporary working directory defined as the logical VMI KWD This option enables you to perform an installation with fewer free blocks on the VMI ROOT device than is otherwise required If you do not specify this option VMSINSTAL creates the temporary working directory in the following location SYSSSPECIFIC SYSUPD facvvu The variable facvvu represents the product identification string Specify this option using the following format AWD dev dir dev Specifies the alternate working device dir Specifies the directory under which the facwu subdirectory will be created Specifying a directory is optional If you do not specify a directory VMSINSTAL creates the working
69. by the callback to modify the file as needed The callback provides for the subsequent return of the updated file to the source directory If the installation is set for safety operation the callback provides for the return of the updated file when the installation progresses beyond safety mode However if the installation is not set for safety operation you must provide an explicit callback command to return it to the source directory after you modify it If the file is found in VMI KWD the file is not copied or returned to the source directory Following is an example of how to access an existing file during safety mode VMISCALLBACK UPDATE_FILE CHECKTRAN VMISROOT SYSEXE CHECKTRAN DAT 3 2 3 2 Updating a File by Creating a New Version To update a file by creating another version you must find the file copy it to VMI KWD update it and then move the updated version back to the original directory with the PROVIDE_FILE callback Use the SET PURGE callback or the K option to specify whether you want to keep the original version of the file after the updated version is created KITINSTAL Command Procedure 3 2 Using Callbacks The following example updates a file in VMI ROOT SY STEST by creating a new version Find the file VMISCALLBACK FIND_FILE OLD OLDCHECK DAT VMISROOT SYSTEST S Use the logical name to copy it to vmiS kwd COPY OLD VMISKWD OLDCHECK DAT Update the file OPEN OLDCHECK VMISKWD OLDCHECK DAT OPEN NEWCHECK
70. callback To utilize the checksum functions you must provide two checksums one representing the file prior to editing and one representing the file after editing To determine the appropriate values run the CHECKSUM program on the current version of the file and then run it on the new version of the file In each case the program stores the checksum value in the DCL symbol CHECKSUM CHECKSUM Use the value from the current version of the file as P6 in the SUMSLP_TEXT callback command line Use the value from the new version of the file as P7 The callback begins by looking for the editing file in the installation working directory After finding the editing file the callback checks to see if the target file or module to be edited is specified in the command line If it is not the callback builds the target specification together with the rest of the command line from the first line of the editing file Next the callback determines whether the target is a data file or a library module If it is a data file the callback parses P4 to make the file specification format compatible with the PROVIDE_FILE command structure Then the callback runs a checksum on the file edits it and if the edited file was found in a system directory returns it with a PROVIDE_FILE callback If the target is a library module the callback looks for the specified library extracts the specified module into a file in the installation work directory and then r
71. callbacks to VMSINSTAL KITINSTAL Command Procedure 3 2 Using Callbacks 3 2 1 Accessing Files While the product is being installed the only files that KITINSTAL can access directly are those in VMI KWD All other files must be accessed by using logical names supplied by various callbacks To gain read only access to a file outside of VMI K WD first invoke the FIND_ FILE callback Then use the logical name provided by FIND_FILE to access the file For example the following shows how you would access a file in VMI ROOT SYSTEST from KITINSTAL VMISCALLBACK FIND_FILE TSTFILE TEST DAT VMISROOT SYSTEST S TYPE TSTFILE See Section 5 12 for more information on the FIND_FILE callback 3 2 2 Moving Files from the Kit s Working Directory To move a file from the kit working directory VMI KWD to a system directory or a user directory use the PROVIDE_FILE callback The following KITINSTAL command moves a file to VMI ROOT SYSUPD and assigns a logical name to the file for future reference VMISCALLBACK PROVIDE_FILE CHECKTXT CHECKTRAN TXT VMIS ROOT SYSUPD See Section 5 22 for more information on the PROVIDE_FILE callback 3 2 3 Updating Files There are two ways to update a file You can either update an existing version or create another version 3 2 3 1 Updating an Existing File Version To update an existing version of a file use the UPDATE FILE callback to copy the file to VMISKWD Then use the logical name assigned
72. cates the following filename Use this parameter P3 to specify the file name and type of the product startup command procedure parameters Use this parameter P4 to pass parameters to the startup procedure Separate parameters with a space and enclose the list in quotation marks For example to pass VMSINSTAL as P1 and DOALL as P2 type the following command line VMISCALLBACK SET STARTUP CHECKTRAN_STARTUP COM VMSINSTAL DOALL The SET STARTUP option always returns VMI SUCCESS 5 37 VMSINSTAL Callbacks 5 29 SUMSLP_TEXT Callback 5 29 SUMSLP_TEXT Callback 5 38 The SUMSLP_TEXT callback is used to edit text files with the SUMSLP batch mode line editor and an appropriate editing file See the OpenVMS SUMSLP Utility Manual for more information In addition to the editing function the SUMSLP_TEXT callback supports the use of the checksum function to determinine whether the file has been incompatibly altered After you build the editing input file the editing input file must reside in the installation kit working directory In addition to editing standard data files you can use the callback to edit modules of the following ASCI based library types help macro and text With library editing the callback extracts the appropriate library module edits it and then returns it to the library using the UPDATE_LIBRARY callback For nonlibrary files the callback returns the file to the source directory using the PROVIDE_FILE
73. ches back to step 3 for the next product kit If the primary save set is found VMSINSTAL loops to build a product list from the distribution volume Following this VMSINSTAL sorts the products alphabetically to build an ordered installation product list Next the volume is dismounted and remounted for BACKUP operations the actual installation mechanism If the installer specified the GET save set option VMSINSTAL branches to step 13 if not it proceeds to step 4 In this step VMSINSTAL sets up the environment for restoring the kit s save sets VMSINSTAL determines if the RSP restore save set and pause option was specified and if this option specified an individual save set or all save sets VMSINSTAL also checks if the AWD alternate working device option was specified If so it defines the logical VMI KWD to point to the specified device VMSINSTAL Functional Description 4 2 Functional Steps 4 2 5 Step 5 This step is a loop point for obtaining listed products from the distribution volume The marker file is kept current to allow for recovery from system crashes Information maintained in the marker file includes the following e Target system root VMI ROOT e Facility and version VMI PRODUCT e State B before e Library being updated e State of the alternate root flag VMI ALTERNATE_ ROOT State of the common root flag VMI COMMON_ ROOT e Name of the system specific root VMI SPECIFIC e Additional infor
74. creates a new account in SYSUAF DAT and in NETPROXY DAT if it is a proxy account You are not permitted to use this callback if you are installing the product in an alternate directory root In most instances new software products do not need to create new accounts For example it is usually unnecessary to create a system management account for a product because the system manager can perform all management from the standard SYSTEM account Your installation procedure should prompt the installer for the UIC of the new account before you invoke this callback Use the following command line format to invoke the CREATE_ACCOUNT callback VMI CALLBACK CREATE_ACCOUNT username qualifiers Parameters on the command line indicate the following username Use this parameter P2 to associate a user name with the new account qualifiers Use this parameter P3 to list the qualifiers of the ADD command in the Authorize utility See the OpenVMS System Management Utilities Reference Manual for more information on the qualifiers to the DCL command ADD Enclose a list of qualifiers with quotation marks The following is an example of the command line for the CREATE _ ACCOUNT callback VMISCALLBACK CREATE_ACCOUNT SMITH PASSWORD FCDREG UIC 360 103 The CREATE_ACCOUNT callback returns VMI SUCCESS if the account is successfully created otherwise it returns VMI FAILURE 5 10 CREATE_DIRECTORY Callback Use the CREATE_DIRECTORY callback to
75. default integer value 3 If the installer enters a data type other than integer the callback repeats the original prompt that is Enter a number 3 The ASK callback returns VMI SUCCESS unless the installation is using an auto answer file and encounters a prompt mismatch The auto answer file includes both the prompt and the proper response If the prompt entered in 5 4 VMSINSTAL Callbacks 5 2 ASK Callback P3 of the callback command line does not match the prompt in the auto answer file a fatal error condition exists The installation terminates and the installer s terminal displays the following message Auto answer file is not in synch with questions In addition to this message the callback displays the mismatched prompts that is the prompt in P3 of the command line and the prompt in the auto answer file 5 3 CHECK_NETWORK Callback Use the CHECK_NETWORK callback to determine whether the network is running The installation can then either proceed or terminate based on the status of the network Products should display messages that indicate whether the network should be running while performing the installation Use the following command line format to invoke the CHECK_NETWORK callback VMI CALLBACK CHECK_NETWORK symbol The parameter on the command line indicates the following symbol Use this parameter P2 to specify a global symbol whose value reflects the status of the network This symbol returns a va
76. directory on the specified device with the following directory specification 000000 facvvu If you specify a directory VMSINSTAL creates the working directory as a subdirectory to the directory that you specify for example WORK facwu The directory that you specify must already exist If it does not exist VMSINSTAL will not create it For example to create the working directory INSTALL facvvu on the alternate device DUA2 specify the following AWD DUA2 INSTALL G The get save set option is used to copy the product kit save sets into a disk directory or other storage device such as a magnetic tape for later installation When option G is selected all kit save sets are copied but no installation is performed When save sets are copied using this option the directory structure originally assigned to files within the save set are not maintained Because the directory structure is lost this option cannot be used to copy OpenVMS operating system kits See Section 4 3 2 for more information on this option L The file log option is used to log all file activity to the controlling terminal during installation File activity is defined as any action that alters the disposition of a file such as creating a new file updating a library or deleting a file N The release notes option is used to display or print the release notes file supplied by the layered product The release notes file is named by the person who builds t
77. e device The device parameter P2 identifies the device that contains the media on which the product save sets are to be built product files The product files parameter P3 identifies the files that are being converted into save sets Typically you put the files for a particular save set in a dedicated directory and then use a wildcard input specifier for the BACKUP command This parameter must be null if you are specifying a data file data file The data file parameter P4 is an optional parameter that identifies a data file that SPKITBLD can use to obtain necessary information The following symbols can be defined in the data file 1 SPKITBLD KITNAME The name of the kit that SPKITBLD is to build Kit names have the following format facvvu where fac is the facility name vv is the major version number u is the update number 2 SPKITBLD REWIND_TAPE A Boolean flag that tells SPKITBLD whether save sets already exist on the media The default is Yes 3 SPKITBLD SAVESET_n One or more symbols that represent the files to be placed in the respective save sets The variable n starts with the alphabet from A to Z and then proceeds from VMI_0027 through VMI_9999 for example the first symbol is SPKITBLD SAVESET A the second is SPKITBLD SAVESET_B the twenty seventh symbol is SPKITBLD SAVESET_VMI_0027 and so on 4 SPKITBLD NEW_MEDIA_FOR_SAVE SET_n A Boolean flag that tells SPKITBLD that save set n should begin on a
78. e This section provides guidelines and conventions for the IVP phase of KITINSTAL COM The IVP may be invoked by KITINSTAL COM but the installer must be able to invoke it any time after the installation If you follow the guidelines listed here you will ensure that the installer can consistently invoke the IVP by using the following command line format SYSS TEST facility name_IVP Put the IVP in a separate file This allows the IVP to run independently of the installation procedure The IVP may consist of separate files but it should be invoked by one controlling command procedure Name the IVP according to the following format facility_IVP COM For example you might name a procedure CHECKTRAN_IVP COM 3 2 Using KITINSTAL Command Procedure 3 1 Guidelines for Writing a KITINSTAL Command Procedure e The KITINSTAL COM should tell the installer the location of the IVP Digital recommends that the IVP be located in the SYS TEST directory If other files are required to perform the installation verification for example a data file or executable image these files must be placed in a subdirectory of the SYS TEST directory The name of the subdirectory should be the same as the facility name of the product For example a subdirectory named SYS SYSDEVICE SYSTEST CHECKTRAN would hold additional files for the IVP for the product CHECKTRAN Use the CREATE_DIRECTORY callback to create the subdirectory For example the following comma
79. e These options override the previous default case including any default set by the SET ASK_CASE callback After this callback executes the default case returns to the previous value Following are options e A Turns auto answer off does not record prompts and responses in the auto answer file This option always requires input from the installer e B The answer must bein Boolean form YES or NO Y or N is also acceptable if it is not the question repeats until the installer responds with a Boolean entry e D Generates a blank line immediately preceding the prompt e E Turns terminal echo off for this prompt Additionally this option disables writing of the prompt and response to an auto answer file if one is being created This option always requires input from the installer If reading from an auto answer file this option causes a read timeout if a response is not received within a predetermined time Responses are thereby handled as classified data 5 3 VMSINSTAL Callbacks 5 2 ASK Callback e H Displays appropriate help text before displaying the prompt e The answer must be an integer if it is not the question repeats until the installer responds with an integer entry e L Returns input from the installer in lowercase M Returns input from the installer in the same case entered by the installer e N A null string response is acceptable applies to situations where a string response is requested
80. e SUMSLP_TEXT callback VMISCALLBACK SUMSLP_TEXT NEWSFILE TEXT FIX _ VMISKWD CHECKTRAN DOC FILE 1627371981 1563932641 K The callback returns VMI SUCCESS if it succeeds in editing the target or if it finds that editing was done by a previous callback The callback exits with VMI FAILURE if either the editing file or the target cannot be found if it detects file tampering or if the attempt to move the edited target back to its source fails 5 30 TELL_QA Callback The TELL_QA callback allows you to identify peculiarities in your product that should be noted if special technical considerations exist The TELL_QA callback generates specific messages for test environments only These messages appear only if the installation is being done in quality assurance QA mode Therefore to use this callback you must specify the QA mode option Q in the command line when you invoke VMSINSTAL Use the following command line format to invoke the TELL_QA callback VMI CALLBACK TELL_QA message message Use this parameter P2 to enter the message in the form of a quoted string In some situations it may be advisable to preface the installation software with appropriate TELL_QA callbacks The TELL_QA callback always returns VMI SUCCESS 5 31 UNWIND Callback The UNWIND callback provides a quick way to exit the installation When UNWIND is invoked VMSINSTAL runs through its cleanup code signals that the installation has failed and execu
81. e callback See the VMI TABLE symbol This local symbol is used by the DELETE_FILE callback to determine if the file was installed This local symbol is used to indicate the status of the installation When the installation begins VMSINSTAL sets this local Boolean symbol to logical true When this global Boolean symbol is set true the Installation Verification Process IVP is in progress VMSINSTAL assigns this process logical name to the journal file used in image patching where applicable This is the process logical name VMSINSTAL assigns to the kit working directory VMI KWD is the subdirectory of SYSUPD used to store the installation files This global symbol specifies a boolean value indicating whether or not the working directory will be deleted at the end of the installation This process logical name is assigned to library modules being updated by the SUMSLP_TXT subroutine VMSINSTAL uses this local symbol to store the string value of the command line parameter that lists the products to be installed VMSINSTAL uses this local symbol as a counter to determine the number of products in the distribution kit VMSINSTAL compares the value of this counter with VMI LIST_COUNT to determine when the product kit is installed This local symbol is used to open and read the file defined by the VMI LIST symbol VMSINSTAL uses this logical name to access the marker file This local symbol is equated to GSYS U PDATE VM
82. ecification semantic Use this parameter P3 to specify the semantic to be set for the specified file Following is an example of a command line that invokes the SET SEMANTICS option vmiScallback SET_SEMANTICS VMISROOT SYSUPD DUMMY DDIF DDIF This SET_SEMANTICS option returns VMI FAILURE if the file is not found otherwise it returns VMI SUCCESS 5 28 11 SET SHUTDOWN Option 5 36 The SET SHUTDOWN option specifies that a reboot is necessary to complete the product installation This option allows you to indicate e if a system reboot is allowed at this time e how long to wait before system is shutdown e whether to do an automatic reboot Use this option in the question portion of the product installation procedure If you are updating or upgrading in an alternate root directory or if you omit a SET SHUTDOWN command from your installation procedure the system will not be shut down following the installation Note This callback should replace the SET REBOOT option Use the following command line format to invoke the SET SHUTDOWN option VMI CALLBACK SET SHUTDOWN keyword symbol installation action VMSINSTAL Callbacks 5 28 SET Callback Parameters on the command line indicate the following keyword Use this parameter P3 to make the appropriate selection e ASK Use this keyword to specify a system shutdown is required and to prompt the installer for shutdown information e NO Use this keyword to
83. ecified in P3 and P4 do not match filespec1 Use this parameter to indicate the full file specification of the image file currently installed on the system filespec2 Use this parameter to indicate the full file specification of the image file that is part of the kit The following is an example of a command line that invokes the COMPARE _ IMAGE callback VMISCALLBACK COMPARE_IMAGE TST_CHECK VMISROOT SYSEXE RDO EXE VMISKWD RDO EXE The previous example compares two RDO images to determine which is the newest version and defines symbol TST CHECK accordingly This callback returns VMI SUCCESS if the file specified in P4 is found Otherwise it returns VMI FAILURE 5 8 CONTROL_Y Callback 5 10 This callback invoked without parameters performs housekeeping chores that must be invoked when the installer presses Ctrl Y Note The CONTROL_Y callback returns a warning status which executes your ON WARNING statement If you omit this statement in your installation command procedure and the installer presses Ctrl Y results are unpredictable VMSINSTAL Callbacks 5 8 CONTROL_Y Callback The installation procedure must either include an ON WARNING statement or it must provide a branch to a label that performs cleanup and then invokes the CONTROL Y callback The following is an example of the required command line ON CONTROL_Y THEN VMISCALLBACK CONTROL_Y 5 9 CREATE_ACCOUNT Callback The CREATE_ACCOUNT callback
84. econdary save sets to the kit working directory in the correct order Determine whether the product has an IVP and if so whether the installer wants the IVP to run after the installation Move the product s image files to the system directories using the PROVIDE _ IMAGE callback Update the DCL command tables if applicable so that the product can be invoked from the DCL level Move any product help files to SYSHLP Move the product specific startup command file to SYS STARTUP it should be invoked before running the IVP where applicable Move any product data files to the appropriate system directory Return the KITINSTAL exit status to VMSINSTAL when the installation terminates Where applicable run the IVP and indicate to VMSINSTAL whether the IVP was successful KITINSTAL Command Procedure 3 3 Summary of KITINSTAL Design Specifications Note Currently VMSINSTAL support for Digital s Distributed Software License Architecture DDSLA and License Management Facility LMF is not available to third party non Digital developers of layered products 3 4 Basic KITINSTAL Command Procedure Example 3 1 demonstrates a basic KITINSTAL COM for a product called CHECKTRAN Example 3 1 Basic KITINSTAL COM OI I II I II IR I I I I I ak I x CHECKTRAN KITINSTAL COM x LI I I II I II II I I I IK I ak l l ON CONTROL_Y THEN VMISCALLBACK CONTROL_Y Take care of interrupts Process errors
85. ed action on files by the safety sensitive callbacks occurs only if safety is set to on otherwise the action occurs immediately For small disk systems you may want to invoke these callbacks only after the affected file is no longer needed for the installation e CONDITIONAL Specifies safety mode only if there is enough space to support it You must specify required peak disk space utilization as the fourth parameter in the command line This is the suggested method for setting the safety level e NO Indicates that you do not want to specify safety mode 5 35 VMSINSTAL Callbacks 5 28 SET Callback peak Use this parameter P4 to enter the peak disk utilization level in blocks required for your installation If you omit this parameter and have entered either YES or CONDITIONAL in P3 the option responds as though there is sufficient disk space for safety operations The SET SAFETY option returns VMI SUCCESS unless you specify safety mode without sufficient disk space to support it in which case VMI FAILURE is returned 5 28 10 SET_SEMANTICS Option AXP Only AXP On AXP systems the SET SEMANTICS option sets a semantic file characteristic for the specified file You can specify only one semantic Use the following command line format to invoke the SET_SEMANTICS option SET_SEMANTICS file spec semantic Parameters on the command line indicate the following file_spec Use this parameter P2 to specify the full file sp
86. enVMS Installation Procedure Example B 1 shows a sample OpenVMS installation procedure The product used in the sample is DECRam_for_OpenVMS Note Until the VMISARCHITECTURE logical is implemented on OpenVMS systems you must use one of the following mechanisms to determine the architecture of the system running a KITINSTAL COM that is common for OpenVMS VAX and OpenVMS AXP systems For an OpenVMS VAX or OpenVMS AXP product that requires OpenVMS Version 5 5 or later use the following code sequence to determine the system architecture SYM FSGETSYI ARCH_TYPE IF SYM EQ 1 THEN DO_VAX_TASKS IF SYM EQ 2 THEN DO_AXP_TASKS This F GETSYI ARCH_TYPE lexical call returns 1 for OpenVMS VAX platforms and 2 for OpenVMS AXP platforms For an OpenVMS VAX or OpenVMS AXP product that requires a version of OpenVMS prior to OpenVMS Version 5 5 use the following sequence SYM FSGETSYI HW_MODEL IF SYM LE 1023 THEN DO_VAX_TASKS ELSE DO_AXP_TASKS The F GETSYI HW_MODEL lexical returns a value greater than 1023 for processors designed under the OpenVMS Alpha AXP architecture Sample OpenVMS Installation Procedure Example B 1 Sample DIGITAL OpenVMS KITINSTAL COM TITLE KITINSTAL DECRam_for_OpenVMS Installation Procedure IDENT V2 1 COPYRIGHT C 1985 1987 1988 1989 1990 1991 1992 BY DIGITAL EQUIPMENT CORPORATION MAYNARD MASSACHUSETTS ALL RIGHTS RESERVED THIS SOFTWARE IS FURNISHED UNDER A
87. er P3 to make the appropriate selection from the following list e ASK Use this keyword to prompt the installer for a decision on whether replaced files are to be purged If help is specified in P4 the prompt is prefaced by a help message Replaced files will be purged if the installer responds with YES or presses the Return key e YES Usethis keyword to specify that the replaced files will be purged e NO Use this keyword to specify that the replaced files will not be purged help Enter the letter H in this parameter P4 if you want to precede the ASK prompt with the following help message During this installation new files will be provided to replace existing versions You may purge older versions to save disk space or keep them if you feel they may be of use Purging is recommended The SET PURGE option always returns VMI SUCCESS Note The SET PURGE option must precede all PROVIDE callbacks VMSINSTAL Callbacks 5 28 SET Callback 5 28 8 SET REBOOT Option AXP The SET REBOOT option which was supported in previous releases of VMSINSTAL is obsolete The SET SHUTDOWN option should be used in its place See Section 5 28 11 On AXP systems VMSINSTAL issues a message stating that SET REBOOT is obsolete and automatically calls SET SHUTDOWN 5 28 9 SET SAFETY Option The SET SAFETY option establishes the safety level of the installation that is the installation s ability to recover from a system f
88. er the specification of the file to be printed Do not include a node name in the file specification copies Where applicable use this parameter P3 to specify the number of copies to be printed Its default value is 1 Following is an example of the command line for the PRINT FILE callback VMISCALLBACK PRINT_FILE VMISKWD CHECKTRAN TXT 3 This callback returns VMI SUCCESS unless the callback cannot find the file VMSINSTAL Callbacks 5 19 PRODUCT Callback 5 19 PRODUCT Callback When a layered product requires additional product specific callbacks include a command procedure in SYS UPDATE that includes those product specific callbacks The PRODUCT callback provides access to these callbacks by invoking the command procedure The callback command procedure acts as an extension of VMSINSTAL and is structured like it Use the following command line format to invoke the PRODUCT callback VMI CALLBACK PRODUCT procedure callback parameter Parameters on the command line indicate the following procedure callback Use this parameter P2 to specify the command procedure default type is COM in SYS UPDATE that contains the product specific callback together with the name of the callback itself For example the entry might be as follows VMISCALLBACK PRODUCT CHECKTRAN FIND_CHECK parameter parameter Use the remaining parameters on the command line to pass the appropriate values to the desired product specific callback
89. etermine the existence and location of a file Logical names and global symbols must begin with VMI the VMSINSTAL facility code because the callback procedure is a logical extension of VMSINSTAL e The return status from a standard callback must be checked with an IF statement to determine success or failure Because a failure indication is limited to a warning the error handler will not be invoked e The callback must return either a VMI SUCCESS or VMI FAILURE status Example C 1 demonstrates a product specific callback procedure Example C 1 Product Specific Callback Procedure First set up a CTRL Y handler and an error handler We don t want to trap warnings because they can happen legitimately ON CONTROL_Y THEN VMISCALLBACK CONTROL_Y ON ERROR THEN EXIT STATUS Use the first parameter to branch to the desired callback GOTO P1 INCREMENT logical name type directory integer This callback will increment the number stored in the file by the specified integer A new file will be created and put back in the original place with the logical name defined to point at it NCREMENT Begin by finding the file with the number to be incremented If the find fails then return a status to inform the caller ISFIND P2 P3 P4 S E F NOT STATUS THEN EXIT STATUS HS Read the record in the file which contains the number to be incremented PEN READ VMISPRODUCT_FILE P2 EAD VMISPRODUCT_F
90. ets into a storage directory for later installation P5 must specify the directory in the following format node ddcu directory where node is a node remote from the target system You must have DECnet software installed to use this option If no node is specified VMSINSTAL assumes that the product save sets are to be stored on the local node ddcu is the destination disk device directory is usually a directory dedicated to product save sets on the specified disk This parameter is optional qualifiers Where applicable use this parameter in conjunction with the get save set G option to further qualify the BACKUP command that copies the save sets to the destination directory See Section 1 4 1 for more information on the get save set option Introduction 1 3 Invoking VMSINSTAL The following example of a command line for invoking VMSINSTAL includes option G and BACKUP qualifiers SYSSUPDATE VMSINSTAL TESTO42 DUAO KITS OPTIONS _ G DUBO KITS VERIFY LOG CONFIRM The following example of a command line for invoking VMSINSTAL uses a wildcard character as the product list parameter to install all products from the distribution source SYSSUPDATE VMSINSTAL DUAO KITS OPTIONS N L The following example specifies a product name TEST as the product_list to install all versions of a product from the distribution source SYSSUPDATE VMSINSTAL TEST DUAO KITS OPTIONS N L This parameter
91. example of how to invoke SPKITBLD by including required parameters on the command line SYSSUPDATE SPKITBLD TESTO10 DUAO DUBO SCRATCH FRED DAT FRED EXE FRED COM Note that this example includes a list of files to be converted into save sets The files in a list must be separated by commas with no intervening spaces If you choose to have the SPKITBLD procedure prompt you for the required information perform the following steps 1 Invoke SPKITBLD as follows SYSSUPDATE SPKITBLD A version message is returned 2 The following prompt appears Do you want to use a kit building data file N If you want to use a kit building data file perform the following steps a Enter Y in response to the prompt b Specify the name of the data file in response to the following prompt Enter name of data file to use c Proceed to step 3 If you do not want to use a kit building data file perform the following steps a Enter N or press Return in response to the prompt The following message appears Kits have names in the format facvvu where fac is the facility name vv is the major version number u is the update number b Specify the name of the kit in response to the prompt Enter name of kit you want to build facvvu Introduction 1 1 Product Kits Specify the destination device in response to the prompt On which device is the kit to be built The following message appears Are you ready Y N Enter
92. f the installation is being done from a console device and is used to initiate console related functions When this local Boolean symbol is set true the installer has included the kit debug option in the VMSINSTAL command line VMSINSTAL uses this logical name to access the defer file VMSINSTAL uses this logical name when the statistics report subprocess is running Symbols and Logical Names VMI DEVICE VMI FAILURE VMIS FIL VMI FIND VMI FIRST_NEXT VMI FREE_BLOCKS VMI INPUT VMI INS VMISINSTALLATION_STATUS VMISINSTALLING VMISIVP VMIS NL VMI KWD VMI KWD_DELETE VMI LIB VMI LIST VMI LIST_COUNT VMI LIST_DONE VMI LIST_FILE VMI MARKER FILE VMI M SG VMI NEW This local symbol is equated to the name of the device that contains the distribution volume during the installation This local symbol equated to X10F 50000 indicates that the installation was unsuccessful This local symbol stores the results of file searches done by the UPDATE FILE subroutine VMSINSTAL equates this local symbol to GSYSSUPDATE VMSINSTAL FIND FILE KITINSTAL uses it to call the frequently invoked FIND_FILE routine VMSINSTAL uses this local symbol as a flag for prompting the user to enter the product from the first or next distribution volume VMSINSTAL assigns this local symbol to the number of free blocks available for the installation This local symbol is defined to be the file name for the input file to th
93. file use this parameter P5 to enter the keyword FILE If the callback is editing a library module enter one of the following to describe the type of library module being edited HELP TEXT MACRO current checksum Use this parameter P6 to specify the checksum for the current version of the target If the target checksum does not agree with this value the callback checks to see if the target was previously edited that is it matches new checksum If the target was not previously edited the callback assumes the target has been tampered with displays an appropriate message and returns VMI FAILURE new checksum Where applicable use this parameter P7 to specify the checksum for the new version of the target If the target checksum agrees with this value the callback assumes the target has already been edited and returns VMI SUCCESS option Where applicable use this parameter P8 to specify options by entering the appropriate option letter Currently only the K option is available e K Use this option to retain the current version of the edited file 5 39 VMSINSTAL Callbacks 5 29 SUMSLP_TEXT Callback Instead of using the callback command line you can specify the target checksum data and parameters P4 through P8 on the first line of the edit file If you do this use the following command line format target type current checksum new checksum options Following is an example of the command line for th
94. g to recover from a crash that occurred during a previous installation attempt At this point the procedure branches to step 12 to perform appropriate crash recovery procedures Then VMSINSTAL determines whether the product is being installed in an alternate system root and sets up appropriate logical names VMI ROOT and VMI SPECIFIC as follows e VMI ROOT represents the common top level directory for the target system and all references to common system directories must be in the form VMI ROOT SY Sxxx e VMIS SPECIFIC represents the systen specific top level directory for the target system and all references to system specific directories must be in the form VMI SPECIFIC SYSxxx Note It is recommended that you use VMI SPECIFIC or VMI ROOT for all references to the system disk rather than logical names prefixed with SYS Failure to do this will result in your product being installable only on the system disk If the file log option L is specified in P4 the LOG qualifier is appended to a set of appropriate DCL command verbs VMSINSTAL then checks various environmental items to ensure that it can perform the installation If the installer has opted for the GET save set option G these checks are omitted The product is not going to be immediately installed but the save sets are to be copied to a save set directory The checks include the installer s account privileges and quotas and the status of other sys
95. h the product kit and you use option N the release notes file must also be included in save set A 2 3 Volume Labeling Product save sets can be distributed on disk or tape media including console media It is strongly recommended that you adhere to the conventions for volume labeling given under the kit descriptions that follow Note that the owner user identification code UIC of files in the save sets is irrelevant File protection must be set as follows e System read write execute delete e Owner read write execute delete e Group read write execute delete e World read execute 2 3 1 Diskette Kits Each volume label for a diskette kit should be in the format facs where the variable fac represents the facility code and the variable s represents the save set sequence identifier The kit must be created directly on master distribution volumes using BACKUP to create sequential disk save sets The following qualifiers are required INTERCHANGE NERIFY BLOCK_SIZE 9000 GROUP_SIZE 25 The specified block and group size result in optimal use of the blocks on the diskettes Be sure to initialize double density diskettes for single density use so that they can be used on VAX11 780 RX0O1 console diskette drives Guidelines and Conventions 2 3 Volume Labeling 2 3 2 TU58 Cartridge Kits TU58 kits follow the same rules and conventions as diskette kits 2 3 3 Magnetic Tape Kits Magnetic tape volume labels must consi
96. he installation The IVP may consist of many separate files but it should be invoked by one command procedure that can be run independently of the installation procedure Guidelines and Conventions 2 9 Verifying Installation The IVP command procedure should adhere to the following naming convention facility name_IVP COM For example the IVP command procedure for the product CHECKTRAN would be named CHECKTRAN_IVP COM The IVP may be invoked from KITINSTAL COM but the installer must be able to invoke it any time after the installation Therefore the IVP must remain available after the installation Digital suggests that the IVP be placed in the SYS TEST directory The kit s installation procedure prompts the installer on whether to execute the IVP If the installer wants to execute the IVP then VMSINSTAL will run it when the installation is complete by invoking the kit installation procedure with the VMI IVP request code VMSINSTAL tries to set up a realistic work environment before running the IVP by doing the following e It assumes that KITINSTAL has put all product files in place e Ifthe installation procedure specified a product specific startup procedure with the SET STARTUP callback VMSINSTAL invokes it immediately before running the IVP e VMSINSTAL sets the default directory to the kit s working directory thus simulating a real user s environment e ThelVP should not use callbacks or the VMI SUCCESS or VMI FAILUR
97. he identifier you are creating qualifiers Use this parameter P3 to specify qualifiers You can specify any qualifiers of the ADD IDENTIFIER command in the Authorize utility Enclose a list of qualifiers in quotation marks Following is an example of a command line that invokes the ADD_IDENTIFIER callback VMISCALLBACK ADD_IDENTIFIER nodeaSident ATTRIBUTES RESOURCE In the previous example the ADD_IDENTIFIER callback adds identifier nodea ident and marks it as a resource The ADD_IDENTIFIER callback returns VMI SUCCESS if the identifier is successfully added otherise the callback returns VMI FAILURE 5 2 ASK Callback Use the ASK callback to get information from the installer The callback prompts the installer for a response verifies and evaluates it and then assigns it to the global symbol you specify The callback also provides help when the installer presses the question mark key Use the following command line format to invoke the ASK callback VMI CALLBACK ASK symbol prompt default_response options help VMSINSTAL Callbacks 5 2 ASK Callback Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that is equated to the installer s response It is a numeric value if the response is integer or Boolean data it is a string value if the response is string data In formatting the installer s response the callback automatically reduces multiple b
98. he product kit It is given the filename fac_vvu release notes where fac_wu represents the product facility code version and update numbers The release note file must 1 9 Introduction 1 4 Choosing VMSINSTAL Options 1 10 be included in the primary save set that is the save set containing the file extension A for example TEST 042 A See Section 2 12 for more information on product release notes During the installation of a product VMSINSTAL moves release notes files to the SYS HELP directory See Chapter 2 for more information about product naming conventions If release notes are available and the N option is specified VMSINSTAL prompts the installer with the following questions the default answers are indicated in brackets Release notes included with this kit are always copied to SYSSHELP Additional Release Notes Options 1 Display release notes 2 Print release notes 3 Both 1 and 2 4 None of the above Select option 2 Queue name SYSSPRINT Do you want to continue the installation N The first prompt Select option allows the installer to 1 display the release notes on a terminal 2 print the release notes 3 print and display the notes or 4 choose none of these options The second prompt Queue name is displayed only if option 2 or 3 is selected If you enter the name of a print queue the system returns a message indicating that the release notes have bee
99. hese are the images that execute when a user invokes your product from the DCL level e Source help files These files describe how to invoke your product and how to assign parameters and qualifiers most effectively e Help library files These files contain the various modules of help text for your product See the OpenVMS Command Definition Librarian and Message Utilities Manual for more information on creating help files e Other product files Any other files required to use your product e Installation Verification Procedure IVP This is a procedure that you design to check whether the product was installed properly The procedure should display or write the results of the verification 1 1 2 Building a Product Kit 1 2 You build your product kit by using the Software Product Kit Building command procedure SPKITBLD COM located in the SYS UPDATE directory When you invoke SPKITBLD you have the option of including required parameters on the command line or you can have the command procedure prompt you for them If you include the required parameters on the command line use the following format to invoke SPKITBLD SYS UPDATE SPKITBLD product name device product files data file Introduction 1 1 Product Kits product name The product name parameter P 1 is used to label the save sets See Chapter 2 for details on the conventions for naming your product This parameter must be null if you are specifying a data fil
100. his parameter if you also specify the T option options Where applicable use this parameter P5 to specify options using the appropriate letters from the following list If you list more than one option do not use intervening spaces between the selected letters e C Use this option if the file must reside in more than one location When you specify option C the file is copied from VMI KWD to its destination A copy of the file remains in VMI KWD e K Use this option to keep old copies of the file do not purge e O Use this option to add the file to SYS SPECIFIC You should only use this option if absolutely necessary If your product requires the option be sure to use the TELL_QA callback to inform the Digital OpenVMS Software Quality Management group 5 23 VMSINSTAL Callbacks 5 22 PROVIDE_FILE Callback e T Use this option to specify an input file that contains a list of logical names for the source files and their respective destinations This option offers faster file processing however the system does not return file specific error messages That is if there is an error in one of the files listed in the input file the system only returns the general message File Not Found rather than identifying the specific file that contains the error The input file must conform to the following rules The file must reside in VMI KWD Each source file entry must use the same format as the command line as fol
101. hrough Z as file types If your product requires more than 26 save sets the addition file types must begin with VM1I_0027 VMI_0028 and so forth up to a maximum of VMI_9999 option Where applicable use this parameter P3 to specify options by entering the appropriate option letter Currently the only available option for this callback is the N option next volume The N option is used to indicate that the save set begins on the next volume of the distribution volume set and the callback responds by prompting for the next volume Even if you do not specify this option the callback may prompt for the next volume if it cannot locate the save set on the current volume Following is an example of the command line for the RESTORE_SAVESET callback VMISCALLBACK RESTORE_SAVESET B N The callback returns VMI SUCCESS if it successfully restores the save set If the attempt is unsuccessful the callback returns VMI FAILURE and displays the appropriate message from the following list e Save set cannot be restored Null saveset name specified to RESTORE_SAVESET e Illegal saveset name specified to RESTORE_SAVESET 5 26 RUN_IMAGE Callback 5 28 Use the RUN_IMAGE callback when your product installation requires running an image If the image requires input provide an input file in the kit working directory because interactive input is not permitted Where applicable the callback defines SYS INPUT as the input file before it execu
102. iers Use this parameter P4 to specify one or more of the CREATE DIRECTORY command qualifiers OWNER_UIC PROTECTION VERSION_LIMIT The entire parameter must be specified as a character string enclosed by quotation marks For example to create a system specific directory called OLDPRODUCT enter the following command line VMISCALLBACK CREATE_DIRECTORY SPECIFIC OLDPRODUCT OWNER_UIC SMITH In most cases Digital recommends you create user directories rather than system specific directories Create system specific directories only where absolutely necessary This callback always returns VMI SUCCESS 5 10 3 Creating a Common Directory To create a system directory in the common area only use the following command line format VMI CALLBACK CREATE_DIRECTORY COMMON name qualifiers Parameters on the command line indicate the following COMMON When you enter the keyword COMMON in this parameter P2 the product directory is created under the system common area only name Use this parameter to specify the name of the directory The callback recognizes the keyword COMMON and makes the directory a rooted directory Therefore do not specify the system device designation and do not include the brackets usually used in directory name specifications qualifiers Use this parameter P4 to specify one or more of the CREATE DIRECTORY command qualifiers OWNER_UIC PROTECTION VERSION_LIMIT The entire parameter must be
103. ion If a previous version of the file was known by the Install utility the new version will replace it You cannot issue the PROVIDE_IMAGE callback more than once per image unless you specify the C option described in this section under Options The file can be either an executable image or a shareable nonexecutabl e image If it is a shareable image you can specify the option in P5 to direct a copy of the image s system table to the system s shareable image library SYS LIBRARY IMAGELIB OLB VMSINSTAL Callbacks 5 23 PROVIDE_IMAGE Callback The E option provides for patching outstanding Engineering Change Orders ECOs into the image if applicable This function should be used very carefully and only when necessary It is preferable to use the PATCH_IMAGE callback for this purpose or to add images that do not require patching Use the following command line format to invoke the PROVIDE_IMAGE callback VMI CALLBACK PROVIDE_IMAGE logical name_type destination options ECO_list Parameters on the command line indicate the following logical Use this parameter P2 to assign a process logical name to the new image file Use the logical name in all subsequent references to the file If you specify the T option in P5 use a null string in P2 because the logical name assignment for each file is included in the input file name_type Use this parameter P3 to specify the name and type of the source image file Only the name and
104. k lines in the input file The following is an example of the contents of an input file fac_GBL GBLPAGES fac_NODE SCSNODE fac_VAXC VAXCLUSTER Following are two examples of the command line for the GET_SYSTEM_ PARAMETER callback VMISCALLBACK GET_SYSTEM_PARAMETER TST_MAX WSMAX In this example the symbol TST_MAX is equated to the value of the SYSGEN parameter WSMAX VMISCALLBACK GET_SYSTEM_PARAMETER INPUT DAT T The preceding example shows how to use the T option to specify an input file This callback returns VMI SUCCESS If the input file is not found it returns VMI _ FAILURE 5 16 MESSAGE Callback 5 18 The MESSAGE callback displays a message in the standard OpenVMS format on the terminal controlling the installation Use this callback only to display important messages about the status of the installation To display large blocks of tutorial text direct output to SYS INPUT Use the following command line format to invoke the MESSAGE callback VMI CALLBACK MESSAGE severity_code id text Parameters on the command line indicate the following severity_code Use this parameter P2 to specify the severity level for the message Following are the severity level choices e S severe e information e W warning e E error VMSINSTAL Callbacks 5 16 MESSAGE Callback id Use this parameter P3 to specify the message identification The message identification enables cross referencing in the product install
105. lanks to a single blank removes all leading and trailing blanks removes comments and changes the response to the required case Uppercase is the default prompt Use this parameter P3 to specify in a quoted string the question to be asked The prompt should not indicate the default value of the response Do not indude trailing spaces a backslash 1 a colon or a question mark because these are added automatically default_response Where applicable use this parameter P4 to specify a default response to a prompt For example you might specify the letter Y as an acceptable default response to a prompt seeking a positive Boolean data type response If you do not want to specify a default response enter a null string in this parameter If you specify a default response the installer accepts it by pressing the Return key If you do not specify a default response the callback will continue to prompt for a response until the installer makes a valid entry options Where applicable use this parameter P5 to specify options choosing the appropriate letters from the following list If you specify more than one option do not enter spaces between the selected letters For example to ring a bell at the installer s terminal and to require a Boolean data type response enter the characters RB Note that options U L and M control the case in which input is returned from the installer for example uppercase or lowercas
106. lation progresses beyond safety mode The new file takes the name and type of the source file If the system previously included a file with the same name the new file becomes the current version Note You cannot issue the PROVIDE_FILE callback more than once per file unless you specify the C option described in this section under Options Do not use this callback to add new product images instead use the PROVIDE_IMAGE callback See Section 5 23 for more information on the PROVIDE_IMAGE callback Use the following command line format to invoke the PROVIDE_FILE callback VMI CALLBACK PROVIDE FILE logical filename_type destination options Parameters on the command line indicate the following logical Use this parameter P2 to assign a process logical name to the new file Use the logical name in all subsequent references to the file If you specify the T option in P5 enter a null string in P2 because the logical name assignment for each file is included in the input file filename_type Use this parameter P3 to specify the source file Only the name and type are required because the procedure assumes that the file resides in the installation working directory Do not specify a version number If you specify the T option in P5 enter the name of the input file in P3 destination Use this parameter P4 to specify the disk and directory name where the new file is to reside You must specify the null string for t
107. lding the kit after each minor fix For example during the pause you might edit a file that was previously restored or replace one version of a file with another You can also pause the installation procedure after a particular save set is restored by specifying the option in the following format s indicates the save set to be restored before pausing RSP s For example to pause after the installation procedure restores save set C specify the following option RSP C If you do not specify a save set with the RSP option the installation procedure pauses after each save set is restored S The statistics option produces a statistics report in the file SYSUPD facwu ANL This report contains a description of the hardware and software on which the installation was performed disk usage statistics and a list of files added deleted modified and accessed by the installation Correct disk usage statistics require that the system disk contain a full complement of OpenVMS software and enough free blocks for an installation in safety mode See the following section for more information about safety mode 1 11 Introduction 1 5 VMSINSTAL History File AXP Only 1 5 VMSINSTAL History File AXP Only AXP On AXP systems a VMSINSTAL history file SYS UPDATE VMSINSTAL HISTORY is updated when VMSINSTAL terminates The new file entry indicates the product for which installation was attempted and the status of the installation To view thi
108. llback The UPDATE_FILE callback makes a system file available for subsequent updating by copying it to the installation working directory if a copy is not currently there Note Do not use this callback to update library files see the UPDATE _ LIBRARY callback If a new version of an existing library file is needed create the new version in the working directory and then use the PROVIDE_FILE callback to replace the current version If the installation is in safety mode and a copy of the file is needed in the installation working directory the callback copies the file to the working directory using the Backup utility The file retains the original file ownership If the installation is not in safety mode or if the file is found in the installation working directory the callback exits without taking any action other than assigning P2 to its file specification When the update is completed the file is moved back to the system directory Note however that the move can be deferred if the installation is in safety mode Use the following command line format to invoke the UPDATE_FILE callback VMI CALLBACK UPDATE_FILE logical filespec option 5 41 VMSINSTAL Callbacks 5 33 UPDATE_FILE Callback Parameters on the command line indicate the following logical Use this parameter P2 to assign a logical name to the file being updated Use the logical name in all subsequent references to the file filespec Use this parame
109. llback VMSINSTAL equates VMI FIND to VMI CALLBACK FIND FILE as illustrated in the following command line VMISFIND SYSUAF VMISROOT SYSEXE SYSUAF DAT SE If the specified file is found or if no error message is returned when the file is not found the callback exits with VMI SUCCESS If the file specification parameters P3 and P4 cannot be parsed or if the file is not found and an error message is returned the callback exits with VMI FAILURE 5 13 GET_IMAGE_ID Callback 5 16 The GET_IMAGE_ID callback extracts the image file identification string data for a file Use the following command line format to invoke the GET_IMAGE_ID callback VMISCALLBACK GET_IMAGE_ID symbol filespec Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that VMSINSTAL equates to the image file identification string from the image header section filespec Use this parameter P3 to specify the full file specification of the file for which you want the file identification string The following is an example of a command line that invokes the GET_IMAGE_ID callback VMISCALLBACK GET_IMAGE_ID TST_IMAGE_ID VMISROOT SYSEXE RDO EXE This callback returns VMI SUCCESS if the file is found if the file is not found it returns VMI FAILURE VMSINSTAL Callbacks 5 14 GET PASSWORD Callback 5 14 GET_PASSWORD Callback The GET_PASSWORD callback obtains a system generated or installe
110. lows logical filename_type destination options Each source file entry must be on a separate line in the input file You can include comment lines and blank lines in the input file The following is an example of the contents of an input file for a product named TEST PROVIDE_FILE data file TEST_FREDE FREDE TXT VMISROOT TEST_FREDC FREDC COM VMISROOT TEST_FREDH FREDH DAT VMISROOT TEST_FREDM FREDM NTS VMISROOT SYSEXE C SYSUPD K SYSHLP sl Bl PA SYSLIB Following are two examples of the command line for the PROVIDE _FILE callback VMI CALLBACK PROVIDE_FILE CHECKTRAN_ CHECKTRAN OLD VMISROOT SYSLIB CK The preceding example shows how to specify more than one option in the command line VMISCALLBACK PROVIDE_FILE INPUT DAT T The preceding example shows how to use the T option to specify an input file The callback returns VMI SUCCESS unless the new file is not found in the working directory or the transfer fails 5 23 PROVIDE_IMAGE Callback 5 24 The PROVIDE_IMAGE callback adds a new image file to the system from the product kit by accessing a source image file in the installation working directory If the installation is in safety mode the addition is deferred until the installation progresses beyond safety mode The new file takes the name and type of the source image file If the system previously included an image file with the same name the new file becomes the current vers
111. lue of true 1 if the network is running and false 0 if the network is not running Following is an example of a command line that invokes the CHECK_NETWORK callback VMISCALLBACK CHECK_NETWORK TST_NETSTAT In the previous example the CHECK NETWORK callback defines the symbol TST_NETSTAT as true when the network is running and false when the network is not running The CHECK NETWORK callback always returns VMI SUCCESS 5 4 CHECK_NET_UTILIZATION Callback The CHECK_NET_UTILIZATION callback determines whether the peak number of free blocks on the VMI ROOT device is sufficient to successfully complete the installation and then returns the result in a global Boolean symbol You can obtain the net block usage for a product by using the statistics option when you invoke VMSINSTAL The net block usage refers to the total number of blocks required by the installation When a product is installed with the alternate working device option AWD the installer specifies an alternate device for the creation of the temporary working area The temporary working area is the location where temporary files are created and save sets are restored The CHECK_NET_UTILIZATION callback can be used in conjunction with the AWD option to specify the following e The number of free blocks that must be available on the device associated with the alternate working directory e The number of free blocks that must be available to complete the installation on
112. mation necessary to recover from a crash VMSINSTAL ends step 5 by announcing the product that will be installed 4 2 6 Step 6 In step 6 VMSINSTAL begins by deleting any previous kit working directory to make space for the product s working directory It then records in the symbol VMI FREE BLOCKS the number of free blocks available on the target system disk The symbol VMI KWD_FREE_BLOCKS records the number of free blocks available on the disk used for the kit working directory Next VMSINSTAL checks for and processes the statistics option S the auto answer option A and the callback trace option C Last VMSINSTAL creates the new kit working directory before giving control to step 7 If the installer has chosen the statistics option S VMSINSTAL displays the following message as it starts the statistics subprocess referred to from here on as the statistics demon Waiting for demon to record initial state This subprocess monitors the installation and produces a statistics report The subprocess is executed from VMI ROOT SYSUPD and is started with a process priority greater than the parent process The statistics demon follows this sequence of steps 1 Records the system directories the number of free blocks available and the current time 2 Opens a statistics report file 3 Sets the file retention on the target volume so that all file accesses are marked with an expiration date 4 Loops while monitoring
113. mmand line format to invoke the RENAME_FILE callback VMI CALLBACK RENAME FILE filespec new_filespec The parameters on the command line indicate the following filespec Use this parameter P2 to enter the complete specification of the file being renamed new _filespec Use this parameter P3 to specify the new directory name and type of the file being renamed You may omit the directory specification if the file will remain in the same directory Wildcards may be used Following is an example of the command line for the RENAME FILE callback VMISCALLBACK RENAME_FILE VMISKWD CHECKTRAN OLD CHECKTRAN NEW The callback returns VMI SUCCESS unless it cannot find the file 5 25 RESTORE_SAVESET Callback Where applicable use the RESTORE_SAVESET callback to restore secondary save sets Secondary save sets are recommended for installations where only part of the product is being installed or for larger products where it is more practical to package the product in multiple save sets Using secondary save sets also ensures that the CHECK NET UTILIZATION callback functions properly Selective structuring of the save sets can reduce the peak disk utilization and simplify the installation The following conventions govern the use of multiple save sets e The save sets must be restored in alphabetical order regardless of whether all of the save sets are restored Note that save set A is automatically restored first e All of the save sets fo
114. n of the installation e NO Use this keyword to specify that the IVP will not run at the completion of the installation help Enter the letter H in this parameter P4 if you want to precede the ASK prompt with the following help message Most products provide an Installation Verification Procedure IVP which verifies the completeness and accuracy of the installation You may wish to run the IVP immediately after installation The SET IVP option always returns VMI SUCCESS 5 28 5 SET POSTINSTALL Option UsetheSET POSTINSTALL option when you want a product s KITINSTAL COM procedure to be called after all files have been moved to their target directories This callback is useful when you must have all new files in place before completing an installation By default there is no postinstall phase This callback passes the string VMI POSTINSTALL to the KITINSTAL COM procedure in P1 The KITINSTAL COM procedure is executed immediately before the IVP phase Use the following command line format to invoke the SET POSTINSTALL option VMI CALLBACK SET POSTINSTALL keyword keyword Use this parameter P3 to make the appropriate selection from the following list e YES Usethis keyword to indicate the postinstall phase will be called when all files have been moved e NO Use this keyword to disable the postinstall phase The SET POSTINSTALL option always returns VMI SUCCESS 5 28 6 SET PRODUCT_NAME Option AXP Only AXP On
115. n successfully queued to the printer If a print queue is not specified the output is directed to SYS PRINT by default The third prompt Do you want to continue the installation allows you to either continue or terminate the installation The default is to terminate the installation at this point If no release notes are supplied with the product VMSINSTAL returns two error messages followed by the prompt to continue or terminate the installation as follows SVMSINSTAL W NOFILE New file RELEASE_NOTES does not exist SVMSINSTAL W NORELNOTE Unable to locate release notes Do you want to continue the installation N You can continue the installation by entering Y in response to this prompt regardless of whether or not release notes are available R The alternate root option is used to install the product on a system disk other than that of the running system This option makes it possible to test a new product without disturbing the running system The OpenVMS system in the alternate root must be complete and at the same version level as the running system Also all files and software products referenced by the product installation must be present in the alternate root All files are installed under the common directory of the alternate root Introduction 1 4 Choosing VMSINSTAL Options 1 4 2 Developer s Options Following is a description of the six VMSINSTAL options that are not normally used by the installer
116. nctional steps 4 1 to 4 10 guidelines and conventions 2 1 to 2 5 history file 1 12 installation phase 1 13 3 1 invoking 1 6 IVP phase 2 4 list installed products procedure 1 12 logic sequence 4 1 name prefixes 2 3 options 1 8to 1 11 developer s 1 11 installer s 1 8 OPTIONS keyword 1 6 outline of logic 1 5 parameter 1 6to 1 7 product installation file 1 12 recovery procedure 4 8 safety mode 1 13 Volume labeling conventions 2 2 W Wildcards restrictions 5 1 Work directory installation 1 5 on an alternate device 1 9 VMI KWD 1 5
117. nd Conventions 2 12 Release Notes To eliminate the need to reload the Help library with each release Help text on release notes may be written generically that is without specific reference to version number Note Digital recommends that your product s documentation advise users to keep previous editions of online release notes after receiving a new release of a product 2 7 3 KITINSTAL Command Procedure After your primary product save set is restored to the installation working directory VMSINSTAL invokes the KITINSTAL command procedure to direct the installation KITINSTAL issues a series of callbacks to VMSINSTAL by using the following callback command line format VMI CALLBACK callback parameter 2 The symbol VMI CALLBACK invokes VMSINSTAL which in turn uses the first parameter the name of the callback to execute the appropriate subroutine The remaining parameters are the arguments for the particular callback See Chapter 5 for detailed descriptions of the callbacks 3 1 Guidelines for Writing a KITINSTAL Command Procedure When you design the KITINSTAL command procedure for your product be sure to observe the guidelines and conventions described in this section They apply to both the installation phase and the IVP phase of KITINSTAL 3 1 1 Installation Phase This section provides guidelines and conventions for the installation phase of KITINSTAL COM See Section 3 1 2 for guidelines governing
118. nd creates a subdirectory for a product called CHECKTRAN VMISCALLBACK CREATE_DIRECTORY USER VMISROOT SYSTEST CHECKTRAN e Digital recommends that the IVP define a logical name that points to the subdirectory holding supplementary IVP files This logical name can be used throughout the IVP to refer to these files e The KITINSTAL COM must ask the installer whether to run the IVP To do so use the SET callback as follows VMISCALLBACK SET IVP ASK If the installer wants to run the IVP then VMSINSTAL will perform it after the installation is complete by invoking the KITINSTAL procedure as follows VMISKWD KITINSTAL VMIS_IVP e The kit installation procedure must handle the request code VMI _IVP e ThelVP cannot use VMSINSTAL callbacks e ThelVP should not use the VMI FAILURE and VMI SUCCESS symbols e The IVP should issue a message indicating the success or failure of its execution This message should include the product name and version For example an IVP might issue the following message IVP for CHECKTRAN V3 0 completed successfully e At the completion of the IVP the IVP must exit with a status back to the installation procedure e IfthelVP fails VMSINSTAL does not attempt to undo the installation The installation procedure must ensure that the product installs correctly For general information on the IVP see Section 2 9 Callbacks This section describes how to execute functions from KITINSTAL using
119. nd line and verifies that it is a valid device It then prompts for the product to be installed if you do not include it in the command line mounts the volume and checks for the presence of the correct save sets Next the environment needed to install the product is set up including a work directory dedicated to the storage of the product files during the installation The directory name reflects the product name and is logically referred to as VMI KWD VMI KWD is either a subdirectory of the system specific update directory VMI SPECIFIC SYSUPD or a subdirectory of the device and directory specified by the alternate working device AWD option The VMI KWD subdirectory is deleted when the installation is completed 1 5 Introduction 1 2 VMSINSTAL Functional Overview 5 The primary save set save set_nameA is restored to the work directory VMISKWD 6 Next the KITINSTAL command procedure restored from the primary save set is invoked KITINSTAL uses callbacks to VMSINSTAL to do the installation 7 When the installation is completed the product s Installation Verification Procedure IVP is invoked if applicable 8 After doing any necessary housekeeping VMSINSTAL prompts for the next product to install if applicable 9 If you specified an asterisk when VMSINSTAL prompted you for the product all products found on the distribution device are installed VMSINSTAL then prompts for additional product kits 1
120. new piece of media This symbol applies only to small disks kits being built on large disks or tapes must reside on the same piece of media The default is No 5 SPKITBLD AUTOINIT TAPE A Boolean flag that tells SPKITBLD to reinitialize a tape that does not have the correct volume label The default is Yes 6 SPKITBLD SKIP_FIRST TAPE READY _PROMPT A Boolean flag that tells the SPKITBLD procedure to skip the first prompt which asks if the tape is ready The default is No 7 SPKITBLD SKIP_FIRST DISK READY _PROMPT A Boolean flag that tells the SPKITBLD procedure to skip the first prompt which asks if the disk is ready The default is No 1 3 Introduction 1 1 Product Kits The following are examples of data files This data file builds a Pascal kit l SPKITBLD KITNAME PASCAL038 SPKITBLD SAVESET_A PASCAL038 RELEASE_NOTES KITINSTAL COM SPKITBLD SAVESET_B PASCAL EXE PASCAL CLD This data file builds a FORTRAN kit on the same media with Pascal l SPKITBLD KITNAME FORT050 SPKITBLD REWIND_MEDIA No SPKITBLD SKIP_FIRST_TAPE_READY_PROMPT Yes Just use existing tape SPKITBLD SAVESET_A FORT050A SPKITBLD SAVESET_B FORTO50B SPKITBLDSNEW_MEDIA_FOR_SAVE SET_C Yes Needs new media SPKITBLDSSAVESET_C FORTO50C When you invoke SPKITBLD it prompts you for any additional data it needs and if applicable it prompts you to physically manipulate media Following is an
121. nt information indicates variables and indicates complete titles of manuals Italic text also represents information that can vary in system messages for example Internal error number command lines for example PRODUCER name and command parameters in text Uppercase text indicates a command the name of a routine the name of a file or the abbreviation for a system privilege A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows All numbers in text are assumed to be decimal unless otherwise noted Nondecimal radixes binary octal or hexadecimal are explicitly indicated 1 Introduction The VMSINSTAL command procedure is the primary tool used by Digital to install OpenVMS updates and optional layered software products This manual provides the installation designer with information about using VMSINSTAL to develop procedures for installing products that layer on the OpenVMS operating system VMSINSTAL lets the OpenVMS developer create installation procedures that conform to uniform standards and are compatible with other Digital products Digital recommends that others who design layered products observe these same standards By using VMSINSTAL and following the guidelines provided in this manual you can achieve the following installation procedure design goals e Build product kits as BACKUP save sets by using the Software Product Kit Building command
122. nvoke the PROVIDE_DCL_HELP callback VMI CALLBACK PROVIDE_DCL_HELP name_type The parameters on the command line indicate the following name_type Use this parameter P2 to specify the name and type of the file used to update the library The file must reside in the kit s working directory and can be deleted after the callback returns Following is an example of the command line for the PROVIDE_DCL_HELP callback VMISCALLBACK PROVIDE_DCL_HELP CHECKTRAN HLP The PROVIDE_DCL_HELP callback cannot be invoked while the help library is in use If the library is in use PROVIDE _DCL_HELP tries to access the library for five minutes a message that states that the library is in use appears on the screen On VAX systems if the DCL help library is still in use at the end of five minutes PROVIDE_DCL_HELP exits with a failure status On AXP systems if the DCL help library is still in use at the end of five minutes PROVIDE_DCL_HELP provides new help files and informs the installer PROVIDE_DCL_HELP then exits with a success status On both AXP and VAX systems this callback exits with the status returned by the UPDATE_LIBRARY callback VMSINSTAL Callbacks 5 22 PROVIDE_FILE Callback 5 22 PROVIDE_FILE Callback The PROVIDE_FILE callback adds a new file to the system from the product kit by accessing a source file in the installation working directory If the installation is in safety mode the addition is deferred until the instal
123. oint for each product kit When all of the products in a kit have been processed or if a kit installation is prematurely terminated VMSINSTAL returns here to check for more product kits In step 3 VMSINSTAL determines the products to be installed and the proper installation order if there are multiple products in the kit If a product is listed in the first parameter P1 of the call to VMSINSTAL it is equated to VMI LIST if not the ASK callback is used to prompt for it The installer can terminate the installation at this point by entering a Ctrl Z or the word EXIT in response to the prompt VMSINSTAL then determines whether it needs to prompt the installer for options VMSINSTAL only prompts for this information when both of the following conditions are true e Options are not specified on the command line e VMSINSTAL must also prompt for the product_list or source device parameters Next VMSINSTAL checks to see if the distribution volume is mounted and if it is not prompts the installer to mount it Then VMSINSTAL checks that the distribution device specification is correct before continuing If either of these requirements is not met the procedure branches back to step 2 VMSINSTAL then checks the products on the distribution volume against the list of products entered by the installer If the product s primary save set is not found an appropriate message is displayed the installation of the kit is aborted and VMSINSTAL bran
124. omments forms at the end of this document request your critical evaluation to assist in preparing future documentation The following are trademarks of Digital Equipment Corporation Alpha AXP AXP Bookreader DECnet DECwindows Digital OpenVMS VAX VAX DOCUMENT VMS the AXP logo and the DIGITAL logo The following is a third party trademark PostScript is a registered trademark of Adobe Systems Inc All other trademarks and registered trademarks are the property of their respective holders ZK 4529 This document was prepared using VAX DOCUMENT Version 2 1 Preface 1 Introduction Produ Kits a at a eae adds Seka ees Files Included in a Product Kit Building a Product Kit VMSINSTAL Functional Overview 0 0 00 cc cee ees Invoking VMSINSTAL 0000 eee eee Choosing VMSINSTAL Options Installer s Options 005 Developer s Options 0050 VMSINSTAL History File AXP Only VMSINSTAL Product Installation File AXP Only List Installed Products Procedure AXP Only Safely Mode dia Ane a oa ew Recovery from System Failure 2 Guidelines and Conventions 2 12 Product Identification String Save Set Identification o o ooooooo Volume Labeling 0 00 cee eee Diskette Kits 0 002 c eee eee TU58 Cartridge Kits Magnetic Tape Kit
125. on marks For example to create a system directory called NEWPRODUCT enter the following command line VMISCALLBACK CREATE_DIRECTORY SYSTEM NEWPRODUCT OWNER_UIC SMITH The callback displays this message If you intend to execute this layered product on other nodes in your VAXcluster and you have the appropriate software license you must prepare the system specific roots on the other nodes by issuing the following command on each node using a suitably privileged account CREATE DIRECTORY SYSS SPECIFIC This callback always returns VMI SUCCESS 5 10 2 Creating a System Specific Directory 5 12 To create a system specific directory use the following command line format VMI CALLBACK CREATE_DIRECTORY SPECIFIC name qualifiers Parameters on the command line indicate the following SPECIFIC When you enter the keyword SPECIFIC in this parameter P2 the product directory is created in the system specific root for the installing system The directory is not created in the common area but is created in the system root on the disk for the installing system name Use this parameter to specify the name of the system specific directory The callback recognizes the keyword SPECIFIC and makes the directory a rooted directory Therefore do not specify the system device designation and do not include the brackets usually used in directory name specifications VMSINSTAL Callbacks 5 10 CREATE_DIRECTORY Callback qualif
126. on to keep old copies of the image file do not purge e O Use this option to move the file to SYS SPECIFIC However you should only use this option if absolutely necessary If your product requires the option be sure to use the TELL_QA callback to inform the Digital OpenVMS Software Quality Management group e R Use this option to reinstall the image when the patch is completed The options can either be specified in P5 of the call to PATCH_IMAGE or be included as an argument on the first line of the patch file using the following format filespec options You must separate the image name and the options with a space When this format is used the option list on the first line of the patch file is merged with the one specified in the callback if applicable Following is an example of the command line for the PATCH_IMAGE callback VMISCALLBACK PATCH_IMAGE NEWIMAGE IMAGE FIX This callback returns VMI SUCCESS It returns VMI FAILURE if the patch file or the image is not found or if the calls to UPDATE FILE or PROVIDE FILE return failure status 5 18 PRINT_FILE Callback 5 20 The PRINT_FILE callback queues a print job to SYS PRINT The print job is named after the product and multiple copies can be specified Use the following command line format to invoke the PRINT_FILE callback VMI CALLBACK PRINT_FILE filespec copies Parameters on the command line indicate the following filespec Use this parameter P2 to ent
127. ontains characters IF DECRAMSVMS_VERSION NES RELEASED THEN GOTO DECRAM_UPDATE VER V FSEXTRACT 1 1 DECRAMSREL_VERSION FSEXTRACT 2 2 DECRAMSREL_VERSION TVER FSELEMENT 1 VMISVMS_VERSION VVER V FSEXTRACT 1 1 TVER PSEXTRACT 2 2 TVER IF TVER GES DECRAMSREL_VERSION then goto DECRAM_VERSION_OK GOTO DECRAM_VERSION_ERROR l DECRAM_UPDATE l l Check for Field Test version IF DECRAMS VMS_VERSION NES UPDATE FT then goto DECRAM BASELEVEL VER T FSEXTRACT 1 1 DECRAMSFT_VERSION 11 PSEXTRACT 2 2 DECRAMSFT_VERSION TVER FSELEMENT 1 FSELEMENT 1 VMISVMS_VERSION VVER T FSEXTRACT 1 1 TVER FSEXTRACT 2 2 TVER IF TVER GES DECRAMSFT_VERSION THEN GOTO DECRAM_VERSION_OK l DECRAM_VERSION_ERROR l VMISCALLBACK MESSAGE E BADVMSVER DECram DECRAMSVERSION requires OpenVMS version VER or later to install EXIT VMIS_FAILURE SDECRAM_BASELEVEL UY Ur Ur Ur Ur Ur Ur Ur Always allow installations on baselevels of OpenVMS Required to ensure early testing of the product by Digital ij VER F ELEMENT 1 F ELEMENT 1 VMISVMS_VERSION VVER FSEXTRACT 1 1 VER FSEXTRACT 2 2 VER IF DECRAMSVMS_VERSION NES UPGRADE FT THEN EXIT VMI _FAILURE VMISCALLBACK MESSAGE I VMBLOK Installing DECram DECRAMSVER
128. opening 1 13 Introduction 1 9 Recovery from System Failure 1 14 the marker file for brief periods the possibility that this file will be impacted by a system failure is minimized When the system startup procedure detects a marker file as it attempts to recover from a system failure it calls VMSINSTAL with the booting option B This option reserved for Digital use only indicates that an installation was in progress when the failure occurred VMSINSTAL responds by branching toa subroutine that determines what action is needed Depending on the information in the marker file VMSINSTAL performs one of the following actions e ifthe failure occurred before KITINSTAL was invoked the installer is told to start the installation again e If the failure occurred while KITINSTAL was installing the product the following conditions are evaluated Ifa library was being updated at the time of the failure the installer is told to restore the library from the backup copy of the system and to start the installation again If the installation was in unsafe mode at the time of the failure the installer is told to restore the entire system from the backup copy and to start again For all other conditions the installer is told to start the installation again e If KITINSTAL has executed the deferred callbacks the installation should complete satisfactorily e If KITINSTAL has completed the installation the installer is
129. orking area this number is specified in P5 The values specified in P4 and P5 are used only when the product is installed using the alternate working device AWD option awd blocks Use this parameter P5 to specify the number of free blocks that must be available on the device associated with the alternate working directory Following is an example of the command line used to invoke the CHECK_NET_ UTILIZATION callback VMISCALLBACK CHECK_NET_UTILIZATION CHECK_ 20000 12000 10000 The preceding callback can function in the following ways depending on whether the installer specifies the AWD option e Ifthe installer does not specify the AWD option the callback returns the value true 1 in the symbol CHECK when the system has at least 20000 free blocks on the VMI ROOT device If the system does not have at least 20000 free blocks the callback returns a value of false 0 e Ifthe installer specifies the AWD option the callback returns the value 1 true when the VMI ROOT device has at least 12000 blocks and the alternate working device has at least 10000 blocks If either of these devices has less than the specified number of free blocks the callback returns a value of O for the CHECK symbol This callback always returns VMI SUCCESS VMSINSTAL Callbacks 5 5 CHECK_PRODUCT_VERSION Callback 5 5 CHECK_PRODUCT_VERSION Callback Use the CHECK PRODUCT VERSION callback to check the version of another layered product installed on
130. ormat to invoke the PROVIDE_DCL_ COMMAND callback VMI CALLBACK PROVIDE_DCL_COMMAND name_type 5 21 VMSINSTAL Callbacks 5 20 PROVIDE_DCL_COMMAND Callback Parameters on the command line indicate the following name_type Use this parameter P2 to enter the name and type of the CLD file used to update the tables Only the name and type are required because the file must reside in the installation working directory The file can be deleted when the callback returns if space is critical Following is an example of the command line for the PROVIDE_DCL_COMMAND callback VMISCALLBACK PROVIDE_DCL_COMMAND CHECKTRAN CLD The callback returns VMI SUCCESS unless the CLD file or DCLTABLES EXE is not found or where applicable the PROVIDE_IMAGE callback returns failed status 5 21 PROVIDE_DCL_HELP Callback AXP O 5 22 The PROVIDE_DCL_HEL P callback adds help appropriate for the installed product to the DCL help library SYS HELP HELPLIB HLB The callback does this by having the UPDATE_LIBRARY callback update the library using a help file provided with the kit On AXP systems PROVIDE_DCL_HELP checks for the logical definition HELPLIB If a logical definition for HELPLIB is present this callback uses the table defined by this logical On AXP and VAX systems multiple help entries can be added to the library using this callback as needed but only top level help entries are allowed Use the following command line format to i
131. ou do not select the alternate root option This global Boolean symbol is set true if the installation is being done in safety mode The decision to install the product in safety mode is in part determined by the amount of disk space available Your KITINSTAL procedure must make this determination Symbols and Logical Names VMI SAVED_DIR VMI SAVED_MSG VMI SAVED_PRIVS VMI SAVED_PROT VMI SAVED_UIC VMI SET_MSG_OFF VMI SET_MSG_ON VMI SPECIFIC VMI STARTUP VMI STAT_FILE VMI SUCCESS VMI SYS_ ARCHITECTURE VMI TABLE VMI TEMP_FILE VMI TERMINAL_FILE VMI TXT VMI UNSUPPORTED VMISUNWIND VMISUPDATE_MARKER VMI VERSION VMI VMS_ VERSION This local symbol is used to store the default device and directory of the current process during the installation VMSINSTAL uses this local symbol to store the message format of the current process during the installation This local symbol is used to store the privileges of the current process during the installation VMSINSTAL uses this local symbol to store the default protection code of the current process during the installation This local symbol is used to store the UIC of the current process during the installation VMSINSTAL equates this local symbol to the following SET MESSAGE NOFACILITY NOSEVERITY NOIDENT NOTEXT VMSINSTAL equates this local symbol to the following SET MESSAGE FACILITY SEVERITY IDENT TEXT VMSINSTAL uses this logical name to reference the target sy
132. pecific callbacks in the installation kit and invoke them from KITINSTAL see Appendix C for information about product specific callbacks However you can invoke the VMSINSTAL callbacks only from KITINSTAL and subprocedures from one level below KITINSTAL Defaults T he following defaults are in effect when KITINSTAL is invoked The VIC is 1 4 The default file protection is s rwed o rwed g rwed w re The default device and directory are MISSING MISSING VMSINSTAL sets the default to this nonexistent directory to prevent products from assuming a default device and directory To move or update any files a full file specification must be given otherwise VMSINSTAL will try to do the work in MISSING MISSING and fail All privileges except BYPASS are in effect Messages appear in full format SET commands tIn the installation portion of KITINSTAL COM as opposed to the IVP portion you are restricted from using the SET commands so that you do not alter the environment that VMSINSTAL has set up Exceptions to this rule are as follows You can use the SET ON and SET NOON commands without restriction You can use the SET VERIFY command only if the installer specifies the debug option You can use the SET FILE command only with files in VMI KWD SHOW command Your KITINSTAL command procedure must not rely on the output format of the SHOW command or the output format of any utility 3 1 2 IVP Phas
133. prise a software product it will simply copy as many as it can find Do not be concerned about error messages from BACKUP after all save sets have been copied Next a loop is used to copy the product save sets for each product in the product list appending any additional BACKUP qualifiers specified in P6 The two qualifiers appended by VMSINSTAL are INTERCHANGE and VERIFY The loop begins by telling the installer which product is being copied Then each of the product save sets is copied to the target directory The loop concludes by indicating the number of save sets copied for the product If an error occurs while any product save set is being copied the contents of the scratch directory are deleted and the program branches to an appropriate error handling routine before looking for the next product When all of a product s save sets are copied VMSINSTAL deletes the product work directory and branches to step 3 for more products If an error occurs while any product save set is being copied the following message is returned at the end of the installation This message is displayed regardless of whether any products were copied successfully Installation terminated due to unexpected event 9 VMSINSTAL Callbacks This chapter describes the VMSINSTAL callbacks and gives guidelines for using them in your installation command procedures The callbacks are presented in alphabetical order Following are rules and guidelines for u
134. procedure SPKITBLD COM As a result you can include larger files in the kit In addition the use of checksum blocks increases the chances of recovering from media errors that occur during the installation e Install products from a wide variety of media including console media magnetic tapes disks and both local and remote disk directories installing products from remote directories requires DE Cnet software an optional OpenVMS product e Minimize the effects of changes in OpenVMS from one version to the next on software product installation procedures e Include multiple products on a single distribution volume e Develop software product installations that are more uniform and consistent This chapter discusses the functional components and concepts required for using VMSINSTAL The chapters that follow describe VMSINSTAL in more detail including guidelines and conventions for its use a description of the KITINSTAL command procedure an outline of VMSINSTAL functional steps and a reference section describing the VMSINSTAL callbacks The term callback is used throughout this manual to refer to a recursive invocation of a specialized subroutine within VMSINSTAL For example VMSINSTAL provides callbacks that move files create directories and delete files Your KITINSTAL COM procedure invokes a specific callback within VMSINSTAL When VMSINSTAL has completed execution of the callback it returns control back to the KITINSTAL COM p
135. procedure can do additional work after all files are in place VMSINSTAL Functional Description 4 2 Functional Steps 4 2 10 Step 10 Step 10 begins by setting the default directory to the installation working directory VMSINSTAL then removes the VMI CALLBACK symbol to avoid any unintentional invocation of callbacks Next the product specific startup procedure is called if applicable On completion of the startup procedure VMSINSTAL invokes the IVP if applicable At the completion of the IVP VMSINSTAL resets the default directory to MISSING MISSING and redefines VMI SCALLBACK VMSINSTAL reports the results of the IVP before going on to step 11 4 2 11 Step 11 In Step 11 VMSINSTAL performs the following tasks then branches to step 5 for the next product 1 It closes the deferred callback file and deletes the kit s working directory 2 If applicable it pauses to wait for the completion of the statistics report while displaying an appropriate message 3 On completion of the statistics report VMSINSTAL closes any deferred working files that may be open and deletes the marker file 4 At this point the procedure checks to see if the installed product requires a reboot of the system If reboot is not required the procedure branches to step 5 to get the next product from the list 5 Ifa reboot is required VMSINSTAL must terminate the installation even if some products have not been installed 6 After displaying
136. r a particular product must be restored from the same physical device and directory For example if the primary save set is restored from MFAO all of the remaining save sets must be restored from MFAO Save sets can span multiple volumes however e The installation command procedure KITINSTAL COM must be part of the primary save set A If the distribution media is magnetic tape the callback will rewind the distribution media once to look for a save set If the save set is not found following the rewinding of the tape the callback returns VMI FAILURE 5 27 VMSINSTAL Callbacks 5 25 RESTORE_SAVESET Callback Restored files are assigned owner UIC 1 4 but retain the protection assigned them when they were saved This protection should be the same as the default value for the installation process If applicable the owner UIC and protection should be changed after files are restored using the SECURE_FILE callback If the RSP restore save set and pause option is specified the procedure will pause if appropriate Use the following command line format to invoke the RESTORE_SAVESET callback VMI CALLBACK RESTORE_SAVESET saveset option Parameters on the command line indicate the following saveset Use this parameter P2 to identify the save set you want to restore The secondary save set is identified using the file type B the next save set using C and so forth For the first 26 save sets use the alphabetic characters A t
137. r specified password The password is returned through a global symbol Passwords are not echoed on the installer s terminal This callback should be used in the question portion of the product installation procedure Use the following command line format to invoke the GET_PASSSWORD callback VMI CALLBACK GET_PASSWORD symbol keyword min size Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that VMSINSTAL defines with the obtained password If a password cannot be obtained the symbol is defined as the null string keyword Use this parameter P3 to make the appropriate selection e AUTO Use this keyword to indicate that you want the system to generate the password to be used The password selected is not made known to the installer This is the default if you do not specify a keyword e SPECIFY Use this keyword to indicate that you want the installer to specify the password to be used The prompt and password will not be entered into the auto answer file if one is being created This prompt always requires input min size Use this parameter P4 to specify the minimum length of the password For AUTO this must be a number from 1 to 10 the default value is 10 For SPECIFY this must be a number from 1 to 31 the default value is 8 The GET_PASSWORD callback always returns VMS SUCCESS 5 15 GET_SYSTEM_PARAMETER Callback The GET SYSTEM PARAMETER call
138. rameter P5 to specify the name of the product for which you are performing the version check If the product does not meet the minimum version requirement specified in P4 VMSINSTAL displays the following message to the installer This kit requires at least product_name minimum_version Please install a proper version of product_name before installing this product Enclose the product name with quotation marks Following is an example of a command line that invokes the CHECK_PRODUCT _ VERSION callback VMISCALLBACK CHECK_PRODUCT_VERSION TST_CHECK VMISROOT SYSEXE RDO EXE V3 0 OpenVMS AXP Rdb VMSINSTAL Callbacks 5 5 CHECK_PRODUCT_VERSION Callback In the previous example VMSINSTAL determines whether the RDO image is version 3 0 or higher If the image is version 3 0 or higher VMSINSTAL defines symbol TST CHECK as true This callback always returns VMI SUCCESS 5 6 CHECK_VMS_VERSION Callback Use the CHECK_VMS VERSION callback to limit the installation of a product to specified versions of the OpenVMS operating system When invoked this callback tests the version of the running system against the minimum and maximum versions necessary to install the product If the version number of the running system does not meet the specified criteria notify the installer To do this use the MESSAGE callback to display a message that specifies the current OpenVMS version of the installing system and the OpenVMS version necessary to install
139. rocedure 2 VMSINSTAL restores the first save set save set A This save set must include the KITINSTAL command procedure described in Chapter 3 If release notes are supplied with the product kit and you want to use option N the release notes file must also be included in save set A 3 VMSINSTAL calls KITINSTAL to direct the installation and KITINSTAL in turn uses callbacks to VMSINSTAL to do the installation Note that certain callbacks can be deferred until the installation is at a point where it is safe to do the callback functions See Chapter 5 for detailed descriptions of the VMSINSTAL callbacks 4 When all callbacks are completed VMSINSTAL invokes the product s Installation Verification Procedure IVP if one exists 5 Finally VMSINSTAL cleans up the files created for doing the installation remounts the console device and restores the normal work environment If the product requires rebooting the system VMSINSTAL shuts down and reboots it Two special installation scenarios are detailed at the end of this chapter One describes how VMSINSTAL recovers from system failures that may occur during the installation Section 4 3 1 the other pertains to copying save sets into a disk directory for later installation Section 4 3 2 4 2 Functional Steps 4 2 1 Step 1 4 2 The following sections describe in detail the functional steps executed by VMSINSTAL when it is invoked In this step VMSINSTAL provides overall ini
140. rocedure See Appendix B Introduction 1 1 Product Kits 1 1 Product Kits Software products that layer on OpenVMS are assembled into product kits that are physically distributed as one or more save sets files created by the Backup utility The file name of each save set must be identical to the product name and be assigned a unique file type that reflects the order in which the save sets are installed The first 26 product save set files are assigned file types using alphabetic characters for example TESTO11 A See Chapter 2 for detailed information on product identification conventions 1 1 1 Files Included in a Product Kit A product kit includes some or all of the following files e KITINSTAL command procedure The kit must include a command procedure that installs your product The command procedure must be named KITINSTAL COM and it must be included in the kit s primary save set assigned file type A See Chapter 3 for an outline of how to write a KITINSTAL command procedure for your product e Release notes file If online release notes are provided with your product and you select the N option the release notes file must be included in save set A See Section 1 4 1 for more information on the N option e Command language description CLD files These files contain the command language descriptions that allow a user to invoke your product from the Digital Command Language DCL level e Product image files T
141. rsion 5 0 5 2 In this example the CHECK_VMS_VERSION callback limits product installation to OpenVMS Versions 5 0 through 5 2 This callback always returns VMI SUCCESS 5 7 COMPARE_IMAGE Callback The COMPARE_IMAGE callback compares the image file identification string of two image files and returns a value that indicates which file is a more recent version The image identification is specified in the following format fac tvv u m where fac is the product s registered facility name for example RDB t is the type of release for example V for released version T for field test version vv is the major version number u is the update number m is the maintenance number VMSINSTAL Callbacks 5 7 COMPARE_IMAGE Callback Use the following command line format to invoke the COMPARE_IMAGE callback VMI CALLBACK COMPARE_IMAGE symbol filespec1 filespec2 Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that returns one of the following values e VMI K_KIT_VER_OLDER indicates that the image file specified in P4 is an older version than the image file specified in P3 e VMI K_KIT_VER_NEWER indicates that the image file specified in P4 is a newer version than the image file specified in P3 e VMIS K_KIT_VER_SAME indicates that the image files specified in P3 and P4 are the same version e VMI K_KIT_VER_NOMATCH indicates that the facility names of the files sp
142. ry aoaaa aaa ee 5 13 5 10 4 Creating a User Directory 0 0 00 ee 5 13 5 11 DELETE FILE Callback o ooooocoooocoooo i e 5 14 5 12 FIND FIELE Callbacks re teren aa a e ee E ES 5 15 5 13 GET_IMAGE_ID Callback 0 0 ee 5 16 5 14 GET PASSWORD Callback 0 0 ee 5 17 5 15 GET SYSTEM PARAMETER Callback 0000 cess 5 17 5 16 MESSAGE Callback ss 228 ocio ae he hee ae Seed ER eh Sede ke 5 18 5 17 PATCH_IMAGE Callback VAX Only 0 0 cee 5 19 5 18 PRINT FILE Callback 0 0 0 5 20 5 19 PRODUCT Callba k isis lat 5 21 5 20 PROVIDE_DCL_COMMAND Callback 0 002 eee eee ee 5 21 5 21 PROVIDE_DCL_HELP Callback 0 ee 5 22 5 22 PROVIDE_FILE Callback i aur d rakane a a a a ee 5 23 5 23 PROVIDE_IMAGE Callback 0 0 cece ee 5 24 5 24 RENAME FILE Callback sredni eaea eaa E R ee 5 27 5 25 RESTORE_SAVESET Callback 0 0 eee neo 5 27 5 26 RUN IMAGE Callback o ooooooooornrrrnrrera ee 5 28 5 27 SECURE_FILE Callback o oooocoooooocncrrrnra ee 5 29 528 SEN Callback eh canica Ra NEA a aN eons 5 30 5 28 1 SET ACI Optoma iii tas Ga Aaa we a ae 5 30 5 28 2 SET ASK CASE OptiOn we iio ica bie ae es 5 31 5 28 3 SET_FILE Option AXP Only 0 0 00 eee 5 31 5 28 4 SET AVP Option meo A eae aie AAA ee 5 32 5 28 5 SET POSTINSTALL Opti0N ooooooccoccoro a A 5 33 5 28 6 SET PRODUCT_NAME Option AXP Only o oooooooo o
143. s 0 Logical Names and Global Symbols Error Handling 0 00 cece eee ees Compatibility Mode VAX Only Referencing Other ProduttS Changing Global State Verifying Installation o ooo oo o Prompting the Installer for Input Internationalization of VMSINSTAL Messages Release NoOt8S oooococcccnooo es 3 KITINSTAL Command Procedure Guidelines for Writing a KITINSTAL Command Procedure 3 1 3 1 1 3 1 2 3 2 3 2 1 3 2 2 Installation Phase IVP PHASE iia aaa Using Callbacks 0 0000 cece eee Accessing FileS ooooooooooommmo Moving Files from the Kit s Working Directory Contents vii ee ee ee ee ee md NW 00 00nNDNmmD 3 2 3 Updating Files 0 de ioe bee aa Sa 3 4 3 2 3 1 Updating an Existing File Version 0 ccc eee eee 3 4 3 2 3 2 Updating a File by Creating a New Version 3 4 3 2 4 Updating a Library as cai da ca i a i es 3 5 3 2 5 Deleting a File sidesse rl a a id 3 5 3 2 6 Creating a Directory oei aeaea a A a A a E ee 3 5 3 3 Summary of KITINSTAL Design Specificati0MS ooo o o 3 6 3 4 Basic KITINSTAL Command Procedure 000 ce eee 3 7 4 VMSINSTAL Functional Description 4 1 OVERVIEW 25 Gia a Chace bo a Gia n 4 1 4 2 Functional Steps e vic e Ben ee eae cals Beaty E OM ea Oe Yee ee
144. s history file use the TYPE or PRINT commands 1 6 VMSINSTAL Product Installation File AXP Only AXP On AXP systems a log file named SYS UPDATE facvwwu VMI_DATA is created following a successful product installation This file contains the following information e Product that was installed e Who installed the product e Names of files that were added deleted or modified during installation To view this log file use the TYPE or PRINT commands 1 7 List Installed Products Procedure AXP Only AXP On AXP systems the procedure SYS UPDATE INSTALLED_PRDS COM lets you check what products have been installed This procedure lists the product name and version date of installation and who installed the product The procedure has an optional parameter to specify a restricted search of installed products Use the following format to invoke this procedure SYS UPDATE INSTALLED_PRDS product mnemonic where product_mneumonic iS an optional string that specifies one or more product save set names to search for This string can contain a save set name product name and version a product name only or wildcard characters Installation data is displayed only for product log files that are found on the system For example SYSSUPDATE INSTALLED_PRDS RDBVMS030 This procedure lists information only if a data file for RDBVMS V3 0 is found SYSSUPDATE INSTALLED_PRDS RDBVMS This procedure lists information for all versions of RD
145. sh occurred the following message is displayed The following library was being updated when the system crashed Other than that the system should be in a usable state Restore the library from backup and then begin the installation again e If the installation was not in safety mode when the crash occurred the following message is displayed The installation was being performed in such a way as to minimize disk usage One or more files may now be in an unusable state Please restore your system disk from backup and then begin the installation again e If the installation was nearly completed when the crash occurred the following message is displayed VMSINSTAL will attempt to complete the installation because it was almost done before the crash Please ignore any error messages listed below After booting is completed you MUST boot the system again In this situation step 12 opens the defer file to begin the deferred callback executions e If the installation was completed when the crash occurred the following message is displayed The installation was completed satisfactorily From here VMSINSTAL proceeds to do a normal completion after displaying the following message Please read your documentation for a complete description of installation crash recovery There may be additional things that you need to do manually such as purging the system disk or deleting certain layered product files 4 9 VMSINSTAL Function
146. sing VMSINSTAL callbacks Add callbacks only to KITINSTAL COM or to files directly invoked from it Specify keywords in uppercase Do not abbreviate them Begin all logical names to be defined by the callback with a prefix that consists of your product facility code followed by an underscore for example CHECKTRAN_ If the logical name is never referenced after being specified in the callback use only the prefix You must refer to the kit s working directory using the logical name VMI KWD Refer to system directories using the logical name VMI ROOT and an explicit directory such as VMI ROOT SY SLIB When referring to other directories you must specify either an explicit device logical name not a device number and a directory or a logical name for the entire file specification Any referenced disk must be mounted and must include the specified directory When a callback parameter requires only the file name and type it automatically includes the device and directory portions of the file specification In these instances you are not allowed to specify the device or the directory and you cannot use logical names or wildcards When a callback parameter requires a complete file specification disk directory name and type you can use a logical name Use of wildcards is not allowed When a parameter permits multiple options represented by single character codes do not use embedded spaces All callbacks return an exit status
147. specified as a character string enclosed by quotation marks for example you might specify OWNER_UICSMITH The following is an example of a command line that creates the directory VMS COMMON MYPROD LOGS VMISCALLBACK CREATE_DIRECTORY COMMON MYPROD LOGS This callback always returns VMI SUCCESS 5 10 4 Creating a User Directory To create a user directory use the following command line format VMI CALLBACK CREATE_DIRECTORY USER name qualifiers 5 13 VMSINSTAL Callbacks 5 10 CREATE_DIRECTORY Callback Parameters on the command line indicate the following USER When you enter the keyword USER in this parameter P2 you must specify whether the directory is being created on the system disk or a user disk Since most optional software products are associated with a particular system root and should reside in that root avoid creating product directories on user disks unless absolutely necessary name Use this parameter to specify the user directory The device portion of the specification must be a valid device specification qualifiers Use this parameter P4 to specify one or more of the CREATE DIRECTORY command qualifiers OWNER_UIC PROTECTION VVERSION_LIMIT The entire parameter must be specified as a character string that is within quotation marks For example to create a directory called USER1 on user disk DISK 1 enter the following command line VMISCALLBACK CREATE_DIRECTORY USER DISK1 USER1 PROTECT
148. ssages If the specified language cannot be found or is not valid VMSINSTAL uses the default language file 2 12 Release Notes Release notes provide information on changes made to a product since the previous release of that product Digital recommends that all product kits include both a printed and online version of release notes This section provides guidelines for including online release notes The Release Notes N option of VMSINSTAL enables the installer to display or print online release notes before beginning an installation To use this option the installer must invoke VMSINSTAL However once VMSINSTAL has been invoked and the release notes are printed or displayed the installer has the option to continue or cancel the installation Product files do not have to be restored from the kit at that time See Section 1 4 1 for more information on the N option The instructions for displaying and printing release notes should be identical for all products Provide these instructions in both the product s installation guide and the cover letter The online release notes file should be a machine readable printable file The name of this file must adhere to the following format fac _vvu RELEASE_NOTES The variable fac is the product s facility name and wvu is the version number For example TEST_042 RELEASE_NOTES is the name of the release notes file for TEST Version 4 2 If your file name follows the recommended format VM
149. st of no more than six characters in the format fac where the variable fac represents the facility code To create save sets the kit must be created directly on the master volume using BACKUP with the INTERCHANGE and VERIFY qualifiers Save sets must be placed on the tape in sequential order There is no restriction to the number of kits that can be placed on one magnetic tape Save set names cannot exceed 17 characters including the period and file type fields 2 4 Logical Names and Global Symbols All logical names and global symbols assigned by VMSINSTAL begin with the prefix VMI KITINSTAL COM logical names and global symbols must be prefixed with your product facility code followed by an underscore _ For example a FORTRAN product might use the prefix FORT_ Local symbols can use any name Avoid using abbreviations in the KITINSTAL procedures DCL commands Do not abbreviate verbs because special symbols may be defined for them by VMSINSTAL Qualifiers should also be spelled out but you can truncate them to a minimum of four characters where it is absolutely necessary 2 5 Error Handling The KITINSTAL COM file must include an ON WARNING statement to handle errors that might be detected within the kit s procedures or that might be returned by a callback For example VMI FAILURE is a warning status If no housekeeping is needed the ON WARNING statement can exit propagating the status up to the next level ON WARNING TH
150. stem s system specific top level directory This global symbol is equated to the name of the product startup command procedure typically part of SYSTARTUP COM VMSINSTAL uses this logical name to access the statistics file This local symbol equated to X10F 50001 indicates a successful installation VMSINSTAL uses this global symbol to indicate the architecture Alpha AXP or VAX of the system that is running VMSINSTAL This local symbol determines whether or not the input to a callback is in a file This symbol is used for the following callbacks GET SYSTEM_PARAMETER PROVIDE FILE and PROVIDE_IMAGE VMSINSTAL uses this logical name to access the temporary file which in turn reads the patch file VMSINSTAL assigns this process logical name to the file used for terminal operations This process logical name is assigned to the target file in text correction operations This local symbol equated to X10F 50000 indicates that the installation was unsuccessful because it attempted to execute an unsupported feature This symbol is defined as true if the UNWIND callback is invoked This local symbol is used to transfer marker data during the installation This local symbol stores the version number of the operating system This local symbol contains the value of the operating system version level It is used to determine whether or not the product being installed is compatible with the operating system B Sample Op
151. t Release Date if DECRAMSlicense_confirmed then goto license_confirmed j license_err ON ERROR THEN GOTO ERR_EXIT back to normal error mode TYPE SYSSINPUT Wt Ut Ur Ur Ur A license for DECram has not been registered and loaded DECram will not be installed goto DECRAM_NO_INSTALL 5 5 5 DECRAM_AXP_LICENSE ON ERROR THEN GOTO license_err don t quit if license not installed vmiScallback CHECK_LICENSE DECRAM license_confirmed AV DECRAM DEC 1 0 Version updated every release 24 Jun 1991 Product Release Date if DECRAMSlicense_confirmed then goto license_confirmed 1 goto license_err license_confirmed ON ERROR THEN GOTO ERR_EXIT back to normal error mode Slicense_not_confirmed ON WARNING THEN GOTO DECRAM_NOT_INSTALLED Ss TYPE SYSSINPUT B 4 continued on next page Sample OpenVMS Installation Procedure Example B 1 Cont Sample DIGITAL OpenVMS KITINSTAL COM The installation will check for the DECram driver already installed in the system If there is no driver installed in the system you will receive the following message SSYSTEM W NOSUCHDEV no such device available This message can be ignored the installation will proceed normally SHOW DEVICE MD DECRAM_INSTALLED 1 GOTO DECRAM_CONTINUE SDECRAM_NOT_INSTALLED DECRAM_INSTALLED 0 SDECRAM_CONTINUE ON WARNING THEN GOTO ERR_EXIT IF not DECRAM_INSTALLED THEN GOTO DECRAM_
152. tallation It is called from the system startup procedures if a marker file is discovered during booting Step 12 begins by opening a file VMISTERMINAL_FILE to read data input from the terminal It then opens another file VMI MARKER_FILE to read data from the marker data file VMIMARKERpid DAT The data from this file is used to determine the manner in which the recovery will proceed VMSINSTAL does this by assigning values found in the marker file to the following symbols e VMI PRODUCT VMISALTERNATE_ROOT VMSINSTAL Functional Description 4 3 Special Steps e VMISCOMMON_ROOT e VMI SPECIFIC After setting up the default directory and the product working directory step 12 disables the VMSINSTAL purge function and turns off safety mode Next an appropriate message is displayed explaining the situation and providing directions for continuing or discontinuing the installation depending on the state of the installation at the time of the crash as follows e If the system disk was unchanged at the time of the crash the following message is displayed Nothing on your system disk had been changed before the crash Simply begin the installation again e If insignificant changes have been made to the system disk the following message is displayed Although files on your system disk may have been changed the system should be in a usable state Simply begin the installation again e Ifa library was being updated when the cra
153. tem processes If necessary after making the various checks VMSINSTAL warns the installer of any unacceptable conditions and ask if the installer wants to continue This warning is not issued if the installation is under internal Digital QA test Finally after giving the installer an opportunity to back up the current system disk VMSINSTAL goes to step 2 4 2 2 Step 2 In this step VMSINSTAL determines the location of the distribution volume which may or may not be included as the second parameter P2 in the command line If the parameter is omitted VMSINSTAL prompts for it using the ASK callback VMSINSTAL also appends the colon following the device designation if it is omitted UVAX J On VAX systems VMSINSTAL then tests the device designation to determine whether it is configured and to establish the proper processing path If the distribution volume is located on the console device VMSINSTAL connects the console device using SYSGEN dismounts the console volume if it is mounted and allocates the console device for the installation If the device is not properly configured a message is generated saying that the device must be either a disk or tape drive VMSINSTAL Functional Description 4 2 Functional Steps 4 2 3 Step 3 4 2 4 Step 4 4 4 On AXP and VAX systems when VMSINSTAL determines that the device is configured and connected properly it finishes parsing P2 into the symbol VMI PLACE This step is a loop p
154. ter P3 to enter the complete specification of the file being updated option Where applicable use this parameter P4 to specify options by entering the appropriate option letter Currently only the K option is available Use the K option to move the updated file to a location other than that specified in P3 Normally when the update is completed the file is moved back to the system directory When you specify the K option the file is kept in the kit working directory VMI KWD after the update is completed Following is an example of the command line for the UPDATE_FILE callback VMISCALLBACK UPDATE_FILE FORMAT VMISROOT SYSEXE FORMAT EXE The UPDATE_FILE callback returns VMI SUCCESS unless the file is not found or any internal callbacks are unsuccessful 5 34 UPDATE_IDENTIFIER Callback 5 42 The UPDATE_IDENTIFIER callback modifies an identifier in the rights database Use the following command line format to invoke the UPDATE_IDENTIFIER callback VMI CALLBACK UPDATE_IDENTIFIER id name qualifiers Parameters on the command line indicate the following id name Use this parameter P2 to specify the name of the identifier to be modified qualifiers Use this parameter P3 to specify qualifiers for the UPDATE_IDENTIFIER callback You can specify the same qualifiers that are available for the MODIFY IDENTIFIER command of the Authorize utility For more information about the MODIFY IDENTIFIER command see the OpenVMS S
155. tes a STOP command to return control to the user Use the UNWIND callback to exit the installation after errors or Ctrl Y interrupts where the installation is several levels deep into DCL you do not have to return status back up a list of invoked command procedures Use the following command line format to invoke the UNWIND callback VMI CALLBACK UNWIND 5 32 UPDATE_ACCOUNT Callback The UPDATE ACCOUNT callback uses the Authorize utility to update accounts in SYSUAF and NETPROXY It should be used only on accounts created through the CREATE_ACCOUNT callback 5 40 VMSINSTAL Callbacks 5 32 UPDATE_ACCOUNT Callback Use the following command line format to invoke the UPDATE_ACCOUNT callback VMI CALLBACK UPDATE_ACCOUNT username qualifiers Parameters on the command line indicate the following username Use this parameter P2 to identify the account being updated qualifiers Use this parameter P3 to list appropriate qualifiers that is qualifiers related to the AUTHORIZE command MODIFY such as DEVICE and DIRECTORY See the OpenVMS System Management Utilities Reference Manual for more information about the MODIFY command qualifiers Enclose the qualifier string in quotation marks Following is an example of the command line for the UPDATE_ACCOUNT callback VMISCALLBACK UPDATE_ACCOUNT SMITH PASSWORD FCDAUX The UPDATE_ACCOUNT callback returns VMI SUCCESS unless it does not find the SYSUAF file 5 33 UPDATE_FILE Ca
156. tes the image On VAX systems use the following command line format to invoke the RUN_ IMAGE callback VMISCALLBACK RUN_IMAGE image spec input file VMSINSTAL Callbacks 5 26 RUN_IMAGE Callback On AXP systems use the following command line format to invoke the RUN_ AXP IMAGE callback VMI CALLBACK RUN_IMAGE image spec input file option Parameters on the command line indicate the following image spec Use this parameter P2 to specify the required image If the image is not in the kit working directory use a full file specification to identify it input file Use this parameter P3 to specify a file to provide inputs to the image During image execution the callback defines this file as SYS INPUT AXP option On AXP systems use this parameter P4 to specify when image execution should occur Valid values are D Image execution is deferred if the installation is in safety mode e Image executes immediately This is the default The following is an example of an OpenVMS AXP command line for the RUN _ IMAGE callback VMISCALLBACK RUN_IMAGE CHECKTRAN EXE De If the image or a specified input file is not found the callback exits returning VMI _ FAILURE otherwise it returns VMI SUCCESS 5 27 SECURE_FILE Callback The SECURE FILE callback is used to specify the UIC and file protection code for product files Typically you use this callback to restore special security values to a file that has been
157. the facility code for each product with the Digital OpenVMS Product Registrar For more information about product registration see Appendix E 2 2 Save Set Identification Optional OpenVMS software products are distributed in product kits A kit is made up of one or more save sets created by the Backup utility each with a name that reflects the product facility code The file name of each save set must be identical to the product identification string with the addition of a unique file type the sequence identifier that reflects the installation order of the product 2 1 Guidelines and Conventions 2 2 Save Set Identification The first 26 product save set files are assigned file types using alphabetic characters That is you assign file type A to the save set you want installed first file type B to the second and so forth If your product requires more than 26 save sets the additional save sets must begin with VMI_0027 VMI_0028 and so forth ranging from VMI_0027 through VMI_9999 The sequence identifier file type specifies the restoration order for your product save sets and can handle up to 9999 save sets per kit Following is a summary of the save set naming format facvvu s where fac is the facility code vv is the current version number u is the current update number S is the sequence identifier The primary save set save set A must include the KITINSTAL command procedure If release notes are supplied wit
158. the free block count and returns control to the parent process 5 When the installation is completed takes control to turn off the file retention function and report the various block statistics VMSINSTAL Functional Description 4 2 Functional Steps 4 2 7 Step 7 4 2 8 Step 8 4 2 9 Step 9 4 6 6 Reports the files added deleted modified and accessed during the installation 7 When the report is completed the demon returns control to VMSINSTAL VMSINSTAL then checks for the auto answer option A If the A option was specified VMSINSTAL checks for the existence of an auto answer file for the product If an auto answer file exists VMSINSTAL reads it for information relating to installing the product Otherwise VMSINSTAL creates an auto answer file to record information relating to installing the product and generates an appropriate message to the installer If the callback trace option C was selected VMSINSTAL creates a file SYS UPDATE facvvu CBT to contain the trace information Step 7 uses the RESTORE_SAVESET callback to restore the product s primary save set save set A to the kit s working directory When the primary save set is restored VMSINSTAL checks to see if it includes the KITINSTAL command procedure and if the installer selected option N when VMSINSTAL was invoked it checks for the existence of a release notes file fac_wu RELEASE_ NOTES If the restoration fails or if the restored primary
159. the system VMSINSTAL extracts the version number from the image file identification string of the image file associated with the product VMSINSTAL then compares this version number to the minimum version specified in the command line You can use this callback if your product requires the existence of a specific version of another product Use the following command line format to invoke the CHECK_PRODUCT _ VERSION callback VMI CALLBACK CHECK_PRODUCT_VERSION symbol filespec minimum_version option Parameters on the command line indicate the following symbol Use this parameter P2 to specify a global symbol that returns a value of true 1 when the product meets the minimum version requirement specified in P4 When the product does not meet the minimum version requirement this symbol returns a value of false 0 filespec Use this parameter P3 to indicate the full file specification of the prerequisite product s image file This is the file from which VMSINSTAL extracts the version number minimum_version Use this parameter P4 to specify the minimum version required to install your product Specify minimum version using the following format tvv u m where is the type of release for example V for released version T for field test version is the major version number is the update number LISA is the maintenance number For example you might specify the following minimum version V3 0 5 option Use this pa
160. tialization of the installation program VMSINSTAL begins by setting up two symbols one to represent the current version of VMSINSTAL VMI VERSION and one to represent the booting option VMI BOOTING Assuming the program is not in booting mode VMSINSTAL deletes all of the user s currently defined global symbols to avoid any possible conflicts VMSINSTAL executes SYS MESSAGE VMSINSTAL_LANGUAGE COM to define symbols that have been equated to VMSINSTAL internal error messages F or more information about SYS MESSAGE VMSINSTAL_LANGUAGE COM see Section 2 11 VMSINSTAL then displays a welcome message that invites the installer to invoke help by entering a question mark when needed After temporarily disabling the Ctrl Y function VMSINSTAL sets up the installation environment and records the current environment in related symbols Then VMSINSTAL opens a file with the symbol definition VMI TERMINAL _ FILE to read input from the terminal Next VMSINSTAL assigns symbols for both internal use and the product installation procedures and equates a symbol called VMI VMS VERSION to the OpenVMS version running on the target system See Appendix D for more information about the VMI VMS_VERSION symbol VMSINSTAL Functional Description 4 2 Functional Steps After enabling Ctrl Y VMSINSTAL checks for the OPTION keyword in P3 before testing for the booting option If the booting option B is active VMI BOOTING set true VMSINSTAL is attemptin
161. tion 1 3 Invoking VMSINSTAL option list Use this parameter P4 to select VMSINSTAL options by entering the appropriate option letter See Section 1 4 for more information on available options If you list more than one option the letters representing the options must be separated by commas Do not include spaces between letters spaces are interpreted as parameter delimiters The following example of a command line for invoking VMSINSTAL specifies the alternate working device AWD file log L and release notes N options SYSSUPDATE VMSINSTAL TESTO42 DUAO KITS OPTIONS _ AWD DUA2 INSTALL L N This parameter is optional alternate_dir By default VMSINSTAL assumes that the product is to be installed in the common directory of the system on which you are running VMSINSTAL In the following instances you can use this parameter P5 to further qualify the destination for the product software 1 If you select the alternate root option R the product is restored toa common directory in a system disk other than that on which the target system is running In this case P5 must identify the alternate system root using the following form ddcu SYSn where ddcu is the destination disk device SYSn is the top level directory of the alternate system root VMSINSTAL will accept a previously defined logical name for the alternate root 2 If you select the get save set option G to copy the product kit save s
162. to specify a null string in P3 locate Use this parameter P5 to specify how the file is to be located by choosing the appropriate characters from the following list If you list more than one character do not use any intervening spaces e W Look in the kit s working directory for a file with the matching name and type e S Look in the directory specified by the file specification P3 and default P4 parameters e E If the file is not found the callback displays an error message and returns VMI FAILURE status e O Look in the system specific directory 5 15 VMSINSTAL Callbacks 5 12 FIND_FILE Callback symbol Where applicable use this parameter P6 to assign a symbol whose return value will be a single character code from the following list e W Thefile was found in the kit s working directory e S The file was found in the specified directory e E The file was not found and an error was reported e None of the above The following is an example of the command line of the FIND_FILE callback VMISCALLBACK FIND_FILE SYSUAF VMISROOT SYSEXE SYSUAF DAT SE In this example the callback is used to search for the SYSUAF file in the system area A default device directory and type are provided in P4 and the file is assigned the logical name SYSUAF P5 returns an error message sequence if the file is not found Note that you can also use the logical name VMI FIND to invoke the FIND_FILE ca
163. told that the installation was completed satisfactorily 2 Guidelines and Conventions This chapter describes guidelines and conventions for developing products to be installed with VMSINSTAL All VMSINSTAL users should closely adhere to the product naming conventions presented in the sections that follow 2 1 Product Identification String Each software product must be identified by a product identification string The product identification string consists of the facility code fac the version number vv and the update number u The facility code can have up to 36 alphanumeric characters The following example gives the format of the product identification string facvvu where fac is the facility code vv is the current version number u is the current update number For example you would identify Version 1 1 of a product named TEST as TESTO11 As new versions and updates of your product are released they must be assigned a new product identification string that reflects the current version and update For example the next update after CHECKTRAN Version 1 1 would be assigned the product identification string CHECKTRANO12 Do not give your product the name of an existing product or component on the target system You can check the names of existing system and user images by entering the following DCL command DIRECTORY SYSSSYSTEM EXE To avoid potential conflicts with other layered products you must register
164. uns the CHECKSUM program on the file If the checksum agrees with the value in P6 the callback invokes the SUMSLP editor to edit the file It then uses the UPDATE_LIBRARY callback to put the new version of the file in the library Use the following command format line to invoke the SUMSLP_TEXT callback VMI CALLBACK SUMSLP_TEXT logical edit file target type current checksum new checksum option VMSINSTAL Callbacks 5 29 SUMSLP_TEXT Callback Parameters on the command line indicate the following logical Use this parameter P2 to assign a logical name to the file or library module being edited Use the logical name in all subsequent references to the file or library module edit file Use this parameter P3 to specify the name and type of the editing file Do not specify the device or directory because the callback assumes that the file is located in the installation working directory To save disk space you can delete this file after the callback returns target If the callback is editing a file use this parameter P4 to specify the file being edited If the callback is editing a library module use this parameter to identify the target by entering the full library specification followed by a comma and then the name of the library module For example if the callback is editing the CONVERT module in the help library enter the following line VMISROOT SYSHLP HELPLIB HLB CONVERT type If the callback is editing a
165. ut file for a product named TEST PROVIDE_FILE data file TEST_FREDE FREDE TXT VMISROOT TEST_FREDC FREDC COM VMISROOT TEST_FREDH FREDH DAT VMISROOT SYSHLP TEST_FREDM FREDM NTS VMISROOT SYSLIB SYSEXE Following are examples of command lines that invoke the SET_FILE option VMISCALLBACK SET_FIL VMISCALLBACK SET_FIL This SET_FILE option returns VMI FAILURE if the file is not found otherwise it returns VMI SUCCESS 5 28 4 SET IVP Option The SET IVP option specifies whether an Installation Verification Procedure IVP is to be used with the product installation assuming that the product includes an IVP If you do not enter a SET IVP command VMSINSTAL specifies that the IVP does not run VMISROOT SYSUPD DUMMY DAT VERSION 2 ERASE FILE LIST DAT T F ay F a Use the following command line format to invoke the SET IVP option VMI CALLBACK SET IVP keyword help 5 32 VMSINSTAL Callbacks 5 28 SET Callback The parameters on the command line indicate the following keyword Use this parameter P3 to make the appropriate selection from the following list e ASK Use this keyword to prompt the installer for a decision on whether to run the IVP If help is specified in P4 the prompt is prefaced by a help message The IVP will run if the installer responds by entering a YES or presses the Return key e YES Usethis keyword to specify that the IVP will run at the completio
166. y AXP On AXP systems the SET_FILE option applies the passed qualifiers for the specified file Use the following command line format to invoke the SET_FILE option SET_FILE file spec qualifiers options 5 31 VMSINSTAL Callbacks 5 28 SET Callback Parameters on the command line indicate the following file_spec Use this parameter P2 to specify the full file specification qualifiers Use this parameter P3 to specify qualifiers Enclose a list of qualifiers in quotation marks options Where applicable use this parameter P4 to specify the following option e T Use this option to indicate that the file spec parameter represents a data file that contains the input file and qualifier information This option offers faster file processing however the system does not return file specific error messages That is if there is an error in one of the files listed in the input file the system only returns the general message File Not Found rather than identifying the specific file that contains the error The input file must conform to the following rules The file must reside in VMI KWD Each source file entry must use the same format as the command line as follows logical filename_type destination options Each source file entry must be on a separate line in the input file You can include comment lines and blank lines in the input file The following is an example of the contents of an inp
167. ystem Management Utilities Reference Manual Following is an example of a command line that invokes the UPDATE _ IDENTIFIER callback VMISCALLBACK UPDATE_IDENTIFIER ACCOUNTING VALUE UIC 300 21 In this example the UPDATE_IDENTIFIER callback specifies a new value for the ACCOUNTING identifier This callback returns VMI SUCCESS if the identifier is successfully modified The callback returns VMI FAILURE if the identifier is not successfully modified VMSINSTAL Callbacks 5 35 UPDATE_LIBRARY Callback 5 35 UPDATE_LIBRARY Callback The UPDATE_LIBRARY callback is used to immediately update an existing library It can be used with either the OpenVMS Librarian or the RSX LBR utility The callback records the update in the marker file immediately to aid in crash recovery procedures if needed Use the following command line format to invoke the UPDATE_LIBRARY callback VMI CALLBACK UPDATE_LIBRARY logical filespec type qualifiers source_file Parameters on the command line indicate the following logical Use this parameter P2 to assign a process logical name to the library file being updated Use the logical name in all subsequent references to the file filespec Use this parameter P3 to enter the complete specification of the library file being updated type Use this parameter P4 to enter the LIBRARY command qualifier that identifies the type of library being updated If an RSX library is being updated enter RSX

OpenVMS Developer`s Guide to VMSINSTAL

Contents

Download Pdf Manuals

Related Search

Related Contents