Brief: The AS/400's help support is one of its great strengths. A powerful feature of this help support is an index search function known as InfoSeeker. Learn how you can create your own custom search indexes to provide users with powerful help search facilities.

Help support is one of the most important features of any application. User access to online, context-sensitive help text can be a significant training and productivity boost. At the touch of a key, a user can quickly obtain information about a display or a particular area of a display. But did you know that you can supplement your application help support with access to help text by topic? By adding an index search function, you enable users to search for specific topics based on search words or phrases and allow them to browse detailed information about each topic.

Index search functions have always been part of OS/400, but V2R3 introduces an enhanced version dubbed InfoSeeker. (MC first covered V2R3's InfoSeeker in detail in "The New AS/400 InfoSeeker," March 1994.) As the user searches for specific topics in his own words, InfoSeeker presents a list of matching topics. From the list, he can select topics for viewing help text such as definitions, overviews, diagrams and how-to instructions. By adding this function to your help support, you can make your applications even easier to learn and use.

InfoSeeker ships with every AS/400 as part of OS/400, so there's no additional charge. It comes with hundreds of topics concerning the operations and programming of your system. But InfoSeeker is not limited to these topics. You can add topics of your own, customized for your applications. Through OS/400's User Interface Manager (UIM) language, you can create help support that includes InfoSeeker access.

Overview of InfoSeeker

With InfoSeeker, you gain access to information organized by topics. Think of it as a glossary or a table of contents for a book. InfoSeeker allows a user to search for topics through search words or phrases. It matches the word or phrase from a user request with synonym tables. The synonym tables are linked to topic descriptions which are in turn linked to help text. Once a topic is found, the user can view information about it.

To illustrate how InfoSeeker works, let's say you need information on how to power down your system. When you key the phrase "power down," InfoSeeker displays all topics related to powering down your system, as illustrated in 1.

To illustrate how InfoSeeker works, let's say you need information on how to power down your system. When you key the phrase "power down," InfoSeeker displays all topics related to powering down your system, as illustrated in Figure 1.

InfoSeeker presents topics in an outline view with dynamic expand, contract and search capabilities so that you can readily find your information. In 1, you can see several topics which you can expand, as indicated by the plus sign (+) to the left of each topic. You can expand these topics individually with the Expand topic option (7) or all at once with the All topics function (F5).

InfoSeeker presents topics in an outline view with dynamic expand, contract and search capabilities so that you can readily find your information. In Figure 1, you can see several topics which you can expand, as indicated by the plus sign (+) to the left of each topic. You can expand these topics individually with the Expand topic option (7) or all at once with the All topics function (F5).

You can view a particular topic to get more detailed information. For example, if you use option 5 (Display topic) in the "Power down system (PWRDWNSYS) command" topic, you get the information screen illustrated in 2.

You can view a particular topic to get more detailed information. For example, if you use option 5 (Display topic) in the "Power down system (PWRDWNSYS) command" topic, you get the information screen illustrated in Figure 2.

Objects known as panel groups (type *PNLGRP) contain InfoSeeker topics and the lower-level help text for those topics. The panel groups aren't directly accessible by InfoSeeker; but when you add them to a search index object (type *SCHIDX), InfoSeeker indirectly gains access to them.

You can start InfoSeeker with the Start Search Index (STRSCHIDX) command, through the Information Assistant Options (INFO) menu or through any command or display file that has the search index function enabled.

For more information about InfoSeeker and the search index function, see the AS/400 manuals listed at the end of this article, or these MC articles: "Simplify Con-textual Help Development," May 1994; "The New AS/400 InfoSeeker," March 1994; or "Jazz Up Help With UIM," January 1992. InfoSeeker Topic Candidates

Now that you have an idea of what InfoSeeker does, let's look at what kind of information you should consider for the InfoSeeker function.

InfoSeeker topics generally include three types of information.

o Reference information-includes reference material such as definitions, examples and tables to help answer the question "What is?" o Procedural information-includes a series of steps to illustrate a process (for example, how to enter an order). Procedural information answers the question "How?" o Conceptual information-includes answers to the question "Why?" Contains overviews, advantages and comparisons.

In brief, anything that helps answer "What?" "How?" or "Why?" could be candidate material for InfoSeeker. Deciding what type of help information you're going to include may help you create information that is more effective. Now we'll look at the objects (and the source members used to create them) that InfoSeeker uses to display help information.

Panel Groups

Although you can use several objects-display files, OfficeVision documents and panel groups-to generate help support for your applications, panel group objects are the most versatile. (You can also use panel groups for creating menus and even application dialogues; but in this article, we'll only be using panel groups to generate help support.) Many useful functions are available through panel groups that aren't available through the other object types that can be used for help support.

 o Help support for user-written commands. o Windowed help text. o Hypertext links. o InfoSeeker functions. 

As you can see, there are several good reasons to choose panel groups for your application help. But if you want to access InfoSeeker functions, you have no choice-you must use panel groups.

You create panel group objects from source members of type PNLGRP much like you create CL program objects from CLP type source members. To make a panel group object accessible through InfoSeeker, you must add it to a search index object. Here are the four basic steps to developing InfoSeeker help.

 1. Create a panel group source member. 2. Create a panel group object from the source member. 3. Create a search index. 4. Add the panel group object to the search index. 

InfoSeeker-capable panel group source members include the topic list that InfoSeeker displays and the help text for each topic in the list. You create panel group source statements with the UIM language. This tag-based language is easy to use and requires very little formatting. Therefore, you don't have to use SEU to edit panel group source-any editor will do.

Each statement starts with a tag which identifies the purpose of the statement. For example, :HELP denotes the beginning of a help module and :P denotes the beginning of a paragraph. The tag identifier is optionally followed by elements referred to as attributes. Attributes, as the name implies, describe the characteristics of the tag statement and how it's used by UIM.

You can enter the source for panel groups in uppercase, lowercase or mixed case. UIM converts all text except tag content (text that you can display or print) to uppercase at the time you create the panel group. For more information, see "Simplify Contextual Help Development," MC, May 1994.

A panel group used for InfoSeeker is similar to any other help panel group- it's made up of help modules. However, InfoSeeker panel groups contain special UIM tags which provide the index search function. Only three such tags exist, so you should be able to remember them quite easily. 3 lists the tags and illustrates their formats.

A panel group used for InfoSeeker is similar to any other help panel group- it's made up of help modules. However, InfoSeeker panel groups contain special UIM tags which provide the index search function. Only three such tags exist, so you should be able to remember them quite easily. Figure 3 lists the tags and illustrates their formats.

If you have already defined your help text with panel groups, you have done much of the work. All you have to do is insert InfoSeeker tags in the appropriate places. Of course, you can also generate panel groups specifically for InfoSeeker, as we'll do here.

In the following sections, we'll describe each statement. We'll then look at a working sample to bind the how-to concepts in your mind.

:ISCH and :ISCHSYN Tags

Every InfoSeeker topic has a corresponding index search (:ISCH) tag statement in the help panel group source member. This tag specifies the topic text displayed by InfoSeeker for a given help module. InfoSeeker displays the topic when the user enters a word that matches a synonym you create for a topic or when the user displays all topics with the F5 (All topics) function. Examine the format of this tag in 3. You must place the :ISCH statement in a help module immediately after the help module statement (:HELP).

Every InfoSeeker topic has a corresponding index search (:ISCH) tag statement in the help panel group source member. This tag specifies the topic text displayed by InfoSeeker for a given help module. InfoSeeker displays the topic when the user enters a word that matches a synonym you create for a topic or when the user displays all topics with the F5 (All topics) function. Examine the format of this tag in Figure 3. You must place the :ISCH statement in a help module immediately after the help module statement (:HELP).

UIM requires the ROOTS attribute for the :ISCH tag. The ROOTS attribute contains a root word list. UIM links these root words to index search synonyms which you specify in the index search synonym (:ISCHSYN) tag statement. In other words, root words are linked to synonyms. This link is created with the :ISCH statement and its related :ISCHSYN statements. Normally you specify an :ISCHSYN statement for every root word found in the :ISCH statement.

You can use a maximum of 50 root words in the :ISCH tag, and each word can be up to 20 characters in length. Valid characters for root words are A through Z, a through z, and 0 through 9. Because a blank is not valid, you cannot create roots that are made up of more than one word. For example, if you used the city of Los Angeles as a root, InfoSeeker considers Los as one root and Angeles as another. In this case, you must make sure that both words are specified as roots and synonyms to enable the user to find topics for Los Angeles with the search phrase "Los Angeles". When a search argument contains more than one word, the search function uses the words in an and relation to find a match.

The "index-entry-text" of the :ISCH tag contains the topic text as you would like it displayed. The text can be up to 72 characters in length and cannot span two lines. If the text won't fit on the :ISCH statement, place the entire text on the following line.

:ISCHSYN statements create a synonym table that InfoSeeker uses to find a topic match. They are normally placed at the very beginning of the panel group source member. 3 illustrates the format of the :ISCHSYN statement. The ROOT attribute contains a root word that corresponds to a word in the ROOTS attribute of an :ISCH statement. It links the root word to its synonyms.

:ISCHSYN statements create a synonym table that InfoSeeker uses to find a topic match. They are normally placed at the very beginning of the panel group source member. Figure 3 illustrates the format of the :ISCHSYN statement. The ROOT attribute contains a root word that corresponds to a word in the ROOTS attribute of an :ISCH statement. It links the root word to its synonyms.

As mentioned earlier, you normally specify one :ISCHSYN statement for every root word in an :ISCH tag. The synonym list follows the ROOT attribute. There is virtually no limit to the number of synonyms you can specify for a root word. To continue a list, just create another :ISCHSYN statement using the same root word. A synonym can be up to 40 characters in length.

The illustration in 4 will help you understand what you just read. It shows the link between the :ISCH and :ISCHSYN statements. Follow the diagram in the order specified by the numbers. The important thing to see here is that the synonyms are the path to the topic. If you want InfoSeeker to provide search capabilities, you must create index search synonyms. In fact, even if you only want to use the root word for a match, you must specify the root word as a synonym. 4 illustrates this requirement. The CPYF root found in the :ISCH statement is used as a synonym in the :ISCHSYN statement. If the cpyf synonym is left out of the synonym list and the user keys cpyf as a search word, no match is found.

The illustration in Figure 4 will help you understand what you just read. It shows the link between the :ISCH and :ISCHSYN statements. Follow the diagram in the order specified by the numbers. The important thing to see here is that the synonyms are the path to the topic. If you want InfoSeeker to provide search capabilities, you must create index search synonyms. In fact, even if you only want to use the root word for a match, you must specify the root word as a synonym. Figure 4 illustrates this requirement. The CPYF root found in the :ISCH statement is used as a synonym in the :ISCHSYN statement. If the cpyf synonym is left out of the synonym list and the user keys cpyf as a search word, no match is found.

:ISCHSUBT Tag

The :ISCHSUBT tag is used to create index search subtopics. 3 illustrates the format of the :ISCHSUBT statement. The TOPICS attribute contains the help module name or names that are subtopics of the help module in which the :ISCHSUBT statement is specified. It must be specified after the :ISCH tag. Any topic for a help module that contains an :ISCHSUBT tag will contain a '+' character to the left of the topic description when displayed by InfoSeeker.

The :ISCHSUBT tag is used to create index search subtopics. Figure 3 illustrates the format of the :ISCHSUBT statement. The TOPICS attribute contains the help module name or names that are subtopics of the help module in which the :ISCHSUBT statement is specified. It must be specified after the :ISCH tag. Any topic for a help module that contains an :ISCHSUBT tag will contain a '+' character to the left of the topic description when displayed by InfoSeeker.

So, now that you understand the InfoSeeker tag statements, let's create a sample help panel group with InfoSeeker support.

Creating a Sample Panel Group

Our sample panel group contains help information for American states. For brevity, we're including partial information for only two states: California and Nevada. 5 illustrates the topics displayed by our sample panel group in a fully exploded form (the F5=All topics function was used from InfoSeeker). Key the source statements or download them from MC-BBS into a source member of type PNLGRP for panel group member IDX001PG (listed in 6). Then, create the panel group object with the Create Panel Group (CRTPNLGRP) command, as shown at the beginning of the source member.

Our sample panel group contains help information for American states. For brevity, we're including partial information for only two states: California and Nevada. Figure 5 illustrates the topics displayed by our sample panel group in a fully exploded form (the F5=All topics function was used from InfoSeeker). Key the source statements or download them from MC-BBS into a source member of type PNLGRP for panel group member IDX001PG (listed in Figure 6). Then, create the panel group object with the Create Panel Group (CRTPNLGRP) command, as shown at the beginning of the source member.

The source member in 6 gives us a chance to examine the function and interrelationship of InfoSeeker tags more closely. We place the synonym table (the :ISCHSYN statements) for every synonym used by our panel group source at the top of the source member. Although this placement isn't a requirement, it enables us to see and maintain all synonyms for a panel group together, in one place.

The source member in Figure 6 gives us a chance to examine the function and interrelationship of InfoSeeker tags more closely. We place the synonym table (the :ISCHSYN statements) for every synonym used by our panel group source at the top of the source member. Although this placement isn't a requirement, it enables us to see and maintain all synonyms for a panel group together, in one place.

As an alternative, we could split up the synonym table and group synonyms with the help module they relate to. For example, we could place the Nevada synonyms with the Nevada help module and the Nevada cities (Vegas and Carson) synonyms with the NVCities help module.

A long root word list may not leave enough room in the :ISCH statement for a title. Therefore, we have elected to specify the topic title for the index search (:ISCH) statements in the statement immediately after the :ISCH statement in all cases.

Now that we have created a panel group object, we must create a search index for it.

Creating and Working with Search Indexes

Creating a search index is easy. All we do is use the Create Search Index (CRTSCHIDX) command. To create a search index called STATEIDX for our sample help panel group, IDX001PG, key:

 CRTSCHIDX SCHIDX(XXX/STATEIDX) + TITLE('American States') + TEXT('American states search + index') 

Next, we add panel group IDX001PG to the search index with the Add Search Index Entry (ADDSCHIDXE) command like this:

 ADDSCHIDXE SCHIDX(XXX/STATEIDX) + PNLGRP(XXX/IDX001PG) 

If a panel group search index is modified, it must be removed and added back to the index. Otherwise, the modifications won't be recognized. We can accomplish this in one of two ways: with the Remove Search Index Entry (RMVSCHIDXE) command followed by the ADDSCHIDXE command, or with the Work with Search Index (WRKSCHIDX) command.

You should be aware of one restriction. If an index is made up of panel groups that do not contain subtopics (:ISCHSUBT tags), you can't add a panel group that does contain subtopics (:ISCHSUBT tags). The opposite is also true. Just remember that a search index must be made up exclusively of one type or the other.

To start InfoSeeker for the STATEIDX index, just key:

STRSCHIDX SCHIDX(XXX/STATEIDX)

Once InfoSeeker is activated, we can add or remove indexes from a working list of currently active indexes with the More Indexes (F18) function. We can also make a relevant index automatically available for any application display file or user-written command, as we'll learn next.

Linking Search Indexes to Applications

A search index can be linked to an application through a display file or through a command.

To link a search index to a display file, use the DDS keyword HLPSCHIDX at the file level, specifying the qualified search index name in parameter one. (HLPSCHIDX is valid only when at least one HLPPNLGRP keyword is specified in the file.) This activates the InfoSeeker function for every record in the file, displaying F11=Infoseeker at the bottom of the help panels.

If the user presses the F11 key from a help panel, InfoSeeker will start and the search index specified in the HLPSCHIDX keyword will be presented. You do not need to define F11 in your display file.

Linking a search index to a command is done by specifying a qualified search index name in the HLPSCHIDX parameter of the Create Command (CRTCMD) or the Change Command (CHGCMD) command. The HLPSCHIDX parameter is valid only when the HLPPNLGRP parameter is specified.

Supplement Application Help Support

To recap what you should know, here is a summary of how you get InfoSeeker function in your applications.

 o Create a help panel group with index-search capabilities. o Create a search index. o Add the panel group to the search index. o Link desired search indexes to a display file or user-written command. 

The easiest software to work with is software that provides good help support. It's the key to quick learning and getting up to speed with an application. We all know that comprehensive, online help support can eliminate the need for hard-copy manuals.

Supplementing application help with InfoSeeker gives your users an alternative path to the information they need to find. It is one of the best enhancements you can add to your application help.

Richard Shaler is a senior technical editor at Midrange Computing.

References

Guide to Programming Application and Help Displays (SC41-0011, CD-ROM QBKA7902).

New User's Guide (SC41-8211, CD-ROM QBKA9B02).

Empower Help Support

Figure 1 InfoSeeker Search Function

 InfoSeeker Type options, press Enter. (+ indicates an expandable topic) 5=Display topic 6=Print topic 7=Expand topic 8=Compress topic Opt Topic AS/400 System Information _ + Operating System/400 CL commands _ + Operational Assistant _ * Change power on/off schedule (CHGPWRSCD) command _ * Change power on/off schedule entry (CHGPWRSCDE) command _ * Display power on/off schedule (DSPPWRSCD) command _ * Retrieve power on/off schedule entry (RTVPWRSCDE) command _ + Work control _ * Power down system (PWRDWNSYS) command _ + System operator tasks _ + Managing your AS/400 system operations More... Or type search words and press Enter. (* indicates a topic match) power down F3=Exit help F5=All topics F6=Main topics F11=Hide structure F12=Cancel F13=Information Assistant F18=More indexes F24=More keys 
 
 Empower Help Support
 
 Figure 2 Viewing an InfoSeeker Topic
 
 Help Power Down System - Help The Power Down System (PWRDWNSYS) command prepares the system for ending and then starts the power-down sequence. All active subsystems are notified that the system is being powered down; no new jobs or routing steps can be started by any subsystem. For example, jobs that are on a job queue as a result of a Transfer Job (TFRJOB) command are not allowed to complete. During the subsequent initial program load (IPL), they are removed from the job queue and their job logs are produced. Note: If tape units are installed on the system, all tape reels that are on the device(s) should be unloaded before the system is powered down to ensure the integrity of data on the tapes. Note: Do not precede an entry with an asterisk unless that entry is a "special value" that is shown (on the display or in the help information) with an asterisk. How to end (OPTION) More... F3=Exit help F10=Move to top F12=Cancel F13=Information Assistant F14=Print help 
 
 Empower Help Support
 
 Figure 3 InfoSeeker UIM Panel Group Tags
 
 :ISCH ROOTS='root-word-list'. index-entry-text :ISCHSYN ROOT='root-word'. synonym-words :ISCHSUBT TOPICS='help-module-name-list'. 
 
 Empower Help Support
 
 Figure 4 InfoSeeker Tag Statement Linkage
 
 :PNLGRP. __________________ 1. ---------------- ? |||| User keys :ISCHSYN ROOT='CPYF'.cpyf copy file |||| "file" as a ? |||| search word ? ---------------- ?__________________________________ 2. ---------------- |||| Synonym "file |||| points to ROO |||| word "CPYF". :HELP NAME=CPYF. ---------------- ____________________________________ 3. ---------------- ? |||| ROOT word :ISCH ROOTS='CPYF'. Copy File Command |||| "CPYF" is fou ? |||| in help modul ? |||| index search ? |||| tag, :ISCH. ? ---------------- ?________________________ 4. ---------------- |||| :ISCH tag :P. |||| displays Info This is the help text for the help module CPYF. |||| Seeker topic |||| "Copy File |||| Command". :EHELP. ---------------- :EPNLGRP. 
 
 Empower Help Support
 
 Figure 5 American States Search Index
 
 InfoSeeker Type options, press Enter. (+ indicates an expandable topic) 5=Display topic 6=Print topic 7=Expand topic 8=Compress topic Opt Topic American States _ California _ Cities _ Description of Los Angeles _ Description of San Francisco _ Nevada _ Cities _ Description of Las Vegas _ Description of Carson City Bottom Or type search words and press Enter. (* indicates a topic match) _____________________________________________________________________________ F3=Exit help F5=All topics F6=Main topics F11=Hide structure F12=Cancel F13=Information Assistant F18=More indexes F24=More keys 
 
 Empower Help Support
 
 Figure 6 American States Hep Panel Group Source Member IDX0
 
 .*==================================================================* .* To compile: * .* * .* CRTPNLGRP PNLGRP(XXX/IDX001PG) SRCFILE(XXX/QPNLSRC) * .* * .*==================================================================* :PNLGRP. :ISCHSYN ROOT='California'.California CA :ISCHSYN ROOT='California'.wackos babes hunks :ISCHSYN ROOT='Cities'.cities city town village metropolis :ISCHSYN ROOT='Los'.Los Las :ISCHSYN ROOT='Angeles'.Angeles Angel Angels Hollywood :ISCHSYN ROOT='Francisco'.Francisco San Golden Gate Bay :ISCHSYN ROOT='Nevada'.Nevada desert gambling casinos NV :ISCHSYN ROOT='Las'.Las Los :ISCHSYN ROOT='Vegas'.Vegas entertainment gambling :ISCHSYN ROOT='Carson'.Carson City capital :HELP NAME=California. :ISCH ROOTS='California'. California :p. California is situated at the extreme western end of continental United States. Known for its beaches, wackos, babes and hunks. :ISCHSUBT topics='CACities'. :EHELP. :HELP NAME='CACities'. :ISCH ROOTS='CACities'. Cities :P. Major metropolitan areas of California. :ISCHSUBT topics='LosAngeles'. :ISCHSUBT topics='SanFrancisco'. :EHELP. :HELP NAME='LosAngeles'. :ISCH ROOTS='Los Angeles'. Description of Los Angeles :P. This southern city of California is famous for its movie industry. :EHELP. :HELP NAME='SanFrancisco'. :ISCH ROOTS='San Francisco'. Description of San Francisco :P. Northwest city of California. Famous for its Golden Gate bridge. City by the bay. :EHELP. :HELP NAME=Nevada. :ISCH ROOTS='Nevada'. Nevada :p. Nevada is situated in the western portion of continental United States. Known for gambling, entertainment and deserts. :ISCHSUBT topics='NVCities'. :EHELP. :HELP NAME='NVCities'. :ISCH ROOTS='NVCities'. Cities :P. Major metropolitan areas of Nevada :ISCHSUBT topics='LasVegas'. :ISCHSUBT topics='CarsonCity'. :EHELP. :HELP NAME='LasVegas'. :ISCH ROOTS='Las Vegas'. Description of Las Vegas :P. This southern city of Nevada is the gambling capital of the world. :EHELP. :HELP NAME='CarsonCity'. :ISCH ROOTS='Carson City'. Description of Carson City :P. Nevada state capital. :EHELP. :EPNLGRP. 

Also Read

TechTip: Printing from a CL Program (the PRTLN Command)

TechTip: Date Arithmetic in CL Programs

TechTip: Entering Quotes in CL Variables — A Better Way?