HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming

The IO$_DEACCESS function closes a connection and deletes a socket. Any pending messages queued for transmission are sent before tearing down the connection.

When used with the IO$M_SHUTDOWN function modifier, the IO$_DEACCESS function shuts down all or part of a bidirectional connection on a socket. Use the p4 argument to specify the disposition of pending I/O operations on the socket.

You can specify a wait time or time-to-linger socket parameter (TCPIP$C_LINGER option) for transmission completion before disconnecting the connection. Use the IO$_SETMODE function to set and clear the TCPIP$C_LINGER option.

If you set the TCPIP$C_LINGER option, a $QIO call that uses the IO$_DEACCESS function allows data queued to the socket to arrive at the destination. The system is blocked until data arrives at the remote socket. The socket data structure remains open for the duration of the TCP idle time interval.

If you do not set the TCPIP$C_LINGER option (option is set to 0), a $QIO call that uses the IO$_DEACCESS function discards any data queued to the socket and deallocates the socket data structure.

Note For compatibility with UNIX, TCP/IP Services forces a time to linger of 2 minutes on TCP stream sockets.

Related Functions

The equivalent Sockets API functions are close() and shutdown() .

Arguments

p4

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Longword of shutdown flags to specify the disposition of pending I/O operations on the socket. The p4 argument is used only with the IO$M_SHUTDOWN function modifier. The following table lists available shutdown flags.

Shutdown Flag	Description
TCPIP$C_DSC_RCV	Discards messages from the receive queue and disallows further receiving. Pending messages in the receive queue for this connection are discarded.
TCPIP$C_DSC_SND	Discards messages from the send queue and disallows sending new messages. Pending messages in the transmit queue for this connection are discarded.
TCPIP$C_DSC_ALL	Discards all messages and disallows both sending and receiving. All pending messages are discarded. Specifying this flag has the same effect as issuing a $CANCEL QIO followed by an IO$_DEACCESS QIO without specifying any flags.

Function Modifiers

IO$M_SHUTDOWN	Causes all or part of a full-duplex connection on a socket to be shut down.
IO$M_NOW	Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	The IO$_DEACCESS operation failed to specify a socket.
SS$_CANCEL	The I/O operation was canceled by a $CANCEL system service.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded, but the INETACP is not currently available for use.
SS$_NOLINKS	The specified socket was not connected.
SS$_SHUT	The local or remote node is no longer accepting connections.
SS$_SUSPENDED	The system detected a condition that might cause the operation to block.

The IO$_READVBLK function transfers data received from an internet host to the specified user buffers. Use both p1 and p2 arguments to specify a single user buffer. Use the p6 argument to specify multiple buffers.

For connection-oriented protocols, such as TCP, data is buffered in system space as a stream of bytes. The IO$_READVBLK function completes when one of the following occurs:

• There is no more data buffered in system space for this socket.
• There is no more available space in the user buffer. Data that is buffered in system space but did not fit in the user buffer is available to the user in subsequent $QIOs.

For connectionless protocols, datagram and raw socket data is buffered in system space as a chain of records. The user buffer specified with a IO$_READVBLK function is filled with data that is buffered in one record. Each IO$_READVBLK reads data from one record. The IO$_READVBLK function completes when one of the following occurs:

• All data from a record is transferred to the user buffer.
• There is no more available space in the user buffer. Any data remaining in the current record that did not fit in the user buffer is discarded. A subsequent $QIO reads data from the next record buffered in system space.

Use the TCP/IP management command SHOW DEVICE_SOCKET/FULL to display counters related to read operations.

Related Functions

The equivalent Sockets API functions are read() , recv() , recvfrom() , and recvmsg() .

Arguments

p1

OpenVMS usage:	buffer
type:	vector byte (unsigned)
access:	read only
mechanism:	(Alpha and I64) by 32- or 64-bit reference
	(VAX) by 32-bit reference

The address of the buffer to receive the incoming data. The length of this buffer is specified by the p2 argument.

p2

OpenVMS usage:	buffer_length
type:
access:	quadword unsigned (Alpha and I64); longword unsigned (VAX)
mechanism:	read only
	(Alpha and I64) by 64-bit value

The length (in bytes) of the buffer available to hold the incoming data. The address of this buffer is specified by the p1 argument.

p3

OpenVMS usage:	socket_name
type:	vector byte (unsigned)
access:	read only
mechanism:	by item_list_3 descriptor

The remote port number and IP address of the source of the datagram or raw IP message (not TCP). The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the remote port number and IP address of the message source is written.

p4

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

Longword of flags to specify attributes for the read operations. Table 6-5 lists the available read flags.

Table 6-5 Read Flags

Read Flag	Description
TCPIP$C_MSG_OOB	Reads an out-of-band byte.
TCPIP$C_MSG_PEEK	Reads a message but leaves the message in the queue.
TCPIP$C_MSG_NBIO	Does not block the I/O operation if the receive queue is empty (similar to using IO$M_NOWAIT).
TCPIP$C_MSG_PURGE	Flushes data from the queue (similar to using IO$M_PURGE).
TCPIP$C_MSG_BLOCKALL	Blocks the completion of the operation until the buffer is filled completely or until the connection is closed (similar to using IO$M_LOCKBUF).

p6

OpenVMS usage:	buffer_list
type:	vector byte (unsigned)
access:	read only
mechanism:	(Alpha and I64) by 32- or 64-bit descriptor-fixed-length descriptor
	(VAX) by 32-bit descriptor-fixed-length descriptor

Output buffer list describing one or more buffers to hold the incoming data. The p6 argument is the 32- or 64-bit address (on Alpha and I64 systems) or the 32-bit address (on VAX systems) of a descriptor that points to a output buffer list. Buffers are filled in the order specified by the output buffer list. The transfer-length value returned in the I/O status block is the total number of bytes transferred to all buffers.

If you use the p1 and p2 arguments, do not use the p6 argument; they are mutually exclusive.

Function Modifiers

IO$M_EXTEND	Specifies the format of the socket address structure to return when used with the p3 argument. When specified, a BSD Version 4.4 formatted socket address structure is returned that identifies the source of the received UDP datagram or raw IP message. To operate in an IPv6 environment, you must set the IO$M_EXTEND modifier.
IO$M_INTERRUPT	Reads an out-of-band (OOB) message. This has the same effect as specifying the TCPIP$C_MSG_OOB flag in the p4 argument. On receiving an OOB character, TCP/IP stores the pointer in the received stream with the character that precedes the OOB character. A read operation with a user-buffer size larger than the size of the received stream up to the OOB character completes and returns to the user the received stream up to, but not including, the OOB character. To determine whether the socket must issue more read $QIOs before getting all the characters from the stream preceding an OOB character, poll the socket. To do this, issue a $QIO with the $IO_SENSEMODE function, and the TCPIP$C_IOCTL subfunction that specifies the SIOCATMARK command. The SIOCATMARK values are as follows: 0 = Issue more read $QIOs to read more data before reading the OOB. 1 = The next read $QIO will return the OOB character. Polling a socket is particularly useful when the OOBINLINE socket option is set. When the OOBINLINE is set, TCP/IP reads the OOB character with the characters in the stream (IO$_READVBLK), but not before reading the preceding characters. Use this polling mechanism to determine whether the first character in the user buffer on the next read is an OOB character. On a socket without the OOBINLINE option set, a received OOB character will always be read by issuing a $QIO with either the IO$_READVBLK|IO$M_INTERRUPT or IO$_READVBLK and the TCPIP$C_MSG_OOB flag set. This can occur regardless of how many preceding characters in the stream have been returned to the user.
IO$M_LOCKBUF	Blocks the completion of the I/O operation until the user buffer is completely filled or until the connection is closed. This is particularly useful when you want to minimize the number of $QIO service calls issued to read a data stream of a set size. This function modifier supports only stream protocols.
IO$M_NOWAIT	Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code.
IO$M_PURGE	Flushes data from the socket receive queue (discards data). If the user buffer is larger than the amount of data in the queue, all data is flushed.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ABORT	Programming error, INET management error, or hardware error. The execution of the I/O was aborted.
SS$_ACCVIO	Access to an invalid memory location or buffer occurred.
SS$_BADPARAM	One of the following methods was used to specify a $QIO function with an invalid parameter: An I/O function executed without specifying a device socket. First issue a $QIO with the IO$_SETMODE function and the proper parameters to create the device socket. An IO$_READVBLK function that does not specify a correct buffer address ( p1 or p6 is null). An IO$_READVBLK function specified an invalid vectored buffer ( p6 is an invalid descriptor). The socket has the OOBINLINE option set, or there is no OOB character in the socket's OOB queue because the character was either already read or never received. This condition happens only if you use the IO$M_INTERRUPT modifier or set the TCPIP$C_MSG_OOB flag with IO$_READVBLK.
SS$_CANCEL	The I/O operation was canceled by a $CANCEL system service.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded, but the INETACP is not currently available for use.
SS$_INSFMEM	INET management or programming error. There is not enough buffer space for allocation. The INET software needs more buffer space. You should set a higher quota for the dynamic buffer space, or shut down and restart TCP/IP Services with a larger static buffer space.
SS$_IVBUFLEN	Programming error occurred for one of the following reasons: The size of the buffer for an I/O function is insufficient. An IO$_READVBLK specified a correct buffer address ( p1 valid), but does not specify a buffer length ( p2 is null).
SS$_LINKDISCON	A virtual circuit (TCP/IP) was closed at the initiative of the peer.
SS$_NOLINKS	Programming error. Read attempt on unconnected TCP socket.
SS$_SHUT	The network is being shut down.
SS$_SUSPENDED	The operation is blocked for one of the following reasons: No messages were received, so the receive operation cannot complete. The socket is marked as nonblocking. The socket has the OOBINLINE option clear, and the OOB character has already been read.
SS$_TIMEOUT	This applies to a socket that has KEEPALIVE set. The connection was idle for longer than the timeout interval (10 minutes is the default). For more information, see Table A-2.
SS$_UNREACHABLE	Communication status. The remote host or network is unreachable.

The IO$_SENSEMODE and IO$_SENSECHAR functions return one or more parameters (characteristics) pertaining to the network driver.

Socket names (local and remote peer) are returned by using IO$_SENSEMODE's p3 and p4 arguments. Other parameters such as socket and protocol options, are specified in an output parameter list using the IO$_SENSEMODE p6 argument.

IO$_SENSEMODE p3 and p4 arguments can be used with the p6 argument in a single $QIO system service to return socket names as well as socket and protocol options. IO$_SENSEMODE processes arguments in this order: p3, p4, p6. If IO$_SENSEMODE detects an error, the I/O status block (IOSB) contains the error and argument address or the value that was at fault.

Refer to individual argument descriptions for details about specifying the type and format of output parameters.

Arguments

p3

OpenVMS usage:	socket_name
type:	vector byte (unsigned)
access:	read only
mechanism:	by item_list_3 descriptor

The port number and IP address of the local name associated with the socket. The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the local name is written.

The equivalent Sockets API function is getsockname() .

p4

OpenVMS usage:	socket_name
type:	vector byte (unsigned)
access:	read only
mechanism:	by item_list_3 descriptor

The port number and IP address of the remote name associated with the socket's peer. The p4 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the peer name is written.

The equivalent Sockets API function is getpeername() .

p6

OpenVMS usage:	output_parameter_list
type:	vector byte (unsigned)
access:	read only
mechanism:	by item_list_2 descriptor

Output parameter list describing one or more parameters to return. The p6 argument is the address of an item_list_2 descriptor that points to and identifies the type of output parameter list.

The equivalent Sockets API functions are getsockopt() and ioctl() .

Function Modifiers

IO$M_EXTEND

Specifies the format of the socket address structure to return when used with the p3 or p4 arguments. When specified, a BSD Version 4.4 formatted socket address structure is returned. Specify the IO$M_EXTEND modifier to operate in an IPv6 environment.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access a buffer specified by one or more arguments.
SS$_BADPARAM	Programming error occurred for one of the following reasons: $QIO system service was specified without a socket. Error occurred processing a socket or protocol option.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded, but the INETACP is not currently available for use.
SS$_ILLCNTRFUNC	Programming error. The operation is unsupported for one of the following reasons: An invalid IO$_SENSEMODE function for the interface was specified. The interface does not have an IOCTL routine. An IO$_SENSEMODE function that requires a socket was specified, but the device did not have one. Create a socket and then issue the function. An unsupported operation was performed on at least one of the following protocols: raw IP, datagram, or stream sockets.
SS$_INSFMEM	Insufficient system dynamic memory to complete the service.
SS$_IVBUFLEN	The size of a socket option buffer specified with the IO$_SENSEMODE function was invalid.
SS$_NOSUCHDEV	Programming error or INET management error. An INET address is not in the Address Resolution Protocol (ARP) table. An attempt to show or delete an ARP table entry failed.
SS$_NOLINKS	The specified socket was not connected.
SS$_NOOPER	Programming error. An attempt to get ARP information occurred without OPER privilege.
SS$_PROTOCOL	A network protocol error occurred. The address family specified in the socket address structure is not supported.
SS$_SHUT	The local or remote node is no longer accepting connections.
SS$_UNREACHABLE	The remote node is currently unreachable.