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.

P3=value

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.

 

Figure 3-1     Connection Status Information

Status

SS$_BUFFEROVF

Buffer too small for all connections
Truncated buffer returned

SS$_DEVINACT

Device not active
Contact system manager why MultiNet (or INETDRIVER) not started

SS$_NORMAL

Success
Status information returned

 

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.

Figure 3-2     I/O Status Block

Table 3-1     TCP State Mask Values 

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
Truncated characteristics buffer is returned

SS$_DEVINACT

Device not active
Contact system manager why MultiNet (or TCPDRIVER) not started

SS$_NORMAL

Success
Characteristics returned

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.

Figure 3-3     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 .

Table 3-2     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.

 

Table 3-3     Line ID Values

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

Average In Packets

 

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 entry’s flag bits are shown in ARP Table Entry Flag Bits .

Table 3-5     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
Truncated buffer returned.

SS$_DEVINACT

Device not active
Contact your system manager to determine why MultiNet was not started.

SS$_NORMAL

Success
Requested information returned.

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);