HP OpenVMS Systems Documentation

This chapter describes a walk-through of transport layer activities, including transport initialization, for both the server and Xlib. The walk-through gives an overview of the transport layer activities; it does not describe every step of the process. The walk-through is based on the sample TCP/IP transport.

This chapter describes the transport-common routines that are called by specific transports. If you write your own transport-specific layer, use these routines to allocate the communication queues, allocate and deallocate protected memory for structures, initiate read and write operations, and so forth.

Transport-common routines that are called only by other transport-common routines or by Xlib and the server are not described in this chapter.

Modifications to the transport-common routines are not recommended or supported.

The transport-common routines are listed in Table 5-1.

Reports that the transport could not accept a network link request.

Format

DECW$XPORT_ACCEPT_FAILED length, address, status

RETURNS

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

Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.

Arguments

length

VMS usage:	longword
type:	longword (unsigned)
access:	read
mechanism:	value

The length of the connection-failed message string.

address

VMS usage:	longword
type:	longword (unsigned)
access:	read
mechanism:	value

The address of the connection-failed message string, which is usually the node name of the failed connection.

status

VMS usage:	longword
type:	longword (unsigned)
access:	read
mechanism:	value

The condition value of the failed connection.

Description

DECW$XPORT_ACCEPT_FAILED builds a message vector that describes the nonacceptance of the connection request. The first element in the message vector is DECW$_ACCEPT_FAILED; the second element is the status argument.

The $PUTMSG system service is called in user mode regardless of the caller's mode:

• If DECW$XPORT_ACCEPT_FAILED was called in user mode, it calls $PUTMSG to write the error message.
• If DECW$XPORT_ACCEPT_FAILED was not called in user mode, it declares an AST to do the $PUTMSG in user mode.

DECW$XPORT_ACCEPT_FAILED is called by the TRANSPORT_READ_AST routine in Example 8-18.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_INSFMEM	There is insufficient memory to perform the operation.

Allocates storage for an XTCC, XTCQ, and all of the XTCBs for a connection. Places all of the XTCBs on the appropriate free queues.

Format

DECW$XPORT_ALLOC_INIT_QUEUES

itcc, xtcc_length, srp_data_length, lrp_data_length, e_srp_count, e_lrp_count, r_srp_count, r_lrp_count, extra_context_length, extra_context_address

RETURNS

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

Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.

Arguments

itcc

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

The IXTCC of the connection for which you want to allocate and initialize the queues. The IXTCC$A_TPB field must already be initialized.

xtcc_length

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The length, in bytes, of the XTCC to allocate. Can be longer than a standard XTCC if the specific transport has appended additional fields. Must be at least XTCC$C_LENGTH.

srp_data_length

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The length, in bytes, of the data portion of a small XTCB. No modification of the XTCB by specific transports is allowed.

lrp_data_length

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The length, in bytes, of the data portion of a large XTCB. No modification of the XTCB by specific transports is allowed.

e_srp_count

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The number of event small XTCBs to allocate. Can be 0 or greater.

e_lrp_count

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The number of event large XTCBs to allocate. Can be 0 or greater.

r_srp_count

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The number of request small XTCBs to allocate. Can be 0 or greater.

r_lrp_count

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The number of request large XTCBs to allocate. Can be 0 or greater.

extra_context_length

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The length, in bytes, of the transport-specific space to be allocated. Can be 0 or greater.

extra_context_address

VMS usage:	address
type:	longword
access:	write
mechanism:	reference

The location to receive the address of the extra transport-specific space.

Description

DECW$XPORT_ALLOC_INIT_QUEUES allocates a block of storage for an XTCC, XTCQ, and all of the XTCBs for a connection and places all of the XTCBs on the appropriate free queues. DECW$XPORT_ALLOC_INIT_QUEUES must allocate at least an XTCC; the other structures are optional.

If no XTCBs are requested, the XTCQ is not allocated. Otherwise, the XTCQ is allocated and initialized. The IXTCC is initialized with the addresses of the XTCC and the XTCQ, the queue headers, and the queue flags. The IXTCC$L_ICI and IXTCC$A_USER_REGION fields are also initialized.

When DECW$XPORT_ALLOC_INIT_QUEUES completes, the status of the data structures is as follows:

