Developers

Omnis Technical Note TNSQ0025 Updated January 2017

Setting Environment Variables on the Mac

For Omnis Studio
By Gary Ashford

Introduction
This Technote consolidates references made in other Technotes to setting Mac environment variables prior to starting Omnis. Historically, this has not been as straight forward as one might expect owing to differences in the Darwin operating system over a 'bulk standard' Linux operating system and the way in which the Mac operating system has evolved over the years.

The environment.plist File
Deprecated content! This section has been hidden by default because the environment.plist file is no longer supported as of MacOSX 10.7 "Lion".   Show Hide

~/.launchd.conf and /etc/launchd.conf

Deprecated content! This section has been hidden by default because ~/.launchd.conf and /etc/launchd.conf are no longer supported as of MacOSX 10.10 "Yosemite".   Show Hide

launchctl

As of MacOSX 10.10 (Yosemite), it is possible to use the launchctl command to set enviroment variables within a user's session. For example:

launchctl setenv DYLD_LIBRARY_PATH /Users/myUser/instantclient_11_2/

When set using terminal session, variable values are inherited by all system processes but the values are lost when the system is rebooted. A slightly more complex solution is required in order to make launchctl assignments automatically during logon:

https://sergeemond.com/en/articles/os-x-environment-at-login/

The DYLD_LIBRARY_PATH Issue
Prior to Mac OS X 10.5 (Leopard), it was not possible to set the DYLD_LIBRARY_PATH variable inside the environment.plist file; the value assigned there was overwritten (cleared) by the system. With reference to Omnis Studio, this meant that the environment.plist file could not be used to locate client libraries required by the DAMs.
The other ways we advocated for locating client libraries were to:

• Move the client libraries to a location on the standard library search path, i.e. /usr/lib and /usr/local/lib. This is often undesirable due to the volume of client files, the system privileges required or duplicate file names. note that it is no longer possible to use this approach as MacOSX 10.11 (El Capitan) unless System Integrity Protection (SIPs) is disabled.
• Create symbolic links to the client libraries from locations on the standard library search path to their installed locations. This may require System Administrator privileges and also may not be possible on more recent systems unless SIPs is disabled. Fortunately, there is a location on the standard library search path that is accessible to the standard user: $(HOME)/lib, for example:
        cd ~
        mkdir lib (in case this folder does not already exist)
        cd lib
        ln -s /Users/myUser/instantclient_11_2/libclntsh.dylib.11.1 libclntsh.dylib.11.1
• Set DYLD_LIBRARY_PATH from within the context of a terminal window, then start Omnis from the command line,
  For example:
        $ cd /Applications/Omnis Software
        $ export DYLD_LIBRARY_PATH=/Applications/SQLAnywhere11/System/lib32
        $ open "Omnis Studio 6.0.1.app"

The "damxxx.ini" Files

Deprecated content! This section has been hidden by default because damxxx.ini files are no longer used in Studio 10.1 and later. See below.    Show Hide

Setting Environment Variables using config.json

In Studio 10.1 and later, xcomp/ini/damxxx.ini files previously used to set environment variables on macOS are no longer used. Instead, DAMs now look inside the "macOS" section of the Omnis Studio config.json file, for example:

"macOS": {
  "useDictation": true,
  "odbcdam.ini": "ODBCINI=/Library/ODBC/odbc.ini, MYVAR=Custom value",
  "oracle8dam.ini": "NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1, TNS_ADMIN=/instantclient_11_2"
}

Conclusion

The recommended approach for setting environment variables and locating clientware as of MacOSX 10.10 (Yosemite) is twofold:

• Create symbolic links from a location on the standard library search path to the client library install location. This avoids the need to set the DYLD_LIBRARY_PATH enviroment variable and the links created will persist after the system is rebooted.
  The standard library search path includes the following locations: $(HOME)/lib, /usr/lib, /lib & /usr/local/lib
• Use the config.json file to set additional environment variables or use the putenv method from within the Omnis library. This mechanism can be used to set environment variables for use within the Omnis process and works for all environment variables except DYLD_LIBRARY_PATH as discussed above.

References:

Stackoverflow.com - Setting environment variables in OS X