Open Parameters in Packages
The use of packages that contain open parameters requires means for controlling the flow of the open parameters and their values from within the script. A number of rules, commands, and functions are available for this purpose that are explained in this section.
Bubbling of Open Parameters
As it was explained in section about open parameters, an open parameter is requested from the trCAD core program at the first moment it is used in the script. This means that e.g. calling a function of a package can trigger an open parameter of the script to be requested. How does the system handle this request? The default way is, that the request bubbles up from the lower-lying package to the higher lying ones until it turns up in the graphical user interface (GUI) where is can be set by the configurator user:
File "pack1.sps":
Example
open int i
{
name = "My Open Parameter"
descr = "This integer can be set from outside."
value = 3
}
public function f()
{
echo( "The value of i is " + i )
}
Main script file:
Example
#import ( "pack1.sps" )
pack1::f()
In the example, call function f() causes open parameter i to be requested since it is used in the function body. i bubbles up into the main script and further to the user interface. The user will be asked to provide the value of open parameter pack1::i before the output is generated.
However this is not always intended by the author of the higher-level script file. Some ways exist to hinder the bubbling in a controlled manner.
Direct setting of package open parameters
The first and most simple way to avoid bubbling of an open parameter of a lower package is to set it directly by assigning a value. The system memorized the parameter as beeing set and will not request it again when its value is required:
Main script file:
Example
#import ( "pack1.sps" )
pack1::i = 12
pack1::f()
Output
The value of i is 12
The do/catch Command
The purpose of the do/catch command is to call an action and block the eventual bubbling of lower-lying open parameters in a controlled manner. The following example uses it to intercept a bubbling open parameter:
Main script file:
Example
#import ( "pack1.sps" )
do pack1::f()
catch
{
pack1::i = 8
}
Output
The value of i is 8
When the open parameter i bubbles up to the main script, it is caught by the catch command block. The value 8 is inserted directly and the parameter stops bubbling. As a result it does not appear in the GUI any more. The catch block can contain more than one open parameter.
The difference between setting the open parameters directly and using a do/catch construction is that the later case guarantees that the value of every open parameter mentioned in the catch block will be set and every open parameter not present in the catch block bubbles up, independently of their former history.
Resetting a Package
As explained above, the open parameters of a package memorize whether they got set at an earlier time. In addition, the attributes of the open parameters may contain data from earlier execution of the package that may hinder the package to work in an intended way. The following code shows such an example:
File "pack2.sps":
Example
open int i
{
value = 3
name = "j_max"
descr = "The upper boundary of open parameter j."
}
open int j
{
value = 3
name = "An Open Parameter"
descr = "This shall be requested from outside. "
max = i
}
Main script file:
Example
#import ( "pack2.sps" )
echo( "First: " + pack2::j )
do echo( "Second: " + pack2::j )
catch
{
pack2::i = 5
pack2::j = 5
}
Output
First: 3
Second: 3
Surprisingly, the second echo outputs a value of 3 and not the value 5, as one might have expected. In addition, a warning pops up stating that the value range of parameter j got exceeded. What happened here is that the execution of package pack2 got caused by the first call to echo. In that, the maximum boundary of parameter j was set to 3, what is the default value of parameter i. When the second echo gets called inside the do/catch statement, the values of i and j are both correctly set to 5 but pack2 is not executed another time (since it was executed once) and thus the attributes of its open parameters are not set again. As a result, the maximum boundary of j is still fixed to 3 what causes j itself to keep restricted to this value.
Luckily there is an easy way to fix this unintended behavior: the reset command. This resets a package to a state in which it will be executed freshly whenever a public or open parameter or function is requested from it the next time. So modifying the main script to this form:
Main script file:
Example
#import ( "pack2.sps" )
echo( "First: " + pack2::j )
do
{
reset pack2
echo( "Second: " + pack2::j )
}
catch
{
pack2::i = 5
pack2::j = 5
}
Output
First: 3
Second: 5
yields the desired result.
Details of the reset command
The reset command performs the following actions:
- It marks the package as "not executed," ensuring that the package will be re-executed the next time any of its public or open parameters or functions are accessed.
- It resets all open parameters within the package to their "no value set" state, ensuring that they will be requested again if needed.
This ensures that any changes to the open parameters or their attributes are correctly applied the next time the package is executed.
