HP OpenVMS Systems Documentation

Content starts here

VMS DECwindows Transport Manual

Previous Contents Index Opening a Connection

Xlib clients call the Xlib OPEN DISPLAY routine to establish a connection with a server. Xlib in turn calls the DECW$XPORT_ATTACH_TRANSPORT and DECW$XPORT_OPEN routines.

The DECW$XPORT_OPEN routine performs the following functions:

  • Tries to find a transport that will initiate a connection. DECW$XPORT_OPEN searches the global XTDB queue for a transport whose family name matches the xportnam argument. xportnam is typically the transport specified in the last use of the SET DISPLAY command (for example, DECNET).
  • Copies the attached transport parameters to connection-specific parameters. Allocates IXTCC and XTPB data structures for the connection and partially establishes the connection context.
  • Updates the connection parameters if an itmlst argument was specified.
  • Changes to executive mode and calls the transport-specific open routine, XTFT$A_OPEN, to try to open the connection. Opening a Connection Asynchronously

DECW$XPORT_OPEN executes in executive mode to open a connection to a server. However, if your specific transport indicates (by status return) that it is necessary to wait for a connection to be established across a network, DECW$XPORT_OPEN can wait in user mode for the open to complete. Waiting in user-mode allows a user to press the Ctrl/Y key combination to exit the application in the event of a problem.

The DECW$XPORT_OPEN code waits in either executive or user mode, depending on the implementation of the transport-specific XTFT$A_OPEN routine. Waiting in executive mode is discouraged and is provided only for backward compatibility. Completing an Asynchronous Open

As described in Section, a specific transport can indicate (by status return) that it is necessary to wait for a connection to be established across a network.

Specifically, if a transport-specific XTFT$A_OPEN routine returns a status of DECW$_STALL, DECW$XPORT_OPEN knows that the connection is not completely set up and calls $SYNCH in user mode to wait. DECW$XPORT_OPEN sets an event flag and IOSB for this purpose.

If the specific transport returns DECW$_STALL, it must call the DECW$$XPORT_OPEN_COMPLETE routine when it has completed the open. DECW$$XPORT_OPEN_COMPLETE waits for the connection to complete, finishes the initialization of the XTCC flags, and notifies DECW$XPORT_OPEN that the asynchronous open operation has completed. DECW$$XPORT_OPEN_COMPLETE sets the event flag and the IOSB to complete the wait initiated by DECW$XPORT_OPEN. Allocating Transport Memory

The common transport uses the routines described in Table 3-13 to allocate and deallocate memory.


The VMS Run-Time Library memory allocation routines cannot be used from inner access (such as executive) modes.

Table 3-13 Transport Memory Allocation Routines
Routine Name Description
DECW$XPORT_ALLOC_INIT_QUEUES Allocates storage for an XTCC, XTCQ, and all of the XTCBs for a connection. These structures are user-writable. Places all of the XTCBs on the appropriate free queues.
DECW$XPORT_ALLOC_PMEM Allocation routine for protected (user-readable, executive-writable) structures. Allocates a block of storage of a given size.
DECW$XPORT_DEALLOC_PMEM Memory deallocation routine (companion to DECW$XPORT_ALLOC_PMEM). Deallocates previously allocated structure.
DECW$XPORT_DEALLOC_QUEUES Deallocates a block of storage previously allocated for the queues of a connection. Common Transport Read Routines

The common transport performs a read operation to remove an input XTCB or return an input XTCB to the queue. There are three read routines: DECW$$XPORT_FREE_INPUT, DECW$XPORT_READ, and DECW$XPORT_READ_COMPLETE. The read routines are described in Table 3-14.

Table 3-14 Transport Read Routines
Routine Name Description
DECW$$XPORT_FREE_INPUT Returns an XTCB acquired with DECW$XPORT_READ to the input free queues. If no XTCB was on the queue and notification is desired, DECW$$XPORT_FREE_INPUT removes the XTCB and initiates a read operation on the connection; that is, it calls the transport-specific XTFT$A_FREE_INPUT_BUFFER routine, which in turn does a read operation for the underlying transport.
DECW$XPORT_READ Attempts to remove an XTCB from the head of the input work queue. If the attempt succeeds, the address of the XTCB is returned to the caller and it returns with successful status. If DECW$XPORT_READ fails, one of the following actions occurs:
  • If it fails and is a nonblocking operation, input notification is enabled and it returns failed status.
  • If it fails and is a blocking operation, the call uses a $SYNCH system service call to wait for an input buffer to become available.
