CreateProperty Method

Applies To

Database Object, Field Object, Index Object, QueryDef Object, TableDef Object.

Description

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 an 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 the Properties collection of an object 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 the collection, use the Delete method on the Properties collection. You can't delete built-in properties.

Note

If you omit the fDDL part, it defaults to False (non-DDL). Because no corresponding DDL property is exposed, you must delete and re-create a Property object you want to change from DDL to non-DDL.

See Also

Append Method, Delete Method, Name Property, Type Property, Value Property.

Specifics (Microsoft Access)

Microsoft Access defines a number of properties on data access objects. These properties are not automatically recognized by the Microsoft Jet database engine. In order to set or return values for a Microsoft Access-defined property in Visual Basic, you must specifically add the property to the Properties collection of the object to which it applies. You can do this by using the CreateProperty method to create the property and then appending it to the Properties collection.

A Microsoft Access-defined property is automatically added to the Properties collection when it is first set from the Microsoft Access window. If the property has already been set in this way, then you don't need to add it to the Properties collection.

When you write code to set a Microsoft Access-defined property, you should include an error-handling routine that creates a Property object representing that property and appends it to the Properties collection if it does not already exist in the collection.

When you refer to a Microsoft Access-defined property in Visual Basic, you must explicitly refer to the Properties collection. For example, you would refer to the AppTitle property in the following manner, once it exists within the Properties collection of a Database object representing the current database.

Dim dbs As Database
Set dbs = CurrentDb
dbs.Properties!AppTitle = "Northwind Traders"

Note

You need to create and append only the Microsoft Access properties that apply to data access objects. You can set other Microsoft Access properties in Visual Basic using the standard object.property syntax.

Example

This example creates a new Property object.

Dim prpPrivilege As Property
Dim dbsNorthwind As Database
Set dbsNorthwind = DBEngine.Workspaces(0).OpenDatabase("Northwind.mdb")
' Create new Property object.
Set prpPrivilege = dbsNorthwind.CreateProperty("Privilege")
' Set other properties of prpPrivilege.
prpPrivilege.Type = dbBoolean
prpPrivilege.Value = True
' Save Property definition by appending it to Properties collection.
dbsNorthwind.Properties.Append prpPrivilege

Example (Microsoft Access)

The following example sets the Subject property. The Subject property is a database property that can also be set on the Summary tab of the Database Properties dialog box, available by clicking Database Properties on the File menu.

The Subject property applies to a data access object — the SummaryInfo Document object. However, it is defined by Microsoft Access, so the Microsoft Jet database engine does not automatically recognize it. Therefore, you must specifically add this property to the Properties collection of the Document object before you can set it. If the property does not exist in the Properties collection, Microsoft Access will generate an error when you attempt to set it.

In the following example, if Microsoft Access generates an error upon trying to set the Subject property, the error-handling routine creates the property and appends it to the Properties collection.

Sub SetAccessProperty()
    Dim dbs As Database, ctr As Container, doc As Document
    Dim prp As Property

    ' Enable error handling.
    On Error GoTo ErrorHandler
    ' Return Database variable pointing to current database.
    Set dbs = CurrentDb
    ' Return Container variable pointing to Databases container.
    Set ctr = dbs.Containers!Databases
    ' Return Document variable pointing to SummaryInfo document.
    Set doc = ctr.Documents!SummaryInfo
    ' Attempt to set Subject property.
    doc.Properties!Subject = "Business Contacts"
    Exit Sub

ErrorHandler:
    ' Check number of error that has occurred.
    If Err.Number = 3270 Then
        ' Create Subject property and set its value.
        Set prp = doc.CreateProperty("Subject", dbText, _
            "Business Contacts")
        ' Append property.
        doc.Properties.Append prp
        ' Resume main procedure.
        Resume Next
    Else
        ' If different error has occurred, display message.
        MsgBox "Unknown error!", vbCritical
    End If
End Sub