Using PV‑WAVE in Runtime Mode

PV‑WAVE can interpret and execute two kinds of files: source files and compiled files.

Source Files—Functions and procedures saved as regular ASCII files with a .pro filename extension. When a function or procedure of this type is called, it is first compiled, then executed by PV-WAVE.

Compiled Files—Functions and procedures that are first compiled in PV-WAVE, then saved with the COMPILE procedure. By default, such files are given a .cpr filename extension. Because a file of this type is already compiled, it can be executed more quickly than a .pro file.

For detailed information on the COMPILE procedure, see its description in the (Undefined variable: pvwave.waveur).

This ability to handle both source and compiled files allows PV‑WAVE to be run in two different modes:

Interactive mode—The mode normally used for PV-WAVE application development and direct access to the PV-WAVE command line.

Runtime mode—Allows direct execution of PV-WAVE applications composed of compiled routines that have been saved with the COMPILE procedure. The runtime mode is described in the following sections.

Runtime Mode for UNIX

All of the interapplication communication methods described in the PV-WAVE Application Developer’s Guide are supported in runtime mode except the unidirectional communication routines wavecmd, waveinit, and waveterm.

Starting PV‑WAVE in Runtime Mode (UNIX)

In runtime mode, you can run a compiled PV‑WAVE application directly from the operating system prompt. When the compiled application is finished running, control returns to the operating system level.

Note:

To execute a runtime mode (compiled) application, you must have a runtime license. Without a runtime license for PV‑WAVE, you will be unable to start PV‑WAVE in runtime mode as described in this section. For information on obtaining a runtime license for PV‑WAVE, please contact Rogue Wave.

The application must first be compiled and saved with the COMPILE procedure. For example, if the procedure called images is compiled, the command:

COMPILE, 'images'

saves a file containing the compiled procedure. By default, this file is named images.cpr, and it is saved in the current working directory. For detailed information on the COMPILE procedure, see its description in the (Undefined variable: pvwave.waveur).

Note:

PV‑WAVE in runtime mode cannot compile applications. Applications may only be compiled using PV‑WAVE with a developer’s license.

To execute the compiled, saved application named images.cpr from the operating system prompt, enter the following command, where -r is a flag that specifies runtime mode:

wave -r images

When the application is finished running, control is returned to the operating system prompt. Note that the .cpr extension is not used when invoking the application.

You can set the default mode to “runtime” with the environment variable WAVE_FEATURE_TYPE by typing on a UNIX system:

setenv WAVE_FEATURE_TYPE RT

Now, the -r flag is not needed, and you can run the application by entering:

wave images

The read-only system variable !Feature_Type allows you to distinguish between runtime mode and normal, interactive mode. This system variable simply reflects the current setting of the WAVE_FEATURE_TYPE environment variable (UNIX).

More than one saved compiled file can be executed at a time from the operating system prompt. Just separate the application filenames with spaces, as follows:

wave file_1 file_2 file_3 ...

Search Path for Compiled Routine Files (UNIX)

Whenever a user-written procedure or function is called, PV-WAVE searches first for saved, compiled files (.cpr files) with the same name as the called routine. If a saved, compiled file is not found, PV-WAVE searches for a source file (.pro file). PV-WAVE searches the current directory and all directories specified in the !Path directory path.

If you place a .pro file in the current working directory that has the same name as a .cpr file further along the directory path, the .cpr file will always be found and executed first.

Note:

The compiled (.cpr) file must have the same name as the called routine. If the calling name of an application program is images, then the saved, compiled file must be called images.cpr.

Developing Runtime Applications (UNIX)

Applications developed for operation in runtime mode must adhere to the following guidelines:

Only PV‑WAVE routines that are compiled and saved with the COMPILE command can be executed in runtime mode. The COMPILE command is only available with a developer’s license.

The startup file pointed to by the WAVE_RT_STARTUP environment variable (UNIX) must be compiled and saved with the COMPILE command. The startup file must be in a directory pointed to by the WAVE_PATH environment variable (UNIX). For more information on this startup file, see WAVE_RT_STARTUP: Using a Startup Procedure in Runtime Mode.

Executive commands .RUN, .RNEW, .GO, .STEP, .SKIP, .CON, and the STOP routine are not recognized in runtime mode.

Breakpoints specified with the BREAKPOINT procedure are not recognized in runtime mode.

Any errors that occur in runtime mode are reported as usual, and control is returned to the operating system prompt.

Runtime Mode for Windows

In the Windows version of PV‑WAVE, you can run a PV‑WAVE application from a Windows command prompt. When the application is finished running, control returns to the operating system level.

Starting PV-WAVE in Runtime Mode (Windows)

To execute a compiled, saved application from the operating system prompt, enter the following command, where -r is a flag that specifies runtime mode:

wave -r filename

When the application is finished running, control is returned to the operating system prompt. Note that the .cpr extension is not used when invoking the application.

You can set the default mode to “runtime” with the environment variable WAVE_FEATURE_TYPE by typing:

set WAVE_FEATURE_TYPE=RT

Now, the -r flag is not needed, and you can run the application by entering:

wave filename

More than one saved compiled file can be executed at a time from the operating system prompt. Just separate the application filenames with spaces, as follows:

wave file_1 file_2 file_3 ...

Search Path for Compiled Routine Files (Windows)

The compiled (.cpr) file must have the same name as the called routine. If the calling name of an application program is images, then the saved, compiled file must be called images.cpr.

If you place a .pro file in the current working directory that has the same name as a .cpr file further along the directory path, the .cpr file will always be found and executed first.

Developing Runtime Applications (Windows)

Applications developed for operation in PV‑WAVE’s runtime mode must adhere to the following guidelines:

Only PV‑WAVE routines that are compiled and saved with the COMPILE command can be executed in runtime mode. The COMPILE command is only available with a developer’s license.

The startup file pointed to by the WAVE_RT_STARTUP environment variable must be compiled and saved with the COMPILE command. The startup file must be in a directory pointed to by the WAVE_PATH environment variable. For more information on this startup file, see WAVE_STARTUP: Using a Startup Command File.

PV‑WAVE executive commands .RUN, .RNEW, .GO, .STEP, .SKIP, .CON, and the STOP routine are not recognized in runtime mode.

PV‑WAVE breakpoints specified with the BREAKPOINT procedure are not recognized in runtime mode.

Note:

Any errors that occur in runtime mode are reported as usual, and control is returned to the operating system prompt.

Runtime Mode for Dynamically Loaded Options

Applications developed with the Option Programming Interface (OPI) can be used in runtime mode.

To load an OPI application in runtime mode, you must include the startup call for the option at the beginning of the runtime procedure. For example, the commands math_init, stat_init, and sigpro_init start PV-WAVE IMSL Mathematics, PV-WAVE IMSL Statistics, and the PV‑WAVE Signal Processing Toolkit.