Win32::ODBC - Object

Contents

Part I

• Module Description
• Business Stuff
• Copyright Notice
• Disclaimer
• GNU General Public License
• Larry Wall's "Artistic License"
• Version History
• Author List
• Features/Limits
• Installation Instructions

Part II

• Creating an ODBC Object
• Object Methods
• Catalog()
• Connection()
• Close()
• Data()
• DataSources()
• Drivers()
• DumpData()
• Error()
• FetchRow()
• FieldNames()
• GetConnections()
• GetDSN()
• GetMaxBufSize()
• new()
• Run()
• SetMaxBufSize()
• Shutdown()
• Sql()
• TableList()
• Examples

Creating an ODBC Object

	use Win32::ODBC;

	$Data = new Win32::ODBC("MyDSN");

Make sure that you close your connection when you are finished:

	$Data->Close();

Object Methods

General Note

	use Win32::ODBC;

	$db = new Win32::ODBC("MyDSN");

Also, in an effort to keep the examples short, no error checking is done on return values for any calls other than the one being exemplified. You should always check for error conditions in production code.

WARNING: The example code has not yet been tested. This will be fixed ASAP, but be forwarned!

Methods

Catalog qualifier, owner, name, type

Retrieves the catalog from the current ODBC object. Returns a four-element array (Qualifier, Owner, Name, Type).

Example:
($qualifier, $owner, $name, $type) = $db->Catalog("", "", "%", "'TABLE'");

Connection

Returns the object's ODBC connection number.

Example:
$cnum = $db->Connection;

Close

Closes the ODBC connection for this object. [Note that the source code says that this will close "this ODBC session (or all sessions)". I am unsure what this means, and will ask Dave about it -- joe]. Example:

Example:
$db->Close();

Data list

Retrieve data from previous fetch for a list of fieldnames. In a scalar context it returns all of the field values concatenated together. In an array context, it returns an array of the values, in the order in which they were specified.

Example:
$db->Sql("SELECT f1, f2 FROM foo");
$db->FetchRow();
($f1, $f2) = $db->Data("f1", "f2");

or

$db->Sql("SELECT name FROM foo");
$db->FetchRow();
$name = $db->Data("name");

DataSources

Returns an associative array of Data Sources and ODBC remarks in the form of:

$ArrayName{'DSN'} = Remark

where DSN is the Data Source Name and Remark is, well, the remark.

Example:
%rem = $db->DataSources;
print LOG qq(Current DSN's Remark: "), %rem{$db->GetDSN}, qq("\n);

Drivers

Returns an associative array of Drivers and their attributes in the form of:

$ArrayName{'DRIVER'} = Attrib1;Attrib2;Attrib3;...

where DRIVER is the ODBC Driver Name and AttribX are the driver-defined attributes.

Example:
%attrib = $db->Drivers;
print LOG qq($driver: $attrib{$driver}\n) foreach $driver (keys %attrib);

DumpData

Dump to the screen all field names and the data in all rows of the current dataset. This is used primarily for debugging.

Example:
$db->Sql("Select * FROM foo");
$db->DumpData;

Error

Returns the last recorded error.

Example:
die $db->Error(), qq(\n);

FetchRow

Fetches the next row of data from the previous specified SQL statement. You would then call Data to actually retrieve the individual elements of data. Returns undef if there's an error, TRUE otherwise.

Example:
$db->Sql("SELECT * FROM foo");
$db->FetchRow() || die qq(Fetch error: ), $db->Error(), qq(\n);
$f1 = $db->Data("f1");

See also: Sql, Data

FieldNames

Returns a list of fieldnames extracted from the current dataset. This is used mostly for testing/debugging. FieldNames returns the data in an array, with no guarantee of the order of the names.

Example:
$db->Sql("SELECT * FROM foo");
$db->FetchRow();
foreach $fd ($db->FieldNames()) print qq($fd: "), $db->Data($fd), qq("\n);

GetConnections

Returns an array of connection numbers for all objects.

Example:
@cnums = $db->GetConnections;

GetDSN

GetDSN conn

Returns the DSN (Data Source Name) for the connection conn, or the current connection if not specified.

Example:
print LOG qq(Current connection: "), $db->GetDSN, qq("\n);

GetMaxBufSize

Returns the current maximum single field data size, in bytes.

Example:
$max = $db->GetMaxBufSize;
$db->SetMaxBufSize($needed) if ($max < $needed);

See also: SetMaxBufSize

new Win32::ODBC(DSN)

new Win32::ODBC(ODBCDriverConnect)

Creates a new ODBC object, given a DSN (Data Source Name) or a properly formatted ODBCDriverConnect string. Returns the created ODBC object or undef if there is an error.

Example:
$DSN = "MyDSN";
$db = new Win32::ODBC($DSN);
die qq(Cannot open new ODBC\n) if ! $db;

Run stmt

Submit the SQL statement stmt and print data about it. This is used only in debugging.

Example:
$db->Run("SELECT * FROM foo");

See also: Sql

SetMaxBufSize size

Sets the maximum buffer size that a single field can allocate when executing a FetchRow. The default limit is 10240 (10k) and the absolute maximum is set to 102400 (100k). This absolute maximum can be reset by recompiling the module. Returns undef if successful.

Example:
$newsize = 20480;
$rc = $db->SetMaxBufSize($newsize);
die qq(SetMaxBufSize($newsize) error: ), $db->Error, qq(\n) if ! $rc;

See also: GetMaxBufSize

ShutDown

Closes the ODBC connection and print data about it. This is used only in debugging.

Example:
$db->Shutdown;

See also: Close

Sql stmt

Executes the SQL command stmt. Returns undef on success, SQL error code on failure.

Example:
$stmt = "SELECT * FROM foo";
$rc = $db->Sql($stmt);
die qq(SQL failed "$stmt": ), $db->Error(), qq(\n) if $rc;

See also: Error

TableList

TableList qualifier, owner, name, type

Retrieves the list of table names from the current ODBC object using Catalog. If not specified, qualifier and owner default to "", name defaults to "%", and table defaults to "'TABLE'". TableList returns an array of table names.

Example:
@tables = $db->TableList;

See also: Catalog

Examples