Linking Windows in Advanced Revelation

In Revelation G, a data entry screen cannot be larger than the viewing area of the monitor. Therefore, an option is provided to allow one screen to be linked to another. Upon finishing a screen, you are prompted to choose "Next screen, Starting screen, or number of screen". Using this protocol, you can update the same record in a file by calling multiple data entry screens in succession.

In Advanced Revelation you are often faced with a need for more than one screen for prompts. The typical solution is to have the window span more than one "page", using the "Page Head Tab" ([Alt-H]) in Paint, thus creating a large entry window.

A common complaint about large windows in Advanced Revelation is the time it takes to display them. This is due to the processing necessary to display large windows and to calculate any symbolics in the window.

There is, however, an alternative solution that links windows in a manner similar to that used in Revelation G. Smaller linked windows take less time to appear because there is less video processing involved and possibly fewer symbolics to calculate.

Linked windows may also be chosen for purely aesthetic reasons. You can use more room to organize prompts and labels if you don't have to worry about the time it takes to bring the window up.

Figure 1 illustrates a program that enables you to control a sequence of linked windows. The program is actually a shell around a call to WINDOW, the window processor. The program (actually a subroutine) can be called from anywhere that you can call a subroutine and pass it an argument such as from a code and command hook in a menu.

There are four sections in the program:

• The main section calls one of three internal subroutines. An argument passed at process hooks defined in each of the linked windows determines which subroutine is called.
• The CONTROL subroutine is a loop that calls the windows with the appropriate record key (if any).
• The PRE_SAVE subroutine stores the current record and record key and loads an [Esc] keystroke into the keyboard buffer to force an exit from the current window.
• The last subroutine is a Replace-read process, REP_READ, which restores the record and key into @RECORD and @ID, respectively.

The program uses three labeled common variables:

The template names of the linked windows must end with a number designating their position in the linking order (for example, LINKED_1, LINKED_2, etc.). After each window is exited, WINDOW@ is incremented by one to call the next window in the linking order.

The program is first invoked with the CONTROL argument. When the program begins, the labeled commons are initialized (WINDOW@ is set to 1 for the first window), and the appropriate window is called using the value in WINDOW@. After a record key is entered, the record is read from disk.

When you save the record, the PRE_SAVE subroutine is called from the Pre-save hook of the window (set up in the Process window in Paint). If there is a record currently active, @ID and @RECORD are stored in the labeled commons KEY@ and REC@, respectively, and an escape keystroke is loaded into the keyboard buffer. This forces an exit from the current window and returns program control to the CONTROL portion of the program. If there is no record present (in other words, the window is blank), the window should not be exited.

At this point, if a key exists in KEY@, WINDOW@ is incremented to call the next window in the sequence. In each of the windows except the first, there is a Replace-read hook that calls the REP_READ section of the program. It is here that KEY@ and REC@ are transferred to @ID and @RECORD.

The Replace-read process allows successive windows, all accessing the same file, to be called without issuing an explicit UNLOCK command. A TRANSFER command is used to set KEY@ to null to act as a flag in the CONTROL subroutine. This indicates that the window was exited with [Esc] rather than [F9] (because KEY@ is assigned a value only in the PRE_SAVE subroutine). Any changes made to the record in the previous window are reflected in successive windows.

In the last window in the linking order there are no successive windows to which to pass the current record and key. Thus it is not necessary to call the PRE_SAVE subroutine. Instead the Pre-save process executes an [Esc] keystroke to exit the window and return to the CONTROL portion of the program.

At this point, because KEY@ is null and WINDOW@ is greater than one, WINDOW@ is reset to one, and the first window is called with no record key (blank). This action is also executed when any of the linked windows other than the first is exited with an [Esc]. If the first window (WINDOW@ = 1) is exited with [Esc], DONE is set to 'TRUE$', the loop in CONTROL is exited, and the program terminates.

Several steps are necessary to use LINKED_WINDOWS:

1. Create separate windows using Paint. The template name for each linked window must be the same, except that each must be suffixed with a number indicating its position in the linking order (for example, INVOICE_1, INVOICE_2, etc.)
2. Add a Pre-save process code 'S' and command 'LINKED_WINDOWS,PRE_SAVE' to each window except the last. In the last window, define the Pre-save process with a code 'K' and a command {ESC}.
3. Add a Replace-read process using a code 'S' and a command 'LINKED_WINDOWS,REP_READ' to each window except the first.
4. In each window except the first, make the key field Entry type prompt (in the prompt window) 'RP'. You can also hide the key prompt label.
5. Disable (through the Paint menus) the refresh function key ([F8]) to protect each record as it is passed through the progression of linked windows.
6. Set up a call to the shell program using a code and command. Use a code 'S' and a command that names your program and passes it the argument 'CONTROL'. Use this as an example:

   LINKED_WINDOWS,CONTROL

When using linked screens in Revelation G, you can call any of the screens directly and ignore the linking order. By adding a few lines to LINKED_WINDOWS, you can skip to any of the linked windows as long as there is a record active in the current window.

This is accomplished by defining a softkey in each window to call the program with the argument "SKIP". Figure 2 illustrates the extra lines required to implement the skip feature.

In addition, you should also add an R-mode popup with your template names (in order) under "Explicit Information" and return the row number position (designated by "P" at the "Type of information returned" prompt). Finally, you must add "SKIP" to the string SUBLIST in the shell program, and include it in the LOCATE statement.

When the SKIP internal subroutine is executed, your popup displays the linked template names, and if a choice is made, the row number (which is the window number) of the selection is returned in @ANS.

The PRE_SAVE subroutine is executed to ensure that KEY@ and REC@ hold their appropriate values, as well as to load the [Esc] keystroke to exit the current window. WINDOW@ is assigned a value one less than the window number to be called because it is incremented in the CONTROL section before the window is called.

Because the key prompt is protected in windows after the first one, there must be a record currently active before you are allowed to leave the current window. If you attempt to bring up another window when no record is present, an appropriate message is displayed.

SUBROUTINE LINKED_WINDOWS(VALUE)
COMMON /LABEL_COM/ WINDOW@, KEY@, REC@
DECLARE SUBROUTINE MSG

EQU TRUE$  TO 1
EQU FALSE$ TO 0
SUBLIST = 'CONTROL,PRE_SAVE,REP_READ' ; * (add SKIP if implementing
                                        * the code from Figure 2)

LOCATE VALUE IN SUBLIST USING ',' SETTING POS THEN
  ON POS GOSUB CONTROL, PRE_SAVE, REP_READ, SKIP
RETURN
* * * * * * * * * * * * * *
*     SUBROUTINE SECTION
* * * * * * * * * * * * * *
*
* CONTROL - This section calls the appropriate windows. If [Esc] is
* pressed in any window after the first, the first window is called
* (refreshed).

CONTROL:
DONE = FALSE$
WINDOW@ = 1
KEY@ = ''
REC@ = ''
LOOP
UNTIL DONE
  * change @TEMPLATES@ to the file in which you keep your templates.
  * this syntax assumes that the windows are called LINKED_n
  PERFORM 'WINDOW @TEMPLATES@ LINKED_':WINDOW@:' ':KEY@
  IF KEY@ THEN
    WINDOW@ += 1
  END ELSE
    IF WINDOW@ > 1 THEN
      WINDOW@ = 1
    END ELSE
      DONE = TRUE$
    END
  END
REPEAT
WINDOW@ = ''
KEY@ = ''
REC@ = ''
RETURN

* * * * * * * * * * * * * * * * *
*PRE_SAVE - Stores @ID and @RECORD in labelled COMMON variables and
* loads the keyboard buffer with [Esc] to leave the current
* window.

PRE_SAVE:
IF @ID THEN
  KEY@ = @ID
  REC@ = @RECORD
  @DATA = @INT.CONST<1> ; * [Esc]
END
RETURN

* * * * * * * * * * * * * * * * * *
* REP_READ - Retrieves the updated record from the previous window and
* reinitializes KEY@ and REC@.
REP_READ:
 TRANSFER KEY@ TO @ID
 TRANSFER REC@ TO @RECORD
RETURN

* SKIP - Allows the user to call linked windows in any order.
SKIP:
IF @RECORD THEN
  CALL CATALYST('P','POPUPS*WIN.CHOOSE')
  IF @ANS THEN
    WINDOW@ = @ANS - 1
    @ANS = ''
    GOSUB PRE_SAVE
  END
END ELSE
  MSG('A record must be active to call another window!','','','')
END
RETURN