|Document revision date: 15 July 2002|
A symbol is a name that represents a numeric, character, or logical value (such as true or false). When you use a symbol in a DCL command line, DCL replaces the symbol with its value before executing the command.
Entering DCL command lines that include parameters, multiple qualifiers, and values can make for much typing and can be time-consuming. To simplify your interaction with DCL and to save time, you can establish symbols to use in place of commands you type frequently.
You can also use symbols in command procedures to collect, store, and manipulate certain types of data. For more information on command procedures, see Chapter 13 and Chapter 14.
This chapter describes:
For additional information, refer to the following:
You can use symbols in the following ways:
In the following example, a symbol is created to set default to a directory that is accessed often. These commands show how to define and use the symbol WORK to set default to the WORK1:[JONES.WORK] directory:
$ WORK :== SET DEFAULT DISK1:[JONES.WORK] $ WORK $ SHOW DEFAULT DISK1:[JONES.WORK]
Although logical names and symbols appear similar, they are used differently. The following table compares the function, usage, and other characteristics of logical names and symbols:
|Function||Represent device, directory, file, queue, and other system object specifications.||Represent commands or portions of command strings.|
|Usage||Are used in place of any complete device, directory, file, queue or other system object specification. Logical names must be used as part of a command string parameter to be passed to the file system for translation.||Are used in place of any command string. Symbols must be used as the first word in a command string to be translated by the command language interpreter.|
|Storage||Are stored in your process, job, group, or system logical name table. See Section 11.10.||Are stored in your global or local symbol table. See Section 12.10.|
|Creation||Use either the ASSIGN or DEFINE command to create a logical name. See Section 11.3.||Use an assignment statement (= or ==) to create a symbol. See Section 12.2.|
|Display||Use either the SHOW LOGICAL or SHOW TRANSLATION command to display a logical name. See Section 11.6.||Use the SHOW SYMBOL command to display a symbol. See Section 12.3.|
|Deletion||Use the DEASSIGN command to delete a logical name. See Section 11.4.||Use the DELETE/SYMBOL command to delete a symbol. See Section 12.2.5.|
You can create two types of symbols, local and global. Local symbols are accessible from the current command level and from command procedures executed from the current command level. Global symbols are accessible at all command levels.
You can define a symbol with a character string, a number, a lexical function, a logical value, or another symbol. The symbol name can be 1 to 255 characters long and must begin with a letter, an underscore (_), or a dollar sign ($). In a symbol name, both lowercase and uppercase letters are treated as uppercase.
To create a symbol, use the assignment statement (= or ==) or the string assignment (:= or ::=,=). When you use the string assignment, all alphabetic characters are converted to uppercase and multiple spaces and tabs are compressed to a single space. You can use string assignments to create a symbol that represents a DCL command or to define a foreign command (note that in either case, there is a 255-character limit). To continue a character string over two lines in a string assignment, use a single hyphen.
You can also create symbols by using the READ and INQUIRE commands (see Chapter 13 and Chapter 14).
Creating Local Symbols
In the following example, the local symbol SS is assigned to the DCL command SHOW SYMBOL:
$ SS = "SHOW SYMBOL"
In the following example, the local symbol DB is assigned to the DCL command DIRECTORY ACCOUNTS:[BOLIVAR]:
$ DB := DIRECTORY ACCOUNTS:[BOLIVAR]
Creating Global Symbols
In the following example, the global symbol DC is used to represent a DCL command line. The DCL command DIRECTORY is executed with the specified qualifiers when you enter the symbol name:
$ DC == "DIRECTORY/SIZE=ALL DISK1:[JONES.TAX]MONEY.LIS"
In the following example, the global symbol READY is used to represent a DCL command line. The DCL command PRINT is executed with the specified qualifiers when you enter the symbol name:
$ READY :== PRINT/CONFIRM/QUEUE=AKI$LN03/NOTIFY/RESTART $ READY FILE.DAT
You can define a symbol to represent a DCL command in your login command file (LOGIN.COM) or interactively at DCL level. When you define the symbol in your login command file, you can use the symbol each time you log in; when you define the symbol interactively, you can use the symbol only during the current process.
If you define a symbol with the same name as a DCL command, your
definition overrides the DCL command name. For example, if you define
the symbol HELP as the command TYPE HELP.LST, you can no longer invoke
the system's Help utility by typing HELP.
12.2.2 Symbol Abbreviation
Use the asterisk (*) to create a symbol that can be abbreviated. Generally, you can use abbreviated symbol definitions in any situation that allows a symbol to be used. Symbols that involve substring replacement are an exception. See Section 12.6.5 for more information.
Note that existing symbols might be superseded. If an existing symbol exactly matches the new symbol at or past the asterisk, the new symbol replaces the existing symbol. In addition, you cannot define another symbol whose name partly matches the existing symbol at or past the asterisk.
The following example creates the local symbol PRINT, which can be abbreviated as PR, PRI, or PRIN:
$ PR*INT = "PRINT/CONFIRM/QUEUE=AKI$LN03/NOTIFY/RESTART"
To execute the DCL command PRINT with the specified qualifiers, you can
enter the symbol or any of its abbreviations.
12.2.3 Defining Foreign Commands
If you equate the file specification of a non-DCL image to a symbol, you can run the image by typing the symbol name. A symbol that runs an image is referred to as a foreign command. A foreign command is an image that is not recognized by the command interpreter as a DCL command. (Note that, like each element of a DCL command, a foreign command has a 255-character limit.)
The formats for defining a symbol as a foreign command are as follows:
symbol-name :=[=] $image-file-spec
symbol-name =[=] "$image-file-spec"
Note that when the dollar sign ($) precedes a file specification at the beginning of a symbol definition, without any space between the dollar sign and the file specification, the request to run the image is implied.
For the image file specification, the default device and directory name is SYS$SYSTEM, the default file type is .EXE, and the default file version number is the highest version.
An alternative to using a foreign command is to define new commands with the Command Definition utility. Refer to the OpenVMS Command Definition, Librarian, and Message Utilities Manual for more information.
There is also a method for executing foreign commands automatically, without specifying symbols. See Section 12.14 for more information.
In the following example, the global symbol PRINTALL is defined to execute the image DISK1:[ACCOUNTS]PRINTALL.EXE:
$ PRINTALL :== $[ACCOUNTS]PRINTALL
In a command line, PRINTALL could be followed by a parameter.
In the following example, the file specification RAT.DAT is a parameter that is passed to the image defined by PRINTALL:
$ PRINTALL RAT.DAT
The command interpreter looks for symbols enclosed by apostrophes (')
and translates them. Thus, if you use symbols or lexical functions
preceded by apostrophes to specify parameters, symbol substitution
occurs (see Section 12.12). Otherwise, the command interpreter does not
parse the line. The image must obtain the parameter and perform any
parsing or evaluation of the command line.
12.2.5 Deleting Symbols
The DELETE/SYMBOL command deletes a symbol. To delete a global symbol, include the /GLOBAL qualifier. For example, to delete the global symbol TEMP, enter the following command:
$ DELETE/SYMBOL/GLOBAL TEMP
The SHOW SYMBOL command displays the values of symbols. To display the value of a particular symbol, enter the SHOW SYMBOL command followed by the name of the symbol. To display the value of a particular global symbol, include the /GLOBAL qualifier. The SHOW SYMBOL/ALL command displays all local symbols. The command SHOW SYMBOL/ALL/GLOBAL displays all global symbols.
Note that when a symbol has an integer value, the SHOW SYMBOL command displays the value in decimal, hexadecimal, and octal notation.
In the following example, the symbol PR is displayed:
$ SHOW SYMBOL PR PR*INT = "PRINT/CONFIRM/COPIES=2/QUEUE=DOC$LN03/NOTIFY/RESTART"
In the following example, the integer value for the symbol TOTAL is displayed:
$ SHOW SYMBOL TOTAL TOTAL = 4 Hex = 00000004 Octal = 00000000004
After you define a symbol, you can use it as part of the definition of another symbol. DCL interprets a symbol as a character string or a number, depending on the context in which you use the symbol.
In the following example, the integer value 3 is assigned to the symbol COUNT:
$ COUNT = 3
The value of COUNT can then be used in other assignment statements. For example, here the value of COUNT is added to 1:
$ TOTAL = COUNT + 1
The result (4) is equated to the symbol TOTAL.
12.4.1 Symbol Concatenation
You can concatenate several symbols to create a long character string by using the plus sign (+). You can also concatenate two or more symbols by placing apostrophes (') around each symbol name.
For more information about requesting symbol substitution, see Section 12.12.2.
In the following example, the symbols "Saturday" and "Sunday" are used to create the symbol "WEEKEND":
$ DAY1 = "Saturday, " $ DAY2 = "Sunday" $ WEEKEND = DAY1 + DAY2 $ SHOW SYMBOL WEEKEND WEEKEND = "Saturday, Sunday"
In the following example, apostrophes are used to concatenate the symbols NAME and TYPE:
$ NAME = "MYFILE" $ TYPE = ".DAT" $ PRINT 'NAME''TYPE'
The PRINT command prints a copy of MYFILE.DAT.
12.4.2 Including Symbols in String Assignments
To include a local symbol in a string assignment, use a colon and an equal sign (:=). To include a global symbol in a string assignment, use a colon and two equal signs (:==). For either type of symbol (local or global), enclose the symbol in apostrophes (' '). Otherwise, DCL will not recognize it as a symbol.
If you define a null character string for a symbol, that symbol has a value of 0.
In the following example, the symbol COUNT is included in a string assignment statement:
$ BARK := P'COUNT'
In a previous example, COUNT was assigned the integer value 3. In this example, COUNT is converted to a string value and appended to the character P. The local symbol BARK now has the value P3.
In the following example, the symbol A is null:
$ A = "" $ B = 2 $ C = A + B $ SHOW SYMBOL C C = 2 Hex = 00000002 Octal = 00000000002
You can use symbols as variables in command procedures. Variables hold values that you calculate or assign as something other than a literal value. For example, you might assign the value of a lexical function to a variable or read the value of a file record into a variable.
An expression is a combination of values. In command procedures, expressions are used in symbol assignment statements (on the right side of the equal sign), in IF statements, in WRITE commands, and as arguments for lexical functions.
When you define a symbol, the left side of the assignment statement defines the symbol name; the right side of the assignment statement contains an expression. Each value (also called an operand) in an expression can be connected to another value by an operator. DCL evaluates the expression and assigns the result to the symbol. If an expression is evaluated as a character string, then the symbol has a string value.
In the following example, the local symbol BARK is equated to an expression that adds three numbers:
$ BARK = 1 + 2 + 3
The operands are 1, 2, and 3. The operator is the plus sign (+). The
evaluated expression is an integer, so the symbol has an integer value.
12.6 Character Strings
A character string can contain any characters that can be printed. Appendix A includes tables of the ASCII character set and the DEC Multinational character set. These tables list characters you can include in a character string.
Characters fall into three main categories:
|HT||Starts printing or typing at the next horizontal tab|
|LF||Starts printing or typing on the next line|
|FF||Starts printing or typing at the top of the next page|
|CR||Starts printing or typing at the first space on the same line|
|ESC||Introduces a terminal escape sequence|
|SP||Inserts one space|
You can define a character string by enclosing it in quotation marks (" "). In this way, alphabetic case and spaces are preserved when the symbol assignment is made. Note the following:
In the following example, the string "YES" is quoted, so it must be defined within quotation marks:
$ PROMPT = "Type ""YES"" or ""NO""" $ SHOW SYMBOL PROMPT PROMPT = "Type "YES" or "NO""
In the following example, the character string is continued over two lines:
$ HEAD = "MONTHLY REPORT FOR" + - _$ " DECEMBER 1999" $ SHOW SYMBOL HEAD HEAD = "MONTHLY REPORT FOR DECEMBER 1999"
A character string expression can contain character strings, lexical functions that are evaluated as character strings, or symbols that have character string values. When you use a character string in an expression, you must enclose it in quotation marks (" "). If you do not use quotation marks, DCL processes the string as a symbol.
Character string expressions combine the following values (called string operands):
If you perform an operation or comparison between a character string and a number, DCL converts the character string to a number.
String operands can be added (string concatenation), subtracted (string reduction), compared, or replaced with other character strings as described in the following subsections.
In the following example, the character string "CAT" must appear in quotation marks:
$ TEMP = "CAT"
In the following example, the symbol TEMP represents the character string "CAT." The symbol TOPIC is a concatenation of the character string "THE" and the character string that the symbol TEMP represents ("CAT"). The result is "THE CAT".
$ TOPIC = "THE" + TEMP
In the following example, the symbol COUNT represents the lexical function F$STRING(65):
$ COUNT = F$STRING(65)
You can specify the following character string operations:
In the following example, the plus sign (+) is used to concatenate two character strings:
$ COLOR = "light brown" $ WEIGHT = "30 lbs." $ DOG2 = "No tag, " + COLOR + ", " + WEIGHT $ SHOW SYMBOL DOG2 DOG2 = "No tag, light brown, 30 lbs."
In the following example, the minus sign ( - ) is used to remove a character string:
$ SHOW SYMBOL DOG2 DOG2 = "No tag, light brown, 30 lbs." $ DOG2 = DOG2 - ", 30 lbs." $ SHOW SYMBOL DOG2 DOG2 = "No tag, light brown"
|privacy and legal statement|