docs.xml

<?xml version="1.0" encoding="UTF-8"?>
<book version="5.1" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:trans="http://docbook.org/ns/transclusion"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:m="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title><inlinemediaobject>
        <imageobject>
          <imagedata fileref="docs/images/hammerDB-H-Logo-FB.png"/>
        </imageobject>
      </inlinemediaobject> HammerDB Documentation</title>
  </info>

  <chapter>
    <title>Installation and Configuration</title>

    <section>
      <title>Release Notes</title>

      <para>The following are the release notes for HammerDB v4.0.</para>

      <section>
        <title>Nomenclature Change</title>

        <para>In the database.xml file and the User Interface the workload
        names have changed to TPROC-C and TPROC-H. This is a nomenclature
        change only to represent that the workloads are fair use
        implementations derived from the TPC specifications and the
        nomenclature does not change the functionality of the workload
        compared to prior versions using the TPC-C and TPC-H
        terminology.</para>
      </section>

      <section>
        <title>Stored Procedure Refactoring and Performance</title>

        <para>At version 4.0 the stored procedures for the Oracle and
        PostgreSQL TPROC-C workloads have been refactored. This increases the
        expected performance between versions and consequently the performance
        from HammerDB v4.0 cannot be compared directly to the performance of
        v3.3 or previous releases. Additionally for some workloads HammerDB
        v4.0 changes the relationship between the NOPM and TPM metrics
        compared to previous versions. As a result of the stored procedure
        refactoring using bulk operations more work is processed per commit
        and therefore in these cases the NOPM has increased whilst the TPM
        remains the same. This indicates a real measure of increased
        throughput by doing more work per database transaction and
        consequently NOPM is now listed first as the primary metric in
        reporting output. However as raised in <link
        xlink:href="https://github.com/TPC-Council/HammerDB/issues/111">HammerDB
        GitHub Issue #111</link> there may be cases where there is a
        dependency on the wording of the HammerDB log. For this reason a
        configuration option in the generic.xml file of first_result is given.
        If this option is set to NOPM then the v4.0 format is used if set to
        TPM then the output is compatible with v3.3.</para>

        <programlisting>&lt;benchmark&gt;
&lt;rdbms&gt;Oracle&lt;/rdbms&gt;
&lt;bm&gt;TPC-C&lt;/bm&gt;
<emphasis role="bold">&lt;first_result&gt;NOPM&lt;/first_result&gt;</emphasis>
&lt;/benchmark&gt;</programlisting>
      </section>

      <section>
        <title>Redis Deprecated</title>

        <para>The Redis workload has been deprecated and no longer features by
        default in the main HammerDB menu. In particular as a single-threaded
        database without support for stored procedures it was considered that
        Redis was not suitable for running workloads derived from the TPC
        specifications and could not reach similar levels of performance as
        the relational databases currently supported. Redis can still be
        enabled for unsupported use by uncommenting the Redis database entry
        in database.xml.</para>

        <programlisting><emphasis role="bold">&lt;!--Redis deprecated, uncomment to enable as unsupported</emphasis>
&lt;redis&gt;
&lt;name&gt;Redis&lt;/name&gt;
&lt;description&gt;Redis&lt;/description&gt;
&lt;prefix&gt;redis&lt;/prefix&gt;
&lt;library&gt;redis&lt;/library&gt;
&lt;workloads&gt;{TPROC-C}&lt;/workloads&gt;
&lt;commands&gt;redis&lt;/commands&gt;
&lt;/redis&gt;
<emphasis role="bold">--&gt;</emphasis></programlisting>
      </section>

      <section>
        <title>Known Third-Party Driver Issues</title>

        <para>HammerDB has a dependency on 3rd party driver libraries to
        connect to the target databases. The following are known issues with
        some of the 3rd party drivers that HammerDB uses.</para>

        <section>
          <title>Oracle on Windows: Oracle Bug 12733000 OCIStmtRelease crashes
          or hangs if called after freeing the service context handle</title>

          <para>If you are running HammerDB against Oracle on Windows there is
          long established bug in Oracle that can cause application crashes
          for multi-threaded applications on Windows.This bug can be
          investigated on the My Oracle Support website with the following
          reference. Bug 12733000 OCIStmtRelease crashes or hangs if called
          after freeing the service context handle. To resolve this Oracle
          issue add the following entry to the SQLNET.ORA file on your
          HammerDB client.</para>

          <programlisting>SQLNET.AUTHENTICATION_SERVICES = (NTS)
DIAG_ADR_ENABLED=OFF 
DIAG_SIGHANDLER_ENABLED=FALSE
DIAG_DDE_ENABLED=FALSE</programlisting>
        </section>

        <section>
          <title>SQL Server on Linux: unixODBC's handle validation may become
          a performance bottleneck</title>

          <para>Using the HammerDB client for SQL Server on Linux can be
          slower than the same client on Windows when using the default
          installed unixODBC drivers on many Linux distributions. As described
          in the <link
          xlink:href="https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/programming-guidelines?view=sql-server-ver15">SQL
          Server Programming Guidelines</link> "<emphasis>When using the
          driver with highly multithreaded applications, unixODBC's handle
          validation may become a performance bottleneck. In such scenarios,
          significantly more performance may be obtained by compiling unixODBC
          with the --enable-fastvalidate option. However, beware that this may
          cause applications which pass invalid handles to ODBC APIs to crash
          instead of returning SQL_INVALID_HANDLE errors.</emphasis>"
          Recompiling unixODBC with the --enable-fastvalidate option has been
          measured to improve client performance by 2X. Example configure
          options used to build unixODBC are shown as follows:</para>

          <programlisting>./configure --prefix=/usr/local/unixODBC --enable-gui=no --enable-drivers=no --enable-iconv 
--with-iconv-char-enc=UTF8 --with-iconv-ucode-enc=UTF16LE --enable-threads=yes <emphasis
              role="bold">--enable-fastvalidate</emphasis></programlisting>
        </section>
      </section>

      <section>
        <title>Linux Font Pre-Installation Requirements</title>

        <para>On Linux HammerDB requires the Xft FreeType-based font drawing
        library for X installed as follows:</para>

        <para>Ubuntu:</para>

        <para><programlisting>$ sudo apt-get install libxft-dev</programlisting>Red
        Hat:</para>

        <programlisting>$ yum install libXft</programlisting>
      </section>
    </section>

    <section>
      <title>Documentation License and Copyright</title>

      <para>Copyright (C) 2020 Steve Shaw.</para>

      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.3 or any later version published by the Free Software Foundation; with
      no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
      copy of the license is included in the section entitled "GNU Free
      Documentation License".</para>
    </section>

    <section>
      <title>HammerDB v4.0 New Features</title>

      <para>Updated Binaries to: tcl8.6.10, tk8.6.10, thread2.8.5, oratcl4.6,
      mysqltcl3.052, pgtcl2.1.1, db2tcl2.0.0</para>

      <para>HammerDB v4.0 New Features are all referenced to GitHub issues,
      where more details for each new feature and related pull requests can be
      found here: <link
      xlink:href="https://github.com/TPC-Council/HammerDB/issues">https://github.com/TPC-Council/HammerDB/issues</link></para>

      <para>[TPC-Council#152] Inclusive Language Updates</para>

      <para>[TPC-Council#149] Add runtimer and waittocomplete routines to
      CLI</para>

      <para>[TPC-Council#148] HammerDB CLI on Windows can have incorrect
      colours</para>

      <para>[TPC-Council#140] Update SQL Server ODBC Driver</para>

      <para>[TPC-Council#139] Fix XML closing tags for sprocs and
      connpool</para>

      <para>[TPC-Council#138] Update SQL Server library version number for
      TCL8.6.10</para>

      <para>[TPC-Council#137] Update versions, changelog and OSS-TPC-x
      workloads</para>

      <para>[TPC-Council#136] update dbms_random for PostgreSQL neword
      infinite loop</para>

      <para>[TPC-Council#135] multiple labelled connections / connect pool
      feature</para>

      <para>[TPC-Council#132] Use Existing User and DB in Postgres</para>

      <para>[TPC-Council#126] Adding docs directory and documentation
      files</para>

      <para>[TPC-Council#124] Make column order in stock_i1 index in
      PostgreSQL consistent with Oracle</para>

      <para>[TPC-Council#121] Fix temp environment variables not
      detected</para>

      <para>[TPC-Council#119] Fix for Issue #118 using diset with variables
      with spaces</para>

      <para>[TPC-Council#115] Add partitioning hints in PostgreSQL neword
      transaction</para>

      <para>[TPC-Council#106] Format details repo</para>

      <para>[TPC-Council#105] Deprecated Redis</para>

      <para>[TPC-Council#104] Reverse print out of metrics to put NOPM ahead
      of TPM</para>

      <para>[TPC-Council#98] MySQL prepared statements and socket
      option</para>

      <para>[TPC-Council#97] Partitioning for Oracle ORDERS and HISTORY</para>

      <para>[TPC-Council#95] PostgreSQL prepared statements for functions and
      tablespace option for schema builds</para>

      <para>[TPC-Council#92] Refactor Oracle and Postgres procedural code for
      performance</para>

      <para>[TPC-Council#91] Added Master/Slave Modes to CLI</para>

      <para>[TPC-Council#86] Added Geomean calculation to TPC-H
      workloads</para>

      <para>[TPC-Council#82] Fix distribution of Warehouse across VUs for All
      Warehouse option</para>

      <para>[TPC-Council#46] Consider changing "Benchmark Options" from TPC-C
      or TPC-H to something that underscores "based on TPC-C/TPC-H"</para>

      <para>[TPC-Council#19] GUI HD Display</para>
    </section>

    <section>
      <title>Test Matrix</title>

      <para>The following test matrix is provided as a guide based on the
      operating system and database releases that HammerDB has been built and
      tested against. The matrix is not an exclusive support or configuration
      matrix and HammerDB has been designed to be compatible with the
      supported databases running on different architectures and operating
      systems. HammerDB is built for the x88-64 architecture on Linux and
      Windows. Where the database is not running on either Linux or Windows on
      x86-64 HammerDB can be run on Linux or Windows and connect to the target
      database on another architecture over a network.</para>

      <para>HammerDB has been built and tested on the following x86 64-bit
      Linux and Windows releases.</para>

      <para><table>
          <title>OS Test Matrix</title>

          <tgroup cols="2">
            <thead>
              <row>
                <entry align="center">Operating System</entry>

                <entry align="center">Release</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Linux</entry>

                <entry>Ubuntu 17.X 18.X 19.X / RHEL 7.X RHEL 8.X</entry>
              </row>

              <row>
                <entry>Windows</entry>

                <entry>Windows 10</entry>
              </row>
            </tbody>
          </tgroup>
        </table></para>

      <para>HammerDB has been built and testing on the following x86-64 64-bit
      Databases.</para>

      <table>
        <title>Database Test Matrix</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Database (Compatible)</entry>

              <entry align="center">Release</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>Oracle (TimesTen)</entry>

              <entry>12c / 18c / 19c</entry>
            </row>

            <row>
              <entry>Microsoft SQL Server</entry>

              <entry>2017 / 2019</entry>
            </row>

            <row>
              <entry>Db2</entry>

              <entry>11.1</entry>
            </row>

            <row>
              <entry>MySQL (MariaDB) (Amazon Aurora)</entry>

              <entry>5.7 / 8.0 / 10.2 / 10.3 / 10.4 / 10.5</entry>
            </row>

            <row>
              <entry>PostgreSQL (EnterpriseDB) (Amazon Redshift)
              (Greenplum)</entry>

              <entry>10.2 / 10.3 / 11 / 12 / 13</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section>
      <title>Checksum Verification</title>

      <para>Checksums for the installation files are shown alongside the
      download files in <link
      xlink:href="https://github.com/TPC-Council/HammerDB/releases">GitHub
      Releases</link>. The integrity of the HammerDB installation files can be
      verified on Windows with the Microsoft File Checksum Integrity Verifier
      which can be downloaded at no cost from Microsoft and run as
      follows:</para>

      <programlisting>fciv -both HammerDB-4.0-Win-x86-64-Setup.exe</programlisting>

      <para>and on Linux with md5sum and sha1sum as shown:</para>

      <programlisting>md5sum HammerDB-4.0-Linux.tar.gz 
sha1sum HammerDB-4.0-Linux.tar.gz</programlisting>
    </section>

    <section>
      <title>Installing and Starting HammerDB on Windows</title>

      <para>To install HammerDB on Windows you have the option of using the
      self-extracting installer or zipfile. The self-extracting installer will
      create an uninstall executable for you. A zipfile installation can be
      deleted manually. In both cases the install is entirely self-contained
      within the installation directory.</para>

      <section>
        <title>Self Extracting Installer</title>

        <para>Double click on the Setup file and the language choice is
        shown.</para>

        <para>Click continue to begin the installation.</para>

        <figure>
          <title>HammerDB Version</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-4.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Read and Accept the GPL License Agreement.</para>

        <figure>
          <title>GPL v3 License</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-5.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Choose the installation directory.</para>

        <figure>
          <title>Choose the Installation Directory</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-6.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Press Next to begin the install.</para>

        <figure>
          <title>Files copying</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-7.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>The installer will extract the files into the chosen
        directory.</para>

        <figure>
          <title>Complete</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-8.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Complete the Install by viewing the Readme File and running
        HammerDB. If both options are chosen HammerDB will run after the
        Readme is closed.</para>

        <figure>
          <title>Complete the Setup Wizard</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-8a.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>HammerDB will start ready for you to use</para>

        <figure>
          <title>HammerDB Started</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-9.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Zip File</title>

        <para>As an alternative to the self-extracting installer you can
        download and extract the zipfile into a directory of your
        choice.</para>

        <figure>
          <title>Zip File</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-10.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para/>
      </section>

      <section>
        <title>Starting HammerDB</title>

        <para>After installation double-click on the "Windows Batch File"
        hammerdb to start hammerdb.</para>

        <figure>
          <title>hammerdb batch file</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-11.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Uninstalling HammerDB</title>

        <para>For a zipfile installation, delete the hammerDB directory. For
        an installer based installation double-click on uninstall and follow
        the on-screen prompts.</para>

        <figure>
          <title>Uninstall</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch1-12.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>
    </section>

    <section>
      <title>Installing and Starting HammerDB on Linux</title>

      <para>To install HammerDB on Linux you have the option of using the
      self-extracting installer or a tar.gz file. The self-extracting
      installer will create an uninstall executable for you. A tar.gz
      installation can be deleted manually. In both cases the install is
      entirely self-contained within the installation directory.</para>

      <section>
        <title>Self Extracting Installer</title>

        <para>To install from the self-extracting installer using a graphical
        environment refer to the previous section on the self-extracting
        installer for Windows, the installation method is the same.</para>
      </section>

      <section>
        <title>Tar.gz File</title>

        <para>To install from the tar.gz run the command</para>

        <programlisting>tar -zxvf HammerDB-4.0.tar.gz </programlisting>

        <para>This will extract HammerDB into a directory named
        HammerDB-4.0.</para>
      </section>

      <section>
        <title>Starting HammerDB</title>

        <para>To start HammerDB change to the HammerDB directory and run
        locally as follows.</para>

        <programlisting>./hammerdb</programlisting>
      </section>

      <section>
        <title>Uninstalling HammerDB</title>

        <para>To uninstall HammerDB on Linux run the uninstall executable for
        the self-extracting installer or remove the directory for the tar.gz
        install.</para>
      </section>
    </section>

    <section>
      <title>Verifying the Installation of Database Client Libraries</title>

      <para>For all of the databases that HammerDB supports it is necessary to
      have a third-party client library installed that HammerDB can use to
      connect and interact with the database. This client library will also
      typically be installed with database server software. HammerDB does not
      statically link the 3rd party libraries to minimise executable size and
      provide flexibility in the third-party libraries used. For example if a
      bug is detected in a particular library then this can be upgraded
      without requiring the HammerDB libraries to be rebuilt. However as the
      client libraries are dynamically linked it is essential that the correct
      client libraries are already installed and environment variables set to
      ensure that HammerDB can find the correct libraries. Note that it is
      only necessary to load the libraries for the database that your are
      testing.</para>

      <para>The HammerDB command line tool can be used to check the status of
      library availability for all databases.</para>

      <para>To run this utility run the following command</para>

      <programlisting>./hammerdbcli</programlisting>

      <para>and type librarycheck.</para>

      <programlisting>HammerDB CLI v4.0
Copyright (C) 2003-2020 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
hammerdb&gt;librarycheck
Checking database library for Oracle
Success ... loaded library Oratcl for Oracle
Checking database library for MSSQLServer
Success ... loaded library tdbc::odbc for MSSQLServer
Checking database library for Db2
Success ... loaded library db2tcl for Db2
Checking database library for MySQL
Success ... loaded library mysqltcl for MySQL
Checking database library for PostgreSQL
Success ... loaded library Pgtcl for PostgreSQL

hammerdb&gt;
</programlisting>

      <para>in the example it can be seen that the libraries for all databases
      were found and loaded. The following table illustrates the first level
      library that HammerDB requires however there may be additional
      dependencies. Refer to the Test Matrix to determine which database
      versions HammerDB was built against. On Windows the <link
      xlink:href="https://dependencywalker.com/">Dependency Walker
      Utility</link> can be used to determine the dependencies and on Linux
      the command ldd.</para>

      <para>For example on Windows use dependency walker to open the HammerDB
      library for your chosen database. In the following example
      libmysqltcl.dll is opened for MySQL. This shows that the key dependency
      is on the 64-bit libmysql.dll.</para>

      <figure>
        <title>Dependency Walker MySQL</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-13.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Right-clicking on this library shows the properties including
      where it was found.</para>

      <figure>
        <title>LIBMYSQL.DLL Properties</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-14.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This location was set in the Environment variables under the Path
      option.</para>

      <figure>
        <title>Environment Variables</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-15.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>As shown below hammerDB found the correct MySQL 8.0 library
      because the path to the 64-bit MySQL 8.0 library was set correctly in
      the environment variables.</para>

      <figure>
        <title>Path environment variable</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-16.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>On Linux we run a similar test with librarycheck, however in this
      instance the library file is not found, although note that it identifies
      the file that is missing as libmysqlclient.so.21.</para>

      <programlisting>Checking database library for MySQL
Error: failed to load mysqltcl - couldn't load file "/home/steve/HammerDB-4.0/lib/mysqltcl-3.052/libmysqltcl3.052.so": libmysqlclient.so.21: cannot open shared object file: No such file or directory
Ensure that MySQL client libraries are installed and the location in the LD_LIBRARY_PATH environment variable
</programlisting>

      <para>We can investigate further using the ldd command in an equivalent
      way to dependency walker on Windows. This also identifies the file that
      is missing.</para>

      <programlisting>$ ldd libmysqltcl3.052.so 
linux-vdso.so.1 (0x00007ffc44f7d000)
<emphasis role="bold">libmysqlclient.so.21 =&gt; not found</emphasis>
libc.so.6 =&gt; /lib/x86_64-linux-gnu/libc.so.6 (0x00007f33e73e7000)
/lib64/ld-linux-x86-64.so.2 (0x00007f33e79e2000)
</programlisting>

      <para>Checking in our MySQL installation we can find the file
      libmysqlclient.so.21.</para>

      <programlisting>$ pwd
/opt/mysql-8.0.18-linux-glibc2.12-x86_64/lib
$ ls libmysqlclient*
libmysqlclient.a  libmysqlclient.so  libmysqlclient.so.21  libmysqlclient.so.21.1.18
</programlisting>

      <para>Therefore we know that the file is installed, however we need to
      tell HammerDB where to find it. This is done by adding the MySQL library
      to the LD_LIBRARY_PATH.</para>

      <programlisting>$ export LD_LIBRARY_PATH=/opt/mysql-8.0.18-linux-glibc2.12-x86_64/lib:$LD_LIBRARY_PATH</programlisting>

      <para>Reversing our steps we can see that the library is now
      found.</para>

      <programlisting>$ ldd libmysqltcl3.052.so 
linux-vdso.so.1 (0x00007fff7f7e6000)
libmysqlclient.so.21 =&gt; /opt/mysql-8.0.18-linux-glibc2.12-x86_64/lib/libmysqlclient.so.21 (0x00007f92b0153000)
libc.so.6 =&gt; /lib/x86_64-linux-gnu/libc.so.6 (0x00007f92afd62000)
libpthread.so.0 =&gt; /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f92afb43000)
libdl.so.2 =&gt; /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f92af93f000)
libssl.so.1.1 =&gt; /opt/mysql-8.0.18-linux-glibc2.12-x86_64/lib/libssl.so.1.1 (0x00007f92af6b5000)
libcrypto.so.1.1 =&gt; /opt/mysql-8.0.18-linux-glibc2.12-x86_64/lib/libcrypto.so.1.1 (0x00007f92af270000)
librt.so.1 =&gt; /lib/x86_64-linux-gnu/librt.so.1 (0x00007f92af068000)
libstdc++.so.6 =&gt; /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f92aecdf000)
libm.so.6 =&gt; /lib/x86_64-linux-gnu/libm.so.6 (0x00007f92ae941000)
libgcc_s.so.1 =&gt; /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f92ae729000)
/lib64/ld-linux-x86-64.so.2 (0x00007f92b0c34000)</programlisting>

      <para>and library check confirms that it can be loaded.</para>

      <programlisting>Checking database library for MySQL
Success ... loaded library mysqltcl for MySQL</programlisting>

      <para>Add the export command to the .bash_profile ensures that it will
      be found each time HammerDB is launched from a new shell.</para>

      <para>The following table shows the libraries that are required for each
      database version. All libraries are 64-bit. Note that some databases are
      considerably more flexible in library versions and therefore the
      following section is important to ensure that you install the correct
      library for your needs.</para>

      <table>
        <title>3rd party libraries</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Database / OS</entry>

              <entry align="center">Library</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>Oracle Linux</entry>

              <entry>libclntsh.so</entry>
            </row>

            <row>
              <entry>Oracle Windows</entry>

              <entry>OCI.DLL</entry>
            </row>

            <row>
              <entry>SQL Server Linux</entry>

              <entry>libodbc.so</entry>
            </row>

            <row>
              <entry>SQL Server Windows</entry>

              <entry>ODBC32.DLL</entry>
            </row>

            <row>
              <entry>Db2 Linux</entry>

              <entry>libdb2.so</entry>
            </row>

            <row>
              <entry>Db2 Windows</entry>

              <entry>DB2CLI64.DLL</entry>
            </row>

            <row>
              <entry>MySQL Linux</entry>

              <entry>libmysqlclient.so</entry>
            </row>

            <row>
              <entry>MySQL Windows</entry>

              <entry>LIBMYSQL.DLL</entry>
            </row>

            <row>
              <entry>PostgreSQL Linux</entry>

              <entry>libpq.so</entry>
            </row>

            <row>
              <entry>PostgreSQL Windows</entry>

              <entry>LIBPQ.DLL</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <section>
        <title>Oracle Client</title>

        <para>When using the Oracle instant client Oratcl uses the additional
        environment variable ORACLE_LIBRARY to identify the Oracle client
        library. On the Windows the Oracle client library is called oci.dll in
        a location such as: C:\oraclexe\app\oracle\product\11.2.0\server\bin.
        On Linux the library is called libclntsh.so where this is typically a
        symbolic link to a product specific name such as libclntsh.so.12.1 for
        Oracle 12c. An example .bash_profile file is shown for a typical
        Oracle environment.</para>

        <programlisting>oracle@server1  oracle]$ cat ~/.bash_profile
# .bash_profile

if [ -t 0 ]; then
stty intr ^C
fi

# Get the aliases and functions
if [ -f ~/.bashrc ]; then
        . ~/.bashrc
fi
# User specific environment and startup programs
umask 022
export ORACLE_BASE=/u01/app/oracle
export ORACLE_HOME=$ORACLE_BASE/product/12.1.0/dbhome_1
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
export ORACLE_LIBRARY=$ORACLE_HOME/lib/libclntsh.so
export ORACLE_SID=PROD1
export PATH=$ORACLE_HOME/bin:$PATH
</programlisting>
      </section>

      <section>
        <title>SQL Server</title>

        <para>On SQL Server on Windows the client libraries and necessary
        environment variables are set automatically during the SQL Server
        installation. Note that on 64-bit Windows the 64-bit ODBC client
        library is named ODBC32.DLL in the following location.
        C:\Windows\System32\odbc32.dll. On Linux follow the SQL Server on
        Linux installation guide to install 'mssql-tools' with the unixODBC
        developer package. The command database drivers will show the
        installed ODBC Driver.</para>

        <programlisting>hammerdb&gt;database drivers
{{ODBC Driver 17 for SQL Server} {{Description=Microsoft ODBC Driver 17 for SQL Server} 
Driver=/opt/microsoft/msodbcsql/lib64/libmsodbcsql-17.0.so.1.1 UsageCount=1}}</programlisting>
      </section>

      <section>
        <title>Db2</title>

        <para>For DB2 on Linux the client library libdb2.so.1 is required
        either in the lib64 directory for 32. Similarly on Windows the
        db2cli64.dll is required. These libraries are included with a standard
        DB2 installation or also with a standalone DB2 client install.</para>
      </section>

      <section>
        <title>MySQL</title>

        <para>HammerDB version 4.0 (and version 3.3) has been built and tested
        against a MySQL 8.0 client installation, hammerDB version 3.0-3.2 has
        been built against MySQL 5.7. On Linux this means that HammerDB will
        require a MySQL client library called libmysqlclient.so.21 for
        HammerDB version 4.0 and 3.3 and libmysqlclient.so.20 for version 3.2
        and earlier. This client library needs to be referenced in the
        LD_LIBRARY_PATH as shown previously in this section. Note that for
        testing MariaDB you also need the libmysqlclient.so.21 from an
        installation of MySQL 8.0. You do not need to install MySQL 8.0 as the
        only file you need is "libmysqlclient.so.21". With this file installed
        and in the library path the HammerDB client can connect to
        MariaDB.</para>
      </section>

      <section>
        <title>PostgreSQL</title>

        <para>For PostgreSQL the client library is called libpq.dll on Windows
        and libpq.so on Linux however note that additional libraries are also
        required. For Windows this means setting your PATH environment
        variable such as the following: D:\PostgreSQL\pgsql\bin; On Linux it
        is required to set the LD_LIBRARY_PATH environment variable in the
        same way described for Oracle previously in this section to the
        location of the PostgreSQL lib directory. Alternatively for
        installations of EnterpriseDB the client directory also contains the
        necessary files for a HammerDB installation.</para>
      </section>
    </section>

    <section>
      <title>XML Configuration</title>

      <para>HammerDB configuration and settings are defined in a number of XML
      files in the config directory. You may edit these files to change the
      configuration on startup, however it is recommended to save a copy of
      the original in case of incompatible changes.</para>

      <figure>
        <title>XML Configuration Files</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-17.PNG"/>
          </imageobject>
        </mediaobject>

        <para>By default the databases in the GUI menu are listed in the order
        that the workloads were added to HammerDB. If you wish to change the
        order to put a particular database first you can change the rdbms
        value in generic.xml to the name of the database of your choice. The
        name entry for a particular database can be found in the database.xml
        file. For example the following would set SQL Server to be the
        database at the top of the menu on startup.</para>

        <programlisting>&lt;benchmark&gt;
&lt;rdbms&gt;MSSQLServer&lt;/rdbms&gt;
&lt;bm&gt;TPC-C&lt;/bm&gt;
&lt;first_result&gt;NOPM&lt;/first_result&gt;
&lt;/benchmark&gt;</programlisting>
      </figure>
    </section>

    <section>
      <title>Themes and Scalable Graphics</title>

      <para>HammerDB v4.0 includes an updated graphical interface that adapts
      to scale to UHD displays such as Microsoft pixelsense displays. The
      behaviour of the display is set in the theme section of
      generic.xml.</para>

      <programlisting>&lt;theme&gt;
&lt;scaling&gt;auto&lt;/scaling&gt;
&lt;scaletheme&gt;auto&lt;/scaletheme&gt;
&lt;pixelsperpoint&gt;auto&lt;/pixelsperpoint&gt;
&lt;/theme&gt;</programlisting>

      <para>By default scaling, the scaletheme and pixelsperpoint are all set
      to auto. This means that HammerDB will detect the display settings and
      scale the interface accordingly. For example the image shows HammerDB
      v3.3 and v4.0 on the same UHD display.</para>

      <figure>
        <title>Scaling Graphics</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-18.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>However some displays or third-party X Windows servers may not be
      updated to support scalable graphics. In this case the scaling value can
      be set to fixed and a standard 96 dpi display will be used with the
      fixed themes from HammerDB v3.3.</para>

      <programlisting>&lt;theme&gt;
&lt;scaling&gt;fixed&lt;/scaling&gt;
&lt;scaletheme&gt;auto&lt;/scaletheme&gt;
&lt;pixelsperpoint&gt;auto&lt;/pixelsperpoint&gt;
&lt;/theme&gt;</programlisting>

      <para>The scaletheme value will accept settings of "auto", "awlight",
      "arc" or "breeze". If set to the default of "auto", "awlight" will be
      used on Linux.</para>

      <figure>
        <title>Linux Theme Awlight</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-19.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>and "breeze" on Windows.</para>

      <figure>
        <title>Windows Theme Breeze</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch1-9.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The scale factor can be fine-tuned by setting the pixelsperpoint
      value. By running the command puts [ tk scaling ] in the console you can
      determine the current value. By setting this value slightly larger or
      smaller than the default you can adjust the scaling to your system. This
      value is not intended for large scale changes from the default as
      settings have been adjusted to the detected value.</para>

      <programlisting>(HammerDB-4.0) 49 % puts [ tk scaling ]
1.3333333333333333</programlisting>
    </section>
  </chapter>

  <chapter>
    <title>Quick Start</title>

    <para>Before proceeding you should have your database software installed
    and running and be familiar with basic functionality of connecting to your
    database. After starting HammerDB, firstly you will need to select which
    benchmark and database you wish to use by choosing Benchmark from under
    the Options menu or double on your chosen database in the tree-view. The
    initial settings are determined by the values in your xml configuration
    file. Select your chosen database and TPROC-C and press OK. This Quick
    Start guide uses Microsoft SQL Server, however the process is the same for
    all other supported databases.</para>

    <section>
      <title>Building the Schema</title>

      <para><figure>
          <title>Benchmark Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch2-1.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Click on the Benchmark tree view, under TPROC-C select TPROC-C
      Schema Build Options to display the TPROC-C Schema Options window.
      Within this window enter the connection details of your database
      software. These options will vary depending on the database chosen.
      Select a number of warehouses, 10 is good for a first test and set the
      Virtual Users to build schema to the number of CPU cores on your system.
      Click OK.</para>

      <figure>
        <title>Build Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>.</para>

      <para>Double-click on Build in the tree view and you will receive a
      prompt on the settings chosen to build the schema. Click Yes.</para>

      <para><figure>
          <title>Create Schema</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch2-3.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Observe that HammerDB begins to build the schema with multiple
      users.</para>

      <figure>
        <title>Building Schema</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Wait until the schema build completes and then click on the red
      button, tagged with Destroy Virtual Users.</para>

      <figure>
        <title>Schema build complete</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-5.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Within the tree-view Select Driver Script Options. Leave the
      settings at Test Driver Script and click OK</para>
    </section>

    <section>
      <title>Run a Test Workload</title>

      <para><figure>
          <title>Driver Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch2-6.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>Observe that the Driver Script is Loaded. Clicking on Load
      will reload the script.</para>

      <figure>
        <title>Driver Script Loaded</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-7.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Further down the tree-view under Virtual User select Options and
      select "2" for the number of Virtual Users, click OK.</para>

      <figure>
        <title>Virtual User Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-8.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Click on Create and the Virtual Users will be created and waiting
      to run in an idle status. (Clicking run first will run both Create and
      Run Immediately).</para>

      <para><figure>
          <title>Virtual Users Created</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch2-9.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Double-click on Run - you can now observe the Virtual Users
      running a workload against the database. When ready press the red stop
      button to stop the workload.</para>

      <para><figure>
          <title>Virtual Users Running</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch2-10.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>
    </section>

    <section>
      <title>Run a Timed Workload</title>

      <para>the Test script is to check connectivity and diagnose performance
      and configuration errors. It is the Timed Workload that should be used
      to conduct performance tests. Under Driver Options select Timed Driver
      Script and click OK, the Timed Driver Script is now loaded.</para>

      <para/>

      <figure>
        <title>Driver Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-11.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Verify the Virtual User Options.</para>

      <figure>
        <title>Virtual Users</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-12.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Click create Virtual User and observe that for Timed workloads an
      additional Virtual User has been created. This Virtual User does not run
      the workload but provides the timing and monitoring
      functionality.</para>

      <figure>
        <title>Virtual User and Monitor Created</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-13.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Click Run, the workload will begin but this time without the
      Virtual User output being written to the screen. The Monitor Virtual
      User will provide information on Timing as the workload
      progresses.</para>

      <figure>
        <title>Timed Workload Running</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-14.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>On completion observe that the Monitor Virtual User reports a
      value for NOPM and a value for TPM. NOPM stands for New Orders per
      Minute and is extracted from the database schema and is therefore
      database independent meaning it is valid to compare between different
      databases. TPM is the transactions per minute and is a unique value to
      how each database processes transactions. NOPM is the key performance
      metric however TPM is the metric that correlates with database
      performance tools measurement of transactions per second or minute and
      can therefore be used by database engineers for deeper analysis of
      database performance.</para>

      <figure>
        <title>Test Result</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-15.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section>
      <title>Using the Transaction Counter</title>

      <para>During a workload press the Transaction Counter button. This will
      report the TPM value at a timed interval (default 10 seconds) to the
      screen.</para>

      <figure>
        <title>Transaction Counter</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch2-16.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </chapter>

  <chapter>
    <title>Introduction to OLTP Testing (TPROC-C derived from TPC-C)</title>

    <section>
      <title>What is a Transactional Workload</title>

      <para>A transactional or OLTP (online transaction processing) workload
      is a workload typically identified by a database receiving both requests
      for data and multiple changes to this data from a number of users over
      time where these modifications are called transactions. Each database
      transaction has a defined beginning point, manipulates and modifies the
      data within the database and either commits the changes or rollbacks the
      changes to the starting point. A database must adhere to the ACID
      (Atomicity, Consistency, Isolation, Durability) properties to ensure
      that the database remains consistent whilst processing transactions.
      Database systems that process transactional workloads are inherently
      complex in order to manage the user sessions access to same data at the
      same time, processing the transactions in isolation whilst keeping the
      database consistent and recoverable. People will typically interact with
      OLTP systems on a regular basis with examples such as an online grocery
      ordering and delivery system or an airline reservation system.
      Performance and scalability are essential properties of systems designed
      to process transactional workloads. The TPC-C benchmark is a benchmark
      designed by the TPC to measure the performance of the software and
      hardware of a relational database system to process these
      workloads.</para>
    </section>

    <section>
      <title>What is the TPC and the TPROC-C workload derived from
      TPC-C?</title>

      <para>Designing and implementing a database benchmark is a significant
      challenge. Many performance tests and tools experience difficulties in
      comparing system performance especially in the area of scalability, the
      ability of a test conducted on a certain system and schema size to be
      comparable with a test on a larger scale system. When system vendors
      wish to publish validated benchmark information about database
      performance they have needed to access sophisticated test specifications
      and the TPC is the industry body most widely recognized for defining
      benchmarks. TPC specifications are the only published benchmarks in the
      database industry recognized by all of the leading database vendors.
      TPC-C is the benchmark published by the TPC for Online Transaction
      Processing and you can view the published TPC-C results at the TPC
      website.</para>

      <para>The TPC Policies allow for derivations of TPC Benchmark Standards
      that comply with the TPC Fair Use rules. TPROC-C is the OLTP workload
      implemented in HammerDB derived from the TPC-C specification with
      modification to make running HammerDB straightforward and cost-effective
      on any of the supported database environments. The HammerDB TPROC-C
      workload is an open source workload derived from the TPC-C Benchmark
      Standard and as such is not comparable to published TPC-C results, as
      the results comply with a subset rather than the full TPC-C Benchmark
      Standard. The name for the HammerDB workload TPROC-C means "Transaction
      Processing Benchmark derived from the TPC "C" specification".</para>
    </section>

    <section>
      <title>HammerDB TPROC-C workload</title>

      <para>The HammerDB TPROC-C workload is intentionally not fully optimized
      and not biased towards any particular database implementation or system
      hardware, being open source you are free to inspect all of the HammerDB
      source code and to submit pull requests to update or enhance the
      workloads. The intent is to provide an out-of-the-box type experience
      when testing a database without requiring complex configurations or
      additional third-party software in addition to both HammerDB and the
      database you are testing. HammerDB can be run on any environment from a
      simple laptop based express type database install right through to 8, 16
      and 32 CPU socket servers and clusters. The crucial element is to
      reiterate the point made in the previous section that the HammerDB
      workloads are designed to be reliable, scalable and tested to produce
      accurate, repeatable and consistent results. In other words HammerDB is
      designed to measure relative as opposed to absolute database performance
      between systems. What this means is if you run a test against one
      particular configuration of hardware and software and re-run the same
      test against exactly the same configuration you will get exactly the
      same result within the bounds of the random selection of transactions
      which will typically be within 1%. Any differences between results are
      directly as a result of changes you have made to the configuration (or
      management overhead of your system such as database checkpoints or
      user/administrator error). Testing has proven that HammerDB tests re-run
      multiple times unattended (see the autopilot feature) on the same
      reliable configuration produce performance profiles that will overlay
      each other almost identically. The Figure below illustrates an example
      of this consistency and shows the actual results of 2 sequences of tests
      run unattended one after another against one of the supported databases
      with the autopilot feature from 1 to 144 virtual users to test
      modifications to a WAL (Write Ahead Log File). In other words HammerDB
      will give you the same results each time, if your results vary you need
      to focus entirely on your database, OS and hardware
      configuration.</para>

      <para/>

      <figure>
        <title>WAL Test</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch3-1.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Consequently when you begin to make changes you are able to
      quantify the impact of these changes. Examples include modifying
      database parameters, changing database software or operating system or
      upgrading or modifying hardware. Taking a baseline of a database system
      with a HammerDB workload is an ideal method to ensure that optimal
      database configurations are engineered put into production.</para>
    </section>

    <section>
      <title>Comparing HammerDB results</title>

      <para>HammerDB implements a workload called TPROC-C based on the TPC-C
      specification called TPROC-C however does NOT implement a full
      specification TPC-C benchmark and the transaction results from HammerDB
      cannot be compared with the official published TPC-C benchmarks in any
      manner. Official Audited TPC-C benchmarks are extremely costly, time
      consuming and complex to establish and maintain. The HammerDB
      implementation based on the specification of the TPC-C benchmark is
      designed to capture the essence of TPC-C in a form that can be run at
      low cost on any system bringing professional, reliable and predictable
      load testing to all database environments. For this reason HammerDB
      results cannot and should NOT be compared or used with the term tpmC in
      any circumstance. HammerDB workloads produce 2 statistics to compare
      systems called TPM and NOPM respectively. NOPM value is based on a
      metric captured from within the test schema itself. As such NOPM (New
      Orders per minute) as a performance metric independent of any particular
      database implementation is the recommended primary metric to use.</para>
    </section>

    <section>
      <title>Understanding the TPROC-C workload derived from TPC-C</title>

      <para>The TPC-C specification on which TPROC-C is based implements a
      computer system to fulfil orders from customers to supply products from
      a company. The company sells 100,000 items and keeps its stock in
      warehouses. Each warehouse has 10 sales districts and each district
      serves 3000 customers. The customers call the company whose operators
      take the order, each order containing a number of items. Orders are
      usually satisfied from the local warehouse however a small number of
      items are not in stock at a particular point in time and are supplied by
      an alternative warehouse. It is important to note that the size of the
      company is not fixed and can add Warehouses and sales districts as the
      company grows. For this reason your test schema can be as small or large
      as you wish with a larger schema requiring a more powerful computer
      system to process the increased level of transactions. The TPROC-C
      schema is shown below, in particular note how the number of rows in all
      of the tables apart from the ITEM table which is fixed is dependent upon
      the number of warehouses you choose to create your schema.</para>

      <para><figure>
          <title>TPROC-C Schema</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch3-2.png"/>
            </imageobject>
          </mediaobject>
        </figure>For additional clarity please note that the term Warehouse in
      the context of TPROC-C bears no relation to a Data Warehousing workload,
      as you have seen TPROC-C defines a transactional based system and not a
      decision support (DSS) one. In addition to the computer system being
      used to place orders it also enables payment and delivery of orders and
      the ability to query the stock levels of warehouses. Consequently the
      workload is defined by a mix of 5 transactions selected at random
      according to the balance of the percentage value shown as
      follows:</para>

      <itemizedlist>
        <listitem>
          <para>New-order: receive a new order from a customer: 45%</para>
        </listitem>

        <listitem>
          <para>Payment: update the customers balance to record a payment:
          43%</para>
        </listitem>

        <listitem>
          <para>Delivery: deliver orders asynchronously: 4%</para>
        </listitem>

        <listitem>
          <para>Order-status: retrieve the status of customers most recent
          order: 4%</para>
        </listitem>

        <listitem>
          <para>Stock-level: return the status of the warehouses inventory:
          4%</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>TPROC-C key similarities and differences from TPC-C</title>

      <para>HammerDB can be seen as a subset of the the full TPC-C
      specification, intentionally modified to make the workload simpler and
      easier to run. The key similarities are the schema definition and data
      and the 5 transactions implemented as stored procedures. The key
      difference is that by default HammerDB will run without keying and
      thinking time enabled (Note enabling event driven scaling will enable
      keying and thinking time to be run with a large number of user
      sessions). This means that HammerDB TPROC-C will run a CPU and memory
      intensive version of the TPC-C workload. In turn this also means that
      the number of virtual users and the required data set will be much
      smaller than a full TPC-C implementation to reach maximum levels of
      performance. HammerDB also does not implement terminals as the full
      specification does. Nevertheless with the HammerDB TPROC-C
      implementation a large number of client systems and third-party
      middleware is not required nor a very large data set to reach maximum
      levels of performance whilst still providing a robust test of relational
      databases capabilities.</para>
    </section>

    <section>
      <title>How many warehouses to create for the TPROC-C test</title>

      <para>This is a very typical FAQ and although detailed in the
      documentation some extra details may help in sizing and configuration.
      For a basic starting point create a schema with 250-500 warehouses per
      server CPU socket for more details size as follows.</para>

      <para>The official TPC-C test has a fixed number of users per warehouse
      and uses keying and thinking time so that the workload generated by each
      user is not intensive. However most people use HammerDB with keying and
      thinking time disabled and therefore each virtual user can approximately
      drive the CPU resources of one CPU core on the database server.
      Therefore the relationship between virtual users, warehouses and cores
      can be seen, you need considerably fewer virtual users and warehouses to
      drive a system to maximum throughput than the official test.</para>

      <para>Additionally it is important to understand the workload. By
      default each virtual user has the concept of a home warehouses where
      approximately 75% of its workload will take place. With HammerDB this
      home warehouse is chosen at random at the start of the test and remains
      fixed. For example it can then be understood that if you configure a
      schema with 1000 warehouses and run a test with 10 virtual users by
      default most of the workload will be concentrated upon 10 warehouses.
      (It is important to note the “by default” clause here as there are
      exceptions to change this behaviour if desired). Also with the home
      warehouse chosen at random it should be clear that number of warehouses
      should be configured so that when the maximum number of virtual users
      that you will run are configured there is a good chance that the
      selection of a home warehouse at random will be evenly distributed
      across the available warehouses with one or possibly 2 virtual users
      selecting the same home warehouse at random but not more.</para>

      <para>As an example configuring a 10 warehouse schema and running 100
      virtual users against this schema would be an error in configuration as
      it would be expected for 10 virtual users or more to select the same
      warehouse. Doing this would mean that the workload would spend
      considerably more time in lock contention and would not produce valid
      results. Typically an option of 4 to 5 warehouses per virtual user would
      be a minimum value to ensure an even distribution of virtual users to
      warehouse. Therefore for the 100 virtual users 400 to 500 warehouses
      should be a minimum to be configured. As noted configuring more should
      not have a major impact on results as depending on the number of virtual
      users used in the test most the warehouses will be idle (and ideally
      most of the warehouses you are using will be cached in memory in your
      buffer cache so the I/O to the data area is minimal).</para>

      <para>As one virtual user can drive most of the capacity of one CPU core
      the actual value for the number of warehouses you choose will depend
      upon the number of cores per socket. Note that if using CPUs with
      Hyper-Threading allow for additional CPU capacity, so size as if there
      were 35% more physical cores. Also depending on your chosen database
      some database software will not scale to fully utilise all cores, see
      the best practice guides for guidance on your chosen database. If CPU
      utilisation is limited then you will need fewer warehouses configured
      and virtual users for the test.</para>

      <para>It should also be clear that there is no completely accurate
      one-size-fits-all type guidance for warehouse sizing as different
      databases will scale differently and some may need more warehouses and
      virtual users than others to reach peak performance. A common error is
      to size many thousands of warehouses and virtual users with the aim of
      reaching high performance but instead resulting in high levels of
      contention and low performance. Even for highly scalable databases on
      large systems upper limits for tests without keying and thinking time
      are in the region of 2000 warehouses for up to 500 virtual users for
      maximum performance.</para>

      <para>The exceptions to these guidelines are given in the section
      Advanced Driver Script Options in the following Chapter namely the Use
      All Warehouses and Event Driven Scaling options. For advanced users
      these options enable increasing the amount of data area I/O and running
      more Virtual Users less intensively with keying and thinking time
      respectively.</para>
    </section>

    <section>
      <title>Publishing database performance results</title>

      <para>The goal of HammerDB is to make database performance data open
      source and enable database professionals a fast and low-cost to compare
      and contrast database systems. HamerDB maintains a list of <link
      xlink:href="https://www.hammerdb.com/benchmarks.html">3rd party
      publications on the HammerDB website</link>.</para>
    </section>
  </chapter>

  <chapter>
    <title>How to Run a TPROC-C Workload</title>

    <para>This Chapter provides a general overview on the HammerDB TPROC-C
    workload and gives you an introduction to conducting OLTP (Online
    Transaction Processing) workloads on all of the supported databases. This
    will equip you with the essentials for assessing the ability of any system
    for processing transactional workloads.</para>

    <section>
      <title>Test Network Configuration</title>

      <para>You require the database server to be tested known as the system
      under test (SUT) installed and configured with the target database
      server. You also require a load generation server to run HammerDB
      installed with the HammerDB software and a database client. Typically
      the load generation server is run on a separate system from the SUT with
      the load generated across the network. It is possible to run HammerDB on
      the same system as the SUT however this will be expected to produce
      different results from a network based load. For example where the
      database software is highly scalable then running HammerDB on the same
      system will result in lower performance as the database software will
      not be able to take advantage of all of the available CPU. Conversely
      where the database software is less scalable and there is more network
      overhead it can take more virtual users to reach the same levels of
      performance using an additional load generation server compared to
      running HammerDB on the SUT. Both the SUT and the load generation server
      may be virtualized or container databases although similarly results may
      differ from a native hardware based installation. In all cases when
      comparing performance results you should ensure that you are comparing
      across the same configurations test network configurations.</para>

      <section>
        <title>SUT Database Server Configuration</title>

        <para>The database server architecture to be tested must meet the
        minimum requirements for your chosen database software, however to
        reach maximum performance it is likely that the specifications will
        considerably exceed these standard. To run a HammerDB transactional
        load test there are minimum requirements in memory and I/O (disk
        performance) to prevent these components being a bottleneck on
        performance. For a configuration requiring the minimal level of memory
        and I/O to maximize CPU utilization keying and thinking time should be
        set to FALSE (keying and thinking time is detailed later in this
        guide). To achieve this you should aim to create a schema with
        approximately 250-500 warehouses per CPU socket. By default each
        Virtual User will select a home warehouse at random and most of its
        work takes place on that home warehouse and therefore the schema
        sizing of 250-500 warehouses per socket should ensure that when the
        Virtual Users login the choice of a home warehouse at random is evenly
        distributed without a large number of Virtual Users selecting the same
        home warehouse. As long as it is not too small resulting in contention
        the schema size should not significantly impact results when testing
        in a default configuration. You should have sufficient memory to cache
        as much of your test schema in memory as possible. If keying and
        thinking time is set to TRUE you will need a significantly larger
        schema and number of virtual users to create a meaningful system load
        and should consider the advanced event-driven scaling option.
        Reductions in memory will place more emphasis on the I/O performance
        of the database containing the schema. If the allocated memory is
        sufficient most of the data will be cached during an OLTP test and I/O
        to the data area will be minimal. As a consequence the key I/O
        dependency will be to the redo/WAL/transaction logs for both bandwidth
        and sequential write latency. Modern PCIe SSDs when correctly
        configured have been shown to provide the capabilities to sustain high
        performance transaction logging.</para>
      </section>

      <section>
        <title>Load Generation Server Configuration</title>

        <para>The most important component of the load generation server is
        the server processor. The overall load generation server capacity
        required depends on the system capabilities of the SUT. It is
        recommend to use an up to date multi-core processor. HammerDB is a
        multi-threaded application and implicitly benefits from a multi-core
        server CPU. To determine whether CPU capacity is sufficient for
        testing you can monitor the CPU utilisation with HammerDB Metrics. CPU
        utilisation reaching 100% is an indication that the CPU on the load
        generation server is limiting performance. Load generation memory
        requirements are dependent on the operating system configuration and
        the number of virtual users created with each virtual user requiring
        its own database client. Typically server sizing guidelines should be
        within the limits expected to support a real user count. Multiple load
        generation servers connected in a “master-slave” configuration are
        enabled within HammerDB to exceed the capacity of a single load
        generation client. The load generation server does not need to be
        running the same version of SQL Server as the SUT.</para>
      </section>

      <section>
        <title>CPU Single-Threaded Performance Calibration</title>

        <para>By far one of the most common configuration errors with database
        performance testing is to have configured the CPUs to run in powersave
        mode. On some Linux operating systems this is the default
        configuration and therefore it is recommended to verify the CPU
        single-threaded performance and operating mode before running database
        workloads. One way to do this is to use the <link
        xlink:href="http://www.juliandyke.com/CPUPerformance/CPUPerformance.php">Julian
        Dyke CPU performance test</link> (referenced by permission of Julian
        Dyke and there are versions shown below to run directly in HammerDB
        and for Oracle PL/SQL and SQL Server T-SQL). Note that the timings are
        not meant to equivalent and it is expected that the HammerDB based
        test is approximately twice as fast as PL/SQL or T-SQL. The reason for
        the faster performance is that the TCL version is compiled into
        bytecode and you can observe this by running a Linux utility such as
        perf to see that the top function is TEBCresume. (Tcl Execute ByteCode
        Resume). During normal HammerDB operations TEBCResume should also be
        the top function for the same reason.</para>

        <programlisting>Samples: 67K of event 'cycles:ppp', Event count (approx.): 33450114923
Overhead  Shared Object                  Symbol
<emphasis role="bold">  33.56%  libtcl8.6.so                   [.] TEBCresume</emphasis>
   7.68%  libtcl8.6.so                   [.] Tcl_GetDoubleFromObj
   6.28%  libtcl8.6.so                   [.] EvalObjvCore
   6.14%  libtcl8.6.so                   [.] TclNRRunCallbacks
</programlisting>

        <para>The goal of running these tests is to ensure that your CPU runs
        the test at the CPU advertised boost frequency. To do this you can use
        the turbostat utility on Linux and the Task Manager utility on
        Windows. By default the tests run for 10000000 iterations however this
        can be extended if desired to allow sufficient time to monitor the
        boost frequency is operational. For the HammerDB version save the
        script shown and run it using the CLI. A commented out command is
        shown that can be uncommented to observe the bytecode for a particular
        procedure.</para>

        <programlisting>proc runcalc {} {
set n 0
for {set f 1} {$f &lt;= 10000000} {incr f} {
set n [ expr {[::tcl::mathfunc::fmod $n 999999] + sqrt($f)} ] 
}
return $n
}
#puts "bytecode:[::tcl::unsupported::disassemble proc runcalc]"
set start [clock milliseconds]
set output [ runcalc ]
set end [ clock milliseconds]
set duration [expr {($end - $start)}]
puts "Res = [ format %.02f $output ]"
puts "Time elapsed : [ format %.03f [ expr $duration/1000.0 ] ]"</programlisting>

        <para>The expected result is 873729.72 as shown in the example output.
        Depending on the CPU used the default completion time should be up to
        3 seconds, if longer then investigating the CPU configuration is
        recommended.</para>

        <programlisting>hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.990

hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.966

hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.980

hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.976

hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.972

hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.988

hammerdb&gt;source CPUTEST.tcl
Res = 873729.72
Time elapsed : 2.976

</programlisting>

        <para>The following listing shows the original Julian Dyke PL/SQL CPU
        test that can be run in an Oracle instance. Example timings are given
        at the website link above.</para>

        <programlisting>SET SERVEROUTPUT ON
SET TIMING ON
 
DECLARE
  n NUMBER := 0;
BEGIN
  FOR f IN 1..10000000
  LOOP
    n := MOD (n,999999) + SQRT (f);
  END LOOP;
  DBMS_OUTPUT.PUT_LINE ('Res = '||TO_CHAR (n,'999999.99'));
END;
/</programlisting>

        <para>The following listing shows the same routine in T-SQL for SQL
        Server.</para>

        <programlisting>USE [tpcc]
GO
SET ANSI_NULLS ON
GO
CREATE PROCEDURE [dbo].[CPUSIMPLE] 
AS
   BEGIN
      DECLARE
         @n numeric(16,6) = 0,
         @a DATETIME,
         @b DATETIME
      DECLARE
         @f int
      SET @f = 1
      SET @a = CURRENT_TIMESTAMP
      WHILE @f &lt;= 10000000 
         BEGIN
      SET @n = @n % 999999 + sqrt(@f)
            SET @f = @f + 1
         END
         SET @b = CURRENT_TIMESTAMP
         PRINT ‘Timing = ‘ + ISNULL(CAST(DATEDIFF(MS, @a, @b)AS VARCHAR),”)
         PRINT ‘Res = ‘+ ISNULL(CAST(@n AS VARCHAR),”)
   END</programlisting>
      </section>

      <section>
        <title>Administrator PC Configuration</title>

        <para>When using the graphical version of HammerDB the administrator
        PC must have the minimal requirement to display the graphical output
        from the load generation server. The PC should also have the ability
        to connect to the SUT to monitor performance by the installation of an
        appropriate database client. For Linux clients where remote desktop
        displays are used it is recommended to use VNC instead of X Windows
        for better graphics performance in particular when using v4.0 SVG
        based scalable graphics. running X windows over long distances is
        known to impact display refresh rates and is not a HammerDB
        issue.</para>
      </section>
    </section>

    <section>
      <title>Installation and Configuration</title>

      <para>This section details database specific installation and
      configuration requirements.</para>

      <section>
        <title>Oracle</title>

        <para>You should have the Oracle database software installed and a
        test database created and running. During the installation make a note
        of your system user password, you will need it for the test schema
        creation. (Note that the system user is used and not sys). You may at
        your discretion use an existing database however please note that
        HammerDB load testing can drive your system utilization to maximum
        levels and therefore testing an active production system is not
        recommended. After your database server is installed you should create
        a tablespace into which the test data will be installed allowing disk
        space according to the guide previously in this chapter. For example
        the following shows creating the tablespace in the ASM disk group
        DATA:</para>

        <programlisting>SQL&gt; create bigfile tablespace tpcctab datafile '+DATA' size 100g; </programlisting>

        <para>If you are running HammerDB against Oracle on Windows add the
        following entry to your SQLNET.ORA file for the reasons described in
        the HammerDB release notes.</para>

        <programlisting>SQLNET.AUTHENTICATION_SERVICES = (NTS)
DIAG_ADR_ENABLED=OFF DIAG_SIGHANDLER_ENABLED=FALSE
DIAG_DDE_ENABLED=FALSE</programlisting>

        <para>You must be able to connect from your load generation server to
        your SUT database server across the network using Oracle TNS. This
        will involve successful configuration of your listener on the SUT
        database server and the tnsnames.ora file on the load generation
        server. You can troubleshoot connectivity issues using the ping,
        tnsping and sqlplus commands on the load generation client and the
        lsnrctl command on the SUT database server. For example a successful
        tnsping test looks as follows:</para>

        <programlisting>[oracle@MERLIN ~]$ tnsping PDB1

TNS Ping Utility for Linux: Version 12.1.0.1.0 - Production on 21-MAY-2014 05:40:49

Copyright (c) 1997, 2013, Oracle.  All rights reserved.

Used parameter files:
/u01/app/oracle/product/12.1.0/dbhome_1/network/admin/sqlnet.ora

Used TNSNAMES adapter to resolve the alias
Attempting to contact (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = merlin)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = pdb1)))
OK (30 msec)

</programlisting>

        <para>Note that where the instant client is being used on the load
        generation server you should configure the TNS_ADMIN environment
        variable to the location where the tnsnames.ora and sqlnet.ora files
        are installed. When you have installed the load generation server and
        SUT database and have verified that you can communicate between them
        using Oracle TNS you can proceed to building a test schema.</para>
      </section>

      <section>
        <title>Microsoft SQL Server</title>

        <para>You will have configured Microsoft SQL Server during
        installation to authenticate either with Windows Authentication or
        with SQL Server and Windows Authentication. HammerDB will permit
        either method to be used however you must have the corresponding
        configuration on your SQL Server. Additionally your chosen method of
        authentication is required to be compatible with your chosen ODBC
        driver. To discover the available drivers use the ODBC Data Source
        Administrator tool on Windows and the command database drivers on
        Linux. The driver name should be entered into HammerDB exactly as
        shown in the Data Source Administrator. The default value is “ODBC
        Driver 17 for SQL Server” for both Windows and Linux.</para>

        <figure>
          <title>ODBC Drivers</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-1.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Db2</title>

        <para>To connect to Db2 requires the IBM CLI interface. Note that CLI
        in this context means "call level interface" and should not be
        confused the with the HammerDB command-line interface. Db2 CLI is the
        'C' language interface that HammerDB uses. ODBC is not used for
        HammerDB connectivity to Db2 however both ODBC and CLI drivers are
        packaged together and therefore for Db2 connectivity it is necessary
        to install the Db2 client software IBM Data Server Driver for ODBC and
        CLI. This is also typically installed with the Db2 database software.
        Configure your db2dsdriver.cfg file with the hostname, port and
        database that you have created on the server.</para>

        <programlisting>db2inst1:~/odbc_cli/clidriver/cfg&gt; more db2dsdriver.cfg
&lt;?xml version="1.0" encoding="UTF-8" standalone="no" ?&gt;
&lt;configuration&gt;
  &lt;dsncollection&gt;
    &lt;dsn alias="TPCC" host="db2v1064bit" name="TPCC" port="50001"/&gt;
  &lt;/dsncollection&gt;

  &lt;databases&gt;
    &lt;database host="db2v1064bit" name="TPCC" port="50001"/&gt;
  &lt;/databases&gt;
&lt;/configuration&gt;
</programlisting>

        <para>Options can be set in the db2cli.ini file.</para>

        <programlisting>[db2inst1@~/sqllib/cfg]$ more db2cli.ini 
[TPCC]
UID=db2inst1
PWD=ibmdb2
SysSchema=SYSIBM
SchemaList=”’SYSIBM’,’TPCC’”
DeferredPrepare=1
ConnectTimeout=10
ReceiveTimeout=120
LockTimeout=-1
AppendForFetchOnly=0
AutoCommit=1
ConnectType=1
CursorHold=OFF
TxnIsolation=1
StmtConcentrator=OFF
</programlisting>

        <para>You should have the Db2 database software installed and ready to
        accept connections as shown below.</para>

        <programlisting>db2inst1~]$ db2stop
04/12/2015 10:12:27     0   0   SQL1064N  DB2STOP processing was successful.
SQL1064N  DB2STOP processing was successful.
[db2inst1~]$ db2start
12/04/2015 10:12:31     0   0   SQL1063N  DB2START processing was successful.
SQL1063N  DB2START processing was successful.
[db2inst1~]$ db2
(c) Copyright IBM Corporation 1993,2007
Command Line Processor for DB2 Client 10.5.5

You can issue database manager commands and SQL statements from the command 
prompt. For example:
    db2 =&gt; connect to sample
    db2 =&gt; bind sample.bnd

For general help, type: ?.
For command help, type: ? command, where command can be
the first few keywords of a database manager command. For example:
 ? CATALOG DATABASE for help on the CATALOG DATABASE command
 ? CATALOG          for help on all of the CATALOG commands.

To exit db2 interactive mode, type QUIT at the command prompt. Outside 
interactive mode, all commands must be prefixed with 'db2'.
To list the current command option settings, type LIST COMMAND OPTIONS.

For more detailed help, refer to the Online Reference Manual.

db2 =&gt;
</programlisting>

        <para>With Db2 installed and running manually create and configure a
        Db2 Database according to your requirements. Pay particular attention
        to setting a LOGFILSIZ appropriate to your environment, otherwise you
        are likely to receive a transaction log full error message during the
        schema build. Additionally HammerDB is bufferpool and tablespace aware
        and therefore you may wish to create additional bufferpools specific
        to the tables that you are going create. The example below shows a
        configuration where a separate bufferpool has been created for each
        table solely to illustrate the usage of HammerDB parameters. You
        should also use the db2set command to set parameters appropriate to
        your system, for example setting DB2_LARGE_PAGE_MEM=DB for a large
        page configuration. Note that the commands below are examples only and
        should not (and are not) recommendations for optimal
        performance.</para>

        <programlisting>[db2inst1@ ~]$ db2 create database tpcc pagesize 8 k
DB20000I  The CREATE DATABASE command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using PCKCACHESZ 1631072
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using LOGFILSIZ 1048572
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using LOGPRIMARY 25 
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using LOGSECOND 5
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using LOGBUFSZ 17264
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using MINCOMMIT 1
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using NUM_IOSERVERS AUTOMATIC
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using DFT_PREFETCH_SZ AUTOMATIC
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using LOCKTIMEOUT 15
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ db2 update db cfg for tpcc using SOFTMAX 2500
DB20000I  The UPDATE DATABASE CONFIGURATION command completed successfully.
[db2inst1@ ~]$ 
[db2inst1@ ~]$ db2 connect to tpcc

   Database Connection Information

 Database server        = DB2/LINUXX8664 10.5.5
 SQL authorization ID   = DB2INST1
 Local database alias   = TPCC

[db2inst1@ ~]$ db2 create bufferpool C_BP immediate size 2500000 pagesize 8k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace C_TS pagesize 8k managed by automatic storage bufferpool C_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool D_BP immediate size 500000 pagesize 4k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace D_TS pagesize 4k managed by automatic storage bufferpool D_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool W_BP immediate size 500000 pagesize 4k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace W_TS pagesize 4k managed by automatic storage bufferpool W_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool I_BP immediate size 500000 pagesize 4k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace I_TS pagesize 4k managed by automatic storage bufferpool I_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool H_BP immediate size 2000000 pagesize 8k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace H_TS pagesize 8k managed by automatic storage bufferpool H_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool S_BP immediate size 2000000 pagesize 8k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace S_TS pagesize 8k managed by automatic storage bufferpool S_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool NO_BP immediate size 3000000 pagesize 8k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace NO_TS pagesize 8k managed by automatic storage bufferpool NO_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool OR_BP immediate size 3000000 pagesize 8k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace OR_TS pagesize 8k managed by automatic storage bufferpool OR_BP
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create bufferpool OL_BP immediate size 5000000 pagesize 8k
DB20000I  The SQL command completed successfully.
[db2inst1@ ~]$ db2 create large tablespace OL_TS pagesize 8k managed by automatic storage bufferpool OL_BP
DB20000I  The SQL command completed successfully.
</programlisting>
      </section>

      <section>
        <title>MySQL</title>

        <para>You should have the MySQL database software installed and
        running. Make sure you set a password for either the root user or a
        user with the correct privileges to create the TPROC-C database, for
        example the following on MySQL 8.0.</para>

        <programlisting>mysql&gt; alter user 'root'@'localhost' identified by 'mysql';
Query OK, 0 rows affected (0.00 sec)</programlisting>

        <para>and the following on MySQL 5.6</para>

        <para><programlisting>-bash-4.1$ ./mysqladmin -u root password mysql</programlisting>By
        default a MySQL installation will allow connection to the local server
        only, you must grant permission to connect to the MySQL database from
        your load generation server, the following example grants all
        permissions to the root user on the system called merlin.home.</para>

        <programlisting>mysql&gt; grant all on *.* to root@'hummingbird.home' identified by 'mysql';
Query OK, 0 rows affected (0.00 sec)
mysql&gt; flush privileges;
Query OK, 0 rows affected (0.00 sec)
</programlisting>

        <para>Alternatively after the test database is created you can
        restrict the privileges to that databases only.</para>

        <programlisting>mysql&gt; grant all on tpcc.* to root@'hummingbird.home' identified by 'mysql';</programlisting>

        <para>When choosing a MySQL Server to test note that HammerDB load
        testing can drive your system utilization to maximum levels and
        therefore testing an active production system is not recommended. When
        you have installed the load generation server and SUT database and
        have verified that you can communicate between them by logging in
        remotely you can proceed to building a test schema.</para>

        <programlisting>mysql@hummingbird:~&gt; mysql -u root -p -h merlin.home
Enter password: 
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 19
Server version: 5.6.17 MySQL Community Server (GPL)
Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql&gt; 
</programlisting>
      </section>

      <section>
        <title>PostgreSQL</title>

        <para>You should have the PostgreSQL database software installed and a
        test database created and running. It is important to note that
        EnterpriseDB produce an enhanced version of the PostgreSQL database
        termed Postgres Plus Advanced Server. This version of PostgreSQL in
        particular includes compatibility features with the Oracle database
        such as PL/SQL support. For this reason the Hammer OLTP workload for
        PostgreSQL can operate in 2 modes. Firstly Oracle compatible mode uses
        PL/SQL and additional Postgres Plus Advanced Server features (such as
        DRITA snapshots) that will only operate against Enterprise DB Postgres
        Plus Advanced Server. Secondly by not selecting Oracle compatibility
        HammerDB can continue to operate against Postgres Plus Advanced Server
        but additionally against a regular PostgreSQL build using native
        PostgreSQL features. You must ensure before proceeding with OLTP that
        you are aware of the version of PostgreSQL you have installed and the
        features available, if you wish to test Oracle compatibility then you
        must use Postgres Plus Advanced Server from EnterpriseDB and install
        in Oracle compatible mode.</para>

        <para>During the installation make a note of your postgres superuser
        password, you will need it for the test schema creation. You must be
        able to connect from your load generation server to your SUT database
        server across the network. Firstly check your postgresql.conf file for
        the listen_addresses parameter. If this is set to localhost then only
        connections from the local server will be permitted. Use
        listen_addresses = ‘*’ to permit connections from all servers.
        Successful network connections will also involve successful
        configuration of your pg_hba.conf on the SUT database server. For
        example the following extract from a pg_hba.conf file from a
        PostgreSQL 9.3 installation shows trusted local connections on the SUT
        permitting connection without a password and remote connections from
        the Load Generation server with IP address 192.168.1.67 if the correct
        password is supplied. Note that the syntax of pg_hba.conf has changed
        for different versions of PostgreSQL and you should therefore consult
        the PostgreSQL documentation and sections further in this document to
        troubleshoot connectivity issues.</para>

        <programlisting># TYPE  DATABASE        USER            ADDRESS                 METHOD
# "local" is for Unix domain socket connections only
local      all       all  trust 
# IPv4 local connections:
host  all  all  127.0.0.1/32 md5
host  all  all  192.168.1.67/32 md5
</programlisting>
      </section>
    </section>

    <section>
      <title>Configuring Schema Build Options</title>

      <para>To create the OLTP test schema based on the TPROC-C specification
      you will need to select which benchmark and database you wish to use by
      choosing select benchmark from under the Options menu or double-clicking
      on the chosen database under the benchmark tree-view. (For the currently
      selected database double left-click shows the benchmark options and
      double right-click expands the tree view). The initial settings are
      determined by the values in your XML configuration files. The following
      example shows the selection of SQL Server however the process is the
      same for all databases.</para>

      <figure>
        <title>Benchmark Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>To create the TPROC-C schema select the TPROC-C schema options
      menu tab from the benchmark tree-view or the options menu. This menu
      will change dynamically according to your chosen database.</para>

      <figure>
        <title>Schema Build Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The “Build Options” section details the general login information
      and where the schema will be built and these are the only options of
      importance at this stage. Note that in any circumstance you do not have
      to rebuild the schema every time you change the “Driver Options”, once
      the schema has been built only the “Driver Options” may need to be
      modified. For the “Build Options” fill in the values according to the
      database where the schema will be built as follows.</para>

      <section>
        <title>Oracle Schema Build Options</title>

        <para><figure>
            <title>Oracle Build Options</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="docs/images/ch4-4.PNG"/>
              </imageobject>
            </mediaobject>
          </figure></para>

        <table>
          <title>Oracle Options</title>

          <tgroup cols="2">
            <thead>
              <row>
                <entry align="center">Option</entry>

                <entry align="center">Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Oracle Service Name</entry>

                <entry>The Oracle Service Name is the service name that your
                load generation server will use to connect to the database
                running on the SUT database server.</entry>
              </row>

              <row>
                <entry>System User</entry>

                <entry>The “system” user or a user with system level
                privileges</entry>
              </row>

              <row>
                <entry>System User Password</entry>

                <entry>The system user password is the password for the
                “system” user you entered during database creation. The system
                user already exists in all Oracle databases and has the
                necessary permissions to create the TPROC-C user.</entry>
              </row>

              <row>
                <entry>TPROC-C User</entry>

                <entry>The TPROC-C user is the name of a user to be created
                that will own the TPROC-C schema. This user can have any name
                you choose but must not already exist and adhere to the
                standard rules for naming Oracle users. You may if you wish
                run the schema creation multiple times and have multiple
                TPROC-C schemas created with ownership under a different user
                you create each time.</entry>
              </row>

              <row>
                <entry>TPROC-C User Password</entry>

                <entry>The TPROC-C user password is the password to be used
                for the TPROC-C user you create and must adhere to the
                standard rules for Oracle user password. You will need to
                remember the TPROC-C user name and password for running the
                TPROC-C driver script after the schema is built.</entry>
              </row>

              <row>
                <entry>TPROC-C Default Tablespace</entry>

                <entry>The TPROC-C default tablespace is the tablespace that
                will be the default for the TPROC-C user and therefore the
                tablespace to be used for the schema creation. The tablespace
                must have sufficient free space for the schema to be
                created.</entry>
              </row>

              <row>
                <entry>TPROC-C Order Line Tablespace</entry>

                <entry>If the “Number of Warehouses” as described below is set
                to 200 or more then the “Partition Order Line Table” option
                becomes active. If this is selected then the option to select
                a different tablespace for the Order Line table only becomes
                active. For high performance schemas this gives the option of
                using both a separate tablespace and memory cache for the
                order line table with a different block size. Where a
                different cache and blocksize is used 16k is
                recommended.</entry>
              </row>

              <row>
                <entry>TPROC-C Temporary Tablespace</entry>

                <entry>The TPROC-C temporary tablespace is the temporary
                tablespace that already exists in the database to be used by
                the TPROC-C User.</entry>
              </row>

              <row>
                <entry>TimesTen Database Compatible</entry>

                <entry>When selected this option means that the Oracle Service
                Name should be a TimesTen Data Source Name and will grey out
                non-compatible options.</entry>
              </row>

              <row>
                <entry>Use Hash Clusters</entry>

                <entry>When Partitioning is selected this option enables the
                building of static tables as single table hash clusters and
                also disables table locks. These options can provide
                additional levels of scalability on high performance systems
                where contention is observed however will not provide
                significant performance gains on entry level systems. When
                Hash Clusters are enabled table locks are also disabled with
                the command "ALTER TABLE XXX DISABLE TABLE LOCK" and these
                locks will need to be re-enabled to drop the schema when
                required.</entry>
              </row>

              <row>
                <entry>Partition Tables</entry>

                <entry>When more than 200 warehouses are selected this option
                uses Oracle partitioning to divide the Order Line table into
                partitions of 100 warehouses each. Using partitioning enables
                scalability for high performance schemas and should be
                considered with using a separate tablespace for the Order Line
                table. Selecting this option also partitions the Orders and
                History tables.</entry>
              </row>

              <row>
                <entry>Number of Warehouses</entry>

                <entry>The Number of Warehouses is selected by a listbox. You
                should set this value to number of warehouses you have chosen
                for your test.</entry>
              </row>

              <row>
                <entry>Virtual Users to Build Schema</entry>

                <entry>The Virtual Users to Build Schema is the number of
                Virtual Users to be created on the Load Generation Server that
                will complete your multi-threaded schema build. You should set
                this value to either the number of warehouses you are going to
                create (You cannot set the number of virtual users lower than
                the number of warehouses value) or the number of
                cores/Hyper-Threads on your Load Generation Server. If you
                have a significantly larger core/Hyper-Thread count on your
                Database Server then also installing HammerDB locally on this
                server as well to run the schema build can take advantage of
                the higher core count to run the build more quickly.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </section>

      <section>
        <title>Microsoft SQL Server Schema Build Options</title>

        <para>The In-Memory OLTP implementation of HammerDB is intended to be
        as close as possible to the original on-disk HammerDB SQL Server
        Schema to enable comparisons between the two. The key areas for memory
        optimization are in-Memory optimized tables, the isolation level and
        the implementation of the stored procedures. Familiarity with the
        architecture of In-memory OLTP can benefit the understanding of the
        performance characteristics.</para>

        <section>
          <title>In-Memory Optimized Tables</title>

          <para>The key difference with the In-memory schema from the on-disk
          database is the organization of the tables. In-memory tables are
          implemented with hash indexes with no additional indexes created
          during the schema creation. Although the differences between hash
          and standard indexes are out of scope for this guide it is
          recommended to become familiar with the architecture as a key
          difference is the requirement to create all of the tables memory
          requirements ‘up-front’ with too little or too much memory impacting
          performance and therefore monitoring of the memory configuration
          usage is essential for workloads operating on In-memory databases.
          For a full implementation of in-memory tables a primary key is
          mandatory, however by definition the HISTORY table does not have a
          primary key. Therefore to implement all tables as in-memory an
          identity column has been added to the HISTORY table. It is important
          to note that despite the nomenclature of in-memory and on-disk
          databases in fact most of the workload of the on-disk database
          actually operates in-memory and high performance implementations can
          limit disk activity almost entirely to transaction logging in
          similarity to an in-memory database with persistence. Consequently
          orders of magnitude performance improvements should not be expected
          by moving to in-memory compared to a well optimised on-disk
          database.</para>

          <para>During schema creation HammerDB sets the option
          MEMORY_OPTIMIZED_ELEVATE_TO_SNAPSHOT for the memory optimized
          database. As a result the use of the snapshot isolation mode is
          mandatory and this will be set without intervention of the user. For
          the on-disk schema the default isolation level of READ COMMITTED is
          used with the addition of hints within the stored procedures for
          specific statements.</para>

          <para>In-memory OLTP introduces the concept of Native Compilation
          for stored procedures that access in-memory tables and the tables
          configured for HammerDB have been implemented with this in mind.
          However at current releases supported features of native compilation
          are highly restricted to the extent that it would not be possible to
          implement stored procedures in a native compilation form that would
          then provide a fair comparison with the on-disk schema. For this
          reason the same T-SQL stored procedures have been implemented with
          minor changes in areas such as removed hints locks and transaction
          isolation levels. Native compilation remains a consideration for
          future releases when the necessary features are supported to provide
          a fair comparison.</para>

          <para>An in-memory database must reside in a memory optimized
          filegroup with one or more containers. This database must be
          pre-created before running the HammerDB schema creation. If the
          database does not exist HammerDB will report the following
          error:</para>

          <programlisting>Database imoltp must be pre-created in a MEMORY_OPTIMIZED_DATA filegroup and empty, to specify an In-Memory build</programlisting>

          <para>If the database exists but is not in a
          MEMORY_OPTIMIZED_FILEGROUP HammerDB will report the following
          error.</para>

          <programlisting>Database imoltp exists but is not in a MEMORY_OPTIMIZED_DATA filegroup</programlisting>

          <para>Therefore to create an in-memory database firstly create a
          standard database using SSMS or at the command line as
          follows:</para>

          <programlisting>use imoltp
GO
ALTER DATABASE imoltp ADD FILEGROUP imoltp_mod CONTAINS memory_optimized_data
GO  
ALTER DATABASE imoltp ADD FILE (NAME='imoltp_mod', FILENAME='C:\Program Files\Microsoft SQL Server\MSSQL13.SQLDEVELOP\MSSQL\data\imoltp_mod') TO FILEGROUP imoltp_mod
GO

</programlisting>

          <para>For SQL Server on Linux specify the filesystem as
          follows:</para>

          <programlisting>ALTER DATABASE imoltp ADD FILE (NAME='imoltp_mod', FILENAME='C:\var\opt\mssql\data\imoltp_mod') TO FILEGROUP imoltp_mod
GO
</programlisting>

          <para>Once the above statements have been run successfully the
          database is ready for an in-memory schema creation.</para>
        </section>

        <section>
          <title>Build Options</title>

          <para><figure>
              <title>SQL Server Build Options</title>

              <mediaobject>
                <imageobject>
                  <imagedata fileref="docs/images/ch4-5.PNG"/>
                </imageobject>
              </mediaobject>
            </figure></para>

          <para><table>
              <title>SQL Server Build Options</title>

              <tgroup cols="2">
                <thead>
                  <row>
                    <entry align="center">Option</entry>

                    <entry align="center">Description</entry>
                  </row>
                </thead>

                <tbody>
                  <row>
                    <entry>SQL Server</entry>

                    <entry>The Microsoft SQL Server is the host name or host
                    name and instance that your load generation server will
                    use to connect to the database running on the SUT database
                    server.</entry>
                  </row>

                  <row>
                    <entry>TCP</entry>

                    <entry>Use the TCP Protocol</entry>
                  </row>

                  <row>
                    <entry>SQL Server Port</entry>

                    <entry>When TCP is enabled, the SQL Server Port is the
                    network port that your load generation server will use to
                    connect to the database running on the SUT database
                    server. In most cases this will be the default port of
                    1433 and will not need to be changed.</entry>
                  </row>

                  <row>
                    <entry>Azure</entry>

                    <entry>Include the Database name in the connect string
                    typical of Azure connections. To successfully build the
                    schema this database must be created and empty.</entry>
                  </row>

                  <row>
                    <entry>SQL Server ODBC Driver</entry>

                    <entry>The Microsoft SQL ODBC Driver is the ODBC driver
                    you will use to connect to the SQL Server database. To
                    view which drivers are available on Windows view the ODBC
                    Data Source Administrator Tool.</entry>
                  </row>

                  <row>
                    <entry>Authentication</entry>

                    <entry>When installing SQL Server on Windows you will have
                    configured SQL Server for Windows or Windows and SQL
                    Server Authentication. On Linux you will be using SQL
                    Server Authentication. If you specify Windows
                    Authentication then SQL Server will use a trusted
                    connection to your SQL Server using your Windows
                    credentials without requiring a username and password. If
                    SQL Server Authentication is specified and SQL
                    Authentication is enabled on your SQL Server then you will
                    be able connect by specifying a username and password that
                    you have already configured on your SQL Server.</entry>
                  </row>

                  <row>
                    <entry>SQL Server User ID</entry>

                    <entry>The SQL Server User ID is the User ID of a user
                    that you have already created on your SQL Server.</entry>
                  </row>

                  <row>
                    <entry>SQL Server User Password</entry>

                    <entry>The SQL Server User Password is the Password
                    configured on the SQL Server for the User ID you have
                    specified. Note that when configuring the password on the
                    SQL Server there is a checkbox that when selected enforces
                    more complex rules for passwords or if unchecked enables a
                    simple password such as “admin”.</entry>
                  </row>

                  <row>
                    <entry>TRPOC-C SQL Server Database</entry>

                    <entry>The SQL Server Database is the name of the Database
                    to be created on the SQL Server to contain the schema. If
                    this database does not already exist then HammerDB will
                    create it, if the database does already exist and the
                    database is empty then HammerDB will use this existing
                    database. Therefore if you wish to create a particular
                    layout or schema then pre-creating the database and using
                    this database is an advanced method to use this
                    configuration.</entry>
                  </row>

                  <row>
                    <entry>In-Memory OLTP</entry>

                    <entry>Creates the database as In-Memory OLTP. The
                    database must be pre-created in a MEMORY_OPTIMIZED_DATA
                    filegroup and empty to specify an In-Memory build.</entry>
                  </row>

                  <row>
                    <entry>In-Memory Hash bucket Multiplier</entry>

                    <entry>The size of the In-memory database is specified at
                    creation time, however the OLTP/TPROC-C schema allows for
                    the insertion of additional rows. This value enables the
                    creation of larger tables for orders, new_order and
                    order_line to allow for these inserts. Note: Do not
                    specify too large a value or the table creation will fail
                    or performance will be significantly impacted. Typically
                    the default value of 1 is sufficient and will suffice for
                    manually run tests. For autopilot tests where are large
                    number of tests are to be run a value of 3 or 4 will
                    typically be sufficient, however of course the number of
                    inserts will depend on the performance of the system under
                    test and therefore testing is the best way to determine
                    the correct schema size for a particular
                    environment.</entry>
                  </row>

                  <row>
                    <entry>in-Memory Durability</entry>

                    <entry>Sets the durability option. If SCHEMA_ONLY is
                    chosen when SQL Server is stopped only the tables remain
                    without data loaded.</entry>
                  </row>

                  <row>
                    <entry>Number of Warehouses</entry>

                    <entry>The Number of Warehouses is selected by a listbox.
                    You should set this value to number of warehouses you have
                    chosen for your test.</entry>
                  </row>

                  <row>
                    <entry>Virtual Users to Build Schema</entry>

                    <entry>The Virtual Users to Build Schema is the number of
                    Virtual Users to be created on the Load Generation Server
                    that will complete your multi-threaded schema build. You
                    should set this value to either the number of warehouses
                    you are going to create (You cannot set the number of
                    virtual users lower than the number of warehouses value)
                    or the number of cores/Hyper-Threads on your Load
                    Generation Server. If you have a significantly larger
                    core/Hyper-Thread count on your Database Server then also
                    installing HammerDB locally on this server as well to run
                    the schema build can take advantage of the higher core
                    count to run the build more quickly.</entry>
                  </row>
                </tbody>
              </tgroup>
            </table></para>
        </section>
      </section>

      <section>
        <title>Db2 Schema Build Options</title>

        <para>Note that as previously described the host and port are defined
        externally in the db2dsdriver.cfg file.</para>

        <figure>
          <title>Db2 Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-6.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para><table>
            <title>Db2 Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>TPROC-C Db2 User</entry>

                  <entry>The name of the operating system user to connect to
                  the DB2 database for example db2inst1.</entry>
                </row>

                <row>
                  <entry>TPROC-C Db2 Password</entry>

                  <entry>The password for the operating system DB2 user by
                  default “ibmdb2”</entry>
                </row>

                <row>
                  <entry>TPROC-C Db2 Database</entry>

                  <entry>The name of the Db2 database that you have already
                  created, for example “tpcc”</entry>
                </row>

                <row>
                  <entry>TPROC-C Db2 Default Tablespace</entry>

                  <entry>The name of the existing tablespace where tables
                  should be located if a specific tablespace has not been
                  defined for that table in the tablespace list. The default
                  is “USERSPACE1”.</entry>
                </row>

                <row>
                  <entry>TPROC-C Db2 Tablespace List (Space Separated
                  Values)</entry>

                  <entry>When partitioning is selected, a space separated list
                  of Tablespace initials followed by a pre-existing tablespace
                  name in double-quotes into which to install a specific
                  table. If no tablespace is given for a specific table then
                  the default tablespace is used. The values are C: CUSTOMER
                  D: DISTRICT H: HISTORY I: ITEM W: WAREHOUSE S: STOCK NO:
                  NEW_ORDER OR: ORDERS OL: ORDER_LINE. And for example the
                  following list, would create all tables in the default. C ""
                  D "" H "" I "" W "" S "" NO "" OR "" OL "". Whereas the
                  following would create the ITEM table in the ITEM_TS
                  tablespace, the STOCK table in the STOCK_TS tablespace and
                  the other tables in the default. C "" D "" H "" I "ITEM_TS"
                  W "" S "STOCK_TS" NO "" OR "" OL "". You may configure all
                  or no distinct tablespaces according to your
                  requirements.</entry>
                </row>

                <row>
                  <entry>Number of Warehouses</entry>

                  <entry>The Number of Warehouses is selected by a listbox.
                  You should set this value to number of warehouses you have
                  chosen for your test.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to either the number of warehouses you
                  are going to create (You cannot set the number of virtual
                  users lower than the number of warehouses value) or the
                  number of cores/Hyper-Threads on your Load Generation
                  Server. If you have a significantly larger core/Hyper-Thread
                  count on your Database Server then also installing HammerDB
                  locally on this server as well to run the schema build can
                  take advantage of the higher core count to run the build
                  more quickly.</entry>
                </row>

                <row>
                  <entry>Partition Tables</entry>

                  <entry>This check option becomes active when more than 10
                  warehouses are configured and transparently divides the
                  schema into 10 separate tables for the larger tables for
                  improved scalability and performance. This option is
                  recommended for larger configurations.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>

      <section>
        <title>MySQL Schema Build Options</title>

        <figure>
          <title>MySQL Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-7.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para><table>
            <title>MySQL Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>MySQL Host</entry>

                  <entry>The MySQL Host Name is the host name that your load
                  generation server will use to connect to the database
                  running on the SUT database server.</entry>
                </row>

                <row>
                  <entry>MySQL Port</entry>

                  <entry>The MySQL Port is the network port that your load
                  generation server will use to connect to the database
                  running on the SUT database server. In most cases this will
                  be the default port of 3306.</entry>
                </row>

                <row>
                  <entry>MySQL Socket</entry>

                  <entry>The MySQL Socket option is enabled on Linux only. If
                  HammerDB is running on the same server and the MySQL Host is
                  127.0.0.1 or localhost then HammerDB will open a connection
                  on the socket given instead of using TCP/IP.</entry>
                </row>

                <row>
                  <entry>MySQL User</entry>

                  <entry>The MySQL User is the user which has permission to
                  create a database and you previously granted access to from
                  the load generation server. The root user already exists in
                  all MySQL databases and has the necessary permissions to
                  create the TPROC-C database.</entry>
                </row>

                <row>
                  <entry>MySQL User Password</entry>

                  <entry>The MySQL user password is the password for the user
                  defined as the MySQL User. You will need to remember the
                  MySQL user name and password for running the TPROC-C driver
                  script after the database is built.</entry>
                </row>

                <row>
                  <entry>TRPOC-C MySQL Database</entry>

                  <entry>The MySQL Database is the database that will be
                  created containing the TPROC-C schema creation. There must
                  have sufficient free space for the database to be
                  created.</entry>
                </row>

                <row>
                  <entry>Transactional Storage Engine</entry>

                  <entry>Use the "show engine" command to display available
                  storage engines and select a storage engine that supports
                  transactions. By default set to InnoDB.</entry>
                </row>

                <row>
                  <entry>Number of Warehouses</entry>

                  <entry>The Number of Warehouses is selected by a listbox.
                  You should set this value to number of warehouses you have
                  chosen for your test.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to either the number of warehouses you
                  are going to create (You cannot set the number of virtual
                  users lower than the number of warehouses value) or the
                  number of cores/Hyper-Threads on your Load Generation
                  Server. If you have a significantly larger core/Hyper-Thread
                  count on your Database Server then also installing HammerDB
                  locally n this server as well to run the schema build can
                  take advantage of the higher core count to run the build
                  more quickly.</entry>
                </row>

                <row>
                  <entry>Partition Order Line Table</entry>

                  <entry>Partition Order Line Table for improved
                  scalability.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>

      <section>
        <title>PostgreSQL Schema Build Options</title>

        <figure>
          <title>PostgreSQL Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-8.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para/>

        <para><table>
            <title>PostgreSQL Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>PostgreSQL Host</entry>

                  <entry>The host name of the SUT running PostgreSQL which the
                  load generation server running HammerDB will connect
                  to.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Port</entry>

                  <entry>The port of the PostgreSQL service. By default this
                  will be 5432 for a standard PostgreSQL installation or 5444
                  for EnterpriseDB.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Superuser</entry>

                  <entry>The PostgreSQL Superuser is a user with sufficient
                  privileges to create both new users (roles) and databases to
                  enable the creation of the test schema.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Superuser Password</entry>

                  <entry>The PostgreSQL Superuser Password is the password for
                  the PostgreSQL superuser which will have been defined during
                  installation. If you have forgotten the password it can be
                  reset from a psql prompt that has logged in from a trusted
                  connection therefore requiring no password using postgres=#
                  alter role postgres password ‘postgres’;</entry>
                </row>

                <row>
                  <entry>PostgreSQL Default Database</entry>

                  <entry>The PostgreSQL default databases is the database to
                  specify for the superuser connection. Typically this will be
                  postgres for a standard PostgreSQL installation or edb for
                  EnterpriseDB.</entry>
                </row>

                <row>
                  <entry>TPROC-C PostgreSQL User</entry>

                  <entry>The PostgreSQL User is the user (role) that will be
                  created that owns the database containing the TPROC-C
                  schema.</entry>
                </row>

                <row>
                  <entry>TPROC-C PostgreSQL User Password</entry>

                  <entry>The PostgreSQL User Password is the password that
                  will be specified for the PostgreSQL user when it is
                  created.</entry>
                </row>

                <row>
                  <entry>TPROC-C PostgreSQL Database</entry>

                  <entry>The PostgreSQL Database is the database that if it
                  does not already exist will be created and owned by the
                  PostgreSQL User that contains the TPROC-C schema. If the
                  named database has already been created and is empty then
                  that database will be used to create the schema.</entry>
                </row>

                <row>
                  <entry>TPROC-C PostgreSQL Tablespace</entry>

                  <entry>The PostgreSQL Tablespace in which to create the
                  schema. By default the tablespace is pg_default.</entry>
                </row>

                <row>
                  <entry>EnterpriseDB Oracle Compatible</entry>

                  <entry>Choosing EnterpriseDB Oracle compatible creates a
                  schema using the Oracle compatible features of EnterpriseDB
                  in an installation of Postgres Plus Advanced Server. This
                  build uses Oracle PL/SQL for the creation of the stored
                  procedures.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Stored Procedures</entry>

                  <entry>When running on PostgreSQL v11 or upwards use
                  PostgreSQL stored procedures instead of functions.</entry>
                </row>

                <row>
                  <entry>Number of Warehouses</entry>

                  <entry>The Number of Warehouses is selected by a listbox.
                  You should set this value to number of warehouses you have
                  chosen for your test.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to either the number of warehouses you
                  are going to create (You cannot set the number of virtual
                  users lower than the number of warehouses value) or the
                  number of cores/Hyper-Threads on your Load Generation
                  Server. If you have a significantly larger core/Hyper-Thread
                  count on your Database Server then also installing HammerDB
                  locally on this server as well to run the schema build can
                  take advantage of the higher core count to run the build
                  more quickly.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>
    </section>

    <section>
      <title>Creating the Schema</title>

      <para>When you have completed your Build Options click OK to store the
      values you have entered. To begin the schema creation select Build from
      the tree-view.</para>

      <para><figure>
          <title>Build</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-10.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>On clicking this button a dialog box is shown</para>

      <para><figure>
          <title>Create Schema</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-11.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>When you click Yes HammerDB will login to your chosen database a
      monitor virtual user and depending on the database create the user with
      the password you have chosen. It will then log out and log in again as
      your chosen user, create the tables and then load the item table data
      before waiting and monitoring the other virtual users. The worker
      virtual users will wait for the monitor virtual user to complete its
      initial work. Subsequently the worker virtual users will create and
      insert the data for their assigned warehouses. There are no intermediate
      data files or manual builds required, HammerDB will both create and load
      your requested data dynamically. Data is inserted in a batch format for
      optimal network performance.</para>

      <figure>
        <title>Schema Build Start</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-12.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When the worker virtual users are complete the monitor virtual
      users will depending on the database create the indexes, stored
      procedures and gather the statistics. When the schema build is complete
      Virtual User 1 will display the message SCHEMA COMPLETE and all virtual
      users will show an end timestamp and that they completed their action
      successfully. If this is not the case then then build did not complete
      successfully, the schema is not valid for testing and should therefore
      be deleted and reinstalled.</para>

      <figure>
        <title>Schema complete</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-13.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <section>
        <title>Deleting or Verifying the Oracle Schema</title>

        <para>If you have made a mistake simply close the application and run
        the following SQL to undo the user you have created.</para>

        <programlisting>SQL&gt;drop user tpcc cascade;</programlisting>

        <para>Note that if Hash Clusters were used it will first be necessary
        to re-enable the table locks as follows before deleting the
        schema.</para>

        <programlisting>ALTER TABLE WAREHOUSE DISABLE TABLE LOCK;
ALTER TABLE DISTRICT DISABLE TABLE LOCK;
ALTER TABLE CUSTOMER DISABLE TABLE LOCK;
ALTER TABLE ITEM DISABLE TABLE LOCK;
ALTER TABLE STOCK DISABLE TABLE LOCK;
ALTER TABLE ORDERS DISABLE TABLE LOCK;
ALTER TABLE NEW_ORDER DISABLE TABLE LOCK;
ALTER TABLE ORDER_LINE DISABLE TABLE LOCK;
ALTER TABLE HISTORY DISABLE TABLE LOCK;</programlisting>

        <para>When you have created your schema you can verify the contents
        with SQL*PLUS or your favourite admin tool as the newly created
        user.</para>

        <para><programlisting>SQL&gt; select tname, tabtype from tab;

TNAME                          TABTYPE
------------------------------ -------
HISTORY                          TABLE
CUSTOMER                         TABLE
DISTRICT                         TABLE
ITEM                             TABLE
WAREHOUSE                        TABLE
STOCK                            TABLE
NEW_ORDER                        TABLE
ORDERS                           TABLE
ORDER_LINE                       TABLE

9 rows selected.

SQL&gt; select * from warehouse;

      W_ID      W_YTD      W_TAX W_NAME     W_STREET_1
---------- ---------- ---------- ---------- --------------------
W_STREET_2           W_CITY               W_ W_ZIP
-------------------- -------------------- -- ---------
         1  773095764        .11 4R0mUe     rM8f7zFYdx
JyiNY5zg1gQNBDO      v2973cRoiFSJ0z       OF 374311111


SQL&gt; select index_name, index_type from ind;

INDEX_NAME                     INDEX_TYPE
------------------------------ ---------------------------
IORDL                          IOT - TOP
ORDERS_I1                      NORMAL
ORDERS_I2                      NORMAL
INORD                          IOT - TOP
STOCK_I1                       NORMAL
WAREHOUSE_I1                   NORMAL
ITEM_I1                        NORMAL
DISTRICT_I1                    NORMAL
CUSTOMER_I1                    NORMAL
CUSTOMER_I2                    NORMAL

10 rows selected.

SQL&gt;

SQL&gt; select object_name from user_procedures;

OBJECT_NAME
------------------------------
NEWORD
DELIVERY
PAYMENT
OSTAT
SLEV

SQL&gt; select sum(bytes)/1024/1024 as MB from user_segments;
        MB
----------
   838.125

</programlisting></para>
      </section>

      <section>
        <title>Deleting or Verifying the SQL Server Schema and In-memory
        Schema</title>

        <para>If you have made a mistake simply close the application and in
        SQL Server Management Studio right-click the database and choose
        Delete. Select the Close existing connections checkbox and click OK.
        When you have created your schema you can verify the contents with the
        SQL Server Management Studio or SQL Connection, for example:</para>

        <para><programlisting>C:\Users&gt;sqlcmd -S (local)\SQLDEVELOP -E -Q "use tpcc; select name from sys.tables"
Changed database context to 'tpcc'.
name
---------------------------------------------------------------------------
CUSTOMER
DISTRICT
HISTORY
ITEM
NEW_ORDER
ORDERS
ORDER_LINE
STOCK
WAREHOUSE
(9 rows affected)

C:\Users&gt;sqlcmd -S (local)\SQLDEVELOP -E -Q "use tpcc; select * from wareh
ouse where w_id = 1"
Changed database context to 'tpcc'.
w_id        w_ytd                 w_tax        w_name     w_street_1           w
_street_2           w_city               w_state w_zip     padding
          1          3000000.0000        .1000 s21C90Ft   pd1mYv9GlqyIww      u
6sOhAB9HF7iOZpM     llz9x35NhpVcrJc47Wy  VL      182111111 xxxxxxxxxxxxxxxxxxxxx(....)
(1 rows affected)
</programlisting>When an In-memory schema has been created under SSMS right
        click the created database and select reports followed memory usage by
        memory optimized objects, this produces a report such as follows for a
        10 warehouse configuration. As with an on-disk schema a rough estimate
        of 100MB per warehouse can be used for the space required. In
        particular note that SQL Server Express has a particularly small
        memory allocation of 252MB and can be used for tests on 1 warehouse
        only for a short period of time before this limit will be reached. The
        error reported in the log will be as follows:</para>

        <programlisting>Could not perform the operation because the database has reached its quota for in-memory tables.

</programlisting>

        <figure>
          <title>SQL Server in-Memory</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-22.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Additionally after schema creation and during testing monitor
        bucket usage as follows:</para>

        <programlisting>use imoltp 
SELECT  
    QUOTENAME(SCHEMA_NAME(t.schema_id)) + N'.' + QUOTENAME(OBJECT_NAME(h.object_id)) as [table],   
    i.name                   as [index],   
    h.total_bucket_count,  
    h.empty_bucket_count,  
      
    FLOOR((  
      CAST(h.empty_bucket_count as float) /  
        h.total_bucket_count) * 100)  
                             as [empty_bucket_percent],  
    h.avg_chain_length,   
    h.max_chain_length  
  FROM  
         sys.dm_db_xtp_hash_index_stats  as h   
    JOIN sys.indexes                     as i  
            ON h.object_id = i.object_id  
           AND h.index_id  = i.index_id  
    JOIN sys.memory_optimized_tables_internal_attributes ia ON h.xtp_object_id=ia.xtp_object_id
    JOIN sys.tables t on h.object_id=t.object_id
  WHERE ia.type=1
  ORDER BY [table], [index];

</programlisting>

        <para>This script produces a report as follows where the
        empty_bucket_percent should indicate a good level of free space and
        the max_chain_length is not too long.</para>

        <figure>
          <title>In-memory report</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-23.png"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Deleting or Verifying the Db2 Schema</title>

        <para>If you have made a mistake simply close the application and run
        the following SQL to undo the user you have created.</para>

        <programlisting>db2inst1 ~]$ db2 drop database tpcc
DB20000I  The DROP DATABASE command completed successfully.
</programlisting>

        <para>To browse the Db2 schema do the following.</para>

        <programlisting>[db2inst1 ~]$ db2 connect to tpcc

   Database Connection Information

 Database server        = DB2/LINUXX8664 10.5.5
 SQL authorization ID   = DB2INST1
 Local database alias   = TPCC

[db2inst1 ~]$ db2
(c) Copyright IBM Corporation 1993,2007
Command Line Processor for DB2 Client 10.5.5

db2 =&gt;  select * from warehouse fetch first 10 rows only

W_NAME     W_STREET_1           W_STREET_2           W_CITY               W_STATE W_ZIP     W_TAX                    W_YTD          W_ID       
---------- -------------------- -------------------- -------------------- ------- --------- ------------------------ -------------- -----------
5SuPObQR4  FCPEw6PzfOCdp5DHDq7e d9lOkysRKPyPtqB      G0Nt9PuUyR8qZxCOXms0 9Y      546011111            +1.70000E-001     3000000.00           1
QP75kKTagb sOaOeFYpGjc5lvA8BW   f6HbFCH2S6mh         cCPt1emu6hFjobgOqeP  TT      533211111            +1.50000E-001     3000000.00           2
Hu3QQhR    KwwcMmuWbpoiQRM      9MaTxygtYX4Dz        NFSkHHdHyEChXclP4iqA cE      919511111            +1.60000E-001     3000000.00           3
aqN3Df     PAJg6lOtk7r          XxWjB1HMQhOlJ        jknxafMFlirG8pUpntm  mG      217211111            +1.80000E-001     3000000.00           4
zZBreP     gCMDTWuJUHh          AG0vp9mbvGh          t7dDHFKFhd72WKP      xa      342611111            +1.30000E-001     3000000.00           5
bleOmY     pzPzlBidlwneHdMkq    dmZvxDxmrL4WdQNg     jC2DTpxGc1g1LQlk5P8n bt      980911111            +1.50000E-001     3000000.00           6
BFmMdkLUUK joucFFovxwZWcdsBPZ   IBjiEBzqn7dtuU       8FNwUX40bJ56Iwh      gC      751911111            +1.00000E-001     3000000.00           7
xWY9EugeeD t5dK0z1bQWwEuMGMnb59 sYEzAdgb9FeuX        K7PkSQHSno0NSHEet4xr 1Q      270611111            +1.70000E-001     3000000.00           8
5XtsHe1kw  uNJGs1Y1lQnYLAX      qvOfjMIqml5kHzm      C3iX14JTbnCyoRVR     ai      203011111            +2.00000E-001     3000000.00           9
t89Pm591   CKjgdxmZ5AgvZ        LqyRXzAoFUO          2O0j38eGPNMXFb       XU      372011111            +1.40000E-001     3000000.00          10

  10 record(s) selected.

db2 =&gt; 
</programlisting>
      </section>

      <section>
        <title>Deleting or Verifying the MySQL Schema</title>

        <para>If you have made a mistake simply close the application and run
        the following SQL to undo the database you have created.</para>

        <programlisting>SQL&gt;drop database tpcc;</programlisting>

        <para>you can verify the contents with SQL or your favourite admin
        tool as the newly created user.</para>

        <programlisting>mysql&gt; use tpcc;
Database changed
mysql&gt; show tables;
+----------------+
| Tables_in_tpcc |
+----------------+
| customer       |
| district       |
| history        |
| item           |
| new_order      |
| order_line     |
| orders         |
| stock          |
| warehouse      |
+----------------+
9 rows in set (0.00 sec)

mysql&gt; select * from warehouse limit 1 \G
*************************** 1. row ***************************
      w_id: 1
     w_ytd: 3000000.00
     w_tax: 0.1300
    w_name: mBr6dkgK
w_street_1: FH0SO5CUEREo
w_street_2: cBcStSxKcIIs4IAUUsJy
    w_city: FKaak9ZBgtJr3Tr6gESW
   w_state: Tt
     w_zip: 432611111
1 row in set (0.00 sec)

mysql&gt; show indexes from warehouse \G
*************************** 1. row ***************************
        Table: warehouse
   Non_unique: 0
     Key_name: PRIMARY
 Seq_in_index: 1
  Column_name: w_id
    Collation: A
  Cardinality: 10
     Sub_part: NULL
       Packed: NULL
         Null:
   Index_type: BTREE
      Comment:
Index_comment:
1 row in set (0.00 sec)

mysql&gt; select routine_name from information_schema.routines where routine_schema
 = 'TPCC';
+--------------+
| routine_name |
+--------------+
| DELIVERY     |
| NEWORD       |
| OSTAT        |
| PAYMENT      |
| SLEV         |
+--------------+
5 rows in set (0.03 sec)
</programlisting>
      </section>

      <section>
        <title>Deleting or Verifying the PostgreSQL Schema</title>

        <para>If you have made a mistake simply close the application and run
        the following SQL to undo the user you have created.</para>

        <programlisting>postgres=# drop database tpcc;
postgres=# drop role tpcc;
</programlisting>

        <para>You can browse the created schema, for example:</para>

        <para><programlisting>-bash-4.1$ ./bin/psql -d tpcc
Password: 
psql.bin (9.3.4.10)
Type "help" for help.

tpcc=# select relname, n_tup_ins - n_tup_del as rowcount from pg_stat_user_tables;
  relname   | rowcount 
------------+----------
 orders     |   300000
 district   |      100
 stock      |  1000000
 warehouse  |       10
 history    |   300000
 new_order  |    90000
 item       |   100000
 order_line |  3001170
 customer   |   300000
(9 rows)
</programlisting></para>
      </section>
    </section>

    <section>
      <title>Configuring Driver Script options</title>

      <para>To configure the Driver Script select Options under the Driver
      Script tree-view.</para>

      <figure>
        <title>Driver Script Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-14.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This displays the Driver Script Options dialog. The connection
      options are common to the Schema Build Dialog in addition to new Driver
      Options. For advanced options more details are provided in the
      subsequent section.</para>

      <figure>
        <title>Driver Script Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-15.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <table>
        <title>Driver Script Options</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Option</entry>

              <entry align="center">Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>TPROC-C Driver Script</entry>

              <entry>For all databases you have the option of selecting a Test
              Driver Script or a Timed Driver Script. The This choice will
              dynamically change the Driver Script that is loaded when the
              TPROC-C Driver Script menu option is chosen. The Test Driver
              Script is intended for verifying and testing a configuration
              only by displaying virtual user output for a small number of
              virtual users. In particular both Windows and Linux graphical
              displays are single-threaded permitting only one Virtual User to
              write to the display at any one time. Therefore the performance
              of writing to the display will limit throughput. Consequently
              once a schema is verified to conduct measured tests you should
              select the Timed Driver Script Option.</entry>
            </row>

            <row>
              <entry>Total Transactions per User</entry>

              <entry>Total transactions per user is reported as
              total_iterations within the EDITABLE OPTIONS section of the
              driver script. This value will set the number of transactions
              each virtual user will process before logging off. You can use
              this value to determine how long the virtual user will remain
              active for. The length of time for activity will depend upon the
              performance of the Database Server under test. A higher
              performing server will process the defined number of
              transactions more quickly than a lower performing one. It is
              important to draw the distinction between the total_iterations
              value and the Iterations value set in the Virtual User Options
              window. The Iterations value in the Virtual User Options window
              determines the number of times that a script will be run in its
              entirety. The total_iterations value is internal to the TPROC-C
              driver script and determines the number of times the internal
              loop is iterated ie for {set it 0} {$it &lt; $total_iterations}
              {incr it} { ... } In other words if total_iterations is set to
              1000 then the executing user will log on once execute 1000
              transactions and then log off. If on the other hand Iterations
              in the Virtual User Options window is set to 1000 and
              total_iterations in the script set to 1 then the executing user
              will log on execute one transaction and then log off 1000
              times.You should ensure that the number of transactions is set
              to a suitably high vale to ensure that the virtual users do not
              complete their tests before the timed test is complete, doing so
              will mean the you will be timing idle virtual users and the
              results will be invalid.</entry>
            </row>

            <row>
              <entry>Exit on Error</entry>

              <entry>Exit on Error is shown as the parameter RAISEERROR in the
              Driver Script. RAISEERROR impacts the behaviour of an individual
              virtual user on detecting a database error. If set to TRUE on
              detecting an error the user will report the error into the
              HammerDB console and then terminate execution. If set to FALSE
              the virtual user will ignore the error and proceed with
              executing the next transaction. It is therefore important to be
              aware that if set to FALSE firstly if there has been a
              configuration error resulting in repeated errors then the
              workload might not be reported accurately and secondly you may
              not be aware of any occasional errors being reported as they are
              silently ignored.</entry>
            </row>

            <row>
              <entry>Keying and Thinking Time</entry>

              <entry>Keying and Thinking Time is shown as KEYANDTHINK in the
              Driver Script. This parameter will have the biggest impact on
              the type of workload that your test will take. Keying and
              thinking time is an integral part of a TPROC-C test in order to
              simulate the effect of the workload being run by a real user who
              takes time to key in an actual order and think about the output.
              If KEYANDTHINK is set to TRUE each user will simulate this real
              user type workload testing a workload scenario that will be
              closer to a real production environment. Whereas with
              KEYANDTHINK set to TRUE each user will execute maybe 2 or 3
              transactions a minute setting KEYANDTHINK to FALSE each user
              will now execute tens of thousands of transactions a minute. If
              this parameter is set to TRUE you will need at least hundreds or
              thousands of virtual users and warehouses, if FALSE then you
              will need to begin testing with 1 or 2 Virtual Users, building
              from here up to a maximum workload with the number of warehouses
              set to a level where the users are not contending for the same
              data. The default mode is to run with KEYANDTHINK set to FALSE
              and this is the method that will drive the highest transaction
              rates. To run with KEYANDTHINK set to TRUE the event driven
              scaling feature has been introduced to scale up the number of
              sessions connecting to the system. This feature is activated by
              selecting the Asynchronous Scaling option (which will also
              enable Keying and Thinking time). When enabled you are able to
              configure multiple sessions per Virtual User. Each Virtual User
              will then manage multiple clients processing the Keying and
              Thinking time asynchronously. With this feature you are able to
              configure significantly more sessions than with a single Virtual
              User configuration.</entry>
            </row>

            <row>
              <entry>Checkpoint/Vacuum when complete</entry>

              <entry>Where available the database will trigger a checkpoint
              after the workload is complete to write out the modified data
              from the in-memory cache to the disk. if the database is
              correctly configured this will prevent this activity being
              conducted during a test to result in higher performance.</entry>
            </row>

            <row>
              <entry>Minutes of Rampup Time</entry>

              <entry>The Minutes of Ramup Time is shown as rampup in the
              Driver Script. The rampup time defines the time in minutes for
              the monitoring virtual user to wait for the virtual users
              running the workload to connect to the database and build up the
              transaction rate by caching data in the database buffer cache
              before taking the first timed value and timing the test. The
              rampup time should be sufficiently long enough for a workload to
              reach a steady transaction rate before the first timed value is
              taken.</entry>
            </row>

            <row>
              <entry>Minutes for Test Duration</entry>

              <entry>The Minutes for Test Duration is shown as duration in the
              Driver Script. The test duration defines the time of the test
              measured as the time the monitor thread waits after the first
              timed value before taking the second one to signal the test is
              complete and the active virtual users to complete their
              workload.</entry>
            </row>

            <row>
              <entry>Use All Warehouses</entry>

              <entry>By default each Virtual User selects a home warehouse at
              random from at the start of a test and remains with that home
              warehouse. Therefore for example if there are 100 warehouses
              created and 10 virtual users selected to run the Driver Script
              then most of the activity will take place on 10 warehouse only.
              This option means that the Virtual Users select a new warehouse
              for each transaction from an available list divided between all
              Virtual Users at the start of the test therefore ensuring
              greater I/O activity.</entry>
            </row>

            <row>
              <entry>Time Profile</entry>

              <entry>This option should be selected in conjunction with having
              enabled output to the logfile. When selected client side time
              profiling will be conducted for the first active virtual user
              and output written to the logfile.</entry>
            </row>

            <row>
              <entry>Asynchronous Scaling</entry>

              <entry>Enable the event driven scaling feature to configure
              multiple client sessions per Virtual User. When selected this
              will also enable the Keying and Thinking Time option. As the
              keying and thinking time is managed asynchronously this option
              is not valid to be run without keying and thinking time.
              Asynchronous Scaling is also a feature that is appropriate to
              test connection pooling by scaling up the number of client
              sessions that connect to the database.</entry>
            </row>

            <row>
              <entry>Asynch Client per Virtual User</entry>

              <entry>Configures the number of sessions that each Virtual User
              will connect to the database and manage. For example if there
              are 5 Virtual Users and 10 Asynchronous Clients there will be 50
              active connections to the database.</entry>
            </row>

            <row>
              <entry>Asynch Client Login Delay</entry>

              <entry>The delay that each Virtual User will allow before
              logging on each asynchronous client.</entry>
            </row>

            <row>
              <entry>Asynchronous Verbose</entry>

              <entry>Report asynchronous operations such as the time taken for
              keying and thinking time.</entry>
            </row>

            <row>
              <entry>XML Connect Pool</entry>

              <entry>XML Connect Pool is intended for simultaneously testing
              multiple instances of related clustered databases and when
              selected the virtual user database connections will open a pool
              of connections defined in the database specific XML file for
              example mssqlscpool.xml for SQL Server located in the directory
              connectpool in the config directory. Note that each virtual user
              (or asynchronous client) will open and hold all of the defined
              connections. The monitor virtual user and each virtual user will
              also continue to open the main standalone database connection.
              The monitor virtual user will continue to report NOPM and TPM
              and the virtual users to extract the warehouse count from this
              standalone connection and therefore the reliance is on the
              database to accurately report cluster wide transactions and for
              the instances to have the same warehouse count. For verification
              of the results from the master connection when using connect
              pooling HammerDB will also report client side transactions. To
              use the XML Connect Pool the XML configuration file should be
              modified according to the cluster database names with each
              connection defined by the tag c1, c2 c3 etc respectively. Under
              the sprocs section in the XML file is defined which stored
              procedures will use which connections and what policy is to be
              used. The policy can be first_named, last_named, random or
              round_robin. For example with connections c1, c2 and c3 for
              neworder and a policy of round_robin the first neworder
              transaction would execute against connection c1, the second c2,
              the third c3 and the fourth c1. first_named uses the first given
              connection, last_named the last and random chooses a connection
              at random. stocklevel and orderstatus are read only stored
              procedures that may be run against read only cluster nodes.
              There is no restriction on the number of connections that may be
              opened per virtual user. For further information on the
              connections opened there is a commented information line in the
              driver script such as #puts "sproc_cur:$st connections:[ set
              $cslist ] cursors:[set $cursor_list] number of cursors:[set
              $len] execs:[set $cnt]" prior to the opening of the standalone
              connection that may be uncommented for more detail when the
              script is run.</entry>
            </row>

            <row>
              <entry>Mode</entry>

              <entry>The mode value is taken from the operational mode setting
              set under the Mode Options menu tab under the Mode menu. If set
              to Local or Primary then the monitor thread takes snapshots, if
              set to Replica no snapshots are taken. This is useful if
              multiple instances of HammerDB are running in Primary and
              Replica mode against a clustered database configuration to
              ensure that only one instance takes the snapshots.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section>
      <title>Advanced Driver Script Options</title>

      <para>This section includes advanced driver script options intended for
      expert usage. These options can be used independently or simultaneously
      for advanced testing scenarios.</para>

      <section>
        <title>Use All Warehouses for increased I/O</title>

        <para>By default each Virtual User will select one home warehouse at
        random and keep that home warehouse for the duration of a run meaning
        the majority of its workload will take place on a single warehouse.
        This means that when running for example 10 Virtual Users most of the
        workload will take place on 10 warehouses regardless of whether 100,
        1000 or 10,000 are configured in the schema. Use All Warehouses is an
        option that enables increased I/O to the database data area by
        assigning all of the warehouses in the schema to the Virtual Users in
        turn. The Virtual Users will then select a new warehouse for each
        transaction. Consequently this means that the schema size impacts on
        the overall level of performance placing a great emphasis on I/O. To
        select this option check the Use All Warehouses check-box.</para>

        <figure>
          <title>Use All Warehouses Option</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15l.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>On running the workload it can now be seen that the Virtual
        Users will evenly assign the available warehouses between them.</para>

        <figure>
          <title>Use All Warehouses</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15k.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>The listing shows an example of a schema with 30 warehouses and
        3 Virtual Users. This approach is particularly applicable when testing
        I/O capabilities for database.</para>

        <programlisting>Vuser 1:Beginning rampup time of 2 minutes
Vuser 2:VU 2 : Assigning WID=1 based on VU count 3, Warehouses = 30 (1 out of 10)
Vuser 2:VU 2 : Assigning WID=4 based on VU count 3, Warehouses = 30 (2 out of 10)
Vuser 2:VU 2 : Assigning WID=7 based on VU count 3, Warehouses = 30 (3 out of 10)
Vuser 2:VU 2 : Assigning WID=10 based on VU count 3, Warehouses = 30 (4 out of 10)
Vuser 2:VU 2 : Assigning WID=13 based on VU count 3, Warehouses = 30 (5 out of 10)
Vuser 2:VU 2 : Assigning WID=16 based on VU count 3, Warehouses = 30 (6 out of 10)
Vuser 2:VU 2 : Assigning WID=19 based on VU count 3, Warehouses = 30 (7 out of 10)
Vuser 2:VU 2 : Assigning WID=22 based on VU count 3, Warehouses = 30 (8 out of 10)
Vuser 2:VU 2 : Assigning WID=25 based on VU count 3, Warehouses = 30 (9 out of 10)
Vuser 2:VU 2 : Assigning WID=28 based on VU count 3, Warehouses = 30 (10 out of 10)
Vuser 2:Processing 1000000 transactions with output suppressed...
Vuser 3:VU 3 : Assigning WID=2 based on VU count 3, Warehouses = 30 (1 out of 10)
Vuser 3:VU 3 : Assigning WID=5 based on VU count 3, Warehouses = 30 (2 out of 10)
Vuser 3:VU 3 : Assigning WID=8 based on VU count 3, Warehouses = 30 (3 out of 10)
Vuser 3:VU 3 : Assigning WID=11 based on VU count 3, Warehouses = 30 (4 out of 10)
Vuser 3:VU 3 : Assigning WID=14 based on VU count 3, Warehouses = 30 (5 out of 10)
Vuser 3:VU 3 : Assigning WID=17 based on VU count 3, Warehouses = 30 (6 out of 10)
Vuser 3:VU 3 : Assigning WID=20 based on VU count 3, Warehouses = 30 (7 out of 10)
Vuser 3:VU 3 : Assigning WID=23 based on VU count 3, Warehouses = 30 (8 out of 10)
Vuser 3:VU 3 : Assigning WID=26 based on VU count 3, Warehouses = 30 (9 out of 10)
Vuser 3:VU 3 : Assigning WID=29 based on VU count 3, Warehouses = 30 (10 out of 10)
Vuser 3:Processing 1000000 transactions with output suppressed...
Vuser 4:VU 4 : Assigning WID=3 based on VU count 3, Warehouses = 30 (1 out of 10)
Vuser 4:VU 4 : Assigning WID=6 based on VU count 3, Warehouses = 30 (2 out of 10)
Vuser 4:VU 4 : Assigning WID=9 based on VU count 3, Warehouses = 30 (3 out of 10)
Vuser 4:VU 4 : Assigning WID=12 based on VU count 3, Warehouses = 30 (4 out of 10)
Vuser 4:VU 4 : Assigning WID=15 based on VU count 3, Warehouses = 30 (5 out of 10)
Vuser 4:VU 4 : Assigning WID=18 based on VU count 3, Warehouses = 30 (6 out of 10)
Vuser 4:VU 4 : Assigning WID=21 based on VU count 3, Warehouses = 30 (7 out of 10)
Vuser 4:VU 4 : Assigning WID=24 based on VU count 3, Warehouses = 30 (8 out of 10)
Vuser 4:VU 4 : Assigning WID=27 based on VU count 3, Warehouses = 30 (9 out of 10)
Vuser 4:VU 4 : Assigning WID=30 based on VU count 3, Warehouses = 30 (10 out of 10)</programlisting>
      </section>

      <section>
        <title>Time Profile for measuring Response Times</title>

        <para>In addition to performance profiles based on throughput you
        should also take note of transaction response times. Whereas
        performance profiles show the cumulative performance of all of the
        virtual users running on the system, response times show performance
        based on the experience of the individual user. When comparing systems
        both throughput and response time are important comparative
        measurements. HammerDB includes a time profiling package called etprof
        that enables you to select an individual user and measure the response
        times. This functionality is enabled by selecting Time Profile
        checkbox in the driver options. When enabled the time profile will
        show response time percentile values at 10 second intervals, reporting
        the minimum, 50th percentile, 95th percentile, 99th percentile and
        maximum for each of the procedures during that 10 second interval as
        well as cumulative values for all of the test at the end of the test
        run. The time profile values are recorded in microseconds.</para>

        <programlisting>Hammerdb Log @ Fri Jul 05 09:55:26 BST 2019
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
Vuser 1:Beginning rampup time of 1 minutes
Vuser 2:Processing 1000000 transactions with output suppressed...
Vuser 3:Processing 1000000 transactions with output suppressed...
Vuser 4:Processing 1000000 transactions with output suppressed...
Vuser 5:Processing 1000000 transactions with output suppressed...
Vuser 2:|PERCENTILES 2019-07-05 09:55:46 to 2019-07-05 09:55:56
Vuser 2:|neword|MIN-391|P50%-685|P95%-1286|P99%-3298|MAX-246555|SAMPLES-3603
Vuser 2:|payment|MIN-314|P50%-574|P95%-1211|P99%-2253|MAX-89367|SAMPLES-3564
Vuser 2:|delivery|MIN-1128|P50%-1784|P95%-2784|P99%-6960|MAX-267012|SAMPLES-356
Vuser 2:|slev|MIN-723|P50%-884|P95%-1363|P99%-3766|MAX-120687|SAMPLES-343
Vuser 2:|ostat|MIN-233|P50%-568|P95%-1325|P99%-2387|MAX-82538|SAMPLES-365
Vuser 2:|gettimestamp|MIN-2|P50%-4|P95%-7|P99%-14|MAX-39|SAMPLES-7521
Vuser 2:|prep_statement|MIN-188|P50%-209|P95%-1067|P99%-1067|MAX-1067|SAMPLES-6
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+
...
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+
Vuser 2:|PERCENTILES 2019-07-05 09:59:26 to 2019-07-05 09:59:36
Vuser 2:|neword|MIN-410|P50%-678|P95%-1314|P99%-4370|MAX-32030|SAMPLES-4084
Vuser 2:|payment|MIN-331|P50%-583|P95%-1271|P99%-3152|MAX-43996|SAMPLES-4142
Vuser 2:|delivery|MIN-1177|P50%-2132|P95%-3346|P99%-4040|MAX-8492|SAMPLES-416
Vuser 2:|slev|MIN-684|P50%-880|P95%-1375|P99%-1950|MAX-230733|SAMPLES-364
Vuser 2:|ostat|MIN-266|P50%-688.5|P95%-1292|P99%-1827|MAX-9790|SAMPLES-427
Vuser 2:|gettimestamp|MIN-3|P50%-4|P95%-7|P99%-14|MAX-22|SAMPLES-8639
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+
Vuser 2:|PERCENTILES 2019-07-05 09:59:36 to 2019-07-05 09:59:46
Vuser 2:|neword|MIN-404|P50%-702|P95%-1296|P99%-4318|MAX-71663|SAMPLES-3804
Vuser 2:|payment|MIN-331|P50%-597|P95%-1250|P99%-4190|MAX-47539|SAMPLES-3879
Vuser 2:|delivery|MIN-1306|P50%-2131|P95%-4013|P99%-8742|MAX-25095|SAMPLES-398
Vuser 2:|slev|MIN-713|P50%-913|P95%-1438|P99%-2043|MAX-7434|SAMPLES-386
Vuser 2:|ostat|MIN-268|P50%-703|P95%-1414|P99%-3381|MAX-249963|SAMPLES-416
Vuser 2:|gettimestamp|MIN-3|P50%-4|P95%-8|P99%-16|MAX-27|SAMPLES-8079
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+
Vuser 1:3 ...,
Vuser 1:Test complete, Taking end Transaction Count.
Vuser 1:4 Active Virtual Users configured
Vuser 1:TEST RESULT : System achieved 468610 SQL Server TPM at 101789 NOPM
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+
Vuser 2:|PROCNAME | EXCLUSIVETOT| %| CALLNUM| AVGPERCALL| CUMULTOT|
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+
Vuser 2:|neword | 82051665|39.96%| 93933| 873| 88760245|
Vuser 2:|payment | 73823956|35.95%| 93922| 786| 80531339|
Vuser 2:|delivery | 22725292|11.07%| 9577| 2372| 23418195|
Vuser 2:|slev | 14396765| 7.01%| 9340| 1541| 14402033|
Vuser 2:|ostat | 10202116| 4.97%| 9412| 1083| 10207260|
Vuser 2:|gettimestamp | 2149552| 1.05%| 197432| 10| 13436919|
Vuser 2:|TOPLEVEL | 2431| 0.00%| 1| 2431| NOT AVAILABLE|
Vuser 2:|prep_statement | 1935| 0.00%| 5| 387| 1936|
Vuser 2:+-----------------+--------------+------+--------+--------------+--------------+</programlisting>

        <para>After capturing the response time the script below can be run at
        the command line and provided with a logfile with the data for one run
        only. Note that it is important that you only provide a logfile for
        one run of a HammerDB benchmark to convert, otherwise all of the data
        will be combined from multiple runs. When run on a logfile with data
        such as shown above this will output the data in tab delimited format
        that can be interpreted by a spreadsheet.</para>

        <programlisting>!/bin/tclsh
 set filename [lindex $argv 0]
 set fp [open "$filename" r]
 set file_data [ read $fp ]
 set data [split $file_data "\n"]
 foreach line $data {
 if {[ string match *PERCENTILES* $line ]} {
 set timeval "[ lindex [ split $line ] 3 ]"
 append xaxis "$timeval\t"
         }
     }
 puts "TIME INTERVALS"
 puts "\t$xaxis"
 foreach storedproc {neword payment delivery slev ostat} {
 puts [ string toupper $storedproc ]
 foreach line $data {
 if {[ string match *PROCNAME* $line ]} { break }
 if {[ string match *$storedproc* $line ]} {
 regexp {MIN-[0-9.]+} $line min
 regsub {MIN-} $min "" min
 append minlist "$min\t"
 regexp {P50%-[0-9.]+} $line p50
 regsub {P50%-} $p50 "" p50
 append p50list "$p50\t"
 regexp {P95%-[0-9.]+} $line p95
 regsub {P95%-} $p95 "" p95
 append p95list "$p95\t"
 regexp {P99%-[0-9.]+} $line p99
 regsub {P99%-} $p99 "" p99
 append p99list "$p99\t"
 regexp {MAX-[0-9.]+} $line max
 regsub {MAX-} $max "" max
 append maxlist "$max\t"
     }
       }
 puts -nonewline "MIN\t"
 puts $minlist
 unset -nocomplain minlist
 puts -nonewline "P50\t"
 puts $p50list 
 unset -nocomplain p50list
 puts -nonewline "P95\t"
 puts $p95list 
 unset -nocomplain p95list
 puts -nonewline "P99\t"
 puts $p99list
 unset -nocomplain p99list
 puts -nonewline "MAX\t"
 puts $maxlist
 unset -nocomplain maxlist
     }
 close $fp</programlisting>

        <para>Pass the name of the logfile for the run where response times
        were captured and output them to a file with a spreadsheet extension
        name. Note that it is important to output the data to a file and not
        to a terminal with that data then cut and paste into a spreadsheet. If
        output to a terminal it may format the output by removing the tab
        characters which are essential to the formatting.</para>

        <programlisting>$ ./extracttp.tcl pgtp.log &gt; pgtp.txt</programlisting>

        <para>With Excel 2013 and above you can give this file a .xls
        extension and open it. If you do it will give the following warning,
        however if you click OK it will open with the correctly formatted
        data.</para>

        <figure>
          <title>Excel Warning</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15a.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Alternatively if we open the file with the .txt extension it
        will show 3 steps for the Text Import Wizard. Click through the Wizard
        until Finish, After clicking Finish the data has been imported into
        the spreadsheet without warnings. Highlight the rows you want to graph
        by clicking on the row numbers.</para>

        <para><figure>
            <title>Highlighted Rows</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="docs/images/ch4-15b.png"/>
              </imageobject>
            </mediaobject>
          </figure></para>

        <para>Click on Insert and Recommended Charts, the default graph
        produced by Excel is shown below with the addition of a vertical axis
        title and a chart header. When saving the spreadsheet it is saved in
        Excel format rather than the imported Tab (Text Delimited).</para>

        <figure>
          <title>Response Time Graph</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15c.png"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Event Driven Scaling for Keying and Thinking Times</title>

        <para>Event driven scaling enables the scaling of virtual users to
        thousands of sessions running with keying and thinking time enabled.
        This feature adds additional benefit to your testing scenarios with
        the ability to handle large numbers of connections or testing with
        connection pooling. When running transactional workloads with HammerDB
        the default mode is CPU intensive meaning that one virtual user will
        run as many transactions as possible without keying and thinking time
        enabled. When keying and thinking time is enabled there is a large
        time delay both before and after running a transaction meaning that
        each Virtual User will spend most of its time idle. However creating a
        very large number of Virtual Users requires a significant use of load
        test generation server resources. Consequently event driven scaling is
        a feature that enables each Virtual User to create multiple database
        sessions and manage the keying and thinking time for each
        asynchronously in an event-driven loop enabling HammerDB to create a
        much larger session count within an existing Virtual User footprint.
        It should be clear that this feature is only designed to work with
        keying and thinking time enabled as it is only the keying and thinking
        time that is managed asynchronously.</para>

        <para>To configure this feature select Asynchronous Scaling noting
        that Keying and Thinking Time is automatically selected. Select a
        number of Asynch Clients per Virtual User and set the Asynch Login
        Delay in milliseconds. This Login Delay means that each client will
        wait for this time after the previous client has logged in before then
        logging in itself. For detailed output select Asynchronous Verbose.
        Note that with this feature it is important to allow the clients
        enough time to both login fully before measuring performance and also
        at the end it will take additional time for the clients to all
        complete their current keying and thinking time and to exit before the
        Virtual User reports all clients as complete.</para>

        <figure>
          <title>Asynchronous Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15e.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>When all Virtual Users have logged in (example from SQL Server)
        the session count will show as the number of Virtual Users multiplied
        by the Asynchronous Clients.</para>

        <programlisting>SELECT DB_NAME(dbid) as DBName, COUNT(dbid) as NumberOfConnections FROM sys.sysprocesses WHERE dbid &gt; 0 GROUP BY dbid;</programlisting>

        <figure>
          <title>Session Count</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15g.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>As each Asynchronous Client logs in it will be reported in the
        Virtual User output.</para>

        <figure>
          <title>Logging In Asynchronous Clients</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15f.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>When the workload is running with Asynchronous Verbose enabled
        HammerDB will report the events as they happen.</para>

        <figure>
          <title>Asynchronous Workload Running</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15h.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>With logging enabled and Asynchronous Verbose HammerDB will
        report the events as they happen for each Virtual User such as when
        they enter keying or thinking time and when they process a
        transaction.</para>

        <programlisting>Vuser 6:keytime:payment:vuser6:ac9:3 secs
Vuser 7:keytime:payment:vuser7:ac92:3 secs
Vuser 7:thinktime:delivery:vuser7:ac77:3 secs
Vuser 3:keytime:payment:vuser3:ac30:3 secs
Vuser 9:keytime:delivery:vuser9:ac49:2 secs
Vuser 7:vuser7:ac77:w_id:21:payment
Vuser 9:keytime:neword:vuser9:ac64:18 secs
Vuser 3:thinktime:neword:vuser3:ac72:15 secs
Vuser 3:vuser3:ac72:w_id:4:payment
Vuser 3:keytime:neword:vuser3:ac52:18 secs
Vuser 7:thinktime:neword:vuser7:ac43:8 secs
Vuser 7:vuser7:ac43:w_id:6:payment
Vuser 7:keytime:ostat:vuser7:ac9:2 secs
Vuser 3:keytime:payment:vuser3:ac9:3 secs
Vuser 3:thinktime:payment:vuser3:ac97:7 secs
Vuser 11:keytime:payment:vuser11:ac42:3 secs
Vuser 5:keytime:neword:vuser5:ac42:18 secs
Vuser 9:thinktime:ostat:vuser9:ac71:3 secs
Vuser 3:vuser3:ac97:w_id:24:payment
Vuser 9:vuser9:ac71:w_id:9:delivery
Vuser 9:keytime:delivery:vuser9:ac69:2 secs
Vuser 5:keytime:delivery:vuser5:ac19:2 secs
Vuser 11:thinktime:neword:vuser11:ac53:13 secs
Vuser 11:vuser11:ac53:w_id:8:neword
Vuser 9:keytime:delivery:vuser9:ac2:2 secs
Vuser 7:thinktime:neword:vuser7:ac81:12 secs
Vuser 3:keytime:neword:vuser3:ac47:18 secs
Vuser 7:vuser7:ac81:w_id:5:payment
Vuser 3:keytime:payment:vuser3:ac81:3 secs
Vuser 7:keytime:slev:vuser7:ac46:2 secs
Vuser 11:thinktime:payment:vuser11:ac65:2 secs
Vuser 11:vuser11:ac65:w_id:21:slev
Vuser 9:keytime:neword:vuser9:ac86:18 secs
Vuser 11:thinktime:payment:vuser11:ac20:1 secs
Vuser 7:thinktime:neword:vuser7:ac76:9 secs
Vuser 11:vuser11:ac20:w_id:6:payment
Vuser 7:vuser7:ac76:w_id:1:payment
Vuser 11:keytime:delivery:vuser11:ac79:2 secs
Vuser 9:thinktime:neword:vuser9:ac57:15 secs
Vuser 11:thinktime:payment:vuser11:ac30:14 secs
Vuser 9:vuser9:ac57:w_id:3:ostat
Vuser 11:vuser11:ac30:w_id:5:neword
Vuser 9:keytime:payment:vuser9:ac3:3 secs
Vuser 11:keytime:payment:vuser11:ac62:3 secs
Vuser 3:keytime:payment:vuser3:ac35:3 secs
Vuser 7:keytime:neword:vuser7:ac88:18 secs
Vuser 11:keytime:payment:vuser11:ac96:3 secs
Vuser 11:thinktime:payment:vuser11:ac47:8 secs
Vuser 11:vuser11:ac47:w_id:4:neword
Vuser 3:thinktime:payment:vuser3:ac24:21 secs
Vuser 5:keytime:neword:vuser5:ac37:18 secs
Vuser 7:keytime:payment:vuser7:ac16:3 secs
Vuser 11:keytime:payment:vuser11:ac88:3 secs
Vuser 3:vuser3:ac24:w_id:16:neword
Vuser 11:thinktime:slev:vuser11:ac25:6 secs
Vuser 11:vuser11:ac25:w_id:3:payment
Vuser 5:thinktime:payment:vuser5:ac40:2 secs
Vuser 5:vuser5:ac40:w_id:26:neword
Vuser 5:thinktime:neword:vuser5:ac63:7 secs
Vuser 5:vuser5:ac63:w_id:10:payment</programlisting>

        <para>One particular advantage of this type of workload is to be able
        to run a fixed throughput test defined by the number of Virtual
        Users.</para>

        <figure>
          <title>Steady State</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15i.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>On completion of the workloads the Monitor Virtual User will
        report the number of Active Sessions and the performance achieved. The
        active Virtual Users will report when all of the asynchronous clients
        have completed their workloads and logged off.</para>

        <figure>
          <title>Asynchronous Workload Complete</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15j.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>The event driven scaling feature is not intended to replace the
        default CPU intensive mode of testing and it is expected that this
        will continue to be the most popular methodology. Instead being able
        to increase up client sessions with keying and thinking time adds
        additional test scenarios for highly scalable systems and in
        particular is an effective test methodology for testing middle tier or
        proxy systems.</para>
      </section>

      <section>
        <title>XML Connect Pool for Cluster Testing</title>

        <para>The XML Connect Pool is intended for simultaneously testing
        related multiple instances of a clustered database. It enables each
        Virtual User to open a pool of connections (Note that each virtual
        user (or asynchronous client) will open and hold all of the defined
        connections) and direct the individual transactions to run on a
        specific instance according to a pre-defined policy. With this
        approach it is possible for example to direct the read-write
        transactions to a primary instance on a cluster whilst directing the
        read-only transactions to the secondary.</para>

        <para><figure>
            <title>Connect Pooling</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="docs/images/ch4-15d.png"/>
              </imageobject>
            </mediaobject>
          </figure>Note that for testing or evaluation of this feature it is
        also possible to direct one HammerDB client to test multiple separate
        instances at the same time provided that the instances have exactly
        the same warehouse count as shown in the example below. However for a
        valid and comparable test consistency should be ensured between the
        database instances. Therefore for example directing transactions
        against any instance in an Oracle RAC configuration would be valid as
        would running the read only transactions against a secondary read only
        instance in a cluster. However running against separate unrelated
        instances is possible for testing but not comparable for performance
        results. The monitor virtual user will continue to connect to the
        instance defined in the driver options and report NOPM and TPM from
        this standalone connection only and therefore the reliance is on the
        database to accurately report a cluster wide transactions and for the
        instances to have the same warehouse count. Nevertheless when using
        the XML connect pooling a client side transaction count will also be
        reported to provide detailed transaction data from all Virtual
        Users.</para>

        <para>The configuration is defined in the database specific XML file
        in the config/connpool directory. It is recommended to make a backup
        of the file before it is modified. The XML configuration file is in 2
        sections, connections and sprocs. For connections the XML
        configuration file should be modified according to the cluster
        database names with each connection defined by the tags c1, c2, c3
        respectively. There is no restriction to the number of connections
        that you define. Under the sprocs section in the XML configuration
        file is defined which stored procedures will use which connections and
        what policy is to be used. The policy can be first_named, last_named,
        random or round_robin. For example with connections c1, c2 and c3 for
        neworder and a policy of round_robin the first neworder transaction
        would execute against connection c1, the second c2, the third c3, the
        fourth c1 and so on. For all databases and all stored procedures
        prepared statements are used meaning that a statement is prepared for
        each connection for each virtual user and a reference kept for that
        prepared statement for execution.</para>

        <para>For further information on the connections opened there is a
        commented information line in the driver script such as #puts
        "sproc_cur:$st connections:[ set $cslist ] cursors:[set $cursor_list]
        number of cursors:[set $len] execs:[set $cnt]" prior to the opening of
        the standalone connection that may be uncommented for more detail when
        the script is run.</para>

        <programlisting>&lt;connpool&gt;
&lt;connections&gt;
    &lt;c1&gt;
        &lt;mssqls_server&gt;(local)\SQLDEVELOP&lt;/mssqls_server&gt;
        &lt;mssqls_linux_server&gt;host1&lt;/mssqls_linux_server&gt;
        &lt;mssqls_tcp&gt;false&lt;/mssqls_tcp&gt;
        &lt;mssqls_port&gt;1433&lt;/mssqls_port&gt;
        &lt;mssqls_azure&gt;false&lt;/mssqls_azure&gt;
        &lt;mssqls_authentication&gt;windows&lt;/mssqls_authentication&gt;
        &lt;mssqls_linux_authent&gt;sql&lt;/mssqls_linux_authent&gt;
&lt;mssqls_odbc_driver&gt;ODBC Driver 17 for SQL Server&lt;/mssqls_odbc_driver&gt;
&lt;mssqls_linux_odbc&gt;ODBC Driver 17 for SQL Server&lt;/mssqls_linux_odbc&gt;
        &lt;mssqls_uid&gt;sa&lt;/mssqls_uid&gt;
        &lt;mssqls_pass&gt;admin&lt;/mssqls_pass&gt;
&lt;mssqls_dbase&gt;tpcc1&lt;/mssqls_dbase&gt;
    &lt;/c1&gt;
    &lt;c2&gt;
        &lt;mssqls_server&gt;(local)\SQLDEVELOP&lt;/mssqls_server&gt;
        &lt;mssqls_linux_server&gt;host2&lt;/mssqls_linux_server&gt;
        &lt;mssqls_tcp&gt;false&lt;/mssqls_tcp&gt;
        &lt;mssqls_port&gt;1433&lt;/mssqls_port&gt;
        &lt;mssqls_azure&gt;false&lt;/mssqls_azure&gt;
        &lt;mssqls_authentication&gt;windows&lt;/mssqls_authentication&gt;
        &lt;mssqls_linux_authent&gt;sql&lt;/mssqls_linux_authent&gt;
&lt;mssqls_odbc_driver&gt;ODBC Driver 17 for SQL Server&lt;/mssqls_odbc_driver&gt;
&lt;mssqls_linux_odbc&gt;ODBC Driver 17 for SQL Server&lt;/mssqls_linux_odbc&gt;
        &lt;mssqls_uid&gt;sa&lt;/mssqls_uid&gt;
        &lt;mssqls_pass&gt;admin&lt;/mssqls_pass&gt;
&lt;mssqls_dbase&gt;tpcc2&lt;/mssqls_dbase&gt;
    &lt;/c2&gt;
    &lt;c3&gt;
        &lt;mssqls_server&gt;(local)\SQLDEVELOP&lt;/mssqls_server&gt;
        &lt;mssqls_linux_server&gt;host3&lt;/mssqls_linux_server&gt;
        &lt;mssqls_tcp&gt;false&lt;/mssqls_tcp&gt;
        &lt;mssqls_port&gt;1433&lt;/mssqls_port&gt;
        &lt;mssqls_azure&gt;false&lt;/mssqls_azure&gt;
        &lt;mssqls_authentication&gt;windows&lt;/mssqls_authentication&gt;
        &lt;mssqls_linux_authent&gt;sql&lt;/mssqls_linux_authent&gt;
&lt;mssqls_odbc_driver&gt;ODBC Driver 17 for SQL Server&lt;/mssqls_odbc_driver&gt;
&lt;mssqls_linux_odbc&gt;ODBC Driver 17 for SQL Server&lt;/mssqls_linux_odbc&gt;
        &lt;mssqls_uid&gt;sa&lt;/mssqls_uid&gt;
        &lt;mssqls_pass&gt;admin&lt;/mssqls_pass&gt;
&lt;mssqls_dbase&gt;tpcc3&lt;/mssqls_dbase&gt;
    &lt;/c3&gt;
&lt;/connections&gt;
&lt;sprocs&gt;
  &lt;neworder&gt;
&lt;connections&gt;c1 c2 c3&lt;/connections&gt;
    &lt;policy&gt;round_robin&lt;/policy&gt;
&lt;/neworder&gt;
    &lt;payment&gt;
&lt;connections&gt;c1 c2&lt;/connections&gt;
    &lt;policy&gt;first_named&lt;/policy&gt;
&lt;/payment&gt;
    &lt;delivery&gt;
&lt;connections&gt;c2 c3&lt;/connections&gt;
    &lt;policy&gt;last_named&lt;/policy&gt;
&lt;/delivery&gt;
    &lt;stocklevel&gt;
&lt;connections&gt;c1 c2 c3&lt;/connections&gt;
    &lt;policy&gt;random&lt;/policy&gt;
&lt;/stocklevel&gt;
    &lt;orderstatus&gt;
&lt;connections&gt;c2 c3&lt;/connections&gt;
    &lt;policy&gt;round_robin&lt;/policy&gt;
&lt;/orderstatus&gt;
&lt;/sprocs&gt;
&lt;/connpool&gt;
</programlisting>

        <para>After modifying the XML configuration file select XML Connect
        Pool in the Driver Options to activate this feature.</para>

        <figure>
          <title>XML Connect Pool</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15m.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>For this example the additional information for the comments is
        also added to illustrate the connections made.</para>

        <figure>
          <title>Connections Comment</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-15n.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>When the Virtual Users are run the logfile shows that
        connections are made for the active Virtual Users according to the
        connections and policies defined in the XML configuration file. Also
        prepared statements are created and held in a pool for execution
        against the defined policy. Also note that the standalone connection
        "tpcc1" is also made to monitor the transaction rates and define the
        warehouse count for the run.</para>

        <programlisting>Vuser 2:sproc_cur:neword_st connections:{odbcc1 odbcc2 odbcc3} cursors:::oo::Obj23::Stmt::3 ::oo::Obj28::Stmt::3 ::oo::Obj33::Stmt::3 number of cursors:3 execs:0
Vuser 2:sproc_cur:payment_st connections:{odbcc1 odbcc2} cursors:::oo::Obj23::Stmt::4 ::oo::Obj28::Stmt::4 number of cursors:2 execs:0
Vuser 2:sproc_cur:ostat_st connections:{odbcc2 odbcc3} cursors:::oo::Obj28::Stmt::5 ::oo::Obj33::Stmt::4 number of cursors:2 execs:0
Vuser 2:sproc_cur:delivery_st connections:{odbcc1 odbcc2 odbcc3} cursors:::oo::Obj23::Stmt::5 ::oo::Obj28::Stmt::6 ::oo::Obj33::Stmt::5 number of cursors:3 execs:0
Vuser 2:sproc_cur:slev_st connections:{odbcc2 odbcc3} cursors:::oo::Obj28::Stmt::7 ::oo::Obj33::Stmt::6 number of cursors:2 execs:0
Vuser 3:sproc_cur:neword_st connections:{odbcc1 odbcc2 odbcc3} cursors:::oo::Obj23::Stmt::3 ::oo::Obj28::Stmt::3 ::oo::Obj33::Stmt::3 number of cursors:3 execs:0
Vuser 3:sproc_cur:payment_st connections:{odbcc1 odbcc2} cursors:::oo::Obj23::Stmt::4 ::oo::Obj28::Stmt::4 number of cursors:2 execs:0
Vuser 3:sproc_cur:ostat_st connections:{odbcc2 odbcc3} cursors:::oo::Obj28::Stmt::5 ::oo::Obj33::Stmt::4 number of cursors:2 execs:0
Vuser 3:sproc_cur:delivery_st connections:{odbcc1 odbcc2 odbcc3} cursors:::oo::Obj23::Stmt::5 ::oo::Obj28::Stmt::6 ::oo::Obj33::Stmt::5 number of cursors:3 execs:0
Vuser 3:sproc_cur:slev_st connections:{odbcc2 odbcc3} cursors:::oo::Obj28::Stmt::7 ::oo::Obj33::Stmt::6 number of cursors:2 execs:0</programlisting>

        <para>On completion of the run the NOPM and TPM is recorded. This is
        the area where it is of particular importance to be aware of the
        database and cluster configuration for the results to be consistent.
        It is therefore valid to reiterate that if the cluster and standalone
        connection does not record all of the transactions in the cluster then
        the NOPM results will only be returned for the standalone connection.
        By way of example in the test configuration shown there are 3 separate
        databases and the standalone connection is made to tpcc1. Therefore
        the test results shows the NOPM value at approximately 1/3rd of the
        ratio expected against the TPM value that records all of the
        transactions against the SQL Server. For this reason the CLIENT SIDE
        TPM is also shown. In this example the neworder value per minute is
        78319 a close equivalent to 3 x 26207 and therefore gives an
        indication of the NOPM value for multiple instances in a non-cluster
        configuration. In this case 3 connections were made to tpcc1, tpcc2
        and tpcc3 and the connections chosen to round robin between them,
        therefore the actual number of NOPM is 3X that recorded from just the
        standalone connection. In a correctly configured cluster environment
        it would be the same and the results wouyld be both consistent and
        valid. Be aware that these client side values are recorded during both
        rampup and timed test periods and therefore may not accurately reflect
        the results from a valid timed test.</para>

        <programlisting>Vuser 1:2 Active Virtual Users configured
Vuser 1:TEST RESULT : System achieved 26207 NOPM from 180515 SQL Server TPM
Vuser 1:CLIENT SIDE TPM : neworder 78319 payment 78185 delivery 7855 stocklevel 7826 orderstatus 7809
</programlisting>

        <para>In addition to the CLIENT SIDE TPM each Virtual User will also
        report the total number of transactions that it processed from the
        time that it started running to the end of the test.</para>

        <programlisting>Vuser 2:VU2 processed neworder 275335 payment 273822 delivery 27495 stocklevel 27588 orderstatus 27568 transactions
Vuser 3:VU3 processed neworder 272901 payment 273475 delivery 27493 stocklevel 27194 orderstatus 27097 transactions
</programlisting>

        <para>The XML Connect Pool feature provides advanced features for the
        expert user to test clusters and multiple instances simultaneously, it
        also gives the user a high degree of control on how this is used,
        therefore it is at the users discretion to use these settings
        appropriately to ensure consistent results.</para>
      </section>
    </section>

    <section>
      <title>Additional Driver Script Options for Stored Procedures and Server
      Side Reports: PostgreSQL, MySQL, Oracle, Db2 and EnterpriseDB
      PostgreSQL</title>

      <section>
        <title>PostgreSQL Stored Procedures</title>

        <para>With PostgreSQL by default the 5 TPROC-C transactions are
        implemented using PostgreSQL functions. From PostgreSQL v11.0 there is
        the option to use PostgreSQL stored procedures instead. However
        prepared statements are not supported by PostgreSQL for stored
        procedures only for functions and therefore if using the XML connect
        pool feature only PostgreSQL functions are supported.</para>
      </section>

      <section>
        <title>MySQL Prepare Statements</title>

        <para>With MySQL there is the option to use server side prepared
        statements. This option is mandatory if using the XML connect pool
        feature.</para>
      </section>

      <section>
        <title>Oracle AWR Reports</title>

        <para>The Generation of Oracle AWR reports is built-in functionality
        with the Oracle Timed Test. At the end of the test HammerDB will
        report the snapshot numbers between which the report corresponds to
        the test.</para>
      </section>

      <section>
        <title>Db2 MONREPORT</title>

        <para>In the Db2 driver script options the Minutes for Test Duration
        is shown as monreportinterval in the Driver Script. This defines the
        period of time taken from the minutes for test duration that the
        monitoring user runs a monreport capture. The results are output at
        the end of the test and therefore selecting this option should be done
        in conjunction with the logfile enabled. While the MONREPORT is being
        captured the monitoring virtual user cannot bet terminated as control
        is handed over to the DB2 database and therefore shorter periods of
        report are optimal. In all cases in the MONREPORT interval specified
        is longer than the minutes for test duration then no MONREPORT will be
        captured.</para>
      </section>

      <section>
        <title>EnterpriseDB PostgreSQL DRITA</title>

        <para>If you have Enterprise DB installed and DRITA functionality
        enabled, by selecting this option HammerDB will automatically take
        DRITA snapshots for performance analysis of the workload between
        tests. For DRITA functionality to work you need the parameter
        timed_statistics = on set in your postgresql.conf file. With the test
        complete and the values you recorded if you selected the DRITA option
        you should next generate the DRITA report that corresponds to the
        reported SNAPIDs to show the PostgreSQL wait events, in the example
        below snapshots 2 and 3.</para>

        <programlisting>edb=# select * from sys_rpt(2,3,1000);
                                   sys_rpt                                   
-----------------------------------------------------------------------------
 WAIT NAME                                COUNT      WAIT TIME       % WAIT
 ---------------------------------------------------------------------------
 wal insert lock acquire                  1054357    2.300713        88.25
 xid gen lock acquire                     83471      0.195263        7.49
 db file read                             5523       0.067953        2.61
 buffer free list lock acquire            11133      0.029317        1.12
 query plan                               205        0.013703        0.53
 freespace lock acquire                   3          0.000007        0.00
 rel cache init lock acquire              0          0.000000        0.00
(9 rows)

edb=# 
</programlisting>
      </section>
    </section>

    <section>
      <title>Loading the Driver Script</title>

      <para>After selecting the Driver Script Options the Driver Script is
      loaded. The configured options can be seen in the Driver Script window
      and also modified directly there. The Load option can also be used to
      refresh the script to the configured Options.</para>

      <figure>
        <title>Driver Script Loaded</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-16.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section>
      <title>Configure Virtual Users</title>

      <para>Select Virtual User Options from the tree-view.</para>

      <figure>
        <title>Virtual User Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-17.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This displays the Virtual User Options dialog.</para>

      <figure>
        <title>Virtual User</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch4-18.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The values have the following meaning.</para>

      <para><table>
          <title>Virtual User Options</title>

          <tgroup cols="2">
            <thead>
              <row>
                <entry align="center">Option</entry>

                <entry align="center">Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Virtual Users</entry>

                <entry>The number of Virtual Users to create. Note that when
                running a Timed Workload HammerDB will automatically create an
                additional Virtual User to monitor the workload.</entry>
              </row>

              <row>
                <entry>User Delay(ms)</entry>

                <entry>User Delay(ms) defines the time to wait a Virtual User
                will wait behind the previous Virtual User before starting its
                test, this is to prevent a login storm with all Virtual Users
                attempting to login at the same time.</entry>
              </row>

              <row>
                <entry>Repeat Delay(ms)</entry>

                <entry>Repeat Delay(ms) is the time that each Virtual User
                will wait before running its next Iteration of the Driver
                Script. For the TPROC-C workload this should be considered as
                an 'outer loop' to the 'inner loop' of the Total Transactions
                per User in the TPROC-C Driver Script.</entry>
              </row>

              <row>
                <entry>Iterations</entry>

                <entry>Iterations is the number of times that the Driver
                Script is run in its entirety.</entry>
              </row>

              <row>
                <entry>Show Output</entry>

                <entry>Show Output will report Virtual User Output to the
                Virtual User Output Window, For TPROC-C tests this should be
                enabled.</entry>
              </row>

              <row>
                <entry>Log Output to Temp</entry>

                <entry>When enabled this appends all Virtual User Output to a
                text file in an available temp directory named
                hammerdb.log</entry>
              </row>

              <row>
                <entry>Use Unique Log Name</entry>

                <entry>Use a unique identifier for the Log Name.</entry>
              </row>

              <row>
                <entry>No Log Buffer</entry>

                <entry>By default text log output is buffered in memory before
                being written, this option writes the log output
                immediately.</entry>
              </row>

              <row>
                <entry>Log Timestamps</entry>

                <entry>Add an additional line of output with a timestamp every
                time that the log is written to.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>Select the Virtual User options, Press OK.</para>
    </section>

    <section>
      <title>Create and Run Virtual Users</title>

      <para>Double-click Create in the tree-view. The Virtual Users will be
      created and waiting in an idle status ready to run the Driver Script in
      the Script Editor Window. If you press Run instead it will both Create
      and Run the Virtual Users. If you have selected a Timed Workload the
      additional Virtual User created will be shown as a monitor.</para>

      <para><figure>
          <title>Virtual Users Create</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-19.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Double-click on Run and the Virtual Users will login to the target
      database and begin running their workload.</para>

      <para><figure>
          <title>Virtual Users Running</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-20.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>When complete the Monitor Virtual User will report the Test
      Result, refer to Chapter for the configuration of how the NOPM and TPM
      values are reported. If logging has been selected these values will also
      be reported in the log. Where supported additional database side server
      report information will also be reported.</para>

      <para><figure>
          <title>Virtual Users Complete</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch4-21.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>you may choose to run all of your performance tests manually in
      this way, however generating a performance profile is the key to
      successful database performance analysis requiring the running of a
      sequence of tests. Consequently HammerDB enables a way to automate the
      running of this sequence of tests with the Autopilot Feature.</para>
    </section>
  </chapter>

  <chapter>
    <title>Autopilot for Automated Testing</title>

    <para>To automate this process of repeated tests HammerDB provides the
    autopilot feature that enables you to configure a single test to be
    repeated by a different numbers of virtual users a number of times.
    Conceptually autopilot is best understood as having instructed a virtual
    DBA to manually repeat the test you have configured a number of times at a
    pre-determined time interval. That virtual DBA will then run the tests by
    ‘virtually’ pressing exactly the same buttons on the HammerDB interface
    that you would press as if running the test manually yourself. It is
    important to understand this concept as the most frequent user errors in
    using autopilot are as a result of not following this approach. Before
    running autopilot you should ensure that you have run a number of tests
    manually and your system is in an optimal configuration for running tests
    up to your planned maximum Virtual User count. For example you should
    enable enough space to schema growth throughout all of the tests you plan
    to run.</para>

    <section>
      <title>Configure and Run Autopilot</title>

      <para>To begin configuring Autopilot mode follow the steps described in
      the previous Chapter for Running OLTP Timed Tests before creating and
      running the Virtual Users, these will be configured automatically.
      Select Autopilot Options from the tree-view as shown.</para>

      <para><figure>
          <title>Autopilot Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch5-1.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>This shows the Autopilot Options Dialog.</para>

      <para><figure>
          <title>Autopilot Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch5-2.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Configure the Autopilot options in the same manner as you would
      use to instruct your Virtual DBA:</para>

      <table>
        <title>Autopilot Options</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Option</entry>

              <entry align="center">Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>Autopilot Disabled/Autopilot Enabled</entry>

              <entry>This Autopilot Disabled/Autopilot Enabled Radio buttons
              give you the option to select whether the Autopilot button is
              enabled on the main window.</entry>
            </row>

            <row>
              <entry>Minutes per Test in Virtual User Sequence</entry>

              <entry>The minutes for test duration defines the time interval
              between which your virtual DBA will create the Virtual Users,
              stop the test and create the next Virtual Users in the sequence.
              You should configure this value in relation to the Minutes for
              Ramup Time and Minutes for Test Duration given in the Timed Test
              options. For example if the values in the test script are 2 and
              5 minutes respectively then 10 minutes for the Autopilot Options
              is a good value to allow the test to complete before the next
              test in the sequence is run. If the test overruns the time
              interval and the Virtual Users are still running the sequence
              will wait for the Virtual Users to complete before proceeding
              however note any pending output will be discarded and therefore
              for example if the TPM and NOPM values have not been reported by
              the time the test is stopped they will not be reported at
              all.</entry>
            </row>

            <row>
              <entry>Virtual User Sequence (Space Separated Values)</entry>

              <entry>The Virtual User Sequence defines the number of Virtual
              Users to be configured in order for a sequence of tests
              separated by the Minutes for Test Duration. Note that for a
              Timed workload the Monitor Virtual User will be added and
              therefore the sequence defines the number of active worker
              Virtual Users. Therefore in this example the actual users
              running the workload will be 1, 2, 4, 8, 12, 16, 20 and 24
              however and additional one will be created.</entry>
            </row>

            <row>
              <entry>Virtual User Options</entry>

              <entry>These values are exactly the same as set when defining
              the Virtual User Options, you should ensure that Output is
              enabled and configure preferred logging options.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>Double-click on the Autopilot Icon to begin running the sequence
      of tests</para>

      <figure>
        <title>Run Autopilot</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch5-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The Autopilot Window is shown tracking the Monitor Virtual User
      output and the time interval, no further interaction is required.</para>

      <figure>
        <title>Autopilot Running</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch5-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>After the first test HammerDB reports the output and then
      configures the Virtual Users and runs the second test
      automatically.</para>

      <figure>
        <title>Autopilot Continuing</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch5-5.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When the sequence is complete you will see the message Autopilot
      Sequence ended. You can now gather all of your test results.</para>

      <para><figure>
          <title>Autopilot Complete</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch5-6.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>
    </section>

    <section>
      <title>Autopilot Troubleshooting</title>

      <para>The most Frequent Autopilot Configuration Error is caused by
      configuring the Autopilot Time Interval to be less than the combined
      rampup and duration time of the test that is running. When viewed from
      the concept of a "Virtual DBA" this User has been instructed to press
      the Stop button before the test has ended, consequently a warning is
      produced and no output results are reported. To resolve this issue
      ensure that the time interval is set long enough to allow the configured
      tests to complete inside this interval.</para>

      <para><figure>
          <title>Autopilot Error</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch5-7.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>
    </section>

    <section>
      <title>Extending Autopilot to start automatically</title>

      <para>Autopilot can be started automatically by adding the keyword
      “auto” followed by the name of a script to run, this script must end in
      the extension .tcl.</para>

      <programlisting>./hammerdb auto
Usage: hammerdb [ auto [ script_to_autoload.tcl  ] ]
</programlisting>

      <para>For example</para>

      <programlisting>./hammerdb auto newtpccscript.tcl</programlisting>

      <para>On doing so HammerDB will now load the script newtpccscript.tcl at
      startup and immediately enter the autopilot sequence defined in
      config.xml. Upon completion HammerDB will exit. This functionality
      enables the potential to run scripted workloads with the HammerDB GUI
      such as the following with multiple sequences of autopilot interspersed
      with a database refresh.</para>

      <programlisting>#!/bin/bash

set -e
SEQ1="4 6 8 10"
SEQ2="12 14 16 18"
SEQ3="20 22 24 26"
CONFIGFILE='/usr/local/hammerDB/config.xml'
RUNS=6

for x in $(eval echo "{1..$RUNS}")
do
        # Running a number of passes for this autopilot sequence
        echo "running run $x of $RUNS"

        for s in "$SEQ1" "$SEQ2" "$SEQ3"
        do
                echo "Running tests for series: $s"
                sed -i "s/&lt;autopilot_sequence&gt;.*&lt;\/autopilot_sequence&gt;/&lt;autopilot_sequence&gt;${s}&lt;\/autopilot_sequence&gt;/" $CONFIGFILE

                (cd /usr/local/hammerDB/ &amp;&amp; ./hammerdb auto TPCC.postgres.tcl)

                echo "Reloading data"
                ssh postgres@postgres  '/var/lib/pgsql/reloadData.sh'
        done
done
</programlisting>
    </section>
  </chapter>

  <chapter>
    <title>Transactions</title>

    <para>HammerDB includes a Transaction Counter that logs into the target
    database and samples the transaction rate displaying it in graph format to
    view the TPM of a test in real time. Note that the TPM value is displayed
    as opposed to the NOPM value as TPM is selected from a database in-memory
    table and therefore sampling does not impact the test being measured. NOPM
    on the other hand is sampled from the schema itself and is therefore only
    measured at the start and end of the test to minimize the impact of
    testing upon performance. To configure the Transaction Counter select the
    Transactions tree-view. If Virtual Users are running the Transaction
    Counter Options can be selected from the menu.</para>

    <figure>
      <title>Transaction Counter Options</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="docs/images/ch6-1.PNG"/>
        </imageobject>
      </mediaobject>
    </figure>

    <section>
      <title>Oracle Transaction Counter</title>

      <para>For Oracle the connection parameters are the same as the schema
      options. There is also an option to query a TimesTen database instead of
      an Oracle one and to select transactions from an Oracle RAC cluster. The
      refresh rate determines the sampling interval.</para>

      <figure>
        <title>Oracle TX Counter Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>For single instance Oracle, transactions are sampled with the
      following statement. This displays transactions with the same value as
      used in Oracle Enterprise Manager and in Oracle AWR reports.</para>

      <programlisting>select sum(value) from v$sysstat where name = 'user commits' or name = 'user rollbacks'</programlisting>

      <para>For Oracle RAC gv$sysstat is queried for global
      transactions.</para>

      <programlisting>select sum(value) from gv$sysstat where name = 'user commits' or name = 'user rollbacks'</programlisting>

      <para>for TimesTen the following SQL is used.</para>

      <programlisting>select (xact_commits + xact_rollbacks) from sys.monitor</programlisting>
    </section>

    <section>
      <title>SQL Server Transaction Counter</title>

      <para>For SQL Server the connection parameters are the same as the
      schema options. The refresh rate determines the sampling
      interval.</para>

      <para/>

      <figure>
        <title>SQL Server TX Counter Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The following SQL is used to sample the transaction rate
      displaying the same value as can be seen in the Activity Monitor in
      SSMS.</para>

      <programlisting>select cntr_value from sys.dm_os_performance_counters where counter_name = 'Batch Requests/sec'</programlisting>
    </section>

    <section>
      <title>Db2 Transaction Counter</title>

      <para>For Db2 the connection parameters are the same as the schema
      options. The refresh rate determines the sampling interval.</para>

      <figure>
        <title>Db2 TX Counter Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The following SQL is used to sample the transaction rate.</para>

      <programlisting>select total_app_commits + total_app_rollbacks from sysibmadm.mon_db_summary</programlisting>
    </section>

    <section>
      <title>MySQL Transaction Counter</title>

      <para>For MySQL the connection parameters are the same as the schema
      options. The refresh rate determines the sampling interval.</para>

      <figure>
        <title>MySQL TX Counter Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-5.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The following SQL is used to sample the transaction rate.</para>

      <programlisting>show global status where Variable_name = 'Com_commit' or Variable_name =  'Com_rollback'</programlisting>

      <para>Note that Com_commit is used instead of the handler_commit value
      used in previous releases of HammerDB as a result of MySQL Bug #52453
      handler_commit is incremented for InnoDB SELECT queries.</para>
    </section>

    <section>
      <title>PostgreSQL Transaction Counter</title>

      <para>For PostgreSQL the connection parameters are the same as the
      schema options. The refresh rate determines the sampling
      interval.</para>

      <figure>
        <title>PostgreSQL TX Counter Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-6.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The following SQL is used to sample the transaction rate.</para>

      <programlisting>select sum(xact_commit + xact_rollback) from pg_stat_database</programlisting>
    </section>

    <section>
      <title>Running the Transaction Counter</title>

      <para>During a test, select the start transaction counter button.</para>

      <figure>
        <title>Start Transaction Counter</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-8.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>On starting the transaction counter will begin sampling the
      transaction data.</para>

      <figure>
        <title>Transaction Counter Starting</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-9.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The transaction counter will be displayed and continually sample
      and display the transaction rate during the test. It is important to
      note that the transaction rate is sampled with the SQL detailed above
      for the database selected and therefore all transactions on the database
      are sampled whether from HammerDB or another application running at the
      same time. Similarly if 2 or more instances of HammerDB are run against
      the same database at the same time, the cumulative transaction is
      sampled.</para>

      <figure>
        <title>Transaction Counter Running</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-10.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>While active the Transaction Counter Window can be dragged out of
      the main HammerDB display to be displayed in an standalone window by
      selecting and dragging the notebook tab. To return to the main display
      close the window and it will be re-embedded in the main
      interface.</para>

      <figure>
        <title>Transaction Counter standalone.</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch6-11.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </chapter>

  <chapter>
    <title>CPU and Database Metrics</title>

    <para>By default HammerDB metrics displays the CPU utilisation per core
    across the target system. HammerDB has also introduced a database metrics
    display initially for the Oracle Database. HammerDB Metrics uses an agent
    and display configuration meaning that the agent must be installed on the
    SUT. This can be accomplished by installing HammerDB on the SUT as well as
    the server. On Linux the sysstat package must be pre-installed where the
    agent is running.</para>

    <programlisting>$ mpstat -V
sysstat version 11.5.7
(C) Sebastien Godard (sysstat &lt;at&gt; orange.fr</programlisting>

    <para>On Windows a version of mpstat is included with HammerDB.</para>

    <section>
      <title>Start the Agent</title>

      <para>To start the agent on Linux run the agent program locally in the
      agent directory.</para>

      <programlisting>$./agent 
Initializing HammerDB Metric Agent 4.0
HammerDB Metric Agent active @ id 20376 hostname CRANE (Ctrl-C to Exit)</programlisting>

      <para>On Windows double-click on agent.bat in the agent
      directory.</para>

      <figure>
        <title>agent.bat</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-1.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>On both Windows and Linux your Firewall configuration should
      permit communication between the hosts where the agent and the display
      are running, for example on Windows you may see the following security
      alert as the agent will open a port for communication, access needs to
      be permitted to enable communication.</para>

      <figure>
        <title>Security Alert</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>A window will open indicating the id that the agent is listening
      on. Pressing Ctrl-C or closing the window will close the agent.</para>

      <figure>
        <title>Windows agent</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section>
      <title>Configure Metrics</title>

      <para>In HammerDB select Metrics Options</para>

      <figure>
        <title>Metrics Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Enter the id and canonical hostname of the agent and press
      OK.</para>

      <figure>
        <title>Agent Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-5.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Double-click on Display</para>

      <figure>
        <title>Display</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-6.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>the agent will report the connection of the display</para>

      <figure>
        <title>Agent connected</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-7.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>and the display will report the connection information of the
      agent</para>

      <para><figure>
          <title>Display connected</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch7-8.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>
    </section>

    <section>
      <title>Monitor Metrics</title>

      <para>The display will now report the CPU utilisation per core on the
      SUT during a workload with user CPU utilisation shown in green and
      system utilisation shown in red. This per core about is particularly
      useful for diagnosing database workload issues where the load is not
      evenly distributed across all cores. A typical example is where all of
      the network interrupt handling is done on the first core, this will be
      evident from the HammerDB CPU metrics showing the first core at 100%
      system utilisation.</para>

      <para>The agent to display configuration is compatible to run
      interchangeably between Linux and Windows with both the agent and
      display on either of the operating systems. Additionally the agent may
      be run to display the CPU metrics whilst the load is run from the
      command line or another system.</para>

      <figure>
        <title>Metrics running</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-9.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>As with the transaction counter the Metrics display can be dragged
      out of the main window for separate viewing and the scrollbar used for
      reviewing large core counts.</para>

      <figure>
        <title>Large Core count</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-10.png"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>If the agent or display is closed the corresponding connection
      will also close and wait for a new connection. The Metrics Display can
      be closed by pressing the corresponding stop button.</para>
    </section>

    <section>
      <title>Oracle Database Metrics</title>

      <para>When the Oracle Database is selected on both Windows and Linux an
      additional option is available to connect to the Oracle Database and
      display detailed performance metrics.</para>

      <figure>
        <title>Oracle Metrics Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-11.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When the metrics button is pressed HammerDB connects to the
      database and displays graphical information from the Active Session
      History detailing wait events. By default in embedded mode the Oracle
      Database Metrics will display the Active Session History Graph. For
      detailed Oracle Database Metrics the Notebook tab should be dragged out
      and expanded to display in a separate window.</para>

      <figure>
        <title>Oracle Metrics Display Linux</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-12.png"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When display in a separate window, it is possible to make a
      selection from the window and display the wait events related to that
      period of time. When the SQL_ID is selected the buttons then enable the
      detailed viewing of SQL text, the explain plan, IO statistics and SQL
      statistics related to that SQL.</para>

      <para><figure>
          <title>Oracle Metrics Display Windows</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch7-13.png"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>When an event is selected the analysis shows details related to
      that particular event.</para>

      <figure>
        <title>Oracle Metrics Event</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-14.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The CPU Metrics button displays the current standard HammerDB CPU
      Metrics display in an embedded Window and requires the agent running on
      the database server. The CPU metrics are not recorded as historical data
      relating to the Active Session History.</para>

      <figure>
        <title>Oracle Database CPU Metrics</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch7-15.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </chapter>

  <chapter>
    <title>Remote Primary and Replica Modes</title>

    <para>HammerDB allows for multiple instances of the HammerDB program to
    run in Primary and Replica modes. Running with multiple modes enables the
    additional instances to be controlled by a single master instance either
    on the same load testing server or across the network. This functionality
    can be particularly applicable when testing Virtualized environments and
    the desire is to test multiple databases running in virtualized guests at
    the same time. Similarly this functionality is useful for clustered
    databases with multiple instances such as Oracle Real Application Clusters
    and wishing to partition a load precisely across servers. HammerDB Remote
    Modes are entirely operating system independent and therefore an instance
    of HammerDB running on Windows can be Primary to one or more instances
    running on Linux and vice versa. Additionally there is no requirement for
    the workload to be the same and therefore it would be possible to connect
    multiple instances of HammerDB running on Windows and Linux simultaneously
    testing SQL Server, Oracle, MySQL and PostrgreSQL workloads in a
    virtualized environment. In the bottom right hand corner of the interface
    the status bar shows the mode that HammerDB is running in. By default this
    will be Local Mode.</para>

    <figure>
      <title>Mode</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="docs/images/ch11-1.PNG"/>
        </imageobject>
      </mediaobject>
    </figure>

    <sect1>
      <title>Primary Mode</title>

      <para>From the tree-view select Mode Options.</para>

      <figure>
        <title>Mode Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This displays the Mode Options as shown in Figure 3 confirming
      that the current mode is Local.</para>

      <figure>
        <title>Mode Options Select</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Select Primary Mode and click OK.</para>

      <figure>
        <title>Primary Mode Select</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-6.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Confirm the selection.</para>

      <figure>
        <title>Mode Confirmation</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This will show that Master Mode is now active and the ID and
      hostname it is running on.</para>

      <para><figure>
          <title>Mode Active</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch11-5.PNG"/>
            </imageobject>
          </mediaobject>
        </figure> Note that this will also be recorded in the console display
      and the current Mode displayed in the status bar at the bottom right of
      the Window.</para>

      <programlisting>Setting Primary Mode at id : 18808, hostname : osprey</programlisting>
    </sect1>

    <sect1>
      <title>Replica Mode</title>

      <para>On another instance of HammerDB select Replica Mode, enter the id
      and hostname of the Primary and select OK.</para>

      <para><figure>
          <title>Replica Mode</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch11-7.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Confirm the change and observe the Mode connection on both the
      Replica</para>

      <programlisting>Setting Replica Mode at id : 18424, hostname : osprey
Replica connecting to osprey 18808 : Connection succeeded
Primary call back successful</programlisting>

      <para>and the Primary. There is no restriction on the number of Replicas
      that can be connected to one Primary.</para>

      <programlisting>Received a new replica connection from host fe80::9042:505b:49de:beb4%26
New replica joined : {18424 osprey}</programlisting>
    </sect1>

    <sect1>
      <title>Primary Distribution</title>

      <para>The Primary Distribution button in the edit menu now becomes
      active to distribute scripts across instances.</para>

      <figure>
        <title>Primary Distribution</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-8.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Pressing this button enables the distribution of the contents of
      the Script Editor to all connected instances.</para>

      <programlisting>Distributing to 18424 osprey ...Primary Distribution Succeeded</programlisting>

      <para>The TPROC-C timed driver scripts reference the operating Mode and
      when loaded will set the parameter "mode" to the operating Mode running
      on that system.</para>

      <para>If loaded locally a script will show the Mode that the instance of
      HammerDB is running in which by default will be "Local".</para>

      <programlisting>set mode "Local" ;# HammerDB operational mode</programlisting>

      <para>Once the Mode is set to "Primary" when the script is loaded on the
      Primary it will show the correct mode.</para>

      <programlisting>set mode "Primary" ;# HammerDB operational mode</programlisting>

      <para>When distributed from the Primary to the Replica the Replica will
      change the mode to the correct setting.</para>

      <programlisting>set mode "Replica" ;# HammerDB operational mode</programlisting>

      <para>Once a Replica is connected to a Primary all actions that are
      taken on the Primary will be replicated on the Replica. All of your
      workload choices of creating and running and closing down virtual users
      will be replicated automatically on the connected Replicas enabling
      control and simultaneous timing from a central point. This enables
      workloads to be directed to different database instances simultaneously.
      When operating in Replica Mode the Monitor Virtual User on that instance
      of HammerDB will not capture any performance data and report that "No
      snapshots are taken", the Replica will only run the active Virtual
      Users. Note that running a schema creation with multiple connected
      instances is not supported.</para>

      <figure>
        <title>Operating in Replica Mode</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-9.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When the workload is complete the Primary will terminate the
      Virtual Users on the Replicas meaning that running in Remote Mode
      configurations is compatible with Autopilot.</para>

      <figure>
        <title>Replica Mode terminated</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch11-10.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>If it is wished to capture the performance metrics on the Replica
      as well as the Primary the operational mode can be manually changed to
      "Local". In this case the Replicas will capture performance data from
      the databases instances that they are connected to.</para>

      <programlisting>set mode "Local" ;# HammerDB operational mode</programlisting>

      <para>To disable Remote Modes select Local Mode on the Primary on
      confirmation all connected instances will return to Local Mode.</para>

      <para>Remote modes functionality in the CLI can be accessed using the
      switchmode command with the GUI and CLI being interchangeable and
      therefore a number of CLI Replicas can be connected to a GUI Primary if
      desired.</para>
    </sect1>
  </chapter>

  <chapter>
    <title>Command Line Interface (CLI)</title>

    <para>HammerDB can be run from the command line without a graphical
    interface. It is recommend that new users become familiar with using the
    graphical interface before using the command line as the command line
    offers the same workflow and therefore once the graphical interface is
    understood learning the command line will be more straightforward. The CLI
    implements equivalent readline functionality for navigation. The CLI can
    be used in conjunction with scripting to build a powerful automated
    environment. Both the CLI and the GUI run exactly the same commands
    underneath the interactive layers, for example when operational the
    Virtual Users run identical workloads and therefore performance
    measurements between the CLI and GUI are interchangeable.</para>

    <section>
      <title>Start the CLI</title>

      <para>To start the command line in interactive mode on Linux run:</para>

      <programlisting>steve@CRANE:~/HammerDB-4.0$ ./hammerdbcli 
HammerDB CLI v4.0
Copyright (C) 2003-2020 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
hammerdb&gt;</programlisting>

      <para>On Windows double-click hammerdbcli.bat</para>

      <figure>
        <title>hammerdbcli.bat</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch8-1.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This will display a console command Window. On Windows this
      console command window has been designed to run with white text on a
      black background and sets the colour scheme accordingly.</para>

      <figure>
        <title>CLI Windows</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch8-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section>
      <title>CLI Commands</title>

      <para>To learn CLI commands type "help".</para>

      <programlisting>HammerDB CLI v4.0
Copyright (C) 2003-2020 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
hammerdb&gt;help
HammerDB v4.0 CLI Help Index

Type "help command" for more details on specific commands below

        buildschema
        clearscript
        customscript
        datagenrun
        dbset
        dgset
        diset
        distributescript
        librarycheck
        loadscript
        print
        quit
        runtimer
        switchmode
        vucomplete
        vucreate
        vudestroy
        vurun
        vuset
        vustatus
        waittocomplete

hammerdb&gt;
</programlisting>

      <para>The commands have the following functionality.</para>

      <para><table>
          <title>CLI commands</title>

          <tgroup cols="3">
            <colspec colwidth="297*"/>

            <colspec colwidth="300*"/>

            <colspec colwidth="403*"/>

            <thead>
              <row>
                <entry align="center">Command</entry>

                <entry align="center">Usage</entry>

                <entry align="center">Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>buildschema</entry>

                <entry>Usage: buildschema</entry>

                <entry>Runs the schema build for the database and benchmark
                selected with dbset and variables selected with diset.
                Equivalent to the Build command in the graphical interface.
                Note that the buildschema command will assume the "yes" reply
                to the Yes or no prompt to proceed with the schema build. This
                is to prevent the stalling of CLI scripts during
                builds.</entry>
              </row>

              <row>
                <entry>clearscript</entry>

                <entry>Usage: clearscript</entry>

                <entry>Clears the script. Equivalent to the "Clear the Screen"
                button in the graphical interface.</entry>
              </row>

              <row>
                <entry>customscript</entry>

                <entry>Usage: customscript scriptname.tcl</entry>

                <entry>Load an external script. Equivalent to the "Open
                Existing File" button in the graphical interface.</entry>
              </row>

              <row>
                <entry>datagenrun</entry>

                <entry>Usage: datagenrun</entry>

                <entry>Run Data Generation. Equivalent to the Generate option
                in the graphical interface.</entry>
              </row>

              <row>
                <entry>dbset</entry>

                <entry>Usage: dbset [db|bm] value</entry>

                <entry>Sets the database (db) or benchmark (bm). Equivalent to
                the Benchmark Menu in the graphical interface. Database value
                is set by the database prefix in the XML
                configuration.</entry>
              </row>

              <row>
                <entry>dgset</entry>

                <entry>Usage: dgset [vu|ware|directory]</entry>

                <entry>Set the Datagen options. Equivalent to the Datagen
                Options dialog in the graphical interface.</entry>
              </row>

              <row>
                <entry>diset</entry>

                <entry>Usage: diset dict key value</entry>

                <entry>Set the dictionary variables for the current database.
                Equivalent to the Schema Build and Driver Options windows in
                the graphical interface. Use "print dict" to see what these
                variables area and diset to change: Example: hammerdb&gt;diset
                tpcc count_ware 10 Changed tpcc:count_ware from 1 to 10 for
                Oracle.</entry>
              </row>

              <row>
                <entry>distributescript</entry>

                <entry>Usage: distributescript</entry>

                <entry>In Master mode distributes the script loaded by Master
                to the connected Slaves.</entry>
              </row>

              <row>
                <entry>librarycheck</entry>

                <entry>Usage: librarycheck</entry>

                <entry>Attempts to load the vendor provided 3rd party library
                for all databases and reports whether the attempt was
                successful.</entry>
              </row>

              <row>
                <entry>loadscript</entry>

                <entry>Usage: loadscript</entry>

                <entry>Load the script for the database and benchmark set with
                dbset and the dictionary variables set with diset. Use "print
                script" to see the script that is loaded. Equivalent to
                loading a Driver Script in the Script Editor window in the
                graphical interface.</entry>
              </row>

              <row>
                <entry>print</entry>

                <entry>Usage: print [db|bm|dict|script|vuconf
                |vucreated|vustatus|datagen]</entry>

                <entry>prints the current configuration: db: database bm:
                benchmark dict: the dictionary for the current database ie all
                active variables script: the loaded script vuconf: the virtual
                user configuration vucreated: the number of virtual users
                created vustatus: the status of the virtual users datagen :
                the configuration to build when datagen is run</entry>
              </row>

              <row>
                <entry>quit</entry>

                <entry>Usage: quit Shuts down the HammerDB CLI.</entry>

                <entry>Calls the exit command and terminates the CLI
                interface</entry>
              </row>

              <row>
                <entry>runtimer</entry>

                <entry>runtimer - Usage: runtimer seconds</entry>

                <entry>Helper routine to run a timer in the main hammerdbcli
                thread to keep it busy for a period of time whilst the virtual
                users run a workload. The timer will return when vucomplete
                returns true or the timer reaches the seconds value. Usually
                followed by vudestroy.</entry>
              </row>

              <row>
                <entry>switchmode</entry>

                <entry>Usage: switchmode [mode] ?PrimaryID?
                ?PrimaryHostname?</entry>

                <entry>Changes the remote mode to Primary, Replica or Local.
                When Master it will report an id and a hostname. Equivalent to
                the Mode option in the graphical interface. Mode to switch to
                must be one of Local, Primary or Replica. If Mode is Replica
                then the ID and Hostname of the Primary to connect to must be
                given.</entry>
              </row>

              <row>
                <entry>vucomplete</entry>

                <entry>Usage: vucomplete</entry>

                <entry>Returns "true" or "false" depending on whether all
                virtual users that started a workload have completed
                regardless of whether the status was "FINISH SUCCESS" or
                "FINISH FAILED".</entry>
              </row>

              <row>
                <entry>vucreate</entry>

                <entry>Usage: vucreate</entry>

                <entry>Create the virtual users. Equivalent to the Virtual
                User Create option in the graphical interface. Use "print
                vucreated" to see the number created, vustatus to see the
                status and vucomplete to see whether all active virtual users
                have finished the workload. A script must be loaded before
                virtual users can be created.</entry>
              </row>

              <row>
                <entry>vudestroy</entry>

                <entry>Usage: vudestroy</entry>

                <entry>Destroy the virtual users. Equivalent to the Destroy
                Virtual Users button in the graphical interface that replaces
                the Create Virtual Users button after virtual user
                creation.</entry>
              </row>

              <row>
                <entry>vurun</entry>

                <entry>Usage: vurun</entry>

                <entry>Send the loaded script to the created virtual users for
                execution. Equivalent to the Run command in the graphical
                interface.</entry>
              </row>

              <row>
                <entry>vuset</entry>

                <entry>Usage: vuset [vu|delay|repeat|iterations|showoutput
                |logtotemp|unique|nobuff|timestamps</entry>

                <entry>Configure the virtual user options. Equivalent to the
                Virtual User Options window in the graphical
                interface.</entry>
              </row>

              <row>
                <entry>vustatus</entry>

                <entry>Usage: vustatus</entry>

                <entry>Show the status of virtual users. Status will be "WAIT
                IDLE" for virtual users that are created but not running a
                workload,"RUNNING" for virtual users that are running a
                workload, "FINISH SUCCESS" for virtual users that completed
                successfully or "FINISH FAILED" for virtual users that
                encountered an error.</entry>
              </row>

              <row>
                <entry>waittocomplete</entry>

                <entry>Usage: waittocomplete</entry>

                <entry>Helper routine to enable the main hammerdbcli thread to
                keep it busy until vucomplete is detected. When vucomplete is
                detected exit is called causing all virtual users and the main
                hammerdblci thread to terminate. Often used when calling
                hammerdb from external scripting commands.</entry>
              </row>
            </tbody>
          </tgroup>
        </table></para>
    </section>

    <section>
      <title>Configure Schema Build</title>

      <para>Use the dbset command to choose a database and benchmark. For the
      database the database prefix shown in the XML configuration is used. IIf
      an incorrect database is selected the available values are
      prompted.</para>

      <programlisting>hammerdb&gt;dbset db orac
Unknown prefix orac, choose one from ora mssqls db2 mysql pg</programlisting>

      <para>When a valid option is chosen the database is set.</para>

      <programlisting>hammerdb&gt;dbset db mssqls
Database set to MSSQLServer</programlisting>

      <para>The print command can be used to confirm the chosen database and
      available options.</para>

      <programlisting>hammerdb&gt;print db
Database MSSQLServer set.
To change do: dbset db prefix, one of:
Oracle = ora MSSQLServer = mssqls Db2 = db2 MySQL = mysql PostgreSQL = pg </programlisting>

      <para>Similarly the workload is also selected from the available
      configuration also prompting if an incorrect value is chosen. When a
      correct value is chosen the selection is confirmed. For backward
      compatibility with existing scripts TPROC-C and TPC-C and TPROC-H and
      TPC-H are interchangeable.</para>

      <programlisting>hammerdb&gt;dbset bm TPROC-H
Benchmark set to TPROC-H for MSSQLServer

hammerdb&gt;dbset bm TPC-C
Benchmark set to TPC-C for MSSQLServer

hammerdb&gt;print bm
Benchmark set to TPC-C</programlisting>

      <para>After the database and workload is selected the print dict command
      lists all of the available configuration variables for that
      database.</para>

      <para><programlisting>hammerdb&gt;print dict
Dictionary Settings for MSSQLServer
connection {
 mssqls_server         = (local)
 mssqls_linux_server   = localhost
 mssqls_tcp            = false
 mssqls_port           = 1433
 mssqls_azure          = false
 mssqls_authentication = windows
 mssqls_linux_authent  = sql
 mssqls_odbc_driver    = ODBC Driver 17 for SQL Server
 mssqls_linux_odbc     = ODBC Driver 17 for SQL Server
 mssqls_uid            = sa
 mssqls_pass           = admin
}
tpcc       {
 mssqls_count_ware       = 1
 mssqls_num_vu           = 1
 mssqls_dbase            = tpcc
 mssqls_imdb             = false
 mssqls_bucket           = 1
 mssqls_durability       = SCHEMA_AND_DATA
 mssqls_total_iterations = 1000000
 mssqls_raiseerror       = false
 mssqls_keyandthink      = false
 mssqls_checkpoint       = false
 mssqls_driver           = test
 mssqls_rampup           = 2
 mssqls_duration         = 5
 mssqls_allwarehouse     = false
 mssqls_timeprofile      = false
 mssqls_async_scale      = false
 mssqls_async_client     = 10
 mssqls_async_verbose    = false
 mssqls_async_delay      = 1000
 mssqls_connect_pool     = false
}
</programlisting>Use the diset command to change these values for example for
      the number of warehouses to build.</para>

      <programlisting>hammerdb&gt;diset tpcc mssqls_count_ware 10
Changed tpcc:mssqls_count_ware from 1 to 10 for MSSQLServer</programlisting>

      <para>and the number of virtual users to build them.</para>

      <programlisting>hammerdb&gt;diset tpcc mssqls_num_vu 4
Changed tpcc:mssqls_num_vu from 1 to 4 for MSSQLServer</programlisting>

      <para>If the dict value to be set has a special character using curly
      brackets around the value will prevent the interpretation of the special
      character.</para>

      <programlisting>hammerdb&gt;diset connection mssqls_server {(local)\SQLDEVELOP}
Changed connection:mssqls_server from (local) to (local)\SQLDEVELOP for MSSQLServer</programlisting>

      <para>print dict will show the changed values.</para>

      <programlisting>hammerdb&gt;print dict
Dictionary Settings for MSSQLServer
connection {
 mssqls_server         = (local)\SQLDEVELOP
 mssqls_linux_server   = localhost
 mssqls_tcp            = false
 mssqls_port           = 1433
 mssqls_azure          = false
 mssqls_authentication = windows
 mssqls_linux_authent  = sql
 mssqls_odbc_driver    = ODBC Driver 17 for SQL Server
 mssqls_linux_odbc     = ODBC Driver 17 for SQL Server
 mssqls_uid            = sa
 mssqls_pass           = admin
}
tpcc       {
 mssqls_count_ware       = 10
 mssqls_num_vu           = 4
 mssqls_dbase            = tpcc
 mssqls_imdb             = false
 mssqls_bucket           = 1
 mssqls_durability       = SCHEMA_AND_DATA
 mssqls_total_iterations = 1000000
 mssqls_raiseerror       = false
 mssqls_keyandthink      = false
 mssqls_checkpoint       = false
 mssqls_driver           = test
 mssqls_rampup           = 2
 mssqls_duration         = 5
 mssqls_allwarehouse     = false
 mssqls_timeprofile      = false
 mssqls_async_scale      = false
 mssqls_async_client     = 10
 mssqls_async_verbose    = false
 mssqls_async_delay      = 1000
 mssqls_connect_pool     = false
}</programlisting>
    </section>

    <section>
      <title>Building the Schema</title>

      <para>Run the buildschema command and the build will commence without
      prompting using your configuration and if successful report the status
      at the end of the build. Note that exactly as the GUI the build is
      multithreaded with Virtual Users running simultaneously.</para>

      <programlisting>hhammerdb&gt;buildschema
Script cleared
Building 10 Warehouses with 5 Virtual Users, 4 active + 1 Monitor VU(dict value mssqls_num_vu is set to 4)
Ready to create a 10 Warehouse MS SQL Server TPROC-C schema
in host (LOCAL)\SQLDEVELOP in database TPCC?
Enter yes or no: replied yes
Vuser 1 created - WAIT IDLE
Vuser 2 created - WAIT IDLE
Vuser 3 created - WAIT IDLE
Vuser 4 created - WAIT IDLE
Vuser 5 created - WAIT IDLE
Vuser 1:RUNNING
Vuser 1:Monitor Thread
Vuser 1:CREATING TPCC SCHEMA
Vuser 1:CHECKING IF DATABASE tpcc EXISTS
Vuser 1:CREATING DATABASE tpcc
Vuser 1:CREATING TPCC TABLES
Vuser 1:Loading Item
Vuser 2:RUNNING
Vuser 2:Worker Thread
Vuser 2:Waiting for Monitor Thread...
Vuser 2:Loading 2 Warehouses start:1 end:2
Vuser 2:Start:Thu Oct 22 17:56:27 BST 2020
Vuser 2:Loading Warehouse
Vuser 2:Loading Stock Wid=1
Vuser 3:RUNNING
Vuser 3:Worker Thread
Vuser 3:Waiting for Monitor Thread...
Vuser 3:Loading 2 Warehouses start:3 end:4
Vuser 3:Start:Thu Oct 22 17:56:27 BST 2020
Vuser 3:Loading Warehouse
Vuser 3:Loading Stock Wid=3
Vuser 4:RUNNING
Vuser 4:Worker Thread
Vuser 4:Waiting for Monitor Thread...
Vuser 4:Loading 2 Warehouses start:5 end:6
Vuser 4:Start:Thu Oct 22 17:56:28 BST 2020
Vuser 4:Loading Warehouse
Vuser 4:Loading Stock Wid=5
Vuser 5:RUNNING
Vuser 5:Worker Thread
Vuser 5:Waiting for Monitor Thread...
Vuser 5:Loading 2 Warehouses start:7 end:10
Vuser 5:Start:Thu Oct 22 17:56:28 BST 2020
Vuser 5:Loading Warehouse
Vuser 5:Loading Stock Wid=7

.....

Vuser 5:Loading Orders for D=10 W=10
Vuser 5:...1000
Vuser 5:...2000
Vuser 5:...3000
Vuser 5:Orders Done
Vuser 5:End:Thu Oct 22 18:02:45 BST 2020
Vuser 5:FINISHED SUCCESS
Vuser 1:Workers: 0 Active 4 Done
Vuser 1:CREATING TPCC INDEXES
Vuser 1:CREATING TPCC STORED PROCEDURES
Vuser 1:UPDATING SCHEMA STATISTICS
Vuser 1:TPCC SCHEMA COMPLETE
Vuser 1:FINISHED SUCCESS
ALL VIRTUAL USERS COMPLETE

hammerdb&gt;
</programlisting>

      <para>The vustatus command can confirm the status of each Virtual
      User.</para>

      <programlisting>hammerdb&gt;vustatus
1 = FINISH SUCCESS
2 = FINISH SUCCESS
3 = FINISH SUCCESS
4 = FINISH SUCCESS
5 = FINISH SUCCESS</programlisting>

      <para>When the build is complete destroy the Virtual Users and confirm
      the status.</para>

      <programlisting>hammerdb&gt;vudestroy
Destroying Virtual Users
Virtual Users Destroyed

hammerdb&gt;vustatus
No Virtual Users found</programlisting>
    </section>

    <section>
      <title>Configure Driver</title>

      <para>Set the type of workload to run. A timed workload with suppressed
      output is strongly recommended as a test workload will print
      considerable output to the command prompt.</para>

      <programlisting>hammerdb&gt;diset tpcc mssqls_driver timed
Clearing Script, reload script to activate new setting
Script cleared
Changed tpcc:mssqls_driver from test to timed for MSSQLServer</programlisting>

      <para>Configure workload settings, in this example the rampup and
      duration times are set.</para>

      <programlisting>hammerdb&gt;diset tpcc mssqls_rampup 1
Changed tpcc:mssqls_rampup from 2 to 1 for MSSQLServer

hammerdb&gt;diset tpcc mssqls_duration 3
Changed tpcc:mssqls_duration from 5 to 3 for MSSQLServer</programlisting>

      <para>Confirm the settings with the print dict command.</para>

      <programlisting>hammerdb&gt;print dict
Dictionary Settings for MSSQLServer
connection {
 mssqls_server         = (local)\SQLDEVELOP
 mssqls_linux_server   = localhost
 mssqls_tcp            = false
 mssqls_port           = 1433
 mssqls_azure          = false
 mssqls_authentication = windows
 mssqls_linux_authent  = sql
 mssqls_odbc_driver    = ODBC Driver 17 for SQL Server
 mssqls_linux_odbc     = ODBC Driver 17 for SQL Server
 mssqls_uid            = sa
 mssqls_pass           = admin
}
tpcc       {
 mssqls_count_ware       = 10
 mssqls_num_vu           = 4
 mssqls_dbase            = tpcc
 mssqls_imdb             = false
 mssqls_bucket           = 1
 mssqls_durability       = SCHEMA_AND_DATA
 mssqls_total_iterations = 1000000
 mssqls_raiseerror       = false
 mssqls_keyandthink      = false
 mssqls_checkpoint       = false
 mssqls_driver           = timed
 mssqls_rampup           = 1
 mssqls_duration         = 3
 mssqls_allwarehouse     = false
 mssqls_timeprofile      = false
 mssqls_async_scale      = false
 mssqls_async_client     = 10
 mssqls_async_verbose    = false
 mssqls_async_delay      = 1000
 mssqls_connect_pool     = false
}</programlisting>

      <para>When all the settings have been chosen load the driver script with
      the loadscript command.</para>

      <programlisting>hammerdb&gt;loadscript
Script loaded, Type "print script" to view</programlisting>

      <para>The loaded script can be viewed with the print script command.
      Note that the driver script is exactly the same as the driver script
      observed in the GUI. There is no difference whatsoever in what is run in
      the CLI compared to the GUI. If there is a wish to change the script a
      modified version can be loaded with the customscript command and it is
      therefore recommended to use the GUI to save a version of the script to
      modify.</para>

      <programlisting>#!/usr/local/bin/tclsh8.6
#EDITABLE OPTIONS##################################################
set library tdbc::odbc ;# SQL Server Library
set version 1.1.1 ;# SQL Server Library Version
set total_iterations 1000000;# Number of transactions before logging off
set RAISEERROR "false" ;# Exit script on SQL Server error (true or false)
set KEYANDTHINK "false" ;# Time for user thinking and keying (true or false)
set CHECKPOINT "false" ;# Perform SQL Server checkpoint when complete (true or false)
set rampup 1;  # Rampup time in minutes before first Transaction Count is taken
set duration 3;  # Duration in minutes before second Transaction Count is taken
set mode "Local" ;# HammerDB operational mode
set authentication "windows";# Authentication Mode (WINDOWS or SQL)
set server {(local)\SQLDEVELOP1};# Microsoft SQL Server Database Server
set port "1433";# Microsoft SQL Server Port 
set odbc_driver {ODBC Driver 17 for SQL Server};# ODBC Driver
set uid "sa";#User ID for SQL Server Authentication
set pwd "admin";#Password for SQL Server Authentication
set tcp "false";#Specify TCP Protocol
set azure "false";#Azure Type Connection
set database "tpcc";# Database containing the TPC Schema
#EDITABLE OPTIONS##################################################
...</programlisting>
    </section>

    <section>
      <title>Configure Virtual Users</title>

      <para>With the schema built and the driver script loaded the next step
      in the workflow is to configure the Virtual Users.</para>

      <para>The print command can be used to show the number of Virtual Users
      currently created. As the Virtual Users were destroyed after the build
      it is reported that none are created.</para>

      <programlisting>hammerdb&gt;print vucreated
0 Virtual Users created</programlisting>

      <para>The vuset command is used to configure the Virtual User options,
      for example the number of Virtual Users to create.</para>

      <programlisting>hammerdb&gt;vuset vu 4</programlisting>

      <para>and to enable logging.</para>

      <programlisting>hammerdb&gt;vuset logtotemp 1</programlisting>

      <para>print vuconf confirms the configuration.</para>

      <programlisting>hammerdb&gt;print vuconf
Virtual Users = 4
User Delay(ms) = 500
Repeat Delay(ms) = 500
Iterations = 1
Show Output = 1
Log Output = 1
Unique Log Name = 0
No Log Buffer = 0
Log Timestamps = 0
</programlisting>

      <para>Then run vucreate to create the Virtual Users who will be created
      in an idle state not yet running. Note that when a timed test is
      selected a Monitor Virtual User is also created as is the case with the
      graphical interface.</para>

      <programlisting>hammerdb&gt;vucreate
Vuser 1 created MONITOR - WAIT IDLE
Vuser 2 created - WAIT IDLE
Vuser 3 created - WAIT IDLE
Vuser 4 created - WAIT IDLE
Vuser 5 created - WAIT IDLE
Logging activated
to C:/Users/Steve/AppData/Local/Temp/hammerdb.log
5 Virtual Users Created with Monitor VU</programlisting>

      <para>vustatus can confirm this status.</para>

      <programlisting>hammerdb&gt;vustatus
1 = WAIT IDLE
2 = WAIT IDLE
3 = WAIT IDLE
4 = WAIT IDLE
5 = WAIT IDLE</programlisting>
    </section>

    <section>
      <title>Run the workload</title>

      <para>To begin the workload type vurun.</para>

      <programlisting>hammerdb&gt;vurun
Vuser 1:RUNNING
Vuser 1:Beginning rampup time of 1 minutes
Vuser 2:RUNNING
Vuser 2:Processing 1000000 transactions with output suppressed...
Vuser 3:RUNNING
Vuser 3:Processing 1000000 transactions with output suppressed...
Vuser 4:RUNNING
Vuser 4:Processing 1000000 transactions with output suppressed...
Vuser 5:RUNNING
Vuser 5:Processing 1000000 transactions with output suppressed...</programlisting>

      <para>The vustatus command can confirm the change in status.</para>

      <programlisting>hammerdb&gt;vustatus

1 = RUNNING
2 = RUNNING
3 = RUNNING
4 = RUNNING
5 = RUNNING</programlisting>

      <para>The vucomplete command returns a boolean value to confirm whether
      an entire workload is still running or finished.</para>

      <para><programlisting>hammerdb&gt;vucomplete
false</programlisting>The test runs as per the configuration and reports the
      result at the end and the Virtual User status. Note that when complete
      the vucomplete command can confirm this.</para>

      <programlisting>hammerdb&gt;Vuser 1:Rampup 1 minutes complete ...
Vuser 1:Rampup complete, Taking start Transaction Count.
Vuser 1:Timing test period of 3 in minutes
Vuser 1:1 ...,
Vuser 1:2 ...,
Vuser 1:3 ...,
Vuser 1:Test complete, Taking end Transaction Count.
Vuser 1:4 Active Virtual Users configured
Vuser 1:TEST RESULT : System achieved 101005 NOPM from 232149 SQL Server TPM
Vuser 1:FINISHED SUCCESS
Vuser 5:FINISHED SUCCESS
Vuser 4:FINISHED SUCCESS
Vuser 3:FINISHED SUCCESS
Vuser 2:FINISHED SUCCESS
ALL VIRTUAL USERS COMPLETE

hammerdb&gt;vucomplete
true
hammerdb&gt;</programlisting>

      <para>To complete the test type vudestroy.</para>

      <programlisting>hammerdb&gt;vudestroy
Destroying Virtual Users
Virtual Users Destroyed
</programlisting>

      <para>and clear the script.</para>

      <programlisting>hammerdb&gt;clearscript
Script cleared</programlisting>
    </section>

    <section>
      <title>CLI Scripting</title>

      <para>The CLI enables a powerful automated test environment through
      scripting in the TCL language. A recommended updated guide to TCL is
      "The Tcl Programming Language: A Comprehensive Guide by Ashok P.
      Nadkarni (ISBN: 9781548679644)"</para>

      <para>The following example shows an automated test script for a
      Microsoft SQL Server database that has previously been created. In this
      example the script runs a timed tests for a duration of a minute for 1,
      2 and 4 Virtual Users in a similar manner to autopilot functionality
      with a timer set to run for 2 minutes. Note that from HammerDB v4.0 the
      runtimer command is included. The timer is set to a period of time for
      the test to run, however if vucomplete is set to true during the test it
      will also return.</para>

      <programlisting>#!/usr/bin/tclsh
puts "SETTING CONFIGURATION"
dbset db mssqls
diset tpcc mssqls_driver timed
diset tpcc mssqls_rampup 0
diset tpcc mssqls_duration 1
vuset logtotemp 1
loadscript
puts "SEQUENCE STARTED"
foreach z { 1 2 4 } {
puts "$z VU TEST"
vuset vu $z
vucreate
vurun
runtimer 120
vudestroy
after 5000
}
puts "TEST SEQUENCE COMPLETE"</programlisting>

      <para>Run the hammerdbcli command and at the prompt type source and the
      name of the script. The following output is produced without further
      intervention whilst also writing the output to the logfile.</para>

      <programlisting>HammerDB CLI v4.0
Copyright (C) 2003-2020 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
hammerdb&gt;source cliexample.tcl
SETTING CONFIGURATION
Database set to MSSQLServer
Clearing Script, reload script to activate new setting
Script cleared
Changed tpcc:mssqls_driver from test to timed for MSSQLServer
Changed tpcc:mssqls_rampup from 2 to 0 for MSSQLServer
Changed tpcc:mssqls_duration from 5 to 1 for MSSQLServer
Script loaded, Type "print script" to view
SEQUENCE STARTED
1 VU TEST
Vuser 1 created MONITOR - WAIT IDLE
Vuser 2 created - WAIT IDLE
Logging activated
to C:/Users/Hdb/AppData/Local/Temp/hammerdb.log
2 Virtual Users Created with Monitor VU
Vuser 1:RUNNING
Vuser 1:Beginning rampup time of 0 minutes
Vuser 1:Rampup complete, Taking start Transaction Count.
Vuser 1:Timing test period of 1 in minutes
Vuser 2:RUNNING
Vuser 2:Processing 1000000 transactions with output suppressed...
Vuser 1:1 ...,
Vuser 1:Test complete, Taking end Transaction Count.
Timer: 1 minutes elapsed
Vuser 1:1 Active Virtual Users configured
Vuser 1:TEST RESULT : System achieved 35576 NOPM from 81705 SQL Server TPM
Vuser 1:FINISHED SUCCESS
Vuser 2:FINISHED SUCCESS
ALL VIRTUAL USERS COMPLETE
runtimer returned after 61 seconds
vudestroy success
2 VU TEST
Vuser 1 created MONITOR - WAIT IDLE
Vuser 2 created - WAIT IDLE
Vuser 3 created - WAIT IDLE
Logging activated
to C:/Users/Hdb/AppData/Local/Temp/hammerdb.log
3 Virtual Users Created with Monitor VU
Vuser 1:RUNNING
Vuser 1:Beginning rampup time of 0 minutes
Vuser 1:Rampup complete, Taking start Transaction Count.
Vuser 1:Timing test period of 1 in minutes
Vuser 2:RUNNING
Vuser 2:Processing 1000000 transactions with output suppressed...
Vuser 3:RUNNING
Vuser 3:Processing 1000000 transactions with output suppressed...
Vuser 1:1 ...,
Vuser 1:Test complete, Taking end Transaction Count.
Vuser 1:2 Active Virtual Users configured
Vuser 1:TEST RESULT : System achieved 60364 NOPM from 138633 SQL Server TPM
Timer: 1 minutes elapsed
Vuser 1:FINISHED SUCCESS
Vuser 2:FINISHED SUCCESS
Vuser 3:FINISHED SUCCESS
ALL VIRTUAL USERS COMPLETE
runtimer returned after 60 seconds
vudestroy success
4 VU TEST
Vuser 1 created MONITOR - WAIT IDLE
Vuser 2 created - WAIT IDLE
Vuser 3 created - WAIT IDLE
Vuser 4 created - WAIT IDLE
Vuser 5 created - WAIT IDLE
Logging activated
to C:/Users/Hdb/AppData/Local/Temp/hammerdb.log
5 Virtual Users Created with Monitor VU
Vuser 1:RUNNING
Vuser 1:Beginning rampup time of 0 minutes
Vuser 1:Rampup complete, Taking start Transaction Count.
Vuser 1:Timing test period of 1 in minutes
Vuser 2:RUNNING
Vuser 2:Processing 1000000 transactions with output suppressed...
Vuser 3:RUNNING
Vuser 3:Processing 1000000 transactions with output suppressed...
Vuser 4:RUNNING
Vuser 4:Processing 1000000 transactions with output suppressed...
Vuser 5:RUNNING
Vuser 5:Processing 1000000 transactions with output suppressed...
Vuser 1:1 ...,
Vuser 1:Test complete, Taking end Transaction Count.
Vuser 1:4 Active Virtual Users configured
Vuser 1:TEST RESULT : System achieved 103055 NOPM from 236412 SQL Server TPM
Vuser 1:FINISHED SUCCESS
Vuser 2:FINISHED SUCCESS
Vuser 4:FINISHED SUCCESS
Vuser 5:FINISHED SUCCESS
Vuser 3:FINISHED SUCCESS
ALL VIRTUAL USERS COMPLETE
runtimer returned after 59 seconds
vudestroy success
TEST SEQUENCE COMPLETE

hammerdb&gt;</programlisting>

      <para>It is a common requirement to also want to drive HammerDB CLI
      scripts from an external scripting tool. For this reason HammerDB v4.0
      also includes the command waittocomplete. This can be seen as
      complementary to runtimer, whereas runtimer will run in the main thread
      for a specified period of time, waittocomplete will wait for an
      indeterminate period of time until vucomplete is set to true. Therefore
      waittocomplete is particularly beneficial for schema builds which may
      take different periods of time but is complete when all Virtual Users
      have finished their task. An example automated build is shown.</para>

      <programlisting>#!/bin/tclsh
dbset db mssqls
diset tpcc mssqls_count_ware 10
diset tpcc mssqls_num_vu 4
diset connection mssqls_server {(local)\SQLDEVELOP}
vuset logtotemp 1
print dict
buildschema
waittocomplete</programlisting>

      <para>The HammerDB CLI will accept the argument auto to run a specified
      script automatically.</para>

      <programlisting>hammerdbcli.bat auto autorunbuild.tcl</programlisting>

      <para>Using this approach it is possible to build complex test scenarios
      automating both build and test functionality.</para>
    </section>
  </chapter>

  <chapter>
    <title>Web Service Interface (WS)</title>

    <para>In addition to the CLI there is a HTTP Web Service that provides the
    same commands as the CLI that can be accessed with a HTTP/REST client
    passing parameters and returning output in JSON format. The key difference
    from the configuration of the CLI is the addition of jobs. Under the web
    service output from schema builds or tests are stored in a SQLite database
    and retrieved at a later point using a job id. A rest interface has been
    provided in HammerDB for interacting with the web service using TCL,
    however this is not a necessity and although the examples in this section
    are given using TCL the web service can be driven with scripts written in
    any language. Additionally the huddle package has been provided for TCL to
    JSON formatting.</para>

    <section>
      <title>Web Service Configuration</title>

      <para>There are 2 configuration parameters for the webservice in the
      file generic.xml in the config directory, ws_port and sqlite_db. ws_port
      defines the port on which the service will run and sqlite_db defines the
      location of the SQLite database file. By default an in-memory location
      is used. Alternatively the name of a file can be given or "TMP" or
      "TEMP" for HammerDB to find a temporary directory to use for the
      file.</para>

      <programlisting>  &lt;webservice&gt;
   &lt;ws_port&gt;8080&lt;/ws_port&gt; 
   &lt;sqlite_db&gt;:memory:&lt;/sqlite_db&gt; 
  &lt;/webservice&gt;
</programlisting>
    </section>

    <section>
      <title>Starting the Web Service and Help Screen</title>

      <para>On starting the Web service with the hammerdbws command HammerDB
      will listen on the specified port for HTTP requests.</para>

      <programlisting>[oracle@vulture HammerDB-4.0]$ ./hammerdbws 
HammerDB Web Service v4.0
Copyright (C) 2003-2020 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
Initialized new SQLite in-memory database
Starting HammerDB Web Service on port 8080
Listening for HTTP requests on TCP port 8080
</programlisting>

      <para>Navigating to the configured port without further argument will
      return the help screen.</para>

      <programlisting>HammerDB Web Service

See the HammerDB Web Service Environment
HAMMERDB REST/HTTP API

GET db: Show the configured database.
get http://localhost:8080/print?db / get http://localhost:8080/db
{
"ora": "Oracle",
"mssqls": "MSSQLServer",
"db2": "Db2",
"mysql": "MySQL",
"pg": "PostgreSQL",
"redis": "Redis"
}


GET bm: Show the configured benchmark.
get http://localhost:8080/print?bm / get http://localhost:8080/bm
{"benchmark": "TPC-C"}


GET dict: Show the dictionary for the current database ie all active variables.
get http://localhost:8080/print?dict /  http://localhost:8080/dict
{
"connection": {
"system_user": "system",
"system_password": "manager",
"instance": "oracle",
"rac": "0"
},
"tpcc": {
"count_ware": "1",
"num_vu": "1",
"tpcc_user": "tpcc",
"tpcc_pass": "tpcc",
"tpcc_def_tab": "tpcctab",
"tpcc_ol_tab": "tpcctab",
"tpcc_def_temp": "temp",
"partition": "false",
"hash_clusters": "false",
"tpcc_tt_compat": "false",
"total_iterations": "1000000",
"raiseerror": "false",
"keyandthink": "false",
"checkpoint": "false",
"ora_driver": "test",
"rampup": "2",
"duration": "5",
"allwarehouse": "false",
"timeprofile": "false"
}
}

 
GET script: Show the loaded script.
get http://localhost:8080/print?script / http://localhost:8080/script
{"script": "#!/usr/local/bin/tclsh8.6
#TIMED AWR SNAPSHOT DRIVER SCRIPT##################################
#THIS SCRIPT TO BE RUN WITH VIRTUAL USER OUTPUT ENABLED
#EDITABLE OPTIONS##################################################
set library Oratcl ;# Oracle OCI Library
set total_iterations 1000000 ;# Number of transactions before logging off
set RAISEERROR \"false\" ;# Exit script on Oracle error (true or false)
set KEYANDTHINK \"false\" ;# Time for user thinking and keying (true or false)
set CHECKPOINT \"false\" ;# Perform Oracle checkpoint when complete (true or false)
set rampup 2;  # Rampup time in minutes before first snapshot is taken
set duration 5;  # Duration in minutes before second AWR snapshot is taken
set mode \"Local\" ;# HammerDB operational mode
set timesten \"false\" ;# Database is TimesTen
set systemconnect system/manager@oracle ;# Oracle connect string for system user
set connect tpcc/new_password@oracle ;# Oracle connect string for tpc-c user
#EDITABLE OPTIONS##################################################
#LOAD LIBRARIES AND MODULES …. 
"}

 
GET vuconf: Show the virtual user configuration.
get http://localhost:8080/print?vuconf / http://localhost:8080/vuconf
{
"Virtual Users": "1",
"User Delay(ms)": "500",
"Repeat Delay(ms)": "500",
"Iterations": "1",
"Show Output": "1",
"Log Output": "0",
"Unique Log Name": "0",
"No Log Buffer": "0",
"Log Timestamps": "0"
}

 
GET vucreate: Create the virtual users. Equivalent to the Virtual User Create option in the graphical interface. Use vucreated to see the number created, vustatus to see the status and vucomplete to see whether all active virtual users have finished the workload. A script must be loaded before virtual users can be created.
get http://localhost:8080/vucreate
{"success": {"message": "4 Virtual Users Created"}}

 
GET vucreated: Show the number of virtual users created.
get http://localhost:8080/print?vucreated / get http://localhost:8080/vucreated
{"Virtual Users created": "10"}

 
GET vustatus: Show the status of virtual users, status will be "WAIT IDLE" for virtual users that are created but not running a workload,"RUNNING" for virtual users that are running a workload, "FINISH SUCCESS" for virtual users that completed successfully or "FINISH FAILED" for virtual users that encountered an error.
get http://localhost:8080/print?vustatus / get http://localhost:8080/vustatus
{"Virtual User status": "1 {WAIT IDLE} 2 {WAIT IDLE} 3 {WAIT IDLE} 4 {WAIT IDLE} 5 {WAIT IDLE} 6 {WAIT IDLE} 7 {WAIT IDLE} 8 {WAIT IDLE} 9 {WAIT IDLE} 10 {WAIT IDLE}"}

 
GET datagen: Show the datagen configuration
get http://localhost:8080/print?datagen /  get http://localhost:8080/datagen
{
"schema": "TPC-C",
"database": "Oracle",
"warehouses": "1",
"vu": "1",
"directory": "/tmp\""
}

 
GET vucomplete: Show if virtual users have completed. returns "true" or "false" depending on whether all virtual users that started a workload have completed regardless of whether the status was "FINISH SUCCESS" or "FINISH FAILED".
get http://localhost:8080/vucomplete
{"Virtual Users complete": "true"}

 
GET vudestroy: Destroy the virtual users. Equivalent to the Destroy Virtual Users button in the graphical interface that replaces the Create Virtual Users button after virtual user creation.
get http://localhost:8080/vudestroy
{"success": {"message": "vudestroy success"}}

 
GET loadscript: Load the script for the database and benchmark set with dbset and the dictionary variables set with diset. Use print?script to see the script that is loaded. Equivalent to loading a Driver Script in the Script Editor window in the graphical interface. Driver script must be set to timed for the script to be loaded. Test scripts should be run in the GUI environment.  
get http://localhost:8080/loadscript
{"success": {"message": "script loaded"}}

 
GET clearscript: Clears the script. Equivalent to the "Clear the Screen" button in the graphical interface.
get http://localhost:8080/clearscript
{"success": {"message": "Script cleared"}}

 
GET vurun: Send the loaded script to the created virtual users for execution. Equivalent to the Run command in the graphical interface. Creates a job id associated with all output. 
get http://localhost:8080/vurun
{"success": {"message": "Running Virtual Users: JOBID=5CEFBFE658A103E253238363"}}


GET datagenrun: Run Data Generation. Equivalent to the Generate option in the graphical interface. Not supported in web service. Generate data using GUI or CLI. 


GET buildschema: Runs the schema build for the database and benchmark selected with dbset and variables selected with diset. Equivalent to the Build command in the graphical interface. Creates a job id associated with all output. 
get http://localhost:8080/buildschema
{"success": {"message": "Building 6 Warehouses with 4 Virtual Users, 3 active + 1 Monitor VU(dict value num_vu is set to 3): JOBID=5CEFA68458A103E273433333"}}


GET jobs: Show the job ids, output, status and results of jobs created by buildschema and vurun. Job output is equivalent to the output viewed in the graphical interface or command line.
GET http://localhost:8080/jobs: Show all job ids
get http://localhost:8080/jobs
[
"5CEE889958A003E203838313",
"5CEFA68458A103E273433333"
]
GET http://localhost:8080/jobs?jobid=TEXT: Show output for the specified job id.
get http://localhost:8080/jobs?jobid=5CEFA68458A103E273433333
[
"0",
"Ready to create a 6 Warehouse Oracle TPC-C schema
in database VULPDB1 under user TPCC in tablespace TPCCTAB?",
"0",
"Vuser 1:RUNNING",
"1",
"Monitor Thread",
"1",
"CREATING TPCC SCHEMA",
...
"1",
"TPCC SCHEMA COMPLETE",
"0",
"Vuser 1:FINISHED SUCCESS",
"0",
"ALL VIRTUAL USERS COMPLETE"
]
GET http://localhost:8080/jobs?jobid=TEXT&amp;vu=INTEGER: Show output for the specified job id and virtual user.
get http://localhost:8080/jobs?jobid=5CEFA68458A103E273433333&amp;vu=1
[
"1",
"Monitor Thread",
"1",
"CREATING TPCC SCHEMA",
"1",
"CREATING USER tpcc",
"1",
"CREATING TPCC TABLES",
"1",
"Loading Item",
"1",
"Loading Items - 50000",
"1",
"Loading Items - 100000",
"1",
"Item done",
"1",
"Monitoring Workers...",
"1",
"Workers: 3 Active 0 Done"
]
GET http://localhost:8080/jobs?jobid=TEXT&amp;status: Show status for the specified job id. Equivalent to virtual user 0.
get http://localhost:8080/jobs?jobid=5CEFA68458A103E273433333&amp;status
[
"0",
"Ready to create a 6 Warehouse Oracle TPC-C schema
in database VULPDB1 under user TPCC in tablespace TPCCTAB?",
"0",
"Vuser 1:RUNNING",
"0",
"Vuser 2:RUNNING",
"0",
"Vuser 3:RUNNING",
"0",
"Vuser 4:RUNNING",
"0",
"Vuser 4:FINISHED SUCCESS",
"0",
"Vuser 3:FINISHED SUCCESS",
"0",
"Vuser 2:FINISHED SUCCESS",
"0",
"Vuser 1:FINISHED SUCCESS",
"0",
"ALL VIRTUAL USERS COMPLETE"
]
GET http://localhost:8080/jobs?jobid=TEXT&amp;result: Show the test result for the specified job id. If job is not a test job such as build job then no result will be reported. 
get http://localhost:8080/jobs?jobid=5CEFA68458A103E273433333&amp;result
[
"5CEFA68458A103E273433333",
"Jobid has no test result"
]
GET http://localhost:8080/jobs?jobid=TEXT&amp;delete: Delete all output for the specified jobid.
get http://localhost:8080/jobs?jobid=5CEFA68458A103E273433333&amp;delete
{"success": {"message": "Deleted Jobid 5CEFA68458A103E273433333"}} 


GET killws: Terminates the webservice and reports message to the console.
get http://localhost:8080/killws
Shutting down HammerDB Web Service


POST dbset: Usage: dbset [db|bm] value. Sets the database (db) or benchmark (bm). Equivalent to the Benchmark Menu in the graphical interface. Database value is set by the database prefix in the XML configuration.
set body { "db": "ora" }
rest::post http://localhost:8080/dbset $body


POST diset: Usage: diset dict key value. Set the dictionary variables for the current database. Equivalent to the Schema Build and Driver Options windows in the graphical interface. Use print?dict to see what these variables are and diset to change.
set body { "dict": "tpcc", "key": "rampup", "value": "0" }
rest::post http://localhost:8080/diset $body
set body { "dict": "tpcc", "key": "duration", "value": "1" }
rest::post http://localhost:8080/diset $body


POST vuset: Usage: vuset [vu|delay|repeat|iterations|showoutput|logtotemp|unique|nobuff|timestamps]. Configure the virtual user options. Equivalent to the Virtual User Options window in the graphical interface.
set body { "vu": "4" }
rest::post http://localhost:8080/vuset $body


POST customscript: Load an external script. Equivalent to the "Open Existing File" button in the graphical interface. Script must be converted to JSON format before post as shown in the example:
set customscript "testscript.tcl"
set _ED(file) $customscript
if {$_ED(file) == ""} {return}
if {![file readable $_ED(file)]} {
puts "File [$_ED(file)] is not readable."
return
}
if {[catch "open \"$_ED(file)\" r" fd]} {
puts "Error while opening $_ED(file): [$fd]"
} else {
set _ED(package) "[read $fd]"
close $fd
}
set huddleobj [ huddle compile {string} "$_ED(package)" ]
set jsonobj [ huddle jsondump $huddleobj ]
set body [ subst { {"script": $jsonobj}} ]
set res [ rest::post http://localhost:8080/customscript $body ] 


POST dgset: Usage: dgset [vu|ware|directory]. Set the Datagen options. Equivalent to the Datagen Options dialog in the graphical interface.
set body { "directory": "/home/oracle" }
rest::post http://localhost:8080/dgset $body 


DEBUG
GET dumpdb: Dumps output of the SQLite database to the console.
GET http://localhost:8080/dumpdb
***************DEBUG***************
5CEE889958A003E203838313 0 {Ready to create a 6 Warehouse Oracle TPC-C schema
in database VULPDB1 under user TPCC in tablespace TPCCTAB?} 5CEE889958A003E203838313 0 {Vuser 1:RUNNING} 5CEE889958A003E203838313 1 {Monitor Thread} 5CEE889958A003E203838313 1 {CREATING TPCC SCHEMA} 5CEE889958A003E203838313 0 {Vuser 2:RUNNING} 5CEE889958A003E203838313 2 {Worker Thread} 5CEE889958A003E203838313 2 {Waiting for Monitor Thread...} 5CEE889958A003E203838313 1 {Error: ORA-12541: TNS:no listener} 5CEE889958A003E203838313 0 {Vuser 1:FINISHED FAILED} 5CEE889958A003E203838313 0 {Vuser 3:RUNNING} 5CEE889958A003E203838313 3 {Worker Thread} 5CEE889958A003E203838313 3 {Waiting for Monitor Thread...} 5CEE889958A003E203838313 0 {Vuser 4:RUNNING} 5CEE889958A003E203838313 4 {Worker Thread} 5CEE889958A003E203838313 4 {Waiting for Monitor Thread...} 5CEE889958A003E203838313 2 {Monitor failed to notify ready state} 5CEE889958A003E203838313 0 {Vuser 2:FINISHED SUCCESS} 5CEE889958A003E203838313 3 {Monitor failed to notify ready state} 5CEE889958A003E203838313 0 {Vuser 3:FINISHED SUCCESS} 5CEE889958A003E203838313 4 {Monitor failed to notify ready state} 5CEE889958A003E203838313 0 {Vuser 4:FINISHED SUCCESS} 5CEE889958A003E203838313 0 {ALL VIRTUAL USERS COMPLETE}
***************DEBUG***************

</programlisting>

      <para>As an example the following script shows printing the output of
      print commands in both JSON and text format.</para>

      <programlisting>set UserDefaultDir [ file dirname [ info script ] ]
::tcl::tm::path add "$UserDefaultDir/modules"
package require rest
package require huddle
puts "TEST DIRECT PRINT COMMANDS"
puts "--------------------------------------------------------"
foreach i {db bm dict script vuconf vucreated vustatus datagen}  {
puts "Printing output for $i and converting JSON to text"
    set res [rest::get http://localhost:8080/$i "" ]
puts "JSON format"
puts $res
puts "TEXT format"
    set res [rest::format_json $res]
    puts $res
}
puts "--------------------------------------------------------"
puts "PRINT COMMANDS COMPLETE"
puts "--------------------------------------------------------"
</programlisting>

      <para>Once the Web Service is running in another port, run the TCL shell
      as follows and run the script above, the output is shown as
      follows.</para>

      <programlisting>$ ./bin/tclsh8.6 
% source restchk.tcl
TEST DIRECT PRINT COMMANDS
--------------------------------------------------------
Printing output for db and converting JSON to text
JSON format
{
  "ora": "Oracle",
  "mssqls": "MSSQLServer",
  "db2": "Db2",
  "mysql": "MySQL",
  "pg": "PostgreSQL",
  "redis": "Redis"
}
TEXT format
ora Oracle mssqls MSSQLServer db2 Db2 mysql MySQL pg PostgreSQL redis Redis
Printing output for bm and converting JSON to text
JSON format
{"benchmark": "TPC-C"}
TEXT format
benchmark TPC-C
Printing output for dict and converting JSON to text
JSON format
{
  "connection": {
    "system_user": "system",
    "system_password": "manager",
    "instance": "oracle",
    "rac": "0"
  },
  "tpcc": {
    "count_ware": "1",
    "num_vu": "1",
    "tpcc_user": "tpcc",
    "tpcc_pass": "tpcc",
    "tpcc_def_tab": "tpcctab",
    "tpcc_ol_tab": "tpcctab",
    "tpcc_def_temp": "temp",
    "partition": "false",
    "hash_clusters": "false",
    "tpcc_tt_compat": "false",
    "total_iterations": "1000000",
    "raiseerror": "false",
    "keyandthink": "false",
    "checkpoint": "false",
    "ora_driver": "test",
    "rampup": "2",
    "duration": "5",
    "allwarehouse": "false",
    "timeprofile": "false"
  }
}
TEXT format
connection {system_user system system_password manager instance oracle rac 0} tpcc {count_ware 1 num_vu 1 tpcc_user tpcc tpcc_pass tpcc tpcc_def_tab tpcctab tpcc_ol_tab tpcctab tpcc_def_temp temp partition false hash_clusters false tpcc_tt_compat false total_iterations 1000000 raiseerror false keyandthink false checkpoint false ora_driver test rampup 2 duration 5 allwarehouse false timeprofile false}
Printing output for script and converting JSON to text
JSON format
{"error": {"message": "No Script loaded: load with loadscript"}}
TEXT format
error {message {No Script loaded: load with loadscript}}
Printing output for vuconf and converting JSON to text
JSON format
{
  "Virtual Users": "1",
  "User Delay(ms)": "500",
  "Repeat Delay(ms)": "500",
  "Iterations": "1",
  "Show Output": "1",
  "Log Output": "0",
  "Unique Log Name": "0",
  "No Log Buffer": "0",
  "Log Timestamps": "0"
}
TEXT format
{Virtual Users} 1 {User Delay(ms)} 500 {Repeat Delay(ms)} 500 Iterations 1 {Show Output} 1 {Log Output} 0 {Unique Log Name} 0 {No Log Buffer} 0 {Log Timestamps} 0
Printing output for vucreated and converting JSON to text
JSON format
{"Virtual Users created": "0"}
TEXT format
{Virtual Users created} 0
Printing output for vustatus and converting JSON to text
JSON format
{"Virtual User status": "No Virtual Users found"}
TEXT format
{Virtual User status} {No Virtual Users found}
Printing output for datagen and converting JSON to text
JSON format
{
  "schema": "TPC-C",
  "database": "Oracle",
  "warehouses": "1",
  "vu": "1",
  "directory": "\/tmp\""
}
TEXT format
schema TPC-C database Oracle warehouses 1 vu 1 directory /tmp\"
--------------------------------------------------------
PRINT COMMANDS COMPLETE
--------------------------------------------------------
% </programlisting>
    </section>

    <section>
      <title>Retrieving Output</title>

      <para>As an example the following script shows printing the output of
      print commands in both JSON and text format.</para>

      <programlisting>set UserDefaultDir [ file dirname [ info script ] ]
::tcl::tm::path add "$UserDefaultDir/modules"
package require rest
package require huddle
puts "TEST DIRECT PRINT COMMANDS"
puts "--------------------------------------------------------"
foreach i {db bm dict script vuconf vucreated vustatus datagen}  {
puts "Printing output for $i and converting JSON to text"
    set res [rest::get http://localhost:8080/$i "" ]
puts "JSON format"
puts $res
puts "TEXT format"
    set res [rest::format_json $res]
    puts $res
}
puts "--------------------------------------------------------"
puts "PRINT COMMANDS COMPLETE"
puts "--------------------------------------------------------"
</programlisting>

      <para>Once the Web Service is running in another port, run the TCL shell
      as follows and run the script above, the output is shown as
      follows.</para>

      <programlisting>$ ./bin/tclsh8.6 
% source restchk.tcl
TEST DIRECT PRINT COMMANDS
--------------------------------------------------------
Printing output for db and converting JSON to text
JSON format
{
  "ora": "Oracle",
  "mssqls": "MSSQLServer",
  "db2": "Db2",
  "mysql": "MySQL",
  "pg": "PostgreSQL",
  "redis": "Redis"
}
TEXT format
ora Oracle mssqls MSSQLServer db2 Db2 mysql MySQL pg PostgreSQL redis Redis
Printing output for bm and converting JSON to text
JSON format
{"benchmark": "TPC-C"}
TEXT format
benchmark TPC-C
Printing output for dict and converting JSON to text
JSON format
{
  "connection": {
    "system_user": "system",
    "system_password": "manager",
    "instance": "oracle",
    "rac": "0"
  },
  "tpcc": {
    "count_ware": "1",
    "num_vu": "1",
    "tpcc_user": "tpcc",
    "tpcc_pass": "tpcc",
    "tpcc_def_tab": "tpcctab",
    "tpcc_ol_tab": "tpcctab",
    "tpcc_def_temp": "temp",
    "partition": "false",
    "hash_clusters": "false",
    "tpcc_tt_compat": "false",
    "total_iterations": "1000000",
    "raiseerror": "false",
    "keyandthink": "false",
    "checkpoint": "false",
    "ora_driver": "test",
    "rampup": "2",
    "duration": "5",
    "allwarehouse": "false",
    "timeprofile": "false"
  }
}
TEXT format
connection {system_user system system_password manager instance oracle rac 0} tpcc {count_ware 1 num_vu 1 tpcc_user tpcc tpcc_pass tpcc tpcc_def_tab tpcctab tpcc_ol_tab tpcctab tpcc_def_temp temp partition false hash_clusters false tpcc_tt_compat false total_iterations 1000000 raiseerror false keyandthink false checkpoint false ora_driver test rampup 2 duration 5 allwarehouse false timeprofile false}
Printing output for script and converting JSON to text
JSON format
{"error": {"message": "No Script loaded: load with loadscript"}}
TEXT format
error {message {No Script loaded: load with loadscript}}
Printing output for vuconf and converting JSON to text
JSON format
{
  "Virtual Users": "1",
  "User Delay(ms)": "500",
  "Repeat Delay(ms)": "500",
  "Iterations": "1",
  "Show Output": "1",
  "Log Output": "0",
  "Unique Log Name": "0",
  "No Log Buffer": "0",
  "Log Timestamps": "0"
}
TEXT format
{Virtual Users} 1 {User Delay(ms)} 500 {Repeat Delay(ms)} 500 Iterations 1 {Show Output} 1 {Log Output} 0 {Unique Log Name} 0 {No Log Buffer} 0 {Log Timestamps} 0
Printing output for vucreated and converting JSON to text
JSON format
{"Virtual Users created": "0"}
TEXT format
{Virtual Users created} 0
Printing output for vustatus and converting JSON to text
JSON format
{"Virtual User status": "No Virtual Users found"}
TEXT format
{Virtual User status} {No Virtual Users found}
Printing output for datagen and converting JSON to text
JSON format
{
  "schema": "TPC-C",
  "database": "Oracle",
  "warehouses": "1",
  "vu": "1",
  "directory": "\/tmp\""
}
TEXT format
schema TPC-C database Oracle warehouses 1 vu 1 directory /tmp\"
--------------------------------------------------------
PRINT COMMANDS COMPLETE
--------------------------------------------------------
% </programlisting>
    </section>

    <section>
      <title>Running Jobs</title>

      <para>The following script run in the same shows how this can be
      extended so that an external script can interact with the web service
      and run a build and then a test successively. Note that wait_to_complete
      procedures can properly sleep using the after command without activity
      and without affecting the progress of the jobs as the driving script is
      run in one interpreter and the web service in another.</para>

      <programlisting>set UserDefaultDir [ file dirname [ info script ] ]
::tcl::tm::path add "$UserDefaultDir/modules"
package require rest
package require huddle

proc wait_for_run_to_complete { runjob } {
global complete
set res [rest::get http://localhost:8080/vucomplete "" ]
set complete [ lindex [rest::format_json $res] 1]
if {!$complete} {
#sleep for 20 seconds and recheck
after 20000 
wait_for_run_to_complete $runjob
	} else {
set res [rest::get http://localhost:8080/vudestroy "" ]
puts "Test Complete"
set jobid [ lindex [ split [ lindex [ lindex [ lindex [rest::format_json $runjob ] 1 ] 1 ] 3 ] \= ] 1 ]
set res [rest::get http://localhost:8080/jobs?jobid=$jobid&amp;result "" ]
puts "Test result: $res"
  }
}

proc wait_for_build_to_complete {} {
global complete
set res [rest::get http://localhost:8080/vucomplete "" ]
set complete [ lindex [rest::format_json $res] 1]
if {!$complete} {
#sleep for 20 seconds and recheck
after 20000 
wait_for_build_to_complete 
	} else {
set res [rest::get http://localhost:8080/vudestroy "" ]
puts "Build Complete"
set complete false
  }
}

proc run_test {} {
puts "Setting Db values"
set body { "db": "ora" }
    set res [ rest::post http://localhost:8080/dbset $body ] 
set body { "bm": "TPC-C" }
    set res [ rest::post http://localhost:8080/dbset $body ] 
puts "Setting Vusers"
set body { "vu": "5" }
    set res [ rest::post http://localhost:8080/vuset $body ] 
puts $res
puts "Setting Dict Values"
set body { "dict": "connection", "key": "system_password", "value": "oracle" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "connection", "key": "instance", "value": "VULPDB1" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "tpcc_pass", "value": "oracle" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "ora_driver", "value": "timed" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "rampup", "value": "1" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "duration", "value": "2" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "checkpoint", "value": "false" }
    set res [rest::post http://localhost:8080/diset $body ]
puts "Config"
set res [rest::get http://localhost:8080/dict "" ]
puts $res
puts "Clearscript"
    set res [rest::post http://localhost:8080/clearscript "" ]
puts $res
puts "Loadscript"
    set res [rest::post http://localhost:8080/loadscript "" ]
puts $res
puts "Create VU"
 set res [rest::post http://localhost:8080/vucreate "" ]
puts $res
puts "Run VU"
 set res [rest::post http://localhost:8080/vurun "" ]
puts $res
wait_for_run_to_complete $res
}

proc run_build {} {
puts "running build"
set body { "db": "ora" }
    set res [ rest::post http://localhost:8080/dbset $body ] 
set body { "bm": "TPC-C" }
    set res [ rest::post http://localhost:8080/dbset $body ] 
puts "Setting Dict Values"
set body { "dict": "connection", "key": "system_password", "value": "oracle" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "connection", "key": "instance", "value": "VULPDB1" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "count_ware", "value": "10" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "tpcc_pass", "value": "oracle" }
    set res [rest::post http://localhost:8080/diset $body ]
set body { "dict": "tpcc", "key": "num_vu", "value": "5" }
    set res [rest::post http://localhost:8080/diset $body ]
puts "Starting Schema Build"
    set res [rest::post http://localhost:8080/buildschema "" ]
puts $res
wait_for_build_to_complete
	}
#Run build followed by run test
run_build
run_test
</programlisting>

      <para>An example of the output running the script is shown.</para>

      <programlisting>./bin/tclsh8.6 
% source buildrun_tpcc.tcl
running build
Setting Dict Values
Starting Schema Build
{"success": {"message": "Building 10 Warehouses with 6 Virtual Users, 5 active + 1 Monitor VU(dict value num_vu is set to 5): JOBID=5D1F4CA858CE03E213431323"}}
Build Complete
Setting Db values
Setting Vusers
{"success": {"message": "Virtual users set to 5"}}
Setting Dict Values
Config
{
  "connection": {
    "system_user": "system",
    "system_password": "oracle",
    "instance": "VULPDB1",
    "rac": "0"
  },
  "tpcc": {
    "count_ware": "10",
    "num_vu": "5",
    "tpcc_user": "tpcc",
    "tpcc_pass": "oracle",
    "tpcc_def_tab": "tpcctab",
    "tpcc_ol_tab": "tpcctab",
    "tpcc_def_temp": "temp",
    "partition": "false",
    "hash_clusters": "false",
    "tpcc_tt_compat": "false",
    "total_iterations": "1000000",
    "raiseerror": "false",
    "keyandthink": "false",
    "checkpoint": "false",
    "ora_driver": "timed",
    "rampup": "1",
    "duration": "2",
    "allwarehouse": "false",
    "timeprofile": "false"
  }
}
Clearscript
{"success": {"message": "Script cleared"}}
Loadscript
{"success": {"message": "script loaded"}}
Create VU
{"success": {"message": "6 Virtual Users Created with Monitor VU"}}
Run VU
{"success": {"message": "Running Virtual Users: JOBID=5D1F4FF558CE03E223730313"}}
Test Complete
Test result: [
  "5D1F4FF558CE03E223730313",
  "TEST RESULT : System achieved 0 Oracle TPM at 27975 NOPM"
]
% </programlisting>
    </section>

    <section>
      <title>Query Job Output</title>

      <para>Note that no output is seen directly in the script and no output
      recorded to a logfile. Instead the output is stored as a job by the web
      service. For example the following script would retrieve the output for
      the run job.</para>

      <programlisting>set UserDefaultDir [ file dirname [ info script ] ]
::tcl::tm::path add "$UserDefaultDir/modules"
package require rest
package require huddle
    set res [rest::get http://localhost:8080/jobs?jobid=5D1F4FF558CE03E223730313 "" ]
puts "JSON format"
puts $res
</programlisting>

      <para>With the output as follows.</para>

      <programlisting>% source joboutput.tcl
JSON format
[
  "0",
  "Vuser 1:RUNNING",
  "1",
  "Beginning rampup time of 1 minutes",
  "0",
  "Vuser 2:RUNNING",
  "2",
  "Processing 1000000 transactions with output suppressed...",
  "0",
  "Vuser 3:RUNNING",
  "3",
  "Processing 1000000 transactions with output suppressed...",
  "0",
  "Vuser 4:RUNNING",
  "4",
  "Processing 1000000 transactions with output suppressed...",
  "0",
  "Vuser 5:RUNNING",
  "5",
  "Processing 1000000 transactions with output suppressed...",
  "0",
  "Vuser 6:RUNNING",
  "6",
  "Processing 1000000 transactions with output suppressed...",
  "1",
  "Rampup 1 minutes complete ...",
  "1",
  "Rampup complete, Taking start AWR snapshot.",
  "1",
  "Start Snapshot 298 taken at 05 JUL 2019 14:20 of instance VULCDB1 (1) of database VULCDB1 (1846545596)",
  "1",
  "Timing test period of 2 in minutes",
  "1",
  "1  ...,",
  "1",
  "2  ...,",
  "1",
  "Test complete, Taking end AWR snapshot.",
  "1",
  "End Snapshot 298 taken at 05 JUL 2019 14:20 of instance VULCDB1 (1) of database VULCDB1 (1846545596)",
  "1",
  "Test complete: view report from SNAPID  298 to 298",
  "1",
  "5 Active Virtual Users configured",
  "1",
  "TEST RESULT : System achieved 0 Oracle TPM at 27975 NOPM",
  "0",
  "Vuser 2:FINISHED SUCCESS",
  "0",
  "Vuser 1:FINISHED SUCCESS",
  "0",
  "Vuser 6:FINISHED SUCCESS",
  "0",
  "Vuser 5:FINISHED SUCCESS",
  "0",
  "Vuser 3:FINISHED SUCCESS",
  "0",
  "Vuser 4:FINISHED SUCCESS",
  "0",
  "ALL VIRTUAL USERS COMPLETE"
]
</programlisting>

      <para>The dumpdb command can be used to dump all of the SQLite database
      to the web service console for debugging and the killws command cause
      the web service terminate.</para>
    </section>
  </chapter>

  <chapter>
    <title>Introduction to Analytic Testing (TPROC-H derived from TPC-H) and
    Cloud Queries</title>

    <para>Analytic workloads can also be interchangeably described as Decision
    Support, Data Warehousing or Business Intelligence, the basis of these
    workloads is the ability to process complex ad-hoc queries on large
    volumes of data. In contrast to a transactional workload the focus is upon
    reading as opposed to modifying data and therefore requires a distinct
    approach. The ability of a database to process transactions gives limited
    information towards the ability of a database to support query based
    workloads and vice-versa, therefore both TPROC-C and TPROC-H based
    workloads complement each other in investigating the capabilities of a
    particular database. When reading large volumes of data to satisfy query
    workloads it should be apparent that if multiple CPU cores are available
    reading with a single processing thread is going to leave a significant
    amount of resources underutilized. Consequently the most effective
    Analytic Systems employ a feature called Parallel Query to break down such
    queries into multiple sub tasks to complete the query more quickly.
    Additional features such as column orientation, compression and
    partitioning can also be used to improve parallel query performance.
    Advances in server technologies in particular large numbers of CPU cores
    available with large memory configurations have popularised both in-memory
    and column store technologies as a means to enhance Parallel Query
    performance. Examples of databases supported by HammerDB that support some
    or all of these enhanced query technologies are the Oracle Database, SQL
    Server, Db2, MariaDB and PostgreSQL, databases that do not support any of
    these technologies are single threaded query workloads and cannot be
    expected to complete these workloads as quickly. If you are unfamiliar
    with row-oriented and column-store technologies then it is beneficial to
    read one of the many guides explaining the differences and familiarising
    with the technologies available in the database that you have chosen to
    test. With commercial databases you should also ensure that your license
    includes the ability to run Parallel workloads as you may have a version
    of a database that supports single-threaded workloads only.</para>

    <section>
      <title>What is TPROC-H derived from TPC-H?</title>

      <para>To complement the OLTP type TPROC-C workload HammerDB also
      contains a Fair Use derivation of the decision support based TPC-H
      Benchmark Standard. The HammerDB TPROC-H workload is an open source
      workload derived from the TPC-H Benchmark Standard and as such is not
      comparable to published TPC-H results, as the results do not comply with
      the TPC-H Benchmark Standard. TPROC-H in simple terms can be thought of
      as complementing the workload implemented in TPROC-C related to the
      activities of a wholesale supplier. However, whereas TPROC-C simulates
      an online ordering system TPROC-H represents the typical workload of a
      retailer running analytical queries about their operations. To do this
      TPROC-H is represented by a set of business focused ad-hoc queries (in
      addition to concurrent data updates and deletes) and is measured upon
      the time it takes to complete these queries. In particular the focus is
      upon highly complex queries that require the processing of large volumes
      of data. Also in similarity to TPROC-C the schema size is not fixed and
      is dependent upon a Scale Factor and therefore your schema can also be
      as small or large as you wish with a larger schema requiring a more
      powerful computer system to process the increased data volume for
      queries. However, in contrast to TPROC-C it is not valid to compare the
      test results of query load tests taken at different Scale Factors shown
      as SF in the Schema diagram.</para>

      <figure>
        <title>TPROC-H Schema.</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch9-1.png"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The workload is represented by users executing a stream of 22
      ad-hocs queries against the database with an example query as
      follows:</para>

      <programlisting>-- using 647655760 as a seed to the RNG
 select
        l_returnflag,
        l_linestatus,
        sum(l_quantity) as sum_qty,
        sum(l_extendedprice) as sum_base_price,
        sum(l_extendedprice * (1 - l_discount)) as sum_disc_price,
        sum(l_extendedprice * (1 - l_discount) * (1 + l_tax)) as sum_charge,
        avg(l_quantity) as avg_qty,
        avg(l_extendedprice) as avg_price,
        avg(l_discount) as avg_disc,
        count(*) as count_order 
from
        lineitem 
where
        l_shipdate &lt;= date '1998-12-01' – interval '69' day (3)
group by
        l_returnflag,
        l_linestatus 
order by
        l_returnflag,
        l_linestatus;
</programlisting>

      <para>In measuring the results the key aspect is the time the queries
      take to complete and it is recommended to use the geometric mean of the
      query times for comparison. A typical performance profile is represented
      by the time it takes the system to process a query set from Q1 to Q22
      (run in a pre-determined random order).</para>

      <figure>
        <title>Power Query</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch9-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section>
      <title>Running the Power and Throughput Test and Calculating the
      Geometric Mean</title>

      <para>The audited metric for TPC-H workloads is called QphH, however
      because of the differences in how these workloads are run, in particular
      using bulk operations for data loads it is not recommended that the QphH
      be calculated for HammerDB workloads. Instead it is recommended to
      measure and compare the geometric mean of the power and throughput test
      query times. For the audited results the following 3 aspects of the
      capability of the system to process queries are considered:</para>

      <orderedlist>
        <listitem>
          <para>Database size.</para>
        </listitem>

        <listitem>
          <para>Query processing power of queries in a single stream.</para>
        </listitem>

        <listitem>
          <para>Total query throughput of queries from multiple concurrent
          users.</para>
        </listitem>
      </orderedlist>

      <para>For the multiple concurrent user tests the throughput test always
      follows the power test and the number of Virtual Users is based upon the
      following table where each Stream is processed by a Virtual User in
      HammerDB. This can also serve as a guide when running throughput tests
      with HammerDB taking the metric as the geomean of the query times of the
      slowest virtual user to complete the query set.</para>

      <table>
        <title>Query Streams and Scale Factors</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">SF ( Scale Factor )</entry>

              <entry align="center">S (Streams)</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>100000</entry>

              <entry>11</entry>
            </row>

            <row>
              <entry>30000</entry>

              <entry>10</entry>
            </row>

            <row>
              <entry>10000</entry>

              <entry>9</entry>
            </row>

            <row>
              <entry>3000</entry>

              <entry>8</entry>
            </row>

            <row>
              <entry>1000</entry>

              <entry>7</entry>
            </row>

            <row>
              <entry>300</entry>

              <entry>6</entry>
            </row>

            <row>
              <entry>100</entry>

              <entry>5</entry>
            </row>

            <row>
              <entry>30</entry>

              <entry>4</entry>
            </row>

            <row>
              <entry>10</entry>

              <entry>3</entry>
            </row>

            <row>
              <entry>1</entry>

              <entry>2</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>There is also the availability for a simultaneous data refresh
      set. HammerDB provides full capabilities to run this refresh set both
      automatically as part of a Power test and concurrently with a Throughput
      test. Note however that once a refresh set is run the schema is required
      to be refreshed and it is prudent to backup and restore a HammerDB
      TPROC-H based schema where running a refresh set is planned.</para>
    </section>

    <section>
      <title>Choosing a Database for running TPROC-H workloads</title>

      <para>TPROC-H workloads run complex queries scanning large volumes of
      data and therefore require the use of database features such as parallel
      query and in-memory column stores to maximise performance. With the
      available HammerDB TPROC-H based workloads the three databases that
      support these features are the Enterprise Editions of Oracle, SQL Server
      and Db2 and therefore these databases will deliver the best experience
      for building and running TPROC-H. Over time there has been improvement
      with open-source and open-source derived databases in the ability to run
      TPROC-H workloads. For example PostgreSQL supports Parallel Query and
      the PostgreSQL derived versions of Amazon Redshift and Greenplum offer
      further accelerated query solutions. MySQL does not support an analytic
      storage engine however the MariaDB column store storage is best suited
      for running analytic tests against MySQL. Nevertheless it is known that
      with some or all of the open source solutions a number of queries either
      fail or are extremely long running due to the limitations of the
      databases themselves (and not HammerDB) in optimizing the
      queries.</para>

      <section>
        <title>Oracle</title>

        <para>The Oracle database is fully featured for running TPROC-H based
        workloads and presents two options for configuring the database either
        row oriented parallel query or the In-Memory Column Store (IM column
        store). Both of these configurations are able to run a full TPROC-H
        workload and are configured on the database as opposed to configuring
        with HammerDB.</para>
      </section>

      <section>
        <title>Microsoft SQL Server</title>

        <para>SQL Server is able to support a full TPROC-H workload and offers
        row oriented parallel query as well as in-memory column store
        configured. The clustered columnstore build is selected through the
        HammerDB Build Options.</para>

        <figure>
          <title>Clustered Columnstore</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch9-9.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Db2</title>

        <para>Db2 can support a full TPCH workload through row oriented
        parallel query and Db2 BLU in-memory column store. The column store is
        selected through the Db2 Organize by options.</para>

        <figure>
          <title>Db2 Organize By</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch9-10.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>PostgreSQL</title>

        <para>PostgreSQL supports standard row oriented parallel query. This
        offers significant performance improvement over single-threaded
        queries however not all queries at all schema sizes are expected to
        complete without database error and some run for a significant length
        of time. Options are also available to run the PostgreSQL queries
        against a Greenplum database. It is important to be aware that because
        of the Greenplum MPP architecture there is significant overhead in
        processing INSERT operations and therefore data should be loaded in
        bulk after generating with the HammerDB datagen operation.</para>

        <figure>
          <title>PostgreSQL TPROC-H</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch9-11.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>MySQL / MariaDB</title>

        <para>MySQL does not support row oriented parallel query or a column
        store configuration and therefore queries run against a MySQL database
        are expected to be long-running. However the MySQL compatible MariaDB
        supports a separate installation of a column store based database
        which offers significantly improved query times. However some queries
        will result in database errors or long running queries. This option is
        selected with the Data Warehouse Storage Engine Option.</para>

        <figure>
          <title>MySQL MariaDB TPROC-H</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch9-12.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>
    </section>

    <section>
      <title>Benchmarking Database Cloud Services</title>

      <para>In addition to the TPROC-H workload there are also a set of Cloud
      Analytic Queries made publicly available by Oracle for comparison of
      Cloud Analytic services. These queries run against a derived TPC-H
      schema and are included with HammerDB for running against Oracle, Amazon
      Aurora and Amazon Redshift with Amazon Aurora and Redshift being based
      upon and compatible with MySQL and PostgreSQL respectively. Note however
      that in similarity to MySQL Amazon Aurora does not have the features to
      support analytics such as parallel query or a column store option and
      therefore running the analytic tests against Aurora although possible is
      not likely to generate the best results. Amazon Redshift however is a
      column oriented database based on PostgreSQL and suitable for running
      analytic workloads.</para>

      <para>For the Cloud Analytic workload the Oracle specification requires
      a schema size of 10TB, it is recommended to create the schema with
      HammerDB using the Generating and Bulk Loading Data feature and this
      guide details how to do this for both Oracle and Redshift and this is
      particularly recommended when uploading data to the cloud.</para>

      <para>You are permitted to run both the in-built TPROC-H queries and the
      Cloud Analytic Queries against the same database. This new query set is
      enabled under the TPROC-H Driver Script Options dialog by selecting the
      Cloud Analytic Queries checkbox. This query set reports the geometric
      mean of the completed queries that returns rows for circumstances where
      the query set is run on a scale factor size of less than 10TB. Given the
      similarity of the Oracle implementation to the existing TPROC-H workload
      the following example illustrates running the workload against Amazon
      Redshift.</para>

      <section>
        <title>Redshift Cloud Analytic Workload</title>

        <para>Ensure that your Redshift cluster is active and note your
        Endpoint name given above the cluster properties.</para>

        <figure>
          <title>Redshift console</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch9-13.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Also ensure that access is enabled to the cluster both by
        defining a user and a security group and allowing access through your
        firewall.</para>

        <figure>
          <title>Create Security Group</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch9-14.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Create the TPROC-H schema within Redshift using the HammerDB
        Generating and Bulk Loading Data feature. Under PostgreSQL TPROC-H
        Driver Options use the Redshift Endpoint as your PostgreSQL host and
        5439 as your port. Set the user and password to the credentials you
        have set under the Amazon AWS console. To run the Cloud Analytic
        Workload with HammerDB refer to the following Chapter on How to run an
        Analytic Workload and select the Cloud Analytic Queries and Redshift
        Compatible Checkbox with the reported metric being the geometric mean
        of the query times that complete for the one Virtual User used. Note
        that when running the queries against data sets smaller than the
        specified 10TB this may result in some queries not returning rows,
        therefore for your calculations HammerDB calculates the geometric mean
        only of queries that returned rows.</para>
      </section>
    </section>
  </chapter>

  <chapter>
    <title>How to Run an Analytic Workload</title>

    <para>The basis of Analytic or Decision Support Systems is the ability to
    process complex ad-hoc queries on large volumes of data. Processing this
    amount of data within a single process or thread on traditional
    row-oriented database is time consuming. Consequently it is beneficial
    Parallel Query to break down such queries into multiple sub tasks to
    complex the query more quickly. Additional features such as compression
    and partitioning are also used with Parallel Query to improve performance.
    As a consequence when planning analytic workloads for optimal performance
    you should consider the database features for in-memory and parallel
    execution configuration. In similarity to the HammerDB OLTP workload,
    HammerDB implements a fair usage of a TPC workload however the results
    should not be compared to official published TPC-H results in any
    way.</para>

    <section>
      <title>SUT Database Server Configuration</title>

      <para>For query based workloads there is no requirement for a load
      testing client although you may use one if you wish. It is entirely
      acceptable to run HammerDB directly on the SUT (System Under Test)
      Database system if you wish, the client workload is minimal compared to
      an OLTP workload. In the analytic workload the client sends long running
      queries to the SUT and awaits a response therefore requiring minimal
      resources on the client side. As with an OLTP configuration however the
      database server architecture to be tested must meet the standard
      requirements for a database server system. Similarly the database can be
      installed on any supported operating system, there is no restriction on
      the version of that is required. Before running a HammerDB analytic test
      depending on your configuration you should focus on memory and I/O (disk
      performance). Also in turn the number and type of multi-core and
      multi-threaded processors installed will have a significant impact on
      parallel performance to drive the workload. When using in-memory column
      store features processors that support SIMD/AVX instructions sets are
      also required for the vectorisation of column scans. HammerDB by default
      provides TPROC-H schemas at Scale Factors 1,10,30,100,300 and 1000
      (larger can be configured if required). The Scale Factors correspond to
      the schema size in Gigabytes. As with the official TPROC-H tests the
      results at one schema size should not be compared with the results
      derived with another schema size. As the analytic workload utilizes
      parallel query where available it is possible for a single virtual user
      to use all of the CPU resources on the SUT at any schema size.
      Nevertheless there is still a relation with all of the hardware
      resources available including memory and I/O and a larger system will
      benefit from tests run a larger schema size. The actual sizing of
      hardware resources of hardware resources is beyond the scope of this
      document however at the basic level with traditional parallel execution
      and modern CPU capabilities I/O read performance is typically the
      constraining factor. Note that also in contrast to an OLTP workload high
      throughput transaction log write performance is not a requirement,
      however in similarity to the OLTP workload storage based on SSD disks
      will usually offer significant improvements in performance over standard
      hard disks although in this case it is the benefits of read bandwidth as
      opposed to the IOPs benefits of SSDs for OLTP. When using the in-memory
      column store memory capacity and bandwidth feature and if fully cached
      in memory storage performance is not directly a factor for query
      performance. Nevertheless data loads are an important consideration for
      in-memory data and therefore I/O and SSD read performance remain
      important for loading the data into memory to be available for
      scans.</para>
    </section>

    <section>
      <title>Installation and Configuration</title>

      <para>Before creating a test schema you should ensure that your database
      is configured to process analytic workloads instead of
      transactional.</para>

      <section>
        <title>Oracle</title>

        <para>When your database server is installed you should create a
        tablespace into which the test data will be installed allowing disk
        space according to the guide previously given in this document.</para>

        <programlisting>SQL&gt; create tablespace tpchtab datafile size 20g;

Tablespace created.
</programlisting>

        <para>When using parallel query ensure that the instance is configured
        for parallel execution, noting in particular the value for
        parallel_max_servers.</para>

        <programlisting>SQL&gt; show parameter parallel
NAME                      TYPE        VALUE
------------------------------------ -----------
parallel_max_servers      integer    160
…
parallel_min_servers      integer    16
…
parallel_servers_target   integer    64
parallel_threads_per_cpu  integer    2
</programlisting>

        <para>For testing purposes you can disable parallel execution in a
        particular environment by setting parallel_max_servers to a value of
        zero. An additional parameter that can provide significant benefit to
        the performance of parallel query workloads is
        optimizer_dynamic_sampling. By default this value is set to 2.
        Increasing this value to 4 has been shown to benefit query performance
        however testing the impact of changing this parameter should always be
        done during pre-testing as it may change between Oracle
        releases.</para>

        <programlisting>SQL&gt; alter system set optimizer_dynamic_sampling=4;

System altered.

SQL&gt; show parameter optimizer_dynamic

NAME                       TYPE       VALUE
------------------------------------ ----------- 
optimizer_dynamic_sampling integer    4


</programlisting>

        <para>If using the In-Memory option ensure that the parameter
        inmemory_size has been configured and the database restarted.</para>

        <programlisting>SQL&gt; show parameter inmemory

NAME                             TYPE        VALUE
-------------------------------------------- --------
inmemory_clause_defaultstring
inmemory_force                   string      DEFAULT
inmemory_max_populate_servers    integer     2
inmemory_query                   string      ENABLE
inmemory_size                    big integer 1500M
inmemory_trickle_repopulate      integer     1
_servers_percent    
optimizer_inmemory_aware         boolean     TRUE
</programlisting>

        <para>Then alter the new tablespace containing the schema to be
        in-memory.</para>

        <programlisting>SQL&gt; alter tablespace TPCHTAB default inmemory;
Tablespace altered.
</programlisting>

        <para>As shown the objects created within the tablespace will now be
        configured to be in-memory.</para>

        <para><programlisting>SQL&gt; select tablespace_name, def_inmemory from dba_tablespaces;

TABLESPACE_NAME           DEF_INME
------------------------- --------
SYSTEM                    DISABLED
SYSAUX                    DISABLED
TEMP                      DISABLED
USER                      DISABLED
TPCCTAB                   DISABLED
TPCHTAB                   ENABLED
</programlisting></para>

        <para>For larger schemas both partitioning and compression settings
        (both standard and in-memory) should be considered for query
        tuning.</para>
      </section>

      <section>
        <title>SQL Server</title>

        <para>For SQL Server ensure that the Max Degree of Parallelism is set
        to the maximum number of cores that you wish to process the
        queries.</para>

        <figure>
          <title>Max Degree of Parallelism</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-1.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Db2</title>

        <para>If using DB2 BLU use db2set to set the parameter DB2_WORKLOAD to
        ANALYTICS.</para>

        <programlisting>[db2inst1 ~]$ db2set DB2_WORKLOAD=ANALYTICS
[db2inst1 ~]$ db2stop force
25/05/2016 10:08:22     0   0   SQL1064N  DB2STOP processing was successful.
SQL1064N  DB2STOP processing was successful.
[db2inst1 ~]$ db2start
05/25/2016 10:08:27     0   0   SQL1063N  DB2START processing was successful.
SQL1063N  DB2START processing was successful.
</programlisting>

        <para>In your db2cli.ini set the following parameter for each of the
        databases that you plan to create to test the TPROC-H workload, this
        will prevent failure due to SQLSTATE 01003 “Null values were
        eliminated from the argument of a column function” when running the
        workload thereby preventing the query set from completing.</para>

        <programlisting>[db2inst1 cfg]$ more db2cli.ini 
[TPCH]
IgnoreWarnList="'01003'"
[TPCH1]
IgnoreWarnList="'01003'"
</programlisting>

        <para>When your database server is installed you should create a
        database into which the test data will be installed, for TPROC-H
        workloads a large pagesize is recommended.</para>

        <programlisting>[db2inst1 ~]$ db2 create database tpch pagesize 32 k
DB20000I  The CREATE DATABASE command completed successfully.
</programlisting>
      </section>

      <section>
        <title>PostgreSQL</title>

        <para>The PostgreSQL Server should be at a minimum level of 9.6 that
        supports Parallel Query. The postgresql.conf file should include
        parallelism specific parameters such as follows:</para>

        <programlisting>work_mem = 1000MB                              
max_worker_processes = 16
max_parallel_workers_per_gather = 16
force_parallel_mode = on

</programlisting>
      </section>

      <section>
        <title>MySQL / MariaDB</title>

        <para>To test analytic workloads on a MySQL compatible databases
        MariaDB columnstore is the solution that should be used. Note that
        this is a separate installation from a MySQL or MariaDB installation
        rather than a pluggable storage engine. As MariaDB columnstore is
        based on a columnstore solution called InfiniDB the relevant
        parameters start with infinidb, for example:</para>

        <programlisting># Enable compression by default on create, set to 0 to turn off
infinidb_compression_type=2
# Default for string table threshhold
infinidb_stringtable_threshold=20
# infinidb local query flag
# infinidb_local_query=1
infinidb_diskjoin_smallsidelimit=0
infinidb_diskjoin_largesidelimit=0
infinidb_diskjoin_bucketsize=100
infinidb_um_mem_limit=64000
infinidb_use_import_for_batchinsert=1
infinidb_import_for_batchinsert_delimiter=7
</programlisting>
      </section>
    </section>

    <section>
      <title>Configuring Schema Build Options</title>

      <para>To create the analytic test schema based on the TPROC-H you will
      need to select which benchmark and database you wish to use by choosing
      select benchmark from under the Options menu or under the benchmark
      tree-view. The initial settings are determined by the values in your XML
      configuration files. The following example shows the selection of SQL
      Server however the process is the same for all databases.</para>

      <para><figure>
          <title>Benchmark Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-2.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>To create the TPROC-H schema select the TPROC-H schema options
      menu tab from the benchmark tree-view or the options menu. This menu
      will change dynamically according to your chosen database.</para>

      <para><figure>
          <title>TPROC-H Schema Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-3.PNG"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>If selected from the Options menu the schema options window is
      divided into two sections. The “Build Options” section details the
      general login information and where the schema will be built and the
      “Driver Options” for the Driver Script to run after the schema is built.
      If selected from the benchmark tree-view only the “Build Options” are
      shown and these are the only options of importance at this stage. Note
      that in any circumstance you do not have to rebuild the schema every
      time you change the “Driver Options”, once the schema has been built
      only the “Driver Options” may need to be modified. For the “Build
      Options” fill in the values according to the database where the schema
      will be built as follows.</para>

      <section>
        <title>Oracle Schema Build Options</title>

        <figure>
          <title>Oracle TPROC-H Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-4.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para><table>
            <title>Oracle Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>Oracle Service Name</entry>

                  <entry>The Oracle Service Name is the service name that your
                  load generation server will use to connect to the database
                  running on the SUT database server.</entry>
                </row>

                <row>
                  <entry>System User</entry>

                  <entry>The “system” user or a user with system level
                  privileges</entry>
                </row>

                <row>
                  <entry>System User Password</entry>

                  <entry>The system user password is the password for the
                  “system” user you entered during database creation. The
                  system user already exists in all Oracle databases and has
                  the necessary permissions to create the TPROC-H
                  user.</entry>
                </row>

                <row>
                  <entry>TPROC-H User</entry>

                  <entry>The TPROC-H user is the name of a user to be created
                  that will own the TPROC-H schema. This user can have any
                  name you choose but must not already exist and adhere to the
                  standard rules for naming Oracle users. You may if you wish
                  run the schema creation multiple times and have multiple
                  TPROC-H schemas created with ownership under a different
                  user you create each time.</entry>
                </row>

                <row>
                  <entry>TPROC-H User Password</entry>

                  <entry>The TPROC-H user password is the password to be used
                  for the TPROC-H user you create and must adhere to the
                  standard rules for Oracle user password. You will need to
                  remember the TPROC-H user name and password for running the
                  TPROC-H driver script after the schema is built.</entry>
                </row>

                <row>
                  <entry>TPROC-H Default Tablespace</entry>

                  <entry>The TPROC-H default tablespace is the tablespace that
                  will be the default for the TPROC-H user and therefore the
                  tablespace to be used for the schema creation. The
                  tablespace must have sufficient free space for the schema to
                  be created.</entry>
                </row>

                <row>
                  <entry>TPROC-H Temporary Tablespace</entry>

                  <entry>The TPROC-H temporary tablespace is the temporary
                  tablespace that already exists in the database to be used by
                  the TPROC-H User.</entry>
                </row>

                <row>
                  <entry>TimesTen Database Compatible</entry>

                  <entry>When selected this option means that the Oracle
                  Service Name should be a TimesTen Data Source Name and will
                  grey out non-compatible options.</entry>
                </row>

                <row>
                  <entry>Scale Factor</entry>

                  <entry>The Scale Factor is selected by a radio button with a
                  choice of scale factors of 1,10,30,100,300 and 1000
                  corresponding to 1GB, 10GB, 30GB,100GB and 1000GB
                  respectively, larger schema sizes can also be created with
                  the datagen option. Note that the required space will be
                  larger than these values due to the indexes
                  required.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to the number of cores on your Load
                  Generation Server or SUT if HammerDB is running
                  there.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>

      <section>
        <title>SQL Server Schema Build Options</title>

        <figure>
          <title>SQL Server Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-5.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para><table>
            <title>SQL Server Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>SQL Server</entry>

                  <entry>The Microsoft SQL Server is the host name or host
                  name and instance where the TPROC-H database will be
                  created.</entry>
                </row>

                <row>
                  <entry>TCP</entry>

                  <entry>Use the TCP Protocol</entry>
                </row>

                <row>
                  <entry>SQL Server Port</entry>

                  <entry>When TCP is enabled, the SQL Server Port is the
                  network port that your load generation server will use to
                  connect to the database running on the SUT database server.
                  In most cases this will be the default port of 1433 and will
                  not need to be changed.</entry>
                </row>

                <row>
                  <entry>Azure</entry>

                  <entry>Include the Database name in the connect string
                  typical of Azure connections. To successfully build the
                  schema this database must be created and empty.</entry>
                </row>

                <row>
                  <entry>SQL Server ODBC Driver</entry>

                  <entry>The Microsoft SQL ODBC Driver is the ODBC driver you
                  will use to connect to the SQL Server database. To view
                  which drivers are available on Windows view the ODBC Data
                  Source Administrator Tool.</entry>
                </row>

                <row>
                  <entry>Authentication</entry>

                  <entry>When installing SQL Server on Windows you will have
                  configured SQL Server for Windows or Windows and SQL Server
                  Authentication. On Linux you will be using SQL Server
                  Authentication. If you specify Windows Authentication then
                  SQL Server will use a trusted connection to your SQL Server
                  using your Windows credentials without requiring a username
                  and password. If SQL Server Authentication is specified and
                  SQL Authentication is enabled on your SQL Server then you
                  will be able connect by specifying a username and password
                  that you have already configured on your SQL Server.</entry>
                </row>

                <row>
                  <entry>SQL Server User ID</entry>

                  <entry>The SQL Server User ID is the User ID of a user that
                  you have already created on your SQL Server.</entry>
                </row>

                <row>
                  <entry>SQL Server User Password</entry>

                  <entry>The SQL Server User Password is the Password
                  configured on the SQL Server for the User ID you have
                  specified. Note that when configuring the password on the
                  SQL Server there is a checkbox that when selected enforces
                  more complex rules for passwords or if unchecked enables a
                  simple password such as “admin”.</entry>
                </row>

                <row>
                  <entry>SQL Server TPCH Database</entry>

                  <entry>The SQL Server Database is the name of the Database
                  to be created on the SQL Server to contain the schema. If
                  this database does not already exist then HammerDB will
                  create it, if the database does already exist and the
                  database is empty then HammerDB will use this existing
                  database. Therefore if you wish to create a particular
                  layout or schema then pre-creating the database and using
                  this database is an advanced method to use this
                  configuration.</entry>
                </row>

                <row>
                  <entry>MAXDOP</entry>

                  <entry>The MAXDOP setting defines the maximum degree of
                  parallelism to be set as a default on the schema
                  objects.</entry>
                </row>

                <row>
                  <entry>Clustered Columnstore</entry>

                  <entry>This option selects the database to be created with
                  in-memory clustered columnstore indexes.</entry>
                </row>

                <row>
                  <entry>Scale Factor</entry>

                  <entry>The Scale Factor is selected by a radio button with a
                  choice of scale factors of 1,10,30,100,300 and 1000
                  corresponding to 1GB, 10GB, 30GB,100GB and 1000GB
                  respectively, larger schema sizes can also be created with
                  the datagen option. Note that the required space will be
                  larger than these values due to the indexes
                  required.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to the number of cores on your Load
                  Generation Server or SUT if HammerDB is running
                  there.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>

      <section>
        <title>Db2 Schema Build Options</title>

        <figure>
          <title>Db2 Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-6.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para><table>
            <title>Db2 Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>Db2 User</entry>

                  <entry>The name of the operating system user to connect to
                  the DB2 database for example db2inst1.</entry>
                </row>

                <row>
                  <entry>Db2 Password</entry>

                  <entry>The password for the operating system DB2 user by
                  default “ibmdb2”</entry>
                </row>

                <row>
                  <entry>Db2 Database</entry>

                  <entry>The name of the Db2 database that you have already
                  created, for example “tpcc”</entry>
                </row>

                <row>
                  <entry>Db2 Default Tablespace</entry>

                  <entry>The name of the existing tablespace where tables
                  should be located if a specific tablespace has not been
                  defined for that table in the tablespace list. The default
                  is “USERSPACE1”.</entry>
                </row>

                <row>
                  <entry>Db2 Organize By</entry>

                  <entry>The Organize by option is selected by a radio button
                  and determines an optional organize by clause to be
                  specified when creating the tables. The database version
                  must be able to accept the option chosen and therefore the
                  recommended choice is NONE to accept the defaults. When the
                  setting DB2_WORKLOAD is set to analytics for example the
                  default is configuration is for columnar storage. If for
                  example this parameter is set you can then choose ROW
                  configuration even when DB2_WORKLOAD is set to analytics to
                  create row organized tables. The DATE option is mutually
                  exclusive to the column store option however creates a ROW
                  organized table that is organized by date which can
                  accelerate some queries when row organized.</entry>
                </row>

                <row>
                  <entry>Scale Factor</entry>

                  <entry>The Scale Factor is selected by a radio button with a
                  choice of scale factors of 1,10,30,100,300 and 1000
                  corresponding to 1GB, 10GB, 30GB,100GB and 1000GB
                  respectively, larger schema sizes can also be created with
                  the datagen option. Note that the required space will be
                  larger than these values due to the indexes
                  required.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to the number of cores on your Load
                  Generation Server or SUT if HammerDB is running
                  there.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>

      <section>
        <title>MySQL Schema Build Options</title>

        <para><figure>
            <title>MySQL Build Options</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="docs/images/ch13-8.PNG"/>
              </imageobject>
            </mediaobject>
          </figure></para>

        <para><table>
            <title>MySQL Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>MySQL Host</entry>

                  <entry>The MySQL Host Name is the host name of the SUT
                  database server.</entry>
                </row>

                <row>
                  <entry>MySQL Port</entry>

                  <entry>The MySQL Port is the network port on the SUT
                  database server. In most cases this will be the default port
                  of 3306.</entry>
                </row>

                <row>
                  <entry>MySQL User</entry>

                  <entry>The MySQL User is the user which has permission to
                  create a database and you previously granted access to from
                  the load generation server. The root user already exists in
                  all MySQL databases and has the necessary permissions to
                  create the TPROC-H database.</entry>
                </row>

                <row>
                  <entry>MySQL User Password</entry>

                  <entry>The MySQL user password is the password for the user
                  defined as the MySQL User. You will need to remember the
                  MySQL user name and password for running the TPROC-H driver
                  script after the database is built.</entry>
                </row>

                <row>
                  <entry>MySQL Database</entry>

                  <entry>The MySQL Database is the database that will be
                  created containing the TPROC-H schema creation. There must
                  have sufficient free space for the database to be
                  created.</entry>
                </row>

                <row>
                  <entry>Data Warehouse Storage Engine</entry>

                  <entry>Use the "show engine" command to display available
                  storage engines and select a storage engine that supports
                  analytics. For MariaDB columnstore specify.
                  "Columnstore"</entry>
                </row>

                <row>
                  <entry>Scale Factor</entry>

                  <entry>The Scale Factor is selected by a radio button with a
                  choice of scale factors of 1,10,30,100,300 and 1000
                  corresponding to 1GB, 10GB, 30GB,100GB and 1000GB
                  respectively, larger schema sizes can also be created with
                  the datagen option. Note that the required space will be
                  larger than these values due to the indexes
                  required.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to the number of cores on your Load
                  Generation Server or SUT if HammerDB is running
                  there.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>

      <section>
        <title>PostgreSQL Schema Build Options</title>

        <figure>
          <title>PostgreSQL Build Options</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-7.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para><table>
            <title>PostgreSQL Build Options</title>

            <tgroup cols="2">
              <thead>
                <row>
                  <entry align="center">Option</entry>

                  <entry align="center">Description</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>PostgreSQL Host</entry>

                  <entry>The host name of the SUT running PostgreSQL.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Port</entry>

                  <entry>The port of the PostgreSQL service. By default this
                  will be 5432 for a standard PostgreSQL installation or 5444
                  for EnterpriseDB.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Superuser</entry>

                  <entry>The PostgreSQL Superuser is a user with sufficient
                  privileges to create both new users (roles) and databases to
                  enable the creation of the test schema.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Superuser Password</entry>

                  <entry>The PostgreSQL Superuser Password is the password for
                  the PostgreSQL superuser which will have been defined during
                  installation. If you have forgotten the password it can be
                  reset from a psql prompt that has logged in from a trusted
                  connection therefore requiring no password using postgres=#
                  alter role postgres password ‘postgres’;</entry>
                </row>

                <row>
                  <entry>PostgreSQL Default Database</entry>

                  <entry>The PostgreSQL default databases is the database to
                  specify for the superuser connection. Typically this will be
                  postgres for a standard PostgreSQL installation or edb for
                  EnterpriseDB.</entry>
                </row>

                <row>
                  <entry>PostgreSQL User</entry>

                  <entry>The PostgreSQL User is the user (role) that will be
                  created that owns the database containing the TPROC-H
                  schema.</entry>
                </row>

                <row>
                  <entry>PostgreSQL User Password</entry>

                  <entry>The PostgreSQL User Password is the password that
                  will be specified for the PostgreSQL user when it is
                  created.</entry>
                </row>

                <row>
                  <entry>PostgreSQL Database</entry>

                  <entry>The PostgreSQL Database is the database that will be
                  created and owned by the PostgreSQL User that contains the
                  TPROC-H schema.</entry>
                </row>

                <row>
                  <entry>Greenplum Database Compatible</entry>

                  <entry>Choosing Greenplum Database Compatible creates a
                  schema with Greenplum Database Options. Building the schema
                  by inserting into Greenplum is not recommended and instead a
                  bulk load of data created with the datagen option should be
                  used.</entry>
                </row>

                <row>
                  <entry>Greenplum Compressed Columns</entry>

                  <entry>Becomes active when Greenplum Database Compatible is
                  selected and configures the columns in a compressed
                  format.</entry>
                </row>

                <row>
                  <entry>Scale Factor</entry>

                  <entry>The Scale Factor is selected by a radio button with a
                  choice of scale factors of 1,10,30,100,300 and 1000
                  corresponding to 1GB, 10GB, 30GB,100GB and 1000GB
                  respectively, larger schema sizes can also be created with
                  the datagen option. Note that the required space will be
                  larger than these values due to the indexes
                  required.</entry>
                </row>

                <row>
                  <entry>Virtual Users to Build Schema</entry>

                  <entry>The Virtual Users to Build Schema is the number of
                  Virtual Users to be created on the Load Generation Server
                  that will complete your multi-threaded schema build. You
                  should set this value to the number of cores on your Load
                  Generation Server or SUT if HammerDB is running
                  there.</entry>
                </row>
              </tbody>
            </tgroup>
          </table></para>
      </section>
    </section>

    <section>
      <title>Creating the Schema</title>

      <para>To begin the schema creation select the Build Option from the
      tree-view.</para>

      <figure>
        <title>Build TPROC-H Schema</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-9.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>A dialog box is shown to confirm the options selected.</para>

      <figure>
        <title>Create Schema</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-10.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When you click Yes HammerDB will login to your chosen service name
      with a monitor thread as the system user and create the user with the
      password you have chosen. It will then log out and log in again as your
      chosen user, create the tables and then load the region and nation table
      data before waiting and monitoring the other threads. The worker threads
      will wait for the monitor thread to complete its initial work.
      Subsequently the worker threads will create and insert the data for
      their assigned warehouses. There are no intermediate data files or
      manual builds required, HammerDB will both create and load your
      requested data dynamically. Data is inserted in a batch format for
      optimal performance, however for larger schemas doing a bulk load of
      data created with the datagen feature will be a faster way to create the
      schema as it bypasses the logging and consistency checks of the insert
      based load.</para>

      <figure>
        <title>Schema Build Start</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-11.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When the workers are complete the monitor thread will create the
      indexes and gather the statistics. When complete Virtual User 1 will
      display the message TPCH SCHEMA COMPLETE and all virtual users will show
      that they completed their action successfully. Pressing the red button
      will destroy the Virtual Users.</para>

      <figure>
        <title>Schema Build Complete</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-12.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <section>
        <title>Verifying and Backing-Up the Oracle Schema</title>

        <para>The schema build is now complete with the following tables
        created and populated. Note that in example below the tables have
        inherited the tablespaces’s in-memory configuration without additional
        settings. If required the inmemory_priority can also be set at this
        point in time.</para>

        <programlisting>  1* select table_name, num_rows, inmemory, inmemory_priority from user_tables
SQL&gt; /

TABLE_NAME                       NUM_ROWS INMEMORY INMEMORY_PRIORITY
------------------------------ ---------- -------- -----------------
ORDERS                            1500000 ENABLED  NONE
PARTSUPP                           800000 ENABLED  NONE
CUSTOMER                           150000 ENABLED  NONE
PART                               200000 ENABLED  NONE
SUPPLIER                            10000 ENABLED  NONE
NATION                                 25 ENABLED  NONE
REGION5                                 5 ENABLED  NONE
LINEITEM                          6003632 ENABLED  NONE

</programlisting>

        <para>You can verify the contents with SQL*PLUS as the newly created
        user.</para>

        <programlisting>SQL&gt; select tname, tabtype from tab;

TNAME                          TABTYPE
------------------------------ -------
CUSTOMER                       TABLE
LINEITEM                       TABLE
NATION                         TABLE
ORDERS                         TABLE
PART                           TABLE
PARTSUPP                       TABLE
REGION                         TABLE
SUPPLIER                       TABLE

8 rows selected.

SQL&gt; select * from customer where rownum = 1;

 C_CUSTKEY C_MKTSEGME C_NATIONKEY C_NAME
---------- ---------- ----------- -------------------------
C_ADDRESS C_PHONE  C_ACCTBAL
---------------------------------------- --------------- ----------
C_COMMENT
--------------------------------------------------------------------------------
    112098 AUTOMOBILE       22 Customer#000112098
v,QXkbT8YhhyQYXjX4Ag3iFPQq0gbfZNo7 776-160-1375    5010.19
carefully pending instructions detect slyly-- pending deposits acco

SQL&gt; select index_name, index_type from ind;

INDEX_NAME       INDEX_TYPE
------------------------------
REGION_PK        NORMAL
NATION_PK        NORMAL
SUPPLIER_PK      NORMAL
PARTSUPP_PK      NORMAL
PART_PK          NORMAL
ORDERS_PK        NORMAL
LINEITEM_PK      NORMAL
CUSTOMER_PK      NORMAL

8 rows selected.
</programlisting>

        <para>At this point the data creation is complete and you are ready to
        start running a performance test. Before doing so note that as this is
        a query based workload you have the potential to run multiple tests
        and it will return the same results as the data is not modified during
        tests, however there is one exception, under the Driver Options the
        option to choose a Refresh Function. Further details will be given on
        the refresh function in the next section however at this point it is
        sufficient to note that the refresh function when enabled will modify
        data and no two same refresh functions can be run on the same data
        set. This means if you choose to include a refresh function and then
        attempt to re-run the test you will receive an error as the data has
        been modified. This means you have a number of options. Firstly (and
        recommended) you can use datapump to backup and restore your schema.
        To do this create a directory as follows to reference a file system
        folder you have already created (or use the pre-existing
        DATA_PUMP_DIR)</para>

        <programlisting>SQL&gt; create directory dump_dir1 as '/u02/app/oracle/dumpdir';

Directory created.

Then use datapump to export your schema to this directory before you have run any workloads with a refresh function:
[oracle@MERLIN oracle]$ expdp \"sys/oracle@pdb1 as sysdba\" schemas=tpch content=all directory=DUMP_DIR1 logfile=dp.log

Export: Release 12.1.0.2.0 - Production on Wed Sep 17 11:23:32 2014

Copyright (c) 1982, 2014, Oracle and/or its affiliates.  All rights reserved.

Connected to: Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 - 64bit Production
With the Partitioning, OLAP, Advanced Analytics and Real Application Testing options
Starting "SYS"."SYS_EXPORT_SCHEMA_01":  "sys/********@pdb1 AS SYSDBA" schemas=tpch content=all directory=DUMP_DIR1 logfile=dp.log 
Estimate in progress using BLOCKS method...
Processing object type SCHEMA_EXPORT/TABLE/TABLE_DATA
Total estimation using BLOCKS method: 1.159 GB
Processing object type SCHEMA_EXPORT/USER
Processing object type SCHEMA_EXPORT/SYSTEM_GRANT
Processing object type SCHEMA_EXPORT/ROLE_GRANT
Processing object type SCHEMA_EXPORT/DEFAULT_ROLE
Processing object type SCHEMA_EXPORT/TABLESPACE_QUOTA
Processing object type SCHEMA_EXPORT/PRE_SCHEMA/PROCACT_SCHEMA
Processing object type SCHEMA_EXPORT/TABLE/TABLE
Processing object type SCHEMA_EXPORT/TABLE/INDEX/INDEX
Processing object type SCHEMA_EXPORT/TABLE/CONSTRAINT/CONSTRAINT
Processing object type SCHEMA_EXPORT/TABLE/INDEX/STATISTICS/INDEX_STATISTICS
Processing object type SCHEMA_EXPORT/TABLE/CONSTRAINT/REF_CONSTRAINT
Processing object type SCHEMA_EXPORT/TABLE/STATISTICS/TABLE_STATISTICS
Processing object type SCHEMA_EXPORT/STATISTICS/MARKER
. . exported "TPCH"."LINEITEM"                           746.2 MB 6003632 rows
. . exported "TPCH"."ORDERS"                             165.4 MB 1500000 rows
. . exported "TPCH"."PARTSUPP"                           112.7 MB  800000 rows
. . exported "TPCH"."PART"                               25.99 MB  200000 rows
. . exported "TPCH"."CUSTOMER"                           23.45 MB  150000 rows
. . exported "TPCH"."SUPPLIER"                           1.430 MB   10000 rows
. . exported "TPCH"."NATION"                             9.125 KB      25 rows
. . exported "TPCH"."REGION"                             6.476 KB       5 rows
Master table "SYS"."SYS_EXPORT_SCHEMA_01" successfully loaded/unloaded
******************************************************************************
Dump file set for SYS.SYS_EXPORT_SCHEMA_01 is:
  /u02/app/oracle/dumpdir/expdat.dmp
Job "SYS"."SYS_EXPORT_SCHEMA_01" successfully completed at Wed Sep 17 11:24:10 2014 elapsed 0 00:00:36
</programlisting>

        <para>After you have run a workload with a refresh function drop the
        TPROC-H user as follows:</para>

        <programlisting>SQL&gt; drop user tpch cascade;

User dropped.
</programlisting>

        <para>Then re-import the export file you took prior to running the
        refresh function:</para>

        <programlisting>[oracle@MERLIN oracle]$ impdp \"sys/oracle@pdb1 as sysdba\" schemas=tpch content=all directory=DUMP_DIR1 logfile=dp1.log

Import: Release 12.1.0.2.0 - Production on Wed Sep 17 11:37:54 2014

Copyright (c) 1982, 2014, Oracle and/or its affiliates.  All rights reserved.

Connected to: Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 - 64bit Production
With the Partitioning, OLAP, Advanced Analytics and Real Application Testing options
Master table "SYS"."SYS_IMPORT_SCHEMA_04" successfully loaded/unloaded
Starting "SYS"."SYS_IMPORT_SCHEMA_04":  "sys/********@pdb1 AS SYSDBA" schemas=tpch content=all directory=DUMP_DIR1 logfile=dp1.log 
Processing object type SCHEMA_EXPORT/USER
Processing object type SCHEMA_EXPORT/SYSTEM_GRANT
Processing object type SCHEMA_EXPORT/ROLE_GRANT
Processing object type SCHEMA_EXPORT/DEFAULT_ROLE
Processing object type SCHEMA_EXPORT/TABLESPACE_QUOTA
Processing object type SCHEMA_EXPORT/PRE_SCHEMA/PROCACT_SCHEMA
Processing object type SCHEMA_EXPORT/TABLE/TABLE
Processing object type SCHEMA_EXPORT/TABLE/TABLE_DATA
. . imported "TPCH"."LINEITEM"                           746.2 MB 6003632 rows
. . imported "TPCH"."ORDERS"                             165.4 MB 1500000 rows
. . imported "TPCH"."PARTSUPP"                           112.7 MB  800000 rows
. . imported "TPCH"."PART"                               25.99 MB  200000 rows
. . imported "TPCH"."CUSTOMER"                           23.45 MB  150000 rows
. . imported "TPCH"."SUPPLIER"                           1.430 MB   10000 rows
. . imported "TPCH"."NATION"                             9.125 KB      25 rows
. . imported "TPCH"."REGION"                             6.476 KB       5 rows
Processing object type SCHEMA_EXPORT/TABLE/INDEX/INDEX
Processing object type SCHEMA_EXPORT/TABLE/CONSTRAINT/CONSTRAINT
Processing object type SCHEMA_EXPORT/TABLE/INDEX/STATISTICS/INDEX_STATISTICS
Processing object type SCHEMA_EXPORT/TABLE/CONSTRAINT/REF_CONSTRAINT
Processing object type SCHEMA_EXPORT/TABLE/STATISTICS/TABLE_STATISTICS
Processing object type SCHEMA_EXPORT/STATISTICS/MARKER
Job "SYS"."SYS_IMPORT_SCHEMA_04" successfully completed at Wed Sep 17 11:38:40 2014 elapsed 0 00:00:44
</programlisting>

        <para>You only need to export once and can then re-import as many
        times as you wish to run the successfully refresh function.</para>

        <para>Secondly another option you have is to use dbms_metadata to
        capture the table definitions and then use SQL*Loader to export and
        import the data using the datagen created data. Finally if you have
        the flashback table feature enabled you can note the time that you
        start running a test with a refresh function and then flashback the
        LINEITEM and ORDERS table to their previous state before the test, for
        example:</para>

        <programlisting>flashback table lineitem to timestamp TO_TIMESTAMP('17-SEP-14 11.41.00.00 AM')</programlisting>

        <para>Whichever method you use, ensure that if you wish to run the
        refresh function you are prepared to restore your schema to the
        previous state before running subsequent tests.</para>
      </section>

      <section>
        <title>Verifying and Backing Up the SQL Server Schema</title>

        <para>Once created you can verify the schema with SSMS or
        sqlcmd.</para>

        <programlisting>C:\Users&gt;sqlcmd -S (local)\SQLDEVELOP -E -Q "use tpch; select name from sys.tables"
Changed database context to 'tpch'.
name

--------------------------------------------------------------------------------
customer
lineitem
nation
part
partsupp
region
supplier
orders

(8 rows affected)

</programlisting>

        <para>At this point the data creation is complete and you are ready to
        start running a performance test. Before doing so note that as this is
        a query based workload you have the potential to run multiple tests
        and it will return the same results as the data is not modified during
        tests, however there is one exception, under the Driver Options the
        option to choose a Refresh Function. Further details will be given on
        the refresh function in the next section however at this point it is
        sufficient to note that the refresh function when enabled will modify
        data and no two same refresh functions can be run on the same data
        set. This means if you choose to include a refresh function and then
        attempt to re-run the test you will receive an error as the data has
        been modified. Therefore you should backup your schema before running
        a workload.</para>

        <figure>
          <title>Backup SQL Server</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-13.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>SQL Server will notify when the backup is successful.</para>

        <figure>
          <title>Backup successful</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-14.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>The restore can also be selected from the tasks option.</para>

        <figure>
          <title>Restore SQL Server</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-15.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>and notification given when the database is restored.</para>

        <figure>
          <title>Restore successful</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-16.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Verifying and Backing up the Db2 Schema</title>

        <para>The schema build is now complete with the following tables
        created and populated with the example showing a scale factor 10
        schema.</para>

        <programlisting>db2 =&gt; select tabname, card from syscat.tables where tabschema = 'DB2INST1'

TABNAME                                            CARD  
---------------------------------- --------------------
CUSTOMER                                        1500000
LINEITEM                                       60001587
NATION                                               25
ORDERS                                         15000000
PART                                            2000000
PARTSUPP                                        8000000
REGION                                                5
SUPPLIER                                         100000

8 record(s) selected.

db2 =&gt; select * from customer fetch first row only

C_CUSTKEY   C_NAME                    C_ADDRESS     C_NATIONKEY C_PHONE         C_ACCTBAL             C_MKTSEGMENT C_COMMENT                                                                                                             
----------- ------------------------- ---------------------------------------- ----------- --------------- ------------------------ ------------ -------------------------------------------------------
    1128378 Customer#001128378        OzpJsusYMT              6 651-964-1273    +9.57891000000000E+003 HOUSEHOLD    ironic requests above the furiously special foxes wake                                                                

  1 record(s) selected.

db2 =&gt; 

</programlisting>

        <para>At this point the data creation is complete and you are ready to
        start running a performance test. Before doing so note that as this is
        a query based workload you have the potential to run multiple tests
        and it will return the same results as the data is not modified during
        tests, however there is one exception, under the Driver Options the
        option to choose a Refresh Function. Further details will be given on
        the refresh function in the next section however at this point it is
        sufficient to note that the refresh function when enabled will modify
        data and no two same refresh functions can be run on the same data
        set. This means if you choose to include a refresh function and then
        attempt to re-run the test you will receive an error as the data has
        been modified. This means that it is strongly recommended to backup or
        export your data before running a refresh function to ensure that if
        you wish to run the refresh function multiple times you are prepared
        to restore your schema to the previous state before running subsequent
        tests.</para>

        <programlisting>$ db2 backup db tpch to /opt/db2/backup

Backup successful. The timestamp for this backup image is : 20180417181222

$ db2 restore db tpch from /opt/db2/backup replace existing
SQL2539W  The specified name of the backup image to restore is the same as the
name of the target database.  Restoring to an existing database that is the
same as the backup image database will cause the current database to be
overwritten by the backup version.
DB20000I  The RESTORE DATABASE command completed successfully.

</programlisting>

        <para>It is useful to reiterate that before running a query test for
        all configurations you must make the following setting in the
        sb2cli.ini file.</para>

        <programlisting>[db2inst1 cfg]$ more db2cli.ini 
[TPCH]
IgnoreWarnList="'01003'"

</programlisting>

        <para>Failure to add this setting for each virtual user will result in
        the query set failing with the following error.</para>

        <programlisting>Error in Virtual User 3: [IBM][CLI Driver][DB2/NT64] SQLSTATE 01003: Null values were eliminated from the argument of a column function. </programlisting>
      </section>

      <section>
        <title>Verifying and Backing up the MySQL Schema</title>

        <para>The schema build is now complete with the following tables
        created and populated with the example showing a scale factor 1
        schema.</para>

        <programlisting>MariaDB [(none)]&gt; show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| performance_schema |
| tpch               |
+--------------------+
4 rows in set (0.00 sec)

MariaDB [(none)]&gt; use tpch;
Database changed
MariaDB [tpch]&gt; show tables;
+----------------+
| Tables_in_tpch |
+----------------+
| CUSTOMER       |
| LINEITEM       |
| NATION         |
| ORDERS         |
| PART           |
| PARTSUPP       |
| REGION         |
| SUPPLIER       |
+----------------+
8 rows in set (0.00 sec)</programlisting>

        <para>At this point the data creation is complete and you are ready to
        start running a performance test. Before doing so note that as this is
        a query based workload you have the potential to run multiple tests
        and it will return the same results as the data is not modified during
        tests, however there is one exception, under the Driver Options the
        option to choose a Refresh Function. Further details will be given on
        the refresh function in the next section however at this point it is
        sufficient to note that the refresh function when enabled will modify
        data and no two same refresh functions can be run on the same data
        set. This means if you choose to include a refresh function and then
        attempt to re-run the test you will receive an error as the data has
        been modified. This means that it is strongly recommended to backup or
        export your data before running a refresh function to ensure that if
        you wish to run the refresh function multiple times you are prepared
        to restore your schema to the previous state before running subsequent
        tests.</para>

        <programlisting>./client/mysqldump -u root -pmysql tpch &gt; backup-tpch.sql

./client/mysql -u root -pmysql
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 16
Server version: 10.1.25-MariaDB Source distribution

Copyright (c) 2000, 2017, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]&gt; create database tpch;
Query OK, 1 row affected (0.00 sec)

MariaDB [(none)]&gt; Bye
./client/mysql -u root -pmysql tpch &lt; backup-tpch.sql 

./client/mysql -u root -pmysql
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 18
Server version: 10.1.25-MariaDB Source distribution

Copyright (c) 2000, 2017, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]&gt; use tpch
Database changed
MariaDB [tpch]&gt; show tables;
+----------------+
| Tables_in_tpch |
+----------------+
| CUSTOMER       |
| LINEITEM       |
| NATION         |
| ORDERS         |
| PART           |
| PARTSUPP       |
| REGION         |
| SUPPLIER       |
+----------------+
8 rows in set (0.00 sec)

MariaDB [tpch]&gt; select count(*) from LINEITEM;
+----------+
| count(*) |
+----------+
|  6000385 |
+----------+
1 row in set (0.00 sec)</programlisting>
      </section>

      <section>
        <title>Verifying and Backing up the PostgreSQL Schema</title>

        <para>The schema build is now complete with the following tables
        created and populated with the example showing a scale factor 1
        schema.</para>

        <programlisting>$ ./bin/psql -d tpch
psql (10.1)
Type "help" for help.
tpch=# select relname, n_tup_ins - n_tup_del as rowcount from pg_stat_user_tables;
 relname  | rowcount 
----------+----------
 nation   |       25
 lineitem |  6000773
 orders   |  1497000
 customer |   150000
 region   |        5
 supplier |    10000
 part     |   200000
 partsupp |   800000
(8 rows)

tpch=# 
</programlisting>

        <para>At this point the data creation is complete and you are ready to
        start running a performance test. Before doing so note that as this is
        a query based workload you have the potential to run multiple tests
        and it will return the same results as the data is not modified during
        tests, however there is one exception, under the Driver Options the
        option to choose a Refresh Function. Further details will be given on
        the refresh function in the next section however at this point it is
        sufficient to note that the refresh function when enabled will modify
        data and no two same refresh functions can be run on the same data
        set. This means if you choose to include a refresh function and then
        attempt to re-run the test you will receive an error as the data has
        been modified. This means that it is strongly recommended to backup or
        export your data before running a refresh function to ensure that if
        you wish to run the refresh function multiple times you are prepared
        to restore your schema to the previous state before running subsequent
        tests.</para>

        <programlisting>pgsql$ ./bin/pg_dump tpch &gt; pgdumpfile

pgsql$ ./bin/psql 
psql (10.1)
Type "help" for help.

# drop database tpch;
DROP DATABASE
# drop role tpch;
DROP ROLE

# create user tpch password 'tpch';
CREATE ROLE
# create database tpch owner tpch;
CREATE DATABASE


pgsql$ cat pgdumpfile | ./bin/psql tpch
SET
SET
SET
SET
....</programlisting>
      </section>
    </section>

    <section>
      <title>Configuring Driver Script Options</title>

      <para>To select the driver script options select Options from under the
      Driver Script heading in the tree-view.</para>

      <figure>
        <title>Driver Script Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-17.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This displays the Driver Script Options dialog. The connection
      options are common to the Schema Build Dialog in addition to new Driver
      Options.</para>

      <figure>
        <title>TPROC-H Driver Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-18.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <table>
        <title>Driver Script Options</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Option</entry>

              <entry align="center">Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>Scale Factor</entry>

              <entry>Although not visible under the Driver Options the Scale
              Factor value is also inherited from the Build Options and must
              be the set to the same value for running the Driver Script as
              was used for the Build. This option is required in the Driver
              Script when the refresh function is run to ensure that the data
              is created to insert in the correction location without errors.
              The Scale Factor is also used as input to some queries. This is
              especially important if you have restarted HammerDB as you may
              need to set the Scale Factor in the Build Options again.</entry>
            </row>

            <row>
              <entry>Total Query Sets per User</entry>

              <entry>A Query Set is a sequence of 22 queries. The Total number
              of query sets is the number of times after logging on that the
              virtual user completes an entire sequence of queries before
              logging off again. The difference between this and using
              iterations value in the Virtual User options is that the virtual
              user only logs on and off once and completes all of the query
              sets in between whereas with the iterations value the entire
              script is run multiple times.</entry>
            </row>

            <row>
              <entry>Exit on Database Error</entry>

              <entry>Exit on Database Error is shown as the parameter
              RAISEERROR in the Driver Script. RAISEERROR impacts the
              behaviour of an individual virtual user on detecting a database
              error. If set to TRUE on detecting an error the user will report
              the error into the HammerDB console and then terminate
              execution. If set to FALSE the virtual user will ignore the
              error and proceed with executing the next transaction. It is
              therefore important to be aware that if set to FALSE firstly if
              there has been a configuration error resulting in repeated
              errors then the workload might not be reported accurately and
              secondly you may not be aware of any occasional errors being
              reported as they are silently ignored.</entry>
            </row>

            <row>
              <entry>Verbose Output</entry>

              <entry>Verbose Output is shown as VERBOSE in the Driver Script.
              Setting this value to TRUE will print both the Queries and their
              results for each virtual user however will add to the Query time
              by the time required to print the results.</entry>
            </row>

            <row>
              <entry>Refresh Function</entry>

              <entry>The refresh function checkbox corresponds to refresh_on
              in the Driver Script. When this checkbox is enabled the first
              virtual user will run the refresh function as opposed to running
              a query set. Note that if you choose only one virtual user and
              select the refresh function checkbox then your virtual user will
              run a power test as detailed further in this document. The
              refresh function as the name implies inserts and deletes rows
              from the ORDERS and LINEITEM tables and the times of this
              function are required as input to calculating the QphH.</entry>
            </row>

            <row>
              <entry>Number of Update Sets/Trickle Refresh Delay(ms)/Refresh
              Verbose</entry>

              <entry>If you have enabled the refresh function then the values
              for Number of Update Sets/Trickle Refresh Delay(ms)/Refresh
              Verbose become active and these correspond to update_sets
              trickle_refresh and REFRESH_VERBOSE in the driver script
              respectively. The update sets determines how many times the
              virtual users will cycle through the refresh functions whilst
              noting that the function always starts at 1 and therefore cannot
              be restarted against the same schema until the schema has been
              refreshed. The Trickle Refresh Delay value sets the delay
              between each insert and delete with a default of 1 second
              ensuring that the refresh function does not place a significant
              load on the system, The Refresh Verbose value means that the
              virtual user running the refresh function reports on its
              activities.</entry>
            </row>

            <row>
              <entry>Cloud Analytic Queries (Oracle MySQL PostgreSQL
              Only)</entry>

              <entry>When selected this option loads a driver script that runs
              the sequence of 13 Oracle Cloud Analytic Queries.</entry>
            </row>

            <row>
              <entry>Degree of Parallelism (Oracle, Db2 and PostgreSQL
              Only)</entry>

              <entry>For Oracle Degree of Parallelism defines the number of
              Parallel Execution Server processes that the Queries will be
              executed with. The Degree of Parallelism is defined as the
              degree of parallel in the driver script. You should consult a
              good reference on Parallel Execution as the actual execution
              environment is more complex including both Producer and Consumer
              Parallel Execution Servers. This value will be determined by
              your available hardware resources and may be different for both
              the Power and Throughput tests. HammerDB will ensure that the
              test will run at your chosen degree of parallelism (also
              dependant on your settings of parallel_min and parallel_max
              servers). For Db2 The Degree of Parallelism is the value used
              for the command “SET CURRENT DEGREE” in the driver script and
              determines the level of parallelism used in executing the
              queries. For PostgreSQL the Degree of Parallelism sets the
              max_parallel_workers_per_gather parameter for the sessions
              executing the queries.</entry>
            </row>

            <row>
              <entry>MAXDOP (SQL Server Only)</entry>

              <entry>The MAXDOP setting defines the Maximum degree of
              parallelism to be set as a default on the schema
              objects.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section>
      <title>Loading the Driver Script</title>

      <para>After selected the Driver Script Options the Driver Script is
      loaded. The configured options can be seen in the Driver Script window
      and also modified directly there. The Load option can also be used to
      refresh the script to the configured Options. Pay particular attention
      to the Scale Factor value shown as "scale_factor" if different from the
      schema that you have loaded. The "scale factor" value is inherited from
      the schema build so you may have to change it manually in the script to
      the same size of the schema that you paln to test.</para>

      <figure>
        <title>Driver Script Loaded</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-19.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </section>

    <section>
      <title>Configure Virtual Users</title>

      <para>Select Virtual User Options from the tree-view.</para>

      <figure>
        <title>Virtual User Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-20.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This displays the Virtual User Options dialog. For Analytic
      workloads it is recommended that only one Virtual User is selected for
      initial testing. If you wish to see the times for individual queries
      rather than just the query set you will also need to write to the
      log.</para>

      <figure>
        <title>Virtual User Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-21.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The values have the following meaning.</para>

      <para><table>
          <title>Virtual User Options</title>

          <tgroup cols="2">
            <thead>
              <row>
                <entry align="center">Option</entry>

                <entry align="center">Description</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Virtual Users</entry>

                <entry>The number of Virtual Users to create. Note that when
                running a Timed Workload HammerDB will automatically create an
                additional Virtual User to monitor the workload.</entry>
              </row>

              <row>
                <entry>User Delay(ms)</entry>

                <entry>User Delay(ms) defines the time to wait a Virtual User
                will wait behind the previous Virtual User before starting its
                test, this is to prevent a login storm with all Virtual Users
                attempting to login at the same time.</entry>
              </row>

              <row>
                <entry>Repeat Delay(ms)</entry>

                <entry>Repeat Delay(ms) is the time that each Virtual User
                will wait before running its next Iteration of the Driver
                Script. For TPROC-H this is an external loop before running
                another query set, however should not be more than 1 when the
                refresh function is enabled.</entry>
              </row>

              <row>
                <entry>Iterations</entry>

                <entry>Iterations is the number of times that the Driver
                Script is run in its entirety.</entry>
              </row>

              <row>
                <entry>Show Output</entry>

                <entry>Show Output will report Virtual User Output to the
                Virtual User Output Window, For TPROC-H tests this should be
                enabled.</entry>
              </row>

              <row>
                <entry>Log Output to Temp</entry>

                <entry>When enabled this appends all Virtual User Output to a
                text file in an available temp directory named
                hammerdb.log</entry>
              </row>

              <row>
                <entry>Use Unique Log Name</entry>

                <entry>Use a unique identifier for the Log Name.</entry>
              </row>

              <row>
                <entry>No Log Buffer</entry>

                <entry>By default text log output is buffered in memory before
                being written, this option writes the log output
                immediately.</entry>
              </row>

              <row>
                <entry>Log Timestamps</entry>

                <entry>Add an additional line of output with a timestamp every
                time that the log is written to.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>Select the Virtual User options, Press OK.</para>
    </section>

    <section>
      <title>Run a Single Virtual User Test</title>

      <para>Check that your scale_factor in the Driver Script is the same as
      the schema you are running the test against. You can also set the Degree
      of Parallelism/MAXDOP directly in the script.</para>

      <figure>
        <title>Modified Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-24.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Double-click on create Virtual User followed by Run. This will
      proceed to run a single Virtual User with one Query Set.</para>

      <figure>
        <title>Run a single Virtual User Test</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-23.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When complete the Virtual User will show the query set time as
      well as the geometric mean of queries that returned rows including a
      count of those queries that returned rows.</para>

      <figure>
        <title>Single Virtual User Complete</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-25.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>And the log will show the Query times. Note how the queries are
      run in a pre-determined random order.</para>

      <programlisting>Hammerdb Log @ Fri Oct 23 15:31:59 BST 2020
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
Vuser 1:Executing Query 14 (1 of 22)
Vuser 1:query 14 completed in 7.301 seconds
Vuser 1:Executing Query 2 (2 of 22)
Vuser 1:query 2 completed in 0.952 seconds
Vuser 1:Executing Query 9 (3 of 22)
Vuser 1:query 9 completed in 24.457 seconds
Vuser 1:Executing Query 20 (4 of 22)
Vuser 1:query 20 completed in 1.249 seconds
Vuser 1:Executing Query 6 (5 of 22)
Vuser 1:query 6 completed in 1.978 seconds
Vuser 1:Executing Query 17 (6 of 22)
Vuser 1:query 17 completed in 1.079 seconds
Vuser 1:Executing Query 18 (7 of 22)
Vuser 1:query 18 completed in 19.45 seconds
Vuser 1:Executing Query 8 (8 of 22)
Vuser 1:query 8 completed in 11.962 seconds
Vuser 1:Executing Query 21 (9 of 22)
Vuser 1:query 21 completed in 58.399 seconds
Vuser 1:Executing Query 13 (10 of 22)
Vuser 1:query 13 completed in 17.475 seconds
Vuser 1:Executing Query 3 (11 of 22)
Vuser 1:query 3 completed in 4.463 seconds
Vuser 1:Executing Query 22 (12 of 22)
Vuser 1:query 22 completed in 2.39 seconds
Vuser 1:Executing Query 16 (13 of 22)
Vuser 1:query 16 completed in 1.152 seconds
Vuser 1:Executing Query 4 (14 of 22)
Vuser 1:query 4 completed in 19.246 seconds
Vuser 1:Executing Query 11 (15 of 22)
Vuser 1:query 11 completed in 2.593 seconds
Vuser 1:Executing Query 15 (16 of 22)
Vuser 1:query 15 completed in 2.253 seconds
Vuser 1:Executing Query 1 (17 of 22)
Vuser 1:query 1 completed in 19.213 seconds
Vuser 1:Executing Query 10 (18 of 22)
Vuser 1:query 10 completed in 21.596 seconds
Vuser 1:Executing Query 19 (19 of 22)
Vuser 1:query 19 completed in 20.239 seconds
Vuser 1:Executing Query 5 (20 of 22)
Vuser 1:query 5 completed in 19.305 seconds
Vuser 1:Executing Query 7 (21 of 22)
Vuser 1:query 7 completed in 6.117 seconds
Vuser 1:Executing Query 12 (22 of 22)
Vuser 1:query 12 completed in 15.223 seconds
Vuser 1:Completed 1 query set(s) in 278 seconds
Vuser 1:Geometric mean of query times returning rows (22) is 6.82555
</programlisting>

      <section>
        <title>Changing the Query Order</title>

        <para>For a single virtual User test you may wish to change the query
        order. This query order is predetermined in the common modules.
        However you can redefine this function by copying and pasting the
        ordered_set function and modifying the order. The following example is
        sufficient for the single Virtual User</para>

        <programlisting>rename ordered_set ordered_set_orig
proc ordered_set { myposition } {
if { $myposition &gt; 40 } { set myposition [ expr $myposition % 40 ] }
        set o_s(0)  { 14 2 9 20 6 17 18 8 21 13 3 22 16 4 11 15 1 10 19 5 7 12 }
        return $o_s($myposition)
}</programlisting>

        <para>and then you can change the query order as follows:</para>

        <programlisting>set o_s(0)  { 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 }</programlisting>

        <para>If your database has issues with particular queries being long
        running you can also remove queries this way that you do not wish to
        run.</para>
      </section>
    </section>

    <section>
      <title>Run a Power Test</title>

      <para>Many test environments are sufficient with running single Virtual
      User tests. With available parallel and column store configurations this
      test is sufficient to stress an entire system. Nevertheless a component
      of the TPROC-H test is the refresh function and the refresh function
      should be run either side of the Power Test. To enable this
      functionality HammerDB has a special power test mode, whereby if
      refresh_on is set to true as shown and only one virtual user is
      configured then HammerDB will run a Power Test. Note that once you
      selected refresh_on for a single Virtual User in Power Test Mode the
      value of update_sets will be set to 1 and the value of trickle_refresh
      set to 0 and the value of REFRESH_VERBOSE set to false, all these values
      will be set automatically to ensure optimal running of the Power
      Test.</para>

      <figure>
        <title>Power Test Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-26.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When loaded note that the refresh_on option is set in the script.
      You should also ensure that the scale factor setting matches the setting
      for your schema.</para>

      <figure>
        <title>TPROC-H refresh on</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-28.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>With these settings run the Virtual User and it will run a New
      Sales Refresh, single Virtual User Query Set and Old Sales Refresh in
      order as required by a Power Test.</para>

      <figure>
        <title>Power Test</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-27.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>HammerDB will report when the Power Test is complete.</para>

      <figure>
        <title>Power Test Complete</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-29.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>and you can collect the refresh and query times from the
      log.</para>

      <programlisting>Hammerdb Log @ Fri Oct 23 15:41:39 BST 2020
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
Vuser 1:New Sales refresh
Vuser 1:New Sales refresh complete in 54.15 seconds
Vuser 1:Completed 1 update set(s)
Vuser 1:Executing Query 14 (1 of 22)
Vuser 1:query 14 completed in 7.868 seconds
Vuser 1:Executing Query 2 (2 of 22)
Vuser 1:query 2 completed in 0.334 seconds
Vuser 1:Executing Query 9 (3 of 22)
Vuser 1:query 9 completed in 21.87 seconds
Vuser 1:Executing Query 20 (4 of 22)
Vuser 1:query 20 completed in 0.816 seconds
Vuser 1:Executing Query 6 (5 of 22)
Vuser 1:query 6 completed in 0.926 seconds
Vuser 1:Executing Query 17 (6 of 22)
Vuser 1:query 17 completed in 1.299 seconds
Vuser 1:Executing Query 18 (7 of 22)
Vuser 1:query 18 completed in 19.289 seconds
Vuser 1:Executing Query 8 (8 of 22)
Vuser 1:query 8 completed in 4.232 seconds
Vuser 1:Executing Query 21 (9 of 22)
Vuser 1:query 21 completed in 59.815 seconds
Vuser 1:Executing Query 13 (10 of 22)
Vuser 1:query 13 completed in 13.889 seconds
Vuser 1:Executing Query 3 (11 of 22)
Vuser 1:query 3 completed in 5.773 seconds
Vuser 1:Executing Query 22 (12 of 22)
Vuser 1:query 22 completed in 0.928 seconds
Vuser 1:Executing Query 16 (13 of 22)
Vuser 1:query 16 completed in 0.792 seconds
Vuser 1:Executing Query 4 (14 of 22)
Vuser 1:query 4 completed in 19.258 seconds
Vuser 1:Executing Query 11 (15 of 22)
Vuser 1:query 11 completed in 0.497 seconds
Vuser 1:Executing Query 15 (16 of 22)
Vuser 1:query 15 completed in 9.436 seconds
Vuser 1:Executing Query 1 (17 of 22)
Vuser 1:query 1 completed in 16.067 seconds
Vuser 1:Executing Query 10 (18 of 22)
Vuser 1:query 10 completed in 22.284 seconds
Vuser 1:Executing Query 19 (19 of 22)
Vuser 1:query 19 completed in 19.648 seconds
Vuser 1:Executing Query 5 (20 of 22)
Vuser 1:query 5 completed in 18.98 seconds
Vuser 1:Executing Query 7 (21 of 22)
Vuser 1:query 7 completed in 6.089 seconds
Vuser 1:Executing Query 12 (22 of 22)
Vuser 1:query 12 completed in 12.512 seconds
Vuser 1:Completed 1 query set(s) in 263 seconds
Vuser 1:Geometric mean of query times returning rows (22) is 5.43452
Vuser 1:Old Sales refresh
Vuser 1:Old Sales refresh complete in 16.016 seconds
Vuser 1:Completed 1 update set(s)</programlisting>

      <para>Be aware that some databases are considerably better at running
      the refresh functions than others and also that once the power test has
      been run it is necessary to restore the database from backup before
      running the refresh function again. If you fail to do so you will
      receive a constraint violation error. This is expected behaviour.</para>

      <programlisting>Error in Virtual User 1: 23000 2627 {[Microsoft][ODBC Driver 13 for SQL Server][SQL Server]
Violation of PRIMARY KEY constraint 'orders_pk'. 
Cannot insert duplicate key in object 'dbo.orders'. The duplicate key value is (9).}</programlisting>
    </section>

    <section>
      <title>Run a Throughput Test</title>

      <para>After the power test you should run the throughput test (if the
      refresh function has been run it is necessary to refresh the schema).
      For the throughput test you need to also run the refresh function
      however this time the aim is to trickle the refresh function slowly
      while multiple query streams are run. Configure the options as for the
      Power Test and enable the refresh function, this time the update sets,
      trickle refresh and REFRESH_VERBOSE options will also be enabled when
      refresh_on is set to true. Configure the correct number of Virtual Users
      to enable the first Virtual User to run the Refresh Functions and
      additional Virtual Users to run the Query Streams as defined in the
      specification for the test. For the example below at Scale Factor 10
      there are 3 Virtual Users to run the queries and 1 to run the refresh.
      Note that the Refresh Function will run more slowly as expected and all
      of the Virtual Users run the queries in a different order.</para>

      <figure>
        <title>Throughput Test</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch13-30.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <section>
        <title>SQL Server Snapshot Isolation</title>

        <para>Note that before running a long running query at the same time
        as the inserts of the refresh function you should enable snapshot
        isolation on the database. Failure to do so will mean the Query
        streams will hang under a shared lock (LCK_M_S) whilst the refresh
        function is running.</para>

        <figure>
          <title>Enable Snapshot Isolation</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-31.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Once set the refresh and queries will run as expected. If you
        observe foreign key or constraint violation errors after having
        restored a schema verify the scale factor in the driver script is set
        to the same value as the scale factor of the schema you have
        restored.</para>

        <figure>
          <title>SQL Server with Snapshot Isolation</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-32.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>When the Virtual Users running the Query sets have completed the
        throughput tests, note the longest (not the shortest) time taken for a
        full query set to complete. You do not need to wait for the trickled
        refresh function to complete, however must have configured enough
        update sets to ensure that the refresh function remains running whilst
        the throughput test completes.</para>

        <figure>
          <title>Throughput test complete</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch13-33.PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>
    </section>

    <section>
      <title>Calculate the Geometric Mean</title>

      <para>For comparison of HammerDB TPROC-H workloads between systems it is
      recommended to use the geometric mean of the query times. This can be a
      straightforward comparison between power tests. When comparing
      throughput tests it is recommended to compare the geomean of the slowest
      virtual user when comparing throughput tests of an equal number of
      virtual users across systems.</para>

      <programlisting>0.943
0.332
21.281
1.163
1.93
0.504
13.358
11.419
55.767
20.412
2.435
1.011
2.08
18.064
5.83
2.003
13.503
5.548
1.525
9.765
3.69
3.226
SUM 195.789
GEOMEAN 4.011822724
</programlisting>
    </section>
  </chapter>

  <chapter>
    <title>Generating and Loading Bulk Datasets</title>

    <para>For all workloads HammerDB can create the schema and generate and
    load the data without requiring a staging area, in many circumstances this
    is the preferred method of loading especially for OLTP workloads.
    Nevertheless in some circumstances it is preferable to create the data
    externally as flat files and then use a special database vendor provided
    bulk loading command to load the data into pre-created tables. This option
    may be preferred for example where the target database to load is located
    in the cloud or where the target database has a column structure meaning
    that load performance using batch inserts is poor. Additionally bulk
    loading can enable more flexibility to modify the schema according to
    preference and reload during testing. This chpater details how to generate
    and load large data sets with HammerDB.</para>

    <section>
      <title>Generate the Dataset</title>

      <para>This example for generating the dataset uses SQL Server on
      Windows, however the process is identical when creating data on Linux.
      Firstly create an empty directory that is writable for the user running
      HammerDB and does not contain any existing generated files. HammerDB
      will not overwrite existing generated files.</para>

      <para><figure>
          <title>Data Directory</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch10-1.png"/>
            </imageobject>
          </mediaobject>
        </figure>This point in time is a good stage to validate how much free
      space is in the directory, HammerDB will not check before generating
      data that enough free space exists in the file system before proceeding.
      From the benchmark menu select your chosen database and workload. Note
      that it is particularly important that you select the correct database
      and workload for your environment before generating the data. The data
      generated is different between different databases and workloads. For
      example for optimization purposes the columns may be ordered differently
      between different databases. The data is generated in column order for
      the way that HammerDB generates the schema and data such as time and
      date formats may be different. Errors will result from loading the data
      generated for one database in another without modification.</para>

      <figure>
        <title>Benchmark Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Under the benchmark or Options menus select Datagen and
      Options</para>

      <figure>
        <title>Datagen Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Depending upon whether you have selected a TPROC-C or TPROC-H
      benchmark under the benchmark options the dialog will be different. For
      the TPROC-H options select the Scale Factor, the directory that you have
      pre-created and the number of Virtual Users to generate the
      schema.</para>

      <figure>
        <title>Data Generation Options</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The data generation offers linear scalability with the key limit
      on performance being the number of CPU cores/threads on the system. Each
      virtual user will use 100% of an available core/thread and therefore it
      should be clear that creating more virtual users than available
      cores/threads is non-productive. Additionally creating the same number
      of virtual users as cores/threads will drive CPU utilisation to 100% -
      therefore select the number of Virtual Users equivalent to the available
      capacity on the system. Similarly it should also be clear that the time
      to create a data set is dependent on the number of available
      cores/threads – a 4 socket or above server with hundreds of
      cores/threads will be able to generate data considerably more quickly
      than a single socket PC or laptop. Finally bear in mind that each
      virtual user will generate a subsection of the data for tables. For
      example selecting 10 virtual users will generate 10 separate files to
      load each table. This approach enables both flexibility and scalability
      in both generating the data but also uploading generated files to the
      cloud and loading data in parallel.</para>

      <figure>
        <title>Multiple files</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-5.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>When the chosen values have been selected choose and click the
      Generate button or Generate menu option.</para>

      <figure>
        <title>Generate</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-6.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>This displays the Generate Data confirmation. Click Yes.</para>

      <figure>
        <title>Generate Data Confirmation</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-7.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>HammerDB will begin to generate the chosen schema in
      parallel.</para>

      <figure>
        <title>Generating Data</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-8.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Observe that the CPU utilisation level is in accordance with your
      Virtual User settings.</para>

      <figure>
        <title>CPU Utilisation 100%</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-9.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>HammerDB requires no further intervention to generate the data for
      the required schema.</para>

      <figure>
        <title>Schema Generated</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-10.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>You may also view the data with a text editor to see that the
      generated data is delimited by a pip character ie “|” and intended NULL
      values are represented by blank or empty data.</para>

      <figure>
        <title>Pipe Delimited Data</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch10-11.png"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Data is now generated and you are ready to proceed to creating a
      schema and loading the data. It should be clear that once you have
      created a chosen data set then you are able to reuse and reload that
      dataset multiple times and therefore HammerDB enables a quick way to
      generate all of the test data that you require. It is also important to
      note that in some cases databases will support compressing data with
      tools such as zip or gzip prior to loading and therefore if you have a
      large dataset to upload then investigating whether this is an option for
      your database is a worthwhile task.</para>
    </section>

    <section>
      <title>Generate the Dataset with the CLI</title>

      <para>Data Generation can also be run from the command line. As shown
      the dbset command is used to specify the database and benchmark to
      generate data for.</para>

      <programlisting>./hammerdbcli 
HammerDB CLI v4.0
Copyright (C) 2003-2020 Steve Shaw
Type "help" for a list of commands
The xml is well-formed, applying configuration
hammerdb&gt;print datagen
Data Generation set to build a TPC-C schema for Oracle with 1 warehouses with 1 virtual users in /tmp

hammerdb&gt;dbset bm TPROC-H
Benchmark set to TPROC-H for Oracle

hammerdb&gt;print datagen
Data Generation set to build a TPC-H schema for Oracle with 1 scale factor with 1 virtual users in /tmp

hammerdb&gt;dbset bm TPROC-C
Benchmark set to TPROC-C for Oracle

hammerdb&gt;print datagen
Data Generation set to build a TPC-C schema for Oracle with 1 warehouses with 1 virtual users in /tmp</programlisting>

      <para>and the Data Generation options set with the command dgset:</para>

      <programlisting>hammerdb&gt;dgset warehouse 10

hammerdb&gt;dgset vu 8
Set virtual users to 8 for data generation

hammerdb&gt;dgset directory "/tmp/TPCCDATA"

hammerdb&gt;print datagen
Data Generation set to build a TPC-C schema for Oracle with 10 warehouses with 8 virtual users in /tmp/TPCCDATA</programlisting>

      <para>The data is then created using the command datagenrun.</para>

      <programlisting>hammerdb&gt;datagenrun
Ready to generate the data for a 10 Warehouse Oracle TPC-C schema
in directory /tmp/TPCCDATA ?
Enter yes or no: replied yes
Vuser 1 created - WAIT IDLE
Vuser 2 created - WAIT IDLE
Vuser 3 created - WAIT IDLE
Vuser 4 created - WAIT IDLE
Vuser 5 created - WAIT IDLE
Vuser 6 created - WAIT IDLE
Vuser 7 created - WAIT IDLE
Vuser 8 created - WAIT IDLE
Vuser 9 created - WAIT IDLE
RUNNING - TPC-C generation
Vuser 1:RUNNING
Vuser 1:Monitor Thread
Vuser 1:Opened File /tmp/TPCCDATA/item_1.tbl
Vuser 1:Generating Item
Vuser 2:RUNNING
Vuser 2:Worker Thread
Vuser 2:Waiting for Monitor Thread...
Vuser 2:Generating 2 Warehouses start:1 end:2
Vuser 2:Start:Mon Apr 09 16:21:36 BST 2018
Vuser 2:Opened File /tmp/TPCCDATA/warehouse_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/stock_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/district_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/customer_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/history_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/orders_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/new_order_1.tbl
Vuser 2:Opened File /tmp/TPCCDATA/order_line_1.tbl
Vuser 2:Generating Warehouse
Vuser 2:Generating Stock Wid=1

...</programlisting>
    </section>

    <section>
      <title>Generate the template database</title>

      <para>Generating a template database is exceptionally straightforward.
      From the HammerDB documentation follow the steps for Build a Schema and
      create the smallest size database such as Scale Factor 1 for TPROC-H.
      This database can then be used as a template to capture the DDL. Note
      that if you stop the database creation after the tables are created but
      before all of the data is loaded objects such as indexes will not have
      been created and will not therefore be included in generated DDL, this
      may or may not be an issue for the type of schema you are intending to
      build, for example for a column store such as Amazon Redshift, indexes
      are not a requirement.</para>

      <section>
        <title>Capture and run the table creation DDL</title>

        <para>All of the mainstream databases supported with HammerDB enable
        DDL capture. This can be done as follows for each database. Note that
        at this stage you have the option to modify the DDL for your needs
        such as for partitioning or column orientation.</para>

        <section>
          <title>Oracle</title>

          <para>As the user owning the template database at a sqlplus prompt
          run a GET_DDL SQL statement as follows, noting that you need to set
          the long and pagesize values correctly to view all of the
          output.</para>

          <programlisting>SQL&gt;select DBMS_METADATA.GET_DDL('TABLE','ORDERS') from dual;</programlisting>

          <para>This produces a Create Table statement such as follows:</para>

          <programlisting>CREATE TABLE "TPCH"."ORDERS"                                                 
("O_ORDERDATE" DATE,                                         
"O_ORDERKEY" NUMBER NOT NULL ENABLE,                            
"O_CUSTKEY" NUMBER NOT NULL ENABLE,                            
"O_ORDERPRIORITY" CHAR(15),                                   
"O_SHIPPRIORITY" NUMBER,                                      
"O_CLERK" CHAR(15),                                           
"O_ORDERSTATUS" CHAR(1),                                       
"O_TOTALPRICE" NUMBER,              
"O_COMMENT" VARCHAR2(79),
 CONSTRAINT "ORDERS_PK" PRIMARY KEY ("O_ORDERKEY")
);
</programlisting>

          <para>Joining these files together can then be run against the
          database to create the schema of empty tables:</para>

          <programlisting>sqlplus tpch/tpch
SQL*Plus: Release 12.1.0.2.0 Production
Copyright (c) 1982, 2014, Oracle.  All rights reserved.
Connected to:
Oracle Database 12c Enterprise Edition Release 12.1.0.2.0
SQL&gt; @tpch_tables.sql
Table created.
Table created.
Table created.
Table created.
Table created.
Table created.
Table created.
Table created.
SQL&gt;
</programlisting>
        </section>

        <section>
          <title>SQL Server</title>

          <para>Within SQL Server Management Studio right click your chosen
          table, select “Script Table as” followed by “CREATE To” and choose
          your destination for the DDL. This produces DDL to create your table
          such as follows. Create a single file containing all of your DDL
          statements and click on Execute (F5) under SQL Server Management
          Studio.</para>

          <figure>
            <title>SQL Server Create Table</title>

            <mediaobject>
              <imageobject>
                <imagedata fileref="docs/images/ch10-12.png"/>
              </imageobject>
            </mediaobject>
          </figure>
        </section>

        <section>
          <title>Db2</title>

          <para>For Db2 use the db2look command, this can generate the DDL for
          all objects within a schema with one command.</para>

          <programlisting>db2look -d TPCH -a -e -x -o tpchcreate.sql
-- Generate statistics for all creators 
-- Creating DDL for table(s)
-- Output is sent to file: tpchcreate.sql
-- Binding package automatically ... 
-- Bind is successful
-- Binding package automatically ... 
-- Bind is successful
------------------------------------------------
-- DDL Statements for Table "DB2INST1"."ORDERS"
------------------------------------------------
</programlisting>

          <para>The output file will contain output as follows:</para>

          <programlisting>
CREATE TABLE "DB2INST1"."ORDERS"  (
  "O_ORDERKEY" INTEGER NOT NULL , 
  "O_CUSTKEY" INTEGER NOT NULL , 
  "O_ORDERSTATUS" CHAR(1 OCTETS) NOT NULL , 
  "O_TOTALPRICE" DOUBLE NOT NULL , 
  "O_ORDERDATE" DATE NOT NULL , 
  "O_ORDERPRIORITY" CHAR(15 OCTETS) NOT NULL , 
  "O_CLERK" CHAR(15 OCTETS) NOT NULL , 
  "O_SHIPPRIORITY" INTEGER , 
  "O_COMMENT" VARCHAR(79 OCTETS) NOT NULL )   
 IN "USERSPACE1"  
 ORGANIZE BY ROW; 
</programlisting>

          <para>Run the file as follows:</para>

          <programlisting>db2 -tvf tpchcreate.sql
CONNECT TO TPCH

   Database Connection Information

 Database server        = DB2/LINUXX8664 11.1.0
 SQL authorization ID   = DB2INST1
 Local database alias   = TPCH2

CREATE SCHEMA "DB2INST1"
DB20000I  The SQL command completed successfully.

CREATE TABLE "DB2INST1"."ORDERS"  ( "O_ORDERKEY" INTEGER NOT NULL , "O_CUSTKEY" INTEGER NOT NULL , "O_ORDERSTATUS" CHAR(1 OCTETS) NOT NULL , "O_TOTALPRICE" DOUBLE NOT NULL , "O_ORDERDATE" DATE NOT NULL , "O_ORDERPRIORITY" CHAR(15 OCTETS) NOT NULL , "O_CLERK" CHAR(15 OCTETS) NOT NULL , "O_SHIPPRIORITY" INTEGER , "O_COMMENT" VARCHAR(79 OCTETS) NOT NULL ) IN "USERSPACE1" ORGANIZE BY ROW
DB20000I  The SQL command completed successfully.
</programlisting>
        </section>

        <section>
          <title>MySQL</title>

          <para>For MySQL use the show create table command. Be aware that if
          foreign keys are defined at this stage they will significantly
          impact load performance.</para>

          <programlisting>mysql&gt; use tpch;
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql&gt; show tables;
+----------------+
| Tables_in_tpch |
+----------------+
| CUSTOMER       |
| LINEITEM       |
| NATION         |
| ORDERS         |
| PART           |
| PARTSUPP       |
| REGION         |
| SUPPLIER       |
+----------------+
8 rows in set (0.00 sec)

mysql&gt; show create table SUPPLIER;

CREATE TABLE `SUPPLIER` (
  `S_SUPPKEY` int(11) NOT NULL,
  `S_NATIONKEY` int(11) DEFAULT NULL,
  `S_COMMENT` varchar(102) CHARACTER SET latin1 COLLATE latin1_bin DEFAULT NULL,
  `S_NAME` char(25) CHARACTER SET latin1 COLLATE latin1_bin DEFAULT NULL,
  `S_ADDRESS` varchar(40) CHARACTER SET latin1 COLLATE latin1_bin DEFAULT NULL,
  `S_PHONE` char(15) CHARACTER SET latin1 COLLATE latin1_bin DEFAULT NULL,
  `S_ACCTBAL` decimal(10,2) DEFAULT NULL,
  PRIMARY KEY (`S_SUPPKEY`),
  KEY `SUPPLIER_FK1` (`S_NATIONKEY`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1;
</programlisting>

          <para>Create a file containing all of the table creation statements
          and run as follows:</para>

          <programlisting>sql&gt; use tpch
Database changed
mysql&gt; source /home/mysql/TPCHDATA/createtpch.sql
Query OK, 0 rows affected (0.08 sec)
Query OK, 0 rows affected (0.07 sec)
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.06 sec)
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.05 sec)
mysql&gt;
</programlisting>
        </section>

        <section>
          <title>PostgreSQL/Amazon Redshift</title>

          <para>To create the DLL for PostgreSQL or Amazon Redshift (note you
          can create a template local PostgreSQL database and the DDL is 100%
          compatible to create a database in Redshift) use the pg_dump command
          as follows:</para>

          <programlisting>pg_dump -U postgres -h localhost tpch -t table_name --schema-only -f table.sql</programlisting>

          <para>On Linux systems you can use the bash shell to generate the
          DDL for all tables with one command, for example:</para>

          <programlisting>for sys in customer lineitem nation orders part partsupp region supplier; do pg_dump -U postgres -h localhost tpch -t $sys --schema-only -f $sys.sql; done</programlisting>

          <para>This generates a series of files containing the required DDL
          as follows:</para>

          <programlisting>CREATE TABLE customer (
    c_custkey numeric NOT NULL,
    c_mktsegment character(10),
    c_nationkey numeric,
    c_name character varying(25),
    c_address character varying(40),
    c_phone character(15),
    c_acctbal numeric,
    c_comment character varying(118)
);
</programlisting>

          <para>Run the files as follows under PostgreSQL or Redshift to
          create the desired tables. The following example create the schema
          on PostgreSQL</para>

          <programlisting>psql -d tpch -f pgtpchtables.sql</programlisting>

          <para>and the following on Redshift</para>

          <programlisting>bash-4.2$ psql -h tpch-instance.xxxxxxxxxxxx.eu-west-1.redshift.amazonaws.com -U postgres -d tpch -p 5439 -f pgtpchtables.sql
Password for user postgres: 
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE
-bash-4.2$ psql -h tpch-instance.xxxxxxxxxxxx.eu-west-1.redshift.amazonaws.com -U postgres -d tpch -p 5439
Password for user postgres: 
psql (9.2.15, server 8.0.2)
WARNING: psql version 9.2, server version 8.0.
         Some psql features might not work.
SSL connection (cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256)
Type "help" for help.

tpch=# \d
          List of relations
 schema |   name   | type  |  owner   
--------+----------+-------+----------
 public | customer | table | postgres
 public | lineitem | table | postgres
 public | nation   | table | postgres
 public | orders   | table | postgres
 public | part     | table | postgres
 public | partsupp | table | postgres
 public | region   | table | postgres
 public | supplier | table | postgres
(8 rows)
</programlisting>
        </section>
      </section>
    </section>

    <section>
      <title>Run the bulk data load</title>

      <para>With the schemas created you can proceed to bulk load the data you
      have created without the overhead of features such as logging associated
      with inserts. This section details example methods by which data can be
      bulk loaded. Note that some of these databases support multiple
      different methods to bulk load data and this section gives examples
      using either the most straightforward or widely available tools,
      therefore additional methods may exists to load your data.</para>

      <section>
        <title>Oracle</title>

        <para>SQL*Loader is the default method for loading Oracle with
        external data. SQL*Loader has the advantage of flexibility in being
        adaptable to loading data in many different formats. To use SQL*Loader
        firstly create a control file. The following example shows a control
        file for the ORDERS table from the TPCH schema. Firstly note that the
        control can accept wildcard characters and therefore multiple files
        can be loaded with one command. Also note how the DATE format has been
        specified.</para>

        <programlisting>more sqlldr-orders.ctl
load data
infile '/home/oracle/TPCCDATA/orders_*.tbl'
into table orders
fields terminated by "|"
(O_ID,O_W_ID,O_D_ID,O_C_ID,O_CARRIER_ID,O_OL_CNT,O_ALL_LOCAL,O_ENTRY_D DATE "YYY
YMMDDHH24MISS")
</programlisting>

        <para>A further different date formatting example can be seen for the
        LINEITEM table in the TPCH schema.</para>

        <programlisting>more sqlldr-lineitem.ctl
load data
infile '/home/oracle/TPCHDATA/lineitem_*.tbl'
into table lineitem
fields terminated by "|"
(L_SHIPDATE DATE "yyyy-mon-dd",L_ORDERKEY,L_DISCOUNT ,L_EXTENDEDPRICE,L_SUPPKEY,L_QUANTITY,L_RETURNFLAG,L_PARTKEY,L_LINESTATUS,L_TAX,L_COMMITDATE DATE "yyyy-mon-dd", L_RECEIPTDATE DATE "yyyy-mon-dd",L_SHIPMODE, L_LINENUMBER, L_SHIPINSTRUCT, L_COMMENT)
</programlisting>

        <para>Now run SQL*Loader specifying the control file and username and
        password.</para>

        <programlisting>sqlldr tpch/tpch control=/home/oracle/sqlldr-orders.ctl direct=true</programlisting>
      </section>

      <section>
        <title>SQL Server</title>

        <para>For SQL Server use a bulk insert state as follows. SQL Server
        does not recognize wildcard characters for bulk insert however is
        adaptable in recognizing both NULLS and various date formats by
        default.</para>

        <programlisting>BULK INSERT customer FROM 'C:\TEMP\TPCHDATA\customer_1.tbl' WITH (TABLOCK, DATAFILETYPE='char', CODEPAGE='raw', FIELDTERMINATOR = '|')</programlisting>

        <para>Run the bulk insert commands via SQL Server Management
        studio.</para>

        <figure>
          <title>SQL Server Bulk Insert</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch10-13.png"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>

      <section>
        <title>Db2</title>

        <para>For DB2 firstly connect to your database and then use the db2
        load command. The delimiter is specified by 0x7c as the ASCII
        character for vertical bar as the delimiter used.</para>

        <programlisting>$ db2 connect to tpch

Database Connection Information

Database server        = DB2/LINUXX8664 11.1.0
SQL authorization ID   = DB2INST1
Local database alias   = TPCH


db2 load from /home/db2inst1/TPCHDATA/nation_1.tbl of DEL MODIFIED BY DELPRIORITYCHAR COLDEL0x7c insert INTO nation
</programlisting>

        <para>This command is easy to script in Linux environments to load all
        available files:</para>

        <programlisting>$ for sys in `ls -1 customer_*.tbl`; do db2 load from /home/db2inst1/TPCHDATA/$sys of DEL MODIFIED BY DELPRIORITYCHAR COLDEL0x7c insert INTO customer; done

</programlisting>

        <para>Where a date is specified the dateformat must be given as
        follows:</para>

        <programlisting>db2 load from /home/db2inst1/TPCHDATA/lineitem_1.tbl of DEL MODIFIED BY DELPRIORITYCHAR COLDEL0x7c DATEFORMAT=\"YYYY-MMM-DD\" insert INTO lineitem</programlisting>

        <para>As with Oracle and SQL Server Db2 automatically recognises NULL
        values in the data.</para>
      </section>

      <section>
        <title>MySQL</title>

        <para>Bulk loading is done in MySQL using the load data infile
        command. This can be done as follows:</para>

        <programlisting>mysql&gt; load data infile '/home/mysql/TPCHDATA/supplier_1.tbl' INTO table SUPPLIER fields terminated by '|';</programlisting>

        <para>Load data infile does not offer enable a method by which
        different date formats can be specified however this can be achieved
        by specifying an additional SET command as shown for the LINEITEM
        table:</para>

        <programlisting>load data infile '/home/mysql/TPCHDATA/lineitem_1.tbl' INTO table LINEITEM fields terminated by '|'
(@dt1, L_ORDERKEY, L_DISCOUNT, L_EXTENDEDPRICE, L_SUPPKEY, L_QUANTITY, L_RETURNFLAG, L_PARTKEY, L_LINESTATUS, L_TAX, @dt2, @dt3, L_SHIPMODE, L_LINENUMBER, L_SHIPINSTRUCT, L_COMMENT)
set L_SHIPDATE = STR_TO_DATE(@dt1, '%Y-%b-%d'),L_COMMITDATE = STR_TO_DATE(@dt2, '%Y-%b-%d'),L_RECEIPTDATE = STR_TO_DATE(@dt3, '%Y-%b-%d');
</programlisting>

        <para>and a SET command as follows shown for the ORDERS table:</para>

        <programlisting>load data infile '/home/mysql/TPCHDATA/orders_1.tbl' INTO table ORDERS fields terminated by '|'
(@dt1, O_ORDERKEY, O_CUSTKEY, O_ORDERPRIORITY, O_SHIPPRIORITY, O_CLERK, O_ORDERSTATUS, O_TOTALPRICE, O_COMMENT)
set O_ORDERDATE = STR_TO_DATE(@dt1, '%Y-%b-%d');
</programlisting>

        <para>Add these commands to a file:</para>

        <programlisting>load data infile '/home/mysql/TPCHDATA/customer_1.tbl' INTO table CUSTOMER fields terminated by '|';
load data infile '/home/mysql/TPCHDATA/customer_2.tbl' INTO table CUSTOMER fields terminated by '|';
load data infile '/home/mysql/TPCHDATA/customer_3.tbl' INTO table CUSTOMER fields terminated by '|';
load data infile '/home/mysql/TPCHDATA/customer_4.tbl' INTO table CUSTOMER fields terminated by '|';
load data infile '/home/mysql/TPCHDATA/customer_5.tbl' INTO table CUSTOMER fields terminated by '|';
load data infile '/home/mysql/TPCHDATA/customer_6.tbl' INTO table CUSTOMER fields terminated by '|';
</programlisting>

        <para>and run as follows:</para>

        <para><programlisting>mysql&gt; source /home/mysql/TPCHDATA/loadfiles.sql
Query OK, 150000 rows affected (0.74 sec)
Records: 150000  Deleted: 0  Skipped: 0  Warnings: 0

Query OK, 150000 rows affected (1.56 sec)
Records: 150000  Deleted: 0  Skipped: 0  Warnings: 0
</programlisting>For the MySQL TPROC-C schema NULLS are not automatically
        recognised and a SET command is required as follows for the ORDER_LINE
        and ORDERS table:</para>

        <programlisting>load data infile '/home/mysql/TPCCDATA/order_line_1.tbl' INTO table order_line fields terminated by '|'
(ol_w_id, ol_d_id, ol_o_id, ol_number, ol_i_id, @dt1, ol_amount, ol_supply_w_id, ol_quantity, ol_dist_info)
set ol_delivery_d = nullif(@dt1,'');

load data infile '/home/mysql/TPCCDATA/orders_1.tbl' INTO table orders fields terminated by '|'
(o_id, o_w_id, o_d_id, o_c_id, @id1, o_ol_cnt, o_all_local, o_entry_d)
set o_carrier_id = nullif(@id1,'');
</programlisting>
      </section>

      <section>
        <title>PostgreSQL/Amazon Redshift</title>

        <para>Both PostgreSQL and Amazon Redshift use the copy command to bulk
        load data, however Redshift has additional requirements to load the
        data into the cloud. For PostgreSQL make a file with the copy commands
        for all tables for example:</para>

        <programlisting>\copy customer from '/home/postgres/TPCHDATA/customer_1.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_2.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_3.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_4.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_5.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_6.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_7.tbl' WITH DELIMITER AS '|';
\copy customer from '/home/postgres/TPCHDATA/customer_8.tbl' WITH DELIMITER AS '|';

</programlisting>

        <para>And run the script to copy the files</para>

        <programlisting>psql -U postgres -d tpch -f TPCHCOPY.sql</programlisting>

        <para>With PostgreSQL additional lines are required to handle NULL
        value for the TPROC-C schema as follows:</para>

        <programlisting>\copy order_line from '/home/postgres/TPCCDATA/order_line_1.tbl' WITH NULL AS '' DELIMITER AS '|';
\copy orders from '/home/postgres/TPCCDATA/orders_1.tbl' WITH NULL AS '' DELIMITER AS '|';
</programlisting>

        <para>For Amazon Redshift firstly upload the generated files to an
        Amazon S3 bucket. As noted previously Amazon S3 is one of the
        databases that supports loading from a compressed file and therefore
        you may wish to convert the files to a compressed format such as gzip
        before uploading.</para>

        <figure>
          <title>Upload to S3</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch10-14.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Under the AWS IAM Console create a user for uploading and under
        security credentials create and download an access key. Note that the
        access keys have been removed from the image.</para>

        <figure>
          <title>Postgres User Access Keys</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch10-15.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Finally give the postgres user permission to access Amazon
        S3.</para>

        <figure>
          <title>S3 Permissions</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch10-16.png"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>Now connect to Redshift using the PostgreSQL command line tool
        and run the copy command specifying the location of the S3 bucket and
        the CREDENTIALs option where the XXX characters are replaced by the
        access key and secure access key you created previously.</para>

        <programlisting>-bash-4.2$ psql -h tpch-instance.xxxxxxxxxxxx.eu-west-1.redshift.amazonaws.com -U postgres -d tpch -p 5439
Password for user postgres: 
psql (9.2.15, server 8.0.2)
WARNING: psql version 9.2, server version 8.0.
         Some psql features might not work.
SSL connection (cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256)
Type "help" for help.

tpch=# copy region from 's3://s3bucket/load/region_1.tbl' CREDENTIALS 'aws_access_key_id=XXXXXXXXXXXXXXXXXXXX;aws_secret_access_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' delimiter '|';
INFO:  Load into table 'region' completed, 5 record(s) loaded successfully.
COPY
</programlisting>

        <para>Note that if you specify part of the filename Redshift will
        upload all of the files with the same prefix.</para>

        <programlisting>copy customer from 's3://s3bucket/load/customer_' CREDENTIALS 'aws_access_key_id=XXXXXXXXXXXXXXXXXXXX;aws_secret_access_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' delimiter '|';
INFO:  Load into table 'customer' completed, 150000 record(s) loaded successfully.
</programlisting>

        <para>For NULL values and date and time formats you can specify the
        formats for load as follows:</para>

        <programlisting>tpch=# copy orders from 's3://s3bucket/load/orders_' CREDENTIALS 'aws_access_key_id=XXXXXXXXXXXXXXXXXXXX;aws_secret_access_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' emptyasnull blanksasnull delimiter '|' timeformat 'YYYY-MON-DD HH:MI:SS';
INFO:  Load into table 'orders' completed, 1500000 record(s) loaded successfully.
COPY
</programlisting>

        <para>Note that as a column store Redshift does not require the
        additional indexes or constraints of a traditional row store
        format.</para>
      </section>
    </section>
  </chapter>

  <chapter>
    <title>Oracle Trace File Replay</title>

    <para>Oracle Trace Files can be converted and replayed against an Oracle
    database. Within HammerDB this trace file replay functionality is only
    available with Oracle as the other supported databases do not provide an
    interface to generating a detailed trace of workloads.</para>

    <sect1>
      <title>Generating Trace Files</title>

      <para>To begin converting Oracle trace file workloads with HammerDB the
      first step is to load an Oracle trace file under the File:Open menu
      option. Before doing this therefore an Oracle trace file must be
      generated using Oracle Event 10046. (There are numerous methods to
      generate Oracle trace files of which only event 10046, level 4 to
      capture bind variables is covered here). As an example the simplest
      method to start and stop the trace of a session interactively is as
      follows:</para>

      <programlisting>SQL&gt; connect / as sysdba
Connected.
SQL&gt; alter session set events '10046 trace name context forever, level 4'; 

Session altered.

SQL&gt; select sysdate from dual;

SYSDATE
---------
10-APR-18

SQL&gt; alter session set events '10046 trace name context off';

Session altered.

SQL&gt; 
</programlisting>

      <para>For more advanced use the creation of a logon trigger is
      recommended. This trigger can then be enabled or disabled to capture the
      trace information for a particular use. The example uses the user TPCC
      created for an Oracle HammerDB OLTP test.</para>

      <programlisting>create or replace trigger logon_trigger
after logon on database
begin
if (user = 'TPCC') then
execute immediate
'alter session set events ''10046 trace name context forever, level 4''';
end if;
end;</programlisting>

      <para>This will then create a tracefile automatically at logon.</para>

      <programlisting>SQL&gt; connect tpcc/tpcc@RVDB1
Connected.
SQL&gt; select sysdate from dual;

SYSDATE
---------
10-APR-18
</programlisting>

      <para>The trigger must be created as SYS with SYSDBA privileges, if
      created by system the trigger will create successfully but fail on the
      user login. This event will produce a trace file in the diagnostic area
      specified for the database server. By default the file will be
      identifiable by ora_SPID.trc, however there are also methods that can be
      used to set the name of the trace file. Note that in a Shared Server
      environment (previously MTS) one users’ session may be distributed
      across numerous trace files as the user processes share multiple server
      processes. Therefore in this environment it is necessary to reassemble
      the trace file data before converting with the Oracle utility ‘trcsess’.
      A a raw trace file is shown below:</para>

      <programlisting>race file /home/oracle/app/oracle/diag/rdbms/rvdb1/RVDB1/trace/RVDB1_ora_13783.trc
Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 - 64bit Production
With the Partitioning, OLAP, Advanced Analytics and Real Application Testing options
ORACLE_HOME = /home/oracle/app/oracle/product/12.1.0/dbhome_1
System name:Linux
Node name:raven
Release:4.1.12-61.1.23.el7uek.x86_64
Version:#2 SMP Tue Dec 20 16:59:23 PST 2016
Machine:x86_64
Instance name: RVDB1
Redo thread mounted by this instance: 1
Oracle process number: 72
Unix process pid: 13783, image: oracle@raven (TNS V1-V3)


*** 2018-04-10 14:35:39.821
*** SESSION ID:(4.48241) 2018-04-10 14:35:39.821
*** CLIENT ID:() 2018-04-10 14:35:39.821
*** SERVICE NAME:(SYS$USERS) 2018-04-10 14:35:39.821
*** MODULE NAME:(sqlplus@raven (TNS V1-V3)) 2018-04-10 14:35:39.821
*** CLIENT DRIVER:(SQL*PLUS) 2018-04-10 14:35:39.821
*** ACTION NAME:() 2018-04-10 14:35:39.821
 
CLOSE #140169830640712:c=0,e=6,dep=0,type=1,tim=530154237
=====================
PARSING IN CURSOR #140169830722080 len=24 dep=0 uid=0 oct=3 lid=0 tim=530194337 hv=2343063137 ad='97b9c9e8' sqlid='7h35uxf5uhmm1'
select sysdate from dual
END OF STMT
PARSE #140169830722080:c=3149,e=39623,p=0,cr=0,cu=0,mis=1,r=0,dep=0,og=1,plh=1388734953,tim=530194336
EXEC #140169830722080:c=0,e=21,p=0,cr=0,cu=0,mis=0,r=0,dep=0,og=1,plh=1388734953,tim=530194497
FETCH #140169830722080:c=0,e=16,p=0,cr=0,cu=0,mis=0,r=1,dep=0,og=1,plh=1388734953,tim=530194568
STAT #140169830722080 id=1 cnt=1 pid=0 pos=1 obj=0 op='FAST DUAL  (cr=0 pr=0 pw=0 time=0 us cost=2 size=0 card=1)'
FETCH #140169830722080:c=0,e=1,p=0,cr=0,cu=0,mis=0,r=0,dep=0,og=0,plh=1388734953,tim=530213687

*** 2018-04-10 14:36:07.973
CLOSE #140169830722080:c=539,e=34,dep=0,type=0,tim=558307025
=====================
PARSING IN CURSOR #140169830722080 len=55 dep=0 uid=0 oct=42 lid=0 tim=558307224 hv=2217940283 ad='0' sqlid='06nvwn223659v'
alter session set events '10046 trace name context off'
END OF STMT
PARSE #140169830722080:c=0,e=112,p=0,cr=0,cu=0,mis=0,r=0,dep=0,og=0,plh=0,tim=558307223
EXEC #140169830722080:c=0,e=214,p=0,cr=0,cu=0,mis=0,r=0,dep=0,og=0,plh=0,tim=558307510</programlisting>

      <para>For more information on the trace file format the document
      Note:39817.1 Subject “Interpreting Raw SQL_TRACE output “ available from
      My Oracle Support, however this knowledge is not essential as HammerDB
      can convert this raw format into a form that can be replayed.</para>

      <figure>
        <title>Doc 39817.1</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch12-1.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
    </sect1>

    <sect1>
      <title>Converting Oracle Trace Files</title>

      <para>It is important to note that to convert Oracle trace files you
      must have selected Oracle from the treeview. If another database is
      selected the button to convert Oracle trace files is disabled Copy the
      trace file to the client machine or location where HammerDB is running
      and use the File:Open menu option or the “Open an existing file button”
      under the Edit Menu to display the Open File dialogue</para>

      <figure>
        <title>Open File</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch12-2.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The Open File dialog allows the specifying of the Directory and a
      filter for the file type, by default this is *.tcl. Change the file
      extension to ‘trc’ and change directory to the location of your files,
      select the trace file you previously generated and select OK.</para>

      <figure>
        <title>Trace Loaded</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch12-3.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Select the Trace Conversion button at the bottom of the Edit
      menu</para>

      <figure>
        <title>Convert Trace</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch12-4.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>and the trace file is converted into a format that can replayed
      against the database.</para>

      <figure>
        <title>Trace Converted</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch12-5.PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Note that the trace file never records a users’ authentication
      details. Therefore the connect string must always be modified manually
      after conversion. Remove the comment before the “set connect” line on
      line 4 and enter the correct username and password. The SID will be set
      by default to the SID that the trace file was taken from and therefore
      if using a pluggable database then the correct container must also be
      set to the correct identifier. Once the connect string is updated the
      generated script is ready for running against the database and contains
      the original statements that were traced. The save menu option or “Save
      current file” button can be used to save the generated script for
      reloading at a later point in time.</para>
    </sect1>

    <sect1>
      <title>Replaying Oracle Trace Files</title>

      <para>Next to the “Convert” button there is a “Test current code”
      button. Click on this to test the code in an individual Virtual User
      environment. Once tested the window can be closed manually or by
      clicking the same button now containing a stop image.</para>

      <para><figure>
          <title>Run Trace</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="docs/images/ch12-8.png"/>
            </imageobject>
          </mediaobject>
        </figure></para>

      <para>Once the script has been tested and is ready for running increase
      the number of Virtual Users and run as for an OLTP test.</para>

      <figure>
        <title>Multiuser Test</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="docs/images/ch12-6.png"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>The tracefile has now been replayed with multiple Virtual Users
      illustrating the basic building blocks for creating a bespoke Oracle
      workload from a captured and converted trace file.</para>
    </sect1>

    <sect1>
      <title>Capturing Errors from Trace File Workloads</title>

      <para>It must be remembered that although the previous workloads shown
      are suitable for directly replaying, with some applications replaying
      data from a previous transaction may result in constraint violations or
      updates of data that no longer exists that results in errors during
      replay. One of the most common error messages received is is the
      standard PL/SQL failure reported by Oratcl oraplexec: SQL execution
      failed. To get the actual Oracle error message underlying this error you
      can use the TCL "catch" command to capture the error and print it out
      inline. For example if you wanted to see the error in the neword
      procedure of the TPROC-C script change the oraplexec line to look like
      the following :</para>

      <programlisting>if {[ catch {oraplexec $curn1 $sql5 :no_w_id $no_w_id :no_max_w_id $w_id_input :no_d_id $no_d_id :no_c_id $no_c_id :no_o_ol_cnt $ol_cnt :no_c_discount {NULL} :no_c_last {NULL} :no_c_credit {NULL} :no_d_tax {NULL} :no_w_tax {NULL} :no_d_next_o_id {0} :timestamp $date} message]} {
puts $message
puts [ oramsg $curn1 all ]
}
</programlisting>

      <para>So you are adding the statements as below to the oraplexec
      statement</para>

      <programlisting>if {[ catch { ... } message] } {
puts $message
puts [ oramsg $curn1 all ]
}
</programlisting>

      <para>Note that the cursor variable $curn1 used in oramsg is the same
      variable used in the previous oraplexec. You can then run the script by
      pressing the test current code button ( or running one user thread with
      an output window ) The $message variable will contain and print out (
      using the "puts" command ) any TCL error and the [ oramsg $curn1 all ]
      command will then print out the oracle error from the cursor $curn1. An
      example is if the procedure neword has not yet been created: This then
      gives the full output from Oracle as shown here instead of just the
      standard message :</para>

      <programlisting>new order
{6550 {ORA-06550: line 1, column 7:
PLS-00201: identifier 'NEWORD' must be declared
ORA-06550: line 1, column 7:
PL/SQL: Statement ignored} 0 0 4 8}
</programlisting>
    </sect1>
  </chapter>

  <chapter>
    <title>HTTP and HTTPS Testing</title>

    <para>HammerDB can also be used for HTTP and HTTPS testing by using
    bespoke scripts. HammerDB uses the TLS package for HTTPS
    encryption.</para>

    <sect1>
      <title>HTTPS Script</title>

      <para>An example HTTPS script is shown. Modify the URL to your own URL.
      The example will fetch the URL in a loop for 10 iterations and report
      the time taken.</para>

      <para><programlisting>#!./bin/tclsh8.6
      package require http
      package require tls
      #package require twapi_crypto

proc http::Log {args} {
puts $args
}

proc cb {token}  {
if { [ http::status $token ] != "ok" } { error "Response not OK [ http::error $token]" } else {
http::cleanup $token
   }
set ::done 1
}


<emphasis role="bold">set url "https://MYURL"</emphasis>
#http::register https 443 [list ::twapi::tls_socket -async ]
http::register https 443 [list ::tls::socket -async -tls1 1 -ssl3 false -ssl2 false -autoservername true ]

set response [ http::geturl $url -keepalive true ]
    puts [ http::status $response ]
    set so [ lsearch -inline [ chan names ] sock* ]

chan configure $so -buffering none -encoding binary -blocking 1 -translation crlf -eofchar {{} {}}
      ::tls::handshake $so
     puts [ ::tls::status $so ]

chan configure $so -buffering full -buffersize 8192 -encoding binary -blocking 0 -translation crlf -eofchar {{} {}}
        set test_count 10
        set response_count 0
        set total_time 0
        set start_time [clock milliseconds]
        for {set i 0} {$i &lt; $test_count} {incr i} {
            set start_time [clock milliseconds]
          set ::done 0
set response [ http::geturl $url -binary true -blocksize 8192 -timeout 10000 -keepalive true -command cb ]        
vwait ::done
            set end_time [clock milliseconds]
            set elapsed [expr {$end_time - $start_time}]
            incr total_time $elapsed
            puts "Call $i took $elapsed"
            }
            set end_time [clock milliseconds]
puts "$test_count iterations in $total_time at an average of [expr {$total_time / $test_count}]"

</programlisting></para>
    </sect1>

    <sect1>
      <title>HTTPS Output</title>

      <para>The following shows the output of the script run against
      www.hammerdb.com.</para>

      <para><programlisting>Vuser 1:^A1 URL https://www.hammerdb.com - token ::http::1
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::1} keepalive
Vuser 1:^B1 begin sending request - token ::http::1
Vuser 1:^C1 end sending request - token ::http::1
Vuser 1:^D1 begin receiving response - token ::http::1
Vuser 1:^E1 end of response headers - token ::http::1
Vuser 1:^F1 end of response body (unchunked) - token ::http::1
Vuser 1:ok
Vuser 1:sha1_hash 1C27C238029A8E34DBC1C7DBDE500DCD42C38446 subject CN=hammerdb.com issuer CN=Encryption Everywhere DV TLS CA - G1,OU=www.digicert.com,O=DigiCert Inc,C=US notBefore Sep  9 00:00:00 2020 GMT notAfter Sep 19 12:00:00 2021 GMT serial 0D9F3C403C1001E7A648E621BECF67F1 certificate 
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
 sbits 256 cipher ECDHE-RSA-AES256-GCM-SHA384
Vuser 1:^A2 URL https://www.hammerdb.com - token ::http::2
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::2}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::2} keepalive
Vuser 1:^B2 begin sending request - token ::http::2
Vuser 1:^C2 end sending request - token ::http::2
Vuser 1:^D2 begin receiving response - token ::http::2
Vuser 1:^E2 end of response headers - token ::http::2
Vuser 1:^F2 end of response body (unchunked) - token ::http::2
Vuser 1:Call 0 took 175
Vuser 1:^A3 URL https://www.hammerdb.com - token ::http::3
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::3}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::3} keepalive
Vuser 1:^B3 begin sending request - token ::http::3
Vuser 1:^C3 end sending request - token ::http::3
Vuser 1:^D3 begin receiving response - token ::http::3
Vuser 1:^E3 end of response headers - token ::http::3
Vuser 1:^F3 end of response body (unchunked) - token ::http::3
Vuser 1:Call 1 took 62
Vuser 1:^A4 URL https://www.hammerdb.com - token ::http::4
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::4}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::4} keepalive
Vuser 1:^B4 begin sending request - token ::http::4
Vuser 1:^C4 end sending request - token ::http::4
Vuser 1:^D4 begin receiving response - token ::http::4
Vuser 1:^E4 end of response headers - token ::http::4
Vuser 1:^F4 end of response body (unchunked) - token ::http::4
Vuser 1:Call 2 took 56
Vuser 1:^A5 URL https://www.hammerdb.com - token ::http::5
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::5}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::5} keepalive
Vuser 1:^B5 begin sending request - token ::http::5
Vuser 1:^C5 end sending request - token ::http::5
Vuser 1:^D5 begin receiving response - token ::http::5
Vuser 1:^E5 end of response headers - token ::http::5
Vuser 1:^F5 end of response body (unchunked) - token ::http::5
Vuser 1:Call 3 took 65
Vuser 1:^A6 URL https://www.hammerdb.com - token ::http::6
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::6}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::6} keepalive
Vuser 1:^B6 begin sending request - token ::http::6
Vuser 1:^C6 end sending request - token ::http::6
Vuser 1:^D6 begin receiving response - token ::http::6
Vuser 1:^E6 end of response headers - token ::http::6
Vuser 1:^F6 end of response body (unchunked) - token ::http::6
Vuser 1:Call 4 took 73
Vuser 1:^A7 URL https://www.hammerdb.com - token ::http::7
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::7}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::7} keepalive
Vuser 1:^B7 begin sending request - token ::http::7
Vuser 1:^C7 end sending request - token ::http::7
Vuser 1:^D7 begin receiving response - token ::http::7
Vuser 1:^E7 end of response headers - token ::http::7
Vuser 1:^F7 end of response body (unchunked) - token ::http::7
Vuser 1:Call 5 took 62
Vuser 1:^A8 URL https://www.hammerdb.com - token ::http::8
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::8}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::8} keepalive
Vuser 1:^B8 begin sending request - token ::http::8
Vuser 1:^C8 end sending request - token ::http::8
Vuser 1:^D8 begin receiving response - token ::http::8
Vuser 1:^E8 end of response headers - token ::http::8
Vuser 1:^F8 end of response body (unchunked) - token ::http::8
Vuser 1:Call 6 took 77
Vuser 1:^A9 URL https://www.hammerdb.com - token ::http::9
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::9}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::9} keepalive
Vuser 1:^B9 begin sending request - token ::http::9
Vuser 1:^C9 end sending request - token ::http::9
Vuser 1:^D9 begin receiving response - token ::http::9
Vuser 1:^E9 end of response headers - token ::http::9
Vuser 1:^F9 end of response body (unchunked) - token ::http::9
Vuser 1:Call 7 took 52
Vuser 1:^A10 URL https://www.hammerdb.com - token ::http::10
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::10}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::10} keepalive
Vuser 1:^B10 begin sending request - token ::http::10
Vuser 1:^C10 end sending request - token ::http::10
Vuser 1:^D10 begin receiving response - token ::http::10
Vuser 1:^E10 end of response headers - token ::http::10
Vuser 1:^F10 end of response body (unchunked) - token ::http::10
Vuser 1:Call 8 took 52
Vuser 1:^A11 URL https://www.hammerdb.com - token ::http::11
Vuser 1:{reusing socket sock55f342ae0870 for www.hammerdb.com:443 - token ::http::11}
Vuser 1:{Using sock55f342ae0870 for www.hammerdb.com:443 - token ::http::11} keepalive
Vuser 1:^B11 begin sending request - token ::http::11
Vuser 1:^C11 end sending request - token ::http::11
Vuser 1:^D11 begin receiving response - token ::http::11
Vuser 1:^E11 end of response headers - token ::http::11
Vuser 1:^F11 end of response body (unchunked) - token ::http::11
Vuser 1:Call 9 took 53
Vuser 1:10 iterations in 727 at an average of 72
</programlisting></para>
    </sect1>
  </chapter>

  <chapter>
    <title>GNU Free Documentation License</title>

    <para>## GNU Free Documentation License</para>

    <para>Version 1.3, 3 November 2008</para>

    <para>Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation,
    Inc. &lt;https://fsf.org/&gt;</para>

    <para>Everyone is permitted to copy and distribute verbatim copies of this
    license document, but changing it is not allowed.</para>

    <para>#### 0. PREAMBLE The purpose of this License is to make a manual,
    textbook, or other functional and useful document "free" in the sense of
    freedom: to assure everyone the effective freedom to copy and redistribute
    it, with or without modifying it, either commercially or noncommercially.
    Secondarily, this License preserves for the author and publisher a way to
    get credit for their work, while not being considered responsible for
    modifications made by others.</para>

    <para>This License is a kind of "copyleft", which means that derivative
    works of the document must themselves be free in the same sense. It
    complements the GNU General Public License, which is a copyleft license
    designed for free software.</para>

    <para>We have designed this License in order to use it for manuals for
    free software, because free software needs free documentation: a free
    program should come with manuals providing the same freedoms that the
    software does. But this License is not limited to software manuals; it can
    be used for any textual work, regardless of subject matter or whether it
    is published as a printed book. We recommend this License principally for
    works whose purpose is instruction or reference.</para>

    <para>#### 1. APPLICABILITY AND DEFINITIONS</para>

    <para>This License applies to any manual or other work, in any medium,
    that contains a notice placed by the copyright holder saying it can be
    distributed under the terms of this License. Such a notice grants a
    world-wide, royalty-free license, unlimited in duration, to use that work
    under the conditions stated herein. The "Document", below, refers to any
    such manual or work. Any member of the public is a licensee, and is
    addressed as "you". You accept the license if you copy, modify or
    distribute the work in a way requiring permission under copyright
    law.</para>

    <para>A "Modified Version" of the Document means any work containing the
    Document or a portion of it, either copied verbatim, or with modifications
    and/or translated into another language.</para>

    <para>A "Secondary Section" is a named appendix or a front-matter section
    of the Document that deals exclusively with the relationship of the
    publishers or authors of the Document to the Document's overall subject
    (or to related matters) and contains nothing that could fall directly
    within that overall subject. (Thus, if the Document is in part a textbook
    of mathematics, a Secondary Section may not explain any mathematics.) The
    relationship could be a matter of historical connection with the subject
    or with related matters, or of legal, commercial, philosophical, ethical
    or political position regarding them.</para>

    <para>The "Invariant Sections" are certain Secondary Sections whose titles
    are designated, as being those of Invariant Sections, in the notice that
    says that the Document is released under this License. If a section does
    not fit the above definition of Secondary then it is not allowed to be
    designated as Invariant. The Document may contain zero Invariant Sections.
    If the Document does not identify any Invariant Sections then there are
    none.</para>

    <para>The "Cover Texts" are certain short passages of text that are
    listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says
    that the Document is released under this License. A Front-Cover Text may
    be at most 5 words, and a Back-Cover Text may be at most 25 words.</para>

    <para>A "Transparent" copy of the Document means a machine-readable copy,
    represented in a format whose specification is available to the general
    public, that is suitable for revising the document straightforwardly with
    generic text editors or (for images composed of pixels) generic paint
    programs or (for drawings) some widely available drawing editor, and that
    is suitable for input to text formatters or for automatic translation to a
    variety of formats suitable for input to text formatters. A copy made in
    an otherwise Transparent file format whose markup, or absence of markup,
    has been arranged to thwart or discourage subsequent modification by
    readers is not Transparent. An image format is not Transparent if used for
    any substantial amount of text. A copy that is not "Transparent" is called
    "Opaque".</para>

    <para>Examples of suitable formats for Transparent copies include plain
    ASCII without markup, Texinfo input format, LaTeX input format, SGML or
    XML using a publicly available DTD, and standard-conforming simple HTML,
    PostScript or PDF designed for human modification. Examples of transparent
    image formats include PNG, XCF and JPG. Opaque formats include proprietary
    formats that can be read and edited only by proprietary word processors,
    SGML or XML for which the DTD and/or processing tools are not generally
    available, and the machine-generated HTML, PostScript or PDF produced by
    some word processors for output purposes only.</para>

    <para>The "Title Page" means, for a printed book, the title page itself,
    plus such following pages as are needed to hold, legibly, the material
    this License requires to appear in the title page. For works in formats
    which do not have any title page as such, "Title Page" means the text near
    the most prominent appearance of the work's title, preceding the beginning
    of the body of the text.</para>

    <para>The "publisher" means any person or entity that distributes copies
    of the Document to the public.</para>

    <para>A section "Entitled XYZ" means a named subunit of the Document whose
    title either is precisely XYZ or contains XYZ in parentheses following
    text that translates XYZ in another language. (Here XYZ stands for a
    specific section name mentioned below, such as "Acknowledgements",
    "Dedications", "Endorsements", or "History".) To "Preserve the Title" of
    such a section when you modify the Document means that it remains a
    section "Entitled XYZ" according to this definition.</para>

    <para>The Document may include Warranty Disclaimers next to the notice
    which states that this License applies to the Document. These Warranty
    Disclaimers are considered to be included by reference in this License,
    but only as regards disclaiming warranties: any other implication that
    these Warranty Disclaimers may have is void and has no effect on the
    meaning of this License.</para>

    <para>#### 2. VERBATIM COPYING</para>

    <para>You may copy and distribute the Document in any medium, either
    commercially or noncommercially, provided that this License, the copyright
    notices, and the license notice saying this License applies to the
    Document are reproduced in all copies, and that you add no other
    conditions whatsoever to those of this License. You may not use technical
    measures to obstruct or control the reading or further copying of the
    copies you make or distribute. However, you may accept compensation in
    exchange for copies. If you distribute a large enough number of copies you
    must also follow the conditions in section 3.</para>

    <para>You may also lend copies, under the same conditions stated above,
    and you may publicly display copies.</para>

    <para>#### 3. COPYING IN QUANTITY</para>

    <para>If you publish printed copies (or copies in media that commonly have
    printed covers) of the Document, numbering more than 100, and the
    Document's license notice requires Cover Texts, you must enclose the
    copies in covers that carry, clearly and legibly, all these Cover Texts:
    Front-Cover Texts on the front cover, and Back-Cover Texts on the back
    cover. Both covers must also clearly and legibly identify you as the
    publisher of these copies. The front cover must present the full title
    with all words of the title equally prominent and visible. You may add
    other material on the covers in addition. Copying with changes limited to
    the covers, as long as they preserve the title of the Document and satisfy
    these conditions, can be treated as verbatim copying in other
    respects.</para>

    <para>If the required texts for either cover are too voluminous to fit
    legibly, you should put the first ones listed (as many as fit reasonably)
    on the actual cover, and continue the rest onto adjacent pages.</para>

    <para>If you publish or distribute Opaque copies of the Document numbering
    more than 100, you must either include a machine-readable Transparent copy
    along with each Opaque copy, or state in or with each Opaque copy a
    computer-network location from which the general network-using public has
    access to download using public-standard network protocols a complete
    Transparent copy of the Document, free of added material. If you use the
    latter option, you must take reasonably prudent steps, when you begin
    distribution of Opaque copies in quantity, to ensure that this Transparent
    copy will remain thus accessible at the stated location until at least one
    year after the last time you distribute an Opaque copy (directly or
    through your agents or retailers) of that edition to the public.</para>

    <para>It is requested, but not required, that you contact the authors of
    the Document well before redistributing any large number of copies, to
    give them a chance to provide you with an updated version of the
    Document.</para>

    <para>#### 4. MODIFICATIONS</para>

    <para>You may copy and distribute a Modified Version of the Document under
    the conditions of sections 2 and 3 above, provided that you release the
    Modified Version under precisely this License, with the Modified Version
    filling the role of the Document, thus licensing distribution and
    modification of the Modified Version to whoever possesses a copy of it. In
    addition, you must do these things in the Modified Version:</para>

    <para>- A. Use in the Title Page (and on the covers, if any) a title
    distinct from that of the Document, and from those of previous versions
    (which should, if there were any, be listed in the History section of the
    Document). You may use the same title as a previous version if the
    original publisher of that version gives permission.</para>

    <para>- B. List on the Title Page, as authors, one or more persons or
    entities responsible for authorship of the modifications in the Modified
    Version, together with at least five of the principal authors of the
    Document (all of its principal authors, if it has fewer than five), unless
    they release you from this requirement.</para>

    <para>- C. State on the Title page the name of the publisher of the
    Modified Version, as the publisher.</para>

    <para>- D. Preserve all the copyright notices of the Document.</para>

    <para>- E. Add an appropriate copyright notice for your modifications
    adjacent to the other copyright notices.</para>

    <para>- F. Include, immediately after the copyright notices, a license
    notice giving the public permission to use the Modified Version under the
    terms of this License, in the form shown in the Addendum below.</para>

    <para>- G. Preserve in that license notice the full lists of Invariant
    Sections and required Cover Texts given in the Document's license
    notice.</para>

    <para>- H. Include an unaltered copy of this License.</para>

    <para>- I. Preserve the section Entitled "History", Preserve its Title,
    and add to it an item stating at least the title, year, new authors, and
    publisher of the Modified Version as given on the Title Page. If there is
    no section Entitled "History" in the Document, create one stating the
    title, year, authors, and publisher of the Document as given on its Title
    Page, then add an item describing the Modified Version as stated in the
    previous sentence.</para>

    <para>- J. Preserve the network location, if any, given in the Document
    for public access to a Transparent copy of the Document, and likewise the
    network locations given in the Document for previous versions it was based
    on. These may be placed in the "History" section. You may omit a network
    location for a work that was published at least four years before the
    Document itself, or if the original publisher of the version it refers to
    gives permission.</para>

    <para>- K. For any section Entitled "Acknowledgements" or "Dedications",
    Preserve the Title of the section, and preserve in the section all the
    substance and tone of each of the contributor acknowledgements and/or
    dedications given therein.</para>

    <para>- L. Preserve all the Invariant Sections of the Document, unaltered
    in their text and in their titles. Section numbers or the equivalent are
    not considered part of the section titles.</para>

    <para>- M. Delete any section Entitled "Endorsements". Such a section may
    not be included in the Modified Version.</para>

    <para>- N. Do not retitle any existing section to be Entitled
    "Endorsements" or to conflict in title with any Invariant Section.</para>

    <para>- O. Preserve any Warranty Disclaimers.</para>

    <para>If the Modified Version includes new front-matter sections or
    appendices that qualify as Secondary Sections and contain no material
    copied from the Document, you may at your option designate some or all of
    these sections as invariant. To do this, add their titles to the list of
    Invariant Sections in the Modified Version's license notice. These titles
    must be distinct from any other section titles.</para>

    <para>You may add a section Entitled "Endorsements", provided it contains
    nothing but endorsements of your Modified Version by various parties for
    example, statements of peer review or that the text has been approved by
    an organization as the authoritative definition of a standard.</para>

    <para>You may add a passage of up to five words as a Front-Cover Text, and
    a passage of up to 25 words as a Back-Cover Text, to the end of the list
    of Cover Texts in the Modified Version. Only one passage of Front-Cover
    Text and one of Back-Cover Text may be added by (or through arrangements
    made by) any one entity. If the Document already includes a cover text for
    the same cover, previously added by you or by arrangement made by the same
    entity you are acting on behalf of, you may not add another; but you may
    replace the old one, on explicit permission from the previous publisher
    that added the old one.</para>

    <para>The author(s) and publisher(s) of the Document do not by this
    License give permission to use their names for publicity for or to assert
    or imply endorsement of any Modified Version.</para>

    <para>#### 5. COMBINING DOCUMENTS</para>

    <para>You may combine the Document with other documents released under
    this License, under the terms defined in section 4 above for modified
    versions, provided that you include in the combination all of the
    Invariant Sections of all of the original documents, unmodified, and list
    them all as Invariant Sections of your combined work in its license
    notice, and that you preserve all their Warranty Disclaimers.</para>

    <para>The combined work need only contain one copy of this License, and
    multiple identical Invariant Sections may be replaced with a single copy.
    If there are multiple Invariant Sections with the same name but different
    contents, make the title of each such section unique by adding at the end
    of it, in parentheses, the name of the original author or publisher of
    that section if known, or else a unique number. Make the same adjustment
    to the section titles in the list of Invariant Sections in the license
    notice of the combined work.</para>

    <para>In the combination, you must combine any sections Entitled "History"
    in the various original documents, forming one section Entitled "History";
    likewise combine any sections Entitled "Acknowledgements", and any
    sections Entitled "Dedications". You must delete all sections Entitled
    "Endorsements".</para>

    <para>#### 6. COLLECTIONS OF DOCUMENTS</para>

    <para>You may make a collection consisting of the Document and other
    documents released under this License, and replace the individual copies
    of this License in the various documents with a single copy that is
    included in the collection, provided that you follow the rules of this
    License for verbatim copying of each of the documents in all other
    respects.</para>

    <para>You may extract a single document from such a collection, and
    distribute it individually under this License, provided you insert a copy
    of this License into the extracted document, and follow this License in
    all other respects regarding verbatim copying of that document.</para>

    <para>#### 7. AGGREGATION WITH INDEPENDENT WORKS</para>

    <para>A compilation of the Document or its derivatives with other separate
    and independent documents or works, in or on a volume of a storage or
    distribution medium, is called an "aggregate" if the copyright resulting
    from the compilation is not used to limit the legal rights of the
    compilation's users beyond what the individual works permit. When the
    Document is included in an aggregate, this License does not apply to the
    other works in the aggregate which are not themselves derivative works of
    the Document.</para>

    <para>If the Cover Text requirement of section 3 is applicable to these
    copies of the Document, then if the Document is less than one half of the
    entire aggregate, the Document's Cover Texts may be placed on covers that
    bracket the Document within the aggregate, or the electronic equivalent of
    covers if the Document is in electronic form. Otherwise they must appear
    on printed covers that bracket the whole aggregate.</para>

    <para>#### 8. TRANSLATION</para>

    <para>Translation is considered a kind of modification, so you may
    distribute translations of the Document under the terms of section 4.
    Replacing Invariant Sections with translations requires special permission
    from their copyright holders, but you may include translations of some or
    all Invariant Sections in addition to the original versions of these
    Invariant Sections. You may include a translation of this License, and all
    the license notices in the Document, and any Warranty Disclaimers,
    provided that you also include the original English version of this
    License and the original versions of those notices and disclaimers. In
    case of a disagreement between the translation and the original version of
    this License or a notice or disclaimer, the original version will
    prevail.</para>

    <para>If a section in the Document is Entitled "Acknowledgements",
    "Dedications", or "History", the requirement (section 4) to Preserve its
    Title (section 1) will typically require changing the actual title.</para>

    <para>#### 9. TERMINATION</para>

    <para>You may not copy, modify, sublicense, or distribute the Document
    except as expressly provided under this License. Any attempt otherwise to
    copy, modify, sublicense, or distribute it is void, and will automatically
    terminate your rights under this License.</para>

    <para>However, if you cease all violation of this License, then your
    license from a particular copyright holder is reinstated (a)
    provisionally, unless and until the copyright holder explicitly and
    finally terminates your license, and (b) permanently, if the copyright
    holder fails to notify you of the violation by some reasonable means prior
    to 60 days after the cessation.</para>

    <para>Moreover, your license from a particular copyright holder is
    reinstated permanently if the copyright holder notifies you of the
    violation by some reasonable means, this is the first time you have
    received notice of violation of this License (for any work) from that
    copyright holder, and you cure the violation prior to 30 days after your
    receipt of the notice.</para>

    <para>Termination of your rights under this section does not terminate the
    licenses of parties who have received copies or rights from you under this
    License. If your rights have been terminated and not permanently
    reinstated, receipt of a copy of some or all of the same material does not
    give you any rights to use it.</para>

    <para>#### 10. FUTURE REVISIONS OF THIS LICENSE</para>

    <para>The Free Software Foundation may publish new, revised versions of
    the GNU Free Documentation License from time to time. Such new versions
    will be similar in spirit to the present version, but may differ in detail
    to address new problems or concerns. See
    &lt;https://www.gnu.org/licenses/&gt;.</para>

    <para>Each version of the License is given a distinguishing version
    number. If the Document specifies that a particular numbered version of
    this License "or any later version" applies to it, you have the option of
    following the terms and conditions either of that specified version or of
    any later version that has been published (not as a draft) by the Free
    Software Foundation. If the Document does not specify a version number of
    this License, you may choose any version ever published (not as a draft)
    by the Free Software Foundation. If the Document specifies that a proxy
    can decide which future versions of this License can be used, that proxy's
    public statement of acceptance of a version permanently authorizes you to
    choose that version for the Document.</para>

    <para>#### 11. RELICENSING</para>

    <para>"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
    World Wide Web server that publishes copyrightable works and also provides
    prominent facilities for anybody to edit those works. A public wiki that
    anybody can edit is an example of such a server. A "Massive Multiauthor
    Collaboration" (or "MMC") contained in the site means any set of
    copyrightable works thus published on the MMC site.</para>

    <para>"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
    license published by Creative Commons Corporation, a not-for-profit
    corporation with a principal place of business in San Francisco,
    California, as well as future copyleft versions of that license published
    by that same organization.</para>

    <para>"Incorporate" means to publish or republish a Document, in whole or
    in part, as part of another Document.</para>

    <para>An MMC is "eligible for relicensing" if it is licensed under this
    License, and if all works that were first published under this License
    somewhere other than this MMC, and subsequently incorporated in whole or
    in part into the MMC, (1) had no cover texts or invariant sections, and
    (2) were thus incorporated prior to November 1, 2008.</para>

    <para>The operator of an MMC Site may republish an MMC contained in the
    site under CC-BY-SA on the same site at any time before August 1, 2009,
    provided the MMC is eligible for relicensing.</para>
  </chapter>
</book>