You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafodion.apache.org by sv...@apache.org on 2016/01/14 19:18:11 UTC
[07/42] incubator-trafodion git commit: Rechecking of asciidoc
conversion due to weird Windows10 upgrade.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/pom.xml
----------------------------------------------------------------------
diff --git a/docs/odb_user/pom.xml b/docs/odb_user/pom.xml
new file mode 100644
index 0000000..0f1d2db
--- /dev/null
+++ b/docs/odb_user/pom.xml
@@ -0,0 +1,219 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <!--
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+-->
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.apache.trafodion</groupId>
+ <artifactId>odb-user-guide</artifactId>
+ <version>1.3.0</version>
+ <packaging>pom</packaging>
+ <name>Trafodion odb User Guide</name>
+ <description>This guide describes how to odb, a multi-threaded, ODBC-based command-line tool, to perform various operations on a Trafodion database.</description>
+ <url>http://trafodion.incubator.apache.org</url>
+ <inceptionYear>2015</inceptionYear>
+
+ <licenses>
+ <license>
+ <name>The Apache Software License, Version 2.0</name>
+ <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+ <distribution>repo</distribution>
+ <comments>A business-friendly OSS license</comments>
+ </license>
+ </licenses>
+
+ <organization>
+ <name>Apache Software Foundation</name>
+ <url>http://www.apache.org</url>
+ </organization>
+
+ <issueManagement>
+ <system>JIRA</system>
+ <url>http://issues.apache.org/jira/browse/TRAFODION</url>
+ </issueManagement>
+
+ <scm>
+ <connection>scm:git:http://git-wip-us.apache.org/repos/asf/incubator-trafodion.git</connection>
+ <developerConnection>scm:git:https://git-wip-us.apache.org/repos/asf/incubator-trafodion.git</developerConnection>
+ <url>https://git-wip-us.apache.org/repos/asf?p=incubator-trafodion.git</url>
+ <tag>HEAD</tag>
+ </scm>
+
+ <ciManagement>
+ <system>Jenkins</system>
+ <url>https://jenkins.esgyn.com</url>
+ </ciManagement>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <asciidoctor.maven.plugin.version>1.5.2.1</asciidoctor.maven.plugin.version>
+ <asciidoctorj.pdf.version>1.5.0-alpha.10.1</asciidoctorj.pdf.version>
+ <asciidoctorj.version>1.5.3.2</asciidoctorj.version>
+ </properties>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-resources-plugin</artifactId>
+ <version>2.7</version>
+ <configuration>
+ <encoding>UTF-8</encoding>
+ <attributes>
+ <generateReports>false</generateReports>
+ </attributes>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctor-maven-plugin</artifactId>
+ <version>${asciidoctor.maven.plugin.version}</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj-pdf</artifactId>
+ <version>${asciidoctorj.pdf.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.asciidoctor</groupId>
+ <artifactId>asciidoctorj</artifactId>
+ <version>${asciidoctorj.version}</version>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <sourceDirectory>${basedir}/src</sourceDirectory>
+ </configuration>
+ <executions>
+ <execution>
+ <id>generate-html-doc</id>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <phase>site</phase>
+ <configuration>
+ <doctype>book</doctype>
+ <backend>html5</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <outputDirectory>${basedir}/target/site</outputDirectory>
+ <attributes>
+ <!-- Location of centralized stylesheet -->
+ <stylesheet>${basedir}/../css/trafodion-manuals.css</stylesheet>
+ <projectVersion>1.3.0</projectVersion>
+ <buildDate>${maven.build.timestamp}</buildDate>
+ </attributes>
+ </configuration>
+ </execution>
+ <execution>
+ <id>generate-pdf-doc</id>
+ <phase>site</phase>
+ <goals>
+ <goal>process-asciidoc</goal>
+ </goals>
+ <configuration>
+ <doctype>book</doctype>
+ <backend>pdf</backend>
+ <sourceHighlighter>coderay</sourceHighlighter>
+ <outputDirectory>${basedir}/target</outputDirectory>
+ <attributes>
+ <icons>font</icons>
+ <pagenums/>
+ <toc/>
+ <idprefix/>
+ <idseparator>-</idseparator>
+ </attributes>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <!-- Populate the web-site docs directory -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <version>1.8</version>
+ <inherited>false</inherited>
+ <executions>
+ <execution>
+ <id>populate-release-directories</id>
+ <phase>post-site</phase>
+ <configuration>
+ <target name="Populate Release Directories">
+ <!-- The website uses the following organization for the docs/target/docs directory:
+ - To ensure a known location, the base directory contains the LATEST version of the web book and the PDF files.
+ - The know location is docs/target/docs/<document>
+ - target/docs/<version>/<document> contains version-specific renderings of the documents.
+ - target/docs/<version>/<document> contains the PDF version and the web book. The web book is named index.html
+ -->
+ <!-- Copy the PDF file to its target directories -->
+ <copy file="${basedir}/target/index.pdf" tofile="${basedir}/../target/docs/odb/Trafodion_odb_User_Guide.pdf" />
+ <copy file="${basedir}/target/index.pdf" tofile="${basedir}/../target/docs/${project.version}/odb/Trafodion_odb_User_Guide.pdf" />
+ <!-- Copy the Web Book files to their target directories -->
+ <copy todir="${basedir}/../target/docs/odb">
+ <fileset dir="${basedir}/target/site">
+ <include name="**/*.*"/> <!--All sub-directories, too-->
+ </fileset>
+ </copy>
+ <copy todir="${basedir}/../target/docs/${project.version}/odb">
+ <fileset dir="${basedir}/target/site">
+ <include name="**/*.*"/> <!--All sub-directories, too-->
+ </fileset>
+ </copy>
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+
+ <!-- Included because this is required. No reports are generated. -->
+ <reporting>
+ <excludeDefaults>true</excludeDefaults>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.8</version>
+ <reportSets>
+ <reportSet>
+ <reports>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ </plugins>
+ </reporting>
+
+ <distributionManagement>
+ <site>
+ <id>trafodion.incubator.apache.org</id>
+ <name>Trafodion Website at incubator.apache.org</name>
+ <!-- On why this is the tmp dir and not trafodion.incubator.apache.org, see
+ https://issues.apache.org/jira/browse/HBASE-7593?focusedCommentId=13555866&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13555866
+ -->
+ <url>file:///tmp</url>
+ </site>
+ </distributionManagement>
+</project>
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/a_warnings.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/a_warnings.adoc b/docs/odb_user/src/asciidoc/_chapters/a_warnings.adoc
new file mode 100644
index 0000000..8bdcbef
--- /dev/null
+++ b/docs/odb_user/src/asciidoc/_chapters/a_warnings.adoc
@@ -0,0 +1,104 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+== A. Troubleshooting
+1. odb uses Condition Variables to synchronize threads during copy and parallel load operations.
+2. Most of the memory allocation operations are dynamic. For example, you can execute an SQL
+command as long as you want. However, you can _hard code_ limits as follows:
++
+[source,cplusplus]
+--
+#define MAX_VNLEN 32 /* Max variable name length */
+#define MAXCOL_LEN 128 /* Max column name length */
+#define MAXOBJ_LEN 128 /* Max catalog/schema/table name length */
+#define MAX_CLV 64 /* Max command line variables (-var) */
+--
+
+3. Some Linux/UNIX systems (notably the Linux Loader) have huge default stack size. Due to this
+extremely large value, you can have errors like this when starting tens/hundreds of threads:
++
+====
+```
+Error starting cmd thread #: cannot allocate memory
+```
+====
++
+If you get this error, then check your default stack size:
++
+====
+$ *ulimit -a*
+```
+core file size (blocks, -c) 0
+data seg size (kbytes, -d) unlimited
+max nice (-e) 0
+file size (blocks, -f) unlimited
+pending signals (-i) 137215
+max locked memory (kbytes, -l) 32
+max memory size (kbytes, -m) unlimited
+open files (-n) 65536
+pipe size (512 bytes, -p) 8
+POSIX message queues (bytes, -q) 819200
+max rt priority (-r) 0
+stack size (kbytes, -s) 204800
+cpu time (seconds, -t) unlimited
+max user processes (-u) 2047
+virtual memory (kbytes, -v) unlimited
+file locks (-x) unlimited
+```
+====
++
+In the example above, the `stack size` value is the problem. Reset it to a reasonable value. (The value will be reset to the initial value when you start a new session).
++
+*Example*
++
+====
+`$` *ulimit -s 4096*
+====
+
+4. If you get errors such as:
++
+====
+`C:\Users\felici>` *odb64luo -u xx -p yy -d oraxe -l src=region.tbl.gz:tgt=region:fs=^|:truncate*
+```
+odb [2012-10-11 13:27:22]: starting ODBC connection(s)... 0
+[0] odb(5020) - [Oracle][ODBC]Optional feature not implemented. (State: HYC00 Native Err: 0)
+```
+====
++
+Try adding `-nocatnull` to your command line. When the backend database doesn’t use catalogs,
+then you should use an *empty string* as catalog name.
++
+NOTE: Some flawed ODBC Drivers unfortunately want NULL here -- instead of *empty strings* as it should be.
+
+5. You can have errors loading `TIME(N)` fields with` N>0` under Trafodion because the
+ODBC Driver does not manage the field display size when `N>0`.
+6. If you have problems starting odb on Unix/Linux check:
++
+* The shared library dependencies with `ldd <odb_executable_name>`.
+* The shared lib path defined in the following environment variables used by the shared library loader:
+** *Linux*: `LD_LIBRARY_PATH`
+** *IBM IAX*: `LIBPATH` (not currently supported)
+** *HP/UX*: `SHLIB_PATH` (not currently supported)
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/about.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/about.adoc b/docs/odb_user/src/asciidoc/_chapters/about.adoc
new file mode 100644
index 0000000..0cfce6f
--- /dev/null
+++ b/docs/odb_user/src/asciidoc/_chapters/about.adoc
@@ -0,0 +1,119 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+= About This Document
+This guide describes how to use odb, a multi-threaded, ODBC-based command-line tool, to perform various operations on a Trafodion
+database.
+
+NOTE: In Trafodion Release 1.3, only loading, extracting, and copying data operations are production ready, meaning that that have
+been fully tested and are ready to be used in a production environment. +
+ +
+Other features are designated as _Technology Preview_ meaning that they have not been fully tested and are not ready for production use.
+
+== Intended Audience
+This guide is intended for database administrators and other users who want to run scripts that operate on a Trafodion database, primarily for
+parallel data loading.
+
+== New and Changed Information
+This manual guide is new.
+
+== Notation Conventions
+This list summarizes the notation conventions for syntax presentation in this manual.
+
+[cols="15%,30%,25%,30%",options="header"]
+|===
+| Notation | Usage | Example | Notes
+| UPPERCASE LETTERS | Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. | SELECT |
+| _Italic Letters_ | Italic letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required. | _file-name_ |
+| `Computer Type` | Computer type letters within text indicate case-sensitive keywords and reserved words. Type these items exactly as shown. Items not enclosed in
+brackets are required. | `myfile.sh` |
+| *Bold Text* | Bold text in an example indicates user input typed at the terminal. | `ENTER RUN CODE:` +
+ ?*123* +
+ `CODE RECEIVED: 123.00` | The user must press the Return key after typing the input.
+| [ ] Brackets | Brackets enclose optional syntax items. |
+DATETIME [_start-field_ TO] +
+_end-field_
+| A group of items enclosed in brackets is a list from which you can choose one item or none.
+
+The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines.
+
+For example:
+
+`DROP SCHEMA _schema_ [CASCADE]` +
+`DROP SCHEMA _schema_ [ CASCADE \| RESTRICT ]`
+| { } Braces | Braces enclose required syntax items. | `FROM { _grantee_[, _grantee_]...}` | A group of items enclosed in braces is a list from which you are required to choose one item.
+
+The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines.
+
+For example:
+
+`INTERVAL { _start-field_ TO _end-field_ }` +
+`{ _single-field_ }` +
+`INTERVAL { _start-field_ TO _end-field_ \| _single-field_ }`
+--
+| \| Vertical Line | A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. | `{_expression_ \| NULL}` |
+| … Ellipsis | An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. |
+`ATTRIBUTE[S] _attribute_ [, _attribute_]...` +
+`{, _sql-expression_}...`
+| An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times.
+
+For example:
+
+`_expression-n_…`
+| Punctuation | Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. |
+DAY (_datetime-expression_)` +
+`@_script-file_` | Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown.
+
+For example:
+
+`"{" _module-name_ [, _module-name_]... "}"`
+| Item Spacing | Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. |
+`DAY (_datetime-expression_) DAY(_datetime-expression_)` | If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items:
+
+`_myfile_.sh`
+
+| Line Spacing | If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line.
+
+This spacing distinguishes items in a continuation line from items in a vertical list of selections. |
+`_match-value_ [NOT] LIKE _pattern_`
+ [ESCAPE _esc-char-expression_] |
+|===
+
+== Publishing History
+[cols="2*",options="header"]
+|===
+| Product Version | Publication Date
+| Trafodion Release 1.3.0 | To be announced.
+|===
+
+<<<
+== Comments Encouraged
+The Trafodion community encourages your comments concerning this document. We are committed to providing documentation that meets your
+needs. Send any errors found, suggestions for improvement, or compliments to:
+
+issues@trafodion.incubator.apache.org
+
+Include the document title and any comment, error found, or suggestion for improvement you have concerning this document.
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/b_develop.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/b_develop.adoc b/docs/odb_user/src/asciidoc/_chapters/b_develop.adoc
new file mode 100644
index 0000000..c427652
--- /dev/null
+++ b/docs/odb_user/src/asciidoc/_chapters/b_develop.adoc
@@ -0,0 +1,50 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+<<<
+== B. Develop and Test odb
+=== Develop
+
+odb is coded in "ANSI C" (K&R programming style) and is compiled in a 64-bit version on the Linux platform, linked
+to the unixODBC driver manager. Other platforms, compilers, and ODBC libraries have not yet been tested.
+
+[cols="15%,15%,40%,20%",options="header"]
+|===
+| Platform | Compiler | ODBC Libraries | Note
+| **Linux** | gcc | unixODBC (supported), iODBC (not currently supported), Data Direct (not currently supported), Teradata (not currently supported) | 64 bit (32 bit is not currently supported)
+| **MS-Windows** +
+(not tested) | Visual Studio (not tested) | MS-Windows (not tested) | 64 bit
+|===
+
+C compilers are set with “all warnings” enabled and odb has to compile, on each platform, with no errors (of course) AND no warnings. Tools used
+to code odb:
+
+* **vim** (http://www.vim.org) as editor (or Visual Studio embedded editor)
+* **splint** (http://www.splint.org) to statically check the source code
+
+=== Test
+
+The info, load, extract, and copy operations of odb have been fully tested. In addition, odb had been tested using a set of
+137 standard tests to check functionalities and identify memory/thread issues.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/compare_tables.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/compare_tables.adoc b/docs/odb_user/src/asciidoc/_chapters/compare_tables.adoc
new file mode 100644
index 0000000..b1fe5c2
--- /dev/null
+++ b/docs/odb_user/src/asciidoc/_chapters/compare_tables.adoc
@@ -0,0 +1,202 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+= Comparing Tables (Technology Preview)
+
+You can use odb to compare two tables *with the same structure* on different databases.
+odb does the following to compare two tables:
+
+1. Extracts source/target tables ordered by Primary Key or any other set of columns.
+2. Compare source/target ODBC buffers without _unpacking_ them into columns/rows.
+
+Each _comparison stream_ is made up of three threads:
+
+* One thred reading from the source table.
+* One thread reading from the target table.
+* One thread comparing the source/target buffers.
+
+These three threads work in parallel: the _compare_ thread checks `buffer N` while the other two threads
+extract the net block of data from the source/target database in parallel.
+
+You can have multiple _triplets_ working in parallel on different section of the table using the `splitby` operator.
+
+*Example*
+
+====
+`$` *odb64luo -u mailto:maurizio.felici@hp.com[MFELICI:maurizio.felici@hp.com] \* +
+*-d MFELICI:VMFELICI \* +
+*-p xx:yy –diff src=trafodion.maurizio.lineitem:tgt=mftest.lineitem:* \* +
+*key=l_orderkey,l_linenumber*:output=lineitem.diff:* +
+*rows=m2:print=IDC:*splitby=l_orderkey*:parallel=8*
+====
+
+The command above compares two tables using eight streams (`parallel=8`) made of three threads each.
+
+The comparison threads use double buffering and advanced memory-comparison techniques. odb can provide the following information in
+output as a CSV file:
+
+* Missing rows on target (`D` – deleted – rows) based on the *key* columns.
+* New rows on target (`I` – inserted – rows) based on the *key* columns.
+* Changed rows (same *key* columns but with different values in other fields).
++
+For these rows odb can print the original source version (`C` rows) and/or the modified target version (`U` rows).
+
+<<<
+*Example*
+
+odb output when comparing two tables:
+
+====
+`$` *cat lineitem.diff*
+```
+DTYPE,L_ORDERKEY,L_LINENUMBER,L_SUPPKEY,L_PARTKEY,L_QUANTITY,L_EXTENDEDPRICE,L_DISCOUNT,L_TAX,L_RETURNFLAG,
+L_LINESTATUS,L_SHIPDATE,L_COMMITDATE,L_RECEIPTDATE,L_SHIPINSTRUCT,L_SHIPMODE,L_COMMENT
+D,4532896,1,5974,100953,42.00,82065.90,0.03,0.00,R,F,1994-12-15,1995-01-17,1995-01-07,COLLECT COD,TRUCK,leep across the ca
+D,4532896,2,2327,102326,48.00,63759.36,0.07,0.05,A,F,1995-02-18,1994-12-10,1995-03-12,TAKE BACK RETURN,RAIL,usly regular platelets. careful
+D,4532896,3,612,193054,12.00,13764.60,0.05,0.02,R,F,1994-11-17,1994-11-23,1994-12-06,COLLECT COD,SHIP,s haggle quickly. ideas after the
+D,4532896,4,9867,47362,36.00,47136.96,0.10,0.06,A,F,1995-01-05,1994-11-29,1995-01-06,COLLECT COD,RAIL,s haggle carefully bo
+D,4532896,5,9576,2075,19.00,18564.33,0.00,0.05,R,F,1994-11-26,1995-01-17,1994-12-03,COLLECT COD,TRUCK,en sauternes integrate blithely alon
+D,4532896,6,1016,68509,9.00,13297.50,0.07,0.00,R,F,1995-02-16,1995-01-05,1995-02-24,TAKE BACK RETURN,RAIL,ily above the blithel
+C,1652227,3,2298,87281,28.00,35511.84,0.06,0.05,R,F,1993-05-04,1993-03-12,1993-05-12,TAKE BACK RETURN,MAIL,lly final acco
+U,1652227,3,2298,87281,99.99,35511.84,0.06,0.05,R,F,1993-05-04,1993-03-12,1993-05-12,TAKE BACK RETURN,MAIL,lly final acco
+D,3456226,1,8161,148160,22.00,26579.52,0.06,0.02,A,F,1994-06-26,1994-06-08,1994-07-10,DELIVER IN PERSON,FOB,uriously. furio
+D,3456226,2,6293,108762,20.00,35415.20,0.10,0.05,R,F,1994-05-07,1994-06-03,1994-05-15,NONE,RAIL,ously bold requests along the b
+D,3456226,3,4542,159511,33.00,51826.83,0.05,0.03,A,F,1994-07-04,1994-05-15,1994-07-26,NONE,FOB,wake carefully al
+D,3456226,4,154,95135,33.00,37294.29,0.04,0.08,A,F,1994-05-27,1994-05-10,1994-06-14,DELIVER IN PERSON,AIR,ests. unusual dependencies wake fluffily
+D,3456226,5,9027,126514,31.00,47755.81,0.08,0.01,R,F,1994-06-13,1994-06-18,1994-07-10,TAKE BACK RETURN,FOB,according to the arefully regular instruct
+D,3456226,6,8477,110943,14.00,27355.16,0.03,0.01,R,F,1994-07-03,1994-05-28,1994-07-13,TAKE BACK RETURN,FOB,onic accounts. ironic,pend
+D,3456226,7,1773,4272,34.00,39993.18,0.08,0.00,A,F,1994-05-01,1994-05-29,1994-05-15,TAKE BACK RETURN,MAIL,ounts are finally ca
+D,3456227,7,3722,101211,22.00,26668.62,0.02,0.01,N,O,1997-12-16,1998-02-05,1997-12-19,NONE,TRUCK,uriously even platelets are fu
+I,3456227,8,3722,101211,22.00,26668.62,0.02,0.01,N,O,1997-12-16,1998-02-05,1997-12-19,NONE,TRUCK,uriously even platelets are fu
+I,9999999,1,8161,148160,22.00,26579.52,0.06,0.02,A,F,1994-06-26,1994-06-08,1994-07-10,DELIVER IN PERSON,FOB,uriously. furio
+I,9999999,2,6293,108762,20.00,35415.20,0.10,0.05,R,F,1994-05-07,1994-06-03,1994-05-15,NONE,RAIL,ously bold requests along the b
+I,9999999,3,4542,159511,33.00,51826.83,0.05,0.03,A,F,1994-07-04,1994-05-15,1994-07-26,NONE,FOB,wakecarefully al
+I,9999999,4,154,95135,33.00,37294.29,0.04,0.08,A,F,1994-05-27,1994-05-10,1994-06-14,DELIVER IN PERSON,AIR,ests. unusual dependencies wake fluffily
+I,9999999,5,9027,126514,31.00,47755.81,0.08,0.01,R,F,1994-06-13,1994-06-18,1994-07-10,TAKE BACK RETURN,FOB,according to the carefully regular instruct
+I,9999999,6,8477,110943,14.00,27355.16,0.03,0.01,R,F,1994-07-03,1994-05-28,1994-07-13,TAKE BACK RETURN,FOB,onic accounts. ironic, pend
+I,9999999,7,1773,4272,34.00,39993.18,0.08,0.00,A,F,1994-05-01,1994-05-29,1994-05-15,TAKE BACK RETURN,MAIL,ounts are finally ca
+```
+====
+
+As you can see the first column defines the type of difference.
+
+== Diff Operators
+
+====
+```
+-diff
+src={table|-file}:tgt=table:[key=columns][:output=[+]file][:pwhere=where_cond]
+[:pwhere=where_cond][:nomark][:rows=#rowset][:odad][:fs=fieldsep][:time]
+[:rs=recsep][:quick][:splitby=column][:parallel=number][:max=#max_rec]
+[:print=[I][D][C]][:ns=nullstring][:es=emptystring][:fwc][:uncommitted]
+[:pre={@sqlfile}|{[sqlcmd]}][:post={@sqlfile}|{[sqlcmd]}][tpar=#tables]
+```
+====
+
+Detailed Descriptions of the Copy Operators:
+
+[cols="30%,70%",options="header",]
+|===
+| Diff Operator | Meaning
+| `src=<CAT.SCH.TAB>\|-file` | Definse the source table(s). You can use: +
+ +
+- A single table (for example: TRAFODION.MFTEST.LINEITEM) +
+- A file containing a list of tables to compare (`-` should precede the filename)
+| `tgt=<CAT.SCH.TAB>` | Target table.
+| `key=column[,column,...]` | Define show to order records extracted from both source and target table.
+*If you do not specify any key column, then odb uses the Primary Key.*
+| `output=[+]file` | Output file where the differences are reported. You can use stdout to print odb
+output on the standard output. A `+` sign in front of the file-name tells odb to *append* to an existing file. +
+ +
+Default value: `stdout`
+| `fs=<char>\|<code>` | Field separator of the output file. You can define the field separator as follows: +
+ +
+- Normal character (for example `fs=,`) +
+- ASCII decimal (for example `fs=44` -- 44 means comma) +
+- ASCII octal value (for example `fs=054` -– 054 means comma) +
+- ASCII hex value (for example fs=`x2C` -– x2C means comma) +
+ +
+The default field separator is `,` (comma).
+| `rs=<char>\|<code>` | Record separator used in the output file. You can define the
+record separator the same way as the field separator. +
+ +
+The default record separator is `\n` (new line).
+| `max=num` | The max number of records to compare. Default is to compare all records.
+| `rows=<num>\|k<num>\|m<num>` | Definess the size of the I/O buffer for each extraction thread. You
+can define the size of this buffer in two different ways: +
+ +
+- number of rows (for example: `rows=100` means 100 rows as IO buffer) +
+- buffer size in kB or MB (for example: `rows=k512` (512 kB buffer) or `rows=m20` (20MB buffer))
+| `ns=<nullstring>` | How odb represents NULL values in the output file. Default is the empty string (two field separators one after the other)
+| `es=<emptystring>` | How odb represents VARCHAR empty strings (NOT NULL with zero length) values in the output file.
+Default is the empty string (two field separators one after the other)
+| `nomark` | Don’t print the number of records extracted so far by each thread.
+| `soe` | Stop On Error. odb stops as soon as it encounters an error.
+| `parallel=num` | odb uses as many _threads triplets_ (extract from source, extract from target, compare) as the parallel argument. +
+ +
+Each thread will take care of a specific range of the source table data defined through the *splitby* option.
+| `uncommitted` | odb adds `FOR READ UNCOMMITTED ACCESS` to the select(s) command(s).
+| `splitby=<column>` | Lets you to use parallel extract from any database. *`<column>` has to be a SINGLE, numeric column (or expression)*. odb
+calculates min()/max() value for `<column>` and assigns it to each <parallel> thread the extraction of the rows in its _bucket_. +
+ +
+*Example* +
+ +
+`...:splitby=emp_id:parallel=4...` +
+ +
+with `min(emp_id)=1` and `max(emp_id)=1000`, the four threads will extract the following rows: +
+ +
+`thread #0 emp_id >=1 and emp_id < 251` +
+`thread #1 emp_id >=251 and emp_id < 501` +
+`thread #2 emp_id >=501 and emp_id < 751` +
+`thread #3 emp_id >=751 and emp_id < 1001 (odb uses max(emp_id) + 1)` +
+ +
+If the values are not equally distributed, then data extraction is deskewed.
+| `print=[I][C][D]` | Specifie which rows are printed in the output file: +
+ +
+`I` prints the new rows on target. (Based on *key*.) +
+`D` prints the missing rows on target. (Based on *key*.) +
+`C` prints the source rows with the same *key* columns but differences in other fields. +
+ +
+The default value for print is `IDC`.
+| `pre={@sqlfile}\|{[sqlcmd]}` | odb runs a *single instance* of either a `sqlfile` script or `sqlcmd` SQL
+command (enclosed between square brackets) on the *target system* immediately before reading the target table.
+| `post={@sqlfile}\|{[sqlcmd]}` | odb runs a *single instance* of either a `sqlfile` script or `sqlcmd` SQL
+command (enclosed between square brackets) on the *target system* immediately after the target table has been compared.
+| `tpar=num` | The number of tables to compare in parallel when you have a list of tables in input.
+| `loaders=num` | odb uses `num` load threads for each extract thread. Default is 2 loaders per extractor.
+| `pwhere=<where condition>` | This option is used in conjunction with parallel to _diff_ only records
+satisfying the where condition. +
+ +
+For example: you want to compare rows with `TRANS_TS > 1999-12-12 09:00:00` from the source table
+TRAFODION.MAURO.MFORDERS using eight parallel streams to a target table having the same name as the source table: +
+ +
+`src=trafodion.mauro.mforders:tgt=trafodion.dest_schema.%t:parallel=8:pwhere=[TRANS_TS > TIMESTAMP ‘1999-12- 12 09:00:00’]...` +
+ +
+You can enclose the where condition between square brackets to avoid a misinterpretation of the characters in the where condition.
+| `quick` | Limits the comparison to the columns in the key option (PK by default). This is a fast way to check for new/missing records but
+it will not find rows with differences in _non-key_ columns.
+| `time` | odb prints a _timeline_. (Milliseconds from starts)
+|===
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/concepts.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/concepts.adoc b/docs/odb_user/src/asciidoc/_chapters/concepts.adoc
new file mode 100644
index 0000000..c709658
--- /dev/null
+++ b/docs/odb_user/src/asciidoc/_chapters/concepts.adoc
@@ -0,0 +1,960 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied. See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+= Basic Concepts
+== Get Help
+The following command shows the odb help:
+
+====
+`~/Devel/odb $` *./odb64luo -h*
+```
+odb version 1.3.0
+Build: linux, amd64, gcc generic m64, uodbc, mreadline, dynamic gzip, dynamic libhdfs, dynamic libxml2 [Mar 30 2015 00:29:25]
+ -h: print this help
+ -version: print odb version and exit
+ -lsdrv: list available drivers @ Driver Manager level
+ -lsdsn: list available Data Sources
+Connection related options. You can connect using either:
+ -u User: (default $ODB_USER variable)
+ -p Password: (default $ODB_PWD variable)
+ -d Data_Source_Name: (default $ODB_DSN variable)
+ -ca Connection_Attributes (normally used instead of -d DSN)
+ -U sets SQL_TXN_READ_UNCOMMITTED isolation level
+ -ndsn [+]<number>: adds 1 to <number> to DSN
+ -nps <nbytes>[:<nbytes>]: specify source[:target] network packet size
+SQL interpreter options:
+ -I [$ODB_INI SECTION]: interactive mode shell
+ -noconnect: do not connect on startup General options:
+ -q [cmd|res|all|off]: do not print commands/results/both
+ -i [TYPE[MULT,WIDE_MULT]:CATALOG.SCHEMA[.TABLE]]: lists following object types:
+ (t)ables, (v)iews, s(y)nonyns, (s)chemas, (c)atalogs, syst(e)m tables
+ (l)ocal temp, (g)lobal temp, (m)at views, (M)mat view groups, (a)lias
+ (A)ll object types, (T)table desc, (D)table DDL, (U) table DDL with multipliers
+ -r #rowset: rowset to be used insert/selects (default 100)
+ -soe: Stop On Error (script execution/loading task)
+ -N : Null run. Doesn't SQLExecute statements
+ -v : be verbose
+ -vv : Print execution table
+ -noschema : do not use schemas: CAT.OBJ instead of CAT.SCH.OBJ
+ -nocatalog : do not use catalogs: SCH.OBJ instead of CAT.SCH.OBJ
+ -nocatnull : like -nocatalog but uses NULL instead of empty CAT strings
+ -ucs2toutf8 : set UCS-2 to UTF-8 conversion in odb
+ -var var_name var_value: set user defined variables
+ -ksep char/code: Thousands Separator Character (default ',')
+ -dsep char/code: Decimal Separator Character (default '.')
+SQL execution options [connection required]:
+ -x [#inst:]'command': runs #inst (default 1) command instances
+ -f [#inst:]'script': runs #inst (default 1) script instances
+ -P script_path_regexp: runs in parallel scripts_path_regexp if script_path_regexp ends with / all files in that dir
+ -S script_path_regexp: runs serially scripts_path_regexp if script_path_regexp ends with / all files in that dir
+ -L #loops: runs everything #loops times
+ -T max_threads: max number of execution threads
+ -dlb: use Dynamic Load Balancing
+ -timeout #seconds: stops everything after #seconds (no Win32)
+ -delay #ms: delay (ms) before starting next thread
+ -ldelay #ms: delay (ms) before starting next loop in a thread
+ -ttime #ms[:ms]: delay (ms) before starting next command in a thread random delay if a [min:max] range is specified
+ -F #records: max rows to fetch
+ -c : output in csv format
+ -b : print start time in the headers when CSV output
+ -pcn: Print Column Names
+ -plm: Print Line Mode
+ -fs char/code: Field Sep <char> ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ -rs char/code: Rec Sep <char> ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ -sq char/code: String Qualifier (default none)
+ -ec char/code: Escape Character (default '\')
+ -ns nullstring: print nullstring when a field is NULL
+ -trim: Trim leading/trailing white spaces from txt cols
+ -drs: describe result set (#cols, data types...) for each Q)
+ -hint: do not remove C style comments (treat them as hints)
+ -casesens: set case sensitive DB
+ -Z : shuffle the execution table randomizing Qs start order
+Data loading options [connection required]:
+ -l src=[-]file:tgt=table[:map=mapfile][:fs=fieldsep][:rs=recsep][:soe]
+ [:skip=linestoskip][:ns=nullstring][:ec=eschar][:sq=stringqualifier]
+ [:pc=padchar][:em=embedchar][:errmax=#max_err][:commit=auto|end|#rows|x#rs]
+ [:rows=#rowset][:norb][:full][:max=#max_rec][:truncate][:show][:bpc=#][:bpwc=#]
+ [:nomark][:parallel=number][:iobuff=#size][:buffsz=#size]][:fieldtrunc={0-4}]
+ [:pre={@sqlfile}|{[sqlcmd]}][:post={@sqlfile}|{[sqlcmd]}][:ifempty]
+ [:direct][:bad=[+]badfile][:tpar=#tables][:maxlen=#bytes][:time][:loadcmd=IN|UP|UL]
+ [:xmltag=[+]element][:xmlord][:xmldump]
+ Defaults/notes:
+ * src file: local file or {hdfs,mapr}[@host,port[,huser]].<HDFS_PATH>
+ * fs: default ','. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * rs: default '\n'. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * ec: default '\'. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * pc: no default. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * direct: only for Vertica databases
+ * bpc: default 1,bpwc: default 4
+ * loadcmd: default IN. only for Trafodion databases
+Data extraction options [connection required]:
+ -e {src={table|-file}|sql=<custom sql>}:tgt=[+]file[:pwhere=where_cond]
+ [:fs=fieldsep][:rs=recsep][:sq=stringqualifier][:ec=escape_char][:soe]
+ [:ns=nullstring][es=emptystring][:rows=#rowset][:nomark][:binary][:bpc=#][:bpwc=#]
+ [:max=#max_rec][:[r]trim[+]][:cast][:multi][parallel=number][:gzip[=lev]]
+ [:splitby=column][:uncommitted][:iobuff=#size][hblock=#size][:ucs2toutf8]
+ [:pre={@sqlfile}|{[sqlcmd]}[:mpre={@sqlfile}|{[sqlcmd]}[:post={@sqlfile}|{[sqlcmd]}]
+ [tpar=#tables][:time][:cols=[-]columns]][:maxlen=#bytes][:xml]
+ Defaults/notes:
+ * tgt file: local file or {hdfs,mapr}.[@host,port[,huser]].<HDFS_PATH>
+ * fs: default ','. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * rs: default '\n'. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * ec: default '\'. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * sq: no default. Also <ASCII_dec> 0<ASCII_OCT> X<ASCII_HEX>
+ * gzip compressione level between 0 and 9
+ * bpc: default 1,bpwc: default 4
+Data copy options [connection required]:
+ -cp src={table|-file:tgt=schema[.table][pwhere=where_cond][:soe][:roe=#][:roedel=#ms]
+ [:truncate][:rows=#rowset][:nomark][:max=#max_rec][:bpc=#][:bpwc=#][:[r]trim[+]]
+ [:parallel=number][errmax=#max_err][:commit=auto|end|#rows|x#rs][:time] ][:cast]
+ [:direct][:uncommitted][:norb][:splitby=column][:pre={@sqlfile}|{[sqlcmd]}]
+ [:post={@sqlfile}|{[sqlcmd]}][:mpre={@sqlfile}|{[sqlcmd]}][:ifempty]
+ [:loaders=#loaders][:tpar=#tables][:cols=[-]columns][:errdmp=file] ][:loadcmd=IN|UP|UL]
+ [sql={[sqlcmd]|@sqlfile|-file}[:bind=auto|char|cdef][:seq=field#[,start]]
+ [tmpre={@sqlfile}|{[sqlcmd]}][:ucs2toutf8=[skip,force,cpucs2,qmark]]
+ Defaults/notes:
+ * loaders: default 2 load threads for each 'extractor'
+ * direct: only work if target database is Vertica
+ * ucs2toutf8: default is 'skip'
+ * roe: default 3 if no arguments
+ * bpc: default 1,bpwc: default 4
+ * loadcmd: default IN. only for Trafodion databases
+Data pipe options [connection required]:
+ -pipe sql={[sqlcmd]|@sqlscript|-file}:tgtsql={@sqlfile|[sqlcmd]}[:soe]
+ [:rows=#rowset][:nomark][:max=#max_rec][:bpc=#][:bpwc=#][:errdmp=file]
+ [:parallel=number][errmax=#max_err][:commit=auto|end|#rows|x#rs][:time]
+ [:pre={@sqlfile}|{[sqlcmd]}][:post={@sqlfile}|{[sqlcmd]}]
+ [:mpre={@sqlfile}|{[sqlcmd]}][:tmpre={@sqlfile}|{[sqlcmd]}]
+ [:loaders=#loaders][:tpar=#tables][:bind=auto|char|cdef]
+ Defaults/notes:
+ * loaders: default 1 load threads for each extraction thread
+ * bpc: default 1,bpwc: default 4
+```
+====
+<<<
+====
+```
+Table diff options [connection required]:
+ -diff src={table|-file}:tgt=table:[key=columns][:output=[+]file][:pwhere=where_cond]
+ [:pwhere=where_cond][:nomark][:rows=#rowset][:odad][:fs=fieldsep][:time][trim[+]]
+ [:rs=recsep][:quick][:splitby=column][:parallel=number][:max=#max_rec]
+ [:print=[I][D][C]][:ns=nullstring][:es=emptystring][:bpc=#][:bpwc=#][:uncommitted]
+ [:pre={@sqlfile}|{[sqlcmd]}][:post={@sqlfile}|{[sqlcmd]}][tpar=#tables]
+ Defaults/notes:
+ * bpc: default 1,bpwc: default 4
+ * print: default is Inserted Deleted Changed
+```
+====
+
+<<<
+== Connect to Database
+odb uses standard ODBC APIs to connect to a database.
+
+Normally you have to provide the following information: user, password and ODBC data source.
+
+*Example*
+
+====
+`$` *./odb64luo –u user –p password –d dsn ...*
+====
+
+You can provide Driver-specific connection attributes using th `-ca` command line option.
+
+NOTE: Command-line passwords are protected against `ps -ef` sniffing attacks under *nix. You can safely pass your
+password via `–p`. An alternative approach is to use environment variables or the odb password prompt (see below).
+
+odb will use the following environment variables (if defined):
+
+[cols="15%,50%,30%",options="header"]
+|===
+| Variable | Meaning | Corresponding Command-Line Option
+| `ODB_USER` | User name to use for database connections | `-u <user>`
+| `ODB_PWD` | Password for database connections | `-p <passwd>`
+| `ODB_DSN` | DSN for database connection | `-d <dsn>`
+| `ODB_INI` | Init file for interactive shell |
+| `ODB_HIST` | history file name to save command history on exit |
+|===
+
+NOTE: Command-line options take precedence over environment variables.
+
+<<<
+== List ODBC Drivers and Data Sources
+You can list available drivers with `-lsdrv`:
+
+====
+`~/Devel/odb $` *./odb64luo -lsdrv* +
+`Trafodion - Description=Trafodion ODBC Stand Alone Driver` +
+`...`
+====
+
+You can list locally configured data sources with `-lsdsn`:
+
+====
+`~/Devel/odb $` *./odb64luo -lsdsn traf - Trafodion* +
+`VMFELICI – Vertica` +
+`...`
+====
+
+<<<
+== Obtain Database Information
+The `-i` option allows you to get information about the database you’re connecting to as well as the ODBC driver.
+It’s a simple way to check your credentials and database connection.
+
+*Example*
+
+====
+`~/mauro/odb $` *./odb64luo -u xxx -p xxx -d traf -i*
+```
+odb [2015-04-20 21:20:47]: starting ODBC connection(s)... 0
+ [odb version 1.3.0]
+ Build: linux, amd64, gcc generic m64, uodbc, mreadline, dynamic gzip, dynamic libhdfs, dynamic libxml2 [Apr 8 2015 16:47:49]
+
+ DBMS product name (SQL_DBMS_NAME) : Trafodion
+ DBMS product version (SQL_DBMS_VER) : 01.03.0000
+ Database name (SQL_DATABASE_NAME) : TRAFODION
+ Server name (SQL_SERVER_NAME) : --name--
+ Data source name (SQL_DATA_SOURCE_NAME) : traf
+ Data source RO (SQL_DATA_SOURCE_READ_ONLY) : N
+ ODBC Driver name (SQL_DRIVER_NAME) : libhpodbc64.so
+ ODBC Driver version (SQL_DRIVER_VER) : 03.00.0000
+ ODBC Driver level (SQL_DRIVER_ODBC_VER) : 03.51
+ ODBC Driver Manager version (SQL_DM_VER) : 03.52.0002.0002
+ ODBC Driver Manager level (SQL_ODBC_VER) : 03.52
+ Connection Packet Size (SQL_ATTR_PACKET_SIZE): 0
+odb [2015-04-20 21:20:48]: exiting. Session Elapsed time 0.229 seconds (00:00:00.229)
+```
+====
+
+<<<
+== List Database Objects
+The previous section used the `-i` option without any argument.
+
+This option accepts arguments with the following syntax:
+
+`[TYPE:][CATALOG.SCHEMA][.OBJECT]`
+
+where type can be:
+
+[cols="40%,60%",options="header"]
+|===
+| Type | Meaning
+| `<missing>` | All database object types
+| `A:` | All database object types
+| `t:` | Tables
+| `v:` | Views
+| `a:` | Aliases
+| `y:` | Synonyms
+| `l:` | Local Temporary
+| `g:` | Global Temporary
+| `m:` | Materialized views
+| `M:` | Materialized view groups
+| `s:` | Schemas
+| `c:` | Catalogs
+| `T:` | Table descriptions
+| `D:` | Table DDL
+| `U[x,y]:` | Table DDL multiplying wide columns by Y and non-wide columns by X
+|===
+
+<<<
+[cols="40%,60%",options="header"]
+|===
+| Example | Action
+| `-i c:` | List all catalogs.
+| `-i s:` | List all schemas.
+| `-i TRAFODION.MFTEST` | List all objects in `TRAFODION.MFTEST` schema.
+| `-i t:TRAFODION.MFTEST` | List all tables in `TRAFODION.MFTEST`.
+| `-i t:TRAFODION.MFTEST.A%` | List all tables in `TRAFODION.MFTEST` schema staring with `A`.
+| `-i v:TRAFODION.MFTEST` | List all views in `TRAFODION.MFTEST`.
+| `-i v:TRAFODION.MFTEST.%_V` | List all views in `TRAFODION.MFTEST` ending with `_V`.
+| `-i T:TRAFODION.MFTEST.STG%` | Describe all tables starting with `STG` in `TRAFODION.MFTEST`.
+|===
+
+*Extended Examples*
+
+====
+`~/mauro/odb $` *./odb64luo -u MFELICI -p xxx -d MFELICI -i T:TRAFODION.MAURIZIO.T%*
+```
+odb [2011-12-07 14:43:51]: starting (1) ODBC connection(s)... 1
+Describing: TRAFODION.MAURIZIO.T1
++------+--------------+----+-------+-------+
+|COLUMN|TYPE |NULL|DEFAULT|INDEX |
++------+--------------+----+-------+-------+
+|ID |INTEGER SIGNED|YES | | |
+|NAME |CHAR(10) |YES | | |
+|LASTN |VARCHAR(20) |YES | | |
++------+--------------+----+-------+-------+
+Describing: TRAFODION.MAURIZIO.T11
++------+--------------+----+-------+-------+
+|COLUMN|TYPE |NULL|DEFAULT|INDEX |
++------+--------------+----+-------+-------+
+|ID |INTEGER SIGNED|NO | |T11 1 U|
+|NAME |CHAR(10) |YES | | |
++------+--------------+----+-------+-------+
+```
+====
+
+The `INDEX` column (when using type `T`) contains the following information:
+
+* `name` of the `INDEX` (in Trafodion indexes having the same name as the table are Primary Keys).
+* `ordinal number` to identify the order of that field in the index.
+* `(U)nique o (M)ultiple` values allowed.
+* `(+)` means that more than one index includes that field.
+
+== Perform Actions on Multiple Database Objects
+odb uses extended SQL syntax to execute actions on multiple objects: `&<type>:<path>` - where `<type>` is one
+of the object types listed in the previous section.
+
+*Example*
+
+[cols="60%,40%",options="header"]
+|===
+| Example | Action
+| `delete from &t:MF%` | Purge ALL tables (t:) staring with `M”`.
+| `drop view &v:mftest.%vw` | Drop ALL views (v:) ending with `_VW` in the schema `MFTEST`.
+| `UPDATE STATISTICS FOR TABLE &t:TRAFODION.MFTEST.%` | Update Stats for ALL tables in `TRAFODION.MFTEST`.
+|===
+
+You can use this _extended_ SQL syntax in the SQL Interpreter or generic SQL scripts.
+
+== Run Commands and Scripts
+The `–x` switch can be used to run generic SQL commands. You can also use `–f` to run SQL scripts:
+
+1. `-x "SQL command"` to run a specific SQL command.
+2. `-f <script>` to run a script file.
+
+*Example*
+
+====
+`~/Devel/odb $` *./odb64luo -x "select count(*) from customer"*
+```
+150000
+[0.0.0]--- 1 row(s) selected in 0.137s (prep 0.000s, exec 0.137s, 1st fetch 0.000s,
+fetch 0.000s)
+```
+====
+
+The meaning of `[0.0.0]` will be explained later.
+
+<<<
+
+====
+`~/Devel/odb $` *cat script.sql*
+[source,sql]
+----
+SELECT COUNT(*) FROM T1;
+-- This is a comment
+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 <= DATE '1998-12-01' - INTERVAL '90' DAY
+GROUP BY
+ L_RETURNFLAG, L_LINESTATUS
+ORDER BY
+ L_RETURNFLAG, L_LINESTATUS
+;
+----
+====
+
+<<<
+
+====
+`~/Devel/odb $` *./odb64luo -f script.sql*
+[source,sql]
+----
+[0.0.0]Executing: 'SELECT COUNT(*) FROM T1;'
+5
+[0.0.0]--- 1 row(s) selected in 0.015s (prep 0.000s, exec 0.015s, 1st fetch -0.000s,
+fetch -0.000s)
+[0.0.1]Executing: '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 <= DATE '1998-12-01'
+- INTERVAL '90' DAY GROUP BY L_RETURNFLAG, L_LINESTATUS ORDER BY L_RETURNFLAG,
+L_LINESTATUS;'
+A,F,37734107.00,56586554400.73,53758257134.8700,55909065222.827692,25.522006,
+38273.129735,0.049985,1478493
+...
+R,F,37719753.00,56568041380.90,53741292684.6040,55889619119.831932,25.505794,
+38250.854626,0.050009,1478870
+[0.0.1]--- 4 row(s) selected in 21.344s (prep 0.000s, exec 21.344s, 1st fetch 0.000s, fetch 0.000s)
+----
+====
+
+<<<
+You can use the `-q` switch to omit selected output components.
+
+*Example*
+
+`–q` cmd will not print the *_commands_* being executed:
+
+====
+`~/Devel/odb $` *./odb64luo -f script.sql –q cmd*
+```
+5
+[0.0.0]--- 1 row(s) selected in 0.015s (prep 0.000s, exec 0.015s, 1st fetch -0.000s,
+fetch -0.000s)
+
+A,F,37734107.00,56586554400.73,53758257134.8700,55909065222.827692,25.522006,
+38273.129735,0.049985,1478493
+...
+R,F,37719753.00,56568041380.90,53741292684.6040,55889619119.831932,25.505794,
+38250.854626,0.050009,1478870
+[0.0.1]--- 4 row(s) selected in 21.344s (prep 0.000s, exec 21.344s, 1st fetch 0.000s,
+fetch 0.000s)
+```
+====
+
+While `-q` res will nit print the *_results_*:
+
+====
+`~/Devel/odb $` *./odb64luo -f script.sql –q res*
+[source,sql]
+----
+[0.0.0]Executing: 'SELECT COUNT(*) FROM T1;'
+[0.0.0]--- 1 row(s) selected in 0.015s (prep 0.000s, exec 0.015s, 1st fetch -0.000s,
+fetch -0.000s)
+[0.0.1]Executing: '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 <= DATE '1998-12-01'
+- INTERVAL '90' DAY GROUP BY L_RETURNFLAG, L_LINESTATUS ORDER BY L_RETURNFLAG,
+L_LINESTATUS;'
+[0.0.1]--- 4 row(s) selected in 21.344s (prep 0.000s, exec 21.344s, 1st fetch 0.000s,
+fetch 0.000s)
+----
+====
+
+`-q all` (or just `-q`) will not print neither the *_commands_* nor the *_results_*:
+
+====
+`~/Devel/odb $` *./odb64luo -f script.sql -q all*
+```
+[0.0.0]--- 1 row(s) selected in 0.015s (prep 0.000s, exec 0.015s, 1st fetch -0.000s,
+fetch -0.000s)
+[0.0.1]--- 4 row(s) selected in 21.344s (prep 0.000s, exec 21.344s, 1st fetch 0.000s,
+fetch 0.000s)
+```
+====
+
+This is often used with odb as query driver.
+
+NOTE: Even when odb doesn’t print query results (`-q res`), the result set will be fetched and data is
+transferred from the database server to the client. In other words, `-q res` is somehow similar (but
+not exactly equivalent) to a `/dev/null` output redirection.
+
+A special file name you can use with `-f` is `-` (dash).
+
+It means: read the script to be executed from the _standard input_.
+
+*Example*
+
+The following command will _copy_ table definitions from one system to
+another recreating, on the target system, the same table structures as in the source system:
+
+====
+`$` *odb64luo –u u1 -p p1 -d SRC -i t:TRAFODION.CIV04 -x "SHOWDDL &1" \* +
+*| odb64luo –u u2 –p p2 -d TGT -f -*
+====
+
+<<<
+== Shell Script "here document" Syntax
+
+Commonly, there's a need to _embed_ SQL commands in shell scripts.
+
+Use the `-f -` (read commands from standard input) odb syntax.
+
+*Example*
+
+====
+```
+odb64luo -f - <<-EOF 2>&1 | tee -a $\{LOG}
+ drop table &t:TRAFODION.maurizio.ml%;
+ create table ml2
+ (
+ id integer
+ , fname char(10)
+ , bdate date
+ , lname char(10) default 'Felici'
+ , comment char(20)
+ , city char(10)
+ ) no partitions;
+EOF
+```
+====
+
+<<<
+== Parallelize Multiple Commands and Scripts
+
+odb uses threads to run multiple commands in parallel. Each command (`-x`) or
+script (`-f`) will be executed, independently from the others, using a different thread.
+
+.Running a command and script in parallel
+====
+`~/Devel/odb $` *./odb64luo -x "select count(*) from types" -f script1.sql*
+====
+
+Uses two _independent_ threads executed in parallel. The first thread will run `select count(*) from types` and the other `script1.sql`.
+
+You can also run *_multiple copies_* of the same command by adding `<num>:` before
+`-x` or `-f` arguments.
+
+The following command runs the instances of `select count(*) from types `, five instances
+of `script1.sql` and three instances of `script2.sql` in parallel using `3 + 5 + 3 = 11` threads in total:
+
+.Running eleven commands and scripts in parallel
+====
+`~/Devel/odb $` *./odb64luo -x 3:"select count(*) from types" -f 5:script1.sql \*
+*-f 3:script2.sql -q*
+```
+[1.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[0.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[2.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[4.0.0]--- 1 row(s) selected in 0.001s (prep 0.000s, exec 0.001s, fetch 0.000s/0.000s)
+[6.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[5.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[3.0.0]--- 1 row(s) selected in 0.001s (prep 0.000s, exec 0.001s, fetch 0.000s/0.000s)
+[8.0.0]--- 1 row(s) selected in 0.001s (prep 0.000s, exec 0.001s, fetch 0.000s/0.000s)
+[7.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[9.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[10.0.0]--- 1 row(s) selected in 0.001s prep 0.000s, exec 0.001s, fetch 0.000s/0.000s)
+```
+====
+
+The first number in `[*1*.0.0]` is the *_thread ID_*. Thread IDs are assigned by odb starting from zero.
+
+You can limit the maximum number of threads with `-T` option.
+
+*Example*
+
+The following command runs the same 11 commands/scripts limiting the number of threads (*and ODBC connections*) to 4:
+
+====
+`~/Devel/odb $` *./odb64luo -x 3:"select count(*) from types" -f 5:script1.sql \*
+*-f 3:script2.sql -q -T 4*
+```
+[1.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[0.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[2.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[1.3.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[2.1.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[0.1.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[3.0.0]--- 1 row(s) selected in 0.001s (prep 0.000s, exec 0.001s, fetch 0.000s/0.000s)
+[2.2.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[3.1.0]--- 1 row(s) selected in 0.001s (prep 0.000s, exec 0.001s, fetch 0.000s/0.000s)
+[0.2.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+[1.2.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, fetch 0.000s/0.000s)
+```
+====
+
+The thread ID is now in the 0-3 range because the 11 *_executions_* were *_queued_* into four threads.
+odb offers several alternatives to queue `M` executions in `N(<M)` threads. See below.
+
+<<<
+== Limit Number of odb Threads
+By default, odb creates as many threads as the numbers of executions.
+
+The command in the following example creates `1 + 3 + 3 = 7` threads. Each thread will start its own ODBC connection.
+
+*Example*
+
+====
+`~/src/C/odb $` *./odb64luo -f script1.sql -f 3:script2.sql -x 3:"<mysqlcmd>"*
+====
+
+You can limit the max number of threads using `–T`.
+
+*Example*
+
+====
+`~/src/C/odb $` *./odb64luo -f script1.sql -f 3:script2.sql -x 3:"<mysqlcmd>" -T 2*
+====
+
+This command creates just two threads to execute the seven commands/scripts. odb will never create
+more threads than needed:
+
+*Example*
+
+====
+`~/Devel/odb $` *./odb64luo -f 2:script1.sql -f 3:script2.sql -T 8 -c -q* +
+`odb [main(1017)] - Warning: won't be created more thread (8) than needed (5).`
+====
+
+<<<
+== Change Executions Distributed Across Threads
+By default, executions are distributed in round-robin across threads.
+
+*Example*
+
+====
+`~/src/C/odb $` *./odb64luo -f script1.sql -f 3:script2.sql -x 3:"<mysqlcmd>" -T 3*
+====
+
+Using the command above, the execution queue will be as follows:
+
+[cols="25%h,25%,25%,25%",options="header"]
+|===
+| | Thread 1 | Thread 2 | Thread3
+| Third Execution | `mysqlcmd` | |
+| Second Execution | `Script2.sql` | `mysqlcmd` | `mysqlcmd`
+| First Execution | `Script1.sql` | `Script2.sql` | `Script2.sql`
+|===
+
+This (standard) behavior can be modified using the following options:
+
+* `–Z` (shuffle): This option *_randomizes_* the execution order.
+* *_factor sign_* with `–P` option: See <<query_driver_all_scripts_path, Run All Scripts With a Given Path>>.
+* `-dlb` (Dynamic Load Balancing): See <<concepts_load_balancing, Dynamic Load Balancing>>.
+
+<<<
+[[concepts_load_balancing]]
+== Dynamic Load Balanacing
+As discussed in the previous section, executions are normally _pre-assigned_ to threads using a simple
+round-robin algorithm. This way, the total elapsed time for each thread depends on the complexity of
+*its own* _executions_.
+
+*Example*
+
+Suppose you have two threads and two _executions_ per thread:
+
+[cols="33%h,33%,33%",options="header"]
+|===
+| | Thread 1 | Thread 2
+| Second Execution | `Script1.2` | `Script2.2`
+| First Execution | `Script1.3` | `Script2.1`
+|===
+
+If thread 2.1 and 2.2 require a very short time to be executed you can have a situation where Thread2 has
+nothing to do (it will be terminated) while Thread1 is still busy with *its own* Script1.3 and Script1.2.
+
+In some cases, for example during data extractions (see <<load_binary_files, Load Binary Files>>), you might want to keep all
+threads busy at any given time. In these cases you can use Dynamic Load Balancing (`-dlb`). With Dynamic
+Load Balancing jobs are not *pre-assigned* to threads when odb starts; each thread will pick the
+next job to run from the job list _at run-time_.
+
+== Use Variables in odb Scripts
+odb let you to use two kinds of variables:
+
+* *Internal Variables* defined through the `set param` command and identified by the ampersand character;
+* *Environment variables* defined at operating system level and identified by a dollar sign;
+
+You can mix internal and environment variables in your scripts. If a variable is not expanded to a valid
+Internal/Environment variable the text will remain unchanged.
+
+====
+`~/Devel/odb $` *cat scr.sql set param region1 ASIA*
+[source,sql]
+----
+-- region1 is defined as an internal odb parameter
+select * from tpch.region where r_name = '®ion1';
+-- region2 is defined as an environment variable
+select * from tpch.region where r_name = '$region2';
+-- you can mix internal and environment variables
+select * from tpch.region where r_name = '$region2' or r_name = '®ion1';
+-- region3 variable does not exists so it won’t be not expanded
+select * from tpch.region where r_name = '®ion3';
+----
+====
+After you define `region2` at operating system level:
+
+====
+`~/Devel/odb $` *export region2=AMERICA*
+====
+
+Output:
+
+====
+`~/Devel/odb $` *./odb64luo -u mauro -p xx -d pglocal -f scr.sql*
+```
+odb [2011-12-12 08:01:31]: starting (1) ODBC connection(s)... 1 [0.0.0]Executing:
+'select * from tpch.region where r_name = 'ASIA';' 2,ASIA,ges. thinly even pinto beans ca
+[0.0.0]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, 1st fetch 0.000s, fetch 0.000s)
+[0.0.1]Executing: 'select * from tpch.region where r_name = 'AMERICA';' 1,AMERICA,hs use ironic, even requests. s
+[0.0.1]--- 1 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, 1st fetch 0.000s, fetch 0.000s)
+[0.0.2]Executing: 'select * from tpch.region where r_name = 'AMERICA' or r_name = 'ASIA';' 1,AMERICA,hs use ironic,
+even requests.s2,ASIA,ges. thinly even pinto beans ca
+[0.0.2]--- 2 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, 1st fetch 0.000s, fetch 0.000s)
+[0.0.3]Executing: 'select * from tpch.region where r_name = '®ion3';'
+[0.0.3]--- 0 row(s) selected in 0.000s (prep 0.000s, exec 0.000s, 1st fetch 0.000s, fetch 0.000s)
+```
+====
+
+<<<
+== Thread ID, Thread Execution#, and Script Command#
+Consider a script containing two commands:
+
+====
+`~/odb $` *cat script.sql*
+[source,sql]
+----
+SELECT COUNT(*) FROM ORDERS;
+SELECT COUNT(*) FROM SUPPLIER;
+----
+====
+
+Running this script ten times using two threads yields:
+
+====
+`~/odb $` *./odb64luo -f 10:script.sql -q -T 2*
+```
+[0.0.0]--- 1 row(s) selected in 0.102s (prep 0.022s, exec 0.044s, 1st fetch 0.037s, fetch 0.037s)
+[1.0.0]--- 1 row(s) selected in 0.125s (prep 0.022s, exec 0.068s, 1st fetch 0.036s, fetch 0.036s)
+[0.0.1]--- 1 row(s) selected in 0.520s (prep 0.022s, exec 0.048s, 1st fetch 0.450s, fetch 0.450s)
+[1.0.1]--- 1 row(s) selected in 0.564s (prep 0.017s, exec 0.480s, 1st fetch 0.067s, fetch 0.067s)
+[0.1.0]--- 1 row(s) selected in 0.131s (prep 0.022s, exec 0.060s, 1st fetch 0.048s, fetch 0.048s)
+[0.1.3]--- 1 row(s) selected in 0.086s (prep 0.022s, exec 0.057s, 1st fetch 0.007s, fetch 0.007s)
+[1.3.0]--- 1 row(s) selected in 0.136s (prep 0.035s, exec 0.058s, 1st fetch 0.042s, fetch 0.042s)
+[0.2.0]--- 1 row(s) selected in 0.123s (prep 0.029s, exec 0.068s, 1st fetch 0.026s, fetch 0.026s)
+[1.3.1]--- 1 row(s) selected in 0.119s (prep 0.016s, exec 0.082s, 1st fetch 0.021s, fetch 0.021s)
+[0.2.1]--- 1 row(s) selected in 0.089s (prep 0.031s, exec 0.054s, 1st fetch 0.004s, fetch 0.004s)
+[1.2.0]--- 1 row(s) selected in 0.138s (prep 0.023s, exec 0.041s, 1st fetch 0.073s, fetch 0.073s)
+[0.3.0]--- 1 row(s) selected in 0.144s (prep 0.038s, exec 0.045s, 1st fetch 0.061s, fetch 0.061s)
+[1.2.1]--- 1 row(s) selected in 0.127s (prep 0.016s, exec 0.041s, 1st fetch 0.070s, fetch 0.070s)
+[0.3.1]--- 1 row(s) selected in 0.136s (prep 0.033s, exec 0.056s, 1st fetch 0.048s, fetch 0.048s)
+[1.3.0]--- 1 row(s) selected in 0.131s (prep 0.023s, exec 0.037s, 1st fetch 0.071s, fetch 0.071s)
+[0.4.0]--- 1 row(s) selected in 0.111s (prep 0.033s, exec 0.045s, 1st fetch 0.033s, fetch 0.033s)
+[0.4.1]--- 1 row(s) selected in 0.076s (prep 0.033s, exec 0.037s, 1st fetch 0.005s, fetch 0.006s)
+[1.3.1]--- 1 row(s) selected in 0.098s (prep 0.016s, exec 0.065s, 1st fetch 0.017s, fetch 0.017s)
+[1.4.0]--- 1 row(s) selected in 0.133s (prep 0.023s, exec 0.074s, 1st fetch 0.035s, fetch 0.035s)
+[1.4.1]--- 1 row(s) selected in 0.098s (prep 0.017s, exec 0.064s, 1st fetch 0.016s, fetch 0.016s)
+```
+====
+
+<<<
+The numbers between square brackets have the following meaning:
+
+1. The first digit is the *_thread ID_*. The example above has two threads; the ID is either 0 or 1.
+2. The second digit is the *_execution#_* for a given thread. The example above has ten script executions
+for two threads, each thread will have to execute this script five times.; *_execution#_*, is between 0 and 4.
+3. The third (last) digit is the *_command#_* in a given script. The script in the example above contains two
+commands; this value is 0 or 1.
+
+*Example*
+
+`*[0.3.1]*` means that the *first thread* (_thread id=0_) was executing its *fourth job*
+(_thread execution#=3_) and -- more specifically -- the *second command* in that script
+(_script command#=1_).
+
+<<<
+
+== Validate SQL Scripts
+You can check commands and SQL scripts with odb using the `-N` (null run) flag. This will just `prepare`
+(compile) the commands without executing them and fetching the results.
+
+== Different Data Sources for Different Threads
+
+Normally all ODBC connections started by odb will use the same Data Source. However, there could be
+special cases where you want to use different DSN for different threads. In these cases you can use the
+`–ndsn <number>` option. This will append to the Data Source name specified via `–d` a suffix from `1` to `-ndsn` argument.
+
+*Example*
+
+====
+`$` *./odb64luo ... –d MYDSN –ndsn 4*
+====
+
+It will use the following (round-robin) DSN/thread association: `MYDSN1` for the first thread, `MYDSN2` for the
+second thread and so on. The fifth thread (if any) will use `MYDSN1` again. You can use a sequential
+DSN/thread association by using a `+` sign in front of the `–ndsn` argument.
+
+*Example*
+
+If you have 16 threads and `–d MYDSN`:
+
+[cols="33%,33%,33%",options="header"]
+|===
+| Thread ID | DSN with `–ndsn 8` | DSN with `–ndsn +8`
+| `0` | `MYDSN1` | `MYDSN1`
+| `1` | `MYDSN2` | `MYDSN1`
+| `2` | `MYDSN3` | `MYDSN2`
+| `3` | `MYDSN4` | `MYDSN2`
+| `4` | `MYDSN5` | `MYDSN3`
+| `5` | `MYDSN6` | `MYDSN3`
+| `6` | `MYDSN7` | `MYDSN4`
+| `7` | `MYDSN8` | `MYDSN4`
+| `8` | `MYDSN1` | `MYDSN5`
+| `9` | `MYDSN2` | `MYDSN5`
+| `10` | `MYDSN3` | `MYDSN6`
+| `11` | `MYDSN4` | `MYDSN6`
+| `12` | `MYDSN5` | `MYDSN7`
+| `13` | `MYDSN6` | `MYDSN7`
+| `14` | `MYDSN7` | `MYDSN8`
+| `15` | `MYDSN8` | `MYDSN8`
+|===
+
+This technique has been used to maximize extraction throughput from a multi-segment Trafodion system.
+Each (local) Data Source was *linked* to a corresponding remote Data Source extracting its own data through its
+own network interface card.
+
+== Format Query Results
+Normally odb prints query results using a very basic CSV format.
+
+*Example*
+
+====
+`$` *./odb64luo -x "select s_suppkey, s_name, s_phone from tpch.supplier limit 5*
+[source,sql]
+----
+1,Supplier#000000001,27-918-335-1736
+2,Supplier#000000002,15-679-861-2259
+3,Supplier#000000003,11-383-516-1199
+4,Supplier#000000004,25-843-787-7479
+5,Supplier#000000005,21-151-690-3663
+----
+====
+
+Adding the option `-pad` you generates the output in table format:
+
+====
+`$` *./odb64luo -x "select s_suppkey, s_name, s_phone from tpch.supplier limit 5" -pad*
+```
+s_suppkey |s_name |s_phone
+---------------+-------------------------+---------------
+1 |Supplier#000000001 |27-918-335-1736
+2 |Supplier#000000002 |15-679-861-2259
+3 |Supplier#000000003 |11-383-516-1199
+4 |Supplier#000000004 |25-843-787-7479
+5 |Supplier#000000005 |21-151-690-3663
+```
+====
+
+<<<
+== Extract Table DDL
+
+You can extract DDL from one or several tables using either the `-i D…` or
+`-i U…` option.
+
+*Example*
+
+====
+`$` *./odb64luo -u xxx -p xxx -d traf -i D:TRAFODION.SEABASE.REGIONS*
+[source,sql]
+----
+odb [2015-04-20 21:25:35]: starting ODBC connection(s)... 0
+Connected to Trafodion
+
+CREATE TABLE TRAFODION.SEABASE."REGIONS" ( REGION_ID INTEGER NOT NULL
+, REGION_NAME VARCHAR(25)
+);
+----
+====
+
+The `&` wildcard allows you to extract the DDL for multiple objects.
+
+*Example*
+
+The following command will extract the DDL for all tables in schema `tpch` starting with `P`:
+
+====
+`$` *./odb64luo -u xxx -p xxx -d traf -i D:TRAFODION.TPCH.P%*
+[source,sql]
+----
+odb [2015-04-20 21:33:43]: starting ODBC connection(s)... 0
+Connected to Trafodion
+
+CREATE TABLE TRAFODION.TPCH."PART" ( P_PARTKEY BIGINT NOT NULL
+,P_NAME VARCHAR(55) NOT NULL
+,P_MFGR CHAR(25) NOT NULL
+,P_BRAND CHAR(10) NOT NULL
+,P_TYPE VARCHAR(25) NOT NULL
+,P_SIZE INTEGER NOT NULL
+,P_CONTAINER CHAR(10) NOT NULL
+,P_RETAILPRICE BIGINT NOT NULL
+,P_COMMENT VARCHAR(23) NOT NULL
+,PRIMARY KEY (P_PARTKEY)
+);
+
+CREATE TABLE TRAFODION.TPCH."PARTSUPP" ( PS_PARTKEY BIGINT NOT NULL
+,PS_SUPPKEY BIGINT NOT NULL
+,PS_AVAILQTY INTEGER NOT NULL
+,PS_SUPPLYCOST BIGINT NOT NULL
+,PS_COMMENT VARCHAR(199) NOT NULL
+,PRIMARY KEY (PS_PARTKEY,PS_SUPPKEY)
+);
+
+odb [2015-04-20 21:33:45]: exiting. Session Elapsed time 2.069 seconds (00:00:02.069)
+----
+====
+
+You should consider possible differences in text column length semantic when porting DDLs from one database to another;
+some databases use "character oriented" text columns length while others use a "byte oriented" semantic.
+
+You can ask odb to multiply text column length when printing DDL using the switch
+`–U[non-wide_char_multiplier,wide_char_multiplier]`.
+
+<<<
+*Example*
+
+====
+`$` *./odb64luo -u xxx -p xxx -d traf -i U2,4:TRAFODION.TPCH.P%*
+[source,sql]
+----
+odb [2015-04-20 21:35:17]: starting ODBC connection(s)... 0
+Connected to Trafodion
+
+CREATE TABLE TRAFODION.TPCH."PART" ( P_PARTKEY BIGINT NOT NULL
+,P_NAME VARCHAR(110) NOT NULL
+,P_MFGR CHAR(50) NOT NULL
+,P_BRAND CHAR(20) NOT NULL
+,P_TYPE VARCHAR(50) NOT NULL
+,P_SIZE INTEGER NOT NULL
+,P_CONTAINER CHAR(20) NOT NULL
+,P_RETAILPRICE BIGINT NOT NULL
+,P_COMMENT VARCHAR(46) NOT NULL
+,PRIMARY KEY (P_PARTKEY)
+);
+
+CREATE TABLE TRAFODION.TPCH."PARTSUPP" ( PS_PARTKEY BIGINT NOT NULL
+,PS_SUPPKEY BIGINT NOT NULL
+,PS_AVAILQTY INTEGER NOT NULL
+,PS_SUPPLYCOST BIGINT NOT NULL
+,PS_COMMENT VARCHAR(398) NOT NULL
+,PRIMARY KEY (PS_PARTKEY,PS_SUPPKEY)
+);
+
+odb [2015-04-20 21:35:18]: exiting. Session Elapsed time 1.620 seconds (00:00:01.620)
+----
+====
+
+The command in the above example multiplies the length of "non-wide" text fields by 2 and
+the length of wide text fields by 4.
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/install.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/install.adoc b/docs/odb_user/src/asciidoc/_chapters/install.adoc
new file mode 100644
index 0000000..5a71706
Binary files /dev/null and b/docs/odb_user/src/asciidoc/_chapters/install.adoc differ
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/859a7e4c/docs/odb_user/src/asciidoc/_chapters/introduction.adoc
----------------------------------------------------------------------
diff --git a/docs/odb_user/src/asciidoc/_chapters/introduction.adoc b/docs/odb_user/src/asciidoc/_chapters/introduction.adoc
new file mode 100644
index 0000000..66a119f
--- /dev/null
+++ b/docs/odb_user/src/asciidoc/_chapters/introduction.adoc
@@ -0,0 +1,50 @@
+////
+/**
+ *@@@ START COPYRIGHT @@@
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * @@@ END COPYRIGHT @@@
+ */
+////
+
+= Introduction
+== What is odb
+odb is a platform independent, multi-threaded, ODBC command-line tool you can use as a:
+
+* Parallel data loader/extractor
+* Query driver (Technology Preview)
+* SQL interpreter (Technology Preview)
+
+odb is written in ANSI C. Currently, odb is available only in a 64-bit version for the Linux platform,
+linked to the unixODBC driver manager.
+
+odb executables use the following naming convention, `*_odbAABCC_*`, where:
+
+* `**AA**` can be 64 (bit) (32 bit is not currently supported).
+* `**B**` identifies the platform/compiler:
+** `l` = Linux/gcc
+** `w` = Windows/MS Visual Studio (not yet tested)
+* `**CC**` identifies the ODBC Driver Manager to which odb was linked:
+** `uo` = unixODBC Driver Manager
+** `ms` = Microsoft ODBC Driver Manager (not yet tested)
+
+So, for example:
+
+* `**odb64luo**` is the 64-bit executable for Linux linked with the unixODBC Driver Manager.
+
+This document contains examples run with the `**odb64luo**` executable.
+
+