This chapter provides information about new features and enhancements related to DECwindows Motif system management.

5.1 Installation and Upgrade Information

The following sections describe features that pertain to installing and upgrading DECwindows Motif systems.

5.1.1 Version Checking Available for Command Files

V1.0

The DECwindows Motif kit contains version-checking command procedures that layered products can use during their installation procedure. The following three files are placed in the SYS$UPDATE directory during the installation of DECwindows Motif:

• DECW$GET_IMAGE_VERSION.COM
  A command procedure that extracts the image identification string from an image and places it into a user-defined symbol.
• DECW$COMPARE_VERSIONS.COM
  A command procedure that compares two image identification strings and assigns a value to a user-defined symbol with these possible results:
  • Facility codes do not match.
  • Identifiers are the same.
  • Second identifier is older than the first.
  • Second identifier is newer then the first.
• DECW$VERSIONS.COM
  A command procedure used to display the versions of several components of the DECwindows Motif layered product and the X11 display server. The DECW$VERSIONS.COM procedure uses the DECW$GET_IMAGE_VERSION.COM command procedure to obtain the image idents of each file. Use the following command to display the versions on sys$output:

  $ @SYS$UPDATE:DECW$VERSIONS *

  Component	Description
  DECwindows ident	Xlib shareable image
  DECwindows server	Server DIX file
  DECwindows transport	Transport common
  DECwindows Xlib	Xlib shareable image
  DECwindows OSF/Motif Toolkit	OSF/Motif Xm Toolkit
  DECwindows applications	DECwindows FileView
  DECwindows programming	OSF/Motif UIL compiler

  
  The output from the command procedure shows DW, the version number, and the date the image is created.
  For example:

  DW V1.2-4960312

  
  is version 1.2-4 and was created on March 12, 1996.

This section describes features related to tuning and customizing the DECwindows Motif environment.

5.2.1 Displaying an Expanded Welcome Message

V1.2--6

You can now enter a longer, customized welcome message to be displayed on the Login Screen of the New Desktop. The size of the welcome message string (Dtlogin*greeting.labelString) in XRESOURCES.DAT has been expanded allowing you to enter more than 8 lines of text.

Note that the actual number of lines you can enter and display is limited by the size of the screen and the selected font. However, a minimum of 25 lines is allowed on most display devices.

5.2.2 Setting the File Manager Refresh Rate

V1.2--6

You can now specify that the File Manager periodically update its view on the New Desktop by adjusting the Dtfile.rereadTime setting in the DTFILE.DAT resource file. The value of this setting represents the seconds elapsed between checking for changes in the viewed directories. Note that this setting does not work when viewing search lists.

5.2.3 Displaying Console Messages

V1.2--3

DECwindows Motif for OpenVMS Version 1.2--3 introduced the feature of displaying console messages in the Console Window application. Previous versions of DECwindows Motif displayed the console window by default.

Specify how to display messages by defining the global symbol DECW$CONSOLE_SELECTION in the customized startup file SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM. Enter one of the following values: WINDOW, DISABLE, or ENABLE.

• WINDOW
  Displays console messages in the Console Window application. This is a new application starting with the DECwindows Motif for OpenVMS Version 1.2--3 software. If you specify the WINDOW value, the Console Window is displayed in the lower right corner of the login screen by default and continues to be displayed after the user logs in to the system.
  The Console Window application shares the same executable file and looks similar to the Message Window. However, a menu bar is not displayed in the Console Window; it reads its resources from the DECW$CONSOLE.DAT file instead of from the DECW$MESSAGEPANEL.DAT file. Internally, the Console Window is invoked by running the DECW$MESSAGEPANEL.EXE executable with the command line option -console.
  To control the initial position of the Console Window and the classes of OPCOM output that are enabled, you can the define the DECW$CONSOLE_GEOMETRY global symbol in the file SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM.
  The DECW$CONSOLE_GEOMETRY symbol specifies the value of the -geometry option in the DECW$MESSAGEPANEL.EXE command line; this command is used to start the Console Window application. The default value is "-0-0", which specifies the location of the window in the lower right corner of the screen.
  To position the window at the lower left corner of the screen, for example, add the following line to the command file SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM:

  $ DECW$CONSOLE_GEOMETRY == "+0-0"

• DISABLE (default)
  Disables broadcasts to the OPA0: device. Console messages are not displayed.
