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

2.19.2 Data Structures for OpenVMS System Services Programming

The data types or data structures locally define unsigned entities. The following lists the available data structures. 


*/ 
**  Locally defined data structures. 
/* 
    typedef struct IosbStruct 
        { 
        unsigned short cond_value; 
        unsigned short count; 
        unsigned long  info; 
        }    iosbType,     /* For one occurrence */ 
            *iosbPtr;      /* For a pointer to an occurrence */ 
 
    typedef struct SocketParamStruct 
        { 
        unsigned short protocol; 
        unsigned char  type; 
        unsigned char  family; 
        }    socketParamType, /* For one occurrence */ 
            *socketParamPtr;  /* For a pointer to an occurrence*/ 
 
/* 
 
** 
** IP Address information. 
** 
*/ 
    typedef struct  IPAddrInfoStruct 
        { 
        unsigned int   length; 
                 char *address; 
        unsigned int  *retLenPtr; 
        }    iPAddrInfoType, /* For one occurrence */ 
            *iPAddrInfoPtr;  /* For a pointer to an occurrence*/ 
 
/* 
** 
** Item List structure for getting and setting socket options. 
** 
*/ 
    typedef struct  ILSockOptStruct 
        { 
        unsigned short  length; 
        unsigned short  code; 
                 char  *optStructAddr; 
        }    iLSockOptType,  /* For one occurrence */ 
            *iLSockOptPtr,   /* For a pointer to an occurrence*/ 
             iLSockOptArr[]; /* For an array of occurrences*/ 
 
/* 
** 
** Set socket options structure. 
** 
*/ 
    typedef struct  SetSockOptStruct 
        { 
        unsigned short  length; 
        unsigned short  code; 
                 char  *optBuffAddr; 
        }    setSockOptType,  /* For one occurrence */ 
            *setSockOptPtr,   /* For a pointer to an occurrence*/ 
             setSockOptArr[]; /* For an array of occurrences*/ 
/* 
** 
** Get socket options structure. 
** 
*/ 
      typedef struct  GetSockOptStruct 
          { 
          unsigned short  length; 
          unsigned short  code; 
                   char  *optBuffAddr; 
          int            *retLength; 
          }    getSockOptType,  /* For one occurrence */ 
              *getSockOptPtr,   /* For a pointer to an occurrence*/ 
               getSockOptArr[]; /* For an array of occurrences*/ 
/* 
/* 
** 
**  MACRO DEFINITIONS 
** 
*/ 
** 
*/ 
 
#define MaxBuff              80 
#define SERVER_PORT_NUMBER   5321 
#define SERVER_QLENGTH       4

2.19.3 Support Routines for OpenVMS System Services Programming

The support routines provide two functions. One routine closes and deassigns the socket from the network device. The other routine signals errors and exits. The contents of the support routines are as follows: 


 
(1)
 
**  FUNCTION: cleanup() 
** 
**  Close the socket and deassign it from the network device. 
** 
**  RETURNS: none 
** 
*/ 
static void cleanup( int IOChannel ) 
{ 
    iosbType   iosb;             /* I/O result status */ 
    int        sysSrvSts;        /* System Service status */ 
 
    /* Attempt to close the socket. */ 
    sysSrvSts = sys$qiow( 0,               /* efn.v | 0 */ 
                          IOChannel,       /* chan.v */ 
                          IO$_DEACCESS,    /* func.v */ 
                          &iosb,           /* iosb.r | 0 */ 
                          0, 0,            /* astadr, astprm: UNUSED */ 
                          0, 0, 0, 0, 0, 0 /* p1 -> p6 UNUSED */ ); 
    sys$dassgn( IOChannel ); 
 
} /* END cleanup() */ 
 
 
(2)
**  FUNCTION: errorExit() 
** 
**  Signal any errors and exit. 
** 
**  RETURNS: none 
** 
*/ 
static void errorExit( int            sysSrvSts,  /* System Service status */ 
                       unsigned short iosbCond )  /* I/O result status */ 
{ 
    if(( sysSrvSts & 1  ) != 1  ) /* Validate the system service status. */ 
        lib$signal( sysSrvSts ); 
 
    if((  iosbCond & 1  ) != 1 )  /* Validate the IO status. */ 
        lib$signal( iosbCond ); 
 
    exit( SS$_NORMAL ); 
} /* END errorExit() */

  1. The support routine that closes and deassigns the socket.
  2. The support routine that signals errors and exits.

2.20 Compiling and Linking Compaq's C Language Programs

