Command Scripts
From SysCAD Documentation
Navigation: User Guide -> Command Scripts
Contents |
Introduction
A set of commands (script) can be used to externally control SysCAD. 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 (ie ideal for overnight runs!).
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, and only one command is allowed on each line. Blank lines are allowed. Lines starting with a semi-colon (;) 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.
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.
Script Commands
The script commands currently available and the context in which they can be used are shown (sorted alphabetically) in the 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. Each command will be described in detail in the sub headings.
| Command | Project Loaded | Solving |
| Commonly Used Commands | ||
| CloseProject() | Yes | No |
| ExecuteMacro(filename, macro name) | No | No |
| Exit() | --- | No |
| GenerateTagReport(filename, reportName) | Yes | No |
| LoadProject(filename.spf\project.spj) | --- | No |
| LoadScenario(filename.scn) | Yes | --- |
| ProcessSetTags(filename, reportName) | Yes | No |
| ResetWait() | Yes | --- |
| RestartHistorian() | Yes | No |
| SaveAndCloseReport(FileName) | --- | No |
| SaveProject() | Yes | No |
| SaveScenario(filename.scn) | Yes | --- |
| SetTag(tag, value) | Yes | --- |
| StartDynamicSolve() | Yes | No |
| StartProbalSolve() | Yes | No |
| Stop() | Yes | Yes |
| Wait(time) | Yes | Yes |
| WaitCount(iterations) | Yes | Yes |
| WaitTillStop() | Yes | Yes |
| Other Commands | ||
| GenerateTrendReport(filename, reportName) | Yes | No |
| CompareOptions(filename, sorted) | --- | --- |
| CompareOptions2(maxCount, relTol, abs Tol, showDifferentStrings, showMissingTags) | --- | --- |
| CompareReset() | --- | --- |
| CompareScenarios(filename1,filename2) | Yes | No |
| CompareScenarioToCurrent(filename) | Yes | No |
Project Related Commands
- LoadProject
LoadProject(filename.spf\project.spj) loads the specified SysCAD project. Any already opened project will be closed without saving.
Restrictions: SysCAD must be stopped.
- SaveProject
SaveProject() saves the current project.
Restrictions: Project must be open; SysCAD must be stopped.
- CloseProject
CloseProject() closes the current project without saving. To save the project, use SaveProject() prior to CloseProject(). Restrictions: Project must be open; SysCAD must be stopped.
- Exit
Exit(value) exits SysCAD completely.
- Exit(0) - SysCAD will close without saving the project.
- Exit(1) - SysCAD will save the opened project and then exit.
If this command is used, it should be the last command in the command script file.
Restrictions: SysCAD must be stopped.
Project Solve / Run Related Commands
- StartDynamicSolve
StartDynamicSolve() starts the simulation run in dynamic mode.
Restrictions: Project must be open; SysCAD must be stopped.
- StartProbalSolve
StartProbalSolve() starts the solver in process balance (ProBal) mode.
Restrictions: Project must be open; SysCAD must be stopped.
- Stop
Stop() stops SysCAD run or solve.
Restrictions: Project must be open; SysCAD must be running/solving.
- SetTag
SetTag(tag (EngUnit), value) sets the specified tag to the specified value. The SysCAD tag must exist. Engineering units may be specified.
Restrictions: Project must be open; Tag of correct type must exist.
- Wait
Wait(Time) 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 was executed (ie from first iteration) or from the last call to ResetWait.
Restrictions: Project must be open; SysCAD must be running/solving.
- WaitCount
WaitCount(iterations) prevents further commands executing until the specified number of iterations has elapsed. The iteration counter is measured from when the StartDynamicSolve\StartProbalSolve was executed (ie from first iteration) or from the last call to ResetWait.
Restrictions: Project must be open; SysCAD must be running/solving.
- WaitTillStop
WaitTillStop() prevents further commands executing until SysCAD stops running/solving. For example, this would occur when a flowsheet is balanced in ProBal mode.
Restrictions: Project must be open; SysCAD must be running/solving.
- ResetWait
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.
Restrictions: Project must be open.
Report Related Commands
- GenerateTagReport
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.
Restrictions: Project must be open; SysCAD must be stopped.
- GenerateTrendReport
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.
Restrictions: Project must be open; SysCAD must be stopped.
- ProcessSetTags
The 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.
Restrictions: Project must be open; SysCAD must be stopped.
- SaveAndCloseReport
The SaveAndCloseReport(ExcelFileName) saves and closes the specified excel report. The command is useful when automating many separate excel report generations.
Restrictions: The specified excel file must be opened.
Other Useful Commands
- ExecuteMacro
ExecuteMacro(filename, macro name) calls and executes a MS Excel Macro.
Restrictions: Project must not be solving.
- RestartHistorian
RestartHistorian() deletes all the historian data files (trend lines). Only meaningful if the project historian is on.
Restrictions: Project must be open; SysCAD must be stopped.
- LoadScenario
LoadScenario(filename.scn) loads the specified scenario.
Restrictions: Project must be open.
- SaveScenario
SaveScenario(filename.scn) saves the specified scenario.
Restrictions: Project must be open.
Compare Commands (Not commonly used)
- CompareOptions
CompareOptions(filename, sorted) sets some options used by CompareScenarios() and CompareScenarioToCurrent(). The file name is the tag value comparison report file name. If the value for sorted is 0 then all tags that are different are shown in the order found. If the value for sorted is 1 then only maxCount of the worst differences are shown in descending order.
Restrictions: None.
- CompareOptions2
CompareOptions2(maxCount,relativeTolerance,absoluteTolerance,showDifferentStrings,showMissingTags) sets some options used by CompareScenarios() and CompareScenarioToCurrent(). maxCount is used to specify the maximum number of differences to be shown if sorted is true. Variables relativeTolerance and absoluteTolerance are used to determine if there is a significant difference. If showDifferentStrings is 0 then string tags will not be compared; otherwise all strings that are different will be reported. If showMissingTags is 0 then tags that are missing in either scenario are not reported, otherwise they are reported.
Restrictions: None.
- CompareReset
CompareReset() the next time a tag value comparison output file is generated it is first deleted. Normally the report is appended to the end of the file.
Restrictions: None.
- CompareScenarios
CompareScenarios(filename1, filename2) compares the tag values in the two files specified and generates an output report. The files may be either snapshots or scenarios. The report format and options will depend on previous calls to CompareOptions(), CompareOptions2() and CompareReset(). The default options (used if the relative commands aren't called) are OutputFilename= compare.csv, sorted= 0, maxCount= 200, relativeTolerance= 0.0001, absoluteTolerance= 0.000001, showDifferentStrings= 1 and showMissingTags= 0. See the section on Scenarios for more information.
Restrictions: Project must be open; SysCAD must be stopped.
- CompareScenarioToCurrent
CompareScenarioToCurrent(filename) compares the tag values in the specified file (snapshot or scenario) and generates an output report. See CompareScenarios() for more details as the commands are almost identical.
Restrictions: Project must be open; SysCAD must be stopped.
Example 1 - Reset solve conditions after a specified time period
; --------------------------------------------------------------------------------------------------
; Script file to run a project for a number of iterations to reach a stable state, then set pgm flag
; to reset counters. Run simulation scenario for one hour then generates the required reports.
; ---------------------------------------------------------------------------------------------------
LoadProject(c:\SysCAD91\tutorial\example.spf\example.spj)
LoadSnapshot(c:\SysCAD91\tutorial\sim1.snp)
StartDynamicSolve()
WaitCount(300)
Stop()
SaveSnapshot(c:\SysCAD91\tutorial\start1.snp)
SetTag(PGM1.ResetAll, 1)
RestartHistorian()
SetTag(PGM1.StartSimulationFlag, 1)
StartDynamicSolve()
Wait(3600)
Stop()
GenerateTagReport("c:\SysCAD91\tutorial\SampleReport.xls", *)
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 SetTag 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) 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. ; ================================================================= ; ;------ 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()
