Client Parameters

Edit online

The Universal Messaging client API supports a variety of parameters that you can use to change the behavior of the client.

You specify the parameters in the command line of any Universal Messaging client application by prefacing the name of the parameter by -D. For example, to set the value of the parameter LOGLEVEL to 4 for a given client application, specify -DLOGLEVEL=4 as a parameter in the command line of the client application.

The following list describes the parameters and their typical values. All parameters are optional, unless otherwise stated.

CAKEYSTORE (deprecated)
Shorthand for javax.net.ssl.trustStore.
CAKEYSTOREPASSWD (deprecated)
Shorthand for javax.net.ssl.trustStorePassword.
CKEYSTORE (deprecated)
Shorthand for javax.net.ssl.keyStore.
CKEYSTOREPASSWD (deprecated)
Shorthand for javax.net.ssl.keyStorePassword.
com.softwareag.um.authentication.maxHeaderCount
Limits the number of headers that the Universal Messaging client and the Universal Messaging server exchange during protocol negotiation. The default value is 0. Do not change the value of the parameter because the supported Universal Messaging client and server versions do not require exchanging headers.
com.softwareag.um.client.connection.reader.daemon
Specifies whether the UM-Connection-Reader thread is an ordinary thread or a daemon thread. Universal Messaging client system property. Valid values are:
  • true - The thread is daemon.
  • false (default) - The thread is non-daemon.

Each nSession has a UM-Connection-Reader thread that synchronously reads from the underlying transport. This thread is set as a non-daemon thread by default to ensure that on program exit, or Main thread exit, all call stacks are completed.

Important: Setting the UM-Connection-Reader thread as a daemon thread might cause your program to prematurely exit when all other non-daemon threads exit.

If you do not specify this system property, the value is extracted from the session attributes. Implicitly, the session attributes have the value set to false. You can change the value using the Universal Messaging client API.

com.softwareag.um.client.MaxReconnectInterval

Specifies the time period in seconds that a Universal Messaging client waits between retry attempts to reconnect to a Universal Messaging server. Use the parameter if the ReconnectImmediate flag for a client session is set to false. When the ReconnectImmediate flag is false, the reconnection interval increases after each retry attempt. You can use this parameter to limit the time period between the retry attempts so that it does not exceed the parameter value. The minimum valid value is 200 milliseconds and a maximum valid value is not defined. The default is 30 seconds.

Note: Because the reconnection interval has a random factor, the maximum time period between retry attempts might be longer than the time you specify in the parameter.
com.softwareag.um.client.missed_keep_alives

Specifies the number of missed server-side keep-alive intervals before the client closes a connection. The default value is 1. A value of 1 means that if the client misses a single keep alive sent by the server, the client closes the session. To disable server-side keep-alive checking, set the property to 0 (zero). Note that this property is consulted only once upon JVM startup.

com.softwareag.um.client.realmnode.cleanup

Specifies whether to clean up internally created nRealmNode objects when an nRealmNode is closed, if no other references to these objects exist. When you create an nRealmNode object, it might create more nRealmNodes internally to obtain information from referenced nodes, for example, the realm nodes in a cluster. Valid values are:

  • true (default) - When closing an nRealmNode, the server cleans up internal nRealmNodes if the nodes are not referenced by any other nRealmNode.
  • false - The server never cleans up internal nRealmNodes. The internal nRealmNodes nodes are reused by all subsequently created nRealmNodes.
com.softwareag.um.client.ssl.certificate_alias
The alias of the certificate in the client keystore that is sent to the server if client certificate authentication is required. Universal Messaging client system property. For more information about using the property, see .
com.softwareag.um.client.ssl.enabled_ciphers
Comma-separated list of ciphers from which the client is allowed to choose for secure communication. Universal Messaging client system property. For more information about using the property, see Using the Universal Messaging Client System Properties for Secure Communication.
com.softwareag.um.client.follow_the_master
Used when creating a session to realms in a cluster. Specifies whether the session always connects to the master realm. The default value is false.
com.softwareag.um.client.IdleThreadTimeout
Specifies the time in milliseconds that a thread can be idle before the thread pool closes it. Valid values are between 10000 and 300000. The default value is 60000.
com.softwareag.um.client.network_io_buffer_size
Specifies the receive and send buffer size in bytes when a socket is created. The larger the value of this property, the larger the buffers that the operating system needs to allocate. The default value is 1310720.
com.softwareag.um.client.PendingTaskErrorThreshold
The threshold at which the client starts to warn about the number of pending tasks on the server. When the number of pending tasks is above the threshold, the server logs an ERROR message. When the server does not find available threads, it logs a message that the thread pool is exhausted. Valid values are between 100 and 100000. The default value is 1000.
com.softwareag.um.client.PendingTaskWarningThreshold
The threshold at which the client starts to warn about the number of pending tasks on the server. When the number of pending tasks is below the threshold, but over 100, the server logs a WARNING message. When the server does not find available threads, it logs a message that the thread pool is exhausted. Valid values are between 100 and 100000. The default value is 100.
com.softwareag.um.client.retry_reconnect_on_security_exception
Specifies whether the session attempts to reconnect to the server after a security exception due to failed realm ACL permissions or authentication. Valid values are:
  • true (default) - The session makes a reconnection attempt.
  • false - The session closes.
