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


Previous Contents Index

3.6 Specifying an Input Parameter List

Use the p5 argument with the IO$_WRITEVBLK and IO$_SETMODE functions to specify input parameter lists. The p5 argument contains the address of a descriptor that points to, and specifies the contents of, an item list descriptor. Figure 3-2 illustrates how the p5 argument specifies the item list.

Figure 3-2 Specifying an Input Parameter List


Table 3-7 defines the descriptor fields, which also apply to buffer lists where indicated.

Table 3-7 p5 Descriptor Fields
Field Description
length A word specifying the length (in bytes) of the requested item list (also applies to buffer lists).
parameter type A user-supplied, word-length symbolic code that specifies the type or class of parameter to set. The parameter types are:
  TCPIP$C_DATA or zero to specify read or write buffers (for buffer lists only)
  TCPIP$C_SOCKOPT to specify socket options (for parameter lists only)
  TCPIP$C_TCPOPT to specify TCP/IP options (for parameter lists only)
  TCPIP$C_IPOPT to specify raw IP options (for parameter lists only)
  TCPIP$C_IOCTL to specify I/O control options (for parameter lists only)
  With the IO$_SENSEMODE function, use either TCPIP$C_SOCKOPT or TCPIP$C_IOCTL parameter types.
  The TCPIP$INETDEF symbol definition file defines the parameter type, which applies to all the descriptors in a list. See the $QIO routine descriptions in this chapter for details about the parameter types.
address A quadword (Alpha) or longword (VAX) that specifies the starting address of the item list (also applies to buffer lists).

The rest of this chapter explains how to use parameters to describe specific information. This chapter also contains a sample DEC C program that specifies IOCTL parameters. There are additional sample programs in TCPIP$EXAMPLES that contain the different functions and parameters.

3.7 Specifying an Output Parameter List

Use the p6 argument with the IO$_READVBLK or the IO$_SENSEMODE function to specify an output parameter list. The p6 argument passes the address of a descriptor that points to, and specifies the contents of, a descriptor list. The list consists of contiguous blocks of memory that contain one or more DIGITAL TCP/IP Services for OpenVMS descriptors.

Figure 3-3 illustrates how the p6 argument specifies the item_list.

Figure 3-3 Specifying an Output Parameter List


Table 3-8 defines the descriptor fields, which also apply to buffer lists where indicated.

Table 3-8 p6 Descriptor Fields
Field Description
length A word that specifies the length (in bytes) of the buffer into which the service writes the information. You supply the integer for this value. The length needed depends on the parameter name specified in the parameter name field of the descriptor on the list. If the value of the buffer length is too small, the service truncates the data (also applies to buffer lists.)
parameter type A user-supplied, word-length symbolic code that specifies the type or class of parameter to get. The parameter types are:
  • TCPIP$C_DATA or zero for read or write buffers (for buffer lists only)
  • TCPIP$C_SOCKOPT to specify socket options (for parameter lists only)
  • TCPIP$C_TCPOPT to specify TCP/IP options (for parameter lists only)
  • TCPIP$C_IPOPT specify raw IP options (for parameter lists only)
  • TCPIP$C_IOCTL to specify I/O control options (for parameter lists only)

With the IO$_SENSEMODE function, use either TCPIP$C_SOCKOPT or TCPIP$C_IOCTL parameter types.

The TCPIP$INETDEF symbol definition file defines the parameter type, which applies to all the descriptors in a list. See the $QIO routine descriptions in this chapter for details about the parameter types.

address A quadword (Alpha) or longword (VAX) from which the service reads the starting address of the user buffer containing data (also applies to buffer lists).

3.8 Specifying the Socket Name

With BSD Versions 4.3 and 4.4, you specify the socket name with the p3 or p4 argument with the IO$_ACCESS, IO$_READVBLK, IO$_WRITEVBLK, IO$_SENSEMODE, and IO$_SETMODE functions. This parameter takes the form of an address of an item_list_2 or item_list_3 descriptor.

The parameter name for p4 is TCPIP$C_SOCK_NAME, which is defined in the TCPIP$INETDEF symbol definition file.

The p3 argument must contain an item_list_2 descriptor, unless you use GETSOCKETNAME. In this case, p3 must contain an item_list_3 descriptor.

With BSD Version 4.3, you specify the local or remote socket names as illustrated in Figure 3-4.

Figure 3-4 Specifying the Local or Remote Socket Name (BSD Version 4.3)


With BSD Version 4.4, you specify the local and remote socket names as illustrated in Figure 3-5. Note that the first byte in the data structure is the length field. To accommodate this field, use the IO$M_EXTEND function modifier for all system services that can take a socket address as an input or output parameter (for example: IO$_ACCESS, IO$_READVBLK, and IO$_SENSEMODE).

Figure 3-5 Specifying the Local or Remote Socket Name (BSD Version 4.4)


