## TCPware V5.7 Programmer's Guide

- Introduction
- Sequence of Operations
- Other Operations
- User Datagram Protocol Implementation Notes
- UDPDRIVER System Service Call Format
- UDPDRIVER System Service Call Arguments
- UDPDRIVER System Service Call Function Codes
  - Status
- Sample Programs
  - C Programs
  - FORTRAN Program
    - VAX
    - Alpha and I64

Chapter 4

UDPDRIVER Services

# Introduction

This chapter describes the User Datagram Protocol (UDP) device driver (UDPDRIVER) services. It describes the user interface of TCPware for the OpenVMS UDP implementation only. RFC 768 contains the protocol specification for UDP.

UDP allows an application on one machine to send a datagram to an application on another machine. The datagram includes a protocol port number that identifies the receiving application from among other applications executing on the remote machine.

The UDP protocol is transaction-oriented so it does not guarantee reliable delivery of data. If your applications require ordered and reliable delivery of data, you should use TCP.

UDP services are available through the OpenVMS Queue I/O (SYS$QIO and SYS$QIOW) system services. These system services:

• Open and close a port.

• Send and receive data over the port.

• Perform status checks on the port.

SYS$QIOW is the synchronous and SYS$QIO the asynchronous form of VMS system services. Use each form depending on your application's requirements.

See the appropriate OpenVMS documentation for details on the OpenVMS I/O system services and related services such as asynchronous system traps (ASTs) and event flags.

Note! The QIO calls described in this chapter are used for direct access to the UDPDRIVER. If you are porting an application that uses the BGDRIVER or INETDRIVER QIO interface, there may be no need to make modifications. Use TCPware's BGDRIVER (see Chapter 2) or INETDRIVER (see Chapter 7).

# Sequence of Operations

Perform the following sequence of operations to open a port:

1 Assign an I/O channel to the UDP0: device using 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 services.

3 Perform read requests with the IO$_READVBLK function and write requests with the IO$_WRITEVBLK function 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.

# Other Operations

In addition to the sequence of operations described in the preceding section, UDPDRIVER includes other operations that:

Read a datagram immediately with | IO$_READVBLK | IO$M_NOW
Read the next received message without removing it from the received message queue with | IO$_READVBLK | IO$M_DATACHECK
Suppress checksum generation at the UDP level with | IO$_WRITEVBLK | IO$M_NOFORMAT
Request a list of buffers to be sent as a single datagram with each request with | IO$_WRITEVBLK | IO$M_EXTEND
Read the open ports status with | IO$_SENSEMODE
Read the port characteristics with | IO$_SENSEMODE | IO$M_CTRL
Read the UDP counters with | IO$_SENSEMODE | IO$M_RD_COUNT
Clear these UDP counters after they have been read with | IO$_SENSEMODE | IO$M_RD_COUNT | IO$M_CLR_COUNTYou must have OPER privilege to clear the counters.
Cancel any pending I/O requests with | SYS$CANCEL

# User Datagram Protocol Implementation Notes

There are no implementation specific restrictions for the User Datagram Protocol (UDP). The material presented here does not explain or describe the UDP protocol.

# UDPDRIVER System Service Call Format

The format for the UDPDRIVER 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 and SYS$QIOW are used to issue UDP 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 bit-wise inclusive OR operator.

# UDPDRIVER System Service Call Arguments

You invoke UDPDRIVER 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

Channel assigned to the UDP 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! UDPDRIVER System Service Call Function Codes describes each func.

iosb

OpenVMS usage: | io_status_block
type: | quadword (unsigned)
access: | write only
mechanism: | by reference

I/O status block that receives the final completion status of the I/O operation, structured as in Figure 4-1.

Figure 4-1 I/O Status see graphic

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

Table 4-1 I/O Status Block Fields

Field Name | Description
Transfer Byte Count | Number of bytes of data transferred in the I/O operation.
Status Code | SS$ status code or special error status code. If the low bit (0) of the OpenVMS error code is clear, the network has returned an error.
Function-Specific | Varies for each function code.

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.

# UDPDRIVER System Service Call Function Codes

System service call function codes specify what action the QIO performs. This section describes the following function codes:

IO$_READVBLK | IO$_WRITEVBLK | IO$M_EXTEND
IO$_WRITEVBLK | IO$_SENSEMODE | IO$M_RD_COUNT
IO$_SENSEMODE | IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP
IO$_SETMODE | IO$M_CTRL | IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN
IO$_SENSEMODE | IO$M_CTRL |

IO$_READVBLK

Receives a datagram. The received datagram is written to the specified user buffer.

Use the IO$M_NOW modifier to execute the function immediately regardless of the amount of available data. If no data is available, the function returns SS$_NODATA status.

Use the IO$M_DATACHECK modifier with a read request to peek at the next received message without removing it from the received message queue.

Unless you set a local internet address (see Table 4-3), datagrams sent to any local interface address, any local broadcast address (TCPware supports both the standard -1 and nonstandard 0 broadcast address forms), or any joined multicast host group address are eligible to be received.

Note! UDPDRIVER holds a maximum of five unsolicited datagrams. It is good programming practice to have a read request pending for incoming datagrams.

Format

status = SYS$QIO(efn, chan, IO$_READVBLK, iosb, astadr, astprm, buffer, size, udp_address, 0, 0, receive_timeout)

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

p2=size

OpenVMS usage: | word_unsigned
type: | word (unsigned)
access: | read only
mechanism: | by value

Length (in bytes) of the buffer to which the address argument points. This is the amount of data the user is willing to receive. The value must be at least 20 and at most 64000 bytes.

p3=udp_address

OpenVMS usage: | vector_longword_unsigned
type: | longword (unsigned)
access: | write only
mechanism: | by reference

Address of an optional 4-longword buffer. Receives the source and destination IP addresses and UDP port numbers from the received datagrams. Figure 4-2 shows the buffer format.

Figure 4-2 Read Function P3 Buffer Format see graphic

Note! IO$_READVBLK returns the source and destination internet addresses in internet byte order, which is reversed from the normal VMS byte order. For example, internet address 2.3.4.5 is stored as ^X05040302.

p6=receive_timeout

OpenVMS usage: | longword_unsigned
type: | longword (unsigned)
access: | read only
mechanism: | by value

Contains the receive time-out time (in seconds). If this value is non-zero, the SS$_TIMEOUT status is returned if a datagram isn't received within this time.

Status

SS$_ABORT | Request aborted due to closed connection
SS$_BUFFEROVF | User's buffer too small for entire datagramTruncated datagram is returnedRemainder of datagram is lost
SS$_CANCEL | Request cancelled
SS$_DEVINACT | Device is not active or port not opened
SS$_NODATA | No datagram available and IO$M_NOW was specified
SS$_NORMAL | SuccessDatagram received
SS$_THIRDPARTY | Port closed by third partyUsually indicates that TCPware was shut down.
SS$_TIMEOUT | Receive time out time specified and no datagram received within allowed time

The number of bytes received are returned in the high-order word of the first longword of the I/O status block. This may be less than the bytes requested.

IO$_SENSEMODE

Reads the active ports status and returns status information for all of the open UDPDRIVER ports.

Format

