:Revision=23
:HTML
<<
120
Internal Routines Without IP-Object|Internal Routines
$Open
--
The internal routines do not belong to any interpreter-object (IP-Object); they are executed directly by the interpreter core.
>>
<<
120.1
Internal Functions without IP-Object|Internal Functions
>>
<<
120.1.1
Internal Numerical Functions|Numerical
>>
<<
120.1.1.1
Round
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Round (rX : real) : real;
<!TXT>
Rounds the value <!PW>rX to the next integer. If <!PW>rX is exactly between two integers, then it will be rounded towards the integer with the higher absolute value (0.5 -> 1, -0.5 -> -1).
>>
<<
120.1.1.2
Frac
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Frac (rX : real) : real;
<!TXT>
Returns the fractional part of <!PW>rX (the part after the decimal place).
>>
<<
120.1.1.3
Int
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Int (rX : real) : real;
<!TXT>
Returns the integer part of <!PW>rX (the part before the decimal place).
>>
<<
120.1.1.4
Abs
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Abs (rX : real) : real;
<!TXT>
Returns <!PW>rX without algebraic signs
>>
<<
120.1.1.5
Sign
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Sign (rX : real) : real;
<!TXT>
Returns -1, if <!PW>rX is negative, 0, if <!PW>rX=0 and otherwise 1
>>
<<
120.1.1.6
Ceil
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Ceil (rX : real) : real;
<!TXT>
Returns the next integer which is greater than or equal to <!PW>rX.
>>
<<
120.1.1.7
Floor
!120.1.1.99 - Example
--
<!DEF>
function <!TW>Floor (rX : real) : real;
<!TXT>
Returns the next integer which is less than or equal to <!PW>rX.
>>
<<
120.1.1.99
Examples of numerical functions|Examples
--
<!STBL>
<tr bgcolor=f0f0f0 align=center><td><b>rX</b><!><b>Round</b><!><b>Int</b><!><b>Frac</b><!><b>Abs</b><!><b>Sign</b><!><b>Ceil</b><!><b>Floor</b><!>
<tr align=right><td><b> 1.7</b><!> 2<!> 1<!> 0.7<!>1.7<!> 1<!> 2<!> 1<!>
<tr align=right><td><b> 1.5</b><!> 2<!> 1<!> 0.5<!>1.5<!> 1<!> 2<!> 1<!>
<tr align=right><td><b> 1.2</b><!> 1<!> 1<!> 0.2<!>1.2<!> 1<!> 2<!> 1<!>
<tr align=right><td><b> 1.0</b><!> 1<!> 1<!> 0.0<!>1.0<!> 1<!> 1<!> 1<!>
<tr align=right><td><b> 0.0</b><!> 0<!> 0<!> 0.0<!>0.0<!> 0<!> 0<!> 0<!>
<tr align=right><td><b><b>-1.0</b><!>-1<!>-1<!> 0.0<!>1.0<!>-1<!>-1<!>-1<!>
<tr align=right><td><b>-1.2</b><!>-1<!>-1<!>-0.2<!>1.2<!>-1<!>-1<!>-2<!>
<tr align=right><td><b>-1.5</b><!>-2<!>-1<!>-0.5<!>1.5<!>-1<!>-1<!>-2<!>
<tr align=right><td><b>-1.7</b><!>-2<!>-1<!>-0.7<!>1.7<!>-1<!>-1<!>-2<!>
<!ETBL>
>>
<<
120.1.1.8
Len
--
<!DEF>
function <!TW>Len (sText : string) : real;
<!TXT>
Returns the length of <!PW>sText as number of characters.

<!DEF>
function <!TW>Len (vVector : string|Vector|StringVector) : real;
<!TXT>
Returns the number of elements for which there is a place reserved in the <!PW>vVector (Vector oder StringVector).

Beispiele:
<!CODE>
  sString := 'Hello';
  rCount := Len( vNumbers ); // rCount = 5
  vNumbers := [1,2,3];
  rCount := Len( vNumbers ); // rCount = 3
  svStrings := ['Hello','World'];
  rCount := Len( vNumbers ); // rCount = 2