com.softwareag.um.client.session_disable_reconnect
Specifies whether the session attempts to reconnect to the realm server after disconnecting. If the property is set to true, the session does not make attempts to reconnect. The default value is false.
com.softwareag.um.client.SharedThreadPoolMaxSize
Specifies the maximum size of the shared thread pool for the client session. The default is 5 threads.
com.softwareag.um.client.SlowMovingTasksTimeout
The time in milliseconds before a task is deemed as slow-moving. Valid values are between 1000 and 30000. The default value is 5000.
com.softwareag.um.client.ssl.keystore_password
The password for the client keystore. Universal Messaging client system property. For more information about using the property, see Using the Universal Messaging Client System Properties for Secure Communication.
com.softwareag.um.client.ssl.truststore_password
The password for the CA keystore. Universal Messaging client system property. For more information about using the property, see Using the Universal Messaging Client System Properties for Secure Communication.
com.softwareag.um.client.ssl.truststore_path
The CA keystore file location. Universal Messaging client system property. For more information about using the property, see Using the Universal Messaging Client System Properties for Secure Communication.
com.softwareag.um.client.ssl.ssl_protocol
The protocol that is used for secure communication. Universal Messaging client system property. For more information about using the property, see Using the Universal Messaging Client System Properties for Secure Communication.
com.softwareag.um.client.StalledTaskWarningTime
The time in milliseconds before reporting a stalled task. The system writes the information at the WARNING log level and generates a thread dump. When you change this configuration, the thread pool monitor interval is updated to monitor at the same time interval as the value you specify for this property. Valid values are between 10000 and 300000. The default value is 60000.
com.softwareag.um.client.useSharedThreadPool
Enables usage of a shared thread pool for processing incoming nConsumeEvent events for each client session. Values are true or false (default). By default, each client session creates and uses a separate thread pool for processing received nConsumeEvent events. When this system property is set to true, all client sessions will use a shared thread pool. Using a shared thread pool for all client sessions may have a performance impact depending on the size of the common thread pool and the number of client sessions.
Note: When each client session uses a separate thread pool, closing the session interrupts any event listener threads that are blocked during processing. When all client sessions share a thread pool, closing a session does not interrupt any event listener threads that are blocked during processing. Thus, the blocked event listener does not release a shared thread after closing the client session. This behavior impacts the processing of incoming events, because the shared pool will not have available threads. IBM recommends that you enable the shared pool for all client sessions only if the event listener of the client application ensures that the processing of the events is fast and graceful.
com.softwareag.um.client.write_handler
Specifies the Universal Messaging JVM-wide socket write handling. Valid values are:
  • standard (default) - enables a peak write handler, which is the most optimized mode for both latency and throughput. The handler writes events directly to the socket layer until a certain number of socket writes per second occur, at which point the handler switches to queued write handing until the rate of messages decreases.
  • direct - enables a write handler that writes events directly to the socket layer and never queues events. This mode can have an impact on latency if the throughput is higher than the capacity of the socket layer.
  • queue - enables a write handler that never writes directly to the socket layer, but pushes all events into an in-memory queue. The events are then written to the socket layer by another thread in batches, which increases latency. However, if many events are being written, this mode prevents further spikes in latency.
DisplayCurrentThreadID
Specifies whether client-side thread ID logging is enabled. Valid values are true or false. The default value is true.

For more information about configuring client-side logging, see Client-Side Logging.

HPROXY (deprecated)

Shorthand for setting an http and https proxy.

HPROXY is deprecated. Use the standard Java http and https proxy properties instead. For more information about the Java proxy properties, see the Oracle documentation.

HPROXY sets http.proxySet and https.proxySet to true, http.proxyHost and https.proxyHost to the provided proxy host, and http.proxyPort and https.proxyPort to the provided proxy port.

The following usage notes apply to HPROXY:

  • HPROXY does not set http.nonProxyHosts and https.nonProxyHosts.
  • HPROXY sets the same proxy for http and https.
  • HPROXY overwrites the existing JVM properties.
http.proxyHost
Sets the proxy host name to use.
http.proxyPort
Sets the proxy port to use.
http.proxySet
Set to true if the URL handler is to use a proxy.
javax.net.debug
Useful to debug SSL issues.
jdk.tls.client.protocols
Specifies one or more (comma-separated) SSL protocols that the client is allowed to use. If an attempt is made to use any other protocol on the client, an error will be raised. Refer also to the option SSLClientProtocol, which can also influence the SSL protocol to be used.

This option is only available on the Oracle® JVM.

LOG_FRAMEWORK
Specifies a third-party logging framework to use. Can be set to LOGBACK or LOG4J2. The default is fLogger.
LOGFILE
Specifies a client log file. The default value is System.out.
LOGLEVEL
Specifies the current log level to use. The default value is 7 (OFF).
LOGSIZE
Specified in bytes before the log file is rolled. The default value is 100000.
SSLClientProtocol
Sets the default SSL Protocol to use.

If the option jdk.tls.client.protocols is defined, SSLClientProtocol must be one of the protocols defined in jdk.tls.client.protocols.

If SSLClientProtocol is not supplied, then client SSL communication will attempt to use one of the protocols defined in jdk.tls.client.protocols. If jdk.tls.client.protocols is not defined, then an attempt will be made to use the JVM default protocol, or TLS when that is not possible.

user.name
Used to override the current username without coding it. The default value is "Signed on name".