# Compaq DECwindows Motif
for OpenVMS

# Installation Guide

Order Number: AA--Q1EAE--TE

# April 2001

This manual provides step-by-step instructions for installing Compaq DECwindows Motif for OpenVMS.

Revision/Update Information: This manual supersedes the DECwindows Motif Version 1.2--5 for OpenVMS Installation Guide.

Operating System: OpenVMS Alpha Version 6.2, 7.1--2,
7.2--1, or 7.3
OpenVMS VAX Version 6.2, 7.1,
7.2, or 7.3
VMS Version 5.5--2

Software Version: Compaq DECwindows Motif for OpenVMS Alpha, Version 1.2--6
Compaq DECwindows Motif for OpenVMS VAX, Version 1.2--6

Compaq Computer Corporation Houston, Texas

April 2001

© 2001 Compaq Computer Corporation

COMPAQ, OpenVMS, VAX, VMS, the Compaq logo, and the DIGITAL logo Registered in U.S. Patent and Trademark Office.

Motif, OSF/1, and UNIX are registered trademarks of The Open Group.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq or authorized sublicensor required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein.

The information in this publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH THE RECIPIENT. IN NO EVENT SHALL COMPAQ BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT, OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.

The limited warranties for Compaq products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.

ZK6434

The Compaq OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents | Index

# Preface

# Intended Audience

This manual is intended for anyone who plans to install Compaq DECwindows Motif for OpenVMS software.

# Document Structure

This manual contains the following chapters and appendixes:

- Chapter 1 discusses how to prepare for installing Compaq DECwindows Motif for OpenVMS software.
- Chapter 2 discusses how to install Compaq DECwindows Motif for OpenVMS using the POLYCENTER Software Installation utility.
- Chapter 3 discusses how to install Compaq DECwindows Motif for OpenVMS using the VMSINSTAL procedure.
- Chapter 4 provides startup procedures. This chapter also includes a sample Installation Verification Procedure (IVP).
- Chapter 5 discusses tuning, customizing the environment, removing unwanted files, and reporting errors.
- Appendix A presents a sample DECwindows Motif installation using the POLYCENTER Software Installation utility on an OpenVMS Alpha Version 7.1--2 system, an OpenVMS VAX Version 7.1 system, and an OpenVMS Alpha Version 6.2 system. It also presents a sample installation of the PCSI ECO.
- Appendix B shows a sample product installation using the VMSINSTAL procedure on a VMS Version 5.5--2 system.
- Appendix C shows how to obtain a list of the software components for the Compaq DECwindows Motif for OpenVMS product using the POLYCENTER Software Installation utility.

# Related Documents

In addition to this manual, the following documents are useful when installing Compaq DECwindows Motif for OpenVMS software:

- Compaq DECwindows Motif for OpenVMS Release Notes
- Guide to the Compaq DECwindows Motif for OpenVMS CD--ROM
- Getting Started With the New Desktop
- Managing DECwindows Motif for OpenVMS Systems
- OpenVMS System Manager's Manual
- OpenVMS System Management Utilities Reference Manual
- A Comparison of System Management on OpenVMS AXP and OpenVMS VAX

For additional information on the OpenVMS System Software Group (OSSG) products and services, access the following OpenVMS World Wide Web address:

    http://www.openvms.compaq.com

# Reader's Comments

Compaq welcomes your comments on this manual.

Please send comments to either of the follwing addresses:

Internet | openvmsdoc@compaq.com
Mail | Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

# How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

    http://www.openvms.compaq.com:8000/

# Conventions

