V_TOPPTR()
 Read/Replace FlexFile pointer in a DBV header.
-------------------------------------------------------------------------------

 Syntax

    V_TOPPTR( [<cPointer>], [<cAlias> | <nArea>] )  ->  cOldPointer

 Arguments

    <cPointer>  (optional) is the six byte character string returned by
    either V_REPLACE() or V_AREPLACE().  If not specified, V_TOPPTR() will
    return the current pointer stored in the header of the DBV file (see
    discussion below).

    <nArea> or <cAlias> refers to the number or name of the target
    DBV work area specified with V_USE() or V_SELECT(). If not specified,
    the current DBV work area is assumed.

 Description

    V_TOPPTR() is a special function which allows the storage of one (and
    only one) Variable Length Field without having a separate DBF file in
    which to keep the pointer to that field.

    Usually, you replace a six byte character field (FlexFile's version of
    a memo-field) in a DBF file with a pointer to data which is stored in a
    DBV file.  V_TOPPTR() allows you to store one pointer in the header of
    the DBV file.  This pointer can then be accessed by calling V_TOPPTR()
    with no parameters.  For example,

         V_ARETRIEVE( V_TOPPTR() )

    would retrieve an array which was previously stored with V_AREPLACE()
    and whose pointer was stored by V_TOPPTR().

    A good example of the use of this function is in storing parameters
    that your application requires at startup:  Things like colors, default
    paths, printer definitions, etc.

    Many routines have been written to handle this kind of data.  MEM files
    are used by some, while others use a large DBF field and parse out the
    various data into variables.  The fact is that MEM files are not
    "network ready" and the DBF file is not efficient to handle data that
    is not repetitive in size and type. So an easy solution is to keep an
    array of these items in a DBV file and point to that array with
    V_TOPPTR().

    Using V_TOPPTR() requires a slightly different syntax than a standard
    replace.  Typically, a DBV replace is made by calling V_AREPLACE() and
    putting the return pointer in a DBF field as follows:

         REPLACE vlf WITH V_AREPLACE( aStartUp, vlf )

    where aStartUp is an array holding your applications startup data.  In
    contrast, the following syntax is required when storing the
    pointer-field directly in the DBV:

         V_TOPPTR( V_AREPLACE( aStartUp, V_TOPPTR() ) )

    The logic here can best be seen by breaking this last line into several
    lines of code:

         // First, get the old pointer stored in the DBV file.
         cOldPointer = V_TOPPTR()

         // Then replace the old array with a new one.  Put
         // the pointer to the new array into the variable
         // cNewPointer.
         cNewPointer = V_AREPLACE( aStartUp, cOldPointer )

         // Finally, store the actual pointer in the DBV.
         // This will overwrite the old pointer stored there.
         V_TOPPTR( cNewPointer )

 Examples

    LOCAL ray

    // Open only a DBV file
    V_USE( "dbv_file" )  // Is created if it does not exist.

    // Declare an array and put some junk into it.
    ray = { { "one", "two", "three" }     ,;
            { 1, 2, 3 )                   ,;
            { p1, p2, p3 }                 }

    // Store the array in DBV file and its pointer in
    // the header of the same DBV.
    V_TOPPTR( V_AREPLACE( ray, V_TOPPTR() ) )