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):

The system property set programmatically using java.lang.System.setProperties()
The system property set using the -D option of the java command
The system property set using a Properties class
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
FTP properties
Connection 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.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 might 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()` or `AS400.setMustUseSockets(true)` has been performed on the object.
com.ibm.as400.access.ProgramCall.threadSafe	Specifies whether ProgramCalls might 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()` or `AS400.setMustUseSockets(true)` has been performed on the object.

FTP properties

FTP property	Description
com.ibm.as400.access.FTP.reuseSocket	Specifies whether the socket is reused for multiple file transfers (through a single FTP instance), when in "active" mode. If `true`, the socket is reused. If `false`, a new socket is created for each file transfer. This property is ignored for a given FTP object if `FTP.setReuseSocket()` has been performed on the object.

Connection properties

Connection property	Description
com.ibm.as400.access.AS400.guiAvailable	Indicates whether the current environment has GUI capability. If `true`, prompting may occur during signon to display error conditions, to prompt for additional information, or to prompt for change password. If `false`, error conditions or missing information will result in exceptions. Applications that are running as IBM i applications or want to control the signon user interface may want to run with prompting mode set to `false`. The default is `true`.
com.ibm.as400.access.AS400.mustAddLanguageLibrary	Indicates whether AS400 objects should attempt to add the appropriate secondary language library to the library list when running on the system. Setting the language library will ensure that any system error messages that are returned, will be returned in the appropriate national language for the client locale. If `true`, AS400 objects will attempt to add the secondary language library to the library list when running on the system. If `false`, no attempt is made by AS400 objects to add the secondary language library to the library list. The default is `false`.
com.ibm.as400.access.AS400.mustUseNetSockets	Specifies whether AS400 objects should use Internet domain sockets only. When your Java program runs on the system, some IBM Toolbox for Java classes create UNIX domain socket connections. If `true`, only Internet domain sockets will be used by AS400 objects. If `false`, AS400 objects may use UNIX domain socket connections in addition to Internet domain sockets. The default is `false`.
com.ibm.as400.access.AS400.mustUseSockets	Specifies whether AS400 objects should use sockets. When your Java program runs on the system, some IBM Toolbox for Java classes access data by calling an API instead of making a socket call to the system. There are minor differences in the behavior of the classes when API calls are used instead of socket calls. If your program is affected by these differences you can force the classes to use socket calls instead of API calls by setting this property to `true`. The default is `false`.
com.ibm.as400.access.AS400.mustUseSuppliedProfile	Specifies whether AS400 objects should use a supplied profile only. When your Java program runs on the system, the information from the currently signed-on user profile (*CURRENT) can be used. If `true`, a user profile must be supplied. If `false`, AS400 objects retrieves the current user profile information if a user profile is not supplied. . The default is `false`.
com.ibm.as400.access.AS400.signonHandler	Specifies the default signon handler. This property is ignored for a given AS400 object if `AS400.setSignonHandler()` has been performed on the object, or if `AS400.setDefaultSignonHandler()` has been called.
com.ibm.as400.access.AS400.threadUsed	Specifies whether AS400 objects use threads in communication with the host servers. Letting the IBM Toolbox for Java use threads may be beneficial to performance; turning threads off may be necessary if your application needs to be compliant with the Enterprise Java Beans specification. The default is `true`.