HP OpenVMS Systems Documentation

This document describes the theory of operation and interconnection of each component of the VMS DECwindows transport layer. This document also describes the recommended coding procedures you should follow when you augment the DECwindows transport with a third-party transport.

Revision/Update Information: This is a new manual.

Operating System: VMS Version 5.4

Software Version: VMS DECwindows Motif Version 1.0

Digital Equipment Corporation
Maynard, Massachusetts

The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

No resposibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

© Digital Equipment Corporation 1991.

All Rights Reserved.

The postpaid Reader's Comments forms at the end of this document request your critical evaluation to assist in preparing future documentation.

The following are trademarks of Digital Equipment Corporation: Bookreader, CDA, DEC, DECnet, DECwindows, DECwrite, Digital, LinkWorks, LiveLink, LN03, MicroVAX, PrintServer, ReGIS, ULTRIX, VAX, VAXcluster, VAXserver, VAXstation, VMS, VT, XUI, and the DIGITAL logo.)

Motif is a trademark of the Open Software Foundation, Inc.

ZK5644

This document was prepared using DECdocument, Version V3.3-1e.

The VMS DECwindows Transport Manual provides information needed to write a DECwindows transport interface that runs under VMS Version 5.4. Digital makes no guarantee that transport interfaces written using these guidelines will execute without modification on future versions of the operating system.

Intended Audience

This document is intended for programmers who need information about the components and interfaces of the VMS DECwindows transport layer. It describes the theory of operation and interconnection of each component of the VMS DECwindows transport layer. It also describes the recommended coding procedures that you should follow when augmenting the DECwindows transport layer with a third-party transport.

You should read this document before modifying or replacing the VMS DECwindows transport.

This document assumes that you are familiar with the overall design of the VMS DECwindows implementation.

Document Structure

The VMS DECwindows Transport Manual is organized into the following chapters:

• Chapter 1 provides an overview of the VMS DECwindows transport layer.
• Chapter 2 describes how X11 protocol requests, events, errors, and replies are generated and transmitted in the VMS DECwindows environment. Although the transport layer itself does not interpret the data that it transfers, you should read this chapter to become familiar with how the transport layer supports the X11 protocol.
• Chapter 3 describes the theory of operation and interconnection of each component of the VMS DECwindows transport layer. This chapter includes a description of the functions performed by the common and specific components and how they interact.
• Chapter 4 describes a walk-through of typical transport layer activities.
• Chapter 5 describes the transport-common routines that a transport-specific component needs to call. You should read this chapter to become familiar with the operation and use of these routines.
• Chapter 6 describes the transport-specific routines that you must implement if you write your own transport-specific component.
• Chapter 7 describes the transport-layer utility routines that you can use. These routines are provided for your convenience; there is no requirement that you use them, but you must implement similar functions.
• Chapter 8 describes a cookbook approach to writing your own transport-specific routines. The chapter includes a sample BLISS-32 code example for each of the transport-specific routines that you must write. Your own implementation of these routines may differ depending on your chosen network service.

Associated Documents

For more information about DECwindows, see the VMS DECwindows Motif documentation set.

Conventions

The following conventions are used in this manual:

The VMS DECwindows transport layer is separated into transport-common and transport-specific components. The routines that comprise the transport-common layer are network independent and are used to buffer and queue data to be sent between a client and server. The transport-common routines then call routines that are specific to a particular network service, such as DECnet and TCP/IP, to actually move the data across the network.

The transport-specific routines perform the following functions:

• Initialize (attach) a specific network service
• Connect a client to a server
• Write data to the network service
• Read data from the network service
• Close a connection and release connection resources

To implement your own transport layer, you must write the transport-specific routines to support your particular network service and link them as a VMS shareable image that can be accessed by the transport-common component.

Chapter 8 includes examples of transport-specific routines that implement a TCP/IP transport layer for DECwindows. You can use these code examples as a starting point when writing your own transport-specific routines.

Depending upon the network service on which you are building, you will probably find that the routines that initialize a transport and establish a connection require the most modification. You may also find that routines that primarily insert and remove buffers from the queues can be used with minimal changes.

The remainder of this chapter provides an overview of the VMS DECwindows transport layer. Subsequent chapters describe the transport layer components and their interconnection in greater detail.

1.1 The Transport Layer Function

The function of the transport layer is to move X Window System Version 11 (X11) protocol requests between an application, called the client, and the X11 server in an efficient manner. The transport layer transmits data over network transports. VMS DECwindows currently supports three network transports: DECnet, TCP/IP, and a high-performance local transport.

