/sys$common/syshlp/HELPLIB.HLB  —  ASSIGN
    Creates a logical name and assigns an equivalence string, or a
    list of strings, to the specified logical name. If you specify
    an existing logical name, the new equivalence name replaces the
    existing equivalence name.

    You can also perform the following functions:

    o  Remove all jobs from one queue and merge them into another
       existing queue (see /MERGE).

    o  Assign or redirect a logical queue to a single execution queue
       (see /QUEUE).

    Format

      ASSIGN  equivalence-name[,...] logical-name[:]

1  –  Parameters

 equivalence-name[,...]

    Specifies a character string of 1 to 255 characters. Defines the
    equivalence name, usually a file specification, device name, or
    other logical name, to be associated with the logical name in
    the specified logical name table. If the string contains other
    than uppercase alphanumeric, dollar sign ($),  or underscore (_)
    characters, enclose it in quotation marks (" ").  Use two sets
    of quotation marks ("" "")  to denote an actual quotation mark
    within the string. Specifying more than one equivalence name for
    a logical name creates a search list. A logical name can have a
    maximum of 128 equivalence names.

    When you specify an equivalence name that will be used as a file
    specification, you must include the punctuation marks (colons
    (:),  brackets ([]),  and periods (.)) that would be required if
    the equivalence name were used directly as a file specification.
    Therefore, if you specify a device name as an equivalence name,
    terminate the device name with a colon.

    The ASSIGN command allows you to assign the same logical name to
    more than one equivalence name. When you specify more than one
    equivalence name for a logical name, you create a search list.
    For more information on search lists, see the OpenVMS User's
    Manual.

 logical-name[:]

    Specifies the logical name string, which is a character string
    containing up to 255 characters. You choose a logical name to
    represent the equivalence name in the specified logical name
    table.

    If the string contains other than uppercase alphanumeric, dollar
    sign, or underscore characters, enclose it in quotation marks.
    Use two sets of quotation marks to denote an actual quotation
    mark. If you terminate the logical-name parameter with a colon,
    the system removes the colon before placing the name in a logical
    name table. (This differs from the DEFINE command, which saves
    the colon.) If the logical name is to be entered into the
    process directory (LNM$PROCESS_DIRECTORY) or system directory
    (LNM$SYSTEM_DIRECTORY) logical name tables, the name can have
    only 1 to 31 alphanumeric characters (including the dollar
    sign and underscore). If the logical name being entered into
    the process or system directory translates to a logical name
    table name, any alphabetic characters in the name should all be
    uppercase. By default, the logical name is placed in the process
    logical name table.

    If the logical name contains any characters other than
    alphanumeric characters, the dollar sign, or the underscore,
    enclose the name in quotation marks. If the logical name contains
    quotation marks, enclose the name in quotation marks and use
    two sets of quotation marks in the places where you want one set
    of quotation marks to occur. Note that if you enclose a name in
    quotation marks, the case of alphabetic characters is preserved.

2  –  Qualifiers

2.1    /CLUSTER_SYSTEM

    You must be signed in to the SYSTEM account or have SYSNAM
    (system logical name) or SYSPRV (system) privilege to use this
    qualifier.

    Assigns a clusterwide logical name in the LNM$SYSCLUSTER table.

2.2    /EXECUTIVE_MODE

    Requires SYSNAM (system logical name) privilege.

    Creates an executive-mode logical name. If you specify executive
    mode, but do not have SYSNAM privilege, a supervisor-mode logical
    name is created. The mode of the logical name must be the same
    as or external to (less privileged than) the mode of the table in
    which you are placing the name.

2.3    /GROUP

    Requires SYSPRV (system privilege) or GRPNAM (group logical name)
    privilege.

    Places the logical name in the group logical name table. Other
    users who have the same group number in their user identification
    codes (UICs) can access the logical name. The /GROUP qualifier is
    synonymous with the /TABLE=LNM$GROUP qualifier.

2.4    /JOB

    Places the logical name in the jobwide logical name table. All
    processes within the same job tree as the process creating the
    logical name can access the logical name. The /JOB qualifier is
    synonymous with the /TABLE=LNM$JOB qualifier.

2.5    /LOG

       /LOG (default)
       /NOLOG

    Displays a message when a new logical name supersedes an existing
    name.

2.6    /NAME_ATTRIBUTES

       /NAME_ATTRIBUTES[=(keyword[,...])]

    Specifies the attributes for a logical name. By default, no
    attributes are set. You can specify the following keywords for
    attributes:

    CONFINE    Does not copy the logical name into a spawned
               subprocess; this keyword is relevant only for logical
               names in a private table.

    NO_ALIAS   Prohibits creation of logical names with the same name
               in an outer (less privileged) access mode within the
               specified table. If another logical name with the same
               name and an outer access mode already exists in this
               table, the name is deleted.

    If you specify only one keyword, you can omit the parentheses.
    Only the attributes you specify are set.

2.7    /PROCESS

       /PROCESS (default)

    Places the logical name in the process logical name table. The
    /PROCESS qualifier is synonymous with the /TABLE=LNM$PROCESS
    qualifier.

2.8    /SUPERVISOR_MODE

       /SUPERVISOR_MODE (default)

    Creates a supervisor-mode logical name in the specified table.

2.9    /SYSTEM

    Requires SYSNAM (system logical name) or SYSPRV (system
    privilege) privilege.

    Places the logical name in the system logical name table. All
    system users can access the logical name. The /SYSTEM qualifier
    is synonymous with the /TABLE=LNM$SYSTEM qualifier.

2.10    /TABLE

       /TABLE=name

    Requires write (W) access to the table if the table is
    shareable.

    Specifies the logical name table in which the logical name is to
    be entered. You can use the /TABLE qualifier to specify a user-
    defined logical name table (created with the CREATE/NAME_TABLE
    command); to specify the process, job, group, or system logical
    name tables; or to specify the process or system logical name
    directory tables.

    If you specify the table name using a logical name that has more
    than one translation, the logical name is placed in the first
    table found. For example, if you specify ASSIGN/TABLE=LNM$FILE_
    DEV and LNM$FILE_DEV is equated to LNM$PROCESS, LNM$JOB,
    LNM$GROUP, and LNM$SYSTEM, then the logical name is placed in
    LNM$PROCESS.

    If you do not explicitly specify the /TABLE qualifier, the
    default is the /TABLE=LNM$PROCESS qualifier.

2.11    /TRANSLATION_ATTRIBUTES

       /TRANSLATION_ATTRIBUTES[=(keyword[,...])]

    Equivalence-name qualifier.

    Specifies attributes of the equivalence-name parameter. Possible
    keywords are as follows:

    CONCEALED  Indicates that the equivalence string is the name of a
               concealed device.

               When a concealed device name is defined, the system
               displays the logical name, rather than the equivalence
               string, in messages that refer to the device. If you
               specified the CONCEALED attribute, then the equivalence
               string must be a physical device name.

    TERMINAL   Indicates that the equivalence string should not be
               translated iteratively; logical name translation should
               terminate with the current equivalence string.

    If you specify only one keyword, you can omit the parentheses.
    Only the attributes you specify are set.

    Note that different equivalence strings of the same logical name
    can have different translation attributes specified.

2.12    /USER_MODE

    Creates a user-mode logical name in the specified table.

    If you specify a user-mode logical name in the process logical
    name table, that logical name is used for the execution of
    a single image only; user-mode entries are deleted from the
    logical name table when any image executing in the process
    exits; that is, after any DCL command that executes an image or
    user program completes execution. Also, user-mode logical names
    are automatically deleted when invoking and exiting a command
    procedure.

3  –  Examples

    1.$ ASSIGN $DISK1:[CREMERS.MEMOS] MEMOSD

      The ASSIGN command in this example equates the partial file
      specification $DISK1:[CREMERS.MEMOS] to the logical name
      MEMOSD.

    2.$ ASSIGN/USER_MODE $DISK1:[FODDY.MEMOS]WATER.TXT TM1

      The ASSIGN command in this example equates the logical name TM1
      to a file specification. After the next image runs, the logical
      name is deassigned automatically.

    3.$ ASSIGN XXX1:[HEROLD]  ED
      $ PRINT  ED:TEST.DAT
      Job 274 entered on queue SYS$PRINT

      The ASSIGN command in this example associates the logical
      name ED with the directory name [HEROLD] on the disk XXX1.
      Subsequent references to the logical name ED result in the
      correspondence between the logical name ED and the disk and
      directory specified. The PRINT command queues a copy of the
      file XXX1:[HEROLD]TEST.DAT to the system printer.

    4.$ ASSIGN YYY2:  TEMP:
      $ SHOW LOGICAL TEMP
         "TEMP" = "YYY2:" (LNM$PROCESS_TABLE)
      $ DEASSIGN TEMP

      The ASSIGN command in this example equates the logical name
      TEMP to the device YYY2. TEMP is created in supervisor mode
      and placed in the process logical name table. The SHOW LOGICAL
      command verifies that the logical name assignment was made.
      Note that the logical name TEMP was terminated with a colon in
      the ASSIGN command, but that the command interpreter deleted
      the colon before placing the name in the logical name table.
      Thus, you can specify TEMP without a colon in the subsequent
      DEASSIGN command. You should omit the colon in the SHOW LOGICAL
      command (for example, SHOW LOGICAL TEMP).

    5.$ MOUNT TTT1: MASTER TAPE
      $ ASSIGN TAPE:NAMES.DAT PAYROLL
      $ RUN PAYROLL
         .
         .
         .

      The MOUNT command in this example establishes the logical name
      TAPE for the device TTT1, which has the volume labeled MASTER
      mounted on it. The ASSIGN command equates the logical name
      PAYROLL with the file named NAMES.DAT on the logical device
      TAPE. Thus, an OPEN request in a program referring to the
      logical name PAYROLL results in the correspondence between
      the logical name PAYROLL and the file NAMES.DAT on the tape
      whose volume label is MASTER.

    6.$ CREATE/NAME_TABLE TABLE1
      $ ASSIGN/TABLE=LNM$PROCESS_DIRECTORY TABLE1,-
      _$ LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM LNM$FILE_DEV
      $ ASSIGN/TABLE=TABLE1 -
      _$ /TRANSLATION_ATTRIBUTES=CONCEALED  DKA1:  WORK_DISK

      The CREATE/NAME_TABLE command in this example creates the
      process private logical name table TABLE1.

      The first ASSIGN command ensures that TABLE1 is searched
      first in any logical name translation of a file specification
      or device name (because TABLE1 is the first item in the
      equivalence string for the logical name LNM$FILE_DEV, which
      determines the default search sequence of logical name tables
      whenever a device or file specification is translated).

      The second ASSIGN command assigns the logical name WORK_DISK
      to the physical device DKA1, and places the name in TABLE1.
      The logical name has the concealed attribute. Therefore, the
      logical name WORK_DISK will be displayed in system messages.

    7.$ ASSIGN/TABLE=LNM$PROCESS/TABLE=LNM$GROUP  DKA0:  SYSFILES
      $ SHOW LOGICAL  SYSFILES
        "SYSFILES" = "DKA0:" (LNM$GROUP_000240)

      The ASSIGN command in this example contains conflicting
      qualifiers. When you specify conflicting qualifiers, the ASSIGN
      command uses the last qualifier specified. The response from
      the SHOW LOGICAL command indicates that the name was placed in
      the group logical name table.

    8.$ ASSIGN/TABLE=LNM$GROUP 'F$TRNLNM("SYS$COMMAND")' TERMINAL
      %DCL-I-SUPERSEDE, previous value of TERMINAL has been superseded

      The ASSIGN command in this example uses the lexical function
      F$TRNLNM to translate the logical name SYS$COMMAND and use the
      result as the equivalence name for the logical name TERMINAL.
      The message from the ASSIGN command indicates that an entry for
      the logical name TERMINAL already existed in the group logical
      name table, and that the new entry has replaced the previous
      one.

      If this command is used in a LOGIN.COM file, the entry for
      TERMINAL will be redefined at the beginning of each terminal
      session. The current process and any subprocesses it creates
      can execute images that use the logical name TERMINAL to write
      messages to the current terminal device.

    9.$ ASSIGN DALLAS::DMA1:  DATA

      The ASSIGN command in this example associates the logical
      name DATA with the device specification DMA1 on remote node
      DALLAS. Subsequent references to the logical name DATA result
      in references to the disk on the remote node.

    10$ CREATE AVERAGE.COM
      $ ASSIGN/USER_MODE SYS$COMMAND:  SYS$INPUT
      $ EDIT/EDT AVERAGE.FOR
      $ FORTRAN AVERAGE
      $ LINK AVERAGE
      $ RUN AVERAGE
      87
      80
      90
      9999
      $ EXIT
 <Ctrl/Z>

      $ @AVERAGE.COM

      The CREATE command in this example creates the command
      procedure AVERAGE.COM. Then the command procedure is executed.

      The command procedure uses the ASSIGN command with the /USER_
      MODE qualifier to change temporarily the value of SYS$INPUT.
      When the EDT editor is invoked, it accepts input from the
      terminal. This allows you to create or modify the program
      AVERAGE.FOR interactively.

      When you exit from EDT, SYS$INPUT is reassigned to its original
      value (the input stream provided by the command procedure).
      Thus, when the program AVERAGE.FOR is ready to accept input, it
      looks for that input in the command procedure.

4    /MERGE

    Removes all jobs from one queue and merges them into another
    existing queue. This command does not affect jobs that are
    executing.

    Requires manage (M) access to both queues.

    Format

      ASSIGN/MERGE  target-queue[:] source-queue[:]

4.1  –  Parameters

 target-queue[:]

    Specifies the name of the queue into which the jobs are being
    merged.

 source-queue[:]

    Specifies the name of the queue from which the jobs are being
    removed.

4.2  –  Example

  $ STOP/QUEUE/NEXT LPB0
  $ STOP/QUEUE/REQUEUE=LPA0 LPB0
  $ ASSIGN/MERGE LPA0 LPB0

      In this example, the STOP/QUEUE/NEXT command prevents another
      job from executing on queue LPB0. The STOP/QUEUE/REQUEUE
      command requeues the current job running on LPB0 to the target
      queue LPA0. The ASSIGN/MERGE command removes the remaining jobs
      from the LPB0 printer queue and places them in the LPA0 printer
      queue.

5    /QUEUE

    Assigns, or redirects, a logical queue to a single execution
    queue. The ASSIGN/QUEUE command can be used only with printer or
    terminal queues.

    Requires manage (M) access to both queues.

    Format

      ASSIGN/QUEUE  queue-name[:] logical-queue-name[:]

5.1  –  Parameters

 queue-name[:]

    Specifies the name of the execution queue. The queue cannot be a
    logical queue, a generic queue, or a batch queue.

 logical-queue-name[:]

    Specifies the name of the logical queue.

5.2  –  Examples

    1.$ INITIALIZE/QUEUE/DEFAULT=FLAG=ONE/START LPA0
      $ INITIALIZE/QUEUE TEST_QUEUE
      $ ASSIGN/QUEUE LPA0 TEST_QUEUE
      $ START/QUEUE TEST_QUEUE

      This example first initializes and starts the printer queue
      LPA0. The LPA0 queue is set to have a flag page precede each
      job. The second INITIALIZE/QUEUE command creates the logical
      queue TEST_QUEUE. The ASSIGN/QUEUE command assigns the logical
      queue TEST_QUEUE to the printer queue LPA0. The START/QUEUE
      command starts the logical queue.

    2.$ INITIALIZE/QUEUE/START LPB0

      The ASSIGN/QUEUE command is not needed in this example because
      a logical queue is not being initialized. A printer queue is
      being initialized; LPB0 is the name of a line printer. After
      you enter the INITIALIZE/QUEUE/START command, jobs can be
      queued to LPB0 for printing.
Close Help