VMS Help TCPIP Services, Programming Interfaces, Sockets API, $CANCEL  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Cancels all pending I/O requests on a specified channel.
    Related Functions
    The equivalent Sockets API function is close().
    Format
      SYS$CANCEL  chan
    C Prototype
      int sys$cancel  (unsigned short int chan);
    Returns
      OpenVMS usage:cond_value
      type:         longword (unsigned)
      access:       write only
      mechanism:    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.

1 - Arguments

 chan
    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by value
    I/O channel on which I/O is to be canceled. The chan argument is
    a word containing the channel number.

2 - 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.
    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:
    o  The specified event flag is set.
    o  The first word of the I/O status block, if specified, is set
       to SS$_CANCEL if the I/O request is queued, or to SS$_ABORT if
       the I/O operation is in progress.
    o  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.

3 - Condition Values Returned

    SS$_NORMAL         The service completed successfully.
    SS$_ABORT          A physical line went down during a network
                       connect operation.
    SS$_CANCEL         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 to cancel
                       the I/O.
    SS$_IVCHAN         An invalid channel was specified (that is, a
                       channel number of 0 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.