| Previous | Contents | Index |
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.
5.5.1 Specifying an Input Parameter List
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 structure, 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 structure, 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 structure, 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. 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 address domain, port number, and host internet address.
Port numbers 1 to 1023 require a system UIC or a UIC with SYSPRV and BYPASS privileges when assigned. If you specify zero 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 socket names as illustrated in Figure 5-8.
Figure 5-8 Specifying a Socket Name (BSD Version 4.3)
With BSD Version 4.4, specify socket names as illustrated in Figure 5-9. 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).
Figure 5-9 Specifying a Socket Name (BSD Version 4.4)
5.6.1 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
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 systems) or a 32-bit fixed-length descriptor (on VAX systems) pointing to an output buffer list.
To initialize the p5 or p6 arugment descriptor, you need to:
Figure 5-10 illustrates how to specify a buffer list.
Figure 5-10 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 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.
This chapter provides detailed information about the OpenVMS system services for writing network applications. The chapter also describes the network pseudodevice driver and TELNET port driver I/O functions used with the $QIO system service.
The descriptions of the system services and I/O function codes are targeted specifically for network application programmers. For a general description of these system services and I/O function codes, see the OpenVMS System Services Reference manuals.
Table 6-1 lists the equivalent Sockets API function for each system service and $QIO I/O function code in this chapter. See Chapter 4 for descriptions of the Sockets API functions.
| OpenVMS System Service | Sockets API Function or Description |
|---|---|
| $ASSIGN | socket() |
| $CANCEL | close() |
| $DASSGN | close() |
| $QIO | |
| Network Pseudodevice I/O Function Codes: | |
| IO$_ACCESS | connect() |
| IO$_ACCESS|IO$M_ACCEPT | accept() |
| IO$_ACPCONTROL | gethostbyname(), gethostbyaddr(), getnetbyname(), getnetbyaddr() |
| IO$_DEACCESS | close() |
| IO$_DEACCESS|IO$M_SHUTDOWN | shutdown() |
| IO$_READVBLK | read(), recv(), recvfrom(), recvmsg() |
| IO$_SENSEMODE | getsockopt(), ioctl(), getpeername(), getsockname() |
| IO$_SENSECHAR | getsockopt(), ioctl(), getpeername(), getsockname() |
| IO$_SETMODE | socket(), bind(), listen(), setsockopt(), ioctl() |
| IO$_SETCHAR | socket(), bind(), listen(), setsockopt(), ioctl() |
| IO$_WRITEVBLK | send(), sendto(), sendmsg(), write() |
| TELNET Port Driver I/O Function Codes: | |
| IO$_TTY_PORT | |
| IO$M_TN_STARTUP | Binds a socket to a TELNET terminal device. |
| IO$M_TN_SHUTDOWN | Breaks a previously bound socket terminal connection. |
| IO$_TTY_PORT_BUFIO | |
| IO$M_TN_SENSEMODE | Reads parameters associated with the device. |
| IO$M_TN_SETMODE | Writes parameters associated with the device. |
This section describes the OpenVMS system service routines used to write network applications.
Detailed information about each argument is listed for each I/O function. The following format is used to describe each argument:
|
argument-name |
| OpenVMS usage: | OpenVMS data type |
| type: | argument data type |
| access: | argument access |
| mechanism: | argument passing mechanism |
The purpose of the OpenVMS usage entry is to facilitate the coding of source-language data type declarations in application programs. Ordinarily, the standard data type is sufficient to describe the type of data passed by an argument. However, within the OpenVMS operating system environment, many system routines contain arguments whose conceptual nature or complexity requires additional explanation.
See Appendix C for a list of the possible OpenVMS usage entries and their definitions. Refer to the appropriate language implementation table in Appendix C to determine the correct syntax of the type declaration in the language you are using.
Note that the OpenVMS usage entry is not a traditional data type (such as the standard data types of byte, word, longword, and so on). It is significant only within the context of the OpenVMS operating system and is intended solely to expedite data declarations within application programs.
Provides a calling process with an I/O channel, thereby allowing the calling process to perform I/O operations on the network pseudodevice.On Alpha systems, this service accepts 64-bit addresses.
SYS$ASSIGN devnam, chan, [acmode], [mbxnam], [flags]
int sys$assign (void *devnam, unsigned short int *chan, unsigned int acmode, void *mbxnam,...);
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: 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 32- or 64-bit descriptor-fixed-length string descriptor (Alpha)
Name of the device to which $ASSIGN is to assign a channel. The devnam argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a character string descriptor pointing to the network pseudodevice name string (either TCPIP$DEVICE: or SYS$NET:).chan
OpenVMS usage: channel type: word (unsigned) access: write only mechanism: by 32- or 64-bit reference (Alpha)
Number of the channel that is assigned. The chan argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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. I/O operations on the channel can be performed only from equal and more privileged access modes. The $PSLDEF macro defines the following symbols for the four access modes:
Symbol Access Mode Numeric Value PSL$C_KERNEL Kernel 0 PSL$C_EXEC Executive 1 PSL$C_SUPER Supervisor 2 PSL$C_USER User 3 mbxnam
OpenVMS usage: device_name type: character-coded text string access: read only mechanism: by 32- or 64-bit descriptor-fixed-length string descriptor (Alpha)
This argument is not used.flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
An optional device-specific argument. The flags argument is a longword bit mask. For more information about the applicability of the flags argument for a particular device, refer to the OpenVMS I/O User's Reference Manual.
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 the TCPIP$DEVICE: template network device, the network software creates a new device called BGn, where n is a unique unit number. The corresponding channel number is used in any subsequent operation requests for that device.
When the auxiliary server creates a process for a service with the LISTEN flag set, the server creates a device socket. In order for your application to receive the device socket, assign a channel to SYS$NET, which is the logical name of a network pseudodevice, and perform an appropriate $QIO(IO$_SETMODE) operation.
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.
SS$_NORMAL The service completed successfully. 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$_DEVLSTFULL The system maximum number of BG: device units has been reached. 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 The specified device does not exist.
Cancels all pending I/O requests on a specified channel.Related Functions
SYS$CANCEL chan
int sys$cancel (unsigned short int chan);
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
| Previous | Next | Contents | Index |