[an error occurred while processing this directive]
HP OpenVMS Systems Documentation |
HP TCP/IP Services for OpenVMS
|
Previous | Contents | Index |
You pass two types of arguments with the $QIO system service:
function-independent arguments and function-dependent arguments. The
following sections provide information about $QIO system service
arguments.
5.4.1 $QIO Function-Independent Arguments
Table 5-4 describes the $QIO function-independent arguments.
Argument | Description |
---|---|
astadr | Address of the asynchronous system trap (AST) routine to be executed when the I/O operation is completed. |
astprm | A quadword (Alpha and I64) or longword (VAX) containing the value to be passed to the AST routine. |
chan | A longword value that contains the number of the I/O channel. The $QIO system service uses only the low-order word. |
efn | A longword value of the event flag number that the $QIO system service sets when the I/O operation completes. The $QIO system service uses only the low-order byte. |
func |
A longword value that specifies the network pseudodevice function code
and function modifiers that specify the operation to be performed.
Function modifiers affect the operation of a specified function code. In MACRO-32, you use the exclamation point (!) to logically OR the function code and its modifier. In C, you use the vertical bar (|). This manual uses the vertical bar (|) in text. |
iosb | The I/O status block that receives the final status message for the I/O operation. The iosb argument is the address of the quadword I/O status block. (For the format of the I/O status block, see Section 5.4.2.) |
The system returns the status of a $QIO operation in the I/O status block (IOSB) supplied as an argument to the $QIO call. In the case of a successful IO$_READVBLK or IO$_WRITEVBLK operation, the second word of the I/O status block contains the number of bytes transferred during the operation (see Figure 5-1).
Figure 5-1 I/O Status Block for a Successful READ or WRITE Operation
With an unsuccessful IO$_READVBLK or IO$_WRITEVBLK operation, in most cases, the system returns a UNIX error code in the second word of the I/O status block.
For C programs, the OpenVMS completion codes are defined in the SSDEF.H
header file. The UNIX error codes are defined in the ERRNO.H header
file and in the TCPIP$INETDEF.H header file. For other language
variants, see Table 5-2.
5.4.3 $QIO Function-Dependent Arguments
Arguments p1, p2, p3, p4, p5, and p6 to the $QIO system service are used to pass function-dependent arguments. Table 5-5 lists arguments p1 through p6 for the $QIO system service and indicates whether the parameter is passed by value, by reference, or by descriptor.
$QIO | p1 | p2 | p3 | p4 | p5 | p6 |
---|---|---|---|---|---|---|
IO$_ACCESS | Not used | Not used | Remote socket name 4 | Not used | Not used | Not used |
IO$_ACCESS|
IO$M_ACCEPT |
Not used | Not used | Remote socket name 5 | Channel number 2 | Not used | Not used |
IO$_ACPCONTROL | Subfunction code 3 | Input parameter 3 | Buffer length 2 | Buffer 3 | Not used | Not used |
IO$_DEACCESS | Not used | Not used | Not used | Not used | Not used | Not used |
IO$_DEACCESS|
IO$M_SHUTDOWN |
Not used | Not used | Not used | Shutdown flags 1 | Not used | Not used |
IO$_READVBLK | Buffer 2 | Buffer size 1 | Remote socket name 5 | Flags 1 | Not used | Output buffer list 3 |
IO$_READVBLK|
IO$M_INTERRUPT |
Buffer 2 | Buffer size 1 | Not used | Not used | Not used | Not used |
IO$_WRITEVBLK | Buffer 2 | Buffer size 1 | Remote socket name 4 | Flags 1 | Input buffer list 3 | Not used |
IO$_WRITEVBLK|
IO$M_INTERRUPT |
Buffer 2 | Buffer size 1 | Not used | Not used | Not used | Not used |
IO$_SETMODE | Socket char 2 | Not used | Local socket name 4 | Backlog limit 1 | Input parameter list 4 | Not used |
IO$_SETMODE|
IO$_OUTBAND |
AST procedure 2 | User argument 1 | Access mode 1 | Not used | Not used | Not used |
IO$_SETMODE|
IO$_READATTN |
AST procedure 2 | User argument 1 | Access mode 1 | Not used | Not used | Not used |
IO$_SETMODE|
IO$WRTATTN |
AST procedure 2 | User argument 1 | Access mode 1 | Not used | Not used | Not used |
IO$_SENSEMODE | Not used | Not used | Local socket name 5 | Remote socket name 5 | Not used | Output parameter list 4 |
In addition to OpenVMS argument descriptors, I/O functions specific to TCP/IP Services also pass arguments by using item_list_2 and item_list_3 argument descriptors. The format of these argument descriptors is unique to TCP/IP Services, and they supplement argument descriptors defined in the OpenVMS Calling Standard.
Use of an item_list_2 or item_list_3 argument descriptor is indicated when the argument's passing mechanism is specified as an item_list_2 descriptor or an item_list_3 descriptor. To determine an argument's passing mechanism, refer to the argument's description in Chapter 6.
The item_list_2 argument descriptors describe the size, data type, and starting address of a service parameter. An item_list_2 argument descriptor contains three fields, as depicted in the following diagram:
The first field is a word containing the length (in bytes) of the parameter being described. The second field is a word containing a symbolic code specifying the data type of the parameter. The third field is a longword containing the starting address of the parameter.
The item_list_3 argument descriptors describe the size, data type, and address of a buffer in which a service writes parameter information returned from a get operation. An item_list_3 argument descriptor contains four fields, as depicted in the following diagram:
The first field is a word containing the length (in bytes) of the buffer in which a service writes information. The length of the buffer needed depends on the data type specified in the type field. If the value of buffer length is too small, the service truncates the data. The second field is a word containing a symbolic code specifying the type of information that a service is to return. The third field is a longword containing the address of the buffer in which a service writes the information. The fourth field is a longword containing the address of a longword in which a service writes the length (in bytes) of the information it actually returned.
When a parameter specified as a descriptor is described as "read-only", the descriptor itself is only read, and TCP/IP Services does not modify the memory described. However, system service postprocessing requires that the described memory must be both readable and writable. |
Use the p5 argument with the IO$_SETMODE function to specify input parameter lists. The p5 argument specifies the address of a item_list_2 descriptor that points to and identifies the type of input parameter list.
To initialize an item_list_2 descriptor, you need to:
Symbolic Name | Input Parameter List Type |
---|---|
TCPIP$C_SOCKOPT | Socket options |
TCPIP$C_TCPOPT | TCP protocol options |
TCPIP$C_IPOPT | IP protocol options |
TCPIP$C_IOCTL | I/O control commands |
Figure 5-2 illustrates how the p5 argument specifies an input parameter list.
Figure 5-2 Specifying an Input Parameter List
As the name implies, input parameter lists consist of one or more contiguous item_list_2 or ioctl_comm structures. The length of a input parameter list is determined solely from the length field of its associated argument descriptor. Input parameter lists are never terminated by a longword containing a zero.
Each item_list_2 structure that appears in an input parameter list describes an individual parameter or item to set. Such items include socket or protocol options as identified by the item's type field.
To initialize an item_list_2 descriptor, you need to:
Table A-1, Socket Options
Table A-2, TCP Protocol Options
Table A-3, IP Protocol Options
Figure 5-3 illustrates how to specify setting socket options.
Figure 5-3 Setting Socket Options
Each ioctl_comm structure appearing in an input parameter list contains an I/O control command---the IOCTL request code (as defined by $SIOCDEF) and its associated IOCTL structure address. Figure 5-4 illustrates how to specify (set) I/O control (IOCTL) commands.
Figure 5-4 Setting IOCTL Parameters
Use the p6 argument with the IO$_SENSEMODE function to specify output parameter lists. The p6 argument specifies the address of an item_list_2 descriptor that points to and identifies the type of output parameter list.
To initialize an item_list_2 descriptor, you need to:
Symbolic Name | Output Parameter List Type |
---|---|
TCPIP$C_SOCKOPT | Socket options |
TCPIP$C_TCPOPT | TCP protocol options |
TCPIP$C_IPOPT | IP protocol options |
TCPIP$C_IOCTL | I/O control commands |
Figure 5-5 illustrates how the p6 argument specifies an output parameter list.
Figure 5-5 Specifying an Output Parameter List
As the name implies, output parameter lists consist of one or more contiguous item_list_3 or ioctl_comm structures. The length of an output parameter list is determined solely from the length field of its associated argument descriptor. Output parameter lists are never terminated by a longword containing a zero.
Each item_list_3 structure that appears in an output parameter list describes an individual parameter or item to return. Such items include socket or protocol options as identified by the item's type field.
To initialize an item_list_3 structure, you need to:
Table A-1, Socket Options
Table A-2, TCP Protocol Options
Table A-3, IP Protocol Options
Figure 5-6 illustrates how to specify getting socket options.
Figure 5-6 Getting Socket Options
Each ioctl_comm structure appearing in a output parameter list contains an I/O control command---the IOCTL request code (as defined by $SIOCDEF) and its associated IOCTL structure address. For more information about IOCTL requests, see Appendix B.
Figure 5-7 illustrates how to specify (get) I/O control (IOCTL) commands.
Figure 5-7 Getting IOCTL Parameters
Use the p3 or p4 argument with the IO$_ACCESS, IO$_READVBLK, IO$_SENSEMODE, IO$_SETMODE, and IO$_WRITEVBLK functions to specify a socket name. The p3 and p4 arguments specify the address of an item_list_2 or item_list_3 descriptor that points to a socket name structure. The socket name structure contains (among other things), the address domain, port number, and host internet address.
Port numbers 1 to 1023 require SYSPRV and BYPASS privileges when assigned. If you specify 0 when binding a socket name, the system assigns an available port. |
Use an item_list_2 argument descriptor with the IO$_ACCESS, IO$_WRITEVBLK, and IO$_SETMODE functions to specify (set) a socket name. The descriptor's parameter type is TCPIP$C_SOCK_NAME.
Use an item_list_3 argument descriptor with the IO$_ACCESS|IO$M_ACCEPT, IO$_READVBLK, and IO$_SENSEMODE functions to specify (get) a socket name. The descriptor's parameter type is TCPIP$C_SOCK_NAME.
With BSD Version 4.3, specify IPv4 socket names as illustrated in Figure 5-8.
Figure 5-8 Specifying IPv4 Socket Names (BSD Version 4.3)
With BSD Version 4.4, specify IPv4 socket names as illustrated in Figure 5-9.
Figure 5-9 Specifying IPv4 Socket Names (BSD Version 4.4)
Specify IPv6 socket names as illustrated in Figure 5-10.
Figure 5-10 Specifying IPv6 Socket Names (BSD Version 4.4)
Note that the first byte in the socket name is the length field. To
accommodate this field, use the IO$M_EXTEND function modifier for all
I/O functions that take a socket name as an output argument
(IO$_ACCESS|IO$M_ACCEPT, IO$_READVBLK, and IO$_SENSEMODE). Always use a
buffer large enough to accept IPv6 socket names when you use the
IO$M_EXTEND function modifier.
5.5.4 Specifying a Buffer List
Use the p5 argument with the IO$_WRITEVBLK function to specify input buffer lists. The p5 argument specifies the address of a 32- or 64-bit fixed-length descriptor (on Alpha and I64 systems) or a 32-bit fixed-length descriptor (on VAX systems) pointing to an input buffer list.
Use the p6 argument with the IO$_READVBLK function to specify output buffer lists. The p6 argument specifies the address of a 32- or 64-bit fixed-length descriptor (on Alpha and I64 systems) or a 32-bit fixed-length descriptor (on VAX systems) pointing to an output buffer list.
To initialize a p5 or p6 argument descriptor, you need to:
Figure 5-11 illustrates how to specify a buffer list.
Figure 5-11 Specifying a Buffer List
Buffer lists, as the name implies, consist of one or more contiguous 32- or 64-bit fixed-length descriptors (on Alpha and I64 systems) or 32-bit fixed-length descriptors (on VAX systems).
Each 32- or 64-bit descriptor that appears in a buffer list describes one user buffer. Initialize each descriptor by setting its data type, class, length, and address fields as appropriate for 32- and 64-bit descriptors.
For more information about using 32-bit and 64-bit descriptors, refer to the OpenVMS Calling Standard.
Previous | Next | Contents | Index |