USE Command

Example   See Also

Opens a table and its associated index files, or a SQL view.

Syntax

USE [[DatabaseName!]Table | SQLViewName | ?]
  [IN nWorkArea | cTableAlias]
  [ONLINE]
  [ADMIN]
  [AGAIN]
  [NOREQUERY [nDataSessionNumber]]
  [NODATA]
  [INDEX IndexFileList | ?
  [ORDER [nIndexNumber | IDXFileName
  | [TAG] TagName [OF CDXFileName]
     [ASCENDING | DESCENDING]]]]
  [ALIAS cTableAlias]
  [EXCLUSIVE]
  [SHARED]
  [NOUPDATE]

Arguments

[DatabaseName!]TableName

Specifies the name of the table to open. Because spaces are significant in file names in Microsoft Windows 95 and Windows NT, avoid using extraneous spaces in TableName. If a table name contains spaces, enclose the table name in quotation marks (“ ” or ‘ ’)

To open a table not in the current database, qualify the table name with the database name, using an exclamation point (!) to separate the database and tables names. If you don't qualify a table with a database name, Microsoft Visual FoxPro can open tables only in the current database. If the database name or table name or both contains spaces, enclose the database and table name in quotation marks (“ ” or ‘ ’)

SQLViewName

Specifies the name of a SQL view in the current database to open. A SQL view is created with CREATE SQL VIEW. SQLViewName can also be the name of an offline view created with CREATEOFFLINE( ).

?

Displays the Use dialog, from which you can choose a table to open.

IN nWorkArea

Specifies the work area in which the table is opened. You can close a table in a specific work area by issuing USE with the IN clause and the work area number.

The IN clause supports 0 as a work area. Including 0 opens a table in the lowest available work area. For example, if tables are open in work areas 1 through 10, the following command opens the customer table in work area 11:

USE customer IN 0

IN cTableAlias

Specifies that the table is opened in the work area of a table that is currently open. The alias of the open table is specified with cTableAlias.

If you omit nWorkArea and cTableAlias, the table is opened in the currently selected work area.

ONLINE

Opens an offline view created with CREATEOFFLINE( ). Specify the name of the offline view in SQLViewName. Use TABLEUPDATE( ) to update data on the server.

The offline view must be opened exclusively. Include the EXCLUSIVE clause in USE or SET EXCLUSIVE to ON before opening the offline view with USE.

ADMIN

Opens an offline view created with CREATEOFFLINE( ), but does not update the data on the server with the changes made to the offline view. Opening an offline view with the ADMIN keyword allows you to make changes to the offline view without updating the data on the server.

AGAIN

To open a table concurrently in multiple work areas, you can do one of the following:

• Select another work area and issue USE with the table name and the AGAIN clause.
  
  
• Issue USE with the table name and the AGAIN clause, and specify a different work area with the IN clause.

  When you open a table again in another work area, the table in the new work area takes on the attributes of the table in the original work area. For example, if a table is opened for read-only or exclusive access and is opened again in another work area, the table is opened for read-only or exclusive access in the new work area.

  Index files opened for the original table are available for the table you open again if you don't open indexes when you open the table again. The index order is set to 0 in the work areas where the table is opened again.

  You can open indexes that weren't opened with the original table. This sets the index order to 0 for the original table.

  A table opened again is assigned the default alias of the work area. You can include an alias every time you open a table in multiple work areas as long as the aliases are unique.

  In Visual FoxPro for Windows, opening a table again in another work area doesn't consume an additional file handle.

NOREQUERY [nDataSessionNumber]

Specifies that data from a remote SQL view is not downloaded again. NOREQUERY is available only for SQL views and is typically used when you open a SQL view again by including the AGAIN clause. Including the NOREQUERY clause increases performance for large data sets because the data does not need to be downloaded again.

nDataSessionNumber can be included to specify that data for a remote SQL view in a specific data session isn't downloaded again. If nDataSessionNumber is omitted, data isn't downloaded for the view open in the current data session.

For additional information about the NOREQUERY clause, see Chapter 8, Creating Views, in the Programmer's Guide.

NODATA

Specifies that only the structure of a SQL view is downloaded. The SQL view's data isn't downloaded. NODATA provides the fastest method for determining a SQL view's structure.

For additional information about the NODATA clause, see Chapter 8, Creating Views, in the Programmer's Guide.

INDEX IndexFileList

Specifies a set of indexes to open with the table. If a table has a structural compound index file, the index file is automatically opened with the table.

IndexFileList can contain any combination of names of single-entry .idx and compound .cdx index files. You don't have to include the file name extensions for index files unless an .idx and a .cdx index file in the index file list have the same name.

The first index file named in the index file list is the master controlling index file, which controls how records in the table are accessed and displayed. However, if the first index file is a .cdx compound index file, records in the table are displayed and accessed in physical record order.

INDEX ?

Displays the Open dialog with a list of available index files to choose from.

ORDER [nIndexNumber]

Specifies a master controlling single-entry .idx index file or compound .cdx index file tag other than the first index file or index tag specified in IndexFileList.

.Idx index files are numbered first, in the order in which they appear in the index file list. Tags in the structural compound index file (if one exists) are then numbered in the order in which the tags were created. Finally, tags in any independent compound index files are numbered in the order in which they were created. You can also use SET ORDER to specify the controlling index file or tag. See SET ORDER for a further discussion of the numbering of index files and tags.

If nIndexNumber is 0, records in the table are displayed and accessed in physical record order, and the indexes remain open. Including ORDER 0 enables open index files to be updated while presenting the file in record number order. Including ORDER without nIndexNumber is identical to including ORDER 0.

ORDER [IDXFileName]

Specifies a single-entry .idx index file as the master controlling index file.

ORDER [TAG TagName] [OF CDXFileName]

Specifies a master controlling tag in a compound .cdx index file. The tag name can be from the structural compound index file or any open compound index file. If identical tag names exist in open compound index files, include OF CDXFileName and specify the name of the compound index file containing the desired tag.

ASCENDING

Specifies that the table records are accessed and displayed in ascending order.

DESCENDING

Specifies that the table records are accessed and displayed in descending order.

Including ASCENDING or DESCENDING doesn't change the index file or tag; it alters only the order in which records are displayed and accessed.

ALIAS cTableAlias

Creates an alias for the table. You can refer to a table by its alias in commands and functions that require or support an alias.

When a table is opened, it is automatically assigned an alias, which is the table name if ALIAS isn't included. You can create a different alias for the table by including ALIAS and a new alias. In Visual FoxPro, an alias can contain up to 254 letters, digits or underscores and must begin with a letter or an underscore. In other FoxPro versions, an alias can contain up to 10 letters, digits or underscores and must begin with a letter or an underscore.

A default alias is assigned automatically if you use AGAIN to open a single table simultaneously in multiple work areas and you don't specify an alias when you open the table in each work area.

A default alias is also assigned if a conflict occurs. For example:

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
ACTIVATE WINDOW View  && Open the Data Session Window
USE customer ALIAS orders IN 1     && Alias is ORDERS
USE orders IN 3     && Conflict; alias is C

EXCLUSIVE

Opens a table for exclusive use on a network. For more information on the exclusive use of tables, see SET EXCLUSIVE.

SHARED

Opens a table for shared use on a network. SHARED allows you to open a table for shared use even when EXCLUSIVE is set ON.

NOUPDATE

Prevents changes to the table and its structure.

Remarks

If USE is issued without a table name and a table file is open in the currently selected work area, the table is closed. Also, a table is closed when another table is opened in the same work area. You can't have more than one table open in a work area at one time.