This chapter describes how to install Compaq TP Desktop Connector gateway for ACMS software. Section 9.1 provides helpful information about installing the gateway software. Section 9.2 contains a step-by-step description of the installation procedure.

9.1 General Installation Information

This section includes the following information.

• Accessing Release Notes (see Section 9.1.1)
• Determining the files and logical names added to your system (see Section 9.1.2)
• Running the Installation Verification Procedure (IVP) (see Section 9.1.3)
• Aborting the installation (see Section 9.1.4)

The gateway software provides online Release Notes. To activate the prompt about displaying or printing the Release Notes, invoke VMSINSTAL with the OPTIONS N parameter.

After the gateway software has been installed, the Release Notes are located in a directory with public access.

9.1.2 Files and Logical Names Installed on Your System

The following files contain a list of the files added to your system by the gateway installation:

SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$FIRST_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_ADD_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_AVERTZ_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_COMMON_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_EMPLOYEE_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SAMPLE_MACINTOSH_FILES.DAT SYS$COMMON:[SYSTEST.ACMSDI]ACMSDI$SYSTEM_FILES.DAT

You can display or print these files after you install the gateway software.

After the installation, if the gateway is started (by ACMSDI$STARTUP.COM), the following logical names are added to your system:

ACMSDI$EXAMPLES ACMSDI$EXAMPLES_ACMS ACMSDI$EXAMPLES_ADD ACMSDI$EXAMPLES_AVERTZ ACMSDI$EXAMPLES_EMPLOYEE ACMSDI_AVERTZ_DEFAULT AVERTZ_TDB

These logical names are entered into the system logical name table. The names are used in various gateway startup files. Thus, they are automatically entered into the system logical name table whenever the gateway startup command file is executed.

9.1.3 Installation Verification Procedure

The Installation Verification Procedure (IVP) for gateway software verifies the installation. During the installation, you are asked whether you want to run the IVP as part of the installation. If you answer YES, VMSINSTAL runs the IVP. It is recommended that you run the IVP to be sure that the software is installed correctly.

After you install the gateway software, you can run the IVP independently to verify that the software is available on your system. You might also want to run the IVP after a system failure to be sure that users can access gateway software. See Chapter 11 for information about running the IVP separately from the installation procedure.

9.1.4 Aborting the Installation

To abort the installation procedure at any time, press [Ctrl/Y] . When you press [Ctrl/Y], the installation procedure deletes all files it has created up to that point and exits. You can then start the installation again.

9.2 Installation Procedure

Perform the steps in the following sections to install the gateway software.

9.2.1 Invoking VMSINSTAL

Perform the following steps to start the installation process.

1. Log to a privileged account (see Section 8.3.2 for details) and set the default to the desired directory. For example:

   $ SET DEFAULT SYS$UPDATE $

   
   SYS$UPDATE is used in this example.

2. Use the following syntax to invoke VMSINSTAL:

   @SYS$UPDATE:VMSINSTAL saveset-name device-name OPTIONS N

   
   The parameter saveset-name represents the installation name for the component. For the gateway software, use the following installation name:

   ACMSDIA

   
   If you do not supply the saveset name, VMSINSTAL prompts you for it later in the installation procedure.
   The parameter device-name represents the location of the saveset files (see Section 8.3.6). If you do not supply device-name, VMSINSTAL prompts you for this information later in the installation procedure.
   OPTIONS N is an optional parameter indicating that you want to be prompted to display or print the Release Notes. If you do not include the OPTIONS N parameter, VMSINSTAL does not prompt you to display or print the Release Notes.
   VMSINSTAL supports several other options. For information, refer to the OpenVMS documentation on software installation.

3. Execute the installation procedure. For example:

   $ @SYS$UPDATE:VMSINSTAL ACMSDIA DKA200[KIT]: OPTIONS N

   
   This command begins installing the ACMSDIA saveset found in the directory KIT on the CD device named DKA200.

VMSINSTAL asks several installation questions as described in Section 9.2.2.

9.2.2 Installation Questions

This section discusses the questions that appear during the installation. Each question in the installation is marked with an asterisk (*) at the beginning of the line. Some questions show the default response in brackets, for example, [YES]. To give the default response, press [Return] .

1. Confirming active processes
   VMSINSTAL displays a list of all active processes. It then asks whether you want to continue the installation. Install the gateway software on a standalone system or cluster with DECnet shut down to minimize possible installation problems.

   %VMSINSTAL-W-ACTIVE, The following processes are still active: . . . * Do you want to continue anyway [NO]? YES

2. Confirm system backup
   VMSINSTAL asks whether you are satisfied with your system backup. Always back up your system disk before performing an installation. If you are satisfied with the backup of your system disk, press [Return] . Answer NO to discontinue the installation. After you back up your system disk, restart the installation.

   * Are you satisfied with the backup of your system disk [YES]?

