home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _11eada26c4f0c893423d214e34e80f99 < prev    next >
Text File  |  2000-03-23  |  10KB  |  263 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>SQL::Eval - Base for deriving evalution objects for SQL::Statement</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> SQL::Eval - Base for deriving evalution objects for SQL::Statement</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#method interface of sql::eval">Method interface of SQL::Eval</A></LI>
  28.         <LI><A HREF="#method interface of sql::eval::table">Method interface of SQL::Eval::Table</A></LI>
  29.     </UL>
  30.  
  31.     <LI><A HREF="#internals">INTERNALS</A></LI>
  32.     <LI><A HREF="#multithreading">MULTITHREADING</A></LI>
  33.     <LI><A HREF="#author and copyright">AUTHOR AND COPYRIGHT</A></LI>
  34.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  35. </UL>
  36. <!-- INDEX END -->
  37.  
  38. <HR>
  39. <P>
  40. <H1><A NAME="name">NAME</A></H1>
  41. <P>SQL::Eval - Base for deriving evalution objects for SQL::Statement</P>
  42. <P>
  43. <HR>
  44. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  45. <UL>
  46. <LI>Linux</LI>
  47. <LI>Solaris</LI>
  48. <LI>Windows</LI>
  49. </UL>
  50. <HR>
  51. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  52. <PRE>
  53.     require SQL::Statement;
  54.     require SQL::Eval;</PRE>
  55. <PRE>
  56.     # Create an SQL statement; use a concrete subclass of
  57.     # SQL::Statement
  58.     my $stmt = MyStatement->new("SELECT * FROM foo, bar",
  59.                                 SQL::Parser->new('Ansi'));</PRE>
  60. <PRE>
  61.     # Get an eval object by calling open_tables; this
  62.     # will call MyStatement::open_table
  63.     my $eval = $stmt->open_tables($data);</PRE>
  64. <PRE>
  65.     # Set parameter 0 to 'Van Gogh'
  66.     $eval->param(0, 'Van Gogh');
  67.     # Get parameter 2
  68.     my $param = $eval->param(2);</PRE>
  69. <PRE>
  70.     # Get the SQL::Eval::Table object referring the 'foo' table
  71.     my $fooTable = $eval->table('foo');</PRE>
  72. <P>
  73. <HR>
  74. <H1><A NAME="description">DESCRIPTION</A></H1>
  75. <P>This module implements two classes that can be used for deriving
  76. concrete subclasses to evaluate SQL::Statement objects. The
  77. SQL::Eval object can be thought as an abstract state engine for
  78. executing SQL queries, the SQL::Eval::Table object can be considered
  79. a *very* table abstraction. It implements method for fetching or
  80. storing rows, retrieving column names and numbers and so on.
  81. See the <CODE>test.pl</CODE> script as an example for implementing a concrete
  82. subclass.</P>
  83. <P>While reading on, keep in mind that these are abstract classes,
  84. you *must* implement at least some of the methods describe below.
  85. Even more, you need not derive from SQL::Eval or SQL::Eval::Table,
  86. you just need to implement the method interface.</P>
  87. <P>All methods just throw a Perl exception in case of errors.</P>
  88. <P>
  89. <H2><A NAME="method interface of sql::eval">Method interface of SQL::Eval</A></H2>
  90. <DL>
  91. <DT><STRONG><A NAME="item_new">new</A></STRONG><BR>
  92. <DD>
  93. Constructor; use it like this:
  94. <PRE>
  95.     $eval = SQL::Eval->new(\%attr);</PRE>
  96. <P>Blesses the hash ref \%attr into the SQL::Eval class (or a subclass).</P>
  97. <P></P>
  98. <DT><STRONG><A NAME="item_param">param</A></STRONG><BR>
  99. <DD>
  100. Used for getting or setting input parameters, as in the SQL query
  101. <PRE>
  102.     INSERT INTO foo VALUES (?, ?);</PRE>
  103. <P>Example:</P>
  104. <PRE>
  105.     $eval->param(0, $val);        # Set parameter 0
  106.     $eval->param(0);              # Get parameter 0</PRE>
  107. <P></P>
  108. <DT><STRONG><A NAME="item_params">params</A></STRONG><BR>
  109. <DD>
  110. Likewise used for getting or setting the complete array of input
  111. parameters. Example:
  112. <PRE>
  113.     $eval->params($params);       # Set the array
  114.     $eval->params();              # Get the array</PRE>
  115. <P></P>
  116. <DT><STRONG><A NAME="item_table">table</A></STRONG><BR>
  117. <DD>
  118. Returns or sets a table object. Example:
  119. <PRE>
  120.     $eval->table('foo', $fooTable);  # Set the 'foo' table object
  121.     $eval->table('foo');             # Return the 'foo' table object</PRE>
  122. <P></P>
  123. <DT><STRONG><A NAME="item_column">column</A></STRONG><BR>
  124. <DD>
  125. Return the value of a column with a given name; example:
  126. <PRE>
  127.     $col = $eval->column('foo', 'id');  # Return the 'id' column of
  128.                                         # the current row in the
  129.                                         # 'foo' table</PRE>
  130. <P>This is equivalent and just a shorthand for</P>
  131. <PRE>
  132.     $col = $eval->table('foo')->column('id');</PRE>
  133. <P></P></DL>
  134. <P>
  135. <H2><A NAME="method interface of sql::eval::table">Method interface of SQL::Eval::Table</A></H2>
  136. <DL>
  137. <DT><STRONG>new</STRONG><BR>
  138. <DD>
  139. Constructor; use it like this:
  140. <PRE>
  141.     $eval = SQL::Eval::Table->new(\%attr);</PRE>
  142. <P>Blesses the hash ref \%attr into the SQL::Eval::Table class (or a
  143. subclass).</P>
  144. <P></P>
  145. <DT><STRONG><A NAME="item_row">row</A></STRONG><BR>
  146. <DD>
  147. Used to get the current row as an array ref. Do not mismatch
  148. getting the current row with the fetch_row method! In fact this
  149. method is valid only after a successfull <CODE>$table->fetchrow()</CODE>.
  150. Example:
  151. <PRE>
  152.     $row = $table->row();</PRE>
  153. <P></P>
  154. <DT><STRONG>column</STRONG><BR>
  155. <DD>
  156. Get the column with a given name in the current row. Valid only after
  157. a successfull <CODE>$table->fetchrow()</CODE>. Example:
  158. <PRE>
  159.     $col = $table->column($colName);</PRE>
  160. <P></P>
  161. <DT><STRONG><A NAME="item_column_num">column_num</A></STRONG><BR>
  162. <DD>
  163. Return the number of the given column name. Column numbers start with
  164. 0. Returns undef, if a column name is not defined, so that you can
  165. well use this for verifying valid column names. Example:
  166. <PRE>
  167.     $colNum = $table->column_num($colNum);</PRE>
  168. <P></P>
  169. <DT><STRONG><A NAME="item_column_names">column_names</A></STRONG><BR>
  170. <DD>
  171. Returns an array ref of column names.
  172. <P></P></DL>
  173. <P>The above methods are implemented by SQL::Eval::Table. The following
  174. methods aren't, so that they *must* be implemented by concrete
  175. subclassed. See the <CODE>test.pl</CODE> script for example.</P>
  176. <DL>
  177. <DT><STRONG><A NAME="item_fetch_row">fetch_row</A></STRONG><BR>
  178. <DD>
  179. Fetches the next row from the table. Returns <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A>, if the last
  180. row was already fetched. The argument $data is for private use of
  181. the concrete subclass. Example:
  182. <PRE>
  183.     $row = $table->fetch_row($data);</PRE>
  184. <P>Note, that you may use</P>
  185. <PRE>
  186.     $row = $table->row();</PRE>
  187. <P>for retrieving the same row again, until the next call of <A HREF="#item_fetch_row"><CODE>fetch_row</CODE></A>.</P>
  188. <P></P>
  189. <DT><STRONG><A NAME="item_push_row">push_row</A></STRONG><BR>
  190. <DD>
  191. Likewise for storing rows. Example:
  192. <PRE>
  193.     $table->push_row($data, $row);</PRE>
  194. <P></P>
  195. <DT><STRONG><A NAME="item_push_names">push_names</A></STRONG><BR>
  196. <DD>
  197. Used by the <EM>CREATE TABLE</EM> statement to set the column names of the
  198. new table. Receives an array ref of names. Example:
  199. <PRE>
  200.     $table->push_names($data, $names);</PRE>
  201. <P></P>
  202. <DT><STRONG><A NAME="item_seek">seek</A></STRONG><BR>
  203. <DD>
  204. Similar to the seek method of a filehandle; used for setting the number
  205. of the next row being written. Example:
  206. <PRE>
  207.     $table->seek($data, $whence, $rowNum);</PRE>
  208. <P>Actually the current implementation is using only <A HREF="#item_seek"><CODE>seek($data, 0,0)</CODE></A>
  209. (first row) and <A HREF="#item_seek"><CODE>seek($data, 2,0)</CODE></A> (last row, end of file).</P>
  210. <P></P>
  211. <DT><STRONG><A NAME="item_truncate">truncate</A></STRONG><BR>
  212. <DD>
  213. Truncates a table after the current row. Example:
  214. <PRE>
  215.     $table->truncate($data);</PRE>
  216. <P></P></DL>
  217. <P>
  218. <HR>
  219. <H1><A NAME="internals">INTERNALS</A></H1>
  220. <P>The current implementation is quite simple: An SQL::Eval object is an
  221. hash ref with only two attributes. The <A HREF="#item_params"><CODE>params</CODE></A> attribute is an array
  222. ref of parameters. The <CODE>tables</CODE> attribute is an hash ref of table
  223. names (keys) and table objects (values).</P>
  224. <P>SQL::Eval::Table instances are implemented as hash refs. Used attributes
  225. are <A HREF="#item_row"><CODE>row</CODE></A> (the array ref of the current row), <CODE>col_nums</CODE> (an hash ref
  226. of column names as keys and column numbers as values) and <CODE>col_names</CODE>,
  227. an array ref of column names with the column numbers as indexes.</P>
  228. <P>
  229. <HR>
  230. <H1><A NAME="multithreading">MULTITHREADING</A></H1>
  231. <P>All methods are working with instance-local data only, thus the module
  232. is reentrant and thread safe, if you either don't share handles between
  233. threads or grant serialized use.</P>
  234. <P>
  235. <HR>
  236. <H1><A NAME="author and copyright">AUTHOR AND COPYRIGHT</A></H1>
  237. <P>This module is Copyright (C) 1998 by</P>
  238. <PRE>
  239.     Jochen Wiedmann
  240.     Am Eisteich 9
  241.     72555 Metzingen
  242.     Germany</PRE>
  243. <PRE>
  244.     Email: joe@ispsoft.de
  245.     Phone: +49 7123 14887</PRE>
  246. <P>All rights reserved.</P>
  247. <P>You may distribute this module under the terms of either the GNU
  248. General Public License or the Artistic License, as specified in
  249. the Perl README file.</P>
  250. <P>
  251. <HR>
  252. <H1><A NAME="see also">SEE ALSO</A></H1>
  253. <P><A HREF="../../../SQL/Statement(3).html">the SQL::Statement(3) manpage</A></P>
  254. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  255. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  256. <STRONG><P CLASS=block> SQL::Eval - Base for deriving evalution objects for SQL::Statement</P></STRONG>
  257. </TD></TR>
  258. </TABLE>
  259.  
  260. </BODY>
  261.  
  262. </HTML>
  263.