harbour-core/doc/en/var.txt

/* $DOC$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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 HB_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.
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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 HB_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.
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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$
      MEMVAR mPrivate

      PROCEDURE Main()

         PRIVATE mPrivate := "PRIVATE from Main()"

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

         RETURN

      STATIC PROCEDURE Test()

         PRIVATE mPrivate := "PRIVATE from Test()"

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

         RETURN
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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.
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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
      <table-noheader>
       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
      </table>
   $EXAMPLES$
      #include "hbmemvar.ch"

      MEMVAR pPublic
      MEMVAR mPrivateGlobal
      MEMVAR mPrivateLocal

      PROCEDURE Main()

         PUBLIC pPublic
         PRIVATE mPrivateGlobal

         CallProc()
         ? __mvScope( "mPrivateLocal" )   // --> HB_MV_UNKNOWN

         RETURN

      STATIC PROCEDURE CallProc()

         PRIVATE mPrivateLocal

         ? __mvScope( "pPublic" )         // --> HB_MV_PUBLIC
         ? __mvScope( "mPrivateGlobal" )  // --> HB_MV_PRIVATE_GLOBAL
         ? __mvScope( "mPrivateLocal" )   // --> HB_MV_PRIVATE_LOCAL
         ? __mvScope( "mFindMe" )         // --> HB_MV_NOT_FOUND

         IF __mvScope( "pPublic" ) > HB_MV_ERROR
            ? "Variable exists"
         ELSE
            ? "Variable not created yet"
         ENDIF

         RETURN
   $STATUS$
      R
   $COMPLIANCE$
      H
   $FILES$
      Library is core
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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)
      <table-noheader>
       HB_MV_PUBLIC
       HB_MV_PRIVATE (or any other value)
      </table>

      <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"

      MEMVAR cPublic
      MEMVAR cPrivate
      MEMVAR ccPublic
      MEMVAR ccPrivate

      PROCEDURE Main()

         LOCAL nCount, tmp, xValue, cName

         nCount := __mvDbgInfo( HB_MV_PUBLIC )
         FOR tmp := 1 TO nCount
            xValue := __mvDbgInfo( HB_MV_PUBLIC, tmp, @cName )
            ? tmp, 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

      STATIC PROCEDURE CountMemvars()

         LOCAL nCount, tmp, xValue, 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 )

         nCount := __mvDbgInfo( HB_MV_PRIVATE ) + 1
         FOR tmp := 1 TO nCount
            xValue := __mvDbgInfo( HB_MV_PRIVATE, tmp, @cName )
            ? tmp, "=", cName, xValue
         NEXT

         nCount := __mvDbgInfo( HB_MV_PUBLIC ) + 1
         FOR tmp := 1 TO nCount
            xValue := __mvDbgInfo( HB_MV_PUBLIC, tmp, @cName )
            ? tmp, "=", cName, xValue
         NEXT

         RETURN
   $STATUS$
      R
   $COMPLIANCE$
      This function should be called from the debugger only.
   $FILES$
      Library is core
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999-2001 Chen Kedem <niki@actcom.co.il>
   $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$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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$
      ? ValType( MemVarBlock( "myvar" ) )
      STATIC 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$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $TEMPLATE$
      Function
   $NAME$
      __mvPut()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Variable management
   $ONELINER$
      This function set the value of memory variable
   $SYNTAX$
      __mvPut( <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$
      ? ValType( MemVarBlock( "myvar" ) )
      STATIC 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$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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$
      LOCAL cbSetGet
      PUBLIC xPublic

      cbSetGet := MemVarBlock( "xPublic" )
      Eval( cbSetGet, "new value" )
      ? "Value of xPublic variable", Eval( cbSetGet )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $SEEALSO$
      __mvGet(), __mvPut()
   $FILES$
      Library is core
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999-2001 Chen Kedem <niki@actcom.co.il>
   $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 "first"
      LOCAL bField
      USE test
      bField := FieldBlock( "first" )
      ? "Original value of field 'first':", Eval( bField )
      Eval( bField, "Mr X new name" )
      ? "New value for the field 'first':", 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$
   $AUTHOR$
      Copyright 1999-2001 Chen Kedem <niki@actcom.co.il>
   $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
      // open a file named 'one' in work area 1 that has a field named "first"
      SELECT 1
      USE one
      // open a file named 'two' in work area 2 that also has a field named "first"
      SELECT 2
      USE two
      SELECT 1
      // this block works on the field "first" that exists on work area 2
      bField := FieldWBlock( "first", 2 )
      ? "Original 'first' values:", one->first, two->first
      ? "'first' value for file 'two':", Eval( bField )
      Eval( bField, "'two' has updated 'first'" )
      ? "and now:", one->first, two->first
   $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$
   $AUTHOR$
      Copyright 1999 Ryszard Glab <rglab@imid.med.pl>
   $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$
      LOCAL c, cFilter
      MEMVAR a, b

      ? Type( "{ 1, 2 }" )                                 // --> "A"
      ? Type( 'iif( .T., SubStr( "TYPE", 2, 1 ), .F. )' )  // --> "C"
      ? Type( 'At( "OK", MyUDF() ) > 0' )                  // --> "UI"
      ? Type( "{ 1, 2 }[ 5 ]" )                            // --> "UE"

      PRIVATE a := "A", b := "B"
      ? Type( "a + b + c" )     // --> "U" ('c' variable is a local one)

      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$
      ? 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"
   $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$
   $AUTHOR$
      Copyright 2002 Walter Negro <anegro@overnet.com.ar>
   $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$
 */