Duwamish Books, Phase 3.5: VBA Application Programmability Model

Ade Miller
Summit Software Company

December 1999

Summary: Details the programmability models against which the VBA programmer writes customizations. Discusses:

Introduction

The VBA programmer writes customization code against an object or programmability model specific to the application. VBA also provides an object model for the MT Designer, which is also discussed in this document.

MT VBA Object Model

MT VBA Projects can sink four events off of an intrinsic object called ApplicationInstance. One of these events, OnConnection, is used to pass the object model of the application in. The project can then sink events off of that object to respond to events relating to that application. The Modifier client automatically adds boilerplate code to new MT Projects to create a local copy of the passed in application object.

ApplicationInstance.Initialize event

Description

Called when the VBA runtime first loads the MT project DLL when IVbaMt::LoadAllRegMTDlls or IVbaMT::LoadMTDll are called.

Visual Basic signature

Public Event Initialize()

ApplicationInstance.Terminate event

Description

Called when the VBA runtime unloads the MT project DLL when IVbaMTDlls::Release or IVbaMTDll::Unload are called.

Visual Basic signature

Public Event Terminate()

ApplicationInstance.OnConnection event

Description

Called when the VBA runtime first loads the MT project DLL in IVbaMt::LoadAllRegMTDlls or IVbaMT::LoadMTDll. This call provides the object model of the app for the project.  The project then should keep a reference to the application and sink events off of it.

Visual Basic signature

For the order programmability model:

Public Event OnConnection(ByVal Application As _
               VbaOrderObjectModel.Application, _
               ByVal MTDllInst As Object, Custom() As Variant)

For the buyer programmability model:

Public Event OnConnection(ByVal Application As _
               VbaBuyerObjectModel.Application, _
               ByVal MTDllInst As Object, Custom() As Variant)

Parameters

ApplicationInstance.OnDisconnection event

Description

Called when the VBA runtime unloads the MT project DLL when IVbaMTDlls::Release or IVbaMTDll::Unload are called.

Visual Basic signature

Public Event OnDisconnection(Custom() As Variant)

Parameter

Order Programmability Model

Application.Order object

Description

Returns an Order object that represents the order that the customer submitted.

Visual Basic signature

Public Property Get Order() As Order

Return type

Order: The order that the customer submitted.

Application.InsertOrderStart event

Description

Allows the VBA programmer to abort the transaction by setting the Cancel parameter to True.

Visual Basic signature

Public Event InsertOrderStart(Order As ADODB.Recordset,_
                  ByRef Cancel As Boolean)

Parameters

Application.InsertOrderEnd event

Description

Should allow the VBA programmer to abort the transaction.

Visual Basic signature

Public Event InsertOrderEnd()

Application.LogEvent method

Description

Write an event to the Windows Application Event Log.

Visual Basic Signature

Public Sub LogEvent(ByVal LogBuffer As String, ByVal EventType As _
                     DbEventTypes)

Parameters

Application.RaiseError method

Description

Allows the VBA programmer to raise an error that is passed back via the BLL to the host application. Raising an error implicitly aborts the current transaction.

Visual Basic signature

Public Sub RaiseError(ByVal Number As Long, _
                        ByVal Description As String)

Parameters

Application.TotalOutstandingPOs method

Description

Returns the total number of outstanding POs for the employee that submitted the order.

Visual Basic signature

Public Property Get TotalOutstandingPOs() As Long

Return type

Long: The count of outstanding purchase orders for that employee.

Order.EmployeeAlias property

Description

Returns the alias associated with the employee placing this order (the alias is the employee's user name).

Visual Basic signature

Public Property Get EmployeeAlias() As String

Return type

String: The alias of the employee placing the order.

Order.EmployeeId property

Description

Returns the ID of the employee placing the order.

Visual Basic signature

Public Property Get EmployeeId() As Long

Return type

Long: A unique identifier (actually the primary key ID in the database) representing the employee placing the order.

Order.OrderDate property

Description

Returns the date that the order was submitted.

Visual Basic signature

Public Property Get OrderDate() As Date

Return type

Date: The date that the order was submitted.

Order.Id property

Description

Returns the ID of the order being placed. This ID is generated when the order is inserted into the database, so before the order ends up in the database (that is, on the InsertOrderStart event), the ID is –1.

Visual Basic signature

Public Property Get Id() As Long

Return type

Long: A unique identifier (actually the primary key ID in the database) representing the order, or –1 if the order is not yet in the database.

Order.OrderItems collection

Description

Returns a collection representing the books in the order. Each member of this collection represents a specific book title in the order.

Visual Basic signature

Property Get OrderItems () As OrderItems

Return type

OrderItems: Returns the collection representing the items in the order.

Order.StoreId property

Description

Returns the ID of the store for which the order is being placed.

Visual Basic signature

Public Property Get StoreId() As Long

Return type

Long: A unique identifier (actually the primary key ID in the database) representing the store for which the order is being placed.

Order.SupplierId property

Description

Returns the ID of the supplier from which the order is being placed.

Visual Basic signature

Public Property Get SupplierId() As Long

Return type

Long: A unique identifier (actually the primary key ID in the database) representing the supplier from which the order is being placed.

Order.TotalBooks property

Description

Returns the total number of books ordered.

Visual Basic signature

Property Get TotalBooks() As Long

Return type

Long: Returns the total number of items in the order.

Order.TotalPrice property

Description

Returns the total value of the order.

Visual Basic signature

Property Get TotalPrice() As Currency

Return type

Currency: Returns the total monetary value of the order.

OrderItems.Count property

Description

Returns the number of unique titles being ordered.

Visual Basic signature

Property Get Count() As Long

Return type

Long: Returns the total number of unique titles being ordered.

OrderItems.Item property

Description

Returns a specific order item.

Visual Basic signature

Function Item(index) As OrderItem

Parameters

Return type

OrderItem: Returns the specific item in the collection.

OrderItem.Author property

Description

Returns the author of the book ordered.

Visual Basic signature

Property Get Author() As String

Return type

String: Returns the author of the book ordered.

OrderItem.Id property

Description

Returns the ID of the book ordered.

Visual Basic signature

Property Get Id() As Long

Return type

Currency: Returns the ID (actually, the primary key in the database) of the book being ordered.

OrderItem.ISBN property

Description

Returns the ISBN number of the order.

Visual Basic signature

Property Get ISBN() As String

Return type

String: Returns the ISBN number of the order.

OrderItem.Price property

Description

Returns the price of this order item (the price per unit times the number of units ordered).

Visual Basic signature

Property Get Price() As Currency

Return type

Currency: Returns the price of this order item.

OrderItem.Title property

Description

Returns the title of the book ordered.

Visual Basic signature

Property Get Title() As String

Return type

String: Returns the title of the book ordered.

OrderItem.UnitPrice property

Description

Returns the price per unit of the book being ordered.

Visual Basic signature

Property Get UnitPrice() As Currency

Return type

Currency: Returns the price per unit of the book being ordered.

OrderItem.UnitQuantity property

Description

Returns the number of copies of this book being ordered.

Visual Basic signature

Property Get UnitQuantity() As Long

Return type

Long: Returns the number of copies of this book being ordered.

OrderItem.Year property

Description

Returns the year this book was published.

Visual Basic signature

Property Get Year() As Long

Return type

Long: Returns the year this book was published.

Buyer Programmability Model

Application.CalculatePerformance event

Description

This event is called when attempting to calculate the performance of any given employee. The VBA programmer is free to use the incoming data to rate the employee in the manner that they see fit.

Visual Basic signature

Public Event CalculatePerformance (ByVal EmployeeId As Long, _
   ByVal EmployeeAlias As String, ByVal Orders As Long, _
   ByVal OrderValue  As Currency, ByVal OrderVolume As Long, _
   ByVal OrderDelay As Long, ByRef PerformancePoints As Long)

Parameters

Application.PeriodOrders property

Description

Returns the total number of orders between the StartDate and EndDate of GetBuyerPerformance.

Visual Basic signature

Property Get PeriodOrders() As Long

Return type

Long: Returns the total number of orders for that period.

Application.PeriodOrderValue property

Description

Returns the total value of sales for all employees between the StartDate and EndDate of GetBuyerPerformance.

Visual Basic signature

Property Get PeriodOrderValue() As Currency

Return type

Currency: Returns the total value of sales for that period.

Application.PeriodOrderVolume property

Description

Returns the total number of books sold by all employees between the StartDate and EndDate of GetBuyerPerformance.

Visual Basic signature

Property Get PeriodOrderVolume() As Long

Return type

Long: Returns the total number of books sold in that period.

Application.PeriodAverageDelay property

Description

Returns the average delay between the StartDate and EndDate of GetBuyerPerformance.

Visual Basic signature

Property Get PeriodAverageDelay() As Long

Return type

Long: The average delay between orders.

Application.Employees property

Description

Returns the total number employees placing orders between the StartDate and EndDate of GetBuyerPerformance.

Visual Basic signature

Property Get Employees() As Long 

Return type

Long: Returns the total number of employees placing orders in that period.

Application.PeriodStartDate property

Description

Returns the start date for the performance period.

Visual Basic signature

Property Get PeriodEndDate() As Date 

Return type

Date: The start date for the performance period.

Application.PeriodEndDate property

Description

Returns the end date for the performance period.

Visual Basic signature

Property Get PeriodEndDate() As Date

Return type

Date: The end date for the performance period.

Application.Periodlength property

Description

Returns the number of days in the performance period.

Visual Basic signature

Property Get PeriodLength() As Long 

Return type

Long: The number of days in the performance period.