HP OpenVMS Systems Documentation

HP DECwindows Motif for OpenVMS
New Features

EVI enables a client to query the display server for additional information about core X visuals, such as colormap information and framebuffer levels. Note that this extension only provides support for client applications and not other X Window System extensions.

Code that uses EVI must include the following header files:

# include "DECW$INCLUDE:Xlib.h"
# include "DECW$INCLUDE:Xevi.h"

This extension is a fixed part of the display server and is always enabled. Call the following routine to check if EVI is available on the server system:

Bool XeviQueryExtension (
       Display *dpy
);

The following table lists each argument and its description.

LBX is a network-transparent protocol for running X Window System applications over transport channels whose bandwidth and latency are significantly lower than that available in local area networks. LBX combines a variety of caching and reencoding techniques that reduce the volume of data sent over the network.

By using a proxy server as an intermediary between the client applications and the X server, low-bandwidth/high-latency communication is maintained between the proxy and X server. The proxy server reencodes and compresses requests, events, replies and errors, as well as the resulting data stream. Additionally, the proxy can cache information from the server to provide low-latency replies to client applications.

A proxy can serve multiple client applications and does not prevent clients from connecting directly to the server. The proxy can combine calls from multiple client applications into a single data stream.

Use of LBX is transparent to clients. The only interface to LBX available to client code is a query to check the availability of LBX. Code that uses this query must include the following header files:

# include "DECW$INCLUDE:Xlib.h"
# include "DECW$INCLUDE:Xlbx.h"

This extension is dynamically loadable at server startup; see the HP DECwindows Motif for OpenVMS Management Guide. Call the following routines to check if LBX has been loaded and is available on the server system:

Bool XLbxQueryVersion(
          Display *display,
          int     *major_version_return,
          int     *minor_version_return
);

The following table lists each argument and its description.

SECURITY contains a new protocol that provides for enhanced X server security. This extension adds the concepts of trusted and untrusted client connections to the X Window System protocol. The trust status of a client is determined by the authorization method used during the startup of a connection. All clients using host- or user-based authorization are considered trusted. Clients using token-based authorization protocols may be either trusted or untrusted depending on the authorization data included in the connection request.

The requests in SECURITY permit a trusted client to create multiple authorization entries related to a single authorization protocol. Each entry is tagged with a trust status, which is then associated with any client using that authorization entry.

When a connection identifying an untrusted client is accepted, the client is restricted from performing certain operations that would steal or modify data that is held by the server for trusted clients. An untrusted client performing a disallowed operation will receive protocol errors.

When a client is untrusted, the server can also limit the extensions that are available to the client. Each X protocol extension is responsible for defining what operations are permitted to untrusted clients. By default, the entire extension is hidden to untrusted clients.

With DECwindows Motif, the following extensions (standard and non-standard) are defined as secure:

• BIG-REQUESTS
• LBX
• XC-MISC

All other extensions are considered insecure. See the HP DECwindows Motif for OpenVMS Management Guide for more information on how to select an appropriate authentication method and specify trusted or untrusted connections.

Code that uses SECURITY must include the following header files:

# include "DECW$INCLUDE:Xlib.h"
# include "DECW$INCLUDE:security.h"

This extension is dynamically loadable (along with the XC-APPGROUP extension) at server startup; see HP DECwindows Motif for OpenVMS Management Guide. Call the following routine to check if SECURITY is available on the server system:

Bool XSecurityQueryExtension (
       Display *dpy,
       int     *major_version_return,
       int     *minor_version_return
);

The following table lists each argument and its description.

XC-MISC allows client applications to retrieve previously-used resource ID ranges from the X server. Xlib handles this function automatically. This extension is useful for long-running applications that use many resource IDs over their runtime life.

Since the XC-MISC functions are part of Xlib, they are a standard part of the client. As such, they are are always available when connected to an X Window system that offers this extension.

4.7.1.8 X Double Buffer Extension (DBE)

DBE provides a way to display flicker-free animation on an X Window system and is intended as a replacement to the Multibuffering extension. Successive frames of an animation sequence are rendered into the back buffer while the previously rendered frame is displayed in the front buffer. When a new frame is ready, the back and front buffers swap roles, making the new frame visible. Only completely rendered frames are shown; these frames remain visible during the entire time it takes to display the new frame.

