Native external functions
Native external functions can be implemented in C++ or Delphi and require that a DLL is created, exporting a function or functions that match the declaration described below.
The function must be declared with the stdcall calling convention. In C++ the function would be declared as:
void __stdcall ExtFn(TExtFnInfo &ExtFnInfo);
In Delphi the function would be declared as:
procedure ExtFn(var ExtFnInfo: TExtFnInfo); stdcall;
You can export any number of different external functions from the same DLL. We recommend that you use descriptive names for your external functions so that they can be more easily identified on the OrcaFlex variable data form.
This function will be called in the following way during an OrcaFlex calculation.
|Notes:||Axial stiffness and bend stiffness external functions for lines differ in that they are updated during statics. In addition external functions for vessels, 6D buoys, wings and line applied loads can optionally elect to be updated during statics by modifying ExtFnInfo.UpdateDuringStatics.|
|When OrcaFlex is using Implicit Integration, the external function may be repeatedly called for the same timestep as OrcaFlex iterates towards a solution. OrcaFlex indicates when the eaCalculate call is for a new timestep by setting the NewTimeStep field to true.|
|Calling C_GetTimeHistory2 from an external function is slower than using the lpInstantaneousCalculationData field. Because of this we recommend the latter approach whenever possible. Indeed for bend stiffness external functions you must use the lpInstantaneousCalculationData field.|
Please note that the external function must not throw any exceptions since OrcaFlex will not be able to handle them – the function must catch all exceptions and handle them before returning. The function can report feedback of any errors that occur by calling C_RecordExternalFunctionError.
If your function's algorithm has state information (e.g. the integrator for a PID controller) then you can store this information in the Data member of the TExtFnInfo structure. To ensure that this state information is restored if you load a partially complete simulation please refer to the State Storage topic.
The procedure for linking an external function to OrcFxAPI differs from a standalone application that uses OrcFxAPI. It is essential that the external function links to the specific OrcaFlex/OrcFxAPI instance that hosts the external function.
For a C++ external function you must not link the OrcFxAPI .lib file to your external function DLL. Instead include OrcFxAPIExplicitLink.c in your DLL project. In addition you must ensure that your DLL exports the function named InitializeOrcFxAPI which is defined in OrcFxAPIExplicitLink.c. Do this by adding InitializeOrcFxAPI to your project's .def file.
For a Delphi external function you must add the ExplicitLinkOrcFxAPI conditional define to your project options. When you do this the InitializeOrcFxAPI function defined in OrcFxAPI.pas will automatically be exported from your DLL.
Because the external function DLL is loaded directly into the OrcaFlex process, you need to provide a 32 bit DLL for use by 32 bit versions of OrcaFlex, and a 64 bit DLL for use by 64 bit versions of OrcaFlex. If you use exclusively 32 bit OrcaFlex then you can build just a 32 bit version of the external function DLL. Likewise, if you use exclusively 64 bit OrcaFlex then you need only build a 64 bit version of your DLL.
There are situations where it may be desirable to to use the same external function from both 32 and 64 bit versions of OrcaFlex. For example, if your IT environment has both 32 and 64 bit systems that run OrcaFlex, then in order to share an external function amongst all OrcaFlex users, you need to compile both 32 and 64 bit versions of the external function DLL. These should be located in the same directory and the 64 bit version given the suffix of 64. For example, if the 32 bit external function DLL is named ExtFn.dll then the 64 bit DLL must be named ExtFn64.dll.
If you follow this naming convention, then OrcaFlex will load whichever external function DLL matches the architecture of the OrcaFlex process. In this situation, it does not matter which version of the DLL you refer to from your OrcaFlex data. The 32 bit OrcaFlex will always load ExtFn.dll, even if the data file names ExtFn64.dll. And vice versa, the 64 bit OrcaFlex will always load ExtFn64.dll, even if the data file names ExtFn.dll.
A number of examples of external functions can be found in ExternalFunctionExamples.zip. This file can be found on the OrcaFlex CD, in the OrcaFlex installation directory or on our website.
TExtFnInfo, Instantaneous Calculation Data, Capabilities, State Storage, Thread Safety, Axial Stiffness, Bend Stiffness, Torsional Stiffness, and Native external functions: Results.