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:

• Using symbols
• Displaying symbols
• Using symbols with other symbols
• Using symbols to store and manipulate data
• Character strings
• Using numeric values and expressions
• Using logical values and expressions
• Converting value types in expressions
• Understanding symbol tables
• Masking the value of symbols
• Understanding symbol substitution
• The three phases of command processing
• An alternative to using symbols: automatic foreign commands

For additional information, refer to the following:

• The OpenVMS DCL Dictionary, for additional information about symbols and their usage
• The OpenVMS Command Definition, Librarian, and Message Utilities Manual, for additional information about defining new commands

You can use symbols in the following ways:

• As synonyms for commands, parameters, or command lines. Instead of typing a long command line, you can create a symbol to use instead.
• To define a foreign command, which allows you to execute an image by entering only the symbol name. The command is "foreign" because it is unknown to DCL.
• In command procedure files, to perform programming tasks such as conditional execution and substitution of variables.
  You can use symbols as variables in expressions or to pass parameters to and from command procedures. In addition, DCL commands such as READ, WRITE, and INQUIRE use symbols to refer to data records.

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]

12.1.1 Comparing Logical Names and Symbols

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:

Characteristic	Logical Names	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.

12.2 Using Symbols

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

12.2.1 Using Symbols to Represent DCL Commands

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

12.2.4 Symbol Substitution

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

12.3 Displaying Symbols

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

12.4 Using Symbols with Other Symbols

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

12.5 Using Symbols to Store and Manipulate Data

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:

• Alphanumeric characters
  The uppercase letters A to Z, lowercase letters a to z, digits 1 to 9, dollar sign ($), underscore (_), and hyphen (-).
• Special characters
  All other characters that can be displayed or printed: exclamation point (!), quotation marks ("), number sign (#), and so on.
• Nonprintable characters
  All characters that cannot be printed or displayed. In general, nonprintable characters are ignored for display and print purposes. However, several nonprintable characters serve control functions as follows:

  Character	Function
  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:

• To include quotation marks (") within a string, type two consecutive quotation marks.
• To continue a character string over two lines, use a plus sign (for string concatenation) and a hyphen (for continuation).
  You cannot use the hyphen continuation character within a quoted character string.

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"

12.6.2 Character String Expressions

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):

• Character strings that must appear in quotation marks
• Symbols that represent character strings
• Lexical functions that are evaluated as character strings

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)

12.6.3 Character String Operations

You can specify the following character string operations:

• Concatenation --- The plus sign concatenates two character strings.
• Reduction --- The minus sign removes the second character string from the first character string.
  If the second character string occurs more than once in the first character string, only the first occurrence of the string is removed.

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
6489PRO_030.HTML