HP OpenVMS Systems Documentation

HP DECwindows Motif for OpenVMS
New Features

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

3.1 Installation and Upgrade Information

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

3.1.1 DECW$STARTUP Log File

V1.5

When you start DECwindows Motif using the command @SYS$MANAGER:DECW$STARTUP RESTART, a startup log file is now created. This log file records activity from the detached process that invokes DECwindows Motif, which can be useful in diagnosing startup problems.

The name of the log file is SYS$MANAGER:DECW$STARTUP_n.LOG, where n represents the server number. The default server number value is 0; hence, the default filename is DECW$STARTUP_0.LOG. If you have set the server number to a value other than 0, that value is then used in the name of the corresponding log file.

To minimize disk space usage, the log files are purged periodically. A maximum of three versions of a startup log file are kept on disk.

For more information on the DECwindows Motif startup procedure, see the HP DECwindows Motif for OpenVMS Management Guide.

3.2 Security and Authorization

The following sections describe features that pertain to maintaining system and network security of DECwindows Motif systems.

3.2.1 Support for ACME Subsystem (Alpha Only)

V1.5

The Authentication and Credentials Management Extensions (ACME) subsystem features of OpenVMS Alpha are now supported by DECwindows. The following dialog boxes and screens support access checks using ACME:

• Login dialog box (New Desktop)
• Lock Screen dialog box (New Desktop)
• Start Session dialog box (Traditional DECwindows Desktop)
• Pause Session screen (Traditional DECwindows Desktop)

All ACME features are supported, including intrusion detection and remote authentication. See the HP OpenVMS Guide to System Security for a detailed description of the ACME subsystem and its components.

3.3 X Display Server Management

The following sections describe features that pertain to managing the DECwindows X11 Display Server.

3.3.1 New Parameter for Enabling IPv6 Support in the Font Server

V1.5

A new server parameter, DECW$IPV6_FONT_SUPPORT, has been added that controls how the TCP transport is interpreted when specifying font servers either through use of the DECW$FONT_SERVER parameter or through the use of an explicit font server path. In addition, the DECW$FONT_SERVER parameter now accepts an expanded set of transport values.

To set these parameters for the server process, do the following:

1. Edit the SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.COM file.
2. Define both the DECW$FONT_SERVER and DECW$IPV6_FONT_SUPPORT parameters as required.
3. Save the file and restart the server.

DECW$FONT_SERVER

The transport options available through this parameter have been expanded to include all valid transports, as described in the HP DECwindows Motif for OpenVMS Management Guide.

DECW$IPV6_FONT_SUPPORT

This parameter controls the interpretation of the TCP or TCPIP transport name in the DECW$FONT_SERVER definition and whenever a client explicitly specifies a font server path. Set the parameter to one of the following values:

• TCP_IS_INET6
  The TCP and TCPIP transport names are interpreted as synonyms for the INET6 transport. Using this value enables IPv6 as the default transport between the display server and its font servers when the TCP or TCPIP transport name is specified. Note that this setting requests the IPv6 transport be used as a default. If the IPv6 transport is not available for the specified node, the IPv4 transport is used.
• DISABLED
  The TCP and TCPIP transport names are interpreted as synonyms for the INET transport. This is the default value if the parameter is undefined. Using this value sets IPv4 as the transport between the display server and its font server when a TCP or TCPIP transport name is specified. A client can still request the IPv6 transport by explicitly specifying the INET6 transport in its font server path.

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 and X11R6.7 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 described in the HP DECwindows Motif for OpenVMS Documentation Overview.

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 Version 1.3 or higher environment.

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

• X Library (Xlib)
• X Toolkit Intrinsics (Xt)
• X Window System Extensions library
• Inter-Client Exchange (ICE) library
• X Session Management Protocol (XSMP) library

V1.3

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 Release Notes.

Existing applications require recompilation against the X11R6.6-compatible X Window System 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 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 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:

• Xlib and X Window System Extension libraries
  For most operations, Xlib and X Window System 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.
• Xt 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.
• ICE and XSMP 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.8.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 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 Application Programming

The following sections describe features related to application programming.

4.2.1 CDA Programming

This section describes features and changes related to CDA programming.

4.2.1.1 Changes to the CDA Programming Interface

V1.2

This section describes the changes to the programming interface for this version of CDA Run-Time Services.

This version provides a new set of header files that define CDA constants, types, and routines using portable naming conventions. By using these new naming conventions, you can use a wider variety of C compilers to minimize the amount of system-specific code in your CDA applications.

The names of the new set of header files are the same as the names of the previous set of header files, except that the dollar sign ($) has been removed. For example, the cda$msg.h include file is now called cdamsg.h. Other examples include the following: The DDIF$K_DSC_MAJOR_VERSION symbol is now declared as DDIF_K_DSC_MAJOR_VERSION, and the CDA$_NORMAL status value is now defined as CDA_NORMAL.

The previous set of header files is also included in this version, but these files will no longer be updated. Changes introduced since the release of DECwindows Motif Version 1.1 (for example, the new definitions for audio support), are available only in the new set of header files. To use the new CDA features, change the file names in your source code.

The new set of header files supplements the previous set of header files. If you want to write ANSI-compliant applications using CDA definitions and CDA Toolkit calls, use the new set of header files. However, you can continue to use the header files that define symbols containing the dollar sign ($) provided you choose a non-ANSI compilation mode.

By using the previous set of header files, you can successfully build existing source code that uses the previous naming conventions.

See Table 4-3 for a list of new header file names.