Open topic with navigation

You are here: Surpac Concepts > Macros > SCL > System and Misc > SclFunction
GEOVIA Surpac

sclFunction

Overview

Using the SclFunction command, you can run other functions within an Scl script. SclFunction commands and arguments are recorded in Scl scripts when the MACRO RECORD START function is executing.

Synopsis

SclFunction $FunctionName $FunctionBody

Description

The SclFunction command executes the FunctionName argument using the arguments defined in the FunctionBody argument.

The FunctionName is the unique name by which the functions are identified. The first stage in creating most Scl scripts is to use the MACRO RECORD START function to record the functions that are required to solve a particular problem.

Recording a sequence of functions in this way will result in a number of SclFunction commands being recorded in an Scl script with the parameters required to replay the script at any time.

The FunctionBody argument describes the parameters that are required for the function and the manner in which the user interface components should be presented to the user during the execution of the script.

Return values

The SclFunction command returns an integer that describes the completion status of function being executed. Possible return values include:

  • $SCL_OK

    • This value is returned if the function completes successfully.

  • $SCL_ERROR

    • This value is returned if the function failed to complete successfully. As well as returning $SCL_ERROR, a TCL exception is generated. Unless specifically handled, exceptions cause the TCL interpreter to fail. Exceptions can be caught and processed using the TCL catch command.

Arguments

  • FunctionName
  • Passed by value. The unique name of the function that is to be executed. These are normally created in the script by first recording a script and executing the functions required by choosing them from menus.
  • FunctionBody
  • Passed by value. The function body defines the parameters to the function. These parameters include the user interface actions that are to be performed during script playback. The FunctionBody is optional if the function has no parameters.

    • In its simplest form FunctionBody takes the form parametername=parametervalue for zero or more parameters. Most functions have a more complex arrangement because of the complexities of the number of parameters that are required to execute the function.

    Aggregate values and repeating forms

    Some parameters are aggregate (multiple) values instead of the more simple single or array values. These aggregate parameters are represented in the form: 

    parametername={ 
 {
   subparam1=value1 
   subparam2=value2
      .        .
      .        .
 }
}

    This form is commonly found to define the parameters for a form, where parametername represents the form identifier and subparam represents a field on the form.

    Braces {} are used to group parameters in such aggregate parameters. The reason for what appears to be a redundant set of braces enclosing such aggregate parameters is to cater for instances where some functions use the same form repeated a number of times to gather inputs for a function. Such repeating forms would be represented like: 

    parametername={ 
 {
   subparam1=value1 
   subparam2=value2
      .        .
      .        .
 }
 {
   subparam1=value1 
   subparam2=value2
      .        .
      .        .
 }
 {
   subparam1=value1 
   subparam2=value2
      .        .
      .        .
 }
}

    Special parameters

    Special parameters may also exist for forms in these representations to define the actions that determine the behaviour of the Guido components that are used to create the user interface. These parameters and their possible values are:

    • _action=apply|display

      • Defines the action that is performed for the form. Permitted values include:

      • apply

        • This is the default if this parameter is not defined. The form will behave as if the apply button were pressed by the user.

      • display

        • The form will be displayed for interactive modification. When the user presses the Apply, or some other button that dismisses the form the script will continue executing.

    • _pause=period

      • This parameter is optional and if present it defines the period in seconds that the form will be displayed if the _action parameter has a value of apply. The default pause period is 2 seconds if not defined explicitly.

    • _error=abort|display

      • This parameter defines the behaviour if an error is found when the _action parameter is set to apply. The type of errors that this parameter manages are those that occur BEFORE the APPLY action has completed.

      • abort

        • This is the default if this parameter is not defined. Execution of the form/function is aborted. The SclFunction command returns $SCL_ERROR as the completion status of the function.

      • display

        • Errors validating inputs on the form cause the form to be displayed to permit interactive modification of form inputs. On dismissing the form execution of the script will continue.

    • _missing=cancel|display

      • This parameter defines the behaviour if an error is found when the _action parameter is set to apply. The type of errors that this parameter manages are those that occur AFTER the APPLY action has completed.

      • cancel

        • This is the default if this parameter is not defined. Execution of the form/function is cancelled. The SclFunction command returns $SCL_ERROR as the completion status of the function.

      • display

        • Errors validating inputs on the form cause the form to be displayed to permit interactive modification of form inputs. On dismissing the form execution of the script will continue.

    Further explanation of the _error and _missing parameters can be found here.

    Inheritance of special parameters

    The special parameters described above have acceptable default behaviour for most circumstances. You may find that it is necessary to change these defaults to achieve your goals. If these special parameters are used for functions that use multiple repeating forms the special parameter values need only be defined once. Subsequent forms for that function will inherit the values defined for earlier forms. This eliminates the need to explicitly define these parameters for each form in a repeating sequence.

    Scalar parameters

    Scalar parameters are expressed in FunctionBody using the following syntax. 

    paramname1=paramvalue1
		paramname2=paramvalue2

    Tables of parameters

    Some Guido forms include tables for entering arrays of values. Each column in the table is represented by a single parameter name and multiple parameter values. Such tables of parameter values are described using the syntax shown below. 

    paramname=table { paramname1 paramname2 paramname3} {
 {param1value1 param2value1 param3value1} 
 {param1value2 param2value2 param3value2} 
 {     .            .            .      }
 {     .            .            .      }
 {     .            .            .      }
}

    Examples

    1. A script created by recording

      This example shows the script exactly as it has been recorded by the software. 

      ######################################################################