The examples in this chapter were written to use the VAX C compiler but should also be compatible with the DEC C compiler. However, if you are using the DEC C or DEC C++ compiler and are having difficulty compiling some of these programs, Compaq recommends using either the VAX C compiler or the DEC C or DEC C++ compiler with the following qualifiers: 


$ /STANDARD=VAXC/PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES

2.20.1 Linking Programs Using BSD Version 4.3

If you compile your program using DEC C, enter the LINK command as follows: 


$ LINK MAIN

Do not specify SYS$LIBRARY:TCPIP$IPC.OLB because the DEC C compiler does not use this library. Also, you do not need to specify TCPIP$IPC_SHR because the DEC C compiler uses this shareable image by default.

If you compile your program using VAX C, enter the LINK command as follows: 


$ LINK MAIN, SYS$LIBRARY:TCPIP$IPC/LIB, SYS$INPUT/OPTIONS - 
_$ SYS$SHARE:TCPIP$IPC_SHR/SHARE

Use the /OPTIONS qualifier for executable images. TCPIP$IPC.OLB contains the transfer vectors used to resolve the socket routine references to the VAXCRTL.

2.20.2 Compiling and Linking Programs Using BSD Version 4.4

To compile and link your DEC C or VAX C program using BSD Version 4.4, enter the following commands, where filename is the name of your client or server program: 


$ CC/NOOPT/STANDARD=VAXC/PREFIX=ALL/EXTERN_MODEL=STRICT_REFDEF - 
_$ /DEFINE=(_SOCKADDR_LEN) filename.C 
 
$ LINK/MAP filename, TCPIP$LIBRARY:TCPIP$LIB/LIB

Chapter 3
Using the $QIO System Service

This chapter describes how to use the $QIO system service and its data structures with DIGITAL TCP/IP Services for OpenVMS.

After you create an internet pseudodevice and assign a channel to it, use the $QIO system service for I/O operations.

3.1 $QIO System Service Variations

The two variations of the $QIO system service are:

The only difference between the $QIO and $QIOW service calls is the service name. The service call parameters are the same.

3.2 $QIO Syntax

The $QIO system service has the following syntax:

SYS$QIO [efn],chan,func[,iosb] [,astadr][,astprm][,p1][,p2] [,p3][,p4][,p5][,p6]

Table 3-1 describes each argument.

Table 3-1 $QIO Arguments
Argument Description
efn Event flag number
chan I/O channel
func Internet pseudodevice function code and modifier
iosb I/O status block
astadr AST (asynchronous system trap) service routine
astprm AST parameter to be passed
p1, p2, p3, p4, p5, p6 Function-dependent $QIO parameters

3.2.1 $QIO Function-Dependent Parameters

Table 3-2 contains the symbol definitions for the $QIO arguments p1 through p6. Use the standard mechanism for the programming language you are using to include these symbol definitions in your program.

Table 3-2 Internet Symbol Definition Files
File Name Language
TCPIP$INETDEF.H DEC C or VAX C
TCPIP$INETDEF.FOR VAX Fortran
TCPIP$INETDEF.PAS VAX PASCAL
TCPIP$INETDEF.MAR MACRO-32
TCPIP$INETDEF.PLI VAX PL/1
TCPIP$INETDEF.R32 BLISS-32
TCPIP$INETDEF.ADA VAX Ada
TCPIP$INETDEF.BAS VAX BASIC

3.3 Common $QIO Functions

Table 3-3 lists the $QIO functions commonly used in internet applications.

Note
The IO$_SETMODE and IO$_SETCHAR service calls function identically. All references to the IO$_SETMODE system call, its arguments, options, modifiers, and condition values returned also apply to the IO$_SETCHAR system call, which is not explicitly described in this book.

Table 3-3 $QIO Functions
Function Description
$QIO(IO$_SETMODE) $QIO(IO$_SETCHAR) Creates the socket by setting the internet domain, protocol (socket) type, and protocol of the device socket.
  Binds a name (local address and port) to the socket.
  Defines an internet pseudodevice as a listener on a TCP/IP server.
  Specifies socket options.
$QIO(IO$_ACCESS) Initiates a connection request from a client to a remote host using TCP.
  Specifies the peer where you can send datagrams.
  Accepts a connection request from a TCP/IP client when used with the IO$M_ACCEPT modifier.
$QIO(IO$_WRITEVBLK) Writes data (virtual block) from local host to remote host for stream sockets, datagrams, and raw IP.
$QIO(IO$_READVBLK) Reads data (virtual block) from remote host to local host for TCP/IP, UDP/IP, or IP layers.
$QIO(IO$_DEACCESS) Disconnects the link established between two communication agents through an ACCESS function TCP/IP.
  Shuts down the communication link when used with the IO$M_SHUTDOWN modifier. You can shut down the receive, transmit, or both portions of the link.
