 |
HP OpenVMS DCL Dictionary
= (Assignment Statement)
Defines a symbolic name for a character string or integer value.
Format
symbol-name =[=] expression
symbol-name[bit-position,size] =[=] replacement-expression
Note
HP advises against assigning a symbolic name that is already a DCL
command name. HP especially discourages the assignment of symbols such
as IF, THEN, ELSE, and GOTO, which can affect the interpretation of
command procedures.
|
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.
Description
Symbols defined using assignment statements allow you to extend the
command language. At the interactive command level, you can use symbols
to define synonyms for commands or command lines. In command procedure
files, you can use symbols to provide for conditional execution and
substitution of variables.
The maximum number of symbols that can be defined at any time depends
on the following:
- The amount of space available to the command interpreter to contain
symbol tables and labels for the current process. The amount of space
is determined for each process by the system parameter CLISYMTBL.
- The size of the symbol names and their values. The command
interpreter allocates space for a symbol name and its value. In
addition, a few bytes of overhead are allocated for each symbol.
Examples
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.
|
