IBM Spectrum Symphony client environment variables

This topic describes the environment variables that the IBM® Spectrum Symphony client uses.

API_CALL_TIMEOUT

Syntax: API_CALL_TIMEOUT=value

Description: Defines the number of seconds the IBM Spectrum Symphony API waits to complete the API call to the session director or session manager before it times out. For a client to submit workload, the client must connect to an application and then call the IBM Spectrum Symphony API to interact with a session created on this connection. The timeout value can be any unsigned integer and -1, which is treated specially to specify that the API never times out.

Notes:

Do not specify zero (0) because then the API never waits and so never connects
Be aware that the IBM Spectrum Symphony API connect () will time out if you set a value for the SOAM_CONNECTION_TIMEOUT environment variable.

Default: -1 (never times out)

FAIL_CONN_IF_ANY_SSM_UNAVAILABLE

Syntax: FAIL_CONN_IF_ANY_SSM_UNAVAILABLE=Y | N

Description: Specifies whether a logical session is created for unrecoverable sessions even when all session managers are not available. When FAIL_CONN_IF_ANY_SSM_UNAVAILABLE is set to N, a logical session is created when at least one session manager is available. When not even one session manager is available, an exception is thrown.

PROXY_PATH

Syntax: PROXY_PATH=file_path

When IBM Spectrum Symphony clients send workload to a proxy server rather than to cluster hosts, specifies the directory from which to load the proxy.conf configuration file. If this variable is not defined, proxy.conf is loaded from $EGO_CONFDIR on Linux® or %EGO_CONFDIR% on Windows.

RS_REQUEST_TIMEOUT

Syntax: RS_REQUEST_TIMEOUT=value

Description: Specifies the number of seconds the deployment command waits for the repository server (RS) to send or receive a service package to or from the RS before it times out. The timeout value can be any positive integer and -1, which specifies that the deployment command never times out. If you specify zero (0), the default value of 300 seconds is applied.

Valid values: 1 to 4294967295

Default: 300 (seconds)

SOAM_APPLY_MESSAGE_CHECKSUM

Syntax: SOAM_APPLY_MESSAGE_CHECKSUM=NONE | CRC32

Description: Enables the data integrity check, which uses a CRC32 checksum to check user data, including common data, common data update, and task input and output during data transfer between clients and service instances. Once enabled, service instances detect the input data streams automatically and check the task output data streams if the task input data is checked.

To enable the data integrity check, set the SOAM_APPLY_MESSAGE_CHECKSUM environment variable to CRC32. Use this variable to detect errors which the NIC CRC checking cannot detect.

To disable the data integrity check, set the SOAM_APPLY_MESSAGE_CHECKSUM environment variable to NONE or remove the SOAM_APPLY_MESSAGE_CHECKSUM environment variable from your environment.

SOAM_CLIENT_PARALLEL_FETCH_NUM

Syntax: SOAM_CLIENT_PARALLEL_FETCH_NUM=positive_value

Description: Used with external task output transfer (enabled by setting the SOAM_TASK_OUTPUT_TO_FILE_THRESHOLD parameter in the application profile). Specifies the maximum size of the parallel fetching task output file in the client. This variable is optional. If the number is negative, an exception is thrown.

Default: 1

SOAM_COMMON_DATA_CHUNK_SIZE

Syntax: SOAM_COMMON_DATA_CHUNK_SIZE=positive_value

Description: The size of each common data chunk. If the size of common data is larger than this value, the common data is sent chunk-by-chunk. Otherwise, it is sent as a whole object. The unit is MB.

If this variable is not defined, common data chunking is disabled. Furthermore, if this variable is not defined, and the SI side uses the SoamCommonDataWrapper object of the onSessionEnter callback function, a casting exception is called in Java™.

SOAM_CONNECTION_RETRY_INTERVAL

Syntax: SOAM_CONNECTION_RETRY_INTERVAL=positive_value