<!TXT>
>>
<<
120.1.1.10
Pos
--
<!DEF>
function <!TW>Pos (sSub, sText : string [; rFrom : real]) : real;
<!TXT>
Searches the <!PW>sSub string in the <!PW>sText string and returns the position of the first occurence or 0, if it is not found. If <!PW>rFrom is specified, then the search starts with the <!PW>rFrom-th character.
>>
<<
120.1.1.11
Ord
--
<!DEF>
function <!TW>Ord (sText : string) : real;
<!TXT>
Returns the character code of the first character of <!PW>sText. If <!PW>sText does not contain any characters, the returned value is 0.
>>
<<
120.1.1.12
Val
--
<!DEF>
function <!TW>Val (sValue : string; rDefault : real) : real;
<!TXT>
Converts the text from <!PW>sValue into a numerical value. If this doesn't work, the returned value is <!PW>rDefault.
>>
<<
120.1.1.13
HexVal
--
<!DEF>
function <!TW>HexVal (sValue : string; rDefault : real) : real;
<!TXT>
Converts the text in <!PW>sValue into a numerical value. Thereby <!PW>sValue is considered to be a hex-number. If this does not work, the returned value is <!PW>rDefault.
>>
<<
120.1.1.14
LastPos
--
<!DEF>
function <!TW>LastPos (sSub, sText : string) : real;
<!TXT>
Searches <!PW>sSub in the <!PW>sText string and returns the position of the last occurence or 0, if not found.
>>

<<
120.1.2
Internal String-Functions|String
>>
<<
120.1.2.1 
Chr
--
<!DEF>
function <!TW>Chr (rCode : real) : string;
<!TXT>
Returns a string which contains the character corresponding to the character code in <!PW>rCode.
>>
<<
120.1.2.2
Str
!120.1.2.3 - HexStr
--
<!DEF>
function <!TW>Str (rValue : real [; rDecimals : real [; rPrecision : real [; sFill : string [; bWhere : bool ]]]]) : string;
<!TXT>
Converts the numerical value <!PW>rValue into a string which corresponds to the decimal notation of <!PW>rValue. <!PW>rDecimals indicates the minimum number of characters in the result, nPrecision indicates the number of digits after the decimal places which the result should have. If <!PW>rDecimals and / or <!PW>rPrecision are not specified, the required number of positions will be used. If <!PW>sFill is specified, any leading blanks are in the result are replaced by the first letter of <!PW>sFill. if <!PW>bWhere is true the filling chars are after the '-' (-005) otherwise  before the '-'(XX-5). The value is in default false.
>>
<<
120.1.2.3
HexStr
!120.1.2.2 - Str
--
<!DEF>
function <!TW>HexStr (rValue : real [; rDigits : real [; sFill : string]]) : string;
<!TXT>
Converts the numeric value <!PW>rValue into a string which corresponds to the hexadecimal notation of <!PW>rValue. <!PW>rDigits indicates the minimum number of characters in the result. If <!PW>sFill is specified, any leading blanks in the result are replaced by the first letter of sFill.
>>
<<
120.1.2.4
Copy
!120.1.2.5 - Left
!120.1.2.6 - Right
--
<!DEF>
function <!TW>Copy (vVector : string|Vector|StringVector , rStart : real [, rCount : real]) : string|Vector|StringVector;
<!TXT>
Returns from <!PW>rCount Elements out of <!PW>vVector, starting with the <!PW>rStart position.
If the parameter rCount is not definded, all elements upto the vector will be copied.


