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