Technical Notes

Verastream Scripting Language Environment Variables
Technical Note 10206
Last Reviewed 10-Aug-2007
Applies To
Verastream Integration Broker version 8.0 or higher
Verastream EAI Suite version 7.1 or higher
Summary

It is often good programming practice to use environment variables in application development. The Verastream Universal Integration Engine uses some required and optional environment variables. There are several ways to set environment variables; in the system.fle file, the sn.ini file, login or initialization scripts, or on the command line. From a Verastream script, environment variable settings can be obtained by using the parameter expression.

All Verastream supported environment variables are described in User Manual II, section 21.3, as well as in other appropriate sections of the manuals.

The System.fle File

The system.fle file is the primary method of configuring environmental variables for Verastream installations. This file is located in the directory specified by the required environmental variable PARDIR (further information on PARDIR is provided below), and is read by the nova executable nova.exe.

Variables stored in this file can be edited using the Verastream Workbench. To do so, open the Verastream Workbench, click Custom, click Preferences, and then click Parameters.

This method of storage and configuration allow Verastream to maintain platform independent environmental variable settings.

The Sn.ini File

The secondary method for setting environment variables, specific to the nova executable or your Verastream application, is in the sn.ini file. This approach of using an initialization file with an "ini" extension may be familiar to Windows 3.1 users, and its usage is similar; however, this approach has been applied to all platforms, not just Windows, and it is the nova executable that uses the sn.ini file.

The sn.ini file is located with the nova.exe file in the bin directory of your Verastream installation. Sn.ini is a text file that you can modify with any text-based editor. Notice that the environment variable settings correspond to information you provided during the installation of Verastream. The sn.ini file can be modified and copied to your application startup directory, to override the default settings in the Verastream bin directory sn.ini file. You can also set application-specific environment variables in the sn.ini file.

Note: The sn.ini file was added in Verastream versions 7.0 and higher. Prior to this, non-windows platforms set environment variables in startup or login scripts. On the Microsoft Windows platforms, the fours.ini file was used in place of the sn.ini, and also supported the use of OS set environment variables, as it does today.

Using the parameter() Expression

You can use the parameter expression to obtain the value of an environment variable. The following Verastream script command prints the parameter directory environment variable:

The parameter() expression is also a good way to test which sn.ini file is being read by an application. If the configuration of a startup directory is not known, or it is not known whether the sn.ini file is being read at all, the parameter() expression can help debug a configuration.

The parameter expression can also be useful in applications where configurations need to be frequently or easily changed without making a code modification. For example, you might want to specify the location of data files or the name of a database in an environment variable so that you can easily switch between test and production databases without having to make any code changes.

Setting Environment Variables at the Operating System Level

In addition to using the system.fle and sni.ini files to set environment variables, environment variables can also be set at the operating system level. A system administrator should be knowledgeable about how to do this, but it is briefly covered here. The method you use depends on the operating system. In a Windows NT platform, environment variables can be set on the Environment tab in System Properties. On the UNIX platform, environment variables are traditionally set in scripts called by a shell login script, such as ".profile". A VMS system would probably use a SYSLOGIN.COM or LOGIN.COM file.

Operating System	Set the environment variable
NT	Control panel, system properties, environment tab
UNIX	.login, .profile
VMS	SYSLOGIN.COM (System wide); LOGIN.COM (personal login)

Setting Environment Variables on the Command Line

You can set environment variables on the command line when you start the Verastream engine, nova or nova.exe. This is useful when you configure a partitioned application that includes a command line in the dpclient.dat file. In this case, it may be desirable to include an environment variable on the command line.

For example, you may not have permission to modify the system.fle or sn.ini file and might want to turn on the nova debug log. Providing the application is designed to report debug information (for example, NEWDBG STATUS), the nova debug log can be turned on at the command line by setting MYDBG.

Here is an example that sets the environment variables: PARDIR, FSSAMPLEDATA, and MYDBG on the command line.

Syntax: nova +[Environment variable setting]

Sequence of Parameter Evaluation

As previously described, it is possible to specify a Verastream parameter using four different methods; the sysem.fle file, the sn.ini file, the operating system environmental variable settings, and the command line. The VIB engine processes these settings in the following sequence:

1. system.fle file
2. operating system environmental variable
3. sn.ini file
4. command line entry

If the same environmental variable is specified in more than one location, the variable specified in by the higher numbered method is used. For example, an environmental variable set in the sn.ini file will take precedence over the same variable set in the system.fle file.

Overriding Default Environment Variables

In some cases it may be necessary to change a default Verastream setting. The most common case is setting the MYDBG environment variable to turn debugging on or off. However, the need may be more sophisticated. Here is an example in which you may want to reset an environment variable.

The Verastream default configuration is to have one Directory Server to a network. This is much like a Name server, but specific to Verastream applications. The Directory server resolves system to system and application to application communications by specifying what system is providing a component method. The disadvantage of this is that it creates dependencies on other systems. When only application to application communication is required, you do not want external system dependencies, so you may want to override the SNDIRECTORYSERVER environment variable that determines which system acts as the Directory Server.

About Verastream Environment Variables

The environment variables you need depend on the technology the Verastream Universal Integration Engine is providing. Look at the contents of the sn.ini file. If the Verastream installation was done correctly, and the technologies used were correctly specified, the sn.ini file will contain the environment variables needed by the Verastream Universal Integration Engine. You can reset environment variables if required. Environment variables such as PARDIR and those required by the ETD (Enterprise Team Development) and APM (Application Partitioning Manager) must be set prior to invoking "nova".

A few common environment variables used by most applications are discussed below. A complete list of Verastream supported environment variables are described in User Manual II, section 21.3, as well as in other appropriate sections of the manuals.

PARDIR

The PARDIR parameter must contain the name of a directory where valid Verastream distribution files like system.fle and builder.fle can be found. A search for terminal capabilities, function keys, printers, parameters, distribution tables and system messages will be done in the PARDIR directory. If the APPLPATH parameter has not been set, a search for applications will also start in the current directory followed by the directory specified in PARDIR.

APPLPATH

Another commonly used environment variable is APPLPATH. This parameters controls which directories will be searched by Verastream for applications and sub-applications. If APPLPATH is not set, Verastream will first look in the current directory and then in the PARDIR directory. APPLPATH contains one or more directory names separated by an operating system-dependent separator: a colon for UNIX, a semicolon for DOS and a comma for VMS. Each of these directories will be scanned in turn for the application needed. When you want to use the Component Builder, you should include PARDIR as one of the directories in APPLPATH.

Operating System	Example
UNIX	APPLPATH=.:$PARDIR:/usr/nova/applic
Microsoft DOS and Windows	set APPLPATH=\;;\nova\pardir;a:
VMS	define APPLPATH [],pardir,sys$login:[nova.applic]

Note: APPLPATH does not influence the search path for system.fle; PARDIR must be set.

MYDBG

Another commonly used environment variable is MYDBG. This optional environment variable specifies the amount of debug information logged. When the application code includes the function DBG STATUS, debugging data and system status is generated. This environment variable specifies the destination and the nature of the data. If the MYDBG variable is not set, no data will be recorded. The following example is a debug setting that reports all information to the “nova.log” file.

This debug information is very useful when troubleshooting Verastream. When contacting Attachmate for VIB technical support, it is recommended that you generate and have available a debug file with the MYDBG setting "all" specified.

Related Technical Notes

10234	Enabling and Using Logging in Verastream Integration Broker
10999	Verastream Integration Broker Technical Notes