Simple interaction during script execution
Unless changes are made to the script prior to executing the script, the script will proceed from start to finish without any opportunity to intervene and change the scripts behaviour. This is automation at its most simple. This behaviour shows how the script plays back the recorded functions.
Scripts become more useful when the automation is melded with a degree of interaction so that it becomes possible to automate a task but to do so with different data each time the script is executed. Using this feature of scripts is how you can eliminate a large amount of repetitive work.
The first step in introducing simple interaction into scripts is to use the Guido extensions to create user interface components for forms and menus.
SCL includes a number of commands that permit Guido components to be used to customise the SCL scripts. This is best demonstrated by example. The example that will be used is to create contours of some data in a string file. The steps required for this example include:
- Record the steps of creating the DTM and contouring the DTM
- Create a GUIDO form to select the file and contour interval required
- Modify the recorded script to use the GUIDO form and replace the fixed filenames and contour interval with variables.
- An exercise to make the script even more general
The recorded script
The script below has been created by recording the function that creates a DTM of a string file and the function that creates a string file of contours from the DTM.
######################################################################
#
# Macro Name : test.tcl
#
# Version : Surpac V4.0-A
#
# Creation Date : Thu Jun 17 11:19:04 1999
#
# Description :
#
######################################################################
set status [ SclFunction "CREATE DTM" {
frm00126={
{
location="pit"
id="100"
swadesc="Y"
break="Y"
anyspots="N"
brktest="Y"
check_distance="0.005"
}
}
}]
set status [ SclFunction "CONTOUR EXTRACT" {
frm00048={
{
dtmloc="pit"
dtmid="100"
dtmfld="Z"
}
}
frm00049={
{
deftype="I"
conmin="147.39"
conmax="157.692"
ci="2"
}
}
frm00050={
{
cloc="con"
cid="1"
index="N"
contval="N"
}
}
}]
|
Changes to be made to enhance automation
After recording a script may be played back to reproduce the tasks that have been recorded. This has little value though unless some changes are made to the script so that different data files can be processed on each ocassion that it is executed.
The changes to be made to this script to make it more useful as a general contouring tool for any string file include:
- Use variables where appropriate
- Use programme determined values
- Use a custom form
1. Use variables where appropriate
To be generally useful this script needs to be able to process any string file so that a DTM and be created and contour strings extracted. The modified script (minus the header comments) with the changes in bold is shown below.
set location pit
set fileid 100
set interval 2
set contourlocation con
set status [ SclFunction "CREATE DTM" {
frm00126={
{
location=$location
id=$fileid
swadesc="Y"
break="Y"
anyspots="N"
brktest="Y"
check_distance="0.005"
}
}
}]
set status [ SclFunction "CONTOUR EXTRACT" {
frm00048={
{
dtmloc=$location
dtmid=$fileid
dtmfld="Z"
}
}
frm00049={
{
deftype="I"
conmin="147.39"
conmax="157.692"
ci=$interval
}
}
frm00050={
{
cloc=$contourlocation
cid=$fileid
index="N"
contval="N"
}
}
}]
|
The changes made to the script permit the string file from which the DTM is to be created to be defined once only in the variables location and fileid. The contour interval is assigned to the interval variable and the location for the contour string file is defined in the contourlocation variable.
These changes while useful still fall short of making the script generally useful. The changes made in this step though show how a variable may be assigned a value and then used in a number of instances in the script where appropriate.
2. Use programme determined values
During the course of execution, some functions perform a certain amount of processing on data and then require further inputs to complete processing. On these ocassions it is common that the values for some of the further inputs are data dependant and so require special consideration when writing scripts.
The CONTOUR EXTRACT function is a good example of this. The contour minimum and contour maximum parameters (conmin and conmax) in the script are assigned default values by the programme and these are presented on the form for your convenience.
The most useful treatment of such parameters that have a data dependant default value is to remove them from the script completely. In this way the parameters will acquire the programme determined default value and still be pertinent to the data being processed.
The script showing the removal of the conmin and conmax parameters is:
set location pit
set fileid 100
set interval 2
set contourlocation con
set status [ SclFunction "CREATE DTM" {
frm00126={
{
location=$location<
id=$fileid
swadesc="Y"
break="Y"
anyspots="N"
brktest="Y"
check_distance="0.005"
}
}
}]
set status [ SclFunction "CONTOUR EXTRACT" {
frm00048={
{
dtmloc=$location
dtmid=$fileid
dtmfld="Z"
}
}
frm00049={
{
deftype="I"
# remove these lines by making them comments or by deleting them
# this is done so that we use data dependant min and max values
# conmin="147.39"
# conmax="157.692"
ci=$interval
}
}
frm00050={
{
cloc=$contourlocation
cid=$fileid
index="N"
contval="N"
}
}
}]
|
3. Use a custom form
While this script is gradually becoming more useful, there is still one major step that is required to create a generally useful script that can be used to create a DTM and contour strings of almost any data.
The change required to enable this is that a custom designed form must be presented to get values for the variables that have been used in the script.
Recall that the variables used so far in this script are, location, fileid, interval and contourlocation. At present, each time this script is used to createa DTM and extract contour strings the script must be edited and the values for these variables must be changed. This is an uneccessary step and it can be replaced by using Guido extensions to SCl.
The Guido extensions permit a form to be created and used during the execution of thes script so that values for variables can be obtained during script execution. This avoids the need to edit the script each time it is to be used.
4. An extension exercise
Finally a suggestion for how this script can be made a little more useful.
When creating a DTM you have the ability to determine which strings are used as breaklines and which strings are used as spot-heights. The script that has been developed so far assumes that all strings will be used as breaklines.
This of course may restrict the usefulness of the script as is may be incorrect, or even impossible to create a DTM from some files in this manner.
The exercise then has two parts to it. These are:
- Modify the custom form created in the previous step to permit entry of an optional spot-height string range
- Modify the script to use the optional spot-height string range
A tip for the first part of the exercise is to use a GuidoCheckBox and a dependency to only accept entry of the spot-height string range when it is appropriate.
Further examples of simple interactive modifications of forms
The following examples have been prepared to describe a range of other useful and commonly used features when developing SCL scripts that involve modifications to the basic user interface actions.
The examples below show the following features:
- Displaying forms during fast motion execution
- Displaying forms when entered data is invalid
- Variable substitution within a table of values
5. Displaying forms during fast motion execution
When scripts are executed you may choose to have the forms displayed (slow motion) or not (fast motion) subject to the setting of the Slow motion playback checkbox on the Macro playback form.
When executed in fast motion none of the forms are displayed, unless they have been specially modified with the _action parameter. Fast motion execution of scripts guarantees the fastest performance and with large complex scripts this is the recommended manner of execution.
During the development of scripts it is usually necessary to spend some time fixing coding errors within the script. This is difficult if using fast motion execution. Under these circumstances slow motion execution proves to be very useful.
When executed in slow motion all forms are displayed for a brief period to permit the contents of the forms to be viewed. It is not possible however to modify the content of the forms during slow motion execution. Slow motion execution slows down the execution of scripts significantly. Consequently this feature is typically only used during the development of scripts or during training and demonstration exercises.
Even during fast motion execution it is sometimes necessary to cause some forms to be displayed to permit interaction before proceeding. This is possible with the special _action parameter that controls the behaviour of the forms regardless of whether slow or fast motion playback is being used.
The _action parameter may be set to one of two possible values:
- apply
- display
This is the default value assumed for the _action parameter if it is not explicitly defined. By assigning this value to the _action parameter the form will behave as if the Apply button had been pressed.
By setting the _action parametr to this value the form will be displayed to permit interactive modification of the form contents. The form will be displayed, permitting values to be changed, until you press either the Apply or Cancel buttons. By pressing the Apply button script execution will continue. If the Cancel button is pressed the script will most likely terminate prematurely.
A script example is shown below that has been modified with the _action=display parameter to force the form to be displayed even if executing in fast motion. In particular note the location of the _action parameter. It is located within the same set of braces that enclose all other parameters for the form.
set status [ SclFunction "CREATE DTM" {
frm00126={
{
_action=display
location="pit"
id="100"
swadesc="Y"
break="Y"
anyspots="N"
brktest="Y"
check_distance="0.005"
}
}
}]
|
Some functions use more than one form to gather the inputs for the function. It is possible to use the _action paremeter differently for each discrete form within such functions. The example below demonstrates this. The second form has been modified with the _action=display parameter while the first form, unmodified as it is, uses the default apply action.
set status [ SclFunction "MAP MODIFY" {
frm00331={
{
map_name="DH SECTION"
}
}
frm00230={
{
_action=display
main=table { entity_name location id_range string_range segment_range } {
{ "DH TRACE" "dhx" "6800" "1" "" }
{ "DH TRACE NO TOP" "dhx" "6800" "2" "" }
{ "DH TRACE NO BOT" "dhx" "6800" "3" "" }
{ "DH TRACE NO TOPBOT" "dhx" "6800" "4" "" }
{ "DH LABEL" "dhx" "6800" "5" "" }
{ "DH EOH DEPTH" "dhx" "6800" "5" "" }
{ "DH ASSAY1 RHS/PN2" "dhx" "6800" "11" "" }
{ "DH ASSAY1 RHS/PN3" "dhx" "6800" "12" "" }
{ "DH ASSAY1 RHS/PN4" "dhx" "6800" "13" "" }
{ "DH ASSAY1 RHS/PN5" "dhx" "6800" "14" "" }
{ "DH ASSAY1 RHS/PN6" "dhx" "6800" "15" "" }
{ "DH ASSAY2 RHS/PN2" "dhx" "6800" "11" "" }
{ "DH ASSAY2 RHS/PN3" "dhx" "6800" "12" "" }
{ "DH ASSAY2 RHS/PN4" "dhx" "6800" "13" "" }
{ "DH ASSAY2 RHS/PN5" "dhx" "6800" "14" "" }
{ "DH ASSAY2 RHS/PN6" "dhx" "6800" "15" "" }
{ "DH GEOLOGY LHS" "dhx" "6800" "70" "" }
{ "ROCK FILL" "dhx" "6800" "71" "" }
}
}
}
}]
|
6. Displaying forms when entered data is invalid
During the execution of a script errors are sometimes made that prevent entered data from passing the validation requirements of the function. When this occurs the form and function normaly terminate with an SCL_ABORT code that, unless specifically trapped, will cause the script to terminate.
Depending on the form, validation of the form parameters may be performed before the final APPLY action of the form is completed or, validation may be performed after the APPLY action is completed but before the function can proceed. The type of validation implemented for a form will determine which method you must use to ensure that the form is displayed for interactive modification to correct the errors.
To enable such interactive correction of errors during script execution either the _error or _missing parameters or both, depending on the type of validation requirements, are used. These parameters determine the behaviour, during script execution, when data validation errors are encountered on a form.
The problem for the script author is to determine when it is appropriate to use the _error or _missing parameter or when it is appropriate to use both. There are good reasons why the two parameters exist although it will probably only confuse the issue to explain it in detail here. The best advice therefore is to use both parameters if you plan to manage errors that may exist in the parameters that are entered on a form.
The _error parameter may be set to either of the following values:
- abort
- display
This is the default value for the _error parameter if it is not explicitly defined. When set to this value the form will return the SCL_ABORT code that will ultimately cause the script to terminate prematurely unless it is trapped.
By setting the _error parameter to this value any validation errors in form parameters that occur BEFORE the APPLY action is completed will cause the form to be displayed for interactive correction regardless of whether slow or fast motion execution is being used. The form will be displayed until you press either the Apply or Cancel buttons. By pressing the Apply button the script execution will continue. If the Cancel button is pressed the script will most likely terminate prematurely.
The _missing parameter may be set to either of the following values:
- cancel
- display
This is the default value for the _missing parameter if it is not explicitly defined. When set to this value the form will return the SCL_ABORT code that will ultimately cause the script to terminate prematurely unless it is trapped.
By setting the _missing parameter to this value any errors in form parameters that occur after the APPLY button action has been completed will cause the form to be displayed for interactive correction regardless of whether slow or fast motion execution is being used. The form will be displayed until you press either the Apply or Cancel buttons. By pressing the Apply button the script execution will continue. If the Cancel button is pressed the script will most likely terminate prematurely.
An example is shown below of a script modified with the _error=display parameter to force the form to display if validation errors are encountered.
set status [ SclFunction "CREATE DTM" {
_missing=display
frm00126={
{
_error=display
location="pit"
id="100"
swadesc="Y"
break="Y"
anyspots="N"
brktest="Y"
check_distance="0.005"
}
}
}]
|
7. Variable substitution within a table of values
Some functions require the entry multiple values for a single parameter. This presents a slightly more complex script than the simpler case where there is only a single value for each parameter.
The example below shows how the parameters for such a form must be modified if variable substitution for parameters within the table are reqired.
set section 3560
set status [ SclFunction "MAP MODIFY" {
frm00331={
{
map_name="DH SECTION"
}
}
frm00230={
{
_action=display
main=table { entity_name location id_range string_range segment_range } {
{ "DH TRACE" "dhx" "$section" "1" "" }
{ "DH TRACE NO TOP" "dhx" "$section" "2" "" }
{ "DH TRACE NO BOT" "dhx" "$section" "3" "" }
{ "DH TRACE NO TOPBOT" "dhx" "$section" "4" "" }
{ "DH LABEL" "dhx" "$section" "5" "" }
{ "DH EOH DEPTH" "dhx" "$section" "5" "" }
{ "DH ASSAY1 RHS/PN2" "dhx" "$section" "11" "" }
{ "DH ASSAY1 RHS/PN3" "dhx" "$section" "12" "" }
{ "DH ASSAY1 RHS/PN4" "dhx" "$section" "13" "" }
{ "DH ASSAY1 RHS/PN5" "dhx" "$section" "14" "" }
{ "DH ASSAY1 RHS/PN6" "dhx" "$section" "15" "" }
{ "DH ASSAY2 RHS/PN2" "dhx" "$section" "11" "" }
{ "DH ASSAY2 RHS/PN3" "dhx" "$section" "12" "" }
{ "DH ASSAY2 RHS/PN4" "dhx" "$section" "13" "" }
{ "DH ASSAY2 RHS/PN5" "dhx" "$section" "14" "" }
{ "DH ASSAY2 RHS/PN6" "dhx" "$section" "15" "" }
{ "DH GEOLOGY LHS" "dhx" "$section" "70" "" }
{ "ROCK FILL" "dhx" "$section" "71" "" }
}
}
}
}]
|