Appeon Labels

Overview

Appeon Labels provided in the Appeon Workarounds PBL can reduce the interactions between the client and PowerServer, thus boosting the performance of Appeon applications.

The Appeon Labels associated functions are contained in the appeon_nvo_db_update object in appeon_workarounds.pbl.

Appeon Labels and associated functions

Label Name

Label Associated Function

Description

Appeon Commit/Rollback Label

of_autocommitrollback

Automatically commits or rolls back the first database operation statement after the label.

Appeon Commit Label

of_autocommit

Automatically commits the first database operation.

Appeon Rollback Label

of_autorollback

Automatically rolls back the first database operation statement if the operation fails.

Appeon Queue Labels

of_startqueue

of_commitqueue

The Appeon Queue Labels are designed for use when it is necessary to execute numerous database operation statements on PowerServer, and the returned values of the statements are not validated or used. Using the pair of labels can dramatically reduce the number of client-server interactions.

Appeon Immediate Call Label

of_imdcall

Immediately commits a database operation.

Appeon Update Label

of_update

Reduces the number of interactions with the server caused by "interrelated updates".

Usage

For detailed instructions on how to take advantages of Appeon Labels to improve performance of the application, please refer to the the section called “Technique #4: grouping multiple server calls with Appeon Labels” in PowerServer Performance Tuning Guide.

Appeon Commit/Rollback Label

Description

The Appeon Commit/Rollback Label is used to automatically commit or rollback the first database operation statement after the label.

Controls

appeon_nvo_db_update object

Associated functions

of_autocommitrollback

Syntax

objectname.of_autocommitrollback( )

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

Return value

None.

Usage

With the Appeon Commit/Rollback Label, the database operation statement will be sent to the PowerServer. The server will automatically commit (or roll back) the statement according to the execution result. If the execution succeeds, the result will be committed; if the execution fails, the result will be rolled back.

The first Commit or Rollback statement after the Appeon Commit/Rollback Label will not be submitted to the PowerServer. Therefore, there must be no more than one database operation statement between the label and the first Commit or Rollback statement. For example, the IF statement should not contain database operation statements, since the executed result will not be committed to the database.

gnv_appeonDbLabel.of_autocommitrollback() 
UPDATE tab_a ...... 
IF SQLCA.SQLCODE = 0 THEN 
   ...... // non-database related bussiness logic 
   COMMIT; 
ELSE 
   ...... // non-database related bussiness logic 
   ROLLBACK; 
   ...... 
END IF

There must be database related operations after the label.

There must be no labels between the Appeon Rollback Label and the first Commit or Rollback statement.

Appeon Commit Label

Description

The Appeon Commit Label is used to automatically commit the first database operation.

Controls

appeon_nvo_db_update object

Associated functions

of_autocommit

Syntax

objectname.of_autocommit( )

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

Return value

none.

Usage

After the label there must be database operations.

With Appeon Commit Label, PowerServer does not validate the execution result of the database operation statement. Instead, the server automatically commits the statement regardless of the execution result.

The first Commit statement after the Appeon Commit Label will not be submitted to the PowerServer , however, the first Rollback statement will be submitted to the server. Therefore, there should be no more than one database operation between the label and the first Commit statement. For example, the IF statement should not contain database related business logic, since the executed result will not be committed to the database.

gnv_appeonDbLabel.of_autocommit() 
SELECT.....INTO ......FROM tab_a; 
IF SQLCA.SQLCODE = 0 THEN 
  ...... // non-database related business logic 
ELSE
  ...... // non-database related business logic 
END IF 
COMMIT;

There must be no labels between the Appeon Commit Label and the first Commit statement.

Appeon Rollback Label

Description

The Appeon Rollback Label is used to automatically roll back the first database operation statement if the operation fails.

Controls

appeon_nvo_db_update object

Associated functions

of_autorollback

Syntax

objectname.of_autorollback( )

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

Return value

None.

Usage

After the label there must be database operations.

With the Appeon Rollback Label, PowerServer only commits an unsuccessful database operation.

The first Rollback statement after the Appeon Rollback Label will not be submitted to the PowerServer if the execution fails. Therefore, there should be no more than one database operation between the label and the first Commit or Rollback statement.

There must be no labels between the Appeon Rollback Label and the first Rollback statement.

Code Example

gnv_appeonDbLabel.of_autorollback() 
IF dw_1.update() <> 1 THEN
  ROLLBACK ; 
  ...... // non-database related business logic 
END IF

Appeon Queue Labels

Description

Appeon Queue Labels consist of the Appeon Start Queue Label and the Appeon Commit Queue Label. The Appeon Queue Labels are designed for use when it is necessary to execute numerous database operation statements on PowerServer, and the returned values of the statements are not validated or used. Using the pair of labels can dramatically reduce the number of client-server interactions.

Controls

appeon_nvo_db_update object

Associated functions

of_startqueue, of_commitqueue

Syntax

objectname.of_startqueue ( )

objectname.of_startqueue( {integer stopmode} )

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

stopmode

0 - continue executing the remaining SQL scripts when an error occurs;

1 - stop executing the remaining SQL scripts when an error occurs.

Note: The of_startqueue function without this argument is preserved for compatibility.

objectname.of_commitqueue()

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

Return value

none.

Usage

Appeon Queue Labels must be used in the same field.

All the database operations in the labels will be submitted to the PowerServer.

If there are multiple Appeon Commit Queue Labels used together with an Appeon Start Queue Label, only the first Appeon Commit Queue Label that is executed will be effective. Other Appeon Commit Queue Labels will be ignored.

With the stopmode argument, users can choose to continue running or return immediately when an error occurs in the database syntax operation in the queue.

In the Appeon Queue Labels, the SELECT statement cannot be used in the condition statements. The following example is incorrect.

Incorrect Example

nv_appeonDbLabel.Of_startqueue() 
IF.....THEN 
  SELECT STATEMENT 1 
else
  SELECT STATEMENT 2 
END IF 
gnv_appeonDbLabel.Of_commitqueue()

In the Appeon Queue Labels, script that stops the execution of another script cannot be included in some events of the DataWindow object, For example, in the following events of DataWindow, the Return statement should not be used: the RetrieveStart event, the RetrieveEnded event, the RowFocusChanged event, the UpdateStart event, the UpdateEnd event, and etc.

For every RETURN statement, there must be an database operation statement or unexpected errors occur.

You can open a cursor in the Appeon Queue Labels.

Using multiple Appeon Queue Labels

Appeon Queue Labels can be embedded in other Appeon Queue Labels. However, only the outer Appeon Queue Labels take effect.

Using non-queue labels together with Appeon Queue Labels

When there are multiple non-queue labels embedded in the Appeon Queue Labels, only the first non-queue label takes effect.

When the other Appeon Labels is embedded in Appeon Queue Labels, the format should be the same as the following code example. Please note that only Commit or Rollback statements are involved in the condition statements.

Code Example

nv_appeonDbLabel.of_startqueue() 
dw_1.update()
gnv_appeonDbLabel.of_autocommitrollback() // the label takes effect
gnv_appeonDbLabel.of_imdcall() // The label takes no effect 
IF dw_2.update() = 1 THEN 
  COMMIT; 
ELSE 
  ROLLBACK; 
END if

nv_appeonDbLabel.of_startqueue(1) // Stop immediately when an error occurs 
dw_1.update() 
gnv_appeonDbLabel.of_autocommitrollback() // the label takes effect 
gnv_appeonDbLabel.of_imdcall() // The label takes no effect 
if dw_2.update() = 1 THEN 
  COMMIT; 
ELSE 
  ROLLBACK; 
END if 

nv_appeonDbLabel.of_autocommitrollback() 
UPDATE tab_a...... 
if SQLCA.SQLCODE = 0 THEN 
  COMMIT; 
ELSE 
  ROLLBACK; 
END IF 
INSERT tab_b......
  COMMIT; 