DECW$XPORT_READ_COMPLETE Read completion AST routine. DECW$XPORT_READ_COMPLETE is called by a specific transport to check the status of the completed I/O. If the I/O was successful, DECW$XPORT_READ_COMPLETE updates buffer and connection state (lengths, pointers, and so forth) and attempts to get another free buffer for reading. If a problem occurred, DECW$XPORT_READ_COMPLETE sets the connection state accordingly. Writing to the Transport

The common transport includes routines to write data from the user's environment to a connection. The transport-common routines in turn call transport-specific routines to send the data across the wire.

The common transport write routines are described in Table 3-15.

Table 3-15 Common Transport Write Routines
Name Description
DECW$XPORT_GET_OUTPUT_BUFFER Gets an XTCB from the output free queue. The mode argument modifies the operation:
  • If the no-block bit is set and no XTCB is available when the call is made, the routine returns a buffer-not-available status and output notification is enabled.
  • If the no-block bit is clear, a call to $SYNCH is made to wait for a buffer to become available. If timeouts are enabled, it is possible for the $SYNCH call to time out.

The data-length argument provides a hint as to what size buffer the caller should receive.

DECW$XPORT_WRITE Initiates a writing operation on the connection associated with an XTCC. The DECW$XPORT_WRITE routine copies the data from a buffer provided by the user to XTCBs. DECW$XPORT_WRITE supports both blocking and nonblocking modes.

DECW$XPORT_WRITE may perform multiple callback operations to the user's callback routine, specified by the copy_rtnadr argument, to get data copied from the caller's environment into the XTCBs.

copy_rtnadr is called with the address of an XTCB as an argument and the user-specified copy_rtnarg argument. The transport user is expected to partially fill the XTCB and return with the status of the write request.

Works similarly to DECW$XPORT_COPY_AND_WRITE but allows the caller to copy data from noncontiguous structures or compute the data dynamically when that is more practical.

DECW$XPORT_COPY_AND_WRITE Initiates a writing operation on the connection associated with the XTCC. DECW$XPORT_COPY_AND_WRITE performs a buffered write operation and returns the size of the data actually copied in the retbuflen argument.
DECW$XPORT_CHAINED_WRITE Initiates a writing operation on the connection associated with the XTCC. The itmlst argument specifies a number of buffers to be written to the connection. Two types of buffers are supported: XTCBs and user buffers. If the specific transport being used does not support writing from the user's buffer, DECW$XPORT_CHAINED_WRITE performs a copy operation using DECW$XPORT_COPY_AND_WRITE. Transport Layer Timer Mechanism

The transport layer timer mechanism is used to create an inner-mode AST at 5-second intervals so that the transport-common layer can search through the transport descriptors and connection contexts to find work that needs to be done. This timer mechanism is particularly useful in generating timeouts for $SYNCH operations, such as XPORT_IN_NOTIFY_WAIT, that have gone on too long.

When the time period expires, the timer finds connections that have been waiting for the number of ticks specified in the connection's XTPB. The wait operations are completed by assigning a SS$_TIMEOUT status to the appropriate I/O status block (IOSB), setting an event flag, and setting the XTCC$V_DYING bit in the XTCC. Closing a Connection

A transport connection is closed in response to a call to the Xlib CLOSE DISPLAY routine, or the server closing the connection. The XTCC data structure XTCC$V_DYING field is set when the connection is to be closed.

The DECW$XPORT_CLOSE routine terminates a connection and releases the resources that are associated with the connection. The server and Xlib are expected to return any XTCBs acquired through DECW$XPORT_READ and DECW$XPORT_GET_OUTPUT_BUFFER before calling DECW$XPORT_CLOSE. After calling DECW$XPORT_CLOSE, the structures used by the connection (XTCC, XTCQ, IXTCC, XTPB, and XTCBs) must not be referenced.

The DECW$XPORT_CLOSE routine calls the transport-specific connection close routine to actually break the network link. Outputting Messages for Debugging

The transport-common layer includes a DECW$XPORT_FAO routine that specific transports can call to output messages for debugging purposes. For example, a specific transport can include calls to DECW$XPORT_FAO at crucial points in the connection-open process to make sure that the connection is proceeding correctly. (See Example 8-12 for an example from the sample transport.)

DECW$XPORT_FAO formats the message string using the VMS system service $FAO and then outputs it. You pass DECW$XPORT_FAO the address of a string descriptor and, optionally, up to 20 variable arguments.

DECW$XPORT_FAO is most easily used from a macro. See Example 8-1 for an example macro called XPORT_FAO, which can take any number of arguments.

If DECW$XPORT_FAO is called in user mode, the message need only be formatted and sent to SYS$OUTPUT. If DECW$XPORT_FAO is called in executive mode, it queues a user-mode AST to deliver the message to SYS$OUTPUT. Buffer Compression