Description: Specifies the number of seconds to wait before the client attempts to reconnect to each VEMKD, SD, and SSM daemon. This value is used in conjunction with the SOAM_CONNECTION_RETRY_LIMIT environment variable value, and must be a positive integer and cannot be a value of zero.

Default: 3 (seconds)

IBM Spectrum Symphony

Note: Do not confuse the SOAM_CONNECTION_RETRY_INTERVAL environment variable with the deprecated environment variable CONNECTION_RETRY_INTERVAL (deprecated as of 4.0). The SOAM_CONNECTION_RETRY_INTERVAL and SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL environment variables replace the deprecated CONNECTION_RETRY_INTERVAL environment variable.

SOAM_CONNECTION_RETRY_LIMIT

Syntax: SOAM_CONNECTION_RETRY_LIMIT=value

Description: Specifies the number of times the client will retry a connection for each VEMKD, SD, and SSM daemon. If the client cannot connect to VEMKD, SD, or SSM, the client will retry the connection using the value specified for this SOAM_CONNECTION_RETRY_LIMIT environment variable. If the number of attempts exceeds the value of the SOAM_CONNECTION_RETRY_LIMIT environment variable, the system throws an exception.

Valid values: 0 to 2147483647

Default: 0 (only connect once)

Note: Do not confuse the SOAM_CONNECTION_RETRY_LIMIT environment variable with the deprecated environment variable CONNECTION_RETRY_LIMIT (deprecated as of IBM Spectrum Symphony 4.0). The SOAM_CONNECTION_RETRY_LIMIT and SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT environment variables replace the deprecated CONNECTION_RETRY_LIMIT environment variable.

SOAM_CONNECTION_TIMEOUT

Syntax: SOAM_CONNECTION_TIMEOUT=positive_value

Description: Specifies the number of seconds the IBM Spectrum Symphony client waits to establish a physical connection to the session director or session manager before it times out. The timeout value can be any number between 1 and 600 (inclusive).

Default: 120 (seconds)

SOAM_DISCONNECTION_TIMEOUT

Syntax: SOAM_DISCONNECTION_TIMEOUT=positive_value

Description: Specifies the number of seconds that the IBM Spectrum Symphony client waits to close a physical connection to the session director or session manager before it times out. The timeout value can be any number between 1 and 600 (inclusive).

Default: 120 (seconds)

SOAM_DDT_WORK_DIR

Syntax: SOAM_DDT_WORK_DIR=value

Description: When direct data transfer (DDT) is enabled, specifies the top-level working directory on the IBM Spectrum Symphony client host under which DDT work data is stored. For example, when SOAM_DDT_WORK_DIR=/tmp, DDT work data is stored at /tmp/work/datamanager/. By default, DDT work data is stored at $SOAM_HOME/work/datamanager/ directory on Linux or %SOAM_HOME%\work\datamanager\ on Windows.

Applicable only to IBM Spectrum Symphony clusters, and not to IBM Spectrum Symphony Developer Edition standalone environments. You can, however, connect to an IBM Spectrum Symphony cluster as a client and use direct data transfer.

SOAM_DIRECT_DATA_PORT

Syntax: SOAM_DIRECT_DATA_PORT=port_number | port_number_range

Description: Defines a port or port range for the client to listen for connections from the service; for example, SOAM_DIRECT_DATA_PORT="25000" or SOAM_DIRECT_DATA_PORT="25000-25100". You may want to do this if your client is running behind a firewall.

SOAM_ENABLE_CLIENT_METADATA

Syntax: SOAM_ENABLE_CLIENT_METADATA=true | false

Description: Specifies whether the SSM collects metadata for the following attributes:

client host name
client IP address
client OS user name

When SOAM_ENABLE_CLIENT_METADATA is set to false, the attributes are not collected or displayed. Use this environment variable to disable metadata collection to gain a performance boost in the session run time.

Default: true

