Managing Data and Working with Databases

This group of objects encapsulates the database capabilities of the Application. Two major object models exist to support this group: the database engine (McDBLib) and the data manager (McAddinData).  The database capabilities of the applicaiton include:

• Storing image objects and files with extracted data.
• Storing files.
• Searching for specific database content.
• Adding, searching, and persistently storing user-defined information; organized in a user-defined structure.
• Managing Database sets.

Examples:

The following examples illustrate some of the more common uses of the Database capabilities of the application and demonstrate some aspects of both object models described above.  All applications may be run in either VBA or compiled Visual Basic.

Creating and manipulating a database.

• This example shows how to create a new database, open it, save a position in it, and add 2 database folders to it.
• The position bookmarked in the created database is held by the Current node of the TargetDataNodes.  The 'Target' is a spot chosen by the user in the database hierarchy.  It may be set programatically, as shown below, or through the user interface by opposite-clicking a database folder or node in the Tree or Folder View and selecting Set Target from the context menu that opens.  It is represented by boldface printing of its text label in the database user interface.

Public Sub MakeTwoFolderDatabase()

   ' Use DataManager's CreateDatabase to create an application compliant database

   Application.DataManager.CreateDatabase "MyAppDB"

   ' Use Datamanager's TargetDataNodes to open the database and to save a current path position.

   Application.DataManager.TargetDataNodes.Current.SetNode "//MyAppDB\"

   ' Add a Database folder to the saved current path position.

   Application.DataManager.TargetDataNodes.AddFolder "MyFolder in MyAppDB"

   ' Add another Database folder to the saved current path position.

   Application.DataManager.TargetDataNodes.AddFolder "AnotherFolder in MyAppDB"

   ' Application.DataManager.TargetDataNodes.Current will continue to hold "//MyAppDB\"

   ' after this function ends

End Sub

• This example shows how to create a new attribute field for all files, except image files, stored in a database.
• The Database Engine is instructed to find the Demo Database and then find the structure (McDBType) of all of the McFiles database objects in it.  Once found, a new attribute for character (string) data is created with the name "RelatedProject".  After execution, each McFile object in the Demo database will have a RelatedProject attribute that may be assigned, read, and searched.

Public Sub CreateNewMcFilesField()

   ' Add an attribute (field) to all objects of type 'McFiles' in Demo database

   Application.Databases("Demo").Types("McFiles").Attributes.Add("RelatedProject", mcdbString)

End Sub

Note that if the above macro fails with a run-time error 91: Object variable or With block variable not set, it is likely because the Demo database is not open or does not exist.

Storing images and files

• This example shows how to store the currently viewed image into the database.
• The Image will be stored into the user hierarchy as a child of the 'Target', described under Creating and Manipulating a Database, above.
• The Description attribute of the newly added database object (McDBNode) is assigned to "Added by a Macro".

Public Sub StoreActiveImageToTarget()

   ' Add the image object to database and remember the new database object.

   Dim dbnodeAdded as McDBNode

   Set dbnodeAdded = Application.DataManager.TargetDataNodes.AddObject( Application.ActiveImage )

   ' Now assign a new value to the Description

   dbnodeAdded.Attributes("Description") = "Added by a Macro"

End Sub

• This example shows how to store a file into the database.
• The File will be stored into the user hierarchy as a child of the 'Target', described under Creating and Manipulating a Database, above.

Public Sub StoreFileToTarget()

   ' Add the file at the given path into the database as a child of 'Target'.

   Application.DataManager.TargetDataNodes.AddFile "C:\Temp\SomeFile.txt"

End Sub

• This example illustrates how to execute code when the Data Manager triggers one of its many event notifications.
• The code in this example displays the McDBNode Path and Author attribute of all files added to the 'Target' destination.  It then assigns a value of Marco Macro to the newly added McDBNode for the file.  See Creating and Manipulating a Database, above for description of the 'Target'.
• For more information about enabling event functions see the 'WithEvents' option of the VBA Dim statement in the Microsoft Visual Basic Help.

Dim WithEvents MyDataManagerVariable as McDataManager
Set MyDataManagerVariable = Application.DataManager

Public Sub MyDataManagerVariable_AfterAddNodeFile(ByVal pnoderefCurrent As McDataNodeRef, _                                                                                     ByVal pmcdbnodeAddedNode As McDBNode, _                                                                                ByVal eStorage As McDataNodeStorageMethods)

      ' Is the file being added to the 'Target'?

    If pnoderefCurrent.ID = Application.DataManager.TargetDataNodes.Current.ID Then

       ' Display the original author and path of the new database object to the VBA debug window

       Debug.Print pmcdbnodeAddedNode.Path(True), "Author was:"; pmcdbnodeAddedNode.Attributes("Author")

       ' Assign Marco Macro to the Author attribute

       dbnodeAdded.Attributes("Author") = "Marco Macro"

       ' ReDisplay the author and path of the new database object to the VBA debug window

       Debug.Print pmcdbnodeAddedNode.Path(True), "Author is:"; pmcdbnodeAddedNode.Attributes("Author")

   End If

End Sub

Note that the above macro requires proper scoping of the MyDataManagerVariable object (e.g. within a UserForm).  To see the effects of this macro from VBA, create a UserForm and place the Dim statement in its Declarations section and place the Set command the UserForm's Show event.  Then display the UserForm modeless (mccdsModeless), set the Target, and add a File to the Target.  The results will appear in the VBA immediate window and the Author attribute of the added file in the database user interface.

Retrieving and displaying images and data

• This example shows how to open the database objects selected by the user.
• The Application.DataManager.SelectedDataNodes object represents the objects selected in the user-interface.
• For most objects types, NodeOpen will show the object in a window.

Public Sub OpenSelection()

       Application.DataManager.SelectedDataNodes.NodeOpen

End Sub

• This example shows how to specify a group of database objects and open them. 
• The Application.DataManager.ActiveDataNodes collection is not associated with any user-interface and may be configured in any way by a macro programmer.
• The Application.DataManager.ActiveDataNodes collection is emptied, then populated with the children of a given database path.  Once defined, the NodeOpen method opens the specified ActiveDataNodes.

Public Sub OpenDemoSamples()

   ' Clear the ActiveDataNodes

   Application.DataManager.ActiveDataNodes.Selection.RemoveAll

   ' Add all children of Samples in the Demo Database

   Application.DataManager.ActiveDataNodes.Selection.AddChildren "//Demo\Sample\"

   ' Open the .Data on all of the selected objects

   Application.DataManager.ActiveDataNodes.NodeOpen 

End Sub

• This example shows how retrieve a database object and display its attributes.

Public Sub GetNodeAttributes()

   ' Find and remember the first child of //Demo\Samples

   Dim dbnodeChild as McDBNode

   Dim ThisAttribute as Variant

   set dbnodeChild = Application.Databases.RetrieveNode("//Demo\Sample").Children(0)

   ' Display the Attributes of the retrieved McDBNode

   Debug.Print "Attributes of node: "; dbnodeChild.Path(True, True)

   For Each ThisAttribute in dbnodeChild.Attributes

       Debug.Print ThisAttribute, "=";                    ' The Attribute's name

       Debug.Print dbnodeChild.Attributes(ThisAttribute)  ' The Attribute's value

   Next

End Sub

Note: The results from this macro will appear in the VBA immediate window.

Querying a database

• This example shows how to search a database for specific content
• Matching objects are saved to a folder in the Journal.
• The illustrated query finds all multiframe sequences in the Demo database.

Public Sub MakeQueryResults()

   ' Create and remember a search query for the whole 'Demo' database.

   Dim mcdbqueryDemo as McDBQuery

   Set mcdbqueryDemo = Application.Databases.Item("Demo").CreateQuery

   If mcdbqueryDemo Is Nothing then Stop

   ' set the search criteria to objects whose 'FileFormat' is "SEQ" and FrameCount is greater

   ' than or equal to 1.

   mcdbqueryDemo.SetAttribute "FileFormat", "SEQ", mcdbEQ Or mcdbIgnoreCase

   mcdbqueryDemo.SetAttribute "FrameCount", 1, mcdbGTE

   ' Execute the query and save the resultant database object to a folder in the Journal.

   Application.DataManager.MakeQuery mcdbqueryDemo, mcdatmqc_UseQuery, , , _

      "Sequences in Demo Database"

End Sub

Where to go from here

Understanding of both the McDBLib and McDataAddin object models is necessary to fully utilize the database capabilities of the application, as each model serves a particular purpose.  The McDataAddin objects facilitate accomplishment of most tasks.  As the examples illustrate, McDataAddin objects can create and manipulate databases, store images, and automatically generate and store core information about them.  However, the objects representing the information in a database, even those created or manipulated by the McDataAddin, are McDBLib objects, so understanding of these objects and their interactions is likely necessary to do customized processessing or manipulation of data.  Further, some advanced features, such as database security and transactions, may only be manipulated through McDBLib objects.

• The McDBLib object model root is exposed via the Databases property of the Application.  These objects, prefaced with 'McDB', are the low-level, native database objects.  They encapsulate the raw data, but do not provide much of the high-level intelligence and automatic processing that happens in the user interface.  For detailed information about the database engine architecture and its features, read the Database Engine Overview and McDBDatabases object model topics.
• The McDataAddin object model root is exposed by the DataManager property of the Application.  These objects, prefaced with 'McData', specialize and extend the McDBLib API, providing specific database structure and uniform access to database objects for the Application.  For detailed information about these objects, read the McAddInData Overview and DataManager object model topics.
• The indicated topics provide more detailed and comprehensive documentation and examples of both object models.