DECLARE*       Create and initialize private memory variables and arrays
 DECLARE*
 Create and initialize private memory variables and arrays

 Syntax: DECLARE <identifier> [[:= <initializer>], ... ]

 Arguments

     <identifier> is the name of a private variable or array to create.
     If the <identifier> is followed by square brackets ([ ]), it is created
     as an array.  If the <identifier> is an array, the syntax for
     specifying the number of elements for each dimension is either
     array[<nElements>, <nElements2>,...] or
     array[<nElements>][<nElements2>]...  The maximum number of elements per
     dimension is 4096.

     <initializer> is the optional assignment of a value to a new
     private variable.  An <initializer> for a private variable consists of
     the in-line assignment operator (:=) followed by any valid Clipper
     expression, including a literal array.  If no explicit <initializer> is
     specified, the variable is given an initial value of NIL.  In the case
     of an array, each element is NIL.  Array identifiers, cannot be given
     values with an <initializer>.

     A list of variables or arrays can be created and optionally initialized
     with one DECLARE statement if each definition is separated by a comma.

 Description

     DECLARE is a compatibility statement that is a synonym for the PRIVATE
     statement.  Its general use is not recommended.  PRIVATE should be used
     in all instances.  See PRIVATE for more information.


 FIELDBLOCK()
 Return a set-get code block for a field variable

 Syntax: FIELDBLOCK(<cFieldName>) --> bFieldBlock

 Arguments

     <cFieldName> is the name of the field the set-get block will refer to.

 Returns

     FIELDBLOCK() returns a code block the when evaluated sets (assigns) or
     gets (retrieves) the value of the given field.  If <cFieldName> does
     not exist in the current work area, FIELDBLOCK() returns NIL.

 Description

     FIELDBLOCK() is a database function that builds a code block.  When
     executed with a argument, the code block created by this function
     assigns the value of the argument to <cFieldName>.  When executed
     without a argument, the code block retrieves the value of <cFieldName>.

 Notes

       Work Area: The code block returned by FIELDBLOCK() sets
        or gets the value of the specified field in whatever work area is
        current when the block is run.  For example, given work areas 1 and
        2, both containing field FName:

        SELECT 1
        FName:= "Kate"
        SELECT 2
        FName := "Cindy"

        bFName := FIELDBLOCK("FName")

        SELECT 1
        ? EVAL(bFName)      // "Kate"
        SELECT 2
        ? EVAL(bFName)      // "Cindy"

        The function FIELDWBLOCK() provides a set-get block for a field in a
        specific work area.

 Examples

     The following example compares FIELDBLOCK() to a code block created
     using the macro operator.  Note that using FIELDBLOCK() allows you to
     avoid the speed and size overhead of the macro operator:

     // Set-Get block defined using macro operator
     bSetGet := &( "{ |setVal| IF( setVal == NIL, FName, FName := setVal ) }" )

     // Set-Get block defined using FIELDBLOCK()
     // bSetGet created here is the functional equivalent of bSetGet above
     bSetGet := FIELDBLOCK("FName")

 Files:  Library is CLIPPER.LIB.
 seealso: "FIELDWBLOCK()" "MEMVARBLOCK()"


 FIELDGET()
 Retrieve the value of a field using the ordinal position of the
 field in the database structure

 Syntax: FIELDGET(<nField>) --> valueField

 Arguments

     <nField>is the ordinal position of the field in the record
     structure for the current work area.

 Returns

     FIELDGET() returns the value of the specified field.  If <nField> does
     not correspond to the position of any field in the current database
     file, FIELDGET() returns NIL.

 Description

     FIELDGET() is a database function that retrieves the value of a field
     using its position within the database file structure rather than its
     field name.  Within generic database service functions this allows,
     among other things, the retrieval of field values without use of the
     macro operator.

 Examples

     The following example compares FIELDGET() to functionally equivalent
     code that uses the macro operator to retrieve the value of a field:

     LOCAL nField := 1, FName, FVal
     USE Customer NEW
     //
     // Using macro operator
     FName := FIELD( nField )        // Get field name
     FVal := &FName                  // Get field value

     // Using FIELDGET()
     FVal := FIELDGET( nField )      // Get field value

 Files:  Library is CLIPPER.LIB.
 seealso: "FIELDPUT()"


 FIELDPUT()     Set the value of a field variable
 FIELDPUT()
 Set the value of a field variable using the ordinal position of
 the field in the database structure

 Syntax: FIELDPUT(<nField>, <expAssign>) --> valueAssigned

 Arguments

     <nField> is the ordinal position of the field in the current
     database file.

     <expAssign> is the value to assign to the given field.  The data
     type of this expression must match the data type of the designated
     field variable.

 Returns

     FIELDPUT() returns the value assigned to the designated field.  If
     <nField> does not correspond to the position of any field in the
     current database file, FIELDPUT() returns NIL.

 Description

     FIELDPUT() is a database function that assigns <expAssign> to the field
     at ordinal position <nField> in the current work area.  This function
     allows you to set the value of a field using its position within the
     database file structure rather than its field name.  Within generic
     database service functions this allows, among other things, the setting
     of field values without use of the macro operator.

 Examples

     The following example compares FIELDPUT() to functionally equivalent
     code that uses the macro operator to retrieve the value of a field:

     // Using macro operator
     FName := FIELD(nField)       // Get field name
     FIELD->&FName := FVal        // Set field value

     // Using FIELDPUT()
     FIELDPUT(nField, FVal)       // Set field value

 Files:  Library is CLIPPER.LIB.
 seealso: "FIELDGET()"


 FIELDWBLOCK()  Return a set-get block for a field in a given work area
 FIELDWBLOCK()
 Return a set-get code block for a field in a given work area

 Syntax: FIELDWBLOCK(<cFieldName>, <nWorkArea>) --> bFieldWBlock

 Arguments

     <cFieldName> is the name of the field the set-get block will refer
     to specified as a character string.

     <nWorkArea> is the work area number where the field resides
     specified as a numeric value.

 Returns

     FIELDWBLOCK() returns a code block that when evaluated sets (assigns)
     or gets (retrieves) the value of <cFieldName> in the work area
     designated by <nWorkArea>.  If <cFieldName> does not exist in the
     specified work area, FIELDWBLOCK() returns NIL.

 Description

     FIELDWBLOCK() is a database function that builds a code block.  When
     evaluated with the EVAL() function, the code block first selects the
     designated <nWorkArea>.  If an argument was passed, the code block then
     assigns the value of the argument to <cFieldName>.  If no argument was
     passed, the code block retrieves the value of <cFieldName>.  The
     original work area is then re-selected before the code block returns
     control.

 Notes

       FIELDWBLOCK() is similar to FIELDBLOCK(), the difference
        being that FIELDBLOCK() does not incorporate a fixed work area into
        the set-get block.

 Examples

       The following example compares FIELDWBLOCK() to a code block
        created using the macro operator.  Note that using FIELDWBLOCK()
        allows you to avoid the speed and size overhead of the macro
        operator:

        // Set-Get block for work area 1 defined with macro operator
        bSetGet := &( "{ |setVal| IF( setVal == NIL, ;
           1->FName, 1->FName := setVal ) }" )

        // Set-Get block defined using FIELDWBLOCK()<R>
        // bSetGet created here is the functional equivalent of bSetGet above
        bSetGet := FIELDWBLOCK("FName", 1)

       Another example of FIELDWBLOCK() can be found in TbDemo.prg,
        a sample program included with Clipper 5.0.  The TBColumn object,
        one of which represents each column in a TBrowse object, requires
        among its instance variables a block to retrieve the expression to
        be displayed.  FIELDWBLOCK() is used to create this block.  In the
        default installation, TbDemo.prg is located in the \CLIPPER5\SOURCE
        directory.

 Files:  Library is CLIPPER.LIB.
 seealso: "FIELDBLOCK()" "MEMVARBLOCK()"


 MEMVARBLOCK()  Return a set-get code block for a given memory variable
 MEMVARBLOCK()
 Return a set-get code block for a given memory variable

 Syntax: MEMVARBLOCK(<cMemvarName>) --> bMemvarBlock

 Arguments

     <cMemvarName> is the name of the variable the set-get block will
     refer to specified as a character string.

 Returns

     MEMVARBLOCK() returns a code block that when evaluated sets (assigns)
     or gets (retrieves) the value of the given memory variable.  If
     <cMemvarName> does not exist, MEMVARBLOCK() returns NIL.

 Description

     The code block created by MEMVARBLOCK() has two operations depending on
     whether an argument is passed to the code block when it is evaluated.
     If evaluated with an argument, it assigns the value of the argument to
     <cMemvarName>.  If evaluated without an argument, the code block
     retrieves the value of <cMemvarName>.

 Notes

       MEMVARBLOCK() creates set-get blocks only for variables
       whose names are known at runtime.  MEMVARBLOCK(), therefore, cannot
       be used to create set-get blocks for local or static variables.  The
       same restriction applies to creating blocks using the macro (&)
       operator.

 Examples

     The following example compares MEMVARBLOCK() to a code block created
     using the macro (&) operator.  Note that using MEMVARBLOCK() allows you
     to avoid the speed and size overhead of the macro operator:

     PRIVATE var := "This is a string"
     //
     // Set-Get block defined using macro operator
     bSetGet := &( "{ |setVal| IF( setVal == NIL, var, var := setVal ) }" )

     // Set-Get block defined using MEMVARBLOCK()
     // bSetGet created here is the functional equivalent of bSetGet above
     bSetGet := MEMVARBLOCK("var")

 Files:  Library is CLIPPER.LIB.
 seealso: "FIELDBLOCK()" "FIELDWBLOCK()"