Managing DECwindows Motif for OpenVMS Systems

Order Number: AA--Q1E9A--TE

Revision/Update Information: This is a new manual.

Software Version: DECwindows Motif Version 1.2 for OpenVMS AXP
DECwindows Motif Version 1.2 for OpenVMS VAX

Operating System Version: OpenVMS AXP Version 1.5
VMS Version 5.5--2

Digital Equipment Corporation
Maynard, Massachusetts

The information in this document is subject to change without notice and should not be construed as a commitment by Compaq Computer Corporation. Compaq Computer Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

Copyright ©1994

The following are trademarks of Compaq Computer Corporation: Alpha AXP, AXP, Bookreader, DECnet, DECwindows, Digital, OpenVMS, ReGIS, ULTRIX, VAX, VAX DOCUMENT, VAXcluster, VMS, VMScluster, VT100, VT320, and the DIGITAL logo.

The following are third-party trademarks:

Display POSTSCRIPT and POSTSCRIPT are registered trademarks of Adobe Systems Incorporated.

Motif is a trademark of the Open Software Foundation, Inc.

TEKTRONIX is a registered trademark of Tektronix, Inc.

Open Software Foundation is a trademark of the Open Software Foundation, Inc.

UNIX is a registered trademark licensed exclusively by X/Open Co. Ltd.

X Window System is a trademark of the Massachusetts Institute of Technology.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6300

This document is available on CD-ROM.

This document was prepared using DECdocument, Version V3.3-1e.

Contents

Index

Intended Audience

The intended audience for this manual is experienced OpenVMS AXP and VAX system managers who need to manage and customize DECwindows Motif for VMScluster or standalone systems.

Document Structure

This manual consists of the following chapters and appendixes:

• Chapter 1---An overview of the DECwindows Motif architecture and a description of DECwindows components.
• Chapter 2---A description of the startup process and how to customize the startup command procedure.
• Chapter 3---How to configure and customize the display server, including the use of symbols for server process, device setup, font setup, backing store, extensions, and error reporting. This chapter also includes customization examples for dual-head setup, for specifying new fonts, and alternative methods of transport.
• Chapter 4---A description of the DECwindows Motif login sequence and how to customize the Session Manager environment, including creating your own logo, creating dedicated accounts, and customizing print formats.
• Appendix A---Recommended settings for UAF limits and system parameters for both OpenVMS AXP and OpenVMS VAX systems.
• Appendix B---Lists the DECwindows Motif keymap names. This appendix is arranged by the language for which each keyboard is designed.
• Appendix C---General troubleshooting techniques and a listing of common problems and suggested solutions.

Conventions

In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating system, every use of OpenVMS VAX means the OpenVMS VAX operating system, and every use of OpenVMS means both the OpenVMS AXP operating system and the OpenVMS VAX operating system.

The following conventions are used to identify information specific to OpenVMS AXP or to OpenVMS VAX:
The AXP icon denotes the beginning of information specific to OpenVMS AXP.

The VAX icon denotes the beginning of information specific to OpenVMS VAX.

The diamond symbol denotes the end of a section of information specific to OpenVMS AXP or to OpenVMS VAX.

In this manual, every use of DECwindows and DECwindows Motif refers to 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.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1, then press and release another key or a pointing device button.
. . .	A vertical ellipsis indicates 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.
boldface text	Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason. Boldface text is also used to show user input in online versions of the manual.
italic text	Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER= name), and command parameters in text.
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
-	A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows.
numbers	All numbers in text are assumed to be decimal, unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.
mouse	The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus.
MB1, MB2, MB3	MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)

This chapter provides an overview of the DECwindows Motif for OpenVMS VAX and AXP systems and includes the following topics:

Topic	Section
Client/Server Model	Section 1.1
Display Server	Section 1.1.1
Client	Section 1.1.2
The Transport Layer	Section 1.1.3
Components of DECwindows Motif	Section 1.2

1.1 Client/Server Model

DECwindows Motif for OpenVMS software operates on a client/server model. A server is a single-shared process that performs operations at the request of many client processes. In the DECwindows Motif environment, the graphics applications (such as DECterm and DECwindows Mail) are the clients that interact with the display server. The display server manages the physical graphics display and input devices on behalf of the client applications.

In most client/server relationships, you think of the client system as a computer that sits on the desktop and the server system as being in the machine room. In DECwindows, as in all X window environments, the server sits on the desktop and displays graphics on the screen, while the client might be in the machine room running applications like DECterm and DECwindows Mail. To differentiate between the DECwindows server and other types of servers, the DECwindows server is referred to as the display server.

Figure 1-1 illustrates the DECwindows Motif client/display server architecture.

Figure 1-1 DECwindows Motif Architecture

The display server is the component of the architecture that allows application interfaces to interact with all the supported systems in the same way. Residing on the displaying system, the display server receives X protocol requests from clients through transport layers and performs the functions required to fulfill the request for a specific device.

