harbour-core/harbour/doc/en/var.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
 *    Documentation for: __MVPUBLIC(), __MVPRIVATE(), __MVXRELEASE(),
 *                       __MVRELEASE(), __MVSCOPE(), __MVCLEAR(),
 *                       __MVDBGINFO(), __MVGET(), __MVPUT(), MEMVARBLOCK(),
 *                       TYPE()
 *
 * Copyright 1999 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: FIELDBLOCK(), FIELDWBLOCK()
 *
 * Copyright 2001 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: __MVEXIST()
 *
 * Copyright 2002 Walter Negro <anegro@overnet.com.ar>
 *    Documentation for: HB_ISBYREF()
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVPUBLIC()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function creates a PUBLIC variable
 *  $SYNTAX$
 *      __MVPUBLIC( <variable_name> )
 *  $ARGUMENTS$
 *      <variable_name> = either a string that contains the variable's name or
 *      an one-dimensional array of strings with variable names
 *      No skeleton are allowed here.
 *  $RETURNS$
 *      Nothing
 *  $DESCRIPTION$
 *      This function can be called either by the harbour compiler or by user.
 *      The compiler always passes the item of IT_SYMBOL type that stores the
 *      name of variable.
 *      If a variable with the same name exists already then the new
 *      variable is not created - the previous value remains unchanged.
 *      If it is first variable with this name then the  variable is
 *      initialized with .T. value.
 *  $EXAMPLES$
 *      None Avaliable
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVPRIVATE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function creates a PRIVATE variable
 *  $SYNTAX$
 *      __MVPRIVATE( <variable_name> )
 *  $ARGUMENTS$
 *      <variable_name> = either a string that contains the variable's name or
 *      an one-dimensional array of strings with variable names
 *      No skeleton are allowed here.
 *  $RETURNS$
 *      Nothing
 *  $DESCRIPTION$
 *      This function can be called either by the harbour compiler or by user.
 *      The compiler always passes the item of IT_SYMBOL type that stores the
 *      name of variable.
 *      If a variable with the same name exists already then the value of old
 *      variable is hidden until the new variable is  released. The new variable
 *      is always initialized to NIL value.
 *  $EXAMPLES$
 *      None Avaliable
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVXRELEASE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function releases value stored in PRIVATE or PUBLIC variable
 *  $SYNTAX$
 *      __MVXRELEASE( <variable_name> )
 *  $ARGUMENTS$
 *      <variable_name> = either a string that contains the variable's name or
 *      an one-dimensional array of strings with variable names
 *      No skeleton are allowed here.
 *  $RETURNS$
 *      Nothing
 *  $DESCRIPTION$
 *      This function releases values stored in memory variable. It shouldn't
 *      be called directly, rather it should be placed into RELEASE command.
 *      If the released variable is a PRIVATE variable then previously hidden
 *      variable with the same name becomes visible after exit from the
 *      procedure where released variable was created. If you access
 *      the released variable in the same function/procedure where it
 *      was created the the NIL value is returned. You can however assign
 *      a new value to released variable without any side effects.
 *
 *      It releases variable even if this variable was created in different
 *      procedure
 *  $EXAMPLES$
 *      PROCEDURE MAIN()
 *      PRIVATE mPrivate
 *
 *        mPrivate :="PRIVATE from MAIN()"
 *        ? mPrivate     //PRIVATE from MAIN()
 *        Test()
 *        ? mPrivate     //PRIVATE from MAIN()
 *
 *      RETURN
 *
 *      PROCEDURE Test()
 *      PRIVATE mPrivate
 *
 *        mPrivate :="PRIVATE from Test()"
 *        ? mPrivate           //PRIVATE from TEST()
 *        RELEASE mPrivate
 *        ? mPrivate           //NIL
 *        mPrivate :="Again in Test()"
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVRELEASE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function releases PRIVATE variables
 *  $SYNTAX$
 *      __MVRELEASE( <skeleton>, <include_exclude_flag> )
 *  $ARGUMENTS$
 *      <skeleton> = string that contains the wildcard mask for variables' names
 *      that will be released. Supported wildcards: '*' and '?'
 *      <include_exclude_flag> = logical value that specifies if variables
 *      that match passed skeleton should be either included in deletion
 *      (if .T.) or excluded from deletion (if .F.)
 *  $RETURNS$
 *    Nothing
 *  $DESCRIPTION$
 *      This function releases values stored in memory variables. It shouldn't
 *      be called directly, it should be placed into RELEASE ALL command.
 *      If the released variable is a PRIVATE variable then previously hidden
 *      variable with the same name becomes visible after exit from the
 *      procedure where released variable was created. If you access
 *      the released variable in the same function/procedure where it
 *      was created the the NIL value is returned. You can however assign
 *      a new value to released variable without any side effects.
 *      PUBLIC variables are not changed by this function.
 *  $EXAMPLES$
 *      None Avaliable
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVSCOPE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      If variable exists then returns its scope.
 *  $SYNTAX$
 *      __MVSCOPE( <cVarName> )
 *  $ARGUMENTS$
 *      <cVarName> = a string with a variable name to check
 *  $RETURNS$
 *      The symbolic values are defined in include/hbmemvar.ch
 *      HB_MV_NOT_FOUND     =variable is not declared (not found in symbol table)
 *      HB_MV_UNKNOWN       =if variable doesn't exist (but found in symbol table)
 *      HB_MV_ERROR         =if information cannot be obtained (memory error
 *      or argument error)
 *      HB_MV_PUBLIC         =for public variables
 *      HB_MV_PRIVATE_GLOBAL =for private variables declared outside of current
 *      function/procedure
 *      HB_MV_PRIVATE_LOCAL  =for private variables declared in current
 *      function/procedure
 *  $EXAMPLES$
 *      PROCEDURE MAIN()
 *      PUBLIC mPublic
 *      PRIVATE mPrivateGlobal
 *
 *      CallProc()
 *      ? __mvScope( "mPrivateLocal" )      //HB_MV_UNKNOWN
 *
 *      RETURN
 *
 *      PROCEDURE CallProc()
 *      PRIVATE mPrivateLocal
 *
 *      ? __mvScope( "mPublic" )            //HB_MV_PUBLIC
 *      ? __mvScope( "mPrivateGlobal" )     //HB_MV_PRIVATE_GLOBAL
 *      ? __mvScope( "mPrivateLocal" )      //HB_MV_PRIVATE_LOCAL
 *      ? __mvScope( "mFindMe" )            //HB_MV_NOT_FOUND
 *
 *      IF( __mvScope( "mPublic" ) > HB_MV_ERROR )
 *         ? "Variable exists"
 *      ELSE
 *         ? "Variable not created yet"
 *      ENDIF
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      include/hbmemvar.ch
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVCLEAR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function releases all PRIVATE and PUBLIC variables
 *  $SYNTAX$
 *      __MVCLEAR()
 *  $ARGUMENTS$
 *      None
 *  $RETURNS$
 *      Nothing
 *  $DESCRIPTION$
 *      This function releases all PRIVATE and PUBLIC variables.
 *      It is used to implement CLEAR MEMORY statement.
 *      The memory occupied by all visible variables are released - any
 *      attempt to access the variable will result in a runtime error.
 *      You have to reuse PRIVATE or PUBLIC statement to create again
 *      the variable that was cleared by this function.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *      __MVPUBLIC()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVDBGINFO()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Internal
 *  $ONELINER$
 *      This function returns the information about the variables for debugger
 *  $SYNTAX$
 *      __MVDBGINFO( <nScope> [, <nPosition> [, @<cVarName>] ] )
 *  $ARGUMENTS$
 *      <nScope> = the scope of variables for which an information is asked
 *           Supported values (defined in hbmemvar.ch)
 *           HB_MV_PUBLIC
 *           HB_MV_PRIVATE (or any other value)
 *      <nPosition> = the position of asked variable on the list of variables
 *      with specified scope - it should start from position 1
 *      <cVarName> = the value is filled with a variable name if passed by
 *      reference and <nPosition> is specified
 *  $RETURNS$
 *      The return value depends on the number of arguments passed
 *  $DESCRIPTION$
 *      This function retrieves the information about memvar variables.
 *      It returns either the number of variables with given scope (when the
 *      first argument is passed only) or a value of variable identified by its
 *      position in the variables' list (when second argument is passed).
 *      It also returns the name of a variable if optional third argument
 *      is passed by reference.
 *
 *      If requested variable doesn't exist (requested position is
 *      greater then the number of defined variables) then NIL value is
 *      returned and variable name is set to "?"
 *
 *      The dynamic symbols table is used to find a PUBLIC variable then
 *      the PUBLIC variables are always sorted alphabetically. The PRIVATE
 *      variables are sorted in the creation order.
 *
 *      Note:
 *
 *      Due to dynamic nature of memvar variables there is no guarantee that
 *      successive calls to retrieve the value of <Nth> PUBLIC variable will
 *      return the value of the same variable.
 *  $EXAMPLES$
 *      #include <hbmemvar.ch>
 *
 *      LOCAL nCount, i, xValue, cName
 *
 *      nCount =_mvDBGINFO( HB_MV_PUBLIC )
 *      FOR i:=1 TO nCount
 *          xValue =__mvDBGINFO( HB_MV_PUBLIC, i, @cName )
 *          ? i, cName, xValue
 *      NEXT
 *  $TESTS$
 *      #include <hbmemvar.ch>
 *      PROCEDURE MAIN()
 *
 *      ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC )
 *      ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE )
 *
 *      PUBLIC cPublic:='cPublic in MAIN'
 *
 *      ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC )
 *      ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE )
 *
 *      PRIVATE cPrivate:='cPrivate in MAIN'
 *
 *      ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC )
 *      ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE )
 *
 *      CountMemvars()
 *
 *      ? 'Back in Main'
 *      ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC )
 *      ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE )
 *
 *      RETURN
 *
 *      PROCEDURE CountMemvars()
 *      LOCAL i, nCnt, xVal, cName
 *      PUBLIC ccPublic:='ccPublic'
 *      PRIVATE ccPrivate:='ccPrivate'
 *
 *      ? 'In CountMemvars'
 *      ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC )
 *      ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE )
 *
 *      PRIVATE cPublic:='cPublic'
 *
 *      ? 'PUBLIC=', __mvDBGINFO( HB_MV_PUBLIC )
 *      ? 'PRIVATE=', __mvDBGINFO( HB_MV_PRIVATE )
 *
 *      nCnt =__mvDBGINFO( HB_MV_PRIVATE ) +1
 *      FOR i:=1 TO nCnt
 *        xVal =__mvDBGINFO( HB_MV_PRIVATE, i, @cName )
 *        ? i, '=', cName, xVal
 *      NEXT
 *
 *      nCnt =__mvDBGINFO( HB_MV_PUBLIC ) +1
 *      FOR i:=1 TO nCnt
 *        xVal =__mvDBGINFO( HB_MV_PUBLIC, i, @cName )
 *        ? i, '=', cName, xVal
 *      NEXT
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *     This function should be called from the debugger only.
 *  $FILES$
 *      Library is vm
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVEXIST()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Determine if a given name is a PUBLIC or PRIVATE memory variable
 *  $SYNTAX$
 *      __MVEXIST( <cVarName> )  --> <lVariableExist>
 *  $ARGUMENTS$
 *      <cVarName> - string that specifies the name of variable to check
 *  $RETURNS$
 *      __MVEXIST() return TRUE (.T.) if a MEMVAR named <cVarName> exist.
 *  $DESCRIPTION$
 *      This function determine if a PUBLIC or PRIVATE variable with the
 *      name <cVarName> exist or not.
 *  $EXAMPLES$
 *      LOCAL   TheLocal
 *      STATIC  TheStatic
 *      PUBLIC  ThePublic
 *      PRIVATE ThePrivate
 *      ? __MVEXIST( "NotExist"   )        // .F.
 *      ? __MVEXIST( "TheLocal"   )        // .F.
 *      ? __MVEXIST( "TheStatic"  )        // .F.
 *      ? __MVEXIST( "ThePublic"  )        // .T.
 *      ? __MVEXIST( "ThePrivate" )        // .T.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $SEEALSO$
 *      MEMVAR, PRIVATE, PUBLIC
 *  $FILES$
 *      Library is vm
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVGET()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function returns value of memory variable
 *  $SYNTAX$
 *      __MVGET( <cVarName> )  --> <xVar>
 *  $ARGUMENTS$
 *      <cVarName> - string that specifies the name of variable
 *  $RETURNS$
 *      <xVar> The value of variable
 *  $DESCRIPTION$
 *      This function returns the value of PRIVATE or PUBLIC variable if
 *      this variable exists otherwise it generates a runtime error.
 *      The variable is specified by its name passed as the function parameter.
 *  $EXAMPLES$
 *      FUNCTION MEMVARBLOCK( cMemvar )
 *      RETURN {|x| ;
 *          IIF( PCOUNT()==0, ;
 *          __MVGET( cMemvar ),;
 *          __MVPUT( cMemvar, x ) ) }
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $SEEALSO$
 *      __MVPUT()
 *  $FILES$
 *      Library is vm
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __MVPUT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      This function set the value of memory variable
 *  $SYNTAX$
 *      __MVGET( <cVarName> [, <xValue>] )  --> <xValue>
 *  $ARGUMENTS$
 *      <cVarName> - string that specifies the name of variable
 *      <xValue>   - a value of any type that will be set - if it is not
 *      specified then NIL is assumed
 *  $RETURNS$
 *      <xValue> A value assigned to the given variable.
 *  $DESCRIPTION$
 *      This function sets the value of PRIVATE or PUBLIC variable if
 *      this variable exists otherwise it generates a runtime error.
 *      The variable is specified by its name passed as the function
 *      parameter.
 *      If a value is not specified then the NIL is assumed
 *  $EXAMPLES$
  *      FUNCTION MEMVARBLOCK( cMemvar )
 *      RETURN {|x| ;
 *          IIF( PCOUNT()==0, ;
 *          __MVGET( cMemvar ),;
 *          __MVPUT( cMemvar, x ) ) }