The transport-common layer includes a routine that provides buffer compression for the XTCB queues. The DECW$XPORT_COMPACT_QUEUE routine eliminates gaps in a queue of XTCBs with data. Buffer compression is especially useful on the client side because the server can send large numbers of events, replies, and errors to Xlib in partially filled buffers.

Although Xlib processes input as often as possible, it is possible that, at any given time, all of the input XTCB buffers will be in use and Xlib will not be able to insert (INSQTI) buffers on the free queue. Therefore, when the specific transport attempts to remove (REHQHI) a free input buffer for a $QIO read operation, a buffer might not be available.

To account for this possibility, if the .xtcc [XTCC$V_MODE] field indicates that a client initiated the read, the DECW$XPORT_READ_COMPLETE routine calls the common-transport buffer compacting routine, DECW$XPORT_COMPACT_QUEUE, to try to compact the free queue to get a buffer for the $QIO read. (If the .xtcc [XTCC$V_MODE] field indicates that a server initiated the read, no buffer compression is performed.)

Buffer compression is performed only as a result of a $QIO read-completion on the client side of the connection when a free buffer is not initially available. The DECW$XPORT_COMPACT_QUEUE routine itself is called only from within the DECW$XPORT_READ_COMPLETE routine.

3.3.2 Transport-Specific Functions

The transport-specific code performs the following functions:

  • Initializes and returns the address of the XTFT
  • Initializes (attaches) a specific transport
  • Connects a client to a server by means of the chosen transport
  • Writes data from XTCBs to the transport
  • Reads data into XTCBs from the transport
  • Closes a connection and releases connection structures
  • Initiates image rundown processing for the connection

Subsequent sections describe the transport-specific functions. Initializing the Transport

The XTFT data structure contains the addresses of the transport-specific routines. The common transport must therefore always be able to find the transport-specific XTFT structures. To make sure that the common transport can find the XTFT structures, every transport-specific image must provide a routine, DECW$TRANSPORT_INIT, as the initialization routine of that image.

A transfer vector to the DECW$TRANSPORT_INIT routine must be provided in the first image section of the transport-specific image. See Section 8.2.23 for an example of this transfer vector.

The DECW$XPORT_ATTACH_TRANSPORT routine calls the DECW$TRANSPORT_INIT routine to initialize and return the XTFT. Once the XTFT is initialized, DECW$XPORT_ATTACH_TRANSPORT calls the XTFT$A_ATTACH_TRANSPORT routine found in this data structure to complete the transport-specific initialization.

3.3.3 Attaching the Specific Transport

As described in Section, the DECW$XPORT_ATTACH_TRANSPORT routine calls the XTFT$A_ATTACH_TRANSPORT routine to complete the transport-specific initialization.

XTFT$A_ATTACH_TRANSPORT functions differently depending on whether the server or Xlib called it. If Xlib called it, XTFT$A_ATTACH_TRANSPORT performs relatively little transport-specific initialization.

If the server called it, XTFT$A_ATTACH_TRANSPORT performs additional transport-specific initialization. For example, for DECnet, XTFT$A_ATTACH_TRANSPORT might function as follows:

  • Create a mailbox
  • Assign a channel to the network device and associate the mailbox with this channel
  • Associate an object name (for example, X$X0) to which clients may refer with the network channel
  • Issue a $QIO read to the mailbox to receive notification of connection attempts by clients

The TRANSPORT_READ_QUEUE and TRANSPORT_READ_AST routines in the example transport are called to initiate a read on the transport channel. TRANSPORT_READ_QUEUE is called by XTFT$A_ATTACH_TRANSPORT to perform the first $QIO read on the newly attached connection. The XTFT$A_ATTACH_TRANSPORT routine assigns a network channel for the transport and then calls TRANSPORT_READ_QUEUE to listen on the channel for a connection attempt from a client.

TRANSPORT_READ_AST is a sample read-completion AST routine for the transport's network channel. Opening a Connection

The XTFT$A_OPEN routine tries to connect a client to a server.

The transport-common DECW$XPORT_OPEN routine attempts to locate a transport with a name matching the one passed in the xportnam argument (for example, DECNET). If a matching transport is found, the XTFT$A_OPEN routine is called with the server number and workstation node name arguments, and an IXTCC and XTPB that have been partially initialized. (Xlib calls DECW$XPORT_OPEN with an item list that gives its desired defaults.)

XTFT$A_OPEN is responsible for the allocation and initialization of the XTCC, XTCQ, and all necessary XTCBs and for starting an initial read if needed. Parameters that would affect these operations are found in the XTPB attached to the IXTCC by means of the IXTCC$A_TPB field.

