Installing AVS/Express

Chapter 2 Installing and Licensing AVS/Express

This chapter provides instructions for installing AVS/Express Release 7.1. It includes the following sections:

Each of these sections contains detailed steps for installing AVS/Express. You should read the sections in order and complete all of the indicated tasks in the order presented to ensure a successful installation.

IMPORTANT: If you have not already read Chapter 1, System Prerequisites Release 7.1, and met all of the listed prerequisites for your platform, you must do so before you continue with the procedures in this chapter.

2.1 Installing AVS/Express

AVS/Express is available on compact disk (CD-ROM) or through download. The CD-ROM contains versions of AVS/Express for multiple hardware platforms. If you did not receive the CD and wish to, you should contact Advanced Visual Systems immediately. (This manual uses the terms CD and CD-ROM interchangeably to describe a compact disk.)

The installation procedure can be summarized in six steps.

Install any other software listed in Chapter 1, System Prerequisites Release 7.1 as required for running AVS/Express on your platform.
Mount the media.
Run the installation script.
Install or update the AVS/Express license.
If necessary, link AVS/Express with the Database Kit.
Set the variables that are necessary for finding AVS/Express when you start the application.

These steps are described in the sections that follow.

Mounting the Media

Before you mount the media, you should know where you want to install AVS/Express. By default, the installation program creates an express directory and installs AVS/Express in it. However, the installation program allows you to select a different installation directory.

Choose or create an installation directory now, and then write the full path and directory name in the table below for future reference. In the steps that follow, this install or home directory will be referred to as install-dir.

On some systems, the CD-ROM is automatically mounted; on others you need to use the mount command. Similarly, some systems require that you create a mount directory, whereas others have a /cdrom directory.

At this point, you should decide whether you already have a /cdrom directory, whether you want to use an existing directory, or whether you want to create a directory for mounting CD-ROMs. In any case, write the mount directory name in the table below for future reference. The directory that you specify will be referred to as /cdrom in all of the instructions that follow.

Follow the procedure below to mount the CD-ROM.

1. Insert the AVS/Express CD-ROM into the CD-ROM drive.

2. If necessary, mount the CD-ROM.

The mount command varies from platform to platform, and the device number for the CD-ROM drive depends on its SCSI ID. The device numbers shown below are sample numbers, so you should contact your system administrator to obtain the correct device number for your system.

Table 0-11


Operating System	Sample Mount Command
Windows	No mount command is necessary.
Mac OS X	No mount command is necessary.
HP-UX	mount -F cdfs -o cdcase /dev/device /cdrom
IRIX	The default IRIX configuration uses the mediad system daemon to automatically mount the CD-ROM as /CDROM. If the mediad daemon is not running, mount the CD-ROM as shown below: mount -r -t iso9660 /dev/scsi/sc0d4l0 /CDROM
Linux	This automatically mount the CD-ROM as /CDROM. If it does not, mount the CD-ROM as shown below: mount /mnt /CDROM
Solaris	mount -r -t hsfs /dev/sr0 /cdrom

Running the Installation Script

This section describes how to read the AVS/Express software from the media and execute the installation program.

UNIX Platforms

1. Run the install.xp script.

Note: Depending on your system platform, the directory, file and script names may appear as all uppercase or all lowercase. If you notice a case difference, make the necessary adjustment when you enter commands.Some differences are highlighted in the table below.

Table 0-12


Platform	Command
SGI with mediad	/CDROM/install.xp
Solaris with vold	/cdrom/avs_xp/install.xp

2. The installation program then leads you through the installation process.

If a "Permission denied" error message is displayed while you are running the installation script, the permissions need to be modified before you attempt to run the script again. Use the chmod a+x install.xp command to modify the permissions. Since you can't modify a file on the CDROM you will need to make a local copy of the install script first.

On Unix platforms, when the installation is finished, you may wish to rename the install directory. Such renaming is helpful if you wish to maintain multiple versions of AVS/Express installed on the same machine.

Relinking Errors on some UNIX Platforms

When AVS/Express is installed, it is dynamically linked with many of its own shared libraries. In some cases additional libraries are required that may not be installed on your system. Advanced Visual Systems has included the libraries that might be missing in the directory <install-dir>/lib/<machine>/missing.

