$.udb.commit()

note

This article is about the commit() function of the $.udb object.

$.udb.commit()

Commits data manipulations (INSERT, UPDATE, DELETE).

Returns a UdbPromise object.

Syntax

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

*options*   ::=  {
    [quiet]:       *quiet*,
    [waitState]:   *wait-state*,
    [waitPending]: *wait-pending*,
    [timeout]:     *timeout*
}

*quiet*         ::=  { true   | [false] }
*wait-state*    ::=  { true   | [false] }

*wait-pending*  ::=  { [true] | false }
*timeout*       ::=  Integer [20]

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

Quiet is a boolean determining whether a message is displayed if an error occurs. The default is false, meaning that an error is displayed by default.

Wait-state automatically adds a loading icon to the application window while this function is being executed. This is especially useful if the server takes unusually long to complete it. Its default value is false.

For the optional waitPending and timeout options, see the "Fast dependent commits" section below.

Example

$.udb.commit({ quiet: true })
.then(() => {
    alert('Commit successfully completed.');
})
.catch(() => {
    alert('Commit failed.');
})
.finally(() => {
    // post-commit actions
})

Fast dependent commits: waitPending, timeout options

tip

This section applies only to dependent commits. They are commits that attempt to manipulate the same data, and are called while another commit on it is still being executed.

note

If two commits are executed via UdbPromise chains, then these are not dependent if the second commit is returned in a .then() clause of the first commit:

$.udb.commit({ quiet: true })
.then(() => {
    // several manipulations done here

    //...

    //not a dependent commit!
    return $.udb.commit( { quiet: true });
});

In this case, the second commit (and its preceding manipulations) will be executed after the first commit is fully executed and processed.

It is possible that a web page performs commits very closely after one another, as when you have checkboxes in a form and you have scripted that commits must happen as soon as the user changes the checkbox value.

If a web page performs two or more dependent commits with minimal time in between, it can happen that the second commit fails and raises a warning message that the first commit is busy or that the second commit is changing records that ar newly inserted in the first commit.

You can set wait-pending to true to cause the second commit to wait until the first has finished, instead of raising this message. You can set the timeout option to determine the maximum time (in seconds; default is 20)that the second commit is allowed to wait.

If you set wait-pending to false (its default value), the second commit will not wait: in this situation, it will always fail if it depends on another earlier commit that has not finished.

tip

If the timeout expires before the first commit is finished, then the second commit is executed regardless, which may still cause it to fail. If this happens, you could raise the value of the timeout parameter.

Example

// NB: long commit, takes several seconds to complete
$.udb.commit({ quiet : true });

/// ...

// several updates made, another commit; wait max 20
// seconds for first commit to finish first;
// In this case we do not want to put everything in
// the .then() clause of the first commit

$.udb.commit({ quiet: true, waitPending: true });

Related events

Event	Applies to	Occurs when
beforecommit	Page objects	Before each commit action
postcommit	Page objects	After each commit action