new RecordSet

new RecordSet($tableName, $parameters, $fields)

Up: class RecordSet

This constructor creates a new instance of RecordSet. The parameters for this constructor are:

parameter	description
$tableName	A string containing the name of the table containing the records that are to be manipulated by this instance. This is one of: an internal SQL table name or one of the synonyms defined in class Record, or a comma-separated list of table names which are to be searched in a UNION, or a table name followed by a JOIN expression in which all of the table names may be either internal names or synonyms.
$parameters	An associative array of 'fieldname' => value pairs to define the subset of the records in the table that are represented by this instance. The parameter can also be an array of instances of the class implied by $tableName to be converted into a RecordSet If this parameter is omitted, or null the resulting object is an empty RecordSet.
$fields	If a UNION of tables is specified then all of the tables would have to implement the exact same set of fields with at least compatible data types. If this is not the case then this parameter is used to specify the real names of the fields that are to be included in the set. This field is also used with a JOIN of tables as otherwise the response would contain all of the fields in all of the tables.

Special identifiers that may be used in the second parameter are:

name	function
'offset'	to set the contents of the OFFSET clause
'limit'	to set the contents of the LIMIT clause
'groupby'	to set the contents of the GROUP BY clause
'order'	to set the contents of the ORDER BY clause
'loosesurname'	if set to 'Y', 'y', or boolean true causes the 'surname' field to be compared using a looser algorithm, as discussed in $recordset->getSurnameChk($table, $value).
'"offset"'	to reference a field with the name "offset"
'"limit"'	to reference a field with the name "limit"
'"groupby"'	to reference a field with the name "groupby"
'"order"'	to reference a field with the name "order"
integer	the parameter value is an associative array of 'fieldname' => value pairs which are combined by operator OR

How the database search is performed depends upon the data type of the field in the database.

If the database field is a string then the value is interpreted as a regular expression pattern. For example:

value	Interpretation
'text'	matches any string that contains 'text'
'^text'	matches any string that starts with 'text'
'text$'	matches any string that ends with 'text'
'^text$'	matches the string 'text'
'LIKE text'	matches using the SQL LIKE command there '_' matches any single character and '%' matches multiple characters.
'!text'	matches any string that is not equal to 'text'
'length=nn'	matches any string whose length matches the length specified with decimal digits
'length>nn'	matches any string whose length is greater than the length specified with decimal digits
County	matches the identifying code for the instance of class County
Township	matches the identifying code for the instance of class Township
Record	matches the $record->get('name')
array	matches any of the string values in the array

If an unrecoverable problem occurs in this constructor, the constructor throws an Exception but the only situations where this would happen indicate a logic error in the application, for example a failure to establish a connection to the database server or a bug in creating the SQL statement. Most errors are reported by adding text onto the warnings report displayed by calling the global function showtrace(), or including the insertion point $TRACE in a template, and ignoring the invalid parameter.

Examples:

$smiths	        = new RecordSet('Names', array('surname' => 'Smith','limit' => 20, 'offset' => 0));
$domains	= new RecordSet('Domains');	// empty set of Domains
$offset         = 0;
do {
    $domains	= new RecordSet('Domains',
                                array('limit' => 20,
                                      'offset' => $offset));	// set of all Domains 20 at a time
    foreach ($domains as $id => $domain)
    {
        ...
    }
    $offset     += 20;
} while(count($domains) == 20);
$entries	= new RecordSet('tblDM ' .
		    'JOIN tblIR AS 'Left' ON IdirLeft='Left'.Idir '.
		    'JOIN tblIR AS 'Right' ON IdirRight='Right'.Idir',
			    $parms);
$entries	= new RecordSet('Census1851,Census1861,Census1871,' . 					 'Census1881,Census1891,Census1901,' .
					 'Census1906,Census1911,Census1916,' .
					 'Census1921',
				      $parms,
		'District, SubDistrict, Division, Page, Line,' .
		'Surname, GivenNames, Age, BYear, D_Name, SD_Name,' .
		'BPlace, Occupation, IDIR, Sex ');
$list		= new RecordSet('Sources',
 				array('idst'	=> 14));
$information	= $list->getInformation();
print_r($information);
print "Query='" . $information['query'] . "'";
print "Size of list " . $list->count();
foreach($list as $key => $record)
{		// iterate over set
     ...	parms
}		// iterate over set
$count	= $list->update(array('idst'	=> 15));
$count	= $list->delete();
$empty	= new RecordSet('Sources', array());// empty set
$whole	= new RecordSet('Sources');		// whole table	
$conv	= new RecordSet('Sources',		// from array
 			array(17 => new Source(array('idsr' => 17)),	
			      18 => new Source(array('idsr' => 18)),	
 			      19 => new Source(array('idsr' => 19)));
$conv[20]	= new Source(array('idsr' => 20));	// add to set
unset($conv[18]);					// remove from set
// observe use of external synonyms for table names
$children	= new RecordSet('Children' .
	' INNER JOIN Persons ON Children.IDIR=Persons.IDIR',
				array('idmr' 	=> $idmr,
				      'order'	=> 'tblIR.BirthSD');			

Next: $recordset->getInformation()