Workarounds & APIs Guide
General API

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( )

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.

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( )

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.

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( )

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

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} )

objectname.of_commitqueue()

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()

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( )

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()

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)

Return value

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