HP OpenVMS Systems Documentation

The following new parameter replaces the symbol DECW$SERVER_CONNECT_LOG and provides additional options for controlling the content of the X server audit logs.

DECW$SERVER_AUDIT_LEVEL

This parameter controls whether normal client connect/disconnect messages are logged in the error log file for the server. Valid values for this parameter are:

• 0 (disabled)
• 1 (enabled)
• 2 (enabled with success messages)
• 4 (enabled with security logging)

The default value is 0.

The following parameter definition enables minimal audit logging:

Example

$ DECW$SERVER_AUDIT_LEVEL == "1"

V1.3

Since some combinations of X server extensions present a function or resource conflict if enabled concurrently, two new parameters (DECW$SERVER_EXTENSIONS and DECW$SERVER_DISABLE_TEST) have been added to the server startup file. These parameters allows you to control which groups of extensions are loaded and enabled on one or more servers. Each dynamically loadable extension specified by these symbols is converted to a shareable image, which is run at server startup.

To load and enable a set of extensions, modify the parameter definitions in the DECW$PRIVATE_SERVER_SETUP.COM file, and restart the server. For example, to enable XIE and XINERAMA, add the following line to the file:

$ DECW$SERVER_EXTENSIONS == "XIE,XINERAMA"

See Section 3.7.2.1 for a detailed description of the valid values for these parameters. For the current list of unsupported combinations of X server extensions, see the HP DECwindows Motif for OpenVMS Alpha Release Notes.

3.7.4 Support for Multihead Systems Using XINERAMA

V1.3

The XINERAMA extension enables you to connect multiple monitors to a single Alpha system running DECwindows Motif for OpenVMS Alpha Version 1.3 or higher to create a unified virtual display. In contrast to the traditional way of configuring multiheaded Alpha systems, described in Managing DECwindows Motif for OpenVMS Systems, XINERAMA provides more control over the arrangement of the screens and desktop. Under a multiheaded display that uses XINERAMA, you can customize the number, order, and configuration of each screen in the display, and drag windows and text from screen to screen on the desktop.

The following sections describe how to configure a multiheaded Alpha system using XINERAMA.

3.7.4.1 Hardware and Configuration Requirements

XINERAMA is supported only in a homogeneous graphics environment. Each multiheaded configuration must consist of common video cards, bit depths, visual classes, screen resolutions, and monitors of a similar size.

See the HP DECwindows Motif for OpenVMS Alpha Software Product Description for a list of the currently supported video graphics cards; see Managing DECwindows Motif for OpenVMS Systems for a description of the logicals you can use to change the default values for these graphics settings.

The X server supports up to 16 monitors in a multiheaded configuration. Note that the actual number of monitors you can use may be further limited by the number of available option card slots.

3.7.4.2 Setting Up a Multiheaded Alpha System

Configuring a multiheaded system using XINERAMA involves the following steps:

1. Disable VGA Services
2. Install the Video Cards
3. Enable XINERAMA
4. Arrange and Configure the Monitors

The following sections describe this process.

Step 1: Disable VGA Services

Some video cards can dynamically disable or enable VGA services as necessary, but others require that you manually disable VGA via a jumper setting on the video card. Refer to the documentation for your video cards to determine if this change is required. If so, make this change prior to installing the cards in your Alpha system.

Step 2: Install the Video Cards

Shut down the OpenVMS Alpha system and install the video cards, as instructed by the hardware documentation.

Turn the power back on and reboot the operating system. During startup, the OpenVMS Alpha operating system will verify that the video cards were installed correctly.

Step 3: Enable XINERAMA

Although this extension is part of the X server, it is not enabled by default. To enable XINERAMA:

1. Edit the DECW$PRIVATE_SERVER_SETUP.COM file.
2. Search for and define the parameter DECW$SERVER_EXTENSIONS so that it includes a value of "XINERAMA." For example:

   $ DECW$SERVER_EXTENSIONS == "DEC-XTRAP,XINERAMA"

3. Save the file and restart the server.

Step 4: Arrange the Monitors

By default, the system uses the physical location of the video cards on the system bus to assign the device names (such as, GYA0, GYB0, etc.) and subsequently number the screens. For example in a four-monitor multihead configuration, if you have connected the cables to the video cards in the proper order and placed the monitors placed side-by-side, the screens could be numbered in either ascending (0, 1, 2, 3) or descending (3, 2, 1, 0) order.

If the screens are not in the desired order, you can do one of the following depending on your screen configuration:

• Physically move the monitors to the correct placement.
• Reconnect the cables in the correct order.
• Edit the DECW$PRIVATE_SERVER_SETUP.COM file and define the DECW$SERVER_SCREENS parameter so that it overrides the default screen order.

Once the screens are in the appropriate order, you can further customize the virtual display using the following edge attachment parameters in DECW$PRIVATE_SERVER_SETUP.COM:

• DECW$SERVER_EDGE_LEFT
• DECW$SERVER_EDGE_RIGHT
• DECW$SERVER_EDGE_TOP
• DECW$SERVER_EDGE_BOTTOM

These parameters, described in Section 3.7.2.2, control where each edge of the virtual display is attached.

When the setup process is complete, all the monitors should be active and organized in the proper arrangement. Once you restart DECwindows Motif, the login dialog box for the session is displayed at the center of the virtual display, and you should be able to open application windows and drag them from screen to screen.

This chapter describes new features relating to application and system programming in the DECwindows Motif environment. This includes extensions, libraries, and functions made available as part of the X11R6.6 implementation as well as those that are specific to the DECwindows Motif environment.

For information on how to program X Window System applications, see the X Window System and X Window System Toolkit (Scheifler and Gettys) series of manuals published by Butterworth-Heinemann.

4.1 General Run-Time and Programming Environment

The following sections describe features related to general DECwindows Motif programming environment.

4.1.1 Multithreading Support

V1.3

DECwindows Motif now supports multithreaded client applications. Client applications that use the HP POSIX Threads Library or HP Ada tasks are now fully supported in the DECwindows Motif for OpenVMS Alpha Version 1.3 or higher environment.

Additionally, each of the following libraries are now fully thread-safe, supporting simultaneous calls from multiple threads:

• X11 library (Xlib)
• X Toolkit intrinsics library (Xt)
• X Extensions library
• Inter-Client Exchange (ICE) library
• Session Management Protocol (XSMP) library

Client applications linked against previous versions of DECwindows Motif are binary compatible, with the exception of those applications that use any changed or retired Xlib entry points documented in this manual and the HP DECwindows Motif for OpenVMS Alpha Release Notes.

Existing applications require recompilation against the X11R6.6-compatible X Window libraries if they produce a shared image potentially used by other multithreaded applications and that image uses:

• Any of the following macros defined in DECW$INCLUDE:XLIBINT.H and is intended for use in a multithreaded environment:
  • LockDisplay
  • UnlockDisplay
  • LockMutex
  • UnlockMutex
• The ConnectionNumber macro or XConnectionNumber function and assumes the return value is an event flag.

Note that recompiling unmodified applications (those that use the previous version of the CompositeClassExtensionRec structure) against the updated library functions may generate Xt warning messages.

4.1.2.1 Use of Asynchronous System Traps (ASTs)

In the past, DECwindows Motif supported application calls from user-mode and normal-mode AST handlers. With DECwindows Motif for OpenVMS Alpha Version 1.3 and higher, applications calls from AST handlers are only supported for existing, unmodified applications (compiled against the X11R5 libraries).

New applications compiled against the X11R6.6 libraries should not call Xlib functions (other than XtNoticeSignal) from AST handlers even in single-threaded environments.

Applications compiled against the updated libraries should either use multiple threads if a higher level of concurrency is required or call XtNoticeSignal so that AST events are processed in the Xt main loop.

4.1.2.2 Levels of Thread Safety and Concurrency

New and existing DECwindows Motif shared images can be grouped according to the following levels of thread safety:

• Thread-safe--The image can be called concurrently from multiple threads.
• Thread-aware--The image can be used in an application that includes multiple threads. However, the application code must avoid making concurrent calls to the image, typically by using a global lock.
• Thread-unsafe--The image cannot be used in any application that has multiple thread support enabled.

Table 4-1 shows the current thread safety level for each of the DECwindows Motif shared images. Note that all images in the Translated Image Environment are thread-unsafe.

In addition to thread safety, the updated libraries offer varying levels of concurrency when called from multiple threads:

• X and X Extension libraries
  For most operations, Xlib and X Extension libraries allow a single concurrent operation on each display connection. If XOpenDisplay is called twice to open two separate server connections, both connections can be operated upon at the same time. However, there are a few operations for which a global lock is needed to prevent corruption of global data.
  Note that XSelectAsyncInput and XSelectAsyncEvent are not supported if multithreading has been enabled by a call to XInitThreads. In general, use of XSelectAsyncEvent and XSelectAsyncInput is discouraged since they are non-standard functions. The equivalent functionality can be obtained by using threaded Xlib functions.
• X Toolkit Intrinsics library
  For most operations, Xt allows a single concurrent operation on each application context. There are a few operations for which a global lock is needed to prevent corruption of global data.
• Inter-Client Exchange and Session Manager libraries
  ICE and XSMP operations allow a single concurrent operation on each ICE connection.
• Transport library
  The transport library is used to communicate between the client application and the X server and between multiple client applications that use the ICE library. The final level of the transport code (which can communicate via global sections, DECnet, or TCP/IP) executes in OpenVMS inner mode, and as a result is serialized by the operating system.
  Running on only one kernel thread at a time, this code temporarily blocks all other kernel threads making OpenVMS system calls that execute in inner mode. However, whenever the transport code is blocked, such as when waiting for a connection to open or for a reply to arrive, it is blocked at user mode allowing other threads to execute and use the transport.

To enable multithreading, a client application must include initial calls to the multithreading functions in Table 4-2. The specific functions called by the application depend on the shared image(s) in use.

Note that IceInitThreads and XInitThreads implicitly call DECW$LCN_THREAD_INIT. The interface to DECW$LCN_THREAD_INIT is described in Section 4.2.2.

These functions have no arguments and return a success status upon successful initialization. To ensure successful initialization, be sure to:

• Link the image with threads.
• Verify there is adequate process memory.
• Issue the initialization call prior to making any other call.

In addition to calling one of the multithreading functions, a client application must also be linked against the POSIX Threads Library. For example:

$  LINK THREAD_ICO/THREADS SYS$INPUT/OPT
SYS$LIBRARY:DECW$XLIBSHR/SHARE
SYS$LIBRARY:PTHREAD$RTL/SHARE

Explicit links against the threads library are not required if the application calls POSIX thread functions (such as, pthread_create).

4.1.2.4 Developing Applications with Thread-Aware Images

If a thread-aware image is used in a multithreaded application, the image must not accept concurrent calls nor make calls to other images that could change the state of the thread-aware image.

Note that if a thread-aware application uses the XtAppMainLoop or XtMainLoop function for dispatch handling, calls to the image will be made from callback functions. Xt makes these callbacks with an exclusive lock held on the application context. To avoid conflicts and deadlocks, applications that use a thread-aware image should include calls to XtAppLock before and XtAppUnlock after each call, or sequence of calls, to the image. The application must also call XtProcessLock and XtProcessUnlock to protect the thread-aware image against changes made by Xt to process global data.

In the following example, an application contains a background thread that constantly checks for error situations and displays an error message when a problem occurs. The main program thread first initializes thread support, creates the application context, creates the background thread, and then enters the Xtmain loop:

        static XtAppContext app_context;

int main ()
{
    .
    .
    .
    MrmInitialize ();
    XInitThreads ();
    XtToolkitThreadInitialize();
    XtToolkitInitialize();
    app_context = XtCreateApplicationContext();
    .
    .
    .
    pthread_create (&thread, 0, backgroundCode, 0);
    .
    .
    .
    XtAppMainLoop(app_context)
}

Code for the background thread is as follows:

void* backgroundCode (void* data)
{
   .
   .
   .
   if (problem_detected)
   {
       XtAppLock (app_context);
       XtProcessLock();
       if (! dlog ) dlog = XmcreateWarningDialog (...);
                           XtManageChild(dlog);
                           XSync(display, 0);
                           XtProcessUnlock();
                           XtAppUnlock(app_context);
    }
    .
    .
    .
}

Callbacks for handling the main events of the application do not require changes for multithreading, since they are called with the application context already locked.

Worker Threads

Each of the DECwindows Motif libraries can create worker threads to support multithreading. These threads are identified by their name, which begins with the string DECW$.

Worker threads typically operate at an elevated priority to prevent task inversion, where a high-priority application thread is waiting for the worker thread to complete its operation. Note that worker threads are typically used for short duration tasks, such as responding to an internal AST or sending a status broadcast to all threads waiting for a particular activity.

Upcalls and Kernel Threads

In general, DECwindows Motif for OpenVMS Alpha Version 1.3 supports client applications either with or without upcalls or multiple kernel threads enabled. However, to avoid problems with priority inversion, HP recommends that upcalls be enabled for all applications that use XtAppAddInput. If upcalls cannot be enabled, then HP recommends assigning the same priority to all threads that use DECwindows Motif.

For example, an application calls XtAppAddInput to request a response to an OpenVMS event flag. The worker thread executes a SYS$WFLOR system call to wait for the event flag. Without upcalls enabled, this thread remains available even though there is no event flag set. And as a result, lower priority threads would not be scheduled.

Cancellation Points

Although some calls in the thread-safe libraries include cancellation points, the action of canceling threads that are executing DECwindows Motif functions is not supported. Canceled threads may hold locks, which can block other threads.

Multiple Application Contexts

Note that multiple application contexts should not be used with multiple threads and thread-aware images. Thread-aware images may contain process global data that requires a single lock to control the data. However, multiple calls to thread-aware images may be made from Xt event handling functions prior to acquiring the lock.

4.2 Transport Programming

The following sections contain features related to DECwindows Motif transport interfaces.

4.2.1 Support for the LAT Transport Interface Restored

V1.3--1

With OpenVMS Alpha Version 7.3--2, support for the DECwindows Motif interface to the LAT transport, which was withdrawn with HP DECwindows Motif for HP OpenVMS Alpha Version 1.3, has been restored. This support enables users of X terminal systems, such as the VXT2000, to start LAT X sessions to communicate with systems running DECwindows Motif Version 1.3--1 or higher. It also allows single- and multithreaded client applications running on these DECwindows Motif systems to use the LAT transport to connect to X terminal systems.

Note that the restored LAT interface included with the OpenVMS Alpha Version 7.3-2 operating system can be used as a valid network transport for communication with the DECwindows Motif Version 1.3 and OpenVMS Alpha Version 7.3-2 display servers. However, use with any other communication protocols in the X11R6.6 environment is not supported. This includes communication by or with the following:

• Inter-Client Exchange (ICE) and Session Manager protocols
• Low-Bandwidth X (LBX) proxy servers
• Proxy manager applications
• Font servers

Additionally, HP does not support the use of a token-based authentication protocol (such as MIT-MAGIC-COOKIE-1 or MIT-KERBEROS-5) with the restored LAT transport interface.