VMS DECwindows Transport Manual
VMS DECwindows Transport Manual
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.
This is a new manual.
VMS Version 5.4
VMS DECwindows Motif Version 1.0
Digital Equipment Corporation
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
No resposibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
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
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.
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.
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
This document assumes that you are familiar with the overall design of
the VMS DECwindows implementation.
The VMS DECwindows Transport Manual is organized into the following chapters:
- Chapter 1 provides an overview of the VMS DECwindows transport
- 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
- 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
- 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.
For more information about DECwindows, see the VMS DECwindows Motif
The following conventions are used in this manual:
mouse is used to refer to any pointing device, such as a
mouse, a puck, or a stylus.
A sequence such as Ctrl+x (or Ctrl/x) indicates that you must hold down
the key labeled Ctrl while you press another key or a pointing device
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
In format descriptions, parentheses indicate that, if you choose more
than one option, you must enclose the choices in parentheses.
Boldface text represents the introduction of a new term or the name of
an argument, a field, a resource, or a reason.
Boldface text is also used to show user input in online versions of
Italic text represents information that can vary in system messages
(for example, Internal error
Uppercase letters indicate that you must enter a command (for example,
enter OPEN/READ), or they indicate the name of a routine, the name of a
file, the name of a file protection code, or the abbreviation for a
Hyphens in coding examples indicate that additional arguments to the
request are provided on the line that follows.
Unless otherwise noted, all numbers in the text are assumed to be
decimal. Nondecimal radixes---binary, octal, or hexadecimal---are
Overview of the VMS DECwindows Transport Layer
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
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
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
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
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
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
- 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
1.3 Using TCP/IP with DECwindows
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
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 VMS server supports the DECnet and local transports by default.
Other transport types, including TCP/IP and third-party transports, can
be specified through the SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.COM file.
DECwindows transports can use the VMS AST and QIO mechanisms to queue
and dequeue X11 protocol requests, replies, and events for a
connection. However, the AST and QIO mechanisms are just VMS system
interfaces to the actual transport service and do not affect how the
data is actually sent or received.
X11 Protocol Overview
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
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
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
The format for replies, errors, and events is different from the format
for requests. See the X Window System C Library and Protocol
Reference for more information.
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 placement and interpretation of the minor opcode, and all other
nonheader fields in extension requests, are not defined by the core
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 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.
The server negotiates the size of the largest request for each
connection when the connection is opened. The VMS DECwindows server
accepts up to a 16Kb protocol request.
The maximum size of a protocol request allowed by the X11 protocol is
256Kb (65,535 times 4). The core protocol allows Xlib to split protocol
requests across output request buffers, and other Xlib implementations
are likely to do this. It is therefore possible that a read request
will not return a complete protocol message and Xlib and the server
must handle this case.
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.