The Director’s Chair
by Robert Freeman and Sheldon Smith		Advanced Techniques
		New Feature
		Special Feature
		FOCUS 101
		Update
		Customer Support
		OS Feature
		User Group Meeting Schedule

Troubleshooting Using TOE Have you ever had an error message appear on the screen but vanish before you could read it? Have you ever run a FOCEXEC with ECHO=ALL, only to have the portion you were interested in scroll off the screen? Do you find yourself continually typing the same command over and over? You can stop all this from happening, improve your troubleshooting skills, and increase your programming performance by using FOCUS' Terminal Operator Environment (TOE). TOE is a window-oriented environment (available in MVS and CMS versions of FOCUS and required in MSO) that presents different work areas on your terminal simultaneously. TOE is easy to use and provides capabilities such as scrollable windows that make debugging applications much simpler for ad hoc developers. You can use TOE to accomplish the following: Trap speeding error messages Retrieve previous commands Capture echoed FOCEXECs Create session logs Improve troubleshooting skills Improve programmer performance Trapping Speeding Error Messages During application development, occasionally a FOCUS error message flashes on the screen and then immediately disappears because the screen was cleared. This happens most frequently in CRTFORM-based applications, where the program returns to the menu after a selection. In this case, the error occurs, execution branches to the top of the procedure, the screen clears (along with the error message), and the menu redisplays. What was the error message? In what line did it occur? You can either press the PrintScreen key repeatedly, hoping to catch the text on paper, add ECHO=ALL to the FOCEXEC to slow down the application, or include a -PROMPT statement to pause the execution so that the screen does not clear. These solutions either rely on luck (while printing untold sheets of paper) or require you to change the FOCEXEC. A simple solution is to invoke TOE by issuing the FOCUS command WINDOW ON either at the FOCUS prompt or from within a FOCEXEC. When an error occurs, the TOE Error Window displays the error message, the full text of the message, and the line number where it occurred. The window remains on the screen until the user acknowledges it and presses the Enter key. An example of incorrect code (the word FILE is typed incorrectly) and the resulting error message appears on Figure 1. Normally, the FOC001 error message appears only as a blip on the screen. But when TOE is enabled by issuing the WINDOW ON command, the error message and text appear in the TOE Error Window (Screen 2). The window remains on the screen until it is acknowledged. (Multiple errors are either shown in turn or stacked on top of each other.) There is no need to change the application to take advantage of this feature. Figure 1 Command line errors also generate the TOE Error Window, but with an added bonus. TOE echoes the command and positions the cursor at the offending statement. You repair the problem by typing over the faulty word, replacing it with the correct syntax. Window Types In addition to the Error Window, six other window types are available: The Command Window accepts user input. By default, users may enter four lines of text. It is possible to type an entire query without hitting the Enter key: Simply tab or hit the New Line key to go to each new line. The entire request can then be transmitted with one keystroke. Figure 2 The PF2 (zoom) key can be used to increase the size of this window to the size of the screen, allowing you to enter many lines of an ad hoc query. To reduce the window to its original size, press the zoom key again. Any window can be enlarged using the zoom key by tabbing to the desired window, pressing the Enter key to make the window active, and pressing the PF2 key. The Output Window echoes the input commands and the resulting output. Here, FOCUS displays statistical messages, such as the number of lines and records, as well as - TYPE messages from the application. Report output still appears in HotScreen. The History Window records the previous 40 typed-in commands for later recall. When you tab to a command in the History Window and press the Enter key, FOCUS copies it to the Command Window. Instead of retyping a previously issued command, you can go to the History Window, select that command and reissue it. TOE will recall the entire command, such as TABLE, including all of the related subcommands (verb and verb objects, sort statements, selection criteria, etc.). The Table Window displays the most recent report generated. When a TABLE request is generated, the report is produced in HotScreen. The first 200 report lines (up to 132 characters wide) are also stored in the Table Window. To review the previous report, tab to the Table Window and zoom it. You can scroll the window (as with any TOE window) up and down using PF7 and PF8, or left and right using PF10 and PF11. The Help Window shows and allows changes to PF keys. Pressing the PF1 key displays this window, which lists the 24 available function keys and their default values. Note that the PF6 key is set by default to RECALL. Pressing this key will recall the previous command that was typed in. If pressed repeatedly, it will scroll back through the list, returning all of the previous commands one at a time to the Command Window so they can be reissued. With TOE, you have the ability to "hot-key" backward through previously issued commands. The Fields Window displays available fields for selection. If, for example, you are writing a TABLE request at the command line and forget the correct spelling of a field, you do not have to quit the request and TED the master. Simply display the Fields Window by issuing a ?F query, then tab to the desired field and select it by pressing the Enter key. Selected Window Commands Several TOE commands are available to customize both TOE and FOCUS sessions. The following commands improve troubleshooting skills and increase programming performance. Techniques using these commands are illustrated in subsequent examples. WINDOW SET CONTINUE {ON|OFF} The SET CONTINUE command dictates the behavior of the Output Window. When the setting is OFF, the Output Window pauses when it is filled, waiting for acknowledgment from the user to continue. When the setting is ON, the Output Window is not displayed until the procedure is terminated or input is required. Even when MESSAGE=OFF, FOCUS prints blank lines to the Output Window, causing it to fill up. WINDOW ROUTE windowname {TO ddname|OFF} The ROUTE command copies window contents to a file. While FOCUS writes to the window, the same information is logged to the file pre-allocated to ddname. The file should be allocated with a record length of 132, a record format of F, and a disposition of MOD. WINDOW SET pfkey [FOCUS] command The SET PFKEY command allows users to assign common WINDOW and FOCUS commands to a PF key for use in a TOE session. (These settings are not used by HotScreen, CRTFORM, or TED.) If a FOCUS command is assigned, as opposed to a WINDOW command, the word FOCUS must be included in the syntax. Users may set PF keys by changing the text in the Help Window. This format allows you to issue the command from a FOCEXEC at any time in your TOE session. Echoed FOCEXECs and Session Logs The WINDOW ROUTE command can be used to capture any window input or output and save it for later use. Figure 3 illustrates how we save the echoed output of a FOCEXEC. First, we enable TOE with the WINDOW ON command and then allocate a log file to an arbitrary ddname with the appropriate characteristics. The example uses a temporary file, but a permanent dataset may be more suitable. The command WINDOW SET CONTINUE ON is issued to prevent the Output Window from displaying when it fills up. The WINDOW ROUTE OUTPUT command tells FOCUS to begin copying the Output Window contents to the TOELOG file. The FOCEXEC is executed with ECHO=ALL and all of the output is logged. Finally, we end the log session with the command WINDOW ROUTE OUTPUT OFF. The resulting output file can now be edited or used by another application. Figure 3 In addition to troubleshooting local applications, this technique is helpful when providing support for users from a remote location. Users can reproduce their problem, log the results to a file and make it available for further examination. You no longer have to wait for screen prints to be faxed to other locations; you can debug online. Figure 4 shows how the same technique can be used to create session logs. Route the History Window contents to a file to save all of the commands that you issued during your session, allowing you to trace your work during ad hoc development. You can develop the structure of a report and easily reproduce it at a later time. Figure 4 The Terminal Operating Environment provides troubleshooting and productivity features that will save you time and frustration. The Error Window traps speeding error messages, and the ROUTE command logs echoed FOCEXECs. The RECALL key and History Window allow you to reissue commands without retyping. You may set function keys to issue commonly used commands. Once you use TOE, you will wonder how you got along without it. By the way, WINDOW OFF turns TOE off, but I doubt that you will want to.