Ploticus > Scripts >

Categories of available functions:



A number of functions are available for use in ploticus scripts and proc getdata filters , for a wide range of purposes including processing of arithmetic, strings dates, times, commalists , and so on. Functions usually take one or more arguments and return a value. Functions may be used with #set , #call or as operands in #if/#elseif conditional expressions .

Custom functions may be coded and added to the file custom.c, and accessed like any of the built in functions, except that the names of custom functions should begin with a double dollar sign ($$) when invoked from scripts.


Function names always start with a dollar sign ($). Function arguments are enclosed by parentheses and if more than one argument, separated by commas (,). For example:
    $formatfloat( @NUM, "%7.2f" )

Function calls may not be nested, ie. function arguments may not be functions.

In the following summaries, the function name appears along with a template for arguments that must be supplied.


Note: the functions in this section may be used with a double dollar sign ($$) for faster function name search. Because of the way ploticus script files are parsed, #endproc should be used to terminate any #proc previous to these function calls, so that the proc executes before the function call.

$inrange( value, axis ) or
$inrange( value, axis, min, max )

    Return 1 if value within a range on the given axis. min and max are optional; if given they determine the range. If they are not given the range is the range of the axis within the plotting area.

$icolor( i )

    Return one of 20 preselected colors. The color sequence was selected to give good contrast between nearby entries. i allowable range is 1 to 20; values out of this range are modulo into range.
    Example: #set COLOR = $icolor( 2 )

$fieldname( n )

    Return the field name assigned to field n. First is 1. If no field name was defined, noname is returned.

$dataitem( row, field )

    Return the contents of the item in row and field of the current data set. row is a number, first is 1. field is either a number or an assigned name.

$defaultinc( min, max )

    Return a reasonable increment given numeric min and max, using the same algorithm used with axis stub increments.
    Example: #set inc = $defaultinc( 0, 200 )

$changeunits( axis, newunitspec )

    Change the scaling units associated with an existing axis.
    Example: #call $changeunits( x, "date nqyy" )

$squelch_display( mode )

    #call $squelch_display( 1 ) .. will squelch all drawing activity.
    #call $squelch_display( 0 ) .. will resume drawing activity.
    Note that #endproc must terminate any #proc previous to these function calls. (version 2.30+)

$boundingbox( mode )

    #call $boundingbox( 0 ) .. subsequent drawing does not influence the bounding box and hence the crop
    #call $boundingbox( 1 ) .. restore to normal mode of operation.
    Note that #endproc must terminate any #proc previous to these function calls. (version 2.30+)

$data_to_absolute( axis, val )

    Given a data location va in either X or Y space (specified by axis), return the absolute location.

$sleep( n )

    Delay for n seconds. Occasionally useful when viewing plots interactively.


    Produce a "More.." button and wait for user to click on it. Upon the click, return. Occasionally useful when viewing plots interactively.

$errmsgpre( tag )

    Allows developer to set the first portion of all ploticus error messages to tag (it will stay in effect until explicitly set again). For example, where a web page generates multiple plots it may be useful in identifying which plot had the error.

$textwidth( text, font, size)

    Return horizontal width of freetype bounding box. Useful only with freetype fonts, otherwise it returns 0. Suggested/contributed by Erik Zachte.

$rewritenums( f )

    takes a numeric quantity f and returns it rewritten for display purposes, applying numbernotation (as specified in your proc settings or config file).


$arith( exp, format )

    Simplistic arithmetic expression evaluator. exp is an expression made up of numbers and the arithmetic operators + - * /. No embedded spaces nor parentheses are allowed within the expression. Evaluation is strictly left to right. Unary plus/minus are allowed. In versions 2.30+ scientific notation eg. 3.74e-07 is supported. format is an optional printf(3) display format specifier controlling the format of the result, eg. %.0f. Default format is %g, which should suffice for all but very large or very small values. For more on format specifiers see your manual page on printf(3).
    Example: #set RESULT = $arith(2+8/5) (result: 2)
    Example: #set RESULT = $arith(2+-8) (result: -6)
    Example: #set RESULT = $arith( 18*1000000000 , "%.f" )
    #set RESULT = $arith( 18*.0000001 , "%.9f" )


    Same as $arith() except lazy, i.e. non-numeric operands are accepted and treated as if they were 0.


    Returns 1 if s is a valid number, 0 if not. In versions 2.30+ scientific notation is supported.
    Example: #set RESULT = $isnumber(-0.24) (result: 1)
    Example: #set RESULT = $isnumber(=) (result: 0)


    Format x using printf-style format string fmt. May also be used to format integers by using a fmt such as %03.0f.
    Example: #set RESULT = $formatfloat( 3.4425, "%3.2f" ) (result: 3.44)


    See if n is within the numeric range of lo to hi. Returns 1 if so, 0 if not. Non-numeric n always returns 0.

