This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: SPOPS/Tie/StrictField,  Next: SPOPS/Utility,  Prev: SPOPS/Tie,  Up: Module List

Enable field checking for SPOPS objects
***************************************

NAME
====

   SPOPS::Tie::StrictField - Enable field checking for SPOPS objects

SYNOPSIS
========

     use SPOPS::Tie::StrictField;
     my ( %data );
     my @fields = qw( first_name last_name login birth_date );
     tie %data, 'SPOPS::Tie::StrictField', $class, \@fields;

     # Trigger warnings by trying to store a misspelled
     # or unknown property

     # 'login' is the correct field
     $data{login_name}  = 'cb';

     # not in @fields list
     $data{middle_name} = 'Amadeus';

DESCRIPTION
===========

   This class subclasses *Note SPOPS/Tie: SPOPS/Tie,, adding field-checking
functionality. When you tie the hash, you also pass it a hashref of extra
information, one key of which should be 'field'. The 'field' parameter
specifies what keys may be used to access data in the hash. This is to
ensure that when you set or retrieve a property it is properly spelled.

   If you do not specify the 'field' parameter properly, you will get
normal *Note SPOPS/Tie: SPOPS/Tie, functionality, which might throw a
monkey wrench into your application since you and any users will expect
the system to not silently accept misspelled object keys.

   For instance:

     my ( %data );
     my $class = 'SPOPS::User';
     tie %data, 'SPOPS::Tie::StrictField', $class, [ qw/ first_name last_name login / ];
     $data{firstname} = 'Chucky';

   would result in a message to STDERR, something like:

     Error setting value for field (firstname): it is not a valid field
     at my_tie.pl line 9

   since you have misspelled the property, which should be 'first_name'.

SEE ALSO
========

   *Note SPOPS/Tie: SPOPS/Tie,, *Note Perltie: (perl.info)perltie,

COPYRIGHT
=========

   Copyright (c) 2001 intes.net, inc.. All rights reserved.

   This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

AUTHORS
=======

   Chris Winters  <chris@cwinters.com>


File: pm.info,  Node: SPOPS/Utility,  Next: SQL/AnchoredWildcards,  Prev: SPOPS/Tie/StrictField,  Up: Module List

Utility methods for SPOPS objects
*********************************

NAME
====

   SPOPS::Utility - Utility methods for SPOPS objects

SYNOPSIS
========

     # In configuration file
      'isa' => [ qw/ SPOPS::Utility SPOPS::DBI / ],

     # Create an object and run a utility
     my $user = MyApp::User->fetch( $id );
     $user->{crypted_password} = $user->crypt_it( $new_password );

     # Also use them separately
     use SPOPS::Utility qw();

     my $now = SPOPS::Utility->now;
     my $random = SPOPS::Utility->generate_random_code( 16 );

DESCRIPTION
===========

   This class has a number of utility methods that can be used from SPOPS
objects or from the SPOPS classes. They were previously in the main SPOPS
module but were removed to make the classes more consistent and focused.

   The different methods are fairly unrelated.

METHODS
=======

   *generate_random_code( $length )*

   Generates a random code of $length length consisting of upper-case
characters in the english alphabet.

   *crypt_it( $text )*

   Returns a crypt()ed version of $text. If $text not passed in, returns
undef.

   *now( \% )*

   Return the current time, formatted: yyyy-mm-dd hh:mm:ss. Since we use
the *Note Date/Format: Date/Format, module (which in turn uses standard
strftime formatting strings), you can pass in a format for the date/time
to fit your needs.

   Parameters:

     format
       strftime format

     time
       return of time command (or manipulation thereof); see 'perldoc -f time'

   *today()*

   Return a date (yyyy-mm-dd) for today.

   *now_between_dates( { begin =* $dateinfo, end => $dateinfo } );

   Where $dateinfo is either a simple scalar ('yyyy-mm-dd') or an arrayref
([yyyy,mm,dd]).

   Note that you can also just pass one of the dates and the check will
still perform ok.

   Returns 1 if 'now' is between the two dates (inclusive), undef
otherwise.

   Examples:

   # Today is '2000-10-31' in all examples

     SPOPS::Utility->now_between_days( { begin => '2000-11-01' } );
     ( returns 'undef' )

     SPOPS::Utility->now_between_days( { end => '1999-10-31' } );
     ( returns 'undef' )

     SPOPS::Utility->now_between_days( { begin => [2000, 10, 1 ] } );
     ( returns 1 )

     SPOPS::Utility->now_between_days( { begin => '2000-10-01',
                                         end   => '2001-10-01' } );
     ( returns 1 )

   *list_process( \@existing, \@new )*

   Returns: hashref with three keys, each with an arrayref as the value:

     keep:   items found in both \@existing and \@new
     add:    items found in \@new but not \@existing
     remove: items found in \@existing but not \@new

   Mainly used for determining one-to-many relationship changes, but you
can probably think of other applications.

COPYRIGHT
=========

   Copyright (c) 2001 intes.net, inc.. All rights reserved.

   This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

MORE INFORMATION
================

   See the website:

     http://www.openinteract.org/SPOPS/

AUTHORS
=======

   Chris Winters <chris@cwinters.com>

   Christian Lemburg <lemburg@aixonix.de> successfully argued that these
methods should be removed from SPOPS.pm


File: pm.info,  Node: SQL/AnchoredWildcards,  Next: SQL/Eval,  Prev: SPOPS/Utility,  Up: Module List

add anchors ('^', '$') to SQL wildcards
***************************************

NAME
====

   SQL::AnchoredWildcards - add anchors ('^', '$') to SQL wildcards

SYNOPSIS
========

     use SQL::AnchoredWildcards;
     $pattern = sql_anchor_wildcards($pattern);

DESCRIPTION
===========

   SQL::AnchorWildcards enhances the default SQL SELECT..LIKE wildcard
processing by adding support for the '^' and '$' anchor metacharacters.
When using sql_anchor_wildcards(), if the pattern does not contain '^'
('$'), the search pattern is unanchored at the beginning (end).  Escaping
of '^' and '$' is done with '\'.

   Please also note that '$' is properly escaped for Perl's benefit.

EXAMPLES
========

   Let's take an SQL SELECT...LIKE Perl statement as in:

     my $query = new CGI;
     $query->import_names('Q');
     my $SQL =<<endSQL;
       SELECT
        GROUPNAME,
        GROUPID
       FROM
        TSR_GROUPS
       WHERE
        GROUPNAME LIKE '$Q::search';
     endSQL

   which will yield the SQL statement:

     SELECT
      GROUPNAME,
      GROUPID
     FROM
      TSR_GROUPS
     WHERE
      GROUPNAME LIKE 'HDTV';

   when the user has typed 'HDTV' into the text box named 'search' on the
CGI input form.  If 'HDTV' is the search term, then SQL SELECT..LIKE will
only find groups whose name matches /^HDTV$/.  If the CGI uses:

     $Q::search = sql_anchor_wildcards($Q::search);

   the SQL statement becomes:

     SELECT
      GROUPNAME,
      GROUPID
     FROM
      TSR_GROUPS
     WHERE
      GROUPNAME LIKE '%HDTV%';

   which will find all groups that have 'HDTV' as part of the group's
name.  I think that most people that use a Web-based search engine would
expect that typing 'HDTV' into a search box would make the search engine
find all groups that have 'HDTV' as part of the group's name.

   But what if you only want to find groups whose name starts with 'HDTV' -
say, all HDTV engineering groups like 'HDTV Power Supply Design' where
other, non-engineering groups would have 'HDTV' later in their names, like
'Marketing & Sales - HDTV Direct View'?  In that case with
SQL::AnchoredWildcards, you would type '^HDTV' into the CGI search box,
with:

     SELECT
      GROUPNAME,
      GROUPID
     FROM
      TSR_GROUPS
     WHERE
      GROUPNAME LIKE 'HDTV%';

   as the resulting SQL.  As you would expect, this SQL SELECT..LIKE
statement would find groups whose name starts with 'HDTV'.

   Similarly, if you know that the groups you want are those that have
'HDTV' as the last component of their names, like 'Marketing & Sales -
Direct View HDTV', you would type 'HDTV$' into the CGI search box, with:

     SELECT
      GROUPNAME,
      GROUPID
     FROM
      TSR_GROUPS
     WHERE
      GROUPNAME LIKE '%HDTV';

   as the resulting SQL.

   If you are looking for an embedded '$', as in:

     DCL LOGICAL $SYS_INFO

   you would type 'DCL LOGICAL \$SYS_INFO' into the CGI search box, with:

     SELECT
      GROUPNAME,
      GROUPID
     FROM
      TSR_GROUPS
     WHERE
      GROUPNAME LIKE 'DCL LOGICAL $SYS_INFO';

   as the resulting SQL.

AUTHOR
======

   Mark Leighton Fisher, fisherm@tce.com

SEE ALSO
========

   perl(1).


File: pm.info,  Node: SQL/Eval,  Next: SQL/Schema,  Prev: SQL/AnchoredWildcards,  Up: Module List

Base for deriving evalution objects for SQL::Statement
******************************************************

NAME
====

   SQL::Eval - Base for deriving evalution objects for SQL::Statement

SYNOPSIS
========

     require SQL::Statement;
     require SQL::Eval;

     # Create an SQL statement; use a concrete subclass of
     # SQL::Statement
     my $stmt = MyStatement->new("SELECT * FROM foo, bar",
     			        SQL::Parser->new('Ansi'));

     # Get an eval object by calling open_tables; this
     # will call MyStatement::open_table
     my $eval = $stmt->open_tables($data);

     # Set parameter 0 to 'Van Gogh'
     $eval->param(0, 'Van Gogh');
     # Get parameter 2
     my $param = $eval->param(2);

     # Get the SQL::Eval::Table object referring the 'foo' table
     my $fooTable = $eval->table('foo');

DESCRIPTION
===========

   This module implements two classes that can be used for deriving
concrete subclasses to evaluate SQL::Statement objects. The SQL::Eval
object can be thought as an abstract state engine for executing SQL
queries, the SQL::Eval::Table object can be considered a *very* table
abstraction. It implements method for fetching or storing rows, retrieving
column names and numbers and so on.  See the test.pl script as an example
for implementing a concrete subclass.

   While reading on, keep in mind that these are abstract classes, you
*must* implement at least some of the methods describe below.  Even more,
you need not derive from SQL::Eval or SQL::Eval::Table, you just need to
implement the method interface.

   All methods just throw a Perl exception in case of errors.

Method interface of SQL::Eval
-----------------------------

new
     Constructor; use it like this:

          $eval = SQL::Eval->new(\%attr);

     Blesses the hash ref \%attr into the SQL::Eval class (or a subclass).

param
     Used for getting or setting input parameters, as in the SQL query

          INSERT INTO foo VALUES (?, ?);

     Example:

          $eval->param(0, $val);        # Set parameter 0
          $eval->param(0);              # Get parameter 0

params
     Likewise used for getting or setting the complete array of input
     parameters. Example:

          $eval->params($params);       # Set the array
          $eval->params();              # Get the array

table
     Returns or sets a table object. Example:

          $eval->table('foo', $fooTable);  # Set the 'foo' table object
          $eval->table('foo');             # Return the 'foo' table object

column
     Return the value of a column with a given name; example:

          $col = $eval->column('foo', 'id');  # Return the 'id' column of
                                              # the current row in the
                                              # 'foo' table

     This is equivalent and just a shorthand for

          $col = $eval->table('foo')->column('id');

Method interface of SQL::Eval::Table
------------------------------------

new
     Constructor; use it like this:

          $eval = SQL::Eval::Table->new(\%attr);

     Blesses the hash ref \%attr into the SQL::Eval::Table class (or a
     subclass).

row
     Used to get the current row as an array ref. Do not mismatch getting
     the current row with the fetch_row method! In fact this method is
     valid only after a successfull `$table->fetchrow()'.  Example:

          $row = $table->row();

column
     Get the column with a given name in the current row. Valid only after
     a successfull `$table->fetchrow()'. Example:

          $col = $table->column($colName);

column_num
     Return the number of the given column name. Column numbers start with
     0. Returns undef, if a column name is not defined, so that you can
     well use this for verifying valid column names. Example:

          $colNum = $table->column_num($colNum);

column_names
     Returns an array ref of column names.

   The above methods are implemented by SQL::Eval::Table. The following
methods aren't, so that they *must* be implemented by concrete subclassed.
See the test.pl script for example.

fetch_row
     Fetches the next row from the table. Returns undef, if the last row
     was already fetched. The argument $data is for private use of the
     concrete subclass. Example:

          $row = $table->fetch_row($data);

     Note, that you may use

          $row = $table->row();

     for retrieving the same row again, until the next call of fetch_row.

push_row
     Likewise for storing rows. Example:

          $table->push_row($data, $row);

push_names
     Used by the *CREATE TABLE* statement to set the column names of the
     new table. Receives an array ref of names. Example:

          $table->push_names($data, $names);

seek
     Similar to the seek method of a filehandle; used for setting the
     number of the next row being written. Example:

          $table->seek($data, $whence, $rowNum);

     Actually the current implementation is using only `seek($data, 0,0)'
     (first row) and `seek($data, 2,0)' (last row, end of file).

truncate
     Truncates a table after the current row. Example:

          $table->truncate($data);

INTERNALS
=========

   The current implementation is quite simple: An SQL::Eval object is an
hash ref with only two attributes. The params attribute is an array ref of
parameters. The tables attribute is an hash ref of table names (keys) and
table objects (values).

   SQL::Eval::Table instances are implemented as hash refs. Used attributes
are row (the array ref of the current row), `col_nums' (an hash ref of
column names as keys and column numbers as values) and col_names, an array
ref of column names with the column numbers as indexes.

MULTITHREADING
==============

   All methods are working with instance-local data only, thus the module
is reentrant and thread safe, if you either don't share handles between
threads or grant serialized use.

AUTHOR AND COPYRIGHT
====================

   This module is Copyright (C) 1998 by

     Jochen Wiedmann
     Am Eisteich 9
     72555 Metzingen
     Germany

     Email: joe@ispsoft.de
     Phone: +49 7123 14887

   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.

SEE ALSO
========

   `SQL::Statement(3)' in this node


File: pm.info,  Node: SQL/Schema,  Next: SQL/Schema/Constraint,  Prev: SQL/Eval,  Up: Module List

Convert a data dictionary into SQL statements
*********************************************

NAME
====

   SQL::Schema - Convert a data dictionary into SQL statements

SYNOPSIS
========

     use DBI;

     my $dbh = DBI->connect(...);

     use SQL::Schema;

     my $schema = SQL::Schema->new($dbh);

     my $sql = $schema->string;
     print $sql;

     print "$schema";

WARNING
=======

   This is alpha software.  It currently works with Oracle databases only.
The name of the module might be changed in future releases as well as its
interface.

   If somebody is modifying the datase schema during the life time of an
`SQL::Schema' object, the object will probably fail and / or produce wrong
information.

DESCRIPTION
===========

   `SQL::Schema' is a class for objects representing a database schema.
