ASDoc

mx.remoting
Class RecordSet

All Implemented Interfaces
mx.data.PageableList

class RecordSet
extends Object

The RecordSet object lets you manipulate record sets returned from Flash Remoting or create client-side record sets. A record set is a list of records, with methods for fetching, accessing, and manipulating the list of records in various ways. Record sets created on an application server usually consist of database query results. Each record in a RecordSet object is represented by an untyped ActionScript object. In a RecordSet object, individual records are identified by an index number. The index starts at zero. When the record set is sorted or a record is added to or deleted from the record set, the index changes. Each field of the record is represented by a field in the object. For a RecordSet object that originated from an application server, the field names are the same as the field names defined by the server-side record set. For local RecordSet objects, the field names are the same as defined in the original call to the new RecordSet() function. You can import the RecordSet class using the following import statement:

   import mx.remoting.RecordSet;

Example
The following example retrieves the array of column names from the columnNames property of the cartRecordSet RecordSet and adds the ID column if it is not already there.

   var colNames:Array = cartRecordSet.columnNames;
   var idFound:Boolean = true;
   for( var i:Number = 0; i < colNames.length; i++ )
     idFound = colNames[i] == "ID";
   if( idFound != true )
     scGrid.addColumnAt( 0, "ID" );

The following example retrieves an array of all records in the cartRecordSet RecordSet and computes the total price for all records in the shopping cart.

   var cartItems:Array = cartRecordSet.items;
   var total:Number = 0;
   for( var i:Number=0;i<cartItems.length; i++ )
     total += cartItems[i].price;

The following example retrieves the number of local records in the rs RecordSet from the length property.

   totalRec_txt.text = String( rs.length );

The following modelChanged() function retrieves the length of RecordSet if any event has occurred that might affect the size of the RecordSet.

   function modelChanged(eventObj : Object) : Void {
     var event = eventObj.eventName;
     if (event == "addItems" || event == "removeItems" ||
       event=="updateAll" || event=="filterModel") {
       total_txt.text = String( eventObj.target.length );
     }
   //
   }

Constructors
`RecordSet ( columnNames)`Creates a new local RecordSet object with the specified column names, which is initially empty. Local RecordSet objects never download data from an application server; the RecordSet methods related to data delivery are not available to local RecordSet objects.

Methods
	`addEventListener( event: String, listener) : Void`Registers a listener object with a `modelChanged` event that affects a RecordSet object.
	`addItem( item: Object) : Void`Inserts a record into the RecordSet object.
	`addItemAt( index: Number, item: Object) : Void`Inserts a record into the RecordSet object at the specified index position.
	`clear( ) : Void`Removes all items from the record set.
	`contains( itmToCheck: Object) : Boolean`Determines whether the record set contains the specified record.
	`editField( index: Number, fieldName: String, value: Object) : Void`Replaces the value in one field of a record with a new value.
	`filter( filterFunction: Function, context) : RecordSet`Creates a new RecordSet object by calling the `filterFunction()` function once for each record in the RecordSet object and collecting, into a new RecordSet object, all records for which the `filterFunction()` function returns a value of `true`.
	`getColumnNames( ) : Array`Returns the names of all the columns of a RecordSet object as an array of strings.
	`getEditingData( index: Number, fieldName: String) : Object`Retrieves data for editing from a data provider (record set).
	`getItemAt( index: Number) : Object`Returns a record if the index is valid and the record is immediately available.
	`getItemID( index: Number) : Object`Returns the unique ID for the record at the specified index.
	`getIterator( ) : Iterator`Returns a new iterator on this RecordSet object (collection).
	`getLength( ) : Number`Note: This method is superseded by the `length` property.
	`getLocalLength( ) : Number`Returns the number of records currently available (or downloaded locally).
	`getNumberAvailable( ) : Number`Returns the number of records that have been downloaded from the server.
	`getRemoteLength( ) : Number`Returns the number of records in the RecordSet object on the server side.
	`isEmpty( ) : Boolean`Determines whether the RecordSet object is empty.
	`isFullyPopulated( ) : Boolean`Determines whether a RecordSet object is fully populated, meaning that it has all its records.
	`isLocal( ) : Boolean`Determines whether a RecordSet object is local or, if the record set is associated with an application server, whether records remain to be retrieved from the application server.
	`removeAll( ) : Void`Removes all records from the record set, in a way similar to the `RecordSet.`
	`removeEventListener( event: String, listener) : Void`Removes the specified event listener.
	`removeItemAt( index: Number) : Object`Removes the specified record.
	`replaceItemAt( index: Number, item: Object) : Void`Replaces a record in the RecordSet object at the specified index.
	`setDeliveryMode( mode: String, pagesize: Number, numPrefetchPages: Number) : Void`Changes the delivery mode of a record set associated with an application server.
	`setField( index: Number, fieldName: String, value: Object) : Void`Note: This method is superceeded by the `RecordSet.`
	`sort( compareFunc: Function) : Void`Sorts all the records using a user-specified comparison function.
	`sortItems( compareFunc: Function, optionFlags: Number) : Void`Sorts all the records using a user-specified comparison function.
	`sortItemsBy( fieldNames: Array, order: String, optionFlags: Number) : Void`Sorts all records in the RecordSet object without making a new copy.

Properties
`static`	`version: String` Component version.
	`columnNames: Array [ Read-Only]`Returns the names of all the columns of a RecordSet object as an array of strings.
	`length: Number [ Read-Only]`Returns the number of records currently available, or downloaded locally, in a RecordSet object.
	`items: Array [ Read-Only]`Returns an array of all records of the RecordSet.

Constructor Detail

RecordSet

RecordSet(
										columnNames)

Creates a new local RecordSet object with the specified column names, which is initially empty. Local RecordSet objects never download data from an application server; the RecordSet methods related to data delivery are not available to local RecordSet objects.

Parameters
columnNames: Array - An array of strings in which each string is a name of one of the record set columns.

Example
The following example creates a new local RecordSet object called productList with the columns ProductName, Price, and Color:

   import mx.remoting.RecordSet;
   var productList:RecordSet = new RecordSet(["ProductName", "Price", "Color"]);

Method Detail

addEventListener

addEventListener(
										event:
													String, listener)
										 : Void

Registers a listener object with a modelChanged event that affects a RecordSet object. When the event is triggered, the listener object or function is notified. You can call this method from any RecordSet instance. For example, the following code registers a listener, myListener, that is called when a modelChanged event occurs for the RecordSet instance myRecs:

   myRecs.addEventListener("modelChanged", myListener);

You must define the listener as either an object or a function before you call addEventListener() to register the listener with the record set. If the listener is an object, it must have a callback function defined that is invoked when the event is triggered. Usually, that callback function has the same name as the event with which the listener is registered. For example, if the event is modelChanged, then the name of the function would be modelChanged(). If the listener is a function, the function is invoked when the event is triggered. You can register multiple listeners to a single record set, but you must use a separate call to addEventListener() for each listener. Also, you can register one listener to multiple record sets, but you must use a separate call to addEventListener() for each instance. For example, the following code defines one listener object, myListener, and assigns it to two RecordSet objects, myRecs and coRecs:

   import mx.remoting.RecordSet;
   
   myRecs = new RecordSet();  // create 1st local RecordSet
   coRecs = new RecordSet();  // create 2nd local RecordSet
   myListener = new Object();  // create listener object
   myListener.modelChanged = function(evt){  // create event handler function
      if (evt.eventName == "addItems"){  // check type of event
         trace("Records added");
      } else if (evt.eventName == "removeItems"){  // check type of event
         trace("Records removed");
      }
   }
   myRecs.addEventListener("modelChanged", myListener);   // reg. myRecs listener
   coRecs.addEventListener("modelChanged", myListener);   // reg. coRecs listener

Execution order is not guaranteed. You cannot rely on one listener being called before another. The modelChanged event object is passed to the listener as a parameter. The event object has properties that contain information about the event that occurred. You can use the event object in the listener callback function to access information about what type of event occurred and which instance broadcast the event. In the preceding example, the event object is evt (you can use any identifier as the event object name) and eventname is used in the if statement to determine more specifically what type of event occurred on the record set. For more information, see Event handler summary for the RecordSet class.

Parameters
event: String - A string that specifies the name of the event that triggers the listener.
listener - A reference to a listener object or function that is called when the event occurs.

Example
The following example imports a class file that updates a text field, billable_txt, based on records with a categoryId value of "B" that are added or removed from the billableCustomers_rs RecordSet:

   import mx.remoting.RecordSet;
   import com.mycompany.crm.*;
   
   var billableCustomers_rs:RecordSet = new RecordSet(["name","categoryId"]);
   var bcHandler:BillableCustomerDisplayHandler = new BillableCustomerDisplayHandler(billable_txt,billableCustomers_rs);

The following is the class file BillableCustomerDisplayHandler.as that should be located in the com.mycompany.crm classpath directory:

   import mx.remoting.RecordSet;
   import mx.controls.TextInput;
   
   class com.mycompany.crm.BillableCustomerDisplayHandler extends Object {
   
     function BillableCustomerDisplayHandler( textCtrl:TextInput, rs:RecordSet ) {
       super();
       _billableCustomers = textCtrl;
       rs.addEventListener( "modelChanged", this );
     }
   
     function modelChanged( evt:Object ):Void {
       if( evt.eventName == "addItems" ) {
         var rs:RecordSet = RecordSet( evt.target );
         if( rs.items[evt.firstItem].categoryId == "B" )
           _billableCustomers.text = String(Number( _billableCustomers.text ) +1);
       } else if( evt.eventName == "removeItems" ) {
           for( var i:Number=0; i<evt.lastItem - evt.firstItem; i++ ) {
             if( evt.removedItems[i].categoryId == "B" )
               _billableCustomers.text = String(Number( _billableCustomers.text ) -1);
           } // for
       }  // else
     }
   
     private var _billableCustomers:mx.controls.TextInput;
   }

addItem

addItem(
										item:
													Object)
										 : Void

Inserts a record into the RecordSet object. When you use the addItem() method, make sure that:

The record parameter is an object.
The record parameter has no unknown or missing fields.
The RecordSet object is associated with an application server and is fully populated.

If these prerequisites are not met, you will encounter the following error conditions and results:

The record parameter is not an object. The record is added to the RecordSet object.
The record parameter has unknown or missing fields. The record is added to the RecordSet object.
The RecordSet object is server associated but not fully populated. No record is added to the record set, and the following error message is reported to the Flash Output panel and Debug Console: Operation not allowed on partial RecordSet objects.

Parameters
item: Object - An object that is the item to add to the record set.

Example
The following example adds an item to the empty myRecordSet RecordSet object:

   import mx.remoting.RecordSet;
   var myItem:Object = {name: "John", age:44, phone: "415-999-9999"};
   var myRecordSet:RecordSet = new RecordSet();
   myRecordSet.addItem(myItem);

addItemAt

addItemAt(
										index:
													Number, item:
													Object)
										 : Void

Inserts a record into the RecordSet object at the specified index position. When you use the addItemAt() method, make sure that:

The value of index specifies a location within the RecordSet.
The record parameter is a record object.
The record parameter has no unknown or missing fields.
RecordSet objects associated with an application server are fully populated.

If these prerequisites are not met, you will encounter the following conditions and results:

The index is less than zero. The RecordSet object is not changed.
The index is greater than the length of the RecordSet object. If the index is greater than the length of the RecordSet object, a trace statement will be sent to the NetConnection Debugger indicating that you can not add items outside the current bounds of the record set and the item will not be added.
The record parameter is not an object. The record is added to the RecordSet object.
The record parameter contains unknown or missing fields. The record is added to the RecordSet object.
The RecordSet object is associated with an application server and not fully populated yet. No change is made to the RecordSet object, and an error message is reported to the Flash Output panel and Debug Console.

Parameters
index: Number - The index number of the record.
item: Object - The item to add to the RecordSet object.

Example
The following example adds an item to the empty myRecordSet RecordSet object:

   import mx.remoting.RecordSet;
   
   var myItem:Object = {name: "John", age:44, phone: "415-999-9999"};
   var myRecordSet:RecordSet = new RecordSet();
   myRecordSet.addItemAt(0,myItem);

The following example adds an item to the end of an existing myRecordSet RecordSet:

   var myItem:Object = {name: "Debbie", age:39, phone: "415-999-9999"};
   myRecordSet.addItemAt(myRecordSet.getLength(),myItem);

clear

clear(
										)
										 : Void

Removes all items from the record set. Do not use the clear() method when the RecordSet object is associated with an application server and is not fully populated yet. The following example illustrates how to handle this condition. If the RecordSet object is server associated and not fully populated yet, no change is made to the RecordSet object and the following error message is reported to the Flash Output panel and Debug Console:

       Operation not allowed on partial RecordSet objects.

Example
The following example removes all items from the myRecordSet RecordSet :

   if( myRecordSet.isFullyPopulated())
     myRecordSet.clear();

contains

contains(
										itmToCheck:
													Object)
										 : Boolean

Determines whether the record set contains the specified record. This method performs a logical (==) comparison on each property of the specified item against all items currently stored in the record set. The comparison is done for like property names only.

