HP OpenVMS Systems Documentation

When the transport layer is initialized, the transport-common code creates a global transport parameter block (XTPB) data structure that contains default parameters. The default parameters are inherited by every network-specific transport that is subsequently attached. The attached transport can override the defaults.

Three levels of XTPB data structures are eventually built:

• A global XTPB data structure
• A transport-specific XTPB data structure
• A connection-specific XTPB data structure

The contents of the global XTPB data structure are copied to the transport-specific XTPB data structure when a transport is attached, and from the transport-specific XTPB data structure to a connection-specific XTPB data structure when a connection is established. The server and Xlib can override this inheritance of XTPB parameter values. After an XTPB has been created, changes to its parent's values do not change its values.

All XTPB data structures are allocated from memory pages that have user-mode read access/executive-mode write access (UREW) to protect them from modification by any less privileged access mode.

The XTPB data structure is shown in Figure 3-9.

Figure 3-9 XTPB Data Structure

As described in Section 3.2.2, the transport communications context (XTCC) data structure describes an established connection. The server and Xlib use the XTCC to identify a connection when calling the DECwindows transport layer. The XTCC structure exists during the lifetime of a connection. This is a user-writable structure.

The XTCC data structure is shown in Figure 3-11.

Figure 3-11 XTCC Data Structure

The transport communication queue (XTCQ) data structure contains the six per-connection communication queues and their state information. The six per-connection communication queues, which are described in more detail in Section 3.1, are as follows:

• Event Work Queue. Identified by the XTCQ$L_EW_RFLINK and XTCQ$L_EW_RBLINK fields in the XTCQ.
• Event Free Queue (small and large). Identified by the XTCQ$L_EFS_RFLINK, XTCQ$L_EFS_RBLINK, XTCQ$L_EFL_RFLINK, and XTCQ$L_EFL_RBLINK fields in the XTCQ.
• Request Work Queue. Identified by the XTCQ$L_RW_RFLINK and XTCQ$L_RW_RBLINK fields in the XTCQ.
• Request Free Queue (small and large). Identified by the XTCQ$L_RFS_RFLINK, XTCQ$L_RFS_RBLINK, XTCQ$L_RFL_RFLINK, and XTCQ$L_RFL_RBLINK fields in the XTCQ.

The XTCQ data structure exists during the lifetime of a connection and is user-modifiable.

The XTCQ data structure is shown in Figure 3-13.

Figure 3-13 XTCQ Data Structure

Each specific transport shareable image provides a set of transport-specific routines that are used for all connections using that transport. The transport function table (XTFT) data structure contains the addresses of these routines. During a transport attach operation, the transport-specific DECW$TRANSPORT_INIT routine initializes and returns that transport's XTFT.

The XTFT data structure exists during the lifetime of a specific transport and is accessible by the common transport. The XTFT data structure is shown in Figure 3-15.

Figure 3-15 XTFT Data Structure

Table 3-12 shows the contents of the XTFT data structure.

As described in Section 1.2, the transport layer is separated into transport-common and transport-specific functions. The routines that support the transport-common functions have names of the form DECW$XPORT_xxx and provide the generic services needed by Xlib or the server.

Some transport-common routines only select and call the correct transport-specific routine. Other transport-common routines perform substantial processing prior or subsequent to invoking the associated transport-specific routine.

A special set of utility routines and macro definitions perform thread suspension and resumption, global section mapping and maintenance, queue maintenance, and communication between transport layer components for use by transport layer developers. See Chapter 7 for more information.

The transport-common routines call transport-specific routines that are private to a particular transport service, such as DECnet. The addresses of the transport-specific routines are contained in the XTFT data structure and, along with VMS packaging requirements, comprise the interface to which a transport developer must program.

3.3.1 Transport-Common Functions

The transport-common code performs the following functions:

• Initializes the transport-specific layer
• Attaches the transport-specific layer
• Opens a connection
• Gets and sets transport-common and per-connection attributes
• Allocates memory
• Reads from the input queue
• Writes to the output queue
• Closes a connection
• Outputs messages for debugging
• Provides buffer compression

Subsequent sections describe the transport-common functions.

3.3.1.1 Initializing the Transport-Common Layer

The DECW$XPORT_INITIALIZE routine is called before any other DECwindows transport-common routine. Xlib and the server call the DECW$XPORT_INITIALIZE routine to initialize the transport-common code. The common transport knows whether it was called by Xlib or the server by a caller_type argument that identifies the caller as a client (DECW$K_XPORT_CLIENT) or as the server (DECW$K_XPORT_SERVER).