• ENABLE
  Displays console messages in the console window. The console window is a six-line display area at the top of the workstation screen.

  Note Although ENABLE was the default value in previous releases of DECwindows Motif, it is recommended that you do not use this option with DECwindows Motif for OpenVMS Version 1.2--3 and later versions. Displaying console messages by default in the console window can corrupt the contents of the workstation display.

The following list describes the related global symbols:

• DECW$CONSOLE_SELECTION
  Specifies how to display operator-messages options.
• DECW$CONSOLE_GEOMETRY
  Specifies the value of the -geometry option in the DECW$MESSAGEPANEL.EXE command line.

Refer to the chapter "Using DECwindows" in Managing DECwindows Motif for OpenVMS Systems for the complete list of global symbols. For information about defining global symbols in the file SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.COM, see Managing DECwindows Motif for OpenVMS Systems.

5.3 Desktop Management

The following sections describe features that pertain to maintaining desktop applications.

5.3.1 Customizing the Login Screen

V1.2

You can customize the DECwindows Motif login screen on the Traditional desktop to display alternate logos or screen colors. To customize the login screen, create a file named DECW$LOGIN.DAT in the SYS$MANAGER directory that contains your resource definitions. The custom resource definitions from SYS$MANAGER:DECW$LOGIN.DAT are merged with the resource definitions supplied by Compaq in SYS$COMMON:[DECW$DEFAULTS.SYSTEM]DECW$LOGIN.DAT to form the new login screen.

Keep customized versions of the DECW$LOGIN.DAT resource file in the SYS$MANAGER directory, and not in DECW$SYSTEM_DEFAULTS, to prevent your customized file from being overwritten when upgraded to a newer version of DECwindows Motif software. In addition, storing the file in the SYS$MANAGER directory prevents the custom file from superseding the file that is supplied by Compaq.

5.3.1.1 Customizing the Compaq Logo and Login Screen Colors

You can define the resources in Table 5-1 to control the position and colors of the Compaq logo and the color of the screen background in the Start Session screen.

Table 5-1 Moving the Compaq Logo and Changing Login Screen Colors

Resource	Description
rootColor	Color of the screen background.
logoColor	Color of the Compaq logo (default is burgundy).
logoX	x position of the Compaq logo (default is 0).
logoY	y position of the Compaq logo (default is 75).
centerLogoX	Boolean; if true (default), the Compaq logo is centered horizontally on the screen.

For example, to position the Compaq logo at x=100, y=600, add the following resource definitions to the SYS$MANAGER:DECW$LOGIN.DAT file:

decw$login.logoX: 100 decw$login.logoY: 600 decw$login.centerLogoX: false

5.3.1.2 Changing Positions of the Start Session and Set Password Dialog Boxes

You can define the resources in Table 5-2 to control the position of the Start Session and Set Password dialog boxes.

Table 5-2 Changing Position of the Start Session and Set Password Dialog Boxes

Resource	Description
centerStartSessionX	Boolean; if true (default), the Start Session dialog box is centered horizontally.
centerStartSessionY	Boolean; if true (default), the Start Session dialog box is centered vertically.
centerSetPasswordX	Boolean; if true (default), the Set Password dialog box for expired passwords is centered horizontally.
centerSetPasswordY	Boolean; if true (default), the Set Password dialog box is centered vertically.

For example, to position the Start Session dialog box at x=100, y=600, add the following resource definitions to the SYS$MANAGER:DECW$LOGIN.DAT file:

decw$login.centerStartSessionX: false decw$login.centerStartSessionY: false decw$login.HiddenShell.x: 100 decw$login.HiddenShell.y: 600

To position the Set Password dialog box at x=30, y=100, add the following resource definitions to the SYS$MANAGER:DECW$LOGIN.DAT file:

decw$login.centerSetPasswordX: false decw$login.centerSetPasswordY: false decw$login.SetPasswordShell.x: 30 decw$login.SetPasswordShell.y: 100

5.3.1.3 Disabling a Node Name Display in the Start Session Dialog Box

To prevent a node name from being displayed in the Start Session dialog box, add the following resource definition to the SYS$MANAGER:DECW$LOGIN.DAT file:

decw$login.displayNodeName: false

This chapter describes new features relating to application and system programming in the DECwindows Motif environment.

