C_SetCorrectExternalFileReferencesHandler

Call C_SetCorrectExternalFileReferencesHandler to set up an application-defined callback function to correct any out-of-date external file references in a simulation file. Examples of external file references include time history file names and external function DLL names.

Parameters

ModelHandle (IN)

The handle of the model.

CorrectExternalFileReferencesProc (IN)

The application-defined callback function. If you do not want to receive a callback pass NULL.

lpStatus (OUT)

Points to a variable in which the status result for the function call will be returned.

Remarks

When a simulation file is loaded (e.g. by calling C_LoadSimulation) OrcaFlex needs to load external files referenced by that simulation file. If those external files are not present then the simulation fails to load. Usually the solution is to restore the external files to the location referred to by the simulation files but sometimes this is not possible or is inconvenient. For example, if an absolute path has been used to specify the external file location then that external location may no longer exist, say due to a network volume being renamed.

If the external files cannot be restored to their original location then C_SetCorrectExternalFileReferencesHandler can be used to update the external file references. The procedure is as follows:

• Define the callback procedure CorrectExternalFileReferencesProc.
• Call C_SetCorrectExternalFileReferencesHandler to register the callback.
• Call C_LoadSimulation to load the simulation.
• During the call to C_LoadSimulation your callback is called. At this point, from inside your callback, you can call C_SetDataString to correct the out-of-date external references.
• Once C_LoadSimulation returns you can call C_SaveSimulation to save the corrected simulation file so that any future loading of the file does not require this correction process.

Please note that the callback function is called during the loading a simulation file. Because of this you are severely restricted in what you can do with the model at this point. You are permitted to modify data items which define references to external files. Any other calls to the API should be expected to result in catastrophic failure.

See also

CorrectExternalFileReferencesProc.