TExtFnInfo

TExtFnInfo is the data structure passed to an OrcaFlex External Function.

Members

Size

Specifies the size, in bytes, of this data structure. This member is set by OrcaFlex before it calls the external function.

This member must not be altered.

Action

This member specifies what action the external function is to perform:

• At the start of the OrcaFlex simulation, or when a complete simulation file is loaded, each external function is called once with this member set to eaRegisterResults which allows the external function to register any external result information with OrcaFlex by calling C_RegisterExternalFunctionResult.
• Before the statics calculation starts each external function is called with this member set to eaInitialise. The purpose of this call is to give the external function a chance to initialise any data structures that it will need during the simulation.
• During the simulation each external function is called repeatedly with this member set to eaCalculate. The external function should calculate the updated value and update the Value or lpStructValue members accordingly.
• At each OrcaFlex logging interval an external function is given the opportunity to log its own results by responding to eaLogResultCreate and then eaLogResultDestroy. For details see External Function Results.
• If the external function has registered an external result, then when this result is requested the external function is called with this member set to eaDeriveResults, the function can then access data logged by the eaLogResultCreate action and calculate the result.
• When the simulation is reset each external function is called with this member set to eaFinalise. Any memory allocated during the eaInitialise call should be deallocated.
• When OrcaFlex saves a simulation file the external function is called with this member set to eaStoreStateCreate and then once again with it set to eaStoreStateDestroy. For details see the State Storage topic.
• External functions which are used by OrcaFlex line types to provide stiffness data are also called with this member set to eaCalculateNominalValue. For details see the axial stiffness, bend stiffness or torsional stiffness topic, as appropriate.
• Tracking external functions are only available as part of a line type stiffness variable data source and are called with actions eaInitialise, eaTrackCalculation and eaFinalise. Action eaTrackCalculation is called at each OrcaFlex logging time step instead of eaCalculate, allowing the user, for example, to log specialised results to a file.

This member must not be altered.

SimulationTime

The current simulation time in the OrcaFlex model.

This member is valid for all actions.

This member must not be altered.

Value

The value of the variable data item. It is the job of the external function to update this member each time it is called with the Action member equal to eaCalculate.

When OrcaFlex first calls the external function with the Action member equal to eaInitialise the Value member is set to the Initial Value as specified on the OrcaFlex variable data form. If you wish to use a different starting value then can change the Value member.

During the simulation OrcaFlex repeatedly calls the external function with the Action member equal to eaCalculate. On entry to the external function the Value member is the value returned by the previous call to the external function. The external function should calculate a new value and update this member accordingly.

For axial stiffness or bend stiffness external functions the nominal stiffness must be returned in this member when the external function is called with the Action member equal to eaCalculateNominalValue.

When the external function is called with the Action member set to eaDeriveResult the requested result must be returned in this member. If the external function supports more than one results, then ResultID and lpDataName can be used to determine which one is required.

Successful

This member is private and must not be altered.

If the external function is unable to calculate Value then you should call C_RecordExternalFunctionError.

ObjectHandle

The handle of the OrcaFlex object which is requesting variable data values. The ObjectHandle and Object Extra members can be passed to the results function C_GetTimeHistory2 to find out the instantaneous state of the object. For example suppose that the external function calculates wing orientation values based on the wing's Z position. You would call C_GetTimeHistory2 specifying Period.PeriodNum = pnInstantaneousValue and using the VarID corresponding to "Wing Z".

This member is valid for all actions.

This member must not be altered.

lpObjectExtra

Extra information about the object which is requesting variable data values. For example if the values are requested by a Wing attached to a 6D buoy then the wing name will be specified in lpObjectExtra. If no extra information is required then this member will be NULL.

This member is valid for all actions, subject to the above rules.

This member must not be altered.

lpObjectParameters

A null-terminated string containing the value of the ExternalFunctionParameters tag as specified on the OrcaFlex data form.

For most external functions this is the tag for the object specified by the ObjectHandle member. However, externally calculated axial stiffness and bend stiffness functions are handled slightly differently. The data for the external function is specified for line type objects, but the external function is called for nodes on OrcaFlex line objects. For such functions this member contains the value of the ExternalFunctionParameters tag as specified by line type object used to define the line properties.

This member is valid for all actions.

This member must not be altered.

lpWorkingDataHandle

This member is private and must not be altered.

lpData

This member can be used for storing information private to the external function. OrcaFlex makes no use of this member. A typical use would be as follows:

1. When the external function is called with the Action member equal to eaInitialise the external function allocates some memory to store persistent calculation information. A pointer to this memory is then stored in the Data member.
2. Each subsequent call to the external function with the Action member equal to eaCalculate can now access the persistent calculation information through the Data member.
3. Finally, when the external function is called with the Action member equal to eaFinalise the memory pointed to by Data is deallocated.

lpDataSourceName

The name of the variable data source which is being used to define the external function. This name can be found on the Variable Data Form in OrcaFlex.

This member is valid for all actions.

This member must not be altered.

lpStateData

This member is used for storing state information to the OrcaFlex simulation file. See External Function State Storage for details.

This member should only be used during Actions eaInitialise, eaStoreStateCreate and eaStoreStateDelete.

LengthOfStateData

