:Revision=14
:html
<<
128.145
GlobalVar-Object|GlobalVar
--
The IP-Object <!RW>GlobalVar makes it possible to use global variables, which are maintained even after the end of an interpreter step.

Global variables are in fact only called 'variables', but have nothing to do with the normal interpreter variables, which must be defined in the VAR-Block. The global variables are not managed by the interpreter step; they are listed in a separate, interpreter-independent list. Each entry in this list represents a global variable and has a certain name, life time, data type and value.

Global variables may be of any type (except <!RW>COMOBJECT) and are referenced by a string. The string indicates the name of the global variable; no differentiation is made between lower- and upper case.

When retrieving a global variable the returned type is always the one which has been previously stored. An automatic conversion e.g. from Real into String does not take place.

Global variables have different 'life times'. 
<ul indent=12>
<li>Globale variables, which were created in system steps (IP_LOOP, IP_BOOT...), will not be deleted while the program is running.</li>
<li>Global variables, which were created in test steps, will be deleted at the end of the test sequence. This behaviour can be changed if a 'life time' is sepcified in the <!RW>GlobalVar.Set.</li>
<li>In addition, there are persistent ('everlasting') global variables, which are defined in the basic setup and neither they or their values are lost even if the progrmm is restarted.</li>
>>
<<
128.145.1
GlobalVar.Set|Set
!128.145.6 - Beispiele
--
<!DEF>
procedure <!TW>GlobalVar.Set (sName : string; .Value : string|real|vector|stringvector [; rScope : real]);
<!TXT>
Sets the global variable <!PW>sName to the specified value.
If such a varibale does not exist, it will be created; if it already exists, it will be overwritten.

<!PW>rScope determines the 'life time' of the variables:
<!STBL>
<!+>rScope<!+>life time<!+>
<!c>1<!><b>Test</b> - the variable is deleted at the end of the test or reset<!>
<!c>2<!><b>System</b> - the variable lives until the end of the programm<!>
<!c>0<br>(default)<!><b>Test</b> if the command is sent in a normal test step<br>
        <b>System</b> if the command is sent in a system step<!>
<!ETBL>

It is not possible to create a <b>persistent</b> global variable from a IP step. This has to be done in the basic setup.

Example:
Assumptions
<ul indent=12>
<li>the variable does not exist</li>
<li>normal test step</li>
</ul>

<!CODE>
GlobalVar.Set ('X', 111);
<!TXT>
Creates a global variable with the name 'X', having a value of 111 and the life time 'Test'

<!CODE>
GlobalVar.Set ('X', 222, 2);
<!TXT>
Changes the value of the global variable 'X' to 222 and its life time to 'System'

<!CODE>
GlobalVar.Set ('X', 333);
<!TXT>
Changes the value of the global variable 'X' into 333 but it does not modify its life time 
>>
<<
128.145.2
GlobalVar.Exists|Exists
!128.145.4 - GetTypeCode
!128.145.6 - Example
--
<!DEF>
function <!TW>GlobalVar.Exists (sName: string) : real;
<!TXT>
Returns <!RW>TRUE, if a global variable with this name exists (= has been previously created).
>>
<<
128.145.3
GlobalVar.Get|Get
!128.145.6 - Beispiele
--
<!DEF>
function <!TW>GlobalVar.Get (sName : string [; .DefaultValue : string|real|vector|stringvector]) : string|real|vector|stringvector;
<!TXT>
Returns the value of the global variable <!PW>sName. If the variable does not exist, the <!PW>DefaultValue will be returned; if the default value is not specified either, then a run time error is generated.
>>
<<
128.145.4
GlobalVar.GetTypeCode|GetTypeCode
!128.145.2 - Exists
!128.145.5 - Example
--
<!DEF>
function <!TW>GlobalVar.GetTypeCode (sName : string) : real;
<!TXT>
Determines the type of the global variable <!PW>sName:

<!STBL>
<!>0<!>no such variable<!>
<!>1<!>Real<!>
<!>2<!>String<!>
<!>3<!>Vector<!>
<!>4<!>StringVector<!>
<!>-1<!>not implemented format<!>
<!ETBL>
>>
<<
128.145.5
GlobalVar.Delete|Delete
--
<!DEF>
procedure <!TW>GlobalVar.Delete (sName : string);
<!TXT>
Removes the global variable <!PW>sName or all Variables which matched with the filter <!PW>sName.

The rules for the filter:

- The * stands for any count of chars (0-infinite)
- The ? stands for one arbitrary char
- Within of [] a set of chars are definable.

