OpenVMS User's Manual

For example, the F$LENGTH function requires an argument that is a character string expression and it returns a value that is an integer. In a previous example, the argument "BUMBLEBEE" is a character string expression and the return value (9) is an integer.

You can use a lexical function in any position that you can use a symbol. In positions where symbol substitution must be forced by enclosing the symbol in apostrophes (see Section 14.13), lexical function evaluation must be forced by placing the lexical function within apostrophes. Lexical functions can also be used as argument values in other lexical functions.

14.9.13 Examples

The following examples show different ways you can specify the argument for the F$LENGTH function. In each example, the argument is a character string expression.

• The following example shows a symbol that is used as an argument:

  $ BUG = "BUMBLEBEE"
  $ LEN = F$LENGTH(BUG)
  $ SHOW SYMBOL LEN
    LEN = 9   Hex = 00000009  Octal = 00000000011
  

  
  When you use the symbol BUG as an argument, do not place quotation marks around it. The lexical function automatically substitutes the value "BUMBLEBEE" for BUG, determines the length, and returns the value 9.
• The following example shows an argument that contains both a symbol and a character string:

  $ BUG = "BUMBLEBEE"
  $ LEN = F$LENGTH(BUG)
  $ SHOW SYMBOL LEN
    LEN = 9   Hex = 00000009  Octal = 00000000011
  $ LEN = F$LENGTH(BUG + "S")
  $ SHOW SYMBOL LEN
    LEN = 10   Hex = 0000000A  Octal = 00000000012
  

  
  The symbol BUG is not enclosed in quotation marks but the string "S" is. The argument must be evaluated before the F$LENGTH function can determine the length. The value represented by the symbol BUG ("BUMBLEBEE") is concatenated with the string "S"; the result is "BUMBLEBEES". The F$LENGTH function determines the length of the string "BUMBLEBEES" and returns the value 10.
• The following example uses another lexical function as the argument for the F$LENGTH function. The F$DIRECTORY function returns the name of your current default directory, including the square brackets. In the following example, the current default directory is [SALMON].

  $ LEN = F$LENGTH(F$DIRECTORY())
  $ SHOW SYMBOL LEN
    LEN = 8   Hex = 00000008  Octal = 00000000010
  

Do not place quotation marks around the F$DIRECTORY function when it is used as an argument; the function is automatically evaluated. The result of the F$DIRECTORY function must be returned before the F$LENGTH function can determine the length. Then, the F$LENGTH function determines the length of your default directory, including the square brackets.

14.9.15 Order of Operations

An expression can contain any number of operations and comparisons. The following table lists the operators in the order in which they are evaluated if there are two or more operators in an expression. The operators are listed from highest to lowest precedence; that is, operators at the top of the table are performed before operators at the bottom.

Precedence	Operation
7	Unary plus (+) and minus (--)
6	Multiplication (*) and division (/)
5	Addition (concatenation) and subtraction (reduction)
4	All numeric and character comparisons
3	Logical .NOT. operations
2	Logical .AND. operations
1	Logical .OR. operations

If an expression contains operators that have the same order of precedence, the operations are performed from left to right.

14.9.16 Overriding Default Precedence

You can override the normal order of precedence (the order in which operation and comparison would be evaluated) by placing operations to be performed first in parentheses. Parentheses can also be nested.

14.9.17 Example

In the following example, the parentheses force the addition to be performed before the multiplication. Without the parentheses, the multiplication is performed first and the result is 26:

$ RESULT = 4 * (6 + 2)
$ SHOW SYMBOL RESULT
  RESULT = 32   Hex = 00000020  Octal = 00000000040

The result of DCL's evaluation of a symbol is either a character string or an integer value. The data type (character or integer) of a symbol is determined by the data type of the value currently assigned. The data type is not permanent: if the value changes data type, the symbol changes data type.

An expression has either an integer or a string value, depending on the types of values and the operators used.

14.9.19 Example

In the following example, the local symbol NUM is first assigned a character value and then converted to an integer value when assigned an integer expression:

