Configure Visual C++ 9 Projects to Build Clients

Contents

Method 1: Copy Sample Project Files
Method 2: New or Existing Project
About _SECURE_SCL

To build StreamBase C++ clients for Windows using Visual C++ 9.0 (Visual Studio 2008), configure your Visual C++ projects as described on this page.

Alternate Project Types

To configure Visual C++ 9.0 projects to build StreamBase clients, you can either:

  • Method 1: Copy the project files from the StreamBase client sample and edit them.

  • Method 2: Create a new project from scratch or modify an existing Visual Studio project.

Method 1: Copy Sample Project Files

  1. Copy the streambase-install-dir\sample\client folder to your Visual C++ workspace. For clarity, keep your Visual C++ workspace in a separate location from your StreamBase Studio workspace.

    Note

    You must copy this folder from the StreamBase installation directory. Do not make a copy of the client sample in your StreamBase Studio workspace, because the Studio workspace sample does not have the Visual Studio .sln and .vcproj files.

  2. Optional. You can remove unnecessary files from the copied project folder. These files are part of the Java and Python client samples and are not used by the C++ client. Remove the java-src folder and all files with the following extensions: .classpath, .project, .html, .txt, .exe, .launch, .csv, .sbapp, .sbfs, .py.

  3. Locate the client-vc8.sln file. You can optionally rename this file before opening it the first time. Preserve the .sln extension, and choose a basename that reflects the purpose of the intended client. For example, rename client-vc8.sln to AcctDeptLoader.sln.

  4. Start Visual C++ 9.0. Use File → Open → Project to load client-vc8.sln (or your renamed solution file). Let the Conversion Wizard update the solution for Visual C++ 9.0.

  5. Copy or rename one of the existing projects in the Solution Explorer. For example, if you are creating an enqueuing client, rename SimpleEnqueuer to AcctDeptLoader.

  6. In your renamed project folder, rename SimpleEnqueuer.cpp as appropriate for your project (such as AcctDeptLoader.cpp).

  7. Remove the other two projects from your solution.

  8. Right-click your project in the Solution Explorer and select Properties from the context menu.

  9. Locate the places in the project properties that use ${STREAMBASE_HOME} and replace those with the absolute path to your top-level StreamBase installation directory. In general, do this by clicking in the specified setting row, then click the button with three dots to open the Additional Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's directory.

    On the Configuration drop-down menu, select All Configurations.

    Make sure the following settings are in place:

    Property Folder Property Page Property Row Setting
    C/C++ General Additional Include Directories Replace the path that uses ${STREAMBASE_HOME} with the absolute path to the include directory of your StreamBase installation: streambase-install-dir\include
    Linker General Additional Library Directories Replace the path that uses ${STREAMBASE_HOME} with the absolute path to the lib\$(ConfigurationName) directory of your StreamBase installation. The macro $(ConfigurationName) is replaced at runtime with either debug or release to match the current Solution Configuration setting: streambase-install-dir\lib\$(ConfigurationName)

  10. Change the Additional Libraries suffix from vc8 to vc9.

    On the Configuration drop-down menu, select All Configurations.

    Make sure the following settings are in place:

    Configuration Properties Folder Property Page Property Row Setting
    Linker Input Additional Dependencies

    Fill in the Additional Dependencies row with the following entries:

    LibsbClient-vc9.lib
    LibsbUtil-vc9.lib
    WS2_32.lib
    xercesLib-vc9.lib
    Dbghelp.lib

    In the Additional Dependencies dialog, make sure the Inherit from project defaults check box is selected.

  11. Build your project and verify that a working client executable is generated.

  12. Begin customizing the source file for your client.

Method 2: New or Existing Project

