IBM Toolbox for Java: System properties

## System properties

You can specify system properties to configure various aspects of the IBM Toolbox for Java. For example, you can use system properties to define a proxy server or a level of tracing. System properties are useful for convenient runtime configuration without needing to recompile code. System properties work like environment variables in that when you change a system property during runtime, the change is generally not reflected until the next time you run the application.

There are several ways that you can set system properties:

- Using the java.lang.System.setProperties() method

  You can set system properties programmatically by using the java.lang.System.setProperties() method.

  For example, the following code sets the `com.ibm.as400.access.AS400.proxyServer` property to `hqoffice`:

      Properties systemProperties = System.getProperties();
         systemProperties.put ("com.ibm.as400.access.AS400.proxyServer", "hqoffice");
         System.setProperties (systemProperties);

- Using the `-D` option of the `java` command

  Many environments allow you to set system properties when running applications from a command line by using the `-D` option of the `java` command.

  For example, the following program runs the application called Inventory with the `com.ibm.as400.access.AS400.proxyServer` property set to `hqoffice`:

         java -Dcom.ibm.as400.access.AS400.proxyServer=hqoffice Inventory

- Using a jt400.properties file

  In some environments, it may be inconvenient to instruct all users to set their own system properties. As an alternative, you can specify IBM Toolbox for Java system properties in a file called jt400.properties that is searched for as if it is part of the com.ibm.as400.access package. In other words, place the jt400.properties file in a com/ibm/as400/access directory pointed to by the classpath.

  For example, set the `com.ibm.as400.access.AS400.proxyServer` property to `hqoffice` by inserting the following line into the jt400.properties file:

         com.ibm.as400.access.AS400.proxyServer=hqoffice

  The backslash character (\) functions as an escape character in properties files. Specify a literal backslash character by using two backslashes (\\).

  Modify this sample of a jt400.properties file for your environment.

- Using a Properties class

  Some browsers do not load properties files without explicitly changing security settings. However, most browsers do allow properties in .class files, so IBM Toolbox for Java system properties can also be specified by a class called com.ibm.as400.access.Properties which extends java.util.Properties.

  For example, to set the `com.ibm.as400.access.AS400.proxyServer` property to `hqoffice`, use the following Java code:

         package com.ibm.as400.access;

         public class Properties
         extends java.util.Properties
         {
            public Properties ()
            {
               put ("com.ibm.as400.access.AS400.proxyServer", "hqoffice");
            }
         }

  Modify and compile this sample of a Properties.java source file for your environment.

If an IBM Toolbox for Java system property is set using more than one of the mechanisms described above, then the precedence is as follows (in order of decreasing precedence):

1. The system property set programmatically using `java.lang.System.setProperties()`
2. The system property set using the `-D` option of the `java` command
3. The system property set using a Properties class
4. The system property set using a jt400.properties file

IBM Toolbox for Java supports the following system properties:

- Proxy server properties
- Trace properties
- CommandCall/ProgramCall properties

### Proxy server properties

Proxy server property | Description
--- | ---
com.ibm.as400.access.AS400.proxyServer | Specifies the proxy server host name and port number, using the format:
       hostName:portNumber
The port number is optional.
com.ibm.as400.access.SecureAS400.proxyEncryptionMode | Specifies which portion of the proxy data flow is encrypted by using SSL. Valid values are: 1 = Proxy client to proxy server 2 = Proxy server to IBM i system 3 = Proxy client to proxy server and proxy server to IBM i system
com.ibm.as400.access.TunnelProxyServer.clientCleanupInterval | Specifies how often, in seconds, the proxy server looks for idle connections. The proxy server starts a thread to look for clients that are no longer communicating. Use this property to set how often the thread looks for idle connections.
com.ibm.as400.access.TunnelProxyServer.clientLifetime | Specifies how long, in seconds, a client can be idle before the proxy server removes references to the objects so the JVM can garbage collect them. The proxy server starts a thread to look for clients that are no longer communicating. Use this property to set how long a client can be idle before performing garbage collection on it.

### Trace properties

Trace property | Description
--- | ---
com.ibm.as400.access.Trace.category | Specifies which trace categories to enable. This is a comma-delimited list containing any combination of trace categories. The complete list of trace categories is defined in the Trace class.
com.ibm.as400.access.Trace.file | Specifies the file to which trace output is written. The default is to write trace output to System.out.
com.ibm.as400.access.ServerTrace.JDBC | Specifies which trace categories to start on the JDBC server job. For information about supported values, see the JDBC server trace property.

### CommandCall/ProgramCall properties

CommandCall/ProgramCall property | Description
--- | ---
com.ibm.as400.access.CommandCall.threadSafe | Specifies whether CommandCalls should be assumed to be thread-safe. If `true`, all CommandCalls are assumed to be thread-safe. If `false`, all CommandCalls are assumed to be non-thread-safe. This property is ignored for a given CommandCall object if either `CommandCall.setThreadSafe(true/false)` or `AS400.setMustUseSockets(true)` has been performed on the object.
com.ibm.as400.access.ProgramCall.threadSafe | Specifies whether ProgramCalls should be assumed to be thread-safe. If `true`, all ProgramCalls are assumed to be thread-safe. If `false`, all ProgramCalls are assumed to be non-thread-safe. This property is ignored for a given ProgramCall object if either `ProgramCall.setThreadSafe(true/false)` or `AS400.setMustUseSockets(true)` has been performed on the object.