Running GoldSim in Hidden Mode from the Command Line

GoldSim provides a command line option that runs GoldSim in "hidden mode", such that it runs as a background process, and is not actively seen on the desktop, while reporting the outcome as either success or failure using a process exit code and a log file. This is useful in cases where you want a separate program to run GoldSim (without the user being aware that it being run). Among other uses, it also allows you to stack up scheduled runs of GoldSim for execution (using a batch file) on a high-performance cloud environment, and shut down the virtual system at the appropriate time (so as not to incur unnecessary costs).

In order to provide meaningful feedback for the many possible failure conditions of a hidden use of GoldSim, hiding is always used in conjunction with logging. This is accomplished using a -hl (short form) or -hide-log (long form) flag. In hidden mode, error messages and Interrupt Element An efvent element that is triggered by an event, and responds by interrupting the simulation. messages are suppressed (i.e., not shown). Instead, this flag instructs GoldSim to generate a log file with these messages. If the run is executed successfully, the log file will contain the text ‘SUCCESS!’. Otherwise, it will contain the text ‘ERROR!’ followed by details of the error.

The flag can be used in combination with any existing command line flags (such as -r for run, -x for exit, -getdb to run a database import). Note, however, that if the hide flag is specified, GoldSim will automatically exit after execution. That is, it is not necessary to include the -x flag if the hide flag is used. An example command line instruction with the -h flag is given below (this assumes that the path for the command prompt is set to the directory where the executable is located; otherwise, you would need to specify the full path to the executable):

GoldSim.exe -hl -r -sv Model1_Results.gsm “c:\runs\Model1.gsm”

This would open the model file "Model1.gsm" (in the folder c:\runs), run it, save it to "Model1_Result.gsm" (in that same folder), create a log file (named Model1.log) and exit, all in the background (i.e., such that the fact that GoldSim ran will not be apparent to the user).

The log file name, by default, is the name of the GoldSim file with the .gsm extension replaced by a .log extension. Alternatively, a log file name may be provided (inside double quotation marks if it includes spaces) following the -hl (or -hide-log) flag. An example is shown below:

GoldSim.exe -hl Model1_ Errors.log -r -sv Model1_Results.gsm “c:\runs\Model1.gsm”

The following points should also be noted:

• If GoldSim has Time History elements exporting results to Excel or to a Text file, the results are only automatically exported if the model option "Export results after simulation" was previously selected.
• An Interrupt element error message will only be written to a log file if the Interrupt element causes an abort operation.
• If a log file with a specified name already exists, it will be overwritten (i.e. GoldSim will not append to an existing file), unless the file is read-only. If the file is read-only, GoldSim skips writing a log file.

Note that the GoldSim process returns an exit code upon exiting when running in hidden mode. A 0 code indicates no errors were identified. A code of 1 or greater indicates an error.

Exit Code	Comments
0	Successful execution.
1	An error occurred while preparing or running the simulation. This includes any errors while checking the model, importing data from external sources, running the model.
2	GoldSim was unable to create, open or write to the log file. Program execution may or may not have been successful.
3	No or insufficient license: Unable to acquire a GoldSim license, or license not sufficient (missing module or exceeding a restriction).
4	File I/O Error: GoldSim was unable to load the model file.
5	Generic Error Processing Shell Command: this is a fall back for cases when an error occurred but cannot be traced back to the a specific origin.
6	GoldSim encountered an error while parsing the model elements.
7	GoldSim encountered an error while sequencing the model elements.
8	GoldSim encountered an error while checking element validity prior to simulation.
9	An error occurred during post-simulation export of model results.
10	GoldSim was unable to obtain write access to spreadsheet file required for saving intermediate model output data.

The exit code can be queried using an IF statement in the batch file as shown in the example below:

if errorlevel 1 ( echo ERROR while executing GoldSim [code:%errorlevel%])

In this example, if the error code is 1 or greater, the error code will be written to the console.