| Note | This command is defined in a header file and will be preprocessed by the X# preprocessor to a function call. If you disable the standard header (-nostddefs) files then this command will not be available. If you tell the compiler to use a different standard header file (-stddef ) then this command may also be not available |
Purpose
Open an existing database file, its associated memo file, and optionally associated index files in the current or the next available work area.
Syntax
USE [<xcDataFile> [INDEX <xcIndexList>] [ALIAS <xcAlias>] [FIELDS <aFields>] [NEW] [READONLY]
[EXCLUSIVE | SHARED] [VIA <cDriver>] [INHERIT <acRDDs>]]
Arguments
| <xcDataFile> | The name of the database file to open, including an optional drive, directory, and extension. If the database file has a corresponding memo file, it is also opened. The default extension for database and memo files is determined by the RDD. |
| INDEX <xcIndexFileList> |
| The names of the index files to open, including an optional drive, directory, and extension for each. The default extension is determined by the RDD and can be obtained using DBOrderInfo(DBOI_INDEXEXT). |
| If you specify <xcIndexList> as an expression and the value returned is spaces or NIL, it is ignored. |
| It is recommended that you open index files with SET INDEX or DBSetIndex() for proper resolution in case of a concurrency conflict. |
| If the database file, its corresponding memo file, or any of the index files does not exist, a runtime error is raised. See SetDefault() and SetPath() for file searching and creation rules. |
| ALIAS <xcAlias> | An identifier name to associate with the work area when <xcDataFile> is opened. If not specified, the alias defaults to the database file name. Duplicate alias names are not allowed within a single application. |
| FIELDS <aFields> | An array containing field descriptions in the format returned by DBStruct(). |
| This argument does not apply to DBF files. It is intended for use with file formats that do not store field descriptions. For example, if you use an RDD that supports SDF or delimited files, you can use this argument to define the file structure, which can then be used with other commands or functions to access the field descriptions. Here is an example of this argument: |
aFields := {;
{"First", "C", 35, 0};
{"Last", "C", 35, 0};
{"Birthday", "D", 8, 0}}
USE Names FIELDS aFields VIA "DELIM"
? First // Return: Josie
| NEW | Selects the next available work area before opening <xcDataFile>. If not specified, <xcDataFile> is opened in the current work area. |
| READONLY | Attempts to open <xcDataFile> with a read-only attribute, prohibiting updates to the work area. If not specified, <xcDataFile> is opened read-write, allowing updates. If <xcDataFile> cannot be accessed using the indicated attribute, a runtime error is raised. |
| EXCLUSIVE | Attempts to open <xcDataFile> for exclusive (non-shared) use. All other processes are denied access until the database file is closed. |
| SHARED | Attempts to open <xcDataFile> for shared use. |
| If neither SHARED nor EXCLUSIVE is specified, the USE command attempts to open <xcDataFile> in the mode indicated by the SetExclusive() flag. However, it is highly recommended that you specify the open mode as part of the USE command rather than relying on SetExclusive() to determine it for you. |
| VIA <cDriver> | The name of the RDD that will service the work area. If not specified, the default RDD as determined by RDDSetDefault() is used. |
| INHERIT <acRDDs> | A one-dimensional array with the names of RDDs from which the main RDD inherits special functionality. This allows you to use RDDs with special capabilities, like encryption or decryption, in different work areas with different database drivers. These RDDs overlay special functions of the main RDD (specified with the VIA clause). If multiple RDDs (specified with this INHERIT clause) implement the same function, the function associated with the last RDD in the list takes precedence. |
| USE specified with no arguments closes the database file open in the current work area. |
Description
The USE command attempts to open <xcDataFile> (and its associated .DBF file, if any) in the indicated mode. If the file is successfully opened, the operation proceeds to open any indicated index files in the same mode — any files that were already open in the work area are closed. The first order in the first index file in the list becomes the controlling order.
If access is denied because, for example, another process has exclusive use of the database file, NetErr() is set to TRUE but no runtime error is raised. For this reason, it is recommended that you open index files as a separate operation (with SET INDEX or DBSetIndex()). Otherwise, a runtime error will result when the USE command tries to open the first index file in the list because the database file will not be open.
When a database file is first opened, the record pointer is positioned at the first logical record in the file (record one if there is no controlling order).
If the database file is opened in shared mode, other processes can have concurrent access to the file and responsibility for data integrity falls on the application program. File and record locking (using, FLock(), RLock(), or DBRLock()) are the basic means of denying other processes access to a particular file or record.
Refer to the CLOSE command for information on how to close files of all types.
USE is functionally equivalent to DBUseArea().
Examples
This example opens a shared database file with associated index files. If NetErr() returns FALSE, indicating the USE was successful, the indexes are opened:
USE accounts SHARED NEW
IF !NetErr()
SET INDEX TO acctnames, acctzip
ELSE
? "File open failed"
BREAK
ENDIF
This example opens a database file with several index files specified as extended expressions:
cDataFile = "MyDbf"
acIndex = {"MyIndex1", "MyIndex2", "MyIndex3"}
USE (cDataFile) INDEX (acIndex[1]), ;
(acIndex[2]), (acIndex[3])
Assembly
XSharp.RT.DLL
See Also
CLOSE, DbSelect(), DbSetIndex(), DbSetOrder(), DbUseArea(), NetErr(), RddSetDefault() SELECT, SET INDEX, Used()