The descriptor that the p3 and p4 arguments specify points to a 16-byte data structure called sockaddr_in. This data structure consists of the address domain (2 bytes), port number (2 bytes), host internet address (4 bytes), and unused bytes (8 bytes). Table 3-9 describes the sockaddr_in fields.

Table 3-9 sockaddr_in Fields
Field Description
address domain INET domain (set by default).
port number An integer in the range 0 to 65,535. Port numbers 1 to 1023 require either system UIC, SYSPRV, or BYPASS privileges when assigned. If you specify zero when binding a socket name, the system assigns an available port.
host internet address A longword 4-byte integer.

3.9 Specifying Socket Options, Protocol Options, and I/O Control Parameters

To set socket options, you use item_list_2 descriptors.

Figure 3-6 shows how to set socket options.

Figure 3-6 Setting Socket Options


The TCPIP$INETDEF symbol definition file defines the TCPIP$C_SOCKOPT parameter name for the socket options. For TCP options, use the TCPIP$C_TCPOPT parameter. For IP options, use the TCPIP$C_IPOPT parameter.

Figure 3-7 illustrates how to set I/O Control (IOCTL) parameters.

Figure 3-7 Setting IOCTL Parameters


The TCPIP$INETDEF symbol definition file specifies the TCPIP$C_IOCTL name. You specify the I/O control (IOCTL) parameters with an item_list_2 descriptor that lists its specifications. Each parameter field contains two longwords: the first is the IOCTL command value defined by the $SIOCDEF macro; the second is an IOCTL parameter structure address. During startup, the TCPIP$INETDEF symbol definition file specifies the values for the $SIOCDEF macro.

To get socket options, you use item_list_3 descriptors.

Figure 3-8 illustrates how to get socket options.

Figure 3-8 Getting Socket Options


Figure 3-9 illustrates how to get IOCTL parameters.

Figure 3-9 Getting IOCTL Parameters



Chapter 4
OpenVMS System Services Reference

This chapter provides detailed use and reference information about the OpenVMS system services used to write internet applications. The chapter also describes the Internet I/O function codes.

The descriptions of the system services and I/O function codes in this chapter are written specifically for internet programmers. For a general description of these system services and I/O function codes, see the OpenVMS reference manuals for system services.

Table 4-1 lists the equivalent C Socket routine for each system service and I/O function code in this chapter. See Chapter 6 for descriptions of C Socket routines.

Table 4-1 OpenVMS System Service and Equivalent C Socket Call
OpenVMS System Service C Socket Call
$ASSIGN open()
$CANCEL close()
$DASSGN close()
$GETDVI getpeername(), getsockname(), getsockopt()
$QIO bind(), listen()
IO$_ACCESS connect(), accept()
IO$_ACPCONTROL gethostbyname(), gethostbyaddr(), getnetbyname(), getnetbyaddr()
IO$_DEACCESS close(), shutdown()
IO$_READVBLK read(), recv(), recvfrom(), recvmsg()
IO$_SENSEMODE getsockopt(), ioctl()
IO$_SENSECHAR getsockopt(), ioctl()
IO$_SETMODE socket(), bind(), listen(), setsockopt(), ioctl()
IO$_SETCHAR socket(), bind(), listen(), setsockopt(), ioctl()
IO$_WRITEVBLK send(), sendto(), sendmsg(), write()

4.1 System Service Descriptions

This section describes the OpenVMS system service routines used to write internet applications.


$ASSIGN

The Assign I/O Channel service provides a calling process with an I/O channel. This makes it possible for the calling process to perform I/O operations on the internet pseudodevice.

Format

SYS$ASSIGN devnam, chan, [acmode], [mbxnam]


Returns


OpenVMS usage: longword (unsigned)
type: write only
access: 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.


Arguments

devnam


OpenVMS usage: device_name
type: character-coded text string
access: read only
mechanism: by fixed-length string descriptor

Name of the device to which $ASSIGN is to assign a channel. The devnam argument specifies the address of a character string descriptor pointing to the pseudodevice name string. The character string contains TCPIP$DEVICE:.

chan


OpenVMS usage: channel
type: word (unsigned)
access: write only
mechanism: by reference

Number of the channel that is assigned. The chan argument is the address 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. The acmode argument specifies the access mode. I/O operations on the channel can be performed only from equal and more privileged access modes.

mbxnam


OpenVMS usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor---fixed length string descriptor

This argument is not used.

Description

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 TCPIP$DEVICE:, the internet software creates a new pseudodevice called BGn, where n is a unique unit number. The corresponding channel number is used in any subsequent operation requests for that device.

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.

Two programming examples for the $ASSIGN routine follow this command description. Example 4-1 uses the MACRO-32 programming language and Example 4-2 uses the C programming language.


Condition Values Returned

