TOC PREV NEXT INDEX

Installing AVS/Express


Chapter 3 Additional Configuration Procedures

This chapter provides expanded information from the prerequisite, installation, and licensing chapters. This chapter consists of:

3.1 Removing Fortran Dependencies

On many platforms, AVS/Express requires that the Fortran runtime libraries (that are typically provided as part of a platform's Fortran development environment) are installed in order to run with the Annotation and Graphing kit and the PrintViewer (a Graphics Display Kit object that provides hardcopy output functionality). The Fortran libraries are also required if you are developing runtime applications that include the PrintViewer or that use objects from the Annotation and Graphing kit.

To determine the AVS/Express Fortran dependencies on your system, refer to the platform-specific prerequisites section in Chapter 1, System Prerequisites Release 6.2.

If you do not need the Annotation and Graphing kit or the PrintViewer and you want to remove the dependencies on Fortran libraries that their presence imposes, you can either relink the installed version of AVS/Express without the Annotation and Graphing kit and PrintViewer, or you can create a project the does not contain the Annotation and Graphing kit and the PrintViewer.

The procedures below explain how to remove Fortran dependencies from AVS/Express by disabling the Annotation and Graphing Kit and the PrintViewer.

Removing Dependencies from the AVS/Express Executable

Follow the instructions below to relink the AVS/Express executable without the Annotation and Graphing kit and PrintViewer.

1. Edit the gd_ren.h file and comment the following lines. (The gd_ren.h file is in the <install-dir>/express/include/<machine type> directory.)
#define AG_KIT
#define PRT_RENDERER
2. Enter the commands below to relink the express executable.
In the commands below, <install-dir> is the directory in which you installed AVS/Express, and <machine type> is a string that corresponds to the platform on which you are running. Refer to the table on page 1-vi for a listing of machine types, or run the <install-dir>/express/bin/xp_mach script.
cd <install-dir>/express
mv .proj_lock .proj_lock.orig
bin/<machine type>/base -gen_proc express -exit
make -f express.mk relink
mv .proj_lock.orig .proj_lock

If at some later stage you need to use the Annotation and Graphing kit or PrintViewer (and the Fortran dependencies can be tolerated), you can reverse this process by uncommenting the #define AG_KIT and #define PRT_RENDERER lines in the gd_ren.h and relinking AVS/Express with the updated file.

Removing Dependencies from an AVS/Express Project

Follow the instructions in this section to create an express executable that is linked without the Annotation and Graphing kit libraries and the PrintViewer, and therefore, does not depend upon the Fortran development environment at run-time or when applications are built.

Note that in the commands that are listed below, <install-dir> is the directory in which you installed AVS/Express, and <machine type> is a string that corresponds to the platform on which you are running. Refer to the table on page 1-vi for a listing of machine types, or run the <install-dir>/express/bin/xp_mach script.

1. Start the VCP-only version of AVS/Express. (The VCP-only version runs without a Fortran development environment.)
<install-dir>/express/bin/<machine type>/base
2. Type the commands below at the VCP prompt to create a new AVS/Express project and then exit from the VCP-only version of AVS/Express.
OM(Root) -> $project_save_as noF77_proj
OM(Root) -> $quit
3. Copy the gd_ren.h header file into your new project directory.
cp <install-dir>/express/include/<machine type>/gd_ren.h ¬
noF77_proj/include/<machine type>/gd_ren.h
4. Edit the gd_ren.h file in the noF77_proj/include/<machine type> directory and comment the following lines.
#define AG_KIT
#define PRT_RENDERER
5. Type the commands below to change to the new project directory and relink the express process.
cd noF77_proj
<install-dir>/bin/<machine type>/base -comp_proc express -exit

As long as you want to run AVS/Express without the Fortran dependencies, you should ensure that you run the express executable from the noF77_proj directory.

noF77_proj/bin/<machine type>/express
3.2 Managing Swap Space

Your system should be configured with 64MB of swap space. If you start to run low on swap space, you will either receive error messages or AVS/Express will abort or hang.

For example, if you are running AVS/Express on the IBM RISC platform, the AIX operating system constantly monitors swap space utilization. If the system detects that it is running out of space, it determines which process is using the most swap space and then sends a warning message to that process. If the swap space situation does not improve, the system will eventually terminate the process using the most swap space. This termination should be accompanied by a "Process nnn killed: no swap space" error message. These error messages have numbers ranging from 917-031 through 917-064.

If you suspect that inadequate swap space is the reason AVS/Express is failing, you can restart AVS/Express and repeat the sequence of steps that led to the abort or hang while monitoring swap space consumption.

The commands below can be used to monitor swap space on Sun platforms. For other platforms, refer to the system administration documentation that was shipped with your system or contact your system administrator.

1. Enter the following command successively to monitor swap space usage.
/usr/sbin/swap -s
2. If you are running low on swap space, use the appropriate procedure below to increase swap space on your platform.
Note: If you are supporting diskless workstations on a central server, you may need to increase the swap space available to each client workstation that will run AVS/Express.
Increasing System Swap Space on Solaris 2.x Platforms
1. Locate a disk with 64MB of free space on it (or more, as you require).
2. Login as root or take on root privileges using the su command.
3. Create a file that will be used as extra swap space. The mkfile command should be in the /usr/sbin directory.
mkfile 64m <path and name of swap file>
4. Edit the /etc/vfstab file and add the following line to the end of the file.
<path and name of swap file> - - swap - no -
5. Enable the new swap file. The swap command should be in the /usr/sbin directory.
swap -a <path and name of swap file>
6. Confirm the swap space settings.
swap -l
Increasing System Swap Space on IBM RISC System/6000 Platforms

If you receive swap space warning messages or if AVS/Express terminates suddenly and your swap space allocations are marginal, you should increase the available swap space in 20MB increments using the smit utility. The instructions for the smit utility are available in the IBM documentation.

Increasing System Swap Space on HP Platforms

If the amount of swap space currently available on your system is inadequate, follow the procedure below to augment the existing swap space with file system swap space.

1. Login as root or take on root privileges using the su command.
2. Invoke the System Administration Manager by typing the following command.
sam
3. Select Disk and File Systems from the main menu.
4. Select the Swap entry.
5. Select Actions->Add File System Swap.
A new panel appears listing the "Unused Kbytes" and the "Total Kbytes," as well as the mount of point for the disks.
6. Edit the Maximum Swap field to increase the amount of file system swap in your system.
7. Click OK to execute your request.
Adjusting other System Parameters

In addition to increasing swap space, you may want to consider changing the following parameters from their default values, which were set by the HPUX kernel.

This is the maximum data segment size. A setting of 67108864 (64MB) is recommended.
This is the maximum stack segment size. A setting of 8388608 (8MB) is recommended.
This is the maximum number of swap chunk. A setting of 256 is recommended.

Follow the procedure below to changes these parameters.

1. Log in as root or take on root privileges using the su command.
2. Start the System Administration Manager by typing the following command.
SAM
3. Double-click the Kernel Configuration icon.
4. Double-click the Configurable Parameters icon.
5. Select Actions->Modify Configurable Parameters.

When you change these parameters, SAM rebuilds the HPUX kernel automatically.

3.3 Managing Shared Memory

On Sun platforms, AVS/Express uses shared memory to improve image display performance and execution speed. If, while working with AVS/Express (particularly while working with images), you receive numerous "shared memory" error messages in the window from which AVS/Express was started, it's possible that AVS/Express is requesting more than the system limit of shared memory, or it's possible that shared memory is not enabled on your system.

When your system has shared memory problems, AVS/Express begins making individual copies of images instead of using shared memory; this results in the use of substantially more real memory, swap space, and processing time.

Determining if Shared Memory is Enabled on Sun Platforms

Use one of the procedures below to determine if shared memory is enabled and, if it is enabled, the current usage.

Either:

Type the following command.
ipcs -a
This will display the amount of shared memory and number of shared memory segments in use. If you see a message, "Shared memory facility not in system...", then shared memory is either not enabled or has not been used by the system.

Or:

1. Issue the /usr/etc/showrev command to display the kernel architecture.
2. Determine the location of configuration file that corresponds to this kernel:
3. Search through the kernel configuration file for the shared memory setting (on Sun platforms this is the IPCSHMEM variable). A sample command is shown below.
more /usr/kvm/sys/<kernel architecture>/conf/generic | grep IPCSHMEM
If the IPCSHMEM option is commented, shared memory is not enabled.
Adjusting Shared Memory Parameters on SunOS 5.x Platforms

The default configuration on SunOS 5.x platforms is typically not appropriate forAVS/Express. For example,

If you are experiencing problems, you should verify that the shared memory parameters are properly configured for AVS/Express.

Follow the procedure below to enable shared memory or modify its parameters:

1. Login as root or take on root privileges using the su command.
2. Edit the /etc/system file.
3. Add or edit the following lines so that the values in your file match the values shown below.

set shmsys:shminfo_shmmax=67108864
set shmsys:shminfo_shmmin=1
set shmsys:shminfo_shmmni=100
set shmsys:shminfo_shmseg=64
set semsys:seminfo_semmns = 200
set semsys:seminfo_semmni = 70
set semsys:seminfo_semmsl = 10
4. Save the edited file.
5. Reboot the system to have the changes take effect.

Setting these parameters to values much larger than required appears to have no adverse effects on system performance, because resources are not allocated until they are requested.

3.4 Re-Linking AVS/Express

When you install AVS/Express, both static archive and dynamic shared versions of the libraries are supplied. With the exception of the IBM AIX and Digital Alpha AXP UNIX platforms, the AVS/Express executable on UNIX platforms references the dynamic shared libraries.

The sections below outline how to address the issues above as well as other relinking considerations.

Updating LD_LIBRARY_PATH and SHLIB_PATH

In order to ensure that AVS/Express can locate the shared libraries, you must update the LD_LIBRARY_PATH (on Sun and SGI systems) or the SHLIB_PATH (on HP systems) environment variable to include <install-dir>/express/lib/<machine>.

The commands below demonstrate how to update the LD_LIBRARY_PATH environment variable on a SunOS 4.1.4 platform. If you need assistance making the change on your platform, refer to the documentation that was shipped with your system, or contact your system administrator.

Note: If you have Advanced Visual Systems' UNIRAS or Gsharp products installed on your system, make sure <install-dir>/express/lib/<machine> precedes $UNIDIR/lib in the LD_LIBRARY_PATH (or SHLIB_PATH) variable.
If LD_LIBRARY_PATH is not set, type:
setenv LD_LIBRARY_PATH /u2/express/lib/sun
If LD_LIBRARY_PATH is already set, type:
setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH:/u2/express/lib/sun
Note: Be sure to precede the pathname with a colon.
If LD_LIBRARY_PATH is not set, type:
LD_LIBRARY_PATH=/u2/express/lib/sun
export LD_LIBRARY_PATH
If LD_LIBRARY_PATH is already set, type:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/u2/express/lib/sun
export LD_LIBRARY_PATH
Note: Be sure to precede the pathname with a colon.

If you want to suppress the output of warnings about incorrect or inconsistent shared library versions, set the environment variable XP_SUPPRESS_VERSION_WARNINGS.

Relinking AVS/Express Statically

If you need to relink your AVS/Express application statically, or if you want to avoid the need to set LD_LIBRARY_PATH, you will need to define the NO_DLLIBS environment variable.

To relink your AVS/Express application statically:

Define the environment variable NO_DLLIBS.
When you compile an application, the presence of this environment variable prevents the generation of shared libraries from the library archives and links the express executable statically.
3.5 Post-Installation System Information

The following sections describe a variety of issues that you will want to be aware of once you have installed AVS/Express. Some of the topics covered include swap space management, compiler issues, memory issues and runtime requirements.

Rendering Considerations
Enabling Double Buffering on Built-In Graphics Adapters

If you have an HP 9000 system with a built-in graphics adapter and you want to use hardware rendering, you will want to enable double buffering. This will give you access to full 8/8 double buffering using virtual memory.

Set the following environment variable to enable this feature:

setenv HP_VM_DOUBLE_BUFFER TRUE

You should be aware that there is a trade off between speed and memory when you enable this feature. Virtual memory rendering uses pure software algorithms. As a result, rendering can be significantly slower. Virtual memory rendering also consumes a part of memory that would otherwise be available to the application. You should carefully consider whether it is more effective to use Advanced Visual Systems's software renderer.

CRX and Built-In Graphics Adapter Problems

If you have an HP system and you are using the CRX graphics adapter, you might encounter problems with colormaps. In particular, colormap sharing can be a problem if hardware rendering is enabled and you are using a pseudocolor visual type. This affects the CRX graphics adapter and the built-in graphics adapters.

There are several steps that need to be taken in order to have AVS/Express, the HP X server, and PEX share the same colormap.

For Both Hardware and Software Rendering

By default, HP VUE will allocate about 40 colors from the default colormap that AVS/Express will try to share. If a message similar to the one shown below appears when AVS/Express starts, it means that AVS/Express was forced to use fewer than the optimal number of colors.

(PALvirt_alloc_cube): Color use degraded - using cube size of 5

In order to reduce HP VUE's color usage so AVS/Express can acquire all the colors that it would like, complete the procedure below.

1. Select Style Manager-> Color-> HPVue Color Use-> Low Color.
2. Click OK.
3. Log out and log in again.
4. Select Toolboxes->General->System Admin->Edit Resources.
You will see your Edit Resources interface.
5. Add the following line to your Edit Resource database.
*shadowPixmaps True
6. Exit from all clients (hpterms, for example)
7. Log out and log in again.
For Hardware Rendering Only

If you want all applications to, if possible, share the existing colormap instead of defining their own, you must set the SB_X_SHARED_CMAP environment variable.

1. Edit the /usr/lib/X11/vue/Vuelogin/Xconfig configuration file.
2. Insert the following line.
Vuelogin*environment: SB_X_SHARED_CMAP=true
3. Restart the X server so the variable will take effect.
The easiest way to restart the X server is to select Options -> Restart Server on the logon screen.
SX Video System

In order to run the SX system with the 24-bit TrueColor visual and enable AVS/Express accelerate hardware rendering on this adapter, you may have to run the system command sxconfig to configure sufficient memory for the SX video system.

1. Type man sxconfig to learn how to determine your system configuration and how to reserve memory for the video system.
2. Run /usr/kvm/sxconfig.
3. Reboot the system with the -r option.
UltraSPARC Creator 3D (FFB)

If you are using the UltraSPARC Creator 3D (also know as the FFB dbZ) frame buffer, it must be configured to use gamma-corrected visuals. Additionally, the gamma-corrected visuals must be first in the list of visuals supported by the frame buffer. If the device is not correctly configured, the rendering of geometries, images, and other graphics will not be gamma-corrected, and will therefore be too dark.

Note: You should not use the ffbconfig command when your window system is running. However, you can use the ffbconfig command with the -propt option at any time.
1. Type the command below to confirm that the device is correctly configured.
/usr/sbin/ffbconfig -propt
The current configuration will be displayed on your screen. (For information on what the current options mean, use the man command to display the ffbconfig man page.)
2. If the current configuration does not meet the requirements, ensure that your window system is not running, and then type the command below to change the settings to the recommended configuration.
ffbconfig -res 1280 -deflinear true -linearorder first
This configuration sets a 1280x1024x76 video mode, sets gamma-corrected visuals, and places gamma-corrected visuals first in the X11 visuals list.
If you are running the device in stereo mode, you will want to set a different -res option, but with the same -deflinear and -linearorder options. Refer to the output of the man ffbconfig command for more information.
Hardware Renderer Failure

If you are running on a GS or GT adapter, make sure that the $OPENWINHOME/bin/install_openwin script was run after OpenWindows 3.0 was installed. If this script was not run, hardware rendering may not work on your GS or GT adapter.

More detail can be found in the OpenWindows Version 3 for SunOS 4.1.x Installation and Startup Guide.

Setting X Resources with Edit Resources on HP Platforms

There are a variety of X resources that you may wish to set. The general procedure for setting X resources on HP systems is:

1. Click the arrow above the "toolbox" icon on the main HP VUE control panel at the bottom of the screen. This is the second icon from the right.
The "Toolboxes" menu pops up.
2. Click on the "General" toolbox.
The "General Toolbox" dialog pops up.
3. Double click on the "System_Admin" icon.
4. Double click on the "EditResources" icon.
An "EditResources" window, and possibly a "TextEditor" window, will appear, and a list of X resources will be displayed.
5. Add the X resource line(s) to the file.
6. Save the file.
7. Exit from the editor.
8. Close the General Toolbox.
9. Log out and log in again, or restart the workspace manager to get the changes to take effect.
Changing User Interface Kit Colors

You can control the colors used by the User Interface (UI) Kit. Follow the same procedure as above. When the "TextEditor" window appears, add the following lines to the resources.

Express*background: #b7b7b7
Express*foreground: black
Setting HyperHelp Resources

To set the X resources that control the HyperHelp online help interface, use the defaults found in $XP_ROOT/runtime/bristol/HyperHelp as a template.

3.6 Expanded Windows Installation Information

The installation procedures for Release 6.1 are the same for both the Developer Edition and the Visualization Edition of AVS/Express.

If you are using the Developer Edition and you want to use the Database Kit, you must link AVS/Express to the Database Kit after installation.

Note: The Database Kit is available in the AVS/Express Developer Edition only; it is not available in the Visualization Edition.
AVS/Express Runtime Directory

The AVS/Express runtime directory, <install-dir>\runtime\bin\<machine type>, contains utilities such as the FLEXlm's license utilities and DLLs that AVS/Express needs at runtime. The following are the files contained in the directory:

Windows NT / 2000 / XP

Under Windows NT / 2000 / XP, AVS/Express copies ctl3d32.dll into the System32 directory. It then modifies the system registry Path value if it cannot find <install-dir>\runtime\bin\<machine type> in the path.

HKEY_LOCAL_MACHINE
SYSTEM\CurrentControlSet\Control\Session Manager\Environment
Path: express\runtime\bin\pc;......

You can always, at a later time, configure the use of AVS/Express by including the runtime\bin\<machine type> directory in the path. Before doing so, you should be aware of how Windows resolves DLL loading: When loading a DLL, Windows searches the system directory first for that DLL, and then searches for the Path value in the environment. This is important to remember when you have different versions of the same-named DLL in different directories.

Uninstalling AVS/Express

On Windows platforms:

Click the Uninstall Express icon in the AVS Express folder.

On UNIX platforms:

Type uninstall -r.
3.7 Expanded UNIX Installation Information

This section includes information regarding moving AVS/Express, remote installations, and expanded mounting instructions.

Copying AVS/Express to its Permanent Home (UNIX)

In most cases, you have read AVS/Express into the file directory that is to be its permanent home. In some cases, you may need to copy the entire AVS/Express file directory across the network to its permanent home. This should be necessary only when the following are true:

If you do not need to copy AVS/Express, skip this part and turn to Licensing AVS/Express.

Remote Installations

The installation script assumes that you are logged into the system that is connected to the I/O device (that is, the CD-ROM drive). The script makes no provision for remote data reads across the network. If you are installing AVS/Express over a network, you should seek the assistance of your system administrator or network administrator.

At a very high level, you will need to:

Expanded Instructions for Mounting the Media (UNIX)

In this step, you mount the media (CD-ROM) and obtain the install.xp script. The install.xp script reads the rest of AVS/Express off the media.

Use the following procedure to mount the media and get install.xp:

1. Using the login or rlogin command, log in to the system that is connected to the I/O device.
You may need to be root in order to create the directory where the CD-ROM will be mounted (refer to Mounting the CD-ROM Device).
2. Using the df, df -k, or bdf command (depending on the system you are on), check the disk space on the disk partition in which you want to install AVS/Express.
AVS/Express requires anywhere from 100MB to 200MB of free storage; the precise amount is dependent on the platform.
3. Determine where you want to install AVS/Express and change to that directory. The following example identifies /u2 as the installation directory:
cd /u2
In a later step, you will read the install.xp installation script into this directory (if you are installing from a tape).
Note: When you run install.xp, later in this installation process, it creates an express directory in the installation directory that you specify. By default, the installation directory is the directory from which you started install.xp. For example, if you run install.xp from the directory /u2, the default installation directory is /u2, and install.xp creates the directory /u2/express. The installation directory, /u2 in this example, is referred to as <install-dir> throughout the examples in this book.
4. Before you install AVS/Express Release 6.1, move any existing express directories that you need to preserve, by using the following command:
mv /u2/express /u2/express.old
Mounting the CD-ROM Device
1. Insert the CD into the CD-ROM drive.
2. If necessary, create a directory where the CD-ROM will be mounted.
mkdir /cdrom
3. As root, mount the CD-ROM device onto the /cdrom directory. All mount commands take a CD-ROM device name, the mount directory (/cdrom or your name) and a set of options that vary from platform to platform. Consult your system administrator if you do not know the CD-ROM device name for your system.
4. The install.xp script should now exist in the /cdrom, /mnt, /CDROM, or /cdrom/avs_xp directory. Verify this with the ls -l /cdrom (or correct device) command.
System administrators can examine the install.xp script before using it to verify that it is acceptable to their system's administrative restrictions.

Once the CD is mounted, you no longer need to be root. However, you may need to become root again to unmount the CD at the end of the installation.

TOC PREV NEXT INDEX