HP OpenVMS Systems Documentation

This chapter describes the transport-specific routines that you must implement if you write your own transport-specific component.

Most of the routines described in this chapter are called by the transport-common code through the XTFT data structure. However, this chapter also describes supporting routines, such as AST completion routines, that you must write if your transport design requires it.

The transport-specific routines are listed in Table 6-1.

The routine descriptions document the generic functions that the transport-common component expects the transport-specific routines to perform. Your implementation of the routines depends on your underlying transport and may therefore differ in details. However, your implementation of the routines must fullfill the transport-common expectations.

See Chapter 8 for examples of TCP/IP implementations of these routines.

6.1 Condition Values

When a transport-specific routine finishes execution, a numeric status value is returned in R0. This status value is returned as the status value of the transport-common routine. Your implementation of the transport-specific routines can return any valid VMS condition value.

Completes the connection close initiated by XTFT$A_CLOSE. Internal to specific transport.

Format

CLOSE_AND_DEALLOCATE_AST itcc

Argument

itcc

VMS usage:	record
type:	ixtcc
access:	modify
mechanism:	reference

The IXTCC of the connection to close.

Description

The CLOSE_AND_DEALLOCATE_AST routine is invoked as an AST by the XTFT$A_CLOSE routine to complete the connection-close process. Once CLOSE_AND_DEALLOCATE_AST executes, it is assumed that neither the transport caller nor any part of transport will refer to this connection again.

CLOSE_AND_DEALLOCATE_AST removes the IXTCC from the IXTCC queue in the XTDB, decrements the reference count in the XTDB, and releases the XTCBs on the communication queue.

CLOSE_AND_DEALLOCATE_AST also zeroes various fields in the XTCC and IXTCC to catch any subsequent references to the connection and deallocates the remaining connection structures.

CLOSE_AND_DEALLOCATE_AST is invoked in executive mode.

Section 8.2.11 shows a sample implementation of the CLOSE_AND_DEALLOCATE_AST routine.

Initializes and returns the XTFT data structure.

Format

xtft=DECW$TRANSPORT_INIT

RETURNS

VMS usage:	record
type:	xtft
access:	write
mechanism:	reference

Returns a pointer to the XTFT data structure.

Arguments

None.

Description

DECW$TRANSPORT_INIT initializes and returns the XTFT data structure through which the transport-specific routines are called.

The common transport must always be able to find the transport-specific XTFT structures. To ensure that the common transport can find the XTFT structures, all specific transports provide a transfer vector to the DECW$TRANSPORT_INIT routine as the first image section in the specific transport shareable image.

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

The DECW$TRANSPORT_INIT routine is called in executive mode.

See Section 8.2.23 for a sample implementation of the DECW$TRANSPORT_INIT routine and the associated transfer vector.

Detaches from the transport and starts polling for a transport restart. Internal to specific transport.

Format

DETACH_AND_POLL tdb

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write
mechanism:	value

Returns a longword condition value in R0.

Argument

tdb

VMS usage:	record
type:	xtdb
access:	modify
mechanism:	reference

The XTDB of the transport that you want to poll.

Description

The DETACH_AND_POLL routine releases the transport's connection-specific and connection-accept channels and then polls the transport to attempt a restart. DETACH_AND_POLL does not attempt to restart the transport if the XTDB$V_DYING bit is set. If it is unable to poll for the restart, DETACH_AND_POLL reports that the reattach attempt failed.

DETACH_AND_POLL is invoked in executive mode.

See Section 8.2.20 for a sample implementation of the DETACH_AND_POLL routine.

AST completion routine for transport read operations. Internal to specific transport.

Format

FREE_INPUT_AST xtcb

Argument

xtcb

VMS usage:	record
type:	xtcb
access:	modify
mechanism:	reference

The XTCB to insert on the input work queue.

Description

FREE_INPUT_AST is the AST completion routine for transport read operations. FREE_INPUT_AST is used by the XTFT$A_FREE_INPUT_BUFFER routine with the XTCB buffer returned by the $QIO read.

