Implementing Callback Functions

See Also: Call_Driver, Copy_Db, Copy_Records, Structure_End, and Sort

Purpose

To enable objects executing long-duration processes to report status of the process and to interrupt it in the event invalid data is encountered.

Syntax

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

Argument Explanation

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:

What It Does

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.

Notes