How to load data from an Iguana Environment Variable

Introduction

There are times times when you want to read the value from an Iguana Environment Variable. Fortunately this is very simple to do in your Lua translator scripts by using the os.getenv() function.

Combined with the ability to set environmental variables within Iguana this can be a powerful technique for customizing the behavior of scripts based the server they are running on.

A very common (and one of the most useful) applications for this is for Configuration Management — where you want to customize the configuration data based on the Iguana Server environment.

Task [top]

How to load an Iguana Environment Variables value into a variable in Lua code.

Implementation [top]

This is actually very simple just use os.getenv('<environment_variable_name>') to read the value from an Environment Variable. In general we suggest loading the value into a (psuedo) STATIC variable — we recommend using upper case to indicate that the variable should be treated as a static value.

The code for loading an environment variable looks something like this:

os.getenv read environment variable

   local YOUR_STATIC_VARIABLE = os.getenv('<environment_variable_name>')
   trace(YOUR_STATIC_VARIABLE)

The Environment Variable in the Iguana Settings looks like this:

environment variables

Note: If you are using the Environment Variables for configuration data then we recommend loading the data into a Lua table of (pseudo) constants, rather separate Lua (pseudo) constants. See Using Iguana Environment Variables in Lua for more information.

How it works [top]

You can use an Environment Variable so set a variable in your Lua code. This process works with any Iguana Environment Variable, however in most cases you will be using Local Iguana Environment Variables (that you create yourself). Environment variables can be read using the os.getenv('<environment_variable_name>') command. In general we suggest loading the value into a (psuedo) STATIC variable — we recommend using upper case to indicate that the variable should be treated as a static value.

There is one other thing that you need to be careful about — avoiding variable accidentally re-using the same variable in several channels.

For example if you have two channels, say Foxton Hospital and Foxton Laboratory, that both process files from disk and use a database.

And they use different source directories and process different file types.

  • Foxton Hospital:
    • Source Directory: C:\foxton\hospital
    • Database name: Foxton_Health
  • Foxton Laboratory:
    • Source Directory: C:\foxton\laboratory
    • Database Name: Foxton_Laboratory

If both channels use the same Environment Variables (FILE_INPUT_DIRECTORY and DATABASE_NAME) then we get a “name collision” — and the data will be incorrect for one or the other of the channels. To fix this we need to make sure the names are unique. The easiest way to do this is to add the channel name to the beginning of the Variable name. Using the channel names does get quite long but it guarantees uniqueness as channel names must be unique (within an Iguana Server instance).

The resulting variables with then be:

  • Foxton Hospital:
    • Source Directory: Foxton_Hospital.FILE_INPUT_DIRECTORY
    • Database Name: Foxton_Hospital.DATABASE_NAME
  • Foxton Laboratory:
    • Source Directory: Foxton_Laboratory.FILE_INPUT_DIRECTORY
    • Database Name: Foxton_Laboratory.DATABASE_NAME

By using the channel names the variables will be conveniently grouped by channel in Settings > Environment Variables which makes them easy to manage:

environment variable Lua code

Note: Some of you will recognize that this is using namespaces to specify scope. But it not necessary to know this, the important thing is that using channel names makes the variable names unique.

More information [top]