In the X11 environment, the mechanism for sending information from a client to the server is by way of a "connection" to the server. Creating a client/server connection is known as opening a display; when you open a display, you open a connection.

The transport layer is a general data-transfer mechanism; it does not interpret or understand the format of the data that it transfers. The transport layer operates symmetrically on both ends of the client/server connection: it buffers and sends output requests from Xlib to the server and buffers and sends input events, errors, and replies to Xlib. The buffers are maintained in a series of communication queues.

The transport layer maintains status (communication context) on a per-connection basis.

1.2 Transport Common/Specific Architecture

The VMS DECwindows transport layer is installed as part of the DECwindows common component; that is, the transport layer is always installed when DECwindows is installed. The DECwindows DECW$STARTUP.COM procedure installs all of the transport images---DECW$TRANSPORT_COMMON.EXE, DECW$TRANSPORT_LOCAL.EXE, DECW$TRANSPORT_DECNET.EXE, and DECW$TRANSPORT_TCPIP.EXE---each time DECwindows is started.

Xlib and the server both initialize and attach a network-specific transport for their respective side of the connection.

The transport layer is separated into transport-common and transport-specific functions. The transport-common functions, which are contained in DECW$TRANSPORT_COMMON.EXE, provide the generic services needed by Xlib or the server. The transport-common functions buffer and queue the data to be sent between the client and server and then call functions in the various images (DECW$TRANSPORT_LOCAL.EXE, DECW$TRANSPORT_DECNET.EXE, DECW$TRANSPORT_TCPIP.EXE) that are specific to a particular transport service, such as local, DECnet, and TCP/IP, respectively, to actually move the data.

This architecture allows the transport-common component to present a common buffer/queue interface to other DECwindows components while the transport-specific component "hides" the details of how data is actually transmitted.

The transport-common/transport-specific architecture is particularly important because the transport layer must be flexible enough to efficiently support two types of client/server connections:

• If the client and server are executing on two different VMS systems, a transport image physically executes on both the client system and the server system. The two transports then establish a network connection between themselves to pass the data. The transport layer buffers data to reduce the number of required network round-trips and their associated overhead.
  This is called a remote connection.
• If the client and server are executing on the same VMS system, there is no need to establish a network connection, but the client must still open a logical connection to the server to pass data. This is called a local connection. Xlib and the server both initialize the transport-common code for their respective side of the client/server connection just as they would in the case of a remote connection. However, Xlib and the server then attach a local transport to transmit data.

The VMS DECwindows transport layer establishes remote or local connections to a server based on the display name argument passed by a client in the Xlib OPEN DISPLAY routine or through information specified in a SET DISPLAY command. (By passing a null value in the call to the OPEN DISPLAY routine, a client need not hard-code the display name. See the VMS DECwindows Xlib Programming Volume for more information.)

In a remote transport connection, a node name other than 0 indicates that a remote workstation node in the network is to be used as the display; the client application and the server do not execute on the same physical machine. The transport layer performs its buffering functions and calls a transport such as DECnet to send the data across the network, as shown in Figure 1-1.

Figure 1-1 Remote Transport Connection

In a local transport connection, a node name of 0 indicates that the client and server are executing on the same hardware, as shown in Figure 1-2. There is no need for the transport layer to send the data across the network, but Xlib and the server must still communicate. The local transport layer implements a shared-memory transport. The shared-memory transport performs functions that are similar to those performed by the DECnet or TCP/IP transport-specific components, but does not incur the network overhead.

Figure 1-2 Local Transport Connection

DECwindows contains support for the Digital-supplied TCP/IP transport. This support depends on the VMS/ULTRIX Connection software (UCX), which is a Digital layered product. Before you can use the DECwindows TCP/IP transport interface, including the example transport described in Chapter 8, you must install UCX. For more information about TCP/IP concepts, see the VMS/ULTRIX Connection System Manager's Guide.

1.3.1 Interoperability and the Transport Layer

The X11 protocol allows a DECwindows client to open a connection to some other vendor's implementation of the X11 server and allows other vendors' X11 clients to open a connection to the DECwindows server.

This interoperability is possible because of the requirement that Xlib and server implementations understand and support the X11 "connection handshake" sequence as well as the format of X11 protocol requests, replies, and events. That is, all Xlib implementations use the same format for sending connection-request information to a server and all servers use the same format for sending connection-request information back to a client.

When a DECwindows client attempts to open a connection to a display, that client has no idea whether that display is running an implementation of the DECwindows server or some other vendor's X11 server; Xlib sends exactly the same information in either case.

When a client opens a connection, it specifies the transport to use. The server gets the open-connection request only if that transport type is supported by the server. If it is, a connection between the two can be opened and X11 protocol connection-setup information can be exchanged.

