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:
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.
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.
| 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.
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.
The following activities are required when using SYSHELP:
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.
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.
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.
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.
Help routine and map have to be cataloged.
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 .
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.
Information from Predict field objects is retrieved with the help routines SYSHLP1 and SYSHLP4.
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.
Information from these Predict objects is retrieved with the help routines SYSHLP7, SYSHLP8, SYSHLP9 and SYSHLP10.
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.
Information from Predict Verification objects is retrieved with the help routines SYSHLP1, SYSHLP2, and SYSHLP3.
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.
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.
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.
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 |
|
||||||||||||||||||||||||||||||||
| 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 |
|
||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||
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.