JESS Client Command-Line (v3)

(Version v3.0.0)

This page describes in detail how to use the JESS Client's command-line. For APIs, please see …

[Some sections of this page may be incomplete]

The JESS Client communicates with the JESS server using a proprietary set of protocols. Users usually do not need the details of the protocols. Instead, they can use the Client Command-line and APIs to carry out all transactions. This document provides details of the command-line interface.

The main user functions of the JESS Client is accessible through the command-line arguments. They can be used either as an external program, e.g. by executing java -jar jess_client_v3.jar [OPTIONS], or by calling the public static void jess.client.Main.main(String [] args) function.

The full command-line options of the JESS Client are as below.

usage: java -jar jess_client_v3.jar [OPTIONS]
 -args <Arguments>           Used with -submit RA_*. Program arguments required
                             to run rtrace or rpict.
 -cancel <job_id>            Cancel a previously submitted job using the job id.
                             If no id is given, cancel all pending jobs
 -case <case_ids>            Additional option to use with -retrieve for
                             specifying a list of simulation cases (ids
                             separated by ';') to download. If this is given,
                             the client will download the full results of the
                             specified cases.
 -cfg <config_file>          Client configuration file. If option is not
                             specified, the default config file is ./client.cfg.
                             The file is created if not present.
 -checkin <session_key>      Check validity of the currrent/specified session.
                             The session_key argument is optional. If not
                             provided, the client will check in with the current
                             stored session key.
 -connect <server[:port]>    Connect to a new server or check connection status
                             of the current server. The server:port argument is
                             optional. If not provided, the client will use the
                             current server address in client.cfg.
 -dbonly                     Use DesignBuilder specific actions and output;
                             effect only with -version, -checkin, -retrieve and
                             -job
 -exitcode <code>            Delay 3 second and return the specified exit code.
                             This argument is for testing and debugging only.
 -header <Header file>       Used with -submit DS_*. Header file required to run
                             DaySim.
 -help                       print this message
 -in <Input file>            Used with -submit RA_*. Input file (e.g. the sensor
                             file or view file) required to run rtrace or rpict.
 -job <job_folder>           Specify at least -job and -type to submit a job to
                             the server. The argument of -job specifies the
                             folder contains job files. Content of the whole
                             folder will be uploaded to the server. -job implies
                             -nogui.
 -log <log_config_file>      Specify where to find the logger's configuration
                             file. Default is ./log4j.cfg. If the config file
                             cannot be found, logger will write to both console
                             and client.err.
 -logon <user:pwd>           Log on to the JESS server with the specified
                             credentials. The user:pwd argument is optional. If
                             not given, the client shows the logon dialog.
 -nogui                      Disallow the GUI mode. GUI is enabled by default.
                             However, if -nogui is given, commands such as
                             -checkin and -logon will not show pop up dialog.
 -oct <Octree file>          Used with -submit RA_*. Octree file (frozen unless
                             submitted with the required .rads) required to run
                             rtrace or rpict.
 -out <Output file>          Used with -submit RA_*. Output file for data
                             produced by rtrace or rpict.
 -output <output_dir>        Output folder to store results
 -ref <job_id>               Job id of the submission that contains full project
                             data
 -result <result_type>       Result to retrieve. Options are SUMMARY_TABLE
                             (default), RESULTS, ALL
 -retrieve <job_id>          Retrieve once the result of the given job if job_id
                             is specified. If no id is given, the client
                             continuously polls the pending jobs until they all
                             finish.
 -submit <job_type>          Submit a job of certain type. Available options are
                             JE_*, EP_*, RA_*, DS_* and OF_*. The job folder to
                             submit is passed in as a program argument. Client
                             exits once job is submitted without waiting for
                             results.
 -subset <subset_type>       Subset type. Options are ALL (default), RANDOM,
                             LHS_RANDOM, LIST, LIST_FILE
 -subset_param <parameter>   Subset parameter. For RANDOM/LHS_RANDOM, it is
                             sample size. For LIST/LIST_FILE it is a string
                             containing jobs or a filename
 -type <job_type>            Specify the job type to submit. Available options
                             are JEPLUS_PROJECT, JEPLUS_JOBSET, STD_SINGLE_JOB,
                             and SPLIT_SINGLE_JOB
 -update                     Try retrieve the update of this client from server
 -version                    Get version string of this client

• -nogui - Suppress GUI when running in a terminal or on a server where GUI is not supported. This may be overridden by -dbonly where GUI is always allowed.

