Copyright: 1994 Microsoft Corporation. All rights reserved.


ODBC Test Contents

Overview

ODBC Test Menus

Using the ODBC Test Interface

Using Auto Tests

Tool Reference

Function Tool Reference

Function Reference

Error and Warning Messages


Overview

Microsoft ODBC Test is an ODBC-enabled application that you can use to test ODBC drivers. ODBC Test has four distinct types of menu items that you can use to execute ODBC functions:

•	Functions    Functions are menu items that call ODBC functions. When you select a function from an ODBC Test menu, ODBC Test displays a dialog box that has one control for each argument in the function. When you select the OK button in the dialog box, ODBC Test executes the function using the values specified for each argument.

•	Function Tools    Function tools are menu items that call a group of related ODBC functions or help you use an ODBC function. For example, Full Disconnect calls SQLDisconnect, SQLFreeConnect, and SQLFreeEnv; Fill Param displays a dialog box in which you enter parameter values. Function tools are listed at the bottom of the Connect, Statement, Results, and Misc menus beneath a separator line.

•	Tools    Tools are menu items that help you configure ODBC Test, such as the level of errors to report or whether menu items for functions the driver does not support are disabled.

•	Auto Tests    Automated tests, or auto tests, are dynamic-link libraries (DLLs) that you have written. Each auto test DLL contains one or more test cases. For example, an auto test for SQLAllocStmt might contain test cases to call SQLAllocStmt with valid and invalid arguments and to call SQLAllocStmt until the driver runs out of statement handles. The source code for a sample auto test that tests basic driver functionality (the Quick Test) is shipped with the ODBC SDK in the \ODBCSDK\SAMPLES\QUIKTEST directory.

In order to use ODBC Test, you must understand the ODBC API, the C language, and SQL. For more information on the ODBC API, see the Microsoft ODBC SDK Programmer's Reference.


ODBC Test Menus

File

Edit

Connect

Statement

Results

Catalog

Misc

Tools

Window

Help


File Menu

Command	Description
Open	Loads text files into the input window.
Save As	Saves contents of the input window as a text file.
Exit	Exits ODBC Test.


Edit Menu

Command	Description
Undo	Reverses the previous Edit menu command.
Cut	Removes the selected text and places it onto the Clipboard.
Copy	Copies the selected text onto the Clipboard.
Paste	Inserts a copy of the Clipboard contents at the insertion point.
Delete	Removes the selected text without placing it onto the Clipboard.
Clear	Clears the contents of the input window or output window, or both.
Select All	Selects the entire contents of the input window.
Word Wrap	Turns wordwrap on or off for the input window.


Connect Menu

SQLAllocEnv

SQLAllocConnect

SQLConnect

SQLBrowseConnect

SQLDriverConnect

SQLDisconnect

SQLFreeConnect

SQLFreeEnv

SQLSetConnectOption

SQLGetConnectOption

SQLDataSources

SQLDrivers

SQLGetInfo

Full Connect

Full Disconnect

Data Sources All

Drivers All

Get Info All


Statement Menu

SQLAllocStmt

SQLSetStmtOption

SQLGetStmtOption

SQLPrepare

SQLBindParameter

SQLNumParams

SQLDescribeParam

SQLExecute

SQLExecDirect

SQLSetCursorName

SQLGetCursorName

SQLParamData

SQLPutData

SQLParamOptions

SQLFreeStmt

SQLNativeSql

Fill Param

Show Params


Results Menu

SQLNumResultCols

SQLDescribeCol

SQLColAttributes

SQLRowCount

SQLBindCol

SQLFetch

SQLExtendedFetch

SQLSetPos

SQLGetData

SQLMoreResults

SQLSetScrollOptions

Describe Col All

Bind Col All

Show Bound Cols

Fetch All

Get Data Row

Get Data All


Catalog Menu

SQLGetTypeInfo

SQLTables

SQLColumns

SQLStatistics

SQLPrimaryKeys

SQLForeignKeys

SQLTablePriveleges

SQLColumnPriveleges

SQLSpecialColumns

SQLProcedures

SQLProcedureColumns


Misc Menu

SQLTransact

SQLCancel

SQLError

SQLGetFunctions

Errors All

Get Functions All


Tools Menu

User Options

Rowset Options

Trace

Manage Test Sources

Manage Auto Tests

Manage Test Groups

Run Auto Tests


Window Menu

Command	Description
Cascade	Cascades all windows.
Tile	Tiles all windows vertically.
Tile Horizontal	Tiles all windows horizontally.
Arrange Icons	Arranges all minimized window icons.
Close All	Closes all windows.
List of Open Windows	Lists each open window by name.


Help Menu

Command	Description
ODBC Test Help	Displays this Help file.
ODBC API Help	Displays the OBDC API Help file.
About ODBC Test	Displays version information.


Using the ODBC Test Interface

Tutorial

Using Windows

Using Function Dialog Boxes


Tutorial

This tutorial illustrates how to connect to a data source, create a table and insert values into it, retrieve those values, and disconnect from the data source. In so doing, it acquaints you with most of the ODBC Test user interface.

 ( [image]) 	To connect to a data source

1.	Create a dBASE data source called Test Data using the ODBC Administrator. (For information on creating data sources with the ODBC Administrator, see the ODBC SDK Guide.)

2.	Start ODBC Test. Either double-click the ODBC Test icon in the ODBC SDK 2.0 program group (or the ODBC Test32 icon if you are running Win32s or Windows NT) or choose Run from the File menu in the Program Manager or File Manager and type \odbcsdk\bin\odbctest.exe (or \odbcsdk\bin32\odbcte32.exe if you are running Win32s or Windows NT).

3.	From the Connect menu, choose Full Connect. ODBC Test displays the SQL Data Sources dialog box.

4.	Select Test Data from the list of data sources and choose the OK button. ODBC Test connects to the Test Data data source and allocates a statement handle. It displays the connection window and the allocated statement handle in the statement handle list.

 ( [image]) 	To create a table and insert values into it

1.	Using the connection window from the previous procedure, type the following SQL statement in the input window:

CREATE TABLE NewTable (City CHAR(10), State CHAR(2))

2.	From the Statement menu, choose SQLExecDirect. ODBC Test displays the SQLExecDirect dialog box. The value of <input window> in the szSqlStr argument indicates that ODBC Test will retrieve the SQL statement from the input window.

3.	Choose the OK button to execute SQLExecDirect. ODBC Test calls SQLExecDirect with the specified arguments and displays the function name, input argument values, and return code in the output window.

4.	Type the following SQL statements in the input window. You do not need to delete the CREATE TABLE statement.

INSERT INTO NewTable VALUES ('Erie', 'PA')
INSERT INTO NewTable VALUES ('Atlanta', 'GA')
INSERT INTO NewTable VALUES ('Cheyenne', 'WY')

5.	Using the mouse, select the first INSERT statement.

6.	From the Statement menu, choose SQLExecDirect again, then choose the OK button to execute SQLExecDirect with the new arguments. ODBC Test calls the driver to insert the values in the table and displays information about the function call in the output window.

Note  If you don't select the line you want to execute, ODBC Test passes all the statements in the input window to the driver. Although some drivers can process multiple statements, the dBASE driver used in this example cannot.

7.	Repeat steps 5 and 6 for the other two INSERT statements.

 ( [image]) 	To retrieve data from a table

1.	Using the connection window and the table from the previous procedure, type the following SQL statement in the input window and select it with the mouse:

SELECT * FROM NewTable

2.	From the Statement menu, choose SQLExecDirect again, then choose the OK button to execute SQLExecDirect with the new arguments. ODBC Test calls the driver to select the data from the table and displays information about the function call in the output window.

3.	From the Results menu, select the Get Data All function tool. The Get Data All function tool retrieves all of the data in the result set created by the SELECT statement. It displays the column count, the column names, the data, and the number of rows fetched in the output window:

"CITY", "STATE"
"Erie      ", "PA"
"Atlanta   ", "GA"
"Cheyenne  ", "WY"
3 rows fetched from 2 columns.

 ( [image]) 	To disconnect from a data source

•	For the connection window used in the previous procedure, select Full Disconnect from the Connect menu. ODBC Test disconnects from the data source and removes the connection window. It then displays a message that the connection is closed in the general output window.


Using Windows

ODBC Test has three types of windows, a general output window, zero or more connection windows, and zero or more rowset windows.

General Output Window

ODBC Test has a single general output window. It uses this window to display information that is not directly related to a connection. For example, ODBC Test displays the output of the SQLAllocEnv function in the general output window.

Connection Windows

ODBC Test creates a connection window each time SQLAllocConnect is successfully executed; it closes the specified connection window each time SQLFreeConnect is successfully executed. To use a specific connection, select the window for that connection.

Each connection window has three parts:

•	Statement Handle List    At the top of the connection window is a list of allocated statement handles and their values. On Windows, the value is a 16-bit segment address and a 16-bit offset; on Windows NT, the value is a 32-bit address. Each time SQLAllocStmt is called, the new statement handle is added to this list; each time SQLFreeStmt is called with the SQL_DROP option, the specified statement handle is removed from the list.

To select a statement handle to use when calling an ODBC function, select the handle from this list. You can also select a null handle.

•	Input Window    The top half of each connection window is used to enter SQL statements for the SQLExecDirect, SQLNativeSql, and SQLPrepare functions, and data for the SQLPutData function. ODBC Test passes the highlighted statements or data to the function. If no statements or data are highlighted, ODBC Test uses all the statements or data in the input window.

To load a text file into the input window, choose Open from the File menu. To save the statements in the input window, choose Save As from the File menu.

•	Output Window    The bottom half of each connection window is used by ODBC Test to display information about each function that it executes, such as the return code and the input and output argument values. To control what information is displayed, choose User Options from the Tools menu and select the desired level from the Logging Level list. To control whether the output wraps from line to line, choose Word Wrap from the Edit menu.

The input and output windows can each contain up to 60,000 characters. When the number of characters in one of these windows reaches this limit, ODBC Test deletes the first 2000 characters in the window. To clear the input or output window, choose Clear from the Edit menu and specify whether to clear one or both windows.

Rowset Windows

ODBC Test creates a rowset window when SQLExtendedFetch is called for the first time on a statement handle. It closes the rowset window when the cursor associated with the statement handle is closed. The rowset window displays the contents of the rgbValue and pcbValue buffers bound to the result set with SQLBindCol and the contents of the rgfRowStatus array specified in SQLExtendedFetch. You can use the Row Options item on the Tools menu to control whether the pcbValue buffers, rgfRowStatus array, and column names are displayed.

Note  Rowset windows do not display the results of calls to SQLGetData; these are displayed in the output window of the connection window.

To update the value of a cell in a rowset window, highlight the cell and choose the Update Cell function tool from the Results menu or double-click the cell. You can also use the Update Cell function tool to view the value of the pcbValue buffer bound to the column with SQLBindCol.


Using Function Dialog Boxes

When you choose an ODBC function from a menu, ODBC Test displays a dialog box in which you can specify argument values. The dialog box contains one control for each argument; it may contain additional controls for supplemental information. For example, the SQLSetStmtOption dialog box contains a list from which you can select the C data type of the vParam argument for a driver-specific statement option.

ODBC Test uses text boxes, drop-down combo boxes, and check boxes in function dialog boxes

Text Boxes

Text boxes are used to specify values for numeric arguments for which no #define values (such as SQL_NTS or SQL_NULL_DATA) apply. For example, text boxes are used to specify values for the cbConnStrOutMax argument in SQLDriverConnect and the icol argument in SQLBindCol.

Drop-Down Combo Boxes

Drop-down combo boxes are used to specify values for most arguments. For example, drop-down combo boxes are used to specify values for the szConnStrIn, cbConnStrIn, and fDriverCompletion arguments in SQLDriverConnect.

For numeric arguments, the list consists of all applicable #define names and the numeric value associated with each #define name. If Version Numbers in the User Options dialog box is selected, the version of ODBC in which each #define name was introduced is also displayed.

For character arguments, the list always contains <empty string> and <null pointer>. It may contain <input window> or <input window selection> (to use the currently selected text in the input window or, if no text is selected, all text in the input window), and any known text values, such as data source names. For character arguments, ODBC Test automatically places the length of the character argument in the corresponding length argument when you move the focus to a different control.

For some arguments, the list may contain <rowset values>. This activates the Rowset hdbc and Rowset hstmt list boxes, which enable you to specify the hdbc and hstmt of the bound rowset. The Row and Column text boxes allow you specify the row and column number, respectively.

You can either select a value from the list or type a value in the text box. If the argument accepts values for which #define names apply, you can type the #define name (or any unambiguous portion of it) in the text box. For example, to specify that the driver prompt the user for connection information, select SQL_DRIVER_COMPLETE from the list of values for fDriverCompletion or type 1, 0x01, or SQL_DRIVER_COMPLETE (COM would be sufficient).

Check Boxes

Check boxes are used to specify values for input arguments that accept environment, connection, or statement handles; input arguments that accept window handles; and output arguments that accept pointers to handles or pointers to output buffers. For example, check boxes are used to specify values for the hdbc, hwnd, szConnStrOut, and pcbConnStrOut arguments in SQLDriverConnect.

After each check box is the name of the argument and its value:

•	For input arguments that accept handles, the value is either the handle value or NULL. ODBC Test retrieves this value from the current environment handle, the connection handle of the current connection window, or the statement handle of the current statement in the current connection window.

•	For input arguments that accept window handles and output arguments that accept pointers to handles or pointers to output buffers, the value is either VALID or NULL.

A handle value or VALID indicates that ODBC Test will pass a valid, non-null pointer or handle; NULL indicates that ODBC Test will pass a null pointer or handle. To switch between the two, select or clear the check box.

Data Formats

ODBC Test accepts data in the following formats:

Data Type	Valid Formats
Binary	Hexadecimal. The value must contain an even number of hexadecimal characters. For example, 0x0100 is legal; 0xF is not.
Bit	Decimal (0 to 255). Hexadecimal (0x00 to 0xFF).
Character	Character. For example, abc. Hexadecimal. The value must contain an even number of hexadecimal characters. For example, 0x 61 62 63 is legal; 0x616 is not.
Date	YYYY-MM-DD. For example, 1993-10-25. Hexadecimal. The hexadecimal characters match the DATE_STRUCT structure. You must enter exactly 12 hexadecimal characters. For example, 0x 07C9 000A 0019.
Floating Point	Decimal. For example, 1234.46. Scientific notation. For example, 1.23446E3. Hexadecimal. The value must contain the exact number of hexadecimal characters required by the floating-point data type. For example, type 0xA64E9A44 for the SFLOAT 1234.46 and type 0x1D5A643BDFD98E40 for the SDOUBLE 987.234.
Integer	Decimal. For example, 255. Hexadecimal. The value can contain any number of hexadecimal characters up to the length of the integer. For example, 0xFF or 0xF.
Time	HH:MM:SS. For example, 12:34:56. Hexadecimal. The hexadecimal characters match the TIME_STRUCT structure. You must enter exactly 12 hexadecimal characters. For example, 0x 000C 0022 0038.
Timestamp	YYYY-MM-DD (time is set to 0). For example, 1993-10-25. HH:MM:SS (date is set to current date). For example, 12:34:56. YYYY-MM-DD HH:MM:SS[.F...]. For example, 1993-10-25 12:34:56. Hexadecimal. The hexadecimal characters match the TIMESTAMP_STRUCT structure. If you specify the fractional part of a timestamp, you must enter exactly 32 hexadecimal characters. If you do not specify the fractional part of a timestamp, you must enter exactly 24 hexadecimal characters. For example, 0x 07C9 000A 0019 000C 0022 0038 0000 0000 (with the fractional part) or 0x 07C9 000A 0019 000C 0022 0038 (without the fractional part).
Hexadecimal values are subject to the following constraints:

•	Values must be in order of most-significant byte to least-significant byte. ODBC Test will convert these values to the byte order of the machine it is running on.

•	Letters in hexadecimal values can be upper or lower case. For example, 0xFF, 0xfF, 0xFf, and 0xff are the same.

•	Hexadecimal values can contain spaces at any point after the 0x characters; ODBC Test ignores these spaces. For example, 0xFF and 0x FF are the same.


Using Auto Tests

Writing an Auto Test

The Quick Test Sample

Building an Auto Test

Creating Test Sources

Installing Auto Tests

Creating Test Groups

Running Auto Tests

Auto Test Function Reference

ODBC Test Function Reference


Writing an Auto Test

Writing an auto test is like writing any other ODBC application. You must write code to allocate and free handles, connect to and disconnect from data sources, and access data. As a starting point, you can use CUSTOM.C or QUIKTEST.C in the \ODBCSDK\SAMPLES\QUIKTEST directory.

Note  An auto test does not have to manage handles or connections if it uses the ODBC Test Handles test source.

An auto test contains one or more test cases, each of which tests some specific functionality. For example, an auto test for SQLAllocStmt might contain two test cases, one to call SQLAllocStmt with all combinations of valid and invalid arguments and one to call SQLAllocStmt repeatedly until the driver runs out of statement handles.

The BUILD program shipped with the ODBC SDK requires specified names for the source files for an auto test DLL.

The auto test must export the following functions, which are called by ODBC Test:

•	AutoTestName   This function returns the name of the auto test and the number of test cases it includes. ODBC Test displays the auto test name in the Manage Auto Tests, Manage Groups, and Run Auto Test dialog boxes.

•	AutoTestDesc   This function returns the name and description of a specific test case. ODBC Test displays the test case name and description in the Run Auto Tests dialog box.

•	AutoTestFunc   This function invokes the auto test for a specific test source. Information about the test source and a bit array of the test cases to execute are passed to the auto test in a structure created by ODBC Test.

An auto test can call the following two functions in GATORTST.DLL (on Windows 3.1) or GTRTST32.DLL (on Win32s or Windows NT):

•	szLogPrintf   An auto test calls this function to log test results and other information to the screen and the log file.

•	szMessageBox   An auto test calls this function to display a message box. This function encapsulates the MessageBox function in the Windows API. Unlike the MessageBox function, it accepts a format string and a list of arguments with which it constructs a string to pass to MessageBox.


The Quick Test Sample

You can use the Quick Test (\ODBCSDK\SAMPLES\QUIKTEST\QUIKTEST.C) as a starting point for both writing your own auto tests and testing your driver. The Quick Test calls each ODBC function and verifies that it returns the expected code. Next, it calls SQLError until that function returns SQL_NO_DATA_FOUND, verifying that the expected SQLSTATEs are returned. Finally, for some functions, it checks if the function returns the expected data.

Note  The Quick Test is not an ODBC acceptance or compliance test. It is a starting point for your testing.


Building an Auto Test

To build an auto test DLL from code you have written, change your directory to \ODBCSDK\SAMPLES\QUIKTEST and use the BUILD.EXE program:

BUILD tstname [options]

where tstname is the base name of your .C file and options are one or more of the following:

Option	Meaning
-16 or -32	Build a 16- or 32-bit DLL. The default is -16.
-a	Build a DLL for each .C file.
-clean	Build all targets, even if the targets are not out of date with respect to their dependents.
-debug or -nodebug	Generate debugging information (-debug) or not (-nodebug). The default is -debug.
-o filename	Create a makefile in filename that does not reference environment variables. When the -o option is specified, BUILD.EXE does not run the make utility.
-?, -help	Display usage information.
For example, to build all the component files into a 16-bit nodebug version of the Quick Test, type:

build quiktest -nodebug -clean

Required Files

To build an auto test, BUILD.EXE needs the following files:

File Name	Description
AUTOTEST.H	Include file containing the constants and prototypes required to build an auto test DLL. All auto tests must include this file.
BUILD.INI	Initialization file for BUILD.EXE. For more information, see the "BUILD.INI File" section.
DLLSTUB.C	Source file containing the library entry points for 16- and 32-bit DLLs.
MAKEFILE	Makefile for auto test DLLs.
tstname.C tstname1.C tstname2.C	Source files. Only tstname.C is required. However, if your auto test requires additional source files, the MAKEFILE makefile requires that they are named tstname1.C and tstname2.C.
tstname.H	Optional include file.
tstname.RC	Optional resource file.
BUILD.INI File

The BUILD.INI file contains a single section, [Build Opts], that contains the following keywords:

Keyword	Value
BLDNAME	Name of the make utility to use. This value cannot include a directory name; the make utility must be in the current path.
CLEANOPT	The flag to pass the make utility specified with the BLDNAME keyword to force a clean compile. For example, this is -a for NMAKE.
DEFAULTS	Default values for the BUILD.EXE command line. For example, to compile a 32-bit nodebug DLL, this would be -32 -nodebug. Values specified on the command line override values specified with this keyword.
INCDIR	The directory containing the tstname.H include file.
OBJDIRDBGN	The output directory for a nodebug version of the DLL.
OBJDIRDBGY	The output directory for a debug version of the DLL.
RCDIR	The directory containing the tstname.RC resource file.
SRCDIR	The directory containing the tstname.C, tstname1.C, and tstname2.C source files.
Environment Variables

BUILD.EXE creates the following environment variables from the values specified in the BUILD.INI file and the BUILD command line. The MAKEFILE makefile refers to these environment variables.

Note  If your make utility cannot use environment variables, run BUILD with the -o option to generate a makefile that does not reference environment variables.

Environment Variable	Description
ADDL1	"Y" if the tstname1.C file is found in the SRCDIR directory; otherwise, "N".
ADDL2	"Y" if the tstname2.C file is found in the SRCDIR directory; otherwise, "N".
DEBUG	"N" if the -nodebug option was specified; otherwise, "Y".
HFILE	"Y" if the tstname.H file is found in the INCDIR directory; otherwise, "N".
INCDIR	The value of the INCDIR keyword in the BUILD.INI file.
OBJDIRDBGN	The value of the OBJDIRDBGN keyword in the BUILD.INI file.
OBJDIRDBGY	The value of the OBJDIRDBGY keyword in the BUILD.INI file.
RCDIR	The value of the RCDIR keyword in the BUILD.INI file.
RCFILE	"Y" if the tstname.RC file is found in the RCDIR directory; otherwise, "N".
SRCDIR	The value of the SRCDIR keyword in the BUILD.INI file.
TSTNM	The value of tstname on the BUILD command line.
WIN32	"Y" if the -32 option was specified; otherwise, "N".


Creating Test Sources

A test source is an ODBC data source and, optionally, all the information necessary to connect silently to that data source. Generally, auto tests are run as a background task — either overnight or on a separate machine — so they should be able to connect to a data source without prompting you for connection information. The ODBC Test Handles test source, which uses the connection and statement handles from the current connection, is always available.

 ( [image]) 	To create a test source

1.	In ODBC Test, choose Manage Test Sources from the Tools menu. ODBC Test displays the Manage Test Sources dialog box.

2.	Choose the New button, type the name of your test source in the Test Source box, and choose the OK button.

3.	Select the data source you want to access from the DSN list. If there are no data sources in the list, you can create them with the ODBC Administrator. For more information, see the Microsoft ODBC SDK Guide.

4.	If your data source requires a user and password, type the user ID in the UID box and the password in the PWD box.

Caution  The password is stored in the \WINDOWS\GATOR.INI file (or the \WINNT\GATOR32.INI file on Windows NT) in unencrypted form. Because of this, you may want to create special data sources and passwords for use with ODBC Test or use only the ODBC Test Handles test source.

5.	If your auto tests use SQLDriverConnect to connect to data sources, and the data source requires any other keywords and attribute values, type these as a connection string in the Keywords box. For example, to specify the Employee database and the DBNMP3.DLL network library, you might type the keywords:

DATABASE=Employee;NetLib=DBNMP3

6.	Choose the Close button.

You can also modify or delete test sources with the Manage Test Sources dialog box.


Installing Auto Tests

ODBC Test cannot automatically recognize which DLLs on your system are auto tests. For this reason, you must install an auto test before you can include it in a test group or run it.

 ( [image]) 	To install an auto test

1.	In ODBC Test, choose Manage Auto Tests from the Tools menu. ODBC Test displays the Manage Auto Tests dialog box.

2.	The Available list lists all DLLs in the \ODBCSDK\BIN directory. To install auto tests from a different directory, choose the From button and select that directory.

3.	Select the auto test to install from the Available list and choose the Add button. ODBC Test displays the name of the auto test.

4.	Choose the Close button.

Note  If you rebuild an auto test, you do not need to reinstall it. Replace the old auto test DLL with the new auto test DLL while ODBC Test is not running.

You can also remove auto tests with the Manage Auto Tests dialog box.


Creating Test Groups

To easily run related auto tests, you can group auto tests together. For example, you might want to create a test group of auto tests for SQLBindCol, SQLGetData, and SQLFetch. An auto test can be included in any number of test groups.

You are not required to create any test groups; all auto tests are automatically included in the All test group.

 ( [image]) 	To create a test group

1.	In ODBC Test, choose Manage Groups from the Tools menu. ODBC Test displays the Manage Groups dialog box.

2.	Choose the New button, type the name of the test group in the Group box, and choose the OK button.

3.	The Available list lists all installed auto tests by name. For information about how to install auto tests, see the previous section.

4.	Select an auto test to add to the test group from the Available list and choose the Add button. ODBC Test moves the auto test from the Available list to the Installed list. Continue to add auto tests to the group until the group contains all of the auto tests that you want.

5.	Choose the Close button.

You can also use the Manage Auto Tests dialog box to add or remove auto tests from an existing test group and delete test groups. Removing an auto test from a test group or deleting a test group that contains an auto test does not affect the auto test; it remains installed in ODBC Test.


Running Auto Tests

After you have created and installed auto tests and created test sources, you can select the test cases you want to run and the test sources you want to run them against.

 ( [image]) 	To run one or more auto tests

1.	In ODBC Test, choose Run Auto Tests from the Tools menu. ODBC Test displays the Run Auto Tests dialog box.

2.	Select the test cases you want to run from the Tests list.

The Tests list shows the test cases in an heirarchical structure: groups contain auto tests and auto tests contain test cases. To expand or collapse how much of the structure is shown, click on the plus or minus sign beside each group or auto test name. You can select test cases in the following ways:

•	By Test Group   Choose the test group name to select all test cases in all auto tests in a group. For example, to select all test cases in all installed auto tests, choose the All group name.

•	By Auto Test   Choose the auto test name to select all test cases in an auto test.

•	By Test Case   Choose the test case name to select an individual test case.

To unselect a test case or cases, click on the highlighted test group name, auto test name, or test case name with the mouse or press spacebar.

You can save the list of test cases, or run list, you have selected by clicking the Run Lists button and clicking the Save As button. Later, you can select the same test cases by selecting the run list.

3.	Select the test sources from the Test Sources dialog box that you want to run the test cases against. When ODBC Test runs the auto tests, it will run each selected test case against each selected test source.

4.	Select where you want the auto tests to log output:

•	Log File   Log output to the file AUTO.LOG in the current directory. To use a different log file, choose the Log File button. In the Log File dialog box, you can also specify whether to append to or replace the log file.

•	Screen   Log output to the Output window in ODBC Test.

If neither Log File nor Screen is selected, the tests will not log any information. ODBC Test always displays a list in the Output window of which tests were run and how many errors occurred.

5.	Select the runtime options you want to use:

•	Debug   Determines whether the fDebug flag in the SERVERINFO structure is set to TRUE or FALSE. What a test does when fDebug is TRUE depends on how the test was written.

•	Isolate Tests   Determines whether AutoTestFunc is called once for each selected test case in an auto test (the tests are isolated) or once for the auto test. If AutoTestFunc is called once for each test case, only one bit in the rglMask bit mask in the SERVERINFO structure is set each time it is called; if it is called once for the auto test, a bit is set in rglMask for each selected test case.

•	Cursor Library   Determines the value of the vCursorLib variable in the SERVERINFO structure:

Check Box	vCursorLib Value
Cleared	SQL_CUR_USE_DRIVER
Filled	SQL_CUR_USE_IF_NEEDED
Selected	SQL_CUR_USE_ODBC
How vCursorLib is used depends on how the test was written; it was intended to be used with the SQL_ODBC_CURSORS option in SQLSetConnectOption.

6.	Choose the OK button. ODBC Test runs each selected test case against each selected test source.


Auto Test Function Reference

This section describes the three functions that each auto test DLL must contain:

AutoTestName

AutoTestDesc

AutoTestFunc


AutoTestName

Description

AutoTestName returns the name of the auto test and the number of test cases it contains.

C Prototype

BOOL EXTFUN AutoTestName(
LPSTR szName, /* Output:  Auto test name */
UINT FAR * piTestCases), /* Output:  Number of test cases */

Arguments

szName

The name of the auto test, such as "SQLAllocStmt Tests," is returned in the szName argument. This name must not exceed AUTO_MAX_TEST_NAME characters.

piTestCases

The number of test cases in the auto test is returned in the piTestCases argument.

Return Values

TRUE if the auto test name is copied (with or without truncation) to szName and the number of test cases in the auto test is copied to piTestCases. Otherwise, FALSE.

Comments

ODBC Test calls this function to determine the name of the auto test and the number of test cases it contains.

Code Example

The following code example shows a simple AutoTestName function:

BOOL EXTFUN AutoTestName(LPSTR szName, UINT FAR * iTestCases);
{
/* The returned name is shorter than AUTO_MAX_TEST_NAME. */
lstrcpy(szName, "SQLAllocStmt Tests");
*iTestCases = 10;
return TRUE;
}


AutoTestDesc

Description

AutoTestDesc returns the name and description of the specified test case.

C Prototype

BOOL EXTFUN AutoTestDesc(
UWORD iTest, /* Input:  Test case number */
LPSTR szName, /* Output:  Test case name */
LPSTR szDesc); /* Output:  Test case description */

Arguments

iTest

The number of the test case. Test cases are numbered sequentially from 1 to the number of test cases in the auto test.

szName

The name of the test case is returned in the szName argument. This name must not exceed AUTO_MAX_TESTCASE_NAME characters.

szDesc

The description of the test case is returned in the szDesc argument. This description must not exceed AUTO_MAX_TESTCASE_DESC characters.

Return Values

TRUE if the test number was valid, the test case name is copied to szName, and the test case description is copied to szDesc. Otherwise, FALSE.

Comments

ODBC Test calls this function to determine the name and description of a test case. It displays this information when the user is selecting the test cases to run.

Code Example

The following code example shows a simple AutoTestDesc function:

#define NumCases(s) (sizeof(s) / sizeof(s[0]))

struct {
LPSTR szName;   /* Test case name        */
LPSTR szDesc;   /* Test case description */
} TestInfo[] = {
/* szName                    szDesc                                   */
/* ------------------        ---------------------------------------- */
   "Valid connection",       "Call SQLConnect normally.",
   "IM002: No DSN",          "Call SQLConnect with no DSN or default.",
   "IM004: Bad SQLAllocEnv", "Make driver's SQLAllocEnv fail."
};

