htdocs/docs/man/Record.txt

   1 NAME
   2     FS::Record - Database record objects
   3
   4 SYNOPSIS
   5         use FS::Record;
   6         use FS::Record qw(dbh fields hfields qsearch qsearchs dbdef);
   7
   8         $record = new FS::Record 'table', \%hash;
   9         $record = new FS::Record 'table', { 'column' => 'value', ... };
  10
  11         $record  = qsearchs FS::Record 'table', \%hash;
  12         $record  = qsearchs FS::Record 'table', { 'column' => 'value', ... };
  13         @records = qsearch  FS::Record 'table', \%hash;
  14         @records = qsearch  FS::Record 'table', { 'column' => 'value', ... };
  15
  16         $table = $record->table;
  17         $dbdef_table = $record->dbdef_table;
  18
  19         $value = $record->get('column');
  20         $value = $record->getfield('column');
  21         $value = $record->column;
  22
  23         $record->set( 'column' => 'value' );
  24         $record->setfield( 'column' => 'value' );
  25         $record->column('value');
  26
  27         %hash = $record->hash;
  28
  29         $hashref = $record->hashref;
  30
  31         $error = $record->add;
  32
  33         $error = $record->del;
  34
  35         $error = $new_record->rep($old_record);
  36
  37         $value = $record->unique('column');
  38
  39         $value = $record->ut_float('column');
  40         $value = $record->ut_number('column');
  41         $value = $record->ut_numbern('column');
  42         $value = $record->ut_money('column');
  43         $value = $record->ut_text('column');
  44         $value = $record->ut_textn('column');
  45         $value = $record->ut_alpha('column');
  46         $value = $record->ut_alphan('column');
  47         $value = $record->ut_phonen('column');
  48         $value = $record->ut_anythingn('column');
  49
  50         $dbdef = reload_dbdef;
  51         $dbdef = reload_dbdef "/non/standard/filename";
  52         $dbdef = dbdef;
  53
  54         $quoted_value = _quote($value,'table','field');
  55
  56         #depriciated
  57         $fields = hfields('table');
  58         if ( $fields->{Field} ) { # etc.
  59
  60         @fields = fields 'table';
  61
  62 DESCRIPTION
  63     (Mostly) object-oriented interface to database records. Records
  64     are currently implemented on top of DBI. FS::Record is intended
  65     as a base class for table-specific classes to inherit from, i.e.
  66     FS::cust_main.
  67
  68 METHODS
  69     new TABLE, HASHREF
  70         Creates a new record. It doesn't store it in the database,
  71         though. See the section on "add" for that.
  72
  73         Note that the object stores this hash reference, not a
  74         distinct copy of the hash it points to. You can ask the
  75         object for a copy with the *hash* method.
  76
  77     qsearch TABLE, HASHREF
  78         Searches the database for all records matching (at least)
  79         the key/value pairs in HASHREF. Returns all the records
  80         found as `FS::TABLE' objects if that module is loaded (i.e.
  81         via `use FS::cust_main;'), otherwise returns FS::Record
  82         objects.
  83
  84     qsearchs TABLE, HASHREF
  85         Same as qsearch, except that if more than one record
  86         matches, it carps but returns the first. If this happens,
  87         you either made a logic error in asking for a single item,
  88         or your data is corrupted.
  89
  90     table
  91         Returns the table name.
  92
  93     dbdef_table
  94         Returns the FS::dbdef_table object for the table.
  95
  96     get, getfield COLUMN
  97         Returns the value of the column/field/key COLUMN.
  98
  99     set, setfield COLUMN, VALUE
 100         Sets the value of the column/field/key COLUMN to VALUE.
 101         Returns VALUE.
 102
 103     AUTLOADED METHODS
 104         $record->column is a synonym for $record->get('column');
 105
 106         $record->column('value') is a synonym for $record-
 107         >set('column','value');
 108
 109     hash
 110         Returns a list of the column/value pairs, usually for
 111         assigning to a new hash.
 112
 113         To make a distinct duplicate of an FS::Record object, you
 114         can do:
 115
 116             $new = new FS::Record ( $old->table, { $old->hash } );
 117
 118     hashref
 119         Returns a reference to the column/value hash.
 120
 121     add Adds this record to the database. If there is an error, returns
 122         the error, otherwise returns false.
 123
 124     del Delete this record from the database. If there is an error,
 125         returns the error, otherwise returns false.
 126
 127     rep OLD_RECORD
 128         Replace the OLD_RECORD with this one in the database. If
 129         there is an error, returns the error, otherwise returns
 130         false.
 131
 132     unique COLUMN
 133         Replaces COLUMN in record with a unique number. Called by
 134         the add method on primary keys and single-field unique
 135         columns (see the FS::dbdef_table manpage). Returns the new
 136         value.
 137
 138     ut_float COLUMN
 139         Check/untaint floating point numeric data: 1.1, 1, 1.1e10,
 140         1e10. May not be null. If there is an error, returns the
 141         error, otherwise returns false.
 142
 143     ut_number COLUMN
 144         Check/untaint simple numeric data (whole numbers). May not
 145         be null. If there is an error, returns the error, otherwise
 146         returns false.
 147
 148     ut_numbern COLUMN
 149         Check/untaint simple numeric data (whole numbers). May be
 150         null. If there is an error, returns the error, otherwise
 151         returns false.
 152
 153     ut_money COLUMN
 154         Check/untaint monetary numbers. May be negative. Set to 0 if
 155         null. If there is an error, returns the error, otherwise
 156         returns false.
 157
 158     ut_text COLUMN
 159         Check/untaint text. Alphanumerics, spaces, and the following
 160         punctuation symbols are currently permitted: ! @ # $ % & ( )
 161         - + ; : ' " , . ? / May not be null. If there is an error,
 162         returns the error, otherwise returns false.
 163
 164     ut_textn COLUMN
 165         Check/untaint text. Alphanumerics, spaces, and the following
 166         punctuation symbols are currently permitted: ! @ # $ % & ( )
 167         - + ; : ' " , . ? / May be null. If there is an error,
 168         returns the error, otherwise returns false.
 169
 170     ut_alpha COLUMN
 171         Check/untaint alphanumeric strings (no spaces). May not be
 172         null. If there is an error, returns the error, otherwise
 173         returns false.
 174
 175     ut_alpha COLUMN
 176         Check/untaint alphanumeric strings (no spaces). May be null.
 177         If there is an error, returns the error, otherwise returns
 178         false.
 179
 180     ut_phonen COLUMN
 181         Check/untaint phone numbers. May be null. If there is an
 182         error, returns the error, otherwise returns false.
 183
 184     ut_anything COLUMN
 185         Untaints arbitrary data. Be careful.
 186
 187 SUBROUTINES
 188     reload_dbdef([FILENAME])
 189             Load a database definition (see the FS::dbdef manpage),
 190             optionally from a non-default filename. This command is
 191             executed at startup unless *$FS::Record::setup_hack* is
 192             true. Returns a FS::dbdef object.
 193
 194     dbdef   Returns the current database definition. See the FS::dbdef
 195             manpage.
 196
 197     _quote VALUE, TABLE, COLUMN
 198             This is an internal function used to construct SQL
 199             statements. It returns VALUE DBI-quoted (see the section
 200             on "quote" in the DBI manpage) unless VALUE is a number
 201             and the column type (see the dbdef_column manpage) does
 202             not end in `char' or `binary'.
 203
 204     hfields TABLE
 205             This is depriciated. Don't use it.
 206
 207             It returns a hash-type list with the fields of this
 208             record's table set true.
 209
 210     fields TABLE
 211             This returns a list of the columns in this record's
 212             table (See the dbdef_table manpage).
 213
 214 BUGS
 215         This module should probably be renamed, since much of the
 216         functionality is of general use. It is not completely unlike
 217         Adapter::DBI (see below).
 218
 219         Exported qsearch and qsearchs should be depriciated in favor
 220         of method calls (against an FS::Record object like the old
 221         search and searchs that qsearch and qsearchs were on top
 222         of.)
 223
 224         The whole fields / hfields mess should be removed.
 225
 226         The various WHERE clauses should be subroutined.
 227
 228         table string should be depriciated in favor of
 229         FS::dbdef_table.
 230
 231         No doubt we could benefit from a Tied hash. Documenting how
 232         exists / defined true maps to the database (and WHERE
 233         clauses) would also help.
 234
 235         The ut_ methods should ask the dbdef for a default length.
 236
 237         ut_sqltype (like ut_varchar) should all be defined
 238
 239         A fallback check method should be provided whith uses the
 240         dbdef.
 241
 242         The ut_money method assumes money has two decimal digits.
 243
 244         The Pg money kludge in the new method only strips `$'.
 245
 246         The ut_phonen method assumes US-style phone numbers.
 247
 248         The _quote function should probably use ut_float instead of
 249         a regex.
 250
 251         All the subroutines probably should be methods, here or
 252         elsewhere.
 253
 254 SEE ALSO
 255         the FS::dbdef manpage, the FS::UID manpage, the DBI manpage
 256
 257         Adapter::DBI from Ch. 11 of Advanced Perl Programming by
 258         Sriram Srinivasan.
 259
 260 HISTORY
 261         ivan@voicenet.com 97-jun-2 - 9, 19, 25, 27, 30
 262
 263         DBI version ivan@sisd.com 97-nov-8 - 12
 264
 265         cleaned up, added autoloaded $self->any_field calls, moved
 266         DBI login stuff to FS::UID ivan@sisd.com 97-nov-21-23
 267
 268         since AUTO_INCREMENT is MySQL specific, use my own unique
 269         number generator (again) ivan@sisd.com 97-dec-4
 270
 271         untaint $user in unique (web demo hack...bah) make unique
 272         skip multiple-field unique's from dbdef ivan@sisd.com 97-
 273         dec-11
 274
 275         merge with FS::Search, which after all was just alternate
 276         constructors for FS::Record objects. Makes lots of things
 277         cleaner. :) ivan@sisd.com 97-dec-13
 278
 279         use FS::dbdef::primary key in replace searches, hopefully
 280         for all practical purposes the string/number problem in SQL
 281         statements should be gone? (SQL bites) ivan@sisd.com 98-jan-
 282         20
 283
 284         Put all SQL statments in $statment before we $sth=$dbh-
 285         >prepare( them, for debugging reasons (warn $statement)
 286         ivan@sisd.com 98-feb-19
 287
 288         (sigh)... use dbdef type (char, etc.) instead of a regex to
 289         decide what to quote in _quote (more sillines...) SQL bites.
 290         ivan@sisd.com 98-feb-20
 291
 292         more friendly error messages ivan@sisd.com 98-mar-13
 293
 294         Added import of datasrc from FS::UID to allow Pg6.3 to work
 295         Added code to right-trim strings read from Pg6.3 databases
 296         Modified 'add' to only insert fields that actually have data
 297         Added ut_float to handle floating point numbers (for sales
 298         tax). Pg6.3 does not have a "SHOW FIELDS" statement, so I
 299         faked it 8). bmccane@maxbaud.net 98-apr-3
 300
 301         commented out Pg wrapper around `` Modified 'add' to only
 302         insert fields that actually have data '' ivan@sisd.com 98-
 303         apr-16
 304
 305         dbdef usage changes ivan@sisd.com 98-jun-1
 306
 307         sub fields now asks dbdef, not database ivan@sisd.com 98-
 308         jun-2
 309
 310         added debugging method ->_dump ivan@sisd.com 98-jun-16
 311
 312         use FS::dbdef::primary key in delete searches as well as
 313         replace searches (SQL still bites) ivan@sisd.com 98-jun-22
 314
 315         sub dbdef_table ivan@sisd.com 98-jun-28
 316
 317         removed Pg wrapper around `` Modified 'add' to only insert
 318         fields that actually have data '' ivan@sisd.com 98-jul-14
 319
 320         sub fields croaks on errors ivan@sisd.com 98-jul-17
 321
 322         $rc eq '0E0' doesn't mean we couldn't delete for all rdbmss
 323         ivan@sisd.com 98-jul-18
 324
 325         commented out code to right-trim strings read from Pg6.3
 326         databases; ChopBlanks is in UID.pm ivan@sisd.com 98-aug-16
 327
 328         added code (with Pg wrapper) to deal with Pg money fields
 329         ivan@sisd.com 98-aug-18
 330
 331         added pod documentation ivan@sisd.com 98-sep-6
 332
 333         ut_phonen got ''; at the end ivan@sisd.com 98-sep-27
 334
 335         $Log: Record.txt,v $
 336         Revision 1.3  1998-11-13 09:56:36  ivan
 337         change configuration file layout to support multiple distinct databases (with
 338         own set of config files, export, etc.)
 339  Revision 1.4 1998/11/10 07:45:25 ivan
 340         doc clarification
 341
 342         Revision 1.2 1998/11/07 05:17:18 ivan In sub new, Pg wrapper
 343         for money fields from dbdef (FS::Record::fields $table), not
 344         keys of supplied hashref.
 345