If you find the libraries required by the express executable are not available on your system, change the LD_LIBRARY_PATH variable to include the <install-dir>/lib/<machine>/missing directory as in the following example (assumes Solaris):

setenv LD_LIBRARY_PATH <install-dir>/lib/s8:<install-dir>/lib/s8/missing:/usr/openwin/lib

For more details, see the Installing AVS/Express manual.

Installing on Linux

To install AVS/Express on a Linux system:

1. Review the prerequisites described in Linux Prerequisites of this document.

2. Use the standard Linux commands to mount the AVS/Express CD.

3. Follow the instructions in the UNIX Installation section of the Installing AVS/Express manual to install AVS/Express from the tar file on the CD.

4. Set the LD_LIBRARY_PATH to include:

the Express runtime shared library path
the Mesa OpenGL shared library path (Not necessary if using OpenGL bundled with X server) , and
the Motif shared library path (Not necessary if libraries installed with other X libraries)

5. Follow the licensing procedure outlined in Quick start Licensing AVS/Express 7.1 for all platforms with a local license of this document.

To use Viz/Express, start AVS/Express with the -viz command line option.

Windows Platforms

You must have administrator privileges in order to install AVS/Express. This is because the installation program modifies the system PATH environment variable in the Windows Registry.

The complete procedure for installing AVS/Express consists of the following steps:

1. Bring up the Run dialog box.

2. Click Start and select Run... from the options menu.

3. You may run the setup.exe file by typing the following in the Run dialog box. (The example commands below assume that your CD-ROM drive is the D drive. If your CD-ROM is installed as a different drive, make the appropriate substitution in the command.)

For Intel systems:

D:\windows\setup.exe

Or you may execute the setup.exe file using the Windows Explorer to find the file.
The installation program leads you through the installation process and takes about 2 minutes on an average system.

2.2 Licensing AVS/Express

AVS/Express Release 7.1 uses a new unified licensing system. Previous releases of AVS/Express (5.x and 6.x) used two different sytems depending on the platform. AVS/Express on Linux and new platforms used a simple node locking system which was called the "simplified licensing scheme" in the release notes of 6.x. AVS/Express on Windows and the older Unix platforms used a system based on FLEXlm. All users of AVS/Express pre-7.0 will need to install new licenses. Permanent licenses must be requested from AVS support. You may request a temporary license at

http://help.avs.com

Note: Many of the examples in this chapter are based on the UNIX operating system. Wherever necessary, Windows-based information has been included; however, if you are running on a Windows platform, you should note that the paths in some of the examples may not match your system.

Licensing models

The available licensing models are summarized by the following table. The axes (variables) of the table are identified by 2 questions:

Is the number of simultaneous users counted and limited Is the client machine limited to one, mulitple or any host

The combination of not checking of simultaneous users but limited to a single host are typlically called node locked licenses. The combination of limiting the number of users but not restricting the host machine are typically called floating licesnes. However, the table shows how different combinations are possible. A third important licensing attribute is whether or not there is an expiration date. A license with no checking of simultaneous users and also not host limited can be combined with an expireation date for a demo license

.

use-limited

not use limited

one host

requires license server
compute server license

does not require license server node locked license for workstation

multiple hosts

requires license server
floating license

does not require license server site license

any host

requires license server
floating license

does not require license server, no restrictions, combine with an expiration date for a demo license

	use-limited	not use limited
one host	requires license server compute server license	does not require license server node locked license for workstation
multiple hosts	requires license server floating license	does not require license server site license
any host	requires license server floating license	does not require license server, no restrictions, combine with an expiration date for a demo license

Quick start Licensing AVS/Express 7.1 for all platforms with a local license

To license AVS/Express, you should create a small text file that contains your license key on a single line. Usually the file is named license.dat, although this can be changed if you use the XP_LICENSE_FILE variable as described below. Make sure the file is saved as plain text without any word processing formatting information. It is possible to put the license keys for mutiple machines in a single file - just put one license key per line. Lines that start with '#' are considered comments and will be skipped.You should set the XP_LICENSE_FILE environment variable to tell AVS/Express where to look for the license.dat file. This variable must specify the full path and filename of the license file, for example:

Using the tcsh shell:

