V_AREPLACE() / V_AREP()
 Replace a VLF with a Clipper 5.0 type array
-------------------------------------------------------------------------------

         Use V_REPLACE() with S'87 arrays

 Syntax

    V_AREPLACE(   <aTarget>,
                  <cOldPointer>,
                  [<cAlias> | <nArea>] )   ->   cNewPointer

 Arguments

    <aTarget> is any valid Clipper 5.0 array.  The array may
    contain nested arrays (i.e. multi-dimensional) which will be saved
    as well.

    <cOldPointer> is a required six byte pointer-field or variable in
    which you have previously stored a pointer to variable length
    data. Passing six spaces causes FlexFile to assume that there is
    no old data to be released before the new <aTarget> data is saved.
    Refer to the discussion below for further explanation.

    <cAlias> or <nArea> is a DBV file alias or area specified with
    V_USE() or V_SELECT(). If omitted, the replace will occur in the
    current DBV area.

 Returns

    V_AREPLACE() returns a pointer which should be stored in the
    pointer-field with which the array is to be associated.

    V_AREPLACE() returns (.F.) on error.  This causes the error system
    to be invoked with a "Data Type Mismatch".  Use V_ERROR() to fetch
    the specific error value (see Appendix B for a table of error
    descriptions).

 Description

    V_AREPLACE() can be used with the Clipper 5.0 compiler only.
    V_AREPLACE() stores the array defined by <aTarget> and returns a
    six byte pointer <cNewPointer>. This pointer is the only way
    FlexFile will ever be able to access the <aTarget> data; if this
    pointer is lost the array in the DBV file will be inaccessible.

    It is highly recommended, therefore, that the V_AREPLACE() function
    be imbedded in the same line of code as the Clipper REPLACE
    command (see examples below). <cNewPointer> will then be stored
    directly into a six byte pointer-field in the related DBF file.

    V_AREPLACE() first deletes the data associated with <cOldPointer>
    freeing up the space, if any, that it was occupying. V_AREPLACE()
    then looks for the smallest available space to put the
    <aTarget> array. Finally, it returns <cNewPointer> to be
    used at any time by V_ARETRIEV() or V_AREPLACE(). In most cases,
    you will be storing the <cNewPointer> in a DBF file (highly
    recommended).

    In designing the associated DBF structure, you will define a
    pseudo memo-field which will be a six byte (or more) character
    type field. FlexFile refers to these fields as pointer-fields.
    When a FlexFile pointer is stored in this field, the field will
    have six bytes of ASCII characters from the "irrational" range
    (128-255). This may appear as "garbage", but is actually a very
    compact encoded structure. It is encoded only to insure that nulls
    are never stored in your DBF file. After creating this field you
    can ignore it exactly as you would a DBT memo-field.

    The V_AREPLACE() function replaces data in the current DBV area or
    the <nArea>/<cAlias> area if specified. Attempting to use
    <cOldPointer> which points into one DBV file to delete/replace
    data in any other DBV file can be dangerous. Although there is a
    degree of protection against this kind of programmer error, it is
    possible that random data will be deleted from the target area
    corrupting that file.

    +-------------------------- WARNING --------------------------+ 
    | V_AREPLACE() deletes the data associated with <cOldPointer> | 
    | before returning <cNewPointer>.  Attempting to use          | 
    | <cOldPointer> after this function deletes the data that it  | 
    | points to can corrupt the DBV file.                         | 
    +-------------------------------------------------------------+ 

 Examples

    LOCAL ray

    // Open the DBF file and its associated DBV file
    USE dbf_file         // Has a 6 byte pointer-field: vlf.
    V_USE( "dbv_file" )  // Is created if it does not exist.

    ray = array( 20 )    // Declare a Clipper 5.0 array

    afill( ray, "junk" ) // Fill the array with some junk.

    ray[10] = array(25)  // Nest an array within the first array

    // Put some variable type data in the nested array
    ray[10][1] = 1
    ray[10][2] = .t.
    ray[10][3] = 5.56
    ray[10][4] = date()
    ray[10][8] = "check it out"

    // Store the array in DBV file and its pointer in
    // the DBF.
    APPEND BLANK
    REPLACE vlf WITH V_AREPLACE( ray, vlf )