VMS DECwindows Transport Manual
XTFT$A_EXECUTE_FREE
Returns an XTCB to a local connection.
Format
XTFT$A_EXECUTE_FREE tcc, nullarg, type, free_queue
RETURNS
|
VMS usage:
|
cond_value
|
|
type:
|
longword (unsigned)
|
|
access:
|
write
|
|
mechanism:
|
value
|
Returns a longword condition value in R0.
Arguments
tcc
|
VMS usage:
|
record
|
|
type:
|
xtcc
|
|
access:
|
modify
|
|
mechanism:
|
by reference
|
Address of the XTCC for this connection.
nullarg
|
VMS usage:
|
null_arg
|
|
type:
|
longword (unsigned)
|
|
access:
|
read
|
|
mechanism:
|
value
|
Placeholding argument reserved for historical reasons. It is never
referred to by XTFT$A_EXECUTE_FREE and its contents are unpredictable.
type
|
VMS usage:
|
longword
|
|
type:
|
longword
|
|
access:
|
read
|
|
mechanism:
|
value
|
Type of XTCB. Valid types are DECW$C_XPORT_BUFFER_LRP or
DECW$C_XPORT_BUFFER_SRP.
free_queue
|
VMS usage:
|
array
|
|
type:
|
longword
|
|
access:
|
modify
|
|
mechanism:
|
reference
|
Pointer to the free queue.
Description
The XTFT$A_EXECUTE_FREE routine logically returns an XTCB to a logical
link. The common transport DECW$XPORT_FREE_INPUT_BUFFER invokes
XTFT$A_EXECUTE_FREE after it returns an input XTCB to a previously
empty free queue.
XTFT$A_EXECUTE_FREE checks to see if input_free operations are enabled
for this connection and tries to remove the first XTCB. If it
successfully removes the XTCB, XTFT$A_EXECUTE_FREE initiates a $QIO
read into it by invoking DECW$$XPORT_FREE_INPUT (which invokes
XTFT$A_FREE_INPUT_BUFFER).
The nullarg argument is a placeholder;
XTFT$A_EXECUTE_FREE does a REMQHI to get the XTCB from the head of the
queue.
XTFT$A_EXECUTE_FREE is invoked in user mode.
See Section 8.2.6 for a sample implementation of the XTFT$A_EXECUTE_FREE
routine.
XTFT$A_EXECUTE_WRITE
Writes an XTCB to a transport-specific connection.
Format
XTFT$A_EXECUTE_WRITE xtcc, nullarg, mode
RETURNS
|
VMS usage:
|
cond_value
|
|
type:
|
longword (unsigned)
|
|
access:
|
write
|
|
mechanism:
|
value
|
Returns a longword condition value in R0.
Arguments
xtcc
|
VMS usage:
|
record
|
|
type:
|
xtcc
|
|
access:
|
modify
|
|
mechanism:
|
reference
|
Address of the XTCC for this connection.
nullarg
|
VMS usage:
|
null_arg
|
|
type:
|
longword (unsigned)
|
|
access:
|
read
|
|
mechanism:
|
value
|
Placeholding argument reserved for historical reasons.
mode
|
VMS usage:
|
longword
|
|
type:
|
longword
|
|
access:
|
read
|
|
mechanism:
|
value
|
Modifying flags for the write operation. The valid field is:
| Constant |
Description |
|
DECW$M_MODE_NOBLOCK
|
Nonblocking write. If no buffer is available when an attempt is made to
allocate one, do not block but return the status value DECW$_BUFNOTAVL.
|
Description
XTFT$A_EXECUTE_WRITE is invoked to write an XTCB to a transport
connection. XTFT$A_EXECUTE_WRITE is expected to remove the head XTCB
from the output work queue and, if the remove was successful, initiate
a write operation for the XTCB by invoking the common transport
DECW$$XPORT_WRITE routine. DECW$$XPORT_WRITE then calls XTFT$A_WRITE to
send the buffer.
The nullarg argument is a placeholder retained for
historical reasons; its value is never accessed or relied upon.
XTFT$A_EXECUTE_WRITE is invoked in user mode.
See Section 8.2.2 for a sample implementation of the
XTFT$A_EXECUTE_WRITE routine.
XTFT$A_FREE_INPUT_BUFFER
Starts a read operation on a freed input buffer.
Format
XTFT$A_FREE_INPUT_BUFFER itcc, tcb
RETURNS
|
VMS usage:
|
cond_value
|
|
type:
|
longword (unsigned)
|
|
access:
|
write
|
|
mechanism:
|
value
|
Returns a longword condition value in R0.
Arguments
itcc
|
VMS usage:
|
record
|
|
type:
|
ixtcc
|
|
access:
|
modify
|
|
mechanism:
|
by reference
|
Address of the connection where communication takes place.
tcb
|
VMS usage:
|
record
|
|
type:
|
xtcb
|
|
access:
|
modify
|
|
mechanism:
|
by reference
|
Address of the XTCB to free.
Description
The XTFT$A_FREE_INPUT_BUFFER routine does a $QIO read operation for a
connection into the provided buffer. If the read $QIO fails,
XTFT$A_FREE_INPUT_BUFFER inserts the XTCB on the free queue and sets
the connection state to dying.
The transport-common DECW$$XPORT_FREE_INPUT routine calls the
XTFT$A_FREE_INPUT_BUFFER routine to perform a $QIO read operation for
the connection.
Unlike the XTFT$A_EXECUTE_FREE routine, the xtcb
argument is a "real" XTCB and it is assumed that any
enable/disable checks, performed with the XPORT_IN_FREE_DISABLE macro,
have already been performed.
XTFT$A_FREE_INPUT_BUFFER is invoked in executive mode.
See Section 8.2.7 for a sample implementation of the
XTFT$A_FREE_INPUT_BUFFER routine.
XTFT$A_OPEN
Attempts to establish a connection to a server.
Format
XTFT$A_OPEN workstation, server, itcc
RETURNS
|
VMS usage:
|
cond_value
|
|
type:
|
longword (unsigned)
|
|
access:
|
write
|
|
mechanism:
|
value
|
Returns a longword condition value in R0.
Arguments
workstation
|
VMS usage:
|
char string
|
|
type:
|
descriptor
|
|
access:
|
read
|
|
mechanism:
|
reference
|
Name of the server object passed by descriptor. Contains network
address and authentication information. The
workstation argument is usually a node name.
server
|
VMS usage:
|
longword
|
|
type:
|
longword
|
|
access:
|
read
|
|
mechanism:
|
value
|
The number of the server to be connected. The server
argument is usually zero because most workstations run only one server.
itcc
|
VMS usage:
|
record
|
|
type:
|
ixtcc
|
|
access:
|
modify
|
|
mechanism:
|
reference
|
Location of a preallocated IXTCC. This IXTCC has an XTPB (IXTCC$A_TPB
and XTCC$A_TPB) that has been initialized.
Description
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 that passed in its
xportnam argument (for example DECNET). If a matching
transport is found, the XTFT$A_OPEN routine is called with the server
and workstation arguments and an IXTCC that has been partially
initialized.
XTFT$A_OPEN is responsible for allocating and initializing the XTCC and
all necessary XTCBs, populating the XTCQ with the XTCBs, and initiating
I/O on the connection. 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 is invoked in executive mode.
Waiting for Asynchronous Connections
Connections are usually established in inner mode. However, if your
specific transport indicates (by an explicit return status of
DECW$_STALL) 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
Ctrl/Y to exit the application in the event of a problem.
You can write your transport-specific XTFT$A_OPEN routine to wait
either in executive mode (by a $QIOW call) or in user mode (by an
asynchronous $QIO call) and use the return status of DECW$STALL to tell
the DECW$XPORT_OPEN routine which way to proceed. Note that waiting in
executive mode is discouraged.
If a transport-specific XTFT$A_OPEN return returns a status of
DECW$_STALL, it must then call DECW$XPORT_OPEN_COMPLETE when it has
completed the open to notify DECW$XPORT_OPEN that an asynchronous open
operation has completed.
See Section 8.2.12 for a sample implementation of the XTFT$A_OPEN
routine.
XTFT$A_RUNDOWN
Performs the transport-specific rundown functions required during image
rundown.
Format
XTFT$A_RUNDOWN 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. The XTDB is initialized by the common transport before
XTFT$A_RUNDOWN is called.
Description
XTFT$A_RUNDOWN is invoked by the common transport when the image in
which the transport is running exits. The transport's rundown procedure
must release any resources that might survive the image exit. ASTs are
disabled while XTFT$A_RUNDOWN is executing.
XTFT$A_RUNDOWN is invoked in executive mode.
See Section 8.2.22 for a sample implementation of the XTFT$A_RUNDOWN
routine.
XTFT$A_WRITE
Writes an XTCB buffer from the common transport to a transport-specific
connection.
Format
XTFT$A_WRITE itcc, tcb, mode
RETURNS
|
VMS usage:
|
cond_value
|
|
type:
|
longword (unsigned)
|
|
access:
|
write
|
|
mechanism:
|
value
|
Returns a longword condition value in R0.
Arguments
itcc
|
VMS usage:
|
record
|
|
type:
|
xtcc
|
|
access:
|
modify
|
|
mechanism:
|
reference
|
Address of the IXTCC for this connection.
tcb
|
VMS usage:
|
record
|
|
type:
|
xtcb
|
|
access:
|
modify
|
|
mechanism:
|
reference
|
Address of the XTCB to write to the transport-specific connection.
mode
|
VMS usage:
|
longword
|
|
type:
|
longword
|
|
access:
|
read
|
|
mechanism:
|
value
|
Modifying flags for the write operation. The valid field is as follows:
| Constant |
Description |
|
DECW$M_MODE_NOBLOCK
|
Nonblocking write. If no buffer is available when an attempt is made to
allocate one, do not block but return the status value DECW$_BUFNOTAVL.
|
Description
The XTFT$A_WRITE routine is invoked to write the data in an XTCB,
possibly by means of $QIO, to a transport connection associated with
the XTCC. If there is nothing to write, that is, the XTCB is empty,
XTFT$A_WRITE inserts the XTCB on the appropriate (small or large)
output free queue.
If the $QIO write operation fails, XTFT$A_WRITE puts the XTCB back at
the head of the output work queue and sets the connection status to
dying.
Unlike XTFT$A_EXECUTE_WRITE, the XTCB parameter in the argument list is
significant and is the address of an XTCB, not an element of any queue,
whose data is to be written to a connection.
The XTFT$A_WRITE routine is called in executive mode.
See Section 8.2.3 for a sample implementation of the XTFT$A_WRITE
routine.
XTFT$A_WRITE_USER
Attempts to write a buffer in the user's address space to a
transport-specific connection.
Format
XTFT$A_WRITE_USER itcc, buffer, mode
RETURNS
|
VMS usage:
|
cond_value
|
|
type:
|
longword (unsigned)
|
|
access:
|
write
|
|
mechanism:
|
value
|
Returns a longword condition value in R0.
Arguments
itcc
|
VMS usage:
|
record
|
|
type:
|
ixtcc
|
|
access:
|
modify
|
|
mechanism:
|
reference
|
Address of the IXTCC data structure that identifies the connection.
buffer
|
VMS usage:
|
char string
|
|
type:
|
char string
|
|
access:
|
read
|
|
mechanism:
|
descriptor
|
A buffer in the user's address space that contains data to write to the
connection.
mode
|
VMS usage:
|
longword
|
|
type:
|
longword
|
|
access:
|
read
|
|
mechanism:
|
value
|
Modifying flags for the write operation. The valid field is as follows:
| Constant |
Description |
|
DECW$M_MODE_NOBLOCK
|
Nonblocking write. If no buffer is available when an attempt is made to
allocate one, do not block but return the status value DECW$_BUFNOTAVL.
|
Description
The XTFT$A_WRITE_USER routine attempts to write a buffer in the user's
address space to a transport connection. The purpose of this interface
is to avoid a data copy into XTCBs when the caller has a large,
contiguous block of data to be written to a connection, such as when
sending image data between client and server.
There are two methods for implementing this routine. The first is to
wait for the output work queue to become empty and then perform the I/O
operation on the user's buffer, typically by means of a $QIO. The other
method is to invoke the common transport's DECW$XPORT_COPY_AND_WRITE
routine for the buffer arguments. It is strongly recommended
that transports use the DECW$XPORT_COPY_AND_WRITE routine.
XTFT$A_WRITE_USER is called in user mode.
See Section 8.2.5 for a sample implementation of the XTFT$A_WRITE_USER
routine.
|