>>
<<
120.1.2.5
Left
!120.1.2.4 - Copy
!120.1.2.6 - Right
--
<!DEF>
function <!TW>Left (sText : string; rCount : real) : string;
<!TXT>
Returns the first <!PW>rCount characters of <!PW>sText.
>>
<<
120.1.2.6
Right
!120.1.2.4 - Copy
!120.1.2.5 - Left
--
<!DEF>
function <!TW>Right (sText : string; rCount : real) : string;
<!TXT>
Returns the last <!PW>rCount characters of <!PW>sText.
>>
<<
120.1.2.7
Insert
!120.1.2.8 - Delete
--
<!DEF>
function <!TW>Insert (sIns, sText : string; rIndex : real) : string;
<!TXT>
Inserts <!PW>sIns into <!PW>sText at the position <!PW>rIndex.
>>
<<
120.1.2.8
Delete
!120.1.2.7 - Insert
--
<!DEF>
function <!TW>Delete (sText : string; rStart, rCount: real) : string;
<!TXT>
Removes <!PW>rCount charcaters from <!PW>sText starting at position  <!PW>rStart.
>>
<<
120.1.2.9
RemoveChars
--
<!DEF>
function <!TW>RemoveChars (sText, sUnWanted : string) : string;
<!TXT>
Removes all the characters which occur in the <!PW>sUnwanted string from the string <!PW>sText.
>>
<<
120.1.2.10
Message
--
<!DEF>
function <!TW>Message (rMsgNr : real [; sDefault : string]) : string;
<!TXT>
Returns the text of the message with <!PW>rMsgNr (0..9999999) number from the current USERMSG.INI-File. The current USERMSG.INI is always the one that belongs to the selected language.
If there is no message available for the <!PW>rMsgNr number, the return value is <!PW>sDefault. If <!PW>sDefault is not specified either, then '&gt;&gt; Message xxx missing. &lt;&lt;' is returned, where xxx is replaced by <!PW>rMsgNr.

The messages must be in the section <!SW>[TEXTE]. 
Example of an USERMSG.INI-File:
<!CODE>
[TEXTE]
0000000=Message Number 0
0000001=This message Number 1
0000002=This message has the Nummer 2
0000003=And this is the 3!
<!TXT>
>>
<<
120.1.2.11
RemoveOtherChars
--
<!DEF>
function <!TW>RemoveOtherChars (sText, sWanted : string) : string;
<!TXT>
Removes all the characters which do not occur in the <!PW>sWanted string from the string <!PW>sText.
>>

<<
120.1.2.12
UpperCase
--
<!DEF>
function <!TW>UpperCase (sText : string) : string;
<!TXT>
Converts every lower case letter from <!PW>sText into upper case. 

Works only with the letters from A-Z, not with umlaut or . 

All the other characters remain as they are.
>>

<<
120.1.2.13
LowerCase
--
<!DEF>
function <!TW>LowerCase (sText : string) : string;
<!TXT>
Converts every upper letter case from <!PW>sText into lower case. 

Works only with letters from A-Z, not with umlauts or . 

All the other characters remain as they are.
>>

<<
120.1.2.14
CutFirstToken
--
<!DEF>
function <!TW>CutFirstToken (var sText : string; sSeparatorChar : string) : string;
<!TXT>

Searches for the first occurence of the character <!PW>sSeparatorChar in <!PW>sText. The part preceeding the separator is returned as result (FirstToken). This part, as well as the separator will be removed from the <!PW>sText (Cut). If the SeparatorChar is not found, then <!PW>sText is considered completely to be the first token.

Only the first character of <!PW>sSeparatorChar is the separator. If <!PW>sSeparatorChar is empty (''), then <!PW>sText is considered completely as the first token.

The components of a string with separators can be analyzed with CutFirstToken.

Example:
<!CODE>
var
  sText, sResult : string;

  sText:='1,23,456789';
  sResult:=CutFirstToken (sText, ',');
  // --> sResult='1', sText='23,456789';
  sResult:=CutFirstToken (sText, ',');
  // --> sResult='23', sText='456789';
  sResult:=CutFirstToken (sText, ',');
  // --> sResult='456789', sText='';
  sResult:=CutFirstToken (sText, ',');
  // --> sResult='', sText='';

  sText:='1,23,456789';
  sResult:=CutFirstToken (sText, 'x');
  // --> sResult='1,23,456789', sText='';

  sText:='1,23,456789';
  sResult:=CutFirstToken (sText, '');
  // --> sResult='1,23,456789', sText='';
