Throughout GDL, the concept of a handle is prevalent. A "handle" is a reference to an object that is required by the Library and is not to be manipulated directly by the developer. For example, when gdlInitialize is called to initialize the library, a handle is returned. This handle (or one derived from it) is required for many Library functions. Likewise, when the gdlOpenSpatialFile function is called, a file handle is returned and is required for all spatial comparison operations. It is important to note that two function calls, gdlGenerateErrorSurface and gdlGetStreetLength, require that GeoStan handles are passed. This handle is generated when the GeoStan library is initialized.
This approach satisfies the requirements that Precisely had when creating the library:
- The library must be language independent.
- The library must be platform independent.
- The library API must be the same regardless of the language or platform.
The library does not require you to have any special knowledge about the above requirements. The most important concept to remember is this:
If a function creates a new handle, then memory or other resources have been allocated by the library. In order to return those resources to the system (free memory, close files, etc.), you must use the appropriate command to "terminate" the handle when you have completed the task.