StartMerge – PB Docs 2022

Description

Indicates the merge mode starts. The database operations after the
StartMerge label will not be executed until the EndMerge label is called. Using the merge
mode, multiple database requests are consolidated into one request, so as
to reduce the number of server calls. Make sure to read the Usage section
below in order to use these label functions properly.

This function takes effect only when the application is deployed via
the PowerServer project (it will be ignored when the application is
deployed via the PowerClient project or the Application project).

Applies to

PowerServerLabel object

Syntax

Return value

Integer.

Returns 1 if it succeeds and -1 if an error occurs.

Usage

The StartMerge label must be used together with the EndMerge label, which means, StartMerge and
EndMerge must be used in pairs. The StartMerge/EndMerge pair (called merge
labels) should not contain any other merge labels.

The merge labels enable requests to be completed in a much shorter
period of time (compared to the unmerged mode).

The merge labels should only be used to merge the following
operations:

For merge labels to work with the SQL Server database, make sure the
“Multiple Active Result Sets” setting (in the Advanced dialog) is set to
True (the default is False).

The merge labels cannot work with the Crosstab DataWindow.

The merge labels cannot work with the DataWindow containing nested
reports.

The merge labels cannot work with the DataWindow that modifies the
SQL statement in the RetrieveStart or UpdateStart event. For example, the
following statement cannot be included in the merge label.

The merge labels should only be used to merge independent requests.
Independent requests means the execution of one request does not rely on
the execution result of another request in the same merged request, or one
request does not use the return value of another request in the same
merged request.

For example,

Incorrect usage (of using the execution result of another
request):

Correct usage:

Incorrect usage (of using the return value of another
request):

The original code:

Incorrect usage:

Correct usage:

The merge labels cannot work with the Retrieve statements in the
same DataWindow or DataStore. For example,

The merge labels cannot work with the Fetch Cursor statement, but
you can place the Open Cursor statement in the merge label. For
example,

The merge labels should not include the GOTO statement, because GOTO
statement may cause the EndMerge label not executed. Besides that GOTO
statement does not support “try catch” for catching the exception.

The merge labels should not include the Connect, Disconnect, Commit,
and Rollback statements. For example,

Incorrect usage:

Correct usage:

If the merge labels include the Destroy statement, make sure the
other requests within the merge labels do not work with the destroyed
object, otherwise, EndMerge label may throw the null object error.

The requests in the DataWindow event cannot be merged if the event
is already placed within the merge labels. For example,

The Retrieve statements in the RowFocusChanged event cannot be
merged.

You should move the event out of the merge labels, and then place
the labels into the event to merge the requests in the event.

The merge labels cannot work with DDDW.Reteive triggered by
InsertRow and ShareData. You can modify the scripts: 1) Disable
auto-retrieve for the DDDW column; 2) Get data from the DDDW column to
DataWindowChild via GetChild and set the transaction object; 3) Place the
DataWindowChild retrieve statements to the merge labels. For
example:

If the DataWindow or embedded SQLs does not support the merge
labels, the following error will occur.

PowerServerLabel Results[] property may return the null object error
when executed in the traditional C/S application. For example,

You can work around this error by rewriting the code as
below:

Examples

In this example, four requests are merged and sent in one
call.

Here is another example:

See also

EndMerge