Command Scripts
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
Introduction
A Command Script is a file containing a set of instructions that can be used to drive common SysCAD load/solve/report actions.
- These provide some high level commands usually executed in batch form from a script file.
- Command scripts are especially useful for loading, running and generating reports for different flowsheets and scenarios.
- Once set up, they can be run without any input from the user (i.e. ideal for overnight runs!).
- Command scripts can be loaded from within SysCAD, or launched externally.
WARNING: The command script file is designed to do repetition work. Therefore, it should only be used when commands have been tested individually. When commands are executed in the command script file, warning dialog boxes are not presented to avoid hold ups between commands.
Script Files
A command script is executed from a text file.
- The file has an extension .ssc.
- Only one command is allowed on each line.
- Blank lines are allowed.
- Lines starting with a semicolon (;) are ignored.
- The entire text file is processed and tested for errors before the script is executed. Strict parameter checking is not performed.
- If an error interpreting the script commands is found, it is reported immediately before executing any script commands.
- If an error occurs while executing a command script, the script is terminated and no further commands are executed.
- While executing the command script, the user may abort at anytime by pressing the abort button on the bottom right hand corner of the screen.
- The SysCAD command script file will terminate after the current command has finished.
A command script can be executed in two ways, either from the command line, or using the Tools - Command Scripts in SysCAD. Refer to the following section which describes the dialog box displayed when this command is selected.
See Command Line Options for examples of running the Command script from Dos prompt or See Starting and running SysCAD from MS Excel for including and starting a Command Script in an Excel macro.
Command Scripts Dialog Box
The following dialog box is displayed when Tools - Command Scripts is selected from the menu in SysCAD.
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 (sortable) 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.
(Note, the last column is for sorting the table in default order, it has no other meaning)
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. In Build 139 or later, 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 Related Commands | ||||
Project Solve - Solve | Solve() | Available from Build 139. Equivalent to “StartSolve()” followed by “WaitTillStop()”. See Example 2 | Yes | Yes |
Project Solve - Start Solve | StartSolve() | Available from Build 139. Replaces StartProBalSolve() and StartDynamicSolve() | Yes | Yes |
Project Solve - Start ProBal Solve | StartProBalSolve() | Starts Solve, used for steady state projects. In Build 139 and later, user can use StartSolve() which can be used for both steady state or dynamic projects. | Yes | Yes |
Project Solve - Start Dynamic Solve | StartDynamicSolve() | Starts Solve, used for dynamic projects. In Build 139 and later, user can use StartSolve() which can be used for both steady state or dynamic projects. | Yes | Yes |
Project Solve - Stop | Stop() | Stops SysCAD run or solve. | Yes | - |
Project Solve - Stop Solve | StopSolve() | Available from Build 139. Replaces Stop() | Yes | - |
Project Solve - Wait | Wait(time in seconds) | Prevents further commands executing until the specified number of seconds has elapsed. The time in seconds is SysCAD simulation time measured from when the StartDynamicSolve, StartProBalSolve or StartSolve was executed (i.e. from first iteration) or from the last call to ResetWait. | Yes | No |
Project Solve - Wait Count | WaitCount(iterations) | Prevents further commands executing until the specified number of iterations has elapsed. The iteration counter is measured from when the StartDynamicSolve, StartProBalSolve or StartSolve was executed (i.e. from first iteration) or from the last call to ResetWait. | Yes | No |
Project Solve - Wait Till Stop | WaitTillStop() | Prevents further commands executing until SysCAD stops running/solving.
|
Yes | No |
Project Solve - Reset and Wait | ResetWait() | Resets the counter and timer used by the Wait and WaitCount commands. These are also always set when StartDynamicSolve or StartProBalSolve commands are executed. | Yes | - |
Report - Setting/Reporting Tags from text files | ||||
Report - Text File - Import Tags | SetTags(format, filename) | Available from Build 139. 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) | Available from Build 139. 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 | Yes | - |
UsefulOther - Save Scenario | SaveScenario(filename.scn) | Saves the specified scenario. | Yes | - |
UsefulOther - Execute Macro | ExecuteMacro(filename, macro name) | Calls and executes a MS Excel Macro. | 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.
; ==============================================================================================================================
Build 139 and later Format | Build 138 and earlier Format |
LoadProject(c:\SysCAD Projects\example.spf\project.spj)
StartSolve()
WaitCount(300)
StopSolve()
SaveScenario(start1.scn)
SetTag(PGM1.ResetAll, 1)
RestartHistorian()
SetTag(PGM1.StartSimulationFlag, 1)
StartSolve()
Wait(3600)
StopSolve()
GenerateTagReport("$PrjFiles\Reports\SampleReport.xlsx", *)
Exit(1) |
LoadProject(c:\SysCAD Projects\example.spf\project.spj)
StartDynamicSolve()
WaitCount(300)
Stop()
SaveScenario(start1.scn)
SetTag(PGM1.ResetAll, 1)
RestartHistorian()
SetTag(PGM1.StartSimulationFlag, 1)
StartDynamicSolve()
Wait(3600)
Stop()
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. ; ==============================================================================================================================
Build 139 and later Format | Build 138 and earlier Format |
; ----------------------------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) |
; ----------------------------Case1---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case1)
StartProBalSolve()
WaitTillStop()
GenerateTagReport('$PrjFiles\TestCases.xls', Case1)
;
; ----------------------------Case2---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case2)
StartProBalSolve()
WaitTillStop()
GenerateTagReport('$PrjFiles\TestCases.xls', Case2)
;
; ----------------------------Case3---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case3)
StartProBalSolve()
WaitTillStop()
GenerateTagReport('$PrjFiles\TestCases.xls', Case3)
;
; ----------------------------Case4---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case4)
StartProBalSolve()
WaitTillStop()
GenerateTagReport('$PrjFiles\TestCases.xls', Case4)
;
; ----------------------------Case5---------------------------------
ProcessSetTags('$PrjFiles\TestCases.xls', Case5)
StartProBalSolve()
WaitTillStop()
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.
; =============================================================================================================================================
Build 139 and later Format | Build 138 and earlier Format |
;------ 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() |
;------ Case 1 ------
SetTag(STL_001.ColumnToSet, 1)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 1)
StartProbalSolve()
WaitTillStop()
;
;------ Case 2 ------
SetTag(STL_001.ColumnToSet, 2)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 2)
StartProbalSolve()
WaitTillStop()
;
;------ Case 3 ------
SetTag(STL_001.ColumnToSet, 3)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 3)
StartProbalSolve()
WaitTillStop()
;
;------ Case 4 ------
SetTag(STL_001.ColumnToSet, 4)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 4)
StartProbalSolve()
WaitTillStop()
;
;------ Case 5 ------
SetTag(STL_001.ColumnToSet, 5)
SetTag(STL_001.SetTags, 1)
SetTag(GTL_001.ColumnToGet, 5)
StartProbalSolve()
WaitTillStop() |
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: