X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=htdocs%2Fdocs%2Fman%2FFS%2FRecord.html;fp=htdocs%2Fdocs%2Fman%2FFS%2FRecord.html;h=0000000000000000000000000000000000000000;hp=cc3d3779530db44864e335f2cf2c479a03f70cae;hb=1d758388ce3b17b8de1ae1d3a8ec39c1026baefc;hpb=e6cf4af2b9d3ffefebe1a3e358f0674f566b56bc diff --git a/htdocs/docs/man/FS/Record.html b/htdocs/docs/man/FS/Record.html deleted file mode 100644 index cc3d37795..000000000 --- a/htdocs/docs/man/FS/Record.html +++ /dev/null @@ -1,342 +0,0 @@ - - -FS::Record - Database record objects - - - - - - - - -

NAME
SYNOPSIS
DESCRIPTION
CONSTRUCTORS
METHODS
SUBROUTINES
VERSION
BUGS
SEE ALSO

- - -

NAME

FS::Record - Database record objects

SYNOPSIS

-    use FS::Record;
-    use FS::Record qw(dbh fields qsearch qsearchs dbdef);

-    $record = new FS::Record 'table', \%hash;
-    $record = new FS::Record 'table', { 'column' => 'value', ... };

-    $record  = qsearchs FS::Record 'table', \%hash;
-    $record  = qsearchs FS::Record 'table', { 'column' => 'value', ... };
-    @records = qsearch  FS::Record 'table', \%hash; 
-    @records = qsearch  FS::Record 'table', { 'column' => 'value', ... };

-    $table = $record->table;
-    $dbdef_table = $record->dbdef_table;

-    $value = $record->get('column');
-    $value = $record->getfield('column');
-    $value = $record->column;

-    $record->set( 'column' => 'value' );
-    $record->setfield( 'column' => 'value' );
-    $record->column('value');

-    %hash = $record->hash;

-    $hashref = $record->hashref;

-    $error = $record->insert;
-    #$error = $record->add; #depriciated

-    $error = $record->delete;
-    #$error = $record->del; #depriciated

-    $error = $new_record->replace($old_record);
-    #$error = $new_record->rep($old_record); #depriciated

-    $value = $record->unique('column');

-    $value = $record->ut_float('column');
-    $value = $record->ut_number('column');
-    $value = $record->ut_numbern('column');
-    $value = $record->ut_money('column');
-    $value = $record->ut_text('column');
-    $value = $record->ut_textn('column');
-    $value = $record->ut_alpha('column');
-    $value = $record->ut_alphan('column');
-    $value = $record->ut_phonen('column');
-    $value = $record->ut_anythingn('column');

-    $dbdef = reload_dbdef;
-    $dbdef = reload_dbdef "/non/standard/filename";
-    $dbdef = dbdef;

-    $quoted_value = _quote($value,'table','field');

