libtabula

## ------------------------
## Input files
## ------------------------

HTML_DIR=../html/userman
BASENAME=userman
DOCFILE=$(BASENAME).dbx
PDFFILE=../pdf/$(BASENAME).pdf
FOFILE=$(BASENAME).fo
COMMON_SS=common.xsl
FO_SS=fo.xsl
HTML_SS=html.xsl
EX_TXT=cgi_jpeg.txt cpool.txt deadlock.txt fieldinf.txt for_each.txt \
		load_jpeg.txt multiquery.txt resetdb.txt simple1.txt \
		simple2.txt simple3.txt ssqls1.txt ssqls2.txt ssqls3.txt \
		ssqls4.txt ssqls5.txt ssqls6.txt stock.txt store_if.txt \
		tquery1.txt transaction.txt


## ------------------------
## Major output rules
## ------------------------

html: $(EX_TXT) $(HTML_DIR)/index.html

pdf: $(EX_TXT) $(PDFFILE)


## ------------------------
## Standard Makefile targets
## ------------------------

# Notice that this is not the first target in the file, as is standard.
# PDF generation takes longer than HTML generation, so to keep the code-
# test-debug-rebuild cycle short, we generate only the HTML manual by
# default.  You can explicitly say "make pdf" or "make all" when you're
# sure the DocBook file's contents are correct.
all: html pdf

