Native external functions: State storage

If your external function's algorithm has state information (e.g. the integrator for a PID controller) then you can store this information in the lpData member of the TExtFnInfo structure.

However, OrcaFlex has the capability of resuming partially complete simulations or even extending completed simulations. Thus your external function's state information must be stored to and restored from the OrcaFlex simulation.

Note: If possible, external functions should store their state to the simulation to enable simulations to be resumed. However, if it is not possible to its store state, an external function should set the lpExtFnInfo->CanResumeSimulation member to FALSE during the eaInitialise call.

Storing state information to an OrcaFlex simulation file

When an OrcaFlex simulation file is saved OrcaFlex calls each external function to give them an opportunity to store state information to the simulation file. If an external function needs to store state information, then the mechanism works as follows:

  1. The function is called with lpExtFnInfo->Action equal to eaStoreStateCreate. If the external function has state data which needs to be stored then it must allocate memory in the lpExtFnInfo->lpStateData pointer and copy the state information into this block of memory. The lpExtFnInfo->LengthOfStateData member must be set to the length of the block of memory allocated.
Note: As an alternative, an existing block of memory could be used here.
  1. OrcaFlex now has access to the state information and can write it to the simulation file.
  2. Having finished with the state information, OrcaFlex calls the external function once more with lpExtFnInfo->Action equal to eaStoreStateDestroy. The external function must then free any memory allocated in step 1.

Restoring state information from an OrcaFlex simulation file

When OrcaFlex loads a simulation file containing external function state information it initialises the external function with this state information. This is done in the call to the external function with lpExtFnInfo->Action equal to eaInitialise.

When you are handling this call you should check the lpExtFnInfo->lpStateData pointer. If it is not NULL then OrcaFlex has loaded a simulation file containing external function state information. The lpExtFnInfo->LengthOfStateData member specifies the size of this state information. It is the responsibility of the external function to restore itself to its former state using this information.

Since OrcaFlex owns the state information, having loaded it from the simulation file, the external function must not attempt to free this memory. Also, the external function must not attempt to access this block of memory after the eaInitialise call has been completed.

See also

TExtFnInfo, Native External Functions, Instantaneous Calculation Data.