Essentially, the server converts data that represents the request into commands that can be executed by the appropriate graphics device. When the user of an application enters data with the mouse or keyboard, the display server receives input from the device drivers and passes protocol packets back through the transport layers to Xlib and toolkit routines.

The display server supports asynchronous input from the user to the application and asynchronous output from the application to a display.

1.1.2 The Client

The client is a process that makes the X protocol request and is usually a user's application, such as DECterm or DECwindows Mail. The client controls what is displayed on the server display system and generates the user interface with which the user interacts.

1.1.3 The Transport Layer

In the DECwindows architecture, as in most client/server models, the client and server do not have to reside on the same machine. The client and server are connected by a transport layer that hides the details of the connection. The client and server must each contain their own transport component.

The transport layer is responsible for transferring data between the client and server systems and does not alter this data in any way.

DECwindows Motif for OpenVMS supports the following transport mechanisms:

• Local transport (shared memory)
• DECnet
• TCP/IP

This section lists the components that makeup the DECwindows Motif layered product and the components that are bundled with the operating system.

1.2.1 DECwindows Motif Layered Product Components

The following components make up the DECwindows Motif layered product:

• Applications
  • Bookreader
  • Calculator
  • Calendar
  • Cardfiler
  • Clock
  • CDA Viewer
  • DECsound
  • DECterm
  • FileView
  • Mail
  • Notepad
  • Paint
  • PrintScreen
• Session management utilities
• Utilities
• Examples
• Libraries
  • Motif toolkit
  • Intrinsics toolkit
  • Xlib
  • Extensions library

The following DECwindows components are bundled with the operating system:

• X server---Consists of a collection of the following shareable images:
  • Main entry-point stub
  • Device-independent server image
  • Device-dependent server image
  • Dynamically loadable extensions
  
  The main image and device-independent server image are directly linked together. During initialization, depending on which graphics devices are available and have been selected, the device-dependent server images are dynamically activated. The loadable extensions are dynamically activated either during initialization for OpenVMS AXP or when they are first used.
• Transport---Consists of a single common image and a collection of transport-specific images.
  The common transport image is built into the display server. Based on transport initialization parameters, one or more of the transport-specific images is dynamically activated.
• Device drivers---The DECwindows display server uses two types of drivers: input drivers and graphics/video drivers.
• Data files---The display server references the following data files:
  • Font files
  • Keymap files that define how keyboard keys are interpreted
  • Color database that defines how color names and RGB values are associated

This chapter describes the DECwindows startup process, which begins when the first DECwindows startup command file executes and continues until the DECwindows Start Session dialog box appears. This chapter contains the following sections:

Topic	Section
System Startup Considerations	Section 2.1
Understanding the Startup Procedure	Section 2.2
Using DECW$STARTUP.COM	Section 2.2.1
Startup Process	Section 2.2.2

2.1 System Startup Considerations

Before starting DECwindows, you may want to make changes or add logicals to the system startup file, SYSTARTUP_VMS.COM, which is located in the SYS$MANAGER directory. (On systems running VMS Version 5.5--2, the startup file is SYSTARTUP_V5.COM.)

Table 2-1 lists each logical name and its meaning.

Table 2-1 System Logicals

Logical Name	Meaning
DECW$IGNORE_DECWINDOWS	Do not start up DECwindows.
DECW$IGNORE_WORKSTATION	Do not perform workstation-specific startup.
DECW$IGNORE_SUBPROCESS	Do not spawn as a subprocess.
DECW$IGNORE_AUTOGEN	Do not verify SYSGEN parameters.
DECW$IGNORE_DECNET	Do not wait for DECnet to start.
DECW$PRIMARY_DEVICE	Use a graphics device on a multihead system.

DECwindows Motif requires that certain system parameters be set to specific or minimum values (For information about these values, see Appendix A). During DECwindows startup, the system checks whether these parameter values are set appropriately. If the values are not set properly, the system prompts you to run AUTOGEN to modify the values.

This section describes the DECwindows Motif startup process. Figure 2-1 illustrates the startup sequence.

Figure 2-1 DECwindows Startup Command Procedure Flow

The DECW$STARTUP.COM procedure is the only DECwindows command procedure with which a system manager invokes directly. This command procedure is used in the following ways:

• Called to startup DECwindows Motif during system startup.
• May be called by a privileged user to restart the display server if required.
• May be called by a privileged user to start the DECwindows server, libraries, or applications. "Starting" the libraries, for example, consists of defining logicals and installing images.

The DECW$STARTUP.COM command procedure takes one parameter. Table 2-2 lists the possible parameter values and the procedure they invoke.

Table 2-2 Startup Parameter Values

P1 Value	Invokes This Procedure	For More Information
" " (null)	Invokes full startup process	See step 1 in Section 2.2.2.
RESTART	Invokes DECW$STARTSERVER.COM	See step 5 in Section 2.2.2.
XTERMINAL	Invokes DECW$STARTXTERMINAL.COM if it exists	See step 4 in Section 2.2.2.
SERVER	Invokes DECW$STARTSERVER.COM	See step 5 in Section 2.2.2.
LIBS	Invokes DECW$STARTLIBS.COM	See step 6 in Section 2.2.2.
APPS	Invokes DECW$STARTAPPS.COM	See step 7 in Section 2.2.2.

2.2.2 The Startup Process

This section describes the events that occur when the DECwindows Motif startup procedure is invoked until the DECwindows Start Session dialog box appears. The startup process is as follows:

1. DECW$LOGICALS.COM is invoked to create the DECW$LOGICAL_NAMES table. DECwindows application startup and configuration parameters are defined in this step.
2. DECW$DEVICE.COM is invoked to load or configure the DECwindows drivers. This procedure also defines the symbols used in subsequent phases of the DECwindows startup sequence. Most importantly, DECW$DEVICE.COM sets the symbol DECW$DEVICE, which contains a list of the graphics devices that the display server attempts to use.
3. DECW$CHECK_PARAMS.COM is invoked. This procedure verifies that all system parameters required during DECwindows startup are set appropriately.
   If one or more parameters are not set correctly, DECW$CHECK_PARAMS.COM displays a list of parameters that need to be modified. The DECW$STARTUP.COM procedure asks whether the user wants to run AUTOGEN. If you invoked DECW$STARTUP.COM with the RESTART parameter, the question displays on the system console.
   If you answer no to this question, DECW$STARTUP.COM displays a message stating that DECwindows cannot start until the system parameters are modified, and exits. If the user answers Yes, DECW$STARTUP.COM runs AUTOGEN from the GETDATA phase to REBOOT. This modifies system parameters and then reboots system.
   To bypass the system parameter check, define the logical name DECW$IGNORE_AUTOGEN before running DECW$STARTUP.COM (see Table 2-1).
4. DECW$STARTXTERMINAL.COM is invoked, if it exists. If the logical DECW$INSTALL_XTERMINAL has been defined in the system startup procedure, the following functions are performed:
   1. Provides client support using the LAT transport
   2. Adds XTDRIVER as class driver for Xlib to communicate to the LT driver
   3. Installs DECW$TRANSPORT_LAT.EXE
   4. Provides font-file sharing through the DECW$FD process
   5. Runs the font daemon process as a detached process
   6. Installs DECnet access gateway server image with SYSNAM privileges
5. DECW$STARTSERVER.COM is invoked to perform the following:
   1. Handle the RESTART option to the DECW$STARTUP procedure. If RESTART is selected, a command file named DECW$KILLSERVERn.COM is created and executed as a detached process with the process name "Server n Restart". This procedure stops the current server process and executes DECW$STARTUP.COM with P1 set to null.
   2. Create the server-specific logical name table DECW$SERVERn_TABLE.
   3. Invoke the server customization file DECW$PRIVATE_SERVER_SETUP.COM. See Section 3.1 for information about how to customize the display server.
   4. Populate the server-specific logical name table based on symbols defined in DECW$DEVICE.COM and DECW$PRIVATE_SERVER_SETUP.COM.
   5. Purge previous versions of the server error log file DECW$SERVER_n_ERROR.LOG.
   6. Check for the logical DECW$SERVER_DUMP that indicates whether the server saves a process dump file when a server crash occurs. Setting this logical disables the server's condition handler.
   7. Check for user-specified server process parameters. See Section 3.2.1 for a list of server process parameters that you can modify.
   8. Determine the server executable name. Normally this is SYS$SYSTEM:DECW$SERVER_MAIN.EXE. An alternative server image executes if:
      • The logical DECW$SERVER_MAIN is defined to point to an alternative server executable file.
      • A file exists with the name SYS$SYSTEM:DECW$SERVER_MAIN_xx.EXE, where xx are the first two letters of the primary graphics device defined by the symbol DECW$DEVICE
      
      Note that an alternate server image is executed only for bug fixes and special hardware releases.
   9. Run the display server image as a detached process using the device name and process parameter information collected.
6. DECW$STARTLIBS.COM is invoked to perform the following:
   1. Defines DECwindows logicals
   2. Installs the Xlib, toolkit, and CDA shared libraries
   3. Connects the WSDRIVER for the DCL command SET DISPLAY

   
   

7. DECW$STARTAPPS.COM is invoked to set up the user application developer environment. This procedure also creates a WSAn: device in executive mode and creates a Start Session dialog box. If you have created the customization command file DECW$PRIVATE_APPS_SETUP.COM, it is invoked here. Use this file to customize the login sequence. See Section 4.3 for information about how to customize application startup.