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.
- 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.
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
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:
Name of the PATROL KM application that generated the error message.
Name of the PATROL KM application instance that produced the error message.
Name of the PATROL KM application instance parameter that produced the error message.
Name of the PATROL KM application instance menu command that produced the error message.
Name of the PATROL KM application instance discovery procedure that produced the error 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:
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.