Creating user information

This section provides information on how to create various types of user information within your PATROL KM, such as messages, context-sensitive help panels, product expert advice, product help systems, and end-user guides. The following topics are discussed:

What is user information?

User information that is built within a PATROL KM falls into three main categories:

Messages printed to the PATROL Console window or dialog box
Context-sensitive help panels activated by a Help button
Expert Advice panel for a PATROL Event Class activated by a Expert Advice button

User information typically thought as "product documentation" includes:

Help system
User Guide

User information objectives

Each of these types of information provide a mechanism to communicate knowledge back to the PATROL KM product end-user. Therefore, keep in mind your end-user's needs when generating this information. Here are some recommendations when generating user information.

For messages

Use the PSL pri ntf() function to print messages to the system output window or to the selected dialog box.
Make sure your messages truly fall into the appropriate message class such as information, warning or error.
See recommendations for error messages.

For context-sensitive help panels

If you have defined a Help button within your PSL code, make sure that an associated context-sensitive panel has been defined.
Test the panel after your Help file has been bundled in the product.
Make sure that the name displayed in the product has the same name displayed in its Help panel (for example, the parameter name that is displayed on its icon is the same name that is displayed in the Help panel).

For expert advic e on event class panels

If you have defined your own event class and have defined a Expert Advice button, complete the Expert Advice screen by using the Expert Advice tab. For more information, refer to Adding an event class to an application.

For a help system

For UNIX PATROL Console Help, you must have a NetHelp file.
For Windows PATROL Console Help, you must have a WinHelp 32-bit .cnt and .hlp file.

For User Guide documentation

Make sure you have informed the user of all the necessary prerequisite requirements and have included step-by-step instructions for setup and configuration for the PATROL KM.
Make sure you have included adequate information about the components of the PATROL KM such as application classes, menu items, parameters, and InfoBoxes.

Error message recommendations

All error messages for the PATROL KM should be logged to the PATROL Console output window.

Note

All error messages should be documented in an appendix of the PATROL KM product's user reference manual.

Parameter, menu command, and discovery messages should have the following output formats:

ERROR: date/time application instance parameter message

ERROR: date/time application instance menu_command message

ERROR: date/time application instance discovery message

Field	Definition
date/time	Character string indicating the date and time the message was produced. The date/time has the following format: Wed Apr 12 09:47:44 1995. The date/time value can be obtained by executing the following PSL statement: `asctime(time());.`
application	Name of the PATROL KM application that generated the error message.
instance	Name of the PATROL KM application instance that produced the error message.
parameter	Name of the PATROL KM application instance parameter that produced the error message.
menu_command	Name of the PATROL KM application instance menu command that produced the error message.
discovery	Name of the PATROL KM application instance discovery procedure that produced the error message.
message	Character string that explains the error that occurred.

More information on creating user information

For more details about how to generate the various categories of PATROL KM user information see the following:

Topic	Source
Messages	Refer to the PATROL Script Language Reference Manual printf() function.
Expert Advice panel for an Event Class	Refer to Adding an event class to an application.