|
Manual page for available_functions(PL)
DESCRIPTION
Functions may be used within ploticus scripts to return
values for assignation to variables.
They may also be used within conditional expressions.
SYNTAX
Function names always start with a dollar sign ($).
In the following summaries, the function name appears along with a
template for arguments that must be supplied.
Embedded spaces are not allowed anywhere within the function call structure.
Some examples of the syntax used with functions in ploticus scripts:
#set RESULT = $todaysdate()
would set the variable RESULT to hold todays date (in the default notation).
select: $inrange(@3,Y) = 1
(a select condition) would select data rows where field 3 is within the defined
range of Y.
DETERIMINING IF DATA IS IN RANGE FOR PLOTTING
$inrange(value,axis) (or $inrange(value,axis,loval,hival)
This is useful in rejecting data that are completely out of the plotting area.
Returns 1 if value is in plottable range for the given axis.
If not, 0 is returned.
The full range of the axis (as defined in proc areadef) is assumed,
unless loval and hival are given.
Example: (see above).
LOOPING THROUGH A SET OF CATEGORIES OR ROW STUBS
$nextstub(maxlen)
Returns the text of a defined category or pltab row stub.
Usually called multiple times within a #loop;
the result is used to build an expression to
select data rows.
The first time it is
called, the first category or row stub text will be returned; second
time, the second category or row stub text will be returned, and so on.
The length will be limited to maxlen.
Any embedded spaces will be converted to underscores.
Example: #set S = $nextstub(5)
A gallery example where this is used is
caselist
ACCESSING A FIELD FROM THE CURRENT DATA SET
$dataitem(row,field)
Returns the contents of the data item in the requested row and field.
Rows are specified by number and the first row is 1.
Fields may be specified by number (first=1) or name.
Example: #set S = $dataitem(1,rate)
CONVERTING FROM DATA SCALE TO ABSOLUTE UNITS
$data_to_absolute(axis,value)
Returns the absolute location of a value in data units (numeric, date, time, etc.).
ARITHMETIC / NUMERIC PROCESSING
$arith(exp)
Arithmetic expression evaluator. Unary plus/minus are allowed.
Evaluation is strictly left to right; no parens may be used.
Does not allow non-numeric operands or malformed arithmetic expressions.
Example: #set RESULT = $arith(2+8/5) (result: 2)
Example: #set RESULT = $arith(2+-8) (result: -6)
$arithl(exp)
Same as $arith() except
lazy, i.e. non-numeric operands
are accepted and treated as if they were 0.
$max(a,b,c,..)
Find the greatest value amongst the supplied arguments
and return it. Any number of arguments (1 or more) may
be used. (This function added in version 1.35)
Non-numeric or zero length arguments will be skipped.
Example: #set MAX = $max(24,9,33) (result: 33)
$isnumber(s)
Returns 1 if s is a valid number, 0 if not.
Example: #set RESULT = $isnumber(-0.24) (result: 1)
Example: #set RESULT = $isnumber(=) (result: 0)
$formatfloat(x,fmt)
format x using
printf-style
format string fmt.
Example: #set RESULT = $formatfloat(3.4425,%3.2f) (result: 3.44)
STRING PROCESSING
$exists(value) = test value to see if it is non-missing and
has a length greater than 0.
Convenient to see if a variable has a value, without worrying about embedded
spaces or whether missing data codes are present or hidden.
$exists() and $notexists() are different
from all other functions in that the argument may contain embedded
white space, and in their syntax (see example).
They may only be used in #if statements, and may not be
logically ANDed or ORed with other expressions.
Example: #if $exists(@USERVAR)
$notexists(value) = opposite of $exists() (see above).
$change(s,t,string)
change every occurance of character s to t
in string. The special symbol space may be used
for t to get spaces (necessary since spaces not allowed in
function call constructs).
Example: #set RESULT = $change(_,~,Hello_world) (result: Hello~world)
$char(n,string)
get the nth character of string (first is 1).
Example: #set RESULT = $char(3,ABCDEFG) (result: C)
$lowerc(string)
lower-case equivalent of string.
Example: #set RESULT = $lowerc(HELLO) (result: hello)
$padr(len,string)
pad the right end of string to a length of len
with underscores (which are displayed as blanks).
Example: #set RESULT = $padr(10,hello) (result: hello_____)
$strcat(s,t)
concatenate strings s and t
Example: #set RESULT = $strcat(ABC,XY) (result: ABCXY)
$strlen(s)
get length of string s. Zero length strings are permissible.
Example: #set RESULT = $strlen(hello) (result: 5)
$substring(s,from,nchar)
get a substring of s
Example: #set RESULT = $substring(abcde,3,99) (result: cde)
Example: #set RESULT = $substring(abcde,-2,99) (result: de)
Example: #set RESULT = $substring(abcde,1,2) (result: ab)
$upperc(string)
get the upper-case equivalent of string
Example: #set RESULT = $upperc(Hello) (result: HELLO)
LIST PROCESSING
These functions operate on a string which is in the format
of a comma-delimited list. This may be used in a limited way
to work with vectors, since there are no arrays in ploticus scripts.
$count(str,list)
count the number of times str appears in
list. list is a comma-delimited list.
Example: #set RESULT = $count(hello,aba,gabba,jabba) (result: 0)
Example: #set RESULT = $count(x,x,y,x,y,y,z,x) (result: 3)
$nmember(n,list)
get the nth member of list.
list is a comma-delimited list.
Example: #set RESULT = $nmember(2,a,b,c,d,e) (result: b)
DATES
Individual scripts may set the current date format as needed
using $setdatefmt(). The date format is also set when specified
in a proc areadef scaletype attribute.
Unless otherwise specified, these functions expect date arguments
to be in the current date format.
$formatdate(date,newformat)
Return date, formatted to newformat.
Example: #set RESULT = $formatdate(062698,yyyymmmdd)
$setdatefmt(format)
set the current date format. Available date notations
are described in
dates
Example: #set STATUS = $setdatefmt(yyyymmdd)
$defaultdatefmt()
reset the current date format to the project default.
Example: #set STATUS = $defaultdatefmt()
$todaysdate()
return the current date. It will be in the
date format currently in effect.
Example: #set RESULT = $todaysdate()
$daysdiff(date1,date2)
return the difference in days between
date1 and date2.
Example: #set RESULT = $daysdiff(011298,010198) (result: 11)
$dateinrange(testdate,earlydate,latedate)
return 1 if
testdate is within interval (exclusive) defined by
earlydate and latedate. Otherwise 0 is returned.
Example: #set RESULT = $dateinrange(011298,010198,063098) (result: 11)
$daysdiff_m(date1,fmt1,date2,fmt2)
same as daysdiff() but the two
dates may be in any supported format.
Example: #set RESULT = $daysdiff_m(011298,mmddyy,1998jan01,yyyymmmdd) (result: 11)
$dateadd(date,ndays)
return a date resulting when
ndays are added to date.
Example: #set RESULT = $dateadd(010198,11) (result: 011298)
$weekday(date)
return the day of the week (a three-character abbreviation)
corresponding to date.
Example: #set RESULT = $weekday(022098) (result: Fri)
$yearsold(birthdate,testdate)
return the integer age in years as of
testdate of a person born on birthdate.
(This can be used for objects other than people of course.)
Example: #set RESULT = $yearsold(062661,022098) (result: 36)
$setdateparms(parmname,value)
set a date-related profile parameter.
May be used to set either the pivot year, or to allow lazy dates.
A pivot year is used to accomodate two-digit year values.
A lazy date has 00 as the day and/or month portion and is usually
used in situations where the day and/or month is unknown or unavailable.
Example of setting the pivot year: #set STATUS = $setdateparms(Pivotyear,90)
Example of allowing lazy days: #set STATUS = $setdateparms(Lazydates,days)
Example of allowing lazy days and months: #set STATUS = $setdateparms(Lazydates,both)
TIMES
$time()
get current time in hh:mm:ss format.
Example: #set RESULT = $time()
$timesec()
get number of seconds since midnight for the current time.
Example: #set RESULT = $timesec()
$minutesdiff(time1,time2)
return number of minutes between two hh:mm
times from the same day. Times may include :ss (seconds) but these are truncated
before the arithmetic is done.
Example: #set RESULT = $minutesdiff(15:20,14:55) (result: 25)
MISCELLANEOUS
$system(command)
execute the given shell command.
Any spaces within the command should be represented as single quotes (').
Result is the first line of standard output produced by the command,
without trailing newline, and with any spaces converted to underscores.
Example: #set RESULT = $system(myprog'488)
$validate(val,datatype)
return 1 if val conforms to the
given datatype, 0 if not. Single quotes (') must be used to represent spaces
in datatype. Datatypes include: date.
Example: #if $validate(@INDATE,date) == 1
LIMITATIONS AND BUGS
Function calls cannot contain embedded white space.
Function calls may not be nested.
|
 data display engine
Copyright Steve Grubb
|