HP OpenVMS Systems Documentation

Terminates a connection and releases its associated resources.

Format

DECW$XPORT_CLOSE tcc

Arguments

tcc

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

The XTCC of the connection to close.

Description

DECW$XPORT_CLOSE terminates a connection and releases its associated resources. The transport user is expected to return any XTCBs acquired through DECW$XPORT_READ and DECW$XPORT_GET_OUTPUT_BUFFER before calling DECW$XPORT_CLOSE. After calling DECW$XPORT_CLOSE, the structures used by the connection (XTCC, XTCQ, and XTCBs) must not be referenced.

The DECW$XPORT_CLOSE routine calls the transport-specific connection close routine, XTFT$A_CLOSE, to actually break the network link.

Copies data into XTCBs and optionally starts a write operation.

Format

DECW$XPORT_COPY_AND_WRITE tcc, mode, buffer, buflen, retbuflen, padbytes

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

tcc

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

The XTCC of the connection from which you want to write.

mode

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

Modifying flags for the write operation. The following are valid fields:

Constant	Description
DECW$M_MODE_NOBLOCK	Nonblocking write. When the DECW$M_MODE_NOBLOCK flag is set, any attempt to get a transport buffer when none is available causes the call to return the status DECW$_BUFNOTAVL and perform only a partial write operation. When this bit is clear and a nonzero timeout value was specified in DECW$XPORT_ATTACH_TRANSPORT, getting a buffer can time out, causing this routine to return with the DECW$_BUFFERTIMEOUT status.
DECW$M_MODE_NOWRTBLOCK	If the specific transport was blocked for the XTCB write operation, the last XTCB is placed on the work queue and DECW$XPORT_COPY_AND_WRITE returns with a DECW$_BLOCKED status.

buffer

VMS usage:	char string
type:	char string
access:	read
mechanism:	reference

A buffer in the user's address space that contains data to write to the connection.

buflen

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

The length of the data in the buffer.

retbuflen

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

Address of longword to receive the amount of data that was actually written to the connection. If DECW$M_MODE_NOBLOCK was not set in the mode argument, and there is no timeout, retbuflen is always the amount requested.

padbytes

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

Number of pad bytes (zeros) to append to the copy.

Description

DECW$XPORT_COPY_AND_WRITE performs a buffered write operation and returns the size of the data actually copied in the retbuflen argument. Data from the user's buffer is always copied to transport buffers prior to processing by the transport-specific write function.

The sample transport calls DECW$XPORT_COPY_AND_WRITE from the XTFT$A_WRITE_USER routine.

DECW$XPORT_COPY_AND_WRITE must be called in user mode.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_ACCVIO	XTCC is not user-readable.
SS$_BADPARAM	XTCC argument is not an XTCC.
DECW$_CNXABORT	Connection is in abort condition.
DECW$_RECIO_OPE	Recursive I/O operation.
DECW$_BLOCKED	The transport blocked the write operation.
DECW$_BUFFERTIMEOUT	Timed out while waiting for buffer.
DECW$_NOT_INITIALIZED	The common transport is not initialized.
DECW$_INV_STRUCT_ID	The XTCC$L_ICI field is not valid.

Can also return any other status set in the XTCC$L_ERR_STATUS field if the connection is aborting.

Deallocation routine for protected structures allocated with DECW$XPORT_ALLOC_PMEM.

Format

DECW$XPORT_DEALLOC_PMEM buffer

Arguments

buffer

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

The address of the buffer to deallocate.

Description

DECW$XPORT_DEALLOC_PMEM deallocates a structure that was previously allocated by DECW$XPORT_ALLOC_PMEM. Any errors are signaled. DECW$XPORT_DEALLOC_PMEM does not return a condition value.

DECW$XPORT_DEALLOC_PMEM must be called in executive mode.

Deallocates a block of storage previously allocated by DECW$XPORT_ALLOC_INIT_QUEUES.

Format

DECW$XPORT_DEALLOC_QUEUES itcc

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 deallocate a block of storage previously allocated for the queues.

Description