<!TXT>
>>
<<
120.1.2.15
Trim
--
<!DEF>
function <!TW>Trim (sUnTrimmed : string) : string;
<!TXT>
Removes all the blanks and control characters from the beginning and end of the string <!PW>sUntrimmed.
>>
<<
120.1.2.16
TrimLeft
--
<!DEF>
function <!TW>TrimLeft (sUnTrimmed : string) : string;
<!TXT>
Removes all the blanks and control characters from the beginning of the string <!PW>sUntrimmed.
>>
<<
120.1.2.17
TrimRight
--
<!DEF>
function <!TW>TrimRight (sUnTrimmed : string) : string;
<!TXT>
Removes all the blanks and control characters from the end of the string <!PW>sUntrimmed.
>>
<<
120.1.2.18
Pad
--
<!DEF>
function <!TW>Pad (sData : string; rLen : real [; sFill : string [; rFlags : real]]) : string;
<!TXT>
Fills up <!PW>sData to the length <!PW>rLen.

It is filled with the string <!PW>sFill.

 <!PW>rFlags is a bit pattern which determines how it is filled and if a string which is too long should be cut off.

<!STBL>
<tr bgcolor=f0f0f0 align=center><td><b>Bit</b><!><b>Value</b><!><b>Effect</b><!>
<tr><td align=center rowspan=2>0</td><td align=center rowspan=2>1<!>0 = will be filled / cut on right side<!>
<!>1 = will be filled / cut on left side<!>
<tr><td align=center rowspan=2>1</td><td align=center rowspan=2>2<!>0 = will not be cut<!>
<!>2 = will be cut down to length <!PW>rLen<!>
<!ETBL>

By default, the right side is filled with blanks and the String is not cut off, if it is longer than <!PW>rLen charcaters (default for <!PW>sFill = ' ', for <!PW>rFlags = 0).


Examples:
<!CODE>
Pad ('', 10);                   -> '          ' (10 blanks)
Pad ('', 10, '*');              -> '**********'
Pad ('Hello', 10);              -> 'Hello     '
Pad ('Hello', 10, '*');         -> 'Hello*****'
Pad ('Hello', 10, '', 1);       -> '     Hello'
Pad ('Hello', 10, '*', 1);      -> '*****Hello'
Pad ('Hello', 12, 'World');     -> 'HelloWorldWo'
Pad ('Hello', 12, 'World', 1);  -> 'WorldWoHello'
Pad ('Hello', 3);               -> 'Hello'
Pad ('Hello', 3, '', 2);        -> 'Hel'
Pad ('Hello', 3, '', 3);        -> 'llo'
<!TXT>
>>

<<
120.1.2.19
nThToken
--
<!DEF>
function <!TW>nThToken (rIdx : real; sText, sSeparatorChar : string) : string;
<!TXT>
Returns the <!PW>rIdx.-th token out of the string <!PW>sText.

The token have to be separated by <!PW>sSeparatorChar. Only the first character of the <!PW>sSeparatorChar is used.

If <!PW>sSeparatorChar is an empty string, the function returns the <!PW>rIdx-th chracter of <!PW>sText.

Tokens are counted from 1.

If there are less tokens than wanted, an empty string is returned.

The string in <!PW>sText is not affected by this function (that is different to <!RW>CutFirstToken).

Example:
<!CODE>
  nThToken (1, '1;23;456789', ';');   --> '1'
  nThToken (1, '1;23;456789', ';x');  --> '1'      the 'x' is not used at all
  nThToken (3, '1;23;456789', ';');   --> '456789'
  nThToken (5, '1;23;456789', ';');   --> ''
  nThToken (3, '1;23;456789', '');    --> '2'      the 3rd character!
<!TXT>
>>

<<
120.1.3
Internal Vector-Functions|Vector
>>
<<
120.1.3.1
BVectToHex
--
<!DEF>
function <!TW>BVectToHex (vBVect : vector [; sFormat : string]) : string;
<!TXT>
Converts the <!PW>vBVect vector into a string with the individual values of the vector. <!PW>vBVect must contain only the values 0-255 (byte-range) and -1 as Don't-Care value. The conversion can be controlled with <!PW>sFormat. <!PW>sFormat consists of four parts, sperated by '|', where the first part indicates the characters which are set before each byte value, the second part indicates the characters which are set between the byte values, the third part is used for Don't-Care values while the fourth part is for values outside the byte-range.

