Tutorial 43: Debugging a Formspider Application

This tutorial describes how to debug a Formspider application. It covers following topics;

  • how to use the debug window
  • how to print custom messages on the debug window
  • how to use different debug levels
  • how to hide exception message details in production environment

Open Formspider IDE and click “New Application” under the “File” menu, the “New Application” dialog shows up. Enter “debug” as the name of the application and “HR” as datasource schema name. Leave other fields empty and click “OK”. This creates the “debug” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

The sample application performs a simple sum operation. When a button is pressed, it retrieves two numbers entered into textFields, calculates their sums and displays the result into another textField.

Expand the “Panels” node from the “Containers” tree and double click the “mainPanel” to open it in the editor. Add two textField components named “tf_value1” and “tf_value2” holding the two numbers to be added and another textField “tf_result” where the result of the calculation will be displayed. Add a button labeled “Sum” which calculates the sum of the values entered in “tf_value1” and “tf_value2” textFields and displays the result in “tf_result”. “mainPanel” XML should look like the following;

<panel>
  <tableLayout cellSpacing="5">
    <row>
      <cell>
        <textField name="tf_value1" domain="DefaultNumber"/>
      </cell>
      <cell width="10" hAlign="Full">
        <textLabel label="+" text-align="Center"/>
      </cell>
      <cell>
        <textField name="tf_value2" domain="DefaultNumber"/>
      </cell>
      <cell width="10" hAlign="Full">
        <textLabel label="=" text-align="Center"/>
      </cell>
      <cell>
        <textField name="tf_result" enable="N" domain="DefaultNumber"/>
      </cell>
      <cell>
        <button name="button_sum" label="Sum"/>
      </cell>
    </row>
  </tableLayout>
</panel>

To calculate the sum of two numbers and print the result when the “Sum” button is pressed, you have to create a Formspider action which fires when this button is pressed.

In your datasource schema, create a package called “debug_pkg” and open your newly created “debug_pkg” package in your favorite PL/SQL editor. Add a procedure named “sum” and ensure that the procedure is exposed in the package specification. This procedures calculates the sum of the numbers entered in “tf_value1” and “tf_value2” textFields and sets the result as the value of the “tf_result” textField.

procedure sum is
  v_value1_nr number;
  v_value2_nr number;
  v_result_nr number;
begin
  -- retrieve the value entered in the "tf_value1" textField
  v_value1_nr := coalesce(api_component.getvaluenr('mainPanel.tf_value1'), 0);
  -- retrieve the value entered in the "tf_value2" textField
  v_value2_nr := coalesce(api_component.getvaluenr('mainPanel.tf_value2'), 0);
  -- calculate the sum of two numbers
  v_result_nr := v_value1_nr + v_value2_nr;
  -- display the result in the "tf_result" textField
  api_component.setvalue('mainPanel.tf_resul', v_result_nr);
end;

Note that this code has a bug, while displaying the result of the sum operation, instead of “tf_result” textField, it sets the value of a component named “tf_resul” which does not exist in the specified panel named “mainPanel”.

In Formspider IDE expand the “Actions” accordion, select the “Actions” node, click the “+” button to create a new action. Alternatively you may right click the “Actions” node and select “New” from the pop-up menu. The “New Action” dialog shows up. Enter “sum” as the action name and “debug_pkg.sum” as the procedure. Click “OK” to save your “action”.

Creating “sum” action

Open the “mainPanel” in the editor. Add a buttonPress event to the “Sum” button triggering the “sum” action, the panel XML should look like;

<panel>
  <tableLayout cellSpacing="5">
    <row>
      <cell>
        <textField name="tf_value1" domain="DefaultNumber"/>
      </cell>
      <cell width="10" hAlign="Full">
        <textLabel label="+" text-align="Center"/>
      </cell>
      <cell>
        <textField name="tf_value2" domain="DefaultNumber"/>
      </cell>
      <cell width="10" hAlign="Full">
        <textLabel label="=" text-align="Center"/>
      </cell>
      <cell>
        <textField name="tf_result" enable="N" domain="DefaultNumber"/>
      </cell>
      <cell>
        <button name="button_sum" label="Sum">
          <events>
            <buttonPress action="sum"/>
          </events>
        </button>
      </cell>
    </row>
  </tableLayout>
</panel>

Press “Run on Web” button to run the application. Enter two numbers into textFields and press “Sum”. Note that an exclamation mark icon is appeared on the top-right of the application, meaning that an exception is occurred.

Exclamation mark icon is appeared on the top-right of the application

Click on this icon to display the exception message generated by the Formspider;

Click on the exclamation mark icon to display the exception message

In this simple application containing a single panel it’s easy to guess the procedure and the name of the button component which causes the exception but in a real application it’s definitely impossible. In order to debug your PL/SQL code, you have to first find the name of the button component and the procedure which causes the exception.

Using the Debug Window

This time, press “Debug on Web” button to run the application on the debug mode, note that a debug window appears on the screen. By default, this window displays all events that are called during the application life cycle and the result of each call. For example, when the application is opened you can see the events like “PREOPEN”, “POSTOPEN”, “PREAPPLYDELTA”… of the application and the “POSTINITIALIZE” event of the “mainpanel” are called but since these events are not used, there are not found.

Debug Window displays all events that are called during the application life cycle

Enter two numbers into the textFields and press “Sum” again. Note that an error log is appeared on the debug window;

When an exception occurs, an error log appears on the debug window

This log introduces a very detailed information about the exception;

  • the name of the component causing the exception (“mainPanel.button_sum”)
  • the component type (“Button”)
  • the name of the event causing the exception (“ButtonPress”)
  • the name of the action called by this event (“sum”)
  • the procedure referenced by this action ( “debug_pkg.sum”)
  • the name of the Formspider API causing the exception (“api_component.setValue”)
  • the exception message ( “Specified component name “mainPanel.tf_resul” not found.”)

