Click above to get retro games delivered to your door ever month!

 V_USE()
 Open/Create a Variable Length Field file (DBV)
-------------------------------------------------------------------------------

 Syntax

    V_USE(   [<cFileName>],
             [<cAlias>],
             [<cNewArea>],
             [<lExclusive>] )   ->    nArea

 Arguments

    <cFileName> is the name of the file to be opened/created. A .DBV
    extension is assumed if none is provided. If the file does not
    exist, one will be created. If <cFileName> is omitted, any file
    open in the current DBV area will be closed.

    <cAlias> is a name to be associated with the DBV work area of the
    file being opened. If this parameter is not passed or a "dummy"
    argument is passed, the alias defaults to the DBV file name.

    <cNewArea> is the word "NEW". This has the same affect as issuing
    a SELECT 0 in Clipper or V_SELECT(0) in FlexFile just before
    opening the file. In Clipper version 5.0, <cNewArea> has the same
    effect as the NEW modifier of the USE command. If this parameter
    is not specified, any DBV file open in the current DBV work area
    will be closed and the <cFileName> file will be opened in its
    place.

    <lExclusive> is a logical expression determining the accessibility
    of the file by other users in a network environment.  If
    <lExclusive> is (.T.) and the file is successfully opened, any
    attempt by another user to V_USE() the <cFileName> file will be
    denied until the file is V_CLOSED(). If this parameter is omitted,
    FlexFile will attempt to open the <cFileName> file according to
    the current setting of V_EXCLUSIV().

 Returns

    If successful, V_USE() returns the DBV area in which the file was
    opened. Otherwise, it will return a -1 and set an error code which
    may be fetched with V_ERROR(). (See appendix B for a list of error
    codes.)

 Description

    V_USE() opens (or creates if the file does not exist) a file that
    can store variable length data. Any file which is already open in
    the DBV area is closed before the <cFileName> file is opened.

    Although it is far more flexible, using a DBV file is very similar
    to using memo-fields and a DBT file. It is not required but highly
    recommended that you have a DBF file open simultaneously with the
    DBV file. You will then store pointers in fields of the DBF file
    that point to variable length data in the DBV file. The fields in
    the DBF file cannot be defined as a <memo> fields but have the
    same basic functionality.

    Unlike the DBT file, FlexFile supports one to one, one to many,
    and many to many relationships between the DBF field pointers and
    the DBV files. For example, a system could use one DBV file to
    store all its help text, random memo's, screens and arrays. The
    pointers to all this data could be stored in several different DBF
    files. Likewise, one DBF file may point into several DBV files. It
    is left up to the programmer to keep straight which DBF fields
    relate to which DBV files.  (Note: it is a critical error to use a
    pointer which points into one DBV file as a pointer into a
    different DBV file.)

    If a DBV file is opened exclusively in a network environment, no
    other users may access the file until it is V_CLOSED().  Likewise,
    if the file is currently being used exclusively by another user,
    attempts to V_USE() that file will fail.  V_USE() returns -1 if
    the file is not opened and reports the error which can be fetched
    with V_ERROR().  (See appendix B for a list of error codes.)

    If the file is opened non-exclusively, other users may access the
    variable length data simultaneously. However, because all data in
    a DBV file must be accessed by a pointer which will usually be
    stored in a DBF file, using standard Clipper locking procedures to
    protect the DBF record will protect the variable length data
    exactly as it does any field in the DBF. (See the V_REPLACE()
    function for more on locking.)

 Notes

  . V_USE() obeys neither the SET DEFAULT nor the SET PATH
    settings. Instead, it will use the current DOS default directory
    or any valid path specified as a part of <cFileName>.

  . Remember that your maximum number of open files must be set by
    the V_FILES() function before V_USE()ing your first DBV file. The
    valid DBV areas will then be from 1 to the value you passed to
    V_FILES(). See V_FILES() for more on defining the active number of
    files.

  . Opening the same DBV file in two work areas simultaneously is
    possible, however, don't do it.

  . Do not confuse Clipper's selected work area with FlexFile's;
    they are mutually exclusive. For example, you can have a DBF file
    open in area 2 and simultaneously have a DBV file open in
    V_SELECT() == 2. Likewise, Clipper's SELECT <n> has no effect on
    the currently selected DBV area.

 Examples

    // Assume that no files are open at this point.
    // Set the maximum number of files to three.
    #define EXCLUSIVE_ (.T.)
    V_FILES( 3 )

    // Open a DBV file with an alias of "MAIN_FILE" in area 1.
    // If dbv_file.dbv does not exist it will be created.
    V_SELECT(1)
    V_USE( "dbv_file", "MAIN_FILE" )
    ? V_ALIAS()           // Result: MAIN_FILE

    // Open another file in the next available area.
    V_USE( "second", , "NEW" )
    ? V_SELECT()          // Result: 2

    // Open a third file for use on a network and test to
    // make certain that the file was properly opened.
    IF V_USE( "F:\GEN\JUNK\third", , "new", !EXCLUSIVE_ ) == -1
       ? "Error: " + str( V_ERROR(), 4 )
       QUIT
    ENDIF

    // Close all files.
    V_CLOSE( 1 )          // Closes file in area 1
    V_CLOSEALL()          // Closes the other two files.