## TCPware V5.7 Programmer's Guide

- Introduction
- Sequence of Operations
- Other Operations
- Internet Protocol Implementation Notes
- IPDRIVER System Service Call Format
- IPDRIVER System Service Call Arguments
- IPDRIVER User Interface System Service Call Function Codes
  - Reading Extended Characteristics
  - Reading Network Device Information
  - Reading the Routing Table
  - Reading the ARP Table Function
- IPDRIVER External Interface
  - I/O Functions for the External Interface
  - Sequence of Operations for the Network Interface Program
  - IPDRIVER External Interface System Service Call Codes

Chapter 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 nooutstanding 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.

Figure 5-1 IPDRIVER User and External Interfaces see graphic

# 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 can not 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.

Figure 5-2 I/O Status Block see graphic

Table 5-1 describes the status block fields in more detail.

Table 5-1 I/O Status Block Fields

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 datagramTruncated datagram is returnedRemainder of datagram is lost
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 | SuccessDatagram received

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 (Continued)

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 IdBytes TransmittedBytes Received 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 Routing Table 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.

Table 5-3 Extended Characteristics (Continued)

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. Table5-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 (Continued)

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 Table5-5.

Table 5-5 ARP Table Entry Flag Bits (Continued)

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 informationTruncated buffer returned.
SS$_DEVINACT | Device not activeContact your system manager to determine why TCPware was not started
SS$_NORMAL | SuccessRequested 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 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 characteristicsTruncated characteristics buffer returned
SS$_NOPRIV | Insufficient privilegeOPER privilege required to zero counters

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.

Figure 5-3 P2 Set Characteristics Buffer see graphic

Table 5-6 lists the port characteristics you can set.

Table 5-6 P2 Set Port Characteristics (Continued)

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 valueReturns PID in low order word of second longword
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 activeContact your system manager to determine why TCPware (or IPDRIVER) was not started
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 privilegesApplication must either be running under SYSTEM UIC or have SYSPRV, BYPASS, or OPER privilege
SS$_NORMAL | SuccessCharacteristics set
SS$_TOOMUCHDATA | Too many multicast group addresses specified
SS$_UNREACHABLE | No default interface for multicast group address could not be foundSpecify local interface’s IP address when joining multicast group

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 activeContact your system manager to determine why TCPware (or IPDRIVER) was not started
SS$_NORMAL | SuccessPort now ( or was) closedPort can no longer receive any datagrams; however, datagrams can still be sent
SS$_NOPRIV | Insufficient privilegesBYPASS or SYSPRV privilege required to open port

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 activeContact your system manager to determine why TCPware was not started
SS$_DUPUNIT | Specified port number already in use by another port
SS$_NOPRIV | Insufficient privilegesYou need BYPASS or SYSPRV privilege to open port
SS$NORMAL | SuccessPort open and write and read functions can be used to transmit or receive datagrams

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.

Figure 5-4 P3 Transmit Characteristics Buffer see graphic

Table 5-7 P3 Transmit Characteristics (Continued)

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 specifiedPID returned in low order word of second longwordIf parameter ID is 0, source internet address is not valid (it is not local address)
SS$_DEVINACT | Device not activeContact your system manager to determine why TCPware (or IPDRIVER) was not started
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 | SuccessDatagram transmitted Failure of translation is not considered an error because datagram would most likely be retransmitted by higher level software at a later timeAlso allows some time for ARP reply to be received
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 existsAdd route for destination or check internet address

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 (Continued)

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 Codes section.

This section describes the following function codes for the External Interface:

IO$_INITILIZE | 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 Codes 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, the IPDRIVER 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.

Figure 5-5 Line Information Buffer for IO$_INITIALIZE see graphic

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 useLowest order byte must be 41 (hex) for External Interface
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 memoryNecessary control block cannot be allocated
SS$_IVADDR | Address already in use
SS$_NOPRIV | Insufficient privilegesYou need OPER privilege to start network interface

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 successfulIn I/O status block, high order word of first longword contains size of IP datagram in bytes
SS$_ABORT | Requests abortedExternal Interface is down
SS$_DATAOVERUN | Receive buffer in Network Interface Program too small for IP datagramTruncated datagram returned to user-specified bufferIn I/O status block high order word of first longword contains truncated size of IP datagram in bytes
SS$DEVINACT | Device not activeUse IO$_INITIALIZE function first

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 abortedExternal Interface shut down
SS$_DEVINACT | Device not activeUse IO$_INITIALIZE function first