Command Scripts

From SysCAD Documentation
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


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.

  1. the file has an extension .ssc,
  2. only one command is allowed on each line.
  3. Blank lines are allowed.
  4. Lines starting with a semi-colon (;) are ignored.
  5. 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.
  6. 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.
  7. 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.

CommandScriptsDialog.png

Columns:

  • Filename: The name of the command script file.
  • Folder: The path location of the specified command script file.

Buttons:

  • Add ... : Used to add a new command script (.ssc) file to the list. Browse for the location the file and press OK when found. Press Cancel to not add any files.
  • Delete : Used to remove the currently selected file from the list.
  • Edit ... : Used to change filename or path of filename for the currently selected file. This does not open the file for editing purposes.
  • Execute : This button is used to run the selected command script.
  • Done : Closes the dialog box (same as pressing X in top right corner).
  • Edit File : Opens the currently selected command script file in the default text editor for editing.

Tickbox:

  • Log Script Command to Messages Window: Only available in Build 138 or later. 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.
  • Exit(0) - SysCAD will close without saving the project.
  • Exit(1) - SysCAD will save the opened project and then exit.
--- Yes

Project Solve Related Commands

Project Solve - Solve Solve() Available in Build139 and later. Equivalent to “StartSolve()” followed by “WaitTillStop()”. See Example 2
Project Solve - Start Solve StartSolve() Available in Build139 and later. Replaces StartProBalSolve() and StartDynamicSolve()
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 No
Project Solve - Stop Solve StopSolve() Available in Build139 and later. Replaces Stop()
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 (ie 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 (ie 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.
  • For steady state projects, SysCAD stops when the project is solved
  • For dynamic projects, SysCAD stops if user has set a time or iteration count.
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) (Command implemented in Build 138.26203 and Build 139.) Please see Example 4 for more detail.

Set a list of tags in a text file to the specified values. The first row of the file is reserved for headings. Any rows starting with ";" are ignored.
The SysCAD tags must exist. Engineering units may be specified. In Build 139 or later, string tags can also be set.

  • Format set to TagList. The file should be a csv formatted file, first column contains full tag, second column contains required value.
  • Format set to TagTable: The file should be a csv formatted file, first row contains primary tags separated by commas, subsequent rows contain secondary tag followed by required values separated by commas.
Yes
Report - Text File - Export Tags ReportTags(format, templatefile, filename) (Command implemented in Build 138.26203 and Build 139.) Please see Example 4 for more detail.

Reports a list or table of tags in a text file, based on a template file which contains the tags. The first row of the file is reserved for headings. Any rows starting with ";" are ignored.
The SysCAD tags must exist. Engineering units may be specified.

  • Format set to TagList: The template file should be a csv formatted file, with the first column containing a list of full tags. The output file will contain the tags in the first column and the reported values in the second column.
  • Format set to TagTable: The template file should be a csv formatted file with 4 possible keywords on any line.
    • Tags (required): a comma separated list of the primary tags for the table.
    • DataTags (required): a comma separated list of the secondary tags for the table.
    • DataLabels (optional): a comma separated list of descriptive headings for the data tags.
    • Options (optional): a comma separated list of options: H or V primary tags to be horizontal or vertical, C or CnvLabels adds additional column/row of engineering conversion units, N or NoDataTags to not ouput the column/row of DataTags.
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 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 (eg 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

  • SysCAD Build 138.26203 or newer required.
  • This provides an alternative to Excel COM Automation for efficiently getting/setting tags.
  • The advantage of this is significant speed up in reporting
  • The disadvantage is no formatting will be stored (as compared with MS Excel)

The workflow for text file reporting is as follows:

  1. create the input file for any tag to be set into SysCAD.
    • This is similar to the normal Excel Set Tag Report, useful for setting a list of values (such as the project criteria) into the model.
  2. create the template file for reporting values from SysCAD.
    • This is similar to the normal Excel Get Tag Report, useful for reporting a list or table of values.
    • This template file will not be replaced by report generation, a new file will be created.
    • The template file can be stored within the project folder or any other folder.
    • If the file is not stored within the project folder, then subfolder or full folder path should be given.
  3. create the command script file that will instruct SysCAD to do the data transfer.
    • This is similar to the Excel automation step, except we are using command script.
    • User must specify the filename and location of the output file.
    • The output file will be auto-created from the template file provided.

Example of the above has been created for the Gold Example Project (added January 2021), a brief description of the files are given below:

Example Command Script File TestTagTransfer.ssc

;Example Command Script file for settag and gettag report in text file format
;
;== Example for setting a list or Table of Tags to SysCAD == Syntax is:   SetTags(format, filename)
 SetTags(TagList,     Reports\ModelCriteriaInput.csv)

;== Example for getting a list or Table of Tags from SysCAD == Syntax is:   ReportTags(format, templatefile, filename)
 ReportTags(TagList,  CommandScript\csvTemplate\ReportListCriteria.csv,      Reports\ModelCriteriaOutput.csv)
 ReportTags(TagTable, CommandScript\csvTemplate\ReportTableStreamReport.csv, Reports\StreamReport.csv)

Text file Set Tag List Report Example: ModelCriteriaInput.csv (partial)

Tag,Value
SLURRY_IN.QmReqd (t/h),40
Feed_ppm_Set.TC[1].User.Value,40
Feed_ppm_Set.TC[2].User.Value,500
SLURRY_IN.Content.DLockup.[Au(s)].LockupReqd (%),10
CARBON_IN.QmReqd (kg/h),292
CSTR.TankVolume,300

Text file Get Tag List Report Template Example: ReportListCriteria.csv (partial)

Tag
;Plant Feed Characteristics
;Ore Slurry Feed
P_001.Qm (t/h)
P_001.Qo.Calc.GoldinOre_ppm
P_001.Qo.Calc.CuinOre_ppm
P_001.Qo.Lockup.[Au(s)].LockedUp.Frac (%)

;Carbon Feed
P_010.Qm (kg/h)
  • first line is ignored, reserved for Tag
  • lines starting with semicolon ; are ignored, can use this to add in group headings
  • blank lines are allowed

Text file Get Tag Table Report Template Example ReportTableStreamReport.csv (partial)

Tags,P_001,P_002,P_003,P_004,P_005,P_006,P_007,P_008,P_009,P_010
DataTags,GenDesc,Qo.Qm (t/h),Qo.LQm (t/h),Qo.SQm (t/h),Qo.Qv (m^3/h),Qo.LQv (m^3/h),Qo.SQv (m^3/h),Qo.T (dC),Qo.P (bar),Qo.SF (%)
DataLabels,Description,Total,Liquid,Solids,Total @T,Liquid @T,Solids @ T,Temperature,Pressure,%Solids
Options,H,C,,,,,,,,
;Options,V,N,C,,,,,,,
  • Tags, DataTags etc are comma separated (or simply create the file in MS Excel, then save as CSV (comma delimited) (*.csv) format.)
  • lines starting with semicolon ; are ignored
  • blank lines are allowed
  • Options for Horizontal or Vertical table as per normal SysCAD TagTable reports.

Please see the full template files and report files in the Gold Project

  • Command Script file can be found in the \CommandScript subfolder
  • template files can be found in the \CommandScript\csvTemplate subfolder
  • report files can be found in the \report subfolder, with .csv file extension.
    1. The "ModelCriteriaInput.csv" and "ModelCriteriaOutput.csv" files are based on the "Model Criteria" worksheet of the "Gold Model Criteria.xlsx" workbook.
    2. The "StreamReport.csv" file is based on the "Streams" worksheet of the "Gold Model Criteria.xlsx" report.

Distributed Example Projects

There are a number of distributed example projects and files that demonstrate the use command script file. These include:

  1. 02 Features: Command Script Example
  2. 03 Unit Models: Counter Current Washer Project
  3. 03 Unit Models: FEM Simple Examples
  4. Gold Project (added January 2021)