| Previous | Contents | Index |
Use the p5 argument with the IO$_WRITEVBLK and IO$_SETMODE functions to specify input parameter lists. The p5 argument contains the address of a descriptor that points to, and specifies the contents of, an item list descriptor. Figure 3-2 illustrates how the p5 argument specifies the item list.
Figure 3-2 Specifying an Input Parameter List
Table 3-7 defines the descriptor fields, which also apply to buffer lists where indicated.
| Field | Description |
|---|---|
| length | A word specifying the length (in bytes) of the requested item list (also applies to buffer lists). |
| parameter type | A user-supplied, word-length symbolic code that specifies the type or class of parameter to set. The parameter types are: |
| TCPIP$C_DATA or zero to specify read or write buffers (for buffer lists only) | |
| TCPIP$C_SOCKOPT to specify socket options (for parameter lists only) | |
| TCPIP$C_TCPOPT to specify TCP/IP options (for parameter lists only) | |
| TCPIP$C_IPOPT to specify raw IP options (for parameter lists only) | |
| TCPIP$C_IOCTL to specify I/O control options (for parameter lists only) | |
| With the IO$_SENSEMODE function, use either TCPIP$C_SOCKOPT or TCPIP$C_IOCTL parameter types. | |
| The TCPIP$INETDEF symbol definition file defines the parameter type, which applies to all the descriptors in a list. See the $QIO routine descriptions in this chapter for details about the parameter types. | |
| address | A quadword (Alpha) or longword (VAX) that specifies the starting address of the item list (also applies to buffer lists). |
The rest of this chapter explains how to use parameters to describe
specific information. This chapter also contains a sample DEC C program
that specifies IOCTL parameters. There are additional sample programs
in TCPIP$EXAMPLES that contain the different functions and parameters.
3.7 Specifying an Output Parameter List
Use the p6 argument with the IO$_READVBLK or the IO$_SENSEMODE function to specify an output parameter list. The p6 argument passes the address of a descriptor that points to, and specifies the contents of, a descriptor list. The list consists of contiguous blocks of memory that contain one or more DIGITAL TCP/IP Services for OpenVMS descriptors.
Figure 3-3 illustrates how the p6 argument specifies the item_list.
Figure 3-3 Specifying an Output Parameter List
Table 3-8 defines the descriptor fields, which also apply to buffer lists where indicated.
| Field | Description |
|---|---|
| length | A word that specifies the length (in bytes) of the buffer into which the service writes the information. You supply the integer for this value. The length needed depends on the parameter name specified in the parameter name field of the descriptor on the list. If the value of the buffer length is too small, the service truncates the data (also applies to buffer lists.) |
| parameter type |
A user-supplied, word-length symbolic code that specifies the type or
class of parameter to get. The parameter types are:
With the IO$_SENSEMODE function, use either TCPIP$C_SOCKOPT or TCPIP$C_IOCTL parameter types. The TCPIP$INETDEF symbol definition file defines the parameter type, which applies to all the descriptors in a list. See the $QIO routine descriptions in this chapter for details about the parameter types. |
| address | A quadword (Alpha) or longword (VAX) from which the service reads the starting address of the user buffer containing data (also applies to buffer lists). |
With BSD Versions 4.3 and 4.4, you specify the socket name with the p3 or p4 argument with the IO$_ACCESS, IO$_READVBLK, IO$_WRITEVBLK, IO$_SENSEMODE, and IO$_SETMODE functions. This parameter takes the form of an address of an item_list_2 or item_list_3 descriptor.
The parameter name for p4 is TCPIP$C_SOCK_NAME, which is defined in the TCPIP$INETDEF symbol definition file.
The p3 argument must contain an item_list_2 descriptor, unless you use GETSOCKETNAME. In this case, p3 must contain an item_list_3 descriptor.
With BSD Version 4.3, you specify the local or remote socket names as illustrated in Figure 3-4.
Figure 3-4 Specifying the Local or Remote Socket Name (BSD Version 4.3)
With BSD Version 4.4, you specify the local and remote socket names as illustrated in Figure 3-5. Note that the first byte in the data structure is the length field. To accommodate this field, use the IO$M_EXTEND function modifier for all system services that can take a socket address as an input or output parameter (for example: IO$_ACCESS, IO$_READVBLK, and IO$_SENSEMODE).
Figure 3-5 Specifying the Local or Remote Socket Name (BSD Version 4.4)
The descriptor that the p3 and p4 arguments specify points to a 16-byte data structure called sockaddr_in. This data structure consists of the address domain (2 bytes), port number (2 bytes), host internet address (4 bytes), and unused bytes (8 bytes). Table 3-9 describes the sockaddr_in fields.
| Field | Description |
|---|---|
| address domain | INET domain (set by default). |
| port number | An integer in the range 0 to 65,535. Port numbers 1 to 1023 require either system UIC, SYSPRV, or BYPASS privileges when assigned. If you specify zero when binding a socket name, the system assigns an available port. |
| host internet address | A longword 4-byte integer. |
To set socket options, you use item_list_2 descriptors.
Figure 3-6 shows how to set socket options.
Figure 3-6 Setting Socket Options
The TCPIP$INETDEF symbol definition file defines the TCPIP$C_SOCKOPT parameter name for the socket options. For TCP options, use the TCPIP$C_TCPOPT parameter. For IP options, use the TCPIP$C_IPOPT parameter.
Figure 3-7 illustrates how to set I/O Control (IOCTL) parameters.
Figure 3-7 Setting IOCTL Parameters
The TCPIP$INETDEF symbol definition file specifies the TCPIP$C_IOCTL name. You specify the I/O control (IOCTL) parameters with an item_list_2 descriptor that lists its specifications. Each parameter field contains two longwords: the first is the IOCTL command value defined by the $SIOCDEF macro; the second is an IOCTL parameter structure address. During startup, the TCPIP$INETDEF symbol definition file specifies the values for the $SIOCDEF macro.
To get socket options, you use item_list_3 descriptors.
Figure 3-8 illustrates how to get socket options.
Figure 3-8 Getting Socket Options
Figure 3-9 illustrates how to get IOCTL parameters.
Figure 3-9 Getting IOCTL Parameters
This chapter provides detailed use and reference information about the OpenVMS system services used to write internet applications. The chapter also describes the Internet I/O function codes.
The descriptions of the system services and I/O function codes in this chapter are written specifically for internet programmers. For a general description of these system services and I/O function codes, see the OpenVMS reference manuals for system services.
Table 4-1 lists the equivalent C Socket routine for each system service and I/O function code in this chapter. See Chapter 6 for descriptions of C Socket routines.
| OpenVMS System Service | C Socket Call |
|---|---|
| $ASSIGN | open() |
| $CANCEL | close() |
| $DASSGN | close() |
| $GETDVI | getpeername(), getsockname(), getsockopt() |
| $QIO | bind(), listen() |
| IO$_ACCESS | connect(), accept() |
| IO$_ACPCONTROL | gethostbyname(), gethostbyaddr(), getnetbyname(), getnetbyaddr() |
| IO$_DEACCESS | close(), shutdown() |
| IO$_READVBLK | read(), recv(), recvfrom(), recvmsg() |
| IO$_SENSEMODE | getsockopt(), ioctl() |
| IO$_SENSECHAR | getsockopt(), ioctl() |
| IO$_SETMODE | socket(), bind(), listen(), setsockopt(), ioctl() |
| IO$_SETCHAR | socket(), bind(), listen(), setsockopt(), ioctl() |
| IO$_WRITEVBLK | send(), sendto(), sendmsg(), write() |
This section describes the OpenVMS system service routines used to write internet applications.
The Assign I/O Channel service provides a calling process with an I/O channel. This makes it possible for the calling process to perform I/O operations on the internet pseudodevice.
SYS$ASSIGN devnam, chan, [acmode], [mbxnam]
OpenVMS usage: longword (unsigned) type: write only access: by value
Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned.
devnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: by fixed-length string descriptor
Name of the device to which $ASSIGN is to assign a channel. The devnam argument specifies the address of a character string descriptor pointing to the pseudodevice name string. The character string contains TCPIP$DEVICE:.chan
OpenVMS usage: channel type: word (unsigned) access: write only mechanism: by reference
Number of the channel that is assigned. The chan argument is the address of a word into which $ASSIGN writes the channel number.acmode
OpenVMS usage: access_mode type: longword (unsigned) access: read only mechanism: by value
Access mode to be associated with the channel. The acmode argument specifies the access mode. I/O operations on the channel can be performed only from equal and more privileged access modes.mbxnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: by descriptor---fixed length string descriptor
This argument is not used.
The $ASSIGN system service establishes a path to a device but does not check whether the calling process has the capability to do I/O operations to the device. The device drivers may apply privilege and protection restrictions. The calling process must have NETMBX privilege to assign a channel.
System dynamic memory is required for the target device and the I/O byte-limit quota from the process buffer is used.
When a channel is assigned to TCPIP$DEVICE:, the internet software creates a new pseudodevice called BGn, where n is a unique unit number. The corresponding channel number is used in any subsequent operation requests for that device.
Channels remain assigned either until they are explicitly deassigned with the Deassign I/O Channel ($DASSGN) service, or, if they are user-mode channels, until the image that assigned the channel exits.
Two programming examples for the $ASSIGN routine follow this command description. Example 4-1 uses the MACRO-32 programming language and Example 4-2 uses the C programming language.
SS$_NORMAL Service successfully completed. SS$_ACCVIO The caller cannot read the device string or string descriptor, or the caller cannot write the channel number. SS$_DEVALLOC The device is allocated to another process. SS$_EXQUOTA The process has exceeded its buffered I/O byte limit (BIOLM) quota. SS$_IVDEVNAM No device name was specified, the logical name translation failed, or the device name string contains invalid characters. SS$_IVLOGNAM The device name string has a length of zero or has more than 63 characters. SS$_NOIOCHAN No I/O channel is available for assignment. SS$_NOSUCHDEV This warning code indicates that the specified device does not exist.
| Example 4-1 $ASSIGN System Service (MACRO-32) |
|---|
.title Assign
.ident /01/
$inetsymdef ; INET symbols
dev: .ascid /tcpip$device:/ ; INET device name
channel: .word 0 ; INET channel
.entry start,^m<>
;
; Assign an INET device
;
$assign_s devnam=dev, chan=channel
.
.
.
.end start
|
| Example 4-2 $ASSIGN System Service (C Programming) |
|---|
#module assgn_chan
/*
**++
**
** This example assigns a channel to INET device
** using system service SYS$ASSIGN
**
**--
*/
/*
** INCLUDE FILES
*/
#include <descrip.h>
assgn_chan(channel)
unsigned short ; /* INET channel */
{
int status ; /* For return status */
/* Descriptor for Inet device name */
$DESCRIPTOR (dev, "TCPIP$DEVICE:");
/*
** Assign a channel to INET device
*/
status = SYS$ASSIGN( &dev,
&channel,
0,
0) ;
if ((status & 1) == 0) {
printf("Failed to assign channel to INET device \n") ;
return(status) ;
}
return(status) ;
/*
** channel will have the assigned
** channel number
*/
}
|
This routine cancels all pending I/O requests on a specified channel.
SYS$CANCEL chan
OpenVMS usage: longword (unsigned) type: write only access: by value
Longword condition value. All system services return (by immediate value) a condition value in R0. Condition values that can be returned by this service are listed under Condition Values Returned.
chan
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
The channel on which the routine cancels the I/O. The chan argument is a word containing the channel number.
To cancel I/O on a channel, the access mode of the calling process must be equal to or more privileged than the access mode of the process that made the original channel assignment.The $CANCEL service requires system dynamic memory and uses the process's buffered I/O limit (BIOLM) quota.
Two programming examples for the $CANCEL routine follow this command description. Example 4-3 uses the MACRO-32 programming language and Example 4-4 uses the C programming language.
When a request currently in progress is canceled, the driver is notified immediately. Actual cancellation may or may not occur immediately, depending on the logical state of the driver. When cancellation does occur, the action taken for I/O in progress is similar to that taken for queued requests. For example:
- The specified event flag is set.
- The first word of the IOSB of the I/O request you are canceling is set to SS$_CANCEL if the I/O request is queued or to SS$_ABORT if the I/O operation is in progress.
- If the asynchronous system trap (AST) is specified, it is queued.
For proper synchronization between this service and the actual canceling of I/O requests to take place, the issuing process must wait for the I/O process to complete normally. Note that the I/O has been canceled. Outstanding I/O requests are canceled automatically at image exit.
SS$_NORMAL Service successfully completed. SS$_ABORT A physical line went down during a network connect operation. SS$_CANCEL Warning code. The I/O operation was canceled by executing a $CANCEL system service. SS$_EXQUOTA The process has exceeded its buffered I/O limit (BIOLM) quota. SS$_INSFMEM Insufficient system dynamic memory is available to cancel the I/O. SS$_IVCHAN An invalid channel was specified (that is, a channel number of zero or a number larger than the number of channels available). SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode.
| Example 4-3 $CANCEL System Service (MACRO-32) |
|---|
.title Cancel
.ident /01/
$inetsymdef ; INET symbols
dev: .ascid /tcpip$device:/ ; INET device name
channel: .word 0 ; INET channel
.entry start,^m<>
;
; Assign an INET device
;
.
.
.
;
; Cancel I/O on INET device
;
$cancel_s chan=channel
.
.
.
.end start
|
| Example 4-4 $CANCEL System Service (C Programming) |
|---|
#module cancel_io
/*
**++
**
** This example cancels all pending I/O requests on the
** specified channel using system service SYS$CANCEL
**
**--
*/
/*
** INCLUDE FILES
*/
cancel_io(chan)
short chan ; /* INET channel on which I/O is to be canceled */
{
int status ; /* For return status */
/*
** Cancel the pending I/Os
*/
(status = SYS$CANCEL(chan)) ;
if ((status & 1) == 0) {
printf("Failed to cancel pending I/Os \n") ;
return(status) ;
}
return(status) ;
}
|
| Previous | Next | Contents | Index |