Postprocessing Template Layout

The template based post processing is a convenient way to automate various post processing steps to obtain 0D, 1D and 1D complex results.

Each template is defined as a VBA macro in a single file with the extension 'rtp'. All these files are located in subfolders of the folder 'Result Templates' within the global library path. The Template Based Post Processing Overview contains more information about using result templates.

A VBA macro for template-based post processing consists of the following special functions that will be called by the framework:

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".

The following functions will be automatically called by the framework when the result item needs to be evaluated. This usually when the corresponding postprocessing task is executed or if the user has forced evaluation from the Template Based Post Processing Dialog box. Which of the functions will be called depends on the template type that was set in the Define method. The framework will automatically restore the script settings that have been stored by the Define function, if any.

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.