The methods of an instanciated object do allow to access the information
within a database's data dictionary and to represent them as SQL create
statements and the like using the proper SQL dialect.

Constructor
-----------

     $schema = SQL::Schema->new($dbh);

   The new method instanciates a schema object. The only argument required
is a database handle, which has to offer the same API as described within
`DBI(3)' in this node.

Methods
-------

     $sql = $schema->string;

   Returns an SQL string containing several statements at once.  This
string contains all the SQL statements to create the database schema.

   This method is overloaded with the string operator. So the following
two lines are equivalent:

     $sql = $schema->string;
     $sql = "$schema";

AUTHOR AND COPYRIGHT
====================

     SQL::Schema is Copyright (C) 2000, Torsten Hentschel
                                        Windmuehlenweg 47
                                        44141 Dortmund
                                        Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `export_schema(1)' in this node, `DBI(3)' in this node,
`SQL::Schema::Procedure(3)' in this node, `SQL::Schema::Sequence(3)' in
this node, `SQL::Schema::Table(3)' in this node, `SQL::Schema::Trigger(3)'
in this node, `SQL::Schema::View(3)' in this node


File: pm.info,  Node: SQL/Schema/Constraint,  Next: SQL/Schema/Function,  Prev: SQL/Schema,  Up: Module List

A constraint of a database table
********************************

NAME
====

   SQL::Schema::Constraint - A constraint of a database table

SYNOPSIS
========

     my $constraint = SQL::Schema::Constraint->new(%attr);

     my $sql = $constraint->constraint_clause;
     print $sql;

     print "$constraint";

DESCRIPTION
===========

   `SQL::Schema::Constraint' is a class for objects representing a database
table's constraint. The methods of an instanciated object do allow to
access the information within a database's data dictionary and to
represent them as SQL create statements and the like using the proper SQL
dialect.

Constructors
------------

     $constraint = SQL::Schema::Constraint->new(%attr);

   The new method instanciates a constraint object. The object is an in
memory representation of a (possible) database table's constraint.  The
attributes are given as key value pairs by the hash %attr.  Possible keys
are:

     key                required?   value description

     constraint_name    yes         the constraint's name
     constraint_type    yes         one of
                                      C for check
                                      P for primary key
                                      U for unique key
                                      R for referential integrity
     search_condition   no          text of search condition for
                                    table check
     delete_rule        (*)         either `cascade' or `no action'
                                    default: `no action'
     status             no          either `enabled' or `disabled'
                                    default: `enabled'
     deferrable         no          either `deferrable' or `not deferrable'
                                    default: `not deferrable'
     deferred           no          either `immediate' or `deferred'
                                    default: `immediate'
     generated          no          either `generated name' or `user name'
                                    default: `user name'
     validated          no          either `validated' or `not validated'
                                    default: `validated'

   These keys (except columns) and their possible values correspond
exactly to the data dictionary view `user_constraints' and are described
within Oracle's Server Reference.

   Additionally the following keys are possible/required. They do not
relate to columns within the view `user_constraints'.

     key                required?   value description

     columns            no          a reference to a list with
                                    column objects
     r_schema           (*)         the referenced table's schema
     r_table_name       (*)         the referenced table's name
     r_columns          (*)         a reference to a list containing
                                    column objects representing the
                                    referenced columns

     (*) means: required for referential constrains otherwise not
                allowed

     @columns = SQL::Schema::Constraint->select_columns($dbh,$schema,$name);

   Returns a list of columns in the correct sequence. All the columns
belonging to the constraint with the name `$schema.$name' are selected
from the database and returned. All the elements of the returned list are
objects of the class `SQL::Schema::Table::Column'.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$schema
     The name of the constraint's schema.

$name
     The constraint's name.

     $constraint = SQL::Schema::Constraint->select($dbh,$constraint_name);

   The select method fetches the attributes required by new from the
database and returns the constraint object. (It calls new internally.)

   If the constraint could not be found within the database, the method
returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

`$constraint_name'
     The name of the constraint.

Methods
-------

   The following attribute methods do return the current value of the
attributes (as handed over to the new method):

     $constraint_name   = $constraint->name;
     $constraint_type   = $constraint->type;
     $search_condition  = $constraint->search_condition;
     $delete_rule       = $constraint->delet_rule;
     $status            = $constraint->status;
     $deferrable        = $constraint->deferrable;
     $deferred          = $constraint->deferred;
     $generated         = $constraint->generated;
     $validated         = $constraint->validated;
     @columns           = $constraint->columns;
     $r_schema          = $constraint->r_schema;
     $r_table_name      = $constraint->r_table_name;
     @r_columns         = $constraint->r_columns;

   The return value of many of the above extra values is text with just