*  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is vm
 *  $SEEALSO$
 *    __MVPUT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      MEMVARBLOCK()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Returns a codeblock that sets/gets a value of memvar variable
 *  $SYNTAX$
 *      MEMVARBLOCK( <cMemvarName> ) --> <bBlock>
 *  $ARGUMENTS$
 *      <cMemvarName> - a string that contains the name of variable
 *  $RETURNS$
 *      <bBlock> a codeblock that sets/get the value of variable
 *  $DESCRIPTION$
 *      This function returns a codeblock that sets/gets the value of
 *      PRIVATE or PUBLIC variable. When this codeblock is evaluated
 *      without any parameters passed then it returns the current value
 *      of given variable. If the second parameter is passed for
 *      the codeblock evaluation then its value is used to set the new
 *      value of given variable - the passed value is also returned
 *      as a value of the codeblock evaluation.
 *  $EXAMPLES$
 *      PROCEDURE MAIN()
 *      LOCAL cbSetGet
 *      PUBLIC xPublic
 *
 *      cbSetGet = MEMVARBLOCK( "xPublic" )
 *      EVAL( cbSetGet, "new value" )
 *      ? "Value of xPublic variable", EVAL( cbSetGet )
 *
 *      RETURN
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $SEEALSO$
 *      __MVGET(),__MVPUT()
 *  $FILES$
 *      Library is rtl
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FIELDBLOCK()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      RDD
 *  $ONELINER$
 *      Return a code block that sets/gets a value for a given field
 *  $SYNTAX$
 *      FIELDBLOCK( <cFieldName> ) --> bFieldBlock
 *  $ARGUMENTS$
 *      <cFieldName> is a string that contain the field name.
 *  $RETURNS$
 *      FIELDBLOCK() return a code block that when evaluate could retrieve
 *      a field value or assigning a new value to the field. If <cFieldName>
 *      is not specified or from type other than character, FIELDBLOCK()
 *      return NIL.
 *  $DESCRIPTION$
 *      FIELDBLOCK() return a code block that sets/gets the value of field.
 *      When this code block is evaluated without any parameters passed then
 *      it returns the current value of the given field. If the code block
 *      is evaluated with a parameter, than its value is used to set a new
 *      value to the field, this value is also return by the block. If the
 *      block is evaluate and there is no field with the name <cFieldName>
 *      in the current work area, the code block return NIL.
 *
 *      Note that FIELDBLOCK() works on the current work area, if you need
 *      a specific work area code block use FIELDWBLOCK() instead.
 *  $EXAMPLES$
 *      // open a file named Test that have a field named "name"
 *      LOCAL bField
 *      bFiled := FIELDBLOCK( "name" )
 *      USE Test
 *      ? 'Original value of field "name" :', EVAL( bField )
 *      EVAL( bField, "Mr X new name" )
 *      ? 'New value for the field "name" :', EVAL( bField )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      If the block is evaluate and there is no field with the name
 *      <cFieldName> in the current work area, the code block return NIL.
 *
 *      CA-Cl*pper would raise BASE/1003 error if the field does not exist.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      EVAL(),FIELDWBLOCK(),MEMVARBLOCK()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FIELDWBLOCK()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      RDD
 *  $ONELINER$
 *      Return a sets/gets code block for field in a given work area
 *  $SYNTAX$
 *      FIELDWBLOCK( <cFieldName>, <nWorkArea> ) --> bFieldBlock
 *  $ARGUMENTS$
 *      <cFieldName> is a string that contain the field name.
 *
 *      <nWorkArea> is the work area number in which <cFieldName> exist.
 *  $RETURNS$
 *      FIELDWBLOCK() return a code block that when evaluate could retrieve
 *      field value or assigning a new value for a field in a given work
 *      area. If <cFieldName> is not specified or from type other than
 *      character, or if <nWorkArea> is not specified or is not numeric
 *      FIELDWBLOCK() return NIL.
 *  $DESCRIPTION$
 *      FIELDWBLOCK() return a code block that sets/gets the value of field
 *      from a given work area. When this code block is evaluated without
 *      any parameters passed then it returns the current value of the given
 *      field. If the code block is evaluated with a parameter, than its
 *      value is used to set a new value to the field, this value is also
 *      return by the block. If the block is evaluate and there is no field
 *      with the name <cFieldName> in work area number <nWorkArea>, the code
 *      block return NIL.
 *  $EXAMPLES$
 *      LOCAL bField
 *      // this block work on the field "name" that exist on work area 2
 *      bFiled := FIELDBLOCK( "name", 2 )
 *      // open a file named One in work area 1
 *      // that have a field named "name"
 *      SELECT 1
 *      USE One
 *      // open a file named Two in work area 2
 *      // it also have a field named "name"
 *      SELECT 2
 *      USE Two
 *      SELECT 1
 *      ? "Original names: ", One->name, Two->name
 *      ? "Name value for file Two :", EVAL( bField )
 *      EVAL( bField, "Two has new name" )
 *      ? "and now: ", One->name, Two->name
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      If the block is evaluate and there is no field with the name
 *      <cFieldName> in the given work area, the code block return NIL.
 *
 *      CA-Cl*pper would raise BASE/1003 error if the field does not exist.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      EVAL(),FIELDBLOCK(),MEMVARBLOCK()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      TYPE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Retrieves the type of an expression
 *  $SYNTAX$
 *      TYPE( <cExp> ) --> <cRetType>
 *  $ARGUMENTS$
 *      <cExp> must be a character expression.
 *  $RETURNS$
 *      <cRetType> a string indicating the type of the passed expression.
 *
 *      <table>
 *        <cRetType>   Meaning
 *
 *        "A"          Array
 *        "B"          Block
 *        "C"          Character (string)
 *        "D"          Date
 *        "L"          Logical
 *        "M"          Memo
 *        "N"          Numeric
 *        "O"          Object
 *        "P"          Pointer
 *        "S"          Symbol
 *        "U"          NIL, local or static variable, or not linked-in function
 *        "UE"         syntax error in the expression or invalid arguments
 *        "UI"         function with non-reserved name was requested
 *      </table>
 *  $DESCRIPTION$
 *      This function returns a string which represents the data type
 *      of the argument. The argument can be any valid Harbour expression.
 *      If there is a syntax error in passed expression then "UE" is returned.
 *      If there is a call for any non-reserved Harbour function then "UI"
 *      is returned (in other words there is no call for passed UDF function
 *      during a data type determination - this is CA-Cl*pper compatible
 *      behavior). Additionally if requested user defined function is not
 *      linked into executable then "U" is returned.
 *
 *      The data type of expression is checked by invoking a macro compiler
 *      and by evaluation of generated code (if there is no syntax errors).
 *      This causes that TYPE() cannot determine a type of local or static
 *      variables - only symbols visible at runtime can be checked.
 *
 *      Notice the subtle difference between TYPE and VALTYPE functions.
 *      VALTYPE() function doesn't call a macro compiler - it simply checks
 *      the type of passed argument of any type. TYPE() requires a string
 *      argument with a valid Harbour expression - the data type of this
 *      expression is returned.
 *  $EXAMPLES$
 *       ? TYPE( "{ 1, 2 }" )                            //prints "A"
 *       ? TYPE( "IIF(.T., SUBSTR('TYPE',2,1), .F.)" )   //prints "C"
 *       ? TYPE( "AT( 'OK', MyUDF())>0" )                //prints "UI"
 *       ? TYPE( "{ 1, 2 }[ 5 ]" )                       //prints "UE"
 *
 *       //--------------------------------------------------------
 *
 *       LOCAL c
 *       PRIVATE a:="A", b:="B"
 *       ? TYPE( "a + b + c" )     //prints: "U" ('C' variable is a local one)
 *
 *       //--------------------------------------------------------
 *
 *       LOCAL cFilter := SPACE( 60 )
 *       ACCEPT "Enter filter expression:" TO cFilter
 *       IF( TYPE( cFilter ) $ "CDLMN" ) )
 *          // this is a valid expression
 *          SET FILTER TO &cFilter
 *       ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      - Incompatibility with CA-Cl*pper:
 *        In the following code:
 *
 *          PRIVATE lCond := 0
 *          ? TYPE( "IIF( lCond, 'true', MyUDF() )" )
 *
 *        CA-Cl*pper will print "UE" - in Harbour the output will be "UI"
 *
 *      - If "UI" is returned then the syntax of the expression is
 *        correct. However invalid arguments can be passed to
 *        function/procedure that will cause runtime errors during
 *        evaluation of expression.
 *
 *      - Harbour supports two new types (Pointer and Symbol) which does
 *        not exists in CA-Cl*pper.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      VALTYPE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      VALTYPE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Retrieves the data type of an expression
 *  $SYNTAX$
 *      VALTYPE( <xExp> ) --> <cRetType>
 *  $ARGUMENTS$
 *      <xExp> is any valid expression.
 *  $RETURNS$
 *      <cRetType> a character indicating the type of the passed expression.
 *
 *      <table>
 *        <cRetType>   Meaning
 *
 *        "A"          Array
 *        "B"          Block
 *        "C"          Character (string)
 *        "D"          Date
 *        "L"          Logical
 *        "M"          Memo
 *        "N"          Numeric
 *        "O"          Object
 *        "P"          Pointer
 *        "S"          Symbol
 *        "U"          NIL
 *  </table>
 *  $DESCRIPTION$
 *      This function returns one character which represents the data type
 *      of the argument.
 *  $EXAMPLES$
 *      See Test(s)
 *  $TESTS$
 *      function Test()
 *         ? ValType( Array( 1 ) )   // "A"
 *         ? ValType( {|| 1 + 1 } )  // "B"
 *         ? ValType( "HARBOUR" )    // "C"
 *         ? ValType( Date() )       // "D"
 *         ? ValType( .T. )          // "L"
 *         ? ValType( 1 )            // "N"
 *         ? ValType( TBrowse() )    // "O"
 *         ? ValType( hb_idleadd() ) // "P" Harbour extension
 *         ? ValType( @QOut() )      // "S" Harbour extension
 *         ? ValType( NIL )          // "U"
 *      return nil
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      VALTYPE() is CA-Cl*pper compliant, with the addition of the new
 *      Harbour types: Pointer and Symbol.
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      TYPE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_ISBYREF()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Determine if a variable is passed by reference.
 *  $SYNTAX$
 *      HB_ISBYREF( @<Var> ) --> <lVarIsByRef>
 *  $ARGUMENTS$
 *      @<Var> is the variable to test; it must be passed by reference.
 *  $RETURNS$
 *      <lVarIsByRef> a logical value indicating if the variable is passed
 *      by reference to actual function or procedure.
 *  $DESCRIPTION$
 *      This function return a logical value indicating if the variable
 *      is passed by reference to actual function or procedure.
 *
 *      ATTENTION: The variable to test must be passed by reference.
 *      If the variable is not passed by reference, the function return NIL.
 *      This function is based on the form that Harbour manages to the
 *      variables for reference. When a variable is passed by reference,
 *      what receives the function or procedure is, a pointer to the
 *      previous variable, be this the container variable of the data or
 *      a pointer to another variable. The function observes if the
 *      variable passed points to a common variable or to a variable
 *      passed by reference.
 *  $EXAMPLES$
 *      See Tests
 *  $TESTS$
 *      function Main()
 *         local cVar := "Test local"
 *         private nVar := 0
 *
 *         Test( @cVar, @nVar, cVar, nVar )
 *      return nil
 *
 *      procedure Test( Arg1, Arg2, Arg3, Arg4 )
 *         ? hb_isbyref( @Arg1 )        // .T.
 *         ? hb_isbyref( @Arg2 )        // .T.
 *         ? hb_isbyref( @Arg3 )        // .F.
 *         ? hb_isbyref( @Arg4 )        // .F.
 *      return
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      VALTYPE()
 *  $END$
 */