UDB DataSourceContainer object

note

This article is about the DataSourceContainer or UdbDsc object in the UDB object model. This model is for data exchange between USoft web UIs and Rules Engines. This model is built around the udb, DataSourceContainer, Rowset, Rows, and Cols object types. See also UDB events.

A DataSourceContainer object contains one or more specified data sources.

Returns a UdbDsc object.

Syntax

$.udb( [ds] )

*ds*  ::= { *data-source* | *data-source-array* )

*data-source-array*  ::= Array[*data-source*]

*data-source*  ::=  {
    [[*frame-id*] '::' ] [*page-id* '.'] { 
        *data-source-name*
      | *data-source-id*
      | *data-source-path*
      | *meta-selector* 
    }
}

*meta-selector* ::=  {
      ':table' 
    | ':variable'
    | ':virtual'
    | ':sql'

    | ':busy'
    | ':queried'
    | ':deferred'
}

The optional ds is a data source selector. If you do not specify ds, all the data sources in scope are returned.

Data source selectors

The data source selector is an expression whereby you identify a single data source, or multiple data sources at once. Data source selectors are used to create a collection of data sources, to populate a UdbDsc object. This object can then be used to access various functions for the selected data sources, or to perform certain operations (queries, etc.) on them.

You can identify a single data source by a simple data-source name string. You can identify a set of multiple data sources by an array of simple string values.

$.udb('EMP');

$.udb(['EMP', 'DEPT']);

If the data source is on the current page, you can identify it simply either by its data-source-name or by its data-source-alias. If it is on a different page in your page stack, you can identify it by prefixing page-id followed by a period.

note

Referencing data sources by yourself by using the alias or even with page id included is highly uncommon. Aliases may change quickly if the page of the data source is republished, and page id's are totally defined at run-time, so not reliable in a custom script. Please use data source names or paths (see below) only, when using data source collections in your scripts.

It is also possible to refer to a data source in a specific frame control. Prefix with frame-id followed by a double colon, or to identify the top-level frame, write the double colon but not the frame-id prefix. This is useful when having the same data source in multiple frame control contexts simultaneously.

You can also identify a data source using data source path syntax.

Finally, you can select types of data source by using meta-selector values. This selection technique cannot be combined with the other options.

• ':table' meta-selector selects all table data sources in scope.
• ':variable' meta-selector selects all variable data sources in scope.
• The ':virtual' meta-selector selects all virtual data sources in scope.
• The ':sql' meta-selector selects all SQL data sources in scope.

There are also a few that can be used that depend on the state of the data source:

• ':queried' meta-selector selects all data sources that have been queried.
• ':busy' meta-selector selects all data sources that are currently being queried at the server, but may not have finished processing results yet.
• ':deferred' meta-selector selects all data sources that have a deferred query initial state, and are waiting to be queried automatically.

The difference between UdbDsc and UdbDataSource objects

A UdbDsc object, which is returned by $.udb(ds) is essentially an array instance of UdbDataSource objects. While you can call any and all functions of the UdbDsc class also directly on its UdbDataSource child objects in the array, some might give different results. Also, some functions in UdbDataSource may not exist in UdbDsc at all.

For backwards compatibility clarity, it is recommendable to prefer usage of the UdbDsc functions over UdbDataSource. If unclear you are dealing with an UdbDsc object, you can directly convert the one into the other quite easy just by wrapping it in another $.udb(ds) instead.

Also, you will never get an actual direct instance of the UdbDataSource class, but always one of its sub-classes:

Subclass	Web Designer class
UdbTableDataSource	Every table data source defined in the web designer. Can be a lookup, relate or info data source instance.
UdbVariableDataSource	Every variable data source defined in the web designer.
UdbSqlDataSource	Every SQL data source defined in the web designer. These have their query defined in their unique 'SQL' property.
UdbVirtualDataSource	Every data source of the above three types that has its 'Synchronization Data Source' property filled in. These have a 'real type' that refers directly to the type of the data source with which they are synchronized.

Examples

let dsc = $.udb();

Example result:
[UdbTableDataSource, UdbVirtualDataSource, UdbTableDataSource]

let dsc = $.udb('EMP');

Example result:
[UdbTableDataSource]

let dsc = $.udb(['EMP','DEPT']);

Example result:
[UdbTableDataSource, UdbTableDataSource]