Platform Agent Environments

RunMyJobs tries to keep the environments under which Platform Agents run as consistent as possible between platforms. However, some platforms differ slightly, especially where Platform Agents use a native OS process environment.

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

  • Account: The account used to run the code.
  • Files: The output and log files.
  • Environment variables: Both standard and RunMyJobs environment variables.

Note: On OpenVMS, no JCS_ variables are set, and neither jtool nor the RunMyJobs tools are guaranteed to be in the PATH. Also, Process Server parameters KeepEnvironmentVariables, EnvironmentFile, and EnvironmentVariables are not available.

Note: You must install Platform Agents on a local file system. SAN file systems may be considered local (if they are mounted as iSCSI, for example). NFS and Windows shares are not supported because they may not be available at all times.

To specify limits, use the appropriate OS-specific procedure. For example, to set ulimit -s on a GNU/Linux system with systemd, specify LimitSTACK on the service.

Account

A Platform Agent's process runs under the account specified in the Process Definition.

  • If the account is not specified, a default account is used.

  • If an account is specified, but unavailable, the process goes into Error status.

Files

The current directory for a Platform Agent's OS process is a directory where the process can put files. All files placed there are 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

On UNIX, the set of environment variables is controlled by the KeepEnvironmentVariables, EnvironmentFile, and EnvironmentVariables Process Server parameters. RunMyJobs looks up the user-defined environment variables in the OS environment, and then looks up any remaining unresolved variables in the user-defined environment.

The following files are also sourced.

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

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

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

The following variables are also set.

  • JCS_JOB_ID: The JobId of the process.
  • JCS_JOB_FILES_DIR: The path of the directory that the OS process can write output files to. The OS process starts out with this directory as its current directory.
  • SHELL, HOME, LOGNAME and USER: These are set to the values for the account that the OS process runs as.
  • TMPDIR, TEMP and TMP: These point to a directory where the OS process can put temporary files. Temporary files will be removed when the process finishes.
  • PATH: This is inherited from the network-processor process, but prefixed with the location of the RunMyJobs tools. This way, you can call tools such as jsleep, jftp, jevent, and jshell without having to specify a path. If PATH is not in the KeepEnvironmentVariables parameter, it will be set to a default PATH value containing the location of the RunMyJobs tools, /usr/bin, and /bin.

Windows

On Windows computers, the Platform Agent starts with the set of environment variables for the user that the Platform Agent runs as. The resulting environment is the same as what you would get if you interactively logged on as that user. Then, the following environment variables are also set.

  • JCS_JOB_ID: The JobId of the process.
  • JCS_JOB_FILES_DIR: The path of the directory that the OS process can write output files to. The OS process starts out with this directory as its current directory.
  • JCS_CODEPAGE: The value of the ANSI code page in effect for the Platform Agent. All Definition Type runner scripts select this code page as the OEM (DOS) code page, so all local files are written in this code page.
  • USERNAME, USERDOMAIN and USERPROFILE: The values for the account that the OS process runs as.
  • TMPDIR, TEMP and TMP: These point to a directory where the OS process can put temporary files. Temporary files will be removed when the process finishes.
  • PATH: This will be set from the user hive, but prefixed with the location of the RunMyJobs tools. This way you can call RunMyJobs tools such as jsleep, jftp, jevent, and 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. If a variable is defined multiple times, the last definition is used.

Variables are resolved as follows:

  1. The list of environment variables is loaded from the OS.
  2. The variables set in the Process Server parameter EnvironmentVariables are loaded.
  3. The Process Server parameter EnvironmentFile is resolved with any loaded variables.
  4. The variables in the environment file are loaded.
  5. Any variables that refer to other variables are resolved.

Microsoft Windows Tips

  • Instead of using %variable% syntax to resolve parameters, use ${variable}.
  • Use \; to separate multiple directory parts in variables. A semicolon (;) is used as a separator between variables in the EnvironmentVariables and EnvironmentFile syntax.
  • Use \\ for backslashes in directory names, because \ 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 a forward slash as a directory separator.

For example:

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

General Tips

Refer to variables as shown here.

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

Or, alternatively, use syntax like the following.

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

Error Reporting in Platform Agent Definition Types

For all Definition Types on UNIX and Windows:

  • Error codes start with JDT-nnnnn.
  • The return code used when a process goes into an error state before the script was able to run is 255.

For all Process Definition Types on Windows:

  • To debug setup code, set the environment variable JCS_DEBUG to any non-null value.