Parameters
itmToCheck: Object - An object containing the item that you are seeking in the record set.

Returns
The Boolean value true if the record set contains the record; false if it does not.

Example
The following example adds the myRec object to the existing myRecordSet RecordSet object, if the record does not already exist there.

   var myRec:Object = {name:"Larry", age:34, phone:"415-999-9999"}; 
   if(myRecordSet.contains(myRec) != true)
     myRecordSet.addItem(myRec);

editField

editField(
										index:
													Number, fieldName:
													String, value:
													Object)
										 : Void

Replaces the value in one field of a record with a new value. Make sure that:

The value of index specifies a location within the RecordSet object.
RecordSet objects associated with an application server are fully populated.
The fieldName parameter specifies a valid column name.

Parameters
    index: Number - A number that specifies the index of the item.
    fieldName: String - A string that specifies the name of the field in which to place the new value.
    value: Object - A value to replace the value in the field specified by fieldName.

Example
The following example calculates the value for the price field for each item in the shopping cart record set, cart_rs, to provide a 20% discount. It calls the editField() method to update the price field with the new discounted price:

   var curPrice:Number = 0;
   for( var i:Number = 0; i < cart_rs.length; i++ ) 
   {
     curPrice = cart_rs.items[i].price * 0.8; //20% discount 
     cart_rs.editField(i, "price", curPrice );
   }

filter

filter(
										filterFunction:
													Function, context)
										 : RecordSet

Creates a new RecordSet object by calling the filterFunction() function once for each record in the RecordSet object and collecting, into a new RecordSet object, all records for which the filterFunction() function returns a value of true. The order of the filtered records in the new RecordSet object is the same as their order in the original RecordSet object. The order in which the original RecordSet object is traversed during the filtering process is not defined. If used on a RecordSet object that is not fully populated, only the currently available records are filtered. The new RecordSet object does not inherit the original RecordSet object's list of views, nor any association with a server-side RecordSet object.

Parameters
filterFunction: Function - An ActionScript function that takes one or two parameters and returns a Boolean value of true or false. The first parameter is a single record from the RecordSet object. The second, optional, parameter is a context value that the function uses to determine whether to include the record in the result. The function must return a value of true if the record should be included in the filtered RecordSet object that is returned to the function specified by filterFunction.
context - Optional. A context value supplied by the caller. This value is the second parameter to the filterFunction function.

Returns
A new RecordSet object that contains a reference to, not a copy of, all the records that were selected by the filterFunction() function.

Example
The following example filters the existing myRecordSet RecordSet object for records with an ID value less than or equal to 5. The resulting RecordSet is assigned to the dataProvider property of an existing Grid component:

   // the filter function receives a record object from the record set and a 
   // value to use in filtering.
   
   function contactFilter(aRecord:Object, aContext ):Boolean { 
     return (aRecord.ID <= aContext ); // true for records that have ID <= 5
   }   
   myDataGrid.dataProvider = myRecordSet.filter(contactFilter, 5);

getColumnNames

getColumnNames(
										)
										 : Array

Returns the names of all the columns of a RecordSet object as an array of strings.

Returns
An array of strings. The array is either the same array that you passed to the RecordSet constructor, or the equivalent array for a RecordSet object associated with an application server.

Example
The following example adds an ID column to an existing Grid component if the RecordSet object shoppingCart_rs contains an ID column:

   import mx.remoting.RecordSet;
   
   var colNames:Array = shoppingCart_rs.getColumnNames();
   var idFound:Boolean = false;
   for( var i:Number = 0; i < colNames.length; i++ ) {
     if (colNames[i] == "ID") {
       idFound = true;
       i = colNames.length;
     }
   }
   if( idFound )
     scGrid.addColumnAt( 0, "ID" );

getEditingData

getEditingData(
										index:
													Number, fieldName:
													String)
										 : Object

Retrieves data for editing from a data provider (record set). This allows the model to provide different data formats for editing or displaying the data.

Parameters
index: Number - The index of the item to retrieve. The value of index can range from >=0 to < dp.length (where dp is the data provider or RecordSet).
fieldName: String - Specifies the name of the field being edited.

Returns
An object containing the data, in editable format, for the field at the specified index.

Example
The following example gets the editing data for the price_txt field of an existing RecordSet object named cart_rs when the user clicks the price_txt text field. For this example to work, there must be an existing Grid component containing cart_rs data:

   var focusListener:Object = new Object();
   focusListener.onSetFocus = function(oldFocus_txt, newFocus_txt):Void {
   if (newFocus_txt._name = "price_txt") {
       var index:Number = cart_grd.selectedIndex;
       newFocus_txt.text = cart_rs.getEditingData(index,"price");
      }
   }
   Selection.addListener(focusListener);

