HP OpenVMS Systems Documentation

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming

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.

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.

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.