BOOL EXTFUN AutoTestDesc(UWORD iTest, LPSTR szName, LPSTR szDesc);
{
if (iTest >= NumCases(TestInfo))
return FALSE;
lstrcpy(szName, TestInfo[iTest-1].szName);
lstrcpy(szDesc, TestInfo[iTest-1].szDesc);
return TRUE;
}


AutoTestFunc

Description

AutoTestFunc runs one or more test cases in an auto test.

C Prototype

void EXTFUN AutoTestFunc(
lpSERVERINFO lpServer); /* Input:  Test information */

Arguments

lpServer

The lpServer argument is a SERVERINFO structure containing information that includes the test cases to run, the test source to run them against, and how to run them. The SERVERINFO structure is defined in the AUTOTEST.H file. It has the following members:

hwnd

The handle of the window to which szLogPrintf and szMessageBox write screen output. hwnd is not used by AutoTestFunc.

szLogFile

The name of the log file to which szLogPrintf writes file output. szLogFile is not used by AutoTestFunc.

henv, hdbc, hstmt

If the test source is not "ODBC Test Handles," these are null and the auto test must allocate its own handles. If the test source is "ODBC Test Handles," these are the currently selected environment, connection, and statement handles; if there are no currently selected environment, connection, and statement handles, these are null.

szSource

The name of the test source.

szValidServer0

The name of the data source associated with the test source. The auto test connects to this data source. szValidServer0 is a null pointer if the test source is "ODBC Test Handles."

szValidLogin0

The user ID associated with the test source. The auto test uses this to connect to the data source. szValidLogin0 is a null pointer if the test source is "ODBC Test Handles."

szValidPassword0

The password associated with the test source. The auto test uses this to connect to the data source. szValidPassword0 is a null pointer if the test source is "ODBC Test Handles."

Caution  The password is stored in the \WINDOWS\GATOR.INI file (or the \WINNT\GATOR32.INI file on Windows NT) in unencrypted form. Because of this, you may want to create special data sources and passwords for use with ODBC Test or use only the ODBC Test Handles test source.

szKeywords

The keyword-value pairs associated with the test source. The auto test uses these to connect to the data source. szKeywords is a null pointer if the test source is "ODBC Test Handles."

rglMask

A bit mask in which each bit represents a test case to be run. The auto test uses the GETBIT macro from the AUTOTEST.H file to determine which bits are set.

failed

Included for backwards compatibility with ODBC Test 1.0.

cErrors

The number of errors that occurred in all test cases run by AutoTestFunc. ODBC Test displays this number after it has called AutoTestFunc.

fDebug

TRUE if debugging was specified in the Run Auto Tests dialog box; otherwise, FALSE. What AutoTestFunc does when fDebug is TRUE depends on how it was written.

fScreen

TRUE if the Screen box was selected in the Run Auto Tests dialog box; otherwise, FALSE. fScreen is used by the szLogPrintf function in ODBC Test to determine whether to log output to the screen; it is not used by AutoTestFunc.

fLog

TRUE if the Log File box was selected in the Run Auto Tests dialog box; otherwise, FALSE. fLog is used by the szLogPrintf function in ODBC Test to determine whether to log output to the log file; it is not used by AutoTestFunc.

fIsolate

If the Isolate Tests box was selected in the Run Auto Tests dialog box, this will be TRUE and a single bit will be set in the rglMask member. Otherwise, FALSE.

vCursorLib

SQL_CUR_USE_IF_NEEDED, SQL_CUR_USE_ODBC, or SQL_CUR_USE_DRIVER, depending on the setting of the Cursor Library box in the Run Auto Tests dialog box. The auto test can pass this value to SQLSetConnectOption for the SQL_ODBC_CURSORS option.

hLoadedInst

The auto test DLL instance handle.

szBuff

Used by szLogPrintf to buffer output until it receives the string " \r\n". szBuff is not used by AutoTestFunc.

cBuff

Used by szLogPrintf to count the output in szBuff. cBuff is not used by AutoTestFunc.

Return Values

None.

Comments

ODBC Test calls this function to run one or more test cases in the auto test. If the szSource member of the SERVERINFO structure specified in the lpServer argument is ODBC Test Handles, AutoTestFunc uses the handles specified in the henv, hdbc, and hstmt members. Otherwise, it connects to the data source specified in the szValidServer0 member using the information in the szValidLogin0, szValidPassword0, and szKeywords members.

AutoTestFunc runs the test cases specified in the rglMask member, using the GETBIT macro to determine which bits are set. It calls szLogPrintf to send output to the screen or log file and stores the total number of errors encountered in the cErrors member.

Code Example

The following code example shows a simple AutoTestFunc function and supporting function:

void EXTFUN AutoTestFunc(lpSERVERINFO lpServer)
{
UINT iCase;

InitTest(lpServer);

/* Loop through the rglMask bitmask with the GETBIT macro to      */
/* determine the test cases to run. NumTests is the count of test */
/* cases returned by AutoTestName.                                */

for (iCase = 1; iCase < NumTests; iCase++)
if (GETBIT(lpServer->rglMask, iCase))
RunTestCase(lpServer, iCase);

EndTest(lpServer);
}

void INTFUN RunTestCase(lpSERVERINFO lpServer, UINT iCase);
{
szLogPrintf(lpServer, FALSE, "Running test case %u.\r\n", iCase);

/* Run the test case specified by iCase. */

szLogPrintf(lpServer, FALSE, "Test case %u finished.\r\n", iCase);
}


ODBC Test Function Reference

This section describes the functions in ODBC Test (in GATORTST.DLL on Windows 3.1 or GTRTST32.DLL on Win32s or Windows NT) that an auto test calls to log output and display screen messages:

szLogPrintf

szMessageBox


szLogPrintf

Description

szLogPrintf prints output from an auto test on the screen, in a log file, or both.

C Prototype

BOOL szLogPrintf(
lpSERVERINFO lpServer, /* Input:  Test information */
BOOL fForce, /* Input:  Force screen output */
LPSTR szFmt, /* Input:  Format string */
...); /* Input:  Arguments for format string */

Arguments

lpServer

The lpServer argument is a SERVERINFO structure containing information that includes the output window handle, the log file name, and where to send output. The SERVERINFO structure is defined in the AUTOTEST.H file. For information about the members of the structure, see the lpServer argument in AutoTestFunc.

When AutoTestFunc calls szLogPrintf, it should pass the value of lpServer that was passed to it by ODBC Test.

fForce

If TRUE, szLogPrintf writes the output to the screen regardless of the fScreen member of the lpServer argument. If FALSE, szLogPrintf writes the output to the screen only if the fScreen member of the lpServer argument is TRUE.

szFmt

A null-terminated format string compatible with the wsprintf function.

...

Arguments for the format string specified in the szFmt argument.

Return Values

TRUE if the function successfully logged the output; otherwise, FALSE. If FALSE is returned, a message box appears that allows the user to turn off logging.

Comments

Auto tests should call this function to log all output from tests.

Code Example

See AutoTestFunc.


szMessageBox

Description

szMessageBox formats a string and displays it using the MessageBox function in the Windows API.

C Prototype

int szMessageBox(
HWND hwnd, /* Input:  Parent window handle */
UINT style, /* Input:  Style of message box */
LPSTR szTitle, /* Input:  Title of message box */
LPSTR szFmt,	 /* Input:  Format string */
...); /* Input:  Arguments for format string */

Arguments

hwnd

The parent window handle to be passed to MessageBox. This should be the hwnd member of the lpServer structure passed to AutoTestFunc.

style

The style of the message box. For more information, see the fuStyle argument of the MessageBox function in the Windows API.

szTitle

The title of the message box. For more information, see the lpszTitle argument of the MessageBox function in the Windows API.

szFmt

A null-terminated format string compatible with the wsprintf function.

...

Arguments for the format string specified in the szFmt argument.

Return Values

szMessageBox returns the value returned by MessageBox.

Comments

Auto tests can call this function to display a message box. Because most auto tests are designed to be run without user interaction, this function should only be called when user interaction is required. To routinely log output, an auto test should call szLogPrintf.

Code Example

The following code example shows how AutoTestFunc might use szMessageBox to tell the user how to use a dialog box displayed by SQLDriverConnect:

#define CONN_STR_LEN 100
UCHAR szConnStrIn[CONN_STR_LEN], szConnStrOut[CONN_STR_LEN];
SWORD cbConnStrOut;

/* szTestName is the test name returned by AutoTestName */
szMessageBox(lpServer->hwnd,
             MB_ICONINFORMATION | MB_OK,
             szTestName,
             "Click the Cancel button in the next dialog box.");

lstrcpy(szConnStrIn, "DSN=");
lstrcat(szConnStrIn, lpServer->szValidServer0);
lstrcat(szConnStrIn, "\0");
SQLDriverConnect(hdbc, lpServer->hwnd,
                 szConnStrIn, lstrlen(szConnStrIn),
                 szConnStrOut, CONN_STR_LEN, *cbConnStrOut,
                 SQL_DRIVER_PROMPT);


Tool Reference

Tools are menu items that help you configure ODBC Test, such as the level of errors to report or whether menu items for functions the driver does not support are disabled.

User Options

Rowset Options

Trace


User Options

The User Options item on the Tools menu displays the User Options dialog box, which controls the ODBC Test user interface. It also controls how ODBC Test checks the result of function calls. The options in this dialog box do not affect auto tests.

Driver Dependent Menus  If selected, ODBC Test disables those menu items not supported by the driver. For example, if the driver does not support SQLDescribeParam, ODBC Test disables the SQLDescribeParam menu item.

Automatic Error Checking  If selected, ODBC Test calls the Error All function tool after each ODBC function is called.

Null Terminator Checking  If selected, ODBC Test checks to see that the driver null-terminates all returned character values.

Buffer Overwrite Checking  If selected, ODBC Test fills output buffers with the pattern 0xCA before calling a function. After calling the function, it performs the following tests:

•	Checks that the driver writes in the buffer when the function returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO. For example, if SQLGetInfo returns SQL_SUCCESS, ODBC Test checks that the driver wrote in the rgbInfoValue buffer.

•	Checks that the driver does not write in the buffer when the function returns SQL_NO_DATA_FOUND, SQL_ERROR, SQL_INVALID_HANDLE, SQL_STILL_EXECUTING, or SQL_NEED_DATA. For example, if SQLGetInfo is called with an invalid fInfoType, ODBC Test checks that no data was written in the rgbValue buffer.

•	Checks that the driver does not write past the end of the buffer. ODBC Test allocates an extra byte at the end of the buffer before calling the function. After calling the function, it checks whether the byte was overwritten. For example, if the cbInfoValueMax argument in SQLGetInfo is 10 and the data to be returned is 15 bytes long, ODBC Test checks that only 10 bytes were written in the rgbInfoValue buffer.

Note  ODBC Test cannot check if the driver writes past the end of an output buffer if that buffer is an array or structure.

Version Numbers  If selected, ODBC Test displays the version number of option values in dialog boxes, such as the values for the fInfoType argument in SQLGetInfo.

Always Use Cursor Library  If selected, ODBC Test calls SQLSetConnectOption with the SQL_ODBC_CURSORS option and the value SQL_CUR_USE_ODBC for each newly allocated connection handle.

Default Buffer Length  Specifies the default length of output buffers, such as szConnStrOut in SQLDriverConnect or pvParam in SQLGetStmtOption.

Argument Display Length  Specifies the default length of arguments displayed as output by the W2 logging level.

Max Bind Col All Length  Specifies the maximum length of the rgbValue buffer when the Bind Col All function tool is used.

Logging Level  Specifies the level of error output ODBC Test generates.

Error Logging Level	Error Output
W0	Return codes and ODBC Test error messages (TST0xxx)
W1	W0 output and ODBC Test warning messages (TST1xxx)
W2	W1 output and function name and argument values
Font Button  Displays the Choose Font dialog box in which you can specify the font and point size to be used by all text in the general output, connection, and rowset windows.


Rowset Options

The Rowset Options item on the Tools menu displays the Rowset Options dialog box, which controls the values displayed in rowset windows and how rowset buffers are allocated.

Status Values  If selected, ODBC Test displays the value of the rgfRowStatus array specified in SQLExtendedFetch at the start of each row in the rowset window.

Length Values  If selected, ODBC Test displays the value of the pcbValue buffer bound with SQLBindCol at the end of each column in the rowset window.

Column Names  If selected, ODBC Test displays the name of each column in the rowset window.

Reserved Rows  Specifies the number of extra rows to allocate in the rowset buffers used with SQLExtendedFetch and SQLSetPos. These rows are generally used for add buffers.


Trace

The Trace item on the Tools menu turns tracing on and off. If tracing is currently disabled, choosing this menu item enables tracing. ODBC Test displays a dialog box in which you can specify a trace file and whether the Driver Manager overwrites or appends to that trace file. It is equivalent to calling SQLSetConnectOption with the SQL_OPT_TRACE and SQL_OPT_TRACE_FILE options to enable tracing and specify a trace file. While tracing is enabled, ODBC Test places a check mark beside the Trace menu item.

If tracing is currently enabled, this menu item disables tracing. It is equivalent to calling SQLSetConnectOption with the SQL_OPT_TRACE option to disable tracing.


Function Tool Reference

Function tools are menu items that call a group of related ODBC functions or help you use an ODBC function. For example, Full Disconnect calls SQLDisconnect, SQLFreeConnect, and SQLFreeEnv; Fill Param displays a dialog box in which you enter parameter values. Function tools are listed at the bottom of the Connect, Statement, Results, and Misc menus beneath a separator line.

Note  To abort those function tools that run in a loop, press the ESC key.

Bind Col All (Results Menu)

Data Sources All (Connect Menu)

Describe Col All (Results Menu)

Drivers All (Connect Menu)

Errors All (Misc Menu)

Fetch All (Results Menu)

Fill Param (Statement Menu)

Full Connect (Connect Menu)

Full Disconnect (Connect Menu)

Get Data All (Results Menu)

Get Data Row (Results Menu)

Get Functions All (Misc Menu)

Get Info All (Connect Menu)

Show Bound Cols (Results Menu)

Show Params (Statement Menu)

Update Cell (Results Menu)


Bind Col All (Results Menu)

The Bind Col All function tool binds all the columns in a result set. It:

1.	Calls SQLFreeStmt with fOption set to SQL_UNBIND to unbind any previously bound columns.

2.	Calls SQLNumResultCols to determine the number of columns in the result set.

3.	Calls SQLDescribeCol for each column in the result set to determine the data type and precision of the column. Based on on the precision, it allocates a character buffer of up to the number of bytes specified with the Max Bind All Buffer box in the Rowset Options dialog box.

4.	Calls SQLBindCol for each column in the result set to bind the column to a SQL_C_CHAR buffer.


Data Sources All (Connect Menu)

The Data Sources All function tool displays a list of all available data sources. It:

1.	Calls SQLDataSources with fDirection set to SQL_FETCH_FIRST.

2.	Calls SQLDataSources with fDirection set to SQL_FETCH_NEXT until it returns SQL_NO_DATA_FOUND.


Describe Col All (Results Menu)

The Describe Col All function tool displays the column name, type, precision, scale, and nullability of each column in the result set on the current hstmt. It:

1.	Calls SQLNumResultCols to determine the number of columns in the result set.

2.	Calls SQLDescribeCol for each column in the result set.


Drivers All (Connect Menu)

The Drivers All function tool displays a list of all available drivers and their attributes. It:

1.	Calls SQLDrivers with fDirection set to SQL_FETCH_FIRST.

2.	Calls SQLDrivers with fDirection set to SQL_FETCH_NEXT until it returns SQL_NO_DATA_FOUND.


Errors All (Misc Menu)

The Error All function tool displays all pending errors. It:

1.	Calls SQLError with the current hstmt until SQLError returns SQL_NO_DATA_FOUND.

2.	Calls SQLError with the current hdbc until SQLError returns SQL_NO_DATA_FOUND.

3.	Calls SQLError with the current henv until SQLError returns SQL_NO_DATA_FOUND.


Fetch All (Results Menu)

The Fetch All function tool fetches all remaining rows in all pending result sets on the current hstmt. If any columns were bound, after Fetch All has completed these will contain the values from the last row of the last result set. The Fetch All function tool:

1.	Calls SQLGetFunctions to determine if the driver supports SQLMoreResults.

2.	Calls SQLFetch until it returns SQL_NO_DATA_FOUND.

3.	If the driver supports it, calls SQLMoreResults. If SQLMoreResults returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, the Fetch All function tool returns to step 2. Otherwise, it stops.


Fill Param (Statement Menu)

The Fill Param function tool displays a dialog box in which you can enter the values of the rgbValue and pcbValue buffers for a parameter specified with SQLBindParameter.

If the parameter is a data-at-execution parameter, you can choose the SQL_LEN_DATA_AT_EXEC check box; if this check box is selected, the value of pcbValue is used as the length parameter of the SQL_LEN_DATA_AT_EXEC macro.

If you have called SQLParamOptions with crow greater than 1 to specify that you will pass an array of parameters, you can use the Element box to specify which element of the parameter array you are entering a value for. When you change the value in the Row box, ODBC Test stores the current values of rgbValue and pcbValue boxes in the previously specified element of the parameter arrays.


Full Connect (Connect Menu)

The Full Connect function tool completely connects to a data source. It:

1.	Calls SQLAllocEnv (if necessary).

2.	Calls SQLAllocConnect.

3.	Calls SQLSetConnectOption with the SQL_ODBC_CURSORS option and the value SQL_CUR_USE_ODBC if the Always Use Cursor Library box in the User Options dialog box is selected.

4.	Calls SQLDriverConnect with the szConnStrIn argument set to a null pointer and the fDriverCompletion argument set to SQL_DRIVER_COMPLETE. If SQLDriverConnect is not supported, it invokes SQLConnect with the given connection information.

5.	Calls SQLAllocStmt.


Full Disconnect (Connect Menu)

The Full Disconnect function tool completely disconnects from the data source on the current hdbc. It:

1.	Calls SQLDisconnect.

2.	Calls SQLFreeConnect.


Get Data All (Results Menu)

The Get Data All function tool attempts to retrieve and display the data in every row and column in the result set on the current hstmt. The Get Data All function tool may not be able to display data for bound columns or columns that occur before the last bound column. It:

1.	Calls SQLGetFunctions to determine if the driver supports SQLMoreResults.

2.	Calls SQLNumResultCols.

3.	Calls SQLDescribeCol to retrieve the name and precision of each column in the result set. Based on the precision, it allocates an output buffer of up to 65,535 bytes for each column.

4.	Calls SQLFetch.

5.	Calls SQLGetData for each column in the result set with an fCType argument of SQL_C_CHAR. The Get Data All function tool only calls SQLGetData once for each column. If the data is longer than 65,535 bytes, <trunc> is displayed before the first byte of data in the buffer.

6.	Repeats steps 4 and 5 until SQLFetch returns SQL_NO_DATA_FOUND.

7.	If the driver supports it, calls SQLMoreResults. If SQLMoreResults returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, the Get Data All function tool returns to step 2. Otherwise, it calls SQLFreeStmt with fOption set to SQL_CLOSE to clear the result set.


Get Data Row (Results Menu)

The Get Data Row function tool retrieves and displays the data for every column in the current row of the result set on the current hstmt. You must call SQLFetch or SQLExtendedFetch before calling the Get Data Row function tool. The Get Data Row function tool:

1.	Calls SQLNumResultCols.

2.	Calls SQLDescribeCol to retrieve the name and precision of each column in the result set. Based on the precision, it allocates an output buffer of up to 65,535 bytes for each column.

3.	Calls SQLGetData for each column in the result set with an fCType argument of SQL_C_CHAR. The Get Data Row function tool only calls SQLGetData once for each column. If the data is longer that 65,535 bytes, <trunc> is displayed before the first byte of data in the buffer.


Get Functions All (Misc Menu)

The Get Functions All function tool displays whether each ODBC function is supported. It:

•	Calls SQLGetFunctions for each ODBC function.


Get Info All (Connect Menu)

The Get Info All function tool displays the return value of each information type defined for SQLGetInfo in ODBC 2.0. It:

•	Calls SQLGetInfo for each value of fInfoType.


Show Bound Cols (Results Menu)

The Show Bound Cols function tool displays the binding information and the value of each buffer bound to a column with SQLBindCol. If the rowset size (specified with the SQL_ROWSET_SIZE statement option) is greater than 1, you must call SQLExtendedFetch to view the rest of the rowset. The Show Bound Cols function tool does not call any ODBC functions.


Show Params (Statement Menu)

The Show Params function tool displays the value of each buffer bound to a parameter marker with SQLBindParameter. If a successful call to SQLParamOptions has been made, it also displays the pirow value. It does not call any ODBC functions.


Update Cell (Results Menu)

The Update Cell function tool displays a dialog box in which you can specify the value of the rgbValue and pcbValue buffers of the current cell in the current rowset window. The dialog box also displays the values of the other arguments from the call to SQLBindCol used to bind the column.


Function Reference

Functions are menu items that call ODBC functions. When you select a function from an ODBC Test menu, ODBC Test displays a dialog box that has one control for each argument in the function. When you choose the OK button in the dialog box, ODBC Test executes the function using the values specified for each argument.

This section describes any special characteristics of the dialog boxes that ODBC Test displays for the ODBC functions. The dialog boxes for many functions are straightforward and do not require further explanation. For information about each ODBC function, see the Microsoft ODBC SDK Programmer's Reference.

SQLAllocConnect (Connect Menu)

SQLAllocEnv (Connect Menu)

SQLAllocStmt (Statement Menu)

SQLBindCol (Results Menu)

SQLBindParameter (Statement Menu)

SQLColAttributes (Results Menu)

SQLExtendedFetch (Results Menu)

SQLFreeConnect (Connect Menu)

SQLFreeStmt (Statement Menu)

SQLGetConnectOption (Connect Menu)

SQLGetInfo (Connect Menu)

SQLGetStmtOption (Statement Menu)

SQLSetConnectOption (Connect Menu)

SQLSetStmtOption (Statement Menu)


SQLAllocConnect (Connect Menu)

After ODBC Test successfully calls SQLAllocConnect, it creates a connection window. If the Always Use Cursor Library box in the User Options dialog box is selected, ODBC Test also calls SQLSetConnectOption with the SQL_ODBC_CURSORS option and the value SQL_CUR_USE_ODBC.


SQLAllocEnv (Connect Menu)

You must allocate an henv before you can execute any other ODBC functions through the ODBC Test menu. You can allocate an henv by executing SQLAllocEnv or choosing Full Connect on the Connect menu. If you try to allocate a second henv without freeing the first, ODBC Test displays an error message. You do not need to allocate an henv before running any auto tests.


SQLAllocStmt (Statement Menu)

After ODBC Test successfully calls SQLAllocStmt, it adds the statement handle to the statement handle list of the current connection window.


SQLBindCol (Results Menu)