Code that uses DBE must include the following header files:

# include "DECW$INCLUDE:Xlib.h"
# include "DECW$INCLUDE:Xdbe.h"

This extension is dynamically loadable at server startup; see the HP DECwindows Motif for OpenVMS Management Guide. Call the following routine to check if the extension has been loaded and is available on the server system:

Bool XdbeQueryExtension (
       Display *dpy,
       int     *major_version_return,
       int     *minor_version_return
);

The following table lists each argument and its description.

XINERAMA (formerly known as PanoramiX) enables a system configured with multiple video monitors (multiheaded system) to function as a single large screen. This extension allows application windows and cursor movement to span multiple screens and move from one screen to another.

The overall size of the composite screen equals the combined size of all screens. Monitor configurations can be easily modified by enabling this extension in conjunction with the associated screen symbols (such as DECW$SERVER_SCREENS). See the HP DECwindows Motif for OpenVMS Management Guide for the complete list of logicals associated with this extension and for instructions on how to setup and configure a multiheaded system that uses XINERAMA.

XKB enhances the control and customization of the keyboard under the X Window System by providing the following:

• Support for the ISO9996 standard for keyboard layouts
• Compatibility with the core X keyboard handling
• Standard methods for handling keyboard LEDs and locking modifiers
• Support for keyboard geometry

Note that all AccessX extension features for people with physical impairments have been incorporated into XKB. These accessibility features include StickyKeys, SlowKeys, BounceKeys, MouseKeys, and ToggleKeys, as well as complete control over the autorepeat delay rate.

Code that uses XKB must minimally include the following header files:

# include "DECW$INCLUDE:Xlib.h"
# include "DECW$INCLUDE:XKBlib.h"

To modify keyboard geometry descriptions, the names and identifiers of the predefined bells, or X Keyboard map definitions, additionally include the following header files:

# include "DECW$INCLUDE:XKBgeom.h"
# include "DECW$INCLUDE:XKBbells.h"
# include "DECW$INCLUDE:XKM.h"
# include "DECW$INCLUDE:XKMformat.h"
# include "DECW$INCLUDE:XKBfile.h"
# include "DECW$INCLUDE:XKBrules.h"
# include "DECW$INCLUDE:XKBconfig.h"

This extension is dynamically loadable at server startup; see the HP DECwindows Motif for OpenVMS Management Guide. Call the following routine to check if the extension has been loaded and is available on the server system:

Bool XkbQueryExtension(
       Display  *dpy,
       int      *opcodeReturn,
       int      *eventBaseReturn,
       int      *errorBaseReturn,
       int      *majorReturn,
       int      *minorReturn
);

The following table lists each argument and its description.

SYNC provides primitive calls that synchronize requests from multiple clients on different hosts running different operating systems. This extension enables applications to make the best use of buffering resources within the client, server, and network and eliminates network errors that can occur when two systems are running a distributed application.

Multimedia applications can use this extension to synchronize streams of audio, video, and graphics data. For example, simple animation applications can be implemented without having to use round-trip requests.

Code that uses SYNC must include the following header files:

# include "DECW$INCLUDE:Xlib.h"
# include "DECW$INCLUDE:sync.h"

This extension is a fixed part of the display server and is always enabled. Call the following routines to check if the extension has been loaded and is available on the server system:

Bool XSyncQueryExtension(
       Display *dpy,
       int     *event_base_return,
       int     *error_base_return
);

Status XSyncInitialize(
       Display *dpy,
       int     *major_version_return,
       int     *minor_version_return
);

The following table lists each argument and its description.

V1.3

The following existing X Window System extensions have been updated:

• DEC XTrap (DEC-XTRAP) and X Test (XTEST) -- Now disabled with the DECW$SERVER_DISABLE_TEST parameter
• MIT Screen Saver (MIT-SCREEN-SAVER) -- Updated to work with XINERAMA
• Multibuffering (MBE) -- New XmbufClearBufferArea function
• MIT Miscellaneous (MIT-SUNDRY-NONSTANDARD)
• MIT Shared Memory (MIT-SHM)
• Non-Rectangular Window Shape (SHAPE)
• X Image Extension (XIE) -- Supports V3.0 and not the adopted standard of V5.0

V1.3

