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