Creating and Running Programs

PV-WAVE Foundation > Programmer Guide > PV-WAVE Programming > Creating and Running Programs

You can create program files using a text editor that can save a file in ASCII format, and then execute these programs within PV-WAVE. This method is usually how programs are created because these programs can be saved in files for future use. The types of programs you can create include:

interactive command line programs

functions and procedures

main programs

command or batch files

journal files

note	For information on creating applications with a Graphical User Interface (GUI), refer to PV‑WAVE Application Developer’s Guide.

Creating and Running Programs Interactively at the Command Line

Normally, functions and procedures are created in files so that they can be used in future sessions. However, occasionally you may need to create a short program or function that you do not want to save. The .RUN command provides this option.

Here’s an example showing how to create a program interactively using the .RUN command:

WAVE> .RUN

- FOR I = 0,3 DO BEGIN

- PRINT, 'SQRT of ', I

- PRINT, ' = ', SQRT(I)

- ENDFOR

- END

% Compiled module: $MAIN$

SQRT OF 0

= 0.00000

SQRT OF 1

= 1.00000

SQRT OF 2

= 1.41421

SQRT OF 3

= 1.73205

The example program calculates and prints out the square root for the numbers 0 through 3.

After typing .RUN and pressing <Return>, a dash (–) prompt is displayed indicating that you are in program mode. When you have completed the program, you must enter END as the last line and press <Return>. The message %Compiled module: $MAIN$ that displays indicates that this is a main program.

Two other types of programs, procedures and functions, can also be created from the WAVE> prompt using the .RUN command. Here’s an example of how to create a function that squares a number:

WAVE> .RUN

- FUNCTION SQUARE, NUMBER

- RETURN, NUMBER^2

- END

%Compiled module: SQUARE

After you type END and press <Return>, the message, %Compiled module: SQUARE, displays. Now, you can use the SQUARE function to calculate the square of a number.

A program created interactively like this cannot be saved for use in later sessions unless you have given it a name, such as SQUARE. As long as the program has a name, you can enter the following command:

SAVE, /Routine

and the routine SQUARE will be saved along with any other routines that you had already compiled during that session.

Creating and Running a Function or Procedure

Using an ordinary text editor that can save to an ASCII file, you can create files that define procedures and functions.

note	For much more information on writing procedures and functions, see Chapter 10: Writing Procedures and Functions, Chapter 11: Programming with PV-WAVE, and Chapter 12: Tips for Efficient Programming.

Function Program Example

For example, here’s the program listing for a file named square.pro that defines a function to square a number:

FUNCTION SQUARE, NUMBER

RETURN, NUMBER^2

END

The file automatically compiles and executes when being called at the WAVE> prompt:

WAVE> x = SQUARE(24) & PRINT, x

% Compiled module: SQUARE.

The file automatically compiles and executes only under the following circumstances:

The file is in the !Path or current directory.

The filename is the same as the function or procedure name and has a .pro extension.

If the file is not the same name as the function, then you must use the .RUN command to compile it. See "WAVE_PATH: Setting Up a Search Path (UNIX)" for details about search paths.

Creating and Running Main Programs

A main program is a series of statements that are not preceded by a procedure or function heading (PRO or FUNCTION) and is compiled as a unit. Main programs can also be created interactively as indicated in the next section. Since there is no heading, it cannot be called from other routines, and cannot be passed arguments. When PV-WAVE encounters the END statement in a main program as the result of a .RUN executive command, it compiles it into the special program named $MAIN$ and immediately executes it as a unit. Afterwards, it can be executed again with the .GO executive command.

Main Program Example

For example, a main program file named testfile might contains the following statements:

FOR I = 3,5 DO BEGIN

PRINT, 'Square of ', I, ' = ', I^2

PRINT, 'Square root of ', I, ' = ', SQRT(I)

ENDFOR

To compile and run this main program file named testfile, enter the following at the WAVE> prompt:

WAVE> .RUN testfile

The results are:

Square of 3 = 9

