Testing and Debugging a Dialogue Manager Procedure

In this section:

Viewing Messages for Debugging an Application

How to:

Test and Debug a Procedure
Establish a Default Value for the &ECHO Variable
Test Dialogue Manager Command Logic

Reference:

Usage Notes for SET DEFECHO = NONE

You can test and debug your procedure with the following.

The &ECHO variable controls the display of command lines as they execute so you can test and debug procedures.
The &STACK variable enables you to test the logic of Dialogue Manager commands. Setting this variable to OFF lets you run the procedure while preventing the execution of stacked commands. This gives you the ability to view the sequence of commands and see how the variable values are resolved.
The &RETCODE variable returns a code after a procedure is executed. If the procedure results in normal output or no records are retrieved, the value of &RETCODE is one. If an error occurs while parsing the procedure, the value of &RETCODE is eight.
&RETCODE can be used to test the result of an operating system command. This retrieves the return code from the operating system.

The &IORETURN variable tests the result of Dialogue Manager -READ and -WRITE commands. After a -READ or -WRITE operation, a non-zero return code indicates an error, such as end-of-file being reached.
&IORETURN can be used to test the result of the following:
- A -READ command. If &IORETURN equals zero, a value was successfully read from the external file.
- A -WRITE command. If &IORETURN equals zero, a value was successfully written to the external file.
- A -TYPE command to write messages to the application. Adding -TYPE commands is a way to debug complicated applications by placing messages throughout a procedure to determine which areas of the procedure were processed correctly. You may not want these messages to appear when you are not in the process of debugging the procedure.
  If you want to suppress the output of the -TYPE command, you must use a Dialogue Manager variable that will either comment or uncomment the -TYPE command, instead of using the -TYPE command directly. This Dialogue Manager variable will then be evaluated to -TYPE (to show the line) or evaluated to -*TYPE (to be treated as a comment and ignore the line). For example:
```
-DEFAULT &SHOWTYPE='NO'
 -SET &TYPE = IF &SHOWTYPE= NO THEN '-*TYPE' ELSE '-TYPE';
 &TYPE.EVAL MY MESSAGE
```
  If the query is run with &SHOWTYPE set to YES (or anything but NO) &TYPE.EVAL will evaluate to -TYPE. Otherwise, it will evaluate to -*TYPE, which will be treated as a comment and ignored.

Syntax: How to Test and Debug a Procedure

{-DEFAULT|-SET|EX} &ECHO = {ON|ALL|OFF|NONE}

where:

ON: Displays WebFOCUS commands that are expanded and stacked for execution.
ALL: Displays Dialogue Manager commands and WebFOCUS commands that are expanded and stacked for execution.
OFF: Suppresses the display of both stacked commands and Dialogue Manager commands. This value is the default.
NONE: Prevents procedure code from being displayed (echoed). Once the value of &ECHO has been set to NONE, it cannot be changed during the session or connection.

By default, any procedure that does not explicitly set the &ECHO variable executes with the value OFF. You can change this default value for &ECHO with the SET DEFECHO command, as described in Establish a Default Value for the &ECHO Variable.

Syntax: How to Establish a Default Value for the &ECHO Variable

SET DEFECHO = {OFF|ON|ALL|NONE}

where:

OFF: Establishes OFF as the default value for &ECHO. OFF is the default value.
ON: Establishes ON as the default value for &ECHO. Displays WebFOCUS commands that are expanded and stacked for execution.
ALL: Establishes ALL as the default value for &ECHO. ALL displays Dialogue Manager commands and WebFOCUS commands that are expanded and stacked for execution.
NONE: Prevents procedure code from being displayed (echoed). Once the value of DEFECHO or &ECHO has been set to NONE, it cannot be changed during the session or connection.

Reference: Usage Notes for SET DEFECHO = NONE

If you issue the SET DEFECHO=NONE command in a FOCEXEC, the setting does not affect &ECHO in that routine. It takes effect as the value of &ECHO in the next executed (EX) procedure after which it may not be changed.
If you attempt to reset &ECHO within the duration of its NONE value, the value you attempted to set will display if you issue a -TYPE command, but the value will not actually change.

Example: Preventing Procedure Code From Being Displayed

The following procedure queries the value of the DEFECHO parameter and issues a TABLE request against the EMPLOYEE data source:

? SET DEFECHO 
-RUN   
-TYPE ECHO = &ECHO         
TABLE FILE EMPLOYEE        
PRINT CURR_SAL CURR_JOBCODE
BY LAST_NAME BY FIRST_NAME 
END                        
-RUN

The query command output shows that DEFECHO is OFF (the default value):

 DEFECHO                  OFF

The -TYPE command shows that the value of &ECHO is OFF (the default):

ECHO = OFF

Because &ECHO is OFF the TABLE commands do not display as the procedure executes:

 NUMBER OF RECORDS IN TABLE=       12  LINES=     12
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY
PAGE     1
LAST_NAME        FIRST_NAME         CURR_SAL  CURR_JOBCODE
---------        ----------         --------  ------------
BANNING          JOHN             $29,700.00  A17
BLACKWOOD        ROSEMARIE        $21,780.00  B04
CROSS            BARBARA          $27,062.00  A17
GREENSPAN        MARY              $9,000.00  A07
IRVING           JOAN             $26,862.00  A15
JONES            DIANE            $18,480.00  B03
MCCOY            JOHN             $18,480.00  B02
MCKNIGHT         ROGER            $16,100.00  B02
ROMANS           ANTHONY          $21,120.00  B04
SMITH            MARY             $13,200.00  B14
                 RICHARD           $9,500.00  A01
STEVENS          ALFRED           $11,000.00  A07
                      END OF REPORT

Now, set DEFECHO=ON and re-run the procedure.

The query command output shows that DEFECHO is ON:

 DEFECHO                  ON

The -TYPE command shows that the value of &ECHO has been changed to ON:

ECHO = ON

Because &ECHO is ON, the TABLE commands display as the procedure executes:

TABLE FILE EMPLOYEE                                 
PRINT CURR_SAL CURR_JOBCODE                         
BY LAST_NAME BY FIRST_NAME                          
END

The output displays next:

 NUMBER OF RECORDS IN TABLE=       12  LINES=     12
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY
PAGE     1
LAST_NAME        FIRST_NAME         CURR_SAL  CURR_JOBCODE
---------        ----------         --------  ------------
BANNING          JOHN             $29,700.00  A17
BLACKWOOD        ROSEMARIE        $21,780.00  B04
CROSS            BARBARA          $27,062.00  A17
GREENSPAN        MARY              $9,000.00  A07
IRVING           JOAN             $26,862.00  A15
JONES            DIANE            $18,480.00  B03
MCCOY            JOHN             $18,480.00  B02
MCKNIGHT         ROGER            $16,100.00  B02
ROMANS           ANTHONY          $21,120.00  B04
SMITH            MARY             $13,200.00  B14
                 RICHARD           $9,500.00  A01
STEVENS          ALFRED           $11,000.00  A07
                      END OF REPORT

Now, issue the SET DEFECHO = NONE command and rerun the procedure:

SET DEFECHO = NONE

The query command output shows that the value of DEFECHO has been changed to NONE:

 DEFECHO                 NONE

The -TYPE command shows that the value of &ECHO is NONE:

ECHO = NONE

Because DEFECHO has the value NONE, the TABLE commands do not display as the procedure executes. The output is:

 NUMBER OF RECORDS IN TABLE=       12  LINES=     12
 PAUSE.. PLEASE ISSUE CARRIAGE RETURN WHEN READY
PAGE     1
LAST_NAME        FIRST_NAME         CURR_SAL  CURR_JOBCODE
---------        ----------         --------  ------------
BANNING          JOHN             $29,700.00  A17
BLACKWOOD        ROSEMARIE        $21,780.00  B04
CROSS            BARBARA          $27,062.00  A17
GREENSPAN        MARY              $9,000.00  A07
IRVING           JOAN             $26,862.00  A15
JONES            DIANE            $18,480.00  B03
MCCOY            JOHN             $18,480.00  B02
MCKNIGHT         ROGER            $16,100.00  B02
ROMANS           ANTHONY          $21,120.00  B04
SMITH            MARY             $13,200.00  B14
                 RICHARD           $9,500.00  A01
STEVENS          ALFRED           $11,000.00  A07
                      END OF REPORT

Once the value of DEFECHO has been set to NONE, it cannot be changed. The following SET command attempts to change the value to ON, but the query command output shows that it is still NONE:

SET DEFECHO=ON
? SET DEFECHO
 DEFECHO                 NONE

Syntax: How to Test Dialogue Manager Command Logic

{-DEFAULT|-SET|EX} &STACK = {ON|OFF}

where:

ON: Executes stacked commands normally. This value is the default.
OFF: Prevents the execution of stacked commands. In addition, system variables (for example, &RECORDS or &LINES) are not set. Dialogue Manager commands are executed so you can test the logic of the procedure.

Example: Using the &RETCODE Variable to Test the Result of a Command

The following command tests the existence of the C:\MYDATA\WEEK27.DAT file. If it exists, the value of &RETCODE is 0, and the file is erased.

DOS STATE C:\MYDATA\WEEK27.DAT
-IF &RETCODE NE 0 GOTO START;
DOS ERASE C:\MYDATA\WEEK27.DAT
-START

Viewing Messages for Debugging an Application

How to:

Use the Message Viewer

The Message Viewer enables you to see messages including error messages, informational messages, and Dialogue Manager commands such as -TYPE, -DEFAULT, and -SET &ECHO. These messages appear in a separate frame below the report output and serve as a good resource for debugging an application.

Syntax: How to Use the Message Viewer

Add the following WFServlet variable to your URL call for WebFOCUS:

IBIWF_msgviewer=option

where:

option

Is one of the following:

OFF: Disables the Message Viewer. When this option is disabled, you can still view informative messages or error messages for HTML reports from the view source option in your browser.
ON: Displays messages in a separate frame below the report output.
ECHOON: Displays messages and lines, in a separate frame below the report output, that are expanded and stacked for execution.
ECHOALL: Displays messages, lines, and all Dialogue Manager commands, in a separate frame below the report output, that are expanded and stacked for execution.

Note: The ON, ECHOON, and ECHOALL options are available for all output formats including HTML and PDF.

Example: Using the Message Viewer

The following illustrates how to use the Message Viewer with WebFOCUS self-service applications. This example shows the parameter with the ECHOALL option.

http://srv:port/ibi_apps/WFServlet?IBIF_ex=region&IBIWF_msgviewer=ECHOALL

The Message Viewer output related to executing the region.fex request is:

-INCLUDE region
-DEFAULT &VALUE = 'Northeast';
TABLE FILE GGSALES
SUM UNITS
BY REGION
WHERE REGION = 'Northeast'
END
0 NUMBER OF RECORDS IN TABLE=     1080  LINES=      1
0 HOLDING HTML FILE ON PC DISK ...