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_COUNT You 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](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 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

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

chan

Channel assigned to the UDP 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
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

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.

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

Address of the user's buffer that receives the data.

p2 = u_int size

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

p3 = u_long *udp_address

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

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

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 datagram Truncated datagram is returned Remainder 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	Success Datagram received
SS$_THIRDPARTY	Port closed by third party Usually 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 = byte *buffer

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

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. The below figure shows the 22 bytes of status information returned.

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 connections Truncated buffer returned
SS$_DEVINACT	Device not active Contact your system manager to determine why TCPware (or UPDRIVER) was not started
SS$_NORMAL	Success Status information returned

The byte count for the status information buffer is returned in the high-order word of the first longword of the I/O status block. This may be less than the bytes requested. See the below figure 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.

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

p2 = u_int address

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.

The below table lists the port characteristics that the function returns.

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.
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 connections Truncated characteristics buffer returned
SS$_DEVINACT	Device not active Contact your system manager to determine why TCPware (or UPDRIVER) was not started
SS$_NORMAL	Success Characteristics returned

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

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

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

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 connection Truncated buffer returned
SS$_DEVINACT	Device not active Contact 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 = u_int address

The address argument is the address of the extended characteristics buffer's descriptor. The below figure shows the format of the extended characteristics buffer and its descriptor.

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

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 specified PID 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 active Contact 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 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	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 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 active Contact system manager why TCPware (or TCPDRIVER) not started
SS$_NORMAL	Success Port is now (or was) closed Port 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 = u_int address

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 specified PID returned in low order word of second longword
SS$_DEVACTIVE	Port is already open
SS$_DEVINACT	Device not active Contact 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 privilege Program tried to open local port below 1024, but program does not have BYPASS or SYSPRV privilege
SS$_NORMAL	Success Port is open and ready for receives
SS$_THIRDPARTY	Port closed by third party Usually 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 = byte *buffer

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

p2 = u_int size

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

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.

The below figure shows the buffer format.

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 active Contact system manager why TCPware (or TCPDRIVER) not started
SS$_IVBUFLEN	User's buffer too large
SS$_NORMAL	Success Datagram 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 = u_long *msghdr

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

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 active Contact system manager why TCPware (or TCPDRIVER) not started
SS$_IVBUFLEN	User's buffer too large
SS$_NORMAL	Success Datagram 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(char *devnam, u_int *chan, [unsigned long acmode], [char *mbxnam]);

Arguments

devnam

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

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.

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

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