- Index

< Previous |  |

# Configure Visual C++ 11 Projects to Build Clients

To build StreamBase C++ client projects for Windows using Visual C++ 11.0 (part of Visual Studio 2012), 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.

It is much simpler to configure projects to build StreamBase clients and plug-ins for Visual C++ 11.0 and later than for earlier Visual C++ versions. Visual C++ 11.0 and later versions allow you to specify a set of library files to be automatically linked into your client module. This avoids having to explicitly specify the import link libraries in the project settings.

The library-loading pragmas are called from the header file `<streambase/Client.hpp>`. Place this file first in the list of StreamBase-related header file #included in your client code.

## Configuring for New Projects

Follow these steps to configure a new Visual C++ 2012 project to build StreamBase clients:

1. 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`\include`, using the full path to your StreamBase installation directory.
   Linker | General | Additional Library Directories | Add ``streambase-install-dir`\lib\$(Platform)\$(PlatformToolset)`, using the full path to your StreamBase installation directory.

   When expressing the path to your StreamBase installation directory, do not use `${STREAMBASE_HOME}` unless you have explicitly made a global setting for the `STREAMBASE_HOME` environment variable. In the default StreamBase installation, this variable is not set globally.

2. Specify `#include `<streambase/Client.hpp>`` as the first StreamBase-related line of your client project's source files.

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 `v110` for Visual C++ 11.0.

## Upgrading Visual Studio 2003-2008 Projects

Follow these steps to upgrade an existing StreamBase client project to use Visual Studio 2012:

1. If your project files are managed by a version control system, add the new project file format with extension `.vcxproj` to the list of recognized extensions.

2. 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)` with ``streambase-install-dir`\lib\$(Platform)\$(PlatformToolset)`, using the full path to your StreamBase installation directory.
   Linker | Input | Additional Dependencies | Remove the following entries: `LibsbClient-vc`#`.lib LibsbUtil-vc`#`.lib pthreads-vc`#`.lib xercesLib-vc`#`.lib WS2_32.lib Dbghelp.lib`

   When expressing the path to your StreamBase installation directory, do not use `$(STREAMBASE_HOME)` unless you have explicitly made a global setting for the `STREAMBASE_HOME` environment variable. In the standard, default StreamBase installation, this variable is not set globally.

3. In your StreamBase client source files, replace all instances of:

   `#include "StreamBaseClient.hpp"`

   with:

   `#include <streambase/Client.hpp>`

## Client Program Redistribution

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. In recommended order:

- Copy the runtime DLLs to the same directory as your client program; the directories where Visual Studio keeps them are listed below. If your client program uses MFC or OpenMP, you must copy more DLLs from that directory.

- If you create a standard MSI installer for your client program, you can incorporate the merge modules provided with Visual Studio, as listed below. All Visual Studio runtime merge modules can be dound in `C:\Program Files (x86)\Common Files\Merge Modules\`.

This table summarizes where the redistributables are found:

Visual Studio version | Runtime DLL names | Runtime DLL directory from Visual Studio | Runtime DLL MSMs
--- | --- | --- | ---
Visual Studio 2012 (including all .NET clients) | `MSVCP110.DLL`, `MSVCR110.DLL` | `C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\redist\`architure`\Microsoft.VC110.CRT\` | `Microsoft_VC110_CRT_x86.msm` or `Microsoft_VC110_CRT_x64.msm`

Custom plugins and .NET operators do not require redistribution setup.

## About _SECURE_SCL

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. TIBCO recommends 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.