Copyright: 1994 Microsoft Corporation. All rights reserved.


ODBC SDK 2.0 Samples Help File Contents
ODBC SDK 2.10 Samples Help File

The ODBC SDK version 2.10 includes the following sample programs:

Sample Name	Description	Filename
Admin Demo	Enables you to connect to a data source, execute SQL statements, run scripts, and perform other special tasks.	ADMNDEMO.EXE
C++ Demo	Demonstrates how C++ classes might be used to write a simple ODBC application.	CPPDEMO.EXE
Cursor Demo	Shows how to take advantage of the block cursor, scrolling, and positioned update and delete capabilities of the ODBC cursor library.	CRSRDEMO.EXE
Query Demo	Demonstrates multiple simultaneous connections using ODBC. It enables you to type any SQL query and browse the results.	QURYDEMO.EXE
Sample Driver	A C-language template provided as an aid for writing drivers. It illustrates how to write an ODBC driver. It also includes a source code template to help you write a driver-specific setup DLL that will work with both the ODBC Administrator and the Driver Setup Toolkit utility.	SAMPLE.DLL SAMPLE32.DLL
DLL Viewer / Translation Spy	DLL Viewer is a translation DLL configuration utility. It also displays all DLLs currently loaded in the system. Translation Spy intercepts and interprets information that is to be translated.	TRANSPEC.EXE TRNSLCHK.DLL
Visual Basic Demo	Demonstrates how a Visual Basic application could be written using ODBC. It also provides a complete list of function prototypes for the ODBC API.	VBDEMO.EXE


Admin Demo Contents

This file contains the following information:

What Admin Demo Demonstrates

Admin Demo Files

How to Build Admin Demo

How to Run Admin Demo

Admin Demo Menus

Pipes

SQL Batch Files


What Admin Demo Demonstrates

Admin Demo uses the ODBC API to enable you to connect to a data source, execute SQL statements, run scripts, and perform other special tasks. In addition, Admin Demo can list information (such as data types, functions, and general ODBC information) about the data source being used.

Note   Admin Demo is provided as a sample. It is not designed to replace proprietary DBMS tools, as there are some tasks that can only be done with DBMS-specific tools. Instead, Admin Demo and its source code are supplied as an example of how to write a general-purpose, ODBC-enabled application for performing system operations on different data sources.

FEATURES

CONNECTION WINDOWS

Admin Demo enables you to connect to multiple data sources. The only limits on connections are those imposed by each driver and the amount of memory available on the system. Each new connection creates a multiple-document interface (MDI) child connection window from which SQL statements can be executed.

INPUT AND OUTPUT WINDOWS

There are two windows in each connection window. The input (upper) window enables you to edit a file, enter new statements, and execute those statements. The output (lower) window is used to log error and diagnostic messages.

To toggle between the input and output windows, press the F6 key. If a results window is currently active, pressing F6 causes the cursor to activate the connection window which owns that results window.

RESULTS WINDOWS

The output from operations that produce result sets, such as executing SQL statements or invoking ODBC catalog functions, is displayed in a results window. Each results window is an MDI child window of the connection window in which the operation was performed. This means that disconnecting from a connection window closes all of the results windows created from that connection window.

LIMITATIONS OF ADMIN DEMO

Admin Demo is a useful sample application, but not a polished product. It is up to you to improve its performance and functionality. Some of the limitations you need to be aware of are listed as follows.

MAXIMUM ROWS FETCHED IN A RESULT SET: 1000

The maximum number of rows that can be fetched in a results set is 1000. Each fetched row is placed in a structure that is added to an owner-drawn list box. Because the operating system limits the number of elements in a list-box to 1000, Admin Demo cannot handle more records than this limit.

SIMPLISTIC MEMORY MANAGEMENT

The memory management scheme used in Admin Demo is also very limited. When Admin Demo needs memory, it calls GlobalAlloc. This is not the most efficient method, as it can cause memory fragmentation and poor performance.

NO ASYNCHRONOUS OPERATION

Admin Demo does not take advantage of the asynchronous capabilities of some ODBC drivers. It executes a query and fetches the results set synchronously, limiting performance for long queries.

OTHER LIMITATIONS

Maximum connections: limited by driver and memory

Maximum result sets: limited by user and memory

Maximum rowset buffer size: 64K


Admin Demo Files

FILES LOCATION

The Admin Demo source code resides in the \ODBCSDK\SAMPLES\ADMNDEMO directory. The 16-bit executable file ADMNDEMO.EXE resides in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

ADMNDEMO.C

Main module. Creates the main window and handles rudimentary functionality (such as displaying the About dialog box).

ADMNDEMO.DEF

Module definition file for Admin Demo.

ADMNDEMO.DLG

Dialog templates for Admin Demo.

ADMNDEMO.H

Prototypes and definitions for ADMNDEMO.C.

ADMNDEMO.ICO

Admin Demo icon.

ADMNDEMO.RC

Resource file for Admin Demo.

CHILD.H

Main structure for tracking connection window information (including ODBC handles).

CONNECT.ICO

Minimized connection window icon.

DIALOGS.C

Code for the catalog functions found under the Lists menu.

DIALOGS.H

Prototypes and definitions for DIALOGS.C.

ERRCHECK.C

Generic error-checking utility functions.

ERRCHECK.H

Prototypes and definitions for ERRCHECK.C.

EXECUTE.C

Executes ad hoc SQL statements and file scripts, as well as the Windows code for displaying result sets.

EXECUTE.H

Prototypes and definitions for EXECUTE.C.

INFO.C

Used to track informational items found under the Info menu.

INFO.H

Prototypes and definitions for INFO.C.

INI.C

Used to track .INI file information. These functions abstract access to the ADMNDEMO.INI file, making it more portable.

INI.H

Prototypes and definitions for INI.C.

MENU.C

Contains state-tracking code as well as the menu-enabling routines.

MENU.H

Prototypes and definitions for MENU.C.

RESULTS.C

Contains code for describing result sets, including all column information, data, and screen output attributes.

RESULTS.H

Prototypes and definitions for RESULTS.C.

RESULTS.ICO

Minimized result set icon.

STANDARD.C

A set of common functions used by several different modules.

STANDARD.H

Prototypes and definitions for STANDARD.C.

STRINGS.H

String ids for resource strings found in ADMNDEMO.RC.


How to Build Admin Demo

The file \ODBCSDK\SAMPLES\ADMNDEMO\MAKEFILE is set up for compilation within both 16- and 32-bit environments using a Microsoft or Microsoft-compatible C compiler. Use the \ODBCSDK\SAMPLES\ADMNDEMO\BUILD.BAT file to set up the proper environment and invoke the appropriate compiler and linker.

Note   For 32-bit compilation, the MAKEFILE assumes that you have installed the Win32 SDK. If you are using Visual C++ 1.0 or later on Windows NT, Admin Demo will not compile with the provided MAKEFILE. Instead, you must use the makefile generated by Visual C++.

To build the sample, change to the \ODBCSDK\SAMPLES\ADMNDEMO directory, then:

To build the 16-bit release version in the \ODBCSDK\SAMPLES\ADMNDEMO\NDEBUG16 directory, type:

   BUILD NDEBUG16

To build the 16-bit debug version in the \ODBCSDK\SAMPLES\ADMNDEMO\DEBUG16 directory, type:

   BUILD DEBUG16

To build the 32-bit release version in the \ODBCSDK\SAMPLES\ADMNDEMO\NDEBUG32 directory, type:

   BUILD NDEBUG32

To build the 32-bit debug version in the \ODBCSDK\SAMPLES\ADMNDEMO\DEBUG32 directory, type:

   BUILD DEBUG32

Unrecognized arguments to BUILD.BAT will halt compilation with a warning.

BUILD.BAT calls NMAKE, the Microsoft Program Maintenance Utility provided with Microsoft C version 7.0 or later, on the file MAKEFILE to rebuild the ADMNDEMO.EXE file. If MAKEFILE is unmodified, BUILD.BAT will rebuild the original ADMNDEMO.EXE sample.

For information on using NMAKE, see your C compiler tools documentation.

