DataGater logo

DataGater LLC

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..

  1. Create the FieldDefinitions – assigning each a unique Name,  a FieldType and an IsIndexer flag.
  2. Collect them into FieldGroups – at least one FieldGroup is required
  3. Collect FieldGroups into a FieldGroupCollection
  4. Assign the FieldGroupCollection to a CaseDefinition
  5. 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.