Parameters

$ parameters

It would be unnecessary work to define a separate panel or compound widget (graphics object) for identical elements in a system. In order to avoid this, you can use panels. Dollar parameters ($) are provided in Control scripts for referencing panels (see the GEDI documentation ). These parameters are needed if you want to define a panel just once, but this same panel should be used more than once and in different ways in other panels.

Take for example a system with three motors of the same type. This motor type with its associated parameters such as required speed, actual speed, rated power etc., is defined in a dedicated "motor" panel, and inserted as often as necessary as a reference in the system panel. In the script it is not possible to access a particular "motor" data point variable, since there are three different motors and these will obviously have different values. Instead you can specify $ parameters which are resolved in the GEDI in a dialog box and which specify the data point actually used.

Syntax

The leading $ can be followed by any number of digits from 0-9, or a character string. This string must either begin with a lowercase letter, a...z, an uppercase letter A...Z or an underline_ character. Examples of valid names are: $plant, $_PLANT, $Valve_01, $Plant_01Valve. Special characters are not allowed. The name can be of any length.

The character after the dollar sign ($) sign is interpreted as the display data type and capitalised names (such as $IMAGE or $BOOL) from the list below can appear anywhere in the name, they are even case-insensitive. If the first characters are lowercase, and are matching with a "data type" from the list, these will be shown as such. Otherwise a case insensitive search will be done with the uppercase data types from the list. The data type is chosen in the order shown in the table below.

Figure 1. Reference Definition

Small characters after the $ parameter win (3rd column), then a type (described in the table) is searched for in the rest of the name (1st column). If nothing was found, "[unknown]" is displayed (2nd column).

CAUTION: Note that the data type for the dollar parameters is only a "display data type" and the actual data type of a data point is not changed. For dollar parameters, the data type is always a string.
First characters (Lowercase) Type
$dpe Data point element
$dpa Data point attribute
$dpt Data point type
$dp Data point
$tp Period in Seconds
$td Date
$tt Time
$ti Point in time
$i Int
$f Float
$s String
$u Unsigned
$c Char
$b Bool
$COLOR Color
$PANEL Panel
$DPE Data point element
$DP Data point
$FONT Font
$RULE Rule
$MSGC Message catalogue
$MSGT Message text
$IMAGE Image
$UINT Uint (positive integer value)
$LANGSTRING Language string
$BOOL Bool
$BIT32 Bool (Bit pattern 32)
BIT64 Bool (Bit pattern 64)
$CHAR Char (1 byte)
$DOUBLE Double (A floating point value)
$FLOAT Float (A floating point value)
$INT Integer value (32 bit)
$ULONG Ulong (positive integer value 64 bit)
$LONG Long (Integer value 64 bit)
$STRING String
$MIXED Mixed (Contrary to anytype the variable type mixed gets each time a new type.)
$MAPPING A Mapping (Mapping saves arbitrary key/value pairs.)
$TIME Time (internal time format)
$UNSIGNED Unsigned (positive integer value)

A dollar parameter ($) is converted into a string constant at runtime:

string x;
x = $valve+ "123" (where $valve is passed as "abc")
//becomes
x = "abc" + "123"

Therefore, you can work with dollar parameters($) in exactly the same way as with string constants.

Example

dpSet($Motor+".Reqdvalue:_original.._value", MOTOR_REQD);

Optional Parameters

You may define optional parameters for functions. This means that these parameters must not be declared when calling the function.

Example

myFunc(int a, bool b = TRUE)
{
  //....
}

A function with 2 parameters is declared. Here the second parameter can be left out when calling the function. If a parameter is not defined, the script uses the default value "TRUE". Therefore, in this example the parameter "bool b = TRUE" is declared as an optional parameter since a value was already assigned to the parameter.

After an optional parameter, other optional parameters can be declared. However, you must not declare a non-optional parameter after an optional parameter!

The function can be called as follows:

myFunc(3, FALSE); // both parameters
myFunc(3); //only the fixed first parameter. The 2. is by default "TRUE"

Optional parameters can only be constants NOT results of an expression! See the following example:

myFunc(int a, string b = (string)TEST)
{
  DebugN("b="+b);
}
main()
{
  myFunc(1, "Hello");   //works
  myFunc(1);            //works
}
//--------------------------------------
myFunc(int a, string b = "Test")
{
  DebugN("b="+b);
}
main()
{
  myFunc(1, "Hello");  //works
  myFunc(1);           //works
}

Note that you can pass parameters that were not defined before, when calling a control function. Note, however, that the number and type of the parameters has to be correct.

Optional parameters of the data type langString are not allowed! The default value will not be passed!

Reference parameters

If a function is declared with test (int &a, float &b, string c), then the parameters a and b are known as reference parameters. This means that the arguments are also changed in the calling function. In the function call, only variables that are also suitable for being assigned values can be passed as reference parameters. These are simple variables or variables with an index for dyn_types. Implicit conversion is supported here.

If a function expects a reference and then receives invalid parameters, an exception for the invalid parameters is thrown.

If a function has a reference parameter (&), always call the function with the required type. If the function is not called with the required parameter type, an error will occur.

Example with A reference parameter:

main()
{
  int a = 3;
  f(a);
  DebugN(a); //4 is output here
}
//...
f (int &x)
{
  x = 4;
}

Example without A reference parameter:

main()
{
  int a = 3;
  f(a);
  DebugN(a); //3 is output here
  //...
}
f(int x)
{
  x = 4;
}

Function with AN arbitrary number of parameters

CTRL functions may have an arbitrary number of parameters. The arbitrary number of parameters is defined via va_list. va_start sets the parameters into the va_list variable. va_arg is like an iterator and it always handles the next parameter of the va_list variable. va_end stops the handling of the parameter list.

Va_list does not require a format string (like C) in order to determine the number and types of the parameters. This information is already known. You do not need to specify the types of the different parameters. You do not have to specify where the parameters in the va_list begin either.

The following example shows how to pass different types of parameters and how to access the parameters in the va_list via va_start, va_arg and va_end.

main()
{
  subfunc("Example1", 5, 'A'); //Pass the parameters
  subfunc("Example2", 'B', "Characters");
}

/* You do not have to pass the parameter types but create a prefix string */
void subfunc(string prefix, ...)
{
  int i, len;
  va_list parameters;

  //Iterate via va_arg
  DebugN("Iterate:");
  len = va_start(parameters);  //Returns the number of parameters

  for (i = 1; i <=len; i++)
    DebugN(prefix, va_arg(parameters)); //Print the parameters
  va_end(parameters); //va_end stops the handling of the list

  //Optional access to the parameters
  DebugN("Optional access");
  len = va_start(parameters);  //Returns the number of parameters

  for (i = 1; i <=len; i++)
    DebugN(prefix, parameters[i]); //Print the parameters
  va_end(parameters); //va_end stops the handling of the list
}