Callback Functions
A number of commands (such as call_driver, copy_db, sort, structure_end, and copy_records) use a callback function to report status back to the caller. The object receiving the get_callback should define a function whose first line looks like this:
Function CallBack for class String Callback_msg Integer Callback_type Returns Integer
Your callback function must return either True or False. If it returns False, the operation will continue. If it returns True, the operation will be aborted. The for class parameter permits defining the function for inheritance by every instance of the class.
On entry to your callback function, Callback_msg is a string. Callback_type indicates the type of message that Callback_msg contains. Callback_type will be one of the following:
- DF_MESSAGE_TEXT: A generic message not falling into one of the following types.
- DF_MESSAGE_HEADING_1: The highest level heading.
- DF_MESSAGE_HEADING_2: A second level heading.
- DF_MESSAGE_HEADING_3: A third level heading.
- DF_MESSAGE_HEADING_4: A fourth level heading.
- DF_MESSAGE_HEADING_5: The lowest level heading.
- DF_MESSAGE_WARNING: A warning message.
- DF_MESSAGE_PROGRESS_TITLE: The title of the following progress values.
- DF_MESSAGE_PROGRESS_VALUE: One or two values indicating how far the current operation has progressed.
By knowing the type of the message, an application can intelligently handle displaying the message. For example, if the message type is DF_MESSAGE_WARNING, the message can be displayed in a text box labeled "Warning." In addition, the application may want to give users an opportunity to abort the operation if a warning message is received—although this can be dangerous. If they abort during a sort or restructure, indexes and even files can become corrupt.
All messages apply to the last message heading level. Since a heading typically identifies the current operation being performed, this gives the user an idea of what is happening. As an example, you might receive the following sequence of messages:
| Message Text | Message Type |
|---|---|
| Sorting file 1 | DF_MESSAGE_HEADING_1 |
| Building index 1. | DF_MESSAGE_HEADING_2 |
| Building index 2. | DF_MESSAGE_HEADING_2 |
| Sorting file 2. | DF_MESSAGE_HEADING_1 |
| Building index 1. | DF_MESSAGE_HEADING_2 |
Since we know the types of the messages, they can be presented to users in a way that leaves the last header message for each level visible.
Progress messages (DF_MESSAGE_PROGRESS_VALUE) pass one or two integer values separated by a comma. The first (or only) integer represents the current completion level of the operation. The second integer represents the value for total completion of the current operation. For example, a DF_MESSAGE_PROGRESS_VALUE of 20,100 might mean that 20 out of 100 records have been read or that the operation is 20% complete. The actual meaning of the DF_MESSAGE_PROGRESS_VALUE is specified in the previous DF_MESSAGE_PROGRESS_TITLE message. The following is an example of a sequence that could be received:
| Message Text | Message Type |
|---|---|
| Sorting file 1. | DF_MESSAGE_HEADING_1 |
| Building index 1. | DF_MESSAGE_HEADING_2 |
| Percent Complete: | DF_MESSAGE_PROGRESS_TITLE |