If the SQL_BIND_TYPE statement option specifies row-wise binding, SQLBindCol builds a structure containing elements for the rgbValue and pcbValue buffers. If you make multiple calls to SQLBindCol, each additional pair of elements is added to the end of the structure.


SQLBindParameter (Statement Menu)

Unless you want to specify a null pointer for the rgbValue argument, you must enter a value for it. You can change this value later with the Fill Param function tool. If you have data-at-exectution parameters, you must enter a valid value for rgbValue based on the fCType specified.

To bind the parameter to the address of a specific row and column in a bound rowset on another hstmt, set the parameter to <rowset values> in the rgbValue and pcbValue arguments. This activates the Rowset hdbc and Rowset hstmt list boxes, which enable you to specify the hdbc and hstmt of the bound rowset. The Row and Column text boxes allow you specify the row and column number, respectively.

If you have called SQLParamOptions with crow greater than 1 to specify that you will pass an array of parameters, ODBC Test places the values you enter for rgbValue and pcbValue arguments in the first element of the parameter arrays. You can enter values for the other elements of the parameter arrays with the Fill Param function tool.

SQLSetParam has been deprecated for ODBC 2.0. To call SQLSetParam in an ODBC 1.0 driver, call SQLBindParameter. The Driver Manager ignores the values for fParamType and cbValueMax and maps the remaining arguments into a call to SQLSetParam.

To emulate an ODBC 1.0 application calling SQLSetParam in an ODBC 2.0 driver, set fParamType to SQL_PARAM_INPUT_OUTPUT and cbValueMax to  −1 (which is the value of SQL_SETPARAM_VALUE_MAX).


SQLColAttributes (Results Menu)

If you enter an fDescType that is not recognized by ODBC Test, it is assumed to be a driver-specific descriptor type. So that ODBC Test can correctly display the value returned for this option, you must specify the value's C data type in the Description Type box. If the description type is SQL_C_ULONG, ODBC Test assumes the value is returned in the pfDesc argument; otherwise it assumes the value is returned in the rgbDesc argument.


SQLExtendedFetch (Results Menu)

After ODBC Test successfully calls SQLExtendedFetch it creates a rowset window.


SQLFreeConnect (Connect Menu)

After ODBC Test successfully calls SQLFreeConnect, it closes the current connection window.


SQLFreeStmt (Statement Menu)

After ODBC Test successfully calls SQLFreeStmt with the SQL_DROP option, it removes the statement handle from the statement handle list of the current connection window.


SQLGetConnectOption (Connect Menu)

The word "Conn:" prefixes the values in the fOption list to signify these are connection options (as opposed to statement options).

If you enter an fOption value that is not recognized by ODBC Test, it is assumed to be a driver-specific connection or statement option. So that ODBC Test can correctly display the value returned for this option, you must specify the value's C data type in the Parameter Type box.


SQLGetInfo (Connect Menu)

If you enter an fInfoType value that is not recognized by ODBC Test, it is assumed to be a driver-specific information type. So that ODBC Test can correctly display the value returned for this information type, you must specify the value's C data type in the Information Value Type box.


SQLGetStmtOption (Statement Menu)

If you enter an fOption value that is not recognized by ODBC Test, it is assumed to be a driver-specific statement option. So that ODBC Test can correctly display the value entered for this option, you must specify the value's C data type in the Parameter Type box.


SQLSetConnectOption (Connect Menu)

The word "Conn:" prefixes values in the fOption list that are connection options; the word "Stmt:" prefixes values that are statement options.

If you enter an fOption value that is not recognized by ODBC Test, it is assumed to be a driver-specific connection or statement option. So that ODBC Test can correctly display the value entered for this option, you must specify the value's C data type in the Parameter Type box.


SQLSetStmtOption (Statement Menu)

If you enter an fOption value that is not recognized by ODBC Test, it is assumed to be a driver-specific statement option. So that ODBC Test can correctly display the value entered for this option, you must specify the value's C data type in the Parameter Type box.


Error and Warning Messages

This section lists error and warning messages generated by ODBC Test. Self-explanatory messages such as "Disk Full" are not listed.

All error and warning messages have the following form:

TSTyxxx : message

where

y

indicates the message level. Zero indicates an error message and 1 indicates a warning message.

xxx

is the message number.

For example:

TST0001: The value of cbConnStrLen is less than 0 and not SQL_NTS= − 3

The following table lists the messages generated by ODBC Test. The values in italics are replaced by ODBC Test when it prints the error message. The value codes represents a list of return codes.

Message	Level	Description
TST0001	W0	The value of %s is less than 0 and not SQL_NTS=-3.
TST0002	W0	The value returned in %s does not match the length of string returned in %s.
TST0003	W0	The driver returned SQL_SUCCESS or SQL_SUCCESS_WITH_INFO but did not update %s.
TST0004	W0	Invalid return code '%s'. Valid return codes are codes.
TST0005	W0	Truncation implied but SQL_SUCCESS_WITH_INFO not returned, %s=%d. The value returned by the specified pcb parameter indicates that truncation occurred. However, SQL_SUCCESS_WITH_INFO was not returned from the driver.
TST0006	W0	The value %ld was not a valid named constant for %s. The value returned for the function named is not one of the legal values as documented in the Microsoft ODBC SDK Programmer's Reference. For example, SQLGetInfo should return either 0 or 1 for SQL_ODBC_SAG_CLI_COMPLIANCE.
TST0007	W0	The following set bits do not have a corresponding named constant: 0x%08lX A bit in the bitmask returned for the function named is not one of the legal values as documented in the Microsoft ODBC SDK Programmer's Reference. For example, SQLGetInfo should only set bits for SQL_LCK_NO_CHANGE, SQL_LCK_EXCLUSIVE, and SQL_LCK_UNLOCK for the information type SQL_LOCK_TYPES.
TST0008	W0	Cannot allocate more than %ld bytes of memory.
TST0009	W0	Buffer %s contained an invalid count byte value.
TST1001	W1	Buffer %s was not updated. Buffer checking has been enabled, but after the function call the named buffer was not updated.
TST1002	W1	Truncation implied by SQL_SUCCESS_WITH_INFO, %s=%d. The value returned by the specified pcb parameter indicates that a truncation ocurred, and SQL_SUCCESS_WITH_INFO was returned from the driver.
TST1003	W1	The message for SQLState "%s" is longer than SQL_MAX_MESSAGE_LENGTH − 1. The description of cbErrorMsgMax indicates that you should allocate no more than SQL_MAX_MESSAGE_LENGTH for an error returned from SQLError. This message indicates that the driver has returned a message which exceeds this limit. Since you should not expect this long of a message, this is a warning to the driver writer that the size of the message should be decreased.
TST1004	W1	Data needed for Parameter #%u Indicates the parameter that ODBC Test has identified as the next SQL_DATA_AT_EXEC parameter. ODBC Test bases this identification on the value of the rgbValue buffer specified in SQLBindParameter (or SQLBindCol when SQLSetPos is used) and returned by SQLParamData.
TST1005	W1	Highest bound column is %u. Returned by the Get Data All function tools when columns are bound. Some drivers cannot return data before this column.
TST1006	W1	A zero was received for %s indicating the driver does not support this function. In ODBC 2.0, SQLGetInfo returns 0 for integer-valued information types that do not apply to the driver or data source. ODBC Test displays this message when SQLGetInfo returns 0 for an information type for which there is no #define with a value of 0.
TST1007	W1	Since prgbValue was NULL, ODBC Test was unable to resolve the data type of the parameter. The data type will be set to SQL_C_CHAR by default.
TST1008	W1	Buffer %s was modified beyond indicated length.
TST1009	W1	Buffer %s was modified and should not have been.
TST1010	W1	Buffer %s contained an invalid count byte value.
TST1011	W1	Buffer %s is not properly null-terminated.
TST1012	W1	Buffer %s contains an embedded NULL.