DIGITAL TCP/IP Services for OpenVMS
System Services and C Socket Programming
Previous Contents Index

For TCP/IP, $QIO uses the following system resources:

For $QIO, completion can be synchronized as follows:

Condition Values Returned

Each function used with $QIO has its own error codes. See the error codes listed under the individual internet I/O function code descriptions that comprise the remainder of this chapter.

4.2 Internet I/O Function Codes

The internet pseudodevice allows physical, logical, and virtual block I/O functions. The physical and logical functions are used only with the IP layer. Table 4-5 lists the basic functions and their modifiers. The sections that follow describe these functions in greater detail.

Table 4-5 Internet I/O Function Codes
Function Code and Arguments Function Modifier Description
IO$_ACCESS p3,p4 IO$M_ACCEPT
IO$M_EXTEND
IO$M_NOW 		Opens a connection.
IO$_ACPCONTROL p1   Performs an ACP (ancillary control process) operation.
IO$_DEACCESS p4 IO$M_NOW
IO$M_SHUTDOWN 		Aborts or closes a connection.
IO$_READVBLK p1,p2,p3,p4,p6 IO$M_EXTEND
IO$M_INTERRUPT 		Reads a virtual block.
  IO$M_LOCKBUF
IO$M_PURGE 		Controls the buffer operations.
IO$_SENSEMODE [ p2], p3,p4,p6   Reads the internet pseudodevice characteristics.
IO$_SENSECHAR [ p2], p3,p4,p6   Reads the internet pseudodevice characteristics.
IO$_SETMODE p1,[ p2], p3,p4,p5 IO$M_OUTBAND
IO$M_READATTN
IO$M_WRTATTN 		Sets the internet pseudodevice characteristics for subsequent operations.
IO$_SETCHAR p1,[ p2], p3,p4,p5 IO$M_OUTBAND
IO$M_READATTN
IO$M_WRTEATTN 		Sets the internet pseudodevice characteristics for subsequent operations.
IO$_WRITEVBLK p1,p2,p3,p4,p5 IO$M_INTERRUPT Writes a virtual block.

Table 3-2 contains the file names of the symbol definition files. These files specify $QIO arguments (p1,p2,...p6) for applications written in the corresponding programming languages. You must invoke the symbol definition by using the appropriate include statement in your application.

IO$_ACCESS

When you are using a connection-oriented protocol such as TCP, the IO$_ACCESS function initiates a connection and specifies a remote port and address. When you use a connectionless protocol such as UDP, the IO$_ACCESS function sets the remote port and address.

For TCP, a connection request times out in a specified interval (75 seconds by default). This interval can be changed by the system manager. The program can also set a specific timeout interval for a socket that it has created.

The equivalent C Socket function is connect() or accept().

Arguments

p3


usage remote socket name
type longword (unsigned)
access read only
mechanism by descriptor

For the IO$_ACCESS function, the p3 parameter is the address of an item_list_2 descriptor that points to the sockaddr_in structure containing the remote host address and port number.

For the IO$_ACCESS function with the IO$M_ACCEPT modifier, the p3 parameter is the address of an item_list_3 descriptor that points to a socket name and a returned longword that contains the length.

With BSD Version 4.4, the IO$_ACCESS function with the IO$M_EXTEND modifier allows the use of extended modifiers.

p4


usage the device channel
type word (unsigned)
access read only
mechanism by reference

The p4 parameter specifies the address of a word value containing the channel for the I/O operations after the connection is established. This input parameter is specified only with the IO$M_ACCEPT modifier (for TCP).

Function Modifiers

IO$M_ACCEPT Accepts a connection request issued from another process. The remote host address and remote port number are output parameters.
IO$M_EXTEND Allows the use of extended modifiers with BSD Version 4.4. Valid only for datagram sockets (UDP or raw IP); ignored for TCP.
IO$M_NOW Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the I/O operation to block, the system completes the I/O operation and returns the $QIO error code SS$_SUSPENDED. The corresponding UNIX error code is EWOULDBLOCK.

Condition Values Returned