Whether using an existing Visual C++ project or starting with a new one, make sure the project's settings match those described in the following steps. All project settings not listed here are optional, and can be changed to match the requirements of your project.

  1. In Visual C++ Studio, select File → New → Project.

    1. In the New Project dialog, select Visual C++ Projects → Win32, then select either Win32 Console Application or Win32 Project, depending the type of client you are creating.

    2. In the Name field, enter a name for your project.

    3. In the Win32 Application Wizard dialog, select Application Settings.

    4. Under Application Type, select Console application or Windows application, depending on the type of client you are creating.

    5. If you already have a C++ file that contains your client code, then under Additional options, select Empty project. If you are starting from scratch, leave this check box cleared.

    6. Under Additional options, clear the Precompiled header check box.

    7. Click Finish. If you have a project already open, click Yes to close that project and open your new project.

  2. If you already have a C++ file for your client, use Windows Explorer to drag that file to the newly created project folder.

  3. Back in Visual C++ Studio, if you dragged a file into the project in step 2, right-click Source Files and select Add to add the new file.

  4. In the Solution Explorer panel, right-click the project just created and select Properties from the context menu.

  5. On the Configuration drop-down menu, select All Configurations.

    Make sure the following settings are in place:

    Configuration Properties Folder Property Page Property Row Setting
    Configuration Properties General Configuration Type From the drop-down menu, select Application (.exe).
    Configuration Properties General Use of MFC From the drop-down menu, select Use Standard Windows Libraries.
    Configuration Properties General Use of ATL From the drop-down menu, select Not Using ATL.
    C/C++ General Additional Include Directories Path to the include directory of your StreamBase installation.

    streambase-install-dir\include

    Do not use the environment variable STREAMBASE_HOME to define this path (unless you have applied this variable globally as described in StreamBase Command Prompt). If there is already an entry in this row that uses ${STREAMBASE_HOME}, replace that entry.

    Instead, click in the row and use the button with three dots on the right side to open the Additional Include Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's include directory.

    C/C++ Preprocessor Preprocessor Definitions Add the following definitions:

    WIN32;

    Linker Input Additional Dependencies

    Fill in the Additional Dependencies row with the following entries:

    LibsbClient-vc9.lib
    LibsbUtil-vc9.lib
    WS2_32.lib
    xercesLib-vc9.lib
    Dbghelp.lib

    In the Additional Dependencies dialog, make sure the Inherit from project defaults check box is selected.

  6. On the Configuration drop-down menu, select the Debug configuration.

    Make sure the following settings are in place:

    Property Folder Property Page Property Row Setting
    C/C++ Code Generation Runtime Library From the drop-down menu, select Multi-threaded Debug DLL (/MDd).
    Linker General Additional Library Directories Append the following path to the entries in that row:

    streambase-install-dir\lib\Debug

    As described above, do not use STREAMBASE_HOME to define this path. If there is already an entry in this row that uses ${STREAMBASE_HOME}, replace that entry.

    Click in the row and use the button with three dots on the right side to open the Additional Library Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's lib\Debug subdirectory.

  7. On the Configuration drop-down menu, select the Release configuration.

    Make sure the following settings are in place:

    Property Folder Property Page Property Row Setting
    C/C++ Code Generation Runtime Library From the drop-down menu, select Multi-threaded DLL (/MD).
    C/C++ Preprocessor Preprocessor Definitions Append _SECURE_SCL=0 to the definitions defined above for the All Configurations case. You end up with:

    WIN32; _SECURE_SCL=0

    See About _SECURE_SCL for an explanation of why this setting is required.

    Linker General Additional Library Directories Append the following path to the entries in that row:

    streambase-install-dir\lib\Release

    As described above, do not use STREAMBASE_HOME to define this path. If there is already an entry in this row that uses ${STREAMBASE_HOME}, replace that entry.

    Click in the row and use the button with three dots on the right side to open the Additional Library Directories dialog. Select a row in this dialog and use the second three-dot button to navigate to your StreamBase installation's lib\Release subdirectory.

Now customize the source file for your client, then build and test it.

About _SECURE_SCL

The _SECURE_SCL setting determines whether the Visual C++ runtime checks for unsafe iterators. The Microsoft default setting is enabled (true or 1), and therefore _SECURE_SCL is enabled for Debug builds of code that uses the StreamBase Client Library. 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 must be disabled (false or 0) 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.