SOAM_ENABLE_SECURE_DDT

Syntax: SOAM_ENABLE_SECURE_DDT=DIGEST_AUTH

Description: Enables or disables the security measures (TLS and authentication) between the SI (service instance) environment and the IBM Spectrum Symphony client. If SSL or ALL is set as the value, then there is the option to set the TLS cipher list.

Note that if you accidentally set

SOAM_ENABLE_SECURE_DDT=DIGEST_AUTH

in an IBM Spectrum Symphony Developer Edition environment, you will encounter an error that the sec_ego_digest library is missing.

Specify any of the following valid values:

SSL (use only TLS)
DIGEST_AUTH (user only authentication)
ALL (use both TLS and authentication)

SOAM_FAM_CONSUMER

Syntax: SOAM_FAM_CONSUMER=consumer path

Description: Used with external task output transfer (enabled by setting the SOAM_TASK_OUTPUT_TO_FILE_THRESHOLD parameter in the application profile). Specifies the name of the consumer that starts FAM. The related resource group, consumer administrator, and OS user are used. If the consumer does not exist, the remote file access (RFA) fails to retrieve the output. This variable is required.

SOAM_RFA_RETRY_LIMIT

Syntax: SOAM_RFA_RETRY_LIMIT=positive_value

Description: Used with external task output transfer (enabled by setting the SOAM_TASK_OUTPUT_TO_FILE_THRESHOLD parameter in the application profile), and the SOAM_RFA_TIMEOUT variable. Specifies the maximum number of retries for the rfa command to fetch task output. If it still fails to fetch the task output, an exception is thrown. This variable is optional.

If this variable is not defined, the IBM Spectrum Symphony API wrapper does not attempt a retry.

SOAM_RFA_TIMEOUT

Syntax: SOAM_RFA_TIMEOUT=positive_value

Description: Used with external task output transfer (enabled by setting the SOAM_TASK_OUTPUT_TO_FILE_THRESHOLD parameter in the application profile), and the SOAM_RFA_RETRY_LIMIT variable. Specifies the duration (in seconds) for the rfa command to retrieve task output. If the RFA cannot retrieve the task output within the timeout, it is counted as a retrieval fail toward the SOAM_RFA_RETRY_LIMIT, and a fail if the limit is reached.

A timeout also applies when the RFA attempts to remove the task output from the computing host. If the RFA cannot remove the task output from the computing host within timeout, it gives up. An exception is thrown if the value of the parameter is not a positive number.

Default: 600

SOAM_SET_CIPHER_SECURE_DDT

Syntax: SOAM_SET_CIPHER_SECURE_DDT=cipher_list

Description: Sets the cipher list used by TLS. The client and server negotiate the cipher list and select the first shared one. Specify any of the following valid values:

AES256-GCM-SHA384 (Default)
AES256-SHA256
AES256-SHA
CAMELLIA256-SHA
AES128-GCM-SHA256
AES128-SHA256
AES128-SHA
SEED-SHA (as of OpenSSL 3.x, this is not a supported cipher, and therefore, is not supported for IBM Spectrum Symphony version 7.3.2 with Fix 601711 or later)
CAMELLIA128-SHA
IDEA-CBC-SHA (as of OpenSSL 3.x, this is not a supported cipher, and therefore, is not supported for IBM Spectrum Symphony version 7.3.2 with Fix 601711 or later)
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA384
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-SHA384
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA256

Default: AES256-GCM-SHA384

SYMPHONY_R_LOG_STDIO

Syntax: SYMPHONY_R_LOG_STDIO=YES|yes|NO|no

Description: Specifies how to handle log messages in the RClient agent process. If set to YES or yes, log messages in the RClient agent process will be printed to stdio. If set to No or no, or not set, the log file will be printed to the RClientAgent.host_name.log file in the current directory on the local host.

Note: If the log messages in the RClient agent process are printed to stdio, which are duplicated with the RClient process, there is a possibility of messages overlapping between the RClient agent process and the RClient process.

