Rowset.gotoDataSet()

note

This article is about the gotoDataSet() function of the Rowset object.

Rowset.gotoDataSet()

Moves the processing flow to a specific data set among this row set's data sets.

Each data set consists of n records, where n is determined by the dataSetSize() function. The number of available data sets is the total number of records divided by n.

A new data set is queried only if the data is not already available on the client, or not anymore, possibly because the lifeTime() function has caused it to expire.

Returns a UdbPromise object with the UdbRowSets object as parameter.

Syntax

$.udb( *ds* ).rowSet( *rowSet* ).gotoDataSet( *index*, [options] )
.then( ( *row-set* ) => {
     // success
})
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

*index*       ::=  { 'first' | 'last' | 'next' | 'previous' | *index-number* }
*index-number ::=  Integer

*options*   ::=  {
     [noSelect]: *no-select*,
     [selKeys]:  *selection-keys*,
     [noCount]:  *no-count*
}

*no-select*      ::= { true | [false] }
*selection-keys* ::= { *index*: Integer, *keys*: { name : value, ...} }
*no-count*       ::= { true | [false] }

The required ds parameter is a data source selector.

The required rowSet parameter is a rowset identifier. The action is automatically scoped to this row set's own keys string.

The required index is a string or an integer that identifies the data set that must become the active data set, using values as follows:

Value	Meaning
'first'	Move to the first data set.
'last'	Move to the last data set.
'next'	Move to the next data set relative to the current.
'previous'	Move to the previous data set relative to the current.
index	Move to the data set that has the integer value index as its index. Important! The index is 1-based. The first item has index 1, not 0.

note

Data set indices that are out of the bounds for the row set get automatically corrected. For example, a data set index < 1 is corrected to the first data set (i.e. index becomes 1), and a data set index higher than the last available data set is automatically corrected to that last index.

Likewise, if 'next' is attempted while at the last data set index, the row set will remain at the last data set.

The optional options is a struct that can have the following items, all of which are optional.

Selection-keys is an object containing the record index and primary keys of the selected record prior to data set navigation, in case the data set is already queried and a specific record needs to be selected. This could also happen when navigating a parent data source and the controls displaying its child data sources need to be updated. By default, this information is not present, and the object has the default value null. This object is also used to make sure that a newly created record that is placed in a new (next) data set is also automatically selected.

No-count is used when the total number of records for the row set is already known and does not need to be redetermined. The default is false, which means that if the total number of records is not sure to be known (if the row set is queried for the first time, or if the last data set is queried), then the total number of records is queried.

No-select is used when a record must not be selected automatically when the data set is queried. This is often the case when an INSERT or DELETE manipulation triggered the query; the operations performing these manipulations handle the record selection on their own. By default, the value is false, which makes sure that a record is always automatically selected; either the first record of the set, or the one referred to by selection-keys.

Examples

let rowSet = $.udb('EMP').rowSet('current');

rowSet.gotoDataSet('next');

rowSet.gotoDataSet(3);

Related events

Event	Applies to	Occurs when
beforegotodataset	Data source objects	Before navigation to a different data set takes place
showdata	Data source objects	New data is available for display.