setenv XP_LICENSE_FILE /usr/licenses/license.dat

Using the bash shell:

export XP_LICENSE_FILE=/usr/licenses/license.dat

If XP_LICENSE_FILE is not defined, AVS/Express searches for a file named license.dat in $XP_ROOT (if defined). AVS/Express will also check for the license file in the Express install directory.

If Express is having problems finding your license file, set the environment variable XP_LICENSE_DEBUG

Using the tcsh shell:

setenv XP_LICENSE_DEBUG 1

Using the bash shell:

export XP_LICENSE_DEBUG=1

License keys can be obtained by contacting AVS customer support.

Running AVS/Express Visualization Edition

AVS/Express Visualization Edition users should ensure that the XP_FEATURE environment variable is set to VIZ_EXPRESS before using the licdiag utility and before starting AVS/Express.

For UNIX ():

Using the tcsh shell:

setenv XP_FEATURE VIZ_EXPRESS

Using the bash shell:

export XP_FEATURE=VIZ

For Windows:

1. Select Start->Settings->Control Panel.

2. Double-click on the System icon.

3. Go to the Environment tab.

4. Change or create the XP_FEATURE environment variable and set it to VIZ_EXPRESS.

Requesting and Installing a New License File

You must complete the following procedure to create a new license file.

If you have not yet completed a license request form, do so now.

The License Request Form was included with your media and documentation, but it is also available on the Advanced Visual Systems web page, at:

http://help.avs.com/licensing/.

The License works on the client/server model, so in order to complete the License Request Form, you must know where the licensing server processes will run (the host machine), whether you purchased a node-locked or floating license, and you will need to know which AVS/Express edition (Developer or Visualization) you are licensing. You will need to supply information about your machine's identity. A simple way to get this information is to attempt to run AVS/Express. The resulting error message will list the identifying information that you need to supply in order to request a license. This is especially helpful in cases where a machine has more than one internet addres or more than one network interface card. The message will show which addresses AVS/Express is using.

The following shows an example of the message:

             Sorry, no license can be issued for EXPRESS at this time.          
             Call AVS Inc. Customer Support for more information. 

             Be prepared to tell them the following information                 
             about your machine: 

             Internet address: 192.138.235.126                                 
             Volume Serial Number: c04b-3482

Advanced Visual Systems will send the license information to you. The information that you receive will look similar to the information shown below.

The license file is an ordinary text file that contains lines that look like the following (all on one line).

AVS LICVER=1 PRODUCT=EXPRESS DATE=30-dec-2004 HOSTID:192.253.36.22 
CUSTID=AVSInc PASSWD:4c8e057c282cab61d7d4324d9b4105c9

A single file can contain multiple licenses. Blank lines and comment lines starting with '#' are skipped. If you are able to share files over your local network, you can manage multiple node locked licenses by putting them all in a single shared license file. The following example shows 2 node locked licenses in a single file (both license lines on one line).

#

# Workstation 1

AVS LICVER=1 PRODUCT=EXPRESS DATE=30-dec-2005 HOSTID=192.253.36.22 
CUSTID=AVSInc PASSWD=4c8e057c282cab61d7d4324d9b4105c9

#

# Workstation 2

AVS LICVER=1 PRODUCT=EXPRESS DATE=30-dec-2005 HOSTID=192.253.36.23 
CUSTID=AVSInc PASSWD=5b8e057c282cab61d7d4324d9b4105c9

The following example shows a use-limited license that allows 5 concurrent copies of AVS/Express to be active at any one time. The presense of the keyword "LIMIT" distinguishes the two types of licenses. This particular example shows a hostid that allows any machine on the local network to run AVS/Express. This corresponds to what is commonly called a floating license.

AVS LICVER=1 PRODUCT=EXPRESS LIMIT:5 DATE=30-dec-2004 
HOSTID:192.253.36.00/24 CUSTID=AVSInc 
PASSWD:4c8e057c282cab61d7d4324d9b4105c9

Use-limited licenses must be under the control of a license server. They cannot be read directly by AVS/Express. For more information on the license see the format section in Appendix A.

Instructions to install the license

Installing a unlimited-use (node locked) license.

AVS/Express can read its licenses either from a local file or from a file in a remote shared directory. By convention, this file is usually called license.dat, but you can use any name you want. Thus installing a license means creating a license file and pointing AVS/Express at the license file. The license file can be created with any text editor, but if you use a word processor program make sure to save the file as plain text without any markup. In other words, don't create a .doc file or .rtf file, etc. It does not matter to AVS/Express what the file extension is, but it can be confusing to use a extension also used by common word processor programs. On Windows, using the notepad editor and naming the file license.txt is a simple way to insure that the file is plain text.

When AVS/Express starts up, it determines the license filename by looking at the following (in order).

The value of the XP_LICENSE_FILE environment variable (if set).
XP_ROOT/license.dat. (If XP_ROOT is set).
"license.dat" in the root of the install directory

When setting XP_LICENSE_FILE make sure to use the complete pathname including its directory. The following shows some examples:

(Unix tcsh shell syntax)

setenv XP_LICENSE_FILE /home/smith/express_license.dat

(Unix bash shell syntax)

export XP_LICENSE_FILE=/home/smith/express_license.dat

(Windows command shell syntax)

set XP_LICENSE_FILE=C:\Documents and Settings\smith\Application Data\express\license.dat

To help troubleshoot problems, set the environment variable XP_LICENSE_DEBUG to any non-null value.

setenv XP_LICENSE_DEBUG 1 (Unix tcsh shell)

export XP_LICENSE_DEBUG=1 (Unix bash shell)

set XP_LICENSE_DEBUG=1 (Windows command shell)

Installing a use-limited (floating) license.

Instructions on how to run the license server are found in a later section. On the client machine (the machine running AVS/Express) all you have to do is set the environment variable XP_LICENSE_SERVER before AVS/Express is started. It has the form hostname:port.

setenv XP_LICENSE_SERVER lserv.avs.com:33333 (Unix tcsh shell)

export XP_LICENSE_SERVER=lserv.avs.com:33333 (Unix bash shell)

set XP_LICENSE_SERVER=lserv.avs.com:33333 (Windows command shell)

A different port may be used, but only if the license server has been configured to use a different port. 33333 is the default. If you use the default port, it can be omitted from the environment variable.

setenv XP_LICENSE_SERVER lserv.avs.com  (Unix tcsh shell)

export XP_LICENSE_SERVER=lserv.avs.com  (Unix bash shell)

set XP_LICENSE_SERVER=lserv.avs.com   (Windows command shell)

To help troubleshoot problems, set the environment variable XP_LICENSE_DEBUG to any non-null value as described in the previous section.

The license server

Licenses that are use-limited require the use of a license server. The AVS license server is a fairly small Java-based program. It can be run on any machine that supports Java. The license server software is totally independent of AVS/Express. AVS/Express does not have to be installed on the machine hosting the license server. However, the machines that are used to run AVS/Express must be able to make a TCP connection to the machine running the license server. This may present an issue if the license server machine and the AVS/Express client machine are separated by a firewall.

For more information about the license server please see Appendix A.

Upgrading an Existing AVS/Express License

If you already have an AVS/Express license, but you need to upgrade or update your license information, complete the procedure below.

1. If you have not yet completed a Change of License request form, do so now.

The Change of License request form is available on the Advanced Visual Systems web page, at http://help.avs.com/licensing/.

2. Upon receiving the license-related information, replace or modify the information in your existing license.dat file with the new information.

2.3 Linking AVS/Express to the Database Kit

Read this section only if you want to link AVS/Express with the Database Kit. If you are not using the Database Kit, skip this section and go to Starting AVS/Express.

Two files are of particular interest when linking AVS/Express to the Database kit and to the database specific libraries; the express.exe and the config.h files.

express.exe is the AVS/Express executable. When AVS/Express is installed, this executable is not linked to the database libraries. In order to use the Database kit, you need to use a batch file or a script file to produce an express.exe file that is linked to the database libraries.
install.sh is the script file that updates your express.exe file if you are running on a UNIX platform.
go_ora.bat, go_odbc.bat go_db.bat, go_ndb.bat are the batch files that update your express.exe file if you are running on a Windows platform.
config.h contains configuration information. When you run a batch file or the script file, the config.h file is updated to include database-specific configuration information.

Linking the Database Libraries

CAUTION: When you run any of the batch files or the install.sh script, a new version of express.exe overwrites the existing version. If you want to keep the current version for later use (for example, to revert to it after testing the Database Kit), you must save a copy of the current express.exe by renaming it.

Follow the instructions below to modify your express.exe file so that it is linked with the appropriate database-specific libraries. The necessary files and their locations are identified in the table below.

Table 0-13


File Name	UNIX Directory	Windows Directory
express.exe	<install-dir>/express	<install-dir>\bin\<machine type>
config.h	<install-dir>\include\<machine type>	<install-dir>\include\<machine type>
install.sh	<install-dir>/express/dbkit	Not applicable.
go_ora.bat, go_odbc.bat go_db.bat, go_ndb.bat	Not applicable.	<install-dir>

On UNIX Platforms

1. Log in as root.

2. Set the environment variable XP_ROOT to the <install-dir>/express directory.

3. Type the following command:

$XP_ROOT/db_kit/install.sh

4. Respond to the prompts that are displayed by the script.

When the script completes, your AVS/Express executable will be linked to the database libraries and you will be ready to run AVS/Express with the Database Kit.

On Windows Platforms

Invoke the appropriate batch file.

Table 0-14


Invoke this batch file...	To link express.exe to...
go_ora.bat	Oracle database libraries
go_odbc.bat	ODBC database libraries
go_db.bat	all of the databases libraries listed above
go_ndb.bat	none of the database libraries

When the batch job completes, your AVS/Express executable will be linked to the database libraries and you will be ready to run AVS/Express with the Database Kit.

Linking a Non-supported Database

If you want to link AVS/Express with a non-certified version of a database, you need to modify the corresponding database link line in the <install-dir>/express/include/<machine type>/machinc.mk makefile. This makefile links the database version specified in the machinc.mk makefile to the AVS/Express executable when you install the Database Kit.

2.4 Starting AVS/Express

Use the appropriate platform-specific procedure below to start AVS/Express.

Note: AVS/Express Visualization Edition users must set the following environment variable before using the licdiag utility and before starting AVS/Express.

setenv XP_FEATURE EXPRESS_VIZ

UNIX Platforms

1. Add <install-dir>/express/bin/<machine type> to your search path.

The AVS/Express executable resides in the <install-dir>/express/bin/<machine type> directory.
<machine type> is a string that corresponds to the name of the platform you are running on.

2. Launch AVS/Express using either the express command or the xp shell script (for the Developer Edition) or use the vxp shell script to start the Visualization Developer Edition.

For the Developer edition...

The express command starts AVS/Express, but it does not set the library path or the XP_FEATURE environment variables.
The xp shell script, sets the shared library path environment variables, sets the XP_FEATURE environment variable for the licensing of your runtime applications, and calls the express executable.

Note: If the license.dat file is stored somewhere other than in the default directory, you must explicitly tell AVS/Express where to find the license.dat file. Depending on your platform, the default location is <install-dir>/license.dat.

Windows Platforms

Either:

Select Start-Programs->AVS Express->AVS Express (Dev Edition)
or Start-Programs->AVS Express->AVS Express (Viz Edition).

Or:

1. Open a command shell.

2. Change to the AVS/Express directory (most likely C:\Express).

3. Type start bin\<machine type>\express.

Troubleshooting Errors while Starting AVS/Express

If your system is not properly configured, it is possible that you could receive error messages when you first start AVS/Express. These problems could be a result of an improperly set environment variable, a license server problem, or some other configuration problem. Some of the more commonly errors are described below; whenever possible, a remedy for the problem is also provided.

"Cannot find .v file" Messages

If, while AVS/Express is starting, you notice messages stating "cannot find V files", in particular, the sys.v file, it is possible that the XP_PATH variable was not set correctly.

Typically, you do not need to define the XP_PATH environment variable to run AVS/Express; it is automatically determined and set based on your directory file search path. However, if the current directory (.) is not in your path, AVS/Express can fail to correctly set XP_PATH.

Follow this procedure to solve this problem.

1. Type the following command to determine the value of XP_PATH.

express -version

2. If the path information is incorrect, either explicitly set an XP_PATH environment variable or use the path option when starting AVS/Express as shown below.

express -path "/<path>/express"

The quotation marks around the directory specification are required.