gnv_appeonDbLabel.of_commitqueue()

Appeon Immediate Call Label

Description

The Appeon Immediate Call Label is used to immediately commit a database operation.

Controls

appeon_nvo_db_update object

Associated functions

of_imdcall

Syntax

objectname.of_imdcall( )

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

Return value

none.

Usage

Appeon Immediate Call Label cannot be used alone, it must be used in Appeon Queue Labels.

With the Appeon Immediate Call Label, the first database operation statement will be sent to the server and executed immediately.

Code Example

gnv_appeonDbLabel.of_startretrievequeue() 
dw_1.retrieve()
gnv_appeonDbLabel.of_imdcall() 
SELECT ......INTO :var_1,:var_2... 
IF var_1 > 0 THEN 
  para = "ok" 
ELSE 
  para = "false" 
END IF 
dw_2.retrieve(para)
gnv_appeonDbLabel.of_endretrievequeue()

Appeon Update Label

Description

The Appeon Update Label is used to reduce the number of interactions with the server caused by "interrelated updates".

Controls

appeon_nvo_db_update object

Associated functions

of_update

Syntax

objectname.of_update (integer transactionflag, powerobject obj_1, powerobject obj_2)

objectname.of_update (integer transactionflag, powerobject obj_1, powerobject obj_2, powerobject obj_3)

objectname.of_update (integer transactionflag, powerobject obj_1, powerobject obj_2, powerobject obj_3, powerobject obj_4)

objectname.of_update (powerobject obj)

objectname.of_update (powerobject obj_1, powerobject obj_2)

objectname.of_update (powerobject obj_1, powerobject obj_2, powerobject obj_3)

objectname.of_update (powerobject obj_1, powerobject obj_2, powerobject obj_3, powerobject obj_4)

Argument

Description

objectname

An instance of the appeon_nvo_db_update object.

transactionflag

0 - transaction is automatically committed;

1 - transaction is not automatically committed.

Note: the of_update() function without this argument is preserved for compatibility.

obj

The name of the DataWindow, DataStore or DataWindowChild that needs to update.

obj_1

The name of the DataWindow, DataStore or DataWindowChild that needs to update.

obj_2

The name of the DataWindow, DataStore or DataWindowChild that needs to update.

obj_3

(optional) The name of the DataWindow, DataStore or DataWindowChild that needs to update.

obj_4

(optional) The name of the DataWindow, DataStore or DataWindowChild that needs to update.

Return value

Integer.

Return values are:

1 - Succeed in update

-101 - Fail to update the first DataWindow/DataStore/DataWindowChild

-102 - Fail to update the second DataWindow/DataStore/DataWindowChild

-103 - Fail to update the third DataWindow/DataStore/DataWindowChild

-104 - Fail to update the fourth DataWindow/DataStore/DataWindowChild

Usage

The update operations of the DataWindows, DataStores, or DataWindowChild will be submitted to the PowerServer together. If the operation of a DataWindow, DataStore or DataWindowChild fails, PowerServer will stop processing the update operation. Users can also use transactionflag argument to control whether to commit or rollback the Database update.

The following script has the same function. However, by using the Appeon Update Label the number of client-server interactions is reduced to one.

Using Appeon Update Label

l_rtn = gnv_appeonDb.of_update(0, dw_1,dw_2) 
IF l_rtn = 1 THEN
  Messagebox("Success","Update success!") 
ELSEIF l_rtn= -102 THEN
  Messagebox("Failure","Update all failure!") 
ELSE
  Messagebox("Failure","Update dw_1 failure!") 
END IF

Without using Appeon Update Label

IF dw_1.Update() = 1 THEN 
  IF dw_2.Update() = 1 THEN 
    COMMIT;
    Messagebox("Success","Update success!") 
  ELSE 
    ROLLBACK;
    Messagebox("Failure","Update all failure!") 
  END IF 
ELSE 
  ROLLBACK;
  Messagebox("Failure","Update dw_1 failure!") 
END IF