# Compaq ACMS for OpenVMS
Version 4.4 Installation Guide

Previous | Contents | Index

## 3.2.5 Running the Installation Verification Procedure (Fifth Phase)

If you were informed during the second phase of the installation that the ACMS Installation Verification Procedure (IVP) would be executed, it is done at this time. A message similar to the following is displayed:

        ACMS Installation Verification Procedure started
          at 11:10 on 22-JUN-2001

The IVP is then invoked. It displays several informational messages to inform you of its progress. Refer to Chapter 5 for more information on the ACMS IVP.

Note If the ACMS IVP is not invoked automatically during the installation, invoke it manually at your earliest convenience after the installation.

When the ACMS IVP is completed, a message similar to the following is displayed:

        ACMS Installation Verification Procedure completed successfully
          at 11:12 on 22-JUN-2001

## 3.2.6 Completing the Installation

The following message indicates that the entire ACMS installation is complete:

    Installation of ACMSDEVA_ V4.4 completed at 11:12

You can now log out of the privileged SYSTEM account:

    $ LOGOUT
    SYSTEM     logged out at 22-JUN-2001 11:13:01.55

VMSINSTAL deletes or changes entries in the process symbol tables during the installation. Therefore, if you are going to continue using the SYSTEM account and you want to restore these symbols, log out and log in again.

# 3.3 Recovering from System and Installation Failures

An unsuccessful installation can result from a system failure or errors encountered during the installation procedure. In some cases, you must correct the problem and reinstall ACMS. In other cases, you can continue where you left off. The following sections describe various failure scenarios and the recommended procedure to follow to recover from them.

## 3.3.1 System Failures

If you experience a system failure, such as a power loss during installation, VMSINSTAL automatically attempts to continue the installation when you reboot the system. Depending on the point in the installation at which the system failed, 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 then might tell you to manually purge replaced files, even if you requested 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 that you want to save, you can delete just the ACMS files you want to remove from system directories. If you want to purge files, reboot the system, log in to the SYSTEM account, and purge all system files using the following command:

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

  When you have performed this task, the installation is complete.

If the system fails after you see the message that indicates the beginning of the ACMS IVP, VMSINSTAL has already completed the installation of the component software. In this case, when you reboot your system, VMSINSTAL displays the following message:

    %VMSINSTAL-I-RECOVER, ACMSDEVA_ V4.4 was being installed when the system crashed.

    The installation completed satisfactorily.

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

VMSINSTAL does not automatically restart the IVP. You can run the IVP independently by following the steps described in Chapter 5.

## 3.3.2 ACMS Installation Failures

If the installation of the ACMS software fails for some reason other than a system failure, the installation procedure displays a message telling you the cause of the failure. To continue with the installation, you must 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:

- Operating system version is incorrect.
- Prerequisite software version is incorrect.
- Quotas necessary for successful installation are insufficient.
- System parameter values for successful installation are insufficient.
- 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. (For example, you might need to change a system parameter or increase a quota value.) For information on installation requirements, see Chapter 2.

If the installation of the component software completes satisfactorily, but a test or operation 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 ACMS. The failure could be due to low settings for the SYSGEN parameters GBLPAGES, GBLSECTIONS, GBLPAGFIL, or to an insufficient number of process slots. Check the ACMS Software Event Log for a message that indicates the source of the problem. If the IVP fails after you reinstall ACMS, contact your local Compaq Customer Support Center.

## 3.3.3 Recovering from Errors

You can run the ACMS IVP separately after you install ACMS by following the instructions in Chapter 5. 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 5. If the action you take is to reinstall ACMS, the IVP runs automatically if you answer YES to the IVP question. If you still cannot successfully run the IVP, contact your local Compaq Customer Support Center.

# 3.4 Accessing the Online Release Notes

After ACMS has been installed, the release notes are located in the following file:

    SYS$HELP:ACMS044.RELEASE_NOTES

Online help also directs you to the release notes file. After the installation, you can enter the following command:

    $ HELP ACMS RELEASE_NOTES