• -dbonly - Apart from allowing GUI, it prefixes “JOB MESSAGE: ” to any key console output.

• -cfg - Specifies the configuration file to use with this client. The client configuration file (client.cfg by default) contains server and session information.

• -log - Specifies the logger configuration file to use with this client. Editing the logger configuration file (normally log4j.cfg) can enable logs on console and change log file names.

• -exitcode - For debug only. This switch makes the client exit with a certain exit code

• -version - Displays the version string of this client

• -help - Displays the help text as shown above

• -connect - Solo command (must be used alone) to connect to a new server (if server address and port number is given) or to check the status of the current connection. Example: java -jar JESS_Client.jar -connect jess.ensims.com:2992

• -update - Solo command to retrieve update package from the JESS server. Example: java -jar JESS_Client.jar -update

• -checkin - Solo command to check-in with the current server connection with either the existing session key or a new one. Example: java -jar JESS_Client.jar -checkin abcabcababcabcababcabcababcabcab.

• -logon - Solo command to log-on to the current server with the given credentials or prompting for new credentials. Example: java -jar JESS_Client.jar -logon myname:mypassword

• -job & -type - Must be used together to submit a job and wait for results

• -submit - Submit a job without waiting for results

• -retrieve - Retrieves results of a specified job (must have been submitted by this client) or all the jobs.

• -cancel - Cancels a specified job or all jobs

• -output - Specifies where to put the retrieved results. Use with -job, -submit or -retrieve

• -result - Specifies how much results to retrieve from the server. Affects only jEPlus project type of jobs

• -case - Used with -retrieve to download specific cases from the server

• -subset - Specifies the subset type of a jEPlus project job

• -subset_param - Specifies extra information used to define the project subset. Use with -subset

• -ref - Specifies the job ID of the project files uploaded previously. Used with -type JEPLUS_JOB_SET, -submit JE, or -submit JE_JSON

• -in - Input file for feeding the Radiance programs' input stream or Daysim's sensor file. Use with RA_* and DS_* jobs

• -out - Output file suffix for capturing the Radiance programs' output stream. Use with RA_* jobs

• -args - Radiance programs arguments. Use with RA_* jobs

• -oct - Octree file for Radiance. Use with RA_* jobs

• -header - Daysim's header file. Use with DS_* jobs

Check the version number of this Client. This can also be used for checking if Java is working properly.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -version
v3.0.0

Usage 1 - test the connection with the current server

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -connect
JESS on server2.ensims.com is READY, with 0 batches in process, 0 batches in queue

Usage 2 - make a new connection to a specified server

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -connect jess.ensims.com
JESS on jess.ensims.com is READY, with 0 batches in process, 0 batches in queue

Check and retrieve update for this client from the JESS server

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -update
Client is up-to-date

The JESS Client uses session tokens to identify authenticated sessions with servers. The session token (session key) can be shared between clients, even if they are on different computers. However, since any usage occurred in the session are counted towards the user who created the session, you should keep the session keys safe and private.

To test the validity of the current session key as stored in client.cfg, do this:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -checkin
Session is accepted.

If the session is invalid, a dialog window will be shown to let user login again. If user interaction is not possible, disable the dialogue window with -nogui, an error message will read as this:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -checkin
User did not provide login credentials.

To switch to a different session that has already been set up, you can specified the session key through the argument. Part of the session is obscured in this exmaple.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -checkin 512abeaed......9e64cb6502e1
Session is accepted.

The -logon command without argument prompts a dialogue window for you to set up server connection, including selecting JESS server and changing user credentials etc.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -logon

You may also provide user credentials through the optional argument, in the form of username:password pair, such as below:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -logon abc:1234
Logged in successfully with session: bb3c72a2d28cf......eab34f6ca4

If the credentials are incorrect, the client returns:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -logon abc:1234
Invalid user credentials. Please try again.

Submitting a job to JESS is a little more complicated than other operations. The JESS Client supports four types of jobs at present - they are EnergyPlus, jEPlus, Radiance and Daysim jobs. Each job type has its own identifiers and requires different command-line options.

The legacy command of submitting a job is using the -job and -type arguments. The client will wait for results to come back after submission. This method support STD_SINGLE_JOB, SPLIT_SINGLE_JOB, JEPLUS_PROJECT and JEPLUS_JOB_SET job types, specified with -type. The argument of -job is the folder containing the job files to submit.