6.1 X Window System Library (Xlib)

The following sections describe features related to X Window System library (Xlib).

6.1.1 UIDPATH Environment Variable

V1.2--6

When opening a hierarchy, DECwindows Motif searches the DECW$USER_DEFAULTS and DECW$SYSTEM_DEFAULTS areas for the User Interface Definition (UID) file. On UNIX systems, the search path is defined using the UIDPATH variable and its fallbacks.

Now DECwindows Motif also checks for the UIDPATH variable if the UID file is not found using either of the OpenVMS symbols listed above. This variable references a UNIX-style pathname (for example, /foo/bar) and allows the substitutions strings as specified by X11 standards. For more information on the UIDPATH variable, see the OSF/Motif Programmer's Reference.

V1.1

Starting with DECwindows Motif for OpenVMS Version 1.1, Xlib added a client side library, DECW$XEXTLIBSHR.EXE, that allows OpenVMS clients to issue Shape, XInput, Multibuffer, and Shared Memory extension requests to servers that provide these features.

You must modify the linking file options for client applications that issue these extension requests to link to the Xlib extensions shareable image in SYS$LIBRARY:DECW$XEXTLIBSHR.EXE. Add the following line to your linker options file:

SYS$LIBRARY:DECW$XEXTLIBSHR/SHARE

For more information on Shape, XInput, and Multibuffer extensions, see the following text files in SYS$HELP:

• DECW$SHAPE.TXT
• DECW$XINPUT.TXT
• DECW$MULTIBUFFER.TXT

The following sections describe features related to X Window System toolkit (Xt).

6.2.1 New Default Format for XtResolvePathname

V1.2--6

In XtResolvePathname, the default pathname is required to have certain properties when either no other path information is present in the call, or when it is referenced by the environment variable XFILESEARCHPATH. The former default OpenVMS format of the pathname consisted of a type-name-suffix substitution. The modified pathname now reflects the 6-part fallback, as specified by X11 Release 6.

The new pathname behavior is enabled by setting the DECW$VSW_COMPLIANT variable, as follows:

$ DEFINE DECW$VSW_COMPLIANT 1

6.2.2 XtAppMainLoop Routine

V1.2--5

Previously, if a program entered its event loop, (for example, by calling XtAppMainLoop) without having opened a display or specified a timer or event flag for the program to wait for (by calling XtAppAddTimeout or XtAppAddInput), Xlib terminated the program with the following error message:

X Toolkit Error: Error in XMultiplexInput

Starting with DECwindows Motif for OpenVMS Version 1.2--5, if there is nothing to wait for, Xlib stalls waiting for input instead of terminating with an error status.

To allow Xlib to process events at a later time, applications should provide some means of regaining control, such as specifying an event flag (on DECwindows Motif for OpenVMS Version 1.2--6 and previous systems) or a logical connection number (on HP DECwindows Motif for HP OpenVMS Alpha Version 1.3 and higher systems) by calling XtAppAddInput.

6.3 X Window System Extensions

V1.2

On OpenVMS Alpha systems, shared memory extension support provides the capability to share memory XImages. This is a version of the XImage interface where the actual image data is stored in a shared-memory segment. Consequently, the image does not need to be moved through the Xlib interprocess communication channel. For large images, use of this extension can result in dramatic performance increases.

Support for shared memory pixmaps is also provided. Shared memory pixmaps are two-dimensional arrays of pixels in a format specified by the X server, where the image data is stored in the shared memory segment. Through the use of shared memory pixmaps, you can change the contents of these pixmaps without using any Xlib routines.

These routines are included in the client side extension library. See Section 6.1.2 for details on linking this library.

6.3.1.1 How to Use Shared Memory Extension

Code that uses the shared memory extension must include the following header files:

# include "DECW$INCLUDE:Xlib.h" # include "DECW$INCLUDE:shm.h" # include "DECW$INCLUDE:XShm.h"

Any code that uses the shared memory extension should first check that the server provides the extension. In some cases, such as running over the network, the extension does not work.

To check if the shared memory extension is available on your system, call one of the following routines:

Status XShmQueryExtension (display) Display *display

Status XShmQueryVersion (display, major, minor, pixmaps) Display *display; int *major, *minor; Bool *pixmaps

The following table lists each argument and its description.