-    #depriciated
-    $fields = hfields('table');
-    if ( $fields->{Field} ) { # etc.

-    @fields = fields 'table'; #as a subroutine
-    @fields = $record->fields; #as a method call

DESCRIPTION

(Mostly) object-oriented interface to database records. Records are currently -implemented on top of DBI. FS::Record is intended as a base class for -table-specific classes to inherit from, i.e. FS::cust_main.

CONSTRUCTORS

new [ TABLE, ] HASHREF
-

-Creates a new record. It doesn't store it in the database, though. See -insert for that. -

Note that the object stores this hash reference, not a distinct copy of the -hash it points to. You can ask the object for a copy with the hash -method.

TABLE can only be omitted when a dervived class overrides the table method.

qsearch TABLE, HASHREF, SELECT, EXTRA_SQL
-

-Searches the database for all records matching (at least) the key/value pairs -in HASHREF. Returns all the records found as `FS::TABLE' objects if that -module is loaded (i.e. via `use FS::cust_main;'), otherwise returns FS::Record -objects. -

###oops, argh, FS::Record::new only lets us create database fields. -#Normal behaviour if SELECT is not specified is `*', as in -#SELECT * FROM table WHERE .... However, there is an experimental new -#feature where you can specify SELECT - remember, the objects returned, -#although blessed into the appropriate `FS::TABLE' package, will only have the -#fields you specify. This might have unwanted results if you then go calling -#regular FS::TABLE methods -#on it.

qsearchs TABLE, HASHREF
-

-Same as qsearch, except that if more than one record matches, it carps but -returns the first. If this happens, you either made a logic error in asking -for a single item, or your data is corrupted. -

METHODS

table
-

-Returns the table name. -

dbdef_table
-

-Returns the FS::dbdef_table object for the table. -

get, getfield COLUMN
-

-Returns the value of the column/field/key COLUMN. -

set, setfield COLUMN, VALUE
-

-Sets the value of the column/field/key COLUMN to VALUE. Returns VALUE. -

AUTLOADED METHODS
-

-$record->column is a synonym for $record->get('column'); -

$record->column('value') is a synonym for $record->set('column','value');

hash
-

-Returns a list of the column/value pairs, usually for assigning to a new hash. -

To make a distinct duplicate of an FS::Record object, you can do:

-    $new = new FS::Record ( $old->table, { $old->hash } );

hashref
-

-Returns a reference to the column/value hash. -

insert
-

-Inserts this record to the database. If there is an error, returns the error, -otherwise returns false. -

add
-

-Depriciated (use insert instead). -

delete
-

-Delete this record from the database. If there is an error, returns the error, -otherwise returns false. -

del
-

-Depriciated (use delete instead). -

replace OLD_RECORD
-

-Replace the OLD_RECORD with this one in the database. If there is an error, -returns the error, otherwise returns false. -

rep
-

-Depriciated (use replace instead). -

check
-

-Not yet implemented, croaks. Derived classes should provide a check method. -

unique COLUMN
-

-Replaces COLUMN in record with a unique number. Called by the add method -on primary keys and single-field unique columns (see the DBIx::DBSchema::Table manpage). -Returns the new value. -

ut_float COLUMN
-

-Check/untaint floating point numeric data: 1.1, 1, 1.1e10, 1e10. May not be -null. If there is an error, returns the error, otherwise returns false. -

ut_number COLUMN
-

-Check/untaint simple numeric data (whole numbers). May not be null. If there -is an error, returns the error, otherwise returns false. -

ut_numbern COLUMN
-

-Check/untaint simple numeric data (whole numbers). May be null. If there is -an error, returns the error, otherwise returns false. -

ut_money COLUMN
-

-Check/untaint monetary numbers. May be negative. Set to 0 if null. If there -is an error, returns the error, otherwise returns false. -

ut_text COLUMN
-

-Check/untaint text. Alphanumerics, spaces, and the following punctuation -symbols are currently permitted: ! @ # $ % & ( ) - + ; : ' `` , . ? / -May not be null. If there is an error, returns the error, otherwise returns -false. -

ut_textn COLUMN
-

-Check/untaint text. Alphanumerics, spaces, and the following punctuation -symbols are currently permitted: ! @ # $ % & ( ) - + ; : ' `` , . ? / -May be null. If there is an error, returns the error, otherwise returns false. -

ut_alpha COLUMN
-

-Check/untaint alphanumeric strings (no spaces). May not be null. If there is -an error, returns the error, otherwise returns false. -

ut_alpha COLUMN
-

-Check/untaint alphanumeric strings (no spaces). May be null. If there is an -error, returns the error, otherwise returns false. -

ut_phonen COLUMN [ COUNTRY ]
-

-Check/untaint phone numbers. May be null. If there is an error, returns -the error, otherwise returns false. -

Takes an optional two-letter ISO country code; without it or with unsupported -countries, ut_phonen simply calls ut_alphan.

ut_ip COLUMN
-

-Check/untaint ip addresses. IPv4 only for now. -

ut_ipn COLUMN
-

-Check/untaint ip addresses. IPv4 only for now. May be null. -

ut_domain COLUMN
-

-Check/untaint host and domain names. -

ut_anything COLUMN
-

-Untaints arbitrary data. Be careful. -

fields [ TABLE ]
-

-This can be used as both a subroutine and a method call. It returns a list -of the columns in this record's table, or an explicitly specified table. -(See the DBIx::DBSchema::Table manpage). -

SUBROUTINES

reload_dbdef([FILENAME])
-

-Load a database definition (see the DBIx::DBSchema manpage), optionally from a -non-default filename. This command is executed at startup unless -$FS::Record::setup_hack is true. Returns a DBIx::DBSchema object. -

dbdef
-

-Returns the current database definition. See the FS::dbdef manpage. -

_quote VALUE, TABLE, COLUMN
-

-This is an internal function used to construct SQL statements. It returns -VALUE DBI-quoted (see DBI/``quote'') unless VALUE is a number and the column -type (see the FS::dbdef_column manpage) does not end in `char' or `binary'. -

hfields TABLE
-

-This is depriciated. Don't use it. -

It returns a hash-type list with the fields of this record's table set true.

VERSION

$Id: Record.html,v 1.3 2001-04-23 12:40:30 ivan Exp $

BUGS

This module should probably be renamed, since much of the functionality is -of general use. It is not completely unlike Adapter::DBI (see below).

Exported qsearch and qsearchs should be depriciated in favor of method calls -(against an FS::Record object like the old search and searchs that qsearch -and qsearchs were on top of.)

The whole fields / hfields mess should be removed.

The various WHERE clauses should be subroutined.

table string should be depriciated in favor of FS::dbdef_table.

No doubt we could benefit from a Tied hash. Documenting how exists / defined -true maps to the database (and WHERE clauses) would also help.

The ut_ methods should ask the dbdef for a default length.

ut_sqltype (like ut_varchar) should all be defined

A fallback check method should be provided which uses the dbdef.

The ut_money method assumes money has two decimal digits.

The Pg money kludge in the new method only strips `$'.

The ut_phonen method assumes US-style phone numbers.

The _quote function should probably use ut_float instead of a regex.

All the subroutines probably should be methods, here or elsewhere.

Probably should borrow/use some dbdef methods where appropriate (like sub -fields)

As of 1.14, DBI fetchall_hashref( {} ) doesn't set fetchrow_hashref NAME_lc, -or allow it to be set. Working around it is ugly any way around - DBI should -be fixed. (only affects RDBMS which return uppercase column names)