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 the below figure 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 IP Version 4, 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]( u_long efn, u_int chan, u_long func, unsigned quadword *iosb, void *astadr, u_long 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

Number of the event flag set by completion of the I/O operation. The argument is optional.

 

chan

I/O channel assigned to the IP device to which you are directing the request.

 

func

Device-specific function code and the modifier, if appropriate, for each operation.

 

iosb

I/O status block that receives the final completion status of the I/O operation, structured as in the below figure.

The below table 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

Address of the asynchronous system trap (AST) routine executed when the I/O is completed.

 

astprm

AST parameter to be passed to the AST routine.

 

p1…p6

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 = byte *buffer

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 = u_int size

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
Truncated datagram is returned
Remainder 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

Success
Datagram 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 = byte *buffer

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 = u_int *address

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 = u_long function

Code that designates the function. The function codes are shown in the below table.

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
Bytes Transmitted
Bytes 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 = u_long line-id

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 the below table.

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 0, 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. The following table shows the line identification values

7

Address mask.

Address mask for the destination address. Returned as a longword value.

8

Path MTU.

Path maximum transmission unit. Returned as a longword value.

 

Line ID 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 the following table.

 

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 host’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
Truncated buffer returned.

SS$_DEVINACT

Device not active
Contact your system manager to determine why TCPware 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 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 = byte *buffer

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 = u_long *address

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

SS$_NOPRIV

Insufficient privilege
OPER 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 = u_int *address

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. The below diagram shows the format of the descriptor for the extended characteristics buffer and the extended characteristics buffer.

The below table 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
Returns 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 active
Contact 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 privileges
Application must either be running under SYSTEM UIC or have SYSPRV, BYPASS, or OPER privilege

SS$_NORMAL

Success
Characteristics set

SS$_TOOMUCHDATA

Too many multicast group addresses specified

SS$_UNREACHABLE

No default interface for multicast group address could not be found
Specify 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 active
Contact your system manager to determine why TCPware (or IPDRIVER) was not started

SS$_NORMAL

Success
Port now ( or was) closed
Port can no longer receive any datagrams; however, datagrams can still be sent

SS$_NOPRIV

Insufficient privileges
BYPASS 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 = u_int 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 = u_long num

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
Contact your system manager to determine why TCPware was not started

SS$_DUPUNIT

Specified port number already in use by another port

SS$_NOPRIV

Insufficient privileges
You need BYPASS or SYSPRV privilege to open port

SS$NORMAL

Success
Port 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 = byte *buffer

User’s buffer address. This is the buffer that contains the data to be sent. The buffer does not include the internet header.

 

p2 = u_int size

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 = u_int address

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.

The below diagram shows the format of the descriptor for the extended characteristics buffer and the extended characteristics buffer.

The following table lists the characteristics you can specify.

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 = u_long dest

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 = u_long source

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
PID returned in low order word of second longword
If parameter ID is 0, source internet address is not valid (it is not local address)

SS$_DEVINACT

Device not active
Contact 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

Success
Datagram transmitted

Failure of translation is not considered an error because datagram would most likely be retransmitted by higher level software at a later time
Also 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 exists
Add 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 (char *devnam, word *chan, [u_long acmode], [char *mbxnam]);

 

Arguments

 

devnam

Address of a character string descriptor pointing to the device name string (IPA0:).

 

chan

Address of a word into which SYS$ASSIGN writes the channel number.

 

acmode

Optional access mode associated with the channel. The most privileged access mode used is that of the caller.

 

mbxnam

Optional logical mailbox associated with the device. (Not supported by IPDRIVER)

 

Status

See the VMS 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(u_int chan);

 

Argument

 

chan

Number of the channel to be canceled.

 

Status

See the 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(u_int chan);

 

Argument

 

chan

Number of the channel to be deassigned.

 

Status

See the 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. The below table lists these functions.

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 Functions 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.

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 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 = byte *buffer

Address of the line information buffer. The below diagram 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).

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 = u_int size

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
Lowest 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 memory
Necessary control block cannot be allocated

SS$_IVADDR

Address already in use

SS$_NOPRIV

Insufficient privileges
You 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 = byte *buffer

Address of the buffer that receives the next IP datagram.

 

p2 = u_int size

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
In I/O status block, high order word of first longword contains size of IP datagram in bytes

SS$_ABORT

Requests aborted
External Interface is down

SS$_DATAOVERUN

Receive buffer in Network Interface Program too small for IP datagram
Truncated datagram returned to user-specified buffer
In I/O status block high order word of first longword contains truncated size of IP datagram in bytes

SS$DEVINACT

Device not active
Use 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 = byte *buffer

Address of the buffer containing the full IP datagram.

 

p2 = u_int size

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 = u_long flags

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
External Interface shut down

SS$_DEVINACT

Device not active
Use IO$_INITIALIZE function first