Child pages
  • State Software Installation Procedure
Skip to end of metadata
Go to start of metadata

Introduction

The primary purpose of the State software installation procedure is to simplify and standardize the installation process. This procedure is modeled after Digital's VMSINSTAL procedure.

The installation process was designed to provide the following capabilities and benefits:

  • Completely automated installation
  • All files are placed in the proper distribution directory
  • Automatic LINK'ing of objects on target system
  • Automatic determination of architecture (AXP or I64) and handles differences in installation

The OECN_INSTALL procedure will not attempt to move the installed programsinto your execution directories, (e.g. OECN$BUD: or OECN$PAY: ). This means that you may safely execute OECN_INSTALL without affecting current interactive users. See Section 1.6 for information about post installation procedures and installing programs into the shared execution directories.

Sites which have both i64 and Alpha systems must run OECN_INSTALL on both systems. Even if the systems are part of a mixed architecture cluster, OECN_INSTALL must be executed on each architecture.

Distribution Kit

The OECN State Software is distributed as a series of backup savesets. Please read the Acquiring the Release page for specific details on how to download the backup savesets.

The files included in the kit consist of a number of required savesets and optional package savesets. The required savesets must be available at the time that OECN_INSTALL is executed. You cannot invoke OECN_INSTALL to install an individual package unless the required savesets are also available.

Each package has at least one saveset which contains common files, such as documentation, documentation and command procedures. If the package also contains executable images, then there will be two additional savesets which contain the I64 and Alpha specific files. These savesets will be named with a _I64 or _AXP suffix. Each site will receive one or both of these savesets depending on the platforms in use at that site.

To install a given package, the common saveset and the appropriate platform specific saveset must both be available when running OECN_INSTALL. If one or the other saveset is missing, then the installation will fail.

It is very important that both the common and platform specific saveset be available during installation. For example, when installing USAS61 on AXP then USAS61.ZIP and USAS61_AXP.ZIP must be available. When installing the same package on I64, then USAS61.ZIP and USAS61_I64.ZIP must be available.

The following table lists the savesets included in a typical distribution and indicates whether they are required and includes a platform specific saveset.

Saveset Required Platform Specific Description

UTIL

Yes

No

Files for OECN$UTL. Includes files which control installation of packages on current release

COBLIB

Yes

Yes

Cobol, Object and Sharable image Libraries

DOCS

No

No

General Documentation

TRAINING

No

No

Training packages and documentation

xxxxvv

No

Yes

Each package is named xxxxxvv where xxxx is the acronym for the package and vv is the version number (e.g. USPS40)

Execution

To begin the installation process, enter the following:

$ @OECN$UTL:OECN_INSTALL [device] [OPTIONS option]

where device is an optional parameter specifying the device where the distribution media is located. The device may be a tape device or a device/directory name. If not specified the procedure will prompt for it.

The next optional parameter is the word "OPTIONS" indicating an option is being specified. The third parameter is the option affecting the behavior of the installation.

If an option is specified, then the word "OPTIONS" must be specified in parameter two. This helps prevent operator error and is consistent with VMSINSTAL. See the section below for more information about options.

The procedure will begin prompting for information necessary to perform the installation. See below for a sample run. Enter a question mark (question) at any prompt for help.

Initial Installation

The first time you receive a distribution using the installation procedure, you will have to perform several steps manually. This is necessary to load the OECN_INSTALL.COM procedure onto your system. After you have done this once, it should not be necessary for future installations. After mounting the tape enter: (replace the device and directory names with ones appropriate for your system)

$ DEFINE OECN$UTL DUA0:[ODE.UTL] (If not previously defined.) 
$ ALLOCATE MFA0:
$ MOUNT/FOREIGN MFA0:
$ BACKUP/NEW_VERSION MFA0:UTIL.BCK OECN$UTL:
$ DISMOUNT/NOUNLOAD MFA0:
$ @OECN$UTL:OECN_INSTALL

