Appendix A
Environment Variables
About Environment Variables
Environment variables can be used to control how software works. SOFTIMAGE|XSI uses environment variables for several purposes, for example, to define the location of various required files.
How XSI Sets Environment Variables
XSI sets the variables that it needs in its environment script: the setenv.bat file on Windows or the .xsi_3.0 file on Linux and IRIX. This file is run or sourced before launching the interactive XSI application, the command-line XSI application, or the mental ray renderer.
The environment script is created when you install XSI. It usually does not require modification, but advanced users can modify it, for example, if they need to accommodate specific aspects of their network.
Because the variables are all set in the environment script, any modifications need to be made in only this one file. In addition, because the environment script is run only before launching XSI, any variable settings will not interfere with other applications or even with other versions of XSI on the same computer.
Tools for Setting Environment Variables
To modify the variables set in the environment script, you can use the User Tools utility. For more information about User Tools, see Modifying Configuration Files with User Tools.
You can also modify the environment script with any text editor.
Setting and Using Environment Variables
This section describes how to set, unset, use, and echo environment variables. The procedures are different on Windows as compared to Linux and IRIX.
On Windows
You can define environment variables on Windows using the set command as described in the sections that follow.
To permanently change environment variables on Windows
When you modify the setenv.bat file, the modifications are used each time you launch the interactive XSI application, the command-line XSI application, or the mental ray renderer.
- Use the User Tools utility or a text editor to modify the setenv.bat file in the Application\bin subfolder of the directory where XSI is installed.
- For information about the syntax of the
set command, see the sections that follow.
|
|
You can also set environment variables for a user profile using Control Panel. These changes will affect the environment for all applications run by that user.
See your Windows documentation for more information.
|
To temporarily change environment variables on Windows
When you modify environment variables in a command prompt window, the modifications affect that specific window and any programs launched from it.
- Open a command prompt window.
For example, to open a command prompt with the default XSI environment already set, choose Programs > Softimage Products > SOFTIMAGE XSI X.X > Command Prompt from the Windows Start menu.
- Modify the environment variables as needed.
- For information about the syntax of the
set command, see the sections that follow.
|
|
If you often need to make the same modifications, store your commands in a batch file and run it.
|
- Start an application in the modified environment.
For example to launch the interactive XSI program from the command prompt, enter the following:
Setting Environment Variables on Windows
To create or modify an environment variable, use the set command. For example, to set the variable SI_LOCATION to the value C:\Softimage\SOFT3D_3.9.2:
Do not enclose the value in quotes, unless you want the quotes to be part of the value. Note that variable names are not case-sensitive on Windows.
Unsetting Environment Variables on Windows
To unset an environment variable, set it to the empty string. For example:
Using Environment Variables on Windows
To use the current value of an environment variable in a command, enclose the variable name in percentage signs (%). For example, to add the directory C:\MyDir to the beginning of the search path:
Echoing Environment Variables on Windows
To echo the current value of an environment variable to the command prompt window, you can use the echo command and enclose the variable name in percentage signs. For example, to see the current search path:
Alternatively, you can use the set command without using the equality sign. For example:
Instead of specifying the full variable name, you can use the set command with the initial characters of the name to echo all variables that begin with that string.
To see the current values of all environment variables, enter the following:
On Linux and IRIX
You can define environment variables on Linux and IRIX using setenv and unsetenv as described in the sections that follow.
To permanently change environment variables on Linux and IRIX
You can change environment variables permanently in the .xsi_3.0 file. Make sure that this file is sourced before launching the interactive XSI application, the command-line XSI application, or the mental ray renderer.
To temporarily change environment variables on Linux and IRIX
When you modify environment variables in an xterm or shell window, the modifications affect that specific window and any programs launched from it.
- Open an xterm or shell window.
- If desired, set the default XSI environment as follows:
- Modify the environment variables as needed.
- For information about the syntax of the
setenv and unsetenv commands, see the sections that follow.
|
|
If you often need to make the same modifications, store your commands in a shell script and source it.
|
- Start an application in the modified environment. For example to launch the interactive XSI program, enter the following:
Setting Environment Variables on Linux and IRIX
To create or modify an environment variable, use the setenv command. For example, to set the variable SI_LOCATION to the value usr/Softimage/SOFT3D_3.9.2:
Character strings must be enclosed in double quotes. Remember that variable names are case-sensitive on Linux and IRIX.
Unsetting Environment Variables on Linux and IRIX
To unset an environment variable, use the unsetenv command. For example:
Using Environment Variables on Linux and IRIX
To use the current value of an environment variable in a command, prefix the variable name with a dollar sign ($). For example, to add the directory ~/MyDir to the beginning of the search path:
Echoing Environment Variables on Linux and IRIX
To echo the current value of an environment variable to the shell or xterm window, use the echo command and prefix the variable name with a dollar sign ($). For example, to see the current search path:
To echo all environment variables, use:
Running the Environment Script on Linux and IRIX
The .xsi_3.0 environment script uses the C shell syntax. The C shell is the default command interpreter on IRIX and is common on Linux as well.
If you are using a different command interpreter as your default, you can switch to a C shell temporarily to run the environment script. You can also change your default command interpreter permanently.
To run the C shell temporarily on either Linux or IRIX
Start a C shell in the current shell or xterm window by doing either one of the following:
- To start a standard C shell, run:
- To start a Tab C shell, run:
To set the C shell as default on Linux
- Log in as root.
- Run the /sbin/linuxconf configuration utility.
- Go to User Accounts > Normal > User Accounts. From here you can choose among the various users and adjust different parameters.
- Change the command interpreter to either csh or tcsh.
To set the C shell as default on IRIX
The C shell is the default command interpreter on IRIX. You need to perform this procedure only if you have previously changed the default.
- Log in as root.
- Run the /usr/sysadm/bin/sysmgr configuration utility.
- Go to Security and Access Control > User Manager > Modify a User Account. From here you can choose among the various users and adjust different parameters.
- Change the default shell program to either csh or tcsh.
Environment Variable Reference
This section describes the different types of environment variables used by XSI and provides a table giving a detailed description of each variable set in setenv.bat on Windows and .xsi_3.0 on Linux and IRIX.
Types of Environment Variables
Many different software applications define environment variables that affect how they run. In addition to XSI-specific environment variables, XSI uses variables that control other software.
In the list of environment variables that follows, the type of each variable is indicated. Here’s a summary of the different types of variable used by XSI and the scope of what they affect:
- XSI variables affect how XSI runs.
- Softimage variables affect XSI as well as other Softimage programs, including SOFTIMAGE|3D.
- mental ray variables affect the mental ray rendering software.
- SPM variables affect the SPM licensing software.
- MainWin variables affect the MainWin shared libraries on Linux and IRIX.
- System variables affect the operating system and all programs running on it.
XSI isolates all the variables it needs in setenv.bat on Windows and .xsi_3.0 on Linux and IRIX and uses these files to set its local environment before running the main program. As a result, the modified variables should not affect any other software on your computer.
However, if you modify your system (for example, by setting variables in .cshrc on Linux or IRIX, or in Control Panel on Windows), then other software could be affected.
Table of Environment Variables
The table that follows describes the XSI, Softimage, mental ray, SPM, MainWin, and system environment variables used by SOFTIMAGE|XSI.
|
Environment variable
|
Description
|
Platforms
|
Type
|
|
HOME
|
The user’s home directory.
This must be a unique location for each specific user. XSI creates a /Softimage/XSI_X.X folder in this directory for storing custom scripts, toolbars, preferences, presets, and other personal XSI files in various subfolders.
On Linux and IRIX, HOME is a system variable and should already be set to the home directory of the current user.
We do not recommend that you change it.
|
Linux, IRIX
|
System
|
|
INCLUDE
|
Location of header files for the XSI SDK.
The default location is the include subfolder of the directory specified by XSISDK_ROOT.
|
Linux, IRIX
|
XSI
|
|
LANG
|
Sets the environment language for XSI on whatever Linux version you are using.
The default value is C which sets the language to English.
This variable sets the default for the shell from where you source the XSI environment script. In the case where you run the xsi script (lowercase xsi) directly from Application/bin, the shell is not affected by the language settings.
If you are using an International version of Linux, the International settings will apply to everything else on your system.
Do not modify this value.
|
Linux
|
System
|
|
LC_NUMERIC
|
Sets the numeric separator.
The default value is C which sets the numeric separator to “.” as defined in the English language environment.
This variable sets the default for the shell from where you source the XSI environment script. In the case where you run the xsi script (lowercase xsi) directly from Application/bin, the shell is not affected by the language settings.
If you are using an International version of Linux, the International settings will apply to everything else on your system.
Do not modify this value.
|
Linux
|
System
|
|
LOGNAME
|
The current user name on Linux and IRIX.
If this variable is not set by the system, XSI sets it to the string returned by whoami.
|
Linux, IRIX
|
System
|
|
MI_RAY_HOSTSFILE
|
The location and name of the rayhosts file for distributed rendering. If no file name is explicitly specified, XSI searches for .ray3hosts, then .rayhosts.
If you are upgrading from SOFTIMAGE|3D, you can set MI_RAY_HOSTSFILE to point to your existing .rayhosts file.
By default, MI_RAY_HOSTSFILE is set to a version-specific subfolder of the XSI_USERROOT directory. This allows you to have different rayhosts files for different versions of XSI without any interference.
|
All
|
XSI
|
|
MI_RAY3_SERVICE
|
The IP service used by mental ray 3.x to contact slaves on other machines for network rendering.
The default is:
|
All
|
mental ray
|
|
MI_ROOT
|
The location of mental ray configuration files such as ray3rc.
The default location is the Application/rsrc subfolder of the directory specified by SI_HOME.
|
All
|
mental ray
|
|
MWHOME
|
The location of MainWin runtime and configuration files.
The default location is the Application/mainwin/mw subfolder of the directory specified by SI_HOME.
|
Linux, IRIX
|
MainWin
|
|
MWLIGHT_MEMORY_CHECKS
|
Increases the speed on non-Windows platforms.
The default is TRUE.
|
Linux, IRIX
|
MainWin
|
|
MWREGISTRY
|
The path and file name of the MainWin registry file required by XSI on Linux and IRIX.
The default depends on the computer name and is located in the Softimage subdirectory of your home directory:
$SI_USERHOME/registry.xsi_3.0${hostname}
|
Linux, IRIX
|
MainWin
|
|
MWWM
|
Controls whether XSI obeys window manager keystrokes on Linux.
By default, XSI does not obey any window manager keystrokes. For example, Alt+Tab is used to switch tasks in Gnome, but this key combination does not work with XSI.
To change this behavior, source your .xsi_3.0 file and then type the following in a shell window (before starting XSI):
Now Alt+Tab will switch windows.
|
Linux
|
MainWin
|
|
PATH
|
A list of paths used by the system when searching for executable files.
On Windows, multiple paths are separated by semicolons. On Linux and IRIX, multiple paths are separated by colons.
XSI adds itself to the existing PATH value on Windows.
|
All
|
System
|
|
SI_DBDIR
|
The location of the DatabaseDir.rsrc file.
This file lists the name and location of each SOFTIMAGE|3D database to which you have access and can import into XSI.
By default, SI_DBDIR is set to the same value as XSI_USERROOT.
|
All
|
Softimage
|
|
SI_HELP_PROGRAM_ENV
|
The viewer used to display the HTML files for the scripting command and object model documentation.
The default value is iexplore.exe on Windows and mozilla on Linux and IRIX.
Note that no error message is given if the write and register SPDL functions cannot find the editor defined for this environment variable. Check for typing errors or that the editor does actually exist on your system.
|
All
|
XSI
|
|
SI_HOME
|
The location where the XSI program files are installed, for example, C:\Softimage\XSI_X.X.
It is important to declare SI_HOME at the beginning of the environment script because it is referenced in the environment variables that follow throughout the script.
For example, SI_HOME is sourced by the MI_ROOT environment variable, which tells mental ray (ray3.exe) where to find the ray3rc file (mental ray rsrc file) and subsequently the location of the mental ray shaders needed by XSI.
|
All
|
XSI
|
|
SI_IMAGE_PATH
|
The location of shared libraries for image manipulation required by certain standalones.
This variable should be set to the /sil subfolder of the directory specified by XSI_BINDIR.
If SI_IMAGE_PATH is not set, then by default the /Application/bin/sil subfolder of the directory specified by SI_HOME is checked for the required libraries. That value is also set by default in setenv.bat on Windows and .xsi_3.0 on Linux and IRIX.
|
All
|
Softimage
|
|
SI_LINKTAB_LOCATION
|
The location of the linktab file.
This file maps between the equivalent Windows and UNIX paths for textures and other external scene files when working on a mixed network.
SI_LINKTAB_LOCATION can define both the path and file name or just the path; if no file name is explicitly set, XSI assumes the name is linktab.ini.
See also SI_LOCATION.
|
All
|
XSI
|
|
SI_LOCATION
|
The location of the linktab file used when importing files from SOFTIMAGE|3D.
See also SI_LINKTAB_LOCATION.
|
All
|
Softimage
|
|
SI_TXT_EDITOR_ENV
|
The default external text editor.
This editor can be used to edit SPDL files as well as expressions.
The default value is notepad.exe on Windows, xterm -e vi on Linux and IRIX.
|
All
|
XSI
|
|
SI_USERHOME
|
The location of various user-specific XSI files on Linux and IRIX.
The default is the Softimage subdirectory of your home directory.
|
Linux, IRIX
|
XSI
|
|
SICOREPATH
|
The location of some required libraries.
This variable should be set to the Application/bin subfolder of the directory specified by SI_HOME.
Do not modify this value.
|
Linux
|
XSI
|
|
SPDLDISABLECACHE
|
Disables SPDL caching and forces a reload of the SPDL file for each use.
This variable is useful if you are doing heavy development work with scripted operator presets or other plug-ins that use SPDL, such as shaders, and you do not want to have to close and reopen XSI to refresh the SPDL.
To turn off SPDL caching define the environment variable as follows:
set SPDLDISABLECACHE=1
Setting this variable may slow down the running of XSI, so it is not recommended for machines that are actively being used for production.
|
All
|
XSI
|
|
STORMPATH
|
The location of some required libraries.
This variable should be set to the Application/bin subfolder of the directory specified by SI_HOME.
Do not modify this value.
|
Linux
|
XSI
|
|
SUMATRAPATH
|
The location of some required libraries.
This variable should be set to the Application/bin subfolder of the directory specified by SI_HOME.
Do not modify this value.
|
Linux
|
XSI
|
|
SPM_HOST
|
Specifies the SPM licence server.
This variable should be set to the hostname or IP address of the computer that is running the SPM daemon. Multiple servers can be separated with semicolons (Windows) or colons (Linux and IRIX).
If this variable is not set, the SPM client first tries localhost, then spmhost0, spmhost1, and spmhost2.
|
All
|
SPM
|
|
SYSTEMDRIVE
|
The drive on which Windows is installed.
XSI uses this variable to define XSI_USERROOT on Windows systems.
SYSTEMDRIVE is set by Windows and should not be changed.
|
Windows
|
System
|
|
USERNAME
|
The current user name on Windows.
XSI uses this variable to define XSI_USERROOT on Windows systems.
USERNAME is set by Windows and should not be changed.
|
Windows
|
System
|
|
XSI_BINDIR
|
The location of the XSI executable binary files.
This variable should be set to the Application/bin subfolder of the directory specified by SI_HOME.
Do not modify this value.
|
All
|
XSI
|
|
XSI_CPU
|
Identifies the type of CPU in the machine. The CPU type is set during installation.
Do not modify this value.
|
All
|
XSI
|
|
XSI_CPU_OPT
|
Identifies the CPU version in the machine.
The CPU version is auto-detected and set during installation.
Do not modify this value.
|
All
|
XSI
|
|
XSI_EXT
|
Identifies the file name extension used by shared libraries.
This value should be dll on Windows or so on Linux and IRIX.
|
All
|
XSI
|
|
XSI_HOME
|
The location where the XSI program files are installed, for example, C:\Softimage\XSI_X.X.
|
All
|
XSI
|
|
XSI_PRELOAD_DLLS_LIST
|
The location of the file containing the list of libraries (dlls /.so) you want to preload at startup (one library listed per line).
|
All
|
XSI
|
|
XSI_USER_SHADERPLUGINS
|
The location of the shader_plugins.mi mental ray registry file for the user-specific custom shaders.
This file identifies custom mental ray shaders and is created and updated automatically when you integrate a custom shader. It contains the path to the shader library and the user interface (SPDL) file for each custom shader.
By default, XSI_USER_SHADERPLUGINS is set to the Application/rsrc subfolder of the directory specified by SI_HOME, unless XSI detects a copy of shader_plugins.mi in the Softimage/XSI_X.X/Addons subfolder of the user’s home directory.
It is not recommended to modify this variable. Doing so may make it impossible for XSI or mental ray to locate custom shaders.
|
All
|
XSI
|
|
XSI_USERROOT
|
The user’s home directory.
This must be a unique location for each specific user. XSI creates a /Softimage/XSI_X.X folder in this directory for storing custom scripts, toolbars, preferences, presets, and other personal XSI files in various subfolders.
XSI_USERROOT is created by XSI. The default value is:
By default, XSI_USERROOT is set to a local drive. However if individual users often move between machines or work on several machines each, then you may want to set XSI_USERROOT to a user directory on the network, for example:
Because multiple users cannot share the same users directory, make sure you include the current user name (%USERNAME%) in the variable definition.
You also need to change the setenv.bat file on all applicable machines. Note that the shared drive on the server must have read and write permissions.
Note: use a workgroup to share plug-ins and add-ons across multiple machines. Do not share a user’s home directory for this purpose.
|
Windows
|
XSI
|
|
XSI_WORKGROUP_SHADERPLUGINS
|
The location of the shader_plugins.mi mental ray registry file for the shared custom shaders of the workgroup.
This file is created and updated when someone such as a technical director integrates a custom shader into the workgroup database. It identifies custom mental ray shaders and contains the path to the shader library and the user interface (SPDL) file for each custom shader.
This variable is set by a batch or script file: xsi_workgroup_shaderplugins.bat on Windows or xsi_workgroup_shaderplugins.csh on Linux and IRIX. The batch or script file is created in the Softimage/XSI_X.X/Addons subfolder of a user’s XSI_USERROOT directory when the workgroup application path is defined in the User Preferences dialog box and is called by setenv.bat on Windows and .xsi_3.0 on Linux and IRIX.
This arrangement makes it possible to change workgroup directories and link to custom shaders in situations where individual users do not have permission to modify setenv.bat or .xsi_3.0 directly.
It is not recommended to modify this variable. Doing so may make it impossible for XSI or mental ray to locate custom shaders.
|
All
|
XSI
|
|
XSISDK_ROOT
|
The location of the XSI SDK files.
By default, this is the XSISDK subfolder of the directory specified by SI_HOME.
|
All
|
XSI
|
|