Square root of 3 = 1.73205

Square of 4 = 16

Square root of 4 = 2.00000

Square of 5 = 25

Square root of 5 = 2.23607

Main Program Compared to Function or Procedure

A main program is a series of statements that is not preceded by a procedure or function heading (PRO or FUNCTION) and is compiled as a unit. The Editor window in the Windows version of PV‑WAVE is ideal for creating programs like this.

Since a main program has no heading, it cannot be called from other routines, and it cannot be passed arguments. But it can contain commands that communicate with other applications – either off-the-shelf commercially-available software, or custom applications that you or a coworker have written in C. Furthermore, it can be stored for later use, either by you or by someone else.

For example, suppose that earlier you had saved a PV-WAVE program on a disk in a file named ditto.pro. Because the program did not include a FUNCTION or PRO command, it is considered to be a main program. If the disk drive on your computer is assigned to the A: partition, you can run this program by entering the following command at the WAVE> prompt:

WAVE> .RUN A:\ditto

If the file had some other filename extension besides .pro, you would have had to supply that, as well (e.g., ditto.txt or ditto.pgm).

note	For more information about how to enable PV-WAVE to communicate with other applications, refer to the PV-WAVE Application Developer’s Guide. For more information about how to enable PV-WAVE to communicate with other applications, refer to the PV-WAVE Application Developer’s Guide.

Main Program Compared to Command File

The differences between a main program and a command file are:

Main programs must have an END statement, they must be executed with the .RUN command (or the File=>Run option), and they are executed as a unit.

Command files do not have an END statement, are executed by typing
@filename, and are executed one line at a time.

For more information about command files, and how they can be used during your PV-WAVE session, refer to "Running a Command (Batch) File".

Creating and Running a Command (Batch) File

Each line of a command file (also called a batch file) is interpreted exactly as if it had been entered from the WAVE> prompt. In the command file mode, PV-WAVE compiles and executes each statement before reading the next statement. This is different than the interpretation of programs, procedures, and functions compiled using .RNEW or .RUN (explained previously), in which all statements in a program are compiled as a single unit and then executed. Labelsare not allowed in the command file mode because each statement is compiled independently.

Multi-line statements must be continued on the next line using the $ continuation character, because in interactive mode PV-WAVE terminates every statement not ending with $ by an END statement. A common mistake is to include a block of commands in a FOR loop inside a command file:

FOR I = 1,10 DO BEGIN
PRINT, I, ' square root = ', SQRT(I)
PRINT, I, ' square = ', I^2

ENDFOR

In command file mode (this is not the case for functions and procedures), PV-WAVE compiles and executes each line separately, causing syntax errors in the example above because no matching ENDFOR is found on the same line as the BEGIN when the line is compiled. The above example can be made to work by inserting an ampersand between each statement in the block of statements and by terminating each line (except the last) with a $:

FOR I = 1,10 DO BEGIN & $ 
PRINT, I, ' square root = ', SQRT(I) & $
PRINT, I, ' square = ', I^2 & $

ENDFOR

note

Both the ampersand and the dollar sign are required on every line of a command file except the last line. For example, with just an ampersand at the end of each line, the sample program does not run properly because each line is compiled as a separate entity. Hence, a syntax error results when the ENDFOR statement is compiled because it is seen as a single statement that is not connected to a FOR statement. With the dollar sign at the end of each line, no compilation occurs until the ENDFOR statement. For more information on the dollar sign and ampersand characters, see Special Characters in the PV‑WAVE Reference.

Running a Command (Batch) File

A command file is simply a file that contains PV-WAVE executive commands and statements. Command files are useful for executing commands and procedures that are commonly used. The commands and statements in the command file are executed as if they were entered from the keyboard at the WAVE> prompt.

There are three ways that you can run a command file:

You can enter the command file mode (run a command file) by entering the following at the WAVE> prompt:

WAVE> @filename

From a UNIX prompt, you can enter the filename in conjunction with the wave command:

wave filename

