PROGRAMMING With .NET

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

(the following examples are for VB.NET)

1. Start by creating empty FieldGroups
Declare the variable (an array, if there are to be more than one)
Dim oFieldGroups() as DataGater.CaseDefinition.FieldGroup

Instantiate each one (g)
oFieldGroups(g) = new DataGater.CaseDefinitions.FieldGroup

2. Create the FieldDefinition objects and place them in FieldGroups
    Declare the variable
        Dim oFieldDefinitions as _
          DataGater.CaseDefinition.FieldDefinition

     Instantiate each FieldDefinition
        oFieldDefinition = New
          DataGater.CaseDefinitions.FieldDefinition

    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. Fill a FieldGroupCollection object with the FieldGroups

    Declare the variable and instantiate the object
            Dim colFieldGroupCollection as
         DataGater.CaseDefinitions.FieldGroupCollection

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

4. Create a CaseDefinition object and set its FieldGroupCollection property

    Declare the variable and instantiate the object
        Dim oCaseDefinition as _
          DataGater.CaseDefinitions.CaseDefinition
        oCaseDefinition = New _
          DataGater. CaseDefinitions.CaseDefinition

Set the FieldGroup Collection into it
oCaseDefinition.FieldGroups = colFieldGroupCollection

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

Declare it
Dim oGaterBase as DataGater

Create it
            oGaterBase = DataGater.Repository.GaterBase _
        .Create(a_sFilename, oCaseDefinition, _
        a_iLowCaseID, a_iHighCaseID)

To Open an Existing GaterBase

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

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

Managing Cases with .NET

To create a new case,

Declare a Case variable
Dim oCase As DataGater.Repository.Case

Instantiate the Case, 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 DataGater.Repository.Case

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

Another method allows you locate a Case by its value on an Indexer field
.GetCaseByIndexerValueGoverned (or Ungoverned)

To delete a Case

To remove a Case from the GaterBase repository, you only need the case’s CaseID index
oGaterBase.DeleteCase(CaseID)

Getting/Setting Data with .NET

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.
oCase.FieldValueSet(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)
        sValue = oCase.FieldValueGetAsString(FieldName)
        jValueCollection = oCase.FieldValueGetAsJoin _
                    (FieldName)

To save JoinField data

With JoinFields, 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 JoinField Entries

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 to hold the JoinFieldNames for the values that are to be saved.

1. Declare the variables to be used:

These are ....
    A string variable to contain the values to be saved in an entry
    A new JoinEntry object (to hold the variables to be saved in each entry)
    A oJoinFieldEntryCollection object (to contain the JoinEntries)
            Dim s_Value as string
      Dim oJoinEntry as _
            DataGater.Repository.FieldValueCollection
            Dim oJoinFieldEntryCollection As _
              DataGater.Repository.JoinFieldValue

2. Create a JoinFieldEntryCollection and a oJoinEntry object

oJoinFieldEntryCollection = New _
      DataGater.Repository.JoinFieldValue
oJoinEntry = oJoinFieldFactory _
      .CreateWithFieldDefinitions _
      (oJoinFieldDefinitionCollection)

3. Set the JoinFieldValues into a JoinEntry object

oJoinEntry.fieldValueSetAsString _
sJoinFieldName_1, sValue_1
oJoinEntry.fieldValueSetAsString _
sJoinFieldName_2, sValue_2

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.FieldValueSet _
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, andta JoinfieldDefinitionCollection object holding the JoinFieldNames for the values that are to be read.

1. Declare the variables to be used

A JoinFieldValueCollection object is the value of a Join-typed field and is contains a collection of JoinEntries
A JoinEntry object is a collection of JoinFieldValues
A JoinFieldValue object contains the values of a single JoinEntry
        Dim sValue as String
        Dim oJoinEntry as _
            DataGater.Repository.FieldValueCollection
        Dim oJoinFieldEntryCollection as _
            DataGater.Repository.JoinFieldValue

2. Create a JoinFieldEntryCollection and a JoinEntry object

oJoinFieldEntryCollection = new DataGater.Repository.JoinFieldValue
oJoinEntry = new DataGater.Repository.FieldValueCollection

3. Read the join entry collection from the Case

oJoinFieldEntryCollection = oCase.FieldValueGetAsJoin _
(FieldName)

4. Read all the JoinFieldValues from all the JoinEntries it contains

For each oJoinEntry in oJoinFieldEntryCollection
    sValue_1 = oJoinEntry.FieldValueGetAsString _
                (sJoinFieldName_1)
    sValue_2 = oJoinEntry.FieldValueGetAsString _
                (sJoinFieldName_2)
    (etc. for any other JoinFields held in the Entry)
Next oJoinEntry

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 to get gate-keys for.
        Declare the variable.
            Dim sFieldNamesSelected( ) as String

     Fill it with all the selected field names.
            sFieldNamesSelected(i)=sFieldName(g,f)

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 _
                DataGater.Repository.CaseInfoCollection
            Dim oCaseInfo as DataGater.Repository.CaseInfo

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

If you are seeking gate-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 _
        DataGater.Repository.CaseInfoCollection
    Dim iCaseIDs( ) as Long

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

2. Request a Quote

Declare variables for the Quote object and the Quote factory
Dim oQuote as DataGater.Purchase.Quote

Instantiate a new (empty) Quote object
oQuote = new DataGater.Purchase.Quote

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.

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 DataGater.Purchase.PurchaseRequest
Dim oPurchaserInfo as DataGater.Purchase PurchaserInfo
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 DataGater.Purchase.PurchaserResult

c) Instantiate new Request and PurchaserInfo objects

oPurchaseRequest = New _
DataGater.Purchase.PurchaseRequest
oPurchaserInfo = New _
DataGater.Purchase.PurchaserInfo

d) Generate a PurchaseRequest including the field and case selections

oPurchaseRequest = oGaterBase.GeneratePurchaseRequest _
(colCaseInfos, sFieldNames())

e) 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 the version)

f) 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)

g) Make the PurchaseRequest and receive the Result

oPurchaseResult = _
oGaterBase.PurchaseFromDataGater _
(oPurchaseRequest, sURL,PurchaseerInfo, iVendorID)

4. Receive a PurchaseKey and update the GaterBase fieldstates.

Determine if the PurchaseResult was successful
oPurchaseResult.WasSuccessful

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