File: functions

package info (click to toggle)
ploticus-doc 2.33-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 9,392 kB
ctags: 169
sloc: pascal: 469; makefile: 63; sh: 11
file content (1124 lines) | stat: -rw-r--r-- 25,098 bytes
.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: functions</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>functions</h2></td>
  <td align=right>
  <small>
  <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  Version 2.33 Jun'06
     </small><br><a href="../doc/scripthome.html">Scripts</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH functions PL "02-JUN-2006   PL ploticus.sourceforge.net"

.LP
Categories of available functions:
.LP
.ig >>
<a href="functions.html#ploticus">
.>>
\0plotting
.ig >>
</a>
.>>
.br
.ig >>
<a href="functions.html#arithmetic">
.>>
\0arithmetic
.ig >>
</a>
.>>
.br
.ig >>
<a href="functions.html#strings">
.>>
\0strings
.ig >>
</a>
.>>
.br
.ig >>
<a href="functions.html#commalists">
.>>
\0commalists
.ig >>
</a>
.>>
.br
.ig >>
<a href="shell.html">
.>>
\0shell
.ig >>
</a>
.>>
.br
.ig >>
<a href="sql.html">
.>>
\0sql
.ig >>
</a>
.>>
.br
.ig >>
<a href="functions.html#dates">
.>>
\0dates
.ig >>
</a>
.>>
.br
.ig >>
<a href="functions.html#times">
.>>
\0times
.ig >>
</a>
.>>
.br
.ig >>
<a href="functions.html#misc">
.>>
\0misc
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH HOW TO USE FUNCTIONS
.LP
A number of functions are available for use in 
.ig >>
<a href="scripts.html">
.>>
\0ploticus scripts
.ig >>
</a>
.>>
  and
.ig >>
<a href="getdata.html">
.>>
\0proc getdata filters
.ig >>
</a>
.>>
, for a wide range of purposes including processing of arithmetic, strings
dates, times, 
.ig >>
<a href="commalist.html">
.>>
\0commalists
.ig >>
</a>
.>>
, and so on.  
Functions usually take one or more arguments and return a value.

Functions may be used with
.ig >>
<a href="scriptsyntax.html#set">
.>>
\0#set
.ig >>
</a>
.>>
  ,
.ig >>
<a href="scriptsyntax.html#call">
.>>
\0#call
.ig >>
</a>
.>>
  or as operands in
.ig >>
<a href="scriptsyntax.html#if">
.>>
\0#if/#elseif
.ig >>
</a>
.>>

.ig >>
<a href="condex.html">
.>>
\0conditional expressions
.ig >>
</a>
.>>
\0.  

.LP
Custom functions may be coded and added to the file \fCcustom.c\fR,
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.

.ig >>
<br><br><br>
.>>

.SH FUNCTION SYNTAX
Function names always start with a dollar sign (\fB$\fR).
Function arguments are enclosed by parentheses and if more than one
argument, separated by commas (,).  For example:
.IP \0
\fC$formatfloat( @NUM, "%7.2f" )\fR
.LP
Function calls may not be nested, ie. function arguments may not be functions.

.ig >>
<br><br><br>
.>>

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


.ig >>
<br><br><br>
.>>
.ig >>
<a name=ploticus></a>
.>>
.SH PLOTTING
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,
\fC#endproc\fR should be used to terminate any #proc previous to these function calls,
so that the proc executes before the function call.
.LP
\fB$inrange( value, axis )\fR   or
.br
\fB$inrange( value, axis, min, max )\fR
.IP \0
Return 1 if \fIvalue\fR within a range on the given \fIaxis\fR.
\fImin\fR and \fImax\fR 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.

.ig >>
<br><br>
.>>

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

.ig >>
<br><br>
.>>

.LP
\fB$fieldname( n )\fR
.IP \0
Return the field name assigned to field \fIn\fR.  First is 1.
If no field name was defined, \fCnoname\fR is returned.

.ig >>
<br><br>
.>>

.LP
\fB$dataitem( row, field )\fR
.IP \0
Return the contents of the item in \fIrow\fR and \fIfield\fR of
the current data set.  \fIrow\fR is a number, first is 1.
\fIfield\fR is either a number or an assigned name.

.ig >>
<br><br>
.>>

.LP
\fB$defaultinc( min, max )\fR
.IP \0
Return a reasonable increment given numeric \fImin\fR and \fImax\fR,
using the same algorithm used with axis stub increments.
.br
Example: \fC#set inc = $defaultinc( 0, 200 )\fR

.ig >>
<br><br>
.>>

.LP
\fB$squelch_display( mode )\fR
.IP \0
\0 #call $squelch_display( 1 ) .. will squelch all drawing activity.  
.br
\0 #call $squelch_display( 0 ) .. will resume drawing activity.  
.br
Note that \fC#endproc\fR must terminate any #proc previous to these function calls.  (version 2.30+)

.ig >>
<br><br>
.>>
.LP
\fB$bounding_box( mode )\fR
.IP \0
\0 #call $boundingbox( 0 )  .. subsequent drawing does not influence the bounding box and hence the crop
.br
\0 #call $boundingbox( 1 )  .. restore to normal mode of operation.
.br
Note that \fC#endproc\fR must terminate any #proc previous to these function calls. (version 2.30+)

.ig >>
<br><br>
.>>

.LP
\fB$data_to_absolute( axis, val )\fR
.IP \0
Given a data location \fIva\fR in either X or Y space (specified by
\fIaxis\fR), return the absolute location.

.ig >>
<br><br>
.>>

.LP
\fB$sleep( n )\fR
.IP \0
Delay for \fIn\fR seconds.  
Occasionally useful when viewing plots interactively.

.ig >>
<br><br>
.>>

.LP
\fB$getclick()\fR
.IP \0
Produce a "More.." button and wait for user to click on it.
Upon the click, return.
Occasionally useful when viewing plots interactively.

.ig >>
<br><br>
.>>