SS$_ABORT Programming error, INET management error, or hardware error. Aborts execution of the I/O operation.
SS$_BADPARAM Programming error that occurred for one of the following reasons:
  1. You tried to execute a $QIO function without specifying a device socket.
  2. You tried to issue an IO$_ACCESS!IO$M_ACCEPT function without specifying the channel for the device socket that will be used for the accepted connection ( p4 is null or invalid).
  3. You tried to issue an IO$_ACCESS function without specifying the address of the remote device socket address ( p3 as null).
SS$_BUGCHECK Inconsistent state. Report the problem to your Compaq support representative.
SS$_CANCEL Warning code. The I/O operation was canceled by a $CANCEL system service.
SS$_CONNECFAIL Programming error, INET management error, or hardware error. The connection was abnormally terminated for one of the following reasons:
  1. An IO$_ACCESS!IO$M_ACCEPT failed because the listener socket closed. The cause can be local or remote.
  2. An existing connection was aborted because of an error detected during communication.
SS$_DEVINACT Programming or INET management error. The driver was not started. Issue the management command START COMMUNICATION before issuing any $QIO call.
SS$_DEVNOTMOUNT Programming or INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated.
SS$_EXQUOTA Programming or system management error. Socket quota (maximum number of sockets allowed) or user quotas exceeded.
SS$_FILALRACC Programming error. The socket name is already in use by one of the following:
  1. On a raw socket, you specified a remote INET socket address with an IO$_ACCESS function, but an INET address was already specified with a previous IO$_ACCESS.
  2. On a datagram, you specified a remote INET socket address with an IO$_ACCESS function, but an INET address was already specified with a previous IO$_ACCESS.
  3. On a stream socket, you issued an IO$_ACCESS function on a stream socket that was already connected.
SS$_ILLCNTRFUNC Programming error. Illegal function.
SS$_INSFMEM INET management or programming error. Not enough buffer space for allocation. The INET software needs more buffer space.
SS$_IVADDR Programming error. The specified INET address was not found or an invalid port and INET address combination was specified with the IO$_ACCESS function. Port zero is not allowed with an IO$_ACCESS function.
SS$_IVBUFLEN Programming error. Socket address buffer has an invalid size.
SS$_NOLICENSE Programming or system management error. DIGITAL TCP/IP for OpenVMS license is not present.
SS$_NOLINKS Programming error. An attempt was made to disconnect a socket that has not been connected.
SS$_LINKABORT Communication status change. The remote socket closed a connection.
SS$_PROTOCOL Programming error. The address family of the remote INET address specified with an IO$_ACCESS function is not supported (UDP/IP or TCP/IP). The address family should be TCPIP$C_AF_INET.
SS$_REJECT Programming error, INET management error, or hardware error. Connection is rejected for one of the following reasons:
  1. An attempt was made to connect to a remote socket that is already connected.
  2. An error was encountered while establishing the connection.
  3. The peer socket either refused a connection request or wants to close the connection.
SS$_SHUT The network is being shut down.
SS$_SUSPENDED The operation is blocked. The accept operation cannot complete because there are no connection requests received. The socket is marked as nonblocking.
SS$_TIMEOUT Programming error, INET management error, or hardware error. A TCP/IP connection timed out while in the process of being established. The default time interval is 75 seconds.
SS$_UNREACHABLE Communication status. Remote host or network is not reachable.

IO$_ACPCONTROL

The internet ACP Control I/O (IO$_ACPCONTROL) function requests that the ACP perform operations such as providing information from the internet host and network database files.

The equivalent C Socket functions are gethostbyname(), gethostbyaddr(), getnetbyname(), or getnetbyaddr(). Two programming examples for the IO$_ACPCONTROL routine follow this command description. Example 4-7 uses the MACRO-32 programming language and Example 4-8 uses the C programming language.

Arguments

p1


usage subfunction code
type longword (unsigned)
access read only
mechanism by descriptor

The p1 parameter is the address of the OpenVMS descriptor for a 4-byte block. The block consists of a subfunction type (1 byte), a call code (1 byte), and 2 bytes reserved for Compaq (must be zero).

Table 4-6 lists the valid INET subfunction codes. These symbols are defined by the $INETACPFSYMDEF module in the TCPIP$INETDEF symbol definition file.