getItemAt

getItemAt(
										index:
													Number)
										 : Object

Returns a record if the index is valid and the record is immediately available. If the requested record index number is less than zero or greater than the largest record index number, it returns null. If the index number is valid but the requested record has not yet been downloaded, it returns the string "in progress". Remember that indexes to the records in a set change when the record set is sorted, and when records are deleted or added.

Parameters
index: Number - The index number of the record to retrieve.

Returns
The item at the specified index or null if none exists.

Example
The following example discounts the price field of each item in the existing cart_rs RecordSet object by 30%:

   for( var i:Number = 0; i < cart_rs.length; i++ ) 
     cart_rs.getItemAt(i).price *= 0.7; // reduce the price by 30%

getItemID

getItemID(
										index:
													Number)
										 : Object

Returns the unique ID for the record at the specified index. The RecordSet object assigns each record a unique ID. The ID is not part of the record; it is a separate item that is associated with the record internally within the RecordSet object. Unlike a record index, a record ID does not change when the RecordSet object is sorted or when records are added or deleted. When a record is deleted, its ID is retired and is never used again in this RecordSet object. Also, the ID is used by the ListBox object to maintain the end user's selection when the RecordSet object changes.

Parameters
index: Number - The index number of the item in the record set.

Returns
An object that is the unique identification (ID) corresponding to the record at the specified index. Returns null if the index is out of range.

Example
The following example creates a bookmark for the selected record in the cart_rs record set, which consists of the records from a Grid component. Subsequently, the code searches the cart_rs RecordSet to see if the bookmarked record is still in the RecordSet:

   var bookmark:Object = cart_rs.getItemID(cart_grd.selectedIndex);
   // later in the program:
   var found:Boolean = true; 
   var i:Number = 0;
   while( !found && i < cart.length ) 
     found = bookmark == cart_rs.getItemID(i++);

getIterator

getIterator(
										)
										 : Iterator

Returns a new iterator on this RecordSet object (collection). The iterator returned starts at the first position in the RecordSet. The Iterator is an interface that is defined as follows:

   interface mx.utils.Iterator
   {
     function hasNext():Boolean;
     function next():Object;
   }

Returns
An Iterator interface that is the new iterator for this record set.

Example
The following example computes the total price of the items in an existing cart_rs RecordSet object:

   import mx.utils.Iterator;
   //   var total:Number = 0;
   var it:Iterator = cart_rs.getIterator();
   while( it.hasNext()) 
     total += it.next().price;

getLength

getLength(
										)
										 : Number

Note: This method is superseded by the length property. Returns the number of records currently available, or downloaded locally, in a RecordSet object. The length of the record set on the client side depends on the delivery mode. In the onDemand and page delivery modes, the value of the length property is equal to the length of the local record set. In the fetchAll delivery mode, the length is equal to the length of the remote record set.

Returns
A number that is the total number of items in the local RecordSet object.

Example
The following example displays in the totalRec_txt text field the total number of records in the existing cart_rs RecordSet object:

   totalRec_txt.text = String( cart_rs.getLength());

getLocalLength

getLocalLength(
										)
										 : Number

Returns the number of records currently available (or downloaded locally). The length of the record set on the client side depends on the delivery mode. In the case of onDemand and page mode, the length is equal to the local length of the record set. In fetchAll mode, the length equals the length of the remote record set.

Returns
A number that specifies the length of the local RecordSet object.

Example
The following example displays in the totalRec_txt text field the total number of records in the existing cart_rs RecordSet object:

   totalRec_txt.text = String( cart_rs.getLocalLength());

getNumberAvailable

getNumberAvailable(
										)
										 : Number

Returns the number of records that have been downloaded from the server. The count does not include records that have been requested but have not yet arrived. For local RecordSet objects, this always returns the same value as the getLocalLength() method.

Returns
A number that is the number of records that have been downloaded from the server.

Example
The following example displays in the totalRec_txt text field the total number of records available in an existing RecordSet object named cart_rs:

   totalRec_txt.text = String( cart_rs.getNumberAvailable());

getRemoteLength

getRemoteLength(
										)
										 : Number

Returns the number of records in the RecordSet object on the server side. This length is independent of the delivery mode; the total count of the records is returned. Note: This method is only valid for record sSets that can be paged, which are available only in ColdFusion MX.