.LP
\fB$errmsgpre( tag )\fR
.IP \0
Allows developer to set the first portion of all ploticus error messages to \fCtag\fR
(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.

.ig >>
<br><br>
.>>
.LP
\fB$textwidth( text, font, size)\fR
.IP \0
Return horizontal width of freetype bounding box.
Useful only with freetype fonts, otherwise it returns 0.  Suggested/contributed by Erik Zachte.


.ig >>
<br><br>
.>>
.LP
\fB$rewritenums( f )\fR
.IP \0
takes a numeric quantity \fIf\fR and
returns it rewritten for display purposes, applying 
numbernotation (as specified in your proc settings or config file).

.ig >>
<br><br>
.>>



.ig >>
<a name=arithmetic></a>
.>>
.ig >>
<br><br><br>
.>>

.SH ARITHMETIC AND NUMBERS

.LP
\fB$arith( exp, format )\fP 
.IP \0
Simplistic arithmetic expression evaluator. 
\fIexp\fR is an expression made up of numbers and the arithmetic operators
\fC+ - * /\fR.
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. \fC3.74e-07\fR is supported.
\fIformat\fR is an optional printf(3) display format specifier controlling
the format of the result,
eg. \fC%.0f\fR.  Default format is \fC%g\fR, which should suffice for all but very
large or very small values.  For more on format specifiers see your manual page on printf(3).
.br
Example: \fC#set RESULT = $arith(2+8/5)\fP  (result: 2)
.br
Example: \fC#set RESULT = $arith(2+-8)\fP  (result: -6)
.br
Example: \fC#set RESULT = $arith( 18*1000000000 , "%.f" )
.br
Example: \fC#set RESULT = $arith( 18*.0000001 , "%.9f" )

.LP
\fB$arithl(exp)\fP
.IP \0
Same as \fB$arith()\fP except 
lazy, i.e. non-numeric operands 
are accepted and treated as if they were 0.  

.LP
\fB$isnumber(s)\fP
.IP \0
Returns 1 if \fIs\fP is a valid number, 0 if not.
In versions 2.30+ scientific notation is supported.
.br
Example: \fC#set RESULT = $isnumber(-0.24)\fR  (result: 1)
.br
Example: \fC#set RESULT = $isnumber(=)\fR  (result: 0)

.LP
\fB$formatfloat(x,fmt)\fR
.IP \0
Format \fIx\fR using printf-style format string \fIfmt\fR.
May also be used to format integers by using a \fIfmt\fR such as \fC%03.0f\fR.
.br
Example: \fC#set RESULT = $formatfloat( 3.4425, "%3.2f" )\fR (result: 3.44)

.LP
\fB$inr(n,lo,hi)\fR
.IP \0
See if \fIn\fR is within the numeric range of \fIlo\fR
to \fIhi\fR.  Returns 1 if so, 0 if not.  Non-numeric \fIn\fR always returns 0.

.LP
\fB$numgroup( val, h, mode )\fR
.IP \0
Convert \fIval\fR to a nearby multiple of \fIh\fR.
Useful in grouping a set of numbers into bins.
\fImode\fR may be either \fClow\fR, \fCmid\fR, or \fChigh\fR.   
For example, if f is 73 and h is 10, function returns 70, 75, or 80 for modes 
\fClow\fR, \fCmid\fR, \fChigh\fR respectively.

.LP
\fB$autoround(val,d)\fR
.IP \0
Round \fIval\fR to a reasonable precision.
Use a value of 0 for \fId\fR for normal behavior.  Increase \fId\fR to
get more precision, reduce \fId\fR to get less precision.
.br
Example: \fC#set X = $autoround( @X, 0 )\fR

.LP
\fB$math(what,a,b)\fR
.IP \0
Various mathematical functions.  \fIa\fR and \fIb\fR can be integer or floating point 
unless otherwise noted below.
.nf
what	returns
----    -------
abs	absolute value of \fIa\fR 
mod	\fIa\fR modulo \fIb\fR 
div	integer division \fIa\fR / \fIb\fR (\fIa\fR and \fIb\fR must be integers)
pow	\fIa\fR raised to \fIb\fR 
mag	\fIa\fR multiplied by 10 to the \fIb\fR
log+1	the natural log of \fIa\fR, plus 1.0
exp-1	the exponential of \fIa\fR, minus 1.0
sqrt	the square root of \fIa\fR
.fi
.br
Example: \fC#set X = $math(abs,-57)\fR would return \fC57\fR.
.br
Example: \fC#set X = $math(mod,10,6)\fR would return \fC4\fR.

.LP
\fB$random()\fR
.IP \0
Returns a random number between 0.0 and 1.0.

.LP
\fB$ranger( rangespec )\fR
.IP
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:
.br
\fC
 \0 #set RANGE = "5,8,11-15"
.br
 \0 #set LIST = $ranger( @RANGE )
\fR
.br
LIST would then contain \fC 5,8,11,12,13,14,15 \fR

.ig >>
<a name=strings></a>
.>>
.ig >>
<br><br><br>
.>>

.SH STRINGS

.LP
\fB$len(s)\fR
.IP \0
Return the length of \fIs\fR.

.LP
\fB$change(s1,s2,string)\fR
.IP \0
Change all occurances of \fIs1\fR to \fIs2\fR in string.
.br
Example: \fC#set T = $change( "<", "<sup>", @T )\fR

.LP
\fB$expand( s )\fR
.IP \0
Expand all @variables present in \fIs\fR.
Example: 
.nf
\0#set B = "@A world"
\0#set A = hello
\0#set C = $expand( @B )
.fi
Variable C would then contain \fChello world\fR.

.LP
\fB$substring(s,n,len)\fR
.IP \0
Return a substring of \fIs\fR.  Substring begins at character \fIn\fR (first is 1)
for a maximum length of \fIlen\fR.
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 \fIn\fR (see 2nd example below).
.br
Example: \fC$substring( "abcde", 3, 99 )\fR would give \fCcde\fR
.br
Example: \fC$substring( "abcde", -2, 99 )\fR would give \fCde\fR


.LP
\fB$changechars(clist,s,newchar)\fR
.IP \0
If string \fIs\fR contains any of chars in \fIclist\fR, change that
character to \fInewchar\fR.  
\fBclist\fR may be passed as the word \fCcomma\fR to represent a comma (,).
.br
Example: \fC#set RESULT = $changechars("*'", @S, "_" )\fR

.LP
\fB$deletechars(clist,s)\fR
.IP \0
If string \fIs\fR contains any of chars in \fIclist\fR, delete that character.
.br
Example: \fC#set RESULT = $deletechars("*'",@S)\fR

.LP
\fB$stripws( s, mode )\fR
.IP \0
Remove whitespace characters from \fIs\fR.
If mode is "any", all whitespace characters are removed.
Otherwise only leading and trailing whitespace is stripped off.

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



.LP
\fB$lowerc(string)\fP
.IP \0
Return the lower-case equivalent of \fIstring\fP.
.br
Example: \fC#set RESULT = $lowerc(HELLO)\fP (result: \fChello\fP)

.LP
\fB$upperc(string)\fP
.IP \0
Return the upper-case equivalent of \fIstring\fP
.br
Example: \fC#set RESULT = $upperc(Hello)\fP (result: \fCHELLO\fP)

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

.LP
\fB$strcat(s,t)\fP
.IP \0
Return the concatenatation of strings \fIs\fP and \fIt\fP
.br
Example: \fC#set RESULT = $strcat(ABC,XY)\fP  (result: \fCABCXY\fP)

.LP
\fB$ntoken( n, s )\fR
.IP \0
Return the \fIn\fRth whitespace-delimited token in \fIs\fR.

.LP
\fB$extractnum( s )\fR
.IP \0
Extract the first numeric entity embedded anywhere in \fIs\fR and return it.

.LP
\fB$wildcmp( s1, s2 )\fR
.IP \0
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.


.ig >>
<a name=commalists></a>
.>>
.ig >>
<br><br><br>
.>>

.SH COMMALISTS
These functions operate on a string which is in the form of a 
.ig >>
<a href="commalist.html">
.>>
\0commalist
.ig >>
</a>
.>>
\0.

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

.LP
\fB$addmember(newmem,list)\fP
.IP \0
Append a new member \fInewmem\fR to end of \fIlist\fR.
If \fIlist\fR is empty before call, result will have one member.
.br
Example: \fC#set RESULT = $addmember( "red", @MYLIST )\fR

.LP
\fB$deletemember(mem,list)\fP
.IP \0
Remove a member \fImem\fR from \fIlist\fR.
.br
Example: \fC#set RESULT = $deletemember( "red", @MYLIST )\fR

.LP
\fB$nmember(n,list)\fP
.IP \0
Get the \fIn\fPth member of \fIlist\fP.  
.br
Example: \fC#set RESULT = $nmember( 2, "a,b,c,d,e" )\fP (result: \fCb\fB)

.LP
\fB$commonmembers( list1, list2, mode )
.IP \0
Detect if \fIlist1\fR and \fIlist2\fR have any members in common.
Returns 0 if no members in common.
If \fImode\fR is \fC"count"\fR, 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.
.br
Example: \fC#set MATCH = $commonmembers( "a,b,c,d,e", "c,d,ee", "count" )\fR  (result: \fC2\fR)

.LP
\fB$homogenous( list )\fR
.IP \0
Return 1 if all members of list are the same, 0 if there are any differences
among members.
If \fIlist\fR has only 1 member, 1 is returned.  
If \fIlist\fR is empty, 0 is returned.

.LP
\fB$makelist( s )\fR
.IP \0
Convert \fIs\fR, a list of items separated by commas and/or whitespace, 
and return a commalist.
Useful for building commalists from user input.
.br
Example: \fC#set LIST = $makelist( "1101   1102 1103" )\fR  (result: \fC1101,1102,1103\fR)
.br
Example: \fC#set LIST = $makelist( "1101,  1102, 1103" )\fR  (result: \fC1101,1102,1103\fR)

.ig >>
<a name=shell></a>
.>>
.ig >>
<br><br><br>
.>>

.SH SHELL COMMAND INTERFACE
Functions related to the shell interface are described on the
.ig >>
<a href="shell.html">
.>>
\0#shell manual page
.ig >>
</a>
.>>
\0.


.ig >>
<a name=sql></a>
.>>
.ig >>
<br><br><br>
.>>

.SH SQL DATABASE INTERFACE
Functions related to SQL interface are described on the
.ig >>
<a href="sql.html">
.>>
\0#sql manual page
.ig >>
</a>
.>>
\0.


.ig >>
<a name=dates></a>
.>>
.ig >>
<br><br><br>
.>>

.SH DATES
.LP
These functions work with 
.ig >>
<a href="dates.html">
.>>
\0dates in various notations.
.ig >>
</a>
.>>
.LP
The default date format is \fCmmddyy\fR.
Unless otherwise specified, these functions expect date arguments
to be in the "current date format".

.LP
\fB$setdatefmt(format)\fR
.IP \0
Set the current date format.
.br
Example: \fC#call $setdatefmt( "yyyymmdd" )\fR

.LP
\fB$formatdate(date,newformat)\fR
.IP \0
Return \fIdate\fR, formatted to \fInewformat\fR.
Use to convert dates to different notations, to extract year, month, day
components, or to get weekday equivalent.
Available formats are described 
.ig >>
<a href="dates.html">
.>>
\0here
.ig >>
</a>
.>>
.br
Example: \fC#set RESULT = $formatdate( @D, "yyyymmmdd" )\fR

.LP
\fB$datevalid(date)\fR
.IP \0
Return 1 if \fIdate\fR is a valid one in the current date format;
return 0 if it is not.
.br
Example: \fC#if $datevalid(@apptdate) != 1\fR

.LP
\fB$todaysdate()\fR
.IP \0
Return the current date.  It will be in the date format currently in effect.
.br
Example: \fC#set RESULT = $todaysdate()\fR

.LP
\fB$daysdiff(date1,date2)\fR
.IP \0
Return the difference in days between \fIdate1\fR and \fIdate2\fR.
.br
Example: \fC#set RESULT = $daysdiff( 011298, 010198 )\fR (result: 11)

.LP
\fB$julian(date)\fR
.IP \0
Return the julian (number of days since Jan 1, 1970) equivalent of \fIdate\fR.
\fIdate\fR should be a date in current format, or the special symbol \fCtoday\fR.

.LP
\fB$jultodate(jul)\fR
.IP \0
Return the date (in current format) that is equivalent to julian value \fIjul\fR.

.LP
\fB$dateadd(date,ndays)\fR
.IP \0
Return the date resulting when \fIndays\fR are added to \fIdate\fR.  
.br
Example: \fC#set RESULT = $dateadd( 010198, 11 )\fR (result: 011298)

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

.LP
\fB$yearsold(birthdate,testdate)\fR
.IP \0
Return the integer age in years as of 
\fItestdate\fR of a person born on \fIbirthdate\fR.
.br
Example: \fC#set RESULT = $yearsold( 062661, 022098 )\fR (result: 36)

.LP
\fB$setdateparms(parmname,value)\fR
.IP \0
Set a date parameter.  
You can set the 
\fBpivotyear\fR, \fBstrictdatelengths\fR, or \fBlazydates\fR attributes.
See the
.ig >>
<a href="config.html">
.>>
\0config file documentation
.ig >>
</a>
.>>
for descriptions of these parameters.
.br
Example of setting the pivot year: \fC#set STATUS = $setdateparms(Pivotyear,90)\fR
.br
Example of allowing lazy days: \fC#set STATUS = $setdateparms(Lazydates,days)\fR
.br
Example of allowing lazy days and months: \fC#set STATUS = $setdateparms(Lazydates,both)\fR

.ig >>
<a name=times></a>
.>>
.ig >>
<br><br><br>
.>>

.SH TIMES
These functions work with 
.ig >>
<a href="times.html">
.>>
\0time values
.ig >>
</a>
.>>
in various notations.

.LP
\fB$settimefmt(fmt)\fR
.IP \0
Set the current time notation to \fIfmt\fR.
Available notations are \fCHH:MM:SS\fR, \fCHH:MM\fR, and \fCMM:SS\fR.
(A leading HH can handle single digit hour values; a leading MM
can handle single digit minute values).
.br
Example: \fC#set RESULT = $settimefmt(MM:SS)\fR
These functions work with time values.

.LP
\fB$time()\fP
.IP \0
Return the current time in \fChh:mm:ss\fR format.
.br
Example: \fC#set RESULT = $time()\fP

.LP
\fB$timevalid(time)\fR
.IP \0
Return 1 if \fItime\fR is valid in the current time format;
return 0 if it is not.
.br
Example: \fC#if $timevalid(@appttime) != 1\fR

.LP
\fB$formattime(time,newformat)\fR
.IP \0
Take \fItime\fR, which is in the current time format,
and reformat it using \fInewformat\fR.
.br
Example: \fC#set t2 = $formattime( "14:22", "hh:mma" )

.LP
\fB$timesec()\fP
.IP \0
Get number of seconds since midnight for the current time.
.br
Example: \fC#set RESULT = $timesec()\fP

.LP
\fB$tomin(t)\fR
.IP \0
Take \fIt\fR (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. 
.br
Example: \fC#set RESULT = $tomin( "3:45" )\fR
 
.LP
\fB$frommin(m)\fR
.IP \0
Inverse of $tomin(), where \fIm\fR is a float minutes value.
Result is equivalent time in current notation.
.br
Example: \fC#set RESULT = $frommin( 3.75 )\fR

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

.ig >>
<a name=checksums></a>
.>>
.ig >>
<br><br><br>
.>>

.SH CHECKSUMS
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.
.LP

\fB$checksumvalid(s)\fP
.IP \0
Returns 1 if \fIs\fR is a valid
number with checksum.  0 if not.
.br
Example: \fC#if $checksumgood(39) = 1\fR (result: true)

.LP
\fB$checksumencode(i)\fR
.IP \0
Result is integer \fBi\fR with 
a checksum digit appended.
.br
Example: \fC#set CHECKNUM = $checksumencode(29)\fR (result: 294)

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


.ig >>
<a name=misc></a>
.>>
.ig >>
<br><br><br>
.>>

.SH MISCELLANEOUS
.LP
\fB$getenv(varname)\fR
.IP \0
Return the contents of environment variable \fIvarname\fR.

.LP
\fB$whoami()\fR
.IP
Return a string containing \fIeuid,egid\fR, where \fIeuid\fR is the
current effective user id, and \fIegid\fR is the current effective group id.

.LP
\fB$errormode( mode )\fR
.IP \0
Control the display of error messages.  Allowable values for \fImode\fR are
\fCstderr\fR and \fCstdout\fR.  For command line applications the default is
generally \fCstderr\fR; for CGI applications it is \fCstdout\fR, so that messages
are visible.  To hide error messages in CGI applications, set \fImode\fR to \fCstderr\fR.

.LP
\fB$uniquename()\fR
.IP \0
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.

.LP
\fB$tmpfilename(tag)\fR
.IP \0
Generate a unique (on a per-host basis) temporary file name, suitable
for use in shell commands.  Uses \fBtmpdir\fR as specified in
.ig >>
<a href="config.html">
.>>
\0project config file
.ig >>
</a>
.>>
\0.  Format of the name is \fItmpdir\fC/\fItag\fC.\fIuniquename\fR where
\fIuniquename\fR is a short name generated using the current date, current time
to the second, and process id.  \fItag\fR may be passed as a zero length string
if desired.

.LP
\fB$fileexists( dir, name )\fR
.IP \0
Return 1 if the requested file can be opened, 0 otherwise.
\fIdir\fR indicates the directory that \fIname\fR is relative to
and may be one of \fC/\fR, \fCscriptdir\fR, \fCtmpdir\fR.
\fIdir\fR may also be \fCdatadir\fR if using shSQL.

.br
Example: \fC#set A = $fileexists( tmpdir, "mytmp" )\fR

.LP
\fB$cleanname( name )\fR
.IP \0
Strip out any punctuation and control characters
from \fIname\fR, leaving only letters, digits, and underscores.
.br
Example: \fC#set name = $cleanname( @name )\fR

.LP
\fB$ref( varname ) \fR
.IP \0
Return the contents of \fIvarname\fR.  May be useful when a variable contains
the name of another variable, to extract the value of the other variable.
Example:
.br
.nf
\0 #set A = "hello"
\0 #set B = "A"
\0 #set C = $ref(@B)
.fi
.br
C would then contain \fChello\fR.

.LP
\fB$def( varname ) \fR
.IP \0
Return 1 if varname has been set to a value (even if the value is "").
Return 0 otherwise.

.LP
\fB$isleep( n )\fR
.IP \0
Delay for \fIn\fR seconds.  


.LP
\fB$fflush()\fR
.IP \0
Flush standard output buffer.  With \fCquisp\fR this can be used to immediately display
all content available so far.




.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif"> 
</center>
</td></tr>
</table>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>