two possible values. Sometimes it is more comfortable for programmers to
have methods returning boolean values. The table below names extra methods
based on the methods above. They return 1 if the base method returns the
value shown within the 3rd column. Otherwise the return 0.

     extra method     base method    1 if eq          0 if eq

     cascade          delete_rule   cascade          no action
     enabled          status        enabled          disabled
     deferrable_b     deferrable    deferrable       not deferrable
     deferred_b       deferred      deferred         immediate
     generated_b      generated     generated name   user name
     validated_b      validated     validated        not validated

   Examples:

     $bool = $constraint->cascade;
     $bool = $constraint->enabled;
     $bool = $constraint->deferrable_b;
     $bool = $constraint->deferred_b;
     $bool = $constraint->generated_b;
     $bool = $constraint->validated_b;

     $sql = $constraint->constraint_clause;
     $sql = "$constraint";

   Returns a string containing the constraint clause which could be used
as part of an SQL statements for creation of the corresponding constraint.
This method is overloaded with the string operator. So the two examples
above are equivalent.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Constraint is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,
`SQL::Schema::Table(3)' in this node


File: pm.info,  Node: SQL/Schema/Function,  Next: SQL/Schema/Package,  Prev: SQL/Schema/Constraint,  Up: Module List

A function stored within the database
*************************************

NAME
====

   SQL::Schema::Function - A function stored within the database

SYNOPSIS
========

     my $function = SQL::Schema::Function->new(%attr);

     my $sql = $function->create_statement;
     print $sql;

     print "$function";

DESCRIPTION
===========

   `SQL::Schema::Function' is a class for objects representing a function
stored within the database.  The methods of an instanciated object do
allow to access the information within a database's data dictionary and to
represent them as SQL create statements and the like using the proper SQL
dialect.

Constructors
------------

     $function = SQL::Schema::Function->new(%attr);

   The new method instanciates a function object. The object is an in
memory representation of a (possible) database function.  The attributes
are given as key value pairs by the hash %attr.  Possible keys are:

     key               required?   value description

     name              yes         the name of the function
                                   without preceeding schema name

     text              yes         the concatenation of all the text lines
                                   forming the function's source code

   As a function is basically a piece of source stored within the
database, this class inherits all methods from `SQL::Schema::Source'.  So
please have a look at the new method describet at `SQL::Schema::Source(3)'
in this node. Though the new method here overwrites the new method there,
it calls the super class's new method with just the key value pair for the
source's type added.

     $function = SQL::Schema::Function->select($dbh,$name);

   The select method fetches the attributes required by new from the
database and returns the function object. (It calls new internally.)

   If the function with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the function without preceeding schema name.

Methods
-------

   The following attribute methods do exist:

     $type = $function->type;

   The method type always returns the string "function".  This package
inherits all the other methods from SQL::Schema::Source as a database
function basically is a special kind of source within the database. For
more information, please have a look at `SQL::Schema::Source(3)' in this
node.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Function is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,
`SQL::Schema::Source(3)' in this node


File: pm.info,  Node: SQL/Schema/Package,  Next: SQL/Schema/Package/Body,  Prev: SQL/Schema/Function,  Up: Module List

A package stored within the database
************************************

NAME
====

   SQL::Schema::Package - A package stored within the database

SYNOPSIS
========

     my $package = SQL::Schema::Package->new(%attr);

     my $sql = $package->create_statement;
     print $sql;

     print "$package";

DESCRIPTION
===========

   `SQL::Schema::Package' is a class for objects representing a package
stored within the database.  The methods of an instanciated object do
allow to access the information within a database's data dictionary and to
represent them as SQL create statements and the like using the proper SQL
dialect.

Constructors
------------

     $package = SQL::Schema::Package->new(%attr);

   The new method instanciates a package object. The object is an in
memory representation of a (possible) database package.  The attributes
are given as key value pairs by the hash %attr.  Possible keys are:

     key               required?   value description

     name              yes         the name of the package
                                   without preceeding schema name

     text              yes         the concatenation of all the text lines
                                   forming the package's source code

   As a package is basically a piece of source stored within the database,
this class inherits all methods from `SQL::Schema::Source'.  So please
have a look at the new method describet at `SQL::Schema::Source(3)' in
this node. Though the new method here overwrites the new method there, it
calls the super class's new method with just the key value pair for the
source's type added.

     $package = SQL::Schema::Package->select($dbh,$name);

   The select method fetches the attributes required by new from the
database and returns the package object. (It calls new internally.)

   If the package with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the package without preceeding schema name.

Methods
-------

   The following attribute methods do exist:

     $type = $package->type;

   The method type always returns the string "package".  This package
inherits all the other methods from SQL::Schema::Source as a database
package basically is a special kind of source within the database. For
more information, please have a look at `SQL::Schema::Source(3)' in this
node.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Package is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,
`SQL::Schema::Source(3)' in this node


File: pm.info,  Node: SQL/Schema/Package/Body,  Next: SQL/Schema/Procedure,  Prev: SQL/Schema/Package,  Up: Module List

A package's body stored within the database
*******************************************

NAME
====

   SQL::Schema::Package::Body - A package's body stored within the database

SYNOPSIS
========

     my $body = SQL::Schema::Package::Body->new(%attr);

     my $sql = $body->create_statement;
     print $sql;

     print "$body";

DESCRIPTION
===========

   `SQL::Schema::Package::Body' is a class for objects representing a