This environment variable is applicable to the open source R-integration for IBM Spectrum Symphony.

Default: By default, this environment variable is not set.

SYMPHONY_R_LOG_LEVEL

Description: Specifies the level of details for R log files. Valid values are DIABLE, ERROR, WARN, INFO, DEBUG, or ALL.

This environment variable is applicable to the open source R-integration for IBM Spectrum Symphony.

Default: INFO

Client re-connection environment variables

The following are the environment variables that you can define on your client machine to influence how the client behaves when it loses its connection to the session manager:

SOAM_RECONNECTION_RETRY_INTERVAL
SOAM_RECONNECTION_RETRY_LIMIT
SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL
SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT

How variables work together

When a client loses its connection to the session manager, it tries to reconnect to the existing session manager up to the SOAM_RECONNECTION_RETRY_LIMIT. Each re-connection attempt is SOAM_RECONNECTION_RETRY_INTERVAL seconds apart.

If the client succeeds in reconnecting to a session manager, the API attempts to refresh all sessions on the connection. If the session manager was relocated during the disconnection, any non-recoverable sessions are aborted.
If re-connection was unsuccessful, the API stops trying to reconnect to the existing session manager and attempts to locate a new session manager. It then tries to locate and connect to a new session manager up to the SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT. Each re-connection attempt is SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL seconds apart.
- If the client fails to reconnect to a session manager, the API stops trying to reconnect and throws an exception indicating that IBM Spectrum Symphony is no longer available.
- If the client succeeds in reconnecting to a session manager, the API attempts to refresh all sessions on the connection. If the session manager was relocated during the disconnection, any non-recoverable sessions are aborted.

Important: For compatibility, note that the variables CONNECTION_RETRY_INTERVAL and CONNECTION_RETRY_LIMIT are deprecated since IBM Spectrum Symphony 4.0. This means that they continue to work in IBM Spectrum Symphony 7.3.2, but you are encouraged to use the variables that replace them. If you use the deprecated variables, all previous variable values are preserved. If you use any of the new variables, any definition of the deprecated variables is ignored and all new variable defaults are used. Mixing the deprecated variables with the newer variables always results in the newer variables and their default values (if not specified) being applied.

CONNECTION_RETRY_INTERVAL

Syntax: CONNECTION_RETRY_INTERVAL=value

Description: This variable is deprecated as of IBM Spectrum Symphony 4.0 and is replaced by SOAM_RECONNECTION_RETRY_INTERVAL and SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL. If you used this variable with previous versions of IBM Spectrum Symphony, it still works the way it used to. If you need to influence the tolerance of a broken connection between your client and the system, use the following variables:

SOAM_RECONNECTION_RETRY_INTERVAL
SOAM_RECONNECTION_RETRY_LIMIT
SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL
SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT

Default: 3 (seconds)

CONNECTION_RETRY_LIMIT

Syntax: CONNECTION_RETRY_LIMIT=value

Description: This variable has been deprecated as of IBM Spectrum Symphony 4.0 and has been replaced by SOAM_RECONNECTION_RETRY_LIMIT and SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT. If you have used this variable with previous versions of IBM Spectrum Symphony, it will still work as previously. If you need to influence the tolerance of a broken connection between your client and the system, use the following variables:

SOAM_RECONNECTION_RETRY_INTERVAL
SOAM_RECONNECTION_RETRY_LIMIT
SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL
SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT

Default: 5 (times)

SOAM_RECONNECTION_RETRY_INTERVAL

Syntax: SOAM_RECONNECTION_RETRY_INTERVAL=value

Description: Specifies how long the API waits, in seconds, before the next attempt to reconnect to the last known instance of the session manager. This value is used in conjunction with SOAM_RECONNECTION_RETRY_LIMIT.

Note: On Windows, the effective minimum interval is 1 second, even if you set the value to 0.

