CSETREF()
 Determines whether or not reference sensitive functions return a value
------------------------------------------------------------------------------
 Syntax

     CSETREF([<lNewSwitch>]) --> lOldSwitch

 Argument

     <lNewSwitch>  Designates whether the return value is suppressed for
     specified functions.  When this parameter is .T., it suppresses the
     return value of the functions listed below.  When the parameter is .F.
     (default value), these functions return a value.

 Returns

     If no parameter is specified, the function returns the current setting.
     If a parameter is specified, the function returns the previous setting.

 Description

     A series of CA-Clipper Tools functions enable you to pass parameters by
     reference.  After executing the function, the passed parameter already
     contains the result.  However, each of these functions also returns this
     result as a value.  A copy of the passed string exists for a short time
     in working memory, but it is invisible to you.  In the worst possible
     case, two adjoining memory blocks would require up to 64 kB.

     This behavior can be influenced by implementing CSETREF(.T.).  Then the
     group of affected string functions no longer return a value, which can
     save you up to 64k of memory with large strings.

           Functions affected by CSETREF():

           ADDASCII()   BLANK()         CHARADD()

           CHARAND()    CHARMIRR()      CHARNOT()

           CHAROR()     CHARRELREP()    CHARREPL()

           CHARSORT()   CHARSWAP()      CHARXOR()

           CRYPT()      JUSTLEFT()      JUSTRIGHT()

           POSCHAR()    POSREPL()       RANGEREPL()

           REPLALL()    REPLLEFT()      REPLRIGHT()

           TOKENLOWER() TOKENUPPER()    WORDREPL()

           WORDSWAP()

 Note

     .  If, in spite of having CSETREF(.T.), you need one of the
        previously listed functions to return a value, then the target
        variable contains .F. instead of the anticipated string.

 Examples

     .  Here is how CSETREF() is set to .F.:

        CSETREF(.F.)
        cStr1  :=  "HAGBDCFE"
        cStr2  :=  CHARSORT(@cStr1)
        ? cStr1, cStr2        // "ABCDEFGH" - cStr1,cStr2 are identical

     .  Here is how CSETREF() is set to .T.:

        CSETREF(.T.)

        cStr1  :=  "HAGBDCFE"
        cStr2  :=  CHARSORT(@cStr1)
        ? cStr1               // "ABCDEFGH" - Sort cStr1
        ? cStr2               // .F.

     .  Determine when memory will be needed:

        cStr1  :=  SPACE(32000)       // Create large string

        CSETREF(.F.)
        CHARSORT(@cStr1)              // Additional 32000 bytes

        CSETREF(.T.)
        CHARSORT(@cStr1)              // Needs no additional memory