2 FS::Record - Database record objects
6 use FS::Record qw(dbh fields hfields 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->add;
33 $error = $record->del;
35 $error = $new_record->rep($old_record);
37 $value = $record->unique('column');
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');
50 $dbdef = reload_dbdef;
51 $dbdef = reload_dbdef "/non/standard/filename";
54 $quoted_value = _quote($value,'table','field');
57 $fields = hfields('table');
58 if ( $fields->{Field} ) { # etc.
60 @fields = fields 'table';
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.
70 Creates a new record. It doesn't store it in the database,
71 though. See the section on "add" for that.
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.
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
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.
91 Returns the table name.
94 Returns the FS::dbdef_table object for the table.
97 Returns the value of the column/field/key COLUMN.
99 set, setfield COLUMN, VALUE
100 Sets the value of the column/field/key COLUMN to VALUE.
104 $record->column is a synonym for $record->get('column');
106 $record->column('value') is a synonym for $record-
107 >set('column','value');
110 Returns a list of the column/value pairs, usually for
111 assigning to a new hash.
113 To make a distinct duplicate of an FS::Record object, you
116 $new = new FS::Record ( $old->table, { $old->hash } );
119 Returns a reference to the column/value hash.
121 add Adds this record to the database. If there is an error, returns
122 the error, otherwise returns false.
124 del Delete this record from the database. If there is an error,
125 returns the error, otherwise returns false.
128 Replace the OLD_RECORD with this one in the database. If
129 there is an error, returns the error, otherwise returns
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
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.
144 Check/untaint simple numeric data (whole numbers). May not
145 be null. If there is an error, returns the error, otherwise
149 Check/untaint simple numeric data (whole numbers). May be
150 null. If there is an error, returns the error, otherwise
154 Check/untaint monetary numbers. May be negative. Set to 0 if
155 null. If there is an error, returns the error, otherwise
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.
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.
171 Check/untaint alphanumeric strings (no spaces). May not be
172 null. If there is an error, returns the error, otherwise
176 Check/untaint alphanumeric strings (no spaces). May be null.
177 If there is an error, returns the error, otherwise returns
181 Check/untaint phone numbers. May be null. If there is an
182 error, returns the error, otherwise returns false.
185 Untaints arbitrary data. Be careful.
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.
194 dbdef Returns the current database definition. See the FS::dbdef
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'.
205 This is depriciated. Don't use it.
207 It returns a hash-type list with the fields of this
208 record's table set true.
211 This returns a list of the columns in this record's
212 table (See the dbdef_table manpage).
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).
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
224 The whole fields / hfields mess should be removed.
226 The various WHERE clauses should be subroutined.
228 table string should be depriciated in favor of
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.
235 The ut_ methods should ask the dbdef for a default length.
237 ut_sqltype (like ut_varchar) should all be defined
239 A fallback check method should be provided whith uses the
242 The ut_money method assumes money has two decimal digits.
244 The Pg money kludge in the new method only strips `$'.
246 The ut_phonen method assumes US-style phone numbers.
248 The _quote function should probably use ut_float instead of
251 All the subroutines probably should be methods, here or
255 the FS::dbdef manpage, the FS::UID manpage, the DBI manpage
257 Adapter::DBI from Ch. 11 of Advanced Perl Programming by
261 ivan@voicenet.com 97-jun-2 - 9, 19, 25, 27, 30
263 DBI version ivan@sisd.com 97-nov-8 - 12
265 cleaned up, added autoloaded $self->any_field calls, moved
266 DBI login stuff to FS::UID ivan@sisd.com 97-nov-21-23
268 since AUTO_INCREMENT is MySQL specific, use my own unique
269 number generator (again) ivan@sisd.com 97-dec-4
271 untaint $user in unique (web demo hack...bah) make unique
272 skip multiple-field unique's from dbdef ivan@sisd.com 97-
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
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-
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
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
292 more friendly error messages ivan@sisd.com 98-mar-13
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
301 commented out Pg wrapper around `` Modified 'add' to only
302 insert fields that actually have data '' ivan@sisd.com 98-
305 dbdef usage changes ivan@sisd.com 98-jun-1
307 sub fields now asks dbdef, not database ivan@sisd.com 98-
310 added debugging method ->_dump ivan@sisd.com 98-jun-16
312 use FS::dbdef::primary key in delete searches as well as
313 replace searches (SQL still bites) ivan@sisd.com 98-jun-22
315 sub dbdef_table ivan@sisd.com 98-jun-28
317 removed Pg wrapper around `` Modified 'add' to only insert
318 fields that actually have data '' ivan@sisd.com 98-jul-14
320 sub fields croaks on errors ivan@sisd.com 98-jul-17
322 $rc eq '0E0' doesn't mean we couldn't delete for all rdbmss
323 ivan@sisd.com 98-jul-18
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
328 added code (with Pg wrapper) to deal with Pg money fields
329 ivan@sisd.com 98-aug-18
331 added pod documentation ivan@sisd.com 98-sep-6
333 ut_phonen got ''; at the end ivan@sisd.com 98-sep-27
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
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.