2 Starting and Exiting AVS/Express

This chapter gives you the information you need to start AVS/Express. If you need to install AVS/Express, read the Installing AVS/Express manual.

This chapter also provides some background information on environment variables and system configurations that may be useful if you run into trouble.

This chapter discusses:

2.1 Starting AVS/Express

The following steps outline how to start-up AVS/Express. If you have installed and used it before, this overview may be all you need to get started. If you are a new user, please look more closely at the detailed sections which follow before starting-up AVS/Express.

For more information about using environment variables with AVS/Express, see See Using Environment Variables on page 2-6..

For comprehensive information on running AVS/Express in your environment, see the Installing AVS/Express manual.

Starting AVS/Express

1. Set environment variables.

On all platforms: Set PATH to include the express installation directory. For more information on setting the PATH environment variable for AVS/Express, see PATH on page 2-7. Set the MACHINE environment variable to identify your operating system. For information on setting MACHINE, see MACHINE on page 2-6.
In addition, on UNIX platforms: Make sure the DISPLAY environment variable is set to your workstation name. For information on setting DISPLAY, see DISPLAY (UNIX only) on page 2-6. On all platforms except HP and IBM, set the LD_LIBRARY_PATH environment variable to include the path to the directory lib/$MACHINE in the AVS/Express installation directory. On HP set the SHLIB_PATH environment variable to include the same location. Shared libraries are not used on the IBM platforms. For information about using shared libraries, see Using Shared Libraries on UNIX Platforms on page 2-7. Note: In some environments you may also need to set the XP_PATH environment variable to the AVS/Express installation directory. For information about setting XP_PATH, see XP_PATH on page 2-11.

2. Navigate to the express directory.

3. Start AVS/Express by typing the platform-specific command listed below.


Visualization Edition users type:

Table B-1


UNIX	Windows
vxp	bin\pc\vxp -or- click on the application icon

Developer Edition users type:

Table B-2


UNIX	Windows
express	bin\pc\express -or- click on the application icon

The V Command Processor (VCP) appears. Then the Network Editor window appears along with a dialog box that allows you to choose an application framework.
You can add a number of command line options to these commands to control how AVS/Express is configured when it starts.
For more information about the AVS/Express command line options, see Using Command Line Options on page 2-12.
You must have a valid license for the AVS/Express edition you choose. If AVS/Express will not start, refer to Installing AVS/Express or contact your license administrator.

4. Choose an initial application type.

When you enter either startup command, AVS/Express displays the Network Editor and a dialog box in which you choose the initial configuration you want to use:

Figure B-1

Select one of the DataViewer applications to enter a predefined application framework that already includes a visualization environment.

The single-window DataViewer displays a window combining a viewer window in which you can display your data or image, and a set of editors that you can use to customize and interact with the viewer configuration. The multi-window DataViewer application creates two windows, a viewer window and a separate window for the editor controls. Before selecting either DataViewer configuration you can use the Viewer type radio buttons to create viewer windows that support 3D or 2D data, or both.

Select Application to create a development framework with no predefined subobjects. This choice loads the DefaultApplication object.
Select Module Stack to load the ModuleStack application. This was the default application in AVS/Express prior to Release 3.0.
Select Scratch Pad to load the ScratchPad application. ScratchPad provides a workspace in which you can create and edit objects.
Select Load application to load an application you have previously saved.
Select None to start AVS/Express without loading any application. In this case, the lower section of the Network Editor displays the Applications subobject. This subobject is intended to be an ancestor of all objects you create. You can add any macro object to Applications, but we recommend you first add an application type object. The application type is a special macro designed to encapsulate an entire application.

For example, you can choose None before instancing one of example applications in the Examples library.

Select Add Data Import Wizard to application to have the Data Import Wizard help you choose the correct reader for you application
Select Add Data Visualization Wizard to application to have the Data Visualization Wizard help you create your application

For more information about the initial application types, see Choosing Your Initial Application on page 3-2.

5. To make your application choice the default application and avoid the start-up dialog, you can set the Set project's default application button on.

To enable this choice as the default, you must save the current session in a project file before exiting, When you start AVS/Express again using this project, the Network Editor loads your choice as the default and does not display the start-up dialog.

6. Click OK.

AVS/Express initializes the Network Editor with the application you have selected and executes any subobjects contained in the application. For an introduction to using the Network Editor, see Chapter 3, Working with the Network Editor

AVS/Express also starts the V Command processor in the console window in which you started AVS/Express. The V Command processor is a command-line interface to AVS/Express. For more information about using the VCP, see Chapter 7, V and the V Command Processor.

2.2 Using Environment Variables

Setting Required Environment Variables

Before starting AVS/Express, be sure that the following environment variables are set correctly:

Table B-1


Environment variable	Description
DISPLAY (UNIX only)	DISPLAY specifies your workstation name: % setenv DISPLAY workstation_name:0 causes X windows to be displayed on display 0 of the computer whose hostname is workstation_name.
MACHINE	Set MACHINE to specify the type of computer and operating system on which you are running. AVS/Express uses this variable to determine the location of executable programs, object libraries, and include files: % setenv MACHINE platform-type For the Windows version of AVS/Express, set MACHINE to pc if it is an Intel machine and alpha_nt if it is a Digital Alpha machine. For the UNIX version, set MACHINE to specify the operating system on which you are running AVS/Express: Platform Value for MACHINE SunOS 5.7 s7 SunOS 5.8 s8 SGI(n32) sgN32 SGI(n64) sg6 HP-UX 10.20 hp1020ex HP-UX 11 hp11 IBM RISC System/6000 ibm Compaq Tru64 5.1 alpha Red Hat Linux 6.0 linux_rh6 Red Hat Linux 7.0 linux You can confirm the correct value for MACHINE by running the script xp_mach, found in the bin subdirectory of your installation directory.
LD_LIBRARY_PATH or SHLIB_PATH (UNIX only)	On UNIX platforms other than HP, you must set LD_LIBRARY_PATH to include the path to the directory lib/$MACHINE in the AVS/Express installation directory. On HP platforms set the SHLIB_PATH environment variable. These variables specify the location of shared libraries required to run AVS/Express. For more information, see See Using Shared Libraries on UNIX Platforms on page 2-7..
PATH	Set PATH to include the pathname of the directory containing the AVS/Express executable, express. The executable is in bin/$MACHINE in your installation directory. If you have created your own project and have recompiled express, the executable is in bin/$MACHINE in your project's directory.

Using Shared Libraries on UNIX Platforms

IMPORTANT: You must set LD_LIBRARY_PATH (or on HP, SHLIB_PATH) to include the lib/<machine> subdirectory of the express install area.

The LD_LIBRARY_PATH or SHLIB_PATH variables may already be set in your environment for use by other applications. If the variable is not set, set it to the AVS/Express library. For example,

setenv LD_LIBRARY_PATH <avs_install_dir>/lib/$MACHINE

If LD_LIBRARY_PATH or SHLIB_PATH is already set on your system, append the path <avs_install_dir>/lib/$MACHINE to the list of directories. You can edit your .login or .profile files directly to add the directory. Or you can enter a new setenv command. For example,

setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:<avs_install_dir>/lib/$MACHINE

Setting Environment Variables In A Startup File

When you save a project, AVS/Express creates a file called avsenv to define environment variables that will be global to the express process. (AVS/Express does not use an .expressrc file.)

The following section describes how you can add your own AVS/Express environment variables to avsenv so that they are set automatically when you start AVS/Express.

The avsenv File Format

The format of the lines in an avsenv file is: VARIABLE = value ...

For example:

XP_PATH=/home/users/me/proj1 /home/express

Lines beginning with the `#' character are ignored.

Locating avsenv

AVS/Express looks for an avsenv file in this order, stopping with the first it finds:

1. The directory specified by the -project command line option, if any.

2. The current directory. That is, the directory in which you started AVS/Express.

3. ~/avsenv (in the home directory of the user invoking AVS/Express.)

4. The directory two levels above the executable's directory. So, if the executable
is in /home/express/bin/sgi, AVS/Express looks in /home/express.

Other Environment Variables Used By AVS/Express

The following environment variable are used by AVS/Express. Usually you will not need to do anything with these variables. However, it may be useful to you to know how AVS/Express uses these variables.

AVS/Express uses the following environment variables:

Table B-2


Environment variable	Description
ARR_TRACE	If this variable is set (to any non-null value), Express will print a one line message every time an ARR array is allocated, reallocated, freed, or has its reference counter incremented or decremented. If XP_EXIT_CLEANUP is also set, a summary of leaked arrays will be printed at exit. Warning: this can result in a lot of output.
OM_NO_CRASH_HANDLER	If set to 1, do not write V to a file upon abnormal termination. Do this in order to get a better structured back trace when debugging AVS/Express.
OM_NO_SERVER	If set to 1, do not create a socket for AVS/Express. AVS/Express requires a socket if it communicates with an external process such as a separately compiled and linked user application.
XP_DEFAULT_RENDERER	Controls which renderer is the default. Valid values are OGL, SW, XGL (s7 only), and PEX (hp1020 only).
XP_ERROR_LOG	Set to a filename and error messages will be written to the file. It works on all platforms, but its really only needed on Windows for the specific scenerio where error messages appear in the VCP window, but the VCP window disappears before the messages can be read.
XP_EXIT_CLEANUP	If this variable is set (to any non-null value), Express will attempt to clean up allocated memory at exit. This variable is not needed for the normal operation of Express or Express runtimes. This variable is intended for use by developers testing Express with memory leak detection tools such as Purify.
XP_GAMMA	Controls the brightness of the display for all AVS/Express windows except windows produced by a hardware renderer. The default varies from platform to platform. Values between 1.7 and 2.2 are good starting points for experimentation. Higher real values produce a lighter display.
XP_HELP_PATH	The path to the AVS/Express help.
XP_HELP_BROWSER	Unix only. Controls which HTML browser is used to view the help files when the browser is launched from the Network Editor. The default is "netscape". The values "KDE" and "GNOME" are treated specially. If the variable is "KDE", the kfmclient program is used to invoke Konqueror. If the variable is "GNOME", the gnome-moz-remote progam is invoked. On Windows, help files are launched using the current default .htm file handler.
XP_HELP_BROWSER	Unix only. Controls which browser is used to view the HTML help files when the browser is launched from the Network Editor. The default is "netscape". The values "KDE" and "GNOME" are treated specially. If the variable is "KDE", the kfmclient program is used to invoke Konqueror. If the variable is "GNOME", the gnome-moz-remote progam is invoked. On Windows, the equivalent functionality is achieved by simply using the current default .htm file handler.
XP_HELP_PATH	You can use XP_HELPPATH to specify the location of the AVS/Express online help files. If XP_HELPPATH is unset, the system will look for help files in the runtime/help subdirectory of the installation directory. You can move the help files to any other directory and set XP_HELPPATH to access them.
XP_PATH	Defines a list of project directories, specified as absolute pathnames. Your project directory, if any, should be specified first, followed by the "initial" project directory--the AVS/Express installation directory. (In V code, this "rightmost" directory in the list is referred to as $XP_PATH<0>.) For example: XP_PATH=/home/users/me/proj1 /home/express When you start AVS/Express, it looks for a definition of XP_PATH. It looks in the places described below, in the order listed: The -path option on the express command line. An explicitly set XP_PATH environment variable. The first avsenv file it finds that includes a definition of XP_PATH. If it does not find a definition for XP_PATH in the above places, then AVS/Express sets it to the directory two levels above where it found the express executable. It determines this from your regular shell PATH. For example, if it found express in: /disk2/user/you/express/bin/$MACHINE, then XP_PATH would automatically be set to /disk2/user/you/express. If your shell PATH does not include the current directory (.), then AVS/Express may not be able to set XP_PATH and you should set it explicitly. AVS/Express uses the value of XP_PATH to automatically set a number of important internal environment variables (XP_VPATH, XP_BINPATH, etc.). You should not set these internal environment variables yourself.
XP_ROOT	The express program does not use this environment variable. Rather, it is used in the AVS/Express makefiles to locate libraries and include files when you compile or link AVS/Express functions. It is normally set automatically by the project mechanism. However, you will need to set it explicitly if you copy one of AVS/Express' makefiles as a model to build your own.

2.3 Using Command Line Options

You can include a number of command line options when you enter either the express or vxp command to start AVS/Express. The following table describes all the available command line options.

Option

Description

-boss

Make this AVS/Express process the main process, overriding the OM_BOSS environment variable.

-client filename

Run this process as a client process using server information obtained using the -server filename option.

-compile

Compile all processes listed in the proc.v file.

-comp_proc process_name

Compile only the process specified.

-display hostname:display

(UNIX systems only) Specifies the X Window System display on which AVS/Express will display any X windows it generates. Overrides the DISPLAY environment variable, if set.

-exit

Exit after processing options (such as -compile).

filename

Loads the specified V file into the Applications object. You use this filename command line option to start an application that was saved using the Save Application command.

By default, neither the Network Editor nor the VCP appears, but you can start either by combining this option with the -ne or -vcp command line options.

AVS/Express does not assume nor append a file suffix of .v to the listed V file. By default, AVS/Express looks for the named V file in this sequence, using the first one it finds:

The v subdirectories defined by the XP_PATH when an event is queued.

The current directory (the directory from which you started AVS/Express.

-genlibs

Compile binary versions of all the libraries.

-gen_proc process_name

Generate source for the process specified.

-ne

Explicitly requests the Network Editor. This is useful with the filename option.

-nocxx

Do not use C++ to compile in this session.

-nohw

Disables all hardware renderers.

-none

Suppresses the Network Editor.

-novcp

Suppresses the VCP.

-offscreen

(UNIX systems only) When AVS/Express is started with the -offscreen flag, no visible windows will be created.

For this mode to be useful, you will need to prepare a non-interactive application using normal Express faculties. The application might automatically loop over its input or the application might read commands from a script file or receive commands from another program via a network connection, but it is crucial that the application can run normally without any user input from a UI.

-path "dir1 dir2 ..."

Sets the value of the XP_PATH environment variable from the command line. This command line option overrides all other devices by which XP_PATH may be set. Note that you must specify all directories, including the main AVS/Express installation directory that would be represented by $XP_PATH<0> in V code.

The list of directories must be enclosed in double quotes. The other directories may not exist yet; you may intend to create them during the session with the Network Editor's Project->Save menu sequence.

-project dir

Reads the avsenv file in the directory specified to obtain a value of XP_PATH. This overrides all other mechanisms of obtaining the XP_PATH value.

-server filename

Store server information in filename so that other processes can use the -client filename option to attach to this server process.

-silent

Suppresses the display of start-up messages.

-synclibs

Load all flibraries at startup.

-usage

Prints a summary of command line options without starting AVS/Express.

-vb "verbose flags"

Turn on individually-specified verbose flags such as functions, files, etc. For details, refer to $set_verbose and $unset_verbose in the Developer's Reference.

-vcp

Explicitly requests the VCP. This is useful with the filename option. Only necessary when the VCP is not presented by default.

-verbose

Displays the usual message stream and writes a message to stderr whenever: it defines the various XP_xxxPATH environment variables (both those set by the user and those internal environment variables that AVS/Express derives from XP_PATH); when a file is loaded; a library is loaded; an event is queued, or an AVS/Express method is executed.

-version

Prints a message showing the current AVS/Express version number. This option does not start AVS/Express.

-viz

For Developer Edition users, express -viz starts AVS/Express in the Visualization Edition configuration.

AVS Compatibility Kit Options
The following options are only of use to AVS5 users who are using the AVS Compatibility Kit. For more information please contact AVS support at support@avs.com or call your local office.

-accli

Start with the command line interpreter.

-aclibrary filename

Specify an AVS module library.

-acdata directory

Specify an AVS data directory.

-acmodule directory or filename

Specify AVS module directory or file.

-acnetdir directory

Specify AVS network directory.

-acnodmc

Disable AVS direct module directory or file.

-acnoshm

Disable AVS shared memory use.

-acparallel number

Set AVS parallel module execution limit.

-acpath directory

Specify main AVS directory.

-acseparate

Run AVS modules as separate processes.

-acshm

Enable the use of AVS shared memory.

-acversion

Display AVS version number.

Option	Description
-boss	Make this AVS/Express process the main process, overriding the OM_BOSS environment variable.
-client filename	Run this process as a client process using server information obtained using the -server filename option.
-compile	Compile all processes listed in the proc.v file.
-comp_proc process_name	Compile only the process specified.
-display hostname:display	(UNIX systems only) Specifies the X Window System display on which AVS/Express will display any X windows it generates. Overrides the DISPLAY environment variable, if set.
-exit	Exit after processing options (such as -compile).
filename	Loads the specified V file into the Applications object. You use this filename command line option to start an application that was saved using the Save Application command. By default, neither the Network Editor nor the VCP appears, but you can start either by combining this option with the -ne or -vcp command line options. AVS/Express does not assume nor append a file suffix of .v to the listed V file. By default, AVS/Express looks for the named V file in this sequence, using the first one it finds: The v subdirectories defined by the XP_PATH when an event is queued. The current directory (the directory from which you started AVS/Express.
-genlibs	Compile binary versions of all the libraries.
-gen_proc process_name	Generate source for the process specified.
-ne	Explicitly requests the Network Editor. This is useful with the filename option.
-nocxx	Do not use C++ to compile in this session.
-nohw	Disables all hardware renderers.
-none	Suppresses the Network Editor.
-novcp	Suppresses the VCP.
-offscreen	(UNIX systems only) When AVS/Express is started with the -offscreen flag, no visible windows will be created. For this mode to be useful, you will need to prepare a non-interactive application using normal Express faculties. The application might automatically loop over its input or the application might read commands from a script file or receive commands from another program via a network connection, but it is crucial that the application can run normally without any user input from a UI.
-path "dir1 dir2 ..."	Sets the value of the XP_PATH environment variable from the command line. This command line option overrides all other devices by which XP_PATH may be set. Note that you must specify all directories, including the main AVS/Express installation directory that would be represented by $XP_PATH<0> in V code. The list of directories must be enclosed in double quotes. The other directories may not exist yet; you may intend to create them during the session with the Network Editor's Project->Save menu sequence.
-project dir	Reads the avsenv file in the directory specified to obtain a value of XP_PATH. This overrides all other mechanisms of obtaining the XP_PATH value.
-server filename	Store server information in filename so that other processes can use the -client filename option to attach to this server process.
-silent	Suppresses the display of start-up messages.
-synclibs	Load all flibraries at startup.
-usage	Prints a summary of command line options without starting AVS/Express.
-vb "verbose flags"	Turn on individually-specified verbose flags such as functions, files, etc. For details, refer to $set_verbose and $unset_verbose in the Developer's Reference.
-vcp	Explicitly requests the VCP. This is useful with the filename option. Only necessary when the VCP is not presented by default.
-verbose	Displays the usual message stream and writes a message to stderr whenever: it defines the various XP_xxxPATH environment variables (both those set by the user and those internal environment variables that AVS/Express derives from XP_PATH); when a file is loaded; a library is loaded; an event is queued, or an AVS/Express method is executed.
-version	Prints a message showing the current AVS/Express version number. This option does not start AVS/Express.
-viz	For Developer Edition users, express -viz starts AVS/Express in the Visualization Edition configuration.
AVS Compatibility Kit Options The following options are only of use to AVS5 users who are using the AVS Compatibility Kit. For more information please contact AVS support at support@avs.com or call your local office.
-accli	Start with the command line interpreter.
-aclibrary filename	Specify an AVS module library.
-acdata directory	Specify an AVS data directory.
-acmodule directory or filename	Specify AVS module directory or file.
-acnetdir directory	Specify AVS network directory.
-acnodmc	Disable AVS direct module directory or file.
-acnoshm	Disable AVS shared memory use.
-acparallel number	Set AVS parallel module execution limit.
-acpath directory	Specify main AVS directory.
-acseparate	Run AVS modules as separate processes.
-acshm	Enable the use of AVS shared memory.
-acversion	Display AVS version number.

2.4 Exiting AVS/Express

You can exit AVS/Express from the Network Editor, the DataViewer, or the VCP.

Network Editor or DataViewer

To exit AVS/Express from the Network Editor or DataViewer:

Select the File->Exit pulldown command.

VCP

To exit AVS/Express from the VCP:

Enter the $quit command.

AVS/Express displays a dialog asking for confirmation that you want to exit. Select OK to exit or Cancel to continue to work.

Using AVS/Express

2 Starting and Exiting AVS/Express