Command Scripts
(Redirected from Script)
Jump to navigation
Jump to search
Navigation: User Guide ➔ Menu Commands ➔ Tools ➔ Command Scripts
| Command Scripts | COM Automation | Python Automation | VBA Automation | C++ Automation | Testing if SysCAD is open |
|---|
Related Links: Command Line Options, Setting and Reporting Tags from text files, Relative File Path
Introduction
A Command Script is a file containing a sequence of instructions used to automate common SysCAD actions such as loading, solving, and reporting.
These scripts provide high-level commands typically executed in batch mode, making them especially useful for running and reporting on multiple project scenarios. Once configured, they can run unattended, ideal for overnight processing. Multiple copies of SysCAD can be run simultaneously each with their own script files for more effective use of computing resources.
Command scripts can be launched from within SysCAD or externally using Command Line Options.
WARNING: Command scripts are designed for repetitive tasks. They should only be used on a robust project after individual commands have been tested. Warning dialogs are suppressed during execution to avoid interruptions.
One of the main uses of command scripts is to run scenarios with different data sets and generate corresponding results. Users can exchange data with SysCAD in several ways:
- Direct input via the script file – suitable for a small number of variables.
- SysCAD Excel data transfer – allows flexible data exchange using MS Excel.
- See Example: Run Test Cases using MS Excel Reports.
- This approach is limited to a single instance of SysCAD running a script because SysCAD and Excel data transfer is by COM Automation API limited to a single instance of Excel.
- SysCAD SetTagList and GetTagList models – for structured data handling within the project.
- See Example: Run Test Cases using SetTagList and GetTagList Controller.
- This approach supports the use of multiple SysCAD instances simultaneously running scripts.
- Text files – allows flexible data exchange using text CSV formatted files.
- See Example: Use command script to create reports in text file (csv) format.
- This approach supports the use of multiple SysCAD instances simultaneously running scripts.
For more complex, interactive, and flexible use cases the COM Automation interface can be used instead of using SysCAD scripts. Using this does have some limitations especially in regards to running simultaneous copies.
Script Files
A command script is executed from a plain text file with the extension .ssc.
File Structure & Rules:
- Each line contains only one command.
- Blank lines are allowed.
- Lines starting with a semicolon (;) are treated as comments and ignored.
- The entire file is parsed and checked for errors before execution begins.
- Strict parameter checking is not performed, so it's important to test commands individually before including them in a script.
Error Handling:
- If an error is found while interpreting the script, it is reported before any commands are executed.
- If an error occurs during execution, the script is terminated immediately, and no further commands are run.
- Users can abort execution manually at any time by pressing the Abort button in the bottom-right corner of the SysCAD window.
- The script will terminate after the current command finishes.
Execution Methods:
Command scripts can be run in two ways:
- From the command line
- Using the Tools - Command Scripts option within SysCAD.
- Refer to the following section which describes the dialog box displayed when this command is selected.
For examples:
- See Command Line Options for running scripts via the DOS prompt.
- See Starting and running SysCAD from MS Excel for integrating and launching command scripts from Excel macros.
Command Scripts Dialog Box
The following dialog box is displayed when Tools - Command Scripts is selected from the menu in SysCAD.
|
Columns:
Buttons:
|
Tickbox:
- Log Script Command to Messages Window: If this is ticked, then a message will be logged in the General Message Log of the Message Window as each command in the command script is executed.
Notes:
- Even with this option unticked, messages may appear in the Message Window related to the commands themselves, for example, processing or generating Excel Reports.
- If the Clear messages on run option is ticked on the Options tab of the Message Window, then even with this option ticked, messages may not linger in the general message log as they will be cleared every time the project is run (including as part of executing the command script).
Script Commands
The script commands currently available and the context in which they can be used are shown in the following table.
- If a path is not specified for most file name command parameters, then the project folder is used.
- String parameters such as file names should be enclosed in single or double quotes if they contain spaces.
- For most commands, try to use the relative paths instead of full path (except for Load project, where full path should be given). See Example 1.
| Command by Group | Command Syntax | Description | Restrictions | ||
|---|---|---|---|---|---|
| Project Must be Loaded | SysCAD Must be Stopped | ||||
Project Related Commands | |||||
| Project - Load Project | LoadProject(filename.spf\project.spj) | Loads the specified SysCAD project, filename requires full path. Any already opened project will be closed without saving. | --- | Yes | |
| Project - Set value to a Tag directly | SetTag(tag (conversions), value) | Sets the specified tag to the specified value. The SysCAD tag must exist. Engineering units may be specified. String tags can also set via this method. | Yes | - | |
| Project - Save Project | SaveProject() | Saves the current project | Yes | Yes | |
| Project - Close Project | CloseProject() | Closes the current project without saving. | Yes | Yes | |
| Project - Exit SysCAD | Exit(value) | Exits SysCAD completely. Should be the last command in the file.
|
--- | Yes | |
Project Solve Commands (Typical) | |||||
| Project Solve - Solve | Solve() | Starts the solver and waits for the solve to be completed (i.e. Solver stopped). | This is equivalent to StartSolve() followed by WaitTillStop(). See Example 2 |
Yes | Yes |
| Project Solve - Solve until time | SolveUntilTime(simulation time in seconds) | Available from Build 139.37057. Starts the solver, waits for the specified simulation time to have passed, and stops the solver. | This is equivalent to StartSolve() followed by WaitTime(nnn) followed by StopSolve(). | Yes | Yes |
| Project Solve - Solve until count | SolveUntilCount(iterations) | Available from Build 139.37057. Starts the solver, waits for the specified number of iterations (ProBal) or steps (dynamic), and stops the solver. | This is equivalent to StartSolve() followed by WaitCount(nnn) followed by StopSolve(). | Yes | Yes |
Project Solve Commands (Detailed) | |||||
| Project Solve - Start Solve | StartSolve() | Starts the Solver. Usually followed by one of the Wait commands, if the next command is not a Wait command, the solver continues until stopped. | Yes | Yes | |
| Project Solve - Wait Time | WaitTime(simulation time in seconds) | Delays execution of the next command in the script file until the specified number of seconds has passed. The time is measured in SysCAD simulation seconds, starting from either the execution of StartSolve or the most recent call to ResetWait. In Steady State projects, one simulation second is equivalent to one iteration. | Yes | No | |
| Project Solve - Wait Count | WaitCount(iterations) | Delays execution of the next script command until the specified number of time steps (for Dynamic projects) or iterations (for Steady State projects) has elapsed. The counter starts from the execution of StartSolve or the most recent call to ResetWait. | Yes | No | |
| Project Solve - Wait Till Stop | WaitTillStop() | Delays execution of the next script command until the SysCAD solver stops.
|
Yes | No | |
| Project Solve - Stop Solve | StopSolve() | Stops SysCAD Solver. | Yes | - | |
| Project Solve - Reset Wait | ResetWait() | Resets the timer and counter used by the Wait and WaitCount commands. These are also always set when StartSolve command is executed. | Yes | - | |
| From Build 139, the following are legacy commands that are planned to be phased out in future releases. It is recommended to transition to the newer commands for continued compatibility. | |||||
| Project Solve - Start ProBal Solve | StartProBalSolve() | Starts Solve for steady state projects. | Recommended Replacement: StartSolve() | Yes | Yes |
| Project Solve - Start Dynamic Solve | StartDynamicSolve() | Starts Solve for dynamic projects. | Recommended Replacement: StartSolve() | Yes | Yes |
| Project Solve - Wait Time | Wait(simulation time in seconds) | Old command name for WaitTime. | Recommended Replacement: WaitTime() | Yes | No |
| Project Solve - Stop | Stop() | Stops SysCAD Solver. | Recommended Replacement: StopSolve() | Yes | - |
Report - Setting/Reporting Tags from text files | |||||
| Report - Text File - Import Tags | SetTags(format, filename) | Set tags in SysCAD from tags and values in a text file. See Setting and Reporting Tags from text files for formats and options. | Yes | Yes | |
| Report - Text File - Export Tags | ReportTags(format, templatefile, filename) | Reports a list or table of tags in a text file. See Setting and Reporting Tags from text files for formats and options. | Yes | Yes | |
Report - Setting/Reporting Tags from MS Excel Files | |||||
| Report - Excel - Import Data | ProcessSetTags(filename, reportName) | Sets the value of SysCAD variables from Excel spreadsheet. The Excel filename and the required report name must be supplied. Specify asterisk (*) for the report name if all reports are required. | Yes | Yes | |
| Report - Excel - Export Tags | GenerateTagReport(filename, reportName) | Generates the specified Excel tagged values report. The Excel filename and the required report name must be supplied. Specify asterisk (*) for the report name if all reports are required. | Yes | - | |
| Report - Excel - Export Trend | GenerateTrendReport(filename, reportName) | Generates the specified Excel trend report. The Excel filename and the required report name must be supplied. Specify asterisk (*) for the report name if all reports are required. | Yes | Yes | |
| Report - Excel - Save And Close | SaveAndCloseReport(FileName) | Saves and closes the specified excel report. The command is useful when automating many separate excel report generations.The specified excel file must be opened. | Yes | ||
Useful Other Commands | |||||
| UsefulOther - Load Scenario | LoadScenario(filename.scn) | Loads the specified scenario. If the scenario file is not saved directly under the project folder, then either specify the full path or use Relative File Path to specify the path name. | Yes | - | |
| UsefulOther - Save Scenario | SaveScenario(filename.scn) | Saves the specified scenario. If the scenario file is not saved directly under the project folder, then either specify the full path or use Relative File Path to specify the path name. | Yes | - | |
| UsefulOther - Report Conditions | ReportConditions(filename) | Available from Build 139.37057. Retrieves the contents of the Conditions tab from the Messages window and saves them to a text file in CSV format. This is especially useful for capturing data immediately after solving a steady-state project. | Yes | Yes | |
| UsefulOther - Execute Macro | ExecuteMacro(filename, macro name) | Calls and executes a MS Excel Macro. This will be discontinued in future releases. | No | Yes | |
| UsefulOther - Restart Historian | RestartHistorian() | Deletes all the historian data files (trend lines). Only meaningful if the project historian is on. | Yes | Yes | |
Example Script Files
Example 1 - Reset solve conditions after a specified time period
; ============================================================================================================================== ; Script file to run a dynamic project for a number of iterations (e.g. to reach a stable state), then set a pgm ; flag to reset counters. Run dynamic simulation scenario for one hour then generates the required reports. ; ==============================================================================================================================
LoadProject(c:\SysCAD Projects\example.spf\project.spj)
StartSolve()
WaitCount(300)
StopSolve()
SaveScenario(".\Scenarios\start1.scn")
SetTag(PGM1.ResetAll, 1)
RestartHistorian()
SetTag(PGM1.StartSimulationFlag, 1)
StartSolve()
Wait(3600)
StopSolve()
GenerateTagReport("$PrjFiles\Reports\SampleReport.xlsx", *)
Exit(1)Example 2 - Run Test Cases from MS Excel Reports
; ============================================================================================================================== ; The file is used to repeat the following commands: ; 1) Set user data from MS Excel to the SysCAD Project via Set Tag Report ; 2) Solve the SysCAD Project; ; 3) Wait until it finished solving; ; 4) Create SysCAD reports in MS Excel via Tag Report. ; This file assume the SysCAD project is opened ; The Script file can be accessed from Tools - Command Scripts ; Add the file then press Execute. ; ==============================================================================================================================
; ----------------------------Case1---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case1)
Solve()
GenerateTagReport('$PrjFiles\TestCases.xls', Case1)
;
; ----------------------------Case2---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case2)
Solve()
GenerateTagReport('$PrjFiles\TestCases.xls', Case2)
;
; ----------------------------Case3---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case3)
Solve()
GenerateTagReport('$PrjFiles\TestCases.xls', Case3)
;
; ----------------------------Case4---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case4)
Solve()
GenerateTagReport('$PrjFiles\TestCases.xls', Case4)
;
; ----------------------------Case5---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case5)
Solve()
GenerateTagReport('$PrjFiles\TestCases.xls', Case5)Example 3 - Run Test Cases Using SetTagList and GetTagList Controller
; ============================================================================================================================================= ; This file assumes the following is used: ; 1) Set Tag List Model is used to Set the user defined data ; 2) Get Tag List Model is used to report the required value (with GetAtEnd option selected) ; The Script file is set up to do the following: ; 1) Define the column number to use for test data ; 2) Sets the test data by executing SetTags (this is equivalent to pressing the SetTags button in the SetTagList Controller) ; 3) Define the column number to report the data. Data is reported when SysCAD is solved. This assumes the GetAtEnd Option is used. ; 4) Solve the SysCAD Project; ; 5) Wait until it has finished solving before proceeding to the next test case; ; This file assume the SysCAD project is opened, the Script file can be accessed from Tools - Command Scripts, Add the file then press Execute. ; =============================================================================================================================================
;------ Case 1 ------
SetTag(STL_001.ColumnToSet, 1)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 1)
Solve()
;
;------ Case 2 ------
SetTag(STL_001.ColumnToSet, 2)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 2)
Solve()
;
;------ Case 3 ------
SetTag(STL_001.ColumnToSet, 3)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 3)
Solve()
;
;------ Case 4 ------
SetTag(STL_001.ColumnToSet, 4)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 4)
Solve()
;
;------ Case 5 ------
SetTag(STL_001.ColumnToSet, 5)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 5)
Solve()Example 4 - Use command script to create reports in text file (csv) format
Please refer to Setting and Reporting Tags from text files.
Distributed Example Projects
There are a number of distributed example projects and files that demonstrate the use command script file. These include: