_____ _______ ___ QHELP Version 2.2 ___________ ____ ________ Interactive Help Facility ___ ___ __ _____ for the HP e3000 _____ ____ ______ QHELP User Manual _______ _________ __________ ____ Robelle Solutions Technology Inc. ____ ___ _______ _____ ___ 7360 137 Street, Suite 372 _______ ____ ______ ___ ___ Surrey, B.C. Canada V3R 7K1 __________ _____________ Toll-free: 1-888-ROBELLE ________________ (1-888-762-3553) ______ _____ ________ Phone: (604) 501-2001 ____ _____ ________ Fax: (604) 501-2003 ___________________ support@robelle.com _______________ www.robelle.com _______ ____ January 1995 Program and Manual Copyright Robelle Solutions Technology Inc. 1981-2007 ___ Permission is granted to reprint this document (but not for profit), provided that copyright notice is given. QEDIT and SUPRTOOL are trademarks of Robelle Solutions Technology Inc. Other product and company names mentioned herein may be the trademarks of their respective owners. 1 _______ _ _______ __ _____ Chapter 1 Welcome to QHELP _ ________ _____ ü Applying QHELP _ _____________ __ ___ _____ ü Authorization to Use QHELP _ _____ _____ __ __ _________ ü Using QHELP on HP Terminals _ ___ ________ __ _____ ü New Features of QHELP Most application subsystems and software utilities will benefit from an on-line HELP facility. QHELP is such a facility, and it does not require a great deal of system or programmer resources. QHELP makes it easy to maintain help text in an external Qedit ____ ____ file. Such a file is called a help file. For utility tools such as Qedit and Suprtool, the help file primarily explains the commands available in the tool, but also gives examples, applications, and news of recent changes. If you run one of our products and type HELP, you will find yourself in the QHELP system. ________ _____ Applying QHELP QHELP provides an easy means for the applications programmer to add HELP capability to application programs. The structure of the HELP text gives the user access to the information which is immediately necessary to the task at hand. Also, QHELP consumes a minimum of system resources when it isn't being used, and it is compatible with our Prose text formatter. _____________ __ ___ _____ Authorization to Use QHELP QHELP is distributed to all users of Robelle software products as part of the QLIB contributed library, at no extra charge. Users are authorized to merge QHELP into their own software, without restriction. QHELP is available in both compatibility-mode and native-mode. _____ _____ __ __ _________ Using QHELP on HP Terminals QHELP provides display enhancements for HP terminals. QHELP does not check for HP terminals. Instead, the RCrtModel JCW must be set before QHELP is invoked. The RCrtModel JCW must be set with the model number of the HP terminal that you use. If you are using a terminal emulator, you should set the JCW to the model number configured in your terminal emulator. If most or all of your users have HP terminals or terminal emulators, you might want to set the JCW in a logon UDC. _______ _ _______ __ _____ 2 Chapter 1 Welcome to QHELP This RCrtModel JCW can have any of these values: 2645 this is an old HP crt without function key labels 2392,etc. this is a newer HP crt with labels 7009 a 700/92 or 700/94 ___ ________ __ _______ ___ _ _______ ____ New Features in Version 2.2 - January 1995 ü By default, QHELP upshifts all keywords. To prevent keyword upshifting, run the QHELP compiler with Parm=16. ü Generate Microsoft Rich Text Format output suitable for input to the Microsoft Help Compiler, by running the QHELP compiler with Parm=8. ü QHELP was not ignoring spaces between keywords. ü The @-keyword did not work correctly in the Open and Find commands. ü Run the QHELP compiler with Parm=4 to generate HTML output, instead of QHELP output. __________ __ _______ ___ _ _________ ____ Highlights in Version 2.1 - September 1994 ü The escape sequence for creating a new blank screen does not work on the hpterm emulator of HP-UX. Enhanced it to eliminate overprint. ___ ________ __ _______ ___ _ ______ ____ New Features in Version 2.0 - August 1993 ü QHELP could sometimes produce a system failure when the compatibility-mode version was run on MPE/iX. This was due to a bug in MPE/iX, but we have programmed around the problem. ü The tree listing has a completely new format. Unlike the previous format, the new format should rarely exceed 80 columns. ü New examples in Pascal and C are included in the user manual. ü When QHELP is printing a list of keywords, a new keyword is shown for obtaining help on QHELP (? - Help). ü If there are two or more keywords in an entry, the keyword "@ - All" is added to the keyword list. _______ _ _______ __ _____ Chapter 1 Welcome to QHELP 3 ü The QHELP compiler was failing on input files with more than 25,000 lines. ü Doing a $ lp off when the lp option had never been enabled printed a file system tombstone message. ü Error messages in the QHELP compiler have been improved. ü The QHELP compiler upshifted lines that started with a period or a backslash and did not handle lines that were one character long. ü The QHELP on-line help has been revised. ü QHELP did not always handle screen overflow correctly. ü Pressing a function key when QHELP is paused for screen overflow now exits QHELP. 4 _______ _ ___ ___ ___ ___ __ ____ _______ _____ Chapter 2 How Far Can You Go with On-line Help? By Gary B. Nordman, The Pinton Group. _ ____________ ü Introduction _ ___________ _______ ____ ____ _____ ü Integrating On-line Help with Menus _ __________ ___________ ____ ______ ü Organizing Information into Levels _ ___________ ü Conclusions ____________ Introduction In our distant corporate past, our users communicated with the HP 3000 computer strictly through UDCs and program menus. Then came menu-driver programs, and we found we had a means of tying together various data entry and inquiry programs for each application. Our users liked it. It was more friendly and less technical. However, procedures manuals, documentation, tutorials, standards, and policies still existed largely in hard copy, as they do in most organizations. I was interested in using our computer system as the storage and retrieval medium. Hard copy is expensive to maintain and difficult to manage. We looked at data dictionaries for, among other things, the ability to provide free-form user-friendly documentation. They didn't quite fit. We are a long-time Robelle customer (Qedit, Suprtool, and Xpress). Fortunately for us, a few years ago Robelle began to include bonus software tools on their tapes. Using Robelle's SELECT and QHELP, we have taken major strides toward our goal of eliminating paper documents. Many DP systems have on-line help -- that is nothing new. However, I believe that our system includes three ingredients which you will find new and interesting: Integrating on-line help with the user menus Breaking information into manageable chunks Using on-line help for manual procedures ___________ _______ ____ ____ _____ Integrating On-line Help with Menus ______ SELECT is the menu system that we use. It is a program that runs other programs for the user, and it works on any terminal, not just HP terminals. Most users lack the time or desire to learn MPE commands, for good reason. The menu system provides us with: _______ _ ___ ___ ___ ___ __ ____ _______ _____ Chapter 2 How Far Can You Go with On-line Help? 5 1) Integration of all user functions under a single program. 2) Access to functions or further sub-menus by a single keystroke. "Functions" include application programs, MPE commands, and help files. 3) Security at any level, by providing password protection for any menu selection. SELECT is a good replacement for UDCs. To use it, you build a menu database and load it with a few menus and the commands to implement them. This part is easy because SELECT has a MAINT entry point that does all the work of updating the database. Then you give users a logon UDC that runs SELECT and logs them off when they are done (we use a UDC similar to the one that Robelle suggests in its SELECT manual). When you first put users into a menu and take the :Run command away from them, you will learn why a menu improves system security. We certainly did. I set up menus for the first group of users and taught them how to use SELECT. Immediately, I received complaints--they couldn't get their jobs done because programs they had been running were not on the menu. These were __ programs that we (in DP) thought they shouldn't have access to, and didn't need. But the users had found out about them from users in other departments and now depended upon them. SELECT can handle up to 99 commands per menu choice. This could include something as simple as running an inquiry program, or as complicated as several DISPLAY statements, followed by access to a multi-level QHELP file, followed by :Running one or two programs to complete various update stages in an application. Under these circumstances SELECT can provide control as well as ease of use. __ _______ ____ ___ _____ An Example from Our Menus Perhaps a few real examples will help make clear what we are trying to accomplish. Here is a sample menu that contains functions related to customer orders: Level 3 Order Processing and Archives 1 Exit this Menu 2 Help with Choices Shown 3 Purchase Orders 4 Customer Orders 5 Customer Invoice Archives _ Make a selection from Order Processing and Archives? 2 _ Enter number from the menu above? 5 A user selects menu choice '2', which always means "give me help on this screen" (in our menus). SELECT asks users which menu item they need help with, and finds the help text for that item. The help text can be in an ordinary Keep file or a special QHELP file. _______ _ ___ ___ ___ ___ __ ____ _______ _____ 6 Chapter 2 How Far Can You Go with On-line Help? _____ QHELP is the software tool that handles help text for the menu system and for application programs. Here is what users will see when they ask for help: QHELP (Version 2.2) Use ? for QHELP Commands The "Customer Invoice Archives" program provides on-line inquiry to: - customer invoices and credit/debit notes - invoice list by customer account number - crossref between credit/debit note and original invoice - request queue for printed invoice copies Below are keywords which provide access to information about the program steps and commands: STEPS Program steps to be read first! COMMANDS Description of program commands EXAMPLES Examples of commands for listing, cross referencing and requesting invoice copies L0: Keywords Under: CUSTOMER INVOICE ARCHIVES STEPS, COMMANDS, EXAMPLES ________ >COMMANDS The help text is about a screen's worth, followed by a list of three optional keywords. By selecting one of the keywords, the user can get further details about "customer invoice archives". Or, the user can hit Return to go back to the menu. _______ _____ __ ___ ____ ____ One innovation we have made is to include menus in the help text. That is, we list the keyword choices like a menu, describing each one with a phrase or sentence. This serves two purposes: it makes the help display look like the menu display, and it allows us to keep the keywords short while still giving the user ample data to make an informed choice. Another innovation we have introduced is to have menu choices in __ _______ ___ _______ _______ ____ the menus that do nothing but provide on-line help. They do not run any programs at all. A menu choice described as "Tape Handling" might consist of a single :QHELP command to display on-line help. __________ ___________ ____ ______ Organizing Information into Levels Rather than having a single menu screen with 30 choices on it, we ______ organize our application menus into levels, each of which offers the user 6 to 12 choices: 1st level - by department 2nd level - by application 3rd level - by program or program grouping 4th level - by program (if applicable) _______ _ ___ ___ ___ ___ __ ____ _______ _____ Chapter 2 How Far Can You Go with On-line Help? 7 For example, here are three levels of menu from our system: Level 1 __________ ____ _____ ________ ___ ______ ____ _____ Management Menu {only managers can access this menu} 1 Exit this Menu 2 Help with Choices Shown 3 Management Tools 4 Sales 5 Distribution 6 Merchandising 7 Accounting=>Level 2 __________ _________ ___ ________ ___ _______ 8 Credit Accounting {sub-menu for managers and clerks} 9 Admin 1 Exit this Menu 10 Branches 2 Help with Choices Shown 11 User Menus 3 Accounts Payable _____ ______ 12 Games 4 Accounts Receivable=>Level 3 {last level} ________ __________ 5 General Ledger Accounts Receivable 6 Sales Reports 1 Exit this Menu 7 Procedures 2 Help with Choices Shown 3 Payment Reconciliation 4 Unreconciled St'ment List 5 Reconciled St'ment List 6 Customer Invoice Archives 7 Customer Account Status 8 Customer Statement People can comprehend only a small number of concrete details at one time. By grouping a number of choices under one heading, we make it easier for users to grasp the computer system as a whole and to find the part within it that they need. _______ ____ ____ Modular Help Text There is nothing more frustrating than a help file that flows past at 9600 baud, screen after screen. You become adept at hitting Control-S. You want the help file to be full and detailed, but the basic unit of help text from the user's perspective is the terminal screen (which is 24 lines). You need to logically break help text into screen-size chunks, then put it back together in a structure that the user can understand. QHELP is an interface that provides on-line, interactive access to structured help text. QHELP organizes help text into small modules, each one identified by a keyword. You can group several keyword modules together under a new keyword and a block of introductory text. The final result is a hierarchy or tree of keywords, where each keyword can have its own sub-keys. These keywords provide access to various levels of detail. They provide the means to focus on a very specific subject, definition, example, or procedure, which might typically be one or two screens in length. They avoid the alternative of screen after screen of unrelated information rolling past your eyes. A multi-level keyworded approach to retrieval is much more effective than _______ _ ___ ___ ___ ___ __ ____ _______ _____ 8 Chapter 2 How Far Can You Go with On-line Help? one-dimensional non-keyworded help files. ___ __ ___ _____ How to Use QHELP 1. Using Qedit, create a skeleton outline of the keywords describing the program, system, or procedure. Keywords can actually contain two or more words if necessary. If you have more than three levels, look seriously at accessing major (or first level) keywords via menu choices. In this example, ________ ________ ____ ___________ handling and cleaning are the keywords under tape maintenance. .Beginkey tape maintenance .Beginkey handling .Endkey handling .Beginkey cleaning .Endkey cleaning .Endkey tape maintenance 2. Using Qedit, add the details for each keyword. Use the Justify command to format lines into tidy paragraphs with straight ___ margins left and right. We have found no need for a separate text formatter, but if you want one, QHELP has options to _____ interface with Robelle's Prose text formatter. .Beginkey tape maintenance Tape Maintenance In general: 80% of all tape problems are due to self- contamination, mostly from loose edge particles 3% of all tapes can be expected to go bad. A higher % indicates equipment/tape problems. Major atmospheric contaminants are paper and cardboard dust and outside pollutants. Below are keywords which provide access to information regarding tape handling and tape cleaning. .Beginkey handling Tape Handling: Sorry! Help not written yet. Check again at 2:00 PM. .Endkey handling .Beginkey cleaning Tape Cleaning: Sorry! Help not written yet. Check again at 2:00 PM. .Endkey cleaning .Endkey tape maintenance _______ _ ___ ___ ___ ___ __ ____ _______ _____ Chapter 2 How Far Can You Go with On-line Help? 9 3. Use QHCOMP (the help compiler) to compile the Qedit file. We use two groups for help files -- the DOC group for source files (editing) and the HELP group for object files (run-time). :run qhcomp.qlib.robelle;info="." { . for key lines} Enter INPUT file name? tapes.doc Enter OUTPUT file name? tapes.help 4. Use the Qhelp.Qlib.Robelle program or the :QHELP command in Qedit to test the structure of your help file. :run qhelp.qlib.robelle ENTER HELP FILENAME? tapes.help :run qedit.pub.robelle /qhelp tapes.help /exit _________ __ ____ _______ Hierarchy of Help Screens The help file you create is a hierarchical tree, just like the menus. The "+" command of QHELP will show the user the tree of keywords available to him. For example: :run qhelp.qlib.robelle Enter help filename? purchase.help >+ PURCHASE ORDERS STEPS FUNCTIONS ENTER STEPS COMMANDS ADD MODIFY COPY LIST UPDATE COST REPLACE _________ _____ _ ________ ____ _______ "Include" Files - Reusable Help Modules In QHELP, "include" files allow you to maintain help text in manageable, logical pieces. Suppose you want a single help file to explain how all the user's tools work together as a system. That "global" help file may "include" references to other help files, each of which describes a specific tool (each with its own keywords for program steps, definitions, examples, display formats, etc.). You can include a single, small, self-contained _______ _ ___ ___ ___ ___ __ ____ _______ _____ 10 Chapter 2 How Far Can You Go with On-line Help? help file on a specific topic in many different places. "Include" files give you a flexible method of breaking documentation into reusable help modules. The QHELP method of "including" other help files does not use an "Include" command. Instead, you can specify the name of an external help file on any command that defines a new keyword. ___________ _____ Multi-Level Entry Since a help file can have many levels of keywords, it is useful that QHELP allows you to start the user's initial entry at any level and any keyword. For example, if everything about magnetic tapes is in a help file named "Tapes.Help.User", you can send the user directly to the section on parity errors. In the menu, you pre-specify the exact sequence of keyword choices needed to reach the desired spot in the help file. The user is not aware that you have done this. ______ __ ____________ _________ Limits of Hierarchical Retrieval SELECT and QHELP work effectively in practice down to three or four levels. Beyond that point there is the factor of diminishing returns. You tend to forget where you are as you go farther down. _______ ____ ___ ______ __________ On-line Help for Manual Procedures On-line help is common for computerized procedures, but we also ______ __________ apply it to manual procedures. A SELECT menu can be composed of :QHELP commands to display specific help text for the user. This extends the use of on-line help beyond the DP department. Other departments also have problems managing training text. The sales and personnel departments have policy manuals, sales tutorials, procedures, and reference matter that must be typed, revised, printed, and distributed. The same methods that work for showing users how to access computer programs can be used to show users how to perform manual tasks. ___________ Conclusions Our firm has come a long way since we installed our first simple menu program from the users group contributed library. Using Qedit, QHELP, and SELECT together, we now provide a friendly and flexible non-technical interface. All departments of the company now use menus and help files, at both the operational and managerial levels. We find that the combination gives us these benefits: security convenient, standardized, hierarchical access _______ _ ___ ___ ___ ___ __ ____ _______ _____ Chapter 2 How Far Can You Go with On-line Help? 11 elimination of hard copy, photocopying, and the expenses and problems associated with distribution. On our Series III [now upgraded!] there is no system or response-time degradation with SELECT. QHELP is normally instantaneous, unless the initial entry into the help file is to the third or fourth level in the keyword tree. In these cases, we notice response times of one or two seconds. Fine-tuning of the user interface is a never-ending process. There are always further refinements that we can make, and it is often the little, seemingly unimportant, changes that the users appreciate the most. We still have many ideas that we haven't had time to implement and user test. For example, QHELP allows a user program to provide on-line help by calling a procedure, specifying the help file name and the starting keyword. We have just started to retrofit such QHELP calls into our old application programs. The most important lesson we have learned in doing this is to maintain a single source for help text. We use the same help file in the menus, in the programs, and even for printed manuals. There is only one place to look for the final word and only one place to update. QHELP allows anything as a "keyword", including a phrase, and requires the user to type in only part of the keyword (enough to define it uniquely). Therefore, we could redo our help text so that keywords start with a selection number: 1 STEPS Program steps to be read first! 2 COMMANDS Description of program commands 3 EXAMPLES Examples of commands for listing, cross- referencing and requesting invoice copies. Then the user would always face the same choice, whether looking at a menu or help text: choose a number from those shown or hit Return to go back. Our users now perceive the availability of many more tools than were previously available, all through a single interface and a single medium, the terminal. Wherever possible, the menus, help files, and application programs present a consistent world for the user. We find this new user interface extremely effective. We use menus and on-line help for all of our applications software, of course, but we also use them for inquiry access to procedures, tutorials, corporate and departmental objectives, policies, and standards. 12 _______ _ _________ __ _ _____ ____ Chapter 3 Structure of a QHELP File _ ________ ___ ______ ________ ü Beginkey and Endkey Commands _ _______ _____ ü Command Lines _ __________ ___ ________ ________ ü Beginindex and Endindex Commands _ ______ ____ _____ ü Nested Help Files _ _____ _____ ____ _____ ü Using QHELP with Prose The basic structure of a QHELP file consists of a key such as "Qedit", some text about the key, and, optionally, lower level keys such as "NEWS", "INTRO", or "COMMAND". The structure can be nested: lower level keys can also have text and more keys. ________ ___ ______ ________ Beginkey and Endkey Commands A new key is specified by the Beginkey command. The end of a key is indicated by the Endkey command. The Beginkey command and the Endkey command are considered to be part of the key and each Beginkey must have a matching Endkey. .Beginkey qedit Qedit is the text editor that you use with QHELP. .Endkey qedit _______ _____ Command Lines QHELP distinguishes commands such as Beginkey from actual help text by looking for a special character in the first column of each line. The QHELP run-time routines discover the specific command character by examining the first command line in a help file. If it says "\Beginkey qedit" then all other command lines in the file must start with "\". But, if it says ".Beginkey qedit", then "." is the command indicator. QHELP ignores any commands that it doesn't recognize, which means that you can use the same command character for QHELP commands as you use for your text formatter. We do this with Prose, the text formatter provided with Robelle products. The help compiler must also know which lines are command lines. QHCOMP assumes backslash "\" for the command character and you must run QHCOMP with a special option to override that. Either with Info="!" to specify "!" (or some other special character) as the command character, or with Parm=1 to specify Prose input and "." as the command character. _______ _ _________ __ _ _____ ____ Chapter 3 Structure of a QHELP File 13 __________ ___ ________ ________ Beginindex and Endindex Commands When you compile your help text into a help file, the help compiler inserts Beginindex and Endindex commands into the help file. These commands delimit a possible index of keywords and the line numbers within the help file where QHELP is to find them. You will find a keyword index before the sub-keywords of any keyword. .BEGININDEX Qedit MANUAL 6000 * NEWS 94000 * RUN 130000 * INTRO 230000 * TERMS 590000 * COMMANDS 1192000 * .ENDINDEX Qedit The "*" after the line number means that the keyword will be found in the current help file. (QHELP allows nested help files as well as nested keywords). ______ ____ _____ Nested Help Files The basic file organization of QHELP files is one file with many Beginkey and Endkey commands, where Beginkey commands can be nested up to a level of 10. For very large systems, this is too cumbersome. It is necessary to have separate HELP files for each major system module. QHELP permits a single "logical" HELP file to be separated into several physical files, which can also act as stand-alone "logical" files. An external help file can be linked into a help ___ file at any Beginkey node by putting the name of the external file in brackets after the keyword: .Beginkey suprtool [suprtool.help.robelle] .Endkey suprtool The help file Robelle.Help.Robelle is a good example of one help file "including" several independent help files as sub-components. The help text for the Qedit and Suprtool keywords is kept in separate files in the Help group of the Robelle account. The primary Robelle help file contains the following entries to point at these other help files: .Beginkey robelle .Beginkey qedit [qedit.help.robelle] .Endkey qedit .Beginkey suprtool [suprtool.help.robelle] .Endkey suprtool _______ _ _________ __ _ _____ ____ 14 Chapter 3 Structure of a QHELP File .Endkey robelle Any key can be in another file, but nesting of files is only permitted to five levels. The [ ] indicates that the key is located in the file specified inside the [ ]. Of course, the Qedit and Suprtool help files can also be used as stand-alone help files. In fact, they are used this way by the Qedit and Suprtool programs. _____ _____ ____ _____ Using QHELP with Prose QHELP and Prose have been modified to work together. The Q+ option of the Prose Output command produces an output file that can be read by the QHELP compiler. When you want to have the Help compiler process a Prose input file, you run it with Parm=1 and it runs Prose for you automatically where needed. The QHELP compiler ignores all of the text before the first Beginkey command. This means that the user manual can contain a title page and a table of contents which will be ignored by the QHELP compiler. Text after the last Endkey is also ignored. This allows appendices and indices to be excluded from the help file, but included in the user manual. Any text between one Endkey and the next Beginkey will be ignored by QHELP, but will be picked up by Prose. The QHELP procedures try to recognize the Prose command character (the default is the period) by checking the first line of the help file. Example: The following example shows where the title page and index should go so that they are not included in the help file. .opt(l- r-).comment Center the following text. < Title page > < Table of Contents > .Beginkey Qedit < Text of the manual which becomes the help file. > .Endkey Qedit < This text will be ignored. > < index > 15 _______ _ ___________ ____ _____ Chapter 4 Interacting with QHELP _ ____________ ü Introduction _ _____ ________ ü QHELP Commands _ ____ ________ ü Tree Printing ____________ Introduction Assume that you have run qhelp.qlib.robelle and asked for the help file named Qedit.Help.Robelle. What happens next? QHELP prints the initial block of text from the help file, which is all of the lines that do not start with a period between the .BEGINKEY QEDIT line and the line that reads .BEGININDEX QEDIT. Then QHELP prints a list of keyword choices. QHELP (Version 2.2) Use ? for QHELP commands Welcome to version 4.3 of Qedit -- the fast text editor for HP 3000 programmers. L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS > QHELP prompts with a ">" character for the user to enter a keyword or a special command. If the user enters a valid keyword, all of the information for that keyword is displayed, along with a list of any sub-keys. In the example above, the user may type NEWS to get information on new features of Qedit. >news The user need not type the entire key word, since QHELP normally matches any leading sub-string of the key (this feature can be disabled with a Set command). In this example, the user could have typed N, NE, or NEW to get NEWS. One disadvantage of this feature: you cannot have another keyword after NEWS that consists of an leading sub-string of the string "NEWS". "N" would not be a reasonable keyword at this level, since you could never get to it! Of course, keywords at lower levels of nesting can be named any way you like. Whenever QHELP is printing text, the user may strike Control-Y to interrupt the printout. QHELP will usually prompt for another key word. _______ _ ___________ ____ _____ 16 Chapter 4 Interacting with QHELP _____ ________ QHELP Commands The user leaves QHELP by entering "Return" or by typing a circumflex (^) instead of a key name. Because the user may be several levels deep into the HELP file structure, he/she may have to enter "Return" several times, once for each level. Or, several circumflexes may be typed in a row(^^^). QHELP will return one level for each circumflex (e.g., entering ^^ exits two levels). Pressing either of the function keys f1 or f8 will also exit QHELP. There are several special commands that may be entered when the user interacts with QHELP. One of these is the circumflex (^), which is used to exit the interactive mode of QHELP. The question mark (?) prints information on the QHELP special commands. Another special command is the dollar sign ($), which is exactly the same as the QHELP Set command (e.g., $ LP On equals Set LP On). Sometimes it is desirable to print all of the information under a specific level. The "at" sign (@) is a special QHELP command, and key word, to do this. The following example illustrates the use of these special commands. Starting at the node for QEDIT, output is directed to the line printer. Next, all of the information under QEDIT is printed on the line printer; then output is directed back to the terminal. L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >$ lp on L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >@ L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >$ lp off Suppose you want to see the help text associated with the key word INFO=, nested under the key word RUN. One way to get this would be to enter the RUN keyword, wait for the RUN text and sub-keys to print, then enter the INFO= key word, read the desired material, and, finally, enter "Return". Or, at the entry level to QHELP (i.e., level 0), you could enter both the key word and the sub-key, separated by commas. QHELP will follow the indicated path through the HELP file tree and print only the lowest level, then exit back to the original level. _______ _ ___________ ____ _____ Chapter 4 Interacting with QHELP 17 >run,info ________ The comma here is required, not optional, since "keywords" in QHELP are allowed to have spaces in them. For example, one of the sub-keywords under "run" is "son process". Suppose you want to see everything on the RUN keyword. You can use the multiple key word option plus the "@" option to request all information under the RUN keyword. Control-Y will bring you back to the original level immediately. >run,@ ____ ________ Tree Printing The structure of a QHELP file is like that of a tree. In our example, the root of the tree is the key "QEDIT" and the branches on the first level consist of keys such as "MANUAL" and "NEWS". It is useful to have a full picture of the QHELP tree. When QHELP is interacting with the user, the tree from the current position in the help file downwards can be printed with the plus sign (+). For example: L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >+ QEDIT MANUAL NEWS RUN INTRO TERMS COMMANDS Further subkeys will be printed when they are present. Like the "at" sign command, you may wish to print the QHELP tree on the line printer. The following example would print all of the keys under Qedit on the line printer: L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >$ lp on L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >+ L0: Keywords Under: QEDIT _______ _ ___________ ____ _____ 18 Chapter 4 Interacting with QHELP MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >$ lp off When interacting with QHELP it is faster to enter both the key that you are interested in and any sub-keys. While this is faster, it requires that you remember what the sub-keys are called. To obtain a quick summary of the sub-keys under a particular key, use the plus option: L0: Keywords Under: QEDIT MANUAL,NEWS,RUN,INTRO,TERMS,COMMANDS >+ terms 19 _______ _ _____ ________ Chapter 5 QHELP Compiler _ ___ __ ___ ___ _____ ________ ü How to Use the QHELP Compiler _ _________ _____ _____ ü Compiling Prose Files _ ____ ______ ü HTML Output _ ___ ______ ü RTF Output _ __________ ____ ü Upshifting Keys The Qedit HELP file must be transformed before being used by the QHELP system. The reasons for this are as follows: 1. The HELP file must be checked to ensure that all Beginkey commands have a matching Endkey command. 2. The HELP file is verified to be a Qedit workfile with the Language=Job. 3. A series of indices must be inserted into the HELP file. This enhances the QHELP package by making it more efficient. 4. Each of the keys on the HELP file must be checked to see that it is not one of the reserved words or special characters. Any HELP file specified in the Open command must have been processed by the QHELP compiler. ___ __ ___ ___ _____ ________ How to Use the QHELP Compiler Use the following procedure to activate the Qhelp compiler: :run qhcomp.qlib.robelle [;info="."] Helpcomp/Qlib/ Copyright Robelle Solutions Technology Inc. 1981-2007 (Version 2.2) Enter INPUT file name? userdoc Enter OUTPUT file name? userhelp The optional Info= parameter tells QHCOMP to look for .Beginkey instead of \Beginkey (\ is the default). Without the Info="." you may get the following error: ERROR: No Beginkey was found in the input file The file Userhelp is now ready to be used by the QHELP procedures. The compiled HELP file must never be renumbered. Minor spelling corrections can be fixed, using Qedit, but you must never add, _______ _ _____ ________ 20 Chapter 5 QHELP Compiler delete or move any of the QHELP command lines. Also, if the HELP file uses the optional include facility described below, it cannot be copied to another group or account, since the full file name of the help file is stored in the help file as part of the key-word indices. To move a help file, you must re-compile it into a new file in the new group or account. Another warning: avoid Opening compiled help files in Qedit, unless the EOF is less than 84, since this will reduce the speed of later on-line access by upsetting the block pointers that were optimized by the help compiler. You can always re-optimize a large help file by compiling it again. There are several restrictions on the keys that can be used in QHELP. The compiler checks to see that none of the keys contain a comma (,), and that the following special characters ($,^,?,@) do not exist as key names. _________ _____ _____ Compiling Prose Files If your INPUT file for the help compiler contains Prose format commands, you must run QHCOMP with Parm=1 and you must use the ".output(lpt q+ w80)" command in the INPUT file. :run qhcomp.qlib.robelle;parm=1 More processing must be done to convert a file in Prose format to a QHELP file. The following steps must be performed to do the conversion from Prose format to QHELP format: 1. Insert a .output(lpt q+ w80) line in the Prose file. Be sure to delete or comment out the Output command that is currently in the Prose file. If are you using our .if commands and Prose 3.1 or later, use :setjcw outhelpcomp=1. 2. Run Prose, leaving the output in a disc file. 3. Run the QHELP compiler using the Prose output-file as input. Fortunately, most of these steps can be combined by using the Parm=1 option of the QHELP compiler. The following example converts the Suprtool manual into the Suprtool help file. :run qhcomp.qlib.robelle;parm=1 Helpcomp/Qlib/ Copyright Robelle Solutions Technology Inc. 1981-2007 (Version 2.2) Enter Prose INPUT file name? suprtool.doc.robelle Does the Prose file contain '.out(lpt q+ w80)'? yes Enter OUTPUT file name? suprtool.help.robelle _______ _ _____ ________ Chapter 5 QHELP Compiler 21 WARN: Records before the first Beginkey were skipped This example requires that you activate the .out(q+) command in the Prose file Suprtool.Doc.Robelle. As of version 3.1 of Prose, we set JCWs for different output. To use the file with the help compiler, set the OutHelpComp JCW: :setjcw outhelpcomp=1 In addition, you can ensure optimal pointer location in the help file by listing a string: /open suprtool.help.robelle /list ".Beginkey" /shut {make no other changes} This should substantially increase the speed of QHELP response. If you are using the Prose text formatter, the QHELP compiler looks for any lines that start with a special character which are followed by one of the QHELP keywords. In this case, formatting commands are not passed from the INPUT to the OUTPUT file. ____ ______ HTML Output Run the QHELP compiler with Parm=4 to generate HTML output. HTML stands for HyperText Markup Language and has been made popular by the World-Wide Web. When run with Parm=4, the QHELP compiler converts the keys into hypertext references. ___ ______ RTF Output Run the QHELP compiler with Parm=8 to generate Microsoft Rich Text Format (RTF) output. RTF is required by the Microsoft Help Compiler. When run with Parm=8, the QHELP compiler converts the keys into RTF footnotes. Converting the RTF output to a Microsoft Windows WinHelp file requires several extra steps. We recommend "The Developer's Guide to WinHelp.Exe" by Jim Mischel (published by John Wiley & Sons, Inc.) as a good reference book on how to create WinHelp files. __________ ____ Upshifting Keys By default, QHELP upshifts all keywords. Run the QHELP compiler with Parm=16 to stop the compiler from upshifting keywords. When run with Parm=16, the QHELP compiler insists that .Beginkey and .Endkey pairs be spelled exactly the same way. 22 _______ _ ___ _____ _______ Chapter 6 The QHELP Program _ ____________ ü Introduction _ _____ _____ __ _____ ___ ______ ü Using QHELP to Clear the Screen _ ____ ________ ü Tree Printing ____________ Introduction The QHELP program provides a means of examining a QHELP file without writing your own program. By default, the QHELP program prompts you for a QHELP file name. This file name may be followed by a list of QHELP keys in the QHELP file. When a set of keys is specified, the QHELP program works just like the keys were specified on the Open command. The alternative way of invoking the QHELP program is with the Info= parameter. The QHELP file name and any keys may be specified in the Info= parameter. For example: :run qhelp.qlib.robelle;info="robelle.help.robelle" would invoke QHELP with the Robelle help file. To obtain help on Suprtool you could use: :run qhelp.qlib.robelle;& info="robelle.help.robelle suprtool" The following User Defined Command will invoke the QHELP Program with any QHELP file. If no file is specified, the QHELP Program will prompt the user for the name of the file. qhelp filename="" run qhelp.qlib.robelle;info="!filename" The following two examples show how to use the QHELP UDC. The first uses the Robelle help file. The second uses the same file, but we obtain help on the commands chapter of the Suprtool manual. :qhelp robelle.help.robelle :qhelp "robelle.help.robelle suprtool,commands" _____ _____ __ _____ ___ ______ Using QHELP to Clear the Screen If you :Run the QHELP program with Parm=1, the QHELP program will home the cursor and clear the screen. This is similar to what the SELECT menu processor does with menu entries that call QHELP. If you combine the Info= and the Parm=1 options, the user will only see the help text (all prompts are suppressed). Try the following: _______ _ ___ _____ _______ Chapter 6 The QHELP Program 23 :run qhelp.qlib.robelle;parm=1;info="robelle.help.robelle" ____ ________ Tree Printing It is often useful to have a formatted listing of the keys in a HELP file. The QHELP program will produce a nicely formatted listing of the tree structure of your help file. To use the QHELP program to obtain a tree listing, you must do the following: :run qhelp.qlib.robelle ________ ENTER HELP FILENAME? filename {Input help file} >$ lp on {Output filename is Qhelpout} >+ >$ lp off The following example prints a formatted listing of the Qhelp help file on the line printer: :run qhelp.qlib.robelle Enter help filename? qhelp.qlibhelp.robelle >$ lp on >+ >$ lp off The listing from the line printer will look like this. The number in parentheses after each entry tells you how many lines of text are in the entry. QHELP Apply(10) Authorization(9) Hp Terminals(17) News(80) Introduction(36) Menu Integration(38) Example(23) What You See(24) Discussion(16) Levels(13) Example(32) Chunks(22) Operation(10) 1-Outline(14) 2-Fill(30) 3-Compile(10) 4-Test(11) Hierarchy(21) Include Files(17) Multi-Level Entry(12) Limits(8) Applications(14) Conclusions(34) Number Keywords(23) _______ _ ___ _____ _______ 24 Chapter 6 The QHELP Program ... 25 _______ _ _____ _____ ____ _____ Chapter 7 Using QHELP from COBOL _ ________ ___ ______ ü Commands for Coding _ _____ _____ ________ ü Using QHELP Keywords Before using QHELP, a standard status/communication area must be declared in the COBOL program. Its structure is as follows: 01 qhelp-area. 05 qhelp-command pic x(80). 05 qhelp-result pic s9(4) comp. 88 qhelp-ok value zeros. 88 qhelp-missing-key value 6. 05 qhelp-buffer-length pic s9(4) comp value 200. 05 filler pic x(200). We recommend that you enter this record into your COPYLIB, rather than coding the declaration into each application program. This communication area must be passed to all subprograms if the QHELP subsystem is opened in the mainline. ________ ___ ______ Commands for Coding QHELP is controlled by commands passed in a PIC X(80) field. The valid commands are: Open, Print, Find, Unfind, Set and Close. Each command must be left-justified in the buffer and be blank filled to the right of the command buffer. Before accessing the HELP text, the HELP file must be opened and QHELP initialized. This is done with the Open command. Assuming that the HELP file is called Qedit.Help.Robelle, the following would be coded into the COBOL program: move "open qedit.help.robelle" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: cannot open help file" perform end-of-program. If the user wanted general HELP on Qedit and the chance to interact with QHELP, the following would be coded into the COBOL program: move "print" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp ", qhelp-result perform end-of-program. On the terminal, the result of the Print command would be as _______ _ _____ _____ ____ _____ 26 Chapter 7 Using QHELP from COBOL ___________ ____ _____ described in the chapter Interacting with QHELP. If the application program required HELP on the intro part of Qedit, the following code would be used: move "print intro" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then if not qhelp-missing-key then display "error: failure of qhelp" perform end-of-program. _____ _____ ________ Using QHELP Keywords Throughout this description, the word "KEY" has a special meaning. A KEY can be a single key entry for the current level in the HELP tree. In order to progress faster through the HELP tree, more than one key can be specified. For example: move "print run,info" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then if not qhelp-missing-key then display "error: failure of qhelp" perform end-of-program. This example would result in the information about the "INFO" part of the RUN keyword being printed. Each comma represents another level in the HELP tree. A KEY can also be the special symbol "@". This key causes all information under the appropriate level to be printed. The following example would print all of the information under the RUN keyword, with no interaction with the user. move "print run,@" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then if not qhelp-missing-key then display "error: failure of qhelp" perform end-of-program. When looking for a specific key, QHELP matches on the minimum number of characters typed. In this way it is possible to search for keys without knowing their full names. The following example will print information on the intro part of Qedit. move "print in" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then if not qhelp-missing-key then display "error: failure of qhelp" perform end-of-program. 27 _______ _ _____ ________ Chapter 8 QHELP Commands _ ____ _______ ü Open Command _ _____ _______ ü Print Command _ ____ _______ ü Find Command _ ______ _______ ü Unfind Command _ ___ _______ ü Set Options _ ____ _______ ü Tree Command _ _____ _______ ü Close Command The following is a list of each of the QHELP commands and all of their parameters. Parameters surrounded with [] are optional. ____ ________ ____ _________ _ OPEN filename [key [,key...] ] Opens a QHELP file and, optionally, positions the internal QHELP pointers to a key within the file. The file name must be a QHELP file which has been processed by the QHELP compiler. The key must be one of the outer level keys of the QHELP file, optionally qualified by sub-keys. Opening with a key parameter is equivalent to an Open command with no key parameter, followed by a Find command with the desired keys. move "open qedit.help.robelle run,info=" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: unable to open qedit.help.robelle" perform end-of-program. _____ ____ _____ ____ _ PRINT [key [,key ...] ] Prints out the information in the HELP file. If a key is specified, QHELP searches for that key, starting at the current level. If the key is found, the information associated with the key is printed. After the key is printed, all sub-keys are listed and the user is prompted for a key to explain. If there are no sub-keys to that key, or the @ option was requested, QHELP returns to the caller. If no key is specified, the information at the current position in the HELP file is printed, along with the indices for the current position. To stop printing the indices at a current level and return to the previous level, Return or a circumflex (^) must be entered. move "print" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. _______ _ _____ ________ 28 Chapter 8 QHELP Commands ____ ___ _____ ____ FIND key [,key ...] Finds the specified key and sets the internal QHELP pointers to that position in the HELP file. This command permits the application programmer to position the HELP file to the key that corresponds to the current module being executed. A Print command with no parameters will then start printing the text selected by the last Find. move "find run" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ______ UNFIND Re-positions the internal QHELP pointers back to where they were before the last Find command was successfully executed. It is an error to Unfind past the first level of the HELP file. Find and Unfind do not print any HELP text. move "unfind" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ___ _______ SET Options The Set command allows certain QHELP defaults to be overridden. Options are followed by other parameters and each option can be abbreviated to its first character. The Set command must be used after the Open command, since the Open command resets all of the Set options back to their default values. The options and their parameters are described below. ___ ______ ________ SET SCREEN numlines (Default=0) QHELP normally continues listing HELP information until all of the information for an entry is printed, or until QHELP must stop to prompt the user for a new key. Many users employ Control-S and Control-Q to stop a listing if it goes over a screen; but this can sometimes be distracting, especially for new users. The screen option causes QHELP to pause after "numlines" has been printed on the terminal. If "numlines" is zero, QHELP will not pause (default). move "set screen 23" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then _______ _ _____ ________ Chapter 8 QHELP Commands 29 display "error: failure of qhelp" perform end-of-program. ___ ____________ ______ SET ERRORMESSAGE ON|OFF (Default=ON) Normally, QHELP prints an error message, as well as returning a non-zero result, whenever an error occurs. To turn error messages off, use the OFF parameter of this option. move "set errormessage off" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ___ __ ______ SET LP ON|OFF (Default=OFF) Normally, all HELP information is printed on the terminal. If you want a hard-copy, you must be able to list the HELP information on the line printer. When Set LP On is used, the file Qhelpout is opened. If no file equations are used, this file defaults to the line printer. All output from QHELP, except for the listing of the level and keywords, is then sent to the line printer. To send output back to the terminal, use Set LP Off. move "set lp on" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ___ _____ ____________ SET MATCH FULL|PARTIAL (Default=PARTIAL) Normally, QHELP searches for keywords using a partial match. The first keyword that matches the number of letters specified for the key causes a match. To force QHELP to always match the complete keyword, use the Set Match Full command. move "set match full" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ___ ______ _________ SET PROMPT character (Default=>) When QHELP is called with the Print command, QHELP prints out the current information, and then it goes into the interactive mode described above. Normally QHELP uses the greater-than (>) symbol to prompt the user for interactive commands. This character may _______ _ _____ ________ 30 Chapter 8 QHELP Commands conflict with the prompt character being used by the program calling QHELP. The prompt character can be changed to CHAR with this Set command. The following example changes the prompt character to a question mark (?). move "set prompt ?" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ___ _______ ______ SET WELCOME OFF|ON (Default=ON) When QHELP is called with the Print command, a welcome message is printed on the listing file. This Set command stops the welcome message from being printed. move "set welcome off" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. ____ ____ _____ ____ _ TREE [key [,key ...] ] This command prints the QHELP tree for the current node. If a key is specified, QHELP searches for that key, starting at the current level. If the key is found, the sub-keys associated with the key are printed like a tree on the current output device. No help text is printed and QHELP returns to the caller after printing the tree. move "tree" to qhelp-command. call "qhelp" using qhelp'area. if not qhelp-ok then display "error: failure of qhelp" perform end-of-program. _____ CLOSE This command closes all open HELP files and moves zeroes to the control buffer (QHELP-AREA). After doing a Close command, the QHELP-AREA may be re-used for another HELP file. move "close" to qhelp-area. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: unable to close qhelp file" perform end-of-program. 31 _______ _ ____________ __ _____ Chapter 9 Installation of QHELP _ _____ ___ _______ _______ ü Build the Robelle Account _ _______ ___ _____ ü Restore the Files _ _______ ___ _____ ü Install the Files _____ ___ _______ _______ Build the Robelle Account QHELP is distributed in the QLIB of every regular Robelle product tape. To install QHELP, you must first build the Robelle account using the job file Robelle.Pub.Sys, then :Restore all of the QHELP files. :hello mgr.robelle :file qtape;dev=tape :restore *qtape;qh@.qlib.robelle;show _______ ___ _____ Restore the Files The following files should be listed as Restored: Qhelpusl.Qlib.Robelle The compatibility-mode object code for the QHELP procedures. These must be installed in a group, account or system SL, or into a program's USL file. The segment name is QHELP. Qhelpxl.Qlib.Robelle The native-mode object code for the QHELP procedures. Qhelp.Qlibdoc.Robelle This User Manual in Prose format. To print yourself some copies, use the Printdoc program: :run printdoc.pub.robelle Printdoc is menu driven, and is very easy to use. Printdoc asks you for information, and if you are not sure of your answer, you can ask for help by typing a question mark (?) and pressing the Return key. Choose the ____ ________ sub-menu Qlib products to find the QHELP manual. Printdoc supports all types of LaserJet printers and regular lineprinters. Printdoc uses a message catalog, and requires Prose version 3.1 or later. It _______ _ ____________ __ _____ 32 Chapter 9 Installation of QHELP will look for these files in the same account as Printdoc. Also, Printdoc will only correctly print Prose documents that use the Output JCWs and the Prose If Commands to choose the output device. Qhelp.Qlib.Robelle General-purpose HELP program; it prompts for a HELP file, then gives assistance with the information in the specified file. The file name prompt will be suppressed if you specify the file name in the Info= parameter. Qhelpnm.Qlib.Robelle Native-mode version of the QHELP program. Qhcomp.Qlib.Robelle QHELP compiler. Qhcompnm.Qlib.Robelle Native-mode version of the QHELP compiler. To install this version as the production version, use these commands: :hello mgr.robelle,qlib :rename qhcomp ,qhcompcm :rename qhcompnm,qhcomp _______ ___ _____ Install the Files In order to call the compatibility-mode QHELP procedure, copy it into your USL file using the AUXUSL and COPYUSL commands of the Segmenter, or install it in an SL file. To install QHELP in an account SL where the account name is DEV, do the following: :hello mgr.dev,pub :segmenter -buildsl sl,500,8 -auxusl qhelpusl.qlib.robelle -buildusl temp,800,4 -copy segment,qhelp -addsl qhelp -exit If a program must use the QHELP procedures in the DEV account, it must be run with ";LIB=P". To avoid ";LIB=P", the QHELP procedure can be installed in the system SL. In order to call the native-mode QHELP procedure, run your program with 'XL=Qhelpxl.Qlib.Robelle'. You can install the native-mode QHELP procedure in your own XL-file with these commands: _______ _ ____________ __ _____ Chapter 9 Installation of QHELP 33 :hello mgr.dev,pub :linkedit -xl xl.pub -copyxl from=qhelpxl.qlib.robelle -exit 34 ________ _ _ _______ _____ _______ Appendix A - Example COBOL Program The following example program demonstrates the use of QHELP from COBOL. The program prompts the user for a command, and executes a separate module for each command. One of the valid commands is "HELP", and when the user types "HELP", QHELP is called. $control source,errors=5,list identification division. program-id. example. author. david greer, robelle solutions technology inc. environment division. data division. working-storage section. 01 true pic x value "t". 01 false pic x value "f". 01 qhelp-initialized-flag pic x. 88 qhelp-initialized value "t". 01 accept-buffer pic x(80). 88 answer-spaces value spaces. 01 accept-buffer-1 redefines accept-buffer. 05 acc-one pic x. 88 acc-command-exit value "e". 88 acc-command-add value "a". 88 acc-command-change value "c". 88 acc-command-delete value "d". 88 acc-command-help value "h". 05 filler pic x(79). 01 qhelp-area. 05 qhelp-command pic x(80). 05 qhelp-result pic s9(4) comp. 88 qhelp-ok value zeros. 88 qhelp-missing-key value 6. 05 qhelp-buffer-length pic s9(4) comp value 200. 05 filler pic x(200). procedure division. 00-main section. perform 05-initialize thru 05-initialize-exit. if qhelp-initialized then move spaces to accept-buffer perform 10-main-processing ________ _ _ _______ _____ _______ Appendix A - Example COBOL Program 35 thru 10-main-processing-exit until acc-command-exit. perform 95-finish-up thru 95-finish-up-exit. 00-main-exit. goback. $page "[05] initialize" 05-initialize section. move "open example.help" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: cannot open help file" move false to qhelp-initialized-flag else move true to qhelp-initialized-flag. 05-initialize-exit. exit. $page "[10] main processing" 10-main-processing section. move spaces to accept-buffer. perform 10-10-get-command until not answer-spaces. if acc-command-help then perform 10-20-call-qhelp else if acc-command-add then perform 20-process-add-command thru 20-process-add-command-exit else if acc-command-change then perform 30-process-change-command thru 30-process-change-command-exit else if acc-command-delete then perform 40-process-delete-command thru 40-process-delete-command-exit else if not acc-command-exit then display "error: unknown command name". go to 10-main-processing-exit. 10-10-get-command. display "enter command name". accept accept-buffer. 10-20-call-qhelp. ________ _ _ _______ _____ _______ 36 Appendix A - Example COBOL Program move "print" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then perform 99-fatal-error thru 99-fatal-error-exit. 10-main-processing-exit. exit. $page "[20] process add command" 20-process-add-command section. display "processing for the add command". 20-process-add-command-exit. exit. $page "[30] process change command" 30-process-change-command section. display "processing for the change command". 30-process-change-command-exit. exit. $page "[40] process delete command" 40-process-delete-command section. display "processing for the delete command". 40-process-delete-command-exit. exit. $page "[95] finish up" 95-finish-up section. move "close" to qhelp-command. call "qhelp" using qhelp-area. if not qhelp-ok then display "error: unable to terminate qhelp". 95-finish-up-exit. exit. $page "[99] fatal error" 99-fatal-error section. display " ". display "error: fatal termination of program". stop run. 99-fatal-error-exit. exit. 37 ________ _ _ _______ ___ _______ Appendix B - Example SPL Program The following example program demonstrates the use of QHELP from SPL. As in the COBOL example, this program prompts the user for a command name. When the user enters "HELP", QHELP is called. << splexample / dev notes: fix next line: $control nolist/$control list,map >> $control nolist $control uslinit,errors=5,main=splexample begin define end'if = end# ,end'else = end# ,end'while= end# ,end'case = end# ,end'do = end# ,end'proc = end# ,end'subr = end# ,p = begin move outbuf := # ,output=,2;output'(*);end# ; equate wl'outbuf = 50 ,bl'outbuf = wl'outbuf * 2 ; integer array outbuf(0:wl'outbuf); byte array outbuf'(*) = outbuf; << the following defines the spl workspace needed to communicate with qhelp. >> equate qhelp'len'workspace = 205; logical array qhelp'workspace(0:qhelp'len'workspace); byte array qhelp'command(*) = qhelp'workspace; <> integer array qhelp'result(*) = qhelp'workspace(40); <> integer array qhelp'buf'len(*) = qhelp'workspace(41); intrinsic print, readx, quit; procedure qhelp(workspace); logical array workspace; option external; procedure output'( address ) ; value address; integer address; << in outbuf >> begin integer output'length; << check length for overflow of buf >> output'length := (address-@outbuf)*2; if output'length > bl'outbuf then begin ________ _ _ _______ ___ _______ 38 Appendix B - Example SPL Program print(outbuf,-bl'outbuf,0); quit(111); end'if; print(outbuf,-output'length,0); end'proc; <> $page "level 2: process'add'command" procedure process'add'command; begin p "processing for the add command" output; end'proc; <> $page "level 2: process'change'command" procedure process'change'command; begin p "processing for the change command" output; end'proc; <> $page "level 2: process'delete'command" procedure process'delete'command; begin p "processing for the delete command" output; end'proc; <> $page "level 2: process'help'command" procedure process'help'command; begin qhelp'command := " "; move qhelp'command(1) := qhelp'command,(79); move qhelp'command := "print"; qhelp(qhelp'workspace); if qhelp'result <> 0 then p "error in calling qhelp" output; end'proc; <> $page "level 1: process'commands" procedure process'commands; begin integer array inbuf(0:80); byte array inbuf'(*) = inbuf; integer input'length; do ________ _ _ _______ ___ _______ Appendix B - Example SPL Program 39 begin p "enter command name" output; input'length := readx(inbuf,-80); if input'length > 0 then begin if inbuf' = "a" then process'add'command else if inbuf' = "c" then process'change'command else if inbuf' = "d" then process'delete'command else if inbuf' = "h" then process'help'command else if inbuf' <> "e" then p "error: unknown command name" output; end'if; end'do until inbuf' = "e"; end'proc; <> $page "level 1: init'splexample" logical procedure init'splexample; begin init'splexample := false; qhelp'workspace := 0; move qhelp'workspace(1) := qhelp'workspace, (qhelp'len'workspace-1); qhelp'buf'len := 200; move qhelp'command := " "; move qhelp'command(1) := qhelp'command,(79); move qhelp'command := "open example.help"; qhelp(qhelp'workspace); if qhelp'result <> 0 then p "error: unable to open help file" output else init'splexample := true; end'proc; <> $page "complete'splexample" procedure complete'splexample; ________ _ _ _______ ___ _______ 40 Appendix B - Example SPL Program begin move qhelp'command := " "; move qhelp'command(1) := qhelp'command,(79); move qhelp'command := "close"; qhelp(qhelp'workspace); if qhelp'result <> 0 then p "error: unable to close help file" output; end'proc; <> $page "mainline" if init'splexample then begin process'commands; complete'splexample; end'if; $control list end. <> 41 ________ _ _ _______ ______ _______ Appendix C - Example Pascal Program The following example program demonstrates the use of QHELP from Pascal. Unlike the COBOL and SPL examples, the Pascal example is much simpler. Its purpose is to show the record layout of the QHELP workspace, how to declare the external QHELP procedure, and example QHELP commands. { Qhelp Pascal Example } { Set nm=false for MPE/V } $set 'nm=true'$ $list off$ program test(input,output); const MaxQhelpCmdLen = 80; MaxQhelpBufLen = 200; type $if 'not nm'$ shortint = -32768 .. 32767; (* 16-bit integer *) $endif$ QhelpWorkType = record command: packed array[1..MaxQhelpCmdLen] of char; status : shortint; buflen : shortint; filler : packed array[1..MaxQhelpBufLen] of char; end; var QhelpWork : QhelpWorkType; procedure Qhelp( var work:QhelpWorkType ); external spl; procedure QhelpInit( var work: QhelpWorkType ); begin work.buflen := MaxQhelpBufLen; end; procedure CallQhelp( var work:QhelpWorkType ); begin Qhelp( work ); end; begin QhelpInit( QhelpWork ); ________ _ _ _______ ______ _______ 42 Appendix C - Example Pascal Program QhelpWork.command := 'open spell.help.robelle'; CallQhelp( QhelpWork ); if QhelpWork.status=0 then begin QhelpWork.command := 'set screen 23'; CallQhelp( QhelpWork ); QhelpWork.command := 'print'; CallQhelp( QhelpWork ); QhelpWork.command := 'close'; CallQhelp( QhelpWork ); end; end. 43 ________ _ _ _______ _ _______ Appendix D - Example C Program The following example program demonstrates the use of QHELP from C. Unlike the COBOL and SPL examples, the C example is much simpler. Its purpose is to show the record layout of the QHELP workspace, how to declare the external QHELP procedure, and example QHELP commands. /* Qhelp C Example */ #pragma list off #include #include #define MaxQhelpBufLen 200 #define MaxQhelpCmdLen 80 typedef short int int16; typedef struct { char command[MaxQhelpCmdLen]; int16 status; int16 buflen; char filler[MaxQhelpBufLen]; } QhelpWorkType; extern Qhelp( QhelpWorkType *work ); QhelpInit( QhelpWorkType *work ) { work->buflen = MaxQhelpBufLen; } CallQhelp( QhelpWorkType *work ) { int i, len; len = strlen( work->command ); for (i=len; icommand[i] = ' '; Qhelp( work ); } main() { QhelpWorkType QhelpWork; QhelpInit( &QhelpWork ); strcpy( QhelpWork.command, "open spell.help.robelle" ); ________ _ _ _______ _ _______ 44 Appendix D - Example C Program CallQhelp( &QhelpWork ); if (QhelpWork.status==0) { strcpy( QhelpWork.command, "set screen 23" ); CallQhelp( &QhelpWork ); strcpy( QhelpWork.command, "print" ); CallQhelp( &QhelpWork ); strcpy( QhelpWork.command, "close" ); CallQhelp( &QhelpWork ); } } 45 _____ Index $ command..........................16 + command..........................17 ? command..........................16 @ command..........................16 _ A abbreviating keywords..............15 at-sign to print all...............16 _ B backslash versus period............12 Beginindex command.................13 Beginkey command...................12 _ C C example..........................43 circumflex command, ^..............16 clearing the screen................22 Close command......................30 COBOL access to QHELP..............25 COBOL example......................34 command character..................12 commands at run-time...............27 control-y..........................15 _ D display enhancements...............1 dollar sign ($) = Set..............16 dumping help to LP.................29 _ E Endindex command...................13 Endkey command.....................12 error messages, off................29 Error: No Beginkey was found .....19 exiting interactive mode...........16 _____ 46 Index _ F Find command.......................28 full keyword matching..............15,29 function keys......................16 _ H help commands......................1 help compiler......................14,19 help file..........................1 help file structure................13 help files, nested.................9,13 HP terminals.......................1 _ I include files......................9,13 installation of QHELP..............31 interacting with QHELP.............15 introduction.......................1 _ J JCWs in Prose files................21 _ K keywords...........................15 keywords, restricted...............20 _ L LP dump............................29 _ M Match option.......................29 _ N nested help files..................13 nesting help files.................9 new features.......................2 _____ Index 47 _ O Open command.......................27 OutHelpComp JCW....................21 _ P Parm=1 invocation of QHELP.........22 partial keyword matching...........15,29 Pascal example.....................41 period versus backslash............12 plus sign (+) = tree...............17 Print command......................27 printing help file structure.......17,23,30 Prompt char option.................29 Prose files and JCWs...............21 Prose text formatter...............1,14,20 Prose version 3.1..................21 _ Q QHCOMP error message...............19 Qhcomp.Qlib.Robelle................19 QHELP commands.....................27 QHELP program......................22,23 QHELP use from COBOL...............25 QHELP, purpose of..................1 Qhelp.Qlib.Robelle.................15,22 question mark, ?...................16 _ R RCrtModel JCW......................1 _ S screen size........................28 Set command........................28 SPL example........................37 structure of help file.............12 sub-keys, pre-entry................16 Suprtool.Doc.Robelle...............21 _ T Tree command.......................30 tree printing......................17,23 _____ 48 Index _ U Unfind command.....................28 _ W Welcome option.....................30 ^ command..........................16 ______ _______ _____ Reader Comment Sheet _____ ___ ____ ______ QHELP 2.2 User Manual Your opinion of this manual is a valuable resource for helping us improve the quality of our documentation. We invite you to rate the manual in the areas shown below. Name: Date: Company: Position: Address: Phone: ______ ______ ___ ______ ___ _____ Please circle one number for each: ____ _______ ____ Good Average Poor ü General organization 1 2 3 ü Technical accuracy 1 2 3 ü Writing clarity 1 2 3 ü Convenience of size and format 1 2 3 ü Ease of locating information 1 2 3 ü Thoroughness of material 1 2 3 ü Quality of examples 1 2 3 ________ ___ ____________ _______ ___ ________ __ __________ Comments and suggestions: (please use reverse, or additional ______ __ _______ sheets as needed) _______________________________________________________________ _______________________________________________________________ _______________________________________________________________ _______________________________________________________________ _______________________________________________________________ _______________________________________________________________ Thank you for your feedback. We appreciate your time and interest. You may fax your comments to us at one of the following numbers or addresses. _______ _________ __________ ____ Robelle Solutions Technology Inc. Toll-free: 1-888-ROBELLE (1-888-762-3553) 7360 137 Street, Suite 372 Phone: (604) 501-2001 Surrey, B.C. Canada V3R 7K1 Fax: (604) 501-2003 E-mail: support@robelle.com Web: www.robelle.com iii _____ ____ ______ QHELP User Manual ________ Contents _______ _ _______ __ _____ Chapter 1 Welcome to QHELP Applying QHELP........................1 Authorization to use QHELP............1 Using QHELP on HP terminals...........1 New features..........................2 _______ _ ___ ___ ___ ___ __ ____ _______ _____ Chapter 2 How Far Can You Go with On-line Help? Introduction..........................4 Integrating on-line help with menus...4 Organizing information into levels....6 Conclusions...........................10 _______ _ _________ __ _ _____ ____ Chapter 3 Structure of a QHELP File Beginkey and Endkey commands..........12 Command lines.........................12 Beginindex and Endindex commands......13 Nested help files.....................13 Using QHELP with Prose................14 _______ _ ___________ ____ _____ Chapter 4 Interacting with QHELP Introduction..........................15 QHELP commands........................16 Tree printing.........................17 _______ _ _____ ________ Chapter 5 QHELP Compiler How to use the QHELP compiler.........19 Compiling Prose files.................20 HTML output...........................21 RTF output............................21 ________ iv Contents Upshifting keys.......................21 _______ _ ___ _____ _______ Chapter 6 The QHELP Program Introduction..........................22 Using QHELP to clear the screen.......22 Tree printing.........................23 _______ _ _____ _____ ____ _____ Chapter 7 Using QHELP from COBOL Commands for coding...................25 Using QHELP keywords..................26 _______ _ _____ ________ Chapter 8 QHELP Commands Open command..........................27 Print command.........................27 Find command..........................28 Unfind command........................28 Set options...........................28 Tree command..........................30 Close command.........................30 _______ _ ____________ __ _____ Chapter 9 Installation of QHELP Build the Robelle account.............31 Restore the files.....................31 Install the files.....................32 ________ _ _ _______ _____ _______ Appendix A - Example COBOL Program...............34 ________ _ _ _______ ___ _______ Appendix B - Example SPL Program.................37 ________ _ _ _______ ______ _______ Appendix C - Example Pascal Program..............41 ________ _ _ _______ _ _______ Appendix D - Example C Program...................43 _____ Index............................................45