Returns
A number that specifies the number of records in the RecordSet object on the server side.

Example
The following example displays in the totalRec_txt text field the total number of records available in an existing server side RecordSet object named cart_rs:

   totalRec_txt.text = String( cart_rs.getRemoteLength());

isEmpty

isEmpty(
										)
										 : Boolean

Determines whether the RecordSet object is empty.

Returns
A Boolean value of true if the RecordSet object is empty; false otherwise.

Example
The following example disables the edit_btn button if the existing RecordSet object shoppingCart_rs is empty:

   edit_btn.enabled = !shoppingCart_rs.isEmpty();

isFullyPopulated

isFullyPopulated(
										)
										 : Boolean

Determines whether a RecordSet object is fully populated, meaning that it has all its records. Local RecordSet objects are always fully populated. RecordSet objects provided by application servers are fully populated after all of their records have been downloaded from the application server. A RecordSet object must be fully populated before you can use any of the following data-editing and data-manipulation methods:

addItem()
addItemAt()
replaceItemAt()
setField()
removeItem()
removeAll()
filter()
sort()

This method is functionally identical to the RecordSet.isLocal() method.

Returns
Returns a Boolean value of true if the RecordSet object is fully populated; false if it is not.

Example
The following example enables the sort_btn button if the books_rs RecordSet object is fully populated.

   sort_btn.enabled = books_rs.isFullyPopulated();

isLocal

isLocal(
										)
										 : Boolean

Determines whether a RecordSet object is local or, if the record set is associated with an application server, whether records remain to be retrieved from the application server. This method is functionally identical to the RecordSet.isFullyPopulated() method.

Returns
A Boolean value of true if the RecordSet object is local and false if records remain to be retrieved from the application server.

Example
The following example enables the sort_btn button if the books_rs RecordSet object is local.

   sort_btn.enabled = books_rs.isLocal();

removeAll

removeAll(
										)
										 : Void

Removes all records from the record set, in a way similar to the RecordSet.clear() method. Do not use the removeAll() method when the RecordSet object is associated with an application server and it is not fully populated yet. If the RecordSet object is server associated and not fully populated yet no change is made to the RecordSet object, and the following error message is reported to the Flash Output panel and Debug Console:

       Operation not allowed on partial RecordSet objects.

Example
The following example removes all records from the record set:

   myRecordSet.removeAll();
   trace(myRecordSet.length); // outputs 0 to trace window

removeEventListener

removeEventListener(
										event:
													String, listener)
										 : Void

Removes the specified event listener.

Parameters
event: String - A string that specifies the name of the event.
listener - A reference to a listener object or function.

Example
The following example removes an event listener from the shoppingCart_rs RecordSet object:

   shoppingCart_rs.removeEventListener("modelChanged", myListener);

removeItemAt

removeItemAt(
										index:
													Number)
										 : Object

Removes the specified record. The associated record ID is never used again in the RecordSet object. When you use the removeItemAt() method, make sure that the following conditions are met:

The index specifies a location that is within the record set.
RecordSet objects associated with an application server are fully populated.

If these prerequisites are not met, you will receive the following error conditions and results:

The RecordSet object is server associated but not fully populated. No change is made to the RecordSet object, and an error message is reported to the Flash Output panel and Debug Console: Operation not allowed on partial RecordSet objects.
Index out of range. The RecordSet object is not changed.

Parameters
index: Number - The index number of the record.

Example
The following function receives an index for the record to remove, then removes the selected item from the shoppingCart_rs RecordSet object:

   function deleteConfirmed( indexToRemove:Number ):Void {
     shoppingCart_rs.removeItemAt( indexToRemove );
   }

replaceItemAt

replaceItemAt(
										index:
													Number, item:
													Object)
										 : Void

Replaces a record in the RecordSet object at the specified index. The specified index must identify an existing record. The record's contents are replaced with the contents of the item parameter. The record's ID does not change. When you use the replaceItemAt() method, make sure that the following conditions are met:

The index parameter specifies a location that is within the record set.
The item parameter is an object.
The item parameter has no unknown or missing fields.
The RecordSet objects associated with an application server are fully populated.

If these prerequisites are not met, you will receive the following error conditions and results:

The RecordSet object is server associated but not fully populated. No change is made to the RecordSet object, and an error message is reported to the Flash Output panel and Debug Console: Operation not allowed on partial RecordSet objects.
Index out of range. The RecordSet object is not changed.
Unknown field name. The RecordSet object is not changed.

