GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DBIX::SQLENGINE::RECORD::BASE (3)

.ds Aq ’

NAME

DBIx::SQLEngine::Record::Base - Base Class for Records

CONTENTS

SYNOPSIS

<B>Setup:B> Several ways to create a class.



  my $sqldb = DBIx::SQLEngine->new( ... );

  $class_name = $sqldb->record_class( $table_name );
 
  $sqldb->record_class( $table_name, $class_name );
 
  package My::Record;
  use DBIx::SQLEngine::Record::Class -isasubclass, @Traits;



<B>Basics:B> Common operations on a record.



  $record = $class_name->new_with_values(somefield => My Value);
 
  print $record->get_values( somefield );

  $record->change_values( somefield => New Value );



<B>Fetch:B> Retrieve records by ID or other query.



  $record = $class_name->select_record( $primary_key );
 
  @records = $class_name->fetch_select(%clauses)->records;



<B>Modify:B> Write changes to the data source.



  $record->insert_record();
 
  $record->update_record();
 
  $record->delete_record();



DESCRIPTION

DBIx::SQLEngine::Record::Base is a superclass for database records in tables accessible via DBIx::SQLEngine.

By subclassing this package, you can easily create a class whose instances represent each of the rows in a SQL database table.

SIMPLE RECORD OBJECT

The following concrete methods provide a constructor, accessor, mutator and destructor for a record object.

    Constructor

You may create your own records for new instances, or fetch records from the database as described in FETCHING DATA
new_empty_record()


  $class_name->new_empty_record() : $empty_record



Creates and blesses an empty hash object into the given record class.

    Getting and Changing Values

Records are stored as simple hashes, and their contents can typically be accessed that way, but methods are also available to get and set field values.
get_values()


  $record->get_values( key1 ) : $value
  $record->get_values( key1, key2, ... ) : $values_joined_with_comma
  $record->get_values( key1, key2, ... ) : @values



Returns the values associated with the keys in the provided record.

change_values()


  $record->change_values( key1 => value1, ... )



Sets the associated key-value pairs in the provided record.

    Vivifying and Serializing Records

These methods are called internally by the various public methods and do not need to be called directly.
record_from_db_data()


  $class_name->record_from_db_data( $hash_ref )
  $class_name->record_from_db_data( $hash_ref ) : $record
  $class_name->record_from_db_data( %hash_contents ) : $record



Converts a hash retrieved from the table to a Record object.

record_set_from_db_data()


  $class_name->record_set_from_db_data( $hash_array_ref )
  $class_name->record_set_from_db_data( $hash_array_ref ) : $record_set
  $class_name->record_set_from_db_data( @hash_refs ) : $record_set



Converts an array of hashrefs retrieved from the table to a RecordSet::Set object containing Record objects.

record_as_db_data()


  $record->record_as_db_data() : $hash_ref
  $record->record_as_db_data() : %hash_values



Returns an unblessed copy of the values in the record.

    Destructor

DESTROY()


  $record->DESTROY()



For internal use only. Does nothing. Subclasses can override this with any functions they wish called when an individual record is being garbage collected.

CONVENIENCE METHODS

The following wrapper methods chain together combinations of other methods.

    Constructor Methods

new_with_values()


  $class_name->new_with_values ( %key_argument_pairs ) : $record



Calls new_empty_record, and then change_values.

new_copy()


  $record->new_copy() : $new_record
  $record->new_copy( %key_argument_pairs ) : $new_record



Makes a copy of a record and then clears its primary key so that it will be recognized as a distinct, new row in the database rather than overwriting the original when you save it. Also includes any provided arguments in its call to new_with_values.

get_record()


  $class_name->get_record ( ) : $new_empty_record
  $class_name->get_record ( $p_key ) : $fetched_record_or_undef



Calls new if no primary key is provided, or if the primary key is zero; otherwise calls select_record.

    Save Methods

These methods hide the distinction between insert and update.
save_record()


  $record->save_record () : $record_or_undef



Determines whether the record has an primary key assigned to it and then calls either insert_record or update_record. Returns the record unless it fails to save it.

new_and_save()


  $class_name->new_and_save ( %key_argument_pairs ) : $record



Calls new_empty_record, and then change_and_save.

change_and_save()


  $record->change_and_save ( %key_argument_pairs ) : $record



Calls change_values, and then save_record.

FETCHING DATA

The following abstract methods are to be implemented by subclasses; in particular, see DBIx::SQLEngine::Record::Table.

    Select to Retrieve Records

fetch_one_record()


  $sqldb->fetch_one_record( %select_clauses ) : $record_hash



Retrives one record from the table using the provided SQL select clauses.

fetch_select()


  $class_name->fetch_select ( %select_clauses ) : $record_set



Retrives records from the table using the provided SQL select clauses.

visit_select()


  $class_name->visit_select ( $sub_ref, %select_clauses ) : @results
  $class_name->visit_select ( %select_clauses, $sub_ref ) : @results



Calls the provided subroutine on each matching record as it is retrieved. Returns the accumulated results of each subroutine call (in list context).

    Selecting by Primary Key

select_record()


  $class_name->select_record ( $primary_key_value ) : $record_obj
  $class_name->select_record ( \@compound_primary_key ) : $record_obj
  $class_name->select_record ( \%hash_with_primary_key_value ) : $record_obj



Fetches a single record by primary key.

The row hash is blessed into the record class before being returned.

select_records()


  $class_name->select_records ( @primary_key_values_or_hashrefs ) : $record_set



Fetches a set of one or more records by primary key.

Each row hash is blessed into the record class before being wrapped in a RecordSet::Set object.

ALTERING DATA

The following abstract methods are to be implemented by subclasses; in particular, see DBIx::SQLEngine::Record::Table.

    Insert to Add Records

After constructing a record with one of the new_*() methods, you may save any changes by calling insert_record.
insert_record()


  $record_obj->insert_record() : $flag



Adds the values from this record to the table. Returns the number of rows affected, which should be 1 unless there’s an error.

    Update to Change Records

After retrieving a record with one of the fetch methods, you may save any changes by calling update_record.
update_record()


  $record_obj->update_record() : $record_count



Attempts to update the record using its primary key as a unique identifier. Returns the number of rows affected, which should be 1 unless there’s an error.

    Delete to Remove Records

delete_record()


  $record_obj->delete_record() : $record_count



Delete this existing record based on its primary key. Returns the number of rows affected, which should be 1 unless there’s an error.

SEE ALSO

For more about the Record classes, see DBIx::SQLEngine::Record::Class.

See DBIx::SQLEngine for the overall interface and developer documentation.

See DBIx::SQLEngine::Docs::ReadMe for general information about this distribution, including installation and license information.

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 221: ’=item’ outside of any ’=over’
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 SQLENGINE::RECORD::BASE (3) 2004-11-22

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.