CreateProperty Method

Applies To Database object, Document object, Field object, Index object, QueryDef object, TableDef object.

Description

Creates a new user-defined Property object (Microsoft Jet workspaces only).

Syntax

Set property = object.CreateProperty(name, type, value, DDL)

The CreateProperty method syntax has these parts.

Part	Description

property	An object variable that represents the Property object you want to create.
object	An object variable that represents the Database, Field, Index, QueryDef, Document, or TableDef object you want to use to create the new Property object.
name	Optional. A Variant (String subtype) that uniquely names the new Property object. See the Name property for details on valid Property names.
type	Optional. A constant that defines the data type of the new Property object. See the Type property for valid data types.
value	Optional. A Variant containing the initial property value. See the Value property for details.
DDL	Optional. A Variant (Boolean subtype) that indicates whether or not the Property is a DDL object. The default is False. If DDL is True, users can't change or delete this Property object unless they have dbSecWriteDef permission.

Remarks You can create a user-defined Property object only in the Properties collection of an object that is persistent.

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 Name, Type, and Value property topics for more details.

If name refers to an object that is already a member of the collection, a run-time 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 DDL argument, 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.

For example, Microsoft Access defines the Description property of a TableDef object. If this property hasn't already been set from table Design view, you must use the CreateProperty method to create the property and then append it to the Properties collection in order to set the property from Visual Basic.

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 DAO objects. You can set other Microsoft Access properties in Visual Basic by using the standard object.property syntax.

Example

This example tries to set the value of a user-defined property. If the property doesn't exist, it uses the CreateProperty method to create and set the value of the new property. The SetProperty procedure is required for this procedure to run.

Sub CreatePropertyX()

    Dim dbsNorthwind As Database
    Dim prpLoop As Property

    Set dbsNorthwind = OpenDatabase("Northwind.mdb")

    ' Set the Archive property to True.
    SetProperty dbsNorthwind, "Archive", True
    
    With dbsNorthwind
        Debug.Print "Properties of " & .Name
        
        ' Enumerate Properties collection of the Northwind
        ' database.
        For Each prpLoop In .Properties
            If prpLoop <> "" Then Debug.Print "    " & _
                prpLoop.Name & " = " & prpLoop
        Next prpLoop

        ' Delete the new property since this is a
        ' demonstration.
        .Properties.Delete "Archive"

        .Close
    End With

End Sub

Sub SetProperty(dbsTemp As Database, strName As String, _
    booTemp As Boolean)

    Dim prpNew As Property
    Dim errLoop As Error

    ' Attempt to set the specified property.
    On Error GoTo Err_Property
    dbsTemp.Properties("strName") = booTemp
    On Error GoTo 0

    Exit Sub

Err_Property:

    ' Error 3270 means that the property was not found.
    If DBEngine.Errors(0).Number = 3270 Then
        ' Create property, set its value, and append it to the
        ' Properties collection.
        Set prpNew = dbsTemp.CreateProperty(strName, _
            dbBoolean, booTemp)
        dbsTemp.Properties.Append prpNew
        Resume Next
    Else
        ' If different error has occurred, display message.
        For Each errLoop In DBEngine.Errors
            MsgBox "Error number: " & errLoop.Number & vbCr & _
                errLoop.Description
        Next errLoop
        End
    End If

End Sub

Example (Microsoft Access)

The first procedure in the following example, the SetAccessProperty function, is a generic function that you can use to set a property. If the property you wish to set already has a corresponding Property object in the Properties collection, the function simply sets the property to the desired value. If the property does not have a corresponding Property object in the Properties collection, then the function creates the Property object and appends it to the Properties collection.

The second procedure sets the Subject property using the SetAccessProperty function. 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 DAO object — the SummaryInfo Document object, which is defined by Microsoft Access. If the Subject property doesn't already exist in the Properties collection for the SummaryInfo Document object, the SetAccessProperty function adds it.

Function SetAccessProperty(obj As Object, strName As String, _
        intType As Integer, varSetting As Variant) As Boolean
    Dim prp As Property
    Const conPropNotFound As Integer = 3270

    On Error GoTo ErrorSetAccessProperty
    ' Explicitly refer to Properties collection.
    obj.Properties(strName) = varSetting
    obj.Properties.Refresh
    SetAccessProperty = True
    
ExitSetAccessProperty:
    Exit Function
ErrorSetAccessProperty:
    If Err = conPropNotFound Then
        ' Create property, denote type, and set initial value.
        Set prp = obj.CreateProperty(strName, intType, varSetting)
        ' Append Property object to Properties collection.
        obj.Properties.Append prp
        obj.Properties.Refresh
        SetAccessProperty = True
        Resume ExitSetAccessProperty
    Else
        MsgBox Err & ": " & vbCrLf & Err.Description
        SetAccessProperty = False
        Resume ExitSetAccessProperty
    End If
End Function

The following procedure calls the SetAccessProperty function to set the Subject property.

Sub CallPropertySet()
    Dim dbs As Database, ctr As Container, doc As Document
    Dim blnReturn As Boolean
    
    ' Return reference to current database.
    Set dbs = CurrentDb
    ' Return reference to Databases container.
    Set ctr = dbs.Containers!Databases
    ' Return reference to SummaryInfo document.
    Set doc = ctr.Documents!SummaryInfo
    blnReturn = SetAccessProperty(doc, _
        "Subject", dbText, "Business Contacts")
    ' Evaluate return value.
    If blnReturn = True Then
        Debug.Print "Property set successfully."
    Else
        Debug.Print "Property not set successfully."
    End If
End Sub