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

    Provides a calling process with an I/O channel, thereby allowing
    the calling process to perform I/O operations on the network
    pseudodevice.
    On Alpha systems, this service accepts 64-bit addresses.
    Format
      SYS$ASSIGN  devnam, chan, [acmode], [mbxnam], [flags]
    C Prototype
      int sys$assign  (void *devnam, unsigned short int *chan,
                      unsigned int acmode, void *mbxnam,...);
    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

 devnam
    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha)
                  by 32-bit descriptor-fixed-length string descriptor
                  (VAX)
    Name of the device to which $ASSIGN is to assign a channel. The
    devnam argument is the 32- or 64-bit address (on Alpha systems)
    or the 32-bit address (on VAX systems) of a character string
    descriptor pointing to the network pseudodevice name string
    (either TCPIP$DEVICE: or SYS$NET:).
 chan
    OpenVMS usage:channel
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha)
                  by 32-bit reference (VAX)
    Number of the channel that is assigned. The chan argument is the
    32- or 64-bit address (on Alpha systems) or the 32-bit address
    (on VAX systems) of a word into which $ASSIGN writes the channel
    number.
 acmode
    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode to be associated with the channel. I/O operations on
    the channel can be performed only from equal and more privileged
    access modes. The $PSLDEF macro defines the following symbols for
    the four access modes:
                   Access
    Symbol         Mode      Numeric Value
    PSL$C_KERNEL   Kernel    0
    PSL$C_EXEC     Executive 1
    PSL$C_SUPER    Supervisor 2
    PSL$C_USER     User      3
 mbxnam
    OpenVMS usage:device_name
    type:         character-coded text string
    access:       read only
    mechanism:    by 32- or 64-bit descriptor-fixed-length string
                  descriptor (Alpha)
                  by 32-bit descriptor-fixed-length string descriptor
                  (VAX)
    This argument is not used.
 flags
    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    An optional device-specific argument. The flags argument is a
    longword bit mask. For more information about the applicability
    of the flags argument for a particular device, refer to the
    OpenVMS I/O User's Reference Manual.

2 - Description

    The $ASSIGN system service establishes a path to a device but
    does not check whether the calling process has the capability
    to do I/O operations to the device. The device drivers may apply
    privilege and protection restrictions. The calling process must
    have NETMBX privilege to assign a channel.
    System dynamic memory is required for the target device, and the
    I/O byte limit quota from the process buffer is used.
    When a channel is assigned to the TCPIP$DEVICE: template network
    device, the network software creates a new device called BGn,
    where n is a unique unit number. The corresponding channel number
    is used in any subsequent operation requests for that device.
    When the auxiliary server creates a process for a service with
    the LISTEN flag set, the server creates a device socket. In
    order for your application to receive the device socket, assign
    a channel to SYS$NET, which is the logical name of a network
    pseudodevice, and perform an appropriate $QIO(IO$_SETMODE)
    operation.
    Channels remain assigned either until they are explicitly
    deassigned with the Deassign I/O Channel ($DASSGN) service or,
    if they are user-mode channels, until the image that assigned the
    channel exits.

3 - Condition Values Returned

    SS$_NORMAL         The service completed successfully.
    SS$_ACCVIO         The caller cannot read the device string or
                       string descriptor, or the caller cannot write
                       the channel number.
    SS$_DEVALLOC       The device is allocated to another process.
    SS$_DEVLSTFULL     The system maximum number of BG: device units
                       has been reached.
    SS$_EXQUOTA        The process has exceeded its buffered I/O byte
                       limit (BIOLM) quota.
    SS$_IVDEVNAM       No device name was specified, the logical name
                       translation failed, or the device name string
                       contains invalid characters.
    SS$_IVLOGNAM       The device name string has a length of zero or
                       has more than 63 characters.
    SS$_NOIOCHAN       No I/O channel is available for assignment.
    SS$_NOSUCHDEV      The specified device does not exist.