$ NUM = "ABC"
$ NUM = 2 + 5

The following table summarizes how DCL evaluates expressions. The first column lists the different values and operators that an expression might contain. The second column tells, for each case, what the entire expression is equated to. Within the table any value stands for a string or an integer.

Expression	Resulting Value Type
Integer value	Integer
String value	String
Integer lexical function	Integer
String lexical function	String
Integer symbol	Integer
String symbol	String
+, - , or .NOT. any value	Integer
Any value .AND. or .OR. any value	Integer
String + or - string	String
Integer + or - any value	Integer
Any value + or - integer	Integer
Any value * or / any value	Integer
Any value (string comparison) any value	Integer
Any value (numeric comparison) any value	Integer

14.10 Converting Value Types in Expressions

All the operands in an expression must be of the same value data type before DCL can evaluate the expression. Values either have string or integer data types. String data includes character strings, symbols with string values, and lexical functions that return string values. Integer data includes integers, symbols with integer values, and lexical functions that return integer values. When an expression contains both number and string operands, DCL either converts all strings to integers or all integers to strings.

14.10.1 Converting Expressions

In general, if you use both string and integer values, the string values are converted to integers. The only exception is when DCL performs string comparisons. In these comparisons, integers are converted to strings.

In addition, the following lexical functions let you determine or change the value of an expression:

• F$TYPE---Determines the current value type of a symbol
• F$INTEGER---Converts a string expression to an integer value
• F$STRING---Converts an integer expression to a string value

Character strings are converted to integers in the following ways:

• Strings containing numbers are converted to their integer values. For example, the string "45" is converted to the integer 45.
• If a character string begins with T, t, Y, or y, it is converted to the integer 1.
• If a string begins with any other letter, it is converted to the integer 0.

The following table shows examples of strings converted to integer values:

String	Resulting Integer
"123"	123
"12XY"	0 (False)
"Test"	1 (True)
"hello"	0 (False)

14.10.4 Converting Integers to Strings

When integers are converted to character strings, the resulting string contains numbers that correspond to the integer value. The following table shows how integers are converted to string values:

Integer	Resulting String
123	"123"
1	"1"
0	"0"

14.11 Understanding Symbol Tables

Symbols are stored in local or global symbol tables, which are maintained by the operating system.

14.11.1 Local Symbol Tables

DCL maintains a local symbol table for your main process and for every command level that you create when you execute a command procedure, use the CALL command, or submit a batch job. When you create a local symbol, DCL places the symbol in the local symbol table for the current command level. As long as the command level is active, DCL maintains the local symbol table for that command level; when a command level is no longer active, its local symbol table (and all the symbols it contains) is deleted. See Chapter 18 for more information about processes, command procedures, and batch jobs.

14.11.2 Parameters in Local Symbol Tables

In addition to the local symbols you create, a local symbol table contains eight symbols that are maintained by DCL. These symbols, named P1, P2, and so on through P8, are used for passing parameters to a command procedure. Parameters passed to a command procedure are regarded as character strings. Otherwise, P1 to P8 are defined as null character strings (""). They are stored in the local symbol table.

14.11.3 Global Symbol Tables

DCL maintains only one global symbol table for the duration of a process and places all global symbols in that table. In addition to the global symbols you create, the global symbol table contains the reserved global symbols described in the following table. These global symbols give you status information on your programs and command procedures as well as on system commands and utilities.

14.11.4 $STATUS Reserved Global Symbol

$STATUS is the condition code returned by the most recently executed command. The symbol $STATUS conforms to the format of an OpenVMS operating system message code. Applications programs can set the value of the global symbol $STATUS by including a parameter value to the EXIT command. The system uses the value of $STATUS to determine which message, if any, to display and whether to continue execution at the next higher command level. The value of the lowest three bits in $STATUS is placed in the global symbol $SEVERITY.

14.11.5 $SEVERITY Reserved Global Symbol