In prior versions of the DECwindows transport-common layer, each specific transport had to perform its own read-completion processing. Beginning with this version, specific transports that support an AST interface should call the transport-common DECW$XPORT_READ_COMPLETE routine to perform the read completion and initiate additional reads. See the description of the DECW$XPORT_READ_COMPLETE routine in Chapter 5 for more information.

You must perform the following processing before calling DECW$XPORT_READ_COMPLETE:

• The connection-context address is stored in the XTCB, an unprotected location. Call the VALIDATE_XTCC macro to confirm that the address is uncorrupted and to get the address of the IXTCC. If the XTCC ID is known and is valid, VALIDATE_XTCC returns the previously registered address of the IXTCC data structure in the ixtcc argument.
• The number of bytes read by the just completed I/O is in the second word of the IOSB (.iosb [1]). Use this number to set the length field of the XTCB. DECW$XPORT_READ_COMPLETE requires this field to be valid.

FREE_INPUT_AST is invoked in user or executive mode.

See Section 8.2.8 for a sample implementation of the FREE_INPUT_AST routine.

Attempts to reattach the transport when the timer interval has expired. Internal to specific transport.

Format

REATTACH_AST tdb

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write
mechanism:	value

Returns a longword condition value in R0.

Argument

tdb

VMS usage:	record
type:	xtdb
access:	modify
mechanism:	reference

The XTDB of the transport that you want to reattach.

Description

REATTACH_AST is the AST completion routine for the $SETIMR system service invoked by the DETACH_AND_POLL routine. REATTACH_AST calls the transport-specific XTFT$A_ATTACH_TRANSPORT routine to reattach the transport.

REATTACH_AST is invoked in executive mode.

See Section 8.2.21 for a sample implementation of the REATTACH_AST routine.

Performs a callback to the client during the connection-open sequence. Internal to specific transport.

Format

TRANSPORT_OPEN_CALLBACK itcc

Argument

itcc

VMS usage:	record
type:	ixtcc
access:	modify
mechanism:	reference

The IXTCC associated with this connection.

Description

TRANSPORT_OPEN_CALLBACK performs a callback to the client during the connection-open sequence. Transport semantics require a callback, as opposed to a simple AST, during the connection-initiation sequence of a connect-to-server operation. Because the callback cannot be performed in executive mode, TRANSPORT_OPEN_CALLBACK is invoked as a user-mode AST to complete this operation.

If the user accepts the connection, TRANSPORT_OPEN_CALLBACK populates the communication queue with transport buffers and initiates I/O. If it fails, TRANSPORT_OPEN_CALLBACK generates a message and releases the connection resources.

The TRANSPORT_OPEN_CALLBACK routine is called in user-AST mode.

See Section 8.2.19 for a sample implementation of the TRANSPORT_OPEN_CALLBACK routine.

Read-completion AST routine for the transport's network channel. Internal to specific transport.

Format

TRANSPORT_READ_AST tdb

Argument

tdb

VMS usage:	record
type:	xtdb
access:	modify
mechanism:	reference

The XTDB associated with this connection.

Description

TRANSPORT_READ_AST is a read-completion AST routine for the transport's network channel. The TRANSPORT_READ_AST routine receives connection request notifications only. All other requests from clients are sent by means of the connection-specific channel, not the transport-specific channel, and do not follow the TRANSPORT_READ_QUEUE to TRANSPORT_READ_AST code path.

TRANSPORT_READ_AST must allocate and initialize an XTCC, put it on the XTDB for this transport, and then call the connection request action routine XTDB$A_CONNECT_REQUEST provided by the server.

The TRANSPORT_READ_AST routine is called in executive mode.

See Section 8.2.18 for a sample implementation of the TRANSPORT_READ_AST routine.

Initiates an asynchronous connection-accept operation. Internal to specific transport.

Format

TRANSPORT_READ_QUEUE tdb

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write
mechanism:	value

Returns a longword condition value in R0.

Argument

tdb

VMS usage:	record
type:	xtdb
access:	modify
mechanism:	reference

The XTDB associated with this connection.

Description

TRANSPORT_READ_QUEUE initiates an asynchronous connection-accept operation.

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.

In the case of the sample transport, the TRANSPORT_READ_QUEUE routine assigns a channel for this connection and then does a $QIO read operation with function IO$_ACCESS or IO$M_ACCEPT on the transport-specific channel created by XTFT$A_ATTACH_TRANSPORT. This $QIO performs the following functions:

• "Listens" on this channel for a $QIO connection request from a client.
• When a connection request from a client is received, the $QIO gets a description of the client node from the client.
• Calls the TRANSPORT_READ_AST routine to accept the connection. The transport must accept all valid connection requests; the server later decides if it wants to reject a connection from the client.

The TRANSPORT_READ_QUEUE routine is called in executive mode.

See Section 8.2.17 for a sample implementation of the TRANSPORT_READ_QUEUE routine.

AST completion routine for transport write operations. Internal to specific transport.

Format

WRITE_AST xtcb

Argument

xtcb

VMS usage:	record
type:	xtcb
access:	modify
mechanism:	reference

The XTCB to return to the appropriate free queue.

Description

WRITE_AST is an AST completion routine for transport write operations. WRITE_AST is used by the XTFT$A_WRITE routine to return an XTCB to the large or small free queue after a successful write operation and to initiate another write operation.

If the $QIO failed, or the connection is dying, WRITE_AST performs failure processing and prevents further operations on this connection. Failure processing is dependent upon the type of transport being used. In the case of the TCP/IP service provided by the ULTRIX Connection product (UCX), a failed I/O attempt to the connection indicates that a connection has aborted. When an I/O operation completes and the status indicates failure, the routine must perform all logical-link rundown operations, including setting the dying bit and error status, completing any process waits for input or output, and sending notification to the process that the connection has died.

After WRITE_AST returns the XTCB to the free queue, it attempts to remove another XTCB from the head of the output work queue and initiate a $QIO write operation. If the queue was empty, WRITE_AST clears the write disable flag for this connection by means of the XPORT_OUT_WRITE_ENABLE macro.

WRITE_AST is invoked in user or executive mode.

See Section 8.2.4 for a sample implementation of the WRITE_AST routine.

Performs the transport-specific initialization functions.

Format

XTFT$A_ATTACH_TRANSPORT tdb

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write
mechanism:	value

Returns a longword condition value in R0.

Argument

tdb

VMS usage:	record
type:	xtdb
access:	modify
mechanism:	reference

XTDB structure. This will have been initialized by the caller prior to entry.

Description

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 what calls it.

If Xlib calls it, XTFT$A_ATTACH_TRANSPORT does only some transport-specific initialization because clients attach specific transports when they open a connection.

If the server calls it, as determined by the XTDB XTDB$V_MODE field, XTFT$A_ATTACH_TRANSPORT creates a mailbox (if DECnet) and gets a channel to the device by means of $ASSGN. The specific transport uses this channel to listen for connection requests from clients; the specific transport later assigns a separate channel for each connection.

XTFT$A_ATTACH_TRANSPORT also indirectly calls the server's connection_request routine to see if the server accepts a connection from this client. If the returned status indicates failure, XTFT$A_ATTACH_TRANSPORT deallocates all resources acquired to this point and quits.

Once the channel is established, XTFT$A_ATTACH_TRANSPORT starts a $QIO read (by means of TRANSPORT_READ_QUEUE) on the channel.

XTFT$A_ATTACH_TRANSPORT is invoked in user or executive mode.

See Section 8.2.16 for a sample implementation of the XTFT$A_ATTACH_TRANSPORT routine.

Closes a transport connection.

Format

XTFT$A_CLOSE itcc

RETURNS

VMS usage:	cond_value
type:	longword (unsigned)
access:	write
mechanism:	value

Returns a longword condition value in R0.

Argument

itcc

VMS usage:	record
type:	ixtcc
access:	modify
mechanism:	by reference

Address of the connection to close.

Description

The XTFT$A_CLOSE routine initiates a series of operations that destroy a connection and release the data structures associated with the link.

After XTFT$A_CLOSE is called, the transport user must not refer to any structures associated with the connection. The transport begins deallocation of all connection resources including, but not limited to, channels, XTCC, XTCBs, XTPB, and transport-private data.

XTFT$A_CLOSE is invoked in executive mode.

See Section 8.2.10 for a sample implementation of the XTFT$A_CLOSE routine.