Scribe Replace Process for Prompts (TB#80) (Functions/Subroutines/Programs)

Scribe Replace Process for Prompts

The window processor offers "hooks" for almost every conceivable purpose. In addition to the many hooks already associated with processing individual prompts, there is an undocumented one that allows you to take over the task of accepting input from the user. This is referred to as the "editor replace" hook, or because of the routine that normally is used for this function, the "scribe replace" hook.

A scribe replacement process gives you complete control over what the user types in, including what keys are active, what information displays on the screen as the user types, how the information is validated, and even what information is passed back to the window for further processing. As a typical example, you may want to use a scribe replace process when prompting the user for a password, so that the password does not display on the screen as the user enters it.

Prompt Processing

Under normal circumstances, WINDOW calls the system subroutine SCRIBE to do accept user input, and SCRIBE handles the tasks of accepting input, looking for priority keys (for example, [F5]), displaying the user's input in the prompt area, and terminating input when the user presses [Enter].

Just before the window processor calls SCRIBE, however, it looks to see if there is a code and command for a routine that should replace this normal sequence. If so, WINDOW will simply execute the code and command. When control returns to the window, WINDOW will place the contents of @ANS (or WINDOW_COMMON% WC_IS%) into the prompt's entry area.

WINDOW then proceeds on to the post-prompt process. It skips the validation process because it is the responsibility of the replacement process not just to get the user's input, but to validate it as well.

Replacing SCRIBE

A scribe replacement is done in much the same way as any other hook in a window, namely by indicating the code and command that you wish to have executed in lieu of the normal process. However, there is no facility in Paint to add a scribe replace process to a prompt. Instead, you must edit the window template directly using Advanced Revelation's editor. To add a scribe replace process to a prompt, follow these steps:

I. Bring the template up in the editor. For example, to edit the window called COMPANY.ENTRY in the TEMPLATES file, enter this command at TCL:

EDIT TEMPLATES COMPANY.ENTRY

II. Each prompt in the window will appear on its own line, starting with line 2 of the emplate record. Locate the line for the prompt you wish to edit and place the cursor there.

III. Press [Ctrl-E] to "explode" the multivalued prompt information into its own window.

IV. Move the cursor to line 39 of this window, and enter there the code (of the code and command) for the process that should replace the editor. Do not press [Enter], because you do not want to add another line – just replace what is there.

V. Move to line 40 and type the command portion of the code and command. Again, do not press [Enter], so as not to add a new line.

VI. Press [F9] to save your edits to the prompt.

VII. Press [Esc] to leave the exploded window.

VIII. Press [F9] to save the modified template, then [Esc] to leave the editor.

The Scribe Replace Process

You can call any routine you like as a scribe replace process, as long as that process can return data via @ANS or the WINDOW_COMMON% variable WC_IS%. This would most likely be a subroutine, but could be a popup or other process as well.

Two examples are provided in Figures 1 and 2, both illustrating ways of prompting for a password. The first example uses a call to MSG that can turn off (ECHO OFF) screen display during input. The second uses a more complex call to SCRIBE (as the window would do normally), but calls it in such a way that only asterisks (*) appear as the user types.

The second example relies on this information for the current prompt as kept in the prompt array WC_SI%:

WC_SI%<9> Video attributes

WC_SI%<12> Validation pattern(s)

WC_SI%<13> Output conversion

WC_SI%<14> Justification

WC_SI%<23> Edit mask

WC_SI%<28> Character count

Figure 1

SUBROUTINE MSG_ENTRY

ECHO OFF

* an RI message uses the R/BASIC INPUT statement – so

* no [F5] keys (etc.) are available during entry.

RESP = ""

CALL MSG("Enter the name", "RI", RESP, "")

ECHO ON

@ANS = RESP

RETURN

Figure 2

SUBROUTINE HIDE_ENTRY

* Calls scribe process with a masked character for output

* so user doesn't * see the text being typed.

$INSERT INCLUDE, WINDOW_COMMON%

$INSERT INCLUDE, WINDOW.POINTERS

T$ATTR = WC_ATR_OVR%<CBACKCUR>:WC_SI%<9>

SCRIBE_FLAGS_INSERT = WC_SCRIBE_FLAGS%

SCRIBE_FLAGS_INSERT<13> = "*" ; * substitute character for input display

PROTECTED = 0

SCB_DEPTH = 0

VALIDATE_INPUT = WC_SI%<12> ; * extract validation info from prompt array

* Note: the following call to SCRIBE should be ONLY ONE line.

SCRIBE(WC_IS%, PROTECTED, WC_WEXIT_KEYS%, WC_EXCEPT_KEYS%, WC_CRT_VX%, WC_CRT_VY%, WC_CRT_VLEN%, T$ATTR, SCRIBE_FLAGS_INSERT, WC_WCHANGE%, SCB_DEPTH, WC_WC%, VALIDATE_INPUT, WC_SI%<13>, WC_SI%<14>, WC_DELIM%, WC_SI%<23>, WC_SI%<38>,WC_SCRIBE_STATE%)

RETURN