HP OpenVMS systems documentation

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.

Table 5-4 $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.)

5.4.2 I/O Status Block

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.

Table 5-5 $QIO Function-Dependent Arguments

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

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:

1. Set the descriptor's type field to one of the following symbolic codes to specify the type of input parameter list:

   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

2. Set the descriptor's length field to specify the length of the input parameter list.
3. Set the descriptor's address field to specify the starting address of the input parameter list.

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:

1. Set the item's type field to one of the symbolic codes found in the following tables:

   Table A-1, Socket Options
   Table A-2, TCP Protocol Options
   Table A-3, IP Protocol Options

2. Set the item's length field to specify the length of the item.
3. Set the item's address field to specify the starting address of its data.

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:

1. Set the descriptor's type field to one of the following symbolic codes to specify the type of output parameter list:

   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

2. Set the descriptor's length field to specify the length of the output parameter list.
3. Set the descriptor's address field to specify the starting address of the output parameter list.

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:

1. Set the item's type field to one of symbolic codes found in the following tables:

   Table A-1, Socket Options
   Table A-2, TCP Protocol Options
   Table A-3, IP Protocol Options

2. Set the item's buffer length field to specify the length of its buffer.
3. Set the item's buffer address field to specify the starting address of its buffer.
4. Set the item's returned length address field to specify the address of a longword to receive the length in bytes of the information actually returned for this item.

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.

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:

1. Set the descriptor's data-type code (the DTYPE field) to DSC$K_DTYPE_DSC to specify a buffer list containing one or more descriptors defining the length and starting address of user buffers.
2. Set the descriptor's class code (the CLASS field) to DSC$K_CLASS_S.
3. Set the descriptor's length field to specify the length of the buffer list.
4. Set the descriptor's MBO field to 1 and the MBMO field to all 1s if this is a 64-bit argument descriptor.

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.