Argument	Description
display	The current display. If the shared memory extension is used, the return value from either function is True. Otherwise, your program operates using conventional Xlib calls.
major	Major version number of the extension implementation. Returned by XShmQueryVersion.
minor	Minor version number of the extension implementation. Returned by XShmQueryVersion.
pixmaps	True, indicates that shared memory pixmaps are supported.

6.3.1.2 Using Shared Memory XImages

The following sequence shows the process for creating and using shared memory XImages:

1. Create the shared memory XImage structure.
2. Create a shared memory segment to store the image data.
3. Attach the shared memory segment.
4. Inform the server about the shared memory segment.
5. Use the shared memory XImage.

The following sections explain each step in this process:

Step 1---Creating a Shared Memory XImage Structure

To create a shared memory XImage, use the XShmCreateImage routine, which has the following format:

XImage *XShmCreateImage (display, visual, depth, format, data, shminfo, width, height) Display *display; Visual *visual; unsigned int depth, width, height; int format; char *data; XShmSegmentInfo *shminfo;

Most of the arguments are the same as for XCreateImage (See the X Window System for a description of the XCreateImage routine.) Note that there are no offset, bitmap_pad, or bytes_per_line arguments. These quantities are set by the server, and your code needs to abide by them. Unless you have already allocated the shared memory segment (see step 2), you pass in NULL for the data pointer.

The argument shminfo is a pointer to a structure of type XShmSegmentInfo. Allocate one of these structures so that it has a lifetime at least as long as that of the shared memory XImage. There is no need to initialize this structure before the call to XShmCreateImage.

If successful, an XImage structure is returned, which you can use for the subsequent steps.

Step 2---Creating the Shared Memory Segment

Create the shared memory segment after the creation of the XImage because the XImage returns information that indicates how much memory to allocate.

The following example illustrates how to create the segment:

shminfo.shmid = shmget (IPC_PRIVATE, image->bytes_per_line * image->height, IPC_CREAT|0777);

This example assumes that you called your shared memory XImage structure. A return value of 0 indicates the shared memory allocation has failed. Use the bytes_per_line field, not the width you used to create the XImage, as they may be different.

Note that the shared memory ID returned by the system is stored in the shminfo structure. The server needs that ID to attach itself to the segment.

Step 3---Attaching the Shared Memory Segment

Attach the shared memory segment to your process as in the following example:

shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0);

The address returned by shmat is stored in both the XImage structure and the shminfo structure.

To finish supplying arguments in the shminfo structure, decide how you want the server to attach to the shared memory segment, and set the shminfo.readOnly field as follows:

shminfo.readOnly = False;

If you set the structure to True, the server cannot write to this segment, and XShmGetImage calls fail.

Step 4---Informing the Server About the Shared Memory Segment

Tell the server to attach to your shared memory segment as in the following example:

Status XShmAttach (display, shminfo);

If successful, a nonzero status is returned, and your XImage is ready for use.

Step 5---Using the Shared Memory XImage

To write a shared memory XImage into an X drawable, use the XShmPutImage routine. The XShmPutImage routine uses the following format:

XShmPutImage (display, d, gc, image, src_x, src_y, dest_x, dest_y, width, height, send_event) Display *display; Drawable d; GC gc; XImage *image; int src_x, src_y, dest_x, dest_y; unsigned int width, height; Bool send_event;

The interface is identical to the XPutImage routine (see the X Window System), except for one additional parameter, send_event. If this parameter is passed as True, the server generates a completion event when the image write is complete. This allows your program to know when it is safe to begin manipulating the shared memory segment again.

The completion event is of the type XShmCompletionEvent, which is defined as follows:

typedef struct { inttype; /* of event */ unsigned long serial; /* # of last request processed */ Bool send_event; /* true if came from a SendEvent request */ Display *display; /* Display the event was read from */ Drawable drawable; /* drawable of request */ int major_code; /* ShmReqCode */ int minor_code; /* X_ShmPutImage */ ShmSeg shmseg; /* the ShmSeg used in the request */ unsigned long offset; /* the offset into ShmSeg used */ } XShmCompletionEvent;

To determine the event type value that is used at run time, use the XShmGetEventBase routine as in the following example:

int CompletionType = XShmGetEventBase (display) + ShmCompletion;

To read image data into a shared memory XImage, use the XShmGetImage routine, which uses the following format: