xHarbour Reference Documentation > Command Reference

USE

Opens a database and its associated files in a work area.

Syntax

       USE [<cDatabase> ;
     [INDEX <cIndexFiles,...>] ;
     [ALIAS <cAlias>] ;
            [EXCLUSIVE | SHARED] ;
            [NEW] ;
            [READONLY] ;
       [VIA <cRDD>] ;
  [CODEPAGE <cCodePage>] ;
[CONNECTION <nConnection>]]

Arguments

<cDatabase>

This is name of the database file to open. It can include path and file extension. The default file extension is DBF. <cDatabase> can be specified as a literal file name or as a character expression enclosed in parentheses.

If no argument is specified, all files open in the current work area are closed.

INDEX <cIndexFiles,...>

The names of the index files to open along with the database can be specified as a comma separated list of literal file names or character expressions enclosed in parentheses. When this option is omitted, the datbase is opened without indexes.

ALIAS <cAlias>

This is the symbolic alias name of the work area. It can be specified as a literal alias name or a character expression enclosed in parentheses. It defaults to the file name of <cDatabase> without extension.

EXCLUSIVE

This option opens the database file for exclusive access. All other users in a network environment cannot access the database until the file is closed.

SHARED

This option opens the database file for shared use in a network environment.

NEW

NEW selects the next free work area and then opens the database. Without the option, all files open in the current work area are closed before <cDatabase> is opened in the current work area.

READONLY

This option is required if the file <cDatabase> is marked as read-only in the file system.

VIA <cRDD>

The option specifies the replaceable database driver (RDD) to use for maintaining the database and its associated files. It defaults to RddSetDefault() and must be a character expression.

CODEPAGE <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().

CONNECTION <nConnection>

This option 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 CONNECTION is used, the USE command opens a database on the server.

Description

The USE command opens a database file along with its associated memo files in the current work area. Optionally, index files belonging to the database can be opened as well. Only one database can be open at any time in one work area. The maximum number of work areas is 65535.

USE operates in the current work area, which can be selected using the SELECT command. As an alternative, the NEW option of USE selects the next free work area as current and then opens the file. When the database is open, its record pointer is positioned on the first logical record, if indexes are opened, or on record number 1.

Index files can be opened along with the database using the INDEX option. It is, however, recommended to open first the database file alone, check the success of file opening with NetErr() and then open associated index files in a separate operation using SET INDEX.

File access to the database in a multi-user environment is controlled with the options SHARED and EXCLUSIVE. Shared file access requires record locking for updating records during database operations. This is accomplished with function RLock().

Info

See also:	CLOSE, DbSetIndex(), DbUseArea(), NetErr(), OrdListAdd(), RddSetDefault(), SELECT, SET DEFAULT, SET INDEX, SET PATH, Used()
Category:	Database commands
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates the recommended procedure of opening a databse
// and its indexes in a multi-user environment:

   PROCEDURE Main
      USE Customer SHARED NEW

      IF .NOT. NetErr()
         SET INDEX TO Cust01, Cust02, Cust03
      ELSE
         ? "Unable to open database"
         BREAK
      ENDIF

      <database operations>

      CLOSE ALL
   RETURN