The CP-6 system provides a comprehensive HELP foci I ity for display of information stored in a central location. HELP is used primari Iy to provide quick reference information on system or user processors. HELP messages for a each processor are stored in a separate database which may be avai lable throughout the system and capable of being utilized to produce other forms of documentation.
To respond to a HELP command, a processor may cal I the X$HElP library service, which in turn parses the parameters of the HELP command and cal Is the U$HElP monitor service.
X$HElP isolate. the cal ling processor from the complexities of M$HElP and provides uniform handling of HELP commands by all processors.
4-32 MSHElP - HELP Wessage Reporting CE74-00
FILE OF HELP MESSAGES
The fi Ie of HELP messages is a keyed file created by HERMAN.X. The fi Ie typically contains the fol lowing:
o Abstract describing the processor and how to request further HELP. There may be breaks between increasingly detailed levels of information within the abstract.
o Topics describing the major topics of interest concerning a processor. Each topic is assigned a keyword.
o Subtopics containing information related to the previous topic. A subtopic that is assigned a keyword is a message that can be obtained by a specific request naming the keyword and the topic that it is under. A subtopic without a keyword creates a break between levels of messages related to a topic.
o Synonyms providing alternate ways to request a topic or subtopic.
For an explanation of how to cleate a HELP message fi Ie, refer to the CP-6 Programmer Guide.
MSHElP
The caller of M$HElP normally specifies the processor name (PROCNAME) and optionally, the account and password. Based on this information M$HElP determines which HELP file to read. The form of the filename is HELP:name:l. Name is the processor name
(PROCNAME) passed by the caller and I is the optional native language byte from the JIT.
The account for a HELP message fi Ie defaults to :SYS.
The caller must also specify a buffer (BUF) to receive the text and an area (RESULTS) to receive status information. The RESULTS area is generated by invoking the VlR_HElP macro.
MSHElP provides two categories of functions: (1) obtaining HELP messages and (2)
I isting information about HELP. To obtain HELP messages the fol lowing parameters apply:
KEY1. KEY2. RANGE. ALL. MORE. SUBTOPIC. SUBSTOPIC; LIST-NO. the default. must be taken.
The fol lowing functions may be requested by using the parameters indicated:
o Access al I messages for a range of topics (RANGE-YES; KEY1, KEY2 are meaningful).
o Access first level message for a topic specified by keyword (i .e., KEY1; SUBTOPIC is meaningful).
o Access first level message for a sUbtopic specified by keywords (i.e., KEY1 identifying the topic, KEY2 identifying the subtopic; SUBTOPIC and SUBSTOPIC are meaningful).
o For a previously requested topic or subtopic. access the next level message (MORE-YES; RESULTS area which must be unchanged since previous cal I to M$HElP indicates how much information has already been displayed).
o For a previously requested topic or subtopic. access the remainder of messages for that topic (ALL-YES; RESULTS area which must be unchanged since previous call to MSHElP indicates how much information has already been displayed).
The SUBTOPIC and SUBSTOPIC parameters permit the caller to request use of a default or substitution message if the requested message cannot be found. If SUBTOPIC-YES and MSHELP cannot find the requested keyword, M$HELP supplies the default message
(abstract). If SUBSTOPIC=YES and if KEY2 is specified but KEY2 cannot be found, M$HELP re-accesses the HELP message fi Ie, disregarding KEY2, to obtain a substitute message.
In these cases, the RESULTS area indicates that the original request was met with a default or substitute message.
CE74-80 M$HELP - HELP Message Reporting 4-33
After the text is read into the buffer, M$HELP performs output if the user suppl ied OUTDCBl and OUTDCB2 parameters. The discussion of the BUF parameter describes how the output function is performed. If no DCBs are specified and the buffer is large enough to contain the text requested, M$HELP returns so that the caller may perform the output operation.
On return to the caller, the RESULTS area reflects the status of the service cal I. On a normal return, the RESULTS area contains information to allow a subsequent call for M$HELP to respond to the timesharing user's entry of ? (MORE=YES) or ?? (ALL-YES).
The alternate return is taken in the following situations:
if no OUTDCBs are specified and the buffer is too smal I to contain the text requested;
if OUTDCBl or OUTDCB2 is specified and output cannot be completed through either DCB (M$HELP performs correspondence checking and also verifies that the OUTDCBs are actually DCBs) and the buffer is too smal I to contain the requested test; if there are database errors, or if bad parameters are passed. Information in the RESULTS area and TCB
indicate the reason for the alternate return.
To I ist information about the avai lable HELP messages, the caller of M$HELP specifies a buffer and RESULTS area. These functions may be requested by using the additional parameters indicated:
o List processor names that provide HELP (LIST=YES, PROCNAME= NIL; PROCACCT, KEY1, KEY2, and RANGE are meaningful).
o List TOPICS (i.e., topic keywords) for a specific processor requested by range or by (possibly) truncated keyword (LIST=YES; PROCNAME, PROCACCT, RANGE, KEY1, KEY2 are meaningful).
This I ist of processor names or keywords is presented to the user in the same way that the message text is presented.
The form of the cal I for this service is as follows:
CALL M$HELP (FPT_HELP) [ALTRET (label)];
The parameters for this service are as fol lows:
ALL
=
IYESINOI indicates, if YES, that al I remaining HELP on the current topic is to be output. This is valid only for HELP text (LIST = NO). The default is NO.BUF = VARIABLE specifies the buffer used when reading the fi Ie of help messages. BUF must have a minimum size of 79 bytes, the maximum size of any record in the fi Ie.
Because the text requested may consist of multiple records in the fi Ie, a 79-byte buffer wi I I not always be large enough to hold the whole message. The caller may alleviate this condition by specifying a larger buffer.
Records from the fi Ie are read into the buffer at 79-byte offsets until the buffer is full or the message is complete. Status is returned to the caller indicating how may records are in the buffer, and whether or not the message is complete. If the buffer is not large enough to hold al I of the records of the message, then the contents of the buffer wi I I vary depending on whether the caller supplied OUTDCBs through which to output the messages. Given a buffer with enough space for n records, if no OUTOCBs have been specified, the buffer wi I I contain the first n records of the message. If OUTDCBs have been specified, then the buffer wil I contain the first n-1 records in the first n-1 slots, and the last record of the message in the nth slot.
EXAMPLE:
Suppose the user posses a 237-byte buffer and tries to read varying size text.
4-34 M$HELP - HELP Message Reporting CE74-00
1. 2-record error text.
PROCPSN
=
VARIABLE locates a six-character area containing the packset of the processor for which HELP is requested.RANGE
=
IYESINOI is used in combination with KEY1 and KEY2 to set I imits on the data output. If RANGE is YES, KEY1 and KEY2 are to be used as inclusive I imits on a range ofitems to display. If RANGE
=
NO and LIST = YES, KEY1 may be provided as a wi Idcard; in this ease, any item in the display list that starts with the keyword is printed. If RANGE=
NO and LIST = NO, the keywords are used to select a single message by topic and sUbtopic. The default is NO.RESULTS
=
VARIABLE locates a VLR_HELP area passed by the user where status information about the cal I to M$HELP is returned. Because this also contains scratch area for M$HELP, it is required for callers who wish to use the MORE or ALL functions or do their own output.SUBSTOPIC
=
IYESINOI indicates whether or not to use a substitute message (i .e., the one that would have resulted if KEY2 were not passed) if M$HELP is unable to find thespecified one. SUBSTOPIC
=
YES is val id only when LIST=
NO and RANGE=
NO. The default is YES.SUBTOPIC
=
IYESINOI indicates whether or not to use the default message if the requested topic does not exist. The default is NO.XLATEKEY
=
IYESINOI indicates, if YES, that the user wishes M$HELP to translate the passed KEYWORDs into upper case and try again if a message isn't found the first time.The default is YES.
The VLR_HELP macro generates on area which receives the results of the M$HELP. The area contains these fields:
ALTMSG
=
VALUE-BIT(l) if set means that M$HELP stored a substitute message in the user buffer.BADCAll
=
VAlUE-BIT(l) if set specifies that the col I contained one or more i I legal parameters.BUFERR = VAlUE-BIT(l) if set specifies that the buffer is not there or bod.
ERRCOOEl specifies the error code for OUTDCB1, in the normal format for monitor service errors.
ERRCOOE2 specifies the error code for OUTDCB2, in the normal format for monitor service errors.
INERR = VAlUE-BIT(l) if set specifies error on reading the message.
MSGCOMP
buffer. VAlUE-BIT(l) if set means that the entire message is stored in the user NNATIVE = VAlUE-BIT(l) if set means that the returned message is not in the user's native language.
NOFIlE
=
VAlUE-BIT(l) if set specifies that MSHElP was unable to open the message file.NOMSG - VAlUE-BIT(l) if set means that MSHElP was unable to find any message for the error code.
OUT ERR 1 VAlUE-BIT(l) if set specifies an error on OUTDCB1.
OUTERR2 - VAlUE-BIT(l) if set specifies error on OUTDCB2.
RECCNT - VAlUE-DEC(0-n) specifies a count of records read into the user buffer.
4-36 CE74-00