# Win32::ODBC

The Win32::ODBC FAQ is now available! (be patient, it is still under construction)

## Contents

### Part I

- Module Description
- Business Stuff

- Latest Version
- Copyright Notice
- Disclaimer
- GNU General Public License
- Larry Wall's "Artistic License"

- Version History

- Author List

- Features/Limits
- Installation Instructions
- Bug Reports
- Latest Versions
- For More Information on Perl

### Part II

- Creating an ODBC Object
- Object Methods

- Catalog()
- Connection()
- Close()
- Data()
- DataHash()
- DataSources()
- Drivers()
- DumpError()
- DumpData()
- Error()
- FetchRow()
- FieldNames()
- GetConnections()
- GetDSN()
- GetStmtCloseType()
- GetMaxBufSize()
- MoreResults()
- new()
- RowCount()
- Run()
- SetMaxBufSize()
- SetStmtCloseType()
- Shutdown()
- Sql()
- TableList()

- Examples

## Module Description

## Business Stuff

ODBC extension for Win32 PERL
Latest version: Version 961011
by Dave Roth (rothd@roth.net)
Courtesy of Roth Consulting.
Based on code by Dan DeMaggio (dmag@umich.edu) -- Thanks Dan!

### Copyright

Copyright © 1996 Dave Roth. All rights reserved.
This program is free software; you can redistribute it or modify it under the same terms as PERL itself.

### Disclaimer

I do not guarantee ANYTHING with this package. If you use it you are doing so AT YOUR OWN RISK! I may or may not support this depending on my time schedule and I am neither an ODBC nor SQL guru so do not ask me questions regarding them!

### GNU General Public License

GNU Library General Public License - GNU Project

### Larry Wall's "Artistic License"

Artistic License

## Version History

ODBC.PM

Date | Changes
--- | ---
96.03.27 | Initial Release (rothd)
96.04.08 | Changed Data() to accept an array of field names, returning an array or scalar (joc)
Various bug fixes (joc)
96.04.10 | Fixed the RowCount() to default to the current connection (droth)
96.04.15 | Changed version numbers to a date format (rothd)
96.05.07 | Fixed Data(): If returning an array, the array consisted of the requested fieldnames + the values. Now only returns the values. Thanks to Dan Westerlund <westerlund@dkraft.se>! (rothd)
96.07.22 | Added MoreResults(): Checks to see if there are any more records that have not been retrieved. (dunfordshore)

96.07.22

Changed Error(): Errors are tracked differently now. Any error will record the error number ($ErrNum) and error text ($ErrText) in the object's name space and can be retrieved by calling $Database->Error(). Error() will also return the ODBC connection number that caused the error. If the context of the call is not an array then a string with this information will be returned. The Win32::ODBC name space will always have the last error info made, even if it is an error returned by the new method. You can call Win32::ODBC::Error() to get that. (rothd)

ODBC.PLL

Date | Changes
--- | ---
96.04.10 | Fixed a "memory bug": we were using SQL_CLOSE when closing an ODBC statement. This kept the cursor alive in memory so it can be cached in the event the same SQL statement is issued. We are now using SQL_DROP. This may lessen speed if the same SQL statements are issued again and again per connection. (rothd)
Cleaned up some code. (rothd)
96.04.12 | Added GetStmtCloseType() and SetStmtCloseType() functions. (rothd)
Added some constants. (rothd)
96.04.13 | ** We now are trying to include a version for builds up to and including 105 and another for builds 106 and greater (for now).
96.04.15 | Fix Bug in ODBCFetchRow(): when retrieving a field with a NULL value the value from the previous field was reported. (jmk)
Changed version numbers to a date format.
96.04.22 | Fix the SDWORD wrap-around bug in ODBCFetchRow(): when a column of size 2147483647 adding 1 (for a NULL byte in szBuf) yields -2147483648 (not easy to "net UCHAR (-2147483648)"!!) (jmk)
96.04.22 | Inspired by Jutta, I have increased the max limit for SetMaxBufSize() to 2,147,483,647 bytes. (rothd)
96.05.03 | Set the lowest allocated char array to be 20 bytes in ODBCFetchRow(). Evidentally sometimes the ODBC manager will report too few chars that are needed to represent an autonumber field. (rothd)
96.05.08 | Convert all results from ODBCTableList() to uppercase since different ODBC drivers impliment this differently (some uppercase some lower). Thanks again to Jutta M. Klebe. (rothd) *** This patch is open for suggestions!!! ***
96.07.22 | Added ODBCMoreResults(): Checks to see if there are any more records that have not been retrieved. (dunfordshore)

