Next Previous Up Contents
Next: JDBC Configuration
Up: Invocation
Previous: Java Flags

### 3.3 System Properties

System properties are a way of getting information into the Java runtime - they are a bit like environment variables. There are two ways to set them when using STILTS: either on the command line using arguments of the form `-Dname=value` (see Section 3.2) or in a file in your home directory named `.starjava.properties`, in the form of a `name=value` line. Thus submitting the flag

       -Dvotable.strict=false

on the command line is equivalent to having the following in your `.starjava.properties` file:

       #  Force strict interpretation of the VOTable standard.
       votable.strict=false

The following system properties have special significance to STILTS:

`http.proxyHost`
  Can be used to force HTTP access to go via a named proxy; may be required if you are attempting access to remote data or services from behind a firewall configured to block direct HTTP connections. See java documentation for this property for more details.
`java.awt.headless`
  May need to be set to "`true`" if running the plotting tasks on a headless server. You only need to worry about this if you see error messages complaining about headlessness.
`java.io.tmpdir`
  The directory in which STILTS will write any temporary files it needs. This defaults to the system temporary directory (e.g. `/tmp` on Unix), so if working with large unmapped (e.g. CSV) tables on a machine with limited space on the default disk, it may be necessary to change it.
`java.util.concurrent.ForkJoinPool.common.parallelism`
  Controls the level of parallelisation done by certain processing, currently mainly visualisation. By default it is typically set to one less than the number of processing cores on the current machine. To inhibit parallelisation (e.g. if you suspect that the parallel output is giving different results to sequential processing) you can set this to 1.
`jdbc.drivers`
  Can be set to a (colon-separated) list of JDBC driver classes using which SQL databases can be accessed (see Section 3.4).
`jel.classes`
  Can be set to a (colon-separated) list of classes containing static methods which define user-provided functions for synthetic columns or subsets. (see Section 10.9.3).
`mark.workaround`
  If set to "true", this will work around a bug in the `mark()`/`reset()` methods of some java `InputStream` classes. These are rather common, including in Sun's J2SE system libraries. Use this if you are seeing errors that say something like "`Resetting to invalid mark`". Currently defaults to "false".
`service.maxparallel`
  Raises the maximum number of concurrent queries that may be made during a multi-cone operation. You should only increase this value with great care since you risk overloading servers and becoming unpopular with data centres. As a rule, you should only increase this value if you have obtained permission from the data centres whose services on which you will be using the increased parallelism.
`auth.username`
`auth.password`
  If these are both set, they will provide username and password for accessing authenticated resources. Any time the application is refused access to an HTTP connection and knows how to try to authenticate, it will try again using these credentials. In each case the values may be either the username/password itself, or of the form "`@<filename>`", in which case the value is read from the first line of the named file. This replaces the normal behaviour of asking for a username and password on the console; see the section on Authentication for more details. Since this setting will pass the username and password information to any protected resource without checking it is the intended destination, this can potentially leak secret information to third parties, so these properties should be set with care.
`auth.schemes`
  Configures the list of authentication schemes that will be considered when connecting to services issuing a WWW-Authenticate challenge. A comma-separated list of scheme names or `AuthScheme` implementation classnames may be provided.
`startable.readers`
  Can be set to a (colon-separated) list of custom table format input handler classes (see SUN/252). Each class must implement the `uk.ac.starlink.table.TableBuilder` interface, and must have a no-arg constructor. The readers thus named will be available alongside the standard ones listed in Section 5.1.1.
`startable.schemes`
  Can be set to a (colon-separated) list of custom table scheme handler classes. Each class must implement the `uk.ac.starlink.table.TableScheme` interface, and must have a no-arg constructor. The schemes thus named will be available alongside the standard ones listed in Section 5.3.
`startable.storage`
  Can be set to determine the default storage policy. Setting it to "`disk`" has basically the same effect as supplying the "`-disk`" argument on the command line (see Section 2.1). Other possible values are "`adaptive`", "`memory`", "`sideways`" and "`discard`"; see SUN/252. The default is "`adaptive`", which means storing smaller tables in memory, and larger ones on disk.
`startable.unmap`
  Determines whether and how unmapping of memory mapped buffers is done. Possible values are "`sun`" (the default), "`cleaner`", "`unsafe`" or "`none`". In most cases you are advised to leave this alone, but in the event of unmapping-related JVM crashes (not expected!), setting it to `none` may help.
`startable.writers`
  Can be set to a (colon-separated) list of custom table format output handler classes (see SUN/252). Each class must implement the `uk.ac.starlink.table.StarTableWriter` interface, and must have a no-arg constructor. The writers thus named will be available alongside the standard ones listed in Section 5.1.2.
`votable.namespacing`
  Determines how namespacing is handled in input VOTable documents. Known values are "`none`" (no namespacing, xmlns declarations in VOTable document will probably confuse parser), "`lax`" (anything that looks like it is probably a VOTable element will be treated as a VOTable element) and "`strict`" (VOTable elements must be properly declared in one of the correct VOTable namespaces). May also be set to the classname of a `uk.ac.starlink.votable.Namespacing` implementation. The default is "`lax`".
`votable.strict`
  Controls the behaviour when encountering a VOTable `FIELD` or `PARAM` element with a `datatype` attribute of `char`/`unicodeChar`, and no `arraysize` attribute. The VOTable standard says this indicates a single character, but some VOTables omit arraysize specification by accident when they intend `arraysize="*"`. If `votable.strict` is set `true`, a missing arraysize will be interpreted as meaning a single character, and if `false`, it will be interpreted as a variable-length array of characters (a string). The default is `true`.
`votable.version`
  Selects the version of the VOTable standard which output VOTables will conform to by default. May take the values "`1.0`", "`1.1`", "`1.2`", "`1.3`" or "`1.4`". By default, version 1.4 VOTables are written.

Next Previous Up Contents
Next: JDBC Configuration
Up: Invocation
Previous: Java Flags

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk