This chapter provides information that may be helpful in debugging your Btrieve application. It contains the following sections:

The MicroKernel’s Trace Operations configuration option allows you to trace each Btrieve API call and save the results to a file. This is helpful in debugging applications. The following shows a sample trace file.

Each operation shows values passed in to and returned by the MicroKernel. Input values are marked by <In> and output values are marked by <Out>; each is followed by a number that indicates the sequence in which the operations were processed, so that <Out> 0016 is the result of <In> 0016. The Opcode field shows the operation code performed; the Status field shows the returned status code.

Crs ID is the cursor ID, or handle, that the MicroKernel assigned to the request. This information can be helpful in debugging applications that support multiple clients or that support single clients with multiple cursors.

Db Length reflects the Data Buffer Length. Keynum reflects the Key Number. Clnt ID reflects the Client ID parameter used by the BTRVID and BTRCALLID functions. DBuf reflects the Data Buffer contents. KBuf reflects the Key Buffer contents. The trace file truncates the Data Buffer and Key Buffer contents, depending on the MicroKernel configuration.

When attempting a Get Direct/Chunk (23) operation, your application may receive a status code 62. You may find that your application is specifying the Indirect Random Descriptor option (Subfunction 0x80000001), but with tracing enabled, you can see that the MicroKernel is actually receiving a Direct Random Descriptor option (Subfunction 0x80000000).

The indirect chunk option allows an application to specify a pointer to a data address in the application's memory block where the data should be stored after it is retrieved, rather than having the data returned in the actual Data Buffer parameter of the Btrieve call. However, since the application is running in an environment in which the MicroKernel does not have direct access to the application's memory, the Btrieve client Requester must convert indirect chunk requests into direct chunk requests before sending the request to the MicroKernel.

All applications always use interprocess communication (IPC) to communicate between the application and the MicroKernel. Since IPC is required, the MicroKernel has no access to the application's memory, so the client Requester must allocate a single contiguous block of memory and adjust all data pointers to point into that memory block. On return from the MicroKernel, the Requester converts the Data Buffer back into the appropriate format for the indirect option and moves the returned data chunk into the designated, indirect address in the application's memory block.

If you are developing a multithreaded console application targeting either Windows 9x or Windows NT, you must set up a control handler routine to handle a potential Ctrl-C keystroke. In this control handler routine, you must clean up all of your Btrieve clients by issuing either a Reset (28) or Stop (25) operation. The cleanup process must complete before your application passes the Ctrl-C event on to the operating system.

If your application still has active clients when the system terminates the threads, the MicroKernel cannot clean up its connection with the application and is forced to allocate more system resources. This causes performance degradation and significantly increases the time needed for the engine to shut down. For more information about control handler routines, see the Microsoft documentation.

The MicroKernel allocates disk space as needed. If there is not enough room in the file when your application inserts new records, the MicroKernel dynamically allocates additional data and index pages to the file. The size of each allocated page is the same as the page size with which the file was created. The MicroKernel also updates directory structures to reflect the new file size.

Once the MicroKernel allocates space to a file, that space remains allocated as long as the file exists.