Calling Planimate helper DLLs from Planimate

=== DLL Calling for routines ===

Planimate enables a user supplied DLL file to be called
from within Planimate as a routine executes. This can greatly speed up
complex mathematical operations.

DLL's can only be called if they conform to the Planimate DLL API, which
is now available for download. A simple matrix utility DLL is provided as
a sample for developers. You will need a C++ compiler capable of producing
a Win32 DLL to develop using the API. You dont need to know how to call/load
a DLL (Planimate does that) and my example DLL provides a calling framework
to put your code/algorithms into.

The API means Planimate can interrogate the DLL's available routines
and their parameter requirements, hopefully minimising GPFs due to memory
allocation issues.

Key features of the Planimate DLL calling mechanism:

• A named function in a DLL can be called from a line in a change
  object routine
• DLLs can contain a number of these callable functions (called routines)
• Multiple attributes and tables can be passed as parameters to each
  routine in a DLL.
• Multiple attributes and tables can be returned from the DLL
• All Planimate data types are passed to/from the DLL as double precision
  numbers. If a DLL is receiving what should be integer values, care
  should be taken in converting the doubles to integers to avoid round
  off issues - never trunc() in this case!
• DLLs also return an integer "result" value. This can be used to
  convey call success, error numbers, as defined by the DLL author.
• table parameters can be entire table references, single rows or columns
  or block references (starting at the top left to the end of the table)
• Where a DLL expects a table for a parameter, Planimate can handle
  passing tables, rows, columns and sub-blocks as parameters. To the
  DLL, it appears as a table.
• Planimate will automatically dynamically allocate space for returned
  tables according to the following rules:

Returning into a table:

• If the table has no rows or columns, it will be allocated to fit
  the table the DLL returns. The columns will be unformatted and
  unlabelled.
• If the table contains columns but no rows, the columns will be
  retained and enough rows added to fit the table the DLL returns.
  The column count must match or a model error is reported.
• If the table contains data, its rows and columns must match the
  table returned by the DLL otherwise a model error is reported

Returning into a row reference:

• The DLL must only be returning 1 row and the column count must match

Returning into a column reference:

• The DLL must only be returning 1 column and the row count must match

Returning into a block reference:

• If the Top Left Cell of the block reference is NOT (1,1) then
  Planimate will place as much data as it can into the table without
  ever complaining. If the DLL's table has too many rows/columns,
  the extra ones are ignored. If it doesn't have enough rows/columns,
  the existing values in the table receiving the data are left intact.
• DLLs which return no outputs apart from the result code are callable
  during lookahead, otherwise they must be called in routines
  that are "only during move" to avoid possible lookahead error messages.

This means that a DLL call can be part of a "look ahead" operation
(eg: very complex movement logic) with the movement result/decision
coming back to Planimate via the DLL result code.

• tables are passed to the DLL "by copy" and the DLL returns data to
  Planimate in the same way. This means the same table can provide data
  to a DLL as the one receiving the result without any consistency issues.
  

---

idkbase note 125