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


Previous | Contents

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, "UCX$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
mechanism: 0

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  /ucx$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) ;     
} 


$DASSGN

This service deassigns (releases) an I/O channel that was acquired using the Assign I/O Channel ($ASSIGN) service.

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


Format

SYS$DASSGN chan


Returns


OpenVMS usage: longword (unsigned)
type: read/write
access: by value
mechanism: 0

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

Number of the I/O channel to be deassigned. The chan argument is a word containing this number.

DESCRIPTION

After all communication is completed, use the $DASSGN system service to free an I/O channel. A $DASSGN operation issued on a channel associated with an internet pseudodevice does the following:
  1. Ends all pending operations to send or receive data at $QIO level ($CANCEL system service).
  2. Clears the port associated with the channel. When issuing the $DASSGN system service for TCP/IP sockets, the socket remains until the connection is closed on both sides, local and remote.
  3. Ends all communications with the internet pseudodevice that the I/O channel identifies.
  4. Frees the channel associated with the internet pseudodevice. An I/O channel can be deassigned only from an access mode equal to or more privileged than the access mode from which the original channel assignment was made.

I/O channels assigned from user mode are automatically deassigned at image exit.

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


Note

Even after a $DASSGN has been issued, a TCP socket may remain until the TCP close timeout interval expires. The default and maximum timeout interval is 10 minutes if the peer host is not responding or 30 seconds after acknowledging the socket close. Although, the TCP socket is open, you cannot make reference to that socket after issuing a $DASSGN.


Condition Values Returned

SS$_NORMAL Service successfully completed.
SS$_IVCHAN An invalid channel number 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 is assigned from a more privileged access mode.

Example 4-5 $DASSGN System Service (MACRO-32)


 
        .title  Dassign 
        .ident  /01/ 
 
        $inetsymdef             ; INET symbols 
 
exit 
purge 
:    .ascid  /ucx$device:/           ; INET device name 
channel:        .word   0               ; INET channel 
 
        .entry   start,^m<> 
        . 
        . 
        . 
; 
;       Deassign an INET  device 
; 
        $Dassgn_s        chan=channel 
        . 
        . 
        . 
        .end start 
 

Example 4-6 $DASSGN System Service (C Programming)


#module dassgn_chan 
/* 
**++ 
**      
** This example deassigns the specified channel 
** using system service SYS$DASSNG           
** 
**-- 
*/ 
 
 
/* 
**  INCLUDE FILES 
*/ 
 
 
dassgn_chan(chan) 
   
       short chan ;     /* INET channel which is to be deassigned */ 
{ 
 
     int status ;      /* For return status */ 
          
/* 
** Deassign the channel 
*/ 
     status = SYS$DASSGN(chan) ; 
     if ((status & 1) == 0) { 
       printf("Failed to deassign the channel\n") ; 
       return(status) ; 
          } 
     return(status) ;     
} 


$GETDVI

This service returns information about primary and secondary device characteristics of the internet pseudodevice.

The $GETDVI service is completed asynchronously. It returns to the caller after queuing the information request without waiting for the requested information to be returned.

For synchronous completion, use the Get Device/Volume Information and Wait ($GETDVIW) service. The $GETDVIW service is identical to the $GETDVI service except that $GETDVIW returns to the caller with the requested information.

The equivalent C Socket calls are the getpeername(), getsockname(), and getsockopt() routines.


Format

SYS$GETDVI [efn],[chan], [devnam],itmlst,[iosb],[astadr], [astprm],[nullarg]


Returns


OpenVMS usage: longword (unsigned)
type: write only
access: by value
mechanism: 0

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

efn


OpenVMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value

Number of the event flag to be set when $GETDVI returns the requested information. The efn argument is a longword containing this number.

When the request is initiated, $GETDVI clears the specified event flag (or event flag 0 if efn was not specified). When $GETDVI returns the requested information, it sets the specified event flag (or event flag 0).

chan


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

Number of the I/O channel assigned to the device about which information is desired. The chan argument is a word containing this number.

devnam


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

The name of the device for which $GETDVI returns information. The devnam argument is the address of a character string descriptor pointing to the name string.

The device name string can be either a physical device name or a logical name. If the first character in the string is an underscore (_), the string is considered a physical device name. Otherwise, the string is considered to be a logical name. In that case, logical name translation is done until either a physical device name is found or the system default for number of translations has been reached.

If the device name string contains a colon, the colon and the characters that follow it are ignored.

To identify a device to $GETDVI, specify either the chan argument or the devnam argument, but not both. If both arguments are specified, the chan argument is used.

If neither chan nor devnam is specified, $GETDVI uses a default value of zero for chan.

