HP OpenVMS systems documentation

The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_WRTATTN is Enable Write Attention AST) requests that an Attention AST be delivered to the requesting process when a data packet can be queued to the socket. For TCP sockets, this occurs when space becomes available in the TCP transmit queue.

The Enable Write Attention AST function enables an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before the AST can occur again. The function is subject to AST quotas.

There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For example, for each enabled AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when the event occurs.

You can use the TCP/IP management command SHOW DEVICE_SOCKET to display information about the socket's characteristics, options, and state.

Arguments

p1

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

To enable the AST, the p1 argument is the address of the Write Attention AST routine. To disable the AST, p1 is set to 0.

p2

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

AST parameter to be delivered to the AST routine.

p3

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

Access mode in which the AST is delivered.

Condition Values Returned

SS$_ABORT	Programming error, INET management error, or hardware error. The route specified with the IO$_SETMODE function already exists. Therefore, the operation failed.
SS$_ACCVIO	Programming error. An attempt to access an invalid memory location or buffer occurred.
SS$_BADPARAM	Programming error. The parameter specified for the $QIO I/O function was invalid for one of the following reasons: An attempt was made to execute the IO$_SETMODE functions without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. A socket option was specified incorrectly.
SS$_DEVACTIVE	INET management error. You attempted to change the static parameters. If you need new parameters, restart TCP/IP Services.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded but the INET_ACP is not currently available for use.
SS$_DUPLNAM	Programming error. Port that is being bound is already in use. An attempt to bind the socket to an address and port failed.
SS$_FILALRACC	Programming error. Because the IP address is already in use, an attempt to bind the socket to an address and port failed.
SS$_INSFMEM	Programming or system management error. There are not enough resources to allocate a new socket.
SS$_ILLCNTRFUNC	Programming error. An attempt was made to execute an IO$_SETMODE function that required a socket, but the device did not have one. Instead, create a socket and issue the function.
SS$_IVADDR	Programming error. An invalid port number and IP address combination was specified with the IO$_SETMODE bind function. This caused the operation to fail for one of the following reasons: An illegal combination of Port 0 and IP address 0 was specified. An attempt was made to make a permanent entry in the ARP table and the operation failed because of lack of space. There are too many permanent entries. An attempt was made to bind a raw IP socket when there were no interfaces defined in the system. An attempt was made to bind a raw IP socket to a null IP address.
SS$_IVBUFLEN	Programming error. An invalid size was specified for the socket option buffer.
SS$_NOLICENSE	Programming or system management error. The TCP/IP Services license is not present.
SS$_NOOPER	Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege.
SS$_NOPRIV	Programming or INET management error. The operation failed for one of the following reasons: An attempt was made to broadcast an IP datagram for a process without having SYSPRV, BYPASS, or OPER privilege. An attempt was made to use a reserved port number lower than 1024. An attempt was made to access a process without having SYSPRV or BYPASS privilege. An attempt was made to use raw IP on a socket that is not a privileged socket. To do this, the process must have SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV	Programming error or INET management error. An attempt was made to show or delete an entry in the ARP table. However, because the IP address was not in the ARP table, the operation failed.
SS$_NOSUCHNODE	Programming error or INET management error. An attempt was made to delete a route from the routing information table (RIT). However, because the route was not found in the RIT, the operation failed.
SS$_PROTOCOL	Programming error. The specified protocol is not supported.
SS$_SHUT	The local or remote node is no longer accepting connections.

The IO$_WRITEVBLK function transmits data from the specified user buffers to an Internet host. Use both p1 and p2 arguments to specify a single user buffer. Use the p5 argument to specify multiple buffers.

For connection-oriented protocols, such as TCP, if the socket transmit buffer is full, the IO$_WRITEVBLK function is blocked until the socket transmit buffer has room for the user data.

For connectionless-oriented protocols, such as UDP and raw IP, the user data is transmitted in one datagram. If the user data is greater than the socket's transmit quota, the error code (SS$_TOOMUCHDATA) is returned.

Related Functions

The equivalent Sockets API functions are send() , sendto() , sendmsg() , and write() .

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 containing the data to be transmitted. The length of this buffer is specified by the p2 argument.

p2

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

The length (in bytes) of the buffer containing data to be transmitted. 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_2 descriptor

The remote port number and IP address of the message destination. The p3 argument is the address of an item_list_2 descriptor pointing to the socket address structure containing the remote port number and IP address.

p4

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

Longword of flags to specify attributes for this write operation. The following table lists the available write flags:

Write Flag	Description
TCPIP$C_MSG_OOB	Writes an out-of-band (OOB) byte.
TCPIP$C_MSG_DONTROUTE	Sends message directly without routing.
TCPIP$C_MSG_NBIO	Completes the I/O operation and returns an error if a condition arises that would cause the I/O operation to be blocked. (Similar to using IO$M_NOWAIT.)

p5

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

Input buffer list describing one or more buffers containing the data to be transmitted. The p5 argument is the address of a descriptor pointing to a input buffer list. Buffers are transmitted in the order specified by the input buffer list. The transfer-length value returned in the I/O status block is the total number of bytes transferred from all buffers.

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

Function Modifiers

IO$M_EXTEND	Allows the use of extended modifiers with BSD Version 4.4. Valid only for datagram sockets (UDP or raw IP); ignored for TCP.
IO$M_INTERRUPT	Sends an OOB message.
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. When using this function modified, always check the message length in the IOSB to ensure that all data is transferred. IO$_WRITEVBLK returns a success status even if data is only partially transferred.

Condition Values Returned

SS$_ABORT	Programming error, INET management error, or hardware error. The execution of the I/O was aborted.
SS$_ACCVIO	Programming error. An attempt was made to access an invalid memory location or buffer.
SS$_BADPARAM	Programming error. An I/O operation was specified using an invalid parameter. An attempt was made to execute an IO$_WRITEVBLK function without specifying a device socket. First create a device socket by issuing an IO$_SETMODE function and the proper arguments. An attempt was made to issue an IO$_WRITEVBLK function that did not specify a correct buffer address ( p1 or p5 is null). An attempt was made to issue an IO$_WRITEVBLK that specifies an invalid vectored buffer ( p5 specifies an invalid address descriptor).
SS$_CANCEL	The I/O operation was canceled by the $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$_EXQUOTA	Returned when process resource mode wait is disabled. There is no Internet request packet (IRP) available for completing the request. Increase the buffered I/O quota.
SS$_FILALRACC	Programming error. IP address is already in use. An attempt was made to bind the socket to an address but the port failed. IP protocol (raw socket). An attempt was made to specify a remote socket address with an IO$_WRITEVBLK function, while an IP address was already specified with an IO$_ACCESS function. UDP/IP protocol. An attempt was made to specify a remote socket address with an IO$_WRITEVBLK function, while an IP address was already specified with the IO$_ACCESS function.
SS$_ILLCNTRFUNC	Programming error. Unsupported operation on the protocol (UDP or TCP).
SS$_INSFMEM	Insufficient system dynamic memory to complete the operation.
SS$_IVADDR	Programming error. The specified IP address is not in the system, and an invalid port number or an IP address combination was specified with an IO$_WRITEVBLK operation. An attempt to bind the socket failed because the INET address is not in the system, Port 0 and IP address 0 are not allowed, or Port 0 is not allowed with an IO$_WRITEVBLK function. An attempt to get an interface IP address, broadcast mask, or network mask failed. A send request was made on a datagram-oriented protocol, but the destination address is unknown or not specified.
SS$_IVBUFLEN	Programming error. The size of the buffer for an I/O function is insufficient. An attempt was made to issue an IO$_WRITEVBLK function that specifies a correct buffer address ( p1 valid) but does not specify a buffer length ( p2 is null).
SS$_LINKDISCON	Notification. Connection completion return code. The virtual circuit (TCP/IP) was closed at the initiative of the peer. The application must stop sending data and must either shut down or close the socket.
SS$_PROTOCOL	Programming error. The address family of the remote address specified with an IO$_WRITEVBLK function is not supported (UDP or TCP). The address family should be either the TCPIP$C_AF_INET or the TCPIP$C_AF_INET6 address family.
SS$_NOLINKS	Programming error. The socket was not connected (TCP), or an INET port and address were not specified with an IO$_ACCESS (UDP). An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (raw IP). An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (UDP). An attempt was made to disconnect a socket that is not connected, or an attempt was made to issue an IO$_WRITEVBLK function on an unconnected socket (TCP).
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.
SS$_TIMEOUT	Programming error, INET management error, or hardware error. A TCP/IP connection timed out after several unsuccessful retransmissions. On a TCP socket where KEEPALIVE is set, the connection was idle for longer than the timeout interval. The default is 10 minutes.
SS$_TOOMUCHDATA	Programming or INET management error. The message size was too large. An IP packet that is broadcast cannot be fragmented. The Not Fragment IP flag was set and the IP datagram was too large to be sent without being fragmented. Internal error. The length of the Ethernet datagram does not allow enough space for the minimum IP header. The message to be sent on a UDP or raw IP socket is larger than the socket buffer high water allows. For more information, see Appendix B. An attempt was made to send or receive more than 16 buffers specified with the p5 argument.
SS$_UNREACHABLE	Communication status. The remote host is currently unreachable. This indicates a hardware error. The data link adapter detected an error and shut itself off. The TCP/IP Services software is waiting for the adapter to come back on line.

