Chip 2000 May

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _63c72fb9580cf0d4746525ac0e3b2af9 < prev next >

Wrap

Text File | 2000-03-23 | 24.4 KB | 566 lines

<HTML> <HEAD> <TITLE>Win32::ODBC - ODBC Extension for Win32</TITLE> <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Win32::ODBC - ODBC Extension for Win32 </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <UL> <LI><A HREF="#background">Background</A></LI> <LI><A HREF="#benefits">Benefits</A></LI> </UL> <LI><A HREF="#constants">CONSTANTS</A></LI> <LI><A HREF="#special notation">SPECIAL NOTATION</A></LI> <LI><A HREF="#constructor">CONSTRUCTOR</A></LI> <LI><A HREF="#methods">METHODS</A></LI> <LI><A HREF="#limitations">LIMITATIONS</A></LI> <LI><A HREF="#installation notes">INSTALLATION NOTES</A></LI> <LI><A HREF="#other documentation">OTHER DOCUMENTATION</A></LI> <LI><A HREF="#author">AUTHOR</A></LI> <LI><A HREF="#credits">CREDITS</A></LI> <LI><A HREF="#disclaimer">DISCLAIMER</A></LI> <LI><A HREF="#history">HISTORY</A></LI> <LI><A HREF="#copyright">COPYRIGHT</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> Win32::ODBC - ODBC Extension for Win32 <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> To use this module, include the following statement at the top of your script: <PRE> use Win32::ODBC;</PRE> Next, create a data connection to your DSN: <PRE> $Data = new Win32::ODBC("MyDSN");</PRE> NOTE: MyDSN can be either the DSN as defined in the ODBC Administrator, or it can be an honest-to-God DSN Connect String. <PRE> Example: "DSN=My Database;UID=Brown Cow;PWD=Moo;"</PRE> You should check to see if <CODE>$Data</CODE> is indeed defined, otherwise there has been an error. You can now send SQL queries and retrieve info to your heart's content! See the description of the methods provided by this module below and also the file TEST.PL as referred to in <A HREF="#installation notes">INSTALLATION NOTES</A> to see how it all works. Finally, MAKE SURE that you close your connection when you are finished: <PRE> $Data->Close();</PRE> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> <H2><A NAME="background">Background</A></H2> This is a hack of Dan DeMaggio's <<A HREF="mailto:dmag@umich.edu">dmag@umich.edu</A>> NTXS.C ODBC implementation. I have recoded and restructured most of it including most of the ODBC.PM package, but its very core is still based on Dan's code (thanks Dan!). The history of this extension is found in the file HISTORY.TXT that comes with the original archive (see <A HREF="#installation notes">INSTALLATION NOTES</A> below). <H2><A NAME="benefits">Benefits</A></H2> And what are the benefits of this module? <UL> <LI> The number of ODBC connections is limited by memory and ODBC itself (have as many as you want!). <LI> The working limit for the size of a field is 10,240 bytes, but you can increase that limit (if needed) to a max of 2,147,483,647 bytes. (You can always recompile to increase the max limit.) <LI> You can open a connection by either specifing a DSN or a connection string! <LI> You can open and close the connections in any order! <LI> Other things that I can not think of right now... :) </UL> <HR> <H1><A NAME="constants">CONSTANTS</A></H1> This package defines a number of constants. You may refer to each of these constants using the notation <CODE>ODBC::xxxxx</CODE>, where <CODE>xxxxx</CODE> is the constant. Example: <PRE> print ODBC::SQL_SQL_COLUMN_NAME, "\n";</PRE> <HR> <H1><A NAME="special notation">SPECIAL NOTATION</A></H1> For the method documentation that follows, an * following the method parameters indicates that that method is new or has been modified for this version. <HR> <H1><A NAME="constructor">CONSTRUCTOR</A></H1> <DL> <DT><A NAME="item_new">new ( ODBC_OBJECT | DSN [, (OPTION1, VALUE1), (OPTION2, VALUE2) ...] ) *</A> <DD> Creates a new ODBC connection based on <CODE>DSN</CODE>, or, if you specify an already existing ODBC object, then a new ODBC object will be created but using the ODBC Connection specified by <CODE>ODBC_OBJECT</CODE>. (The new object will be a new hstmt using the hdbc connection in <CODE>ODBC_OBJECT</CODE>.) <CODE>DSN</CODE> is Data Source Name or a proper <CODE>ODBCDriverConnect</CODE> string. You can specify SQL Connect Options that are implemented before the actual connection to the DSN takes place. These option/values are the same as specified in <A HREF="#item_GetConnectOption"><CODE>GetConnectOption</CODE></A>/<A HREF="#item_SetConnectOption"><CODE>SetConnectOption</CODE></A> (see below) and are defined in the ODBC API specs. Returns a handle to the database on success, or undef on failure. </DL> <HR> <H1><A NAME="methods">METHODS</A></H1> <DL> <DT><A NAME="item_Catalog">Catalog ( QUALIFIER, OWNER, NAME, TYPE )</A> <DD> Tells ODBC to create a data set that contains table information about the DSN. Use <CODE>Fetch</CODE> and <A HREF="#item_Data"><CODE>Data</CODE></A> or <A HREF="#item_DataHash"><CODE>DataHash</CODE></A> to retrieve the data. The returned format is: <PRE> [Qualifier] [Owner] [Name] [Type]</PRE> Returns true on error. <DT><A NAME="item_ColAttributes">ColAttributes ( ATTRIBUTE [, FIELD_NAMES ] )</A> <DD> Returns the attribute <CODE>ATTRIBUTE</CODE> on each of the fields in the list <CODE>FIELD_NAMES</CODE> in the current record set. If <CODE>FIELD_NAMES</CODE> is empty, then all fields are assumed. The attributes are returned as an associative array. <DT><A NAME="item_ConfigDSN">ConfigDSN ( OPTION, DRIVER, ATTRIBUTE1 [, ATTRIBUTE2, ATTRIBUTE3, ... ] )</A> <DD> Configures a DSN. <CODE>OPTION</CODE> takes on one of the following values: <PRE> ODBC_ADD_DSN.......Adds a new DSN. ODBC_MODIFY_DSN....Modifies an existing DSN. ODBC_REMOVE_DSN....Removes an existing DSN.</PRE> <PRE> ODBC_ADD_SYS_DSN.......Adds a new System DSN. ODBC_MODIFY_SYS_DSN....Modifies an existing System DSN. ODBC_REMOVE_SYS_DSN....Removes an existing System DSN.</PRE> You must specify the driver <CODE>DRIVER</CODE> (which can be retrieved by using <A HREF="#item_DataSources"><CODE>DataSources</CODE></A> or <A HREF="#item_Drivers"><CODE>Drivers</CODE></A>). <CODE>ATTRIBUTE1</CODE> should be ``DSN=xxx'' where xxx is the name of the DSN. Other attributes can be any DSN attribute such as: <PRE> "UID=Cow" "PWD=Moo" "Description=My little bitty Data Source Name"</PRE> Returns true on success, false on failure. NOTE 1: If you use <CODE>ODBC_ADD_DSN</CODE>, then you must include at least ``DSN=xxx'' and the location of the database. Example: For MS Access databases, you must specify the DatabaseQualifier: <PRE> "DBQ=c:\\...\\MyDatabase.mdb"</PRE> NOTE 2: If you use <CODE>ODBC_MODIFY_DSN</CODE>, then you need only specify the ``DNS=xxx'' attribute. Any other attribute you include will be changed to what you specify. NOTE 3: If you use <CODE>ODBC_REMOVE_DSN</CODE>, then you need only specify the ``DSN=xxx'' attribute. <DT><A NAME="item_Connection">Connection ()</A> <DD> Returns the connection number associated with the ODBC connection. <DT><A NAME="item_Close">Close ()</A> <DD> Closes the ODBC connection. No return value. <DT><A NAME="item_Data">Data ( [ FIELD_NAME ] )</A> <DD> Returns the contents of column name <CODE>FIELD_NAME</CODE> or the current row (if nothing is specified). <DT><A NAME="item_DataHash">DataHash ( [ FIELD1, FIELD2, ... ] )</A> <DD> Returns the contents for <CODE>FIELD1, FIELD2, ...</CODE> or the entire row (if nothing is specified) as an associative array consisting of: <PRE> {Field Name} => Field Data</PRE> <DT><A NAME="item_DataSources">DataSources ()</A> <DD> Returns an associative array of Data Sources and ODBC remarks about them. They are returned in the form of: <PRE> $ArrayName{'DSN'}=Driver</PRE> where DSN is the Data Source Name and ODBC Driver used. <DT><A NAME="item_Debug">Debug ( [ 1 | 0 ] )</A> <DD> Sets the debug option to on or off. If nothing is specified, then nothing is changed. Returns the debugging value (1 or 0). <DT><A NAME="item_Drivers">Drivers ()</A> <DD> Returns an associative array of ODBC Drivers and their attributes. They are returned in the form of: <PRE> $ArrayName{'DRIVER'}=Attrib1;Attrib2;Attrib3;...</PRE> where DRIVER is the ODBC Driver Name and AttribX are the driver-defined attributes. <DT><A NAME="item_DropCursor">DropCursor ( [ CLOSE_TYPE ] )</A> <DD> Drops the cursor associated with the ODBC object. This forces the cursor to be deallocated. This overrides <A HREF="#item_SetStmtCloseType"><CODE>SetStmtCloseType</CODE></A>, but the ODBC object does not lose the <CODE>StmtCloseType</CODE> setting. <CODE>CLOSE_TYPE</CODE> can be any valid <CODE>SmtpCloseType</CODE> and will perform a close on the stmt using the specified close type. Returns true on success, false on failure. <DT><A NAME="item_DumpData">DumpData ()</A> <DD> Dumps to the screen the fieldnames and all records of the current data set. Used primarily for debugging. No return value. <DT><A NAME="item_Error">Error ()</A> <DD> Returns the last encountered error. The returned value is context dependent: If called in a scalar context, then a 3-element array is returned: <PRE> ( ERROR_NUMBER, ERROR_TEXT, CONNECTION_NUMBER )</PRE> If called in a string context, then a string is returned: <PRE> "[ERROR_NUMBER] [CONNECTION_NUMBER] [ERROR_TEXT]"</PRE> If debugging is on then two more variables are returned: <PRE> ( ..., FUNCTION, LEVEL )</PRE> where <CODE>FUNCTION</CODE> is the name of the function in which the error occurred, and <CODE>LEVEL</CODE> represents extra information about the error (usually the location of the error). <DT><A NAME="item_FetchRow">FetchRow ( [ ROW [, TYPE ] ] )</A> <DD> Retrieves the next record from the keyset. When <CODE>ROW</CODE> and/or <CODE>TYPE</CODE> are specified, the call is made using <CODE>SQLExtendedFetch</CODE> instead of <CODE>SQLFetch</CODE>. NOTE 1: If you are unaware of <CODE>SQLExtendedFetch</CODE> and its implications, stay with just regular <A HREF="#item_FetchRow"><CODE>FetchRow</CODE></A> with no parameters. NOTE 2: The ODBC API explicitly warns against mixing calls to <CODE>SQLFetch</CODE> and <CODE>SQLExtendedFetch</CODE>; use one or the other but not both. If ROW is specified, it moves the keyset RELATIVE <CODE>ROW</CODE> number of rows. If ROW is specified and <CODE>TYPE</CODE> is not, then the type used is RELATIVE. Returns true when another record is available to read, and false when there are no more records. <DT><A NAME="item_FieldNames">FieldNames ()</A> <DD> Returns an array of fieldnames found in the current data set. There is no guarantee on order. <DT><A NAME="item_GetConnections">GetConnections ()</A> <DD> Returns an array of connection numbers showing what connections are currently open. <DT><A NAME="item_GetConnectOption">GetConnectOption ( OPTION )</A> <DD> Returns the value of the specified connect option <CODE>OPTION</CODE>. Refer to ODBC documentation for more information on the options and values. Returns a string or scalar depending upon the option specified. <DT><A NAME="item_GetCursorName">GetCursorName ()</A> <DD> Returns the name of the current cursor as a string or undef. <DT><A NAME="item_GetData">GetData ()</A> <DD> Retrieves the current row from the dataset. This is not generally used by users; it is used internally. Returns an array of field data where the first element is either false (if successful) and true (if not successful). <DT><A NAME="item_getDSN">getDSN ( [ DSN ] )</A> <DD> Returns an associative array indicating the configuration for the specified DSN. If no DSN is specified then the current connection is used. The returned associative array consists of: <PRE> keys=DSN keyword; values=Keyword value. $Data{$Keyword}=Value</PRE> <DT><A NAME="item_GetFunctions">GetFunctions ( [ FUNCTION1, FUNCTION2, ... ] )</A> <DD> Returns an associative array indicating the ability of the ODBC Driver to support the specified functions. If no functions are specified, then a 100 element associative array is returned containing all possible functions and their values. <CODE>FUNCTION</CODE> must be in the form of an ODBC API constant like <CODE>SQL_API_SQLTRANSACT</CODE>. The returned array will contain the results like: <PRE> $Results{SQL_API_SQLTRANSACT}=Value</PRE> Example: <PRE> $Results = $O->GetFunctions( $O->SQL_API_SQLTRANSACT, SQL_API_SQLSETCONNECTOPTION ); $ConnectOption = $Results{SQL_API_SQLSETCONNECTOPTION}; $Transact = $Results{SQL_API_SQLTRANSACT};</PRE> <DT><A NAME="item_GetInfo">GetInfo ( OPTION )</A> <DD> Returns a string indicating the value of the particular option specified. <DT><A NAME="item_GetMaxBufSize">GetMaxBufSize ()</A> <DD> Returns the current allocated limit for MaxBufSize. For more info, see <A HREF="#item_SetMaxBufSize"><CODE>SetMaxBufSize</CODE></A>. <DT><A NAME="item_GetSQLState">GetSQLState () *</A> <DD> Returns a string indicating the SQL state as reported by ODBC. The SQL state is a code that the ODBC Manager or ODBC Driver returns after the execution of a SQL function. This is helpful for debugging purposes. <DT><A NAME="item_GetStmtCloseType">GetStmtCloseType ( [ CONNECTION ] )</A> <DD> Returns a string indicating the type of closure that will be used everytime the hstmt is freed. See <A HREF="#item_SetStmtCloseType"><CODE>SetStmtCloseType</CODE></A> for details. By default, the connection of the current object will be used. If <CODE>CONNECTION</CODE> is a valid connection number, then it will be used. <DT><A NAME="item_GetStmtOption">GetStmtOption ( OPTION )</A> <DD> Returns the value of the specified statement option <CODE>OPTION</CODE>. Refer to ODBC documentation for more information on the options and values. Returns a string or scalar depending upon the option specified. <DT><A NAME="item_MoreResults">MoreResults ()</A> <DD> This will report whether there is data yet to be retrieved from the query. This can happen if the query was a multiple select. Example: <PRE> "SELECT * FROM [foo] SELECT * FROM [bar]"</PRE> NOTE: Not all drivers support this. Returns 1 if there is more data, undef otherwise. <DT><A NAME="item_RowCount">RowCount ( CONNECTION )</A> <DD> For UPDATE, INSERT and DELETE statements, the returned value is the number of rows affected by the request or -1 if the number of affected rows is not available. NOTE 1: This function is not supported by all ODBC drivers! Some drivers do support this but not for all statements (e.g., it is supported for UPDATE, INSERT and DELETE commands but not for the SELECT command). NOTE 2: Many data sources cannot return the number of rows in a result set before fetching them; for maximum interoperability, applications should not rely on this behavior. Returns the number of affected rows, or -1 if not supported by the driver in the current context. <DT><A NAME="item_Run">Run ( SQL )</A> <DD> Executes the SQL command SQL and dumps to the screen info about it. Used primarily for debugging. No return value. <DT><A NAME="item_SetConnectOption">SetConnectOption ( OPTION ) *</A> <DD> Sets the value of the specified connect option OPTION. Refer to ODBC documentation for more information on the options and values. Returns true on success, false otherwise. <DT><A NAME="item_SetCursorName">SetCursorName ( NAME ) *</A> <DD> Sets the name of the current cursor. Returns true on success, false otherwise. <DT><A NAME="item_SetPos">SetPos ( ROW [, OPTION, LOCK ] ) *</A> <DD> Moves the cursor to the row <CODE>ROW</CODE> within the current keyset (not the current data/result set). Returns true on success, false otherwise. <DT><A NAME="item_SetMaxBufSize">SetMaxBufSize ( SIZE )</A> <DD> This sets the MaxBufSize for a particular connection. This will most likely never be needed but... The amount of memory that is allocated to retrieve the field data of a record is dynamic and changes when it need to be larger. I found that a memo field in an MS Access database ended up requesting 4 Gig of space. This was a bit much so there is an imposed limit (2,147,483,647 bytes) that can be allocated for data retrieval. Since it is possible that someone has a database with field data greater than 10,240, you can use this function to increase the limit up to a ceiling of 2,147,483,647 (recompile if you need more). Returns the max number of bytes. <DT><A NAME="item_SetStmtCloseType">SetStmtCloseType ( TYPE [, CONNECTION ] )</A> <DD> Sets a particular hstmt close type for the connection. This is the same as <CODE>ODBCFreeStmt(hstmt, TYPE)</CODE>. By default, the connection of the current object will be used. If <CODE>CONNECTION</CODE> is a valid connection number, then it will be used. <CODE>TYPE</CODE> may be one of: <PRE> SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS</PRE> Returns a string indicating the newly set type. <DT><A NAME="item_SetStmtOption">SetStmtOption ( OPTION ) *</A> <DD> Sets the value of the specified statement option <CODE>OPTION</CODE>. Refer to ODBC documentation for more information on the options and values. Returns true on success, false otherwise. <DT><A NAME="item_ShutDown">ShutDown ()</A> <DD> Closes the ODBC connection and dumps to the screen info about it. Used primarily for debugging. No return value. <DT><A NAME="item_Sql">Sql ( SQL_STRING )</A> <DD> Executes the SQL command <CODE>SQL_STRING</CODE> on the current connection. Returns ? on success, or an error number on failure. <DT><A NAME="item_TableList">TableList ( QUALIFIER, OWNER, NAME, TYPE )</A> <DD> Returns the catalog of tables that are available in the DSN. For an unknown parameter, just specify the empty string ``''. Returns an array of table names. <DT><A NAME="item_Transact">Transact ( TYPE ) *</A> <DD> Forces the ODBC connection to perform a rollback or commit transaction. <CODE>TYPE</CODE> may be one of: <PRE> SQL_COMMIT SQL_ROLLBACK</PRE> NOTE: This only works with ODBC drivers that support transactions. Your driver supports it if true is returned from: <PRE> $O->GetFunctions($O->SQL_API_SQLTRANSACT)[1]</PRE> (See <A HREF="#item_GetFunctions"><CODE>GetFunctions</CODE></A> for more details.) Returns true on success, false otherwise. <DT><A NAME="item_Version">Version ( PACKAGES )</A> <DD> Returns an array of version numbers for the requested packages (ODBC.pm or ODBC.PLL). If the list <CODE>PACKAGES</CODE> is empty, then all version numbers are returned. </DL> <HR> <H1><A NAME="limitations">LIMITATIONS</A></H1> What known problems does this thing have? <UL> <LI> If the account under which the process runs does not have write permission on the default directory (for the process, not the ODBC DSN), you will probably get a runtime error during a <CODE>SQLConnection</CODE>. I don't think that this is a problem with the code, but more like a problem with ODBC. This happens because some ODBC drivers need to write a temporary file. I noticed this using the MS Jet Engine (Access Driver). <LI> This module has been neither optimized for speed nor optimized for memory consumption. </UL> <HR> <H1><A NAME="installation notes">INSTALLATION NOTES</A></H1> If you wish to use this module with a build of Perl other than ActivePerl, you may wish to fetch the original source distribution for this module at: <PRE> <A HREF="ftp://ftp.roth.net:/pub/ntperl/ODBC/970208/Bin/Win32_ODBC_Build_CORE.zip">ftp://ftp.roth.net:/pub/ntperl/ODBC/970208/Bin/Win32_ODBC_Build_CORE.zip</A></PRE> or one of the other archives at that same location. See the included README for hints on installing this module manually, what to do if you get a parse exception, and a pointer to a test script for this module. <HR> <H1><A NAME="other documentation">OTHER DOCUMENTATION</A></H1> Find a FAQ for Win32::ODBC at: <PRE> <A HREF="http://www.roth.net/odbc/odbcfaq.htm">http://www.roth.net/odbc/odbcfaq.htm</A></PRE> <HR> <H1><A NAME="author">AUTHOR</A></H1> Dave Roth <<A HREF="mailto:rothd@roth.net">rothd@roth.net</A>> <HR> <H1><A NAME="credits">CREDITS</A></H1> Based on original code by Dan DeMaggio <<A HREF="mailto:dmag@umich.edu">dmag@umich.edu</A>> <HR> <H1><A NAME="disclaimer">DISCLAIMER</A></H1> 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. <HR> <H1><A NAME="history">HISTORY</A></H1> Last Modified 1999.09.25. <HR> <H1><A NAME="copyright">COPYRIGHT</A></H1> Copyright (c) 1996-1998 Dave Roth. All rights reserved. Courtesy of Roth Consulting: <A HREF="http://www.roth.net/consult/">http://www.roth.net/consult/</A> Use under GNU General Public License. Details can be found at: <A HREF="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</A> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Win32::ODBC - ODBC Extension for Win32 </TD></TR> </TABLE> </BODY> </HTML>