Hardcopy release notes are not included with the documentation set for ACMS.

# 3.5 Files Installed on Your System

The files added to your system by the ACMS installation are listed in:

    SYS$SYSTEM:ACMS044_FILES.DAT

You can display or print this file after you install ACMS.

ACMS Version Identification File (ACMS_ECO_LEVEL.DAT)

Starting with the ACMS Version 4.0 ECO Kit 1 release, a file named ACMS_ECO_LEVEL.DAT is distributed with the kit. This file is placed in the SYS$SYSTEM directory during installation.

ACMS_ECO_LEVEL.DAT contains the version identifier for the ACMS release that is currently installed on the system. This file is distributed for all releases, including full releases, that have an ECO level of 0. If you report any problems with ACMS, refer to this file to determine the current ACMS version number. The version in this file may be more current than the version numbers that appear throughout the ACMS system, especially when running with an ECO release.

# Chapter 4
After Installing ACMS

This chapter describes system management tasks that you perform manually after installing ACMS Version 4.4. These tasks might include:

- Executing the ACMS postinstallation procedure manually (if it was not executed automatically during installation)
- Editing system startup and shutdown procedures to include ACMS
- Editing the ACMS site-specific startup procedure ACMS_SETUP.COM
- Modifying ACMS parameters
- Authorizing applications, devices, users, and processes
- Creating and modifying ACMS user accounts
- Setting up ACMS on an OpenVMS Cluster system
- Enabling distributed ACMS processing
- Rebuilding the LSE environment
- Preparing language-specific ACMS development environments

The following sections describe these tasks.

# 4.1 Executing the ACMS Postinstallation Procedure

If you were notified during the ACMS installation that the postinstallation procedure would not be run automatically, execute it now.

To execute the postinstallation procedure manually, use the following commands:

    $ SET DEFAULT SYS$MANAGER
    $ @ACMS_POST_INSTALL.COM

See Section 3.2.4 for more information on the steps performed by the postinstallation procedure.

# 4.2 Editing System Startup and Shutdown Procedures

You must edit the OpenVMS system startup and shutdown procedures to provide for automatic startup and shutdown of ACMS when your system is rebooted. (This step is usually not necessary for system upgrades.)

## 4.2.1 Editing the System Startup Procedure

Add the following DCL command to the system startup procedure:

    $ @SYS$STARTUP:ACMSTART.COM

For sites that have modularized startup procedures, be sure to add the command to the correct procedure. The default startup command procedure for OpenVMS VAX starting with Version 6.x and for OpenVMS Alpha systems is SYS$MANAGER:SYSTARTUP_VMS.COM.

Position the ACMS startup command after the commands that start software on which ACMS relies. In particular, start ACMS after the network, DECdtm, and DECforms are started, and before TP Desktop Connector is started. For example:

    $ @SYS$STARTUP:STARTNET.COM
    $ @SYS$STARTUP:DECDTM$STARTUP.COM
    $ @SYS$STARTUP:FORMS$STARTUP.COM
    $ @SYS$STARTUP:ACMSTART.COM
    $ @SYS$STARTUP:ACMSDI$STARTUP.COM

Note The network must be running before ACMS is started, if you are going to use distributed ACMS processing.

## 4.2.2 Installing ACMS Images as Resident on OpenVMS Alpha

On OpenVMS Alpha systems, your application performance may improve by installing certain ACMS images as resident with the OpenVMS Install utility. Installing images as resident allows them to take advantage of the OpenVMS Alpha image-slicing feature.

The code sections of an image installed as resident reside in huge pages called granularity hint regions (GHRs) in memory. The Alpha hardware can consider a set of pages as a single GHR. This GHR can be mapped by a single page table entry (PTE) in the translation buffer (TB). The result is a reduction in TB miss rates. For more information on improving the performance of shareable images, see the OpenVMS Linker Utility Manual.

The following ACMS images have been linked to allow them to be installed as resident:

For all kits:

