Click above to get retro games delivered to your door ever month!

 indcall()           Execute an indirect function call
------------------------------------------------------------------------------
 Declaration
   memory.hdr

 Syntax
   proc indcall extern

 Arguments
   None.

 Return
   None.

 Description
   The indcall() function performs an indirect call to a function, previously
   set up on the stack.

   In the strongly typed Force language there are no constructs corresponding
   to the runtime macros available in xBase dialects. On the other hand,
   quite often there is a need to decide at runtime which specific
   routine has to be executed, depending on certain conditions.
   Instead of creating huge case constructs, the appropriate function can
   be called indirectly, using a function pointer.

   Earlier Force versions used the indcall() function to achieve the
   same goal. The indcall() function is now obsolete and included
   for compatibility with previous Force versions. Use function pointers
   for calling code indirectly.

   For indirectly executing a function using indcall(), several rules are
   necessary to observe:

   - Determine the address of the function to be called indirectly
   using the function addr() or the & operator.

   - Write a shell routine that executes indcall(). The shell routine's
   first parameter should be the address of the function to be executed
   indirectly, and accept the same parameters and return the same data type
   like that function. The shell routine does not need to have an explicit
   return statement. Typically the shell routine's body only contains a
   call to indcall().

   - The function to be called indirectly must have a value ulong at the
   first parameter position. This way its prototype is identical to that
   of the shell routine.

   - Call the shell routine with the previously determined address of
   the function, and the necessary parameters when appropriate. The
   caller code receives the return value of the indirectly called
   function.

 Example
   #define EXAMPLE_MEMORY
   #include example.hdr

   // Three ways of calling a function
   
   func uint _CALL ptr               // function pointer type declaration
   param value ulong pDummy, const char cString
   
   func uint Executor static         // shell routine for indcall()
   param value ulong pFunc, const char cString
   indcall()
   endproc
   
   func uint TestCall static         // actual function to execute
   param value ulong pDummy, const char cString
   /*
   Observe that the pDummy parameter is only necessary for executing
   this function via indcall() and the shell routine. The dummy parameter
   is unnecessary when calling the function directly, or via function pointer.
   */
   ?? cString
   return( 100 )
   endfunc
   
   proc Test_indcall
   vardef
      ptr( _CALL ) pFunc
   enddef
   ? TestCall( 0, "hello" )                 // execute directly
   ? Executor( addr( TestCall ), "hello" )  // execute via indcall()
   pFunc := &TestCall
   ? pFunc( 0, "hello" )                    // execute via function pointer
   endproc

   proc main
   Test_indcall()
   endproc