Below is an example for submitting a single E+ job. The folder (std_job_v72/ in the example) contains one IDF file and one EPW file. Results will be collected and stored in the folder named output/ next to the project folder.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -job std_job_v72 -type STD_SINGLE_JOB -output ../output
user@K890:~/JESS_Client_v3.0.0$ 

Below is an example for submitting a single E+ job to execute using the run-period split acceleration method. The folder (std_single_v81/ in the example) also contains one IDF file and one EPW file. The merged results will be collected and stored in the folder named output/ next to the project folder.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -job std_signle_v81 -type SPLIT_SINGLE_JOB -output ../output
user@K890:~/JESS_Client_v3.0.0$ 

Here are some examples for submitting jEPlus project jobs. A number of arguments can be used with this job type (and the JEPLUS_JOB_SET type) to specify what cases to run.

The folder (example_E+_v8.1/ in this example) contains all the files of the project, including one .jep file that defines the project. All cases found in the project will be run, and result summary tables will be collected and stored in the folder named output/ next to the project folder.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -job example_E+_v8.1 -type JEPLUS_PROJECT -output ../output
user@K890:~/JESS_Client_v3.0.0$ 

The folder (example_E+_v8.1/ in this example) contains all the files of the project, including one .jep file that defines the project. -subset LHS_RANDOM is used with -subset_param 10 to specify a random sample (using LHS) of 10 cases of the project will be run, and result summary tables will be collected and stored in the folder named output/ next to the project folder.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -job example_E+_v8.1 -type JEPLUS_PROJECT -subset LHS_RANDOM -subset_param 10 -output ../output
user@K890:~/JESS_Client_v3.0.0$ 

The folder (example_E+_v8.1/ in this example) contains all the files of the project, including one .jep file that defines the project. -subset LIST_FILE is used with -subset_param joblist.csv to specify a user-defined list of cases of the project to be run, and the full results (specified with -result ALL) will be collected and stored in the folder named output/ next to the project folder.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -job example_E+_v8.1 -type JEPLUS_PROJECT -subset LIST_FILE -subset_param joblist.csv -result ALL -output ../output
user@K890:~/JESS_Client_v3.0.0$ 

The JEPLUS_JOB_SET type is very similar to JEPLUS_PROJECT, except that the project files previously uploaded are re-used. The folder to submit, -job example_E+_v8.1 in this example, is only used for locating the job list file if -subset LIST_FILE -subset_param joblist.csv are specified. -ref 14458 indicates the job id whose files to be re-used. The full results (specified with -result ALL) will be collected and stored in the folder named output/ next to the project folder in this example.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -job example_E+_v8.1 -type JEPLUS_JOB_SET -ref 14487 -subset LIST_FILE -subset_param joblist.csv -result ALL -output ../output
user@K890:~/JESS_Client_v3.0.0$ 

A new option to submit jobs without waiting for results is introduced in v3.0. The command-line option -submit <job type> is used, and the folder containing files to submit is given as the program argument. A new set of type names can be used, too. For EnergyPlus jobs, the type names start with EP_. For example, EP_IDF is equivalent to STD_SINGLE_JOB, whereas EP_IDF_SPLIT to SPLIT_SINGLE_JOB. Below are two examples showing their uses.

The command-line below submits a single EnergyPlus simulation with a model file (IDF) and a weather file (EPW) stored in the job folder std_job_v72. The simulation results will be put in the same folder as the model files after simulation.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -submit EP_IDF -output ./ std_job_v72
Job 14530 has been submitted successfully.

The command-line below submits a single EnergyPlus simulation with a model file (IDF) and a weather file (EPW) stored in the job folder std_job_v72. The simulation results will be put in the same folder as the model files after simulation.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -submit EP_IDF_SPLIT -output ./ std_job_v72
Job 14531 has been submitted successfully.

In v3.0, the job type for jEPlus jobs is JE_JEP, which replaces both JEPLUS_PROJECT and JEPLUS_JOB_SET in the command-line option -submit <job type>. Below are a few examples showing their uses.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -submit JE_JEP -output ./ example_E+v8.1
Job 14532 has been submitted successfully.

Or to reference a previously submitted job:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -submit JE_JEP -ref 14487 -subset LHS_RANDOM -subset_param 10 -output ../output example_E+v8.1
Job 14533 has been submitted successfully.