$numgroup( val, h, mode )

    Convert val to a nearby multiple of h. Useful in grouping a set of numbers into bins. mode may be either low, mid, or high. For example, if f is 73 and h is 10, function returns 70, 75, or 80 for modes low, mid, high respectively.


    Round val to a reasonable precision. Use a value of 0 for d for normal behavior. Increase d to get more precision, reduce d to get less precision.
    Example: #set X = $autoround( @X, 0 )


    Various mathematical functions. a and b can be integer or floating point unless otherwise noted below.
    what	returns
    ----    -------
    abs	absolute value of a 
    mod	a modulo b 
    div	integer division a / b (a and b must be integers)
    pow	a raised to b 
    mag	a multiplied by 10 to the b
    log+1	the natural log of a, plus 1.0
    exp-1	the exponential of a, minus 1.0
    sqrt	the square root of a

    Example: #set X = $math(abs,-57) would return 57.
    Example: #set X = $math(mod,10,6) would return 4.


    Returns a random number between 0.0 and 1.0.

$ranger( rangespec )

    Convert an integer range specification to an enumerated list of all integers covered. Range specifications can contain integers separated by commas or dashes, with no embedded spaces. Example:
    #set RANGE = "5,8,11-15"
    #set LIST = $ranger( @RANGE )

    LIST would then contain 5,8,11,12,13,14,15



    Return the length of s.


    Change all occurances of s1 to s2 in string.
    Example: #set T = $change( "<", "<sup>", @T )

$expand( s )

    Expand all @variables present in s. Example:
    #set B = "@A world"
    #set A = hello
    #set C = $expand( @B )
    Variable C would then contain hello world.


    Return a substring of s. Substring begins at character n (first is 1) for a maximum length of len. This function may also be used to count back from the end of the string and take a substring-- to do this, specify a negative n (see 2nd example below).
    Example: $substring( "abcde", 3, 99 ) would give cde
    Example: $substring( "abcde", -2, 99 ) would give de

$changechars( clist, teststring, newchar )

    The result will be teststring, with each instance of any char in clist changed to newchar. clist is either a single character or it may be one of these special symbols: not_alnum (change all non-alphanumeric chars); not_print (change all chars decimal ascii < 32 or > 127)l whitespace (change all whitespace chars).
    Example: #set RESULT = $changechars("*'", @S, "_" )

$deletechars( clist, teststring )

    The result will be teststring, with each instance of any char in clist deleted. clist may be a string of one or more characters, or one of these special symbols: not_alnum (delete all non-alphanumeric chars); not_print (delete all chars decimal ascii < 32 or > 127)l whitespace (delete all whitespace chars).
    Example: #set RESULT = $deletechars("*'",@S)

$stripws( s, mode )

    Remove whitespace characters from s. If mode is "any", all whitespace characters are removed. Otherwise only leading and trailing whitespace is stripped off.


    If string s contains any of chars in clist, return position (first=1) of the first occurance. Return 0 if none found. clist may be passed as the word comma to represent a comma (,).
    Example: #set RESULT = $contains( "*'", @S )
    Example: #set RESULT = $contains( ",", @S )


    Return the lower-case equivalent of string.
    Example: #set RESULT = $lowerc(HELLO) (result: hello)


    Return the upper-case equivalent of string
    Example: #set RESULT = $upperc(Hello) (result: HELLO)


    Return the string with first letter capitalized. (added 5/15/08).
    Example: #set RESULT = $upperc(hello) (result: Hello)


    Return an integer representation of the difference in magnitude of s and t, using ascii order.
    Note: don't use this for #if statement equality comparisons; simple = and != should be used instead.
    Example: #set RESULT = $strcmp(ABC,XY) (result will be a negative integer)
    Example: #set RESULT = $strcmp(XY,ABC) (result will be a positive integer)


    Return the concatenatation of strings s and t
    Example: #set RESULT = $strcat(ABC,XY) (result: ABCXY)

$ntoken( n, s [,c] )

    Return the nth whitespace-delimited token in s. Or if c is specified as a single character, it is used as the delimiter... return the nth field in s (added 3/28/08).

$counttokens( s [,c] )

    Return the number of whitespace-delimited tokens in s. Or if c is specified as a single character, it is used as the delimiter... return the nth field in s (added 5/15/08).

$extractnum( s )

    Extract the first numeric entity embedded anywhere in s and return it.

$wildcmp( s1, s2 )

    Return the result of a wildcard-enabled match s1 vs. s2. s2 can contain wild cards. Return value is 0 on a match, -1 if s1 is "less than" s2, and 1 if s1 is "greater than" s2.

$encrypt( s, salt )

    Returns the result of one-way encryption of s. Uses crypt(3C). salt is optional 2 character perturbation string.

$urlencode( s )

    Returns the url-encoded version of s.

$urldecode( s )

    Returns the url-decoded version of s.


These functions operate on a string which is in the form of a commalist .


    Count the number of times str appears in list. If str is passed as * then this function will count the number of members in the list.
    Example: #if $count( "*", "a,b,c" ) = 3 (true)
    Example: #set RESULT = $count( "hello", "aba,gabba,jabba" ) (result: 0)
    Example: #set RESULT = $count( "x", "x,y,x,y,y,z,x" ) (result: 3)


    Append a new member newmem to end of list. If list is empty before call, result will have one member.
    Example: #set RESULT = $addmember( "red", @MYLIST )


    Remove a member mem from list.
    Example: #set RESULT = $deletemember( "red", @MYLIST )


    Get the nth member of list.
    Example: #set RESULT = $nmember( 2, "a,b,c,d,e" ) (result: b)

$commonmembers( list1, list2, mode )

    Detect if list1 and list2 have any members in common. Returns 0 if no members in common. If mode is "count", then the number in common is returned (for a,b,c vs. c,d,e this would be 1; for a,a,a vs a,b,c it would be 3). Otherwise, when a match is found 1 is returned immediately.
    Example: #set MATCH = $commonmembers( "a,b,c,d,e", "c,d,ee", "count" ) (result: 2)

$homogenous( list )

    Return 1 if all members of list are the same, 0 if there are any differences among members. If list has only 1 member, 1 is returned. If list is empty, 0 is returned.

$makelist( s )

    Convert s, a list of items separated by commas and/or whitespace, and return a commalist. Useful for building commalists from user input.
    Example: #set LIST = $makelist( "1101 1102 1103" ) (result: 1101,1102,1103)
    Example: #set LIST = $makelist( "1101, 1102, 1103" ) (result: 1101,1102,1103)


Functions related to the shell interface are described on the #shell manual page .


Functions related to SQL interface are described on the #sql manual page .


These functions work with dates in various notations.

The default date format is mmddyy. Unless otherwise specified, these functions expect date arguments to be in the "current date format".


    Set the current date format.
    Example: #call $setdatefmt( "yyyymmdd" )


    Return date, formatted to newformat. Use to convert dates to different notations, to extract year, month, day components, or to get weekday equivalent. Available formats are described here
    Example: #set RESULT = $formatdate( @D, "yyyymmmdd" )


    Return 1 if date is a valid one in the current date format; return 0 if it is not.
    Example: #if $datevalid(@apptdate) != 1


    Return the current date. It will be in the date format currently in effect.
    Example: #set RESULT = $todaysdate()


    Return the difference in days between date1 and date2.
    Example: #set RESULT = $daysdiff( 011298, 010198 ) (result: 11)


    Return the julian (number of days since Jan 1, 1970) equivalent of date. date should be a date in current format, or the special symbol today.


    Return the date (in current format) that is equivalent to julian value jul.


    Return the date resulting when ndays are added to date.
    Example: #set RESULT = $dateadd( 010198, 11 ) (result: 011298)

$dategroup( interval, mode, input )

    Take date, datetime, or time input value, and adjust it for grouping purposes. For example, after a set of dates are processed using $dategroup( week, mid, .. ), the result can be tabulated to get a weekly distribution. Allowable interval values are week month quarter year day hour. Allowable mode values are mid and first. First character is sufficient for these two args.


    Return the integer age in years as of testdate of a person born on birthdate.
    Example: #set RESULT = $yearsold( 062661, 022098 ) (result: 36)


    Set a date parameter. You can set the pivotyear, strictdatelengths, or lazydates attributes. See the config file documentation for descriptions of these parameters.
    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)


