APPENDIX A - CONTEXTUAL

CONTEXTUAL HELP UTILITY

The contextual help utility makes it possible to enter and change the application's help text in context while running an application.  This allows help text to be entered by users rather than just programmers.  The help text can be displayed with various video characteristics (bold, blink, underline,  or reverse).  A number of commands, statements, and routines are provided in order for the help text editing to work.

SET-UP FOR HELP TEXT EDITING

The following command must be entered at the ACCENT R interactive command prompt, or contained in a Command Module (CM) that is used by the application:

SET @DEFINE.LOGICAL('ACCHELP', 'help_text_ds_name') TO string_variable

This command identifies the name and location of the data set that contains (or will contain) the help text.

If the Data Set (DS) file does not exist, the Help utility will create it in the designated user directory.  A Data Index (DI) file and a Control File (CF) are also created with the same name as the DS.  The DI is used for indexing the help text while the CF is used to allow simultaneous updating while others are accessing it.

The application Process Module (PM) must contain calls to the help routine ACCHP.DO.HELP.  Code Segments (CS) must be INCLUDED from the Help utility in different sections of the PM.  There are eight INCLUDE statements to be used - two of which require parameters to be passed. Each is listed below with explanations as needed.

Enter the following statement in the Control Section of the PM:

INCLUDE ACCHELP.UPDATE.CON FROM CS ACCHELP IN DBL NISUTL:ACCCUST

Enter the following statements in the Declare Section of the PM.  The Help utility's ACCHELP. COMMON.VAR routine requires a parameter which is specified in the WITH clause.  It is a string constant which specifies the maximum number of help text lines to allow for any single help message.  The example below shows a limit of 100 text lines.

INCLUDE ACCHELP.ENTER.VAR FROM CS ACCHELP IN DBL NISUTL:ACCCUST
INCLUDE ACCHELP.COMMON.VAR FROM CS ACCHELP IN DBL NISUTL:ACCCUST &
      WITH '100'
INCLUDE ACCHELP.ENTER.SCN FROM CS ACCHELP IN DBL NISUTL:ACCCUST
INCLUDE ACCHELP.START.ENTER.SCN FROM CS ACCHELP IN DBL NISUTL:ACCCUST
INCLUDE ACCHELP.PAGE.CONTROL.SCN  FROM CS ACCHELP IN DBL NISUTL:ACCCUST

Enter the following statements in the Process Section of the PM.  ACCHELP.ENTER.PRO requires seven string parameters.  These parameters specify the default form settings for the help text window (in order):  begin row, begin column, number of rows, number of columns, text video attribute,  border title, border title location.

INCLUDE ACCHELP.ENTER.PRO FROM CS ACCHELP IN DBL NISUTL:ACCCUST
      WITH '10','10','10','60','@NORMAL','Help Title','top'
INCLUDE ACCHELP.VIEW.PRO FROM CS ACCHELP IN DBL NISUTL:ACCCUST

To allow users the ability to change help text, enter the following statement in the Initial Section of the PM:

1 TO ACCMAKE.HELP:D

The preceding statement  activates the Help Control Menu in the Help utility to allow help text editing.

Enter the help text key in ACCHP.KEY:D and perform ACCH.DO.HELP for each field or menu item that is to have help text editing.  Specify the help text key name in quotes.

"key_name" TO ACCHP.KEY:D

PERFORM ACCHP.DO.HELP

Within FILL layouts, the help key can be specified in the ID statement

ACCHP.DO.HELP.KEYED in the HELP PERFORM statement.

/FIELD 1 4 6 ACCT

/ID 'ACCT_NUMBER'

/HELP

/PERFORM ACCHP.DO.HELP.KEYED

HELP ROUTINE UTILITY

The Help routine utility will generate routines from layouts where help routine names have been specified.  This utility will create a help key string and call ACCHP.DO.HELP.  It will save time from having to enter the routines manually.  Enter the following command:

USE CM GENERATE.HELP.RTNS IN DBL NISUTL:ACCUST

This utility will prompt for the object name and type where the layouts are located.  It will produce a System File (SF) with all the needed routines.  The keys are named according to the routine name called in the menu and form layouts.  Enter the following command in the desired Data Base Library (DBL) to generate the needed Code Segment (CS) from the SF

USE SF HELP.RTNS

The CS is named HELP.RTNS.  This segment needs to be INCLUDEd in the application PM(s) in the Process Section.

INCLUDE HELP_RTNS  FROM CS HELP_RTNS [IN DBL dbl_name]

HELP TEXT EDITING

While in an application, when a question mark is entered, the Help utility is invoked.  The Help Control Menu will appear with three options if ACCMAKE.HELP has been set to 1.

The help display window can page forward or backward if there are multiple pages of text (see the following example).  Select EXIT to return to the Help Control Menu.

The Help edit window allows both the form and the text of the help display window to be modified.  Form modification involves the starting row and column, the number of rows and columns, text video attributes, border video attributes, help window title and placement.  The form elements are placed at the top of the edit window.  The cursor is placed in the first form element initially.  The text edit window does not appear until <CTRL>Z is typed.  The Action Menu has seven options:

Press <PF2> for help text on an item in the Action Menu.  The item must be highlighted at the time.

 

Type <CTRL>^ (Control key + Shift 6) while in the Text Edit window to view the list of edit control keys.  This display overlaps the form elements.

EQUATED COMMANDS

The following is a list of equated commands that are available with the Help utility.