The default for <!PW>sFormat is '| |?|!'. Thus the resulting Strings are as e.g. : '12 3A B3 ? C2'.
>>
<<
120.1.3.2
HexToBVect
--
<!DEF>
function <!TW>HexToBVect (sHex  : string [; sDontCareChar : string]) : vector;
<!TXT>
Converts the <!PW>sHex string into a vector. All the characters in <!PW>sHex which are not hex-numbers will be considered separators between two bytes. If there is an odd number of hex-digits between separators, then the last digits is considered to be a separate byte.

If a character corresponds to the <!PW>sDontCareChar (default : '?'), then this character is treated as a value and -1 is entered in its place. This can be only used in connection with the Check Functions.

<!CODE>
HexToBVect('$12$123$5') results in : [18, 18, 3, 5]

HexToBVect('12123?5') results in : [18, 18, 3, -1, 5]

HexToBVect('12 12 3 * 5', '*') results in : [18, 18, 3, -1, 5]
<!TXT>
>>

<<
120.1.3.3
BVectToString
--
<!DEF>
function <!TW>BVectToString (vBVect : vector) : string;
<!TXT>
Converts the <!PW>vBVect vector into a string with the individual values of the vector. <!PW>vBVect may contain only the values 0-255 (byte-range). Each element of <!PW>vBVect is converted into one character of the string (with the ASCII-Code of the element). The result string has excatly the same number of charcaters as <!PW>vBVect holds elements.
>>
<<
120.1.3.4
StringToBVect
--
<!DEF>
function <!TW>StringToBVect (sData : string) : vector;
<!TXT>
Converts the <!PW>sData string into a vector. Each character in <!PW>sData becomes an element of the result with its ASCII-value. The number of elements in the result vector is equal to the number of characters in the String.
<!CODE>
StringToBVect('ABCD') results in : [65, 66, 67, 68]
<!TXT>
>>

<<
120.1.3.5
Check
--
<!DEF>
function <!TW>Check (vFrame, vWanted : vector [; rMode : real [; rDontCareValue : real]]) : real;
<!TXT>

Compares the frame in <!PW>vFrame vector with the frame in the <!PW>vWanted vector.

<!PW>rMode determines the behaviour in case of different lengths
<!STBL>
<tr bgcolor=f0f0f0><td><b>rMode</b><!><b>Verhalten</b><!>
<!>0<!>Length must be identical (default)<!>
<!>1<!>lFrame may be shorter than lWanted<!>
<!>2<!>lFrame may be longer than  lSoll, no  testing of the 'protruding' values<!>
<!>3<!>lFrame may be longer or shorter, the comparison is made until 
the highest common index<!>
<!ETBL>

If a value is specified for <!PW>rDontCareValue and one of the <!PW>vWanted elements corresponds to this value, then the corresponding element in the <!PW>vFrame can have any value.

Return value: 0= everything ok, otherwise the position in <!PW>vFrame which deviates.

<!CODE>
Check ([1,2,3,4],  [1,2,3,4], 1)      ->  0  - everything is the same
Check ([1,2,99,4], [1,2,3,4])         ->  3
Check ([1,2,99,4], [1,2,3,4], 0)      ->  3
Check ([1,2,3],    [1,2,3,4], 1)      ->  0  - may be shorter!
Check ([1,2,3],    [1,2,3,4], 2)      ->  3
Check ([1,2,3,5],  [1,2,3,-1], 0, -1) ->  0  - -1 is DontCare!
<!TXT>
>>

<<
120.2
Internal procedures without IP-Object|Internal Procedures
>>
<<
120.2.1
Exit
--
<!DEF>
procedure <!TW>Exit;
<!TXT>
Leaves the interpreter step as if the end has been reached. The command works as a jump directly to the end of the step.

This works, even if the <!RW>Exit is used in a function or procedure!
>>
<<
120.2.2
Dec
!120.2.3 - Inc
--
<!DEF>
procedure <!TW>Dec (var rValue : real [; rDec : real]);
<!TXT>
Decreases the value of the variable <!PW>rValue by value of <!PW>rDec. If <!PW>rDec is not specified, then <!PW>rValue is decreased with 1.

