$.udb(ds).gotoDataSet()

note

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

$.udb(ds).gotoDataSet()

Moves the processing flow to a specific data set in the data source.

Each data set consist of n records, where n is determined by the dataSetSize() function of the DataSourceContainer object. 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.

When you call this function, it is executed for all data sources in the container object. To move between data sets on a single data source's Rowset, use rowSet.gotoDataSet() instead.

Returns a UdbPromise object with the UdbDsc object as parameter.

Syntax

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

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

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

*options*   ::=  {
     [pKeys]:    *rowSet*,
     [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 optional rowSet parameter is a rowset identifier. If the .rowSet() clause is omitted, then .rowSet('current') is assumed, unless the option pKeys specifies another one.

pKeys is an alternative way of specifying the rowset to operate on, equivalent to the .rowSet() clause; it identifies the rowset by its parent key in the same way as the .rowSet() clause's rowSet parameter.

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 data source get automatically corrected. For example, a data set index < 1 is corrected to the first data source (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, will make the data source 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 data source / rowset 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 data source 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

$.udb('EMP').gotoDataSet('next');

$.udb('EMP').gotoDataSet('previous');

$.udb('EMP').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.