annotate_get()

Return the annotation text for a parameter value.

Syntax
Parameter
Description

Syntax

annotate_get( parameter ,[ timestamp ] )

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 specify the NULL string "" or the string ".", the annotate() function uses the current parameter name or the parameter name for which the current recovery script is running.
timestamp	string that identifies the timestamp of the desired annotation The timestamp is the timestamp of the set() function that set the parameter value and not the timestamp of the annotate() function that created the annotation. The timestamp is the number of seconds that have elapsed since 00:00:00 GMT, Jan 01, 1970. The timestamp of the data points for a parameter can be obtained with the PSL history() function. Default If the timestamp parameter is omitted, the most recent data point for parameter . (This may not be the same as the most recent call to the annotate() function as there may have been another data point stored by a set() function.)

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 specify the NULL string "" or the string ".", the annotate() function uses the current parameter name or the parameter name for which the current recovery script is running.

timestamp

string that identifies the timestamp of the desired annotation The timestamp is the timestamp of the set() function that set the parameter value and not the timestamp of the annotate() function that created the annotation. The timestamp is the number of seconds that have elapsed since 00:00:00 GMT, Jan 01, 1970. The timestamp of the data points for a parameter can be obtained with the PSL history() function.

Default
If the timestamp parameter is omitted, the most recent data point for parameter . (This may not be the same as the most recent call to the annotate() function as there may have been another data point stored by a set() function.)

Description

The annotate_get() function returns the annotation for the parameter value at timestamp. The annotate_get() function is designed for the more advanced uses of the annotate() function, such as those that require verification of whether an annotation already exists.

Return Values

If successful, the annotate_get() function sets the PSL variable errno = 0 (E_PSL_NO_ERROR) and returns the annotation string that consists of the data arguments specified in the annotate() function that created the annotation. There are three types of strings that the annotate_get() function will return.

Plain-Text Annotation Text

If the annotate() function created a plain-text annotation the annotation is returned in a form similar to the following text:

\Sample Annotation with Plain Text\

InfoBox Annotation Text

If the annotate() function created a plain-text annotation the annotation is returned in a form similar to the following text:

%InfoBox\Tag1 Value1 \Tag2 Value2 \Tag3 Value3 \Tag4 Value4 \Tag5 Value5\

response() Function Text

If the annotate() function created a response() function annotation, the annotation is returned in a form similar to the following text:

%Response \Sample Annotation\-1\h=100
  w=100
  b=Patrol
  e=1
  o=Accept
  c=Cancel
  N=0
  A=0
  B=0\16
\2\1
  Sample Annotation Text\

Errors

The following are specific annotate_get() function error conditions.

Invalid or Non-parameter Object

The annotate_get() function returns the NULL string and sets errno = 103 (E_PSL_NO_RTCELL) when the parameter does not exist or is not a parameter object.

No Annotation for Parameter

The annotate_get() function returns the NULL string and sets errno = 105 (E_PSL_ANN_NO_HISTORY_RETENTION) when parameter is valid but

timestamp is omitted and no annotations exist for any value of parameter in the PATROL Agent history database
timestamp is specified and no annotation exists for the value of parameter at timestamp

Note

If you specify the NULL string for the timestamp parameter, the annotate_get() function sets the errno value to 105 because no timestamp matches the NULL string. Omit the timestamp parameter if you want to obtain the annotation of the last data point for a parameter.