Symphony client environment variables

This topic describes the environment variables that the Symphony client uses.

API_CALL_TIMEOUT

Syntax

API_CALL_TIMEOUT=value

Description

Defines the number of seconds the Symphony API waits to complete a connection 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 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.

Do not specify zero (0) because then the API never waits and so never connects.

Default

-1 (never times out)

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.

Default

300 (seconds)

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_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; e.g., 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.

Default

Not applicable

Client reconnection environment variables

The following are the four 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 reconnection 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 reconnection 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 reconnection 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 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:

Compatibility Note: The variables CONNECTION_RETRY_INTERVAL and CONNECTION_RETRY_LIMIT have been deprecated as of Symphony 4.0. This means that they continue to work in Symphony 5.1 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 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 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 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 Symphony it will still work in 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

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 reconnection, 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.

Default

5 (seconds)

Command line environment variables

SOAM_CLI_VIEWSESSION_COMPATIBILITY

Syntax

SOAM_CLI_VIEWSESSION_COMPATIBILITY=ON | OFF

Description

As of 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 1 character in width.

To keep backward compatibility, this environment variable defines whether the "soamview session application_name" command displays output in the previous format (prior to 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 Symphony processes originating from the shell where the variable is defined.

Specify a numeric value of 180 seconds (3 minutes) or more. Values lower than 300 seconds (5 minutes) are not recommended.

Restriction:

This variable is ignored for installations on Solaris, which does not support this TCP/IP setting on a per-socket basis.

Default

Connections by default use the operating system-dependable, system-wide TCP keep alive setting, which for most operating systems, is 7200 seconds, or 2 hours.

PLATCOMMDRV_TCP_NODELAY

Syntax

PLATCOMMDRV_TCP_NODELAY=1 | 0

Description

Enables or disables the Nagle algorithm for TCP sockets.

Specify 1 to enable, 0 to disable.

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 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 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 Symphony middleware commands are installed

SOAM_HOME

Directory where the Symphony middleware is installed

SOAM_SERVER_DIR

Directory where the Symphony middleware daemons are installed