DECW$XPORT_DEALLOC_QUEUES deallocates a block of storage that was previously allocated for the queues of a connection by DECW$XPORT_ALLOC_INIT_QUEUES.

DECW$XPORT_DEALLOC_QUEUES must be called in executive mode.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
DECW$_NOT_INITIALIZED	The common transport is not initialized.

Outputs messages for debugging purposes.

Format

DECW$XPORT_FAO ctrstr, [P1...Pn]

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

ctrstr

VMS usage:	char string
type:	character-coded text string
access:	read
mechanism:	descriptor-fixed-length string descriptor

Address of a string descriptor. This will be used as the control string argument to $FAO.

P1 to Pn

VMS usage:	varying_arg
type:	longword (signed)
access:	read
mechanism:	value

$FAO can take a variable number of optional arguments, numbered P1 to P20. See the description of $FAO in the OpenVMS System Services Reference Manual for additional information.

Description

DECW$XPORT_FAO outputs messages for debugging purposes. DECW$XPORT_FAO formats the message string using the VMS system services $FAO and then outputs it.

For example, a specific transport can include calls to DECW$XPORT_FAO at crucial points in the connection-open process to make sure that the connection is proceeding correctly. (See Section 8.2.12 for an example from the sample transport.)

If DECW$XPORT_FAO is called in user mode, it formats the message and sends it to SYS$OUTPUT. If DECW$XPORT_FAO is called in executive mode, it queues a user-mode AST to deliver the message to SYS$OUTPUT.

DECW$XPORT_FAO can be called from user mode or executive mode.

Condition Values Returned

SS$_INSFMEM

There is insufficient memory to perform the operation.

Initiates a read operation on the connection.

Format

DECW$$XPORT_FREE_INPUT tcc, tcb

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

tcc

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

The XTCC of the connection from which you want to read.

tcb

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

DECW$$XPORT_FREE_INPUT initiates a read operation for the connection into this XTCB.

Description

The DECW$$XPORT_FREE_INPUT system service calls the XTFT$A_FREE_INPUT_BUFFER routine in executive mode to perform an asynchronous read operation for the connection. The read operation is performed asynchronously to avoid waiting for it to complete.

The XTFT$A_FREE_INPUT_BUFFER routine does the actual read operation for the connection into the XTCB specified in the tcb argument. If the read operation fails, XTFT$A_FREE_INPUT_BUFFER inserts the XTCB on the free queue and sets the connection state to dying.

DECW$$XPORT_FREE_INPUT is an executive-mode routine.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
DECW$_CNXABORT	Connection is in abort condition.

Notifies Xlib or the server that data on the input work queue is available to be read.

Format

DECW$XPORT_IN_NOTIFY_USER tcc

Argument

tcc

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

The XTCC of the connection for which you want to limit input-notify AST delivery.

Description

DECW$XPORT_IN_NOTIFY_USER clears the XTCC$V_IN_AST_IN_PROG bit in the XTCC to indicate that the AST has been delivered, and calls the input notification procedure, identified by the XTPB$A_I_NOTIFY_RTNADR field.

Transport users can request notification of input data. One method of notifying transport users is to deliver an AST that calls the user's XTPB$A_I_NOTIFY_RTNADR procedure with the XTCC as an argument.

It is possible for a large number of read operations to complete before the first notification AST is delivered, particularly if an Xlib application is executing at user-AST level for a long period of time, or not reading events.

If ASTs were declared without regard for whether they were being delivered, it is possible to exceed the process AST quota. DECW$XPORT_IN_NOTIFY_USER and the XPORT_IN_NOTIFY_SEND macro provide a mechanism for limiting AST use.

The XPORT_IN_NOTIFY_SEND macro tests and sets the XTCC$V_IN_AST_IN_PROG bit. If it was set, there is already a notification AST waiting to be delivered. If the XTCC$V_IN_AST_IN_PROG bit was clear, XPORT_IN_NOTIFY_SEND declares a user-mode AST to call DECW$XPORT_IN_NOTIFY_USER.

