= VoltDB CPP Client Library

The VoltDB client library implements the native VoltDB wire
protocol. You can use the library to connect to a VoltDB cluster,
invoke stored procedures and read responses.

The Using VoltDB Guide explains how to use the CPP library in the
chapter 15.1.1: Writing VoltDB Client Applications in C++.

Binaries for 64-bit Linux and 64-bit OSX 10.5+ are provided. The
linking instructions below apply to the Linux binaries.

== Building the kit samples
In terminal go to the examples directory then run:

make

This will build the HelloWorld, AsyncHelloWorld and Voter applications
that you can then run against a locally running HelloWorld or Voter database.

You can additionally view the source code of the c++ client library and the
examples online at:

      https://github.com/VoltDB/voltdb-client-cpp

== Linking against libvoltdbcpp.a

The following command will compile and link an example client
(clientvoter.cpp) libvoltdb.a.

Note that -lrt and -pthread must appear after the object files being compiled/linked
in more recent Linux distributions.

Directory structure for this example:

./clientvoter.cpp        # Example client
./include                # Directory containing client library headers
./                       # Directory containing client library archive

g++ -I./include/                 \
clientvoter.cpp                  \
./libvoltdbcpp.a                 \
./libevent.a                     \
./libevent_pthread.a             \
-lrt                             \
-pthread                         \
-o voter

Note that -lrt should not be included for the mac edition. See the example makefile
for more detail.

==== Example clientvoter.cpp

/*
 This very simple example demonstrates a few basic concepts.
 This example executes against the 'voter' example included
 in the voltdb distribution.

 The "Using VoltDB Guide" includes more complete information.
*/

#define __STDC_CONSTANT_MACROS
#define __STDC_LIMIT_MACROS

#include "Client.h"
#include "Parameter.hpp"
#include "ParameterSet.hpp"
#include "Row.hpp"
#include "Table.h"
#include "TableIterator.h"
#include "WireType.h"

#include <vector>

using namespace std;

int main(int argc, char** argv) {

    // instantiate a voltdb::Client instance
    voltdb::Client client = voltdb::Client::create();
    client.createConnection("localhost");

    // create a procedure instance for the Initialize procedure
    vector<voltdb::Parameter> initParamTypes(2);
    initParamTypes[0] = voltdb::Parameter(voltdb::WIRE_TYPE_INTEGER);
    initParamTypes[1] = voltdb::Parameter(voltdb::WIRE_TYPE_STRING);
    voltdb::Procedure initialize("Initialize", initParamTypes);
    voltdb::ParameterSet *initParams = initialize.params();

    // invoke the Initialize procedure
    int64_t maxContestant = 4;
    string contestantNames = "Edwina Burnam,Tabatha Gehling,Kelly Clauss,Jessie Alloway";
    initParams->addInt32(maxContestant);
    initParams->addString(contestantNames);
    voltdb::InvocationResponse initResponse = client.invoke(initialize);

    if (initResponse.failure()) {
        cout << "Initialization failed. " << initResponse.toString() << endl;
        return -1;
    }

    cout << "Successfully connected and initialized the database." << endl;
    return 0;
}