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

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:

The specified event flag is set.
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.
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:

Ends all pending operations to send or receive data at $QIO level ($CANCEL system service).
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.
Ends all communications with the internet pseudodevice that the I/O channel identifies.
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

buffer-length
A word containing a user-supplied integer specifying the length (in bytes) of the buffer for which the $GETDVI returns information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer-length is too small, $GETDVI truncates the data.

item-code
A word containing a user-supplied symbolic code that specifies the information that $GETDVI returns. These codes are defined by the $DVIDEF macro, which is defined in SYS$LIBRARY:STARLET.MLB for the MACRO-32 language and SYS$LIBRARY:DVIDEF.H for the C language. Each item code is listed in the Table 4-2.

buffer-address
A longword containing the user-supplied address of a word in which the length of the information (in bytes) is returned.

return-length-address
A longword containing the user-supplied address of a word in which $GETDVI writes the length of the information it returned (in bytes).

$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:

If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value. This allows you to be sure that the event flag was not set by an event other than service completion.
If you are using the $SYNCH system service to synchronize the completion of the service, you must use iosb as an argument. The iosb argument is required for $SYNCH.
The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $GETDVI service. The condition value returned in R0 gives you information about the success or failure of the service call itself. The condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $GETDVI, you must check the condition values returned in both R0 and the I/O status block.

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.

**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

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

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:

If the device has an associated mailbox, the primary characteristics are those of the assigned device and the secondary characteristics are those of the associated mailbox.
If the device represents a logical link on the network, the secondary characteristics contain information about the link.

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

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

$CANCEL

Format

SYS$CANCEL chan

Returns

ARGUMENTS

chan

DESCRIPTION

Condition Values Returned

$DASSGN

Format

SYS$DASSGN chan

Returns

ARGUMENTS

chan

DESCRIPTION

Condition Values Returned

$GETDVI

Format

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

Returns

ARGUMENTS

efn

chan

devnam

itmlst

$GETDVI Item Descriptor Fields

$GETDVI Item Codes

iosb

astadr

astprm

nullarg

DESCRIPTION

Condition Values Returned

$QIO

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

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

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.

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

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

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

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

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

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

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

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.

DIGITAL TCP/IP Services for OpenVMSSystem Services and C Socket Programming

$CANCEL

Format

SYS$CANCEL chan

Returns

ARGUMENTS

chan

DESCRIPTION

Condition Values Returned

$DASSGN

Format

SYS$DASSGN chan

Returns

ARGUMENTS

chan

DESCRIPTION

Condition Values Returned

$GETDVI

Format

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

Returns

ARGUMENTS

efn

chan

devnam

itmlst

$GETDVI Item Descriptor Fields

$GETDVI Item Codes

iosb

astadr

astprm

nullarg

DESCRIPTION

Condition Values Returned

$QIO

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