DECW$XPORT_IN_NOTIFY_USER clears the XTCC$V_IN_AST_IN_PROG bit and then calls the user's XTPB$A_I_NOTIFY_RTNADR procedure.

DECW$XPORT_IN_NOTIFY_USER is called in user mode.

Completes an asynchronous open connection operation.

Format

DECW$$XPORT_OPEN_COMPLETE ixtcc, status

Arguments

ixtcc

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

IXTCC of the connection whose open operation is done.

status

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

The condition value of the open operation. Can be SS$_NORMAL, an error, or a fatal condition code.

Description

Connections are usually established in inner mode. However, your specific transport can indicate (by an explicit return status of DECW$_STALL) that it is necessary to wait for a connection to be established across a network.

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.

DECW$$XPORT_OPEN_COMPLETE functions as follows:

• Checks the status argument. If an error occurred, either while allocating memory, initializing the attributes, or opening the connection, it deallocates any allocated memory resources.
• Initializes the XTCC and XTDB, and finishes the initialization of the XTCC flags.
• Sets an IOSB and event flag to notify DECW$XPORT_OPEN that the asynchronous open has completed.

DECW$$XPORT_OPEN_COMPLETE is called in executive mode.

Read completion AST routine. Checks status of completed I/O and, if a problem occurred, sets the connection state accordingly.

Format

DECW$XPORT_READ_COMPLETE itcc, full_tcb, read_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

itcc

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

The address of the IXTCC for this connection.

full_tcb

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

Address of the XTCB that was the target of the just-completed input operation. XTCB$L_LENGTH has been set to the number of bytes read during the input operation.

read_status

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

Condition code for the just-completed input operation.

Description

DECW$XPORT_READ_COMPLETE is a transport-common AST read-completion routine. DECW$XPORT_READ_COMPLETE is called only by specific transports to check the status of completed I/O and, if a problem occurred, set the connection state accordingly. If successful, it updates the buffer and connection state and attempts to get another free buffer for reading.

DECW$XPORT_READ_COMPLETE functions as follows:

1. Checks to see if the connection is still valid.
   DECW$XPORT_READ_COMPLETE checks if this connection is aborting or the I/O failed and, if so, performs failure processing. If DECW$XPORT_READ_COMPLETE is the first to set the dying bit, it must also perform abort notification. Abort notification consists of conditionally declaring a user-mode AST for the link abort (by means of XPORT_ABORT_SEND) and sending notification that a read operation has completed to satisfy any input wait condition.
2. Checks the read status.
3. Gets the length and subtype (DECW$C_DYN_XTCB_SRP or DECW$C_DYN_XTCB_LRP) of the XTCB.
4. Inserts the buffer on the tail of the input work queue and makes some decisions about whether to use small or large XTCBs for the next read. If the $QIO read operation that just completed filled a small request packet, DECW$XPORT_READ_COMPLETE uses the large request packet. If large XTCBs were being used and the last read operation would have fit in a small XTCB, DECW$XPORT_READ_COMPLETE shifts down to the small XTCBs.
5. Gets a buffer from the free queue.
   If no buffers are available and the .xtcc [XTCC$V_MODE] field indicates that this is a client, calls the common-transport buffer compacting routine to try to compact the queue to get a buffer.
6. If it got a buffer, calls the transport-specific XTFT$A_FREE_INPUT_BUFFER routine to do a read into it. Drops to user mode and calls XPORT_IN_NOTIFY_SEND to notify the transport user that some input activity has happened.
7. If there were no buffers available, drops to user mode and calls XPORT_IN_FREE_ENABLE to be informed when a buffer becomes available, calls XPORT_IN_NOTIFY_SEND to notify the transport user that some input activity has happened, and returns a status of SS$_NOMOREITEMS.

DECW$XPORT_READ_COMPLETE is called in executive mode.

In the sample transport (see Section 8.2.8), DECW$XPORT_READ_COMPLETE is called from inside FREE_INPUT_AST, the AST completion routine for transport read operations.

Condition Values Returned

SS$_NORMAL	Routine successfully completed.
SS$_NOMOREITEMS	No free input buffers are available.