Table 4-6 Valid INET Subfunction Codes
INET Subfunction Code Code Function
INETACP_FUNC$C_GETHOSTBYNAME Get the INET address of the specified host from the internet host database.
INETACP_FUNC$C_GETHOSTBYADDR Get the host name of the specified internet address from the internet host database.
INETACP_FUNC$C_GETNETBYNAME Get the INET address of the specified network from the internet network database.
INETACP_FUNC$C_GETNETBYADDR Get the network name of the specified internet address from the internet network database.

When these functions are performed, IO$_ACPCONTROL searches the local database for the host's name. If it does not find the host name in the local host database, IO$_ACPCONTROL then searches the BIND database if the BIND resolver is enabled.

Table 4-7 lists the valid INET call codes that IO$_ACPCONTROL accepts.

Table 4-7 INET Call Codes
Code Description
INETACP$C_ALIASES Obtains the list of alias names associated with the specified host or network from the internet hosts or network database.
INETACP$C_TRANS Returns a longword value of the internet address in dotted-decimal notation.
INETACPC$C_HOSTENT_OFFSET Returns full host information in a modified hostent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure.
INETACP$C_NETENT_OFFSET Returns full network information in a modified netent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure.

The INET_ACP call codes are defined by the $INETACPSYMDEF module in the TCPIP$INETDEF symbol definition file.

The hostent and netent structures are defined by the $HOSTENTDEF and $NETENTDEF modules in the TCPIP$INETDEF symbol definition file.

p2


usage input parameter
type longword (unsigned)
access read only
mechanism by descriptor

The p2 parameter is the address of the string descriptor for the input parameter. The input parameter contains the host name, network name, host address, or network INET address. The INET address is specified as a character string. The network and host numbers are separated by periods. The address is in network format. For example, in the address 128.20.10.5, the network is 128.20.10 and the host is 5.

p3


usage length of the output string
type word
access write only
mechanism by reference

The p3 parameter is the address of the word location where the length of the output string is returned.

p4


usage output character string address
type longword or character string
access write only
mechanism by descriptor

The p4 parameter is the address of the descriptor for the output character string that contains the host name, network name, host address, or the network INET address. The INET address is returned as a character string. The network and host numbers are separated by periods. The address is in dotted decimal notation.

Alias names are separated by a null character (a 0 byte). The length of the returned string includes all null characters that separate aliases.

Condition Values Returned

SS$_ABORT Unknown cause of an internal error. An unspecified error was detected while performing an INET ACP function.
SS$_BADPARAM Programming or internal error. You specified a bad parameter (name or address) in a GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_BUFFEROVF Programming error. There was not enough space for returning all alias names in a
GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
SS$_ENDOFFILE The information requested is not in the database.
SS$_ILLCNTRFUNC Programming error. An invalid ACP function code was specified in an IO$_ACPCONTROL function.
SS$_NOPRIV INET management error. No privilege for the execution of an INET ACP function.
SS$_RESULTOVF Programming error. The ACP overflowed the buffer in returning a parameter.
SS$_SHUT The network is being shut down.

Example 4-7 IO$_ACPCONTROL Function (MACRO-32 Programming) 

        .title Get_host_by_name 
        .ident  /01/ 
        .library        /sys$share:lib.mlb/ 
        .show meb 
 
        $inetacpfdef 
 
dev:    .ascid  /tcpip$device:/ 
chan:   .long   0 
iosb:    .quad  0 
command:        .long   length 
                .address        comm 
comm:   .byte   1       ; get host 
        .byte   0 
        .word   0 
length=.-comm 
host_d: .ascid  /BRIGIT/ 
host_nam: .ascid        /           
        .blkl   32 
title:  .ascid /Host address:/ 
title1: .ascid /Host name:/ 
        .entry   start,^m<> 
; 
; assign Internet device for INIT 
; 
        $assign_s       devnam=dev, chan=chan 
        blbs    r0,as1 
        brw     exit 