Data Structure	Status
IXTCC	The following fields are initialized: IXTCC$L_ICI IXTCC$A_TCC IXTCC$A_TCQ IXTCC$A_USER_REGION IXTCC$A_BUFFER_REGION IXTCC$A_IW_QUEUE IXTCC$A_IFS_QUEUE IXTCC$A_IFL_QUEUE IXTCC$A_OW_QUEUE IXTCC$A_OFS_QUEUE IXTCC$A_OFL_QUEUE IXTCC$L_IWQ_FLAG IXTCC$L_IFSQ_FLAG IXTCC$L_IFLQ_FLAG IXTCC$L_OWQ_FLAG IXTCC$L_OFSQ_FLAG IXTCC$L_OFLQ_FLAG
XTCC	The following fields are initialized: XTCC$W_SIZE XTCC$B_TYPE XTCC$B_SUBTYPE XTCC$A_TPB XTCC$A_TCQ XTCC$L_ICI XTCC$A_IW_QUEUE XTCC$A_IFS_QUEUE XTCC$A_IFL_QUEUE XTCC$A_OW_QUEUE XTCC$A_OFS_QUEUE XTCC$A_OFL_QUEUE XTCC$A_TCQ_FLAGS XTCC$L_IWQ_FLAG XTCC$L_IFSQ_FLAG XTCC$L_IFLQ_FLAG XTCC$L_OWQ_FLAG XTCC$L_OFSQ_FLAG XTCC$L_OFLQ_FLAG
XTCBs	Completely initialized
XTCQ	Completely initialized

DECW$XPORT_ALLOC_INIT_QUEUES can be called only from executive mode.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
DECW$_NOT_INITIALIZED	The common transport is not initialized.
DECW$_BADQUEUE	A queue was corrupted during initialization.

Allocation routine for protected structures.

Format

status_return=DECW$XPORT_ALLOC_PMEM size, subtype

RETURNS

VMS usage:	address
type:	longword
access:	write
mechanism:	value

Returns 0 on failure, and a nonzero address of allocated storage if successful.

Arguments

size

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

The size of the memory block to allocate, in bytes.

subtype

VMS usage:	longword
type:	longword
access:	read
mechanism:	value

User-defined subtype field used to initialize the final byte of the third longword.

Description

DECW$XPORT_ALLOC_PMEM is an allocation routine for protected structures. The sample transport calls DECW$XPORT_ALLOC_PMEM to allocate IXTCCs and XTPBs, structures that must not be modified by user-mode code.

DECW$XPORT_ALLOC_PMEM allocates a block of storage of the size that you specify. The block is assumed to begin with a 3-longword structure prefix; the length, type, and subtype fields in the third longword are initialized to appropriate values.

DECW$XPORT_ALLOC_PMEM is called only from executive mode. The allocated memory is protected as user-read/executive-write (UREW).

Reports that a transport is attached.

Format

DECW$XPORT_ATTACHED tdb

RETURNS

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

Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.

Argument

tdb

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

The XTDB of the transport that is attached.

Description

DECW$XPORT_ATTACHED builds a message vector that describes the attached transport. The only element of the vector is DECW$_ATTACHED.

The $PUTMSG system service is called in user mode regardless of the caller's mode:

• If DECW$XPORT_ATTACHED was called in user mode, it calls $PUTMSG to write the message.
• If DECW$XPORT_ATTACHED was not called in user mode, it declares a user-mode AST to do the $PUTMSG.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_INSFMEM	There is insufficient memory to perform the operation.

Reports that a network has shut down.

Format

DECW$XPORT_ATTACH_LOST tdb, status

RETURNS

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

Returns a longword condition value in R0. Condition values returned by this routine are listed under Condition Values Returned.

Arguments

tdb

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

The XTDB of the transport that shut down.

status

VMS usage:	longword
type:	longword (unsigned)
access:	read
mechanism:	value

The condition value of the transport that is shutting down.

Description

DECW$XPORT_ATTACH_LOST builds a message vector that describes the network shutdown. The first element in the message vector is DECW$_ATTACH_LOST; the second element is the status argument.

The $PUTMSG system service is called in user mode regardless of the caller's mode:

• If DECW$XPORT_ATTACH_LOST was called in user mode, it calls $PUTMSG to write the message.
• If DECW$XPORT_ATTACH_LOST was not called in user mode, it declares a user-mode AST to do the $PUTMSG.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_INSFMEM	There is insufficient memory to perform the operation.