Using and Debugging Environment Variables

Environment variables can be used to configure the various Validator tools that we provide. Configuration provides flexibility, but it also provides avenues for failure. In this article, I’m going to show you how you can configure our tools using environment variables, and how you can debug them if that configuration goes wrong.

In this article, I’m going to use Coverage Validator, but these topics also apply to Bug Validator, Memory Validator, Performance Validator and Thread Validator.

Should I use % or $?

Note that you can use % to delimit env vars, as in %PATH%, or you can use $ to delimit env vars, as $PATH$.

If you use % the command shell (or batch file processor) will do the substitution before the Validator gets to see the command line.

If you use $ the command shell will not do the substitution for you, the Validator will do the substitution.

Using environment variables

Any Validator command line option that also takes an argument can have that argument supplied by an environment variable. For example:

• -program e:\test\test.exe
• -directory e:\testArea
• -arg 1
• -arg “strawberry ice cream”

Using environment variables, the above could become

• -program $TEST_PROGRAM$
• -directory $TEST_AREA$
• -arg $TEST_COUNT$
• -arg $FAVOURITE_ICE_CREAM$

A slightly more complicated command line could look like this:

coverageValidator.exe -program $BUILD_DIR$\test.exe -directory $TEST_DIR$ -fileLocations $TEST_DIR$\fileLocations.cvxfl

This command line starts test.exe located in the directory identified in the BUILD_DIR environment variable, with the current directory set to the directory identified in the TEST_DIR environment variable, and sets the source code file locations to the list of files specified in the fileLocations.cvxfl file in the directory identified in the TEST_DIR environment variable.

The fileLocations.cvxfl file can also contain environment variable definitions:

[Files]
$SRC_DIR$\model
$SRC_DIR$\view
$SRC_DIR$\controller
$SRC_DIR$\test 
[Third]
[PDB]
[MAP]

The environment variables in the fileLocations file (or any other file where environment variables are used) are substituted for the environment variable definitions when that file is loaded. In the example above, if the SRC_DIR environment variable had the value “e:\abcMusicTutor”, the file contents lines would evaluate to:

[Files]
e:\abcMusicTutor\model
e:\abcMusicTutor\view
e:\abcMusicTutor\controller
e:\abcMusicTutor\test 
[Third]
[PDB]
[MAP]

As you can see, the use of environment variables allows you to set up a general framework for controlling Coverage Validator from the command line, but then customise that usage by setting the environment variables appropriately.

What happens when things go wrong?

When using environment variables, there are a few things that can go wrong:

• The environment variable isn’t defined
• The value in the environment variable is wrong
• The value in the environment variable doesn’t exist

You can view the environment variables in the Validator, the target application, and any environment variable substitution errors using the Env Vars tab in the Diagnostic part of the Validator.

To view the environment variable substitution errors choose “Environment variable errors” in the combo box on the Env Vars tab.

Environment variable not defined

All the Validator tools check if an environment variable is defined or not. Environment variables that are not defined are logged and reported on the Diagnostic Environment Variables display. In addition, any locations where the substituted value is meant to be used as a directory or filename (the fileLocations example) will show the non-substituted path ($SRC_DIR$\model) and will be highlighted in an error colour indicating an invalid path.

Example: These are values loaded via -fileLocations. The environment variable SRC_DIR does not exist. The file locations dialog lists the invalid paths in red.

Example: These are values loaded via -fileLocations. The environment variable SRC_DIR does not exist. The columns show the environment variable name, the original string value being parsed, a comment indicating where this option was encountered and a timestamp.

Environment variable is wrong

Each Validator can’t tell if a value is wrong. This is a subjective matter. For example: -numSession $NUM_SESSION$.

If NUM_SESSIONS is set to 1 when you’d prefer it to be 2, that’s an error that will stop you from loading multiple sessions and comparing them, but it’s not an error that will prevent Coverage Validator from performing code coverage.

As such, debugging this error is something that requires your judgement. Examining the Diagnostic Environment Variables displays will help you identify what the problem is.

Value in the environment variable doesn’t exist

A common error case is where the environment variable specifies a directory, but the directory does not exist. A related error case is when a filename is specified but does not exist. For cases like -fileLocations where the values loaded can be inspected in the settings displays you will see the specified folder location listed in an error colour indicating an invalid path.

The best way to debug this class of error is to open the settings dialog (Settings->Edit Settings…) and examine all settings looking for paths in the error code (the default for this is red).

Example: The environment variable SRC_DIR did exist and was substituted for e:\abcMusicTutor, but that directory does not exist.

How do I view the Validator’s environment variables?

To view the Validator’s environment variables, on the Diagnostic Env Vars tab, choose “??? Validator” in the combo box, in this example “Coverage Validator”. The environment variables will be shown below.

How do I view the target application’s environment variables?

To view the target application’s variables, on the Diagnostic Env Vars tab, choose “Application being monitored” in the combo box. The environment variables will be shown below.

If you launched the target application from the Validator, the target application’s environment variables will be similar to those in the Validator, but with some additional env vars to control .Net profilers and some other SVL_ prefixed env vars to communicate various data to Software Verify components that are loaded.

If you launched the target application as a standalone application or service and used one of our APIs to connect to the Validator, the environment variables shown will reflect those in force at the time the application/service was started, and the account that application/service is running on.