Defines a symbolic name for a character string value.

   Format

     symbol-name :=[=] string


     symbol-name[offset,size] :=[=] replacement-string

Additional information available:

PARAMETERSEXAMPLES

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

string
   Names the character string value to be equated to the symbol. The
   string can contain any alphanumeric or special characters. DCL
   uses a buffer that is 1024 bytes long to hold a string assignment
   statement. Therefore, the length of the symbol name, the string,
   and any symbol substitution within the string cannot exceed 1024
   characters.

   With the string assignment statement (:=),  you do not need to
   enclose a string literal in quotation marks (" ").  String values
   are converted to uppercase automatically . Also, any leading and
   trailing spaces and tabs are removed, and multiple spaces and tabs
   between characters are compressed to a single space.

   It is easier to use the assignment statement (=) to create symbols
   with string values because the assignment statement does not
   automatically convert letters to uppercase and remove extra
   spaces. Also, the assignment statement allows you to perform
   string operations in expressions.

   To prohibit uppercase conversion and to retain required space
   and tab characters in a string, place quotation marks around the
   string. To use quotation marks in a string, enclose the entire
   string within quotation marks and use a double set of quotation
   marks within the string. For example:

     $ TEST := "this     is a ""test"" string"
     $ SHOW SYMBOL TEST
       TEST = "this     is a "test" string"

   In this example, the spaces, lowercase letters, and quotation
   marks are preserved in the symbol definition.

   To continue a symbol assignment on more than one line, use the
   hyphen (-)  as a continuation character. For example:

     $ LONG_STRING := THIS_IS_A_VERY_LONG-
     _$ _SYMBOL_STRING

   To assign a null string to a symbol by using the string assignment
   statement, do not specify a string. For example:

     $ NULL :=

   Specify the string as a string literal, or as a symbol or lexical
   function that evaluates to a string literal. If you use symbols or
   lexical functions, place single quotation marks (' ')  around them
   to request symbol substitution. See the VMS DCL Concepts Manual
   for more information on symbol substitution.

   You can also use the string assignment statement to define
   a foreign command. See the VMS DCL Concepts Manual for more
   information about foreign commands.

[offset,size]
   Specifies that a portion of a symbol value is to be overlaid with
   a replacement string. This form of the string assignment statement
   evaluates the value assigned to a symbol and then replaces the
   portion of the value (defined by the offset and size) with the
   replacement string. The brackets are required notation, and no
   spaces are allowed between the symbol name and the left bracket.

   The offset specifies the character position relative to the
   beginning of the symbol name's string value at which replacement
   is to begin. Offset values start at 0.

   If the offset is greater than the offset of the last character
   in the string you are modifying, spaces are inserted between the
   end of the string and the offset where the replacement string is
   added. The maximum offset value you can specify is 768.

   The size specifies the number of characters to replace. Size
   values start
   at 1.

   Specify the offset and size as integer expressions. See the VMS
   DCL Concepts Manual for more information on integer expressions.
   The value of the size plus the offset must not exceed 769.

replacement-string
   Specifies the string that is used to overwrite the string you
   are modifying. If the replacement string is shorter than the size
   argument, the replacement string is filled with blanks on the
   right until it equals the specified size. Then the replacement
   string overwrites the string assigned to the symbol name. If the
   replacement string is longer than the size argument, then the
   replacement string is truncated on the right to the specified
   size.

   You can specify the replacement string as a string literal, or as
   a symbol or lexical function that evaluates to a string literal.
   If you use symbols or lexical functions, place single quotation
   marks (' ')  around them to request symbol substitution. For more
   information on symbol substitution, see the VMS DCL Concepts
   Manual.

   1.  $ TIME := SHOW TIME
       $ TIME
         19-APR-1990 11:55:44

     In this example, the symbol TIME is equated to the command
     string SHOW TIME. Because the symbol name appears as the first
     word in a command string, the command interpreter automatically
     substitutes it with its string value and executes the command
     SHOW TIME.

   2.  $ STAT := $DBA1:[CRAMER]STAT
       $ STAT

     This example shows how to define STAT as a foreign command. The
     symbol STAT is equated to a string that begins with a dollar
     sign followed by a file specification. The command interpreter
     assumes that the file specification is that of an executable
     image, that is, a file with a file type of EXE. The symbol STAT
     in this example becomes a synonym for the following command:

         $ RUN DBA1:[CRAMER]STAT.EXE

     When you subsequently type STAT, the command interpreter
     executes the image.


   3.  $ A = "this is a big     space."
       $ SHOW SYMBOL A
         A = "this is a big     space."
       $ B := 'A'
       $ SHOW SYMBOL B
         B = "THIS IS A BIG SPACE."

     This example compares the assignment and the string assignment
     statements. The symbol A is defined using the assignment
     statement, so lowercase letters and multiple spaces are
     retained. The symbol B is defined using the string assignment
     statement. Note that the single quotation marks (' ')  are
     required; otherwise, the symbol name B would have been equated
     to the literal string A. However, when symbol A's value is
     assigned to symbol B, the letters are converted to uppercase
     and multiple spaces are compressed.

   4.  $ FILE_NAME := MYFILE
       $ FILE_NAME[0,2]:= OL
       $ SHOW SYMBOL FILE_NAME
         FILE_NAME = "OLFILE"

     In this example, the substring expression in the assignment
     statement overlays the first 2 characters of the string
     assigned to the symbol FILE_NAME with the letters OL. The
     offset of 0 requests that the overlay begin with the first
     character in the string, and the size specification of 2
     indicates the number of characters to overlay.


   5.  $ FILE_NAME := MYFILE
       $ FILE_TYPE := .TST
       $ FILE_NAME[F$LENGTH(FILE_NAME),4] := 'FILE_TYPE'
       $ SHOW SYMBOL FILE_NAME
         FILE_NAME = "MYFILE.TST"

     In this example, the symbol name FILE_NAME is equated to the
     string MYFILE and the symbol name FILE_TYPE is equated to the
     string .TST. The third assignment statement uses the lexical
     function F$LENGTH to define the offset value where the overlay
     is to begin. The symbol name FILE_TYPE is used to refer to
     the replacement string (.TST). Note that you must use single
     quotation marks (' ')  to request symbol substitution.

     The F$LENGTH lexical function returns the length of the string
     equated to the symbol FILE_NAME; this length is used as the
     offset. The expression requests that 4 characters of the string
     currently equated to the symbol FILE_TYPE be placed at the end
     of the string currently equated to FILE_NAME. The resultant
     value of the symbol FILE_NAME is MYFILE.TST.