history()

Return history information from the PATROL history database.

Syntax

history([parameter],[format],[number])

Parameter

Parameter

Definition

parameter

name of the object whose history is returned*Valid Values*

  • an absolute path (/APP/INST/PARAM )
  • a relative path (/DIFFERENTINST/PARAM )
  • "" or "." for the current parameter

Default 

current parameter|

 

format

optional character string inside double quotation marks that specifies the format of each history() function entry*Valid Values* 
n return the number of available data points as the first value in the return list 
t include the time stamp of each entry in the return list 
v include the value of each history entry in the return list*Default* 
ntv

number

optional numeric value that limits the number of entries the history function will return*Default* 
50

 

Description

The history() function accesses the parameter history database and returns a list containing the number of data points available followed by a number of entries. 

The history() function returns the empty string, produces a run-time error, and sets the PSL errno variable if a bad format character is provided. 

Because of the defaults provided in the history() function, the following function specifications are equivalent:

history(parameter)
history(parameter,"ntv",50)

 

History Output Format

The history() function will return any of the following formats, depending on which format flags are set: 

  • number_entries \n if the n flag is set
  • value \n, time \n, or value time \n if the v, t, and vt flags are set 

The history() function separates the values of an entry with spaces and successive entries with new-line characters. 

You can use the nthline( list1 ) function to get the number of points from the head of the list and also to extract the entries. Entries can be split if necessary into time and data values using the ntharg() function. The entries will be single values if either the t or v flag is absent.

Example

The following PSL statements return history information for the MEMPageOut parameter from the PATROL history database:

history_information = history("/MEMORY/MEMORY/MEMPageOut","ntv");
number_of_points = trim( nthlinef(history_information,"1"), "\n");
history_points = nthlinef(history_information,"2-");
printf("Number of points %d\n",number_of_points);
printf("History points:\n%s\n",history_points);

history(parameter)history(parameter,"ntv",50)