$SEVERITY is the severity level of the condition code returned by the most recently executed command. The symbol $SEVERITY, which is equal to the lowest three bits of $STATUS, can have the following values:

0	Warning
1	Success
2	Error
3	Information
4	Severe (fatal) error

14.11.6 $RESTART Reserved Global Symbol

$RESTART has the value TRUE if a batch job was restarted after it was interrupted by a system failure. Otherwise, $RESTART has the value FALSE.

14.11.7 Symbol Table Search Order

When the command interpreter determines the value of a symbol, it searches symbol tables in the following order:

1. The local symbol table for the current command level
2. Local symbol tables for each previous command level, searching backwards from the current level
3. The global symbol table

The following sections describe how to mask the value symbols.

14.12.1 SET SYMBOL Command

By default, all symbols (both global and local) defined in an outer command procedure level are accessible to inner procedure levels. However, you can isolate the local or global symbols in a command procedure from the symbols defined in other command procedures by using the SET SYMBOL command. The SET SYMBOL command masks the values of local and global symbols without deleting them. Thus, if a command procedure executes another command procedure, you can use the same symbol names in both procedures if you specify the SET SYMBOL command in the second procedure.

14.12.2 Verb String Translation

The SET SYMBOL command also controls whether DCL attempts to translate the verb string (the first word on the command line) as a symbol before processing the line. The default behavior is that the translation is attempted. The advantage to changing this behavior is that a command procedure is not affected by outer-procedure-level environments when it invokes a command.

14.12.3 Symbol Scoping State

The symbol scope is different for local and global symbols. When you exit a procedure level to return to a previous procedure, the symbol scoping context from the previous level is restored for both local and global symbols.

To display the current, general symbol scoping state, use the lexical function F$ENVIRONMENT("SYMBOL_SCOPE"). To display the current verb scoping state, use the lexical function F$ENVIRONMENT("VERB_SCOPE").

14.12.4 Local Symbol Scope

Local symbols are procedure-level dependent. If you define a local symbol in an outer procedure level, the symbol can be read (but not written to) at any inner procedure level. If you assign a value to a symbol that is local to an outer procedure level, a new symbol is created at the current procedure level. However, the symbol in the outer procedure level is not modified.

The SET SYMBOL/SCOPE=NOLOCAL command causes all local symbols defined at an outer procedure level to be inaccessible to the current procedure level and any inner levels. For example, if you specify SET SYMBOL/SCOPE=NOLOCAL at procedure levels 2 and 4:

• Procedure level 2 can read and write to level 2 local symbols only.
• Procedure level 3 can read (but not write to) level 2 local symbols. Level 3 can also read and write to level 3 local symbols.
• Procedure level 4 can read and write to level 4 local symbols only.

Global symbols are procedure-level independent. The current global symbol scoping context is applied subsequently to all procedure levels.

The /SCOPE=NOGLOBAL qualifier causes all global symbols to become inaccessible for all subsequent commands until either the /SCOPE=GLOBAL qualifier is specified or the procedure exits to a previous level at which global symbols were accessible. In addition, specifying the /SCOPE=NOGLOBAL qualifier prevents you from creating any new global symbols until the /SCOPE=GLOBAL qualifier is specified.

14.13 Understanding Symbol Substitution

In certain contexts, DCL uses a string of characters beginning with a letter as a symbol name or a lexical function. In these contexts, DCL tries to replace the symbol or lexical function with its value. Replacing a symbol with its current value is referred to as symbol substitution. If you use a symbol or lexical function in any other context, you must use a substitution operator to request symbol substitution.

14.13.1 Automatic Evaluation of Symbols

DCL automatically evaluates symbols and lexical functions when they are used as follows:

• On the right side of an assignment (=) statement
• In an argument for a lexical function
• In a DEPOSIT, EXAMINE, IF, or WRITE command
• At the beginning of a command line when the string is not followed by an equal sign or a colon
• In the brackets on the left side of an assignment statement when you are performing substring substitution or numeric overlays (see Section 14.7.12)