Note   ADMNDEMO.EXE is a medium-model program. Accordingly, to build it you must have installed both the Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later with the medium-model option set. (Windows NT is a flat-memory model environment, so the small/medium/large model options don't apply. The 32-bit sample will compile correctly using the Windows NT Software Development Kit.)

For more information on the medium-model option, see your Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later installation guides.

OTHER REQUIRED FILES

The LIBENTRY.OBJ file, included in the Windows 3.1 SDK, must be also be present to make ADMNDEMO.EXE. The resultant files (.RES, .EXE, and .MAP, and corresponding .OBJ files for each of the C source files listed previous) are placed in the appropriate directory, depending on the build option.


How to Run Admin Demo

You can run the Admin Demo by double-clicking the Sys Admin Sample icon in the ODBC SDK program group, or by choosing File/Run in the File Manager or Program Manager and typing \ODBCSDK\BIN\ADMNDEMO.EXE in the Command Line box.

ADMIN DEMO COMMAND-LINE SWITCHES

Admin Demo supports command-line switches to automatically connect to data sources, execute SQL scripts, and trace ODBC function calls. The switches are:

/D[connection-string]

Specifies a connection string for SQLDriverConnect. See the driver documentation for the precise syntax of this string. For example:

   /D[DSN=myserver;UID=Smith;PWD=Sesame;]

Note   Except for the /T option, the /D option must be specified for any other option to work.

/Ffilename

Specifies the full path of a file to execute in the same manner used for the File/Execute menu item.

/O:option

Specifies a set of options that determine how the file specified with /F is executed. Each option is separated by a colon.

   T	The statement terminator, either CR (default) or '<value>'

   M	Maximum statement size (default is 1000)

/Tfilename

Specifies the full path of a file to use for tracing of ODBC statements made by Admin Demo. This filename is used as a parameter to the SQLSetConnectOption function with the SQL_OPT_TRACEFILE option.

/Xoption

'Y' to force Admin Demo to exit once all other switches have been processed; 'N' (the default) to leave Admin Demo running.

EXAMPLES

In the following example, the statement terminator is the semicolon and the maximum statement size is 500:

/O:T';':M500

In next example, the statement terminator is a carriage return-linefeed character. The maximum statement size is 2500:

/O:TCR:M2500

In the final example, all options are used:

ADMNDEMO.EXE /FC:\SQLADMIN\BACKUP.SQL
   /D[DSN=myserver;UID=Smith;PWD=;]
   /O:TCR:M2000 /TC:\TMP\ADMNDEMO.LOG /XN

When Admin Demo is run, ODBC calls are logged to the C:\TMP\ADMNDEMO.LOG file, and Admin Demo connects to 'myserver' as user 'Smith' with no password. Once connected, the file C:\SQLADMIN\BACKUP.SQL is executed using a carriage return-linefeed character as a statement terminator with a maximum statement size of 2000. After the file has been executed, the application releases control to the user instead of exiting.


Admin Demo Menus

This section briefly describes the menu commands in Admin Demo. For more information on the ODBC functions that are executed by many of the menu items, see the Microsoft ODBC SDK Programmers Reference.

FILE MENU

CONNECT

Calls SQLDriverConnect to connect to a data source. If a new connection is successfully made, Admin Demo opens a new connection window and adds the connection window name to the Window menu.

DISCONNECT

Disconnects from a data source. The connection window and all results windows for the data source are closed. The connection window name is removed from the Window menu list.

EXECUTE

Executes the SQL statements found in the specified file. For more information, see "SQL Batch Files", later in this file.

OPEN

Opens the specified file and places its contents in the input window.

CLOSE

Closes the current file.

SAVE

Saves the contents of the input window to the current file.

SAVE AS

Saves the contents of the input window to the specified file.

EXIT

Discards pending result sets, closes open connections, and exits Admin Demo.

EDIT MENU

UNDO

Reverses the previous editing operation in the input window.

CUT

Cuts the selection from the active input or output window to the Clipboard.

COPY

Copies the selection from the active input or output window to the Clipboard.

PASTE

Pastes the clipboard contents to the current cursor location. (Text only)

SELECT ALL

Selects the entire contents of the current window.

COMMAND MENU

EXECUTE

Executes the selected statement in the input window. If no statement is selected, all statements in the input window are executed. The statement or statements are executed with SQLExecDirect. Results (if present) are retrieved with SQLFetch and SQLGetData. After a result set is fetched, SQLMoreResults is called to handle any additional result sets.

COMMIT

If supported, SQLTransact is called with the SQL_COMMIT option for the current connection window.

ROLLBACK

If supported, SQLTransact is called with the SQL_ROLLBACK option for the current connection window.

PIPE MENU

For more information, see "Pipes" later in this file.

EDIT

Creates a new pipe or modifies an existing pipe.

DO

Runs a pipe against a result set.

INFO MENU

MANAGE DATA SOURCES

Calls SQLManageDataSources in the ODBC installer DLL to allow you to add, modify, and delete data sources.

DATA SOURCES

Calls SQLDataSources to list the data sources on the current system. Although SQLDataSources only requires an environment handle, Admin Demo needs a connection window to display the results. Therefore this item is only valid after connecting to a data source.

DATA TYPES

Calls SQLGetTypeInfo to produce a result set of all data types on the system.

FUNCTIONS

Calls SQLGetFunctions to list the functions supported by the current driver. The results are listed in alphabetical order by Core, Level 1, and Level 2 functionality.

ODBC INFORMATION

Calls SQLGetInfo to list of the values returned for each information type defined in SQL.H and SQLEXT.H. (Note that no driver-defined values are retrieved.)

LISTS

These menu items provide a dialog box interface to the ODBC catalog functions. See the Microsoft ODBC SDK Programmer's Reference for details on each function.

TABLES

Calls SQLTables to produce a result set of tables.

COLUMNS

Calls SQLColumns to produce a result set of columns.

STATISTICS

Calls SQLStatistics to produce a result set of index information.

PRIMARY KEYS

Calls SQLPrimaryKeys to produce a result set of primary key information.

FOREIGN KEYS

Calls SQLForeignKeys to produce a result set of foreign key information.

TABLE PRIVILEGES

Calls SQLTablePrivileges to produce a result set of table privilege information.

COLUMN PRIVILEGES

Calls SQLColumnPrivileges to produce a result set of column privilege information.

SPECIAL COLUMNS

Calls SQLSpecialColumns to produce a result set of column information in a specified table.

PROCEDURES

Calls SQLProcedures to produce a result set of procedures.

PROCEDURE COLUMNS

Calls SQLProcedureColumns to produce a result set of procedure columns.

WINDOW MENU

FONT

Selects the default font to use for results windows. This value is stored in ADMNDEMO.INI for subsequent use.

CASCADE

Cascades all child windows, including connection and results windows.

TILE

Tiles all child windows, including connection and results windows.

ARRANGE ICONS

Arranges all child window icons in the frame window area.

CLOSE ALL

Closes all child windows, including connection and results windows.

LIST OF OPEN WINDOWS

Lists each child window using the form:

   N:<USER ID>@<DATA SOURCE> for connection windows

   N:<USER ID>@<DATA SOURCE>:<RESULTS> for results windows

where N is the number in the list, <USER ID> is the user name, <DATA SOURCE> is the data source name, and <RESULTS> is the results window name.

HELP MENU

HELP

Opens the \ODBCSDK\HELP\ODBCSMPL.HLP file.

ABOUT

Displays version information for Admin Demo.


Pipes

Pipes allow the results fetched from a connection to be used as the parameters for another statement. All statements are executed against the connection window which owns the result set window. Pipes cannot span multiple connections, but could be expanded to do the following:

Copy table contents from one connection window to another.

Perform administrative tasks. For example, you could select user names from one connection window, and apply them as a parameter to a CREATE USER statement in another connection window.

Support any function that requires a result set as an input parameter.

DEFINING PIPES

A pipe consists of an SQL statement (which may or may not take parameters), a list of the parameters to use, and a parameter option. This information is stored in the ADMNDEMO.INI file. To create a new pipe or modify an existing pipe, choose the Edit command from the Pipe menu.

PIPE DEFINITION EXAMPLE

The following example shows a pipe (as defined in the ADMNDEMO.INI file) that can be used in conjunction with the Tables list to drop all selected tables.

[Drop Table/View]
sql=DROP ? ?.?.?
parms=4,1,2,3
parmopt=value
delete=1

The items in the example pipe definition are:

sql

The SQL statement to be executed. Use a parameter marker (?) for each parameter.

parms

The list of parameters to be placed into the SQL statement. These values are 1-based and correspond to the columns in the result set produced by the function. (For example, in the result set produced by the Tables item, column 1 is Qualifier, column 2 is Owner, column 3 is Name, and column 4 is Type.)

parmopt

The parameter passing method to be used, either VALUE or ADDRESS. For VALUE, a textual substitution is done so that the SQL statement is executed as a complete statement with no unused parameter markers. For ADDRESS, the parameter markers are left in and the statement is prepared. The parameters are defined with SQLSetParam, and SQLExecute substitutes the values of each parameter.

delete

If set to 1, the row is deleted from the result set after processing the pipe. If set to 0, the row is not deleted.

PIPING BY VALUE EXAMPLE

Using the Drop Table/View pipe as an example, assume that you have created a result set with the following values:

(column)	Qualifier	Owner	Table	Type
(data)	accounting	joe	sales	table
When you choose Do from the Pipe menu and choose the Pipe button, Admin Demo loads the pipe information and processes each selected row of the result set. When the row is processed, the parameter method of 'value' indicates that each parameter marker is to be replaced before execution. The 'parms' entry indicates that the order of parameters is 4, 1, 2, 3, which, when correlated to the result set, is Type, Qualifier, Owner, and Table. Therefore the resulting SQL statement is:

DROP table accounting.joe.sales

Because the statement is complete, it is passed directly to SQLExecDirect, which executes the statement.

Passing data by value is often required due to the SQL involved. For example, most data sources do not allow parameter markers to mark keywords, as in this example.

PIPING BY ADDRESS EXAMPLE

Parameters can be used to execute SQL statements many times. For example, parameters are useful for copying a table from one data source to another, as in the following code:

SQLPrepare(hstmt2, "INSERT INTO SALES VALUES (?,?,?)", SQL_NTS);
SQLExecDirect(hstmt1, "SELECT * FROM SALES", SQL_NTS);

/* Bind columns returned on hstmt1 to output buffers */
/* Bind parameters markers to the same buffers       */

rc=SQLFetch(hstmt1);
while(rc != SQL_NO_DATA_FOUND) {
   SQLExecute(hstmt2);
   rc=SQLFetch(hstmt1);
}

where

   hstmt1 is on a connection from server1

   hstmt2 is on a connection from server2

Note that this example does not show calls to SQLBindCol to bind buffers to the result set columns or calls to SQLSetParam to bind the same buffers to the parameter markers. It also does not show error checking.

Although this is not a very sophisticated piece of code, it does show the power of the ODBC API: the results from a single SELECT statement were easily inserted into a table in another data source.

Admin Demo provides this type of pipe interface by allowing the 'address' parmopt keyword value. As an example, here is a pipe called Record Select that takes all selected rows and inserts their values into another table.

[Record Select]
sql=INSERT INTO CatchSelection VALUES (?,?,?,?)
parms=1,2,3,4
parmopt=address

In this example, the SQL statement is an INSERT statement that inserts four values into the CatchSelection table. Because the parmopt keyword is 'address', Admin Demo prepares the statement and calls SQLSetParam for each parameter marker. The parms keyword specifies that columns 1, 2, 3, and 4 of the result set (Qualifier, Owner, Name, and Type) be linked with parameters 1, 2, 3, and 4 in that order. For each row of the result set, Admin Demo then copies the row values to the parameter buffers and calls SQLExecute.

Using the result set in the previous example, the parameter data would be:

(column)	Qualifier	Owner	Table	Type
(data)	accounting	joe	sales	table
Selecting the data from CatchSelection would show this row in the table when the pipe was finished running.

LIMITATIONS OF PIPES

PARAMETER COUNT

Only 18 parameters are allowed per statement.

PARSING

The parsing engine of the SQL statement for the VALUE parameter option is not robust. It simply identifies the parameter marker, '?', and assumes it is the next parameter to replace. This means that the statement:

SELECT '?', ? FROM bigset

where only one parameter, Owner, was selected, will result in a final statement of:

SELECT 'joe', ? FROM bigset

This is not the intended result. If your needs exceed this limitation, you should either modify Admin Demo, or create your own application.


Sql Batch Files

The Execute command in the File menu allows you to execute SQL statements stored in a text file. This is useful for running scripts, such as backups. When this option is selected, the Execute File dialog box appears.

EXECUTE FILE DIALOG BOX OPTIONS

You use the Execute File dialog box to identify SQL batch files. The options for the dialog box are:

Terminator

The character or characters that terminate an SQL statement. If Carriage Return is selected, the \r\n string is used. If Character is selected, the value in the edit box is used.

The following example shows the CARRTN.SQL batch file, which uses carriage returns to terminate statements.

CREATE TABLE SALES (SALESNUM INTEGER, CUSTOMER CHAR(10))
INSERT INTO SALES VALUES (10, 'Harry')
INSERT INTO SALES VALUES (20, 'June')
SELECT * FROM SALES

The next example file, SQLSRVR.SQL, shows how you may run a script for SQL Server that uses 'GO' to indicate the end of a block of statements.

CREATE TABLE Sales (SalesNum integer, Customer char(10))
GO
INSERT INTO Sales VALUES (10, 'Harry')
INSERT INTO Sales VALUES (20, 'June')
GO
SELECT * FROM Sales
GO

The third example shows the ORACLE.SQL batch file, which uses semicolons (;) to terminate SQL statements.

CREATE TABLE SALES
(SALESNUM NUMBER, CUSTOMER CHAR(10));
INSERT INTO SALES VALUES (10, 'Harry');
INSERT INTO SALES VALUES (20, 'June');
SELECT * FROM SALES;

Note that because the terminator is never actually sent to the server, you could take a script designed for SQL Server (with the 'GO' terminator) and run it against Oracle. Only the SQL statements would be sent. Provided the SQL grammar is compatible, it will work on either platform.

Maximum Statement Length

Specifies the maximum statement length to be used. The statement length must be from 100 to 9999. This value is used to allocate global memory into which the file is read. If a statement is longer than this value, Admin Demo executes only that part of the statement that it has read. This will most likely cause a syntax error. The default of 1000 should be sufficient for nearly all batch files.

BATCH FILE LIMITATIONS

The execution method is not particularly sophisticated. Because of this, the following limitations should be kept in mind:

EXTENDED SQL

The only SQL statements which can be executed are those which the data source can process. That is, there is no special batch control mechanism in Admin Demo. Using SQL extensions such as WHILE and IF must be limited to data sources which can interpret them. For example, you may use various conditional statements when creating a stored procedure in SQL Server or Oracle. Admin Demo makes no attempt to distinguish between them.

MAXIMUM FILE SIZE

Since only "Max Length" bytes are read from the file at a time, there should be no real limit on the overall size of the file being executed. However, the maximum statement size can be no longer than "Max Length," which is defined to be 100 to 9999.

TERMINATOR PARSING

The search algorithm simply fills the buffer to the specified maximum by reading sequentially from the file. A search for the terminator string starts at the beginning of the buffer. When found, it is replaced with a null terminator and all carriage returns (assuming the terminator is not a carriage return) are removed before the statement is executed. This means that embedded carriage returns in data will be stripped.

An attempt is made to skip over data strings wherever possible (with the exception of carriage returns). For example, if your terminator is the semicolon (;) character, executing the following file:

SELECT ';', Customer FROM Sales;

is identical to executing the following:

SELECT ';', Customer FROM Sales

and

SELECT 'A line
   of data' FROM Sales

is identical to:

SELECT 'A line of data' FROM Sales


Cursor Demo Contents

This file contains the following information:

What Cursor Demo Demonstrates

Cursor Demo Files

How to Build Cursor Demo

How to Run Cursor Demo

Cursor Demo Menus

How to Use Cursor Demo


What Cursor Demo Demonstrates

Cursor Demo takes advantage of the block cursor, scrolling, positioned update and delete capabilities of the ODBC Cursor Library. For more information on the ODBC Cursor Library, see the Microsoft ODBC SDK Programmers Reference.

FEATURES

SCROLLABLE RESULT SET WINDOWS

Provides a scrolling window over a result set. Individual rows in the result set may be selected and updated, if the data source supports positioned updates. Result sets may be generated either by queries or by activating the ODBC functions that return a result set, such as SQLTables.

Each results window is an MDI child window of the connection window in which the operation was performed. This means that disconnecting from a connection window closes all of the results windows created from that connection window.

LIMITED LEVEL 2 API CONFORMANCE CAPABILITY

Demonstrates some ODBC conformance level 2 features, such as SQLExtendedFetch. It is also possible to use this driver with non-level 2 drivers if the Cursor Library is installed and enabled.

STATEMENT OPTIONS DIALOG BOX

Optional run modes are configurable with the Stmt menu Options command. The Options dialog box is a dynamic dialog box. Selecting an option changes the dialog box configuration to match the requirements of the option.

MULTITHREADED SUPPORT FOR WINDOWS NT

Cursor Demo supports multithreading under Windows NT when compiled with the "thread" option. (For more information on compiling with the "thread" option, see "How to Build Cursor Demo.")

LIMITATIONS

ONE ACTIVE CONNECTION WINDOW

Cursor Demo can only open single connections. If the driver has the capability, Cursor Demo will support multiple statements over the connection.

NUMBER OF ROWS FETCHED AND ROWSET SIZE

The maximum number of rows Cursor Demo displays is set using the Stmt menu Options command. The Rowset Size option defaults to 10, maximum is 65500.

SIMPLISTIC MEMORY MANAGEMENT

Cursor demo doesn't handle out-of-memory conditions very gracefully. Make sure you have sufficient memory to run the program and load your data.


Cursor Demo Files

FILES LOCATION

The Cursor Demo source code resides in the \ODBCSDK\SAMPLES\CRSRDEMO directory. The 16-bit executable file CRSRDEMO.EXE is located in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

CHILD.C

Contains routines that maintain a child window. These include most interfaces with ODBC as well as all data retrieval and display.

CHILD.ICO

Minimized child window icon.

CRSRDEMO.C

Main module. Contains the standard functions used in a Windows program (such as WinMain) plus two functions shared between all the files.

CRSRDEMO.DEF

Module definition file Cursor Demo.

CRSRDEMO.H

Prototypes and definitions for CRSRDEMO.C.

CRSRDEMO.ICO

Cursor Demo icon.

CRSRDEMO.RC

Resource file for Cursor Demo.

DIALOGS.C

Displays and manages Cursor Demo dialog boxes.

FRAME.C

Manages the main frame window. The frame window owns the MDI client window, the menu bar, and other major parts of the interface.

HEADERS.C

Implements precompiled headers

HEADERS.H

Precompiled-headers file.

RESOURCE.H

Definitions used by CRSRDEMO.RC.

RESRC1.H

App Studio-generated include file.


How to Build Cursor Demo

The file \ODBCSDK\SAMPLES\CRSRDEMO\MAKEFILE is set up for compilation within both 16- and 32-bit environments using a Microsoft or Microsoft-compatible C compiler. Use the \ODBCSDK\SAMPLES\CRSRDEMO\BUILD.BAT file to set up the proper environment and invoke the appropriate compiler and linker.

Note   For 32-bit compilation, the MAKEFILE assumes that you have installed the Win32 SDK. If you are using Visual C++ 1.0 or later on Windows NT, Cursor Demo will not compile with the provided MAKEFILE. Instead, you must use the makefile generated by Visual C++.

To build the sample, change to the \ODBCSDK\SAMPLES\CRSRDEMO directory, then:

To build the 16-bit release version in the \ODBCSDK\SAMPLES\CRSRDEMO\NDEBUG16 directory, type:

   BUILD NDEBUG16

To build the 16-bit debug version in the \ODBCSDK\SAMPLES\CRSRDEMO\DEBUG16 directory, type:

   BUILD DEBUG16

To build the 16-bit release version in the \ODBCSDK\SAMPLES\CRSRDEMO\NDEBUG32 directory, type:

   BUILD NDEBUG32

To build the 32-bit debug version in the \ODBCSDK\SAMPLES\CRSRDEMO\DEBUG32 directory, type:

   BUILD DEBUG32

Unrecognized arguments to BUILD.BAT will halt compilation with a warning.

BUILD.BAT calls NMAKE, the Microsoft Program Maintenance Utility provided with Microsoft C version 7.0 or later, on the file MAKEFILE to rebuild the CRSRDEMO.EXE file. If MAKEFILE is unmodified, BUILD.BAT will rebuild the original CRSRDEMO.EXE sample.

For information on using NMAKE, see your C compiler tools documentation.

Note   CRSRDEMO.EXE is a large-model program. Accordingly, to build CRSRDEMO.EXE in a 16-bit environment, you must have installed both the Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later with the large-model option set. (Windows NT is a flat-memory model environment, so the small/medium/large model options don't apply. The sample will compile correctly using the Windows NT Software Development Kit.)

For more information on the large-model option, see your Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later installation guides.

OTHER REQUIRED FILES

The LIBENTRY.OBJ file, included in the Windows 3.1 SDK, must be also be present to make CRSRDEMO.EXE. The resultant files (CRSRDEMO.RES, CRSRDEMO.EXE, and CRSRDEMO.MAP, and corresponding .OBJ files for each of the C source files listed previous) are placed in the appropriate directory, depending on the build option.

COMPILING A MULTITHREADED CURSOR DEMO

An optional build switch, "thread", compiles a version of Cursor Demo that is multithreaded under Windows NT. For example, to compile a 32-bit debug version in the \ODBCSDK\SAMPLES\CRSRDEMO\DEBUG32 directory, type:

   BUILD DEBUG32 THREAD

Only 32-bit builds (debug32 or ndebug32) may specify the "thread" switch. The default is the "nothread" option.

Note   Do a clean build before switching from a "thread" to a "nothread" build (or vice versa) in the same directory (DEBUG32 or NDEBUG32); that is, delete all .OBJ files before beginning the next build.


How to Run Cursor Demo

You can run Cursor Demo by double-clicking the Cursor Demo icon from ODBC SDK program group, or by choosing to run the \ODBCSDK\BIN\CRSRDEMO.EXE file from the File Manager or Program Manager.


Cursor Demo Menus

This section briefly describes the menu commands in Cursor Demo. For more information on the ODBC functions that are executed by many of the menu items, see the Microsoft ODBC SDK Programmers Reference.

STMT MENU

NEW

Opens a new statement handle on the current connection.

CONNECT

Closes the current data source connection and connects to a new data source.

DISCONNECT

Disconnects from the current data source

SQL

Opens the Statement dialog box, which enables you to execute an SQL statement.

TABLE INFORMATION

Opens the Table Information dialog box, which enables you to query various types of information from the database. It contains the following:

Tables

Calls SQLTables with the specified arguments.

Columns

Calls SQLColumns to return column information.

Procedures

Calls SQLProcedures for procedure information.

Statistics

Calls SQLStatistics to retrieve index information.

Privileges

Calls SQLTablePrivileges to retrieve privilege information.

Qualifier, Owner, Name, and Type

These edit boxes specify arguments for the ODBC functions. For information on ODBC functions, see the Microsoft ODBC SDK Programmers Reference.

TYPE INFORMATION

Calls SQLGetTypeInfo to return information on the data types supported by the data source.

OPTIONS

Opens the Options dialog box, which enables you to set Cursor Demo statement options. The Options dialog box contains the following:

Options List Box

Contains the statement option types Bind, Concurrency, General, and Scrolling. Enables you to specify values for the selected type.

Options Group

Available options for the selected type are displayed in this group. See the descriptions for the statement options following.

Bind options   Uses SQLSetStmtOption with an fOption value of SQL_BIND_TYPE. Enables you to set binding by row, single column, all columns or a specified row or column number.

Concurrency options   Uses SQLSetStmtOption with an fOption value of SQL_CONCURRENCY to specify when fetched data may be updated, and a vParam value as follows:

Read-Only

Fetched data may not be updated. (Uses SQL_CONCUR_READ_ONLY.)

Optimistic by timestamp

Fetches will not be updated if timestamp differs from original. (Uses SQL_CONCUR_ROWVER.)

Optimistic by values

Fetches will not be updated if values differ from original. (Uses SQL_CONCUR_VALUES.)

General options   These options display when General is selected in the Options list box. They include:

Asynchronous processing

Uses SQLSetStmtOption with an fOption value of SQL_ASYNC_ENABLE to enable Cursor Demo to perform asynchronous processing.

Always fetch first

Instructs Cursor Demo to always do SQLExtendedFetch with an fFetchType value of SQL_FETCH_FIRST after the successful execution of an SQL statement. If this option is not set, no rows will appear in the result set window until you select one of the commands in the Fetch menu.

Max column width

Sets the maximum length of data that will be retrieved for any column. The maximum limit of this parameter is set in the MAX_MAXBIND definition of the CRSRDEMO.H file. Because Cursor Demo allocates space for each column in the rowset, it can run out of memory if too many large columns are bound. Make this value smaller if you run out of memory, or increase it if you want to see more data in large columns. Uses SQLSetStmtOption with an fOption of SQL_MAX_LENGTH.

Scrolling options   Uses SQLSetStmtOption with an fOption value of SQL_CURSOR_TYPE to specify legal movement of the cursor, and a vParam value as follows:

Forward only

The cursor will scroll in the forward direction only. (Uses SQL_CURSOR_FORWARD_ONLY.)

Static (scrollable snapshot)

The cursor will scroll in any direction, but the data will not be updated. (Uses SQL_CURSOR_STATIC.)

Keyset driven

The cursor is fully keyset-driven. (Uses SQL_CURSOR_KEYSET_DRIVEN.)

Dynamic

The driver only saves and uses the keys for the rows in the rowset. (Uses SQL_CURSOR_DYNAMIC.)

Row set size

Defines the number of rows in your rowset.

CLOSE

Close the current statement.

CLOSE ALL

Close all open statements.

EXIT

Exits Cursor Demo.

FETCH MENU

All the Fetch menu items use SQLExtendedFetch with different values for the fFetchType option. For information on SQLExtendedFetch, see the Microsoft ODBC SDK Programmers Reference.

FIRST

Uses SQLExtendedFetch with an fFetchType value of SQL_FETCH_FIRST. (Fetches the first rowset in the result set.)

PREV

Uses SQLExtendedFetch with an fFetchType value of SQL_FETCH_PRIOR. (Fetches the previous rowset in the result set.)

NEXT

Uses SQLExtendedFetch with an fFetchType value of SQL_FETCH_NEXT. (Fetches the next rowset in the result set.)

LAST

Uses SQLExtendedFetch using an fFetchType value of SQL_FETCH_LAST. (Fetches the last rowset in the result set.)

ABSOLUTE

Uses SQLExtendedFetch with an fFetchType value of SQL_FETCH_ABSOLUTE. (Fetches the rowset starting at the given absolute row number.)

RELATIVE

Uses SQLExtendedFetch with an fFetchType value of SQL_FETCH_RELATIVE. (Fetches the rowset starting at the given relative row number.)

DELETE ROW

Deletes the selected row.

UPDATE ROW

Opens the Update Row dialog box, which enables you to change data in the selected row.

WINDOW MENU

CASCADE

Cascades all open windows.

TILE HORIZONTAL

Tiles all open windows horizontally.

TILE VERTICAL

Tiles all open windows vertically.

ARRANGE ICONS

Lines up all minimized windows along the bottom of the Cursor Demo workspace.

LIST OF OPEN WINDOWS

All open windows are listed along with the name of the cursor they represent.

HELP MENU

HELP

Opens the \ODBCSDK\HELP\ODBCSMPL.HLP file.

ABOUT

Displays version information for Cursor Demo.


How to Use Cursor Demo

To connect to a data source, choose the Connect command from the Stmt menu. A list of data sources appears; select one, and then follow the connection procedures for that data source.

Once you have connected to a data source, an empty result set window appears. To retrieve a result set, either enter a query (using the Stmt menu SQL command) or select one of the ODBC catalog functions (for example, the Stmt menu Table Information command). If the query or catalog request executes successfully, a result set appears in the window.

Cursor Demo allows you to perform Cursor Library operations. You can select rows by clicking the row with the mouse. To delete a selected row, use the Delete Row command in the Fetch menu. To update the values in a selected row, use the Update Row command in the Fetch menu. For information on the operation of the Cursor Library, see the Microsoft ODBC SDK Programmers Reference.


C++ Demo Contents

This file contains the following information:

What C++ Demo Demonstrates

C++ Demo Files

How to Build C++ Demo

How to Run C++ Demo

C++ Demo Menus

Making a Query with C++ Demo


What C++ Demo Demonstrates

C++ Demo illustrates the use of C++ classes. These classes provide a thin-layer C++ interface to the ODBC API. All ODBC API calls go through the class structure instead of directly to the API.

The C++ Demo uses three classes (one for environment, one for connection, and one for statement). C++ Demo uses an object from each of the three classes. The source code defines many member functions that are not used in C++ Demo.

FEATURES

Supports multiple instances of the application; more than one instance of the C++ Demo may be run at the same time.

LIMITATIONS

ONE ACTIVE CONNECTION WINDOW

Only one connection window may be active. To open another connection to a data source, you must close the current connection.

MAXIMUM ROWS FETCHED IN A RESULT SET: 100

The maximum number of rows that can be fetched in a results set is 100.


C++ Demo Files

FILES LOCATION

The C++ Demo source code resides in the \ODBCSDK\SAMPLES\CPPDEMO directory. The 16-bit executable file CPPDEMO.EXE is located in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

CODBC.CPP

Implements the sample ODBC C++ classes.

CODBC.H

The sample ODBC C++ class definitions.

CODBC.INL

Implements the member functions of the sample ODBC C++ class.

CPPDEMO.CPP

The main C++ source file. It handles connecting, disconnecting, fetching of result sets, error handling, and so on. It also handles all of the user interface except for the dialog boxes.

CPPDEMO.DEF

Module definition file for C++ Demo.

CPPDEMO.H

Prototypes and definitions for CPPDEMO.CPP.

CPPDEMO.ICO

C++ Demo icon.

CPPDEMO.RC

Resource file for C++ demo.

DIALOGS.CPP

Handles all of the dialog boxes used by C++ Demo.

HEADERS.CPP

This file is used for support of precompiled headers.

HEADERS.H

This file contains #include statements for all the header files used by all the .CPP files. It is used to support precompiled headers.

RESOURCE.H

This file contains definitions that associate names with resource ID numbers.


How to Build C++ Demo

The file \ODBCSDK\SAMPLES\CPPDEMO\MAKEFILE is set up for compilation within both 16- and 32-bit environments using a Microsoft or Microsoft-compatible C compiler. Use the \ODBCSDK\SAMPLES\CPPDEMO\BUILD.BAT file to set up the proper environment and invoke the appropriate compiler and linker.

Note   For 32-bit compilation, the MAKEFILE assumes that you have installed the Win32 SDK. If you are using Visual C++ 1.0 or later on Windows NT, C++ Demo will not compile with the provided MAKEFILE. Instead, you must use the makefile generated by Visual C++.

To build the sample, change to the \ODBCSDK\SAMPLES\CPPDEMO directory, then:

To build the 16-bit release version in the \ODBCSDK\SAMPLES\CPPDEMO\NDEBUG16 directory, type:

   BUILD NDEBUG16

To build the 16-bit debug version in the \ODBCSDK\SAMPLES\CPPDEMO\DEBUG16 directory, type:

   BUILD DEBUG16

To build the 16-bit release version in the \ODBCSDK\SAMPLES\CPPDEMO\NDEBUG32 directory, type:

   BUILD NDEBUG32

To build the 32-bit debug version in the \ODBCSDK\SAMPLES\CPPDEMO\DEBUG32 directory, type:

   BUILD DEBUG32

Unrecognized arguments to BUILD.BAT will halt compilation with a warning.

BUILD.BAT calls NMAKE, the Microsoft Program Maintenance Utility provided with Microsoft Visual C++ version 1.0 or later, on the file MAKEFILE to rebuild the files. If MAKEFILE is unmodified, BUILD.BAT will rebuild the original CPPDEMO.EXE sample.

The NMAKE utility will find the file MAKEFILE and build the files in the appropriate directory. MAKEFILE is set up for compilation within both 16- and 32-bit environments.

For information on using NMAKE, see your C compiler tools documentation.

Note   CPPDEMO.EXE is a medium-model program. Accordingly, to build it you must have installed both the Microsoft Windows 3.1 SDK and Microsoft Visual C++ version 1.0 or later with the medium-model option set. (Windows NT is a flat-memory model environment, so the small/medium/large model options don't apply. The 32-bit sample will compile correctly using the Windows NT Software Development Kit.)

For more information on the medium-model option, see your Microsoft Windows 3.1 SDK and Microsoft Visual C++ version 1.0 or later installation guides.

BORLAND (R) COMPILER BUILD OPTION

BUILD.BAT also contains a switch to enable you to compile the C++ Demo using the Borland C++ compiler (version 3.1). Specify the BORLAND parameter to use the alternate \ODBCSDK\SAMPLES\CPPDEMO\BCCMAKE makefile. For example:

BUILD NDEBUG16 BORLAND

will build the 16-bit NDEBUG version of the C++ Demo using your Borland compiler and the BCCMAKE makefile.


How to Run C++ Demo

You can run the C++ Demo by double-clicking the ODBC/C++ Sample icon from ODBC SDK program group, or by choosing File/Run in the File Manager or Program Manager and typing \ODBCSDK\BIN\CPPDEMO.EXE in the Command Line box.


C++ Demo Menus

This section briefly describes the menu commands in C++ Demo. For more information on the ODBC functions that are executed by many of the menu items, see the Microsoft ODBC SDK Programmers Reference.

FILE MENU

EXIT

Closes the current connection and exits C++ Demo.

ENVIRONMENT MENU

ADD DATA SOURCE

Opens the ODBC installer DLL Add Data Source dialog box, which enables you to add and configure a new data source.

OPEN CONNECTION

Opens the SQL Data Sources dialog box, which enables you to connect to an existing data source.

CLOSE CONNECTION

Closes the current connection.

SQL MENU

EXECUTE SQL

Opens a dialog box that enables you to type a single SQL query. Choosing the OK button sends the query to the current data source.

FETCH NEXT ROWSET

Fetches the next 100 rows of result set data. This command is only active when you execute an SQL query that returns more than 100 rows of data in its result set. If there are fewer than 100 rows remaining, it fetches the remaining rows.

HELP MENU

HELP

Opens the \ODBCSDK\HELP\ODBCSMPL.HLP file.

ABOUT

Displays version information for C++ Demo.


Making a Query with C++ Demo

To connect to a data source and make a query:

1.	From the Environment menu, choose Open Connection. The SQL Data Sources dialog box appears.

2.	Select the data source to which you want to connect and choose the OK button. The SQL Data Sources dialog box disappears. If successful, the C++ Demo workspace title bar displays the name of the Data Source.

3.	From the SQL menu, choose Execute SQL. The ODBC SDK 2.0 C++ Demo dialog box appears.

4.	Type the SQL statement you want to execute. Then choose the OK button. If the statement is successful, results are displayed in the C++ Demo workspace. If the statement is unsuccessful, a dialog box appears informing you of the error.

5.	From the Environment menu, choose Close Connection. A dialog box appears requesting that you confirm the disconnection.

6.	Choose the OK button. The connection is closed.

7.	From the File menu, choose Exit to exit the C++ Demo.


Query Demo Contents

This file contains the following information:

What Query Demo Demonstrates

Query Demo Files

How to Build Query Demo

How to Run Query Demo

Query Demo Menus and Toolbar

Making a Query with Query Demo


What Query Demo Demonstrates

Query Demo demonstrates multiple simultaneous connections using ODBC. It enables you to type any SQL query and browse the results.

FEATURES

CONNECTION WINDOWS

Query Demo enables you to connect to multiple data sources. The only limits on connections are those imposed by each driver and the amount of memory available on the system. Each new connection creates a multiple-document interface (MDI) child connection window from which SQL statements can be executed.

STATEMENT WINDOWS

Query Demo enables you to open multiple statement windows on a connection. The only limits on statements are those imposed by each driver and the amount of memory available on the system.

LIMITATIONS

MAXIMUM NUMBER OF WINDOWS: 10

You can open a maximum of 10 connection and statement windows.

NON-SELECT STATEMENTS

For non-SELECT statements, application behavior is undefined.

OTHER LIMITATIONS

Maximum displayed columns: 15

Maximum displayed rows: 100


Query Demo Files

LOCATION

The Query Demo source code resides in the \ODBCSDK\SAMPLES\QURYDEMO directory. The 16-bit executable file QURYDEMO.EXE resides in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

MAIN.C

Contains the main application window procedures. Demonstrates usage of MDI windows, toolbar and status bar.

NEWQUERY.BMP

A toolbar button bitmap, used to open a new statement window.

QUERY.C

Contains the code that uses the ODBC API. Used for all data access operations (for example, connecting to a data source, executing and displaying query results, and so on).

QUERYWDW.ICO

Minimized connection/statement window icon.

QURYDEMO.DEF

Module definition file for Query Demo.

QURYDEMO.H

Prototypes and definitions for QURYDEMO.C.

QURYDEMO.ICO

Query Demo icon.

QURYDEMO.RC

Resource file for Query Demo.

RUNQUERY.BMP

A toolbar button bitmap, used to execute an SQL command.


How to Build Query Demo

The file \ODBCSDK\SAMPLES\QURYDEMO\MAKEFILE is set up for compilation within both 16- and 32-bit environments using a Microsoft or Microsoft-compatible C compiler. You use the \ODBCSDK\SAMPLES\QURYDEMO\BUILD.BAT file to set up the proper environment and invoke the appropriate compiler and linker.

Note   For 32-bit compilation, the MAKEFILE assumes that you have installed the Win32 SDK. If you are using Visual C++ 1.0 or later on Windows NT, Query Demo will not compile with the provided MAKEFILE. Instead, you must use the makefile generated by Visual C++.

To build the sample, change to the \ODBCSDK\SAMPLES\QURYDEMO directory, then:

To build the 16-bit release version in the \ODBCSDK\SAMPLES\QURYDEMO\NDEBUG16 directory, type:

   BUILD NDEBUG16

To build the 16-bit debug version in the \ODBCSDK\SAMPLES\QURYDEMO\DEBUG16 directory, type:

   BUILD DEBUG16

To build the 16-bit release version in the ODBCSDK\SAMPLES\QURYDEMO\NDEBUG32 directory, type:

   BUILD NDEBUG32

To build the 32-bit debug version in the ODBCSDK\SAMPLES\QURYDEMO\DEBUG32 directory, type:

   BUILD DEBUG32

Unrecognized arguments to BUILD.BAT will halt compilation with a warning.

BUILD.BAT calls NMAKE, the Microsoft Program Maintenance Utility provided with Microsoft C version 7.0 or later, on the file MAKEFILE to rebuild the QURYDEMO.EXE file. If MAKEFILE is unmodified, BUILD.BAT will rebuild the original QURYDEMO.EXE sample.

For information on using NMAKE, see your C compiler tools documentation.

Note   QURYDEMO.EXE is a medium-model program. Accordingly, to build it, you must have installed both the Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later with the medium-model option set. (Windows NT is a flat-memory model environment, so the small/medium/large model options don't apply. The sample will compile correctly using the Windows NT Software Development Kit.)

For more information on the medium-model option, see your Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later installation guides.

OTHER REQUIRED FILES

The LIBENTRY.OBJ file, included in the Windows 3.1 SDK, must be also be present to make QURYDEMO.EXE. The resultant files (.RES, .EXE, and .MAP, and corresponding .OBJ files for each of the C source files listed previous) are placed in the appropriate directory, (depending on the build option).


How to Run Query Demo

You can run Query Demo by double-clicking the Query Sample icon from ODBC SDK program group, or by choosing to run the \ODBCSDK\BIN\QURYDEMO.EXE file from the File Manager or Program Manager.


Query Demo Menus and Toolbar

This section briefly describes the menu and toolbar commands in Query Demo. For more information on the ODBC functions that are executed by many of the menu items, see the Microsoft ODBC SDK Programmers Reference.

LOGIN MENU

CONNECT

Calls SQLConnect to connect to a data source and provides a dialog box for entering connection information.

DRIVER CONNECT

Calls SQLDriverConnect to connect to a driver and a data source.

DISCONNECT

Disconnects from statement and connection handles.

EXIT

Exits Query Demo

QUERY MENU

EXECUTE SQL

Executes the SQL query you typed in the statement window.

NEW QUERY

Opens a new statement window in which you can type an SQL query.

WINDOW MENU

TILE

Tiles all child windows, including connection and statement windows.

CASCADE

Cascades all windows in the Query Demo workspace.

ARRANGE ICONS

Arranges all minimized components along the bottom of the Query Demo workspace.

CLOSE ALL

Closes all open connection and statement windows.

HELP MENU

HELP

Opens the \ODBCSDK\HELP\ODBCSMPL.HLP file.

ABOUT

Displays version information for Query Demo.

TOOLBAR

The toolbar contains:

A connection window list box, listing connected data sources

A statement window list box, listing open statement handles

A button to open a new statement window (same as New Query in the Query menu)

A button to execute SQL statements (same as Execute SQL in the Query menu)


Making a Query with Query Demo

1.	From the Login menu, choose either Connect or Driver Connect to connect to a data source. If connection is successful, a connection window opens. The title bar displays the values for DSN, HDBC, and HSTMT. The SQL> box enables you to type in SQL statements.

2.	Type a valid SQL statement in the SQL> box. From the Query menu, choose Execute SQL, or use the corresponding toolbar button. The SQL statement is executed. If successful, the result set for the query will be displayed. You can scroll through the result set using the mouse or the keyboard.

Note   You must click the mouse in the result set window before you can use the keyboard to scroll the results set.

3.	If you want to open more than one statement window, from the Query menu, choose New Query to open a new query window, or use the corresponding toolbar button.

4.	To free statement handles and disconnect from the connected data sources, choose Disconnect from the Login menu. The Disconnect From Data Source dialog box appears.

5.	Select all data sources you have connected to and choose the Disconnect button.

6.	To exit Query Demo, from the Login menu, choose Exit. Query Demo closes all open connections before exiting.


Sample Driver Contents

This file contains the following information:

What Sample Driver Demonstrates

Sample Driver Files

How to Build the Sample Driver


What Sample Driver Demonstrates

The Sample Driver provides an example of the code structure needed to write a basic driver. You can use it as a template for writing your drivers. The Sample Driver implements the following:

Minimal SQLAllocConnect and SQLAllocStmt functionality.

Minimal SQLFreeConnect and SQLFreeStmt functionality.

A complete driver-specific setup function.

Inclusion of the SQLGetTranslator function in the driver-specific setup for setting up drivers with translation DLLs.

Use of the Windows SDK WEP (windows exit procedure) code and LibMain functions.

FUNCTIONALITY

The Sample Driver DLL receives function arguments and returns SQL_SUCCESS (or for SQLError, SQL_NO_DATA_FOUND) in RETCODE. However, several functions in the Sample Driver template provide greater functionality.

The SQLAllocConnect and SQLAllocStmt functions allocate connection and statement handles, respectively, and then check the handle argument in the function. The SQLFreeConnect and SQLFreeStmt functions free the memory for the handle structure allocated by their respective allocation functions. The SQLDriverConnect function displays a dialog box when an fDriverCompletion value of SQL_DRIVER_PROMPT or SQL_DRIVER_COMPLETE is supplied. The resource file for the dialog box is included in the SDK.

The driver-specific setup DLL is included in the Sample Driver DLL and is used to install the Sample Driver through the ODBC installer DLL. It shows how to respond to calls from the ODBC installer DLL by parsing the attribute string, responding to different requests, and updating the ODBC.INI file. It also provides an example of how to use SQLGetTranslator to configure a driver with translation information during the driver-specific setup. The resource file contains a dialog-box interface to the setup DLL, which enables the user to choose driver-specific setup options for the Sample Driver. The Option buttons are displayed as an example of how such a dialog box could be implemented; they have no functionality.

The Sample Driver supports load-by-ordinal by exporting all Windows functions to a specific ordinal number; non-ODBC functions are exported at values outside of the ODBC API range.

For detailed information on ODBC functions and return codes, see the Microsoft ODBC SDK Programmers Reference.

LIMITATIONS

Because Sample Driver is an operational template, its possesses little functionality. Specifically, the following limitations apply:

The SQLDriverConnect function displays the Driver Connect dialog box, but doesn't actually make a connection. You must implement this feature.

Sample Driver returns SQL_SUCCESS for all functions, except for the following cases:

SQLAllocConnect returns SQL_ERROR if it cannot allocate a connection handle.

SQLDriverConnect returns SQL_NO_DATA_FOUND if the dialog box cannot be displayed or if it is canceled.

SQLError always returns SQL_NO_DATA_FOUND.

The Sample Driver source code files include every ODBC function except SQLDataSources and SQLDrivers, which are implemented in the Driver Manager.


Sample Driver Files

FILES LOCATION

The Sample Driver source code resides in the \ODBCSDK\SAMPLES\SMPLDRVR directory. The 16-bit version of Sample Driver (SAMPLE.DLL) resides in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

CATALOG.C

Contains the function templates for the catalog functions:

   SQLTables	SQLColumns

   SQLStatistics	SQLTablePrivileges

   SQLColumnPrivileges	SQLSpecialColumns

   SQLPrimaryKeys	SQLForeignKeys

   SQLProcedures	SQLProcedureColumns

CONNECT.C

Contains the function templates for the connection functions:

   SQLAllocEnv	SQLAllocConnect

   SQLConnect	SQLDriverConnect

   SQLBrowseConnect	SQLDisconnect

   SQLFreeConnect	SQLFreeEnv

DLL.C

Contains the code template for creating a DLL.

EXECUTE.C

Contains the function templates for functions used in the execution of SQL statements:

   SQLExecute	SQLExecDirect

   SQLNativeSql	SQLParamData

   SQLPutData	SQLCancel

INFO.C

Contains the function templates for information functions:

   SQLGetInfo	SQLGetTypeInfo

   SQLGetFunctions

OPTIONS.C

Contains the function templates for functions that support the setting and getting of options:

   SQLSetConnectOption	SQLSetStmtOption

   SQLGetConnectOption	SQLGetStmtOption

PREPARE.C

Contains the function templates for functions that support the preparation of SQL statements for execution:

   SQLAllocStmt	SQLFreeStmt

   SQLPrepare	SQLBindParameter

   SQLDescribeParam	SQLParamOptions

   SQLNumParams	SQLSetScrollOptions

   SQLSetCursorName	SQLGetCursorName

RESULTS.C

Contains the function templates for functions that describe or retrieve results:

   SQLNumResultCols	SQLDescribeCol

   SQLColAttributes	SQLBindCol

   SQLFetch	SQLGetData

   SQLMoreResults	SQLRowCount

   SQLSetPos	SQLExtendedFetch

   SQLError

SAMPLE.DEF

Module definition file for Sample Driver.

SAMPLE.H

Prototypes and definitions for Sample Driver.

SAMPLE.RC

Resource file for Sample Demo, including the connection dialog box displayed by SQLDriverConnect.

SETUP.C

Responds to the ODBC installer DLL, manages dialogs, and updates the ODBC.INI file (or registry on Windows NT).

TRANSACT.C

Contains the function template for SQLTransact.


How to Build the Sample Driver

The file \ODBCSDK\SAMPLES\SMPLDRVR\MAKEFILE is set up for compilation within both 16- and 32-bit environments using a Microsoft or Microsoft-compatible C compiler. Use the \ODBCSDK\SAMPLES\SMPLDRVR\BUILD.BAT file to set up the proper environment and invoke the appropriate compiler and linker.

Note   For 32-bit compilation, the MAKEFILE assumes that you have installed the Win32 SDK. If you are using Visual C++ 1.0 or later on Windows NT, Sample Driver will not compile with the provided MAKEFILE. Instead, you must use the makefile generated by Visual C++.

To build the sample, change to the \ODBCSDK\SAMPLES\SMPLDRVR directory, then:

To build the 16-bit release version in the \ODBCSDK\SAMPLES\SMPLDRVR\NDEBUG16 directory, type:

   BUILD NDEBUG16

To build the 16-bit debug version in the \ODBCSDK\SAMPLES\SMPLDRVR\DEBUG16 directory, type:

   BUILD DEBUG16

To build the 16-bit release version in the \ODBCSDK\SAMPLES\SMPLDRVR\NDEBUG32 directory, type:

   BUILD NDEBUG32

To build the 32-bit debug version in the ODBCSDK\SAMPLES\SMPLDRVR\DEBUG32 directory, type:

   BUILD DEBUG32

Unrecognized arguments to BUILD.BAT will halt compilation with a warning.

BUILD.BAT calls NMAKE, the Microsoft Program Maintenance Utility provided with Microsoft C version 7.0 or later, on the file MAKEFILE to rebuild the DLL. If MAKEFILE is unmodified, BUILD.BAT will rebuild the original SAMPLE.DLL driver (SAMPLE32.DLL on Windows NT).

For information on using NMAKE, see your C compiler tools documentation.

Note   SAMPLE.DLL is a large-model DLL. Accordingly, to build SAMPLE.DLL, you must have installed both the Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later with the large-model option set. (Windows NT is a flat-memory model environment, so the small/medium/large model options don't apply. The 32-bit sample will compile correctly using the Windows NT Software Development Kit.)

For more information on the large-model option, see your Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later installation guides.

OTHER REQUIRED FILES

The LIBENTRY.OBJ file, included in the Windows 3.1 SDK, must be also be present to make SAMPLE.DLL. The resultant files (.RES, .DLL, and .MAP, and corresponding .OBJ files for each of the C source files listed previous) are placed in the appropriate directory, (depending on the build option).


DLL Viewer / Translation Spy Contents

This file contains the following information:

What DLL Viewer / Translation Spy Demonstrates

DLL Viewer / Translation Spy Files

How to Build DLL Viewer / Translation Spy

DLL Viewer: TRANSPEC.EXE

Translation Spy: TRNSLCHK.DLL


What DLL Viewer / Translation Spy Demonstrates

This demo consists of two programs, as follows:

DLL Viewer    A translation DLL configuration utility (TRANSPEC.EXE). DLL Viewer is a Windows application that allows you to edit the TRNSLCHK.INI file. All translation functionality is implemented in Translation Spy. While TRANSPEC.EXE allows you to specify that a translation DLL is to be loaded, it does not load the DLL. This is done by Translation Spy at run time.

DLL Viewer displays all DLLs currently loaded in memory, which you can selectively unload. This is useful for unloading DLLs that remain in memory after an application that loads it fails or the DLL itself fails.

Translation Spy    A translation DLL (TRNSLCHK.DLL). Translation Spy shows the basic requirements for writing a translation DLL. As a sample, you may use it to check that your driver is making the correct calls during translations.

FEATURES

Can be used to test calls made by a driver to a translation DLL

Can be used to debug other translation DLLs

Can trace function calls to SQLDriverToDataSource and SQLDataSourceToDriver

Can filter displayed data types

Allows for ad hoc testing of the translation API

LIMITATIONS

Only 16-bit versions of DLL Viewer / Translation Spy are provided. The DLL Viewer does not work on a 32-bit environment. However, Translation Spy will work on both 16- and 32-bit environments.

Only one instance of Translation Spy can be loaded at a time. Having more than one loaded may cause unpredictable behavior.

You can only view the data being translated; you cannot modify this data.


DLL Viewer / Translation Spy Files

FILES LOCATION

The DLL Viewer / Translation Spy source code resides in the \ODBCSDK\SAMPLES\TRNSLCHK directory. The 16-bit executable file TRANSPEC.EXE and TRNSLCHK.DLL are located in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

ABOUTBOX.DLG

Dialog templates for the About dialog box.

OPTIONS.C

Maintain the Options dialog box and allows the user to change all the options, including the filters. This file is used by both TRNSLCHK.DLL and TRANSPEC.EXE. In addition, this module contains the information needed to display the About dialog box.

OPTIONS.DLG

Dialog templates for the Options dialog box.

OPTIONS.H

Prototypes and definitions for OPTIONS.C.

TRANSPEC.C

Main module for DLL Viewer. Maintains the dialog box that displays the current libraries which are loaded on the system.

TRANSPEC.DEF

Module definition file for DLL Viewer.

TRANSPEC.H

Prototypes and definitions for TRANSPEC.C.

TRANSPEC.ICO

DLL Viewer / Translation Spy icon.

TRANSPEC.RC

Resource file for DLL Viewer.

TRNSLCHK.C

Main module for Translation Spy. This DLL provides an ad hoc interface to the translation DLL functions, SQLDriverToDataSource and SQLDataSourceToDriver.

TRNSLCHK.DEF

Module definition file for Translation Spy.

TRNSLCHK.H

Definitions and macros for TRNSLCHK.C.

TRNSLCHK.RC

Resource file for Translation Spy.


How to Build DLL Viewer / Translation Spy

The files \ODBCSDK\SAMPLES\TRNSLCHK\TRANSPEC.MAK and \ODBCSDK\SAMPLES\TRNSLCHK\TRNSLCHK.MAK are set up for compilation within a 16-bit environment. You use the \ODBCSDK\SAMPLES\TRNSLCHK\BUILD.BAT file to set up the proper environment and invoke the appropriate compiler and linker.

To build the sample, change to the \ODBCSDK\SAMPLES\TRNSLCHK directory, then:

To build the 16-bit release version in the \ODBCSDK\SAMPLES\TRNSLCHK\NDEBUG16 directory, type:

BUILD NDEBUG16

To build the 16-bit debug version in the \ODBCSDK\SAMPLES\TRNSLCHK\DEBUG16 directory, type:

BUILD DEBUG16

Unrecognized arguments to BUILD.BAT will halt compilation with a warning.

BUILD.BAT calls NMAKE, the Microsoft Program Maintenance Utility provided with Microsoft C version 7.0 or later, on the files TRANSPEC.MAK and TRNSLCHK.MAK to rebuild the files. If the makefiles are unmodified, BUILD.BAT will rebuild the original files.

For information on using NMAKE, see your C compiler tools documentation.

Note   TRNSLCHK.DLL is a large-model program. Accordingly, to build it you must have installed both the Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later with the large-model option set.

For more information on the large-model option, see your Microsoft Windows 3.1 SDK and Microsoft C version 7.0 or later installation guides.


DLL Viewer: TRANSPEC.EXE

HOW TO RUN DLL VIEWER

You can run DLL Viewer by double-clicking the DLL Viewer / Translation Spy icon in the ODBC SDK program group, or by choosing File/Run in the File Manager or Program Manager and typing \ODBCSDK\BIN\TRANSPEC.EXE in the Command Line box.

DLL VIEWER DIALOG BOX

DLL Viewer uses the TOOLHELP.DLL to show all of the currently loaded DLLs on the system. Here is a description of the dialog box:

Libraries list box

A list of loaded DLLs on the system, as returned by TOOLHELP.DLL.

Library Statistics

Provides information about the selected DLL. This information is updated when you select a different DLL from the Libraries list box.

hModule

The hInstance of the loaded library.

Load Count

The current load count on the DLL.

System Statistics

Provides information about the operating system.

Free Memory

The available memory on the current system.

Free Resources

The percent of free space on the system.

Version

The version of Windows being run.

CPU

The system microprocessor.

Refresh button

Update the Libraries list box and statistics.

Close button

Closes DLL Viewer.

Unload button

Calls the FreeLibrary function on the selected DLL as many times as the value of Load Count. When the Load Count is 0, Windows unloads the DLL from memory.

Note   Use care when using the Unload button. You can cause a GP fault by unloading a DLL at the wrong time.

Options button

Displays the Options dialog box, as follows:

Translate Entry edit box

The specified entry is a name for a list of Options configurations, which may or may not use a translation DLL, and the tracing/display options associated with them. These configurations are saved in the TRNSLCHK.INI file. The TRNSLCHK entry should be used if you are not using your own translation DLL. To specify a configuration for your own translation DLL, type in the new name and specify the Options values for the new entry. For more information, see "Testing a Translation DLL," following.

Trace File

The name of the log file, if tracing is being done. To specify a trace file, choose the Trace button.

Translation DLL

The full path name of the user translation DLL to be loaded and called by TRNSLCHK.DLL. To specify your own translation DLL, choose the Translate button.

Process Options

Allows you to set the following options:

Trace check box   If selected, calls to SQLDriverToDataSource and SQLDataSourceToDriver are logged in the specified Trace File.

Call Translation DLL check box   If selected, TRNSLCHK.DLL loads the specified Translation DLL.

Display check box   If selected, calls to SQLDriverToDataSource and SQLDataSourceToDriver which meet the filter criteria are displayed in the Function dialog box.

Set Default button

Sets the value in Translation Entry to be the default to use when TRNSLCHK.DLL is loaded.

Delete button

Removes the current Translate Entry from the TRNSLCHK.INI file.

Done button

Closes the Options dialog box.

Save button

Saves any changes made to the current Translate Entry to the TRNSLCHK.INI file.

About button

Displays version information for DLL Viewer.

Trace button

Enables you to specify a log file for tracing. After choosing a log file, the filename is displayed in Trace File, and the Trace check box is selected.

Translate button

Enables you to specify a translation DLL to be loaded and called by TRNSLCHK.DLL. After choosing a translation DLL, the filename is displayed in Translation DLL, and the Call Translation DLL check box is selected.

Filter button

Opens the Filter dialog box to allow a filter value to be specified for the current entry.

There are times when only certain data types are required by a trace. For example, you may just want to see SQL_CHAR values. This can be accomplished by specifying a filter for a translation entry. You use the Filter dialog box to define a filter. All selected data types will be included for both display and tracing for that entry. Any cleared data types are not processed.

Help button

Displays this Help file.

MODIFYING TRNSLCHK.INI

DLL Viewer allows you to modify TRNSLCHK.INI through the Options dialog box. For a description of the Options dialog box, see the previous section. DLL Viewer is designed so that options can be changed without loading Translation Spy (TRNSLCHK.DLL).

Note   If TRNSLCHK.DLL is already loaded, then it should be used to change the options, since TRANSPEC.EXE will simply set the options in the .INI file.

TESTING A TRANSLATION DLL

DLL Viewer allows you to test a translation DLL under development. DLL Viewer loads Translation Spy (TRNSLCHK.DLL), which in turn loads the translation DLL you specify. Because Translation Spy captures each call to SQLDriverToDataSource and SQLDataSourceToDriver, you can view how data is being translated by your translation DLL.

To use TRNSLCHK.DLL in this manner:

1.	Run DLL Viewer (see "How to Run DLL Viewer," previous).

2.	Choose the Options button. The Options dialog box appears.

3.	Type the name of the new entry in the Translate Entry box. Then choose the Translate button. The Open dialog box appears.

4.	Select the translation DLL you want to use and then choose the OK button. The Open dialog box disappears.

5.	Choose the Set Default button. Now all calls to TRNSLCHK.DLL are caught from the driver, then passed to your DLL. In this manner you can test the following scenarios:

Input from the driver

Input to a translation DLL

Output from a translation DLL

Output to a driver


Translation Spy: TRNSLCHK.DLL

LOADING TRNSLCHK.DLL

There are two methods to loading TRNSLCHK.DLL:

Using the SQLSetConnectOption function

Making entries in the ODBC.INI file.

USING THE SQLSetConnectOption FUNCTION

1.	Call SQLSetConnectOption with fOption of SQL_TRANSLATE_DLL and vParam set to TRNSLCHK.DLL.

2.	The driver should verify that the given name is a valid translation DLL, load it, and save it as the translation DLL for the connection.

3.	If successful, you should call SQLSetConnectOption with fOption of SQL_TRANSLATE_OPTION, and a vParam with the desired option.

EXAMPLE

In the following example, an application connects to a data source and establishes TRNSLCHK.DLL as its translation DLL (for simplicity no error checking is shown. It is assumed that TRNSLCHK.DLL is on the search path for LoadLibrary).

#include <sql.h>
#include <sqlext.h>

BOOL FAR PASCAL UserConnect()
{
   RETCODE      rc;
   HENV      henv;
   HDBC      hdbc;

   rc = SQLAllocEnv(&henv);
   rc = SQLAllocConnect(henv, &hdbc);
   rc = SQLConnect(hdbc, "EmpData", SQL_NTS,
                         "JohnS", SQL_NTS,
                         "Sesame", SQL_NTS);
   rc = SQLSetConnectOption(hdbc, SQL_TRANSLATE_DLL, "TRNSLCHK.DLL");
   rc = SQLSetConnectOption(hdbc, SQL_TRANSLATE_OPTION, 1);

   /* Do whatever, everything is logged or displayed */
   rc = SQLDisconnect(hdbc);
   rc = SQLFreeConnect(hdbc);
   rc = SQLFreeEnv(henv);
   return TRUE;
}

Note   An easy way to test this is to use ODBC Test.

MAKING ENTRIES IN THE ODBC.INI FILE

Using SQLSetConnectOption assumes that the application writer knows what the translation DLL is going to be while writing the application. This is not always true, however. For example, if code page translations are required between an ODBC application and the server, they could be done in a translation DLL. The driver, however, does not always know which code pages are going to be translated, and should not assume anything. Instead, the technique of making entries in the ODBC.INI file should be used.

Note   Users are generally discouraged from modifying the ODBC.INI file without using the ODBC Administrator or a similar utility. A more efficient method of making the changes listed here is to have a setup DLL which handles the SQLConfigTranslators function. Since Translation Spy does not have such a setup DLL, use caution when modifying the ODBC.INI file. For more information about the ODBC.INI file, see the Microsoft ODBC SDK Programmer's Reference.

The following example shows a data source section in the ODBC.INI file, which indicates what its translation DLL and option should be:

[myserver]
Driver=c:\windows\system\mydriver.dll
TranslationName=Translation DLL Sample
TranslationDLL=c:\windows\system\TRNSLCHK.dll
TranslationOption=0

When processing a connection to a data source, the driver looks for the TranslationDLL and TranslationOption keywords in the ODBC.INI file. If found, it establishes the translation DLL and option listed for the connection. This has the same net effect as calling SQLSetConnectOption directly.

TRNSLCHK.DLL FUNCTION DIALOG BOX

When TRNSLCHK.DLL is loaded, a call to SQLDriverToDataSource or SQLDataSourceToDriver will open a dialog box for the function called. The dialog box displays all arguments in the two functions. Following is a description of the dialog box:

Return

This is the value to return to the caller, which in all cases is the driver itself.

fOption

The default value is the value either set directly with SQLSetConnectOption (fOption of SQL_TRANSLATE_OPTION), or by specifying the TranslationOption keyword in ODBC.INI for the data source.

fSqlType/fCType

The SQL or C data type for the argument, as applicable.

rgbValueIn

The buffer to translate from.

cbValueIn

The size in bytes of rgbValueIn.

rgbValueOut

The output buffer, which can be the same as rgbValueIn (in-place translation).

cbValueOutMax

The maximum number of bytes which can be written to rgbValueOut.

pcbValueOut

The number of bytes written to rgbValueOut.

Edit Buffer

The large edit box shows the contents of rgbValueIn. The value of cbValueIn is used to determine what is to be translated. If a byte contains 0x00, then a '.' is substituted and displayed.

szErrorMsg

Error message.

cbErrorMsgMax

Maximum size in bytes of szErrorMsg.

pcbErrorMsg

The size in bytes of szErrorMsg.

Debug Information

This section indicates where logging of calls is placed (if logging is enabled) and where the values are coming from. The "Direction" message will give you one of the following values if you also have your own translation DLL loaded:

From client to server (pre)

Calling SQLDriverToDataSource, immediately after call from driver but just before call to user translation DLL

From client to server (post)

Calling SQLDriverToDataSource immediately after call to user translation DLL, just before return to driver.

From server to client (pre)

Calling SQLDataSourceToDriver immediately after call from driver, just before call to user translation DLL.

From server to client (post)

Calling SQLDataSourceToDriver immediately after call to user translation DLL, just before return to driver.

If you are not loading your own translation DLL, the "Direction" value will be one of the following:

From client to server

The call from the driver to SQLDriverToDataSource. Return will be directly to driver.

From server to client

The call from the driver to SQLDataSourceToDriver. Return will be directly to the driver.

OK button

Proceeds to the next function call, if there is one; otherwise, it returns.

Reset All button

Sets all arguments back to their original values when the dialog box was first displayed.

Options button

Displays the Options dialog, described as follows:

Translate Entry edit box

The specified entry is a name for a list of Options configurations, which may or may not use a translation DLL, and the tracing/display options associated with them. These configurations are saved in the TRNSLCHK.INI file. The TRNSLCHK entry should be used if you are not using your own translation DLL. To specify a configuration for your own translation DLL, type in the new name and specify the Options values for the new entry. For more information, see "Testing a Translation DLL," following.

Trace File

The name of the log file, if tracing is being done. To specify a trace file, choose the Trace button.

Translation DLL

The full path name of the user translation DLL to be loaded and called by TRNSLCHK.DLL To specify a your own translation DLL, choose the Translate button.

Process Options

Allows you to set the following options:

Trace check box   If selected, calls to SQLDriverToDataSource and SQLDataSourceToDriver are logged in the specified Trace File.

Call Translation DLL check box   If selected, TRNSLCHK.DLL loads the specified Translation DLL.

Display check box   If selected, calls to SQLDriverToDataSource and SQLDataSourceToDriver which meet the filter criteria are displayed in the Function dialog box.

Set Default button

Sets the value in Translation Entry to be the default to use when TRNSLCHK.DLL is loaded.

Delete button

Removes the current Translate Entry from the TRNSLCHK.INI file.

Done button

Closes the Options dialog box.

Save button

Saves any changes made to the current Translate Entry to the TRNSLCHK.INI file.

About button

Displays version information for DLL Viewer.

Trace button

Enables you to specify a log file for tracing. After choosing a log file, the filename is displayed in Trace File, and the Trace check box is selected.

Translate button

Enables you to specify a translation DLL to be loaded and called by TRNSLCHK.DLL. After choosing a translation DLL, the filename is displayed in Translation DLL, and the Call Translation DLL check box is selected.

Filter button

Opens the Filter dialog box to allow a filter value to be specified for the current entry.

There are times when only certain data types are required by a trace. For example, you may just want to see SQL_CHAR values. This can be accomplished by specifying a filter for a translation entry. You use the Filter dialog box to define a filter. All selected data types will be included for both display and tracing for that entry. Any cleared data types are not processed.

Help button

Displays this Help file.

HOW TRANSLATION SPY WORKS

TRNSLCHK.DLL consists of two functions which intercept and interpret the information that is to be translated. These two functions, SQLDriverToDataSource and SQLDataSourceToDriver, must be available in any translation DLL.

SQLDriverToDataSource

Handles the translation of data which is being passed from the ODBC driver on the client, to the data source on the server.

SQLDataSourceToDriver

Handles the translation of data which is being passed from the data source on the server, back to the ODBC driver on the client.

Note   For description of these functions, see the Microsoft ODBC SDK Programmer's Reference.

TESTING AN ODBC DRIVER

Every ODBC-compliant driver should call the translation DLL functions SQLDriverToDataSource and SQLDataSourceToDriver to perform translations of data. These translations could be done to convert data from one code page to another, or for other user-defined purposes.

A developer of an ODBC driver can load TRNSLCHK.DLL as its translation DLL and then check each call to the two APIs accordingly. Depending on your options, each function call is captured by TRNSLCHK.DLL and displayed in a dialog box.


Visual Basic Demo Contents

This file contains the following information:

What VB Demo Demonstrates

VB Demo Files

How to Build VB Demo

How to Run VB Demo

VB Demo Menus and Toolbar

Making a Query with VB Demo


What VB Demo Demonstrates

VB Demo uses the ODBC API to enable you to connect to a data source, execute SQL queries, and retrieve results. In addition, VB Demo can display table information (using SQLTables) for a data source.

FEATURES

MULTIPLE CONNECTIONS

VB Demo allows multiple simultaneous connections to data sources.

QUERY EDIT BOX

The Query Edit box enables you to type valid SQL queries. The Options menu allows you to choose either single-line or multiple-line queries, and sizes the Query Edit box accordingly. To send the query, choose the Query button.

RESULTS WINDOW

The results window displays the results of valid queries. Errors are returned by message box. You can copy the results to the Clipboard using the commands in the Edit menu and change the display font using the Font menu.

AUTOMATIC DISCONNECT

When you exit VB Demo, all connections you have made are automatically closed.

LIMITATIONS

Maximum number of connections: 16

Maximum query size: 256 characters


VB Demo Files

FILES LOCATION

The VB Demo source code resides in the \ODBCSDK\SAMPLES\VBDEMO directory. The 16-bit executable file VBDEMO.EXE resides in the \ODBCSDK\BIN directory.

SOURCE CODE FILE CONTENTS

GRID.VBX

Contains custom controls required by VB Demo.

LOGON.FRM

Dialog box that enables the user to connect to a data source.

MISCPROC.BAS

Manages connections and fills the grid with data.

ODBC.BAS

Windows API declarations and constants.

ODBCOR_G.BI

Core ODBC API definitions and constants.

ODBCOR_M.BI

Core ODBC API function prototypes.

ODBEXT_G.BI

Extended ODBC API definitions, types, and constants.

ODBEXT_M.BI

Extended ODBC API function prototypes.

QUERY.FRM

Main form for VB Demo. Allows a user to enter SQL queries and view results.

SQLABOUT.FRM

Displays version information for VB Demo.

VBDEMO.BAS

Global module containing constant definitions, ODBC and Windows API declarations, and global variables used to maintain connection and statement handles.

VBDEMO.ICO

VB Demo icon.


How to Build VB Demo

From the Visual Basic File menu, choose Open Project and open the \ODBCSDK\SAMPLES\VBDEMO\VBDEMO.MAK file.

Then, from the File menu, choose Make .EXE File. The VBDEMO.EXE file will be built into your \ODBCSDK\SAMPLES\VBDEMO directory.

REQUIRED FILES

You must have installed the Visual Basic Professional version 3.0 in order to build the VB Demo.


How to Run VB Demo

You can run the VB Demo by double-clicking the ODBC/VB Sample icon from ODBC SDK program group, or by choosing to run the \ODBCSDK\BIN\VBDEMO.EXE file from the File Manager or Program Manager.

Important   The VBRUN300.DLL run-time library is required to run Visual Basic applications. This file is included in the \ODBCSDK\BIN directory.


VB Demo Menus and Toolbar

FILE MENU

PRINT

Prints the unformatted contents (screen shot) of the results window.

EXIT

Closes all open connections and then exits VB Demo.

EDIT MENU

COPY SELECTED CELL(S)

Copies data from selected cells to the Clipboard as text. The columns are separated by tabs, and the rows are separated by a carriage return-linefeed character.

COPY RESULTS

Copies all data from the grid to the Clipboard as text. The columns are separated by tabs, and the rows are separated by a carriage return-linefeed character.

CONNECTIONS MENU

ADD NEW CONNECTION

Opens the SQL Data Sources dialog box, which enables you to connect to a data source.

REMOVE CURRENT CONNECTION

Closes the connection displayed in the Current Connection box. (For information on the Current Connection box, see "VB Demo Toolbar," following.)

OPTIONS MENU

SINGLE-LINE QUERY

Switches the Query Edit box to single-line mode. (For information on the Query Edit box, see "VB Demo Toolbar," following.)

MULTI-LINE QUERY

Switches the Query Edit box to multiple-line mode. (For information on the Query Edit box, see "VB Demo Toolbar," following.)

FONTS MENU

NORMAL FONT

Changes the results window output font to normal.

ITALIC FONT

Changes the results window output font to italic.

BOLD FONT

Changes the results window output font to bold (default).

HELP MENU

CONTENTS

Opens the \ODBCSDK\HELP\ODBCSMPL.HLP file.

ABOUT

Displays version information for VB Demo.

VB DEMO TOOLBAR

CURRENT CONNECTION BOX

Displays the current connection. You may view other connections by selecting them from the list.

QUERY EDIT BOX

Enables you to type in an SQL query on the current connection.

TABLES BUTTON

Returns a result set containing information on all tables (uses SQLTables).

QUERY BUTTON

Sends the single- or multiple-line query in the Query Edit box.

DISCONNECT BUTTON

Disconnects VB Demo from the connection displayed in the Current Connection Box.


Making a Query with VB Demo

1.	From the Connections menu, choose Add New Connection. The SQL Data Sources dialog box appears.

2.	Choose the data source to which you want to connect VB Demo. Then choose the OK button. The SQL Data Sources dialog box disappears. VB Demo displays a message box to indicate a successful connection.

3.	Decide if you want to send a single-line or a multiple-line query. For a single-line query, choose Single-line Query from the Options menu. For a multiple-line query, choose Multi-line Query from the Options menu.

4.	In the Query Edit box, type the valid query you want to send. Then choose the Query button. VB Demo sends your query to the data source. If the query is successful, the results will be displayed in the results window. If the query is not successful, a message box will appear informing you. You can print or copy the query results at this time.

5.	Repeat steps 3 and 4 to make additional queries.

6.	When you have finished making queries, choose Exit from the File menu to exit VB Demo.