VMS Help System Services, $ASSIGN  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Provides a process with an I/O channel so input/output operations
    can be performed on a device, or establishes a logical link with
    a remote node on a network.

    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,...);

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)
    mechanism:    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 device name string.

    If the device name contains a double colon (::),  the system
    assigns a channel to the first available network device (NET:)
    and performs an access function on the network.

 chan

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       write only
    mechanism:    by 32- or 64-bit reference (Alpha)
    mechanism:    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. The acmode
    argument specifies the access mode. The $PSLDEF macro defines
    the following symbols for the four access modes:

    Symbol        Access Mode   Numeric Value

    PSL$C_KERNEL  Kernel        0
    PSL$C_EXEC    Executive     1
    PSL$C_SUPER   Supervisor    2
    PSL$C_USER    User          3

    The specified access mode and the access mode of the caller are
    compared. The less privileged (but the higher numeric valued)
    of the two access modes becomes the access mode associated
    with the assigned channel. I/O operations on the channel can
    be performed only from equal and more privileged access modes.
    For more information, refer to the section on access modes in the
    OpenVMS Programming Concepts Manual.

 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)
    mechanism:    by 32-bit descriptor-fixed-length string descriptor
                  (VAX)
    Logical name of the mailbox to be associated with the device. The
    mbxnam 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 logical name string.

    If you specify mbxnam as 0, no mailbox is associated with the
    device. This is the default.

    You must specify the mbxnam argument when performing a
    nontransparent, task-to-task, network operation.

    Only the owner of a device can associate a mailbox with the
    device; the owner of a device is the process that has allocated
    the device, whether implicitly or explicitly. Only one mailbox
    can be associated with a device at any one time.

    For unshareable, nonspooled devices, an implicit $ALLOCATE is
    done. This requires read, write, or control access to the device.

    A mailbox cannot be associated with a device if the device has
    foreign (DEV$M_FOR) or shareable (DEV$M_SHR) characteristics.

    A mailbox is disassociated from a device when the channel that
    associated it is deassigned.

    If a mailbox is associated with a device, the device driver can
    send status information to the mailbox. For example, if the
    device is a terminal, this information might indicate dialup,
    hangup, or the reception of unsolicited input; if the device is a
    network device, it might indicate that the network is connected
    or perhaps that the line is down.

    For details on the nature and format of the information returned
    to the mailbox, refer to the OpenVMS I/O User's Reference Manual.

 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 on the applicability of the flags argument
    for a particular device, refer to the OpenVMS I/O User's
    Reference Manual.