PROGRAMMING with a COM Interface

Every GaterBase needs a CaseDefinition
    The CaseDefinition contains a FieldGroupCollection
        The FieldGroupCollection contains one or more FieldGroups
                FieldGroups contain one or more FieldDefinitions
                FieldDefinitions include the name, datatype and IsIndexer flag

Begin by planning the basic data structure (the data fields you will need, what you will name them, what type of data they will story, which ones are to be indexers, and how many FieldGroups will you want to organize them into). Then create the GaterBase..

Create the FieldDefinitions – assigning each a unique Name, a FieldType and an IsIndexer flag.
Collect them into FieldGroups – at least one FieldGroup is required
Collect FieldGroups into a FieldGroupCollection
Assign the FieldGroupCollection to a CaseDefinition
Create a GaterBase with the CaseDefinition and a permissible CaseID range

Steps to Create a GaterBase

The steps outlined here do not precisely follow the logical sequence outlined above, but make for more efficient coding – requiring fewer arrays and control loops

Note:
        The code examples are for VB6.
        There are some shorter ways of coding these operations, (by
            compressing several steps into one line) but we chose the
            longhand way to make the logic clearer.

1. Start by creating empty FieldGroups and naming them

Declare a fieldgroup variable (an array, if there are to be more than one), and a factory
Dim oFieldGroups() as DGFieldGroup
Dim oFieldGroupFactory as DGFieldGroupFactory

Instantiate the factory
Set oFieldGroupFactory = New DGFieldGroupFactory

Instantiate each FieldGroup (g)
Set oFieldGroups(g) = oFieldGroupFactory.Create

Name each FieldGroup(g)
oFieldGroups(g).Name = (FieldGroup name)

2. Create each FieldDefinition objects and place it in a FieldGroup

Declare the FieldDefinition variable and the FieldDefinitionCollection factory.
                Dim oFieldDefinitions as DGFieldDefinition
         Dim oFieldDefinitionCollectionFactory as _
                DGFieldDefinitionFactory

Use the Factory to Instantiate it
Set oFieldDefinition = _
oFieldDefinitionCollectionFactory.Create

Assign its name, type and is-Integer flags
                oFieldDefinition.Name = (FieldName)
         oFieldDefinition.FieldType = (FieldType)
         oFieldDefinition.InIndexer = (True/False)

Add it to its FieldGroup (g)
oFieldGroups(g).Add oFieldDefinition

3. Create an empty FieldGroupCollection object and fill it with the FieldGroups

Declare the collection variable and factory
                Dim colFieldGroupCollection as DGFieldGroupCollection
         Dim oFieldGroupCollectionFactory as _
                DGFieldGroupCollectionFactory

Instantiate an empty collection object
Set colFieldGroupCollection = _
oFieldGroupCollectionFactory.create

Add each FieldGroup to the FieldGroupCollection
colFieldGroupCollection.Add sFieldGroup(g)

4. Create a CaseDefinition object and set its FieldGroupCollection property
(I typically declare the CaseDefinition as Public,
to simplify access from various modules)

Declare the variable and factory
Public oCaseDefinition as DGCaseDefinition
Dim oCaseDefinitionFactory as DGCaseDefinitionFactory

Instantiate an empty CaseDefinition object
oCaseDefinition = oCaseDefinitionFactory.create

Set the FieldGroup Collection into it
oCaseDefinition.FieldGroups = colFieldGroupCollection

5. Create a GaterBase with the CaseDefinition, filename and range for new CaseID entries

(We typically declare the CaseDefinition as Public, to simplify access from various modules)

Declare it
Public oGaterBase as DGGaterBase
Dim oGaterBaseFactory as DGGaterBaseFactory

Instantiate a new GaterBase using the CaseDefinition and assigning a range of permissible new CaseID values
                 Set oGaterBase = oGaterBaseFactory.CreateNew _
                            (a_sFilename, oCaseDefinition, _
                             a_iLowCaseID, a_iHighCaseID

Open an Existing GaterBase

Declare a variable for it
Public oGaterBase as DataGater.Repository.GaterBase

And open it
oGaterBase = DataGater.Repository.GaterBase. _
Open(sFilename, IO.FileMode.Open)

Managing Cases with .COM

To create a new case,
Declare a Case variable and its CaseID
Dim oCase As DGCase
Dim iCaseID as long

Instantiate it, using the CaseDefinition
oCase=new DataGater.Repository.Case(oCaseDefinition)

The Case’s CaseID index value is assigned automatically by the GaterBase, and can be read as a property of the Case.
iCaseID = oCase.CaseID

To open an existing Case

There are many methods for finding and opening a case from the GaterBase. The critical thing is to be sure you are getting it in the mode you want it: Governed (all values, but with a speed restriction or UnGoverned (Purchased and Indexer data only, but no speed restriction)

Declare a Case variable
Dim oCase As DGCase

Get it from the GaterBase
                oCase = oGaterBase.GetCaseByIDGoverned(iCaseID)
        or
                oCase = oGaterBase.GetCaseByIDUngoverned(iCaseID)

Other methods for allow you to identifying the Case by its value on an Indexer field:
    For String Indexers
                .GetCaseByIndexerValueGoverned (or Ungoverned)
For Integer Indexers (note the “IntInteger” part of the method name)
                .GetCaseByIntIndexerValueGoverned (or UnGoverned)

To delete a case
All you need is its CaseID property.
oGaterBase.DeleteCase (iCaseID)

Getting/Setting Data with COM

To save data to a Case

You need an open Case object, the Field name, and the Value to be saved. Values can be saved as Boolean, Double-precision, Integers, Joins or Strings. The method you call depends upon the declared type of the value to be saved
        oCase.FieldValueSetAsBoolean(FieldName, Value)
        oCase.FieldValueSetAsFloatingPoint(FieldName, Value)
        oCase.FieldValueSetAsInteger(FieldName, Value)
        oCase.FieldValueSetAsJoin(FieldName, Value)
        oCase.FieldValueSetAsString(FieldName, Value)

Saving values can be done with either kind of case, and there is no speed limit to saving to Governed cases (if you surpass the speed limit, you will still be able to access the Case records as governed, and save values to any of its fields, you just wont be allowed to read any of its unpaid (RAW) values until a period of time has passed.

If you want to change a FieldValue that currently has data in it to an “Undefined” (missing) value, use this method call:
oCase.FieldValueSetAsUndefined(FieldName)

To read data from a Case

You need an open Case and a FieldName. Different method calls are used, depending on the type of the saved variable.
        bValue = oCase.FieldValueGetAsBoolean(FieldName)
        dblValue = oCase.FieldValueGetAsDouble(FieldName)
        iValue = oCase.FieldValueGetAsInteger(FieldName)
        jValueCollection = oCase.FieldValueGetAsJoin(FieldName)
        sValue = oCase.FieldValueGetAsString(FieldName)

To save JoinField data

With a JoinField, the value obtained from the oCase.FieldValueGetAJoin method is not a simple value (like an Integer or a String) but a JoinFieldEntryCollection object containing JoinEntries – and each JoinEntry, in turn, contains a collection of JoinFieldValues … identified by their JoinFieldNames.

JoinField with entries - example

In the figure above, the field named “FieldNotes” contains collection of JoinEntries, each of which contains two JoinFieldValues, one named “NoteTime” the other named “NoteText”

The number of JoinEntries in the collection is unlimited, which makes this a very convenient structure for holding data whose counts you can’t know at design time. Anecdotal Field Notes are one example, as are all kinds of logfiles where you can pre-specify the kinds of values to be stored (TimeStamp, EventDescription) but not their number.

To save values to a JoinField, you need an open Case, the FieldName for the Field that holds the JoinEntry collection, and a JoinfieldDefinitionCollection object holding the JoinFieldNames for the values that are to be saved.

1.      Declare the variables to be used:
        A string variable to hold the values to be saved in a Entry.
        A new JoinEntry object (which is a collection of JoinFieldValues)
        A JoinFieldEntryCollection object tol contain the JoinEntries.
        A factory to create JoinEntry objects
        A factory to create a JoinFieldEntryCollection object

Dim sValue as String
Dim oFieldValue As DGFieldValue
Dim oJoinEntry As DGFieldValueCollection
Dim oJoinEntryFactory as DGJoinFieldFactory
Dim oJoinFieldValueFactory as _
DGJoinFieldValueFactory

2.      Create a JoinFieldEntryCollection and a oJoinEntry object
                    Set oJoinFieldEntryCollection = oJoinFieldValueFactory _
                        .Create()
                    Set oJoinEntry = JoinFieldFactory _
                        .CreateWithFieldDefinitions(oJoinFieldDefinitionCollection)

3.      Set the JoinFieldValues into a JoinEntry object
            oJoinEntry.fieldValueSetAsString _
                    sJoinFieldName_1, sValue
            oJoinEntry.fieldValueSetAsString _
                    sJoinFieldName_2, sValue

        etc for each value to be held by the entry

4.      Read the current entry collection from the Case, if one exists
           oJoinFieldEntryCollection = oCase. _
                    FieldValueGetAsJoin(FieldName)

5. Add the new JoinEntry to the collection
oJoinFieldEntryCollection.Add oJoinEntry

6.      Set the expanded collection into the Case’s value field
                oCase.FieldValueSetAsJoin _
                    sFieldName, oJoinFieldEntryCollection

7. Put the modified Case object into the GaterBase
oGaterBase.SaveCase oCase

To read JoinField data

To read JoinField data values from a case, you need an open Case, the FieldName for the Field that holds the JoinEntry collection, and a JoinfieldDefinitionCollection object holding the JoinFieldNames for the values that are to be read.

1.      Declare the variables to be used
        A FieldValue object is the Value of a Join-typed field and
                    it contains a collection of JoinEntries
        A JoinEntry object is a collection of JoinFieldValues
        A JoinFieldValue object contains the values of a single JoinEntry
        Two factorie are needed: one to create JoinEntry objects,
                    the other for JoinFieldEntryCollections

Dim oFieldValue As DGFieldValue
Dim oJoinEntry As DGFieldValueCollection
Dim oJoinEntryFactory as DGJoinFieldFactory
Dim oJoinFieldValueFactory as _
DGJoinFieldValueFactory
Dim oJoinFieldValue As DGJoinFieldValue

6.      Create a JoinFieldEntryCollection and a JoinEntry object
            Set oJoinFieldEntryCollection = _
                    oJoinFieldValueFactory.Create()
            Set oJoinEntry = oJoinFieldFactory. _
                    CreateWithFieldDefinitions _
                    (oJoinFieldDefinitionCollection)

7.      Read the join entry collection from the Case
                    oJoinFieldEntryCollection = _
                    oCase.FieldValueGetAsJoin(FieldName)

8.      Read all the JoinFieldValues from all the JoinEntries it contains
                For each oJoinEntry in the oJoinFieldEntryCollection
             sJoinFieldValue1= oJoinEntry. _
                    FieldValueGetAsString(sJoinFieldName_1)
                      sJoinFieldValue2 = oJoinEntry. _
                    FieldValueGetAsString(sJoinFieldName_2)
         (etc. for any other JoinFields held in the Entry)

Managing the Purchase Process

The purchase of gating-keys involves the following operations.

·         Specify the cases and fields to gate
·         Request a quote
·         Receive the quote
·         Request a purchase with credit account information
·         Receive a gating PurchaseKey and update the GaterBase FieldStates

1. Specify cases and fields for keying.

Create an array of the FieldNames of the fields to get gate-keys for.
        Declare the variable.
                Dim sFieldNamesSelected( ) as String
     Fill it with all the selected field names.

Create collection of the CaseInfos for the cases selected for gate-keys

If you are seeking gate-keys for a subset of the cases on file, declare the collection and a CaseInfo variable.
            Dim colCaseInfos as DGCaseInfoCollection
            Dim oCaseInfo as DGCaseInfo

For each selected case, get its CaseInfo and add it to the collection.
                colCaseInfosSelected.Add _
                oGaterBase.GetCaseInfoForCase(iCaseID)

If you are seeking keys for all the cases on file it is quicker to get all the CaseIDs at once, and use them to get the CaseInfos in a batch.

Declare a long-integer array variable for the CaseIDs, and a collection variable for the CaseInfos
                   Dim colCaseInfos as DGCaseInfoCollection
            Dim iCaseIDs( ) as Long

Get the CaseIDs and fill the CaseInfos collection directly from the GaterBase
                    iCaseIDs() = oGaterBase.GetAllCaseIDs
            Set colCaseInfos = oGaterBase. _
                            GetCaseInfoForCases(iCaseIDs)

2. Request a Quote

Declare variables for the Quote object and the Quote factory
Dim oQuote as DGQuote
Dim oQuoteFactory as DGQuoteFactory

Instantiate a new (empty) Quote object
Set oQuote = oQuoteFactory.Create

Request the Quote (where sURL is the address of the DataGater server and iVendorID is the unique identifying index of the vendor of the app in use.
                            Set oQuote = oGaterBase.QuoteFromDataGater _
                     (colCaseInfos, sFieldNamesSelected, _
                     sURL, iVendorID)

3. Receive a Quote

The server will return a Quote object to the client with the following properties, any or all of which can be reported out to the client on the app’s order form:

.PurchasedCaseDataCount
.QuoteFeeDetails
.SalesTaxAmount
.SubTotalAmount
.TotalAmount

For example:
frmOrderForm.lblFee.caption = oQuote.TotalAmount

If the client finds the fee acceptable, they can proceed to placing the order, otherwise they have the option of revising their Case and Field selections and resubmitting their quote,

4. Place a purchase order

To order gating-keys, the client needs to submit their field selections and their case selections (they ones they used for getting their most-recent quote) and their credit-card billing information.

a)      Declare variables for PurchaseRequest and PurchaserInfo objects to send to DataGater
            Dim oPurchaseRequest as DGPurchaseRequest
            Dim oPurchaseRequestFactory as _
                    DGPurchaseRequestFactory
            Dim oPurchaserInfo as DGPurchaserInfo
            Dim oPurchaserInfoFactory as DGPurchaserInfoFactory

b)      Declare a variable for the Result object to be returned
      by the DataGater server in response to the request.
            Dim oPurchaseResult as DGPurchaserResult

c)      Instantiate the factories
            Set oPurchaseRequestFactory = _
                    New DGPurchaseRequestFactory
            Set oPurchaserInfoFactory = New _
                    DGPurchaserInfoFactory
            Set oPurchaseResultFactory = New _
                    DGPurchaseResultFactory

d) Instantiate new Request and PurchaserInfo objects
            Set oPurchaseRequest = oPurchaseRequestFactory _
                    .Create
            Set oPurchaserInfo = oPurchaserInfoFactory.Create

e)      Generate a PurchaseRequest including the field and case selections
                    Set oPurchaseRequest = oGaterBase _
                .GeneratePurchaseRequest _
                (colCaseInfos, sFieldNames())

f)       Add tracking information to the PurchaseRequest object, identifying the App and its version (so that the transaction reports you receive will include that information)
            oPurchaseRequest.VendorApplicationID = _
                (whatever number or string you assign the app)
            oPurchaseRequest.VendorApplicationVersion = _
                (whatever number or string you assign it)

    These properties are strings, so you can format them
    with periods, hyphens, commas and letters as you with.

g) Set the PurchaserInfo properties

oPurchaserInfo.Contact.Name = (firstname last name)
oPurchaserInfo.Contact.PhoneNumber = (phone number)
oPurchaserInfo.BillingAddress.Address1 = (address1)
oPurchaserInfo.BillingAddress.Address2 = (address2)
oPurchaserInfo.BillingAddress.City = (city)
oPurchaserInfo.BillingAddress.State = (State)
oPurchaserInfo.BillingAddress.PostalCode = (PostalCode)
oPurchaserInfo.CreditCardInformation.CardType = _
                (card type enumerator),
        e.g., “DataGater_Purchase_CardType_Visa”
oPurchaserInfo.CreditCardInformation.AccountNumber = _
                (account number)
oPurchaserInfo.CreditCardInformation.SecurityCode = _
                (security code)
oPurchaserInfo.CreditCardInformation.Expiration = _
                (expiration in mm/yyyy format)

h)      Make the PurchaseRequest and receive the Result
                Set oPurchaseResult = oGaterBase _
                 .PurchaseFromDataGater(oPurchaseRequest, _
                 sURL,PurchaseerInfo, iVendorID)

4. Receive a PurchaseKey and update the GaterBase fieldstates

Determine if the PurchaseResult was successful
oPurchaseResult.WasSuccessful = True

And if so, unlock the data with the PurchaseKey that was returned with the oPurchaseResult
oGaterBase.UnlockData oPurchaseResult.PurchaseKey

The data will now be PAID and ready for analysis or export. PAID status is permanent. A field will only lose it if a new value replaces the PAID one.