Planimate as a DLL

Planimate can convert itself into a DLL which can embedded in other applications, includding dotNET applications using the Planimate dotNET wrapper.

This page documents the core functions which Planimate exports.

Loading the DLL

Typically you will load the DLL using LoadLibrary() followed by GetProcAddress to bind to the member functions. This is demontrated in the LoadPL SDK demo application and will not be covered in detail here.

Since an EXE converted to a DLL does not have a regular DllMain(), you need to invoke initialisation functions explicitly as follows. This example is for a simplistic single threaded use of the DLL.

• LoadLibrary() and GetProcAddress() for the functions
  
• PL_SetInstance() to set the instance handle
  
• PL_Init() to initialise planimate. This can be passed command line arguments to load a model. It also needs a window handle for a window into which Planimate will create a child window for its output.
  
• PL_GetSystemInfo() / PL_SetSystemInfo() to configure special options
  
• PL_GetBroadcastName() to lookup a broadcast handle
  
• PL_SendBroadcast() to send a broadcast (via its handle) to the model
  
• PL_Term() when you are finished with the model to deallocate it
  
• FreeLibrary() the DLL instance
  

PL_GetSystemInfo / PL_SetSystemInfo

These enable access to a number of attributes.

PLSI_CLOCK = 0

This read only attribute returns the model run clock during a simulation run. This is the number of seconds since the model's Run Start Date.

PLSI_ADVANCETOTIME = 1

This read only attribute returns the time (measured as for clock) that the model is advancing to. Valid if an advance to time is active.

PLSI_CURRENTPENDING = 2

This returns the number of events currently in the simulation Future Events List.

PLSI_ENGINESTATE = 3

This returns the state of the simulation engine

PLSI_CURRENTFILEVERSION

This returns the version of MDL files that the Planimate DLL will save

PLSI_OLDESTFILEVERSION = 5

This returns the oldest file ersion that the Planimate DLL can load and run.

PLSI_LOADEDFILEVERSION = 6

This returns the version of the loaded model, as appears next to "V" near the beginning of the MDL file.

PLSI_DLLVERSION = 7

This returns the version of the DLL API. As of January 2013 this is 2.

PLSI_BATCH = 8

This is a read/write attribute. When 1 it indicates that Planimate is running in "batch" mode where no screen updates or animation delays are performed and no windows event dispatching occurs.

This property can be set on and off however If the "/BATCH" command line option was used to initialise Planimate, Planimate will remain in batch mode.

A model in batch mode must not pop up dialogs or panels. The s.Batch system attribute can be used by the modeller to test this state.

It will be desireable to hide the parent window used to initialise Planimate in batch mode as it will not be updated or redrawn.

PLSI_MESSAGELOCK = 9

As a standalone application, when Planimate is running a model, the main thread is in a loop in which Planimate processes events, performs display updates, performs timing delays (to keep animation at a consistent speed) and also dispatches windows events to keep the process responsive to paint messages and user interaction with the running model.

When embedded as a DLL, it is possible to run the model in its own thread whilst the main thread continues independently. In such cases it is important that the Planimate thread does not dispatch windows messages as well as the main thread.

Setting this value to 1 will prevent the simulation loop from dispatching windows events.