These functions work with time values in various notations.


    Set the current time notation to fmt. Available notations are HH:MM:SS, HH:MM, and MM:SS. (A leading HH can handle single digit hour values; a leading MM can handle single digit minute values).
    Example: #set RESULT = $settimefmt(MM:SS) These functions work with time values.


    Return the current time in hh:mm:ss format.
    Example: #set RESULT = $time()


    Return 1 if time is valid in the current time format; return 0 if it is not.
    Example: #if $timevalid(@appttime) != 1


    Take time, which is in the current time format, and reformat it using newformat.
    Example: #set t2 = $formattime( "14:22", "hh:mma" )


    Get number of seconds since midnight for the current time.
    Example: #set RESULT = $timesec()


    Take t (a value in the current time notation) and return the equivalent, expressed in # of minutes since 0:00:00. Result is float, with any seconds expressed as the decimal portion of a minute.
    Example: #set RESULT = $tomin( "3:45" )


    Inverse of $tomin(), where m is a float minutes value. Result is equivalent time in current notation.
    Example: #set RESULT = $frommin( 3.75 )


    Find the difference between two times t1 and t2 (both in current notation). Result is expressed in float minutes (any seconds expressed as fraction of a minute)
    Example: #set RESULT = $timediff( "3:43", "2:28" )


Checksum routines use an odd-even algorithm that takes an integer and computes a checksum digit 0 - 9 or x. This checksum digit may be used to guard against key errors and transposed digits.


    Returns 1 if s is a valid number with checksum. 0 if not.
    Example: #if $checksumgood(39) = 1 (result: true)


    Result is integer i with a checksum digit appended.
    Example: #set CHECKNUM = $checksumencode(29) (result: 294)


    Take s which is a number including trailing checksum digit, and increment the number and recompute new checksum digit. Result is returned. Example: #set RESULT = $checksumnext(39) = 1 (result: 41)



    Return the contents of environment variable varname.


    Return a string containing euid,egid, where euid is the current effective user id, and egid is the current effective group id.

$errormode( mode )

    Control the display of error messages. Allowable values for mode are stderr and stdout. For command line applications the default is generally stderr; for CGI applications it is stdout, so that messages are visible. To hide error messages in CGI applications, set mode to stderr.


    Return a short identifier generated using the current date, time to the current second, and process id. The name will be unique on a per-host basis.


    Generate a unique (on a per-host basis) temporary file name, suitable for use in shell commands. Uses tmpdir as specified in project config file . Format of the name is tmpdir/tag.uniquename where uniquename is a short name generated using the current date, current time to the second, and process id. tag may be passed as a zero length string if desired.

$fileexists( dir, name )

    Return 1 if the requested file can be opened, 0 otherwise. dir indicates the directory that name is relative to and may be one of /, scriptdir, tmpdir. dir may also be datadir if using shSQL.
    Example: #set A = $fileexists( tmpdir, "mytmp" )

$rename( pathname, newpathname )

    Rename a file.

$unlink( pathname )

    Remove a file.

$chmod( pathname, mode )

    Do a chmod on pathname, setting it's file permissions to mode. Allowable modes are: 644, 664, 666, 444, 640, and 660.

$chdir( dirpath )

$mkdir( newdirpath )

    Initially sets the mode to 755; do a subsequent $chmod() for other protection modes.

$cleanname( name )

    Strip out any punctuation and control characters from name, leaving only letters, digits, and underscores.
    Example: #set name = $cleanname( @name )

$ref( varname )

    Return the contents of varname. May be useful when a variable contains the name of another variable, to extract the value of the other variable. Example:
     #set A = "hello"
     #set B = "A"
     #set C = $ref(@B)

    C would then contain hello.

$def( varname )

    Return 1 if varname has been set to a value (even if the value is ""). Return 0 otherwise.

$isleep( n )

    Delay for n seconds.


    For debug purposes. Writes a list of every existing internal variable name to standard output, along with a count. If mode is given as "values" variable contents are also written.


    Flush standard output buffer. With quisp this can be used to immediately display all content available so far.


Ploticus 2.42 ... May 2013 Terms of use /