Modifying your PV-WAVE environment (UNIX)

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

Under UNIX, PV-WAVE uses environment variables to determine its initial state. This section explains how to modify or customize environment variables and logicals.

note	Normally, you do not need to alter your environment. If PV-WAVE is installed properly, your environment will be already set up. The information in this section applies only if you wish to modify or customize your environment.

WAVE_DEVICE: Defining Your Terminal or Window System

In order to function properly, PV-WAVE must know the type of terminal or window system you wish to use. By default, it assumes X, the X Window System. If you wish, this default can be changed, as described below.

Changing the Default Device on a UNIX System

PV-WAVE reads the value of the environment variable WAVE_DEVICE when it starts. If WAVE_DEVICE is defined, PV-WAVE calls the procedure SET_PLOT with this string. For example, to use PV-WAVE with Tektronix terminals, include the following command in your .login (or .profile) file:

setenv WAVE_DEVICE tek

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.

note	See the description of SET_PLOT in the PV‑WAVE Reference for a complete list of device names.

WAVE_DIR: Ensuring Access to Required Files

WAVE_DIR is the root of the PV-WAVE directory structure. All PV-WAVE files are located in subdirectories of WAVE_DIR.

Setting WAVE_DIR on a UNIX System

The WAVE_DIR environment variable must be correctly defined in order for PV-WAVE to run properly. If WAVE_DIR is not defined, PV-WAVE assumes a default of /usr/local/lib/wave.

To make sure that you have WAVE_DIR properly defined, enter the following command at the UNIX prompt:

source RW_DIR/wave/bin/

where RW_DIR is the main Rogue Wave installation directory.

WAVE_PATH: Setting Up a Search Path (UNIX)

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 UNIX 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. You may find it convenient to add to the value that is already defined in your wvsetup file. For example, in csh use the following command:

setenv WAVE_PATH $WAVE_PATH":"/user/mylib

This command adds the directory /user/mylib to the existing variable WAVE_PATH.

!Path is a colon-separated list of directories, similar to the PATH environment variable that UNIX uses to locate commands. When PV-WAVE starts, !Path is initialized from the environment variable WAVE_PATH. The value of !Path may be changed once you are running PV-WAVE. For example, the following command adds the directory /usr2/home/wave_files to the beginning of the search path:

WAVE> !Path = '/usr2/home/wave_files:' + !Path

Setting Up WAVE_PATH on a WIndows System

To set up the WAVE_PATH on a Windows sytem, see "WAVE_PATH: Setting Up a Search Path (Windows)" .

WAVE_STARTUP: Using a Startup Command File

WAVE_STARTUP points to the name of a command file that is executed when PV-WAVE starts. Common uses are to compile frequently-used procedures or functions, to load data, and to perform other useful operations. It contains 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 file for UNIX is called wavestartup and is located in <path>/wave/bin.

The wavestartup file turns off the compiler messages, sets up 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.

note	Setting WAVE_STARTUP to a file with no PRINT statements or to /dev/null suppresses all startup messages for PV-WAVE.

Using a Startup File Under UNIX

To use a startup file under UNIX, set the environment variable WAVE_STARTUP to the name and path of the file to be executed. For example, assume the startup file named startfile contains the following statements:

.RUN add.pro

.RUN square.pro

INFO

In csh, set the environment variable with the setenv command:

setenv WAVE_STARTUP startfile

When you start PV-WAVE by entering wave at the UNIX prompt, you get the following display:

PV-WAVE. Version ...

% Compiled module: ADD.

% Compiled module: SQUARE.

% At $MAIN$ .

Code area used: 0.00% (0/16384), Data area used: 0.05% (2/4096)

# local variables: 0, # parameters: 0

Saved Procedures:

ADD

Saved Functions:

 SQUARE

WAVE>

The startup file compiles the ADD procedure and the SQUARE function, and displays general information about the current status of PV-WAVE before displaying the WAVE> prompt.

WAVE_FEATURE_TYPE: Setting Default Operating Mode

The environment variable WAVE_FEATURE_TYPE lets you set the default operating mode 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:

% setenv WAVE_FEATURE_TYPE RT

Set the environment variable.

% wave somerset

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

WAVE_RT_STARTUP: Using a Startup Procedure in Runtime Mode

The environment variable 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 PV-WAVE routines that are executed each time PV-WAVE is started in runtime mode.

Set WAVE_RT_PATH to the directory where the WAVE_RT_STARTUP file is located. This enables users to start PV-WAVE in runtime mode from anywhere.

At startup, WAVE_RT_PATH is appended to WAVE_PATH.

note	To define WAVE_RT_PATH, set a system level environment variable %WAVE_PATH% that includes the directory where the WAVE_RT_STARTUP file is located. Otherwise, you will need to start PV-WAVE from the directory where the WAVE_RT_STARTUP file is located.

Setting WAVE_RT_PATH isn't required, but is recommended for WAVE_RT_STARTUP users. It's also recommended that users place WAVE_RT_STARTUP in its own directory so they don't end up with unexpected files being found under WAVE_PATH.

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

On a UNIX system, the default startup file for 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:

% setenv 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:

% setenv WAVE_INIT_LVARS 400

Set the initial number of local variables to 400.

WAVE_MSG: Suppressing Startup Messages

The environment variable WAVE_MSG lets you suppress the version and copyright messages for PV-WAVE. For example:

% setenv WAVE_MSG NO

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 for UNIX. 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 ring the bell on the terminal without echoing visible text when prompting:

!Prompt = '\007'

The ASCII code for the bell is 7. It does not have a printable representation, so it is specified using the octal escape sequence \007.

note	See "Representing Nonprintable Characters with UNIX". You can also place a prompt definition in your WAVE_STARTUP file, as described on "WAVE_STARTUP: Using a Startup Command File".

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

Defining Keyboard Shortcuts

Function keys may be equated to a character string using the DEFINE_KEY procedure. For example, the <R4> key on a Sun-style keyboard or the <PF4> key on a Digital keyboard, can be equated to the string PLOT, as shown in the example below. This allows frequently used strings and commands to be entered with a single key stroke.

; Load predefined function key definitions.

SETUP_KEYS

; Enter the text "PLOT" when the F11 function key is pressed.

DEFINE_KEY, 'F11', 'PLOT'

For detailed information on DEFINE_KEY, see the PV‑WAVE Reference.

INFO, /Keys displays current definition of all function keys.

note	A natural place to put your key definitions is in the startup file so that the function keys are defined when PV-WAVE is initialized. The defaults for the key definitions are set up with the setdemo.pro procedure in the wavestartup file. See "WAVE_STARTUP: Using a Startup Command File".

Using PV-WAVE with X Windows

A brief explanation of how to set up the X Windows system to work with PV-WAVE is provided in this section.

note	The interface to the X Windows system is described in the PV‑WAVE Reference.

If You Are Running Under X Windows

Little or no customizing is required to use PV-WAVE with the X Windows system. You can control the number of colors used by PV-WAVE, if and how windows are repainted, and the type of color system (visual class).

Be sure that your system is properly set up to display X graphics. For UNIX systems under the C shell, you may need to enter:

% setenv DISPLAY hostname:0.0

% xhost hostname