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.
MicroKernel Trace File of a BUTIL STAT Call
MicroKernel Database Engine [Server Edition] for Windows NT 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.
Note To avoid a degradation in performance, only turn the Trace File setting on for short periods of time so that you can determine what operations are being handled by the MicroKernel.
Indirect Chunk Operations in Client-Server Environments
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.
Engine Shutdowns and Connection Resets
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.
Reducing Wasted Space in Files
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.
►To reduce the space required for a file from which numerous records have been deleted, you can use the Maintenance utility as follows
1 Create a new file with the same characteristics as the original file.
In the interactive Maintenance utility, the commands are Open and Create As from the File menu. In the command-line based Maintenance utility, the command is CLONE.
2 Insert records into the new file using one of the following methods:
•Write a small application that reads the records from the original file and inserts them into the new file.
•In the command-line Maintenance utility, use the SAVE command and then the LOAD command. Alternatively, you can use the COPY command.
•In the interactive Maintenance utility, use the Save command and then the Load command from the Data menu. Alternatively, you can use the Copy command from the Data menu.
3 Rename the new file and then delete the original file from the disk.