xHarbour Reference Documentation > Function Reference

DbUseArea()

Opens a database file in a work area.

Syntax

DbUseArea( [<lNewArea>]  , ;
           [<cRddName>]  , ;
           <cDatabase>   , ;
           [<cAlias>]    , ;
           [<lShared>]   , ;
           [<lReadonly>] , ;
           [<cCodePage>] , ;
           [<nConnection>] ) --> NIL

Arguments

<lNewArea>

If .T. (true) is passed for <lNewArea>, the function selects the next unused work area before the database is opened. The default value is .F. (false), which opens the database in the current work area. If the current work area is used, all files are closed before the new database is opened.

<cRddName>

<cRddName> is an optional character string with the name of the RDD to use for opening the database file. It defaults to the return value of RddSetDefault().

<cDatabase>

This is a character string holding the name of the database file to open. It can include path and file extension. The default file extension is DBF.

<cAlias>

This is the symbolic alias name of the work area as a character string. It defaults to the file name of <cDatabase> without extension.

<lShared>

Specifying .T. (true) for <lShared> opens the database in SHARED mode. The default value depends on the SET EXCLUSIVE setting. If set to ON, <lShared> defaults to .F. (false).

<lReadonly>

Specifying .T. (true) for <lReadonly> opens the database in READONLY mode. The default value is .F. (false) which opens the file for read and write access.

<cCodePage>

This is a character string specifying the code page to use for character strings stored in the database. It defaults to the return value of HB_SetCodePage().

<nConnection>

This parameter specifies a numeric server connection handle. It is returned by a server connection function which establishes a connection to a database server, such as SR_AddConnection() of the xHarbour Builder SQLRDD. When <nConnection> is passed, the function opens a database on the server.

Return

The return value is always NIL.

Description

DbUseArea() opens an existing database file named <cDatabase> in the current work area, or in the next unused work area when <lNewArea> is set to .T. (true). The file is searched in the following directories: first in the current directory, then in the SET DEFAULT directory and finally in all directories specified with SET PATH. If the file cannot be found, a runtime error is raised.

When a database is to be accessed in a network, it should be opened in SHARED mode, since EXCLUSIVE usage of a database file prevents other work stations from accessing the file. Shared database access requires to lock a database before changes can be written to a file. Refer to RLock() and FLock() for information about record and file locks in shared database access.

Info

See also:	CLOSE, DbCloseArea(), NetDbUse(), RddSetDefault(), Select(), SET DEFAULT, SET PATH, Set(), USE
Category:	Database functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example opens a database file using command
// and function syntax.

   REQUEST DBFCDX

   PROCEDURE Main
      USE Customer ALIAS Cust NEW
      ? Alias()                        // result: CUST

      DbUseArea( .T., "DBFCDX" , "Orders", "Ord" )
      ? Alias()                        // result: ORD

      CLOSE ALL
   RETURN