- SYS$LIBRARY:ACMSHR.EXE
- SYS$LIBRARY:ACMTWPSHR.EXE
- SYS$LIBRARY:ACMRRSHR.EXE
- SYS$LIBRARY:ACMVFSHR.EXE

For development and run-time kits only (in addition to the preceding):

- SYS$LIBRARY:ACMIWPSHR.EXE
- SYS$SYSTEM:ACMSIWP.EXE

To install images as resident, execute the ACMS startup command procedure with the RESIDENT parameter as follows:

    @SYS$STARTUP:ACMSTART.COM RESIDENT

On OpenVMS VAX, the RESIDENT parameter is ignored when specified with ACMSTART.COM.

Installing images as resident may require that you increase the GBLPAGES, GBLSECTIONS, and NPAGEDYN system parameters. Refer to Section 2.6.3 for more information on using AUTOGEN to change system parameters.

For OpenVMS Alpha Version 6.x, you may need to increase the GH_RSRVPGCNT SYSGEN parameter to install ACMS images as resident.

## 4.2.3 ACMSTART.COM Installs DECC$SHR and ACMS$TRACE_SHR.EXE

ACMSHR.EXE links with ACMS$TRACE_SHR.EXE, which links with DECC$SHR.EXE. ACMSTART.COM has been modified to install both DECC$SHR.EXE and ACMS$TRACE_SHR.EXE. It is necessary to leave both of these images installed.

If DECC$SHR is not installed on the system, you get an error similar to the following when starting ACMS:

    $ ACMS/START SYS
    %DCL-W-ACTIMAGE, error activating image DECC$SHR
        -CLI-E-IMGNAME, image file
         $100$DUA253:[SYS4.SYSCOMMON.][SYSLIB]DECC$SHR.EXE;1
        -SYSTEM-F-PRIVINSTALL, shareable images must be installed
         to run privileged image

If ACMS$TRACE_SHR.EXE is not installed on the system, you get the following error when starting ACMS:

    $ ACMS/START SYS
    %DCL-W-ACTIMAGE, error activating image ACMS$TRACE_SHR.EXE
    -CLI-E-IMGNAME, image file
         $100$DUA253:[SYS4.SYSCOMMON.][SYSLIB]ACMS$TRACE_SHR.EXE
        -SYSTEM-F-PRIVINSTALL, shareable images must be installed
         to run privileged image

## 4.2.4 Editing the System Shutdown Procedure

Add the following DCL commands to the system shutdown file, SYS$MANAGER:SYSHUTDWN.COM:

    $ ACMS/STOP SYSTEM /CANCEL
    $ @SYS$STARTUP:ACMSTOP.COM

The first command cancels all active tasks and shuts down the ACMS system. It ensures that the ACMS system processes are run down properly and immediately.

The second command invokes the ACMS shutdown command procedure, ACMSTOP.COM. This procedure deinstalls ACMS images (using the Install Utility of OpenVMS).

# 4.3 Editing ACMS_SETUP.COM

During the installation of ACMS, ACMS_SETUP.COM, a template for site-specific ACMS startup operations, is placed in SYS$STARTUP. If ACMS_SETUP.COM already existed from a previous installation, the template is named ACMS_SETUP_NEW.COM.

The next sections describe modifications you can make to ACMS_SETUP.COM, based on your use of ACMS.

## 4.3.1 Optional ACMS Logical Names

Table 4-1 lists optional ACMS logical names that you can define in ACMS_SETUP.COM, and their defaults.

Table 4-1 Optional ACMS Logical Names
Logical Name | Default
--- | ---
ACMS$AUDIT_LOG 1 | SYS$ERRORLOG:ACMSAUDIT.LOG
ACMS$SWL_LOG 1 | SYS$ERRORLOG:SWL.LOG
ACMS$NOTICE 2 | (none)
ACMS$EDIT 3 | SYS$COMMON:[SYSEXE]TDMSEDIT.COM
ADU$EDIT 4 | ACMS$EDIT
SWLUP$EDIT 5 | ACMS$EDIT