In the following examples, the command interpreter uses any character string beginning with an alphabetic character as a symbol name and any string beginning with a number or with the radix operator (%) as a literal numeric value.

• In the following example, COUNT is automatically recognized and evaluated as a symbol:

  $ TOTAL = COUNT + 1
  

• In the second line of this example, the symbol QUERY is automatically evaluated when it is used with the F$LENGTH function. In addition, the F$LENGTH function is automatically evaluated because it is on the right side of an assignment statement:

  $ QUERY = "Have we met before?"
  $ LEN = F$LENGTH(QUERY) + 5
  $ SHOW SYMBOL LEN
    LEN = 27   Hex = 0000001B  Octal = 000033
  

• In the following example, the IF command uses both A and B as symbol names and uses their current values:

  $ IF A .EQ. B THEN WRITE SYS$OUTPUT "DONE"
  

• In the second line of this example, the command interpreter automatically replaces PDEL with its current value and executes the resulting command:

  $ PDEL = "DELETE SYS$PRINT/ENTRY="
  $ PDEL 181
  

• In the following example, DCL automatically defines the symbol BELL as the value of 7 and then assigns a new value based on the bracketed values on the left side of the assignment statement.

  $ BELL = 7
  $ BELL[5,1] = 1
  $ SHOW SYMBOL BELL
   BELL = 39   Hex = 00000027   Octal = 00000000047
  

