Debugging a Procedure

How to:

Display Command Lines as They Execute
Establish a Default Value for the &ECHO Variable
Test Dialogue Manager Command Logic

Reference:

Usage Notes for SET DEFECHO = NONE
Testing the Status of a Query

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 procedure.
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 (non-Dialogue Manager) 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 1. If an error occurs while parsing the procedure, the value of &RETCODE is 8.
&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.

Syntax: How to Display Command Lines as They Execute

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

where:

ON: Displays FOCUS commands that are expanded and stacked for execution.
ALL: Displays Dialogue Manager commands and FOCUS 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 FOCUS commands that are expanded and stacked for execution.
ALL: Establishes ALL as the default value for &ECHO. ALL displays Dialogue Manager commands and FOCUS 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 procname} &STACK = {ON|OFF}

where:

procname: Is the procedure to execute.
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.

Note: &STACK is usually used with &ECHO = ALL for debugging purposes. The terminal displays both the Dialogue Manager commands, as well as the FOCUS commands with the supplied values. You can view the logic of the procedure.

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

If you are using Simultaneous Usage (SU), you must know if the FOCUS Database Server is available before beginning a particular procedure. The following procedure tests whether SINK1 is available before launching PROC1.

? SU SINK1
-RUN
-IF &RETCODE EQ 16 GOTO BAD;
-INCLUDE PROC1
-BAD
-EXIT

Reference: Testing the Status of a Query

The system variable &RETCODE returns a code after a query is executed. If the query results in a normal display, the value of &RETCODE is 0. If a display error occurs, or no display results (as can happen when the query finds no data), the value of &RETCODE is 8. (If the error occurs on a ? SU, the value of &RETCODE is 16.)

The value of &RETCODE is set following the execution of any of these queries:

	NODISPLAY	ERROR
? HOLD	8
? SU*	8	16
? JOIN	8
? COMBINE	8
? DEFINE	8
? USE	8
? LOAD	8

*The &RETCODE value of ? SU means: 0 indicates that the FOCUS Database Server (formerly called the sink machine) is up with one or more users; 8 indicates that the FOCUS Database Server is up with no users; 16 indicates that there is an error in communicating to the FOCUS Database Server.

You can test the status of any of these queries by checking the &RETCODE variable and providing branching instructions in your procedure.