If you have created a startup file that has been defined with the environment variable WAVE_STARTUP, then you can enter the wave command at the UNIX prompt to run the command file. See "WAVE_STARTUP: Using a Startup Command File" for details.

note	You cannot execute a command file and a PV-WAVE command on the same command line. For instance, if you were to type the following commands at the WAVE> prompt, the command file will execute, but the PRINT command will not.

WAVE> @myfile & PRINT, a

PV-WAVE reads commands from the specified file until the end is reached. You can nest command files by prefacing the name of the new command file with the @ character. The current directory and then all directories in the !Path system variable are searched for the file. See "WAVE_PATH: Setting Up a Search Path (UNIX)".

Command file execution may be terminated before the end of the file with control returning to the interactive mode by calling the STOP procedure from within the command file. Calling the EXIT procedure from the command file has the usual effect of terminating PV-WAVE.

Command File Example

An example of a command line that initiates command file execution is:

; Use myfile for statement and command input. If not in the

; current directory, use the search path !Path.

WAVE> @myfile

Possible contents of myfile are shown below:

.RUN PROGA

.RUN PROGB

; Print results and close file on logical unit 3.

PRINT, avalue, bvalue

CLOSE,3

The command file should not contain complete program units such as procedures or functions. However, complete program units can be compiled and run by using the .RUN and .RNEW commands in the command files, as shown in the previous example.

Creating Journal Files

Journaling provides a record of an interactive PV-WAVE session. All text entered at the WAVE> prompt is entered directly into the file. The result is a file that contains a complete description of the PV-WAVE session which can be rerun later.

The JOURNAL procedure has the form:

JOURNAL [, param]

where the string parameter param is either a filename (if journaling is not currently in progress), or an expression to be written to the file (if journaling is active).

The first call to JOURNAL starts the logging process. If no parameter is supplied, a journal file named wavesave.pro is created. If a filename is specified in param, the session’s commands will be written to a file of that name.

note	Under UNIX, creating a new journal file causes any existing file with the same name to be lost. This includes the default file wavesave.pro. Use a filename parameter with the JOURNAL procedure to avoid destroying existing journal files.

Programmatically Controlling the Journal File

When journaling is not in progress, the value of the system variable !Journal is 0. When the journal file is opened, the value of this system variable is set to the logical unit number of the journal file that is opened. This fact can be used by routines to check if journaling is active. You can send any arbitrary data to this file using the normal PV-WAVE output routines. In addition, calling JOURNAL with a parameter while journaling is in progress results in the parameter being written to the journal file as if the PRINTF procedure had been used. In other words, the statement:

JOURNAL, param

is equivalent to:

PRINTF, !Journal, param

with one exception—the JOURNAL procedure is not logged to the file (only its output) while a PRINTF statement is logged to the file in addition to its output.

Journaling ends when the JOURNAL procedure is called again without an argument, or when you exit PV-WAVE.

note	The journal file can be used later as a command input file to repeat the session, and it can be edited with any text editor if changes are necessary.

JOURNAL Procedure Example

As an example, consider the following statements:

; Start journaling to file demo.pro

JOURNAL, 'demo.pro'

PRINT, 'Enter a number: '

; Read the user response into variable Z.

READ, Z

; Send a comment to the journal file using the JOURNAL procedure.

JOURNAL, '; This was inserted with JOURNAL.'

; Send another comment using PRINTF.

PRINTF, !Journal, '; This was inserted with PRINTF.'

; End journaling.

JOURNAL

If these statements are executed by a user named bobf on a Sun workstation named peanut, the resulting journal file demo .pro will look something like:

; SUN WAVE Journal File for bobf@peanut

; Working directory: /home/bobf/wavedemo

; Date: Mon Aug 29 19:38:51 1995

PRINT, 'Enter a number: '

; Enter a number: READ, Z

; This was inserted with JOURNAL.

; This was inserted with PRINTF.

PRINTF, !Journal, '; This was inserted with PRINTF.'

note	The statement to insert the text using JOURNAL does not appear.