SYSHELP - Active Help System for Your Application

SYSHELP, the Active Help System provided by Predict for your application, consists of the subprogram SYSHELP and the help routines SYSHLP1 to SYSHLP10.

With the rules coded in the help routines, SYSHELP reads information from Predict objects and makes this information available as screen or field online help.

Note:
An extended description can use Long Lines of up to 250 characters. However, if you intend to use extended descriptions with the SYSHELP utility to generate your own online help system, you should limit the line length of your extended descriptions to 72 characters.

This document covers the following topics:


Active Help System of Predict - Overview

Predict provides routines which enable you to use information contained in the abstract or extended description of a Predict object as online help text in your application for screens (referred to in this section as screen help, and for fields (referred to here as field help).

The following information can be displayed as online help:

  • Abstracts and extended descriptions of databases, files, file relations, fields, verifications, systems and programs of type M (Map).

  • Permitted values of verifications linked to a field. Permitted values can be displayed for selection.

Abstracts and verification values are displayed in a window, extended descriptions are displayed full screen.

Online help read from Predict objects can be displayed in two forms:

  • Help on individual input fields (field help) can be displayed by entering a question mark (?) in the field a help routine it is assigned to. See Using Field Help.

  • Help on screens (screen help) can be displayed by pressing PF1 in a map. The abstract and extended description of a Predict Program objects can be used as screen help.

The help screens need not use all of the abstracts or extended descriptions: display can start at any line.

How the Help Facility Works

The Predict help facility consists of the subprogram SYSHELP and the help routines SYSHLP1 to SYSHLP10. SYSHELP retrieves information from Predict objects according to rules coded in the help routines and displays this information as screen help or as field help.

Overview of Help Routines

Help Routine Use
SYSHLP1 Abstract for a field and for linked Verifications
SYSHLP2 Permitted values for verifications. Allows one value to be selected by marking it with the cursor
SYSHLP3 Extended description for verifications
SYSHLP4 Extended description for fields
SYSHLP5 Abstract for programs of type M (map)
SYSHLP6 Extended description for programs of type M (map)
SYSHLP7 Abstract for databases, files, systems
SYSHLP8 Extended description for databases, files, systems
SYSHLP9 Abstract for file relations
SYSHLP10 Extended description for file relations

The help routines delivered with Predict are examples.

Additional help routines must be created when displaying Verification values for several fields with different length. See Using SYSHLP2 to Display Verification Values for Selection.

The parameters contained in the parameter data area SYSHELPA are passed when SYSHELP is called. These parameters determine which information is to be retrieved and how help routines work and are described under Interface to the SYSHELP Subprogram.

How the Help Facility is Delivered

SYSHELP and the routines SYSHLP1 to SYSHLP10 are contained in the library SYSDICH. The following applies to the delivery of the help facility:

  • SYSHELP is delivered as a load module to guarantee an upward compatible interface to Predict. This ensures that your help system will continue to work with the same source code when a new version of Predict is installed.

  • The help routines SYSHLP1 to SYSHLP10 are delivered as source code. These routines are working examples to show the functionality and scope of the Predict help facility. The routines can be modified as desired.

  • The program EXAPGM demonstrates the help facility. Handling of this program is self-explanatory.

Overview of Activities when Using SYSHELP

The following activities are required when using SYSHELP:

  1. The help routine to be used has to be assigned to the map (for screen help) or to the field of a map (for field help). Different help routines are used to deliver different types of information. See Overview of Help Routines.

  2. The Predict object delivering the help text has to be specified. How this is done depends on the type of Predict object. See the respective sections How to specify the field/database/file relation/system/verification object below.

  3. The help routine to be used can be changed to meet specific demands. One option is to move values other than the default settings to variables in the parameter data area SYSHELPA. See Interface to the SYSHELP Subprogram. Help routines may also be rewritten.

  4. When using SYSHLP2 to display selection values, the definition of the variable MAP-VARIABLE has to be changed to the format and length of the input field in the map.

  5. Help routine and map have to be cataloged.

Using Field Help

This section describes the use of text from Predict objects as field help. For a description of using Predict text as screen help, see Using Screen Help .

Assigning the Help Routines

Help routines are assigned to a field of a map with the parameter HE of the Extended Field Editing screen of the Natural map editor.

HE= 'SYSHLPn',=  

SYSHLPn is the help routine to be called where n is a number in the range from 1 to 10.

Note:
See the section Natural Session Parameters of the Natural Parameter Reference documentation and section Natural Help Routines of the Natural Programming Guide for a detailed description of the HE parameter.

Help from Field Objects

Information from Predict field objects is retrieved with the help routines SYSHLP1 and SYSHLP4.

How to Specify the Field Object

File ID and field ID (separated by a period) of the Predict field object to be used must be specified in the input field Field of the Extended Field Editing screen of the map editor. For example: CUSTOMER.NAME for the field NAME in the file CUSTOMER.

SYSHELP moves the values to the variables FILENAME (A32) and FIELDNAME (A32) in the parameter data area SYSHELPA. If only a field and no file is specified, a default file ID in the help routine is used. When SYSHLP1 and SYSHLP4 are delivered, the default file ID is MISCELLANEOUS.

Using the default file ID is especially useful when providing online help information for fields that are not implemented in a file (for example fields that are used for navigating in an application) and the field and file ID cannot be selected from the DDM.

Help from Database, File Relation, System Objects

Information from these Predict objects is retrieved with the help routines SYSHLP7, SYSHLP8, SYSHLP9 and SYSHLP10.

How to Specify a Database, File Relation or System Object

The database, file relation, or system ID of the Predict object to be used must be specified in the input field Field of the Extended Field Editing screen of the map editor.

SYSHELP moves the value to the variable FILENAME (A32) in the parameter data area SYSHELPA.

Help from Verification Objects

Information from Predict Verification objects is retrieved with the help routines SYSHLP1, SYSHLP2, and SYSHLP3.

How to Specify the Verification Object

File ID and field ID (separated by a period) of the Predict field object must be specified in the input field Field of the Extended Field Editing screen of the map editor. If a field is specified without a file, a default file name in the help routine is used. See the respective description for field objects above.

Using SYSHLP2 to Display Verification Values for Selection

SYSHELP will display the abstract/description of all verifications of type T (table) linked to the Field.

The following rules apply when using verification values as online information:

  • Verification values specified in the documentation are displayed. If values in a rule generated from a verification have been changed manually (using the rule editor) this has no impact on the online help derived from the verification.

  • When selecting a verification value for a numeric field, the value must be converted from alphanumeric to numeric. This can be done with the following statement:

    IF HELP-TEXT1 (#HELP) IS (N27)
     COMPUTE MAP-VARIABLE=VAL(HELP-TEXT1(#HELP))
    END-IF
  
  • If Verification values for several Fields of different length are to be displayed, additional help routines have to be created. Copy SYSHLP2 (for example into a new member SYSHLP11) and assign the new help routine to the parameter HE.

  • If Verification values are displayed for selection, line comments can be displayed as descriptive text for the values. These line comments are specified in the field Value of the Add/Modify Verification function and are preceded by /* (a slash and an asterisk). When you select a value, the line comments are not moved to the input field.

Using Screen Help

To use the abstract or extended description of a Predict program object for online screen help, specify SYSHLP5 (for abstract) or SYSHLP6 (for the description) in the field Help of the Define Map setting for MAP screen (the input screen for defining a map profile).

SYSHELP identifies by the implementation pointer the Predict object to be used. The program object with the map name and the library name of the map in the implementation pointer is used.

If no Predict object is found, the STEPLIB name of the map is used as search criterion instead of the library name of the map. If this again fails, the first Predict object with the same member name as the map name is used.

Interface to the SYSHELP Subprogram

The following parameters are passed when SYSHELP is called. These parameters are stored in the parameter data area SYSHELPA.

Parameter Format Output
Input
Description
FIELDNAME A32 I Predict field object identifying the extended description/abstract/verification values to be read. Response code H'FF' will be received if the field does not exist in Predict. Synonyms of fields can be specified. For example: field name synonyms beginning with # can be used for customer-specific naming conventions.
FILENAME A32 I ID of the Predict object to provide the help information. If the field for which help information is required is not a field of a DDM (userview), it can, for example, be described together with other such fields in a special file, whose name can, for example, be the name of the application. If the file name is the name of a dataview that is defined in a data area for a userview, SYSHELP will search using XRef data for the name of the userview and will substitute that name.
VENAME A32 O The name of a verification that is linked to the field. If no verification is found, this parameter is blank. Information-type C must be retrieved first so that Verification-name contains either the name of the first verification or blanks. If information-type T, V or W are retrieved, response-code H'03' indicates that the verification-name contains either the name of the next verification or blanks.
VETYPE A1 O Only verifications of type T (table) will be evaluated.
INFTYPE A1 I
The type of information to be read from Predict. The following values can be specified:
C Abstract of a database
C Abstract of a field of a file
D Extended description of a database
E Extended description of a field of a file
F Abstract of a file
G Extended description of a file
P Abstract of a program of type M (Map)
R Extended description of a file relation
L Abstract of a file relation
Q Extended description of a program of type M (Map)
S Abstract of a system
T Possible values of a verification
V Abstract of a verification of status automatic
W Extended desc. of a verification of status automatic
Y Extended description of a system
STARTLN-OLD N4 I O The first line of help information to be displayed. If no value is specified, display will start with the first line. After the call has been executed, this parameter contains the number of the next line of help information to be displayed. If information-type C or E is retrieved, response-code H'03' indicates that starting-line contains the value 1. If information-type V is retrieved and starting-line contains the value 0, SYSHELP searches for the next verification.
RSP B1 O
Response code:
H'00' O.K. No error
H'01' A wrong type was passed to SYSHELP
H'03' No more information available for object
H'04' No more information of this type is available
H'05' SYSHELP was called without using parameter STARTLN but the description exceeds 9999 lines
H'FF' This object is not described in the dictionary.
HELPINF A240 O The help information taken from a Predict object. If information-type C is retrieved, this parameter contains up to 8 lines of abstract and/or verification values.
If information-type E is retrieved, this parameter contains up to three lines of extended description.
The help information must be translated into a help screen by the user's help routine which calls SYSHELP.
VE-INDEX     Verification indicator. For internal use only.
DESC-UNIQUE-ID     Internal ID of description. For internal use only.
STARTLN N8 I O Same as STARTLIN-OLD but overall number of lines in the description can be up to 99999999. This parameter is optional.

Support for the Structured Mode of Natural

Within a data area, file names can be used which are different from the names of the corresponding DDMs. SYSHELP searches for the correct file name using XRef data.