Preprocessor-Directives
#ONCE / #OEND / #OREM
Include code-parts only once
Intention
All Commands starting with a "#" are Preprocessing Commands. These commands will influence the code before it is actually starting.These commands have no access to Variables and Runtime Resources, as they work in the Preprocessor, which is before Runtime.
The #ONCE and #OEND is a preprocessor command. The block between #ONCE and #OEND will not be read two times.
These commands can be nested. The most outer Block has Priority over inner Blocks.
From all Preprocessor directives, the #ONCE is processed first, therefore #IFVA and other Directives have lower Priority.
As #ONCE is processed before #VARD, it does not support Preprocessor-Variables.
There are two versions of the #ONCE command.
First version:
The #ONCE without any parameters. In this case the internal Preprocessor uses the name of the actual loaded file as parameter. This will prevent the whole file from being loaded a second time. even if the block is somewhere inside the file.
Second version:
To just block a part of a code, use #ONCE [parameter-string]. In this case the parameter string will be stored in an internal memory and compared to any further call to #ONCE.
If this string is found a second time, the whole enclosed Block is been removed before any further processing is done.
This way, you can prevent files which are included with #INC: from being loaded and processed multiple times.
For example if the files contain MACRO Definitions. You do not want them to be loaded and parsed several times. Even if they are called from multiple incclude files.
There is no internal space after #ONCE, anything after the "#" is taken as part of the string. You can use the : or many other signs for formatting, these will however be part of the string. Variables are not resolved after #ONCE because this is done at Preprocessing-time, not at run-time.
#OREM P1 will remove the String P1 from the List that stores the #ONCE Values. It will therefore allow such files to be re-processed. It may possibly useful together with Macros and #IF_PARAM..
Command Nesting:
' #ONCE without any Param uses current Filename as Param
' First occurence of "Key" is allowed
#ONCE
DBP.Hallo A
#OEND
' Second occurence of "Key" is deleted
#ONCE
DBP.Hallo B
#OEND
' With explicit Key
' #ONCE with Param uses Param as "Key"
#ONCE VA
DBP.Hallo A
#OEND
' Second occurence of "Key" is deleted
#ONCE VA
DBP.Hallo B
#OEND
' Nested, most outer Layer has Priority
' We had Key "VA" already therefore the whole Block will not be executed
#ONCE VA
' That will include anything inside even if it would be allowed otherwise
#ONCE CV
#ONCE CX
DBP.Hallo C
#OEND
DBP.Hallo E
#OEND
DBP.Hallo D
#OEND
' Until here
' CV is allowed as Key as it was not processed above
#ONCE CV
' CV is not allowed here as this iis the second appearance
#ONCE CV
#ONCE CX
DBP.Hallo C
#OEND
DBP.Hallo E
#OEND
' ANything untl here will be commented out
DBP.Hallo D
#OEND
#OREM CV
' CV is allowed as Key as we used #OREM to delete it from used Keys
#ONCE CV
DBP.Hallo G
#OEND
DMP.Speed
MBX.!
ENR.
The Speed-Dump shows which Lines are processed / commented out.
Order of Processing in the Pre-Processor:
There is an Order of processing inside the Pre-Processor, the following Commands are processed sequentially:
1. #INC:
2. #LIB:
2. #ONCE / #OEND / #OREM
4. #VARD
5. #IFVA / #ELSA / # EIFA and #IFVL
6. #SCSA / #CASE / #CSEA / #ENSA
7. Macros etc.
8. Collecting Labels
This is important, because of this you can use the Preprocessor to remove Macro-Lines and Labels from the Code.
You can not use t to remove #INC: or #LIB: from the Code as its processed before, with highest Priority.
ts even processed before #ONCE: therefore #ONCE will not protect from these directives.
Generally the Priority of #ONCE ... #OEND is the highest.
Anything that is in there will be removed from the Code if the Condition s "Duplicate".
Of course the Directives themselves will also be removed from the final Code as well before Execution.
Generally Directives are processed and removed in one step.
In the next step the Compiler defines numerical Variables in Model-Space 255.
These Variables are available from that Moment and can be used inside #IFVA, #IFVL #SCSA, and wth #CASE .
For example like this:
#VARD $$VER=3
#IFVL $$VER>1
Here is a Real-Life Sample from the "Twitter-Button Bar" from Sample-Code Folder.
Using this System, we can remove Lines with Macros from the Code before the Script starts running.
#VARD $$VER=1
%SetText Letztes Diktat|Zuletzt diktierten Text wiederherstellen und einfügen.
#IFVL $$VER>1
%SetText UnDo|Letzte Textänderung im Arbeitsbereich rückgängig machen.
'-------
%SetText Schiller//Goethe|Zwischenablage-Text in Schillers oder Goethe's poetischem Stil neu interpretieren.
#IFVA $$VER>1
%SetText E. Roth//Sam Hawkins|Zwischenablage-Text im humorvollen Stil von Eugen Roth oder SAm Hawkins neu dichten.
%SetText W. Busch//Morgenstern|Zwischenablage-Text in Wilhelm Buschs oder Christian Morgenstern's satirischem Versmaß umwandeln.
%SetText Dichter//Erhard|Zwischenablage-Text im Stil eines wählbaren Dichters oder RMB: Heinz Erhardt's Stil neu interpretieren.
#EIFA
Important Implications:
This will also prevent the use for the "higher Constructs" (1.-6.) Inside Macros, because at the Time of Macro-Expansion, they simply do not exist anymore.
You can generally nest these Construction. Again there is a Priority that the most outer Construct will remove anything inside if the Condition is not "True".
It does not matter f a "inner Condition" is true or not, f the outer Condition is False.
' This the case where its removed from the Code
#VARD $$VER=3
#IFVA $$VER>3
#IFVA $$VER>1
.. Will be removed
#EIFA
#EIFA
' This the case where ts not removed
#VARD $$VER=3
#IFVA $$VER>2
#IFVA $$VER>1
.. Will not be removed
#EIFA
#EIFA
You also need to understand that the #SCSA are generally processed after the #IFVA and therefore have a general Priority.
However that seems to not be any problem, as it does not Matter when a Construct is removed. In cases like below, first the #IFVA are processed and in the next Pass the #SCSA are processed.
The result is the same.
#VARD $$VER=3
#SCSA $$VER
#CASE 1
#IFVA=3
... will be removed from the #SCSA
#EIFA
#CASE 2
#CSEA
#ENSA
Syntax:
#ONCE[P1]
#OREM P1
P1 - string which identifies the block as unique.
Example:
'----------------------------------------
' Macro/#ONCE-Example 1
'----------------------------------------
' Minimum Number of parameters is set to zero
: %MyMacroA 0
#ONCE:ME
PRT.Number of Parameters:§§§00-Parameter=§§§01
#OEND
' Replace the MEX with ME to prevent the block from
' being processed.
#ONCE:MEX
PRT.Number of Parameters:§§§00-Parameter=§§§01
#OEND
END%
' Minimum Number of parameters is set to 1
: %MyMacroB 1
%MyMacroA Mytext
PRT.Number of Parameters:§§§00
END%
%MyMacroA Mytext
%MyMacroB Mytext
DMP.
END.
Parameter Explanation:
-
Remarks:
-
Limitations:
-
See also:
•1.1 #INC: - Pre-Processor File-Include
•1.2 #ONCE / # OEND - Multiple Include Protection
•1.4 #IF ... #EIF - Decisions in Macros