package's body stored within the database.  The methods of an instanciated
object do allow to access the information within a database's data
dictionary and to represent them as SQL create statements and the like
using the proper SQL dialect.

Constructors
------------

     $body = SQL::Schema::Package::Body->new(%attr);

   The new method instanciates a package body object. The object is an in
memory representation of a (possible) database package body.  The
attributes are given as key value pairs by the hash %attr.  Possible keys
are:

     key               required?   value description

     name              yes         the name of the package
                                   without preceeding schema name

     text              yes         the concatenation of all the text lines
                                   forming the packag body's source code

   As a package body is basically a piece of source stored within the
database, this class inherits all methods from `SQL::Schema::Source'.  So
please have a look at the new method describet at `SQL::Schema::Source(3)'
in this node. Though the new method here overwrites the new method there,
it calls the super class's new method with just the key value pair for the
source's type added.

     $body = SQL::Schema::Package::Body->select($dbh,$name);

   The select method fetches the attributes required by new from the
database and returns the package body object. (It calls new internally.)

   If the package body with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the package without preceeding schema name.

Methods
-------

   The following attribute methods do exist:

     $type = $body->type;

   The method type always returns the string "`package body'".  This
package inherits all the other methods from SQL::Schema::Source as a
database package body basically is a special kind of source within the
database. For more information, please have a look at
`SQL::Schema::Source(3)' in this node.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Package::Body is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,
`SQL::Schema::Source(3)' in this node


File: pm.info,  Node: SQL/Schema/Procedure,  Next: SQL/Schema/Sequence,  Prev: SQL/Schema/Package/Body,  Up: Module List

A procedure stored within the database
**************************************

NAME
====

   SQL::Schema::Procedure - A procedure stored within the database

SYNOPSIS
========

     my $procedure = SQL::Schema::Procedure->new(%attr);

     my $sql = $procedure->create_statement;
     print $sql;

     print "$procedure";

DESCRIPTION
===========

   `SQL::Schema::Procedure' is a class for objects representing a procedure
stored within the database.  The methods of an instanciated object do
allow to access the information within a database's data dictionary and to
represent them as SQL create statements and the like using the proper SQL
dialect.

Constructors
------------

     $procedure = SQL::Schema::Procedure->new(%attr);

   The new method instanciates a procedure object. The object is an in
memory representation of a (possible) database procedure.  The attributes
are given as key value pairs by the hash %attr.  Possible keys are:

     key               required?   value description

     name              yes         the name of the procedure
                                   without preceeding schema name

     text              yes         the concatenation of all the text lines
                                   forming the procedure's source code

   As a procedure is basically a piece of source stored within the
database, this class inherits all methods from `SQL::Schema::Source'.  So
please have a look at the new method describet at `SQL::Schema::Source(3)'
in this node. Though the new method here overwrites the new method there,
it calls the super class's new method with just the key value pair for the
source's type added.

     $procedure = SQL::Schema::Procedure->select($dbh,$name);

   The select method fetches the attributes required by new from the
database and returns the procedure object. (It calls new internally.)

   If the procedure with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the procedure without preceeding schema name.

Methods
-------

   The following attribute methods do exist:

     $type = $procedure->type;

   The method type always returns the string "`procedure'".  This package
inherits all the other methods from SQL::Schema::Source as a database
procedure basically is a special kind of source within the database. For
more information, please have a look at `SQL::Schema::Source(3)' in this
node.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Procedure is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,
`SQL::Schema::Source(3)' in this node


File: pm.info,  Node: SQL/Schema/Sequence,  Next: SQL/Schema/Source,  Prev: SQL/Schema/Procedure,  Up: Module List

An Oracle sequence
******************

NAME
====

   SQL::Schema::Sequence - An Oracle sequence

SYNOPSIS
========

     my $sequence = SQL::Schema::Sequence->new(%attr);

     my $sql = $sequence->create_statement;
     print $sql;

     print "$sequence";

DESCRIPTION
===========

   `SQL::Schema::Sequence' is a class for objects representing an Oracle
sequence. The methods of an instanciated object do allow to access the
information within a database's data dictionary and to represent them as
SQL create statements and the like using the proper SQL dialect.

Constructors
------------

     $sequence = SQL::Schema::Sequence->new(%attr);

   The new method instanciates a sequence object. The object is an in
memory representation of a (possible) oracle sequence.  The attributes are
given as key value pairs by the hash %attr.  Possible keys are:

     key            required?   value description

     schema_name    no          The name of the schema for

     sequence_name  yes         The name of the sequence (without a
                                preceeding schema name).

     min_value      no          number
     max_value      no          number
     increment_by   yes         number
     cycle_flag     no          either `Y' or `N'; default: `N'
     order_flag     no          either `Y' or `N'; default: `N'
     cache_size     yes         number
     start_with     yes         number

   These keys (except `schema_name' and `start_with') and their possible
values correspond exactly to the data dictionary view `user_sequences' and
are described within Oracle's Server Reference.

   The value for `start_with' is the number the sequence should start with.

     $sequence = SQL::Schema::Sequence->select($dbh,$name);
     $sequence = SQL::Schema::Sequence->select($dbh,$name,$schema_name);

   The select method fetches the attributes required by new from the
