# 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

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

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