Modifying your PV-WAVE environment (Windows)

PV-WAVE Foundation > Programmer Guide > Modifying Your Environment > Modifying your PV-WAVE environment (Windows)

Under Windows, PV‑WAVE obtains the information it needs to determine its initial state from environment variables. Windows allows environment variables to be specified in two ways:

The Registry

The System window (launched from the Windows Control Panel)

This section discusses ways to customize PV‑WAVE using environment variables. In addition, several important environment variables are discussed in detail.

note	As long as PV-WAVE is installed properly, your environment will be already set up. Much of the information in this section applies only if you wish to modify or customize your environment.

Adding a Procedure Library to the Search Path

This section explains how to add your own procedure library to the default PV‑WAVE path. This default path is used by PV‑WAVE to locate procedure libraries (directories containing .pro and .cpr files), such as the Standard Library and the User Library.

The best way to add a procedure library to the default path is to use the !Path system variable.

The system variable !Path stores a list of directories, similar to the PATH environment variable that Windows uses to locate commands. When PV‑WAVE starts, !Path is initialized with all of the directory paths necessary to run PV‑WAVE and any PV‑WAVE Companion Technologies or options that have been installed.

You can modify !Path while PV‑WAVE is running, or you can modify it in your PV‑WAVE startup file. If you modify !Path during a PV‑WAVE session, the change only takes effect for that session. If you modify the startup file, the change takes effect every time you start PV‑WAVE. (For information on the startup file, see "WAVE_STARTUP: Using a Startup Command File".)

For example, the following command adds the directory D:\myra\results\wave to the beginning of the search path:

!Path = 'D:\myra\results\wave;'+!Path

Again, if this line is typed at the WAVE> prompt, the change takes effect only for the current session. If you add this line to a PV‑WAVE startup file, the change takes effect every time you start PV‑WAVE.

note	When looking for a function or procedure file, PV‑WAVE searches current working directory first. PV-WAVE then looks for the function or procedure in the locations specified by !Path.

For more information on system variables, see "System Variables".

Environment Variables

PV‑WAVE relies on the user’s environment for configuration and customization information. The following environment variables tell PV‑WAVE where it is installed, where to find important files, and how it is to behave when started.

IMSLERRPATH	WAVE_GALL	WAVE_USER
IMSLSERRPATH	WAVE_GALL2	WAVE_PATH
RW_DIR	WAVE_GALL3	WAVE_VERSION
WAVE_DIR	WAVE_ARL	WAVE_BIN
WAVE_STARTUP	WAVE_RAY	WAVE_MSG
WAVE_APPL	WAVE_LANG	WAVE_CODEBOOK
WAVE_LIB	WAVE_DATA	WAVE_HELPDIR
WAVE_DEMO	WAVE_HELP_PATH	PVWAVE_LIC_FILE
PVWAVE_LOG_LM	PVWAVE_LM_LOGFILE

Support for Environment Variables in Windows

This section describes the environment variable support in Windows.

Environment Variable Support in Windows

Windows was designed to support applications ported from UNIX and has strong support for environment variables. You can set environment variables for an individual user and for a particular computer by using the System icon in the Windows Control Panel. This environment is picked up by GUI applications launched from the Program Manager as well as Console applications. Environment variables can take up as much space as needed and can be easily changed on a system-wide basis without restarting Windows.

How the PV-WAVE Environment is Set

At initialization, PV‑WAVE looks for each of the environment variables listed in the Table in section "Environment Variables" in the current environment. If the variable is found, PV‑WAVE uses its value and does no further processing for that variable.

note	The environment variables are processed in the order listed in listed in the Table in section "Environment Variables". This means that you can use the values of earlier environment variables when setting later ones: since RW_DIR is listed before WAVE_DIR, you can define WAVE_DIR as %RW_DIR%/wave.

WAVE_PATH: Setting Up a Search Path (Windows)

