Symbol

A symbol is a name that represents a numeric, string, or boolean value (represented as a numeric or string value). Symbols are a CLI construct and are stored in process-specific symbol tables.

Symbols are used:

• as command synonyms and foreign commands to simplify interaction with DCL
• to store and manipulate data in command procedures and on the command line
• to pass data between command procedures in a single process

Data types

Symbols can store numeric and string values; both numeric and string values can also be treated as boolean values. The value of the symbol can be a 32-bit integer or a string with 1 to 255 characters (for VAX) or 1 to 8192 characters (for Alpha and I64 systems).

Symbol table

Symbols are stored in the local and global symbol table. Local symbols are accessible from the current and nested command levels, global symbols are accessible from all command levels. The symbol table is defined by the number of equal signs in symbol assignment: single equal sign (=) stands for local symbol, double equal sign (==) stands for global symbol.

If symbols with the same name but different equivalence strings are defined in different tables, local symbols are preferred to global symbols.

Access to local and global symbol in command procedures can be controlled with the SET SYMBOL command: SET SYMBOL/SCOPE=NOLOCAL causes all local symbols defined in outer procedure levels to be treated as undefined by the current procedure level and all inner procedure levels, and SET SYMBOL/SCOPE=NOGLOCAL causes all global symbols to be inaccessible to the current procedure level and all inner procedure levels.

Symbol assignment

Symbols are assigned to equivalence strings with an equal sign (=). The following rules apply:

• a single equal sign (=) is used for local symbol assignments, double equal sign (==) for global symbol assignments
• a colon may be used in front of the equal sign (:= or :==) to indicate that the symbol has a string value
• if the equivalence string is enclosed in double quotes (""), a string symbol is defined and the equivalence string is not normalized by DCL (not translated to uppercase, spaces and tabs are intact). If the equivalence string is not enclosed in double quotes but a colon is used in front of the equals sign, a string symbol is defined but the equivalence string is normalized (translated to uppercase, leading and trailing spaces and tabs removed, multiple spaces converted to a single space):

$ 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."
 

In the example below, A is first defined using quotes around the value, and then redefined using :=. Notice how the string value is normalized in this case.

If the equivalence string is not enclosed in double quotes and no colon is used in front of the equals sign, but the equivalence string does not have a numeric value, an error is displayed because DCL treats the equivalence string itself like a symbol:

$ a = hello
%DCL-W-UNDSYM, undefined symbol - check validity and spelling
 \HELLO\
 

• symbols can be abbreviated if an asterisk (*) is inserted in the symbol name (e.g. SY*MBOL will cause SY, SYM, SYMB, SYMBO and SYMBOL to be replaced with the value of SYMBOL)

The symbol name can be 1 to 255 characters long and contain any alphanumeric characters from the DEC Multinational character set, the underscore (_), and the dollar sign ($). It must begin only with an alphabetic character, an underscore, or a dollar sign.

The string value can contain any alphanumeric or special characters. The length of the symbol name, string, and any symbol substitution within the string must not exceed 1024 characters.

To continue a symbol assignment on more than one line, the hyphen (-) can be used 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 :=

To delete a symbol, DELETE/SYMBOL is used. By default, it works with local symbols; to delete a global symbol, specify /GLOBAL.

String Value Replacement

The following syntax:

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

can be used to overlay a portion of the 32-bit symbol value (defined by the offset and size) with a replacement string. 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.

Replacement string specifies the string that is used to overwrite the string to the left of the assignment operator. 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. The replacement string can be specified as a string literal, or as a symbol or lexical function that evaluates to a string literal.

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

$ 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). 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.

$ esc[0,7] = 27
 

In the example above, the first 7 bytes of the symbol ESC are equated to 27. This creates the escape character that cannot be entered from a modern keyboard and that can be used to control the terminal.

Displaying Symbols

SHOW SYMBOL displays the symbol passed as the parameters (wildcards * and % can be used) or all symbols if /ALL is used.

Forcing Symbol Substitution

To force a part of the command line to be interpreted as a symbol in cases when DCL does not expect it to be a symbol (such as in the middle of a string), use:

• for a symbol on the command line:
  • a single quote before the symbol and a single quote after the symbol:

$ file = "xxx.txt"
$ type file
%TYPE-E-OPENIN, error opening DSA1:[DZELENINA]FILE.LIS; as input
-RMS-E-FNF, file not found
$ type 'file'
===Explicit content===
 

• an ampersand (&) before the symbol:

SMAN43$ type &file
===Explicit content===
 

• for a symbol inside of a string:
  • a double quote before the symbol and a single quote after the symbol:

SMAN43$ write sys$output "Here is your ''file'"
Here is your xxx.txt
 

See also

• OpenVMS User's Manual