annotate()
Provides contextual information for a PATROL parameter.
Syntax
Parameter
Parameter | Definition |
|---|---|
parameter | name of the parameter for which annotation information is specified The parameter name can be an absolute path name, or a path name relative to the current or other parameter name. If you are using the %Text or %InfoBox formats you can specify the NULL string "" or ".", and the annotate() function uses the current parameter name or the parameter name for which the current recovery script is running. However, if you are using the %Response format, you must specify parameter. |
format | mnemonic indicating the type of display for the specified annotation information For more information, seeSpecifying the annotate() Function Output Format. Valid Values
Default %Text |
datan | One or more optional text strings that specify the annotation information. The datan parameters are interpreted differently depending on format . |
Description
The annotate( ) function instructs the PATROL Agent to save information represented by datan for parameter in the history database for later viewing as format.
The annotate() function allows a Knowledge Module to annotate a parameter value with contextual information that allows a user to easily identify the cause of an unusual condition. The additional information, represented by the datan parameter, is stored historically in the PATROL Agent history database and is subsequently viewable from the PATROL Console, from a PSL script, or through archiving.
The PATROL Console can view annotation information for the current parameter value or historical values. The PATROL Console accesses the annotation information using drill-down on data points or options (depending on the context). The annotation information is presented either as plain text, a PATROL InfoBox, or as a PSL response() function dialog.
Annotation and History Retention
The PATROL Event Manager/Agent retains annotations for the same duration as the parameter values that they accompany. Annotations are kept in the history database using the usual history retention settings in the Knowledge Module and PATROL Agent configurations. Annotations are purged when the accompanying parameter value is purged. Thus, when specified, every data point retained in the history database has an accompanying annotation.
The annotate() function succeeds even when the history retention is zero because it stores the current annotation in memory with the current parameter value. There is no need to pretext the value of the history_get_retention() function before calling the annotate() function. In this case, however, multiple annotations are not stored, nor are annotations persistent.
annotate() Return Codes
If successful, the annotate() command returns the NULL string and sets the PSL variable errno = 0 (E_PSL_NO_ERROR). Upon failure, the annotate() function returns the NULL string, can return the message FAILED to the computer icon display window, and sets the PSL variable errno .
The annotate() function return value lends itself to the usage:
if (ann_return)
{
print("Error from annotate() : ",ann_return,"\n");
}
The following are specific annotate() function error conditions.
Cannot find runtime object
The annotate() function returns the message Cannot find runtime object and sets errno = 103 (E_PSL_NO_RTCELL) when parameter does not exist or is not a parameter object.
annotate is called before any data point generated
The annotate() function returns the message Annotate called before any data point generated and sets errno = 115 (E_PSL_ANN_TOO_EARLY) when it attempts to annotate a parameter that has not yet stored a value. This can occur when the annotate() function is called before a set() function can set the parameter value.
Cannot save annotation information
The annotate() function returns the message Cannot save annotation information and sets errno = 116 (E_PSL_ANN_SAVE_FAILED) when an attempt to save the annotation data fails. This can be caused by permission restrictions on the history database. This error can also be the result of an internal PATROL error.
Specifying the annotate() Function Output Format
The annotate() function format parameter specifies the style of the annotation output on a PATROL Console and determines how the annotate() function interprets the datan strings.
Plain text output
When format = "%Text" or format = ""is specified, the annotate() function treats the datan annotations as a single string of text in a text editor window. Each datan can be a multi-line string containing newline (\n) characters. The format = "%Text" option is useful for displaying long results such as command output or error log files.
The following example creates a plain-text annotation:
When this annotation is viewed on a PATROL Console, a plain-text dialog box is displayed.
PATROL console InfoBox output
When format = "%InfoBox" is specified, the annotate() function treats the datan annotations as PATROL console InfoBox item strings in the form "tagn\nvaluen" where tagn is the InfoBox item label and valuen is the InfoBox item label.
The following example creates an InfoBox annotation:
When this annotation is viewed on a PATROL console, the following InfoBox dialog box is displayed.
PSL response() Function Dialog Output
When format = "%InfoBox" is specified, the annotate() function treats the datan annotations as PSL response() function element definitions. (For more information about the response() function element definitions, see response().) The response() function dialog generated by the annotate() function is read-only.
The following example creates a response() function annotation:
When this annotation is viewed on a PATROL console, the following response() function dialog box is displayed.