Now, you can navigate directly to the debug_pkg.sum procedure, check the usages of the api_component.setValue API and search for the usage where ‘mainPanel.tf_resul’ is used as the component reference.

You can always clear the logs displayed on the debug window by clicking the “Clear” button existing at the top-left of this dialog.

In addition to display the logs generated by Formspider, the debug window can also display the name and the type of any object existing in the application. You can use this functionality basically to discover the name of a specific component and in which panel it is. Without the debug window, this information is very hard to find especially in a complex application containing hundreds of panels and components.

To use this functionality, you should simply hover over the object while Ctrl+Shift keys are pressed. Every time the mouse cursor hovers over a different object, its details appears on the debug window. Press “Debug on Web” button again and move you cursor over different components while Ctrl+Shift is pressed.

Move you cursor over different components while Ctrl+Shift is pressed to display its details

Printing custom messages on the Debug Window

You can also use the debug window to print your custom messages which help the debugging operation. Open “sum” procedure again, and use api_debug.log procedure to print the value of all variables used in the procedure;

procedure sum is
  v_value1_nr number;
  v_value2_nr number;
  v_result_nr number;
begin
  -- retrieve the value entered in the "tf_value1" textField
  v_value1_nr := coalesce(api_component.getvaluenr('mainPanel.tf_value1'), 0);
  api_debug.log('v_value1_nr>> ' || v_value1_nr);
  -- retrieve the value entered in the "tf_value2" textField
  v_value2_nr := coalesce(api_component.getvaluenr('mainPanel.tf_value2'), 0);
  api_debug.log('v_value2_nr>> ' || v_value2_nr);
  -- calculate the sum of two numbers
  v_result_nr := v_value1_nr + v_value2_nr;
  api_debug.log('v_result_nr>> ' || v_result_nr);
  -- display the result in the "tf_result" textField
  api_component.setvalue('mainPanel.tf_resul', v_result_nr);
end;

Press “Debug on Web” button, enter two numbers into textFields and press “Sum” again. Note that this time, in addition to the error and info logs, a new type of the log named “USER” appeared on the debug window. These logs are the custom messages that we have added using api_debug.log API.

Custom messages are displayed using api_debug.log API

Using different debug levels

In Formspider, there are two different debug level;

  • Info: The default debug level of the Formspider. Displays the info logs (event calls) generated by Formspider as well as the error logs and custom logs created with api_debug.log API.
  • Error: Displays only the error logs and custom logs created with api_debug.log API.

Note that in Formspider, the debug level is defined on system level, meaning that changing the debug level will affect all applications.

To change the debug level to “Error”, you can use the following SQL statement on the schema where the Formspider engine stands (the default name of this schema is FORMSPIDER);

update bdf_setup set value_tx = 'Error' where var_cd = 'BDF_DebugLevel'

To change the debug level back to “Info”, you can use the following SQL statement;

update bdf_setup set value_tx = 'Info' where var_cd = 'BDF_DebugLevel'

Change your debug level to “Error” and run the application on the debug mode again. This time note that the event call logs (info logs) do not appear on the debug window.

Event call logs (info logs) do not appear on the debug window

Hiding exception message details in production environment

By default, when an exception is occurred, you can display the exception message by clicking the exclamation mark icon which appears on the top-right of the application. This usage is preferred to provide a quick understanding to the developers about the exception which is occurred. But in a production environment it’s often needed to hide the exception details as much as possible.

In Formspider, there are two different debug environment option;

  • Development: The default debug environment of the Formspider. Displays the full exception message generated by Formspider when the exclamation icon is clicked.
  • Production: Displays always the generic message “An error occurred. Please contact your system administrator.” when the exclamation icon is clicked.

To change the debug environment to “Production”, you can use the following SQL statement on the schema where the Formspider engine stands;

update bdf_setup set value_tx = 'Production' where var_cd = 'BDF_DebugEnvironment'

To change the debug level back to “Development”, you can use the following SQL statement;

update bdf_setup set value_tx = 'Development' where var_cd = 'BDF_DebugEnvironment'

Note that in Formspider, the debug environment is also defined on system level, meaning that changing the debug level will affect all applications.

Change your debug level to “Production”, run the application on the debug mode and press “Sum” to cause the exception. Note that this time, when you click the exclamation icon, the generic “An error occurred. Please contact your system administrator.” message displays.

The generic exception message displays

  • http://twitter.com/Ik_zelf Ronald Rood

    So all error messages are logged for review. Good, great! That’s a lot better than having to ask to reproduce the problem, if possible at all. How are those logs maintained? Where are they stored? How can we view them? (I have not yet seen full docu so it might be written somewhere …)

  • http://twitter.com/Ik_zelf Ronald Rood

    great way to debug interactive. What about a production environment. A user get’s ‘An error occurred’ that is not very informative. Are the real messages logged so application support can find what error the user got? Reproducing the error might not allways be possible.

    • http://www.gerger.co Yalim K. Gerger

      Hi Ronald.
      You raise an important point. The error message the end users see in production is controlled by the developer. He can catch any exception/error that might be raised, in an On-Error event and take the appropriate action. However, if an error/exception is not handled by the developer, Formspider does not display the full error stack to the user in a production environment because this is a security best practise. Showing the error messages would be viewed as a vulnerability by a security auditor.

      The actual error is logged for an administrator to review. Even more, Formspider can log every action the user takes and every response the application sends back. This log information is in such a detail that it could be executed automatically to see what the user has been doing in the application. We never got around to actually implement the software to do that yet but I think it will be a fun project.