2 FS::Record - Database record objects
6 use FS::Record qw(dbh fields qsearch qsearchs dbdef);
8 $record = new FS::Record 'table', \%hash;
9 $record = new FS::Record 'table', { 'column' => 'value', ... };
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', ... };
16 $table = $record->table;
17 $dbdef_table = $record->dbdef_table;
19 $value = $record->get('column');
20 $value = $record->getfield('column');
21 $value = $record->column;
23 $record->set( 'column' => 'value' );
24 $record->setfield( 'column' => 'value' );
25 $record->column('value');
27 %hash = $record->hash;
29 $hashref = $record->hashref;
31 $error = $record->insert;
32 #$error = $record->add; #depriciated
34 $error = $record->delete;
35 #$error = $record->del; #depriciated
37 $error = $new_record->replace($old_record);
38 #$error = $new_record->rep($old_record); #depriciated
40 $value = $record->unique('column');
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');
53 $dbdef = reload_dbdef;
54 $dbdef = reload_dbdef "/non/standard/filename";
57 $quoted_value = _quote($value,'table','field');
60 $fields = hfields('table');
61 if ( $fields->{Field} ) { # etc.
63 @fields = fields 'table'; #as a subroutine
64 @fields = $record->fields; #as a method call
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.
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.
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.
81 TABLE can only be omitted when a dervived class overrides
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
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.
99 Returns the table name.
102 Returns the FS::dbdef_table object for the table.
105 Returns the value of the column/field/key COLUMN.
107 set, setfield COLUMN, VALUE
108 Sets the value of the column/field/key COLUMN to VALUE.
112 $record->column is a synonym for $record->get('column');
114 $record->column('value') is a synonym for $record-
115 >set('column','value');
118 Returns a list of the column/value pairs, usually for
119 assigning to a new hash.
121 To make a distinct duplicate of an FS::Record object, you
124 $new = new FS::Record ( $old->table, { $old->hash } );
127 Returns a reference to the column/value hash.
130 Inserts this record to the database. If there is an error,
131 returns the error, otherwise returns false.
133 add Depriciated (use insert instead).
136 Delete this record from the database. If there is an error,
137 returns the error, otherwise returns false.
139 del Depriciated (use delete instead).
142 Replace the OLD_RECORD with this one in the database. If
143 there is an error, returns the error, otherwise returns
146 rep Depriciated (use replace instead).
149 Not yet implemented, croaks. Derived classes should provide
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
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.
164 Check/untaint simple numeric data (whole numbers). May not
165 be null. If there is an error, returns the error, otherwise
169 Check/untaint simple numeric data (whole numbers). May be
170 null. If there is an error, returns the error, otherwise
174 Check/untaint monetary numbers. May be negative. Set to 0 if
175 null. If there is an error, returns the error, otherwise
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.
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.
191 Check/untaint alphanumeric strings (no spaces). May not be
192 null. If there is an error, returns the error, otherwise
196 Check/untaint alphanumeric strings (no spaces). May be null.
197 If there is an error, returns the error, otherwise returns
201 Check/untaint phone numbers. May be null. If there is an
202 error, returns the error, otherwise returns false.
205 Untaints arbitrary data. Be careful.
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).
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.
219 dbdef Returns the current database definition. See the FS::dbdef
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'.
230 This is depriciated. Don't use it.
232 It returns a hash-type list with the fields of this
233 record's table set true.
236 $Id: Record.txt,v 1.4 1999-02-09 09:37:51 ivan Exp $
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).
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
248 The whole fields / hfields mess should be removed.
250 The various WHERE clauses should be subroutined.
252 table string should be depriciated in favor of
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.
259 The ut_ methods should ask the dbdef for a default length.
261 ut_sqltype (like ut_varchar) should all be defined
263 A fallback check method should be provided whith uses the
266 The ut_money method assumes money has two decimal digits.
268 The Pg money kludge in the new method only strips `$'.
270 The ut_phonen method assumes US-style phone numbers.
272 The _quote function should probably use ut_float instead of
275 All the subroutines probably should be methods, here or
278 Probably should borrow/use some dbdef methods where
279 appropriate (like sub fields)
282 the FS::dbdef manpage, the FS::UID manpage, the DBI manpage
284 Adapter::DBI from Ch. 11 of Advanced Perl Programming by
288 ivan@voicenet.com 97-jun-2 - 9, 19, 25, 27, 30
290 DBI version ivan@sisd.com 97-nov-8 - 12
292 cleaned up, added autoloaded $self->any_field calls, moved
293 DBI login stuff to FS::UID ivan@sisd.com 97-nov-21-23
295 since AUTO_INCREMENT is MySQL specific, use my own unique
296 number generator (again) ivan@sisd.com 97-dec-4
298 untaint $user in unique (web demo hack...bah) make unique
299 skip multiple-field unique's from dbdef ivan@sisd.com 97-
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
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-
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
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
319 more friendly error messages ivan@sisd.com 98-mar-13
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
328 commented out Pg wrapper around `` Modified 'add' to only
329 insert fields that actually have data '' ivan@sisd.com 98-
332 dbdef usage changes ivan@sisd.com 98-jun-1
334 sub fields now asks dbdef, not database ivan@sisd.com 98-
337 added debugging method ->_dump ivan@sisd.com 98-jun-16
339 use FS::dbdef::primary key in delete searches as well as
340 replace searches (SQL still bites) ivan@sisd.com 98-jun-22
342 sub dbdef_table ivan@sisd.com 98-jun-28
344 removed Pg wrapper around `` Modified 'add' to only insert
345 fields that actually have data '' ivan@sisd.com 98-jul-14
347 sub fields croaks on errors ivan@sisd.com 98-jul-17
349 $rc eq '0E0' doesn't mean we couldn't delete for all rdbmss
350 ivan@sisd.com 98-jul-18
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
355 added code (with Pg wrapper) to deal with Pg money fields
356 ivan@sisd.com 98-aug-18
358 added pod documentation ivan@sisd.com 98-sep-6
360 ut_phonen got ''; at the end ivan@sisd.com 98-sep-27
363 Revision 1.4 1999-02-09 09:37:51 ivan
364 regenerated perl api docs from embedded pod
365 Revision 1.12 1999/01/25 12:26:06 ivan
366 yet more mod_perl stuff
368 Revision 1.11 1999/01/18 09:22:38 ivan changes to track
369 email addresses for email invoicing
371 Revision 1.10 1998/12/29 11:59:33 ivan mostly properly OO,
372 some work still to be done with svc_ stuff
374 Revision 1.9 1998/11/21 07:26:45 ivan "Records identical"
375 carp tells us it is just a warning.
377 Revision 1.8 1998/11/15 11:02:04 ivan bugsquash
379 Revision 1.7 1998/11/15 10:56:31 ivan qsearch gets sames "IS
380 NULL" semantics as other WHERE clauses
382 Revision 1.6 1998/11/15 05:31:03 ivan bugfix for new config
385 Revision 1.5 1998/11/13 09:56:51 ivan change configuration
386 file layout to support multiple distinct databases (with own
387 set of config files, export, etc.)
389 Revision 1.4 1998/11/10 07:45:25 ivan doc clarification
391 Revision 1.2 1998/11/07 05:17:18 ivan In sub new, Pg wrapper
392 for money fields from dbdef (FS::Record::fields $table), not
393 keys of supplied hashref.