Submit a Radiance Rtrace job with a single sensor file:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -submit RA_RTRACE -output ../ra_out -oct dbmodel.oct -in trace.in -out out -args "-ab 5 -ad 2048 -aa .2 -ar 512 -as 1024 -h+ -I+ -oov -fa" example_Ray
Job 14540 has been submitted successfully.

Submit a Radiance Rtrace job with all the sensor files in the folder:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -submit RA_RTRACE -output ../ra2_out -oct dbmodel.oct -in *.in -out out -args "-ab 5 -ad 2048 -aa .2 -ar 512 -as 1024 -h+ -I+ -oov -fa" example_Ray2
Job 14541 has been submitted successfully.

Submit a Rpict job with view point specified in the command-line:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -submit RA_RPICT -output ../rpic_out -oct scene.oct -out image.hdr -args "-vtv -vp -.5 -5 1.15 -vd 0.5 5 0 -vh 45 -vv 45 -pa 1.0 -pj 0.02 -pd 0.0 -pm 0.0 -ps 1 -w+ -i- -bv+ -dt 0.050 -dc 0.50 -dj 0.0 -ds 0.250 -dr 1 -dp 512 -dv+ -st 0.150 -ab 4 -ar 128 -ad 1500 -as 500 -aa 0.15 -av 0.0 0.0 0.0 -aw 0 -lw 0.004 -ss 1.0 -lr -10 -u- -x 2048 -y 2048 -t 60" example_Rpic
Job 14542 has been submitted successfully.

Submit a Rpict job with view points in a .vf file:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -submit RA_RPICT -output ../rpicVF318_out -oct dbmodel.oct -in alt.vf -out hdr -args "-S 1 -o sc%%03d.hdr -pa 1.0 -pj 0.9 -pd 0.0 -pm 0.0 -ps 1  -pt 0.05 -w+ -i- -bv+ -dt 0.050 -dc 0.50 -dj 0.7 -ds 0.150 -dr 3 -dp 512 -dv+ -st 0.150 -ab 4 -ar 256 -ad 1024 -as 512 -aa 0.15 -av 0.0 0.0 0.0 -aw 0 -lw 0.002 -ss 1.0 -lr -10 -u- -x 1600 -y 1600 -t 60" example_RpicVF318
Job 14543 has been submitted successfully.

Submitting a Daysim job is similar to submitting a Radiance job. The main model file is the Daysim header file in this case. Sensor file should be specified separately using the -in argument. This will replace the entry in the header file by the JESS server.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -submit DS_ALL -output ../ds1_out -header Daysim.txt -in trace.in example_ds1
Job 14549 has been submitted successfully.

Or to run all the sensor files found in the folder:

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -nogui -submit DS_ALL -output ../ds2_out -header Daysim.txt -in *.in example_ds2
Job 14550 has been submitted successfully.

Start auto-retrieval of all submitted jobs. The client will keep polling the server for job results until all results are received. The client will not prompt anything unless some errors have occured, or the -dbonly option is specified. It exits when retrieval completes.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -retrieve
user@K890:~/JESS_Client_v3.0.0$

To collect results of any job of the user on the server, you can specify the job ID and options for what to download and where to save results.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -retrieve 1234 -output /files/output_1234 -result ALL
user@K890:~/JESS_Client_v3.0.0$

To download result files of selected cases in a jEPlus project job, you can use the additional -case option. All files of the selected cases will be downloaded.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -retrieve 1234 -case LHS-000001;LHS-000002 -output /files/output_1234
user@K890:~/JESS_Client_v3.0.0$

The simplest form of the cancel command is java -jar jess_client_v3.jar -cancel. This will cause the client to try cancel all pending jobs that have been submitted by this client.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -cancel
Cancel command sent for 1234@server2.ensims.com:2992

It is possible to send cancel command for any job that belongs to the current user by specifying the job id in the argument.

user@K890:~/JESS_Client_v3.0.0$ java -jar jess_client_v3.jar -cancel 12345
Cancel command sent for 12345@server2.ensims.com:2992

Sometimes it is necessary to call the client from a different folder than where jess_client_v3.jar is. To do that, you need to specify explicitly the location of the client.cfg and the log4j.cfg files, by including two extra arguments in the command-line. For example, to submit an E+ job from the current folder, i.e. from where in.idf and in.epw are, and the client is installed in C:\jess_client\, use the following command.

D:\MyJob>java -jar c:\\jess_client\\jess_client_v3.jar -cfg c:\\jess_client\\client.cfg -log c:\\jess_client\\log4j.cfg -job . -type STD_SINGLE_JOB -output .