[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS User's Manual


Previous Contents Index


Chapter 14
Programming with DCL: Defining Symbols, Commands, and Expressions

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.

This chapter describes:

For additional information, refer to the following:

14.1 About Symbols

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]

14.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 13.10. Are stored in your global or local symbol table. See Section 14.10.
Creation Use either the ASSIGN or DEFINE command to create a logical name. See Section 13.3. Use an assignment statement (= or :=,=) to create a symbol. See Section 14.2.
Display Use either the SHOW LOGICAL or SHOW TRANSLATION command to display a logical name. See Section 13.6. Use the SHOW SYMBOL command to display a symbol. See Section 14.3.
Deletion Use the DEASSIGN command to delete a logical name. See Section 13.4. Use the DELETE/SYMBOL command to delete a symbol. See Section 14.2.5.

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

Note

If you are working in an environment with Extended File Specifications, refer to the OpenVMS Guide to Extended File Specifications for information about the richer character set and other options available.

You can also create symbols by using the READ and INQUIRE commands (see Chapter 15 and Chapter 16).

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

14.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, the symbol can be used 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.

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

14.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. See 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 14.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

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

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

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

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

14.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 the section titled The Apostrophe (').

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.

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

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

14.6 Character Strings

A character string can contain any characters that can be printed. Appendix B 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:

Note

If you are working in an HFS environment, refer to the OpenVMS Guide to Extended File Specifications for information about the richer character set and other options available.

14.6.1 Defining Character Strings

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 1996"
$ SHOW SYMBOL HEAD
  HEAD = "MONTHLY REPORT FOR DECEMBER 1996"

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

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)


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
6489PRO_033.HTML