MemVars

Memory Variables handling

Note: all the functions below, do work with PUBLIC and/or PRIVATE variables only; they are literally "blind" to other type of variables, such as LOCALs, STATICs et.c., thereby they can't and won't operate with them. Worth noting that in Harbour Reference Guide there is quite a good documentation for these functions you can read about, starting from 👉 here, (just ignore a few inaccuracies that ensued due to source-code changes made during years of development).

• __mvPublic(<cVarName>, [<cVarNameN>], [{"cVar1","cVar2", ...}]) ➜ NIL
  attempts to create one or more PUBLIC variable(s) with name(s) passed; note that besides of single var names, an one-dimensional array, filled with (valid) variable names, can be used, also.

• __mvPrivate(<cVarName>, [<cVarNameN>], [{"cVar1","cVar2", ...}]) ➜ NIL
  same as public vars creation (see above) but used for private vars creation.

• __mvScope(<cVarName>) ➜ nScope
  returns the functional scope (operative range, i.e. visibility and accessibility level) of a variable, public or private.
  Scope constants, returned by this function, are defined in hbmemvar.ch; for reader's convenience, they are shown in the table below:

  identifier	constant value	meaning/description
  HB_MV_NOT_FOUND	-2	not found in the symbols table
  HB_MV_UNKNOWN	-1	not created yet
  HB_MV_ERROR	0	information cannot be obtained
  HB_MV_PUBLIC	1	PUBLIC variable
  HB_MV_PRIVATE_GLOBAL	2	PRIVATE [*] created outside of current function/procedure
  HB_MV_PRIVATE_LOCAL	4	PRIVATE [*] created in current function/procedure
  HB_MV_PRIVATE	6	PRIVATE [*] variable

  [*] Practically, any value equal to or greater than 2, indicates a PRIVATE variable, with values 2 & 4 identifying the creation locality, (and indirectly their visibility scope)

• __mvClear() ➜ NIL
  this function clean-ups working memory, by destroying every memory variable visible. (see more at __mvClear() entry, in Harbour Reference Guide).

• __mvDbgInfo(<nScope> [,nPosition [,@cVarName]]) ➜ xValue
  retrieves informations about memvar variables. (see more at __mvDbgInfo() entry, in Harbour Reference Guide).

• __mvExist(<cVarName>) ➜ lExists
  returns .T. if exists a public or private variable with name cVarName, otherwise .F.

• __mvGet(<cVarName>) ➜ xValue
  if the given (public or private) <cVarName> variable exists, this function returns the value that is assigned to it or NIL if no value is assigned. If the variable does not exist, a recoverable run-time error is raised, that can be handled by properly prepared custom error handler (into which, for example, could be created "on the fly" the missing variable, thus allowing to continue the processing).

• __mvGetDef(<cVarName> [,<xDefault>]) ➜ xValue
  it works in similar way to __mvGet() above, but if <cVarName> does not exist then it returns <xDefault> or NIL (if no default value specified) instead of run-time error. Note: it's a new function, available after this 2018-09-14 commit.

• __mvPut(<cVarName>, <xValue>) ➜ xValue
  sets (assigns) a value <xValue> to the (public or private) variable <cVarName>. If the variable <cVarName> does not exist, it is created as private and the value <xValue> assigned to it, unless the value type of <cVarName> is not of string type (hence, it cannot be used as a valid variable name), in which case a recoverable error is raised. The function, when successful, returns the assigned <xValue>.
  Note: in the entry of __mvPut() into Harbour Reference Guide it is stated, incorrectly, that if the variable <cVarName> does not exist "it generates a runtime error".

• __mvSetBase() ➜ NIL
  This is a "hacking" function, which changes base private offset, so all PRIVATE variables created inside the function that calls the __mvSetBase(), they not only won't be released upon exiting the function, but rather they shall be inherited by its caller.
  Obviously, this unconventional behavior violates the standard, according to which every PRIVATE (and LOCAL) variable created inside a function is released (and cleared out) upon exit off that function. Therfore, this function must be used with caution and only when the developer knows what exactly is doing.

🔙 Home