Omnis Technical Note TNSQ0025 Updated January 2017

Setting Environment Variables on the Mac

For Omnis Studio
By Gary Ashford

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


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:

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/TigerLogic
          $ export DYLD_LIBRARY_PATH=/Applications/SQLAnywhere11/System/lib32
          $ open "Omnis Studio"

The "xxxdam.ini" Files

The DAM.ini files (e.g. were conceived as a way to allow environment variables to be set independently of (in the absence of ) the environment.plist file.
Unfortunately, they are of little use in setting DYLD_LIBRARY_PATH, since they are only read and processed once the DAM has already loaded and any clientware dependencies resolved.
DAM.ini files can be used to set vendor specific variables, such as ODBCINI, NLS_LANG and SYBASE_OCS although it should be noted that any values set here will override any values set by other means, e.g. via launchctl.

Note that following implmentation of the Omnis putenv command, xxxdam.ini files are no longer required. The Omnis library can set shell environment variables itself. For example:

      Do putenv('NLS_LANG','AMERICAN_AMERICA.WE8ISO8859P1')
      Do putenv('TNS_ADMIN','/Users/myUser/instantclient_11_2')/


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 xxxdam.ini files 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: - Setting environment variables in OS X