Set up Client Information and Warning Messages

System messages to the client are divided into information messages and warnings. The information messages will just show a message to the client. The warning message handle, will be used to give the end user the opportunity to answer a question by choosing OK or Cancel in a Windows-like manner. These texts are language dependent and must be prefixed with the ordinary message key (see examples).

Some of the ideas with Windows-like user interaction are supported in package Client_SYS and their interface is described below:

The warnings will only appear on forms that have warnings enabled at the design time through Foundation1 Properties. The default setting is warnings enabled for form windows and disabled for table windows.

Note: Enabling warnings for table windows will noticeably decrease the performance of that window.

Contents

• Specification of GUI-interface
• Example 1
• Example 2

Specification of GUI-interface

PROCEDURE Clear_Info;

PROCEDURE Add_Info (
   lu_name_ IN VARCHAR2,
   text_    IN VARCHAR2,
   p1_      IN VARCHAR2 DEFAULT NULL,
   p2_      IN VARCHAR2 DEFAULT NULL,
   p3_      IN VARCHAR2 DEFAULT NULL );

PROCEDURE Add_Warning (
   lu_name_ IN VARCHAR2,
   text_    IN VARCHAR2,
   p1_      IN VARCHAR2 DEFAULT NULL,
   p2_      IN VARCHAR2 DEFAULT NULL,
   p3_      IN VARCHAR2 DEFAULT NULL );

FUNCTION Get_All_Info RETURN VARCHAR2;

Example 1

Client_SYS.Clear_Info;
...
Client_SYS.Add_Info(lu_name_, 'TOOYOUNG: Person is younger '||
                    'than 10 years old.');
...
Client_SYS.Add_Warning(lu_name_, 'DISAPP: Employee :P1 '||
                       'not valid', newrec_.name);
...
info_ := Client_SYS.Get_All_Info;

The framework generally handles the client presentation of the information/warning messages automatically. Standard transaction methods New__, Modify__ & Remove__ uses the variable info_ to transfer the messages up the client. The client framework decodes the information stored in the same variable using the methods HandleSqlWarnings and HandleSqlResult. What happens during a transaction is that the server methods are called twice from the client (if warnings are enabled for current datasource, see the Foundation1 Properties dialog). The only difference between the calls is the value in the parameter action_. During the first access, the action_ is set to 'CHECK'. This results in only the validation part of the server method (E.g. Unpack_Check_Insert___) being executed. Here's where the warning messages may be used. Having added a warning message will make the client framework to decode it using HandleSqlWarnings and, if any warnings are found, they will all be presented, one at a time, and users may be able to answer OK or Cancel. If they answer Cancel, the transaction breaks. Otherwise, if the answer is OK, the transaction will continue by accessing the same server method once again. The only difference now will be that the action_ will be set to 'DO'. The validation part (E.g. Unpack_Check_Insert___) will be executed one more time and then the rest of the code (E.g. Insert___).

Here's an example on how to use this functionality on own, custom methods.

Example 2

SERVER:

PROCEDURE Do_Something(
   info_ OUT VARCHAR2,
   action_ IN VARCHAR2 )
IS
BEGIN
   ...
   Client_SYS.Add_Info(lu_name_, 'SHOW_INFO: Showing Information');
   ...
   Client_SYS.Add_Warning(lu_name_, 'ASK_USER: Should I Continue?');
   ...
   IF action_ = 'DO';
      ! Do some more stuff like the actual storage.
   END IF;
   ...
   info_ := Client_SYS.Get_All_Info;
END Do_Something;

CLIENT:

Function: MyOwnTransaction
   Returns
      Boolean:
   Local variables
      String: sStmt
   Actions
      Set sStmt = 'My_Lu_API.Do_Something__( :i_hWndFrame.frmMyForm.lsInfo, :i_hWndFrame.frmMyForm.sAction )'
      Set sAction = 'CHECK'
      If DbPLSQLBlock( c_hSql, sStmt )
         ! Show warnings (if any)
         If HandleSqlWarnings( lsInfo )
            ! All warnings were answered "OK".
             Set sAction = 'DO'
             If DbPLSQLBlock( c_hSql, sStmt )
                ! Show the information messages (if any)
                Return HandleSqlResult( lsInfo )
      Return FALSE

Window Variables:
   Long String: lsInfo
   String: sAction

In cases where there are no warnings in the server code, the first call (with the parameter 'CHECK') is unnecessary and will only impact negatively on the performance. Mostly, methods in IFS Applications do not have the need to display any warnings, only information messages after the transaction.