Developers

Environment Variables and Omnis Studio

By David Swain
Polymath Business Systems

Omnis Studio 4.2 offers us a few new functions, as is usual for significant dot-releases. Among these are three that allow us to manage the environment variables on the computer on which Omnis Studio is running. Why would we want or need to do this? That is what we are here to explore in this article.

What Are Environment Variables?

When a process is launched on a computer, that process establishes variables that contain information about the environment for that process. Generally these are either the paths to certain things (path to an executing program, for example) or the names of certain things (the current user, the host computer, etc.). These variables are accessible by all programs executing within the context of or launched from within that process.

Programs can also be written to use additional environment variables that point to resource locations or that contain other information needed for the execution of that program within the local context. Environment variables are somewhat like preference settings, except that they are not specific to any one program. But they are also not as global as system preferences because they are set for individual users rather than for the entire computer.

System vs User Environment Variables

On Windows, there are two levels of environment variables: System and User variables. System variables can only be modified by an administrative user. We generally would not change these. If we do change a System environment variable, we must restart the computer for the system to recognize and use the new value.

User variables include both variables defined by the user and those set up by executing programs. We can edit these and use their new values without having to restart the computer. The program from within which we change an environment variable can use the new value immediately, but other programs will have to be restarted before they can use the new environment variable value.

Platform Differences

Since we can write cross-platform applications with Omnis Studio, we need to remain aware of the differences among platforms for the handling of environment variables. If we include code for manipulating environment variables, it is absolutely necessary that we do this correctly for the current platform on which our appliction happens to be running.

On the Windows platform, we can view (but not edit) environment variables using the System Information application. We access this application by following this path: Start menu>Accessories>System Tools>System Information. We then drill down to the Environment Variables display as shown here:

On Windows, environment variables can be managed manually using the System Control Panel under the Advanced tab. We access this by opening the Control Panels directory, launching the System control panel, selecting the Advanced tab and finally clicking the Environment Variables pushbutton we find on that pane. A window like this one will then appear:

Administrative users can see and manipulate both User and System variables. Non-administrative users can only access User variables.

