TCPIP Services, Programming Interfaces, Sockets API, $QIO, Network Pseudodevice Driver Functions
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help TCPIP Services, Programming Interfaces, Sockets API, $QIO, Network Pseudodevice Driver Functions *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
The network pseudodevice allows physical, logical, and virtual
I/O functions. The physical and logical I/O functions are used
only with the IP layer. Network Pseudodevice Driver I/O Functions
lists the basic I/O functions and their modifiers. The sections
that follow describe in greater detail the operation of these I/O
functions.
Table 1 Network Pseudodevice Driver I/O Functions
Function Code and Function
Arguments Modifier Description
IO$_ACCESS p3,p4 IO$M_ACCEPT Opens a connection.
IO$M_EXTEND
IO$M_NOW
IO$_ACPCONTROL p1, Performs an ACP (ancillary
p2, p3, p4 control process) operation.
IO$_DEACCESS p4 IO$M_NOW Aborts or closes a
IO$M_SHUTDOWN connection.
IO$_READVBLK IO$M_EXTEND Reads a virtual block.
p1,p2,p3,p4,p6 IO$M_
INTERRUPT
IO$M_LOCKBUF Controls the buffer
IO$M_PURGE operations.
IO$_SENSEMODE Reads the network
p2,p3,p4,p6 pseudodevice
characteristics.
IO$_SENSECHAR Reads the network
p2,p3,p4,p6 pseudodevice
characteristics.
IO$_SETMODE p1,p2, IO$M_OUTBAND Sets the network
p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTATTN for subsequent operations.
IO$_SETCHAR p1,p2, IO$M_OUTBAND Sets the network
p3,p4,p5 IO$M_READATTN pseudodevice characteristics
IO$M_WRTEATTN for subsequent operations.
IO$_WRITEVBLK IO$M_ Writes a virtual block.
p1,p2,p3,p4,p5 INTERRUPT
The following table contains the file names of the symbol
definition files. These files specify $QIO arguments
(p1,p2,...p6) for applications written in the corresponding
programming languages. You must invoke the symbol definition
by using the appropriate include statement in your application.
Table 2 Network Symbol Definition Files
File Name Language
<REFERENCE>(filpref)$INDECEC.or VAX C
<REFERENCE>(filpref)$INVAXEFortran
<REFERENCE>(filpref)$INVAXEPASCAL
<REFERENCE>(filpref)$INMACRO-32R
<REFERENCE>(filpref)$INVAXEPL/1I
<REFERENCE>(filpref)$INBLISS-322
<REFERENCE>(filpref)$INVAXEADADA
<REFERENCE>(filpref)$INVAXEBASIC
| 1 - IO$_ACCESS |
When using a connection-oriented protocol, such as TCP, the IO$_
ACCESS function initiates a connection and specifies a remote
port number and internet address. When using a connectionless
protocol, such as UDP, the IO$_ACCESS function sets the remote
port number and internet address.
For TCP, a connection request times out at a specified interval
(75 seconds is the default). This interval can be changed by
the system manager. The program can also set a specific timeout
interval for a socket that it has created.
If a connection fails, you must deallocate the socket and then
create a new socket before trying to reconnect.
Related Functions
The equivalent Sockets API function is connect().
1.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The remote port number and internet address of the host to
connect. The p3 argument is the address of an item_list_2
descriptor that points to the socket address structure containing
the remote port number and internet address.
1.2 - Function Modifiers
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.
1.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o An IO$_ACCESS function was specified
without the address of a remote socket
name (p3 was null).
SS$_BUGCHECK Inconsistent state. Report the problem to your
Compaq support representative.
SS$_CANCEL The I/O operation was canceled by a $CANCEL
system service.
SS$_CONNECFAIL The connection to a network object timed out
or failed.
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$_DUPLNAM A network configuration error. No ports were
available for new connections.
SS$_EXQUOTA The process has exceeded its socket quota or
some other process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote internet
address was already specified on a previous
IO$_ACCESS call.
o On a datagram, the remote internet address
was already specified on a previous
IO$_ACCESS call.
o On a stream socket, the IO$_ACCESS function
targeted a stream socket that was already
connected.
SS$_ILLCNTRFUNC Illegal function.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVADDR The specified internet address was not found,
or an invalid port number and internet address
combination was specified with the IO$_ACCESS
function. Port 0 is not allowed with the
IO$_ACCESS function.
SS$_IVBUFLEN The size of the socket name structure
specified with the IO$_ACCESS function was
invalid.
SS$_LINKABORT The remote socket closed the connection.
SS$_NOLICENSE The Compaq TCP/IP Services for OpenVMS license
is not present.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_REJECT The network connection is rejected for one of
the following reasons:
o An attempt was made to connect to a remote
socket that is already connected.
o An error was encountered while establishing
the connection
o The peer socket refused the connection
request or is closing the connection.
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 A TCP connection timed out before the
connection could be established.
SS$_UNREACHABLE The remote node is currently unreachable.
| 2 - IO$_ACCESS|IO$M_ACCEPT |
This function is used with a connection-based protocol, such as
TCP, to accept a new connection on a passive socket.
This function completes the first connection on the queue of
pending connections.
Related Functions
The equivalent Sockets API function is accept() .
2.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The remote port number and internet address of a new connection.
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 internet address of the new connection is written.
Use the IO$_ACCESS function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
p4
OpenVMS usage:channel
type: word (unsigned)
access: write only
mechanism: by reference
The I/O channel number assigned to a new connection. The p4
argument is the address of a word into which the new connection's
channel number is written.
2.2 - Function Modifiers
IO$M_EXTEND Allows the usage of BSD Version 4.4 formatted
socket address structures.
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.
2.3 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_BADPARAM Programming error that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o A IO$_ACCESS|IO$M_ACCEPT function was
specified without the address of the
channel for the new connection (p4 was
null or invalid).
SS$_BUGCHECK Inconsistent state. Report the problem to your
Compaq support representative.
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$_EXQUOTA The process has exceeded its socket quota or
some other process quota.
SS$_FILALRACC The specified socket name is already in use by
one of the following:
o On a raw socket, the remote internet
address was already specified on a previous
IO$_ACCESS call.
o On a datagram, the remote internet address
was already specified on a previous
IO$_ACCESS call.
o On a stream socket, the IO$_ACCESS function
targeted a stream socket that was already
connected.
SS$_ILLCNTRFUNC Illegal function.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVADDR The specified internet address was not found,
or an invalid port number and internet address
combination was specified with the IO$_ACCESS
function. Port 0 is not allowed with the
IO$_ACCESS function.
SS$_IVBUFLEN The size of the socket name structure
specified with the IO$_ACCESS function was
invalid.
SS$_LINKABORT The remote socket closed the connection.
SS$_NOLICENSE The TCP/IP Services license is not present.
SS$_PROTOCOL A network protocol error occurred. The
address family specified in the socket address
structure is not supported.
SS$_REJECT The network connection is rejected for one of
the following reasons:
o An attempt was made to connect to a remote
socket that is already connected.
o An error was encountered while establishing
the connection
o The peer socket refused the connection
request or is closing the connection.
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 A TCP connection timed out before the
connection could be established.
SS$_UNREACHABLE The remote node is currently unreachable.
| 3 - IO$_ACPCONTROL |
The IO$_ACPCONTROL function accesses the network ACP to retrieve
information from the host and the network database files.
Related Functions
The equivalent Sockets API functions are gethostbyaddr(),
gethostbyname(), getnetbyaddr(), and getnetbyname().
3.1 - Arguments
p1
OpenVMS usage:subfunction_code
type: longword (unsigned)
access: read only
mechanism: by descriptor-fixed-length descriptor
A longword identifying the network ACP operation to perform.
The p1 argument is the address of a descriptor pointing to this
longword.
To specify the network ACP operation to perform, select a
subfunction code from Subfunction Codes and a call code from
Call Codes.
Subfunction Codes defines subfunction codes for network ACP
operations.
Table 3 Subfunction Codes
Subfunction Code Description
INETACP_FUNC$C_ Get the host name of the specified
GETHOSTBYADDR internet address from the host
database.
INETACP_FUNC$C_ Get the internet address of the
GETHOSTBYNAME specified host from the host
database.
INETACP_FUNC$C_ Get the network name of the specified
GETNETBYADDR internet address from the network
database.
INETACP_FUNC$C_ Get the internet address of the
GETNETBYNAME specified network from the network
database.
Call Codes defines call codes for network ACP operations.
Table 4 Call Codes
Call Code Description
INETACP$C_ALIASES Returns the list of alias names associated
with the specified host or network from
the internet hosts or network database.
INETACP$C_TRANS Returns the internet address associated
with the specified host or network as a
32-bit value in network byte order.
INETACPC$C_HOSTENT_ Returns full host information in a
OFFSET modified hostent structure. In the
modified structure, pointers are replaced
with offsets from the beginning of the
structure.
INETACP$C_NETENT_ Returns full network information in
OFFSET a modified netent structure. In the
modified structure, pointers are replaced
with offsets from the beginning of the
structure.
IO$_ACPCONTROL searches the local host database for the host's
name. If a matching host name is not found in the local host
database, IO$_ACPCONTROL then searches the BIND database if the
BIND resolver is enabled.
p2
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Input string for the network ACP operation containing one of the
following: host internet address, host name, network internet
address, or network name. The p2 argument is the address of a
string descriptor pointing to the input string.
All internet addresses are specified in dotted-decimal notation.
p3
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the output buffer returned by IO$_ACPCONTROL.
The p3 argument is the address of a word in which the length of
the output buffer is written.
p4
OpenVMS usage:buffer
type: vector byte (unsigned)
access: write only
mechanism: by descriptor-fixed-length descriptor
Buffer into which IO$_ACPCONTROL writes its output data. The p4
argument is the address of a descriptor pointing to the output
buffer.
The format of the data returned in the output buffer is dictated
by the call code specified by the p1 argument.
o Strings returned by IO$_ACPCONTROL with a call code of
INETACP$C_ALIASES consist one of the following: host internet
address, host name, network internet address, or network name.
All internet addresses are formatted using dotted-decimal
notation. Alias names are separated by a null character (0).
The length of the returned string includes all null characters
that separate alias names.
o Internet addresses returned by IO$_ACPCONTROL with a call code
of INETACP$C_TRANS are 32-bit value and in network byte order.
o All hostent and netent structures returned by IO$_ACPCONTROL
with a call code of INETACP$C_HOSTENT_OFFSET or INETACP$C_
NETENT_OFFSET are modified; pointers are replaced with offsets
from the beginning of the structure.
3.2 - Condition Values Returned
SS$_NORMAL The service completed successfully
SS$_ABORT An error was detected while performing an ACP
function.
SS$_BADPARAM Programming or internal error. A bad
parameter (name or address) was specified
in a GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_BUFFEROVF Programming error. There was not enough space
for returning all alias names in a
GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_ENDOFFILE The information requested is not in the
database.
SS$_ILLCNTRFUNC Illegal function.
SS$_NOPRIV No privilege for the execution of an ACP
function.
SS$_RESULTOVF The ACP overflowed the buffer in returning a
parameter.
SS$_SHUT The local or remote node is no longer
accepting connections.
| 4 - IO$_DEACCESS |
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 or IO$_SETCHAR
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 Compaq Tru64 UNIX, the 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().
4.1 - 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_ Discards messages from the receive queue and
RCV disallows further receiving. Pending messages
in the receive queue for this connection are
discarded.
TCPIP$C_DSC_ Discards messages from the send queue and
SND disallows sending new messages. Pending messages
in the transmit queue for this connection are
discarded.
TCPIP$C_DSC_ Discards all messages and disallows both
ALL 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.
4.2 - 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.
4.3 - 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.
| 5 - IO$_READVBLK |
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 (1) when there is no more data buffered in system space
for this socket, or (2) when 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 (1) when all data
from a record is transferred to the user buffer, or (2) when
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 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().
5.1 - Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) 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: quadword unsigned (Alpha); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
by 32-bit value (VAX)
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 internet 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 internet
address of the message source is written.
Use the IO$_READVBLK function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
If the IO$M_EXTEND modifier is not specified, the IO$_READVBLK
function returns a BSD Version 4.3 formatted socket address
structure.
p4
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of flags to specify attributes for the read operations.
Read Flags lists the available read flags.
Table 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_ Blocks the completion of the operation until
BLOCKALL 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: by 32- or 64-bit descriptor-fixed-length descriptor
(Alpha)
by 32-bit descriptor-fixed-length descriptor (VAX)
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 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.
5.2 - 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.
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 a TCP/IP 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:
o 0 = Issue more read QIOs to read more data
before reading the OOB.
o 1 = The next read QIO will return the OOB.
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 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.
5.3 - 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:
o 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.
o An IO$_READVBLK function that does not
specify a correct buffer address (p1 or p6
is null).
o An IO$_READVBLK function specified an
invalid vectored buffer (p6 is an invalid
descriptor).
o 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 your
internet with a larger static buffer space.
SS$_IVBUFLEN Programming error occurred for one of the
following reasons:
o The size of the buffer for an I/O function
is insufficient.
o 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:
o No messages were received, so the receive
operation cannot complete. The socket is
marked as nonblocking.
o 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).
SS$_UNREACHABLE Communication status. The remote host or
network is unreachable.
| 6 - IO$_SENSEMODE/IO$_SENSECHAR |
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 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.
6.1 - Arguments
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_3 descriptor
The port number and internet 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.
Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
Related Functions
The Sockets API equivalent for this 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 internet address of the remote name
associated with the socket's peer. The p3 argument is the address
of an item_list_3 descriptor that points to the socket address
structure into which the peer name is written.
Use the IO$_SENSEMODE function with the IO$M_EXTEND modifier to
specify a BSD Version 4.4 formatted socket address structure.
Related Functions
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 following are the types of output parameter lists:
Symbolic Name Output Parameter List Type
TCPIP$C_SOCKOPT Socket options
TCPIP$C_TCPOPT TCP protocol options
TCPIP$C_IPOPT IP protocol options
TCPIP$C_IOCTL I/O control commands
Each item_list_3 structure appearing in an output parameter
list describes an individual parameter or item to return. See
<REFERENCE>(op_setsock_tab) for details about socket option
parameters; see <REFERENCE>(tcp_set_tab_opt) for TCP protocol
option parameters; and see <REFERENCE>(ip_set_tab_opt) for
IP protocol option parameters. Unsupported socket or protocol
options are ignored.
Each ioctl_com structure that appears in an output parameter list
contains an I/O control command - the get IOCTL request code and
its associated IOCTL structure address. See <REFERENCE>(ioctl_
cmds2) for details about IOCTL command parameters.
Unsupported socket options are ignored.
The equivalent Sockets API functions are getsockopt() and
ioctl().
6.2 - 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.
6.3 - 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:
o $QIO system service was specified without a
socket.
o 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:
o An invalid IO$_SENSEMODE function for the
interface was specified. The interface does
not have an IOCTL routine.
o 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.
o 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.
| 7 - IO$_SETMODE/IO$_SETCHAR |
The IO$_SETMODE and IO$_SETCHAR functions set one or more
parameters (characteristics) pertaining to the network driver.
Sockets are created using the IO$_SETMODE p1 argument. Names are
assigned to sockets using the IO$_SETMODE p3 argument. Active
sockets are converted to passive sockets using the IO$_SETMODE p4
argument. Other parameters, such as socket and protocol options,
are specified in an input parameter list using the IO$_SETMODE p5
argument.
The IO$_SETMODE p1, p3, and p4 arguments can be used with the
p5 argument in a single $QIO system service to set socket names
as well as socket and protocol options. IO$_SETMODE processes
arguments in this order: p1, p3, p4, p5. If IO$_SETMODE detects
an error, the 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 input parameters.
7.1 - Arguments
p1
OpenVMS usage:socket_characteristics
type: longword (unsigned)
access: read only
mechanism: by reference
Longword specifying the protocol, socket type, and address
family, of a new socket. The p1 argument is the address of the
longword containing the socket characteristics.
The newly created socket is marked privileged if the image that
creates a socket runs in a process that has a privileged UIC or
has BYPASS, OPER, or SYSPRV privilege.
The following table shows protocol codes:
Protocol Description
TCPIP$C_TCP TCP/IP protocol
TCPIP$C_UDP UDP/IP protocol
TCPIP$C_RAW_ IP protocol
IP
Socket Types lists the valid socket types.
Table 6 Socket Types
Socket Type Description
TCPIP$C_STREAM Permits bidirectional, reliable, sequenced,
and unduplicated data flow without record
boundaries.
TCPIP$C_DGRAM Permits bidirectional data flow with record
boundaries. No provisions for sequencing,
reliability, or unduplicated messages.
TCPIP$C_RAW Permits access to the IP layer; used to develop
new protocols that are layered upon the IP
layer.
The following table shows address family codes:
Address
Family Description
TCPIP$C_AF_ Internet domain (default).
INET
TCPIP$C_AUXS Accept hand-off of a socket already created and
initialized by the auxiliary server.
Related Functions
The equivalent Sockets API function is socket().
p3
OpenVMS usage:socket_name
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
The local name (that is, port number and internet address) to
assign to the socket. The p3 argument is the address of an item_
list_2 descriptor that points to the socket address structure
containing the local name.
Related Functions
The equivalent Sockets API function is bind() .
p4
OpenVMS usage:connection_backlog
type: byte (unsigned)
access: read only
mechanism: by value
Maximum limit of outstanding connection requests for a socket
that is connection oriented. If more connection requests are
received than are specified, the additional requests are ignored
so that TCP retries can succeed.
Related Functions
The equivalent Sockets API function is listen().
p5
OpenVMS usage:input_parameter_list
type: vector byte (unsigned)
access: read only
mechanism: by item_list_2 descriptor
Input parameter list describing one or more parameters to set.
The p5 argument is the address of an item_list_2 descriptor that
points to and identifies the type of input parameter list.
The following are the types of input parameter lists:
Symbolic Name Input Parameter List Type
TCPIP$C_SOCKOPT Socket options
TCPIP$C_TCPOPT TCP protocol options
TCPIP$C_IPOPT IP protocol options
TCPIP$C_IOCTL I/O control commands
Each item_list_2 structure appearing in an input parameter
list describes an individual parameter or item to set. See
<REFERENCE>(op_setsock_tab) for details about socket option
parameters; see <REFERENCE>(tcp_set_tab_opt) for TCP protocol
option parameters; and see <REFERENCE>(ip_set_tab_opt) for
details about IP protocol option parameters. Unsupported socket
or protocol options are ignored.
Each ioctl_com structure that appears in an input parameter list
contains an I/O control command - the set IOCTL request code and
its associated IOCTL structure address. See <REFERENCE>(ioctl_
cmds2) for details about IOCTL command parameters.
You can use one $QIO system call to set up several socket options
at once.
Unsupported socket options are ignored.
To execute set IOCTL operations, you need a system UIC or SYSPRV,
BYPASS, or OPER privilege.
Related Functions
The equivalent Sockets API functions are setsockopt() and
ioctl().
7.2 - 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 that occurred for one of the
following reasons:
o $QIO system service was specified without a
socket.
o 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$_DUPLNAM Programming error. The port being bound is
already in use. An attempt to bind the socket
to an address and port failed.
SS$_EXQUOTA Programming or INET management error occurred
for one of the following reasons:
o An attempt to create a new socket with
the IO$_SETMODE function occurred, but the
maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter).
o The number of sockets specified with the
IO$_SETMODE (listen) exceeds the maximum
number of sockets. Increase the maximum
number of sockets (INET parameter), or
reduce the listen parameter (the number of
sockets the listener socket can create).
SS$_FILALRACC Programming error. The INET address is already
in use. An attempt to bind the socket to an
address and port failed.
SS$_ILLCNTRFUNC Programming error. The operation is not
supported for one of the following reasons:
o An invalid IO$_SETMODE function for the
interface occurred that does not have an
IOCTL routine.
o An attempt to perform an IO$_SETMODE
function required a socket, but the device
did not have one. Create a socket before
issuing the function.
SS$_IVADDR Programming error. The INET address you
specified using the IO$_SETMODE function was
not placed into the system. This resulted
in an invalid port number or INET address
combination. The INET address was invalid for
one of the following reasons:
o Port zero and INET address zero are not
allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to exceed the limit of allowable
permanent entries in the ARP table
occurred.
o An attempt to bind a raw IP socket when
there are no interfaces defined in the
system occurred.
o An attempt to bind a raw IP socket to a
null INET address occurred.
SS$_INSFMEM Insufficient system dynamic memory to complete
the service.
SS$_IVBUFLEN The size of a socket option buffer specified
with the IO$_SETMODE function was invalid.
SS$_NOLICENSE Programming or system management error. A
TCP/IP Services license is not present.
SS$_NOOPER Programming or INET management error. An
attempt to execute an I/O function that needs
the OPER privilege occurred.
SS$_NOPRIV Programming or INET management error. There
are not enough privileges for the attempted
operation for one of the following reasons:
o An attempt to broadcast an IP datagram on
a process without a system UIC or SYSPRV,
BYPASS, or OPER privilege occurred.
o An attempt to use a reserved port number
lower than 1024 occurred.
o An attempt to access a process that
requires a system UIC or SYSPRV, or BYPASS
privilege occurred.
o An attempt to use raw IP on a privileged
socket that requires the SYSPRV or BYPASS
privilege occurred.
SS$_NOSUCHDEV Programming error or INET management error. An
attempt to show or delete an ARP table entry
failed because the INET address is not found.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
table failed because the entry was not found.
SS$_PROTOCOL Programming error. A specified protocol or
address family caused an error for one of the
following reasons:
o An invalid protocol type was specified at
socket creation.
o An unsupported protocol was specified.
o A protocol type that was not found in the
internal tables was specified.
o The address family is unsupported for one
of the following reasons:
- An unsupported address family with the
IO$_SETMODE subfunction was specified.
Instead, specify the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- An unsupported address family for a
remote INET address with the IO$_ACCESS
or IO$_WRITEVBLK function was specified.
Instead, specify the TCPIP$C_AF_INET
address family.
- An unsupported address family for the
local INET address with the IO$_SETMODE
function was specified. Instead, specify
the TCPIP$C_AF_INET address family.
- An unsupported address family for the
INET address of the routing module was
specified. Instead, specify the TCPIP$C_
AF_INET address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
| 8 - IO$_SETMODE|IO$M_OUTBAND |
The IO$_SETMODE|IO$M_OUTBAND function/modifier combination
requests that the asynchronous system trap (AST) for an out-
of-band (OOB) character be delivered to the requesting process.
This is to be done only when an OOB character is received on the
socket and there is no waiting read request. The socket must be a
TCP (stream) socket.
The Enable OOB character AST function allows an Attention AST
to be delivered to the requesting process only once. After the
AST occurs, the function must explicitly reenable AST delivery
before a new AST can be delivered. This function is subject to
AST quotas.
8.1 - 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 OOB
character AST routine. To disable the AST, p1 equals 0.
p2
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be delivered to the AST routine specified by the
p1 argument.
p3
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to deliver the AST.
8.2 - Condition Values Returned
SS$_NORMAL The service completed successfully.
SS$_ABORT Programming, INET management, or hardware
error.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. A $QIO service with an
invalid parameter occurred for one of the
following reasons:
o An attempt to execute an IO$_SETMODE
function (all subfunctions, except socket
creation) without specifying a device
socket. Instead, create a device socket
by issuing a $QIO with the IO$_SETMODE
function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static INET parameters occurred. If new
parameters are needed, shut down the internet,
reset the static parameters, and issue the
START COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver was not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure executed incorrectly. The driver was
loaded, but the INET_ACP was not activated.
Execute the INET startup procedure again.
SS$_DUPLNAM Programming error. An attempt to bind a port
that is already in use occurred. An attempt to
bind the socket to an address and port failed.
SS$_EXQUOTA Programming or INET management error occurred
because of one of the following reasons:
o An attempt to create a new socket with the
IO$_SETMODE function failed because the
maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter).
o The number of sockets specified with the
IO$_SETMODE (listen) exceeds the maximum
number of sockets. Increase the maximum
number of sockets (INET parameter), or
reduce the listen parameter (the number
of sockets that the listener socket can
create).
SS$_FILALRACC Programming error. INET address is already
in use. An attempt to bind the socket to an
address and port failed.
SS$_INSFMEM Programming or system management error: Not
enough resources to allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported
because of one of the following reasons:
o Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
o An attempt to perform an IO$_SETMODE
(IOCTL) function that required a socket,
but the device did not have one. Create a
socket and issue the IOCTL function.
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an invalid INET address combination
was specified with an IO$_SETMODE function (a
bind) for one of the following reasons:
o An attempt to bind the address failed
because the INET address is not in the
system and port zero and INET address zero
are not allowed.
o An attempt to make a permanent entry in an
ARP table that was full failed.
o An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
o An attempt was made to bind an IP socket
(raw IP) to a null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. TCP/IP
Services 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. Not
enough privileges for the attempted operation
for one of the following reasons:
o Broadcasting an IP datagram was denied
because the process does not have a system
UIC or SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An operation accesses only processes that
have a system UIC or SYSPRV or BYPASS
privilege.
o Raw IP protocol can be used only on
privileged sockets. The process must have a
SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An INET address is not in the ARP table. An
attempt to show or delete an ARP table entry
failed.
SS$_NOSUCHNODE Programming or INET management error. An
attempt to delete a route from the routing
table failed because a route entry was not
found.
SS$_PROTOCOL Programming error because of one of the
following reasons:
o The protocol type specified at socket
creation is not valid.
o The protocol is not supported.
o The protocol type specified is not found
in the internal tables and therefore is an
invalid type.
o The address family is not supported for one
of the following reasons:
- The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
- The address family of the INET address
specified in a request to the routing
module is not supported. The address
family should be the TCPIP$C_AF_INET
address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
| 9 - IO$_SETMODE|IO$M_READATTN |
The IO$_SETMODE|IO$M_READATTN function/modifier combination
requests that an Attention AST be delivered to the requesting
process when a data packet is received on the socket and there is
no waiting read request.
The Enable Read 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.
Consider the following when using IO$M_READATTN:
o 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 an event occurs.
o If an out-of-band (OOB) Attention AST is enabled, the OOB AST
is delivered, regardless of the following:
- An enabled Read Attention AST
- The TCPIP$C_OOBINLINE socket option
- A READ $QIO waiting for completion on the socket
If the TCPIP$C_OOBINLINE option is set, then a waiting READ
$QIO is completed and the OOB character is returned in the data
stream.
o If both an OOB AST and a Read Attention AST are enabled, only
the OOB AST is delivered when an OOB character is received.
o If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE
socket option is set, a waiting READ $QIO completes and the
OOB character is returned in the data stream.
o If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE
socket option is not set (clear), the Read Attention AST
is delivered when an OOB character is received, regardless
of whether a READ $QIO is waiting for completion. In this
case, the OOB character is not returned in the data stream.
Therefore, if the OOB character is the only character
received, the READ $QIO does not complete.
9.1 - 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 Read
Attention AST routine. To disable the AST, set p1 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 to deliver the AST.
9.2 - Condition Values Returned
SS$_ABORT Programming, INET management, or hardware
error. The route entry already exists, so
the attempt to add a route entry using the
IO$_SETMODE function failed.
SS$_ACCVIO Programming error. An attempt to access an
invalid memory location or buffer occurred.
SS$_BADPARAM Programming error. The parameter specified
for a $QIO function was invalid for one of the
following reasons:
o An attempt to execute the IO$_SETMODE
subfunctions without specifying a device
socket occurred. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. An attempt to change
the static INET parameter was unsuccessful.
If you need new parameters, shut down the
internet, reset the static parameters, and
issue the START COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver was not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. TCP/IP Services
improperly executed the startup procedure. The
driver was loaded, but the INET_ACP was not
activated. Execute the INET startup procedure
again.
SS$_DUPLNAM Programming error. An attempt to bind a port
already in use occurred so the operation
to bind the socket to the address and port
failed.
SS$_EXQUOTA Programming or INET management error. The
quota for the valid number of sockets caused
an error for one of the following reasons:
o An attempt to exceed the maximum number
of sockets by creating new socket with the
IO$_SETMODE function occurred. Increase the
maximum number of allowable sockets (INET
parameter) before creating more sockets.
o The number of sockets specified with the
IO$_SETMODE function exceeds the maximum
number of sockets allowed. Increase the
maximum number of sockets (INET parameter)
or reduce the number of sockets that
the listener socket can create (listen
parameter).
SS$_FILALRACC Programming error. An attempt to bind the
socket to an address that is already in use
occurred and the operation failed.
SS$_INSFMEM Programming or system management error. The
system does not have enough resources to
allocate new socket.
SS$_ILLCNTRFUNC Programming error. Operation is not supported.
o Invalid IO$_SETMODE (IOCTL) function was
used for the interface. The interface does
not have an IOCTL routine.
o An attempt was made to perform an IO$_
SETMODE (IOCTL) function that required
a socket, but the device did not have
one. Create a socket and issue the IOCTL
function.
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an invalid INET address combination
was specified with an IO$_SETMODE function (a
bind).
o An attempt to bind the address failed
because the INET address is not in the
system, port zero and INET address zero are
not allowed, or port zero is not allowed
when using an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to make a permanent entry in the
ARP table failed because of lack of space.
Too many permanent entries.
o An attempt was made to bind an IP socket
(raw IP) when there are no interfaces
defined in the system.
o An attempt was made to bind an IP socket
(raw IP) to a null INET address.
SS$_IVBUFLEN Programming error. The socket option buffer
has an invalid size.
SS$_NOLICENSE Programming or system management error. TCP/IP
Services 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. Not
enough privileges for the attempted operation.
o Broadcasting an IP datagram was denied
because the process does not have a system
UIC or SYSPRV, BYPASS, or OPER privilege.
o An attempt was made to use a reserved port
number lower than 1024.
o An operation accesses only processes that
have a system UIC or SYSPRV, or BYPASS
privilege.
o Raw IP protocol can be used only on
privileged sockets. The process must have a
SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error.
An INET address is not in the ARP table. An
attempt to show or delete an ARP table entry
failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
table failed because a route entry was not
found.
SS$_PROTOCOL Programming error.
o The protocol type specified at socket
creation is not valid.
o The protocol is not supported.
o The protocol type specified is not found in
the internal tables. It is an invalid type.
o The address family is not supported:
- The address family specified with an
IO$_SETMODE function (IOCTL subfunction)
is not supported. The address family
should be the TCPIP$C_AF_INET or
TCPIP$C_UNSPEC address family.
- The address family of the remote INET
address specified with an IO$_ACCESS or
IO$_WRITEVBLK function is not supported
(UDP/IP or TCP/IP). The address family
should be the TCPIP$C_AF_INET address
family.
- The address family of the local INET
address specified with an IO$_SETMODE
(bind) function is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
- The address family of the INET address
that is specified in a request to the
routing module is not supported. The
address family should be the TCPIP$C_AF_
INET address family.
SS$_SHUT The local or remote node is no longer
accepting connections.
| 10 - IO$_SETMODE|IO$M_WRTATTN |
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 management command SHOW DEVICE_SOCKET to display
information about the socket's characteristics, options, and
state.
10.1 - 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 to deliver the AST.
10.2 - 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:
o An attempt to execute the IO$_SETMODE
functions without specifying a device
socket occurred. Instead, create a device
socket by issuing a $QIO with the IO$_
SETMODE function and the proper parameters.
o A socket option was specified incorrectly.
SS$_DEVACTIVE INET management error. You attempted to change
the static INET parameters. If you need new
parameters, shut down the internet, reset
the static parameters, and issue the START
COMMUNICATION command.
SS$_DEVINTACT INET management error. The driver is not
started. Issue a START COMMUNICATION command
before issuing $QIO functions.
SS$_DEVNOTMOUNT INET management error. The INET startup
procedure was improperly executed. The
driver was loaded, but the INET_ACP was not
activated. Execute the INET startup procedure
again.
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$_EXQUOTA Programming or INET management error.
o An attempt to create a new socket with the
IO$_SETMODE function and it failed because
the maximum number of sockets was exceeded.
Increase the maximum number of sockets
(INET parameter), and then create a new
socket.
o The number of sockets specified with the
IO$_SETMODE function exceeds the allowable
maximum number of sockets. Increase the
maximum number of sockets (INET parameter),
or reduce the number of sockets that
the listener socket can create (listen
parameter).
SS$_FILALRACC Programming error. Because the INET 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. The operation is
unsupported for one of the following reasons:
o An invalid IO$_SETMODE function for the
interface was specified. The interface does
not have an IOCTL routine.
o An attempt 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
INET address combination was specified with
the IO$_SETMODE bind function. This caused
the operation to fail for one of the following
reasons:
o An illegal combination of port zero and
INET address zero was specified.
o An attempt to make a permanent entry in
the ARP table occurred, and the operation
failed because of lack of space. There are
too many permanent entries.
o An attempt to bind a raw IP socket occurred
when there were no interfaces defined in
the system.
o An attempt to bind a raw IP socket to a
null INET address occurred.
SS$_IVBUFLEN Programming error. An invalid size was
specified for the socket option buffer.
SS$_NOLICENSE Programming or system management error. There
is no TCP/IP Services license present.
SS$_NOOPER Programming or INET management error. An
attempt to execute an I/O function that needs
the OPER privilege occurred.
SS$_NOPRIV Programming or INET management error. The
operation failed for one of the following
reasons:
o An attempt to broadcast an IP datagram for
a process without having a system UIC or
SYSPRV, BYPASS, or OPER privilege.
o An attempt to use a reserved port number
lower than 1024 occurred.
o An attempt to access a process without
having a system UIC or SYSPRV, or BYPASS
privilege occurred.
o An attempt to use raw IP on a socket that
is not a privileged socket occurred. To
do this, the process must have SYSPRV or
BYPASS privilege.
SS$_NOSUCHDEV Programming error or INET management error. An
attempt to show or delete an entry in the
ARP table occurred. However, because the
INET address was not in the ARP table, the
operation failed.
SS$_NOSUCHNODE Programming error or INET management error.
An attempt to delete a route from the routing
information table (RIT) occurred. However,
because the route was not found in the RIT,
the operation failed.
SS$_PROTOCOL Programming error.
o An invalid protocol type was specified when
creating a socket.
o An unsupported protocol was specified.
o An unsupported protocol type was specified
because it is not found in the internal
tables.
o An unsupported address family was specified
for one of the following reasons:
- An invalid address family was
specified with an IO$_SETMODE
subfunction. Instead, specify the
TCPIP$C_AF_INET or TCPIP$C_UNSPEC
address family.
- An address family of the remote INET
address for a datagram or stream
socket was specified with an IO$_
ACCESS or IO$_WRITEVBLK function.
Instead, specify the TCPIP$C_AF_INET
address family.
- An invalid address family of the
local INET address was specified
with an IO$_SETMODE bind function.
Instead, specify the TCPIP$C_AF_INET
address family.
- You made a request to the routing
module by specifying the address
family of the INET address. Instead,
specify the TCPIP$C_AF_INET address
family.
SS$_SHUT The local or remote node is no longer
accepting connections.
| 11 - IO$_WRITEVBLK |
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 connectless-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().
11.1 - Arguments
p1
OpenVMS usage:buffer
type: vector byte (unsigned)
access: read only
mechanism: by 32- or 64-bit reference (Alpha)
by 32-bit reference (VAX)
The 32- or 64-bit address (on Alpha systems) or the 32-bit
address (on VAX systems) 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); longword unsigned (VAX)
access: read only
mechanism: by 64-bit value (Alpha)
by 32-bit value (VAX)
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 internet 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 internet 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_ Sends message directly without routing.
DONTROUTE
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: by 32- or 64-bit descriptor-fixed-length descriptor
(Alpha)
by 32-bit descriptor-fixed-length descriptor (VAX)
Input buffer list describing one or more buffers containing the
data to be transmitted. The p5 argument is the 32- or 64-bit
address (on Alpha systems) or the 32-bit address (on VAX systems)
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.
11.2 - 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.
11.3 - 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. A $QIO I/O function was
specified using an invalid parameter.
o 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.
o An attempt was made to issue an
IO$_WRITEVBLK function that did not specify
a correct buffer address (p1 or p5 is
null).
o 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
in 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.
o INET address is already in use. An attempt
was made to bind the socket to an address
but the port failed.
o IP protocol (raw socket). An attempt was
made to specify a remote INET socket
address with an IO$_WRITEVBLK function,
while an INET address was already specified
with an IO$_ACCESS function.
o UDP/IP protocol. An attempt was made to
specify a remote INET socket address with
an IO$_WRITEVBLK function, while an INET
address was already specified with the IO$_
ACCESS function.
SS$_ILLCNTRFUNC Programming error. Unsupported operation on
the protocol (IP, UDP/IP, TCP/IP).
SS$_INSFMEM INET management or programming error returned
when process resource mode wait is disabled.
Not enough system space for buffering user
data. A higher quota for socket buffer space
needs to be set, or the internet needs more
dynamic buffer space (number of dynamic
clusters should be increased).
SS$_IVADDR Programming error. The specified INET address
is not in the system, and an invalid port
number or an INET address combination was
specified with an IO$_WRITEVBLK operation.
o An attempt to bind the socket failed
because the INET address is not in the
system, port number zero and INET address
zero are not allowed, or port zero is not
allowed with an IO$_ACCESS or IO$_WRITEVBLK
function.
o An attempt to get an interface INET
address, broadcast mask, or network mask
failed.
o A send request was made on a datagram-
oriented protocol, but the destination
address is unknown or not specified.
SS$_IVBUFLEN Programming error.
o The size of the buffer for an I/O function
is insufficient.
o 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 INET address specified with an
IO$_WRITEVBLK function is not supported
(UDP/IP or TCP/IP). The address family should
be the TCPIP$C_AF_INET address family.
SS$_NOLINKS Programming error. The socket was not
connected (TCP/IP), or an INET port and
address were not specified with an IO$_ACCESS
(UDP/IP or IP).
o 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).
o 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/IP).
o 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/IP).
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.
o A TCP/IP connection timed out after several
unsuccessful retransmissions.
o 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.
o An IP packet that is broadcast cannot be
fragmented.
o The Not Fragment IP flag was set and the IP
datagram was too large to be sent without
being fragmented.
o Internal error. The length of the Ethernet
datagram does not allow enough space for
the minimum IP header.
o The message to be sent on a UDP/IP or raw
IP socket is larger than the socket buffer
high water allows.
o 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.
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.
|
|
