Symbol Assign
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help Symbol Assign *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
Defines a symbolic name for a character string or integer value.
Format:
symbol-name =[=] expression
symbol-name[bit-position,size] =[=] replacement-expression
| 1 - Parameters |
symbol-name Defines a 1- through 255-character alphanumeric string name for the symbol. The symbol name must begin with an alphabetic character (uppercase and lowercase characters are equivalent), an underscore, or a dollar sign. After the first character, the name can contain any alphanumeric characters from the DEC multinational character set, underscores, or dollar signs. If you specify a single equal sign (=) in the assignment statement, the symbol name is placed in the local symbol table for the current command level. If you specify double equal signs (==) in the assignment statement, the symbol name is placed in the global symbol table. expression Specifies the value on the right-hand side of an assignment statement. An expression can consist of a character string value, an integer value, a symbol name, a lexical function, or a combination of these entities. The components of an expression are evaluated, and the result is assigned to a symbol. All literal character strings must be enclosed in quotation marks. If you specify an expression containing a symbol, the command interpreter uses the symbol's value in evaluating the expression. The result of expression evaluation is either a character string or an integer value. The data type of a symbol is determined by the data type of the expression. If the expression evaluates to a string, the symbol is assigned a string value. If the expression evaluates to an integer, the symbol is assigned an integer value. For a summary of operators used in expressions, details on how to specify expressions, and details on how expressions are evaluated, see the Open VMS Users 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] Specifies that a binary overlay is to be inserted in the current 32-bit value of a symbol-name. This type of assignment statement evaluates the current value of the symbol-name and replaces the specified number of bits with 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 that you are overlaying is an integer, then the bit position must be less than 32. Also, 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. (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, then DCL reduces the size to 32. The square brackets are required notation; no spaces are allowed between the symbol name and the left bracket. Specify values for bit-position and size as integer expressions. replacement-expression Specifies the value that is used to overlay the symbol you are modifying. Specify the replacement-expression as an integer expression. If the symbol you are modifying is an integer, the replacement-expression defines a bit pattern which 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 which 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"
$ TIME == "SHOW TIME"
$ QP == "SHOW QUEUE/DEVICE"
$ SS == "SHOW SYMBOL"
The file SYNONYM.COM contains the assignment statements shown;
these are user-defined synonyms for commands. Execute this command
procedure as follows:
$ @SYNONYM
After the command procedure creates the global symbol definitions,
you can use these synonyms (LIST, TIME, QP,and SS) at the
interactive command level. Note that the assignments are global;
otherwise, the symbol names would have been deleted after the file
SYNONYM.COM completed execution.
2. $ COUNT = 0
$ LOOP:
$ COUNT = COUNT + 1
.
.
.
$ IF COUNT .LT.5 THEN GOTO LOOP
The symbol COUNT is initially assigned a numeric value of 0; a loop
is established to increment the value of COUNT by 1 each time the
loop is entered. Note that when the symbol name COUNT appears on
the right-hand side of an arithmetic assignment statement, the
command interpreter automatically substitutes its current value.
The IF command tests the value of COUNT; if it is less than 5, the
procedure branches to the label LOOP and the statements between the
label LOOP through the IF command are executed again. When the
value of the symbol count reaches 5, the loop is not executed again
and the command following the IF command is executed.
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
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.
| 3 - String Assign |
Defines a symbolic name for a character string value.
Format:
symbol-name :=[=] string
symbol-name[offset,size] :=[=] replacement-string
3.1 - Parameters
symbol-name
Defines a 1- through 255-character string name for the symbol. The
symbol name must begin with an alphabetic character (uppercase and
lowercase characters are equivalent), an underscore, or a dollar
sign. After the first character, the name can contain any
alphanumeric characters from the DEC Multinational Character Set,
underscores, or dollar signs.
If you specify a single equal sign (:=) in the assignment statement,
the symbol name is placed in the local symbol table for the current
command level.
If you specify double equal signs (:==) in the assignment statement,
the symbol name is placed in the global symbol table.
string
Specifies a 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
automatically converted to uppercase. Also, any leading and
trailing spaces and tabs are removed, and multiple spaces and tabs
between characters are compressed to a single space.
Note that, in general, it is easier to use the assignment statement
(=) to create symbols with string values. The assignment statement
does not automatically capitalize and remove extra spaces. Also,
the assignment statement allows you to perform string operations
in expressions.
If you want to prohibit uppercase conversion and retain required
space and tab characters in a string, you must place quotation marks
around the string. To use quotation marks in a string, enclose the
entire string in 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.
You can continue a symbol assignment on more than one line by using
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 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 which evaluates to a string literal. If you use symbols or
lexical functions, place apostrophes around them to request symbol
substitution.
You can also use the string assignment statement to define a foreign
command. See the OpenVMS Users Manual for more information on
symbol substitution and 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-name and then replaces the
portion of the value (defined by the offset and size) with the
replacement string. The square 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 Users 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 overlay the string you are
modifying. If the replacement-string is shorter than the size
argument, the replacement string is blank-filled on the right until
it equals the specified size. Then the replacement string is used
to overlay 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 which evaluates to a string literal. If
you use symbols or lexical functions, place apostrophes around them
to request symbol substitution. See the Open VMS Users Manual
for more information on symbol substitution.
3.2 - Examples
1. $ TIME := SHOW TIME
$ TIME
15-APR-1987 11:55:44
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. Thus, the symbol STAT in this
example becomes a synonym for the 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
apostrophes 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.
|
|
