CalcIt Commands

CALLBACK(FuncName, BufDefID, ReturnValueType=atINT, CDECL=false)

Returns the address of a stub routine (in processor's code) which when it is called redirects execution to a local CalcIt function.

  • FuncName. The local CalcIt function where the execution is redirected. This local function has always the same interface of one Buffer type parameter. Via this Buffer type parameter user's code can access the parameters passed to the callback routine. See below for more information.
  • BufDefID.  A value returned by a BUFDEF command which describes the parameters interface of the callback routine and is the structure of the Buffer parameter mentioned above.
  • ReturnValueType. Optional.  The type of returned value by the callback routine. atINT if omitted.
  • CDECL. Optional.  Chooses between Windows calling conventions (default) or C/C++ calling conventions for the callback routine.

This command is used to import API calls (exported functions in DLLs) that need an address of a function in user's code to be called by the API routine itself. Usually we refer to such user code routines as CALLBACKs and it is obvious why. Callbacks is a usual way to customize a general operation offered by a routine. Represents the "polymorphism" of "old times", before the emergence of Object Oriented Programming languages and their handy virtual methods.

For example a Callback routine handles the appearance and operation of every Window created under Windows operating system. Additionally Callbacks are used In many other situations, for example in sorting routines where the CallBack function handles the way the values in a list are compared and so makes the same sorting routine able to sort correctly lists with arbitrary kind of elements and sorting preferences.

Because CalcIt local functions cannot be passed directly to such API calls we need a redirection mechanism that bridges native code execution with CalcIt code execution.

So CALLBACK command creates a stub routine, in processor's code, which when it is called by any API routine, redirects the execution to a local CalcIt function, handling all the interfacing details. This way the user can handle Callbacks in CalcIt code.

The Local CalcIt function has always the same interface:

function MyCallbackInCalcIt(buf p);

Only one parameter. This parameter of Buffer type is used to handle the parameters of the called callback routine. The Buffer type ID defined in the CALLBACK command is assumed in this Buffer parameter.

See also Using Buffer variables, Classes and Class variables

Go Back