FME 2022.0 FME Objects Application Migration Guide

Introduction

This article provides a guide for upgrading C++ FME Objects applications to the latest version of the FME API. In FME 2022.0 or newer, FME changed the default string encoding from the operating system locale encoding (e.g. Windows-1252) to UTF-8 on supported Windows 10 and later operating systems.

Benefits of migrating to the new FME API include:

• Improved support for international characters in feature type names, attribute names, trait names, coordinate system names, datasets, or other file paths
• Increased workspace portability between all supported operating systems and locales
• Improved performance due to reduced transcoding operations

FAQ Overview

• How is the Windows SDK version different from the Windows version?
• Why require a minimum Windows SDK version of 10.0.17134.0?
• What are the implications of setting a locale?
• How do I disable UTF-8 processing?
• How to verify the locale is set correctly in a plug-in for FME 2022.0?
• Was the FME_createSession entry point removed?

Upgrading to use the new FME 2022.0 API version requires recompilation of the FME Objects application, making a few entry point changes, and potentially adjusting locale usage to work correctly with the UTF-8 or operating system encodings used by FME.

​​​​​​​FAQ

Note: whenever setlocale() is mentioned the same applies to _wsetlocale() as the latter is a Windows specialization that supports wide (wchar_t) strings in FME 2023.0+. 
​​​​​​​

How is the Windows SDK version different from the Windows version?

The Windows SDK version is the target that the plug-in will be compiled against and is defined per the FME Objects application in the Visual Studio project settings and must be at least 10.0.17134.0.


The Windows SDK version is distinct from the Windows operating system version, which can be seen in System Information on Windows. Note: Windows 10 must be at least version 1903 or Windows Server 2019 must be at least version 1809 and build 17763.1339 to support a UTF-8 encoding via setlocale() and _wsetlocale().

Why require a minimum Windows SDK version of 10.0.17134.0?

Microsoft has added support for setting C Runtime locale to UTF-8 in Windows 10 build 17134 - the April 2018 Update, which also coincides with the minimum Windows 10 version required for FME UTF-8 operation.

What are the implications of setting a locale?

Setting the locale influences the execution of all locale-sensitive C library functions in the running process, which may impact the behavior of the whole calling FME Objects application. For further information on setlocale() and _wsetlocale(), please refer to the C++ documentation and Microsoft documentation, respectively.

For example, if the locale encoding was set to the UTF-8 encoding, the following is valid on any Windows version that supports the UTF-8 encoding:

// This file name will work on any locale!
std::string filename(u8"サンプルファイル.txt");
std::fstream exampleFile;
exampleFile.open(filename);

In contrast, if the locale encoding were set to Windows-1252, only characters that are valid in that code page would be allowed.
 

How do I disable UTF-8 processing?

By default, in FME 2022.0+ the process locale will be UTF-8. This includes all FME Objects applications. However, the environment variable FME_DISABLE_UTF8_PROCESSING will allow using FME with the operating system locale.

• FME_DISABLE_UTF8_PROCESSING=yes
  • Launches FME with current operating system locale 
  • For example, a Windows-1252 encoding on an English US locale
• All other values of FME_DISABLE_UTF8_PROCESSING or the lack of the environment variable would enable UTF-8 processing in FME

How to verify the locale is set correctly in a plug-in for FME 2022.0?

FMEPluginCapabilities is available starting from FME 2022.0 betas for development and testing. 

A mixed encoding string containing Japanese, English, Russian and Thai characters can be a good test to ensure correct UTF-8 operation:

だめもじ_mixed_цифра_ทดสอบ

The example string can be used by any string in FME, including feature type names, attribute names, trait names, coordinate system names, or as part of a file path.

In FME 2022.0 and beyond, these non-ASCII characters should be correctly preserved in the FME application GUIs, logfile, and data files as supported by specific formats.

If the test string appears garbled or contains replacement characters such as question marks, this may be an indication that encodings are not being set or interpreted correctly.
 

Was the FME_createSession entry point removed?

Yes. This was done to require that all FME Objects applications be rebuilt for FME 2022.0.

When an FME Objects application that was built against a version of FME prior to FME 2022.0 is run using FME 2022.0+, Windows will bring up a dialog that looks like this:


However, the FME_createSession() function was kept as an inline function that delegates to the new entrypoint, so recompiling your application is the only action to take. No source code changes are required.

If the FME Objects application was looking up the FME_createSession entry point via GetProcAddress, code changes would be required to access the new entry point (FME_createSession2) directly. Please refer to the documentation for isession.h in your SDK package for more details.