This member is used for storing state information to the OrcaFlex simulation file. See External Function State Storage for details.

This member should only be used during Actions eaInitialise, eaStoreStateCreate and eaStoreStateDelete.

lpDataName

The name of the value determined by this external function. This name will be the value of one of the constants prefixed with "vdn" in OrcFxAPI.h.

This member allows you to control related variable data items (e.g. applied load for X, Y and Z) with a single external function. This single external function would determine which value to return based on the value of this member.

This member is valid for all actions.

This member must not be altered.

lpInstantaneousCalculationData

Points to a block of memory containing information about the OrcaFlex object's instantaneous state (e.g. position, orientation, velocity etc.) Some external functions do not provide any such information and set this member to NULL. The information provided is different for each type of OrcaFlex object – see Instantaneous Calculation Data for details.

Note that for all values of Action other than eaCalculate and eaTrackCalculation this member is undefined.

This member must not be altered.

lpModelDirectory

The directory containing the latest OrcaFlex file (.dat, .yml or .sim) that you have opened or saved. This allows your external function to use relative paths to access any support files which are stored in the same directory tree as the OrcaFlex file. If the model has not yet been saved, then this member is the empty string.

This member is valid for all actions.

This member must not be altered.

UpdateDuringStatics

If TRUE then the external function will be updated during each iteration of the OrcaFlex statics calculation. Otherwise the value returned in the Value member after the eaInitialise call is used throughout statics.

• Axial stiffness and bend stiffness external functions for lines are always updated during statics. This member is always set to TRUE and must never be modified.
• External functions for vessels, 6D buoys, wings and line applied loads are optionally updated during statics. This member is set to FALSE before the eaInitialise call. If the external function wants the opportunity to update its value during statics then this member should be changed to TRUE. Note that the member should only be modified during the eaInitialise call.
• External functions for turbines are not called during statics so this member is ignored.
• All other external functions are not updated during statics. This member is always set to FALSE and must never be modified.

lpLogData

This member is used for storing data in the OrcaFlex simulation file allowing later derivation of results. See Native external functions: Results for details.

This member is only valid for eaDeriveResult, eaLogResultCreate and eaLogResultDestroy Actions.

LengthOfLogData

This member is used for storing data in the OrcaFlex simulation file allowing later derivation of results. See Native external functions: Results for details.

This member is only valid for eaDeriveResult, eaLogResultCreate and eaLogResultDestroy Actions.

ResultID

This member is used when deriving externally calculated results from previously stored data. See Native external functions: Results for details.

This member is only valid for the eaDeriveResult Action.

This member must not be altered.

NewTimeStep

This flag is used to indicate that a new time step has commenced.

• This flag is most relevant to implicit integration because, in that scenario, the external function will be called repeatedly for each iteration of a time step. This is in contrast with explicit integration for which only a single update per time step is requested of the external function.
• The flag is only used for the eaCalculate action. For all other actions its value is undefined.
• If your external function performs time integration, then this integration must not be performed on every iteration of a time step. Rather, the time integration should be performed only when NewTimeStep is TRUE.
• Be warned that if a variable time step scheme is in use then the simulation time may decrease during an iteration. This occurs when the variable time step integration scheme switches to use a shorter time step than was used on the initial iterations of the time step.

The PIDController example external function demonstrates how this member is intended to be used.

This member must not be altered.

lpStructValue

Some external functions return more than a single value and do so using this member instead of the Value member.

The types of external function that use this member are:

• Vessel primary motion and constraint imposed motion. For such external functions, a pointer to TExternallyCalculatedImposedMotionStructValue is passed in lpStructValue.
• Turbine generator motion. For such external functions, a pointer to TScalarStructValue is passed in lpStructValue.
• Turbine blade pitch motion. If common pitch control mode is active, a pointer to TScalarStructValue is passed in lpStructValue. If individual pitch control mode is active, a pointer to an array of TScalarStructValue is passed in lpStructValue. This array contains one item per turbine blade.

The external function must fill out the values of these structs for each eaCalculate call.

ModelHandle

The handle of the OrcaFlex model.

This member is valid for all actions.

This member must not be altered.

lpModelFileName

The name of the latest OrcaFlex file (.dat, .yml or .sim) that was opened or saved. If the model has not yet been saved, then this member is the empty string.

This member is valid for all actions.

This member must not be altered.

DataObjectHandle

This member is usually equal to ObjectHandle. However, externally calculated axial stiffness, bend stiffness and torsional stiffness functions are handled slightly differently. The data for the external function is specified for line type objects, but the external function is called for nodes on OrcaFlex line objects. For such functions this member contains the handle of the line type object used to define the line properties.

This member is valid for all actions.

This member must not be altered.

CanResumeSimulation

This member is TRUE by default. If the external function does not support resuming partially run simulation files, then is should set the value to FALSE during the eaInitialise call.

If possible, external functions should be coded to support resuming partially run simulation files. Typically this will involve implementing code to store external function state to the simulation file. However, this is not always possible, for example when the state is held by an external DLL that does not provide access to it.

Unicode and ANSI

The Unicode structure name is TExtFnInfoW and the ANSI structure name is TExtFnInfoA.

See also

External Functions, State Storage, Instantaneous Calculation Data, C_RecordExternalFunctionError.