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 / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _e0d98ade3b5d2aff2a86c7b307618e17 < prev next >

Wrap

Text File | 2000-03-23 | 31KB | 674 lines

<HTML> <HEAD> <TITLE>SQL::Statement - SQL parsing and processing engine</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"> SQL::Statement - SQL parsing and processing engine </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="#creating a parser object">Creating a parser object</A></LI> <LI><A HREF="#parsing a query">Parsing a query</A></LI> <LI><A HREF="#retrieving query information">Retrieving query information</A></LI> <LI><A HREF="#evaluating a where clause">Evaluating a WHERE clause</A></LI> <LI><A HREF="#evaluating queries">Evaluating queries</A></LI> </UL> <LI><A HREF="#sql syntax">SQL syntax</A></LI> <UL> <LI><A HREF="#create">CREATE</A></LI> <LI><A HREF="#drop">DROP</A></LI> <LI><A HREF="#insert">INSERT</A></LI> <LI><A HREF="#delete">DELETE</A></LI> <LI><A HREF="#update">UPDATE</A></LI> <LI><A HREF="#select">SELECT</A></LI> </UL> <LI><A HREF="#installation">INSTALLATION</A></LI> <LI><A HREF="#internals">INTERNALS</A></LI> <UL> <LI><A HREF="#perlindependent c part">Perl-independent C part</A></LI> <LI><A HREF="#perldependent c part">Perl-dependent C part</A></LI> <LI><A HREF="#perl part">Perl part</A></LI> <LI><A HREF="#the sql_stmt_t structure">The sql_stmt_t structure</A></LI> <LI><A HREF="#the where clause evaluation">The WHERE clause evaluation</A></LI> <LI><A HREF="#features">Features</A></LI> </UL> <LI><A HREF="#multithreading">MULTITHREADING</A></LI> <LI><A HREF="#author and copyright">AUTHOR AND COPYRIGHT</A></LI> <LI><A HREF="#see also">SEE ALSO</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> SQL::Statement - SQL parsing and processing engine <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> require SQL::Statement;</PRE> <PRE> # Create a parser my($parser) = SQL::Statement->new('Ansi');</PRE> <PRE> # Parse an SQL statement $@ = ''; my ($stmt) = eval { SQL::Statement->new("SELECT id, name FROM foo WHERE id > 1", $parser); }; if ($@) { die "Cannot parse statement: $@"; }</PRE> <PRE> # Query the list of result columns; my $numColums = $stmt->columns(); # Scalar context my @columns = $stmt->columns(); # Array context # @columns now contains SQL::Statement::Column instances</PRE> <PRE> # Likewise, query the tables being used in the statement: my $numTables = $stmt->tables(); # Scalar context my @tables = $stmt->tables(); # Array context # @tables now contains SQL::Statement::Table instances</PRE> <PRE> # Query the WHERE clause; this will retrieve an # SQL::Statement::Op instance my $where = $stmt->where();</PRE> <PRE> # Evaluate the WHERE clause with concrete data, represented # by an SQL::Eval object my $result = $stmt->eval_where($eval);</PRE> <PRE> # Execute a statement: $stmt->execute($data, $params);</PRE> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> For installing the module, see <A HREF="#installation">INSTALLATION</A> below. The SQL::Statement module implements a small, abstract SQL engine. This module is not usefull itself, but as a base class for deriving concrete SQL engines. The implementation is designed to work fine with the DBI driver DBD::CSV, thus probably not so well suited for a larger environment, but I'd hope it is extendable without too much problems. By parsing an SQL query you create an SQL::Statement instance. This instance offers methods for retrieving syntax, for WHERE clause and statement evaluation. <H2><A NAME="creating a parser object">Creating a parser object</A></H2> What's accepted as valid SQL, depends on the parser object. There is a set of so-called features that the parsers may have or not. Usually you start with a builtin parser: <PRE> my $parser = SQL::Parser->new($name, [ \%attr ]);</PRE> Currently two parsers are builtin: The Ansi parser implements a proper subset of ANSI SQL. (At least I hope so. :-) The SQL::Statement parser is used by the DBD:CSV driver. You can query or set individual features. Currently available are: <DL> <DT><A NAME="item_create%2Etype_blob">create.type_blob</A> <DD> <DT><A NAME="item_create%2Etype_real">create.type_real</A> <DD> <DT><A NAME="item_create%2Etype_text">create.type_text</A> <DD> These enable the respective column types in a CREATE TABLE clause. They are all disabled in the Ansi parser, but enabled in the SQL::Statement parser. Example: <DT><A NAME="item_select%2Ejoin">select.join</A> <DD> This enables the use of multiple tables in a SELECT statement, for example <PRE> SELECT a.id, b.name FROM a, b WHERE a.id = b.id AND a.id = 2</PRE> </DL> To enable or disable a feature, for example select.join, use the following: <PRE> # Enable feature $parser->feature("select", "join", 1); # Disable feature $parser->feature("select", "join", 0);</PRE> Of course you can query features: <PRE> # Query feature my $haveSelectJoin = $parser->feature("select", "join");</PRE> The <CODE>new</CODE> method allows a shorthand for setting features. For example, the following is equivalent to the SQL::Statement parser: <PRE> $parser = SQL::Statement->new('Ansi', { 'create' => { 'type_text' => 1, 'type_real' => 1, 'type_blob' => 1 }, 'select' => { 'join' => 0 }});</PRE> <H2><A NAME="parsing a query">Parsing a query</A></H2> A statement can be parsed with <PRE> my $stmt = SQL::Statement->new($query, $parser);</PRE> In case of syntax errors or other problems, the method throws a Perl exception. Thus, if you want to catch exceptions, the above becomes <PRE> $@ = ''; my $stmt = eval { SQL::Statement->new($query, $parser) }; if ($@) { print "An error occurred: $@"; }</PRE> The accepted SQL syntax is restricted, though easily extendable. See <A HREF="#sql syntax">SQL syntax</A> below. See <A HREF="#creating a parser object">Creating a parser object</A> above. <H2><A NAME="retrieving query information">Retrieving query information</A></H2> The following methods can be used to obtain information about a query: <DL> <DT><A NAME="item_command">command</A> <DD> Returns the SQL command, currently one of SELECT, INSERT, UPDATE, DELETE, CREATE or DROP, the last two referring to CREATE TABLE and DROP TABLE. See <A HREF="#sql syntax">SQL syntax</A> below. Example: <PRE> my $command = $stmt->command();</PRE> <DT><A NAME="item_columns">columns</A> <DD> <PRE> my $numColumns = $stmt->columns(); # Scalar context my @columnList = $stmt->columns(); # Array context my($col1, $col2) = ($stmt->columns(0), $stmt->columns(1));</PRE> This method is used to retrieve column lists. The meaning depends on the query command: <PRE> SELECT $col1, $col2, ... $colN FROM $table WHERE ... UPDATE $table SET $col1 = $val1, $col2 = $val2, ... $colN = $valN WHERE ... INSERT INTO $table ($col1, $col2, ..., $colN) VALUES (...)</PRE> When used without arguments, the method returns a list of the columns $col1, $col2, ..., $colN, you may alternatively use a column number as argument. Note that the column list may be empty, like in <PRE> INSERT INTO $table VALUES (...)</PRE> and in CREATE or DROP statements. But what does ``returning a column'' mean? It is returning an SQL::Statement::Column instance, a class that implements the methods <CODE>table</CODE> and <CODE>name</CODE>, both returning the respective scalar. For example, consider the following statements: <PRE> INSERT INTO foo (bar) VALUES (1) SELECT bar FROM foo WHERE ... SELECT foo.bar FROM foo WHERE ...</PRE> In all these cases exactly one column instance would be returned with <PRE> $col->name() eq 'bar' $col->table() eq 'foo'</PRE> <DT><A NAME="item_tables">tables</A> <DD> <PRE> my $tableNum = $stmt->tables(); # Scalar context my @tables = $stmt->tables(); # Array context my($table1, $table2) = ($stmt->tables(0), $stmt->tables(1));</PRE> Similar to <A HREF="#item_columns"><CODE>columns</CODE></A>, this method returns instances of <CODE>SQL::Statement::Table</CODE>. For UPDATE, DELETE, INSERT, CREATE and DROP, a single table will always be returned. SELECT statements can return more than one table, in case of joins. Table objects offer a single method, <CODE>name</CODE> which returns the table name. <DT><A NAME="item_params">params</A> <DD> <PRE> my $paramNum = $stmt->params(); # Scalar context my @params = $stmt->params(); # Array context my($p1, $p2) = ($stmt->params(0), $stmt->params(1));</PRE> The <A HREF="#item_params"><CODE>params</CODE></A> method returns information about the input parameters used in a statement. For example, consider the following: <PRE> INSERT INTO foo VALUES (?, ?)</PRE> This would return two instances of SQL::Statement::Param. Param objects implement a single method, <CODE>$param-</CODE>num()>, which retrieves the parameter number. (0 and 1, in the above example). As of now, not very usefull ... :-) <DT><A NAME="item_row_values">row_values</A> <DD> <PRE> my $rowValueNum = $stmt->row_values(); # Scalar context my @rowValues = $stmt->row_values(); # Array context my($rval1, $rval2) = ($stmt->row_values(0), $stmt->row_values(1));</PRE> This method is used for statements like <PRE> UPDATE $table SET $col1 = $val1, $col2 = $val2, ... $colN = $valN WHERE ... INSERT INTO $table (...) VALUES ($val1, $val2, ..., $valN)</PRE> to read the values $val1, $val2, ... $valN. It returns scalar values or SQL::Statement::Param instances. <DT><A NAME="item_Order">Order</A> <DD> <PRE> my $orderNum = $stmt->order(); # Scalar context my @order = $stmt->order(); # Array context my($o1, $o2) = ($stmt->order(0), $stmt->order(1));</PRE> In SELECT statements you can use this for looking at the ORDER clause. Example: <PRE> SELECT * FROM FOO ORDER BY id DESC, name</PRE> In this case, <CODE>order</CODE> could return 2 instances of SQL::Statement::Order. You can use the methods <CODE>$o->table()</CODE>, <CODE>$o->column()</CODE> and <CODE>$o->desc()</CODE> to examine the order object. <DT><A NAME="item_where">where</A> <DD> <PRE> my $where = $stmt->where();</PRE> This method is used to examine the syntax tree of the <CODE>WHERE</CODE> clause. It returns undef (if no WHERE clause was used) or an instance of SQL::Statement::Op. The Op instance offers 4 methods: <DL> <DT><A NAME="item_op">op</A> <DD> returns the operator, one of <CODE>AND</CODE>, <CODE>OR</CODE>, <CODE>=</CODE>, <CODE><></CODE>, <CODE>>=</CODE>, <CODE>></CODE>, <CODE><=</CODE>, <CODE><</CODE>, <CODE>LIKE</CODE>, <CODE>CLIKE</CODE> or <CODE>IS</CODE>. <DT><A NAME="item_arg1">arg1</A> <DD> <DT><A NAME="item_arg2">arg2</A> <DD> returns the left-hand and right-hand sides of the operator. This can be a scalar value, an SQL::Statement::Param object or yet another SQL::Statement::Op instance. <DT><A NAME="item_neg">neg</A> <DD> returns a TRUE value, if the operation result must be negated after evalution. </DL> To evaluate the WHERE clause, fetch the topmost Op instance with the <A HREF="#item_where"><CODE>where</CODE></A> method. Then evaluate the left-hand and right-hand side of the operation, perhaps recursively. Once that is done, apply the operator and finally negate the result, if required. </DL> To illustrate the above, consider the following WHERE clause: <PRE> WHERE NOT (id > 2 AND name = 'joe') OR name IS NULL</PRE> We can represent this clause by the following tree: <PRE> (id > 2) (name = 'joe') \ / NOT AND \ (name IS NULL) \ / OR</PRE> Thus the WHERE clause would return an SQL::Statement::Op instance with the <A HREF="#item_op"><CODE>op()</CODE></A> field set to 'OR'. The <A HREF="#item_arg2"><CODE>arg2()</CODE></A> field would return another SQL::Statement::Op instance with <A HREF="#item_arg1"><CODE>arg1()</CODE></A> being the SQL::Statement::Column instance representing id, the <A HREF="#item_arg2"><CODE>arg2()</CODE></A> field containing the value undef (NULL) and the <A HREF="#item_op"><CODE>op()</CODE></A> field being 'IS'. The <A HREF="#item_arg1"><CODE>arg1()</CODE></A> field of the topmost Op instance would return an Op instance with <A HREF="#item_op"><CODE>op()</CODE></A> eq 'AND' and <A HREF="#item_neg"><CODE>neg()</CODE></A> returning TRUE. The <A HREF="#item_arg1"><CODE>arg1()</CODE></A> and <A HREF="#item_arg2"><CODE>arg2()</CODE></A> fields would be Op's representing ``id > 2'' and ``name = 'joe'''. Of course there's a ready-for-use method for WHERE clause evaluation: <H2><A NAME="evaluating a where clause">Evaluating a WHERE clause</A></H2> The WHERE clause evaluation depends on an object being used for fetching parameter and column values. Usually this can be an SQL::Eval object, but in fact it can be any object that supplies the methods <PRE> $val = $eval->param($paramNum); $val = $eval->column($table, $column);</PRE> See <A HREF="../../../site/lib/SQL/Eval.html">the SQL::Eval manpage</A> for a detailed description of these methods. Once you have such an object, you can call a <PRE> $match = $stmt->eval_where($eval);</PRE> <H2><A NAME="evaluating queries">Evaluating queries</A></H2> So far all methods have been concrete. However, the interface for executing and evaluating queries is abstract. That means, for using them you have to derive a subclass from SQL::Statement that implements at least certain missing methods and/or overwrites others. See the <CODE>test.pl</CODE> script for an example subclass. Something that all methods have in common is that they simply throw a Perl exception in case of errors. <DL> <DT><A NAME="item_execute">execute</A> <DD> After creating a statement, you must execute it by calling the <A HREF="#item_execute"><CODE>execute</CODE></A> method. Usually you put an eval statement around this call: <PRE> $@ = ''; my $rows = eval { $self->execute($data); }; if ($@) { die "An error occurred!"; }</PRE> In case of success the method returns the number of affected rows or -1, if unknown. Additionally it sets the attributes <PRE> $self->{'NUM_OF_FIELDS'} $self->{'NUM_OF_ROWS'} $self->{'data'}</PRE> the latter being an array ref of result rows. The argument $data is for private use by concrete subclasses and will be passed through to all methods. (It is intentionally not implemented as attribute: Otherwise we might well become self referencing data structures which could prevent garbage collection.) <DT><A NAME="item_CREATE">CREATE</A> <DD> <DT><A NAME="item_DROP">DROP</A> <DD> <DT><A NAME="item_INSERT">INSERT</A> <DD> <DT><A NAME="item_UPDATE">UPDATE</A> <DD> <DT><A NAME="item_DELETE">DELETE</A> <DD> <DT><A NAME="item_SELECT">SELECT</A> <DD> Called by <A HREF="#item_execute"><CODE>execute</CODE></A> for doing the real work. Usually they create an SQL::Eval object by calling <A HREF="#item_open_tables"><CODE>$self->open_tables()</CODE></A>, call <A HREF="#item_verify_columns"><CODE>$self->verify_columns()</CODE></A> and then do their job. Finally they return the triple <PRE> ($self->{'NUM_OF_ROWS'}, $self->{'NUM_OF_FIELDS'}, $self->{'data'})</PRE> so that execute can setup these attributes. Example: <PRE> ($self->{'NUM_OF_ROWS'}, $self->{'NUM_OF_FIELDS'}, $self->{'data'}) = $self->SELECT($data);</PRE> <DT><A NAME="item_verify_columns">verify_columns</A> <DD> Called for verifying the row names that are used in the statement. Example: <PRE> $self->verify_columns($eval, $data);</PRE> <DT><A NAME="item_open_tables">open_tables</A> <DD> Called for creating an SQL::Eval object. In fact what it returns doesn't need to be derived from SQL::Eval, it's completely sufficient to implement the same interface of methods. See <A HREF="../../../site/lib/SQL/Eval.html">the SQL::Eval manpage</A> for details. The arguments <CODE>$data</CODE>, <CODE>$createMode</CODE> and <CODE>$lockMode</CODE> are corresponding to those of SQL::Eval::Table::open_table and usually passed through. Example: <PRE> my $eval = $self->open_tables($data, $createMode, $lockMode);</PRE> The eval object can be used for calling <CODE>$self-</CODE>verify_columns> or <CODE>$self-</CODE>eval_where>. <DT><A NAME="item_open_table">open_table</A> <DD> This method is completely abstract and *must* be implemented by subclasses. The default implementation of <CODE>$self-</CODE>open_tables> calls this method for any table used by the statement. See the <CODE>test.pl</CODE> script for an example of imlplementing a subclass. </DL> <HR> <H1><A NAME="sql syntax">SQL syntax</A></H1> The SQL::Statement module is far away from ANSI SQL or something similar, it is designed for implementing the DBD::CSV module. See <A HREF="../../../DBD/CSV(3).html">the DBD::CSV(3) manpage</A>. I do not want to give a formal grammar here, more an informal description: Read the statement definition in sql_yacc.y, if you need something precise. The main lexical elements of the grammar are: <DL> <DT><A NAME="item_Integers">Integers</A> <DD> <DT><A NAME="item_Reals">Reals</A> <DD> Syntax obvious <DT><A NAME="item_Strings">Strings</A> <DD> Surrounded by either single or double quotes; some characters need to be escaped with a backslash, in particular the backslash itself (\\), the NUL byte (\0), Line feeds (\n), Carriage return (\r), and the quotes (\' or \``). <DT><A NAME="item_Parameters">Parameters</A> <DD> Parameters represent scalar values, like Integers, Reals and Strings do. However, their values are read inside <CODE>Execute()</CODE> and not inside Prepare(). Parameters are represented by question marks (?). <DT><A NAME="item_Identifiers">Identifiers</A> <DD> Identifiers are table or column names. Syntactically they consist of alphabetic characters, followed by an arbitrary number of alphanumeric characters. Identifiers like SELECT, INSERT, INTO, ORDER, BY, WHERE, ... are forbidden and reserved for other tokens. </DL> What it offers is the following: <H2><A NAME="create">CREATE</A></H2> This is the CREATE TABLE command: <PRE> CREATE TABLE $table ( $col1 $type1, ..., $colN $typeN, [ PRIMARY KEY ($col1, ... $colM) ] )</PRE> The column names are $col1, ... $colN. The column types can be <CODE>INTEGER</CODE>, <CODE>CHAR(n)</CODE>, <CODE>VARCHAR(n)</CODE>, <CODE>REAL</CODE> or <CODE>BLOB</CODE>. These types are currently completely ignored. So is the (optional) <CODE>PRIMARY KEY</CODE> clause. <H2><A NAME="drop">DROP</A></H2> Very simple: <PRE> DROP TABLE $table</PRE> <H2><A NAME="insert">INSERT</A></H2> This can be <PRE> INSERT INTO $table [ ( $col1, ..., $colN ) ] VALUES ( $val1, ... $valN )</PRE> <H2><A NAME="delete">DELETE</A></H2> <PRE> DELETE FROM $table [ WHERE $where_clause ]</PRE> See <A HREF="#item_SELECT">SELECT</A> below for a decsription of $where_clause <H2><A NAME="update">UPDATE</A></H2> <PRE> UPDATE $table SET $col1 = $val1, ... $colN = $valN [ WHERE $where_clause ]</PRE> See <A HREF="#item_SELECT">SELECT</A> below for a decsription of $where_clause <H2><A NAME="select">SELECT</A></H2> <PRE> SELECT [DISTINCT] $col1, ... $colN FROM $table [ WHERE $where_clause ] [ ORDER BY $ocol1, ... $ocolM ]</PRE> The $where_clause is based on boolean expressions of the form $val1 $op $val2, with $op being one of '=', '<>', '>', '<', '>=', '<=', 'LIKE', 'CLIKE' or IS. You may use OR, AND and brackets to combine such boolean expressions or NOT to negate them. <HR> <H1><A NAME="installation">INSTALLATION</A></H1> Like most other Perl modules, you simply do a <PRE> perl Makefile.PL make (nmake or dmake, if you are using Win32) make test (Let me know, if any tests fail) make install</PRE> Known problems are: <UL> <LI> Some flavours of SCO Unix don't seem to have <CODE>alloca()</CODE> or something similar. I recommend using gcc or egcs for compiling Perl and the SQL::Statement module: Both compilers have a builtin alloca(). Another option could be to use external alloca.c, for example <PRE> <A HREF="http://www.pu.informatik.th-darmstadt.de/FTP/pub/pu/alloca.c">http://www.pu.informatik.th-darmstadt.de/FTP/pub/pu/alloca.c</A> <A HREF="http://www.cs.purdue.edu/homes/young/src2www-example/alloca.c.html">http://www.cs.purdue.edu/homes/young/src2www-example/alloca.c.html</A></PRE> I did test neither of them and cannot give detailed instructions for including them into the SQL::Statement module. However, it should be sufficient to compile alloca.c with the same instructions than, for example, sql_yacc.c and finally repeat the linker command by inserting alloca.o after sql_yacc.o. Note that I cannot modify the sources to work without alloca(), as it is the bison parser that's using <CODE>alloca()</CODE> and I don't have the bison generated code in my hands. My thanks to Theo Petersen, <<A HREF="mailto:theo@acsp.com">theo@acsp.com</A>>, for pointing out this problem and the possible workarounds. </UL> <HR> <H1><A NAME="internals">INTERNALS</A></H1> Internally the module is splitted into three parts: <H2><A NAME="perlindependent c part">Perl-independent C part</A></H2> This part, contained in the files <CODE>sql_yacc.y</CODE>, <CODE>sql_data.h</CODE>, <CODE>sql_data.c</CODE> and <CODE>sql_op.c</CODE>, is completely independent from Perl. It might well be used from within another script language, Tcl say, or from a true C application. You probably ask, why Perl independence? Well, first of all, I think this is a valuable target in itself. But the main reason was the impossibility to use the Perl headers inside bison generated code. The Perl headers export almost the complete Yacc interface to XS, for whatever reason, thus redefining constants and structures created by your own bison code. :-( <H2><A NAME="perldependent c part">Perl-dependent C part</A></H2> This is contained in <CODE>Statement.xs</CODE>. The both C parts communicate via a C structure sql_stmt_t. In fact, an SQL::Statement object is nothing else than a pointer to such a structure. The XS calls columns(), Table(), where(), ... do nothing more than fetching data from this structure and converting it to Perl objects. See <A HREF="#the sql_stmt_t structure">The sql_stmt_t structure</A> below for details on the structure. <H2><A NAME="perl part">Perl part</A></H2> Besides some stub functions for retrieving statement data, this is mainly the query processing with the exception of WHERE clause evaluation. <H2><A NAME="the sql_stmt_t structure">The sql_stmt_t structure</A></H2> This structure is designed for optimal performance. A typical query will be parsed with only 4 or 5 <CODE>malloc()</CODE> calls; in particular no memory will be aquired for storing strings; only pointers into the query string are used. The statement stores its tokens in the values array. The array elements are of type sql_val_t, a union, that can represent the most interesting tokens; for example integers and reals are stored in the data.i and data.d parts of the union, strings are stored in the data.str part, columns in the data.col part and so on. Arrays are allocated in chunks of 64 elements, thus a single <CODE>malloc()</CODE> will be usually sufficient for allocating the complete array. Some types use pointers into the values array: For example, operations are stored in an sql_op_t structure that containes elements arg1 and arg2 which are pointers into the value table, pointing to other operations or scalars. These pointers are stored as indices, so that the array can be extended using realloc(). The sql_stmt_t structure contains other arrays: columns, tables, rowvals, order, ... representing the data returned by the columns(), tables(), <A HREF="#item_row_values"><CODE>row_values()</CODE></A> and <CODE>order()</CODE> methods. All of these contain pointers into the values array, again stored as integers. Arrays are initialized with the _InitArray call in SQL_Statement_Prepare and deallocated with _DestroyArray in SQL_Statement_Destroy. Array elements are obtained by calling _AllocData, which returns an index. The number -1 is used for errors or as a NULL value. <H2><A NAME="the where clause evaluation">The WHERE clause evaluation</A></H2> A WHERE clause is evaluated by calling SQL_Statement_EvalWhere(). This function is in the Perl independent part, but it needs the possibility to retrieve data from the Perl part, for example column or parameter values. These values are retrieved via callbacks, stored in the sql_eval_t structure. The field stmt->evalData points to such a structure. Of course the calling method can extend the sql_eval_t structure (like eval_where in Statement.xs does) to include private data not used by SQL_Statement_EvalWhere. <H2><A NAME="features">Features</A></H2> Different parsers are implemented via the sql_parser_t structure. This is mainly a set of yes/no flags. If you'd like to add features, do the following: First of all, extend the sql_parser_t structure. If your feature is part of a certain statement, place it into the statements section, for example ``select.join''. Otherwise choose a section like ``misc'' or ``general''. (There's no particular for the section design, but structure never hurts.) Second, add your feature to sql_yacc.y. If your feature needs to extend the lexer, do it like this: <PRE> if (FEATURE(misc, myfeature) { /* Scan your new symbols */ ... }</PRE> See the BOOL symbol as an example. If you need to extend the parser, do it like this: <PRE> my_new_rule: /* NULL, old behaviour, doesn't use my feature */ | my_feature { YFEATURE(misc, myfeature); } ;</PRE> Thus all parsers not having FEATURE(misc, myfeature) set will produce a parse error here. Again, see the BOOL symbol for an example. Third thing is to extend the builtin parsers. If they support your feature, add a 1, otherwise a 0. Currently there are two builtin parsers: The ansiParser in sql_yacc.y and the sqlEvalParser in Statement.xs. Finally add support for your feature to the <CODE>feature</CODE> method in Statement.xs. That's it! <HR> <H1><A NAME="multithreading">MULTITHREADING</A></H1> The complete module code is reentrant. In particular the parser is created with <CODE>%pure_parser</CODE>. See bison(1) for details on reentrant parsers. That means, the module is ready for multithreading, as long as you don't share handles between threads. Read-only handles, for example parsers, can even be shared. Statement handles cannot be shared among threads, at least not, if you don't grant serialized access. Per-thread handles are always safe. <HR> <H1><A NAME="author and copyright">AUTHOR AND COPYRIGHT</A></H1> This module is Copyright (C) 1998 by <PRE> Jochen Wiedmann Am Eisteich 9 72555 Metzingen Germany</PRE> <PRE> Email: joe@ispsoft.de Phone: +49 7123 14887</PRE> All rights reserved. You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. <HR> <H1><A NAME="see also">SEE ALSO</A></H1> DBI(3), <A HREF="../../../DBD/CSV(3).html">the DBD::CSV(3) manpage</A> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> SQL::Statement - SQL parsing and processing engine </TD></TR> </TABLE> </BODY> </HTML>