🔙 Home

        The Garbage Collector

• hb_gcAll( [<lForce>] ) ➜ NIL
  Scans the memory and releases all garbage memory blocks. Optional param <lForce> will force Garbage Collector activation in Multi Thread mode by temporary suspending all executing threads.

• hb_gcStep() ➜ lResult
  this function performs a single-step garbage collection. Returns logical value indicating whether garbage collection of unused memory chunk was performed or not. See more details and an example of use here. Also here... is the detailed documentation of the Harbour garbage collection mechanism (mostly internal API).

• hb_gcSetAuto([<nNewVal>]) ➜ nPrevVal
  set the frequency of automatic garbage collection (GC) activation.
  <nNewVal> is the (optional) number, in thousands, of allocated items that when exceeded forces garbage collector's activation; if set to 0 (zero), automatic garbage collection is deactivated! it returns the previously set value.
  Normally, the garbage collector is activated during idle states. In cases where a program allocates big number of complex items with cyclic references without entering any idle state, then it is necessary programmers to add code invoking the hb_gcAll() function; if the Automatic GC is activated, there's no need of such an extra coding.
  NOTE: This function is not included by default in binaries builds being released! To make it available, Harbour must be compiled with setting the relevant build flag: SET HB_USER_CFLAGS=-DHB_GC_AUTO

• hb_Get() ➜ oGet
  Creates a new Get object. For more, inspect tget.prg and tgethb.prg Harbour source files.
  Below is a sample code utilizing hb_Get() to create a password-like Get object:

  PROCEDURE Main()
     LOCAL cValidPass := "Top Secret"
     LOCAL cPass := GetPassword()
     LOCAL GetList
     
     CLS
     IF ! (cPass == cValidPass)
        ? "Access not allowed!"
     ELSE
        ? "Access granted!"
     ENDIF
     ? "---"
     ? "password expected: " + cValidPass
     ? "password entered : " + cPass
     RETURN
  
  FUNCTION GetPassword( cPrompt, nRow , nCol )
     LOCAL GetList := {}
     LOCAL cPass   := Space(30)
     LOCAL oGet
  
     hb_Default( @cPrompt, "Enter password:" )
     hb_Default( @nRow, 0 )
     hb_Default( @nCol, 0 )
  
     oGet := hb_Get():New( nRow, nCol+Len( cPrompt )+2 , ;
                           {|x| IIf( x == NIL, cPass, cPass := x )}, "cPass" )
     oGet:PostBlock := {|| ! Empty(cPass)} // valid block: Empty pass not allowed!
     oGet:Picture := "@S10"  //  // the get picture: modify as needed.
     oGet:ColorSpec := "w/b,r/w" // color
     oGet:HideInput := .T. // this one does the real trick!
     oGet:Style := Chr(7)
  
     AAdd(GetList, oGet)
  
     SAVE SCREEN
     CLS
     @ nRow, nCol SAY cPrompt
     ReadModal(GetList)
     RESTORE SCREEN
  
     RETURN RTrim( cPass )

• hb_GetEnv(<cEnvVar>, [<cDefaultValue>]) ➜ cValue
  retruns the value of the <cEnvVar> environment variable or <cDefaultValue> or an empty string if <cEnvVar> does not exist and no <cDefaultValue> specified.

• hb_GetReadVar()

• hb_GetStdErr()

• hb_GetStdIn()

• hb_GetStdOut()

• hb_gtAlert(cMessage, [aOptions|"Ok"],[cColorNorm],[cColorHigh],[nDelay]) ➜ nSelection
  same as hb_Alert() with an additional parameter to define hi-light color of displayed option(s).
  In fact, the hb_Alert() invokes this very function to perform the Alert service.

• hb_gtCreate(<cGtName>) ➜ pGT
  Creates a new graphic terminal window; this way an application can create many different windows (even in single thread programs) and switch between them by applying their pointers to hb_gtSelect() (see below).
  <cGtName> is the literal name of a GT that have such capabilities, like f.e., GTXWC (XWindow Console) or GTWVT (Windows GUI console).
  Returns pointer to newly created window or NIL on failure.

• hb_gtExists(<cGtName>) ➜ lExists
  returns true when the given <cGtName> GT driver is available, false otherwise. Note that the GT name has to be designated as a three letter keyword without the GT prefix, e.g.: "WVT"
  NOTE: This function is not available in Harbour 3.2 before the 2023-01-15 11:17 source-code update.

• hb_GtInfo(<nInfo>, [<xParam1>], [<xParam2>]) ➜ xResult
  returns and/or change many of GT driver settings. This is a sophisticated function with a plethora of accepted values / performed actions.

  • For a quite long list of GTI_* actions, refer to /harbour/include/hbgtinfo.ch header file.
  • For detailed documentation about this function, see this excellent page.
    Just note that not all settings are supported by all GT drivers.

• hb_gtList() ➜ aGtNames
  returns array with all available GT drivers, each one as a three letter keyword. See the code below for more...

  #if ! defined( __HBSCRIPT__HBSHELL ) 
  request hb_gt_NUL, hb_gt_WIN, hb_gt_GUI
  request hb_gt_WVT, hb_gt_STD, hb_gt_PCA, hb_gt_CGI
  #endif   
  
  PROCEDURE Main()
     LOCAL aGtNames, cGtName, cList
     SetColor( "G+/N" )
     CLS
     aGtNames := hb_gtList() // -> <aGtNames>
     cList := "" 
     for each cGtName in aGtNames
        cList += cGtName + " " + hb_CStr( hb_gtExists( cGtName ) ) + ", "
     next
     ? hb_StrShrink( cList, 2 )
     RETURN

  result of above code when run on Windows platform as a script via hbrun: NUL .T., WIN .T., GUI .T., WVT .T., STD .T., PCA .T., CGI .T., CTW .T. (by the way, if any harbour user out there knows sth about the GT drivers: STD, PCA & CTW and how or when they could be used please be so kind to let us know).
  NOTE: This function is not available in Harbour 3.2 before the 2023-01-15 11:17 source-code update.

• hb_gtLock() ➜ lSuccess
  Locks the current GT console to permit output only from current process (thread), which means that console output from any other thread is blocked.
  NOTE: be careful using GT lock and always unlock locked GT!

• hb_gtReload(<cGtName>) ➜ lSuccess
  By default new thread inherits console Window from parent thread. But each thread can allocate its own console window by calling hb_gtReload(<cGtName>) function, f.e. by: hb_gtReload( hb_gtVersion() ). If the GT driver supports such functionality, then new thread will allocate new console windows. Each console window has reference counter which is increased when new thread starts and decreased when hb_gtReload() is executed or thread terminates. When counter reach zero console window is destroyed.

• hb_gtSelect([<pGT>]) ➜ pPrevGT
  selects the window specified by <pGT>. Returns pointer of the previous selected GT window.

• hb_GTSYS()

• hb_gtUnlock() ➜ lResult
  unlocks previously locked console output.

• hb_GtVersion() ➜ cGtID
  returns GT identifier, e.g.: WVT

• NOTE: see this and this code sample concerning hb_gt***() functions usage.

It must be noted here that there exists a group of hb_Gz***() core functions which, alphabetically, should be placed here. However, I decided to move them at a dedicated, separate Compress page, so to be together with other, relative compression functions. Also in that page, I have included the hb_ZLib***() core functions.

🔙 Home