ODBCTEST - ODBC test application
================================
ODBCTEST is a small test application that enables you to 
connect to an ODBC source and execute SQL statements against 
it. It is there for those of you that do not already have 
some other (and better) application able to talk to ODBC 
drivers. Its main strong point is its ability to return the 
raw ODBC error messages directly to you without any 
filtering. This can be a very handy feature. You may also 
find it a nice utility if you often issue long streams of SQL 
against different ODBC compatible databases.

ODBCTEST is written by Jorgen Grosbol, ISS Data, Denmark, in 
1996 and 1997.

ODBCTEST is freeware .

Disclaimer : If you use this software, you and you alone 
carry the responsibility for errors and/or problems resulting 
from its use.


Software Version Information
----------------------------
This document refers to version 2.7 of the ODBCTEST program 
dated 2000-07-03.


Using ODBCTEST
--------------
You activate ODBCTEST by simply double clicking its icon. The 
interface is MDI (multi document interface), so you can 
access and test several ODBC sources at the same time, one in 
each window.

Double click on the ODBCT32.EXE program to start ODBCTEST.

Before you can execute SQL statements against an ODBC source, 
you must connect to it. Use the SQL/Open ODBC connection menu 
item to perform the connection.

Once the connection is established you use the SQL/Execute 
SQL commands menu item to enter and submit SQL commands 
against the data source. You can load and save the SQL 
statements in files via the buttons placed directly under the 
SQL source filename field.

You can submit more than one SQL statement if you delimit 
them by semicolons . If semicolons are used they should be 
either the last nonblank character on the line or occupy an 
otherwise blank line by themselves. In addition, you may 
place SQL comment characters (double dash, --) in front of 
lines to have ODBCTEST ignore them. Tab characters are 
translated to blanks before the SQL statement is submitted to 
the host.

If you execute several SQL statements and an error occurs you 
are shown the error message and you are asked if you want to 
cancel the command stream now or if you want to continue 
processing commands.

Note that due to Windows peculiarities you have to use 
Ctrl+Enter to place newline characters in the SQL source 
window.


Using the Table Lookup
----------------------
This function allows you to browse through the list of 
available tables in your server and to create several types 
of SQL statements towards them. The SQL dialect may not match 
the requirements of your driver completely, but even so, this 
feature can substantially reduce the work needed to create 
new SQL statements from scratch - and it is very easy to use.

This version of ODBCTEST Gives you the ability to change the 
default data type names in the create statements and also 
allows you to save and restore the defaults from a file. If 
you repeatedly use the program to generate create statements 
for a database system with a deviating syntax this can save 
you some tedious editing work.


Batch download of data
----------------------
If you activate the ODBCTEST program from a command prompt or 
from a BAT file you can make it perform SQL commands to a 
host without opening any windows. You do it like this:

             C:> ODBCT32.EXE  =outputfile options 
             sql-statement
            
where:

             '=outfile' is the name of the output file where 
             the result is placed. This must be the first 
             parameter on the command line. If the name 
             contain blanks you must enclose it in single or 
             double quotes. You control the contents of this 
             file by options.
            
             'options' are some set of options where each 
             option has must start with a slash and a 
             lowercase letter. You cannot group options. Each 
             option must be prefixed with a slash. If the 
             option contain spaces you must quote the option 
             value (like this: /s"My Source") The possible 
             options are:
            
                         /v inserts a line containing program 
                         name, version and compile date into 
                         the output file.
                        
                         /i inserts a line with the command 
                         line options into the output file.
                        
                         /m inserts a line containing either 
                         the text "OK" or the ODBC error 
                         message if something went wrong.
                        
                         /o lists the available ODBC driver 
                         names in the output file. Each name 
                         starts on a new line and is prefixed 
                         with a colon.
                        
                         /c lists the name and some column 
                         information for each column in the 
                         result set (if any) to the output 
                         file. Each column is starts on a new 
                         line and is prefixed with a '>' 
                         character.
                        
                         /sNNNNN defines the ODBC source name 
                         to be used.
                        
                         /uXXXXX defines the userid to be 
                         used when connecting to ODBC.
                        
                         /pPPPPPP defines the password to be 
                         used when connecting to ODBC.
                        
                         /dX uses the character X as 
                         delimiter between data fields 
                         returned in the output file. The 
                         default is a comma.
                        
                         /q quotes each output field with the 
                         double-quote character. You can also 
                         use the option /qX to use the 
                         character X to surround each output 
                         field.
                        
                         /rY replaces all occurrences of 
                         character Y with blanks in the 
                         returned data fields in the output 
                         file. Typically used to remove 
                         commas from the text fields to avoid 
                         ambiguity about where the field ends.
                        
                         /n inserts the string NULL in the 
                         output file each time a NULL value 
                         data field is encountered.
                        
                         /bN1,N2,N3,... (where ' Nx ' is some 
                         positive integer number) skips to a 
                         new line in the output file each 
                         time the corresponding number of 
                         columns has been output. If you 
                         specify /b2,3 and have 10 columns in 
                         the result set, then the first two 
                         columns will be placed in the first 
                         line, the next 3 columns will be 
                         placed in the second line and the 
                         last 5 columns will be placed in the 
                         third line. In this case each output 
                         row will produce three lines in the 
                         output file.
                        
                         /fN1,N2,N3,... (where 'Nx' is left 
                         out or some positive integer) 
                         defines the output width of each 
                         column. In this way you can force 
                         the width of columns to always have 
                         the same length effectively creating 
                         fixed format output records. The 
                         data in each field is left 
                         justified. Fields that are longer 
                         than the specified number of 
                         positions are truncated from the 
                         right. If you do not specify the 
                         width of a column it defaults to the 
                         current character width which may be 
                         varying form row to row.
                        
                         /xABCD (where 'A', 'B', 'C' and 'D' 
                         are single characters) defines what 
                         characters in your SQL line should 
                         be translated into '(', ')', '<' and 
                         '>' respectively. If you leave this 
                         option out the default is /x[]{} . 
                         This option allows you to use 
                         parentheses and comparations in your 
                         SQL statements. So, if you want to 
                         write SELECT COUNT(*) FROM A.B you 
                         actually have to write SELECT 
                         COUNT[*] FROM A.B . The reason 
                         behind this option is that certain 
                         characters (like parentheses and the 
                         '>' and '<' operators) are not 
                         allowed on command lines in certain 
                         systems.
                        
                         /hXXX (where 'XXX' is any text 
                         string) will replace all newline 
                         characters with the specified text. 
                         If you leave out the /h option the 
                         default is to insert the string ' 
 
                         ' in place of all newline characters 
                         in output fields. Please note that 
                         in this version of ODBCTEST ' 
 ' 
                         characters are not translated when 
                         updating or inserting fields (but of 
                         course some database systems may 
                         perform the translation for you on 
                         their own).
                        
                         /eFILENAME (where 'FILENAME' is the 
                         name of an existing text file) 
                         allows you to supply data values for 
                         repeated executions of the SQL 
                         statement in a file. Each line in 
                         the file is read and the data values 
                         are used as host variables for the 
                         SQL statement. The SQL statement 
                         itself must contain references to 
                         the host variables in the form of 
                         question marks, as in:
                        
                         INSERT INTO CREA.TABL (COL1, COL2, 
                         COL3) VALUES(?,?,?)
                        
                         Delimiter characters must separate 
                         the data values in the file. You can 
                         change the default delimiter (comma) 
                         with the /d option. The SQL 
                         statement is issued one time for 
                         each non-empty input line. The 
                         output file will hold the appended 
                         results from all executions of the 
                         SQL statement. If you specify the /n 
                         option you can use the string NULL 
                         to insert null-values into the host 
                         variables. An input file for the 
                         above SQL statement could look like 
                         this:
                        
                                     123,Nigel 
                                     Larsson,1998-04-02
                                     124,Carl 
                                     Petersen,1998-03-29
                                     125,Joy 
                                     Pettingblast,1998-12-4
                                    
                         /tXXXXX (where each 'X' is one of 
                         the letters defined below) is used 
                         in conjugation with the /e option to 
                         specify the format of the input 
                         fields. Each letter corresponds to 
                         one field in the file. The default 
                         format is c (character format) for 
                         all. Some database systems require 
                         host variables to be in the correct 
                         format, others will perform the 
                         conversion from character format for 
                         you thus eliminating the need for 
                         the /t option. The above sample 
                         input file could match the 
                         parameter: /ticd . The possible type 
                         letters are:
                         c .... character format
                         n .... numeric format
                         i .... integer format
                         f .... floating point format
                         d .... date format
                         t .... time format
                         s .... timestamp format
                        
                         /wFILENAME (where 'FILENAME' is the 
                         name of an existing text file) lets 
                         you read part or all of the sql 
                         statement from the specified file. 
                         If you specify the /w option the 
                         contents of the file will be 
                         appended to the SQL specified on the 
                         command line. The file can contain 
                         more than one line, but only one SQL 
                         statement. Do not place a trailing 
                         semicolon after the SQL statement. 
                         Note that the special characters 
                         from the /x option are not 
                         translated, so in the file you must 
                         specify the SQL statement exactly as 
                         you want it to appear to the host 
                         database system.
                        
             'sql-statement' is the SQL statement to be 
             executed. If you specify the /w option you can 
             omit this part of the command line.
            