Author List

Abbreviation | Name | EMail
--- | --- | ---
rothd | Dave Roth | rothd@roth.net
joc | Joe Casadonte | joc@netaxs.com
jmk | Jutta M. Klebe | jmk@exc.bybyte.de
dunfordshore | Brian Dunfordshore | brian_dunfordshore@bridge.com

## Features/Limits

### Features

- The number of ODBC connections is limited only by memory and ODBC itself.
- The working limit to the size of a field is 10,240 bytes. This can be raised (if needed) to a maximum of 2,147,483,647 bytes (memory permitting).
- Connections can be opened using a DSN or connection string.
- Connections can be opened and closed in any order.
- Catalog (and TableList) functions are supported.
- Add, modify and remove DNS's.
- Transactions are supported (rollback and commit).
- GetInfo() is supported.
- Get/SetConnectOptions() is supported.
- Get/SetStmtOptions() is supported.
- The entire SQL_xxx constant set is supported.

### Limits

- If the account that the process runs under does not have write permission on the default directory (for the process, not the ODBC DSN) you will probably get a run-time error during an SQLConnection(). I don't think that this is a problem with the code, more like ODBC. This happens because some ODBC drivers need to write a temporary file. I noticed this using the MS Jet Engine (Access Driver).
- This has not been optimized for speed nor optimized for memory consumption. This may run into memory bloat.
- Release versions are compiled for a 486 processor. I have no idea what problems you may run into if you use a 386, but then again, if you are using a 368 then I doubt that you are using a Win32 OS.
- When adding a DSN you can not specify it to be a System DSN; it will automatically be a user DSN.

## Installation Instructions

1. Copy the ODBC.PM file into the \PERL\LIB\WIN32 directory.
2. Copy the ODBC.PLL file into the \PERL\LIB\AUTO\WIN32\ODBC\ directory.
3. Define a DSN (Data Source Name) and ensure that you have everything you need to use it normally (ODBC drivers, database files, etc.)
4. You are now ready to ODBC all over town!

## Bug Reports

Please send bug reports to Dave Roth. Include the following (if appropriate):

- Versions of both Perl and ODBC.
- ODBC data source type (Oracle, Access, etc).
- Which ODBC system you are using (Microsoft's, Visigenic's, etc).
- Short description of the problem.
- Small code example which you have tested to ensure that it reproduces the problem as described.
- Output of the code exmaple.

What version of Perl and ODBC do I have?

To find version numbers you need to:

- Perl:
  From a command line enter: `perl -v`
- ODBC:
  Run the ODBC Administrator, select the driver you are using and hit the About button.
- Win32::ODBC:
  In later versions you can select the `ODBC.PLL` file from the file manager or explorer and examine its properties. In older versions (and new ones also) just run the `test.pl` that came with the Win32::ODBC package.

## Obtaining the Latest Versions

- Win32::ODBC - ftp.roth.net
- Perl for Win32 - ftp.hip.com

## For More Information on Perl

CPAN - Comprehensive Perl Archive Network - Selected Sites

- ftp.metronet.com (Texas)
- ftp.cdrom.com (California)
- ftp.cis.ufl.edu (Florida)
- mango.pinc.com (British Columbia)
- ftp.funet.fi (Finland) [Master CPAN site]
- ftp.cs.ruu.nl (The Netherlands)
- ftp.sunet.se (Sweden)
- ftp.demon.co.uk (United Kindom)
- coombs.anu.edu.au (Australia)

This page maintined by Joe Casadonte. Please let me if something is wrong or does not make sense. Send these or other comments to: joc@netaxs.com.