The Environment of Platform Agent OS Processes

All OS processes that run on the platform agent obtain a reliable environment. The environment of the OS process is kept as consistent as possible, regardless of OS and/or OS family (UNIX, Microsoft Windows, HP OpenVMS).

Some platforms differ slightly, especially where the native OS process environment is re-used.

For UNIX and Windows, an OS process' environment contains the following:

account - the account used to run the code.
files - output and log files.
environment variables - standard environment variables and Redwood Server-specific ones that store the process ID, for example.

note

On HP OpenVMS, no JCS_ variables are set and jtool as well as all the Redwood Server tools are not guaranteed to be on the path. Process server parameters KeepEnvironmentVariables, EnvironmentFile, and EnvironmentVariables are not available either.

note

You must install the Redwood Server platform agent on a local file system; SAN file systems might be considered local, when they are mounted as iSCSI, for example.

You use the OS-specific procedure to specify any limits, for example, to set ulimit -s on a GNU/Linux system with systemd, you specify LimitSTACK on the service.

Error Reporting in Platform Agent Definition Types

For all definition types on UNIX and Microsoft Windows:

Error codes start with JDT-nnnnn:
The return code used when a process errors before the user script code was able to run is 255.

For all process definition types on Microsoft Windows:

You debug the setup code by setting environment variable JCS_DEBUG to any non-null value.

Account

The OS process will be run under the account that is specified in the process definition. If this is not null but the account is not available the process will fail (status Error ). If the account is null, a default account will be used.

Open files

The current directory for the OS process is a directory where you can place files. All files placed there will be listed as output files, and are viewable in the user interface.

An OS process can write text output to stdout and stderr.
Reading from stdin will result in no data being returned.
No other file handles or descriptors are open.

Environment Variables

UNIX

For UNIX the set of environment variables is controlled by the KeepEnvironmentVariables, EnvironmentFile, and EnvironmentVariablesprocess server parameter. Redwood Server then looks up the user defined environment variables in the existing OS environment, and eventually looks up the remainder of unresolved variables in the user defined environment.

Additionally, the following files are sourced:

${InstallDir}/etc/environment
${startupDir}/environment
${InstallDir}/${version}/etc/environment

The result is then added to the OS Environment updating any existing definitions.

OS limits imposed upon the user that started the network-processor are imposed on all platform OS processes, regardless of the user under which they run - this is standard UNIX functionality.

Additionally the following variables are set:

JCS_JOB_ID - set to the JobId of the process.
JCS_JOB_FILES_DIR - points to the directory that the OS process can write files to that will be listed as output files. The OS process also starts out with this directory as its current directory.
SHELL, HOME, LOGNAME and USER - set to the correct value of the account that the OS process runs as.
TMPDIR, TEMP and TMP - point to a directory that contains process-specific temporary files. The OS process can add extra temporary files there. They will be removed when the process finishes.
PATH - inherited from the network-processor, but prefixed with the location of the Redwood Server tools. This way you can call tools such as jsleep, jftp, jevent, jshell without having to specify a path. If PATH is not in the KeepEnvironmentVariables parameter, it will be set to a default path consisting of the location of the Redwood Server tools, /usr/bin and /bin.

Microsoft Windows

For Microsoft Windows the environment variables are formed by recreating the standard set of environment variables for the user that the OS process runs for, by looking these up in the user hive in the registry. This is equivalent to the values that you would find active when you would log in interactively as that user.

Additionally the following environment variables are set:

JCS_JOB_ID - set to the JobId of the process.
JCS_JOB_FILES_DIR - points to the directory that the OS process can write files to that will be listed as output files. The OS process also starts out with this directory as its current directory.
JCS_CODEPAGE - set to the value of the ANSI code-page in effect for the agent. All definition type runner scripts select this code-page as the OEM (DOS) code-page, so that all local files are written in this code-page.
USERNAME, USERDOMAIN and USERPROFILE - set to the correct value of the account that the OS process runs as.
TMPDIR, TEMP and TMP - point to a directory that contains process-specific temporary files. The OS process can add extra temporary files there. They will be removed when the OS process finishes.
PATH - will be set from the user hive, but prefixed with the location of the Redwood Server tools. This way you can call Redwood Server tools such as jsleep, jftp, jevent, jshell without having to specify a path.

Environment Variable Evaluation

Environment variables are first loaded and then evaluated; this means that variables can be defined in any order; when a variable is defined multiple times, the last definition is used.

The variables are resolved as follows:

The list of environment variables is loaded from the OS.
The variables set in the process server parameter EnvironmentVariables are loaded.
The process server parameter EnvironmentFile is resolved with any loaded variables.
The variables in the environment-file are loaded.
Any variables that refer to others are resolved.

Microsoft Windows tips

Do not use %variable% syntax but ${variable} to resolve parameters.
Use \; to separate multiple directory parts in variables, ``; is used as a separator between variables in the EnvironmentVariables and EnvironmentFile syntax.
Use \\ for backslashes in directory names, as \ is used as an escape character.
You do not need to escape spaces as long as they are not at the end of a value.
You can use forward slashes as a directory separator

For instance:

MY_TOOL_BIN=C:\\Program Files\\My Tool\\bin;PATH=${MY_TOOL_BIN}\;${PATH};TIMEOUT=60

General tips

Resolving is done after all variables are loaded, so the order of defining variables does not matter.
Variables can refer to other variables which can refer to other variables to any level.
If variables are defined multiple times in the various sources the last one loaded takes precedence.

This does mean that the following is not possible as this defines PATH twice, only the last PATH specification is used and DIR1 is not part of PATH:

DIR1=ABC
PATH=${DIR1}:${PATH}
DIR2=DEF
PATH=${DIR2}:${PATH}

Referring to variables should be expressed like this:

DIR1=ABC
DIR2=DEF
PATH=${DIR2}:${DIR1}:${PATH}

Alternative:

PATH=${DIR2}:${DIR1}:${PATH}
DIR1=ABC
DIR2=DEF