HP OpenVMS Systems Documentation
Content starts here

VMS DECwindows Transport Manual
Previous Contents Index

Chapter 4
Transport Walk-Through

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.

Note
The boxed numbers in the illustrations correspond to the buffers, or XTCBs, that are being queued.

The convention for TCP/IP is that server number 0 listens on port 6000.

Chapter 5
Transport-Common Routines

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.

Table 5-1 Transport-Common Routines
Routine Name Function
DECW$XPORT_ACCEPT_FAILED Reports that the transport-specific routines could not accept a network link request.
DECW$XPORT_ALLOC_INIT_QUEUES Allocates storage for an XTCC, XTCQ, and all of the XTCBs for a connection. Places all of the XTCBs on the appropriate free queues.
DECW$XPORT_ALLOC_PMEM Allocation routine for protected structures.
DECW$XPORT_ATTACHED Reports that a transport is attached.
DECW$XPORT_ATTACH_LOST Reports that a network has shut down.
DECW$XPORT_CLOSE Terminates a connection and releases its associated resources.
DECW$XPORT_COPY_AND_WRITE Copies data into XTCBs and optionally starts a write operation.
DECW$XPORT_DEALLOC_PMEM Deallocation routine for protected structures allocated with DECW$XPORT_ALLOC_PMEM.
DECW$XPORT_DEALLOC_QUEUES Deallocates a block of storage previously allocated by DECW$XPORT_ALLOC_INIT_QUEUES.
DECW$XPORT_FAO Outputs messages for debugging purposes.
DECW$$XPORT_FREE_INPUT Initiates a read operation for a connection.
DECW$XPORT_IN_NOTIFY_USER Notifies Xlib or the server that data on the input work queue is available to be read.
DECW$$XPORT_OPEN_COMPLETE Completes an asynchronous connection open operation.
DECW$XPORT_READ_COMPLETE Read completion AST routine.
DECW$XPORT_REATTACH_FAILED Reports that the transport layer cannot continue attempting to reattach.
DECW$XPORT_REFUSED_BY_SERVER Reports that the server did not accept a connection.
DECW$XPORT_UNEXPECTED_MESSAG Reports that an unexpected message was received from the underlying transport.
DECW$XPORT_UNKNOWN_LINK Reports a message from an unknown connection.
DECW$XPORT_VALIDATE_STRUCT Returns the address of the user write-protected IXTCC structure.
DECW$XPORT_VALIDATE_STRUCT_JSB JSB routine that returns the address of the user write-protected IXTCC structure.
DECW$XPORT_VALIDATE_XTCB Validates that an XTCB is contained within the allocated storage for the connection and that it is correctly formed.
DECW$XPORT_VALIDATE_XTCB_JSB JSB routine that validates that an XTCB is contained within the allocated storage for the connection and that it is correctly formed.
DECW$$XPORT_WRITE Initiates a writing operation on the connection.

DECW$XPORT_ACCEPT_FAILED

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.
Any condition value returned by $PUTMSG. Any condition value returned by $DCLAST.

DECW$XPORT_ALLOC_INIT_QUEUES

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.

DECW$XPORT_ALLOC_PMEM

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).

DECW$XPORT_ATTACHED

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.
Any condition value returned by $PUTMSG. Any condition value returned by $DCLAST.

DECW$XPORT_ATTACH_LOST

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.
Any condition value returned by $PUTMSG. Any condition value returned by $DCLAST.

Previous Next Contents Index