XTFT$A_OPEN can also open the connection asynchronously and indicate to the transport-common DECW$XPORT_OPEN routine that it should wait in user mode. Waiting in user-mode allows a user to press Ctrl/Y to exit the application in the event of a problem.

If a transport-specific XTFT$A_OPEN routine completes asynchronously, it must call the transport common DECW$XPORT_OPEN_COMPLETE routine when it has completed the open. DECW$XPORT_OPEN_COMPLETE notifies DECW$XPORT_OPEN that an asynchronous open operation has completed. Writing XTCBs to a Transport

There are three transport-specific routines that are called through the XTFT data structure for writing to the transport:


Many transport-specific images will also need a write-completion routine. A sample write-completion AST routine, WRITE_AST, is shown in Chapter 8 .

The transport-specific write routines are described in Table 3-16.

Table 3-16 Transport-Specific Write Routines
Routine Description
XTFT$A_EXECUTE_WRITE Writes the contents of an XTCB to a connection. XTFT$A_EXECUTE_WRITE is called when the common transport inserts an XTCB on an empty output work queue. XTFT$A_EXECUTE_WRITE must decide whether to call DECW$$XPORT_WRITE so that an I/O operation can be started in executive mode.
XTFT$A_WRITE Attempts to write an XTCB to the connection associated with the XTCC. XTFT$A_WRITE writes the contents of XTCBs across the wire. If there is nothing to write, that is, the XTCBs are empty, XTFT$A_WRITE inserts the XTCBs on the appropriate (small or large) output free queue. This is a method of populating the free queues.

If the write operation fails, XTFT$A_WRITE puts the XTCB back at the head of the output work queue and sets the connection status to dying.

XTFT$A_WRITE_USER Attempts to write a buffer in the user's address space to a transport connection. XTFT$A_WRITE_USER can use the common routine DECW$XPORT_COPY_AND_WRITE to copy the user's buffer into XTCBs and queue them for writing, or wait for the output work queue to empty and issue $QIOs directly from the user's buffer. Reading XTCBs from a Transport

There are two transport-specific routines that are called through the XTFT data structure for reading from the transport: XTFT$A_EXECUTE_FREE and XTFT$A_FREE_INPUT_BUFFER.

Many transport-specific images will also need a read-completion routine. A sample read-completion AST routine, FREE_INPUT_AST, is shown in Chapter 8.

The transport-specific read routines are described in Table 3-17.

Table 3-17 Transport-Specific Read Routines
Routine Description
XTFT$A_EXECUTE_FREE Returns an XTCB to a local connection. DECW$XPORT_EXECUTE_FREE calls XTFT$A_EXECUTE_FREE to remove the buffer just placed on the input free queue. In the case of DECnet or TCP/IP, the buffer is then used to store the result of the next $QIO read operation for the connection.
XTFT$A_FREE_INPUT_BUFFER In the case of DECnet or TCP/IP, XTFT$A_FREE_INPUT_BUFFER does a $QIO read operation for a connection into the provided buffer. If there is nothing to read for the connection, XTFT$A_FREE_INPUT_BUFFER inserts the XTCB on the free queue and sets the connection state to dying. Closing a Connection

The connection close routines close a connection and release the structures associated with the connection. The common transport layer begins deallocation of all connection resources including, but not limited to, channels, XTCC, XTCBs, XTPB, and transport-private data. After this is done, the transport user must not refer to any structures associated with the connection.

There are two transport-specific routines that work together to close a connection: XTFT$A_CLOSE and XTFT$A_RUNDOWN. XTFT$A_CLOSE uses an additional routine, CLOSE_AND_DEALLOCATE_AST, to clean up after aborted I/O operations. A sample CLOSE_AND_DEALLOCATE_AST routine is shown in Chapter 8.

The transport-specific connection close routines are described in Table 3-18.

Table 3-18 Transport-Specific Connection Close Routines
Routine Description
XTFT$A_CLOSE Marks the connection as dying and cancels and deassigns the channel to the connection. XTFT$A_CLOSE declares an AST to the CLOSE_AND_DEALLOCATE_AST routine that is executed after any completion ASTs. This performs the final cleanup operations such as structure invalidation and deallocation.
XTFT$A_RUNDOWN Invoked by the common transport when the current image exits. Each specific transport must release any resources necessary for a clean exit. The Transport-Specific Callback

When a specific transport receives a connection request, it completely sets up the new connection and then calls the server connection-request routine, identified by the XTDB$A_CONNECT_REQUEST field, to see if the server accepts the connection. The sample transport shown in Chapter 8 uses the TRANSPORT_READ_AST, TRANSPORT_READ_QUEUE, and TRANSPORT_OPEN_CALLBACK routines to accomplish this task.

Previous Next Contents Index