The X Session Management Protocol (XSMP) provides a standard way for users to save client sessions. Each session is controlled by a network service known as the session manager. The session manager issues commands that direct client applications to save their state information for use during subsequent sessions.

This protocol is built on top of ICE, which manages the client connections to the session manager server.

Code that uses XSMP must include the following header files:

# include "DECW$INCLUDE:SM.h" # include "DECW$INCLUDE:SMlib.h" # include "DECW$INCLUDE:SMproto.h"

The following sections describe the implementation of XSMP provided with HP DECwindows Motif for HP OpenVMS Alpha Version 1.3, highlighting any variances from or restrictions posed by the standard implementation. For a detailed description of the XSMP protocol and the available server requests, see the X Window System (Scheifler and Gettys) series of manuals published by Butterworth-Heinemann, or visit the X.Org web site (http://www.x.org) for the X Window System protocol and library specifications.

3.5.4.1 Multithreading Considerations

The implementation of XSMP is thread safe, using locks on the underlying ICE connection as needed. All send message operations are thread cancellation points; all callback operations are made by locking the associated ICE connection.

When SmcOpenConnection is called, it opens an ICE connection and processes messages until the session manager registers the client. The open connection subsequently causes a series of ICE watch procedures to be called. Typically, these procedures add the connection to a list monitored for input. IceProcessMessages is called when input to the list arrives. The thread issuing the IceProcessMessages calls will be blocked if it tries to handle a new connection.

3.5.4.2 Differences from the Standard Implementation

The following sections describe differences from and issues in the standard XSMP implementation provided with X11R6.6.

SmcCloseConnection and SmsCleanUp

In the standard implementation, SmcCloseConnection disables shutdown negotiation for an ICE connection, which results in abrupt termination of the connection. This can prevent the session manager from receiving all SmCloseConnection messages.

In the DECwindows Motif implementation, shutdown negotiation is enabled. SmcCloseConnection returns SmcClosedASAP, and the connection is closed only after the session manager calls SmsCleanUp.

Note also that the sample session manager code does not specify whether SmsCleanUp closes an ICE Connection. In the DECwindows Motif implementation, an IceCloseConnection call is issued.

POSIX Property Names and Data Type Definitions

The standard specification defines the data types and property names supported for POSIX. The DECwindows Motif implementation specifies the property names; however, the data types definitions are not provided, since they may vary based on the use of session manager in the OpenVMS Alpha environment.

This chapter provides information about new features that pertain to all users of DECwindows Motif.

4.1 General DECwindows Motif Environment

This section describes new features that are common to both the New Desktop and traditional DECwindows desktop environments.

4.1.1 Extended File Specification (EFS) Support

V1.2--5

In general, DECwindows Motif supports the Extended File Specifications (EFS) option provided in OpenVMS Alpha. The interface either supports the new ODS-5 file names or provides an error message indicating that the particular component does not support the new names.

4.1.1.1 File Selection Popup Window

The standard file selection popup window used by most DECwindows Motif applications fully supports ODS-5 style file names. The window supports deep directories, case preservation, and extended-length file names. The window supports entry of file names using the extended file name character and displays files using the extended file name character set using the circumflex character (^). See the current OpenVMS documentation for more specific information about using deep directories and the extended file name character set.

4.1.1.2 New Desktop and the FileView Application

With an ODS-5 volume, the FileView application supports deep directories, case preservation, and extended-length file names. FileView supports entry of file names using the extended file name character and displays files using the extended file name character set using the circumflex character (^). See the current OpenVMS documentation for more specific information about using deep directories and the extended file name character set.

Any custom FileView command extensions must be modified to support EFS.

4.1.1.3 Traditional Desktop and the File Manager Application

The File Manager application supports case preservation and creates files with the extended file name character set, but does not support any operations on its files.

The File Manager application supports deep directories and extended-length file names with the following restriction. As indicated in the OpenVMS Guide to Extended File Support, ODS-5 volumes allow file names up to 236 8-bit characters in length and deep directory structures if the total file specification does not exceed 512 8-bit characters in length. The current version of the File Manager supports extended-length file names and deep directory structures with the additional restriction that a total file specification cannot exceed 235 8-bit characters in length. Exceeding this limit causes an error message for some menu items.

4.1.1.4 The Programming Libraries

The programming libraries fully support deep directories and extended-length file names. However, the libraries do not support case preservation or the extended file name character set.

4.1.1.5 Translated Image Support (TIS) Library

The translated image support (TIS) library has not been updated to support EFS.

4.1.2 Color Customizer Example Program

V1.2

The color customizer example program allows you to dynamically control the colors of your workstation environment. Window, icon, and window manager colors can be changed individually or as part of a palette switch. You can control mapping between resources and color cells, as well as the size and contents of the palette set. Also, automatic shadowing with the standard Motif shadowing algorithms is supported.

4.1.2.1 Supported Displays

The color customizer supports any display using pseudocolor or grayscale visuals. This includes most 4- and 8-plane workstation displays.

4.1.2.2 Supported Applications

The color customizer can affect the colors of any applications that use the current release of the DECwindows X Toolkit Library. Applications from other vendors and previous versions of the X Toolkit Library are unaffected.

To build the color customizer on OpenVMS systems, perform the following steps:

1. Copy the files to a private directory. For example:

   $ SET DEFAULT SYS$LOGIN $ CREATE/DIRECTORY [.CUSTOMIZER] $ SET DEFAULT [.CUSTOMIZER] $ COPY DECW$EXAMPLES:CUSTOM.C [] $ COPY DECW$EXAMPLES:CUSTOM.UIL [] $ COPY DECW$EXAMPLES:CUSTOMIMAGE.DAT [] $ COPY DECW$EXAMPLES:XSETROOT_CUST.C [] $ COPY DECW$EXAMPLES:BUILD_CUSTOMIZER.COM []

2. Build the customizer using the following command:

   $ @BUILD_CUSTOMIZER.COM

This command procedure creates the following output files:

• CUSTOM.UID
• CUSTOM.EXE
• XSETROOT_CUST.EXE

To run the color customizer, perform the following steps:

1. Copy the files CUSTOM.UID and CUSTOM.EXE, which were created during the customizer build, to the directory where the customizer will be run. A typical location is the directory SYS$LOGIN or the directory DECW$USER_DEFAULTS.
2. Copy the files CUSTOM.DAT and DXMDEFAULTS.DAT from the directory DECW$EXAMPLES to the directory DECW$USER_DEFAULTS.
3. Run the executable file CUSTOM.EXE as follows:

   $ RUN CUSTOM

As noted in Section 4.1.2.4, the color customizer should be the first X application started during the login process. Do this by starting it as a subprocess from within the DECW$LOGIN.COM file. Add a command to wait approximately 10 seconds between customizer startup and the startup of other applications.

For example, add the following lines to the DECW$LOGIN.COM file:

$! Starting the color customizer $ DISPLAY = F$LOGICAL("DECW$DISPLAY") $ SPAWN/NOWAIT/OUTPUT='DISPLAY' RUN SYS$LOGIN:CUSTOM.EXE $ WAIT 0:0:10

See Using DECwindows Motif for OpenVMS and Managing DECwindows Motif for OpenVMS Systems for more information on the file DECW$LOGIN.COM.

4.1.2.6 Command Interface Summary

A box containing a list of available palettes is in the leftmost section of the Color Customizer window. Click on the desired palette to see the colors take affect.

Below the palettes are two arrays of colored buttons, representing the dynamically allocated color cells for normal and shadow colors. To find out what resources are affected by a color cell, click and hold the arrow button next to the color cell.

To modify a single color cell, click on the corresponding color button. A colormix widget pops up; as you modify the color, these modifications are reflected in your workstation environment. Use the colormix widget reset button to return to the starting color at any time. You can also change the color cell you are modifying by clicking on a different color button while the colormix widget is displayed.

The automatic shadowing option causes shadow and select colors to be automatically updated when their corresponding background colors are changed. The standard Motif shadowing algorithms are used for these calculations.

Use the File menu to modify, add, and delete color palettes as follows:

• To modify an existing palette, select the palette, change the colors, and choose Save Palette from the File menu.
• To add a new palette, select an existing palette, modify the colors as necessary, and choose Save Palette As... from the File menu. A message box prompts you for the name of the new palette.
• To delete a palette, select the palette and choose Delete Palette from the File menu.

Changes made through the File menu automatically update the CUSTOM.DAT file, which contains the resource defaults.

The File menu Exit button causes the customizer application to exit. A warning dialog is displayed first. Note that the color cells allocated by the customizer (and used by the currently running applications) will be deallocated. After the customizer exits, if the colors of the currently running applications are not correct, the applications should be restarted to restore normal colors. Usually, there is no need to exit the color customizer; it is typically kept running at all times, like the Session Manager.

4.1.2.7 Changing the Mapping Between Color Resources and Color Cells

The file DXMDEFAULTS.DAT allows you to control how many dynamic color cells are allocated and what resources are affected. This file contains resource specifications like the following:

*background: DXmDynamicWindowBackground *foreground: DXmDynamicWindowForeground *topShadowColor: DXmDynamicWindowTopShadow

When the customizer is started, the file DXMDEFAULTS.DAT is written to a property on the root window. Any application that is subsequently run and that uses the correct X Toolkit Library merges these resources with its normal resource database. Resource specifications in this file take precedence over specifications with equivalent resource names in other resource default files.

The resource values within the file DXMDEFAULTS.DAT have a special format. For each unique color value in this file that begins with the string "DXmDynamic", a color button is created in the color customizer. If the string "Shadow" is encountered in a name, the color button is placed in the shadow button box rather than the normal color button box. If a color value string ends with the suffix "Background", it is linked to any color buttons with identical prefixes and suffixes of "TopShadow", "BottomShadow", or "SelectColor" for purposes of automatic shadowing. If a color value named "DXmDynamicScreenBackground" is encountered, the color cell allocated is used by the customizer to set the root window background color.

You can edit the file DXMDEFAULTS.DAT and define resources to use the same color cells. You can have separate dynamic color cells, for scrollbar widgets or for your DECwindows Mail application, for example, by adding the following lines to the file DXMDEFAULTS.DAT:

Mail*background: DXmDynamicMyMailBackground Mail*foreground: DXmDynamicMyMailForeground Mail*topShadowColor: DXmDynamicMyMailTopShadow Mail*bottomShadowColor: DXmDynamicMyMailBottomShadow

Adding the previous lines to the file DXMDEFAULTS.DAT and restarting the customizer causes four new color cells to be allocated and four new color buttons to be added to the customizer interface. These buttons are assigned default color values (usually black or white) for each palette. These defaults can then be modified for each palette through the customizer interface.

To change the colors of DECterm windows, copy the DECterm resource specifications from the file DXMDEFAULTS.DAT and add them to the DECterm resource defaults file DECW$USER_DEFAULTS:DECW$TERMINAL_DEFAULT.DAT. For example, add the following lines to the DECterm resource defaults file:

. . . DECW$TERMINAL.main.terminal.background: DXmDynamicTerminalBackground DECW$TERMINAL.main.terminal.foreground: DXmDynamicTerminalForeground

This allows the DECterm window colors to be customized with the color customizer.

4.1.2.9 Changing the Default Value of the Automatic Shadowing Toggle Button

The default value of the automatic shadowing toggle button is set using the Custom.autoShadow resource in the CUSTOM.DAT file as follows:

Custom.autoShadowing: False

The default value is True.

4.1.2.10 Using the Customizer on Multihead Systems

The color customizer affects only applications started on the same screen as the customizer. On most multihead systems, you can start a different color customizer for each screen and have a different palette in effect on each screen. On multihead systems using XINERAMA, a single instance of the color customizer affects all applications, since the screens function as a single logical screen.

The color customizer can be configured so that it is invoked once and affects all applications regardless of where they are started. This mode is invoked by modifying the Custom.multiScreen resource in the CUSTOM.DAT file as follows:

Custom.multiScreen: True

The default value is False.

4.1.2.11 Using the XSETROOT_CUST.EXE Demonstration Program

The XSETROOT_CUST.EXE demonstration program, created during the customizer build, is a modified version of the MIT utility program xsetroot that is used to set a bitmap on the root window. The XSETROOT_CUST.EXE program uses DXmDynamicScreenBackground and DXmDynamicScreenForeground as the background and foreground colors of the specified bitmap. If your DXMDEFAULTS.DAT file contains entries for these two dynamic colors, then use the customizer to dynamically modify the colors of your bitmap.

For example:

$ XSETROOT_CUST :== "$SYS$LOGIN:XSETROOT_CUST.EXE" $ XSETROOT_CUST -BITMAP your_xbm_file.XBM

4.1.3 Drag and Drop Support

V1.2

The drag-and-drop feature lets you move or copy screen objects. This feature is provided primarily for programmers who choose to incorporate drag-and-drop into their applications. For example, you can move text from a text entry area and paste it elsewhere.

All DECwindows Motif applications except Notepad support the drag-and-drop feature. DECwindows Mail supports the drag-and-drop feature in all windows except the main message area, where DECwindows Mail has its own drag-and-drop; you can use MB2 to move messages around with the SVN interface.

To drag and drop text into a new location:

1. Select the text to be copied or moved with MB1.
2. To move the text, press and hold MB2; to copy the text, press and hold Ctrl/MB2.
   A move or copy icon appears.
3. Drag the icon to the location where you want to drop the text and release MB2.
   If the object is highlighted as you drag the icon across it, you can drop the text into that location.

For a list of the widgets that support drag-and-drop functionality, see Section 6.5.1.

4.1.4 Tear-Off Menu Support

V1.2

Most DECwindows Motif applications allow you to tear off pull-down and popup menus. Tear-off menus let you keep frequently used menus displayed without repeatedly pulling them down or popping them up.

To tear off a menu:

1. Display a pull-down or popup menu.
   If the menu is a tear-off menu, a dotted line is displayed at the top of the menu.
2. Click on the dotted line with MB1.
   The menu remains active until it is closed or until the parent application is closed.

To close a tear-off menu:

1. Click on the Window menu button in the tear-off menu.
2. Choose the Close menu item.

This section describes new features related to the New Desktop environment.

4.2.1 Screen Saver and Screen Lock Support

V1.2--6

New Desktop now supports the MIT Screen Saver extension (MIT-SCREEN-SAVER), which is available on systems running on OpenVMS Alpha Version 7.1 or greater. This extension enables you to use the following features, which are available from the Style Manager Screen dialog box:

• Screen saver---Prevents screen burn-in by displaying one or more screen savers after a specific timeout period. You can set both the timeout period and the amount of time each screen saver is displayed onscreen.
  Sample screen savers are available from CDE$SYSTEM_DEFAULTS:[EXAMPLES.DTSCREEN]. To learn how to create additional screen savers and make them available to the Style Manager, see Getting Started With the New Desktop.
• Screen lock---Secures your current New Desktop session(s) by locking the Front Panel after a specific timeout period. Once locked, a user must enter the account password of the home session password to unlock the desktop.

For more information on using the screen saver and screen lock components of the Style Manager, see the online help for the Style Manager application.

4.2.2 Updated Welcome Message

V1.2--6

The welcome message in the Login Screen now displays a host name regardless of the transport. If the DECnet transport is configured, the DECnet host name is displayed. If the TCP/IP transport is configured, the TCP/IP host name is displayed. If neither transport is configured, a default message of "Welcome to OpenVMS" is displayed.