Programmer 7500/MAX_PROGRAMMERS.iso/CLIPPER/MISC/MAKEHELP.ZIP/MAKEHELP.DOC

Text File | 1987-01-27 | 6.0 KB | 111 lines

.po 8
.cw 10


       MAKEHELP_-_A_Utility_to_Build_and_Maintain_Online_HELP_Messages
                   Randy Richter               January 27, 1987

With the release of Nantucket Software's CLIPPER compiler, creation of a
context sensitive, fully interactive HELP capability for dBASE III
applications became an attainable reality for non-technical programmers.
Prior to this package, this capability was available in only 3 cases:

     o    if you modified the DOS keyboard processor to intercept a particular
          key sequence, then determine your specific location within an
          executing program (which calls for complex assembly language use);

     o    if you designed a HELP program written around dBASE's SET FUNCTION
          command, and initialized variables for program location at every
          input prompt (which requires a lot of extra coding to handle both
          calling the HELP program and restoring conditions in the original
          program on return);

     o    or if you purchased a separate package, compiled into a .COM file
          (or the like) executed from within your dBASE application.

CLIPPER provides a mechanism for making this context information available to
a HELP program or any other program: the SET KEY n TO progname command.  Once
SET, pressing key  'n' causes CLIPPER to load and execute module 'progname'.
It also passes three parameters:  the name of the program currently being
executed, the current source code line number, and the name of the variable
waiting for user input.  Once 'progname' finishes executing, control returns
to the original program at the last line number.

By default, CLIPPER sets key F1 (actually, key 28) to HELP.PRG.  If this
program has been linked into your program, HELP will automatically be run when
key F1 is pressed.  You can override this default and, for example, assign F10
to the HELP program with the command:

                         SET KEY -9 TO HELP

In this case, key F1 (key 28) will be available for another use.

Nantucket provides a sample HELP program in their documentation.  This program
has several major shortcomings:

     o    Changing HELP messages will require recompiling and relinking your
          source code.

     o    Printing messages can only be accomplished by printing a source code
          listing; this is not a format readily presentable to an end user.

     o    If HELP.PRG is compiled into your main program, the resulting size
          of your program may be too large to fit into memory in one piece.
          This would require you to use overlays.
.pa
.he MAKEHELP                          #                      January 27, 1987
To resolve these difficulties, I wrote a different version of HELP.PRG,
included on this diskette.  This version stores help message in a memo field
(called HELP_MSG) linked to a particular variable (stored in the field named
HELP_VAR).  When F1 is pressed, the HELP program defines the current database
select area, opens area 9 for the HELP database, and searches that database
for the passed variable name.  If the variable is not found, a message is
displayed and control returns (after some housekeeping) to the calling
program.  If the variable is found (that is, if a help message has been
written for it), the message is displayed at the bottom of the screen using
CLIPPER's MEMOEDIT() command.  Use of MEMOEDIT is key to this routine.  It
allows the program author to provide as much HELP information as is desired,
while allowing the user to see as much or as little of the final message as is
needed (since MEMOEDIT allows for scrolling up and down through a memo field).

Once the user exits MEMOEDIT (by pressing either the F1 key again, or ESC and
answering 'Y' to the 'Abort edit' prompt), HELP selects the original database,
restores the original screen, and returns to the calling program.

This version of HELP does have some limitations.  In particular, it is not
fully context sensitive (unless you never use the same name for a variable in
two places - unlikely if you have separate add/delete/change routines).  If
this is a problem, the easiest solution is to modify the structure of the HELP
database to add the program name and/or line number of the different uses.  In
this case, you would also have to modify HELP.PRG to look for these variables
as well as HELP_VAR.

Maintaining your HELP files and messages is the function of MAKEHELP.PRG,
also included on this diskette.  This routine creates a unique help database
for your system (named 'xxxxxHLP', with 'xxxxx' replaced by your 1-to-5
character system acronym), and allows you to add, change, delete, view, or
print your messages.  MAKEHELP should not be included in your system's source
code; only HELP itself must be compiled and linked.

MAKEHELP makes extensive use of two CLIPPER 'extensions' to dBASE: its
treatment of memo fields as string variables, and its use of arrays.  These
are combined in the print routine (procedure SUBSTRING), where the memo fields
are truncated just before the phrase 'END OF MESSAGE', then placed into array
elements.  This last operation uses the MEMOTRAN function (written by
Nantucket) and the LAT function (written by me) to remove control characters,
and separate the memo field into separate elements broken at the end of whole
words.

There is one 'kludge' in the HELP procedure at the end of MAKEHELP:  this
version uses a procedure called SETCOLOR to set display colors.  This allows
HELP to determine the colors in use in the calling program, and restore them
once the help message has been displayed.  I'm currently looking for a way of
determining the current color setting in CLIPPER without resorting to this
klunky approach; any suggestions?

MAKEHELP and HELP are freely available for use within DOE applications.
No guarantees - but please let me know of any problems or suggestions.



ly available for use within D