In some cases, it may be useful to run the GoldSim Player A program that allows you to "play" or "read" an existing GoldSim model without having to license the GoldSim software. The GoldSim Player is available as a free download from the GoldSim website. directly from the command line.
This, for example, could be done by selecting Run from the Windows Start menu, which displays the following dialog:
You must enter the full path to the GoldSim Player executable (which may, of course, be different than that shown above), followed by the GoldSim file that you want to open. If no filename is specified, GoldSim simply opens the Player and displays the splash screen.
Note: If no path is specified for a filename, GoldSim Player looks in the same directory as the Player executable. Hence, it is highly recommended that you provide a full path for the filename.
The primary reason for running the Player from the command line is to take advantage of a number of command line parameters that cause the Player to execute in a specific manner.
The command line parameters are summarized in the following table. Note that the parameters are entered after the executable and before the model file name.
| Parameter | Description | Comments |
| -r -run |
Opens the GoldSim Player file A special file format (with the extension .gsp) that can be created by GoldSim and can only be read by the GoldSim Player. and immediately runs the simulation. | |
| -getdb [date] | Executes a global database download for all elements linked to databases. | The date is only required for Extended GoldSim databases. The date must be specified in local format and be enclosed in quotes (e.g., "7 March 2013"). |
| -x | Closes GoldSim after all other options have been executed. | Note that unless the -sv parameter is also used, the GoldSim Player file will NOT be saved when the application is closed. |
| -sv [filename] -save [filename] |
Saves the Player file using either the optionally provided output filename, or the input filename (if an output file is not provided). | This option can be used to run and save a Player file. |
| -starttime "date[time]" | Resets the Start Time | The time is optional. The date/time string can take on
any of the following formats:
"25 January 1996" "January 25, 1996 8:30:00" "8:30:00 Jan. 25, 1996" "1/25/1996 8:30:00" Time can be specified in military (24 hour time) or 12 hour time using PM and AM. |
| -endtime "date[time]" | Resets the End Time | -endtime and -duration are mutually exclusive (only one
can be set). The -endtime flag must be used in conjunction with the
-starttime flag. The time is optional. The date/time string can take on
any of the following formats:
"25 January 1996" "January 25, 1996 8:30:00" "8:30:00 Jan. 25, 1996" "1/25/1996 8:30:00" Time can be specified in military (24 hour time) or 12 hour time using PM and AM. |
| -duration "time expression" | Resets the Duration using the provided expression | -endtime and -duration are mutually exclusive (only one can be set). Time expression should use GoldSim's built-in units, and must have dimensions An output attribute for an element that defines the dimensionality (in terms of Length, Time and other fundamental dimensions) of the output. of Time. |
Examples of how these parameters would commonly be used are provided below. Note that these parameter strings would follow the name (and path) of the GoldSim Player executable (GSPlayer.exe).
| Command line | Comments |
| -r test1.gsp | Opens test1.gsp, executes pre-run checks and starts the simulation. GoldSim Player remains open after the simulation. |
| -r -sv test1.gsp | Opens test1.gsp, executes pre-run checks and starts the simulation. At the end of the simulation, the Player file is saved. GoldSim Player remains open after the simulation. |
| -r -sv -x test1.gsp | Opens test1.gsp, executes pre-run checks and starts the simulation. At the end of the simulation, the Player file is saved. GoldSim Player is then closed. |
| -r -sv test1res.gsp test1.gsp | Opens test1.gsp, executes pre-run checks and starts the simulation. At the end of the simulation, the Player file is saved to test1res.gsp. GoldSim Player remains open after the simulation. |
Several points should be noted regarding the use of the -starttime, -endtime and -duration commands:
-
In order for these to work, the Player file must have been created by the author such that "Allow changes to model's Simulation Time Settings" was checked.
-
The arguments to these commands must be enclosed in quotes.
-
Units must be specified if the input has dimensions.
-
The commands can only be used in the following combinations:
- -starttime only (Elapsed Time, Calendar Time or Static models)
- -starttime and -duration (Elapsed Time or Calendar Time models)
- -starttime and -endtime (Calendar Time models only)
- -duration only (Elapsed Time or Calendar Time models)
Examples of the use of the -starttime, -endtime and -duration commands are provided below:
| Command line | Comments |
| -starttime "1/1/2021" | Sets the Start Time to 1 January 2021 |
| -starttime "25 January 2021 18:30:00" | Sets the Start Time to 25 January 2021 at 6:30 PM |
| -starttime "25 January 2021 6:30:00 PM" | Sets the Start Time to 25 January 2021 at 6:30 PM |
| -starttime "1/1/2021" -duration "100 days" | Sets the Start Time to 1 January 2021and the Duration to 100 days |
| -starttime "1/1/2021" -endtime "1/1/2022" | Sets the Start Time to 1 January 2021 and the End Time to 1 January 2022 |
| -duration "100 days" | Set the Duration to 100 days (using the defined Start Time and replacing the End Time |
In most cases, it is likely that you will want to "stack" a number of GoldSim runs by creating a batch file that you run from the command line. However, if you simply stack command lines and then run a batch file, all GoldSim Player calls would be launched in parallel (e.g., if you had 10 command lines that ran GoldSim Player, 10 instances of GoldSim Player would open and run simultaneously).
To avoid this problem and force the commands to run in series, you can use the Start/Wait command provided by Windows. An example batch file that utilizes this is shown below:
CD c:\Program Files\GTG\GoldSim
14.0
Start /wait GSPlayer.exe -r -sv
-x c:\runs\input1.gsp
Start /wait GSPlayer.exe -r -sv
-x c:\runs\input2.gsp
Start /wait GSPlayer.exe -r -sv
-x c:\runs\input3.gsp
Start /wait GSPlayer.exe -r -sv
-x c:\runs\input4.gsp
The first line simply sets the directory to the location of the GoldSim executable. The next line opens a GoldSim Player file called input1.gsp. The Player runs the model, saves the results and then closes. After closing, the next GoldSim Player command is implemented (open input2.gsp, run and save the model). This continues until all four GoldSim runs are complete.
The GoldSim Player also provides an additional command line option that runs the Player in "hidden mode", such that it runs as a background process, and is not actively seen on the desktop. This is useful in cases where you want a separate program to run the Player (without the user being aware that it being run).
This is accomplished using a -h (for "hide") flag. 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, the Player will automatically exit after execution. In other words, 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:
GSPlayer.exe -h -r -sv Model1_Results.gsp Model1.gsp
This would open the model file "Model1.gsp", run it, save it to "Model1_Result.gsp", and exit, all in the background (i.e., such that the fact that the Player ran will not be apparent to the user).
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). However, an alternative command line flag, -hl (or -hide-log), is available that instructs the Player to generate a log file to which any such messages will be written. 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 log file name, by default, is the name of the Player file with the .gsp 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.
GSPlayer.exe -hide-log "Model1 Errors.log" -r Model1.gsp
The following points should also be noted:
- If the Player file 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.
- If the -getdb flag is specified with a "date" that is invalid, an error message "Effective date for database download is invalid!" is logged (assuming the -hl or -hide-log flag is used) and the process terminates with error code 1.
- 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 Player will not append to an existing file), unless the file is read-only. If the file is read-only, GoldSim Player skips writing a log file.
Note that the Player 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 Player was unable to create, open or write to the log file. Program execution may or may not have been successful. |
| 4 | File I/O Error: GoldSim Player 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. |
| 9 | An error occurred during post-simulation export of model results. |
| 10 | GoldSim Player 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.