itmlst


OpenVMS usage: item_list
type: longword (unsigned)
access: read only
mechanism: by reference

Item list specifying which information about the device is to be returned. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a length and item code of zero. Figure 4-1 depicts the format of an item descriptor.

Figure 4-1 Single Item Descriptor



$GETDVI Item Descriptor Fields

$GETDVI Item Codes

Table 4-2 $GETDVI Item Code Descriptions
Item Code Description
DVI$_ACPTYPE A 4-byte hexadecimal number. The DVI$_ACP_TCP symbol defines the ACP type code that $GETDVI can return. This symbol is defined in the UCX$INETDEF symbol definition file.
DVI$_DEVCHAR Returns device-independent characteristics as a 4-byte vector. Each characteristic is represented by a bit. When $GETDVI sets a bit, the device has the corresponding characteristic. Each bit in the vector has a symbolic name. These symbolic names are defined by the $DEVDEF macro, and are listed in Table 4-3.

Table 4-3 Symbolic Names for$GETDVI
Symbol Device Type
DVI$_NET Network device
DVI$_AVL Available
DVI$_MNT Mounted
DVI$_IDV Input device
DVI$_ODV Output device

DVI$_STS

When DVI$_STS is specified, $GETDVI returns the device unit status as a 4-byte vector. Each bit in the vector, when set, corresponds to a symbolic name that is defined by the $UCBDEF macro. These symbols are defined in Table 4-4.

Table 4-4 Device Unit Status Symbolic Names
Symbol Device Type
UCB$M_ONLINE Online
UCB$M_TEMPLATE Template

iosb


OpenVMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference

The iosb argument signifies the I/O status block that receives the final completion status code. The iosb is the address of the quadword I/O status block.

When the iosb argument is specified, $GETDVI sets the quadword to zero when the request is initiated. When the request is completed, a condition value is returned to the first longword. The second longword is reserved for DIGITAL.

Although the iosb argument is optional, DIGITAL strongly recommends that you specify it for the following reasons:

astadr


OpenVMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference

AST service routine to be executed when $GETDVI is completed. The astadr argument is the address of the entry mask of this routine.

If astadr is specified, the AST routine executes at the same access mode as the caller of the $GETDVI service.

astprm


OpenVMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value

AST parameter to be passed to the AST service routine specified by the astadr argument. The astprm argument contains a longword parameter value.

nullarg


OpenVMS usage: null_arg
type: quadword (unsigned)
access: read only
mechanism: by reference

Place-holding argument. This argument is reserved for DIGITAL.

DESCRIPTION

The chan argument can be used only if the channel has already been assigned and the caller's access mode is equal to or more privileged than the access mode from which the original channel assignment was made.

The $GETDVI system service does not need to have a channel assigned to the device about which information is desired.

The $GETDVI system service returns information about both primary and secondary characteristics of the device. By default, $GETDVI returns information about the primary characteristics only.

To obtain information about secondary device characteristics, the item code specifying the information desired must be merged (ORed) with the code DVI$M_SECONDARY.

Information about primary and secondary devices can be obtained in a single call to $GETDVI.

In most cases, the two sets of characteristics (primary and secondary) returned by $GETDVI are identical. However, the two sets provide different information in the following cases:

Unless otherwise stated in the item code description, $GETDVI returns information about the local node only.


Condition Values Returned

SS$_NORMAL Service successfully completed.
SS$_ACCVIO The device name string descriptor, device name string, or itmlst argument cannot be read or the buffer or return length longword cannot be written by the caller.
SS$_BADPARAM The item list contains an invalid item code, or the return length address field in an item descriptor specifies less than 4 bytes for the return length information.
SS$_EXASTLM The process has exceeded its AST limit quota.
SS$_IVCHAN An invalid channel number was specified (that is, a channel number of zero or a number greater than the number of channels).
SS$_IVDEVNAM The device name string contains invalid characters or neither the devnam nor the chan arguments was specified.
SS$_IVLOGNAM The device name string has either a length of zero or more than 63 characters.
SS$_NONLOCAL This warning code indicates that the device is on a remote system.
SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode.
SS$_NOSUCHDEV This warning code indicates that the specified device does not exist on the host system.

$QIO

This service queues an I/O request to a channel associated with an internet pseudodevice.

The $QIO service is completed asynchronously, which means it returns to the caller immediately after queuing the I/O request, without waiting for the I/O operation to be completed.

For synchronous completion, use the Queue I/O Request and Wait ($QIOW) service. The $QIOW service is identical to the $QIO service, except the $QIOW returns to the caller after the I/O operation has been completed.


Previous | Next | Contents