Creating Custom Checks
This section describes how to define custom checks in that users can run using the standard interface in .
To define and register a custom check:
1. Set the CUSTMTK_CHECKS_FILE configuration option in the start configuration file to a text file that stores the check definition. For example:
CUSTMTK_CHECKS_FILE text/custmtk_checks.txt.
2. Set the contents of the CUSTMTK_CHECKS_FILE file to define the checks. Each check should list the following items:
◦ DEF_<checkname>—Specifies the name of the check. The format must be CHKTK_<checkname>_<mode>, where mode is PRT, ASM, or DRW.
◦ TAB_<checkname>—Specifies the tab (category) in the report under which the check is classified. All the custom checks are stored in the Miscellaneous category.
◦ MSG_<checkname>—Specifies the description of the check that appears in the lower part of the report when you select the name.
◦ DSC_<checkname>—Specifies the name of the check as it appears in the report table.
◦ ERM_<checkname>—If set to INFO, the check is considered an INFO check and the report table will display the text from the first item returned by the check, instead of a count of the items. Otherwise, this value must be included, but is ignored by .
See
Example 1: Text File for Custom Checks for a sample custom checks text file.
1. Add the check and its values to the configuration file. For an example of how this is done, see the sample code at the end of this section.
2. Register the check from the application.
|
Note:
|
Other than the requirements listed above, custom checks do not have access to the rest of the values in the configuration files. All the custom settings specific to the check such as start parameters, constants, and so on, must be supported by the user application and not . In the custom checks text file, separate options and values for options with a space, not by a tab character.
|
Functions Introduced
The function
ProModelcheckCheckRegister() registers the callback functions for each custom check. The following arguments are available:
• The custom check name. This name must match the name given to the check in the configuration file, and must begin with "CHKTK_".
• The check label. Currently unused; the label is taken from the check configuration file.
• The check options. Currenlty unused, specify the value as NULL.
• The check callback functions, described in details below.
• Labels for the action and update buttons, or specify NULL if these buttons should not be shown.
• Application data to pass to the callback functions.
The check callback functions are as follows:
• The check function (required)—This function, whose signature matches
ProModelcheckCheckFunction(), should calculate the results of the check and provide them to through the function output arguments.
• The action and update functions (optional)—These functions are called when users choose the action or update button when viewing the report. These have the signature of the
ProModelcheckUpdateFunction() function.
• The cleanup function (optional)—Gives your application a chance to free memory allocated by the check function. This has the signature of the
ProModelcheckCleanupFunction() function.
Each callback function receives the following inputs:
• The model being checked.
The function whose prototype matches
ProModelcheckCheckFunction() is used to evaluate the custom defined checks. The user application runs the check on the specified model and populates the following output arguments:
• results_count—Specifies an integer indicating the number of errors found by the check.
• results_url—Specifies the link to an application-owned page that contains information specific to the check.
• results_table—Specifies an array of data for each error encountered that will be shown along with the results.
The function whose prototype matches
ProModelcheckCleanupFunction() is used to release memory allocated for the check callback function.
The functions whose prototypes matches
ProModelcheckUpdateFunction() are used for the following:
• To execute a check-defined action on a given item.
• To automatically update a given item to fix errors, if any.
The selected item’s description string is passed as an argument to the update function.
checks may have one "action" function to highlight the problem, and possibly an update function, to fix it automatically. The following figure displays the report with an action button that invokes the action callback function.
Parent topic