Close down or crash

One of the basic principles that you need to learn when you start programming the API is that for top level object (constituents, gifts, funds, participants, etc) whenever you initialize the object you need to close it down. This is not too difficult to remember to do and you are swiftly reminded when you close the plug-in or the application (it crashes).

However there are some exceptions to this. When you loop a collection of top level records e.g. CGifts, using the for each construct you also have to close down the individual item. This goes against the above logic as you did not initialize it.

Below is an example of this:


'Just use anonymous to limit the number of gifts  

Dim oGifts As New CGiftsDim oGift As CGift  

oGifts.Init SessionContext, tvf_Gift_AnonymousOnly     

For Each oGift In oGifts     

    MsgBox oGift.Fields(GIFT_fld_Amount) 

Next oGift     

Set oGifts = Nothing

Another not so obvious time that the close down method has to be called is when you delete a record. When I first did this I did not think that I would need to close down because the gift was no longer in the system. In fact I assumed that by I would cause an error by trying to close down a gift because it no longer existed.

However the closedown mechanism does not close the actual gift down but closes the gift object. Until the gift is loaded the gift object is an empty shell with some initialization done on it. The closedown method will uninitialize it whether or not there is a current gift loaded.