The installation will then proceed normally.

Option

An option is provided to perform a special function and expedite the installation process. The option must be specified on the command line when OECN_INSTALL is invoked as follows:

$ @OECN$UTL:OECN_INSTALL \{device\} OPTIONS \{option\}

The device parameter is not optional when indicating the option. If you do not wish to specify the device on the command line you may specify two double quotes ("") as a place holder for the first parameter.

To specify the "Autoanswer" option, you would enter:

$ @OECN$UTL:OECN_INSTALL MFA0: OPTIONS A

Option: Autoanswer

For any given site the responses to prompts during an installation are generally repetitive from one release to the next. The autoanswer option allows the answers to the installation prompts to be saved in a special file and used to install future releases. To use this option include the letter "A" in the options list, as follows:

$ @OECN$UTL:OECN_INSTALL MFA0: OPTIONS A

The answers to the installation prompts are stored in a file named OECN_INSTALL.ANS located in either OECN$CUSTOM: or OECN$UTL:. The answer file may be created from scratch or modified and placed in OECN$CUSTOM:. The installation will always look in OECN$CUSTOM first for the answer file.

When this option is used with an existing answer file the installation will run to completion without operator intervention. However, if an error should occur the answer file will be closed and the operator will be prompted for any remaining information.

Creating your own Answer file

Before you can use an auto-answer file, you need to create one. To create an autoanswer file from scratch, just delete the OECN_INSTALL.ANS file from both OECN$CUSTOM: and OECN$UTL:. Then perform an installation and specify OPTION A. When the procedure is unable to locate an existing answer file it will automatically create a new one, saving the answers from the current installation. After the installation, the answer file will be located in OECN$CUSTOM and ready for use during the next installation. To make changes to an autoanswer file, you can re-create it as described above, or edit it with a text editor.

Both the prompts and the responses are included in the answer file. The format for each line in the answer file is: prompt\response.

If there is no response, (i.e. nothing to the right of the backslash) then the default for this prompt will be used. That is, the default as provided by OECN_INSTALL.COM during the installation.

The following is a sample of the default answer file:

Enter top level directory to place distribution: \
Enter OECN utility directory: \
Do you want to print a copy of the release notes? \Y
Do you wish to proceed with the installation? \Y
Enter option\1
Do you want the programs LINK'ed with /TRACE? \N
Enter username to send error messages to: \
Enter time to start compiles/links\23:30
Which package(s) do you want to install: *

Be careful not to modify any part of the prompt, (i.e. only change the response on the right side of the backslash). The prompt is used as an internal check within the installation procedure to ensure the answer file is in sync with the installation. If the answer file is found to be out-of-sync, then the autoanswer mode is terminated and the operator must supply any remaining responses.

Sample Run

The following section contains a sample run of a typical installation. Comments enclosed in parentheses () are part of this document, and therefore will not be seen during an actual installation. All input by the operator is in SMALL UPPERCASE.

$ @OECN$UTL:OECN_INSTALL
 
 
$ @OECN$UTL:OECN_INSTALL 
 
 Copyright (C) 1987 Ohio Department of Education 
 Division of Computer Services and Statistical Reports 
 
 
  -- State Software Installation Procedure -- 
 
  Enter '?' for help at any time. 
 
 
 
Deleting Global symbols . . . 
 
     Note: This procedure will completely supersede the packages that it 
installs.  Old versions of files will not be retained. 
 
 
Enter device where distribution media is located: DKA100:[OECN_SSDT.RELEASE] 
 
Enter top-level directory to place distribution: <DKA100:[ODE]> 
 
Enter OECN utility directory: <DKA100:[ODE.UTL.DIST]> 
 
Installing UTIL.BCK . . . 
 
 
Do you want to print a copy of the release notes? <Y> n 
The release notes will be available after the installation 
in DKA100:[ODE.UTL.DIST] 
 
Do you wish to proceed with the installation? <Y> 
 
 Some of the packages on this distribution may need to be LINK'ed 
 before they can be executed. 
 
Options: 
   1)  Link all packages (LINKALL via SYS$BATCH) 
   2)  Don't Link. 
 
Enter link/compile option<1> 1 
 
Do you want the programs LINK'ed with /TRACE? <N> 
 
Enter username to send error messages to: <SMITH> 
 
Enter time to start compiles/links <NOW> 
 
    - Installing mandatory backup sets - 
 
Purging destination directory . . . 
Decompressing DKA100:[ODE.TAPE]COBLIB.ZIP; using UNZIP 
Decompressing DKA100:[ODE.TAPE]COBLIB_AXP.ZIP; using UNZIP 
Restoring COBLIB_AXP to [COBLIB] 
Restoring COBLIB to [COBLIB] 
 
OECN Sharable Image Installation: 
--------------------------------- 
%INSTALL-W-NOPREV, no previous entry exists - new entry created for DEV:[SYS0.SYSCOMMON.][SYSLIB]OECNSHR.EXE;1 
 
%OECNINS-I-SHRINST, OECN sharable image installed. 
%OECNINS-I-RTLINST, Inserted CDA$ACCESS into OECNSHR 
%OECNINS-I-INSTV, Installing translated VAX sharable images 
Installation complete for: OECN COBOL libraries 
 
Package   Description           Destination 
-------   -----------           ----------- 
CSSR10    CSSR Version 1.0      [CSSR.V1P0.DIST]
DOCS      Software Docs         [DOCUMENT.DIST]    
EMIS16    EMIS Version 1.6      [EMIS.V1P6.DIST]    
OECN10    OECN Version 1.0      [OECN.V1P0.DIST]     
SAAS20    SAAS Version 2.0      [SAAS.V2P0.DIST]     
SECIMS10  SECIMS Version 1.0    [SECIMS.V1P0.DIST]         
TRAINING  Training Materials    [TRAINING.DIST...]            
USAS60    USAS Version 6.0      [USAS.V6P0.DIST]              
USPS40    USPS Version 4.0      [USPS.V4P0.DIST]              
 
 
Which package(s) do you want to install: <*> oecn10,usas60 
 
Purging destination directory . . . 
Decompressing DKA100:[ODE.TAPE]OECN10.ZIP; using UNZIP 
Decompressing DKA100:[ODE.TAPE]OECN10_AXP.ZIP; using UNZIP 
Restoring OECN10_AXP to [OECN.V1P0.DIST] 
Restoring OECN10 to [OECN.V1P0.DIST] 
 
OECN Version 1.0 Installation: 
------------------------------ 
 
Do you want customized security ids installed from OECN$CUSTOM: <Y> n 
 
Identiiers will not be installed. 
 
Installation complete for: OECN Version 1.0 
 
Purging destination directory . . . 
Decompressing DKA100:[ODE.TAPE]USAS60.ZIP; using UNZIP 
Decompressing DKA100:[ODE.TAPE]USAS60_AXP.ZIP; using UNZIP 
Restoring USAS60_AXP to [USAS.V6P0.DIST] 
Restoring USAS60 to [USAS.V6P0.DIST] 
 
USAS Version 6.0 Installation: 
------------------------------ 
 
Which USAS purchase order form layout does your site use? 
 
    1) NWOCA supported layout 
    2) State supported layout 
 
Enter USAS PO layout selection: <1> 
Installation complete for: USAS Version 6.0 
 
Package   Description           Destination 
-------   -----------           ----------- 
CSSR10    CSSR Version 1.0      [CSSR.V1P0.DIST]              
DOCS      Software Docs         [DOCUMENT.DIST]               
EMIS16    EMIS Version 1.6      [EMIS.V1P6.DIST]              
OECN10    OECN Version 1.0      [OECN.V1P0.DIST]              
SAAS20    SAAS Version 2.0      [SAAS.V2P0.DIST]              
SECIMS10  SECIMS Version 1.0    [SECIMS.V1P0.DIST]            
TRAINING  Training Materials    [TRAINING.DIST...]            
USAS60    USAS Version 6.0      [USAS.V6P0.DIST]              
USPS40    USPS Version 4.0      [USPS.V4P0.DIST]              
 
 
Which package(s) do you want to install: <*> 
 
Job COMP_PACKAGES (queue SYS$BATCH, entry 447) started on SYS$BATCH 
 
Please add the following line to your SYSTARTUP file: 
 
@DKA100:[ODE.UTL.DIST]OECN_STARTUP.COM 
 
%OECNINS-S-NORMAL, Installation procedure completed successfully 
 
 
 (End of Sample Run) 
 

Post Installation Procedures

Installing packages on the system using OECN_INSTALL does not make them available for the end users. All the required components for each package exist in the distribution directories (OECN$ROOT:[*...DIST]) but have not been moved to the "execution" or "shared" directories. Prior to making the new distribution available to the users, site personnel may wish to review the release notes, test the programs and determine the impact of the distribution on their users.

When you are ready to install the release live, INSTALL_PACKAGE should be used to transfer each package into the execution directory. INSTALL_PACKAGE is described in detail in the next section.

INSTALL_PACKAGE Procedure

To assist site personnel in installing packages on their system, the SSDT provides a command procedure called OECN$UTL:INSTALL_PACKAGE.COM. This procedure should be used by sites to move the required components to the proper directories.

INSTALL_PACKAGE installs an individual package into the proper OECN$ directories ensuring that all required components are installed properly and consistently.

Do not use this procedure until after you have reviewed the release notes for the package and are ready to install the package for use by your users. This procedure will replace files in the OECN$xxx shared directories and make the previously installed version unusable.

INSTALL_PACKAGE must be executed at least once, depending on the options chosen, for each package which is to be installed. In general, packages may be installed an any order and need not be installed at the same time. However, it is strongly recommended that the OECN package be installed prior to installing any other package. The OECN package contains common files and procedures which other packages may depend on.

INSTALL_PACKAGE uses the existing definitions of the the OECN$ logicals to determine where the files should be placed. If you want the files to be installed in different directories then currently defined by the OECN$ logicals, you must redefine the logicals prior to executing INSTALL_PACKAGE. If any required logicals are undefined or improperly defined, the procedure will abort the installation.

Search lists are supported by INSTALL_PACKAGE. If any of the OECN$ logicals are defined as search lists, the package components will be installed in the last directory specified by the search list. The procedure assumes that you want the SSDT supplied files to be at the end of the search list. If this is not true, you will not be able to use INSTALL_PACKAGE on your system.

Using INSTALL_PACKAGE

To use INSTALL_PACKAGE you must know the device and directory of the package's distribution directory. This directories are named OECN$ROOT:[package.version.DIST]. For example, the USPS Version 4.0 distribution directory is called OECN$ROOT:[USPS.V4P0.DIST].

INSTALL_PACKAGE accepts several parameters that determine the function it should perform and package to install. The syntax for invoking INSTALL_PACKAGE is:

        $ @OECN$UTL:INSTALL_PACKAGE \{function\} \{dist_dir\} [options] 

function

Function to perform. See table below.

dist_dir

Device and directory of package's distribution directory.

options

Optional keywords controlling installation. See table below.

The following table describes the primary functions available.

Function Description

FULL

Performs a full installation of the package. Performs the same steps as EXECUTION, CDD and UDMS.

EXECUTION

Performs all steps necessary to prepare package for execution on the system. Moves all executable images, shared data files and command procedures to shared directories. Does not install CDD or UDMS definitions.

CDD

Installs CDD/DTR definitions only. Automatically determines whether to use CDD or DTR text dictionary

DTR

Same as CDD, except explicitly requests DTR text dictionary instead of CDD installation.

