Integrating Windows and the FOCEXEC

When the -WINDOW command is encountered, control in the FOCEXEC is transferred to the Window facility. Control remains with the Window facility until one of the following occurs:

• The user makes a selection for which you have assigned no goto value.
• The PFKEY option is in effect and the user presses a function key (the function key must be set to RETURN, HX, CANCEL, or END, as described in the Testing Function Key Values.)

Once control passes back to the FOCEXEC, control only returns to the Window facility if another WINDOW command is encountered.

1. -START 
2. -WINDOW REPORT R1 PFKEY
   -* 
3. -*Control is transferred from the above command
   -*to window R1 in window file REPORT.
   -* 
4. -IF &PFKEY EQ PF05 GOTO LABEL1;
   -*
   -*Control returns to the above command from
   -*window R2 in window file REPORT.
   .
   .
   -LABEL1 
5. -WINDOW REPORT R3
   -* 
6. -*Control is transferred from the above command
   -*to window R3 in window file REPORT.
   -* 
7. -IF &R3 EQ EXIT GOTO EXIT;
   -*
   -*Control returns to the above command from
   -*WINDOW R3 in window file REPORT.
   .
   .
   -EXIT

When the user responds to your window prompt by entering text, selecting an item from a menu, or pressing a function key, this response is the return value that fills in an amper variable in your FOCEXEC.

There are two ways in which amper variables are most commonly used in FOCEXECs:

• To collect values to plug into a FOCUS procedure such as a TABLE or GRAPH request so it can run.
• To test the value returned in a variable, and branch accordingly to a different part of the FOCEXEC or to another FOCEXEC.

The return value collected can be a character string, a number, the name of a file, a procedure name, or part of a FOCUS command.

A return value amper variable in the FOCEXEC has the same name as the window in which it is collected; that is:

 
&windowname

For example, the return value collected by the window MAIN supplies a value for the variable &MAIN.

• In vertical menu and horizontal menu windows, you assign any return value to each item on the menu. If the user selects that option, that return value is collected.
• In text input windows, the return value is the text that the user types.
• In text display windows, you can assign one return value to the entire window. Unlike other return values, a text display window return value is collected as soon as control passes to the window, without the user selecting anything.
• Return value display windows display return values collected from other types of windows. These return values can be displayed one per line, or several together on a single line. Although this type of window does not have a return value, each line has a corresponding amper variable (&windownamexx, where xx is the line number).
• For a multi-input window, the return value is the name of the input field on which the cursor is positioned when you press Enter or a PF key.
• In windows with the Multi-Select option, the return value is the number of items selected.
• In file names, field names, and file contents windows, the return value is, respectively, the file name, field name, or line of file contents that the user selects from the display.

-START
-WINDOW EXAMPLE FILE
.
.
.
TABLE FILE &FILE

TABLE FILE SALES

When creating your windows, you also assign goto values telling the Window facility which window to display next. These values allow you to move the user through a series of windows, collecting return values for amper variables, without adding lines to your FOCEXEC.

• In vertical menu and horizontal menu windows, you assign a goto value for each menu item.
• In all other windows, you assign a single goto value.
• You can use an amper variable as a GOTO value.

As described in Transferring Control in Window Applications, if you assign no goto value to a menu option or window, control passes back to the FOCEXEC when the user selects that option or presses Enter at that window.

It is important not to confuse these goto values with the Dialogue Manager -GOTO command. The goto value points your application to a new window in the window file; the -GOTO command transfers control to a label in your FOCEXEC.

We have already discussed return values: these are specific to each window. Two other Window facility variables, &WINDOWNAME and &WINDOWVALUE, are specific to the -WINDOW session (not to each window) and receive values when the Window facility passes control from a window file back to the FOCEXEC.

To test for function key values, you must specify the PFKEY option on the -WINDOW command line. When the PFKEY option is set and a user presses a function key during window execution, the name of that key is stored in the amper variable &PFKEY.

For example, if the user presses PF1, the 4-character value of &PFKEY is PF01. If PF2, the value is PF02, and so forth. If the user presses Enter, the value is ENTR. The value of &PFKEY is reset each time the user presses a function key.

Note that if the PFKEY option is specified, the Window facility's default PF key actions are overridden by the general FOCUS PF key settings. This means that when you specify the PFKEY option, if you still want the standard Window facility PF key actions to be available to window users (for example, PF1 = HELP, PF3 = UNDO), you must use the SET command in your application FOCEXEC, followed by a -RUN command, to explicitly set those actions.

For example, if you specify the PFKEY option but you want to retain all of the Window facility's default PF key actions using the same PF keys, you need to include the following commands before the -WINDOW command in your application FOCEXEC:

SET PF01=HELP
SET PF03=UNDO
SET PF04=TOP
SET PF05=BOTTOM
SET PF06=SORT
SET PF07=BACKWARD
SET PF08=FORWARD
SET PF09=SELECT
SET PF10=LEFT
SET PF11=RIGHT
SET PF12=UNDO
-RUN

When you specify the PFKEY option, any PF key which you want to test for in the application FOCEXEC must be set to RETURN. (HX, CANCEL, and END also function as RETURN within the Window facility, and can be used in place of it.)

For example, if you design your application so that a user can press PF2 to choose an additional menu option, and therefore you want to test &PFKEY for the value PF02 in your application FOCEXEC, then you must include the following SET command before the -WINDOW command in your application FOCEXEC:

SET PF02=RETURN

The SET PF command is discussed in Customizing Your Environment, and in the Maintaining Databases manual.

You can list the current general FOCUS PF key settings by issuing the ? PFKEY command. The ? PFKEY command is discussed in Testing and Debugging With Query Commands.

The variable &PFKEY can be tested just like any other amper variable. Note that the name of the variable is always &PFKEY; it is not linked to a window name like other amper variables collected through windows.

You may test the PFKEY variable repeatedly throughout the FOCEXEC. Additional SET commands are not required.

One of the advantages of using the &PFKEY variable is that it enables you to collect two return values from a single menu. You might, for example, create a window called FILES, which prompts the user to enter the name of a file, then press PF7 to produce a graph or PF8 to produce a report. Both the file name as &FILES and the function key value as &PFKEY would be collected as return values.

It is always important to remember that pressing a function key immediately returns control to the FOCEXEC if that key was set to RETURN (or to HX, CANCEL, or END).

Note: If the cursor is on a menu that has a FOCEXEC associated with it, the FOCEXEC is executed and the GOTO value associated with the menu choice is assumed. The PFKEY is ignored.

In the example above, if the user presses a function key before typing the file name, the &FILES variable is not collected. If the key was set to something other than RETURN, HX, CANCEL, or END, then the action it was set to is invoked, and control remains within the Window facility.

You can execute a window directly from the FOCUS command prompt.