|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Variable Definitions and Operations > Variable Commands |
MiniRobotLanguage (MRL)
SAV. Command
Save / Restore Variables (Encapsulation of Variables)
Intention
This command can be used in Subroutines to safely use Variables, that may also be in use somewhere else. For this the Command will "Save" the Variable Content and give you a fresh and Clear Variable. You can think of making Variable "Subroutine local". Think of Encapsulation of code.
SAV. is like brackets in Math. (3+(4+5)) There is always a fitting Closing Bracket to an opening bracket.
In the same way you need to call a SAV.Restore for each SAV.Save. If you do not call a SAV.Restore for each SAV.Save there is a danger that the internal Stack which holds all the Variables may run over with time..
In Short: You can make a
SAV.Save ( Sub-Script) SAV.Restore
like a Encapsulation-Shell around your Subprograms.
This will make sure that all used (and specified) Variables will be the same value and state that they had before the Subprogram was called.
SAVe - Variables (DO whatever) SAV.Restore Variables
SAV. will:
1. Save all specified Variables, whether they are currently defined or not.
2. Variables that are currently not defined (not in use) will be SAV.ed and Cleared, but deleted at the SAV.Restore.
Therefore SAV. will create Variables that are not in use at that time and clear them.
3. Restore all SAVed Variables deleting the Values that may have been in these Variables.
When there are Variables that have not been defined before, these will be deleted at the Restore.
4. Has no depth limit. You can go as many levels deep as you want.
5. SAV. uses a LIFO (LAST IN FIRST OUT)-System. Calling SAV.Restore will therefore restore all Variables that have been saved with the last SAV.Save
statement. And the next call will restore the Variables from the SAV.Save before this one.
Lets see an example:
:Test
' $$TXT will be saved and cleared
SAV.Save|$$TXT
GVT.$$PAA|$$RES
VAR.$$TXT=$$PAA-$$PAB->Type is:$$RES
DBP.$$TXT
' $$TXT will be restored and get the original Value and Type
SAV.Restore
RET.
In this Subrprogramm we use the Variable $$TXT. At the time of writing, we do not know if we will use this Variable in a Script that may call this Subprogram later.
Now we just make $$TXT "local" to this Subprogramm using the SAV.-Command..
SAV. has unlimited Levels. Therefore you can call Subprogrammes that are protected with SAV. in a recursive way.
Or call a Subprogram that uses such Variables, and calls another that uses such variables.
SAV. accepts up to 70 Variables, if you need more just use more successive SAV.-Statements.
Just keep in mind that SAV. uses a LIFO (LAST IN FIRST OUT)-System.
VAN.$$PAA=5.56
VAN.$$PAB=7
' Level 1
SAV.Save|$$PAA|$$PAB|$$PAC
MBX.After SAV. the Variables are Cleared:$$PAA-$$PAB
VAR.$$PAA=Hallo
VAR.$$PAB=Peter
' Level 2
SAV.Save|$$PAA|$$PAB|$$PAC
VAR.$$PAA=Inside
VAR.$$PAB=SPR
GSB.Test
' Restore Level 1
SAV.Restore
GSB.Test
' Restore Original Values
SAV.Restore
GSB.Test
END.
'---------------------
:Test
SAV.Save|$$TXT|$$TAX
GVT.$$PAA|$$RES
VAR.$$TXT=$$PAA-$$PAB->Type is:$$RES
DBP.$$TXT
SAV.Restore
RET.
ENR.
'---------------------------------
' This is a Subprogram that will change the Format of a date from
' 20181204 -> 2018-12-04
' Called like this:
' GSB.DateFormat|$$RES
:DateFormat
SAV.Save|$$YEA|$$MON|$$DAY|$$INP
VAR.$$INP=§§_01
GSS.1|4|$$INP|$$YEA
FMT.$$YEA|0000
GSS.5|6|$$INP|$$MON
FMT.$$MON|00
GSS.7|8|$$INP|$$DAY
FMT.$$DAY|00
VAR.$$RES=$$YEA-$$MON-$$DAY
SAV.Restore
RET.
Syntax
SAV.s|P1[|P2..|Px]
SAV.Save|P1[|P2..|Px]
Parameter Explanation
P1 - Variable-name of Source and Target variable
P2...Px - (optional) any Number of Variables to preserve.
SAV.r
SAV.Restore
Parameter Explanation
No Parameters are supported in Restore-Mode.
The Command will always restore all Variables that have been saved with the LAST matching Save-Command.
Example
'**********************************
' SAV.-Sample
'**********************************
VAN.$$PAA=5.56
VAN.$$PAB=7
SAV.Save|$$PAA|$$PAB|$$PAC
MBX.After SAV. the Variables are Cleared:$$PAA-$$PAB
VAR.$$PAA=Hallo
VAR.$$PAB=Peter
SAV.Save|$$PAA|$$PAB|$$PAC
VAR.$$PAA=Inside
VAR.$$PAB=SPR
GSB.Test
SAV.Restore
GSB.Test
SAV.Restore
GSB.Test
END.
:Test
SAV.Save|$$TXT
GVT.$$PAA|$$RES
VAR.$$TXT=$$PAA-$$PAB->Type is:$$RES
DBP.$$TXT
SAV.Restore
RET.
ENR.
ENR.
'**********************************
Remarks
SAV. can be nested to any depth.
SAV. is like brackets in Math. (3+(4+5)) There is always a fitting Closing Bracket to an opening bracket.
In the same way you need to call a SAV.Restore for each SAV.Save. If you do not call a SAV.Restore for each SAV.Save there is a danger that the internal Stack which holds all the Variables may run over with time..
Limitations:
Note that currently Variables will normally loose their Variable-Type (and get Type 1 String) if they are assigned to another Variable. You can avoid this by using the VAO.-Command:
' This will preserve the Variable Type
VAO.$$ABC=$$EFG
The overall maximum length of variables depend on your available RAM and your actual Memory fragmentation. String memory needs to be in one piece and can not be fragmented. As a raw assumption, 500 MB maximum size for strings should always be possible. If you stay below you should be on the safe side. The theoretical maximum is about ~2 GB.
See also:
• VAR. - Variable Set Value/Clear
• VAV. - Variables with Variables
• VBA. - Variable Binary Append
• CAL. - mathematical CALculation