This command is somewhat faster than the assignment:
<!CODE>
rValue := rValue - rDec;
<!TXT>
(Which has the same result)
>>
<<
120.2.3
Inc
!120.2.2  - Dec
--
<!DEF>
procedure <!TW>Inc (var rValue : real [; rInc : real]);
<!TXT>
Increases the value of the variable <!PW>rValue by the value of <!PW>rInc. If <!PW>rInc is not specified, then <!PW>rValue is increased with 1.
 
This command is somewhat faster than the assignment:
<!CODE>
rValue := rValue + rDec;
<!TXT>
(Which has the same result)
>>
<<
120.2.4
SetLen
--
<h4>For vectors:</h4>
<!DEF>
procedure <!TW>SetLen (var vVector : vector; rLen :real);
<!TXT>
Sets the length of the vector <!PW>vVector to <!PW>rLen values (0 &lt;= <!PW>rLen &lt;= 65535). Newly assigned elements have the value 0 and the value of cut off elements is lost.
Example:
<!CODE>
vData:=[1,2,3,4];
SetLen (vData, 6);   // -> vData=[1,2,3,4,0,0]
SetLen (vData, 3);   // -> vData=[1,2,3]
<!TXT>
        
<!DEF>
procedure <!TW>SetLen (var vVector : vector; rLen, rValue : real);
<!TXT>
As before, but: Newly assigned elements have the value <!PW>rValue.
<!CODE>
vData:=[1,2,3,4];
SetLen (vData, 6, 9);   // -> vData=[1,2,3,4,9,9]
SetLen (vData, 3, 9);   // -> vData=[1,2,3]
<!TXT>

<h4>For stringVekctoren:</h4>
<!DEF>
procedure <!TW>SetLen (var svVector : StringVector; rLen :real);
<!TXT>
Sets the length of the vector <!PW>vVector to <!PW>rLen values (0 &lt;= <!PW>rLen &lt;= 65535). Newly assigned elements have the value 0 and the value of cut off elements is lost.
Beispiel:
<!CODE>
svData:=['Hello','World','!'];
SetLen (svData, 5);   // -> vData=['Hello','World','!','','']
SetLen (svData, 2);   // -> vData=['Hello','World']
<!TXT>

<!DEF>
procedure <!TW>SetLen (var svVector : StringVector; rLen, sValue : string);
<!TXT>
As before, but: Newly assigned elements have the value <!PW>rValue.
<!CODE>
vData:=['Hello','World','!'];
SetLen (vData, 5, 'cPCI');   // -> vData=['Hello','World','!','cPCI','cPCI']
SetLen (vData, 2, 'cPCI');   // -> vData=['Hello','World']
<!TXT>

<h4>For Strings:</h4>
<!DEF>
procedure <!TW>SetLen (var sString : string; rLen : real);
<!TXT>
Sets the length of the String <!PW>sString to <!PW>rLen characters (0 &lt;= rLen). Newly assigned characters are filled with blanks.
Example:
<!CODE>  sData:='1234';
SetLen (sData, 6);   // -> sData='1234  ';
SetLen (sData, 3);   // -> vData='123';
<!TXT>

<!DEF>
procedure <!TW>SetLen (var sString : string; rLen : real; sValue : string);
<!TXT>
Sets the length of the String <!PW>sString to <!PW>rLen characters (0 &lt;= rLen). If the String must be lengthened, so <!PW>sValue is attached as many times until the wanted length is reached.
If <!PW>sValue is empty, blanks are attached.
Example:
<!CODE>
sData:='1234';
SetLen (sData, 6, '*');     // -> sData='1234**';
SetLen (sData, 3);          // -> vData='123';
SetLen (sData, 10, 'ABC');  // -> vData='123ABCABCA';
<!TXT>
>>
<<
120.2.5
Return
--
<!DEF>
procedure <!TW>Return;
<!TXT>
Only to be used in functions and procedures. Will leave the function/procedure immediately and returns execution to the calling block.
Works like a jump to the last <!RW>END; of the function or procedure.
To get a similar function in the main block (<!RW>STEP <!RW>END.), use <a href="120.2.1">Exit</a>; .

<!DEF>
procedure <!TW>Return (.Value : real|string|vector|StringVector);
<!TXT>
Only to be used in functions and works like this combination:
<!CODE>
Result:=Value;
Return;
<!TXT>
The data type of value must be compatible to the return type of the function.
>>
