    
    
    
                             SETUP User's Guide
    
                              Matthew Madison
                  Center for Interactive Computer Graphics
                      Rensselaer Polytechnic Institute
                               Troy, New York
    
    
    Introduction
    
    If you run many third-party applications on your VAX/VMS system, you 
    have probably had to contend with the problems of getting these 
    applications "set up" for users: defining the right logical names, 
    setting up commands or symbols, etc.
    
    Not all users necessarily need to have all applications set up for 
    them, so placing the startup commands in the SYS$SYLOGIN command 
    procedure is generally a bad idea.  But users don't want to have to 
    know some obscure commands in order to be able to setup the 
    applications they want.  Also, some applications require some sort 
    of one-time initialization before the packages can be used.
    
    SETUP is a utility that centralizes application setup operations, 
    making it easier for users to set up the applications they need.
    
    
    Installing SETUP
    
    SETUP is a single executable file which should be installed in 
    SYS$SYSTEM or some other directory in which you store command 
    images.  You can make it accessible to users in one of two ways:
    
    	 1.   Define a foreign command in SYS$SYLOGIN, such as:
    
    	       $ setup :== $setup				       
    
    	 2.   Create a CLD file with the following commands to add SETUP to 
           your system-wide DCLTABLES:
    
    	       DEFINE VERB SETUP
    	       IMAGE "SETUP"
    	       PARAMETER P1,VALUE(TYPE=$REST_OF_LINE)
    
    A help file is included with SETUP that can be added to your help 
    library.
    
    
    Defining Applications
    
    SETUP gets its information about applications from a file called 
    SETUP_CMDS.DAT.  By default, SETUP looks for that file in the 
    directory RPI$ROOT:[SETUP], but by defining a logical name called 
    SETUP_CMDS, you can put the file anywhere you'd like.  The 
    SETUP_CMDS file contains APPLICATION definitions, which have the 
    form:
    
         APPLICATION appl-name
               /SETUP=setup-cmd
               /INITIAL=initial-setup-cmd
               /DESCRIPTION=description
               /ACCESS=access-control-list
    
    "appl-name" is some character string identifying the application.  
    The /SETUP qualifier defines the command to be used when the user 
    sets up the application.  The /INITIAL qualifier defines the command 
    to be used when the user requests a one-time initial application 
    setup.  The text specified with the /DESCRIPTION qualifier is 
    displayed when the user requests a SETUP/LIST/FULL.  The /ACCESS 
    qualifier can be used to prevent access to application setup 
    information (see "Access Control", below).
    
    These APPLICATION definitions are parsed by the DCL command-line 
    interpreter, so all DCL syntax rules apply.  Note that you need not 
    include any of the qualifiers (though excluding the /SETUP and the 
    /INITIAL qualifiers at the same time doesn't make much sense).
    
    
    The SETUP command
    
    The user types the SETUP command to gain access to the information 
    in the SETUP_CMDS file.  The SETUP command has the following format:
    
         SETUP appl-name
               /LIST
               /FULL
               /INITIAL
    
    The appl-name the user types must match an application name in the 
    SETUP_CMDS file exactly for the appropriate setup command to be 
    executed.  The /LIST qualifier can be used to display a list of 
    available applications; adding /FULL also displays the application 
    descriptions.  For /LIST, the appl-name may contain wildcards (if 
    omitted, it defaults to "*").  The /INITIAL qualifier selects the 
    one-time setup command for the specified application.
    
    SETUP looks through the APPLICATION definitions in the SETUP_CMDS 
    file sequentially until the application name matches.  SETUP/LIST 
    uses all the APPLICATION definitions.  You might want to order your 
    APPLICATION definitions either (a) most-used first, for speed, or 
    (b) in alphabetical order, for a more easily understood listing.
    
    
    Access Control
    
    You can control access to application setup information by using the 
    /ACCESS qualifier on application definitions.  This qualifier takes 
    as its value an access control list.  The access control list should 
    contain identifier ACE's which grant EXECUTE and/or READ access.  
    EXECUTE access is required to execute the SETUP command for that 
    application.  READ access is required to be able to list that 
    application's name in a SETUP/LIST command.  READ access also 
    implies EXECUTE access.
    
    If you do not use the /ACCESS qualifier, access is assumed to be 
    granted for any operation.  If you do use /ACCESS, access is assumed 
    to be denied unless granted by an ACE in the ACL.
    
    Note that using /ACCESS can significantly slow the operation of 
    SETUP, since the ACL must be parsed and checked.
    
    Also note that using /ACCESS to protect setup information is not 
    effective unless the SETUP_CMDS file is also protected.  If you want 
    to use /ACCESS, you should make sure the SETUP_CMDS file is 
    protected such that WORLD has no access to the file.  Then you 
    should INSTALL SETUP.EXE with SYSPRV (or READALL) privilege to allow 
    access to SETUP_CMDS through the SETUP program.
    
    Contacting the Author
    
    Comments, suggestions, and questions about SETUP can be directed to 
    the author via electronic mail at one of the following addresses:
    
    Internet: madison@cicgj.rpi.edu
    BITNET:   madison@rpicicge
    
    
    Copyright Notice
    
    COPYRIGHT © 1988, RENSSELAER POLYTECHNIC INSTITUTE.  ALL RIGHTS 
    RESERVED.  Permission is given to redistribute this software for 
    non-commercial purposes provided no there is no charge for the 
    distribution beyond handling and materials costs.
    
    DISCLAIMER: This software is provided "as is".  Neither the author 
    nor Rensselaer Polytechnic Institute makes any guarantee as to the 
    suitability, usefulness, performance, or security of the software.
    