DECW$XPORT_INITIALIZE initializes the global XTPB data structure, from which other XTPB data structures inherit their default values. (See Section 3.2.1.)

Transports and connections that are subsequently attached or opened inherit the parameters set at initialization time unless they override them in an itmlst argument to the DECW$XPORT_INITIALIZE or DECW$XPORT_ATTACH_TRANSPORT routines. Both Xlib and the server override some of these defaults.

The DECW$XPORT_INITIALIZE routine calls a transport-common routine to load the global XTPB data structure with the attributes passed in the itmlst argument.

The itmlst argument can specify the following parameters:

• The address of a procedure to call when an input operation is completed on the connection and input notification has been enabled
• The address of a procedure to call when an output operation is completed on the connection and output notification has been enabled
• The size of the data area of the large communication buffers used by transport
• The size of the data area of the small communication buffers used by transport
• A value to be passed to the input notification routine
• A value to be passed to the output notification routine
• The number of the event flag to be set for input notification
• The number of the event flag to be set for output notification
• The number of seconds the default waiting procedures are allowed to wait for output completion
• The number of seconds the default waiting procedures are allowed to wait for input completion

On the client side of the connection, Xlib calls DECW$XPORT_ATTACH_TRANSPORT to attach and initialize only those transports to which it wants to connect. Xlib determines the transports to attach and initialize as follows:

• If the call to the Xlib OPEN DISPLAY routine specifies a display name, Xlib parses the display name to determine the transport to initialize.
• If the call to the Xlib OPEN DISPLAY routine specifies a null display name, Xlib uses the result of the last SET DISPLAY command to determine the transport to initialize.

On the server side of the connection, the server must tell the common transport which specific transports to attach and initialize. The server uses the logical name DECW$SERVER_TRANSPORTS (see SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.TEMPLATE) to accomplish this.

For example, DECW$SERVER_TRANSPORTS could translate to DECNET,LOCAL,TCPIP. The server calls the common transport DECW$XPORT_ATTACH_TRANSPORT routine for each transport identified by the logical name. The transport_name argument specifies the transport, such as DECNET.

DECW$XPORT_ATTACH_TRANSPORT needs a way to associate the transport name specified in the transport_name argument with a specific transport's image. When called by either Xlib or the server, DECW$XPORT_ATTACH_TRANSPORT attempts to locate and activate an image with a name in the form SYS$SHARE:DECW$TRANSPORT_transport_name.EXE. If it does not find one, DECW$XPORT_ATTACH_TRANSPORT looks for a name in the form SYS$SHARE:DECW_TRANSPORT_transport_name.EXE.

For example, if DECW$XPORT_ATTACH_TRANSPORT could not find an image with the name SYS$SHARE:DECW$TRANSPORT_FOO.EXE, it would look for SYS$SHARE:DECW_TRANSPORT_FOO.EXE.

If the image activation is successful, DECW$XPORT_ATTACH_TRANSPORT builds an XTDB, initializes the common fields, and calls the transport-specific DECW$TRANSPORT_INIT routine to complete the initialization by initializing the XTFT data structure with the addresses of the transport-specific routines.

Every transport-specific image (SYS$SHARE:DECW$TRANSPORT_transport_name.EXE or SYS$SHARE:DECW_TRANSPORT_transport_name.EXE) must provide an implementation of DECW$TRANSPORT_INIT for its initialization routine. A transfer vector to the DECW$TRANSPORT_INIT routine must be placed in the first image section of the transport-specific image.

The DECW$XPORT_ATTACH_TRANSPORT routine performs the following functions:

• Validates the transport_name argument.
• Checks to see if the transport-specific image is already attached.
• Builds the transport-specific image file name.
• Activates the transport-specific image.
• Calls the transport-specific DECW$TRANSPORT_INIT initialization routine to get the address of the XTFT.
• Allocates memory for XTDB and XTPB. Copies the contents of the global XTPB to the new XTPB.
• Attaches the XTPB to the XTDB and sets the XTDB attributes from the itmlst argument.
• Fills in the XTDB contents, such as the transport family name.
• Enqueues the XTDB on the global XTDB queue.
• Calls the transport-specific attach routine, XTFT$A_ATTACH_TRANSPORT, and returns the status.