Command USE Foundation
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 ] ;
]
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())) ).
// 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
// 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
// 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.