Function DbUseArea() | Xbase++

Opens a database file in a work area.

DbUseArea( [<lNewArea>]        , ;
           [<cDBE>|<oSession>] , ;
            <cFileName>        , ;
           [<cAlias>]          , ;
           [<lShared>]         , ;
           [<lReadonly>]  )  --> NIL

<lNewArea> is a logical value specifying whether a new work area is selected before the database file is opened. Including <lNewArea> is optional and the default value is .F. (false). If <lNewArea> contains the value .T. (true), a file is opened in a free work area. Otherwise, all open files in the work area where the file <cFileName> will be opened are first closed.

<cDBE>

<cDBE> optionally specifies the data base engine (DBE) used to manage the files in the desired work area. It is a character string containing the name of the DBE. If <cDBE> is not specified, the DBE defined as the default with DbeSetDefault()is used.

<oSession> optionally specifies the Session context for the operation. oSession is an object of DacSession() or any derived class. If oSession is not specified the current session of the current thread is used.

<cFileName> is a character string containing the name of the file to open. <cFileName> can contain drive and/or path information. The default extension is predetermined by the database engine (DBE) used to open the file. The default file extension of the DBFDBE is ".DBF".

The argument <cAlias> specifies the alias name used to identify the work area. It is an optional character value. When <cAlias> is not specified the alias name is created from the file name <cFileName>. Each individual alias name may be in use for only one work area.

<lShared> is an optional value specifying whether concurrent access to the file is allowed. It is a logical value which is significant in multi-user applications. If <lShared> contains the value .T. (true), the file is opened in the SHARED mode permitting concurrent access. If <lShared> is missing, the setting SET EXCLUSIVE ON | OFF is used as the default value.

<lReadonly> is an optional logical value specifying the write access to the file being opened. When <lReadonly> contains the value .T. (true), only read access is allowed and no data can be written into the file. The default value is .F. (false), meaning that the file is opened with read and write privileges.

The return value of DbUseArea() is always NIL.

The database function DbUseArea() opens a database file in a work area and selects the area as the current work area. If <lNewArea>contains the value .T. (true), DbUseArea() selects a free work area before opening the file. If <lNewArea> is not specified, all files in the current work area are closed before the new file is opened in the work area.

The file is searched in the following directories: 1st) the DEFAULT directory; 2nd) if this is not defined, the current directory; 3rd) the directories defined with the PATH setting.

The command USE can be used instead of DbUseArea().

Open a database several times

It is possible to open the same database file in different work areas. In this case each work area maintains its own record pointer and record locks must be set when writing data to a database field. If a database is opened more than once without specifying <cAlias>Xbase++ automatically creates a unique alias name. It is build from the file name followed by an underscore and the number of the selected work area ( <cFileName> + "_" + LTrim(Str(Select())) ).

Comparison between USE and DbUseArea()

// The example shows how to open a database file using both 
// the command and function syntax. 

PROCEDURE Main 

   USE Invoice ALIAS Inv NEW 

   ? Alias()                 // result: INV 

   DbUseArea(.T., , "Customer", "Cust" ) 

   ? Alias()                 // result: CUST 

   CLOSE DATABASES 
RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function DbUseArea() Foundation