Retro1.org codex

LINK                                                     CP Privilege Class:  G

Use the LINK command to make a device that is associated with another virtual
machine available to your virtual machine configuration, based upon information
in that user's VM/SP directory entry.  The format of the LINK command is:
+----------+------------------------------------------------------------------+
| LINK     | [To] userid vaddr1 [As] vaddr2 [mode] [[PASS=] password]         |
+----------+------------------------------------------------------------------+
where:

[To] userid
         is the name of the user whose VM/370 directory is to be searched for
         device vaddr1.  An asterisk (*) is used to specify that the device is
         in your own VM/370 directory.  If the keyword TO is omitted, the
         userid may not be "TO" or "T."

vaddr1   is the virtual device address (cuu) in the VM/SP directory for that
         userid.

[As] vaddr2
         is the virtual address (cuu) that is to be assigned to the device for
         your virtual machine. If the keyword AS is omitted, vaddr may not be
         "AS" or "A."  If your virtual machine has the ECMODE option, any
         address up to X'FFF' is valid; otherwise, any address up to X'5FF' is
         valid.

mode     is the access mode which consists of up to two letters.  The first
         letter specifies the primary access mode (read-only, write, or
         multiple).  The optional second letter indicates the alternate access
         mode (read-only or write access) desired if the primary access is not
         available.  Valid modes are:
         R     Primary read-only (R/O) access.  The read-only link is
               established as long as no other user has the disk in write
               status.  If there is an existing write link to the disk, no link
               is given.  R is the default mode if the link is to another
               userid.

         RR    Primary read-only access or alternate read-only access.  The
               read-only link is established even if another user has the disk
               in write status.  The alternate access of R assures the user
               will get the read link no matter what links currently exist to
               the disk.

         W     Primary write access.  The write link is established only if
               there are no other current links to the disk.  If another user
               has the disk in read or write status, no link is given.

         WR    Primary write access or alternate read-only access.  If write
               access is available, then the write link is established,
               otherwise the alternate access of a read-only link is given.

         M     Primary multiple access.  A write link is established unless
               another user already has write access to the disk, in which case
               no link is given.

         MR    Primary multiple access or alternate read access.  A write link
               is established unless another user already has write access to
               the disk, in which case a read link is given since it was the
               alternate access requested.

               Note:  Unpredictable results can occur when one user has a read-
               only (R or RR) link to a device that is being updated by a user
               who has the device in write status (W or WR).

               For example, in CMS, when a file is updated, it is moved on the
               disk and the directory for the disk is updated.  The user with a
               read-only link will be using an old copy of the file until the
               disk is reaccessed.  As a precaution, the user with a read-only
               link should reaccess the disk everytime a user with a write link
               updates the disk.

         MW    Primary multiple access or alternate write access.  A write link
               is established in all cases.

         Caution:  CMS does not protect a user from loss of data on a disk when
         multiple users have write access to the disk.  More than one user
         writing to the same virtual device will almost always result in a
         permanent loss of data.  Users should not be linking with MW mode to
         obtain the M or MR function.  (The M or MR access modes will allow
         only one write link to a disk.)

         If the mode is omitted and the userid is that of another user, then
         the default mode is R.  If you are linking to one of your own disks,
         the default mode is the access mode as specified in the VM/370
         directory for your disk (on the MDISK or LINK control statement).

PASS= password
         is a one- to eight-character string that must match the access mode
         password for device vaddr1 in the VM/370 directory for the user
         (userid) specified.  The password should be specified only when the
         LINK is executed by a virtual machine (for example, from CMS), since
         printing of the password is not suppressed when included with the LINK
         command.  The access mode password cannot be the same as any of the
         access modes (R, RR, W, WR, M, MR, or MW) if the default mode is to be
         used.


Usage notes:

1.  The access mode password should not be confused with a user password.  Up
    to three access mode passwords can exist for each disk; these are the read,
    write, and multiple passwords.

2.  If you link to one of your own disks, no password is required.  If another
    user has write access to one of your disks when you log on, your access
    will be forced read-only (R/O).  You can obtain write access by issuing a
    link command with an access mode of MW.  Now two write links exist to the
    disk and the integrity of the data is not guaranteed by CP or CMS.

3.  If the link is to a device whose password is ALL, (meaning that any user
    can access the device), the password is not required.  However, if the link
    is to a device whose password is not ALL, a password must be provided.  If
    a LINK command is issued from a CMS batch job, a password must be provided
    even if the access password is ALL.

4.  The link established by the LINK command to the vaddr1 device belonging to
    userid is summarized in the following table where R = read-only, W = write,
    M = multiple, N = no or none, and Y = yes:
       Primary access requested      R R R R R    W W W W W W    M M M M M M
       Alternate access requested            R          R   R            R W
       Read password in directory    N Y Y Y Y
       Write password in directory                N Y Y Y Y Y
       Multi password in directory                               N Y Y Y Y Y
       Current existing links          N R W W      N R R W W      N R W W W
       Access established            N R R N R    N W N R N R    N W W N R W

Responses:

ENTER READ PASSWORD:
XXXXXXXX
   Type the read password over the mask to request read-only access to the
   desired disk.  The mask will only appear on line-mode terminals.

ENTER WRITE PASSWORD:
XXXXXXXX
   Type the write password over the mask to request write access to the desired
   disk.  The mask will only appear on line-mode terminals.

ENTER MULT PASSWORD:
XXXXXXXX
   Type the multiple password over the mask to obtain write access to a disk to
   which other users may already have access.  The mask will only appear on
   line-mode terminals.

   Note:  CP keeps track of unsuccessful link attempts due to invalid
   passwords.  When a user exceeds 10 incorrect password attempts, the LINK
   command is disabled for the remainder of the terminal session.

DASD vaddr2 LINKED R/O
   This response indicates that a read-only link to the given disk is
   established for a LINK request with a mode of R or RR, and that no other
   users are linked to the same disk in read/write mode.

DASD vaddr2 LINKED R/W
   This response indicates that a read/write link to the given disk is
   established for a LINK request with a mode of W, WR, M, MR, or MW, and that
   no other users are linked to the same disk.

DASD vaddr2 LINKED R/O;R/W BY userid ¦ nnn USERS ;R/O BY userid ¦ nnn USERS
   This response indicates that a read-only link to the given disk is
   established for a LINK request with a mode of RR, but warns that the disk is
   in read/write use by some users and possibly in read use by some users.  If
   only one user has access, the number of users (nnn USERS) is replaced by
   userid.

DASD vaddr2 LINKED R/W; R/O BY userid ¦ nnn USERS
   This response indicates that a read/write link to the given disk is
   established for a LINK request with a mode of M, MR, or MW, and informs you
   that the disk is also in read-only use by userid or by nnn users. (No other
   users have a read/write link to the disk.)

DASD vaddr2 LINKED R/W;R/W BY userid ¦ nnn USERS ;R/O BY userid ¦ nnn USERS
   This response indicates that a read/write link to the given disk is
   established for a LINK request with a mode of MW, but warns you that the
   disk is also in read/write use by some users and possibly in read use by
   some users. If only one user has access, the number of users (nnn USERS) is
   replaced by userid.