database and returns the sequence object. (It calls new internally.) It
takes the following arguments:

   If the sequence with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the sequence without preceeding schema name.

`$schema_name'
     Optionally the name of the database schema.

     Warning: The method introduces a bug. The value for `start_with'
     required by the new method is selecte as `last_number + increment_by'.
     If the resulting value is outside the inverval given by `min_value'
     and `max_value' this is not checked. This means: In extreme cases it
     might happen, that the statement produced by the *create_statement*
     method can not really be executed on by a database.

Methods
-------

   The following attribute methods do return the current value of the
attributes (as handed over to the new method):

     $schema_name = $sequence->schema_name;
     $name = $sequence->name;
     $min_value = $sequence->min_value;
     $max_value = $sequence->max_value;
     $increment_by = $sequence->increment_by;
     $cycle_flages = $sequence->cycle_flags;
     $order_flags = $sequence->order_flags;
     $cache_size = $sequence->cache_size;
     $start_with = $sequence->start_with;

   The return value of *cycle_flag* resp. *order_flag* is either Y or N.
This is somewhat uncomfortable for perl programmers. You might want to use
the following two methods instead:

     $cycle_flag = $sequence->cycle;
     $order_flag = $sequence->order;

   They do return 1 resp. 0 where their corresponding attribute method
returns Y resp. N.

     my $qname = $sequence->qualified_name;

   Returns the qualified name of the sequence which is the concatenation
of `schema_name' and `sequence_name' with a in between if `schema_name'
has been set. Otherwise only `sequence_name' is returned.

     $sql = $sequence->create_statement;
     $sql = "$sequence";

   Returns a string containing an SQL statements for creation of a
sequence. This method is overloaded with the string operator.  So the two
examples above are equivalent.

     $sql = $sequence->drop_statement;

   Returns a string containing an SQL statement that would drop this
sequence.

BUGS
====

   The select method introduces a bug. This occurs if the value selected
from the database for `start_with' is not valid. For more information see
warning at select.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Sequence is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node


File: pm.info,  Node: SQL/Schema/Source,  Next: SQL/Schema/Table,  Prev: SQL/Schema/Sequence,  Up: Module List

A source stored within the database
***********************************

NAME
====

   SQL::Schema::Source - A source stored within the database

SYNOPSIS
========

     my $source = SQL::Schema::Source->new(%attr);

     my $sql = $source->create_statement;
     print $sql;

     print "$source";

DESCRIPTION
===========

   `SQL::Schema::Source' is a class for objects representing the source of
a package, function, procedure etc. stored within the database.  The
methods of an instanciated object do allow to access the information
within a database's data dictionary and to represent them as SQL create
statements and the like using the proper SQL dialect.

Constructors
------------

     $source = SQL::Schema::Source->new(%attr);

   The new method instanciates a source object. The object is an in memory
representation of a (possible) database source.  The attributes are given
as key value pairs by the hash %attr.  Possible keys are:

     key               required?   value description

     name              yes         the name of the package, procedure,
                                   function, ... without preceeding
                                   schema name

     type              yes         the type of the source; e.g.
                                     `procedure', `function',
                                     `package', `package body', ...

     text              yes         the concatenation of all the text lines
                                   forming the source code

   All the keys correspond to the columns with the same name from Oracle's
data dictionary view `user_sources'. Only text is somewhat special: It has
to be a concatenation of the source lines.

     $source = SQL::Schema::Source->select($dbh,$name,$type);

   The select method fetches the attributes required by new from the
database and returns the source object. (It calls new internally.)

   If the source with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the source without preceeding schema name.

$type
     The type of the source.

Methods
-------

   The following attribute methods do return the current value of the
attributes (as handed over to the new method):

     $name = $source->name;
     $type = $source->type;
     $text = $source->text;

     $sql = $source->create_statement;
     $sql = "$source";

   Returns a string containing an SQL statements for creation of this
source. This method is overloaded with the string operator.  So the two
examples above are equivalent.

     $sql = $trigger->drop_statement;

   Returns a string containing an SQL statement that would drop this
trigger.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Source is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,


File: pm.info,  Node: SQL/Schema/Table,  Next: SQL/Schema/Table/Column,  Prev: SQL/Schema/Source,  Up: Module List

A database table
****************

NAME
====

   SQL::Schema::Table - A database table

SYNOPSIS
========

     my $table = SQL::Schema::Table->new(%attr);

     my $sql = $table->create_statement;
     print $sql;

     print "$table";

DESCRIPTION
===========

   `SQL::Schema::Table' is a class for objects representing a database
table. The methods of an instanciated object do allow to access the
information within a database's data dictionary and to represent them as
SQL create statements and the like using the proper SQL dialect.

Constructors
------------

     $table = SQL::Schema::Table->new(%attr);

   The new method instanciates a table object. The object is an in memory
