HCi Journal

Context-sensitive help for a mainframe application

Although most applications these days are developed to run with a GUI user interface, there are a large number of older applications (and some newer ones) which for one reason or another are still 'green screen', using character-based displays either on a terminal, or through a PC using a terminal emulator.

One of the advantages of a GUI interface is that online help can be made 'context-sensitive': by pressing the F1 key, the user can call up the help text that is associated with the particular screen that they are looking at at the time.

With mainframe applications, there are a number of ways of adding help text:

build the help text into the mainframe application, or use an external mainframe application to display it; unfortunately, the readability of text on a character-based display is very poor, and this often renders the text practically unreadable
build a help file which can be launched from a PC, but which is not context-sensitive; the user then has to navigate manually through the help file to the spot that deals with the relevant screen
deliver documentation on paper
build a context-sensitive help file, and then use the terminal emulator to link it to the mainframe application

This article describes the last of these approaches. It will work only in situations where:

the mainframe application uses (or can be retrofitted with) unique screen IDs that appear in the same place on each screen, and which identify that screen
the organisation has standardised on PCs with a standard terminal emulator for application access
the terminal emulator is programmable

This article provides example code for two common terminal emulators:

Hummingbird Software's HostExplorer, and
Attachmate's IRMA 2.1.1

... but the principles can be applied to any, more up to date, emulators.

Integration of the help files with the mainframe applications is achieved using the macro features of these emulators, which allow the F1 key of the PC to be mapped onto a macro (written, in the case of these two emulators, in a version of BASIC specific to each emulator). This macro in turn launches the help file.

From the user's perspective, this means that they run their terminal emulator as normal, log on, etc. When they need help, they press their F1 key. Their PC will launch the Windows help viewer, showing the correct help topic for the screen that they are viewing at the time.

We have developed macros to work in both HostExplorer and Extra! (they are included at the end of this document).

A number of files need to be developed for each application:

terminal emulator macro program (needs to be modified for site-specific drive mappings, etc)
help file
context ID map file

All three of these files will have to be placed on the network so that they are accessible by all users of the mainframe application. The keyboard mappings used for the application will also have to be changed to set the F1 keystroke to run the macro. Depending on how the terminal emulators are managed, this might simply be a case of changing a single central file. At worst, it will mean making minor changes at each desktop.

When the macro runs, it first looks at the screen being displayed. The macro captures this screen ID, and then reads the context ID map file to find out which help file context ID matches the screen. It then launches the Windows help viewer locally, and passes it the name of the help file and the context ID to display.

In order to modify this approach to use HTML files, simply have the macro call Explorer, and put the URL of the file in the context ID map file in place of the context ID. The URL will then be passed to Explorer as a parameter, and explorer will launch and display the relevant HTML file. The examples shown here are written for Win3.1 and Win95, but will work with minor modifications for Win98.

Terminal emulator program - Extra!

Sub Main

' Demo to show proof of concept of using Extra! for Windows version 5.1 to

' provide context-sensitive help for a mainframe application.

' This macro would be linked to, say, the F1 key for the profile which

' is set up for the mainframe application. When the user presses the

' F1 key, this macro abstracts the unique screen ID from the emulator

' page that's on the screen, does a lookup in a file that translates

' that into a help file context id, and then launches the local help

' viewer using the context id. In this way, the user is provided

' transparently with context-sensitive help for their mainframe

' application.

' Developed by Phil Cohen (pcohen@hci.com.au), and free of copyright.

Dim a$, tid, screenid$, contextid$, cmd$

tid=Connectsession("A")

a$=space$(5)

tid=Getstring(1, 2, a$, 5)

' Now looking only at top left 5 chars - but could be any part of

' the screen where the unique screen ID is found

Open "c:\extrawin\user\demo.txt" for input as #1

' File would be on a network drive, contain pairs of screen identifiers

' and help file context IDs, like this:

' "SCR01", 2

' "SCR02", 3

contextid$=""

Do while not eof(1)

Input #1, screenid$, contextid$

If a$=screenid$ then

Exit do

End if

Loop

If contextid$="" then

cmd$="c:\windows\winhelp.exe c:\extrawin\user\sample.hlp"

tid = Shell (cmd$,1)

' If there's no match, open the help file at the default context

' id for that file ...

Else

cmd$="c:\windows\winhelp.exe -n"+contextid$+" c:\extrawin\user\sample.hlp"

tid = Shell (cmd$, 1)

' ... otherwise, give the context id to winhelp.exe using the -n parameter;

' the .hlp file path will be on a network drive in practice

End if

' This method will work just as well with Win95 (using winhlp32.exe); the

' -n parameter works the same way.

End Sub

Terminal emulator program - HostExplorer

Sub Main

' Demo to show proof of concept of using HostExplorer to