[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP DECwindows Motif for OpenVMS
New Features


Previous Contents Index

4.7.3.3 IPv6 Considerations

V1.5

For ICE clients, the ICE library has been upgraded to support all the transport names described in the HP DECwindows Motif for OpenVMS Management Guide.

For ICE servers, specifying a value of TCPIP or TCP now opens listen sockets on all configured TCP/IP interfaces. If some of the interfaces are IPv6 interfaces, the library supports accepting connections on IPv6 interfaces.

After using the IceListenForConnections call, you can use the IceComposeNetworkIdList call to obtain the address for the TCP/IP listen object in the format "tcp/hostname", where hostname is the value of the system logical TCPIP$INET_HOST. Use of the generic TCP transport allows the listen object to be used by both IPv4-based and IPv6-based peers.

The host-based authentication callback is provided the peer's host name as returned by the TCP/IP Services getnameinfo function. If the peer's host name is unavailable, the callback is provided with the peer's host address in either IPv4 or IPv6 format (depending on the protocol used to establish the connection). If the address is an IPv4-mapped IPv6 address, the address is converted to an IPv4 address before being provided to the callback. If the getnameinfo returns a name that includes a scope identifier, the scope identifier is included in the value passed to the callback.

4.7.4 X Session Management Protocol (XSMP) Support

V1.3

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 DECwindows Motif, 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 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.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.

4.7.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 and OpenVMS I64 environments.

SmsGenerateClientId and IPv6

On a host where the primary TCP/IP interface limited to IPv6, the ID generated by SmsGenerateClientId will follow the IPv6 format (as defined in the X11R6.7 specification published by the X.Org Foundation).

4.7.5 MIT Shared Memory Extension (MIT-SHM) Support

V1.2

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 4.6.9 for details on linking this library.

4.7.5.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.

4.7.5.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.

Note

The shared memory segment routines are provided with DECwindows Motif. Using global sections, these routines emulate the shared memory routines on UNIX systems.

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;

Note

If you modify the shared memory segment before the arrival of the completion event, the results may be inconsistent.

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


Status XShmGetImage (display, d, image, x, y, plane_mask)
       Display *display;
       Drawable d;
       XImage *image;
       int x, y;
       unsigned long plane_mask;

The following table lists each argument and its description.

Argument Description
display The display of interest.
d The source drawable.
image The destination XImage.
x X-offset within the source drawable.
y Y-offset within the source drawable.
plane_mask The planes that are to be read.

To destroy a shared memory XImage, first instruct the server to detach from it, then destroy the segment itself. The following example illustrates how to destroy a shared memory XImage:


XShmDetach (display, shminfo);
XDestroyImage (image);
shmdt (shminfo.shmaddr);
shmctl (shminfo.shmid, IPC_RMID, 0);

4.7.5.3 Using Shared Memory Pixmaps

Unlike X images, for which any image format is usable, the shared memory extension supports only a single format for the data stored in a shared memory pixmap (XYPixmap or ZPixmap). This format is independent of the depth of the image and independent of the screen. (For 1-bit pixmaps the format is irrelevant.)

The XShmPixmapFormat routine returns the shared memory pixmap format for the server. The XShmPixmapFormat routine has the following format:


int XShmPixmapFormat (display)
       Display *display;

Your application can only use shared memory pixmaps in the format returned by the XShmPixmapFormat routine (including bits-per-pixel). To create a shared memory pixmap do the following:

  • Create a shared memory segment and shminfo structure exactly the same way as is listed for shared memory XImages steps 1 through 4 (see Section 4.7.5.2). While it is not necessary to create an XImage first (step 1), doing so incurs little overhead and provides an appropriate bytes_per_line value to use.
  • Call the XShmCreatePixmap routine, which has the following format:


    Pixmap XShmCreatePixmap (display, d, data, shminfo, width,
                             height, depth);
           Display *display;
           Drawable d;
           char *data;
           XShmSegmentInfo *shminfo;
           unsigned int width, height, depth;
    

    The arguments are the same as for XCreatePixmap (see the X Window System) except for two additional parameters, data and shminfo. The data parameter is the pointer to the shared memory segment and is the same as the shminfo.shmaddr field. The shminfo parameter is the same as the previous structure.
    If successful, a pixmap is returned, which you can manipulate. You can manipulate its contents directly through the shared memory segment. Shared memory pixmaps are destroyed with the XFreePixmap routine, although you should detach and destroy the shared memory segment (see step 4 in Section 4.7.5.2).

4.7.6 X Image Extension (XIE) Support

V1.1

Starting with DECwindows Motif for OpenVMS Version 1.1, DECwindows Motif supports the X Image Extension (XIE). XIE allows image display processing using resources on the server side of the X client-server model. XIE eliminates the need to transmit image data repeatedly from the client to the server and also allows data to be transmitted in compressed form, reducing the network load.

DECwindows Motif includes the XIE client side shareable library (XIE$SHRLIB.EXE) and C language header files. These allow applications to communicate with any X11 server that supports the XIE extension.

An XIE program uses a structure called the XIEImage to describe image data on the client side. This general mechanism describes data that the destination server is incapable of processing. Consult the documentation for the server system for information on what data types and sizes are supported. Unless the documentation specifies different limits, the server is capable of processing unsigned byte (UdpK_DTypeBU), unaligned bit field (UdpK_DTypeVU), and aligned bit field (UdpK_DTypeV) data, with a maximum depth of 8 bits per pixel per component. The XIE client library supports these data types, as well as unsigned word (UdpK_DTypeWU), and a depth of up to 16 bits per pixel per component.

Although the XIE protocol and programming interface have been standardized for X11R6, DECwindows Motif has not yet migrated to the latest implementation of this protocol.

4.8 Transport Programming

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

4.8.1 Support for the LAT Transport Interface Available

V1.3--1

Support for the DECwindows Motif interface to the LAT transport, which was withdrawn with DECwindows Motif Version 1.3, has been restored and is available on the OpenVMS Alpha and OpenVMS I64 platforms. This support enables users to start LAT X sessions and communicate over low-capacity networks with systems running DECwindows Motif Version 1.3--1 or higher. It also allows 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 operating system can be used as a valid network transport for communication with the DECwindows Motif Version 1.3--1 (or greater) and OpenVMS Version 7.3--2 (or greater) 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.

4.8.2 Support for the Logical Connection Number (LCN) Interface

V1.3

DECwindows Motif now includes an interface for determining when an I/O channel is ready and available for use. The logical connection number (LCN) interface is now used to signal when DECwindows Motif I/O channels are available, including those for Inter-Client Exchange (ICE), local and remote X server, and for Input Method Server connections.

Previously, DECwindows Motif used an OpenVMS event flag number (EFN) to signal when input was received from the X server. However, EFNs cannot be used safely in a multithreaded environment. The LCN interface allows multiple threads to handle the same, or different, connections without any thrashing or unnecessary delays.

The following sections further describe the functions of the LCN interface and provide detailed information about the supported routines.

4.8.2.1 LCN Functions

The principal function of the LCN interface is to test the readiness of an I/O channel. The design of the interface is based on the UNIX select function, which tests the state of UNIX file descriptors and returns when one of them is ready or a timeout occurs.

On OpenVMS, the LCN routines perform the following operations:

  • Initialize support for multithreading
  • Allocate a connection number
  • Query the status of a connection number
  • Signal when input is available

4.8.2.1.1 Initializing Thread Support

LCN routines can execute in a single-threaded environment using EFNs to signal input or in a multithreaded environment using POSIX Threads routines. Multithreading is enabled with the DECW$LCN_THREAD_INIT routine.

With multithreading enabled, the select routines (DECW$LCN_SELECT_ONE and DECW$LCN_SELECT) can be called concurrently from multiple kernel threads in user mode and one kernel thread in exec mode. Calls from user mode ASTs are not allowed.

With single threading, the select routines can be called from user mode and exec mode ASTs. Note, however, that the only concurrent calls allowed are one call from user mode followed by one call from an AST in user mode.


Previous Next Contents Index