status = SYS$QIO(efn, chan, IO$_SENSEMODE, 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 (DS$_SCOM) in the first byte, the device type (0) in the second byte, and the default buffer size, which is the maximum datagram size, in the high-order word of the first longword. IO$_SENSEMODE returns the second longword as 0.

p2=address

OpenVMS usage: | vector_word_unsigned
type: | word (unsigned)
access: | write only
mechanism: | by descriptor

Address of the descriptor for the buffer to receive the status information on the open ports. The buffer receives 22 bytes of information for each open UDP port. Figure 4-3 shows the 22 bytes of status information returned.

Figure 4-3

P2 Status Information see graphic

Protocol type | Word value is 3 for UDPDRIVER ports, 4 for INETDRIVER datagram sockets, and 5 for BGDRIVER datagram sockets.
Unit number | Word value is the UDPDRIVER, INETDRIVER or BGDRIVER device unit number for the port.
Receive queue | Word value is the number of bytes received on the port waiting to be delivered to the user (via the read function).
Send queue | Word value is the number of bytes waiting to be transmitted for the port.
Local internet address | Longword value is the local internet address specified for the opened port. 0 means that none was specified.
Local port number | Word value is the local port number for the opened port.
Peer internet address | Longword value is the peer's internet address for a fully specified opened port. 0 means the port is not fully specified.
Peer port number | Word value is the peer's port number for a fully specified opened port. 0 means the port is not fully specified.

## Status

SS$_BUFFEROVF | Buffer too small for all connectionsTruncated buffer returned
SS$_DEVINACT | Device not activeContact your system manager to determine why TCPware (or UPDRIVER) was not started
SS$_NORMAL | SuccessStatus information returned

The byte count for the status information buffer is returned in the high-order word of the first longword of the I/O status block. This may be less than the bytes requested. See Figure 4-4 for more information.

The size in bytes of each connection's record (22 bytes) is returned in the low order word of the second longword of the I/O status block.

The total number of active connections is returned in the high-order word of the second longword of the I/O status block. This can be greater than the number of reported connections if the buffer is full.

Figure 4-4 I/O Status Block see graphic

IO$_SENSEMODE | IO$M_CTRL

Reads the port characteristics for the channel.

Format

status = SYS$QIO(efn, chan, IO$_SENSEMODE | IO$M_CTRL, 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, which is the maximum datagram size, in the high-order word of the first longword. IO$_SENSEMODE returns the second longword as 0.

p2=address

OpenVMS usage: | vector_word_unsigned
type: | word (unsigned)
access: | write only
mechanism: | by descriptor

Address of the descriptor for the extended characteristics buffer to receive the characteristics. The information returned in the buffer is formatted the same as the extended characteristics buffer used to set the connection characteristics. See the IO$_SETMODE function description for more information.

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.

Table 4-2 lists the port characteristics that the function returns.

Table 4-2 P2 Port Characteristics

PID | Meaning
0 | Local internet or multicast address. Internet or multicast address is returned as the longword value. Last specified value or 0 is returned.
1 | Local port number. Port number is returned in the low order word of the longword value. Local port number is either the default port number or the last specified local port number.
2 | Peer internet address. Internet address is returned as the longword value. Last specified value or 0 is returned.
3 | Peer port number. Port number is returned in the low order word of the longword value. Last specified value or 0 is returned.
5 | Port datagram size. Maximum datagram size (in bytes) is returned as the longword value.
6 | Port state. Longword value is 0 if the port is not open and 1 if the port is open.
7 | Shared access control. Longword value is 0 if the port is set for exclusive access and 1 if the port is set for shared access.
10 | Socket options. For the values of this option, see the socket options entry in Table4-3.
14 | IP TTL. Longword. Low byte 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 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 order in which IO$_SENSEMODE | IO$M_CTRL returns the parameters can change. It is recommended that you search the buffer for the desired parameter.

Status

SS$_BUFFEROVF | Buffer too small for all connectionsTruncated characteristics buffer returned
SS$_DEVINACT | Device not activeContact your system manager to determine why TCPware (or UPDRIVER) was not started
SS$_NORMAL | SuccessCharacteristics returned

The byte count for the characteristics buffer is returned in the high-order word of the first longword of the I/O status block. This may be less than the bytes requested.

The number of bytes in the receive queue is returned in the low order word of the second longword in the I/O status block.

Note! You can use the SYS$GETDVI system service to obtain the local port number, peer port number, and peer internet address. The DEVDEPEND field stores the local port number (low order word) and peer port number (high-order word). The DEVDEPEND2 field stores the peer internet address.

IO$_SENSEMODE | IO$M_RD_COUNT

Reads the UDP counters. You can add the IO$M_CLR_COUNT modifier to this function to zero the counters after they are read. However, you must have the OPER privilege to use this modifier.

Format

status = SYS$QIO(efn, chan, IO$_SENSEMODE | IO$M_RD_COUNT, iosb, astadr, astprm, 0, address, 0, 0, 0, 0)

Argument

p2=address

OpenVMS usage: | vector_longword_unsigned
type: | longword (unsigned)
access: | write only
mechanism: | by descriptor

Address of the descriptor for the buffer that receives the counters. These counters relate only to the UDP level and are for all ports since the counters were last zeroed. The counters in the order they are returned:

1 Number of seconds since last zeroed

2 Number of datagrams transmitted

3 Number of datagrams transmitted with transmission errors

4 Number of datagrams received

5 Number of datagrams received in error (invalid UDP header or checksum)

6 Number of datagrams that were discarded because they could not be delivered to a receiver

All counters are longword values. All counters stop at their maximum value instead of overflowing.

Status

SS$_BUFFEROVF | Buffer too small for all connectionTruncated buffer returned
SS$_DEVINACT | Device not activeContact your system manager to determine why TCPware (or UPDRIVER) was not started
SS$_NORMAL | Success, Counters returned

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 of that characteristic, or a counted string. Counted strings consist of a word with the size of the character string, followed by the character string.

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

The address argument is the address of the extended characteristics buffer's descriptor. Figure 4-5 shows the format of the extended characteristics buffer and its descriptor.

Figure 4-5 P2 Set Characteristics Buffer see graphic

Table 4-3 lists the port characteristics you can set. The characteristics remain set, even after you close the port, until you change them with another IO$_SETMODE operation.

Table 4-3 P2 Set Port Characteristics (Continued)

PID | Meaning
0 | Local internet address. Longword with the local host's internet or multicast address. If used, must be a valid local internet or multicast address. Set this parameter only if the port is not open. Specify in internet byte order, reversed from the normal VMS byte order. For example, internet address 2.3.4.5 is stored as ^X05040302. To determine if an internet address is local, issue an IO$_SETMODE | IO$M_CTRL function specifying the address in this characteristic. If the address is not local, the function returns an SS$_BADPARAM status.
1 | Local port number. Low order word of the longword containing the port number. If omitted, the function uses the unique port number generated when you assign the UDP device unit. Set this parameter only if the port is not open. If you use 0, the function generates a new, unique number. Specify in normal VMS byte order.
2 | Peer internet address. Longword with the peer host's internet address. If you specify both the peer's internet address and port number after opening the port (or when the port is opened) the port is considered fully specified (or opened as fully specified) and all further receive requests receive datagrams from that address and port only. Transmitted requests that do not provide a source/destination buffer are sent to that address and port. Specify in internet byte order, as the local internet address characteristic above. Using 0 functionally omits the address.
3 | Peer port number. Low order word of the longword containing the port number. (See PID 2 above.) Specify in normal VMS byte order. Using 0 functionally omits the port number.
7 | Shared access control. Longword that specifies whether others can (shared access) or cannot (exclusive access) use the same local port number. For shared access (used primarily by servers), the value must be non-zero. You can open any number of ports on the local port number. Received datagrams are placed in a common queue so that the first receive on any of these opened ports returns the next datagram. For exclusive access (the default), the longword value must be 0.
9 | Change ownership. Longword that allows the current owner of the device unit to prepare to pass ownership to another process. Removes the owner's process ID from the connection. If the value field is non-zero, specifies the new owner UIC for the connection and changes the connection protection so that only system and owner have access (S:RWLP,O:RWLP). Changes the following fields for the connection: owner process ID, owner UIC, and device protection. Primarily the NETCP master server but also other programs use it.
10 | Set socket options. Low order word of the longword value field containing the mask value of the socket options to set. Specify the following options, as defined in the TCPWARE_INCLUDE:SOCKET.H header file (the values are in hexadecimal): SO_DEBUG, with a value of 0001, enables debugging (ignored) SO_REUSEADDR, with a value of 0004, allows reuse of local address (controllable through the passive open access control parameter SO_KEEPALIVE, with a value of 0008, keeps connections alive SO_DONTROUTE, with a value of 0010, prevents routing (ignored) SO_BROADCAST, with a value of 0020, enables use of broadcasts (ignored) SO_USELOOPBACK, with a value of 0040, bypasses hardware when possible (ignored)
11 | Clear socket options. Low order word of the longword value field containing the mask of the socket options to clear. (See the options under PID 10 above.)
13 | IP options. Counted string containing the IP options to be included in datagrams.
14 | IP TTL. Low byte of the longword containing the time-to-live (TTL) for datagrams.
15 | IP TOS. Low byte of the longword containing the type of service (TOS) for datagrams.
16 | Join multicast group. Counted string of eight bytes of which the first longword contains the multicast group IP address to join, and the 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. Counted string of eight bytes of which the first longword contains the multicast group IP address to leave, and the last longword contains the IP address of the local interface from which to leave the group. If 0, the default interface is used.
18 | Multicast interface. Longword with the IP address of the local interface to use in sending multicast datagrams. If 0, the default interface is used.
19 | Multicast TTL. Longword of which the low byte contains the time-to-live (TTL) for multicast datagrams transmitted.
20 | Multicast loopback. Longword of which the low byte is 0 to disable, or 1 to enable local loopback of multicast datagrams.

Status

SS$_BADPARAM | Bad parameter or value specifiedPID returned in low order word of second longword
SS$_DEVACTIVE | Port is open, and you made a request to change a parameter that cannot be changed when the port is open
SS$_DEVINACT | Device not activeContact system manager why TCPware (or TCPDRIVER) not started
SS$_DUPUNIT | 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 | 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 previously opened port.

After you issue this modifier any received datagrams are discarded.

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 system manager why TCPware (or TCPDRIVER) not started
SS$_NORMAL | SuccessPort is now (or was) closedPort can no longer receive datagrams; however, datagrams can still be sent

IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP

Opens a new receive port. When opening a new receive port, you have a choice of either fully or partially specifying the port characteristics.

To open a fully specified port, you must specify both the peer's internet address and port number. UDPDRIVER then delivers only datagrams received from that address and port and destined for the local port number.

To open a partially specified port, do not specify the peer's internet address and port number. UDPDRIVER then delivers all datagrams destined for the local port number, except those to be delivered to fully specified ports for the same local port number. You can convert a partially specified port into a fully specified port by issuing a IO$_SETMODE | IO$M_CTRL function and specifying both the peer's internet address and port number.

Format

status = SYS$QIO(efn, chan, IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP, 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

Address of the descriptor for the extended characteristics buffer. See the previous IO$_SENSEMODE | IO$M_CTRL function description for details on the extended characteristics buffer.

Note! You only need to open ports if you are to receive datagrams. You can send datagrams whether or not you open the port.

Status

SS$_BADPARAM | Bad parameter or value specifiedPID returned in low order word of second longword
SS$_DEVACTIVE | Port is already open
SS$_DEVINACT | Device not activeContact system manager why TCPware (or TCPDRIVER) not started
SS$_DUPUNIT | Specified port number is already in use by another user, and that user or you did not request shared access
SS$_NOPRIV | Insufficient privilegeProgram tried to open local port below 1024, but program does not have BYPASS or SYSPRV privilege
SS$_NORMAL | SuccessPort is open and ready for receives
SS$_THIRDPARTY | Port closed by third partyUsually indicates that TCPware was shut down.

IO$_WRITEVBLK

Sends a datagram stored in a single user buffer.

The IO$M_NOFORMAT modifier suppresses checksum generation at the UDP level.

Format

status = SYS$QIO(efn, chan, IO$_WRITEVBLK, iosb, astadr, astprm, buffer, size, address, 0, 0, 0)

Arguments

p1=buffer

OpenVMS usage: | vector_byte_unsigned
type: | byte (unsigned)
access: | read only
mechanism: | by reference

Address of the buffer that contains the data to be sent.

p2=size

OpenVMS usage: | word_unsigned
type: | word (unsigned)
access: | read only
mechanism: | by value

User's buffer size in bytes (the byte count), which is the amount of data that the user is sending. The value should not be greater than 64000 bytes.

p3=address

OpenVMS usage: | longword_unsigned
type: | longword (unsigned)
access: | read only
mechanism: | by value

Address of the optional 4-longword source/destination buffer. The source and destination internet address and port number specified in this buffer are used to transmit the datagram.

Figure 4-6 shows the buffer format.

Figure 4-6 Write Function Address Buffer Format see graphic

You can use any destination port. You can specify the source internet address, which must be a valid local address, or specify it as 0. When you specify the address as 0, UDPDRIVER supplies the appropriate local internet address. You must specify internet addresses in internet byte order, which is reversed from the normal VMS byte order. For example, internet address 2.3.4.5 is stored as ^X05040302.

If you do not specify the address buffer or if fields in this buffer are 0, UDPDRIVER uses the port's characteristic values set using the IO$_SETMODE | IO$M_CTRL or IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP functions for the unspecified fields.

To broadcast a datagram, you must either specify the source address and a destination address of 255.255.255.255, or specify a local network's broadcast address. The local network's broadcast address is an address with all bits set (or cleared) for the host number portion of the internet address.

Status

SS$_DEVINACT | Device not activeContact system manager why TCPware (or TCPDRIVER) not started
SS$_IVBUFLEN | User's buffer too large
SS$_NORMAL | SuccessDatagram was transmitted
SS$_OPINCOMPL | Datagram not transmitted because no destination internet address or port number was specified by source/destination buffer or port's characteristics
SS$_THIRDPARTY | TCPware shut down
SS$_UNREACHABLE | No route to specified destination internet address

The number of bytes sent are returned in the high-order word of the first longword of the I/O status block.

IO$_WRITEVBLK | IO$M_EXTEND

Sends a datagram stored in an array of buffers.

The IO$M_NOFORMAT modifier suppresses checksum generation at the UDP level.

Format

status = SYS$QIO(efn, chan, IO$_WRITEVBLK | IO$M_EXTEND, iosb, astadr, astprm, msghdr, size, 0, 0, 0, 0)

Arguments

p1=msghdr

OpenVMS usage: | vector_longword_unsigned
type: | longword (unsigned)
access: | read only
mechanism: | by reference

Address of the msghdr structure. Points to the address of the structure storing the array of additional structures. Each of these array structures contains the address and size of one of the user buffers.

p2=size

OpenVMS usage: | longword_unsigned
type: | longword (unsigned)
access: | read only
mechanism: | by value

Size of the msghdr structure. The size must be 24 bytes.

For details on the msghdr structure and an example of using the scatter-gather write function, see Chapter 3, TCPDRIVER Services.

Status

SS$_DEVINACT | Device not activeContact system manager why TCPware (or TCPDRIVER) not started
SS$_IVBUFLEN | User's buffer too large
SS$_NORMAL | SuccessDatagram was transmitted
SS$_OPINCOMPL | Datagram not transmitted because no destination internet address or port number was specified by source/destination buffer or port's characteristics
SS$_THIRDPARTY | TCPware shut down
SS$_UNREACHABLE | No route to specified destination internet address

The number of bytes sent 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 (UDP0:).

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.

Status

See Computer's 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 cancelled 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’s VMS System Services Reference Manual for a complete list of status messages.

# Sample Programs

## C Programs

The following sample programs, which show the use of SYS$QIO system service calls to the UDPDRIVER to set up a DISCARD client and server, are included in the TCPWARE_COMMON:[TCPWARE.EXAMPLES] directory:

• UDPDRIVER_CLIENT.C

• UDPDRIVER_SERVER.C

The client sequence of operations is as follows:

1 Assigns an I/O channel to UDP0, using SYS$ASSIGN.

2 Sends data using $QIO with IO$_WRITEVBLK.

3 Deassigns the channel, using SYS$DASSGN.

The server sequence of operations is as follows:

1 Assigns an I/O channel to UDP0, using SYS$ASSIGN.

2 Opens a receive port, using $QIO(IO$_SETMODE | IO$M_CTRL | IO$M_STARTUP).

3 Exchanges data, using $QIO(IO$_WRITEVBLK) and $QIO(IO$_READVBLK).

4 Closes the port, using $QIO(IO$_SETMODE | IO$M_CTRL | IO$M_SHUTDOWN).

5 Deassigns the channel, using SYS$DASSGN.

To build any one of these applications using DEC C, enter:

$ CC/DECC/PREFIX=ALL filename
$ LINK filename
Ctrl/Z

To build any one of these applications using VAX C, enter:

$ CC/VAXC filename
$ LINK filename, TCPWARE:UCX$IPC/LIB, SYS$INPUT/OPTIONS-
_$ SYS$SHARE:VAXCRTL/SHARE
Ctrl/Z

## FORTRAN Program

The TCPWARE_COMMON:[TCPWARE.EXAMPLES] directory also includes a UDPSAMPLES.FOR FORTRAN language file that transmits or receives data. This program links to the TCPware Socket Library as follows:

### VAX

$ FORTRAN TCPWARE_ROOT:[TCPWARE.EXAMPLES]UDPSAMPLE
$ LINK UDPSAMPLE, SYS$INPUT/OPTIONS
SYS$SHARE:TCPWARE_SOCKLIB_SHR/SHARE
Ctrl/Z

### Alpha and I64

$ FORTRAN/NOALIGN TCPWARE_ROOT:[TCPWARE.EXAMPLES]UDPSAMPLE
$ LINK UDPSAMPLE, SYS$INPUT/OPTIONS
SYS$SHARE:TCPWARE_SOCKLIB_SHR/SHARE
Ctrl/Z