$.udb(ds).executeQuery()

note

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

$.udb(ds).executeQuery()

Executes a query. Existing queried data (if any) is cleared before the query is executed. The data that is retrieved by the query is always the first data set of the data source, which has its boundaries defined by the dataSetSize() function of the DataSourceContainer object.

Returns a UdbPromise object with the UdbDsc object as parameter.

Syntax

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

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

*options*  ::=  {
     [hostvars]: *hostvars*,
     [nocheck]:  *no-check*,
     [orderBy]:  *order-by*,
     [before]:   *before-function*,
     [pKeys]:    *parent-keys*,
     [clear]:    *clear*
}

*hostvars*        ::=  { *name* : *value*, ... }

*no-check*        ::=  { true   | [false] }

*order-by*        ::=  Array[*order-col*]
*order-col*       ::=  { *column-name* | *column-sort-order* }
*col-sort-order*  ::=  { *column-name* : *sort-order* }
*sort-order*      ::=  { ['ASC'] | 'DESC' }

*pKeys*           ::= *rowSet*

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.

Options is a struct that can contain the following items, all of which are optional.

The optional hostvars is a set of (temporary) name-value pairs that are passed to the query as variables. By default, hostvars is the empty set {}.

No-check is a boolean that specifies whether unhandled manipulations are checked first before the query is executed. This happens only if nocheck is set to false. By default, no-check is false.

Order-by is an array of instructions that determine how the queried data is sorted. Each element in this array is either a column name or a struct combining a column name with an 'ASC' or 'DESC' instruction, as in the Example below. Column names not accompanied by 'DESC' are automatically result in sorting in ascending order ('ASC' is the default). If you specify order-by, any existing default sort order settings defined in Web Designer are overwritten.

Before-function is a function that is executed before the query is performed.

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.

Example

$.udb('EMP').executeQuery({
   hostvars: { 'ID' : '5' },
   orderBy: ['NAME', {DEPT: 'DESC'}]
}).then((dsc) => {
  ...
});

Related events

Event	Applies to	Occurs when
beforeexecutequery	Data source objects	Before the data source is queried
showdata	Data source objects	New data is available for display.