3. Mounting the media
   VMSINSTAL now displays the CD device name and asks whether you are ready to continue with the installation.
   Answer YES to indicate that the CD is mounted. VMSINSTAL displays a message that the media containing gateway software is mounted on the specified device and that the installation is beginning. For example:

   Please mount the first volume of the set on DKA200:. * Are you ready? YES %MOUNT-I-MOUNTED, ACMSDI mounted on DKA200: The following products will be processed: ACMSDIA V3.1 Beginning installation of ACMSDIA V3.1 at 13:14 %VMSINSTAL-I-RESTORE, Restoring product save set A...

   
   If you enter the wrong device name when you invoke VMSINSTAL and need to restart the installation, answer NO in response to the Are you ready? question. See Section 8.3.6 for instructions on mounting the CD.
   To abort the installation for other reasons, press [Ctrl/Y] .

4. Release Notes
   If you specified OPTIONS N when you invoked VMSINSTAL, you see several options for reviewing the Release Notes. The following options are displayed:

   Release Notes included with this kit are always copied to SYS$HELP. 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]: 1

   • Option 1
     If you select option 1, VMSINSTAL displays the Release Notes immediately on the console terminal. You can terminate the display at any time by pressing [Ctrl/C] . Because the Release Notes are several pages long, it is recommended that you choose option 2 to print the Release Notes rather than reviewing them on line.
   • Option 2
     If you select option 2, VMSINSTAL prompts for the name of the print queue to use:

     * Queue name [SYS$PRINT]:

     
     Enter the name of an ANSI print queue on your system, or press [Return] to send the file to the default queue shown within the square brackets.

   • Option 3
     If you select option 3, VMSINSTAL displays the Release Notes and prompts for a queue name for the printed version.
   • Option 4
     If you select option 4, VMSINSTAL continues the installation.
5. Continuing the installation
   The installation procedure asks whether you want to continue the installation. To continue, answer YES. Otherwise, press [Return] . In either case, the Release Notes are copied to a file in the SYS$HELP directory. For example:

   * Do you want to continue the installation [N]?: YES %VMSINSTAL-I-RELMOVED, Product's Release Notes have been moved to SYS$HELP. © Digital Equipment Corporation. 1998. All Rights Reserved.

   
   The name of the Release Notes file installed by VMSINSTAL consists of the current product name and version number. If you plan to compare previous versions of gateway software, do not delete the Release Notes for previous versions of the gateway.

6. Choosing to purge files
   You can purge files from previous versions of the gateway that are superseded by this installation. Purging is recommended, however, if you need to keep files from a previous version, answer NO in response to this question:

   * Do you want to purge files replaced by this installation [YES]?

7. Choosing to run the IVP
   If you are installing the gateway system components, the installation procedure asks whether you want to run the IVP. The IVP checks that the software is installed correctly. It is recommended that you run the IVP.

   * Do you want to run the IVP after the installation [YES]? YES

   
   Press [Return] to run the IVP after installing gateway software. Answer NO to omit the IVP. Run the IVP independently after the installation to check the consistency of the gateway software. See Chapter 11 for information about how to run the gateway IVP independently of the installation procedure.

8. Installing Macintosh sample code
   You have the option of installing the gateway samples for the Macintosh platform.

   * Do you want to install the Macintosh sample [YES]? NO

   
   Press [Return] to load the server-side Macintosh sample application code in the [.MACINTOSH] subdirectory of the ACMSDI$EXAMPLES directory. Answer NO to omit the Macintosh sample code. Note that only the Macintosh samples are optional; the Add, Avertz, and Employee server-side sample files are installed automatically.

9. Confirming license registration
   VMSINSTAL asks whether you have a PAK installed. You can install gateway software prior to registration; however, the software is unusable until you register the license.

   Looking up the Product Authorization Information. Product: TP-DESKTOP-ACMS Producer: DEC Version: 3.1 Release Date: 18-AUG-1999 * Does this product have an authorization key registered and loaded? YES

   
   If you answer NO, the installation completes but the IVP is not run. If you answer YES and the license is not registered, the IVP fails.

At this point, the installation procedure displays a number of informational messages that report on the progress of the installation and advise about different uses of the product. There are no further questions.

%ACMSDI-I-PROCEED, There are no further questions and all checks have been completed. -ACMSDI-I-PROCEED, It will take approximately 15 minutes to complete the installation. %VMSINSTAL-I-ACCOUNT, This installation updates an identifier named ACMSDI$CLIENT. %UAF-I-RDBMDFYMSG, identifier ACMSDI$CLIENT modified . . .

Read the instructions, because they might apply to your installation.

If the installation procedure has been successful up to this point, VMSINSTAL moves the new or modified files to their target directories and updates help files. If you asked for files to be purged, that work is done. The following message is displayed:

. . . %VMSINSTAL-I-MOVEFILES, Files will now be moved to their target directories... . . .

If you are installing gateway software on a system disk that has limited free space, VMSINSTAL might not be operating in safety mode. In this case, VMSINSTAL processes all files immediately and does not display the %VMSINSTAL-I-MOVEFILES... message.

If the disk has quotas enabled, a message is displayed. The account must have sufficient disk quotas to install. Refer to Table 8-1.

9.2.4 Running the Installation Verification Procedure

If you chose to run the IVP, VMSINSTAL runs it next. When the IVP runs successfully, you see the following messages displayed:

%RUN-S-PROC_ID, identification of created process is 210031D5 Starting Server ACMSDI$SERVER The TP Desktop Connector V3.1 Gateway for ACMS IVP completed successfully Installation of ACMSDIA V3.1 completed at 13:32 . . . The TP Desktop Connector V3.1 Gateway for ACMS IVP completed successfully

9.2.5 Completing the Installation Procedure

The following messages indicate that the installation procedure is complete:

Installation of ACMSDIA V3.1 completed at 13:32 VMSINSTAL procedure done at 13:33 $

You can now log out of the privileged account:

$ LOGOUT SYSTEM logged out at 04-JAN-1999 13:34:12.28

VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, to continue using the system account and restore these symbols, log out and log in again. Proceed to Chapter 10 to follow postinstallation procedures.

9.3 Recovering from System and Installation Failures

An unsuccessful installation can result from a system failure (see Section 9.3.1) or errors encountered during the installation procedure (see Section 9.3.2).

9.3.1 System Failures

If you experience a system failure, such as a power loss during installation, VMSINSTAL attempts to continue the installation when you reboot the system. Depending on the point in the installation at which the system fails, one of three conditions exists:

• The system disk did not undergo any changes before the system failure. VMSINSTAL instructs you to restart the installation.
• The system disk used by the installation was corrupted. VMSINSTAL instructs you to restore the system disk from the backup copy and restart the installation.
• VMSINSTAL continues the installation and can tell you to manually purge replaced files, even if you request that they be purged automatically. You can purge files, but remember that purging deletes all but the latest version of all files on your system disk. If you have multiple versions of system files to save, you can delete just the gateway files you want to remove from system directories.
  To purge files, perform the following steps:
  1. Reboot the system.
  2. Log in to the SYSTEM account.
  3. Purge all system files using the following command:

     $ PURGE/LOG SYS$SYSROOT:[*...]*.* . . .

  
  After you perform this task, the installation is complete.

After you see the message that indicates the beginning of the IVP, the installation of the component software is complete. If the system fails subsequently, VMSINSTAL displays the following message when you reboot.

%VMSINSTAL-I-RECOVER, TP Desktop Gateway for ACMS was being installed when the system crashed. The installation completed satisfactorily.

This message indicates that VMSINSTAL finished successfully, not that the installation of the gateway was successful.

VMSINSTAL does not automatically restart the IVP. Run the IVP independently by following the steps described in Chapter 11.

9.3.2 Installation Failures

If the installation of the gateway software or a TP Desktop Connector sample application fails for some reason other than a system failure, the installation procedure displays a message describing the cause of the failure. To continue with the installation, correct the condition causing the error and restart the installation procedure from the beginning.

Errors can occur during the installation if any of the following conditions exist:

• The operating system version is incorrect.
• A prerequisite software version is incorrect.
• Quotas necessary for successful installation are insufficient.
• System parameter values for successful installation are insufficient.
• The OpenVMS help library is currently in use.

For descriptions of the error messages generated by these conditions, see the OpenVMS documentation on system messages, recovery procedures, and OpenVMS software installations. If you are notified that any of these conditions exist, take the appropriate action as described in the message. (You might need to change a system parameter or increase a quota value.) For information on installation requirements, see Chapter 8.

If the installation of the component software completes satisfactorily, but a test fails during the IVP, the IVP displays a message describing the failure and suggests a course of action.

In most cases, the suggested course of action is to reinstall the gateway software. If the IVP fails after you reinstall the gateway software, contact your Compaq software specialist.

9.3.3 IVP Error Recovery

As the IVP executes, it checks the success of each test and operation it performs. If any test or operation fails, the IVP displays a message describing the failure and suggests a course of action.

Follow the suggested course of action and then restart the IVP as described in Chapter 11. If you reinstall gateway software, the IVP runs automatically if you answer YES to the IVP question. If you still cannot successfully run the IVP, contact your Compaq software specialist.