VMS Help  —  =
    Defines a symbolic name for a character string or integer value.

    Format

      symbol-name =[=] expression

      symbol-name[bit-position,size] =[=] replacement-expression

                                   NOTE

       VSI advises against assigning a symbolic name that is already
       a DCL command name. VSI especially discourages the assignment
       of symbols such as IF, THEN, ELSE, and GOTO, which can
       affect the interpretation of command procedures.

1  –  Parameters

 symbol-name

    Specifies a string of 1 to 255 characters for the symbol name.
    The name can contain any alphanumeric characters from the DEC
    Multinational character set, the underscore (_),  and the dollar
    sign ($).  However, the name must begin only with an alphabetic
    character (uppercase and lowercase characters are equivalent),
    an underscore, or a dollar sign. Using one equal sign (=)  places
    the symbol name in the local symbol table for the current command
    level. Using two equal signs (==) places the symbol name in the
    global symbol table.

 expression

    Names the value on the right-hand side of an assignment
    statement. This parameter can consist of a character string, an
    integer, a symbol name, a lexical function, or a combination of
    these entities. The components of the expression are evaluated,
    and the result is assigned to the symbol. All literal character
    strings must be enclosed in quotation marks (" ").  If the
    expression contains a symbol, the expression is evaluated using
    the symbol's value.

    The result of expression evaluation is either a character string
    or a signed integer value. If the expression is evaluated as a
    string, the symbol is assigned a string value. If the expression
    is evaluated as an integer, the symbol is assigned an integer
    value. If the integer value exceeds the capacity of the 4-byte
    buffer that holds it, no error message is issued.

    For a summary of operators used in expressions, details on
    how to specify expressions, and details on how expressions are
    evaluated, see the OpenVMS User's Manual.

    DCL uses a buffer that is 1024 bytes long to hold an assignment
    statement and to evaluate the expression. The length of the
    symbol name, the expression, and the expression's calculations
    cannot exceed 1024 bytes.

 [bit-position,size]

    States that a binary overlay is to be inserted in the current
    32-bit value of a symbol name. The current value of the symbol
    name is evaluated. Then, the specified number of bits is replaced
    by the result of the replacement expression. The bit position is
    the location relative to bit 0 at which the overlay is to occur.
    If the symbol you are overlaying is an integer, then the bit
    position must be less than 32. The sum of the bit position and
    the size must be less than or equal to 32.

    If the symbol you are overlaying is a string, then the bit
    position must be less than 6152. Because each character is
    represented using 8 bits, you can begin an overlay at any
    character through the 768th character. (The 768th character
    starts in bit position 6144.) The sum of the bit position and
    the size must be less than or equal to 6152.

    The size is the number of bits to be overlaid. If you specify a
    size that is greater than 32, DCL reduces the size to 32.

    The brackets are required notation; no spaces are allowed between
    the symbol name and the left bracket. Specify values for the bit
    position and size as integers.

 replacement-expression

    Specifies the value that is used to overlay the symbol you are
    modifying. Specify the replacement expression as an integer.

    If the symbol you are modifying is an integer, the replacement
    expression defines a bit pattern that is overlaid on the value
    assigned to the symbol. If the symbol you are modifying is
    a character string, the result of the replacement expression
    defines a bit pattern that is overlaid on the specified bits
    of the character string. If the symbol you are modifying is
    undefined, the result of the replacement expression is overlaid
    on a null string.