You must start the options on the command line with an equal 
sign for the program to run in batch mode with no windows 
displayed.

This may seem somewhat daunting, but really, there is not 
that much to it. An example:


ODBCT32.EXE =c:\myfile.txt /m /n /sSORUCE1 select * from 
MY.TABLE

This will make the 32-bit version of ODBCTEST connect to the 
ODBC source named SOURCE1 and issue the SELECT statement. The 
result is written to the file c:\myfile.txt . After executing 
the above line from a command prompt the file should look 
something like this:

             OK
             1,55.3,Jensen,
             2,NULL,Petersen,
             ...
            
The first line is the return code of the select statement 
(because the /m option was used) and the following lines 
contain the data rows selected from the table. The /n option 
ensures that the text NULL is inserted in place of empty 
(NULL) data values.

Please note that the program executes in the background, so 
the task is probably not finished when the command prompt 
reappears. This means that if you issue several calls to 
ODBCTEST from a BAT file they will all execute in parallel. 
Also note that error messages are not written to the command 
window but to the result file (see the /m option).


Choosing ODBC drivers
---------------------
The ODBC interface exists in several versions and each 
version implements several levels (core level, level 1 and 
level 2). This alone ensures that you cannot be sure that 
your ODBC driver will work with the ODBCTEST program, but to 
complicate matters further not all drivers are written 
exactly to specifications, and some drivers contain bugs.

The ODBCTEST program is written to the ODBC version 2 
function level 2, but it does not by far use all functions in 
the interface, so drivers implementing a lower level may 
still work. Sometimes this may result in irrelevant error 
messages. Higher levels of ODBC (like version 3) should of 
course work with the ODBCTEST program.

To summarize: you should always test to see if a driver 
actually works with the software mix you are going to use. Do 
not take the driver supplier's word for it.

We have tested ODBCTEST against several ODBC drivers, and our 
general impression is that the drivers from the major 
suppliers work just fine. When it comes to drivers for less 
popular systems, you just have to try them out.


Talking to the author
---------------------
You can reach me at my E-mail address: 
jorgen.grosbol@iss-data.dk , put please remember that this is 
a freeware program given to you as-is . While I would love to 
hear from you, I may find it difficult to take time out to 
answer all mail, so don't be disappointed if you don't get an 
answer.