1See Compaq ACMS for OpenVMS Managing Applications for more information on this logical name.
2Used to display the text in the file pointed to by the logical name whenever an ACMS user signs in through the terminal subsystem. If defined, it must point to an existing, nonempty text file.
3If TDMS is not installed, the default is SYS$COMMON:[SYSEXE]ACMSEDIT.COM.
4Defines the editor to be used for the EDIT command to ACMSADU.
5Defines the editor to be used for the EDIT command to SWLUP.

For each of these logical names, a DCL command exists in ACMS_SETUP.COM. For example:

    $! DFN_SUPER ACMS$AUDIT_LOG SYS$ERRORLOG:ACMSAUDIT.LOG

(DFN_SUPER is also defined in ACMS_SETUP.COM, to create the logical name in the mode required by ACMS.) To equate an optional ACMS logical to a nondefault value, edit the appropriate command line by removing the exclamation point (!) and providing a new equivalence string for the logical name. For example:

    $ DFN_SUPER ACMS$AUDIT_LOG AUDIT_DISK:ACMSAUDIT.LOG

## 4.3.2 Installing Application Development Shareable Images

If you have installed the development kit, or the run-time kit with CDD installed, the shareable images listed in Table 4-2 and Table 4-3 are in SYS$SHARE. If you installed the remote-access kit, or the run-time kit without CDD installed, these images are not supplied.

If you do a lot of ACMS application development work, consider installing these shareable images. Installing these images increases the number of global sections and global pages required by ACMS, but decreases memory requirements if many users are running ADU, and also decreases image activation time. Table 4_2 and Table 4-3 show the number of global sections and global pages required for installing each image.

Table 4-2 Global Sections and Pages Required for Shared Utility Images (Alpha)
Utility Image | GBLSECTIONS Used | GBLPAGES Used
--- | --- | ---
ACMADUSHR | 3 | 63
ACMCDUSHR | 3 | 383
ACMCMUSHR | 1 | 331
ACMTDUSHR | 3 | 650

Table 4-3 Global Sections and Pages Required for Shared Utility Images (VAX)
Utility Image | GBLSECTIONS Used | GBLPAGES Used
--- | --- | ---
ACMADUSHR | 3 | 22
ACMCDUSHR | 1 | 169
ACMCMUSHR | 1 | 145
ACMTDUSHR | 1 | 299

For each of these images, the following DCL commands exist in ACMS_SETUP.COM:

    $! IMAGE_NAME = "image"
    $! GOSUB INSTALL_IMAGE

To install these images during the next ACMS startup, edit the command lines by removing the exclamation point (!) in each line.

## 4.3.3 ACMS System Management Commands

ACMS_SETUP.COM can also be used to execute ACMS system management commands that prepare the ACMS system for work. These commands might include starting applications, enabling ACMS operator terminals, starting the Queued Task Initiator (QTI), and so forth.

Examples of these commands are included at the end of ACMS_SETUP.COM:

    $!** Start the ACMS system (delay terminal startup until applications are
    $!** started)
    $! ACMS/START SYSTEM /NOTERMINALS
    $!
    $!** Set ACMS operator terminals; if more than one, place them within the
    $!** parentheses and separate with commas, eg (OPA0,TTA2)
    $! ACMS/SET SYSTEM /OPERATOR/TERMINAL=(OPA0)
    $!
    $!** Start the Queued Task Initiator
    $! ACMS/START QTI
    $!
    $!** Start task queues; if more than one, separate with commas,
    $!** eg QUEUE_1,QUEUE_2
    $! ACMS/START QUEUE QUEUE1
    $!
    $!** Start ACMS applications; if more than one, separate with commas,
    $!** eg APPLICATION_1,APPLICATION_2
    $! ACMS/START APPLICATION APPLICATION_1
    $!
    $!** Start ACMS terminals
    $! ACMS/START TERMINALS

Edit this section of ACMS_SETUP.COM by inserting the commands necessary to complete the startup of your ACMS system.

Previous | Next | Contents | Index