Parameters
index: Number - A number that specifies the index number of the record.
item: Object - The record to add.

Example
The following example replaces the tenth record of the existing contacts_rs RecordSet with a new record:

   var myItem:Object = {name:"Kerry", age:45, phone:"415-999-9999"};
   contacts_rs.replaceItemAt(9, myItem);

setDeliveryMode

setDeliveryMode(
										mode:
													String, pagesize:
													Number, numPrefetchPages:
													Number)
										 : Void

Changes the delivery mode of a record set associated with an application server. At any time, a RecordSet object associated with an application server is operating in a particular data-delivery mode. The new mode setting takes effect immediately, except that pending application server requests are allowed to complete. You can change mode settings and delivery mode parameters. Until you call this method for a RecordSet object, it operates in onDemand mode. When using fetchAll mode, you can supply a pagesize parameter. The entire record set is "fetched" (retrieved) from the application server in a series of requests, and each request fetches only the number of records specified in the pagesize parameter. When using page mode, you can supply the pagesize and numPrefetchPages parameters. In page mode, when you request a record using the getItemAt() method, the RecordSet object ensures that those pages to be prefetched after the page containing the requested record are either already available in the client or requested from the server. If the value of numPrefetchPages is zero, only the current page containing the requested record is fetched. When the RecordSet object is fully populated, the setDeliveryMode method has no effect. If the mode string has an unknown value, no change is made to the RecordSet object, and the following error message is reported to the Flash Output panel and Debug Console:

   SETDELIVERYMODE: unknown mode string

Parameters
    mode: String - A string that identifies the delivery mode. The options are onDemand (default), fetchAll, and page.
    pagesize: Number - An optional parameter that, in page mode, is a number that specifies what the page size is. In fetchall mode, the parameter is a number that specifies how many records to fetch in each server request. The default is 25.
    numPrefetchPages: Number - An optional parameter that, in page mode, is a number that specifies the number of pages to prefetch. The default is 0, which fetches only the requested page.

Example
The following example sets the RecordSet contacts_rs delivery mode to page, with a page size corresponding to the number of rows in myGrid_grd. The number of prefetch pages is set to 10:

   contacts_rs.setDeliveryMode("page", myGrid_grd.getRowCount(), 10);

setField

setField(
										index:
													Number, fieldName:
													String, value:
													Object)
										 : Void

Note: This method is superceeded by the RecordSet.editField() method. Replaces one field of a record with a new value. When you use the setField() method, make sure that the following conditions are met:

The index parameter specifies a location that is within the record set.
RecordSet objects associated with an application server are fully populated.
The fieldName parameter specifies a valid column name.

If these prerequisites are not met, you will receive the following error conditions and results:

The RecordSet object is server associated but not fully populated.

No change is made to the RecordSet object, and the following error message is reported to the Flash Output panel and Debug Console:

       Operation not allowed on partial RecordSet objects.
        Index out of range

The RecordSet object is not changed.

Unknown field name

The RecordSet object is not changed.

Parameters
    index: Number - The index number of the record.
    fieldName: String - The field name to replace.
    value: Object - A value to replace the value in the field specified by fieldName.

Example
The following example edits the price field for each item in the existing cart_rs RecordSet object to provide a 20% discount:

   var curPrice:Number = 0;
   for( var i:Number = 0; i < cart_rs.length; i++ ) {
     curPrice.price = cart_rs.items[i].price * 0.8; //20% discount 
     cart_rs.setField(i, "price", curPrice );
   }

sort

sort(
										compareFunc:
													Function)
										 : Void

Sorts all the records using a user-specified comparison function. The sort() method sorts all the records in place, without making a new copy. The order is determined by the user-supplied compareFunc() function. The original order is not remembered. When you use the sort() method, avoid sorting a RecordSet object that is associated with an application server and not fully populated yet. If the RecordSet object is not fully populated no change is made to the RecordSet object, and the following error message is reported to the Flash Output panel and Debug Console.

   Operation not allowed on partial RecordSet objects.

Parameters
compareFunc: Function - An ActionScript comparison function that determines the sorting order. Given the arguments A and B, the comparison function returns a value as follows:

-1 if A appears before B in the sorted sequence
0 if A = B
1 if A appears after B in the sorted sequence

Example
The following example sorts the RecordSet object contacts_rs by calling the function sortContacts(), two records at a time, to sort by the lastname field:

   function sortContacts(a:Object,b:Object):Number {
   if ( a.lastname < b.lastname)
     return( -1 );
   else if ( a.lastname == b.lastname)
     return( 0 );
   else return( 1 ); 
   }
   contacts_rs.sort(sortContacts);

