harbour-core/doc/en/var.txt

/*
 * 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_PIsByRef()
 *
 * See COPYING.txt 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 core
   $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 core
   $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 := "PRIVATE from Main()"

         ? mPrivate     // PRIVATE from Main()
         Test()
         ? mPrivate     // PRIVATE from Main()

         RETURN

      PROCEDURE Main()

         PRIVATE mPrivate := "PRIVATE from Main()"

         ? mPrivate           // PRIVATE from Main()
         RELEASE mPrivate
         ? mPrivate           // NIL
         mPrivate := "Again in Main()"

         RETURN
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $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 core
   $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 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 core
   $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 core
   $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"

      PROCEDURE Main()

         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

         //

         ? "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 core
   $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 core
   $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 core
   $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 core
   $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 core
   $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.dbf that have a field named "name"
      LOCAL 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 core
   $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$
      // this block work on the field "name" that exist on work area 2
      LOCAL 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 core
   $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( "iof( 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 core
   $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$
      PROCEDURE Main()
         ? 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
   $STATUS$
      R
   $COMPLIANCE$
      ValType() is CA-Cl*pper compliant, with the addition of the new
      Harbour types: Pointer and Symbol.
   $FILES$
      Library is core
   $SEEALSO$
      Type()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_PIsByRef()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Variable management
   $ONELINER$
      Determine if a parameter is passed by reference.
   $SYNTAX$
      hb_PIsByRef( nParam ) --> <lParamIsByRef>
   $ARGUMENTS$
      <nParam> is the parameter number to test.
   $RETURNS$
      <lVarIsByRef> a logical value indicating if the parameter is
      passed by reference to actual function or procedure.
   $DESCRIPTION$
      This function return a logical value indicating if the parameter
      is passed by reference to actual function or procedure.

      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$
      PROCEDURE Main()

         LOCAL cVar := "Test local"

         MEMVAR m_nVar
         PRIVATE m_nVar := 0

         Test( @cVar, @m_nVar, cVar, m_nVar )

         RETURN

      STATIC PROCEDURE Test( Arg1, Arg2, Arg3, Arg4 )
         ? hb_PIsByRef( 1 )        // .T.
         ? hb_PIsByRef( 2 )        // .T.
         ? hb_PIsByRef( 3 )        // .F.
         ? hb_PIsByRef( 4 )        // .F.
         RETURN
   $STATUS$
      S
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $SEEALSO$
      ValType()
   $END$
 */