Iris Script

Script Language Reference
Edition: 2013


Iris, Greek goddess of the rainbow
Software that brings information
The choice to name our software Iris is well thought over. You will find remarkable unique
features that very well compare to how the Greek goddess Iris is described.

In Greek mythology, Iris is a goddess of communication. She is the messenger of the
gods, particularly Zeus and Hera, to humankind. She is pictured with wings and
personifies the rainbow. It was said that Iris leaves Mount Olympus only to deliver
messages to mankind who look to her as an advisor and guide, linking her between the
worlds of the gods and humanity.
One of the strong features of Iris SCADA and PanelWare relates to communication with the
process. No other SCADA or PanelWare software supports the same high and accurate
performance to bring process and production data to the operators, and back.

Apart from carrying messages Goddess Iris had many other tasks to perform. One
was to deliver a jug of water from the river Styx so to put whoever lies to sleep. The
Greek called her 'The source of water from above'. If the Gods argue, or if they lie
about something, Iris will get water out of the river Styx. With this water, the Gods
must pledge the truth. If they lied, they lost their immortality.
Besides the strong communication in Iris SCADA and PanelWare you also will find many smart
engineering tools that will help you to generate quickly solutions for different type of
applications. Iris SCADA and PanelWare holds a very strong event driven task handler. This
guarantees that data is always handled correctly and communicated to the different modules
(e.g. alarming, trending, visualization and more).

Travelling through all dimensions, Iris uses her gifts to prevent unnecessary suffering
by severing the silver cord that binds them to Mother Earth bringing relief from a
slow death. Though she was sometimes called upon to deliver bad news, Iris was
known as a sweet tempered Goddess with no enemies. This gave her access to the
universe and welcome in all corners of the earth and beyond.
Iris SCADA and PanelWare is independent from whatever type of control equipment. The
unique architecture is suited for a wide variety of applications. Iris SCADA and PanelWare can
be used in small stations and in large control rooms, in simple to mission critical applications.
Iris SCADA and PanelWare can be fully adjusted and new functionality can be added always.

Iris not being a mere follower and deliverer of others' messages, her other qualities
are gentle strength and communication skills born out of the art of balance. She
arrests action and creates harmony. Iris is a bringer of hope and justice through
temperance rather than force. It has been said that all the colours of the rainbow
blended together create the colour white, essence of the Spirit.
Iris SCADA and PanelWare is not comparable with regular SCADA systems. It is software
developed by engineers for engineers allowing easy and rapid application development,
saving valuable engineering time. Even changes to the application can be made without
stopping the process, if needed from a remote development station. All the different modules
in Iris SCADA and PanelWare make it an ideal platform to develop specific solutions.


Abstract
This document is the Script Language Reference for Iris, a product of Raster Products B.V.
Iris is a program build to control and visualize data from Programmable logic Controllers
(PLC) or Process Control Systems (PCS) through highly efficient data communication. Iris is
equipped with lots of extensive features, provided to create the best possible interface with
the user.

Raster Products B.V.
P.O. box 3
6620 AA DREUMEL
The Netherlands
Phone: +31 (0)487-572719
Fax: +31 (0)487-573394
E-mail: [email protected]
Website: www.raster.com


History
Edition Date Author Description
2009 16-JUL-2009 Alex Oskam Newly written for Iris V4
2011 28-JAN-2011 Alex Oskam Slightly updated
2013 10-AUG-2013 RvW Slightly updated

This document is property of Raster Products B.V. No part of it may be reproduced or used in
any form or by any means without written permission of the owner.
Although this manual is written with the most care, Raster will not be responsible for any
mistakes in this manual or damage that is a result of the information in this manual.


2001-2013 Raster Products B.V. All right reserved


Table of Contents
1. Abort - Aborts the current processing with a silent exception ...................................... 12
2. Abs - Gives the absolute value of a number (-ve sign is removed) .............................. 13
3. And - Boolean and or bitwise and of two arguments .................................................. 14
4. AnsiChar - A character type guaranteed to be 8 bits in size ........................................ 15
5. AnsiCompareStr - Compare two strings for equality .................................................... 16
6. AnsiCompareText - Compare two strings for equality, ignoring case ............................ 18
7. AnsiLowerCase - Change upper case characters in a string to lower case .................... 20
8. AnsiPos - Find the position of one string in another .................................................... 21
9. AnsiString - A data type that holds a string of AnsiChars ............................................ 22
10. AnsiUpperCase - Change lower case characters in a string to upper case .................. 24
11. Append - Open a text file to allow appending of text to the end ............................... 25
12. ArcCos - The Arc Cosine of a number, returned in radians ........................................ 27
13. ArcSin - The Arc Sine of a number, returned in radians ............................................ 28
14. ArcTan - The Arc Tangent of a number, returned in radians ..................................... 29
15. Array - A data type holding indexable collections of data .......................................... 30
16. AssignFile - Assigns a file handle to a binary or text file ........................................... 32
17. Beep - Make a beep sound ..................................................................................... 34
18. Begin - Keyword that starts a statement block ......................................................... 35
19. Boolean - Allows just True and False values ............................................................ 36
20. Break - Forces a jump out of a single loop .............................................................. 37
21. Byte - An integer type supporting values 0 to 255 ................................................... 38
22. Cardinal - The basic unsigned integer type .............................................................. 39
23. Case - A mechanism for acting upon different values of an Ordinal ........................... 40
24. ChangeFileExt - Change the extension part of a file name ........................................ 42
25. ChangePage - Change a page ................................................................................ 43
26. Char - Variable type holding a single character ........................................................ 44
27. ChDir - Change the working drive plus path for a specified drive .............................. 45
28. Chr - Convert an integer into a character ................................................................ 46
29. ClearMailBox - Clears the current MailBox................................................................ 47
30. CloseCurrentPage - Close a screen .......................................................................... 48
31. CloseFile - Closes an open file ................................................................................ 49
32. CompareStr - Compare two strings for equality ....................................................... 51
33. CompareText - Compare two strings for equality, ignoring case ................................ 53
34. CompareValue - Compare numeric values with a tolerance ....................................... 55
35. Const - Starts the definition of fixed data values ...................................................... 57
36. Continue - Forces a jump to the next iteration of a loop ........................................... 58
37. Copy - Create a copy of part of a string or an array ................................................. 59
38. Cos - The Cosine of a number ................................................................................ 60
39. CreateDir - Create a directory ................................................................................. 61
40. Currency - A floating point type with 4 decimals used for financial values ................. 62
41. CurrencyDecimals - Defines decimal digit count in the Format function ..................... 63
42. CurrencyFormat - Defines currency string placement in curr display functions ........... 64


43. CurrencyString - The currency string used in currency display functions .................... 65
44. CurrentPageName - Show the current page name ................................................... 66
45. CurrToStr - Convert a currency value to a string ...................................................... 67
46. CurrToStrF - Convert a currency value to a string with formatting............................. 68
47. Date - Gives the current date ................................................................................. 69
48. DateSeparator - The character used to separate display date fields .......................... 70
49. DateTimeToFileDate - Convert a TDateTime value to a file date/time format ............. 71
50. DateTimeToStr - Converts TDateTime date and time values to a string ..................... 73
51. DateTimeToString - Rich formatting of a TDateTime variable into a string ................. 74
52. DateToStr - Converts a TDateTime date value to a string ......................................... 77
53. DayOfTheMonth - Gives day of month index for a TDateTime value (ISO 8601) ........ 78
54. DayOfTheWeek - Gives day of week index for a TDateTime value (ISO 8601) ........... 79
55. DayOfTheYear - Gives the day of the year for a TDateTime value (ISO 8601) ........... 80
56. DayOfWeek - Gives day of week index for a TDateTime value .................................. 81
57. DaysBetween - Gives the whole number of days between 2 dates ............................ 82
58. DaysInAMonth - Gives the number of days in a month ............................................. 83
59. DaysInAYear - Gives the number of days in a year .................................................. 84
60. DaySpan - Gives the fractional number of days between 2 dates .............................. 85
61. Dec - Decrement an ordinal variable ....................................................................... 86
62. DecimalSeparator - The character used to display the decimal point ......................... 87
63. DecodeDate - Extracts the year, month, day values from a TDateTime var. .............. 88
64. DecodeTime - Break a TDateTime value into individual time values .......................... 89
65. DegToRad - Convert a degrees value to radians ...................................................... 90
66. Delete - Delete a section of characters from a string ................................................ 91
67. DeleteFile - Delete a file specified by its file name ................................................... 92
68. DirectoryExists - Returns true if the given directory exists ........................................ 94
69. Div - Performs integer division, discarding the remainder ......................................... 95
70. Do - Defines the start of some controlled action ...................................................... 96
71. Double - A floating point type supporting about 15 digits of precision ....................... 97
72. Downto - Prefixes an decremental for loop target value ........................................... 98
73. Else - Starts false section of if, case and try statements ........................................... 99
74. EncodeDate - Build a TDateTime value from year, month and day values ............... 101
75. EncodeDateTime - Build a TDateTime value from day and time values .................... 102
76. EncodeTime - Build a TDateTime value from hour, min, sec and msec values.......... 103
77. End - Keyword that terminates statement blocks ................................................... 104
78. EndOfADay - Generate a TDateTime value set to the very end of a day .................. 105
79. EndOfAMonth - Generate a TDateTime value set to the very end of a month .......... 106
80. Eof - Returns true if a file opened with Reset is at the end ..................................... 107
81. Erase - Erase a file............................................................................................... 109
82. Except - Starts the error trapping clause of a try statement .................................... 110
83. Exit - exit abruptly from a function or procedure .................................................... 111
84. Exp - Gives the exponent of a number .................................................................. 112
85. ExpandMailBox - Expands a MailBox ..................................................................... 113
86. ExpandPowerTree - Expands a PowerTree ............................................................ 114


87. ExtractFileDir - Extracts the dir part of a full file name ........................................... 115
88. ExtractFileDrive - Extracts the drive part of a full file name .................................... 116
89. ExtractFileExt - Extracts the extension part of a full file name ................................. 117
90. ExtractFileName - Extracts the name part of a full file name ................................... 118
91. ExtractFilePath - Extracts the path part of a full file name ...................................... 119
92. File - Defines a typed or untyped file .................................................................... 120
93. FileAge - Get the last modified date/time of a file without opening it ...................... 122
94. FileDateToDateTime - Converts a file date/time format to a TDateTime value ......... 123
95. FileExists - Returns true if the given file exists ....................................................... 124
96. FileGetAttr - Gets the attributes of a file ................................................................ 126
97. FileSearch - Search for a file in one or more directories .......................................... 129
98. FileSetDate - set the last modified date and time of a file ....................................... 131
99. Finally - Starts the unconditional code section of a try statement ............................ 133
100. FloatToStr - Convert a floating point value to a string .......................................... 135
101. FloatToStrF - Convert a floating point value to a string with formatting ................ 136
102. Flush - Flushes buffered text file data to the file .................................................. 139
103. For - Starts a loop that executes a finite number of times .................................... 141
104. ForceDirectories - Create a new path of directories ............................................. 142
105. Format - Rich formatting of numbers and text into a string .................................. 143
106. FormatCurr - Rich formatting of a currency value into a string ............................. 146
107. FormatDateTime - Rich formatting of a TDateTime variable into a string .............. 149
108. FormatFloat - Rich formatting of a floating point number into a string .................. 154
109. Frac - The fractional part of a floating point number ............................................ 157
110. Function - Defines a subroutine that returns a value ............................................ 158
111. GetCurrentDir - Get the current directory (drive plus directory) ............................ 161
112. GetDir - Get the default directory (drive plus path) for a specified drive ................ 162
113. GetPageDir - Returns the page directory ............................................................. 163
114. GetTagProp - Reads a property of a tag.............................................................. 164
115. GetTagValue - Reads the value of a tag .............................................................. 166
116. Goto - Forces a jump to a label, regardless of nesting ......................................... 169
117. If - Starts a conditional expression to determine what to do next ......................... 170
118. Implementation - Starts the implementation (code) section of a unit .................... 172
119. Inc - Increment an ordinal variable .................................................................... 175
120. IncDay - Increments a TDateTime variable by + or - number of days ................... 176
121. IncMillisecond - Increments a TDateTime variable by + or - number of mseconds . 177
122. IncMinute - Increments a TDateTime variable by + or - number of minutes .......... 178
123. IncMonth - Increments a TDateTime variable by a number of months .................. 179
124. IncSecond - Increments a TDateTime variable by + or - number of seconds ......... 180
125. IncYear - Increments a TDateTime variable by a number of years ........................ 181
126. Infinity - Floating point value of infinite size ........................................................ 182
127. InputBox - Display a dialog that asks for user text input, with default ................... 183
128. InputQuery - Display a dialog that asks for user text input ................................... 184
129. Insert - Insert a string into another string ........................................................... 185
130. Int - The integer part of a floating point number as a float .................................. 186


131. Integer - The basic Integer type ........................................................................ 187
132. Interface - Used for definitions ........................................................................... 188
133. IntToHex - Convert an Integer into a hexadecimal string ..................................... 191
134. IntToStr - Convert an integer into a string .......................................................... 192
135. IsInfinite - Checks whether a floating point number is infinite .............................. 193
136. IsLeapYear - Returns true if a given calendar year is a leap year .......................... 194
137. LastDelimiter - Find the last position of selected characters in a string .................. 195
138. Length - Return the number of elements in an array or string .............................. 196
139. LinkedPopup - Open a Linked Popup .................................................................. 197
140. Ln - Gives the natural logarithm of a number ...................................................... 198
141. Log10 - Gives the log to base 10 of a number ..................................................... 199
142. LongDateFormat - Long version of the date to string format ................................ 200
143. LongInt - An Integer whose size is guaranteed to be 32 bits ................................ 201
144. LongTimeFormat - Long version of the time to string format ................................ 202
145. LowerCase - Change upper case characters in a string to lower case .................... 203
146. Max - Gives the maximum of two integer values ................................................. 204
147. MessageBox - Displays a message, symbol, and selectable buttons ...................... 205
148. MessageDlg - Displays a message, symbol, and selectable buttons ....................... 206
149. MessageDlgPos - Displays a message plus buttons at a given screen position ....... 208
150. Min - Gives the minimum of two integer values ................................................... 210
151. MinsPerDay - Gives the number of minutes in a day ............................................ 211
152. MkDir - Make a directory .................................................................................... 212
153. Mod - Performs integer division, returning the remainder..................................... 213
154. ModalPopup - Open a Modal Popup .................................................................... 214
155. MonthOfTheYear - Gives the month of the year for a TDateTime value ................. 215
156. NegCurrFormat - Defines negative amount formatting in currency displays ........... 216
157. Not - Boolean not or bitwise not of one arguments .............................................. 218
158. Now - Gives the current date and time ............................................................... 219
159. Null - A variable that has no value ...................................................................... 220
160. NumEditor - Shows a numerical popup to write the value of a tag ........................ 222
161. Or - Boolean or or bitwise or of two arguments ................................................... 224
162. Ord - Provides the Ordinal value of an integer, character or enum........................ 225
163. PageBack - Show Previous Page ......................................................................... 227
164. PageForward - Show Next Page ......................................................................... 228
165. Pi - The mathematical constant .......................................................................... 229
166. Popup - Open a Popup ...................................................................................... 230
167. Pos - Find the position of one string in another ................................................... 231
168. Pred - Decrement an ordinal variable .................................................................. 232
169. Private - Starts the section of private data and methods in a class ....................... 233
170. Procedure - Defines a subroutine that does not return a value ............................. 234
171. PtInRect - Tests to see if a point lies within a rectangle ....................................... 237
172. Public - Starts an externally accessible section of a class...................................... 238
173. RadToDeg - Converts a radian value to degrees .................................................. 239
174. Random - Generate a random floating point or integer number ............................ 240


175. Randomize - Reposition the Random number generator next value ...................... 242
176. RandomRange - Generate a random integer number within a supplied range........ 244
177. RandSeed - Reposition the Random number generator next value ........................ 245
178. ReadLn - read a complete line of data from a text file ......................................... 247
179. ReadRecipe - read a recipe file. .......................................................................... 249
180. RecodeDate - Change only the date part of a TDateTime variable ........................ 250
181. RecodeTime - Change only the time part of a TDateTime variable ........................ 251
182. RemoveDir - Remove a directory ........................................................................ 252
183. RemoveMailBox - Removes a MailBox ................................................................. 253
184. Rename - Rename a file .................................................................................... 254
185. Repeat - repeat statements until a ternmination condition is met ......................... 256
186. ReplaceDate - Change only the date part of a TDateTime variable ....................... 258
187. ReplaceTime - Change only the time part of a TDateTime variable ....................... 259
188. Result - A variable used to hold the return value from a function ......................... 260
189. ReWrite - Open a text or binary file for write access ............................................ 261
190. RmDir - Remove a directory ............................................................................... 263
191. Round - Rounds a floating point number to an integer ......................................... 264
192. SecsPerDay - Gives the number of seconds in a day ............................................ 265
193. SetCurrentDir - Change the current directory ...................................................... 266
194. SetMailBox - Sets a MailBox to a specific value .................................................... 267
195. SetPageDir - Sets the page directory .................................................................. 268
196. SetTagValue - Sets a value of a tag .................................................................... 269
197. Shl - Shift an integer value left by a number of bits ............................................. 272
198. ShortDateFormat - Compact version of the date to string format .......................... 273
199. ShortInt - An integer type supporting values -128 to 127 ..................................... 274
200. ShortString - Defines a string of up to 255 characters .......................................... 275
201. ShortTimeFormat - Short version of the time to string format .............................. 276
202. ShowMessage - Display a string in a simple dialog with an OK button ................... 277
203. ShowMessageFmt - Display formatted data in a simple dialog with an OK button .. 278
204. ShowMessagePos - Display a string in a simple dialog at a given screen position ... 281
205. Shr - Shift an integer value right by a number of bits .......................................... 282
206. Sin - The Sine of a number ................................................................................ 283
207. Single - The smallest capacity and precision floating point type ............................ 284
208. SmallInt - An Integer type supporting values from -32768 to 32767 ..................... 285
209. Sqr - Gives the square of a number .................................................................... 286
210. Sqrt - Gives the square root of a number ............................................................ 287
211. StopRunTime - Stops the runtime....................................................................... 288
212. String - A data type that holds a string of characters ........................................... 289
213. StringReplace - Replace one or more substrings found within a string .................. 290
214. StrToCurr - Convert a number string into a currency value ................................... 291
215. StrToDate - Converts a date string into a TDateTime value .................................. 293
216. StrToDateTime - Converts a date+time string into a TDateTime value .................. 294
217. StrToFloat - Convert a number string into a floating point value ........................... 295
218. StrToInt - Convert an integer string into an Integer value .................................... 296


219. StrToIntDef - Convert a string into an Integer value with default ......................... 298
220. StrToTime - Converts a time string into a TDateTime value ................................. 300
221. Succ - Increment an ordinal variable .................................................................. 301
222. Tan - The Tangent of a number ......................................................................... 302
223. TBits - An object that can hold an infinite number of Boolean values .................... 303
224. TDateTime - Data type holding a date and time value ......................................... 305
225. TextFile - Declares a file type for storing lines of text .......................................... 306
226. TFloatFormat - Formats for use in floating point number display functions ............ 308
227. TFormatSettings - A record for holding locale values ........................................... 311
228. Then - Part of an if statement - starts the true clause.......................................... 313
229. ThousandSeparator - The character used to display the thousands separator ........ 315
230. Time - Gives the current time ............................................................................ 316
231. TimeAMString - Determines AM value in DateTimeToString procedure .................. 317
232. TimePMString - Determines PM value in DateTimeToString procedure .................. 318
233. TimeSeparator - The character used to separate display time fields ...................... 319
234. TimeToStr - Converts a TDateTime time value to a string .................................... 320
235. To - Prefixes an incremental for loop target value ............................................... 321
236. Tomorrow - Gives the date tomorrow ................................................................. 322
237. Trim - Removes leading and trailing blanks from a string ..................................... 323
238. TrimLeft - Removes leading blanks from a string ................................................. 324
239. TrimRight - Removes trailing blanks from a string ............................................... 325
240. Trunc - The integer part of a floating point number ............................................. 326
241. Try - Starts code that has error trapping ............................................................. 327
242. TStringList - Holds a variable length list of strings ............................................... 330
243. TwoDigitYearCenturyWindow - Sets the century threshold for 2 digit years ........... 334
244. Unit - Defines the start of a script file ................................................................. 335
245. Until - Ends a repeat control loop ....................................................................... 338
246. UpperCase - Change lower case characters in a string to upper case .................... 340
247. Uses - Declares a list of Units to be imported ...................................................... 341
248. Var - Starts the definition of a section of data variables ....................................... 344
249. Variant - A variable type that can hold changing data types ................................. 346
250. VarType - Gives the current type of a Variant variable ......................................... 347
251. VarTypeMask - Mask for the meta-type part of a Variant variable ......................... 350
252. While - repeat statements whilst a continuation condition is met .......................... 353
253. WideString - A data type that holds a string of WideChars ................................... 355
254. Word - An integer type supporting values 0 to 65535 .......................................... 357
255. WriteLn - write a complete line of data to a text file ............................................ 358
256. WriteRecipe - write a recipe file.......................................................................... 360
257. WriteTagValue - Writes a value of a tag .............................................................. 361
258. Xor - Boolean xor or bitwise xor of two arguments .............................................. 364
259. Yesterday - Gives the date yesterday.................................................................. 365

Error! Use the Home tab to apply Kop 1 to the text that you
want to appear here.Error! Use the Home tab to apply Kop 1
to the text that you want to appear here.

Page 12 of 366

1. Abort - Aborts the current processing with a silent
exception
1.1. Unit
SysUtils
1.2. Type
Procedure
1.3. Description
The Abort procedure stops the current processing and exits to the last exception block. In
doing so, no end user message is produced - the abort is silent.
1.4. Syntax
procedure Abort;
1.5. Example
1.5.1. Name
Aborting from a try block
1.5.2. Code
begin
// enter a try block
try
ShowMessage('Before abort');
Abort;
ShowMessage('After abort');
except
ShowMessage('Exception occurred');
end;
ShowMessage('After try');
end;
1.5.3. Result
Before abort
Exception occurred
After try


Page 13 of 366

2. Abs - Gives the absolute value of a number (-ve sign is
removed)
2.1. Unit
System
2.2. Type
Function
2.3. Description
The Abs function returns the absolute value of a negative or positive number. It does this by
removing a negative sign, if found. The Number can be any numeric type, and can even be a
Variant, as long as it can be converted to a number. For example, a Variant set to a string '-
1.23' will work fine. Always, Abs converts the Variant to an Extended floating point number
prior to removing any negative sign, even if the result is an integer value.
2.4. Syntax
function Abs(Number : Numeric type) : Numeric type;
2.5. Example
2.5.1. Name
Illustrating absolute values of different data types
2.5.2. Code
var
float : single;
int : Integer;
varVar : Variant;

begin
float := -1.5; // small negative floating point number
int := -7; // negative integer
varVar := '-98'; // variants are converted to floating point!

ShowMessage('Abs(float) = '+FloatToStr(Abs(float)));
ShowMessage('Abs(int) = '+FloatToStr(Abs(int)));

// variants are converted into extended floating types
float := Abs(varVar);
ShowMessage('Abs(varVar) = '+FloatToStr(float));
end;
2.5.3. Result
Abs(float) = 1.5
Abs(int) = 7
Abs(varVar) = 98


Page 14 of 366

3. And - Boolean and or bitwise and of two arguments
3.1. Unit
Iris Standard
3.2. Type
Keyword
3.3. Description
The and keyword is used in two different ways: 1. to perform a logical or Boolean 'and' of
two logical values. If both are true, then the result is true, otherwise, the result is false. 2. To
perform a mathematical 'and' of two integers. The result is a bitwise 'and' of the two
numbers. For example: 10110001 and 01100110 = 00100000
3.4. Syntax
1 Boolean expression and Boolean expression
2 Integer expression and Integer expression
3.5. Example
3.5.1. Name
Illustrate both types of and usage
3.5.2. Code
var
num1, num2, num3 : Integer;
letter : Char;

begin
num1 := $25; // binary value : 0010 0101
num2 := $32; // binary value : 0011 0010
// and-ed value : 0010 0000 = $20 = 32 dec
letter := 'G';

// and used to return a boolean value
if (num1 > 0) and (letter = 'G')
then ShowMessage('Both values are true')
else ShowMessage('None or only one true value');

// and used to perform a mathematical and operation
num3 := num1 and num2;

ShowMessageFmt('$25 and $32 = $%x',[num3]);
end;
3.5.3. Result
Both values are true
$25 and $32 = $20


Page 15 of 366

4. AnsiChar - A character type guaranteed to be 8 bits in
size
4.1. Unit
System
4.2. Type
Type
4.3. Description
The AnsiChar type is used to hold single characters. It is guaranteed to be 8 bits in size. It
can be assigned from a character or integer value.
4.4. Syntax
type AnsiChar = #0..#255;
4.5. Example
4.5.1. Name
Different ways of assigning to and from an AnsiChar
4.5.2. Code
var
myChar : AnsiChar;

begin
myChar := 'g'; // assign from a character constant
ShowMessage('Letter g = '+myChar);

myChar := #65; // assign from an integer constant
ShowMessage('#65 = '+myChar);

myChar := Chr(66); // using chr to convert a number
ShowMessage('Chr(66) = '+myChar);
end;
4.5.3. Result
Letter g = g
#65 = A
Chr(66) = B


Page 16 of 366

5. AnsiCompareStr - Compare two strings for equality
5.1. Unit
SysUtils
5.2. Type
Function
5.3. Description
The AnsiCompareStr function compares String1 and String2 for equality. This is the modern,
Locale safe form of CompareStr. All Ansi commands support multi-byte and accented
characters. It returns these values: String1 < String2 : -ve numberString1 = String2 :
0String1 > String2 : +ve number The comparison is not affected by length - it is carried out
on a letter by letter basis. But a longer string is greater than a shorter, otherwise matching
string. The comparison is case sensitive.
5.4. Syntax
function AnsiCompareStr(const String1, String2 : string) : Integer;


Page 17 of 366

5.5. Example
5.5.1. Name
Compare various strings
5.5.2. Code
// remember to declare the procedure at type using the following line
// procedure comparestrings(const string1, string2: string);

begin
// compare two obviously different strings
CompareStrings('HELLO', 'WORLD');
// compare identical strings
CompareStrings('Hi 2 you', 'Hi 2 you');
// upper case letters follow lower case in iris
CompareStrings('ABC', 'abc');

// all letters follow numbers in iris
CompareStrings('abc', '123');
end;

// compare two strings, and show which is bigger than the other
procedure TUntitled.CompareStrings(const string1, string2: string);
var
result : Integer;
begin
// compare some strings
result := AnsiCompareStr(string1, string2);

if result < 0 then ShowMessage(string1+' < '+string2);
if result = 0 then ShowMessage(string1+' = '+string2);
if result > 0 then ShowMessage(string1+' > '+string2);
end;
5.5.3. Result
HELLO < WORLD
Hi 2 you = Hi 2 you
ABC > abc
abc > 123


Page 18 of 366

6. AnsiCompareText - Compare two strings for equality,
ignoring case
6.1. Unit
SysUtils
6.2. Type
Function
6.3. Description
The AnsiCompareText function compares String1 and String2 for equality, ignoring case. This
is the modern, Locale safe form of CompareStr. All Ansi commands support multi-byte and
accented characters. It returns these values: String1 < String2 : -ve numberString1 = String2
: 0String1 > String2 : +ve number The comparison is not affected by length - it is carried out
on a letter by letter basis. But a longer string is greater than a shorter, otherwise matching
string.
6.4. Syntax
function AnsiCompareText(const String1, String2 : string) : Integer;


Page 19 of 366

6.5. Example
6.5.1. Name
6.5.2. Code

begin


// ansicomparetext treats upper and lower case identically
CompareStrings('ABCdef', 'abcDEF');

end;

var
result : Integer;
begin
result := AnsiCompareText(string1, string2);

end;
6.5.3. Result
HELLO < WORLD
Hi 2 you = Hi 2 you
ABCdef = abcDEF
abc > 123


Page 20 of 366

7. AnsiLowerCase - Change upper case characters in a
string to lower case
7.1. Unit
SysUtils
7.2. Type
Function
7.3. Description
The AnsiLowerCase function creates a copy of MixedString with all letters converted to lower
case. All Ansi commands support multi-byte and accented characters.
7.4. Syntax
function AnsiLowerCase(const MixedString : string) : string;
7.5. Example
7.5.1. Name
Converting a mixed case string to lower case
7.5.2. Code
var
SimpleString : string;

begin
SimpleString := AnsiLowerCase('The Cat Sat on The MAT');
ShowMessage('SimpleString : '+SimpleString);
end;
7.5.3. Result
SimpleString : the cat sat on the mat


Page 21 of 366

8. AnsiPos - Find the position of one string in another
8.1. Unit
SysUtils
8.2. Type
Function
8.3. Description
The AnsiPos function looks for a substring Needle in a string HayStack, returning the position
in the string of the first occurrence. All Ansi commands support multi-byte and accented
characters. if the string is not found, 0 is returned. The search is case sensitive.
8.4. Syntax
function AnsiPos(const Needle, HayStack : string) : Integer;
8.5. Example
8.5.1. Name
Find a word in a sentence
8.5.2. Code
var
position : Integer;

begin
// look for the word 'cat' in a sentence
// note : that this search is case sensitive, so that
// the first 'cat' is not matched
position := AnsiPos('Cat', 'The cat sat on the Cat mat');
if position = 0
then ShowMessage('''Cat'' not found in the sentence')
else ShowMessage('''Cat'' was found at character '+IntToStr(position));
end;
8.5.3. Result
'Cat' was found at character 20


Page 22 of 366

9. AnsiString - A data type that holds a string of
AnsiChars
9.1. Unit
System
9.2. Type
Type
9.3. Description
The AnsiString data type is used to hold sequences of characters, like sentences. Each
character is an AnsiChar, guaranteed to be 8 bits in size. An AnsiString can hold any number
of characters, restricted only by memory. Unlike ShortStrings, AnsiStrings are pointer
referenced variables. Storage is allocated for an AnsiString only when needed. for example,
assigning the value of one AnsiString to another does not allocate storage for a copy of the
first string. Instead, the reference count of the first string is incremented, and the second
AnsiString set to point to it. But when the second string is changed, new storage is obtained
for this new string, and the reference count for the first string is decremented. AnsiStrings
can be assigned from other strings, from functions that return a string, and with
concatenations as in the sample code.
9.4. Syntax
type AnsiString;


Page 23 of 366

9.5. Example
9.5.1. Name
Assign to two AnsiStrings and manipulate these
9.5.2. Code
var
string1, string2 : AnsiString;
begin
// assign a famous sentence to the first string
string1 := 'Hello World';

// assign to the second string
// this simply points string2 at string1
// the 'hello world' string storage has a reference count of 2
string2 := string1;

// add to the second string
// this disassociates from string1 - new string storage is
// created to hold the string2 value
string2 := string2 + ', how is everyone?';

// and finally, set the length of the first string to 5
SetLength(string1, 5);

// display both strings
ShowMessage('String1 = '+string1);
end;
9.5.3. Result
String1 = Hello
String2 = Hello World, how is everyone?


Page 24 of 366

10. AnsiUpperCase - Change lower case characters in a
string to upper case
10.1. Unit
SysUtils
10.2. Type
Function
10.3. Description
The AnsiUpperCase function creates a copy of MixedString with all letters converted to upper
case. All Ansi commands support multi-byte and accented characters.
10.4. Syntax
function AnsiUpperCase(const MixedString : string) : string;
10.5. Example
10.5.1. Name
Converting a mixed case string to upper case
10.5.2. Code
var

begin
SimpleString := AnsiUpperCase('The Cat Sat on The MAT');
end;
10.5.3. Result
SimpleString : THE CAT SAT on THE MAT


Page 25 of 366

11. Append - Open a text file to allow appending of text to
the end
11.1. Unit
System
11.2. Type
Procedure
11.3. Description
The Append procedure opens a file given by FileHandle to allow subsequent writes to append
to the end of the file. You must use AssignFile to assign a file to the FileHandle before using
Append. This is often used when logging information - existing log data must be preserved,
with the new log information appended to the end. Use write or WriteLn to write to the file
after this Append is executed.
11.4. Syntax
procedure Append(var FileHandle : TextFile);


Page 26 of 366

11.5. Example
11.5.1. Name
Appending a line of text to an existing file
11.5.2. Code
var
myFile : TextFile;
text : string;

begin
// try to open the test.txt file for writing to
AssignFile(myFile, 'Test.txt');
ReWrite(myFile);

// write a couple of well known words to this file
WriteLn(myFile, 'Hello');
WriteLn(myFile, 'World');

// close the file
CloseFile(myFile);

// reopen to append a final line to the file
Append(myFile);

// write this final line
WriteLn(myFile, 'Final line added');

// close the file
CloseFile(myFile);

// reopen the file for reading
Reset(myFile);

// display the file contents
while not Eof(myFile) do
begin
ReadLn(myFile, text);
ShowMessage(text);
end;

// close the file for the last time
CloseFile(myFile);
end;
11.5.3. Result
Hello
World
Final line added


Page 27 of 366

12. ArcCos - The Arc Cosine of a number, returned in
radians
12.1. Unit
Math
12.2. Type
Function
12.3. Description
The ArcCos function is a mathematical function giving the value in radians of the Arc Cosine
of Number. PI radians = 180 degrees
12.4. Syntax
function ArcCos(const Number : Extended) : Extended;
12.5. Example
12.5.1. Name
The ArcCos of 0.5 gives 60 degrees
12.5.2. Code
var
float : single;
begin
// the arccos of 0.5 should give 60 degrees
float := ArcCos(0.5);
float := RadToDeg(float); // convert result to degrees
ShowMessage('ArcCos of 0.5 = '+FloatToStr(float)+' degrees');
end;
12.5.3. Result
ArcCos of 0.5 = 60 degrees


Page 28 of 366

13. ArcSin - The Arc Sine of a number, returned in radians
13.1. Unit
Math
13.2. Type
Function
13.3. Description
The ArcSin function is a mathematical function giving the value in radians of the Arc Sine of
Number. PI radians = 180 degrees
13.4. Syntax
function ArcSin(const Number : Extended) : Extended;
13.5. Example
13.5.1. Name
The ArcSin of 0.5 gives 30 degrees
13.5.2. Code
var
float : single;
begin
// the arcsin of 0.5 should give 30 degrees
float := ArcSin(0.5);
ShowMessage('ArcSin of 0.5 = '+FloatToStr(float)+' degrees');
end;
13.5.3. Result
ArcSin of 0.5 = 30 degrees


Page 29 of 366

14. ArcTan - The Arc Tangent of a number, returned in
radians
14.1. Unit
System
14.2. Type
Function
14.3. Description
The ArcTan function is a mathematical function giving the value in radians of the Arc Tangent
of Number. PI radians = 180 degrees
14.4. Syntax
function ArcTan(const Number : Extended) : Extended;
14.5. Example
14.5.1. Name
Get the ArcTan of PI/2
14.5.2. Code
var
float : single;
begin
// the arctan of pi/2 should give 1.0
float := ArcTan(PI/2);
ShowMessage('ArcTan of PI/2 = '+FloatToStr(float));
end;
14.5.3. Result
ArcTan of PI/2 = 1.00388479232788


Page 30 of 366

15. Array - A data type holding indexable collections of
data
15.1. Unit
Iris Standard
15.2. Type
Keyword
15.3. Description
The array keyword provides single and multi dimensional arrays (indexable sequences) of
data. Arrays in Iris always have a fixed, unchangeable size. They may be single or
multidimensional - the latter being an array of arrays (of arrays etc). The size and range of
such a multidimensional array is always given for the highest, leftmost array - the parent
array.
15.4. Syntax
type Name = array[index type|Ordinal..Ordinal {,...}] of Base type;
15.5. Example 1
15.5.1. Name
Declaring and using arrays
15.5.2. Code
var
IntArr : array[0..20] of integer;
i : Integer;
begin
// use indexing to furnish an array
for i := 5 to 20 do
IntArr[i] := i * 5;

// now use indexing to display 2 of the elements
ShowMessage('element 7 = '+IntToStr( IntArr[7] ));
ShowMessage('element 20 = '+IntToStr( IntArr[20] ));
end;
15.5.3. Result
element 7 = 35
element 20 = 100


Page 31 of 366

15.6. Example 2
15.6.1. Name
Declaring and using multidimensional arrays
15.6.2. Code
var
FloatArr : array[0..9,20..29] of single;
x,y : Integer;
begin
// use indexing to furnish an array
for x := 0 to 9 do
begin
for y := 20 to 29 do
FloatArr[x,y] := x+(y/100);
end;

// now use indexing to display 2 of the elements
ShowMessage('coordinate [3,24] = '+FloatToStr( FloatArr[3,24] ));
ShowMessage('coordinate [8,22] = '+FloatToStr( FloatArr[8,22] ));
end;
15.6.3. Result
coordinate [3,24] = 3.24
coordinate [8,22] = 8.22


Page 32 of 366

16. AssignFile - Assigns a file handle to a binary or text file
16.1. Unit
System
16.2. Type
Procedure
16.3. Description
The AssignFile procedure assigns a value to FileHandle for a FileName in preparation for
reading or writing to that file. Takes a text file variable type as the handle. The file is treated
as a textfile when opened. if the file name is an empty string, then file access is made to the
console standard input and output streams.
16.4. Syntax
procedure AssignFile(var FileHandle : TextFile; const FileName : string);


Page 33 of 366

16.5. Example
16.5.1. Name
write to a text file, and then read back its contents
16.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
16.5.3. Result
Hello
World


Page 34 of 366

17. Beep - Make a beep sound
17.1. Unit
SysUtils
17.2. Type
Procedure
17.3. Description
The Beep procedure creates a very short and quiet sound through the internal speaker of
your PC. It is used as an indication that the user has done something wrong.
17.4. Syntax
procedure Beep;
17.5. Example
17.5.1. Name
Very simple!
17.5.2. Code
begin
Beep;
end;
17.5.3. Result
No result specified


Page 35 of 366

18. Begin - Keyword that starts a statement block
18.1. Unit
Iris Standard
18.2. Type
Keyword
18.3. Description
The begin keyword is fundamental to Iris - it starts statement blocks. The begin-end pair
fence in a set of statements. You may place such a block anywhere in your code. It is
particularly sensible in if and for statements, even if only one statement is required. It means
that adding an additional statement in the future is easy.
18.4. Syntax
begin
Statements
end
18.5. Example
18.5.1. Name
Some examples of the begin statement
18.5.2. Code
var
myChars : array[1..2] of char;
myBytes : array[1..2] of Byte;
i : Integer;

// the begin statement always starts the code part of a subroutine
begin
// use a for block to assign to both arrays
for i := 1 to 2 do
begin
myChars[i] := Chr(i+64);
myBytes[i] := i+64;
end;

// use a for block to observe the contents
for i := 1 to 2 do
begin
ShowMessage('myChars['+IntToStr(i)+'] = '+myChars[i]);
ShowMessage('myBytes['+IntToStr(i)+'] = '+IntToStr(myBytes[i]));
end;
end;
18.5.3. Result
myChars[1] = A
myBytes[1] = 65
myChars[2] = B
myChars[2] = 66


Page 36 of 366

19. Boolean - Allows just True and False values
19.1. Unit
System
19.2. Type
Type
19.3. Description
The Boolean type provides an enumeration of the logical True and False values. Unlike other
languages, it is not a number - it will only allow these values. This makes the code much
more reliable.
19.4. Syntax
type Boolean = (False, True);
19.5. Example
19.5.1. Name
Boolean assignments and tests
19.5.2. Code
var
same : Boolean;
small, large, i : Integer;

begin
small := 23;
large := 455555;

// test directly to see if these numbers are the same size
if small = large
then ShowMessage('small = large')
else ShowMessage('small <> large');

// use a boolean to hold and test this outcome
same := (small = large);
if same
then ShowMessage('small = large')
else ShowMessage('small <> large');

// assign a direct logical value to this boolean
same := True;
if same
then ShowMessage('same is True')
else ShowMessage('same is False');
end;
19.5.3. Result
small <> large
small <> large
same is True


Page 37 of 366

20. Break - Forces a jump out of a single loop
20.1. Unit
System
20.2. Type
Procedure
20.3. Description
The Break procedure forces a jump out of the setof statements within a loop. Like the goto
statement, it should be used with caution. It is important to note that the Break statement
only jumps out of the current loop - not out of any nested loops above it. The goto statement
can.
20.4. Syntax
procedure Break;
20.5. Example
20.5.1. Name
Breaking out of a loop for good reason
20.5.2. Code
var
i : Integer;
s : string;

begin
s := '';

// a big loop
for i := 1 to 10 do
begin
s := s + IntToStr(i) + ' ';
// exit loop when a certain condition is met
if Random(4) = 2 then Break;
end;

ShowMessage('i = '+IntToStr(i));
ShowMessage('s = '+s);
end;
20.5.3. Result
i = 6
s = 1 2 3 4 5 6


Page 38 of 366

21. Byte - An integer type supporting values 0 to 255
21.1. Unit
System
21.2. Type
Type
21.3. Description
The Byte type is the smallest form of integer, occupying 8 bits (1 byte) of storage. It supports
only the positive integers from 0 to 255.
21.4. Syntax
type Byte = 0..255;
21.5. Example
21.5.1. Name
Showing maximum and minimum byte values
21.5.2. Code
var
A, B : Byte;
begin
// set the values of this data type
A := 5;
B := 100;
ShowMessage('A = '+IntToStr(A)+' and B = '+IntToStr(B));
ShowMessage('A + B = '+IntToStr(A+B));
end;
21.5.3. Result
A = 5 and B = 100
A + B = 100


Page 39 of 366

22. Cardinal - The basic unsigned integer type
22.1. Unit
System
22.2. Type
Type
22.3. Description
The Cardinal type is an Integer whose size is not guaranteed. It is the basic unsigned integer
type, and currently has the same capacity as the LongWord: 32 bits. to hold very large
integers, use the Int64 type.
22.4. Syntax
type Cardinal = 0..4294967295; // at the time of writing
22.5. Example
22.5.1. Name
Showing the capacity of Cardinal
22.5.2. Code
var
A, B : Cardinal;
begin
A := 1;
B := 999999;
end;

22.5.3. Result
A = 1 and B = 999999
A + B = 1000000


Page 40 of 366

23. Case - A mechanism for acting upon different values of
an Ordinal
23.1. Unit
Iris Standard
23.2. Type
Keyword
23.3. Description
The case keyword provides a structured equivalent to a sequence of if statements on the
same variable. The case statement is more elegant, more efficient, and easier to maintain
than multiple if nestings.
23.4. Syntax
1 case Ordinal expression of
Ordinal value {,ordinal value...} : Statement;
{...}
else Statement;
end;


Page 41 of 366

23.5. Example
23.5.1. Name
Standard case statement usage
23.5.2. Code
// procedure showcolour(colour : string);

var
colour : string;
number : Integer;

begin
// show the colour before it has an assigned value
ShowColour(colour);

// now set the colour and try again
colour := 'Green';
ShowColour(colour);

// calculations can also be used in the case statement
number := 17;
case number mod 2 of
0 : ShowMessage(IntToStr(Number)+' mod 2 = 0');
1 : ShowMessage(IntToStr(Number)+' mod 2 = 1');
else ShowMessage(IntToStr(Number)+' mod 2 is unknown');
end;
end;

// procedure to show the colour of a passed
procedure TUntitled.ShowColour(colour : string);
begin
// use a case statement to see the colour of the passed var
// note how important the else clause is, even though we have
// apparently covered all string values!
case colour of
'Red' : ShowMessage('The colour is Red');
'Green' : ShowMessage('The colour is Green');
'Blue' : ShowMessage('The colour is Blue');
'Yellow' : ShowMessage('The colour is Yellow');
else ShowMessage('The colour is Unknown!');
end;
end;
23.5.3. Result
The colour is Unknown!
The colour is Green
17 mod 2 is 1


Page 42 of 366

24. ChangeFileExt - Change the extension part of a file
name
24.1. Unit
SysUtils
24.2. Type
Function
24.3. Description
The ChangeFileExt function changes the Extension value of a file FileName, returning the new
value as a string.
24.4. Syntax
function ChangeFileExt(const FileName, Extension : string) : string;
24.5. Example
24.5.1. Name
Renaming Test.exe to Test.bak
24.5.2. Code
var
oldName, newName : string;

begin
// try to rename the current test.exe to test.bak
oldName := 'Test.exe';
newName := ChangeFileExt(oldName, '.bak');

// show the old and new values
ShowMessage('Old name = '+oldName);
ShowMessage('New name = '+newName);
end;
24.5.3. Result
Old name = Test.exe
New name = Test.bak


Page 43 of 366

25. ChangePage - Change a page
25.1. Unit
Iris Standard
25.2. Type
Frame Function
25.3. Description
Opens a new screen instead of the active screen
25.4. Syntax
procedure ChangePage(PageName: string);
25.5. Example 1
25.5.1. Name
Open the screen 'ScreenName'
25.5.2. Code
begin
ChangePage('ScreenName');
end;
25.5.3. Result
No result specified
25.6. Example 2
25.6.1. Name
Open the screen 'ScreenName' in the frame 'FrameName'
25.6.2. Code
begin
FrameName.ChangePage('ScreenName');
end;
25.6.3. Result
No result specified


Page 44 of 366

26. Char - Variable type holding a single character
26.1. Unit
System
26.2. Type
Type
26.3. Description
The Char type is a simple variable type used to hold a single character. It can be assigned
from a character constant, or an integer.
26.4. Syntax
type : Char = #0..#255;
26.5. Example
26.5.1. Name
Different ways of assigning to and from a Char
26.5.2. Code
var
myChar : Char;

begin
myChar := 'g'; // assign from a character constant
ShowMessage('Letter g = '+myChar);

myChar := #65; // assign from an integer constant
ShowMessage('#65 = '+myChar);

myChar := Chr(66); // using chr to convert a number
ShowMessage('Chr(66) = '+myChar);
end;
26.5.3. Result
Letter g = g
#65 = A
Chr(66) = B


Page 45 of 366

27. ChDir - Change the working drive plus path for a
specified drive
27.1. Unit
System
27.2. Type
Procedure
27.3. Description
The ChDir procedure sets the working drive + path values to the supplied Directory. There
are as many working directories as drives on the target machine. if the directory is invalid,
you will get an error such as ElnOutError, and the directory will remain unchanged.
27.4. Syntax
procedure ChDir(const Directory : string);
27.5. Example
27.5.1. Name
Getting and setting the directory for the C: drive
27.5.2. Code
var
directory : string;

begin
// get the directory for the c drive
GetDir(2, directory);
ShowMessage('default C drive directory = '+directory);

// set the c directory to this value
ChDir(directory);

// try to set to an invalid value
ChDir('C:Bad/Path/Value');
end;
27.5.3. Result
The following output is representative, and will necessarily vary
from PC to PC:

C:\IrisTest
C:\IrisTest

EInOutError ('Invalid file name')

IrisTest


Page 46 of 366

28. Chr - Convert an integer into a character
28.1. Unit
System
28.2. Type
Function
28.3. Description
The Chr function converts an IntValue integer into either an AnsiChar or WideChar as
appropriate.
28.4. Syntax
function Chr(IntValue : Integer) : AnsiChar;
28.5. Example
28.5.1. Name
Showing Chr usage
28.5.2. Code
var
tab : char;
crlf : string;
begin
// show the use of chr
tab := Chr(9);
crlf := Chr(13)+Chr(10);
ShowMessage('Hello'+tab+'World');
ShowMessage('');
ShowMessage('Hello'+crlf+'World');
ShowMessage('');
end;
28.5.3. Result
Hello World

Hello
World


Page 47 of 366

29. ClearMailBox - Clears the current MailBox
29.1. Unit
Iris Standard
29.2. Type
MailBox Function
29.3. Description
Clears the current mailbox. MailBoxes can be used to pass structrured values to for example
popups.
29.4. Syntax
procedure ClearMailbox;
29.5. Example
29.5.1. Name
Using MailBoxes
29.5.2. Code
begin

// set the mailbox 'mymailbox' to the object 'unit23'
SetMailBox('MyMailBox','Unit23')

// the following could be done in a linked popup

// write a value to the tag '[mymailbox].open', - which will be unit23.open
WriteTagValue(ExpandMailbox('[MyMailBox].Open'),1);

// remove the mailbox
RemoveMailbox('MyMailBox')

// the following could be done in another linked popup

// set the mailbox 'mymailbox' to the object 'unit23.modulea'
SetMailBox('MyMailBox','Unit23.ModuleA')

// write a value to the tag '[mymailbox].status', - which will be
unit23.modulea.status

// clear the current mailbox
ClearMailbox;

end;
29.5.3. Result

Unit23.Open is written inside popup 1
Unit23.ModuleA.Status is written inside popup 2 that is a popup from popup 1


Page 48 of 366

30. CloseCurrentPage - Close a screen
30.1. Unit
Iris Standard
30.2. Type
Frame Function
30.3. Description
Closes the active screen. Note that this can also be a popup screen.
30.4. Syntax
procedure CloseCurrentPage;
30.5. Example
30.5.1. Name
Close the current screen
30.5.2. Code
begin
// closes the screen
CloseCurrentPage;
end;
30.5.3. Result
No result specified


Page 49 of 366

31. CloseFile - Closes an open file
31.1. Unit
System
31.2. Type
Procedure
31.3. Description
The CloseFile procedure closes an open file given by FileHandle. The file must have been
assigned, and opened with Append, Reset or ReWrite. The file is closed, and the handle is
made available for further assignment to files.
31.4. Syntax
procedure CloseFile(var FileHandle : TextFile);


Page 50 of 366

31.5. Example
31.5.1. Name
Closing after write and read operations
31.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

// reopen the file in read only mode
Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
31.5.3. Result
Hello
World


Page 51 of 366

32. CompareStr - Compare two strings for equality
32.1. Unit
SysUtils
32.2. Type
Function
32.3. Description
The CompareStr function compares String1 and String2 for equality. It returns these values :
String1 < String2 : -ve numberString1 = String2 : 0String1 > String2 : +ve number The
comparison is not affected by length - it is carried out on a letter by letter basis. But a longer
string is greater than a shorter, otherwise matching string. The comparison is case sensitive.
32.4. Syntax
function CompareStr(const String1, String2 : string) : Integer;


Page 52 of 366

32.5. Example
32.5.1. Name
32.5.2. Code

begin


// upper case letters follow lower case in iris
CompareStrings('ABC', 'abc');

end;

var
result : Integer;
begin
result := CompareStr(string1, string2);

end;
32.5.3. Result
HELLO < WORLD
Hi 2 you = Hi 2 you
ABC > abc
abc > 123


Page 53 of 366

33. CompareText - Compare two strings for equality,
ignoring case
33.1. Unit
SysUtils
33.2. Type
Function
33.3. Description
The CompareText function compares String1 and String2 for equality, ignoring case. It
returns these values : String1 < String2 : -ve numberString1 = String2 : 0String1 > String2 :
+ve number The comparison is not affected by length - it is carried out on a letter by letter
basis. But a longer string is greater than a shorter, otherwise matching string.
33.4. Syntax
function CompareText(const String1, String2 : string) : Integer;


Page 54 of 366

33.5. Example
33.5.1. Name
33.5.2. Code

begin


// ansicomparetext treats upper and lower case identically
CompareStrings('ABCdef', 'abcDEF');

end;

var
result : Integer;
begin
result := CompareText(string1, string2);

end;
33.5.3. Result
HELLO < WORLD
Hi 2 you = Hi 2 you
ABCdef = abcDEF
abc > 123


Page 55 of 366

34. CompareValue - Compare numeric values with a
tolerance
34.1. Unit
Math
34.2. Type
Function
34.3. Description
CompareValue allows floating point numbers to be compared in a tolerant way. if the two
numbers are close enough together, they are deemed to be equal. The delta value is the
permitted tolerance. There seems no point to the author in providing the Integer version of
this function with no delta. TValueRelationship supports the following values: LessThanValue
-1EqualsValue 0GreaterThanValue 1
34.4. Syntax
function CompareValue (const A, B : Single|Double|Extended; delta :
Single|Double|Extended) : TValueRelationship;


Page 56 of 366

34.5. Example
34.5.1. Name
Comparing floating point numbers
34.5.2. Code
var
A : Single;
B : Single;
C : Single;

begin
A := 23.0;
B := 23.0;
C := 23.1;

// compare 2 equal floats
case CompareValue(A, B, 0) of
LessThanValue : ShowMessage('A < B');
EqualsValue : ShowMessage('A = B');
GreaterThanValue : ShowMessage('A > B');
end;

// compare 2 unequal floats
case CompareValue(A, C, 0) of
LessThanValue : ShowMessage('A < C');
EqualsValue : ShowMessage('A = C');
GreaterThanValue : ShowMessage('A > C');
end;

// compare 2 unequal floats - but allow for a difference of up to +/- 0.2
case CompareValue(A, C, 0.2) of
LessThanValue : ShowMessage('A < C');
EqualsValue : ShowMessage('A = C');
GreaterThanValue : ShowMessage('A > C');
end;
end;
34.5.3. Result
A = B
A < C
A = C


Page 57 of 366

35. Const - Starts the definition of fixed data values
35.1. Unit
Iris Standard
35.2. Type
Keyword
35.3. Description
The const keyword is used to start a section of constant definitions. The section is terminated
by the next keyword in a program. Within the section, one or more constants may be
defined.
35.4. Syntax
const Name1 = Expression1;
35.5. Example
35.5.1. Name
Illustrating the different constant types
35.5.2. Code
const
MAX_LINES = 3;
CRUDE_PI = 22/7;
HELLO = 'Hello World';

var
i : Integer;

begin
// display our crude value of pi
ShowMessage('Crude Pi = '+FloatToStr(CRUDE_PI));

// say hello to the world
ShowMessage(HELLO);

// display max_lines of data
for i := 1 to MAX_LINES do
ShowMessage(Chr(i+64));

end;
35.5.3. Result
Crude Pi = 3.14285714285714
Hello World
A
B
C


Page 58 of 366

36. Continue - Forces a jump to the next iteration of a loop
36.1. Unit
System
36.2. Type
Procedure
36.3. Description
The Continue procedure forces a jump past the remaining statements within a loop, back to
the next loop iteration. Like the goto statement, it should be used with caution. It is
important to note that the Continue statement only jumps to the start of the current loop -
not out of any nested loops above it. The goto statement can.
36.4. Syntax
procedure Continue;
36.5. Example
36.5.1. Name
Skipping loop processing for certain loop values
36.5.2. Code
var
i : Integer;
s : string;

begin
s := '';

// a big loop
for i := 1 to 9 do
begin
// skip loop processing for certain values of i
if (i = 3) or (i = 7) then Continue;
s := s + IntToStr(i);
s := s + ' ';
end;

// show the string created by the above loop
ShowMessage('s = '+s);
end;
36.5.3. Result
s = 1 2 4 5 6 8 9


Page 59 of 366

37. Copy - Create a copy of part of a string or an array
37.1. Unit
System
37.2. Type
Function
37.3. Description
The Copy function has 2 forms. in the first, it creates a new string from part of an existing
string. in the second, it creates a new array from part of an existing array. string copy The
first character of a string has index = 1. Up to Count characters are copied from the
StartChar of the Source string to the returned string. Less than Count characters if the end of
the Source string is encountered before Count characters have been copied.
37.4. Syntax
function Copy(Source : string; StartChar, Count : Integer) : string;
37.5. Example
37.5.1. Name
string copy
37.5.2. Code
var
Source, Target : string;

begin
Source := '12345678';
Target := Copy(Source, 3, 4);
ShowMessage('Target : '+Target);
end;
37.5.3. Result
Target : 3456


Page 60 of 366

38. Cos - The Cosine of a number
38.1. Unit
System
38.2. Type
Function
38.3. Description
The Cos function is a mathematical function giving the Cosine value of a Number value given
radians. PI radians = 180 degrees
38.4. Syntax
function Cos(const Number : Extended) : Extended;
38.5. Example
38.5.1. Name
Get the Cosine of 60 degrees
38.5.2. Code
var
float : single;
begin
// the sine of 60 degrees = 0.5
float := Cos(PI/3); // = 180/3 = 60 degrees
ShowMessage('Cos(PI/3) = '+FloatToStr(float));
end;
38.5.3. Result
Cos(PI/3) = 0.5


Page 61 of 366

39. CreateDir - Create a directory
39.1. Unit
SysUtils
39.2. Type
Function
39.3. Description
The CreateDir function creates a new directory Dir in the current directory. if the create
succeeded, the True is returned, otherwise the error can be obtained using GetLastError.
39.4. Syntax
function CreateDir(const Dir : string) : Boolean;
39.5. Example
39.5.1. Name
Create a new directory
39.5.2. Code
begin
// create a new directory in the current directory
if CreateDir('TestDir')
then ShowMessage('New directory added OK')
else ShowMessage('New directory add failed with error : '+
IntToStr(GetLastError));
end;
39.5.3. Result
New directory added OK


Page 62 of 366

40. Currency - A floating point type with 4 decimals used
for financial values
40.1. Unit
System
40.2. Type
Type
40.3. Description
The Currency type is designed for use in financial applications. It supports 4 decimal places
with at least 53 bits precision*. Decimal places beyond the supported 4 are rounded up or
down, as appropriate. See the sample code for an example.
40.4. Syntax
type Currency;
40.5. Example
40.5.1. Name
Rounding up and down currency amounts
40.5.2. Code
var
account1, account2, account3 : Currency;
begin
account1 := 123.456789;
account2 := 987.654321;
account3 := account1 + account2;

ShowMessage('Account1 = '+CurrToStr(account1));
end;
40.5.3. Result
Account1 = 123.4568
Account2 = 987.6543
Account3 = 1111.1111


Page 63 of 366

41. CurrencyDecimals - Defines decimal digit count in the
Format function
41.1. Unit
SysUtils
41.2. Type
Variable
41.3. Description
The CurrencyDecimals variable provides a default number of decimal digits for the Format
and related functions.
41.4. Syntax
var CurrencyDecimals : Byte;
41.5. Example
41.5.1. Name
Change the default decimal digits from 2 to 4
41.5.2. Code
var
amount : Double;

begin
amount := 1234.567;

// display the amount using the default decimal digits (2)
ShowMessage('Amount = '+Format('%m', [amount]));

// redisplay the amount with 4 decimal digits
CurrencyDecimals := 4;
ShowMessage('Amount = '+Format('%m', [amount]));
end;
41.5.3. Result
Amount = ?1,234.57
Amount = ?1,234.5670


Page 64 of 366

42. CurrencyFormat - Defines currency string placement in
curr display functions
42.1. Unit
SysUtils
42.2. Type
Variable
42.3. Description
The CurrencyFormat variable is in effect an enumerated type. The values it can hold
determine placement of the currency string in the currency display functions, such as
CurrToStr. The allowed values are: 0 = Before amount1 = After amount2 = Before amount
with space3 = After amount with space
42.4. Syntax
var CurrencyFormat : Byte;
42.5. Example
42.5.1. Name
Illustrate the 4 currency formats
42.5.2. Code
var
amount : Currency;
i : Byte;

begin
amount := 12; // 12 pounds

// display the amount using all 4 currency formats
for i := 0 to 3 do
begin
CurrencyFormat := i;
ShowMessage('Format '+IntToStr(i)+' = '+CurrToStrF(amount, ffCurrency, 0));
end;
end;

42.5.3. Result
Format 0 = ?12
Format 1 = 12?
Format 2 = ? 12
Format 3 = 12 ?


Page 65 of 366

43. CurrencyString - The currency string used in currency
display functions
43.1. Unit
SysUtils
43.2. Type
Variable
43.3. Description
The CurrencyString variable is used in currency display functions. It is used to prefix or suffix
the currency amount. for example, the UK default is ?, so 1.23 is displayed as ?1.23 by
default.
43.4. Syntax
var CurrencyString : string;
43.5. Example
43.5.1. Name
Changing the currency character to a word
43.5.2. Code
var
amount : Currency;

begin
amount := 12; // 12 pounds

// display with the default currency string
ShowMessage('Amount = '+CurrToStrF(amount, ffCurrency, 0));

// display with the currency shown as a word after the amount
CurrencyString := 'Pounds';
CurrencyFormat := 4; // 4 means after with a space
ShowMessage('Amount = '+CurrToStrF(amount, ffCurrency, 0));
end;
43.5.3. Result
Amount = ?12
Amount = 12 Pounds


Page 66 of 366

44. CurrentPageName - Show the current page name
44.1. Unit
Iris Standard
44.2. Type
Frame Function
44.3. Description
Returns the name of the active screen
44.4. Syntax
property CurrentPageName
44.5. Example
44.5.1. Name
Show a message with the Screen Name of the frame 'FrameName'
44.5.2. Code
begin

ShowMessage(FrameName.CurrentPageName);
end;
44.5.3. Result
No result specified


Page 67 of 366

45. CurrToStr - Convert a currency value to a string
45.1. Unit
SysUtils
45.2. Type
Function
45.3. Description
The CurrToStr function converts a currency Value into a displayable string. The decimal point
and digits are only displayed if non-zero. The CurrencyDecimals does not affect this function.
Unexpectedly, there is no currency symbol or thousands separator character used in the
display.
45.4. Syntax
function CurrToStr(Value : Currency) : string;
45.5. Example
45.5.1. Name
Display currency values as strings
45.5.2. Code
var
amount1, amount2, amount3 : Currency;

begin
amount1 := 1.23;
amount2 := 123456789.1234;

ShowMessage('Amount1 = '+CurrToStr(amount1));
ShowMessage('Amount2 = '+CurrToStr(amount2));
end;
45.5.3. Result
Amount1 = 1.23
Amount2 = 123456789.1234


Page 68 of 366

46. CurrToStrF - Convert a currency value to a string with
formatting
46.1. Unit
SysUtils
46.2. Type
Function
46.3. Description
The CurrToStrF function converts a currency Value into a displayable string, with great control
over the formatting via the Format, and Digits values. The Digits value determines how many
decimal digits are displayed. The Format parameter is defined by the TFloatFormat (SysUtils)
type: ffCurrency eg : ?2,345.60ffExponent eg : 2.3456E+04ffFixed eg : 2345.60ffGeneral eg :
2345.6ffNumber eg : 2,345.6
46.4. Syntax
1 function CurrToStrF(Value : Currency; Format : TFloatFormat; Digits : Integer) :
string;
46.5. Example
46.5.1. Name
Display currency numbers as financial values
46.5.2. Code
var
amount1 : Currency;

begin
amount1 := 1234.567;

// display in a currency format
CurrencyString := '? ';
ShowMessage('Using 4 digits = '+CurrToStrF(amount1, ffCurrency, 4));
end;

46.5.3. Result
Using 4 digits = 1,234.5670 ?
Using 2 digits = 1,234.57 ?
Using 0 digits = 1,235 ?


Page 69 of 366

47. Date - Gives the current date
47.1. Unit
SysUtils
47.2. Type
Function
47.3. Description
The Date function returns the current date in the local time zone. Because the return value is
a TDateTime type, the time component is set to zero (start of day).
47.4. Syntax
function Date : TDateTime;
47.5. Example
47.5.1. Name
Show the current date
47.5.2. Code
begin
ShowMessage('Yesterday = '+DateToStr(Yesterday));
ShowMessage('Today = '+DateToStr(Date));
ShowMessage('Tomorrow = '+DateToStr(Tomorrow));

ShowMessage('Today''s time = '+TimeToStr(Date));
end;
47.5.3. Result
Yesterday = 28/10/2009
Today = 29/10/2009
Tomorrow = 30/10/2009
Today's time = 00:00:00


Page 70 of 366

48. DateSeparator - The character used to separate
display date fields
48.1. Unit
SysUtils
48.2. Type
Variable
48.3. Description
The DateSeparator variable is used in date and time display functions. DateSeparator value is
'/' by default, depending on the Windows locale.
48.4. Syntax
var DateSeparator : char;
48.5. Example
48.5.1. Name
Changing the date display separator character
48.5.2. Code
var
mydate : TDateTime;

begin
myDate := EndOfAMonth(2000, 2); // 29th feb 2000 at 23:59:59.999

ShowMessage('Date = '+DateTimeToStr(myDate));
DateSeparator := '_'; // override the / date separator
ShowMessage('Date now = '+DateTimeToStr(myDate));
end;
48.5.3. Result
Date = 29/02/2000 23:59:59
Date now = 29_02_2000 23:59:59


Page 71 of 366

49. DateTimeToFileDate - Convert a TDateTime value to a
file date/time format
49.1. Unit
SysUtils
49.2. Type
Function
49.3. Description
The DateTimeToFileDate function converts a TDateTime value DateTime to the format used
for file dates. The file date is more restricted in range than TDateTime:Year must be 1980 ..
2099Milli-seconds are rounded to 2 decimal places
49.4. Syntax
function DateTimeToFileDate(DateTime : TDateTime) : Integer;
49.5. Example
49.5.1. Name
Display, update, and redisplay the last modified date of a file
49.5.2. Code
var
fileName : string;
fileDate : Integer;
newDateTime : TDateTime;
begin
// try to open the test.dfm file for the current project
fileName := 'test.dfm';
fileDate := FileAge(fileName);

// did we get the file age ok?
if fileDate > -1 then
begin
ShowMessage(fileName+' last modified date = '+
DateTimeToStr(FileDateToDateTime(fileDate)));

// now change the last modified date
newDateTime := StrToDateTime('01/01/2009 12:34:56');
FileSetDate(fileName, DateTimeToFileDate(newDateTime));
end;

// did we update the file last modified date ok?
end;
49.5.3. Result
test.dfm last modified date = 30/10/2009 15:16:22


Page 72 of 366



Page 73 of 366

50. DateTimeToStr - Converts TDateTime date and time
values to a string
50.1. Unit
SysUtils
50.2. Type
Function
50.3. Description
The DateTimeToStr function converts a TDateTime value DateTime into a formatted date and
time string. The string comprises : Date in ShortDateFormat1 blank Time in LongTimeFormat
See these two formatting variables for more details. The date and time formats are also
affected by the DateSeparator and TimeSeparator values.
50.4. Syntax
function DateTimeToStr(DateTime : TDateTime) : string;
50.5. Example
50.5.1. Name
Converting two date/time values to strings
50.5.2. Code
var
myDate : TDateTime;

begin
myDate := StrToDateTime('09/02/2002 12:00');
ShowMessage('Middle of a day = '+DateTimeToStr(myDate));

ShowMessage('Start of a day = '+DateTimeToStr(myDate));
end;
50.5.3. Result
Middle of a day = 09/02/2002 12:00:00
Start of a day = 09/02/2002


Page 74 of 366

51. DateTimeToString - Rich formatting of a TDateTime
variable into a string
51.1. Unit
SysUtils
51.2. Type
Procedure
51.3. Description
The DateTimeToString procedure provides rich formatting of a TDateTime value DateTime
into a string Result. Formatting is defined by the Formatting string. The Formatting string can
comprise a mix of ordinary characters (that are passed unchanged to the result string), and
data formatting characters. This formatting is best explained by the example code. The
following (non-Asian) formatting character strings can be used in the Formatting string: y =
Year last 2 digitsyy = Year last 2 digitsyyyy = Year as 4 digitsm = Month number no-leading
0mm = Month number as 2 digitsmmm = Month using ShortDayNames (Jan)mmmm = Month
using LongDayNames (January)d = Day number no-leading 0dd = Day number as 2 digitsddd
= Day using ShortDayNames (Sun)dddd = Day using LongDayNames (Sunday)ddddd = Day
in ShortDateFormatdddddd = Day in LongDateFormat c = Use ShortDateFormat +
LongTimeFormath = Hour number no-leading 0hh = Hour number as 2 digitsn = Minute
number no-leading 0nn = Minute number as 2 digitss = Second number no-leading 0ss =
Second number as 2 digitsz = Milli-sec number no-leading 0szzz = Milli-sec number as 3
digitst = Use ShortTimeFormattt = Use LongTimeFormat am/pm = Use after h : gives 12
hours + am/pma/p = Use after h : gives 12 hours + a/pampm = As a/p but
TimeAMString,TimePMString/ = Substituted by DateSeparator value: = Substituted by
TimeSeparator value in addition to this formatting, various of the above options are affected
by the following variables, withe their default values : DateSeparator = /TimeSeparator =
:ShortDateFormat = dd/mm/yyyyLongDateFormat = dd mmm yyyyTimeAMString =
AMTimePMString = PMShortTimeFormat = hh:mmLongTimeFormat =
hh:mm:ssShortMonthNames = Jan Feb ...LongMonthNames = January, February
...ShortDayNames = Sun, Mon ...LongDayNames = Sunday, Monday
...TwoDigitCenturyWindow = 50
51.4. Syntax
1 procedure DateTimeToString(var Result : string; const Formatting : string;
DateTime : TDateTime);


Page 75 of 366

51.5. Example 1
51.5.1. Name
Showing all of the date
51.5.2. Code
var
myDate : TDateTime;
formattedDateTime : string;

begin
// set up our tdatetime variable with a full date and time :
// 5th of june 2000 at 01:02:03.004 (.004 milli-seconds)
myDate := EncodeDateTime(2000, 6, 5, 1, 2, 3, 4);

// date only - numeric values with no leading zeroes (except year)
DateTimeToString(formattedDateTime, 'd/m/y', myDate);
ShowMessage('d/m/y = '+formattedDateTime);

// date only - numeric values with leading zeroes
DateTimeToString(formattedDateTime, 'dd/mm/yy', myDate);
ShowMessage('dd/mm/yy = '+formattedDateTime);

// use short names for the day, month, and add freeform text ('of')
DateTimeToString(formattedDateTime, 'ddd d of mmm yyyy', myDate);
ShowMessage('ddd d of mmm yyyy = '+formattedDateTime);

// use long names for the day and month
DateTimeToString(formattedDateTime, 'dddd d of mmmm yyyy', myDate);
ShowMessage('dddd d of mmmm yyyy = '+formattedDateTime);

// use the shortdateformat settings only
DateTimeToString(formattedDateTime, 'ddddd', myDate);
ShowMessage('ddddd = '+formattedDateTime);

// use the longdateformat settings only
DateTimeToString(formattedDateTime, 'dddddd', myDate);
ShowMessage('dddddd = '+formattedDateTime);

// use the shortdateformat + longtimeformat settings
DateTimeToString(formattedDateTime, 'c', myDate);
ShowMessage('c = '+formattedDateTime);
end;
51.5.3. Result
d/m/y = 5/6/00
dd/mm/yy = 05/06/00
ddd d of mmm yyyy = Mon 5 of Jun 2000
dddd d of mmmm yyyy = Monday 5 of June 2000
ddddd = 05/06/2000
dddddd = 05 June 2000
c = 05/06/2000 01:02:03


Page 76 of 366

51.6. Example 2
51.6.1. Name
Showing all of the time
51.6.2. Code
var
myDate : TDateTime;
formattedDateTime : string;

begin

// time only - numeric values with no leading zeroes
DateTimeToString(formattedDateTime, 'h:n:s.z', myDate);
ShowMessage('h:n:s.z = '+formattedDateTime);

// time only - numeric values with leading zeroes
DateTimeToString(formattedDateTime, 'hh:nn:ss.zzz', myDate);
ShowMessage('hh:nn:ss.zzz = '+formattedDateTime);

// use the shorttimeformat settings only
DateTimeToString(formattedDateTime, 't', myDate);
ShowMessage('t = '+formattedDateTime);

// use the longtimeformat settings only
DateTimeToString(formattedDateTime, 'tt', myDate);
ShowMessage('tt = '+formattedDateTime);

DateTimeToString(formattedDateTime, 'c', myDate);
ShowMessage('c = '+formattedDateTime);
end;
51.6.3. Result
h:m:s.z = 1:2:3.4
hh:mm:ss.zzz = 01:02:03.004
t = 01:02
tt = 01:02:03
c = 05/06/2000 01:02:03


Page 77 of 366

52. DateToStr - Converts a TDateTime date value to a
string
52.1. Unit
SysUtils
52.2. Type
Function
52.3. Description
The DateToStr function converts a TDateTime value Date into a formatted date string. The
date is formatted using the ShortDateFormat value, which in turn uses the DateSeparator
value.
52.4. Syntax
function DateToStr(Date : TDateTime) : string;
52.5. Example
52.5.1. Name
Converting a date value to a string
52.5.2. Code
var
myDate : TDateTime;

begin
myDate := StrToDate('13/02/2002');
ShowMessage('myDate = '+DateToStr(myDate));
end;
52.5.3. Result
myDate = 13/02/2002


Page 78 of 366

53. DayOfTheMonth - Gives day of month index for a
TDateTime value (ISO 8601)
53.1. Unit
DateUtils
53.2. Type
Function
53.3. Description
The DayOfTheMonth function returns an index number for the day of the month. Depending
on the year and month, the value is in the range 1..31
53.4. Syntax
function DayOfTheMonth(const Date : TDateTime) : Word;
53.5. Example
53.5.1. Name
Show the day of the month for a TDateTime variable
53.5.2. Code
var
myDate : TDateTime;

begin
myDate := EncodeDate(2002, 12, 31);
ShowMessage('The day of the month = '+IntToStr(DayOfTheMonth(myDate)));
end;
53.5.3. Result
The day of the month = 31


Page 79 of 366

54. DayOfTheWeek - Gives day of week index for a
54.1. Unit
DateUtils
54.2. Type
Function
54.3. Description
The DayOfTheWeek function returns an index number for the day of the week :1 = Monday2
= Tuesday3 = Wednesday4 = Thursday5 = Friday6 = Saturday7 = Sunday
54.4. Syntax
function DayOfTheWeek(const Date : TDateTime) : Integer;
54.5. Example
54.5.1. Name
Show the day of the week for Christmas 2002
54.5.2. Code
var
myDate : TDateTime;
day : array[1..7] of string;

begin
// we cannot use longdaynames - they start on sunday
day[1] := 'Monday';
day[2] := 'Tuesday';
day[3] := 'Wednesday';
day[4] := 'Thursday';
day[5] := 'Friday';
day[6] := 'Saturday';
day[7] := 'Sunday';


ShowMessage('Christmas day 2002 is on a '+day[DayOfTheWeek(myDate)]);
end;
54.5.3. Result
Christmas day 2002 is on a Wednesday


Page 80 of 366

55. DayOfTheYear - Gives the day of the year for a
55.1. Unit
DateUtils
55.2. Type
Function
55.3. Description
The DayOfTheYear function returns an index number for the day of the year. Depending on
the year, the value is in the range 1..366
55.4. Syntax
function DayOfTheYear(const Date : TDateTime) : Word;
55.5. Example
55.5.1. Name
Show the day of the year for a TDateTime variable
55.5.2. Code
var
myDate : TDateTime;

begin
ShowMessage('20/10/2002 day of year = '+
IntToStr(DayOfTheYear(myDate)));
end;
55.5.3. Result
20/10/2002 day of the year = 302


Page 81 of 366

56. DayOfWeek - Gives day of week index for a TDateTime
value
56.1. Unit
SysUtils
56.2. Type
Function
56.3. Description
The DayOfWeek function returns an index number for the day of the week :1 = Sunday2 =
Monday3 = Tuesday4 = Wednesday5 = Thursday6 = Friday7 = Saturday
56.4. Syntax
function DayOfWeek(Date : TDateTime) : Integer;
56.5. Example
56.5.1. Name
Show the day of the week for Christmas 2002
56.5.2. Code
var
myDate : TDateTime;
day : string;

begin

day := IntToStr(DayOfWeek(myDate));

ShowMessage('Christmas day 2002 is on ' + day + ' of the week');
end;
56.5.3. Result
Christmas day 2002 is on a Tuesday


Page 82 of 366

57. DaysBetween - Gives the whole number of days
between 2 dates
57.1. Unit
DateUtils
57.2. Type
Function
57.3. Description
The DaysBetween function subtracts the FromDate from the ToDate, returning the number
whole days difference. The time value of each date is taken account of - only whole 24 hour
chunks are counted as whole days.
57.4. Syntax
function DaysBetween(const ToDate, FromDate : TDateTime) : Integer;
57.5. Example
57.5.1. Name
Find the days difference between two date+time values.
57.5.2. Code
var
fromdate, toDate : TDateTime;

begin
// set up our date variables
fromDate := EncodeDateTime(2000, 02, 26, 10, 0, 0, 0);
toDate := EncodeDateTime(2000, 02, 29, 9, 0, 0, 0);

// display these dates and the days between them
ShowMessage('From date = '+DateTimeToStr(fromDate));
ShowMessage('to date = '+DateTimeToStr(toDate));
ShowMessage('Whole days difference = '+
IntToStr(DaysBetween(toDate, fromDate))+' days');
end;
57.5.3. Result
From date = 26/02/2000 10:00:00
to date = 29/02/2000 09:00:00
Whole days difference = 2 days


Page 83 of 366

58. DaysInAMonth - Gives the number of days in a month
58.1. Unit
DateUtils
58.2. Type
Function
58.3. Description
The DaysInAMonth function gives the number of days in a given Year and Month.
58.4. Syntax
function DaysInAMonth(const Year, Month : Word) : Word;
58.5. Example
58.5.1. Name
How many days in February 2000 ?
58.5.2. Code
begin
// how many days in february 2000 ?
ShowMessage('Days in February 2000 = '+
IntToStr(DaysInAMonth(2000, 2)));
end;
58.5.3. Result
Days in February 2000 = 29


Page 84 of 366

59. DaysInAYear - Gives the number of days in a year
59.1. Unit
DateUtils
59.2. Type
Function
59.3. Description
The DaysInAYear function gives the number of days in a given Year. The Year can be in the
range 0..9999
59.4. Syntax
function DaysInAYear(const Year : Word) : Word;
59.5. Example
59.5.1. Name
How many days in the leap year 2000 ?
59.5.2. Code
begin
// how many days in the leap year 2000?
ShowMessage('Days in 2000 = '+
IntToStr(DaysInAYear(2000)));
end;
59.5.3. Result
Days in 2000 = 366


Page 85 of 366

60. DaySpan - Gives the fractional number of days
between 2 dates
60.1. Unit
DateUtils
60.2. Type
Function
60.3. Description
The DaySpan function subtracts the FromDate from the ToDate, returning the fractional days
difference. The Double return value contains the number of days as the integral part, and the
part-day remainder as the fractional part. for example, a difference of 2 days and 6 hours
would give a value of 2.25
60.4. Syntax
function DaySpan(const ToDate, FromDate : TDateTime) : Double;
60.5. Example
60.5.1. Name
Find the days difference between two date+time values.
60.5.2. Code
var
fromdate, toDate : TDateTime;

begin
// set up our date variables
fromDate := EncodeDateTime(2000, 01, 01, 0, 0, 0, 0);
toDate := EncodeDateTime(2000, 01, 02, 12, 0, 0, 0);

// display these dates and the days between them
ShowMessage('From date = '+DateTimeToStr(fromDate));
ShowMessage('to date = '+DateTimeToStr(toDate));
ShowMessage('Fractional days difference = '+
FloatToStr(DaySpan(toDate, fromDate))+' days');
end;
60.5.3. Result
From date = 01/01/2000
to date = 02/01/2000 12:00:00
Fractional days difference = 1.5 days


Page 86 of 366

61. Dec - Decrement an ordinal variable
61.1. Unit
System
61.2. Type
Procedure
61.3. Description
The Dec procedure decrements the ordinal Variable parameter passed to it. You can
decrement: Characters Non-floating number types Enumeration types Pointers The
decrement is by the base size of the unit. for example, decrementing a Pointer will be by 4
bytes if the pointer points to Words. Version 1 of Inc decrements by 1 unit. Version 2 of Inc
decrements by Count units.
61.4. Syntax
1 procedure Dec(var Variable : Ordinal variable);2 procedure Dec (var Variable :
Ordinal variable; Count : Integer) ;
61.5. Example
61.5.1. Name
Decrementing characters, numbers and enumerations
61.5.2. Code
var
Number : Integer;

begin
Number := 23;

ShowMessage('Number : '+IntToStr(Number));
Dec(Number);
ShowMessage('Number-1 : '+IntToStr(Number));
Dec(Number, 5);
end;
61.5.3. Result
Number : 24
Number-1 : 23
Number-5 : 18


Page 87 of 366

62. DecimalSeparator - The character used to display the
decimal point
62.1. Unit
SysUtils
62.2. Type
Variable
62.3. Description
The DecimalSeparator variable is used in currency and floating point display functions.
DecimalSeparator value is '.' by default, depending on the Windows locale.
62.4. Syntax
var DecimalSeparator : char;
62.5. Example
62.5.1. Name
Changing the decimal point character
62.5.2. Code
var
amount : Currency;
begin
amount := 12.34; // 12 pounds 34 pence

// display with the default decimal point character
ShowMessage('Amount = '+FloatToStrF(amount, ffCurrency, 10, 2));

// display with a new decimal point character
DecimalSeparator := '|';
end;
62.5.3. Result
Amount = ?12.34
Amount = ?12|34


Page 88 of 366

63. DecodeDate - Extracts the year, month, day values
from a TDateTime var.
63.1. Unit
SysUtils
63.2. Type
Procedure
63.3. Description
The DecodeDate procedure extracts year, month and day values from a given SourceDate
TDateTime type value. It stores the values in the output variables: Year, Month and Day.
63.4. Syntax
procedure DecodeDate(const SourceDate : TDateTime; out Year, Month, Day : Word);
63.5. Example
63.5.1. Name
Add a month to a date and then extract the year, month and day values
63.5.2. Code
var
myDate : TDateTime;
myYear, myMonth, myDay : Word;
begin
// set up the mydate variable to have a december 2000 value

// now add a month to this value
myDate := IncMonth(myDate);

// and let us see what we get
DecodeDate(myDate, myYear, myMonth, myDay);
ShowMessage('myDate now = '+DateToStr(myDate));
ShowMessage('myDay = '+IntToStr(myDay));
ShowMessage('myMonth = '+IntToStr(myMonth));
ShowMessage('myYear = '+IntToStr(myYear));
end;
63.5.3. Result
myDate now = 01/29/2001
myDay = 29
myMonth = 1
myYear = 2001


Page 89 of 366

64. DecodeTime - Break a TDateTime value into individual
time values
64.1. Unit
SysUtils
64.2. Type
Procedure
64.3. Description
The DecodeTime procedure extracts hour, minute, second and milli-second values from a
given SourceDateTime TDateTime type value. It stores the values in the output variables:
Hour, Min, Sec and MSec.
64.4. Syntax
procedure DecodeTime(const SourceDateTime : TDateTime; out Hour, Min, Sec, MSec :
Word);
64.5. Example
64.5.1. Name
Add 5 minutes to a time and then extract the new time values
64.5.2. Code
var
myDate : TDateTime;
myHour, myMin, mySec, myMilli : Word;

begin
// set up the mydate variable to have a december 2000 value
myDate := StrToDateTime('12/29/2000 12:45:12.34');

// now add 5 minutes to this value
myDate := IncMinute(myDate, 5);

// and let us see what we get
DecodeTime(myDate, myHour, myMin, mySec, myMilli);
ShowMessage('Time now = '+TimeToStr(myDate));
ShowMessage('Hour = '+IntToStr(myHour));
ShowMessage('Minute = '+IntToStr(myMin));
ShowMessage('Second = '+IntToStr(mySec));
ShowMessage('MilliSec = '+IntToStr(myMilli));
end;
64.5.3. Result
Time now = 12:50:12
Hour = 12
Minute = 50
Second = 12
MilliSec = 34


Page 90 of 366

65. DegToRad - Convert a degrees value to radians
65.1. Unit
Math
65.2. Type
Function
65.3. Description
The DegToRad function is a mathematical function converting a Degrees value to Radians PI
radians = 180 degrees
65.4. Syntax
function DegToRad(const Degrees : Extended) : Extended;
65.5. Example
65.5.1. Name
Get the Sine of 30 degrees
65.5.2. Code
var
float : single;
begin
float := Sin(DegToRad(30));
ShowMessage('Sine of 30 degrees = '+FloatToStr(float));
end;
65.5.3. Result
Sine of 30 degrees = 0.5


Page 91 of 366

66. Delete - Delete a section of characters from a string
66.1. Unit
System
66.2. Type
Procedure
66.3. Description
The Delete procedure deletes up to Count characters from the passed parameter Source
string starting from position StartChar. No error is produced if Count exceeds the remaining
character count of Source. The first character of a string is at position 1.
66.4. Syntax
procedure Delete(var Source : string; StartChar : Integer; Count : Integer);
66.5. Example
66.5.1. Name
Deleting characters from the middle of a string
66.5.2. Code
var
Source : string;

begin
Source := '12345678';
Delete(Source, 3, 4); // delete the 3rd, 4th, 5th and 6th characters
ShowMessage('Source now : '+Source);
end;
66.5.3. Result
Source now : 1278


Page 92 of 366

67. DeleteFile - Delete a file specified by its file name
67.1. Unit
SysUtils
67.2. Type
Function
67.3. Description
The DeleteFile function deletes a file given by its file name FileName. The file is looked for in
the current directory. if the file was deleted OK, then True is returned, otherwise False is
returned. This function is easier to use than the equivalent System unit Erase routine.
67.4. Syntax
function DeleteFile(const FileName : string) : Boolean;


Page 93 of 366

67.5. Example
67.5.1. Name
try to delete a file twice
67.5.2. Code
var
fileName : string;
myFile : TextFile;
data : string;

begin
// try to open a text file for writing to
fileName := 'Test.txt';
AssignFile(myFile, fileName);
ReWrite(myFile);

// write to the file
write(myFile, 'Hello World');

// close the file
CloseFile(myFile);

// reopen the file in read mode
Reset(myFile);

begin
ReadLn(myFile, data);
ShowMessage(data);
end;

CloseFile(myFile);

// now delete the file
if DeleteFile(fileName)
then ShowMessage(fileName+' deleted OK')
else ShowMessage(fileName+' not deleted');

// try to delete the file again
if DeleteFile(fileName)
then ShowMessage(fileName+' deleted OK again!')
else ShowMessage(fileName+' not deleted, error = '+
end;
67.5.3. Result
Hello World
Test.txt deleted OK
Test.txt not deleted, error = ?


Page 94 of 366

68. DirectoryExists - Returns true if the given directory
exists
68.1. Unit
SysUtils
68.2. Type
Function
68.3. Description
The DirectoryExists function returns True if the given DirectoryName file exists. The directory
is searched for in the current directory. False may be returned if the user is not authorised to
see the file.
68.4. Syntax
function DirectoryExists(const DirectoryName : string) : Boolean;
68.5. Example
68.5.1. Name
Check for a directory before and after deleting it
68.5.2. Code
var
dirName : string;

begin
// create a new directory
dirName := 'Test Folder';
CreateDir(dirName);

// now see if the directory exists
if DirectoryExists(dirName)
then ShowMessage(dirName+' exists OK')
else ShowMessage(dirName+' does not exist');

// delete the directory and look again
RemoveDir(dirName);
if DirectoryExists(dirName)
then ShowMessage(dirName+' still exists!')
else ShowMessage(dirName+' no longer exists');
end;
68.5.3. Result
Test Folder exists OK
Test Folder no longer exists


Page 95 of 366

69. Div - Performs integer division, discarding the
remainder
69.1. Unit
Iris Standard
69.2. Type
Keyword
69.3. Description
The div keyword gives the whole number result of dividing the Dividend by the Divisor. Any
remainder is discarded.
69.4. Syntax
Dividend div Divisor
69.5. Example
69.5.1. Name
A simple example
69.5.2. Code
var
int : Integer;

begin
// divide a primary integer by 2 - it discards the remainder
int := 17 div 2;

ShowMessage('17 div 2 = '+IntToStr(int));
end;
69.5.3. Result
17 div 2 = 8


Page 96 of 366

70. Do - Defines the start of some controlled action
70.1. Unit
Iris Standard
70.2. Type
Keyword
70.3. Description
The do keyword is always a part of one of the shown 4 control types. It precedes the
Statements section of the control action.
70.4. Syntax
1. for Variable := Expression to Expression do Statement;
2. while Expression do Statement
3. try Statements except on ExceptionClass do Statement; end;
4. with Expression do Statement
70.5. Example
70.5.1. Name
Show singles and block do statement blocks
70.5.2. Code
var
i : Integer;

begin
// a for statement - the do keyword precedes a single statement
for i := 1 to 3 do
ShowMessage('for loop, i = '+IntToStr(i));

// a while statement - the do precedes a statement block
while i < 6 do
begin
ShowMessage('while loop, i = '+IntToStr(i));
Inc(i);
end;
end;
70.5.3. Result
for loop, i = 1
for loop, i = 2
for loop, i = 3
while loop, i = 4
while loop, i = 5


Page 97 of 366

71. Double - A floating point type supporting about 15
digits of precision
71.1. Unit
System
71.2. Type
Type
71.3. Description
The Double type is the general purpose floating point type. It strikes the balance between
capacity/precision versus storage/performance. It supports approximately 15 digits of
precision in a range from 2.23 x 10-307 to 1.79 x 10307.
71.4. Syntax
type Double;
71.5. Example
71.5.1. Name
Showing the precision and capacity of Double values
71.5.2. Code
var
account1, account2, account3 : Double;
begin
account1 := 0.1234567890123456789; // 20 decimal places
account2 := 1.234567890123456789E307; // highest exponent value
account3 := account1 + account2;

ShowMessage('Account1 = '+FloatToStr(account1));
end;

71.5.3. Result
Account1 = 0.123456789012346
Account2 = 1.23456789012346E307
Account3 = 1.23456789012346E307


Page 98 of 366

72. Downto - Prefixes an decremental for loop target
value
72.1. Unit
Iris Standard
72.2. Type
Keyword
72.3. Description
The downto keyword prefixes the target value Expression in a for loop. See the for keyword
for full details.
72.4. Syntax
1 for Variable := Integer Expression downto Integer Expression do Statement;
72.5. Example
72.5.1. Name
Integer for loop
72.5.2. Code
var
i : Integer;

begin
// loop 5 times
for i := (10 div 2) downto 1 do
end;
72.5.3. Result
i = 5
i = 4
i = 3
i = 2
i = 1


Page 99 of 366

73. Else - Starts false section of if, case and try statements
73.1. Unit
Iris Standard
73.2. Type
Keyword
73.3. Description
The else keyword is part of the if, case and try statements. It is used to start the section of
code executed when earlier conditions are not satisfied. See details of each of these
statements for further details.
73.4. Syntax
1 if Condition then Statement else Statement;
2 case Expression of
case clauses
...
else
Statements
end;
3 try
Statements
...
except
Exception statements
...
else
Statements
end


Page 100 of 366

73.5. Example
73.5.1. Name
Illustrate various uses of the else clause
73.5.2. Code
begin
// note the lack of a ';' after the 'then' clause
if False
then ShowMessage('True')
else ShowMessage('False');

// nested if statements - iris sensibly manages associations
if true then
if false then
ShowMessage('Inner then satisfied')
else
ShowMessage('Inner else satisfied')
else
ShowMessage('Outer else satisfied')
end;
73.5.3. Result
False
Inner else satisfied


Page 101 of 366

74. EncodeDate - Build a TDateTime value from year,
month and day values
74.1. Unit
SysUtils
74.2. Type
Function
74.3. Description
The EncodeDate function generates a TDateTime return value from the passed Year, Month
and Day values. The permitted parameter values are: Year = 0..9999Month = 1..12Day =
1..31 (depending on month/year) if you exceed these values, an EConvertError is raised.
74.4. Syntax
function EncodeDate(const Year, Month, Day : Word) : TDateTime;
74.5. Example
74.5.1. Name
Assign a date to a TDateTime variable
74.5.2. Code
var
myDate : TDateTime;

begin
// set my date variable using the encodedate function

LongTimeFormat := 'hh:mm:ss.zzz'; // ensure that msecs are shown

ShowMessage('Date set to '+DateToStr(myDate));
ShowMessage('Time set to '+TimeToStr(myDate));
end;
74.5.3. Result
Date set to 29/02/2000
Time set to 00:00:00.000


Page 102 of 366

75. EncodeDateTime - Build a TDateTime value from day
and time values
75.1. Unit
DateUtils
75.2. Type
Function
75.3. Description
The EncodeDateTime function generates a TDateTime return value from the passed Year,
Month, Day, Hour, Min, Sec and MSec (millisecond) values. The permitted parameter values
are : Year = 0..9999Month = 1..12Day = 1..31 (depending on month/year) Hour = 0..23Min
= 0..59Sec = 0..59MSec = 0..999 if you exceed these values, an EConvertError is raised.
75.4. Syntax
function EncodeDateTime(const Year, Month, Day, Hour, Min, Sec, MSec : Word) :
TDateTime;
75.5. Example
75.5.1. Name
Assign a full day and time value to a TDateTime variable
75.5.2. Code
var
myDate : TDateTime;

begin
// set my date variable using the encodedatetime function

LongTimeFormat := 'hh:mm:ss.z'; // ensure that msecs are shown

end;
75.5.3. Result
Time set to 12:34:56.789


Page 103 of 366

76. EncodeTime - Build a TDateTime value from hour, min,
sec and msec values
76.1. Unit
SysUtils
76.2. Type
Function
76.3. Description
The EncodeTime function generates a TDateTime return value from the passed Hour, Min,
Sec and MSec (millisecond) values. The permitted parameter values are : Hour = 0..23Min =
0..59Sec = 0..59MSec = 0..999 if you exceed these values, an EConvertError is raised.
76.4. Syntax
function EncodeTime(const Hour, Min, Sec, MSec : Word) : TDateTime;
76.5. Example
76.5.1. Name
Assign a time to a TDateTime variable
76.5.2. Code
var
myDate : TDateTime;

begin
// set my date variable using the encodetime function
myDate := EncodeTime(12, 34, 56, 789);

LongTimeFormat := 'hh:mm:ss.z'; // ensure that msecs are shown

end;
76.5.3. Result
Time set to 12:34:56.789


Page 104 of 366

77. End - Keyword that terminates statement blocks
77.1. Unit
Iris Standard
77.2. Type
Keyword
77.3. Description
The end keyword is fundamental to Iris - it terminates statement blocks. The most common
is: begin ... statements ... end;
77.4. Syntax
asm ... end;
begin ... end;
case ... end;
library ... end;
package ... end;
program ... end;
try ... end;
type ... end;
unit ... end. // note terminating dot
77.5. Example
77.5.1. Name
Some examples of the end clause
77.5.2. Code
var
i : Integer;

begin
i := 2;

case i of
0 : Showmessage('i = 0');
end;
end;
77.5.3. Result
i = 2


Page 105 of 366

78. EndOfADay - Generate a TDateTime value set to the
very end of a day
78.1. Unit
DateUtils
78.2. Type
Function
78.3. Description
The EndOfADay function generates a TDateTime value set to the given year, month and day
with a time set to 1 millisecond before midnight. Allows the Month and Day to be specified
separately. The month must be between 1 (January) and 12 (December). The day must be
between 1 and 31, depending on the year and month.
78.4. Syntax
function EndOfADay(const Year, Month, Day : Word) : TDateTime;
78.5. Example
78.5.1. Name
set the date to last msec of the 20th century - illustrates Iris bug
78.5.2. Code
var
mydate : TDateTime;

begin
myDate := EndOfADay(1999, 12, 31);

// ensure that milli-seconds are shown
LongTimeFormat := 'hh:mm:ss.zzz';
ShowMessage('end of 1999 = '+DateTimeToStr(myDate));
end;
78.5.3. Result
end of 1999 = 30/01/2000 23:59:59.999


Page 106 of 366

79. EndOfAMonth - Generate a TDateTime value set to the
very end of a month
79.1. Unit
DateUtils
79.2. Type
Function
79.3. Description
The EndOfAMonth function generates a TDateTime value set to the given Year and Month
with the day set to the last of the month, and the time set to 1 millisecond before midnight.
The Year value must be between 0 and 9999. The Month value must be between 1 (January)
and 12 (December).
79.4. Syntax
function EndOfAMonth(const Year, Month : Word) : TDateTime;
79.5. Example
79.5.1. Name
set the date to the last millisecond of February 2000, a leap month
79.5.2. Code
var
mydate : TDateTime;

begin
myDate := EndOfAMonth(2000, 2);

// ensure that milli-seconds are shown
LongTimeFormat := 'hh:mm:ss.zzz';
ShowMessage('end of February 2000 = '+DateTimeToStr(myDate));
end;
79.5.3. Result
end of February 2000 = 29/02/2000 23:59:59.999


Page 107 of 366

80. Eof - Returns true if a file opened with Reset is at the
end
80.1. Unit
System
80.2. Type
Function
80.3. Description
The Eof function returns true if the file given by FileHandle is at the end. The file must have
been assigned, and opened with Reset.
80.4. Syntax
function Eof(var FileHandle : TextFile);


Page 108 of 366

80.5. Example
80.5.1. Name
Reading to the end of a text file
80.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
80.5.3. Result
Hello
World


Page 109 of 366

81. Erase - Erase a file
81.1. Unit
System
81.2. Type
Procedure
81.3. Description
The Erase procedure attempts to erase a file given by the FileHandle. The file name must
have been assigned to the given FileHandle by the AssignFile routine. if the file does not
exist, then the EInOutError exception is raised.
81.4. Syntax
procedure Erase(var FileHandle : file);
81.5. Example
81.5.1. Name
Create a simple file, then try to delete it twice
81.5.2. Code
var
myFile : TextFile;

begin
// let us open a text file
ReWrite(myFile);

// and write a single line to it
WriteLn(myFile, 'Hello World');

// then close it
CloseFile(myFile);

// and finally erase it
Erase(myFile);

// if we try to raise it again, we'll raise an exception
try
Erase(myFile);
except
ShowMessage('Cannot erase!');
end;
end;
81.5.3. Result
Cannot erase!


Page 110 of 366

82. Except - Starts the error trapping clause of a try
statement
82.1. Unit
Iris Standard
82.2. Type
Keyword
82.3. Description
The except keyword is used to mark the start of a block of statements that handle an
exception in a try clause. if the except block can handle the exception, then the program is
not terminated. in this version, if the try clause generates an exception the except clause is
executed. This is used to take alternative action when something unexpected goes wrong.
The except clause cannot determine the error type however.
82.4. Syntax
try
Statement
{statement...}
except
Statement
{statement...}
end;
82.5. Example
82.5.1. Name
Zero divide with a plain except block
82.5.2. Code
var
number, zero : Integer;
begin
// try to divide an integer by zero - to raise an exception
try
zero := 0;
number := 1 div zero;
ShowMessage('number / zero = '+IntToStr(number));
except
ShowMessage('Unknown error encountered');
end;
end;
82.5.3. Result
Unknown error encountered


Page 111 of 366

83. Exit - exit abruptly from a function or procedure
83.1. Unit
System
83.2. Type
Procedure
83.3. Description
The exit procedure abruptly terminates the current function or procedure. if exiting a
function, then Result contains the last set value. Warning: use with caution - jumping is a
concept at odds with structured coding - it makes code maintenance difficult.
83.4. Syntax
procedure exit;
83.5. Example
83.5.1. Name
exit a proc when a user cancels data entry
83.5.2. Code
// remember to declare the function at type using the following line
// function askforname: string;

begin
// ask the user for their name
ShowMessage('Name = '+AskForName);
end;

// ask the user for first and second names
function TUntitled.AskForName: string;
var
firstName, secondName : string;
begin
Result := 'Lazy person';
repeat
if not InputQuery('Test program', 'First name :', firstName)
then exit;
if not InputQuery('Test program', 'Second name :', secondName)
then exit;
until (firstName <> '') or (secondName <> '');

Result := firstName + ' ' + secondName;
end;
83.5.3. Result
if the user cancels from the first or second name dialogs, the ShowMessage dialog
gives:

Name = Lazy person


Page 112 of 366

84. Exp - Gives the exponent of a number
84.1. Unit
System
84.2. Type
Function
84.3. Description
The Exp function takes an integer or floating point Number and raises e (2.72) to that power.
This is only used for mathematical processing. Exp has the opposite effect to Ln - the natural
logarithm.
84.4. Syntax
function Exp(Number : Extended) : Extended;
84.5. Example
84.5.1. Name
Calculate the exponent of 2
84.5.2. Code
var
float : Double;
begin
// get the natural logarithm of 2
float := Ln(2);

// show this value
ShowMessage('Ln(2) = '+FloatToStr(float));

// get the exponent of this value - reverses the ln operation
float := Exp(float);

// show this value
ShowMessage('Exp(Ln(2)) = '+FloatToStr(float));
end;
84.5.3. Result
Ln(2) = 0.693147180559945
Exp(Ln(2)) = 2


Page 113 of 366

85. ExpandMailBox - Expands a MailBox
85.1. Unit
Iris Standard
85.2. Type
MailBox Function
85.3. Description
Expand the MailBox, to access its values and childs. MailBoxes can be used to pass structured
values to for example popups.
85.4. Syntax
function ExpandMailBox(InRef: string): string;
85.5. Example
85.5.1. Name
Using MailBoxes
85.5.2. Code
begin








ClearMailbox;

end;
85.5.3. Result


Page 114 of 366

86. ExpandPowerTree - Expands a PowerTree
86.1. Unit
Iris Standard
86.2. Type
MailBox Function
86.3. Description
Expand the PowerTree, to access its values and childs. The PowerTree can be used to pass
structured values to for example popups.
86.4. Syntax
function ExpandPowerTree(Sender: TObject; Addition: string): string;
86.5. Example
86.5.1. Name
Using the PowerTree in a generic popup
86.5.2. Code
// on a screen object you have connected 'tank13' to the powertree using the
tagconnector
// from that screen object you would call the code for a popup using the following:
procedure TUntitled.ButtonClick(Sender: TObject);
begin
// open the linked popup 'mytank', this will also send the powertree
LinkedPopup(Sender,'MyTank');
end;

// in the generic popup 'mytank' you would like to display the level
// this is done by connecting the level to [powertree].level
// you would also like to edit the tank's setpoint this should be the following
procedure TUntitled.ChangeSetpointClick(Sender: TObject);
begin
// call the numeditor to write to the 'tank'.setpoint using the powertree
NumEditor(Sender,ExpandPowerTree(Sender,'.SetPoint'));
end;
86.5.3. Result

You have written to Tank13.SetPoint using a generic popup


Page 115 of 366

87. ExtractFileDir - Extracts the dir part of a full file name
87.1. Unit
SysUtils
87.2. Type
Function
87.3. Description
The ExtractFileDir function extracts from FullFileName the directory substring. This is the part
of the full file name up to but not including the final \ before the file name.
87.4. Syntax
function ExtractFileDir(const FullFileName : string) : string;
87.5. Example
87.5.1. Name
Extract all of the parts of a full file name
87.5.2. Code
var
fullFileName : string;

begin
// set up a full file name with drive and path
fullFileName := 'C:\IrisProject\Test.dfm';

// show the component parts of this full name
ShowMessage('Drive = '+ExtractFileDrive (fullFileName));
ShowMessage('Dir = '+ExtractFileDir (fullFileName));
ShowMessage('Path = '+ExtractFilePath (fullFileName));
ShowMessage('Name = '+ExtractFileName (fullFileName));
ShowMessage('Ext = '+ExtractFileExt (fullFileName));
end;
87.5.3. Result
Drive = C:
Dir = C:\IrisProject
Path = C:\IrisProject\
Name = Test.dfm
Ext = .dfm


Page 116 of 366

88. ExtractFileDrive - Extracts the drive part of a full file
name
88.1. Unit
SysUtils
88.2. Type
Function
88.3. Description
The ExtractFileDrive function extracts from FullFileName the drive substring. if the file name
does not contain a drive prefix, then an empty string is returned.
88.4. Syntax
function ExtractFileDrive(const FullFileName : string) : string;
88.5. Example
88.5.1. Name
88.5.2. Code
var

begin

end;
88.5.3. Result
Drive = C:
Name = Test.dfm
Ext = .dfm


Page 117 of 366

89. ExtractFileExt - Extracts the extension part of a full
file name
89.1. Unit
SysUtils
89.2. Type
Function
89.3. Description
The ExtractFileExt function extracts from FullFileName the extension substring. The extension
is give inclusive of the '.' prefix, such as .txt
89.4. Syntax
function ExtractFileExt(const FullFileName : string) : string;
89.5. Example
89.5.1. Name
89.5.2. Code
var

begin

end;
89.5.3. Result
Drive = C:
Name = Test.dfm
Ext = .dfm


Page 118 of 366

90. ExtractFileName - Extracts the name part of a full file
name
90.1. Unit
SysUtils
90.2. Type
Function
90.3. Description
The ExtractFileName function extracts from FullFileName the file name substring.
90.4. Syntax
function ExtractFileName(const FullFileName : string) : string;
90.5. Example
90.5.1. Name
90.5.2. Code
var

begin

end;
90.5.3. Result
Drive = C:
Name = Test.dfm
Ext = .dfm


Page 119 of 366

91. ExtractFilePath - Extracts the path part of a full file
name
91.1. Unit
SysUtils
91.2. Type
Function
91.3. Description
The ExtractFilePath function extracts from FullFileName the path substring. This is the part of
the full file name up to and including the final \ before the file name.
91.4. Syntax
function ExtractFilePath(const FullFileName : string) : string;
91.5. Example
91.5.1. Name
91.5.2. Code
var

begin

end;
91.5.3. Result
Drive = C:
Name = Test.dfm
Ext = .dfm


Page 120 of 366

92. File - Defines a typed or untyped file
92.1. Unit
Iris Standard
92.2. Type
Keyword
92.3. Description
The file keyword is used to define a variable as a file, normally as written to and read from a
storage device. Defines the file with a base data type. for example, a simple type such as a
char or a complex type such as a record. AssignFile must be used to get a file handle. Reset
or ReWrite must then be used to open the file for read and/or write access. read and write
must be used to access the file. in all cases, the type must be of fixed size, and access to the
file must be in units of that type.
92.4. Syntax
var TypedFile : file of some type;


Page 121 of 366

92.5. Example
92.5.1. Name
Writing to and reading from a file
92.5.2. Code
var
myLine : string;
myFile : file;

begin
ReWrite(myFile);

// write two lines
WriteLn(myFile, 'this is just a test');
WriteLn(myFile, 'with a dummy line');

// close the file
CloseFile(myFile);

Reset(myFile);

begin
ReadLn(myFile, myLine);
ShowMessage(myLine);
end;

CloseFile(myFile);
end;
92.5.3. Result
this is just a test
with a dummy line


Page 122 of 366

93. FileAge - Get the last modified date/time of a file
without opening it
93.1. Unit
SysUtils
93.2. Type
Function
93.3. Description
The FileAge function returns the last modified date and time of a file FileName. There is no
need to open or close the file - this function handles these operations silently for you. The
returned value is in a 32 bit partitioned format. Use the FiledateToDateTime function to
convert into a manageable TDateTime value. if the file date could not be found (for example,
the FileName was invalid), then -1 is returned.
93.4. Syntax
function FileAge(const FileName : string) : Integer;
93.5. Example
93.5.1. Name
Get the last modified date of the current unit form file
93.5.2. Code
var
fileName : string;
fileDate : Integer;

begin
fileName := 'Test.dfm';

DateToStr(FileDateToDateTime(fileDate)));
end;
93.5.3. Result
Test.dfm last modified date = 10/11/2002


Page 123 of 366

94. FileDateToDateTime - Converts a file date/time format
to a TDateTime value
94.1. Unit
SysUtils
94.2. Type
Function
94.3. Description
The FileDateToDateTime function converts an Integer FileDate value (as obtained from
FileAge for example) to a more manageable TDateTime format. There are many routines in
Iris that can work on this TDateTime format.
94.4. Syntax
function FileDateToDateTime(const FileDate : Integer) : TDateTime;
94.5. Example
94.5.1. Name
Convert the last modified date of a file into a TDateTime value
94.5.2. Code
var
fileName : string;
fileDate : Integer;

begin
fileName := 'Test.dfm';

DateToStr(FileDateToDateTime(fileDate)));
end;
94.5.3. Result
Test.dfm last modified date = 10/11/2002


Page 124 of 366

95. FileExists - Returns true if the given file exists
95.1. Unit
SysUtils
95.2. Type
Function
95.3. Description
The FileExists function returns True if the given FileName file exists. The file is searched for in
the current directory. False may be returned if the user is not authorised to see the file.
95.4. Syntax
function FileExists(const FileName : string) : Boolean;


Page 125 of 366

95.5. Example
95.5.1. Name
Check for a file before and after deleting it
95.5.2. Code
var
fileName : string;
myFile : TextFile;
data : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

// reopen the file in read mode
Reset(myFile);

begin
ReadLn(myFile, data);
ShowMessage(data);
end;

CloseFile(myFile);

// now see if the file exists
if FileExists(fileName)
then ShowMessage(fileName+' exists OK')
else ShowMessage(fileName+' does not exist');

// delete the file and look again
DeleteFile(fileName);
if FileExists(fileName)
then ShowMessage(fileName+' still exists!')
else ShowMessage(fileName+' no longer exists');
end;
95.5.3. Result
Hello World
Test.txt exists OK
Test.txt no longer exists


Page 126 of 366

96. FileGetAttr - Gets the attributes of a file
96.1. Unit
SysUtils
96.2. Type
Function
96.3. Description
The FileGetAttr function returns attributes of the specified FileName. The returned Integer
value will be a bitwise combination of the following independent attributes: faReadOnly :
read-only filesfaHidden : Hidden filesfaSysFile : System filesfaVolumeID : Volume ID
filesfaDirectory : Directory filesfaArchive : Archive filesfaSymLink : Symbolic link
96.4. Syntax
function FileGetAttr(const FileName : string) : Integer;


Page 127 of 366

96.5. Example
96.5.1. Name
Create a text file and display its attributes
96.5.2. Code
var
fileName : string;
myFile : TextFile;

attrs : Integer;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

// get the file attributes
attrs := FileGetAttr(fileName);

// display these attributes
if attrs and faReadOnly > 0
then ShowMessage('file is read only')
else ShowMessage('file is not read only');

if attrs and faHidden > 0
then ShowMessage('file is hidden')
else ShowMessage('file is not hidden');

if attrs and faSysFile > 0
then ShowMessage('file is a system file')
else ShowMessage('file is not a system file');

if attrs and faVolumeID > 0
then ShowMessage('file is a volume ID')
else ShowMessage('file is not a volume ID');

if attrs and faDirectory > 0
then ShowMessage('file is a directory')
else ShowMessage('file is not a directory');

if attrs and faArchive > 0
then ShowMessage('file is archived')
else ShowMessage('file is not archived');

if attrs and faSymLink > 0
then ShowMessage('file is a symbolic link')
else ShowMessage('file is not a symbolic link');


Page 128 of 366

end;
96.5.3. Result
file is not read only
file is not hidden
file is not a system file
file is not a Volume ID
file is not a directory
file is archived
file is not a symbolic link


Page 129 of 366

97. FileSearch - Search for a file in one or more directories
97.1. Unit
SysUtils
97.2. Type
Function
97.3. Description
The FileSearch function searches for the given FileName in the given DirectoryList. The
FileName may be a file name or sub-path to a file. The DirectoryList is a ; separated list of
directory (path) names. if the file cannot be found, then an empty string is returned.
Otherwise, the full path plus the name of the file is returned. WARNING: the current directory
(see GetCurrentDir) is ALWAYS searched first, regardless of the given directories. if the file is
found there, then the returned path is Only the file name. You have been warned!
97.4. Syntax
function FileSearch(const FileName, DirectoryList : string) : string;


Page 130 of 366

97.5. Example
97.5.1. Name
Searching in the current directory and beyond
97.5.2. Code
var
myFile : TextFile;
fileName : string;
fullFilePath : string;
dir1, dir2 : string;

begin
// the file we will be searching for

// write to a text file in the current directory
ReWrite(myFile);
CloseFile(myFile);

// write to a text file to another directory
AssignFile(myFile, 'C:\program Files\'+fileName);
ReWrite(myFile);
CloseFile(myFile);

// define two directories where we want to search for the file
dir1 := 'C:\No such directory';
dir2 := 'C:\program Files';

// search for the file
fullFilePath := FileSearch(fileName, dir1+';'+dir2);

// if we search now, we will find it in the current directory
if fullFilePath = ''
then ShowMessage(fileName+' not found')
else ShowMessage(fullFilePath+' found OK');

// now delete test.txt from the current directory and retry
DeleteFile(fileName);

// if we search now, we will find it in one of the search dirs
fullFilePath := FileSearch(fileName, dir1+';'+dir2);
if fullFilePath = ''
then ShowMessage(fileName+' not found')
else ShowMessage(fullFilePath+' found OK');
end;
97.5.3. Result
Test.txt found OK
C:\program Files\Test.txt found OK


Page 131 of 366

98. FileSetDate - set the last modified date and time of a
file
98.1. Unit
SysUtils
98.2. Type
Function
98.3. Description
The SetFileDate function sets the last modified date and time of a file. Version 1 of this
function takes a FileHandle parameter to indicate the file. This requires use of the FileOpen
function, which is one of the low level file handling routines in Iris. Version 2 of this function
takes a FileName parameter to define the file. The file is searched for in the current directory.
The second parameter, FileAge is an Integer date/time representation that is used to change
the last modified date/time of the file. Use the DateTimeToFileDate function to convert a
TDateTime value to this integer format.
98.4. Syntax
1 function FileSetDate(FileHandle : Integer; FileAge : Integer) : Integer;
2 function FileSetDate (const FileName : string; FileAge : Integer) : Integer;


Page 132 of 366

98.5. Example
98.5.1. Name
Display, update, and redisplay the last modified date of a file
98.5.2. Code
var
fileName : string;
fileDate : Integer;
newDateTime : TDateTime;

begin
fileName := 'test.dfm';

begin

// now change the last modified date
newDateTime := StrToDateTime('01/01/2000 12:34:56');
FileSetDate(fileName, DateTimeToFileDate(newDateTime));
end;

// did we update the file last modified date ok?
end;
98.5.3. Result


Page 133 of 366

99. Finally - Starts the unconditional code section of a try
statement
99.1. Unit
Iris Standard
99.2. Type
Keyword
99.3. Description
The finally keyword is used to mark the start of the final block of statements in a try
statement. They are executed regardless of what happens in the try statements. However,
the finally clause does not actually handle any exceptions - the program will terminate if no
except clause is found (see notes below). try-finally is normally used by a routine to allow
cleanup processing to take place, such as freeing resources, with the exception being
correctly passed to the caller to handle.
99.4. Syntax
try
Statement
{statement...}
finally
Statement
{statement...}
end;


Page 134 of 366

99.5. Example
99.5.1. Name
Zero divide with a finally clause
99.5.2. Code
var
begin
number := -1;
try
zero := 0;
finally
if number = -1 then
begin
ShowMessage('Number was not assigned a value - using default');
number := 0;
end;
end;
end;
99.5.3. Result
Number was not assigned a value - using default

then, the program terminates with an division by zero error message - the finally
clause did not trap the error.


Page 135 of 366

100. FloatToStr - Convert a floating point value to a string
100.1. Unit
SysUtils
100.2. Type
Function
100.3. Description
The FloatToStr function converts a floating point number Value into a displayable string. The
value is displayed to 15 digits of precision. The Value type may be any of the floating point
types. Values before the decimal point (the mantissa) exceeding the display capacity (15)
result in a display using the exponent value, such as 1.2E9.
100.4. Syntax
function FloatToStr(Value : Extended) : string;
100.5. Example
100.5.1. Name
Display various sizes of extended data values
100.5.2. Code
var
amount1, amount2, amount3 : Extended;
begin
amount1 := 1234567890.123456789; // high precision number
amount2 := 1234567890123456.123; // high mantissa digits
amount3 := 1E100; // high value number

ShowMessage('Amount1 = '+FloatToStr(amount1));
end;
100.5.3. Result
Amount1 = 1234567890.12346
Amount2 = 1.23456789012346E15
Amount3 = 1E100


Page 136 of 366

101. FloatToStrF - Convert a floating point value to a
string with formatting
101.1. Unit
SysUtils
101.2. Type
Function
101.3. Description
The FloatToStrF function converts a floating point number Value into a displayable string,
with great control over the formatting via the Format, Precision, and Digits values. The Value
type may be any of the floating point types. The Format parameter is defined by the
TFloatFormat (SysUtils) type : ffCurrency eg : ?2,345.60ffExponent eg : 2.3456E+04ffFixed
eg : 2345.60ffGeneral eg : 2345.6ffNumber eg : 2,345.6 The other parameters are dependent
on this format. See TFloatFormat for full details.
101.4. Syntax
function FloatToStrF(Value : Extended; Format : TFloatFormat; Precision, Digits :
Integer) : string;
101.5. Example 1
101.5.1. Name
Display numbers as financial values
101.5.2. Code
var
amount1 : Extended;
begin
amount1 := 1234.567;

// display in a currency format
CurrencyString := '? ';
ShowMessage('Using 8,4 = '+FloatToStrF(amount1, ffCurrency, 8, 4));
end;
101.5.3. Result
Using 8,4 = ? 1,234.5670
Using 4,4 = ? 1,235.0000
Using 4,2 = ? 1,235.00
Using 2,4 = 1.2E0003


Page 137 of 366

101.6. Example 2
101.6.1. Name
Display numbers with Scientific formatting
101.6.2. Code
var
amount1 : Extended;
begin
amount1 := 1234.567;

// display in a scientific format
ShowMessage('Using 8,4 = '+FloatToStrF(amount1, ffExponent, 8, 4));
end;
101.6.3. Result
Using 8,4 = 1.2345670E+0003
Using 4,4 = 1.235E+0003
Using 4,2 = 1.235E+03
Using 2,4 = 1.2E+0003


Page 138 of 366

101.7. Example 3
101.7.1. Name
General display of numbers
101.7.2. Code
var
amount1 : Extended;
begin
amount1 := 1234.567;

// display in fixed format
ShowMessage('Fixed formatting :');
ShowMessage('Using 8,4 = '+FloatToStrF(amount1, ffFixed, 8, 4));

// display in general format
ShowMessage('');
ShowMessage('General formatting :');
ShowMessage('Using 8,4 = '+FloatToStrF(amount1, ffGeneral, 8, 4));
ShowMessage('Using 4,4 = '+FloatToStrF(amount1, ffgeneral, 4, 4));

// display in number format
ShowMessage('');
ShowMessage('Number formatting :');
ShowMessage('Using 8,4 = '+FloatToStrF(amount1, ffNumber, 8, 4));
end;
101.7.3. Result
Fixed formatting :
Using 8,4 = 1234.5670
Using 4,4 = 1235.0000
Using 4,2 = 1235.00
Using 2,4 = 1.2E0003

General formatting :
Using 8,4 = 1234.567
Using 4,4 = 1235
Using 4,2 = 1235
Using 2,4 = 1.2E0003

Number formatting :
Using 8,4 = 1,234.5670
Using 4,4 = 1,235.0000
Using 4,2 = 1,235.00
Using 2,4 = 1.2E0003


Page 139 of 366

102. Flush - Flushes buffered text file data to the file
102.1. Unit
System
102.2. Type
Procedure
102.3. Description
The Flush procedure flushes unwritten text file data to disk. The same effect can be achieved
by closing the file. in fact, this is more likely to be effective, since Flush simply passes the
flush request to the Operating System, which may in turn be doing its own buffering, and
possibly caching.
102.4. Syntax
procedure Flush(var FileHandle : TextFile);


Page 140 of 366

102.5. Example
102.5.1. Name
Flushing after writing lines to a file
102.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);

Flush(myFile);

// close the file
CloseFile(myFile);

Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
102.5.3. Result
Hello
World


Page 141 of 366

103. For - Starts a loop that executes a finite number of
times
103.1. Unit
Iris Standard
103.2. Type
Keyword
103.3. Description
The for keyword starts a control loop, which is executed a finite number of times. The
Variable is set to the result of the 1st Expression. if the result is less than or equal to the
result of the 2nd Expression (when to is specified), then the Statement is executed. Variable
is then incremented by 1 and the process is repeated until the variable value exceeds the 2nd
expression value. for downto, the variable value is checked as being greater than or equal to
the 2nd expression, and its value is decremented at the loop end. The Statement maybe a
single line, or a set of statements with a begin/end block.
103.4. Syntax
for Variable := Integer Expression to|downto Integer Expression do Statement;
103.5. Example
103.5.1. Name
Integer for loop
103.5.2. Code
var
i : Integer;

begin
// loop 5 times
for i := 1 to (10 div 2) do
end;
103.5.3. Result
i = 1
i = 2
i = 3
i = 4
i = 5


Page 142 of 366

104. ForceDirectories - Create a new path of directories
104.1. Unit
SysUtils
104.2. Type
Function
104.3. Description
The ForceDirectories function creates one or more nested directories specified by the Path. if
the create succeeded, then True is returned, otherwise the error can be obtained using
GetLastError.
104.4. Syntax
function ForceDirectories(const Path : string) : Boolean;
104.5. Example
104.5.1. Name
Create a new path on the C drive
104.5.2. Code
begin
// try to create a new nested directory in the current directory
if CreateDir('C:\NonExistantDir\TestDir')

// now force it to create this directory
if ForceDirectories('C:\NonExistantDir\TestDir')
end;
104.5.3. Result
New directory add failed with error ?
New directory added OK


Page 143 of 366

105. Format - Rich formatting of numbers and text into a
string
105.1. Unit
SysUtils
105.2. Type
Function
105.3. Description
The Format function provides 'C' like formatting of multiple of simple data types into a string.
It provides very precise control over this formatting. The Formatting parameter defines how
the Data array is manipulated into the returned string. The Formatting string can comprise a
mix of ordinary characters (that are passed unchanged to the result string), and data
formatting characters. This formatting is best explained by the example code. in simple
terms, each data formatting substring starts with a % and ends with a data type indicator : d
= Decimal (integer)e = Scientificf = Fixedg = Generalm = Moneyn = Number (floating)p =
Stringu = Unsigned decimalx = Hexadecimal The general format of each formatting substring
is as follows: %[index:][-][Width][.Precision]type where the square brackets refer to optional
parameters, and the : . - characters are literals, the first 2 of which are used to identify two
of the optional arguments.
105.4. Syntax
1 function Format(const Formatting : string; const Data : array of const) : string;


Page 144 of 366

105.5. Example 1
105.5.1. Name
Showing all of the formatting data types
105.5.2. Code
var
text : string;
begin
// just 1 data item
ShowMessage(Format('%s', ['Hello']));

// a mix of literal text and a data item
ShowMessage(Format('string = %s', ['Hello']));
ShowMessage('');

// examples of each of the data types
ShowMessage(Format('Decimal = %d', [-123]));
ShowMessage(Format('Exponent = %e', [12345.678]));
ShowMessage(Format('Fixed = %f', [12345.678]));
ShowMessage(Format('General = %g', [12345.678]));
ShowMessage(Format('Number = %n', [12345.678]));
ShowMessage(Format('Money = %m', [12345.678]));
ShowMessage(Format('string = %s', ['Hello']));
ShowMessage(Format('Unsigned decimal = %u', [123]));
ShowMessage(Format('Hexadecimal = %x', [140]));
end;
105.5.3. Result
Hello
string = Hello

Decimal = -123
Exponent = 1.23456780000000E+004
Fixed = 12345.68
General = 12345.678
Number = 12,345,68
Money = ?12,345.68
string = Hello
Unsigned decimal = 123
Hexadecimal = 8C


Page 145 of 366

105.6. Example 2
105.6.1. Name
Using the index, width and precision values
105.6.2. Code
begin
// the width value dictates the output size
// with blank padding to the left
// note the <> characters are added to show formatting
ShowMessage(Format('Padded decimal = <%7d>', [1234]));

// with the '-' operator, the data is left justified
ShowMessage(Format('Justified decimal = <%-7d>', [1234]));

// the precision value forces 0 padding to the desired size
ShowMessage(Format('0 padded decimal = <%.6d>', [1234]));

// a combination of width and precision
// note that width value precedes the precision value
ShowMessage(Format('Width + precision = <%8.6d>', [1234]));

// the index value allows the next value in the data array
// to be changed
ShowMessage(Format('Reposition after 3 strings = %s %s %s %1:s %s',
['Zero', 'One', 'Two', 'Three']));

// one or more of the values may be provided by the
// data array itself. note that testing has shown that an *
// for the width parameter can yield econverterror.
ShowMessage(Format('in line = <%10.4d>', [1234]));
ShowMessage(Format('Part data driven = <%*.4d>', [10, 1234]));
ShowMessage(Format('Data driven = <%*.*d>', [10, 4, 1234]));
end;
105.6.3. Result
Padded decimal =
Justified decimal =
0 padded decimal =
Width + precision =
Reposition after 3 strings = Zero One Two One Two
in line =
Part data driven =
Data driven =


Page 146 of 366

106. FormatCurr - Rich formatting of a currency value
into a string
106.1. Unit
SysUtils
106.2. Type
Function
106.3. Description
The FormatCurr function provides rich Formatting of a currency Value into a string. The
Formatting string may contain a mix of freeform text and control characters: 0 : Forces digit
display or 0# : Optional digit display, : Forces display of thousands. : Forces display of
decimalsE+ : Forces signed exponent displayE- : Optional sign exponent display; : Separator
of +ve -ve and zero values These are best understood by looking at the sample code.
106.4. Syntax
1 function FormatCurr(const Formatting : string; Value : Currency) : string;


Page 147 of 366

106.5. Example
106.5.1. Name
106.5.2. Code
var
curr : Currency;

begin
// set up our floating point number
curr := 1234.567;

// display a sample value using all of the format options

// round out the decimal value
ShowMessage('##### : '+FormatCurr('#####', curr));
ShowMessage('00000 : '+FormatCurr('00000', curr));
ShowMessage('0 : '+FormatCurr('0' , curr));
ShowMessage('#,##0 : '+FormatCurr('#,##0', curr));
ShowMessage(',0 : '+FormatCurr(',0' , curr));
ShowMessage('');

// include the decimal value
ShowMessage('0.#### : '+FormatCurr('0.####', curr));
ShowMessage('0.0000 : '+FormatCurr('0.0000', curr));
ShowMessage('');

// scientific format
ShowMessage('0.0000000E+00 : '+FormatCurr('0.0000000E+00', curr));
ShowMessage('0.0000000E-00 : '+FormatCurr('0.0000000E-00', curr));
ShowMessage('#.#######E-## : '+FormatCurr('#.#######E-##', curr));
ShowMessage('');

// include freeform text
ShowMessage('"Value = "0.0 : '+FormatCurr('"Value = "0.0', curr));
ShowMessage('');

// different formatting for negative numbers
curr := 1234.567;
ShowMessage('0.0 : '+FormatCurr('0.0' , -curr));
ShowMessage('0.0 "CR";0.0 "DB" : '+
FormatCurr('0.0 "CR";0.0 "DB"', -curr));
FormatCurr('0.0 "CR";0.0 "DB"', curr));
ShowMessage('');

// different format for zero value
curr := 0.0;
ShowMessage('0.0 : '+FormatCurr('0.0' , curr));
ShowMessage('0.0;-0.0;"Nothing" : '+
FormatCurr('0.0;-0.0;"Nothing"', curr));
end;


Page 148 of 366

106.5.3. Result
##### : 1235
00000 : 01235
0 : 1235
#,##0 : 1,235
,0 : 1,235

0.#### : 1234.567
0.0000 : 1234.5670

0.0000000E+00 : 1.2345670E+03
0.0000000E-00 : 1.2345670E03
#.#######E-## : 1.234567E3

"Value = " : Value = 1234.6

0.0 : -1234.6
0.0 "CR";0.0 "DB" : 1234.6 DB
0.0 "CR";0.0 "DB" : 1234.6 CR

0.0 : 0.0
0.0;-0.0;"Nothing" : Nothing


Page 149 of 366

107. FormatDateTime - Rich formatting of a TDateTime
variable into a string
107.1. Unit
SysUtils
107.2. Type
Function
107.3. Description
The FormatDateTime function provides rich formatting of a TDateTime value DateTime into a
string. Formatting is defined by the Formatting string. The Formatting string can comprise a
mix of ordinary characters (that are passed unchanged to the result string), and data
formatting characters. This formatting is best explained by the example code. The following
(non-Asian) formatting character strings can be used in the Formatting string: y = Year last 2
digitsyy = Year last 2 digitsyyyy = Year as 4 digitsm = Month number no-leading 0mm =
Month number as 2 digitsmmm = Month using ShortDayNames (Jan)mmmm = Month using
LongDayNames (January)d = Day number no-leading 0dd = Day number as 2 digitsddd =
Day using ShortDayNames (Sun)dddd = Day using LongDayNames (Sunday)ddddd = Day in
ShortDateFormatdddddd = Day in LongDateFormat c = Use ShortDateFormat +
LongTimeFormath = Hour number no-leading 0hh = Hour number as 2 digitsn = Minute
number no-leading 0nn = Minute number as 2 digitss = Second number no-leading 0ss =
Second number as 2 digitsz = Milli-sec number no-leading 0szzz = Milli-sec number as 3
digitst = Use ShortTimeFormattt = Use LongTimeFormat am/pm = Use after h : gives 12
hours + am/pma/p = Use after h : gives 12 hours + a/pampm = As a/p but
TimeAMString,TimePMString/ = Substituted by DateSeparator value: = Substituted by
TimeSeparator value Important : if you want to see characters such as dd in the formatted
output, placing them in " marks will stop them being interpreted as date or time elements. in
addition to this formatting, various of the above options are affected by the following
variables, withe their default values : DateSeparator = /TimeSeparator = :ShortDateFormat =
dd/mm/yyyyLongDateFormat = dd mmm yyyyTimeAMString = AMTimePMString =
PMShortTimeFormat = hh:mmLongTimeFormat = hh:mm:ssShortMonthNames = Jan Feb
...LongMonthNames = January, February ...ShortDayNames = Sun, Mon ...LongDayNames =
Sunday, Monday ...TwoDigitYearCenturyWindow = 50
107.4. Syntax
function FormatDateTime(const Formatting : string; DateTime : TDateTime) : string;


Page 150 of 366

107.5. Example 1
107.5.1. Name
Showing all of the date
107.5.2. Code
var
myDate : TDateTime;

begin

// date only - numeric values with no leading zeroes (except year)
ShowMessage(' d/m/y = '+
FormatDateTime('d/m/y', myDate));

// date only - numeric values with leading zeroes
ShowMessage(' dd/mm/yy = '+
FormatDateTime('dd/mm/yy', myDate));

// use short names for the day, month, and add freeform text ('of')
ShowMessage(' ddd d of mmm yyyy = '+
FormatDateTime('ddd d of mmm yyyy', myDate));

// use long names for the day and month
ShowMessage('dddd d of mmmm yyyy = '+
FormatDateTime('dddd d of mmmm yyyy', myDate));

// use the shortdateformat settings only
ShowMessage(' ddddd = '+
FormatDateTime('ddddd', myDate));

// use the longdateformat settings only
ShowMessage(' dddddd = '+
FormatDateTime('dddddd', myDate));

ShowMessage(' c = '+
FormatDateTime('c', myDate));
end;
107.5.3. Result
d/m/y = 5/6/00
dd/mm/yy = 05/06/00
ddd d of mmm yyyy = Mon 5 of Jun 2000
dddd d of mmmm yyyy = Monday 5 of June 2000
ddddd = 05/06/2000
c = 05/06/2000 01:02:03


Page 151 of 366

107.6. Example 2
107.6.1. Name
Showing all of the time
107.6.2. Code
var
myDate : TDateTime;

begin

// time only - numeric values with no leading zeroes
ShowMessage(' h:n:s.z = '+FormatDateTime('h:n:s.z', myDate));

// time only - numeric values with leading zeroes
ShowMessage('hh:nn:ss.zzz = '+FormatDateTime('hh:nn:ss.zzz', myDate));

// use the shorttimeformat settings only
ShowMessage(' t = '+FormatDateTime('t', myDate));

// use the longtimeformat settings only
ShowMessage(' tt = '+FormatDateTime('tt', myDate));

ShowMessage(' c = '+FormatDateTime('c', myDate));
end;
107.6.3. Result
h:m:s.z = 1:2:3.4
hh:mm:ss.zzz = 01:02:03.004
t = 01:02
tt = 01:02:03
c = 05/06/2000 01:02:03


Page 152 of 366

107.7. Example 3
107.7.1. Name
Showing the effect of local date format settings
107.7.2. Code
var
myDate : TDateTime;

begin
//
// note that 49 is treated as 2049 as follows :
// twodigityearcenturywindow => 50
// current year => 2008 (at time of writing)
// subtract twodigityearcenturywindow => 1958
// 2 digit year to be converted => 49
// compare with the last 2 digits of 1958 => less
// so the year is in the next century => 2049
// (58 would be converted to 1958)

myDate := StrToDateTime('05/06/49 01:02:03.004');

// demonstrate default locale settings

// use the dateseparator and timeseparator values
ShowMessage('dd/mm/yy hh:nn:ss = '+
FormatDateTime('dd/mm/yy hh:nn:ss', myDate));

// use the shortdateformat string
ShowMessage('ddddd = '+FormatDateTime('ddddd', myDate));

// use the longdateformat string
ShowMessage('dddddd = '+FormatDateTime('dddddd', myDate));

// use the timeamstring
ShowMessage('hhampm = '+FormatDateTime('hhampm', myDate));

// use the shorttimeformat string
ShowMessage('t = '+FormatDateTime('t', myDate));

// use the longtimeformat string
ShowMessage('tt = '+FormatDateTime('tt', myDate));

// use the twodigitcenturywindow
ShowMessage('dd/mm/yyyy = '+
FormatDateTime('dd/mm/yyyy', myDate));

ShowMessage('');

// now change the defaults
DateSeparator := '-';
TimeSeparator := '_';
ShortDateFormat := 'dd/mmm/yy';
LongDateFormat := 'dddd dd of mmmm of yyyy';


Page 153 of 366

TimeAMString := 'morning';
TimePMString := 'afternoon';
ShortTimeFormat := 'hh:nn:ss';
LongTimeFormat := 'hh : nn : ss . zzz';
TwoDigitYearCenturyWindow := 75; // this means 49 is treated as 1949

// set up our tdatetime variable with the same value as before
// except that we must use the new date and time separators
// the twodigityearcenturywindow variable only takes effect here
myDate := StrToDateTime('09-02-49 01_02_03.004');

// use the dateseparator and timeseparator values
ShowMessage('dd/mm/yy hh:nn:ss = '+
FormatDateTime('dd/mm/yy hh:nn:ss', myDate));

// use the shortdateformat string
ShowMessage('ddddd = '+FormatDateTime('ddddd', myDate));

// use the longdateformat string
ShowMessage('dddddd = '+FormatDateTime('dddddd', myDate));

// use the timeamstring
ShowMessage('hhampm = '+FormatDateTime('hhampm', myDate));

// use the shorttimeformat string
ShowMessage('t = '+FormatDateTime('t', myDate));

// use the longtimeformat string
ShowMessage('tt = '+FormatDateTime('tt', myDate));

// use the twodigitcenturywindow
ShowMessage('dd/mm/yyyy = '+
FormatDateTime('dd/mm/yyyy', myDate));
end;
107.7.3. Result
dd/mm/yy hh:mm:ss = 05/06/49 01:02:03
ddddd = 05/06/2049
hhampm = 01AM
t = 01:02
tt = 01:02:03
dd/mm/yyyy = 05/06/2049

dd/mm/yy hh:nn:ss = 05-06-49 01_02_03
ddddd = 05-Jun-49
dddddd = Sunday 05 of June of 1949
hhampm = 01morning
t = 01_02_03
tt = 01 _ 02 _ 03 . 004
dd/mm/yyyy = 05-06-1949


Page 154 of 366

108. FormatFloat - Rich formatting of a floating point
number into a string
108.1. Unit
SysUtils
108.2. Type
Function
108.3. Description
The FormatFloat function provides rich Formatting of a floating point number Value into a
string. The Formatting string may contain a mix of freeform text and control characters: 0 :
Forces digit display or 0# : Optional digit display, : Forces display of thousands. : Forces
display of decimalsE+ : Forces signed exponent displayE- : Optional sign exponent display; :
Separator of +ve and -ve and zero values These are best understood by looking at the
sample code.
108.4. Syntax
function FormatFloat(const Formatting : string; Value : Extended) : string;


Page 155 of 366

108.5. Example
108.5.1. Name
108.5.2. Code
var
float : extended;

begin
// set up our floating point number
float := 1234.567;

// display a sample value using all of the format options

// round out the decimal value
ShowMessage('##### : '+FormatFloat('#####', float));
ShowMessage('00000 : '+FormatFloat('00000', float));
ShowMessage('0 : '+FormatFloat('0' , float));
ShowMessage('#,##0 : '+FormatFloat('#,##0', float));
ShowMessage(',0 : '+FormatFloat(',0' , float));
ShowMessage('');

// include the decimal value
ShowMessage('0.#### : '+FormatFloat('0.####', float));
ShowMessage('0.0000 : '+FormatFloat('0.0000', float));
ShowMessage('');

// scientific format
ShowMessage('0.0000000E+00 : '+FormatFloat('0.0000000E+00', float));
ShowMessage('0.0000000E-00 : '+FormatFloat('0.0000000E-00', float));
ShowMessage('#.#######E-## : '+FormatFloat('#.#######E-##', float));
ShowMessage('');

// include freeform text
ShowMessage('"Value = "0.0 : '+FormatFloat('"Value = "0.0', float));
ShowMessage('');

// different formatting for negative numbers
ShowMessage('0.0 : '+FormatFloat('0.0' , -1234.567));
FormatFloat('0.0 "CR";0.0 "DB"', -1234.567));
FormatFloat('0.0 "CR";0.0 "DB"', 1234.567));
ShowMessage('');

// different format for zero value
ShowMessage('0.0 : '+FormatFloat('0.0' , 0.0));
ShowMessage('0.0;-0.0;"Nothing" : '+
FormatFloat('0.0;-0.0;"Nothing"', 0.0));
end;


Page 156 of 366

108.5.3. Result
##### : 1235
00000 : 01235
0 : 1235
#,##0 : 1,235
,0 : 1,235

0.#### : 1234.567
0.0000 : 1234.5670

0.0000000E+00 : 1.2345670E+03
0.0000000E-00 : 1.2345670E03
#.#######E-## : 1.234567E3

"Value = " : Value = 1234.6

0.0 : -1234.6
0.0 "CR";0.0 "DB" : 1234.6 DB
0.0 "CR";0.0 "DB" : 1234.6 CR

0.0 : 0.0
0.0;-0.0;"Nothing" : Nothing


Page 157 of 366

109. Frac - The fractional part of a floating point number
109.1. Unit
System
109.2. Type
Function
109.3. Description
The Frac function returns the fractional part of a floating point number.
109.4. Syntax
function Frac(const Number : Extended) : Extended;
109.5. Example
109.5.1. Name
A simple example
109.5.2. Code
begin
ShowMessage('Round(12.75) = '+IntToStr(Round(12.75)));
ShowMessage('Trunc(12.75) = '+IntToStr(Trunc(12.75)));
ShowMessage(' Int(12.75) = '+FloatToStr(Int(12.75)));
ShowMessage(' Frac(12.75) = '+FloatToStr(Frac(12.75)));
end;
109.5.3. Result
Round(12.75) = 13
Trunc(12.75) = 12
Int(12.75) = 12
Frac(12.75) = 0.75


Page 158 of 366

110. Function - Defines a subroutine that returns a value
110.1. Unit
System
110.2. Type
Keyword
110.3. Description
The function keyword defines a subroutine that returns a value. See the SubRoutines tutorial
for details on using functions. Version 1 - Defines a function that simply returns a data type.
Only one value can be returned from a function. Version 2 - Defines a function that is passed
one or more parameters, and returns a data type. Only one value can be returned from a
function. However, using the out or var keyword before a parameter allows the parameter to
be treated as variable to contain return values. in both cases, the returned value is passed by
assigning to the Result pseudo variable. Iris creates this variable for you at the function start,
with the correct return data type.
110.4. Syntax
1 function Name : Return type; {directives;}
2 function Name(Parameters) : Return type; {directives;}


Page 159 of 366

110.5. Example
110.5.1. Name
A simple example
110.5.2. Code
// -----------------------------------------------------------
// complete iris script page
// -----------------------------------------------------------
unit total; // the name of the unit, in this case the default name 'untitled'

interface // used to start the definitions

uses // defines a list of units that are used on this page
Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs;

type // defines a new category of variable or process
TUntitled = class(TIrisScreen)
procedure IrisScreenCreate(Sender: TObject);
procedure SayHelloTo(Name: string);
function NameLength(Name: string): integer;
procedure ShowDifference;
function GetTimeAsString: string;
private // starts the section of private data and methods in a class
{ private declarations }
public // starts an externally accessible section of a class
{ public declarations }
end;

var // starts the definition of a section of data variables
Untitled: TUntitled; // variable that refers to the screen name
UserNameLength: integer; // variable that will be used in the script

const // starts the definition of fixed data values
AverageUserNameLength = 7.25; // constant value that will be used in the script

implementation // starts the implementation (code) section of a unit

{$r *.dfm}

// start of the iris screen create function, this is called as soon as the page is
loaded
procedure TUntitled.IrisScreenCreate(Sender: TObject);
var
UserName string;
begin
// asking for the users name
repeat
UserName := InputBox('Iris Test Script', 'Please enter your name', 'John');
until UserName <> '';

// call the procedure to welcome the user
SayHelloTo(UserName);
// call the function to get the length of the users name and store it in a variable
UserNameLength := NameLength(UserName);


Page 160 of 366

// show both username and its length in a message and get the constant average
length
ShowMessage(UserName+', did you know your name has '+IntToStr(UserNameLength)+
' characters and the average name has '+FloatToStr(AverageUserNameLength)+'
characters?');
// call another procedure, but this time without arguments
ShowDifference;
end;

// procedure with an argument
procedure TUntitled.SayHelloTo(Name: string);
begin
// show a message with a welcome text, a newline character (#10#13) and the current
time from a function without arguments
ShowMessage('Welcome to Iris, '+Name+#10#13+GetTimeAsString);
end;

// function with arguments and a return value (mandatory)
function TUntitled.NameLength(Name: string): integer;
begin
// trim spaces from the name, get the length of the name and return it
Result := Length(Trim(Name));
end;

// procedure without arguments
procedure TUntitled.ShowDifference;
begin
// show a message with the difference in length by accesing the var and const parts
from this page
ShowMessage('Well, that''''s only a difference of '+FloatToStr(Abs(UserNameLength-
AverageUserNameLength))+' characters');
end;

// function without arguments
procedure TUntitled.GetTimeAsString: string;
begin
// return the current time as a string
Result := 'It is now: '+TimeToStr(Now);
end;

// end of the file, not that this ends with a dot instead of a semi-colon
end.
110.5.3. Result
Please enter your name

Welcome to Iris, John
It is now 12:34:56

John, did you know your name has 4 characters and the average name has 7.25 characters

Well, that's only a difference of 3.25 characters


Page 161 of 366

111. GetCurrentDir - Get the current directory (drive plus
directory)
111.1. Unit
SysUtils
111.2. Type
Function
111.3. Description
The GetCurrentDir procedure returns a string containing the drive plus path name of the
current directory.
111.4. Syntax
function GetCurrentDir : string;
111.5. Example
111.5.1. Name
Getting the current directory
111.5.2. Code
var
dir : string;

begin
// get the current directory
dir := GetCurrentDir;
ShowMessage('Current directory = '+dir);
end;
111.5.3. Result
Current directory = C:\IrisTest


Page 162 of 366

112. GetDir - Get the default directory (drive plus path)
for a specified drive
112.1. Unit
System
112.2. Type
Procedure
112.3. Description
The GetDir procedure stores in the passed parameter Directory string the drive plus path
name of the default directory on the specified Drive. Drive values : 0 = default drive1 = A:
drive2 = B: drive3 = C: drive4 = D: drive and so on.
112.4. Syntax
procedure GetDir(Drive : Byte; var Directory : string);
112.5. Example
112.5.1. Name
Getting the directory for the C: drive
112.5.2. Code
var
DirName : string;

begin
GetDir(3, DirName); // store c: directory in the dirname variable
ShowMessage(DirName);
end;
112.5.3. Result
The following output is representative, and will necessarily vary
from PC to PC:

C:\IrisTest


Page 163 of 366

113. GetPageDir - Returns the page directory
113.1. Unit
Iris Standard
113.2. Type
Frame Function
113.3. Description
Returns the working directory of the current page as a string. This can be used to access files
that are inside the Iris project directory.
113.4. Syntax
function GetPageDir: string;
113.5. Example
113.5.1. Name
Alter the working directory
113.5.2. Code
begin
// read the original working directory
ShowMessage('The original working directory is '+GetPageDir);

// set the working directory to c:\
SetPageDir('C:\');

// read the new working directory
ShowMessage('The new working directory is '+GetPageDir);

end;
113.5.3. Result

The original working directory is C:\IrisTest
The new working directory is C:\


Page 164 of 366

114. GetTagProp - Reads a property of a tag
114.1. Unit
Iris Standard
114.2. Type
Tag Function
114.3. Description
Read a property of a tag. The following properties are available: ScaledMin ScaledMax
RoLimitHigh RoLimitLow Name Description
114.4. Syntax
function GetTagProp(TagName: string; PropName: string): Variant;
114.5. Example 1
114.5.1. Name
read a tag property
114.5.2. Code
var
value: integer;

begin
// read the property 'rolimithigh' of tag 'tagname' into variable 'value'
value := GetTagProp('tagname','RoLimitHigh');

// display the value
ShowMessage('The property value is '+IntToStr(Value));
114.5.3. Result
The property value is ?


Page 165 of 366

114.6. Example 2
114.6.1. Name
read a tag property through a PowerTree
114.6.2. Code
var
value: integer;

begin
// read the property 'scaledmin' of tag '[powertree].name' into variable 'value'
value := GetTagProp(ExpandMailbox('[PowerTree].name'),'ScaledMin');

ShowMessage('The property value is '+IntToStr(Value));
end;
114.6.3. Result
114.7. Example 3
114.7.1. Name
read a property from a structured tag
114.7.2. Code
var
value: string;

begin
// read the property 'description' of tag 'unit1.equipmentmodule2' into variable
'value'
value := GetTagProp('Unit1.EquipmentModule2','Description');

ShowMessage('The property value is '+Value);
end;
114.7.3. Result


Page 166 of 366

115. GetTagValue - Reads the value of a tag
115.1. Unit
Iris Standard
115.2. Type
Tag Function
115.3. Description
Reads the current value from a tag into a variable. It is possible to read values from device
and internal tags.
115.4. Syntax
function GetTagValue(TagName: string): Variant;
115.5. Example 1
115.5.1. Name
read/write a tag value
115.5.2. Code
var
value: integer;

begin
// read the value of tag 'tagname' into variable 'value'
value := GetTagValue('tagname');

ShowMessage('The old value is '+IntToStr(Value));

// write a new value to the tag 'tagname'
WriteTagValue('tagname',Inc(value));


ShowMessage('The New value is '+IntToStr(Value));
end;
115.5.3. Result
The old value is ?
The new value is ?


Page 167 of 366

115.6. Example 2
115.6.1. Name
Read/write a tag value through a PowerTree
115.6.2. Code
var
value: integer;

begin
// read the value of tag '[powertree].name' into variable 'value'
value := GetTagValue(ExpandMailbox('[PowerTree].name')));


// write a new value to the tag '[powertree].name'
WriteTagValue(ExpandMailbox('[PowerTree].name'),Inc(value));

value := GetTagValue(ExpandMailbox('[PowerTree].name'));

end;
115.6.3. Result
The old value is ?
The new value is ?


Page 168 of 366

115.7. Example 3
115.7.1. Name
Read/write a tag value from a structured tag
115.7.2. Code
var
value: integer;

begin
// read the value of tag 'unit1.equipmentmodule2' into variable 'value'
value := GetTagValue('Unit1.EquipmentModule2');


WriteTagValue('Unit1.EquipmentModule2',Inc(value));


end;
115.7.3. Result
The old value is ?
The new value is ?


Page 169 of 366

116. Goto - Forces a jump to a label, regardless of nesting
116.1. Unit
Iris Standard
116.2. Type
Keyword
116.3. Description
The goto keyword forces a jump to a given label. It should Never be used in modern code
since it makes code very difficult to maintain. It is mostly used to force a termination of
heavily nested code, where the logic to safely exit would be tortuous. Never jump into or out
of try statements, or into a loop or conditional block. Be careful!
116.4. Syntax
goto label
116.5. Example
116.5.1. Name
A simple goto test
116.5.2. Code
var
i : Integer;

label
GotoLabel;

begin
for i := 1 to 10 do
begin

if i = 4 then goto GotoLabel; // conditionally exit the loop
end;

ShowMessage('The loop finished OK');
GotoLabel:
ShowMessage('Loop finished with i = '+IntToStr(i));
end;
116.5.3. Result
i = 1
i = 2
i = 3
i = 4
Loop finished with i = 4


Page 170 of 366

117. If - Starts a conditional expression to determine
what to do next
117.1. Unit
Iris Standard
117.2. Type
Keyword
117.3. Description
The if keyword is used to control the flow of code depending on the logical result of the given
condition. There are two forms of the if statement - one with an else clause, the other not. if
works as follows: if the condition is true, then the first statement is executed. if false, then
this statement is bypassed. if there is an else statement, it is executed instead. in all cases,
the Statement clause must be a contained in a begin/end block if it is longer than one
statement in length.
117.4. Syntax
1 if Condition then Statement;


Page 171 of 366

117.5. Example
117.5.1. Name
Illustrate the different flavours of the if statement
117.5.2. Code
begin
// illustrate a simple if statement that executes true
if True then ShowMessage('True!');

// illustrate the same, but with multiple actions
if 1 = 1 then
begin
ShowMessage('We now have');
ShowMessage('multiple lines');
end;

// illustrate a simple if statement that fails
if 1 = 2 then ShowMessage('1 = 2');

// illustrate an if then else statement
if False

if true then
if false then
else
else
end;
117.5.3. Result
True!
We now have
multiple lines
False


Page 172 of 366

118. Implementation - Starts the implementation (code)
section of a unit
118.1. Unit
Iris Standard
118.2. Type
Keyword
118.3. Description
The implementation keyword starts the active code section of a unit - where the interface
declarations are implemented. Within the implementation section, the functions and
procedures defined in the interface section are coded. This section may have its own
functions, procedures and data over and above that defined by the interface. These are in
effect private to the unit. It may also have its own uses statement, where Units are defined
that are only used by the implementation. They are specific to the implementation, and
external users of the unit need not know about them.
118.4. Syntax
unit UnitName;
interface
Declarations...
implementation
Declarations...
end;


Page 173 of 366

118.5. Example
118.5.1. Name
A simple example
118.5.2. Code
// -----------------------------------------------------------
// -----------------------------------------------------------



end;




{$r *.dfm}

loaded
var
UserName string;
begin
repeat



Page 174 of 366

length
characters?');
ShowDifference;
end;

begin
end;

begin
end;

begin
from this page
end;

begin
end;

end.
118.5.3. Result

It is now 12:34:56




Page 175 of 366

119. Inc - Increment an ordinal variable
119.1. Unit
System
119.2. Type
Procedure
119.3. Description
The Inc procedure increments the ordinal Variable parameter passed to it. You can
increment: Characters Non-floating number types Enumeration types Pointers The increment
is by the base size of the unit. for example, incrementing a Pointer will be by 4 bytes if the
pointer points to Words. Version 1 of Inc increments by 1 unit. Version 2 of Inc increments by
Count units.
119.4. Syntax
1 procedure Inc(var Variable : Ordinal variable);
2 procedure Inc ( var Variable : Ordinal variable; Count : Integer ) ;
119.5. Example
119.5.1. Name
Incrementing numbers
119.5.2. Code
var
Number : Integer;

begin
Number := 22;

Inc(Number);
ShowMessage('Number+1 : '+IntToStr(Number));
Inc(Number, 5);
end;
119.5.3. Result

Number : 22
Number+1 : 23
Number+5 : 28


Page 176 of 366

120. IncDay - Increments a TDateTime variable by + or -
number of days
120.1. Unit
DateUtils
120.2. Type
Function
120.3. Description
The IncDay function returns a TDateTime value that is NumberOfDays greater than the
passed StartDateTime value. The year and month values are incremented as appropriate. The
increment value is optional, being 1 by default.
120.4. Syntax
function IncDay(const StartDateTime : TDateTime; { numberofdays : integer = 1}) :
TDateTime;
120.5. Example
120.5.1. Name
A simple example of increment and decrement
120.5.2. Code
var
myDate : TDateTime;
begin
// set up our date just before the end of the year 2000

// add 10 days to this date
myDate := IncDay(myDate, 10);
ShowMessage('myDate + 10 days = '+DateToStr(myDate));

// subtract 12 days from this date
myDate := IncDay(myDate, -12);
ShowMessage('myDate - 12 days = '+DateToStr(myDate));
end;
120.5.3. Result
myDate = 30/12/2000
myDate + 10 days = 09/01/2001
myDate - 12 days = 29/12/2000


Page 177 of 366

121. IncMillisecond - Increments a TDateTime variable by
+ or - number of mseconds
121.1. Unit
DateUtils
121.2. Type
Function
121.3. Description
The IncMillisecond function returns a TDateTime value that is NumberOfMilliSeconds greater
than the passed StartDateTime value. The year, month, day and hour values are incremented
as appropriate. The increment value is optional, being 1 by default.
121.4. Syntax
function IncMillisecond(const StartDateTime : TDateTime {; numberofmilliseconds :
integer = 1}) : TDateTime;
121.5. Example
121.5.1. Name
121.5.2. Code
var
myDate : TDateTime;
begin
// set up our date to the start of 2006
ShowMessage('myDate = '+DateTimeToStr(myDate));

// add 5000 milliseconds to this date
myDate := IncMillisecond(myDate, 5000);
ShowMessage('myDate + 5000 milliseconds = '+DateTimeToStr(myDate));

// subtract 2000 milliseconds from this date
myDate := IncMillisecond(myDate, -2000);
ShowMessage('myDate - 2000 milliseconds = '+DateTimeToStr(myDate));
end;
121.5.3. Result
myDate = 01/01/2006
myDate = 01/01/2006 00:00:05
myDate = 01/01/2006 00:00:03


Page 178 of 366

122. IncMinute - Increments a TDateTime variable by +
or - number of minutes
122.1. Unit
DateUtils
122.2. Type
Function
122.3. Description
The IncMinute function returns a TDateTime value that is NumberOfMinutes greater than the
passed StartDateTime value. The year, month, day and hour values are incremented as
appropriate. The increment value is optional, being 1 by default.
122.4. Syntax
function IncMinute(const StartDateTime : TDateTime {; numberofminutes : integer = 1})
: TDateTime;
122.5. Example
122.5.1. Name
122.5.2. Code
var
myDate : TDateTime;
begin

// add 100 minutes to this date
myDate := IncMinute(myDate, 100);
ShowMessage('myDate + 100 minutes = '+DateTimeToStr(myDate));

// subtract 40 minutes from this date
myDate := IncMinute(myDate, -40);
ShowMessage('myDate - 40 minutes = '+DateTimeToStr(myDate));
end;
122.5.3. Result
myDate = 31/12/2000 23:00:00
myDate + 100 minutes = 01/01/2001 00:40:00
myDate - 40 minutes = 01/01/2001


Page 179 of 366

123. IncMonth - Increments a TDateTime variable by a
number of months
123.1. Unit
SysUtils
123.2. Type
Function
123.3. Description
The IncMonth function returns a TDateTime value that is NumberOfMonths greater than the
passed StartDate value. The time component of the StartDate value is passed unchanged to
the output value. The year value is incremented as appropriate. The increment value is
optional, being 1 by default. After incrementing the month, if the day value is too high for
that month/year, then it is reduced to the highest value for that month/year.
123.4. Syntax
function IncMonth(const StartDate : TDateTime {; numberofmonths : integer = 1}) :
TDateTime;
123.5. Example
123.5.1. Name
Add values to an example date
123.5.2. Code
var
myDate : TDateTime;
begin
myDate := StrToDate('31/01/2000'); // end of jan in a leap year

// increment by 1 (default)
// 31st jan 2000 ==> 31st feb 2000 (illegal) ==> 29th feb 2000
myDate := IncMonth(myDate);
ShowMessage('myDate + 1 month = '+DateToStr(myDate));

// increment by 12 months
// 29th feb 2000 ==> 29th feb 2000 (illegal) ==> 28th feb 2001
myDate := IncMonth(myDate, 12); // increment by 12 months
ShowMessage('myDate + 12 months = '+DateToStr(myDate));
end;
123.5.3. Result
myDate = 31/01/2000
myDate + 1 month = 29/02/2000
myDate + 12 months = 28/02/2001


Page 180 of 366

124. IncSecond - Increments a TDateTime variable by +
or - number of seconds
124.1. Unit
DateUtils
124.2. Type
Function
124.3. Description
The IncSecond function returns a TDateTime value that is NumberOfSeconds greater than
the passed StartDateTime value. The year, month, day and hour values are incremented as
appropriate. The increment value is optional, being 1 by default.
124.4. Syntax
function IncSecond(const StartDateTime : TDateTime {; numberofseconds : integer = 1})
: TDateTime;
124.5. Example
124.5.1. Name
124.5.2. Code
var
myDate : TDateTime;
begin

// add 60 seconds to this date
myDate := IncSecond(myDate, 60);
ShowMessage('myDate + 60 seconds = '+DateTimeToStr(myDate));

// subtract 120 seconds from this date
myDate := IncSecond(myDate, -120);
ShowMessage('myDate - 120 seconds = '+DateTimeToStr(myDate));
end;
124.5.3. Result
myDate = 31/12/2005 23:59:00
myDate + 60 seconds = 01/01/2006
myDate - 120 seconds = 31/12/2005 23:58:00


Page 181 of 366

125. IncYear - Increments a TDateTime variable by a
number of years
125.1. Unit
DateUtils
125.2. Type
Function
125.3. Description
The IncYear function returns a TDateTime value that is NumberOfYears greater than the
passed StartDateTime value. The increment value is optional, being 1 by default. After
incrementing the year, if the day value is too high for that month/year, then it is reduced to
the highest value for that month/year.
125.4. Syntax
function IncYear(const StartDate : TDateTime {; numberofyears : integer = 1}) :
TDateTime;
125.5. Example
125.5.1. Name
Add and then subtract 2 years to an example date
125.5.2. Code
var
myDate : TDateTime;
begin
// set up our date to a leap year special day

// add 2 years to this date
myDate := IncYear(myDate, 2);
ShowMessage('myDate + 2 years = '+DateToStr(myDate));

// subtract 2 years from this date
myDate := IncYear(myDate, -2);
ShowMessage('myDate - 2 years = '+DateToStr(myDate));
end;
125.5.3. Result
myDate = 29/02/2000
myDate + 2 years = 28/02/2002
myDate - 2 years = 28/02/2000


Page 182 of 366

126. Infinity - Floating point value of infinite size
126.1. Unit
Math
126.2. Type
Constant
126.3. Description
The Infinity constant is a special floating point number, marked as infinite in size. It may be
assigned and calculated upon, but use IsInfinite for comparisons.
126.4. Syntax
const Infinity = 1.0 / 0.0;
126.5. Example
126.5.1. Name
Illustrate use of Infinity
126.5.2. Code
var
float1, float2 : single;
begin
float1 := Infinity;
float2 := 23;

ShowMessage('float1 = '+FloatToStr(float1));
ShowMessage('float2 = '+FloatToStr(float2));
ShowMessage('float1 - float2 = '+FloatToStr(float1 - float2));
ShowMessage('-float1 = '+FloatToStr(-float1));
end;
126.5.3. Result
float1 = INF
float2 = 23
float1 - float2 = INF
-float1 = -INF


Page 183 of 366

127. InputBox - Display a dialog that asks for user text
input, with default
127.1. Unit
Dialogs
127.2. Type
Function
127.3. Description
The InputBox function displays a simple dialog box with the given Caption and Prompt
message. It asks the user to enter data in a text box on the dialog. A default value is
displayed in the text box. if the user presses OK, the default or user entered data is stored in
the return string, otherwise an empty string is returned. if the user cancels the dialog, then
the return value is an empty string. Use to ask the user for a data value, where you can give
a sensible default value, to save the user unnecessary typing.
127.4. Syntax
function InputBox(const Caption, Prompt, default : string) : string;
127.5. Example
127.5.1. Name
Keep asking the user for their city with a default
127.5.2. Code
var
value : string;

begin
// keep asking the user for their town
repeat
value := InputBox('Test program', 'Please type your town', 'Cardiff');
until value <> '';

// show their name
ShowMessage('Your town is '+value);
end;
127.5.3. Result
A dialog is displayed asking for the user city,
with Cardiff given as the initial value.

if the user just hits OK, then :

Your town is Cardiff

is then displayed


Page 184 of 366

128. InputQuery - Display a dialog that asks for user text
input
128.1. Unit
Dialogs
128.2. Type
Function
128.3. Description
The InputQuery function displays a simple dialog box with the given Caption and Prompt
message. It asks the user to enter data in a text box on the dialog. if the user presses OK,
the entered data is stored in the UserValue variable and the return value is True. if the user
cancels the dialog, then the return value is False and any entered data is lost. Use to ask the
user for simple data such as a name.
128.4. Syntax
function InputQuery(const Caption, Prompt : string; var UserValue : string) : Boolean;
128.5. Example
128.5.1. Name
Keep asking the user for their name until they do so
128.5.2. Code
var
value : string;

begin
// keep asking the user for their name
repeat
if not InputQuery('Test program', 'Please type your name', value)
then ShowMessage('User cancelled the dialog');
until value <> '';

// show their name
ShowMessage('Hello '+value);
end;
128.5.3. Result
A dialog is displayed asking for the user name.
if the user types their name, 'Fred' and hits OK :

Hello Fred

is then displayed


Page 185 of 366

129. Insert - Insert a string into another string
129.1. Unit
System
129.2. Type
Procedure
129.3. Description
The Insert procedure inserts one string, InsertStr into another string, TargetStr at the given
Position. The TargetStr string characters from the Position character are moved right to make
way for the InsertStr string. The length of TargetStr is now the sum of the length of the two
strings. to insert into the start of TargetStr, set Position to 1 or less. to append to the end of
TargetStr, set Position after the last character of TargetStr.
129.4. Syntax
procedure Insert(const InsertStr : string; var TargetStr : string; Position :
Integer);
129.5. Example
129.5.1. Name
Inserting into the middle of a string
129.5.2. Code
var
Target : string;
begin
Target := '12345678';
Insert('-+-', Target, 3);
ShowMessage('Target : '+Target);
end;
129.5.3. Result
Target : 12-+-345678


Page 186 of 366

130. Int - The integer part of a floating point number as a
float
130.1. Unit
System
130.2. Type
Function
130.3. Description
The Int function returns the integer part of a floating point number as a floating point
number.
130.4. Syntax
function Int(const Number : Extended) : Extended;
130.5. Example
130.5.1. Name
A simple example
130.5.2. Code
begin
end;
130.5.3. Result
Round(12.75) = 13
Trunc(12.75) = 12
Int(12.75) = 12
Frac(12.75) = 0.75


Page 187 of 366

131. Integer - The basic Integer type
131.1. Unit
System
131.2. Type
Type
131.3. Description
The Integer type is an Integer whose size is not guaranteed. It is the basic integer type in
Iris, and currently has the same capacity as the LongInt type - 1 bit sign, and 31 bits value.
131.4. Syntax
type Integer = -2147483648..2147483647;
131.5. Example
131.5.1. Name
Showing the capacity of Integer
131.5.2. Code
var
A, B : Integer;
begin
A := -2147483648;
B := 2147483647;
end;

131.5.3. Result
A = -2147483648 and B = 2147483647
A + B = -1


Page 188 of 366

132. Interface - Used for definitions
132.1. Unit
System
132.2. Type
Keyword
132.3. Description
The interface keyword starts the definition of interface of a Script Page. All interface
declarations must be implemented in the implementation section. The uses statement, if
present, must be at the start.
132.4. Syntax
unit Name;
interface
Declarations...
implementation
Declarations...
end.


Page 189 of 366

132.5. Example
132.5.1. Name
A simple example
132.5.2. Code
// -----------------------------------------------------------
// -----------------------------------------------------------



end;




{$r *.dfm}

loaded
var
UserName string;
begin
repeat



Page 190 of 366

length
characters?');
ShowDifference;
end;

begin
end;

begin
end;

begin
from this page
end;

begin
end;

end.
132.5.3. Result

It is now 12:34:56




Page 191 of 366

133. IntToHex - Convert an Integer into a hexadecimal
string
133.1. Unit
SysUtils
133.2. Type
Function
133.3. Description
The IntToHex function converts a DecimalValue integer into a hexadecimal format sting of at
least MinimumWidth characters wide. The resulting string has no prefix character.
133.4. Syntax
function IntToHex(DecimalValue : Integer; MinimumWidth : Integer) : string;
133.5. Example
133.5.1. Name
Convert an integer to a hex format
133.5.2. Code
begin
// display 123 decimal in hex with minimal width
ShowMessage('1234 decimal = '+IntToHex(1234, 1));

// display 123 decimal in hex with fixed width
ShowMessage('1234 decimal = '+IntToHex(1234, 8));
end;
133.5.3. Result
1234 decimal = 4D2
1234 decimal = 000004D2


Page 192 of 366

134. IntToStr - Convert an integer into a string
134.1. Unit
SysUtils
134.2. Type
Function
134.3. Description
The IntToStr function converts an Integer Number into a string. It is normally used for
display purposes.
134.4. Syntax
function IntToStr(Number : Integer) : string;
134.5. Example
134.5.1. Name
Converting integers to strings
134.5.2. Code
var
value : Integer;

begin
value := 2147483647; // largest possible integer value
ShowMessage('value : '+IntToStr(value));
end;
134.5.3. Result
value : 2147483647


Page 193 of 366

135. IsInfinite - Checks whether a floating point number
is infinite
135.1. Unit
Math
135.2. Type
Function
135.3. Description
The IsInfinite function returns True if FloatNumber is infinite in value.
135.4. Syntax
function IsInfinite(const FloatNumber : Double) : Boolean;
135.5. Example
135.5.1. Name
Assign Infinity to a number and then test using IsInfinite
135.5.2. Code
var
float : Double;

begin
// set the number to infinity
float := Infinity; // equivalent to 1.0/0.0

// although infinite, we can still display it
ShowMessage('float = '+FloatToStr(float));

// and we can test to see if it is infinite
if IsInfinite(float)
then ShowMessage('float is infinite')
else ShowMessage('float = '+FloatToStr(float));
end;
135.5.3. Result
float = INF
float is infinite


Page 194 of 366

136. IsLeapYear - Returns true if a given calendar year is
a leap year
136.1. Unit
SysUtils
136.2. Type
Function
136.3. Description
The IsLeapYear function returns true if a given calendar value is a leap year. Year can have a
value 0..9999
136.4. Syntax
function IsLeapYear(const Year : Word) : Boolean;
136.5. Example
136.5.1. Name
Was the year 2000 a leap year?
136.5.2. Code
begin
if IsLeapYear(2000)
then ShowMessage('2000 was a leap year')
else ShowMessage('2000 was not a leap year');
end;
136.5.3. Result
2000 was a leap year


Page 195 of 366

137. LastDelimiter - Find the last position of selected
characters in a string
137.1. Unit
SysUtils
137.2. Type
Function
137.3. Description
The LastDelimiter function finds the last occurrence of any of a set of Delimiter characters in
a Source string. if found, the position is returned. Otherwise, 0 is returned.
137.4. Syntax
function LastDelimiter(const Delimiters, Source : string) : Integer;
137.5. Example
137.5.1. Name
Find the last position of 1 or more characters in a string
137.5.2. Code
var
source, find : string;
position : Integer;

begin
// create a string
source := '12345678901234567890';

// find the position of the last 1
position := LastDelimiter('1', source);
ShowMessage('The last 1 is at '+IntToStr(position));

// find the position of the last 2, 4 or 6
position := LastDelimiter('246', source);
ShowMessage('The last 2, 4 or 6 is at '+IntToStr(position));
end;
137.5.3. Result
The last 1 is at 11
The last 2, 4 or 6 is at 16


Page 196 of 366

138. Length - Return the number of elements in an array
or string
138.1. Unit
System
138.2. Type
Function
138.3. Description
The Length function returns the number of characters in a string. It is often used to loop
around all characters in a string or elements in an array.
138.4. Syntax
function Length(const SourceString : string) : Integer;
138.5. Example
138.5.1. Name
Get the length of a string
138.5.2. Code
var
shortStr : shortstring;
longStr : string;
i : Integer;
begin
shortStr := 'ABCDEFGH';
longStr := '12345678901234567890';
ShowMessage('Length of shortStr = '+IntToStr(Length(shortStr)));
ShowMessage('Length of longStr = '+IntToStr(Length(longStr)));

// display one letter at a time from the short string
for i := 1 to Length(shortStr) do
ShowMessage('Letter '+IntToStr(i)+' = '+shortStr[i]);
end;
138.5.3. Result
Length of shortStr = 8
Length of longStr = 20
Letter 1 = A
Letter 2 = B
Letter 3 = C
Letter 4 = D
Letter 5 = E
Letter 6 = F
Letter 7 = G
Letter 8 = H


Page 197 of 366

139. LinkedPopup - Open a Linked Popup
139.1. Unit
Iris Standard
139.2. Type
Frame Function
139.3. Description
Open a popup screen that is linked by a PowerTree
139.4. Syntax
procedure LinkedPopup(Sender: TObject; PageName: string);
139.5. Example
139.5.1. Name
Open the popup 'PopupName' with the PowerTree 'Sender'
139.5.2. Code
begin

LinkedPopup('Sender','PopupName');
end;
139.5.3. Result
No result specified


Page 198 of 366

140. Ln - Gives the natural logarithm of a number
140.1. Unit
System
140.2. Type
Function
140.3. Description
The Ln function takes an integer or floating point Number and gives the natural logarithm of
that number. This is only used for mathematical processing. Ln has the opposite effect to Exp
- the exponent of a number. (2.72 raised to that number power).
140.4. Syntax
function Ln(Number : Extended) : Extended;
140.5. Example
140.5.1. Name
Calculate the exponent of 2 and the natural log of the result
140.5.2. Code
var
float : Double;
begin
// get the natural logarithm of 2
float := Ln(2);

// show this value
ShowMessage('Ln(2) = '+FloatToStr(float));

// get the exponent of this value - reverses the ln operation
float := Exp(float);

// show this value
ShowMessage('Exp(Ln(2)) = '+FloatToStr(float));
end;
140.5.3. Result
Ln(2) = 0.693147180559945
Exp(Ln(2)) = 2


Page 199 of 366

141. Log10 - Gives the log to base 10 of a number
141.1. Unit
Math
141.2. Type
Function
141.3. Description
The Log10 function returns the logarithm to base 10 of Number.
141.4. Syntax
function Log10(const Number : Extended) : Extended;
141.5. Example
141.5.1. Name
Show the logarithm of a set of numbers
141.5.2. Code
begin
// show the log to base 10 values of 3 numbers
ShowMessage('Log10(1) = '+FloatToStr(Log10(1)));
end;
141.5.3. Result
Log10(1) = 0
Log10(5) = 0.698970004336019
Log10(10) = 1


Page 200 of 366

142. LongDateFormat - Long version of the date to string
format
142.1. Unit
SysUtils
142.2. Type
Variable
142.3. Description
The LongDateFormat variable provides the long (extended) formatting used for certain date
to string conversions. It is used by the DateTimeToString routine when the 'dddddd'
formatting is used. The following formatting character strings can be used in the
LongDateFormat string: y = Year last 2 digitsyy = Year last 2 digitsyyyy = Year as 4 digitsm
= Month number no-leading 0mm = Month number as 2 digitsmmm = Month using
ShortDayNames (Jan)mmmm = Month using LongDayNames (January)d = Day number no-
leading 0dd = Day number as 2 digitsddd = Day using ShortDayNames (Sun)dddd = Day
using LongDayNames (Sunday)
142.4. Syntax
var LongDateFormat : string;
142.5. Example
142.5.1. Name
Illustrating customised LongDateFormat setting
142.5.2. Code
var
myDate : TDateTime;
formattedDate : string;

begin

// display using the default longdateformat
DateTimeToString(formattedDate, 'dddddd', myDate);
ShowMessage('29/02/2000 using default = '+formattedDate);

// change the display formatting
LongDateFormat := 'dddd dd of mmmm yyyy';
DateTimeToString(formattedDate, 'dddddd', myDate);
ShowMessage('29/02/2000 using override = '+formattedDate);
end;
142.5.3. Result
29/02/2000 using default = 29 February 2000
29/02/2000 using override = Tuesday 29 of February 2000


Page 201 of 366

143. LongInt - An Integer whose size is guaranteed to be
32 bits
143.1. Unit
System
143.2. Type
Type
143.3. Description
The LongInt type is a 32 bit signed Integer. This size is fixed, and will not change in future
releases of Iris. It is currently the same size as the Integer type.
143.4. Syntax
type LongInt = -2147483648..2147483647;
143.5. Example
143.5.1. Name
Showing the capacity of LongInt
143.5.2. Code
var
A, B : LongInt;
begin
A := -2147483648;
B := 2147483647;
end;

143.5.3. Result
A = -2147483648 and B = 2147483647
A + B = -1


Page 202 of 366

144. LongTimeFormat - Long version of the time to string
format
144.1. Unit
SysUtils
144.2. Type
Variable
144.3. Description
The LongTimeFormat variable provides the long (extended) formatting used for certain time
to string conversions. It is used by the DateTimeToString routine when the 'tt' formatting is
used. The following formatting character strings can be used in the LongTimeFormat string: h
= Hour with no leading 0'shh = Hour as 2 digitsn = Minute with no leading 0'snn = Minute as
2 digitss = Seconds with no leading 0'sss = Seconds as 2 digitsz = Milli-seconds with no
leading 0'szzz = Milli-seconds as 3 digits
144.4. Syntax
var LongTimeFormat : string;
144.5. Example
144.5.1. Name
Illustrating customised LongTimeFormat setting
144.5.2. Code
var
myDate : TDateTime;

begin
myDate := StrToTime('15:06:23.456');

// display using the default longtimeformat
DateTimeToString(formattedDate, 'tt', myDate);
ShowMessage('15:06:23.456 using default = '+formattedDate);

LongTimeFormat := 'hh nn ss (zzz)';
DateTimeToString(formattedDate, 'tt', myDate);
ShowMessage('15:06:23.456 using override = '+formattedDate);
end;
144.5.3. Result
15:06:23.456 using default = 15:06:23
15:06:23.456 using override = 15 06 23 (456)


Page 203 of 366

145. LowerCase - Change upper case characters in a
string to lower case
145.1. Unit
SysUtils
145.2. Type
Function
145.3. Description
The LowerCase function creates a copy of MixedString with all letters converted to lower
case.
145.4. Syntax
function LowerCase(const MixedString : string) : string;
145.5. Example
145.5.1. Name
Converting a mixed case string to lower case
145.5.2. Code
var

begin
SimpleString := LowerCase('The Cat Sat on The MAT');
end;
145.5.3. Result
SimpleString : the cat sat on the mat


Page 204 of 366

146. Max - Gives the maximum of two integer values
146.1. Unit
Math
146.2. Type
Function
146.3. Description
The Max function returns the value of higher of two numeric arguments, A and B. These
arguments may be any of the given numeric types, in any mixture. The result will be
normalised to the appropriate value - floating point if either argument is floating point.
146.4. Syntax
function Max(const A, B : Integer|Int64|Single|Double|Extended) :
Integer|Int64|Single|Double|Extended;
146.5. Example
146.5.1. Name
Illustrate integer use of Max
146.5.2. Code
var
int1, int2, int3 : Integer;
begin
int1 := 37;
int2 := 38;
int3 := Max(int1, int2);

ShowMessage('int1 = '+IntToStr(int1));
ShowMessage('Max(int1, int2) = '+IntToStr(int3));
end;
146.5.3. Result
int1 = 37
int2 = 38
Max(int1, int2) = 38


Page 205 of 366

147. MessageBox - Displays a message, symbol, and
selectable buttons
147.1. Unit
Dialogs
147.2. Type
Function
147.3. Description
The function shows a MessageBox Dialog which waits for user input. The following Icon
Options are available: mb_IconWarning mb_IconStop mb_IconExclamation
mb_IconInformation mb_IconQuestion
147.4. Syntax
function MessageBox(hWnd: HWND; lpText, lpCaption: string; uType: UINT): Integer;
147.5. Example
147.5.1. Name
Display a confirmation dialog
147.5.2. Code
var
buttonSelected : Integer;
begin
// show a confirmation dialog
buttonSelected := MessageBox(Handle,'Are you sure?','Confirmation',mb_IconStop or
mb_YesNo or Mb_TaskModal);

// show the button type selected
if buttonSelected = idYes then ShowMessage('YES pressed');
if buttonSelected = idNo then ShowMessage('NO pressed');
end;
147.5.3. Result
A confirmation dialog is displayed with YES and NO buttons.
The user presses YES :
YES pressed
is displayed in another dialog box.

The user presses NO :
NO pressed


Page 206 of 366

148. MessageDlg - Displays a message, symbol, and
selectable buttons
148.1. Unit
Dialogs
148.2. Type
Function
148.3. Description
The MessageDlg function is used to display messages to the user. These messages may be
informational, or warnings or whatever. There is complete freedom over the choice of buttons
that the user may press to acknowledge the dialog. for example, the user may be shown an
error message, and be allowed to abort, retry or cancel the erroneous process. The
DialogType may have one of the following enumerated values: mtWarning Displays a
exclamation symbolmtError Displays a red 'X'mtInformation Displays an 'i' in a
bubblemtConfirmation Displays an question markmtCustom Displays just the message The
Buttons value may be one or more of the following enumerated values : mbYes Displays a
'Yes' buttonmbNo Displays a 'No' buttonmbOK Displays an 'OK' buttonmbCancel Displays a
'Cancel' buttonmbAbort Displays an 'Abort' buttonmbRetry Displays a 'Retry' buttonmbIgnore
Displays an 'Ignore' buttonmbAll Displays an 'All' buttonmbNoToAll Displays a 'No to all'
buttonmbYesToAll Displys a 'Yes to all' buttonmbHelp Displays a 'Help' button You specify
these values comma separated in square brackets, as in the second code example. Iris
provides a number of predefined button combinations: mbYesNoCancel =
[mbYes,mbNO,mbCancel]mbYesAllNoAllCancel =[mbYes,mbYesToAll,
mbNo,mbNoToAll,mbCancel]mbOKCancel =[mbOK,mbCancel]mbAbortRetryCancel
=[mbAbort,mbRetry,mbCancel]mbAbortIgnore =[mbAbort,mbIgnore] Now Iris seem to have
made a design error when setting the return value from the dialog box. Instead of specifying
the enumeration value of the button pressed, it uses a completely different set of
enumeration names: mrYes = 6mrNo = 7mrOK = 1mrCancel = 2mrAbort = 3mrRetry =
4mrIgnore = 5mrAll = 8mrNoToAll = 9mrYesToAll = 10 The values given are the numerical
values of these enumerations, given in the numerical order that the mb equivalents are
defined. This is very odd. Additionally, these values are defined in the Controls unit, not the
Dialogs unit. Note that the Help button has no equivalent return value. This is because it does
not terminate the dialog. The HelpContext value is used in conjunction with the Help button.
It's use is beyond the scope of Iris Basics.
148.4. Syntax
function MessageDlg(const message : string; DialogType : TMsgDlgType; Buttons :
TMsgDlgButtons; HelpContext : Longint) : Integer;


Page 207 of 366

148.5. Example 1
148.5.1. Name
148.5.2. Code
var
begin
// show a confirmation dialog
buttonSelected := MessageDlg('Confirmation',mtError, mbOKCancel, 0);

if buttonSelected = mrOK then ShowMessage('OK pressed');
if buttonSelected = mrCancel then ShowMessage('Cancel pressed');
end;
148.5.3. Result
A confirmation dialog is displayed with OK and Cancel buttons.
The user presses OK :

OK pressed

148.6. Example 2
148.6.1. Name
Displays a custom dialog with custom button selection
148.6.2. Code
var
begin
// show a custom dialog
buttonSelected := MessageDlg('Custom dialog',mtCustom,mbAll, 0);

if buttonSelected = mrYes then ShowMessage('Yes pressed');
if buttonSelected = mrNo then ShowMessage('No pressed');
end;
148.6.3. Result
A dialog with no icon is displayed with Yes, No and OK buttons.
The user presses the Yes button :

Yes pressed

is shown in another dialog


Page 208 of 366

149. MessageDlgPos - Displays a message plus buttons at
a given screen position
149.1. Unit
Dialogs
149.2. Type
Function
149.3. Description
The MessageDlgPos function is used to display messages to the user at a given screen
position. These messages may be informational, or warnings or whatever. There is complete
freedom over the choice of buttons that the user may press to acknowledge the dialog. for
example, the user may be shown an error message, and be allowed to abort, retry or cancel
the erroneous process. The screen coordinates are given by the X and Y values. The
DialogType may have one of the following enumerated values: mtWarning Displays a
exclamation markmtError Displays a red 'X'mtInformation Displays an 'i' in a
bubblemtConfirmation Displays an question markmtCustom Displays just the message The
Buttons value may be one or more of the following enumerated values : mbYes Displays a
'Yes' buttonmbNo Displays a 'No' buttonmbOK Displays an 'OK' buttonmbCancel Displays a
'Cancel' buttonmbAbort Displays an 'Abort' buttonmbRetry Displays a 'Retry' buttonmbIgnore
Displays an 'Ignore' buttonmbAll Displays an 'All' buttonmbNoToAll Displays a 'No to all'
buttonmbYesToAll Displys a 'Yes to all' buttonmbHelp Displays a 'Help' button You specify
these values comma separated in square brackets, as in the second code example. Iris
provides a number of predefined button combinations: mbYesNoCancel =
[mbYes,mbNO,mbCancel]mbYesAllNoAllCancel =[mbYes,mbYesToAll,
mbNo,mbNoToAll,mbCancel]mbOKCancel =[mbOK,mbCancel]mbAbortRetryCancel
=[mbAbort,mbRetry,mbCancel]mbAbortIgnore =[mbAbort,mbIgnore] Now Iris seem to have
made a design error when setting the return value from the dialog box. Instead of specifying
the enumeration value of the button pressed, it uses a completely different set of
enumeration names: mrYes = 6mrNo = 7mrOK = 1mrCancel = 2mrAbort = 3mrRetry =
4mrIgnore = 5mrAll = 8mrNoToAll = 9mrYesToAll = 10 The values given are the numerical
values of these enumerations, given in the numerical order that the mb equivalents are
defined. This is very odd. Additionally, these values are defined in the Controls unit, not the
Dialogs unit. Note that the Help button has no equivalent return value. This is because it does
not terminate the dialog. The HelpContext value is used in conjunction with the Help button.
It's use is beyond the scope of Iris Basics.
149.4. Syntax
function MessageDlgPos(const message : string; DialogType : TMsgDlgType; Buttons :
TMsgDlgButtons; HelpContext : Longint; X, Y : Integer) : Integer;


Page 209 of 366

149.5. Example 1
149.5.1. Name
149.5.2. Code
var
begin
// show a confirmation dialog at 20,100
buttonSelected := MessageDlgPos('Confirmation',mtError, mbOKCancel, 0, 20, 100);

if buttonSelected = mrCancel then ShowMessage('Cancel pressed');
end;
149.5.3. Result
A confirmation dialog is displayed with OK and Cancel buttons at 20,100 coordinates.
The user presses OK :

OK pressed

149.6. Example 2
149.6.1. Name
Displays a custom dialog with custom button selection
149.6.2. Code
var
begin
// show a custom dialog at 20,100 coordinates
buttonSelected := MessageDlgPos('Custom dialog',mtCustom,mbAll, 0, 20, 100);

if buttonSelected = mrYes then ShowMessage('Yes pressed');
if buttonSelected = mrNo then ShowMessage('No pressed');
end;
149.6.3. Result
A dialog with no icon is displayed with Yes, No and Ok buttons at 20,100 coordinates.
The user presses the Yes button :

Yes pressed

is shown in another dialog


Page 210 of 366

150. Min - Gives the minimum of two integer values
150.1. Unit
Math
150.2. Type
Function
150.3. Description
The Min function returns the value of lower of two numeric arguments, A and B. These
arguments may be any of the given numeric types, in any mixture. The result will be
normalised to the appropriate value - floating point if either argument is floating point.
150.4. Syntax
function Min(const A, B : Integer|Int64|Single|Double|Extended) :
Integer|Int64|Single|Double|Extended;
150.5. Example
150.5.1. Name
Illustrate integer use of Min
150.5.2. Code
var
int1, int2, int3 : Integer;
begin
int1 := 37;
int2 := 38;
int3 := Min(int1, int2);

ShowMessage('Min(int1, int2) = '+IntToStr(int3));
end;
150.5.3. Result
int1 = 37
int2 = 38
Min(int1, int2) = 37


Page 211 of 366

151. MinsPerDay - Gives the number of minutes in a day
151.1. Unit
SysUtils
151.2. Type
Constant
151.3. Description
The MinsPerDay constant gives the number of minutes in a day (24 * 60 = 1440).
151.4. Syntax
const MinsPerDay = 1440;
151.5. Example
151.5.1. Name
Show the number of minutes and seconds in a week
151.5.2. Code
begin
ShowMessage('Number of minutes in a week = '+IntToStr(MinsPerDay*7));
ShowMessage('Number of seconds in a week = '+IntToStr(SecsPerDay*7));
end;
151.5.3. Result
Number of minutes in a week = 10080
Number of seconds in a week = 604800


Page 212 of 366

152. MkDir - Make a directory
152.1. Unit
System
152.2. Type
Procedure
152.3. Description
The MkDir procedure makes a new directory in the current directory. if the directory already
exists, an EInOutError exception is thrown. You must then check the IOResult value to see
the outcome of your IO operation (remembering that use of IOResult resets the value).
152.4. Syntax
procedure MkDir(const DirectoryName : string);
152.5. Example
152.5.1. Name
Create a directory and then remove it
152.5.2. Code
var
error : Integer;

begin
// try to create a new subdirectory in the current directory
MkDir('TempDirectory');

// did the directory get created ok?
error := IOResult;
if error = 0
then ShowMessage('Directory created OK')
else ShowMessageFmt('Directory creation failed with error %d',[error]);

// delete the directory to tidy up
RmDir('TempDirectory');

end;
152.5.3. Result
Directory created OK


Page 213 of 366

153. Mod - Performs integer division, returning the
remainder
153.1. Unit
Iris Standard
153.2. Type
Keyword
153.3. Description
The mod keyword gives the remainder from dividing the Dividend by the Divisor. The whole
number result of the division is ignored.
153.4. Syntax
Dividend mod Divisor
153.5. Example
153.5.1. Name
A simple example
153.5.2. Code
var
int : Integer;

begin
// divide a primary integer by 4 - mod returns the remainder
int := 19 mod 4;

ShowMessage('19 mod 4 = '+IntToStr(int));
end;
153.5.3. Result
19 mod 4 = 3


Page 214 of 366

154. ModalPopup - Open a Modal Popup
154.1. Unit
Iris Standard
154.2. Type
Frame Function
154.3. Description
Open a popup screen that is always on top. It is only possible to access the popup. Other
screens can only be accessed when the popup is closed.
154.4. Syntax
procedure ModalPopup(PageName: string);
154.5. Example
154.5.1. Name
Open the popup 'PopupName' and make it always on top
154.5.2. Code
begin

ModalPopup('PopupName');
end;
154.5.3. Result
No result specified


Page 215 of 366

155. MonthOfTheYear - Gives the month of the year for a
TDateTime value
155.1. Unit
DateUtils
155.2. Type
Function
155.3. Description
The MonthOfTheYear function returns an index number for the month of the year. The value
is in the range 1 for January to 12 for December.
155.4. Syntax
function MonthOfTheYear(const Date : TDateTime) : Word;
155.5. Example
155.5.1. Name
Show the month of the year for a TDateTime variable
155.5.2. Code
var
myDate : TDateTime;

begin
ShowMessage('The month of the year = '+
IntToStr(MonthOfTheYear(myDate)));
end;
155.5.3. Result
The month of the year = 10


Page 216 of 366

156. NegCurrFormat - Defines negative amount
formatting in currency displays
156.1. Unit
SysUtils
156.2. Type
Variable
156.3. Description
The NegCurrFormat variable defines how negative currency amounts are formatted by such
functions as FloatToStr and CurrToStr. It is in effect an enumerated type, but with no names
for the values. It is easiest to show their meanings by example, given below with an amount
1.23 and ? as the CurrencyString: ?0 = (?1.23)?1 = -?1.23?2 = ?-1.23?3 = ?1.23-?4 =
(1.23?)?5 = -1.23??6 = 1.23-??7 = 1.23?-?8 = -1.23 ??9 = -? 1.2310 = 1.23 ?-11 = ? 1.23-
12 = ? -1.2313 = 1.23- ?14 = (? 1.23)15 = (1.23 ?)
156.4. Syntax
var NegCurrFormat : Byte;


Page 217 of 366

156.5. Example
156.5.1. Name
Illustrate the 16 different negative formatting flavours
156.5.2. Code
var
i : Byte;

begin
// display the amount using all the flavours of negcurrformat
for i := 0 to 15 do
begin
NegCurrFormat := i;
ShowMessage('Format '+IntToStr(i)+' = '+Format('%m', [-1.23]));
end;
end;
156.5.3. Result
Format 0 = (?1.23)
Format 1 = -?1.23
Format 2 = ?-1.23
Format 3 = ?1.23-
Format 4 = (1.23?)
Format 5 = -1.23?
Format 6 = 1.23-?
Format 7 = 1.23?-
Format 8 = -1.23 ?
Format 9 = -? 1.23
Format 10 = 1.23 ?-
Format 11 = ? 1.23-
Format 12 = ? -1.23
Format 13 = 1.23- ?
Format 14 = (? 1.23)
Format 15 = (1.23 ?)


Page 218 of 366

157. Not - Boolean not or bitwise not of one arguments
157.1. Unit
Iris Standard
157.2. Type
Keyword
157.3. Description
The not keyword is used in two different ways: 1. to perform a logical or Boolean 'not' of a
logical value. If True, the value becomes False. if False, the value becomes True. 2. to
perform a mathematical 'not' of an integer in a bitwise fashion. The result is a bitwise 'not' of
the number - every bit value is reversed - 0 to 1 and 1 to 0.
157.4. Syntax
1 not Boolean expression
2 not Integer expression
157.5. Example
157.5.1. Name
Illustrate both types of not usage
157.5.2. Code
var
num1, num2 : Word;

begin
num1 := $2C; // binary value : 0000 0000 0000 0000 0000 0000 0010 1100
// not-ed value : 1111 1111 1111 1111 1111 1111 1101 0011 =
$ffffffd3

if not (num1 > 0)
then ShowMessage('num1 <= 0')
else ShowMessage('num1 > 0');

// and used to perform a mathematical not operation
num2 := not num1;

// display the result
ShowMessage('not $2C = $'+IntToHex(num2,2));
end;
157.5.3. Result
num1 > 0
not $2C = $FFFFFFD3


Page 219 of 366

158. Now - Gives the current date and time
158.1. Unit
SysUtils
158.2. Type
Function
158.3. Description
The Now function returns the current date and time in the local time zone. The returned
TDateTime type can be manipulated and displayed by many SysUtil and DateUtils routines.
158.4. Syntax
function Now : TDateTime;
158.5. Example
158.5.1. Name
Show the current date and time
158.5.2. Code
var
today : TDateTime;
begin
today := Now;
ShowMessage('today has date = '+DateToStr(today));
ShowMessage('today has time = '+TimeToStr(today));
end;
158.5.3. Result
today has date = 12/10/2002
today has time = 13:37:25


Page 220 of 366

159. Null - A variable that has no value
159.1. Unit
Variants
159.2. Type
Variable
159.3. Description
The Null variable has an undefined value. Null does not mean a zero number or empty string
- it is undefined. Any expression using a null variable will yield a null result. Null is particularly
useful when handling SQL table data - providing a one for one correspondence with the SQL
NULL value.
159.4. Syntax
var Null : Variant;


Page 221 of 366

159.5. Example
159.5.1. Name
Using Null to represent the result of a bad divide
159.5.2. Code
/ Remember to declare the function at type using the following line
// function divide(dividend, divisor: integer) : variant;

var
Answer : Variant;

begin
Answer := Divide(4,2);

// show the result of this division
if Answer = Null
then ShowMessage('4 / 2 = Invalid')
else ShowMessage('4 / 2 = '+IntToStr(Answer));

Answer := Divide(4,0);

// show the result of this division
if Answer = Null
then ShowMessage('4 / 0 = Invalid')
else ShowMessage('4 / 0 = '+IntToStr(Answer));

end;

function TUntitled.Divide(Dividend, Divisor: Integer) : Variant;
begin
// try to divide the dividend by the divisor
try
Result := Dividend div Divisor;
except
Result := Null ; // assign null if the division threw an error
end;
end;
159.5.3. Result
4 / 2 = 2
4 / 0 = Invalid


Page 222 of 366

160. NumEditor - Shows a numerical popup to write the
value of a tag
160.1. Unit
Iris Standard
160.2. Type
Tag Function
160.3. Description
Writes a value to a tag using a NumEditor Popup. Writes regardless of the current value of
the tag. It is possible to read values from device and internal tags.
160.4. Syntax
procedure NumEditor(ScreenControl: TObject; TagName: string);
160.5. Example 1
160.5.1. Name
read/write a tag value using a NumEditor
160.5.2. Code
var
value: integer;
begin
NumEditor(Sender,'tagname');
end;
160.5.3. Result
The old value is ?
The new value is ?


Page 223 of 366

160.6. Example 2
160.6.1. Name
read/write a tag value using a NumEditor through a PowerTree
160.6.2. Code
var
value: integer;
begin
NumEditor(Sender,ExpandMailbox('[PowerTree].name'));
end;
160.6.3. Result
The old value is ?
The new value is ?
160.7. Example 3
160.7.1. Name
read/write a structured tag value using a NumEditor
160.7.2. Code
var
value: integer;
begin
// write a new value to the tag 'unit1.equipmentmodule2'
NumEditor(Sender,'Unit1.EquipmentModule2');
end;
160.7.3. Result
The old value is ?
The new value is ?


Page 224 of 366

161. Or - Boolean or or bitwise or of two arguments
161.1. Unit
Iris Standard
161.2. Type
Keyword
161.3. Description
The or keyword is used in two different ways: 1. to perform a logical or Boolean 'or' of two
logical values. if either are true, then the result is true, otherwise it is false. 2. to perform a
mathematical 'or' of two integers. The result is a bitwise 'or' of the two numbers. for
example: 10110001 or 01100110 = 11110111
161.4. Syntax
1 Boolean expression or Boolean expression
2 Integer expression or Integer expression
161.5. Example
161.5.1. Name
Illustrate both types of or usage
161.5.2. Code
var
letter : Char;

begin
num1 := $25; // binary value : 0010 0101 $25
num2 := $32; // binary value : 0011 0010 $32
// or'ed value : 0011 0111 = $37
letter := 'G';

if (num1 > 0) or (letter = 'G')
then ShowMessage('At least one value is true')
else ShowMessage('Both values are false');

// and used to perform a mathematical or operation
num3 := num1 or num2;

ShowMessageFmt('$25 or $32 = $%x',[num3]);
end;
161.5.3. Result
At least one value is true
$25 or $32 = $37


Page 225 of 366

162. Ord - Provides the Ordinal value of an integer,
character or enum
162.1. Unit
System
162.2. Type
Function
162.3. Description
The Ord function returns an integer value for any ordinal type Arg. It is principally used to
convert characters or enumerations into their numeric equivalents.
162.4. Syntax
function Ord(Arg : AnsiChar | Char | WideChar | Enumeration | Integer) : Integer;


Page 226 of 366

162.5. Example
162.5.1. Name
Illustrate all Ord types
162.5.2. Code
var
A : AnsiChar;
C : Char;
W : WideChar;
E : Boolean;
I : Integer;
I64 : Int64;

begin
// set the ordinal type values
A := 'A';
C := 'C';
W := 'W';
E := True;
I := 22;
I64 := 64;

// and show the value of each
ShowMessage('A = '+IntToStr(Ord(A)));
ShowMessage('C = '+IntToStr(Ord(C)));
ShowMessage('W = '+IntToStr(Ord(W)));
ShowMessage('E = '+IntToStr(Ord(E)));
ShowMessage('I = '+IntToStr(Ord(I)));
ShowMessage('I64 = '+IntToStr(Ord(I64)));
end;
162.5.3. Result
A = 65
C = 67
W = 87
E = 1
I = 22
I64 = 64


Page 227 of 366

163. PageBack - Show Previous Page
163.1. Unit
Iris Standard
163.2. Type
Frame Function
163.3. Description
Opens the previous screen, just like in a browser
163.4. Syntax
procedure PageBack;
163.5. Example
163.5.1. Name
Open previously opened screen (browser page back)
163.5.2. Code
begin
PageBack;
end;
163.5.3. Result
The previous screen is opened (if any)


Page 228 of 366

164. PageForward - Show Next Page
164.1. Unit
Iris Standard
164.2. Type
Frame Function
164.3. Description
Opens a the next screen, just like in a browser
164.4. Syntax
procedure PageForward;
164.5. Example
164.5.1. Name
Open next opened screen (browser page forward)
164.5.2. Code
begin
PageForward;
end;
164.5.3. Result
The next screen is opened (if any)


Page 229 of 366

165. Pi - The mathematical constant
165.1. Unit
System
165.2. Type
Function
165.3. Description
The Pi function returns a floating point value giving a useful approximation of the value of Pi.
The circumference of a circle Pi * Diameter.
165.4. Syntax
function Pi : Extended;
165.5. Example
165.5.1. Name
Get the area and circumference of a circle
165.5.2. Code
var
myPi : Extended;
diam : Integer;
begin
diam := 10;

// show circumference and the area of a circle
// with diameter - 10 cm
ShowMessage(' Diameter = '+IntToStr(diam));
ShowMessage('Circumference = '+FloatToStr(Pi*diam));
ShowMessage(' Area = '+FloatToStr(Pi*(diam/2)*(diam/2)));
end;
165.5.3. Result
Diameter = 10
Circumference = 31.4159265358979
Area = 78.5398163397448


Page 230 of 366

166. Popup - Open a Popup
166.1. Unit
Iris Standard
166.2. Type
Frame Function
166.3. Description
Open a popup screen
166.4. Syntax
procedure Popup(PageName: string);
166.5. Example
166.5.1. Name
Open the popup 'PopupName'
166.5.2. Code
begin

Popup('PopupName');
end;
166.5.3. Result
No result specified


Page 231 of 366

167. Pos - Find the position of one string in another
167.1. Unit
SysUtils
167.2. Type
Function
167.3. Description
The Pos function looks for a substring Needle in a string HayStack, returning the position in
the string of the first occurrence. if the string is not found, 0 is returned. The search is case
sensitive.
167.4. Syntax
function Pos(const Needle, HayStack : string) : Integer;
167.5. Example
167.5.1. Name
Find a word in a sentence
167.5.2. Code
var
position : Integer;

begin
// look for the word 'cat' in a sentence
// note : that this search is case sensitive, so that
// the first 'cat' is not matched
position := Pos('Cat', 'The cat sat on the Cat mat');
if position = 0
then ShowMessage('''Cat'' not found in the sentence')
else ShowMessage('''Cat'' was found at character '+IntToStr(position));
end;
167.5.3. Result
'Cat' was found at character 20


Page 232 of 366

168. Pred - Decrement an ordinal variable
168.1. Unit
System
168.2. Type
Function
168.3. Description
The Pred function decrements an ordinal value and returns this value. You can decrement:
Characters Non-floating number types Enumeration types Pointers The decrement is by the
base size of the unit. for example, decrementing a Pointer will be by 2 bytes if the pointer
points to Words.
168.4. Syntax
function Pred(const Ordinal Value) : Ordinal type;
168.5. Example
168.5.1. Name
Decrementing characters, numbers and enumerations
168.5.2. Code
var
Number : Integer;

begin
Number := 23;

Number := Pred(Number);
end;
168.5.3. Result
Number : 23
Number-1 : 22


Page 233 of 366

169. Private - Starts the section of private data and
methods in a class
169.1. Unit
Iris Standard
169.2. Type
Directive
169.3. Description
Note: Currently there is no difference in Iris between private and public! The private directive
starts the section of data (fields) and routines (methods) of a class that are private (internal)
to that class. It is a vital part of the object Oriented concept that a class be treated like a
black box - how it operates internally is not relevant to the external use. This is where the
private section comes in - it hides data and routines used solely by other routines in the class.
if private data needs to be accessed externally, a public (or published) property or routine is
provided to give this access. private data and routines are not even accessible by a
descendent class - you must use protected to provide this access. protected data and
methods are externally invisible, but are accessible to all classes in a hierarchy.
169.4. Syntax
private
public
end;


Page 234 of 366

170. Procedure - Defines a subroutine that does not
return a value
170.1. Unit
System
170.2. Type
Keyword
170.3. Description
The procedure keyword defines a subroutine that does not return a value. See the
SubRoutines tutorial for details on using procedures. Version 1 - Defines a procedure that
operates with no parameters. Version 2 -Defines a procedure that is passed one or more
parameters.
170.4. Syntax
1 procedure Name; {directives;}
2 procedure Name(Parameters); {directives;}
170.5. Example
170.5.1. Name
A simple example
170.5.2. Code
// -----------------------------------------------------------
// -----------------------------------------------------------


end;




Page 235 of 366


{$r *.dfm}
loaded
var
UserName string;
begin
repeat

length
characters?');
ShowDifference;
end;

begin
end;

begin
end;

begin
from this page
end;

begin
end;

end.


Page 236 of 366

170.5.3. Result

It is now 12:34:56




Page 237 of 366

171. PtInRect - Tests to see if a point lies within a
rectangle
171.1. Unit
Types
171.2. Type
Function
171.3. Description
The PtInRect function returns true if ThePoint lies within TheRectangle. Note that the
rectangle inside is defined as: (left, top, right-1, bottom-1)
171.4. Syntax
function PtInRect(const TheRectangle : TRect; const ThePoint : TPoint) : Boolean;
171.5. Example
171.5.1. Name
Determine inside and outside points of a rectangle
171.5.2. Code
var
myRect : TRect;

begin
// create a rectangle
// note : the rectangle inisde starts at top left, but ends
// 1 pixel inside bottom right.
myRect := Rect(20, 30, 100, 200);

// check to see if (20,30) is inside the rectangle
if PtInRect(myRect, Point(20,30))
then ShowMessage(' 20, 30 is inside the rectangle')
else ShowMessage(' 20, 30 is outside the rectangle');

then ShowMessage(' 99,199 is inside the rectangle')
else ShowMessage(' 99,199 is outside the rectangle');

then ShowMessage('100,200 is inside the rectangle')
else ShowMessage('100,200 is outside the rectangle');
end;
171.5.3. Result
20, 30 is inside the rectangle
99,199 is inside the rectangle
100,200 is outside the rectangle


Page 238 of 366

172. Public - Starts an externally accessible section of a
class
172.1. Unit
Iris Standard
172.2. Type
Directive
172.3. Description
Note: Currently there is no difference in Iris between private and public! The public directive
starts a declaration section of a class definition. in a public section, Fields, Properties and
Methods are declared to be accessible to this class, classes descending from it, and code
using object instances of the class. in object Oriented terms, a class object is seen as a black
box. The internal operations are not relevant. public fields, properties and methods are the
externally visible part of an object - a controlled access to the internals of the class. Because
public access provides a linkage of sorts to external code, you should avoid wherever possible
making changes to the public section. A published section is very similar to a public section,
except that it provides some run time information.
172.4. Syntax
private
public
end;


Page 239 of 366

173. RadToDeg - Converts a radian value to degrees
173.1. Unit
Math
173.2. Type
Function
173.3. Description
The RadToDeg function is a mathematical function converting the Radians value into
Degrees. PI radians = 180 degrees
173.4. Syntax
function RadToDeg(const Radians : Extended) : Extended;
173.5. Example
173.5.1. Name
Use to display the result of an ArcSin calculation in degrees
173.5.2. Code
var
float : single;
begin
// the arcsin of 0.5 should give 30 degrees
float := ArcSin(0.5);
ShowMessage('ArcSin of 0.5 = '+FloatToStr(float)+' degrees');
end;
173.5.3. Result
ArcSin of 0.5 = 30 degrees


Page 240 of 366

174. Random - Generate a random floating point or
integer number
174.1. Unit
System
174.2. Type
Function
174.3. Description
The Random function generates random numbers. They can be floating point numbers in the
range : 0 <= Number < 1.0 or integer numbers in the range : 0 <= Number < LimitPlusOne
Iris uses a pseudo random number generator that always returns the same sequence of
values (232) each time the program runs. to avoid this predictability, use the Randomize
procedure. It repositions into this random number sequence using the time of day as a
pseudo random seed.
174.4. Syntax
1 function Random : Extended;2 function Random (LimitPlusOne : Integer) : Integer;


Page 241 of 366

174.5. Example
174.5.1. Name
Generate sets of floating point and integer numbers
174.5.2. Code
var
float : single;
int : Integer;
i : Integer;

begin
// get floating point random numbers in the range 0 <= Number < 1.0
for i := 1 to 5 do
begin
float := Random;
ShowMessage('float = '+FloatToStr(float));
end;

ShowMessage('');

// get an integer random number in the range 1..100
for i := 1 to 5 do
begin
int := 1 + Random(100); // the 100 value gives a range 0..99
ShowMessage('int = '+IntToStr(int));
end;
end;
174.5.3. Result
float = 2.3283064365387E-10
float = 0.031379981256104
float = 0.861048460006714
float = 0.202580958604813
float = 0.2729212641716

int = 68
int = 32
int = 17
int = 38
int = 43


Page 242 of 366

175. Randomize - Reposition the Random number
generator next value
175.1. Unit
System
175.2. Type
Procedure
175.3. Description
The Randomize procedure is used in conjunction with the Random function. It repositions the
random number generator in its sequence of 232 pseudo random numbers. Randomize uses
the time of day as the seed for this repositioning, so should provide a reliable method of
creating an unpredictable sequence of numbers, even if they are a part of a predetermined
sequence.
175.4. Syntax
procedure Randomize;


Page 243 of 366

175.5. Example
175.5.1. Name
Run this code twice to see the effect of Randomize
175.5.2. Code
var
int : Integer;
i : Integer;

begin
// if you run this program twice, only the first 5 values
// will be guaranteed to be the same each time - randomize
// repositions into a different part of the pseudo sequence
// of random numbers.

ShowMessage('Fixed first 5 random numbers');
for i := 1 to 5 do
begin
end;

// now randomize to reposition
Randomize;
ShowMessage('');

ShowMessage('Random next 5 numbers');
for i := 1 to 5 do
begin
end;
end;
175.5.3. Result
Fixed first 5 random numbers
int = 1
int = 4
int = 87
int = 21
int = 28

Random next 5 numbers
int = 35
int = 74
int = 45
int = 50
int = 31


Page 244 of 366

176. RandomRange - Generate a random integer number
within a supplied range
176.1. Unit
Math
176.2. Type
Function
176.3. Description
The RandomRange function generates a random Integer number within the range
RangeFrom to RangeTo inclusively. * This provides a more convenient version of the System
unit Random function. Both use a pseudo random number sequence of 232 values. Each time
you run your program, the values generated will be the same, unless you reposition the
generator to a different part of the sequence using the Randomize or RandSeed functions.
176.4. Syntax
function RandomRange(const RangeFrom, RangeTo : Integer) : Integer;
176.5. Example
176.5.1. Name
Generate random numbers in a very small range
176.5.2. Code
var
i : Integer;
begin
// show 5 random numbers in the range 652 to 656
for i := 1 to 5 do
ShowMessage('Random number : '+IntToStr(RandomRange(652, 656)));
end;
176.5.3. Result
Random number = 652
Random number = 652
Random number = 655
Random number = 652
Random number = 653


Page 245 of 366

177. RandSeed - Reposition the Random number
generator next value
177.1. Unit
System
177.2. Type
Variable
177.3. Description
The RandSeed variable is used in conjunction with the Random function. It changes the seed
used that Iris uses to generate its range of 232 pseudo random numbers.
177.4. Syntax
var RandSeed : LongInt;


Page 246 of 366

177.5. Example
177.5.1. Name
Run this code twice to see the effect of RandSeed
177.5.2. Code
var
int : Integer;
i : Integer;
hours, mins, secs, milliSecs : Word;

begin
// get random numbers using the default random seed value
ShowMessage('Fixed first 5 random numbers');
for i := 1 to 5 do
begin
end;

// now change the random seed to the milliseconds value
// of the current time
DecodeTime(now, hours, mins, secs, milliSecs);
ShowMessage('');
ShowMessage('Setting randSeed to value : '+IntToStr(milliSecs));
ShowMessage('');
RandSeed := milliSecs;

ShowMessage('Random next 5 numbers');
for i := 1 to 5 do
begin
end;
end;
177.5.3. Result
Fixed first 5 random numbers
int = 1
int = 4
int = 87
int = 21
int = 28

Setting random seed to value : 660

Random next 5 numbers
int = 72
int = 62
int = 28
int = 63
int = 44


Page 247 of 366

178. ReadLn - read a complete line of data from a text file
178.1. Unit
System
178.2. Type
Procedure
178.3. Description
The ReadLn procedure reads a complete line of data from a text file or to the console. Is
used to read a line of text from a text file with the given FileHandle. You must use AssignFile
to assign a file to the FileHandle and open the file with Reset before using ReadLn. The
current file text line is parsed into the given variable values. After parsing, any remaining text
in the current file line is ignored, and the file positioned to the next line (or Eof set true if
none left).
178.4. Syntax
procedure ReadLn (var FileHandle : TextFile; var Variable1 {,var variable2...}) ;


Page 248 of 366

178.5. Example
178.5.1. Name
Reading each text line as a set of 4 numbers
178.5.2. Code
var
myFile : TextFile;
Line : string;

begin
ReWrite(myFile);

// write numbers in a string
WriteLn(myFile, '1 2 3 4');

// write numbers as separate parameters
WriteLn(myFile, 5, ' ', 6, ' ', 7);

// write numbers as separate parameters
WriteLn(myFile, '8 9');

// close the file
CloseFile(myFile);

Reset(myFile);

begin
ReadLn(myFile, Line);
ShowMessage(Line);
end;

CloseFile(myFile);
end;
178.5.3. Result
1 2 3 4
5 6 7
8 9


Page 249 of 366

179. ReadRecipe - read a recipe file.
179.1. Unit
Iris Standard
179.2. Type
Recipes
179.3. Description
Reads values from a recipe file into a recipe tag structure.
179.4. Syntax
procedure ReadRecipe(RecipeName, FileName: string);
179.5. Example
179.5.1. Name
read a recipe file.
179.5.2. Code
begin
// load the recipe file 'coffee.rcp' into the recipe tag 'myrecipe'
ReadRecipe('MyRecipe', 'Coffee.rcp');

// save the recipe tag 'myrecipe' into the recipe file 'tea.rcp'
WriteRecipe('MyRecipe', 'Tea.rcp');
end;
179.5.3. Result
The recipe file coffee is loaded into the recipe tag MyRecipe
The recipe tag MyRecipe is stored into the recipe file Tea


Page 250 of 366

180. RecodeDate - Change only the date part of a
TDateTime variable
180.1. Unit
DateUtils
180.2. Type
Function
180.3. Description
The RecodeDate function allows the Year, Month and Day values of a TDateTime variable to
be changed without affecting the time.
180.4. Syntax
function RecodeDate(const SourceDate : TDateTime; const Year, Month, Day : Word) :
TDateTime;
180.5. Example
180.5.1. Name
Change the date without changing the time
180.5.2. Code
var
myDate : TDateTime;

begin
// set the date to 29/10/2002 at 12:34:56
ShowMessage('The starting date/time = '+DateTimeToStr(myDate));

// now change the date portion without touching the time
myDate := RecodeDate(myDate, 1957, 2, 18);
ShowMessage('The new date/time = '+DateTimeToStr(myDate));
end;
180.5.3. Result
The starting date/time = 29/10/2002 12:34:56
The new date/time = 18/02/1957 12:34:56


Page 251 of 366

181. RecodeTime - Change only the time part of a
TDateTime variable
181.1. Unit
DateUtils
181.2. Type
Function
181.3. Description
The RecodeTime function allows the Hour, Min, Sec and MSec (millisecond) values of a
TDateTime variable to be changed without affecting the date.
181.4. Syntax
function RecodeTime(const SourceDate : TDateTime; const Hour, Min, Sec, MSec : Word) :
TDateTime;
181.5. Example
181.5.1. Name
Change the time without changing the date
181.5.2. Code
var
myDate : TDateTime;

begin
// set the date to 29/10/2002 at 12:34:56
ShowMessage('The starting date/time = '+DateTimeToStr(myDate));

// now change the time portion without touching the date
myDate := RecodeTime(myDate, 7, 35, 22, 0);
ShowMessage('The new date/time = '+DateTimeToStr(myDate));
end;
181.5.3. Result
The new date/time = 29/10/2002 07:35:22


Page 252 of 366

182. RemoveDir - Remove a directory
182.1. Unit
SysUtils
182.2. Type
Function
182.3. Description
The RemoveDir function removes a directory Dir from the current directory. if the remove
succeeded, then True is returned, otherwise the error can be obtained using GetLastError.
182.4. Syntax
function RemoveDir(const Dir : string) : Boolean;
182.5. Example
182.5.1. Name
Create a new directory and then remove it
182.5.2. Code
begin
// create a new directory in the current directory
if CreateDir('TestDir')

// remove this directory
if RemoveDir('TestDir')
then ShowMessage('TestDir removed OK')
else ShowMessage('TestDir remove failed with error : '+
end;
182.5.3. Result
TestDir added OK
TestDir removed OK


Page 253 of 366

183. RemoveMailBox - Removes a MailBox
183.1. Unit
Iris Standard
183.2. Type
MailBox Function
183.3. Description
Remove the value from a MailBox. MailBoxes can be used to pass structured values to for
example popups.
183.4. Syntax
procedure RemoveMailbox(const AMailboxName: string);
183.5. Example
183.5.1. Name
Using MailBoxes
183.5.2. Code
begin








ClearMailbox;

end;
183.5.3. Result



Page 254 of 366

184. Rename - Rename a file
184.1. Unit
System
184.2. Type
Procedure
184.3. Description
The Rename procedure renames a file given by FileHandle to a new name NewFileName. The
file must have been assigned the given FileHandle using the AssignFile routine.
184.4. Syntax
procedure Rename(var FileHandle; NewFileName : string | PChar);


Page 255 of 366

184.5. Example
184.5.1. Name
Create a file, rename it, and then reopen it with the new name
184.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

// try to rename the file - ensure that no such file exists first!
DeleteFile('NewName.txt');
Rename(myFile, 'NewName.txt');

// now read the file
AssignFile(myFile, 'NewName.txt');
ReSet(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
184.5.3. Result
Hello
World


Page 256 of 366

185. Repeat - repeat statements until a ternmination
condition is met
185.1. Unit
Iris Standard
185.2. Type
Keyword
185.3. Description
The repeat keyword starts a control loop that is always executed at least once, and which
terminates when the Expression is satisfied (returns True). There is no need for begin or end
markers - the repeat and until keywords serve that purpose. It is used when it is important
that the statements are at least executed once.
185.4. Syntax
repeat
Statement1;
{statement2;
...}
until Expression


Page 257 of 366

185.5. Example
185.5.1. Name
Display integer squares until we reach or exceed 100
185.5.2. Code
var
num, sqrNum : Integer;

begin
num := 1;
sqrNum := num * num;

// display squares of integers until we reach 100 in value
repeat
// show the square of num
ShowMessage(IntToStr(num)+' squared = '+IntToStr(sqrNum));

// increment the number
Inc(num);

// square the number
until sqrNum > 100;
end;
185.5.3. Result
1 squared = 1
2 squared = 4
3 squared = 9
4 squared = 16
5 squared = 25
6 squared = 36
7 squared = 49
8 squared = 64
9 squared = 81
10 squared = 100


Page 258 of 366

186. ReplaceDate - Change only the date part of a
TDateTime variable
186.1. Unit
SysUtils
186.2. Type
Procedure
186.3. Description
The ReplaceDate function updates the date part of a TDateTime variable DateTimeVar with
the date part of another TDateTime value NewDateValue without affecting the time.
186.4. Syntax
procedure ReplaceDate(var DateTimeVar : TDateTime; const NewDateValue : TDateTime);
186.5. Example
186.5.1. Name
Change the date without changing the time
186.5.2. Code
var
myDateTime, newDate : TDateTime;

begin
// set the date to 29/10/2002 at 12:34:56
myDateTime := EncodeDateTime(2002, 10, 29, 12, 34, 56, 0);
ShowMessage('The starting date/time = '+DateTimeToStr(myDateTime));

// now change the date portion without touching the time
newDate := EncodeDate(1957, 02, 18);
ReplaceDate(myDateTime, newDate);
ShowMessage('The new date/time = '+DateTimeToStr(myDateTime));
end;
186.5.3. Result
The new date/time = 18/02/1957 12:34:56


Page 259 of 366

187. ReplaceTime - Change only the time part of a
TDateTime variable
187.1. Unit
SysUtils
187.2. Type
Procedure
187.3. Description
The ReplaceTime function updates the time part of a TDateTime variable DateTimeVar with
the time part of another TDateTime value NewTimeValue without affecting the date.
187.4. Syntax
procedure ReplaceTime(var DateTimeVar : TDateTime; const NewTimeValue : TDateTime);
187.5. Example
187.5.1. Name
Change the time without changing the date
187.5.2. Code
var
myDateTime, newTime : TDateTime;

begin
// set the date to 29/10/2002 at 12:34:56
myDateTime := EncodeDateTime(2002, 10, 29, 12, 34, 56, 0);
ShowMessage('The starting date/time = '+DateTimeToStr(myDateTime));

// now change the time portion without touching the date
newTime := EncodeTime(9, 45, 52, 0);
ReplaceTime(myDateTime, newTime);
ShowMessage('The new date/time = '+DateTimeToStr(myDateTime));
end;
187.5.3. Result
The new date/time = 29/10/2002 09:45:52


Page 260 of 366

188. Result - A variable used to hold the return value
from a function
188.1. Unit
System
188.2. Type
Variable
188.3. Description
The Result variable is used to hold the result value to be returned by a function. Iris
automatically creates this variable when the function starts. It is of the same type as the
return type of the function. Result can be used throughout a function as if it were explicitly
declared. Whatever its value is upon return from the function is what is passed back. Result
can be seen as equivalent to an out type parameter - where the value upon entry to the
function is undefined.
188.4. Syntax
var Result : function-Return-type;
188.5. Example
188.5.1. Name
Call a simple function that assigns to Result
188.5.2. Code
// remember to declare the function at type using the following line
// function squareit(value: integer): integer;

begin
// get the square of some numbers
ShowMessageFmt('Square of %d = %d',[2, SquareIt(2)]);
ShowMessageFmt('Square of %d = %d',[8, SquareIt(8)]);
end;

// simple function that returns the square of the parameter
function TUntitled.SquareIt(value: Integer): Integer;
begin
// return the value in the result variable
Result := value * value;
end;
188.5.3. Result
Square of 2 = 4
Square of 8 = 64


Page 261 of 366

189. ReWrite - Open a text or binary file for write access
189.1. Unit
System
189.2. Type
Procedure
189.3. Description
The ReWrite procedure opens a file given by FileHandle for writing. You must use AssignFile
to assign a file to the FileHandle before using Reset. if the file does not exist, it is created. if
the file already exists, the contents are lost, and new data is added to the start. Use write or
WriteLn to write to the file after this ReWrite is executed.
189.4. Syntax
procedure ReWrite(var FileHandle : TextFile);


Page 262 of 366

189.5. Example
189.5.1. Name
Writing and reading lines of text to/from a text file
189.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
189.5.3. Result
Hello
World


Page 263 of 366

190. RmDir - Remove a directory
190.1. Unit
System
190.2. Type
Procedure
190.3. Description
The RmDir procedure removes a directory from the current directory. if the directory does not
exist, an EInOutError exception is thrown. You can avoid such an exception by preventing IO
errors using the {$IOChecks Off} compiler directive. You must then check the IOResult value
to see the outcome of your IO operation (remembering that use of IOResult resets the
value).
190.4. Syntax
procedure RmDir(const DirectoryName : string);
190.5. Example
190.5.1. Name
Create a directory and then remove it
190.5.2. Code
var
error : Integer;

begin
// try to create a new subdirectory in the current directory
// switch off i/o error checking
{$iochecks off}
MkDir('TempDirectory');

// did the directory get created ok?
error := IOResult;
if error = 0
then ShowMessage('Directory created OK')
else ShowMessageFmt('Directory creation failed with error %d',[error]);

// delete the directory to tidy up
RmDir('TempDirectory');

// did the directory get removed ok?
error := IOResult;
if error = 0
then ShowMessage('Directory removed OK')
else ShowMessageFmt('Directory removal failed with error %d',[error]);
end;
190.5.3. Result
Directory created OK
Directory removed OK


Page 264 of 366

191. Round - Rounds a floating point number to an
integer
191.1. Unit
System
191.2. Type
Function
191.3. Description
The Round function rounds a floating point Number to an Integer value. The rounding uses
Bankers rules, where an exact half value causes a rounding to an even number: 12.4 rounds
to 1212.5 rounds to 12 // Round down to even12.6 rounds to 13 13.4 rounds to 1313.5
rounds to 14 // Round up to even13.6 rounds to 14
191.4. Syntax
function Round(const Number : Extended) : Int64;
191.5. Example
191.5.1. Name
A simple example
191.5.2. Code
begin
ShowMessage('Int(12.75) = '+FloatToStr(Int(12.75)));
ShowMessage('Frac(12.75) = '+FloatToStr(Frac(12.75)));
end;
191.5.3. Result
Round(12.75) = 13
Trunc(12.75) = 12
Int(12.75) = 12
Frac(12.75) = 0.75


Page 265 of 366

192. SecsPerDay - Gives the number of seconds in a day
192.1. Unit
SysUtils
192.2. Type
Constant
192.3. Description
The MinsPerDay constant gives the number of minutes in a day (24 * 60 * 60 = 86400).
192.4. Syntax
const SecsPerDay = 86400;
192.5. Example
192.5.1. Name
Show the number of minutes and seconds in a week
192.5.2. Code
begin
ShowMessage('Number of minutes in a week = '+IntToStr(MinsPerDay*7));
ShowMessage('Number of seconds in a week = '+IntToStr(SecsPerDay*7));
end;
192.5.3. Result
Number of minutes in a week = 10080
Number of seconds in a week = 604800


Page 266 of 366

193. SetCurrentDir - Change the current directory
193.1. Unit
SysUtils
193.2. Type
Function
193.3. Description
The SetCurrentDir function sets the current directory to Dir, returning True if successful. if the
directory does not exist, then getLAstError can be used to get the error code.
193.4. Syntax
function SetCurrentDir(const Dir : string) : Boolean;
193.5. Example
193.5.1. Name
Show set and re-show the current directory
193.5.2. Code
begin
// show the current directory
ShowMessage('Current directory = '+GetCurrentDir);

// change this value
SetCurrentDir('C:\program Files');

// show the current directory again
ShowMessage('Current directory = '+GetCurrentDir);
end;
193.5.3. Result
Current directory = C:\*
Current directory = C:\*


Page 267 of 366

194. SetMailBox - Sets a MailBox to a specific value
194.1. Unit
Iris Standard
194.2. Type
MailBox Function
194.3. Description
set a MailBox to a specific value. MailBoxes can be used to pass structured values to for
example popups.
194.4. Syntax
procedure SetMailbox(const AMailboxName: string; const AValue: string);
194.5. Example
194.5.1. Name
Using MailBoxes
194.5.2. Code
begin








ClearMailbox;

end;
194.5.3. Result



Page 268 of 366

195. SetPageDir - Sets the page directory
195.1. Unit
Iris Standard
195.2. Type
Frame Function
195.3. Description
Sets the current page directory. This can be used to access files that are inside the Iris
project directory.
195.4. Syntax
procedure SetPageDir(const AValue: string);
195.5. Example
195.5.1. Name
Alter the working directory
195.5.2. Code
begin
// read the original working directory
ShowMessage('The original working directory is '+GetPageDir);

// set the working directory to c:\
SetPageDir('C:\');

// read the new working directory
ShowMessage('The new working directory is '+GetPageDir);

end;
195.5.3. Result

The original working directory is C:\IrisTest
The new working directory is C:\


Page 269 of 366

196. SetTagValue - Sets a value of a tag
196.1. Unit
Iris Standard
196.2. Type
Tag Function
196.3. Description
Sets a value to a tag. Setting a value is a form of writing, but the value is only written if the
current value of the tag is different from the new value. It is possible to read values from
device and internal tags.
196.4. Syntax
function SetTagValue(TagName: string; Value: Variant): boolean;
196.5. Example 1
196.5.1. Name
read/set a tag value
196.5.2. Code
var
value: integer;

begin


// set a new value to the tag 'tagname'
SetTagValue('tagname',Inc(value));


end;
196.5.3. Result
The old value is ?
The new value is ?


Page 270 of 366

196.6. Example 2
196.6.1. Name
Read/set a tag value through a PowerTree
196.6.2. Code
var
value: integer;
begin
value := GetTagValue(ExpandMailbox('[PowerTree].name');


// set a new value to the tag '[powertree].name'
SetTagValue(ExpandMailbox('[PowerTree].name'),Inc(value));


end;
196.6.3. Result
The old value is ?
The new value is ?


Page 271 of 366

196.7. Example 3
196.7.1. Name
read/set a structured tag value
196.7.2. Code
var
value: integer;
begin


// set a new value to the tag 'unit1.equipmentmodule2'
SetTagValue('Unit1.EquipmentModule2',Inc(value));


end;
196.7.3. Result
The old value is ?
The new value is ?


Page 272 of 366

197. Shl - Shift an integer value left by a number of bits
197.1. Unit
Iris Standard
197.2. Type
Keyword
197.3. Description
The shl keyword performs a bitwise shift left of an Integer. The number is shifted Bits to the
left.
197.4. Syntax
Number shl bits
197.5. Example
197.5.1. Name
Shifting left and losing high bits before shifting back
197.5.2. Code
var
before, after : integer;
begin
// set up out starting number
before := $3C; // hex 3c = 003c in the integer

// shift left by 28 will lose the top 28 of the 32 bits of the integer
after := before shl 28;

ShowMessageFmt('Before : %x',[before]);
ShowMessageFmt('After shift left : %x',[after]);

// shifting right by 28 will not recover the lost data
after := after shr 28;

ShowMessageFmt('After shift right : %x',[after]);
end;
197.5.3. Result
Before : 3C
After shift left : C0000000
After shift right : C


Page 273 of 366

198. ShortDateFormat - Compact version of the date to
string format
198.1. Unit
SysUtils
198.2. Type
Variable
198.3. Description
The ShortDateFormat variable provides the short (compact) formatting used for default date
to string conversion. It is used by the DateToStr, DateTimeToStr and DateTimeToString
routines (the latter when the 'c' or 'ddddd' formatting is used). The following formatting
character strings can be used in the ShortDateFormat string: y = Year last 2 digitsyy = Year
last 2 digitsyyyy = Year as 4 digitsm = Month number no-leading 0mm = Month number as 2
digitsmmm = Month using ShortDayNames (Jan)mmmm = Month using LongDayNames
(January)d = Day number no-leading 0dd = Day number as 2 digitsddd = Day using
ShortDayNames (Sun)dddd = Day using LongDayNames (Sunday)
198.4. Syntax
var ShortDateFormat : string;
198.5. Example
198.5.1. Name
Illustrating customised ShortDateFormat setting
198.5.2. Code
var
myDate : TDateTime;

begin

// display using the default shortdateformat
ShowMessage('29/02/2000 using default = '+DateToStr(myDate));

ShortDateFormat := 'dddd dd mmmm yyyy';
ShowMessage('29/02/2000 using dddd dd mmmm yyyy = '+DateToStr(myDate));
end;
198.5.3. Result
29/02/2000 using default = 29/02/2000
29/02/2000 using dddd dd mmmm yyyy = Tuesday 29 February 2000


Page 274 of 366

199. ShortInt - An integer type supporting values -128 to
127
199.1. Unit
System
199.2. Type
Type
199.3. Description
The ShortInt type is the smallest form of signed integer, occupying 8 bits (1 byte) of storage.
It supports only the integers from -128 to 127.
199.4. Syntax
type ShortInt = -128..127;
199.5. Example
199.5.1. Name
Showing the maximum and minimum values
199.5.2. Code
var
A, B : ShortInt;
begin
A := -128;
B := 127;
end;
199.5.3. Result
A = -128 and B = 127
A + B = -1


Page 275 of 366

200. ShortString - Defines a string of up to 255
characters
200.1. Unit
System
200.2. Type
Type
200.3. Description
The ShortString type holds sequences of characters up to 255 in length. Strings can be
assigned from other strings, from functions that return a string, and with concatenations as in
the sample code.
200.4. Syntax
type ShortString
200.5. Example
200.5.1. Name
Assigning to a ShortString and a fixed length string
200.5.2. Code
var
myString : ShortString;
begin
// assign a famous sentence to this string
myString := 'Hello World';

// add to this string
myString := myString + ', how is everyone?';

// display the final mystring value
ShowMessage('myString = '+myString);
end;
200.5.3. Result
Hello World, how is everyone?


Page 276 of 366

201. ShortTimeFormat - Short version of the time to
string format
201.1. Unit
SysUtils
201.2. Type
Variable
201.3. Description
The ShortTimeFormat variable provides the short (compact) formatting used for certain time
to string conversions. It is used by the TimeToStr, DateTimeToStr and DateTimeToString
routines (the latter when the 'c' or 't' formatting is used). The following formatting character
strings can be used in the ShortTimeFormat string: h = Hour with no leading 0'shh = Hour as
2 digitsn = Minute with no leading 0'snn = Minute as 2 digitss = Seconds with no leading
0'sss = Seconds as 2 digitsz = Milli-seconds with no leading 0'szzz = Milli-seconds as 3 digits
201.4. Syntax
var ShortTimeFormat : string;
201.5. Example
201.5.1. Name
Illustrating customised ShortTimeFormat setting
201.5.2. Code
var
myDate : TDateTime;

begin
myDate := StrToTime('15:06:23.456');

// display using the default shorttimeformat
DateTimeToString(formattedDate, 't', myDate);
ShowMessage('15:06:23.456 using default = '+formattedDate);

ShortTimeFormat := 'hh nn ss';
DateTimeToString(formattedDate, 't', myDate);
ShowMessage('15:06:23.456 using override = '+formattedDate);
end;
201.5.3. Result
15:06:23.456 using default = 15:06
15:06:23.456 using override = 15 06 23


Page 277 of 366

202. ShowMessage - Display a string in a simple dialog
with an OK button
202.1. Unit
Dialogs
202.2. Type
Procedure
202.3. Description
The ShowMessage procedure displays a string of Text in a simple dialog with an OK button. It
is used to inform the user of some information - no decision is needed by the user. Insert
carriage return and line feed characters (#13#10) into the string to generate multi line
message display.
202.4. Syntax
procedure ShowMessage(const Text : string);
202.5. Example
202.5.1. Name
Show single and multiple line text displays
202.5.2. Code
begin
// show a simple message
ShowMessage('Hello World');

// show a blank message
ShowMessage('');

// split this into two lines
ShowMessage('Hello '+#13#10+'World');
end;
202.5.3. Result
Hello World

Hello
World


Page 278 of 366

203. ShowMessageFmt - Display formatted data in a
simple dialog with an OK button
203.1. Unit
Dialogs
203.2. Type
Procedure
203.3. Description
The ShowMessageFmt procedure provides 'C' like formatting of multiple of simple data types
into a string that is displayed in a single. It provides very precise control over this formatting.
The Formatting parameter defines how the Data array is manipulated into the displayed
string. The dialog has an OK button to allow the user to register the message and close the
dialog. The Formatting string can comprise a mix of ordinary characters (that are passed
unchanged to the result string), and data formatting characters. This formatting is best
explained by the example code. in simple terms, each data formatting substring starts with a
% and ends with a data type indicator : d = Decimal (integer)e = Scientificf = Fixedg =
Generalm = Moneyn = Number (floating)p = Pointers = Stringu = Unsigned decimalx =
Hexadecimal The general format of each formatting substring is as follows: %[index:][-
][Width][.Precision]type where the square brackets refer to optional parameters, and the : . -
characters are literals, the first 2 of which are used to identify two of the optional arguments.
203.4. Syntax
procedure ShowMessageFmt(const Formatting : string; const Data : array of const);


Page 279 of 366

203.5. Example 1
203.5.1. Name
203.5.2. Code
var
text : string;
begin
// just 1 data item
ShowMessageFmt('%s', ['Hello']);

// a mix of literal text and a data item
ShowMessageFmt('string = %s', ['Hello']);
ShowMessage('');

// examples of each of the data types
ShowMessageFmt('Decimal = %d', [-123]);
ShowMessageFmt('Exponent = %e', [12345.678]);
ShowMessageFmt('Fixed = %f', [12345.678]);
ShowMessageFmt('General = %g', [12345.678]);
ShowMessageFmt('Number = %n', [12345.678]);
ShowMessageFmt('Money = %m', [12345.678]);
ShowMessageFmt('string = %s', ['Hello']);
ShowMessageFmt('Unsigned decimal = %u', [123]);
ShowMessageFmt('Hexadecimal = %x', [140]);
end;
203.5.3. Result
Hello
string = Hello

Decimal = -123
Exponent = 1.23456780000000E+004
Fixed = 12345.68
General = 12345.678
Number = 12,345,68
Money = ?12,345.68
string = Hello
Unsigned decimal = 123
Hexadecimal = 8C


Page 280 of 366

203.6. Example 2
203.6.1. Name
Using the index, width and precision values
203.6.2. Code
begin
// the width value dictates the output size
// with blank padding to the left
// note the <> characters are added to show formatting
ShowMessageFmt('Padded decimal = <%7d>', [1234]);

// with the '-' operator, the data is left justified
ShowMessageFmt('Justified decimal = <%-7d>', [1234]);

// the precision value forces 0 padding to the desired size
ShowMessageFmt('0 padded decimal = <%.6d>', [1234]);

// a combination of width and precision
// note that width value precedes the precision value
ShowMessageFmt('Width + precision = <%8.6d>', [1234]);

// the index value allows the next value in the data array
// to be changed
ShowMessageFmt('Reposition after 3 strings = %s %s %s %1:s %s',
['Zero', 'One', 'Two', 'Three']);

// one or more of the values may be provided by the
// data array itself. note that testing has shown that an *
// for the width parameter can yield econverterror.
ShowMessageFmt('in line = <%10.4d>', [1234]);
ShowMessageFmt('Part data driven = <%*.4d>', [10, 1234]);
ShowMessageFmt('Data driven = <%*.*d>', [10, 4, 1234]);
end;
203.6.3. Result
Padded decimal = < 1234>
Justified decimal =
0 padded decimal =
Width + precision = < 001234>
Reposition after 3 strings = Zero One Two One Two
in line = < 1234>
Part data driven = < 1234>
Data driven = < 1234>


Page 281 of 366

204. ShowMessagePos - Display a string in a simple
dialog at a given screen position
204.1. Unit
Dialogs
204.2. Type
Procedure
204.3. Description
The ShowMessagePos procedure displays a string of Text in a simple dialog with an OK
button at the given XPos, YPos screen coordinates. The dialog is positioned with its top left at
the given screen pixel coordinates. This dialog is used to inform the user of some information
- no decision is needed by the user. Insert carriage return and line feed characters (#13#10)
into the string to generate multi line message display.
204.4. Syntax
procedure ShowMessagePos(const Text : string; const XPos, YPos : Integer);
204.5. Example
204.5.1. Name
Show the message dialog at default and selected screen coordinates
204.5.2. Code
begin
// show a simple message at the default coordinates
ShowMessage('Hello World');

// show a simple message at screen position 100, 200
ShowMessagePos('Hello World', 100, 200);
end;
204.5.3. Result
The following is displayed at the screen centre:

Hello World

The following is displayed at position 100,200:

Hello World


Page 282 of 366

205. Shr - Shift an integer value right by a number of bits
205.1. Unit
Iris Standard
205.2. Type
Keyword
205.3. Description
The shr keyword performs a bitwise shift right of an Integer. The number is shifted Bits to
the right.
205.4. Syntax
Number shr bits
205.5. Example
205.5.1. Name
Shifting left and losing high bits before shifting right
205.5.2. Code
var
before, after : integer;
begin
// set up out starting number
before := $3C; // hex 3c = 003c in the integer

// shift left by 28 will lose the top 28 of the 32 bits of the integer
after := before shl 28;

ShowMessageFmt('Before : %x',[before]);
ShowMessageFmt('After shift left : %x',[after]);

// shifting right by 28 will not recover the lost data
after := after shr 28;

ShowMessageFmt('After shift right : %x',[after]);
end;
205.5.3. Result
Before : 3C
After shift left : C0000000
After shift right : C


Page 283 of 366

206. Sin - The Sine of a number
206.1. Unit
System
206.2. Type
Function
206.3. Description
The Sin function is a mathematical function giving the Sine value of a Number value given
radians. PI radians = 180 degrees
206.4. Syntax
function Sin(const Number : Extended) : Extended;
206.5. Example
206.5.1. Name
Get the Sine of 30 degrees
206.5.2. Code
var
float : single;
begin
float := Sin(PI/6); // = 180/6 = 30 degrees
ShowMessage('Sin(PI/6) = '+FloatToStr(float));
end;
206.5.3. Result
Sin(PI/6) = 0.5


Page 284 of 366

207. Single - The smallest capacity and precision floating
point type
207.1. Unit
System
207.2. Type
Type
207.3. Description
The Single type is the fastest floating point type in Iris. It also has the lowest storage
requirements - 32 bits (1 for the sign 8 for the exponent, and 23 for the mantissa). It
supports approximately 7 digits of precision in a range from 1.18 x 10-38 to 3.4 x 1038.
207.4. Syntax
type Single;
207.5. Example
207.5.1. Name
Showing the precision and capacity of Single values
207.5.2. Code
var
account1, account2, account3 : Single;
begin
account1 := 0.1234567890123456789;
account2 := 1.18E-38;
account3 := 3.4E38;

end;
207.5.3. Result
Account1 = 0.1234567910123456
Account2 = 1.18E-38
Account3 = 3.4E38


Page 285 of 366

208. SmallInt - An Integer type supporting values from -
32768 to 32767
208.1. Unit
System
208.2. Type
Type
208.3. Description
The SmallInt type is a 16 bit sized signed Integer. to hold larger integers, use the Integer ,
LongInt (both 32 bits) or the Int64 (64 bits) types.
208.4. Syntax
type SmallInt = -32768..32767;
208.5. Example
208.5.1. Name
Showing the capacity of SmallInt
208.5.2. Code
var
A, B : SmallInt;
begin
A := -32767;
B := 32768;
end;

208.5.3. Result
A = -32767 and B = 32768
A + B = 1


Page 286 of 366

209. Sqr - Gives the square of a number
209.1. Unit
System
209.2. Type
Function
209.3. Description
The Sqr function returns the square of a Number. Sqr(Number) = Number * Number The
number may be an integer or floating point type. Integer, Int64 numbers if the square of the
number exceeds the capacity of the target variable, then the result is : Result mod Capacity
Extended numbers if the square of the number exceeds the capacity, EOverFlow exception is
raised. Special values are treated as follows: Infinity, -Infinity: InfinityNaN (not a Number) :
NaN
209.4. Syntax
1 function Sqr(Number : Integer) : Integer;
2 function Sqr(Number : Int64) : Int64;
3 function Sqr(Number : Extended) : Extended;
209.5. Example
209.5.1. Name
Find the square of various values
209.5.2. Code
var
number, squared : Byte;
float : Extended;

begin
// the square of 15 = 225
number := 15;
squared := Sqr(number);
ShowMessage(IntToStr(number)+' squared = '+IntToStr(squared));

// the square of infinity is still infinity
float := Infinity;
float := Sqr(float);
ShowMessage('Infinity squared = '+FloatToStr(float));
end;
209.5.3. Result
15 squared = 225
Infinity squared = INF


Page 287 of 366

210. Sqrt - Gives the square root of a number
210.1. Unit
System
210.2. Type
Function
210.3. Description
The Sqrt function returns the square root of a Number. The number must be a floating point
type. Special values are treated as follows: Infinity: Infinity-0 : -0NaN (not a Number) : NaN
210.4. Syntax
function Sqrt(Number : Extended) : Extended;
210.5. Example
210.5.1. Name
Find the square root of various values
210.5.2. Code
var
number, squareRoot : Extended;

begin
// the square root of 225 = 15
number := 225;
squareRoot := Sqrt(number);
ShowMessage('Square root of '+FloatToStr(number)+' = '+FloatToStr(squareRoot));

// the square root of 3.456 = 1.859...
number := 3.456;
squareRoot := Sqrt(number);
ShowMessage('Square root of '+FloatToStr(number)+' = '+FloatToStr(squareRoot));

// the square root of infinity is still infinity
number := Infinity;
number := Sqrt(number);
ShowMessage('Square root of Infinity = '+FloatToStr(number));
end;
210.5.3. Result
Square root of 225 = 15
Square root of 3.456 = 1.859032006180
Square root of Infinity = INF


Page 288 of 366

211. StopRunTime - Stops the runtime
211.1. Unit
Iris Standard
211.2. Type
Runtime
211.3. Description
Stops the Iris Runtime. This is the same as selecting stop application from the taskbar icon.
211.4. Syntax
procedure StopRunTime;
211.5. Example
211.5.1. Name
Stopping the runtime.
211.5.2. Code
begin
// display the final message
ShowMessage('System is going down');
// stops the run time
StopRunTime;
end;
211.5.3. Result
System is going down
The runtime will stop.


Page 289 of 366

212. String - A data type that holds a string of characters
212.1. Unit
System
212.2. Type
Type
212.3. Description
The string data type is used to hold sequences of characters, like sentences. string is by
default, actually treated as a AnsiString. It can be treated as a ShortString if the $LongStrings
compiler directive is set Off (the default is on). An AnsiChar can hold any number of
characters, restricted only by memory. Strings can be assigned from other strings, from
functions that return a string, and with concatenations as in the sample code.
212.4. Syntax
type string;
212.5. Example
212.5.1. Name
Assigning to a string and then adding a bit more
212.5.2. Code
var
myString : string;
begin
// assign a famous sentence to this string
myString := 'Hello World';

// add to this string
myString := myString + ', how is everyone?';

// display the final mystring value
ShowMessage('myString = '+myString);
end;
212.5.3. Result
Hello World, how is everyone?


Page 290 of 366

213. StringReplace - Replace one or more substrings
found within a string
213.1. Unit
SysUtils
213.2. Type
Function
213.3. Description
The StringReplace function replaces the first or all occurences of a substring OldPattern in
SourceString with NewPattern according to Flags settings. The changed string is returned.
The Flags may be none, one, or both of these set values: rfReplaceAll : Change all
occurrences rfIgnoreCase : Ignore case when searching These values are specified in square
brackets, as in the example.
213.4. Syntax
function StringReplace(const SourceString, OldPattern, NewPattern : string; Flags :
TReplaceFlags) : string;
213.5. Example
213.5.1. Name
Change a
213.5.2. Code
var
before, after : string;

begin
// try to replace all occurrences of a to the
before := 'This is A way to live A big life';

after := StringReplace(before, ' A ', ' THE ', rfReplaceAll);
ShowMessage('Before = '+before);
ShowMessage('After = '+after);
end;
213.5.3. Result
Before = This is A way to live A big life
After = This is THE way to live THE big life


Page 291 of 366

214. StrToCurr - Convert a number string into a currency
value
214.1. Unit
SysUtils
214.2. Type
Function
214.3. Description
The StrToCurr function converts a number string, CurrString such as '123.456' into a Currency
value. It supports integer, floating point, and scientific (exponent) formats. if a decimal point
appears in CurrString, then it must match the current DecimalSeparator value.
214.4. Syntax
function StrToCurr(CurrencyString : string) : Currency;
214.5. Example 1
214.5.1. Name
Converting a scientific format number string
214.5.2. Code
var
stringValue : string;
currValue : Currency;

begin
// set up the source string containing a number representation
stringValue := '123.456E+002';

// convert it to a floating point number
currValue := StrToCurr(stringValue);

// and display the value
ShowMessage(stringValue+' = '+CurrToStr(currValue));
end;
214.5.3. Result
123.456E+002 = 12345.6


Page 292 of 366

214.6. Example 2
214.6.1. Name
Catching string conversion errors
214.6.2. Code
var
A : Currency;

begin
// we will catch conversion errors
try
A := StrToCurr('10 E 2'); // middle blanks are not supported
except
ShowMessage('Exception');
end;

try
A := StrToCurr('$FF'); // hexadecimal values are not supported
except
ShowMessage('Exception');
end;
end;
214.6.3. Result
'10 E 2' is not a valid floating point value
'$FF' is not a valid floating point value


Page 293 of 366

215. StrToDate - Converts a date string into a TDateTime
value
215.1. Unit
SysUtils
215.2. Type
Function
215.3. Description
The StrToDate function attempts to convert a date as a string Date into a TDateTime value.
The date string must adhere to the format of the ShortDateFormat value, and use the
DateSeparator character to separate the day, month and year values. The default format in
the UK is day/month/year, where : The day must be 1..31 (depending on month/year)The
month must be 1..12The year must be 0..9999 (optional)
215.4. Syntax
1 function StrToDate(const Date : string) : TDateTime;
2 function StrToDate (const Date : string; const FormatSettings : TFormatSettings) :
TDateTime;
215.5. Example
215.5.1. Name
Showing 2 and 4 digit year date string conversions
215.5.2. Code
var
myDate : TDateTime;

begin
ShowMessage('15/03/75 = '+DateTimeToStr(myDate));
ShowMessage('01/01/2075 = '+DateTimeToStr(myDate));
end;
215.5.3. Result
15/03/75 = 15/03/1975
01/01/2075 = 01/01/2075


Page 294 of 366

216. StrToDateTime - Converts a date+time string into a
TDateTime value
216.1. Unit
SysUtils
216.2. Type
Function
216.3. Description
The StrToDateTime function attempts to convert a date plus time as a string DateTime into a
TDateTime value. The first, date part of the string must adhere to the format of the
ShortDateFormat value, and use the DateSeparator character to separate the day, month and
year values. The second, time part, separated by a blank from the date must adhere to the
format of the LongTimeFormat value, and use the TimeSeparator character to separate the
hour, minute and second values. The default format in the UK isday/month/year
hour:minute:second.msec, where : The day must be 1..31 (depending on month/year)The
month must be 1..12The year must be 0..9999 (optional)The hour must be 0..23The minute
must be 0..59 (optional)The second must be 0..59 (optional)The milli-sec must be 0..999
(optional) Omitting the year results in the use of the current year. Note that year 0015, for
example, must be given with the century digits; 15 on its own would be seen as a recent
year. if the year is 2 digits, the century is determined by the TwoDigitYearCenturyWindow
value. Any errors in the date/time string will yield EConvertError.
216.4. Syntax
function StrToDateTime(const DateTime : string) : TDateTime;
216.5. Example
216.5.1. Name
Showing 2 and 4 digit year date string conversions
216.5.2. Code
var
myDateTime : TDateTime;

begin
myDateTime := StrToDateTime('23/02/75 12');
ShowMessage('23/02/75 12 = '+DateTimeToStr(myDateTime));

myDateTime := StrToDateTime('23/02/2075 12:34:56');
ShowMessage('23/02/2075 12:34:56 = '+DateTimeToStr(myDateTime));
end;
216.5.3. Result
23/02/75 12 = 23/02/1975 12:00:00
23/02/2075 12:34:56 = 23/02/2075 12:34:56


Page 295 of 366

217. StrToFloat - Convert a number string into a floating
point value
217.1. Unit
SysUtils
217.2. Type
Function
217.3. Description
The StrToFloat function converts a number string, FloatString such as '123.456' into an
Extended floating point number. It supports integer, floating point, and scientific (exponent)
formats. if a decimal point appears in FloatString, then it must match the current
DecimalSeparator value.
217.4. Syntax
function StrToFloat(FloatString : string) : Extended;
217.5. Example
217.5.1. Name
Converting a scientific format number string
217.5.2. Code
var
stringValue : string;
floatValue : Extended;

begin
// set up the source string containing a number representation
stringValue := '123.456E+002';

// convert it to a floating point number
floatValue := StrToFloat(stringValue);

// and display the value
ShowMessage(stringValue+' = '+FloatToStr(floatValue));
end;
217.5.3. Result
123.456E+002 = 12345.6


Page 296 of 366

218. StrToInt - Convert an integer string into an Integer
value
218.1. Unit
SysUtils
218.2. Type
Function
218.3. Description
The StrToInt function converts an Integer string, IntegerString such as '123' into an Integer.
It supports +ve and -ve numbers, and hexadecimal numbers, as prefixed by $ or 0x.
218.4. Syntax
function StrToInt(IntegerString : string) : Integer;
218.5. Example 1
218.5.1. Name
Converting decimal and hexadecimal numbers
218.5.2. Code
var
A, B, C, D, E, F : Integer;

begin
A := 32;
B := StrToInt('100'); // '100' string converted to 100 integer
C := StrToInt(' -12'); // leading blanks are ignored
D := StrToInt('$1E'); // hexadecimal values start with a '$'
E := StrToInt('-0x1E'); // ... or with a '0x'
F := A + B + C + D + E; // lets add up all these integers

ShowMessage('A : '+IntToStr(A));
ShowMessage('B : '+IntToStr(B));
ShowMessage('C : '+IntToStr(C));
ShowMessage('D : '+IntToStr(D));
ShowMessage('E : '+IntToStr(E));
ShowMessage('F : '+IntToStr(F));
end;
218.5.3. Result
A : 32
B : 100
C : -12
D : 30
E : -30
F : 120


Page 297 of 366

218.6. Example 2
218.6.1. Name
Catching string to integer conversion errors
218.6.2. Code
var
A : Integer;

begin
// we will catch conversion errors
try
A := StrToInt('100 '); // trailing blanks are not supported
except
on Exception : EConvertError do
ShowMessage(Exception.message);
end;

try
A := StrToInt('$FG'); // 'g' is an invalid hexadecimal digit
except
on Exception : EConvertError do
ShowMessage(Exception.message);
end;
end;
218.6.3. Result
'100 ' is not a valid integer value
'$FG' is not a valid integer value


Page 298 of 366

219. StrToIntDef - Convert a string into an Integer value
with default
219.1. Unit
SysUtils
219.2. Type
Function
219.3. Description
The StrToIntDef function converts an Integer string, IntegerString such as '123' into an
Integer value, with a default if the conversion fails. It supports +ve and -ve numbers, and
hexadecimal numbers, as prefixed by $ or 0x.
219.4. Syntax
function StrToIntDef(const IntegerString : string; default : Integer) : Integer;
219.5. Example 1
219.5.1. Name
Converting decimal and hexadecimal numbers
219.5.2. Code
var
A, B, C, D, E, F : Integer;

begin
A := 32;
B := StrToIntDef('100', 0); // '100' string converted to 100 integer
C := StrToIntDef(' -12', 0); // leading blanks are ignored
D := StrToIntDef('$1E', 0); // hexadecimal values start with a '$'
E := StrToIntDef('-0x1E', 0); // ... or with a '0x'
F := A + B + C + D + E; // lets add up all these integers

ShowMessage('A : '+IntToStr(A));
ShowMessage('B : '+IntToStr(B));
ShowMessage('C : '+IntToStr(C));
ShowMessage('D : '+IntToStr(D));
ShowMessage('E : '+IntToStr(E));
ShowMessage('F : '+IntToStr(F));
end;
219.5.3. Result
A : 32
B : 100
C : -12
D : 30
E : -30
F : 120


Page 299 of 366

219.6. Example 2
219.6.1. Name
Catching string to integer conversion errors
219.6.2. Code
var
A : Integer;

begin
// no need to catch conversion errors
A := StrToIntDef('100 ', 55); // trailing blanks are not supported
ShowMessage('Value = '+IntToStr(A));

A := StrToIntDef('$FG' , 66); // 'g' is an invalid hexadecimal digit
ShowMessage('Value = '+IntToStr(A));
end;
219.6.3. Result
Value = 55
Value = 66


Page 300 of 366

220. StrToTime - Converts a time string into a TDateTime
value
220.1. Unit
SysUtils
220.2. Type
Function
220.3. Description
The StrToTime function attempts to convert a time as a string Date into a TDateTime value.
The time string must adhere to the format of the LongTimeFormat value, and use the
TimeSeparator character to separate the hour, minute and second values. The default format
in the UK is hour:minute:second.milli-seconds, where : The hour must be 0..23The minute
must be 0..59 (optional)The second must be 0..59 (optional)The milli-secs must be 0..999
(optional) You may use the current AM and PM value (as defined by TimeAMString,
TimePMString), or the literals 'AM', 'am', 'PM' and 'pm' before or after the time. The date is
set to 30 dec 1899, one day short of the 19th century. Any errors in the time string will yield
EConvertError.
220.4. Syntax
function StrToTime(const Time : string) : TDateTime;
220.5. Example
220.5.1. Name
Showing with and without minutes and/or seconds
220.5.2. Code
var
myTime : TDateTime;

begin
myTime := StrToTime('3PM');
ShowMessage('3PM = '+TimeToStr(mytime));
myTime := StrToTime('15');
ShowMessage('15 = '+TimeToStr(mytime));
myTime := StrToTime('15:03');
ShowMessage('15:03 = '+TimeToStr(mytime));
myTime := StrToTime('15:03:45');
ShowMessage('15:03:45 = '+TimeToStr(mytime));
end;
220.5.3. Result
3PM = 15:00:00
15 = 15:00:00
15:03 = 15:03:00
15:03:45 = 15:03:45


Page 301 of 366

221. Succ - Increment an ordinal variable
221.1. Unit
System
221.2. Type
Function
221.3. Description
The Succ function increments an ordinal value, and returns this value. You can increment :
Characters Non-floating number types Enumeration types Pointers The increment is by the
base size of the unit. for example, incrementing a Pointer will be by 4 bytes if the pointer
points to Words.
221.4. Syntax
function Succ(const Ordinal Value) : Ordinal type;
221.5. Example
221.5.1. Name
Incrementing characters, numbers and enumerations
221.5.2. Code
var
Number : Integer;

begin

Number := 23;

Number := Succ(Number);
end;
221.5.3. Result
Number : 23
Number+1 : 24


Page 302 of 366

222. Tan - The Tangent of a number
222.1. Unit
Math
222.2. Type
Function
222.3. Description
The Tan function is a mathematical function giving the Tangent value of a Number value
given radians. PI radians = 180 degrees
222.4. Syntax
function Tan(const Number : Extended) : Extended;
222.5. Example
222.5.1. Name
Get the Tangent of 45 degrees
222.5.2. Code
var
float : single;
begin
// the tangent of 45 degrees = 1.0
float := Tan(PI/4); // = 180/4 = 45 degrees
ShowMessage('Tan(PI/4) = '+FloatToStr(float));
end;
222.5.3. Result
Tan(PI/4) = 1


Page 303 of 366

223. TBits - An object that can hold an infinite number of
Boolean values
223.1. Unit
Classes
223.2. Type
Type
223.3. Description
The TBits type holds a flexible collection of bits (Boolean values). The colection size can be
altered at any time (using the size property). Bits are accessed using the Bits property, like
this: flag := myBits.Bits[2]; or, more simply: flag := myBits[2]; There is one utility function -
OpenBit - which returns the index of the first false value. There is no equivalent for true
values.
223.4. Syntax
type TBits;


Page 304 of 366

223.5. Example
223.5.1. Name
A simple example
223.5.2. Code
var
flags : TBits; // our variable collection of boolean values
i : Integer;
begin
// create our tbits object
flags := TBits.Create;

// add a few items to our boolean flags collection
flags.Size := 5;

// and set a few values
flags[0] := true;
flags[1] := true;
flags[4] := true;

// now display the contents of the collection
// note that indexing starts at 0
for i := 0 to flags.Size-1 do
if flags[i] = true
then ShowMessageFmt('Bit %d is true',[i])
else ShowMessageFmt('Bit %d is false',[i]);

// tbits has one main method -
// to find the index of the first false value
ShowMessageFmt('index of the first false value is %d',[flags.OpenBit]);
end;
223.5.3. Result
Bit 0 is true
Bit 1 is true
Bit 2 is false
Bit 3 is false
Bit 4 is true
index of the first false value is 2


Page 305 of 366

224. TDateTime - Data type holding a date and time value
224.1. Unit
System
224.2. Type
Type
224.3. Description
The TDateTime type holds a date and time value. It is stored as a Double variable, with the
date as the integral part, and time as fractional part. The date is stored as the number of
days since 30 Dec 1899. Quite why it is not 31 Dec is not clear. 01 Jan 1900 has a days value
of 2. Because TDateTime is actually a double, you can perform calculations on it as if it were
a number. This is useful for calculations such as the difference between two dates.
224.4. Syntax
type TDateTime = type Double;
224.5. Example
224.5.1. Name
Finding the difference between two dates
224.5.2. Code
var
day1, day2 : TDateTime;
diff : Double;
begin
day1 := StrToDate('12/06/2002');
day2 := StrToDate('12/07/2002');
ShowMessage('day1 = '+DateToStr(day1));
ShowMessage('day2 = '+DateToStr(day2));

diff := day2 - day1;
ShowMessage('day2 - day1 = '+FloatToStr(diff)+' days');
end;
224.5.3. Result
day1 = 12/06/2002
day2 = 12/07/2002
day2 - day1 = 30 days


Page 306 of 366

225. TextFile - Declares a file type for storing lines of text
225.1. Unit
System
225.2. Type
Type
225.3. Description
The TextFile type defines a file type for holding textual data. Text files provide a simple,
convenient way of storing textual data. They do provide mechanisms for reading and writing
numerical data stored as text (see write), but it is safer and wiser to use structured records
when storing anything other than plain text strings. However, text files do allow variable
length records.
225.4. Syntax
var TextFile;


Page 307 of 366

225.5. Example
225.5.1. Name
Writing to and reading from a TextFile
225.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// close the file
CloseFile(myFile);

Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
225.5.3. Result
Hello World


Page 308 of 366

226. TFloatFormat - Formats for use in floating point
number display functions
226.1. Unit
SysUtils
226.2. Type
Type
226.3. Description
The TFloatFormat type is used by the following SysUtils functions : CurrToStrF? for displaying
currency valuesFloatToStrF for general float displayingFloatToText for formatting to an array
The possible values of TFloatFormat are : - ffGeneral - Defines general number formatting
that aims to keep the resultant value as compact as possible. It removes trailing zeros and
the decimal point where appropriate. No thousand separators are shown. Exponent format is
used if the mantissa is too large for the specified Precision value of the formatting command.
in this case, the Digits value (0..4) determines the minimum number of exponent digits
shown. The decimal point character is determined by the DecimalSeparator variable. -
ffExponent - Commonly referred to as the Scientific or Engineering format, the exponent
refers to the letter E followed by a number. The number gives the power of 10 of the
number. for example, E+15 means 1015. The exponent always has a + or - sign. This
exponent is preceded by a number that always has one digit before the decimal place. for
example : 123.456 formats as 1.23456E+20.00123 formats as 1.23E-3 The using function
Precision parameter gives the number of displayed digits before the E, and the Digits
parameter gives the number (0..4) of digits after the E. The decimal point character is
determined by the DecimalSeparator variable. - ffFixed - This format again uses no thousands
separator. It displays Precision digits before the decimal point, and Digits digits after. if there
are too many digits before the decimal point, then the Exponent format is used instead. The
decimal point character is determined by the DecimalSeparator variable. - ffNumber - Same
as ffFixed, except that thousand separators are used. These are defined by the
ThousandSeparator variable. - ffCurrency - Same as ffNumber, but with a currency symbol
(string) added, as defined by the CurrencyString variable. Additionally, the formatting is
influenced by the CurrencyFormat and NegCurrFormat variables.
226.4. Syntax
type TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency);


Page 309 of 366

226.5. Example
226.5.1. Name
Illustrate the 5 different types of formatting
226.5.2. Code
var
amount : Extended;

begin
amount := 1234.56;

// display using ffgeneral formatting
ShowMessage('General 4,0 = '+FloatToStrF(amount, ffGeneral, 4, 0));
ShowMessage('');

// display using ffexponent formatting
ShowMessage('Exponent 4,0 = '+FloatToStrF(amount, ffExponent, 4, 0));
ShowMessage('');

// display using fffixed formatting
ShowMessage('Fixed 4,0 = '+FloatToStrF(amount, ffFixed, 4, 0));
ShowMessage('');

// display using ffnumber formatting
ShowMessage('Number 4,0 = '+FloatToStrF(amount, ffNumber, 4, 0));
ShowMessage('');

// display using ffcurrency formatting
ShowMessage('Currency 4,0 = '+FloatToStrF(amount, ffCurrency, 4, 0));
end;


Page 310 of 366

226.5.3. Result
General 4,0 = 1235
General 6,0 = 1234.56
General 6,2 = 1234.56
General 3,2 = 1.23E03

Exponent 4,0 = 1.235E+3
Exponent 6,0 = 1.23456E+3
Exponent 6,2 = 1.23456E+03
Exponent 3,2 = 1.23E+03

Fixed 4,0 = 1235
Fixed 6,0 = 1235
Fixed 6,2 = 1234.56
Fixed 3,2 = 1.23E03

Number 4,0 = 1,235
Number 6,0 = 1,235
Number 6,2 = 1,234.56
Number 3,2 = 1.23E03

Currency 4,0 = ?1,235
Currency 6,0 = ?1,235
Currency 6,2 = ?1,234.56
Currency 3,2 = 1.23E03


Page 311 of 366

227. TFormatSettings - A record for holding locale values
227.1. Unit
SysUtils
227.2. Type
Type
227.3. Description
The TFormatSettings record is used to hold Windows locale global variable of a number of
data conversion functions. It must be furnished before invoking a function that uses it.
227.4. Syntax
type TFormatSettings = record
CurrencyFormat : Byte;
NegCurrFormat : Byte;
ThousandSeparator : Char;
DecimalSeparator : Char;
CurrencyDecimals : Byte;
DateSeparator : Char;
TimeSeparator : Char;
ListSeparator : Char;
CurrencyString : string;
ShortDateFormat : string;
LongDateFormat : string;
TimeAMString : string;
TimePMString : string;
ShortTimeFormat : string;
LongTimeFormat : string;
ShortMonthNames : array[1..12] of string;
LongMonthNames : array[1..12] of string;
ShortDayNames : array[1..7] of string;
LongDayNames : array[1..7] of string;
TwoDigitYearCenturyWindow : Word;
end;


Page 312 of 366

227.5. Example
227.5.1. Name
Use of the format settings record
227.5.2. Code
var
formatSettings : TFormatSettings;

begin
// furnish the locale format settings record
GetLocaleFormatSettings(LOCALE_SYSTEM_default, formatSettings);

// and use it in the thread safe form of currtostrf
ShowMessage('1234.56 formats as = '+
CurrToStrF(1234.56, ffCurrency, 4, formatSettings));
end;
227.5.3. Result
1234.56 formats as ?1,234.5600


Page 313 of 366

228. Then - Part of an if statement - starts the true clause
228.1. Unit
Iris Standard
228.2. Type
Keyword
228.3. Description
The then keyword is part of the if statement. It is used to start the section of code executed
when the if condition is true. There are two forms of the if statement - one with an else
clause, the other not. if works as follows: if the condition is true, then the first statement is
executed. if false, then this statement is bypassed. if there is an else statement, it is executed
instead. in all cases, the Statement clause must be contained in a begin/end block if it is
longer than one statement in length.
228.4. Syntax
1 if Condition then Statement;


Page 314 of 366

228.5. Example
228.5.1. Name
Illustrate various uses of the then clause
228.5.2. Code
begin
// illustrate a simple if statement that executes true
if True then ShowMessage('True!');

// illustrate the same, but with multiple actions
if 1 = 1 then
begin
ShowMessage('We now have');
ShowMessage('multiple lines');
end;

// illustrate a simple if statement that fails
if 1 = 2 then ShowMessage('1 = 2');

// illustrate an if then else statement
if False

if true then
if false then
else
else
end;
228.5.3. Result
True!
We now have
multiple lines
False


Page 315 of 366

229. ThousandSeparator - The character used to display
the thousands separator
229.1. Unit
SysUtils
229.2. Type
Variable
229.3. Description
The ThousandSeparator variable is used in currency and floating point display functions.
ThousandSeparator value is ',' by default, but is dependent on your Windows locale.
229.4. Syntax
var ThousandSeparator : char;
229.5. Example
229.5.1. Name
Changing the thousands separator character
229.5.2. Code
var
amount : Currency;
begin
amount := 1234567.89; // 1,234,567 pounds 89 pence

// display with the default thousands separator

// display with a new thousands separator
ThousandSeparator := ' ';
end;
229.5.3. Result
Amount = ?1,234,567.89
Amount = ?1 234 567.89


Page 316 of 366

230. Time - Gives the current time
230.1. Unit
SysUtils
230.2. Type
Function
230.3. Description
The Time function returns the current time in the local time zone. Because the return value is
a TDateTime type, the date component is set to zero (30/12/1899).
230.4. Syntax
function Time : TDateTime;
230.5. Example
230.5.1. Name
Show the current time
230.5.2. Code
var
today : TDateTime;
begin
today := Time;
ShowMessage('today has date = '+DateToStr(today));
ShowMessage('today has time = '+TimeToStr(today));
end;
230.5.3. Result
today has date = 30/12/1899
today has time = 13:37:25


Page 317 of 366

231. TimeAMString - Determines AM value in
DateTimeToString procedure
231.1. Unit
SysUtils
231.2. Type
Variable
231.3. Description
The TimeAMString variable value is used in the DateTimeToString procedure, and StrToTime
function. It qualifies the hour value when the ampm formatting string is used. The position is
determined by the formatting string (see the example). The default value is 'AM' as set by the
locale settings.
231.4. Syntax
var TimeAMString : string
231.5. Example
231.5.1. Name
Show AM as Morning
231.5.2. Code
var
myDate : TDateTime;

begin

// format using the default timeamstring value
DateTimeToString(formattedDate, 'dd/mm/yyyy @ hh:nn ampm', myDate);
ShowMessage('Using default AM value = '+formattedDate);

// format using the 'in the morning' value
TimeAMString := 'in the morning';
ShowMessage('with changed AM value = '+formattedDate);
end;
231.5.3. Result
Using default AM value = 09/02/2002 @ 11:03 AM
with changed AM value = 09/02/2002 @ 11:03 in the morning


Page 318 of 366

232. TimePMString - Determines PM value in
DateTimeToString procedure
232.1. Unit
SysUtils
232.2. Type
Variable
232.3. Description
The TimePMString variable value is used in the DateTimeToString procedure, and the
StrToTime function. It qualifies the afternoon hour value when the ampm formatting string is
used. The formatting determines the position. The default value is 'PM' as set by the locale
settings.
232.4. Syntax
var TimePMString : string
232.5. Example
232.5.1. Name
Show PM as Afternoon
232.5.2. Code
var
myDate : TDateTime;

begin

// format using the default timepmstring value
ShowMessage('Using default PM value = '+formattedDate);

// format using the 'in the afternoon' value
TimePMString := 'in the afternoon';
ShowMessage('with changed PM value = '+formattedDate);
end;
232.5.3. Result
Using default PM value = 09/02/2002 @ 03:03 PM
with changed PM value = 09/02/2002 @ 03:03 in the afternoon


Page 319 of 366

233. TimeSeparator - The character used to separate
display time fields
233.1. Unit
SysUtils
233.2. Type
Variable
233.3. Description
The TimeSeparator variable is used in date and time display functions between hour, minute
and second values. TimeSeparator value is ':' by default, depending on the Windows locale.
233.4. Syntax
var TimeSeparator : char;
233.5. Example
233.5.1. Name
Changing the time display separator character
233.5.2. Code
var
mydate : TDateTime;

begin
myDate := EndOfAMonth(2000, 2); // 29th feb 2000 at 23:59:59.999

LongTimeFormat := 'hh:mm:ss.zzz'; // show milli-seconds

ShowMessage('Date = '+DateTimeToStr(myDate));
TimeSeparator := '_'; // override the : time separator
ShowMessage('Date now = '+DateTimeToStr(myDate));
end;
233.5.3. Result
Date = 29/02/2000 23:59:59.999
Date now = 29/02/2000 23_59_59.999


Page 320 of 366

234. TimeToStr - Converts a TDateTime time value to a
string
234.1. Unit
SysUtils
234.2. Type
Function
234.3. Description
The TimeToStr function converts a TDateTime value Time into a formatted time string. The
time is formatted using the LongTimeFormat value, which in turn uses the TimeSeparator
value.
234.4. Syntax
function TimeToStr(Time : TDateTime) : string;
234.5. Example
234.5.1. Name
Converting a time value to a string
234.5.2. Code
var
myTime : TDateTime;

begin
myTime := StrToTime('15:22:35');
ShowMessage('myTime = '+TimeToStr(myTime));
end;
234.5.3. Result
myTime = 15:22:35


Page 321 of 366

235. To - Prefixes an incremental for loop target value
235.1. Unit
Iris Standard
235.2. Type
Keyword
235.3. Description
The to keyword prefixes the target value Expression in a for loop. The to expression maybe
an Integer, Character or Enumeration type. See the for keyword for full details. The examples
illustrate the three expression types.
235.4. Syntax
for Variable := Integer Expression to Integer Expression do Statement;
235.5. Example
235.5.1. Name
Integer for loop
235.5.2. Code
var
i : Integer;

begin
// loop 5 times
for i := 1 to (10 div 2) do
end;
235.5.3. Result
i = 1
i = 2
i = 3
i = 4
i = 5


Page 322 of 366

236. Tomorrow - Gives the date tomorrow
236.1. Unit
DateUtils
236.2. Type
Function
236.3. Description
The Tomorrow function returns tomorrows date in the local time zone. Because the return
value is a TDateTime type, the time component is set to zero (start of day). The TDateTime
type can be processed by many SysUtil and Dateutils routines.
236.4. Syntax
function Tomorrow : TDateTime;
236.5. Example
236.5.1. Name
Show yesterday, today and tomorrows dates
236.5.2. Code
begin
ShowMessage('Tomorrow = '+DateToStr(Tomorrow));

ShowMessage('Tommorow''s time = '+TimeToStr(Tomorrow));
end;
236.5.3. Result
Today = 29/10/2002
Tomorrow = 30/10/2002
Tomorrow's time = 00:00:00


Page 323 of 366

237. Trim - Removes leading and trailing blanks from a
string
237.1. Unit
SysUtils
237.2. Type
Function
237.3. Description
The Trim function removes blank and control characters (such as line feed) from the start
and end of a string.
237.4. Syntax
function Trim(const Text : string) : string;
237.5. Example
237.5.1. Name
Illustrating Trim, TrimLeft and TrimRight
237.5.2. Code
const
PaddedString = ' Letters ';
begin
ShowMessage('[' + TrimLeft(PaddedString) + ']');
ShowMessage('[' + TrimRight(PaddedString) + ']');
ShowMessage('[' + Trim(PaddedString) + ']');
end;
237.5.3. Result
[Letters ]
[ Letters]
[Letters]


Page 324 of 366

238. TrimLeft - Removes leading blanks from a string
238.1. Unit
SysUtils
238.2. Type
Function
238.3. Description
The TrimLeft function removes blank and control characters (such as line feed) from the start
of a string.
238.4. Syntax
function TrimLeft(const Text : string) : string;
238.5. Example
238.5.1. Name
238.5.2. Code
const
begin
end;
238.5.3. Result
[Letters ]
[ Letters]
[Letters]


Page 325 of 366

239. TrimRight - Removes trailing blanks from a string
239.1. Unit
SysUtils
239.2. Type
Function
239.3. Description
The TrimRight function removes blank and control characters (such as line feed) from the
end of a string.
239.4. Syntax
function TrimRight(const Text : string) : string;
239.5. Example
239.5.1. Name
239.5.2. Code
const
begin
end;
239.5.3. Result
[Letters ]
[ Letters]
[Letters]


Page 326 of 366

240. Trunc - The integer part of a floating point number
240.1. Unit
System
240.2. Type
Function
240.3. Description
The Trunc function returns the integer part of a floating point number. It returns this part as
an Integer value.
240.4. Syntax
function Trunc(const Number : Extended) : Integer;
240.5. Example
240.5.1. Name
A simple example
240.5.2. Code
begin
end;
240.5.3. Result
Round(12.75) = 13
Trunc(12.75) = 12
Int(12.75) = 12
Frac(12.75) = 0.75


Page 327 of 366

241. Try - Starts code that has error trapping
241.1. Unit
Iris Standard
241.2. Type
Keyword
241.3. Description
The try keyword is used to mark the start of a block of statements that have error trapping. if
an error occurs, the program is not terminated. Instead, control is passed to either a finally or
except section. try is used in a number of ways. Version 1 in a try-finally construct, the finally
statement is guaranteed to be executed absolutely regardless of what happens in the try
clause. However, the finally clause does not actually handle any exceptions - the program will
terminate if no except clause is found (see notes below). try-finally is normally used by a
routine to allow cleanup processing to take place, such as freeing resources, with the
exception being correctly passed to the caller to handle. Version 2 in this version, only if the
try clause generates an exception will the except clause be executed. This is used to take
alternative action when something unexpected goes wrong. The except clause cannot
determine the error type however. Version 3 This is similar to version 2, but specifies
different actions for different exception types, such as EInOutError. An else clause can be
used as a catch all for unexpected exception types. The general exception type Exception can
be used to catch all exception types. By assigning a Name to the exception, the message text
of the exception (Name.message) can be obtained for display or other uses. When an
exception is raised in a version 3 setup, if the exception is not acted upon by on or else
statements, then a check is made to see if we are in a nested try block. if so, the except
clause of this parent try is processed. if no on or else clause is found, the program
terminates. The else clause is not really necessary - it is better to use on E:Exception do, the
generic exception handling, since it still provides the error message (E.message). Important :
you can determine the type of error that occured by using the generic exception handling -
on E:Exception do. E is a pointer to the exception object that is created by the exception
condition. E.ClassName gives the exception type, such as 'EDivByZero', as shown in the final
example code.


Page 328 of 366

241.4. Syntax
1 try
Statement
{statement...}
finally
Statement
{statement...}
end;
2 try
Statement
{statement...}
except
Statement
{statement...}
end;
3 try
Statement
{statement...}
except
on {name :} Exception type do Statement
{else statement}
end;
241.5. Example 1
241.5.1. Name
Version 1 : Zero divide with a finally clause
241.5.2. Code
var
begin
number := -1;
try
zero := 0;
finally
if number = -1 then
begin
ShowMessage('Number was not assigned a value - using default');
number := 0;
end;
end;
end;
241.5.3. Result
Number was not assigned a value - using default

then, the program terminates with an EDivByZero error message - the finally clause did
not trap the error.


Page 329 of 366

241.6. Example 2
241.6.1. Name
Version 2 : Zero divide with a plain except block
241.6.2. Code
var
begin
try
zero := 0;
except
ShowMessage('Unknown error encountered');
end;
end;
241.6.3. Result
Unknown error encountered
241.7. Example 3
241.7.1. Name
Version 3 : Divide by zero with an except on clause
241.7.2. Code
var
begin
try
zero := 0;
except
ShowMessage('Error raised...');
end;
end;
241.7.3. Result
Error raised...


Page 330 of 366

242. TStringList - Holds a variable length list of strings
242.1. Unit
Classes
242.2. Type
Type
242.3. Description
TStringList is a utility class type. It is extremely useful for many kinds of list processing. Items
in a string list may be inserted, moved and sorted. The list can be built string by string, or
loaded from a comma separated big string, or even from a text file. TStringList is derived
from TStrings. Whilst you can use TStrings, it is not recommended since it is incomplete -
some of the methods are abstract. TStringList implements these abstract methods (Clear,
Delete and Insert). We'll cover the main properties and methods of TStringList, including
those derived from TStrings - Count property - Returns the number of strings in the list -
Capacity property - set or get the current capacity of the string list. You would manage this
capacity for performance reasons. - Strings property - Get or update the string at a given
index in the list (the first list item has index 0). Note that the Strings property is the default
property. This means that you can use it without specifying its name: myName :=
names.Strings[4]; is equivalent to : myName := names[4]; - Text property - set or get the list
via a big string. This string will have each string terminated with a carriage return and line
feed combination (CRLF). Useful for loading from a visual object that can hold multiple lines
of text. - CommaText property - Get or set the list via a big string. This string will have the
list strings separated by commas. This is useful for loading from a text spreadsheet export.
When getting, if a string contains embedded spaces, it will be enclosed in double quote
marks. - DelimitedText property - Get or set the list via a big string. This string will have the
list strings separated by the Delimiter value (default is a comma). Strings containing
embedded blanks must be enclosed in the QuoteChar (default is "). - QuoteChar property -
Used to enclose strings that have embedded blanks when using DelimitedText. - Delimiter
property - Used to separate strings when using DelimitedText. - Names property - Strings in a
string list can be treated as name/value pairs, as in the second code example. Each string
must have no embedded blanks, and contain an embedded = sign (or whatever the current
NameValueSeparator variable is).This is a very useful concept. See the Value and
ValueFromIndex properties, and the IndexOfName method. - Values property - Returns the
value for a given name when using name/value pair strings (see above). - ValueFromIndex
property - Returns the value by string index (starting at 0) when using name/value pairs. -
CaseSensitive property - When true, Iris treats strings as mixed case when perforing certain
operations, such as Sort. - Duplicates property - This property may have one of the following
TDuplicates enumeration values: dupIgnore Ignore (discard) duplicatesdupAccept Allow
duplicatesdupError Throw exception if duplicates You should of course set this property to the
desired value before adding strings. - Sorted property - When true all strings added will into a
sorted sequence. When false, they are added at the end. See also the Sort method. - Objects
property - Returns the object associated with the string at the given index, if present. - Add
method - Will add the given string to the list, returning its allocated index position (starting
with 0). - Append method - As Add but does not return the index value. - Insert method -
Inserts a string at the given index position. Position 0 will force an insert at the start. - Delete
method - Deletes the string at the given index. - Clear method - Deletes all strings from the
list. - Move method - Moves a string from one index position to another, shifting other strings
around as appropriate. - Exchange method - Swaps two strings in the list, as identified by
their index positions. - IndexOf method - Gets the index position of the first string matching


Page 331 of 366

the given string. or -1 if not found. - IndexOfName method - Gets the index position of the
first name/value pair string where the name matches the given string. or -1 if not found. -
Find method - Same as IndexOf but used with sorted string lists. - Sort method - When
Sorted is false, this will force a sort of the list. - AddStrings method - Adds the strings from
another list into this one. - Assign method - Replaces the current list with the contents of
another list. - LoadFromFile method - Very useful indeed - loads a string list from a text file.
Each text line (as terminated by CRLF - see DelimitedText) becomes a list string. - SaveToFile
method - Will save a string list to a text file.
242.4. Syntax
type TStringList;
242.5. Example 1
242.5.1. Name
A simple example
242.5.2. Code
var
animals : TStringList; // define our string list variable
i : Integer;
begin
// define a string list object, and point our variable at it
animals := TStringList.Create;

// now add some names to our list
animals.Add('Cat');
animals.Add('Mouse');
animals.Add('Giraffe');

// now display these animals
for i := 0 to animals.Count-1 do
ShowMessage(animals[i]); // animals[i] equates to animals.strings[i]
end;
242.5.3. Result
Cat
Mouse
Giraffe


Page 332 of 366

242.6. Example 2
242.6.1. Name
Using name-value strings
242.6.2. Code
var
names : TStringList; // define our string list variable
ageStr : string;
i : Integer;
begin
names := TStringList.Create;

// now add some names to our list
names.CommaText := 'Neil=45, Brian=63, Jim=22';

// and now find brian's age
ageStr := names.Values['Brian'];

// display this value
ShowMessage('Brians age = '+ageStr);

// now display all name and age pair values
for i := 0 to names.Count-1 do
begin
ShowMessage(names.Names[i]+' is '+names.ValueFromIndex[i]);
end;
end;
242.6.3. Result
Brians age is 63
Neil is 45
Brian is 63
Jim is 22


Page 333 of 366

242.7. Example 3
242.7.1. Name
Using DelimitedText, Delimiter
242.7.2. Code
var
cars : TStringList; // define our string list variable
i : Integer;
begin
cars := TStringList.Create;

// now add some cars to our list - using the delimitedtext property
// with overriden control variables
cars.Delimiter := ' '; // each list item will be blank separated
cars.QuoteChar := '|'; // and each item will be quoted with |'s
cars.DelimitedText := '|Honda Jazz| |Ford Mondeo| |Jaguar "E-type"|';

// now display these cars
for i := 0 to cars.Count-1 do
ShowMessage(cars[i]); // cars[i] equates to cars.strings[i]
end;
242.7.3. Result
Honda Jazz
Ford Mondeo
Jaguar "E-type"


Page 334 of 366

243. TwoDigitYearCenturyWindow - Sets the century
threshold for 2 digit years
243.1. Unit
SysUtils
243.2. Type
Variable
243.3. Description
The TwoDigitYearCenturyWindow variable is used when converting 2 digit year date strings to
TDateTime values. The TwoDigitYearCenturyWindow value is subtracted from the current
date to set the conversion threshold. for example : TwoDigitYearCenturyWindow : 50
(default)Current year last : 2002Threshold is then set : 1952100 year window becomes :
1952 - 2051 When converting a 2 digit string year, such as 75, the 2 digits are compared to
the threshold last two digits. if greater, then the date is in the lower century, for example
1975. if lower than the threshold, the date is in the higher century. for example, 44 would
give 2044.
243.4. Syntax
var TwoDigitYearCenturyWindow : Word;
243.5. Example
243.5.1. Name
Move the threshold to see how a conversion is affected
243.5.2. Code
var
myDate : TDateTime;

begin
// set up a date from a 2 digit year using the default threshold
ShowMessage('09/05/30 using default threshold = '+DateToStr(myDate));

// now change the default threshold to 80 :
// 2002 (at time of writing) - 80 gives 1922
// 30 is above 22, so 1900 century is chosen
TwoDigitYearCenturyWindow := 80;
ShowMessage('09/05/30 using override threshold = '+DateToStr(myDate));
end;
243.5.3. Result
09/05/30 using default threshold = 09/05/2030
09/05/30 using override threshold = 09/05/1930


Page 335 of 366

244. Unit - Defines the start of a script file
244.1. Unit
Iris Standard
244.2. Type
Keyword
244.3. Description
The unit keyword is fundamental, because it defines the start of the scripts. Each script file is
stored in a Name.pas file, where Name must match the Screen Name of Name.dfm. Each
script file comprises a set of interface definitions. These interface definitions defines data,
types and routine declarations. Any routines defined in the interface must be implemented in
the implementation section. All function and procedure definitions must have exactly
redefined arguments.
244.4. Syntax
unit Name;
interface
...
implementation
...
end. // note terminating dot


Page 336 of 366

244.5. Example
244.5.1. Name
A simple example
244.5.2. Code
// -----------------------------------------------------------
// -----------------------------------------------------------



end;




{$r *.dfm}

loaded
var
UserName string;
begin
repeat



Page 337 of 366

length
characters?');
ShowDifference;
end;

begin
end;

begin
end;

begin
from this page
end;

begin
end;

end.
244.5.3. Result

It is now 12:34:56




Page 338 of 366

245. Until - Ends a repeat control loop
245.1. Unit
Iris Standard
245.2. Type
Keyword
245.3. Description
The until keyword ends a control loop that is always executed at least once, and which
terminates when the Expression is satisfied (returns True). There is no need for begin or end
markers - the repeat and until keywords serve that purpose. It is used when it is important
that the statements are at least executed once.
245.4. Syntax
repeat
Statement1;
{statement2;
...}
until Expression


Page 339 of 366

245.5. Example
245.5.1. Name
Display integer squares until we reach or exceed 100
245.5.2. Code
var

begin
num := 1;

repeat

Inc(num);

until sqrNum > 100;
end;
245.5.3. Result
1 squared = 1
2 squared = 4
3 squared = 9
4 squared = 16
5 squared = 25
6 squared = 36
7 squared = 49
8 squared = 64
9 squared = 81
10 squared = 100


Page 340 of 366

246. UpperCase - Change lower case characters in a
string to upper case
246.1. Unit
SysUtils
246.2. Type
Function
246.3. Description
The UpperCase function creates a copy of MixedString with all letters converted to upper
case.
246.4. Syntax
function UpperCase(const MixedString : string) : string;
246.5. Example
246.5.1. Name
Converting a mixed case string to upper case
246.5.2. Code
var

begin
SimpleString := AnsiUpperCase('The Cat Sat on The MAT');
end;
246.5.3. Result
SimpleString : THE CAT SAT on THE MAT


Page 341 of 366

247. Uses - Declares a list of Units to be imported
247.1. Unit
Iris Standard
247.2. Type
Keyword
247.3. Description
The uses keyword defines a list of one or more units that are used by the current unit,
program or library. Each unit is effectively imported - all public or published routines and data
in each unit is made available. for example, including SysUtils makes available a lot of data
manipulation routines, such as IntToStr. The order of the units in the list is important. Those
later in the list take precedence over the earlier ones. in the rare situation where the same
routine or data is defined in two or more units, you can force Iris to use the desired unit by
prefixing that unit name to the routine or data name.
247.4. Syntax
uses Test {unit2, ...};


Page 342 of 366

247.5. Example
247.5.1. Name
A simple example
247.5.2. Code
// -----------------------------------------------------------
// -----------------------------------------------------------



end;




{$r *.dfm}

loaded
var
UserName string;
begin
repeat



Page 343 of 366

length
characters?');
ShowDifference;
end;

begin
end;

begin
end;

begin
from this page
end;

begin
end;

end.
247.5.3. Result

It is now 12:34:56




Page 344 of 366

248. Var - Starts the definition of a section of data
variables
248.1. Unit
Iris Standard
248.2. Type
Keyword
248.3. Description
The var keyword is used to start a section of variable definitions. The section is terminated by
the next keyword in a program. Within the section, one or more variables may be defined.
These can be of any data type. 1. Variables within a function, procedure or unit These are
defined with a given type, such as string or Integer. 2. Variable routine parameters When
passing data to a routine (function or procedure), you can prefix the parameter definition
with var if the variable itself is to be updated by the routine. This allows a caller to pass data
to a routine that will be enriched by the routine.
248.4. Syntax
1 var Name1 : type;
2 Name (var Var1 : type);


Page 345 of 366

248.5. Example
248.5.1. Name
Defining local and parameter variables
248.5.2. Code
// procedure updatecounts(count1: integer; var count2: integer);

var // local variables
apples, bananas : Integer;
begin
// initialise our fruit counts
apples := 1;
bananas := 1;

// show their initial values
ShowMessage('Apples = '+IntToStr(apples));
ShowMessage('Bananas = '+IntToStr(bananas));
ShowMessage('');

// increment them in the updatecounts routine
UpdateCounts(apples, bananas);

// show their new values - only bananas will be updated
ShowMessage('Apples = '+IntToStr(apples));
ShowMessage('Bananas = '+IntToStr(bananas));
end;

// a procedure to increment the passed parameter values
procedure TUntitled.UpdateCounts(count1: Integer; var count2: Integer);
begin
// increment both passed parameter values
Inc(count1);
Inc(count2);
end;
248.5.3. Result
Apples = 1
Bananas = 1

Apples = 1
Bananas = 2


Page 346 of 366

249. Variant - A variable type that can hold changing data
types
249.1. Unit
System
249.2. Type
Type
249.3. Description
The Variant data type provides a flexible general purpose data type.
249.4. Syntax
type Variant;
249.5. Example
249.5.1. Name
Illustrating a few Variant assignments and the resulting data types
249.5.2. Code
var
myVar : Variant;

begin
// assign various values to a variant
// and then show the result
myVar := 15;
ShowMessage('Variant integer value = '+IntToStr(MyVar));
myVar := 12.34;
ShowMessage('Variant float value = '+FloatToStr(MyVar));
myVar := 'abc';
ShowMessage('Variant string value = '+MyVar);
end;
249.5.3. Result
Variant integer value = 15
Variant float value = 12.34
Variant string value = abc


Page 347 of 366

250. VarType - Gives the current type of a Variant
variable
250.1. Unit
Variants
250.2. Type
Function
250.3. Description
The VarType function returns an integer representing the current data type for a Variant
variable VariantVariable. Use VarTypeMask to filter out the meta part when looking for the
basic data type of a Variant.
250.4. Syntax
function VarType(const VariantVariable : Variant) : Integer;


Page 348 of 366

250.5. Example
250.5.1. Name
Illustrating a few Variant types
250.5.2. Code
// procedure showbasicvarianttype(varvar: variant);

var
myVar : Variant;

begin
// and then show the resulting variant type
ShowMessage('Variant value = not yet set');
ShowBasicVariantType(myVar);

// simple value
myVar := 123;
ShowMessage('Variant value = 123');

// calculated value using a variant and a constant
myVar := myVar + 456;
ShowMessage('Variant value = 123 + 456');

myVar := 'string '+IntToStr(myVar);
ShowMessage('Variant value = string 579');
end;

// show the type of a variant
procedure TUntitled.ShowBasicVariantType(varVar: Variant);
var
typeString : string;
basicType : Integer;

begin
// get the variant basic type :
// this means excluding array or indirection modifiers
basicType := VarType(varVar) and VarTypeMask;

// set a string to match the type
case basicType of
varEmpty : typeString := 'varEmpty';
varNull : typeString := 'varNull';
varSmallInt : typeString := 'varSmallInt';
varInteger : typeString := 'varInteger';
varSingle : typeString := 'varSingle';
varDouble : typeString := 'varDouble';
varCurrency : typeString := 'varCurrency';
varDate : typeString := 'varDate';
varOleStr : typeString := 'varOleStr';
varBoolean : typeString := 'varBoolean';


Page 349 of 366

varVariant : typeString := 'varVariant';
varUnknown : typeString := 'varUnknown';
varByte : typeString := 'varByte';
varWord : typeString := 'varWord';
varLongWord : typeString := 'varLongWord';
varAny : typeString := 'varAny';
varTypeMask : typeString := 'varTypeMask';
end;

// show the variant type
ShowMessage('Variant type is '+typeString);
end;
250.5.3. Result
Variant value = not yet set
Variant type = varEmpty
Variant value = 123
Variant type = varInteger
Variant value = 123 + 456
Variant value = string 579
Variant type = varOleStr


Page 350 of 366

251. VarTypeMask - Mask for the meta-type part of a
Variant variable
251.1. Unit
Variants
251.2. Type
Constant
251.3. Description
The VarTypeMask constant provides a mask for use with the VarType function. It allows the
meta-type part of a Variant to be excluded when checking for the basic data type of a
Variant.
251.4. Syntax
const VarTypeMask = $0FFF;


Page 351 of 366

251.5. Example
251.5.1. Name
Illustrating a few Variant types using VarTypeMask
251.5.2. Code
// procedure showbasicvarianttype(varvar: variant);

var
myVar : Variant;

begin
// and then show the resulting variant type
ShowMessage('Variant value = not yet set');

// simple value
myVar := 123;
ShowMessage('Variant value = 123');

// calculated value using a variant and a constant
myVar := myVar + 456;
ShowMessage('Variant value = 123 + 456');

myVar := 'string '+IntToStr(myVar);
ShowMessage('Variant value = string 579');
end;

// show the type of a variant
procedure TUntitled.ShowBasicVariantType(varVar: Variant);
var
typeString : string;
basicType : Integer;

begin
// get the variant basic type :
// this means excluding array or indirection modifiers
basicType := VarType(varVar) and VarTypeMask;

// set a string to match the type
case basicType of
varEmpty : typeString := 'varEmpty';
varNull : typeString := 'varNull';
varSmallInt : typeString := 'varSmallInt';
varInteger : typeString := 'varInteger';
varSingle : typeString := 'varSingle';
varDouble : typeString := 'varDouble';
varCurrency : typeString := 'varCurrency';
varDate : typeString := 'varDate';
varOleStr : typeString := 'varOleStr';
varBoolean : typeString := 'varBoolean';


Page 352 of 366

varVariant : typeString := 'varVariant';
varUnknown : typeString := 'varUnknown';
varByte : typeString := 'varByte';
varWord : typeString := 'varWord';
varLongWord : typeString := 'varLongWord';
varAny : typeString := 'varAny';
varTypeMask : typeString := 'varTypeMask';
end;

// show the variant type
ShowMessage('Variant type is '+typeString);
end;
251.5.3. Result
Variant value = not yet set
Variant type = varEmpty
Variant value = 123
Variant value = 123 + 456
Variant value = string 579
Variant type = varOleStr


Page 353 of 366

252. While - repeat statements whilst a continuation
condition is met
252.1. Unit
Iris Standard
252.2. Type
Keyword
252.3. Description
The while keyword starts a control loop that is executed as long as the Expression is satisfied
(returns True). The loop is not executed at all if the expression is false at the start. You need
begin or end markers if multiple statements are required in the loop. It is used when it is
important that the statements are at only executed when necessary.
252.4. Syntax
while Expression do Statement;


Page 354 of 366

252.5. Example
252.5.1. Name
Display integer squares until we reach 100
252.5.2. Code
var

begin
num := 1;

while sqrNum <= 100 do
begin

Inc(num);

end;
end;
252.5.3. Result
1 squared = 1
2 squared = 4
3 squared = 9
4 squared = 16
5 squared = 25
6 squared = 36
7 squared = 49
8 squared = 64
9 squared = 81
10 squared = 100


Page 355 of 366

253. WideString - A data type that holds a string of
WideChars
253.1. Unit
System
253.2. Type
Type
253.3. Description
The WideString data type is used to hold sequences of International characters, like
sentences. Each character is a WideChar, guaranteed to be 16 bits in size. WideChar types
provide support for multi-byte International character sets such as Chinese, which have vast
numbers of characters (idiograms) in their character sets. Unlike ShortStrings, WideStrings
are pointer referenced variables (for Windows - for Linux, they are not). Storage is allocated
for an AnsiString only when needed. for example, assigning the value of one AnsiString to
another does not allocate storage for a copy of the first string. Instead, the reference count
of the first string is incremented, and the second AnsiString set to point to it. But when the
second string is changed, new storage is obtained for this new string, and the reference
count for the first string is decremented. When a string is no longer referenced (the last
AnsiString referrer is set to nil), it is discarded. This is an example of Iris managing storage
on your behalf. WideStrings can be assigned from other strings, from functions that return a
string, and with concatenations as in the sample code. When assigning to a 'narrow' string,
such as an AnsiString, the double to single byte conversion can have unpredictable results.
Use with care. Converting from AnsiString to WideString is trouble free.
253.4. Syntax
type WideString;


Page 356 of 366

253.5. Example
253.5.1. Name
Assign to two WideStrings and manipulate these
253.5.2. Code
var
string1, string2 : WideString;
begin
// assign a famous sentence to the first string
string1 := 'Hello World';

// assign to the second string
// this simply points string2 at string1
// the 'hello world' string storage has a reference count of 2
string2 := string1;

// add to the second string
// this disassociates from string1 - new string storage is
// created to hold the string2 value
string2 := string2 + ', how is everyone?';

// and finally, set the length of the first string to 5
SetLength(string1, 5);

// display both strings
end;
253.5.3. Result
String1 = Hello
String2 = Hello World, how is everyone?


Page 357 of 366

254. Word - An integer type supporting values 0 to 65535
254.1. Unit
System
254.2. Type
Type
254.3. Description
The Word type is an integer holding positive values up to 65535. It occupies 16 bits of
storage. The SmallInt type is the equivalent 16 bit type for signed integers (-32768 to
32767).
254.4. Syntax
type Word = 0..65535;
254.5. Example
254.5.1. Name
Showing maximum and minimum Word values
254.5.2. Code
var
A, B : Word;
begin
A := 0;
B := 65535;
end;
254.5.3. Result
A = 0 and B = 65535
A + B = 65535


Page 358 of 366

255. WriteLn - write a complete line of data to a text file
255.1. Unit
System
255.2. Type
Procedure
255.3. Description
The WriteLn procedure writes a complete line of data to a text file or to the console. Is used
to write a line of text to a text file with the given FileHandle. You must use AssignFile to
assign a file to the FileHandle and open the file with Reset or ReWrite before using WriteLn.
The text written may be any valid Expression(s). Often these will be strings, but may also be
expressions that result in strings or numbers.
255.4. Syntax
procedure WriteLn (var FileHandle : TextFile; Expression1 {options} {, expression2
{options} ...}) ;


Page 359 of 366

255.5. Example
255.5.1. Name
Illustrating single, multiple and formatted text line writing
255.5.2. Code
var
myFile : TextFile;
text : string;

begin
ReWrite(myFile);


// write a blank line
WriteLn(myFile);

// write a string and a number to the file
WriteLn(myFile, '22/7 = ' , 22/7);

// close the file
CloseFile(myFile);

Reset(myFile);

begin
ShowMessage(text);
end;

CloseFile(myFile);
end;
255.5.3. Result
Hello World

22/7 = 3.14285714285714


Page 360 of 366

256. WriteRecipe - write a recipe file.
256.1. Unit
Iris Standard
256.2. Type
Recipes
256.3. Description
write values from a recipe tag structure into a recipe file.
256.4. Syntax
procedure WriteRecipe(RecipeName, FileName: string);
256.5. Example
256.5.1. Name
write a recipe file.
256.5.2. Code
begin
// load the recipe file 'coffee.rcp' into the recipe tag 'myrecipe'
ReadRecipe('MyRecipe', 'Coffee.rcp');

// save the recipe tag 'myrecipe' into the recipe file 'tea.rcp'
WriteRecipe('MyRecipe', 'Tea.rcp');
end;
256.5.3. Result
The recipe file coffee is loaded into the recipe tag MyRecipe
The recipe tag MyRecipe is stored into the recipe file Tea


Page 361 of 366

257. WriteTagValue - Writes a value of a tag
257.1. Unit
Iris Standard
257.2. Type
Tag Function
257.3. Description
Writes a value to a tag, regardless of the current value of the tag. It is possible to read values
from device and internal tags.
257.4. Syntax
function WriteTagValue(TagName: string; Value: Variant): boolean;
257.5. Example 1
257.5.1. Name
read/write a tag value
257.5.2. Code
var
value: integer;

begin


WriteTagValue('tagname',Inc(value));


end;
257.5.3. Result
The old value is ?
The new value is ?


Page 362 of 366

257.6. Example 2
257.6.1. Name
read/write a tag value through a PowerTree
257.6.2. Code
var
value: integer;

begin


WriteTagValue(ExpandMailbox('[PowerTree].name'),Inc(value));


end;
257.6.3. Result
The old value is ?
The new value is ?


Page 363 of 366

257.7. Example 3
257.7.1. Name
read/write a structured tag value
257.7.2. Code
var
value: integer;

begin


// write a new value to the tag 'unit1.equipmentmodule2'
WriteTagValue('Unit1.EquipmentModule2',Inc(value));


end;
257.7.3. Result
The old value is ?
The new value is ?


Page 364 of 366

258. Xor - Boolean xor or bitwise xor of two arguments
258.1. Unit
Iris Standard
258.2. Type
Keyword
258.3. Description
The xor keyword is used in two different ways: 1. to perform a logical or boolean 'Exclusive-
or' of two logical values. if they are different, then the result is true. 2. to perform a
mathematical 'Exclusive-or' of two integers. The result is a bitwise 'Exclusive-or' of the two
numbers. for example: 10110001 xor 01100110 = 11010111
258.4. Syntax
1 Boolean expression xor Boolean expression
2 Integer expression xor Integer expression
258.5. Example
258.5.1. Name
Illustrate both types of xor usage
258.5.2. Code
var
letter : Char;

begin
num1 := $25; // binary value : 0010 0101 $25
num2 := $32; // binary value : 0011 0010 $32
// xor'ed value : 0001 0111 = $17
letter := 'G';

if (num1 > 0) xor (letter = 'G')
then ShowMessage('Only one of the values is true')
else ShowMessage('Both values are true or false');

// and used to perform a mathematical xor operation
num3 := num1 xor num2;

ShowMessageFmt('$25 xor $32 = $%x',[num3]);
end;
258.5.3. Result
Both values are true or false
$25 xor $32 = $17


Page 365 of 366

259. Yesterday - Gives the date yesterday
259.1. Unit
DateUtils
259.2. Type
Function
259.3. Description
The Yesterday function returns yesterdays date in the local time zone. Because the return
value is a TDateTime type, the time component is set to zero. The TDateTime type can be
processed by many SysUtil and Dateutils routines (start of day).
259.4. Syntax
function Yesterday : TDateTime;
259.5. Example
259.5.1. Name
Show yesterday, today and tomorrows dates
259.5.2. Code
begin
ShowMessage('Tomorrow = '+DateToStr(tomorrow));

ShowMessage('Yesterday''s time = '+TimeToStr(Yesterday));
end;
259.5.3. Result
Today = 29/10/2002
Tomorrow = 30/10/2002
Yesterday's time = 00:00:00

Iris Script

Uploaded by

Copyright:

Available Formats

Iris Script

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Iris Script

Uploaded by

Copyright:

Available Formats

Script Language Reference

You might also like