Once this connection is open, the data is sent in the X11 protocol format. For example, the contents of a DECwindows transport buffer conforms exactly to the X11 protocol. In this way, other vendors' servers get just what they expect from DECwindows clients, and the DECwindows server receives what it expects from other vendors' clients.

The client and server must use the same transport to establish a connection; a DECnet transport cannot open a connection to a TCP/IP transport, and vice versa.

The X Window System Version 11 (X11) standard defines a common protocol for all communications between client applications and implementations of the X11 server. This standard protocol makes it possible to mix client/server pairs from different operating-system and vendor environments.

The protocol defines the format of the data, such as the request, reply, error, and event formats, that is passed between the client and server; it does not dictate the mechanism for transporting this data. The protocol nests inside transport mechanisms that move the protocol requests between clients and servers.

This chapter describes how X11 protocol requests, events, errors, and replies are generated and transmitted in the VMS DECwindows environment. You should read this chapter to become familiar with how the transport layer supports the X11 protocol. Later chapters describe the transport layer's architecture and role in supporting the X11 protocol in greater detail.

For more information about the X11 protocol, see the X Window System C Library and Protocol Reference by Robert W. Scheifler, James Gettys, and Ron Newman.

2.1 Generating a Protocol Request

When a DECwindows client program needs to generate output on a screen connected to a display, the client calls an Xlib or Toolkit routine to perform the output. Xlib translates these routines into one or more protocol requests. The protocol request is sent from a client to server to invoke some operation in the server. Requests may be synchronous (the client waits until the server sends a reply packet) or asynchronous (no reply is generated and the client may send more requests).

The protocol request is either one of the core protocol requests or a protocol request that is interpreted by an extension. The format of the core protocol request is predefined to ensure portability of core requests across various implementations of the X Window System. The format of the protocol request is shown in Figure 2-1.

Figure 2-1 Protocol Request Format

Every request consists of a 4-byte header, which contains an 8-bit "major" opcode, a spare data byte that is usually used for the "minor" opcode of an extension, and a 16-bit length field. The header is followed by zero or more additional bytes of data; unused bytes are not required to be zero, except in a few special cases such as image text.

The core protocol requests use only seven of the eight available bits of the opcode field in the request header; major opcodes 0 through 127 are reserved for core requests. Extensions use all eight bits, and opcodes 128 through 255 are reserved for extensions.

Because the 128 opcodes available for extensions could be consumed fairly quickly, extensions usually have an additional 8-bit minor opcode encoded in the spare data byte of the request header. This minor opcode increases the number of requests that can be associated with a major opcode. By convention, each extension uses one major opcode.

The length field is a 16-bit value that defines the total number of longwords in the request, including the header. For example, if the value of the length field was 4096, multiply 4096 times 4 to compute a request length of 16,384 bytes. The maximum size of a protocol request that a server is willing to accept is server dependent; the server communicates this maximum request length to the client as part of the connection setup when a client opens a connection.

The length field must be exactly the number of longwords in the request. If the specified length is shorter or longer than the actual length, the protocol is corrupted and the default error handler may generate a fatal or nonfatal error. Under other circumstances an inconsistent length field can hang the server.

2.2 Xlib Output Buffering and Synchronization

Most of the Xlib routines add protocol requests to an output buffer; these protocol requests are later sent to the server when the buffer fills or is explicitly flushed by the client. The transport layer maintains the buffers on a per-connection basis. If a client explicitly flushes a buffer, only the output requests for that connection are affected; output buffered for other connections, either to the same or a different server, is not affected.

The total number of available output buffers is set by the server and Xlib when the transport layer is initialized. The Xlib output buffers for an individual connection are established when the connection to the server is opened. The format of the output request buffer is shown in Figure 2-2.

Figure 2-2 Output Buffer Containing a Protocol Request

The number of protocol requests that Xlib sends in a single output buffer depends on the amount of data that is associated with each request. Because the VMS implementation of Xlib tries not to split protocol requests across output buffers, Xlib adds requests to a buffer until a protocol request does not fit completely within the remaining space. Xlib then flushes the current buffer and adds the waiting protocol request to the head of a new buffer.

Xlib provides routines with which clients can control output buffering. If you do not want an output request to wait for the buffer to fill, you can follow it with an explicit call to a routine such as FLUSH, which sends all buffered output for a connection.

Xlib also includes routines that allow clients to synchronize output requests. Xlib accomplishes this synchronization by immediately flushing the client's Xlib output buffer after each output request and then calling a synchronization routine that generates a return.