Function Define
Syntax: Function Define(sName As String, bCreate As Boolean, bNameChanged As Boolean) As Boolean
The main purpose of this function is to define the result type of a template and to customize the created result item. The Define method is called when a new template is created from the Template Based Post Processing Dialog or when the settings of an existing template are to be changed.
Usually this function will show a dialog box allowing the user to customize the settings of the result template. These settings can then be stored by using StoreScriptSettings commands. The framework ensures that these stored settings will be available whenever a Define or Evaluate method is called from the framework.
The variable 'bCreate' is True when the Define method is called for the first time, i.e. when a new template is defined. If the Define method is called to modify an existing template, 'bCreate' will be false. This can be done for instance by clicking on the "Settings..." - button in the Template Based Postprocessing Dialog.
The variable 'sName' contains the name of the result item that will be created on template evaluation. The result name is automatically generated by the framework. If desired, it may be changed within the Define function by assigning the a string to the variable 'sName'.
In case you modified the name of the result item, the argument 'bNameChanged' will be True when the Define method is called again. Considering the value of 'bNameChanged', further modifications of the result name within the Define function may be switched off to keep the result name unchanged.
Only in the case that the Define function changes 'sName' again (out-sName <> in_sName), the 'bNameChanged'-value will be set back to false, until you again manually change it.
Furthermore it is necessary to call the method StoreTemplateSetting( "TemplateType", string Type ) within the Define function to tell the framework the type of the result template. The following table shows which values are allowed for 'Type', which evaluation method is then called and which result type or result object is expected to be returned.
Type |
Evaluation method called by framework |
expected return type |
"0D" |
Evaluate0D |
double |
"1D" |
Evaluate1D |
Result1D object |
"1DC" |
Evaluate1DComplex |
Result1DComplex object |
"M0D" |
EvaluateMultiple0D |
double |
"M1D" |
EvaluateMultiple1D |
Result1D object |
"M1DC" |
EvaluateMultiple1DComplex |
Result1DComplex object |
Note: The Define function may not be omitted and it needs to call "StoreTemplateSetting".
Function Evaluate0D
Syntax: Function Evaluate0D() As Double
The result of the 0D evaluation is required to be a single double value that needs to be assigned to the function name.
Note: This function is necessary if the template type was set to "0D".
Function Evaluate1D
Syntax: Function Evaluate1D() As Object
The result of the 1D evaluation is required to be a Result1D object a that needs to be assigned to the function name.
Note: This function is necessary if the template type was set to "1D".
Function Evaluate1DComplex
Syntax: Function Evaluate1DComplex() As Object
The result of the 1DComplex evaluation is required to be a Result1DComplex object that needs to be assigned to the function name.
Note: This function is necessary if the template type was set to "1DC".
Function EvaluateMultiple0D
Syntax: Function EvaluateMultiple0D(nCount As Long, sName As String, sTableName As String) As Double
This function can be used to create multiple table results from only one result template. The variable 'nCount' contains the number of the current iteration as a one-based index. The variable 'sName' contains the result name of the template that is being evaluated. The variable 'sTableName' is expected to be set within the EvaluateMultiple0D - function and it defines the name of the table that will be created out of the returned result value (which, in contrast to the single evaluation functions, may be different from 'sName') The framework keeps calling the function as long as a nonempty string is assigned to the variable "sTableName".
The result of the multiple 0D evaluation is required to be a double value that needs to be assigned to the function name.
Note: This function is necessary if the template type was set to "M0D".
Function EvaluateMultiple1D
Syntax: Function EvaluateMultiple1D(nCount As Long, sName As String, sTableName As String) As Object
This function can be used to create multiple table results from only one result template. The variable 'nCount' contains the number of the current iteration as a one-based index. The variable 'sName' contains the result name of the template that is being evaluated. The variable 'sTableName' is expected to be set within the EvaluateMultiple1D - function and it defines the name of the table that will be created out of the returned result value (which, in contrast to the single evaluation functions, may be different from 'sName') The framework keeps calling the function as long as a nonempty string is assigned to the variable "sTableName".
The result of the multiple 1D evaluation is required to be a Result1D object that needs to be assigned to the function name.
Note: This function is necessary if the template type was set to "M1D".
Function EvaluateMultiple1DComplex
Syntax: Function EvaluateMultiple1DComplex(nCount As Long, sName As String, sTableName As String) As Object
This function can be used to create multiple table results from only one result template. The variable 'nCount' contains the number of the current iteration as a one-based index. The variable 'sName' contains the result name of the template that is being evaluated. The variable 'sTableName' is expected to be set within the EvaluateMultiple1DComplex - function and it defines the name of the table that will be created out of the returned result value (which, in contrast to the single evaluation functions, may be different from 'sName') The framework keeps calling the function as long as a nonempty string is assigned to the variable "sTableName".
The result of the multiple 1DComplex evaluation is required to be a Result1DComplex object that needs to be assigned to the function name.
Note: This function is necessary if the template type was set to "M1DC".
Definition of Variables
Use the StoreScriptSetting, GetScriptSetting, GetTreeNameScriptSetting and StoreTreeNameScriptSetting VBA commands to store and restore data. StoreTreeNameScriptSetting is intended to store tree item names, e.g. "Tasks\S-Parameters1". Settings stored with this method will be automatically adjusted if the corresponding tree item is renamed or moved, so that they still refer to the same object. This also includes the case when a template using this setting is part of a task hierarchy that is moved. If a template using this setting is part of a task hierarchy that is copied, and the referenced object is copied as well, then the template setting will also be adjusted to point to the copied object. It will not be adjusted if the referenced object is not copied. The following items will be automatically adjusted: Blocks, tasks, external ports and probes.
For testing the macros outside the postprocessing framework (e.g. inside the macro editor) the ActivateScriptSettings and ClearScriptSettings commands can store, restore and reset the script setting data base. See VBA Macro Language Overview for details.
See also
Template Based Post Processing Overview, Template Based Post Processing Dialog, VBA Macro Language Overview