2  –  Examples

    1.$ LIST == "DIRECTORY"

      The assignment statement in this example assigns the user-
      defined synonym LIST as a global symbol definition for the DCL
      command DIRECTORY.

    2.$ COUNT = 0
      $ LOOP:
      $      COUNT = COUNT + 1
      $      IF P'COUNT' .EQS. "" THEN EXIT
      $      APPEND/NEW &P'COUNT' SAVE.ALL
      $      DELETE &P'COUNT';*
      $      IF COUNT .LT. 8 THEN GOTO LOOP
      $ EXIT

      This command procedure, COPYDEL.COM, appends files (specified
      as parameters) to a file called SAVE.ALL. After a file has been
      appended, the command procedure deletes the file. Up to eight
      file names can be passed to the command procedure. The file
      names are assigned to the symbols P1, P2, and so on.

      The command procedure uses a counter to refer to parameters
      that are passed to it. Each time through the loop, the
      procedure uses an IF command to check whether the value of
      the current parameter is a null string. When the IF command is
      scanned, the current value of the symbol COUNT is concatenated
      with the letter P. The first time through the loop, the IF
      command tests P1; the second time through the loop it tests
      P2, and so on. After the expression P`COUNT' is evaluated, the
      substitution of the file names that correspond to P1, P2, and
      so on is automatic within the context of the IF command.

      The APPEND and DELETE commands do not perform any substitution
      automatically, because they expect and require file
      specifications as input parameters. The ampersand (&) precedes
      the P`COUNT' expression for these commands to force the
      appropriate symbol substitution. When these commands are
      initially scanned each time through the loop, COUNT is
      substituted with its current value. Then, when the commands
      execute, the ampersand causes another substitution: the first
      file specification is substituted for P1, the second file
      specification is substituted for P2, and so on.

      To invoke this procedure, use the following command:

        $ @COPYDEL ALAMO.TXT BEST.DOC

      The files ALAMO.TXT and BEST.DOC are each appended to the file
      SAVE.ALL and are then deleted.

    3.$ A = 25
      $ CODE = 4 + F$INTEGER("6") - A
      $ SHOW SYMBOL CODE
        CODE = -15   HEX = FFFFFFF1   Octal = 1777761

      This example contains two assignment statements. The first
      assignment statement assigns the value 25 to the symbol A. The
      second assignment statement evaluates an expression containing
      an integer (4), a lexical function (F$INTEGER("6")), and the
      symbol A. The result of the expression, -15, is assigned to the
      symbol CODE.

    4.$ FILENAME = "JOBSEARCH" - "JOB"
      $ FILETYPE = ".OBJ"
      $ FILESPEC = FILENAME + FILETYPE
      $ TYPE 'FILESPEC'

      The first command in this example assigns the symbol FILENAME
      the value "SEARCH". Notice that the string "SEARCH" is the
      result of the string reduction operation performed by the
      expression. The second command assigns the symbol FILETYPE
      the character string ".OBJ".

      The symbols FILENAME and FILETYPE are then added together in an
      expression assigned to the symbol FILESPEC. Because the values
      of the symbols FILENAME and FILETYPE are concatenated, the
      resultant value assigned to FILESPEC is the character string
      "SEARCH.OBJ". The symbol FILESPEC is then used as a parameter
      for the TYPE command. The single quotation marks (` ')  request
      the command interpreter to replace the symbol FILESPEC with its
      value SEARCH.OBJ. Thus, the TYPE command types the file named
      SEARCH.OBJ.

    5.$ BELL[0,32] = %X07
      $ SHOW SYMBOL BELL
        BELL = ""

      In this example, the symbol BELL is created with an arithmetic
      overlay assignment statement. Because the symbol BELL is
      previously undefined, the hexadecimal value 7 is inserted
      over a null character string and is interpreted as the ASCII
      code for the bell character on a terminal. When you issue the
      command SHOW SYMBOL BELL, the terminal beeps.

      If the symbol BELL had been previously defined with an integer
      value, the result of displaying BELL would have been to show
      its new integer value.

    6.$ $=34
      %DCL-W-NOCOMD, no command on line - reenter with alphabetic first
      character
      $ $$=34
      $ SHOW SYMBOL $$
      %DCL-W-UNDSYM, undefined symbol - check validity and spelling
      $ SHOW SYMBOL $
      $ = 34   Hex = 00000022  Octal = 00000000042

      If you begin a symbol name with the dollar sign ($),  use two
      dollar signs ($$)  because DCL discards the first instance of
      the dollar sign.

    7.$ COUNT = 0
      $ LOOP:
      $      COUNT = COUNT + 1
      $      IF P'COUNT' .EQS. "" THEN EXIT
      $      APPEND/NEW &P'COUNT' SAVE.ALL
      $      DELETE &P'COUNT';*
      $      IF COUNT .LT. 16 THEN GOTO LOOP
      $ EXIT

      This command procedure, COPYDEL.COM, appends files (specified
      as parameters) to a file called SAVE.ALL. After a file has been
      appended, the command procedure deletes the file. Up to sixteen
      file names can be passed to the command procedure. The file
      names are assigned to the symbols P1, P2, and so on. This is
      applicable only when you set bit 3 of DCL_CTLFLAGS to 1.

      The command procedure uses a counter to refer to parameters
      that are passed to it. Each time through the loop, the
      procedure uses an IF command to check whether the value of
      the current parameter is a null string. When the IF command is
      scanned, the current value of the symbol COUNT is concatenated
      with the letter P. The first time through the loop, the IF
      command tests P1; the second time through the loop it tests
      P2, and so on. After the expression PCOUNT is evaluated, the
      substitution of the file names that correspond to P1, P2, and
      so on is automatic within the context of the IF command.

      The APPEND and DELETE commands do not perform any substitution
      automatically, because they expect and require file
      specifications as input parameters. The ampersand (&) precedes
      the P`COUNT' expression for these commands to force the
      appropriate symbol substitution. When these commands are
      initially scanned each time through the loop, COUNT is
      substituted with its current value. Then, when the commands
      execute, the ampersand causes another substitution: the first
      file specification is substituted for P1, the second file
      specification is substituted for P2, and so on.

      To invoke this procedure, use the following command:

        $ @COPYDEL ALAMO.TXT BEST.DOC

      The files ALAMO.TXT and BEST.DOC are each appended to the file
      SAVE.ALL and are then deleted.
Close Help