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 first lower case character after the dollar sign ($) sign is interpreted as the data type. Otherwise the data type is automatically defined as undefined.

1. First character	Type
   $b	Bool
   $c	Char
   $f	Float
   $i	Int
   $s	String
   $u	Unsigned

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

Example

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
}