Contents
To build StreamBase C++ client projects for Windows using Visual C++ 14.2 (part of Visual Studio 2019), configure your Visual C++ projects as described on this page. The instructions on this page are expected to work with all Visual Studio editions going forward.
The library-loading pragmas for the StreamBase client API are called from the header
file <streambase/Client.hpp>. Place this file first
in the list of StreamBase-related header files #included in your client code.
Follow these steps to configure a new Visual C++ 2019 project to build StreamBase clients:
-
In your project settings for All Configurations and All Platforms, add two entries:
Configuration Properties Folder Property Page Property Row Setting C/C++ General Additional Include Directories Add streambase-install-dir\includeLinker General Additional Library Directories Add streambase-install-dir\lib\$(Platform)\$(PlatformToolset)When expressing the path to your StreamBase installation directory, do not use
${STREAMBASE_HOME}unless you have explicitly made a global setting for theSTREAMBASE_HOMEenvironment variable. In the default StreamBase installation, this variable is not set globally. -
Specify
#includeas the first StreamBase-related line of your client project's source files.<streambase/Client.hpp>
When used together, these two steps do all the work of configuring to build
StreamBase clients. The Visual Studio macro $(Platform)
resolves to either Win32 or x64, while the macro $(PlatformToolset)
resolves to v142 for Visual C++ 14.2.
Follow these steps to upgrade an existing StreamBase client project to use Visual Studio 2019:
-
If your project files are managed by a version control system, add the new project file format with extension
.vcxprojto the list of recognized extensions. -
In your project settings for All Configurations and All Platforms, adjust two entries:
Configuration Properties Folder Property Page Property Row Setting Linker General Additional Library Directories Replace streambase-install-dir\lib\$(ConfigurationName)streambase-install-dir\lib\$(Platform)\$(PlatformToolset)Linker Input Additional Dependencies Remove the following entries:
LibsbClient-vc#.lib
LibsbUtil-vc#.lib
pthreads-vc#.lib
xercesLib-vc#.lib
WS2_32.lib
Dbghelp.libWhen expressing the path to your StreamBase installation directory, do not use
$(STREAMBASE_HOME)unless you have explicitly made a global setting for theSTREAMBASE_HOMEenvironment variable. In the standard, default StreamBase installation, this variable is not set globally. -
In your StreamBase client source files, replace all instances of:
#include "StreamBaseClient.hpp"with:
#include <streambase/Client.hpp>
To distribute your StreamBase client program to a machine that does not have StreamBase installed, you must also include the correct runtime DLLs for the version of Visual Studio that was used to build it, and those DLLs must match the platform architecture (x86 or x64) as well.
See Microsoft documentation for a discussion of the ways you redistribute the runtime.
Custom .NET operators do not require redistribution setup.
The _SECURE_SCL setting determines whether the Visual C++ runtime checks for unsafe
iterators. When you use the #include
<streambase/Client.hpp> setting recommended above, _SECURE_SCL
is enabled for Debug builds with the StreamBase Client Library, but is disabled for
Release builds.
The Microsoft default setting is enabled (true or 1).
The Client Library provides an iterator handler for Debug builds that converts
iterator bounds exceptions into warnings, which permits your client code to continue
running. It is a best practice leaving _SECURE_SCL in its default true setting when developing and debugging your client code, to help
identify any iterators in your own code that need explicit bounds checking.
However, _SECURE_SCL is disabled (false or 0) by default
for Release builds with the StreamBase Client Library. Without this setting, client
programs exit silently immediately after startup.
This setting is necessary because the StreamBase Client Library includes unchecked iterators by design for runtime efficiency, and does not provide the iterator handler for Release builds. If the Client Library were to add an iterator bounds check for every iterator in the API, this code would run for every tuple, list field, and tuple field encountered, which would significantly slow the client's ability to efficiently consume tuples from StreamBase Server. Instead of accepting this performance penalty at runtime, StreamBase checks during the build of the Library that it uses safe iterators that, for all type and inputs, never exceed their bounds. This one-time performance cost to make sure the iterators are safe occurs during development and QA of the Library at StreamBase. At customer runtime, this performance cost does not need to be incurred again.
It is true that setting _SECURE_SCL=0 means that iterators are not checked. However, unchecked iterators are not necessarily unsafe iterators if QA testing is comprehensive.
If your site policy requires that iterator checks must be enabled for all deployed programs, you can enable _SECURE_SCL and at the same time, enable the Client Library's enabler handler. These settings will significantly impact your client's ability to consume tuples from the Server, and are NOT recommended for production use. In addition, if your client code does encounter an exception related to iterator bounds checking, these settings produce diagnostic output. To use these settings, set:
| #define _SECURE_SCL 1 // NOT RECOMMENDED. See text above. |
| #define STREAMBASE_SET_INVALID_PARAMETER_HANDLER 1 // NOT RECOMMENDED. See text above. |