Default: 1 (second)

SOAM_RECONNECTION_RETRY_LIMIT

Syntax: SOAM_RECONNECTION_RETRY_LIMIT=value

Description: Specifies the number of attempts made by the API to reconnect to the last known instance of the session manager. This variable is used to handle the case of a transient disconnection from the system for any type of session. When a disconnection is sensed by the API, instead of throwing an exception for a pending operation, the API attempts to automatically reconnect to the last known instance of the session manager for the specified number of times. When the API has reached the number of attempts without re-connection, it attempts to connect to a new instance of the session manager and uses SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT.

Default: 15 (times)

SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT

Syntax: SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT=value

Description: Specifies the number of attempts made by the API to reconnect to a new instance of the session manager. This variable is used to handle the case in which session manager is relocated (either restarted on the same host or failed over to a different host). This variable is used by the API to locate a new instances of the session manager after SOAM_RECONNECTION_RETRY_LIMIT is reached.

Note: On Windows, the effective minimum interval is 1 second, even if you set the value to 0.

Default: 60 (times)

SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL

Syntax: SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL=value

Description: Specifies how long the API waits, in seconds, before the next attempt to reconnect to the new instance of the session manager. This value is used in conjunction with SOAM_RELOCATED_RECONNECTION_RETRY_LIMIT.

Note: If startUpTimeout is set in the SSM section of the application profile, the interval before the next reconnection attempt to the new instance of the session manager is determined by either startUpTimeout or SOAM_RELOCATED_RECONNECTION_RETRY_INTERVAL, whichever is greater.

Default: 5 (seconds)

Client keepalive environment variables

The following are the environment variables that you can define on your client machine, enabling software-level detection when the client loses its connection to the session manager:

SOAM_ALIVE_TIME
SOAM_HEARTBEAT_INTERVAL
SOAM_HEARTBEAT_PROBES

How the keepalive variables work together

When the IBM Spectrum Symphony client exceeds the length of time that the client can remain idle without receiving any data from the session manager (specified by SOAM_ALIVE_TIME), the client begins to ping the session manager.

If the ping is successful, the client resets the idle time to 0 and waits another SOAM_ALIVE_TIME seconds.
If the ping is not successful, the client pings the session manager at the SOAM_HEARTBEAT_INTERVAL frequency.

If the client cannot reach the session manager for SOAM_HEARTBEAT_PROBES attempts at the SOAM_HEARBEAT_INTERVAL frequency, the client begins to reconnect to the session manager.

If the client fails to reconnect to the session manager, the API stops trying to reconnect and throws an exception indicating that IBM Spectrum Symphony is no longer available.
If the client succeeds in reconnecting to the session manager, the client submits or retrieves tasks as usual.

SOAM_ALIVE_TIME

Syntax: SOAM_ALIVE_TIME=value

Description: Specifies the length of time (in seconds) that the client waits without receiving data from the session manager, after which it begins to ping the session manager. When SOAM_ALIVE_TIME is not defined or set to 0, the client does not ping the session manager when the connection is idle. Specify 0 or greater, up to a maximum of 3600.

Default: 180 (seconds)

SOAM_HEARTBEAT_INTERVAL

Syntax: SOAM_HEARTBEAT_INTERVAL=value

Description: Specifies the frequency (in seconds) at which the client pings the session manager when it does not receive data from the session manager for the last SOAM_ALIVE_TIME seconds. This variable is optional and works in conjunction with SOAM_ALIVE_TIME, which must be set to 1 or more. Specify 1 or greater, up to a maximum of 3600.

Default: 10 (seconds)

SOAM_HEARTBEAT_PROBES

Syntax: SOAM_HEARTBEAT_PROBES=value

Description: Specifies the number of attempts made by the client to ping the session manager at the SOAM_HEARTBEAT_INTERVAL frequency. This variable is optional and works in conjunction with SOAM_ALIVE_TIME, which must be set to 1 or more. If the client fails to ping the session manager, the client attempts to reconnect to the session manager:

If the client fails to reconnect to a session manager, the client stops trying to reconnect and throws an exception indicating that IBM Spectrum Symphony is no longer available.
If the client succeeds in reconnecting to the session manager, the client submits or retrieves tasks as usual.

Specify 1 or greater, up to a maximum of 100.

Default: 3 (attempts)

Command line environment variables

SOAM_CLI_VIEWSESSION_COMPATIBILITY

Syntax: SOAM_CLI_VIEWSESSION_COMPATIBILITY=ON | OFF

Description: As of IBM Spectrum Symphony 5.1, the number of SIMs supported for one application can be up to 10000. However, in the output of the soamview session application_name command, the RUN column and INST column cannot support the display of such a large number. For example, 10000 will be displayed as 100*in the RUN and INST columns of the command output. Therefore, to accommodate the maximum number of SIMs supported (10000), the output format has changed. To keep the total length of one line consistent with previous versions, the ERR and CANL columns have each been reduced by one character in width.

To maintain backward compatibility, this environment variable defines whether the soamview session application_name command displays output in the previous format (prior to IBM Spectrum Symphony 5.1) or in the new format. If the environment variable is set to ON (case insensitive), the output will be displayed in the previous format; otherwise, the output will be displayed in the new format.

Default: OFF

TCP connection environment variables

You can set the following environment variables on your client machine to define the characteristics of the TCP connection:

PLATCOMMDRV_TCP_KEEPALIVE_TIME
PLATCOMMDRV_TCP_NODELAY
PLATCOMMDRV_TCP_RECV_BUFFER_SIZE
PLATCOMMDRV_TCP_SEND_BUFFER_SIZE

PLATCOMMDRV_TCP_KEEPALIVE_TIME

Syntax: PLATCOMMDRV_TCP_KEEPALIVE_TIME=seconds

Description: Specifies the maximum time in seconds the system can take to detect a broken connection to and from IBM Spectrum Symphony processes originating from the shell where the variable is defined. Specify a numeric value of 180 seconds (3 minutes) or more. Values less than 300 seconds (5 minutes) are not recommended.

Valid values: 180 to 7200

Default: 180 (seconds)

PLATCOMMDRV_TCP_NODELAY

Syntax: PLATCOMMDRV_TCP_NODELAY=1 | 0

Description: Enables or disables TCP_NODELAY for TCP sockets. When TCP_NODELAY is enabled, the Nagle algorithm is disabled and vice-versa. Specify 1 to enable TCP_NODELAY and disable Nagle, 0 to disable TCP_NODELAY and enable Nagle. When the Nagle algorithm is enabled, small outgoing messages are aggregated, adding more data to the TCP buffer until a full-size packet can be sent.

Default: 1 (enabled)

PLATCOMMDRV_TCP_RECV_BUFFER_SIZE

Syntax: PLATCOMMDRV_TCP_RECV_BUFFER_SIZE=bytes

Description: Specifies the size for the TCP receive buffer for each IBM Spectrum Symphony connection. Specify a numeric value greater than or equal to 65535 bytes (64KB).

Default: 65535 (64KB)

PLATCOMMDRV_TCP_SEND_BUFFER_SIZE

Syntax: PLATCOMMDRV_TCP_SEND_BUFFER_SIZE=bytes

Description: Specifies the size for the TCP send buffer for each IBM Spectrum Symphony connection. Specify a numeric value greater than or equal to 65535 bytes (64KB).

Default: 65535 (64KB)

System-defined environment variables

Environment variable	Description
SOAM_BINDIR	Directory where the IBM Spectrum Symphony middleware commands are installed
SOAM_HOME	Directory where the IBM Spectrum Symphony middleware is installed
SOAM_SERVER_DIR	Directory where the IBM Spectrum Symphony middleware daemons are installed