The Harbour implementation of codeblocks

Author : Ryszard Glab <>

Compilation of a codeblock.
During compile time the codeblock is stored in the following form:
- the header
- the stream of pcode bytes
The header stores information about referenced local variables.
+0: the pcode byte for _PUSHBLOCK
+1: the number of bytes that defines a codeblock
+3: number of codeblock parameters (declared between || in a codeblock)
+5: number of used local variables declared in procedure/function where
 the codeblock is created
+7: the list of procedure/function local variables positions on the eval
 stack of procedure/function. Every local variable used in a codeblock
 occupies 2 bytes in this list. When nested codeblocks are used then this
 list is created for the outermost codeblock only.
+x: The stream of pcode bytes follows the header.
+y: the pcode byte for _ENDBLOCK

Creation of a codeblock.
When HB_P_PUSHBLOCK opcode is executed then the HB_ITEM structure is created
and placed on the eval stack. The type of item is IT_BLOCK. The value of this
item is a pointer to HB_CODEBLOCK structure. Additionally this item stores the
base of static variables defined for the current function/procedure - this
is used during a codeblock evaluation when the evaluation is called from a code
from other PRG module. Also the number of expected parameters is stored.
The HB_CODEBLOCK structure stores a pointer to the pcodes stream that is
executed during a codeblock evaluation. It stores also the pointer to a table
with local variables references. Values of all local variables defined in a
procedure and used in a codeblock are replaced with a reference to a
value stored in a global memory variables pool. This allows the correct access
to detached local variables in a codeblock returned from this function (either
directly in RETURN statement or indirectly by assigning it to a static or
memvar variable. This automatic and unconditional replace is required because
there is no safe method to find if a codeblock will be accessed from an outside
of a function where it is created.
When nested codeblocks are used then only the outermost codeblock creates
the table - all inner codeblock uses this table. The first element of this
table contains a reference counter for this table. It allows to share the table
between nested codeblock - the table is deleted if there is no more references
to it. This is caused by the fact that a inner codeblock can be created during
evaluation of outer codeblock when local variables don't exist like in this
 PRIVATE foo, bar
 Eval( foo )
 Eval( bar )

 LOCAL a := "FOO", b := "BAR"
foo := {|| a + ( bar := Eval( {|| b } ) ) }

Evaluation of a codeblock.
Parameters passed to a codeblock are placed on the eval stack before a
codeblock evaluation. They are accessed just like usual function
parameters. When a codeblock parameter is referenced then its position on the
eval stack is used. When a procedure local variable is referenced then the
index into the table of local variables positions (copied from the header) is
used. The negative value is used as an index to distinguish it from the
reference to a codeblock parameter.

Incompatbility with the Clipper.
1) Detached locals passed by reference
There is a little difference between the handling of variables passed by
the reference in a codeblock.
The following code explains it (thanks to David G. Holm)
 LOCAL nTest
 LOCAL bBlock1 := MakeBlock()
 LOCAL bBlock2 := {|| DoThing( @nTest ), QOut( "From Main: ", nTest ) }
Eval( bBlock1 )
 Eval( bBlock2 )
FUNCTION MakeBlock()
 LOCAL nTest
 RETURN {|| DoThing( @nTest ), QOut( "From MakeBlock: ", nTest ) }
FUNCTION DoThing( n )
n := 42

 In Clipper it produces:
From MakeBlock: NIL
From Main: 42
In Harbour it produces (it is the correct output, IMHO)
From MakeBlock: 42
From Main: 42

2) Scope of undeclared variables
 Consider the following code:
 cb := Detach()
 ? Eval( cb, 10 )
 LOCAL b := {| x | x + a }
 LOCAL a := 0

In Clipper the 'a' variable in a codeblock has the *local* scope however in
Harbour the 'a' variable has the *private* scope. As a result, in Clipper
this code will print 10 and in Harbour it will raise 'argument error' in
'+' operation.
 This will be true also when the 'a' variable will be declared as PRIVATE

 cb := Detach()
 ? Eval( cb, 10 )

The above code also prints 10 in Clipper (even if compiled with -a or -v

Source :

C5 Memory Management

Clipper Memory Management

Once upon a time ..

PCs has a 640 KB memory limit and Clipper programmers was must struggled with errors such as Memory overflow, Conventional memory exhausted, Stack overflow and so on…

This article mainly focused on this subject.

In our modern era we haven’t such problems, because we have gigabytes of memory installed in our computers. Morever OS’s offers to us immense memory management possibilities transparent to us. Like we have unlimited memory to use.

But nothing can be unlimited …

This article of Roger Donnay has very useful info about efficient ways to using memory; and especially variable handling.