#
# Macro Name    : test.tcl
#
# Version       : Surpac V4.0-a
#
# Creation Date : Thu Jun 17 10:06:04 1999
#
# Description   : 
#
######################################################################
set status [ SclFunction "CREATE DTM" {
  frm00126={
    {
      location="gol"
      id="1"
      swadesc="Y"
      break="Y"
      anyspots="N"
      brktest="Y"
      check_distance="0.005"
    }
  }
}]

      This may be extended by a script programmer by including various special parameters to alter the default behaviour when executing the script. For example, to ensure that the form is displayed to permit the entered values to be reviewed or altered include the _action="display" parameter. 

      set status [ SclFunction "CREATE DTM" {
  frm00126={
    {
      _action="display"
      location="gol"
      id="1"
      swadesc="Y"
      break="Y"
      anyspots="N"
      brktest="Y"
      check_distance="0.005"
    }
  }
}]

      An alternative modification might be to use _pause="5" to display the form for 5 seconds before proceeding.

      Another alternative might be to display the form for correction of errors if one or more values on the form are incorrect by using the _error="display" parameter.

    2. Special use of the _action parameter

      Recorded scripts are often used to invoke functions that permit repeated graphics selections in the 3D viewport. For maximum flexibility, it is best to provide the user with interactive control over the points that are to be selected or digitised. After interactive selection of the required points, the script will continue to execute the recorded instructions.

      The portion of a script below shows how the DIGITISER DIGITISE function has been used to digitise and record 5 points. 

      set status [ SclFunction "DIGITISER DIGITISE" {
  digitise_point=table { winx winy objectx objecty objectz } {
    { "-0.400" "0.585" "2450.650" "6738.320" "154.025" }
    { "-0.243" "0.645" "2455.065" "6747.634" "155.694" }
    { "-0.105" "0.435" "2449.745" "6757.838" "157.673" }
    { "0.075" "0.362" "2449.862" "6769.631" "159.868" }
    { "0.169" "0.604" "2459.732" "6773.538" "160.448" }
  }
}]

      When executing the script above it will perform exactly as recorded, that is, 5 points at the specified locations will be created.

      By modifying the script as shown below, the DIGITISER DIGITISE function will be invoked by the script and it will then permit the user to digitise as many points as required until the escape button is pressed, after which the script will continue to execute commands in the script file. 

      set status [ SclFunction "DIGITISER DIGITISE" {
     _action="display"
}]

    3. A function that has no parameters

      This example shows how the result of the SclFunction is assigned to a variable by using the TCL evaluation syntax of [command arguments]. This is how the scripts are recorded. 

      set status [ SclFunction "GRAPHICS" {} ]

    4. Example of using catch to process function execution errors

      This example shows how an exception can be caught to permit script execution to continue if an error in processing a function occurs. 

      if {[catch {set status [ SclFunction "CREATE DTM" {
  frm00126={
    {
      location="pit"
      id="100"
      swadesc="Y"
      break="Y"
      anyspots="N"
      brktest="Y"
      check_distance="0.005"
    }
  }
}]}]} {
  puts "An error occured processing the CREATE DTM function"
}

    5. A function that has one form

      This function shows a non-repeating form and the parameters in that form. 

      set status [ SclFunction "CREATE DTM" {
  frm00126={
    {
      location="pit"
      id="100"
      swadesc="Y"
      break="Y"
      anyspots="N"
      brktest="Y"
      check_distance="0.005"
    }
  }
}]

    6. A complex example with multiple forms and tables

      set status [ SclFunction "ENTITY MODIFY" { 
  frm00231={ 
    { 
      entity_name="ABC1" 
    } 
  } 
  frm00227={ 
    { 
      use_string_ops="Y" 
      string_ops=table { str_attribute str_field str_ndec str_notation 
                         str_symbol str_position str_direction str_bearing 
                         str_distance str_distance_type str_text_height 
                         str_text_angle str_text_angle_type str_horiz_just 
                         str_vert_just str_priority str_pen } { 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "1" } 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "1" } 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "1" } 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "1" } 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "1" } 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "1" } 
        { "field" "STR" "0" "" "" "centre" "none" "0" "0" "actual" "   1.8" 
          "  0.0" "absolute" "centre" "centre" "10" "2" } 
      } 
      use_point_ops="N" 
      use_line_ops="N" 
      use_cliff_ops="N" 
      use_pattern_ops="N" 
      use_colour_ops="N" 
    } 
  } 
}]

Notes

Note: When you use sclFunction and the FunctionName argument is CREATE TABLE, or DELETE TABLE (or DB ADD FIELD when the database is an ODBC database) the database is closed and opened as part of processing. To perform subsequent tasks on the database, you must get the database handle again using the syntax sclDatabases SclGetItem dbHandle 0.

Open topic with navigation