Defines a symbolic name for a character string value.
Format
symbol-name :=[=] string
symbol-name[offset,size] :=[=] replacement-string
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, 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.
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_SYMBOL_ASSIGNMENT_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 OpenVMS User's
Manual for more information on symbol substitution.
You can also use the string assignment statement to define
a foreign command. See the OpenVMS User's 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 OpenVMS User's 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 OpenVMS User's
Manual.
2 – Examples
1.$ TIME := SHOW TIME
$ TIME
24-DEC-2001 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 := $DKA1:[TEDESCO]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.
When you subsequently enter 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.