V1.0

Horizontal live scrolling is not supported in the SVN widget.

4.6.3 Corrections

The following notes describe the resolution of any problems specific to the DECwindows Extensions to Motif that previously resulted in an error or required a workaround.

4.6.3.1 Calling DXmSvnDeleteEntries after DXmSvnAddEntries

V1.2--6

Calling the DXmSvnDeleteEntries routine after a call to the DXmSvnAddEntries routine no longer causes the related application to crash.

4.7 Display Server Extensions

This section contains information about the display server extensions.

4.7.1 Changes and Enhancements

The following notes describe changes and enhancements made to the display server extensions.

4.7.1.1 Shared Memory Extension Support (Alpha Only)

V1.2

On OpenVMS Alpha systems, 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.7.1.4 for details on linking this library.

4.7.1.1.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, if shared memory pixmaps.

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

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;

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.1.1.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.1.1.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.1.1.2).

V1.2

To ensure that programs that contain extension include files compile properly, add the logical name DECW$INCLUDE to the C include directory search list.

To add the logical name for VAX C, enter the following command:

$ DEFINE C$INCLUDE DECW$INCLUDE

To add the logical name for DEC C, enter the following command:

$ DEFINE DECC$USER_INCLUDE DECW$INCLUDE

4.7.1.3 X Image Extension Support

V1.1

Starting with DECwindows Motif Version 1.1 for OpenVMS, 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 sharable 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.

The XIE protocol and programming interface are being standardized within the X Consortium for R6, and programs that use XIE will probably have to be modified. You can use the Image Display Services (IDS) component of DECimage Application Services for VMS as an alternative to the XIE library interface. IDS provides a higher level model of image display and automatically uses XIE when it is available and appropriate.

4.7.1.4 Client Side Extension Library Available

V1.1

Starting with DECwindows Motif Version 1.1 for OpenVMS, Xlib added a client side library that allows OpenVMS clients to issue Shape, XInput, Multibuffer, and shared memory extension requests to servers that provide these features. (For example, the DECwindows X11 display server for OpenVMS VAX does not support the Shape extension while the DECwindows X11 display server for OpenVMS Alpha system does support Shape.) The name of this library is DECW$XEXTLIBSHR.EXE.

You must modify the linking file options for client applications that issue Shape, XInput, Multibuffer, or shared memory extension requests to link to the Xlib extensions shareable image in SYS$LIBRARY:DECW$XEXTLIBSHR.EXE. Add the following line to your linker options file:

SYS$LIBRARY:DECW$XEXTLIBSHR/SHARE

For more information on Shape, XInput, and Multibuffer extensions, see the following text files in SYS$HELP:

• DECW$SHAPE.TXT
• DECW$XINPUT.TXT
• DECW$MULTIBUFFER.TXT

This section contains release notes pertaining to internationalization and localization.

4.8.1 Changes and Enhancements

The following notes describe changes and enhancements made to internationalization and localization support. These changes enable users to view and convert files that contain Asian-language characters.

4.8.1.1 Using the CDA Viewer to View Asian-Language Text

V1.2--3

You can use the CDA Viewer in two ways to view text files that contain Asian characters:

• Specify an options file to the CDA Viewer application.
• Define logical names at the DCL command level or in a LOGIN.COM file.

Refer to the DECwindows Motif for OpenVMS Applications Guide for information about using the CDA Viewer.

4.8.1.1.1 Specifying an Options File

Specify an options file by including a one-line entry in the file in the following format:

TEXT TEXT_ENCODING text_encoding_value

• TEXT is the format.
• TEXT_ENCODING is the option you specify to CDA.
• text_encoding_value is the value of the codeset. (See Table 4-5 for a list of values.)

Table 4-5 shows the languages, codesets, and text-encoding values.

Table 4-5 Asian Language Codes for Options Files

Language	Codeset	Text Encoding Value
Japanese	DEC Kanji	DEC_KANJI
Japanese	Super DEC Kanji	SDECKANJI
Traditional Chinese	DEC Hanyu	DEC_HANYU
Simplified Chinese	DEC Hanzi	DEC_HANZI
Korean	DEC Korean	DEC_HANGUL

The following table shows examples of one-line entries.

Options File	One-Line Entry
HANYU.CDA$OPTIONS	TEXT TEXT_ENCODING DEC_HANYU
HANZI.CDA$OPTIONS	TEXT TEXT_ENCODING DEC_HANZI
HANGUL.CDA$OPTIONS	TEXT TEXT_ENCODING DEC_HANGUL

To view the EXAMPLES_CUSTOMERS.TXT file that contains Japanese text in DEC Kanji, use your editor to create an options file called KANJI.CDA$OPTIONS. Add the following one-line entry to the file:

TEXT TEXT_ENCODING DEC_KANJI

When you access the file through the Options File dialog box with the CDA Viewer, the EXAMPLES_CUSTOMERS.TXT file is viewable in the DEC Kanji codeset (Japanese language).

4.8.1.1.2 Defining Logical Names

The second option to enable viewing files in Asian languages is to specify the text file and encoding value by defining two logical names:

• DDIF$READ_TEXT_GL
• DDIF$READ_TEXT_GR

Table 4-6 shows the logical names and associated encoding values.

Table 4-6 Logical Names for Specifying Text Encoding

DDIF$READ_TEXT_GL	DDIF$READ_TEXT_GR	Encoding Value
LATIN1	MCS	MCS
LATIN1	LATIN1	ISO Latin--1
LATIN1	KATAKANA	ASCII--Kana
LATIN1	KANJI	DEC Kanji
ROMAN	MCS	Roman--MCS
ROMAN	LATIN1	Roman
ROMAN	KANJI	Roman--Kanji
ROMAN	KATAKANA	Roman--Kana
LATIN1	HANZI	DEC Hanzi
LATIN1	HANGUL	DEC Hangul
LATIN1	HANYU	DEC Hanyu

You can define the logical names on the DCL command line or in your LOGIN.COM file. For example:

$ DEFINE DDIF$READ_TEXT_GL LATIN1 $ DEFINE DDIF$READ_TEXT_GR KANJI

Note that this example defines the text encoding for DEC Kanji (see Table 4-6).