====== Linking Windows in Advanced Revelation=====

^Published By^Date^Version^Knowledge Level^Keywords^
|Revelation Technologies|16 JAN 1990|2.X|EXPERT|SCREENS, SCREEN, REVG|

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.

==== Linked Windows ====

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.

==== Creating Linked Windows ====

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.

==== Program Structure ====

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:

|WINDOW@|holds the current window number|
|KEY@|holds the record key|
|REC@|holds the current record|

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.

==== Flow of Control ====

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.

==== Set-up ====

Several steps are necessary to use LINKED_WINDOWS:

  - 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.)
  - 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}.
  - Add a Replace-read process using a code 'S' and a command 'LINKED_WINDOWS,REP_READ' to each window except the first.
  - 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.
  - Disable (through the Paint menus) the refresh function key ([F8]) to protect each record as it is passed through the progression of linked windows.
  - 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:<code>LINKED_WINDOWS,CONTROL</code>

==== Skipping Windows ====

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.

==== Examples ====

=== Figure 1 ===

<code>
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
</code>

=== Figure 2 ===

<code>
* 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
</code>