To force substitution of a symbol that is not in one of the positions listed, enclose the symbol with apostrophes ('), as follows:

$ TYPE 'B'

To force substitution of a symbol within a quoted character string, precede that symbol with two apostrophes (') and follow it with a single apostrophe (') as follows:

$ T = "TYPE ''B'"

When processing a command line, DCL replaces symbols with their values in the following order:

• Forced substitution
  From left to right, DCL replaces all strings delimited by apostrophes (or double apostrophes for strings within quotation marks). Symbols preceded by single apostrophes are translated iteratively; symbols preceded by double apostrophes are not.
• Automatic substitution
  From left to right, DCL evaluates each value in the command line, executing it if it is a command and evaluating it if it is an expression. Symbols in expressions are replaced by their assigned values; this substitution is not iterative.

The following example demonstrates the effect of the order in which DCL substitutes symbols. First, the symbols PN, FILE1, and NUM are defined:

$ PN = "PRINT/NOTIFY"
$ FILE1 = "[BOLIVAR]TEST_CASE.TXT"
$ NUM = 1

Given the preceding symbol definitions, the following commands print the file named [BOLIVAR]TEST_CASE.TXT:

$ FILE = "'FILE''NUM''"
$ PN 'FILE'

In the first command, forced substitution causes NUM to become 1, making FILE''NUM' become FILE1. If you enter the command SHOW SYMBOL FILE, you see that FILE = " 'FILE1' ".

The second command performs two substitutions. First, 'FILE' is substituted with 'FILE1'. 'FILE1' also requires substitution because it is enclosed in apostrophes ('). Automatic substitution causes FILE1 to become [BOLIVAR]TEST_CASE.TXT. This file name is then appended to the value of PN, which is PRINT/NOTIFY. The resulting string is as follows:

$ PRINT/NOTIFY [BOLIVAR]TEST_CASE.TXT

You can use a substitution operator to request symbol substitution in places where DCL does not usually perform it. DCL accepts two substitution operators:

• Apostrophe (')
• Ampersand (&)

The difference between these two operators is the time when the substitution occurs. Symbols preceded by apostrophes are substituted during the first phase of DCL command processing; symbols preceded by ampersands are substituted during the second phase. For more information on the phases of command processing, see Section 14.14.

14.13.7 The Apostrophe (')

The apostrophe (') is the most frequently used substitution operator. Use it to request symbol substitution when you use a symbol in place of a command parameter or qualifier. Use the apostrophes to request symbol substitution on the right side of a string assignment (:=) statement.

To request symbol substitution within a quoted character string, place two apostrophes before the symbol name and one apostrophe after it.

When you use apostrophes to request symbol substitution, you cannot continue the line (with the hyphen continuation character) in the middle of the value that is being substituted.

14.13.8 Examples

• In the following example, the TYPE command requires a file specification. The apostrophes indicate that LIT is a symbol that must be evaluated. If you omit the apostrophes, DCL looks for a file called LIT.LIS (.LIS is the default file type for the TYPE command):

  $ LIT = "LIGHT.BILLS"
  $ TYPE 'LIT'
  

• In the following example, the value for NAME is substituted so that FILE becomes REPORT.DAT:

  $ NAME := REPORT
  $ FILE := 'NAME'.DAT
  $ SHOW SYMBOL FILE
    FILE = "REPORT.DAT"
  

• In the following example, the current value of the symbol NAME is FRED:

  $ MESSAGE = "Creating file ''NAME'.DAT"
  

  
  Therefore, MESSAGE has the following value:

  Creating file FRED.DAT
  

The ampersand (&) is also a substitution operator that the command interpreter recognizes. In many cases, the apostrophe and the ampersand perform the same function. Ampersands are most effective as substitution operators when they are used with apostrophes to affect the order in which substitution is performed.

The action the command interpreter takes when a symbol is undefined depends on the context of the command. For more information, see Section 14.14.13.

14.13.10 Examples

• In the first command shown here, the command interpreter replaces the symbol NAME with its current value during the first phase of command processing (scanning). The second command replaces the symbol NAME with its current value during the second phase of command processing (parsing). The result is the same, even though the methods are different:

  $ TYPE 'NAME'
  $ TYPE &NAME
  

• In the following example, the ampersand (&) is used with apostrophes to affect the substitution order:

  $ P1 = "FRED.DAT"
  $ COUNT = 1
  $ TYPE &P'COUNT'
  

  
  First, the command interpreter evaluates the symbol enclosed by apostrophes ('COUNT'). The result is as follows:

  TYPE &P1
  

  
  Second, the command interpreter evaluates the symbol preceded by an ampersand (P1). The result is as follows:

  TYPE FRED.DAT
  

• In the following example, apostrophes are used with both P and COUNT:

  $ TYPE 'P''COUNT'
  

  
  Working left to right, the command interpreter attempts to evaluate P. Because P is not a defined symbol, DCL gives it a null value. Next, it evaluates the symbol COUNT. The result is as follows:

  TYPE 1
  

• In the following example, A is equated to the current value of B:

  $ B = "MYFILE.DAT"
  $ A = "&B"
  $ TYPE 'A'
  

  
  The ampersand (&) does not cause symbol substitution when it is used inside quotation marks (" "). Therefore, when the assignment is made, the value of B is not substituted. However, the TYPE command displays MYFILE.DAT. This occurs because the command interpreter first substitutes the value &B for A. Next, it substitutes MYFILE.DAT for the symbol &B. If you were to redefine B, the result of the TYPE command would change accordingly.

Observe the following rules:

• Place the ampersand before, but not after, the symbol name.
• An ampersand must follow a delimiter (any blank or special character).
• You cannot use ampersands to request substitution within character strings enclosed in quotation marks (" ").
• You cannot use ampersands to concatenate two or more symbol names.
• In general, do not use the ampersand for symbol substitution unless it is required to translate your symbols correctly.

The command interpreter performs symbol substitution in three phases.

14.14.1 Phase 1: Command Input Scanning

In command input scanning (also called the lexical input phase), the command interpreter evaluates symbols preceded by apostrophes from left to right. Symbols that are preceded by single apostrophes are translated iteratively, as described in Section 14.14.7. Symbols preceded by two apostrophes are not translated iteratively.

14.14.2 Phase 2: Command Parsing

In the command parsing phase:

• The command interpreter analyzes the command line. It checks the first item on the line to see if it is a symbol. If it is, it is evaluated.
• The command interpreter evaluates symbols preceded by ampersands from left to right.

  6489P025.HTM
  OSSG Documentation
  22-NOV-1996 13:17:13.64

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal