Language Reference

The code toolbox in the Calc tab of the clarity designer provides the user with a list of various functions that can be used to manipulate and format the data before being displayed in the report. The following is a list of elements contained in the toolbox:

String Functions

Capitalize - Capitalizes the first character following a space for every word in a string.

Declaration: Function Capitalize(const S: String) : String;
CompareText - Compares two strings by ordinal value with case sensitivity.

Declaration: Function CompareText (const S1, S2: String): Integer;
Copy - Returns a substring of a string or a segment of a dynamic array

Declaration: Function Copy(S:String; Index, Count: Integer) : String;
Delete - Removes a substring from a string.

Declaration: procedure Delete (var S: String; Index, Count: Integer);
Insert - Inserts a substring into a string beginning at a specified point.

Declaration: procedure Insert (Soure: String; var S: String; Index: Integer);
Length - Returns the number of characters in a string.

Declaration: function Length(S: String): Integer;
LowerCase - Converts an ASCII string to lowercase.

Declaration: function LowerCase (const S: String): String;
NumberStr - Converts a number to an English string (e.g. for cheques).

Declaration: function NumberStr (const aNumber: Integer): String;
PadLeft - “Pads” a string with characters up to a fixed length.

Declaration: function PadLeft (const S: string; tolength: Integer; withchar: Char): string;
PadRight - “Pads” a string with characters up to a fixed length.

Declaration: function PadRight(const S: string; tolength: Integer; withchar: Char): string;
Pos - Returns the index value of the first character in a specified substring that occurs in a given string.

Declaration: function Pos (Substr: String; S: String): Integer;
Trim - Returns a copy of the string S with leading spaces and control characters removed.

Declaration: function Trim(const S: String) : String;
TrimLeft - Returns a copy of the string S with leading spaces and control characters removed.

Declaration: function TrimLeft (const S: String) : String;
TrimRight - Returns a copy of the string S with trailing spaces and control characters removed.

Declaration: function TrimRight (const S: String) : String;
Uppercase - Returns a copy of the string in uppercase.

Declaration: function Uppercase(const S: String): String;

Conversion Functions

Chr - Returns the character with the ordinal value (ASCII value) of the byte-type expression X.

Declaration: function Chr (X: Byte) : Char;
CurrToStr - Formats a currency value as string.

Declaration: function CurrToStr (Value: Currency): String;
DateTimeToStr - Converts a Datetime value to string.

Declaration: function DateTimeToStr (aDateTime: DateTime) : String;
DateToStr - Converts a Date value to string.

Declaration: function DateToStr (aDate: Date): String;
FloatToStr - Converts a floating point value to string.

Declaration: FloatToStr (Value: Extended): String;
IntToStr - Converts and integer to a string.

Declaration: function IntToStr(Value: Integer): String;
RGB - Returns a red, green, blue (RGB) color based on the arguments supplied. The intensity for each argument is in the range 0 through 255. If all three intensities are zero, the result is black. If all three intensities are 255, the result is white,

Declaration: function RGB(bRed, bGreen, bBlue: Integer) : Integer;
StrToCurr - Converts a string to a currency value.

Declaration: function StrToCurr (const S: String): Currency;
StrToDate - Converts a string to a date value.

Declaration: function StrToDate (const S : String) : Date;
StrToDateTime - Converts a string to Datetime value.

Declaration: function StrToDateTime (const S : String) : DateTime;
StrToFloat - Converts a given string to a floating point value.

Declaration: StrToFloat (const S : String) : Extended;
StrToInt - Converts a string that represents an integer (decimal or hex notation) to a number.

Declaration: function StrToInt (const S : String) : Integer;
StrToIntDef - Converts a string that represents an integer (decimal or hex notation) to a number. If S does not represent a valid number, StrToIntDef returns the number passed in Default.

Declaration: function StrToIntDef (const S : String; Default: Integer) : Integer;
StrToTime - Converts a string to time value.

Declaration: function StrToTime (const S : String) : Time;
TimeToStr - Returns a string that represents a DateTime value.

Declaration: TimeToStr(aTime: Time) : String;

Format Functions

FormatCurr - Formats a currency object. See FormatFloat function for more information on supported formats.

Declaration: function FormatCurr(const Format: String; Value: Currency): String;

FormatDateTime - Formats a datetime value.

Declaration: function FormatDateTime(const Format: string; aDateTime: datetime): String;

The following format specifiers are supported:

Specifier	Description
C	Displays the date using the format given by the Windows short date format, followed by the time using the format given by the Windows long time format. The time is not displayed if the fractional part of the DateTime value is zero
d	Displays the day as a number without leading zero (1-31)
dd	Displays the day as a number with a leading zero (01-31)
ddd	Displays the day as an abbreviation (Sun-Sat)
dddd	Displays the day as a full name (Sunday-Saturday)
ddddd	Displays the date using the format given by the Windows short date format.
dddddd	Displays the date using the format given by the Windows long date format.
m	Displays the month as a number without leading zero (1-12). If the m specifier immediatel follows an h or hh specifier, the minute rather than month is displayed.
mm	Displays the month as a number with a leading zero (01-12). If the mm specifier immediatel follows an h or hh specifier, the minute rather than month is displayed.
mmm	Displays the month as an abbreviation (Jan-Dec)
mmmm	Displays the month as a full name (January-December)
yy	Displays the year as a two digit number (00-99)
yyyy	Displays the year as a four digit number (0000-9999)
h	Displays the hour without leading zero (0-23)
hh	Displays the hour with a leading zero (00-23)
n	Displays the minute without leading zero (0-59)
nn	Displays the minute with a leading zero (00-59)
s	Displays the second without leading zero (0-59)
ss	Displays the second with a leading zero (00-59)
z	Displays the millisecond without leading zero (0-999)
zzz	Displays the millisecond with a leading zero (000-999)
t	Displays the time using the format given by the Windows short time format
tt	Displays the time using the format given by the Windows long time format
am/pm	Uses the 12 hour clock for preceding h or hh specifier, and displays 'am' for any hours before noon and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case and the result is displayed accordingly.
a/p	Uses the 12 hour clock for preceding h or hh specifier, and displays 'a' for any hours before noon and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case and the result is displayed accordingly.
ampm	Uses the 12 hour clock for preceding h or hh specifier, and displays the windows AM symbol for any hour before noon and contents of Windows PM Symbol for any hour after noon.
/	Displays the date separator character given by the Windows date separator.
:	Displays the time separator character given by the Windows time separator.

Example:

The following example assigns 'The meeting is on Wednesday, February 15, 1995 at 10:30 AM' to the string variable S.

S:= FormatDateTime('”The meeting is on “ dddd, mmmm d , yyyy, “ at “ hh:mmAM/PM', strToDateTime('2/15/95 10:30am'));

FormatFloat- Formats a floating point value.

Declaration: function FormatFloat (const Format: String; Value: Extended): String;

The following format specifiers are supported:

Specifier	Description
0	Digit placeholder. If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the output string. Otherwise, a '0' is stored in that position in the output string.
#	Digit placeholder. If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string.
.	Decimal point. The first '.' Character in the format string determines the location of the decimal separator in the formatted value; any additional '.' Characters are ignored. The actual character used as a decimal separator in the output string is determined by the Windows decimal separator specified in the Number format of the International section in the Windows control panel.
,	Thousand separator. If the format string contains one or more ',' characters, the output will that thousand separators inserted betweeneach group of three degits to the left of the decimal point. The placement and number of ',' characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as thousand separator in the output is determined by the Windows thousand separator specified in the Number format of the International section in the Windows control panel.
E+	Scientific notation. If any of the strings 'E+', 'E-', 'e+', 'e-' are contained in the format string, the number is formatted using scientific notation. A group of upto four '0' characters can immediately follow the 'E+','E-','e+', or 'e-' to determine the minimum number of digits in the exponent. The 'E+' and 'e+' formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The 'E-' and 'e-' formats output a sign character only for negative exponents.
;	Separates sections for positive, negative and zero numbers in the format string.

The locations of the leftmost '0' before the decimal point in the format string and the rightmost '0' after the decimal point in the format string determine the range of digits that are always present in the output string.

The number being formatted is always rounded to as many decimal places as there are digit placeholders ('0' or '#') to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

To allow different formats for positive, negative and zero values, the format string can contain between one and three sections separated by semicolon.

One section: The format string applies to all values.
Two sections: The first section applies to positive values and zeros and the second section applies to negative values.
Three sections: The first section applies to positive values, the second applies to negative values and the third applies to zeros.

The following table shows some sample formats and results produced when formats are applied to different values:

Format String	Value
	1234	-1234	0.5	0
0	1234	-1234	1	0
0.00	1234.00	-1234.00	0.50	0.00
#.##	1234	-1234	.5
#,##0.00	1,234.00	-1,234.00	0.50	0.00
#,##0.00;(#,##0.00)	1,234.00	(1,234.00)	0.50	0.00
#,##0.00;;Zero	1,234.00	-1,234.00	0.50	Zero
0.000E+00	1.234E+03	-1.234E+03	5.000E-01	0.000E+00
#,###E-0	1.234E3	-1.234E3	5E-1	0E0

Datetime Functions

CurrentDate - Returns the current date.

Declaration: function CurrentDate: Date;
CurrentDateTime - Returns the current date and time.

Declaration: function CurrentDateTime: DateTime;
CurrentTime - Returns the current time.

Declaration: fnction CurrentTime: DateTime;
DayOfWeek - Returns the day of week of the specified date as an integer between 1 and 7, where Sunday is the first day of the week and Saturday is the seventh.

Declaration: function DayOfWeek (aDate: DateTime) : Integer;
DecodeDate - Breaks the value specified as the Date parameter into year, month and day values. If the given time value is less than or equal to zero, the year, month and day return parameters are all set to zero.

Declaration: procedure DecodeDate(aDate: DateTime; var Year, Month, Day: Integer);
DecodeTime - Breaks a DateTime value into hours, minutes, seconds and milliseconds.

Declaration: procedure DecodeTime( aTime: DateTime; var Hour, Min, Sec, Msec: Integer);
EncodeDate - Returns a datetime value from the values specified as the Year, month and day parameters. The year must be between 1 and 9999. Valid month values are 1 throught 12. Valid day values are 1 through 28,29,30 or 31, depending on month value. For example, the possible day values for month 2(February) are 1 through 28 or 1 through 29, depending on whether or not the year is a leap year.

Declaration: function EncodeDate( Year, Month, Day: Integer): DateTime;
EncodeTime - Encodes the given hour, minute, second and millisecond into a DateTime value. Valid hour values are 0 through 23. Valid Min and Sec values are 0 through 59. Valid MSec values are 0 through 999.

Utility Functions

MessageBeep - Plays a waveform sound.

Declaration: procedure MessageBeep
ShowMessage - Displays a message box with an OK button. The Msg parameter is the message string that appears in the message box.

Declaration: procedure ShowMessage (const Msg: string);