WAVE_PATH sets the function and procedure library directory search path. The search path is a list of locations to search if the procedure or function is not found in the current directory. The current directory is always searched first. PV-WAVE then looks for the function or procedure in the locations specified by the system variable !Path. For more information on system variables, see "System Variables".

Setting Up WAVE_PATH on a Windows System

The environment variable WAVE_PATH is a colon-separated list of directories. If you do not explicitly define WAVE_PATH, and you use PV-WAVE’s default startup command file, PV-WAVE starts its search in the current working directory, searches next in RW_DIR\wave\lib, and then searches numerous subdirectories of RW_DIR\wave\demo.

Each user may add directories to WAVE_PATH that contain PV-WAVE programs, procedures, functions, and “include” files. To add the WAVE_PATH environment variable:

1. In the Control Panel, double-click the System icon.

2. In the System Properties dialog box, click the Advanced tab, then the Environment Variable button (or click the Environment tab).

3. Create the new system variable WAVE_PATH and add the paths to the directories you want included in PV-WAVE’s path at startup.

RW_DIR and WAVE_DIR: Ensuring Access to Required Files

The RW_DIR environment variable must be correctly defined in order for PV-WAVE to run properly; RW_DIR is defined during the installation process.

All PV-WAVE files are placed in a subdirectory of RW_DIR that becomes the top-level directory for PV-WAVE; the path to this directory is stored in the environment variable WAVE_DIR. Look in the file system where you have installed Rogue Wave software and you will see a subdirectory named wave. This is where PV-WAVE has been installed, the directory to which the environment variable WAVE_DIR points, and where PV-WAVE expects to find its required files.

To see what the value of WAVE_DIR is on your computer, enter the following command at a Windows’ command prompt:

echo %WAVE_DIR%

note

Remember that RW_DIR and WAVE_DIR are only defined automatically on the machine where PV-WAVE was installed, and only for the user who performed the installation. If you wish to run PV-WAVE on a different machine or for different users, you must explicitly set the value of these variables using the Control Panel’s System window before you run PV-WAVE on that machine for the first time. Or, you can rerun the installation program (the setup program). For detailed information on rerunning the setup program, see the Installation Guide. You may also need to use the File Manager to connect the disk that contains the PV-WAVE files. For instructions on connecting another disk, consult your Windows documentation.

When Are PV-WAVE’s Environment Variables Defined?

RW_DIR and WAVE_DIR are the only environment variables that get defined during the installation process. Other PV-WAVE environment variables get defined dynamically as PV-WAVE is started. However, the value of any environment variable that has been explicitly defined prior to PV-WAVE startup is left intact instead of being redefined during startup. For information about other PV-WAVE environment variables, refer to subsequent sections in this discussion of the PV-WAVE environment.

Method of Starting PV-WAVE Can Affect Your Environment

When you make changes to values of environment variables on your system, the value applies only to command prompt windows that you open after making those changes.

However, the Windows program group to which PV-WAVE belongs will be unaware of the changes you made. Consequently, if you start PV-WAVE by clicking on an icon in a program group, that session of PV-WAVE will also be unaware of the changes you made. For the program group to be aware of the changes you made, you must log off and then log back on to your computer.

WAVE_DATA: Retrieving Data Files Directly Where They Reside

You can store your data in a different area, e.g., a disk that actually resides on a different computer, and still easily access those files, by defining a value for WAVE_DATA prior to starting PV-WAVE. This way you can leave your data files intact in the area where you first stored them, and not have to specify a long path to them or copy them into your current working directory.

note	The default WAVE_DATA path is used by the PV‑WAVE Gallery and other demonstration programs. If you reset WAVE_DATA, these demonstration systems will not work.

Using WAVE_DATA in PV-WAVE Function and Procedure Calls

WAVE_DATA specifies a single path, and this path is used to initialize the PV-WAVE system variable !Data_Dir. You can then use this system variable as a shorthand notation for pointing to data files, as shown in the following sample PV-WAVE statements:

OPENR, 1, !Data_Dir+'latest.dat'

or:

status = DC_READ_DIB(!Data_Dir+'ztee.bmp', $
 zt, Imagewidth=xsize, Imagelength=ysize)

PV-WAVE does not use a search path when accessing, opening, and closing data files; it uses only the path that you specify, which is the current working directory if you have not specified any other path.

note

By default, !Data_Dir is initialized during PV-WAVE startup by a call to setdemo.pro. If the startup command file you are using does not include a call to setdemo.pro, several system variables, including !Data_Dir, may not be initialized properly. For more details, refer to "WAVE_RT_STARTUP: Using a Startup Procedure in Runtime Mode".

WAVE_DEVICE: Defining Your Terminal or Window System

PV-WAVE must know the type of terminal or window system that you are using. By default, it assumes win32 (Windows, 32 bit). If you wish, this default can be changed, as described below.

Changing the Default Device

PV-WAVE sets the value of the environment variable WAVE_DEVICE to win32 when it starts. But if you prefer WAVE_DEVICE to have a different value, such as PS (PostScript), you can enter the following command at the command prompt window:

set WAVE_DEVICE=PS

In this situation, PV-WAVE will start as expected, but will send graphics output to a file using the specified format (PostScript) and the default filename of wave.ps. You will not be able to display graphics windows on the screen of your computer until you enter the command:

SET_PLOT, 'win32'

The device name can be entered in either upper or lower case. If WAVE_DEVICE is defined, it must contain the name of a valid PV-WAVE graphics device. For details, see the list of valid output devices in the PV‑WAVE Reference.

note

Use the DEVICE command to reconfigure the behavior of any of PV-WAVE’s drivers, including the PostScript driver mentioned in this section. For example, you could use the Filename keyword to choose a different output filename, or you could use the Epsi keyword to enable encapsulated PostScript interchange format.

WAVE_STARTUP: Using a Startup Command File

WAVE_STARTUP points to the full pathname of a command file that is executed by PV-WAVE on initialization. The startup file contains a series of PV-WAVE statements and is executed each time PV-WAVE is started. Common uses are to compile frequently-used procedures or functions, to load data, and to perform other useful operations. It contains PV-WAVE statements which are individually compiled and executed, in the same manner as command file execution. For more information on command files, see "Creating and Running a Command (Batch) File".

The default startup filename is wavestartup and is located in %WAVE_DIR%\bin. The wavestartup file turns off the compiler messages, defines the WAVE> prompt, and then calls the Standard library routine setdemo.pro. This routine sets up the default key bindings for the function keys. For more information about the SETDEMO command, see the PV‑WAVE Reference.

To use a different PV-WAVE startup file:

Create a file containing the commands you want to be executed every time you start PV-WAVE. For example, assume the startup file named startfile.txt contains the following statements:

.RUN add.pro

.RUN square.pro

INFO

At a Windows’ command prompt, enter this command to set the environment variable WAVE_STARTUP to the name of the file to be executed:

	set WAVE_STARTUP=startfile.txt

The startup file compiles ADD and SQUARE and displays general information about the current status of PV-WAVE before displaying the normal WAVE> prompt. The messages you see when you start PV-WAVE this way are shown in Figure 16-9: PV-WAVE Console Window below.

To use this startup file every time you start PV-WAVE use the System icon in the Windows Control Panel or modify the AUTOEXEC.BAT file.

Figure 16-9: PV-WAVE Console Window

note

When you create a new startup file, start with a copy of PV-WAVE’s default startup file, wavestartup. This way, you will still define a default WAVE> prompt and default behavior for function keys. Also, you will not inadvertently disable the setups for a PV-WAVE feature, e.g., the PV-WAVE gallery, that you might want to use later.

WAVE_FEATURE_TYPE: Setting Default Operating Mode

