See Also: Call_Driver, Copy_Db, Copy_Records, Structure_End, and Sort
To enable objects executing long-duration processes to report status of the process and to interrupt it in the event invalid data is encountered.
Function Callback string CallbackMessage integer CallbackType ;
returns integer
: (optional code for progress-monitoring display)
: (code to set result value True or False //false =continue)
Function_Return result
End_Function
CallbackMessage A string to receive the first parameter of the received message, being progress-display text or progress-extent values.
CallbackType An integer to receive the second parameter of the received message, being a classification of the first parameter as follows:
DF_MESSAGE_PROGRESS_TITLE A caption explaining display of progress values.
DF_MESSAGE_PROGRESS_VALUE up to two values indicating extent of progress of the process.
DF_MESSAGE_HEADING_1 Level 1 heading
DF_MESSAGE_HEADING_2 Level 2 heading
DF_MESSAGE_HEADING_3 Level 3 heading.
DF_MESSAGE_HEADING_4 Level 4 heading.
DF_MESSAGE_HEADING_5 Level 5 heading.
DF_MESSAGE_TEXT An unclassified message.
DF_MESSAGE_WARNING A warning message.
Get_callback is a message sent (with parameters) by a number of commands that carry out long-duration processes on database files. These include the call_driver, copy_db, copy_records, structure_end, and sort commands, as well as various tools in which such processes are performed.
This message is sent once every 100 cycles (usually records) of the process in question to the object that called the process.
The (receiving) function itself is not defined anywhere in DataFlex. What is defined is the get_callback message and its parameters. These are defined in the commands that send it. Also defined in most of these commands are routines to act on the value returned by the callback function defined in the object receiving the message. If True is returned, the process will abort; False will allow it to continue.
The first of the two parameters sent with get_callback is display text or a pair of integer values separated by a comma (to drive an extent-of-progress report). The second parameter is a classification for the content of the first parameter. The types may be any of those shown above for callback_type. Special values for the parameters peculiar to each command that sends this message are documented with each command. The callback function you define should be able to handle each of the values sent by the command(s) that send to it.
The frequency (number of cycles) of sending get_callback can be adjusted by changing the value of the DF_RUNTIME_PROGRESS_FREQUENCY attribute of the embedded database driver. Its default value is 100.
Use of the callback function is optional in the commands that support it. Typically, the option is elected by identifying the receiving object in the command line. If the receiving object either does not exist or has no callback definition, an error will be triggered.