lars@ACC-SB-UNIX.ARPA.UUCP (05/24/86)
VMS contains a wonderful tool for well-defined installation of
layered software products. Unfortunately, VMSINSTAL is not very
well documented from the software developer's point of view in
the VMS reference documentation. However, the MicroVMS User's Manual
(which is a single binder substituting for the whole VMS document
kit) has some stuff about it.
I thought it might be a GOOD THING to have everybody use VMSINSTAL
compatible distribution kit, so here is a very practical hands-on
how-to guide to using the VMSINSTAL tools, along with actual working
DCL examples.
This is abstracted from an internal ACC document, but no assumptions should
be made about the actual relationship of this to any ACC products.
This technical note was written by Peggy Cornell <Peggy@ACC.ARPA>
--------------------------------------------------------------------------
#86-001 March 12, 1986 ACC TECHNICAL NOTES
TITLE
Software Distribution Kits
ABSTRACT
Prior to submitting software to the library, a software distribution
kit should be created which will enable a software distribution "save
set" to be created, the installation of the software, and provide a
means to ensure that the installation was successful. This note
describes what needs to be done.
KEYWORDS
save set, backup, VMSINSTAL
DESCRIPTION
Software products supplied by ACC for execution on a VMS system
should observe certain standards so they can be uniformly built and
installed. When submitting the software to the library, a software
distribution kit should be provided which consists of:
1. A command procedure to create a BACKUP save set.
2. A KITINSTAL command procedure which will perform the
installation of the product.
3. An Installation Verification Procedure (IVP) which
exercises the product (and hence verifies that the
installation was successful) and displays or writes
results.
A BACKUP save set contains all the files to be shipped to the
customer. It includes the KITINSTAL command procedure, the IVP, all
the source files provided to the customer, and any executable code
provided to the customer. This memo will discuss how to create a
save set on tape, and will show a sample KITINSTAL.COM and IVP.
CREATING_A_SAVE_SET
VMS provides a command procedure called SPKITBLD.COM to build a new
product kit for you. The steps to use the SPKITBLD.COM follow:
1. Copy all files to be contained in the save set to
the same directory.
2. Log in to the SYSTEM account
3. Invoke SPKITBLD.COM as follows:
@SYS$UPDATE:SPKITBLD
The message "Software Product Kit Build Procedure" appears.
4. In response to the prompt: "Which kit would you like to build?"
specify the name of the kit. The kit name must be in the format
facvvu, where fac is the name of the facility (up to six
characters), vv is the version number, and u is the update number.
In the following examples, fac is defined as A6100V, vv is 02,
and u is zero (for revision 2.0). Thus the name of the kit is
A6100V020. The save set will be named A6100V020.A.
NOTE: The names of the first 26 save sets must consist of
consecutive letters of the alphabet starting with A. Thus, if
two save sets were needed, they would be named A6100V020.A and
A6100V020.B.
5. In response to the prompt: "On which device is the kit to be
built?", specify the device; for example: MSA0:
6. In response to the prompt: "Which files?", give the path to the
directory containing the files to be placed on the save set
followed by *.* to show that all files in that directory
belong in the save set; example:
u:[username.subdir.savedir]*.*
7. Answer all other prompts until all save sets have been created.
The message "Kit Build Completed Successfully" indicates
a successful product kit build.
When submitting the software distribution kit to the library, a
command procedure should be used to copy the files to the desired
directory and build the save set. In the example that follows, the
command
Backup/BLOCK_SIZE=2048/list [.A6100V020]*.* A6100V020.A/SAVESET
takes the files in the sub-directory [.A6100V020], and places them in
the save set A6100V020.A on disk. The qualifier must be specified
when the output save set refers to a backup save set on a disk. The
command
Backup/Rewind/Interchange/Block=2048/Verify/List [.A6100V020]*.* -
MSA0:A6100V020.A
creates the save set on tape.
$! COMMAND PROCEDURE TO COPY FILES INTO A DIRECTORY AND
$! CREATE A SAVE SET ON TAPE
$!
$!
$! Move required files from library entries to distribution kit
$ Project UPBHDLC
$ Set default Project:[UPBHDLC.SUBMIT.DISTKIT]
$ Set Noon
$ Delete A6100V020.A;*
$ Delete [.A6100V020]*.*;*
$ Set Prot=(Ow:RWED,Wo:RWED) A6100V020.dir
$ Delete A6100V020.DIR;*
$ Set On
$ Define P4300037 'F$PARSE("[-.UMCRESET]",,,"DIRECTORY")'
$ Define P4300205 'F$PARSE("[-.KITINSTAL]",,,"DIRECTORY")'
$ Define P4400267 'F$PARSE("[-.ACP6100T1]",,,"DIRECTORY")'
$ Define P4400332 'F$PARSE("[-.ACP6100T2]",,,"DIRECTORY")'
$ Define P4400333 'F$PARSE("[-.CIFHDR]",,,"DIRECTORY")'
$ Define P4400328 'F$PARSE("[-.PMDRIVER]",,,"DIRECTORY")'
$ Define P4400329 'F$PARSE("[-.UADRIVER]",,,"DIRECTORY")'
$ Create/Directory [.A6100V020]
$ Copy/Log P4300205:KITINSTAL.COM [.A6100V020]
$ Copy/Log P4400328:PMDRIVER.MAR [.A6100V020]
$ Copy/Log P4400328:PMSTRUCT.MAR [.A6100V020]
$ Library/Create/Macro/List [.A6100V020]PMSTRUCT [.A6100V020]PMSTRUCT
$ Copy/Log P4400329:UADRIVER.MAR [.A6100V020]
$ Copy/Log P4300037:UMCRESET.C,.EXE [.A6100v020]
$ Copy/Log P4400267:ACP6100T1.C [.A6100V020]
$ Copy/Log P4400267:ACP6100T1.EXE [.A6100V020]
$ Copy/Log P4400332:ACP6100T2.EXE [.A6100V020]
$ Copy/Log P4400333:CIF.H [.A6100V020]
$ Directory/Date/Size [.A6100V020]
$ Backup/BLOCK_SIZE=2048/List [.A6100V020]*.* A6100V020.A/SAVESET
$ Mount/Foreign MSA0:
$ Backup/Rewind/Interchange/Block=2048/Verify/List [.A6100V020]*.* MSA0:A6100V020.A
$ Logout
VMSINSTAL_FOR_INSTALLING_AND_TESTING_THE_SOFTWARE_PACKAGE
The following steps are necessary to install the support software
package on a VAX/VMS system:
1. Log in as SYSTEM
2. Invoke the system update procedure thus:
@SYS$UPDATE:VMSINSTAL A6100V MTAO:
3. To have the installation automatically verified using
a provided IVP, answer "YES" when asked if you want to
run the IVP after the installation.
VMSINSTAL creates a "kit working directory" and loads into it the
files from save set A of the installation kit. This is the save set
A6100V020.A. You will notice that the product name given in the
command above is given as A6100V. Specifying just the product name
will install all updates and versions of a product in order. MSA0:
specifies the name of the device (in this case the tape name)
containing the installation kit. Thus the command above installs
Version 2.0 of a product named A6100V from a tape called MSA0:.
As VMSINSTAL runs, you will receive messages and be required to make
responses. Type your response and press RETURN. The default reply
which appears in brackets will be used if you simply press RETURN.
During an installation, KITINSTAL is invoked once by VMSINSTAL to
perform the actual installation, and then is invoked a second time to
test the installation. The first situation is handled with an
installation procedure and the second with an installation
verification procedure (IVP).
INSTALLING_THE_SOFTWARE_PACKAGE_ON_THE_VAX/VMS_SYSTEM
Following is an example of a KITINSTAL.COM which was created for the
ACP 6100 project. It builds two drivers, creates two command
procedures which load the drivers, and moves the files to the proper
directories.
$! KITINSTAL.COM for VMS Port/Class Drivers
$!
$ ACP$NAME = "ACP6100"
$ ACP$PORT = "PM"
$ ACP$CLASS = "UA"
$ KIT$IVP = "''ACP$NAME'T1"
$ KIT$EXER = "''ACP$NAME'T2"
$ ACP$TESTNAME = "ACP6100" ! Logical name referenced by IVP
$!
$ On Control_Y Then VMI$CALLBACK Control_Y
$ On Warning Then Exit $Status
$ If P1 .eqs. "VMI$_INSTALL" Then Goto Install
$ If P1 .eqs. "VMI$_IVP" Then Goto IVP
$ Write SYS$OUTPUT "Option ''P1' Not Supported"
$ Exit VMI$_UNSUPPORTED
$!
$Install:
$ Set Default VMI$KWD
$ VMI$CALLBACK CHECK_NET_UTILIZATION KIT$SPACE 1500
$ If .not. KIT$SPACE Then VMI$CALLBACK MESSAGE E -
NOSPACE "This kit requires at least 1500 free blocks"
$ VMI$CALLBACK SET IVP ASK
$ VMI$CALLBACK SET PURGE ASK
$ VMI$CALLBACK SET SAFETY CONDITIONAL 1000
$ VMI$CALLBACK ASK KIT$DEFAULT "Is a default installation adequate" "YES" B -
"See the ''ACP$NAME' User's Manual (VMS Software Installation)"
$ If KIT$DEFAULT Then skip_port = "N"
$ If KIT$DEFAULT Then KIT$MIXED = "N"
$ If .not. KIT$DEFAULT Then VMI$CALLBACK ASK KIT$MIXED -
"Do you need to support mixed device types" NO B
$ If .not. KIT$MIXED Then -
VMI$CALLBACK ASK KIT$N_UNITS "How many ''ACP$NAME' are to be supported" 1 I
$ If .not. KIT$MIXED Then skip_port = "NO"
$ If KIT$MIXED Then VMI$CALLBACK ASK skip_port -
"Have you already built the physical port driver" "NO" B
$ If skip_port Then goto Build_Class
$!
$ ! Assemble and link the Port Driver
$ ! Assume that the necessary files are in the current directory
$ ! and leave the driver image in the current directory.
$!
$Build_Port:
$ KIT$PORT = ACP$PORT
$ If .not. KIT$DEFAULT Then -
VMI$CALLBACK ASK KIT$PORT "Port driver prefix" 'ACP$PORT' S
$ Write SYS$OUTPUT " Assembling ''KIT$PORT'DRIVER ..."
$ MACRO /OBJ='ACP$PORT'DRIVER/EN=SUPP -
'ACP$PORT'DRIVER+PMSTRUCT/LIBRARY+SYS$LIBRARY:LIB.MLB/LIBRARY
$ Write SYS$OUTPUT " Linking (ignore transfer address warning)"
$ On Warning then Continue
$ LINK /NOTRACE /MAP -
/EXE='KIT$PORT'DRIVER -
'ACP$PORT'DRIVER,SYS$INPUT/OPTIONS,SYS$SYSTEM:SYS.STB/SELECTIVE
BASE=0
$ On Warning Then Exit $Status
$ Write SYS$OUTPUT ""
$Build_Class:
$ KIT$CLASS = ACP$CLASS
$ If .not. KIT$DEFAULT Then -
VMI$CALLBACK ASK KIT$CLASS "Class driver prefix" 'ACP$CLASS' S
$ Write SYS$OUTPUT " Assembling ''KIT$CLASS'DRIVER ..."
$ MACRO /OBJ='ACP$CLASS'DRIVER/EN=SUPP -
'ACP$CLASS'DRIVER+PMSTRUCT/LIBRARY+SYS$LIBRARY:LIB.MLB/LIBRARY
$ Write SYS$OUTPUT " Linking (ignore transfer address warning)"
$ On Warning then Continue
$ LINK /NOTRACE /MAP -
/EXE='KIT$CLASS'DRIVER -
'ACP$CLASS'DRIVER,SYS$INPUT/OPTIONS,SYS$SYSTEM:SYS.STB/SELECTIVE
BASE=0
$ On Warning Then Exit $Status
$ Write SYS$OUTPUT ""
$!
$!
$ If skip_port Then Goto Class_Config
$ Port_Conn = "''KIT$PORT'CONN.COM"
$ Write SYS$OUTPUT "Configure hardware ... build ''Port_Conn'"
$ If KIT$MIXED Then -
VMI$CALLBACK ASK KIT$N_UNITS -
"How many physical ports are to be supported" 1 I
$ Open/Write Port_Conn 'Port_Conn'
$ Write Port_Conn "$ MCR SYSGEN"
$ Units = 1
$ Letters = "@ABCDEFGHIJKLMNOPQRSTUVWXYZ"
$ Def_CSR = "766740"
$ Def_vec = "410"
$NEXT_PORT:
$ PORT$NAME = KIT$PORT+F$extract(Units,1,Letters)
$ DEV$CSR = Def_CSR
$ DEV$VEC = Def_VEC
$ DEV$UBA = "UB0"
$ If KIT$DEFAULT Then Goto UBA_IS_OK
$ GET_DEV_CSR:
$ !
$ VMI$CALLBACK ASK DEV$CSR -
"Address of CSR for ''ACP$NAME' ''PORT$NAME'" 'Def_CSR' S,Z
$ IF F$LENGTH(DEV$CSR) .NE. 6 THEN GOTO CSR_IS_NOT_OK
$ I = F$integer("%O"+DEV$CSR)
$ If (I-((I/%O40)*%O40)) .ne. 0 Then Goto CSR_IS_NOT_OK
$ IF F$EXTRACT(0,2,DEV$CSR) .EQS. "77" THEN GOTO CSR_IS_OK
$ IF F$EXTRACT(0,2,DEV$CSR) .EQS. "76" THEN GOTO CSR_IS_OK
$ !
$CSR_IS_NOT_OK:
$ WRITE SYS$OUTPUT "That is not a valid CSR value, try again."
$ WRITE SYS$OUTPUT ""
$ GOTO NEXT_PORT
$ !
$CSR_IS_OK:
$ !
$ VMI$CALLBACK ASK DEV$VEC -
"Address of Vector for this ''ACP$NAME'" 'Def_vec' S,Z
$ IF DEV$VEC .EQS. "^Z" THEN Goto NEXT_PORT
$ IF F$LENGTH(DEV$VEC) .NE. 3 THEN Goto Bad_vector
$ I = F$INTEGER("%O"+DEV$VEC)
$ IF I .GT. %O1000 THEN Goto Bad_Vector
$ IF I .EQ. %O0 THEN Goto Bad_Vector
$ IF (I-((I/4)*4)) .EQ. 0 THEN GOTO VEC_IS_OK
$Bad_Vector:
$ Write Sys$output "Invalid Vector value, try again"
$ Goto NEXT_PORT
$Vec_is_OK:
$ !
$ VMI$CALLBACK ASK DEV$UBA -
"''ACP$NAME' ''PORT$NAME' is used with which Unibus Adapter" -
UB0 S,Z
$ IF DEV$UBA .EQS. "^Z" THEN GOTO NEXT_PORT
$ IF F$LENGTH(DEV$UBA) .NE. 3 THEN GOTO UBA_IS_NOT_OK
$ IF DEV$UBA .EQS. "UB0" THEN GOTO UBA_IS_OK
$ IF DEV$UBA .EQS. "UB1" THEN GOTO UBA_IS_OK
$ !
$ UBA_IS_NOT_OK:
$ WRITE SYS$OUTPUT "That is not a valid UBA value, try again."
$ WRITE SYS$OUTPUT ""
$ Goto NEXT_PORT
$ !
$UBA_IS_OK:
$ If KIT$DEFAULT Then Write SYS$OUTPUT -
"+++ ''PORT$NAME'0: CSR=%o''DEV$CSR' Vector=%o''DEV$VEC' on UB0 +++"
$ Write Port_Conn -
" Connect ''PORT$NAME'0/DRIVER=''KIT$PORT'DRIVER -"
$ Write Port_Conn -
" /Adapter=''DEV$UBA'/CSR=%o''DEV$CSR'/Vector=%o''DEV$VEC'/Numvec=2"
$ If Units.eq.KIT$N_UNITS Then Goto End_Port_Config
$ Units = Units+1
$ Def_CSR = F$fao("!6OL",F$integer("%O"+DEV$CSR)+%O40)
$ Def_vec = F$fao("!3OW",F$integer("%O"+DEV$VEC)+%O10)
$ Goto NEXT_PORT
$End_Port_Config:
$ Close Port_Conn
$Class_Config:
$ Class_Conn = "''KIT$CLASS'CONN.COM"
$ Write SYS$OUTPUT "Configure hardware ... build ''Class_Conn'"
$ If KIT$MIXED Then -
VMI$CALLBACK ASK KIT$N_UNITS "How many ''ACP$NAME' are to be supported" 1 I
$ Open/Write Class_Conn 'Class_Conn'
$ Open/Write Kit_IVP 'KIT$IVP'.COM
$ Write Kit_IVP "$! ---------------------------------- "
$ Units = 1
$NEXT_UNIT:
$ DEV$NAME = KIT$CLASS+F$extract(Units,1,Letters)
$ PORT$NAME = KIT$PORT+F$extract(Units,1,Letters)
$ If KIT$MIXED Then -
VMI$CALLBACK ASK PORT$NAME -
"Which port does ''DEV$NAME' connect to" -
PORT$NAME S -
"Format is PMx (no 0, no :)"
$ If F$length(PORT$NAME).ne.3 Then Goto NEXT_UNIT
$ Write Class_Conn "$ Define ''DEV$NAME'_PORT_FAC ''PORT$NAME':03"
$ Write Class_Conn "$ MCR SYSGEN"
$ Write Class_Conn "Connect ''DEV$NAME'/NOADAPTER"
$ Write Kit_IVP "$ Define ''ACP$TESTNAME' ''DEV$NAME'0:"
$ Write Kit_IVP "$ Run Sys$test:''KIT$IVP'"
$ Write Kit_IVP "$ Deassign ''ACP$TESTNAME'"
$ If Units.eq.KIT$N_UNITS Then Goto End_Class_Config
$ Units = Units+1
$ Goto NEXT_UNIT
$End_Class_Config:
$ Close Class_Conn
$ Write Kit_IVP "$! ---------------------------------- "
$ Close Kit_IVP
$ Write Sys$output -
"You will need to edit SYS$MANAGER:SYCONFIG to include the line(s):"
$ If .not. skip_port Then -
Write Sys$output " @SYS$MANAGER:''Port_Conn'"
$ Write Sys$output " @SYS$MANAGER:''Class_Conn'"
$!
$! Move files to their destination
$!
$ If KIT$DEFAULT Then Goto Provide_files
$ VMI$CALLBACK ASK Normal_files -
"Should all files be placed in their default locations" "YES" B
$ If Normal_files Then Goto Provide_files
$ Create/Directory [-.A6100V]
$ Copy *.* [-.A6100V]
$ Exit VMI$_SUCCESS
$Provide_files:
$ VMI$CALLBACK PROVIDE_IMAGE PORT_DRIVER 'KIT$PORT'DRIVER.EXE -
VMI$ROOT:[SYSEXE]
$ VMI$CALLBACK PROVIDE_IMAGE CLASS_DRIVER 'KIT$CLASS'DRIVER.EXE -
VMI$ROOT:[SYSEXE]
$ VMI$CALLBACK PROVIDE_FILE UMC_RESET UMCRESET.EXE VMI$ROOT:[SYSMGR]
$ VMI$CALLBACK PROVIDE_FILE PORT_CONNECT 'Port_Conn' VMI$ROOT:[SYSMGR]
$ VMI$CALLBACK PROVIDE_FILE CLASS_CONNECT 'Class_Conn' VMI$ROOT:[SYSMGR]
$ VMI$CALLBACK PROVIDE_IMAGE KIT$IVP 'KIT$IVP'.EXE VMI$ROOT:[SYSTEST]
$ VMI$CALLBACK PROVIDE_FILE KIT$IVPCOM 'KIT$IVP'.COM VMI$ROOT:[SYSTEST]
$ VMI$CALLBACK PROVIDE_FILE KIT$EXER 'KIT$EXER'.EXE VMI$ROOT:[SYSTEST]
$ VMI$CALLBACK PROVIDE_FILE KIT$CIF_H CIF.H VMI$ROOT:[SYSHLP.EXAMPLES]
$ VMI$CALLBACK PROVIDE_FILE KIT$IVPC 'KIT$IVP'.C VMI$ROOT:[SYSHLP.EXAMPLES]
$ VMI$CALLBACK PROVIDE_FILE UMC_RESETC UMCRESET.C VMI$ROOT:[SYSHLP.EXAMPLES]
$!
$ Exit VMI$_SUCCESS
$!
$! IVP is Installation Verification Procedure
$!
$IVP:
$ @SYS$MANAGER:PMCONN.COM
$ @SYS$MANAGER:UACONN.COM
$ Write SYS$OUTPUT -
"Verifying installation of ''ACP$NAME' using following command file:"
$ Type SYS$TEST:'KIT$IVP'.COM
$@SYS$TEST:'KIT$IVP'
$ Exit VMI$_SUCCESS
VERIFYING_THE_SOFTWARE_PACKAGE_ON_THE_VAX/VMS_SYSTEM
Following is an example of a installation verification program which
was created for the XXXXXXXX project. It establishes communication
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXX to ensure that the system works.
/* ACP6100T1.C
* Installation Verification Procedure and Sample Application
* Program for ACP6100 connected via VMS UADRIVER/PMDRIVER
.... 700 lines of sample code deleted ....
SEE ALSO
MicroVMS User's Manual - Chapter 3
"Product Integration"