The environment variable WAVE_FEATURE_TYPE lets you set the default operating mode of PV-WAVE to “runtime”. When this environment variable is set to RT, compiled PV-WAVE applications can be executed directly from the operating system prompt without using the -r option. For example:

C:\ set WAVE_FEATURE_TYPE=RT

Set the environment variable.

C:\ wave somerset

Run a compiled, saved PV-WAVE application called somerset.

WAVE_RT_STARTUP: Using a Startup Procedure in Runtime Mode

WAVE_RT_STARTUP points to the name of a compiled procedure file that is executed when PV-WAVE initializes in runtime mode. The startup file may contain saved, compiled PV-WAVE routines that are executed each time PV-WAVE is started in runtime mode.

note	For more information on saving and using compiled routines, see "Runtime Mode for Windows".

The default startup filename that PV-WAVE looks for when it is running in runtime mode is:

%WAVE_DIR%\LIB\STD\rtwavestartup.cpr

WAVE_INIT_CODESIZE: Setting Initial Size of Code Area

The environment variable WAVE_INIT_CODESIZE lets you set the initial size of the code area for PV-WAVE. For example:

C:\ set WAVE_INIT_CODESIZE 2000000

Set the initial size of the code area to 2 MB.

WAVE_INIT_LVARS: Setting Initial Value for Number of Local Variables

The environment variable WAVE_INIT_LVARS lets you set the initial number of local variables for PV-WAVE. For example:

C:\ set WAVE_INIT_LVARS 400

Set the initial number of local variables to 400.

PVWAVE_LIC_FILE

The environment variable PVWAVE_LIC_FILE allows you to specify a license file for PV-WAVE that is other than the default. By default, PV-WAVE uses the file: RW_DIR/license/license.pvwave. If you wish to specify an alternative file or location, set PVWAVE_LIC_FILE to be the full path to and file name of the license file you wish to use. Only one file may be specified.

note	For information on the license monitoring environment variables, see PVWAVE_LOG_LM and PVWAVE_LM_LOGFILE in the License monitoring details section.

PVWAVE_LM_WHITELIST

The environment variable PVWAVE_LM_WHITELIST allows you to restrict the use of PV-WAVE to a specified list of users. Set PVWAVE_LM_WHITELIST to the full path to and file name of the text file containing the list of users allowed to use PV-WAVE. PV-WAVE compares the user name of the account currently using PV-WAVE to this list of users. If the user name does not appear in the list, PV-WAVE displays the following message and exits:

Unauthorized user: username; please see your local PV-WAVE site administrator

The file containing the list of users must conform to the following format restrictions:

Must be a plain text file.

Each name must be on a separate line.

Lines beginning with the comment character (#) are ignored. Comment characters that do not begin a line are considered part of the user name.

Does not include leading or trailing spaces which are not part of the user name.

Does not include domain names.

note	If PVWAVE_LM_WHITELIST is defined and PV-WAVE cannot find or open the file, it prints an error and exits.

Changing the PV-WAVE Prompt

The text string PV-WAVE uses to prompt you for input is specified by the system variable !Prompt. You can change the prompt by setting this system variable to the new prompt string. The prompt is currently defined in the file wavestartup.

Here’s an example showing how to tailor your prompt to display text:

!Prompt = 'Hello World!> '

Here’s another example that causes PV-WAVE to echo the text string, plus ring the bell on the terminal when prompting:

!Prompt = 'Hello World!> ' + STRING(7B)

The ASCII code for the bell is 7. It does not have a printable representation, so it is specified using the value 7.

note	See "Representing Nonprintable Characters with Windows". You can also place a prompt definition in your WAVE_STARTUP file; this file is described in "WAVE_STARTUP: Using a Startup Command File" of this guide.

For an alternate way to modify the prompt, see the description of the PROMPT procedure in the PV‑WAVE Reference.