The Inter-Client Exchange (ICE) Protocol provides support for direct X Window System client-to-client communication without using the X server. This means that DECwindows Motif client applications can use ICE rather than connect to the X server. The standard protocol provides the basic mechanisms for establishing and closing network transport connections, performing authentication, negotiating versions, and reporting errors. The protocols running within an ICE connection are known a subprotocols, of which Session Manager (described in Section 4.7.4) is a member.

A new client-side library, DECW$ICELIB, is provided. Code that uses ICE must include the following header file:

# include "DECW$INCLUDE:Icelib.h"

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

4.7.3.1 Multithreading Considerations

The ICE library supports multithreading after IceInitThreads has been called. IceInitThreads must be the first call on the ICE library if multithreading is required. Programs that call IceInitThreads must have been linked against PTHREAD$RTL.

The following sections further describe issues with using ICE functions in a multithreaded environment.

Lock Nesting

Locks held by IceLockConn and IceAppLockConn are recursive. The corresponding unlock routine must be called the same number of times as the lock routine.

Deleting IceConn Objects

IceConn objects can be deleted by:

• IceProcessMessages returning IceProcessMessagesConnectionClosed
• IceCloseConnection returning IceClosedNow

In these cases, the IceConn object is freed without validation even though locks may still be held. To avoid race conditions, ensure that the deleted IceConn object is not being used by another thread.

Non-Atomic Functions and Macros

The following subset of the ICE functions that prepare and read messages are not atomic and do not acquire locks:

• IceGetHeader
• IceGetHeaderExtra
• IceSimpleMessage
• IceErrorHeader
• IceWriteData
• IceWriteData16
• IceWriteData32
• IceSendData
• IceWritePad
• IceReadSimpleMessage
• IceReadCompleteMessage
• IceDisposeCompleteMessage
• IceReadMessageHeader
• IceReadData
• IceReadData16
• IceReadData32
• IceReadPad

Any multithreaded application that uses one or more of these macros or functions must explicitly acquire a lock on the connection before creating a message, and release the lock after the message is prepared. For read operations, this action is not required since the ICE process callbacks automatically lock the connection.

For example, the following is sample code for creating a message:

IceAppLockConn (iceConn);
IceGetHeaderExtra (iceConn, _SmcOpcode, SM_RegisterClient,
          SIZEOF (smRegisterClientMsg), WORD64COUNT (extra),
          smRegisterClientMsg, pMsg, pData);

*((CARD32 *) pData) = len;
pData += 4;

memcpy (pData, previousId, len);
pData += (len + 3) & (~3);
IceAppUnLockConn (iceConn);

Since an ICE connection can be shared between protocols, every protocol must use these locks, even if the protocol can only be used by a single thread.

Opening Connections

DECwindows Motif restricts multithreaded applications from concurrently calling IceOpenConnection and IceCloseConnection. IceOpenConnection can accept concurrent calls to itself as long as IceCloseConnection is not called at the same time.

ICE can maintain two open connections for the same protocol by using a major opcode check to the IceOpenConnection call. Since a protocol is registered only after it calls IceProtocolSetup, a conflict can occur if two threads simultaneously establish ICE connections for the same protocol and request that the connection is not shared.

To prevent this conflict from occurring, code for opening an ICE connection with a major opcode check should follow a format similar to the following:

IceConn conn;
IceProtocolSetupStatus status;
while (1) {
     conn = IceOpenConnection (....)
     if (conn == 0) break;
     status = IceProtocolSetup (...)
     if (status != IceProtocolAlreadyActive) break;
     IceCloseConnection (conn);
     /* Try again as another thread set up the protocol on this connection */
}

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

Connection and Protocol Authentication

The implementation of ICE included with DECwindows Motif does not include any authentication mechanisms for ICE connections. All listen objects must use IceSetHostBasedAuthProc to register host-based authentication.

For protocol authentication, all authentication schemes provided when the protocol is registered are permitted. This differs from the standard ICE implementation, where only those those schemes defined in the ICE Authority (IceAuth) file are allowed.

Object Name Changes

The sample implementation of ICE provided by the X.Org Foundation contained objects whose name differed from that described in the ICE specification. The following table lists those objects and specifies which name was used in the DECwindows Motif implementation of ICE.

IceGetHeaderExtra Structure

The header structure used with IceGetHeaderExtra must have a sizeof value that is a multiple of 8 bytes.