Compaq DECwindows Motif for OpenVMS Alpha contains a graphical user interface that is derived from the Common Desktop Environment (CDE). This interface is referred to throughout this document as the New Desktop.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to Compaq DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:

Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
`[Return]` | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
... | Horizontal ellipsis points in examples indicate one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . . | Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) | In command format descriptions, parentheses indicate that you must enclose the choices in parentheses if you choose more than one.
[ ] | In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
| | In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ } | In command format descriptions, braces surround a required choice of options; you must choose one of the options listed.
text style | This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. In the HTML version of this document, this convention appears as italic text.
italic text | Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system messages (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace type | Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
- | A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

# Chapter 1
Preparing to Install the Software

This chapter describes the preparation and requirements for installing Compaq DECwindows Motif for OpenVMS software using either the POLYCENTER Software Installation utility or the VMSINSTAL procedure. Your Bill of Materials (BOM) specifies the number and contents of your media. Verify the contents of your kit with this information. If your kit is damaged or if you find that parts are missing, contact your Compaq representative.

Note Compaq strongly recommends that you read the release notes before proceeding with the installation. The Compaq DECwindows Motif for OpenVMS product provides online release notes. For information about accessing the release notes: If you install the software using the POLYCENTER Software Installation utility, see Section 2.2. If you use the VMSINSTAL procedure to install the software, see Section 3.2.5.

This chapter presents information about the following topics:

- Section 1.1, License Registration
- Section 1.2, Supported Hardware
- Section 1.3, Prerequisites for the Installation Procedures
- Section 1.4, Required Operating System Software
- Section 1.5, Required ECO for POLYCENTER Software Installation Utility
- Section 1.6, OSF/Motif Release 1.1.3 and XUI Programming Support
- Section 1.7, Saving Customized Bookreader Files
- Section 1.8, Installation Procedure Requirements

# 1.1 License Registration

Before you install and run Compaq DECwindows Motif for OpenVMS software on a newly licensed node or cluster, you must first register a License Product Authorization Key (License PAK) using the License Management Facility (LMF). The License PAK is provided along with the kit if you ordered the license and media together; otherwise, it is provided separately to a location based on your license order.

If you are installing Compaq DECwindows Motif for OpenVMS software as an update on a node or cluster already licensed for this software, you have already completed the License PAK registration requirements.

You must register and load your license for Compaq DECwindows Motif for OpenVMS before you run the Installation Verification Procedure (IVP) and use the software.

To register a license, log in to the system manager account (SYSTEM). Then choose one of the following options to register the license:

- Invoke the SYS$UPDATE:VMSLICENSE.COM procedure. When the procedure prompts you for information, respond with data from your License PAK.
- At the DCL prompt, enter the LICENSE REGISTER command with the appropriate qualifiers that correspond to License PAK information.

If you plan to use Compaq DECwindows Motif for OpenVMS software on more than one node in a VMScluster, load the license on the other nodes after you complete this installation.

For complete information about using LMF, see the OpenVMS License Management Utility Manual.

# 1.2 Supported Hardware

Compaq DECwindows Motif for OpenVMS software can be installed on any supported Alpha or VAX processor. For a complete list of supported hardware, see the Compaq DECwindows Motif for OpenVMS Software Product Description (SPD).

# 1.3 Prerequisites for the Installation Procedures

Before you can install and configure Compaq DECwindows Motif for OpenVMS software, you must have the required versions of the OpenVMS operating system software, sufficient memory, and a license. (Refer to Section 1.1 for information about registering a License Product Authorization Key [PAK].)

Use the POLYCENTER Software Installation utility or the VMSINSTAL procedure to install your DECwindows Motif software according to the operating system information that follows.

Operating System | Installation Method
--- | ---
OpenVMS Alpha Version 6.2 (or higher) OpenVMS VAX Version 6.2 (or higher) | POLYCENTER Software Installation utility
VMS Version 5.5--2 | VMSINSTAL procedure

# 1.4 Required Operating System Software

The Compaq DECwindows Motif for OpenVMS software requires one of the following operating systems:

- OpenVMS Alpha Version 6.2, 7.1--2, 7.2--1, or 7.3
- OpenVMS VAX Version 6.2, 7.1, 7.2, or 7.3
- VMS Version 5.5--2

If your system is not running one of these versions before you attempt to install Compaq DECwindows Motif for OpenVMS, the installation fails.

A minimum of 16 MB of memory is required for OpenVMS VAX systems; 32 MB of memory is highly recommended. A minimum of 64 MB of memory is required for OpenVMS Alpha systems; at least 128 MB of memory is highly recommended.

The OpenVMS operating system provides two subsets of components to support Compaq DECwindows Motif for OpenVMS. To use Compaq DECwindows Motif for OpenVMS software, your system should be running a version of the OpenVMS system that includes the following components:

- DECwindows Motif transports and base system support
  This support is required to install Compaq DECwindows Motif for OpenVMS and to run Compaq DECwindows Motif for OpenVMS applications. During the installation of OpenVMS, you are prompted to specify whether you want to install this option.
  To determine whether this option was installed during the installation of OpenVMS, enter the following command:

      $ DIR SYS$LIBRARY:DECW$TRANSPORT_COMMON.EXE

  See Section 5.3 for information on adding DECwindows base support files after OpenVMS has been installed.
- DECwindows X11 display server for OpenVMS, fonts, and device drivers, which are necessary to display Compaq DECwindows Motif for OpenVMS applications or any other X11 applications on your Alpha or VAX system
  During the installation of OpenVMS, you are prompted to specify whether you want to install this option.
  To determine whether this option was installed during the installation of OpenVMS, enter the following command:

      $ DIR SYS$SYSTEM:DECW$SERVER_MAIN.EXE

  If the DECW$SERVER_MAIN.EXE file is not on your system, you cannot display Compaq DECwindows Motif for OpenVMS applications on your Alpha or VAX system. However, you can run Compaq DECwindows Motif for OpenVMS applications that display on a DECwindows X11 display server that runs on another system. The Compaq DECwindows Motif for OpenVMS installation procedure asks whether you want to continue the installation without workstation support.
  See Section 5.3 for information on adding DECwindows device support files and 75- or 100-dpi font files after OpenVMS has been installed.

Note See the release notes and cover letter for the version of the OpenVMS operating system that you are running for more information about the DECwindows X11 display server.

# 1.5 Required ECO for POLYCENTER Software Installation Utility

If you are installing the Compaq DECwindows Motif for OpenVMS software on an OpenVMS Version 6.2 or 7.1 system, you must first install an ECO to the POLYCENTER Software Installation (PCSI) utility. See the Guide to the Compaq DECwindows Motif for OpenVMS CD--ROM for details about this ECO. OpenVMS Versions 7.2 and higher include this functionality in the operating system; therefore, you need not apply this ECO if you are running OpenVMS Version 7.2 or higher.

The following example shows a PCSI ECO installation on an OpenVMS Alpha Version 7.1 system (installations on other OpenVMS versions differ slightly):

    $ PRODUCT INSTALL VMS62TO71U2_PCSI

    The following product has been selected:
        DEC AXPVMS VMS62TO71U2_PCSI V1.0       Patch (maintenance update)

    Do you want to continue? [YES]

    Configuration phase starting ...

    You will be asked to choose options, if any, for each selected product and for
    any products that may be installed to satisfy software dependency requirements.

    DEC AXPVMS VMS62TO71U2_PCSI V1.0

    * This product does not have any configuration options.

    Execution phase starting ...

    The following product will be installed to destination:
        DEC AXPVMS VMS62TO71U2_PCSI V1.0       DISK$1:[VMS$COMMON.]

    Portion done: 0%
    ...10%
    ...40%
    ...70%
    ...80%
    ...90%
    ...100%

    The following product has been installed:
        DEC AXPVMS VMS62TO71U2_PCSI V1.0       Patch (maintenance update)

## 1.5.1 Upgrade Problem After Installing Required PCSI ECO

After installing the required POLYCENTER Software Installation utility ECO, your system will use the new features provided by this version of the PCSI utility. If a layered product is installed that makes use of this new functionality, then it may not be possible to revert back to an older version of the utility. The restriction occurs because there may be records in the software product database that the older version of the utility will not be able to interpret.

This scenario occurs if you install the PCSI ECO, then install DECwindows Motif, and later install certain upgrades to the OpenVMS operating system. The steps below describe the situations when this will occur:

1. Install the PCSI ECO kit onto OpenVMS Version 6.2, 6.2--1H1, 6.2--1H2, 6.2--1H3, 7.1, 7.1--1H1, or 7.1--1H2.
2. Install DECwindows Motif Version 1.2--6.
3. Upgrade to (or reinstall) OpenVMS Version 6.2, 6.2--1H1, 6.2--1H2, 6.2--1H3, 7.1, 7.1--1H1, or 7.1--1H2.

Upgrading to any of the OpenVMS versions listed in item 3 may fail (or other PRODUCT command operations on the product database may fail) with one of the following errors:

    %SYSTEM-F-ACCVIO, access violation, ...
    %PCSI-E-UNSDOCENC, unsupported product document encoding version

To prevent these failures after installing the PCSI ECO and DECwindows Motif, perform the following steps:

1. Remove DECwindows Motif using the following command:

       $ PRODUCT REMOVE DWMOTIF

2. Upgrade to (or reinstall) OpenVMS Version 6.2, 6.2--1H1, 6.2--1H2, 6.2--1H3, 7.1, 7.1--1H1, or 7.1--1H2.
3. Reinstall the PCSI ECO.
4. Reinstall DECwindows Motif.

This workaround is not needed if you upgrading to OpenVMS Alpha Version 7.2-1 or higher, or if you are upgrading to OpenVMS VAX Version 7.2 or higher. These versions (and all later versions) already include the new functionality added by the PCSI ECO.

# 1.6 OSF/Motif Release 1.1.3 and XUI Programming Support

The X Window and OSF/Motif libraries that are provided with Compaq DECwindows Motif for OpenVMS software are incompatible with those libraries provided with versions of DECwindows Motif for OpenVMS prior to Version 1.2. Run-time compatibility is preserved, but the earlier OSF/Motif Release 1.1.3 and XUI programming environments are not compatible with the later OSF/MOTIF Release 1.2 programming environment.

Programming in the XUI and OSF/Motif Release 1.1.3 environments that was provided in previous versions of DECwindows Motif is no longer supported in the Compaq DECwindows Motif for OpenVMS product. However, the installation procedure gives you the option of saving the XUI and OSF/Motif Release 1.1.3 programming files that already exist on your system. If you choose to save these programming files, they are moved to subdirectories where you can access them for programming. Specifically, the installation creates a subdirectory called [.DECW$113] in each of the directories listed in Table 1-1 and moves the previous files into the new [.DECW$113] subdirectory.

Table 1-1 Directories for Previous XUI or OSF/Motif Programming Environments
Directory | Contents | New Location
--- | --- | ---
DECW$INCLUDE | C header files | SYS$SYSROOT:[DECW$INCLUDE.DECW$113]
SYS$SYSTEM | UIL compiler | SYS$SYSROOT:[SYSEXE.DECW$113]
SYS$LIBRARY | Non-C language bindings | SYS$SYSROOT:[SYSLIB.DECW$113]

Refer to Section 3.2.7 for additional information about saving previous programming environments.

Note The process for using the saved programming environment is documented in the programmer chapter of the release notes.

Next | Contents | Index