1 Symbol_Assign Defines a symbolic name for a character string or integer value. Format: symbol-name =[=] expression symbol-name[bit-position,size] =[=] replacement-expression 2 Parameters symbol-name Defines a 1- through 255-character alphanumeric string name for the symbol. The symbol name must begin with an alphabetic character (uppercase and lowercase characters are equivalent), an underscore, or a dollar sign. After the first character, the name can contain any alphanumeric characters from the DEC multinational character set, underscores, or dollar signs. If you specify a single equal sign (=) in the assignment statement, the symbol name is placed in the local symbol table for the current command level. If you specify double equal signs (==) in the assignment statement, the symbol name is placed in the global symbol table. expression Specifies the value on the right-hand side of an assignment statement. An expression can consist of a character string value, an integer value, a symbol name, a lexical function, or a combination of these entities. The components of an expression are evaluated, and the result is assigned to a symbol. All literal character strings must be enclosed in quotation marks. If you specify an expression containing a symbol, the command interpreter uses the symbol's value in evaluating the expression. The result of expression evaluation is either a character string or an integer value. The data type of a symbol is determined by the data type of the expression. If the expression evaluates to a string, the symbol is assigned a string value. If the expression evaluates to an integer, the symbol is assigned an integer value. For a summary of operators used in expressions, details on how to specify expressions, and details on how expressions are evaluated, see the Open VMS Users Manual. DCL uses a buffer that is 1024 bytes long to hold an assignment statement, and to evaluate the expression. The length of the symbol name, the expression, and the expression's calculations cannot exceed 1024 bytes. [bit-position,size] Specifies that a binary overlay is to be inserted in the current 32-bit value of a symbol-name. This type of assignment statement evaluates the current value of the symbol-name and replaces the specified number of bits with 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 that you are overlaying is an integer, then the bit position must be less than 32. Also, 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. (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, then DCL reduces the size to 32. The square brackets are required notation; no spaces are allowed between the symbol name and the left bracket. Specify values for bit-position and size as integer expressions. replacement-expression Specifies the value that is used to overlay the symbol you are modifying. Specify the replacement-expression as an integer expression. If the symbol you are modifying is an integer, the replacement-expression defines a bit pattern which is overlaid on the value assigned to the symbol. If the symbol you are modifying is a character string, the result of the replacement-expression defines a bit pattern which is overlaid on the specified bits of the character string. If the symbol you are modifying is undefined, the result of the replacement-expression is overlaid on a null string. 2 Examples 1. $ LIST == "DIRECTORY" $ TIME == "SHOW TIME" $ QP == "SHOW QUEUE/DEVICE" $ SS == "SHOW SYMBOL" The file SYNONYM.COM contains the assignment statements shown; these are user-defined synonyms for commands. Execute this command procedure as follows: $ @SYNONYM After the command procedure creates the global symbol definitions, you can use these synonyms (LIST, TIME, QP,and SS) at the interactive command level. Note that the assignments are global; otherwise, the symbol names would have been deleted after the file SYNONYM.COM completed execution. 2. $ COUNT = 0 $ LOOP: $ COUNT = COUNT + 1 . . . $ IF COUNT .LT.5 THEN GOTO LOOP The symbol COUNT is initially assigned a numeric value of 0; a loop is established to increment the value of COUNT by 1 each time the loop is entered. Note that when the symbol name COUNT appears on the right-hand side of an arithmetic assignment statement, the command interpreter automatically substitutes its current value. The IF command tests the value of COUNT; if it is less than 5, the procedure branches to the label LOOP and the statements between the label LOOP through the IF command are executed again. When the value of the symbol count reaches 5, the loop is not executed again and the command following the IF command is executed. 3. $ A = 25 $ CODE = 4 + F$INTEGER("6") - A $ SHOW SYMBOL CODE CODE = -15 HEX = FFFFFFF1 Octal = 1777761 This example contains two assignment statements. The first statement assigns the value 25 to the symbol A. The second assignment statement evaluates an expression containing an integer (4), a lexical function (F$INTEGER("6")), and the symbol A. The result of the expression, -15, is assigned to the symbol CODE. 2 String_Assign Defines a symbolic name for a character string value. Format: symbol-name :=[=] string symbol-name[offset,size] :=[=] replacement-string 3 Parameters symbol-name Defines a 1- through 255-character string name for the symbol. The symbol name must begin with an alphabetic character (uppercase and lowercase characters are equivalent), an underscore, or a dollar sign. After the first character, the name can contain any alphanumeric characters from the DEC Multinational Character Set, underscores, or dollar signs. If you specify a single equal sign (:=) in the assignment statement, the symbol name is placed in the local symbol table for the current command level. If you specify double equal signs (:==) in the assignment statement, the symbol name is placed in the global symbol table. string Specifies a character string value to be equated to the symbol. The string can contain any alphanumeric or special characters. DCL uses a buffer that is 1024 bytes long to hold a string assignment statement, Therefore, the length of the symbol name, the string, and any symbol substitution within the string cannot exceed 1024 characters. With the := string assignment statement, you do not need to enclose a string literal in quotation marks. String values are automatically converted to uppercase. Also, any leading and trailing spaces and tabs are removed, and multiple spaces and tabs between characters are compressed to a single space. Note that, in general, it is easier to use the assignment statement (=) to create symbols with string values. The assignment statement does not automatically capitalize and remove extra spaces. Also, the assignment statement allows you to perform string operations in expressions. If you want to prohibit uppercase conversion and retain required space and tab characters in a string, you must place quotation marks around the string. To use quotation marks in a string, enclose the entire string in quotation marks and use a double set of quotation marks within the string. For example: $ TEST := "this is a ""test"" string" $ SHOW SYMBOL TEST TEST = "this is a "test" string" In this example, the spaces, lowercase letters, and quotation marks are preserved in the symbol definition. You can continue a symbol assignment on more than one line by using the hyphen as a continuation character. For example: $ LONG_STRING := THIS_IS_A_VERY_LONG- _$ _SYMBOL_STRING To assign a null string to a symbol using the string assignment statement, do not specify a string. For example: $ NULL := Specify the string as a string literal, or as a symbol or lexical function which evaluates to a string literal. If you use symbols or lexical functions, place apostrophes around them to request symbol substitution. You can also use the string assignment statement to define a foreign command. See the OpenVMS Users Manual for more information on symbol substitution and foreign commands. [offset,size] Specifies that a portion of a symbol value is to be overlaid with a replacement string. This form of the string assignment statement evaluates the value assigned to a symbol-name and then replaces the portion of the value (defined by the offset and size) with the replacement string. The square brackets are required notation, and no spaces are allowed between the symbol name and the left bracket. The offset specifies the character position relative to the beginning of the symbol-name's string value at which replacement is to begin. Offset values start at 0. If the offset is greater than the offset of the last character in the string you are modifying, spaces are inserted between the end of the string and the offset where the replacement string is added. The maximum offset value you can specify is 768. The size specifies the number of characters to replace. Size values start at 1. Specify the offset and size as integer expressions. See the OpenVMS Users Manual for more information on integer expressions. The value of the size plus the offset must not exceed 769. replacement-string Specifies the string that is used to overlay the string you are modifying. If the replacement-string is shorter than the size argument, the replacement string is blank-filled on the right until it equals the specified size. Then the replacement string is used to overlay 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. You can specify the replacement-string as a string literal, or as a symbol or lexical function which evaluates to a string literal. If you use symbols or lexical functions, place apostrophes around them to request symbol substitution. See the Open VMS Users Manual for more information on symbol substitution. 3 Examples 1. $ TIME := SHOW TIME $ TIME 15-APR-1987 11:55:44 The symbol TIME is equated to the command string SHOW TIME. Because the symbol name appears as the first word in a command string, the command interpreter automatically substitutes it with its string value and executes the command SHOW TIME. 2. $ STAT := $DBA1:[CRAMER]STAT $ STAT This example shows how to define STAT as a foreign command. The symbol STAT is equated to a string that begins with a dollar sign followed by a file specification. The command interpreter assumes that the file specification is that of an executable image, that is, a file with a file type of EXE. Thus, the symbol STAT in this example becomes a synonym for the command: $ RUN DBA1:[CRAMER]STAT.EXE When you subsequently type STAT, the command interpreter executes the image. 3. $ 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." This example compares the assignment and the string assignment statements. The symbol A is defined using the assignment statement, so lowercase letters and multiple spaces are retained. The symbol B is defined using the string assignment statement. Note that the apostrophes are required; otherwise, the symbol name B would have been equated to the literal string A. However, when symbol A's value is assigned to symbol B, the letters are converted to uppercase and multiple spaces are compressed.