$.udb(ds).rowCreate()

note

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

$.udb(ds).rowCreate()

Creates a new record in the data source.

Returns a UdbPromise object with the UdbDsc object as parameter.

Syntax

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

*options*     ::=  {
     [hostvars]:      *hostvars*,
     [initialValues]: *initial-values*,
     [rows]:          Array[*row*],
     [before]:        *before*,
     [copyValues]:    *copy-values*
}

*hostvars*        ::=  { *name* : *value*, ... }
*row*             ::=  { *column* : *value*, ... }
*initial-values*  ::=  { *column* : *value*, ... }

*before*       ::=  { [true] | false }
*copy-values*  ::=  { true | [false] }

The optional ds is a data source selector.

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

Hostvars is a set of (temporary) name-value pairs that are passed as column values to the record being created. By default, hostvars is the empty set.

Initial-values is a set of (temporary) name-value pairs that override the default initial values of the newly created record. By default, initial-values is the empty set.

Rows is an array of predefined rows to be created. These rows follow the same format of initial-values being sets of name-value pairs. The contents of initial-values can override those of rows.

Before is a boolean that specifies whether the new record must be created before or after the currently selected record. By default, it is created before, and thus has the value true.

Copy-values is a boolean that specifies whether all field values must be duplicated from the record currently selected, or not. By default it is false, this duplication does not happen.

Example 1

$.udb('EMP').rowCreate({
  initialValues: { NAME: 'John' }
});

This example creates a new record with the NAME field already set to 'John'. To perform additional actions once the record has been created, use the .then() clause of the returned UdbPromise instead:

$.udb('EMP').rowCreate().then((dsc) => {
    dsc.rows('current').cols('NAME').val('John');
});

Example 2

This example creates an array of predefined rows:

$.udb('EMP').rowCreate({
  rows: [
    {
      FIRST_NAME: 'John',
      NAME: 'Smith'
    },
    {
      FIRST_NAME: 'Jane',
      NAME: 'Doe'
    }
],
  initialValues: { DEPT: 'Engineering' }
});

Related events

Event	Applies to	Occurs when
rowprecreate	Data source objects	Before a record is created.
rowpostcreate	Data source objects	After a record is created.