|
HP OpenVMS Systems Documentation |
|
VMS DECwindows Transport Manual
3.3.1.3 Opening a ConnectionXlib 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:
3.3.1.4 Opening a Connection AsynchronouslyDECW$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.
As described in Section 3.3.1.4, 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.
The common transport uses the routines described in Table 3-13 to allocate and deallocate memory.
3.3.1.7 Common Transport Read RoutinesThe 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.
3.3.1.8 Writing to the TransportThe 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.
3.3.1.9 Transport Layer Timer MechanismThe 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.
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.
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.
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.
The transport-specific code performs the following functions:
Subsequent sections describe the transport-specific functions.
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.
As described in Section 3.3.2.1, 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:
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.
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.
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.
3.3.3.3 Reading XTCBs from a TransportThere 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.
3.3.3.4 Closing a ConnectionThe 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.
3.3.3.5 The Transport-Specific CallbackWhen 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.
|