Append Method

Applies To

Documents Collection; Fields Collection; Groups Collection; Indexes Collection; Properties Collection; QueryDefs Collection; Relations Collection; TableDefs Collection; Users Collection; Workspaces Collection.

Description

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 of an Index object 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 haven't specified a 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 you 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

See Also

Delete Method, GetChunk Method, Refresh Method, Type Property.

Example

The following example defines a new field and appends it to a Fields collection.

Dim dbsBiblio As Database, fldPhone As Field, tdfAuthors As TableDef
            ' Open a database.
Set dbsBiblio = DBEngine.Workspaces(0).OpenDatabase("Biblio.mdb")
Set tdfAuthors = dbsBiblio.TableDefs("Authors")
Set fldPhone = dbsBiblio.CreateField()
fldPhone.Name = "Phone"    ' Set field properties.
fldPhone.Type = dbText
fldPhone.Size = 15
' Append field to collection.
dbsBiblio.tdfAuthors.Fields.Append fldPhone
dbsBiblio.tdfAuthors.Fields.Delete "Phone"
dbsBiblio.Close

Example (Microsoft Access)

The following example defines a new Field object and appends it to the Fields collection of a TableDef object.

Sub NewField()
    Dim dbs As Database, tdf As TableDef, fld As Field

    ' Return Database variable that points to current database.
    Set dbs = CurrentDb
    Set tdf = dbs.TableDefs!Employees
    ' Create new field in Employees table.
    Set fld = tdf.CreateField("SocialSecurity#", dbText, 15)
    ' Append field to collection.
    dbs.TableDefs!Employees.Fields.Append fld
End Sub

Example (Microsoft Excel)

This example creates a new database (NWINDEX.MDB). The example attaches two tables from the C:\Program Files\Common Files\Microsoft Shared\MSquery folder to the database. (On Windows NT™, the two tables are in the \WINDOWS\MSAPPS\MSQUERY folder.)

Const sourceDir = "C:\Program Files\Common Files\Microsoft Shared\"

Sub createNWindEx()
    Dim nWindEx As Database, customerTable As TableDef, _
        supplierTable As TableDef
    Dim dataSource As String
    dataSource = "dbase IV;DATABASE=" & sourceDir & "MSquery"    appPath = Application.Path
    Set nWindEx = Workspaces(0).CreateDatabase(Application.Path _
        & "\NWINDEX.MDB", dbLangGeneral)
    Set customerTable = nWindEx.CreateTableDef("Customer")
    customerTable.Connect = dataSource
    customerTable.SourceTableName = "Customer"
    nWindEx.TableDefs.Append customerTable
    Set supplierTable = nWindEx.CreateTableDef("Supplier")

    supplierTable.Connect = dataSource
    supplierTable.SourceTableName = "Supplier"
    nWindEx.TableDefs.Append supplierTable
    MsgBox "The database " & nWindEx.Name & " has been created."
    nWindEx.Close
End Sub