Unicode

Starting from version 9.5, OrcaFlex and OrcFxAPI have full support for Unicode strings. All previous versions used ANSI strings. OrcFxAPI still supports the older ANSI interface but this interface has now been supplemented by a Unicode interface.

C++

Functions and structures which use character data now have two implementations: an ANSI version where the name is suffixed with A and a Unicode version where the name is suffixed with W.

For example, the C_SaveSimulation function has the following versions:

The Windows SDK defines macros LPTSTR and LPCTSTR which expand either to ANSI types (LPSTR, LPCSTR) or Unicode types (LPWSTR, LPCWSTR) depending on whether the UNICODE conditional has been defined. The OrcFxAPI header file declares C_SaveSimulation in the same way. It is a macro that expands to C_SaveSimulationW if UNICODE is defined or otherwise to C_SaveSimulationA. This pattern is followed throughout the header file.

The MSVC runtime library includes a header file named tchar.h that defines similar generic text mappings for types and functions. For example, this header file defines a macro TCHAR that expands to either char or wchar_t. However, this header file uses the _UNICODE conditional to determine how the macros expand. Consequently it is common to define both UNICODE (for the Windows SDK headers) and _UNICODE (for the MSVC headers).

Using the TCHAR character types and the generic names for functions and structures allows you to target both ANSI and Unicode from the same source. However, it is rare that you would need to write code that could be compiled for either ANSI or Unicode. Usually code is written to target one or the other. For instance, it is perfectly legitimate to continue to use the ANSI versions of the functions if you already have code that predates OrcaFlex's Unicode capability, and have no need for the Unicode API. When writing new code we recommend that you target only the Unicode version of the API.

Delphi

As for C++, functions which use character data are available in both ANSI and Unicode versions. However, we recommend that you use the generic named versions of the functions, e.g. C_SaveSimulation, which map to either ANSI or Unicode depending on the version of Delphi being used. Applications built with Delphi 2009 or later use the Unicode version of the API. When using earlier versions of Delphi, the ANSI version of the API will be used. The Delphi import file, OrcFxAPI.pas, supports Delphi 6 and later.

Python

The Python interface to the OrcFxAPI will detect whether the OrcFxAPI DLL supports Unicode and call the appropriate functions.

MATLAB

Starting with R2022a, MATLAB has full support for Unicode character data and the the OrcFxAPI interface to MATLAB also has full support for Unicode character data. For earlier versions of MATLAB which do not have full Unicode support, the OrcFxAPI interface only supports ANSI characters.

Compatibility

Applications built using the older ANSI OrcFxAPI (version 9.4 and earlier) will still work with the new OrcFxAPI DLL (version 9.5 and later).

Applications built with version 9.5 and later may not work when run against older versions of the OrcFxAPI DLL (version 9.4 and earlier):

• If the application uses Unicode character data then it will fail when run against a version 9.4 or earlier DLL.
• Python applications that use ANSI character data will work against all versions of the DLL.
• Applications built with Delphi 2007 or earlier will work against all versions of the DLL. Applications built with Delphi 2009 or later will work against DLL version 9.5 or later.
• C++ applications that use ANSI character data and are built with OrcFxAPI 9.5 and later will fail when run against DLL version 9.4b or earlier. If you face this scenario then you can either upgrade the DLL to 9.4c, or re-build the application with the 9.4 versions of OrcFxAPI.h and OrcFxAPI.lib.