Executive Commands

PV-WAVE executive commands compile programs, continue stopped programs, and start previously compiled programs. All executive commands begin with a period. Under UNIX, file names are case sensitive, while under OpenVMS and Windows, either case may be used. Executive commands can be executed from files or from the WAVE prompt.

Using Executive Commands

Executive commands are summarized in the following table:

Executive Commands

Command	Action
.CON	Continues execution of a stopped program.
.GO	Executes previously compiled main program from the beginning of the program.
.LOCALS	Resizes the data area in terms of local variables and common block symbols.
..LOCALS	Allocates space for procedures executed from within procedures.
.RNEW	Compiles and possibly executes text from files or from the WAVE prompt.
.RUN	Compiles and possibly executes text from files or from the WAVE prompt.
.SIZE	Resizes the code area and the data area used to compile programs in terms of bytes.
.SKIP	Skips over the next statement and then single steps.
.STEP	Executes a single statement. This command may be abbreviated as .S.

.CON

The .CON command continues execution of a program that has stopped because of an error, a STOP statement, or a keyboard interrupt. PV-WAVE saves the location of the beginning of the last statement executed before an error. If it is possible to correct the error condition in the interactive mode, the offending statement may be re-executed by typing .CON. After STOP statements, .CON continues execution at the next statement.

The .GO command starts execution at the beginning of a previously compiled main program.

The syntax of the .LOCALS command is:

.LOCALS local_vars common_symbols

The .LOCALS command is similar to the .SIZE command, in that it resizes the data area (the data area is described in the previous section, Using .SIZE). The .LOCALS command, however, lets you specify the data area size in terms of local variables and common block symbols rather than in bytes. This command affects the size of the data area for the $MAIN$-level (commands entered from the WAVE prompt), and the initial size of the data area for compiled procedures and functions.

The two parameters are positional, but not required. If you execute .LOCALS with no parameters, the data area is set back to its default value, which is 500 local variables. If you want to use 700 variables at the $MAIN$ level, enter:

.LOCALS 700

.LOCALS clears and frees the current $MAIN$ data area and code area. It then allocates a new code area of the same size as the previous one and a new data area of the specified size.

For compiled procedures and functions, the compiler initially allocates code and data areas of the same size as those that $MAIN$ is currently using. If you get compiler error messages stating that the code and/or data area of a procedure or function is full, you must first make the $MAIN$ code and/or data areas larger with the .SIZE or .LOCALS executive command. Then when you recompile the procedure or function, the compiler starts with the larger code and/or data areas.

The syntax of the ..LOCALS compiler directive is:

..LOCALS local_vars common_symbols

This command is useful when you want to place the EXECUTE function inside a procedure or function. EXECUTE takes a string parameter containing a PV-WAVE command. This command argument is compiled and executed at runtime, allowing the possibility for command options to be specified by the user. Because the data area is compressed after compilation, there may not be enough room for additional local variables and common block symbols created by EXECUTE. The ..LOCALS command provides a method of allocating extra space for these additional items.

The ..LOCALS compiler directive is similar to the .LOCALS executive command, except:

• ..LOCALS is only used inside procedures and functions.

• Its arguments specify the number of additional local variables and common block symbols that will be needed at "interpreter" time (when the already-compiled instructions are interpreted).

• It is used in conjunction with the EXECUTE function, which can create new local variables and common block symbols at runtime.

The .RNEW command compiles and saves procedures and programs in the same manner as .RUN. However, all variables in the main program unit, including those in common blocks, are erased. The -t, -l, and -c switches have the same effect as with .RUN. See the examples below. Its syntax is:

.RNEW file₁, ..., file_n

See Sample Usage of .RUN and .RNEW.

The .RUN command compiles procedures, functions and main programs. The .RUN command also executes main programs. The command may be followed by a list of files to be compiled. Separate the filenames with blanks or commas:

.RUN file₁, ..., file_n

If no files are specified with the .RUN command, input is accepted from the keyboard at the WAVE prompt until a complete program unit is entered. The values of all the variables are retained.

Files containing PV-WAVE procedures, programs, and functions are assumed to have the filename extension (suffix) .pro. If the filename is the same as the actual function or procedure name, the function or procedure is compiled and executed.

The command arguments -t for terminal listing, or -l for listing to a named file, may be used after the command name, and before the program file names, to produce a numbered program listing directed to the terminal or to a file. For instance, to see a listing on the screen as a result of compiling a procedure contained in a file named analyze.pro:

.RUN -t analyze

To compile the same procedure and save the listing in a file named: analyze.lis:

.RUN -l analyze.lis ana1yze

In listings produced by PV-WAVE, the line number of each statement is printed at the left margin. This number is the same as that printed in error statements, simplifying location of the statement causing the error.

Each level of block nesting is indented four spaces to the right of the preceding block level to improve the legibility of the program's structure.

Sample Usage of .RUN and .RNEW

Some examples of the .RUN and .RNEW commands are:

.RUN

; Accept a program from the keyboard (WAVE prompt). Retain the
; present variables.

.RUN myfile

; Compile the file myfile.pro. If myfile.pro is not found in the current
; directory, PV-WAVE looks for the file in the directory search path.

.RUN -t a, b, c

; Compiles the files a.pro, b.pro, and c.pro. Lists the programs on the
; terminal.

.RNEW -l myfile.lis myfi1e, yourfile

; Erases all variables. Compiles the files myfile.pro and yourfile.pro.
; Produces a listing of myfile in the file myfile.lis.

The .SKIP command skips one or more statements and then single steps. This command is useful for continuing over a program statement which caused an error. If the optional argument n is present, it gives the number of statements to skip, otherwise, a single statement is skipped. The syntax is:

.SKIP [n]

For example, consider the following program segment:

... ... ...
OPENR, 1, 'missing'
READF, 1, xxx, ..., ...
... ... ...

If the OPENR procedure fails because the specified file does not exist, program execution will halt with the OPENR procedure as the current procedure. Execution may not be resumed with the executive command .CON because it attempts to re-execute the offending OPENR procedure, causing the same error.

The remainder of the program can be executed by:

• Opening the correct file manually by typing in a valid OPENR procedure.

• Entering .SKIP, which skips over the incorrect OPENR procedure.

• Entering .CON, which resumes execution of the program at the READF procedure.

The syntax of the .SIZE command is:

.SIZE code_size data_size

The .SIZE command resizes the code area and data area. These memory areas are used when PV-WAVE programs are compiled. The code area holds internal instruction codes that the compiler generates. The data area, also used by the compiler, contains variable name, common block, and keyword information for each compiled function, procedure, and main program.

After successful compilation, a new memory area of the required size is allocated to hold the newly compiled program unit.

By default, the size of the code area is about 800 bytes, and it grows dynamically as needed to accommodate the activity of your session. The initial size of the data area is 8,000 bytes (enough space to hold 500 local variables).

For example, to extend the code and data areas to 40,000 and 10,000 bytes respectively:

.SIZE 40000 10000

The upper limit for both code_size and data_size is over 2 billion bytes.

The .STEP command executes one or more statements in the current program starting at the current position, stops, and returns control to the interactive mode. This command is useful in debugging programs. If the optional argument n is present, it gives the number of statements to execute, otherwise, a single statement is executed. The syntax of the .STEP command is:

.STEP [n]

or

.S [n]