On Mac OS X, System environment variables are buried somewhere deep in the UNIX core (meaning there wasn't enough time for me to locate them for this article) - but we would normally not want to change those anyway. User environment variable definitions are stored in a property list file named environment.plist, which is held in an invisible directory named .MacOSX within the current user's main directory. Since programming that requires environment variables is relatively rare on this platform, this file and directory do not exist by default. But some programs (like Omnis Studio versions 4.1) may create them on installation. If the directory and file have not already been created, then either the user must do so (which could present a problem or two) or we would have to execute a shell script using Applescript from within our program that performs this set of operations before we can set up any necessary environment variables.

Once this file is properly established, the user must then use the Property List Editor application (part of the Xcode suite of developer tools) to edit it. Here is what that might look like:

We can also view the raw XML content of this file in the Terminal program by typing:

more ~/.MacOSX/environment.plist

For paths stored in environment variables, there are also platform differences. Most platforms on which Omnis Studio runs use POSIX pathnames that use a forward slash character (/) to separate directory levels. This includes Mac OS X. Windows environment variables on the other hand, use the DOS path delimiting character: the backslash (\).

Alternate Values

An environment variable can contain multiple values if its use warrants that option. For example, an environment variable that contains a path for locating some kind of file might also contain an alternate path for that purpose. A program using this variable would use the first path, but if that does not lead to success it would then use the alternate path.

Alternate values are separated from one another by using a delimiting character. Here we face another platform difference. On those platforms that use POSIX pathnames, the alternate value delimiting character is the colon (:). Since this character is reserved for a specific purpose within DOS pathnames, the semicolon (;) is used as the alternate value delimiter on the Windows platform. So if we have an environment variable named PROGRAMPATH set up to point to the locations of two alternate applications for some purpose whose names are myProgram and myOtherProgram, those values might look like this:

On Mac OS X: /Applications/myProgram:/Applications/myOtherProgram
On Windows: C:\Program Files\myProgram;C:\Program Files\myOtherProgram

How Does Omnis Studio Use Environment Variables?

The classic Omnis Studio example for the use of environment variables in for the use of Java components. Omnis Studio must know where any custom Java classes are to be found and, on all platforms except Mac OS X, it must be told where the Java Virtual Machine is kept as well. So it looks for the environment variables CLASSPATH and OMNISJVM to find this information. instructions for setting up and assigning values to these variables are given in the Omnis Programming manual beginning on page 584.

By default, the CLASSPATH value points to a directory that may contain Java classes we have no use for in our Omnis Studio application. Version 4.2 now also recognizes an environment variable named OMNISCLASSPATH, which we can use to point to only those directories containing Java classes we need for our application.

But we could also choose to set up and use our own environment variables for other purposes if we wish. Perhaps we want to use an external directory to house image files or ad hoc reports. We could establish and query our own environment variable (call it CUSTOMPATH or something similar) and use it like we might use a sys() function option. If only we had the tools to set up and manipulate environment variables easily from within an Omnis Studio application...

New Environment Variable Functions

Rather than requiring that our users manually set up or adjust their environment variables in the Control Panel (Windows) or using the Property List Editor (Mac OS X), we now have the tools to perform this feat from within our Omnis programs. Under the General tab of the Catalog window in Omnis Studio 4.2, we find three new functions: listenv(), getenv() and putenv(). Here is a bit more detail on each of them:

The listenv() function returns a list of the current set of user environment variables along with the value of each variable. Note that no parameters are required (or even used) by this function. The list this function returns contains two columns named name and value. Both of these columns are of Character data type. The name column is limited to 255 characters, but the value column can contain up to the Omnis Studio maximum string length. Here is a typical set of environment variables one might find on the Mac OS Xplatform:

Note that not all of these variable are of use to Omnis Studio. Only those involving the odbc.ini file are consulted by Studio 4.2.

By contrast, here is a typical set of environment variables retrieved on a Windows machine:

While there is a lot more here, there is still very little that we would need to use with Omnis Studio. Still, there might be a number that we could take advantage of on occasion.

All we need to know is the name of the environment variable we wish to query. We can then use the getenv() function in a similar way to how we use the sys() function to retrieve the value of an individual environment variable. The name of the variable whose value we want to obtain is given as the parameter of the function. For example, if we want to know the name of the current user, we would use:

getenv('USERNAME')

Notice that the environment variable name we supply must be a string - either surrounded by quotes, contained in an Omnis Studio variable or calculated using a string manipulation expression. These are not variables of Omnis itself.

If the variable we request does not exist, the function returns an empty value.

But we might also want to set the value of an environment variable at some point. The putenv() function allows us to do so. This function requires two parameters: the name of the environment variable whose value we wish to modify and the value we want to assign to that variable. An added bonus to this function is that the variable is added to the existing set if it does not already exist - so be careful about your spelling and capitalization! For example, if we want to both create a new environment variable named OMNISREPORTPATH and assign a value of /Users/david/OmnisReports to it, we would issue:

putenv('OMNISREPORTPATH','/Users/david/OmnisReports')

If we want to append this path as an alternate value (when we know a value alreadys exists), we could use:

putenv('OMNISREPORTPATH',con(getenv('OMNISREPORTPATH'),':/Users/david/OmnisReports'))

These examples were given for Mac OS X, but the equivalents on Windows are easy to sort out.

Does This Solve Any Problems?

Well, it would have. Omnis Studio version 4.1 introduced a little problem involving environment variables for Mac OS X users. One specific variable controls the use of the Graph2 external component in that version of Omnis Studio. The dynamic library needed for the operation of that component was held in the dylib directory of the Omnis installation and an environment variable named DYLD_LIBRARY_PATH was needed to point to that directory.

It appears that Omnis Studio 4.2 no longer uses the DYLD_LIBRARY_PATH environment variable to locate the dylib directory, nor does that directory exist any more. Apparently the Graph2 component has been more fully integrated into the current version of Omnis Studio.

Still, we must manually set up environment variables to use Java classes within our applications, so we can use these new functions to simplify the setup process for our end users.

Next Time

In the next issue of Omnis Tech News, we will examine some other new feature of Omnis Studio version 4.2. I hope you continue to find these writings useful!