Here some examples:
- Test*     = stands for all Global Variables which starts with Test and 0 or more chars.
- Test?     = stands for all Global Variables which starts with Test and one more char.
- Test[0-9] = stands for all Global Variables which starts with Test and one number.
- Test[abc] = stands for all Global Variables which starts with Test and a a, b oder c.

Persistent ('everlasting') global variables, which are defined in the basic setup, can not be deleted with the interpreter.
>>
<<
128.145.6
GlobalVar.Examples|Examples
--
<h4>1. Saving a value under a fixed name:</h4>
<!CODE>
rVSoll:= 2.54 * ME3000.ADW.Get (1);
GlobalVar.Set ('grVSoll', rVSoll);
<!TXT>
Creates a global variable with the name 'grVSoll'. This method provides a good readability of the source text, but it is not very flexible, as far as modifications of the variable names are concerned.

<h4>2. Saving a value under a name from the parameter data base</h4>
<!CODE>
PARAMETER
  psGVarName : (12, string, 'Name of Global Variable', '');
  :
VAR
  rVSoll : real;
  :
STEP
  :
  rVSoll:= 2.54 * ME3000.ADW.Get (1);
  GlobalVar.Set (psGVarName, rVSoll);
<!TXT>  
The name of the created global variable corresponds to the value of the parameter from the data base. This method provides a good flexibility, but makes the source text less readible. The actual name of the VGlobale variable is determined based on the parameters.

<h4>3a. Saving a value under a dynamically generated name</h4>
Assumption: A Multi-Barcode-Scanner returns 1 to n barcodes. These barcodes are saved in the global variables.
<!CODE>
VAR
  sBarCode,
  sGVName : string;
  rBCAnzahl : real;
STEP
  RS232.Send ('BCReader', '<D>');               // Trigger scanner
  rBCAnzahl:=0;                                 // nothing yet
  repeat
    sBarCode:=RS232.Get('BCReader');            // read BarCode 
    if sBarCode<>'' then begin                  // if there is one
      inc (rBCAnzahl);                          // increase number
      sGVName:='BC'+Str(rBCAnzahl);             // create name (BC1, BC2 ...)
      GlobalVar.Set (sGVName, sBarCode);        // store barcode
    end;
  until sBarCode='';                            // until there isn't any
  GlobalVar.Set ('BCAnzahl', rBCAnzahl);        // store the number!
end;
<!TXT>

<h4>3b. Read out the value under a dynamically generated name</h4>
<!CODE>
VAR
  sBarCode,
  sGVName : string;
  rBCAnzahl,
  rBCNum : real;
STEP
  rBCAnzahl:=GlobalVar.Get ('BCAnzahl', 0);     
  for rBCNum:=1 to rBCAnzahl do begin
    sGVName:='BC'+Str(rBCNum);                  // create name (BC1, BC2 ...)
    sBarCode:=GlobalVar.Get (sGVName);          // get
    :           
  end;

  // works without additional variables as follows:
  for rBCNum:=1 to GlobalVar.Get ('BCAnzahl', 0) do begin
    sBarCode:=GlobalVar.Get ('BC'+Str(rBCNum));         // get
    :           
  end;
end;
<!TXT>
>>
<<
128.145.7
GlobalVar.Get.Comment|Get.Comment
--
<!DEF>
function <!TW>GlobalVar.Get.Comment (sName : string) : string;
<!TXT>
Returns the comment of the globale variable withg the name <!PW>sName. If the variable doesn't exist or the comment is empty, an empty string will be returned.
>>
<<
128.145.8
GlobalVar.Set.Comment|Set.Comment
--
<!DEF>
procedure <!TW>GlobalVar.Set.Comment (sName : string; sComment : string);
<!TXT>
Sets the comment of the global variable with the name <!PW>sName to <!PW>sComment. If the variable doesn't exist, nothing happens.
>>
<<
128.145.9
GlobalVar.First|First
!128.145.10
--
<!DEF>
function <!TW>GlobalVar.First : string;
<!TXT>
Returns the name of the first global variable or '', if no global variable exists.

For an example, see <!RW>Global.Next
>>
<<
128.145.10
GlobalVar.Next|Next
!128.145.9
--
<!DEF>
function <!TW>GlobalVar.Next : string;
<!TXT>
Returns the name of the next global variable or '',if no more global variable exists.

May be used together with <!RW>GlobalVar.First to scan all existing global variables.

<!CODE>
var
  s : string;
begin
  s:=GlobalVar.First;
  while s<>'' do begin
    Debug.Show (1, s,'=',GlobalVar.Get(s), 'Info =', GlobalVar.Get.Comment (s));
    s:=GlobalVar.Next;
  end;
end;
>>
