The Duwamish Books, Phase 4 Business Logic Layer API Reference

Steve Kirk
Microsoft Developer Network

August 1999

Introduction

The Business Logic Layer (BLL) COM component used in this Phase 4 of the Duwamish Books sample application contains two code classes providing separate BLL implementations. One class (cBusLogic) provides features and a transaction model optimized for the Phase 4 Web application. The other class (cBusLogic_3) provides compatibility with legacy (Phase 3 and Phase 3.5) applications by implementing functionality that is equivalent to the Phase 3x BLL. This article documents the Phase 4 BLL API exposed by cBusLogic. For documentation of the Phase 3x BLL API, see "Duwamish Books Business Logic Layer API Reference." The cBusLogic_3 API may be accessed through migration components that are COM interface compatible with the legacy BLL components. This strategy for compatibility with legacy client applications is covered in my article "Migrating a Business Logic Component to a Web Application."

GetAuthors

Description

Retrieves into Authors Recordset the entire Authors domain or a single Author specified by PKId.

Visual Basic signature

Public Function GetAuthors(Authors As ADODB.Recordset, _
                        Optional Byval PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetCategories

Description

Retrieves into Categories Recordset the entire Categories domain, or a single Category specified by PKId.

Visual Basic signature

Public Function GetCategories(Categories As ADODB.Recordset, _
                           Optional Byval PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetCustomers

Description

Retrieves into Customers Recordset the entire Customers domain or a single Customer specified by PKId, or by Alias. The Customers Recordset is expanded according to the value of ExpType.

Visual Basic signature

Public Function GetCustomers(Customers As ADODB.Recordset, _
               Optional ByVal PKId as Long, _
               Optional ByVal Alias As String, _
               Optional ByVal ExpType As EXPANSION_TYPE_4 = icPK_4)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetEmployees

Description

Retrieves into Employees Recordset the entire Employees domain or a single Employee specified either by PKId or by Alias.

Visual Basic signature

Public Function GetEmployees(Employees As ADODB.Recordset, _
                           Optional ByVal PKId as Long, _
                           Optional ByVal Alias As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetInventories

Description

Retrieves into Inventories Recordset the entire Inventories domain or one of the following subsets:

Inventories are expanded according to the value of ExpType.

Visual Basic signature

Public Function GetInventories(Inventories As ADODB.Recordset, _
                              Optional ByVal PKId as Long, _
                              Optional ByVal ItemId As Long, _
                              Optional ByVal StoreId As Long, _
                              Optional ByVal ExpType As EXPANSION_TYPE_4 = icPART_4)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetItemCategories

Description

Retrieves into ItemCategories Recordset the entire ItemCategories domain, or a single ItemCategory specified by PKId.

Visual Basic signature

Public Function GetItemCategories(ItemCategories As ADODB.Recordset, _
                                 Optional Byval PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetItems

Description

Retrieves into Items Recordset, in a format specified by ItemTemplateType, the entire Items domain, a single Item, or a subset of the Items domain.

Visual Basic signature

Public Function GetItems(Items As ADODB.Recordset, _
                  Optional ByVal PKId as Long, _
                  Optional ByVal PKIdList As String, _
                  Optional ByVal ISBN As String, _
                  Optional ByVal Title As String, _
                  Optional ByVal AuthorId As String, _
                  Optional ByVal CategoryId As String, _
                  Optional ByVal AuthorKeywordList As String, _
                  Optional ByVal SubjectKeywordList As String, _
                  Optional ByVal TitleKeywordList As String, _
                  Optional ByVal NatLangIn As String, _
                  Optional NatLangOut As String, _
                  Optional ByVal ItemTemplateType As ITEM_TEMPLATE_TYPE_4 = icITEM_4), _
                  Optional ByVal TopId As Long, _
                  Optional ByVal MatchLevel As Long

Parameters

Either of the following parameters specifies a single Item to retrieve:

Any of the following parameters, specify a subset of Items to retrieve.

The following parameters are used for natural-language search. These parameters return PKIds only. PKIds may be converted to PKIdList format to return columns specified with ItemTemplateType.

The following parameters control "chunking" of the returned subset. They may be used with subset specifying parameters as indicated above. Subset specifying parameters return Item records ordered by MatchLevel (descending count of number of matches for Item) and by PKId.

Return type

Boolean: Returns True if successful, False if not successful.

GetItemTypes

Description

Retrieves into ItemTypes Recordset the entire ItemTypes domain or a single ItemType specified by PKId.

Visual Basic signature

Public Function GetItemTypes(ItemTypes As ADODB.Recordset, _
                              Byval Optional PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetOrders

Description

Retrieves Orders matching OrderTemplateType. From Orders matching OrderTemplateType, GetOrders will return all Orders, a single Order specified by PKId, all Orders for a store specified by StoreId, or all Orders for a customer specified by CustomerId.

Visual Basic signature

Public Function GetOrders(Orders As ADODB.Recordset, _
               OrderTemplateTypeAs ORDER_TEMPLATE_TYPE_4, _
               Optional ByVal ExpType As EXPANSION_TYPE_4, _
               Optional ByVal PKId as Long, _
               Optioinal ByVal CustomerId As Long, _
               Optional ByVal StoreId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetOrderTypes

Description

Retrieves into OrderTypes domain into OrderTypes Recordset.

Visual Basic signature

Public Function GetItemTypes(OrderTypes As ADODB.Recordset)

Parameters

Boolean: Returns True if successful, False if not successful.

GetPublishers

Description

Retrieves into Publishers Recordset the entire Publishers domain or a single Publisher specified by PKId.

Visual Basic signature

Public Function GetPublishers(Publishers As ADODB.Recordset, _
                  Optional ByVal PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetSession

Description

Gets and updates data for session specified by PKId and Alias. Creates session and returns PKId if session matching PKId and Alias does not exist.

Visual Basic signature

Public Function GetSession(PKId As Long, _
                           Alias As String, _
                           Session As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetSettings

Description

Retrieves into Settings Recordset Codes for the entire Settings domain or a single Setting specified by Description.

Visual Basic signature

Public Function GetSettings(Settings As ADODB.Recordset, _
                           Optional ByVal Code as String)

Parameters

Settings: An ADO Recordset to be filled with the appropriate data.

Return type

Boolean: Returns True if successful, False if not successful.

GetStores

Description

Retrieves into Stores Recordset the entire Stores domain or a single Store specified by PKId.

Visual Basic signature

Public Function GetStores(Stores As ADODB.Recordset, _
                           Optional ByVal PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

GetSuppliers

Description

Retrieves into Suppliers Recordset the entire Suppliers domain or a single Supplier specified by PKId.

Visual Basic signature

Public Function GetSuppliers(Suppliers As ADODB.Recordset, _
                              Optional ByVal PKId as Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertAuthor

Description

Inserts an Author into database. Returns PKId of inserted Author if successful.

Visual Basic signature

Public Function InsertAuthor(PKId As Long, ByVal AuthorName As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertCategory

Description

Inserts a Category into database. Returns PKId of inserted Category if successful.

Visual Basic signature

Public Function InsertCategory(PKId As Long, _
                              ByVal Description As String, _
                              Optional ByVal ParentId As Long,)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertCustomer

Description

Inserts a Customer into database. Returns PKId of inserted customer if successful.

Visual Basic signature

Public Function InsertCustomer(PKId As Long, _
                              ByVal Alias As String, _
                              ByVal Password As String, _
                              ByVal CustomerName As String, _
                              ByVal Address As String, _
                              ByVal Country As String, _
                              ByVal PhoneNumber As String, _
                              ByVal Fax As String, _
                              ByVal Email As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertEmployee

Description

Inserts an Employee into database. Returns PKId of inserted Employee if successful.

Visual Basic signature

Public Function InsertEmployee(PKId As Long, _
                           ByVal Alias As String, _
                           ByVal Password As String, _
                           Optional ByVal EmployeeName As String, _
                           Optional ByVal TaxAccount As String, _
                           Optional ByVal Address As String, _
                           Optional ByVal Country As String, _
                           Optional ByVal PhoneNumber As String, _
                           Optional ByVal Fax As String, _
                           Optional ByVal CellPhone As String, _
                           Optional ByVal EmergencyContact As String, _
                           Optional ByVal HireDate As Date, _
                           Optional ByVal Admin As Boolean)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertInventory

Description

Inserts an Inventory into database for Item and Store. Returns PKId of inventory if successful.

Visual Basic signature

Public Function InsertInventory(PKId As Long, _
                                 ByVal ItemId As Long, _
                                 ByVal StoreId As Long, _
                                 ByVal InStock As Long, _
                                 ByVal ReorderLevel As Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertItem

Description

Inserts an Item into database. If insert is successful, returns PKId of inserted Item.

Visual Basic signature

Public Function InsertItem(PKId As Long, _
                           ByVal ItemTypeId As Long, _
                           Optional ByVal PublisherId As Long, _
                           Optional ByVal SupplierId As Long, _
                           Optional ByVal PublicationYear As Long, _
                           Optional ByVal ISBN As String, _
                           Optional ByVal ImageFileSpec As String, _
                           Optaionl ByVal Title As String, _
                           Optional ByVal Description As String, _
                           Optional ByVal UnitCost As Currency, _
                           Optional ByVal UnitPrice As Currency, _
                           Optional ByVal AuthorList As String, _
                           Optional ByVal KeywordList As String) Ab Boolean

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertItemCategory

Description

Inserts an ItemCategory into database for Item and Category.

Visual Basic signature

Public Function InsertItemCategory(ByVal ItemId As Long, _
                                 ByVal CategoryId As Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertItemType

Description

Inserts an ItemType into database. If insert is successful, returns PKId of ItemType.

Visual Basic signature

Public Function InsertItemType(PKId As Long, _
                        ByVal Code As String, _
                        ByVal Description As String, _
                        ByVal IsBook As Boolean)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertOrder

Description

Inserts an Order into database and returns PKId of inserted order if successful.

Visual Basic signature

Public Function InsertOrder(PKId As Long, _
   Optional ByVal OrderType As ORDER_TYPE_4, _
                           Optional ByVal OrderStatus As ORDER_STATUS_4, _                           Optinal ByVal CustomerId As Long, _
                           Optional ByVal EmployeeId As Long, _
                           Optional ByVal OtherStoreId As Long, _
                           Optional ByVal StoreId As Long, _
                           Optional ByVal SupplierId As Long, _
                           Optional ByVal OrderDate As Date, _
                           Optional ByVal PickupDate As Date, _
                           Optional ByVal SubTotal As Currency, _
                           Optional ByVal ShippingHandling As Currency, _
                           Optional ByVal ShipToName As String, _
                           Optional ByVal Address As String, _
                           Optional ByVal Country As String, _
                           Optional ByVal PhoneNumber As String, _
                           Optional ByVal Fax As String, _
                           Optional ByVal ItemIdList As String, _
                           Optional ByVal QuantityList As String, _
                           Optional ByVal PriceList As stirng) As Boolean

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertPublisher

Description

Inserts a Publisher into database. Returns PKId of inserted Publisher if successful.

Visual Basic signature

Public Function InsertPublisher(PKId As Long, _
                        ByVal PublisherName As String, _
                        Optional ByVal Address As String, _
                        Optional ByVal Country As String, _
                        Optional ByVal PhoneNumber As String, _
                        Optional ByVal Fax As String, _
                        Optional ByVal ContactPerson As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertSale

Description

Inserts a Sale into database and returns PKId of inserted Sale if successful.

Visual Basic signature

Public Function InsertSale(PKId As Long, _
_                           Optinal ByVal CustomerId As Long, _
                           Optional ByVal EmployeeId As Long, _
                           Optional ByVal StoreId As Long, _
                           Optional ByVal SaleDate As Date, _
                           Optional ByVal SubTotal As Currency, _
                           Optional ByVal Tax As Currency, _
                           Optional ByVal ShippingHandling As Currency, _
                           Optional ByVal ShipToName As String, _
                           Optional ByVal Address As String, _
                           Optional ByVal Country As String, _
                           Optional ByVal PhoneNumber As String, _
                           Optional ByVal Fax As String, _
                           Optional ByVal Ship As Boolean, _
                           Optional ByVal PaymentType As String, _
                           Optional ByVal CreditCardNumber As String, _
                           Optional ByVal ExpirationDate As String, _
                           Optional ByVal NameOnCard As String, _
                           Optional ByVal ItemIdList As String, _
                           Optional ByVal QuantityList As String, _
                           Optional ByVal PriceList As stirng) As Boolean

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertSetting

Description

Inserts a Setting into database for supplied Code, Description, and Value. Code must be unique in Settings table.

Visual Basic signature

Public Function InsertSetting (ByVal Code As String, 
                              ByVal Description As String, _
                              ByVal Value As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertStore

Description

Inserts a Store into database. Returns PKId of inserted Store if successful.

Visual Basic signature

Public Function InsertStore(PKId As Long, 
                           ByVal Code As String, _
                           ByVal StoreName As String, _
                           ByVal Address As String, _
                           ByVal Country As String, _
                           ByVal PhoneNumber As String, _
                           ByVal Fax As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

InsertSupplier

Description

Inserts a Supplier into database. Returns PKId of inserted Supplier if successful.

Visual Basic signature

Public Function InsertSupplier (PKId As Long, _
                                 ByVal SupplierName As String, _
                                 ByVal Address As String, _
                                 ByVal Country As String, _
                                 ByVal PhoneNumber As String, _
                                 ByVal Fax As String, _
                                 ByVal ContactPerson As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateAuthor

Description

Updates database for Author specified by PKId.

Visual Basic signature

Public Function UpdateAuthor(ByVal As Long, _
                              ByVal AuthorName As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateCategory

Description

Updates database for Category specified by PKId.

Visual Basic signature

Public Function UpdateCategory(ByVal PKId As Long, _
                              ByVal Description As String, _
                              ByVal ParentId As Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateCustomer

Description

Updates database for Customer specified by PKId.

Visual Basic signature

Public Function UpdateCustomer(PKId As Long, _
                              ByVal Alias As String, _
                              Optional ByVal Password As String, _
                              Optional ByVal CustomerName As String, _
                              Optional ByVal Address As String, _
                              Optional ByVal Country As String, _
                              Optional ByVal PhoneNumber As String, _
                              Optional ByVal Fax As String, _
                              Optional ByVal Email As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateEmployee

Description

Updates database for Employee specified by PKId.

Visual Basic signature

Public Function UpdateEmployee(PKId As Long, _
                              ByVal Alias As String, _
                              ByVal Password As String, _
                              ByVal EmployeeName As String, _
                              ByVal TaxAccount As String, _
                              ByVal Address As String, _
                              ByVal Country As String, _
                              ByVal PhoneNumber As String, _
                              ByVal Fax As String, _
                              ByVal CellPhone As String, _
                              ByVal EmergencyContacty As String, _
                              ByVal EmergencyPhone As String, _
                              ByVal HireDate As Date, _
                              ByVal Admin As Boolean) As Boolean

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateInventory

Description

Updates database for Inventory specified by PKId.

Visual Basic signature

Public Function UpdateInventory(ByVal PKId As Long, _
                  ByVal InventoryUpdateType As INVENTORY_UPDATE_TYPE_4, _
                  ByVal InStock As Long, _
                  ByVal ReorderLevel As Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateItem

Description

Updates database for Item specified by PKId.

Visual Basic signature

Public Function UpdateItem(ByVal PKId As Long, _
                           ItemTypeId As Long, _
                           Optional ByVal PublisherId As Long, _
                           Optional ByVal SupplierId As Long, _
                           Optional ByVal PublicationYear As Long, _
                           Optional ByVal ISBN As String, _
                           Optional ByVal ImageFileSpec As String, _
                           Optional ByVal Title As String, _
                           Optional ByVal Description As String, _
                           Optional ByVal UnitCost As Currency, _
                           Optional ByVal UnitPrice As Currency, _
                           Optional ByVal AuthorList As String, _
                           Optional ByVal KeywordList As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateItemType

Description

Updates database for ItemType specified by PKId.

Visual Basic signature

Public Function UpdateItemType(ByVal PKId As Long, _
                                 ByVal Code As String, _
                                 ByVal Description As String, _
                                 ByVal IsBook As Boolean)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateOrder

Description

Updates database according to UpdateType for current record in Order Recordset.

Visual Basic signature

Public Function UpdateOrders(Byval OrderUpdateType As ORDER_UPDATE_TYPE_4,_
                           Optional Order As ADODB.Recordset, _
                           Optional ByVal PKId As Long, _
                           Optional ByVal StatusType As ORDER_STATUS_4, _
                           Optional ByVal ApprovalCode As String, _
                           Byval Optional EmployeeId As Long)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdatePublisher

Description

Updates database for Publisher specified by PKId.

Visual Basic signature

Public Function UpdatePublisher(ByVal PKId As Long, _
                                 ByVal PublisherName As String, _
                                 Optional ByVal Address As String, _
                                 Optional ByVal Country As String, _
                                 Optional ByVal PhoneNumber As String, _
                                 Optional ByVal Fax As String, _
                                 Optional ByVal ContactPerson As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateSetting

Description

Updates database Setting record specified by Code.

Visual Basic signature

Public Function UpdateSetting(ByVal Code As String, _
                              ByVal Description As String, _
                              ByVal Value As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateStore

Description

Updates database for Store specified by PKId.

Visual Basic signature

Public Function UpdateStore(ByVal PKId As Long, _
                           ByVal Code As String, _
                           ByVal StoreName As String, _
                           ByVal Address As String, _
                           ByVal Country As String, _
                           ByVal PhoneNumber As String, _
                           ByVal Fax As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

UpdateSupplier

Description

Updates database for Supplier specified by PKId.

Visual Basic signature

Public Function UpdateSupplier(ByVal PKId As Long, _
                              ByVal SupplierName As String, _
                              ByVal Address As String, _
                              ByVal Country As String, _
                              ByVal PhoneNumber As String, _
                              ByVal Fax As String, _
                              ByVal ContactPerson As String)

Parameters

Return type

Boolean: Returns True if successful, False if not successful.

Comments? We welcome your feedback at duwamish@microsoft.com.