clean:
	@rm -f tags *.fo $(HTML_DIR)/*.html *.log *.out *.pdf $(EX_TXT) $(PDFFILE)


## ------------------------
## How to make output files
## ------------------------

$(PDFFILE): *.dbx *.in $(FO_SS) $(COMMON_SS)
	xsltproc --xinclude $(FO_SS) $(DOCFILE) > $(FOFILE)
	mkdir -p ../pdf
	./fo2pdf $(FOFILE) $(PDFFILE)


$(HTML_DIR)/index.html: *.dbx *.in *.mod *.txt *.xsl
	@xmllint --xinclude --nonet --postvalid --noent --noout $(DOCFILE)
	xsltproc --xinclude --nonet -o $(HTML_DIR)/ $(HTML_SS) $(DOCFILE)


## ------------------------

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="breakages">
  <title>Incompatible Library Changes</title>

  <para>This chapter documents those library changes since the v4.0.0
  fork with MySQL++ that break end-user programs. You can dig this stuff
  out of the <filename>ChangeLog.md</filename> file, but the change log
  focuses more on explaining and justifying the facets of each change,
  while this section focuses on how to migrate your code between these
  library versions.</para>

  <para>Since pure additions do not break programs, those changes are
  still documented only in the change log.</para>


  <sect2 id="api-changes">
    <title>API Changes</title>

    <para>This section documents files, functions, methods and classes
    that were removed or changed in an incompatible way. If your
    program uses the changed item, you will have to change something
    in your program to get it to compile after upgrading to each of
    these versions.</para>

    <sect3 id="api-4.0.0">
      <title>v4.0.0</title>

      <subtitle>Or, differences between MySQL++ 3.2.4 and
      libtabula</subtitle>

      <para>Renamed library files from <filename>*mysqlpp*</filename>
      to <filename>*tabula*</filename>. On Unixy platforms, this
      means the actual library file will be called something
      like <filename>libtabula.*</filename>, which is where the
      new name comes from. (I didn&#x2019;t want to call it just

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="configuration">
  <title>Configuring libtabula</title>

  <para>The default configuration of libtabula is suitable for most
  purposes, but there are a few things you can change to make it meet
  special needs.</para>

#!/bin/bash
AHCMD=/usr/XSLFormatterV42/run.sh
FOPCMD=$(type -p fop)
XEPCMD=/usr/local/xep/xep

FOFILE=$1
PDFFILE=$2
if [ -n "$FOFILE" -a -r "$FOFILE" -a -n "$PDFFILE" ]
then
	if [ -x "$XEPCMD" ]

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="incorporating">
  <title>Using libtabula in Your Own Project</title>

  <para>Up to now, this manual has only discussed libtabula
  in conjunction with the example programs that come with the
  library. This chapter covers the steps you need to take to

    <filename>Makefiles</filename> you have seen collect both types
    of flags in a single variable. That can work if the variable
    is used in the right place in the link command. However, this
    particular <filename>Makefile</filename> is made with GNU make
    in mind, and uses its standard rules implicitly. Those rules
    are designed to use these two variables separately like this.
    If you were writing your own compilation rules, you could write
    them in such a way that you didn&rsquo;t have to do this.</para>

    <para>Beyond that, we have a pretty vanilla
    <filename>Makefile</filename>, thanks in large part to the fact
    that the default <filename>make</filename> rules are fine for
    such a simple program.</para>
  </sect2>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="intro">
  <title>Introduction</title>

  <para>libtabula is a powerful C++ wrapper for multiple C database
  access libraries. The initial version supports MySQL, MariaDB, and
  SQLite. Its purpose is to make working with SQL queries as easy as

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="licenses">
  <title>Licensing</title>

  <para>The primary copyright holders on libtabula and its documentation
  are Kevin Atkinson (© 1998), MySQL AB (© 1999 through 2001) and
  Educational Technology Resources, Inc. (© 2004 through the date of
  this writing).  There are other contributors, who also retain
  copyrights on their additions; see the
  <filename>ChangeLog.md</filename> file in the distribution tarball for
  details. Contributions made prior to May 2014 were done to MySQL++,
  the predecessor to this library.</para>

  <para>The libtabula library and its Reference Manual are released under
  the GNU Lesser General Public License (LGPL), reproduced below.</para>

  <para>The libtabula User Manual &mdash; excepting some example code from
  the library reproduced within it &mdash; is offered under a license
  closely based on the Linux Documentation Project License (LDPL) v2.0,

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="overview">
  <title>Overview</title>

  <para>libtabula has a lot of complexity and power to cope with the
  variety of DBMSes and uses for them, but at bottom it doesn&#x2019;t
  work all that differently than other database access APIs. The

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="SOMETHING_UNIQUE">
  <title>SECTION TITLE</title>

  <para>FIRST PARAGRAPH</para>
</sect1>

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="ssqls">
  <title>Specialized SQL Structures</title>

  <para>The Specialized SQL Structure (SSQLS) feature lets you easily
  define C++ structures that match the form of your SQL tables. At the
  most superficial level, an SSQLS has a member variable corresponding

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="threads">
  <title>Using libtabula in a Multithreaded Program</title>

  <para>libtabula is not &#x201C;thread safe&#x201D; in any
  meaningful sense. libtabula contains very little code that
  actively prevents trouble with threads, and all of it is

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="tquery" xreflabel="Template Queries">
  <title>Template Queries</title>

  <para>Another powerful feature of libtabula is being able to set up
  template queries. These are kind of like C&#x2019;s
  <function>printf()</function> facility: you give libtabula a string

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="tutorial" xreflabel="Tutorial">
  <title>Tutorial</title>

  <para>The <link linkend="overview">previous chapter</link> introduced
  the major top-level mechanisms in libtabula. Now we&#x2019;ll dig
  down a little deeper and get into real examples. We start off

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<sect1 id="unicode" xreflabel="Using Unicode with libtabula">
  <title>Using Unicode with libtabula</title>

  <sect2 id="unicode-history">
    <title>A Short History of Unicode</title>
    <subtitle>...with a focus on relevance to libtabula</subtitle>

    common 7-bit ASCII subset.  Either people used approximations like a
    plain “c” instead of the French “ç”,
    or they invented things like HTML entities
    (“ç” in this case) to encode these additional
    characters using only 7-bit ASCII.</para>

    <para>Unicode solves this problem. It encodes every character used
    for writing in the world, using up to 4 bytes per character.  Before
    emoji became popular, the subset covering the most economically
    valuable cases fit into the lower 65536 code points, so you could
    encode most texts using only two bytes per character.  Many
    nominally Unicode-aware programs only support this subset, called


    the Basic Multilingual Plane, or BMP.</para>

  
    <para>Unfortunately, Unicode was invented about two decades too late
    for Unix and C. Those decades of legacy created an immense inertia
    preventing a widespread move away from 8-bit characters. MySQL and
    C++ come out of these older traditions, and so they share the same
    practical limitations. MySQL++ doesn&#x2019;t have any code in it
    for Unicode conversions, and it likely never will; it just passes
    data along unchanged from the underlying MySQL C API, so you still
    need to be aware of these underlying issues.</para>

    <para>During the development of the <ulink
    url="http://en.wikipedia.org/wiki/Plan_9_from_Bell_Labs">Plan
    9</ulink> operating system (a kind of successor to Unix) Ken
    Thompson <ulink
    url="http://www.cl.cam.ac.uk/~mgk25/ucs/utf-8-history.txt">invented</ulink>
    the <ulink url="http://en.wikipedia.org/wiki/UTF-8">UTF-8
    encoding</ulink>. UTF-8 is a superset of 7-bit ASCII and is
    compatible with C strings, since it doesn&#x2019;t use 0 bytes
    anywhere as multi-byte Unicode encodings do. As a result, many
    programs that deal in text will cope with UTF-8 data even though
    they have no explicit support for UTF-8. Follow the last link above
    to see how the design of UTF-8 allows this.</para>
  </sect2>


  <sect2 id="unicode-mysql">
    <title>Unicode in MySQL</title>

    <para>Since MySQL comes out of the Unix world, and it predates the
    widespread use of UTF-8 in Unix, the early versinos of MySQL had no
    explicit support for Unicode. From the start, you could store raw
    UTF-8 strings, but it wouldn&#x2019;t know how to do things like
    sort a column of UTF-8 strings.</para>

    <para>MySQL 4.1 added the first explicit support for Unicode. This
    version of MySQL supported only the BMP, meaning that if you told it
    to expect strings to be in UTF-8, it could only use up to 3 bytes
    per character.</para>

    <para>MySQL 5.5 was the first release to completely support Unicode.
    Because the BMP-only Unicode support had been in the wild for about
    6 years by that point, and changing to the new character set
    requires a table rebuild, the new one was called
    &#x201C;utf8mb4&#x201D; rather than change the longstanding meaning
    of &#x201C;utf8&#x201D; in MySQL. This release also added a new
    alias for the old UTF-8 subset character set,
    &#x201C;utf8mb3.&#x201D;</para>

    <para>Finally, in MySQL 8.0, &#x201C;utf8mb4&#x201D; became the
    default character set. For backwards compatibility,
    &#x201C;utf8&#x201D; remains an alias for
    &#x201C;utf8mb3.&#x201D;</para>

    <para>We&#x2019;ve defined the <varname>LIBTABULA_UTF8_CS</varname>
    and <varname>LIBTABULA_UTF8_COL</varname> macros which expand to
    &#x201C;utf8mb4&#x201D; and &#x201C;utf8mb4_general_ci&#x201D; when
    you build this library against MySQL 5.5 and newer and to
    &#x201C;utf8&#x201D; and &#x201C;utf8_general_ci&#x201D; otherwise.
    We use these macros in our <filename>resetdb</filename> example;
    you're welcome to use them in your code as well.</para>
  </sect2>


  <sect2 id="unicode-unix">
    <title>Unicode on Unixy Systems</title>

    <para>Linux and Unix have system-wide UTF-8 support these days. If

    <function>iconv()</function> should suffice.</para>
  </sect2>


  <sect2 id="unicode-windows">
    <title>Unicode on Windows</title>

    <para>Each Windows API function that takes a string actually comes
    in two versions. One version supports only 1-byte
    &#x201C;ANSI&#x201D; characters (a superset of ASCII), so they end

    in 'A'. Since Windows XP, there is also a parallel set of APIs


    ending in 'W' (meaning &#x201C;wide&#x201D;) that expect <ulink
    url="http://en.wikipedia.org/wiki/UTF-16">UTF-16</ulink> encoded





    strings. The <function><ulink
    url="http://msdn.microsoft.com/library/en-us/winui/winui/windowsuserinterface/windowing/dialogboxes/dialogboxreference/dialogboxfunctions/messagebox.asp">MessageBox</ulink>()</function>
    API, for instance, is actually a macro, not a real function. If you
    define the <symbol>UNICODE</symbol> macro when building your
    program, the <function>MessageBox()</function> macro evaluates to
    <function>MessageBoxW()</function>; otherwise, to
    <function>MessageBoxA()</function>.</para>

    <para>Most open source DBMSes these days use the UTF-8 Unicode
    encoding by preference but Windows uses UTF-16 instead.  Because
    of that, you probably need to convert data when passing text
    between libtabula and the Windows API. Since there&#x2019;s no
    point in trying for portability &mdash; no other OS I&#x2019;m
    aware of natively uses UTF-16 &mdash; you might as well use

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                         "http://www.docbook.org/xml/4.4/docbookx.dtd"
[ <!ENTITY % xinclude SYSTEM "xinclude.mod">
%xinclude;
]>
<article>
	<articleinfo>
		<title>libtabula v@LIBTABULA_VERSION_MAJOR@.@LIBTABULA_VERSION_MINOR@.@LIBTABULA_VERSION_BUGFIX@ User Manual</title>

			<author>
				<firstname>Warren</firstname>
				<surname>Young</surname>
			</author>
		</authorgroup>

		<copyright>
			<year>1998-2001, 2005-2018</year>
			<holder>Kevin Atkinson (original author)</holder>
			<holder>MySQL AB</holder>
			<holder>Educational Technology Resources</holder>
		</copyright>

		<pubdate><?dbtimestamp format="B d, Y"?></pubdate>
	</articleinfo>

/***********************************************************************
 resetdb.cpp - (Re)initializes the libtabula example database.

	You must run this at least once before running most of the other
	examples, and it is helpful sometimes to run it again, as some of
	the examples modify the table in this database.

 Copyright © 1998 by Kevin Atkinson, © 1999-2001 by MySQL AB, and
 © 2004-2009, 2018 by Educational Technology Resources, Inc.  Others may
 also hold copyrights on code in this file.  See the CREDITS file in
 the top directory of the distribution for details.

 This file is part of libtabula.

 libtabula is free software; you can redistribute it and/or modify it
 under the terms of the GNU Lesser General Public License as published

				"CREATE TABLE stock (" <<
				"  item CHAR(30) NOT NULL, " <<
				"  num BIGINT NOT NULL, " <<
				"  weight DOUBLE NOT NULL, " <<
				"  price DECIMAL(6,2) NULL, " << // NaN & inf. == NULL
				"  sdate DATE NOT NULL, " <<
				"  description MEDIUMTEXT NULL) " <<
				"ENGINE = InnoDB" <<
				" CHARACTER SET "LIBTABULA_UTF8_CS
                " COLLATE " LIBTABULA_UTF8_COL;
		query.execute();

		// Set up the template query to insert the data.  The parse()
		// call tells the query object that this is a template and
		// not a literal query string.
		query << "insert into %6:table values " <<
				"(%0q, %1q, %2, %3, %4q, %5q:desc)";

	emake || die "unable to make"
}

src_install() {
	emake DESTDIR="${D}" install || die
	# install the docs and HTML pages
	dodoc README* CREDITS.md ChangeLog.md HACKERS.md Wishlist.md
	dodoc doc/*
	cp -ra doc/html "${D}"/usr/share/doc/${PF}/html
	prepalldocs
}

// C++11 added unique_ptr as a replacement for auto_ptr.  We don't have
// the ABI problem above with this one, so we switch to it with the
// oldest release possible.  As with the above ifdef, this one only
// currently works for g++ and clang++.
#if __cplusplus >= 201103L
#	define UNIQUE_PTR(what) std::unique_ptr<what>
#else
#	define UNIQUE_PTR(what) std::auto_ptr<what>
#endif

namespace libtabula {

/// \brief Alias for 'true', to make code requesting exceptions more
/// readable.

// while actually working with C++.  This is why we disobey the MySQL
// developer docs, which recommend including my_global.h before mysql.h.
#if defined(LIBTABULA_MYSQL_HEADERS_BURIED)
#	include <mysql/mysql.h>
#else
#	include <mysql.h>
#endif

// The Unicode chapter of the user manual justifies the following.
#if MYSQL_VERSION_ID >= 50500
    /// \brief Use this macro in CREATE TABLE strings to get the best
    /// available UTF-8 character set.
    ///
    /// MySQL++ is built against MySQL or MariaDB 5.5 or newer, so these
    /// macros are defined so that programs using them get the complete
    /// UTF-8 character set.
#   define LIBTABULA_UTF8_CS  "utf8mb4"

    /// \brief Use this macro in CREATE TABLE strings to get a matching
    /// collation to the character set selected by LIBTABULA_UTF8_CS
#   define LIBTABULA_UTF8_COL "utf8mb4_general_ci"
#else
    /// \brief Use this macro in CREATE TABLE strings to get the best
    /// available UTF-8 character set and correpsonding collation.
    ///
    /// MySQL++ is built against a version of MySQL or MariaDB older than
    /// 5.5, so we must use the legacy 3-byte-limited subset of UTF-8.
#   define LIBTABULA_UTF8_CS  "utf8"

    /// \brief Use this macro in CREATE TABLE strings to get a matching
    /// collation to the character set selected by LIBTABULA_UTF8_CS
#   define LIBTABULA_UTF8_COL "utf8_general_ci"
#endif

#endif // !defined(LIBTABULA_COMMON_H)

/***********************************************************************
 dbdriver.cpp - Implements the DBDriver class.

 Copyright © 2005-2009, 2014, 2018 by Educational Technology Resources,
 Inc.  Others may also hold copyrights on code in this file.  See the
 CREDITS.md file in the top directory of the distribution for details.

 This file is part of libtabula.

 libtabula is free software; you can redistribute it and/or modify it
 under the terms of the GNU Lesser General Public License as published
 by the Free Software Foundation; either version 2.1 of the License, or

 License along with libtabula; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
 USA
***********************************************************************/