6.3 TELNET Port Driver I/O Function Codes

A user program can manage a TELNET connection with the standard OpenVMS $QIO system service by using the IO$_TTY_PORT and IO$_TTY_PORT_BUFIO I/O function codes. This section describes these I/O function codes and their associated arguments.

6.3.1 Interface Definition

The following definitions are used by the interface. The symbols are defined in SYS$LIBRARY:TNIODEF.H.

6.3.1.1 Item List Codes

Table 6-7 describes the symbols used with the p5 parameter.

Table 6-7 List Codes for the p5 Item

Item Code	Maximum Size	Description
TN$_ACCPORNAM	64	Access port name string. When written, the string's length is determined by the item_length field. The value of item_length should not be more than 63 bytes. When read, the string is returned in ASCIC format (the first byte contains the string's length), so a size of 64 is appropriate.
TN$_CHARACTERISTICS	4	Characteristics mask. This longword contains a bit mask of the device's characteristics read or to be written. (See Table 6-8.)
TN$_CONNECTION_ATTEMPTS	4	Reconnection attempts. This item is the number of unsuccessful reconnection attempts which have been made on a reconnectable device. The value will be reinitialized when a successful connection is made. This item is read only.
TN$_CONNECTION_INTERVAL	4	Minimum time (in seconds) before reconnection attempts.
TN$_CONNECTION_TIMEOUT	4	Current time (in seconds) since the last reconnection attempt. This item is read only.
TN$_DATA_HIGH	4	Maximum amount of output data (in bytes) buffered at the network port. This number does not affect the amount of data buffered within the socket.
TN$_DEVICE_UNIT	4	Terminal device unit number. When written, this value must be between 1 and 9999.
TN$_IDLE_INTERVAL	4	Maximum idle time (in seconds) allowed before a connection is to be broken. Connections are not broken if the device is stalled.
TN$_IDLE_TIMEOUT	4	Current time (in seconds) since last output on the terminal. This item is read only.
TN$_LOCAL_ADDRESS	32	Local sockaddr of the active connection. When written, the value of item_length determines the size of the sockaddr . Note that the sockaddr is in BSD Version 4.4 format, which includes a sockaddr size field. (C programs should be compiled with the _SOCKADDR_LEN symbol defined.) This item is read only.
TN$_NETWORK_DEVICE_NAME	64	Name of the network pseudodevice currently bound to the terminal. When read, the data is returned in ASCIC format (the first byte contains the string's length). This item is read only.
TN$_PROTOCOL	4	Session protocol. (See Table 6-9.)
TN$_REMOTE_ADDRESS	32	Remote peer's sockaddr of the active connection. Note that the sockaddr is in BSD Version 4.4 format, which includes a sockaddr size field. The size of the sockaddr should be determined from this field. This item is read only.
TN$_SERVICE_TYPE	4	Class of terminal service. (See Table 6-10.)
TN$_STATUS	4	Current device and session status. This item is read only.