Eval Function Tag Reference

More Eval functions can be created with the DEFFUN tag or by compiling the functions directly into DynamicFuncEvaluator.cpp.

For each function, the function name is a link to the source code at which it is defined. After the title a description of the function, the number and type of arguments, the return type, and an example of the function in use.

Description:

Returns the number of seconds since Jan 1 1970 for the current or given date and time.

It can take an optional date (in mm-dd-yy, mm/dd/yy, mm-dd-yyyy, mm/dd/yyyy or yyyyddmm) format, in which it returns the seconds for 12:01 AM of that date.

If the date is provided, the time can be given in a second argument (in "HHMM", "HH:MM" 24 hour formats or "HH:MM AM/PM/am/pm").

Two digit years are converted to four digit years using a sliding window of fifty years based on today's date.

Usage:

$return = dtTime([$date, [$time])

See Also: dtStrFromTime dtEpoc dtLegalDate

Description:

Returns true ("1") if the specified date is legal (a valid date of the format mm-dd-yy, mm/dd/yy, mm-dd-yyyy, mm/dd/yyyy, or yyyyddmm).

Two digit years are converted to four digit years using a sliding window of fifty years based on today's date.

Usage:

$return = dtLegalDate($date)

Description:

Returns the number of days since Jan 1 1970 for the current or given date.

It can take an optional date (in mm-dd-yy, mm/dd/yy, mm-dd-yyyy, mm/dd/yyyy or yyyyddmm) format, in which it returns the days since Jan 1 1970 for that date.

Two digit years are converted to four digit years using a sliding window of fifty years based on today's date.

Usage:

$return = dtEpoc([$date])

See Also: dtStrFromEpoc dtTime dtLegalDate

Description:

Returns today's date in mm-dd-yyyy format

Usage:

$return = dtToday()

Description:

Returns today's date and time according to the format string. Any characters that are not format commands are passed directly into the string.

The following are the possible format commands:

Date Format Commands
Format	Result
%a	Abbreviated weekday name
%A	Full weekday name
%b	Abbreviated month name
%B	Full month name
%c	Full date and time representation
%C	Full date and time representation produced by the UNIX date(1) command
%d	Day of month ["01","02",...,"31"]
%D	Date as %m/%d/%y
%e	Day of month [" 1"," 2",...,"31"]
%g	Week-based year within century [00,99]
%G	Week-based year with centry [0000,9999]
%h	Abbreviated month name
%H	Hour ["00","01",...,"23"]
%I	Hour ["01","02",...,"12"]
%J	Day number of the year ["001",...,"366"]
%k	Hour [" 0"," 1",...,"23"]
%l	Hour [" 1"," 2",...,"12"]
%M	Minute ["00","01",...,"59"]
%m	Month ["01","02",...,"12"]
%n	Newline
%p	a.m. or p.m.
%r	12-hour time format with %p
%R	Time with %H:%M
%S	Seconds [00,...,61] (2 extra seconds to accommodate leap seconds)
%t	Insert a TAB
%T	Time with %H:%M:%S
%V	ISO 8601 week number [01,...,53]. Week 01 begins with Monday on the week that includes both January 4th and the first Thursday of the year.
%w	Weekday [0,...,6] (0 is Sunday)
%W	Week number [00,...,53] (Sunday is the first day of week 1)
%x	Full date
%X	Full time
%y	Year within century [00,99]
%Y	Year including centry (i.e. 1999)
%Z	Time zone abbreviation

Usage:

$return = dtStrFromNow($format)

Example:

print(dtStrFromNow("%m/%d/%y %I:%M %p"))

// printed "12/10/99 09:10 PM" when this was written

See Also: dtStrFromDate dtFormatTime dtStrFromTime dtStrFromEpoc dtFormatMonth

Description:

Returns the specified date (and time if supplied) according to the format string. Any characters that are not format commands are passed directly into the string.

Please see dtStrFromNow for the possible format commands.

Two digit years are converted to four digit years using a sliding window of fifty years based on today's date.

Usage:

$return = dtStrFromDate($format, $date, [$time])

Example:

print(dtStrFromDate("%m/%d/%Y %I:%M %p","2/12/03","21:03"));
print(dtStrFromDate("%m/%d/%Y %I:%M %p","2/12/03 21:03"));

// prints "02/12/2003 09:03 PM"

See Also: dtStrFromNow dtFormatTime dtStrFromTime dtStrFromEpoc

Description:

Returns the given time according to the format string. Any characters that are not format commands are passed directly into the string. For the string formatting commands, the date is assumed to be 1/1/1970.

Please see dtStrFromNow for the possible format commands.

Usage:

$return = dtFormatTime($format, $time)

Example:

print(dtFormatTime("%I:%M %p","21:03"))

// prints "09:03 PM"

See Also: dtStrFromNow dtStrFromDate dtStrFromTime dtStrFromEpoc

Description:

Returns specified date and time (seconds since Jan 1, 1970) according to the format string. Any characters that are not format commands are passed directly into the string.

Please see dtStrFromNow for the possible format commands.

Usage:

$return = dtStrFromTime($format, $seconds)

Example:

print(dtStrFromTime("%m/%d/%Y %I:%M %p",944879848))

// prints "12/10/1999 09:37 PM"

See Also: dtTime dtStrFromNow dtStrFromDate dtFormatTime dtStrFromEpoc

Description:

Returns specified date (days since Jan 1, 1970) according to the format string. Any characters that are not format commands are passed directly into the string.

Please see dtStrFromNow for the possible format commands. Like dtStrFromNow, but it takes a second arg which is the days since Jan 1 1970

Usage:

$return = dtStrFromEpoc($format, $epoc_day)

Example:

print(dtStrFromEpoc("%m/%d/%Y",11000))

// prints "02/12/2000"

See Also: dtEpoc dtStrFromNow dtStrFromDate dtFormatTime dtStrFromTime

Description:

Given a date and a day of the week [0,...,6] (0 is Sunday), returns the date of the next day matching the day of the week after the given date.

Usage:

$return = dtNextDayOfWeek($date,$day_of_week)

Example:

print(dtNextDayOfWeek("12/10/99",0));

// prints "12-12-1999" (the Sunday after 12/10/99) 

Description:

Given a date and a number of days (positive or negative), returns a date separated from the specified date by the number of days.

Usage:

$return = dtAddDays($date,$num_days)

Example:

print(dtAddDays("1/2/2000",-3))

// prints "12-30-1999"

Description:

Converts between different month formats. It uses the format commands in dtStrFromNow to determine the output format. This includes "%b" for the abbreviated month name, "%B" for the full month name, and "%m" for the month as a number ["01",...,"12"].

Usage:

$return = dtFormatMonth($format,$month)

Example:

print(dtFormatMonth("%b %B %m","March"))

// prints "Mar March 03"

See Also: dtStrFromNow

Description:

Returns the full weekday name for a given weekday number. The week number is an integer [1,...,7] with 1 as Sunday.

Usage:

$return = dtFullWeekday($weekday_num)

Example:

print(dtFullWeekday(3));

// prints "Tuesday"

Description:

Returns the number of days in the month of a specified date. The day of the month in the date is ignored.

Usage:

$return = dtDaysInMonth($date)

Example:

print(dtDaysInMonth('8-23-2002'))

// prints "31" 

Description:

Returns true if a specified regular expression matches a given string. Searches are done across multiple lines. Matches are "greedy" in that every section of the regular expression will match as large a string as possible.

The following tables lists special regular expression characters. In order to use the respective real characters in the search string, they must be escaped with the character "\". (Due to the escape processing of the Eval language, the "\" character itself may need to be escaped.)

Regular Expression Characters
Characters	Purpose
(...)	Groups contents together
[...]	Matches a single character in a list of possible characters (i.e. [abc] will match a, b, or c)
[^...]	Matches a all characters not in the list of possible characters. (i.e. [^abc] will match all characters not a, b, or c.)
-	Enables a range of characters (i.e. [0-9] represents all digits
.	Matches all characters
|	Logical OR. (i.e. (dog|cat) matches "dog" or "cat)
?	Zero or one. (i.e. b(a?)t will match "bat" or "bt")
+	One or more. (i.e. [0-9]+ matches one or more numerical digits)
*	Zero or more. (i.e. [0-9]* matches zero or more numerical digits)
^	Matches the beginning of the string
$	Matches the end of the string

Usage:

$return = regExpFind($string,$regexp)

Example:

$integer_regexp = "[0-9]+";
print(regExpFind("Spot jumped 23 times.",$integer_regexp)); 
// prints "1"
print(regExpFind("Spot didn't jump.",$integer_regexp)); 
// prints "0"

See Also: regExpReplace regExpGrab

Description:

Executes regular expression search and replace on a string. Please see regExpFind for the list of regular expression command strings.

In the replace string, the command strings "\1", "\2", etc. can be used in the first, second, etc. matched parenthetical items in the regular expression. The string "\0" represents the complete match. (Due to the escape processing of the Eval language, the "\" character itself may need to be escaped.)

Usage:

$return = regExpReplace($string,$regexp,$replace_str,[$global_bool])

Example:

print(regExpReplace("butch is nice, al is nice","is","is not",0));
// prints "butch is not nice, al is nice"

print(regExpReplace('butch@tcg-inc.com',
                    '([^@]*)@([^\\.]*).*',
                    '\\0 -> user \\1 from \\2'));
// prints "butch@tcg-inc.com -> user butch from tcg-inc"

See Also: regExpFind regExpGrab

Description:

Executes regular expression search and returns a matched pattern string. Please see regExpFind for the list of regular expression command strings.

In the matched pattern string, the command strings "\1", "\2", etc. can be used in the first, second, etc. matched parenthetical items in the regular expression. The string "\0" represents the complete match. (Due to the escape processing of the Eval language, the "\" character itself may need to be escaped.)

Usage:

$return = regExpGrab($string,$regexp,$return_pattern)

Example:

$date_regexp = "([0-9]+)(/|-)([0-9]+)(/|-)([0-9]+)";
print(regExpGrab("Today is 12/11/99",$date_regexp,
                  "\\1-\\3-\\5"))
// prints "12-11-99"

See Also: regExpFind regExpReplace

Description:

One way encryption for added security with passwords. For distributions of SteelBlue compiled without the NO_CRYPT flag, this function calls the crypt(3C) one way encryption algorithm. Only the first 8 characters in $string and the first two characters of $salt are used.

Usage:

$return = crypt($string,$salt)

Example:

print(crypt("test","aa"))

// prints "aaqPiZY5xR5l."

Description:

Converts a string into uppercase.

Usage:

$return = upcase($string)

Example:

print(upcase("this works 2"))

// prints "THIS WORKS 2"

Description:

Converts a string into lowercase

Usage:

$return = downcase($string)

Example:

print(downcase("THIS WORKS 2"))

// prints "this works 2"

Description:

Converts newlines to BR tags in a string.

Usage:

$return = return2BR($string)

Example:

print(return2BR("One line\nAnd the next"))

// prints "One line<BR>And the next"

Description:

Loads the contents of a file (in binary mode). If the file cannot be read, it returns the empty string.

Note: this file can be used to load any file readable by the user of the Web server. Therefore, care should be taken to restrict outside access to this command.

Usage:

$return = loadFile($filename)

Example:

$contents = loadFile("/foo.txt")
\\ $contents is set to the contents of foo.txt 
\\ (read as a binary file)

See Also: saveFile

Description:

Saves a binary file on the server. If the file exists, it is overwritten.

Note: this file can be used to save any file writable by the user of the Web server. Therefore, care should be taken to restrict outside access to this command.

Usage:

$return = saveFile($filename,$string)

Example:

if(! saveFile("/foo.txt","test")){
   print("Test save not successful");
}
\\ Stores the string "test" in "/foo.txt"

See Also: loadFile

Description:

Executes a command-line SteelBlue page. If the configuration option "SB-Executable" is not set, the fourth argument $sbexecutable is required to specify the full path the steelblue executable. Tags and values passed into the second argument are set in the $this namespace of the executed page.

For high traffic public sites, execSteelBlue can be used to easily create static pages from database data (like a Calendar).

Usage:

execSteelBlue($filename,$tags,$output_file,[$sbexecutable])

Description:

Executes a shell command and captures STDOUT.

Usage:

$return = execCmd($cmd)

Example:

print(execCmd('date'));

\\ Prints the date returned by the shell command 'date'

Description:

Checks for existence and readability of a file.

Usage:

$return = execCmd($filename)

Example:

if(!fileExists("/foo.txt")){
  print("Cannot read /foo.txt");
}

Description:

Determines length of a binary string.

Usage:

$return = length($string)

Example:

print(length("test"));

// prints "4"

Description:

Usage:

$return = substr($string,$start,$num_chars)

Example:

print(substr("This is a test",10,4));

// prints "test"

Description:

Removes a possible leading 0 from numbers resulting from dtStrFromDate with %d, %m, etc..

Usage:

$return = unpad($string)

Example:

print(unpad(dtStrFromDate("%d","01/02/99")))

// prints "2"

Description:

Removes leading spaces from a string.

Usage:

$return = removeSpaces($string)

Example:

print("'" . removeSpaces("  Test") . "'");

// prints "'Test'"

Description:

Converts binary data to text (for insertion into a database). This is done by mapping every 6 bits of the binary string into 64 printable characters. The first character of the result holds the original binary string length mod 3 (for the purpose of proper string reconstruction).

Usage:

$return = binToTxt($string)

Example:

print(binToTxt("\0\r\nabcd"));

// prints "10oU2V9qMY100"

See Also: txtToBin

Description:

Converts text data (processed by bintoTxt()) back to binary. The process of converting binary data to and from text is useful to easily store binary data into a database that may only accept text data.

Usage:

$return = txtToBin($string)

Example:

print(txtToBin("08Z68oVKNmJK8"));

// prints "Hi there!"

See Also: binToTxt

Description:

Returns the location of a specified substring in a string.

Usage:

$return = find($string,$search_string,[$start_index])

Example:

print(find("This is a test","test"));

// prints "10"

Description:

Concatenates a variable number of strings.

Usage:

$return = concat($arg1,...,$argn)

Example:

print(concat("this"," is"," a"," test"));
// prints "this is a test"

Description:

Executes a dynamic Eval command.

Usage:

$return = eval($evalcmd)

Example:

$i = 2;
$name = "i";
print(eval("$".$name." + 1"));

// prints "3"

Description:

Changes the active username and institution of the user. This is useful in applications where an administrator needs to actively become other users, or in an application where public users can "log-in" in the middle of a session. If password is specified, the password is encrypted and then checked against the password for that user in the AuthUsers table.

If the user does not exist or the password is invalid (if a password is specified) then "0" is returned. Otherwise, the active username and institution are changed and "1" is returned.

Any Swap entries in the database will be moved to the new user, however subsequent calls to LOAD, SAVE, or CLEAR in the same section as the call to su will still refer to the former user's Swap.

Usage:

$return = su($username,$institution[,$password])

Example:

if (!su($new{username},$new{institution},$new{password})){
 print("Invalid username/password ");
} else {
 print("You are now ".$USER{username}");
} 

Description:

Exits currently executing function and returns the given value as the return value of the function. If called from outside a function, it will terminate the execution of the given SteelBlue section.

Usage:

return([$value])

Example:

function $a = times_two($b){
  return($b + 2);
}

print(times_two(20));
// prints "40"

Description:

Prints a variable number of (binary) strings to STDOUT.

Usage:

print($arg1,...,$argn)

Example:

$i = 2;
print("$i = ",$i);

// prints "$i = 2"

Description:

Flushes the STDOUT buffer

Usage:

flush()

Example:

print("Please wait"); flush();
execCmd('sleep 15');
print("\nDone");

// prints "Please wait" before pausing 15 seconds.  Becuase
// of the flush, the message should be visible to the user
// before the pause,

Description:

Returns true if the user is part of a list of comma separated groups. Group memebership is determined if an appropriate entry is placed in the Groups database table.

For speed, the first group call causes all groups to which the current user belongs to be stored in an associative array. Subsequent group calls in the page use this cached information.

Usage:

$return = group($grouplist)

Example:

if(group('admin,tcg')){
   // Do something special since the user is either in
   // the group "admin" or "tcg"
}

Description:

Simulates a sequence using Access or mySQL autonumber columns. For Access, it requires a table to be created for each sequence. The format should be:

create table seq_XXXXXXXX {
  seq   autonumber,
  pid   long
}

where XXXXXXXX is the name of sequence.

Usage:

$return = getSequence ($seq_name)

Example:

$pid = getSequence('person') //uses seq_person table

Description:

Executes an arbitrary SQL command (no data returned)

Usage:

sql($sqlcmd)

Example:

sql("delete from Swap where username='"
     .$USER{username}."'")
// Completely clears the Swap for a given username

Description:

Escapes the quotes in a string appropriate for use in SQL statements

Usage:

$return = escapeQuote($string)

Example:

sql("insert into Notes values ('"
     .escapeQuote($this{NOTES})."'")
// If NOTES has quotes, it is properly escaped before entry
// into the database

Description:

Compares two strings for lexicographic order. The function returns "0" if the strings are the same, a negative number if the first string is before the second string, and a positive number if the first string is after the second string.

Usage:

$return = strcmp($stra,$strb)

Example:

print(strcmp("hi","hello"));

// prints a positive number

Description:

Returns a random integer in the range 0 to $maxnum (inclusive). If $maxnum is not given, it defaults to 32767.

Usage:

$return = rand([$maxnum])

Example:

for($i=0;$i<10;$i=$i+1){
  print(rand(10)," ");
}
// prints 10 random integers in [0,10]

Description:

Formats a number using sprintf format strings.

Usage:

$return = formatNum($number)

Example:

print(formatNum("$%.2f","100.3"));

// prints "$100.30"

Description:

Rounds a number to the nearest integer.

Usage:

$return = round($number)

Example:

print(round(1.6))
// prints "2"

Description:

Performs the 'mod' operation

Usage:

$return = mod($number,$modulous)

Example:

print(mod(7,4))
// prints "3"

Description:

Rounds a number to the nearest integer with greater absolute value.

Usage:

$return = ceil($number)

Example:

print(ceil(3.1))
// prints "4"

Description:

Calculates the sine of an angle given in radians

Usage:

$return = sin($degrees)

Example:

print(sin(3.14159265/2))
// prints "1"

Description:

Calculates the cosine of an angle given in radians

Usage:

$return = cos($degrees)

Example:

print(cos(2*3.14159265))
// prints "1"

Description:

Rounds a number to the nearest integer with lesser absolute value.

Usage:

$return = floor($number)

Example:

print(floor(2.6))
// prints "2"

Description:

Declares variables in the local scope. New scopes are defined in the LOOP and DEFFUN command.

Please see the Functions section of the Eval Language of SteelBlue for an example of my() used in a recursive function.

Usage:

my($var1,...,$varn)

Description:

Calls the deconstructor and deletes an object.

If the object is an Eval-defined object, delete calls "~CLASSNAME()" for the object. If the deconstructor is not defined, it tries to call the deconstructor for the object's parent. If the object is a built-in object, it calls the virtual function deconstructObject().

Once the deconstructor is called, the object is deleted and removed from memory.

Usage:

delete($object)

Example:

class person($name){
  $this.name = $name;
}

function ~person(){
  print($this.name . " is being removed<br>\n");
}

$me = new person("Rob Buccigrossi");
delete($me);

// Prints "Rob Buccigrossi is being removed"

Description:

Invalidates (deletes) previously cached SteelBlue pages. Standard file wildcards are permitted in either $name or $index. The cache files are removed in the directory specified by the "CacheDir" SteelBlue configuration entry.

Usage:

invalidateCache($name,[$index])

Example:

invalidateCache('week');

// Deletes all cache files beginning with "week" (i.e. week*.csb)

Description:

Iterates through the keys of an associative array. The first key is returned by setting $previouskey to "". The next key is then returned by setting $previouskey to the previously returned key. "" is returned when all keys have been listed.

Usage:

$return = nextKey($namespace, $previouskey)

Example:

$test{a} = "hi"; $test{b} = "there"; $test{c} = 3;
for($key=nextKey($test,"");
    $key ne "";
    $key=nextKey($test,$key)){
  print("$test{",$key,"} = '",$test{$key},"'<br>");
}

// Prints the three assignments to the $test namespace

Description:

Gets the value of an environment variable

Usage:

$return = getEnv($env_var)

Example:

print(getenv('REQUEST_URI'))

// prints the CGI command string

Description:

Gets the value of a configuration variable. The configuration variable name ($config_name) is case insensitive and ignores "-" and "_" characters.

Usage:

$return = getConfig($config_name)

Example:

print(getconfig('UseDB'))

//prints the type of database currently used 

Description:

Creates a URL to access a given SteelBlue screen. This is useful for creating a pop-up pages that access SteelBlue screens.

Usage:

$return = makeHREF($screen)

Example:

print(makeHREF('welcome.sb'))
// prints a URL to the SteelBlue screen 'welcome.sb'

Description:

Integer multiplication by 2 (example function in DynamicFuncEvaluator.cpp)

Usage:

$return = timestwo($number) 

Example:

print(timestwo(3.14));

// prints "6"