as1: 
        $qioW_s efn=#1,- 
                chan=chan, - 
                func=#io$_acpcontrol,- 
                iosb= iosb,- 
                p1=command,p2=#host_d,P3=#host_nam,p4=#host_nam 
        blbc    r0,print 
        cmpw    #ss$_normal,iosb 
        beqlu   print 
        movzwl  iosb,r0 
print: 
        movl    r0,r10 
        pushab  title1 
        calls   #1,g^lib$put_output 
        pushab  host_d 
        calls   #1,g^lib$put_output 
        pushab  title 
        calls   #1,g^lib$put_output 
        pushab  host_nam 
        calls   #1,g^lib$put_output 
        movl    r10,r0 
exit: 
        ret 
        .end start

Example 4-8 IO$_ACPCONTROL Function (C Programming) 

#module gethost_addr 
/* 
**++ 
** 
**  This example gets host address for the given host name 
**  using the Internet ACP Control I/O function IO$_ACPCONTROL 
**            
** 
**-- 
**/ 
 
/* 
**  INCLUDE FILES 
*/ 
 
#include <descrip.h> 
#include <iodef.h> 
#include <tcpip$inetdef.h> 
 
gethost_addr (addr) 
 
  int *addr; 
 
{ 
 
/* Descriptor for Inet device name */ 
 
struct dsc$descriptor Inet_dev =          
  {11, DSC$K_CLASS_S, DSC$K_DTYPE_T, "TCPIP$DEVICE:" }; 
 
/* Descriptor for the host name for which to get the Internet address */ 
 
struct dsc$descriptor host_name = 
  {6, DSC$K_CLASS_S, DSC$K_DTYPE_T, "lassie" }; 
 
/* Descriptor for ACP command */ 
 
struct dsc$descriptor command = 
  {0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0 }; 
 
/* Descriptor for host address */ 
 
struct dsc$descriptor host_ad = 
  {0, DSC$K_CLASS_S, DSC$K_DTYPE_T, 0 }; 
 
 
  int status ;            /* Return status                 */ 
  int iosb [2] ;          /* I/O status block              */ 
  short channel ;         /* INET dev channel              */ 
  short retlen ;          /* Word to return address length */ 
 
/* 
** ACP command: INETACP$C_TRANS - If this bit set, the Internet 
** address will be returned as a long word integer value.       
** INETACP_FUNC$C_GETHOSTBYNAME indicates that it is a function 
** to get the host address given the host name.            
*/ 
  int comm = INETACP$C_TRANS * 256 + INETACP_FUNC$C_GETHOSTBYNAME ; 
                /* byte 1,2,0,0 */ 
 
   int addr_buff[8];      /* buffer for ACP output */ 
     
/* 
** INET ACP command 
*/    
        command.dsc$a_pointer = &comm ; 
        command.dsc$w_length = sizeof(comm) ; 
 
/* 
** Descriptor for ACP output 
*/ 
        host_ad.dsc$a_pointer = &addr_buff ; 
        host_ad.dsc$w_length = sizeof(addr_buff) ; 
 
/* 
**  Assign a channel to INET  device 
*/ 
        status = SYS$ASSIGN(&Inet_dev, 
                            &channel, 
                            0, 
                            0); 
        if ((status & 1) == 0) { 
        printf("Failed to assign channel to INET device \n"); 
        return(status); 
        } 
 
/* 
** Get the Host address (longword) 
*/ 
        status = SYS$QIOW(1, 
                          channel,          /* Channel number */ 
                          IO$_ACPCONTROL,   /* I/O function */ 
                          iosb,             /* I/O status */ 
                          0, 
                          0, 
                          &command,         /* P1  command */ 
                          &host_name,       /* P2  host name */ 
                          &retlen,          /* P3  adrs to ret length */ 
                          &host_ad,         /* P4  adrs output */ 
                          0, 0); 
       if (((status & 1) && (iosb[0] & 1)) == 0) { 
          printf("Failed to get INET address for host %s \n", 
                  host_name.dsc$a_pointer); 
          return (status) ; 
        } 
/* 
** Return the host Internet address 
*/ 
        addr = addr_buff[0]; 
 
/* 
** Deassign the INET dev channel 
*/ 
        SYS$DASSGN (channel); 
 
        return (status); 
}

Previous Next Contents Index