26 May 86 lars@ACC-SB-UNIX.ARPA (Lars Poulsen)
How to build VMSINSTAL compatible software distribution kits

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 tAm0 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"

26 May 86 allegra!yetti!eriks@seismo.CSS.GOV (Eriks Rugelis)
RE: Toggle Interactive/Detached


> I am interested in making a detached process appear to be an interactive
> process that is visible via $ show user. That process then should receive
> messages sent to him using sys$brkthru. Is that possible and has somebody
> already written a routine modifying it?
> And how, on the other hand can an interactive process be made detached, wherea
s
> in reality it is still connected to a terminal with a user?
>
> Christoph Gatzka                <ZRPLIB3@DTUZDV5A> in Bitnet

here at york, we have been working on at least part of what you want...
in our case, I need a process that is not attached to a physical terminal
thus does not waste a terminal port but is still capable of responding
in some intelligent fashion to broadcast messages

We've been experimenting with Kevin Carosso's PTYdriver (pseudo-terminal)
with some success...  we're just trying to get opcom to recognize a pty
as a legitimate terminal so that we can trap and react to opcom messages

It isn't working quite yet but I fully expect that it will in the very near
future

If you are interested in the final result send me mail and I'll send you
a copy of the finished hack

p.s.  the PTYdriver is a really neat piece of code and was submitted to
at least two u.s. decus tapes..  it still works under vms 4.3.. take that
as a good omen

          Voice: Eriks Rugelis
        Ma Bell: 416/736-5257 x.2688
     Electronic: {allegra|decvax|ihnp4|linus}!utzoo!yetti!eriks.UUCP
              or eriks@yulibra.BITNET