UDMS

Installs the UDMS dictionary for the package. If a previous version of the UDMS dictionary is already present, then the distribution version will be merged with the current version.

CHECK

Verifies installation on current system. Reinstalls images as necessary using the VMS INSTALL utility. Use on nodes in a cluster after installing a package on another node.

PATCH

A special mode which assists sites in downloading files from OECN_OOPS, OECN_BETA and OECN_DOWNLOAD

DOWNLOAD

Synonym for PATCH

HELP

Displays help about functions

The following table describes the options that may be specified for the options parameter. You may specify multiple options on the command line separated by commas. If multiple options are specified, enclose them in double quotes (").

Option Description

VERBOSE

Displays detailed information about progress of installation.

LOG

Same as VERBOSE.

PURGE

Purge files replaced by installation. By default files are not purged.

Examples using INSTALL_PACKAGE

The following examples show several uses of INSTALL_PACKAGE.

$ @OECN$UTL:INSTALL_PACKAGE HELP 

This example causes the procedure to display the help messages for INSTALL_PACKAGE. You may may also request help on specific functions or topics. For example:

$ @OECN$UTL:INSTALL_PACKAGE HELP FULL 
$ @OECN$UTL:INSTALL_PACKAGE HELP RESTRICTIONS 

The first example will display help for the FULL function. The second example displays help for the "RESTRICTIONS" help topic. The "RESTRICTIONS" topic displays the latest information about any restrictions on using the INSTALL_PACKAGE procedure.

$ @OECN$UTL:INSTALL_PACKAGE FULL OECN$ROOT:[SAAS.V2P0.DIST] 

This command causes INSTALL_PACKAGE to do full installation for the SAAS Version 2.0 package, including CDD/DTR definitions.

$ @OECN$UTL:INSTALL_PACKAGE EXECUTION OECN$ROOT:[USPS.V4P0.DIST] PURGE 

This command installs everything needed to run USPS Version 4.0. It would not install CDD definitions. Also, because the "PURGE" option was specified, old versions of files replaced by the installation are purged.

$ @OECN$UTL:INSTALL_PACKAGE CHECK OECN$ROOT:[USPS.V4P0.DIST] 

This command uses the CHECK function to check the installation on the current system. You might use this command on nodes in a cluster after a package has been installed on another node. It will verify that the package is installed properly and re-install any known images using the VMS INSTALL utility.

Building the Menu Alias File

The INSTALL_PACKAGE procedure described in the previous section performs most of the necessary steps for installing packages. However, it cannot build a new alias file for the menu system. This is because the alias file depends on all the menu files placed in OECN$MENU$FILES (not one particular package).

After you have installed one or more packages (using INSTALL_PACKAGE) you must build a new alias file that includes the new or updated menu files. SSDT provides a command procedure called BUILD_ALIAS.COM as part of the OECN package. This procedure is located in OECN$:. This procedure will automatically build a new alias file.

By default, BUILD_ALIAS will build the alias file based on the current value of OECN$MENU$FILES, OECN$MENU and OECN$ALIAS. If you only have one menu system on your system and the logicals are defined in your current process, you can rebuild the alias file using the following command:

$ @OECN$:BUILD_ALIAS 

The procedure will also accept parameters that allow you to specify the location and name of a menu system if different from the default. The following syntax is used:

$ @OECN$:BUILD_ALIAS [location] [main_menu] [alias] 

location

Defines the logical or device/directory where the menu files are located.

main_menu

Defines the name of the top level menu file for the menu system.

alias_file

Defines the name of the alias file for the menu system.

For example, assume you have a menu system located in USERA:[MENUFILES] and the main menu is called MY_MAIN_MENU.DAT and the alias file is called MY_ALIAS.DAT. You could use the following command to build a new alias file:

$ @OECN$:BUILD_ALIAS USERA:[MENUFILES] MY_MAIN_MENU MY_ALIAS 

  • No labels