$QIO(IO$_SENSEMODE) Obtains socket information.

3.4 $QIO Arguments

You pass two types of arguments with $QIO system services: function-independent arguments and function-dependent arguments. The following sections provide information on $QIO system service arguments.

3.4.1 Device- and Function-Independent $QIO Arguments

Table 3-4 describes the device- and function-independent $QIO arguments.

Table 3-4 Device- and Function-Independent Arguments
Argument Description
efn A longword value of the event flag number that the $QIO system service sets when the I/O operation completes.
chan A longword value that contains the number of the I/O channel. The $QIO system service uses only the low-order word.
func A longword value that specifies the internet pseudodevice functions and function modifiers that define the specified operation.

Function modifiers affect the operation of a specified function. In MACRO-32, you use the exclamation point (!) to logically .OR the function and its modifier. In DEC C, you use the vertical bar (|). This book 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.
astadr Address of the asynchronous system trap (AST) routine to be executed when the I/O operation is completed.
astprm A quadword (Alpha) or longword (VAX) value containing the value to be passed to the AST routine.

Figure 3-1 shows the I/O status block (iosb) for the IO$_SETMODE, IO$_SENSEMODE, IO$_READVBLK, IO$_WRITEVBLK functions, and Table 3-5 describes each field.

Figure 3-1 I/O Status Block

Table 3-5 I/O Status Block Fields
Field Description
OpenVMS completion status field The final status of the operation. A standard OpenVMS system service status (that is, SS$_xx). The OpenVMS completion values are defined in the <sysef.h> file provided with DEC C.
DIGITAL UNIX completion status field The UNIX equivalent of the OpenVMS completion status code field. A word-length completion value returned to IO$_SETMODE and IO$_SENSEMODE, or on all I/O functions that are completed with an error.

The UNIX completion values are defined in the <errno.h> file provided with DEC C and in the TCPIP$INETDEF symbol definition file.

The word-length status value is returned by the $QIO system service when the I/O operation has been completed.

Parameter address Address of the parameter or error.
Transfer size Number of bytes transferred during a read or write operation when the OpenVMS completion status field indicates success.
  Read/write operations that complete with an error return the UNIX completion status instead of the transfer size.
Buffer address Address of the buffer where the data was transferred.

3.4.2 Function-Dependent $QIO Arguments

Specify the p1, p2, p3, p4, p5, and p6 arguments. You can pass a parameter as a value, a reference to the address of a value, or a descriptor address. Table 3-6 lists arguments p1 through p6 for the $QIO system service calls.

Table 3-6 Function-Dependent$QIO Arguments
$QIO p1 p2 p3 p4 p5 p6
IO$_ACCESS Not used Not used Remote socket name 2, 5 Not used Not used Not used
IO$_ACCESS|
IO$M_ACCEPT 		Not used Not used Returned remote socket name 4, 5 Channel number (word) 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, 7 Not used Not used
IO$_READVBLK Buffer 3 Buffer size 1 Remote socket name 4 Flags 1, 7 Not used Output buffer list 2, 6
IO$_READVBLK|
IO$M_INTERRUPT 		Buffer 3 Buffer size 1 Not used Not used Not used Not used
IO$_WRITEVBLK Buffer 3 Buffer size 1 Remote socket name 2 Flags 1, 6 Input buffer list 2 Not used
IO$_WRITEVBLK|
IO$M_INTERRUPT 		Buffer 3 Buffer size 1 Not used Not used Not used Not used
IO$_SETMODE Socket char 3 Not used Local socket name 2, 5 Backlog limit 1 Input parameter list 2 Not used
IO$_SENSEMODE Not used Not used Local socket name 4, 5 Remote socket name 4, 5 Not used Output parameter list 4

1By value
2Address of an item_list_2 descriptor
3By reference
4Address of an item_list_3 descriptor
5Buffer is a sockaddr_in structure
6Buffer is an iovec structure
7Value is a mask

3.5 Item Lists and Item List Descriptors

An item list is a contiguous block of memory that contains item list descriptors. An item list descriptor points to parameters and contains fields that describe the data. TCP/IP Services uses two item list formats:

These formats do not necessarily correspond to formats used elsewhere in OpenVMS programming.

The function you call determines which format is required. When you specify a item_list_2 descriptor, it either passes a parameter to the system or returns a parameter from the system (depending on the function's requirements). When a item_list_2 descriptor returns the parameter from the system, the system returns only that parameter.

When you specify an item_list_3 descriptor, it returns a parameter from the system. In addition to the parameter itself, the system also returns the length of the parameter.

Previous Next Contents Index