This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: DbFramework/DataModel, Next: DbFramework/DataModelObject, Prev: DbFramework/Catalog, Up: Module List Data Model class **************** NAME ==== DbFramework::DataModel - Data Model class SYNOPSIS ======== use DbFramework::DataModel; $dm = new DbFramework::DataModel($name,$dsn,$user,$password); $dm->init_db_metadata; @tables = @{$dm->collects_table_l}; %tables = %{$dm->collects_table_h}; @tables = @{$dm->collects_table_h_byname(@tables)}; $sql = $dm->as_sql; $db = $dm->db; $driver = $dm->driver; DESCRIPTION =========== A *DbFramework::DataModel* object represents a database schema. It can be initialised using the metadata provided by a DBI driver and a catalog database (see *Note DbFramework/Catalog: DbFramework/Catalog,). SUPERCLASSES ============ *DbFramework::Util* CLASS METHODS ============= new($name,$dsn,$user,$password) ------------------------------- Create a new *DbFramework::DataModel* object called $name. *$dsn* is the DBI data source name associated with the data model. *$user* and $password are optional arguments specifying the username and password to use when connecting to the database. OBJECT METHODS ============== A data model has a number of tables. These tables can be accessed using the methods *COLLECTS_TABLE_L* and *COLLECTS_TABLE_H*. See `AUTOLOAD()', *Note DbFramework/Util: DbFramework/Util, for the accessor methods for these attributes. name($name) ----------- If $name is supplied sets the data model name. Returns the data model name. db() ---- Returns the name of the database associated with the data model. driver() -------- Returns the name of the driver associated with the data model. as_sql() -------- Returns a SQL string which can be used to create the tables which make up the data model. init_db_metadata() ------------------ Returns a *DbFramework::DataModel* object configured using metadata from the database handle returned by dbh() and the catalog (see *Note DbFramework/Catalog: DbFramework/Catalog,). Foreign keys will be automatically configured for tables in the data model but this method will die() unless the number of attributes in each foreign and related primary key match. SEE ALSO ======== *Note DbFramework/Catalog: DbFramework/Catalog,, *Note DbFramework/Table: DbFramework/Table, and *Note DbFramework/Util: DbFramework/Util,. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ACKNOWLEDGEMENTS ================ This module was inspired by *Msql::RDBMS*.  File: pm.info, Node: DbFramework/DataModelObject, Next: DbFramework/DataType, Prev: DbFramework/DataModel, Up: Module List DataModelObject class ********************* NAME ==== DbFramework::DataModelObject - DataModelObject class SYNOPSIS ======== use DbFramework::DataModelObject; DESCRIPTION =========== Abstract class for CDIF Data Model objects. SUPERCLASSES ============ *DbFramework::Util* AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1998 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/DataType, Next: DbFramework/DataType/ANSII, Prev: DbFramework/DataModelObject, Up: Module List Data type class *************** NAME ==== DbFramework::DataType - Data type class SYNOPSIS ======== use DbFramework::DataType; my $dt = new DbFramework::DataType($name,$length,$extra); $dt->name($name); $dt->length($length); $dt->extra($extra); DESCRIPTION =========== A *DbFramework::DataType* object represents a data type associated with a *DbFramework::Attribute* object. SUPERCLASSES ============ *DbFramework::DefinitionObject* CLASS METHODS ============= new($name,$length,$extra) ------------------------- Create a new *DbFramework::DataType* object. $name is the name of the data type. $length is the length of the data type. *$extra* is any extra information which applies to the data type e.g. *AUTO_INCREMENT* in they case of a Mysql INTEGER data type. name($name) ----------- If $name is supplied, sets the name of the data type. Valid data types are *CHAR DATE DATETIME INT INTEGER TEXT TIMESTAMP VARCHAR*. Returns the name of the data type. length($length) --------------- If $length is supplied, sets the length of the data type. Returns the length of the data type. extra($extra) ------------- If *$extra* is supplied, sets any extra information which applies to the data type e.g. *AUTO_INCREMENT* in they case of a Mysql INTEGER data type. Returns the extra information which applies to the data type. SEE ALSO ======== *Note DbFramework/DefinitionObject: DbFramework/DefinitionObject, AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1998 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/DataType/ANSII, Next: DbFramework/DataType/Mysql, Prev: DbFramework/DataType, Up: Module List ANSII data type class ********************* NAME ==== DbFramework::DataType::ANSII - ANSII data type class SYNOPSIS ======== use DbFramework::DataType::ANSII; $dt = new DbFramework::DataType::ANSII($dbh,$type,$length); $name = $dt->name($name); $type = $type($type); $length = $dt->length($length); $extra = $dt->extra($extra); DESCRIPTION =========== A *DbFramework::DataType::ANSII* object represents an ANSII data type. SUPERCLASSES ============ *DbFramework::DefinitionObject* CLASS METHODS ============= new($dbh,$type,$length) ----------------------- Create a new *DbFramework::DataType* object. $dbh is a DBI database handle. $type is a numeric ANSII type e.g. a type containd in the array reference returned by $sth->{TYPE}. This method will die() unless $type is a member of the set of ANSII types returned by $dbh. $length is the length of the data type. name($name) ----------- If $name is supplied, sets the name of the ANSII data type. Returns the name of the data type. type($type) ----------- If $type is supplied, sets the number of the ANSII data type. Returns the numeric data type. length($length) --------------- If $length is supplied, sets the length of the data type. Returns the length of the data type. extra($extra) ------------- If *$extra* is supplied, sets any extra information which applies to the data type e.g. *AUTO_INCREMENT*. Returns the extra information which applies to the data type. SEE ALSO ======== *Note DbFramework/DefinitionObject: DbFramework/DefinitionObject, AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/DataType/Mysql, Next: DbFramework/DefinitionObject, Prev: DbFramework/DataType/ANSII, Up: Module List Mysql data type class ********************* NAME ==== DbFramework::DataType::Mysql - Mysql data type class SYNOPSIS ======== use DbFramework::DataType::Mysql; $dt = new DbFramework::DataType::ANSII($dbh,$type,$length); $name = $dt->name($name); $type = $dt->type($type); $length = $dt->length($length); $extra = $dt->extra($extra); DESCRIPTION =========== A *DbFramework::DataType::Mysql* object represents a Mysql data type. SUPERCLASSES ============ *DbFramework::DefinitionObject* CLASS METHODS ============= new($dbh,$type,$length,$extra) ------------------------------ Create a new *DbFramework::DataType* object. $dbh is a DBI database handle. $type is a numeric Mysql type e.g. a type containd in the array reference returned by $sth->{mysql_type}. This method will die() unless $type is a member of the set of Mysql types returned by $dbh. $length is the length of the data type. *$extra* is any extra stuff which applies to the type e.g. 'AUTO_INCREMENT'. name($name) ----------- If $name is supplied sets the name of the Mysql data type. Returns the name of the data type. type($type) ----------- If $type is supplied sets the number of the Mysql data type. Returns the numeric data type. length($length) --------------- If $length is supplied sets the length of the data type. Returns the length of the data type. extra($extra) ------------- If *$extra* is supplied sets any extra information which applies to the data type e.g. *AUTO_INCREMENT* in they case of a Mysql INTEGER data type. Returns the extra information which applies to the data type. SEE ALSO ======== *Note DbFramework/DefinitionObject: DbFramework/DefinitionObject, AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/DefinitionObject, Next: DbFramework/ForeignKey, Prev: DbFramework/DataType/Mysql, Up: Module List DefinitionObject class ********************** NAME ==== DbFramework::DefinitionObject - DefinitionObject class SYNOPSIS ======== use DbFramework::DefinitionObject; DESCRIPTION =========== Abstract class for CDIF Definition Object objects. SUPERCLASSES ============ *DbFramework::Util* OBJECT METHODS ============== A definition object contains 0 or more *DbFramework::Attribute* objects. These objects can be accessed using the attributes *CONTAINS_L* and *CONTAINS_H*. See `AUTOLOAD()', *Note DbFramework/Util: DbFramework/Util, for the accessor methods for these attributes. SEE ALSO ======== *Note DbFramework/Util: DbFramework/Util, AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1998 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/ForeignKey, Next: DbFramework/Key, Prev: DbFramework/DefinitionObject, Up: Module List Foreign Key class ***************** NAME ==== DbFramework::ForeignKey - Foreign Key class SYNOPSIS ======== use DbFramework::ForeignKey; $fk = new DbFramework::ForeignKey($name,\@attributes,$primary); $pk = $fk->references($primary); $sql = $fk->as_sql; $html = $fk->as_html_form_field(\%values); DESCRIPTION =========== The *DbFramework::ForeignKey* class implements foreign keys for a table. SUPERCLASSES ============ *DbFramework::Key* CLASS METHODS ============= new($name,\@attributes,$primary) -------------------------------- Returns a new *DbFramework::ForeignKey* object. $name is the name of the foreign key. *@attributes* is a list of *DbFramework::Attribute* objects from a single *DbFramework::Table* object which make up the key. *$primary* is the *DbFramework::Primary* object which the foreign key references. OBJECT METHODS ============== references($primary) -------------------- *$primary* should be a *DbFramework::PrimaryKey* object. If supplied it sets the primary key referenced by this foreign key. Returns the *DbFramework::PrimaryKey* object referenced by this foreign key. as_html_form_field(\%values) ---------------------------- Returns an HTML selection box containing values and labels from the primary key columns in the related table. *%values* is a hash whose keys are the attribute names of the foreign key and whose values indicate the item in the selection box which should be selected by default. See `html_select_field()', *Note DbFramework/PrimaryKey: DbFramework/PrimaryKey,. SEE ALSO ======== *Note DbFramework/Key: DbFramework/Key,, *Note DbFramework/PrimaryKey: DbFramework/PrimaryKey, and *Note DbFramework/Catalog: DbFramework/Catalog,. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998,1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/Key, Next: DbFramework/Persistent, Prev: DbFramework/ForeignKey, Up: Module List Key class ********* NAME ==== DbFramework::Key - Key class SYNOPSIS ======== use DbFramework::Key; $k = new DbFramework::Key($name,\@attributes); $name = $k->name($name); @a = @{$k->incorporates_l(\@attributes)}; @names = $k->attribute_names; $sql = $k->as_sql; $table = $k->belongs_to($table); $html = $k->as_html_heading; DESCRIPTION =========== The *DbFramework::Key* class implements keys (indexes) for a table. SUPERCLASSES ============ *DbFramework::Util* CLASS METHODS ============= new($name,\@attributes) ----------------------- Create a new *DbFramework::Key* object. $name is the name of the key. *@attributes* is a list of *DbFramework::Attribute* objects from a single *DbFramework::Table* object which make up the key. OBJECT METHODS ============== A key incorporates 0 or more attributes. These attributes can be accessed using the attribute *INCORPORATES_L*. See `AUTOLOAD()', *Note DbFramework/Util: DbFramework/Util, for the accessor methods for this attribute. name($name) ----------- If $name is supplied sets the data model name. Returns the data model name. belongs_to($table) ------------------ *$table* is a *DbFramework::Table* object. If supplied sets the table to which this key refers to *$table*. Returns a *DbFramework::Table*. bgcolor($bgcolor) ----------------- If $color is supplied sets the background colour for HTML table cells. Returns the current background colour. attribute_names() ----------------- Returns a list of the names of the attributes which make up the key. as_sql() -------- Returns a string which can be used in an SQL 'CREATE TABLE' statement to create the key. as_html_heading() ----------------- Returns a string for use as a column heading cell in an HTML table; SEE ALSO ======== *Note DbFramework/ForeignKey: DbFramework/ForeignKey,, *Note DbFramework/PrimaryKey: DbFramework/PrimaryKey, and *Note DbFramework/Catalog: DbFramework/Catalog,. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/Persistent, Next: DbFramework/PrimaryKey, Prev: DbFramework/Key, Up: Module List Persistent Perl object base class ********************************* NAME ==== DbFramework::Persistent - Persistent Perl object base class SYNOPSIS ======== package Foo; use base qw(DbFramework::Persistent); package main; $foo = new Foo($table,$dbh); $foo->attributes_h(\%foo}; $foo->insert; $foo->attributes_h(\%new_foo); $foo->update; $foo->delete; $foo->init_pk; @foo = $foo->select($condition,$order); $hashref = $foo->table_qualified_attribute_hashref; $code = DbFramework::Persistent::make_class($name); DESCRIPTION =========== Base class for persistent objects which use a DBI database for storage. To create your own persistent object classes subclass *DbFramework::Persistent* (see the make_class() class method.) SUPERCLASSES ============ *DbFramework::Util* CLASS METHODS ============= new($table,$dbh) ---------------- Create a new persistent object. *$table* is a *DbFramework::Table* object or the name of a database table. $dbh is a DBI database handle which refers to a database containing a table associated with *$table*. make_class($name) ----------------- Returns some Perl code which can be used with eval() to create a new persistent object (sub)class called $name. OBJECT METHODS ============== Attributes in a persistent object which relate to columns in the associated table are made available through the attribute *ATTRIBUTES_H*. See `AUTOLOAD()', *Note DbFramework/Util: DbFramework/Util, for the accessor methods for this attribute. delete() -------- Delete this object from the associated table based on the values of it's primary key attributes. Returns the number of rows deleted if supplied by the DBI driver. insert() -------- Insert this object in the associated table. Returns the primary key of the inserted row if it is a Mysql 'AUTO_INCREMENT' column or -1. update() -------- Update this object in the associated table. Returns the number of rows updated if supplied by the DBI driver. select($conditions,$order) -------------------------- Returns a list of objects of the same class as the object which invokes it. Each object in the list has its attributes initialised from the values returned by selecting all columns from the associated table matching *$conditions* ordered by the list of columns in $order. as_html_form() -------------- Returns an HTML form representing the object, filled with the object's attribute values. init_pk() --------- Initialise an object by setting its attributes based on the current value of the its primary key attributes. table_qualified_attribute_hashref() ----------------------------------- Returns a reference to a hash whose keys are the keys of *%ATTRIBUTES_H* with a prefix of *$table*, where *$table* is the table associated with the object and whose values are values from *%ATTRIBUTES_H*. This is useful for filling a template (see `fill()', *Note DbFramework/Template: DbFramework/Template,.) SEE ALSO ======== *Note DbFramework/Util: DbFramework/Util,, *Note DbFramework/Table: DbFramework/Table, and *Note DbFramework/Template: DbFramework/Template,. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998,1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/PrimaryKey, Next: DbFramework/Table, Prev: DbFramework/Persistent, Up: Module List Primary key class ***************** NAME ==== DbFramework::PrimaryKey - Primary key class SYNOPSIS ======== use DbFramework::PrimaryKey; $pk = new DbFramework::Primary(\@attributes); $sql = $pk->as_sql; $html = $pk->html_pk_select_field(\@column_names,$multiple,\@default); $html = $pk->as_html_heading; $qw = $pk->as_query_string(\%values); DESCRIPTION =========== The *DbFramework::PrimaryKey* class implements primary keys for a table. SUPERCLASSES ============ *DbFramework::Key* CLASS METHODS ============= new(\@attributes) ----------------- Create a new *DbFramework::PrimaryKey* object. *@attributes* is a list of *DbFramework::Attribute* objects from a single *DbFramework::Table* object which make up the key. OBJECT METHODS ============== as_sql() -------- Returns a string which can be used in an SQL 'CREATE TABLE' statement to create the primary key. html_select_field(\@column_names,$multiple,\@default,$name) ----------------------------------------------------------- Returns an HTML form select field where the value consists of the values from the columns which make up the primary key and the labels consist of the corresponding values from *@column_names*. If *@column_names* is undefined the labels consist of the values from all column names. If *$multiple* is defined the field will allow multiple selections. *@default* is a list of values in the select field which should be selected by default. For fields which allow only a single selection the first value in *@default* will be used as the default. If $name is defined it will be used as the name of the select field, otherwise the name will consist of the attribute names of the primary key joined by ',' (comma) and the values will consist of the corresponding attribute values joined by ',' (comma). as_html_heading() ----------------- Returns a string for use as a column heading cell in an HTML table; as_query_string(\%values) ------------------------- Returns a CGI query string consisting of attribute names from the primary key and their corresponding values from *%values*. SEE ALSO ======== *Note DbFramework/Key: DbFramework/Key, AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998,1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/Table, Next: DbFramework/Template, Prev: DbFramework/PrimaryKey, Up: Module List Table class *********** NAME ==== DbFramework::Table - Table class SYNOPSIS ======== use DbFramework::Table; $t = new DbFramework::Table new($name,\@attributes,$pk,$dbh,$dm); $t->init_db_metadata; $dbh = $t->dbh($dbh); $pk = $t->is_identified_by($pk); @fks = @{$t->has_foreign_keys_l}; %fks = %{$t->has_foreign_keys_h}; @keys = @{$t->is_accessed_using_l}; @a = $t->get_attributes(@names); @n = $t->attribute_names; $html = $t->as_html_form; $s = $t->as_string; $sql = $t->as_sql; $rows = $t->delete($conditions); $pk = $t->insert(\%values); $rows = $t->update(\%values,$conditions); @lol = $t->select(\@columns,$conditions,$order); @loh = $t->select_loh(\@columns,$conditions,$order); @a = $t->non_key_attributes; $dm = $t->belongs_to; do_something if $t->in_foreign_key($attribute); do_something if $t->in_key($attribute); do_something if $t->in_primary_key($attribute); do_something if $t->in_any_key($attribute); DESCRIPTION =========== A *DbFramework::Table* object represents a database table (entity). SUPERCLASSES ============ *DbFramework::DefinitionObject* *DbFramework::DataModelObject* CLASS METHODS ============= new($name,\@attributes,$pk,$dbh,$dm) ------------------------------------ Create a new *DbFramework::Table* object. $dbh is a DBI database handle which refers to a database containing a table named $name. *@attribues* is a list of *DbFramework::Attribute* objects. *$primary* is a *DbFramework::PrimaryKey* object. *@attributes* and *$primary* can be omitted if you plan to use the init_db_metadata() object method (see below). *$dm* is a *DbFramework::DataModel* object to which this table belongs. OBJECT METHODS ============== Foreign keys in a table can be accessed using the *HAS_FOREIGN_KEYS_L* and *HAS_FOREIGN_KEYS_H* attributes. Note that foreign key objects will not be created automatically by calling init_db_metadata() on a table object. If you want to automatically create foreign key objects for your tables you should use call init_db_metadata() on a *DbFramework::DataModel* object (see `DbFramework::Datamodel' in this node). Other keys (indexes) defined for a table can be accessed using the *IS_ACCESSED_USING_L* attribute. See `AUTOLOAD()', *Note DbFramework/Util: DbFramework/Util, for the accessor methods for these attributes. is_identified_by($primary) -------------------------- *$primary* is a *DbFramework::PrimaryKey* object. If supplied sets the table's primary key to *$primary*. Returns a *DbFramework::PrimaryKey* object with is the table's primary key. dbh($dbh) --------- $dbh is a DBI database handle. If supplied sets the database handle associated with the table. Returns the database handle associated with the table. belongs_to($dm) --------------- *$dm* is a *DbFramework::DataModel* object. If supplied sets the data model to which the table belongs. Returns the data model to which the table belongs. get_attributes(@names) ---------------------- Returns a list of *DbFramework::Attribute* objects. *@names* is a list of attribute names to return. If *@names* is undefined all attributes associated with the table are returned. attribute_names() ----------------- Returns a list of attribute names for the table. as_html_form() -------------- Returns HTML form fields for all attributes in the table. in_foreign_key($attribute) -------------------------- $attribute is a *DbFramework::Attribute* object. Returns true if $attribute is a part of any foreign key in the table. in_primary_key($attribute) -------------------------- $attribute is a *DbFramework::Attribute* object. Returns true if $attribute is a part of the primary key in the table. in_key($attribute) ------------------ $attribute is a *DbFramework::Attribute* object. Returns true if $attribute is a part of a key (index) in the table. in_any_key($attribute) ---------------------- $attribute is a *DbFramework::Attribute* object. Returns true if $attribute is a part of a key (index), a primary key or a foreign key in the table. non_key_attributes() -------------------- Returns a list of *DbFramework::Attribute* objects which are not members of any key, primary key or foreign key. as_string() ----------- Returns table details as a string. init_db_metadata() ------------------ Returns an initialised *DbFramework::Table* object for the table matching this object's name() in the database referenced by dbh(). as_sql() -------- Returns a string which can be used to create a table in an SQL 'CREATE TABLE' statement. delete($conditions) ------------------- DELETE rows FROM the table associated with this object WHERE the conditions in *$conditions* are met. Returns the number of rows deleted if supplied by the DBI driver. insert(\%values) ---------------- INSERT INTO the table columns corresponding to the keys of *%values* the VALUES corresponding to the values of *%values*. Returns the primary key of the inserted row if it is a Mysql 'AUTO_INCREMENT' column or -1. update(\%values,$conditions) ---------------------------- UPDATE the table SETting the columns matching the keys in %values to the values in %values WHERE *$conditions* are met. Returns the number of rows updated if supplied by the DBI driver. select(\@columns,$conditions,$order) ------------------------------------ Returns a list of lists of values by SELECTing values FROM *@columns* WHERE rows meet *$conditions* ORDERed BY the list of columns in $order. Strings in *@columns* can refer to functions supported by the database in a SELECT clause e.g. `@columns = q/sin(foo),cos(bar),tan(baz)/;' select_loh(\@columns,$conditions,$order) ---------------------------------------- Returns a list of hashrefs containing *(column_name,value)* pairs by SELECTing values FROM *@columns* WHERE rows meet *$conditions* ORDERed BY the list of columns in $order. Strings in *@columns* can refer to functions supported by the database in a SELECT clause e.g. `@columns = q/sin(foo),cos(bar),tan(baz)/;' The keys in the hashrefs will match the name of the function applied to the column i.e. `@loh = $foo->select(\@columns);' `print "sin(foo) = $loh[0]->{sin(foo)}\n";' as_html_heading() ----------------- Returns a string for use as a table heading row in an HTML table. SEE ALSO ======== *Note DbFramework/DefinitionObject: DbFramework/DefinitionObject,, *Note DbFramework/Attribute: DbFramework/Attribute,, *Note DbFramework/DataModelObject: DbFramework/DataModelObject, and *Note DbFramework/DataModel: DbFramework/DataModel,. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998,1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/Template, Next: DbFramework/Util, Prev: DbFramework/Table, Up: Module List Fill template with database values ********************************** NAME ==== DbFramework::Template - Fill template with database values SYNOPSIS ======== use DbFramework::Template; $t = new DbFramework::Template($template,\@tables); print $t->fill; $t->default($table); $t->template->set_text($template); DESCRIPTION =========== *DbFramework::Template* is a class for filling templates with values from a database. Template placeholders --------------------- The following list describes the placeholders allowed in a template. In each case *%values* relates to the hash passed to the fill() method. (:&db_value(table.column):) Replaced with the value from *%values* whose key is *table.column*. See `table_qualified_attribute_hashref()', *Note DbFramework/Persistent: DbFramework/Persistent, for a useful method for generating a hash to fill this type of placeholder. *(:&db_html_form_field(table.column[ value=value][ type=type]):)* Replaced with an HTML form field appropriate for the column column in the table table. value is the inital value which will be applied to the field. The type of field generated is determined by the data type of column. This can be overridden by setting type. See `as_html_form_field()', *Note DbFramework/Attribute: DbFramework/Attribute, for more details. (:&db_fk_html_form_field(table.fk):) Replaced with an HTML form field appropriate for the foreign key *fk* in the table table. See `as_html_form_field()', *Note DbFramework/ForeignKey: DbFramework/ForeignKey, for more details. SUPERCLASSES ============ *DbFramework::Util* CLASS METHODS ============= new($template,\@tables) ----------------------- Create a new *DbFramework::Template* object. $template is the template to be filled. *@tables* are the *DbFramework::Table* objects required for filling the template. OBJECT METHODS ============== template() ---------- Returns the *Text::FillIn* object associated with the template. fill(\%values) -------------- Returns a filled template. The values in *%values* are used to fill certain placeholders in the template (see `"Template placeholders"' in this node.) default($table) --------------- *$table* is a *DbFramework::Table* object. Sets up a default template consisting of all fields in *$table*. SEE ALSO ======== *Note Text/FillIn: Text/FillIn, and *Note DbFramework/Util: DbFramework/Util,. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1999 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: DbFramework/Util, Next: Decision/Markov, Prev: DbFramework/Template, Up: Module List DbFramework utility functions ***************************** NAME ==== DbFramework::Util - DbFramework utility functions SYNOPSIS ======== use DbFramework::Util; ($user,$password) = DbFramework::Util::get_auth(); $dbh = DbFramework::Util::get_dbh($dsn,$user,$password); $sth = DbFramework::Util::do_sql($dbh,$sql); ($user,$password) = DbFramework::Util::get_auth(); $object->debug($n); DESCRIPTION =========== *DbFramework::Util* contains miscellaneous utility functions and acts as a base class for many other *DbFramework* classes. BASE CLASS METHODS ================== AUTOLOAD() ---------- AUTOLOAD() provides default accessor methods (apart from DESTROY()) for any of its subclasses. For AUTOLOAD() to catch calls to these methods objects must be implemented as an anonymous hash. Object attributes must * have UPPER CASE names * have keys in attribute _PERMITTED (an anonymous hash) The name accessor method is the name of the attribute in *lower case*. The 'set' versions of these accessor methods require a single scalar argument (which could of course be a reference.) Both 'set' and 'get' versions return the attribute's value. *Special Attributes* /_L$/ Attribute names matching the pattern /_L$/ will be treated as arrayrefs. These accessors require an arrayref as an argument. If the attribute is defined they return the arrayref, otherwise they return an empty arrayref. A method **_l_add(@foo)* can be called on this type of attribute to add the elements in *@foo* to the array. If the attribute is defined they return the arrayref, otherwise they return an empty arrayref. /_H$/ Attribute names matching the pattern /_H$/ will be treated as hashrefs. These accessors require a reference to an array containing key/value pairs. If the attribute is defined they return the hashref, otherwise they return an empty hashref. A method **_h_byname(@list)* can be called on this type of attribute. These methods will return a list which is the hash slice of the *_H* attribute value over *@list* or an empty list if the attribute is undefined. A method **_h_add(\%foo)* can be called on this type of attribute to add the elements in *%foo* to the hash. If the attribute is defined they return the hashref, otherwise they return an empty hashref. debug($n) --------- As a class method sets the class attribute *$Debugging* to $n. As an object method sets the object attribute *$_DEBUG* to $n. UTILITY FUNCTIONS ================= get_auth() ---------- Read (*$user*,$password) from standard input with no echo when entering password. get_dbh($dsn,$user,$password) ----------------------------- Returns a database handle for the data source name *$dsn* by connecting using *$user* and $password. do_sql($dbh,$sql) ----------------- Executes *$sql* on $dbh and returns a statement handle. This method will die with *$h->errstr* if prepare() or execute() fails. AUTHOR ====== Paul Sharpe COPYRIGHT ========= Copyright (c) 1997,1998 Paul Sharpe. England. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Decision/Markov, Next: Decision/Markov/State, Prev: DbFramework/Util, Up: Module List Markov models for decision analysis *********************************** NAME ==== Decision::Markov - Markov models for decision analysis SYNOPSIS ======== use Decision::Markov; $model = new Decision::Markov; $state = $model->AddState("Name",$utility); $error = $model->AddPath($state1,$state2,$probability); $error = $model->Check $model->Reset([$starting_state,[$number_of_patients]]); $error = $model->StartingState($starting_state[,$number_of_patients]); $model->DiscountRate($rate); ($utility,$cycles) = $model->EvalMC(); $state = $model->EvalMCStep($cycle); ($utility,$cycles) = $model->EvalCoh(); $patients_left = $model->EvalCohStep($cycle); $model->PrintCycle($FH,$cycle); $model->PrintMatrix($FH); DESCRIPTION =========== This module provides functions used to built and evaluate Markov models for use in decision analysis. A Markov model consists of a set of states, each with an associated utility, and links between states representing the probability of moving from one node to the next. Nodes typically include links to themselves. Utilities and probabilities may be fixed or may be functions of the time in cycles since the model began running. METHODS ======= new Create a new Markov model. AddState Add a state to the model. The arguments are a string describing the state and the utility of the state. The utility may be specified either as a number or as a reference to a subroutine that returns the utility. The subroutine will be passed the current cycle number as an argument. Returns the new state, which is an object of class Decision::Markov::State. AddPath Adds a path between two states. The arguments are the source state, the destination state, and the probability of transition. Probability may be specified either as a number or as a reference to a subroutine that returns the probability. The subroutine will be passed the current cycle number as an argument. AddPath returns undef if successful, error message otherwise. Check Checks all states in the model to include that the probabilities of the paths from each state sum to 1. Returns undef if the model checks out, error message otherwise. Reset Resets the model. Use before evaluating the model. StartingState Sets the state in which patients start when the model is evaluated. The optional second argument sets the number of patients in a cohort when performing a cohort simulation. Returns undef if successful or an error message. DiscountRate Sets the per-cycle discount rate for utility. By default, there is no discounting. To set, for example, 3%/cycle discounting, use $model->DiscountRate(.03); If no discount rate is given, returns the current discount rate. EvalMC Performs a Monte Carlo simulation of a single patient through the model, and returns that patient's cumulative utility and the number of cycles the model ran. The patient begins in the state set by StartingState. EvalMCStep Given the current model cycle, evaluates a single step of the Markov model, and returns the patient's new state. Internally continues to track the patient's cumulative utility. EvalCoh Performs a cohort simulation of the model and returns the average cumulative utility of a patient in the cohort, and the number of cycles the model ran. The number of patients and their initial state are set with StartingState. EvalCohStep Evaluates a single cycle of a cohort simulation. Returns the number of patients who will change states in the next cycle (i.e., if it returns 0, you're at the end of the model run). PrintCycle Given a FileHandle object and the cycle, prints the current distribution of patients in the cohort (if a cohort simulation is in progress) or the current state and utility of the patient (if a Monte Carlo simulation is in progress). PrintMatrix Given a FileHandle object, prints the model in transition matrix form REFERENCES ========== Sonnenberg, F. A. & Beck, J. R. (1993). Markov Models in Medical Decision Making: A Practical Guide. Med. Dec. Making, 13: 322-338. COPYRIGHT ========= Copyright (c) 1998 Alan Schwartz . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. REVISION HISTORY ================ 1. March 1988 - Initial concept.  File: pm.info, Node: Decision/Markov/State, Next: DelayLine, Prev: Decision/Markov, Up: Module List Markov state object for Decision::Markov **************************************** NAME ==== Decision::Markov::State - Markov state object for Decision::Markov SYNOPSIS ======== use Decision::Markov::State; $state = new Decision::Markov::State("Name",); $state->Reset(); $state->Name("Name"); $name = $state->Name; $state->NumPatients(100); $num = $state->NumPatients; $utility = $state->Utility($cycle); $error = $state->AddTransition($newstate,$prob); $prob = $state->TransitionProb($newstate[,$cycle]); $total = $state->SumProbs([$cycle]); $boolean = $state->FinalState; $newstate = $state->NextState($cycle); $state->DistributeCohort($cycle); $state->UpdateCohort(); DESCRIPTION =========== This module implements a Markov state object used by Decision::Markov. It's not really intended to be used directly, but for completeness, its public methods are documented here. METHODS ======= new Creates a new Markov state object, given a name for the state and its utility. The utility may be specified either as a number or as a reference to a subroutine which will be called with the current model cycle as its only argument. Reset Resets the state, clearing temporary information that is stored in the state during model evaluations. Name With no argument, returns the name of the state. With an argument, sets the name of the state. NumPatients With no argument, returns the number of patients in the state. With an argument, sets the number of patients in the state. Utility Given the current model cycle, computes and returns the utility of being in the state during that cycle. AddTransition Given a second Markov state, and a transition probability, adds a transition from the first state to the second that will occur with probability equal to the transition probability at the model cycle. Probability can be specified as a number or a reference to a subroutine which will be called with the current model cycle as its only argument. Returns undef if successful or an error message if unsuccessful (e.g., there's already a transition between those states.) TransitionProb Given a second Markov state, return the probability of transitioning from the first state to the second. May return either a number or a reference to a subroutine that can be called with the current model cycle to get the numerical probability. If TransitionProb is given a cycle number as its optional second argument, it will always return the probability during that cycle. If a state doesn't have a transition to the new state, this function returns 0. SumProbs Return the sum of all the transition probabilities from the state. If any of the probabilities are subroutine references, they are evaluated at the cycle given as an argument to SumProbs or at cycle 3 if SumProbs is called without arguments. This function is used to check that probabilities sum to 1. FinalState Returns 1 if the state is a final state: a state with no transitions to states other than itself. Otherwise, returns 0. NextState Given the model cycle, randomly determine and return the next state that a patient in this state will move to, based on the transition probabilities. Used in Monte Carlo evaluations. DistributeCohort Given the model cycle, distribute all of the patients in the state to other states in proportion to their transition probabilities. Note that a state usually transitions to itself as well, so some of the patients are distributed back to the same state. Distributed patients are held in a temporary attribute of the object so that all states can be distributed before calling UpdateCohort to actually set the new number of patients for each state. Used in cohort simulations. UpdateCohort Update the number of patients in this state from the temporary attribute created by DistributeCohort. COPYRIGHT ========= Copyright (c) 1998 Alan Schwartz . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. REVISION HISTORY ================ 1. March 1988 - Initial concept.  File: pm.info, Node: DelayLine, Next: Des, Prev: Decision/Markov/State, Up: Module List Simple time-delay data stucture ******************************* NAME ==== DelayLine - Simple time-delay data stucture SYNOPSIS ======== use DelayLine; my $dl = DelayLine->new(delay => $defaultdelay); $dl->in($item); [ ... ] if (my $ob = $dl->out()) { # do stuff with $ob } DESCRIPTION =========== The `DelayLine' is a simple two-port data structure, like a FIFO, but with variable delay. Each object put into the input of the DelayLine will appear on the output only after some pre-determined amount of time has elapsed. This time can be set as a default for the DelayLine, or can be individually overridden for each object put into the DelayLine. If the default delay time is set to zero, and is not overridden for the individual objects, the DelayLine mimics a straightforward FIFO. The DelayLine accepts any scalar value as input, including references. The DelayLine is a very useful component when building simple event loops. Methods ------- `DelayLine' provides the following methods: DelayLine->new( [ delay => DELAY [, debug => DEBUG ]] ) Returns a newly created `DelayLine' object. The default delay is 0 seconds, unless an optional DELAY time in seconds is given. Debugging is turned off by default. Setting DEBUG to true, enables debugging output to STDOUT. The parameter naming style is very flexible: the keyword can be in lower, upper or mixed case, and can be optionally prefixed with a dash. Thus, the following are all equivalent: $dl = DelayLine->new( -delay => 42 ); $dl = DelayLine->new( delay => 42 ); $dl = DelayLine->new( -Delay => 42 ); $dl = DelayLine->new( DELAY => 42 ); $dl = DelayLine->new( -deLaY => 42 ); new() can be called as a class (static) or object method. Calling new() as an object method is only a convenience; no data from the original DelayLine is carried over into the newly created object. $DL->in( OBJ [, DELAY ] ) This method puts object OBJ into DelayLine `$DL'. The object OBJ can be any scalar value, including references. The default delay as set in the new() method is used, unless overridden by setting DELAY. $DL->out() This method fetches objects from the out from the DelayLine `$DL'. Returns the first of the timed-out objects, if any. Returns undef if the DelayLine is empty, of if no objects in the DelayLine have timed out yet. $DL->delay( [ DELAY ] ) Returns the current default delay setting of the DelayLine. If the optional value DELAY is set, sets a new default delay value. $DL->debug( [ DEBUG ] ) Returns the current debug setting of the DelayLine. If the optional value DEBUG is set, sets a new debug value. If the debug value is set (true), calling any of the 'active' methods (`in()' or `out()' will yield a short debug message on STDERR. BUGS ==== This is a fairly simple module, so no serious bugs are expected. Patches are welcome, though. RELEASE HISTORY =============== v0.02 - 2000-jul-22 Fixed test for multiple unknown args. Removed superfluous test output. Streamlined debug output. v0.01 - 2000-jul-13 Initial release. COPYRIGHT ========= Copyright (c) 2000 Lars Thegler. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Lars Thegler  File: pm.info, Node: Des, Next: Devel/Carp, Prev: DelayLine, Up: Module List Des extension module for Perl ***************************** NAME ==== Des - Des extension module for Perl DESCRIPTION =========== The Des extension module gives access to the DES library. The following is a brief and over-simplified description of the relevant stuff about DES. DES keys are 8-byte blocks. A key is passed to a perl function as an 8-byte string. Before keys can be used to encrypt or decrypt data, the key needs to be transformed into a key schedule using the function set_key. There is a certain amount of overhead in creating these key schedules (which are 128 bytes or 256 bytes depending on implementation and architecture) so they can be created and cached for later if desired. Encryption and decryption can be done in 3 modes: ECB (electronic code book) mode Takes a des_cblock (perl 8-byte string) and produces another des_cblock. (Very rarely useful for large amounts of plain text, subject to known plaintext attacks under certain circumstances, only slightly faster than CBC or PCBC mode, and you lose even this advantage in perl). CBC (cipher block chaining) mode Takes an arbitrary length string, pads it out (internally) on the right with NULs to a multiple of 8-bytes. Encrypts/decrypts the data and produces output (same size as padded input) which is an exact multiple of 8 bytes long. Changing a single bit of the cleartext affects all the following ciphertext. However, changing a single bit of the ciphertext affects only the corresponding cleartext block and the following block. This is occasionally an advantage but is usually a disadvantage. PCBC mode A modified CBC mode with indefinite proagation of single bit errors both from cleartext to ciphertext and from ciphertext to cleartext. "Usually" the best mode (for certain values of "usually"). Functions imported by *use Des*. -------------------------------- string_to_key (STRING) Takes an arbitrary STRING and munges it (with a one-way function) into a DES key, which is returned. set_key (KEY) The DES key KEY (which must be a string of exactly 8 bytes) is turned into a key schedule which is returned. ecb_encrypt (INPUT, SCHEDULE) The INPUT argument (which must be a string of exactly 8 bytes) is encrypted using ECB mode using key schedule SCHEDULE (created using set_key) and the resulting 8-byte string is returned. ecb_decrypt (INPUT, SCHEDULE) The INPUT argument (which must be a string of exactly 8 bytes) is decrypted using ECB mode using key schedule SCHEDULE (created using set_key) and the resulting 8-byte string is returned. cbc_encrypt (INPUT, OUTPUT, SCHEDULE, IV) The INPUT argument can be of arbitrary length, although it will be internally padded on the right with NULs to the nearest multiple of 8 bytes. INPUT is taken and encrypted using CBC mode with key schedule SCHEDULE and initialisation vector IV. If OUTPUT is not undef then it assumed to be an lvalue which is grown (if necessary) and receives the encrypted output. Whether or not OUTPUT is undef, the output is also available as the return value of the function. cbc_decrypt (INPUT, OUTPUT, SCHEDULE, IV) The INPUT argument can be of arbitrary length, although it will be internally padded on the right with NULs to the nearest multiple of 8 bytes. INPUT is taken and decrypted using CBC mode with key schedule SCHEDULE and initialisation vector IV. If OUTPUT is not undef then it assumed to be an lvalue which is grown (if necessary) and receives the decrypted output. Whether or not OUTPUT is undef, the output is also available as the return value of the function. pcbc_encrypt (INPUT, OUTPUT, SCHEDULE, IV) The INPUT argument can be of arbitrary length, although it will be internally padded on the right with NULs to the nearest multiple of 8 bytes. INPUT is taken and encrypted using PCBC mode with key schedule SCHEDULE and initialisation vector IV. If OUTPUT is not undef then it assumed to be an lvalue which is grown (if necessary) and receives the encrypted output. Whether or not OUTPUT is undef, the output is also available as the return value of the function. pcbc_decrypt (INPUT, OUTPUT, SCHEDULE, IV) The INPUT argument can be of arbitrary length, although it will be internally padded on the right with NULs to the nearest multiple of 8 bytes. INPUT is taken and decrypted using PCBC mode with key schedule SCHEDULE and initialisation vector IV. If OUTPUT is not undef then it assumed to be an lvalue which is grown (if necessary) and receives the decrypted output. Whether or not OUTPUT is undef, the output is also available as the return value of the function. pcbc_cksum (INPUT, SCHEDULE, IV) The INPUT argument can be of arbitrary length, although it will be internally padded on the right with NULs to the nearest multiple of 8 bytes. CBC mode is used to generate an 8-byte cryptographic checksum using key schedule SCHEDULE and initialisation vector IV. This checksum is returned. Functions in package Des which can be imported ---------------------------------------------- random_key () Produces a random DES key based on current time, PID and a counter. read_password (PROMPT [, VERIFY]) Prints PROMPT on the terminal, turns off echo if possible and reads a password from the keyboard. If the optional VERIFY argument is present and true than the password is prompted for a second time and the two are compared. If different, the prompting is repeated. The resulting string is turned into a DES key (using string_to_key (q.v.) internally) and that key is returned. AUTHOR ------ Malcolm Beattie, `mbeattie@sable.ox.ac.uk', 6 Dec 1994.