sortItems

sortItems(
										compareFunc:
													Function, optionFlags:
													Number)
										 : Void

Parameters
compareFunc: Function - An ActionScript comparison function that determines the sorting order. Given the arguments A and B, the comparison function returns a value as follows: -1 if A appears before B in the sorted sequence 0 if A = B 1 if A appears after B in the sorted sequence
optionFlags: Number - One or more numbers or strings, separated by the bitwise OR operator
( | ), that change the behavior of the sort from the default. The following values are valid: Array.CASEINSENSITIVE Array.DESCENDING Array.UNIQUESORT Array.RETURNINDEXEDARRAY Array.NUMERIC

Example
The following example sorts the contacts_rs RecordSet object by calling the function sortContacts(), two records at a time, to numerically sort by the age field:

   function sortContacts(a:Object,b:Object):Number {
   if ( a.age < b.age)
     return( -1 );
   else if ( a.age == b.age)
     return( 0 );
   else return( 1 ); 
   }
   contacts_rs.sortItems(sortContacts, Array.NUMERIC);

sortItemsBy

sortItemsBy(
										fieldNames:
													Array, order:
													String, optionFlags:
													Number)
										 : Void

Sorts all records in the RecordSet object without making a new copy. The sort key value for each record is the contents of the field identified by the field ID. The original order is not saved. Sorting large RecordSet objects can take a long time. RecordSet objects that contain fewer than 2000 records should take less than one second on a computer with a Pentium 3 processor. Sort times increase rapidly as the number of records grows. When two or more records have the same sort key value, they are not sorted in a special way. The original order of the records might not be preserved. If the fieldNames parameter identifies a field that does not exist in one or more records, then null is used as the key value for those records. The value null appears lower in the sort order than any other value. The sortItemsBy() method may be used only with fully populated RecordSet objects. If the RecordSet object is server associated but not fully populated no change is made to the RecordSet object, and an error message is reported to the Flash Output panel and Debug Console:

   Operation not allowed on partial RecordSet objects.

Parameters
    fieldNames: Array - A string or an array of strings that represents the field or fields on which sorting needs to be done. The first field name represents the primary sort field, the second represents the next sort field, and so on.
    order: String - A String specifying whether to sort the items in ascending order ("ASC") or descending order ("DESC").
    optionFlags: Number - One or more numbers or strings, separated by the bitwise OR operator ( | ), that change the behavior of the sort from the default. The following values are valid: Array.CASEINSENSITIVE Array.DESCENDING Array.UNIQUESORT Array.RETURNINDEXEDARRAY Array.NUMERIC.

Returns
A Boolean value of true if the sort succeeds; false if any errors occurred.

Example
The following example sorts the existing contacts_rs RecordSet object by the lastname and firstname fields. The case is ignored and the sort is performed in descending order:

   var sortOptions:Number = Array.CASEINSENSITIVE | Array.DESCENDING;
   contacts_rs.sortItemsBy(["lastname","firstname"], null, sortOptions);

Property Detail

columnNames

columnNames:
												Array  [
												Read-Only]

Returns the names of all the columns of a RecordSet object as an array of strings. The array is either the same array that you passed into the RecordSet constructor, or the equivalent array for an application server-associated RecordSet object.

items

items:
												Array  [
												Read-Only]

Returns an array of all records of the RecordSet.

length

length:
												Number  [
												Read-Only]

Returns the number of records currently available, or downloaded locally, in a RecordSet object. The length of the record set on the client side depends on the delivery mode. In the onDemand and page delivery modes, the value of the length property is equal to the length of the local record set. In the fetchAll delivery mode, the length is equal to the length of the remote record set.

version

static
												 version:
												String

Component version. For internal use only.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flashremoting/mx2004/actionscript_api_reference/mx/remoting/RecordSet.html

mx.remoting Class RecordSet

RecordSet

addEventListener

addItem

addItemAt

clear

contains

editField

filter

getColumnNames

getEditingData

getItemAt

getItemID

getIterator

getLength

getLocalLength

getNumberAvailable

getRemoteLength

isEmpty

isFullyPopulated

isLocal

removeAll

removeEventListener

removeItemAt

replaceItemAt

setDeliveryMode

setField

sort

sortItems

sortItemsBy

columnNames

items

length

version

mx.remoting
Class RecordSet