#define LIBTABULA_NOT_HEADER
#include "dbdriver.h"

#include "common.h"

using namespace std;

namespace libtabula {

DBDriver::DBDriver(bool te) :
OptionalExceptions(te),

// High-level option setting mechanism, called by Connection::set_option()
// and by apply_pending_options().  Lower levels are in the leaf classes.

bool
DBDriver::set_option(Option* o)
{
	// Ensure o gets destroyed if there is a fatal error or exception
	UNIQUE_PTR(Option) cleanup(o);

	option_error_ = o->set(this);
	if (option_error_ == Option::err_NONE) {
		// It was applied successfully, so save it until destruction of
		// the driver so we know what options have already been applied.
		applied_options_.push_back(o);
		cleanup.release();

	// the option value, which is as it should be.
	int n = o;
	while (n && ((n & 1) == 0)) {
		n >>= 1;
	}
	
	if ((n == 1) &&
#ifdef CLIENT_LONG_PASSWORD
			(o >= CLIENT_LONG_PASSWORD) &&
#else
			(o >= CLIENT_MYSQL) &&
#endif
#if MYSQL_VERSION_ID > 40000	// highest flag value varies by version
			(o <= CLIENT_MULTI_RESULTS)
#else
			(o <= CLIENT_TRANSACTIONS)
#endif
			) {
		// Option value seems sane, so go ahead and set/clear the flag

#endif
}


bool
MySQLDriver::shutdown()
{
#if (MYSQL_VERSION_ID >= 80000)
    // The C API function we were depending on is removed in 8.0.0.  It
    // was replaced in 8.0.1, but they claim they're going to remove it
    // again later, so we prefer to behave as if it's gone for good as
    // of 8.0.0, so we've got a well-tested workaround before then.
    return connected() ? execute("SHUTDOWN", 8) : false;
#elif ((MYSQL_VERSION_ID >= 40103) && (MYSQL_VERSION_ID <= 49999)) || (MYSQL_VERSION_ID >= 50001)
    // An argument was added to mysql_shutdown() in MySQL 4.1.3 and 5.0.1.
	return mysql_shutdown(&mysql_, SHUTDOWN_DEFAULT);
#else
    // Prior versions had no argument
	return mysql_shutdown(&mysql_);
#endif
}


bool
MySQLDriver::thread_aware()
{
#if defined(LIBTABULA_PLATFORM_WINDOWS) || defined(HAVE_PTHREAD) || defined(HAVE_SYNCH_H)

/// \file refcounted.h
/// \brief Declares the RefCountedPointer template

/***********************************************************************
 Copyright © 2007-2011, 2018 by Educational Technology Resources, Inc.
 and © 2007 by Jonathan Wakely.  Others may also hold copyrights on code
 in this file.  See the CREDITS.md file in the top directory of the
 distribution for details.

 This file is part of libtabula.

 libtabula is free software; you can redistribute it and/or modify it
 under the terms of the GNU Lesser General Public License as published
 by the Free Software Foundation; either version 2.1 of the License, or
 (at your option) any later version.