representation of a (possible) database table.  The attributes are given
as key value pairs by the hash %attr.  Possible keys are:

     key              required?   value description

     schema_name      no          The name of the schema for

     table_name       yes         The name of the table (without a
                                  preceeding schema name).

     columns          yes         a reference to a list of
                                  column objects

     pct_free         no          number
     pct_used         no          number
     ini_trans        no          number

   These keys (except `schema_name' and columns) and their possible values
correspond exactly to the data dictionary view `user_tables' and are
described within Oracle's Server Reference.

   Optionally the following keys and values which do have no counter part
within the view `user_tables' are allowed for the attribute hash:

     key           value description

     constraints   a reference to a list of constraint objects
                   (objects of type SQL::Schema::Constraint for instance)

     $table = SQL::Schema::Table->select($dbh,$name,$schema_name);

   The select method fetches the attributes required by new from the
database and returns the table object. (It calls new internally.)

   If the table with the name $name could not be found within the
database, the method returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

$name
     The name of the table without preceeding schema name.

`$schema_name'
     The name of the database schema.

Methods
-------

   The following attribute methods do return the current value of the
attributes (as handed over to the new method):

     $schema_name = $table->schema_name;
     $name = $table->name;
     @columns = $table->columns;
     $pct_free = $table->pct_free;
     $pct_used = $table->pct_used;
     $ini_trans = $table->ini_trans;
     @constraints = $table->constraints;

     my $qname = $table->qualified_name;

   Returns the qualified name of the table which is the concatenation of
`schema_name' and table_name with a in between if `schema_name' has been
set. Otherwise only table_name is returned.

     $sql = $table->create_statement;
     $sql = "$table";

   Returns a string containing an SQL statements for creation of this
table. This method is overloaded with the string operator.  So the two
examples above are equivalent.

     $sql = $table->drop_statement;

   Returns a string containing an SQL statement that would drop this table.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Table is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema(3)' in this node,
`SQL::Schema::Table::Column(3)' in this node, `SQL::Schema::Constraint(3)'
in this node


File: pm.info,  Node: SQL/Schema/Table/Column,  Next: SQL/Schema/Trigger,  Prev: SQL/Schema/Table,  Up: Module List

A column of a database table
****************************

NAME
====

   SQL::Schema::Table::Column - A column of a database table

SYNOPSIS
========

     my $column = SQL::Schema::Table::Column->new(%attr);

     my $sql = $column->column_definition;
     print $sql;

     print "$column";

DESCRIPTION
===========

   `SQL::Schema::Table::Column' is a class for objects representing a
database table's column. The methods of an instanciated object do allow to
access the information within a database's data dictionary and to
represent them as SQL create statements and the like using the proper SQL
dialect.

Constructors
------------

     $column = SQL::Schema::Table::Column->new(%attr);

   The new method instanciates a column object. The object is an in memory
representation of a (possible) database table's column.  The attributes
are given as key value pairs by the hash %attr.  Possible keys are:

     key              required?   value description

     column_name      yes         The name of the table's column.

     data_type        yes         number
     data_length      no          number
     data_precision   no          number
     data_scale       no          number
     nullable         no          either `Y' o `N'; default: `Y'
     data_default     no          a character string approbriate as
                                  expression after the `default' keyword
                                  (might include quotes)

   These keys and their possible values correspond exactly to the data
dictionary view `all_tab_columns' and are described within Oracle's Server
Reference.

     $column = SQL::Schema::Table::Column->select($dbh,$table_name,$column_name);

   The select method fetches the attributes required by new from the
database and returns the column object. (It calls new internally.)

   If the column could not be found within the database, the method
returns undef.

   The method's arguments are as follows:

$dbh
     A database handle as defined by `DBI(3)' in this node.

`$table_name'
     The name of the table without preceeding schema name.

`$column_name'
     The name of the column.

Methods
-------

   The following attribute methods do return the current value of the
attributes (as handed over to the new method):

     $column_name = $column->name;
     $data_type = $column->data_type;
     $data_length = $column->data_length;
     $data_precision = $column->data_precision;
     $data_scale = $column->data_scale;
     $nullable = $column->nullable;
     $data_default = $column->data_default;

   There does exist a speciallity for the `data_default' method: If the
attribute `data_default' the method `data_default' returns the content of
the attribute with eleminated trailing new line.

   The return value of *nullable* is either Y or N.  This is somewhat
uncomfortable for perl programmers.  You might want to use the following
method instead:

     $nullable = $sequence->nullable_bool;

   It does return 1 resp. 0 where its corresponding attribute method
returns Y resp. N.

     $sql = $column->column_definition;
     $sql = "$column";

   Returns a string containing the column definition which could be used
as part of an SQL statements for creation of the corresponding column.
This method is overloaded with the string operator. So the two examples
above are equivalent.

AUTHOR AND COPYRIGHT
====================

     SQL::Schema::Table::Column is Copyright (C) 2000,
       Torsten Hentschel
       Windmuehlenweg 47
       44141 Dortmund
       Germany

     Email: todd@bayleys.ping.de

     All rights reserved.

     You may distribute this package under the terms of either the GNU
     General Public License or the Artistic License, as specified in the
     Perl README file.

SEE ALSO
========

   `DBI(3)' in this node, `SQL::Schema::Table(3)' in this node