3. $QIO Interface
The $QIO interface allows programmers to
use more sophisticated programming techniques than available with the socket
library. Using the $QIO interface, you can perform fully asynchronous
I/O to the network and receive Asynchronous System Traps (ASTs) when
out-of-band data arrives (similar to the UNIX SIGURG signal). In
general, there is a one-to-one mapping between the socket library
functions and $QIO calls.
The $QIO interface returns an OpenVMS error code in the first word of the Input/Output Status Block (IOSB). If the low bit of the OpenVMS error code is clear, an error has been returned by the network. The OpenVMS error code is generated from the UNIX errno code by multiplying the UNIX code by 8 (eight) and logical ORing it with 0x8000.
You can mix and match the socket library function and the $QIO calls. For example, you can use socket() and connect() to establish a connection, then use IO$_SEND and IO$_RECEIVE to send and receive data on it.
Note! If more than one $QIO operation is pending on a socket at any one time, there is no guarantee that the $QIO calls will complete in the order they are queued. In particular, if more than one read or write operation is pending at any one time, the data may be interleaved. You do not need to use multiple read or write operations concurrently on the same socket to increase performance because of the network buffering.
The function codes for the MultiNet-specific $QIO functions are defined in the include file multinet_root:[multinet.include.vms]inetiodef.h.
If the compile time constant USE_BSD44_ENTRIES is defined, then the BSD 4.4 variant of the IO$_ACCEPT, IO$_BIND, IO$_CONNECT, IO$_GETPEERNAME, IO$_GETSOCKNAME, IO$_RECEIVE, IO$_SEND is selected.
The following are the interface functions:
|
IO$_ACCEPT |
IO$_SEND |
|
IO$_ACCEPT_WAIT |
IO$_SENSEMODE |
|
IO$_BIND |
IO$_SENSEMODE | IO$M_CTRL |
|
IO$_CONNECT |
IO$_SETCHAR |
|
IO$_GETPEERNAME |
IO$_SETMODE|IO$M_ATTNAST |
|
IO$_GETSOCKNAME |
IO$_SETSOCKOPT |
|
IO$_GETSOCKOPT |
IO$_SHUTDOWN |
|
IO$_IOCTL |
IO$_SOCKET |
|
IO$_LISTEN |
SYS$CANCEL |
|
IO$_RECEIVE (I |
SYS$DASSGN |
|
IO$_SELECT |
|
IO$_ACCEPT
Extracts the first connection from the queue of pending connections on a socket, creates a new socket with the same properties as the original socket, and associates an OpenVMS channel to the new socket. IO$_ACCEPT is equivalent to the accept() socket library function.
Normally, instead of calling IO$_ACCEPT to wait for a connection to become available, IO$_ACCEPT_WAIT is used. This allows your process to wait for the connection without holding the extra network channel and tying up system resources. When the IO$_ACCEPT_WAIT completes, it indicates that a connection is available. IO$_ACCEPT is then called to accept it.
FORMAT
Status = SYS$QIOW(Efn, New_VMS_Channel, IO$_ACCEPT, IOSB, AstAdr, AstPrm, Address, AddrLen, VMS_Channel, 0, 0, 0);
ARGUMENTS
New_VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
An OpenVMS channel to a newly-created
INET device. Create this channel by using SYS$ASSIGN to assign a fresh
channel to INET0: before issuing the IO$_ACCEPT call.
The accepted connection is accessed using this channel.
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
The OpenVMS channel to the INET: device
on which the IO$_LISTEN call was performed.
After accepting the connection, this device remains available to accept new
connections.
Address
OpenVMS Usage: special_structure
type: structure defined below
access: write only
mechanism: by reference
An optional pointer to a structure that, following the completion of the IO$_ACCEPT call, contains the address of the socket that made the connection. This structure is defined as follows:
struct {
unsigned long Length;
struct sockaddr Address;
};
AddrLen
OpenVMS Usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
The length of the buffer pointed to by
the Address argument, in bytes. It must be at least 20 bytes.
IO$_ACCEPT_WAIT
Used to wait for an incoming connection without accepting it. This allows your process to wait for the connection without holding the extra network channel and tying up system resources. When the IO$_ACCEPT_WAIT call completes, it indicates that a connection is available. IO$_ACCEPT is then called to accept it.
The IO$_ACCEPT_WAIT call takes no function-specific parameters.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_ACCEPT_WAIT, IOSB, AstAdr, AstPrm, 0, 0, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
The OpenVMS channel to the INET: device
on which the IO$_LISTEN call was performed.
IO$_BIND
Assigns an address to an unnamed socket. When a socket is created with IO$_SOCKET, it exists in a name space (address family) but has no assigned address. IO$_BIND requests that the address be assigned to the socket. IO$_BIND is equivalent to the bind() socket library function.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_BIND, IOSB, AstAdr, AstPrm, Name, NameLen, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Name
OpenVMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
The address to which the socket should be bound. The exact format of the Address argument is determined by the domain in which the socket was created.
NameLen
OpenVMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the Name argument,
in bytes.
IO$_CONNECT
When used on a SOCK_STREAM socket, this function attempts to make a connection to another socket. When used on a SOCK_DGRAM socket, this function permanently specifies the peer to which datagrams are sent to and received from. The peer socket is specified by name, which is an address in the communications domain of the socket. Each communications domain interprets the name parameter in its own way. IO$_CONNECT is equivalent to the connect() socket library function.
If the address of the local socket has not yet been specified with IO$_BIND, the local address is also set to an unused port number when IO$_CONNECT is called.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_CONNECT, IOSB, AstAdr, AstPrm, Name, NameLen, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Name
OpenVMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
The address of the peer to which the socket should be connected. The exact format of the Address argument is determined by the domain in which the socket was created.
NameLen
OpenVMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the Name argument, in
bytes.
IO$_GETPEERNAME
Returns the name of the peer connected to the specified socket. It is equivalent to the getpeername() socket library function.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_GETPEERNAME, IOSB, AstAdr, AstPrm, Address, AddrLen, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Address
OpenVMS Usage: socket_address
type: struct sockaddr
access: write only
mechanism: by reference
A result parameter filled in with the address of the peer, as known to the communications layer. The exact format of the Address argument is determined by the domain in which the communication is occurring.
AddrLen
OpenVMS Usage: socket_address_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the
space pointed to by Address, in bytes. On return, it contains the actual
length, in bytes, of the address returned.
IO$_GETSOCKNAME
Returns the current name of the specified socket. Equivalent to the getsockname() socket library function.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_GETSOCKNAME, IOSB, AstAdr, AstPrm, Address, AddrLen, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Address
OpenVMS Usage: socket_address
type: struct sockaddr
access: write only
mechanism: by reference
A result parameter filled in with the address of the local socket, as known to the communications layer. The exact format of the Address argument is determined by the domain in which the communication is occurring.
AddrLen
OpenVMS Usage: socket_address_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the
space pointed to by Address, in bytes. On return, it contains the actual
length, in bytes, of the address returned.
IO$_GETSOCKOPT
Retrieves options associated with a socket. It is equivalent to the getsockopt() library routine. Options can exist at multiple protocol levels; however, they are always present at the uppermost socket level.
When manipulating socket options, you must specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify level as SOL_SOCKET. To manipulate options at any other level, specify the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by the TCP protocol, set Level to the protocol number of TCP, as determined by calling getprotobyname().
OptName and any specified options are passed without modification to the appropriate protocol module for interpretation. The include file multinet_root:[multinet.include.sys]socket.h contains definitions for socket-level options. Options at other protocol levels vary in format and name.
For more information on what socket options may be retrieved with IO$_GETSOCKOPT, see the socket option sections.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_GETSOCKOPT, IOSB, AstAdr, AstPrm, Level, OptName, OptVal, OptLen, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Level
OpenVMS Usage: option_level
type: longword (unsigned)
access: read only
mechanism: by value
The protocol level at which the option will be manipulated. Specify Level as SOL_SOCKET or a protocol number as returned by getprotoent().
OptName
OpenVMS Usage: option_name
type: longword (unsigned)
access: read only
mechanism: by value
The option that is to be manipulated.
OptVal
OpenVMS Usage: dependent on OptName
type: byte buffer
access: write only
mechanism: by reference
A pointer to a buffer that is to receive the current value of the option. The format of this buffer is dependent on the option requested.
OptLen
OpenVMS Usage: option_length
type: longword (unsigned)
access: modify
mechanism: by reference
On entry, contains the length of the
space pointed to by OptVal, in bytes. On return, it contains the actual
length, in bytes, of the option returned.
IO$_IOCTL
Performs a variety of functions on the network; in particular, it manipulates socket characteristics, routing tables, ARP tables, and interface characteristics. The IO$_IOCTL call is equivalent to the socket_ioctl() library routine.
A IO$_IOCTL request has encoded in it whether the argument is an input or output parameter, and the size of the argument, in bytes. Macro and define statements used in specifying an IO$_IOCTL request are located in the file multinet_root:[multinet.include.sys]ioctl.h.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_IOCTL, IOSB, AstAdr, AstPrm, Request, ArgP, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Request
OpenVMS Usage: ioctl_request
type: longword (unsigned)
access: read only
mechanism: by value
Which IO$_IOCTL function to perform. The available IO$_IOCTL functions are documented in the socket ioctl sections.
ArgP
OpenVMS Usage: arbitrary
type: byte buffer
access: read, write, or modify depending on Request
mechanism: by reference
A pointer to a buffer whose format and
function is dependent on the Request specified.
IO$_LISTEN
Specifies the number of incoming connections that may be queued while waiting to be accepted. This backlog must be specified before accepting a connection on a socket. The IO$_LISTEN function applies only to sockets of type SOCK_STREAM. The IO$_LISTEN call is equivalent to the listen() socket library function.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_LISTEN, IOSB, AstAdr, AstPrm, BackLog, 0, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Backlog
OpenVMS Usage: connection_backlog
type: longword (unsigned)
access: read only
mechanism: by value
Defines the maximum length of the queue
of pending connections. If a connection request arrives when the queue is full,
the request is ignored. The backlog queue length is limited to 5.
IO$_RECEIVE (IO$_READVBLK)
Receives messages from a socket. This call is equivalent to the recvfrom(), recv(), and socket_ read() socket library functions.
The length of the message received is returned in the second and third word of the I/O Status Block (IOSB). A count of 0 indicates an end-of-file condition; that is, the connection has been closed. If a message is too long to fit in the supplied buffer and the socket is type SOCK_DGRAM, excess bytes are discarded.
If no messages are available at the socket, the IO$_RECEIVE call waits for a message to arrive, unless the socket is nonblocking (see socket_ioctl()).
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_RECEIVE, IOSB, AstAdr, AstPrm, Buffer, Size, Flags, From, FromLen, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
OpenVMS Usage: arbitrary
type: byte buffer
access: write only
mechanism: by reference
The address of a buffer in which to place the data read.
Size
OpenVMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The length of the buffer specified by Buffer. The actual number of bytes read is returned in the Status.
Flags
OpenVMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Control information that affects the IO$_RECEIVE call. The Flags argument is formed by ORing one or more of the following values:
#define MSG_OOB 0x1 /* process
out-of-band data */
#define MSG_PEEK 0x2 /* peek at incoming message */
The MSG_OOB flag causes IO$_RECEIVE to read any out-of-band data that has arrived on the socket.
The MSG_PEEK flag causes IO$_RECEIVE to read the data present in the socket without removing the data. This allows the caller to view the data, but leaves it in the socket for future IO$_RECEIVE calls.
From
OpenVMS Usage: special_structure
type: structure defined below
access: write only
mechanism: by reference
An optional pointer to a structure that, following the completion of the IO$_RECEIVE, contains the address of the socket that sent the packet. This structure is defined as follows:
struct {
unsigned short Length;
struct sockaddr Address;
};
FromLen
OpenVMS Usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
The length of the buffer pointed to by
the From argument, in bytes. It must be at least 18 bytes.
IO$_SELECT
Examines the specified channel to see if it is ready for reading, ready for writing, or has an exception condition pending (the presence of out-of-band data is an exception condition).
The UNIX select() system call can be emulated by posting multiple IO$_SELECT calls on different channels.
Note! IO$_SELECT is only useful for channels assigned to the INET: device. It cannot be used for any other VMS I/O device.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SELECT, IOSB, AstAdr, AstPrm, Modes, 0, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Modes
OpenVMS Usage: mask_longword
type: longword (unsigned)
access: modify
mechanism: by reference
On input, the Modes argument is a bit mask of one or more of the following values:
#define SELECT_DONTWAIT
(1<<0)
#define SELECT_READABLE (1<<1)
#define SELECT_WRITEABLE (1<<2)
#define SELECT_EXCEPTION (1<<3)
If the SELECT_DONTWAIT bit is set, the IO$_SELECT call will complete immediately, whether or not the socket is ready for any I/O operations. If this bit is not set, the IO$_SELECT call will wait until the socket is ready to perform one of the requested operations.
If the SELECT_READABLE bit is set, the IO$_SELECT call will check if the socket is ready for reading or a connecting has been received and is ready to be accepted.
If the SELECT_WRITEABLE bit is set, the IO$_SELECT call will check if the socket is ready for writing or a connect request has been completed.
If the SELECT_EXCEPTION bit is set, the IO$_SELECT call will check if the socket has out-of-band data ready to read.
On output, the Modes argument is a
bit mask that indicates which operations the socket is ready to perform. If the
SELECT_DONTWAIT operation was specified, the Modes value may be zero; if
SELECT_DONTWAIT is not specified, then one or more of the SELECT_READABLE,
SELECT_WRITABLE, or SELECT_EXCEPTION bits will be set.
IO$_SEND
Transmits a message to another socket. It is equivalent to the sendto(), send(), and socket_write() socket library functions.
If no message space is available at the socket to hold the message to be transmitted, IO$_SEND blocks unless the socket has been placed in non-blocking I/O mode via IO$_IOCTL. If the message is too long to pass through the underlying protocol in a single unit, the error EMSGSIZE is returned and the message is not transmitted.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SEND, IOSB, AstAdr, AstPrm, Buffer, Size, Flags, To, ToLen, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Buffer
OpenVMS Usage: arbitrary
type: byte buffer
access: read only
mechanism: by reference
The address of a buffer containing the data to send.
Size
OpenVMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The length of the buffer specified by Buffer.
Flags
OpenVMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Control information that affects the IO$_SEND call. The Flags argument can be zero or the following:
#define MSG_OOB 0x1 /* process out-of-band data */
The MSG_OOB flag causes IO$_SEND to send out-of-band data on sockets that support this operation (such as SOCK_STREAM).
To
OpenVMS Usage: socket_address
type: struct sockaddr
access: read only
mechanism: by reference
An optional pointer to the address to which the packet should be transmitted. The exact format of the Address argument is determined by the domain in which the communication is occurring.
ToLen
OpenVMS Usage: socket_address_length
type: longword (unsigned)
access: read only
mechanism: by value
An optional argument that contains the
length of the address pointed to by the To argument.
IO$_SENSEMODE
Reads the active connections status and returns status information for all of the active and listening connections.
FORMAT
Status = SYS$QIO(efn, chan, IO$_SENSEMODE, iosb, astadr, astprm, buffer, address, conn_type, 0, 0, 0)
ARGUMENTS
p1=buffer
OpenVMS Usage: vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Optional address of the 8-byte device characteristics buffer. Data returned is: the device class (DC$_SCOM) in the first byte, the device type (0) in the second byte, and the default buffer size, which is the maximum datagram size, in the high-order word of the first longword. IO$_SENSEMODE returns the second longword as 0.
p2=address
OpenVMS Usage: vector_word_unsigned
type: word (unsigned)
access: write only
mechanism: by descriptor
Address of the descriptor for the buffer to receive the status information on the active connections.
OpenVMS Usage: Longword_unsigned
type: Longword (unsigned)
access: Read only
mechanism: by value
0 to get information about TCP connections, non-zero to get information about UDP connections.
Connection Status Information shows the 22 bytes of information returned for each connection.
|
Protocol type |
Word value is 4 for INETDRIVER stream sockets, and 5 for BGDRIVER stream sockets. |
|
Unit number |
Word value is the INETDRIVER, or BGDRIVER device unit number for the connection. |
|
Receive queue |
Word value is the number of bytes received from the peer waiting to be delivered to the user through the IO$_READVBLK function. |
|
Send queue |
Word value is the number of bytes waiting to be transmitted to or to be acknowledged by the peer. |
|
Local internet address |
Longword value is the local internet address (or 0 if the connection is not open and no local internet address was specified for the connection). |
|
Local port number |
Word value is the local port number. |
|
Peer internet address |
Longword value is the peer's internet address (or 0 if the connection is not open and no peer internet address was specified for the connection). |
|
Peer port number |
Word value is the peer's port number, or 0 if the connection is not open and you did not specify a peer port number for the connection. |
|
TCP state |
Word value is the Transmission Control Protocol connection state mask. See Table 3-1for the mask value definitions. |
Status
|
SS$_BUFFEROVF |
Buffer too small for all connections |
|
SS$_DEVINACT |
Device not active |
|
SS$_NORMAL |
Success |
The byte count for the status information buffer is returned in the high-order word of the first longword of the I/O status block. This may be less than the bytes requested. See I/O Status Block for more information.
The size in bytes of each connection's record (22 bytes) is returned in the low order word of the second longword of the I/O status block.
The total number of active connections is returned in the high-order word of the second longword of the I/O status block. This can be greater than the number of reported connections if the buffer is full.
|
Mask Value |
State |
Mask Value |
State |
Mask Value |
State |
|
1 |
LISTEN |
16 |
FIN-WAIT-1 |
256 |
LAST-ACK |
|
2 |
SYN-SENT |
32 |
FIN-WAIT-2 |
512 |
TIME-WAIT |
|
4 |
SYN-RECEIVED |
64 |
CLOSE-WAIT |
1024 |
CLOSED |
|
8 |
ESTABLISHED |
128 |
CLOSING |
|
|
IO$_SENSEMODE | IO$M_CTRL
|
SS$_BUFFEROVF |
Buffer too small for all characteristics |
|
SS$_DEVINACT |
Device not active |
|
SS$_NORMAL |
Success |
The byte count for the characteristics buffer is returned in the high-order word of the first longword of the I/O status block. This may be less than the bytes requested. The number of bytes in the receive queue is returned in the low order word of the second longword in the I/O status block. The number of bytes in the read queue is returned in the high-order word of the second longword in the I/O status block. I/O Status Block shows the I/O Status Block.
Note! 
You can
use the SYS$GETDVI system service to obtain the local port number, peer port
number, and peer internet address. The DEVDEPEND field stores the local port
number (low order word) and peer port number (high-order word). The DEVDEPEND2
field stores the peer internet address.
Performs the following functions:
Reads network device information
Reads the routing table
Reads the ARP information
Reads the IP SNMP information
Reads the ICMP SNMP information
Reads the TCP SNMP information
Reads the UDP SNMP information
FORMAT
Status = SYS$QIO(efn, chan, IO$_SENSEMODE | IO$M_CTRL, iosb, astadr, astprm, buffer, address, function, line-id, 0, 0)
ARGUMENTS
p1=buffer
OpenVMS Usage: vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Optional address of the 8-byte device characteristics buffer. The data returned is the device class (DC$_SCOM) in the first byte, the device type (0) in the second byte, and the default buffer size (0) in the high-order word of the first longword. The second longword is returned as 0.
p2=address
OpenVMS Usage: vector_word_unsigned
type: Word (unsigned)
access: write only
mechanism: by descriptor
Address of the descriptor for the buffer to receive the information. The format of the buffer depends on the information requested. Each buffer format is described separately in the section that follows.
If bit 12 (mask 4096) is set in the parameter identifier (PID), the PID is followed by a counted string. If bit 12 is clear, the PID is followed by a longword value. While MultiNet currently never returns a counted string for a parameter, this may change in the future.
p3=function
OpenVMS Usage: Longword-unsigned
type: Longword (unsigned)
access: read only
mechanism: by value
Code that designates the function.
The function codes are shown in P3 Function Codes .
|
Code |
Function |
|
1 |
P1 of the QIO is not used |
|
2 |
VMS descriptor of the space to put the return information |
|
3 |
10 |
|
4 |
Not used |
|
5 |
Not used |
|
6 |
Not used |
|
7 |
Read UDP SNMP counters |
|
8 |
Read routing table |
|
10 |
Read interface throughput information |
p4=line-id
OpenVMS Usage: Longword-unsigned
type: Longword (unsigned)
access: read only
mechanism: by value
Specify this argument only if you are reading a network device's ARP table function.
Reading Network Device Information
Use IO$_SENSEMODE | IO$M_CTRL with p3=1 to read network device information. The information returned in the buffer (specified by p2=address) can consist of multiple records. Each record consists of nine longwords, and one record is returned for each device.
When you read network device information, the data in each record is returned in the order presented below. All are longword values.
|
1 |
Line id (see the description of the line-id argument) |
|
2 |
Line's local internet address |
|
3 |
Line's internet address network mask |
|
4 |
Line's maximum transmission unit (MTU) in the low-order word, and the line flags in the high-order word |
|
5 |
Number of packets transmitted (includes ARP packets for Ethernet lines) |
|
6 |
Number of transmit errors |
|
7 |
Number of packets received (includes ARP and trailer packets for Ethernet lines) |
|
8 |
Number of receive errors |
|
9 |
Number of received packets discarded due to insufficient buffer space |
Reading the Routing Table
Use IO$_SENSEMODE | IO$M_CTRL with p3=8 to read the routing table. The information returned in the buffer (specified by p2=address) can consist of multiple records. Each record consists of five longwords, and one record is returned for each table entry.
The p3=8 function returns full routing information and is a superset of p3=2, which was retained for backwards compatibility with existing programs. p3=2 and p3=8 return the same table of routing entries, in the following order, except that p3=2 does not return items 7 and 8 (address mask and Path MTU):
|
1 |
Destination internet address. |
Destination host or network to which the datagram is bound. Returned as a longword value. |
|
2 |
Gateway internet address. |
Internet address to which the datagram for this route is transmitted. Returned as a longword value. |
|
3 |
Flags. |
Routing table entry's flag bits. Returned as a word value: Mask 1, name GATEWAY, if set, the route is to a gateway (the datagram is sent to the gateway internet address). If clear, the route is a direct route. Mask 2, name HOST, if set, the route is for a host. If clear, the route is for a network. Mask 4, name DYNAMIC, if set, the route was created by a received ICMP redirect message. Mask 8, name AUTOMATIC, if set, this route was added by MULTINET_RAPD process and will be modified or remoted by that process as appropriate. Mask 16, name LOCKED, if set, the route cannot be changed by an ICMP redirect message. Mask 32, name INTERFACE, if set, the route is for a network interface. Mask 64, name DELETED, if set, the route is marked for deletion (it is deleted when the reference count reaches 0). Mask 128, name POSSDOWN, if set, the route is marked as possibly down. |
|
4 |
Reference count. |
Number of connections currently using the route. Returned as a word value. |
|
5 |
Use count. |
Number of times the route has been used for outgoing traffic. Returned as a longword value. |
|
6 |
Line ID. |
Line identification for the network device used to transmit the datagram to the destination. See the description of the line-id argument later in this section for the line ID codes. Line ID Values shows the line identification values. |
|
7 |
Address mask. |
Address mask for the destination address. Returned as a longword value. |
|
8 |
Path MTU. |
Path maximum transmission unit. Returned as a longword value. |
|
Line ID |
Line ID Value |
Line ID |
Line ID Value |
Line ID |
Line ID Value |
|
LO-0 |
^X00000001 |
DN-n |
^X00nn0241 |
PD-n |
^X00nn0042 |
|
PSI-n |
^X00nn0006 |
PPP-n |
^X00nn0341 |
|
|
|
SL-n |
^X00nn0141 |
SE-n |
^X00nn0402 |
|
|
Note! The I/O status block (iosb) returns routing table entry size information for the p3=8 function to assist in diagnosing buffer overflow situations. See the Status section for details.
Reading Interface Throughput Information
Use IO$_SENSEMODE | IO$M_CTRL with p3=10 to read network device information. The information returned in the buffer (specified by p2=descriptor) can consist of multiple records. Each record consists of nine longwords, and one record is returned for each device.
When you read network device information, the data in each record is returned in the order presented below. All are longword values.
|
Table 3-4 QIO Parameters |
|
|
Code |
Function |
|
1 |
P1 of the QIO is not used |
|
2 |
is a VMS descriptor of the space to put the return information |
|
3 |
10 |
|
4 |
Not used |
|
5 |
Not used |
|
6 |
Not used |
The returned data is in the following format (all values are integers):
|
1 |
Line ID |
|
2 |
Average Out Bytes (for the last 6 seconds) |
|
3 |
Average In Bytes |
|
4 |
Average Out Packets |
|
5 |
Reading the ARP Table Function
Use IO$_SENSEMODE | IO$M_CTRL with function=3 to read a network device's ARP table function. The information returned in the buffer (specified by p2=address) depends on the line id specified in line-id.
The line-id argument is the line id and is a longword value. The least significant byte of the line id is the major device type code. The next byte is the device type subcode. The next byte is the controller unit number. The most significant byte is ignored.
The information returned in the buffer can consist of multiple records. Each record consists of 12 bytes, and one record is returned for each ARP table entry.
When reading a table function, the data in each record is returned in the following order:
1 Internet address. Returned as a longword value.
2 Physical address. Returned as a 6 byte value.
3 Flags. Returned as a word value. The ARP table entrys flag bits are shown in ARP Table Entry Flag Bits .
|
Mask |
Name |
Description |
|
1 |
PERMANENT |
If set, the entry can only be removed by a NETCU REMOVE ARP command and if RARP is enabled, the local host responds if a RARP request is received for this address. If clear, the entry can be removed if not used within a short period. |
|
2 |
PUBLISH |
If set, the local host responds to ARP requests for the internet address (this bit is usually only set for the local hosts's entry). If clear, the local host does not respond to received ARP requests for this address. |
|
4 |
LOCKED |
If set, the physical address cannot be changed by received ARP requests/replies. |
|
4096 |
LASTUSED |
If set, last reference to entry was a use rather than an update. |
|
8192 |
CONFNEED |
If set, confirmation needed on next use. |
|
16384 |
CONFPEND |
If set, confirmation pending. |
|
32768 |
RESOLVED |
If set, the physical address is valid. |
3
Status
|
SS$_BADPARAM |
Code specified in function argument invalid. |
|
SS$_BUFFEROVF |
Buffer too small for all information |
|
SS$_DEVINACT |
Device not active |
|
SS$_NORMAL |
Success |
|
SS$_NOSUCHDEV |
Line identification specified in arp argument does not exist. |
The byte count for the information or counters buffer is returned in the high-order word of the first longword of the I/O status block. This can be less than the bytes requested.
For the p3=2 routing table function, in the second longword of the I/O status block, bit 0 is always set, bit 1 is set if the forwarding capability is enabled, and bit 2 is set if ARP replies for non-local internet addresses are enabled.
For the p3=8 routing table function, the IOSB contains the following:
|
Status Code |
SS$_NORMAL or SS$_BUFFEROVF |
|
Transfer Byte Count |
Number of bytes of returned information |
|
Entry Size |
Number of bytes in each entry |
|
Number of Entries |
Number of entries in the routing table |
If the status is SS$_BUFFEROVF, you can determine the number of routing entries actually returned by calculating (Transfer Byte Count) DIV (Entry Size) and comparing that with the Number of Entries value. Be sure to check the Entry Size in the IO status block. Later versions of MultiNet may return more information for each entry, which will return a larger Entry Size. Any additional information to be returned in the future will be added to the end of the returned entry.
Reading the IP SNMP Counters Function
Use IO$_SENSEMODE | IO$M_CTRL with function=4 to read the IP SNMP counters.
The data returned is an array of longwords in the following format:
Indicates whether or not this entity is acting as an IP router.
The default value inserted in the IP header's time-to-live field.
The total number of input datagrams received.
The number of input datagrams discarded due to errors in their IP headers.
The number of input datagrams discarded because the IP address in their IP header's destination field was not a valid address to be received at this entity.
The number of IP datagrams for which this entity was not their final destination, and for which forwarding to another entity was required.
The number of datagrams received but discarded because of an unknown or unsupported protocol.
The number of input datagrams received but discarded for reasons other than errors.
The total number of input datagrams successfully delivered to IP user protocols, including ICMP.
The total number of IP datagrams that local IP user protocols (including ICMP) supplied to IP in request for transmission.
The number of output IP datagrams that were discarded for reasons other than errors.
The number of IP datagrams discarded because no route could be found to transmit them to their destination.
The maximum number of seconds that received fragments are held while they are awaiting reassembly at this entity.
The number of IP fragments received that needed to be reassembled at this entity.
The number of IP datagrams successfully reassembled.
The number of failures detected by the IP reassembly algorithm.
The number of IP datagrams that have been successfully fragmented at this entity.
The number of IP datagrams that have been discarded at this entity because they could not be fragmented.
The number of IP datagrams that have been created as a result of fragmentation at this entity.
Reading the ICMP SNMP Counters Function
Use IO$_SENSEMODE | IO$M_CTRL with function=5 to read the ICMP SNMP counters.
The data returned is an array of longwords in the following format:
The total number of ICMP messages received.
The number of ICMP messages received but determined as having ICMP-specific errors.
The number of ICMP Destination Unreachable messages received.
The number of ICMP Time Exceeded messages received.
The number of ICMP Parameter Problem messages received.
The number of ICMP Source Quench messages received.
The number of ICMP Redirect messages received.
The number of ICMP Echo (request) messages received.
The number of ICMP Echo reply messages received.
The number of ICMP Timestamp (request) messages received.
The number of ICMP Timestamp Reply messages received.
The number of ICMP Address Mask Request messages received.
The number of ICMP Address Mask Reply messages received.
The total number of ICMP messages that this entity attempted to send.
The number of ICMP messages that this entity did not send because of ICMP-related problems.
The number of ICMP Destination Unreachable messages sent.
The number of ICMP Time Exceeded messages sent.
The number of ICMP Parameter Problem messages sent.
The number of ICMP Source Quench messages sent.
The number of ICMP Redirect messages sent.
The number of ICMP Echo (request) messages sent.
The number of ICMP Echo reply messages sent.
The number of ICMP Timestamp (request) messages sent.
The number of ICMP Timestamp Reply messages sent.
The number of ICMP Address Mask Request messages sent.
The number of ICMP Address Mask Reply messages sent.
Reading the TCP SNMP Counters Function
Use IO$_SENSEMODE | IO$M_CTRL with function=6 to read TCP SNMP counters.
The data returned is an array of longwords in the following format:
The algorithm used to determine the timeout value for retransmitting unacknowledged octets.
The minimum value (measured in milliseconds) permitted by a TCP implementation for the retransmission timeout.
The maximum value (measured in milliseconds) permitted by a TCP implementation for the retransmission timeout.
The limit on the total number of TCP connections supported.
The number of times TCP connections have made a transition to the SYN-SENT state from the CLOSED state.
The number of times TCP connections have made a direct transition to the SYN-REVD state from the LISTEN state.
The number of failed connection attempts.
The number of resets that have occurred.
The number of
TCP connections having a current state of either ESTABLISHED or
CLOSE-WAIT.
The total number of segments received.
The total number of segments sent.
The total number of segments retransmitted.
Reading the UDP SNMP Counters Function
Use IO$_SENSEMODE | IO$M_CTRL with function=7 to read the UDP SNMP counters.
The data returned is an array of longwords in the following format:
The total number of IDP datagrams delivered to UDP users.
The total number of received UDP datagrams for which there was not an application at the destination port.
The number of received UDP datagrams that could not be delivered for reasons other than the lack of an application at the destination port.
The total
number of UDP datagrams sent from this entity.
IO$_SETCHAR
Sets special characteristics that control the operation of the INET: device, rather than the socket attached to it. These operations are normally used by only the MULTINET_SERVER process to hand off a connection to a process that it creates to handle the connection.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SETCHAR, IOSB, AstAdr, AstPrm, Flags, 0, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Flags
OpenVMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A bit mask of one or more of the following values. If IO$_SETCHAR is not called, all options are set to OFF.
#define SETCHAR_PERMANENT
(1<<0)
#define SETCHAR_SHAREABLE (1<<1)
#define SETCHAR_HANDOFF (1<<2)
If the SETCHAR_PERMANENT bit is set when the last channel to the socket device is deassigned using the SYS$DASSGN system service, the socket is not closed and the socket device is not deleted. Normally, the last deassign closes the socket. If this bit has been set, it must be explicitly cleared before the socket can be deleted.
If the SETCHAR_SHAREABLE bit is set, the socket becomes a shareable device and any process can assign a channel to it.
If the SETCHAR_HANDOFF bit is set,
the socket is not closed and the socket device is not deleted when the last
channel to the socket device is deassigned. After this occurs, the socket
reverts to a normal socket, and if a new channel is assigned and deassigned,
the socket is closed. The SETCHAR_HANDOFF bit is a safer version of the SETCHAR_PERMANENT
bit because it allows a single hand-off to another process without the risk of
a socket getting permanently stuck on your system.
IO$_SETMODE|IO$M_ATTNAST
Enables an AST to be delivered to your process when out-of-band data arrives on a socket. This is similar to the UNIX 4.3BSD SIGURG signal being delivered. You cannot enable the delivery of the AST through the socket library functions.
After the AST is delivered, you must explicitly reenable it using this call if you want the AST to be delivered when future out-of-band data arrives.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SETMODE|IO$M_ATTNAST, IOSB, AstAdr, AstPrm, Routine, Parameter, 0, 0, 0, 0);
ARGUMENTS
Routine
OpenVMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
The address of the AST routine to call when out-of-band data arrives on the socket. To disable AST delivery, set Routine to 0.
Parameter
OpenVMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
The argument with which to call the AST
routine.
IO$_SETSOCKOPT
Manipulates options associated with a socket. It is equivalent to the setsockopt() socket library function. Options may exist at multiple protocol levels; however, they are always present at the uppermost socket level.
When manipulating socket options, you must specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify Level as SOL_SOCKET. To manipulate options at any other level, specify the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by the TCP protocol, set Level to the protocol number of TCP; see getprotobyname().
OptName and any specified options are passed without modification to the appropriate protocol module for interpretation. The include file multinet_root:[multinet.include.sys]socket.h contains definitions for socket-level options. Options at other protocol levels vary in format and name.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SETSOCKOPT, IOSB, AstAdr, AstPrm, Level, OptName, OptVal, OptLen, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
Level
OpenVMS Usage: option_level
type: longword (unsigned)
access: read only
mechanism: by value
The protocol level at which the option will be manipulated. Specify Level as SOL_SOCKET, or a protocol number as returned by getprotobyname().
OptName
OpenVMS Usage: option_name
type: longword (unsigned)
access: read only
mechanism: by value
The option that is to be manipulated. For a description of each of the valid options for IO$_ SETSOCKOPT, see the socket option sections.
OptVal
OpenVMS Usage: dependent on OptName
type: byte buffer
access: read only
mechanism: by reference
A pointer to a buffer that contains the new value of the option. The format of this buffer depends on the option requested.
OptLen
OpenVMS Usage: option_length
type: longword (unsigned)
access: read only
mechanism: by value
The length of the buffer pointed to by OptVal.
IO$_SHUTDOWN
Shuts down all or part of a full-duplex connection on the socket associated with VMS_Channel. This function is usually used to signal an end-of-file to the peer without closing the socket itself, which would prevent further data from being received. It is equivalent to the shutdown() socket library function.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SHUTDOWN, IOSB, AstAdr, AstPrm, How, 0, 0, 0, 0, 0);
ARGUMENTS
VMS_Channel
OpenVMS Usage: channel
type: word (signed)
access: read only
mechanism: by value
A channel to the socket.
How
OpenVMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Controls which part of the full-duplex
connection to shut down, as follows: if How is 0, further receive
operations are disallowed; if How is 1, further send operations are
disallowed; if How is 2, further send and receive operations are
disallowed.
IO$_SOCKET
Creates an end point for communication and returns an OpenVMS channel that describes the end point. It is equivalent to the socket() socket library function.
Before issuing the IO$_SOCKET call, an OpenVMS channel must first be assigned to the INET0: device to get a new channel to the network.
FORMAT
Status = SYS$QIOW(Efn, VMS_Channel, IO$_SOCKET, IOSB, AstAdr, AstPrm, Address_Family, Type, Protocol, 0, 0, 0);
ARGUMENTS
Address_Family
OpenVMS Usage: address_family
type: longword (unsigned)
access: read only
mechanism: by value
An address family with which addresses specified in later operations using the socket will be interpreted. The following formats are currently supported; they are defined in the include file multinet_root:[multinet.include.sys]socket.h:
|
AF_INET |
Internet (TCP/IP) addresses |
|
AF_PUP |
Xerox PUP addresses |
|
AF_CHAOS |
CHAOSnet addresses |
Type
OpenVMS Usage: socket_type
type: longword (unsigned)
access: read only
mechanism: by value
The semantics of communication using the created socket. The following types are currently defined:
|
SOCK_STREAM |
SOCK_DGRAM |
SOCK_RAW |
A SOCK_STREAM socket provides a sequenced, reliable, two-way connection-oriented byte stream with an out-of-band data transmission mechanism. A SOCK_DGRAM socket supports communication by connectionless, unreliable messages of a fixed (typically small) maximum length. SOCK_RAW sockets provide access to internal network interfaces. The type SOCK_RAW is available only to users with SYSPRV privilege.
The Type argument, together with the Address_Family argument, specifies the protocol to be used. For example, a socket created with AF_INET and SOCK_STREAM is a TCP socket, and a socket created with AF_INET and SOCK_DGRAM is a UDP socket.
Protocol
OpenVMS Usage: protocol_number
type: longword (unsigned)
access: read only
mechanism: by value
A protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type using a given address format. However, many protocols may exist, in which case a particular protocol must be specified by Protocol. The protocol number to use depends on the communication domain in which communication will take place.
For TCP and UDP sockets, the protocol
number MUST be specified as 0. For SOCK_RAW sockets, the protocol number
should be the value returned by getprotobyname().
SYS$CANCEL
Cancels any I/O IOSB status of SS$_CANCEL.
Outstanding I/O operations are automatically cancelled at image exit.
For more information on SYS$CANCEL, see the OpenVMS System Services Reference Manual.
FORMAT
Status = SYS$CANCEL(VMS_Channel);
SYS$DASSGN
Equivalent to the socket_close() function. When you deassign a channel, any outstanding I/O is completed with an IOSB status of SS$_CANCEL. Deassigning a channel closes the network connection.
I/O channels are automatically deassigned at image exit.
For more information on SYS$DASSGN, see the OpenVMS System Services Reference Manual.
FORMAT
Status = SYS$DASSGN(VMS_Channel);