OpenVMS User's Manual

Symbol substitution during this phase is not iterative.

14.14.3 Phase 3: Expression Evaluation

During the expression evaluation phase:

• The command interpreter evaluates symbols that are preceded by the DEPOSIT, EXAMINE, IF, and WRITE commands.
• The command interpreter evaluates symbols within lexical functions.

Symbol substitution during this phase is not iterative.

14.14.4 Symbol Substitution on Data Lines

Note that the command interpreter does not scan any lines that are read as input data by commands or programs executed within a command procedure. Therefore, the command interpreter does not perform symbol substitution within these data lines.

14.14.5 Example

In the following example, the program AVERAGE reads 55, 57, and 9999 from SYS$INPUT (the command input stream). These data lines are never read by the command interpreter. If you enter symbol names as input, they are not evaluated:

$ RUN AVERAGE 
55 
57 
9999

Symbol substitution can be repetitive or iterative:

• Repetitive substitution results when more than one type of substitution occurs in a single command line.
• Iterative substitution occurs when the command interpreter examines a substituted value to see if the value itself is a symbol. Iterative substitution occurs only when symbols preceded by apostrophes are translated during the first phase of command processing.

When you use an apostrophe (') to request symbol substitution, the command interpreter performs iterative substitution during the first phase of command processing.

Substitution using apostrophes is not iterative when a symbol is included in a quoted character string.

14.14.8 Example

In the following example, the substitution is not iterative:

$ MAC = "5"
$ A = "''MAC'"
$ B = "''A'"
$ SHOW SYMBOL B
  B = 5  Hex = 00000005  Octal = 00000000005

After the statement B = 'A' the resulting value of the symbol B is 5 because:

• The symbol name A is enclosed in apostrophes, so it is replaced with its current value ('MAC').
• Because this value ('MAC') is also enclosed in apostrophes, the command interpreter replaces MAC with its current value (5).
• Because this value (5) has no apostrophes, the first phase of command processing is complete. No further substitution is required during the second or third phases. Therefore, 5 is the final value given to the symbol name B.

Note, however, what happens when you include A in a quoted character string:

$ B = "''A'"
$ SHOW SYMBOL B
  B = "'MAC'"

In this case, B has the value 'MAC'. The symbol name A is replaced only once because substitution is not iterative within quoted character strings.

14.14.9 Phase 2 Substitution

The command interpreter performs iterative substitution automatically only when an apostrophe is in the command line. In some cases, you may want to nest command synonym definitions.

14.14.10 Example

In the following example, when EXEC is processed, the command interpreter performs substitution only once:

$ MAC = "TYPE A.B"
$ EXEC = "'MAC'"
$ EXEC

The result is the string 'MAC'. The command interpreter displays an error message because it does not recognize MAC as a command. This error occurs because during the first phase of command processing, no substitution is performed (the string EXEC is not delimited by apostrophes). During the second phase, the string 'MAC' is substituted for EXEC because EXEC is the first value on the command line. This substitution is not iterative. Therefore, even though 'MAC' is delimited by apostrophes, no additional substitution is performed.

To use the command synonym EXEC correctly, enclose it in apostrophes:

$ 'EXEC'

In this case, the symbol EXEC is evaluated during the first phase of command processing. Because this substitution is iterative, ('MAC') is also evaluated and the string TYPE A.B is substituted.

14.14.11 Phase 3 Substitution

When the command interpreter analyzes an expression in a command, any symbols specified in the expression are replaced only once. You can, however, force iterative substitution by using an apostrophe or an ampersand in the expression. When you force iteration in this way, you must remember the following:

• The command interpreter performs all substitutions requested by apostrophes and ampersands before the command string is executed.
• Commands that automatically perform symbol substitution do so after the first and second phases of command processing.

Note, however, that if substitution does not result in a valid symbol name, the command fails.

14.14.12 Examples

• The following example shows iterative substitution in an IF command:

  $ P1 = "FRED.DAT"
  $ COUNT = 1
  $ IF P'COUNT' .EQS. "" THEN GOTO END
  

  
  When the command interpreter scans this line, it replaces the symbol COUNT with its current value. The result is as follows:

  IF P1 .EQS. "" THEN GOTO END
  

  
  Because this string has no apostrophes, the command interpreter does not perform any more substitution. However, when the IF command executes, it automatically evaluates the symbol name P1 and replaces it with its current value.
• In the following example, the symbol name FILENAME is invalid:

  $ FILENAME = "A.B"
  $ IF 'FILENAME' .NES. "" THEN TYPE 'FILENAME'
  

  
  The command interpreter replaces the symbol FILENAME with its current value (A.B). The result is as follows:

  IF A.B .NES.  "" THEN TYPE A.B
  

  
  When the IF command executes the command line, A.B is not a valid symbol and an error occurs. For this IF command to be processed correctly, omit the apostrophes, as follows:

  $ IF FILENAME .NES. "" THEN TYPE 'FILENAME'
  

If a symbol is not defined when it is used in a command line, the command interpreter either displays an error message or replaces the symbol with a null string, depending on the context. The rules are as follows:

• During the first and second phases of command processing, the command interpreter replaces all undefined symbols that are preceded by apostrophes or ampersands with null strings.
• During the third phase of command processing, if the command interpreter finds an undefined symbol, it displays a warning message and does not finish processing.

• The following example shows how the command interpreter processes an undefined symbol that is preceded by an apostrophe:

  $ FILE := MYFILE'FILE_TYPE'
  $ SHOW SYMBOL FILE
    FILE = "MYFILE"
  $ PRINT 'FILE'
  

  
  When the symbol FILE is created, the symbol FILE_TYPE is replaced with its current value. If FILE_TYPE is not defined, the command interpreter replaces FILE_TYPE with a null string. The absence of a file type in the file specification causes the PRINT command to use the default file type .LIS. Thus, the file specification is interpreted as MYFILE.LIS.
• In the following example, the expression is evaluated during the third phase of command processing:

  $ A = 1
  $ C = A + B
  %DCL-W-UNDSYM, undefined symbol - check validity and spelling
  

  
  The symbol B is undefined, so the command interpreter cannot evaluate the expression.

You can also invoke a command procedure (.COM file type) or executable image (.EXE file type) from DCL level without defining a symbol for that procedure. Using automatic foreign commands, DCL can search a specific set of directories for a command procedure or executable image and run it automatically.

14.15.1 How Automatic Foreign Commands Work

When you enter a command verb that is not a DCL symbol and that is not in the DCL command tables, the system usually displays the following message:

DCL-W-IVVERB, unrecognized command verb - check validity and spelling 

However, if the logical name DCL$PATH is defined (and is not blank), DCL instead performs an RMS $SEARCH for any file that contains the invalid verb in its file name and DCL$PATH:.* as the default file specification.

If DCL finds a .COM or .EXE file, DCL will automatically execute that file with the rest of the command line as its parameters. (This behavior is similar to the PATH options found in DOS, UNIX, and other operating systems.)

14.15.2 Example

In the following example, the DCL symbol SYSGEN is no longer needed. DCL looks in the SYS$SYSTEM directory and finds SYSGEN.EXE. DCL acts like the symbol "SYSGEN" was defined as "$SYS$SYSTEM:SYSGEN" which causes the SYSGEN image to be activated as a foreign command.

$ SYSGEN
%DCL-W-IVVERB, unrecognized command verb - check validity and spelling 
 \SYSGEN\
$ DEFINE DCL$PATH SYS$SYSTEM,SYS$DISK:[]FOO
$ SYSGEN SHOW MAXPROCESSCNT
Parameter Name   Current   Default    Min.    Max.    Unit  Dynamic 
--------------   -------   -------   ------- -------  ----  ------- 
MAXPROCESSCNT        157        32        12    8192 Processes 

In the following example, SS does not need to the defined as "@SS.COM" because DCL will automatically search the SYS$SYSTEM directory for SS.COM or SS.EXE. If that fails, DCL will search the current directory for SS.COM or SS.EXE.

$ TYPE SS.COM
$ SHOW SYMBOL/LOCAL/ALL
$ EXIT
$ SS "This is a parameter"
  P1 = "This is a parameter" 
  P2 = "" 
  P3 = "" 
  P4 = "" 
  P5 = "" 
  P6 = "" 
  P7 = "" 
  P8 = "" 
$ SS.EXE "This is a parameter"
  P1 = ".EXE" 
  P2 = "This is a parameter" 
  P3 = "" 
  P4 = "" 
  P5 = "" 
  P6 = "" 
  P7 = "" 
  P8 = ""

In the example, DCL locates SS.COM and acts like "SS" had been a symbol defined as "@SS.COM". The command procedure is activated with the rest of the command line parsed as parameters. Note that "SS.EXE" does not invoke the image SS.EXE, but instead invokes SS.COM with two parameters, the first being the text string ".EXE". This is consistent with the way command parsing and symbol substitution is performed by the OpenVMS operating system.

14.15.4 Using Automatic Foreign Commands

Note the following:

• The logical name DCL$PATH can be a search-list type logical.
• Only the node, device, and directory portions of each translation of the logical name are used.
• Normal logical precedence takes place. Users can override a system definition of DCL$PATH by defining their own. If a system definition exists and the user does not want the feature, it can be turned off by overriding the logical with a definition of " ".
• The set of valid characters for DCL verbs and symbol names differs from the set of valid characters for filenames. For example, DCL symbols cannot contain a hyphen (-) or start with a dollar sign ($). If the image or procedure you wish to execute is not valid as a DCL symbol name, it cannot be directly invoked by this new feature.
• DCL has not parsed the command. It is up to the image being invoked to perform its own command parsing. For C programs, use the "argc" and "argv" parameters to the main() routine. For programs written in other languages, call LIB$GET_FOREIGN to obtain the entire command line, which must then be parsed by the program.
• If a directory contains both a command procedure and an executable image, whichever file is found first will be invoked. On OpenVMS systems, directories are in alphabetical order, so a ".COM" file will be found before a ".EXE" file. A network file specification in the DCL$PATH logical pointing to a node running some other operating systems could result in a ".EXE" file being found before a ".COM" file.
  Because DCL performs the search with the invalid verb as the file specification and "DCL$PATH:.*" as the default file specification, it is possible to define a logical in such a way that a specific file is found. For example, if you define the logical FOO to be "FOO.EXE", and type "FOO" at the DCL prompt, you will never invoke FOO.COM, only FOO.EXE.

If you are a privileged user and set your default device and directory to other user accounts, you should not place "SYS$DISK:[]" in the definition of the DCL$PATH logical name. Doing so will cause DCL to search the current directory, where a typographical error or poor placement of the translation within the search list could cause user images in the current directory to be found and mistakenly invoked with privileges.

14.15.6 Restrictions

Note the following restrictions:

• You cannot use automatic foreign commands on any versions of the OpenVMS operating system prior to Version 6.2.
• Because new verbs can be added to the DCL command table at any time, a command that works with automatic foreign commands one day may not work at a later date.
• The automatic foreign commands feature does not work in all cases. In the following example, DCL (which looks only at the first four characters of any verb) finds a match with the SHOW verb (the first four letters of SHOWME) and executes the SHOW USERS command instead of the SHOWME.COM procedure. If you defined SHOWME as a DCL symbol, then the SHOWME command would invoke SHOWME.COM.

  $ DEFINE DCL$PATH SYS$SYSTEM,SYS$DISK:[]FOO
  $ TYPE SHOWME.COM
  $ SHOW SYMBOL P1 
  $ EXIT
  $ SHOWME USERS
        OpenVMS User Processes at MARCH 2, 1996 01:40 PM 
      Total number of users = 1,  number of processes = 11 
   
   Username     Interactive  Subprocess   Batch 
   RSMITH              9         2 
  

Command procedures are files that contain DCL commands and data lines used by DCL commands. This chapter is divided into major sections that include the following:

• Basic information about writing command procedures
• Step-by-step procedure for writing command procedures
• Executing command procedures
• Exiting, interrupting, and error handling command procedures
• Login command procedures

Refer to the OpenVMS DCL Dictionary for complete information on all commands described in this chapter.

15.1.1 Types of Command Procedures

There are two types of DCL command procedures:

• Simple
  Execute a series of DCL commands in the order in which they are written
• Complex
  Perform program-like functions

There are two ways to create command procedures:

• Use a text editor such as EVE or EDT to create a new file
• Use the DCL command CREATE to create a new file

The file that you create can contain command lines, labels, comments, conditional statements, and variables.

15.2.1 File Type

The default file type for command procedures is .COM. If you specify the .COM file type when you name a command procedure, you can execute the procedure by specifying the file name only. The SUBMIT and execute procedure (@) commands assume the file type is .COM unless you specify otherwise.

15.2.2 Writing Commands

The following are suggestions for including commands in command procedures:

• Use complete names for commands and qualifiers. This will help to ensure that your command procedure is upwardly compatible to future releases of OpenVMS.
• Use continuation lines to make a procedure easier to read. Note that continuation lines do not begin with dollar signs. For example:

  $ PRINT LAB.DAT   - 
       /AFTER=17:00 - 
       /COPIES=20   - 
       /NAME="COMGUIDE" 
  

When writing command lines:

• You must use a dollar sign ($) to begin each line containing a command, comment, or label.
• If you want to include a line containing data, omit the dollar sign ($) on that line.
• If you need to include a data line that begins with a dollar sign ($), use the DCL commands DECK and EOD. For example:

        $ ! Everything between the commands DECK and EOD 
        $ ! is written to the file WEATHER.COM 
        $ ! 
        $ CREATE WEATHER.COM 
        $ DECK 
        $ FORTRAN SUMMER 
        $ LINK SUMMER 
        $ RUN SUMMER 
        $ EOD 
        $ ! 
        $ ! Now execute WEATHER.COM 
        $ @WEATHER 
        $ EXIT 
  

Note that command lines that do not begin with a dollar sign might be correctly interpreted by DCL, but Digital strongly recommends that any DCL command line start with a dollar sign.

15.3 Using Labels

The following sections describe how to use labels.

15.3.1 Rules for Using Labels

Labels are used in DCL command procedures to mark the beginning of loops, sections of code, or subroutines. Note the following rules when using labels:

• Put labels on separate lines to make loops, subroutines, and conditional code more visible.
• Use label names that contain fewer than 255 characters and no blank spaces.
• Differentiate labels from commands by placing labels immediately after the dollar sign ($) and by preceding commands with spaces.
• End each label with a colon.
• You cannot delete labels.

As the command interpreter encounters labels, it enters them in a special section of the local symbol table. The amount of space available for labels is limited. If a command procedure uses many symbols and contains many labels, the command interpreter might run out of symbol table space and issue an error message. If this occurs, include the DELETE/SYMBOL command in your procedure to delete symbols as they are no longer needed. (Note, however, that you cannot delete labels.)

15.3.3 Duplicate Labels

If a command procedure uses the same label more than once, the new definition replaces the existing one in the local symbol table.

When duplicate labels exist, the GOTO command transfers control to the label that DCL has processed most recently. The GOTO command also uses the following rules when processing duplicate labels:

• If all duplicate labels precede the GOTO command, control transfers to the label nearest the GOTO command.
• If duplicate labels precede and follow the GOTO command, control transfers to the preceding label nearest the GOTO command.
• If all duplicate labels follow the GOTO command, control transfers to the label nearest the GOTO command.

The following sections describe how to use comments in command procedures.

15.4.1 Suggested Uses of Comments

It is good programming practice to include comments in command procedures. Comments can be helpful when updating or troubleshooting the command procedure. Comments can be used as follows:

• At the beginning of a procedure to describe the procedure and the parameters passed to it.
• At the beginning of each block of commands to describe that section of the procedure.
• To separate command sequences with lines containing both a dollar sign and an exclamation point ($!). This makes it easier to see the outline of the command procedure. If you insert blank lines, the command interpreter interprets them as data lines and produces a message warning you that the data lines were ignored.

The following rules apply when writing comments in command procedures:

• Use an exclamation point (!) to indicate the beginning of a comment; the command interpreter ignores all text to the right of an exclamation point when the command procedure executes.
• To include a literal exclamation point in a command line, enclose the exclamation point in quotation marks (" ").

Before you begin writing a command procedure, perform the tasks interactively that the command procedure will execute. As you type the necessary commands, note any variables and conditionals that are used, and any iterations that occur.

The following sections contain the steps to write a simple command procedure. The example used throughout these sections is a command procedure called CLEANUP.COM. This procedure can be used to clean up a directory.

15.5.1 Definitions

• Variable
  Data that changes each time you perform a task.
• Conditional
  Any command or set of commands that can vary and therefore must be tested each time you perform the task.
• Iteration
  Any command or set of commands that are performed repetitively until a condition is met.

Follow these steps to write a command procedure:

Step	Task
1	Design the command procedure.
2	Assign variables and test conditionals.
3	Add loops.
4	End the command procedure.
5	Test and debug the program logic.
6	Add clean up tasks.
7	Finish the procedure.

15.6 Step 1: Design the Command Procedure

Follow these steps to design a command procedure:

Step	Task
1	Decide which tasks your procedure will perform.
2	Determine any variables your command procedure will use and how they will be loaded.
3	Determine what conditionals the command procedure requires and how you will test them.
4	Decide how you will exit from the command procedure.

15.6.2 Deciding Which Tasks to Perform

There are certain commands that are usually executed during clean up operations. The following table lists those commands and the tasks that they perform:

Command	Task Performed
DIRECTORY	Displays the contents of the current directory
TYPE filespec	Displays a file
PURGE filespec	Purges a file
DELETE filespec	Deletes a file
COPY filespec new-filespec	Copies a file

15.6.3 Variables

Any data that changes when you perform a task is a variable. If you create or delete files in your directory, the file names will be different each time you clean your directory; therefore, the file names in CLEANUP.COM are variables.

15.6.4 Conditionals

Any command that must be tested each time you execute a command procedure is considered conditional. Because any or all of the commands in CLEANUP.COM might be executed, depending on the operation you need to perform, each command is conditional.

15.6.5 Design Decisions

After you have determined what variables and conditionals you will use in the CLEANUP.COM command procedure, you must decide how to load the variables, test the conditionals and exit from the command procedure. For the CLEANUP.COM command procedure, the following decisions have been made:

Task	How Accomplished
Load variables	The command procedure gets the file names from the terminal.
Test Conditionals	The command procedure: Gets a command name from the terminal and executes the appropriate statements based on the command name. Ensures that the first two characters of each command name are read to differentiate between the DELETE and DIRECTORY commands.
Exit from loop	You must enter the EXIT command to exit from the loop.

15.6.6 Ordering Commands

To make command procedures easier to understand and maintain, write statements so the procedures execute from the first command to the last command.

15.7 Step 2: Assign Variables and Test Conditionals

There are many ways to assign values to variables. In this section, we will discuss using the INQUIRE command. For additional methods, see Chapter 16.

15.7.1 How to Assign Variables and Test Conditionals

Follow these steps to assign values to variables and test conditionals:

Step	Task
1	Assign values to variables using the INQUIRE command.
2	Determine which action should be taken.
3	Test the conditional using IF and THEN statements.
4	Write program stubs and insert them into the command procedure as placeholders for commands.
5	Write error messages, if necessary.

15.7.2 Using the INQUIRE Command

The INQUIRE command prompts for a value, reads the value from the terminal, and assigns the value to a symbol.

  6489P026.HTM
  OSSG Documentation
  22-NOV-1996 13:17:15.19

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal