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 and enable interfacing to other support libraries.

DLL's can only be called if they conform to the Planimate DLL API, which is available for download by request to InterDynamics.

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 or load a DLL (Planimate does that) and the example DLL provides a framework to put your code / algorithms into.

The API used enables Planimate can interrogate the DLL's available routines and their parameter requirements, enabling the DLL to be used in a type-safe manner.

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, tables and strings can be passed as parameters to each DLL routine
• Multiple attributes, tables and strings (as labels) can be returned from the DLL
• Numeric 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 a a table.
• Planimate will automatically dynamically allocate space for returned tables according to the rules in the next section

Returning into a table

• If the target 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 is supported but the DLL must only be returning 1 row and the column count must match
• Returning into a column reference is supported but the DLL must only be returning 1 column and the row count must match
• Returning into a block reference is supported. 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.

Lookahead

• 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 allocation consistency issues.

---

idkbase note 125