Xbase++ - Command USE

Opens a database file and its accompanying files in a work area.

USE [ <cFileName> ;
      [ INDEX <cIndexFiles,...> ] ;
      [ ALIAS <cAlias> ] ;
      [ VIA   <cDbeName> | (<oSession>) ] ;
      [ NEW ] ;
      [ READONLY ] ;
      [ EXCLUSIVE | SHARED ] ;
    ]

<cFileName> is a literal file name or a character expression in parentheses containing the name of the file to open. <cFileName> can contain drive and/or path information. The default file extension is ".DBF"

<cIndexFiles,...>

Following the option INDEX, a comma separated list can be specified containing the names of the index files to open in conjunction with the database file. The names can be specified as literals or as character expressions in parentheses. The first index file in the list specifies the controlling index. The number of open index files in a work area is limited only by the number of available file handles.

The argument <cAlias> optionally specifies the alias name used to identify the work area. The alias name can be specified as a literal or as a character expression in parentheses. When <cAlias> is not specified, the alias name is created using the file name <cFileName>. Alias names used to identify a work area must be unique.

<cDbeName> optionally specifies the database engine (DBE) used to manage the data in the work area. <cDbeName> can be specified as a literal or as a character expression in parentheses. If <cDbeName> is not specified, the default DBE is used.

(<oSession>)

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

EXCLUSIVE

EXCLUSIVE locks the file after opening against write access by other users on a network. Thus, data in the file cannot be changed from other workstations. Read access is still permitted. If EXCLUSIVE is specified, shared write access is not possible until the file is closed and reopened in SHARED mode.

SHARED

SHARED specifies that multiple access to the file is permitted. This is significant in multi-user applications on a network. The SHARED option has precedence over the setting defined with SET EXCLUSIVE.

NEW

The option NEW optionally specifies whether a new work area is selected before opening the DBF file. When NEW is specified, the file is opened in the next available work area. Otherwise, all files currently open in the work area where the file <cFileName> is being opened are first closed.

READONLY

The option READONLY optionally prohibits write access to the file being opened. When READONLY is specified, only read access is permitted and no data can be written to the file. By default, files are opened with read and write access.

The file command USE opens a database file in a work area and can optionally open specified index files. If the option NEW is used, the next available work area is selected before opening the files. If NEW is missing, all files in the current work area are closed before the new file is opened in the work area.

If no arguments are specified with the command USE, the files in the current work area are closed.

In addition to the database file, the index files which appear in the list after the option INDEX are opened. The first index file in the list determines the controlling index and the record pointer is positioned on the first logical record after the files are opened. In a multi-user application in network operation, index files should not be opened by the command USE, but separately using the command SET INDEX TO. If opening the database file fails in network operation, the index files cannot be opened and runtime errors occur.

Files are 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 function DbUseArea(), used with OrdListAdd(), is the functional equivalent of the command USE.

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

USE

// The example shows different ways to call USE 
// with literal names and character expressions. 

PROCEDURE Main 
   LOCAL cFileName := "INVOICE" 
   LOCAL aIndex    := {"INVA","INVB"} 

   USE Customer INDEX CustA, CustB NEW    // literal file name 

                                          // called with variables 
   USE (cFileName) INDEX (aIndex[1]), (aIndex[2]) NEW 

   CLOSE DATABASES 
RETURN

USE in network operation

// The example shows a how a failed opening of a DBF 
// file in network operation can be caught. A message 
// is displayed and the user makes a decision about 
// whether to retry the operation. The index files are 
// separately opened only if a DBF file is open in 
// the work area. 

PROCEDURE Main 

   DO WHILE .T. 
      USE Customer SHARED NEW 

      IF Neterr() .AND. ; 
         Alert( "File is locked!;Try again?", ; 
                {"Retry","Cancel"} ) <> 2 
         LOOP 
      ENDIF 

      EXIT 
   ENDDO 

   IF Used() 
      SET INDEX TO CustA, CustB, CustC 
   ENDIF 

RETURN

USE with session context

// The example shows how a session object can be used 
// when opening a DBF file. 
// 
PROCEDURE Main 
  LOCAL oSession 

  oSession := DacSession():New("DBE=ADSDBE;SERVER=\\ALASKA01\VOL1") 

  USE "\\ALASKA01\VOL1\Customer" SHARED VIA (oSession) 

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.

Command USE Foundation