Handles

Bank Wizard uses handles to store your inputs and results. Your application creates a handle by calling BWICreateHandle. This returns an integer value which your application passes to the other API functions. Handles isolate your application from the physical implementation of the storage.

The many advantages of this approach include:

Your application does not need to create any complex structures to hold the input or results used by Bank Wizard
Bank Wizard can be called by any programming language
When a handle is created it references the current set of Database Table Files. Therefore, you can load new DTFs without affecting any checks currently in progress. When all of the handles referencing the old set are freed, Bank Wizard can unload the old DTFs. (This is known as dynamic update)
Applications are entirely isolated from Bank Wizard's internal structure. This prevents an application inadvertently overwriting memory which belongs to Bank Wizard and so results in stable implementations
Multiple validations can occur at the same time. Each validation is run within its own handle and is isolated from all other checks.

Bank Wizard provides Get and Set functions so that your application can pass inputs and retrieve results.

When a validation has been completed, you must free the data structure used by the handle. To do this you call BWIFree.

BWICreateHandle(h);

/* do validations, process results */

BWIFree(h);

By default, Bank Wizard can have 256 handles in use at any given time. If you do not free the handles but keep creating new ones, eventually the creation will fail. You can detect this failure by passing the handle to BWIValidHandle:

BWICreateHandle(h);

if(BWIValidHandle(h) != 0) {

...serious error

}

Creating and freeing handles uses very little processing time, therefore make sure you always:

Create the handle.
Use the handle for a validation or search.
Free the handle.

You should explicitly free the handle even if your programming language supports automatic garbage collection. This is because you cannot guarantee that the garbage collector will run before you use all of the available handles.

Typically, you should never need more than 256 handles, however you can increase this by calling BWISetRuntime passing item BWI_R_MAX_HANDLE.

Consider carefully before increasing the number of handles. If creation fails then it is more likely that you have created handles, using BWICreateHandle, without freeing them, using BWIFree.