action query <definition>
action query

A query that moves or changes data.  Action queries include append, delete, make-table, and update queries.  Delete and update queries change existing data; append and make-table queries move existing data.  In contrast, select queries return data records.  A SQL pass-through query may also be an action query.


action QueryDef <definition>
action QueryDef

A data access object that contains the definition of an action query.  An action QueryDef object is used only with the Execute method, and it defines, moves or changes data instead of returning rows.


aggregate function <definition>
aggregate function

A function, such as Count, Avg, and Var, used in creating a query that calculates totals.  In writing expressions and in programming, you can use SQL aggregate functions (including the three listed above) and domain aggregate functions to determine various statistics.


alias <definition>
alias

In Visual Basic, an alternate name you give to an external procedure to avoid conflict with a Visual Basic keyword, global variable, constant, or a name not allowed by the standard naming conventions.

In SQL, an alternate name you give to a field or expression in a SELECT statement (Using the AS clause), to make it shorter or more meaningful or to prevent name conflicts when performing SQL queries using expressions that don't return names or in a query that uses a self-join.


ANSI Character Set <definition>
ANSI Character Set

American National Standards Institute (ANSI) 8-bit character set used by Microsoft Windows that allows you to represent up to 256 characters (0 [image] 255) using your keyboard.  The first 128 characters (0 [image] 127) correspond to the letters and symbols on a standard U.S. keyboard.  The second 128 characters (128 [image] 255) represent special characters, such as letters in international alphabets, accents, currency symbols, and fractions.


append query <definition>
append query

An action query that adds new records to the end of an existing table or query.  Append queries don't return records (rows).


argument <definition>
argument

A constant, variable, or expression passed to a procedure.


ASCII Character Set <definition>
ASCII Character Set

American Standard Code for Information Interchange (ASCII) 7-bit character set widely used to represent letters and symbols found on a standard U.S. keyboard.  The ASCII character set is the same as the first 128 characters (0 [image] 127) in the ANSI character set.


asterisk <definition>
asterisk

A character (*) used as a wildcard in SQL LIKE expressions to accept any string of characters.  For example, the expression LIKE "*town*" accepts any name containing the string "town."

When you create a query or enter an SQL statement, use the asterisk to include all the fields that currently exist in the underlying table or query.  For example, SELECT * FROM MyTable returns all fields (columns) from the table.


attached table <definition>
attached table

A table in another database linked to a Microsoft Jet database.  Data for attached tables remains in the external database where it may be manipulated by other applications.  You cant use the table-type Recordset object with attached tables.  SQL Passthrough queries cant be executed against attached tables.


base table <definition>
base table

A table in a Microsoft Jet database.  You can manipulate the structure of a base table using the data access objects or data definition SQL statements, and you can modify data in a base table using Recordset objects or action queries.


bookmark <definition>
bookmark

A system-generated string identifying the current record that is contained in a Recordset object's Bookmark property.  If you assign the Bookmark property value to a variable and then move to another record, you can make the earlier record current again by assigning the value of the string variable to the Bookmark property.  Bookmarks can be shared between cloned Recordset objects.


Boolean  data type<definition>
KBoolean data type

A True/False or yes/no value.  Boolean values are usually stored in Bit fields in a Microsoft Jet database; however, some databases don't support this data type directly.


Boolean expression <definition>
Boolean expression

An expression that evaluates to either True or False.


bound control <definition>
bound control

A data-aware control that can provide access to a specific field in a database through a Data control.  A data-aware control can be bound to a Data control through its DataSource and DataField properties.  When a Data control moves from one record to the next, all bound controls connected to the Data control change to display data from fields in the current record.  When users change data in a bound control and then move to a different record, the changes are automatically saved in the database.


Byte data type <definition>
Byte data type

A fundamental data type used to hold small positive integer numbers ranging from 0 to 255.


Cartesian product <definition>
Cartesian product

The result of joining two relational tables, producing all possible ordered combinations of rows from the first table with all rows from the second table.

Generally, a cartesian product results from executing a SQL SELECT statement referencing two or more tables in the FROM clause and not including a WHERE or JOIN clause that indicates how the tables are to be joined.


cascade delete <definition>
cascade delete

For relationships that enforce referential integrity between tables, an option that causes the deletion of a record from the primary table to automatically delete all related records in the related foreign table or tables.

For example, suppose you establish a relationship between a Customers (Primary) table and an Orders (Foreign) table with the cascade delete option enabled.  When a record in the Customers table is deleted, all orders associated with that customer would be also be deleted in the Foreign Orders table.


cascade update <definition>
cascade update

For relationships enforcing referential integrity between tables, an option that causes a change to the primary key in a record in the Primary table to automatically update the foreign key in all related records in the related Foreign table or tables.

For example, suppose you establish a relationship between a Customers (Primary) table and an Orders (Foreign) table with the cascade update option enabled.  When the primary key in a record in the Customers table is changed, all orders associated with that customer would be also be changed in the Foreign Orders table.


cascade <definition>
cascade

The process of  one action triggering another action.  For example, when a cascading update relationship is defined for two (or more) tables, an update to the primary key in the primary table automatically triggers (cascades) changes to the foreign table.


case-sensitive <definition>
case-sensitive

Capable of distinguishing between uppercase and lowercase letters.  A case-sensitive search finds only text that is an exact match of uppercase and lowercase letters.  Such a search would, for instance, treat ZeroLengthStr and zerolengthstr as different.  Microsoft Jet database operations are not case-sensitive.  However, case sensitivity is a feature of some other database management systems.


class <definition>
class

The formal definition of an object.  The class acts as the template from which an instance of an object is created at run time.  The class defines the properties of the object and the methods used to control the object's behavior.


class module <definition>
class module

A module containing the definition of a class (its property and method definitions).


collection <definition>
collection

An object that contains a set of related objects.  An object's position in the collection can change whenever a change occurs in the collection; therefore, the position of any specific object in the collection may vary.


column <definition>
column

In a relational database, a column is synonymous with a field in a nonrelational database.  A column defines the data type, size and other attributes of one field of a row (record) of data.  All columns taken as a set define a row (record) in the database.  An individual column contains data related in type and purpose throughout the table; that is, a column's definition doesnt change from row to row.


commit <definition>
commit

To accept a pending transaction.  If you use transaction processing and begin a transaction using data access, none of the changes made in the transaction are written to the database until you commit or accept the transaction.


compile error <definition>
compile error

An error that occurs during compile time as the result of incorrectly constructed code.


consistent <definition>
consistent

The state of a multiple-table Recordset object that allows you to only perform updates that result in a consistent view of the data.  For example, in a Recordset that is a join of two or more tables (a one-to-many relationship), a consistent query would not allow you to set the many-side key to a value that isnt in the one-side table.


control <definition>
control

An object you can place on a form that has its own set of recognized properties and events.  You use controls to receive user input, display output, and trigger event procedures.  You can manipulate most controls using methods.  Some controls are interactive (responsive to user actions), while others are static (accessible only through code).


copy buffer <definition>
copy buffer

A location created by the Microsoft Jet database engine for the contents of a record that is open for editing.  The Edit method copies the current record to the copy buffer; the AddNew method clears the buffer for a new record and sets the default values; and the Update method saves the data from the copy buffer to the database, replacing the current record or inserting the new record.  Any statement that resets or moves the current record pointer discards the copy buffer.  For example, using the MoveNext method or changing the Index property of a table would discard the contents of the copy buffer.


connect string <definition>
connect string

A string used to define the source of data for an external database.  The connect string is usually assigned to the Connect property of a QueryDef object or Data control or as an argument to the OpenDatabase method.


Counter data type<definition>
Counter data type

A Long data type field in a table where the field Attribute property has the dbAutoIncrement option bit set.  A  counter field is automatically incremented by 1 when a new record is added to the table.  Counter fields are not intended to be updated by the user.


counter field <definition>
counter field

A field that assigns the next consecutive number for each successive record added in the same field.  A counter field always uses the Long data type.


criteria <definition>
criteria

A set of limiting conditions, such as = "Denmark" (meaning equal to Denmark) or > 30000, used in creating a query or filter to show a specific set of records.


crosstab query <definition>
crosstab query

A query that returns data in a spreadsheet type format using fields you specify as row and column headings, and that can return summary data.


Currency data type <definition>
Currency data type

A data type that is useful for calculations involving money or for fixed-point calculations in which accuracy is extremely important.  This data type is used to store numbers with up to 11 digits to the left of the decimal point and 4 digits to the right.  The type-declaration character in Visual Basic is @.  The Currency data type uses discrete values for all amounts so binary round-off isnt a factor when calculating totals.


current database <definition>
current database

The Database object returned by the CurrentDB( ) function.  A reference of DBEngine.Workspaces(0).Databases(0) returns the first database opened.  Not all Microsoft Jet database engine clients support the concept of a "current" database.  This concept isnt supported in Visual Basic version 4.0.


current index <definition>
current index

For an indexed table-type Recordset object, the index most recently set with the Index property.  This index is the basis for ordering records in a table-type Recordset, and is used by the Seek method to locate records.  A Recordset object can have more than one index but can use only one index at a time (although a TableDef object may have several indexes defined on it).  The Microsoft Jet database engine may use more than one index to evaluate a query.


current record <definition>
current record

The record in a Recordset object that you can use to modify or examine data.  Use the Move methods to reposition the current record in a recordset.  Use the Find methods (with a dynaset- or snapshot-type Recordset object) or the Seek method (with a table-type Recordset object) to change the current record position according to specific criteria.

Only one record in a Recordset can be the current record; however, a Recordset may have no current record.  For example, after a dynaset-type Recordset record has been deleted, or when a Recordset has no records, the current record is undefined.  In this case, operations that refer to the current record result in a trappable error.


current transaction <definition>
current transaction

All changes made to a Recordset object after you use the last BeginTrans method and before you use the Rollback or CommitTrans method.


data access object <definition>
data access object

An object that is defined by the Microsoft Jet database engine.  You use data access objects, such as the Database, TableDef, Recordset and QueryDef objects, to represent objects that are used to organize and manipulate data in code.


data-definition query <definition>
data-definition query

An SQL-specific query that can create, alter, or delete a table, or create or delete an index in a database.


data page <definition>
data page

A portion of the database file in which record data is stored.  Depending on the size of the records, a data page may contain more than one record.  A data page in a Microsoft Jet database is 2K bytes.


data source <definition>
data source

A named Open DataBase Connectivity (ODBC) resource that specifies the location, driver type and other parameters needed by an ODBC driver to access an ODBC database.  A data source can be any source of database information.


data type (Data Access) <definition>
data type (Data Access)

The attribute of a variable or field that determines what kind of data it can hold.  For example a Field defined with the Text data type is designed to contain text.


database <definition>
database

A set of data related to a particular topic or purpose.  A database contains tables and can also contain queries and indexes as well as table relationships, table and field validation criteria and linkages to external data sources.


database administration <definition>
database administration

Activities required to preserve the integrity and security of a database, such as maintaining user permissions and backing up, compacting, and repairing the database.


database engine <definition>
database engine

That part of the database system that retrieves data from and stores data in user and system databases.


database management system (DBMS) <definition>
database management system (DBMS)

Software used to organize, analyze, and modify information stored in a database.  For example, the Microsoft SQL Server and the Microsoft Jet database engine are examples of database management systems.


database objects <definition>
database objects

The database objects are Recordset, Field, Index, QueryDef, TableDef, Relation, User, Group, Property and Document.


Database object <definition>
Database object

A Database object is a logical representation of a physical database.  A database is a set of data related to a specific topic or purpose.  A database contains tables and can also contain queries and indexes as well as table relationships, table and field validation criteria and linkages to external data sources.


date literal <definition>
date literal

Any sequence of characters with a valid format that is surrounded by number signs (#).  Valid formats include the date format specified by the locale settings for your code or the universal date format.

For example, #12/31/92# is the date literal that represents December 31, 1992 where English-U.S. is the locale setting for your application.  Use date literals to maximize portability across national languages.


dates and times <definition>
dates and times

Dates and times are stored internally as different parts of a real number.

The value to the left of the decimal represents a date between January 1, 100 and December 31, 9999, inclusive.  Negative values represent dates prior to December 30, 1899.

The value to the right of the decimal represents a time between 0:00:00 and 23:59:59, inclusive.  Midday is represented by .5.


DDL (Data Definition Language) <definition>
DDL (Data Definition Language)

The language used to describe attributes of a database, especially tables, fields, indexes and storage strategy.


default workspace <definition>
default workspace

The Workspace object that Visual Basic automatically establishes when your application first references any data access object.  This Workspace is referenced by DBEngine.Workspaces(0) or simply Workspaces(0).


delete query <definition>
delete query

An action query that deletes a set of rows that match the criteria you specify.  A delete query doesnt return rows.


design time <definition>
design time

The time during which you build an application in the development environment by adding controls, setting control or form properties, and so on.  In contrast, during run time, you interact with the application as a user would.


Double data type <definition>
Double data type

A fundamental data type that holds double-precision floating-point numbers in IEEE format.  A Double variable is stored as a 64-bit (8-byte) number ranging in value from -1.79769313486232E308 to -4.94065645841247E-324 for negative values, from 4.94065645841247E-324 to 1.797693134862325E308 for positive values, and 0.  The type-declaration character is #.


domain <definition>
domain

A set of records defined by a table, query, or SQL expression.  Domain aggregate functions, such as DMax and DStDev, return statistical information about a specific domain.


domain aggregate function <definition>
domain aggregate function

A function used to aggregate data over a certain set of records (the domain).  The domain aggregate functions are DAvg, DCount, DFirst, DLast, DLookup, DMax, DMin, DStDev, DStDevP, DSum, DVar, and DVarP.  These functions can be used in SQL statements but not in Visual Basic code.


dynamic-link library (DLL) <definition>
dynamic-link library (DLL)

A library of routines loaded and linked into applications at run time.  DLLs are created with other programming languages such as C, MASM, or FORTRAN.


dynaset <definition>
dynaset

A type of Recordset object that returns a dynamic set of pointers to live database data.  Like a table- or a snapshot-type Recordset, a dynaset returns data in records (rows) and fields (columns).  Unlike a table-type Recordset, a dynaset-type Recordset can be the result of a query that joins two or more tables.  The records in dynaset-type Recordset objects are updatable if their Updatable property is True, the Field being changed is updatable, and the data page containing the current record isnt locked.


equi-join <definition>
equi-join

A join in which records from two tables are combined and added to the Recordset object only when there are equal values in the joined fields.  In Visual Basic, equi-joins are referred to as inner joins.


expression (Data Access) <definition>
expression (Data Access)

Any combination of operators, constants, literal values, functions, and names of fields, controls, and properties that evaluates to a single value.  You can use expressions as settings for many properties and action arguments, to set criteria or define calculated fields in queries.


external table <definition>
external table

A table in a database outside the open Microsoft Jet database.  An external table may take the form of another file or it may be a table in another relational database.


exclusive <definition>
exclusive

Indicates whether a database or a table can be shared by other users in a multiuser environment.  If the database or table is opened for exclusive use, it cant be shared by other users.


external database <definition>
external database

Either an ODBC database such as SQL Server that resides on a remote server, or one of the external databases such as Btrieve, Paradox, dBASE, FoxPro, Microsoft Excel or Microsoft Access.


field <definition>
field

A category of information stored in a table in a database [image] a column of data.  An element of a database table that contains a specific item of information, such as last name.


field data types <definition>
field data types

The following table lists the field data types and their equivalent Visual Basic data types.

Field data type	Visual Basic data type

True/False	Integer

Byte	Integer

Integer	Integer

Long	Long

Currency	Double

Single	Single

Double	Double

Date/Time	Variant

Text	String

Long Binary	String or Variant; can be up to 1.2 gigabytes.

Memo	String or Variant; can be up to 1.2 gigabytes.

Note that any kind of value can be stored in a Variant data type.


field properties <definition>
field properties

Attributes of a field that determine what kind of data it contains.  Size and Type are examples.


filter <definition>
filter

A set of criteria applied to records in order to create a subset of the records.


foreign key <definition>
foreign key

One or more table fields that refer to the primary key field or fields in another table.  For example, a list of valid part numbers would contain a foreign key to an inventory table containing references to valid part numbers.  Used when establishing referential integrity for a database.


foreign table <definition>
foreign table

A database table used to contain foreign keys.  Generally, you use a foreign table to establish or enforce referential integrity.  The foreign table is usually on the many side of a one-to-many relationship.  An example of a foreign table is a table of state codes or customer orders.


form <definition>
form

A window or dialog box.  Forms are containers for controls.  A multiple-document interface (MDI) form can also act as a container for child forms and some controls.


forward scroll <definition>
forward scroll

Move toward the end (EOF) of a Recordset object.


forward-only scrolling snapshot <definition>
forward-only scrolling snapshot

A snapshot-type Recordset object in which records can be searched only from beginning to end; the current record position can't be moved back toward the first record.  Forward-scrolling snapshots are useful for quickly scanning data, such as when you're searching for a particular record.


FROM clause <definition>
FROM clause

The part of an SQL statement that indicates the location of the data to be examined by the query by specifying which database tables are to be included in the search for the desired data.  The location specified by a FROM clause is sometimes called the domain.


Function procedure <definition>
Function procedure

A procedure that performs a specific task within a Visual Basic program and returns a value.  A Function procedure begins with a Function statement and ends with an End Function statement.


group <definition>
group

A collection of user accounts in a Workgroup object, identified by group name and personal identifier (PID).  Permissions assigned to a group apply to all users in the group.


identifier <definition>
identifier

An element of an expression that refers to the value of a field, or property.


inconsistent <definition>
inconsistent

The state of a multiple-table Recordset object that enables you to update all fields (columns).  For example, in a Recordset created by joining two tables in a one-to-many join (as in a Customers and Orders table), you can update Orders.[Customer ID] so that it doesnt match Customers.[Customer ID].


index (Data Access) <definition>
index (Data Access)

A dynamic cross-reference of one or more table data fields (columns) that permits faster retrieval of specific records from a table.  As records are added, changed, or deleted, the database management system automatically updates the index to reflect the changes.

When used with a table-type Recordset object, the current index determines the order in which data records are returned to the Recordset.  A table may have several indexes defined for its data.

A data access object that represents an index for a TableDef object.


initialization file <definition>
initialization file

An ASCII text file used to contain parameters for configuring Windows-based applications, the Microsoft Jet database engine or Microsoft Windows itself.  Generally, an initialization file uses the extension .INI and is named after the executable program that uses it.  For example, a program named TESTING.EXE would expect an initialization file called TESTING.INI.


inner join <definition>
inner join

A join in which records from two tables are combined and added to a Recordset only if the values of the joined fields meet a specified condition.  For instance, an equi-join is an inner join in which the values of the joined fields must be equal.


installable ISAM <definition>
installable ISAM

A driver you can specify that allows access to external database formats such as Btrieve, dBASE, Microsoft Excel, and Paradox.  ISAM is an acronym for Indexed Sequential Access Method.  The Microsoft Jet database engine installs (loads) these ISAM drivers when referenced by your application.  The location of these drivers is maintained in the Microsoft Windows registration database.


instance <definition>
instance

Any one of a set of objects sharing the same class.  For example, multiple instances of a Form class share the same code and are loaded with the same controls with which the Form class was designed.  During run time, the individual properties of controls on each instance can be set to different values.


Integer data type <definition>
Integer data type

A fundamental data type that holds integer numbers.  An Integer variable is stored as a 16-bit (2-byte) number ranging in value from -32,768 to 32,767.  The type-declaration character is % (ANSI character 37).


intrinsic constant <definition>
intrinsic constant

A constant provided by an application.  Visual Basic constants are listed in the Visual Basic (VB) object library and can be viewed using the Object Browser.


join <definition>
join

A database operation that combines some or all records from two or more tables, such as an equi-join, outer join, or self-join. Generally, a join refers to an association between a field in one table and a field of the same data type in another table.  You create a join with an SQL statement.

When you define a relationship between two tables, you create a join by specifying the primary and foreign table fields.  When you add a table to a query, you need to create a join between appropriate fields in the SQL statement that defines the query.


left outer join <definition>
left outer join

An outer join in which all the records from the left-hand side of the LEFT JOIN operation in the query's SQL statement are added to the Recordset object, even if there are no matching values in the joined field from the right-hand table.  Records from the right-hand table are combined with those from the left-hand table only when there are matching values in the joined fields.  When a left-side record has no match, a row of NULL values is joined on the right side.


left join <definition>
left join

A left outer join includes all of the records from the first (left-hand) of two tables, even if there are no matching values for records in the second (right-hand) table.


Legend

 Applies only to object.

 Applies only to collection.

 Applies to both object and collection.


linked object <definition>
linked object

An object that is created in another application and linked to a Visual Basic application.  When you link an object, you insert a placeholder in your application.  Unlike an embedded object, a linked object's data is actually stored in and managed by the application that created it.


locked <definition>
locked

The condition of a data page, Recordset object, or Database object that makes it read-only to all users except the one who is currently entering data in it.


Long Binary <definition>
Long Binary

A data type used to contain binary values up to 1.2 gigabytes in size.


Long data type

A four-byte integer (a whole number between -2,147,483,648 and 2,147,483,647, inclusive).


make table query <definition>
make table query

An action query that creates a new table from the Recordset object of an existing query.


many-only table <definition>
many-only table

A table that doesnt appear as the "one" side of any join in a query.


Memo object <definition>
Memo object

An object you can use to hold the contents of a table field that has a Memo field data type.  Memo objects can contain up to 1.2GB of data.


Memo data type <definition>
Memo data type

A field data type.  Such fields can contain up to1.2GB of data.


message <definition>
message

A packet of information passed from one application to another.


method <definition>
method

A procedure that acts on an object.


Microsoft Jet database engine <definition>
Microsoft Jet database engine

A database management system that retrieves data from and stores data in user and system databases.  The Jet engine can be thought of as a data manager component with which other data access systems, such as Microsoft Access and Visual Basic, are built.


multiuser database <definition>
multiuser database

A database that permits more than one user to access and modify the same set of data at the same time.  In some cases, the additional "user" may be another instance of your application or another application running on your system that accesses the same data as some other application.


normalize <definition>
normalize

To minimize the duplication of information in a relational database through effective table design.


Null <definition>
Null

A value indicating that a variable contains no valid data.  Null is the result of:

An explicit assignment of Null to a variable.

Any operation between expressions that contain Null.


null (Data Access) <definition>
Null (Data Access)

A value that indicates missing or unknown data.  Null values can be entered in fields for which information is unknown and in expressions and queries.  In Visual Basic, the Null keyword indicates a Null value.  Some fields, such as those defined as containing the primary key, cant contain null values.


null field <definition>
null field

A field containing no characters or values.  A null field isn't the same as a zero-length string ("") or a field with a value of 0.  A field is set to null when the content of the field is unknown.  For example, a Date Completed field in a task table would be left null until a task is completed.


Null propagation <definition>
Null propagation

The ability of Null expressions, when used with most operators, to take precedence over other values in expressions.


numeric expression <definition>
numeric expression

Any expression that can be evaluated as a number.  Elements of the expression can include any combination of keywords, variables, constants, and operators that result in a number.


Object Browser <definition>
Object Browser

A dialog box that lets you examine the contents of an object library to get information about the objects provided.


object data type <definition>
object data type

A collective term for objects defined by Visual Basic or by the Microsoft Jet database engine. In this context, an object data type represents objects that are stored in a field in the database.  These can include any of the OLE data types or other long binary fields.


object expression <definition>
object expression

An expression that specifies a particular object.  This expression can include any of the object's containers.  For example, if your application has an Application object that contains a Document object that contains a Text object, the following are valid object expressions:

Application.Document.Text

Application.Text

Document.Text

Text


object library <definition>
object library

A file with the .OLB extension that provides information to OLE Automation controllers (like Visual Basic) about available OLE Automation objects.  You can use the Object Browser to examine the contents of an object library to get information about the objects provided.


object variable <definition>
object variable

A variable that contains a reference to an object.


ODBC (Open Database Connectivity) <definition>
ODBC (Open Database Connectivity)

A standard protocol that permits applications to connect to a variety of external database servers or files.  ODBC drivers used by the Microsoft Jet database engine permit access to Microsoft SQL Server and several other external databases.

The ODBC applications programming interface (API) may also be used to access ODBC drivers and the databases they connect to without using the Jet engine.


ODBC data source <definition>
ODBC data source

A term used to refer to a database or database server used as a source of data. ODBC data sources are referred to by their Data Source Name.  Data sources can be created using the Windows control panel or the RegisterDatabase method.


ODBC driver <definition>
ODBC driver

A dynamic link library (DLL) used to connect a specific Open Database Connectivity data source with another (client) application.


OLE <definition>
OLE

Object linking and embedding: The technology that enables you to create applications that contain components from various other applications.


OLE Automation object <definition>
OLE Automation object

An object that is exposed to other applications or programming tools through OLE Automation interfaces.


OLE Object data type <definition>
OLE Object data type

A field data type you use for objects created in other applications that can be linked or embedded in a Microsoft Jet database.


one-to-many relationship <definition>
one-to-many relationship

An association between two tables in which:

•	The primary key value of each record in the primary table corresponds to the value in the matching field or fields of a number of records (or no record) in the related table.

•	The primary key value of each record in the related table is null or corresponds to the value in the matching field or fields of one and only one record in the primary table.


one-to-one relationship <definition>
one-to-one relationship

An association between two tables in which:

•	The primary key value of each record in the primary table corresponds to the value in the matching field or fields of no more than one record in the related table.

•	The primary key value of each record in the related table is null or corresponds to the value in the matching field of one and only one record in the primary table.


optimistic <definition>
optimistic

A type of locking in which the data page containing one or more records, including the record being edited, is unavailable to other users only while the record is being updated by the Update method, but is available between the Edit and Update methods.  Optimistic locking is used when accessing ODBC databases or when the LockEdits property of the Recordset object is set to False.


outer join <definition>
outer join

A join in which all the records from one table are added to the Recordset object, even if there are no matching values in the joined field from the second table.  Records from the second table are combined with those from the first table only when there are matching values in the joined fields.  Null records are joined when there is no match.


page <definition>
page

A portion of the database in which record data is stored.  Depending on the size of the records, a page may contain more than one record.  In Microsoft Jet databases (.MDB), a page is 2,048 (2K) bytes in length.


parameter (Data Access) <definition>
parameter (Data Access)

An element containing a value that you can change to affect the results of the query.  For example, a query returning data about an employee might have a parameter for the employee's name.  You can then use one QueryDef object to find data about any employee by setting the parameter to a specific name before running the query.


parameter query <definition>
parameter query

A query that requires you to provide one or more criteria values, such as Redmond for City, before the query is run.  A parameter query isnt, strictly speaking, a separate kind of query; rather, it extends the flexibility of other queries.


parse <definition>
parse

To identify the parts of a statement or expression and then validate those parts against the appropriate language rules.


pass-through query <definition>
pass-through query

An SQL-specific query you use to send commands directly to an SQL database server (such as Microsoft SQL Server).  With pass-through queries, you work with the tables on the server instead of attaching them.  Pass-through queries are used to execute SQL queries and system specific commands written using SQL dialects known only to the server.

A pass-through query may or may not return records.  If it does, they are always returned in a snapshot.


permission <definition>
permission

One or more attributes that specify what kind of access a user has to data or objects in a database.  For example, a table or query with Read Data permission permits a user to retrieve but not edit data in the table or query.


persistent object <definition>
persistent object

An object stored in the database, for example, a database table or QueryDef object.  Dynaset-type or snapshot-type Recordset objects are not considered persistent objects because they are created in memory as needed.


personal identifier (PID) <definition>
personal identifier (PID)

A case-sensitive alphanumeric string 4-20 characters long that the Microsoft Jet database engine uses in combination with the account name to identify a user or group in a Workgroup object.  You provide the PID and the account name when you create a new user or group.


pessimistic <definition>
pessimistic

A type of locking in which the page containing one or more records, including the record being edited, is unavailable to other users when you use the Edit method and remains unavailable until you use the Update method.  Pessimistic locking is enabled when the Lockedits property of the Recordset object is set to True.


primary key <definition>
primary key

One or more fields whose value or values uniquely identify each record in a table.  You can have only one primary key.  An Employees table, for example, could use the social security number for the primary key.


primary table <definition>
primary table

A database table used to contain primary keys.  Generally, a primary key table is used to establish or enforce referential integrity.  The primary table is usually on the one side of a one-to-many relationship with a foreign table.


property <definition>
property

A named attribute of an object.  Properties define object characteristics such as size, color, and screen location, or the state of an object, such as enabled or disabled.


query <definition>
query

A formalized instruction to a database to either return a set of records or perform a specified action on a set of records as specified in the query.  For example, the following SQL query statement returns records:

SELECT [Company Name] FROM Publishers WHERE State = 'NY'

You can create and run select, action, crosstab, parameter, and SQL-specific queries:


query parameter data types <definition>
query parameter data types

The set of data types for a field in a parameter query.  The Microsoft Jet database engine has 13 query parameter data types:

Category	Data type

Table fields	Currency, Date/Time, Memo, OLE Object, Text, and Yes/No correspond to the same data types in table fields.

Number	Byte, Single, Double, Integer, and Long Integer correspond to the five Field Size options of the Number data type in table fields.

Generic 	Value is a Generic data type that doesn't accept any type of data.

Binary	You can use the Binary data type in parameter queries directed to attached tables that recognize it.


QueryDef object <definition>
QueryDef object

A data access object that contains the SQL statement that describes a query and its properties, such as DateCreated and ODBCTimeout.  Querydef objects with an ODBC Connect property may contain an SQL statement that can only be executed on an external database like Microsoft SQL Server.  This is called an SQL pass-through query.


read-only <definition>
read-only

A type of access to data whereby information can be retrieved but not modified.


record <definition>
record

A set of related data about a person, place, event, or some other item.  Table data is stored in records (rows) in the database.  Each record is composed of a set of related fields (columns) [image] each field defining one attribute of information for the record.  Taken together, a record defines one specific unit of retrievable information in a database.


recordset <definition>
recordset

A logical set of records.  The three types of Recordset objects are dynaset, snapshot, and table.


recordset population <definition>
recordset population

The process of loading Recordset records into memory.

When a dynaset- or snapshot-type Recordset is first opened, it usually contains only one record, even if the query returns additional records.  As your code moves the current record forward (toward EOF) through the Recordset, additional records are fetched and become members of either the keyset (dynaset) or the set of records in memory (snapshot).  This process is called recordset population.  Executing the MoveLast or FindLast methods or setting the  PercentPosition property to 100 completely populates the Recordset.

In Visual Basic version 4.0, when using SQL Passthrough against ODBC data sources, the Recordset isnt fully-populated when first opened (as it was in Visual Basic version 3.0).


referential integrity <definition>
referential integrity

Rules that you set to establish and preserve relationships between tables when you add, change, or delete records.  Enforcing referential integrity prohibits users from adding records to a related table for which there is no primary key, changing values in a primary table that would result in orphaned records in a related table, and deleting records from a primary table when there are matching related records.

If you select the Cascade Update Related Fields or Cascade Delete Related Records option for a relationship, the Microsoft Jet database engine allows changes and deletions but changes or deletes related records to ensure that the rules are still enforced.


relationship <definition>
relationship

An association established between common fields (columns) in two tables.  A relationshp can be one-to-one or one-to-many.


requery <definition>
requery

To rerun a query to reflect changes to the records, retrieve newly added records, and eliminate deleted records.


reserved word <definition>
reserved word

A word that is part of a language, such as the Microsoft Jet database engine SQL language.  Reserved words include the names of statements, predefined functions and data types, methods, operators, and objects.  Examples include SELECT, UPDATE, BETWEEN, SET and INSERT.  Dont use reserved words for variable or object names.


right join <definition>
right join

A right outer join includes all of the records from the second (right-hand) of two tables, even if there are no matching values for records in the first (left-hand) table.

For example, you could use LEFT JOIN with the Departments (left) and Employees (right) tables to select all departments, including those that have no employees assigned to them.  To select all employees, including those who aren't assigned to a department, you would use RIGHT JOIN.


right outer join <definition>
right outer join

An outer join in which all the records from the right-hand side of the RIGHT JOIN operation in the query's SQL statement are added to the Recordset object, even if there are no matching values in the joined field from the left-hand table.  Records from the left-hand table are combined with those from the right-hand table only when there are matching values in the joined fields.


row <definition>
row

A set of related columns or fields used to hold data.  A row is synonymous with a record in the Microsoft Jet database engine.  A table is composed of zero or more rows of data.


run time <definition>
run time

The time when code is running.  During run time, you interact with the code as a user would.


run-time error <definition>
run-time error

An error that occurs when code is running.  A run-time error results when a statement attempts an invalid operation.


scope <definition>
scope

Defines the visibility of a variable, procedure, or object.  For example, a variable declared as Public is visible to all procedures in all modules in a directly referencing project (unless Option Private Module is in effect).  Variables declared in procedures are visible only within the procedure and lose their value between calls unless they are declared Static.


secure workgroup <definition>
secure workgroup

A Microsoft Jet database Workgroup object to which users log on with a user name and password and in which access to database objects is restricted according to permissions specified for user accounts and groups.


security <definition>
security

A set of features used to specify or restrict the access that specified users or user groups have to data and objects in a database.


select query <definition>
select query

A query that asks a question about the data stored in your tables and returns a Recordset object without changing the data.  Once the Recordset data is retrieved, you can examine and make changes to the data in the underlying tables.  In contrast, action queries can make changes to your data, but they don't return data records.


self-join <definition>
self-join

A join in which records from a table are combined with other records for the same table where there are matching values in the joined fields.  A self-join an be an equi-join or an outer join.  A self-join is useful when you ask hierarchical questions, such as a query that shows all the managers and the people who report to them.


server <definition>
server

The database management system designed to share data with client applications; servers and clients are often connected over a network.  A database server usually contains and manages a central repository of data that remote client applications can retrieve and manipulate.


session <definition>
session

A session delineates a sequence of operations performed by the Microsoft Jet database engine.  A session begins when a user logs in and ends when a user logs off.  All operations performed during a session form one transaction scope and are subject to permissions determined by the login user name and password.  Sessions are implemented as Workspace objects by the Jet engine.


Short data type <definition>
Short data type

A Microsoft Jet database engine fundamental data type that corresponds to the Integer data type defined by Visual Basic for Applications.  A Short variable is stored as a 16-bit (2-byte) number ranging in value from -32,768 to 32,767.  The type-declaration character is % (ANSI character 37).


Single data type <definition>
Single data type

A fundamental data type that holds single-precision floating-point numbers in IEEE format.  A Single variable is stored as a 32-bit (4-byte) number ranging in value from -3.402823E38 to -1.401298E-45 for negative values, from 1.401298E-45 to 3.402823E38 for positive values, and 0.  The type-declaration character is !.


snapshot <definition>
snapshot

A static copy of a set of records retrieved from the database and copied into memory.  Snapshot-type Recordset objects can be created from a base table, a query, or another recordset.  Snapshots are not updatable.  All SQL pass-through queries return snapshots.


sort order <definition>
sort order

A sequencing principle used to order data, for example, alphabetic, numeric, ascending, descending, and so on.


SQL database <definition>
SQL database

A database that can be accessed through use of Open Database Connectivity (ODBC) data sources.


SQL-specific query <definition>
SQL-specific query

A query that can be created only by writing an SQL statement.  Subqueries and pass-through, union, and data-definition queries are SQL-specific queries.


SQL statement/string <definition>
SQL statement/string

An expression that defines a Structured Query Language (SQL) command, such as SELECT, UPDATE, or DELETE, and includes clauses such as WHERE and ORDER BY.  SQL strings and statements are typically used in queries, Recordset objects, and aggregate functions but can also be used to create or modify a database structure.


standard deviation <definition>
standard deviation

A parameter that indicates the way in which a probability function is centered around its mean and that is equal to the square root of the moment in which the deviation from the mean is squared.  Used to describe sets of values to determine how far the value varies from the arithmetic mean or average.


standard naming conventions <definition>
standard naming conventions

A set of specific rules for naming Microsoft Jet database engine objects.  Names can be up to 64-characters long and can include any combination of letters, numbers, spaces, and special characters except a period (.), an exclamation mark (!), a backquote character (`), and brackets ([ ]).  You also can't use leading spaces or control characters (ASCII values 0 through 31).


string comparison <definition>
string comparison

A comparison of two sequences of characters.  Use Option Compare to specify binary or text comparison.  In English, binary comparisons are case-sensitive; text comparisons are not.


String data type <definition>
String data type

A fundamental data type that holds character information.  A String variable can contain approximately 65,535 bytes (64K), is either fixed-length or variable-length, and contains one character per byte.  Fixed-length strings are declared to be a specific length.  Variable-length strings can be any length up to 64K, less a small amount of storage overhead.

The type-declaration character for the String data type is $.


string expression <definition>
string expression

Any expression that evaluates to a sequence of contiguous characters.  Elements of the expression can include a function that returns a string, a string literal, a string constant, a string variable, a string Variant, or a function that returns a string Variant (VarType 8).


Structured Query Language (SQL) <definition>
Structured Query Language (SQL)

A language used in querying, updating, and managing relational databases.  SQL can be used to retrieve, sort and filter specific data to be extracted from the database.

You can use SQL SELECT statements anywhere a table name, query name, or field name is accepted.  For example, you can use an SQL statement in place of a table name in the OpenRecordset method.


syntax error <definition>
syntax error

An error that occurs when you enter a line of code that Visual Basic doesn't recognize.

Note   Syntax rules for individual keywords are defined in the Syntax section of the associated Help topic.  To get Help on a keyword from within the development environment, select the keyword and press F1.


system object <definition>
system object

A database object defined by the Microsoft Jet database engine, such as the table MSysIndexes.


table <definition>
table

The basic unit of data storage in a relational database.  A table stores data in records (rows) and fields (columns) and is usually about a particular category of things, such as employees or parts. Also called a base table.

A table-type Recordset is a logical representation of a base table in a database.


TableDef object <definition>
TableDef object

An object in a database that defines the structure of a table.  In contrast, a table is the physical container of the data in a database.


temporary disk <definition>
temporary disk

The disk or directory, identified by the TEMP operating system environment variable, where the Microsoft Jet database engine stores temporary files and result sets.  Also known as temporary drive.  Although the TEMP environment variable may point to a RAM disk, this isnt recommended.


TEMP <definition>
TEMP

A TEMP environment variable is set by your AUTOEXEC.BAT file when you start your system.  Generally, TEMP points to an area on your hard disk used by Microsoft Windows and other programs, like the Microsoft Jet database engine, to store information that doesn't need to be saved after you shut down your system.  For example, the following line in your AUTOEXEC.BAT file points the TEMP environment variable to the D:\TEMPAREA directory:

SET TEMP=D:\TEMPAREA


Text data type <definition>
Text data type

A field data type.  Text fields can contain up to 255 characters or the number of characters specified by the Size property of the Field object, whichever is less.


transaction <definition>
transaction

A series of changes made to a database's data and schema.  Mark the beginning of a transaction with the BeginTrans statement, commit the transaction using the CommitTrans statement, and undo all your changes since BeginTrans using the Rollback statement.

There is an implicit transaction while action queries are running.  If a query doesnt complete for any reason, it is automatically rolled back.

Transactions are optional and can be nested up to five levels.  Transactions increase the speed of data changing operations and enable changes to be reversed easily.

Transactions are global to the referenced database object's Workspace.


two's complement <definition>
two's complement

A type of base-2 notation used to represent positive and negative in which negative values are formed by complementing all bits and adding 1 to the result.  Complementing is done by changing all 1s to 0, and all 0s to 1.


union query <definition>
union query

A SQL-specific select query that creates a snapshot-type Recordset object containing data from all specified records in two or more tables with any duplicate records removed.  To include the duplicates, add the keyword ALL.

For instance, a union query of the Customers table and the Suppliers table results in a snapshot-type Recordset that contains all suppliers that are also customers.


update <definition>
update

The process that saves changes to data in a record.  Until the record is saved, changes are stored in a temporary record called the copy buffer.  The UPDATE clause in an SQL Statement changes data values in one or more records (rows) in a database table.


update query <definition>
update query

An action query that changes a set of records according to criteria you specify.  An update query doesnt return any records.


user account <definition>
user account

An account identified by a user name and personal identifier (PID) that is created to manage access to database objects in a Microsoft Jet database Workgroup object.


validation <definition>
validation

The process of checking whether entered data meets certain conditions or limitations.


validation properties <definition>
validation properties

Properties used to set conditions on table fields and records.  Validation properties include ValidationRule, Required and AllowZeroLength.


validation rule <definition>
validation rule

A rule that sets limits or conditions on what can be entered in one or more fields.  Validation rules can be set for a Field or a TableDef object.  Validation rules are checked when you update a record containing fields requiring validation.  If the rule is violated, a trappable error results.


variable <definition>
variable

A named storage location that can contain data that can be modified during program execution.  Each variable has a name that uniquely identifies it within its level of scope.  A data type can be specified or not.

Variable names:

Must begin with an alphabetic character.

Can't contain an embedded period or type-declaration character.

Must be unique within the same scope.

Must be no longer than 255 characters.


Variant data type <definition>
Variant data type

A special data type that can contain numeric, string, or date data as well as the special values Empty and Null.  The VarType function defines how the data in a Variant is treated.  All variables become variant types if not explicitly declared as some other type.


variant expression <definition>
variant expression

Any expression that can evaluate to numeric, string, or date data as well as the special values Empty and Null.


VarType <definition>
VarType

The VarType function returns a value that provides information about the type of data stored in a variable.  The following table shows the equivalent constant, the return value, and a description of the variable:

Constant	Value	Description

vbEmpty	0	Uninitialized

vbNull	1	Contains no valid data

vbInteger	2	Integer

vbLong	3	Long integer

vbSingle	4	Single-precision floating-point number

vbDouble	5	Double-precision floating-point number

vbCurrency	6	Currency

vbDate	7	Date

vbString	8	String

vbObject	9	OLE Automation object

vbError	10	Error

vbBoolean	11	Boolean

vbVariant	12	Variant (used only for arrays of Variants)

vbDataObject	13	Non-OLE Automation object

vbByte	17	Byte

vbArray	8192	Array

Note   The constant vbArray combined with any other constant indicates an array of that type of variable.


WHERE clause <definition>
WHERE clause

The part of an SQL statement that specifies which records to retrieve.  The WHERE clause limits the scope of the query and specifies which columns are used to join multiple tables.  When using the Microsoft Jet database engine to perform the query, use the JOIN clause to join multiple tables.


wildcard characters <definition>
wildcard characters

The asterisk (*), question mark (?), number sign (#), exclamation point (!), hyphen (-), and brackets ([ ]) are wildcard characters.  You can use these characters in queries and expressions to include all records, filenames, or other items that begin with specific characters or match a certain pattern.  You can also use wildcard characters and matching characters to further refine a search when using an SQL statement.

Symbol	Example	Usage
*	wh* finds what, white, and why *at finds cat, bat, and what	Like the MS-DOS asterisk (*) wildcard character, this asterisk matches any number of characters.  But unlike MS-DOS, it can be used anywhere in the character string.
?	b?ll finds ball, bell, and bill	Like the MS-DOS ? wildcard character, this symbol matches any single character.
#	1#3 finds 103, 113, 123	Matches any single digit.
[ ]	b[ae]ll finds ball and bell but not bill	Matches any single character within the brackets.
!	b[!ae]ll finds bill and bull but not bell or ball	Matches any character not in the list.
-	b[a-c]d finds bad, bbd, and bcd	Matches any one of a range of characters.
Note   The wildcard characters * (asterisk), ? (question mark), # (number sign), and [ (opening bracket) can match themselves only if enclosed in brackets.


workgroup <definition>
workgroup

A group of users in a multiuser environment who share data and the same system database (typically the SYSTEM.MDA file).


workgroup administrator <definition>
workgroup administrator

A member of the group Admins in a Microsoft Jet database Workgroup object.  A workgroup administrator can always obtain full permissions for any database object created in the Workgroup.


workspace <definition>
workspace

A Workspace object defines a session for a specific user.  When Visual Basic starts, a default Workspace is created with a password of "" and username of "Admin".


Yes/No data type <definition>
Yes/No data type

A field data type that contains a Boolean (True/False or yes/no) value.


zero-length string <definition>
zero-length string

A string containing no characters.  The Len function of a zero-length string returns 0.


ODBC objects require VBODBCA.DLL

See Also	Example	Specifics

Couldn't locate the VBODBCA.DLL file. Check setup or the location of this file.


Expression not valid: <expression>. (Error 2055)

See Also	Example	Specifics

You entered an invalid expression.  Check the expression to make sure you entered it correctly.


Can't change the data type or field size of this field.  It is part of one or more relationships. (Error 2390)

See Also	Example	Specifics

You can't change the data type of any fields that make up the primary key in the primary table, or of any matching fields in the related table.


Syntax error in number
Syntax error in number. (Error 2420)

See Also	Example	Specifics

A number was called for here; it is invalid.   This can occur if a non-numeric value is provided as part of the expression.


Syntax error in date. (Error 2421)

See Also	Example	Specifics

Date syntax incorrect.  This error may occur if you specify an invalid date.  For example, 9/31/94 is invalid (September only has 30 days).


Syntax error in string
Syntax error in string. (Error 2422)

See Also	Example	Specifics

You entered an expression that has an invalid string.  For example, you may have exceeded the maximum length of a string.  A string can be up to 255 characters long, including opening and closing quotation marks.  Check the expression to make sure you entered it correctly.


Invalid use of '.', '!', or '()'. (Error 2423)

See Also	Example	Specifics

The expression doesn't use delimiters correctly. To reference the properties of data objects, it is recommended that you use the ."<name>" syntax. See the Programmer's Reference "Accessing the Recordset Object" for more information.


Unknown name
Unknown name. (Error 2424)

See Also	Example	Specifics

You entered an expression that has a field, control, or property name that can't be recognized.  Make sure the object exists, or check the expression to make sure you entered it correctly.


Unknown function name
Unknown function name. (Error 2425)

See Also	Example	Specifics

You entered an expression with a function name that can't be recognized.  Make sure the function exists, or check the expression to make sure you entered it correctly.


Function isn't available in expressions. (Error 2426)

See Also	Example	Specifics

You have entered a function that can't be used in this expression.  The functions DoEvents, LBound, UBound , Spc, and Tab aren't available in expressions.


Object has no value. (Error 2427)

See Also	Example	Specifics

You entered an expression containing an identifier for an object that has no value.

Check the expression to make sure you entered it correctly.


Invalid arguments used with domain function (Error 2428)

See Also	Example	Specifics

You have entered an invalid argument in a domain function.  For information on the function's arguments, see Domain Aggregate Functions, and then choose the name of the function.


In operator without () (Error 2429)

See Also	Example	Specifics

When coding an SQL statement that includes the IN operator, you must surround the list of items to test with parenthesis. For example, to see if a value is one of a set of values you could code in the WHERE clause of an SQL query:

WHERE Publishers.State IN ('TX', 'CA', 'WA')

This code tests to see if the State field is either Texas, California, or Washington.


Between operator without And (Error 2430)

See Also	Example	Specifics

When using the Between operator to test whether a value of an expression lies within a specified range of values, specify the upper and lower limits of the range separated with the reserved word And.  For example, to test for a range of "A" to "C" code:

WHERE MyField BETWEEN "A" AND "C"


Syntax error (missing operator).  (Error 2431)

See Also	Example	Specifics

The expression or statement was missing an operator.


Syntax error (comma). (Error 2432)

See Also	Example	Specifics

The expression or statement used a comma where it doesn't belong or was missing a comma to separate arguments.


Syntax error. (Error 2433)

See Also	Example	Specifics

The wording or punctuation of the command isn't correct.  It may be missing an operator or an operator specified may not exist.


Syntax error (missing operator). (Error 2434)

See Also	Example	Specifics

The expression or statement was missing an operator.


Extra ). (Error 2435)

See Also	Example	Specifics

You entered an expression that has too many closing parentheses.  Delete any parenthesis that don't have matching opening parenthesis.


Missing ), ], or Item. (Error 2436)

See Also	Example	Specifics

You entered an expression that is missing a closing parenthesis, bracket or vertical bar.  Check the expression to make sure you entered it correctly.


Invalid use of vertical bars. (Error 2437)

See Also	Example	Specifics

You entered an expression that has invalid vertical bars (|).  Check the expression to make sure you entered it correctly.


Syntax error. (Error 2438)

See Also	Example	Specifics

You entered an expression that has invalid syntax.  For example, an operand or operator may be missing, you may have entered an invalid character or comma, or you may have entered text without surrounding it in quotation marks (").  Check the expression to make sure you entered it correctly.


Wrong number of arguments used with function. (Error 2439)

See Also	Example	Specifics

You entered an expression that has a function with the wrong number of arguments.  Check the function to verify how many arguments it takes, or check the expression to make sure you entered it correctly.


IIF function without (). Error (2440)

See Also	Example	Specifics

The IIf function requires parentheses around its arguments (as shown below):

IIf( expr, truepart, falsepart )

The IIf function has the following parts:

Argument	Description

expr	Expression you want to evaluate.

truepart	Value or expression returned if expr is True.

falsepart	Value or expression returned if expr is False.


Invalid use of parentheses. (Error 2442)

See Also	Example	Specifics

You entered an expression that has invalid parentheses.  For example, you may be trying to use the parenthesis syntax for an identifier in a query.  In a query, you can use only the standard identifier syntax; for example:

Forms![MyForm]![MyControl]


Invalid use of Is operator. (Error 2443)

See Also	Example	Specifics

The Is operator is used to determine if an expression is Null.  You can use the Is operator in an expression only with Null or Not Null.


Expression too complex. (Error 2445)

See Also	Example	Specifics

This expression is too complex for Visual Basic or the Microsoft Jet database engine. Try to simplify the expression.


Out of memory during calculation. (Error 2446)

See Also	Example	Specifics

Visual Basic doesn't have enough memory to complete the calculation.  Make sure you have enough RAM and a virtual swap file established.  You may need to terminate other programs, remove desktop wallpaper bitmaps, or remove unneeded TSR programs or device drivers to recover enough memory.


Invalid use of '.', '!', or '()'. (Error 2447)

See Also	Example	Specifics

The expression doesn't use delimiters correctly. To reference the properties of data objects, it is recommended that you use the ."<name>" syntax. See the Programmer's Reference "Accessing the Recordset Object" for more information.


Can't set value. (Error 2448)

See Also	Example	Specifics

You are trying to assign a value to an object that is read-only or doesn't have a value.


Invalid method in expression. (Error 2449)

See Also	Example	Specifics

You called an invalid method in an expression.  For example, you may have tried to use the Print method with an object other than Debug.  Check the expression to make sure you entered it correctly.


Invalid reference to form 'Item'.
Invalid reference to form 'Item'. (Error 2450)

See Also	Example	Specifics

You entered an expression that refers to a form that isn't open.  Make sure the form is open, or check the expression to make sure you entered it correctly.


Invalid reference to report 'Item'.
Invalid reference to report 'Item'. (Error 2451)

See Also	Example	Specifics

You entered an expression that refers to a report that isn't open.  Make sure the report is open, or check the expression to make sure you entered it correctly.


Invalid reference to Parent property.
Invalid reference to Parent property. (Error 2452)

See Also	Example	Specifics

You entered an expression that has an invalid reference to the Parent property.  For example, you may be using the property with a form rather than a subform or subreport.  Check the expression to make sure you entered it correctly.


Invalid reference to control 'Item'.
Invalid reference to control 'Item'. (Error 2453)

See Also	Example	Specifics

You entered an expression that refers to a control that doesn't exist.  Check the expression to make sure you entered it correctly.


Invalid reference to '!Item'.
Invalid reference to '!Item'. (Error 2454)

See Also	Example	Specifics

You entered an invalid object name following the ! operator in an expression.  For example, you may have tried to enter an identifier with two control names separated by the ! operator.

You can use the ! operator to refer to a form, or to the value of a control or field:

To refer to a form or report, enter the Form object names followed by a form name ; for example:

Forms![MyForm]

To refer to the value of a control or field, enter a form or report identifier followed by a control name or field name; for example:

Forms![MyForm]![MyControl]


Invalid reference to property 'Item'.
Invalid reference to property 'Item'. (Error 2455)

See Also	Example	Specifics

You entered an expression that has an invalid reference to a property.  For example, the property may not exist or may not apply to an object you specified.  Check the expression to make sure you entered it correctly.


Invalid form number reference.
Invalid form number reference. (Error 2456)

See Also	Example	Specifics

You are referring to a form by a number that is outside the range of valid numbers.

Use the Count property to count the open forms and make sure that the number is within the valid range.


Invalid report number reference.
Invalid report number reference. (Error 2457)

See Also	Example	Specifics

You are referring to a report by a number that is outside the range of valid numbers.

Use the Count property to count the open reports and make sure that the number is within the valid range.


Invalid control number reference.
Invalid control number reference. (Error 2458)

See Also	Example	Specifics

You are referring to a control on a form by a number that is outside the range of valid numbers.

Use the Count property to count the controls on the form and make sure that the number is within the valid range.


Can't refer to Parent property in Design view.
Can't refer to Parent property in Design view. (Error 2459)

See Also	Example	Specifics

This property can't be accessed until run time.


Can't refer to Dynaset property in Design view. (Error 2460)

See Also	Example	Specifics

This property can't be accessed until run time.


Invalid section reference.
Invalid section reference. (Error 2461)

See Also	Example	Specifics

You are trying to use a string to refer to a form section.  You can refer to a section only by number.


Invalid section number reference.
Invalid section number reference. (Error 2462)

See Also	Example	Specifics

You are referring to a form section by a number that is outside the range of valid numbers.  Make sure that the number you're using is less than the number of sections on the report.


Invalid group level reference.
Invalid group level reference. (Error 2463)

See Also	Example	Specifics

You are trying to use a string to refer to a group level.  You can refer to a group level only by number.


Invalid group level number reference.
Invalid group level number reference. (Error 2464)

See Also	Example	Specifics

You are referring to a group level on a report by a number that is outside the range of valid numbers.  Make sure that the number you're using is less than the number of group levels on the report.


Invalid reference to field 'Item'. (Error 2465)

See Also	Example	Specifics

You entered an expression that refers to a field that doesn't exist.  Check the expression to make sure you entered it correctly.


Invalid reference to Dynaset property. (Error 2466)

See Also	Example	Specifics

You entered an expression that has an invalid reference to a Dynaset object.  Check the expression to make sure you entered it correctly.


Object referred to in expression no longer exists. (Error 2467)

See Also	Example	Specifics

You entered an expression that refers to an object that has been closed or deleted.  For example, you may have assigned a form to a Form object variable, closed the form, and then referred to the object variable.

Make sure objects referred to in the expression are active, or check the expression to make sure you entered it correctly.


Item1 in validation rule: 'Item2'. (Error 2469)

See Also	Example	Specifics

You have entered an invalid validation expression.  Check the expression to make sure you entered it correctly.


Item in validation rule. (Error 2470)

See Also	Example	Specifics

You have entered an invalid validation expression.  Check the expression to make sure you entered it correctly.


Item in query. (Error 2471)

See Also	Example	Specifics

The specified item is invalid in the context of a query or the expression you entered, because a query parameter produced an error.  Check the expression to make sure you entered it correctly.


Item in linked master field.
Item in linked master field. (Error 2472)

See Also	Example	Specifics

The LinkMasterField setting has produced an error.  Check the setting to make sure you entered it correctly.


Item1 in 'Item2' expression.
Item1 in 'Item2' expression. (Error 2473)

See Also	Example	Specifics

The expression entered in the Property setting produced an error.  Check the expression to make sure you entered it correctly.


No control is active.
No control is active. (Error 2474)

See Also	Example	Specifics

You entered an expression that requires a control in the active window.  Open or select a form containing a control; or create a new control, and then retry the operation.


No form is active.
No form is active. (Error 2475)

See Also	Example	Specifics

You entered an expression that requires a form to be the active window.  Open or select a form, and then retry the operation.


No report is active.
No report is active. (Error 2476)

See Also	Example	Specifics

You entered an expression that requires a report to be the active window.  Open or select a report, and then retry the operation.


Invalid subclass 'Item' referred to in TypeOf function.
Invalid subclass 'Item' referred to in TypeOf function. (Error 2477)

See Also	Example	Specifics

You have entered an invalid objecttype value in an If TypeOf object Is objecttype condition of an If...Then...Else Statement.


Search string has unmatched brackets (Error 3751)

See Also	Example	Specifics

When performing pattern matching, you must supply matching open and closed square brackets.


Reserved error (Item); there is no message for this error. (Error 3000)

See Also	Example	Specifics

An unexpected error occurred.  The specified code identifies the conditions under which this error can occur.


Invalid argument. (Error 3001)

See Also	Example	Specifics

You tried to perform an operation that involves a routine in a DLL, and one of the arguments to the routine is invalid.  Check your entry to make sure you have specified the correct arguments, and then try the operation again.

This error may also occur in some instances if you do not use the Set keyword.  For example:

s = OpenDatabase("c:\vb\biblio.mdb")

will return "Invalid argument".  To fix this, you need to use the Set keyword:

Set s = OpenDatabase("c:\vb\biblio.mdb")


Couldn't start session. (Error 3002)

See Also	Example	Specifics

You tried to initiate an operation that requires a new session, but you've reached the limit of sessions that can be active at one time.  Wait for other operations to finish or stop other operations, and then try the operation again.


Couldn't start transaction; too many transactions already nested. (Error 3003)

See Also	Example	Specifics

You tried to nest a transaction more than five-levels deep.  Use the CommitTrans or Rollback method to save or roll back the current transaction before you begin another.


Couldn't find database 'Item'. (Error 3004)

See Also	Example	Specifics

The database you're trying to use couldn't be found.  It may have been deleted, or you may have misspelled the name or path.  Check the name and path to make sure you entered them correctly.


'Item' isn't a valid database name. (Error 3005)

See Also	Example	Specifics

The specified database name doesn't follow the standard naming conventions for filenames.  Enter a new name, and then try the operation again.


Database 'Item' is exclusively locked. (Error 3006)

See Also	Example	Specifics

You tried to use a database that is currently open for exclusive access by another user.  Wait for the other user to finish working with the database, and then try the operation again.


Couldn't open database 'Item'. (Error 3007)

See Also	Example	Specifics

The specified database is an internal Microsoft Jet engine library database, which you can't open.


Table 'Item' is exclusively locked. (Error 3008)

See Also	Example	Specifics

You tried to use a table that is currently open for exclusive access by another user.  Wait for the other user to finish working with the table, and then try the operation again.


Couldn't lock table 'Item'; currently in use. (Error 3009)

See Also	Example	Specifics

You tried to lock a table while opening it, but the table can't be locked because it is currently in use.  Wait a moment, and then try the operation again.


Table 'Item' already exists. (Error 3010)

See Also	Example	Specifics

You tried to create or rename a table with a name that already exists in this database.  Choose another name, and then try the operation again.

In a multiuser database, this error can also occur if you delete a table, another user creates a table with the same name, and then you try to rollback the deletion of your table.  To restore your table, the other user must first delete or rename the new table before you try the rollback operation again.


Couldn't find object 'Item'. (Error 3011)

See Also	Example	Specifics

Possible causes:

The specified object doesn't exist.

You misspelled the object name.  Check for missing underscores ( _ ) or other punctuation, and make sure you didn't enter leading spaces.

If you're trying to open a Btrieve table, the paths indicated in the data definition file FILE.DDF may be incorrect.  Be sure your data (.DAT) files are in the correct directories.


Object 'Item' already exists. (Error 3012)

See Also	Example	Specifics

You tried to create an object with a name that already exists in this database.  Choose a different name, and then try the operation again.


Couldn't rename installable ISAM file. (Error 3013)

See Also	Example	Specifics

You tried to rename a Btrieve, dBASE, or Paradox table, but the file that contains that table couldn't be renamed.

Possible causes:

The file has been defined as read-only in the operating system or by your network.

In a network environment, you don't have write privileges for the file.


Can't open any more tables. (Error 3014)

See Also	Example	Specifics

You've reached the limit on the number of tables that can be opened at one time.  Close one or more tables, and then try the operation again.


Item' isn't an index in this table. (Error 3015)

See Also	Example	Specifics

You tried to use a value that isn't an Index.  You can determine the valid index names by looking in the Indexes collection of the TableDef object.


Field won't fit in record. (Error 3016)

See Also	Example	Specifics

You tried to import or paste a field that is too large.  Consider breaking the field into smaller pieces and then importing or pasting the data to multiple fields.


Field length is too long. (Error 3017)

See Also	Example	Specifics

You tried to define or create a Text field longer than 255 characters.  Use a number between 0 and 255, and then try the operation again.


Couldn't find field 'Item'. (Error 3018)

See Also	Example	Specifics

Possible causes:

The specified field doesn't exist.

You misspelled the field name.  Check for missing underscores ( _ ) or other punctuation, and make sure you didn't enter leading spaces.

You entered an invalid field identifier.  For example, [My Table]_[My Field] instead of MyTable![My Field].


Operation invalid without a current index. (Error 3019)

See Also	Example	Specifics

Set the Index, and then try the operation again.


Update without AddNew or Edit. (Error 3020)

See Also	Example	Specifics

You didn't use the AddNew or Edit method before trying to save changes to a record.  Use one of these methods and then use the Update method.


No current record. (Error 3021)

See Also	Example	Specifics

This error occurs following the unsuccessful application of one of the FindFirst, FindLast, FindNext, FindPrevious methods or the Seek method, when the underlying recordset contains no records or the record has been deleted.  Move to or select another record, and try the operation again.


Can't have duplicate key; index changes were unsuccessful. (Error 3022)

See Also	Example	Specifics

You tried to duplicate a value in a field that is the underlying table's primary key or an index that doesn't allow duplicates.  Change the data in the field or fields that contain duplicate data, remove the index, or redefine the index to permit duplicate entries and try again.


AddNew or Edit already used. (Error 3023)

See Also	Example	Specifics

You haven't saved or rolled back the current changes and are trying to add or change another record.  Use the Rollback or Update method, and then use the AddNew or Edit method.


Couldn't find file 'Item'. (Error 3024)

See Also	Example	Specifics

Possible causes:

The specified file doesn't exist.

You misspelled the filename.  Check for missing underscores ( _ ) or other punctuation,  and make sure you didn't enter leading spaces.  The filename may be too long.  MS-DOS-based systems require filenames no longer than 8 characters with a 3-character extensions separated by a period.

You entered an invalid file specification that contains an invalid path.  For example, you might have entered a path that doesn't exist or misspelled an element in the path specification.

The specified file is on a network drive and that network isn't connected.  Make sure the network is available, and then try the operation again.


Can't open any more files. (Error 3025)

See Also	Example	Specifics

You've reached the limit on the number of files that can be opened at one time.  Close one or more files, and then try the operation again.


Not enough space on disk. (Error 3026)

See Also	Example	Specifics

You tried to perform an operation that requires more disk space than is available.  Remove unused files from your disk or compress your database, and then try the operation again.


Couldn't update; database is read-only. (Error 3027)

See Also	Example	Specifics

You tried to save changes in a database that was opened for read-only access.

The database is read-only for one of these reasons:

You used the OpenDatabase function and opened the database for read-only access.

You are using the Data Control, and you set the ReadOnly property to True.

The database file is defined as read-only in the operating system or by your network.

The database file is stored on read-only media.

In a network environment, you don't have write privileges for the database file.

When working with a secured database, databases, tables or fields may be set to read-only.  You may not have permission to access this data with your user name and password.

Close the database, resolve the read-only condition, and then reopen the file for read/write access.


Couldn't initialize data access because file 'SYSTEM.MDA' couldn't be opened. (Error 3028)

See Also	Example	Specifics

In order to insure referential integrity in databases created by the Microsoft Jet database engine, Visual Basic must read the Jet database's SYSTEM.MDA file.  Make sure the file is in  the location specified in the SystemDB entry in the [Options] section of the .INI file.  If this file is unavailable, you can create it using the WRKGADM.EXE application included with Microsoft Access V2.0.


Not a valid account name or password. (Error 3029)

See Also	Example	Specifics

You entered an invalid account (user) name or password.

User names

User names can be from 1 to 20-characters long and include alphabetic characters, accented characters, numbers, spaces, and symbols, with the following exceptions:

The characters "  /  \  [  ]  |  <  >  +  =  ;  ,  :  ?  *

Leading spaces

Control characters

User names are not case-sensitive.

Passwords

Passwords can be any combination of 14 or fewer characters; passwords can't contain control characters.  Passwords are case-sensitive.


'Item' isn't a valid account name. (Error 3030)

See Also	Example	Specifics

The specified account (user) name isn't valid.  User names can be from 1 to 20-characters long and can include alphabetic characters, accented characters, numbers, spaces, and symbols, with the following exceptions:

The characters "  /  \  [  ]  |  <  >  +  =  ;  ,  :  ?  *

Leading spaces

Control characters

User names are not case-sensitive.


Not a valid password. (Error 3031)

See Also	Example	Specifics

You've typed an invalid password.  Passwords can be any combination of 14 or fewer characters, except control characters.  Passwords are case-sensitive.


Can't perform this operation. (Error 3032)

See Also	Example	Specifics

Possible causes:

You tried to delete the only user account in the group Admins.  The group Admins must have at least one user account.  If you want to delete this account, create a new account and add that it to the group Admins, or add an existing account to the group Admins, and then delete the account.

You tried to put a user in a group to which the user already belongs, by appending either a Group object to a User object's Groups collection that already has a Group object of the same name or a User object to a Group object's Users collection that already has a User object of the same name.


No permission for 'Item'. (Error 3033)

See Also	Example	Specifics

You don't have the necessary permissions for the specified object.  To change your permission assignments, see your system administrator or the object's creator.


Commit or Rollback without BeginTrans. (Error 3034)

See Also	Example	Specifics

You tried to commit or roll back a transaction that doesn't start with a BeginTrans statement.


Database has reached maximum size. (Error 3036)

See Also	Example	Specifics

To add data to this database, you must first reduce its size by deleting data.


Can't open any more tables or queries. (Error 3037)

See Also	Example	Specifics

You've reached the limit on the number of tables and queries that can be opened at one time.  Close one or more table or query, and then try the operation again.


Couldn't create index; too many indexes already defined. (Error 3039)

See Also	Example	Specifics

You can't create another index for this table.  Consider deleting an existing index to make room for the new index.


Disk I/O error during read. (Error 3040)

See Also	Example	Specifics

Visual Basic couldn't read the disk due to an internal disk or drive failure.

Possible causes:

You tried to read from a network drive, and the network is temporarily busy, or you're no longer connected to the network.  Check the network connection, and then try the operation again.

The disk or drive has failed.


Incompatible database version. (Error 3041)

See Also	Example	Specifics

You tried to access a database that is in an outdated format.  Compact the database and then try the operation again.


Out of MS-DOS file handles. (Error 3042)

See Also	Example	Specifics

Either close some files in Visual Basic or other applications, close other applications, or increase the number of available MS-DOS file handles.

To increase the number of file handles

1.	Edit your CONFIG.SYS file using Microsoft Windows Notepad or another text editor.  The CONFIG.SYS file is usually located in the root directory of your boot drive.  If you don't have a CONFIG.SYS file on your system, you must create one that contains the line listed in step 2.

2.	Look for the line that reads FILES = x, where x is some number.  Increase the number specified by the FILES command; the exact number of handles you enter depends on the applications you run and the number of files that are open at any given time.  If other applications open multiple files, you may need to specify more file handles.

As you increase the number of file handles, remember that each handle consumes more memory.  For additional information, refer to your operating system manual.

3.	Exit Microsoft Windows.

4.	Reboot your system, and then try the operation again.


Disk or network error. (Error 3043)

See Also	Example	Specifics

Visual Basic either couldn't read from or write to the disk due to an internal disk or drive failure.

Possible causes:

You tried to use a network drive, and the network is temporarily busy, or you're no longer connected to the network.  Check the network connection, and then try the operation again.

The disk or drive has failed.


'Item' isn't a valid path. (Error 3044)

See Also	Example	Specifics

Possible causes:

The specified path doesn't exist.  Check your entry to make sure it is spelled correctly.

The specified path points to a network drive that isn't connected.  Make sure the network is available.


Couldn't use 'Item'; file already in use. (Error 3045)

See Also	Example	Specifics

The specified file is currently being used by another user or session.  Wait for the other user or session to finish working with the file, and then try the operation again.


Couldn't save; currently locked by another user. (Error 3046)

See Also	Example	Specifics

You tried to save information on a database page that is currently locked by another user.  To save your changes, wait for the other user to finish, and then try the operation again.

In some cases, this problem may be caused because SHARE.EXE /L:500 isn't included in your CONFIG.SYS file.  This application enables file sharing and locking for MS-DOS operating systems and indicates that up to 500 locks are permitted.

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Using a text editor, add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The exact number of locks you use depends on the applications you run and the number of files that are locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	If you added SHARE.EXE to your AUTOEXEC.BAT file, reboot your system.

4.	Restart Microsoft Windows, and try the operation again.


Record is too large. (Error 3047)

See Also	Example	Specifics

You defined a table with records larger than Visual Basic can support.  This error occurs when you enter data into such a record [image] not when you define the table structure.  Redefine the table by making some fields shorter or by removing unneeded fields.


Can't open any more databases. (Error 3048)

See Also	Example	Specifics

You've reached the limit on the number of databases that can be opened at one time.  Close one or more databases and try the operation again.


Can't open database <name>. File is corrupt or not a Microsoft Jet database. (Error 3049)

See Also	Example	Specifics

Possible causes:

You tried to open a Btrieve, dBASE, or Paradox database or table.  Instead, attach the database or table to an existing Microsoft Jet database.

You tried to import or attach a Paradox database or table, and the associated .PX file couldn't be found.  Make sure the .PX file is in the same directory as the Paradox database or table, and then try the operation again.

If the specified database is a Jet database, it is corrupted.  You should attempt to repair the database.  If the database can't be repaired, restore the database from a backup copy; or create a new database.


Couldn't lock file; SHARE.EXE hasn't been loaded. (Error 3050)

See Also	Example	Specifics

To enable file and record locking in a multiuser environment, you must first load SHARE.EXE.  (Microsoft Windows for Workgroups operating systems don't require SHARE.EXE because file sharing is handled internally.)

This error may also result if you try to open a database on a read-only device.

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The number of locks you use depends on the applications you run and the number of files locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	Reboot your system, then try the operation again.


Couldn't open file 'Item'. (Error 3051)

See Also	Example	Specifics

Possible causes:

You must have Read Data permission for the specified file in order to view its data.  To change your permission assignments, see your system administrator or the table or query's creator.

You tried to open the indicated file exclusively, but another user already has the file open.


MS-DOS file sharing lock count exceeded.  You need to increase the number of locks installed with SHARE.EXE. (Error 3052)

See Also	Example	Specifics

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Using a text editor, add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The exact number of locks you use depends on the applications you run and the number of files that are locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	If you added SHARE.EXE to your AUTOEXEC.BAT file, reboot your system.

4.	Restart Microsoft Windows, and try the operation again.


Too many client tasks. (Error 3053)

See Also	Example	Specifics

You have too many copies of Visual Basic or Visual Basic applications running at the same time.  Close one or more instances.


Too many Memo or Long Binary fields. (Error 3054)

See Also	Example	Specifics

You tried to perform a Btrieve operation that involves too many Memo or Long Binary fields.  Reduce the number of Memo and Long Binary fields, and then try the operation again.


Not a valid file name. (Error 3055)

See Also	Example	Specifics

You tried to use a filename that doesn't follow the naming conventions for your operating system.  Reenter the filename, and then try the operation again.


Couldn't repair this database. (Error 3056)

See Also	Example	Specifics

This database is corrupted or it isn't a Microsoft Jet database.  Restore the corrupted Jet database from a backup copy or create a new database.


Operation not supported on attached tables. (Error 3057)

See Also	Example	Specifics

Import data from the table, and then try the operation again.


Can't have Null value in index. (Error 3058)

See Also	Example	Specifics

Possible causes:

You tried to add a primary key to a field that contains a Null value.

You tried to add a new record but didn't enter a value in the column that contains the primary key.

You executed a query that tried to create a primary key field that contains a Null value.


Operation canceled by user. (Error 3059)

See Also	Example	Specifics

You stopped the operation before its normal completion.  Some data changes may not have been saved.


Wrong data type for parameter 'Item'. (Error 3060)

See Also	Example	Specifics

You tried to use an argument with a data type that conflicts with the data type defined for this parameter.  For example, you might have tried to use a numeric argument with a parameter that expects a string expression.  Use an argument that has the correct data type, and then try the operation again.


Item1 parameters were expected, but only Item2 were supplied. (Error 3061)

See Also	Example	Specifics

This parameter query requires the specified number of parameters, which you didn't supply.  Provide the expected number of parameters, and run the query again.

In some cases, this message is generated when unknown field names or expressions are interpreted as query parameters.  Be sure to enclose field names containing spaces or punctuation with square brackets [].


Duplicate output alias 'Item'. (Error 3062)

See Also	Example	Specifics

You tried to execute an SQL statement that has more than one alias with the same name.  The following statement, for example, would produce this error:

SELECT [Last Name] AS Name, [First Name] AS Name FROM Employees;

Rename one or more of the aliases, and then try the operation again.


Duplicate output destination 'Item'. (Error 3063)

See Also	Example	Specifics

You tried to execute a query that contains more than one output field with the same name.

Possible cause:

You created an SQL statement that includes an INSERT INTO, SELECT...INTO, or UPDATE statement that lists the specified field name more than once.

Remove the duplicate fields or alias the output field names, and try the operation again.


Can't open action query 'Item'. (Error 3064)

See Also	Example	Specifics

You tried to open an action query using the OpenQueryDef method, which is only valid with select queries.  Use the Execute method with action queries.


Can't execute a non-action query. (Error 3065)

See Also	Example	Specifics

You tried to use the Execute method with a select query.  The Execute method is valid only with action queries.  Select queries contain a SELECT statement and can return records; action queries do not.


Query must have at least one output field. (Error 3066)

See Also	Example	Specifics

This error occurs if you don't specify any output field names when you create a query.  Select at least one output field.


Query input must contain at least one table or query. (Error 3067)

See Also	Example	Specifics

This error occurs if you don't select a table name when you create a query.  Select at least one table or query.


Not a valid alias name. (Error 3068)

See Also	Example	Specifics

The alias you entered doesn't follow standard naming conventions.  Enter a new name, and then try the operation again.


Can't have action query 'Item' as an input. (Error 3069)

See Also	Example	Specifics

You can't use the name of an action query here.  Instead, use the name of a select query.  To run an action query, use the Execute method.  Use the name of a select query instead of the name of an action query as input to the FROM clause.


Can't bind name 'Item'. (Error 3070)

See Also	Example	Specifics

The specified name isn't a recognized field name or a valid expression.  In a query, this error can occur if you enter a name that improperly refers to a database, table, or field.  For example, BIBLIO.* produces this error.


Can't evaluate expression. (Error 3071)

See Also	Example	Specifics

Possible causes:

You typed an expression that has invalid syntax.  For example, an operand or operator may be missing, you may have typed an invalid character or comma, or you may have typed text without enclosing it with quotation marks ( " ).  Check the expression to make sure you typed it correctly.

You typed an expression that is too complex.  For example, a numeric expression may contain too many complicated subexpressions.  Try simplifying the expression by assigning some subexpressions to variables.


Operation must use an updatable query. (Error 3073)

See Also	Example	Specifics

You tried to run, open, or modify a query that isn't updatable.

Possible causes:

You attempted to run a query that tried to update a field that can't be updated.  For example, you may have created the query in such a way that you tried to update a field on the one side of a one-to-many relationship.

You tried to use the OpenQueryDef method on a query that is in a database opened for read-only access.

The database is read-only for one of the following reasons:

1.	You used the OpenDatabase function or Data Control, and opened the database for read-only access.

2.	The database file has been defined as read-only in MS-DOS or your network operating system.

3.	In a network environment, you don't have write privileges for the database file.

4.	Close the database, resolve the read-only condition, and then reopen it for read/write access.

You must have Modify Definitions permission for the query in order to make changes.  To change your permission assignments, see your system administrator or the query's creator.


Can't repeat table name 'Item' in FROM clause. (Error 3074)

See Also	Example	Specifics

You can't list the table name more than once.  Remove the extra occurrences of the table name or use an alias.  If you are trying to join a table to itself, use an alias to change the second reference to the table.


Item1 in query expression 'Item2'. (Error 3075)

See Also	Example	Specifics

The expression you typed isn't valid for the reason indicated in the message.  Check your typing to make sure you have typed field names and punctuation correctly, and then try the operation again.


Item in criteria expression. (Error 3076)

See Also	Example	Specifics

The expression you entered isn't valid for the reason indicated in the message.  Check your typing to make sure you entered field names and punctuation correctly, and then try the operation again.


Item in expression. (Error 3077)

See Also	Example	Specifics

The expression you entered isn't valid for the reason indicated in the message.  Make sure you entered field names and punctuation correctly, and then try the operation again.


Couldn't find input table or query 'Item'. (Error 3078)

See Also	Example	Specifics

Possible causes:

The specified table or query doesn't exist.

You misspelled the table or query name.  Check for missing underscores  ( _ ) or other punctuation, and make sure you didn't enter leading spaces.


Ambiguous field reference 'Item'. (Error 3079)

See Also	Example	Specifics

The specified field reference could refer to more than one table listed in the FROM clause of your SQL statement.  In the following example, the Order ID field exists in both the Orders and Order Details tables.  Because the statement doesn't specify which table Order ID belongs to, it produces this error.

SELECT [Order ID]

FROM Orders, [Order Details];

To complete this operation, fully qualify the field reference by adding a table name.  For example:

SELECT Orders.[Order ID]

FROM Orders, [Order Details];


Joined table 'Item' not listed in FROM clause. (Error 3080)

See Also	Example	Specifics

Add the specified table name to the query, and then try the operation again.


Can't join more than one table with the same name (Item). (Error 3081)

See Also	Example	Specifics

You tried to join more than one table that has the same name.  Select different tables, rename one of the tables, or use an alias, and then try the operation again.  If you are trying to join a table to itself, use a table alias to change the second reference to the table.


JOIN operation 'Item' refers to a non-joined table. (Error 3082)

See Also	Example	Specifics

You tried to execute an SQL statement that contains an invalid join.  This error occurs when you try to create a join on a field that isn't in one of the joined tables.  The following example produces this error.

SELECT Authors.[First Name], Titles.[ISBN]

FROM Authors, Titles, AuthorTitles,

Authors INNER JOIN Titles ON Authors.ID = AuthorTitles.ISBN;

The error occurs because the join involves the Authors and Titles tables, but the joined fields are in the Authors and AuthorTitles tables.


Can't use internal report query. (Error 3083)

See Also	Example	Specifics

You tried to use an SQL statement that includes an explicit reference to a disallowed internal report query.  Remove the invalid reference and then try the operation again.


Can't insert into action query. (Error 3084)

See Also	Example	Specifics

You tried to run an append query using an action query for the input.  Replace the action query with a select query and then try the operation again.


Undefined function 'Item' in expression. (Error 3085)

See Also	Example	Specifics

You entered an SQL expression that includes a function procedure name that can't be recognized.  Make sure the function exists, or check the expression to make sure you entered the name correctly.


Couldn't delete from specified tables. (Error 3086)

See Also	Example	Specifics

You tried to delete data from one or more tables, but the deletion couldn't be completed.

Possible causes:

You don't have permission to modify the table.  To change your permissions assignments, see your system administrator or the table's creator.

The database was opened for read-only access.  The database is read-only for one of these reasons:

1.	You used the OpenDatabase function and opened the database for read-only access.

2.	The database file is defined as read-only in the database server operating system or by your network.

3.	In a network environment, you don't have write privileges for the database file.

4.	In Visual Basic, you used the Data control and set the ReadOnly property to True..

To delete the data, close the database, resolve the read-only condition, and then reopen the file for read/write access.


Too many expressions in GROUP BY clause. (Error 3087)

See Also	Example	Specifics

You created an SQL statement with more than 10 fields listed in the GROUP BY clause.  Remove some of the fields listed in the GROUP BY clause.


Too many expressions in ORDER BY clause. (Error 3088)

See Also	Example	Specifics

You created an SQL statement that has an ORDER BY clause with more than ten expressions.  Remove some of the fields listed in the ORDER BY clause.


Too many expressions in DISTINCT output. (Error 3089)

See Also	Example	Specifics

You created an SQL statement that has an ALL, DISTINCT, or DISTINCTROW predicate with more than ten expressions.  Remove the DISTINCT reserved word, or remove some of the fields listed in the DISTINCT predicate.


Resultant table may not have more than one Counter field. (Error 3090)

See Also	Example	Specifics

You tried to execute a query that would result in a table with more than one field that has a Counter data type.  Change the query to include only one Counter field.


HAVING clause (Item) without grouping or aggregation. (Error 3091)

See Also	Example	Specifics

You tried to execute an SQL statement that contains a HAVING clause but doesn't contain a GROUP BY clause or an aggregate function in the SELECT statement.  For example, this error occurs if you execute the following SQL statement:

SELECT [Last Name]

FROM Employees

HAVING [Last Name] > "M";

If you don't want to perform grouping or include an aggregate function, you can apply the same condition by entering a WHERE clause.  The next example shows how you might enter the preceding SQL statement correctly.

SELECT [Last Name]

FROM Employees

WHERE [Last Name] > "M";


Can't use HAVING clause in TRANSFORM statement. (Error 3092)

See Also	Example	Specifics

If you want to specify selection criteria, use a WHERE clause.


ORDER BY clause (Item) conflicts with DISTINCT. (Error 3093)

See Also	Example	Specifics

You created an SQL statement with an ALL, DISTINCT, or DISTINCTROW predicate and an ORDER BY clause that contains a field not listed in the SELECT statement.  Remove the DISTINCT reserved word, or remove the specified field from the ORDER BY clause.


ORDER BY clause (Item) conflicts with GROUP BY clause. (Error 3094)

See Also	Example	Specifics

This error can occur when you create a select query and specify grouped fields after sorted fields that are not grouped.  For example, you created an SQL statement with the specified field out of sequence in the ORDER BY clause.  Move the specified field to the left of the ungrouped fields, or remove the specified field from the ORDER BY clause


Can't have aggregate function in expression (Item). (Error 3095)

See Also	Example	Specifics

You can't use an aggregate function in this expression.


Can't have aggregate function in WHERE clause (Item). (Error 3096)

See Also	Example	Specifics

You can't use an aggregate function in the WHERE clause of an SQL statement.


Can't have aggregate function in ORDER BY clause (Item). (Error 3097)

See Also	Example	Specifics

You can't use an aggregate function in the ORDER BY clause of an SQL statement.


Can't have aggregate function in GROUP BY clause (Item). (Error 3098)

See Also	Example	Specifics

You can't use an aggregate function in the GROUP BY clause of an SQL statement.


Can't have aggregate function in JOIN operation (Item). (Error 3099)

See Also	Example	Specifics

You can't use an aggregate function in the JOIN operation of an SQL statement.


Can't set field 'Item' in join key to Null. (Error 3100)

See Also	Example	Specifics

When you join tables, the fields you join can't contain any null values.  Either select different fields or enter data in the fields, and then try the operation again.


Join is broken by value(s) in fields 'Item'. (Error 3101)

See Also	Example	Specifics

In a one-to-many relationship, you entered data on the "many" side that doesn't exist on the "one" side.  For example, this error occurs if you join a Customers table and Orders table on a Customer ID field, and then add an order using a Customer ID that doesn't exist in the Customers table.


Circular reference caused by 'Item'. (Error 3102)

See Also	Example	Specifics

You tried to execute a query that depends on itself for data.  For example, this error occurs if you execute either of the following queries:

Query1

SELECT * FROM Employees, Query2;

Query2

SELECT * FROM Query1;

Redesign the queries to eliminate the dependency.


Circular reference caused by alias 'Item' in query definition's SELECT list. (Error 3103)

See Also	Example	Specifics

The specified alias created an unresolvable reference.  This error can occur, for example, if you enter the following SQL statement, in which A is the circular reference:

SELECT A + B AS C, C + D AS E, E + F AS A
FROM MyTable;


Can't specify Fixed Column Heading 'Item' in a crosstab query more than once. (Error 3104)

See Also	Example	Specifics

When you create a crosstab query with fixed column headings, the values you specify must be unique.  Change one or more of the duplicate column headings, and then try the operation again.


Missing destination field name in SELECT INTO statement (Item). (Error 3105)

See Also	Example	Specifics

Enter a destination field name in the specified statement, and then try the operation again.


Missing destination field name in UPDATE statement (Item). (Error 3106)

See Also	Example	Specifics

Enter a destination field name in the specified statement, and then try the operation again.


Couldn't insert; no insert permission for table or query 'Item'. (Error 3107)

See Also	Example	Specifics

You must have Modify Data permission for the specified table or query to insert data into it.  To change your permission assignments, see your system administrator or the table or query's creator.


Record(s) can't be edited; no Update Data permission on <name>. (Error 3108)

See Also	Example	Specifics

You must have Update Data permission for the specified table or query to replace data in it.  To change your permission assignments, see your workgroup administrator or the table or query's creator.


Couldn't delete; no delete permission for table or query 'Item'. (Error 3109)

See Also	Example	Specifics

You must have Modify Data permission for the specified table or query in order to delete data.  To change your permission assignments, see your system administrator or the table or query's creator.


Couldn't read definitions; no read definitions permission for table or query 'Item'. (Error 3110)

See Also	Example	Specifics

You must have Read Definitions permission for the specified table or query to read its definition.  To change your permission assignments, see your system administrator or the table or query's creator.


Couldn't create; no create permission for table or query 'Item'. (Error 3111)

See Also	Example	Specifics

You tried to create the specified table or query, but you don't have the required Modify Definitions permission.  To change your permission assignments, see your system administrator or the query's creator.


Couldn't read; no read permission for table or query 'Item'. (Error 3112)

See Also	Example	Specifics

You must have Read Data permission for the specified table or query to view its data.  To change your permission assignments, see your system administrator or the table or query's creator.


Can't update 'Item'; field not updatable. (Error 3113)

See Also	Example	Specifics

Possible causes:

The specified field is part of a Table or Dynaset object that can't be updated.  For example, this error occurs if you try to update a Counter.

You executed a query that combines updatable and nonupdatable Table objects, and you tried to update one of the fields in the query's resulting Dynaset.


Can't include Memo or Long Binary when you select unique values (Item). (Error 3114)

See Also	Example	Specifics

Remove the DISTINCT reserved word.


Can't have Memo or Long Binary in aggregate argument (Item). (Error 3115)

See Also	Example	Specifics

You can't include Memo or Long Binary fields in an aggregate function.


Can't have Memo or Long Binary in criteria (Item) for aggregate function. (Error 3116)

See Also	Example	Specifics

The HAVING clause of an SQL statement can't include Memo or Long Binary fields.


Can't sort on Memo or Long Binary (Item). (Error 3117)

See Also	Example	Specifics

The ORDER BY clause of an SQL statement can't include Memo or Long Binary fields.


Can't join on Memo or Long Binary (Item). (Error 3118)

See Also	Example	Specifics

You can't join Memo or Long Binary fields.  The field you use to logically tie two or more tables together must be some other data type, such as character or integer.


Can't group on Memo or Long Binary (Item). (Error 3119)

See Also	Example	Specifics

The GROUP BY clause of an SQL statement can't include Memo or Long Binary fields.


Can't group on fields selected with '*' (Item). (Error 3120)

See Also	Example	Specifics

You tried to execute a SELECT statement that groups or totals fields selected with an asterisk ( * ).  This error occurs, for example, if you enter the following SQL statement:

SELECT Orders.* FROM Orders GROUP BY [Ship Via];


Can't group on fields selected with '*'. (Error 3121)

See Also	Example	Specifics

You tried to execute a SELECT statement that groups or totals fields selected with an asterisk ( * ).

Possible cause:

You created an SQL statement that includes an aggregate function or GROUP BY clause that refers to a field you selected with an asterisk.  This error occurs, for example, if you enter the following SQL statement:

SELECT * FROM Orders GROUP BY [Ship Via];


'Item' not part of aggregate function or grouping. (Error 3122)

See Also	Example	Specifics

You tried to execute a query that doesn't include the specified expression as part of an aggregate function or grouping.

Possible cause:

You didn't enter an aggregate function in the TRANSFORM statement.


Can't use '*' in crosstab query. (Error 3123)

See Also	Example	Specifics

You tried to execute a query that groups or totals fields selected with an asterisk ( * ).  Choose specific fields, and then try the operation again.


Can't input from internal report query (Item). (Error 3124)

See Also	Example	Specifics

You tried to use an SQL statement that includes an explicit reference to a disallowed internal report query.


'Item' isn't a valid name. (Error 3125)

See Also	Example	Specifics

The specified name doesn't follow standard naming conventions or isn't a valid parameter or alias name.  Check your entry to make sure you haven't included invalid characters or punctuation and that the name isn't too long.


Invalid bracketing of name 'Item'. (Error 3126)

See Also	Example	Specifics

The specified name either can't have brackets around it or the brackets are mismatched.  Check your entry to make sure the brackets are properly matched, and then try the operation again.


INSERT INTO statement contains unknown field name 'Item'. (Error 3127)

See Also	Example	Specifics

You tried to use INSERT INTO statement with the specified field name, but that field doesn't exist in the output table.  Make sure you've typed the name correctly, and then try the operation again.


Must specify tables to delete from. (Error 3128)

See Also	Example	Specifics

You tried to execute a delete query but the query doesn't specify the name of the table containing the records you want to delete.

Possible cause:

You didn't type an asterisk for each table in the ALL, DISTINCT, DISTINCTROW predicates.  Instead, you typed field names (for example, Customers.Address instead of Customers.*).


Invalid SQL statement; expected 'DELETE', 'INSERT', 'PROCEDURE', 'SELECT', or 'UPDATE'. (Error 3129)

See Also	Example	Specifics

Your SQL statement couldn't be recognized because it doesn't begin with one of the specified reserved words.


Syntax error in DELETE statement. (Error 3130)

See Also	Example	Specifics

You entered an SQL statement that has an invalid DELETE statement.  Visual Basic can't determine what action to take.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in FROM clause. (Error 3131)

See Also	Example	Specifics

You entered an SQL statement that has an invalid FROM clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in GROUP BY clause. (Error 3132)

See Also	Example	Specifics

You entered an SQL statement that has an invalid GROUP BY clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in HAVING clause. (Error 3133)

See Also	Example	Specifics

You entered an SQL statement that has an invalid HAVING clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in INSERT statement. (Error 3134)

See Also	Example	Specifics

You entered an SQL statement that has an invalid INSERT INTO statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in JOIN operation. (Error 3135)

See Also	Example	Specifics

You entered an SQL statement that has an invalid join operation.  It could be an equi-join, outer-join or self-join.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in LEVEL clause. (Error 3136)

See Also	Example	Specifics

You entered an SQL statement that has an invalid Visual Basic SQL reserved words clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Missing semicolon (;) at end of SQL statement. (Error 3137)

See Also	Example	Specifics

SQL statements must include a trailing semicolon.  Add a semicolon, and then try the operation again.


Syntax error in ORDER BY clause. (Error 3138)

See Also	Example	Specifics

You entered an SQL statement that has an invalid ORDER BY clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in PARAMETER clause. (Error 3139)

See Also	Example	Specifics

You entered an SQL statement with an invalid PARAMETERS declaration.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in PROCEDURE clause. (Error 3140)

See Also	Example	Specifics

You entered an SQL statement that has an invalid PROCEDURE clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in SELECT statement. (Error 3141)

See Also	Example	Specifics

You entered an SQL statement that has an invalid SELECT statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Characters found after end of SQL statement. (Error 3142)

See Also	Example	Specifics

Microsoft Jet database engine SQL statements can't have any characters following the semicolon (;).  Unlike lines of code in Visual Basic, SQL statements can't include remarks.  Remove the extra characters.


Syntax error in TRANSFORM statement. (Error 3143)

See Also	Example	Specifics

You entered an SQL statement that has an invalid TRANSFORM statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in UPDATE statement. (Error 3144)

See Also	Example	Specifics

You entered an SQL statement that has an invalid UPDATE statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in WHERE clause. (Error 3145)

See Also	Example	Specifics

You entered an SQL statement that has an invalid WHERE clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


ODBC [image] call failed. (Error 3146)

See Also	Example	Specifics

Using ODBC, you tried to perform an operation on data in an SQL database.  This error may occur when the SQL database is on a network drive and the network isn't connected.  Make sure the network is available, and then try the operation again.


ODBC [image] data buffer overflow. (Error 3147)

See Also	Example	Specifics

Using ODBC, you tried to perform an operation that would have resulted in a record larger than the SQL database can support.  Not including Memo and Long Binary fields, a record can't be larger than approximately 2 kilobytes.  Consider breaking the data into smaller records.


ODBC [image] connection failed. (Error 3148)

See Also	Example	Specifics

Using ODBC, the connection to the SQL database server couldn't be made.  If the SQL database is on a network drive, make sure the network is available, and then try the operation again.


ODBC [image] incorrect DLL. (Error 3149)

See Also	Example	Specifics

The DLL file has become corrupted or isn't the correct one for this SQL database.  Reinstall the ODBC driver, and then try the operation again.


ODBC [image] missing DLL. (Error 3150)

See Also	Example	Specifics

One or more of the ODBC DLLs needed to connect to external databases is missing.  Reinstall the ODBC libraries and make sure they are in the path so the Windows loader can locate them.  Generally, these DLLs are installed in the WINDOWS\SYSTEM directory.


ODBC [image] connection to 'Item' failed. (Error 3151)

See Also	Example	Specifics

Using ODBC, the connection to the specified SQL database or table couldn't be made.  If the SQL database is on a network drive, make sure the network is available, and then try the operation again.


ODBC [image] incorrect driver version 'Item1'; expected version 'Item2'. (Error 3152)

See Also	Example	Specifics

The installed driver is corrupted or isn't the correct one for this SQL database.  Reinstall the ODBC driver, and then try the operation again.


ODBC [image] incorrect server version 'Item1'; expected version 'Item2'. (Error 3153)

See Also	Example	Specifics

The installed driver has become corrupted or isn't the correct one for this SQL database.  Reinstall the ODBC driver, and then try the operation again.


ODBC [image] couldn't find DLL 'Item'. (Error 3154)

See Also	Example	Specifics

Using ODBC, you tried to perform an operation that requires the specified DLL.

Possible causes:

The DLL file is on a network drive and the network isn't connected.  Make sure the network is available, and then try the operation again.

The DLL file wasn't installed properly.  Reinstall the ODBC driver, and then try the operation again.


ODBC [image] insert failed. (Error 3155)

See Also	Example	Specifics

Using ODBC, you tried to insert data into an SQL database; that insertion couldn't be completed.

Possible causes:

The insertion would have caused a rule violation.

The SQL database is read-only, or you don't have permission to insert data in that database.  Resolve the read-only condition, or see your system administrator or the person who created the database to obtain the necessary permissions.

The SQL database is on a network drive and the network isn't connected.  Make sure the network is available, and then try the operation again.


ODBC [image] delete failed. (Error 3156)

See Also	Example	Specifics

Using ODBC, you tried to delete data from an SQL database; the deletion couldn't be completed.

Possible causes:

The deletion would have caused a rule violation.

The SQL database is read-only, or you don't have permission to delete data in that database.  Resolve the read-only condition, or see your system administrator or the person who created the database to obtain the necessary permissions.

The SQL database is on a network drive and the network isn't connected.  Make sure the network is available, and then try the operation again.


ODBC [image] update failed. (Error 3157)

See Also	Example	Specifics

Using ODBC, you tried to update data in an SQL database; that update couldn't be completed.

Possible causes:

The update would have caused a rule violation.

The SQL database is read-only, or you don't have permission to update data in that database.  Resolve the read-only condition, or see your system administrator or the person who created the database to obtain the necessary permissions.

The SQL database is on a network drive and the network isn't connected.  Make sure the network is available, and then try the operation again.


Couldn't save record; currently locked by another user. (Error 3158)

See Also	Example	Specifics

You tried to save a record that is on a database page currently locked by another user.  To save your changes, wait for the other user to finish working with the record, and then try the operation again.

In some cases, this problem may be caused because SHARE.EXE /L:500 isn't included in your CONFIG.SYS file.  This application enables file sharing and locking for MS-DOS operating systems and indicates that up to 500 locks are permitted.

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Using a text editor, add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The exact number of locks you use depends on the applications you run and the number of files that are locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	If you added SHARE.EXE to your AUTOEXEC.BAT file, reboot your system.

4.	Restart Microsoft Windows, and try the operation again.


Not a valid bookmark. (Error 3159)

See Also	Example	Specifics

You tried to set a bookmark to an invalid string.

This error can occur in Visual Basic if you set the Bookmark property to a string that wasn't saved from previously reading a Bookmark property.  For example, the following code produces this error:

Sub MyFunction

Dim MyDB As Database, MySet As Dynaset

Dim Placeholder As String

Set MyDB = CurrentDB( )

Set MySet = MyDB.CreateDynaset("Employees")

Placeholder = "1"

MySet.Bookmark = Placeholder	' Not a valid bookmark.

End Sub


Table isn't open. (Error 3160)

See Also	Example	Specifics

You tried to perform an operation on a table that hasn't been opened.  Open the table, and then try the operation again.


Couldn't decrypt file. (Error 3161)

See Also	Example	Specifics

You tried to access an encrypted Btrieve or Paradox table, but the password you provided isn't correct.  Try the operation again by entering the correct password.


Null is invalid. (Error 3162)

See Also	Example	Specifics

You tried to assign the Null value to a variable that isn't a Variant data type.  Use the Dim statement to declare the variable as a Variant, and then try the operation again.


Couldn't insert or paste; data too long for field. (Error 3163)

See Also	Example	Specifics

The field into which you tried to insert or paste data isn't large enough to hold the it.  Try inserting or pasting less data.


Couldn't update field. (Error 3164)

See Also	Example	Specifics

Possible causes:

You tried to update a field in a record or table that is currently locked by another user.  Wait for the other user to finish working with the record or table, and then try the operation again.

You tried to change the value of a control whose Locked property is set to Yes.

In some cases this problem may be caused by not having included SHARE.EXE /L:500 in your AUTOEXEC.BAT file.  This application enables file sharing and locking for MS-DOS operating systems and indicates that up to 500 locks are permitted.

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Using a text editor, add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The exact number of locks you use depends on the applications you run and the number of files that are locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	If you added SHARE.EXE to your AUTOEXEC.BAT file, reboot your system.

4.	Restart Microsoft Windows, and try the operation again.


Couldn't open .INF file. (Error 3165)

See Also	Example	Specifics

You tried to attach a dBASE table, but Microsoft Visual Basic couldn't open or create the associated .INF file that contains index information about that table.

Possible causes:

There isn't enough disk space available to create the .INF file.

In a network environment, you don't have write privileges for the network drive.


Missing memo file. (Error 3166)

See Also	Example	Specifics

You tried to access a dBASE (.DBF) file, but the file's associated memo (.DBT) file couldn't be found.  Make sure the .DBT file is in the same directory as the .DBF file, and then try the operation again.


Record is deleted. (Error 3167)

See Also	Example	Specifics

You referred to a record that you deleted or that another user in a multiuser environment deleted.  Move to another record, and then try the operation again.


Invalid .INF file. (Error 3168)

See Also	Example	Specifics

You tried to access a dBASE table, but its associated .INF file is invalid or has become corrupted.  Reattach the table, making sure you specify the correct indexes.


Illegal type in expression. (Error 3169)

See Also	Example	Specifics

You tried to execute an SQL statement that contains a field that has an invalid field data type.

Possible causes:

You included a Memo or Long Binary field in an expression where it isn't allowed.

You included a numeric aggregate function, such as Sum or StDev, that tried to perform a calculation on a Text field.  Choose a different aggregate function.


Couldn't find installable ISAM. (Error 3170)

See Also	Example	Specifics

An installable ISAM's DLL file couldn't be found.  This file is required for attaching external tables (other than ODBC, Visual Basic/Microsoft Jet database tables).  The locations for all IISAM drivers are maintained in the Windows registration database (REG.DAT).  These entries are created automatically when you install Visual Basic or your application.  If you change the location of these drivers, you need to correct your application setup program to reflect this change and make the correct entries in REG.DAT.

Possible causes:

An entry in the registration database (REG.DAT) isn't valid.  For example, this error occurs if you're using a Paradox external database, and the Paradox entry points to a nonexistent directory or driver.  Exit the application, correct the registration database, and try the operation again.

One of the entries in the registration database (REG.DAT) points to a network drive and that network isn't connected.  Make sure the network is available, and then try the operation again.


Couldn't find net path or user name. (Error 3171)

See Also	Example	Specifics

One or more entries in the [Paradox ISAM] section of your .INI file is invalid.  Using Microsoft Windows Notepad or another text editor, correct the invalid entries, and then try the operation again.


Couldn't open PARADOX.NET. (Error 3172)

See Also	Example	Specifics

Possible causes:

The ParadoxNetPath entry in the [Paradox ISAM] section of the .INI file isn't valid.  This error occurs if you're using the Paradox external database, and the Paradox entry points to a nonexistent directory.  Exit the application, correct the invalid entry using Microsoft Windows Notepad or another text editor, and try the operation again.

The ParadoxNetPath entry in the [Paradox ISAM] section of the .INI file points to a network drive, and that network drive isn't connected.  Make sure the network drive is available, and then try the operation again.


Couldn't open table 'MSysAccounts' in SYSTEM.MDA. (Error 3173)

See Also	Example	Specifics

This operation requires the SYSTEM.MDA file, which contains the security and option settings for Microsoft Jet database tables.

Possible causes:

The SystemDB entry in the [Options] section of the .INI file points to a network drive that isn't connected.  Make sure the network drive is available, and then try the operation again.

The SYSTEM.MDA file is corrupted.  If you have a backup copy of SYSTEM.MDA, copy it to the location specified in the SystemDB entry in the [Options] section of the .INI file.


Couldn't open table 'MSysGroups' in SYSTEM.MDA. (Error 3174)

See Also	Example	Specifics

This operation requires the SYSTEM.MDA file, which contains the security and option settings for Microsoft Jet database tables.

Possible causes:

The SystemDB entry in the [Options] section of the .INI file points to a network drive that isn't connected.  Make sure the network drive is available, and then try the operation again.

The SYSTEM.MDA file is corrupted.  If you have a backup copy of SYSTEM.MDA, copy it to the location specified in the SystemDB entry in the [Options] section of the .INI file.


Date is out of range or is in an invalid format. (Error 3175)

See Also	Example	Specifics

Only dates from January 1, 100, through December 31, 9999 are recognized.

Possible causes:

You entered a date that was outside the valid range.

You entered a valid date, but it wasn't in a recognized format.  Make sure you entered it correctly, and then try the operation again.


Couldn't open file 'Item'. (Error 3176)

See Also	Example	Specifics

The specified text or spreadsheet file couldn't be opened.  The specified file specification may be invalid, another user may be accessing the file, or you may not have read privileges for the file.  Wait for the other user to finish using the file and then try the operation again, or contact your system administrator or network administrator.


Not a valid table name. (Error 3177)

See Also	Example	Specifics

The name you entered doesn't follow standard naming conventions.  Enter a new name, and then try the operation again.


Out of memory. (Error 3178)

See Also	Example	Specifics

Visual Basic doesn't  have enough memory to complete the operation.  Make sure you have enough RAM and a virtual swap file established.  You may need to terminate other programs, remove desktop wallpaper bitmaps, or remove unneeded TSR programs or device drivers to recover enough memory.


Encountered unexpected end of file. (Error 3179)

See Also	Example	Specifics

You tried to import a file that contains an end-of-file marker in an unexpected position.

Possible causes:

The import file is corrupted.  Restore a backup copy of the import file, and then try the operation again.

The import/export specifications you're using don't match the data in the import file.  Edit the import/export specifications, and then try the operation again.


Couldn't write to file 'Item'. (Error 3180)

See Also	Example	Specifics

You tried to export data to the specified text or spreadsheet file, but the file couldn't be modified.

Possible causes:

Another user is currently accessing the file.  Wait for the other user to finish using the file and then try the operation again.

The file has been defined as read-only in the operating system or by your network.  Resolve the read-only condition and then try the operation again.

In a network environment, you don't have write privileges for the file.

You may need to contact your system administrator or network administrator.


Invalid range. (Error 3181)

See Also	Example	Specifics

You attempted to import an invalid range of spreadsheet cells  This error should never occur in Visual Basic, since importing of spreadsheets isn't supported.


Invalid file format. (Error 3182)

See Also	Example	Specifics

Possible causes:

The file you tried to read or attach is corrupted.  Restore a backup copy of the file to your disk, and then try the operation again.

Visual Basic can't recognize the file format.  If the file is a Btrieve, dBASE, or Paradox file, run Setup to install the installable ISAM, and then attach the file.


Not enough space on temporary disk. (Error 3183)

See Also	Example	Specifics

You tried to perform an operation that requires more space than is available on the temporary disk.  Your temporary disk location is based on the TEMP DOS environment variable, which was set when your system started.

For example, you may be trying to create a query that creates temporary files larger than the temporary disk.  Reduce the size of the temporary files by accessing smaller amounts of data at one time or increase the size of the temporary disk.

You can increase the amount of available temporary disk space in several ways:

Select fewer records.  Dynaset-type and snapshot-type Recordset objects record keys and data to the temporary disk.

Select a different drive for your temporary disk.

If the temporary disk is a RAM disk, increase the size of the disk or move it to a fixed disk.

Free some space by deleting data or by removing unneeded tables, queries, forms, macros, and modules from your database.

Free some space by compressing deleted records out of your database.

If you still need additional space, consider removing other unused files from your disk.


Couldn't execute query; couldn't find linked table. (Error 3184)

See Also	Example	Specifics

Possible causes:

The attached table no longer exists or has been renamed or moved.  Reattach the table and then try to execute the query again.

The attached table is on a network drive and the network isn't connected.  Make sure the network is available, and then try to execute the query again.


SELECT INTO remote database tried to produce too many fields. (Error 3185)

See Also	Example	Specifics

The Microsoft Jet database supports up to 255 fields per table, but the other database supports fewer fields.  A SELECT...INTO statement created a table with more fields than the remote database can support.  Reduce the number of columns produced by the SELECT INTO statement, and then try the operation again.


Couldn't save; currently locked by user 'Item2' on machine 'Item1'. (Error 3186)

See Also	Example	Specifics

Possible causes:

You tried to save a record on a 2K database page that is currently locked by another user.  Wait for the other user to finish working with the record, and then try the operation again.

The MS-DOS file-sharing count has been exceeded.  You need to increase the number of locks installed with SHARE.EXE.  (Microsoft Windows for Workgroups operating systems don't require SHARE.EXE because file sharing is handled internally.)

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Using a text editor, add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The exact number of locks you use depends on the applications you run and the number of files that are locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	If you added SHARE.EXE to your AUTOEXEC.BAT file, reboot your system.

4.	Restart Microsoft Windows, and try the operation again.


Couldn't read; currently locked by user 'Item2' on machine 'Item1'. (Error 3187)

See Also	Example	Specifics

You tried to read information on a database page that is currently locked by the specified user.  Wait for the other user to finish, and then try the operation again.


Couldn't update; currently locked by another session on this machine. (Error 3188)

See Also	Example	Specifics

You tried to update information that is currently locked by another session.  Wait for the other session to finish or close the other session, and then try the operation again.


Table 'Item1' is exclusively locked by user 'Item3' on machine 'Item2'. (Error 3189)

See Also	Example	Specifics

You can't access the specified table because it is exclusively locked by another user.  Wait for the other user to release the lock, then try the operation again.


Too many fields defined. (Error 3190)

See Also	Example	Specifics

You tried to perform an operation that involves more than 255 fields.  Reduce the number of fields, and then try the operation again.


Can't define field more than once. (Error 3191)

See Also	Example	Specifics

You tried to create a table in which more than one field was defined with the same name.  Each field name in a table must be unique.


Couldn't find output table 'Item'. (Error 3192)

See Also	Example	Specifics

You tried to use an INSERT INTO statement with the specified table, which doesn't exist.  Make sure you entered the name correctly, and then try the operation again.


No UserName. (Error 3193)

See Also	Example	Specifics

For security purposes, the operation you attempted requires a valid user name.


No machine name. (Error 3194)

See Also	Example	Specifics

Visual Basic or the Microsoft Jet database engine couldn't determine the name assigned to your computer as registered on the network.


Couldn't use 'Item'; database already in use. (Error 3196)

See Also	Example	Specifics

The specified database is currently being used by another user or session.  Wait for the other user or session to finish working with the database, and then try the operation again.


Data has changed; operation stopped. (Error 3197)

See Also	Example	Specifics

This error can occur in a multiuser environment.

Another user has changed the data you are trying to update.  This error can occur in Visual Basic when multiple users open a table or create a dynaset and use optimistic locking.  Between the time you used the Edit method and the Update method, another user changed the same data.

To overwrite the other user's changes with your own, execute the Update method again.


Couldn't start session.  Too many sessions already active. (Error 3198)

See Also	Example	Specifics

You tried to perform an operation that would have started a new session, but too many sessions are already active.  Wait for one or more sessions to finish, and then try the operation again.


Couldn't find reference. (Error 3199)

See Also	Example	Specifics

You entered a file, table, or field reference that couldn't be found.  Check the spelling and punctuation to make sure you entered the reference correctly, and then try the operation again.


Can't delete or change record. Related records exist in table 'Item' that would violate referential integrity. (Error 3200)
Can't delete or change record. Related records exist in table 'Item' that violate referential integrity. (Error 3200)

See Also	Example	Specifics

You tried to perform an operation that would have violated referential integrity rules for related tables.  For example, this error occurs if you try to delete or change a record in the "one" table in a one-to-many relationship when there are related records in the "many" table.

If you want to delete or change the record, first delete the related records from the "many" table.


Can't add or change record.  Referential integrity rules require a related record in table 'Item'. (Error 3201)

See Also	Example	Specifics

You tried to perform an operation that would have violated referential integrity rules for related tables.  For example, this error occurs if you try to change or insert a record in the "many" table in a one-to-many relationship, and that record doesn't have a related record in the table on the "one" side.

If you want to add or change the record, first add a record to the "one" table that contains the same value for the matching field.


Couldn't save; currently locked by user 'Item2' on machine 'Item1'. (Error 3202)

See Also	Example	Specifics

Possible causes:

You tried to save a record on a 2K database page that is currently locked by another user.  Wait for the other user to finish working with the record, and then try the operation again.

The MS-DOS file-sharing count has been exceeded.  You need to increase the number of locks installed with SHARE.EXE.  (Microsoft Windows for Workgroups operating systems don't require SHARE.EXE because file sharing is handled internally.)

To load SHARE.EXE

1.	Exit Microsoft Windows.

2.	Using a text editor, add the following line to your AUTOEXEC.BAT file:

SHARE.EXE /L:500

If you don't have an AUTOEXEC.BAT file on your system, enter the preceding line at the command prompt before you start Microsoft Windows.  The exact number of locks you use depends on the applications you run and the number of files that are locked at any given time.  If other applications require file locks, you may need to specify more than 500 locks.

3.	If you added SHARE.EXE to your AUTOEXEC.BAT file, reboot your system.

4.	Restart Microsoft Windows, and try the operation again.


Can't specify subquery in expression (Item). (Error 3203)

See Also	Example	Specifics

The specified expression contains a subquery or other expression that functions as a subquery.

Possible cause:

You used a SELECT statement that includes an aggregate function that evaluates another aggregate function.  This error occurs, for example, if you execute the following statement:

TRANSFORM Sum([OrderAmount]) AS Sum1

SELECT Sum([Sum1]) AS Sum2, [Order ID], Sum([Sum2]) AS Expr1

FROM Orders

GROUP BY [Order ID]

PIVOT [Ship Name];


Database already exists. (Error 3204)

See Also	Example	Specifics

You tried to create or rename a database using a name that already exists.  Enter a different name, and then try the operation again.


Too many crosstab column headers (Item). (Error 3205)

See Also	Example	Specifics

You executed an SQL statement that tried to create too many columns.  The specified value is the column that produced this error.

You can reduce the number of columns by adding additional conditions to the WHERE clause or, if there is no WHERE clause, add one.


Can't create a relationship between a field and itself. (Error 3206)

See Also	Example	Specifics

You tried to create a relationship between a field and itself.  Choose a different field for the primary or related table, and then try the operation again.


Operation not supported on Paradox table with no primary key. (Error 3207)

See Also	Example	Specifics

Run the application that created the table, and add a primary key.  Then, try the operation again.


Invalid Deleted entry in [dBASE ISAM] section in INI file. (Error 3208)

See Also	Example	Specifics

To complete this operation

1.	Exit Visual Basic.

2.	Using Microsoft Windows Notepad or another text editor, correct the Deleted entry in the [dBASE ISAM] section of the .INI file.

3.	Restart Visual Basic, and then try the operation again.


Invalid Stats entry in [dBASE ISAM] section in INI file. (Error 3209)

See Also	Example	Specifics

To complete this operation

1.	Exit Visual Basic.

2.	Using Microsoft Windows Notepad or another text editor, correct the Stats entry in the [dBASE ISAM] section of the .INI file.

3.	Restart Visual Basic, and then try the operation again.


Connect string too long. (Error 3210)

See Also	Example	Specifics

The connect string in the IN clause of an SQL statement can't be longer than 255 characters.  Correct your entry, and then try the operation again.


Couldn't lock table 'Item'; currently in use. (Error 3211)

See Also	Example	Specifics

To complete this operation, a table currently in use by another user must be locked.  Wait for the other user to finish working with the table, and then try the operation again.


Couldn't lock table 'Item1'; currently in use by user 'Item3' on machine 'Item2'. (Error 3212)

See Also	Example	Specifics

The table can't be locked because it is currently in use.  Wait for the other user's transaction to complete, then try the operation again.


Invalid Date entry in [dBASE ISAM] section in INI file. (Error 3213)

See Also	Example	Specifics

To complete this operation

1.	Exit Visual Basic.

2.	Using Microsoft Windows Notepad or another text editor, correct the Date entry in the [dBASE ISAM] section of the .INI file.

3.	Restart Visual Basic, and then try the operation again.


Invalid Mark entry in [dBASE ISAM] section in INI file. (Error 3214)

See Also	Example	Specifics

To complete this operation

1.	Exit Visual Basic.

2.	Using Microsoft Windows Notepad or another text editor, correct the Mark entry in the [dBASE ISAM] section of the .INI file.

3.	Restart Visual Basic, and then try the operation again.


Too many Btrieve tasks. (Error 3215)

See Also	Example	Specifics

Too many applications are using the Btrieve driver.  In a multiuser environment, this error can occur when too many users access the same server.  Contact your system administrator or network administrator.


Parameter 'Item' specified where a table name is required. (Error 3216)

See Also	Example	Specifics

You created a parameter query that specifies an invalid parameter type.  The following example produces this error.

PARAMETERS Param1 Text;

INSERT INTO Param1

SELECT *

FROM Customers;

Param1 is a text parameter, but the INSERT INTO statement expects a table name.

Change the parameter type from Text to TableID, and then try the operation again.


Parameter 'Item' specified where a database name is required. (Error 3217)

See Also	Example	Specifics

You created a parameter query that specifies an invalid parameter type.  The following example produces this error:

PARAMETERS Param1 Text;

SELECT [Customer ID]

FROM Customers IN Param1;

Param1 is a text parameter, but the FROM clause requires a database parameter.

Change the parameter type from Text to Database, and then try the operation again.


Couldn't update; currently locked. (Error 3218)

See Also	Example	Specifics

You tried to update data that is located on a page that is currently locked.

Possible causes:

You tried to save a query that is being used by someone else.  To save your query, wait for the other user to finish or enter a different name, and then try the operation again.

You tried to use the Edit method on a data page containing a record that is already open or locked.


Invalid Operation. (Error 3219)

See Also	Example	Specifics

Possible causes:

You tried to write to a read-only property.  See the Help topic for the property to determine whether it is read/write.

You tried to use a method or property on a type of Recordset object that the method or property doesn't apply to.  See the Recordset Object, Recordsets Collection topic to determine which methods and properties apply to a given type of Recordset object.

You tried to append a property to a Properties collection of an object that doesn't support user-defined properties.


Wrong Paradox sort sequence. (Error 3220)

See Also	Example	Specifics

You tried to attach a Paradox table that was created with an international sort order that isn't the same as the one you are using.


Invalid entries in [Btrieve ISAM] section in WIN.INI. (Error 3221)

See Also	Example	Specifics

An entry in the [Btrieve] section of WIN.INI isn't valid.  For example, this error occurs if the /l: or /f: settings in the options entry are invalid.  Exit the application, correct any invalid entries using Microsoft Windows Notepad or another text editor, and then restart the application to try the operation again.


Query can't contain a Database parameter. (Error 3222)

See Also	Example	Specifics

Change the parameter field data type for this parameter query to a valid field data type and then try the operation again.


'Item' isn't a valid parameter name. (Error 3223)

See Also	Example	Specifics

The parameter name is longer than 64 characters or contains invalid characters.  Correct the name, and then try the operation again.


Btrieve [image] data dictionary is corrupted. (Error 3224)

See Also	Example	Specifics

Restore a backup copy of the DDF file, and then try the operation again.


Encountered record locking deadlock while performing Btrieve operation. (Error 3225)

See Also	Example	Specifics

You tried to lock a record during an update, insert, or delete operation on an attached Btrieve table, and another user is also trying to lock the same record.  Cancel the operation, wait for the other user to finish, and then try the operation again.


Errors encountered while using the Btrieve DLL. (Error 3226)

See Also	Example	Specifics

An unexpected error occurred when you tried to access data in an attached Btrieve table.  Try the operation again, or contact your system administrator or network administrator.


Invalid Century entry in [dBASE ISAM] section in INI file. (Error 3227)

See Also	Example	Specifics

To complete this operation

1.	Exit Visual Basic.

2.	Using Microsoft Windows Notepad or another text editor, correct the Century entry in the [dBASE ISAM] section of the .INI file.

3.	Restart Visual Basic, and then try the operation again.


Invalid CollatingSequence entry in [Paradox ISAM] section in INI file. (Error 3228)

See Also	Example	Specifics

You have an incorrect value for the Collating Sequence entry of the .INI file.

To complete this operation

1.	Exit the application.

2.	Use Microsoft Windows Notepad or another text editor to change the CollatingSequence entry in the [Paradox ISAM] section of the .INI file to either ASCII or International.

3.	Restart the application, and then try the operation again.


Btrieve [image] can't change field. (Error 3229)

See Also	Example	Specifics

You tried to update a field in a Btrieve table that is part of an index that can't be modified.  Use Novell Xtrieve or another program to change the attribute of the index that can't be modified, and then try the operation again.


Out-of-date Paradox lock file. (Error 3230)

See Also	Example	Specifics

You tried to use a Paradox table, but the table's associated lock (.LCK) file is outdated.  Delete the .LCK file and then try the operation again.


ODBC [image] field would be too long; data truncated. (Error 3231)

See Also	Example	Specifics

You tried to perform an ODBC operation that would have resulted in a field that is too long.  The data has been truncated to the maximum allowable length.


ODBC [image] couldn't create table. (Error 3232)

See Also	Example	Specifics

You tried to export a table to an SQL database and the table couldn't be created.  This error can occur if the SQL database is read-only, or you don't have permission to create a table in that database.  Resolve the read-only condition, or see your system administrator or the person who created the database to obtain the necessary permissions.


ODBC [image] incorrect driver version. (Error 3233)

See Also	Example	Specifics

You tried to perform an ODBC operation that requires a different driver.  Reinstall the ODBC driver, and then try the operation again.


ODBC [image] remote query timeout expired. (Error 3234)

See Also	Example	Specifics

The ODBC server may not be properly installed, or a required network connection isn't active.  Check the network connection or contact your system administrator, and then try the operation again.


ODBC [image] data type not supported on server. (Error 3235)

See Also	Example	Specifics

The ODBC server doesn't support the same SQL data types as Visual Basic.  The data has not been placed on the server.


ODBC [image] encountered unexpected Null value. (Error 3236)

See Also	Example	Specifics

Using ODBC, you tried to read data from an SQL database, and that data contains a Null value in an unexpected position.

This error can occur if the data is corrupted.  Restore a backup copy of the SQL database or table, and then try the operation again.


ODBC [image] unexpected type. (Error 3237)

See Also	Example	Specifics

Using ODBC, you tried to read from or write to an SQL database or table, and the field data types aren't compatible.  This error can occur if the data types don't match or if the data has become corrupted.


ODBC [image] data out of range. (Error 3238)

See Also	Example	Specifics

Using ODBC, you tried to read from or write to an SQL database, and the data isn't within the prescribed limits.


Too many active users. (Error 3239)

See Also	Example	Specifics

In a multiuser environment, Microsoft Jet databases support up to 255 concurrent users.  Wait for one or more users to stop using the system, and then try the operation again.


Btrieve [image] missing WBTRCALL.DLL. (Error 3240)

See Also	Example	Specifics

You tried to perform an operation that requires the specified file.  To use data access to read and write data to a Novell Btrieve file, you must have a copy of the stand-alone Btrieve for Windows file: WBTRCALL.DLL (about 52K in size).  This file must be in your \WINDOWS\SYSTEM directory.

You may already have a copy of this file on your hard drive.  To find it, at the root directory type:

dir WBTRCALL.DLL /s

Copy this file to your \WINDOWS\SYSTEM directory.

Important   If you already have a copy of WBTRCALL.DLL in your \WINDOWS\SYSTEM directory, contact your system administrator before copying over it.  This file may be used by other programs on your computer.

If you don't have a copy of this file, you can purchase Btrieve for Windows from Novell Inc. by calling 800-453-1267 or by contacting your local software dealer.


Btrieve [image] out of resources. (Error 3241)

See Also	Example	Specifics

While working with a Btrieve file, Visual Basic ran out of resources.  Exit Visual Basic and use Microsoft Windows Notepad or another text editor to increase one or more of the settings in the Options entry of the [Btrieve] section in your WIN.INI file.  Then restart Visual Basic and try the operation again.

Visual Basic requires the following minimum values:

[Btrieve]

Options=/m:38 /p:4096 /b:16 /f:4 /l:8 /n:4 /t:<pathname>

For more information, refer to your Btrieve documentation.


Invalid reference in SELECT statement. (Error 3242)

See Also	Example	Specifics

You entered an invalid field or table reference in the SELECT statement.


None of the import field names match fields in the appended table. (Error 3243)

See Also	Example	Specifics

At least one field name in the import table and the appended table must match.


Can't import password-protected spreadsheet. (Error 3244)

See Also	Example	Specifics

Return to the application that was used to save the spreadsheet, save the spreadsheet again without a password, and then try to import the spreadsheet again.


Couldn't parse field names from first row of import table. (Error 3245)

See Also	Example	Specifics

The first row of data contains invalid field names, such as quoted and unquoted strings in the same field name.  In the following example, the third and fourth field names can't be parsed:

"Name", Date, "ID " Number, Phone" Number"

The first two fields are valid, but the third and fourth aren't because they contain nonspace characters outside of the quotation marks.

Check the import table for properly matched quotation marks, then try the import operation again.


Operation not supported in transactions. (Error 3246)

See Also	Example	Specifics

You tried to perform an operation that isn't valid within a transaction.  A transaction can be one you create using a BeginTrans, CommitTrans, Rollback statements, or an internal transaction created by The Microsoft Jet database engine, as when you delete multiple records in a single operation.


ODBC [image] linked table definition has changed. (Error 3247)

See Also	Example	Specifics

The definition or structure of an attached table changed since you created the link.  Delete the link, and then reattach the table.

This error shouldn't occur in Visual Basic, because importing/attaching tables isn't supported.


Invalid NetworkAccess entry in INI file. (Error 3248)

See Also	Example	Specifics

To complete this operation

1.	Exit the application.

2.	Using Microsoft Windows Notepad or another text editor, correct the NetworkAccess entry in your .INI file.  The entry must be either ON or OFF.

Depending on which installable ISAM you're trying to use, the invalid entry is in the [Btrieve], [dBASE ISAM], or [Paradox ISAM] section.

3.	Restart your application, and then try the operation again.


Invalid PageTimeout entry in INI file. (Error 3249)

See Also	Example	Specifics

To complete this operation

1.	Exit the application.

2.	Using Microsoft Windows Notepad or another text editor, correct the NetworkAccess entry in your .INI file.  The entry must be either ON or OFF.

Depending on which installable ISAM you're trying to use, the invalid entry is in the [Btrieve], [dBASE ISAM], or [Paradox ISAM] section.

3.	Restart your application, and then try the operation again.


Couldn't build key. (Error 3250)

See Also	Example	Specifics

When building a primary index, the Microsoft Jet database engine couldn't build a primary key.  Make sure the key fields are named properly and that there are no duplicate records based on this key.


Feature not available. (Error 3251)

See Also	Example	Specifics

You were attempting to execute a method or assign a value to a property that is generically valid for the object, but isn't supported in this specific instance.  For example, the Edit method is generally valid for Recordset objects, but not for a snapshot-type Recordset.  This error could also occur in cases where the operation isn't permitted due to the type or status of the object [image] as when trying to use the MovePrevious method on a forward-only scrolling snapshot-type Recordset.


Illegal reentrancy during query execution. (Error 3252)

See Also	Example	Specifics

This error can occur if you execute a query that includes a user-defined function in its output and then create a form based on that query.


ODBC [image] Can't lock all records. (Error 3254)

See Also	Example	Specifics

Using ODBC, you tried to lock all of the records in an SQL database.


ODBC [image] Can't change connect string parameter. (Error 3255)

See Also	Example	Specifics

Using ODBC, you tried to change a connect string parameter other than the Login ID or Password.  If you need to change one of the other parameters, you must delete and then reattach the table.


Index file not found. (Error 3256)

See Also	Example	Specifics

You tried to access a dBASE table, but one of the indexes listed in the table's associated .INF file couldn't be found.  The index may have been renamed, moved, or deleted.  Either reattach the table, or use Microsoft Windows Notepad or another text editor to update the .INF file.


Syntax error in WITH OWNERACCESS OPTION declaration. (Error 3257)

See Also	Example	Specifics

Possible causes:

The WITH OWNERACCESS OPTION declaration is incomplete or includes a space between OWNER and ACCESS.

The declaration appears in an unexpected and disallowed position in the SQL statement.  For example:

SELECT * WITH OWNERACCESS OPTION FROM [My Table];

The WITH OWNERACCESS OPTION declaration should appear at the end of the SQL statement, usually after the ORDER BY clause, if present:

SELECT * FROM [My Table] WITH OWNERACCESS OPTION;


Query contains ambiguous (outer) joins. (Error 3258)

See Also	Example	Specifics

You tried to execute an SQL statement that contains multiple joins; the results of the query can differ depending on the order in which the joins are performed.  For example, this error can occur if you execute the following SQL statement:

SELECT * FROM Customers, Orders, [Order Details],

Customers LEFT JOIN Orders

ON Customers.[Customer ID] = Orders.[Customer ID],

Orders INNER JOIN [Order Details]

ON Orders.[Order ID] = [Order Details].[Order ID];

Executing this statement produces an error because the order of the joins is ambiguous.  To force one of the joins to be performed first, create a separate query that performs the first join and then include that query in your SQL statement.  The following queries illustrate how you might construct the preceding query so that the INNER JOIN operation is performed before the LEFT JOIN and RIGHT JOIN operation:

Query1

SELECT * FROM Orders, [Order Details],

Orders INNER JOIN [Order Details]

ON Orders.[Order ID] = [Order Details].[Order ID];

Query2

SELECT * FROM Customers, Query1,

Customers LEFT JOIN Query1

ON Customers.[Customer ID] = Orders.[Customer ID];


Invalid field data type. (Error 3259)

See Also	Example	Specifics

The data type specified in the Field object Type property isn't valid.  Choose one of the valid types as shown in the Type property Help topic.


Couldn't update; currently locked by user 'Item2' on machine 'Item1'. (Error 3260)

See Also	Example	Specifics

You tried to update data that is located on a page that is currently locked.

Possible causes:

You tried to save a query being used by someone else.  To save your query, wait for the other user to finish or enter a different name, and then try the operation again.

You tried to use the Edit method on a data page containing a record that is already open or locked.


Item (Error 3261)

See Also	Example	Specifics

You tried to use a table that is currently open for exclusive access by the specified user.  Wait for the other user to finish working with the table, and then try the operation again.


Table in use. (Error 3262)

See Also	Example	Specifics

You tried to lock a table while opening it, but the table can't be locked because it is currently in use.  Wait a moment, and then try the operation again.


Invalid database object. (Error 3263)

See Also	Example	Specifics

The Database object specified isn't the result of the OpenDatabase method, or it has been modified and is no longer valid.


No fields defined - cannot append table (Error 3264)

See Also	Example	Specifics

You can't append a table until you define one or more fields.  Use the CreateField method to create fields, append them to your TableDef object, and then append the TableDef object to the TableDefs collection.


Name not found in this collection. (Error 3265)

See Also	Example	Specifics

An attempt to reference a name in a collection failed.

Possible causes:

The object doesn't exist in this collection.  Make sure the object is appended to a collection before referencing it.

There is more than one object with this name in the collection; using its name is an ambiguous reference.  Reference the object by its ordinal position in the collection (for example, Recordsets(3)).


Append illegal - field is part of a TableDefs collection. (Error 3266).
Append illegal - field is part of a TableDefs collection (Error 3266).

See Also	Example	Specifics

A Field object was specified as an argument to an Append operation when it already is a member of an existing Fields collection.  Use the Dim statement to declare a new Field object, specify its values and retry the operation with the new Field object.


Property can be set only when the field is part of a Recordset object's Fields collection. (Error 3267)

See Also	Example	Specifics

This property is valid only for Field objects that are part of a Recordset object's Fields collection or part of a Table, Dynaset or Snapshot object.  See the Fields collection Summary topic for a list of properties available for different Fields collections.


Cannot set the property of an object once it is part of a collection. (Error 3268)

See Also	Example	Specifics

An attempt was made to change the value of a property of an object (TableDef, Field, and so on) that is a part of an open Database object.


Append illegal - Index is part of a TableDefs collection. (Error 3269)
Append illegal - Index is part of a TableDefs collection (Error 3269)

See Also	Example	Specifics

An Index object was specified as an argument to an Append operation when it already is a member of an existing Indexes collection.  Use the Dim statement to declare a new Index object, specify its values and retry the operation with the new Index object.


Property not found. (Error 3270)

See Also	Example	Specifics

The specified property couldn't be found.

Possible causes:

The property doesn't exist.  Check the spelling of the property in your code.

If the property is user-defined, it may have been deleted from the collection.


Invalid property value. (Error 3271)

See Also	Example	Specifics

Possible causes:

The setting for the Value property of the Parameter object is too long or is otherwise incorrect.

The Index object name is a zero-length string [" "].  You must enter a name for the Index object when appending the object to the Indexes collection.

The Workspace object name is a zero-length string.  You must enter a name for the Workspace object when appending the object to a Workspaces collection.


Object isn't a collection. (Error 3272)

See Also	Example	Specifics

You've referred to an object as though it were a collection.  For example, a statement such as MyQuery.Refresh or MyQuery(2) causes this error.


Method not applicable for this object. (Error 3273)

See Also	Example	Specifics

You tried to use a method on an object that doesn't support that method.  Refer to the Summary topic for the object to see a list of valid methods for that object.


External table isn't in the expected format. (Error 3274)

See Also	Example	Specifics

The format of the table has changed since it was attached.  Attach the table again, then retry the operation.


Unexpected error from external database driver (Item). (Error 3275)

See Also	Example	Specifics

The external database driver (as specified) returned an error.  This error can be caused by performing an operation not supported on this type of external database.


Invalid database ID. (Error 3276)

See Also	Example	Specifics

The Database object specified isn't the result of the OpenDatabase method, or it has been modified and is no longer valid.


Can't have more than 10 fields in an index. (Error 3277)

See Also	Example	Specifics

You defined an index with more than ten fields.  Reduce the number of fields to ten or less.


Database engine has not been initialized. (Error 3278)

See Also	Example	Specifics

Visual Basic can't initialize the database engine.

Possible causes:

There is a conflict with another application that uses the Microsoft Jet database engine.  Quit all other applications, and then restart your application.

An error occurred during installation and setup.  Reinstall Visual Basic.


Database engine has already been initialized. (Error 3279)

See Also	Example	Specifics

You attempted to initialize the data access engine, but it has already been initialized.


Can't delete a field that is part of an index. (Error 3280)

See Also	Example	Specifics

To delete a field that is part of an index, you must first delete the index.


Can't delete this index.  It is either the current index or is used in a relationship. (Error 3281)

See Also	Example	Specifics

If the index is used in a relationship, you must delete the relationship before you can delete the index.  If the index is specified as the current index by the Index property, you must set the property to a different index before you can delete the index.


Can't define field or index in a table that contains data. (Error 3282)

See Also	Example	Specifics

In Visual Basic, you can't add a field or create an index on an attached table that contains data.  Once a table is populated with data, you can't change the table design or indexes.  Create a new table with the altered design and transfer the data to it using an action query.


Primary key already exists. (Error 3283)

See Also	Example	Specifics

You're attempting to define a second primary key for this table.  Each table can have only one primary key.  Remove the reference to the second primary key.


Index already exists. (Error 3284)

See Also	Example	Specifics

You can't have two indexes with the same name in a table.  Rename one of the indexes.


Invalid index definition. (Error 3285)

See Also	Example	Specifics

Possible causes:

You're using the same column twice in an index or relationship, which the Microsoft Jet database engine doesn't permit.

You're creating a relationship using columns with data types that don't match.  In Jet databases, you can only relate columns with identical data types or a Counter column with a Number column set to a Long Integer.


Format of memo file doesn't match specified external database format. (Error 3286)

See Also	Example	Specifics

Visual Basic can't read the memo file associated with the database you're trying to import or attach and consequently can't import or attach the file.  The memo file may be in the wrong format; for example, if you selected dBASE IV as the data source and the memo file is in a FoxPro format.


Can't create index on a one-byte field, Memo field or Long Binary field. (Error 3287)

See Also	Example	Specifics

You're trying to create an index on a Memo or OLE Object field.  Specify another field, and then try the operation again.

This can also occur if you try to create an index on a Btrieve table on a one byte field.


Paradox: No primary index. (Error 3288)

See Also	Example	Specifics

You are attempting to create an index on a Paradox table for which no other indexes are defined. The first index created on a Paradox table must be a primary index.

Possible solutions:

Redefine the index as the primary index.

If the index you're attempting to create isn't the primary index, create the primary index first.


Syntax error In CONSTRAINT Clause. (Error 3289)

See Also	Example	Specifics

You entered an SQL statement that includes an invalid CONSTRAINT clause.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in CREATE TABLE statement. (Error 3290)

See Also	Example	Specifics

You entered an SQL statement that includes an invalid CREATE TABLE statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in CREATE INDEX statement. (Error 3291)

See Also	Example	Specifics

You entered an SQL statement that includes an invalid CREATE INDEX statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in column definition. (Error 3292)

See Also	Example	Specifics

A syntax error occurred in the field definition of a CREATE TABLE or ALTER TABLE statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in ALTER TABLE statement. (Error 3293)

See Also	Example	Specifics

You entered an SQL statement that includes an invalid ALTER TABLE statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in DROP INDEX statement. (Error 3294)

See Also	Example	Specifics

You entered an SQL statement that has an invalid DROP INDEX statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Syntax error in DROP TABLE or DROP INDEX statement. (Error 3295)

See Also	Example	Specifics

You entered an SQL statement that has an invalid DROP Statement.

Possible causes:

A reserved word or argument name is misspelled or missing.

Punctuation is incorrect.


Join expression not supported. (Error 3296)

See Also	Example	Specifics

Possible causes:

Your SQL statement contains multiple joins in which the results of the query can differ, depending on the order in which the joins are performed.  You may want to create a separate query to perform the first join, and then include that query in your SQL statement.

The ON statement in your JOIN operation is incomplete or contains too many tables.  You may want to put your ON expression in a WHERE clause.


Couldn't import. No records found or all records contained errors. (Error 3298)

See Also	Example	Specifics


Several tables exist with that name; please specify owner, as in 'owner.table'. (Error 3298)

See Also	Example	Specifics

More than one table with that name exists in the remote ODBC database.  To resolve the ambiguity, specify the owner of the table you wish to access, using the owner.table syntax.


ODBC Specification Conformance Error (<message>).  This error should be reported to the ODBC driver vendor. (Error 3299)

See Also	Example	Specifics

This error can be caused by any of a number of problems with your ODBC driver.  Write down the error number indicated in the message and report it to your driver vendor.


Can't create a relationship. (Error 3300)

See Also	Example	Specifics

You are attempting to create a relationship that isn't allowed.  For example, the tables may be in different databases.


Can't perform this operation; features in this version are not available in databases with older formats. (Error 3301)

See Also	Example	Specifics

The database was stored in an earlier version of the Microsoft Jet database engine that doesn't support this feature.  The database needs to be converted to Jet version 2.0 format or this particular operation needs to be revised to avoid using the unsupported feature.


Can't change a rule while the rules for this table are in use. (Error 3302)

See Also	Example	Specifics

A record in this table has been changed by another user, or has been changed by you in a separate session of Visual Basic, and is currently locked.  You can't modify the rules in a table while a record in that table is locked.

If you have locked the record in a separate session, save the record, then make your changes.  If another user has locked the record, wait a little while, then save your rule modifications.


Can't delete this field.  It's part of one or more relationships. (Error 3303)

See Also	Example	Specifics

You're trying to delete a field for which relationships have been defined in the database.  To delete the field, you must first delete its relationships.


You must enter a personal identifier (PID) consisting of at least four and no more than 20 characters and digits. (Error 3304)

See Also	Example	Specifics

A personal identifier (PID) must be between at least 4 characters and no more than 20 characters long.


Invalid connection string in pass-through query. (Error 3305)

See Also	Example	Specifics

The connection string for a pass-through query doesn't begin with "ODBC;".


At most one field can be returned from a subquery that doesn't use the EXISTS keyword. (Error 3306)

See Also	Example	Specifics

You've written a subquery that can return more than one field without using the EXISTS reserved word in the main query's FROM clause.  Revise the SELECT statement of the subquery to request only one field.


The number of columns in the two selected tables or queries of a union query don't match. (Error 3307)

See Also	Example	Specifics

The two tables or queries joined by the UNION operation must output the same number of columns.  Remove columns from the SELECT statement that has too many columns or include more columns in the SELECT statement that has too few.

Tip   You may include constants instead of columns in the SELECT statement that has too few columns.  For example, the following union query outputs three columns from the first SELECT statement but one column and two constants in the second SELECT statement.  The query returns all countries in the Employees and Regions tables.  From the Employees table, the query also returns the first and last name of an employee.  If the country value is from the Regions table, however, the query returns Null in the First Name and Last Name columns.

SELECT [Country], [First Name], [Last Name] FROM [Employees]

UNION SELECT [Country], NULL, NULL FROM [Regions];


Invalid TOP argument in select query. (Error 3308)

See Also	Example	Specifics

An invalid parameter appeared in the TOP clause of a SELECT statement.  The value placed after the TOP reserved word must be a positive integer.  If the PERCENT reserved word is also used, the integer can't be greater than 100.


Property setting can't be larger than 2 KB. (Error 3309)

See Also	Example	Specifics

You are trying to set a property value of an object to a size greater than the largest permissible size of 2 kilobytes.  Shorten the length of the property value.


This property isn't supported for external data sources or for databases created in a previous Jet version. (Error 3310)

See Also	Example	Specifics

You attempted to set or check a property that isn't available for this object in a database stored in A Microsoft Jet database version 1.x or in an external data source.  Search for the object in Help, and then display the Summary topic for the object to see a list of its valid properties.


Property specified already exists. (Error 3311)

See Also	Example	Specifics

You tried to append a new Property object to a collection that contains a property of the same name.  Check to see whether you've misspelled the new Property object's Name property, or refer to the Help topic for the existing property of the same name to see whether you need to create a new Property object.


Validation rules and default values can't be placed on system tables nor on attached tables. (Error 3312)

See Also	Example	Specifics

You're trying to set the DefaultValue, ValidationRule, ValidationText, or Required property, on a table, field, or other object that is prohibited by Visual Basic.  For example, you're setting a property on a system object.


Can't place this validation expression on this field. (Error 3313)

See Also	Example	Specifics

You're trying to set validation properties on a field (such as a Counter or OLE field) that doesn't allow this type of property.  Use a different field to validate data or, if you have not added data to the table, redefine the data type for the field.


Field <name> can't contain a null value. (Error 3314)

See Also	Example	Specifics

The Required property for this field is set to Yes, prohibiting the entry of a Null in the field.  Enter a value in the field.


Field <name> can't be a zero-length string. (Error 3315)

See Also	Example	Specifics

The AllowZeroLength property for this field is set to No, prohibiting the entry of a zero-length string in the field.  Enter a different value in the field.


<Table-level validation text>. (Error 3316)

See Also	Example	Specifics

A table-level validation rule was violated.


One or more values entered is prohibited by the validation rule <rule> set for <name>. (Error 3317)

See Also	Example	Specifics

The ValidationRule property for this field contains an expression that limits the values that can be entered in the field.  You must enter a value that isn't prohibited by the expression.


Top not allowed in delete queries. (Error 3318)

See Also	Example	Specifics

Top values; that is, those specified in a TOP clause of a SELECT statement, aren't allowed in delete queries.


Syntax error in union query. (Error 3319)

See Also	Example	Specifics

There is a syntax error in a SQL string of the union query.

Possible causes:

A reserved word or argument name is misspelled.

A reserved word or argument is missing.

Punctuation is incorrect.


<Error> in table-level validation expression. (Error 3320)

See Also	Example	Specifics

An error occurred in a table-level validation rule expression or its default value expression.  This could be a syntax error or some other kind of error.


No database specified in connection string or IN clause. (Error 3321)

See Also	Example	Specifics

Microsoft Jet database engine is unable to connect to an external ISAM database because you haven't specified the name of the database to connect to.  When connecting to an external source of data, you must specify a database name.

Possible causes:

The connection string in the FROM clause of the SELECT statement is missing the parameter, DATABASE=.

The IN clause of the SELECT statement includes a database type argument (indicating to select the data from an external database) but it's missing a database name argument.


Crosstab query contains one or more invalid fixed column headings. (Error 3322)

See Also	Example	Specifics

The list of entries for a fixed column heading of a crosstab query (the PIVOT clause in a TRANSFORM statement) isn't valid.

Possible causes:

No entries in the list.  There must be at least one value in the parentheses following the IN reserved word in the PIVOT clause.

A blank entry appears in the list.  Two commas in a row (,,) create a blank entry.

The list contains a field name of more than 64 characters.

Correct the PIVOT clause and execute the query again.


Query does not return records. (Error 3323)

See Also	Example	Specifics

Possible causes:

The query being used as a record source is an action query or a data-definition query.

In version 1.x code, the ListFields method was used on an action query or data-definition query.


Execute method must be used on action or data-definition queries. (Error 3324)

See Also	Example	Specifics

In Visual Basic, you tried to run an action query or data-definition query without using the Execute method.

This error message could also be the result of setting the RowSource property to an action query or data-definition query.


Pass-through query with ReturnsRecords property set to True did not return any records. (Error 3325)

See Also	Example	Specifics

A pass-through query didn't return any records even though the ReturnsRecords property is set to Yes (True in Visual Basic).  If a pass-through query doesn't return records, set the ReturnsRecords property to No (False).


This Recordset is not updatable. (Error 3326)

See Also	Example	Specifics

In Visual Basic, you attempted to edit data in a field that is bound to a snapshot-type Recordset object.  Snapshot fields can't be edited.


Can be present only in version 1.0 format. (Error 3334)

See Also	Example	Specifics

You are attempting to use a feature that is no longer supported in the current version of the application.  To learn about the current approach to completing your task, see Examples of Converting Code to Version 2.5.


Btrieve: Invalid IndexDDF option in <initialization (.INI) file>. (Error 3336)

See Also	Example	Specifics

The setting for the IndexDDF entry in the [Btrieve ISAM] section of the initialization file isn't valid.  The IndexDDF entry determines the manner in which the Btrieve external ISAM database is to handle the INDEX.DDF file, which is updated whenever indexes are created or deleted.

Valid settings are:

Require [image] INDEX.DDF file is required in the database directory, in addition to FILE.DDF and FIELD.DDF.

Maintain [image] Updates the INDEX.DDF file if it exists, but doesn't generate an error if it doesn't.

Ignore [image] Makes no attempt to update the INDEX.DDF file, regardless of whether or not it exists.


Invalid DataCodePage option in <initialization (.INI) file>. (Error 3337)

See Also	Example	Specifics

The DataCodePage setting for the external data source you are attempting to use isn't valid.  This setting is in the corresponding [<external data source> ISAM] section (for example, [Btrieve ISAM]) in the initialization (.INI) file.

Valid settings are:

OEM [image] Data is stored as OEM data; OemToAnsi and AnsiToOem conversions are done.

ANSI [image] Data is stored as ANSI data; OemToAnsi and AnsiToOem conversions aren't done.


Btrieve: Xtrieve options aren't correct in <initialization (.INI) file>. (Error 3338)

See Also	Example	Specifics

One or more of the XTRPATH, XTRENV, and XTRPINDEX entries in MSACC20.INI is invalid.

Possible causes and solutions:

XTRPATH is the directory search path for locating data files.  The format for this entry is:

XTRPATH=dir1;dir2;dir2

where dir1, dir2, and dir3 are full directory paths (for example, XTRPATH=C:\DATA;D:\FILES;E:\DATA).

XTRENV is the directory and filename for the Xtrieve environment file (for example, XTRENV=C:\XTRV\XTRIEVE.ENV).

XTRPINDX is a pointer to the directory in which to create new Xtrieve tables, expressed as a numeric value corresponding to a directory in XTRPATH, with the first directory having an XTRPINDX of 1, the second having an XTRPINDX of 2, and so on.  In the XTRPATH shown above, an XTRPINDX value of 2 indicates create new Xtrieve tables in the directory D:\FILES.


Btrieve: Invalid IndexDeleteRenumber option in <initialization (.INI) file>. (Error 3339)

See Also	Example	Specifics

The setting for the IndexDeleteRenumber entry in the [Btrieve ISAM] section of the initialization file isn't valid.  The IndexDeleteRenumber entry determines whether remaining indexes are renumbered if one is deleted.

Valid settings are:

On [image] Renumbers.

Off [image] Doesn't renumber.

On is consistent with Btrieve version 5.1x behavior.  Off is consistent with Btrieve version 6.0 behavior.


Query <name> is corrupt. (Error 3340)

See Also	Example	Specifics

You've referenced an undefined query name.  Check the queries listed QueryDefs collection to make sure you reference a valid query name.


Current field must match join key <name> on 'one' side of outer join. (Error 3341)

See Also	Example	Specifics

You've tried to enter a value into the join field in the many-only table of an outer join with no corresponding value in the join field of the "one" side table.  First enter a record in the "one" side table with the desired key value.  Then make the entry with the desired join field in the "many-only" table.


Invalid Memo or OLE object in subquery <name>. (Error 3342)

See Also	Example	Specifics

A subquery can't return a Memo or OLE object, and can't be compared to a Memo or OLE object in an expression.


Unknown or invalid reference (<name>) in validation expression or default value in table <name>. (Error 3344)

See Also	Example	Specifics

Your expression refers to a field incorrectly, or to a field that doesn't exist.  Check to make sure the field name is valid and spelled correctly.


Unknown or invalid field reference <name>. (Error 3345)

See Also	Example	Specifics

Your expression refers to a field incorrectly or to a field that doesn't exist.  Check to make sure the field name is correct.


Number of query values and destination fields aren't the same. (Error 3346)

See Also	Example	Specifics

The INSERT INTO (Append) query either doesn't have enough destination fields or it has more fields in the VALUES or SELECT list than there are fields in the destination table.  Select a matching number of fields.


Numeric field overflow. (Error 3349)

See Also	Example	Specifics

The data in a Btrieve field is too large to represent in Visual Basic.


Object is invalid for operation or no longer exists. (Error 3350)

See Also	Example	Specifics

You used the RefreshLink Method on an object other than an attached table.  An object ceases to exist when it is destroyed and when its associated data object is closed or is no longer defined in the current scope.


ORDER BY expression <expression> uses non-output fields. (Error 3351)

See Also	Example	Specifics

In a union query, you've included nonoutput fields in an ORDER BY expression.  Only those fields requested in the first query can be included in an ORDER BY expression.


No destination field name in INSERT INTO statement <statement>. (Error 3352)

See Also	Example	Specifics

The destination field name or names can't be determined from the expression in the SELECT clause of the INSERT INTO statement.


Btrieve: Can't find file FIELD.DDF. (Error 3353)

See Also	Example	Specifics

The Btrieve driver can't find the FIELD.DDF file pointed to by the FILE.DDF file.

Possible solutions:

If the FIELD.DDF file exists, fix the reference to it in the FILE.DDF file using either Novell Xtrieve or another .DDF file builder.

If the FIELD.DDF file doesn't exist, create it using either Novell Xtrieve or another .DDF file builder.


At most one record can be returned by this subquery. (Error 3354)

See Also	Example	Specifics

A subquery of this kind can't return more than one record.  Revise the SELECT statement of the subquery to request only one record.


Syntax error in default value. (Error 3355)

See Also	Example	Specifics

Possible causes:

An unknown function name was included in the default value expression in a table-level validation rule.

A default value expression in a table-level validation rule is syntactically incorrect.


Can't open this database exclusively.  The database is opened by user <name> on machine <name>. (Error 3356)

See Also	Example	Specifics

You can't open or change the specified database because another user has it open for exclusive access.  Ask the other user to open the database for shared access, or try again later.


Can't open Microsoft Jet engine system database (typically SYSTEM.MDA). (Error 3358)

See Also	Example	Specifics

You attempted to perform a security-related task, but the system database required for the task can't be found.


Pass-through query must contain at least one character. (Error 3359)

See Also	Example	Specifics

The SQL string of a pass-through query must contain at least one character.


Query is too complex. (Error 3360)

See Also	Example	Specifics

The query is too complex.  Reduce the number of fields in the SELECT clause.


Unions not allowed in a subquery. (Error 3361)

See Also	Example	Specifics

You can't use a UNION operation in a subquery expression.  To use a union query in a subquery, first create the union query and save it as a named query.  Then include the name of the saved query in your subquery expression.


Single-row update/delete affected more than one row of an attached table.  Unique index contains duplicate values. (Error 3362)

See Also	Example	Specifics

Your update or delete query affected more than one record in the attached SQL table.  Update and delete can affect only one record at a time.


Can't use Memo or OLE object field <name> in SELECT clause of a union query. (Error 3364)

See Also	Example	Specifics

A field you specified in the SELECT part of a UNION query in the SQL statement for the query has a field data type of Memo or OLE object.  You can't specify a field of either of these types.


Can't set this property for remote objects. (Error 3365)

See Also	Example	Specifics

This property isn't available for objects associated with ODBC databases.


Can't append a relation with no fields defined. (Error 3366)

See Also	Example	Specifics

You are trying to append a Relation object without any fields to a Relations collection.

To correctly append a Relation

1.	Use the CreateRelation method to create the Relation object.

2.	Set the Table, ForeignTable, and Attributes properties of the Relation object, if you didn't specify them as arguments to the CreateRelation method.

3.	Use the CreateField method to create a new Field object for each field in the primary and foreign keys of the relationship.

4.	Set the Name (if you didn't specify it as an argument to the CreateField method) and ForeignName properties of the Field object(s) to the corresponding Name property settings of the primary key and the foreign key Field objects of each field in the relationship.

5.	Use the Append method to save the Field object(s) in the Fields collection of the Relation object.

6.	Use the Append method to save the Relation object in the Relations collection of the database.


Can't append.  Object already in collection. (Error 3367)

See Also	Example	Specifics

You tried to append an object to a collection that already contains an object of the same name.  Use the Refresh method on the collection and check to see whether the object you want to append already exists, or try changing the object's Name property setting.


Relationship must be on the same number of fields with the same data types. (Error 3368)

See Also	Example	Specifics

The CONSTRAINT clause you're using to create a relationship includes a different number of fields for each table or includes fields with different data types.  Check the number of fields in the CONSTRAINT clause, check the data types of fields to make sure they match, and try again.


Can't modify the design of table <name>; it's in a read-only database. (Error 3370)

See Also	Example	Specifics

You can't modify tables in a read-only database.


Can't find table or constraint. (Error 3371)

See Also	Example	Specifics

The table or relationship you specified doesn't exist.  Specify a valid table or constraint name.


No such index <name> on table <name>. (Error 3372)

See Also	Example	Specifics

The specified index doesn't exist in the specified table.  Check your SQL statement or Visual Basic code for a misspelling or other error.


Can't create relationship; referenced table <name> doesn't have a primary key. (Error 3373)

See Also	Example	Specifics

The table you've referenced in the CONSTRAINT clause doesn't have a primary key.  To create the relationship, you must either create a primary key in the referenced table, or specifically reference one or more uniquely indexed fields to use in the relationship.


The specified fields are not uniquely indexed in table <name>. (Error 3374)

See Also	Example	Specifics

The specified fields in the referenced table of a CONSTRAINT clause aren't uniquely indexed.


Table <name> already has an index named <name>. (Error 3375)

See Also	Example	Specifics

You're trying to create an index that already exists.


Table <name> doesn't exist. (Error 3376)

See Also	Example	Specifics

The table you specified doesn't exist.  Check the name you specified.


No such relationship <name> on table <name>. (Error 3377)

See Also	Example	Specifics

The relationship you specified doesn't exist in this database.  Check the name you specified.


There is already a relationship named <name> in the current database. (Error 3378)

See Also	Example	Specifics

You must specify a unique name for each relationship you add to a database using data-definition queries.


Can't create relationships.  Existing data in table <name> violates referential integrity rules in table <name>. (Error 3379)

See Also	Example	Specifics

You're trying to create a relationship using the CONSTRAINT clause of the ALTER TABLE statement, but existing data in the two tables violates referential integrity constraints.  For example, there might be records relating to an employee in the related table but no corresponding record for the employee in the primary table.

To create the relationship, you must edit the data so that primary records exist for all related records.


Field <name> already exists in table <name>. (Error 3380)

See Also	Example	Specifics

You have entered the same field name twice.  Rewrite your SQL statement or Visual Basic code, giving each field a unique name.


There is no field named <name> in table <name>. (Error 3381)

See Also	Example	Specifics

The specified table doesn't contain the specified field.  Check the spelling of the field name.


Field <name> size must be from 1 to 255. (Error 3382)

See Also	Example	Specifics

Text fields can be no more than 255 characters.  Redefine the size of the field.


Can't delete field <name>.  It's part of one or more relationships. (Error 3383)

See Also	Example	Specifics

You're trying to delete a field for which relationships have been defined in the database.  To delete the field, you must first delete its relationships.


Can't delete a built-in property. (Error 3384)

See Also	Example	Specifics

You are trying to delete a Property object defined by the Microsoft Jet database engine.

You can delete only user-defined (including application-defined) properties for which you have Modify Design permission or ones for which Modify Design permission isn't required.


User-defined properties don't support a Null value. (Error 3385)

See Also	Example	Specifics

User-defined Property objects can't be set to Null.  Instead, use the Delete method on the property to remove it from its collection.


Property <name> must be set before using this method. (Error 3386)

See Also	Example	Specifics

You attempted to append a new Property object to a collection without first setting all of the new object's properties: Value, Type, and Name.


Can't find TEMP directory. (Error 3387)

See Also	Example	Specifics

The Microsoft Jet database engine often creates temporary files while performing operations.  These files are written to a directory specified by the TEMP or TMP environment variable in your AUTOEXEC.BAT file.  The path to this directory currently specified in your AUTOEXEC.BAT file is invalid.

Check the location of the directory you use for storing temporary files, then use an editor such as Microsoft Notepad to open your AUTOEXEC.BAT file and enter the correct path.  For example, if you store temporary files in C:\TEMP, you would enter:

Set temp=C:\TEMP


Unknown function <name> in validation expression or default value on <name>. (Error 3388)

See Also	Example	Specifics

The function you are referencing is either unknown (because the name is invalid or misspelled) or is a type of function not allowed by the ValidationRule or DefaultValue property.  Among the types of functions not allowed are user-defined, SQL aggregated, and domain aggregate functions.


Query support unavailable. (Error 3389)

See Also	Example	Specifics

In Visual Basic, you attempted to establish referential integrity on a Relation object of a QueryDef object, which isn't supported.

Change the Attributes property setting of the Relation object to dbrelationdontenforce.


Account name already exists. (Error 3390)

See Also	Example	Specifics

This is a security problem.  You tried to establish a user account using a name that already exists.  Try again using a different user name.


Can't perform join, group, or sort.  Combined fields are too long. (Error 3393)

See Also	Example	Specifics

The maximum combined length of fields used to join, group, or sort is 255 bytes.  Reduce the number of fields in your join, group, or sort, or use shorter data types and field sizes for the fields.


Can't save property; property is a schema property. (Error 3394)

See Also	Example	Specifics

You tried to set or change a schema property.  When you create a new schema property, specify True as the fourth argument to the CreateProperty method in order to set or delete this property.


Can't perform cascading operation.  Records exist in table <name> that  can violate referential integrity rules. (Error 3396)

See Also	Example	Specifics

The cascade operation you are attempting violates referential integrity rules with the indicated table.  Check the values you are attempting to update or delete, and fix them so they comply with the referential integrity rules.


Can't perform cascading operation.  There must be a related record in table <name>. (Error 3397)

See Also	Example	Specifics

The cascade operation you are attempting violates a referential integrity rule that requires a related record in the indicated table.  Check the values you are attempting to update or delete and fix them so they comply with the referential integrity rule.


Can't perform cascading operation.  It would result in a null key in table <name>. (Error 3398)

See Also	Example	Specifics

The cascade operation you are attempting would result in a Null value in a primary key field in the indicated table, which has been set up not to allow null values.  Check the values you are attempting to update and fix them so they don't result in null values.


Can't perform cascading operation.  It would result in a duplicate key in table <name>. (Error 3399)

See Also	Example	Specifics

The cascade operation you are attempting would result in a duplicate key in the indicated table, which is set up not to allow duplicate primary keys.  Check the values you are attempting to update and fix them so they don't result in duplicate keys.


Can't perform cascading operation.  It would result in two updates to field <name> in table <name>. (Error 3400)

See Also	Example	Specifics

The cascade operation you are attempting can't be completed because it would result in two separate updates to the indicated field.  Check the values you are attempting to update, and fix them so that either:

The field is updated only one time.

If the field is updated more than once; the result of each update to the field is the same.


Can't perform cascading operation.  It would cause field <name> to become null, which is not allowed. (Error 3401)

See Also	Example	Specifics

The cascade operation you are attempting would result in a Null value in the indicated field, which has been set up not to allow null values.  Check the values you are attempting to update and fix them so they don't result in null values in this field.


Can't perform cascading operation.  It would cause field <name> to become a zero-length string. (Error 3402)

See Also	Example	Specifics

The cascade operation you are attempting would result in a zero-length string in the indicated field, which is set up not to allow zero-length strings.  Check the values you are attempting to update and fix them so they don't result in zero-length strings in this field.


Can't perform cascading operation: <validation text>. (Error 3403)

See Also	Example	Specifics

The cascade operation you are attempting would result in invalid data.  Check the values you are attempting to update and fix them so they comply with the validation rules.


Can't perform cascading operation.  Value entered violates the validation rule <rule> set for field <name>. (Error 3404)

See Also	Example	Specifics

The cascade operation you are attempting would result in an invalid value in the indicated field, as established by the field's validation rule.  Check the values you are attempting to update and fix them so they comply with the validation rule.


Error <error text> in validation rule. (Error 3405)

See Also	Example	Specifics

Visual Basic is unable to the evaluate the expression correctly, for the reason listed between the single quotation marks in the error message.  For example, if the error text is Type Mismatch, the property setting doesn't match the data type defined for the field.


Error <error text> in default value. (Error 3406)

See Also	Example	Specifics

The expression you're trying to set the DefaultValue property to is invalid.  Set the property to a valid expression.


The server's MSysConf table exists, but is in an incorrect format.  Contact your system administrator. (Error 3407)

See Also	Example	Specifics

The MSysConf table created on the server to help control communications between The Microsoft Jet database engine and the attached SQL database requires a very specific format.


Invalid field name <name> in definition of index or relationship. (Error 3409)

See Also	Example	Specifics

Possible causes:

The field name you've specified in your SQL statement or Visual Basic code is invalid.  Check the spelling of the field name.

You tried to update a Counter field, but Counter fields can't be updated.


Can't open this database for update. (Error 3410)

See Also	Example	Specifics

This database is temporarily in use by the system.  Wait a short time and then try to open the database again.


Invalid entry. Can't perform cascading operation in table <name>. Value is too long for field <name>. (Error 3411)

See Also	Example	Specifics

You're trying to save a value to a primary key field that's included in a relationship.  Because the Cascade Update Related Fields option is selected for the relationship, Visual Basic is attempting to update the matching field in the related table.

To save your changes to this field, the text you enter must be no longer than the field size of the related field that Visual Basic is trying to update for you.  In this case, the related field has a shorter field size than the field you're updating.  To avoid this problem in the future, set the Size property for both of the matching fields to the same value.


Can't perform cascading update on table <name> because it is currently in use by user <name> on machine <name>. (Error 3412)

See Also	Example	Specifics

You're trying to save a value into a primary key field that's included in a relationship.  Because the Cascade Update Related Fields option is selected for this relationship, Visual Basic is attempting to update the matching field in the related table.

The matching field can't be updated because of a locking conflict with another user.  To save the record, you must wait until the related table is no longer in use.


Can't perform cascading update on table <name> because it is currently in use. (Error 3414)

See Also	Example	Specifics

You're trying to save a value to a primary key field that's included in a relationship.  Because the Cascade Update Related Fields option is selected for this relationship, Visual Basic is attempting to update the matching field in the related table.

The matching field can't be updated because you have it open or locked on your computer.  To save the record, you must first close the related table.


Zero-length string is valid only in a text or Memo field. (Error 3415)

See Also	Example	Specifics

You're trying to enter a zero-length string in field that has a data type other than Text.  You may be able to enter a Null value instead.


Can't open <tablename>. Another user has the table open using a different network control file or locking style. (Error 3418)

See Also	Example	Specifics

The Microsoft Jet database engine can't open an external Paradox table because of inconsistencies between your initialization settings and those of another user who currently has the table open.  The ParadoxNetPath and the ParadoxNetStyle options in the [Paradox ISAM] section of MSACC20.INI (located in your Microsoft Windows directory) must be consistent for all users sharing a database.  Make sure your initialization settings match those of all other users sharing the database, and then try opening the table again.


Can't open this Paradox 4.x table because ParadoxNetStyle is set to 3.x in <initialization (.INI) file>. (Error 3419)

See Also	Example	Specifics

The Microsoft Jet database engine was unable to open an external Paradox table because of inconsistencies between the version of the table and your ParadoxNetStyle initialization setting in the [Paradox ISAM] section of MSACC20.INI.

To correct the problem

1.	Exit Microsoft Access.

2.	Using a text editor such as Windows Notepad, open the MSACC20.INI file in your Microsoft Windows directory.

3.	In the [Paradox ISAM] section, change the ParadoxNetStyle setting to 4.x.

The ParadoxNetStyle setting must be consistent for all users sharing a database.

4.	Restart Microsoft Access.

5.	Try opening the table again


Object is not valid. (Error 3420)

See Also	Example	Specifics

You are attempting to reference an object that is no longer valid or has not been set.

Possible causes:

The object has been closed.

The object has been orphaned (the parent object has been closed or deleted).

You are trying to reference a method or property in the DBEngine.Workspaces(0).Databases(0) collection, but you haven't assigned it to a variable first.  For example, to reference the name property, use the following:

Dim MyDB As Database

Set MyDB = OpenDatabase("BIBLIO.MDB")

dbname = MyDB.Name


Data type conversion error. (Error 3421)

See Also	Example	Specifics

The Microsoft Jet database engine was unable to convert data into the type required by a method or property.  This problem typically occurs if you use an argument of one type when a method or property expects another type.


Can't modify table structure. Another user has the table open. (Error 3422)

See Also	Example	Specifics

The Microsoft Jet database engine was unable to modify the structure of a table because another user currently has the table open.  Wait until the table is closed, and then try making your changes again.


You cannot use ODBC to attach an external Microsoft Access or ISAM database table to your database. (Error 3423)

See Also	Example	Specifics

You are attempting to attach either an external Microsoft Access table or an external ISAM database table (for example, dBASE, FoxPro, Paradox, or Btrieve), but you've selected <SQL Database> as the data source. You must select the appropriate data source for the data you're attempting to attach.  For example, to attach an external Microsoft Access table, select Microsoft Access as the data source.


The Jet database engine has found a problem in your database.  You must repair and compact the database. (Error 3428)

See Also	Example	Specifics

The database you are attempting to use has an unspecified problem and, as a result, it is marked as corrupt.

To correct the problem

1.	Repair the database by choosing Repair Database from the File menu.

2.	Compact the database by choosing Compact Database from the File menu.

Important   Both steps are required.


You are attempting to use an installable ISAM that is incompatible with this version of Jet (Error 3429)
You are attempting to use an Installable ISAM that is incompatible with this version of Jet. (Error 3429)

See Also	Example	Specifics

You attempted to use an older version of an installable ISAM with the current version of the Microsoft Jet database engine.  Rerun Setup to install the correct version of the installable ISAM.


While loading the Excel installable ISAM, OLE was unable to initialize (Error 3430)

See Also	Example	Specifics

OLE Automation was unable to initialize while loading the Microsoft Excel installable ISAM.  Try reinstalling the OLE DLL files.


This is not an Excel 5 file. (Error 3431)

See Also	Example	Specifics

You attempted to read a file as a Microsoft Excel version 5 file, but the file isn't in this format.


Error opening an Excel 5 file (Error 3432)

See Also	Example	Specifics

An OLE error occurred while opening a Microsoft Excel version 5 file.


Invalid parameter in [Excel ISAM] section of the <filename> initialization file (Error 3433)

See Also	Example	Specifics

One of the options in the [Excel ISAM] section of the initialization file isn't valid.  Edit the initialization file and be sure all the parameters are valid.


Can't expand named range (Error 3434)

See Also	Example	Specifics

Nonempty cells were encountered while attempting to add rows to a Microsoft Excel version 5 named range.  These cells can't be overwritten by an append operation.


Cannot delete Excel cells (Error 3435)

See Also	Example	Specifics

Data in the specified Microsoft Excel spreadsheet range of cells can't be deleted.  These cells may contain formulas, or they may be protected cells.


Failure creating Excel file (Error 3436)

See Also	Example	Specifics

An error occurred while attempting to create a Microsoft Excel file.

Possible causes:

Insufficient disk space

Network failure


Excel spreadsheet is full (Error 3437)

See Also	Example	Specifics

An attempt was made to add new records to a Microsoft Excel version 3 or version 4 file, but the file is full.  Files of these types can hold a maximum of 16,384 records.


File specification and data do not match (Error 3438)

See Also	Example	Specifics

The data being exported doesn't match the format described in the SCHEMA.INI file.


Can't attach or import Word mail merge file (Error 3439)

See Also	Example	Specifics

You attempted to attach or import a Microsoft Word mail merge file.  Although you can export such files, you can't attach or import them.


Text file has no columns. (Error 3440)

See Also	Example	Specifics

An attempt was made to import or attach to an empty text file.  To import or attach a text file, the file must contain data.


Error in <entry> entry of the <section> section in the <path> file (Error 3442)

See Also	Example	Specifics

The specified SCHEMA.INI file contains an error.


Can't create fixed width text file without column specification (Error 3443)

See Also	Example	Specifics

An attempt was made to export a fixed-width file without a valid column specification in the SCHEMA.INI file.


Column width required in schema.ini file. (Error 3444)

See Also	Example	Specifics

An attempt was made to export a fixed-width file without a column width specification in the SCHEMA.INI file.


Data Access

See Also	Specifics

Concepts

Data Access Object Hierarchy (Version 3.0)

Data Access Overview

Using Data Access

Reference

Data Access Constants

Methods

Objects and Collections

Properties

Trappable Data Access Errors

ODBC Reference

Installing ODBC

Using the ODBC Driver for Microsoft SQL Server


Methods

See Also	Specifics

This reference groups all data-access methods by object or collection and lists them alphabetically.

Grouped by Object or Collection

Database, Databases DBEngine Document, Documents Field, Fields Group, Groups Index, Indexes Parameter, Parameters	Property, Properties QueryDef, QueryDefs Recordset, Recordsets Relation, Relations TableDef, TableDefs User, Users Workspace, Workspaces
Listed Alphabetically

A-E

AddNew Append AppendChunk BeginTrans CancelUpdate Clone Close CommitTrans CompactDatabase CopyQueryDef CreateDatabase	CreateField CreateGroup CreateIndex CreateProperty CreateQueryDef CreateRelation CreateUser CreateWorkspace Delete Edit Execute
F-N

FieldSize FillCache FindFirst FindLast FindNext FindPrevious GetChunk GetRows	Idle Move MoveFirst MoveLast MoveNext MovePrevious NewPassword
O-Z

OpenDatabase OpenRecordset Refresh RefreshLink RegisterDatabase	RepairDatabase Requery Rollback Seek Update


Microsoft Jet Database Engine 2.5
Data Access Object Hierarchy (Version 2.5)

See Also	Example	Specifics


Microsoft Jet Database Engine 3.0
Data Access Object Hierarchy (Version 3.0)

See Also	Specifics

This artwork will change when we finalize the DAO 3.0 spec.


Objects and Collections

See Also	Specifics

Listed Alphabetically

Container, Containers Database, Databases DBEngine Document, Documents Error, Errors Field, Fields Group, Groups Parameter, Parameters	Property, Properties QueryDef, QueryDefs Recordset, Recordsets Relation, Relations TableDef, TableDefs User, Users Workspace, Workspaces


Properties

See Also	Specifics

This reference groups all data-access properties by object or collection and lists them alphabetically.

Grouped by Object or Collection

Container, Containers Database, Databases DBEngine Document, Documents Error, Errors Field, Fields Group, Groups Index, Indexes	Parameter, Parameters Property, Properties QueryDef, QueryDefs Recordset, Recordsets Relation, Relations TableDef, TableDefs User, Users Workspace, Workspaces

Listed Alphabetically

A

AbsolutePosition AllowZeroLength (Data Access)	Attributes

B

BOF Bookmark	Bookmarkable

C

CacheSize CacheStart Clustered	CollatingOrder Connect Count (Data Access)

D

DataUpdatable DateCreated DefaultUser DefaultPassword	DefaultValue Description DistinctCount

E

EditMode EOF

F-H

Fields Filter Foreign ForeignName	ForeignTable HelpContext HelpFile

I-K

IgnoreNulls Index Inherit	Inherited IniPath

L

LastModified LastUpdated	LockEdits LoginTimeout LogMessages

M-N

Name NoMatch	Number

O

ODBCTimeout	OrdinalPosition Owner

P

Password PercentPosition Permissions	PID Primary

Q-R

QueryTimeout RecordCount RecordsAffected	Required Restartable ReturnsRecords

S

Size Sort Source SourceField	SourceTable SourceTableName SQL

T

Table Transactions	Type

U

Unique	Updatable UserName

V-Z

V1xNullBehavior ValidateOnSet ValidationRule	ValidationText Value Version


Using Data Access

See Also	Specifics

The following topics can provide additional detailed information on specific subjects.

Accessing Data in a Microsoft Excel Worksheet or Workbook

Accessing Data in a Text Document

Accessing Databases on CDROM

Accessing External Databases

Building SQL Statements in Code

Choosing a Field Data Type

Creating A Database

Creating Parameter Queries

Customizing Data Access .INI Settings

Managing Connections to ODBC Data Sources

Populating Recordsets

Positioning the Current Record Pointer

Querying a Database

Retrieving Data Using SQL

Using Counter Fields

Using Named Arguments

Using SQL PassThrough

Using the MSysConf Table with SQL Databases


Data Access Objects and Collections

See Also	 Specifics

Data access objects and collections provide a framework for using code to create and manipulate components of your database system.  Objects and collections have properties that describe the characteristics of database components and methods that you use to manipulate them.  Using the containment framework, you create relationships among objects and collections, and these relationships represent the logical structure of your database system.

Objects and collections provide different types of containment relationships:  Objects contain zero or more collections, all of different types; and collections contain zero or more objects, all of the same type.  Although objects and collections are similar entities, the distinction differentiates the two types of relationships.

In the following table, the type of collection in the first column contains the type of object in the second column.  The third column describes what each type of object represents.

Collection	Object	Description

Containers	Container	Storage for information about a predefined object type.

Databases	Database	An open database.

None	DBEngine	The Microsoft Jet database engine.

Documents	Document	Information about a saved, predefined object.

Errors	Error	Information about any errors associated with this object.

Fields	Field	A column that is part of a table, query, index, relation, or recordset.

Groups	Group	A group of user accounts.

Indexes	Index	Predefined ordering and uniqueness of values in a table.

Parameters	Parameter	A parameter for a parameter query.

Properties	Property	A built-in or user-defined property.

QueryDefs	QueryDef	A saved query definition.

Recordsets	Recordset	The records in a base table or query.

Relations	Relation	A relationship between fields in tables and queries.

TableDefs	TableDef	A saved table definition.

Users	User	A user account.

Workspaces	Workspace	A session of the Jet database engine.


Container Object, Containers Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Container object collects information about a database and each type of object it contains: all of its saved tables, queries, or relationships.

A Containers collection contains all of the Container objects that describe a database.

Remarks

Each Database object has a Containers collection consisting of built-in Container objects.  Some of these Container objects are defined by the Microsoft Jet database engine while others may be defined by other applications.  The following table lists the name of each Container object and what type of information it contains.

Container name	Contains information about

Databases	Containing database

Tables	Saved tables and queries

Relationships	Saved relationships

Note   Don't confuse the particular types of Container objects listed in the preceding table with the collection types of the same name.  The Databases type of Container object refers to all saved objects of the specified type, but the Databases collection refers only to open objects of the specified type.

Some Container objects defined by other applications manipulating your Jet database may not be accessible by code from your application.  For example, only Microsoft Access can be used to manipulate the four types of Container objects that it defines: forms, reports, macros, and modules.

Each Container object has a Documents collection that contains a Document object for each instance of the type of object it describes.  You typically use a Container object with one of the Document objects in the Documents collection, so you can consider a Container object to be an intermediate link to the information that the Document object contains.

Because Container objects are built-in, you can't create new Container objects or delete existing ones.  Using the properties of an existing Container object, you can:

Determine the predefined names an object has by checking its Name property setting.

Determine or specify the owner of the Container object by checking or setting its Owner property.  To set the Owner property, you must have write permission for the Container object, and you must set the property to the name of an existing User or Group object.

Set access permissions for the Container object using the Permissions and UserName properties; any Document object created in the Documents collection of a Container object inherits these access permission settings.

You can refer to a Container object by its Name property setting using this syntax:

Containers("name")


Container Object,  Containers Collection Summary

See Also	Specifics

Container Object

The Container object contains no methods and these collections and properties.

Collections

Documents

Properties

Properties

Inherit

Name

Owner

Permissions

UserName

Containers Collection

The Containers collection contains no methods and this property.

Property

Count


Database Object, Databases Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Database object represents an open database.

A Databases collection contains all open Database objects in a Workspace object of the Microsoft Jet database engine.

Remarks

You manipulate an open database using a Database object and its methods and properties.  You can examine the collections in a Database object to learn about its tables, queries, and relationships.  You can also use its collections to modify or create tables, queries, recordsets, and relationships.  For example, you can:

Use the Execute method to run an action QueryDef or pass an SQL string to an ODBC database.

Use the OpenRecordset method to create a new Recordset object directly from the Database object.

Use the Close method to close an open database.

You use the CreateDatabase method to create a new, persistent Database object and save it on disk.  After you create a new database, you must create new tables to hold your data.  You can also create new indexes and table relationships, attach existing external tables, or establish a protection scheme using permissions, groups, and users.

To open an existing Database object, use the OpenDatabase method, which appends it to the Databases collection.  OpenDatabase applies to the Workspace object.  You can use OpenDatabase on the default Workspace(0) object, or specify which Workspace to use.

When you use one of the transaction methods (BeginTrans, CommitTrans, or Rollback) on the Database, these transactions apply to all databases opened on the current Workspace.  If you want to use independent transactions, you must open an additional Workspace object, and open another Database object using it.  For example, to create two independent Database objects:

Dim Db1 As Database, DB2 As Database, Ws As Workspace, WS2 As Workspace

Dim MyUserName As String

Set Ws = Workspaces(0)	' Use the default Workspace.

Set Db1 = Ws.OpenDatabase("MYDB.MDB")

' Get UserName of default Workspace.

MyUserName = Ws.UserName

' Create new Workspace.

Set WS2 = DBEngine.CreateWorkspace("Special", MyUserName, "SpecialPW")

Set Db2 = WS2.OpenDatabase("MYDB.MDB")

You can also use the outdated OpenDatabase function instead of the OpenDatabase method to create a Database object.  In this case, the default Workspaces(0) is always used.

It isn't necessary to specify the DBEngine object when using the OpenDatabase method.  It's only when you need to open a Database object in a separate transaction context that a specific Workspace object needs to be referenced.  For example, the following statements are equivalent:

Set Db = DBEngine.Workspaces(0).OpenDatabase("MYDB.MDB")

Set Db = Workspaces(0).OpenDatabase("MYDB.MDB")

Set Db = OpenDatabase("MYDB.MDB")

Opening a database that has attached tables doesn't automatically establish links to the specified external files or external ODBC databases until the table's TableDef or Field objects are referenced.  If links to these tables can't be established, a trappable error occurs.  You may also need permission to access the database, or the database may already be open for exclusive use by another user.  In these cases, trappable errors occur.

You can also open an external database directly instead of opening a Jet database that has links to its tables.  The Jet database engine supports FoxPro, dBASE, Btrieve, Paradox, and ODBC external databases.  See the OpenDatabase method for more information.  For example, to open a FoxPro database, you could use the following code:

Dim Db As Database

Set Db = Workspaces(0).OpenDatabase("C:\FoxFiles", _

False,False,"FoxPro 2.5")

After you open an external database, you can examine the Connect property of the Database object to determine the parameters used to access the database.  When an external ODBC database is opened directly, you can't use the Table object or table-type Recordset objects.

Each time you open an external ODBC database directly, you establish a connection to the external database server.  The Jet engine also executes additional queries on the database to determine the structure of accessed tables.  Therefore, don't open external databases directly (the capability to do so is provided for backward compatibility only).

You use the Close method to remove a Database object from the Databases collection without deleting it from disk.  You must close all open Recordset objects before closing a Database object.

By default, a variable declared as a Database object in a Sub or Function procedure exists only while the procedure is executing.  As a result, references to any data access objects in the database are invalid after the procedure is finished, even if they're objects represented by global variables.  For example, if you declare a Recordset variable MyRs as a global variable, and then execute the following procedure, MyRs is invalid after the procedure is finished:

Sub TestRecordset()

Dim MyDb As Database

Set MyDb = Workspaces(0).Databases(0)

Set MyRs = MyDb.OpenRecordset("Categories")

End Sub

To avoid this problem, declare the Database variable as a global variable.

Important   To refer to a database's properties, methods, or objects, you must first declare and set a variable to represent the database.  For example, to refer to the Name property of the current database, you must first assign the current database to a variable:

Dim MyDb as Database

Set MyDb = Workspaces(0).Databases(0)

' Display the name of the specified database in the Immediate pane.

Debug.Print MyDb.Name

A trappable error is triggered if you refer to a property, method, or object of the Database object without first declaring and setting a variable to represent the database.  For example, the following code produces an error:

Debug.Print Workspaces(0).Databases(0).Name

When a procedure that declares a Database object is finished, these local Database objects are closed along with any open Recordset objects.  Any pending updates are lost and any pending transactions are rolled back, but no trappable error occurs.  It's recommended that you explicitly complete any pending transactions or edits and close Recordset objects and Database objects before exiting procedures that declare these object variables locally.

The first database that is opened is Databases(0).  The Name property setting of the current database is a string that specifies the path of the database file.  The Connect property specifies the database type and other parameters used to connect to external databases.  You can refer to any Database object by its Name property setting using this syntax:

Databases("name")

You can also refer to the object by its ordinal number using this syntax (which refers to the first member of the Databases collection):

Databases(0)


Database Object, Databases Collection Summary

See Also	Specifics

Database Object

The Database object contains these collections, methods, and properties.

Collections

Containers	Relations

QueryDefs	TableDefs (default)

Recordsets

Methods

CreateProperty	CreateTableDef

CreateQueryDef	Execute

CreateRelation	OpenRecordset

Properties

CollatingOrder	Transactions

Connect	Updatable

Name	Version

QueryTimeout

RecordsAffected

Databases Collection

The Databases collection contains no methods and this property.

Property

Count


DBEngine Object

See Also	Example	Properties	Methods	Specifics 	Summary

The DBEngine object represents the Microsoft Jet database engine.  As the top-level object, it contains and controls all other objects in the hierarchy of data access objects.

Remarks

Use the DBEngine object to control the Jet database engine, manipulate its properties, and perform tasks on temporary objects that aren't elements of collections.  For example, you can:

Use the Version property to obtain the version number of the Jet engine, the LoginTimeout property to obtain or set the ODBC login timeout, and the RegisterDatabase method to provide ODBC information to the Jet engine.

Use the Idle method to enable the Jet engine to complete any pending tasks and the CompactDatabase and RepairDatabase methods to maintain database files.

Use the CreateWorkspace method to create a new session.

Use the Errors collection to examine data access error details.

Set the DBEngine object to Nothing to force reinitialization of the engine when it is next accessed.

The DBEngine object is a predefined object, and you can't create additional DBEngine objects.  To refer to a collection belonging to the DBEngine object or to refer to a method or property that applies to this object, use this syntax:

DBEngine.[collection | method | property]

The DBEngine object isn't an element of any collection.

Note   The Microsoft Jet database engine is limited to 10 instances on any particular system.  That is, you can execute up to 10 applications that simultaneously use the Jet version 2.5 engine.


DBEngine Object Summary

See Also	Specifics

The DBEngine object contains these collections, methods, and properties.

Collections

Errors

Properties

Workspaces (default)

Methods

CompactDatabase	RegisterDatabase

CreateWorkspace	RepairDatabase

Idle

Properties

DefaultPassword

DefaultUser

IniPath

LoginTimeout

Version


Document Object, Documents Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Document object includes information about one instance of a type of object.  The object can be a database, saved table, query, or relationship.

A Documents collection contains all of the Document objects for a specific type of object.

Remarks

Each Container object has a Documents collection containing Document objects that describe instances of built-in Container types.  The following table lists the type of object each Document describes, the name of its Container object, and what type of information Document contains.

Document	Container	Contains information about

Database	Databases	Containing database

Table or query	Tables	Saved table or query

Relationship	Relationships	Saved relationship

Note   Don't confuse the particular types of Container objects with the collection types of the same name.  The Databases Container object refers to all saved objects of the specified type, but the Databases collection refers only to open objects of the specified type.

Because a Document object corresponds to an existing database object, you can't create new Document objects or delete existing ones.  Using the properties of an existing Document object, you can:

Determine the name that a user or the Microsoft Jet database engine gave to the object when it was created by checking the Name property setting.

Determine or specify the owner of the database object by checking or setting the Owner property.  To set the Owner property, you must have write permission for the Document object, and you must set the property to the name of an existing User or Group object.

Determine the name of the Container object that contains the Document object by checking the Container property setting.

Determine or specify the access permissions of a user or group for the object by checking or setting the UserName or Permissions property.  To set these properties, you must have write permission for the Document object, and you must set the UserName property to the name of an existing User or Group object.

Determine the date and time when the Document object was created and last modified by checking the DateCreated and LastUpdated property settings.

You can refer to a Document object by its Name property setting using this syntax:

MyContainer.Documents("name")


Document Object, Documents Collection Summary

See Also	Specifics

Document Object

The Document object contains no methods, this collection, and these and properties.

Collection

Properties

Properties

Container	Owner

DateCreated	Permissions

LastUpdated	UserName

Name

Documents Collection

The Documents collection contains these methods and this property.

Methods

Refresh

Property

Count


Dynaset-Type Recordset
Dynaset-Type Recordset Object

See Also	Example	Properties	Methods	Specifics

A dynaset-type Recordset is a type of Recordset object that you can use to manipulate data in an underlying table or tables.  A dynaset-type Recordset is a dynamic set of records that can contain fields from one or more tables in a database and may be updatable.

Remarks

A dynaset-type Recordset is different from a snapshot-type Recordset because only a unique key for each record is brought into memory.  Like the table-type Recordset, a current record is fetched only when its fields are referenced.

To create a dynaset-type Recordset, use the OpenRecordset on an open database, against another dynaset- or snapshot-type Recordset, or on a QueryDef object.

If you request a dynaset-type Recordset and the Microsoft Jet database engine is unable to gain read-write access to the records, the Jet engine may create a read-only dynaset-type Recordset.  If the Recordset created isn't updatable, the Updatable property setting is False.

As base table data changes due to updates made by your application or by other users, current data is available to your application when you reposition the current record.  In a multiuser database, more than one user can open a dynaset-type Recordset referring to the same records.  Because a dynaset-type Recordset is dynamic, when one user changes a record, other users have immediate access to the changed data.  However, if one user adds a record, other users aren't notified until they use the Requery method on the Recordset.  If a user deletes a record, other users are notified when they try to access it.

Records added to the database don't become a part of your dynaset-type Recordset unless you add them using the AddNew method.  For example, if you use an action query containing an INSERT INTO SQL statement to add records, the new records aren't included in your dynaset-type Recordset until you use the Requery method or you rebuild your Recordset using the OpenRecordset method.

To maintain data integrity, dynaset- and table-type Recordset objects are locked during Edit and Update operations so that only one user can update a particular record at a time.  When the Jet database engine locks a record, it locks the entire 2K page containing the record.

Two kinds of locking are used with non-ODBC tables [image] pessimistic and optimistic.  External tables accessed using ODBC always use optimistic locking.  The locking conditions in effect during editing are determined by the LockEdits property.

Not all fields can be updated in all dynaset-type Recordset objects.  To determine whether you can update a particular field, check the Updatable property setting of the Field object.

Some of the reasons a dynaset-type Recordset may not be updatable are:

There isn't a unique index on the ODBC or Paradox table(s).

The data page is locked by another user.

The record has changed since you last read it.

The user doesn't have permission.

One or more of the tables or fields are set to Read-Only.

The database is opened as Read-Only.

The Recordset was created from multiple tables without a JOIN statement or the query was too complex.

The order of dynaset-type Recordset or Recordset data isn't guaranteed to follow any specific sequence.  If you need to order your data, use an SQL statement with an ORDER BY clause to create the Recordset.  This technique can also be used to filter the records so that only certain records are added to the Recordset.  For example, the following code selects only titles that were published between 1993 and 1994 and sorts the resulting records by title:

Dim Db As Database, Rs As Recordset, SQL As String

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")

SQL$ = "SELECT * FROM Titles  " _

& " WHERE [Year Published] BETWEEN 1993 AND 1994 " _

& " ORDER BY ISBN;"

Set Rs = Db.OpenRecordset(SQL$,dbOpenDynaset)

Using this technique instead of the Filter or Sort properties or testing each record individually generally results in faster access to your data.


Error Object, Errors Collection

See Also	Example	Properties	Methods	Specifics 	Summary

Error object [image] contains details about data access errors.

Errors collection [image] contains all stored Error objects, each of which pertains to a single operation involving data access objects (DAO).

Remarks

Any operation involving data access objects can generate one or more errors.  As each error occurs, one or more Error objects are placed in the Errors collection of the DBEngine object.  When another DAO operation generates an error, the Errors collection is cleared, and the new Error object is placed in the Errors collection.  DAO operations that don't generate an error have no effect on the Errors collection.

Members of the Errors collection aren't appended as is typical with other collections.  The most detailed errors are placed at the end of the collection (Count -1), and the most general errors are placed at index 0.

The set of Error objects in the Errors collection describes one error.  The first Error object is the lowest level error, the second the next higher level, and so forth.  For example, if an ODBC error occurs while trying to open a Recordset object, the last Error object contains the DAO error indicating that the object couldn't be opened.  The first error object contains the lowest level ODBC error.  Subsequent errors contain the ODBC errors returned by the various layers of ODBC.  In this case, the driver manager, and possibly the driver itself return separate Error objects.

Note   If you use the New keyword to create an object that causes an error before or while being placed into the Errors collection, the collection doesn't contain error information about that object (it might contain information from a previous error).

The error information is available in the Err object.

To determine if the error information in the Errors collection is valid, compare the Number property of the last element of the Errors collection (DBEngine.Errors(0)) with the Visual Basic Err value.


Error Object, Errors Collection Summary

See Also	Specifics

Error Object

An Error object contains these properties:

Properties

Description	Number

HelpContext	Source

HelpFile

Errors Collection

The Errors collection contains no methods and this property:

Property

Count


Field Object, Fields Collection

See Also	Example	Properties	Methods	Events	Specifics 	Summary

A Field object represents a column of data with a common data type and a common set of properties.

A Fields collection contains all stored Field objects of an Index, QueryDef, Recordset, Relation, or TableDef object.

Remarks

The Fields collections of Index, QueryDef, Relation, and TableDef objects contain the specifications for the fields those objects represent.  The Fields collection of a Recordset object represents the Field objects in a row of data, or record.  You use the Field objects in a Recordset to read and to set values for the fields in the current record of the Recordset.

You manipulate a field using a Field object and its methods and properties.  For example, you can:

Get or set the presentation order of the Field object in a Fields collection using the OrdinalPosition property.

Read the SourceField and SourceTable property settings to determine the original source of the data.

Read or set the ForeignName property setting for a field in a Relation object.

Read or set the AllowZeroLength, DefaultValue, Required, ValidateOnSet, ValidationRule, or ValidationText property setting to find or specify validation conditions.

Read or set the Value property of a Recordset.

Use the AppendChunk, FieldSize, and GetChunk methods to get or set a value in a OLE Object or Memo field of a Recordset.

You can refer to the Value property of a Field object that you create and append to a Fields collection by:

Its Name property setting using this syntax:

Fields("name")

-Or-

Fields!name

Note   Fields that have names with embedded spaces must be delimited with brackets as in [Part Number] or enclosed in single (' ') or double (" ") quotation marks, as in 'Part Number' or "Part Number".

For example:

Fields![long name]

-Or-

Fields("long name")

Its position in the Fields collection using this syntax:

Fields(0)

To create a new Field object in an Index, TableDef, or Relation object, use the CreateField method.

When the Field object is accessed as part of a Recordset object, data from the current record is visible in the Field object's Value property.  To manipulate data in the Recordset, you won't usually reference the Fields collection directly, but instead use syntax as shown below that references the Fields collection as the default collection of the Recordset.  For example, to manipulate data from a Recordset, you use the following syntax that indirectly references the Value property of Field object in the Fields collection of the Recordset:

Dim Rs As Recordset, Db As Database

Set Db = Workspaces(0).OpenDatabase("MYDB.MDB")

Set Rs = Db.OpenRecordset("Select [Part Name], Size,  " _

& "[Part Type], [Part Age] AS Age FROM MyTable")

'Return the Part Name field in the Recordset.

Debug.Print Rs.Fields(0).Value

' Or, use indirect coding.

Debug.Print Rs(0)	' Return the Part Name field in the Recordset.

Debug.Print Rs("Part Name")	' Also return the Part Name field.

Debug.Print Rs![Part Type]	' Return the Part Type field.

Debug.Print Rs!Age	' Return the Part Age field aliased as Age.


Field Object, Fields Collection Summary

See Also	Specifics

Field Object

A Field object contains these collections, methods, and properties.

Collection

Properties

Methods

AppendChunk

CreateProperty

FieldSize

GetChunk

Properties

AllowZeroLength	Name	Type

Attributes	OrdinalPosition	ValidateOnSet

CollatingOrder	Required	ValidationRule

DataUpdatable	Size	ValidationText

DefaultValue	SourceField	Value

ForeignName	SourceTable

Fields Collection

A Fields collection contains these methods and properties.

Methods

Append

Delete

Refresh

Property

Count


Group Object, Groups Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Group object represents a group of user accounts that have common access permissions when a Workspace object operates as a secure workgroup.

A Groups collection contains all stored Group objects of a Workspace or user account.

Remarks

You create Group objects, and then use their names to establish and enforce access permissions for your databases, tables, and queries using the Document objects that represent the database and database objects (tables and queries) you're working with.

You can append an existing Group object to the Groups collection in a User object to establish membership of a user account in that Group object.  Alternatively, you can append a User object to the Users collection in a Group object to give a user account the global permissions of that group.  If you use a Groups or Users collection other than the one to which you just appended an object, you may need to use the Refresh method to refresh the collection with current information from the database.

Using the properties of a Group object, you can:

Check the Name property setting of an existing Group object to determine its name.  You can't check the PID property setting of an existing Group object.

Set the Name and PID properties of a newly created, unappended Group object to establish the identity of that Group object.

The Microsoft Jet database engine predefines three Group objects named Admins, Users, and Guests.  Any User object you add is automatically made a member of the Users collection of the Group object named Users.

You can refer to a Group object that you create and append to a Groups collection by its Name property setting using this syntax:

Groups("name")

To create a new Group object, use the CreateGroup method.


Group Object, Groups Collection Summary

See Also	Specifics

Group Object

The Group object contains these collections, methods, and properties.

Collections

Properties

Users (default)

Method

CreateUser

Properties

Name

PID

Groups Collection

The Groups collection contains these methods and properties.

Methods

Append

Delete

Refresh

Property

Count


Index Object, Indexes Collection

See Also	Example	Properties	Methods	Specifics 	Summary

Index objects specify the order of records accessed from database tables and whether or not duplicate records are accepted.  Index objects also provide efficient access to data.  For external databases, Index objects describe the indexes established for external tables.

An Indexes collection contains stored Index objects of a TableDef object.

Remarks

The Microsoft Jet database engine maintains all base table indexes automatically.  Once created, you must use the CompactDatabase method periodically.  Indexes are updated whenever you add, change, or delete records from the base table.

The Jet engine uses indexes when it joins tables and creates recordsets.  Indexes determine the order of records returned by Table objects and table-type Recordsets, but they don't determine the order in which records are stored in the base table or the order of records returned from any other type of recordset.

When accessing a table-type Recordset or Table object, you specify the order of records using the object's Index property.  Set this property to the Name property setting of an existing Index object in the Indexes collection.  This collection is contained by the TableDef object that underlies the Recordset object that you're populating.  For example, to order your table-type Recordset by the Publisher's ZIP Code index, you could use the following code:

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Set MyRs = Db.OpenRecordset("Publishers", dbOpenTable)

MyRs.Index = "ZIP_INDEX"

Tip   You don't have to create indexes for a table, but in large, unindexed tables, accessing a specific record or processing joins can take a long time.  Conversely, having too many indexes can slow down updates to the database as each of the table indexes is amended.

The Attributes property of each Field object in the index determines the order of records returned and consequently determines the access techniques to use for that index.

Each Field object in the Fields collection of an Index object is a component of the index.  You define a new Index by setting its properties before you append it to a collection, which makes the Index available for subsequent use.

Note   You can use the Append or Delete method on an Indexes collection or modify the Name property setting of an existing Index only if the Updatable property setting of the containing TableDef object is True.

Using an Index object and its properties, you can:

Use the Required property to determine whether the Field objects in the index require non-Null values, and you can use the IgnoreNulls property to determine whether the Null values have index entries.

Use the Primary and Unique properties to determine the ordering and uniqueness of the Index.

When you set a primary key for a table, the Jet database engine automatically defines it as the primary index.  A primary index consists of one or more fields that uniquely identify all records in a table in a predefined order.  Because the primary index field must be unique, the Jet engine automatically sets the Unique property of the primary Index object to True.  If the primary index consists of more than one field, each field can contain duplicate values, but each combination of values from all the indexed fields must be unique.  A primary index consists of a key for the table and is always made up of the same fields as the primary key.

If you attempt to create an Index object and your data doesn't comply with the attributes specified for the index, such as nonunique or Null values in an indexed field, a trappable error results when you attempt to use the Append method on the new index.

When you create a relationship that enforces referential integrity, the Jet database engine automatically creates an index with the Foreign property set as the foreign key in the referencing table.  After you've established a table relationship, the Jet engine prevents additions or changes to the database that violate that relationship.  If you set the Attributes property of the Relation object to allow cascade update and cascade delete operations, the Jet engine updates or deletes records in related tables automatically.

To create a new Index object

1.	Use the CreateIndex method on the TableDef object.

2.	Use the CreateField method on the Index object to create a Field object for each field (column) to be included in the Index.

3.	Set Index properties as needed.

4.	Append the Field object to the Fields collection.

5.	Append the Index to the Indexes collection.

For example:

' Create new Index object.

Set MyIndex = MyTableDef.CreateIndex("Another")

Set MyField = MyIndex.CreateField("LastName")

MyIndex.Primary = True

MyIndex.Required = True

MyIndex.Fields.Append MyField

' Save Index definition by appending it to Indexes collection.

MyTableDef.Indexes.Append MyIndex

Important   Make sure your data complies with the attributes of your new index.  If your index requires unique values, make sure that there are no duplicates in existing data records.  If duplicates exist, the database engine can't create the index, resulting in a trappable error.

Note   The Clustered property is ignored for databases that use the Jet engine, which doesn't support clustered indexes.


Index Object, Indexes Collection Summary

See Also	Specifics

Index Object

The Index object contains these collections, methods, and properties.

Collections

Fields (default)

Properties

Methods

CreateField

CreateProperty

Properties

Clustered	Primary

Foreign	Unique

IgnoreNulls	Required

Name

Indexes Collection

The Indexes collection contains these methods and properties.

Methods

Append

Delete

Refresh

Property

Count


Parameter Object, Parameters Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Parameter object represents a parameter associated with a QueryDef object created from a parameter query.

A Parameters collection contains all the Parameter objects of a QueryDef object.

Remarks

Using the properties of a Parameter object, you can set a query parameter that can be changed before the query is run.  You can:

 	Check the Name property setting to determine the name of a parameter.

 	Check or set the Value property (the default property of a Parameter) of a parameter.  For example:

MyQueryDef.Parameters(0) = 5

 	Check the Type property setting to determine the data type of the Parameter.

The Parameters collection provides information only about existing parameters.  You can't append objects to or delete objects from the Parameters collection.

The only method supported by the Parameters collection is Refresh.


Parameter Object, Parameters Collection Summary

See Also	Specifics

Parameter Object

A Parameter object contains no collections or methods and these properties.

Properties

Name

Type

Value

Parameters Collection

A Parameters collection contains these methods and this property.

Methods

Append

Refresh

Property

Count


Property Object, Properties Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Property object represents a built-in characteristic or a user-defined characteristic of a data access object.

A Properties collection contains all the Property objects for a specific instance of an object.

Remarks

Every data access object contains a Properties collection, which has certain built-in Property objects.  These Property objects (which are often just called properties) uniquely characterize that instance of the object.  You specify built-in properties when you create a new data access object.  You can set the properties of some existing data access objects using an assignment statement.

The Property object itself has four built-in properties:

The Name property, a String that uniquely identifies the property.

The Type property, an Integer that specifies the property data type.

The Value property, a Variant that contains the property setting.

The Inherited property, a Boolean flag that indicates whether the property is inherited from another object.  For example, a Field object in a Fields collection of a Recordset object can inherit properties from the underlying TableDef or QueryDef object.

In addition to these built-in properties, you can create and add your own user-defined properties to these objects:

Database, Index, QueryDef, and TableDef objects

Field objects in Fields collections of QueryDef and TableDef objects

To add a user-defined property, use the CreateProperty method to create a Property object with a unique Name property setting.  Set the Type and Value properties of the new Property, and then append it to the Properties collection of the appropriate object.  The object you add the user-defined property to must already be saved on disk (that is, it must be appended to a collection).

You can delete user-defined properties from the Properties collection, but you can't delete built-in properties.

Note   A user-defined property (Property object) is associated only with the specific instance of the object whose Properties collection you append it to.  The property isn't defined for all instances of objects of the selected type.

You can use the Properties collection of an object to enumerate the object's built-in and user-defined properties.  You don't need to know beforehand exactly which properties exist or what their characteristics (Name and Type) are to manipulate them.  However, if you try to check a write-only property (such as the Password property of a Workspace object), an error occurs.

You can refer to an existing built-in or user-defined property by its Name property setting using this syntax:

object.Properties("name")

You can also refer to a user-defined property by its Name property using this syntax:

object.Properties!name

For a built-in property, you can also use this syntax:

object.name

You can also reference properties by their ordinal position with this syntax which refers to the first member of the Properties collection:

object.Properties(0)

Notes   Application-defined properties differ from the built-in properties of a data access object in the following ways:

You must refer to them using the full Properties("name") or Properties!name syntax.

Except for user-defined properties, they aren't part of the Properties collection until you change their values from their default values.

If you haven't previously set its value, you need to create it first using the CreateProperty method.  For an example of how to set an application-defined property (or any user-defined property), see the Example.

Properties of Control objects differ from data access object properties in several ways.  The Property objects:

Don't have an Inherited property.

Have a Category property that you can't set.

Can't be enumerated.


Property Object, Properties Collection Summary

See Also	Specifics

Property Object

The Property object contains no methods and these collections and properties.

Collection

Properties

Properties

Inherited

Name

Type

Value

Properties Collection

The Properties collection contains these methods and this property.

Methods

Append

Delete

Refresh

Property

Count


QueryDef Object, QueryDefs Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A QueryDef object is a stored definition of a query in a Microsoft Jet database.

A QueryDefs collection contains all QueryDef objects in a Database object.

Remarks

The QueryDef object corresponds to a stored query definition in a database.  You can think of a saved query as a compiled SQL statement.

You can use the properties of a QueryDef object to define a query.  For example, you can:

Check and modify the SQL property setting, set its parameters, and then run the query.

Set query parameters using the QueryDef object's Parameters collection.

Set or check the Type property to determine whether the query selects records from an existing table, makes a new table, inserts records from one table into another table, deletes records, or updates records.

Retrieve data from an ODBC data source by setting the ODBCTimeout and Connect properties and, if the query isn't a select query, setting the ReturnsRecords property to False.

Indicate the query is to be passed to an external ODBC server by setting the Connect property, making it an SQL pass-through query.

Use the ReturnsRecords property to indicate that the query returns records.  The ReturnsRecords property is only valid on SQL pass-through queries.

Use the ODBCTimeout property to indicate how long to wait before the query returns records.  ODBCTimeout applies to any query that accesses ODBC data through SQL pass-through, attach without links, or attached ODBC tables.

Queries executed from QueryDef objects run faster than queries specified in the OpenRecordset method because the Microsoft Jet database engine doesn't need to compile the query before executing it.

QueryDef objects are the preferred way to use the native SQL dialect of an external database engine.  For example, you can create a Transact SQL query (as used on Microsoft SQL Server) and store it in a QueryDef object.  When you need to use a non-Jet engine SQL query, you must provide a Connect property string that points to the external data source.  Queries with valid Connect properties bypass the Jet engine and pass the query directly to the external database server for processing:

To create a new QueryDef object, use the CreateQueryDef method.


QueryDef Object, QueryDefs Collection Summary

See Also	Specifics

QueryDef Object

The QueryDef object contains these collections, methods, and properties.

Collections

Fields

Parameters (default)

Methods

Close

CreateProperty

Execute

OpenRecordset

Properties

Connect	ODBCTimeout

DateCreated	RecordsAffected

LastUpdated	ReturnsRecords

LogMessages	SQL

Name	Type

QueryDefs Collection

The QueryDefs collection contains these methods and this property.

Methods

Append

Delete

Refresh

Property

Count


Recordset Object, Recordsets Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Recordset object represents the records in a base table or the records that result from running a query.

The Recordsets collection contains all open Recordset objects in a Database object.

Remarks

When you use data access objects, you interact with data almost entirely using Recordset objects.  All Recordset objects are constructed using records (rows) and fields (columns).  There are three types of Recordset objects:

Table-type Recordset [image] a representation in code of a base table that you can use to add, change, or delete records from a single database table.

Dynaset-type Recordset [image] the result of a query that can have updatable records.  A dynaset-type Recordset is a dynamic set of records that you can use to add, change, or delete records from an underlying database table or tables.  A dynaset-type Recordset can contain fields from one or more tables in a database.

Snapshot-type Recordset [image] a static copy of a set of records that you can use to find data or generate reports.  A snapshot-type Recordset can contain fields from one or more tables in a database but can't be updated.

You can choose the type of Recordset object you want to create using the type argument of the OpenRecordset method.  If you don't specify a type, the Microsoft Jet database engine attempts to create a table-type Recordset.  If this isn't possible, the Jet engine creates a dynaset-type or snapshot-type Recordset.

When creating a Recordset using a nonattached TableDef object, only table-type Recordset objects are created.  Only dynaset-type or snapshot-type Recordsets can be created with attached tables or tables in external ODBC databases.

The Type property indicates the type of Recordset created and the Updatable property indicates whether or not you can change the object's records.

A new Recordset is automatically added to the Recordsets collection when you open the object, and it's automatically removed when you close it.

Information about the structure of a base table, such as the names and field data types of each Field and any Index objects, is stored in a TableDef.

Note   If you use variables to represent a Recordset object and the Database object that contains the recordset, make sure the variables have the same scope, or lifetime.  For example, if you declare a global variable that represents a Recordset, make sure the variable that represents the database containing the recordset is also global or is declared in a Sub or Function procedure using the Static keyword.

Your application can create as many Recordset object variables as needed.  A Recordset can refer to one or more tables, queries alone, or queries referenced by other Recordset objects in any combination.  You can also have a Recordset that refers to some or all of the fields or records in other Recordset objects.

Dynaset- and snapshot-type Recordsets are stored in local memory. If there isn't enough space in local memory to store the data, the Jet engine saves the additional data to TEMP disk space.  If this space is exhausted, a trappable error occurs.

The default collection of a Recordset is the Fields collection, and the default property of a Field object is the Value property.  You can simplify your code by taking advantage of these defaults.  For example, the following lines of code all set the value of the PubID field in the current record of a Recordset:

MyTable.Fields("PubID").Value = 99

MyTable("PubID") = 99

MyTable!PubID = 99

When you create a Recordset, the current record is positioned to the first record if there are any records.  If there are no records, the RecordCount property setting is 0, and the BOF and EOF property settings are True.

You can use the MoveNext, MovePrevious, MoveFirst, and MoveLast methods to reposition the current record.  For dynaset-type and snapshot-type Recordsets, you can also use the Find methods, such as FindFirst, to locate a specific record based on a criterion.  If the record isn't found, the NoMatch property is set to True.

To cycle through all records, you can use the BOF and EOF properties to check for the beginning or end of the Recordset.  However, it may be faster to write an SQL query to perform operations that apply to an entire set of records.

You can have more than one Recordset object variable that refers to the same set of records.  Also, keep in mind that object variables created with the Dim statement in the Declarations section of a form exist only while the form is open and are closed when the form is unloaded.  In the same way, object variables created in a procedure exist only until the procedure has finished.  Explicitly complete any pending transactions or edits, and close all Recordset and Database objects before exiting or completing any procedure containing declarations for these data access objects.


Recordset Object, Recordsets Collection Summary

See Also	Specifics

Recordset Object

The Recordset object contains these collections, methods, and properties.

Collections

Fields

Parameters (default)

Recordset Methods

The following table lists recordset methods and which objects support them.

Note   Snapshot-type Recordset objects created when you use dbForwardOnly as the options argument with the OpenRecordset method don't support the methods and properties marked with an asterisk (*).  In addition, the Move method works only with forward moves that don't use a bookmark offset.

Recordset object types

Method	Dynaset	Snapshot	Table

AddNew

CancelUpdate

Clone	*

Close

CopyQueryDef

Delete

Edit

FillCache

FindFirst	*

FindLast	*

FindNext	*

FindPrevious	*

GetRows

Move

MoveFirst	*

MoveLast	*

MoveNext

MovePrevious	*

OpenRecordset	*

Requery

Seek

Update

Recordset Properties

The following table indicates which properties apply to each type of Recordset object and whether the property setting is read/write, read-only, or always False.

Note   Snapshot-type Recordset objects that are created when you use dbForwardOnly as the options argument with the OpenRecordset method don't support the methods and properties marked with an asterisk (*).  In addition, the Move method works only with forward moves that don't use a bookmark offset.

Read-only

Read/write

Recordset object types

Property	Dynaset	Snapshot	Table

AbsolutePosition	*

BOF

Bookmark	*

Bookmarkable	*

CacheSize

CacheStart

DateCreated

EditMode

EOF

Filter

Index

LastModified

LastUpdated

LockEdits

Name

NoMatch

PercentPosition	*

RecordCount

Restartable	False

Sort

Transactions	False

Type

Updatable	False

ValidateOnSet

ValidationRule

ValidationText

Value

Recordsets Collection

The Recordsets collection contains this method and this property.

Method

Refresh

Property

Count


NoMatch

PercentPosition	*

RecordCount

Restartable	False

Sort

Transactions	False

Type

Updatable	False

ValidateOnSet

ValidationRule

ValidationText

Value


Relation Object, Relations Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Relation object represents a relationship between fields in tables or queries.

A Relations collection contains stored Relation objects of a Database object.

Remarks

You can use the Relation object to create new relationships and examine existing relationships in your database.  By setting the Attributes property, you can also use the Microsoft Jet database engine to enforce referential integrity.

Any changes you make to the database that violate the relationships established for the database result in a trappable error.  If you request cascade update or cascade delete operations, the Jet database engine also modifies the primary or foreign key tables to enforce the relationships you establish.

An example of a typical relationship can be found between the NameAddress table and the ValidStateCodes table. The State field of the NameAddress table is the primary key, and the State field of the ValidStateCodes table is the foreign key.  For a new record to be accepted in the NameAddress table, the Jet engine searches the ValidStateCodes table for a match on the State field of the NameAddress table.  If no match is found, the Jet engine doesn't accept the new record, and a trappable error occurs.

Using a Relation object and its properties, you can:

Specify an enforced relationship between fields in base tables (but not a relationship that involves a query or an attached table).

Establish unenforced relationships between any type of table or query [image] native or attached.

Use the Name property to refer to the relationship between the fields in the referenced primary table and the referencing foreign table.

Use the Attributes property to determine whether the relationship between fields in the table is one-to-one or one-to-many and how to enforce referential integrity.

Use the Attributes property to determine whether the Microsoft Jet database engine can perform cascade update and cascade delete operations on primary and/or foreign tables.

Use the Attributes property to determine whether the relationship between fields in the table is left join or right join.

Notes

The Name property settings of all Field objects in the Fields collection of a Relation object represent the names of the fields in the primary key of the referenced table.  The ForeignName property settings of the Field objects represent the names of the fields in the foreign key of the referencing table.

When you enforce referential integrity, a unique index must already exist for the key field of the referenced table.  The Jet database engine automatically creates an index with the Foreign property set to act as the foreign key in the referencing table.

To create a new Relation object, use the CreateRelation method.


Relation Object, Relations Collection Summary

See Also	Specifics

Relation Object

The Relation object contains these collections, methods, and properties.

Collections

Fields (default)

Properties

Methods

CreateField

CreateProperty

Properties

Attributes

ForeignTable

Name

Table

Relations Collection

The Relations collection contains these methods and this property.

Methods

Append

Delete

Refresh

Property

Count


Snapshot-Type Recordset
Snapshot-Type Recordset Object

See Also	Example	Properties	Methods	Specifics

A snapshot-type Recordset object is a static set of records that you can use to examine data in an underlying table or tables.  A snapshot-type Recordset can contain fields from one or more tables in a database but can't be updated.

Remarks

When you create a snapshot-type Recordset, data values for all fields (except Memo and OLE Object field data types) are brought into memory.  Once loaded, changes made to base table data aren't reflected in the snapshot-type Recordset data.  To reload the snapshot-type Recordset with current data, use the Requery method, or re-execute the OpenRecordset method.

The order of snapshot-type Recordset data isn't guaranteed to follow any specific sequence.  To order your data, use an SQL statement with an ORDER BY clause to create the Recordset.  This technique can also be used to filter the records so that only certain records are added to the Recordset.  For example, the following code selects only titles whose name contains the string "VBSQL" and sorts the resulting records by ISBN:

Dim Db As Database, Rs As Recordset, SQL As String

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")

SQL$ = "SELECT * FROM Titles WHERE Title like '*VBSQL*' ORDER BY ISBN;"

Set Rs = Db.OpenRecordset(SQL$,dbOpenSnapshot)

Using this technique instead of the Filter or Sort properties or testing each record individually generally results in faster access to your data.

To create a snapshot-type Recordset, use the OpenRecordset on an open database, on another dynaset- or snapshot-type Recordset, or on a QueryDef object.

Snapshot-type Recordset objects are generally faster to create and access than dynaset-type Recordset objects because their records are either in memory or stored in TEMP disk space, and the Microsoft Jet database engine doesn't have to deal with page locking or multiuser issues.  However, snapshot-type Recordset objects consume more local resources than dynaset-type Recordset objects because the entire record is downloaded to local memory.


Table-type Recordset

See Also	Example	Properties	Methods	Specifics

A table-type Recordset object is a representation in code of a base table that you can use to add, change, or delete records from a table.  Only the current record is loaded into memory.  A predefined index is used to determine the order of the records in the Recordset object.

Remarks

To create a table-type Recordset, use the OpenRecordset method on an open Database object.

A table-type Recordset can be created with a Jet database base table but not with an ODBC or attached table.  The table-type Recordset can be used with ISAM databases (like FoxPro, dBASE, Paradox, or Btrieve) when opened directly.

Unlike dynaset- or snapshot-type Recordset objects, the table-type Recordset can't refer to more than one base table, and it can't be accessed using an SQL statement that filters or sorts the data.  Generally, when you access a table-type Recordset, you specify one of the predefined indexes for the table, which orders the data returned to your application.  If the table doesn't have an index, the order of the data returned can't be guaranteed.  If necessary, your application can create an index that returns records in a specific order.  To choose a specific order for your table-type Recordset, set the Index property to a valid index.

To maintain data integrity, table-type Recordset objects are locked during Edit and Update operations so that only one user can update a particular record at a time.  When the Microsoft Jet database engine locks a record, it locks the entire 2K page containing the record.

Two kinds of locking are used with non-ODBC tables [image] pessimistic and optimistic.  ODBC-accessed tables always use optimistic locking.  The locking conditions in effect during editing are determined by the LockEdits property.


TableDef Object, TableDefs Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A TableDef object represents the stored definition of a base table or an attached table.

A TableDefs collection contains all stored TableDef objects in a database.

Remarks

You manipulate a table definition using a TableDef object and its methods and properties.  For example, you can:

Examine the field and index structure of any local, attached, or external table in a database.

Read or write the Connect and SourceTableName property settings for attached tables, and use the RefreshLink method to update connections to attached tables.

Read (or write, if the Updatable property is set to True) the ValidationRule and ValidationText property settings to find (or specify) validation conditions.

Use the OpenRecordset method to create a table-, dynaset-, or snapshot-type Recordset object based on the table definition.

The default collection of a Database object is the TableDefs collection, and the default collection of a TableDef object is the Fields collection.  The default property of a TableDef is the Name property.  You can simplify your code by using these defaults.  For example, the following statements are identical in that they both print the number corresponding to the field data type of a Field in a TableDef using a Data control:

Print Data1.Database.TableDefs("Publishers").Fields("PubID").Type

Print Data1.Database("Publishers")("PubID").Type

The Name property of a TableDef object isn't the same as the name of an object variable to which it's assigned.

For base tables, the RecordCount property contains the number of records in the specified database table.  For attached tables the RecordCount property setting is always -1.

You refer to a TableDef object that you create and append to a TableDefs collection by its Name property setting using this syntax:

TableDefs("name")

To create a new TableDef object, use the CreateTableDef method.

To make changes in the structure of a table, such as adding a field

1.	Make sure any Recordset objects based on the table are closed by all users.

2.	Create a Field object variable and set its properties using the CreateField method.

3.	Add the Field to the Fields collection of the TableDef with the Append method.

To create a table that is ready for new records in a database

1.	Create a TableDef object using the CreateTableDef method.

2.	Set its properties.

3.	Create a Field object variable and set its properties using the CreateField method for each field in the table.

4. 	Add the fields to the Fields collection of the TableDef with the Append method.

5.	Use the Append method to add the new TableDef to the TableDefs collection of the Database.

An attached table is linked to the database by the SourceTableName and Connect properties of the TableDef object.

To attach a table to a database

1.	Create a TableDef object using the CreateTableDef method.

2.	Set its Connect and SourceTableName properties (and optionally, its Attributes property).

3.	Add it to the TableDefs collection of a Database with the Append method.

You can delete a Field from a TableDefs collection if it doesn't have any indexes assigned to it, but its underlying data is lost.

To change a table definition using Microsoft Access or in code

1.	Back up the table or field data.

2.	Delete a specified TableDef from the TableDefs collection or Field from the Fields collection (which also deletes the data).

3.	Create and append your revised TableDef or Field.

4.	Reload the data.


Tabledefs Obect, TableDefs Collection Summary

See Also	Specifics

TableDef Object

A TableDef object contains these collections, methods, and properties.

Collections

Fields (default)

Indexes

Properties

Methods

CreateField

CreateIndex

CreateProperty

OpenRecordset

RefreshLink

Properties

Attributes	RecordCount

Connect	SourceTableName

DateCreated	Updatable

LastUpdated	ValidationRule

Name	ValidationText

A TableDef object may also contain application-defined properties.  For details on reading and setting these properties, refer to the application's online Help.

TableDefs Collection

A TableDefs collection contains these methods and this property.

Methods

Append

Delete

Refresh

Property

Count


User Object, Users Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A User object represents a user account that has access permissions when a Workspace object operates as a secure workgroup.

A Users collection contains all stored User objects of a Workspace or group account.

Remarks

You create User objects, and then use their names to establish and enforce access permissions for your databases, tables, and queries using the Document objects that represent the database or database objects (tables and queries) you're working with.  Also, if you know the properties of a specific User object, you can create a new Workspace object that has the same access permissions as the User object.

You can append an existing User object to the Users collection of a Group object to give a user account the access permissions for that Group object.  Alternatively, you can append the Group object to the Groups collection in a User object to establish membership of the user account in that group.  If you use a Users or Groups collection other than the one to which you just appended an object, you may need to use the Refresh method.

Using the properties of a User object, you can:

Check the Name property setting of an existing User object to determine its name.  You can't check the PID and Password property settings of an existing User object.

Set the Name, PID, and Password properties of a newly created, unappended User object to establish the identity of that User object.  If you don't set the Password property, it's set to a zero-length string ("").

The Microsoft Jet database engine predefines two User objects named Admin and Guest.  The user Admin is a member of the Group objects named Admins and Users; the user Guest is a member only of the Group object named Guests.

You can refer to any other User object that you create and append to a Users collection by its Name property setting using this syntax:

Workspaces(n)|Group.Users("name")

To create a new User object, use the CreateUser method.


User Object, Users Collection Summary

See Also	Specifics

User Object

The User object contains these collections, methods, and properties.

Collections

Groups (default)

Properties

Methods

CreateGroup

NewPassword

Properties

Name

Password

PID

Users Collection

The Users collection contains these methods and this property.

Methods

Append

Delete

Refresh

Property

Count


Workspace Object, Workspaces Collection

See Also	Example	Properties	Methods	Specifics 	Summary

A Workspace object defines a session for a user.  It contains open databases and provides mechanisms for simultaneous transactions and for a secure workgroup.

The Workspaces collection contains all active, unhidden Workspace objects of the DBEngine object.

Remarks

Use the Workspace object to manage the current session or to start an additional session.  In a session, you can open multiple databases, manage transactions, and establish security based on user names and passwords.  For example, you can:

Create a Workspace object using the Name, Password, and UserName properties to establish a named, password-protected session.  The session creates a scope in which you can open multiple databases and conduct one instance of nested transactions.  Use the Close method to terminate a session.

Use the OpenDatabase method to open one or more existing databases on that Workspace.

Use the BeginTrans, CommitTrans, and Rollback methods to manage nested transaction processing within a Workspace and use several Workspace objects to conduct multiple, simultaneous, and overlapping transactions.

Use the IsolateODBCTrans property to isolate multiple transactions that involve the same ODBC database.

When you start the Jet database engine, you automatically create the default workspace, DBEngine.Workspaces(0).  The settings of the Name and UserName properties of the default workspace are "#Default Workspace#" and "Admin", respectively.  If security is enabled, the UserName property setting is the name of the user who logged on.  If you use the OpenDatabase method without specifying a Workspace object, the default DBEngine.Workspaces(0) is used.

When you use transactions, all databases in the specified Workspace are affected [image] even if multiple Database objects are opened in the Workspace.  For example, if you use a BeginTrans method, update several records in a database, and then delete records in another database, both the update and delete operations are rolled back when you use the Rollback method.  You can create additional Workspace objects to manage transactions independently across Database objects.

Workspace objects are created with the CreateWorkspace method of the DBEngine object.  Once created, new Workspace objects must be appended to the Workspaces collection if you need to refer to them from the Workspaces collection.  You can, however, use newly created Workspace objects without appending them to the Workspaces collection.

You can refer to any other Workspace object that you create and append to the collection by its Name property setting using this syntax:

Workspaces("name")

You can also refer to appended Workspace objects by their position in the Workspaces collection using this syntax (where n is the nth member of the Workspaces collection):

DBEngine.Workspaces(n)


Workspace Object, Workspaces Collection Summary

See Also	Specifics

Workspace Object

The Workspace object contains these collections, methods, and properties.

Collections

Databases (default)

Groups

Users

Methods

BeginTrans	CreateGroup

Close	CreateUser

CommitTrans	OpenDatabase

CreateDatabase	Rollback

Properties

Name

Password

UserName

Workspaces Collection

The Workspaces collection contains this method and property.

Method

Refresh

Property

Count


Container Object, Containers Collection and Document Object, Documents Collection Example

This example enumerates the properties of all the Container and Document objects in the current database.  See the properties listed in the Container and Document summary topics for additional examples.

Function EnumerateDocuments () As Integer

Dim MyDatabase As Database

Dim MyContainer As Container, MyDocument As Document

Dim I As Integer, J As Integer

Set MyDatabase = Workspaces(0).OpenDatabase("MyDB.MDB")

For J = 0 To MyDatabase.Containers.Count - 1

Set MyContainer = MyDatabase.Containers(J)

Debug.Print ">> Container: "; MyContainer.Name;

Debug.Print "  Owner: "; MyContainer.Owner

Debug.Print "  UserName: "; MyContainer.UserName;

Debug.Print "  Permissions: "; MyContainer.Permissions

Debug.Print

For I = 0 To MyContainer.Documents.Count - 1

Set MyDocument = MyContainer.Documents(I)

Debug.Print " > Document: "; MyDocument.Name;

Debug.Print "  Owner: "; MyDocument.Owner;

Debug.Print "  Container: "; MyDocument.Container

Debug.Print "  UserName: "; MyDocument.UserName;

Debug.Print "  Permissions: "; MyDocument.Permissions

Debug.Print "  DateCreated: "; MyDocument.DateCreated;

Debug.Print "  LastUpdated: "; MyDocument.LastUpdated

Debug.Print

Next I

Next J

EnumerateDocuments = True

End Function


Database Object, Databases Collection Example

This example creates a new Database object and opens it (thereby appending it to the Databases collection) in the default Workspace object.  Then it enumerates all the collections contained by each Database object and the properties of the new Database object and closes the new Database.  See the methods and properties listed in the Database summary topic for additional examples.

Function EnumerateDatabase () As Integer

Dim DefaultWorkspace As Workspace

Dim MyDatabase As Database, TempDatabase As Database

Dim I As Integer, J As Integer

Set DefaultWorkspace = Workspaces(0)

Set MyDatabase = DefaultWorkspace.CreateDatabase("MyDB.MDB", _  	dbLangGeneral)

' Enumerate all open databases.

For J = 0 To DefaultWorkspace.Databases.Count - 1

Set TempDatabase = DefaultWorkspace.Databases(J)

Debug.Print

Debug.Print "Enumeration of Databases("; J; "): "; TempDatabase.Name

Debug.Print

' Enumerate containers.

Debug.Print "Container: Name, Owner"

For I = 0 To TempDatabase.Containers.Count - 1

Debug.Print "  "; TempDatabase.Containers(I).Name;

Debug.Print ", "; TempDatabase.Containers(I).Owner

Next I

Debug.Print

' Enumerate query definitions.

Debug.Print "QueryDef: Name"

For I = 0 To TempDatabase.QueryDefs.Count - 1

Debug.Print "  "; TempDatabase.QueryDefs(I).Name

Next I

Debug.Print

' Enumerate recordsets.

' No output because no Recordset is open.

Debug.Print "Recordset: Name"

For I = 0 To TempDatabase.Recordsets.Count - 1

Debug.Print "  "; TempDatabase.Recordsets(I).Name

Next I

Debug.Print

' Enumerate relationships.

Debug.Print "Relation: Name, Table, ForeignTable"

For I = 0 To TempDatabase.Relations.Count - 1

Debug.Print "  "; TempDatabase.Relations(I).Name;

Debug.Print ", "; TempDatabase.Relations(I).Table;

Debug.Print ", "; TempDatabase.Relations(I).ForeignTable

Next I

Debug.Print

' Enumerate table definitions.

Debug.Print "TableDef: Name, DateCreated"

For I = 0 To TempDatabase.TableDefs.Count - 1

Debug.Print "  "; TempDatabase.TableDefs(I).Name;

Debug.Print ", "; TempDatabase.TableDefs(I).DateCreated

Next I

Debug.Print

Next J

' Enumerate built-in properties of MyDatabase.

Debug.Print "MyDatabase.Name: "; MyDatabase.Name

Debug.Print "MyDatabase.CollatingOrder: "; MyDatabase.CollatingOrder

Debug.Print "MyDatabase.Connect: "; MyDatabase.Connect

Debug.Print "MyDatabase.QueryTimeout: "; MyDatabase.QueryTimeout

Debug.Print "MyDatabase.Transactions: "; MyDatabase.Transactions

Debug.Print "MyDatabase.Updatable: "; MyDatabase.Updatable

Debug.Print "MyDatabase.V1xNullBehavior: "; MyDatabase.V1xNullBehavior

Debug.Print

MyDatabase.Close	' File remains on disk.

EnumerateDatabase = True

End Function


DBEngine Object Example

This example enumerates the collections of the DBEngine object.  See the methods and properties of DBEngine for additional examples.

Function EnumerateDBEngine () As Integer

Dim MyWorkspace As Workspace

Dim I As Integer

Debug.Print

Debug.Print "Enumeration of DBEngine"

Debug.Print

' Enumerate all workspaces.

Debug.Print "Workspaces: Name, UserName"

For I = 0 To Workspaces.Count - 1

Set MyWorkspace = Workspaces(I)

Debug.Print "  "; MyWorkspace.Name;

Debug.Print ", "; MyWorkspace.UserName

Next I

Debug.Print

' Enumerate built-in properties.

Debug.Print "DBEngine.Version: "; DBEngine.Version

Debug.Print "DBEngine.LoginTimeout: "; DBEngine.LoginTimeout

Debug.Print

EnumerateDBEngine = True

End Function


Dynaset-Type Recordset Example

This example creates a new dynaset-type Recordset object and opens it, appending it to the Recordsets collection in the default database.  It then edits the record(s).

Function ChangeSQL () As Integer

Dim MyDB As Database, MyData As Recordset

Dim I As Integer, J As Integer, SQL As String

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")

SQL$ = "Select * From Titles Where Title = 'Using SQL' "

Set MyData = MyDB.OpenRecordset(SQL$, dbOpenDynaset)

If MyData.RecordCount > 0 and MyData.Updatable Then

Do Until MyData.EOF

MyData.Edit

MyData![Year Published] = 1994	' Change year published.

MyData.Update

MyData.MoveNext

Loop

Else

Debug.Print "No such title or table not updatable"

End If

MyData.Close

MyDb.Close

ChangeSQL = True

End Function


Field Object, Fields Collection Example

This example creates a TableDef object and a Field object, appends the Field to the Fields collection in the new TableDef, and appends the TableDef to the TableDefs collection in the current database.  The example enumerates all the fields in the new TableDef object and all the properties of the new Field.  See the methods and properties listed in the Field summary topic for additional examples.

Function EnumerateField () As Integer

Dim MyDatabase As Database

Dim MyTableDef As TableDef

Dim MyField As Field

Dim I As Integer

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTableDef = MyDatabase.CreateTableDef("MyTable")

Set MyField = MyTableDef.CreateField("MyField", dbDate)

MyTableDef.Fields.Append MyField

MyDatabase.TableDefs.Append MyTableDef

' Get database name.

Debug.Print

Debug.Print "Database Name: "; MyDatabase.Name

Debug.Print

' Enumerate all fields in MyTableDef.

Debug.Print "TableDefs: Name; Fields: Name"

For I = 0 To MyTableDef.Fields.Count - 1

Debug.Print "  "; MyTableDef.Name;

Debug.Print "; "; MyTableDef.Fields(I).Name

Next I

Debug.Print

' Enumerate built-in properties of MyField.

Debug.Print "MyField.Name: "; MyField.Name

Debug.Print "MyField.AllowZeroLength: "; MyField.AllowZeroLength

Debug.Print "MyField.Attributes: "; MyField.Attributes

Debug.Print "MyField.CollatingOrder: "; MyField.CollatingOrder

Debug.Print "MyField.DefaultValue: "; MyField.DefaultValue

Debug.Print "MyField.OrdinalPosition: "; MyField.OrdinalPosition

Debug.Print "MyField.Required: "; MyField.Required

Debug.Print "MyField.Size: "; MyField.Size

Debug.Print "MyField.SourceField: "; MyField.SourceField

Debug.Print "MyField.SourceTable: "; MyField.SourceTable

Debug.Print "MyField.Type: "; MyField.Type

Debug.Print "MyField.ValidateOnSet: "; MyField.ValidateOnSet

Debug.Print "MyField.ValidationRule: "; MyField.ValidationRule

Debug.Print "MyField.ValidationText: "; MyField.ValidationText

EnumerateField = True

End Function


Group Object, Groups Collection; User Object, Users Collection Example
Group Object, Groups Collection and User Object, Users Collection Example

This example illustrates the use of the Group and User objects and the Groups and Users collections.  First it creates a new User object with the Name, PID, and Password property settings of "Pat Smith", "abc123DEF456", and "My Secret" and appends the object to the Users collection of the default Workspace object.  Next it creates a new Group object with the Name and PID property settings of "Accounting" and "UVW987xyz654" and appends the object to the Groups collection of the default Workspace object.  Then the example adds user Pat Smith to the Accounting group.  Finally, it enumerates the User and Group objects in the collections of the default Workspace object.  See the methods and properties listed in the Group and User summary topics for additional examples.

Function EnumerateUserGroup () As Integer

Dim MyWorkspace As Workspace

Dim MyUser As User, TempUser As User

Dim MyGroup As Group, TempGroup As Group

Dim I As Integer, J As Integer

' Create and append new user.

Set MyWorkspace = Workspaces(0)

Set MyUser = MyWorkspace.CreateUser("Pat Smith", "abc123DEF456", "My Secret")

MyWorkspace.Users.Append MyUser

' Create and append new group.

Set MyGroup = MyWorkspace.CreateGroup("Accounting", "UVW987xyz654")

MyWorkspace.Groups.Append MyGroup

' Add new user to new group or converse (do one or the other).

' Use Refresh because both collections are referred to in following code.

' Either add user to group and refresh user.

Set MyUser = MyWorkspace.CreateUser("Pat Smith")

MyWorkspace.Groups![Accounting].Users.Append MyUser

MyWorkspace.Users![Pat Smith].Groups.Refresh

' Or add group to user and refresh group.

'  Set MyGroup = MyWorkspace.CreateGroup("Accounting")

'  MyWorkspace.Users![Pat Smith].Groups.Append MyGroup

'  MyWorkspace.Groups![Accounting].Users.Refresh

' Enumerate all users.

For J = 0 To MyWorkspace.Users.Count - 1

Set TempUser = MyWorkspace.Users(J)

Debug.Print

Debug.Print "Enumeration of Users("; J; "): "; TempUser.Name

Debug.Print

' Enumerate groups.

Debug.Print "Group: Name"

For I = 0 To TempUser.Groups.Count - 1

Debug.Print "  "; TempUser.Groups(I).Name

Next I

Next J

' Enumerate all groups.

For J = 0 To MyWorkspace.Groups.Count - 1

Set TempGroup = MyWorkspace.Groups(J)

Debug.Print

Debug.Print "Enumeration of Groups("; J; "): "; TempGroup.Name

Debug.Print

' Enumerate users.

Debug.Print "User: Name"

For I = 0 To TempGroup.Users.Count - 1

Debug.Print "  "; TempGroup.Users(I).Name

Next I

Next J

EnumerateUserGroup = True

End Function


Index Object, Indexes Collection Example

This example creates a new TableDef object and two new Field objects, appends the Field objects to the Fields collection in the new TableDef, and appends the TableDef to the TableDefs collection in the database.  Then it creates a new primary Index object, includes the two Field objects in it, and appends the Index to the Indexes collection of the TableDef.  Finally, the example enumerates the Index objects in the current database.  See the methods and properties listed in the Index summary topic for additional examples.

Function EnumerateIndex () As Integer

Dim  MyDatabase As Database

Dim MyTableDef As TableDef

Dim MyField As Field, MyIndex As Index

Dim I As Integer

' Get workspace and database.

Set MyDatabase = Workspaces(0).OpenDatabase("MyDB.MDB")	' Create table with two fields.

Set MyTableDef = MyDatabase.CreateTableDef("MyTable")

Set MyField = MyTableDef.CreateField("Field1", dbLong)

MyField.Required = True	' No Null values allowed.

MyTableDef.Fields.Append MyField

Set MyField = MyTableDef.CreateField("Field2", dbLong)

MyField.Required = True	' No Null values allowed.

MyTableDef.Fields.Append MyField

MyDatabase.TableDefs.Append MyTableDef

' Create primary index for those two fields.

Set MyIndex = MyTableDef.CreateIndex("MyIndex")

MyIndex.Primary = True

MyIndex.Unique = True

Set MyField = MyTableDef.CreateField("Field1")

MyIndex.Fields.Append MyField

Set MyField = MyTableDef.CreateField("Field2")

MyIndex.Fields.Append MyField

MyTableDef.Indexes.Append MyIndex

' Enumerate index and its fields.

Debug.Print "Index: "; MyIndex.Name

Debug.Print "  Required: "; MyIndex.Required

Debug.Print "  IgnoreNulls: "; MyIndex.IgnoreNulls

Debug.Print "  Primary: "; MyIndex.Primary

Debug.Print "  Clustered: "; MyIndex.Clustered

Debug.Print "  Unique: "; MyIndex.Unique

Debug Print "  Foreign: "; MyIndex.Foreign

Debug.Print

Debug.Print "Fields in Index: ";

For I = 0 To MyIndex.Fields.Count - 1

Debug.Print " "; MyIndex.Fields(I).Name;

Next I

Debug.Print

EnumerateIndex = True

End Function

This example opens a table-type Recordset and selects an index for the Recordset.  By setting an index, the Microsoft Jet database engine returns records in the order specified by the index.  Without an index, table-type Recordset objects return records from the database table in no particular order.

Dim Db As Database

Dim MyTable as Recordset, MyIndex As Index

Dim I As Integer

' Get workspace and database.

Set Db = Workspaces(0).OpenDatabase("MyDB.MDB")

Set MyTable = Db.OpenRecordset("Titles", dbOpenTable)

MyTable.Index = "MyIndex"

.

.

.


Parameter Object, Parameters Collection Example

This example creates two query parameters for an existing query, runs the query by opening a Recordset from the QueryDef, and then prints the properties of each parameter.  The parameter data types are of type Date.  See the methods and properties listed in the Parameter summary topic for additional examples.

Dim MyDB As Database

Dim MyQuery As QueryDef, MyParameter As Parameter

Dim MyRecordset As Recordset

Dim X As Integer

Set MyDB = Workspaces(0).Databases(0)

Set MyQuery = MyDB.QueryDefs("ParamQuery")	' Open existing
' QueryDef.

MyQuery.Parameters("Order Date") = "10/11/94"	' Set parameters.

MyQuery.Parameters("Ship Date") = "11/4/94"

Set MyRecordset = MyQuery.OpenRecordset()	' Open Recordset.

For X = 0 To MyQuery.Parameters.Count - 1

Set MyParameter = MyQuery.Parameters(X)

Debug.Print MyParameter.Name	' Print parameter properties.

Debug.Print MyParameter.Type

Debug.Print MyParameter.Value

Next X

MyRecordset.Close


Property Object, Properties Collection Example

This example creates a user-defined property for the current database, sets its Type and Value properties, and appends it to the Properties collection of the database.  Then the example enumerates all properties in the database.  See the properties listed in the Property summary topic for additional examples.

Function EnumerateProperty () As Integer

Dim DefaultWorkspace As Workspace

Dim MyDatabase As Database, MyProperty As Property

Dim I As Integer

' Get default workspace and current database.

Set DefaultWorkspace = Workspaces(0)

Set MyDatabase = Workspaces(0).OpenDatabase("MyDB.MDB")

' Create user-defined property.

Set MyProperty = MyDatabase.CreateProperty()

' Set properties of new property.

MyProperty.Name = "UserDefinedProperty"

MyProperty.Type = dbText

MyProperty.Value = "This is a user-defined property."

' Append property to current database.

MyDatabase.Properties.Append MyProperty

' Enumerate all properties of current database.

Debug.Print "Properties of Database "; MyDatabase.Name

For I = 0 To MyDatabase.Properties.Count - 1

Set MyProperty = MyDatabase.Properties(I)

Debug.Print

Debug.Print " Properties("; I; ")"

Debug.Print "  Name: "; MyProperty.Name

Debug.Print "  Type: "; MyProperty.Type

Debug.Print "  Value: "; MyProperty.Value

Debug.Print "  Inherited: "; MyProperty.Inherited

Next I

Debug.Print

EnumerateProperty = True

End Function

This example shows how you can set an application-defined property (or any user-defined property that may not yet exist) without causing a run-time error.  The example sets an arbitrary property of a Field object.  The return value of the function is True if the value was properly set.  The return value is False if an unexpected error occurs when the property is set.  See the properties listed in the Property summary topic for additional examples.

Function SetFieldProperty (MyField As Field, PropertyName As String, PropertyType As Integer, PropertyValue As Variant) As Integer

Const ERR_PROPERTY_NONEXISTENT = 3270

Dim MyProperty As Property

On Error Resume Next	' Function handles errors.

SetFieldProperty = True

MyField.Properties(PropertyName) = PropertyValue

If Err <> 0 Then	' Error occurred when value was set.

If Err <> ERR_PROPERTY_NONEXISTENT

On Error GoTo 0

SetFieldProperty = False

Else

' Create Property object, setting its Name, Type, and Value properties.

On Error Resume Next

Set MyProperty = MyField.CreateProperty(PropertyName, PropertyType, PropertyValue)

MyField.Properties.Append MyProperty

If Err <> 0 Then

SetFieldProperty = False

End If

On Error GoTo 0

End If

End If

End Function


QueryDef Object, QueryDefs Collection Example

This example creates a new QueryDef object and appends it to the QueryDefs collection in the current database.  Then the example enumerates all the QueryDef objects in the database and all the properties of the new QueryDef.  See the methods and properties listed in the QueryDef summary topic for additional examples.

Function EnumerateQueryDef () As Integer

Dim MyWorkspace As Workspace, MyDB As Database, MyQuery As QueryDef

Dim I As Integer

Set MyWorkspace = Workspaces(0)

Set MyDB = MyWorkspace.OpenDatabase("MyDB.MDB")

Set MyQuery = MyDB.CreateQueryDef("This is a test")

Debug.Print

' Enumerate QueryDef objects.

Debug.Print

For I = 0 To MyDB.QueryDefs.Count - 1

Debug.Print MyDB.QueryDefs(I).Name

Next I

Debug.Print

' Enumerate built-in properties of MyQuery.

Debug.Print "MyQuery.Name: "; MyQuery.Name

Debug.Print "MyQuery.DateCreated: "; MyQuery.DateCreated

Debug.Print "MyQuery.LastUpdated: "; MyQuery.LastUpdated

Debug.Print "MyQuery.SQL: "; MyQuery.SQL

Debug.Print "MyQuery.ODBCTimeout: "; MyQuery.ODBCTimeout

Debug.Print "MyQuery.Updatable: "; MyQuery.Updatable

Debug.Print "MyQuery.Type: "; MyQuery.Type

Debug.Print "MyQuery.Connect: "; MyQuery.Connect

Debug.Print "MyQuery.ReturnsRecords: "; MyQuery.ReturnsRecords

MyDB.QueryDefs.Delete "This is a test"

EnumerateQueryDef = True

End Function


Recordset Object, Recordsets Collection Example

This example creates a new Recordset object and opens it (thereby appending it to the Recordsets collection) in the default database.  Then the example enumerates all the Recordset objects in the current database and all the fields in each Recordset object and closes the new Recordset.  See the methods and properties in the Recordset summary topic for additional examples.

Function EnumerateRecordset () As Integer

Dim MyDB As Database, MyData As Recordset, TempRecordset As Recordset

Dim I As Integer, J As Integer

Set MyDB = Workspaces(0).OpenDatabase("MyDB.MDB")

Set MyData = MyDB.OpenRecordset("Orders", dbOpenSnapshot)

Debug.Print

' Enumerate all Recordset objects.

For J = 0 To MyDB.Recordsets.Count - 1

Set TempRecordset = MyDB.Recordsets(J)

Debug.Print

Debug.Print "Enumeration of Recordset objects("; J; "): "; TempRecordset.Name

Debug.Print

' Enumerate fields.

Debug.Print "Fields: Name, Type, Value"

For I = 0 To TempRecordset.Fields.Count - 1

Debug.Print "  "; TempRecordset.Fields(I).Name

Debug.Print ", "; TempRecordset.Fields(I).Type

If TempRecordset.Fields(I).Type = dbText Then

Debug.Print ", "; TempRecordset.Fields(I).Value

End if

Next I

Next J

MyData.Close

MyDB.Close

EnumerateRecordset = True

End Function


Relation Object, Relations Collection Example

This example creates a one-to-many relationship between single fields in two tables.  Because referential integrity is enforced for the relationship, an index is created for the primary table.  See the methods and properties listed in the Relation summary topic for additional examples.

Function EnumerateRelation () As Integer

Dim MyDatabase As Database

Dim MyTableDef As TableDef, MyField As Field

Dim MyIndex As Index, MyRelation As Relation

Dim I As Integer

' Get database.

Set MyDatabase = Workspaces(0).OpenDatabase("MyDB.MDB")

' Create referenced table with primary key.

Set MyTableDef = MyDatabase.CreateTableDef("Referenced")

Set MyField = MyTableDef.CreateField("PrimaryKey", dbLong)

MyTableDef.Fields.Append MyField

' Create unique index for enforced referential integrity.

Set MyIndex = MyTableDef.CreateIndex("UniqueIndex")

MyIndex.Primary = True ' No Null values allowed.

Set MyField = MyTableDef.CreateField("PrimaryKey")

MyIndex.Fields.Append MyField

MyTableDef.Indexes.Append MyIndex

MyDatabase.TableDefs.Append MyTableDef

' Create referencing table with foreign key.

Set MyTableDef = MyDatabase.CreateTableDef("Referencing")

Set MyField = MyTableDef.CreateField("ForeignKey", dbLong)

MyTableDef.Fields.Append MyField

MyDatabase.TableDefs.Append MyTableDef

' Create one-to-many relationship and enforce referential integrity.

Set MyRelation = MyDatabase.CreateRelation("EnforcedOneToMany")

MyRelation.Table = "Referenced"

MyRelation.ForeignTable = "Referencing"

' Don't set either dbRelationUnique or dbRelationDontEnforce.

MyRelation.Attributes = 0

Set MyField = MyRelation.CreateField("PrimaryKey")

MyField.ForeignName = "ForeignKey"

MyRelation.Fields.Append MyField

MyDatabase.Relations.Append MyRelation

' Enumerate relation and its fields.

Debug.Print "Relation: "; MyRelation.Name

Debug.Print "  Primary Table: "; MyRelation.Table

Debug.Print "  Foreign Table: "; MyRelation.ForeignTable

Debug.Print "  Attributes: "; MyRelation.Attributes

Debug.Print "Fields in Relation: Primary, Foreign";

For I = 0 To MyRelation.Fields.Count - 1

Set MyField = MyRelation.Fields(I)

Debug.Print "  "; MyField.Name;

Debug.Print ", "; MyField.ForeignName

Next I

Debug.Print

MyDatabase.Relations.Delete "EnforcedOneToMany"

MyDatabase.TableDefs.Delete "Referenced"

MyDatabase.TableDefs.Delete "Referencing"

EnumerateRelation = True

End Function


Snapshot-Type Recordset Example

This example creates a new snapshot-type Recordset object and opens it, appending it to the Recordsets collection in the default database.  It then finds a record and prints it.

Function ShowVBSQL () As Integer

Dim MyDB As Database, MyData As Recordset

Dim I As Integer, J As Integer

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Set MyData = MyDB.OpenRecordset(Titles, dbOpenSnapshot)

If MyData.RecordCount > 0 Then

MyData.FindFirst "Title Like '*VBSQL*'"  ' Any title on VBSQL

Do until MyData.NoMatch = True

Debug.Print MyData!Title

MyData.FindNext "Title Like '*VBSQL*'"

Loop

Else

Debug.Print "No such title"

End If

MyData.Close

MyDb.Close

ShowVBSQL = True

End Function


Table-Type Recordset Example

This example opens a table-type Recordset and selects an index for the Recordset.  By setting an index, the Microsoft Jet database engine returns records in the order specified by the index.  Without an index, table-type Recordset objects return records from the database table in no particular order.

Dim Db As Database

Dim MyTable as Recordset, MyIndex As Index

Dim I As Integer

' Get workspace and database.

Set Db = Workspaces(0).OpenDatabase("MyDB.MDB")

Set MyTable = Db.OpenRecordset("Titles", dbOpenTable)

MyTable.Index = "MyIndex"

.

.

.


TableDef Object, TableDefs Collection Example

This example creates a new TableDef object, adds a Field object to it, and appends the TableDef to the TableDefs collection in the current database.  Then the example enumerates all the TableDef objects in the current database and all the properties of the new TableDef.  See the methods and properties listed in the TableDef summary topic for additional examples.

Function EnumerateTableDef () As Integer

Dim MyDatabase As Database

Dim MyTableDef As TableDef

Dim MyField As Field

Dim I As Integer

Set MyDatabase = Workspaces(0).OpenDatabase("MyDB.MDB")

Set MyTableDef = MyDatabase.CreateTableDef("MyTable")

Set MyField = MyTableDef.CreateField("MyField", dbDate)

MyTableDef.Fields.Append MyField

MyDatabase.TableDefs.Append MyTableDef

' Get database name.

Debug.Print "Database Name: "; MyDatabase.Name

' Enumerate all fields in MyTableDef.

Debug.Print "TableDef: Name; Field: Name"

For I = 0 To MyTableDef.Fields.Count - 1

Debug.Print "  "; MyTableDef.Name;

Debug.Print "; "; MyTableDef.Fields(I).Name

Next I

Debug.Print

' Enumerate all indexes in MyTableDef.

Debug.Print "TableDef: Name; Index: Name"

For I = 0 To MyTableDef.Indexes.Count - 1

Debug.Print "  "; MyTableDef.Name;

Debug.Print "; "; MyTableDef.Indexes(I).Name

Next I

Debug.Print

' Enumerate built-in properties of MyTableDef.

Debug.Print "MyTableDef.Name: "; MyTableDef.Name

Debug.Print "MyTableDef.Attributes: "; MyTableDef.Attributes

Debug.Print "MyTableDef.Connect: "; MyTableDef.Connect

Debug.Print "MyTableDef.DateCreated: "; MyTableDef.DateCreated

Debug.Print "MyTableDef.LastUpdated: "; MyTableDef.LastUpdated

Debug.Print "MyTableDef.RecordCount: "; MyTableDef.RecordCount

Debug.Print "MyTableDef.SourceTableName: "; MyTableDef.SourceTableName

Debug.Print "MyTableDef.Updatable: "; MyTableDef.Updatable

Debug.Print "MyTableDef.ValidationRule: "; MyTableDef.ValidationRule

Debug.Print "MyTableDef.ValidationText: "; MyTableDef.ValidationText

EnumerateTableDef = True

End Function


Workspace Object, Workspaces Collection Example

This example creates a new Workspace and appends it to the Workspaces collection.  It assumes that the user JustAUser with a password of Secret has already been created.  The example enumerates the collections of each Workspace object and finally closes the new Workspace.  See the methods and properties of the Workspace object or Workspaces collection for additional examples.

Function EnumerateWorkspace () As Integer

Dim AnyWorkspace As Workspace, NewWorkspace As Workspace

Dim I As Integer, J As Integer

' Create new workspace and add it to collection.

Set NewWorkspace = DBEngine.CreateWorkspace("NewWorkspace", "JustAUser", "Secret")

DBEngine.Workspaces.Append NewWorkspace

' Enumerate all workspaces.

For J = 0 To DBEngine.Workspaces.Count - 1

Set AnyWorkspace = DBEngine.Workspaces(J)

Debug.Print

Debug.Print "Enumeration of Workspaces("; J; "): "; AnyWorkspace.Name

Debug.Print

' Enumerate databases.

Debug.Print "Databases: Name"

For I = 0 To AnyWorkspace.Databases.Count - 1

Debug.Print "  "; AnyWorkspace.Databases(I).Name

Next I

' Enumerate all user accounts.

Debug.Print "Users: Name"

For I = 0 To AnyWorkspace.Users.Count - 1

Debug.Print "  "; AnyWorkspace.Users(I).Name

Next I

Debug.Print

' Enumerate all group accounts.

Debug.Print "Groups: Name"

For I = 0 To AnyWorkspace.Groups.Count - 1

Debug.Print "  "; AnyWorkspace.Groups(I).Name

Next I

Debug.Print

Next J

Debug.Print

' Enumerate built-in properties of NewWorkspace.

Debug.Print "NewWorkspace.Name: "; NewWorkspace.Name

Debug.Print "NewWorkspace.UserName: "; NewWorkspace.UserName

Debug.Print

NewWorkspace.Close

EnumerateWorkspace = True

End Function


Accessing Data in a Microsoft Excel Worksheet or Workbook

See Also	Example	Specifics

You can either attach Microsoft Excel worksheets and workbooks to your Microsoft Jet database or open them directly.  The procedures for accessing the data in Microsoft Excel files (versions 3.0, 4.0, or 5.0) are similar to the procedures used to access data in other external data sources.

Attaching a Worksheet

To attach an Microsoft Excel worksheet or workbook as a table in your Jet database, use the OpenDatabase method to identify the location of your .MDB database and set the TableDef  object to specify the location of the Microsoft Excel file.  You can specify either the named range within a worksheet, the entire worksheet, or the entire workbook.  The following example shows how to attach a named range in an external Microsoft Excel worksheet:

Dim CurrentDatabase As Database

Dim MyTableDef As TableDef

'Open Microsoft Jet database named MYDB.MDB.

Set CurrentDatabase = OpenDatabase("MYDB.MDB")

'Create TableDef.

Set MyTableDef = CurrentDatabase.CreateTableDef("February")

'Attach Microsoft Excel table Third Quarter Sales in worksheet.

'C:\EXCEL\EXAMPLES\SALES.XLS.

MyTableDef.Connect = "EXCEL 5.0; Database=C:\EXCEL\EXAMPLES\SALES.XLS"

MyTableDef.SourceTableName = "February"

'Append TableDef to create link.

CurrentDatabase.TableDefs.Append MyTableDef

Opening a Worksheet

If you want to use a table-type Recordset object with your Microsoft Excel worksheet or workbook, you must open the Microsoft Excel file directly using the OpenDatabase method.  The following example shows how to directly open an external Microsoft Excel worksheet and create a Recordset from the table:

Dim CurrentDatabase As Database

Dim MySet As Recordset

'Open external Microsoft Excel worksheet table.

Set CurrentDatabase = OpenDatabase("C:\EXCEL\EXAMPLES\SALES.XLS", _

  False, False, "EXCEL 5.0;")

'Create Recordset from Sales worksheet.

Set MySet = CurrentDatabase.OpenRecordset("February",dbOpenTable)

How to Reference Tables, Fields and Records

You can reference either an entire Microsoft Excel workbook, one or more worksheets within a workbook, or a named range of cells within a worksheet.  Unnamed ranges (for example, A1:B5) can't be referenced.  To reference an entire workbook, enter the path and filename (for example, C:\EXCEL\SALES.XLS).  If you want to open one or more worksheets, add the sheet names to the filename ( for example, C:\EXCEL\SALES.XLS$SHEET1:SHEET3).  The Jet engine doesn't recognize the exclamation point (!); it uses the dollar sign ($) instead.  For example, the worksheet name "SHEET!NAME" is shown as table "SHEET$NAME."

If you want to reference only a range of cells with a worksheet, be sure to name the range before attempting to open or attach it.  You can name a range of cells by highlighting the range, choosing Insert Name Define from the menu, and entering the name of the range (for example, ThirdQtrSales).  The name you enter becomes the name of the data table attached or opened using the Microsoft Excel ISAM.  You can't directly reference individual fields and records in an Microsoft Excel data table.

Special Caveats for Using Microsoft Excel Worksheets

You can't delete rows from Microsoft Excel worksheets.  You can directly modify, add, or clear data from individual cells in the worksheet, but you can't modify cells that contain formulas.  Also, you can't create indexes.  Because the Jet engine doesn't support multiple users of an Microsoft Excel worksheet, worksheets are opened exclusively for a single user.  Data that has been encrypted in Microsoft Excel can't be read by the Microsoft Excel driver.  If the Jet engine encounters encrypted data, the attachment fails.  You can't create indexes for your Microsoft Excel tables.  If the Jet engine encounters encrypted data, it returns a NULL value.

Benefits/problems with Using an Microsoft Excel Worksheet

Directly attaching or opening the Microsoft Excel worksheets and workbooks allows other Microsoft Excel users to continue accessing the files from their own applications.

Customizing your .INI File

You must customize your .INI file to include the [Excel ISAM] heading.  The .INI filename you use is set by the INIPath property of the DBEngine object. The information entered into this section initializes the settings for the MSXL2016.DLL driver.  The same parameters are used for all versions of Microsoft Excel.  The following is an example of the heading and settings in the .INI file:

[Excel ISAM]

TypeGuessRows=8

AppendBlankRows=4

FirstRowHasNames=Yes

Heading	Use for

TypeGuessRows	The number of rows to be checked for data type.  The data type is determined by the maximum number of kinds of data found.  If there is a tie, the data type is determined in the following order:  number, currency, date, text, Boolean.  If data is encountered that doesn't match the data type guessed for the column, it is returned as a NULL value.

AppendBlankRows	The number of rows to be inserted into the table.  Tables specified by a named range increase as new data is added.  If any new data would overwrite existing data in a worksheet (outside the named range that represents the data), an error is returned.

FirstRowHasNames	Yes or no indicator.  Yes indicates that the first row of the table contains column names; during export column names are exported as the first row.  No indicates no column names in the first row; column names appear as numbers (1, 2, 3, and so on).


Accessing Data in a Text Document

See Also	Example	Specifics

You can either attach or directly open text files, which can be stored in either fixed-width or delimited format.  The procedures for retrieving the data in text files are similar to those used to access data in other external data sources.  However, unlike other database types, text databases have no standard schema or structure that you can determine by inspection.  For this reason, you need to create a SCHEMA.INI that describes your text file database so that the ISAM driver can manipulate the data.

Generally, the ability to access text files is provided so you can import existing text files into your Microsoft Jet database or to export Jet or other attached database tables to text files.  You shouldn't access text files in order to establish attached text databases that can be simultaneously accessed like other attached database tables.

Special Caveats for Using Text Files

A text file can only be opened for a single user, because the Jet engine doesn't support multiple users of text files.  When referencing a text file, you must work with the entire file; you can't reference single fields or records within the file.

You can read both delimited and fixed-width text files.  The Jet engine recognizes commas, tabs, and custom delimiters when dealing with delimited text data, but you must use the same delimiter consistently.  Null data is denoted by two consecutive delimiters.  For example, if your delimiter is a double quote ("), two double quotes ("") denotes a Null value.  If you are using fixed-width data, you can specify the format of the data in a SCHEMA.INI file (see below).  Null fixed-width data is represented as spaces.

Tables are limited to a maximum of 256 columns.  Column names are limited to 64 characters, and column widths are limited to 65,500 characters.  Rows are limited to 65,543 bytes.

Attaching a Text File

To attach a text file as a table in your Jet database, use the OpenDatabase method to identify the location of your .MDB database and set the TableDef object to specify the location of the text file.  The following example shows how to attach an external text file:

Dim CurrentDatabase As Database

Dim MyTableDef As TableDef

'Open Microsoft Jet database named MYDB.MDB.

Set CurrentDatabase = OpenDatabase("C:\DATABASES\MYDB.MDB")

'Create TableDef.

Set MyTableDef = CurrentDatabase.CreateTableDef("MONTHS")

'Set connection information.

MyTableDef.Connect = "Text;Database=C:\TEXT\DATA\"

MyTableDef.SourceTableName = "MONTHS"

'Append TableDef to create link.

CurrentDatabase.TableDefs.Append MyTableDef

Opening a Text File

If you want to use table-type Recordset with your text file, you must open the file directly using the OpenDatabase method.  The following example shows how to directly open an external text file and create a Recordset object from the table:

Dim CurrentDatabase As Database

Dim MySet As Recordset

'Open external text data file.

Set CurrentDatabase = OpenDatabase("C:\TEXT\DATA",  _

  False, False, "Text;")

'Create Recordset from Awards table.

Set MySet = CurrentDatabase.OpenRecordset("MONTHS")

Customizing your .INI File

You must customize your .INI file to include the [Text ISAM] heading and the type of text file.  The .INI filename you use is set by the DBEngine INIPath property. The information entered into this section initializes the settings for the MSTX2016.DLL driver.  The following is an example of the heading and settings in the .INI file:

[Text ISAM]

Extensions=none,asc,csv,tab,txt

ColNameHeader=False

Format=TabDelimited

MaxScanRows=25

CharacterSet=OEM

Heading	Use for

Extensions	The name of the file extension for the text file.

ColNameHeader	True or False, indicating whether the first record of data is used for the column names.  Yes or no indicator.  Yes indicates that the first row of the table contains column names; during export column names are exported as the first row.  No indicates no column names in the first row; column names appear as numbers (1, 2, 3, and so on).

Format	TabDelimited, CSVDelimited, Delimited(<single character >), or FixedLength.  The single-character delimiter in the Delimited format can be any single character except a double quote (").

MaxScanRows	Number of rows to be scanned when guessing the column types.  If set to 0, the entire file is searched.

CharacterSet	OEM or ANSI, indicating whether the source file is written using an OEM or ANSI code page.

Customizing the SCHEMA.INI File

To import or export text data, you need to create a SCHEMA.INI file in addition to including the Text ISAM information in the .INI file.  SCHEMA.INI contains the specifics of a text data source: how the text file is formatted, how it is read at import time, and the default export format for files.  The following examples show the layout for a fixed-width file, FILENAME.TXT:

[FILENAME.TXT]

ColNameHeader=False

Format=FixedLength

MaxScanRows=25

CharacterSet=OEM

Col1=columnname Char Width 24

Col2=columnname2 Date(dd.mmm.yy) Width 9

Col3=columnname3 Date (mm-dd-yy) Width 8

Col4=columnname4 Date (mmm.dd.yy) Width 9

Col5=columnname5 Date (yyyy-mm-dd) Width 10

Col6=columnname6 Date (yyyy-mmm-dd) Width 11

Col7=columnname7 Float Width 10

Col8=columnname8 Integer Width 10

Col9=columnname9 LongChar Width 10

Similarly, the format for a delimited file is specified as:

[DELIMIT.TXT]

ColNameHeader=True

Format=Delimited(!)

MaxScanRows=0

CharacterSet=OEM

Col1=username char width 50

Col2=dateofbirth Date (dd-mmm-yy) width 9

If you are exporting data into a delimited text file, specify the format for that file as well:

[Export: My Special Export]

ColNameHeader=True

Format=TabDelimited

MaxScanRows=25

CharacterSet=OEM

DateTimeFormat=mm.dd.yy:hh.mm.ss

CurrencySymbol=Dm

CurrencyFormat=0

CurrencyDigits=2

CurrencyNegativeFormat=0

DecimalSymbol=,

NumberDigits=2

NumberLeadingZeros=0

The FILENAME.TXT and DELIMIT.TXT examples above represent text files specified at setup time.  The My Special Export example refers to a specific export option; you can specify any variation of export options at connect time.  This last example also corresponds to a data source name (DSN) that can be optionally passed at connect time.  All three format sections can be included in the same .INI file.

The Jet engine uses the SCHEMA.INI entries as follows.

Entry	Description

ColNameHeader	Can be set to either True (indicating that the first record of data specifies the column names) or False.

Format	Can be set to one of the following values:  TabDelimited, CSVDelimited, Delimited(<single character delimiter), or FixedLength.  The delimiter specified for the Delimited file format can be any single character except a double quotation mark (").

MaxScanRows	Indicates the number of rows to be scanned when guessing the column data types.  If this is set to 0, the entire file is searched.

CharacterSet	Can be set to OEM or ANSI, indicating whether the source file is written using an OEM or ANSI code page.

DateTimeFormat	Can be set to a format string indicating dates and times.  This entry should be specified if all date/time fields in the import/export are handled with the same format.  All of the Jet engine formats except AM and PM are supported.  In the absence of a format string, the Control Panel short date picture and time options is used.

CurrencySymbol	Indicates the currency symbol to be used for currency values in the text file.  Examples include the dollar sign or Dm.  If this entry is absent, the default value in the Control Panel is used.

CurrencyFormat	Can be set to any of the following values:

0: Currency symbol prefix with no separation ($1)
1: Currency symbol suffix with no separation (1$)
2: Currency symbol prefix with one character separation ($ 1)
3: Currency symbol suffix with one character separation (1 $)

If this entry is absent, the default value in the Control Panel is used.

CurrencyDigits	Specifies the number of digits used for the fractional part of a currency amount.  If this entry is absent, the default value in the Control Panel is used.

CurrencyNegativeFormat	Can be one of the following values:

0: ($1)
1: $1
2: $1
3: $1
4: (1$)
5: 1$
6: 1$
7: 1$
8: 1 $
9: $ 1
10: 1 $
11: $ 1
12: $ 1
13: 1 $
14: ($ 1)
15: (1 $)

The dollar sign is shown for purposes of this example, but it should be replaced with the appropriate CurrencySymbol value in the actual program.  If this entry is absent, the default value in the Control Panel is used.

DecimalSymbol	Can be set to any single character that is used to separate the integer from the fractional part of a number.  If this entry is absent, the default value in the Control Panel is used.

NumberDigits	Indicates the number of decimal digits in the fractional portion of a number.  If this entry is absent, the default value in the Control Panel is used.

NumberLeadingZeros	Specifies whether a decimal value less than 1 and greater than  1 should contain leading zeros; this value can either be 0 (no leading zeros) or 1.

Col1, Col2, ...	Lists the columns in the text file to be read.  The format of this entry should be:

Coln=columnName type [Width #]

columnName: Column names with embedded spaces should be enclosed in quotation marks.

type: Can be Bit, Byte, Short, Long, Currency, Single, Double, DateTime, Text, or Memo.

In addition, the following ODBC Text Driver types are supported:

Char (same as Text)
Float (same as Double)
Integer (same as Short)
LongChar (same as Memo)
Date date format

The Width parameter is ignored if the Format entry is set to any of the delimited options.


Accessing Databases on CDROM
Accessing Databases on CD-ROM

See Also	Example	Specifics

If you need to provide users with a Microsoft Jet database on CD-ROM or other read-only media, the CD-ROM must contain both the .MDB database file and the .LDB page lock file.  In addition, the database should be opened using the read-only and exclusive options.  By using the exclusive option, the Jet engine doesn't attempt to open the locking file.  Other users can still access the CD-ROM in the same way.


Accessing External Databases

See Also	Example	Specifics

There are a number of ways to access data from external databases, which can include other Microsoft Jet databases (.MDB), ODBC-based databases, or installable ISAM databases.  For example, you can open a QueryDef object on an external table by specifying the external database in the Connect property.

You can also use the OpenDatabase method to access external tables.  Set the source argument to the appropriate database type and any needed connection parameters, and set the dbname argument to either "ODBC", for ODBC databases, or to the directory or filename of the external database.  When you open an ODBC external database directly, the Microsoft Jet database engine sends a series of queries to the external database to determine the names and schema of all available tables and views.  When you subsequently create a Recordset with one of the tables in an external database, the Jet engine sends another series of queries to determine the schema of the table.

Because all these queries take time, you'll find it is far more efficient to attach an external table to an existing Jet database instead of opening the external database directly.  Attaching a table creates a link to the external table and saves it in your Jet database.  This stored link keeps a record of the database table's structure.  None of the external database data is stored in the .MDB file.

Although you can't create table-type Recordset objects with attached tables, you can create dynaset-type and snapshot-type Recordset objects.  You can't run SQL PassThrough queries against attached tables.

Attaching tables to an existing Jet engine database

To attach an external table to your database, you can write code as outlined in the following steps:

1.	Create variables for the Database and TableDef objects you are going to modify:

Dim Td As TableDef, Db As Database

2.	Use the OpenDatabase method to open the existing database:

Set Db = OpenDatabase("C:\DATABASE\MYDB.MDB")

3.	Create a TableDef object for the external table:

Set Td = Db.CreateTableDef("Customer Detail")

 	4.	Set the TableDef properties to link to the attached table:

Td.Attributes = dbAttachedODBC

Td.Connect = "ODBC;DSN=SSRVR1;UID=Fred;PWD=RHS;DATABASE=SQLDB;"

Td.SourceTableName = "CustDetail"

5.	Append the TableDef to the TableDefs collection with the Append method.  This step actually creates the object links in the database file.


Building SQL Statements in Code

See Also	Example	Specifics

This topic discusses how to create a Structured Query Language (SQL) Statement to manipulate data in your database.  SQL statements can be used to retrieve data from one or more tables, add, update or delete records, or execute stored procedures or foreign SQL statements on external databases.

Overview

To provide your application with the ability to generate context-sensitive SQL queries or adapt existing queries in ways not ordinarily supported by parameter queries, your application can build an SQL query in code.  Parameter queries can only accept SQL arguments that substitute for the values in the SQL statement but not table names, expressions or operators.

If you don't expect the Microsoft Jet database engine query to be changed by your code, create a permanent query in Microsoft Access or a QueryDef in your Visual Basic code.  QueryDef objects execute faster and can be executed by other applications that use your Jet engine database.  In many cases, you can create a parameter query that has all of the advantages of a QueryDef and also accepts parameters that can be substituted at run time.

Determine the SQL Dialect

To create an SQL statement in your application, first determine the target of the query.  If it is the Jet engine, you need to use Jet engine syntax.  Otherwise, use the syntax required by the backend processor.  If you are working with a database engine other than the Jet engine (like SQL Server), your only option to pass parameters to SQL statements or stored procedures may be to build the SQL statement in code.

When working with the Jet engine, the easiest way to create SQL statements is to use Microsoft Access to create a sample that closely approximates the syntax needed by your application.  Once the sample is created and tested, use the Clipboard to paste it into your Visual Basic application.

Construct the Query

When your application is ready to modify the SQL sample, use the concatenation operator (&) to join portions of the sample SQL with the contents of controls or variables in your application.  Avoid using the plus operator (+), which implies addition of the arguments.  If your substituted arguments must be bounded by quotes in the SQL query, your logic must provide quotes on both ends of the string.

Watch out for arguments passed from the user that contain single or double quotes, because these may break the quote pairing in your SQL statement.  You can use either single ( ' ) or double ( " ) quotes to frame quoted strings, as long as they are used in matched pairs.

For example, the following procedure accepts the name of a column to search and a search argument,  and inserts them into an SQL query.  The code then completes the SQL query based on the arguments, creates a Recordset and places the name field of the first selected publisher into a TextBox.

Sub FindPub (Db as Database, Column as String, Criteria as String)

Dim SQL as String, Rs as Recordset

SQL = "SELECT * FROM Publishers" _

  & " WHERE " & Column & Criteria" _

  & "'" & Publisher.Text & "'"

Set Rs = Db.OpenRecordset(SQL,dbOpenSnapshot)

If Rs.RecordCount <> 0 Then

  FoundPublisher.Text = Rs(Name) & ""

Else

  FoundPublisher.Text = "(Not found)"

End If

End Sub

If you call this procedure with "PUB_ID" as the column argument, " = " as the criteria argument and Publisher.Text contained "2774" , the SQL statement generated is:

SELECT * FROM Publishers WHERE PUB_ID = '2774'

Tip   Watch out for spaces before and after the arguments provided, especially when you break your string into more than one line.  Without the space before the WHERE clause, the SQL statement would read: SELECT * FROM Publishers WHERE....  Note that the code shown above uses the line continuation character.  This syntax is supported by Visual Basic to help break up longer lines, but isn't supported (or really necessary) with SQL statements.


Changing Microsoft FoxPro or dBASE Database Settings

See Also	Example	Specifics

Use the following procedure to change the [dBASE ISAM] section of <APPNAME>.INI.

1.	Change the setting of any of the following options:

Option	Description	Example
CollatingSequence	Sets the sort sequence the Microsoft Jet database engine uses when interacting with a FoxPro or dBASE database.   Valid settings: ASCII (U.S. only) or International (all other countries). The default is ASCII (U.S. only), International (all other countries).	CollatingSequence=International
Century	Specifies whether the Jet engine uses four-digit years in Date fields when interacting with a FoxPro or dBASE database.   Valid settings: On or Off (default).	Century=On
Date	Sets the convention the Jet engine uses for displaying dates when interacting with a FoxPro or dBASE database.   See your FoxPro or dBASE documentation for valid settings.	Date=American
Mark	Defines the character the Jet engine uses to separate months, days, and years in date displays when interacting with a FoxPro or dBASE database.   The setting is the ASCII decimal value of the mark character, in this example, the forward slash (/).	Mark=47
INFPath = path	In this entry, path is a valid path where the corresponding information (.INF) file can be written.  The Jet engine uses this file to keep track of information about indexes you specify for each FoxPro or dBASE file. Set this to a valid path if you want to import or attach a table from a FoxPro or dBASE database on a read-only drive (for example, a CD-ROM drive).	INFPath = C:\ACCESS\FOXPRO
Deleted	Specifies whether the Jet engine displays records marked for deletion when interacting with a FoxPro or dBASE database.   Valid settings: On (default) or Off.	Deleted=On
2.	Save your changes, exit your text editor, and start an application using the Jet engine.


Changing Microsoft Jet Engine ISAM Settings

See Also	Example	Specifics

Use the following procedure to change the [ISAM] section of <APPNAME>.INI.  This section determines how data is read and saved.

1.	Change the setting of any of the following options:

Option	Description	Example
PageTimeout	Sets the length of time between when data that isn't being used is placed in an internal cache and when it's marked to be refreshed.  The settings are expressed in 100 millisecond units.  The default is 5 (500 milliseconds, or 0.5 seconds).	PageTimeout=5
LockedPageTimeout	Sets the length of time between when data that is being used is placed in an internal cache and when it's marked to be refreshed.  The settings are expressed in milliseconds.   The default is 5 (500 milliseconds, or 0.5 seconds).	LockedPageTimeout=5
CursorTimeout	Sets the cursor time-out in 1/10 second intervals.  The default is 5 (or 0.5 seconds).	CursorTimeout=5
LockRetry	Specifies the number of times to repeat attempts to access a locked page.   The default is 20.	LockRetry=20
CommitLockRetry	Specifies the number of times the Microsoft Jet database engine attempts to get a lock on data in order to save changes to data.  If it fails to get a commit lock, then updates are unsuccessful. The number of attempts the Jet engine makes to get a commit lock is directly related to the LockRetry entry.  For each attempt at getting a commit lock, it tries the number of times specified in the LockRetry setting to get a lock.  For example, if CommitLockRetry is 20 and LockRetry is 20, the Jet engine attempts to get a commit lock as many as 20 times, and for each of those times it tries to get a lock as many as 20 times, for a total of 400 attempts at locking. The default is 20.	CommitLockRetry=20
MaxBufferSize	The size of the Jet engine internal cache, measured in kilobytes (K).  MaxBufferSize must be between 18 and 4096.   Increasing this setting may provide better ODBC performance in systems with enough memory. The default is 512.	MaxBufferSize=512
ReadAheadPages	Sets the number of pages to read ahead when doing sequential scans.   The default is 16.	ReadAheadPages=16
2.	Save your changes, exit your text editor, and start an application using the Jet engine.


Changing Microsoft ODBC Settings

See Also	Example	Specifics

Use the following procedure to change the [ODBC] section of <APPNAME>.INI.

1.	Change the setting of any the following options:

Option	Description	Example
QueryTimeout	Sets the number of seconds a query can be run before ODBC stops attempting to complete the query.  The countdown stops as soon as the first result record arrives from the server. The default is 60 seconds.	QueryTimeout=60
LoginTimeout	Sets the number of seconds a login attempt can continue before the Jet engine stops trying and displays a message.   The default is 20.	LoginTimeout=20
ConnectionTimeout	Sets the number of seconds a cached connection can remain idle before the Microsoft Jet database engine closes the connection.   The default is 600.  Be sure to use the Idle method of the DBEngine object to initialize this timer.	ConnectionTimeout=600
AsyncRetryInterval	Specifies in milliseconds the interval the Jet engine waits between polls that determine whether a server is finished processing an asynchronous query.   The default is 500.	AsyncRetryInterval=500
AttachCaseSensitive	Toggles case-sensitivity for matching table names. Valid settings: 0 Attach the first table whose name matches the specified string, regardless of case.   1 Attach a table only if its name exactly matches the specified string. The default is 0.	AttachCaseSensitive=0
AttachableObjects	Specifies a list of object types to which attaching is allowed.   Default values: 'TABLE', 'VIEW', 'SYSTEM TABLE', 'ALIAS', 'SYNONYM'.	AttachableObjects='TABLE','ALIAS'
TraceSQLMode	Indicates whether the Jet engine traces and records in the file SQLOUT.TXT all SQL statements sent to an ODBC data source.  This setting is interchangeable with SQLTraceMode. Valid settings: 0 (No) or 1 (Yes).  The default is 0.	TraceSQLMode=0 -Or- SQLTraceMode=0
TraceODBCAPI	Indicates whether the Jet engine traces and records in the file ODBCAPI.TXT all ODBC API calls.  If you set this to 1, it's recommended that you also set DisableAsync to 1. Valid settings: 0 (No) or 1 (Yes).  The default is 0.	TraceODBCAPI=0
DisableAsync	Indicates whether the Jet engine forces synchronous query execution. Valid settings:  0 Use asynchronous query execution where possible.   1 Force synchronous query execution.  This entry is ignored for Visual Basic and the default is 1 (synchronous).	DisableAsync=
TryJetAuth	Indicates whether to try using the Jet engine user name and password to log on to the server before prompting you to enter a user name and password. Valid settings: 0 (No) or 1 (Yes).  The default is 1.	TryJetAuth=1
PreparedInsert	Indicates whether the Jet engine uses a prepared INSERT that inserts data in all columns. Using a prepared INSERT can cause Nulls to replace server defaults, and can cause triggers to execute on columns where data wasn't inserted explicitly. Valid settings: 0 (Default)  Use a custom INSERT that inserts only non-Null values.   1 Use a prepared INSERT.	PreparedInsert=0
PreparedUpdate	Indicates whether the Jet engine uses a prepared UPDATE that updates data in all columns. Using a prepared UPDATE can cause triggers to execute on unchanged columns. Valid settings: 0 (Default)  Use a custom UPDATE that uses a SET only for columns that have changed.   1 Use a prepared UPDATE.	PreparedUpdate=0
FastRequery	Indicates whether to use a prepared SELECT for parameterized queries. Valid settings: 0 (Default)  Don't use a prepared SELECT for parameterized queries.  This is a bit slower but uses fewer connections.   1 Use a prepared SELECT for parameterized queries.  This is faster but may use more connections.	FastRequery=0
SnapshotOnly	Indicates whether recordsets are forced to be snapshots. Valid settings: 0 (Default)  Get index information when tables are attached so that dynasets are allowed.   1 Ignore index information when tables are attached so that only snapshots are allowed.  If you choose this setting, you aren't able to edit data.	SnapshotOnly=0
2.	Save your changes, exit your text editor, and start the Jet engine.


Changing Paradox Database Settings

See Also	Example	Specifics

Use the following procedure to change the [Paradox ISAM] section of <APPNAME>.INI.

1.	Change the setting of any of the following options:

Option	Description	Example
ParadoxUserName	Sets the user name that Paradox uses to alert another user of a locking conflict. The default is the user name you specified when you installed Visual Basic.	ParadoxUserName=nancydav
ParadoxNetPath	Sets the path to your PARADOX locking file, either PARADOX.NET (for Paradox 3.X) or PDOXUSRS.NET (for Paradox 4.X). file. Set this option to a network path if you want to share Paradox locking settings with other users. The default is the directory where you installed your application.	ParadoxNetPath=F:\WRKGRP\
ParadoxNetStyle	Sets the Paradox Network Style, either 3.X (for the Paradox 3.X locking style) or 4.X (for the Paradox 4.X) locking style. This applies only to network users.  All users who share Paradox files on a network must have the same ParadoxNetStyle settings. The default is 3.X.	ParadoxNetStyle=3.X
CollatingSequence	Sets the sort sequence the Microsoft Jet database engine uses when interacting with a Paradox database. Valid settings: ASCII, International, Norwegian-Danish, or Swedish-Finnish. The default is ASCII (U.S. only).	CollatingSequence=International
2.	Save your changes, exit your text editor, and start an application using the Jet engine.


Changing the System Database

See Also	Example	Specifics

Use the following procedure to change the setting of the SystemDB option in the [Options] section of <APPNAME>.INI.

1.	Type the name and new path of the system database (typically, the SYSTEM.MDA file); for example:

SystemDB=C:\WRKGRP\SYSTEM.MDA

The next time you start the Microsoft Jet database engine, it uses the system database, SYSTEM.MDA, in the WRKGRP directory on drive C, including its security settings.

2.	Save your changes, exit your text editor, and start an application using the Jet engine.

Warning   It is strongly recommended that you use the Microsoft Access Workgroup Administrator application to change your system database, rather than modify <APPNAME>.INI directly.  This application provides easy-to-use dialog boxes for changing your system database, creating a workgroup, or joining an existing workgroup.


Choosing a Field Data Type

See Also	Example	Specifics

Every field in a table must have a defined data type.  Like Visual Basic data types, the Field object data type determines the kind and range of values that can be entered in a field, the amount of storage space available in the field, and the amount of space allocated in the database to store the data.

Don't confuse the variable data types used by Visual Basic with the data types used to describe database fields.  Choose a variable type best suited to contain the data used in the database.  Conversions are done automatically wherever possible.  Your code triggers a trappable error if you attempt to save a value that doesn't conform to the limitations of the field.

For Field objects declared as type dbText, you also need to set the Size property that indicates the length of the longest string to be saved in the field.  All other types of Field objects have their Size property set automatically.

The table below lists the types of data, the constant used in the Type property, and their uses.

Data	Constant	Use for

Text	dbText	Text and numbers, such as names and addresses, phone numbers and postal codes.  A Text field can contain from 0 to 255 characters.  You must set the Size property to the maximum length of your text when you declare a field as type Text.

Memo	dbMemo	Lengthy text and numbers, such as comments or explanations.  A Memo field can contain up to 1.2GB characters.

Number	(See below)	Numerical data on which you intend to perform mathematical calculations, except calculations involving money.  See the table below for a further explanation of number fields.

Date/Time	dbDate	Dates and times.  These values are stored in a combined field [image] the date is always stored with the time.  Note that all dates are stored in U.S. format.

Currency	dbCurrency	Used where a field contains monetary values.  Don't use the Number data type for currency values because numbers to the right of the decimal may be rounded off during calculations.  The Currency data type maintains a fixed number of digits to the right of the decimal.  Set the Field object Type property to dbCurrency for currency fields.

Counter	dbLong	Sequential numbers automatically inserted by the Microsoft Jet database engine.  Set the dbAutoIncrement flag in the Field object Attributes property.  Numbering begins with 1.  The Counter data type makes a good primary key field.  If you want to establish a primary key/foreign key relationship between two tables using a counter field, make sure that the foreign key column data type is also defined as Long.

Yes/No	dbBoolean	Yes/No, True/False, On/Off, or fields that contain only one of two Boolean values.

OLE Object	dbLongBinary	Objects created in other programs using the OLE protocol.  Managed by OLE, Image or PictureBox controls.

Binary Image	dbLongBinary	Any value that can be expressed in binary up to 1.2GB in size.  This type is used to store pictures, files or other raw binary data.  Managed by Image or PictureBox controls.

Number Types	Use for

dbBoolean	Binary values of 0 or 1.

dbByte	Positive values from 0 to 255.  Stored in Byte variables.

dbInteger	Values from -32,768 to +32,767.  Stored in Integer variables.

dbLong	-2,147,483,648 to 2,147,483,647 (about 2.1 GB).  Stored in Long variables.

dbSingle	-3.402823E38 to 1.401298E-45 for negative numbers and 1.401298E-45 to -3.402823E38.  Stored in Single variables.

dbDouble 	1.79769313486232E308 to 4.94065645841247E-324 for negative values and 4.94065645841247E-324 to 1.79769313486232E308 for positive values.  Stored in Double variables.

Notes

Select the appropriate data type for each field.  For example, you usually define most fields in a table of names and addresses as Text fields.  Even a phone number field that contains only digits should be defined as a Text field.  Reserve the Number data type for fields on which you want to perform calculations.  Note that the Variant data type can accept any of these types and also supports NULL values.

You can't index fields with the data types Long Binary, Memo or OLE Object.

Limitations

The records you define must fit on the 2K pages supported by the Jet engine.  Each Field you include in the table definition counts toward this 2K total, including Binary and Memo fields.  However, the amount stored for Binary and Memo fields is only 14 bytes per non-null field, and only 1 byte for null fields, as the actual data for these fields is stored on additional pages.  The amount of data committed to each text field isn't set until you actually store data in the field.  Generally, you can "overcommit" a data page by defining more text fields than there would be room for, but no more than about 2K of actual data can be stored in a record.  For example, you can define 15 250-byte text fields in a record as long as the total number of characters stored is less than about 2K.  See the definitions for each of the data types to find out how much space each type of field uses.


Connecting to ODBC Databases

See Also	Example	Specifics

Data Access applications can connect to any database with an ODBC driver.  Connecting to ODBC database tables can be accomplished in a variety of ways:

Attach an ODBC database table or view to a Microsoft Jet database and use the OpenRecordset method to access the table.

Open the ODBC database directly using the OpenDatabase method.

Create a Querydef object that references an ODBC database.

Use the Data control to open either an attached ODBC table or the ODBC database directly.

Use the ODBC API as supplied in the ODBC programmer's toolkit.

Before any application can access an ODBC database, the ODBC drivers must be installed and a Data Source Name (DSN) created using the Control Panel or the RegisterDatabase method.  Whenever you refer to an ODBC database, this DSN is used.  It contains the linkage information used by the ODBC drivers and the Microsoft Jet database engine to establish a connection to the database.  Visual Basic includes an ODBC setup disk that can be freely copied when you distribute your application.  When you are ready to open an ODBC database, use the DSN in the Connect property of the Data control or QueryDef object or in the source argument of the OpenDatabase method.

For example, to directly open an ODBC database using a QueryDef object, you could either enter the string shown below in the Connect property using the Property window, or use the following code:

MyQuery.Connect = "ODBC;DSN=MySQLServer;" _

..& "UID=Fred;PWD=APlus;DATABASE=MySSDB;"

Data1.Database = ""

Data1.Refresh

In the same way you can provide a source argument to the OpenDatabase method:

Dim Db as Database, Connect as String

Connect$ = "ODBC;DSN=MySQLServer;" _

  & "UID=Fred;PWD=APlus;DATABASE=MySSDB;"

Set Db = OpenDatabase("", False, False, Connect$)

Performance Considerations

For best efficiency, you should not connect directly to an ODBC database.  When you do, the Jet engine is forced to query the database to determine table schema.  As each Recordset is created, this process may be repeated to determine the structure of the tables and indexes accessed.  This extra overhead can significantly increase the time it takes to open an ODBC database and retrieve data from its tables.

A higher-performance alternative when accessing ODBC databases is to attach chosen ODBC database tables or views to a Jet database.  By using this technique, the Jet engine is able to determine the structure of the table when it is attached.  When the database is subsequently opened or accessed, the linkage information stored in the Jet database is referenced.  If the ODBC database structure changes, however, use the TableDef object's RefreshLink method to rebuild the linkage information.  Attached tables may be updatable, but you can't use SQL PassThrough queries with these tables.

To perform many of its operations more quickly on Microsoft SQL Server systems, the ODBC driver may create one or more stored procedures in your working database.  If your program terminates abnormally, these procedures may remain on the server.  Generally, it is safe to remove these procedures manually once you determine they are not being used.

To adjust the parameters used by the Jet engine when working with ODBC databases, create a special table, MSysConf, on each ODBC database that you expect to access from Visual Basic using the Jet engine.

Executing SQL Statements Directly

In cases where you need to execute SQL statements that can only be executed on the ODBC database, like Transact SQL statements on Microsoft SQL Server, or to execute stored procedures, create a Querydef object whose Connect property contains an ODBC connect string.  The Jet engine can return multiple result sets and messages from stored procedures when you use a Querydef to execute the procedure.

When using ODBC databases, the LockEdits property is always False.  The Jet engine defaults to optimistic locking.  You can only update ODBC database tables if a unique key exists for the table.  If you need to use and update an external temporary table, create an index for it before attaching to or opening it directly.

You can set an upper limit on the time that the Jet engine takes to open an ODBC database by setting the LOGINTIMEOUT argument in the Connect string.  You can also limit the time the Jet engine takes to execute an ODBC query by setting the QueryTimeout property of the Database object or the ODBCTimeout property of the Querydef object.  When any of these preset times expire, a trappable error occurs.


Creating a Database
_Creating a Database

See Also	Example	Specifics

This topics discusses how to create a database in code.

A database file can contain a number of data access objects, and some of those objects can contain other objects or collections of objects.  Before you create a database, you should have a good idea about what information will be stored in your database and what kinds of tables, fields, and indexes you'll need to store and track that information.

Data Manager

The easiest way to create or modify the structure of your database is to use Microsoft Access or the Data Manager, which you can open by choosing the Data Manager command on the Tools menu.

External ISAM Databases

An external database is one where the actual data is stored in another file or database management system, not in a Microsoft Jet database (.MDB file).  In most cases, external ISAM databases are stored in a named disk directory.  Thus, to create a new ISAM FoxPro database you would use Windows FileManager or the MkDir statement to create a new directory.  To open this database, specify the path of the directory as the database name.  Individual tables are referenced by their filenames.

External ODBC Databases

The Microsoft Jet database engine can't create external ODBC databases.  This can be accomplished from your application, however, by using the SQL PassThrough option with the Execute method.  For Microsoft SQL Server installations, the system administrator (SA) user can use the OpenDatabase method to open the Master database with the SA password and then pass the required Transact SQL Statements to the SQL Server using the Execute method.  To add tables to the database from Visual Basic, you need to open it directly using a Connect string as discussed below.

Professional Edition

If you have the Professional Edition, you can write code to create and modify the structure of a database.  After you plan the structure of your tables, use these basic steps to create a database:

1.	Use Dim to declare a variable for the Database object you want to create:

Dim DB As Database

2.	Use the Workspace object's CreateDatabase method to create an empty database file and Database.  The CreateDatabase method sets the locale (language) used and the Jet database version.

Note   If you are working with an existing external database, use the CreateDatabase method to set the Database object variable.

Set Db = Workspaces(0).CreateDatabase("MyNewDb",  _

  dbLangGeneral,  _	' General language locale

  dbVersion20)	' Create Jet version 2.0 database

3.	Define each table in the database.  To do this, you first need to define the fields for each table.  Create the database tables and fields using the following steps:

a.	Use the Database object's CreateTableDef method to create a TableDef object for each table.  This method names the database table:

Dim Td as TableDef

Set Td = Db.CreateTableDef("Customer Detail")

b.	Use the new TableDef object's CreateField method to create a Field object for each field.  The example creates and names three fields.  Be sure to set the size property for text fields and any other required attributes before the field is appended:

Dim Fd as Field

Set Fd = Td.CreateField("Cust ID",dbLong)

' This is a counter field.

Fd.Attributes = dbAutoIncrField

Td.Fields.Append Fd

Set Fd = Td.CreateField("Cust Name",dbText,25)

Td.Fields.Append Fd

Set Fd = Td.CreateField("Picture",dbLongBinary)

Td.Fields.Append Fd

c.	Append the new TableDef to the Database object's TableDefs collection.  This is the step that actually creates the object in the database file.  Once appended, you can't make further changes to the appended field.  You may, however, add new fields or delete existing field definitions.

Db.TableDefs.Append Td

4.	You can optionally create one or more Index objects for each table using the TableDef object's CreateIndex method.  After you create each Index, create a Field object to describe which fields are used as keys.  For one of the indexes, set the Primary property to True.  If you want the Jet engine to prevent duplicates in the table based on a chosen index, set the Unique property to True:

a.	Use the TableDef object's CreateIndex method to create an Index object.

Dim Ix as Index

Set Ix = Td.CreateIndex("Customer Index")

b.	Use the Index object's CreateField method to create a Field object for each field in the table that is a component of the key.  Append each Field object to the Index object's Fields collection:

Set Fd = Ix.CreateField("Cust ID")

Fd.Primary = True

Ix.Fields Append Fd

c.	Append each Index object to the Indexes collection of the TableDef with the Append method.  A table can have none or several indexes.

Td.Indexes.Append Ix


Creating Parameter Queries

See Also	Example	Specifics

In situations where your application executes the same query repeatedly, it is more efficient to create a stored QueryDef object that contains the query SQL statement.  Queries stored in the database execute faster and can be used by anyone with access to the database.

If your application needs to alter WHERE clause arguments in a query, you can also add a PARAMETERS clause to your query that permits the Microsoft Jet database engine to substitute values into the query at run time.  Before running Parameter queries, your application must substitute values for each of the parameters as stored in the Parameters collection of the Querydef.

To create a parameter query

1.	Create a PARAMETERS clause string that includes a parametername and datatype for each parameter.  Don't use the field name alone as the parametername, because duplicating it may cause problems.  You can include the field name within the parametername, however.

If you are working with a database accessed by Microsoft Access, the parametername is used as a prompt string.  Keep this in mind if you expect Microsoft Access users to use this query.

Shown below is a typical PARAMETERS clause:

SQL$ = "PARAMETERS [Product Wanted] TEXT; [Size] LONG "

2.	Create a SELECT statement that fetches the needed fields and incorporates the named parameters into the WHERE clause.  In the example below, the parameters are used to filter the query to return only selected products of a specified size.  Note that the parameter [Product Wanted] is substituted by the Jet engine during execution of the query at run time.

SQL$ = SQL$ & "SELECT DISTINCTROW * " _ ' Add SELECT to PARAMETERS

  & " FROM Vendors" _

  & " WHERE ((Vendors.Product_ID =[Product Wanted]) " _

  & " AND (Vendors.Size_= [Size])) " _

  & " WITH OWNERACCESS OPTION; "

3.	Create a named QueryDef with your SQL statement.

Dim Qd as QueryDef

Set QD = CreateQueryDef("Find Vendors", SQL$)

4.	You are now ready to set the QueryDef parameters.  First, you need to gain access to the QueryDef.  You can either use the QueryDef object just created, or reference the stored QueryDef object from the QueryDefs collection.  The example shows two different types of addressing; either is acceptable.  You can also address the parameters by their ordinal number.

Dim ParmQD as QueryDef

Set ParmQD = MyDb.QueryDefs("Find Vendors")

ParmQD("Product Wanted") = "Salmon"	' Note the two ways to

ParmQD!Size = 16	' address the parameters.

5.	You are now ready to execute the procedure.  Because this query returns records, you need to create a Recordset to capture the result set.

Dim Rs as Recordset

Set Rs = ParmQD.OpenRecordset()

Note

You can use the BETWEEN...AND SQL operators in a parameter query to retrieve a range of values.  For example, you could enter BETWEEN [Low price] AND [High price] in the WHERE clause to fetch a list of products within a certain range of prices.

You can create a parameter query with the LIKE operator that allows the user to provide wildcard characters.  For example, if you entered LIKE [Enter the first letter]&*, the user could enter '"B" to display all values that start with the letter B.


Customizing Data Access .INI Settings

See Also	Example	Specifics

Unless your application can work correctly with the default functionality of the Microsoft Jet database engine, you must create an initialization file that the Jet engine can access.  Unlike in Visual Basic version 3.0, the VB.INI file isn't searched for these initialization parameters.  Initialization entries are also used to tune the operation of the installable ISAM and ODBC drivers.  All of these parameters are expected to be kept in your initialization (.INI) file.  If your application can't accept the default behavior of the drivers, you must include appropriate parameters in your initialization file and point to this file using the INIPath property.

This initialization file is usually kept in the \WINDOWS directory and should be named based on the name of your application.  For example, if you have an application named "SOCCER.EXE" your application's .INI file would be named "SOCCER.INI".  This file is referred to as your <appname>.INI.

You can name this initialization file anything you choose and locate it anywhere on your system by setting the INIPath property of the DBEngine object to a specific path and filename.  You must set the INIPath property before the DBEngine is initialized by the first reference to any data access object.  This includes the Data control and any of the data access methods.  For example, the following code tells the Jet engine to use the MYAPP.INI file located at D:\MYDIR:

DBEngine.INIPath = "D:\MYDIR\MYAPP.INI"

To restart the DBEngine so you can reestablish initialization settings, you can code the following.  Note, however, that this operation closes all Database and Recordset objects.

DBEngine = Nothing

You can customize the settings of the .INI file as described below by using Windows Notepad or another text editor.  The revised settings take effect the next time you start your application.

Note   In Visual Basic version 3.0, path names indicating the location of the installable ISAM drivers are maintained in the <APPNAME>.INI file.  In Visual Basic version 4.0, these entries are automatically installed and maintained in the Windows registration database.

You can add entries to <APPNAME>.INI or revise existing entries to specify:

The file that defines your or your workgroup's system database (typically the SYSTEM.MDA file).  See Changing the System Database.

Settings used for interaction with Microsoft FoxPro, Paradox, and dBASE databases.  See Changing Paradox Database Settings and Changing Microsoft FoxPro or dBASE Database Settings.

Settings used by Microsoft ODBC for interaction with SQL databases.  See Changing Microsoft ODBC Settings.

Settings that affect how the Jet engine reads and saves data.  See Changing Microsoft Jet Engine ISAM settings.

Settings that determine whether OLE links are saved in the OLE version 2.0 or OLE version 1.0 format.  See Specifying OLE Links Format.


Data Access Overview

See Also	Example	Specifics

Data Access Objects (DAO) enable you to use a programming language to access and manipulate data in databases, and to manage databases, their objects and structure.

The Microsoft Jet Database Engine

You can use Data Access Objects to manipulate databases in either the native Jet engine .MDB format or in other installable ISAM database formats including Fox, dBASE, Excel, Btrieve, Paradox and delimited Text.  In addition, you can use the Jet engine to access Microsoft SQL Server and any other database that can be accessed with an ODBC driver using the same DAO code.

Data Access Objects

You can declare new data access object variables for any of the object types using the Dim and Set statements.  For example, the following code creates object variables for a Database, a dynaset-type Recordset, and a Field:

Dim MyDb As Database, MyRs As Recordset, MyFd As Field

Set MyDb = OpenDatabase("BIBLIO.MDB")

Set MyRs = MyDb.OpenRecordset("Authors", dbOpenDynaset)

Set MyFd = MyRs.Fields("Au_ID")

Data access objects have a default collection or property.  For example, the default collection of a Recordset is the Fields collection and the default property of a Field is the Value property.  You can simplify your code by taking advantage of these defaults.  For example, the following code also sets the value of the PubID field in the current record:

Data1.RecordSource = "Publishers"

Data1.Refresh

Data1.Recordset("PubID") = 99

You can use object variables and other DDL features to modify your database structure.  For example, you can add a new Field to an existing table with the following code:

Dim MyDb As Database, MyTd as TableDef, MyFd As Field

Set MyDb = OpenDatabase("BIBLIO.MDB")	' Open database.

Set MyTd = MyDb.TableDefs("Authors")

Set MyFd = MyTd.CreateField("Address", dbText, 20)

MyTd.Fields.Append MyFd	' Append to TableDef fields.

This code creates a New object variable for a Field and adds it to a TableDef with the Append method.  Since a TableDef contains the definition of a table, the table now has a field named Address for entering data.  In much the same way, you can create new tables and new indexes.

DBEngine and Workspace Objects

All data access objects are derived from the DBEngine object, which represents the Jet engine.  When your application starts, the Jet engine creates a default DBEngine.Workspace object that can be referenced through the Workspaces collection (Workspaces(0)).  You can open additional Workspace objects as needed.  Each Workspace has a user ID and password associated with it.

Note   Unless you need to manipulate databases that have security enabled or create a separate transaction scope, you don't need to reference the DBEngine or Workspace objects. The default DBEngine.Workspaces(0) object is assumed if it isn't specifically referenced.  For example, to open a database using DAO and create a table-type Recordset, you can write the following code:

Dim Db as Database, Rs as Recordset

Set Db = OpenDatabase("BIBLIO.MDB")

Set Rs = Db.OpenRecordset("Titles")

All Database objects opened against a Workspace share a common transaction scope.  That is, when you use the BeginTrans method on a database, it applies to all other open databases opened in the Workspace.  In the same way, using the CommitTrans method against one database applies to all other databases opened in the Workspace.

Security

You can restrict access to one or more .MDB databases or their tables using security settings established and managed by the Jet engine.  In your code you can establish Group and User objects to define the scope and level of permissions available to individual users on an object-by-object basis.  For example, you can establish permissions for a specific user so that they have read-only access to one table and full access to another.

Important   Before you can establish or alter any security settings, you need to gain access to the SYSTEM.MDA file associated with the .MDB database.  This file can only be created by a special utility included with Microsoft Access version 2.0 or later.  Without this file your application can't activate security for a .MDB database.


Managing Connections to ODBC Data Sources

See Also	Example	Specifics

When you use the Microsoft Jet database engine to connect to ODBC data sources like SQL Server, the Jet engine opens one or more connections to the backend server.  These connections pass queries to the server and return result sets.  In Visual Basic version 3.0, the Jet engine automatically closed unused connections after 600 seconds (10 minutes).  In Visual Basic version 4.0, these connections remain open, even if your code closes the Recordset and Database objects, unless your code calls the Idle method of the DBEngine object after the time-out period expires.

To specify how much time the Jet engine waits before closing a connection, set the ConnectionTimeout parameter in your .INI file.  The name of the .INI file is determined by the INIPath property of the DBEngine object.  You must set this parameter before the Jet engine is initialized for it to have any affect.

To restart the DBEngine so you can reestablish initialization settings, use the following code.  Note, however, that this operation closes all Database and Recordset objects.

DBEngine = Nothing

To establish a connection time-out value

Use a text editor to set the ConnectionTimeout parameter in your .INI file to n (seconds).

Set the INIPath property of the DBEngine object to point to your .INI file before the Jet engine is initialized.  Generally, this must be done in the first Form_Load procedure before any references are made to data access objects.

Open a Database and create one or more Recordset objects.

When you are finished with the Recordset and Database objects:

Use the Close method to release the Recordset and Database object resources.

Wait for at least n seconds (the number of seconds set by the ConnectionTimeout parameter).

Call the Idle method of the DBEngine object.  This closes unneeded connections.

You may wish to set up a timer event in your Visual Basic application that periodically calls the Idle method to ensure that the Jet engine has enough time to complete background processing and to close unneeded connections as they time out.


Populating Recordsets

See Also	Example	Specifics

This topic discusses how to accomplish recordset population and how it affects the performance and operation of your application.

Recordset objects are composed of zero or more database records (rows) that become part of the Recordset based on criteria you specify when you create the Recordset.  When the Microsoft Jet database engine adds a record to a Recordset, the record is considered a member of the Recordset object.

Determining Recordset Membership

Membership in dynaset-type Recordset (dynaset) objects isn't fixed until the current row pointer is positioned to the last eligible row.  It is only then that the Recordset is considered to be fully populated.  To force immediate population, you can execute a MoveLast or FindLast method against the Recordset, or move the current record pointer to (that is, visit) each record in the Recordset.

In some cases, a Recordset may be fully populated immediately following its creation.  Depending on the way the Jet engine creates it, or how you phrase the SQL query, the number of populated rows can vary from a minimum of 0, when the Recordset is empty, to the total number of rows returned by the query.

In a multiuser environment, multiple users can add, delete or change records that make records qualify or disqualify as members of the Recordset until it is fully populated.  This means that any Recordset can contain records retrieved over a relatively long period of time.

Until you execute a MoveLast method, or otherwise position to the end of the Recordset, the number of qualified members in your Recordset can't be determined because it isn't fixed.  For this reason, the RecordCount property is set to zero for an empty Recordset or to the number of records actually fetched by the Jet engine.  Once you move the current record pointer to the last record, no further members are included, and the RecordCount property reflects the total number of records in the Recordset, regardless of the changes that other users make.  When working with Table objects, the RecordCount property of the TableDef object associated with the Table contains a current count of records in a specific table.

When other users delete records from the base table(s), your Recordset object's RecordCount property remains unchanged until you set the current record to the deleted record.  At this point you trigger a trappable error and the current record is no longer valid.  When your code positions to records changed by other users, these changes are available to your table-type and dynaset-type Recordset object, but not to your snapshot-type Recordset object .

When your code uses the MoveNext method, the Jet engine often fetches more than one record from the database to improve performance.  Because of this, the RecordCount can increase by more than one when you execute the MoveNext method or set the AbsolutePosition property.

Determining Current Record Position

The PercentPosition and AbsolutePosition properties can be used to set or return the location of the current record relative to the RecordCount property value.  Setting the AbsolutePosition property to the current setting of the RecordCount property causes the Jet engine to fetch another block of records, which adds to the membership of the Recordset.  However, if the Recordset is fully populated, setting AbsolutePosition to RecordCount causes a trappable error.

When working with external ODBC databases that can only handle one active statement, the connection to the external server is held open until the Recordset is fully populated.  In addition, this connection can't be reused for other queries until the last result set is completely fetched.  For these reasons, your code should attempt to fully populate the Recordset as quickly as possible.  You shouldn't create applications that open Recordset objects for user browsing without first fully populating them.

Note that the Data control fully populates any Recordset objects it creates in the background so your code doesn't need to perform a MoveLast method to force population.


Positioning the Current Record Pointer

See Also	Example	Specifics

Whenever you work with Recordset objects, the record which can be examined or modified is referred to as the current record. Only the current record is available for modification.  This topic discusses how to position the current record pointer to specific records in an open Recordset.  For more detailed information, search Help for the individual methods or see the See Also list.

You need to use one of the programmatic methods discussed below to reposition the pointer.  In some cases, no current record exists and references to it trigger a trappable error.  For example, the current record is invalid if you:

Delete the current record or all records in a Recordset.

Create a Recordset with no records.

Move beyond the beginning (BOF) or end (EOF) of the Recordset.

A Seek or Find has failed and the NoMatch property is True.

There are basically five ways to position the current record.  All of these techniques depend on the type of Recordset you are using, whether or not bookmarks are supported, and if the Recordset has a valid index.  See the table shown below to determine which methods work with which type of Recordset.

The Move Methods

The Move methods (MoveFirst, MoveLast, MovePrevious, MoveNext) reposition the current record pointer based on its current position (MoveNext and MovePrevious) or based on the beginning (MoveFirst) or end (MoveLast) of the Recordset.  Using the Move methods, you can position the current record pointer beyond either end of the Recordset, making it invalid.

Search Based on Criteria

Use the Seek method or one of the Find methods (FindFirst, FindLast, FindNext, FindPrevious) to reposition based on criteria you provide.  The Seek method works only with table-type Recordset objects, while the Find methods work only with dynaset and snapshot-type Recordset objects.  If the record you are searching for doesn't exist, the NoMatch property is set to True and the current record is invalid.

Using a Bookmark

If the Recordset you are working with supports bookmarks, you can move the current record pointer to any specific record by setting the Recordset object's Bookmark property to a valid bookmark.  To position to the record most recently added or changed, use the bookmark in the Recordset object's LastModified property.  If you clone a working Recordset, you can use bookmarks from the clone to position the current record pointer in the working Recordset.  The Move method can also be used to position based on a bookmark plus or minus an offset from that position.

Using Record Numbers

Although relational database applications shouldn't depend on record numbers, there are several methods that permit positioning within a Recordset based on the ordinal number of the record.  Note that a record number isn't assigned to individual records in the database, but is created when a Recordset is built.  For this reason, they can be different each time the Recordset is created.  Ordinal record numbers are assigned from 1 to RecordCount.

You can use the AbsolutePosition method to position to a specific record based on its ordinal number, or the PercentPosition method to move to the record closest to the percentage value provided.  For example, in a Recordset with 50 records, using the PercentPosition method with an argument of 10 positions to the 5th record.

Note that the Recordset object's RecordCount property for table-type Recordset objects is set to the number of records in the table.  For dynaset and snapshot-type Recordset objects, the RecordCount property is set to 0 for empty Recordset objects or to 1 for unpopulated Recordset objects.  As you move the current record pointer toward the end of the Recordset, the RecordCount property is incremented for each record visited.  Using the MoveLast method on the Recordset or its clone fully populates the Recordset and sets the RecordCount property to the number of records in the Recordset.

Adding and Deleting Records

Records are always added to the end of the Recordset regardless of the order in which the Recordset was originally created.  After a record is added, the current record pointer is repositioned to the record that was current before the record was added.  When you need to delete records, only the current record can be deleted.  Once the delete is complete, the current record is invalid so you need to reposition it to another valid record.

Applying Reposition Methods

Method	Recordset Type	Notes
AddNew	Dynaset, Table	If Updatable property is True.
Delete	Dynaset, Table	If Updatable property is True.
Find methods	Dynaset, Snapshot	Current record is invalid if NoMatch is True.
Move	Dynaset, Snapshot, Table	Relative to current location or specific bookmark.
Move methods	Dynaset, Snapshot, Table	Can reposition past EOF or BOF, making current record invalid.
PercentPosition	Dynaset, Snapshot, Table	Not for forward-only scrolling snapshots.
Seek	Table	Current record is invalid if NoMatch is True.


Querying a Database

See Also	Example	Specifics

To work with the data in a database, you can use queries to manipulate or extract data.  A query either asks the database for a set of records matching specified criteria (a select query), or tells the database to perform a specified operation on a set of records that match specified criteria (an action query).  In any case, you may use an SQL statement to define which records you want, and how you want them ordered and grouped.

If you use an SQL query to retrieve data, the Microsoft Jet database engine only creates a dynaset-type or snapshot-type Recordset.  Once the Recordset is built, you can use one of the Find methods to further refine the search or step through the records one at a time.

There are a variety of ways to execute queries including:

Use an SQL action query as an argument to the Execute method.

Create and execute a custom Querydef object.

Use an SQL statement as an argument to the OpenRecordset method.

Execute an existing Querydef with the OpenRecordset method.

Using an SQL action query as an argument to the Execute method

If you need to execute an action query to perform an operation that doesn't return records, as when you insert or delete records, you can use an SQL statement as an argument to the Execute method.  The Execute method can be used with the Data control or an open Database object as long as the query doesn't return records.  For example, to delete all of the records from a table matching specific criteria, you can use the following code:

Data1.Database.Execute "DELETE FROM Titles " _

& " WHERE [Year Published] = 1869 "

Creating a new QueryDef object

You can set the SQL property of a QueryDef in either of two situations:

1.	Design your query so the database returns only the records you want.

2.	Create a complete QueryDef in code:

Dim MyQuery As QueryDef, Db As Database, MySQL As String

Set Db = OpenDatabase("C:\VB\BIBLIO.MDB")

MySQL = "SELECT Author FROM Authors WHERE Author LIKE 'A*'"

Set MyQuery = Db.CreateQueryDef("A Names", MySQL)

Or you can create a blank QueryDef and set the SQL property later.

1.	Design your query so the database returns only the records you want.

2.	Create a QueryDef in code:

Dim MyQuery As QueryDef, Db As Database, Rs as Recordset

Set Db = OpenDatabase("C:\VB\BIBLIO.MDB")

Set MyQuery = Db.CreateQueryDef("A Names")

3.	Set the SQL property later:

MyQuery.SQL = "SELECT Author FROM Authors WHERE Left(Author, 1) = 'A'"

4.	Now you can use the QueryDef to create a Recordset with either of these lines of code:

Set Rs = MyQuery.OpenRecordset()
Set Rs = Db.OpenRecordset("A Names")

You can also create parameter queries that allow you to modify parts of a query at run time without changing the query saved in the database.

Creating a parameter QueryDef object

1.	Design your parameter query so the database returns only the records you want.

2.	Create a parameter QueryDef in code.  Note that the parameter [Name Wanted] isn't enclosed in quotes and is only enclosed in brackets [ ] when the parameter includes imbedded spaces or punctuation:

Dim MyQuery As QueryDef, Db As Database

Dim MySQL As String, Rs As Recordset

Set Db = OpenDatabase("C:\VB\BIBLIO.MDB")

MySQL = "PARAMETERS [Name Wanted] Text;"

MySQL = MySQL & " SELECT Author FROM Authors"

MySQL = MySQL & " WHERE Author = [Name Wanted]"

Set MyQuery = Db.CreateQueryDef("A Name", MySQL)

3.	You must set the parameter before you use the query. With Microsoft Visual Basic or Microsoft Access, you could use a TextBox or similar control to obtain the name to search for, instead of the InputBox function shown in the following code segment.

Prompt = Name to search for:

MyQuery.Parameters![Name Wanted] = InputBox(Prompt)

Set Rs = MyQuery.OpenRecordset()

If Rs.Recordcount > 0 Then 	' The record was found.


Retrieving Data Using SQL

See Also	Example	Specifics

You can use SQL to query, update, and manage relational databases such as Microsoft Jet databases.

For some query types [image] such as pass-through, data-definition, and union queries [image] you must use an SQL statement.

You can also use SQL statements in many places where you can enter the name of a table, query, or field.  For example, you can enter an SQL statement instead of a table name when using the OpenRecordset method to create a Recordset object.

To learn more about the parts of an SQL statement, search Help for any of the Microsoft Jet database engine SQL reserved words:

SELECT fieldlist

FROM tablenames IN databasename

WHERE searchconditions

GROUP BY fieldlist

HAVING searchconditions

ORDER BY fieldlist

SQL statements can't be entered in the same way as other Visual Basic commands.  To use an SQL statement in your program, build a string containing the statement and either include it as a literal quoted argument, or as a variable in a method, statement, or function.

Because SQL statements can be very long, you may wish to break them up for readability.  To do this, use the line continuation character ( _ ) as shown below.  Note that SQL statements can't contain imbedded carriage return characters, because these act as statement terminators.  The following example uses a valid SQL statement:

Dim SQL as String, Rst as Recordset

SQL$ = "SELECT [Last Name], [First Name] " _

  & " FROM Employees " _

  & " WHERE Salary > 21000;"

Set Rst = OpenRecordset(SQL$)

Note   You may want to use Microsoft Access to create queries for your Visual Basic application.  When you create a query in the Query window, Microsoft Access creates the equivalent SQL statement.  You can view or edit this statement by choosing SQL from the View menu in the Microsoft Access Query window or by clicking the SQL View button.  After Microsoft Access creats the SQL query, you can use the Clipboard to copy the query into your program or access the query using the stored QueryDef object.


Specifying the OLE Link Format

See Also	Example	Specifics

Use the following procedure to change the [Options] section of <APPNAME>.INI.  This section determines whether OLE links are saved in OLE version 1.0 or 2.0 format.

1.	Change the setting of any the following options:

Option	Description	Example
AllowOLE1LinkFormat	Specifies whether the Microsoft Jet database engine saves OLE links in OLE version 2.0 format, saving both relative and absolute link source references, or in OLE version 1.0 format, saving only absolute link source references. Set this option to 1 to ensure consistency of OLE linking operations in the Jet engine version 1.x databases in an environment where both the Jet engine version 2.0 and version 1.x are used. Valid settings: 0 (OLE version 2.0 link format) or 1 (OLE version 1.0 link format).  The default is 0.	AllowOLE1LinkFormat=0
2.	Save your changes, exit your text editor, and start an application using the Jet engine.


Using Bookmarks With the Microsoft Jet Version 2.5 Engine

See Also	Example	Specifics

In older versions of the Microsoft Jet Database engine (i.e., Microsoft Visual Basic 3.0 and earlier; Microsoft Access 2.0 and earlier), the Bookmark property is managed as a String or Variant data type.  In later versions, the Bookmark property is managed as a Byte array.  For this reason, if you try to use the Bookmark property in a compare operation, a trappable error results.  For example, if you use the Bookmark property in a Select Case or If...Then...Else statement, a Type Mismatch error occurs because Visual Basic can't compare Byte arrays with any other variable type.

To compare bookmark values, copy them to string variables and write the comparison expression using these string variables.


Using Counter Fields

See Also	Example	Specifics

In situations where your table records need a value to act as a unique record identifier, the Microsoft Jet database engine can be programmed to use a Counter field that automatically provides a unique value for this purpose.

To create a new Counter field with this feature, use Microsoft Access to specify a Counter data type.  If you use Visual Basic code, set the dbAutoIncrField bit in the Attributes property of a Field object, and assign the Long data type to the Type property.

Once enabled, the Jet engine automatically calculates a unique Long integer for this Field, and supplies it when the record is written to the table with the Update method.  Your code doesn't need to supply this value but if it does, the value must be a valid (and unique) Long integer >= 0.

To determine the number assigned once the data is written to disk, execute the Edit method, use the Requery method against the Recordset, or refresh the record from the table by repositioning to the LastModified property bookmark.  When your code establishes relationships to Counter fields, be sure to use the Long data type on related foreign key fields.


Using Named Arguments

See Also	Example	Specifics

In some cases, arguments for methods, functions, statements and procedures can be coded using the argument name instead of positional arguments.  This topic discusses how to write code for and pass these arguments.

Note   Named arguments aren't supported universally in Visual Basic.  If you aren't sure whether a method, function or statement supports named arguments, consult Help or the Object Browser on the specific topic.

Coding

Postional arguments are specified by coding arguments in a specific order.

Named arguments use the argument name followed by :=.  For example, to supply False to an argument named "READONLY", use: READONLY:=False.  Each named argument is listed in the object library under the method, function or statement.  Press F2 to open the object library dialog.

Using named arguments doesn't eliminate the need to specify arguments where required, but it does allow you to place them in any order.  Separate all arguments by commas, regardless of style.

To determine specific names to use for each argument, paste the object into your code from its object library entry.  For example, the entry for the OpenDatabase method appears as:

OpenDatabase(Name:=, [Exclusive]:=, [ReadOnly]:=, [Connect]:=)

Using positional arguments, the OpenDatabase method can be coded in a number of ways.  For example, where only the database name is supplied:

Set Db = OpenDatabase("MyDb.MDB")

Or, where the name, exclusive, readonly and connect arguments are all supplied:

Set Db = OpenDatabase("MyDSN", _

  False, _

  False , _

  "ODBC;UID=Vicky")

The OpenDatabase method can also be coded by replacing positional arguments with equivalent named arguments.  For example, where only the database name is supplied:

Set Db = OpenDatabase(Name:="MyDb.MDB")

Or, where the name, exclusive, readonly and connect arguments are all supplied:

Set Db = OpenDatabase(Name:="MyDSN",  _

  Exclusive:=False, _

  ReadOnly:=False, _

  Connect:="ODBC;UID=Vicky")

Or, where the name, exclusive, readonly and connect arguments are supplied, but in a different order:

Set Db = OpenDatabase(Connect:="ODBC;UID=Vicky, _

  Name:="MyDSN",  _

  ReadOnly:=False, _

  Exclusive:=False")


Using SQL PassThrough

See Also	Example	Specifics

SQL PassThrough permits your application to effectively bypass the Microsoft Jet database engine query processor and route foreign-dialect SQL statements to an external database server like SQL Server.

This technique is used to pass single or multiple SQL commands, stored procedures, or other SQL statements to an external database server to be executed.  Whenever you specify a SQL PassThrough query, the Jet database query processor is bypassed, but its recordset processor is used to create and manage the result sets that may be generated by your query.

Typical Uses

SQL PassThrough can be used to force query processing to be executed on an external database engine.  For example, you can use SQL PassThrough to:

Execute a stored procedure.

Run an SQL query using foreign syntax or return more than one set of results.

Create a new database, table or index on an external server.

Create or manage Triggers, Defaults, Rules or stored procedures.

Maintain user accounts or perform other System Administrator tasks.

Run maintenance operations like Microsoft SQL Server's DBCC.

Execute multiple INSERT or UPDATE statements in a single batch.

Implementation

Although the technique shown below uses the QueryDef object to store and execute the foreign-language SQL query, you can't set parameters for the query using the Parameters collection of the QueryDef object.  To build SQL queries that are created in code or require parameters, you need to construct or modify the query in code.

If there are result records (rows) from your SQL PassThrough query, the Jet engine creates a snapshot-type Recordset objects for each set of results.

This version of the Jet engine supports use of SQL Passthrough by permitting your code to set the SQL property of the QueryDef object to contain non-Jet engine SQL syntax.  Although you can still place foreign SQL syntax in the SQL argument of the CreateDynaset, CreateSnapshot or ExecuteSQL methods, and use the dbSQLPassThrough option, this outdated technique isn't recommend.

To create a SQL PassThrough QueryDef

1.	Use the CreateQueryDef method to create a QueryDef object using only a name argument.  If you specify an SQL argument, you can't use foreign SQL syntax [image] it must comply with Jet engine SQL syntax.  To create a temporary QueryDef that isn't automatically saved in the database, use the CreateQueryDef method without the name argument.

Note   The dbSQLPassThrough option doesn't need to be set by your code to execute a SQL PassThrough query using a Querydef object.  This option is set for you by the Jet engine.

2.	Set the Connect property of the QueryDef to a valid connect string to inform the Jet engine that this is a SQL PassThrough query.  From this point forward, the Jet engine doesn't attempt to parse the SQL property.

3.	Set the SQL property of the Querydef to the SQL statement to be executed.  Be sure to use SQL syntax as dictated by the external server.

4.	If you expect your query to return one or more sets of records (rows), set the ReturnsRecords property of the Querydef to True to inform the Jet engine to expect records (rows) back from the query.  This forces the Jet engine to create a Recordset for each set of results.  If you don't set the ReturnsRecords property to True for a query that returns records, a trappable error results.

For example, the following code creates a SQL PassThrough QueryDef that executes a stored procedure called MultipleResultSets:

Dim Rs As Recordset, Db As Database, Qd As Querydef

Set Db = Workspaces(0).OpenDatabase("MYDB.MDB")

Set Qd = Db.CreateQueryDef("My QD")

Qd.Connect = "odbc;dsn=MyDSN;uid=Chrissy;pwd=Champ;database=TestDB;"

Qd.SQL = "MultipleResultSets"

Qd.ReturnsRecords = True

To execute the SQL PassThrough QueryDef

1.	Use the OpenRecordset method to execute the stored Querydef so that the first (and only the first) set of results is available.

Set Rs = Db.OpenRecordset("My Qd", dbOpenSnapshot)

To process any additional result sets of a SQL PassThrough QueryDef

1.	 Create and execute a temporary QueryDef that executes a Jet SQL make table query using SELECT INTO syntax.  The Jet engine creates one new table for each set of results and stores them in your database.  If more than one user executes this code at the same time when using a shared database, the applications may generate table name collisions.

The SELECT INTO query doesn't return records, but it builds one or more tables to store the results from the QueryDef.  By not providing a name to the CreateQueryDef method, the Jet engine doesn't store a new QueryDef in the database.

Set Qd = Db.CreateQueryDef("")

Qd.SQL = "SELECT [My QD].* INTO Result FROM [My QD];"

Qd.Execute

2.	Create and process each of the resulting tables that contain the results of the QueryDef using the OpenRecordset method.

Set Rs = Db.OpenRecordset("Result")

' Process the results of the query...

3.	Repeat the process for each of the result sets.  Unless you know how many there are, you must query the TableDefs collection to see how many result set tables were created.  Note that the Jet engine numbers each subsequent table sequentially.  In this case, the table name Result contains the first set of results, Result1 contains the second and so on.

' Get second set of results.

Set Rs = Db.OpenRecordset("Result1")

' Process the results...

' Get Third set of results

Set Rs = Db.OpenRecordset("Result2")

' Process the results...

Rs.Close	' Close the Recordset, you are done with it.

4.	Remove the tables used to store the results of your query.

Db.Execute "Drop table [Result]"

Db.Execute "Drop table [Result1]"

Db.Execute "Drop table [Result2]"


Using the MSysConf Table with SQL Databases

See Also	Example	Specifics

If you are administering an SQL database with front-end applications that use the Microsoft Jet database engine, you can create a table in your SQL database named MSysConf to help you control communication between the two applications.  You can add this table to each SQL database you expect to access.  Without the MSysConf table in your SQL database, the Jet engine uses all of the default settings as described below.

The MSysConf table has two potential functions:

It can disable the feature that enables users to store the login ID and password for an attached SQL database locally.

It can optimize how the Jet engine performs background population of records during idle time when using the Data control.  Using the MsysConf table, you can set the number of rows of data that are retrieved at one time and the number of seconds of delay between each retrieval.  The Jet engine uses a default of 100 records returned every 10 seconds if you don't create the MSysConf table.

The Structure of the MSysConf Table

The SQL database table MSysConf should have the following structure:

Column name	Data type	Allows Null?
Config	A data type that corresponds to a 2-byte integer	No
chValue	VARCHAR(255)	Yes
nValue	A data type that corresponds to a 4-byte integer	Yes
Comments	VARCHAR(255)	Yes
Note   If the data source you're working with is case-sensitive, use the table and column names exactly as shown.

All users must have permission to use the SELECT statement on this table, and only the system administrator should have INSERT/UPDATE/DELETE permission.

The Data in the MSysConf Table

There are three valid records in the MSysConf table.  The table below shows what values you should enter in the Config and nValue field.  The other columns are reserved for future use, and their contents are ignored.

Config	nValue	Meaning

101	0	Don't allow local storage of the login ID and password in attachments.

101	1 	(Default)  Allow local storage of the login ID and password in attachments.

102	D	D is the delay in seconds between each retrieval (default: 10 seconds).

103	N	N is the number of rows retrieved (default: 100 rows).

Notes

Setting a higher delay time decreases network traffic, but increases the amount of time that read-locks are left on data (if the server uses read-locks).

If you create an MSysConf table, it must be set up properly or you can't connect to the SQL database table at all.


Using Bookmarks With the Microsoft Jet Version 2.5 Engine Example

This example compares bookmarks in two Recordset objects:

Dim Db as Database

Set Db = OpenDatabase("BIBLIO.MDB")

Dim Book1 as String, Book2 as String

Dim Rs1 as Recordset, Rs2 as Recordset

Set Rs1 = Db.OpenRecordset("Titles")

Set Rs2 = Rs1.Clone()

Book1 = Rs1.Bookmark

Book2 = Rs2.Bookmark

If Book1 = Book2 Then Print "This comparison is valid"


ALTER TABLE Statement (SQL)

See Also	Example	Specifics

Modifies the design of a table after it has been created with the CREATE TABLE statement.

Note   The Microsoft Jet database engine doesn't support the use of ALTER TABLE, or any of the data definition language (DDL) statements, with non-Jet databases.  Use the data access object Create methods instead.

Syntax

ALTER TABLE table {ADD {COLUMN field type[(size)] [CONSTRAINT index] I
CONSTRAINT multifieldindex} |
DROP {COLUMN field I CONSTRAINT indexname} }

The ALTER TABLE statement has these parts:

Part	Description

table	The name of the table to be altered.

field	The name of the field to be added to or deleted from table.

type	The data type of field.

size	The field size in characters (Text data type fields only).

index	The index for field.  See the CONSTRAINT clause topic for more information on how to construct this index.

multifieldindex	The definition of a multiple-field index to be added to table.  See the CONSTRAINT clause topic for more information on how to construct this clause.

indexname	The name of the multiple-field index to be removed.

Remarks

Using the ALTER TABLE statement, you can alter an existing table in several ways.  You can:

Use ADD COLUMN to add a new field to the table.  You specify the field name, data type, and (for Text fields) an optional size.  For example, the following statement adds a 25-character Text field called Notes to the Employees table:

ALTER TABLE Employees ADD COLUMN Notes TEXT(25)

You can also define an index on that field.  For more information on single-field indexes, see the CONSTRAINT clause topic.

Use the ADD constraint to add a multiple-field index.  For more information on multiple-field indexes, see the CONSTRAINT clause topic.

Use DROP COLUMN to delete a field.  You specify only the name of the field.

Use the DROP constraint to delete a multiple-field index.  You specify only the index name following the CONSTRAINT reserved word.

Notes

You can't add or delete more than one field or index at a time.

You can use the CREATE INDEX statement to add a single- or multiple-field index to a table, and you can use ALTER TABLE or the DROP statement to delete an index created with ALTER TABLE or CREATE INDEX.


CONSTRAINT Clause (SQL)

See Also	Example	Specifics

A constraint is an index.  You use the CONSTRAINT clause in ALTER TABLE and CREATE TABLE statements to create or delete indexes.  There are two types of CONSTRAINT clauses: one for creating an index on a single field and one for creating an index on more than one field.

Note   The Microsoft Jet database engine doesn't support the use of CONSTRAINT, or any of the data definition language (DDL) statements, with non-Jet databases.  Use the data access object Create methods instead.

Syntax

Single-field index:

CONSTRAINT name {PRIMARY KEY |
UNIQUE |
REFERENCES foreigntable [(foreignfield1, foreignfield2)]}

Multiple-field index:

CONSTRAINT name
{PRIMARY KEY (primary1[, primary2 [, ...]]) |
UNIQUE (unique1[, unique2 [, ...]]) |
FOREIGN KEY (ref1[, ref2 [, ...]]) REFERENCES foreigntable [(foreignfield1 [, foreignfield2 [, ...]])]}

The CONSTRAINT clause has these parts:

Part	Description
name	The name of the index to be created.
primary1, primary2	The name of the field or fields to be designated the primary key.
unique1, unique2	The name of the field or fields to be designated as a unique key.
ref1, ref2	The name of a foreign key field or fields that refer to fields in another table.
foreigntable	The name of the foreign table containing the field or fields specified by foreignfield.
foreignfield1, foreignfield2	The name of the field or fields in foreigntable specified by ref1, ref2.  You can omit this clause if the referenced field is the primary key of foreigntable.
Remarks

You use the syntax for a single-field index in the field-definition clause of an ALTER TABLE or CREATE TABLE statement immediately following the specification of the field's data type.

You use the syntax for a multiple-field index whenever you use the reserved word CONSTRAINT outside a field-definition clause in an ALTER TABLE or CREATE TABLE statement.

Using CONSTRAINT, you can designate a field as one of the following types of indexes:

You can use the UNIQUE reserved word to designate a field as a unique key.  This means that no two records in the table can have the same value in this field.  You can constrain any field or list of fields as unique.  If a multiple-field index is designated as a unique key, the combined values of all fields in the index must be unique, even if two or more records have the same value in just one of the fields.

You can use the PRIMARY KEY reserved words to designate one field or set of fields in a table as a primary key.  All values in the primary key must be unique, and there can be only one primary key for a table.

Note   Don't set a PRIMARY KEY constraint on a table that already has a primary key; if you do, an error occurs.

You can use the FOREIGN KEY reserved words to designate a field as a foreign key.  If the foreign table's primary key consists of more than one field, you must use a multiple-field index definition, listing all of the referencing fields, the name of the foreign table, and the names of the referenced fields in the foreign table in the same order that the referencing fields are listed.  If the referenced field or fields are the foreign table's primary key, you don't have to specify the referenced fields [image] by default, the Jet engine behaves as if the foreign table's primary key is the referenced fields.


CREATE INDEX Statement (SQL)

See Also	Example	Specifics

Creates a new index on an existing table.

Note   The Microsoft Jet database engine doesn't support the use of CREATE INDEX, or any of the data definition language (DDL) statements, with non-Jet databases.  Use the data access object Create methods instead.

Syntax

CREATE [ UNIQUE ] INDEX index
ON table (field [ASC|DESC][, field [ASC|DESC], ...])
[WITH { PRIMARY | DISALLOW NULL | IGNORE NULL }]

The CREATE INDEX statement has these parts:

Part	Description

index	The name of the index to be created.

table	The name of the existing table the index will be created on.

field	The name of the field or fields to be indexed.  To create a single-field index, list the field name in parentheses following the table name.  To create a multiple-field index, list the name of each field to be included in the index.  To create descending indexes, use the DESC reserved word; otherwise, indexes are assumed to be ascending.

Remarks

To prohibit duplicate values in the indexed field or fields of different records, use the UNIQUE reserved word.

In the optional WITH clause, you can enforce data validation rules.  You can:

Prohibit Null entries in the indexed field or fields of new records by using the DISALLOW NULL option.

Prevent records with Null values in the indexed field or fields from being included in the index by using the IGNORE NULL option.

Designate the indexed field or fields as the primary key by using the PRIMARY reserved word.  This implies that the key is unique, so you can omit the UNIQUE reserved word.

Generally, you use the CREATE INDEX statement with the Execute method.

You can use CREATE INDEX to create an index specification on an attached table that does not already have an index.  To create such an index, you don't need permission or access to the remote server, and the remote database is unaware of and unaffected by the index.  You use the same syntax for attached and native tables. This can be especially useful to create an index on a table that would ordinarily be read-only due to lack of an index.

You can also use the ALTER TABLE statement to add a single- or multiple-field index to a table, and you can use the ALTER TABLE statement or the DROP statement to remove an index created with ALTER TABLE or CREATE INDEX.

Note   Don't use the PRIMARY reserved word when you create a new index on a table that already has a primary key; if you do, an error occurs.


CREATE TABLE Statement (SQL)

See Also	Example	Specifics

Creates a new table.

Note   The Microsoft Jet database engine doesn't support the use of CREATE TABLE, or any of the data definition language (DDL) statements, wtih non-Jet databases.  Use the data access object Create methods instead.

Syntax

CREATE TABLE table (field1 type [(size)] [index1] [, field2 type [(size)] [index2] [, ...]] [, multifieldindex [, ...]])

The CREATE TABLE statement has these parts:

Part	Description

table	The name of the table to be created.

field1, field2	The name of field or fields to be created in the new table.  You must create at least one field.

type	The data type of field in the new table.

size	The field size in characters (Text fields only).

index1, index2	A CONSTRAINT clause defining a single-field index.  See the CONSTRAINT clause topic for more information on how to create this index.

multifieldindex	A CONSTRAINT clause defining a multiple-field index.  See the CONSTRAINT clause topic for more information on how to create this index.

Remarks

Generally, you use the CREATE TABLE statement with the Execute method.  You can also use the CREATE INDEX statement to create indexes on existing tables.


DROP Statement (SQL)

See Also	Example	Specifics

Deletes an existing table from a database or deletes an existing index from a table.

Note   The Microsoft Jet database engine doesn't support the use of DROP, or any of the data definition language (DDL) statements, with non-Jet databases.  Use the data access object Create methods instead.

Syntax

DROP {TABLE table | INDEX index ON table}

The DROP statement has these parts:

Part	Description

table	The name of the table to be deleted or the table from which an index is deleted.

index	The name of the index to be deleted from table.

Remarks

You must close the table before you can delete it or remove an index from it.

You can also use ALTER TABLE to delete an index from a table.

You can use CREATE TABLE to create a table and CREATE INDEX or ALTER TABLE to create an index.  To modify a table, use ALTER TABLE.

Note   Generally, you use the DROP statement with the Execute method.


SELECT Statement (SQL)

See Also	Example	Specifics

Instructs the Microsoft Jet database engine to return information from the database as a set of records.

Syntax

SELECT [predicate] { * | table.* | [table.]field1 [, [table.]field2[, ...]]}
[AS alias1 [, alias2 [, ...]]]
FROM tableexpression [, ...] [IN externaldatabase]
[WHERE... ]
[GROUP BY... ]
[HAVING... ]
[ORDER BY... ]
[WITH OWNERACCESS OPTION]

The SELECT statement has these parts:

Part	Description

predicate	One of the following predicates: ALL, DISTINCT, DISTINCTROW, or TOP.  You use the predicate to restrict the number of records returned.

*	Specifies all fields from the specified table(s) are selected.

table	The name of the table containing the fields from which records are selected.

field1, field2	The names of the fields to retrieve data from.  If you include more than one field, they are retrieved in the order listed.

alias1, alias2	The column names to return as Field object names in the resulting Recordset object.

tableexpression	The name of the table or tables containing the data you want to retrieve.

externaldatabase	The name of the database containing the tables in tableexpression if not in the current database.

Remarks

To perform this operation, the Jet engine searches the specified table(s), extracts the chosen columns, selects rows that meet the criterion, sorts and/or groups the resulting rows into the order specified, and returns the results in a Recordset object.  Your application can then manipulate this Recordset [image] displaying, adding, changing and/or deleting records as needed.  Your application can also display and produce reports from the data.

SELECT statements don't change data in the database.

You can use a SELECT statement in the SQL property of a QueryDef object, in the RecordSource property of a Data control, or as an argument for the OpenRecordset method.

SELECT is usually the first word in an SQL statement.  Most SQL statements are either SELECT or SELECT...INTO statements.

The minimum syntax for a SELECT statement is:

SELECT fields FROM table

You can use an asterisk (*) to select all fields in a table.  The following example selects all of the fields in the Employees table:

SELECT * FROM Employees;

If a field name is included in more than one table in the FROM clause, precede it with the table name and the . (dot) operator.  In the following example, the Department field is in both the Employees table and the Supervisors table.  The SQL statement selects Department from the Employees table and SupvName from the Supervisors table:

SELECT Employees.Department, SupvName
FROM Supervisors, Employees
WHERE Employees.Department = Supervisors.Department;

When a Recordset object is created, the Jet database engine uses the table's field name as the Field object name in the Recordset.  If you want a different field name or a name isn't implied by the expression used to generate the field, use the AS reserved word.  The following example uses the title Birth Date to name the returned Field in the resulting Recordset:

SELECT [Birth Date]
AS Birth FROM Employees;

Whenever you use aggregate functions or queries that return ambiguous or duplicate Field object names, you must use the AS clause to provide an alternate name for the Field.  The following example uses the title Head Count to name the returned Field in the resulting Recordset:

SELECT COUNT(Employee ID)
AS [Head Count] FROM Employees;

You can use the other clauses in a SELECT statement to further restrict and organize your returned data.  For more information, see the Help topic for the clause you're working with.

In your Visual Basic program, you can also create a SELECT statement in your application by concatenating local variables into the statement as needed to select, sort, or filter the data as dictated by your application.  For example, if you have a TextBox control (TitleWanted) containing the name of a Title and you want to fetch all books from the Titles table with this title, you can create an SQL statement that includes the current value of the TextBox.  Note that the SQL query encloses the TitleWanted value in single quotation marks (' '):

Set Rst = Db.OpenRecordset("SELECT * FROM Titles " _
& " WHERE Title = '" & TitleWanted.Text & "'" )


FROM Clause (SQL)

See Also	Example	Specifics

Specifies the tables or queries that contain the fields listed in the SELECT statement.

Syntax

SELECT fieldlist
FROM tableexpression [IN externaldatabase]

A SELECT statement containing a FROM clause has these parts:

Part	Description

fieldlist	The name of the field or fields to be retrieved along with any field-name aliases, SQL aggregate functions, selection predicates (ALL, DISTINCT, DISTINCTROW, or TOP), or other SELECT statement options.

tableexpression	An expression that identifies one or more tables from which data is retrieved.  The expression can be a single table name or a compound resulting from a JOIN or subquery.

externaldatabase	The full pathname of an external database containing all the tables in tableexpression.

Remarks

FROM is required and follows any SELECT statement.

The order of the table names in tableexpression isn't important.

For improved performance and ease of use, it's recommended that you use an attached table instead of an IN clause to retrieve data from an external database.

The following example shows how you can retrieve data from the Employees table:

SELECT [Last Name], [First Name]
FROM Employees;


IN Clause (SQL)

See Also	Example	Specifics

Identifies tables in any external database to which the Microsoft Jet database engine can connect, such as a dBASE or Paradox database or an external Jet database.

Syntax

To identify a destination table:

[SELECT | INSERT] INTO destination IN
{path | ["path" "type"] | ["" [type; DATABASE = path]]}

To identify a source table:

FROM tableexpression IN
{path | ["path" "type"] | ["" [type; DATABASE = path]]}

A SELECT statement containing an IN clause has these parts:

Part	Description

destination	The name of the external table into which data is inserted.

tableexpression	The name of the table or tables from which data is retrieved.  This argument can be a single table name or a compound resulting from a JOIN or subquery.

path	The full path for the directory or file containing table.

      type	The name of the database type used to create table if a database isn't a Jet database (for example, dBASE III, dBASE IV, Paradox 3.x, Paradox 4.x, or Btrieve).

Remarks

You can use IN to connect to only one external database at a time.

In some cases, the path argument refers to the directory containing the database files.  For example, when working with dBASE, FoxPro or Paradox database tables, the path argument specifies the directory containing .DBF or .DB files.  The table filename is derived from the destination or tableexpression arguments.

To specify a non-Jet database, append a semicolon (;) to the name, and enclose it in single (' ') or double (" ") quotation marks.  For example, either 'dBASE IV;' or "dBASE IV;" is acceptable.

You can also use the DATABASE reserved word to specify the external database.  For example, the following lines specify the same table:

... FROM Table IN  "" [dBASE IV; DATABASE=C:\DBASE\DATA\SALES;];

... FROM Table IN "C:\DBASE\DATA\SALES" "dBASE IV;"

Notes

For improved performance and ease of use, use an attached table instead of IN.

You can also use the IN reserved word as a comparison operator in an expression.  For more information, see the In operator.


WHERE Clause (SQL)

See Also	Example	Specifics

Specifies which records from the tables listed in the FROM clause are included in the results of the SELECT statement.

Syntax

SELECT fieldlist
FROM tableexpression
WHERE criteria

A SELECT statement containing a WHERE clause has these parts:

Part	Description

fieldlist	The name of the field or fields to be retrieved along with any field-name aliases, selection predicates (ALL, DISTINCT, DISTINCTROW, or TOP), or other SELECT statement options.

tableexpression	The name of the table or tables from which data is retrieved.

criteria	An expression that records must satisfy to be included in the query results.

Remarks

The Microsoft Jet database engine selects the records that meet the conditions listed in the WHERE clause.  If you don't specify a WHERE clause, your query returns all rows from the table.  If you specify more than one table in your query and you haven't included a WHERE clause or a JOIN clause, your query generates a Cartesian product of the tables.

WHERE is optional, but when included, follows FROM.  For example, you can select all employees in the sales department (WHERE Dept = 'Sales') or all customers between the ages of 18 and 30 (WHERE Age Between 18 And 30).

If you don't use a JOIN clause to perform SQL join operations on multiple tables, the resulting Recordset won't be updatable.

WHERE is similar to HAVING.  WHERE determines which records are selected.  Similarly, once records are grouped with GROUP BY, HAVING determines which records are displayed.

Use the WHERE clause to eliminate records you don't want grouped by a GROUP BY clause.

Use various expressions to determine which records the SQL statement returns.  For example, the following SQL statement selects all employees whose salaries are more than $21,000:

SELECT [Last Name], Salary
FROM Employees
WHERE Salary > 21000;

A WHERE clause can contain up to 40 expressions linked by logical operators, such as And and Or.

When you enter a field name that contains a space or punctuation, surround the name with brackets ([ ]):

SELECT [Product ID], [Units In Stock]
FROM Products
WHERE [Units In Stock] <= [Reorder Level];

When you specify the criteria argument, date literals must be in U.S. format, even if you're not using the U.S. version of the Jet database engine.  For example, May 10, 1994, is written 10/5/94 in the United Kingdom and 5/10/94 in the United States.  Be sure to enclose your date literals with the number sign (#) as shown in the following examples.

To find records dated May 10, 1994 in a United Kingdom database, you must use the following SQL statement:

SELECT *
FROM Orders
WHERE [Shipped Date] = #5/10/94#;

You can also use the DateValue function which is aware of the International settings established by Microsoft Windows.  For example, for code in the United States:

SELECT *
FROM Orders
WHERE [Shipped Date] = DateValue('5/10/94');

For code in the United Kingdom:

SELECT *
FROM Orders
WHERE [Shipped Date] = DateValue('10/5/94');


GROUP BY Clause (SQL)

See Also	Example	Specifics

Combines records with identical values in the specified field list into a single record.  A summary value is created for each record if you include an SQL aggregate function, such as Sum or Count, in the SELECT statement.

Syntax

SELECT fieldlist
FROM table
WHERE criteria
GROUP BY groupfieldlist

A SELECT statement containing a GROUP BY clause has these parts:

Part	Description

fieldlist	The name of the field or fields to be retrieved along with any field-name aliases, SQL aggregate functions, selection predicates (ALL, DISTINCT, DISTINCTROW, or TOP), or other SELECT statement options.

table	The name of the table from which records are retrieved.  For more information, see the FROM clause.

criteria	Selection criteria.  If the statement includes a WHERE clause, the Microsoft Jet database engine groups values after applying the WHERE conditions to the records.

groupfieldlist	The names of up to 10 fields used to group records.  The order of the field names in groupfieldlist determines the grouping levels from the highest to the lowest level of grouping.

Remarks

GROUP BY is optional.

Summary values are omitted if there is no SQL aggregate function in the SELECT statement.

Null values in GROUP BY fields are grouped and aren't omitted.  However, Null values aren't evaluated in any SQL aggregate function.

Use the WHERE clause to exclude rows you don't want grouped, and use the HAVING clause to filter records after they've been grouped.

Unless it contains Memo or OLE Object data, a field in the GROUP BY field list can refer to any field listed in the FROM clause, even if the field isn't included in the SELECT statement, provided the SELECT statement includes at least one SQL aggregate function.  The Jet database engine can't group on Memo or OLE Object fields.

All fields in the SELECT field list must either be included in the GROUP BY clause or be included as arguments to an SQL aggregate function.

When you enter a field name that contains a space or punctuation, surround the name with brackets ([ ]):

SELECT [Product Name],
Sum([Units in Stock])
FROM Products
GROUP BY [Product Name];


HAVING Clause (SQL)

See Also	Example	Specifics

Specifies which grouped records are displayed in a SELECT statement with a GROUP BY clause.  Once GROUP BY combines records, HAVING displays any records grouped by the GROUP BY clause that satisfy the conditions of the HAVING clause.

Syntax

SELECT fieldlist
FROM table
WHERE selectcriteria
GROUP BY groupfieldlist
HAVING groupcriteria

A SELECT statement containing a HAVING clause has these parts:

Part	Description

fieldlist	The name of the field or fields to be retrieved along with any field-name aliases, SQL aggregate functions, selection predicates (ALL, DISTINCT, DISTINCTROW, or TOP), or other SELECT statement options.

table	The name of the table from which records are retrieved.  For more information, see the FROM clause.

selectcriteria	Selection criteria.  If the statement includes a WHERE clause, The Microsoft Jet database engine groups values after applying the WHERE conditions to the records.

groupfieldlist	The names of up to 10 fields used to group records.  The order of the field names in groupfieldlist determines the grouping levels from the highest to the lowest level of grouping.

groupcriteria	An expression that determines which grouped records to display.

Remarks

HAVING is optional.

HAVING is similar to WHERE, which determines which records are selected.  Once records are grouped with GROUP BY, HAVING determines which records are displayed.

A HAVING clause can contain up to 40 expressions linked by logical operators, such as And and Or.


ORDER BY Clause (SQL)

See Also	Example	Specifics

Sorts a Recordset object's data on a specified field or fields in ascending or descending order.

Syntax

SELECT fieldlist
FROM table
WHERE selectcriteria
ORDER BY field1 [ASC | DESC ][, field2 [ASC | DESC ][, ...]]

A SELECT statement containing an ORDER BY clause has these parts:

Part	Description

fieldlist	The name of the field or fields to be retrieved along with any field-name aliases, SQL aggregate functions, selection predicates (ALL, DISTINCT, DISTINCTROW, or TOP), or other SELECT statement options.

table	The name of the table from which records are retrieved.  For more information, see the FROM clause.

selectcriteria	Selection criteria.  If the statement includes a WHERE clause, The Microsoft Jet database engine orders values after applying the WHERE conditions to the records.

field1, field2	The names of the fields on which to sort records.

Remarks

ORDER BY is optional (unless you use the TOP or TOP n PERCENT predicate in the fieldlist of the SELECT clause).  If you don't include ORDER BY, the data is displayed unsorted.

The default sort order is ascending (A-Z, 0-9).  However, you may want to include the ASC reserved word at the end of each field you want to sort in ascending order.  Both of the following examples sort employee names in last name order:

SELECT [Last Name], [First Name]
FROM Employees
ORDER BY [Last Name];

SELECT [Last Name], [First Name]
FROM Employees
ORDER BY [Last Name] ASC;

To sort in descending order (Z-A, 9-0), add the DESC reserved word to the end of each field you want to sort in descending order.  The following example selects salaries and sorts them in descending order:

SELECT [Last Name], Salary
FROM Employees
ORDER BY Salary DESC, [Last Name];

If you specify a field containing Memo or OLE Object data in the ORDER BY clause, an error occurs.  The Microsoft Jet database engine doesn't sort on fields of these types.

ORDER BY is usually the last item in an SQL statement.

You can include additional fields in the ORDER BY clause.  Records are sorted first by the first field listed after ORDER BY.  Records that have equal values in that field are then sorted by the value in the second field listed, and so on.


ALL, DISTINCT, DISTINCTROW Predicates (SQL)
ALL, DISTINCT, DISTINCTROW, TOP Predicates (SQL)

See Also	Example	Specifics

Specifies records selected with SQL queries.

Syntax

SELECT [ALL | DISTINCT | DISTINCTROW | [TOP n [PERCENT]]]
FROM table

A SELECT statement containing these predicates has the following parts:

Part	Description
ALL	Assumed if you don't include one of the predicates.  The Microsoft Jet database engine selects all of the records that meet the conditions in the SQL statement.  The following two examples are equivalent and return all records from the Employees table: SELECT ALL * FROM Employees ORDER BY [Employee ID]; SELECT * FROM Employees ORDER BY [Employee ID];
DISTINCT	Omits records that contain duplicate data in the selected fields.  To be included in the results of the query, the values for each field listed in the SELECT statement must be unique.  For example, several employees listed in an Employees table may have the same last name.  If two records contain Smith in the Last Name field, the following SQL statement returns only one of the records: SELECT DISTINCT [Last Name] FROM Employees; If you omit DISTINCT, this query returns both Smith records. If the SELECT clause contains more than one field, the combination of values from all fields must be unique for a given record to be included in the results. The output of a query that uses DISTINCT isn't updatable and doesn't reflect subsequent changes made by other users.
DISTINCTROW	Omits data based on entire duplicate records, not just duplicate fields.  For example, you could create a query that joins the Customers and Orders tables on the Customer ID field.  The Customers table contains no duplicate Customer ID fields, but the Orders table does because each customer can have many orders.  The following SQL statement shows how you can use DISTINCTROW to produce a list of companies that have at least one order but without any details about those orders: SELECT DISTINCTROW [Company Name] FROM Customers INNER JOIN Orders ON Customers.[Customer ID] = Orders.[Customer ID] ORDER BY [Company Name]; If you omit DISTINCTROW, this query produces multiple rows for each company that has more than one order. DISTINCTROW has an effect only when you select fields from some, but not all, of the tables used in the query.  DISTINCTROW is ignored if your query includes only one table.
TOP	Returns a certain number of records that fall at the top or the bottom of a range specified by an ORDER BY clause.  Suppose you want the names of the top 25 students from the class of 1994: SELECT TOP 25 [First Name], [Last Name] FROM Students WHERE [Graduation Year] = 1994 ORDER BY [Grade Point Average] DESC; If you don't include the ORDER BY clause, the query will return an arbitrary set of 25 records from the Students table that satisfy the WHERE clause. The TOP predicate doesn't choose between equal values.  In the preceding example, if the twenty-fifth and twenty-sixth highest grade point averages are the same, the query will return 26 records. You can also use the PERCENT reserved word to return a certain percentage of records that fall at the top or the bottom of a range specified by an ORDER BY clause.  Suppose that, instead of the top 25 students, you want the top 10 percent of the class: SELECT TOP 10 PERCENT [First Name], [Last Name] FROM Students WHERE [Graduation Year] = 1994 ORDER BY [Grade Point Average] DESC; The value that follows TOP must be an unsigned Integer. TOP doesn't affect the query's updatability.
table	The name of the table from which records are retrieved.


DELETE Statement (SQL)

See Also	Example	Specifics

Creates a delete query that removes records from one or more of the tables listed in the FROM clause that satisfy the WHERE clause.

Syntax

DELETE [table.*]
FROM tableexpression
WHERE criteria

The DELETE statement has these parts:

Part	Description

table	The optional name of the table from which records are deleted.

tableexpression	The name of the table or tables from which records are deleted.  This argument can be a single table name or a compound resulting from a JOIN or subquery.

criteria	An expression that determines which records to delete.

Remarks

DELETE is especially useful when you want to delete many records.

In a multiple-table DELETE statement, you must include the table argument.  If you specify more than one table to delete records from, they must all be many-only tables.

If you want to delete all of the records in a table, deleting the table itself may be more efficient than running a delete query.  You can use the Execute method with a DROP TABLE statement to drop a table from the database.  If you delete the table, however, the structure is lost.  In contrast, when you use DELETE, only the data is deleted; the table structure and all of the table properties, such as field attributes and indexes, remain intact.

You can use DELETE to remove records from a single table or from the many side of a one-to-many relationship.  Cascade delete operations in a query only delete from the many side of a relationship.  For example, in the relationship between the Customers and Orders tables, the Orders table is the many side, so cascade delete operations would only affect the Orders table.

A delete query deletes entire records, not just data in specific fields.  If you want to delete values in a specific field, create an update query that changes the values to Null.

Important

Once you remove records using a delete query, you can't undo the operation.  If you want to know which records were deleted, first examine the results of a select query that uses the same criteria, and then run the delete query.

Maintain backup copies of your data at all times.  If you delete the wrong records, you can retrieve them from your backup copies.


INNER JOIN Operation (SQL)

See Also	Example	Specifics

Combines records from two tables whenever there are matching values in a common field.

Syntax

FROM table1 INNER JOIN table2 ON table1.field1 = table2.field2

The INNER JOIN operation has these parts:

Part	Description

table1, table2	The names of the tables from which records are combined.

field1, field2	The names of the fields that are joined.  If they aren't numeric, the fields must be of the same data type and contain the same kind of data, but they don't have to have the same name.

Remarks

You can use an INNER JOIN operation in any FROM clause.  It creates an equi-join, which is also known as an inner join.  Equi-joins are the most common type of join.  They combine records from two tables whenever there are matching values in a field common to both tables.

You can use INNER JOIN with the Departments and Employees tables to select all the employees in each department.  In contrast, to select all departments (even if some have no employees assigned to them) or all employees (even if some aren't assigned to a department), you can use a LEFT JOIN or RIGHT JOIN operation to create an outer join.

If you try to join fields containing Memo or OLE Object data, an error occurs.

You can join any two numeric fields, even if they are of different data types.  For example, you can join a Number field, for which the Size property of its Field object is set to Integer, and a Counter field.

The following example shows how you could join the Categories and Products tables on the Category ID field:

SELECT [Category Name], [Product Name]
FROM Categories INNER JOIN Products
ON Categories.[Category ID] = Products.[Category ID];

In the preceding example, Category ID is the joined field, but it isn't included in the query output because it isn't included in the SELECT statement.  To include the joined field, include the field name in the SELECT statement [image] in this case, Categories.[Category ID].

You can also nest JOIN statements using the following syntax:

SELECT fields
FROM table1 INNER JOIN
(table2 INNER JOIN [( ]table3
[INNER JOIN [( ]tablex [INNER JOIN ...)]
ON table3.field3 = tablex.fieldx)]
ON table2.field2 = table3.field3)
ON table1.field1 = table2.field2;

A LEFT JOIN or a RIGHT JOIN may be nested inside an INNER JOIN, but an INNER JOIN may not be nested inside a LEFT JOIN or a RIGHT JOIN.


INSERT INTO Statement (SQL)

See Also	Example	Specifics

Adds a record to a table or creates an append query.

Syntax

Multiple-record append query:

INSERT INTO target [IN externaldatabase]
SELECT [source.]field1[, field2[, ...]
FROM tableexpression

Single-record append query:

INSERT INTO target [(field1[, field2[, ...]])]
VALUES (value1[, value2[, ...])

The INSERT INTO statement has these parts:

Part	Description

target	The name of the table or query to append records to.

externaldatabase	The path to an external database.  For a description of the path, see the IN clause.

source	The name of the table or query to copy records from.

field1, field2	In the syntax for a multiple-record append query, these are the names of the fields to be appended.

In the syntax for a single-record query, these are the names of fields to which you want to append specific values in a single new record.

tableexpression	The name of the table or tables from which records are inserted.   This argument can be a single table name or a compound resulting from a JOIN or subquery.

value1, value2	The values to insert into the specific fields of the new record.  Each value is inserted into the field that corresponds to the value's position in the list: value1 is inserted into field1 of the new record, value2 into field2, and so on.  You must enclose each value in double quotation marks (" ") and separate pairs of values with a comma.

Remarks

You can use the INSERT INTO statement to add a single record to a table using the single-record append query syntax as shown above.  In this case, your code specifies the name and value for each field of the record.  You must specify each of the fields of the record that a value is to be assigned to and a value for that field.  When you don't specify each field, the default value or Null is inserted for missing columns.  Records are added to the end of the table.

You can also use INSERT INTO to append a set of records from another table or query by using the SELECT ... FROM clause as shown above in the multiple-record append query syntax.  In this case, the SELECT clause specifies the fields to append to the target table specified.

The source or target table may specify a table or a query.  If a query is specified, the Microsoft Jet database engine appends to any and all tables specified by the query.

INSERT INTO is often used to append a new table of customer records to your active Customers table.

INSERT INTO is optional but when included, precedes the SELECT statement.

If your destination table contains a primary key, make sure you append unique, non-Null values to the primary key field or fields; if you don't, the Jet engine won't append the records.

If you append records to a table with a Counter field, don't include the Counter field in your query if you want the Jet engine to renumber the appended records.  Include the Counter field in the query if you want to retain the original values from the field.  If there are duplicate values, however, the Jet engine won't append the records.

Use the IN clause to append records to a table in another database.

To create a new table, use the SELECT... INTO statement instead to create a make-table query.

To find out which records will be appended before you run the append query, first execute and view the results of a select query that uses the same selection criteria.

An append query copies records from one or more tables to another.  The tables that contain the records you append aren't affected by the append query.

Instead of appending existing records from another table, you can specify the value for each field in a single new record using the VALUES clause.  If you omit the field list, the VALUES clause must include a value for every field in the table; otherwise, the INSERT will fail.  Use an additional INSERT INTO statement with a VALUES clause for each additional record you want to create.


LEFT JOIN, RIGHT JOIN Operations (SQL)

See Also	Example	Specifics

Combines source-table records when used in any FROM clause.

Syntax

FROM table1 [ LEFT | RIGHT ] JOIN table2
ON table1.field1 = table2.field2

The LEFT JOIN and RIGHT JOIN operations have these parts:

Part	Description

table1, table2	The names of the tables from which records are combined.

field1, field2	The names of the fields that are joined.  The fields must be of the same data type and contain the same kind of data, but they don't have to have the same name.

Remarks

Use a LEFT JOIN operation to create a left outer join.  Left outer joins include all of the records from the first (left-hand) of two tables, even if there are no matching values for records in the second (right-hand) table.

Use a RIGHT JOIN operation to create a right outer join.  Right outer joins include all of the records from the second (right-hand) of two tables, even if there are no matching values for records in the first (left-hand) table.

For example, you could use LEFT JOIN with the Departments (left) and Employees (right) tables to select all departments, including those that have no employees assigned to them.  To select all employees, including those who aren't assigned to a department, you would use RIGHT JOIN.

The following example shows how you could join the Categories and Products tables on the Category ID field.  The query produces a list of all categories, including those that contain no products:

SELECT [Category Name],
[Product Name]
FROM Categories LEFT JOIN Products
ON Categories.[Category ID] = Products.[Category ID];

In this example, Category ID is the joined field, but it isn't included in the query results because it isn't included in the SELECT statement.  To include the joined field, enter the field name in the SELECT statement [image] in this case, Categories.[Category ID].

Notes

To create a query that includes only records in which the data in the joined fields is the same, use an INNER JOIN operation.

You can nest INNER, RIGHT, and LEFT joins.  See the discussion of nesting in the INNER JOIN topic to see how to nest joins of any type within other joins.

If you try to join fields containing Memo or OLE Object data, an error occurs.


PARAMETERS Declaration (SQL)

See Also	Example	Specifics

Declares the name and data type of each parameter in a parameter query.

Syntax

PARAMETERS text datatype [, text datatype [, ...]]

The PARAMETERS declaration has these parts:

Part	Description

text	The name of the parameter.  Assigned to the Name property of the Parameter object and used to identify this parameter in the Parameters collection.  You can use text as a string that is displayed in a dialog box while your application runs the query.  Use brackets ([ ]) to enclose text that contains spaces or punctuation.  For example, [Low price] and [Begin report with which month?] are valid text arguments.

datatype	The parameter's data type.

Remarks

For queries that you run regularly, you can use a PARAMETERS declaration to create a parameter query.  A parameter query can help automate the process of changing query criteria.  With a parameter query, your code will need to provide the parameters each time the query is run.

The PARAMETERS declaration is optional but when included precedes any other statement, including SELECT.

If the declaration includes more than one parameter, separate them with commas.  The following example includes two parameters:

PARAMETERS [Low price] Currency, [Beginning date] DateTime;

You can use text but not datatype in a WHERE or HAVING clause.  The following example expects two parameters to be provided and then applies the criteria to records in the Orders table:

PARAMETERS [Low price] Currency,
[Beginning date] DateTime;
SELECT [Order ID], [Order Amount]
FROM Orders
WHERE [Order Amount] > [Low price]
AND [Order Date] >= [Beginning date];

The following example shows how to use parameters in your Visual Basic program:

Dim SQL As String, Qd as QueryDef, Rs as Recordset

SQL = "PARAMETERS [Low price] Currency, " _
& " 	[Beginning date] DateTime; " _
& " 	SELECT [Order ID], [Order Amount] " _
& " 	FROM Orders " _
& " 	WHERE [Order Amount] > [Low price] " _
& " 	AND [Order Date] >= [Beginning date];"

Set Qd = Db.CreateQueryDef("MyParameterQuery", SQL)

Qd.Parameters![Low Price] = 1.99

Qd.Parameters![Beginning date] = "#12/31/95#"

Set Rs = Qd.OpenRecordset()


PROCEDURE Clause (SQL Only)

See Also	Example	Specifics

Defines the name of a query.

Syntax

PROCEDURE name [param1 datatype[, param2 datatype[, ...]]

The PROCEDURE clause has these parts:

Part	Description

name	A name for the procedure.  It must follow standard naming conventions.

param1, param2	One or more field names or parameters.  For example:

PROCEDURE Sales_By_Country [Beginning Date] DateTime, [Ending Date] DateTime;

For more information on parameters, see PARAMETERS.

datatype	One of the 13 primary Microsoft Jet SQL data types or their synonyms.

Remarks

An SQL procedure consists of a PROCEDURE clause (which specifies the name of the procedure), a list of parameter definitions, and a single SQL statement.  For example, the procedure Get_Part_Number might run a query that retrieves a specified part number.

Notes

If the clause includes more than one field definition (that is, param-datatype pairs), separate them with commas.

The PROCEDURE clause must be followed by an SQL statement (for example, a SELECT or UPDATE statement).


SELECT...INTO Statement (SQL)

See Also	Example	Specifics

Creates a make-table query.

Syntax

SELECT field1[, field2[, ...]] INTO newtable [IN externaldatabase]
FROM source

The SELECT...INTO statement has these parts:

Part	Description

field1, field2	The name of the fields to be copied into the new table.

newtable	The name of the table to be created.  It must conform to standard naming conventions.  If newtable is the same as the name of an existing table, a trappable error will result.

externaldatabase	The path to an external database.  For a description of the path, see the IN clause.

source	The name of the existing table from which records are selected.  This can be either a single table or a compound resulting from a JOIN or a subquery.

Remarks

You can use make-table queries to archive records, make backup copies of your tables, or make copies to export to another database or to use as a basis for reports that display data for a particular time period.  For example, you could produce a Monthly Sales by Region report by running the same make-table query each month.

Notes

You may want to define a primary key for the new table.  When you create the table, the fields in the new table inherit the data type and field size of each field in the query's underlying tables, but no other field or table properties are transferred.

To add data to an existing table, use the INSERT INTO statement instead to create an append query.

To find out which records will be selected before you run the make-table query, first examine the results of an action query that uses the same selection criteria.


SQL Subqueries

See Also	Example	Specifics

A subquery is a SELECT statement nested inside a SELECT, SELECT...INTO, INSERT...INTO, DELETE, or UPDATE statement or inside another subquery.

Syntax

You can use three forms of syntax to create a subquery:

comparison [ANY | ALL | SOME] (sqlstatement)

expression [NOT] IN (sqlstatement)

 [NOT] EXISTS (sqlstatement)

A subquery has these parts:

Part	Description

comparison	An expression and a comparison operator that compares the expression with the results of the subquery.

expression	An expression for which the result set of the subquery is searched.

sqlstatement	A SELECT statement, following the same format and rules as any other SELECT statement.  It must be enclosed in parentheses.

Remarks

You can use a subquery instead of an expression in the field list of a SELECT statement or in a WHERE or HAVING clause.  In a subquery, you use a SELECT statement to provide a set of one or more specific values to evaluate in the WHERE or HAVING clause expression.

Use the ANY or SOME predicate, which are synonymous, to retrieve records in the main query that satisfy the comparison with any records retrieved in the subquery.  The following example returns all products whose unit price is greater than that of any product sold at a discount of 25 percent or more:

SELECT * FROM Products
WHERE [Unit Price] > ANY
(SELECT [Unit Price] FROM [Order Details]
WHERE [Discount] >= .25);

Use the ALL predicate to retrieve only those records in the main query that satisfy the comparison with all records retrieved in the subquery.  If you changed ANY to ALL in the above example, the query would return only those products whose unit price is greater than that of all products sold at a discount of 25 percent or more.  This is much more restrictive.

Use the IN predicate to retrieve only those records in the main query for which some record in the subquery contains an equal value.  The following example returns all products sold at a discount of 25 percent or more:

SELECT * FROM Products
WHERE [Product ID] IN
(SELECT [Product ID] FROM [Order Details]
WHERE [Discount] >= .25);

Conversely, you can use NOT IN to retrieve only those records in the main query for which no record in the subquery contains an equal value.

Use the EXISTS predicate (with the optional NOT reserved word) in true/false comparisons to determine whether the subquery returns any records.

You can also use table name aliases in a subquery to refer to tables listed in a FROM clause outside the subquery.  In this example, the Employees table is given the alias "T1":

SELECT [Last Name],
[First Name], Title, Salary
FROM Employees AS T1
WHERE Salary >=
(SELECT Avg(Salary)
FROM Employees
WHERE T1.Title = Employees.Title) Order by Title;

In the preceding example, the AS reserved word is optional.


TRANSFORM Statement (SQL)

See Also	Example	Specifics

Creates a crosstab query.

Syntax

TRANSFORM aggfunction
selectstatement
PIVOT pivotfield [IN (value1[, value2[, ...]])]

The TRANSFORM statement has these parts:

Part	Description

aggfunction	An SQL aggregate function that operates on the selected data.

selectstatement	A SELECT statement.

pivotfield	The field or expression you want to use to create column headings in the query's result set.

value1, value2	Fixed values used to create column headings.

Remarks

When you summarize data using a crosstab query, you select values from specified fields or expressions as column headings so you can view data in a more compact format than with a select query.

TRANSFORM is optional but when included is usually the first statement in an SQL string.  It precedes a SELECT statement that specifies the fields used as row headings and a GROUP BY clause that specifies row grouping.  Optionally, you can include other clauses, such as WHERE, that specify additional selection or sorting criteria.

The values returned in pivotfield are used as column headings in the query's result set.  For example, pivoting the sales figures on the month of the sale in a crosstab query would create 12 columns.  You can restrict pivotfield to create headings from fixed values (value1, value2 ) listed in the optional IN clause.  You can also include fixed values for which no data exists to create additional columns.


UNION Operation (SQL)

See Also	Example	Specifics

You use the UNION operation to create a union query, combining the results of two or more independent queries or tables.

Syntax

query1 UNION [ALL] query2 [UNION [ALL] queryn [ ... ]]

The query placeholder represents a string expression identifying the field that contains the numeric data you want to average or an expression that performs a calculation using the data in that field.  Operands in query can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

You can merge the results of a query and an SQL statement in a single UNION operation.  The following example merges the results of an existing query named New Accounts and a SELECT statement:

TABLE [New Accounts] UNION ALL
SELECT *
FROM Customers
WHERE [Order Amount] > 1000;

By default, no duplicate records are returned when you use a UNION operation; however, you can include the ALL predicate to ensure that all records are returned.  This also makes the query run faster.

All queries in a UNION operation must request the same number of fields; however, the fields don't have to be of the same size or data type.

Notes

You can use a GROUP BY and/or HAVING clause in each query argument to group the returned data.

You can use an ORDER BY clause at the end of the last query argument to display the returned data in a specified order.


UPDATE Statement (SQL)

See Also	Example	Specifics

Creates an update query that changes values in fields in a specified table based on specified criteria.

Syntax

UPDATE table
SET newvalue
WHERE criteria;

The UPDATE statement has these parts:

Part	Description

table	The name of the table whose data you want to modify.

newvalue	An expression that determines the value to be inserted into a particular field in the updated records.

criteria	An expression that determines which records will be updated.  Only records that satisfy the expression are updated.

Remarks

UPDATE is especially useful when you want to change many records or when the records that you want to change are in multiple tables.

Generally, you use the UPDATE statement with the Execute method.

You can change several fields at the same time.  The following example increases the Order Amount values by 10 percent and the Freight values by 3 percent for shippers in the United Kingdom:

UPDATE Orders
SET [Order Amount] = [Order Amount] * 1.1,
Freight = Freight * 1.03
WHERE [Ship Country] = 'UK';

UPDATE doesn't generate a result set.  If you want to know which records will be changed, first examine the results of a select query that uses the same criteria, and then run the update query.


WITH OWNERACCESS OPTION Declaration (SQL)

See Also	Example	Specifics

In a multiuser environment with a secure workgroup, use the WITH OWNERACCESS OPTION with a query to give the user who runs the query permission to view the data in the query even if the user is otherwise restricted from viewing the query's underlying tables.

Syntax

sqlstatement
WITH OWNERACCESS OPTION

Remarks

The WITH OWNERACCESS OPTION declaration is optional.

The following example enables the user to return salary information, even if the user doesn't otherwise have permission to view the Payroll table, provided the query is created by someone who has that permission:

SELECT [Last Name],
[First Name], Salary
FROM Employees
ORDER BY [Last Name]
WITH OWNERACCESS OPTION;

If a user is otherwise prevented from creating or adding to a table, you can use WITH OWNERACCESS OPTION to enable the user to run a make-table or append query.

If you want to enforce workgroup security settings and users' permissions, don't include the WITH OWNERACCESS OPTION declaration.

This option requires you to have access to the SYSTEM.MDA file associated with the database.  It's really useful only in secured multiuser implementations.


SQL Aggregate Functions (SQL Only)

See Also	Example	Specifics

Using the SQL aggregate functions, you can determine various statistics on sets of values.  You can use these functions in a query expression, but not in Microsoft Visual Basic code outside of an SQL query string.  You can also use aggregate expressions in the SQL property of a QueryDef object or when creating a Recordset object based on an SQL query.

Avg Function

Count Function

Min, Max Functions

StDev, StDevP Functions

Sum Function

Var, VarP Functions


Avg Function (SQL)

See Also	Example	Specifics

Calculates the arithmetic mean of a set of values contained in a specified field on a query.

Syntax

Avg(expr)

The expr placeholder represents a string expression identifying the field that contains the numeric data you want to average or an expression that performs a calculation using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

The average calculated by Avg is the arithmetic mean (the sum of the values divided by the number of values).  You could use Avg, for example, to calculate average freight cost.

The Avg function doesn't include any Null fields in the calculation.

You can use Avg in a query expression and in the SQL property of a QueryDef object or when creating a Recordset based on an SQL query.


Count Function (SQL)

See Also	Example	Specifics

Calculates the number of records returned by a query.

Syntax

Count(expr)

The expr placeholder represents a string expression identifying the field that contains the data you want to count or an expression that performs a calculation using the data in the field.  Operands in expr can include the name of one or more table fields, constants, or functions (which can be either intrinsic or user-defined but not other SQL aggregate or domain aggregate functions).  You can count any kind of data, including text.

Remarks

You can use Count to count the number of records in an underlying query.  For example, you could use Count to count the number of orders shipped to a particular country.  In a dynamic database where the data is subject to change, the value returned by Count is only accurate until the database changes [image] records are added or deleted, or fields that affect the criterion in the query change.  For this reason, you should not expect a SELECT query to necessarily return the same number of rows.

Although expr can perform a calculation on a field, Count simply tallies the number of records.  It doesn't matter what values are stored in the records.

The Count function doesn't count records that have null fields unless expr is the asterisk (*) wildcard character.  If you use an asterisk, Count calculates the total number of records, including those that contain null fields.  Count(*) is considerably faster than Count([Column Name]).  Don't enclose the asterisk in quotation marks (" ").  The following example calculates the number of records in the Orders table:

SELECT Count(*)
AS [Total Orders] FROM Orders;

If expr identifies multiple fields, the Count function counts a record only if at least one of the fields is not Null.  If all of the specified fields are Null, the record isn't counted.  Separate the field names with an ampersand (&).  The following example shows how you can limit the count to records in which either Shipped Date or Freight isn't Null:

SELECT
Count('[Shipped Date] & [Freight]')
AS [Not Null] FROM Orders;

You can use Count in a query expression.  You can also use this expression in the SQL property of a QueryDef object or when creating a Recordset object based on an SQL query.


First, Last Functions (SQL)

See Also	Example	Specifics

Return a field value from the first or last record in a query.

Syntax

First(expr)
Last(expr)

The expr placeholder represents a string expression identifying the field that contains the data you want to use or an expression that performs a calculation using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

You can use First and Last to determine the limits of the underlying query.  For example, the records returned by First and Last might contain order dates that you could use in a report title to identify the range for orders.

You can use First and Last in a query expression.  You can also use this expression in the SQL property of a QueryDef object or when creating a Recordset based on an SQL query.


Min, Max Functions (SQL)

See Also	Example	Specifics

Return the minimum or maximum of a set of values contained in a specified field on a query.

Syntax

Min(expr)

Max(expr)

The Min and Max functions have this part:

The expr placeholder represents a string expression identifying the field that contains the data you want to evaluate or an expression that performs a calculation using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

You can use Min and Max to determine the smallest and largest values in a field, including a Text field.  For example, you could use these functions to return the lowest and highest freight cost.

You can use Min and Max in a query expression and in the SQL property of a QueryDef object or when creating a Recordset object based on an SQL query.


StDev, StDevP Functions (SQL)

See Also	Example	Specifics

Return estimates of the standard deviation for a population or a population sample represented as a set of values contained in a specified field on a query.

Syntax

StDev(expr)

StDevP(expr)

The expr placeholder represents a string expression identifying the field that contains the numeric data you want to evaluate or an expression that performs a calculation using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

StDevP evaluates a population, and StDev evaluates a population sample.

If the underlying query contains fewer than two records (or no records, for StDevP), these functions return a Null (which indicates that a standard deviation can't be calculated).

You can use StDev and StDevP in a query expression.  You can also use this expression in the SQL property of a QueryDef object or when creating a Recordset object based on an SQL query.


Sum Function (SQL)

See Also	Example	Specifics

Returns the sum of a set of values contained in a specified field on a query.

Syntax

Sum(expr)

The expr placeholder represents a string expression identifying the field that contains the numeric data you want to add or an expression that performs a calculation using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

Sum totals the values in a field.  For example, you could use Sum to determine the total cost of freight charges.

The Sum function treats records that contain Null fields as having a value of 0.  The following example shows how you can calculate the sum of the products of Unit Price and Quantity fields:

SELECT
Sum([Unit Price] * [Quantity])
AS [Total Revenue]  FROM [Order Details];

You can use Sum in a query expression.  You can also use this expression in the SQL property of a QueryDef object or when creating a Recordset based on an SQL query.


Var, VarP Functions (SQL)

See Also	Example	Specifics

Return estimates of the variance for a population or a population sample represented as a set of values contained in a specified field on a query.

Syntax

Var(expr)
VarP(expr)

VarP evaluates a population, and Var evaluates a population sample.

The expr placeholder represents a string expression identifying the field that contains the numeric data you want to evaluate or an expression that performs a calculation using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other SQL aggregate or domain aggregate functions).

Remarks

If the underlying query contains fewer than two records, Var and VarP return a Null (which indicates that a variance can't be calculated).

You can use Var and VarP in a query expression or in an SQL statement.


Var, VarP Functions See Also
See Also

Domain Aggregate Functions

DVar, DVarP Functions (SQL)

SQL Aggregate Functions


Domain Aggregate Functions (SQL)

See Also	Example	Specifics

Using the domain aggregate functions, you can determine various statistics about domains.  You can use these functions in a query expression.

Note   It's easier and more efficient to use queries or subqueries instead of domain functions, which are included for compatibility with earlier versions.

The domain aggregate functions:

Must be included in SQL SELECT statements [image] usually in a WHERE clause.

Require that you enclose the individual arguments of the function in quotation marks.  You can use single quotation marks (' ') inside the SQL statement except where you must refer to literals within the statement.  In this case, you must use double quotation marks (" ") as shown below.

Most domain aggregate functions can be converted to subqueries.  For example:

DCount (expr, source, restriction)

Is equivalent to:

SELECT Count(expr) FROM source WHERE restriction;

For the DCount function, you could use the domain aggregate function:

SELECT * FROM Orders
WHERE
DCount('[Order Amount]',
'Orders', '[Ship Country]' = ""UK"" ) > 1;

Or, you could use a subquery:

SELECT * FROM Orders WHERE
(SELECT Count([Order Amount]) FROM Orders
WHERE [Ship Country] = 'UK' ) > 1;


DAvg Function (SQL)

See Also	Example	Specifics

Returns the arithmetic mean of a set of values in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DAvg(expr, domain[, criteria])

The DAvg function has these parts:

Part	Description

expr	String expression identifying the field that contains the numeric data you want to average or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be either intrinsic or user-defined but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DAvg is performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DAvg evaluates expr against the entire domain.

Remarks

The average calculated by DAvg is the arithmetic mean (the sum of the values divided by the number of values).  You could use DAvg to calculate average freight cost.

Records that contain null fields aren't included in the calculation.


DCount Function (SQL)

See Also	Example	Specifics

Returns the number of selected records in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DCount(expr, domain[, criteria])

The DCount function has these parts:

Part	Description

expr	String expression identifying the field that contains the data you want to count or an expression that performs calculations using the data in that field.  Operands in expr can include the name of one or more table fields, constants, or intrinsic functions (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).  You can count any kind of data, including text.

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DCount is performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DCount evaluates expr against the entire domain.

Remarks

If you don't need to know particular values, you can use DCount to count the number of records in a domain.  For example, you could use DCount to count the number of orders shipped to a particular region.  Although expr can perform a calculation on a field, DCount simply tallies the number of records.  It doesn't matter what values are stored in the records.

Unless expr is the asterisk (*) wildcard character, the DCount function doesn't count records that contain null fields.  If you use an asterisk, DCount calculates the total number of records, including those that contain null fields.  The following example calculates the number of records in the Orders table:

SELECT DCount('*', 'Orders');

If domain is an indexed table, you can also count the total number of records by setting expr to the primary key field.  The primary key field in an indexed table won't be Null.

If the criteria argument contains text that isn't numeric (other than field names), you must enclose the text in single quotation marks (' ').

If expr identifies multiple fields, separate the field names with either a plus sign (+) or an ampersand (&).


DFirst, DLast Functions (SQL)

See Also	Example	Specifics

Return a field value from the first and last record in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DFirst(expr, domain[, criteria])

DLast(expr, domain[, criteria])

The DFirst and DLast functions have these parts:

Part	Description

expr	String expression identifying the field that contains the data you want to return or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DFirst or DLast is performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, expr is evaluated against the entire domain.

Remarks

DFirst and DLast are similar to DLookup.  These functions return a field value from the record that satisfies criteria.  DFirst and DLast return values from the first and last occurrence according to the order of records in domain.  If domain is an indexed table, the order follows the current index.  Otherwise, the order follows the actual order of the records.

If more than one record satisfies criteria, DFirst returns the field value from the first occurrence, and DLast returns the field value from the last occurrence.

You can use DFirst and DLast to determine the limits of a domain.  For example, the fields returned by DFirst and DLast might contain order dates that you could use in a report title to indicate the range of orders.

If the criteria argument contains text that isn't numeric (other than field names), you must enclose the text in single quotation marks (' ').

If no record satisfies criteria or if domain contains no records, DFirst and DLast return a Null.


DLookup Function (SQL)

See Also	Example	Specifics

Returns a field value in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DLookup(expr, domain[, criteria])

The DLookup function has these parts:

Part	Description

expr	String expression identifying the field that contains the data you want to return or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DLookup is performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DLookup evaluates expr against the entire domain.

Remarks

You can use DLookup to return a field value based on the value of another field.  In the following example from the Employees table, DLookup uses the Employee ID field to return the corresponding last name:

SELECT DLookup("[Last Name]", "Employees", "[Employee ID] = 24";

If the criteria argument contains text that isn't numeric (other than field names), you must enclose the text in single quotation marks (' ').

Even if more than one record satisfies criteria, DLookup returns only one field.  If no record satisfies criteria or if domain contains no records, DLookup returns a Null.


DMin, DMax Functions (SQL)

See Also	Example	Specifics

Return the minimum and maximum of a set of values in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DMin(expr, domain[, criteria])
DMax(expr, domain[, criteria])

The DMin and DMax functions have these parts:

Part	Description

expr	String expression identifying the field that contains the data you want to evaluate or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DMin and DMax are performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DMin and DMax evaluate expr against the entire domain.

Remarks

You can use DMin and DMax to return the lowest and highest value.  If expr identifies numeric data, these functions return numeric values.  If expr identifies data that isn't numeric, they return the string that is first or last alphabetically.

If the criteria argument contains text that isn't numeric other than field names, you must enclose the text in single quotation marks (' ').

If no record satisfies criteria or if domain contains no records, DFirst and DLast return a Null.


DStDev, DStDevP Functions (SQL)

See Also	Example	Specifics

Return estimates of the standard deviation for a population or a population sample represented as a set of values in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DStDev(expr, domain[, criteria])

DStDevP(expr, domain[, criteria])

The DStDev and DStDevP functions have these parts:

Part	Description

expr	String expression identifying the field that contains the numeric data you want to evaluate or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DStDev and DStDevP are performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DStDev and DStDevP evaluate expr against the entire domain.

Remarks

DStDevP evaluates a population, and DStDev evaluates a population sample.

If the criteria argument contains text that isn't numeric (other than field names), you must enclose the text in single quotation marks (' ').

If domain refers to fewer than two records or if fewer than two records satisfy criteria, DStDev and DStDevP return a Null (which indicates that a standard deviation can't be calculated).


DSum Function (SQL)

See Also	Example	Specifics

Returns the sum of a set of values in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DSum(expr, domain[, criteria])

The DSum function has these parts:

Part	Description

expr	String expression identifying the field that contains the numeric data you want to add or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DSum is performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DSum evaluates expr against the entire domain.

Remarks

Unlike the DCount function, which returns the number of records, DSum totals the values in a field.  For example, you could use DSum to determine the total cost of freight charges.

If the criteria argument contains text that isn't numeric other than field names, you must enclose the text in single quotation marks (' ').


DVar, DVarP Functions (SQL)

See Also	Example	Specifics

Return estimates of the variance for a population or a population sample represented as a set of values in a specified domain.

Note   It's easier and more efficient to use a query or subquery instead of this function.  It's included for compatibility with earlier versions.

Syntax

DVar(expr, domain[, criteria])

DVarP(expr, domain[, criteria])

DVarP evaluates a population, and DVar evaluates a population sample.

The DVar and DVarP functions have these parts:

Part	Description

expr	String expression identifying the field that contains the numeric data you want to evaluate or an expression that performs calculations using the data in that field.  Operands in expr can include the name of a table field, a constant, or a function (which can be intrinsic but not one of the other domain aggregate or SQL aggregate functions).

domain	String expression identifying the records that constitute the domain.  It can be a table name or a query name.

criteria	Optional string expression used to restrict the range of data on which DVar and DVarP are performed.  For example, criteria could be the WHERE clause in an SQL expression (without the word WHERE).  If criteria is omitted, DVar and DVarP evaluate expr against the entire domain.

Remarks

If the criteria argument contains text that isn't numeric other than field names, you must enclose the text in single quotation marks (' ').

If domain refers to fewer than two records or if fewer than two records satisfy criteria, DVar and DVarP return a Null (which indicates that a variance can't be calculated).


Between...And Operator (SQL)

See Also	Example	Specifics

Determines whether the value of an expression lies within a specified range of values.  This operator can only be used within SQL statements.

Syntax

expr [Not] Between value1 And value2

The Between...And operator syntax has these parts:

Part	Description

expr	Expression identifying the field that contains the data you want to evaluate

value1, value2	Expressions against which you want to evaluate expr

Remarks

If the value of expr is between value1 and value2 (inclusive), the Between...And operator returns True; otherwise, it returns False.  You can include the Not logical operator to evaluate the opposite condition (that is, whether expr lies outside the range defined by value1 and value2).

You might use Between...And to determine whether the value of a field falls within a specified numeric range.  The following example determines whether an order was shipped to a location within a range of ZIP codes.  If the ZIP Code is between 98101 and 98199, the IIf function returns "Local".  Otherwise, it returns "Nonlocal".

SELECT IIf([ZIP] Between 98101 And 98199, "Local", "Nonlocal")
FROM Publishers

If expr, value1, or value2 is Null, Between...And returns a Null.


Comparison of Data Types

See Also	Example	Specifics

The Microsoft Jet database engine recognizes several overlapping sets of data types; which data type you use depends on whether or not you're writing code in Visual Basic or in one of the Microsoft Access development contexts.  In Microsoft Access, there are four different contexts, each with its own set of data types [image] a table's Design view, the Query Parameters dialog box, Access Basic, and a query's SQL view.  See online Help in Microsoft Access for more information on these contexts.

The following table compares the four sets of data types that correspond to each context.  The first column lists the Type property settings available in a table's Design view and the five FieldSize property settings for the Number data type.  The second column lists the data types for designing parameter queries that are available in the Query Parameters dialog box.  The third column lists the Visual Basic data types.  The fourth column lists the Microsoft Access SQL data types defined by the Jet engine along with their valid synonyms.

Table fields	Query  parameters	Visual  Basic	Microsoft Access SQL and synonyms
Not supported	Binary	Not supported	BINARY (See Notes) VARBINARY
Yes/No	Yes/No	Boolean	BOOLEAN BIT, LOGICAL, LOGICAL1, YESNO
Number; Size = Byte	Byte	Byte	BYTE INTEGER1
Counter	Not supported	Long	COUNTER AUTOINCREMENT
Currency	Currency	Currency	CURRENCY MONEY
Date/Time	Date/Time	Variant (See Notes)	DATETIME DATE, TIME, TIMESTAMP
Number; Size = Single	Single	Single	SINGLE, FLOAT4, IEEESINGLE, REAL
Number; Size = Double	Double	Double	DOUBLE FLOAT, FLOAT8, IEEEDOUBLE, NUMBER, NUMERIC
Number; Size = Integer	Integer (See Notes)	Integer (See Notes)	SHORT, INTEGER2, SMALLINT
Number; Size = Long Integer	Long Integer	Long	LONG (See Notes) INT, INTEGER, INTEGER4
OLE Object	OLE Object	String	LONGBINARY GENERAL, OLEOBJECT
Memo	Memo	String	LONGTEXT LONGCHAR, MEMO, NOTE
Text	Text	String	TEXT ALPHANUMERIC, CHAR, CHARACTER, STRING, VARCHAR
Not supported	Value	Variant	VALUE (See Notes)
Notes

The Jet engine itself doesn't use the BINARY data type.  It's recognized only for use in queries on attached tables from other database products that support the BINARY data type.

If you want to declare a Visual Basic variable that contains date/time information, declare it as a Variant.  If you create a Date/Time table field in SQL view or in a table's Design view using Microsoft Access, check the field's Type property in Visual Basic; the returned integer constant corresponds to the constant dbDate (defined by the Jet engine) instead of the Variant date constant vbDate.  The variable types represented by these two constants are fully compatible, however, and no type mismatch error will occur if a Variant variable contains data from a Date/Time field in a Jet engine table or query.

The Integer data type in Jet engine SQL doesn't correspond to the Integer data type for table fields, query parameters, or Visual Basic.  Instead, in Jet engine SQL, Integer corresponds to a Long Integer for table fields and query parameters and to a Long data type in Visual Basic.

The VALUE reserved word doesn't represent a data type defined by the Jet database engine.  However, in Microsoft Access or SQL queries, VALUE can be considered a valid synonym for the Visual Basic Variant data type.


Comparison of Microsoft Jet Database Engine SQL and ANSI SQL

See Also	Example	Specifics

Microsoft Jet database engine SQL is generally ANSI-89 Level 1 compliant.  However, certain ANSI SQL features aren't implemented in Jet engine SQL.  Conversely, Jet engine SQL includes reserved words and features not supported in ANSI SQL.

Major Differences

Jet engine SQL and ANSI SQL each have different reserved words and data types.  For more information, see Microsoft Jet Database Engine SQL Reserved Words and Equivalent ANSI SQL Data Types.

Different rules apply to the Between...And construct, which has the following syntax:

expression1 [NOT] BETWEEN expression2 AND expression3

In Jet engine SQL, expression2 can be greater than expression3; in ANSI SQL, expression2 must be equal to or less than expression3.

Different wildcard characters are used with the Like predicate.

Matching character	Jet engine SQL	ANSI SQL
Any single character	?	_ (underscore)
Zero or more characters	*	%
Jet engine SQL is generally less restrictive.  For example, it permits grouping and ordering on expressions.

Jet engine SQL supports more powerful expressions.  For example, you can include any Visual Basic in a Jet engine SQL statement.

Enhanced Features of Jet Engine SQL

The TRANSFORM statement, which provides support for crosstab queries

Additional aggregate functions, such as StDev and VarP

The PARAMETERS declaration for defining parameter queries

ANSI SQL Features Not Supported in Jet Engine SQL

Security statements, such as COMMIT, GRANT, and LOCK; instead, you can use Visual Basic.

DISTINCT aggregate function references.  For example, Jet engine SQL doesn't allow SUM(DISTINCT columnname).

The LIMIT TO nn ROWS clause used to limit the number of rows returned by a query. Only the WHERE clause can be used to limit the scope of a query.


Equivalent ANSI SQL Data Types

See Also	Example	Specifics

The following table lists ANSI SQL data types and the equivalent Microsoft Jet database engine SQL data types and their valid synonyms.

ANSI SQL  data type	Jet engine  SQL data type	Synonym
BIT, BIT VARYING	BINARY (See Notes)	VARBINARY
Not supported	BIT (See Notes)	BOOLEAN, LOGICAL, LOGICAL1, YESNO
Not supported	BYTE	INTEGER1
Not supported	COUNTER	AUTOINCREMENT
Not supported	CURRENCY	MONEY
DATE, TIME, TIMESTAMP	DATETIME	DATE, TIME, TIMESTAMP
DECIMAL	Not supported
REAL	SINGLE	FLOAT4, IEEESINGLE, REAL
DOUBLE PRECISION, FLOAT	DOUBLE	FLOAT, FLOAT8, IEEEDOUBLE, NUMBER, NUMERIC
SMALLINT	SHORT	INTEGER2, SMALLINT
INTEGER	LONG	INT, INTEGER, INTEGER4
INTERVAL	Not supported
Not supported	LONGBINARY	GENERAL, OLEOBJECT
Not supported	LONGTEXT	LONGCHAR, MEMO, NOTE
CHARACTER, CHARACTER VARYING	TEXT	ALPHANUMERIC, CHAR, CHARACTER, STRING, VARCHAR
Not supported	VALUE (See Notes)
Notes

The ANSI SQL BIT data type doesn't correspond to the Jet engine SQL BIT data type, but it corresponds to the BINARY data type instead.  There is no ANSI SQL equivalent for the Jet engine SQL BIT data type.

The BINARY data type is recognized only for use in queries on attached tables from other database products that support the BINARY data type.

The VALUE reserved word doesn't represent a data type defined by the Jet engine.  However, in Microsoft Access or SQL queries, VALUE can be considered a valid synonym for the Visual Basic Variant data type.


Like Operator (SQL)

See Also	Example	Specifics

Used to compare a string expression to a pattern in an SQL expression.

Syntax

Expression Like "pattern"

The Like operator syntax has these parts:

Part	Description

expression	SQL expression used in a WHERE clause.

pattern	String or character string literal against which expression is compared.

Remarks

You can use the Like operator to find values in a field that match the pattern you specify.  For pattern, you can specify the complete value (for example, Like "Smith"), or you can use wildcard characters like those recognized by the operating system to find a range of values (for example, Like "Sm*").

In an expression, you can use the Like operator to compare a field value to a string expression.  For example, if you enter Like "C*" in an SQL query, the query returns all field values beginning with the letter C.  In a parameter query, you can prompt the user for a pattern to search for.

You can also use Like in an expression as a setting for the ValidationRule property.  The following example returns data that begins with the letter P followed by any letter between A and F and three digits:

Like "P[A-F]###"

In Visual Basic, if expression matches pattern, result is True (-1); if there is no match, result is False (0); and if either expression or pattern is a Null, result is also a Null.


Microsoft Jet Database Engine SQL Data Types

See Also	Example	Specifics

The Microsoft Jet engine SQL data types consist of 13 primary data types defined by the Microsoft Jet database engine and several valid synonyms recognized for these data types.

The following table lists the primary data types.  The synonyms are identified in the Comparison of Data Types and Jet Database Engine SQL Reserved Words topics.

Data type	Storage size	Description
BINARY	1 byte	For queries on attached tables from database products that define a Binary data type.
BIT	1 byte	Yes and No values and fields that contain only one of two values.
BYTE	1 byte	An integer value between 0 and 255.
COUNTER	4 bytes	A number automatically incremented by the Jet engine whenever a new record is added to a table.  In the Jet engine, the data type for this value is a Long.
CURRENCY	8 bytes	A scaled integer between -922,337,203,685,477.5808 and 922,337,203,685,477.5807.
DATETIME (See DOUBLE)	8 bytes	A date or time value between the years 100 and 9999.
SINGLE	4 bytes	A single-precision floating-point value with a range of -3.402823E38 to -1.401298E-45 for negative values, 1.401298E-45 to 3.402823E38 for positive values, and 0.
DOUBLE	8 bytes	A double-precision floating-point value with a range of -1.79769313486232E308 to -4.94065645841247E-324 for negative values, 4.94065645841247E-324 to 1.79769313486232E308 for positive values, and 0.
SHORT	2 bytes	A short integer between -32,768 and 32,767.
LONG	4 bytes	A long integer between -2,147,483,648 and 2,147,483,647.
LONGTEXT	1 byte per character	Zero to a maximum of 1.2 gigabytes.
LONGBINARY	As required	Zero to a maximum of approximately 1 gigabyte.  Used for OLE objects.
TEXT	1 byte per character	Zero to 255 characters.
Note   You can also use the VALUE reserved word in SQL statements.  Although it doesn't represent a data type defined by the Jet database engine, VALUE can be considered a valid synonym for the Microsoft Visual Basic Variant data type.


Microsoft Jet Database Engine SQL Reserved Words

See Also	Example	Specifics

The following list includes all words reserved by the Microsoft Jet database engine for use in SQL statements.  The words in the list that aren't in all uppercase letters are also reserved by other applications, including Microsoft Visual Basic.  Consequently, the individual Help topics for these words provide general descriptions that don't focus on SQL usage.

Note   Words followed by an asterisk (*) are reserved by the Jet engine but currently have no meaning in the context of a Jet engine SQL statement (for example, Level and TableID).

A-D

ADD ALL  Alphanumeric [image] See TEXT ALTER  And  ANY  AS  ASC AUTOINCREMENT [image] See COUNTER Avg Between BINARY  BIT  BOOLEAN [image] See BIT BY BYTE  CHAR, CHARACTER [image] See TEXT	COLUMN CONSTRAINT  Count COUNTER CREATE  CURRENCY  DATABASE DATE [image] See DATETIME DATETIME  DELETE DESC DISALLOW DISTINCT  DISTINCTROW  DOUBLE   DROP
E-K

Eqv  EXISTS FLOAT, FLOAT8 [image] See DOUBLE FLOAT4 [image] See SINGLE FOREIGN FROM  GENERAL [image] See LONGBINARY GROUP  HAVING  IEEEDOUBLE [image] See DOUBLE IEEESINGLE [image] See SINGLE IGNORE	Imp  IN  INDEX  INNER  INSERT INT, INTEGER, INTEGER4 [image] See LONG INTEGER1 [image] See BYTE INTEGER2 [image] See SHORT INTO Is JOIN KEY
L-R

LEFT Level* Like LOGICAL, LOGICAL1 [image] See BIT LONG  LONGBINARY  LONGTEXT  Max  MEMO [image] See LONGTEXT Min  Mod  MONEY [image] See CURRENCY Not NULL  NUMBER [image] See DOUBLE NUMERIC [image] See DOUBLE	OLEOBJECT [image] See LONGBINARY ON OPTION Or  ORDER  Outer* OWNERACCESS  PARAMETERS  PERCENT  PIVOT  PRIMARY  PROCEDURE  REAL [image] See SINGLE REFERENCES  RIGHT
S-Z

SELECT  SET  SHORT  SINGLE  SMALLINT [image] See SHORT SOME  StDev StDevP  STRING [image] See TEXT Sum TABLE TableID* TEXT  TIME [image] See DATETIME TIMESTAMP [image] See DATETIME	TOP  TRANSFORM  UNION  UNIQUE  UPDATE  VALUE  VALUES  Var  VARBINARY [image] See BINARY VARCHAR [image] See TEXT VarP  WHERE  WITH  Xor YESNO [image] See BIT


Using Wildcard Characters in String Comparisons

See Also	Example	Specifics

Built-in pattern matching provides a versatile tool for making string comparisons.  The following table shows the wildcard characters you can use with the Like operator and the number of digits or strings they match.

Character(s)  in pattern	Matches in expression
?	Any single character
*	Zero or more characters
#	Any single digit (0 [image] 9)
[charlist]	Any single character in charlist
[!charlist]	Any single character not in charlist
A group of one or more characters (charlist) enclosed in brackets ([ ]) can be used to match any single character in expression and can include almost any characters in the ANSI character set, including digits.  In fact, the special characters opening bracket ([ ), question mark (?), number sign (#), and asterisk (*) can be used to match themselves directly only if enclosed in brackets.  The closing bracket ( ]) can't be used within a group to match itself, but it can be used outside a group as an individual character.

In addition to a simple list of characters enclosed in brackets, charlist can specify a range of characters by using a hyphen (-) to separate the upper and lower bounds of the range.  For example, using [A-Z] in pattern results in a match if the corresponding character position in expression contains any of the uppercase letters in the range A through Z.  Multiple ranges can be included within the brackets without any delimiting.  For example, [a-zA-Z0-9] matches any alphanumeric character.

Other important rules for pattern matching include the following:

An exclamation mark (!) at the beginning of charlist means that a match is made if any character except those in charlist are found in expression.  When used outside brackets, the exclamation mark matches itself.

The hyphen (-) can be used either at the beginning (after an exclamation mark if one is used) or at the end of charlist to match itself.  In any other location, the hyphen is used to identify a range of ANSI characters.

When a range of characters is specified, they must appear in ascending sort order (A-Z or 0-100).  [A-Z] is a valid pattern, but [Z-A] isn't.

The character sequence [ ] is ignored; it's considered to be a zero-length string ("").


ALTER TABLE Statement Example

The SQL statements shown below can be used on tables created with the CREATE TABLE statement.

SQL statement	Description
ALTER TABLE Employees  ADD COLUMN Salary CURRENCY;	Adds a Salary field with a data type of Currency to the Employees table.
ALTER TABLE Employees  DROP COLUMN Salary;	Removes the Salary field from the Employees table.
ALTER TABLE Orders  ADD CONSTRAINT OrdersRelationship  FOREIGN KEY ([Employee ID])  REFERENCES Employees ([Employee ID]);	Adds a foreign key to the Orders table.  The foreign key is based on the Employee ID field and refers to the Employee ID field of the Employees table.  In this example, you don't have to list the Employee ID field after the Employees table in the REFERENCES clause because Employee ID is the primary key of the Employees table.
ALTER TABLE Orders  DROP CONSTRAINT OrdersRelationship;	Removes the foreign key from the Orders table.


CREATE INDEX Statement Example

Generally, you use the CREATE INDEX statement, as shown in these examples, with the Execute method.

SQL statement	Description
CREATE INDEX NewIndex  ON Employees ([Home Phone], Extension);	Creates an index consisting of the fields Home Phone and Extension in the Employees table.
CREATE UNIQUE INDEX MyIndex  ON Employees (SSN)  WITH DISALLOW NULL;	Creates an index on the Employees table using the Social Security Number field.  No two records can have the same data in the SSN field, and no Null values are allowed.
CREATE UNIQUE INDEX MailID  ON MailList ([Client No.])	Creates an index on an attached table.  The table's remote database is unaware of and unaffected by the new index.


CREATE TABLE Statement, CONSTRAINT Clause Example

Generally, you use the CREATE TABLE statement, as shown in the examples below, with the Execute method.

SQL statement	Description
CREATE TABLE [This Table]  ([First Name] TEXT, [Last Name] TEXT);	Creates a new table called This Table with two Text fields.
CREATE TABLE MyTable ([First Name] TEXT, [Last Name] TEXT, [Date of Birth] DATETIME,  CONSTRAINT MyTableConstraint UNIQUE ([First Name], [Last Name], [Date of Birth]));	Creates a new table called MyTable with two Text fields, a Date/Time field, and a unique index made up of all three fields.
CREATE TABLE NewTable  ([First Name] TEXT, [Last Name] TEXT,  SSN INTEGER  CONSTRAINT MyFieldConstraint PRIMARY  KEY)	Creates a new table with two Text fields and an Integer field.  The SSN field is the primary key.


DROP Statement Example

Generally, you use the DROP statement, as shown in the examples below, with the Execute method.

SQL statement	Description
DROP INDEX MyIndex ON Employees;	Deletes MyIndex from the Employees table.
DROP TABLE [This Table];	Deletes This Table from the database.


SELECT Statement, FROM Clause Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT [Last Name], [First Name]  FROM Employees;	Selects the Last Name and First Name fields of all records in the Employees table.
SELECT Employees.*  FROM Employees;	Selects all fields from the Employees table.
SELECT Count([Postal Code]) AS Tally  FROM Customers;	Counts the number of records that have an entry in the Postal Code field and names the returned Field "Tally".
SELECT [Last Name], Salary AS Current, Salary * 1.1 AS Proposed  FROM Employees;	Shows what the salary would be if each employee received a 10 percent raise.  It doesn't change the original salary amounts.
SELECT [Last Name] AS Name, Salary  FROM Employees;	Places the title Name at the top of the Last Name column.  The title Salary is displayed at the top of the Salary column.
SELECT Count(*) AS [Total Employees], Avg(Salary)  AS [Average Salary], Max(Salary) AS [Maximum Salary]  FROM Employees;	Shows the number of employees and the average and maximum salaries.
SELECT [Last Name], 'has a salary of', Salary  FROM Employees;	For each record, shows the Last Name and Salary in the first and last fields.  The string "has a salary of" is returned as the middle field of each Recordset.


IN Clause Example

The following table shows how you can use the IN clause to retrieve data from an external database.  The Customers table is stored in an external database.  The SQL statements shown below must be used as the SQL property of a QueryDef object, or in an SQL expression with the OpenRecordset method.

External database	SQL statement
Microsoft Jet database	SELECT [Customer ID] FROM Customers IN MYDATA.MDB  WHERE [Customer ID] Like "A*"; MYDATA.MDB is the name of the Jet database that contains the Customers table.
dBASE III or IV	SELECT [CustomerID] FROM Customer IN "C:\DBASE\DATA\SALES" "dBASE IV;" WHERE CustomerID Like "A*"; To retrieve data from a dBASE III table, substitute "dBASE III" in place of "dBASE IV;".
dBASE III or IV using DATABASE syntax	SELECT [CustomerID] FROM Customer IN "" [dBASE IV; DATABASE=C:\DBASE\DATA\SALES;]  WHERE CustomerID Like "A*"; To retrieve data from a dBASE III table, substitute "dBASE III" in place of "dBASE IV;".
Paradox 3.x or 4.x	SELECT [CustomerID] FROM Customer IN "C:\PARADOX\DATA\SALES" "Paradox 4.x;" WHERE CustomerID Like "A*"; To retrieve data from a Paradox version 3.x table, substitute "Paradox 3.x;" in place of "Paradox 4.x;".
Paradox 3.x or 4.x using DATABASE syntax	SELECT [CustomerID] FROM Customer IN "" [Paradox 4.x;DATABASE=C:\PARADOX\DATA\SALES;]  WHERE CustomerID Like "A*"; To retrieve data from a Paradox version 3.x table, substitute "Paradox 3.x;" in place of "Paradox 4.x;".
Btrieve	SELECT [CustomerID] FROM Customer IN "C:\BTRIEVE\DATA\SALES\FILE.DDF" "Btrieve;"  WHERE CustomerID Like "A*"; C:\BTRIEVE\DATA\SALES\FILE.DDF is the path and filename of the Btrieve data definition file.
Btrieve	SELECT [CustomerID] FROM Customers IN "" [Btrieve;DATABASE=C:\BTRIEVE\DATA\SALES\FILE.DDF;]  WHERE CustomerID Like "A*"; C:\BTRIEVE\DATA\SALES\FILE.DDF is the path and filename of the Btrieve data definition file.


WHERE Clause Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT [Last Name], [First Name]  FROM Employees  WHERE [Last Name] = 'King';	Selects the Last Name and First Name fields of each record in which the last name is King.
SELECT [Last Name], [First Name]  FROM Employees  WHERE [Last Name] Like 'S*';	Selects the Last Name and First Name fields for employees whose last names begin with the letter S.
SELECT [Last Name], Salary  FROM Employees  WHERE Salary Between 20000 And 30000;	Selects employees whose salaries are between $20,000 and $30,000, inclusive.
SELECT [Last Name], Salary  FROM Employees  WHERE [Last Name] Between 'Lon' And 'Tol';	Selects employees whose last names fall in alphabetic order between Lon and Tol, inclusive.  It doesn't retrieve Tolstoy because Tolstoy follows Tol and therefore is outside the specified range.
SELECT [Order ID], [Order Date]  FROM Orders  WHERE [Order Date] Between #1-1-94# And #6-30-94#;	Selects orders placed during the first half of 1994.
SELECT [Last Name], [First Name], City  FROM Employees  WHERE City In ('Interlaken', 'New York', 'Frankfurt');	Selects employees who live in Interlaken, New York, or Frankfurt.


GROUP BY Clause Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT Department, Count([Department]) AS Tally  FROM Employees  GROUP BY Department;	Creates a list of unique department names and the number of employees in each of those departments.
SELECT Title, Count([Title]) AS Tally  FROM Employees  WHERE Department = 'Sales'  GROUP BY Title;	For each unique job title, calculates the number of Sales department employees who have that title.
SELECT Item, Sum(Units) AS Tally  FROM ItemsInStock  GROUP BY Item, Color;	Calculates the number of items in stock for each combination of item number and color.


HAVING Clause Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT Title, Count([Title])  FROM Employees  WHERE Department = 'Production'  GROUP BY Title  HAVING Count(Title) > 50;	Selects the job titles in the Production department assigned to more than 50 employees.
SELECT Department, Count([Department])  FROM Employees  GROUP BY Department  HAVING Count(Department) > 100;	Selects departments with more than 100 employees.


ORDER BY Clause Example

The SQL statements shown below use the ORDER BY clause to sort records alphabetically and then by category.

SQL statement	Description
SELECT [Last Name], [First Name]  FROM Employees  ORDER BY [Last Name] DESC;	Sorts the records by last name in descending order (Z-A).
SELECT [Category ID], [Product Name], [Unit Price]  FROM Products  ORDER BY [Category ID], [Product Name];	Sorts by category ID first, then by product name.


ALL, DISTINCT, DISTINCTROW, TOP Predicates Example

The following examples use two tables, Customers and Orders.

Customers Table

First name	Customer ID

Bob	1

Adam	2

Beverly	3

Bob	4

Orders Table

Customer ID	Order ID

1	1

1	2

2	3

2	4

2	5

4	6

4	7

The SQL statements shown below must be used as the SQL property of a QueryDef object or in a SQL expression with the OpenRecordset method.

SQL statement	Result	Updatable
SELECT ALL [First Name]  FROM Customers INNER JOIN Orders  ON Customers.[Customer ID] = Orders.[Customer ID];	Bob Bob Adam Adam Adam Bob Bob	Yes
SELECT DISTINCT [First Name]  FROM Customers INNER JOIN Orders  ON Customers.[Customer ID] = Orders.[Customer ID];	Bob Adam	No
SELECT DISTINCTROW [First Name]  FROM Customers INNER JOIN Orders  ON Customers.[Customer ID] = Orders.[Customer ID];	Bob Adam Bob	Yes
SELECT TOP 5 [First Name]  FROM Customers INNER JOIN Orders  ON Customers.[Customer ID] = Orders.[Customer ID] ORDER BY Orders.[Order ID]	Bob Bob Adam Adam Adam	Yes


DELETE Statement Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
DELETE * FROM Employees  WHERE Title = 'Trainee';	Deletes all records for employees whose title is Trainee.  When the FROM clause includes only one table, you don't have to list the table name in the DELETE statement.
DELETE Employees.*  FROM Employees INNER JOIN Payroll  ON Employees.[Employee ID] = Payroll.[Employee ID]  WHERE Title = 'Trainee';	Deletes all records for employees whose title is Trainee and who also have a record in the Payroll table.  The Employees and Payroll tables have a one-to-one relationship.


INNER JOIN Operation Example

The SQL statement shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT DISTINCTROW  Sum([Unit Price] * [Quantity]) AS [Sales],  [First Name] & " " & [Last Name] AS Name  FROM Employees INNER JOIN (Orders INNER JOIN [Order Details]  ON Orders.[Order ID] = [Order Details].[Order ID])  ON Employees.[Employee ID] = Orders.[Employee ID]  GROUP BY [First Name] & " " & [Last Name];	Creates two equi-joins: one between the Order Details and Orders tables and another between the Orders and Employees tables.  This is necessary because the Employees table doesn't contain sales data, and the Order Details table doesn't contain employee data.  The query produces a list of employees and their total sales.


INSERT INTO Statement Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
INSERT INTO Customers  SELECT [New Customers].*  FROM [New Customers];	Selects all records in the New Customers table and adds them to the Customers table.
INSERT INTO Employees ([First Name], [Last Name], Title)  VALUES ("Harry", "Washington", "Trainee");	Creates a new record in the Employees table.
INSERT INTO Employees  SELECT Trainees.*  FROM Trainees  WHERE [Hire Date] < Now() - 30;	Selects all trainees who were hired more than 30 days ago and adds their records to the Employees table.


LEFT JOIN, RIGHT JOIN Operations Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT [Department Name],  [First Name] & " " & [Last Name] AS Name  FROM Departments LEFT JOIN Employees  ON Departments.[Department ID] = Employees.[Department ID]  ORDER BY [Department Name];	Selects all departments, including those without employees.
SELECT [Last Name] & ", " & [First Name] AS Name,  [Department Name]  FROM Departments RIGHT JOIN Employees  ON Departments.[Department ID] = Employees.[Department ID]  ORDER BY [Last Name] & ", " & [First Name];	Selects all employees, including those not assigned to a department.


PARAMETERS Declaration Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
PARAMETERS [Enter a Last Name:] Text;  SELECT *  FROM Employees  WHERE [Last Name] =  [Enter a Last Name:];	Requires you to provide an employee's last name and then uses that entry as the criteria for the query.
PARAMETERS [Enter a Category ID:] Value;  SELECT DISTINCTROW  [Category ID], [Product Name],  Count([Order Details].[Order ID]) AS Tally  FROM Products INNER JOIN [Order Details]  ON Products.[Product ID] = [Order Details].[Product ID]  GROUP BY [Category ID], [Product Name]  HAVING [Category ID] = [Enter a Category ID:];	Requires you to provide a category ID and then uses that entry as the criteria for the query.


PROCEDURE Clause Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
PROCEDURE Category_List;  SELECT DISTINCTROW  [Category Name], [Category ID]  FROM Categories  ORDER BY [Category Name];	Names the query Category_List.
PROCEDURE Summary  [Beginning Date] DATETIME,  [Ending Date] DATETIME;  SELECT DISTINCTROW  [Shipped Date], [Order ID], [Employee ID],  Format([Shipped Date], "yyyy") AS Year  FROM Orders  WHERE [Shipped Date]  Between [Beginning Date] And [Ending Date];	Names the query Summary and includes two parameters.  The PROCEDURE clause is changed to the following PARAMETERS declaration: PARAMETERS [Beginning Date] DateTime, [Ending Date] DateTime;


SELECT...INTO Statement Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT Employees.* INTO [Emp Backup]  FROM Employees;	Selects all records in the Employees table and copies them into a new table named Emp Backup.
SELECT Employees.[First Name], [Last Name]  INTO Trainees  FROM Employees  WHERE Title = 'Trainee';	Creates a new table called Trainees that contains only employee records that have the title Trainee.
SELECT Employees.* INTO Employees IN "BACKUP.MDB"  FROM Employees;	Makes a copy of the Employees table and places the new table in the BACKUP database.
SELECT Employees.*, Salary INTO Trainees  FROM Employees INNER JOIN Payroll  ON Employees.[Employee ID] = Payroll.[Employee ID]  WHERE Title = 'Trainee';	Creates a new table that contains employee and payroll data for all trainees.  The Employees and Payroll tables have a one-to-one relationship.  The new table contains all of the data from the Employees table plus the Salary field from the Payroll table.


TRANSFORM Statement Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
PARAMETERS [Sales for which year?] LONG;  TRANSFORM Sum([Order Details].Quantity * ([Order Details]. [Unit Price] - ([Order Details].Discount / 100) * [Order Details]. [Unit Price])) AS Sales  SELECT [Product Name]  FROM Orders INNER JOIN (Products INNER JOIN [Order Details]  ON Products.[Product ID] = [Order Details].[Product ID]) ON Orders.[Order ID] = [Order Details].[Order ID]  WHERE DatePart("yyyy", [Order Date]) = [Sales for which year?]  GROUP BY [Product Name]  ORDER BY [Product Name]  PIVOT DatePart("m", [Order Date]);	Creates a crosstab query that shows product sales by month for a user-specified year.  The months are returned from left to right (pivoted) as columns, and the product names are returned from top to bottom as rows.
PARAMETERS [Sales for which year?] LONG;  TRANSFORM Sum([Order Details].Quantity * ([Order Details]. [Unit Price] - ([Order Details].Discount / 100) * [Order Details]. [Unit Price])) AS Sales  SELECT [Company Name]  FROM Orders INNER JOIN  ((Suppliers INNER JOIN Products ON Suppliers.[Supplier ID] = Products.[Supplier ID])  INNER JOIN [Order Details] ON  Products.[Product ID] = [Order Details].[Product ID])  ON Orders.[Order ID] = [Order Details].[Order ID]  WHERE DatePart("yyyy", [Order Date]) = [Sales for which year?]  GROUP BY [Company Name]  ORDER BY [Company Name]  PIVOT "Qtr " & DatePart("q", [Order Date])  In ('Qtr 1', 'Qtr 2', 'Qtr 3', 'Qtr 4');	Creates a crosstab query that returns product sales by quarter for each supplier for a user-specified year.  The quarters are returned from left to right (pivoted) as columns, and the supplier names are returned from top to bottom as rows.


UPDATE Statement Example

The SQL statements shown below should be used with the Execute method.

SQL statement	Description
UPDATE Employees  SET [Reports To] = 5  WHERE [Reports To] = 2;	Changes values in the Reports To field to 5 for all employee records that currently have Reports To values of 2.
UPDATE Products  SET [Unit Price] = [Unit Price] * 1.1  WHERE [Supplier ID] = 8  AND Discontinued = No;	Increases the Unit Price for all nondiscontinued products from supplier 8 by 10 percent.
UPDATE Suppliers INNER JOIN Products  ON Suppliers.[Supplier ID] = Products.[Supplier ID]  SET [Unit Price] = [Unit Price] * .95  WHERE [Company Name] = 'Tokyo Traders'  AND Discontinued = No;	Reduces the Unit Price for all nondiscontinued products supplied by Tokyo Traders by 5 percent.  The Products and Suppliers tables have a many-to-one relationship.


UNION Operation Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT [Company Name], City  FROM Suppliers  WHERE Country = "Brazil"  UNION SELECT [Company Name], City  FROM Customers  WHERE Country = "Brazil";	Retrieves the names and cities of all suppliers and customers in Brazil.
SELECT [Company Name], City  FROM Suppliers  WHERE Country = "Brazil"  UNION SELECT [Company Name], City  FROM Customers  WHERE Country = "Brazil";  ORDER BY City;	Retrieves the names and cities of all suppliers and customers located in Brazil, arranged by city name.
SELECT [Company Name], City  FROM Suppliers  WHERE Country = "Brazil"  UNION SELECT [Company Name], City  FROM Customers  WHERE Country = "Brazil"  UNION SELECT [Last Name], City  FROM Employees  WHERE Region = "South America"	Retrieves the names and cities of all suppliers and customers in Brazil and the last names and cities of all employees in South America.
TABLE [Customer List]  UNION  TABLE [Supplier List]	Retrieves the names and IDs of all suppliers and customers.


SQL Subqueries Example

The SQL statements shown below must be used as the SQL property of a QueryDef object or in an SQL expression with the OpenRecordset method.

SQL statement	Description
SELECT [Last Name], [First Name], Title, Salary  FROM Employees  WHERE Title LIKE "*Sales Rep*" AND Salary > ALL  (SELECT Salary FROM Employees  WHERE (Title LIKE "*Manager*") OR (Title LIKE "*Director*"));	Lists the name, title, and salary of every sales representative whose salary is higher than that of all managers and directors.
SELECT DISTINCTROW [Product Name], [Unit Price]  FROM Products WHERE [Unit Price] =  (SELECT [Unit Price] FROM [Products]  WHERE [Product Name] = "Aniseed Syrup");	Lists the name and unit price of every product whose unit price is the same as that of Aniseed Syrup.
SELECT DISTINCTROW [Contact Name], [Company Name], [Contact Title], Phone  FROM Customers WHERE [Customer ID] IN  (SELECT DISTINCTROW [Customer ID]  FROM Orders WHERE [Order Date] BETWEEN #04/1/94# AND #07/1/94#);	Lists the company and contact of every customer who placed an order in the second quarter of 1994.
SELECT [Last Name], [First Name], Title, Salary  FROM Employees T1  WHERE Salary >=  (SELECT AVG(Salary)  FROM Employees  WHERE Employees.Title = T1.Title)  ORDER BY Title;	Lists employees whose salary is higher than the average salary for all employees.
SELECT [First Name], [Last Name]  FROM Employees AS E  WHERE EXISTS  (SELECT *  FROM Orders AS O  WHERE O.[Employee ID] = E.[Employee ID]);	Selects the name of every employee who has booked at least one order.  This could also be done with an INNER JOIN.


Avg Function Example

This example uses the Orders table to calculate the average freight charges for orders with freight charges over $100.

SELECT Avg([Freight])
AS [Average Freight]
FROM Orders WHERE [Freight] > 100;


Count Function Example

This example uses the Orders table to calculate the number of orders shipped to the United Kingdom.  You can use this expression in the SQL property of a QueryDef object or when creating a Recordset based on an SQL query.

SELECT Count([Ship Country])
AS [UK Orders] FROM Orders WHERE [Ship Country] = 'UK';


First, Last Functions Example

This example uses the Orders table to return the values from the Shipped Date field of the first and last records for orders shipped to the United Kingdom.  You can also use this expression in the SQL property of a QueryDef object or when creating a Recordset based on an SQL query.

SELECT First([Shipped Date])
AS [First Order],
Last([Shipped Date]) AS [Last Order]
FROM Orders WHERE [Ship Country] = 'UK';


Min, Max Functions Example

This example uses the Orders table to return the lowest and highest freight charges for orders shipped to the United Kingdom.  You can also use this expression in the SQL property of a QueryDef object or when creating a Recordset object based on an SQL query.

SELECT Min([Freight])
AS [Low Freight],
Max([Freight]) AS [High Freight]
FROM Orders WHERE [Ship Country] = 'UK';


StDev, StDevP Functions Example

This example uses the Orders table to estimate the standard deviation of the freight charges for orders shipped to the United Kingdom.

SELECT StDev([Freight])
AS [Freight Dev]
FROM Orders WHERE [Ship Country] = 'UK';

SELECT StDevP([Freight])
AS [Freight DevP]
FROM Orders WHERE [Ship Country] = 'UK';


Sum Function Example

This example uses the Orders table to calculate the total sales for orders shipped to the United Kingdom.

SELECT Sum([Unit Price]*[Quantity]) AS [Total UK Sales]
FROM Orders INNER JOIN [Order Details]
& " 	ON Orders.[Order ID] = [Order Details].[Order ID]
WHERE ([Ship Country] = 'UK');


Var, VarP Functions Example

This example uses the Orders table to estimate the variance of freight costs for orders shipped to the United Kingdom.

SELECT Var([Freight])
AS [UK Freight Variance] FROM Orders
WHERE [Ship Country] = 'UK';

SELECT VarP([Freight])
AS [UK Freight VarianceP]
FROM Orders WHERE [Ship Country] = 'UK';


Like Operator Example

This example can be used in an SQL expression in the SQL argument of a query or in the Filter property of a Recordset object.  It returns a list of customers whose names begin with the letter A through D, in alphabetic order.

Like "[A-D]*"

The following example uses the Like operator to compare two strings.

Result = "aa" Like "a[*]a"

The following table shows how you can use Like to test expressions for different patterns.

Kind of match	Pattern	Match (returns True)	No match (returns False)
Multiple characters	"a*a"	"aa", "aBa", "aBBBa"	"aBC"
	"*ab*"	"abc", "AABB", "Xab"	"aZb", "bac"
Special character	"a[*]a"	"a*a"	"aaa"
Multiple characters	"ab*"	"abcdefg", "abc"	"cab", "aab"
Single character	"a?a"	"aaa", "a3a", "aBa"	"aBBBa"
Single digit	"a#a"	"a0a", "a1a", "a2a"	"aaa", "a10a"
Range of characters	"[a-z]"	"f", "p", "j"	"2", "&"
Outside a range	"[!a-z]"	"9", "&", "%"	"b", "a"
Not a digit	"[!0-9]"	"A", "a", "&", "~"	"0", "1", "9"
Combined	"a[!b-m]#"	"An9", "az0", "a99"	"abc", "aj0"


AddNew Method

See Also	Example	Applies to	Specifics

Creates a new record for a table-type or dynaset-type Recordset object.  The AddNew method can also be used with the outdated Dynaset and Table objects.

Syntax

object.AddNew

The object placeholder represents the name of an open table-type or dynaset-type Recordset object to which you want to add a new record.

Remarks

The AddNew method creates a new record you can edit and add to the Recordset object named by object.  This method sets the fields to Null (the default values specified for a table-type Recordset) or default values, if any.

After you modify the new record, use the Update method to save the changes and add the record to the recordset.  No changes are made to the database until you use the Update method.

Caution   If you edit a record and then perform any operation that moves to another record without using Update, your changes are lost without warning.  In addition, if you close the object or end the procedure which declares the object or its Database object, the new record and the changes made to it are discarded without warning.

When you use AddNew and the Microsoft Jet database engine has to create a new 2K page to hold the current record, page locking is pessimistic.  If the new record fits in an existing page, page locking is optimistic.

If you add a record to a table using an action query, the record won't be included in any existing dynaset-type Recordset object based on that table as long as the object is fully populated.  If you haven't moved to the last record of your dynaset, records added to base tables may be included if they would be positioned beyond the current record.

If you add a record to a dynaset using the AddNew method on the dynaset, however, the record is visible in the dynaset and included in the underlying table where it becomes visible to any new Recordset objects.

The position of the new record depends on the type of Recordset:

In a dynaset-type Recordset object, records are inserted at the end of the recordset, regardless of any sorting or ordering rules that may have been in effect when the recordset was opened.

In a table-type Recordset object whose Index property has been set, records are returned in their proper place in the sort order.  If the Index property hasn't been set, new records are returned at the end of the recordset.

The record that was current before you used AddNew remains current.  If you want to make the new record current, you can set the Bookmark property to the bookmark identified by the LastModified property setting.


Append Method

See Also	Example	Applies to	Specifics

Adds a new data access object to a collection.

Syntax

collection.Append object

The Append method syntax has these parts:

Part	Description

collection	Any collection that can accept new objects (for limitations, see the following table).

object	A variable of an object data type identifying the object being appended, which must be of the same type as the elements of collection.

Remarks

Uses of the Append method include adding a new table to a database, adding a field to a table, and adding a field to an index.

The appended object becomes a persistent object, stored on disk, until you delete it using the Delete method.  If the collection is a Workspaces collection (which is stored only in memory), the object is active until you remove it using the Close method.

The addition of a new object occurs immediately, but you should use the Refresh method on any other collections that may be affected by changes to the database structure.

If the object being appended isn't complete (such as when you haven't appended any Field objects to a Fields collection before it's appended to an Indexes collection) or if the properties set in one or more subordinate objects are incorrect, the Append method triggers a trappable error.  For example, if you specify an invalid field type and then try to append the Field object to the Fields collection in a TableDef object, the Append method triggers a trappable error.

The following table shows some limitations on the use of the Append method.  The object in the first column is an object containing the collection in the second column.  The third column indicates when, if ever, you can append an object to that collection (for example, you can never append a Container object to the Containers collection of a Database object).

Object	Collection	When can use Append
Workspace	Databases	Never; use the OpenDatabase method instead
Database	Containers	Never
Database	Recordsets	Never; use the OpenRecordset method instead
Container	Documents	Never
Index	Fields	When the Index object is a new, unappended object
QueryDef	Fields	Never
QueryDef	Parameters	Never
Recordset	Fields	Never
Relation	Fields	Never
TableDef	Fields	When the Updatable property of the TableDef is set to True
TableDef	Indexes	When the Updatable property of the TableDef is set to True
Database, Field, Index, QueryDef, TableDef	Properties	When the Database, Field, Index, QueryDef, or TableDef is persistent


AppendChunk Method

See Also	Example	Applies to	Specifics

Appends data from a string expression to a Memo or OLE Object Field object in the Fields collection of a Recordset object.

Syntax

recordset ! field.AppendChunk source

The AppendChunk method syntax has these parts:

Part	Description

recordset	A variable of an object data type that refers to the Recordset object containing the Fields collection.

field	The name of a Field object whose Type property is set to dbMemo (Memo), dbLongBinary (OLE Object), or the equivalent.

source	A string expression or variable containing the data you want to append to the Field object specified by field.

Remarks

You can use the AppendChunk and GetChunk methods to access data in an OLE Object field larger than 64K (the size limit for String data types).

You can also use these methods to conserve string space when you work with Memo fields, which are limited to 1.2GB.  Certain operations (copying, for example) involve temporary strings.  If string space is limited, you may need to work with chunks of a Memo field instead of the entire field.

If you want to clear the contents of a field, set it to a zero-length string ("").  The following example shows how you can clear a field named Notes:

MyRecordset!Notes = ""

If there is no current record when you use AppendChunk, an error occurs.

Note   The initial AppendChunk (after the first Edit method), even if the record already contains data, will simply place the data in the field as the only data.  Subsequent AppendChunk calls within a single Edit session will then add to the data.


BeginTrans, CommitTrans, Rollback Methods

See Also	Example	Applies to	Specifics

The transaction methods manage transaction processing during a session defined by a Workspace object as follows:

BeginTrans begins a new transaction.

CommitTrans ends the current transaction and saves the changes.

Rollback ends the current transaction and restores the databases in the Workspace object to the state they were in when the current transaction began.

Syntax

workspace.BeginTrans | CommitTrans | Rollback

database.BeginTrans | CommitTrans | Rollback

The transaction methods have these parts:

Part	Description

workspace	A variable of an object data type identifying the Workspace.

database	A variable of an object data type identifying the Database.

Remarks

You use these methods with a Workspace or Database object when you want to treat a series of changes made to the databases in a session as one unit.

Note   All of the transaction methods apply to the Workspace specified.  If you use the methods with a Database object, the method applies to the Database object's Workspace.  If you use the transaction statements, the default Workspace is used; however, this technique is discouraged.

Typically, you use transactions to maintain the integrity of your data when you must update records in two or more tables and ensure that changes made are completed (committed) in all tables or none at all (rolled back).  For example, if you transfer money from one account to another, you might subtract an amount from one and add the amount to another.  If either update fails, the accounts no longer balance.  Use the BeginTrans method before updating the first record, and then, if any subsequent update fails, you can use the Rollback method to undo all of the updates.  Use the CommitTrans method after you successfully update the last record.

Caution   Within one Workspace object, transactions are always global to the Workspace and aren't limited to only one database or recordset.  If you perform operations on more than one database or recordset within a Workspace transaction, the Rollback method restores all operations on those databases and recordsets.

Once you use CommitTrans, you can't undo changes made during that transaction unless the transaction is nested within another transaction that is itself rolled back.  You can have up to five levels of transactions open at once in a single Workspace object by using multiple, nested combinations of BeginTrans and CommitTrans or Rollback.  If you nest transactions, you must save or roll back the current transaction before you can save or roll back a transaction at a higher level of nesting.  If you want to have simultaneous transactions with overlapping, non-nested scopes, you can create additional Workspace objects to contain the concurrent transactions.

If you close a Workspace object without saving or rolling back any pending transactions, the transactions are automatically rolled back.

If you use the CommitTrans or Rollback methods without first using the BeginTrans method, an error occurs.

Some databases may not support transactions, in which case the Transactions property of the Database object or Recordset object is False.  To make sure that the database supports transactions, check the value of the Transactions property of the Database object before using the BeginTrans method.  If you are using a Recordset object based on more than one database, check the Transactions property of the Recordset object.  If a recordset is based entirely on Microsoft Jet database engine tables, its Transactions property is True (-1), and you can use transactions.  Dynaset-type Recordset objects based on tables created by other database products, however, may not support transactions.  For example, you can't use transactions in a Recordset based on a Paradox table.  In this case, the Transactions property is False (0).  If the Database or Recordset doesn't support transactions, the methods are ignored and no error occurs.

 When using external ODBC SQL databases, you can't nest transactions.

Tip   In addition to performing transactions to maintain data integrity, you can often improve the performance of your application by breaking operations that require disk access on your database into transaction blocks.  This ensures buffering of your operations and may greatly reduce the number of times a disk is accessed.

Note   When you begin a transaction, the Jet database engine records its operations in a file kept in the directory specified by the TEMP environment variable on the workstation.  If the transaction log file exhausts the available storage on your TEMP drive, the Jet database engine will trigger a trappable error (2004).  At this point, if you use a CommitTrans, an indeterminate number of operations are committed but the remaining uncompleted operations are lost, and the operation has to be restarted.  Using a Rollback method releases the transaction log and rolls back all operations in the transaction.


CancelUpdate Method

See Also	Example	Applies to	Specifics

Cancels any pending updates for the Recordset object represented by the object placeholder.

Syntax

object.CancelUpdate

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The CancelUpdate method cancels any pending updates due to an Edit or AddNew operation.  For example, if a user invokes the Edit or AddNew method and hasn't yet invoked the Update method, CancelUpdate cancels any changes made after Edit or AddNew was invoked.

Note   Using the CancelUpdate method has the same effect as moving to another record without using the Update method except that the current record doesn't change, and various properties, such as BOF and EOF, aren't updated.

If there is no Edit or AddNew operation pending, CancelUpdate triggers a trappable error.  Use the EditMode property to determine if there is a pending operation that can be canceled.


Clone Method

See Also	Example	Applies to	Specifics

Creates a duplicate Recordset object that refers to the original object.

Syntax

Set duplicate = original.Clone( )

The Clone method syntax has these parts:

Part	Description

duplicate	A variable of an object data type identifying the duplicate Recordset object you're creating.

original	A variable of an object data type identifying the Recordset object you want to duplicate.

Remarks

Use the Clone method to create multiple, duplicate Recordset objects).  Each recordset can have its own current record.  Using Clone by itself doesn't change the data in the objects or in their underlying structures.  Using the Clone method, you can share bookmarks between two or more recordsets because their bookmarks are interchangeable.

You could use Clone when you want to perform an operation on a recordset that requires multiple current records.  This is faster and more efficient than creating a second recordset.

A recordset you create with Clone initially lacks a current record.  To make a record current before you use the recordset object specified by duplicate, you must set the Bookmark property or use one of the Move methods, one of the Find methods (for dynaset- and snapshot-type Recordset objects only), or the Seek method (for table-type Recordset objects only).

Cloning a recordset that resulted from running a QueryDef object doesn't run the query again.

Using the Close method on either the original or duplicate object doesn't affect the other object.

Note   You can't use this method with forward-scrolling snapshots (snapshot-type Recordset objects that have the dbForwardOnly option set).


Close Method

See Also	Example	Applies to	Specifics

Closes an open data access object

Syntax

object.Close

The object placeholder represents the name of an open Database, QueryDef, Recordset, or Workspace object.

Remarks

Closing an open object removes it from the collection to which it's appended.  Any attempt to close the default workspace is ignored.

To remove objects from collections other than the Databases, Recordsets, QueryDefs, and Workspaces collections, use the Delete method on those collections.

Caution   Use the Update method (if there are pending edits) and the Close method on all open recordset objects before you close a database.  If you exit a procedure that declares recordset or Database objects, the database is closed, any unsaved changes are lost, all pending transactions are rolled back, and any pending edits to your data are lost.

If you try to close a Database object while any recordset objects are open, or if you try to close a Workspace object while any Database objects belonging to that specific Workspace are open, those Recordset objects will be closed and any pending updates or edits will be rolled back.

If you try to close a Workspace object while any Database objects belonging to it are open, the operation closes all Database objects belonging to that specific Workspace object which may result in unclosed Recordset objects being closed.

If the Database object is defined outside the scope of the procedure, and you exit the procedure without closing it, the Database object will remain open until explicitly closed or the module in which it is defined is out of scope.

If the Database, Recordset, QueryDef, or Workspace object named by object is already closed when you use Close, a trappable error occurs.

Using the Close method on either an original object or a duplicate object made with the Clone method doesn't affect either object.


CompactDatabase Method

See Also	Example	Applies to	Specifics

Copies, compacts, and gives you the option of changing the version, collating order, and encryption of a closed database.

Syntax

DBEngine.CompactDatabase olddatabase, newdatabase [, locale [, options]]

The CompactDatabase method syntax has these parts:

Part	Description

olddatabase	A string expression that is the name of an existing, closed database.  It can be a full path and filename, such as "C:\MYDB.MDB".  If the filename has an extension, you must specify it.  If your network supports it, you can also specify a network path, such as "\\MYSERVER\MYSHARE\MYDIR\MYDB.MDB".

newdatabase	A string expression that is the full path of the compacted database that you're creating.  You can also specify a network path as with olddatabase.  You can't use the newdatabase argument to specify the same database file as olddatabase.

locale	A string expression used to specify collating order for creating newdatabase, as specified in Settings.  If you omit this argument, the locale of newdatabase is the same as olddatabase.

options	An integer that indicates one or more options, as specified in Settings.  You can combine options by summing the corresponding constants.

Settings

You can use one of the following constants for the locale argument to specify the CollatingOrder property of text for string comparisons:

Constant	Collating order

dbLangGeneral	English, German, French, Portuguese, Italian, and Modern Spanish

dbLangArabic	Arabic

dbLangCzech	Czech

dbLangCyrillic	Russian

dbLangDutch	Dutch

dbLangGreek	Greek

dbLangHebrew	Hebrew

dbLangHungarian	Hungarian

dbLangIcelandic	Icelandic

dbLangNordic	Nordic languages (Microsoft Jet database engine version 1.0 only)

dbLangNorwdan	Norwegian and Danish

dbLangPolish	Polish

dbLangSwedfin	Swedish and Finnish

dbLangSpanish	Traditional Spanish

dbLangTurkish	Turkish

You can use one of the following constants in the options argument to specify whether to encrypt or to decrypt the database as it's compacted:

Constant	Description

dbEncrypt	Encrypt the database while compacting.

dbDecrypt	Decrypt the database while compacting.

If you omit an encryption constant or if you include both dbDecrypt and dbEncrypt, newdatabase will have the same encryption as olddatabase.

You can use one of the following constants in the options argument to specify the version of the data format for the compacted database.  This constant affects only the version of the data format of newdatabase and doesn't affect the version of any Microsoft Access [image] defined objects, such as forms and reports.

Constant	Description

dbVersion10	Create a database that uses the Microsoft Jet database engine version 1.0 while compacting.

dbVersion11	Create a database that uses the Microsoft Jet database engine version 1.1 while compacting.

dbVersion20	Create a database that uses the Microsoft Jet database engine version 2.0 while compacting.

You can specify only one version constant.  If you omit a version constant, newdatabase will have the same version as olddatabase.  You can compact newdatabase only to a version that is the same or later than that of olddatabase.

Remarks

As you change data in a database, the database file can become fragmented and use more disk space than necessary.  Periodically, you can compact your database to defragment the database file.  The compacted database is usually smaller.  You can also choose to change the collating order, the encryption, or the version of the data format while you copy and compact the database.

Warning   The CompactDatabase method won't correctly convert a complete Microsoft Access database from one version to another.  Only the data format is converted.  Microsoft Access [image] defined objects, such as forms and reports, aren't converted.

Use the Convert Database command on the File menu of the Microsoft Access startup window to convert Microsoft Access databases from an earlier version to the current version.

The CompactDatabase method copies all the data and the security permissions settings from the database specified by olddatabase to the database specified by newdatabase.  In the process, the data in the compacted database is organized contiguously to recover disk space.

You must close olddatabase before you compact it.  In a multiuser environment, other users can't have olddatabase open while you're compacting it.  If olddatabase isn't closed or isn't available for exclusive use, an error occurs.

Because CompactDatabase creates a copy of the database, you must have enough disk space for both the original and the duplicate databases.  The compact operation fails if there isn't enough disk space available.  The newdatabase duplicate database doesn't have to be on the same disk as olddatabase.  After successfully compacting a database, you can delete the olddatabase file and rename the compacted newdatabase file to the original filename.


CopyQueryDef Method

See Also	Example	Applies to	Specifics

Returns a QueryDef object which is a copy of the QueryDef used to create the Recordset object represented by the object placeholder.

Syntax

object.CopyQueryDef

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

Creates a new QueryDef that is a duplicate of the QueryDef used to create this Recordset.  If a QueryDef wasn't used to create this Recordset, this method returns a null value.


CreateDatabase Method

See Also	Example	Applies to	Specifics

Creates a new Database object, saves the database on disk and returns an opened Database object.

Syntax

Set database = workspace.CreateDatabase (databasename, locale [, options])

The CreateDatabase method syntax has these parts:

Part	Description

database	A variable of an object data type that represents the Database object you're creating.

workspace	A variable of an object data type that represents the existing Workspace object that will contain the database.  If you omit the workspace part, the default Workspace is used.

databasename	A string expression that is the name of the database file that you're creating.  It can be the full path and filename, such as "C:\MYDB.MDB".  If you don't supply a filename extension, .MDB is appended.  If your network supports it, you can also specify a network path, such as  "\\MYSERVER\MYSHARE\MYDIR\MYDB".  Only .MDB database files can be created using this method.

locale	A string expression used to specify collating order for creating the database.  You must supply this argument or an error will occur.  See the table that lists locale constants later in this topic.

options	An integer that indicates one or more options, as specified in Settings.  You can combine options by summing the corresponding constants.

Note   The outdated CreateDatabase statement is used as a CreateDatabase method on the Workspaces(0) [image] the default Workspace.  Its use is discouraged.

Settings

You can use one of the following constants for the locale argument to specify the CollatingOrder property of text for string comparisons:

Constant	Collating order

dbLangGeneral	English, German, French, Portuguese, Italian, and Modern Spanish

dbLangArabic	Arabic

dbLangCzech	Czech

dbLangCyrillic	Russian

dbLangDutch	Dutch

dbLangGreek	Greek

dbLangHebrew	Hebrew

dbLangHungarian	Hungarian

dbLangIcelandic	Icelandic

dbLangNordic	Nordic languages (Microsoft Jet database engine version 1.0 only)

dbLangNorwdan	Norwegian and Danish

dbLangPolish	Polish

dbLangSwedfin	Swedish and Finnish

dbLangSpanish	Traditional Spanish

dbLangTurkish	Turkish

You can use one or more of the following constants in the options argument to specify which version the data format should have and whether or not to encrypt the database:

Constant	Description

dbEncrypt	Create an encrypted database.

dbVersion10	Create a database that uses the Microsoft Jet database engine version 1.0.

dbVersion11	Create a database that uses the Microsoft Jet database engine version 1.1.

dbVersion20	Create a database that uses the Microsoft Jet database engine version 2.0.

If you omit the encryption constant, an unencrypted database is created.  You can specify only one version constant.  If you omit a version constant, a database that uses the Microsoft Jet database engine version 2.0 is created.

Remarks

Use the CreateDatabase method to create a template for a new database the accesses the Jet engine.  The CreateDatabase method opens this new database and returns the Database object.  You must complete its structure and content using additional data access objects.  If you want to make a partial or complete copy of an existing database, you can use the CompactDatabase method to make a copy that you can customize.


CreateField Method (Data Access)
CreateField Method

See Also	Example	Applies to	Specifics

Creates a new Field object.

Syntax

Set variable = object.CreateField([name[, type [, size]]])

The CreateField method syntax has these parts:

Part	Description

variable	A variable declared as object data type Field.

object	The variable name of the Index, Relation, or TableDef object you want to use to create the new Field object.

name	A String variable that uniquely names the new Field object.  See the Name property for details on valid Field names.

type	An Integer constant that determines the data type of the new Field object.  See the Type property for valid data types.

size	An integer that indicates the maximum size, in bytes, of a Field object that contains text.  See the Size property for valid size values.  This argument is ignored for numeric and fixed-width fields.

Remarks

If you omit one or more of the optional parts when you use CreateField, you can use an appropriate assignment statement to set or reset the corresponding property before you append the new object to a collection.  After you append the new object, you can alter some but not all of its property settings.  See the individual property topics for more details.

Note   The type and size arguments apply only to Field objects in a TableDef object.  These arguments are ignored when a Field object is associated with Index and Relation objects.

If name refers to an object that is already a member of the collection, a trappable error occurs when you use the Append method.

To remove a Field object from a collection, use the Delete method on the collection.  You can't delete a Field object from a TableDef object's Fields collection once an index has been created that references the field.


CreateGroup Method

See Also	Example	Applies to	Specifics

Creates a new Group object.

Syntax

Set variable = object.CreateGroup([name[, pid]])

The CreateGroup method syntax has these parts:

Part	Description

variable	A variable declared as object data type Group.

object	The variable name of the User or Workspace object you want to use to create the new Group object.

name	A String variable that uniquely names the new Group object.  See the Name property for details on valid Group names.

pid	A String variable containing the PID of a group account.  The identifier must contain from 4 to 20 alphanumeric characters.  See the PID property for more information on valid personal identifiers.

Remarks

If you omit one or both of the optional parts when you use CreateGroup, you can use an appropriate assignment statement to set or reset the corresponding property before you append the new object to a collection.  After you append the object, you can alter some but not all of its property settings.  See the individual property topics for more details.

If name refers to an object that is already a member of the collection, a trappable error occurs when you use the Append method.

To remove a Group object from a collection, use the Delete method on the collection.


CreateIndex Method

See Also	Example	Applies to	Specifics

Creates a new Index object.

Syntax

Set variable = tabledef.CreateIndex([name])

The CreateIndex method syntax has these parts:

Part	Description

variable	A variable declared as object data type Index.

tabledef	The variable name of the TableDef object you want to use to create the new Index object.

name	A String variable that uniquely names the new Index object.  See the Name property for details on valid Index names.

Remarks

If you omit the optional name part when you use CreateIndex, you can use an appropriate assignment statement to set or reset the Name property before you append the new object to a collection.  After you append the object, you may or may not be able to set its Name property, depending on the type of object the Indexes collection resides in.  See the Name property topic for more details.

If name refers to an object that is already a member of the collection, a trappable error occurs when you use the Append method.

To remove an Index object from a collection, use the Delete method on the collection.


CreateProperty Method

See Also	Example	Applies to	Specifics

Creates a new user-defined Property object.

Syntax

Set variable = object.CreateProperty([name[, type[, value[, fDDL]]]])

The CreateProperty method syntax has these parts:

Part	Description

variable	A variable declared as object data type Property.

object	The variable name of the Database, Field, Index, QueryDef, or TableDef object you want to use to create the new Property object.

name	A String variable that uniquely names the new Property object.  See the Name property for details on valid Property names.

type	An Integer constant that defines the data type of the new Property object.  See the Type property for valid data types.

value	A Variant variable containing the initial property value.  See the Value property for details.

fDDL	A Boolean variable indicating whether or not the Property is a DDL object.  The default is False.  If the fDDL is True, this Property object can't be changed or deleted unless the user has dbSecWriteDef permission.

Remarks

You can create a user-defined Property object only in a Properties collection that is persistent (that is, already stored on disk).

If you omit one or more of the optional parts when you use CreateProperty, you can use an appropriate assignment statement to set or reset the corresponding property before you append the new object to a collection.  After you append the object, you can alter some but not all of its property settings.  See the individual property topics for more details.

If name refers to an object that is already a member of the collection, a trappable error occurs when you use the Append method.

To remove a user-defined Property object from a collection, use the Delete method on the collection.  You can't delete built-in properties.

Note   If you omit the fDDL part, it defaults to False (non-DDL).  There is no corresponding DDL property exposed, so to change a Property object from DDL to non-DDL, you must delete and re-create the Property.


CreateQueryDef Method

See Also	Example	Applies to	Specifics

Creates a new QueryDef object in a specified database.

Syntax

Set querydef = database.CreateQueryDef([name][, sqltext])

The CreateQueryDef method syntax has these parts:

Part	Description

querydef	A variable of an object data type that represents the QueryDef object you want to create.

database	A variable of an object data type that represents the open Database object that contains the new QueryDef.

name	A string expression that is the name of the new QueryDef.

sqltext	A string expression (a valid SQL statement) that defines the QueryDef.  If you omit this argument, you can define the QueryDef by setting its SQL property before or after you append it to a collection.

Remarks

If you include name but omit sqltext or include both name and sqltext, the QueryDef is automatically saved when you create or change it.

If the object specified by name is already a member of the QueryDefs collection, a trappable error occurs.

You can create a temporary QueryDef by setting the Name property of a newly created QueryDef to a zero-length string ("") or by using a zero-length string for the name argument when you execute the CreateQueryDef method.  You can't append a temporary QueryDef to any collection because a zero-length string isn't a valid name for a permanent QueryDef.  You can set the Name and SQL properties of the newly created QueryDef and subsequently append the QueryDef to the QueryDefs collection where it's stored in the database.  If you provide anything other than a zero-length string for the name when you create a QueryDef, the resulting QueryDef object is automatically appended to the QueryDefs collection.

To remove a QueryDef object from a QueryDefs collection, use the Delete method on the collection.

To run the SQL statement in a QueryDef object, use the Execute method.

Using a QueryDef object is the preferred way to perform SQL pass-through queries with ODBC databases.  See the QueryDef object for more information.


CreateRelation Method

See Also	Example	Applies to	Specifics

Creates a new Relation object.

Syntax

Set variable = database.CreateRelation([name[, table[, foreigntable[, attributes]]]])

The CreateRelation method syntax uses these parts:

Part	Description

variable	A variable declared as object data type Relation.

database	The variable name of the Database object you want to use to create the new Relation object.

name	A String variable that uniquely names the new Relation object.  See the Name property for details on valid Relation names.

table	A String variable that names the primary table in the relation.  If the table doesn't exist before you append the Relation object, a trappable error occurs.

foreigntable	A String variable that names the foreign table in the relation.  If the table doesn't exist before you append the Relation object, a trappable error occurs.

attributes	A Long variable that contains information about the relationship type.  See the Attributes property for details.

Remarks

The Relation object relays information to the Microsoft Jet database engine about the relationship between fields in two TableDef or QueryDef objects.  The Jet engine can provide referential integrity through the Attributes property.

If you omit one or more of the optional parts when you use CreateRelation, you can use an appropriate assignment statement to set or reset the corresponding property before you append the new object to a collection.  After you append the object, none of its property settings can be altered.  See the individual property topics for more details.

Before you can use the Append method on a Relation object, you must append the appropriate Field objects to define the primary and foreign key relationship tables.

If name refers to an object that is already a member of the collection or if the Field object names provided in the subordinate Fields collection are invalid, a trappable error occurs when you use the Append method.

To remove a Relation object from a collection, use the Delete method on the collection.


CreateTableDef Method

See Also	Example	Applies to	Specifics

Creates a new TableDef object.

Syntax

Set variable = database.CreateTableDef([name[, attributes[, source[, connect]]]])

The CreateTableDef method syntax has these parts:

Part	Description

variable	A variable declared as object data type TableDef.

database	The variable name of the Database object you want to use to create the new TableDef object.

name	A String variable that uniquely names the new TableDef object.  See the Name property for details on valid TableDef names.

attributes	A Long variable that indicates one or more characteristics of the new TableDef object.  See the Attributes property for more information.

source	A String variable containing the name of a table in an external database that is the original source of the data.  The source string becomes the SourceTableName property setting of the new TableDef object.

connect	A String variable containing information about the source of an open database, a database used in a pass-through query, or an attached table.  See the Connect property for more information on valid connection strings.

Remarks

If you omit one or more of the optional parts when you use CreateTableDef, you can use an appropriate assignment statement to set or reset the corresponding property before you append the new object to a collection.  After you append the object, you can alter some but not all of its properties.  See the individual property topics for more details.

If name refers to an object that is already a member of the collection or you specify an invalid property in the TableDef or Field object you're appending, a trappable error occurs when you use the Append method.

To remove a TableDef object from a collection, use the Delete method on the collection.


CreateUser Method

See Also	Example	Applies to	Specifics

Creates a new User object.

Syntax

Set variable = object.CreateUser([name[, pid [, password]]])

The CreateUser method syntax has these parts:

Part	Description

variable	A variable declared as object data type User.

object	The variable name of the Group or Workspace object you want to use to create the new User object.

name	A String variable that uniquely names the new User object.  See the Name property for details on valid User names.

pid	A String variable containing the PID of a user account.  The identifier must contain from 4 to 20 alphanumeric characters.  See the PID property for more information on valid personal identifiers.

password	A String variable containing the password for the new User object.  The password can be up to 14 characters long and can include any characters except the ASCII character 0 (null).  See the Password property for more information on valid passwords.

Remarks

If you omit one or more of the optional parts when you use CreateUser, you can use an appropriate assignment statement to set or reset the corresponding property before you append the new object to a collection.  After you append the object, you can alter some but not all of its property settings.  See the individual property topics for more details.

If name refers to an object that is already a member of the collection, a trappable error occurs when you use the Append method.

To remove a User object from a collection, use the Delete method on the collection.


CreateWorkspace Method

See Also	Example	Applies to	Specifics

Creates a new Workspace object.

Syntax

Set variable = CreateWorkspace(name, user, password)

The CreateWorkspace method syntax has these parts:

Part	Description

variable	A variable declared as object data type Workspace.

name	A String variable that uniquely names the new Workspace object.  See the Name property for details on valid Workspace names.

user	A String variable that identifies the owner of the new Workspace object.  See the UserName property for more information.

password	A String variable containing the password for the new Workspace object.  The password can be up to 14 characters long and can include any characters except ASCII character 0 (null).  See the Password property for more information on valid passwords.

Remarks

Unlike the other methods you use to create data access objects, CreateWorkspace requires that you provide all of its parts.  In addition, Workspace objects aren't permanent and can't be saved.  Once you create a Workspace object, you can't alter any of its property settings.

You don't have to append the new Workspace object to a collection before you can use it.  You append a newly created Workspace object only if you need to be able to refer to it through the Workspaces collection.

If name refers to an object that is already a member of the Workspaces collection, a trappable error occurs.

Once you use CreateWorkspace to create a new Workspace object, a Workspace session is started, and you can refer to the Workspace object in your application.

To remove a Workspace object from the Workspaces collection, use the Close method on the Workspace object.


Delete Method

See Also	Example	Applies to	Specifics

Recordset objects [image] deletes the current record in an open dynaset-type or table-type Recordset object.

Collections [image] deletes a stored object from a collection.

Syntax

recordset.Delete

collection.Delete objectname

The Delete method syntax has these parts:

Part	Description

recordset	A variable of an object data type identifying an open dynaset-type or table-type Recordset object containing the record you want to delete.

collection	A variable of an object data type identifying a collection.

objectname	A String that is the Name property setting of an object in collection.

Remarks

You can use the Delete method to delete a current record from a recordset, a member from a collection, a stored table from a database, a stored field from a table, and a stored index from a table.

Recordsets:  When you delete records from a recordset, there must be a current record in recordset before you use Delete; otherwise, a trappable error occurs.

In table- and dynaset-type Recordset objects, Delete removes the current record and makes it inaccessible.  Although you can't edit or use the deleted record, it remains current.  Once you move to another record, however, you can't make the deleted record current again.  Subsequent references to a deleted record in a Recordset or Table object are invalid and produce an error.

You can undelete a record if you use transactions and the Rollback method.

If the base table is the primary table in a cascade delete relationship, deleting the current record may also delete one or more records in a foreign table.

Collections:  You can use the Delete method to delete a persistent object.  However, if the collection is a Databases, Recordsets, or Workspaces collection (each of which is stored only in memory), you can remove an open or active object by closing that object using the Close method.

The deletion of a stored object occurs immediately, but you should use the Refresh method on any other collections that may be affected by changes to the database structure.

When you delete a TableDef object from the TableDefs collection, you delete the table definition and the data in the table.

The following table shows some limitations on the use of the Delete method.  The object in the first column contains the collection in the second column.  The third column indicates when, if ever, you can delete an object from that collection (for example, you can never delete a Container object from the Containers collection of a Database object).

Object	Collection	When can use Delete method
DBEngine	Workspaces	Never; use the Close method instead
Workspace	Databases	Never; use the Close method instead
Database	Containers	Never
Database	Recordsets	Never; use the Close method instead
Container	Documents	Never
Index	Fields	On new objects that haven't been appended to the database.
QueryDef	Fields	Never
QueryDef	Parameters	Never
Recordset	Fields	Never
Relation	Fields	On new objects that haven't been appended to the database.
TableDef	Fields	On new objects that haven't been appended to the database or when the Updatable property of the TableDef is set to True
TableDef	Indexes	On new objects that haven't been appended to the database or when the Updatable property of the TableDef is set to True
Database, Field, Index, QueryDef, TableDef	Properties	When the property is user-defined


Edit Method

See Also	Example	Applies to	Specifics

Copies the current record from a dynaset-type or table-type Recordset object to the copy buffer for subsequent editing.

Syntax

recordset.Edit

The recordset placeholder represents the name of an open, updatable Recordset object that contains the record you want to edit.

Remarks

Once you use the Edit method, changes made to the current record's fields are copied to the copy buffer.  After you make the desired changes to the record, use the Update method to save your changes.

Caution   If you edit a record and then perform any operation that moves to another record without first using Update, your changes are lost without warning.  In addition, if you close recordset or end the procedure which declares the recordset or the parent Database object, your edited record is discarded without warning.

When the Recordset object's LockEdits property setting is True (pessimistically locked) in a multiuser environment, the record remains locked from the time Edit is used until the updating is complete.  If the LockEdits property setting is False (optimistically locked), the record is locked and compared with the pre-edited record just before it's updated in the database.  If the record has changed since you used the Edit method, the Update operation fails with a trappable error (3197).

Note   Optimistic locking is always used on external database formats, such as ODBC and installable ISAM.

The current record remains current after you use Edit.

To use Edit, there must be a current record.  If there is no current record or if recordset doesn't refer to an open table-type or dynaset-type Recordset object, an error occurs.

Using Edit produces an error under the following conditions:

There is no current record.

The database or recordset is read-only.

No fields in the record are updatable.

The database or recordset was opened for exclusive use by another user.

Another user has locked the page containing your record.


Execute Method

See Also	Example	Applies to	Specifics

Runs an action query or executes an SQL statement on a specified Database object.

Syntax

database.Execute source[, options]

querydef.Execute [options]

For a Database object, the Execute method syntax has these parts:

Part	Description

database	The name of the Database object on which the query will run.

source	The SQL statement or QueryDef object.

options	An integer that determines the data integrity characteristics of the query.  For constants you can use for this argument, see Settings.

For a QueryDef object, the Execute method syntax has these parts:

Part	Description

querydef	The name of the QueryDef object whose SQL property setting specifies the SQL statement to execute.

options	An integer or constant that determines the data integrity characteristics of the query, as specified in Settings.

Settings

You can use the following constants for the options part:

Constant	Description

dbDenyWrite	Deny write permission to other users.

dbInconsistent	(Default) Inconsistent updates.

dbConsistent	Consistent updates.

dbSQLPassThrough	SQL pass-through.  Causes the SQL statement to be passed to an ODBC  database for processing.

dbFailOnError	Roll back updates if an error occurs.

dbSeeChanges	Generate a run-time error if another user is changing data you are editing.

Remarks

The Execute method is valid only for action queries.  If you use Execute with another type of query, an error occurs.  Because an action query doesn't return any records, Execute doesn't return a recordset.

Tips

Given a syntactically correct SQL statement and proper permissions, the Execute method won't fail [image] even if not a single row can be modified or deleted.  Therefore, always use the dbFailOnError option when using the Execute method to run an update or delete query.  This option generates a trappable error and rolls back all successful changes if any of the records affected are locked and can't be updated or deleted.

For best performance, especially in a multiuser environment, nest the Execute method inside a transaction:  Use the BeginTrans method on the current Workspace object, then use the Execute method, and complete the transaction by using the CommitTrans method on the Workspace.  This saves changes on disk and frees any locks that may have been placed while the query was running.

Use the RecordsAffected property of the Database or Querydef object to determine the number of records affected by the most recent Execute method.  For example, RecordsAffected contains the number of records deleted, updated or inserted when executing an action query.  When you use the Execute method to run a Querydef, the RecordsAffected property of the Querydef object is set to the number of records affected.

If both dbInconsistent and dbConsistent are included or if neither is included, the result is the default.

Using Execute on a query that selects records produces an error.

Like ExecuteSQL, Execute doesn't return a recordset.

The Execute and ExecuteSQL methods are different in the following ways:

ExecuteSQL returns the number of rows affected by the SQL statement, while Execute doesn't return a value.

ExecuteSQL operates only on a remote ODBC database, such as SQL Server.

Execute allows setting of options that affect how the SQL statement is executed.


FieldSize Method

See Also	Example	Applies to	Specifics

Returns the number of bytes in a Memo or an OLE Object Field object in the Fields collection of a Recordset object.

Syntax

varname = recordset ! field.FieldSize( )

The FieldSize method syntax has these parts:

Part	Description

varname	The name of a Long or Variant variable.

recordset	A variable of an object data type that specifies the Recordset object containing the Fields collection.

field	The name of a Field object whose Type property is set to dbMemo (Memo), dbLongBinary (OLE Object), or the equivalent.

Remarks

Because the size of an OLE Object field or Memo field can exceed 64K, you should assign the value returned by FieldSize to a variable large enough to store a Long variable.

You can use FieldSize with the AppendChunk and GetChunk methods to manipulate large fields.

Note   To determine the size of a Field object (except Memo and Long Binary types), use the Size property.


FillCache Method

See Also	Example	Applies to	Specifics

Fills all or a part of a local cache for a Recordset object that contains data from an ODBC data source.  This method has no effect on non-ODBC data sources.

Syntax

recordset.FillCache [rows[, start]]

The FillCache method syntax has these parts:

Part	Description

recordset	A Recordset object created from an ODBC data source, such as a TableDef representing an attached table or a QueryDef object derived from such a TableDef.

rows	An Integer specifying the number of rows to fill in the cache.  If you omit this argument, the value is determined by the CacheSize property setting.

start	A string specifying a bookmark.  The cache is filled starting from the record indicated by this bookmark.  If you omit this argument, the cache is filled starting from the record indicated by the CacheStart property.

Remarks

Caching improves the performance of an application that retrieves, or fetches, data from a remote server.  A cache is space in local memory that holds the data most recently fetched from the server on the assumption that the data will probably be requested again while the application is running.  When data is requested, the Microsoft Jet database engine checks the cache for the data first rather than fetching it from the server, which takes more time.  Data that doesn't come from an ODBC data source isn't saved in the cache.

Rather than waiting for the cache to be filled with records as they are fetched, you can explicitly fill the cache at any time using the FillCache method.  This is a faster way to fill the cache because FillCache fetches several records at once instead of one at a time.  For example, while each screenful of records is being displayed, you can have your application use FillCache to fetch the next screenful of records.

Any ODBC database accessed with Recordset objects can have a local cache.  To create the cache, open a Recordset object from the remote data source, and then set the CacheSize and CacheStart properties of the Recordset.

If rows and start create a range that is partly or wholly outside the range specified by the CacheSize and CacheStart properties, the portion of recordset outside this range is ignored and isn't loaded into the cache.

If FillCache requests more records than remain in the remote data source, only the remaining records are fetched, and no error occurs.

Notes

 	Records fetched from the cache don't reflect changes made concurrently to the source data by other users.

FillCache fetches only records not already cached.  To force an update of all the cached data, set the CacheSize property of the Recordset to 0, set it to the size of the cache you originally requested, and then use FillCache.

If your application uses a FillCache method against a non-ODBC Recordset, your application will generate a trappable error (3219).


FindFirst, FindLast, FindNext, FindPrevious Methods

See Also	Example	Applies to	Specifics

Locates the first, last, next, or previous record in a dynaset- or snapshot-type Recordset object that satisfies the specified criteria and makes that record the current record.

Syntax

recordset.{FindFirst | FindLast | FindNext | FindPrevious} criteria

The Find methods have these parts:

Part	Description

recordset	The name of an existing dynaset- or snapshot-type Recordset object.

criteria	A string expression (like the WHERE clause in an SQL statement without the word WHERE) used to locate the record.

Remarks

If you want to include all the records in your search [image] not just those that meet a specific condition [image] use the Move methods to move from record to record.  To locate a record in a table-type Recordset, use the Seek method.

If a record matching the criteria isn't located, the current record pointer is undetermined, and the NoMatch property is set to True.  If recordset contains more than one record that satisfies the criteria, FindFirst locates the first occurrence, FindNext locates the next occurrence, and so on.

Caution   If you edit the current record, be sure you save the changes using the Update method before you move to another record.  If you move to another record without updating, your changes are lost without warning.

Each of the Find methods begins its search from the location and in the direction specified in the following table:

Find methods	Begin	Search direction
FindFirst	Beginning of recordset	End of recordset
FindLast	End of recordset	Beginning of recordset
FindNext	Current record	End of recordset
FindPrevious	Current record	Beginning of recordset
When you use the FindLast method, the Microsoft Jet database engine fully populates your recordset before beginning the search [image] if this hasn't already been done.

Using one of the Find methods isn't the same as using MoveFirst or MoveNext, however, which simply makes the first or next record current without specifying a condition.  You can follow a Find operation with a Move operation.

Notes

Always check the value of the NoMatch property to determine whether the Find operation has succeeded.  If the search succeeds, NoMatch is set to False.  If it fails, NoMatch is set to True and the current record isn't defined.  In this case, you must position the current record pointer back to a valid record.  For example:

Dim Here as Variant

Here = Rs.Bookmark

Rs.Find "Name = 'Ms. Schmidt' "	' Search for a name in the recordset.

If Rs.NoMatch then 	' Was it found?

Rs.Bookmark = Here	' If not, go back to previously

' current record.

Else

. 	' Match found.

.

.

End If

You can't use these methods with a forward-only scrolling snapshot-type Recordset.

Using the Find methods with ODBC-accessed recordsets can be inefficient.  You may find that rephrasing your SQL to locate a specific record is faster, especially when working with large recordsets.

You should use the U.S. date format (month-day-year) when you search for fields containing dates, even if you're not using the U.S. version of the Jet database engine; otherwise, the data may not be found.  Use the Visual Basic Format function to convert the date.  For example:

MyDs.FindFirst "statdate > #" & Format(mydate, 'm/d/yy' ) & "#"

When working with ODBC databases and large dynasets, you may discover that using the Find methods or using the Sort or Filter properties is slow.  You can improve performance by using SQL queries with customized ORDER BY or WHERE clauses, parameter queries, or QueryDef objects that retrieve specific indexed records.


GetChunk Method

See Also	Example	Applies to	Specifics

Returns all or a portion of the contents of a Memo or an OLE Object Field object in the Fields collection of a Recordset object.

Syntax

stringvar = recordset ! field.GetChunk(offset, numbytes)

The GetChunk method syntax has these parts:

Part	Description

stringvar	The name of a String variable or Variant that receives the data from the Field object named by field.

recordset	A variable of an object data type that specifies the Recordset object containing the Fields collection.

field	The name of a Field object whose Type property is set to dbMemo (Memo), dbLongBinary (OLE Object), or the equivalent.

offset	A numeric expression that is the number of bytes to skip before copying begins.

numbytes	A numeric expression that is the number of bytes you want to return.

Remarks

If offset is 0, GetChunk begins copying from the first byte of the field.

Assign the bytes returned by GetChunk to stringvar.  Because a String variable is limited in size, numbytes can't be greater than approximately 64K.  If the field is greater than 64K, use GetChunk to return a portion at a time.  You can use the AppendChunk method to reassemble the pieces.  If numbytes is greater than 64K, an error occurs even if stringvar is a Variant.

If numbytes is greater than the number of bytes in the field, the actual number of bytes in the field is returned.  After assigning the results of GetChunk to a String variable, you can use the Visual Basic Len function to determine the number of bytes returned.

If the value of offset or numbytes is less than 0, GetChunk uses the two's complement of the value.


GetRows Method

See Also	Example	Applies to	Specifics

Retrieves multiple rows of a Recordset into an array.

Syntax

MyArray = object.GetRows (numrows)

The GetRows Method syntax has the following parts:

MyArray	The name of a Variant type variable to store the returned data

object 	An object expression that evaluates to an object in the Applies To list.

numrows	The number of rows to retrieve.

Remarks

GetRows returns the specified number of rows and all the fields into a variant containing an array.  Subsequent rows contain the data.  If more rows are requested than are available, then only the number available will be returned.  Use Ubound to determine how many rows were actually fetched, as the array will be sized to fit how many rows were returned.  E.g., if you returned the results into a variant called 'a', you could use:

numreturned = ubound(a,2) + 1

to determine how many rows were actually returned.  The "+ 1" is used because the first data returned is in the 0 element of the array.  The number of rows that can be fetched is constrained by available memory and should be chosen to suit your applicationdon't expect to use GetRows to bring your whole table into an array.

Since all fields of the recordset are returned in the array, including long memo and binary fields, you may wish to use a query that restricts the columns returned.

After a call to GetRows, the current record will be positioned at the next unread row.  I.e., GetRows will have the equivalent positioning affect as Move numrows.


Idle Method

See Also	Example	Applies to	Specifics

Suspends data processing, enabling the Microsoft Jet database engine to complete any pending tasks such as memory optimization or page timeouts.

Syntax

DBEngine.Idle [dbFreeLocks]

Remarks

You use the Idle method to provide the database engine with the opportunity to perform background tasks that may not be up-to-date because of intense data processing.  This is often true in multiuser, multitasking environments in which there isn't enough background processing time to keep all records in a recordset current.

Usually, read locks are removed and data in local dynaset-type Recordset objects is updated only when no other actions (including mouse movements) are occurring.  If you periodically use the Idle method, you provide the database engine with time to catch up on background processing tasks by releasing unneeded read locks.  If you specify the dbFreeLocks constant as an argument, processing is delayed until all read locks are released.

This method isn't needed in single-user environments unless multiple instances of an application are running.  The Idle method may increase performance in a multiuser environment because it forces the database engine to flush data to disk, releasing locks on memory.

You can also release read locks by making operations part of a transaction.  For example:

.

MyWorkspace.BeginTrans

Set MyRs = MyDb.OpenRecordset("MyTable")

MyWorkspace.CommitTrans

Do Until MyRs.EOF

.

.

.

MyRs.MoveNext

Loop


Move Method (Data Access)

See Also	Example	Applies to	Specifics

Moves the position of the current record in a Recordset object.

Syntax

recordset.Move rows[, start]

The Move method syntax has these parts:

Part	Description

recordset	The name of the Recordset object whose current record position is being moved.

rows	A signed Long value specifying the number of rows the position will move.  If rows is greater than 0, the position is moved forward (toward the end of the file).  If rows is less than 0, the position is moved backward (toward the beginning of the file).

start	A String value identifying a bookmark.  If start is specified, the move begins relative to this bookmark.  If start is not specified, Move begins from the current record.

Remarks

If using Move would move the position of the current record to a position before the first record, the position is moved to the beginning-of-file (BOF) position.  If the Recordset contains no records and its BOF property is set to True, using this method to move backward produces a trappable run-time error.  If either the BOF or EOF property is True and you attempt to use the Move method without a valid bookmark, a trappable error is triggered.

If using Move would move the position of the current record to a position after the last record, the position is moved to the end-of-file (EOF) position.  If the Recordset is based on a query, then this approach forces the query to be run on the specified number of rows.  If the Recordset contains no records and its EOF property is set to True, then using this method to move forward produces a trappable run-time error.

Notes

When you use Move on a forward-only scrolling snapshot, the rows argument must be a positive integer and bookmarks aren't allowed, so you can move forward only.

To make the first, last, next, or previous record in a Recordset the current record, use the MoveFirst, MoveLast, MoveNext, or MovePrevious method.


MoveFirst, MoveLast, MoveNext, MovePrevious Methods

See Also	Example	Applies to	Specifics

Move to the first, last, next, or previous record in a specified Recordset object and make that record the current record.

Syntax

object.{MoveFirst | MoveLast | MoveNext | MovePrevious}

The object placeholder represents an object expression that evaluates to the name of an open Recordset object.

Remarks

Use the Move methods to move from record to record without applying a condition.  Use the Find methods to locate records in a dynaset- or snapshot-type Recordset object that satisfy a certain condition.  To locate a record in a table-type Recordset object, use the Seek method.

Caution   If you edit the current record, be sure you save the changes using the Update method before you move to another record.  If you move to another record without updating, your changes are lost without warning.

When you open the recordset named by recordset, the first record is current and the BOF property is set to False.  If the recordset contains no records, the BOF property is set to True, and there is no current record.

If the first or last record is already current when you use MoveFirst or MoveLast, the current record doesn't change.

If you use MovePrevious when the first record is current, the BOF property is set to True, and there is no current record.  If you use MovePrevious again, an error occurs; BOF remains True.

If you use MoveNext when the last record is current, the EOF property is set to True, and there is no current record.  If you use MoveNext again, an error occurs; EOF remains True.

If recordset refers to a table-type Recordset or Table object, movement follows the table's current index.  You can set the current index using the Index property.  If you don't set the current index, the order of returned records is undefined.

If you use MoveLast on a Recordset object based on an SQL query or QueryDef, the query is forced to completion and the Recordset object is fully populated.

Notes

You can't use the MoveFirst or MovePrevious method with a forward-only scrolling snapshot.

To move the position of the current record in a Recordset object a specific number of records forward or backward, use the Move method.


NewPassword Method

See Also	Example	Applies to	Specifics

Changes the password of an existing user account.

Syntax

userobject.NewPassword oldpassword, newpassword

The NewPassword method syntax has these parts:

Part	Description

userobject	A variable of an object data type that represents the User object whose Password property you want to change.

oldpassword	A string expression that is the current setting of the Password property of the User object.

newpassword	A string expression that is the new setting of the Password property of the User object.

Remarks

If userobject doesn't refer to an existing User object (an element of a Users collection), an error occurs.  To set a new password, you must either be logged on as the user whose user account you're changing, or you must be a member of the Admins group.

The oldpassword and newpassword strings can be up to 14 characters long and can include any characters except the ASCII character 0 (null).  To clear the password, use a zero-length string ("") for newpassword.

Passwords are case-sensitive.

The Password property of a User object is write-only [image] users can't read the current value.


OpenDatabase Method

See Also	Example	Applies to	Specifics

Opens a specified database in a session and returns a reference to the Database object that represents it.  The open database is automatically added to the Databases collection.

Syntax

Set database = workspace.OpenDatabase(dbname[, exclusive[, read-only[, source]]])

The OpenDatabase method syntax has these parts:

Part	Description

database	A variable of an Database object data type that represents the Database object that you're opening.

workspace	A variable of a Workspace object data type that represents the existing Workspace object that will contain the database.

dbname	A string expression that is the name of an existing database file or registered ODBC data source name.  If the filename has an extension, it's required.  If your network supports it, you can also specify a network path, such as "\\MYSERVER\MYSHARE\MYDIR\MYDB.MDB".

Some considerations apply when using dbname:

  If it refers to a database that is already open for exclusive access by another user, an error occurs.

  If it refers to the current database, refer to Databases(0) instead of using the OpenDatabase method.

  If it doesn't refer to an existing database or valid ODBC data source name, an error occurs.

  If it's a zero-length string ("") and source is "ODBC;", a dialog box listing all registered ODBC data source names is displayed so the user can select a database.

exclusive	A Boolean expression that is True if the database is to be opened for exclusive (nonshared) access and False if the database is to be opened for shared access.  If you omit this argument, the database is opened for shared access.

read-only	A Boolean value that is True if the database is to be opened for read-only access and False if the database is to be opened for read/write access.  If you omit this argument, the database is opened for read/write access.

source	A string expression used for opening the database.  This string constitutes the ODBC connect arguments.  You must supply the exclusive and read-only arguments to supply a source string.  See the Connect Property for syntax.

Remarks

To close a database, and thus remove its Database object from the Databases collection, use the Close method on the object.

For more information about ODBC drivers, such as SQL Server, see the Help file provided with the driver.

Note   The source argument is expressed in two parts, the database type, followed by a semicolon (;) and the optional parameters.  The database type, like "ODBC;" or "FoxPro 2.5" must be provided first.  The optional arguments follow in no particular order [image] separated by semicolons.


OpenRecordset Method

See Also	Example	Applies to	Specifics

Creates a new Recordset object and appends it to the Recordsets collection.

Syntax

Set variable = database.OpenRecordset(source[, type[, options]])

Set variable = object.OpenRecordset([type[, options]])

The OpenRecordset method syntax has these parts:

Part	Description

variable	A variable that has been declared as object data type Recordset.

database	The name of an existing Database object you want to use to create the new Recordset.

object	The name of an existing QueryDef, Recordset, or TableDef object you want to use to create the new Recordset.  This argument can't be the name of a forward-only scrolling snapshot.
If object refers to a dynaset or snapshot-type Recordset object, the type of the new object is the same as that of the Recordset specified by object.  If object refers to a table-type Recordset object, the type of the new object is a dynaset-type Recordset.

source	A String specifying the source of the records for the new Recordset.  The source can be a table name, a query name, or an SQL statement that returns records.  For table-type Recordset objects, the source can only be a table name.

type	If you don't specify a type, OpenRecordset creates a table-type Recordset if possible.  If you specify an attached table or query, OpenRecordset creates a dynaset-type Recordset.  One of the following Integer constants that defines the data type of the new Recordset object:

  dbOpenTable [image] to open a table-type Recordset object.

  dbOpenDynaset [image] to open a dynaset-type Recordset object.

  dbOpenSnapshot [image] to open a snapshot-type Recordset object.

options	Any combination (or none) of the following Integer constants specifying characteristics of the new Recordset, such as restrictions on other users' ability to edit and view it:

  dbAppendOnly [image] You can only append new records (dynaset-type Recordset only).

  dbForwardOnly [image] The Recordset is a forward-only scrolling snapshot. Note that Recordset objects created with this option cannot be cloned and only support the MoveNext method to move through the records.

  dbSeeChanges [image] Generate a run-time error if another user is changing data you are editing.

  dbDenyWrite [image] Other users can't modify or add records.

  dbDenyRead [image] Other users can't view records (table-type Recordset only).

  dbReadOnly [image] You can only view records; other users can modify them.

  dbInconsistent [image] Inconsistent updates are allowed (dynaset-type Recordset only).

  dbConsistent [image] Only consistent updates are allowed (dynaset-type Recordset only).

Note   The constants dbConsistent and dbInconsistnet are mutually exclusive.  You can use one or the other, but not both in a given instance of OpenRecordset.

Remarks

If object refers to a QueryDef, or a dynaset- or snapshot-type Recordset, or if source refers to an SQL statement or a TableDef that represents an attached table, you can't use dbOpenTable for the type argument; if you do, a trappable error occurs.  To determine whether a TableDef object represents an attached table, check its Connect property setting.  If the Connect property hasn't been set, the TableDef doesn't represent an attached table.  If it does, use dbOpenDynaset.

Use the dbSeeChanges flag if you wish to trap changes made by another user or another program on your machine when you're editing or deleting the same record.  For example, if two users start editing the same record, the first user to execute the Update method succeeds.  When the Update method is executed by the second user, a run-time error occurs.  Similarly, if the second user tries to use the Delete method to delete the record, and it has already been changed by the first user, a run-time error also occurs.

Typically, if the user gets this error while updating, your code should refresh the contents of the fields and retrieve the newly modified values.  If the error occurs in the process of deleting, your code could display the new record data to the user and a message indicating that the data has recently changed.  At this point, your code can request a confirmation that the user still wants to delete the record.

Tip   Use the forward-only scrolling option (dbForwardOnly) to improve performance when your application makes a single pass through a Recordset opened from an ODBC data source.

When you close a Recordset using the Close method, it's automatically deleted from the Recordsets collection.


Refresh Method (Data Access)

See Also	Example	Applies to	Specifics

Updates the objects in a collection to reflect the current database.

Syntax

collection.Refresh

Remarks

The Refresh method adjusts the ordinal positions of objects in a collection so they are contiguous and start from 0.  It may change the order of objects within the collection.

The Refresh method can't be used with collections that aren't persistent, such as Databases, Recordsets, or Workspaces.

Note   To determine the position that the Microsoft Jet database engine uses for Field objects in the Fields collection of a QueryDef, Recordset, or TableDef object, use the OrdinalPosition property of each Field object.

Use the Refresh method in multiuser environments in which other users may change the database.  You may also need to use it on any collections that are indirectly affected by changes to the database.  For example, if you change a Users collection, you may need to refresh a Groups collection before using the Groups collection.

Tip   A collection is filled with objects the first time it's referred to and won't automatically reflect subsequent changes made to it by other users.  If it's likely that a collection has been changed by another user, use the Refresh method on the collection immediately before carrying out any task in your application that assumes the presence or absence of a particular object in the collection.  This will ensure that the collection is as up-to-date as possible.


RefreshLink Method

See Also	Example	Applies to	Specifics

Updates the connection information for an attached table.

Syntax

tabledef.RefreshLink

The tabledef placeholder specifies the TableDef object representing the attached table whose connection information you want to update.

Remarks

You change the connection information for an attached table by resetting the Connect property of the corresponding TableDef object and then using the RefreshLink method to update the information.  When you use RefreshLink, the attached table's properties and Relation objects aren't changed.

To force this connection information to exist in all collections associated with the TableDef object that represents the attached table, you must also use the Refresh method on each collection.


RegisterDatabase Method

See Also	Example	Applies to	Specifics

Enters connection information for an ODBC data source in the ODBC.INI file.  The ODBC driver needs connection information when the Microsoft Jet database engine opens the data source during a session.

Syntax

DBEngine.RegisterDatabase dbname, driver, silent, attributes

The RegisterDatabase method syntax has these parts:

Part	Description

dbname	A string expression that is the name used in the OpenDatabase method that refers to a block of descriptive information about the data source.  For example, if the data source is an ODBC remote database, it could be the name of the server.

driver	A string expression that is the name of the ODBC driver.  This isn't the name of the ODBC driver DLL file.  For example, SQL Server is a driver name, but SQLSRVR.DLL is the name of a DLL file.  You must have ODBC and the appropriate driver already installed.

silent	A numeric expression that is True if you don't want to display the ODBC driver dialog boxes that prompt for driver-specific information or False if you do want to display the ODBC driver dialog boxes.  If silent is True, attributes must contain all the necessary driver-specific information or the dialog boxes are displayed anyway.

attributes	A string expression that is a list of keywords to be added to the ODBC.INI file.  The keywords are in a carriage-return-delimited string.

Remarks

If the database is already registered (connection information is already entered) in the ODBC.INI file when you use the RegisterDatabase method, the connection information is updated.

In 32 bit installations, most of the ODBC registration information is maintained in the Windows registration database and not in the ODBC.INI file.

If the RegisterDatabase method fails for any reason, no changes are made to the ODBC.INI file, and an error occurs.

For more information about ODBC drivers such as SQL Server, see the Help file provided with the driver.

You are encouraged to use the Windows Control Panel ODBC setup icon to add new data sources, or to make changes to existing entries.  However, if you choose to use the RegisterDatabase method, you are encouraged to set the silent option to True.


RepairDatabase Method

See Also	Example	Applies to	Specifics

Attempts to repair a corrupted database that accesses the Microsoft Jet database engine.

Syntax

DBEngine.RepairDatabase dbname

The dbname placeholder represents a string expression that is the path and filename for an existing Jet engine database file.  If you omit the path, only the current directory is searched.  If your system supports the uniform naming convention (UNC), you can also specify a network path, such as: "\\MYSERVER\MYSHARE\MYDIR\MYDB.MDB".

Remarks

You must close the database specified by dbname before you repair it.  In a multiuser environment, other users can't have dbname open while you're repairing it.  If dbname isn't closed or isn't available for exclusive use, an error occurs.

This method attempts to repair a database that was marked as possibly corrupt by an incomplete write operation.  This can occur if an application using the Jet engine is closed unexpectedly because of a power outage or computer hardware problem.  The database won't be marked as possibly corrupt if you use the Close method or if you quit your application in a usual way.

The RepairDatabase method also attempts to validate all system tables and all indexes.  Any data that can't be repaired is discarded.  If the database can't be repaired, a trappable error occurs.

When you attempt to open or compact a corrupted database, a trappable error usually occurs.  In some situations, however, a corrupted database may not be detected, and no error occurs.  It's a good idea to provide your users with a way to use the RepairDatabase method in your application if their database behaves unpredictably.

Some types of databases can become corrupted if a user ends an application without closing Database or Recordset objects and the Jet engine; Microsoft Windows or MS-DOS doesn't have a chance to flush data caches.  To avoid corrupt databases, establish procedures for closing applications and shutting down systems that ensure that all cached pages are saved to the database.  In some cases, power supplies that can't be interrupted may be necessary to prevent accidental data loss during power fluctuations.

Tip   After repairing a database, it's also a good idea to compact it using the CompactDatabase method to defragment the file and to recover disk space.


Requery Method

See Also	Example	Applies to	Specifics

Updates the data in a Recordset object by re-executing the query on which the object is based.

Syntax

recordset.Requery

The recordset placeholder represents the name of the Recordset object you want to update.

Remarks

Requery ([NewQuerydef As Querydef])

(This method has been expanded from Access 2.0 to optionally take a querydef object as a parameter.)

Re-populates the current Recordset by either using the currrent query parameters or the new ones supplied by the NewQuerydef argument.

•	If the originial querydef is supplied then the Recordset is requeried using the parameters originally specified by the Querydef  (e.g. myquerydef.OpenRecordset()).

•	If a querydef was not used to create the recordset , or if a different querydef is specified than what was originally used to create the Recordset, then the Recordset is essentially recreated from scratch.

Note that the Restartable property can be used to determine whether this query can be rerun.

Use this method to ensure that a Recordset contains the most recent data.  When you use Requery, all changes made to the data in the underlying table by other users are displayed in the Recordset, and the first record in the Recordset becomes the current record.

You can't use the Requery method on dynaset- or snapshot-type Recordset objects whose Restartable property is set to False, nor can you use it on a table-type Recordset.

If both the BOF and EOF property settings of the Recordset object are True after you use the Requery method, the query didn't return any records and the Recordset will contain no data.


Seek Method

See Also	Example	Applies to	Specifics

Locates the record in an indexed table-type Recordset object that satisfies the specified criteria for the current index and makes that record the current record.

Syntax

table.Seek comparison, key1, key2...

The Seek method syntax has the following parts:

Part	Description

table	The name of an existing table-type Recordset object that has a defined index as specified by the Recordset object's Index property.

comparison	One of these string expressions: "<", "<=", "=", ">=", or ">".

key1, key2...	One or more values corresponding to the underlying table's Primary property setting.

Remarks

You must set the current index with the Index property before you use Seek.  If the index identifies a nonunique key field, Seek locates the first record that satisfies the criteria.

Caution   If you edit the current record, be sure you save the changes using the Update method before you move to another record.  If you move to another record without using Update, your changes are lost without warning.

The Seek method searches through the specified key fields and locates the first record that satisfies the criteria specified by comparison and key1.  Once found, it makes that record current and the NoMatch property is set to False.  If the Seek method fails to locate a match, the NoMatch property is set to True, and the current record is undefined.

If comparison is "=",  ">=", or  ">", Seek starts at the beginning of the index.  If comparison is "<" or "<=", Seek starts at the end of the index and searches backward unless there are duplicate index entries at the end.  In this case, Seek starts at an arbitrary entry among the duplicate index entries at the end of the index.

The key1 argument must be of the same field data type as the corresponding field in the current index.  For example, if the current index refers to a number field (such as Employee ID), key1 must be numeric.  Similarly, if the current index refers to a Text field (such as Last Name), key1 must be a string.

There doesn't have to be a current record when you use Seek.

You can use the Indexes collection to enumerate the existing indexes.

Notes

Always check the value of the NoMatch property setting to determine whether the Seek method has succeeded.  If it fails, NoMatch is set to True and the current record is undefined.

To locate a record in a dynaset- or snapshot-type Recordset that satisfies a specific condition, use the Find methods.  To include all records, not just those that satisfy a specific condition, use the Move methods to move from record to record.

You can't use the Seek method on an attached table of any type because attached tables must be opened as dynaset- or snapshot-type Recordset objects, which don't support the Seek method.  However, if you use the OpenDatabase method to directly open an installable ISAM database, you can use Seek on tables in that database.


Update Method (Data Access)

See Also	Example	Applies to	Specifics

Saves the contents of the copy buffer to a specified dynaset- or table-type Recordset object.

Syntax

recordset.Update

The recordset placeholder represents the name of an open, updatable dynaset- or table-type Recordset object.

Remarks

Use Update to save the current record and any changes you've made to it.

Caution   Changes to the current record are lost if:

You use the Edit or AddNew method, and then move to another record without first using Update.

You use Edit or AddNew, and then use Edit or AddNew again without first using Update.

You set the Bookmark property to another record.

You close the recordset referred to by recordset without first using Update.

To edit a record, use the Edit method to copy the contents of the current record to the copy buffer.  If you don't use Edit first, an error occurs when you use Update or attempt to change a field's value.

When the Recordset object's LockEdits property setting is True (pessimistically locked) in a multiuser environment, the record remains locked from the time Edit is used until the Update method is executed.  If the LockEdits property setting is False (optimistically locked), the record is locked and compared with the pre-edited record just before it is updated in the database.  If the record has changed since you used the Edit method, the Update operation fails with a trappable error (3197).  Note that optimistic locking is always used on external database formats like ODBC or installable ISAM.  To continue the Update operation with your changes, use the Update method again.  To revert to the record as the other user changed it, refresh the current record using the Move methods, or set the Bookmark property to itself.  For example:

' Error 3197 detected

Rs.BookMark = Rs.Bookmark	' Restore record from

' database (as changed).

To add a new record to a recordset, use the AddNew method.


AddNew Method, LastModified Property Example

This example creates a new record in a table named Customers, enters values, saves the changes, and then moves to and deletes the new record.

Dim MyDb As Database, MyTable As Recordset

Set MyDb = Workspaces(0).OpenDatabase("MYDB.MDB")

' Open table.

Set MyTable = MyDB.OpenRecordset("Customers", dbOpenTable)

MyTable.AddNew	' Create new record.

MyTable("Customer ID") = "FINNF"	' Set record key.

MyTable("Company Name") = "Finnegan's Foods"	' Set company name.

MyTable.Update	' Save changes.

MyTable.Move 0, MyTable.LastModified	' Go to new record

MyTable.Delete	' Delete new record.

MyTable.Close	' Close Table.

MyDb.Close	' Close Database


Append Method Example

The example defines a new field and appends it to a Fields collection.

Dim MyDB As Database, Fd As Field

Const dbText = 10	' Set field type constant.

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")  ' Open a database.

Fd.Name = "Phone"	' Set field properties.

Fd.Type = dbText

Fd.Size = 15

MyDB.TableDefs("Authors").Fields.Append Fd	' Add field to collection.


AppendChunk, FieldSize, Getchunk Methods Example

This example uses the GetChunk method to return consecutive 16K chunks of the Notes field in the Employees table of the database MYDB.MDB.  It uses FieldSize to determine how many chunks it needs to copy and copies the chunks to the string array NoteArray() where they can be changed.  It then uses AppendChunk to copy NoteArray() back to Notes.

' This line should be in Declarations section.

Option Base 1

Function GetNotes

Const ChunkSize = 16384	' Set size of chunk.

Dim NumChunks As Integer, TotalSize As Long, X As Integer

Dim MyDatabase As Database, MyRecordset As Recordset

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Open table.

Set MyRecordset = MyDatabase.OpenRecordset("Employees")

' Get field size.

TotalSize = MyRecordset![Notes].FieldSize()

' How many chunks?

NumChunks = TotalSize \ ChunkSize - (TotalSize Mod ChunkSize <> 0)

ReDim NoteArray(NumChunks) As String * ChunkSize

' Get current Notes field.

For X = 1 To NumChunks

NoteArray(X) = MyRecordset![Notes].GetChunk((X - 1) * _

ChunkSize, ChunkSize)

Next X

...	' Make changes.

MyRecordset.Edit	' Enable editing.

MyRecordset!Notes = ""	' Initialize Notes field.

For X = 1 To NumChunks

' Replace with edited Notes.

MyRecordset![Notes].AppendChunk NoteArray(X)

Next X

MyRecordset.Update	' Save changes.

MyRecordset.Close	' Close table.

   MyDatabase.Close 	'Close database.

End Function


BeginTrans, CommitTrans, Rollback Methods Example

This example changes the job title of all sales representatives in the Employees table of the database.  After the BeginTrans method starts a transaction that isolates all the changes made to the Employees table, the CommitTrans method saves the changes.  Notice that you can use the Rollback method to undo changes that you saved using the Update method.

One or more table pages remain locked while the user decides whether or not to accept the changes.  For this reason, this technique isn't recommended but only shown as an example.

Function ChangeTitle

Dim CRLF As String, EmployeeName As String

Dim Message As String, Prompt As String

Dim MyWorkspace As Workspace, MyDatabase As Database, MyTable _

As Recordset

CRLF = Chr$(13) & Chr$(10)

Prompt = "Change title to Account Executive?"

Set MyWorkspace = Workspaces(0)   ' Get default Workspace.

' Get current database.

Set MyDatabase = MyWorkspace.OpenDatabase("MYDB.MDB")

' Open table.

Set MyTable = MyDatabase.OpenRecordset("Employees", dbOpenTable)

MyWorkspace.BeginTrans	' Start of transaction.

MyTable.MoveFirst

Do Until MyTable.EOF

If MyTable![Title] = "Sales Representative" Then

EmployeeName = MyTable![Last Name] & ", " & MyTable! _

[First_Name]

Message = "Employee: " & EmployeeName & CRLF & CRLF

If MsgBox(Message & Prompt, vbQuestion + vbYesNo, "Change Job

Title") = YES Then

MyTable.Edit	' Enable editing.

MyTable![Title] = "Account Executive"   ' Change job title.

MyTable.Update	' Save changes.

End If

End If

MyTable.MoveNext	' Move to next record.

Loop

If MsgBox("Save all changes?", vbQuestion + vbYesNo, _

" Save Changes") = YES Then

MyWorkspace.CommitTrans	' Commit changes.

Else

MyWorkspace.Rollback	' Undo changes.

End If

MyTable.Close	' Close table.

MyDatabase.Close

End Function


Clone Method Example

This example creates a Recordset object using an SQL query and then uses Clone to create a clone of the Recordset so that bookmarks can be shared between the two objects.  This technique is especially useful when you have to compare the results of a query from more than one point at the same time.  The example creates two sorted lists of the same data: One sorted by Author and the other by Title.  Selections from either list can be used to fetch records based on either Recordset because they share the same bookmarks.

Dim Db as Database

Dim Rs1 as Recordset, Rs2 as Recordset

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Set Rs1 = Db.OpenRecordset("SELECT * FROM Titles " _

& " WHERE [Year Published] > 1993 ORDER by Title"

Set Rs2 = Rs1.Clone()	' Clone Recordset.

Rs2.MoveFirst	' Set current record.

Do Until Rs1.EOF

List1.AddItem Rs1!Author	' Add to self-sorting list box.

Rs1.MoveNext

Loop

Do Until Rs2.EOF

List1.AddItem Rs2!Title	' Add to list box.

Rs2.MoveNext

Loop


Close Method Example

This example opens and then closes a database and a table-type Recordset object for the Customers table in the database.

Dim MyDatabase As Database, MyRecordset As Recordset

' Open database.

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Open table.

Set MyRecordset = MyDatabase.OpenRecordset("Customers")

...

MyRecordset.Close	' Close table.

MyDatabase.Close	' Close database.


CompactDatabase Method Example

This example uses CompactDatabase to compact a database called PUBS.MDB and keeps a backup copy of the original database.  The new database has the same locale as the source database, but is encrypted.

DBEngine.CompactDatabase "C:\PUBS.MDB","C:\PUBSNEW.MDB","",dbEncrypt

...

Kill "C:\PUBS.BAK"

Name "C:\PUBS.MDB" As "C:\PUBS.BAK"

Name "C:\PUBSNEW.MDB" As "C:\PUBS.MDB"

This example copies a database named MYDB.MDB and keeps a new, compacted copy named MYDB.NEW.  The new database has the same collating order as the original database, but it's encrypted.

DBEngine.CompactDatabase "C:\MYDB.MDB", "C:\MYDB.NEW", dbLangGeneral, _

dbEncrypt


CreateDatabase Method Example

This example uses CreateDatabase to create a new, encrypted Database object named CurrentEncrypted.  The example customizes some properties of the new database, completes its structure, and then closes it.

Dim DefaultWorkspace As Workspace

Dim CurrentDatabase As Database, MyDatabase As Database

Set DefaultWorkspace = DBEngine.Workspaces(0)

Set CurrentDatabase = DefaultWorkspace.Databases(0)

' Create new, encrypted database.

Set MyDatabase = DefaultWorkspace.CreateDatabase ("NEWDB.MDB", _

dbLangGeneral, dbEncrypt)

' Fill in new database.

' Set property to that of current database.

MyDatabase.QueryTimeout = CurrentDatabase.QueryTimeout

...

' Complete structure of MyDatabase, possibly using structure of CurrentDatabase.

...

MyDatabase.Close


CreateField Method Example

This example creates a new Field object.

Dim MyDatabase As Database

Dim MyTableDef As TableDef

Dim MyField As Field

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTableDef = MyDatabase.TableDefs(0)

' Create new Field object.

Set MyField = MyTableDef.CreateField("Phone", dbText)

' Set another property of MyField.

MyField.Size = 25	' Greater than longest phone number.

' Save Field definition by appending it to Fields collection.

MyTableDef.Fields.Append MyField


CreateGroup Method Example

This example creates a new Group object.

Dim MyGroup As Group, ManagersPID As String

ManagersPID = "2222abc"

' Create new Group object.

Set MyGroup = Workspaces(0).CreateGroup("Managers", ManagersPID)

' Create new group in workgroup by appending it to Groups collection.

DBEngine.Workspaces(0).Groups.Append MyGroup


CreateIndex Method Example

This example creates a new Index object.

Dim MyIndex As Index

Dim MyField As Field

Dim MyTableDef As TableDef

Dim MyDatabase As Database

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTableDef = MyDatabase.TableDefs(0)

' Create new Index object.

Set MyIndex = MyTableDef.CreateIndex("Another")

Set MyField = MyIndex.CreateField("LastName")

MyIndex.Primary = True

MyIndex.Required = True

MyIndex.Fields.Append MyField

' Save Index definition by appending it to Indexes collection.

MyTableDef.Indexes.Append MyIndex


CreateProperty Method Example

This example creates a new Property object.

Dim MyProperty As Property

Dim MyDatabase As Database

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create new Property object.

Set MyProperty = MyDatabase.CreateProperty("Privilege")

' Set other properties of MyProperty.

MyProperty.Type = dbBoolean

MyProperty.Value = True

' Save Property definition by appending it to Properties collection.

MyDatabase.Properties.Append MyProperty


CreateQueryDef Method Example

This example creates a QueryDef named All Pubs with an SQL statement, and then creates a dynaset-type Recordset based on the query.

Dim MyDB As Database, MyQuery As QueryDef, MySet As Recordset

' Open a database.

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")

' Create a QueryDef.

Set MyQuery = MyDB.CreateQueryDef("All Pubs",  _

"SELECT * FROM Publishers;")

' Create Recordset from query.

Set MySet = MyDB.OpenRecordset("All Pubs")

...

MySet.Close	' Close Recordset object.


CreateRelation Method Example

This example creates a new Relation object.  In this case, the Customers table is related to a ValidStates table.  Once established, the relationship requires that an entry exist in the ValidStates table corresponding to the Customers.CustState field before it can be added to the Customers table.  Any changes to the State field that violates this relationship triggers a trappable error.

By setting the dbRelationUpdateCascade attribute, the Microsoft Jet database engine changes the Primary table Customers.CustState if a corresponding value changes in the ValidStates table.  For example, if the ValidState entry TR was changed to TX, all Customers records having TR as a CustState code would be changed to TX.

Dim MyRelation As Relation

Dim MyDatabase As Database

Dim MyField As Field

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create new Relation object.

Set MyRelation = MyDatabase.CreateRelation("TableRelationOne")

MyRelation.Table = "Customers"	'Name the Primary Table.

MyRelation.ForeignTable = "ValidStates"	'Name the Foreign Table.

MyRelation.Attributes = dbRelationUpdateCascade

Set MyField = MyRelation.CreateField("CustState")

MyField.ForeignName = "StateCode"

MyRelation.Fields.Append MyField

' Save Relation definition by appending it to Relations collection.

MyDatabase.Relations.Append MyRelation


CreateTableDef Method Example

This example creates a new TableDef object in  the BIBLIO.MDB database.

Dim MyTableDef As TableDef, MyField As Field

Dim MyDatabase As Database

Set MyDatabase = Workspaces(0).OpenDatabase("BIBLIO.MDB")

' Create new TableDef.

Set MyTableDef = MyDatabase.CreateTableDef("Title Detail")

' Add field to MyTableDef.

Set MyField = MyTableDef.CreateField("Comments",dbDate)

MyTableDef.Fields.Append MyField

' Save TableDef definition by appending it to TableDefs collection.

MyDatabase.TableDefs.Append MyTableDef


CreateUser Method Example

This example creates a new User object.

Dim MyUser As User

Dim ManagersPID As String

ManagersPID = "1122aabb"

' Create new user account.

Set MyUser = Workspaces(0).CreateUser("Senior Partner", ManagersPID)

' Set other properties of MyUser.

MyUser.Password = "NewPassword"

' Save user account definition by appending it to Users collection.

Workspaces(0).Users.Append MyUser

' Add user to predefined Users group.

MyUser.Groups.Append MyUser.CreateGroup("Users")


CreateWorkspace Method Example

This example creates a new Workspace object named Special, sets its UserName property to the UserName property setting of the default workspace, and sets its Password property to SpecialPW.

Dim MyWorkspace As Workspace

Dim MyUserName As String

' Get UserName of default workspace.

MyUserName = DBEngine.Workspaces(0).UserName

' Create new workspace.

Set MyWorkspace = DBEngine.CreateWorkspace("Special", MyUserName, _

"SpecialPW")


Delete Method Example

This example finds a record in a  Recordset  and deletes it.

' Find the record you want to delete.

MyRecordset.FindFirst "PubNum = 9"

If Not MyRecordset.NoMatch Then	' Check if record found.

MyRecordset.Delete	' Delete the record.

End If

This example adds and then deletes an Index from a TableDef.

Dim MyDB As Database, MyTableDef As TableDef, MyIndex As Index

' Open the database.

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Set MyTableDef = MyDB.TableDefs("Publishers")	' Set the TableDef.

Set MyIndex = MyTableDef.CreateIndex("Author Name")

Set MyField = MyIndex.CreateField("Author")

MyIndex.Fields.Append MyField	' Add Field to Index.

MyRsDef.Indexes.Append MyIndex	' Add Index to TableDef.

...

MyRsDef.Indexes.Delete "Author Name"	' Delete the Index.


OpenRecordset, Edit, Update Methods; Recordset Object, Recordsets Collection Example
OpenRecordset, Edit, Update Methods Example

This example finds the first record in a Recordset object that matches the search criteria and opens it for editing.  Then it changes the value in the Title field and saves the change using the Update method.

Dim Criteria As String, NewTitle As String

Criteria = "Title = 'My Right Hand'"	' Create the criteria.

NewTitle = "My Right Foot"	' Create a new title.

MyRecordset.FindFirst Criteria	' Make record current.

Do While Not MyRecordset.NoMatch

If Not Data1.Recordset.NoMatch Then

MyRecordset.Edit	' Open record.

MyRecordset.Fields("Title") = NewTitle	' Enter new title.

MyRecordset.Update	' Save changes.

End If

MyRecordset.FindNext Criteria

Loop

The following example achieves the same effect without using the Edit method.

' Create the criteria string.

SQLQuery = "UPDATE Titles SET Title = 'My Right Foot'"

SQLQuery = SQLQuery & " WHERE Title = 'My Right Hand';"

MyDatabase.Execute SQLQuery	' Execute the query.

This example opens a Recordset object and locates each record whose Title field satisfies the search criteria and copies it to the copy buffer.  The example then prepares the record for subsequent editing, changes the job title, and saves the change using the Update method.

Dim Criteria As String, MyDB As Database, MySet As Recordset

Dim NewTitle As String

' Set search criteria.

Criteria = "Title = 'Sales Representative'"

NewTitle = "Account Executive"	' Set new job title.

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create dynaset.

Set MySet = MyDB.OpenRecordset("Employees", dbOpenDynaset)

MySet.FindFirst Criteria	' Find first occurrence.

' Loop until no matching records.

Do Until MySet.NoMatch

MySet.Edit	' Enable editing.

MySet!Title = NewTitle	' Change title.

MySet.Update	' Save changes.

MySet.FindNext Criteria	' Find next occurrence.

Loop	' End of loop.

Tip   Using an update query to change job titles might be more efficient.  For example you could use the following code to achieve the same results:

SQL$ = "Update Employees Set Title = 'Account Executive' " "

& " "WHERE Title = 'Sales Representative' "

MyDb.Execute SQL$


Execute Method Example

This example uses a Data control to execute an action query that updates all titles that have no value in the ISBN column in the Titles table.  If there is an error, all changes are rolled back.

Dim SQL as String

SQL = "DELETE FROM Titles WHERE ISBN IS NULL"

My.Database.Execute SQL, dbFailOnError


FindFirst, FindLast, FindNext, FindPrevious Methods Example

This example uses FindFirst to find the first record matching the specified criteria in a Recordset object and then uses FindNext to find the next matching record.

Dim MyCriteria As String

MyCriteria = "State = 'NY'"	' Set the criteria.

My.Recordset.FindFirst MyCriteria	' Find first matching record.

If Not My.Recordset.NoMatch Then...	' Check if record is found.

...

My.Recordset.FindNext MyCriteria	' Find next matching record.

This example creates a dynaset-type Recordset object and then uses FindFirst to locate the first record satisfying the title condition.

Dim MyCriteria As String, MyDB As Database, MySet As Recordset

MyCriteria = "State = 'NY'" 	' Define search criteria.

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")

' Create a dynaset-type Recordset based on Publishers table.

Set MySet = MyDB.OpenRecordset("Publishers",dbOpenDynaset)

MySet.FindFirst MyCriteria	' Find first matching record.

If MySet.NoMatch Then...	' Check if record is found.

...

MySet.FindNext MyCriteria	' Find next matching record.


GetRows Method Example

This example uses the GetRows method to bring two fields from the Orders table into memory.

Dim db as Database

Dim rs as Recordset

Dim data as Variant

Set db = OpenDatabase("sales.mdb")

set rs = db.OpenRecordset("Select OrderId, CustId from Orders")

While Not rs.eof

   data = rs.GetRows(10)

   .... ' do something with the data

Wend

rs.Close

db.Close


Move Method Example

This example creates a function that moves the current record position in a Recordset forward or back a specified number of records and provides an optional offset.

Sub MoveRelative (Distance As Long, Direction As String, MyRecordset _

As Recordset, RelativeBookMark As String)

Dim Here As String

Here = MyRecordset.Bookmark

Direction = UCase(Direction)

Select Case Direction

Case "FWD":  Distance = Abs(Distance)

Case "BACK": Distance = Abs(Distance) * -1

Case Else: MsgBox "Incorrect calling argument"

End Select

If UCase(RelativeBookMark) = "HERE" Then

MyRecordset.Move Distance	' Move current record position.

Else

' Move relative to bookmark.

MyRecordset.Move Distance, RelativeBookMark

End If

' Move may not have been completed.

If MyRecordset.EOF Or MyRecordset.BOF Then Beep

End Sub


MoveFirst, MoveLast, MoveNext, MovePrevious Methods Example

This example changes the job title of all sales representatives in a table named Employees.  After opening the table, it uses MoveFirst to locate the first record and MoveNext to move to the next record.  For each record satisfying the title condition, the example changes the title and saves the change using the Update method.

It's far more efficient to use the WHERE clause of an SQL statement to request the records you want to update than to test each record one at a time.  The whole operation could be accomplished by using a single UPDATE statement, as shown below.

Dim MyDB As Database, MyTable As Recordset, SQL as String

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

SQL$ = "Select * FROM Employees WHERE Title = 'Sales Representative' "

' Open recordset.

Set MyTable = MyDB.OpenRecordset(SQL$, dbOpenDynaset)

Do Until MyTable.EOF	' Begin loop.

MyTable.Edit	' Enable editing.

MyTable!Title = "Account Executive"	' Change title.

MyTable.Update	' Save changes.

MyTable.MoveNext	' Locate next record.

Loop	' End of loop.

MyTable.Close	' Close table.

MyDB.Close

Tips

Using an update query to change job titles might be more efficient.  For example, you could use the following code to achieve the same results:

Dim SQL as String

SQL$ = "Update Employees Set Title = 'Account Executive' " " _

& " "WHERE Title = 'Sales Representative' "

MyDb.Execute SQL$


NewPassword Method Example

This example changes the password of the existing user Pat Smith from My Secret to msMSApw.  The user must be logged on as Pat Smith or as a member of the Admins group.

Workspaces(0).Users("Pat Smith").NewPassword "My Secret", "msMSApw"


OpenDatabase Method Example

This example opens the Employees table in the database in the default Workspace object.  If the database can't be opened (for example, if it has already been opened for exclusive access by another user in a multiuser environment), an error occurs and a message is displayed.  Then the example updates the Title field of the Employees table.

Function UpdateNorthwind () As Integer

Dim MyWorkspace As Workspace, MyDatabase As Database

Dim MyTable As Recordset

Dim MyFile As String

Dim ErrorCondition As Integer

UpdateDb = True

MyFile = "MYDB.MDB"	' Define name of database.

On Error GoTo DBErrorHandler	' Enable error trapping.

Set MyWorkspace = Workspaces(0)

' Open database.

Set MyDatabase = MyWorkspace.OpenDatabase(MyFile)

If Not ErrorCondition Then

On Error GoTo TableErrorHandler	' Enable error trapping.

' Open table.

Set MyTable = MyDatabase.OpenRecordset("Employees")

If Not ErrorCondition Then

On Error GoTo EditErrorHandler	' Enable error trapping.

Do Until MyTable.EOF

If MyTable![Title] = "Sales Representative" Then

MyTable.Edit	' Enable editing.

MyTable![Title] = "Account Executive"   ' Make changes.

MyTable.Update	' Save changes.

End If

MyTable.MoveNext	' Move to next record.

Loop

MyTable.Close	' Close table.

End If

MyDatabase.Close	' Close database.

End If

On Error GoTo 0	' Disable error trapping.

Exit Function

DBErrorHandler:

ErrorCondition = True

UpdateDb = False

MsgBox "Can't open database.", vbExclamation

Resume Next

TableErrorHandler:

ErrorCondition = True

UpdateDb = False

MsgBox "Can't open Employees table.", vbExclamation

Resume Next

EditErrorHandler:

ErrorCondition = True

UpdateDb = False

MsgBox "Can't edit Employees table.", vbExclamation

Resume Next

End Function


Refresh Method (Data Access) Example
Refresh Method Example

This example refreshes the Tables collection in a database in a multiuser environment in case another user has made changes.

Dim MyWorkspace As Workspace, MyDatabase As Database

' Get default workspace.

Set MyWorkspace = Workspaces(0)

' Open database.

Set MyDatabase = MyWorkspace.OpenDatabase("MYDB.MDB")

...

' Refresh possibly changed collection.

MyDatabase.Containers("Tables").Documents.Refresh


RefreshLink Method Example

This example attaches a Paradox table named PDX_Author to a database opened for exclusive use, moves the connection to a different directory, and then refreshes the connection information.

Dim MyDb As Database, MyTable As TableDef

' Open database.

Set MyDb = MyWorkspaces(0).OpenDatabase("C:\CONTACTS\PUBS.MDB")

Set MyTable = MyDB.CreateTableDef("PDX_Author", dbAttachExclusive)

MyTable.SourceTableName = "Author"

MyTable.Connect = "Paradox 3.x; " _

& "DATABASE = C:\PDX\PUBS; PWD=books"

' Append to TableDefs collection.

MyDB.TableDefs.Append MyTable

' Move to new directory.

MyDB.TableDefs!PDX_Author.Connect = "Paradox 3.x; " _

& "DATABASE = N:\PDX\PUBS; PWD=books"

' Refresh connection information.

MyDB.TableDefs!PDX_Author.RefreshLink


RegisterDatabase Method Example

This example registers a SQL Server data source named PtLudlow and then opens the database MySQLDb on that server.

Using the Windows ODBC control panel icon is the preferred way to create, modify or delete data source names.

Dim MyDatabase As Database

Dim Attribs As String

' Build keywords string.

Attribs = "Description=SQL Server on server PtLudlow" & Chr$(13)

Attribs = Attribs & "OemToAnsi=No" & Chr$(13)

Attribs = Attribs & "Network=DBNMP3" & Chr$(13)

Attribs = Attribs & "Address=\\PTLUDLOW\PIPE\SQL\QUERY" & Chr$(13)

Attribs = Attribs & "Database=MySQLDb"

' Update ODBC.INI.

DBEngine.RegisterDatabase "PtLudlow", "SQL Server", True, Attribs

...

' Open the database.

Set MyDatabase = Workspaces(0).OpenDatabase("PtLudlow", False, _

False, "ODBC;")


RepairDatabase Method Example

This example attempts to repair a database named MYDB.MDB.

DBEngine.RepairDatabase "C:\MYDB.MDB"


Seek Method Example

This example uses Seek to locate the first record in the Publishers table where the PubID field is 3, using the existing primary key index.

Dim MyDB As Database, MyTable As Recordset

' Open a database.

Set MyDB = Workspaces(0).OpenDatabase("BIBLIO.MDB")

' Open a table.

Set MyTable = MyDB.OpenRecordset("Publishers",dbopenTable)

MyTable.Index = "PrimaryKey"	' Define current index.

MyTable.Seek "=", 3	' Seek record.

If MyTable.NoMatch Then...

This example uses the OpenDatabase method to directly open an installable ISAM database and then uses Seek to locate a record in a table in that database.

Dim Db as Database

Dim Rst as Recordset, SaveHere as Variant

Set Db = OpenDatabase("C:\FoxData", False, False,"Fox 2.5")

Set Rst = OpenRecordset("PARTS.DBF", dbOpenTable)

' Choose record order and Seek index.

Rst.Index = "PartNameIndex"

Rst.Bookmark = Rst.BookMark	' Save current location.

' Search for first instance of a chosen part.

Rst.Seek = "Framis Lever"

If Rst.NoMatch then 	' Test for success.

Rst.BookMark = SaveHere	' Seek not successful.

...

Else	' Seek worked; use current record.

Debug.Print Rst!PartName

End If


Update Method Example

This example changes the Title field in the current record of a Recordset object and then uses the Update method to save the changes.

My.Recordset.Edit	' Enable editing.

My.Recordset.Fields("Title") = "My Right Foot"	' Change title.

My.Recordset.Update	' Save changes.


AbsolutePosition Property

See Also	Example	Applies to	Specifics

Returns or sets the relative record number of a Recordset object's current record.

Syntax

object.AbsolutePosition [= value]

The AbsolutePosition property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An integer from 0 to the number of records in the Recordset.  Corresponds to the ordinal position of the current record in the Recordset specified by object.  (Data type is Long.)

Remarks

The AbsolutePosition property enables you to position the current record pointer to a specific record based on its ordinal position in a dynaset- or snapshot-type Recordset.  You can also determine the current record number by checking the AbsolutePosition property setting.

The AbsolutePosition property value is zero-based [image] a setting of 0 refers to the first record in the Recordset.  Setting a value greater than the number of populated records causes a trappable error.  You can determine the number of populated records in the Recordset by checking the RecordCount property setting.

If there is no current record, as when there are no records in the Recordset, -1 is returned.  If the current record is deleted, the AbsolutePosition property value isn't defined, and a trappable error occurs if it's referenced.  New records are added to the end of the sequence.

Note   This property isn't intended to be used as a surrogate record number.  Bookmarks are still the recommended way of retaining and returning to a given position and are the only way to position the current record across all types of Recordset objects.  In particular, the position of a given record changes when record(s) preceding it are deleted.  There is also no assurance that a given record will have the same absolute position if the Recordset is re-created again because the order of individual records within a Recordset isn't guaranteed unless it's created with an SQL statement using an ORDER BY clause.


AllowZeroLength Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether a zero-length string ("") is a valid setting for the Value property of a Field object with a Text or Memo data type.  For an object not yet appended to the Fields collection, this property is read/write.

Syntax

object.AllowZeroLength [= value]

The AllowZeroLength property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates if a value is valid, as described in Settings. (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	A zero-length string is a valid value.

False	A zero-length string isn't a valid value.

Remarks

For a Field object, use of the AllowZeroLength property depends on the object that contains the Fields collection that the Field object is appended to, as the following table shows.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read/write

You can set this property to False to ensure that you can't use a zero-length string to set the Value property of a Field object.

You can use this property along with the Required, ValidateOnSet, or ValidationRule property to determine the validity of a value in a field.


Attributes Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates one or more characteristics of a Field object, a Relation object, or a TableDef object.  For an object not yet appended to a collection, this property is read/write.  See Remarks for the more specific read/write characteristics of this property.

Syntax

object.Attributes [= value]

The Attributes property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A constant specifying the characteristics of an object, as described in Settings.  (Data type is Long.)

Settings

For a Field object, value specifies characteristics of the field represented by the Field object and can be a sum of these constants:

Constant	Description

dbFixedField	The field size is fixed (default for Numeric fields).

dbVariableField	The field size is variable (Text fields only).

dbAutoIncrField	The field value for new records is automatically incremented to a unique Long integer that can't be changed.  Only supported for Jet database tables.

dbUpdatableField	The field value can be changed.

dbDescending	The field is sorted in descending (Z-A or 100-0) order (applies only to a Field object in a Fields collection of an Index object).  If you omit this constant, the field is sorted in ascending (A-Z or 0-100) order (default).

For a Relation object, value specifies characteristics of the relationship represented by the Relation object and can be a sum of these constants:

Constant	Description

dbRelationUnique	Relationship is one-to-one.

dbRelationDontEnforce	Relationship isn't enforced (no referential integrity).

dbRelationInherited	Relationship exists in a noncurrent database that contains the two attached tables.

dbRelationLeft	The relationship is a left join.

dbRelationRight	The relationship is a right join.

dbRelationUpdateCascade	Updates will cascade.

dbRelationDeleteCascade	Deletions will cascade.

Note   If you set the Relation object's Attributes property to activate cascade operations, the Microsoft Jet database engine automatically updates or deletes records in one or more other tables when changes are made to related primary key tables.

For example, suppose you establish a cascade delete relationship between a Customers table and an Orders table.  When you delete records from the Customers table, records in the Orders table related to that customer are also deleted.  In addition, if you establish cascade delete relationships between the Orders table and other tables, records from those tables are automatically deleted when you delete records from the Customers table.

For a TableDef object, value specifies characteristics of the table represented by the TableDef object and can be a sum of these Long constants:

Constant	Description

dbAttachExclusive	For databases that use the Microsoft Jet database engine, indicates the table is an attached table opened for exclusive use.

dbAttachSavePWD	For databases that use the Jet database engine, indicates that the user ID and password for the attached table saved with the connection information.

dbSystemObject	Indicates the table is a system table provided by the Jet engine.  (Read-only.)

dbHiddenObject	Indicates the table is a hidden table provided by the Jet engine (for temporary use).  (Read-only.)

dbAttachedTable	Indicates the table is an attached table from a non-ODBC database, such as a Jet or Paradox database.

dbAttachedODBC	Indicates the table is an attached table from an ODBC database, such as Microsoft SQL Server.

Remarks

These constants are listed in the Data Access (DAO) object library in the Object Browser.

For a Field object, use of the Attributes property depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Read-only

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read-only

For a Relation object, the Attributes property setting is read-only for an object appended to a collection.

For a TableDef object, use of the Attributes property depends on the status of TableDef, as shown in the following table.

TableDef	Usage

Base table	Read-only

Attached table	Read-only

When checking the setting of this property, you can use the Visual Basic And operator to test for a specific attribute.  For example, to determine whether a Field object is fixed-size, you can use this code:

If MyRecordset![FieldName].Attributes And dbFixedField Then...

When setting multiple attributes, you can combine them by summing the appropriate constants.  Any nonmeaningful values are ignored without producing an error.  For example, to use the Attributes property to make the Text field represented by a Field object variable-sized and changeable, you can use this code:

MyRecordset![FieldName].Attributes = dbVariableField + dbUpdatableField


BOF, EOF Properties

See Also	Example	Applies to	Specifics

BOF [image] returns a value that indicates whether the current record position is before the first record in a Recordset.

EOF [image] returns a value that indicates whether the current record position is after the last record in a Recordset.

Syntax

object.BOF

object.EOF

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The BOF property return values are:

Value	Description

True	The current record position is before the first record.

False	The current record position is on or after the first record.

The EOF return values are:

Value	Description

True	The current record position is after the last record.

False	The current record position is on or before the last record.

Remarks

The BOF and EOF return values are determined by the location of the current record pointer.

You can use the BOF and EOF properties to determine whether a Recordset object contains records or whether you've gone beyond the limits of a Recordset as you move from record to record.

If either BOF or EOF is True, there is no current record.

If you open a Recordset containing no records, BOF and EOF are set to True, and the recordset's RecordCount property setting is 0.  When you open a Recordset that contains at least one record, the first record is the current record and BOF and EOF are False; they remain False until you move beyond the beginning or end of the Recordset using the MovePrevious or MoveNext method, respectively.  When you move beyond the beginning or end of the recordset, there is no current record or no record exists.

If you delete the last remaining record in the Recordset object, BOF and EOF may remain False until you attempt to reposition the current record.

If you use the MoveLast method on a Recordset containing records, the last record becomes the current record; if you then use the MoveNext method, the current record becomes invalid and EOF is set to True.  Conversely, if you use the MoveFirst method on a Recordset containing records, the first record becomes the current record; if you then use the MovePrevious method, there is no current record and BOF is set to True.

Typically, when you work with all the records in a Recordset, your code will loop through the records using MoveNext until the EOF property is set to True.

If you use MoveNext while EOF is set to True or MovePrevious while BOF is set to True, an error occurs.

This table shows which Move methods are allowed with different combinations of BOF/EOF.

	MoveFirst, MoveLast	MovePrevious, Move < 0	Move 0	MoveNext, Move > 0
BOF=True, EOF=False	Allowed	Error	Error	Allowed
BOF=False, EOF=True	Allowed	Allowed	Error	Error
Both True	Error	Error	Error	Error
Both False	Allowed	Allowed	Allowed	Allowed
Allowing a Move method doesn't mean that the method will successfully locate a record.  It merely indicates that an attempt to perform the specified Move method is allowed and won't generate an error.  The state of the BOF and EOF flags may change as a result of the attempted Move.

Effect of specific methods on BOF and EOF settings:

An OpenRecordset method internally invokes a MoveFirst.  Therefore, an OpenRecordset on an empty set of records results in BOF and EOF being set to True.  (See the following table for the behavior of a failed MoveFirst method.)

All Move methods that successfully locate a record clear (set to False) both BOF and EOF.

An AddNew method followed by an Update method that successfully inserts a new record will clear BOF, but only if EOF is already set to True.  The state of EOF will always remain unchanged.  As defined by the Microsoft Jet database engine, the current record pointer of an empty recordset is at the end of a file, so any new record is inserted after the current record.

Any Delete method, even if it removes the only remaining record from a recordset, won't change the setting of BOF or EOF.

The effect of Move methods that don't locate a record on BOF and EOF settings is shown in the following table.

	BOF	EOF
MoveFirst, MoveLast	True	True
Move 0	No change	No change
MovePrevious, Move < 0	True	No change
MoveNext, Move > 0	No change	True


Bookmark Property

See Also	Example	Applies to	Specifics

Returns or sets a bookmark that uniquely identifies the current record in a Recordset object or sets the current record in a Recordset to a valid bookmark.

Syntax

object.Bookmark [= value]

The Bookmark property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression or variant expression that evaluates to a valid bookmark.  (Data type is String or Variant.)

Remarks

You can use the Bookmark property with Recordset objects and with the outdated Dynaset, Snapshot, and Table objects.  For a Recordset based entirely on Microsoft Jet database engine tables, the value of the Bookmarkable property is True and bookmarks can be used.  Other database products may not support bookmarks, however.  For example, you can't use bookmarks in any Recordset based on an attached Paradox table that has no primary key.

When a Recordset object is created or opened, each of its records already has a unique bookmark.  You can save the bookmark for the current record by assigning the value of the Bookmark property to a variable.  To quickly return to that record at any time after moving to a different record, set the Recordset object's Bookmark property to the value of that variable.

Note   In Visual Basic version 3.0, the Bookmark property is managed as a string.  In Visual Basic version 4.0, the Bookmark property is stored internally as a Byte array.  For this reason, if you attempt to use the Bookmark property in a compare operation, a trappable error will result.  Before accessing the Bookmark property, copy the bookmark values to string variables and make all comparisions using just these string variables.  For example, the following code compares bookmarks in two Recordset objects:

Dim Book1 as String, Book2 as String

Dim Rs1 as Recordset, Rs2 as Recordset

Set Rs1 = Db.OpenRecordset("Titles")

Set Rs2 = Rs1.Clone()

Book1 = Rs1.Bookmark

Book2 = Rs2.Bookmark

If Book1 = Book2 Then Print "This comparison is valid"

There is no limit to the number of bookmarks you can establish.  To create a bookmark for a record other than the current record, move to the desired record and assign the value of the Bookmark property to a String variable that identifies the record.

To make sure the Recordset supports bookmarks, inspect the value of its Bookmarkable property before you use the Bookmark property.  If Bookmarkable is False, the Recordset doesn't support bookmarks, and using the Bookmark property results in a trappable error.

If you create a copy of a Recordset object using the Clone method, the Bookmark settings for the original and the duplicate Recordset are identical and can be used interchangeably.  However, you can't use bookmarks from different Recordset objects interchangeably, even if they were created using the same object or the same SQL statement.

If you set the Bookmark property to a value that represents a deleted record, a trappable error occurs.

To refresh the contents of a record, set the Bookmark property to itself.  (This technique, however, also cancels any pending operations invoked by the Edit or AddNew methods.)  For example:

Rst.Bookmark = Rst.Bookmark

The value of the Bookmark property isn't the same as a record number.

Note   The Bookmark property doesn't apply to forward-only scrolling, snapshot-type Recordset objects.


Bookmarkable Property

See Also	Example	Applies to	Specifics

Returns a value that indicates whether a Recordset object supports bookmarks, which you can set using the Bookmark property.

Syntax

object.Bookmarkable

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Bookmarkable property return values are:

Value	Description

True	The Recordset supports bookmarks.

False	The Recordset doesn't support bookmarks.

Remarks

You can use the Bookmarkable property with Recordset objects and with the outdated Dynaset, Snapshot, and Table objects that support bookmarks.

Check the Bookmarkable property setting before you attempt to set or check the Bookmark property to make sure that the Recordset supports bookmarks.

For a Recordset based entirely on Microsoft Jet database engine tables, the value of the Bookmarkable property is True, and bookmarks can be used except on forward-only scrolling snapshots.  Other database products may not support bookmarks, however.  For example, you can't use bookmarks in any Recordset based on an attached Paradox table that has no primary key.


CacheSize, CacheStart Properties

See Also	Example	Applies to	Specifics

CacheSize [image] returns or sets a value that specifies the number of records in a dynaset-type Recordset containing data to be locally cached from an ODBC data source.

CacheStart [image] returns or sets a value that specifies the bookmark of the first record in the Recordset to be cached.

Syntax

object.CacheSize [= value]

object.CacheStart [= value]

The CacheSize and CacheStart property syntaxes have these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A number or string expression.  The setting for CacheSize specifies the number of records and must be between 5 and 1200, but not greater than available memory.  A typical value is 100.  A setting of 0 turns off caching.  (Data type is Long.)  The setting for CacheStart specifies a bookmark (Data type is String.)

Remarks

Data caching improves the performance of an application that retrieves data from a remote server through dynaset-type Recordset objects.  A cache is a space in local memory that holds the data most recently retrieved from the server in the event that the data will be requested again while the application is running.  When data is requested, the Microsoft Jet database engine checks the cache for the requested data first rather than retrieving it from the server, which takes more time.  Data that doesn't come from an ODBC data source isn't saved in the cache.

Any ODBC data source, such as an attached table, can have a local cache.  To create the cache, open a Recordset object from the remote data source, set the CacheSize and CacheStart properties, and then use the FillCache method or step through the records using the Move methods.

The CacheSize property setting can be based on the number of records your application can work with at one time.  For example, if you're using a Recordset as the source of the data to be displayed on screen, you could set its CacheSize property to 20 to display 20 records at one time.

The CacheStart property setting is the bookmark of the first record in the Recordset to be cached.  You can use the bookmark of any record to set the CacheStart property.  Make the record you want to start the cache with the current record, establish a bookmark for that record, and set the CacheStart property to the bookmark.

The Jet database engine requests records within the cache range from the cache, and it requests records outside the cache range from the server.

Notes

 	Records retrieved from the cache don't reflect changes made concurrently to the source data by other users.

To force an update of all the cached data, set the CacheSize property of the Recordset to 0, set it to the size of the cache you originally requested, and then use the FillCache method.


Clustered Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether an Index object represents a clustering index for a table.  This property setting is read/write for a new Index object not yet appended to a collection and read-only for an existing Index object in an Indexes collection.

Syntax

object.Clustered [= value]

The Clustered property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates a clustering index, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	The Index object represents a clustering index.

False	The Index object doesn't represent a clustering index.

Remarks

A clustering index consists of one or more nonkey fields that, taken together, arrange all records in a table in a predefined order.  A clustering index provides efficient access to records in a table in which the index values may not be unique.

Notes

The Clustered property is ignored for databases that use the Microsoft Jet database engine because the Jet database engine doesn't support clustering indexes.

You don't have to create indexes for tables, but in large, unindexed tables, accessing a specific record can take a long time.  The Attributes property of each Field object in the Index object determines the order of records and consequently determines the access techniques to use for that index.


CollatingOrder Property

See Also	Example	Applies to	Specifics

Returns a value that specifies the sequence of the sort order in text for string comparison or sorting.  This property setting is read-only.

Syntax

object.CollatingOrder

The CollatingOrder property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A constant that specifies the sort order, as described in Settings.  (Data type is Integer.)

Settings

The values returned are:

Setting	Description

dbSortGeneral	Use the General (English, French, German, Portuguese, Italian, and Modern Spanish) sort order.

dbSortArabic	Use the Arabic sort order.

dbSortCyrillic	Use the Russian sort order.

dbSortCzech	Use the Czech sort order.

dbSortDutch	Use the Dutch sort order.

dbSortGreek	Use the Greek sort order.

dbSortHebrew	Use the Hebrew sort order.

dbSortHungarian	Use the Hungarian sort order.

dbSortIcelandic	Use the Icelandic sort order.

dbSortNorwdan	Use the Norwegian or Danish sort order.

dbSortPDXIntl	Use the Paradox International sort order.

dbSortPDXNor	Use the Paradox Norwegian or Danish sort order.

dbSortPDXSwe	Use the Paradox Swedish or Finnish sort order.

dbSortPolish	Use the Polish sort order.

dbSortSpanish	Use the Spanish sort order.

dbSortSwedFin	Use the Swedish or Finnish sort order.

dbSortTurkish	Use the Turkish sort order.

dbSortUndefined	The sort order is undefined or unknown.

Remarks

These constants are listed in the Data Access (DAO) object library in the Object Browser.

For a Field object, use of the CollatingOrder property depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read only

The CollatingOrder property setting corresponds to the locale argument of the CreateDatabase method when the database was created or the CompactDatabase method when the database was most recently compacted.

Check the CollatingOrder property setting of a Database or Field object to find out the string comparison method for the database or field.  You can set the CollatingOrder property of a new Field object if you want the setting of the Field object to differ from that of the Database object that contains it.

The CollatingOrder and Attributes property settings of a Field object in a Fields collection of an Index object together determine the sequence and direction of the sort order in an index.  However, you can't set a collating order for an individual index [image] only for an entire table.

You can use the setting of the CollatingOrder property as the compare argument in the Visual Basic StrComp and InStr functions.


Connect Property

See Also	Example	Applies to	Specifics

Returns or sets a value that provides information about the source of an open database, a database used in a pass-through query, or an attached table.  For a Database object, this property is read-only.  For a QueryDef object, this property is read/write.  For a TableDef object not yet appended to a collection or for an attached table, this property setting is read/write.  For a base table, this property is read-only.

Syntax

object.Connect = [databasetype;[parameters;]]

The Connect property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

databasetype	A string expression that specifies a database type.  For Jet databases, exclude this argument; if you specify parameters, use a semicolon (;) as a placeholder.  (Data type is String.)

parameters	A string expression that specifies additional parameters to pass to ODBC or installable ISAM drivers.  Use semicolons to separate parameters.  (Data type is String.)

Settings

The Connect property setting is a String composed of a database type specifier and zero or more parameters separated by semicolons.  The Connect property is used to pass additional information to ODBC and certain ISAM drivers as needed.  It isn't used for Jet databases.

For a TableDef object that represents an attached table, the Connect property setting consists of one or two parts (a database type specifier and a path to the database), each of which ends with a semicolon.

The path as shown in the table below is the full path for the directory containing the database files and must be preceded by the identifier "DATABASE=".  In some cases (as with Jet, Btrieve, and Microsoft Excel databases) a specific filename is included in the database path argument.

The following table shows possible database types and their corresponding database specifiers and paths for the Connect property setting:

Database type	Specifier	Path
Database using the Jet database engine	";"	"drive:\path\filename.MDB"
dBASE III	"dBASE III;"	"drive:\path"
dBASE IV	"dBASE IV;"	"drive:\path"
Paradox 3.x	"Paradox 3.x;"	"drive:\path"
Paradox 4.x	"Paradox 4.x;"	"drive:\path"
Btrieve	"Btrieve;"	"drive:\path\filename.DDF"
FoxPro 2.0	"FoxPro 2.0;"	"drive:\path"
FoxPro 2.5	"FoxPro 2.5;"	"drive:\path"
FoxPro 2.6	"FoxPro 2.6;"	"drive:\path"
Excel 3.0	"Excel 3.0;"	"drive:\path\filename.XLS"
Excel 4.0	"Excel 4.0;"	"drive:\path\filename.XLS"
Excel 5.0	"Excel 5.0;"	"drive:\path\filename.XLS"
Text	"Text;"	"drive:\path"
ODBC	"ODBC; DATABASE=defaultdatabase; UID=user; PWD=password; DSN=datasourcename LOGINTIMEOUT=seconds"  (This may not be a complete connection string for all servers; it's just an example.)	None
Remarks

If the specifier is only "ODBC;", a dialog box listing all registered ODBC data source names is displayed by the ODBC driver so the user can select a database.

If a password is required but not provided in the Connect property setting, a login dialog box is displayed the first time a table is accessed by the ODBC driver and again if the connection is closed and reopened.

For Jet database base tables, the Connect property setting is a zero-length string ("").

You can set the Connect property for a Database object by providing a source argument to the OpenDatabase method.  You can check the setting to determine the type, path, user ID, Password, or ODBC data source of the database.

For a QueryDef object, you use the Connect property with the ReturnsRecords property to create an ODBC SQL pass-through query.  The databasetype of the connection string is "ODBC;", and the remainder of the string contains information specific to the ODBC driver used to access the remote data.  For more information, see the documentation for the specific driver.


Container Property (Data Access)

See Also	Example	Applies to	Specifics

Returns the name of the Container object to which a Document object belongs

Syntax

object.Container

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Container property return value is a String value.


Count Property (Data Access)

See Also	Example	Applies to	Specifics

Indicates the number of objects in a collection.

Syntax

collection.Count

The Count property indicates the number of objects in a collection.

Return Value

The Count property returns a Long integer.

Remarks

Members of a collection are numbered starting with 0, so loops are always coded starting with the 0 member; for example:

For I = 0 to Databases.Count - 1

The Count property setting is never Null.  If its value is 0, there are no objects in the collection.


DataUpdatable Property

See Also	Example	Applies to	Specifics

Returns a value that indicates whether the data in the field represented by a Field object is updatable.

Syntax

object.DataUpdatable

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The DataUpdatable property return values are:

Value	Description

True	The data in the field is updatable.

False	The data in the field isn't updatable.

Remarks

Use this property to determine whether you can change the Value property setting of a Field object.


DateCreated, LastUpdated Properties

See Also	Example	Applies to	Specifics

DateCreated [image] returns the date and time the base table underlying an object was created.

LastUpdated [image] returns the date and time of the most recent change made to the design of a base table underlying an object.

Syntax

object.DateCreated

object.LastUpdated

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The DateCreated and LastUpdated return values are Variant of VarType 7 (Date).

Remarks

You can use the DateCreated and LastUpdated properties with Recordset, TableDef, QueryDef, and Document objects.  You can also use these properties with the outdated Table object.

The date and time settings are derived from the computer on which the base table was created or last updated.  In a multiuser environment, users should get these settings directly from the file server to avoid discrepancies in the DateCreated and LastUpdated property settings.


DefaultUser, DefaultPassword Properties

See Also	Example	Applies to	Specifics

Set the user name and password used by the Microsoft Jet database engine when a Workspace object is created without a specific user name and password.

Syntax

object.DefaultPassword = value

object.DefaultUser = value

The DefaultUser and DefaultPassword property syntaxes have these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression containing a valid user name or password.  (Data type is String.)

A user name can be 1-20 characters long and include alphabetic characters, accented characters, numbers, spaces, and symbols except for: " (quotation marks), / (forward slash), \ (backslash), [ ] (brackets), : (colon), | (pipe), < (less-than sign), > (greater-than sign), + (plus sign), = (equal sign), ; (semicolon), , ( comma), ? (question mark), * (asterisk), leading spaces, and control characters (ASCII 00 to ASCII 31).

A password may be up to 14 characters long and may contain any character except ASCII 0.

Remarks

User names aren't usually case-sensitive; however, if you're re-creating a user account that was deleted or created in a different workgroup, the user name must be an exact case-sensitive match of the original name.  User names aren't case-sensitive.

Typically, the CreateWorkspace method is used to create a Workspace object with a given user name and password.  However, for backward compatibility with earlier versions and for convenience when secured databases aren't being used, the Jet engine automatically creates a Workspace object when needed if one isn't already open.  In this case, the DefaultUser and DefaultPassword values are used.

Note   The default UserName and Password properties are unaffected if the Workspace object is referenced before you set the DefaultUser and DefaultPassword properties.

By default, the DefaultUser property is set to admin and the DefaultPassword property is set to a zero-length string ("").

The DefaultUser and DefaultPassword properties are set when you call the outdated SetDefaultWorkspace method.


DefaultValue Property

See Also	Example	Applies to	Specifics

Returns or sets the default value of a Field object.  For a Field object not yet appended to the Fields collection, this property is read/write.  See Remarks for the more specific characteristics of this property.

Syntax

object.DefaultValue [= value]

The DefaultValue property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that can contain a maximum of 255 characters.  It can be either text or an expression.  If the property setting is an expression, it can't contain user-defined functions; Microsoft Jet database engine domain aggregate functions; SQL aggregate functions; or references to queries, forms, or other Field objects.  (Data type is String.)

Remarks

For a Field object, use of the DefaultValue property depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read/write

When a new record is created, the DefaultValue property setting is automatically entered as the value for the field.  You can change the field value by setting its Value property.

The DefaultValue property doesn't apply to Counter and OLE Object fields.


Description Property

See Also	Example	Applies to	Specifics

Returns or sets a descriptive string associated with an error.

Syntax

object.Description [= stringexpression]

The Description property syntax has these parts:

Part	Description

object	Always the Error object.

stringexpression	A string expression containing a description of the error.

Remarks

The Description property comprises a short description of the error.  Use this property to alert the user to an error that you cannot or do not want to handle.  When generating a user-defined error, assign a short description of your error to this property.  If Description is not filled in, and the value of Number corresponds to a Visual Basic run-time error, the string returned by the Error function is placed in Description when the error is generated.


DistinctCount Property

See Also	Example	Applies to	Specifics

Returns a value that indicates the number of unique values for the Index object that are included in the associated table.

Syntax

object.DistinctCount

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The DistinctCount property returns a Long data type.

Remarks

Check the DistinctCount property to determine the number of unique values, or keys, in an index.  Any key is counted only once, even though there may be multiple occurrences of that value if the index permits duplicate values.  This information is useful in applications that attempt to optimize data access by evaluating index information.  The number of unique values is also known as the cardinality of an Index object.

The DistinctCount property won't always reflect the actual number of keys at a particular time.  For example, a change caused by a transaction rollback won't be reflected immediately in the DistinctCount property.


EditMode Property

See Also	Example	Applies to	Specifics

Returns a value that indicates the state of editing for the current record.

Syntax

object.EditMode = value

The EditMode property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An integer that indicates the state of editing, as described in Return Values.  (Data type is Integer.)

Return Values

The EditMode property returns the following values:

Value	Description

dbEditNone	No editing operation is in progress.

dbEditInProgress	Edit method has been invoked, and the current record is in the copy buffer.

dbEditAdd	AddNew method has been invoked, and the current record in the copy buffer is a new record that hasn't been saved in the database.

These constants are listed in the Data Access (DAO) object library in the Object Browser.

Remarks

The EditMode property is most useful when you want to depart from the default functionality of a Data control or if you aren't using a Data control with Visual Basic Professional Edition.  You can check the value of the EditMode property and the value of the action parameter in the Validate event procedure to determine whether to invoke the UpdateRecord method.

You can also check to see if the LockEdits property setting is True and the EditMode property setting is dbEditInProgress to determine whether the current data page is locked.


Fields Property

See Also	Example	Applies to	Specifics

Returns or sets a value indicating which TableDef fields are key fields in an index.  This property is read/write for a new Index object not yet appended to a collection and read-only for an existing Index object in an Indexes collection.

Note   The Fields property is included in this version for compatibility with earlier versions.  It's recommended that you use Field objects in the Fields collection of an Index object instead.  In this case, you create a Field object for each of the key fields and append them to the Fields collection of an Index object to indicate index keys.

Syntax

index.Fields [ = fieldlist[;fieldlist] ]

The Fields property syntax has these parts:

Part	Description

index	An object expression that evaluates to an object in the Applies To list.

fieldlist	A string expression containing a semicolon-delimited (;) list of field names that make up the index.  (Data type is String.)

Remarks

In the list of field names, you can precede a name with a plus sign (+) or a minus sign (-) to indicate ascending (A-Z or 0-100) or descending (Z-A or 100-0) sort order, respectively, for the field.  The default sort order is ascending.  You can enclose field names in brackets ([ ]).  You must use brackets to enclose a field name containing a semicolon.

An Index object can have one or more fields representing index keys for each record.


Filter Property

See Also	Example	Applies to	Specifics

Returns or sets a value that determines records included in a subsequently opened Recordset.

Syntax

object.Filter [= value]

The Filter property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that contains the WHERE clause of an SQL statement without the reserved word WHERE.  (Data type is String.)

Remarks

Use the Filter property to apply a filter to the dynaset- or snapshot-type Recordset object or to the outdated Dynaset and Snapshot objects.

You can use the Filter property to restrict the records returned from an existing object when a new Recordset object is opened based on an existing Recordset.

The following example shows how the Filter property can be used to return only the records for customers who live in a particular region:

MyRecordset.Filter = "[Region] = 'NY'"

Set FilteredRecordset = MyRecordset.OpenRecordset()

Notes

In many cases, it's faster to open a new Recordset object using an SQL statement that includes the filter criteria.

Use the U.S. date format (month-day-year) when you filter fields containing dates, even if you're not using the U.S. version of the Microsoft Jet database engine; otherwise, the data may not be filtered as you expect.  You can use the Format function to make this easier.  For example:

MyDS.Filter = "startdate > #" & Format(mydate, "m/d/yy") & "#"


Foreign Property

See Also	Example	Applies to	Specifics

Returns a value that indicates whether an Index object represents a foreign key in a table.  This property setting is read-only.

Syntax

object.Foreign

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Foreign property return values are:

Value	Description

True	The Index object represents a foreign key.

False	The Index object doesn't represent a foreign key.

Remarks

A foreign key consists of one or more fields in a foreign table that uniquely identify all rows in a primary table.

The Microsoft Jet database engine creates an Index object for the foreign table and sets the Foreign property when you create a relationship that enforces referential integrity.


ForeignName Property

See Also	Example	Applies to	Specifics

Returns or sets a value that, in a relationship, specifies the name of the Field object in a foreign table that corresponds to a field in a primary table.

Syntax

object.ForeignName [= value]

The ForeignName property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that evaluates to the name of a Field in the Database object's TableDefs collection.  (Data type is String.)

Remarks

Only a Field object that belongs to a Fields collection contained by a Relation object can support the ForeignName property.  If the Relation isn't appended to the Database, but the Field is appended to the Relation, you can still change the ForeignName property.  Once the Relation object is appended to the database, the properties of the Field object are read-only.

The Name and ForeignName property value settings for a Field object specify the names of the corresponding fields in the primary and foreign tables of a relationship.  The Table and ForeignTable property value argument settings of a Relation object determine the primary and foreign tables of a relationship.

For example, if you had a list of valid part codes (in a field named PartNo) stored in a ValidParts table, you could establish a relationship with an OrderItem table such that, if a part code was entered into the OrderItem table, it must exist in the ValidParts table.  If the part code did not exist in the ValidParts table and you had not indicated No Enforcement in the Attributes property, a trappable error would occur.

In this case, the ValidParts table would be an example of a Primary table, so the ForeignTable property of the Relation object would be set to OrderItem and the Table property of the Relation object would be set to ValidParts.  The Name property and ForeignName property of the Field object would both be PartNo.


ForeignTable Property

See Also	Example	Applies to	Specifics

Specifies the name of the foreign table in a relationship.  This property setting is read/write for a new Relation object not yet appended to a collection and read-only for an existing Relation object in the Relations collection.

Syntax

object.ForeignTable [= value]

The ForeignTable property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that evaluates to the name of a table in the Database object's TableDefs collection.  (Data type is String.)

Remarks

The ForeignTable property setting of a Relation object is the Name property setting of the TableDef or QueryDef object that represents the foreign table or query; the Table property setting is the Name property setting of the TableDef or QueryDef object that represents the primary table or query.

For example, if you had a list of valid part codes (in a field named PartNo) and stored in a ValidParts table, you could establish a relationship with an OrderItem table such that if a part code was entered into the OrderItem table, it must exist in the ValidParts table.  If the part code did not exist in the ValidParts table and you had not indicated No Enforcement in the Attributes property, a trappable error would occur.

In this case, the ValidParts table would be an example of a foreign table, so the ForeignTable property of the Relation object would be set to ValidParts and the Table property of the Relation object would be set to OrderItem.  The Name property and ForeignName property of the Field object would both be set to PartNo.


HelpContext Property

See Also	Example	Applies to	Specifics

Returns or sets a context ID for a topic in a Microsoft Windows Help file.

Syntax

object.HelpContext [= ContextID]

The HelpContext property syntax has these parts:

Part	Description

object	Always the Error object.

ContextID	A valid identifier for a Help topic within the Help file.

Remarks

If a Microsoft Windows Help file is specified in HelpFile, the HelpContext property is used to automatically display the Help topic it identifies.  If both HelpFile and HelpContext are empty, the value of Number is checked, and, if it corresponds to a Visual Basic run-time error value, then the Visual Basic Help context ID for the error is used.  If the Number value does not correspond to a Visual Basic error, the contents screen for the Visual Basic Help file is displayed.

Note   You should write routines in your application to handle typical errors.  When programming with an object, you can use the Help supplied by the object's Help file to improve the quality of your error handling, or to display a meaningful message to your user if the error is not recoverable.  When writing OLE Automation objects, you should tailor your Help to programmers programming with your object, as well as supply meaningful information to an end user for an unrecoverable error.


HelpFile Property

See Also	Example	Applies to	Specifics

Returns or sets a fully qualified path to a Microsoft Windows Help file.

Syntax

object.HelpFile [= pathspec]

The HelpFile property syntax has these parts:

Part	Description

object	Always the Error object.

pathspec	Fully qualified path to the Help file.

Remarks

If a Microsoft Windows Help file is specified in HelpFile, it is automatically called when the user presses the Help button (or the F1 key) in the error message dialog box.  If the HelpContext property contains a valid context ID for the specified file, that topic is automatically displayed.  If no HelpFile is specified, then the Visual Basic Help file is displayed.

Note   You should write routines in your application to handle typical errors.  When programming with an object, you can use the Help supplied by the object's Help file to improve the quality of your error handling, or to display a meaningful message to your user if the error is not recoverable.  When writing OLE Automation objects, you should tailor your Help to programmers programming with your object, as well as supply meaningful information to an end user for an unrecoverable error.


IgnoreNulls Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether there are index entries for records that have Null values in their index fields.  This property setting is read/write for a new Index object not yet appended to a collection and read-only for an existing Index object in an Indexes collection.

Syntax

object.IgnoreNulls [= value]

The IgnoreNulls property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates index entries, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	Fields with Null values don't have an index entry.

False	Fields with Null values have an index entry.

Remarks

To make searching for records using a field faster, you can define an index for the field.  If you allow Null entries in an indexed field and expect many of the entries to be Null, you can set the IgnoreNulls property for the Index object to True to reduce the amount of storage space that the index uses.

The IgnoreNulls property setting and the Required property setting together determine whether a record with a Null index value has an index entry, as the following table shows.

IgnoreNulls	Required	Null in index field

True	False	Null value allowed; no index entry added.

False	False	Null value allowed; index entry added.

True or False	True	Null value not allowed; no index entry added.


Index Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates the name of the current Index object in a table-type Recordset.

Syntax

object.Index [ = indexname ]

The Index property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

indexname	A string expression that evaluates to the name of an Index object in the Indexes collection of the Table or table-type Recordset object's TableDef.  (Data type is String.)

Remarks

Records in base tables aren't stored in any particular order.  Setting the Index property changes the order of records returned from the database; it doesn't affect the order in which the records are stored.

For example, to set the Index property prior to using the Seek method on the Titles table:

Dim Tb as Recordset, Db as Database

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Set Tb = Db.OpenRecordset("Titles",dbTable)

Tb.Index = "PubID"

Tb.Seek "=", 3

The specified Index object must already be defined.  If you set the Index property to an Index object that doesn't exist or if the Index property isn't set when you use the Seek method, a trappable error occurs.

Examine the Indexes collection of a TableDef object to determine what Index objects are available to table-type Recordset objects created from that TableDef.

You can create a new index for the table by creating a new Index object, setting its properties, appending it to the Indexes collection of the underlying TableDef, and then reopening the Recordset.

Records returned from a Table object can be ordered only by the indexes defined for the underlying TableDef.  To sort records in some other order, you can open a dynaset- or snapshot-type Recordset using an SQL statement with an ORDER BY clause.

The Index property of an element of a control array isn't the same as the Index property of a data access object.

Tips

You don't have to create indexes for tables, but in large, unindexed tables, accessing a specific record or creating a  Recordset can take a long time.  On the other hand, creating too many indexes slows down update, append, and delete operations as all indexes are automatically updated.

Records read from tables without indexes are returned in no particular sequence.

The Attributes property of each Field object in the Index object determines the order of records and consequently determines the access techniques to use for that index.

A unique index helps optimize finding records.

Indexes don't affect the physical order of a base table [image] indexes only affect how the records are accessed by the Table object when a particular index is chosen or when the Microsoft Jet database engine creates Recordset objects.


Inherit Property

See Also	Example	Applies to	Specifics

Determines whether new Docoument objects will inherit a default Permissions property setting.

Syntax

object.Inherit

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Inherit property return value is a Boolean value.

Remarks

Use the Inherit property in conjunction with the Permissions property to define what permissions new documents will automatically be given when they're created. If you set the Inherit property to True, and then set a permission on a container, then whenever a new document is created in that container, that permission will be set on the new document. This is a very convenient way of presetting permissions on an object.

Setting the Inherit property will not affect existing documents in the container - you can't modify all the permissions on all existing documents in a container by setting the Inherit property and a new permission.  It will only affect new documents that are created after Inherit is set..


Inherited Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether a Property object is inherited from an underlying object.  This property setting is read-only.

Syntax

object.Inherited

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Inherited property return values are:

Value	Description

True	The Property object is inherited.

False	The Property object isn't inherited.  For built-in Property objects that represent predefined properties, False is the only setting.

Remarks

You can use the Inherited property to determine whether a user-defined property was created for the object it applies to or whether the property was created for another object.  For example, suppose you create a property for a QueryDef object and then open a Recordset object from the QueryDef.  This property will be part of the Recordset object's Properties collection, and its Inherited property will be set to True because the property was created for the QueryDef, not the Recordset.


IniPath Property

See Also	Example	Applies to	Specifics

Returns or sets the full path and filename of the Microsoft Jet database engine initialization (.INI) file.

Syntax

object.IniPath [= value]

The IniPath property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that points to a user-supplied ASCII file containing Jet engine settings or parameters needed for installable ISAM databases.  (Data type is String.)

Remarks

The Jet engine can be configured with a user-provided initialization file.  You can use the initialization file settings to set options, such as page timeout and maximum buffer size.

You also use this file to provide initialization parameters for some installable ISAM database drivers.  For example, to use Paradox version 4.0, set the IniPath property to an initialization file containing the appropriate parameters.

Jet engine initialization is handled differently in 16- and 32-bit systems:

16-bit [image] For this option to have any effect, the IniPath property must be set before any other data access functions are invoked by any application in the system.  If the Jet engine is already initialized, a trappable error occurs.  The scope of this setting is public to the system and once set, can't be changed without restarting all programs that are using the Jet engine.

32-bit [image] For this option to have any effect, the IniPath property must be set before any other data access functions are invoked by your application.  If the Jet engine is already initialized, a trappable error occurs.  The scope of this setting is limited to your application and can't be changed without restarting your application.

Microsoft Access version 1.1 doesn't use the same version of the Jet engine as Visual Basic version 4.0.  However, other applications using the Jet engine version 2.5 will initialize the engine.

The IniPath property replaces the outdated SetDataAccessOption parameter DB_OPTIONINIPATH used in Visual Basic version 3.0.


IsolateODBCTrans Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether multiple transactions that involve the same ODBC database are isolated.

Syntax

object.IsolateODBCTrans [= value]

The IsolateODBCTrans property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates whether transactions are isolated, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	Isolate transactions involving the same ODBC database.

False	(Default) Don't isolate transactions involving the same ODBC database.

Remarks

In some situations, you need to have multiple simultaneous transactions pending on the same ODBC database.  To do this, you need to open a separate Workspace for each transaction.  Although each Workspace can have its own ODBC connection to the database, this slows system performance.  Because transaction isolation isn't normally required, ODBC connections from multiple Workspace objects opened by the same user are shared by default.

Some ODBC servers, such as Microsoft SQL Server, don't allow simultaneous transactions on a single connection.  If you need to have more than one transaction at a time pending against such a database, set the IsolateODBCTrans property to True on each Workspace as soon as you open it.  This forces a separate ODBC connection for each Workspace.


LastModified Property

See Also	Example	Applies to	Specifics

Returns a bookmark indicating the most recently added or changed record.

Syntax

object.LastModified

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The return value for this property is a Variant or String data type.  You can use LastModified to move to the most recently added or updated record.

Use the LastModified property with Recordset objects and with the outdated Dynaset, Snapshot, and Table objects.


LockEdits Property

See Also	Example	Applies to	Specifics

Returns a value indicating the locking that is in effect during editing.

Syntax

object.LockEdits [= value]

The LockEdits property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates the type of locking, as described in Settings. (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	(Default) Pessimistic locking is in effect.  The 2K page containing the record you're editing is locked as soon as you use the Edit method.  The page is unlocked when you use the Update or Close method or any of the Move or Find methods.

False	Optimistic locking is in effect for editing.  The 2K page containing the record is locked only while the record is being updated with the Update method.

Remarks

You can use the LockEdits property with dynaset- and table-type Recordset objects and with the outdated Dynaset and Table objects.

If a page is locked, no other user can edit records on the same page.  If you set LockEdits to True and another user already has the page locked, an error occurs when you use the Edit method.  Other users can read data from locked pages.

If you set LockEdits to False and later use Update while the page is locked by another user, an error occurs.  To see the changes made to your record by another user (and lose your changes), set the Bookmark property of your Recordset object to itself.

When working with ODBC data sources, LockEdits is always set to False (optimistic locking).  The Microsoft Jet database engine has no control over the locking mechanisms used in external database servers.


LoginTimeout property

See Also	Example	Applies to	Specifics

Returns or sets the number of seconds before an error occurs when you attempt to log in to an ODBC database.

Syntax

object.LoginTimeout [= value]

The LoginTimeout property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An Integer representing the number of seconds before a login timeout error occurs.  The default LoginTimeout setting is 20 seconds.  When LoginTimeout is set to 0, no timeout occurs.

Remarks

When you're attempting to log in to an ODBC database, such as SQL Server, the connection may fail as a result of network errors or because the server isn't running.  Rather than waiting for the default 20 seconds to connect, you can specify how long the Microsoft Jet database engine waits before it produces an error.  Logging on to the server happens implicitly as part of a number of different events, such as running a query on an external server database.

The timeout value is determined by the current setting of the LoginTimeout property in the [ODBC] section of the application initialization (.INI) file.


LogMessages Property

See Also	Example	Applies to	Specifics

Sets a value that specifies if the messages returned from an ODBC database are recorded.  This property is user-defined and is read/write once created and installed.

Note   The user must install this property using the CreateProperty method on a QueryDef object.

Syntax

object.LogMessages [= value]

The LogMessages property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that specifies whether messages are recorded, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	ODBC-generated messages are recorded.

False	ODBC-generated messages aren't recorded.

Remarks

Some pass-through queries can return messages in addition to data.  If you set the LogMessages property to True, the Microsoft Jet database engine creates a table that contains returned messages.  The table name is the user name concatenated with a hyphen (-) and a sequential number starting at 00.  For example, because the default user name is ADMIN, the tables returned would be named ADMIN-00, ADMIN-01, and so on.

If you expect the query to return messages, create and append a user-defined LogMessages property for the QueryDef, and set its type to BOOLEAN and its value to True.

Once you've processed the results from these tables, you may want to delete them from the database along with the temporary query used to create them.

The LogMessages property setting must be defined as dbBoolean (Boolean) when created.


Name Property (Data Access)

See Also	Example	Applies to	Specifics

Returns or sets a user-defined name for a data access object.  For an object not appended to a collection, this property is read/write.  See Remarks for the more specific read/write characteristics of this property.

Syntax

object.Name [= value]

The Name property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that specifies a name.  The name must start with a letter and can contain a maximum of 40 characters.  It can include numbers and underscore characters but can't include punctuation or spaces.  (Data type is String.)

Remarks

TableDef and QueryDef objects can't share the same name, nor can User and Group objects.

The Name property of a Recordset object opened using an SQL statement is the first 256 characters of the SQL statement.

You can use an object's Name property with the Dim statement in code to create other instances of the object.

Note   For many of the Database objects, the Name property reflects the name as known to the Database, as in the name of a Table, Field, or QueryDef.  There is no direct link between the name of the Database object and the object variable used to reference it.  The name of the Dynaset or Snapshot is either the Name property of a Table or QueryDef used to create it, or the SQL statement used to create it.

The read/write usage of the Name property depends on the type of object it applies to.

Object	Usage

Container	Read-only

Database	Read-only

Document	Read-only

Field	Read/write

  Index.Field	Read-only

  QueryDef.Field	Read-only

  Recordset.Field	Read-only

  TableDef.Field	Read-only

  Relation.Field	Read-only

Group	Read/write

Index	Read/write

  Recordset.Index	Read-only

Parameter	Read-only

Property (built-in)	Read-only

Property (user-defined)	Read/write

QueryDef	Read/write

Recordset	Read-only

Relation	Read/write

TableDef (native)	Read/write

TableDef (attached)	Read/write

User	Read/write

Workspace	Read/write


NoMatch Property

See Also	Example	Applies to	Specifics

Returns a value indicating whether a particular record was found using the Seek method or one of the Find methods.

Syntax

object.NoMatch

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The NoMatch property return values are:

Value	Description

True	The desired record wasn't found.

False	The desired record was found.

Remarks

You can use the NoMatch property with Recordset objects and with the outdated Dynaset, Snapshot, and Table objects.

When you open or create a Recordset object, its NoMatch property is set to False.

To locate a record, use the Seek method on a table-type Recordset or Table object or one of the Find methods on a dynaset- or snapshot-type Recordset, Dynaset, or Snapshot object.  Check the NoMatch property setting to see whether the record was found.

If the Seek or Find operation is unsuccessful and NoMatch is True, the current record will no longer be valid.  Be sure to obtain the current record's bookmark before using the Seek method or a Find method if you'll need to return to that record.

Note   Using any of the Move methods on a Recordset object won't affect its NoMatch property setting.


Number Property

See Also	Example	Applies to	Specifics

Returns or sets a numeric value specifying an error.  Number is the Error object's default property.

Syntax

object.Number [= errornumber]

The Number property syntax has these parts:

Part	Description

object	Always the Error object.

errornumber	A Long integer representing an error number.

Remarks


ODBCTimeout Property

See Also	Example	Applies to	Specifics

Returns or sets the number of seconds the Microsoft Jet database engine waits before a timeout error occurs when a query is run on an ODBC database.

Syntax

object.ODBCTimeout [= value]

The ODBCTimeout property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An integer representing the number of seconds the Jet engine waits before a timeout error occurs.  (Data type is Integer.)

Remarks

When you're using an ODBC database, such as SQL Server, there may be delays because of network traffic or heavy use of the ODBC server.  Rather than waiting indefinitely, you can specify how long the Jet engine waits before it produces an error.

The default timeout value is 60 seconds.  The QueryTimeout property setting for a Database object overrides the default setting.

Setting the ODBCTimeout property of a QueryDef object overrides the values specified by the QueryTimeout property setting of the Database containing the QueryDef, but only for that QueryDef.

When ODBCTimeout is set to 0, no timeout occurs.


OrdinalPosition Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies the numeric order in which you want a field represented by a Field object to be displayed relative to other fields.  For an object not yet appended to the Fields collection, this property is read/write.  See Remarks for the more specific read/write characteristics of this property.

Syntax

object.OrdinalPosition [= value]

The OrdinalPosition property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An integer that specifies the numeric order of fields.  The default is 0.  (Data type is Integer.)

Remarks

For a Field object, use of the OrdinalPosition property depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read/write

Generally, the ordinal position of an object that you append to a collection depends on the order in which you append the object.  The first appended object is in the first position (0), the second appended object is in the second position (1), and so on.  The last appended object is in ordinal position count - 1, where count - 1 is the number of objects in the collection as specified by the Count property setting.

Using the OrdinalPosition property, you can specify an ordinal position for new Field objects that differs from the order in which you append those objects to a collection.  This enables you to specify a field order for your tables, queries, and recordsets when you use them in an application.  For example, the order in which fields are returned in a SELECT * query would be determined by the current OrdinalPosition values.

You can permanently reset the order in which fields are returned in recordsets by setting the OrdinalPosition property.  The Microsoft Jet database engine accepts any positive integer for the OrdinalPosition property; however, if you specify:

A number that is already assigned to another field, the two fields are ordered alphabetically.  For example, if you have a field named Age set to 4 and you set a second field named Weight to 4, Weight is returned after Age.

A number that is greater than the number of fields -1, the field is returned in an order relative to the largest number.  For example, if you set a field's OrdinalPosition property to 20 (and there are only 5 fields) and you've set the OrdinalPosition property for two other fields to 10 and 30, respectively, the field set to 20 is returned between the fields set to 10 and 30.

A negative number, a trappable error occurs.

After you change the OrdinalPosition property setting, you can use the property to return the current setting.  However, the fields aren't reordered until the Fields collection is repopulated.  For example:

TableDefs("Titles").Fields(0).OrdinalPosition = 3

This code changes which Field object is referenced in the fourth position (0 relative).  Because Field(0) was Title, Field(2) now refers to Title, and Field(0) refers to the first (lowest) field in the sequence.

It is far clearer to reference Field objects by their Name property.  For example, this code assigns the AU_ID field to the third field position:

TableDefs("Titles").Fields("AU_ID").OrdinalPosition = 2

Note   After you change the OrdinalPosition property setting of an object in the Fields collection, you may need to use the Refresh method on the collection before the new property setting takes effect.


Owner Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies the owner of the object.

Syntax

object.Owner [= value]

The Owner property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that evaluates to either the name of a User object in the Users collection or the name of a Group object in the Groups collection.  (Data type is String.)

Remarks

The owner of an object has certain access privileges denied to other users.  The Owner property setting can be changed at any time by any individual user account (represented by a User object) or group of user accounts (represented by a Group object) having the appropriate permissions.


Password Property

See Also	Example	Applies to	Specifics

Sets the password for either a user account or a session of the database engine.  This property setting is write-only for new objects not yet appended to a collection, and it's not available for existing objects.

Syntax

object.Password [= value]

The Password property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that can be up to 14 characters long and can include any characters except the ASCII character 0 (null).  (Data type is String.)

Remarks

Set the Password property along with the PID property when you create a new User object.  Set it along with the UserName property when you create a new Workspace object.

Use the NewPassword method to change the Password property setting for an existing User object.  To clear a password, set the newpassword argument of the NewPassword method to a zero-length string ("").

Passwords are case-sensitive.

Note   If you don't have access permission, you can't change the password of any other user.


PercentPosition Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates or changes the approximate location of the current record in the Recordset object based on a percentage of the records in the Recordset.

Syntax

object.PercentPosition [= value]

The PercentPosition property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A number between 0.0 and 100.00.  (Data type is Single.)

Remarks

To indicate or change the approximate position of the current record in a Recordset, you can check or set the PercentPosition property.  When working with a dynaset- or snapshot-type Recordset, first populate the Recordset by moving to the last record before you set or check the PercentPosition property.  If you use the PercentPosition property before fully populating the Recordset, the amount of movement is relative to the number of records accessed as indicated by the RecordCount property setting.  You can move to the last record using the MoveLast or FindLast method.

Note Using the PercentPosition property to move the current record to a specific record in a Recordset isn't recommended [image] the Bookmark property or AbsolutePosition property is better suited for this task.

Once you set the PercentPosition property to a value, the record at the approximate position corresponding to that value becomes current, and the PercentPosition property is reset to a value that reflects the approximate position of the current record.  For example, if your Recordset contains only five records, and you set its PercentPosition value to 77, the value returned from the PercentPosition property may be 80, not 77.

The PercentPosition property applies to all three types of Recordset objects (except for forward-only scrolling snapshots).  However, the PercentPosition property of a table-type Recordset always returns 50 if you haven't set the Index property of the Recordset to a valid value.  The PercentPosition property doesn't work with the outdated Dynaset, Snapshot, and Table objects.

You can use the PercentPosition property with a scroll bar on a form or text box to indicate the location of the current record in a Recordset.


Permissions Property

See Also	Example	Applies to	Specifics

Returns or sets a value that establishes the permissions for the user or group identified by the UserName property of the Container or Document object.

Syntax

object.Permissions [= value]

The Permissions property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A constant that establishes permissions, as described in Settings.

Settings

For any Container or Document object, the settings for value are:

Constant	Description

dbSecNoAccess	No access to the object.

dbSecFullAccess	Full access to the object.

dbSecDelete	Can delete the object.

dbSecReadSec	Can read the object's security-related information.

dbSecWriteSec	Can alter access permissions.

dbSecWriteOwner	Can change the Owner property setting.

For the Tables Container or any Document in a Documents collection, the settings for value are:

Constant	Description

dbSecCreate	Can create new documents (valid only with a Container object).

dbSecReadDef	Can read the table definition including column and index information.

dbSecWriteDef	Can modify or delete the table definition including column and index information.

dbSecRetrieveData	Can retrieve data from the Document.

dbSecInsertData	Can add records.

dbSecReplaceData	Can modify records.

dbSecDeleteData	Can delete records.

For the Databases Container object or any Document object in a Documents collection, the settings for value are:

Constant	User or group

dbSecDBCreate	Can create new databases (valid only on the databases Container object in the system database [SYSTEM.MDA]) .

dbSecDBExclusive	Exclusive access.

dbSecDBOpen	Can open the database.

Remarks

These constants are listed in the Data Access (DAO) object library in the Object Browser.

Use this property to establish or determine the type of read/write/modify permissions the user specified by the UserName property has for a Container or Document object.

A Document object inherits the permissions for users from its Container, provided the Inherited property of the Container is set for those users or for a group to which the users belong.  By setting a Document object's Permissions and UserName properties later, you can further refine the access control behavior of your object.


PID Property

See Also	Example	Applies to	Specifics

Sets the personal identifier (PID) for either a group or a user account.  This property setting is write-only for new objects not yet appended to a collection, and it's not available for existing objects.

Syntax

object.PID = [value]

The PID property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression containing 4-20 alphanumeric characters.  (Data type is String.)

Remarks

Set the PID property along with the Name property when you create a new Group object.  Set the PID property along with the Name and Password properties when you create a new User object.


Primary Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether an Index object represents a primary index for a table.  The Primary property setting is read/write for a new Index object not yet appended to a collection and read-only for an existing Index object in an Indexes collection.  If the Index object is appended to the TableDef but the TableDef isn't appended to the TableDefs collection, the Index property is read-write.

Syntax

object.Primary [= value]

The Primary property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that specifies a primary index, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	The Index object represents a primary index.

False	The Index object doesn't represent a primary index.

Remarks

A primary index consists of one or more fields that uniquely identify all records in a table in a predefined order.  Because the index field must be unique, the Unique property of the Index object is set to True.  If the primary index consists of more than one field, each field can contain duplicate values, but each combination of values from all the indexed fields must be unique.  A primary index consists of a key for the table and usually contains the same fields as the primary key.

Tip   You don't have to create indexes for tables, but in large, unindexed tables, accessing a specific record can take a long time.  The Attributes property of each Field object in the Index determines the order of records and consequently determines the access techniques to use for that index.  When you create a new table in your database, it's a good idea to create an index on one or more fields that uniquely identify each record, and then set the Primary property of the Index object to True.

When you set a primary key for a table, the primary key is automatically defined as the primary index for the table.


QueryTimeout Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies the number of seconds the Microsoft Jet database engine waits before a timeout error occurs when a query is executed on an ODBC database.

Syntax

object.QueryTimeout [= value]

The QueryTimeout property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An integer representing the number of seconds the Jet database engine waits before timing out and returning an error.  (Data type is Integer.)

Remarks

When you're using an ODBC database, such as SQL Server, there may be delays due to network traffic or heavy use of the ODBC server.  Rather than waiting indefinitely, you can specify how long to wait before the Jet engine produces an error.

When used with a Database object, the QueryTimeout property specifies a global value for all queries associated with the database.

The default timeout value is always 60 seconds, regardless of any .INI file settings.  The setting of QueryTimeout on a Database object overrides the default value.


RecordCount Property

See Also	Example	Applies to	Specifics

Returns the number of records accessed in a Recordset or TableDef object.  This property setting is read-only.

Syntax

object.RecordCount

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The RecordCount property return value is a Long integer.

Remarks

Use the RecordCount property to find out how many records in a Recordset or TableDef object have been accessed.  RecordCount doesn't indicate how many records are contained in a dynaset- or snapshot-type Recordset until all records have been accessed.

Once the last record has been accessed, the RecordCount property indicates the total number of undeleted records in the Recordset or TableDef.  To force the last record to be accessed, use the MoveLast or FindLast method on the Recordset.  You can also use an SQL Count function to determine the approximate number of records your query will return.

As your application deletes records in a dynaset-type Recordset or Dynaset object, the value of RecordCount decreases.  However, records deleted by other users aren't reflected by RecordCount until the current record is positioned to a deleted record.  If you execute a transaction that affects the RecordCount property setting and subsequently rolls back the transaction, RecordCount won't reflect the actual number of remaining records.

The RecordCount property of a snapshot-type Recordset or Snapshot object isn't affected by changes in the underlying tables.

The RecordCount property of a table-type Recordset, Table, or TableDef object always reflects the number of records in the table and is affected immediately as table records are added and deleted by all users.

A Recordset or TableDef with no records has a RecordCount property setting of 0.

When working with attached tables or ODBC databases, the RecordCount property setting is always -1.

Using the Requery method on a Recordset resets the RecordCount property just as if the query were re-executed.


RecordsAffected Property

See Also	Example	Applies to	Specifics

Returns the number of records affected by the most recently invoked Execute method.

Syntax

object.RecordsAffected

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The RecordsAffected property return value is an integer from 0 to the number of records affected by the most recently invoked Execute method on either a Database or QueryDef object.  (Data type is Long.)

Remarks

RecordsAffected contains the number of records deleted, updated, or inserted when running an action query.  When you use the Execute method to run a QueryDef, the RecordsAffected property setting is the number of records affected.

Note   The RecordsAffected property setting is the same as the value returned by the ExecuteSQL method.


Required Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether a Field or Index object requires a non-Null value.  For an object not yet appended to a collection, this property is read/write.  For an Index object, this property setting is read-only for objects appended to Indexes collections in Recordset and TableDef objects.  See Remarks for the more specific read/write characteristics of this property.

Syntax

object.Required [= value]

The Required property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression indicating whether an object requires a non-Null value, as described in Settings.

Settings

The settings for value are:

Setting	Description

True	A Null value isn't allowed.

False	A Null value is allowed.

Remarks

For a Field object, use of the Required property depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read/write

For a Field object, you can use the Required property along with the AllowZeroLength, ValidateOnSet, or ValidationRule property to determine the validity of the Value property setting for that Field object.  If Required is set to False, the field can contain Null values as well as values that meet the conditions specified by the AllowZeroLength and ValidationRule property settings.

Tip   When you can set this property for either an Index object or a Field object, set it for the Field object.  The validity of the property setting for a Field object is checked before that of an Index object.


Restartable Property

See Also	Example	Applies to	Specifics

Returns a value that indicates whether a Recordset object supports the Requery method, which re-executes the query on which the Recordset is based.

Syntax

object.Restartable

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Restartable property return values are:

Value	Description

True	The Recordset supports the Requery method.

False	The Recordset doesn't support the Requery method.  This is the only setting for table-type Recordset objects.

Remarks

Check the Restartable property before using the Requery method on a Recordset.  If the object's Restartable property is set to False, use the OpenRecordset method on the underlying QueryDef to re-execute the query.

You can use the Requery method to update a Recordset object's underlying parameter query after the parameter values have been changed.


ReturnsRecords Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether an SQL pass-through query to an external database returns records.

Syntax

object.ReturnsRecords [= value]

The ReturnsRecords property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates whether records are returned, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	(Default) The pass-through query returns records.

False	The pass-through query doesn't return records.

Remarks

Not all SQL pass-through queries to external databases return records.  For example, an SQL UPDATE statement updates records without returning records, while an SQL SELECT statement does return records.  If the query returns records, set ReturnsRecords to True; if the query doesn't return records, set ReturnsRecords to False.


Size Property (Data Access)

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates the maximum size, in bytes, of a Field object that contains text or the fixed size of a Field object that contains text or numeric values.  For an object not yet appended to the Fields collection, this property is read/write.

Syntax

object.Size [= value]

The Size property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A constant or value indicating the maximum size, as described in Settings.  (Data type is Integer.)

Settings

The setting for value depends on the Type property setting of the Field object and can be one of these integer values:

Setting	Value	Description

dbBoolean	1	Boolean

dbByte	1	Byte

dbInteger	2	Integer

dbLong	4	Long

dbCurrency	8	Currency

dbSingle	4	Single

dbDouble	8	Double

dbDate	8	Date/Time

dbText	1-255	Text

dbLongBinary	0	Long Binary (OLE Object)

dbMemo	0	Memo

Remarks

These constants are listed in the Data Access (DAO) object library in the Object Browser.

For a Field object, use of the Size property depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read-only

When you create a Field object with a data type other than Text, the Type property setting automatically determines the Size property setting, and you don't need to set the Size property.  For OLE Object and Memo Field objects, Size is always set to 0.  For a Field object with the Text data type, Size can be set to any integer up to 255 where the Size property sets the maximum size for the Field.

For OLE Object and Memo Field objects, use the FieldSize method of the Field object to determine the size of the data in a specific record.  The maximum size of an OLE Object or Memo field is limited only by your system resources or the maximum size of the database.


Sort property

See Also	Example	Applies to	Specifics

Returns or sets the sort order for records in a Recordset object.

Syntax

object.Sort [= value]

The Sort property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that contains the ORDER BY clause of an SQL statement without the reserved words ORDER BY.  (Data type is String.)

Remarks

You can use the Sort property with dynaset- and snapshot-type Recordset objects and with the outdated Dynaset and Snapshot objects.

When you set this property for an object, sorting occurs when a subsequent Recordset is created from that object.  The Sort property setting overrides any sort order specified for a QueryDef object.

The default sort order is ascending (A-Z or 0-100).  The following examples show how you can set the sort order to ascending or descending (Z-A or 100-0):

MySet.Sort = "[Ship Country]"	' Defaults to ascending.

MySet.Sort = "[Ship Country] Asc"

MySet.Sort = "[Ship Country] Desc"

The Sort property doesn't apply to table-type Recordset objects.  To sort a table-type Recordset, use the Index property.

Tip   In many cases, it's faster to open a new Recordset using an SQL statement that includes the sorting criteria.


Source Property

See Also	Example	Applies to	Specifics

Returns or sets the name of the object or application that originally generated the error.

Syntax

object.Source [= stringexpression]

The Source property syntax has these parts:

Part	Description

object	Always the Error object.

stringexpression	A string expression representing the application that generated the error.

Remarks

The Source property specifies a string expression representing the object that originally generated the error; the expression is usually the object's class name or programmatic ID.  Use Source to provide your users with information when your code is unable to handle an error generated in an accessed object.  For example, if you access Microsoft Excel and it generates a Division by zero error, Microsoft Excel sets Error.Number to its error code for that error and sets Source to Excel.Application.  Note that if the error is generated in another object called by Microsoft Excel, Microsoft Excel intercepts the error and sets Error.Number to its own code for Division by zero.  However, it leaves the other Error object properties (including Source) as set by the object that generated the error.  Source always contains the name of the object that originally generated the error [image] your code can try to handle the error according to the error documentation of the object you accessed.  If your error handler fails, you can use the Error object information to describe the error to your user, using Source and the other Error properties to inform the user which object originally caused the error, its description of the error, and so forth.

When generating an error from code, Source is your applications programmatic ID.  For OLE Automation class modules, Source should contain a name having the form project.class.

Note   The On Error Resume Next construct may be preferable to On Error GoTo when dealing with errors generated during access to other objects.  Checking Err after each interaction with an object removes ambiguity about which object your code was accessing when the error occurred.  Thus, you can be sure which object placed the error code in Err.Number, as well as which object originally generated the error (the one specified in Error.Source).


SourceField, SourceTable Properties

See Also	Example	Applies to	Specifics

SourceField [image] returns a value that indicates the name of the field that is the original source of the data for a Field object.

SourceTable [image] returns a value that indicates the name of the table that is the original source of the data for a Field object.

This property is not available at design time and is read-only at runtime.

Syntax

object.SourceField [= value]

object.SourceTable [= value]

The SourceField and SourceTable property syntaxes have these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression specifying the name of the field or table that is the source of data.  (Data type is String.)

Remarks

For a Field object, use of the SourceField and SourceTable properties depends on the object that contains the Fields collection that the Field object is appended to, as shown in the following table.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read-only

These properties indicate the original field and table names associated with a Field object.  For example, you could use these properties to determine the original source of the data in a query field whose name is unrelated to the name of the field in the underlying table.


SourceTableName Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies the name of an attached table or the name of the base table on which the query is based as it exists in the original source of the data.  This property setting is read-only for a base table and read/write for an attached table or an object not appended to a collection.

Syntax

object.SourceTableName [= value]

The SourceTableName property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that specifies a table name.  For a base table, the setting is a zero-length string ("").  (Data type is String.)


SQL Property

See Also	Example	Applies to	Specifics

Returns or sets the SQL statement that defines the query executed by a QueryDef object.

Syntax

object.SQL [= value]

The SQL property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that contains an SQL statement.  (Data type is String.)

Remarks

The SQL property contains the SQL statement that determines how records are selected, grouped, and ordered when you execute the query.  You can use the query to select records to include in a dynaset- or snapshot-type Recordset object or in a Dynaset or Snapshot object.  You can also define bulk queries to modify data without returning records.

Using the ORDER BY or WHERE clause to sort or filter a Recordset is more efficient than using the Sort and Filter properties.

The SQL syntax used in a query must conform to the SQL dialect as defined by the Microsoft Jet database engine unless you create an SQL pass-through query.

Using a QueryDef object is the preferred way to perform SQL pass-through operations on ODBC databases.  By setting the QueryDef object's Connect property to an ODBC data source, you can specify non-Microsoft Jet database SQL in the query passed to the external server.  For example, you can use TRANSACT SQL statements (with Microsoft SQL Server or Sybase SQL Server databases) in the value argument, which won't be processed by the Jet engine.

If the SQL statement includes parameters for the query, you must set these before you execute the query.  Until you reset the parameters, the same parameter values are applied each time you execute the query. Set the parameters by accessing the Parameters collection of the QueryDef object using the following code:

MyQuery.Parameters("Order Date") = "10/11/94"   ' Set parameters.

MyQuery.Parameters("Ship Date") = "11/4/94"


Table Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies the name of a Relation object's primary table.  This name is the Name property setting of a TableDef or QueryDef object.  The Table property setting is read/write for a new Relation object not yet appended to a collection and read-only for an existing Relation object in a Relations collection.

Syntax

object.Table [= value]

The Table property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that evaluates to the name of a table in the TableDefs collection.  (Data type is String.)

Remarks

Use the Table property with the ForeignTable property to define a Relation object, which represents the relationship between fields in two tables or queries.  Set the Table property to the Name property setting of the primary TableDef or QueryDef object, and set the ForeignTable property to the Name property setting of the foreign (referencing) TableDef or QueryDef object.  The Attributes property determines the type of relationship between the two objects.

For example, if you had a list of valid part codes (in a field named PartNo) and stored in a ValidParts table, you could establish a relationship with an OrderItem table such that if a part code was entered into the OrderItem table, it must exist in the ValidParts table.  If the part code didn't exist in the ValidParts table and you had not indicated No Enforcement in the Attributes property, a trappable error would occur.

In this case, the ValidParts table is an example of a foreign table, so the ForeignTable property of the Relation object would be set to ValidParts and the Table property of the Relation object would be set to OrderItem.  The Name property and ForeignName property of the Field object would both be set to Part Number.

The picture shown below illustrates how the ValidParts table is primary because it's referenced by the OrderItem table.


Transactions Property

See Also	Example	Applies to	Specifics

Returns a value that indicates whether an object supports the recording of a series of changes that can later be rolled back (canceled) or committed (saved).

Syntax

object.Transactions

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Transactions property return values are:

Value	Description

True	The object supports transactions.

False	The object doesn't support transactions.  This is the only value returned for snapshot-type Recordset objects.

Remarks

You can use the Transactions property with dynaset- or snapshot-type Recordset objects and with the outdated Dynaset and Table objects.

If a dynaset or table is based on a Microsoft Jet database engine table, the Transactions property is True and you can use transactions.  Other database engines may not support transactions.  For example, you can't use transactions in a dynaset-type Recordset based on a Paradox table.

Check the Transactions property before using the BeginTrans method on the Recordset object's Workspace object to make sure that transactions are supported.  Using the BeginTrans, CommitTrans, or Rollback methods on a nonsupported object has no effect.


Type Property (Data Access)

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates the operational type or data type of an object.  For a Field or Property object, this property setting is read/write until the object is appended to a collection or to another object, after which it's read-only.  For a Parameter, QueryDef, or Recordset object, the property setting is read-only.

Syntax

object.Type [= value]

The Type property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A constant that indicates an operational or data type, as described in Settings.  (Data type is Integer.)

Settings

For a Field, Parameter, or Property object, the settings for value are:

Setting	Description

dbDate	Date/Time

dbText	Text

dbMemo	Memo

dbBoolean	Yes/No

dbInteger	Integer

dbLong	Long

dbCurrency	Currency

dbSingle	Single

dbDouble	Double

dbByte	Byte

dbLongBinary	Long Binary (OLE Object)

Note   A Long Binary data type is the same as a String.  However, it's recommended that you use the Variant data type instead of  Long Binary (OLE Object ) data types because doing so enables you to store Nulls.

For a QueryDef object, the settings for value are:

Setting	Query type

dbQSelect	Select

dbQAction	Action

dbQCrosstab	Crosstab

dbQDelete	Delete

dbQUpdate	Update

dbQAppend	Append

dbQMakeTable	Make-table

dbQDDL	Data-definition

dbQSQLPassThrough	Pass-through

dbQSetOperation	Union

dbQSPTBulk	Used with dbQSQLPassThrough to specify a query that doesn't return records.

Note   To create an SQL pass-through query, don't set the dbSQLPassThrough constant.  This is set automatically by the Microsoft Jet database engine when you create a QueryDef object and set the Connect property.

For a Recordset object, the settings for value are:

Setting	Recordset type

dbOpenTable	Table

dbOpenDynaset	Dynaset

dbOpenSnapshot	Snapshot

Remarks

These constants are listed in the Data Access (DAO) object library in the Object Browser.

Depending on the object, the Type property indicates:

Object	Type indicates

Field, Parameter, Property	Object data type

QueryDef	Type of query

Recordset	Type of Recordset

When you append a new Field, Parameter, or Property object to the collection of an Index, QueryDef, Recordset, or TableDef object, an error occurs if the underlying database doesn't support the data type specified for the new object.


Unique Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether an Index object represents a unique (key) index for a table.  For an Index object, this property setting is read/write until the object is appended to a collection, after which it's read-only.

Syntax

object.Unique [= value]

The Unique property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that specifies a unique index, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	The Index object represents a unique index.

False	The Index object represents a non-unique index.

Remarks

A unique index consists of one or more fields that logically arrange all records in a table in a unique, predefined order.  If the index consists of one field, values in that field must be unique for the entire table.  If the index consists of more than one field, each field can contain duplicate values, but each combination of values from all the indexed fields must be unique.

If both the Unique and Primary properties of an Index object are set to True, the index is unique and primary:  It uniquely identifies all records in the table in a predefined, logical order.  If the Primary property is set to False, the index is a secondary index.  Secondary indexes (both key and nonkey) logically arrange records in a predefined order without serving as an identifier for records in the table.

Tips

You don't have to create indexes for tables, but in large, unindexed tables, accessing a specific record can take a long time.

Records read from tables without indexes are returned in no particular sequence.

The Attributes property of each Field object in the Index object determines the order of records and consequently determines the access techniques to use for that Index.

A unique index helps optimize finding records.

Indexes don't affect the physical order of a base table [image] indexes only affect how the records are accessed by the Table object when a particular index is chosen or when the Microsoft Jet database engine creates Recordset objects.


Updatable Property

See Also	Example	Applies to	Specifics

Returns a value that indicates whether changes can be made to a data access object.

Syntax

object.Updatable

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Updatable property return values are:

Value	Description

True	The object can be changed or updated.

False	The object can't be changed or updated.  This is the only setting for snapshot-type Recordset and Snapshot objects.

Remarks

Depending on the object, if the Updatable property setting is True, the specified:

Database object can be changed.

QueryDef object query definition can be changed.

Recordset, Dynaset, or Table object records can be updated.

TableDef object table definition can be changed.

You can use the Updatable property with all Recordset objects and with the outdated Dynaset, Snapshot, and Table objects.

The Updatable property setting is always True for a newly created TableDef object and False for an attached TableDef object.  A new TableDef object can be appended only to a database for which the current user has write permission.

Many types of objects can contain fields that can't be updated.  For example, you can create a dynaset-type Recordset in which only some fields can be changed.  These fields can be fixed or contain data that increments automatically, or the dynaset can result from a query that combines updatable and nonupdatable tables.

If the object contains only nonupdatable fields, the value of the Updatable property is False.  When one or more fields are updatable, the property's value is True.  You can edit only the updatable fields.  A trappable error occurs if you try to assign a new value to a nonupdatable field.

The Updatable property of a QueryDef object is set to True if the query definition can be updated, even if the resulting Recordset isn't updatable.

Because an updatable object can contain nonupdatable fields, check the Fields collection of a Recordset object to check the DataUpdatable property of each field before you edit a record in the Recordset.


UserName Property

See Also	Example	Applies to	Specifics

Returns or sets a value that represents a user or group of users or the owner of a Workspace object.  For Container and Document objects, this property setting is read/write.  For a Workspace object, this property setting is read/write for an object not yet appended to a collection and read-only for an existing Workspace object.

Syntax

object.UserName [= value]

The UserName property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that evaluates to the name of a User object in the Users collection or a Group object in the Groups collection.  (Data type is String.)

Remarks

Depending on the type of object, the UserName property represents:

A user or group of users when you manipulate the access permissions of a Container object or a Document object.

The owner of a Workspace object.  For Container and Document objects, you use the UserName property with the Permissions property to establish read or write permissions.

To find or set the permissions for a particular user or group of users, first set the UserName property to the user or group name that you want to examine.  Then check the Permissions property setting to determine what permissions that user or group of users has, or set the Permissions property to change the permissions.

For a Workspace object, check the UserName property setting to determine the owner of the Workspace object.  Set the UserName property to establish the owner of the Workspace object before you append the object to the Workspaces collection.


V1xNullBehavior Property

See Also	Example	Applies to	Specifics

Returns or sets a value that indicates whether zero-length strings ("") used in code to fill Text or Memo fields are converted to Null.  This property applies only to Microsoft Jet database engine version 1.x databases that have been converted to Microsoft Jet engine version 2.0 databases.

Note   The Jet engine automatically creates this property when it converts a version 1.x database to a version 2.0 database.

Syntax

object.V1xNullBehavior [= value]

The V1xNullBehavior property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A Boolean expression that indicates whether zero-length strings are converted to Null, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	Zero-length strings are converted to Null.

False	Zero-length strings aren't converted to Null.

You can only set this property using Visual Basic.

Note   If you change this property setting, you must close and then reopen the database for your change to take effect.

Remarks

For fastest performance, modify code that sets any Text or Memo fields to zero-length strings so that the fields are set to Null instead, and remove V1xNullBehavior from the Properties collection.


ValidateOnSet Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies whether or not the value of a Field object is immediately validated when the object's Value property is set.  Only Field objects in Recordset objects support the ValidateOnSet property as read/write.

Syntax

object.ValidateOnSet [= value]

The ValidateOnSet property syntax has these parts:

Part	Description

object	An object expression that evaluates to a Field object of a table-type or dynaset-type Recordset object.

value	A Boolean expression that indicates whether a value is validated, as described in Settings.  (Data type is Boolean.)

Settings

The settings for value are:

Setting	Description

True	Validate when the property is set.

False	Validate when the record is updated.

Remarks

When ValidateOnSet is set to True, the validation rule specified by the ValidationRule property setting of the Field object is checked when you set the object's Value property.

A Recordset object can contain a Fields collection with several Field objects whose ValidationRule property value settings involve a combination of the fields.  When ValidateOnSet is set to False, you can set the Value property of each field independently and perform validation using the final value settings when the record is updated.

The ValidateOnSet property isn't supported on Field objects associated with the outdated Dynaset or Table objects.


ValidationRule Property

See Also	Example	Applies to	Specifics

Returns or sets a value that validates the data in a field as it's changed or added to a table.  For an object not yet appended to the Fields collection, this property is read/write.  See Remarks for the more specific read/write characteristics of this property.

Syntax

object.ValidationRule [= value]

The ValidationRule property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that validates an operation, as described in Settings.  (Data type is String.)

Settings

The settings for value are:

Setting	Description

True	An Update method for Field is successfully completed or a Field value is successfully set (if the ValidateOnSet property is set to True).

False	The operation described above fails.  The returned error message is the text of the ValidationText property, if specified, or the text of the expression specified by ValidationRule.

Remarks

For a Field object, use of the ValidationRule property depends on the object that contains the Fields collection that the Field object is appended to, as the following table shows.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read/write

For a Recordset object, use of the ValidationRule property is read-only.  For a TableDef object, use of the ValidationRule property depends on the status of the TableDef, as the following table shows.

TableDef	Usage

Base table	Read/write

Attached table	Read-only

Validation is supported only for databases that use the Microsoft Jet database engine.

The string expression specified by the ValidationRule property of a Field object can refer only to that Field.  The expression can't refer to user-defined functions, domain aggregate functions, SQL aggregate functions, or queries.  To set a Field object's ValidationRule property when its ValidateOnSet property setting is True, the expression must successfully parse (with the field name as an implied operand) and evaluate to True.  If its ValidateOnSet property setting is False, the ValidationRule property setting is ignored.

The ValidationRule property of a Recordset or TableDef object can refer to multiple fields in that object.  The restrictions noted earlier in this topic for the Field object apply.

For a table-type Recordset object, ValidationRule takes the value of the ValidationRule property setting of the TableDef object that you use to create the table-type Recordset object.

For a TableDef object based on an attached table, ValidationRule takes the value of the underlying base table.  If the underlying base table doesn't support validation, the value of this property is a zero-length string ("").

The ValidationRule property isn't supported for Field objects associated with the outdated Dynaset or Table objects.


ValidationText Property

See Also	Example	Applies to	Specifics

Returns or sets a value that specifies the text of the message that your application displays if the value of a Field object doesn't satisfy the validation rule specified by the ValidationRule property setting.

For an object not yet appended to a collection, this property is read/write.  For a Recordset object, this property setting is read-only.  For a TableDef object, this property setting is read-only for an attached table and read/write for a base table.  See Remarks for the more specific read/write characteristics of this property.

Syntax

object.ValidationText [= value]

The ValidationText property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	A string expression that specifies the text displayed if an entered value is invalid.  (Data type is String.)

Remarks

For a Field object, use of the ValidationText property depends on the object that contains the Fields collection that the Field object is appended to, as the following table shows.

Object appended to	Usage

Index	Not supported

QueryDef	Read-only

Recordset	Read-only

Relation	Not supported

TableDef	Read/write


Value Property (Data Access)

See Also	Example	Applies to	Specifics

Returns or sets the value of an object.

Syntax

object.Value [= value]

The Value property syntax has these parts:

Part	Description

object	An object expression that evaluates to an object in the Applies To list.

value	An expression that evaluates to a value appropriate for the data type, as specified by the Type property of an object.  (Data type is Variant.)

Remarks

Generally, Value is used to retrieve and alter data in Recordset objects.

The Value property is the default property of the Field, Parameter, and Property objects.  Therefore, the following lines of code are equivalent (assuming Field1 is at the first ordinal position):

X = MyRecordset!Field1

X = MyRecordset!Field1.Value

X = MyRecordset(0)

X = MyRecordset(0).Value

X = MyRecordset("Field1").Value

X = MyRecordset("Field1")

F$ = "Field1" : X = MyRecordset(F$).Value

X = MyRecordset(F$)


Version Property

See Also	Example	Applies to	Specifics

Returns a value that indicates the version of the database or database engine associated with the object.  This property setting is read-only.

Syntax

object.Version

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The Version property return value is a string expression that evaluates to a value, depending on the object specified:

Database object [image] identifies the data format version of an open database.

DBEngine object [image] identifies the version number of the Microsoft Jet database engine.

Remarks

For a Database object, this property identifies the version of the Jet database engine that created the database.

The setting of the Version property represents the version number in the form "major.minor"; for example, "2.0".  The product version number (for example, 2.0) consists of the version number (2), a period, and the release number (0).


AbsolutePosition Property Example

This example positions the current record to the nth record in a dynaset-type Recordset object.

Function MoveToRecord (N as Long, Rs as Recordset) As Integer

Rs.MoveLast	' Fully populate the Recordset.

If Rs.RecordCount > N Then

Rs.AbsolutePosition = N

MoveToRecord = True

Else

MoveToRecord = False

End If

Db.Close


BOF, EOF Properties Example

This example uses the BOF and EOF properties to find the beginning and end of an Orders table.  The example moves through the records from the beginning of the file to the end and then from the end to the beginning.  Notice that there is no current record immediately following the first loop.

Dim MyDB As Database, MyTable As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")
Set MyTable = MyDB.OpenRecordset("Orders")	' Open Recordset.

Do Until MyTable.EOF	' Do until end of file.
MyTable.MoveNext	' Move to next record.
...
Loop

MyTable.MoveLast	' Move to last record to set a current record.

Do Until MyTable.BOF	' Do until beginning of file.
MyTable.MovePrevious	' Move to previous record.

...
Loop

MyTable.Close	' Close table.

MyDb.Close


Bookmark, Bookmarkable Properties Example

This example shows how you can save your place in a Recordset by saving a bookmark.  Once saved, this bookmark can be applied to the Bookmark property to reposition the current record pointer to any location in the Recordset.  The FindYear function looks up a title in a Recordset based on a value and Recordset passed to it and fills a string array with the bookmarks of any records that match.

Function FindYear (YearWanted%, Rs As Recordset, Found()) As Integer

Dim i As Integer

Rs.FindFirst "[Year Published] = " & YearWanted

If Rs.NoMatch Or Rs.Bookmarkable = False Then

FindYear = False

Exit Function

Else

Do Until Rs.NoMatch = True

Found(i) = Rs.Bookmark

Rs.FindNext "[Year Published] = " & YearWanted

i = i + 1

Loop

End If

FindYear = i

End Function


CacheSize, CacheStart Properties, FillCache Method Example

This example opens a Recordset from an Order Detail table stored on an ODBC server, sets the CacheSize and CacheStart properties, and then uses FillCache to cache data from the server to the database.

Dim MyRecordset As Recordset, MyDatabase As Database

' Open database containing attached ODBC table.

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Open local recordset.

Set MyRecordset = MyDatabase.OpenRecordset("OrderDetail",DbOpenDynaset)

' Locate record whose Customer ID is 1001.

MyRecordset.FindFirst "CustID = 1001"

' Start caching records at Customer ID 1001.

MyRecordset.CacheStart = MyRecordset.Bookmark

MyRecordset.CacheSize = 12	' Set cache size to 12 records.

MyRecordset.FillCache	' Fill cache.

...	' Display rows.

...


Connect, SourceTableName Properties; TableDef Object Example
Connect, SourceTableName Properties Example

This example creates a TableDef object in the specified database; sets its Connect, Name, and SourceTableName properties; and then appends it to the TableDefs collection.

Function ConnectSource () As Integer

Dim MyDatabase As Database

Dim MyTableDef As TableDef

Dim I As Integer

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTableDef = MyDatabase.CreateTableDef("PDXAuthor")

' Attach Paradox table Author in database C:\PDX\PUBLISH.

MyTableDef.Connect = "Paradox 4.X;DATABASE=C:\PDX\PUBLISH"

MyTableDef.SourceTableName = "Author"

MyDatabase.TableDefs.Append MyTableDef	' Attach table.

ConnectSource = True

End Function


Container Property (Data Access) Example

This example determines the name of the Container object to which a Document object belongs.

Sub Doc_Analyzer(Doc As Document)

Dim ContainerName As String

ContainerName = Doc.Container

Select Case ContainerName

Case "Relations"

...	' Now that you know it's a relation,

...	' you can do relation-specific things

' in this line of code.

Case "Tables"	' TableDef or QueryDef.

...

Case "Databases"

...

Case "Forms"

...

End Select

End Sub


Count Property Example
Count Property (Data Access) Example

This example lists the names and total number of TableDef and QueryDef objects in the current database.

Dim MyDB As Database, I As Integer

Set MyDB = DBEngine.Workspaces(0).Databases(0)

For I = 0 To MyDB.TableDefs.Count - 1
Debug.Print MyDB.TableDefs(I).Name
Next I

Debug.Print MyDB.TableDefs.Count

For I = 0 To MyDB.QueryDefs.Count - 1
Debug.Print MyDB.QueryDefs(I).Name
Next I

Debug.Print MyDB.QueryDefs.Count


DateCreated, LastUpdated Properties Example

This example determines the date and time when the Employees table was created and last updated.

Dim Creation As Variant, DesignChange As Variant, MyTable As Recordset, MyDB As Database

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTable = MyDB.OpenRecordset("Employees", dbOpenTable)

Creation = MyTable.DateCreated

DesignChange = MyTable.LastUpdated


Description Property Example

This example assigns a user-defined message to the Description property of the Err object.

Err.Description = "It was not possible to access an object necessary " _

& "for this operation."


DistinctCount Property Example

This example checks the DistinctCount property of the current Index of a TableDef object opened on a table in the database.

Dim MyDB As Database, MyTD As TableDef, MyIND As Index

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB", True)

Set MyTD = MyDB!Customers

Set MyIND = MyTD.Indexes(0)

Debug.Print = MyIND.DistinctCount


EditMode Property Example

This example checks the EditMode property of a Recordset object and completes the update if the AddNew method has been invoked or the object is being edited.

Function PostChange(Rs as Recordset) As Integer

If (Rs.EditMode = dbEditAdd) or  _

(Rs.EditMode = dbEditInProgress) Then

Rs.Update

PostChange = True

Else

PostChange = False

End If

End Function


Fields Property Example

This example adds a new index to the Authors table.

Dim TempIndex As Index	' Create new Index object.

Set TempIndex = MyDb.TableDefs("Authors").CreateIndex("Full Name")

TempIndex.Fields = "LName;FName"

TempIndex.Unique = True

' Append the new Index to the Indexes collection.

MyDb.TableDefs("Authors").Indexes.Append TempIndex


Filter Property Example

This example creates a dynaset-type Recordset that contains only records for orders shipped to the United Kingdom.

Dim MyDB As Database, MySet As Recordset, FilteredSet As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MySet = MyDB.OpenRecordset("Orders", dbOpenDynaset)	' Create dynaset-type Recordset.

MySet.Filter = "[Ship Country] = 'UK'"	' Set filter condition.

Set FilteredSet = MySet.OpenRecordset()	' Create filtered dynaset-type Recordset.

Note   To change the contents of MySet, you must set its Filter property, and then open a second Recordset object based on MySet.

Tip   In some situations, it may be more efficient to create the second Recordset object with the desired conditions in one step.  As a general rule, when you know the data you want to select, it's usually more efficient to create a Recordset with an SQL statement.  This example shows how you can create just one Recordset and obtain the same results as in the preceding example:

Dim MyDB As Database, MySet As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MySet = MyDB.OpenRecordset("SELECT * FROM Orders WHERE [Ship Country] = 'UK';")


ForeignName Property Example

This example shows how you can use the ForeignName, ForeignTable, and Table properties when you create a relationship between two existing tables [image] in this case, Table1 (the primary table) and Table2 (the foreign table) in the specified database.  Field1 is the primary key in Table1, and Field2 is a foreign key in Table2.  The relationship is one-to-many and referential integrity is enforced.

Function ForeignNameTable () As Integer

Dim MyDb As Database

Dim MyField As Field, MyRelation As Relation

' Get database.

Set MyDb = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create new relationship and set its properties.

Set MyRelation = MyDb.CreateRelation("MyRelation")

MyRelation.Table = "Table1"

MyRelation.ForeignTable = "Table2"

' Create field and set its properties.

Set MyField = MyRelation.CreateField("Field1")

MyField.ForeignName = "Field2"

' Append field to relation and relation to database.

MyRelation.Fields.Append MyField

MyDb.Relations.Append MyRelation

End Function


HelpContext Property Example

This example uses the HelpContext property of the Err object to show the Visual Basic Help topic for the error Overflow.

Err.Clear

On Error Resume Next

Err.Raise 6 ' Generate "Overflow" error.

If Err.Number <> 0 Then

Msg = "Press F1 or Help to see " & Err.HelpFile & " topic for" & _

" the following HelpContext: " & Err.HelpContext

MsgBox Msg, , "Error: " & Err.Description, Err.HelpFile, _

Err.HelpContext

End If


HelpFile Property Example

This example uses the HelpFile property of the Err object to start the Microsoft Windows Help system.  By default the HelpFile property contains the name of the Visual Basic Help file.

Err.Clear

On Error Resume Next	' Suppress errors for demonstration purposes.

Err.Raise 6	' Generate "Overflow" error.

Msg = "Press F1 or Help to see " & Err.HelpFile & _

" topic for this error"

MsgBox Msg, , "Error: " & Err.Description,Err.HelpFile, Err.HelpContext


Index, Unique Properties Example

This example adds a new index to a TableDef object, makes that index the current index, and invokes the Seek method based on that index.  The names of the Field objects created and appended to the Fields collection of the Index object correspond to the names of current fields in the table.

Dim Tb As Recordset, Ix As Index, Fd As Field

Dim MyDb As Database

Set MyDb = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Set Ix = MyDb.TableDefs("Publishers").CreateIndex("PubID Name")

Set Fd = Ix.CreateField("PubID")

Ix.Fields.Append Fd

Set Fd = Ix.CreateField("Name")

Ix.Fields.Append Fd

Ix.Unique = True

Debug.Print Ix.Fields	' Show Fields property.

' Append the new Index to the Indexes collection.

MyDb.TableDefs("Publishers").Indexes.Append Ix

Set Tb = MyDb.OpenRecordset("Publishers",dbOpenTable)  'Open the table.

Tb.Index = "PubID Name"	' Set table's current index.

Tb.Seek "=", "27", "Yourdon Press"	' Look for Publisher.

If Tb.NoMatch Then

Tb.MoveFirst

Debug.Print "Not found"

Else

Debug.Print Tb.Name

End If

Tb.Close

This example sets the index for MyTable to the primary key (PrimaryKey is the default name of an Index object if the primary key is set in the table's Design view).  Next, it locates the record with a matching key field value of 10,050.  Notice that the current index must be set before certain operations, such as the Seek method, can be performed.

Dim MyDB As Database, MyTable As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTable = MyDB.OpenRecordset("Orders", dbOpenTable)   ' Open Recordset.

MyTable.Index = "PrimaryKey"	' Set current index.

MyTable.Seek "=", 10050	' Locate record.

...

MyTable.Close	' Close Recordset.


Inherit Property Example

This example sets the Table containers Inherit property to True, and then sets the Permissions property to allow users to alter the security settings of documents.

Dim MyDB As Database, MyContainer As Container

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyContainer = MyDB.Containers(Tables)

MyContainer.Inherit = True

MyContainer.Permissions = dbSeeWriteSec


Inherited Property Example

This example creates a Recordset object from a QueryDef object, creates a new property, and indicates whether the property is inherited.  Then the example prints the name of each field in the Recordset and, for each property of each field, it prints the Name, Type, Value, and Inherited property value settings.

Dim MyDB As Database, MyQueryDef As QueryDef, MyRecordset As _

Recordset, MyProperty As Property

Dim X, Y As Integer

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyQueryDef = MyDB.QueryDefs(0)

Set MyProperty = MyQueryDef.CreateProperty("Moose",dbBoolean, True)

MyQueryDef.Properties.Append MyProperty

Set MyRecordset = MyQueryDef.OpenRecordset()

Debug.Print "Is MyQueryDef.Moose inherited? "; MyQueryDef.Properties("Moose").Inherited

Debug.Print "Is MyRecordset.Moose inherited? "; MyRecordset.Properties("Moose").Inherited

For X = 0 To MyRecordset.Fields.Count - 1

Debug.Print MyRecordset.Fields(X).Name

On Error Resume Next

For Y = 0 To MyRecordset.Fields(X).Properties.Count - 1

Debug.Print MyRecordset.Fields(X).Properties(Y).Name

Debug.Print MyRecordset.Fields(X).Properties(Y).Type

Debug.Print MyRecordset.Fields(X).Properties(Y).Value

Debug.Print MyRecordset.Fields(X).Properties(Y).Inherited

Next Y

Next X


IniPath Property Example

This example sets the path in the IniPath property to an application .INI file.

Sub SetPathFirst()

DBEngine.IniPath = "C:\MYAPPDIR\MYAPP.INI"

End Sub


IsolateODBCTrans Property Example

This example opens a Workspace and sets IsolateODBCTrans to True before starting a transaction.

Dim MyDB As Database, MyWS As Workspace, MyQuery As QueryDef

Set MyWS = DBEngine.Workspaces(0)

MyWS.IsolateODBCTrans = True

MyWS.BeginTrans

' Execute query to ODBC database and complete transaction.

...

...


LockEdits Property Example

This example opens a dynaset-type Recordset and sets its LockEdits property to False.  This enables optimistic locking so other users can change the database records at any time.  Your application triggers a trappable error if the data changes before you use the Update method.

Sub ShowLE()

Dim MyDB As Database, MyRecords As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyRecords = MyDB.OpenRecordset("Table To Update")

MyRecords.LockEdits = False

MyRecords.Edit	' Start editing.

MyRecords!MyField = "New Stuff"

OnError Goto MyEH

MyRecords.Update	' Try to post the changes.

MyRecords.Close

Exit Sub

MyEH:

If Error = 3197 Then	' Data changed.

MsgBox "Data changed."

Resume Next

Else

Msgbox "Some other error."

End If

End Sub


LoginTimeout Property Example

This example sets the LoginTimeout property to 120 seconds and then creates and runs a query on a database on an ODBC server.

Dim MyDB As Database, MyQuery As QueryDef, MyRecords As Recordset

DBEngine.LoginTimeout = 120	' Timeout in 2 minutes.

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create query.

Set MyQuery = MyDB.CreateQueryDef("All Cust", "SELECT * FROM Customers;")

MyQuery.Connect = "ODBC;DSN=Human Resources; DATABASE=HRSRVR; UID=Smith; PWD=Sesame"

' Log in to server and run query.

Set MyRecords = MyQuery.OpenRecordset()


Name Property Example

This example creates a TableDef object and then names it Parts ID.

Dim MyDB As Database, MyTD As TableDef, Fd as Field

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTD = MyDB.CreateTableDef("")

MyTD.Name = "Parts ID"

...	' Create fields.

MyDB.TableDefs.Append MyTD


NoMatch Property Example

This example changes the job title of all sales representatives in an Employees table.  It creates a dynaset-type Recordset and then uses FindFirst and FindNext to locate every record satisfying the criteria for the title.  It prepares each record for editing, changes the title, and saves the change with the Update method.

Dim Criteria As String, SaveHere As String,

Dim MyDB As Database, MySet As Recordset

Criteria = "Title = 'Sales Representative'"   ' Define search criteria.

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create Recordset.

Set MySet = MyDB.OpenRecordset("Employees", dbOpenDynaset)

SaveHere = MySet.Bookmark	' Save Bookmark.

MySet.FindFirst Criteria	' Locate first occurrence.

Do Until MySet.NoMatch	' Loop until no matching records.

MySet.Edit	' Enable editing.

MySet!Title = "Account Executive"	' Change title.

MySet.Update	' Save changes.

MySet.FindNext Criteria	' Locate next record.

Loop	' End of loop.

MySet.Bookmark = SaveHere

Tip   In some situations, using an update query is faster.


Number Property Example

This example examines the Number property of the Err object to determine whether an error returned by an object was defined by the object, or whether it was mapped to an error defined by Visual Basic.  Note that the constant vbObjectError is a very large negative number that an object adds to its own error code to indicate that the error is defined by the server.  Therefore, subtracting it from Err.Number strips it out of the result.  If the error is object-defined, the base number is left in MyError, which is displayed in a message box along with the original source of the error.  If Err.Number represents a Visual Basic error, then the Visual Basic error number is displayed in the message box.

' First, strip off the constant added by the object to indicate one

' of its own errors.

MyError = Err.Number - vbObjectError

' If you subtract the vbObjectError constant, and the number is still

' in the range 0-65,535, it is an object-defined error code.

If MyError > 0 And MyError < 65535 Then

Msg = "The object you accessed assigned this number to the error: " _

 	& MyError & ". The originator of the error was: " _

& Err.Source & ". Press F1 to see originator's Help topic."

' Otherwise it is a Visual Basic error number.

Else

Msg = "This error (# " & Err.Number & ") is a Visual Basic error" & _

" number. Press Help button or F1 for the Visual Basic Help" _

& " topic for this error."

End If

MsgBox Msg, , "Object Error", Err.HelpFile, Err.HelpContext


ODBCTimeoutProperty Example

This example sets the ODBCTimeout property to 120 seconds and then creates a query and runs it on a database on an ODBC server.

Dim MyDB As Database, MyQuery As QueryDef, MyRecords As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

' Create query.

Set MyQuery = MyDB.CreateQueryDef("All Cust", "SELECT * FROM Customers;")

MyQuery.Connect = "ODBC;DSN=Human Resources; SERVER=HRSRVR: UID=Smith; PWD=Sesame"

' Log in to server and run query.

MyQuery.ODBCTimeout = 120

Set MyRecords = MyQuery.OpenRecordset()


Owner Property Example

This example changes the Owner property setting of a Document object after determining whether the current user has the appropriate permissions to do so.

Dim MyDB As Database, MyDoc As Document

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyDoc = MyDB.Containers(0).Documents(0)

If (MyDoc.Permissions And dbSecWriteOwner) <> 0  Then

MyDoc.Owner = "SomebodyElse"

End If


Password, PID Properties Example

This example creates a new User object and sets the Name, PID, and Password properties for the new object before appending it to the Users collection.

Dim MyUser As User, MyWorkspace As Workspace

...

Set MyWorkspace = DBEngine.Workspaces(0)   ' Get default workspace.

' Create, specify, and append new User object.

Set MyUser = MyWorkspace.CreateUser("Pat Smith")

MyUser.PID = "abc123DEF456"

MyUser.Password = "My Secret"

MyWorkspace.Users.Append MyUser


PercentPosition Property Example

This example displays the current position of a record in a Recordset in a label named CurrentPosition.

Dim MyDB As Database, MyTable As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyTable = MyDB.OpenRecordset("Employees",dbOpenTable)   ' Open table.

MyTable.Index = "Last Name"

' Set current index.

MyTable.MoveLast

...

CurrentPosition.Caption = MyTable.PercentPosition   ' Display current position.


Permissions Property Example

This example prints the Permissions property setting of a Document object for the current user.

Dim MyDB As Database, MyDoc As Document

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")
Set MyDoc = MyDB.Containers(0).Documents("MyDoc")

Debug.Print MyDoc.Permissions


Primary Property Example

The example creates a new Table and primary key Index object and then adds the Table to the TableDefs collection of a Database.

Dim Db As Database , Td As TableDef, Idx As Index

Dim Fd1 As Field, Fd2 As Field

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")   ' Open the Database.

Set Td = Db.CreateTableDef("Book Types")

Set Fd1 = Td.CreateField("TypeNum",dbLong)   ' Create and Set Fd1 field properties.

 Td.Fields.Append Fd1	' Add Fd1 field to TableDef.

Set Fd2 = Td.CreateField("Type",dbText)   ' Create and Set Fd2 field properties.

 Fd2.Size = 15	' Set Size property of text field.

Td.Fields.Append Fd2	' Add Fd2 field to TableDef.

Set Idx = Td.CreateIndex("PrimaryKey")

Idx.Name = "PrimaryKey"	' Set properties in new Index.

Idx.Unique = True

Idx.Primary = True

Idx.Fields = "TypeNum"

Td.Indexes.Append Idx	' Add Index to TableDefs collection.

Db.TableDefs.Append Td	' Add TableDefs to Database.


QueryTimeout Property Example

This example opens the specified database and sets the QueryTimeout property to 120 seconds.

Dim MyDB As Database

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

MyDB.QueryTimeout = 120


RecordCount Property Example

This example creates a Recordset object based on the Employees table and then determines the number of records in the Recordset.

Dim MyDB As Database, MyRecords As Recordset, Total As Long

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyRecords = MyDB.OpenRecordset("Employees")

MyRecords.MoveLast

Total = MyRecords.RecordCount

If Total = -1 Then

Debug.Print "Count not available."

End If


RecordsAffected Property Example

This example prints the number of records updated by an action query.

Dim Db As Database, Results As Long

Set Db = Workspaces(0).OpenDatabase("BIBLIO.MDB")

Db.Execute "Update Titles Set [Year Published] = 1994 " _

& " WHERE Title = 'To Kill an SQL Query' "

Results = Db.RecordsAffected

Debug.Print Results " records were changed."

Db.Close


Restartable Property, Requery Method Example

This example determines the Restartable property setting of a dynaset-type Recordset and then uses the Requery method on the Recordset.

Dim MyDB As Database, MyData As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyData = MyDB.OpenRecordset("Table That Changes Often", dbOpenDynaset)

If MyData.Restartable = True Then

MyData.Requery

Else

MyData.Close

End If


ReturnsRecords Property Example

The following example creates an SQL pass-through query that returns records from an external database.

Dim MyDB As Database, PassThrough As QueryDef

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set PassThrough = MyDB.CreateQueryDef("October _

Orders","SELECT * From Orders WHERE ShipCity = 'London'")

MyDB.Connect = "ODBC; DSN=MySQLDBDSN;  " _

& " UID=Chrissy;PWD=FourOh;"

PassThrough.ReturnsRecords = True


Size, Type Properties Example

This example creates a new Field object with a Text field type, sets its Name property to Fax Phone and its Size property to 20, and appends the new object to the Fields collection of the Employees table in the TableDefs collection of the database.

Function SizeType() As Integer

Dim MyDatabase As Database

Dim MyField As Field, MyTableDef As TableDef

' Open database.

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Get existing table reference.

Set MyTableDef = MyDatabase!Employees

' Create Field object.

Set MyField = MyTableDef.CreateField("Fax Phone")

' Set field properties.

MyField.Type = dbText

MyField.Size = 20

' Append MyField to Fields collection.

MyTableDef.Fields.Append MyField

SizeType = True

End Function

You can also use the CreateField method if you provide name, type, and size as arguments.

Set MyField = MyTableDef.CreateField("Fax Phone", dbText, 20)


Sort Property Example

This example uses the Sort property to set the sort order of a dynaset-type Recordset based on an Orders table.  The records in SortedSet will be in ascending Ship Country order.

Dim MyDB As Database, MySet As Recordset, SortedSet As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MySet = MyDB.OpenRecordset("Orders", dbOpenDynaset)   ' Create dynaset.

MySet.Sort = "[Ship Country]"	' Set sort order.

Set SortedSet = MySet.OpenRecordset()	' Create second dynaset.

Tip   In some situations, it may be more efficient to create the second Recordset object with the desired conditions in one step.  As a general rule, when you know the data you want to select, it's usually more efficient to create a Recordset with an SQL statement.  This example shows how you can create just one Recordset and obtain the same results as in the preceding example:

Dim MyDB As Database, MySet As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MySet = MyDB.OpenRecordset("SELECT * FROM Orders ORDER BY [Ship Country];")


Source Property Example

This example assigns the Programmatic ID of an OLE Automation object created in Visual Basic to the variable MyObjectID, then assigns that to the Source property of the Err object when it generates an error with the Raise method.  When handling errors, you should not use the Source property (or any Err properties other than Number) programatically.  The only valid use of properties other than Number is for displaying rich information to an end user in cases where you cannot handle an error.

' An object of type MyClass generates an error and fills all Err object

' properties, including Source, which receives MyObjectID, which is a

' combination of the Title property of the App object and the Name

' property of the MyClass object.

MyObjectID = App.Title & "." & MyClass.Name

Err.Raise	Number := vbObjectError + 894, Source := MyObjectID, _

Description := "Was not able to complete your task", _

HelpFile := MyHelpFile, HelpContext := MyHelpContext


SourceField Property Example
SourceField, SourceTable Properties Example

This example creates a Recordset object using an SQL statement that creates aliases for fields in two different tables in the database.  The example then prints the name of the field, the original table, and the original field.

Function SourceInfo () As Integer

Dim MyDatabase As Database

Dim MyRecordset As Recordset, MyField As Field

Dim MySQL As String, I As Integer

' Open database.

Set MyDatabase = Workspaces(0).OpenDatabase("MYDB.MDB")

' Construct SQL statement.

MySQL = "SELECT [Employee ID] As EmpID, [Customer ID] As CustID"

MySQL = MySQL & " FROM Employees, Customers;"

Set MyRecordset = MyDatabase.OpenRecordset(MySQL)   ' Generate recordset.

For I = 0 To MyRecordset.Fields.Count - 1

Set MyField = MyRecordset.Fields(I)

Debug.Print MyField.Name	' Print field name.

Debug.Print MyField.SourceTable	' Print original table name.

Debug.Print MyField.SourceField	' Print original field name.

Next I

SourceInfo = True

End Function


SQL Property Example

This example creates a query based on an Orders table.  The query selects all orders that have a Freight value greater than 10.

Dim MyDB As Database, MyQuery As QueryDef, MySnapshot As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyQuery = MyDB.CreateQueryDef("Large Freight")   ' Create query.

MyQuery.SQL = "SELECT * FROM Orders WHERE [Freight] > 10;"

' Create snapshot.

Set MySnapshot = MyDB.OpenRecordset("Large Freight", dbOpenSnapshot)


Updatable Property Example

This example adds a record to a Recordset object if the object's Updatable property setting is True.

Dim MyDB As Database, MyData As Recordset

Set MyDB = Workspaces(0).OpenDatabase("MYDB.MDB")

Set MyData = MyDB.OpenRecordset("Unfamiliar Table")

If MyData.Updatable = True Then

MyData.AddNew

MyData("MyField") = "Some new data"

MyData.Update

End If

MyData.Close

MyDB.Close


UserName Property Example

This example sets the access permissions for a table named MyTable in the specified database for a user named Millicent to read-only.  The code then checks to see if Millicent has permission to add records.

Dim MyWorkspace As Workspace, MyDatabase As Database

Dim MyDocument As Document

...

Set MyWorkspace = DBEngine.Workspaces(0)

Set MyDatabase = MyWorkspace.OpenDatabase("MYDB.MDB")

...

Set MyDocument = MyDatabase.Containers("Tables")![MyTable]

MyDocument.UserName = "Millicent"

MyDocument.Permissions = dbSecRetrieveData

If(MyDocument.Permissions and dbSecInsertData) > 0 Then

Debug.Print "Millicent can insert data."

Else

Debug.Print "Millicent can't insert data."

End If

...


Version Property Example

This example checks the version number of the Jet database engine and splits it into the version number and release number.  The example doesn't check for an invalid string.

Dim DBVersion As String, JetVerNo As String, JetRelNo As String

Dim DotLocation As Integer

...

DBVersion = DBEngine.Version

DotLocation = InStr(DBVersion, ".")

JetVerNo = Left$(DBVersion, DotLocation - 1)

JetRelNo = Right$(DBVersion, Len(DBVersion) - DotLocation)

...


Data Access Constants

See Also	Example	Specifics

You can use the Object Browser to browse the list of built-in constants.  From the View menu, choose Object Browser, select the appropriate library, and then select the Constants object. Scroll the list in the Methods/Properties box to see the complete list of constants.

The data access objects provide built-in constants that you can use with methods or properties.  These constants all begin with the letters db and are documented with the method or property to which they apply.

Visual Basic contains built-in constants that you can use with methods or properties.  These constants all begin with the letters vb and are documented with the method or property to which they apply.

Constant	Value	Description

dbOpenTable 	1	Open table-type Recordset.

dbOpenDynaset 	2	Open dynaset-type Recordset.

dbOpenSnapshot	4	Open snapshot-type Recordset.

Constant	Value	Description

dbDenyWrite	0x1	Other users can't change dynaset records.

dbDenyRead	0x2	Other users can't read dynaset records.

dbReadOnly	0x4	Open dynaset as read-only.

dbAppendOnly	0x8	You can add new records to the dynaset, but you can't read existing records.

dbInconsistent	0x10	Updates apply to all dynaset fields, even if other records affected.

dbConsistent	0x20	Updates apply only to those fields that will not affect other records in the dynaset.

dbSQLPassThrough	0x40	Sends an SQL statement to an ODBC database.

dbFailOnError	0x80	Roll back changes if error occurs.

dbForwardOnly	0x100	Create forward-only scrolling snapshot-type Recordset.

dbOptionINIPath	1	Set application initialization (.INI) filename and path .

Constant	Value	Description

dbFixedField     	0x1	Field size fixed (default for Numeric fields).

dbVariableField  	0x2	Field size variable (Text fields only).

dbAutoIncrField  	0x10	New record field value incremented to unique Long integer (counter type).

dbUpdatableField 	0x20	Field is updatable (read/write).

dbDescending	0x1	Field sorted in descending order.

Constant	Value	Description

dbBoolean	1	Boolean (True/False) data.

dbByte	2	Byte (8-bit) data .

dbInteger	3	Integer data.

dbLong	4	Long Integer data.

dbCurrency	5	Currency data.

dbSingle	6	Single-precision floating-point data.

dbDouble	7	Double-precision floating-point data.

dbDate	8	Date value data.

dbText	10	Text data (variable width).

dbLongBinary	11	Binary data (bitmap).

dbMemo	12	Memo data (extended text).

Constant	Value	Description

dbRelationUnique	0x00000001&	One-to-one relationship.

dbRelationDontEnforce 	0x00000002&	Relationship not enforced (no referential integrity).

dbRelationInherited 	0x00000004&	Relationship exists in a noncurrent database containing the two attached tables.

dbRelationUpdateCascade 	0x00000100&	Updates cascade.

dbRelationDeleteCascade 	0x00001000&	Deletions cascade.

dbRelationLeft	0x1000000&	Relationship is a left join.

dbRelationRight  	0x02000000&	Relationship is a right join.

dbAttachExclusive  	0x00010000&	Attached Microsoft Jet database engine table opened for exclusive use.

dbAttachSavePWD 	0x00020000&	Save user ID and password for attached table.

dbSystemObject 	0x80000002&	System table.

dbHiddenObject  	0x00000001&	Hidden table (for temporary use).

dbTable	1	Table object.

dbQueryDef	5	QueryDef object.

dbAttachedTable  	0x40000000&	Attached non-ODBC database table.

dbAttachedODBC 	0x20000000&	Attached ODBC database table.

Constant	Value	Description

dbQSelect	0x00	SELECT query.

dbQAction	0xF0	Action query.

dbQCrosstab	0x10	Crosstab query.

dbQDelete	0x20	DELETE query.

dbQUpdate	0x30	UPDATE query.

dbQAppend	0x40	APPEND query.

dbQMakeTable	0x50	Make-table query.

dbQDDL	0x60	Data definition language (DDL) query.

dbQSQLPassThrough	0x70	SQL pass-through query.

dbQSetOperation	0x80	Set operation query.

dbQSPTBulk	0x90	Bulk operation query.

Constant	Value	Description

dbUnique	1	Unique index.

dbPrimary	2	Primary index.

dbProhibitNull	4	No null keys permitted.

dbIgnoreNull	8	Ignore null keys.

Constant	Value	Description

dbVersion10	1	Microsoft Jet database engine version 1.0.

dbEncrypt	2	Encrypt database.

dbDecrypt	4	Decrypt database while compacting.

dbVersion11	8	Microsoft Jet database engine version 1.1.

dbVersion20	16	Microsoft Jet database engine version 2.0.

Constant	Value	Description

dbFreeLocks	1	Free page locks.

dbSecNoAccess	0x0&	No access to the object.

dbSecFullAccess	0xFFFFF&	Has full access to the object.

dbSecDelete 	0x10000&	Can delete the object.

dbSecReadSec 	0x20000&	Can read the object's security-related information.

dbSecWriteSec 	0x40000&	Can alter access permissions.

dbSecWriteOwner 	0x80000&	Can change the Owner property setting.

dbSecDBCreate	0x1&	Can create new databases (valid only on the databases Container object in the system database, typically SYSTEM.MDA).

dbSecDBOpen	0x2&	Can open the database.

dbSecDBExclusive	0x4&	Has exclusive access.

dbSecCreate	0x1&	Create new tables (valid only with a Container object that represents a table).

dbSecReadDef	0x4&	Read the table definition, including column and index information.

dbSecWriteDef	0x8&	Modify or delete table definition, including column and index information.

dbSecRetrieveData 	0x10&	Retrieve data from the document.

dbSecInsertData	0x20&	Add records.

dbSecReplaceData	0x40&	Modify records.

dbSecDeleteData	0x80&	Delete records.

Constant	Value	Description

dbMatchEntrySimple	0	First character match.

dbMatchEntryExtended	1	Word search.

Constant	Value	Description

dbEditNone	0	No editing operation in effect.

dbEditInProgress	1	Edit method invoked.

dbEditAdd	2	AddNew method invoked.

Constant	Value	Description

dbSortArabic	267	Arabic collating order.

dbSortCyrillic	263	Russian collating order.

dbSortCzech	264	Czech collating order.

dbSortDutch 	259	Dutch collating order.

dbSortGeneral	256	English, German, French, and Portuguese collating order.

dbSortGreek	269	Greek collating order.

dbSortHebrew	268	Hebrew collating order.

dbSortHungarian	265	Hungarian collating order.

dbSortIcelandic	262	Icelandic collating order.

dbSortNorw	261	Norwegian and Danish collating order.

dbSortPDXIntl	4096	Paradox international collating order.

dbSortPDXNor	4098	Paradox Norwegian and Danish collating order.

dbSortPDXSwe	4097	Paradox Swedish and Finnish collating order.

dbSortPolish	266	Polish collating order.

dbSortSpanish	258	Spanish collating order.

dbSortSwedFin	260	Swedish and Finnish collating order.

dbSortTurkish	270	Turkish collating order.

dbSortUndefined	-1	Collating order undefined or unknown.

Constant	Value	Description

dbLangArabic	LANGID0x0401CP1256COUNTRY0	Arabic collating order.

dbLangCzech	LANGID0x0405CP1250COUNTRY0	Czech collating order.

dbLangDutch	LANGID0x0413CP1252COUNTRY0	Dutch collating order.

dbLangGeneral	LANGID0x0409CP1252COUNTRY0	English, German, French, Portuguese, Italian, and Modern Spanish collating order.

dbLangGreek	LANGID0x0408CP1253COUNTRY0	Greek collating order.

dbLangHebrew	LANGID0x040DCP1255COUNTRY0	Hebrew collating order.

dbLangHungarian	LANGID0x040ECP1250COUNTRY0	Hungarian collating order.

dbLangIcelandic	LANGID0x040FCP1252COUNTRY0	Icelandic collating order.

dbLangNordic	LANGID0x041DCP1252COUNTRY0	Nordic collating order.

dbLangNorwdan	LANGID0x0414CP1252COUNTRY0	Norwegian and Danish collating order.

dbLangPolish	LANGID0x0415CP1250COUNTRY0	Polish collating order.

dbLangCyrillic	LANGID0x0419CP1251COUNTRY0	Russian collating order.

dbLangSpanish	LANGID0x040ACP1252COUNTRY0	Spanish collating order.

dbLangSwedfin	LANGID0x040BCP1252COUNTRY0	Swedish and Finnish collating order.

dbLangTurkish	LANGID0x041FCP1254COUNTRY0	Turkish collating order.


Trappable Data Access Errors

See Also	Example	Specifics

Trappable errors can occur while an application is running, either within the Visual Basic environment or as a stand-alone executable.  These errors may be generated in operations that involve the data access functionality of Visual Basic.  You can test and respond to trappable errors using the On Error statement and the Err function.

Remember, while developing in Visual Basic, you can get help on any message by pressing F1.

Note   600 series data access error messages have been replaced or made obsolete by the latest version of the Microsoft Jet database engine.

Code	Message

2055	Expression not valid: <expression>.

2390	Can't change the data type or field size of this field.  It is part of one or more relationships.

2420	Syntax error in number.

2421	Syntax error in date.

2422	Syntax error in string.

2423	Invalid use of '.', '!', or '()'.

2424	Unknown name.

2425	Unknown function name.

2426	Function isn't available in expressions.

2427	Object has no value.

2428	Invalid arguments used with domain function

2429	In operator without ()

2430	Between operator without And

2431	Syntax error (missing operator).

2432	Syntax error (comma).

2433	Syntax error.

2434	Syntax error (missing operator).

2435	Extra ).

2436	Missing ), ], or Item.

2437	Invalid use of vertical bars.

2438	Syntax error.

2439	Wrong number of arguments used with function.

2442	Invalid use of parentheses.

2443	Invalid use of Is operator.

2445	Expression too complex.

2446	Out of memory during calculation.

2447	Invalid use of '.', '!', or '()'.

2448	Can't set value.

2449	Invalid method in expression.

2450	Invalid reference to form 'Item'.

2451	Invalid reference to report 'Item'.

2452	Invalid reference to Parent property.

2453	Invalid reference to control 'Item'.

2454	Invalid reference to '!Item'.

2455	Invalid reference to property 'Item'.

2456	Invalid form number reference.

2457	Invalid report number reference.

2458	Invalid control number reference.

2459	Can't refer to Parent property in Design view.

2460	Can't refer to Dynaset property in Design view.

2461	Invalid section reference.

2462	Invalid section number reference.

2463	Invalid group level reference.

2464	Invalid group level number reference.

2465	Invalid reference to field 'Item'.

2466	Invalid reference to Dynaset property.

2467	Object referred to in expression no longer exists.

2469	Item1 in validation rule: 'Item2'.

2470	Item in validation rule.

2471	Item in query.

2472	Item in linked master field.

2473	Item1 in 'Item2' expression.

2474	No control is active.

2475	No form is active.

2476	No report is active.

2477	Invalid subclass 'Item' referred to in TypeOf function.

3000	Reserved error (Item); there is no message for this error.

3001	Invalid argument.

3002	Couldn't start session.

3003	Couldn't start transaction; too many transactions already nested.

3004	Couldn't find database 'Item'.

3005	'Item' isn't a valid database name.

3006	Database 'Item' is exclusively locked.

3007	Couldn't open database 'Item'.

3008	Table 'Item' is exclusively locked.

3009	Couldn't lock table 'Item'; currently in use.

3010	Table 'Item' already exists.

3011	Couldn't find object 'Item'.

3012	Object 'Item' already exists.

3013	Couldn't rename installable ISAM file.

3014	Can't open any more tables.

3015	Item' isn't an index in this table.

3016	Field won't fit in record.

3017	Field length is too long.

3018	Couldn't find field 'Item'.

3019	Operation invalid without a current index.

3020	Update without AddNew or Edit.

3021	No current record.

3022	Can't have duplicate key; index changes were unsuccessful.

3023	AddNew or Edit already used.

3024	Couldn't find file 'Item'.

3025	Can't open any more files.

3026	Not enough space on disk.

3027	Couldn't update; database is read-only.

3028	Couldn't initialize data access because file 'SYSTEM.MDA' couldn't be opened.

3029	Not a valid account name or password.

3030	'Item' isn't a valid account name.

3031	Not a valid password.

3032	Can't perform this operation.

3033	No permission for 'Item'.

3034	Commit or Rollback without BeginTrans.

3036	Database has reached maximum size.

3037	Can't open any more tables or queries.

3039	Couldn't create index; too many indexes already defined.

3040	Disk I/O error during read.

3041	Incompatible database version.

3042	Out of MS-DOS file handles.

3043	Disk or network error.

3044	'Item' isn't a valid path.

3045	Couldn't use 'Item'; file already in use.

3046	Couldn't save; currently locked by another user.

3047	Record is too large.

3048	Can't open any more databases.

3049	Can't open database <name>. File is corrupt or not a Microsoft Jet database.

3050	Couldn't lock file; SHARE.EXE hasn't been loaded.

3051	Couldn't open file 'Item'.

3052	MS-DOS file sharing lock count exceeded.  You need to increase the number of locks installed with SHARE.EXE.

3053	Too many client tasks.

3054	Too many Memo or Long Binary fields.

3055	Not a valid file name.

3056	Couldn't repair this database.

3057	Operation not supported on attached tables.

3058	Can't have Null value in index.

3059	Operation canceled by user.

3060	Wrong data type for parameter 'Item'.

3061	Item1 parameters were expected, but only Item2 were supplied.

3062	Duplicate output alias 'Item'.

3063	Duplicate output destination 'Item'.

3064	Can't open action query 'Item'.

3065	Can't execute a non-action query.

3066	Query must have at least one output field.

3067	Query input must contain at least one table or query.

3068	Not a valid alias name.

3069	Can't have action query 'Item' as an input.

3070	Can't bind name 'Item'.

3071	Can't evaluate expression.

3073	Operation must use an updatable query.

3074	Can't repeat table name 'Item' in FROM clause.

3075	Item1 in query expression 'Item2'.

3076	Item in criteria expression.

3077	Item in expression.

3078	Couldn't find input table or query 'Item'.

3079	Ambiguous field reference 'Item'.

3080	Joined table 'Item' not listed in FROM clause.

3081	Can't join more than one table with the same name (Item).

3082	JOIN operation 'Item' refers to a non-joined table.

3083	Can't use internal report query.

3084	Can't insert into action query.

3085	Undefined function 'Item' in expression.

3086	Couldn't delete from specified tables.

3087	Too many expressions in GROUP BY clause.

3088	Too many expressions in ORDER BY clause.

3089	Too many expressions in DISTINCT output.

3090	Resultant table may not have more than one Counter field.

3091	HAVING clause (Item) without grouping or aggregation.

3092	Can't use HAVING clause in TRANSFORM statement.

3093	ORDER BY clause (Item) conflicts with DISTINCT.

3094	ORDER BY clause (Item) conflicts with GROUP BY clause.

3095	Can't have aggregate function in expression (Item).

3096	Can't have aggregate function in WHERE clause (Item).

3097	Can't have aggregate function in ORDER BY clause (Item).

3098	Can't have aggregate function in GROUP BY clause (Item).

3099	Can't have aggregate function in JOIN operation (Item).

3100	Can't set field 'Item' in join key to Null.

3101	Join is broken by value(s) in fields 'Item'.

3102	Circular reference caused by 'Item'.

3103	Circular reference caused by alias 'Item' in query definition's SELECT list.

3104	Can't specify Fixed Column Heading 'Item' in a crosstab query more than once.

3105	Missing destination field name in SELECT INTO statement (Item).

3106	Missing destination field name in UPDATE statement (Item).

3107	Couldn't insert; no insert permission for table or query 'Item'.

3108	Record(s) can't be edited; no Update Data permission on <name>.

3109	Couldn't delete; no delete permission for table or query 'Item'.

3110	Couldn't read definitions; no read definitions permission for table or query 'Item'.

3111	Couldn't create; no create permission for table or query 'Item'.

3112	Couldn't read; no read permission for table or query 'Item'.

3113	Can't update 'Item'; field not updatable.

3114	Can't include Memo or Long Binary when you select unique values (Item).

3115	Can't have Memo or Long Binary in aggregate argument (Item).

3116	Can't have Memo or Long Binary in criteria (Item) for aggregate function.

3117	Can't sort on Memo or Long Binary (Item).

3118	Can't join on Memo or Long Binary (Item).

3119	Can't group on Memo or Long Binary (Item).

3120	Can't group on fields selected with '*' (Item).

3121	Can't group on fields selected with '*'.

3122	'Item' not part of aggregate function or grouping.

3123	Can't use '*' in crosstab query.

3124	Can't input from internal report query (Item).

3125	'Item' isn't a valid name.

3126	Invalid bracketing of name 'Item'.

3127	INSERT INTO statement contains unknown field name 'Item'.

3128	Must specify tables to delete from.

3129	Invalid SQL statement; expected 'DELETE', 'INSERT', 'PROCEDURE', 'SELECT', or 'UPDATE'.

3130	Syntax error in DELETE statement.

3131	Syntax error in FROM clause.

3132	Syntax error in GROUP BY clause.

3133	Syntax error in HAVING clause.

3134	Syntax error in INSERT statement.

3135	Syntax error in JOIN operation.

3136	Syntax error in LEVEL clause.

3137	Missing semicolon (;) at end of SQL statement.

3138	Syntax error in ORDER BY clause.

3139	Syntax error in PARAMETER clause.

3140	Syntax error in PROCEDURE clause.

3141	Syntax error in SELECT statement.

3142	Characters found after end of SQL statement.

3143	Syntax error in TRANSFORM statement.

3144	Syntax error in UPDATE statement.

3145	Syntax error in WHERE clause.

3146	ODBC [image] call failed.

3147	ODBC [image] data buffer overflow.

3148	ODBC [image] connection failed.

3149	ODBC [image] incorrect DLL.

3150	ODBC [image] missing DLL.

3151	ODBC [image] connection to 'Item' failed.

3152	ODBC [image] incorrect driver version 'Item1'; expected version 'Item2'.

3153	ODBC [image] incorrect server version 'Item1'; expected version 'Item2'.

3154	ODBC [image] couldn't find DLL 'Item'.

3155	ODBC [image] insert failed.

3156	ODBC [image] delete failed.

3157	ODBC [image] update failed.

3158	Couldn't save record; currently locked by another user.

3159	Not a valid bookmark.

3160	Table isn't open.

3161	Couldn't decrypt file.

3162	Null is invalid.

3163	Couldn't insert or paste; data too long for field.

3164	Couldn't update field.

3165	Couldn't open .INF file.

3166	Missing memo file.

3167	Record is deleted.

3168	Invalid .INF file.

3169	Illegal type in expression.

3170	Couldn't find installable ISAM.

3171	Couldn't find net path or user name.

3172	Couldn't open PARADOX.NET.

3173	Couldn't open table 'MSysAccounts' in SYSTEM.MDA.

3174	Couldn't open table 'MSysGroups' in SYSTEM.MDA.

3175	Date is out of range or is in an invalid format.

3176	Couldn't open file 'Item'.

3177	Not a valid table name.

3178	Out of memory.

3179	Encountered unexpected end of file.

3180	Couldn't write to file 'Item'.

3181	Invalid range.

3182	Invalid file format.

3183	Not enough space on temporary disk.

3184	Couldn't execute query; couldn't find linked table.

3185	SELECT INTO remote database tried to produce too many fields.

3186	Couldn't save; currently locked by user 'Item2' on machine 'Item1'.

3187	Couldn't read; currently locked by user 'Item2' on machine 'Item1'.

3188	Couldn't update; currently locked by another session on this machine.

3189	Table 'Item1' is exclusively locked by user 'Item3' on machine 'Item2'.

3190	Too many fields defined.

3191	Can't define field more than once.

3192	Couldn't find output table 'Item'.

3193	No UserName.

3194	No machine name.

3196	Couldn't use 'Item'; database already in use.

3197	Data has changed; operation stopped.

3198	Couldn't start session.  Too many sessions already active.

3199	Couldn't find reference.

3200	Can't delete or change record. Related records exist in table 'Item' that would violate referential integrity.

3201	Can't add or change record.  Referential integrity rules require a related record in table 'Item'.

3202	Couldn't save; currently locked by user 'Item2' on machine 'Item1'.

3203	Can't specify subquery in expression (Item).

3204	Database already exists.

3205	Too many crosstab column headers (Item).

3206	Can't create a relationship between a field and itself.

3207	Operation not supported on Paradox table with no primary key.

3208	Invalid Deleted entry in [dBASE ISAM] section in INI file.

3209	Invalid Stats entry in [dBASE ISAM] section in INI file.

3210	Connect string too long.

3211	Couldn't lock table 'Item'; currently in use.

3212	Couldn't lock table 'Item1'; currently in use by user 'Item3' on machine 'Item2'.

3213	Invalid Date entry in [dBASE ISAM] section in INI file.

3214	Invalid Mark entry in [dBASE ISAM] section in INI file.

3215	Too many Btrieve tasks.

3216	Parameter 'Item' specified where a table name is required.

3217	Parameter 'Item' specified where a database name is required.

3218	Couldn't update; currently locked.

3219	Invalid Operation.

3220	Wrong Paradox sort sequence.

3221	Invalid entries in [Btrieve ISAM] section in WIN.INI.

3222	Query can't contain a Database parameter.

3223	'Item' isn't a valid parameter name.

3224	Btrieve [image] data dictionary is corrupted.

3225	Encountered record locking deadlock while performing Btrieve operation.

3226	Errors encountered while using the Btrieve DLL.

3227	Invalid Century entry in [dBASE ISAM] section in INI file.

3228	Invalid CollatingSequence entry in [Paradox ISAM] section in INI file.

3229	Btrieve [image] can't change field.

3230	Out-of-date Paradox lock file.

3231	ODBC [image] field would be too long; data truncated.

3232	ODBC [image] couldn't create table.

3233	ODBC [image] incorrect driver version.

3234	ODBC [image] remote query timeout expired.

3235	ODBC [image] data type not supported on server.

3236	ODBC [image] encountered unexpected Null value.

3237	ODBC [image] unexpected type.

3238	ODBC [image] data out of range.

3239	Too many active users.

3240	Btrieve [image] missing WBTRCALL.DLL.

3241	Btrieve [image] out of resources.

3242	Invalid reference in SELECT statement.

3243	None of the import field names match fields in the appended table.

3244	Can't import password-protected spreadsheet.

3245	Couldn't parse field names from first row of import table.

3246	Operation not supported in transactions.

3247	ODBC [image] linked table definition has changed.

3248	Invalid NetworkAccess entry in INI file.

3249	Invalid PageTimeout entry in INI file.

3250	Couldn't build key.

3251	Feature not available.

3252	Illegal reentrancy during query execution.

3254	ODBC [image] Can't lock all records.

3255	ODBC [image] Can't change connect string parameter.

3256	Index file not found.

3257	Syntax error in WITH OWNERACCESS OPTION declaration.

3258	Query contains ambiguous (outer) joins.

3259	Invalid field data type.

3260	Couldn't update; currently locked by user 'Item2' on machine 'Item1'.

3261	Item

3262	Table in use.

3263	Invalid database object.

3264	No fields defined - cannot append table

3265	Name not found in this collection.

3266	Append illegal - field is part of a TableDefs collection.

3267	Property can be set only when the field is part of a Recordset object's Fields collection.

3268	Cannot set the property of an object once it is part of a collection.

3269	Append illegal - Index is part of a TableDefs collection

3270	Property not found.

3271	Invalid property value.

3272	Object isn't a collection.

3273	Method not applicable for this object.

3274	External table isn't in the expected format.

3275	Unexpected error from external database driver (Item).

3276	Invalid database ID.

3277	Can't have more than 10 fields in an index.

3278	Database engine has not been initialized.

3279	Database engine has already been initialized.

3280	Can't delete a field that is part of an index.

3281	Can't delete this index.  It is either the current index or is used in a relationship.

3282	Can't define field or index in a table that contains data.

3283	Primary key already exists.

3284	Index already exists.

3285	Invalid index definition.

3286	Format of memo file doesn't match specified external database format.

3287	Can't create index on a one-byte field, Memo field or Long Binary field.

3288	Paradox: No primary index.

3289	Syntax error In CONSTRAINT Clause.

3290	Syntax error in CREATE TABLE statement.

3291	Syntax error in CREATE INDEX statement.

3292	Syntax error in column definition.

3293	Syntax error in ALTER TABLE statement.

3294	Syntax error in DROP INDEX statement.

3295	Syntax error in DROP TABLE or DROP INDEX statement.

3296	Join expression not supported.

3297	Couldn't import. No records found or all records contained errors.

3298	Several tables exist with that name; please specify owner, as in 'owner.table'.

3299	ODBC Specification Conformance Error (<message>).  This error should be reported to the ODBC driver vendor.

3300	Can't create a relationship.

3301	Can't perform this operation; features in this version are not available in databases with older formats.

3302	Can't change a rule while the rules for this table are in use.

3303	Can't delete this field.  It's part of one or more relationships.

3304	You must enter a personal identifier (PID) consisting of at least four and no more than 20 characters and digits.

3305	Invalid connection string in pass-through query.

3306	At most one field can be returned from a subquery that doesn't use the EXISTS keyword.

3307	The number of columns in the two selected tables or queries of a union query don't match.

3308	Invalid TOP argument in select query.

3309	Property setting can't be larger than 2 KB.

3310	This property isn't supported for external data sources or for databases created in a previous Jet version.

3311	Property specified already exists.

3312	Validation rules and default values can't be placed on system tables nor on attached tables.

3313	Can't place this validation expression on this field.

3314	Field <name> can't contain a null value.

3315	Field <name> can't be a zero-length string.

3316	<Table-level validation text>.

3317	One or more values entered is prohibited by the validation rule <rule> set for <name>.

3318	Top not allowed in delete queries.

3319	Syntax error in union query.

3320	<Error> in table-level validation expression.

3321	No database specified in connection string or IN clause.

3322	Crosstab query contains one or more invalid fixed column headings.

3323	Query does not return records.

3324	Execute method must be used on action or data-definition queries.

3325	Pass-through query with ReturnsRecords property set to True did not return any records.

3326	This Recordset is not updatable.

3334	Can be present only in version 1.0 format.

3336	Btrieve: Invalid IndexDDF option in <initialization (.INI) file>.

3337	Invalid DataCodePage option in <initialization (.INI) file>.

3338	Btrieve: Xtrieve options aren't correct in <initialization (.INI) file>.

3339	Btrieve: Invalid IndexDeleteRenumber option in <initialization (.INI) file>.

3340	Query <name> is corrupt.

3341	Current field must match join key <name> on 'one' side of outer join.

3342	Invalid Memo or OLE object in subquery <name>.

3344	Unknown or invalid reference (<name>) in validation expression or default value in table <name>.

3345	Unknown or invalid field reference <name>.

3346	Number of query values and destination fields aren't the same.

3349	Numeric field overflow.

3350	Object is invalid for operation or no longer exists.

3351	ORDER BY expression <expression> uses non-output fields.

3352	No destination field name in INSERT INTO statement <statement>.

3353	Btrieve: Can't find file FIELD.DDF.

3354	At most one record can be returned by this subquery.

3355	Syntax error in default value.

3356	Can't open this database exclusively.  The database is opened by user <name> on machine <name>.

3358	Can't open Microsoft Access system database (typically SYSTEM.MDA).

3359	Pass-through query must contain at least one character.

3360	Query is too complex.

3361	Unions not allowed in a subquery.

3362	Single-row update/delete affected more than one row of an attached table.  Unique index contains duplicate values.

3364	Can't use Memo or OLE object field <name> in SELECT clause of a union query.

3365	Can't set this property for remote objects.

3366	Can't append a relation with no fields defined.

3367	Can't append.  Object already in collection.

3368	Relationship must be on the same number of fields with the same data types.

3370	Can't modify the design of table <name>; it's in a read-only database.

3371	Can't find table or constraint.

3372	No such index <name> on table <name>.

3373	Can't create relationship; referenced table <name> doesn't have a primary key.

3374	The specified fields are not uniquely indexed in table <name>.

3375	Table <name> already has an index named <name>.

3376	Table <name> doesn't exist.

3377	No such relationship <name> on table <name>.

3378	There is already a relationship named <name> in the current database.

3379	Can't create relationships.  Existing data in table <name> violates referential integrity rules in table <name>.

3380	Field <name> already exists in table <name>.

3381	There is no field named <name> in table <name>.

3382	Field <name> size must be from 1 to 255.

3383	Can't delete field <name>.  It's part of one or more relationships.

3384	Can't delete a built-in property.

3385	User-defined properties don't support a Null value.

3386	Property <name> must be set before using this method.

3387	Can't find TEMP directory.

3388	Unknown function <name> in validation expression or default value on <name>.

3389	Query support unavailable.

3390	Account name already exists.

3393	Can't perform join, group, or sort.  Combined fields are too long.

3394	Can't save property; property is a schema property.

3396	Can't perform cascading operation.  Records exist in table <name> that  can violate referential integrity rules.

3397	Can't perform cascading operation.  There must be a related record in table <name>.

3398	Can't perform cascading operation.  It would result in a null key in table <name>.

3399	Can't perform cascading operation.  It would result in a duplicate key in table <name>.

3400	Can't perform cascading operation.  It would result in two updates to field <name> in table <name>.

3401	Can't perform cascading operation.  It would cause field <name> to become null, which is not allowed.

3402	Can't perform cascading operation.  It would cause field <name> to become a zero-length string.

3403	Can't perform cascading operation: <validation text>.

3404	Can't perform cascading operation.  Value entered violates the validation rule <rule> set for field <name>.

3405	Error <error text> in validation rule.

3406	Error <error text> in default value.

3407	The server's MSysConf table exists, but is in an incorrect format.  Contact your system administrator.

3409	Invalid field name <name> in definition of index or relationship.

3410	Can't open this database for update.

3411	Invalid entry. Can't perform cascading operation in table <name>. Value is too long for field <name>.

3412	Can't perform cascading update on table <name> because it is currently in use by user <name> on machine <name>.

3414	Can't perform cascading update on table <name> because it is currently in use.

3415	Zero-length string is valid only in a text or Memo field.

3418	Can't open <tablename>. Another user has the table open using a different network control file or locking style.

3419	Can't open this Paradox 4.x table because ParadoxNetStyle is set to 3.x in <initialization (.INI) file>.

3420	Object is not valid.

3421	Data type conversion error.

3422	Can't modify table structure. Another user has the table open.

3423	You cannot use ODBC to attach an external Microsoft Access or ISAM database table to your database.

3428	The Jet database engine has found a problem in your database.  You must repair and compact the database.

3429	You are attempting to use an Installable ISAM that is incompatible with this version of Jet.

3430	While loading the Excel installable ISAM, OLE was unable to initialize

3431	This is not an Excel 5 file.

3432	Error opening an Excel 5 file

3433	Invalid parameter in [Excel ISAM] section of the <filename> initialization file

3434	Can't expand named range

3435	Cannot delete Excel cells

3436	Failure creating Excel file

3437	Excel spreadsheet is full

3438	File specification and data do not match

3439	Can't attach or import Word mail merge file

3440	Text file has no columns.

3442	Error in <entry> entry of the <section> section in the <path> file

3443	Can't create fixed width text file without column specification

3444	Column width required in schema.ini file.

3751	Search string has unmatched brackets