SS$_NORMAL Service successfully completed.
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$_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 This warning code indicates that the specified device does not exist.

Example 4-1 $ASSIGN System Service (MACRO-32)

 
        .title  Assign 
        .ident  /01/ 
 
        $inetsymdef             ; INET symbols 
 
dev:    .ascid  /tcpip$device:/           ; INET device name 
channel:        .word   0       ; INET channel 
 
        .entry   start,^m<> 
; 
;       Assign an INET  device 
; 
        $assign_s       devnam=dev, chan=channel 
        . 
        . 
        . 
        .end start 

Example 4-2 $ASSIGN System Service (C Programming)

#module assgn_chan 
/* 
**++ 
**      
** This example assigns a channel to INET device 
** using system service SYS$ASSIGN           
** 
**-- 
*/ 
 
 
/* 
**  INCLUDE FILES 
*/ 
 
#include <descrip.h> 
 
assgn_chan(channel) 
 
     unsigned short ;          /* INET channel */ 
{ 
     int status ;            /* For return status */ 
 
 /* Descriptor for Inet device name */ 
 
     $DESCRIPTOR (dev, "TCPIP$DEVICE:");     
 
/* 
** Assign a channel to INET device 
*/ 
          
     status = SYS$ASSIGN( &dev, 
                          &channel, 
                          0, 
                          0) ; 
      if ((status & 1) == 0) { 
         printf("Failed to assign channel to INET device \n") ; 
         return(status) ; 
          } 
     return(status) ; 
/* 
** channel will have the assigned 
** channel number      
*/ 
     
} 


$CANCEL

This routine cancels all pending I/O requests on a specified channel.

The equivalent C Socket call is the close() routine.


Format

SYS$CANCEL chan


Returns


OpenVMS usage: longword (unsigned)
type: write only
access: 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.


Arguments

chan


OpenVMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value

The channel on which the routine cancels the I/O. The chan argument is a word containing the channel number.

Description

To cancel I/O on a channel, the access mode of the calling process must be equal to or more privileged than the access mode of the process that made the original channel assignment.

The $CANCEL service requires system dynamic memory and uses the process's buffered I/O limit (BIOLM) quota.

Two programming examples for the $CANCEL routine follow this command description. Example 4-3 uses the MACRO-32 programming language and Example 4-4 uses the C programming language.

When a request currently in progress is canceled, the driver is notified immediately. Actual cancellation may or may not occur immediately, depending on the logical state of the driver. When cancellation does occur, the action taken for I/O in progress is similar to that taken for queued requests. For example:

  1. The specified event flag is set.
  2. The first word of the IOSB of the I/O request you are canceling is set to SS$_CANCEL if the I/O request is queued or to SS$_ABORT if the I/O operation is in progress.
  3. If the asynchronous system trap (AST) is specified, it is queued.

For proper synchronization between this service and the actual canceling of I/O requests to take place, the issuing process must wait for the I/O process to complete normally. Note that the I/O has been canceled. Outstanding I/O requests are canceled automatically at image exit.


Condition Values Returned

SS$_NORMAL Service successfully completed.
SS$_ABORT A physical line went down during a network connect operation.
SS$_CANCEL Warning code. The I/O operation was canceled by executing a $CANCEL system service.
SS$_EXQUOTA The process has exceeded its buffered I/O limit (BIOLM) quota.
SS$_INSFMEM Insufficient system dynamic memory is available to cancel the I/O.
SS$_IVCHAN An invalid channel was specified (that is, a channel number of zero or a number larger than the number of channels available).
SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode.

Example 4-3 $CANCEL System Service (MACRO-32)

        .title  Cancel 
        .ident  /01/ 
 
        $inetsymdef             ; INET symbols 
 
dev:    .ascid  /tcpip$device:/           ; INET device name 
channel:        .word   0       ; INET channel 
 
        .entry   start,^m<> 
; 
;       Assign an INET  device 
; 
        . 
        . 
        . 
; 
;       Cancel I/O on INET  device 
; 
        $cancel_s       chan=channel 
        . 
        . 
        . 
        .end start 
 

Example 4-4 $CANCEL System Service (C Programming)

#module cancel_io 
/* 
**++ 
**      
** This example cancels all pending I/O requests on the 
** specified channel using system service SYS$CANCEL           
** 
**-- 
*/ 
 
 
/* 
**  INCLUDE FILES 
*/ 
 
 
cancel_io(chan) 
   
       short chan ;     /* INET channel on which I/O is to be canceled */ 
{ 
 
       int status ;     /* For return status */ 
/* 
** Cancel the pending I/Os 
*/          
     (status = SYS$CANCEL(chan)) ; 
     if ((status & 1) == 0) { 
      printf("Failed to cancel pending I/Os \n") ; 
      return(status) ; 
          } 
     return(status) ;     
} 


Previous Next Contents Index