5. IPDRIVER Services
Introduction
This chapter describes the IP device driver (IPDRIVER) services. It describes both the user and external interfaces of this IP implementation:
• The user interface exists above the IP layer, de-multiplexing received datagrams, as described below.
• The external interface provides a method by which you can support four types of network interfaces. The program you create is responsible for sending and receiving raw IP datagrams over the network interface.
IP does not include end-to-end data reliability, flow control, sequencing, or other services usually found in host-to-host protocols. Since TCP does include these services, you should use TCP unless the applications programs intend to implement or do not require these services.
IP services are available through the OpenVMS Queue I/O (SYS$QIO and SYS$QIOW) system services. Functions are provided to open and close a port, and to transmit and receive datagrams.
SYS$QIOW is the synchronous and SYS$QIO the asynchronous form of VMS system services. Use each form depending on your application’s requirements.
The IPDRIVER uses ports to demultiplex received datagrams. When an IP datagram is received, IPDRIVER validates the header and searches for a port opened on the protocol number indicated within the datagram’s internet header. If no port is opened for that protocol or that port has no outstanding receive, IPDRIVER discards the datagram.
See Figure 5-1 for an illustration of the user interface and external interface working with IPDRIVER. The IP specifications are in RFC 791.
The external interface is intended primarily for sites that use proprietary network hardware. This interface lets you write programs that support the use of IPDRIVER with various network controllers. This chapter refers to these programs as Network Interface Programs.
Basically, the Network Interface Programs perform two functions:
• Delivery of received datagrams to IPDRIVER for processing.
• Receiving of datagrams from IPDRIVER for transmission.
These programs do not handle IP activities such as routing, fragmentation and reassembly, or datagram validation. IPDRIVER performs these activities.
Sequence of Operations
Perform the following sequence of operations to open a port:
1 Assign an I/O channel to IPA0: with the SYS$ASSIGN system service. SYS$ASSIGN creates a new device unit and assigns to it the channel for the port.
2 Open the port with the IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP function of the SYS$QIO or SYS$QIOW system service.
3 Perform read requests with the IO$_READVBLK function and write requests with the IO$_WRITEVBLK function to receive and transmit datagrams as desired.
4 Close the port with the IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN function.
5 Deassign the I/O channel with the SYS$DASSGN system service.
See the appropriate OpenVMS documentation for information on the OpenVMS I/O system services (SYS$ASSIGN, SYS$CANCEL, SYS$DASSGN, SYS$QIO, and SYS$QIOW) and on related system services, such as asynchronous system trap (AST) and event flag services.
Other Operations
In addition to the sequence of operations described above, IPDRIVER includes other operations that:
|
Read the network device information, read the ARP table, or read the routing table with |
IO$_SENSEMODE | IO$M_CTRL |
|
Read the IP counters with |
IO$_SENSEMODE | IO$M_RD_COUNT |
Internet Protocol Implementation Notes
The material presented here does not explain or describe the Internet Protocol (IP).
TCPware for OpenVMS implements Version 4 of the IP, and the following restrictions apply:
• The type of service field is ignored.
• All options are ignored (options may be present in incoming datagrams). Options are copied to fragmented datagrams as required by the Internet Protocol specification.
• The TCPware host may send the following Internet Control Message Protocol (ICMP) messages:
|
Destination unreachable |
When the datagram cannot be forwarded or the destination port is not active |
|
Echo |
In response to a echo request |
|
Parameter problem |
When you enable forwarding and the datagram contains a parameter error |
|
Redirect |
When you enable forwarding and the forwarded datagram exits by the same interface on which it was received (see the NETCU ENABLE FORWARDING command) |
|
Timestamp reply |
In response to a timestamp request |
IPDRIVER System Service Call Format
The format for the IPDRIVER SYS$QIO system service call is as follows:
status = SYS$QIO[W](efn, chan, func, iosb, astadr, astprm, p1,p2,p3,p4,p5,p6)
SYS$QIO or SYS$QIOW issues IP functions.
SYS$QIO is for asynchronous service completion, specifying that the service return to the caller immediately after queuing the I/O request.
SYS$QIOW is for synchronous service completion, specifying that the service place the calling process in a wait state and only return to the caller after completing the I/O operation.
The OpenVMS IODEF module provides definitions for the SYS$QIO function codes.
Note! The vertical bar ( | ) used in some of the functions described in this chapter is the C bitwise inclusive OR operator.
IPDRIVER System Service Call Arguments
You invoke IPDRIVER system service calls with the standard OpenVMS QIO mechanism.
See the appropriate OpenVMS documentation (for example, the Introduction to VMS System Services volume) for details on the QIO mechanism.
The following sections describe each system call argument.
efn
|
OpenVMS usage: |
ef_number |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism |
by value |
Number of the event flag set by completion of the I/O operation. The argument is optional.
chan
|
OpenVMS usage: |
channel |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
I/O channel assigned to the IP device to which you are directing the request.
func
|
OpenVMS usage: |
function_code |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Device-specific function code and the modifier, if appropriate, for each operation.
Note! The IPDRIVER User Interface System Service Call Function Codes and IPDRIVER External Interface sections describe each func in detail.
iosb
|
OpenVMS usage: |
function_code |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
I/O status block that receives the final completion status of the I/O operation, structured as in Figure 5-2.
Table 5-1 describes the status block fields in more detail.
|
Field Name |
Description |
|
Function-Specific |
Varies for each function code. |
|
Status Code |
SS$ status code or special error status code. If the low bit (0) of the OpenVMS error code is clear, the network returned an error. |
|
Transfer Byte Count |
Number of bytes of data transferred in the I/O operation. |
astadr
|
OpenVMS usage: |
ast_procedure |
|
type: |
procedure entry mask |
|
access: |
call without stack unwinding |
|
mechanism: |
by reference |
Address of the asynchronous system trap (AST) routine executed when the I/O is completed.
astprm
|
OpenVMS usage: |
user_arg |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
AST parameter to be passed to the AST routine.
p1 to p6
|
OpenVMS usage: |
varying_arg |
|
type: |
longword (unsigned) |
|
access: |
read only or write only |
|
mechanism: |
by reference or by value |
Function-specific parameters, as described for each function.
IPDRIVER User Interface System Service Call Function Codes
System service call function codes specify what action the QIO performs. This section describes the following function codes for the User Interface:
|
IO$_READVBLK |
IO$_SETMODE | IO$M_CTRL |
|
IO$_SENSEMODE | IO$M_RD_COUNT |
IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP |
|
IO$_SENSEMODE |
IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN |
|
IO$_SENSEMODE | IO$M_CTRL |
IO$_WRITEVBLK |
IO$_READVBLK
Receives a datagram. The data received is written to the specified user buffer.
Note! IPDRIVER delivers ICMP messages received for the active protocol. It is up to the application to check the "protocol" field in the received datagram to determine if the received datagram is an ICMP message. IPDRIVER can deliver the following ICMP messages: destination unreachable, time exceeded, parameter problem, source quench, and redirect.
Note! A copy of a broadcast or multicast datagram is looped back by default. This means that your application receives its own broadcast and multicast datagrams.
Format
status = SYS$QIO(efn, chan,IO$_READVBLK,iosb, astadr, astprm, buffer, size,0, 0, 0, 0)
Arguments
p1=buffer
|
OpenVMS usage: |
vector_byte_unsigned |
|
type: |
byte (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
Address of the user’s buffer that receives the datagram. This buffer must be large enough to store the internet header as well as the expected data. The maximum size of an internet header is 60 bytes.
p2=size
|
OpenVMS usage: |
word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
User’s buffer size in bytes (the byte count). This is the amount of data the user is willing to receive (including the internet header). The value should not be greater than 65000 bytes.
The internet header contains the following fields:
|
Destination internet address (i.e., the local internet address) |
Longword at an offset of 16 bytes into the header. Stored in internet byte order. |
|
Identification |
Word at an offset of 4 bytes into the header. Stored in internet byte order. |
|
Options |
Variable length buffer (internet header size - 20) at an offset of 20 bytes into the header. |
|
Source internet address |
Longword at an offset of 12 bytes into the header. Stored in internet byte order. |
|
Time to Live |
Byte at an offset of 8 bytes into the header. |
|
Type of Service |
Byte at an offset of 1 byte into the header. |
See RFC 791 for details on the internet header.
Status
|
SS$ABORT |
Request aborted due to closed connection |
|
SS$_BUFFEROVF |
User’s buffer was too small for entire datagram |
|
SS$_CANCEL |
Request cancelled |
|
SS$_DEVINACT |
Device not active or port was not opened |
|
SS$_NODATA |
No datagram is available and IO$M_NOW was specified |
|
SS$_NORMAL |
Success |
The number of bytes of the entire datagram (including the internet header) is returned in the high-order word of the first longword of the I/O status block. The size (in bytes) of the internet header is returned in the low-order word of the second longword. The size (in bytes) of the data within the datagram is returned in the high-order word of the second longword.
IO$_SENSEMODE | IO$M_CTRL
Performs the following functions:
• Reads extended characteristics
• Reads network device information
• Reads the ARP table
• Reads the routing table
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 TCPware 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 Table 5-2.
|
Table 5-2 P3 Function Codes |
|
|
Code |
Function |
|
0 |
Read extended characteristics |
|
1 |
Read network device information |
|
2 |
Read routing table |
|
3 |
Read ARP table |
|
8 |
Read routing table (includes CIDR-related mask information) |
|
9 |
Returns a record for each interface in the following format: Line Id All values are longwords. |
p3 function code 8 is a superset of function code 2. Both read the routing table, although the output is different. For details, see the Reading the R section.
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 Extended Characteristics
Use IO$_SENSEMODE | IO$M_CTRL with function=0 to read the extended characteristics. The information returned consists of one or more records, each record containing a word parameter identifier (PID) value followed by either a longword or a counted string. A counted string consists of a word length followed by the specified number of bytes. The parameters that can be returned are listed in Table 5-3.
|
PID |
Meaning |
|
14 |
IP TTL. Longword. Low byte of the longword contains the time-to-live (TTL). |
|
15 |
IP TOS. Longword. Low byte of the longword contains the type of service (TOS). |
|
18 |
Multicast interface. Longword. IP address of the local interface to use in sending multicast datagrams. If o, the default interface is used. |
|
19 |
Multicast TTL. Longword. Low byte contains the time-to-live (TTL) to be used in sending multicast datagrams. |
|
20 |
Multicast loopback. Longword. Low byte is 0 to disable and 1 to enable local loopback of multicast datagrams. |
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.
The SHOW NETWORKS command in NETCU uses this function.
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=2 or 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 SHOW ROUTES command in NETCU uses this function.
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 TCPWARE_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. Table 5-4 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 5-4 Line ID Values |
|
|
Line ID |
Line ID Value |
|
LPB-0 |
^X00000001 |
|
PRO-n |
^X00nn0003 |
|
HYP-n |
^X00nn0004 |
|
X25-n |
^X00nn0006 |
|
UNA-n |
^X00nn0102 |
|
DSV-n |
^X00nn0105 |
|
SLIP-n |
^X00nn0141 |
|
QNA-n |
^X00nn0202 |
|
DSB-n |
^X00nn0205 |
|
DECNET-n |
^X00nn0241 |
|
BNA-n |
^X00nn0302 |
|
DST-n |
^X00nn0305 |
|
PPP-n |
^X00nn0341 |
|
SVA-n |
^X00nn0402 |
|
MNA-n |
^X00nn0502 |
|
ISA-n |
^X00nn0602 |
|
KFE-n |
^X00nn0702 |
|
MXE-n |
^X00nn0802 |
|
ERA-n |
^X00nn0902 |
|
EWA-n |
^X00nn0A02 |
|
CLIP-n |
^X00nn2002 |
|
ELA-n |
^X00nn2102 |
|
MFA-n |
^X00nn4102 |
|
FZA-n |
^X00nn4202 |
|
FAA-n |
^X00nn4302 |
|
FEA-n |
^X00nn4402 |
|
FQA-n |
^X00nn4502 |
|
TRA-n |
^X00nn6102 |
|
TRE-n |
^X00nn6202 |
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 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 SHOW ARP command in NETCU uses this function.
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 Table 5-5. |
|
Table 5-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. |
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 TCPware 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.
IO$_SENSEMODE | IO$M_RD_COUNT
Reads the IP counters.
The IO$M_CLR_COUNT modifier with this function zeros the counters after they are read. Using IO$M_CLR_COUNT requires the OPER privilege.
Format
status = SYS$QIO(efn, chan,IO$_SENSEMODE | IO$M_RD_COUNT, iosb, astadr, astprm, buffer, address, 0, 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. 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_longword_unsigned |
|
type: |
longword (unsigned) |
|
access: |
write only |
|
mechanism: |
by descriptor |
Address of the descriptor for the buffer to receive the information. The information returned in the buffer is a record that consists of eleven longwords. The data in the record is returned in the order below. Each value is a longword.
1 Number of seconds since last zeroed
2 Number of IP datagrams transmitted
3 Number of IP datagrams fragmented
4 Number of IP datagrams forwarded (if gateway capability is enabled)
5 Number of ICMP messages transmitted
6 Number of IP datagrams and fragments received
7 Number of IP fragments received
8 Number of ICMP messages received
9 Number of datagrams delivered to receivers
10 Number of IGMP messages transmitted
11 Number of IGMP messages received
Status
|
SS$_BUFFEROVF |
Buffer too small for all characteristics |
|
SS$_NOPRIV |
Insufficient privilege |
The byte count for the counters buffer is returned in the high-order word of the first longword of the I/O status block. This is the actual number of bytes received, which may be less than what was requested.
IO$_SETMODE | IO$M_CTRL
Sets the port characteristics.
Format
status = SYS$QIO(efn, chan,IO$_SETMODE | IO$M_CTRL, iosb, astadr, astprm, 0, address, 0, 0, 0, 0)
Argument
p2=address
|
OpenVMS usage: |
vector_word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by descriptor |
IO$_SETMODE | IO$M_CTRL sets the port characteristics in the extended characteristics buffer. The buffer consists of a series of six-byte or counted string entries. The first word of each entry contains the parameter identifier (PID) of a characteristic, followed by either a longword that contains the value for that characteristic or a counted string. Counted strings consist of a word with the size of the character string followed by the character string.
The address argument is the address of the descriptor for the extended characteristics buffer. Figure 5-3 shows the format of the descriptor for the extended characteristics buffer and the extended characteristics buffer.
Table 5-6 lists the port characteristics you can set.
|
PID |
Meaning |
|
13 |
IP options. Counted string. Internet Protocol options to be included in datagrams to be transmitted. |
|
14 |
IP TTL. Longword. Low byte of the longword contains the time-to-live (TTL) to be used in datagrams to be transmitted. |
|
15 |
IP TOS. Longword. Low byte of the longword contains the type of service (TOS) to be used in datagrams to be transmitted. |
|
16 |
Join multicast group. Counted string of eight bytes. First longword contains the multicast group IP address to join. Last longword contains the IP address of the local interface on which to join the group (if 0, the default interface is used). |
|
17 |
Leave multicast group. (See the previous PID.) |
|
18 |
Multicast Interface. Longword. IP address of the local interface to use in sending multicast datagrams. If 0, the default interface is used. |
|
19 |
Multicast TTL. Longword. Low byte contains the time-to-live (TTL) to be used in multicast datagrams to be transmitted. |
|
20 |
Multicast loopback. Longword. Low byte is 0 to disable and 1 to enable local loopback of multicast datagrams. |
Note! The above parameters remain set even after you close the port until you change them with another IO$_SETMODE operation
Status
|
SS$_BADPARAM |
Specified bad parameter or parameter value |
|
SS$_DEVACTIVE |
Port is open, and you made request to change parameter that cannot be changed when port is open |
|
SS$_DEVINACT |
Device is not active |
|
SS$_DUPINIT |
Multicast group address already joined |
|
SS$_INSFMEM |
Insufficient memory to complete request |
|
SS$_IVBUFLEN |
Extended characteristics buffer length invalid |
|
SS$_NOPRIV |
Setting IP layer options (PIDs 13 through 20) requires
privileges |
|
SS$_NORMAL |
Success |
|
SS$_TOOMUCHDATA |
Too many multicast group addresses specified |
|
SS$_UNREACHABLE |
No default interface for multicast group address could not
be found |
IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN
Closes a port.
Closing a port aborts all pending receives for the port, prevents further receives and transmissions on the port, and lets another user use the protocol number.
Format
status = SYS$QIO(efn, chan,IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN,iosb, astadr, astprm, 0, 0, 0, 0, 0, 0)
Arguments
None.
Status
|
SS$_DEVINACT |
Device not active |
|
SS$_NORMAL |
Success |
|
SS$_NOPRIV |
Insufficient privileges |
IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP
Opens a port. Opening a port lets you receive internet datagrams.
Requires BYPASS or SYSPRV privileges.
Format
status = SYS$QIO(efn, chan,IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP, iosb, astadr, astprm, 0, 0, protocol, num, 0, 0)
Arguments
p3=protocol
Internet protocol number in the low byte. Datagrams are transmitted using this protocol number, and you can only receive datagrams with it.
See the latest Assigned Numbers RFC for a list of the currently assigned protocol numbers.
p4=num
|
OpenVMS usage: |
longword_unsigned |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Number of unsolicited receives to be queued for delivery. A value of 0 to 5 is valid. 0 results in all unsolicited receives being discarded.
Status
|
SS$_DEVACTIVE |
Port already open |
|
SS$_DEVINACT |
Device not active |
|
SS$_DUPUNIT |
Specified port number already in use by another port |
|
SS$_NOPRIV |
Insufficient privileges |
|
SS$NORMAL |
Success |
IO$_WRITEVBLK
Sends data. This builds and transmits the datagram using the protocol number for the port.
The IO$M_NOFORMAT modifier prevents fragmentation. This sets the "don’t fragment" bit in the IP datagram.
The IO$M_FORCEPATH modifier prevents routing on the datagram. This limits the datagram to be sent to a locally connected address.
The IO$M_LPBEXT modifier inhibits a copy of a broadcast or multicast datagram from being looped back.
Format
status = SYS$QIO(efn, chan,IO$_WRITEVBLK,iosb, astadr, astprm, buffer, size, address, dest, source, 0)
Arguments
p1=buffer
|
OpenVMS usage: |
vector_byte_unsigned |
|
type: |
byte (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
User’s buffer address. This is the buffer that contains the data to be sent. The buffer does not include the internet header.
p2=size
|
OpenVMS Usage: |
word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
User’s buffer size in bytes (the byte count). This is the amount of data that the user has to send. The value should not be greater than 65000 bytes.
If the resulting datagram is larger than the maximum transmission unit (MTU) for the network, the datagram is fragmented, unless you specified IO$M_NOFORMAT. In that case, IO$_WRITEVBLK returns an error.
p3=address
|
OpenVMS usage: |
vector_word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by descriptor |
Address of the descriptor for the optional transmit characteristics buffer.
The transmit characteristics buffer consists of a series of 6-byte and counted string entries. The first word of each entry contains the parameter identifier (PID) followed either by a longword or by a counted string.
The PID determines whether a longword value or counted string follows. The longword contains one of the values that can be associated with that parameter. The counted string consists of a word byte count field followed by the specified number of bytes of data.
Figure 5-4 shows the format of the descriptor for the extended characteristics buffer and the extended characteristics buffer.
Table 5-7 lists the characteristics you can specify.
|
Table 5-7 P3 Transmit Characteristics |
|
|
PID |
Meaning |
|
1 |
Type of service. Low-order byte of the longword value. Contains the type of service. If omitted, the previously specified value or the default of 0 is used. |
|
2 |
Time to live. Low-order byte of the longword value field. Contains the time to live. If not specified, the previously specified value of the default is used. The default time to live is specified by the IPDEFAULTTTL parameter for non-multicast datagrams and is 1 for multicast datagrams. |
|
3 |
Identification. Low-order word of the longword value field. Contains the identification number. IPDRIVER automatically increments this value for each transmission (the initial value starts at 0). |
|
4 |
Options. Counted string. Contains the internet options buffer. This buffer is used as is and is not validated. The maximum size of this counted string is 40 bytes. Note that if the options are not a multiple of 4 bytes, IPDRIVER adds the required padding (using the End of Option List option). |
|
5 |
Protocol. Lowest-order byte of the longword value field. Contains the IP protocol number to be used in sending the datagram. Can be used to override the protocol under which this unit was opened. |
See the specifications for the Internet Protocol (RFC 791) for details on each of the internet header items described above.
p4=dest
|
OpenVMS usage: |
longword_unsigned |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Destination internet address. Internet addresses are specified in internet byte order (which is reversed from the normal VAX byte order). For example, internet address 2.3.4.5 is stored as ^X05040302. If the destination internet address is the loopback internet address, IPDRIVER loops-back the datagram.
p5=source
|
OpenVMS usage: |
longword_unsigned |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Optional source internet address. Must be a valid local internet address (if specified). Internet addresses are specified in internet byte order (which is reversed from the normal VAX byte order). For example, internet address 2.3.4.5 is stored as ^X05040302.
Status
|
SS$_BADPARAM |
Bad parameter or parameter value specified |
|
SS$_DEVINACT |
Device not active |
|
SS$_INSFMEM |
Insufficient memory available to fragment datagram |
|
SS$_INVSECLASS |
Basic Security Option label incompatible with outgoing IPSO settings |
|
SS$_IVBUFLEN |
User’s buffer too large |
|
SS$_NORMAL |
Success Failure of translation is not considered an error because
datagram would most likely be retransmitted by higher level software at a
later time |
|
SS$_OPINCOMPL |
Datagram not transmitted because no destination internet address or port number was specified by source/destination bugger or port’s characteristics |
|
SS$_THIRDPARTY |
TCPware shut down |
|
SS$_UNREACHABLE |
No route to the destination internet address exists |
The number of data bytes transmitted are returned in the high-order word of the first longword of the I/O status block.
SYS$ASSIGN
Assigns a channel to a device.
Format
status = SYS$ASSIGN (devnam, chan, [acmode], [mbxnam])
Arguments
devnam
|
OpenVMS usage: |
device_name |
|
type: |
character_coded text string |
|
access: |
read only |
|
mechanism: |
by descriptor-fixed length string descriptor |
Address of a character string descriptor pointing to the device name string (IPA0:).
chan
|
OpenVMS usage: |
channel |
|
type: |
word (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
Address of a word into which SYS$ASSIGN writes the channel number.
acmode
|
OpenVMS usage: |
access_mode |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Optional access mode associated with the channel. The most privileged access mode used is that of the caller.
mbxnam
|
OpenVMS usage: |
device_name |
|
type: |
character-coded text string |
|
access: |
read only |
|
mechanism: |
by descriptor-fixed length string descriptor |
Optional logical mailbox associated with the device. (Not supported by IPDRIVER)
Status
See HP’sVMS System Services Reference Manual for a complete list of status messages.
SYS$CANCEL
Cancels any I/O that is pending on a channel.
The I/O will be completed with an iosb status of SS$_CANCEL.
Outstanding I/O operations are automatically canceled at image exit.
Format
status = SYS$CANCEL (chan)
Argument
chan
|
OpenVMS usage: |
channel |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Number of the channel to be canceled.
Status
See HP’s VMS System Services Reference Manual for a complete list of status messages.
SYS$DASSGN
Releases a channel.
When you deassign a channel, any outstanding I/O is completed with an iosb status of SS$_CANCEL.
I/O channels are automatically deassigned at image exit.
Format
status = SYS$DASSGN (chan)
Argument
chan
|
OpenVMS usage: |
channel |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Number of the channel to be deassigned.
Status
See HP VMS System Services Reference Manual for a complete list of status messages.
IPDRIVER External Interface
This section describes the IPDRIVER External Interface.
This interface allows you to write Network Interface Programs that support the use of IPDRIVER with various network controllers.
I/O Functions for the External Interface
The Network Interface Program uses four functions to communicate with IPDRIVER. Table 5-8 lists these functions.
|
Table 5-8 I/O Functions for the External Interface |
|
|
Function |
Purpose |
|
IO$_INITIALIZE |
Initializes the IPDRIVER External Interface for the network device. (Informs IPDRIVER that the External Interface is on-line.) |
|
IO$_READVBLK |
Receives datagrams from IPDRIVER for transmission over the network. |
|
IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN |
Shuts down the IPDRIVER External interface. |
|
IO$_WRITEVBLK |
Delivers datagrams that are received from the network to IPDRIVER. IPDRIVER processes and delivers them to higher-level applications (such as TCP and UDP). |
Sequence of Operations for the Network Interface Program
This section provides the typical sequence of operations for the Network Interface Program. These operations apply only to the IPDRIVER External Interface. Any operations needed to set up and use the network device depend on the specific requirements of that device.
The Network Interface Program:
1 Uses the Assign I/O Channel (SYS$ASSIGN) system service to assign an I/O channel to IPA0:. SYS$ASSIGN creates a new unit for the channel.
2 Issues the IO$_INITIALIZE function on the assigned channel to initialize the network line.
3 Issues the IO$_READVBLK function to read IP datagrams from IPDRIVER, then sends the datagrams over the network device.
4 Issues the IO$_WRITEVBLK function for each datagram received from the network device.
5 Issues the IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN function to shut down the network device.
6 Uses the Deassign I/O Channel (SYS$DASSGN) system service to deassign the channel.
Your Network Interface programs must provide their own means of starting up and shutting down. You cannot use the NETCU START/IP and STOP/IP commands to start up or shut down these network lines.
IPDRIVER External Interface System Service Call Codes
The following pages describe each SYS$QIO[W] function code for the external interface. System service call function codes specify what action the QIO performs. See the format specified in the IPDRIVER System Service Call Format section before referencing each function.
You can use OpenVMS system services SYS$ASSIGN, SYS$DASSGN, and SYS$CANCEL for the External Interface in the same way as described for the User Interface in the IPDRIVER User Interface System Service Call Function Co section.
This section describes the following function codes for the External Interface:
|
IO$_INITIALIZE |
IO$_SETMODE |
IO$_READVBLK |
IO$_WRITEVBLK |
IO$_INITIALIZE (External)
Informs IPDRIVER that the External Interface is on-line. IPDRIVER adds the External Interface to a list of existing network interfaces and creates a route for it.
Note! Once a Network Interface program issues an IO$_INITIALIZE on a channel, that channel becomes the External Interface. After that, the functions documented in the IPDRIVER User Interface System Service Call Function Co section for the User Interface (such as those used to open and close ports) are no longer valid: you must use only those functions documented in this part of the chapter, theIPDRIVER External Interface section.
Format
status = SYS$QIO(efn, chan,IO$_INITIALIZE,iosb, astadr, astprm, buffer, size, 0, 0, 0, 0)
Arguments
p1=buffer
|
OpenVMS usage: |
vector_byte_unsigned |
|
type: |
byte (unsigned) |
|
access: |
read only |
|
mechanism: |
by reference |
Address of the line information buffer. Figure 5-5 illustrates this buffer.
In the figure:
|
address mask |
is the address mask for the network. The bits set in the mask are the bits that specify the host number (the one’s complement of the network mask). |
|
flags |
is the line’s flag bits. Typically, this value is 0, but the following bits can be set as needed: |
|
internet address |
is the internet address of the host on the network or, for unnumbered interfaces, the internet address used as the source address when sending datagrams over the interface if a source address was not explicitly specified. |
|
lineid |
is the line identification. Its value should be 00nnxx41 (hex), where: nn is the unit number of the line. xx is a unique value for the specific network line. SLIP lines are 01. IP-over-DECnet lines are 02. PPP lines are 03. For Network Interface Programs, nn should start at 80 (hex) and a |
|
mtu |
is the maximum transmission unit for the network. It is the size of the largest IP datagram that can be transmitted over the network. |
|
Bit |
Mask |
Meaning |
|
0 |
1 |
Unnumbered interface. If this bit is set, the interface does not have a local address and the internet address specified is only used when originating datagrams over the interface when no source address was explicitly specified. |
p2=size
|
OpenVMS usage: |
word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Size of the line information buffer, in bytes.
Status
|
SS$_NORMAL |
Initialization successful |
|
SS$_BADPARAM |
lineid parameter does not contain valid value, or
already in use |
|
SS$_DEVACTIVE |
Device already active |
|
SS$_DEVREQERR |
You are trying to start up new interface while IPDRIVER is in process of shutting down |
|
SS$INSFMEM |
Insufficient system memory |
|
SS$_IVADDR |
Address already in use |
|
SS$_NOPRIV |
Insufficient privileges |
IO$_READVBLK (External)
Requests IPDRIVER to return the next IP datagram to the Network Interface program. The Network Interface program should then send the datagram over the network.
The Network Interface program is responsible for adding the network header to the datagram.
IPDRIVER provides "unsolicited" read support. This means that datagrams are held in a queue until the Network Interface Program issues an IO$_READVBLK function. IPDRIVER queues up to 100 datagrams.
Format
status = SYS$QIO(efn, chan, IO$_READVBLK,iosb, astadr, astprm, buffer, size, 0, 0, 0, 0)
Arguments
p1=buffer
|
OpenVMS usage: |
vector_byte_unsigned |
|
type: |
byte (unsigned) |
|
access: |
write only |
|
mechanism: |
by reference |
Address of the buffer that receives the next IP datagram.
p2=size
|
OpenVMS usage: |
word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Size, in bytes, of the buffer. This buffer must be at least as large as the MTU of the interface and not greater than 65000 bytes. Otherwise, IPDRIVER might return a SS$_DATAOVERUN status code.
Status
|
SS$_NORMAL |
Read successful |
|
SS$_ABORT |
Requests aborted |
|
SS$_DATAOVERUN |
Receive buffer in Network Interface Program too small for
IP datagram |
|
SS$DEVINACT |
Device not active |
The high-order word of the first longword contains the size of the IP datagram read.
The second longword of the I/O status block contains the internet address of the next destination. The next destination can be the final destination or a gateway. This longword is valid only for the SS$_NORMAL and SS$_DATAOVERUN status codes.
IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN (External)
Shuts down the External Interface for the channel.
Causes IPDRIVER to remove the network interface from the list of available interfaces. It also removes any routes for the network interface.
Format
status = SYS$QIO(efn, chan,IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN,iosb, astadr, astprm, 0, 0, 0, 0, 0, 0)
Arguments
None.
Status
SS$_Normal Success
IO$_WRITEVBLK (External)
Used after the Network Interface program receives a datagram from the network. Delivers the datagram to IPDRIVER for processing.
Format
status = SYS$QIO(efn, chan,IO$_WRITEVBLK,iosb, astadr, astprm, buffer, size, 0, flags, 0, 0)
Arguments
p1=buffer
|
OpenVMS usage: |
vector_byte_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Address of the buffer containing the full IP datagram.
p2=size
|
OpenVMS usage: |
word_unsigned |
|
type: |
word (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Size of the IP datagram in bytes. The value should not be greater than 65000 bytes.
Note! The buffer specified by these parameters must not include the network header.
p4=flags
|
OpenVMS usage: |
mask_longword |
|
type: |
longword (unsigned) |
|
access: |
read only |
|
mechanism: |
by value |
Flag bits providing information about the received datagram as follows:
|
Bit |
Mask |
Meaning |
|
0 |
1 |
Datagram was sent to a broadcast/multicast address. This information is used to prevent sending ICMP datagrams to broadcast/multicast addresses. All other bits must be 0. |
Status
|
SS$_NORMAL |
Write successful |
|
SS$_ABORT |
Request aborted |
|
SS$_DEVINACT |
Device not active |