DISCLAIMERTHIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTSWERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATIONCONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED “AS IS”WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED,LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THEIMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BERESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT,CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION.NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THISDOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

COPYRIGHTUnder the copyright laws, neither the documentation nor the software may be copied, photocopied,reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Lotus Development Corporation, except in the mannerdescribed in the documentation or the applicable licensing agreement governing the use of thesoftware.

© Copyright 1985 – 1999 Lotus Development Corporation55 Cambridge ParkwayCambridge, MA 02142

All rights reserved. Printed in the United States.

LIST OF TRADEMARKS Domino, cc:Mail, Notes, NotesBench, NotesFlow, and Notes/FX are trademarks and Freelance,Freelance Graphics, Lotus, Lotus Components, Lotus Notes, LotusScript, Notes Mail, NotesSQL,NotesView, 1-2-3, Organizer, SmartIcons, and SmartSuite are registered trademarks of LotusDevelopment Corporation. AS/400, OS/2 Warp, RS/6000, and PowerPC are trademarks and AIX,IBM, OS/2, Presentation Manager, and SNA are registered trademarks of International BusinessMachines Corporation. Tivoli/Courier is a trademark of Tivoli Systems Inc., a wholly ownedsubsidiary of International Business Machines Corporation. All other trademarks are the property oftheir respective owners.

Preface . . . . . . . . . . . . . . . . . . . xxxvii

Volume I1 Programming Overview . . . . 1. . .Programming in Domino . . . . . . . . . . . . 1. . . .

Where to use scripts and formulas . . . . . 1. . . .

Table of Domino Objects . . . . . . . . . . . . . 3. . . .

SmartIcons . . . . . . . . . . . . . . . . . . . . . . . . 5. . . .

Replication formulas . . . . . . . . . . . . . . . . 6. . . .

Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. . . .

Actions . . . . . . . . . . . . . . . . . . . . . . . . . . 10. . .

Hotspots . . . . . . . . . . . . . . . . . . . . . . . . . 12. . .

Form, selection, and column formulas . . . 15. . .

Form formulas . . . . . . . . . . . . . . . . . . 15. . .

Selection formulas . . . . . . . . . . . . . . . . 15. . .

Column formulas . . . . . . . . . . . . . . . . 16. . .

Window title, section access, and insertsubform formulas . . . . . . . . . . . . . . 17. . .

Window title formulas . . . . . . . . . . . . 17. . .

Section access formulas . . . . . . . . . . . . 18. . .

Insert subform formulas . . . . . . . . . . . 18. . .

Section title and hidden paragraph formulas . . . . . . . . . . . . 19. . .

Section title formulas . . . . . . . . . . . . . 19. . .

Hidden paragraph formulas . . . . . . . . 19. . .

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 19. . .

Field design formulas . . . . . . . . . . . . . . . 22. . .

Default value formulas . . . . . . . . . . . . 23. . .

Input translation formulas . . . . . . . . . 23. . .

Input validation formulas . . . . . . . . . . 23. . .

Value formulas for a computed fields . 24. . .

Keyword field formulas . . . . . . . . . . . 24. . .

Event descriptions . . . . . . . . . . . . . . . . . . 25. . .

Event sequencing . . . . . . . . . . . . . . . . . . . 29. . .

2 User Interface . . . . . . . . . . . . 33. .Exploring the Programmer’s pane . . . . . . 33. . .

Exploring the Java interface in theProgrammer’s pane . . . . . . . . . . . . 35. . .

Accessing the Programmer’s pane . . . 36. . .

Using the Info List . . . . . . . . . . . . . . . . . . 37. . .

Using the Objects tab . . . . . . . . . . . . . . . . 37. . .

Programming an object’s propertiesand events . . . . . . . . . . . . . . . . . . . 37. . .

Using the Reference tab . . . . . . . . . . . . . . 38. . .

Pasting information from the Referencetab into the Script area . . . . . . . . . . 38. . .

Using short-cut keys to access theReference tab . . . . . . . . . . . . . . . . . 39. . .

Using the Errors box . . . . . . . . . . . . . . . . 39. . .

Using the Script area . . . . . . . . . . . . . . . . 39. . .

Setting text properties . . . . . . . . . . . . . 40. . .

Moving the insertion point whileediting text in the Script area . . . . . 40. . .

Selecting text . . . . . . . . . . . . . . . . . . . . 41. . .

Editing text with key combinations . . 42. . .

Editing text with menu commands . . . 42. . .

Saving and deleting text in the Script area . . . . . . . . . . . . . . . . . . . 42. . .

Renaming an object, subprogram, or class . . . . . . . . . . . . . . . . . . . . . . 43. . .

Writing Java in an agent . . . . . . . . . . . . . 43. . .

Compiling Java . . . . . . . . . . . . . . . . . . 44. . .

Importing Java into the Programmer’s pane . . . . . . . . . . . . 44. . .

iii

Contents

Using AgentRunner . . . . . . . . . . . . . . . . . 45. . .

Creating a project for AgentRunner . . 45. . .

Generating an AgentContext document 46. . .

Debugging a Java agent withAgentRunner . . . . . . . . . . . . . . . . . 46. . .

Writing JavaScript in the Programmer’s pane . . . . . . . . . . . . 47. . .

Writing JavaScript in a page header . . 48. . .

Compiling JavaScript . . . . . . . . . . . . . 48. . .

Writing LotusScript in the Programmer’s pane . . . . . . . . . . . . 48. . .

Defining global variables and subprograms . . . . . . . . . . . . . . 48. . .

Create an additional script in LotusScript . . . . . . . . . . . . . . . . . 49. . .

Completing a LotusScript blockstatement automatically . . . . . . . . . 50. . .

Completing a LotusScript %directive automatically . . . . . . . . 50. . .

Compiling LotusScript . . . . . . . . . . . . 50. . .

Exploring the LotusScript Debugger . . . . 51. . .

Using the LotusScript Debugger . . . . . 52. . .

Selecting a subprogram . . . . . . . . . . . 53. . .

Stepping through a script . . . . . . . . . . 53. . .

Debugging with breakpoints . . . . . . . 54. . .

Using the debugger utilities . . . . . . . . . . 55. . .

Using Script Libraries . . . . . . . . . . . . . . . 56. . .

Using LotusScript in a Script Library . 56. . .

Using Java in a Script Library . . . . . . . 57. . .

Writing formulas in the Programmer’s pane . . . . . . . . . . . . 58. . .

Using the formula window . . . . . . . . . 58. . .

Using the Programmer’s pane for Simple action(s) . . . . . . . . . . . . . . . 59. . .

3 Formula Language Rules . . . 61. .Using the syntax rules . . . . . . . . . . . . . . . 61. . .

Lexical elements . . . . . . . . . . . . . . . . . 61. . .

General syntax rules . . . . . . . . . . . . . . 62. . .

Using variables . . . . . . . . . . . . . . . . . . . . 63. . .

Fields . . . . . . . . . . . . . . . . . . . . . . . . . 63. . .

Temporary variables . . . . . . . . . . . . . . 65. . .

Using constants . . . . . . . . . . . . . . . . . . . . 66. . .

Text constants . . . . . . . . . . . . . . . . . . . 66. . .

Numeric constants . . . . . . . . . . . . . . . 67. . .

Time-date constants . . . . . . . . . . . . . . 67. . .

Using operators . . . . . . . . . . . . . . . . . . . . 68. . .

Operator overview and precedence . . 69. . .

Order of evaluation for operations . . . 70. . .

Assignment operator . . . . . . . . . . . . . 70. . .

List operator . . . . . . . . . . . . . . . . . . . . 70. . .

Unary operators . . . . . . . . . . . . . . . . . 71. . .

Arithmetic operators . . . . . . . . . . . . . . 71. . .

Text operator . . . . . . . . . . . . . . . . . . . 71. . .

Comparison operators . . . . . . . . . . . . 72. . .

Logical operators . . . . . . . . . . . . . . . . 72. . .

Operations on lists . . . . . . . . . . . . . . . 72. . .

Using @functions . . . . . . . . . . . . . . . . . . . 75. . .

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 75. . .

Return value . . . . . . . . . . . . . . . . . . . . 76. . .

Side-effects . . . . . . . . . . . . . . . . . . . . . 76. . .

@Commands . . . . . . . . . . . . . . . . . . . . 77. . .

Order of evaluation for formula statements . . . . . . . . . . . . 77. . .

Using keywords . . . . . . . . . . . . . . . . . . . 79. . .

Specifying form and view names in formulas . . . . . . . . . . . . . . . . . . . 81. . .

Debugging formulas . . . . . . . . . . . . . . . . 81. . .

4 Formula Language Coding Guidelines . . . . . . . . . . . 83. .Formulas . . . . . . . . . . . . . . . . . . . . . . . . . 83. . .

Writing formulas that evaluate to a result . . . . . . . . . . . . . . . . . . . . . . 84. . .

Writing formulas that perform actions 85. . .

Working with lists . . . . . . . . . . . . . . . 86. . .

iv Domino Designer Programming Guide

Using conditional statements . . . . . . . 90. . .

Writing messages and getting user input . . . . . . . . . . . . . . . . . . . . 92. . .

Handling errors . . . . . . . . . . . . . . . . . 98. . .

Working with @functions . . . . . . . . . . 101. . .

Working with @commands . . . . . . . . . 103. . .

Performing string operations . . . . . . . . . . 104. . .

Concatenating, comparing, anddetermining length . . . . . . . . . . . . 106. . .

Locating and extracting substrings . . . 109. . .

Trimming, repeating, adding a newline, and changing case . . . . . . . . . 112. . .

Performing arithmetic operations . . . . . . 113. . .

Performing time-date operations . . . . . . . 118. . .

Accessing the user environment . . . . . . . 120. . .

Accessing the current database and view 122. . .

Accessing the current document in theformula language . . . . . . . . . . . . . . 125. . .

Accessing data outside the currentdocument and database . . . . . . . . . 128. . .

Accessing external databases throughODBC using @functions . . . . . . . . . 131. . .

5 Formula Language@Functions A–Z . . . . . . . . . . . . 133.Where does this @function work?

(Part 1 A–D) . . . . . . . . . . . . . . . . . . 133. . .

Where does this @function work? (Part 1 E–K) . . . . . . . . . . . . . . . . . . 136. . .

Where does this @function work? (Part 1 L–R) . . . . . . . . . . . . . . . . . . 138. . .

Where does this @function work? (Part 1 S–Z) . . . . . . . . . . . . . . . . . . 141. . .

Where does this @function work? (Part 2 A–D) . . . . . . . . . . . . . . . . . . 143. . .

Where does this @function work? (Part 2 E–K) . . . . . . . . . . . . . . . . . . 146. . .

Where does this @function work? (Part 2 L–R) . . . . . . . . . . . . . . . . . . 148. . .

Where does this @function work? (Part 2 S–Z) . . . . . . . . . . . . . . . . . . 151. . .

@Functions with ECL security . . . . . . . . . 153. . .

@Abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154. . .

@Abstract . . . . . . . . . . . . . . . . . . . . . . . . . 155. . .

@Accessed . . . . . . . . . . . . . . . . . . . . . . . . 162. . .

@Acos . . . . . . . . . . . . . . . . . . . . . . . . . . . 164. . .

@AddToFolder . . . . . . . . . . . . . . . . . . . . 164. . .

@Adjust . . . . . . . . . . . . . . . . . . . . . . . . . . 165. . .

@All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167. . .

@AllChildren . . . . . . . . . . . . . . . . . . . . . . 167. . .

@AllDescendants . . . . . . . . . . . . . . . . . . . 168. . .

@Ascii . . . . . . . . . . . . . . . . . . . . . . . . . . . 171. . .

@Asin . . . . . . . . . . . . . . . . . . . . . . . . . . . 172. . .

@Atan . . . . . . . . . . . . . . . . . . . . . . . . . . . 173. . .

@Atan2 . . . . . . . . . . . . . . . . . . . . . . . . . . 174. . .

@AttachmentLengths . . . . . . . . . . . . . . . . 175. . .

@AttachmentNames . . . . . . . . . . . . . . . . 176. . .

@Attachments . . . . . . . . . . . . . . . . . . . . . 176. . .

@Author . . . . . . . . . . . . . . . . . . . . . . . . . 177. . .

@Begins . . . . . . . . . . . . . . . . . . . . . . . . . . 178. . .

@BrowserInfo . . . . . . . . . . . . . . . . . . . . . 179. . .

@Certificate . . . . . . . . . . . . . . . . . . . . . . . 181. . .

@Char . . . . . . . . . . . . . . . . . . . . . . . . . . . 182. . .

@CheckAlarms . . . . . . . . . . . . . . . . . . . . 183. . .

@ClientType . . . . . . . . . . . . . . . . . . . . . . 184. . .

@Command . . . . . . . . . . . . . . . . . . . . . . . 184. . .

@Contains . . . . . . . . . . . . . . . . . . . . . . . . 186. . .

@Cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186. . .

@Created . . . . . . . . . . . . . . . . . . . . . . . . . 187. . .

@Date . . . . . . . . . . . . . . . . . . . . . . . . . . . 188. . .

@Day . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190. . .

@DbColumn (Notes databases) . . . . . . . . 190. . .

@DbColumn (ODBC) . . . . . . . . . . . . . . . . 195. . .

@DbCommand (ODBC) . . . . . . . . . . . . . . 201. . .

@DbExists . . . . . . . . . . . . . . . . . . . . . . . . 206. . .

@DbLookup (Notes databases) . . . . . . . . 207. . .

v

@DbLookup (ODBC) . . . . . . . . . . . . . . . . 214. . .

@DbManager . . . . . . . . . . . . . . . . . . . . . . 220. . .

@DbName . . . . . . . . . . . . . . . . . . . . . . . . 221. . .

@DbTitle . . . . . . . . . . . . . . . . . . . . . . . . . 222. . .

@DDEExecute . . . . . . . . . . . . . . . . . . . . . 223. . .

@DDEInitiate . . . . . . . . . . . . . . . . . . . . . . 225. . .

@DDEPoke . . . . . . . . . . . . . . . . . . . . . . . 227. . .

@DDETerminate . . . . . . . . . . . . . . . . . . . 228. . .

DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . 229. . .

@DeleteDocument . . . . . . . . . . . . . . . . . . 229. . .

@DeleteField . . . . . . . . . . . . . . . . . . . . . . 230. . .

@DialogBox . . . . . . . . . . . . . . . . . . . . . . . 230. . .

@Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233. . .

@DocChildren . . . . . . . . . . . . . . . . . . . . . 234. . .

@DocDescendants . . . . . . . . . . . . . . . . . . 236. . .

@DocFields . . . . . . . . . . . . . . . . . . . . . . . 238. . .

@DocLength . . . . . . . . . . . . . . . . . . . . . . 238. . .

@DocLevel . . . . . . . . . . . . . . . . . . . . . . . . 239. . .

@DocMark . . . . . . . . . . . . . . . . . . . . . . . . 240. . .

@DocNumber . . . . . . . . . . . . . . . . . . . . . 240. . .

@DocParentNumber . . . . . . . . . . . . . . . . 241. . .

@DocSiblings . . . . . . . . . . . . . . . . . . . . . . 242. . .

@DocumentUniqueID . . . . . . . . . . . . . . . 243. . .

@Domain . . . . . . . . . . . . . . . . . . . . . . . . . 246. . .

@EditECL . . . . . . . . . . . . . . . . . . . . . . . . 246. . .

@EditUserECL . . . . . . . . . . . . . . . . . . . . . 247. . .

@Elements . . . . . . . . . . . . . . . . . . . . . . . . 247. . .

@EnableAlarms . . . . . . . . . . . . . . . . . . . . 248. . .

@Ends . . . . . . . . . . . . . . . . . . . . . . . . . . . 248. . .

ENVIRONMENT . . . . . . . . . . . . . . . . . . . 249. . .

@Environment . . . . . . . . . . . . . . . . . . . . . 250. . .

@Error . . . . . . . . . . . . . . . . . . . . . . . . . . . 253. . .

@Exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254. . .

@Explode . . . . . . . . . . . . . . . . . . . . . . . . . 254. . .

@Failure . . . . . . . . . . . . . . . . . . . . . . . . . . 257. . .

@False . . . . . . . . . . . . . . . . . . . . . . . . . . . 257. . .

FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . 258. . .

@Fontlist . . . . . . . . . . . . . . . . . . . . . . . . . 259. . .

@GetDocField . . . . . . . . . . . . . . . . . . . . . 259. . .

@GetPortsList . . . . . . . . . . . . . . . . . . . . . 260. . .

@GetProfileField . . . . . . . . . . . . . . . . . . . 261. . .

@Hour . . . . . . . . . . . . . . . . . . . . . . . . . . . 262. . .

@If . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263. . .

@Implode . . . . . . . . . . . . . . . . . . . . . . . . 265. . .

@InheritedDocumentUniqueID . . . . . . . . 266. . .

@Integer . . . . . . . . . . . . . . . . . . . . . . . . . . 266. . .

@IsAgentEnabled . . . . . . . . . . . . . . . . . . 267. . .

@IsAvailable . . . . . . . . . . . . . . . . . . . . . . 268. . .

@IsCategory . . . . . . . . . . . . . . . . . . . . . . . 269. . .

@IsDocBeingEdited . . . . . . . . . . . . . . . . . 270. . .

@IsDocBeingLoaded . . . . . . . . . . . . . . . . 270. . .

@IsDocBeingMailed . . . . . . . . . . . . . . . . . 271. . .

@IsDocBeingRecalculated . . . . . . . . . . . . 272. . .

@IsDocBeingSaved . . . . . . . . . . . . . . . . . 273. . .

@IsDocTruncated . . . . . . . . . . . . . . . . . . . 274. . .

@IsError . . . . . . . . . . . . . . . . . . . . . . . . . . 274. . .

@IsExpandable . . . . . . . . . . . . . . . . . . . . 275. . .

@IsMember . . . . . . . . . . . . . . . . . . . . . . . 276. . .

@IsModalHelp . . . . . . . . . . . . . . . . . . . . . 277. . .

@IsNewDoc . . . . . . . . . . . . . . . . . . . . . . . 278. . .

@IsNotMember . . . . . . . . . . . . . . . . . . . . 278. . .

@IsNumber . . . . . . . . . . . . . . . . . . . . . . . 280. . .

@IsResponseDoc . . . . . . . . . . . . . . . . . . . 280. . .

@IsText . . . . . . . . . . . . . . . . . . . . . . . . . . 281. . .

@IsTime . . . . . . . . . . . . . . . . . . . . . . . . . . 282. . .

@IsUnavailable . . . . . . . . . . . . . . . . . . . . 282. . .

@IsValid . . . . . . . . . . . . . . . . . . . . . . . . . 283. . .

@Keywords . . . . . . . . . . . . . . . . . . . . . . . 284. . .

@LanguagePreference . . . . . . . . . . . . . . . 285. . .

@Left . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286. . .

@LeftBack . . . . . . . . . . . . . . . . . . . . . . . . 287. . .

@Length . . . . . . . . . . . . . . . . . . . . . . . . . . 288. . .

vi Domino Designer Programming Guide

@Like . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289. . .

@Ln . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290. . .

@Locale . . . . . . . . . . . . . . . . . . . . . . . . . . 291. . .

@Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292. . .

@LowerCase . . . . . . . . . . . . . . . . . . . . . . 293. . .

@MailDbName . . . . . . . . . . . . . . . . . . . . 294. . .

@MailEncryptSavedPreference . . . . . . . . 295. . .

@MailEncryptSentPreference . . . . . . . . . . 296. . .

@MailSavePreference . . . . . . . . . . . . . . . . 296. . .

@MailSend . . . . . . . . . . . . . . . . . . . . . . . . 297. . .

@MailSignPreference . . . . . . . . . . . . . . . . 301. . .

@Matches . . . . . . . . . . . . . . . . . . . . . . . . . 302. . .

@Max . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303. . .

@Member . . . . . . . . . . . . . . . . . . . . . . . . . 304. . .

@Middle . . . . . . . . . . . . . . . . . . . . . . . . . 305. . .

@MiddleBack . . . . . . . . . . . . . . . . . . . . . . 307. . .

@Min . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308. . .

@Minute . . . . . . . . . . . . . . . . . . . . . . . . . 310. . .

@Modified . . . . . . . . . . . . . . . . . . . . . . . . 310. . .

@Modulo . . . . . . . . . . . . . . . . . . . . . . . . . 311. . .

@Month . . . . . . . . . . . . . . . . . . . . . . . . . . 312. . .

@Name . . . . . . . . . . . . . . . . . . . . . . . . . . 313. . .

@NameLookup . . . . . . . . . . . . . . . . . . . . 317. . .

@Narrow . . . . . . . . . . . . . . . . . . . . . . . . . 319. . .

@NewLine . . . . . . . . . . . . . . . . . . . . . . . . 320. . .

@No . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321. . .

@NoteID . . . . . . . . . . . . . . . . . . . . . . . . . 322. . .

@Now . . . . . . . . . . . . . . . . . . . . . . . . . . . 322. . .

@OptimizeMailAddress . . . . . . . . . . . . . 322. . .

@Password . . . . . . . . . . . . . . . . . . . . . . . 323. . .

@Pi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324. . .

@PickList . . . . . . . . . . . . . . . . . . . . . . . . . 325. . .

@Platform . . . . . . . . . . . . . . . . . . . . . . . . 328. . .

@PostedCommand . . . . . . . . . . . . . . . . . 330. . .

@Power . . . . . . . . . . . . . . . . . . . . . . . . . . 330. . .

@Prompt . . . . . . . . . . . . . . . . . . . . . . . . . 331. . .

@ProperCase . . . . . . . . . . . . . . . . . . . . . . 336. . .

@Random . . . . . . . . . . . . . . . . . . . . . . . . 337. . .

@RefreshECL . . . . . . . . . . . . . . . . . . . . . . 338. . .

REM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338. . .

@Repeat . . . . . . . . . . . . . . . . . . . . . . . . . . 339. . .

@Replace . . . . . . . . . . . . . . . . . . . . . . . . . 340. . .

@ReplaceSubstring . . . . . . . . . . . . . . . . . 341. . .

@Responses . . . . . . . . . . . . . . . . . . . . . . . 342. . .

@Return . . . . . . . . . . . . . . . . . . . . . . . . . . 343. . .

@Right . . . . . . . . . . . . . . . . . . . . . . . . . . . 344. . .

@RightBack . . . . . . . . . . . . . . . . . . . . . . . 345. . .

@Round . . . . . . . . . . . . . . . . . . . . . . . . . . 346. . .

@Second . . . . . . . . . . . . . . . . . . . . . . . . . 347. . .

SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . 348. . .

@Select . . . . . . . . . . . . . . . . . . . . . . . . . . . 349. . .

@Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350. . .

@SetDocField . . . . . . . . . . . . . . . . . . . . . . 351. . .

@SetEnvironment . . . . . . . . . . . . . . . . . . 352. . .

@SetField . . . . . . . . . . . . . . . . . . . . . . . . . 353. . .

@SetProfileField . . . . . . . . . . . . . . . . . . . . 354. . .

@SetTargetFrame . . . . . . . . . . . . . . . . . . . 354. . .

@Sign . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356. . .

@Sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356. . .

@Soundex . . . . . . . . . . . . . . . . . . . . . . . . 357. . .

@Sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358. . .

@Subset . . . . . . . . . . . . . . . . . . . . . . . . . . 358. . .

@Success . . . . . . . . . . . . . . . . . . . . . . . . . 359. . .

@Sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359. . .

@Tan . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361. . .

@Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361. . .

@TextToNumber . . . . . . . . . . . . . . . . . . . 363. . .

@TextToTime . . . . . . . . . . . . . . . . . . . . . . 364. . .

@Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 365. . .

@Today . . . . . . . . . . . . . . . . . . . . . . . . . . 366. . .

@Tomorrow . . . . . . . . . . . . . . . . . . . . . . . 367. . .

@Trim . . . . . . . . . . . . . . . . . . . . . . . . . . . 367. . .

vii

@True . . . . . . . . . . . . . . . . . . . . . . . . . . . 368. . .

@Unavailable . . . . . . . . . . . . . . . . . . . . . . 369. . .

@UndeleteDocument . . . . . . . . . . . . . . . . 369. . .

@Unique . . . . . . . . . . . . . . . . . . . . . . . . . 370. . .

@UpperCase . . . . . . . . . . . . . . . . . . . . . . 370. . .

@URLGetHeader . . . . . . . . . . . . . . . . . . . 371. . .

@URLHistory . . . . . . . . . . . . . . . . . . . . . 373. . .

@URLOpen . . . . . . . . . . . . . . . . . . . . . . . 374. . .

@UserAccess . . . . . . . . . . . . . . . . . . . . . . 377. . .

@UserName . . . . . . . . . . . . . . . . . . . . . . . 379. . .

@UserNameLanguage . . . . . . . . . . . . . . . 381. . .

@UserNamesList . . . . . . . . . . . . . . . . . . . 382. . .

@UserPrivileges . . . . . . . . . . . . . . . . . . . . 383. . .

@UserRoles . . . . . . . . . . . . . . . . . . . . . . . 383. . .

@V2If . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384. . .

@V3UserName . . . . . . . . . . . . . . . . . . . . 385. . .

@ValidateInternetAddress . . . . . . . . . . . . 386. . .

@Version . . . . . . . . . . . . . . . . . . . . . . . . . 388. . .

@ViewTitle . . . . . . . . . . . . . . . . . . . . . . . 389. . .

@Weekday . . . . . . . . . . . . . . . . . . . . . . . . 389. . .

@Wide . . . . . . . . . . . . . . . . . . . . . . . . . . . 390. . .

@Word . . . . . . . . . . . . . . . . . . . . . . . . . . . 391. . .

@Year . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392. . .

@Yes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393. . .

@Yesterday . . . . . . . . . . . . . . . . . . . . . . . 393. . .

@Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . 394. . .

6 Formula Language@Commands A–Z . . . . . . . . . . . 397.Using @Commands . . . . . . . . . . . . . . . . . 397. . .

@Commands with ECL security . . . . . . . 397. . .

AddBookmark . . . . . . . . . . . . . . . . . . . . . 400. . .

AddDatabase . . . . . . . . . . . . . . . . . . . . . . 400. . .

AddDatabaseRepID . . . . . . . . . . . . . . . . . 401. . .

AdminCertify . . . . . . . . . . . . . . . . . . . . . 402. . .

AdminCreateGroup . . . . . . . . . . . . . . . . . 402. . .

AdminCrossCertifyIDFile . . . . . . . . . . . . 403. . .

AdminCrossCertifyKey . . . . . . . . . . . . . . 403. . .

AdminDatabaseAnalysis . . . . . . . . . . . . . 403. . .

AdminDatabaseQuotas . . . . . . . . . . . . . . 404. . .

AdminIDFileClearPassword . . . . . . . . . . 404. . .

AdminIDFileExamine . . . . . . . . . . . . . . . 404. . .

AdminIDFileSetPassword . . . . . . . . . . . . 405. . .

Administration . . . . . . . . . . . . . . . . . . . . 405. . .

AdminNewOrganization . . . . . . . . . . . . . 405. . .

AdminNewOrgUnit . . . . . . . . . . . . . . . . 406. . .

AdminOpenAddressBook . . . . . . . . . . . . 406. . .

AdminOpenCatalog . . . . . . . . . . . . . . . . 406. . .

AdminOpenCertLog . . . . . . . . . . . . . . . . 407. . .

AdminOpenGroupsView . . . . . . . . . . . . 407. . .

AdminOpenServerLog . . . . . . . . . . . . . . 407. . .

AdminOpenServersView . . . . . . . . . . . . . 408. . .

AdminOpenStatistics . . . . . . . . . . . . . . . . 408. . .

AdminOpenUsersView . . . . . . . . . . . . . . 408. . .

AdminOutgoingMail . . . . . . . . . . . . . . . . 409. . .

AdminRegisterFromFile . . . . . . . . . . . . . 409. . .

AdminRegisterServer . . . . . . . . . . . . . . . 409. . .

AdminRegisterUser . . . . . . . . . . . . . . . . . 410. . .

AdminRemoteConsole . . . . . . . . . . . . . . 410. . .

AdminSendMailTrace . . . . . . . . . . . . . . . 410. . .

AdminStatisticsConfig . . . . . . . . . . . . . . . 411. . .

AdminTraceConnection . . . . . . . . . . . . . 411. . .

AgentEdit . . . . . . . . . . . . . . . . . . . . . . . . 411. . .

AgentEnableDisable . . . . . . . . . . . . . . . . 412. . .

AgentLog . . . . . . . . . . . . . . . . . . . . . . . . . 412. . .

AgentRun . . . . . . . . . . . . . . . . . . . . . . . . 413. . .

AgentSetServerName . . . . . . . . . . . . . . . 413. . .

AgentTestRun . . . . . . . . . . . . . . . . . . . . . 413. . .

AttachmentDetachAll . . . . . . . . . . . . . . . 414. . .

AttachmentLaunch . . . . . . . . . . . . . . . . . 414. . .

AttachmentProperties . . . . . . . . . . . . . . . 414. . .

AttachmentView . . . . . . . . . . . . . . . . . . . 415. . .

CalendarFormat . . . . . . . . . . . . . . . . . . . 415. . .

viii Domino Designer Programming Guide

CalendarGoTo . . . . . . . . . . . . . . . . . . . . . 416. . .

ChooseFolders . . . . . . . . . . . . . . . . . . . . . 416. . .

Compose . . . . . . . . . . . . . . . . . . . . . . . . . 417. . .

CreateAction . . . . . . . . . . . . . . . . . . . . . . 418. . .

CreateAgent . . . . . . . . . . . . . . . . . . . . . . 418. . .

CreateControlledAccessSection . . . . . . . . 419. . .

CreateEllipse . . . . . . . . . . . . . . . . . . . . . . 419. . .

CreateFolder . . . . . . . . . . . . . . . . . . . . . . 419. . .

CreateForm . . . . . . . . . . . . . . . . . . . . . . . 420. . .

CreateLayoutRegion . . . . . . . . . . . . . . . . 420. . .

CreateNavigator . . . . . . . . . . . . . . . . . . . 420. . .

CreatePolygon . . . . . . . . . . . . . . . . . . . . . 421. . .

CreatePolyline . . . . . . . . . . . . . . . . . . . . . 421. . .

CreateRectangle . . . . . . . . . . . . . . . . . . . . 421. . .

CreateRectangularHotspot . . . . . . . . . . . 422. . .

CreateSection . . . . . . . . . . . . . . . . . . . . . . 422. . .

CreateSubForm . . . . . . . . . . . . . . . . . . . . 422. . .

CreateTextbox . . . . . . . . . . . . . . . . . . . . . 423. . .

CreateView . . . . . . . . . . . . . . . . . . . . . . . 423. . .

DatabaseReplSettings . . . . . . . . . . . . . . . 423. . .

DebugLotusScript . . . . . . . . . . . . . . . . . . 424. . .

DesignDocumentInfo . . . . . . . . . . . . . . . 424. . .

DesignFormAttributes . . . . . . . . . . . . . . . 424. . .

DesignFormFieldDef . . . . . . . . . . . . . . . . 425. . .

DesignFormNewField . . . . . . . . . . . . . . . 425. . .

DesignForms . . . . . . . . . . . . . . . . . . . . . . 425. . .

DesignFormShareField . . . . . . . . . . . . . . 425. . .

DesignFormUseField . . . . . . . . . . . . . . . . 426. . .

DesignFormWindowTitle . . . . . . . . . . . . 426. . .

DesignHelpAboutDocument . . . . . . . . . . 426. . .

DesignHelpUsingDocument . . . . . . . . . . 427. . .

DesignIcon . . . . . . . . . . . . . . . . . . . . . . . . 427. . .

DesignMacros . . . . . . . . . . . . . . . . . . . . . 427. . .

DesignRefresh . . . . . . . . . . . . . . . . . . . . . 428. . .

DesignReplace . . . . . . . . . . . . . . . . . . . . . 428. . .

DesignSharedFields . . . . . . . . . . . . . . . . . 428. . .

DesignSynopsis . . . . . . . . . . . . . . . . . . . . 429. . .

DesignViewAppendColumn . . . . . . . . . . 429. . .

DesignViewAttributes . . . . . . . . . . . . . . . 429. . .

DesignViewColumnDef . . . . . . . . . . . . . . 429. . .

DesignViewEditActions . . . . . . . . . . . . . 430. . .

DesignViewFormFormula . . . . . . . . . . . . 430. . .

DesignViewNewColumn . . . . . . . . . . . . . 430. . .

DesignViews . . . . . . . . . . . . . . . . . . . . . . 430. . .

DesignViewSelectFormula . . . . . . . . . . . . 431. . .

DialingRules . . . . . . . . . . . . . . . . . . . . . . 431. . .

EditBottom . . . . . . . . . . . . . . . . . . . . . . . 431. . .

EditButton . . . . . . . . . . . . . . . . . . . . . . . . 432. . .

EditClear . . . . . . . . . . . . . . . . . . . . . . . . . 432. . .

EditCopy . . . . . . . . . . . . . . . . . . . . . . . . . 432. . .

EditCut . . . . . . . . . . . . . . . . . . . . . . . . . . 433. . .

EditDeselectAll . . . . . . . . . . . . . . . . . . . . 433. . .

EditDetach . . . . . . . . . . . . . . . . . . . . . . . . 434. . .

EditDocument . . . . . . . . . . . . . . . . . . . . . 435. . .

EditDown . . . . . . . . . . . . . . . . . . . . . . . . 436. . .

EditEncryptionKeys . . . . . . . . . . . . . . . . . 436. . .

EditFind . . . . . . . . . . . . . . . . . . . . . . . . . . 437. . .

EditFindInPreview . . . . . . . . . . . . . . . . . 437. . .

EditFindNext . . . . . . . . . . . . . . . . . . . . . . 438. . .

EditGoToField . . . . . . . . . . . . . . . . . . . . . 438. . .

EditHeaderFooter . . . . . . . . . . . . . . . . . . 439. . .

EditHorizScrollbar . . . . . . . . . . . . . . . . . . 439. . .

EditIndent . . . . . . . . . . . . . . . . . . . . . . . . 439. . .

EditIndentFirstLine . . . . . . . . . . . . . . . . . 440. . .

EditInsertButton . . . . . . . . . . . . . . . . . . . 440. . .

EditInsertFileAttachment . . . . . . . . . . . . 440. . .

EditInsertObject . . . . . . . . . . . . . . . . . . . . 441. . .

EditInsertPageBreak . . . . . . . . . . . . . . . . 442. . .

EditInsertPopup . . . . . . . . . . . . . . . . . . . 442. . .

EditInsertTable . . . . . . . . . . . . . . . . . . . . 443. . .

EditInsertText . . . . . . . . . . . . . . . . . . . . . 443. . .

EditLeft . . . . . . . . . . . . . . . . . . . . . . . . . . 444. . .

ix

EditLinks . . . . . . . . . . . . . . . . . . . . . . . . . 444. . .

EditLocations . . . . . . . . . . . . . . . . . . . . . . 445. . .

EditMakeDocLink . . . . . . . . . . . . . . . . . . 445. . .

EditNextField . . . . . . . . . . . . . . . . . . . . . 445. . .

EditOpenLink . . . . . . . . . . . . . . . . . . . . . 445. . .

EditPaste . . . . . . . . . . . . . . . . . . . . . . . . . 446. . .

EditPasteSpecial . . . . . . . . . . . . . . . . . . . 446. . .

EditPhoneNumbers . . . . . . . . . . . . . . . . . 446. . .

EditPrevField . . . . . . . . . . . . . . . . . . . . . . 447. . .

EditProfile . . . . . . . . . . . . . . . . . . . . . . . . 447. . .

EditResizePicture . . . . . . . . . . . . . . . . . . . 448. . .

EditRight . . . . . . . . . . . . . . . . . . . . . . . . . 448. . .

EditSelectAll . . . . . . . . . . . . . . . . . . . . . . 449. . .

EditSelectByDate . . . . . . . . . . . . . . . . . . . 450. . .

EditShowHideHiddenChars . . . . . . . . . . 450. . .

EditTableDeleteRowColumn . . . . . . . . . . 450. . .

EditTableFormat . . . . . . . . . . . . . . . . . . . 451. . .

EditTableInsertRowColumn . . . . . . . . . . 451. . .

EditTop . . . . . . . . . . . . . . . . . . . . . . . . . . 452. . .

EditUndo . . . . . . . . . . . . . . . . . . . . . . . . . 452. . .

EditUntruncate . . . . . . . . . . . . . . . . . . . . 452. . .

EditUp . . . . . . . . . . . . . . . . . . . . . . . . . . . 453. . .

EmptyTrash . . . . . . . . . . . . . . . . . . . . . . . 453. . .

ExchangeUnreadMarks . . . . . . . . . . . . . . 454. . .

Execute . . . . . . . . . . . . . . . . . . . . . . . . . . 454. . .

FileCloseWindow . . . . . . . . . . . . . . . . . . 455. . .

FileDatabaseACL . . . . . . . . . . . . . . . . . . . 455. . .

FileDatabaseCompact . . . . . . . . . . . . . . . 455. . .

FileDatabaseCopy . . . . . . . . . . . . . . . . . . 456. . .

FileDatabaseDelete . . . . . . . . . . . . . . . . . 456. . .

FileDatabaseInfo . . . . . . . . . . . . . . . . . . . 456. . .

FileDatabaseRemove . . . . . . . . . . . . . . . . 457. . .

FileDatabaseUseServer . . . . . . . . . . . . . . 457. . .

FileExit . . . . . . . . . . . . . . . . . . . . . . . . . . 457. . .

FileExport . . . . . . . . . . . . . . . . . . . . . . . . 458. . .

FileFullTextCreate . . . . . . . . . . . . . . . . . . 460. . .

FileFullTextDelete . . . . . . . . . . . . . . . . . . 460. . .

FileFullTextInfo . . . . . . . . . . . . . . . . . . . . 460. . .

FileFullTextUpdate . . . . . . . . . . . . . . . . . 461. . .

FileImport . . . . . . . . . . . . . . . . . . . . . . . . 461. . .

FileNewDatabase . . . . . . . . . . . . . . . . . . . 463. . .

FileNewReplica . . . . . . . . . . . . . . . . . . . . 463. . .

FileOpenDatabase . . . . . . . . . . . . . . . . . . 464. . .

FileOpenDBRepID . . . . . . . . . . . . . . . . . . 466. . .

FilePageSetup . . . . . . . . . . . . . . . . . . . . . 467. . .

FilePrint . . . . . . . . . . . . . . . . . . . . . . . . . . 468. . .

FilePrintSetup . . . . . . . . . . . . . . . . . . . . . 470. . .

FileSave . . . . . . . . . . . . . . . . . . . . . . . . . . 470. . .

FileSaveNewVersion . . . . . . . . . . . . . . . . 470. . .

FindFreeTimeDialog . . . . . . . . . . . . . . . . 471. . .

Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . 472. . .

FolderCollapse . . . . . . . . . . . . . . . . . . . . 473. . .

FolderCustomize . . . . . . . . . . . . . . . . . . . 473. . .

FolderExpand . . . . . . . . . . . . . . . . . . . . . 474. . .

FolderExpandAll . . . . . . . . . . . . . . . . . . . 474. . .

FolderExpandWithChildren . . . . . . . . . . 474. . .

FolderMove . . . . . . . . . . . . . . . . . . . . . . . 475. . .

FolderProperties . . . . . . . . . . . . . . . . . . . 475. . .

FolderRename . . . . . . . . . . . . . . . . . . . . . 475. . .

FormActions . . . . . . . . . . . . . . . . . . . . . . 476. . .

FormTestDocument . . . . . . . . . . . . . . . . . 476. . .

GoUpLevel . . . . . . . . . . . . . . . . . . . . . . . 476. . .

Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476. . .

HelpAboutDatabase . . . . . . . . . . . . . . . . 477. . .

HelpAboutNotes . . . . . . . . . . . . . . . . . . . 477. . .

HelpFunctions . . . . . . . . . . . . . . . . . . . . . 477. . .

HelpIndex . . . . . . . . . . . . . . . . . . . . . . . . 477. . .

HelpKeyboard . . . . . . . . . . . . . . . . . . . . . 478. . .

HelpMessages . . . . . . . . . . . . . . . . . . . . . 478. . .

HelpRelease3MenuFinder . . . . . . . . . . . . 478. . .

HelpReleaseNotes . . . . . . . . . . . . . . . . . . 478. . .

HelpTableOfContents . . . . . . . . . . . . . . . 478. . .

x Domino Designer Programming Guide

HelpUsingDatabase . . . . . . . . . . . . . . . . . 479. . .

HotSpotClear . . . . . . . . . . . . . . . . . . . . . . 479. . .

HotSpotProperties . . . . . . . . . . . . . . . . . . 479. . .

InsertSubForm . . . . . . . . . . . . . . . . . . . . . 480. . .

LayoutAddGraphic . . . . . . . . . . . . . . . . . 480. . .

LayoutAddText . . . . . . . . . . . . . . . . . . . . 480. . .

LayoutElementBringToFront . . . . . . . . . . 481. . .

LayoutElementProperties . . . . . . . . . . . . 481. . .

LayoutElementSendToBack . . . . . . . . . . . 481. . .

LayoutProperties . . . . . . . . . . . . . . . . . . . 482. . .

MailAddress . . . . . . . . . . . . . . . . . . . . . . 482. . .

MailComposeMemo . . . . . . . . . . . . . . . . 482. . .

MailForward . . . . . . . . . . . . . . . . . . . . . . 483. . .

MailForwardAsAttachment . . . . . . . . . . . 483. . .

MailOpen . . . . . . . . . . . . . . . . . . . . . . . . 483. . .

MailRequestCrossCert . . . . . . . . . . . . . . . 483. . .

MailRequestNewName . . . . . . . . . . . . . . 484. . .

MailRequestNewPublicKey . . . . . . . . . . . 484. . .

MailScanUnread . . . . . . . . . . . . . . . . . . . 484. . .

MailSend . . . . . . . . . . . . . . . . . . . . . . . . . 485. . .

MailSendCertificateRequest . . . . . . . . . . 485. . .

MailSendEncryptionKey . . . . . . . . . . . . . 485. . .

MailSendPublicKey . . . . . . . . . . . . . . . . . 486. . .

NavigateNext . . . . . . . . . . . . . . . . . . . . . 486. . .

NavigateNextHighlight . . . . . . . . . . . . . . 486. . .

NavigateNextMain . . . . . . . . . . . . . . . . . 487. . .

NavigateNextSelected . . . . . . . . . . . . . . . 487. . .

NavigateNextUnread . . . . . . . . . . . . . . . 488. . .

NavigatePrev . . . . . . . . . . . . . . . . . . . . . . 488. . .

NavigatePrevHighlight . . . . . . . . . . . . . . 489. . .

NavigatePrevMain . . . . . . . . . . . . . . . . . 489. . .

NavigatePrevSelected . . . . . . . . . . . . . . . 490. . .

NavigatePrevUnread . . . . . . . . . . . . . . . . 490. . .

NavigateToBackLink . . . . . . . . . . . . . . . . 490. . .

NavigatorProperties . . . . . . . . . . . . . . . . 491. . .

NavigatorTest . . . . . . . . . . . . . . . . . . . . . 491. . .

ObjectDisplayAs . . . . . . . . . . . . . . . . . . . 491. . .

ObjectOpen . . . . . . . . . . . . . . . . . . . . . . . 492. . .

ObjectProperties . . . . . . . . . . . . . . . . . . . 492. . .

OpenCalendar . . . . . . . . . . . . . . . . . . . . . 492. . .

OpenDocument . . . . . . . . . . . . . . . . . . . . 493. . .

OpenFrameset . . . . . . . . . . . . . . . . . . . . . 494. . .

OpenHelpDocument . . . . . . . . . . . . . . . . 494. . .

OpenNavigator . . . . . . . . . . . . . . . . . . . . 495. . .

OpenPage . . . . . . . . . . . . . . . . . . . . . . . . 496. . .

OpenView . . . . . . . . . . . . . . . . . . . . . . . . 496. . .

PasteBitmapAsBackground . . . . . . . . . . . 497. . .

PasteBitmapAsObject . . . . . . . . . . . . . . . 498. . .

PictureProperties . . . . . . . . . . . . . . . . . . . 498. . .

PublishDatabase . . . . . . . . . . . . . . . . . . . 498. . .

RefreshHideFormulas . . . . . . . . . . . . . . . 498. . .

RefreshParentNote . . . . . . . . . . . . . . . . . 499. . .

RemoveFromFolder . . . . . . . . . . . . . . . . . 499. . .

RenameDatabase . . . . . . . . . . . . . . . . . . . 499. . .

Replicator . . . . . . . . . . . . . . . . . . . . . . . . 500. . .

ReplicatorReplicateHigh . . . . . . . . . . . . . 500. . .

ReplicatorReplicateNext . . . . . . . . . . . . . 501. . .

ReplicatorReplicateSelected . . . . . . . . . . . 501. . .

ReplicatorReplicateWithServer . . . . . . . . 501. . .

ReplicatorSendMail . . . . . . . . . . . . . . . . . 502. . .

ReplicatorSendReceiveMail . . . . . . . . . . . 502. . .

ReplicatorStart . . . . . . . . . . . . . . . . . . . . . 502. . .

ReplicatorStop . . . . . . . . . . . . . . . . . . . . . 502. . .

SectionCollapse . . . . . . . . . . . . . . . . . . . . 503. . .

SectionCollapseAll . . . . . . . . . . . . . . . . . . 503. . .

SectionDefineEditors . . . . . . . . . . . . . . . . 503. . .

SectionExpand . . . . . . . . . . . . . . . . . . . . . 504. . .

SectionExpandAll . . . . . . . . . . . . . . . . . . 504. . .

SectionProperties . . . . . . . . . . . . . . . . . . . 504. . .

SectionRemoveHeader . . . . . . . . . . . . . . 505. . .

SetCurrentLocation . . . . . . . . . . . . . . . . . 505. . .

ShowHideLinkPreview . . . . . . . . . . . . . . 505. . .

xi

ShowHideParentPreview . . . . . . . . . . . . 506. . .

ShowHidePreviewPane . . . . . . . . . . . . . . 506. . .

ShowProperties . . . . . . . . . . . . . . . . . . . . 506. . .

SmartIconsFloating . . . . . . . . . . . . . . . . . 507. . .

SmartIconsNextSet . . . . . . . . . . . . . . . . . 507. . .

StyleCycleKey . . . . . . . . . . . . . . . . . . . . . 507. . .

TextAlignCenter . . . . . . . . . . . . . . . . . . . 508. . .

TextAlignFull . . . . . . . . . . . . . . . . . . . . . 508. . .

TextAlignLeft . . . . . . . . . . . . . . . . . . . . . 508. . .

TextAlignNone . . . . . . . . . . . . . . . . . . . . 509. . .

TextAlignRight . . . . . . . . . . . . . . . . . . . . 509. . .

TextBold . . . . . . . . . . . . . . . . . . . . . . . . . 509. . .

TextBullet . . . . . . . . . . . . . . . . . . . . . . . . 510. . .

TextCycleSpacing . . . . . . . . . . . . . . . . . . 510. . .

TextEnlargeFont . . . . . . . . . . . . . . . . . . . 511. . .

TextFont . . . . . . . . . . . . . . . . . . . . . . . . . 511. . .

TextItalic . . . . . . . . . . . . . . . . . . . . . . . . . 512. . .

TextNormal . . . . . . . . . . . . . . . . . . . . . . . 512. . .

TextNumbers . . . . . . . . . . . . . . . . . . . . . . 513. . .

TextOutdent . . . . . . . . . . . . . . . . . . . . . . 513. . .

TextParagraph . . . . . . . . . . . . . . . . . . . . . 514. . .

TextParagraphStyles . . . . . . . . . . . . . . . . 514. . .

TextPermanentPen . . . . . . . . . . . . . . . . . 514. . .

TextReduceFont . . . . . . . . . . . . . . . . . . . . 515. . .

TextSetFontColor . . . . . . . . . . . . . . . . . . . 515. . .

TextSetFontFace . . . . . . . . . . . . . . . . . . . . 516. . .

TextSetFontSize . . . . . . . . . . . . . . . . . . . . 517. . .

TextSpacingDouble . . . . . . . . . . . . . . . . . 517. . .

TextSpacingOneAndAHalf . . . . . . . . . . . 518. . .

TextSpacingSingle . . . . . . . . . . . . . . . . . . 518. . .

TextUnderline . . . . . . . . . . . . . . . . . . . . . 518. . .

ToolsCall . . . . . . . . . . . . . . . . . . . . . . . . . 519. . .

ToolsCategorize . . . . . . . . . . . . . . . . . . . . 519. . .

ToolsHangUp . . . . . . . . . . . . . . . . . . . . . 520. . .

ToolsMarkAllRead . . . . . . . . . . . . . . . . . 520. . .

ToolsMarkAllUnread . . . . . . . . . . . . . . . 520. . .

ToolsMarkSelectedRead . . . . . . . . . . . . . 521. . .

ToolsMarkSelectedUnread . . . . . . . . . . . 521. . .

ToolsRefreshAllDocs . . . . . . . . . . . . . . . . 522. . .

ToolsRefreshSelectedDocs . . . . . . . . . . . . 522. . .

ToolsReplicate . . . . . . . . . . . . . . . . . . . . . 522. . .

ToolsRunBackgroundMacros . . . . . . . . . 523. . .

ToolsRunMacro . . . . . . . . . . . . . . . . . . . . 523. . .

ToolsScanUnreadChoose . . . . . . . . . . . . . 524. . .

ToolsScanUnreadPreferred . . . . . . . . . . . 524. . .

ToolsScanUnreadSelected . . . . . . . . . . . . 524. . .

ToolsSetupLocation . . . . . . . . . . . . . . . . . 525. . .

ToolsSetupMail . . . . . . . . . . . . . . . . . . . . 525. . .

ToolsSetupPorts . . . . . . . . . . . . . . . . . . . . 525. . .

ToolsSetupUserSetup . . . . . . . . . . . . . . . 526. . .

ToolsSmartIcons . . . . . . . . . . . . . . . . . . . 526. . .

ToolsSpellCheck . . . . . . . . . . . . . . . . . . . 526. . .

ToolsUserLogoff . . . . . . . . . . . . . . . . . . . 527. . .

UserIDCertificates . . . . . . . . . . . . . . . . . . 527. . .

UserIDClearPassword . . . . . . . . . . . . . . . 527. . .

UserIDCreateSafeCopy . . . . . . . . . . . . . . 528. . .

UserIDEncryptionKeys . . . . . . . . . . . . . . 528. . .

UserIDInfo . . . . . . . . . . . . . . . . . . . . . . . . 528. . .

UserIDMergeCopy . . . . . . . . . . . . . . . . . 529. . .

UserIDSetPassword . . . . . . . . . . . . . . . . . 529. . .

UserIDSwitch . . . . . . . . . . . . . . . . . . . . . 529. . .

V3EditNextField . . . . . . . . . . . . . . . . . . . 530. . .

V3EditPrevField . . . . . . . . . . . . . . . . . . . 530. . .

ViewArrangeIcons . . . . . . . . . . . . . . . . . . 531. . .

ViewBelowFolders . . . . . . . . . . . . . . . . . 531. . .

ViewBesideFolders . . . . . . . . . . . . . . . . . 531. . .

ViewCertify . . . . . . . . . . . . . . . . . . . . . . . 531. . .

ViewChange . . . . . . . . . . . . . . . . . . . . . . 532. . .

ViewCollapse . . . . . . . . . . . . . . . . . . . . . 533. . .

ViewCollapseAll . . . . . . . . . . . . . . . . . . . 533. . .

ViewExpand . . . . . . . . . . . . . . . . . . . . . . 534. . .

ViewExpandAll . . . . . . . . . . . . . . . . . . . . 534. . .

xii Domino Designer Programming Guide

ViewExpandWithChildren . . . . . . . . . . . 534. . .

ViewHorizScrollBar . . . . . . . . . . . . . . . . . 535. . .

ViewMoveName . . . . . . . . . . . . . . . . . . . 535. . .

ViewNavigatorsFolders . . . . . . . . . . . . . . 535. . .

ViewNavigatorsNone . . . . . . . . . . . . . . . 536. . .

ViewRefreshFields . . . . . . . . . . . . . . . . . . 536. . .

ViewRefreshUnread . . . . . . . . . . . . . . . . 536. . .

ViewRenamePerson . . . . . . . . . . . . . . . . . 537. . .

ViewShowFieldHelp . . . . . . . . . . . . . . . . 537. . .

ViewShowObject . . . . . . . . . . . . . . . . . . . 537. . .

ViewShowOnlyCategories . . . . . . . . . . . . 538. . .

ViewShowOnlySearchResults . . . . . . . . . 538. . .

ViewShowOnlySelected . . . . . . . . . . . . . 538. . .

ViewShowOnlyUnread . . . . . . . . . . . . . . 539. . .

ViewShowPageBreaks . . . . . . . . . . . . . . . 539. . .

ViewShowRuler . . . . . . . . . . . . . . . . . . . . 539. . .

ViewShowSearchBar . . . . . . . . . . . . . . . . 539. . .

ViewShowServerNames . . . . . . . . . . . . . 540. . .

ViewShowUnread . . . . . . . . . . . . . . . . . . 540. . .

ViewSwitchForm . . . . . . . . . . . . . . . . . . . 540. . .

WindowMaximize . . . . . . . . . . . . . . . . . . 541. . .

WindowMaximizeAll . . . . . . . . . . . . . . . 541. . .

WindowMinimize . . . . . . . . . . . . . . . . . . 541. . .

WindowMinimizeAll . . . . . . . . . . . . . . . . 542. . .

WindowWorkspace . . . . . . . . . . . . . . . . . 542. . .

WorkspaceProperties . . . . . . . . . . . . . . . . 542. . .

WorkspaceStackReplicaIcons . . . . . . . . . 543. . .

ZoomPreview . . . . . . . . . . . . . . . . . . . . . 543. . .

Volume II7 LotusScript Classes CodingGuidelines . . . . . . . . . . . . . . . . . 545.Using the Domino classes . . . . . . . . . . . . 545. . .

Using LotusScript features in Domino . . . 547. . .

Using %Include and %If . . . . . . . . . . . 548. . .

Closing a file . . . . . . . . . . . . . . . . . . . . 548. . .

Using OLE . . . . . . . . . . . . . . . . . . . . . 549. . .

Using the Evaluate statement . . . . . . . 549. . .

Using an object . . . . . . . . . . . . . . . . . . 550. . .

Using Bind, Command, Execute,InputBox, MessageBox, Print,SendKeys, Use, and UseLSX . . . . . 551. . .

Calling a function or subroutine . . . . . 552. . .

Using parentheses to pass by value . . 553. . .

Accessing Domino databases . . . . . . . . . . 553. . .

Accessing database properties . . . . . . 554. . .

Locating a database on a server andlocal disk . . . . . . . . . . . . . . . . . . . . 557. . .

Opening a database . . . . . . . . . . . . . . 558. . .

Creating a database . . . . . . . . . . . . . . 561. . .

Accessing an outline . . . . . . . . . . . . . . 562. . .

Examining and adjusting an accesscontrol list . . . . . . . . . . . . . . . . . . . 565. . .

Examining and adjusting databasereplication settings . . . . . . . . . . . . . 570. . .

Resetting the replication properties of a database . . . . . . . . . . . . . . . . . . . 574. . .

Saving database replication properties 574. . .

Accessing a document . . . . . . . . . . . . 575. . .

Accessing a form . . . . . . . . . . . . . . . . . 575. . .

Accessing views and folders . . . . . . . . . . 577. . .

Accessing view or folder properties . . 578. . .

Locating a view or folder . . . . . . . . . . 580. . .

Accessing view or folder columns . . . 581. . .

Refreshing a view or folder . . . . . . . . . 584. . .

Removing a view or folder . . . . . . . . . 585. . .

Retrieving multiple entries from a view 585. . .

Retrieving an entry from a view . . . . . 585. . .

Creating view navigators . . . . . . . . . . 586. . .

Accessing view entry properties . . . . . 587. . .

Getting the position of a view entry . . 590. . .

Accessing a view entry collection . . . . 590. . .

Adding an entry to a view entry collection . . . . . . . . . . . . . . . . 591. . .

xiii

Deleting an entry from a view entry collection . . . . . . . . . . . . . . . . 591. . .

Searching for entries in a view entry collection . . . . . . . . . . . . . . . . 591. . .

Retrieving entries from a view entry collection . . . . . . . . . . . . . . . . 592. . .

Removing documents from a viewentry collection . . . . . . . . . . . . . . . . 593. . .

Accessing NotesViewNavigatorproperties . . . . . . . . . . . . . . . . . . . . 594. . .

Accessing entries in a view navigator . 595. . .

Accessing documents in a view navigator . . . . . . . . . . . . . . . . 596. . .

Accessing an entry by position . . . . . . 598. . .

Accessing documents . . . . . . . . . . . . . . . 599. . .

Accessing document properties . . . . . 599. . .

Accessing the current document . . . . . 603. . .

Collecting all documents and allunprocessed documents . . . . . . . . . 610. . .

Collecting documents by searching . . 612. . .

Adding a document . . . . . . . . . . . . . . 614. . .

Locating a document by ID . . . . . . . . . 614. . .

Accessing a NotesDocument objectthrough a view . . . . . . . . . . . . . . . . 615. . .

Locating documents within a view or folder . . . . . . . . . . . . . . . . . . . . . 615. . .

Creating a document . . . . . . . . . . . . . 621. . .

Deleting a document . . . . . . . . . . . . . . 621. . .

Removing a document . . . . . . . . . . . . 622. . .

Copying a document . . . . . . . . . . . . . 622. . .

Mailing a document . . . . . . . . . . . . . . 623. . .

Accessing items . . . . . . . . . . . . . . . . . . . . 624. . .

Accessing item properties . . . . . . . . . . 625. . .

Creating an item and assigning values 630. . .

Copying an item . . . . . . . . . . . . . . . . . 633. . .

Removing an item . . . . . . . . . . . . . . . . 634. . .

Working with a rich text item . . . . . . . 635. . .

Working with an embedded object . . . 639. . .

Accessing rich-text style properties . . 641. . .

Accessing rich-text paragraph style properties . . . . . . . . . . . . . . . 643. . .

Working with tabs . . . . . . . . . . . . . . . 645. . .

Accessing sessions . . . . . . . . . . . . . . . . . . 646. . .

Accessing session properties . . . . . . . . 646. . .

Using environment variables . . . . . . . 649. . .

Accessing agents . . . . . . . . . . . . . . . . . 650. . .

Accessing international settings . . . . . 653. . .

Accessing supporting Domino objects . . . 654. . .

Converting between Domino Designerand LotusScript time . . . . . . . . . . . 655. . .

Making a Domino log . . . . . . . . . . . . . 656. . .

Making a Domino newsletter . . . . . . . 658. . .

Setting up a timer . . . . . . . . . . . . . . . . 659. . .

Representing a name . . . . . . . . . . . . . 659. . .

Accessing external databases through LS:DO . . . . . . . . . . . . . . . . 661. . .

Setting up LS:DO . . . . . . . . . . . . . . . . . . . 662. . .

LS:DO requirements . . . . . . . . . . . . . . 663. . .

Setting up LS:DO with ODBC . . . . . . . 664. . .

Creating your script . . . . . . . . . . . . . . 666. . .

Using LS:DO . . . . . . . . . . . . . . . . . . . . . . 667. . .

Connecting to an external database . . 667. . .

Retrieving data from an external database . . . . . . . . . . . . . . 672. . .

Working with data retrieved from anexternal database . . . . . . . . . . . . . . 676. . .

Tips and techniques . . . . . . . . . . . . . . . . . 690. . .

Handling an ODBC event . . . . . . . . . . 690. . .

Handling an ODBC error . . . . . . . . . . 693. . .

Transaction processing . . . . . . . . . . . . 695. . .

Caching data . . . . . . . . . . . . . . . . . . . . 697. . .

Multi-threading agents . . . . . . . . . . . . 697. . .

Handling run-time errors . . . . . . . . . . . . 698. . .

Using OLE custom controls . . . . . . . . . . . 715. . .

Using Domino Designer classes in Visual Basic . . . . . . . . . . . . . . . . . . 719. . .

xiv Domino Designer Programming Guide

8 LotusScript Classes A-Z . . . . 721.Properties and methods with

ECL security . . . . . . . . . . . . . . . . . . 721. . .

NotesACL class . . . . . . . . . . . . . . . . . . . . 728. . .

InternetLevel property . . . . . . . . . . . . . . . 729. . .

Parent property . . . . . . . . . . . . . . . . . . . . 730. . .

Roles property . . . . . . . . . . . . . . . . . . . . . 731. . .

UniformAccess property . . . . . . . . . . . . . 732. . .

AddRole method . . . . . . . . . . . . . . . . . . . 733. . .

CreateACLEntry method . . . . . . . . . . . . . 734. . .

DeleteRole method . . . . . . . . . . . . . . . . . 735. . .

GetEntry method . . . . . . . . . . . . . . . . . . . 736. . .

GetFirstEntry method . . . . . . . . . . . . . . . 737. . .

GetNextEntry method . . . . . . . . . . . . . . . 738. . .

RenameRole method . . . . . . . . . . . . . . . . 738. . .

Save method . . . . . . . . . . . . . . . . . . . . . . 739. . .

NotesACLEntry class . . . . . . . . . . . . . . . 740. . .

CanCreateDocuments property . . . . . . . . 743. . .

CanCreateLSOrJavaAgent property . . . . 744. . .

CanCreatePersonalAgent property . . . . . 745. . .

CanCreatePersonalFolder property . . . . . 746. . .

CanCreateSharedFolder property . . . . . . 747. . .

CanDeleteDocuments property . . . . . . . . 748. . .

IsAdminReaderAuthor property . . . . . . . 749. . .

IsAdminServer property . . . . . . . . . . . . . 750. . .

IsGroup property . . . . . . . . . . . . . . . . . . . 751. . .

IsPerson property . . . . . . . . . . . . . . . . . . 752. . .

IsPublicReader property . . . . . . . . . . . . . 753. . .

IsPublicWriter property . . . . . . . . . . . . . . 754. . .

IsServer property . . . . . . . . . . . . . . . . . . . 755. . .

Level property . . . . . . . . . . . . . . . . . . . . . 756. . .

Name property . . . . . . . . . . . . . . . . . . . . 757. . .

Parent property . . . . . . . . . . . . . . . . . . . . 759. . .

Roles property . . . . . . . . . . . . . . . . . . . . . 760. . .

UserType property . . . . . . . . . . . . . . . . . 761. . .

DisableRole method . . . . . . . . . . . . . . . . 761. . .

EnableRole method . . . . . . . . . . . . . . . . . 762. . .

IsRoleEnabled method . . . . . . . . . . . . . . . 763. . .

Remove method . . . . . . . . . . . . . . . . . . . 764. . .

NotesAgent class . . . . . . . . . . . . . . . . . . 765. . .

Comment property . . . . . . . . . . . . . . . . . 766. . .

CommonOwner property . . . . . . . . . . . . 767. . .

IsEnabled property . . . . . . . . . . . . . . . . . 768. . .

IsNotesAgent property . . . . . . . . . . . . . . 769. . .

IsPublic property . . . . . . . . . . . . . . . . . . . 770. . .

IsWebAgent property . . . . . . . . . . . . . . . 771. . .

LastRun property . . . . . . . . . . . . . . . . . . 772. . .

Name property . . . . . . . . . . . . . . . . . . . . 773. . .

Owner property . . . . . . . . . . . . . . . . . . . . 773. . .

Parent property . . . . . . . . . . . . . . . . . . . . 775. . .

Query property . . . . . . . . . . . . . . . . . . . . 775. . .

ServerName property . . . . . . . . . . . . . . . 777. . .

Target property . . . . . . . . . . . . . . . . . . . . 778. . .

Trigger property . . . . . . . . . . . . . . . . . . . 779. . .

Remove method . . . . . . . . . . . . . . . . . . . 780. . .

Run method . . . . . . . . . . . . . . . . . . . . . . . 782. . .

RunOnServer method . . . . . . . . . . . . . . . 783. . .

Save method . . . . . . . . . . . . . . . . . . . . . . 784. . .

Button class . . . . . . . . . . . . . . . . . . . . . . . 784. . .

Click event . . . . . . . . . . . . . . . . . . . . . . . . 784. . .

ObjectExecute event . . . . . . . . . . . . . . . . . 785. . .

NotesDatabase class . . . . . . . . . . . . . . . . 785. . .

ACL property . . . . . . . . . . . . . . . . . . . . . 793. . .

Agents property . . . . . . . . . . . . . . . . . . . 793. . .

AllDocuments property . . . . . . . . . . . . . . 794. . .

Categories property . . . . . . . . . . . . . . . . . 796. . .

Created property . . . . . . . . . . . . . . . . . . . 796. . .

CurrentAccessLevel property . . . . . . . . . 797. . .

DelayUpdates property . . . . . . . . . . . . . . 799. . .

DesignTemplateName property . . . . . . . 799. . .

FileName property . . . . . . . . . . . . . . . . . 801. . .

FilePath property . . . . . . . . . . . . . . . . . . . 801. . .

xv

FolderReferencesEnabled property . . . . . 802. . .

Forms property . . . . . . . . . . . . . . . . . . . . 804. . .

IsDirectoryCatalog property . . . . . . . . . . 804. . .

IsFTIndexed property . . . . . . . . . . . . . . . 805. . .

IsMultiDbSearch property . . . . . . . . . . . . 807. . .

IsOpen property . . . . . . . . . . . . . . . . . . . 807. . .

IsPrivateAddressBook property . . . . . . . 808. . .

IsPublicAddressBook property . . . . . . . . 809. . .

LastFTIndexed property . . . . . . . . . . . . . 810. . .

LastModified property . . . . . . . . . . . . . . 810. . .

Managers property . . . . . . . . . . . . . . . . . 811. . .

MaxSize property . . . . . . . . . . . . . . . . . . 813. . .

Parent property . . . . . . . . . . . . . . . . . . . . 813. . .

PercentUsed property . . . . . . . . . . . . . . . 814. . .

ReplicaID property . . . . . . . . . . . . . . . . . 815. . .

ReplicationInfo property . . . . . . . . . . . . . 815. . .

Server property . . . . . . . . . . . . . . . . . . . . 816. . .

Size property . . . . . . . . . . . . . . . . . . . . . . 817. . .

SizeQuota property . . . . . . . . . . . . . . . . . 817. . .

TemplateName property . . . . . . . . . . . . . 818. . .

Title property . . . . . . . . . . . . . . . . . . . . . . 819. . .

UnprocessedDocuments property . . . . . . 820. . .

Views property . . . . . . . . . . . . . . . . . . . . 824. . .

Compact method . . . . . . . . . . . . . . . . . . . 825. . .

Create method . . . . . . . . . . . . . . . . . . . . . 826. . .

CreateCopy method . . . . . . . . . . . . . . . . 827. . .

CreateDocument method . . . . . . . . . . . . . 829. . .

CreateFromTemplate method . . . . . . . . . 830. . .

CreateOutline method . . . . . . . . . . . . . . . 831. . .

CreateReplica method . . . . . . . . . . . . . . . 832. . .

EnableFolder method . . . . . . . . . . . . . . . 833. . .

FTDomainSearch method . . . . . . . . . . . . 834. . .

FTSearch method . . . . . . . . . . . . . . . . . . . 835. . .

GetAgent method . . . . . . . . . . . . . . . . . . 838. . .

GetDocumentByID method . . . . . . . . . . . 839. . .

GetDocumentByUNID method . . . . . . . . 841. . .

GetDocumentByURL method . . . . . . . . . 842. . .

GetForm method . . . . . . . . . . . . . . . . . . . 844. . .

GetOutline method . . . . . . . . . . . . . . . . . 845. . .

GetProfileDocument method . . . . . . . . . . 845. . .

GetProfileDocCollection method . . . . . . . 847. . .

GetURLHeaderInfo method . . . . . . . . . . 847. . .

GetView method . . . . . . . . . . . . . . . . . . . 849. . .

GrantAccess method . . . . . . . . . . . . . . . . 850. . .

Open method . . . . . . . . . . . . . . . . . . . . . . 852. . .

OpenByReplicaID method . . . . . . . . . . . . 854. . .

OpenIfModified method . . . . . . . . . . . . . 854. . .

OpenMail method . . . . . . . . . . . . . . . . . . 855. . .

OpenURLDb method . . . . . . . . . . . . . . . . 856. . .

OpenWithFailover method . . . . . . . . . . . 857. . .

QueryAccess method . . . . . . . . . . . . . . . . 858. . .

Remove method . . . . . . . . . . . . . . . . . . . 860. . .

Replicate method . . . . . . . . . . . . . . . . . . . 861. . .

RevokeAccess method . . . . . . . . . . . . . . . 861. . .

Search method . . . . . . . . . . . . . . . . . . . . . 862. . .

UnprocessedFTSearch method . . . . . . . . 864. . .

UnprocessedSearch method . . . . . . . . . . 869. . .

UpdateFTIndex method . . . . . . . . . . . . . 874. . .

NotesDateRange class . . . . . . . . . . . . . . 876. . .

EndDateTime property . . . . . . . . . . . . . . 877. . .

StartDateTime property . . . . . . . . . . . . . . 878. . .

Text property . . . . . . . . . . . . . . . . . . . . . . 878. . .

NotesDateTime class . . . . . . . . . . . . . . . 879. . .

DateOnly property . . . . . . . . . . . . . . . . . 883. . .

GMTTime property . . . . . . . . . . . . . . . . . 884. . .

IsDST property . . . . . . . . . . . . . . . . . . . . 885. . .

IsValidDate property . . . . . . . . . . . . . . . . 886. . .

LocalTime property . . . . . . . . . . . . . . . . . 887. . .

LSGMTTime property . . . . . . . . . . . . . . . 887. . .

LSLocalTime property . . . . . . . . . . . . . . . 888. . .

TimeOnly property . . . . . . . . . . . . . . . . . 889. . .

TimeZone property . . . . . . . . . . . . . . . . . 889. . .

xvi Domino Designer Programming Guide

ZoneTime property . . . . . . . . . . . . . . . . . 890. . .

AdjustDay method . . . . . . . . . . . . . . . . . 891. . .

AdjustHour method . . . . . . . . . . . . . . . . 892. . .

AdjustMinute method . . . . . . . . . . . . . . . 893. . .

AdjustMonth method . . . . . . . . . . . . . . . 894. . .

AdjustSecond method . . . . . . . . . . . . . . . 895. . .

AdjustYear method . . . . . . . . . . . . . . . . . 896. . .

ConvertToZone method . . . . . . . . . . . . . 897. . .

SetAnyDate method . . . . . . . . . . . . . . . . 898. . .

SetAnyTime method . . . . . . . . . . . . . . . . 898. . .

SetNow method . . . . . . . . . . . . . . . . . . . . 898. . .

TimeDifference method . . . . . . . . . . . . . . 899. . .

TimeDifferenceDouble method . . . . . . . . 900. . .

NotesDbDirectory class . . . . . . . . . . . . . 901. . .

Name property . . . . . . . . . . . . . . . . . . . . 902. . .

GetFirstDatabase method . . . . . . . . . . . . 902. . .

GetNextDatabase method . . . . . . . . . . . . 903. . .

NotesDocument class . . . . . . . . . . . . . . . 904. . .

Authors property . . . . . . . . . . . . . . . . . . . 909. . .

ColumnValues property . . . . . . . . . . . . . 911. . .

Created property . . . . . . . . . . . . . . . . . . . 912. . .

EmbeddedObjects property . . . . . . . . . . . 913. . .

EncryptionKeys property . . . . . . . . . . . . 915. . .

EncryptOnSend property . . . . . . . . . . . . 916. . .

FolderReferences property . . . . . . . . . . . 917. . .

FTSearchScore property . . . . . . . . . . . . . . 919. . .

HasEmbedded property . . . . . . . . . . . . . 920. . .

IsDeleted property . . . . . . . . . . . . . . . . . . 921. . .

IsNewNote property . . . . . . . . . . . . . . . . 922. . .

IsProfile property . . . . . . . . . . . . . . . . . . 923. . .

IsResponse property . . . . . . . . . . . . . . . . 924. . .

IsSigned property . . . . . . . . . . . . . . . . . . 924. . .

IsUIDocOpen property . . . . . . . . . . . . . . 925. . .

IsValid property . . . . . . . . . . . . . . . . . . . 926. . .

Items property . . . . . . . . . . . . . . . . . . . . . 927. . .

Key property . . . . . . . . . . . . . . . . . . . . . . 928. . .

LastAccessed property . . . . . . . . . . . . . . 928. . .

LastModified property . . . . . . . . . . . . . . 929. . .

NameOfProfile property . . . . . . . . . . . . . 930. . .

NoteID property . . . . . . . . . . . . . . . . . . . 930. . .

ParentDatabase property . . . . . . . . . . . . . 931. . .

ParentDocumentUNID property . . . . . . . 932. . .

ParentView property . . . . . . . . . . . . . . . . 933. . .

Responses property . . . . . . . . . . . . . . . . . 933. . .

SaveMessageOnSend property . . . . . . . . 935. . .

SentByAgent property . . . . . . . . . . . . . . . 936. . .

Signer property . . . . . . . . . . . . . . . . . . . . 937. . .

SignOnSend property . . . . . . . . . . . . . . . 938. . .

Size property . . . . . . . . . . . . . . . . . . . . . . 939. . .

UniversalID property . . . . . . . . . . . . . . . 939. . .

Verifier property . . . . . . . . . . . . . . . . . . . 941. . .

AppendItemValue method . . . . . . . . . . . 942. . .

ComputeWithForm method . . . . . . . . . . 944. . .

CopyAllItems method . . . . . . . . . . . . . . . 946. . .

CopyItem method . . . . . . . . . . . . . . . . . . 947. . .

CopyToDatabase method . . . . . . . . . . . . 948. . .

CreateReplyMessage method . . . . . . . . . 949. . .

CreateRichTextItem method . . . . . . . . . . 950. . .

Encrypt method . . . . . . . . . . . . . . . . . . . . 951. . .

GetAttachment method . . . . . . . . . . . . . . 952. . .

GetFirstItem method . . . . . . . . . . . . . . . . 953. . .

GetItemValue method . . . . . . . . . . . . . . . 956. . .

HasItem method . . . . . . . . . . . . . . . . . . . 958. . .

MakeResponse method . . . . . . . . . . . . . . 960. . .

PutInFolder method . . . . . . . . . . . . . . . . 961. . .

Remove method . . . . . . . . . . . . . . . . . . . 963. . .

RemoveFromFolder method . . . . . . . . . . 964. . .

RemoveItem method . . . . . . . . . . . . . . . . 965. . .

RenderToRTItem method . . . . . . . . . . . . 966. . .

ReplaceItemValue method . . . . . . . . . . . . 967. . .

Save method . . . . . . . . . . . . . . . . . . . . . . 969. . .

Send method . . . . . . . . . . . . . . . . . . . . . . 972. . .

xvii

Sign method . . . . . . . . . . . . . . . . . . . . . . 974. . .

NotesDocumentCollection class . . . . . . 974. . .

Count property . . . . . . . . . . . . . . . . . . . . 977. . .

IsSorted property . . . . . . . . . . . . . . . . . . . 977. . .

Parent property . . . . . . . . . . . . . . . . . . . . 978. . .

Query property . . . . . . . . . . . . . . . . . . . . 979. . .

AddDocument method . . . . . . . . . . . . . . 980. . .

DeleteDocument method . . . . . . . . . . . . . 980. . .

FTSearch method . . . . . . . . . . . . . . . . . . . 981. . .

GetDocument method . . . . . . . . . . . . . . . 982. . .

GetFirstDocument method . . . . . . . . . . . 983. . .

GetLastDocument method . . . . . . . . . . . . 984. . .

GetNextDocument method . . . . . . . . . . . 984. . .

GetNthDocument method . . . . . . . . . . . . 985. . .

GetPrevDocument method . . . . . . . . . . . 987. . .

PutAllInFolder method . . . . . . . . . . . . . . 988. . .

RemoveAll method . . . . . . . . . . . . . . . . . 989. . .

RemoveAllFromFolder method . . . . . . . . 989. . .

StampAll method . . . . . . . . . . . . . . . . . . 990. . .

UpdateAll method . . . . . . . . . . . . . . . . . . 991. . .

NotesEmbeddedObject class . . . . . . . . . 992. . .

Class property . . . . . . . . . . . . . . . . . . . . . 994. . .

FileSize property . . . . . . . . . . . . . . . . . . . 995. . .

FitBelowFields property . . . . . . . . . . . . . 996. . .

FitToWindow property . . . . . . . . . . . . . . 997. . .

Name property . . . . . . . . . . . . . . . . . . . . 998. . .

Object property . . . . . . . . . . . . . . . . . . . . 999. . .

Parent property . . . . . . . . . . . . . . . . . . . . 999. . .

RunReadOnly property . . . . . . . . . . . . . . 1000. .

Source property . . . . . . . . . . . . . . . . . . . . 1000. .

Type property . . . . . . . . . . . . . . . . . . . . . 1001. .

Verbs property . . . . . . . . . . . . . . . . . . . . 1002. .

Activate method . . . . . . . . . . . . . . . . . . . 1003. .

DoVerb method . . . . . . . . . . . . . . . . . . . . 1005. .

ExtractFile method . . . . . . . . . . . . . . . . . 1005. .

Remove method . . . . . . . . . . . . . . . . . . . 1006. .

Field class . . . . . . . . . . . . . . . . . . . . . . . . 1007. .

Entering event . . . . . . . . . . . . . . . . . . . . . 1007. .

Exiting event . . . . . . . . . . . . . . . . . . . . . . 1007. .

NotesForm class . . . . . . . . . . . . . . . . . . . 1008. .

Aliases property . . . . . . . . . . . . . . . . . . . 1009. .

Fields property . . . . . . . . . . . . . . . . . . . . 1010. .

FormUsers property . . . . . . . . . . . . . . . . 1011. .

IsSubForm property . . . . . . . . . . . . . . . . . 1012. .

Name property . . . . . . . . . . . . . . . . . . . . 1013. .

ProtectReaders property . . . . . . . . . . . . . 1014. .

ProtectUsers property . . . . . . . . . . . . . . . 1015. .

Readers property . . . . . . . . . . . . . . . . . . . 1016. .

Remove method . . . . . . . . . . . . . . . . . . . 1017. .

NotesInternational class . . . . . . . . . . . . . 1018. .

AMString property . . . . . . . . . . . . . . . . . 1019. .

CurrencyDigits property . . . . . . . . . . . . . 1020. .

CurrencySymbol property . . . . . . . . . . . . 1020. .

DateSep property . . . . . . . . . . . . . . . . . . . 1021. .

DecimalSep property . . . . . . . . . . . . . . . . 1022. .

IsCurrencySpace property . . . . . . . . . . . . 1023. .

IsCurrencySuffix property . . . . . . . . . . . . 1023. .

IsCurrencyZero property . . . . . . . . . . . . . 1024. .

IsDateDMY property . . . . . . . . . . . . . . . . 1024. .

IsDateMDY property . . . . . . . . . . . . . . . . 1025. .

IsDateYMD property . . . . . . . . . . . . . . . . 1025. .

IsDST property . . . . . . . . . . . . . . . . . . . . 1025. .

IsTime24Hour property . . . . . . . . . . . . . . 1026. .

PMString property . . . . . . . . . . . . . . . . . . 1026. .

ThousandsSep property . . . . . . . . . . . . . 1027. .

TimeSep property . . . . . . . . . . . . . . . . . . 1027. .

TimeZone property . . . . . . . . . . . . . . . . . 1027. .

Today property . . . . . . . . . . . . . . . . . . . . 1028. .

Tomorrow property . . . . . . . . . . . . . . . . . 1028. .

Yesterday property . . . . . . . . . . . . . . . . . 1028. .

NotesItem class . . . . . . . . . . . . . . . . . . . . 1029. .

DateTimeValue property . . . . . . . . . . . . . 1033. .

xviii Domino Designer Programming Guide

IsAuthors property . . . . . . . . . . . . . . . . . 1034. .

IsEncrypted property . . . . . . . . . . . . . . . . 1035. .

IsNames property . . . . . . . . . . . . . . . . . . 1036. .

IsProtected property . . . . . . . . . . . . . . . . 1037. .

IsReaders property . . . . . . . . . . . . . . . . . 1037. .

IsSigned property . . . . . . . . . . . . . . . . . . 1038. .

IsSummary property . . . . . . . . . . . . . . . . 1039. .

LastModified property . . . . . . . . . . . . . . 1040. .

Name property . . . . . . . . . . . . . . . . . . . . 1040. .

Parent property . . . . . . . . . . . . . . . . . . . . 1041. .

SaveToDisk property . . . . . . . . . . . . . . . . 1041. .

Text property . . . . . . . . . . . . . . . . . . . . . . 1042. .

Type property . . . . . . . . . . . . . . . . . . . . . 1044. .

ValueLength property . . . . . . . . . . . . . . . 1046. .

Values property . . . . . . . . . . . . . . . . . . . . 1046. .

Abstract method . . . . . . . . . . . . . . . . . . . 1048. .

AppendToTextList method . . . . . . . . . . . 1048. .

Contains method . . . . . . . . . . . . . . . . . . . 1050. .

CopyItemToDocument method . . . . . . . . 1051. .

Remove method . . . . . . . . . . . . . . . . . . . 1052. .

NotesLog class . . . . . . . . . . . . . . . . . . . . 1052. .

LogActions property . . . . . . . . . . . . . . . . 1055. .

LogErrors property . . . . . . . . . . . . . . . . . 1056. .

NumActions property . . . . . . . . . . . . . . . 1057. .

NumErrors property . . . . . . . . . . . . . . . . 1058. .

OverwriteFile property . . . . . . . . . . . . . . 1059. .

ProgramName property . . . . . . . . . . . . . 1060. .

Close method . . . . . . . . . . . . . . . . . . . . . . 1061. .

LogAction method . . . . . . . . . . . . . . . . . . 1061. .

LogError method . . . . . . . . . . . . . . . . . . . 1063. .

LogEvent method . . . . . . . . . . . . . . . . . . 1067. .

OpenAgentLog method . . . . . . . . . . . . . . 1068. .

OpenFileLog method . . . . . . . . . . . . . . . . 1068. .

OpenMailLog method . . . . . . . . . . . . . . . 1069. .

OpenNotesLog method . . . . . . . . . . . . . . 1071. .

NotesName class . . . . . . . . . . . . . . . . . . . 1073. .

Abbreviated property . . . . . . . . . . . . . . . 1075. .

Addr821 property . . . . . . . . . . . . . . . . . . 1076. .

Addr822Comment1 property . . . . . . . . . 1076. .

Addr822Comment2 property . . . . . . . . . 1076. .

Addr822Comment3 property . . . . . . . . . 1077. .

Addr822LocalPart property . . . . . . . . . . . 1077. .

Addr822Phrase property . . . . . . . . . . . . . 1077. .

ADMD property . . . . . . . . . . . . . . . . . . . 1078. .

Canonical property . . . . . . . . . . . . . . . . . 1078. .

Common property . . . . . . . . . . . . . . . . . . 1078. .

Country property . . . . . . . . . . . . . . . . . . 1079. .

Generation property . . . . . . . . . . . . . . . . 1079. .

Given property . . . . . . . . . . . . . . . . . . . . 1079. .

Initials property . . . . . . . . . . . . . . . . . . . . 1080. .

IsHierarchical property . . . . . . . . . . . . . . 1080. .

Keyword property . . . . . . . . . . . . . . . . . . 1080. .

Language property . . . . . . . . . . . . . . . . . 1081. .

Organization property . . . . . . . . . . . . . . . 1085. .

OrgUnit1 property . . . . . . . . . . . . . . . . . . 1085. .

OrgUnit2 property . . . . . . . . . . . . . . . . . . 1085. .

OrgUnit3 property . . . . . . . . . . . . . . . . . . 1086. .

OrgUnit4 property . . . . . . . . . . . . . . . . . . 1086. .

PRMD property . . . . . . . . . . . . . . . . . . . . 1086. .

Surname property . . . . . . . . . . . . . . . . . . 1087. .

Navigator class . . . . . . . . . . . . . . . . . . . . 1087. .

Click event . . . . . . . . . . . . . . . . . . . . . . . . 1087. .

NotesNewsletter class . . . . . . . . . . . . . . . 1088. .

DoScore property . . . . . . . . . . . . . . . . . . 1090. .

DoSubject property . . . . . . . . . . . . . . . . . 1091. .

SubjectItemName property . . . . . . . . . . . 1091. .

FormatDocument method . . . . . . . . . . . . 1092. .

FormatMsgWithDoclinks method . . . . . . 1094. .

ODBCConnection class . . . . . . . . . . . . . 1097. .

AutoCommit property . . . . . . . . . . . . . . . 1098. .

CommitOnDisconnect property . . . . . . . 1099. .

DataSourceName property . . . . . . . . . . . 1100. .

xix

GetLSDOMasterRevision property . . . . . 1101. .

SilentMode property . . . . . . . . . . . . . . . . 1101. .

CommitTransactions method . . . . . . . . . 1102. .

ConnectTo method . . . . . . . . . . . . . . . . . 1103. .

Disconnect method . . . . . . . . . . . . . . . . . 1105. .

GetError method . . . . . . . . . . . . . . . . . . . 1106. .

GetErrorMessage method . . . . . . . . . . . . 1106. .

GetExtendedErrorMessage method . . . . . 1106. .

IsConnected method . . . . . . . . . . . . . . . . 1106. .

IsSupported method . . . . . . . . . . . . . . . . 1107. .

ListDataSources method . . . . . . . . . . . . . 1109. .

ListFields method . . . . . . . . . . . . . . . . . . 1110. .

ListProcedures method . . . . . . . . . . . . . . 1111. .

ListTables method . . . . . . . . . . . . . . . . . . 1112. .

RollbackTransactions method . . . . . . . . . 1113. .

ODBCQuery class . . . . . . . . . . . . . . . . . . 1114. .

Connection property . . . . . . . . . . . . . . . . 1115. .

QueryExecuteTimeOut property . . . . . . . 1117. .

SQL property . . . . . . . . . . . . . . . . . . . . . . 1118. .

UseRowID property . . . . . . . . . . . . . . . . 1120. .

GetError method . . . . . . . . . . . . . . . . . . . 1121. .

GetErrorMessage method . . . . . . . . . . . . 1121. .

GetExtendedErrorMessage method . . . . . 1127. .

ODBCResultSet class . . . . . . . . . . . . . . . 1128. .

CacheLimit property . . . . . . . . . . . . . . . . 1131. .

CurrentRow property . . . . . . . . . . . . . . . 1133. .

FetchBatchSize property . . . . . . . . . . . . . 1135. .

MaxRows property . . . . . . . . . . . . . . . . . 1137. .

Query property . . . . . . . . . . . . . . . . . . . . 1138. .

ReadOnly property . . . . . . . . . . . . . . . . . 1139. .

AddRow method . . . . . . . . . . . . . . . . . . . 1140. .

Close method . . . . . . . . . . . . . . . . . . . . . . 1143. .

DeleteRow method . . . . . . . . . . . . . . . . . 1145. .

ExecProcedure Method . . . . . . . . . . . . . . 1147. .

Execute method . . . . . . . . . . . . . . . . . . . . 1147. .

FieldExpectedDataType method . . . . . . . 1149. .

FieldID method . . . . . . . . . . . . . . . . . . . . 1153. .

FieldInfo method . . . . . . . . . . . . . . . . . . . 1154. .

FieldName method . . . . . . . . . . . . . . . . . 1158. .

FieldNativeDataType method . . . . . . . . . 1159. .

FieldSize method . . . . . . . . . . . . . . . . . . . 1161. .

FirstRow method . . . . . . . . . . . . . . . . . . . 1162. .

GetError method . . . . . . . . . . . . . . . . . . . 1164. .

GetErrorMessage method . . . . . . . . . . . . 1164. .

GetExtendedErrorMessage method . . . . . 1164. .

GetParameter method . . . . . . . . . . . . . . . 1164. .

GetParameterName method . . . . . . . . . . 1166. .

GetRowStatus method . . . . . . . . . . . . . . . 1167. .

GetValue method . . . . . . . . . . . . . . . . . . . 1169. .

HasRowChanged method . . . . . . . . . . . . 1171. .

IsBeginOfData method . . . . . . . . . . . . . . 1173. .

IsEndOfData method . . . . . . . . . . . . . . . . 1175. .

IsResultSetAvailable method . . . . . . . . . . 1176. .

IsValueAltered method . . . . . . . . . . . . . . 1177. .

IsValueNull method . . . . . . . . . . . . . . . . 1179. .

LastRow method . . . . . . . . . . . . . . . . . . . 1180. .

LocateRow method . . . . . . . . . . . . . . . . . 1181. .

NextRow method . . . . . . . . . . . . . . . . . . 1183. .

NumColumns method . . . . . . . . . . . . . . . 1185. .

NumParameters method . . . . . . . . . . . . . 1186. .

NumRows method . . . . . . . . . . . . . . . . . 1187. .

PrevRow method . . . . . . . . . . . . . . . . . . . 1189. .

SetParameter method . . . . . . . . . . . . . . . 1190. .

SetValue method . . . . . . . . . . . . . . . . . . . 1192. .

UpdateRow method . . . . . . . . . . . . . . . . 1194. .

NotesOutline class . . . . . . . . . . . . . . . . . 1196. .

Alias property . . . . . . . . . . . . . . . . . . . . . 1197. .

Comment property . . . . . . . . . . . . . . . . . 1198. .

Name property . . . . . . . . . . . . . . . . . . . . 1199. .

AddEntry method . . . . . . . . . . . . . . . . . . 1199. .

CreateEntry method . . . . . . . . . . . . . . . . 1200. .

GetFirst method . . . . . . . . . . . . . . . . . . . . 1200. .

xx Domino Designer Programming Guide

GetLast method . . . . . . . . . . . . . . . . . . . . 1201. .

GetNext method . . . . . . . . . . . . . . . . . . . 1202. .

GetNextSibling method . . . . . . . . . . . . . . 1202. .

GetParent method . . . . . . . . . . . . . . . . . . 1203. .

GetPrev method . . . . . . . . . . . . . . . . . . . . 1204. .

GetPrevSibling method . . . . . . . . . . . . . . 1205. .

MoveEntry method . . . . . . . . . . . . . . . . . 1205. .

RemoveEntry method . . . . . . . . . . . . . . . 1206. .

Save method . . . . . . . . . . . . . . . . . . . . . . 1207. .

NotesOutlineEntry class . . . . . . . . . . . . . 1207. .

Alias property . . . . . . . . . . . . . . . . . . . . . 1208. .

Database property . . . . . . . . . . . . . . . . . . 1209. .

Document property . . . . . . . . . . . . . . . . . 1209. .

EntryClass property . . . . . . . . . . . . . . . . 1210. .

Formula property . . . . . . . . . . . . . . . . . . 1210. .

FrameText property . . . . . . . . . . . . . . . . . 1211. .

HasChildren property . . . . . . . . . . . . . . . 1212. .

ImagesText property . . . . . . . . . . . . . . . . 1212. .

IsHidden property . . . . . . . . . . . . . . . . . . 1213. .

IsInThisDB property . . . . . . . . . . . . . . . . 1214. .

IsPrivate property . . . . . . . . . . . . . . . . . . 1215. .

Label property . . . . . . . . . . . . . . . . . . . . . 1215. .

Level property . . . . . . . . . . . . . . . . . . . . . 1216. .

NamedElement property . . . . . . . . . . . . . 1217. .

Type property . . . . . . . . . . . . . . . . . . . . . 1217. .

URL property . . . . . . . . . . . . . . . . . . . . . 1218. .

View property . . . . . . . . . . . . . . . . . . . . . 1219. .

SetAction method . . . . . . . . . . . . . . . . . . 1219. .

SetNamedElement method . . . . . . . . . . . 1220. .

SetNoteLink method . . . . . . . . . . . . . . . . 1220. .

SetURL method . . . . . . . . . . . . . . . . . . . . 1221. .

NotesRegistration class . . . . . . . . . . . . . 1222. .

CertifierIDFile property . . . . . . . . . . . . . . 1225. .

CreateMailDb property . . . . . . . . . . . . . . 1225. .

Expiration property . . . . . . . . . . . . . . . . . 1226. .

IDType property . . . . . . . . . . . . . . . . . . . 1226. .

IsNorthAmerican property . . . . . . . . . . . 1227. .

MinPasswordLength property . . . . . . . . 1227. .

OrgUnit property . . . . . . . . . . . . . . . . . . 1228. .

RegistrationLog property . . . . . . . . . . . . 1228. .

RegistrationServer property . . . . . . . . . . 1228. .

StoreIDInAddressbook property . . . . . . . 1229. .

AddCertifierToAddressbook method . . . 1230. .

AddServerToAddressbook method . . . . . 1230. .

AddUserProfile method . . . . . . . . . . . . . 1232. .

AddUserToAddressbook method . . . . . . 1232. .

CrossCertify method . . . . . . . . . . . . . . . . 1234. .

DeleteIDOnServer method . . . . . . . . . . . 1235. .

GetIDFromServer method . . . . . . . . . . . . 1236. .

GetUserInfo method . . . . . . . . . . . . . . . . 1237. .

ReCertify method . . . . . . . . . . . . . . . . . . 1238. .

RegisterNewCertifier method . . . . . . . . . 1239. .

RegisterNewServer method . . . . . . . . . . . 1240. .

RegisterNewUser method . . . . . . . . . . . . 1241. .

SwitchToID method . . . . . . . . . . . . . . . . . 1243. .

NotesReplication class . . . . . . . . . . . . . . 1244. .

Abstract property . . . . . . . . . . . . . . . . . . 1246. .

CutoffDate property . . . . . . . . . . . . . . . . 1247. .

CutoffDelete property . . . . . . . . . . . . . . . 1248. .

CutoffInterval property . . . . . . . . . . . . . . 1248. .

Disabled property . . . . . . . . . . . . . . . . . . 1249. .

DoNotBrowse property . . . . . . . . . . . . . . 1250. .

DoNotCatalog property . . . . . . . . . . . . . . 1251. .

HideDesign property . . . . . . . . . . . . . . . . 1251. .

IgnoreDeletes property . . . . . . . . . . . . . . 1252. .

IgnoreDestDeletes property . . . . . . . . . . . 1253. .

MultiDbIndex property . . . . . . . . . . . . . . 1254. .

NeverReplicate property . . . . . . . . . . . . . 1254. .

NoChronos property . . . . . . . . . . . . . . . . 1255. .

Priority property . . . . . . . . . . . . . . . . . . . 1256. .

ClearHistory method . . . . . . . . . . . . . . . . 1257. .

Reset method . . . . . . . . . . . . . . . . . . . . . . 1257. .

xxi

Save method . . . . . . . . . . . . . . . . . . . . . . 1258. .

NotesRichTextItem class . . . . . . . . . . . . 1258. .

EmbeddedObjects property . . . . . . . . . . . 1261. .

AddNewLine method . . . . . . . . . . . . . . . 1262. .

AddPageBreak method . . . . . . . . . . . . . . 1263. .

AddTab method . . . . . . . . . . . . . . . . . . . 1264. .

AppendDocLink method . . . . . . . . . . . . . 1266. .

AppendParagraphStyle method . . . . . . . 1268. .

AppendRTItem method . . . . . . . . . . . . . . 1269. .

AppendStyle method . . . . . . . . . . . . . . . . 1270. .

AppendText method . . . . . . . . . . . . . . . . 1271. .

EmbedObject method . . . . . . . . . . . . . . . 1271. .

GetEmbeddedObject method . . . . . . . . . . 1274. .

GetFormattedText method . . . . . . . . . . . 1276. .

NotesRichTextParagraphStyle class . . . 1277. .

Alignment property . . . . . . . . . . . . . . . . . 1278. .

FirstLineLeftMargin property . . . . . . . . . 1279. .

InterLineSpacing property . . . . . . . . . . . . 1280. .

LeftMargin property . . . . . . . . . . . . . . . . 1281. .

Pagination property . . . . . . . . . . . . . . . . . 1282. .

RightMargin property . . . . . . . . . . . . . . . 1283. .

SpacingAbove property . . . . . . . . . . . . . . 1284. .

SpacingBelow property . . . . . . . . . . . . . . 1285. .

Tabs property . . . . . . . . . . . . . . . . . . . . . 1286. .

ClearAllTabs method . . . . . . . . . . . . . . . . 1287. .

SetTab method . . . . . . . . . . . . . . . . . . . . . 1287. .

SetTabs method . . . . . . . . . . . . . . . . . . . . 1289. .

NotesRichTextStyle class . . . . . . . . . . . . 1290. .

Bold property . . . . . . . . . . . . . . . . . . . . . 1292. .

Effects property . . . . . . . . . . . . . . . . . . . . 1293. .

FontSize property . . . . . . . . . . . . . . . . . . 1294. .

Italic property . . . . . . . . . . . . . . . . . . . . . 1295. .

NotesColor property . . . . . . . . . . . . . . . . 1296. .

NotesFont property . . . . . . . . . . . . . . . . . 1297. .

PassThruHTML property . . . . . . . . . . . . 1298. .

Strikethrough property . . . . . . . . . . . . . . 1299. .

Underline property . . . . . . . . . . . . . . . . . 1300. .

NotesRichTextTab class . . . . . . . . . . . . . 1301. .

Position property . . . . . . . . . . . . . . . . . . . 1302. .

Type property . . . . . . . . . . . . . . . . . . . . . 1303. .

Clear method . . . . . . . . . . . . . . . . . . . . . . 1303. .

NotesSession class . . . . . . . . . . . . . . . . . 1303. .

AddressBooks property . . . . . . . . . . . . . . 1305. .

CommonUserName property . . . . . . . . . 1307. .

CurrentAgent property . . . . . . . . . . . . . . 1308. .

CurrentDatabase property . . . . . . . . . . . . 1309. .

DocumentContext property . . . . . . . . . . . 1310. .

EffectiveUserName property . . . . . . . . . . 1313. .

International property . . . . . . . . . . . . . . . 1314. .

IsOnServer property . . . . . . . . . . . . . . . . 1315. .

LastExitStatus property . . . . . . . . . . . . . . 1316. .

LastRun property . . . . . . . . . . . . . . . . . . 1316. .

NotesBuildVersion property . . . . . . . . . . 1317. .

NotesVersion property . . . . . . . . . . . . . . 1318. .

Platform property . . . . . . . . . . . . . . . . . . 1319. .

SavedData property . . . . . . . . . . . . . . . . . 1320. .

UserName property . . . . . . . . . . . . . . . . . 1321. .

UserNameList property . . . . . . . . . . . . . . 1322. .

CreateDateRange method . . . . . . . . . . . . 1323. .

CreateDateTime method . . . . . . . . . . . . . 1323. .

CreateLog method . . . . . . . . . . . . . . . . . . 1324. .

CreateName method . . . . . . . . . . . . . . . . 1325. .

CreateNewsletter method . . . . . . . . . . . . 1327. .

CreateRichTextParagraphStyle method . . 1328. .

CreateRichTextStyle method . . . . . . . . . . 1329. .

CreateTimer method . . . . . . . . . . . . . . . . 1329. .

FreeTimeSearch method . . . . . . . . . . . . . 1331. .

GetDatabase method . . . . . . . . . . . . . . . . 1333. .

GetDbDirectory method . . . . . . . . . . . . . 1334. .

GetEnvironmentString method . . . . . . . . 1335. .

GetEnvironmentValue method . . . . . . . . 1336. .

SetEnvironmentVar method . . . . . . . . . . 1338. .

xxii Domino Designer Programming Guide

UpdateProcessedDoc method . . . . . . . . . 1339. .

NotesTimer class . . . . . . . . . . . . . . . . . . 1341. .

Alarm event . . . . . . . . . . . . . . . . . . . . . . . 1344. .

Comment property . . . . . . . . . . . . . . . . . 1344. .

Enabled property . . . . . . . . . . . . . . . . . . . 1344. .

Interval property . . . . . . . . . . . . . . . . . . . 1345. .

NotesUIDatabase class . . . . . . . . . . . . . . 1345. .

PostDocumentDelete event . . . . . . . . . . . 1347. .

PostDragDrop event . . . . . . . . . . . . . . . . 1347. .

PostOpen event . . . . . . . . . . . . . . . . . . . . 1348. .

QueryClose event . . . . . . . . . . . . . . . . . . 1349. .

QueryDocumentDelete event . . . . . . . . . 1349. .

QueryDocumentUndelete event . . . . . . . 1350. .

QueryDragDrop event . . . . . . . . . . . . . . . 1350. .

Database property . . . . . . . . . . . . . . . . . . 1351. .

Documents property . . . . . . . . . . . . . . . . 1352. .

OpenNavigator method . . . . . . . . . . . . . . 1352. .

OpenView method . . . . . . . . . . . . . . . . . 1352. .

NotesUIDocument class . . . . . . . . . . . . . 1353. .

PostModeChange event . . . . . . . . . . . . . . 1356. .

PostOpen event . . . . . . . . . . . . . . . . . . . . 1357. .

PostRecalc event . . . . . . . . . . . . . . . . . . . 1359. .

PostSave event . . . . . . . . . . . . . . . . . . . . . 1360. .

QueryClose event . . . . . . . . . . . . . . . . . . 1361. .

QueryModeChange event . . . . . . . . . . . . 1362. .

QueryOpen event . . . . . . . . . . . . . . . . . . 1363. .

QuerySave event . . . . . . . . . . . . . . . . . . . 1365. .

AutoReload property . . . . . . . . . . . . . . . . 1367. .

CurrentField property . . . . . . . . . . . . . . . 1368. .

DialogBoxCanceled property . . . . . . . . . 1369. .

Document property . . . . . . . . . . . . . . . . . 1370. .

EditMode property . . . . . . . . . . . . . . . . . 1371. .

FieldHelp property . . . . . . . . . . . . . . . . . 1372. .

HiddenChars property . . . . . . . . . . . . . . 1373. .

HorzScrollBar property . . . . . . . . . . . . . . 1374. .

InPreviewPane property . . . . . . . . . . . . . 1374. .

IsNewDoc property . . . . . . . . . . . . . . . . . 1375. .

PreviewDocLink property . . . . . . . . . . . . 1376. .

PreviewParentDoc property . . . . . . . . . . 1377. .

Ruler property . . . . . . . . . . . . . . . . . . . . . 1378. .

WindowTitle property . . . . . . . . . . . . . . . 1379. .

Categorize method . . . . . . . . . . . . . . . . . 1379. .

Clear method . . . . . . . . . . . . . . . . . . . . . . 1380. .

Close method . . . . . . . . . . . . . . . . . . . . . . 1381. .

CollapseAllSections method . . . . . . . . . . 1382. .

Copy method . . . . . . . . . . . . . . . . . . . . . . 1382. .

CreateObject method . . . . . . . . . . . . . . . . 1383. .

Cut method . . . . . . . . . . . . . . . . . . . . . . . 1384. .

DeleteDocument method . . . . . . . . . . . . . 1385. .

DeselectAll method . . . . . . . . . . . . . . . . . 1386. .

ExpandAllSections method . . . . . . . . . . . 1387. .

FieldAppendText method . . . . . . . . . . . . 1387. .

FieldClear method . . . . . . . . . . . . . . . . . . 1389. .

FieldContains method . . . . . . . . . . . . . . . 1390. .

FieldGetText method . . . . . . . . . . . . . . . . 1391. .

FieldSetText method . . . . . . . . . . . . . . . . 1392. .

FindFreeTimeDialog method . . . . . . . . . . 1393. .

FindFreeTimeDialogEx method . . . . . . . 1395. .

FindString method . . . . . . . . . . . . . . . . . . 1397. .

Forward method . . . . . . . . . . . . . . . . . . . 1398. .

GetObject method . . . . . . . . . . . . . . . . . . 1399. .

GetSelectedText method . . . . . . . . . . . . . 1400. .

GotoBottom method . . . . . . . . . . . . . . . . 1401. .

GotoField method . . . . . . . . . . . . . . . . . . 1401. .

GotoNextField method . . . . . . . . . . . . . . 1402. .

GotoPrevField method . . . . . . . . . . . . . . 1402. .

GotoTop method . . . . . . . . . . . . . . . . . . . 1402. .

Import method . . . . . . . . . . . . . . . . . . . . 1403. .

InsertText method . . . . . . . . . . . . . . . . . . 1404. .

NavBarSetText method . . . . . . . . . . . . . . 1404. .

NavBarSpinnerStart method . . . . . . . . . . 1405. .

NavBarSpinnerStop method . . . . . . . . . . 1405. .

xxiii

Paste method . . . . . . . . . . . . . . . . . . . . . . 1405. .

Print method . . . . . . . . . . . . . . . . . . . . . . 1406. .

Refresh method . . . . . . . . . . . . . . . . . . . . 1407. .

RefreshHideFormulas method . . . . . . . . 1408. .

Reload method . . . . . . . . . . . . . . . . . . . . 1409. .

Save method . . . . . . . . . . . . . . . . . . . . . . 1410. .

SaveNewVersion method . . . . . . . . . . . . 1410. .

SelectAll method . . . . . . . . . . . . . . . . . . . 1411. .

Send method . . . . . . . . . . . . . . . . . . . . . . 1412. .

SpellCheck method . . . . . . . . . . . . . . . . . 1413. .

NotesUIView class . . . . . . . . . . . . . . . . . 1413. .

PostDragDrop event . . . . . . . . . . . . . . . . 1414. .

PostOpen event . . . . . . . . . . . . . . . . . . . . 1415. .

PostPaste event . . . . . . . . . . . . . . . . . . . . 1415. .

QueryAddToFolder event . . . . . . . . . . . . 1416. .

QueryClose event . . . . . . . . . . . . . . . . . . 1417. .

QueryDragDrop event . . . . . . . . . . . . . . . 1418. .

QueryOpen event . . . . . . . . . . . . . . . . . . 1418. .

QueryOpenDocument event . . . . . . . . . . 1419. .

QueryPaste event . . . . . . . . . . . . . . . . . . . 1420. .

QueryRecalc event . . . . . . . . . . . . . . . . . . 1421. .

RegionDoubleClick event . . . . . . . . . . . . 1422. .

CalendarDateTime property . . . . . . . . . . 1422. .

CaretCategory property . . . . . . . . . . . . . . 1423. .

Documents property . . . . . . . . . . . . . . . . 1424. .

View property . . . . . . . . . . . . . . . . . . . . . 1424. .

Viewname property . . . . . . . . . . . . . . . . . 1424. .

Print method . . . . . . . . . . . . . . . . . . . . . . 1425. .

SelectDocument method . . . . . . . . . . . . . 1426. .

NotesUIWorkspace class . . . . . . . . . . . . 1426. .

CurrentCalendarDateTime property . . . . 1428. .

CurrentDatabase property . . . . . . . . . . . . 1428. .

CurrentDocument property . . . . . . . . . . . 1429. .

CurrentView property . . . . . . . . . . . . . . . 1430. .

AddDatabase method . . . . . . . . . . . . . . . 1430. .

CheckAlarms method . . . . . . . . . . . . . . . 1431. .

ComposeDocument method . . . . . . . . . . 1431. .

DialogBox method . . . . . . . . . . . . . . . . . . 1433. .

EditDocument method . . . . . . . . . . . . . . 1437. .

EditProfile method . . . . . . . . . . . . . . . . . 1438. .

EnableAlarms method . . . . . . . . . . . . . . . 1439. .

Folder method . . . . . . . . . . . . . . . . . . . . . 1439. .

GetListOfTunes method . . . . . . . . . . . . . 1440. .

OpenDatabase method . . . . . . . . . . . . . . 1441. .

OpenFileDialog method . . . . . . . . . . . . . 1442. .

OpenFrameSet method . . . . . . . . . . . . . . 1443. .

OpenPage method . . . . . . . . . . . . . . . . . . 1443. .

PickListCollection method . . . . . . . . . . . . 1444. .

PickListStrings method . . . . . . . . . . . . . . 1445. .

PlayTune method . . . . . . . . . . . . . . . . . . 1447. .

Prompt method . . . . . . . . . . . . . . . . . . . . 1447. .

RefreshParentNote method . . . . . . . . . . . 1449. .

ReloadWindow method . . . . . . . . . . . . . 1450. .

SaveFileDialog method . . . . . . . . . . . . . . 1450. .

SetCurrentLocation method . . . . . . . . . . 1451. .

SetTargetFrame method . . . . . . . . . . . . . 1452. .

URLOpen method . . . . . . . . . . . . . . . . . . 1452. .

UseLSX method . . . . . . . . . . . . . . . . . . . . 1455. .

ViewRefresh method . . . . . . . . . . . . . . . . 1455. .

NotesView class . . . . . . . . . . . . . . . . . . . 1457. .

Aliases property . . . . . . . . . . . . . . . . . . . 1460. .

AllEntries property . . . . . . . . . . . . . . . . . 1461. .

AutoUpdate property . . . . . . . . . . . . . . . 1461. .

BackgroundColor property . . . . . . . . . . . 1462. .

ColumnCount property . . . . . . . . . . . . . . 1464. .

Columns property . . . . . . . . . . . . . . . . . . 1464. .

Created property . . . . . . . . . . . . . . . . . . . 1465. .

HeaderLines property . . . . . . . . . . . . . . . 1466. .

IsCalendar property . . . . . . . . . . . . . . . . 1466. .

IsCategorized property . . . . . . . . . . . . . . 1467. .

IsConflict property . . . . . . . . . . . . . . . . . 1468. .

IsDefaultView property . . . . . . . . . . . . . . 1468. .

xxiv Domino Designer Programming Guide

IsFolder property . . . . . . . . . . . . . . . . . . . 1469. .

IsHierarchical property . . . . . . . . . . . . . . 1470. .

IsModified property . . . . . . . . . . . . . . . . 1471. .

IsPrivate property . . . . . . . . . . . . . . . . . . 1472. .

LastModified property . . . . . . . . . . . . . . 1472. .

Name property . . . . . . . . . . . . . . . . . . . . 1473. .

Parent property . . . . . . . . . . . . . . . . . . . . 1473. .

ProtectReaders property . . . . . . . . . . . . . 1474. .

Readers property . . . . . . . . . . . . . . . . . . . 1475. .

RowLines property . . . . . . . . . . . . . . . . . 1476. .

Spacing property . . . . . . . . . . . . . . . . . . . 1477. .

TopLevelEntryCount property . . . . . . . . 1478. .

UniversalID property . . . . . . . . . . . . . . . 1478. .

Clear method . . . . . . . . . . . . . . . . . . . . . . 1479. .

CreateViewNav method . . . . . . . . . . . . . 1480. .

CreateViewNavFrom method . . . . . . . . . 1481. .

CreateViewNavFromCategory method . . 1482. .

CreateViewNavFromChildren method . . 1483. .

CreateViewNavFromDescendants method 1483. .

FTSearch method . . . . . . . . . . . . . . . . . . . 1484. .

GetAllDocumentsByKey method . . . . . . 1486. .

GetAllEntriesByKey method . . . . . . . . . . 1488. .

GetChild method . . . . . . . . . . . . . . . . . . . 1489. .

GetDocumentByKey method . . . . . . . . . . 1490. .

GetEntryByKey method . . . . . . . . . . . . . . 1493. .

GetFirstDocument method . . . . . . . . . . . 1494. .

GetLastDocument method . . . . . . . . . . . . 1495. .

GetNextDocument method . . . . . . . . . . . 1496. .

GetNextSibling method . . . . . . . . . . . . . . 1497. .

GetNthDocument method . . . . . . . . . . . . 1499. .

GetParentDocument method . . . . . . . . . . 1501. .

GetPrevDocument method . . . . . . . . . . . 1502. .

GetPrevSibling method . . . . . . . . . . . . . . 1503. .

Refresh method . . . . . . . . . . . . . . . . . . . . 1504. .

Remove method . . . . . . . . . . . . . . . . . . . 1506. .

NotesViewColumn class . . . . . . . . . . . . 1506. .

Alignment property . . . . . . . . . . . . . . . . . 1509. .

DateFmt property . . . . . . . . . . . . . . . . . . 1510. .

FontColor property . . . . . . . . . . . . . . . . . 1510. .

FontFace property . . . . . . . . . . . . . . . . . . 1512. .

FontPointSize property . . . . . . . . . . . . . . 1512. .

FontStyle property . . . . . . . . . . . . . . . . . . 1513. .

Formula property . . . . . . . . . . . . . . . . . . 1514. .

HeaderAlignment property . . . . . . . . . . . 1515. .

IsAccentSensitiveSort . . . . . . . . . . . . . . . 1515. .

IsCaseSensitiveSort property . . . . . . . . . . 1516. .

IsCategory property . . . . . . . . . . . . . . . . 1517. .

IsField property . . . . . . . . . . . . . . . . . . . . 1518. .

IsFormula property . . . . . . . . . . . . . . . . . 1518. .

IsHidden property . . . . . . . . . . . . . . . . . . 1519. .

IsHideDetail property . . . . . . . . . . . . . . . 1520. .

IsIcon property . . . . . . . . . . . . . . . . . . . . 1521. .

IsResize property . . . . . . . . . . . . . . . . . . . 1521. .

IsResortAscending property . . . . . . . . . . 1522. .

IsResortDescending property . . . . . . . . . 1523. .

IsResortToView property . . . . . . . . . . . . 1523. .

IsResponse property . . . . . . . . . . . . . . . . 1524. .

IsSecondaryResort property . . . . . . . . . . 1527. .

IsSecondaryResortDescending property . 1527. .

IsShowTwistie property . . . . . . . . . . . . . 1528. .

IsSortDescending property . . . . . . . . . . . 1529. .

IsSorted property . . . . . . . . . . . . . . . . . . . 1529. .

ItemName property . . . . . . . . . . . . . . . . . 1531. .

ListSep property . . . . . . . . . . . . . . . . . . . 1532. .

NumberAttrib property . . . . . . . . . . . . . . 1533. .

NumberDigits property . . . . . . . . . . . . . . 1533. .

NumberFormat property . . . . . . . . . . . . . 1534. .

Position property . . . . . . . . . . . . . . . . . . . 1535. .

TimeDateFmt property . . . . . . . . . . . . . . 1536. .

TimeFmt property . . . . . . . . . . . . . . . . . . 1536. .

TimeZoneFmt property . . . . . . . . . . . . . . 1537. .

Title property . . . . . . . . . . . . . . . . . . . . . . 1538. .

xxv

Width property . . . . . . . . . . . . . . . . . . . . 1539. .

NotesViewEntry class . . . . . . . . . . . . . . . 1539. .

ChildCount property . . . . . . . . . . . . . . . . 1541. .

ColumnIndentLevel property . . . . . . . . . 1542. .

ColumnValues property . . . . . . . . . . . . . 1542. .

DescendantCount property . . . . . . . . . . . 1543. .

Document property . . . . . . . . . . . . . . . . . 1544. .

FTSearchScore property . . . . . . . . . . . . . . 1544. .

IndentLevel property . . . . . . . . . . . . . . . . 1545. .

IsCategory property . . . . . . . . . . . . . . . . 1546. .

IsConflict property . . . . . . . . . . . . . . . . . 1547. .

IsDocument property . . . . . . . . . . . . . . . 1548. .

IsTotal property . . . . . . . . . . . . . . . . . . . . 1549. .

IsValid property . . . . . . . . . . . . . . . . . . . 1549. .

NoteID property . . . . . . . . . . . . . . . . . . . 1550. .

Parent property . . . . . . . . . . . . . . . . . . . . 1551. .

SiblingCount property . . . . . . . . . . . . . . . 1552. .

UniversalID property . . . . . . . . . . . . . . . 1552. .

GetPosition method . . . . . . . . . . . . . . . . . 1553. .

NotesViewEntryCollection class . . . . . . 1554. .

Count property . . . . . . . . . . . . . . . . . . . . 1556. .

Parent property . . . . . . . . . . . . . . . . . . . . 1556. .

Query property . . . . . . . . . . . . . . . . . . . . 1557. .

AddEntry method . . . . . . . . . . . . . . . . . . 1558. .

DeleteEntry method . . . . . . . . . . . . . . . . 1558. .

FTSearch method . . . . . . . . . . . . . . . . . . . 1559. .

GetEntry method . . . . . . . . . . . . . . . . . . . 1560. .

GetFirstEntry method . . . . . . . . . . . . . . . 1561. .

GetLastEntry method . . . . . . . . . . . . . . . 1562. .

GetNextEntry method . . . . . . . . . . . . . . . 1563. .

GetNthEntry method . . . . . . . . . . . . . . . . 1564. .

GetPrevEntry method . . . . . . . . . . . . . . . 1565. .

PutAllInFolder method . . . . . . . . . . . . . . 1566. .

RemoveAll method . . . . . . . . . . . . . . . . . 1567. .

RemoveAllFromFolder method . . . . . . . . 1567. .

StampAll method . . . . . . . . . . . . . . . . . . 1568. .

UpdateAll method . . . . . . . . . . . . . . . . . . 1569. .

NotesViewNavigator class . . . . . . . . . . . 1570. .

MaxLevel property . . . . . . . . . . . . . . . . . 1573. .

ParentView property . . . . . . . . . . . . . . . . 1574. .

GetChild method . . . . . . . . . . . . . . . . . . . 1574. .

GetEntry method . . . . . . . . . . . . . . . . . . . 1575. .

GetFirst method . . . . . . . . . . . . . . . . . . . . 1576. .

GetFirstDocument method . . . . . . . . . . . 1577. .

GetLast method . . . . . . . . . . . . . . . . . . . . 1578. .

GetLastDocument method . . . . . . . . . . . . 1579. .

GetNext method . . . . . . . . . . . . . . . . . . . 1579. .

GetNextCategory method . . . . . . . . . . . . 1580. .

GetNextDocument method . . . . . . . . . . . 1581. .

GetNextSibling method . . . . . . . . . . . . . . 1582. .

GetNth method . . . . . . . . . . . . . . . . . . . . 1583. .

GetParent method . . . . . . . . . . . . . . . . . . 1584. .

GetPos method . . . . . . . . . . . . . . . . . . . . 1585. .

GetPrev method . . . . . . . . . . . . . . . . . . . . 1586. .

GetPrevCategory method . . . . . . . . . . . . 1587. .

GetPrevDocument method . . . . . . . . . . . 1588. .

GetPrevSibling method . . . . . . . . . . . . . . 1589. .

Volume III9 Java Classes . . . . . . . . . . . . . 1591Java Classes Coding Guidelines . . . . . . . 1591. .

Running a Java program . . . . . . . . . . . . . 1591. .

Accessing databases . . . . . . . . . . . . . . . . 1603. .

Accessing database properties . . . . . . 1603. .

Locating a database on a server or thelocal directory . . . . . . . . . . . . . . . . 1609. .

Opening a database . . . . . . . . . . . . . . 1610. .

Creating, compacting, removing, andreplicating a database . . . . . . . . . . 1614. .

Examining and adjusting an accesscontrol list . . . . . . . . . . . . . . . . . . . 1616. .

Accessing a form . . . . . . . . . . . . . . . . . 1619. .

Accessing an outline . . . . . . . . . . . . . . . . 1620. .

Accessing views and folders . . . . . . . . . . 1621. .

xxvi Domino Designer Programming Guide

Accessing view properties . . . . . . . . . 1621. .

Locating a view . . . . . . . . . . . . . . . . . . 1625. .

Accessing view columns . . . . . . . . . . . 1626. .

Working with view entries and navigators . . . . . . . . . . . . . . . . 1628. .

Removing a view . . . . . . . . . . . . . . . . 1631. .

Accessing documents . . . . . . . . . . . . . . . 1631. .

Accessing document properties . . . . . 1632. .

Collecting all documents and allunprocessed documents . . . . . . . . . 1635. .

Collecting documents by searching . . 1637. .

Locating a document by ID . . . . . . . . . 1638. .

Creating a document . . . . . . . . . . . . . 1639. .

Removing a document . . . . . . . . . . . . 1639. .

Copying a document . . . . . . . . . . . . . 1640. .

Mailing a document . . . . . . . . . . . . . . 1640. .

Accessing items . . . . . . . . . . . . . . . . . . . . 1640. .

Accessing item properties . . . . . . . . . . 1641. .

Creating an item and assigning values 1644. .

Copying an item . . . . . . . . . . . . . . . . . 1644. .

Removing an item . . . . . . . . . . . . . . . . 1645. .

Working with a rich text item . . . . . . . 1645. .

Working with an embedded object . . . 1646. .

Accessing Domino sessions . . . . . . . . . . . 1647. .

Accessing session properties . . . . . . . . 1648. .

Using environment variables . . . . . . . 1649. .

Accessing agents . . . . . . . . . . . . . . . . . 1650. .

Accessing international settings . . . . . 1652. .

Working with time . . . . . . . . . . . . . . . 1654. .

Making a log . . . . . . . . . . . . . . . . . . . . 1657. .

Making a newsletter . . . . . . . . . . . . . . 1658. .

Representing a name . . . . . . . . . . . . . 1658. .

10 Java Classes A-Z . . . . . . . . . 1661Properties and methods with

ECL security . . . . . . . . . . . . . . . . . . 1661. .

AgentBase class . . . . . . . . . . . . . . . . . . . 1668. .

AppletBase class . . . . . . . . . . . . . . . . . . . 1668. .

NotesError and NotesException classes . 1669. .

NotesFactory class . . . . . . . . . . . . . . . . . 1691. .

NotesThread class . . . . . . . . . . . . . . . . . . 1692. .

getURL method . . . . . . . . . . . . . . . . . . . . 1694. .

recycle method . . . . . . . . . . . . . . . . . . . . 1694. .

toString method . . . . . . . . . . . . . . . . . . . . 1695. .

Visibility interface . . . . . . . . . . . . . . . . . . 1695. .

ACL class . . . . . . . . . . . . . . . . . . . . . . . . 1696. .

InternetLevel property . . . . . . . . . . . . . . . 1697. .

IsUniformAccess property . . . . . . . . . . . . 1699. .

Parent property . . . . . . . . . . . . . . . . . . . . 1700. .

Roles property . . . . . . . . . . . . . . . . . . . . . 1701. .

addRole method . . . . . . . . . . . . . . . . . . . 1702. .

createACLEntry method . . . . . . . . . . . . . 1703. .

deleteRole method . . . . . . . . . . . . . . . . . . 1704. .

getEntry method . . . . . . . . . . . . . . . . . . . 1705. .

getFirstEntry method . . . . . . . . . . . . . . . . 1707. .

getNextEntry method . . . . . . . . . . . . . . . 1708. .

removeACLEntry method . . . . . . . . . . . . 1709. .

renameRole method . . . . . . . . . . . . . . . . 1710. .

save method . . . . . . . . . . . . . . . . . . . . . . 1711. .

ACLEntry class . . . . . . . . . . . . . . . . . . . . 1711. .

IsAdminReaderAuthor property . . . . . . . 1713. .

IsAdminServer property . . . . . . . . . . . . . 1714. .

IsCanCreateDocuments property . . . . . . 1714. .

IsCanCreateLSOrJavaAgent property . . . 1715. .

IsCanCreatePersonalAgent property . . . . 1716. .

IsCanCreatePersonalFolder property . . . 1717. .

IsCanCreateSharedFolder property . . . . . 1719. .

IsCanDeleteDocuments property . . . . . . 1719. .

IsGroup property . . . . . . . . . . . . . . . . . . . 1721. .

IsPerson property . . . . . . . . . . . . . . . . . . 1721. .

IsPublicReader property . . . . . . . . . . . . . 1722. .

IsPublicWriter property . . . . . . . . . . . . . . 1723. .

IsServer property . . . . . . . . . . . . . . . . . . . 1723. .

xxvii

Level property . . . . . . . . . . . . . . . . . . . . . 1724. .

Name property . . . . . . . . . . . . . . . . . . . . 1726. .

NameObject property . . . . . . . . . . . . . . . 1727. .

Parent property . . . . . . . . . . . . . . . . . . . . 1728. .

Roles property . . . . . . . . . . . . . . . . . . . . . 1729. .

UserType property . . . . . . . . . . . . . . . . . 1730. .

disableRole method . . . . . . . . . . . . . . . . . 1732. .

enableRole method . . . . . . . . . . . . . . . . . 1733. .

isRoleEnabled method . . . . . . . . . . . . . . . 1734. .

remove method . . . . . . . . . . . . . . . . . . . . 1735. .

Agent class . . . . . . . . . . . . . . . . . . . . . . . 1736. .

Comment property . . . . . . . . . . . . . . . . . 1738. .

CommonOwner property . . . . . . . . . . . . 1739. .

IsEnabled property . . . . . . . . . . . . . . . . . 1740. .

IsNotesAgent property . . . . . . . . . . . . . . 1742. .

IsPublic property . . . . . . . . . . . . . . . . . . . 1743. .

IsWebAgent property . . . . . . . . . . . . . . . 1744. .

LastRun property . . . . . . . . . . . . . . . . . . 1744. .

Name property . . . . . . . . . . . . . . . . . . . . 1746. .

Owner property . . . . . . . . . . . . . . . . . . . . 1746. .

Parent property . . . . . . . . . . . . . . . . . . . . 1747. .

Query property . . . . . . . . . . . . . . . . . . . . 1748. .

ServerName property . . . . . . . . . . . . . . . 1749. .

Target property . . . . . . . . . . . . . . . . . . . . 1751. .

Trigger property . . . . . . . . . . . . . . . . . . . 1753. .

remove method . . . . . . . . . . . . . . . . . . . . 1753. .

run method . . . . . . . . . . . . . . . . . . . . . . . 1755. .

runOnServer method . . . . . . . . . . . . . . . . 1756. .

save method . . . . . . . . . . . . . . . . . . . . . . 1757. .

AgentContext class . . . . . . . . . . . . . . . . . 1757. .

CurrentAgent property . . . . . . . . . . . . . . 1759. .

CurrentDatabase property . . . . . . . . . . . . 1760. .

DocumentContext property . . . . . . . . . . . 1761. .

EffectiveUserName property . . . . . . . . . . 1762. .

LastExitStatus property . . . . . . . . . . . . . . 1763. .

LastRun property . . . . . . . . . . . . . . . . . . 1764. .

SavedData property . . . . . . . . . . . . . . . . . 1765. .

UnprocessedDocuments property . . . . . . 1766. .

unprocessedFTSearch method . . . . . . . . . 1768. .

unprocessedSearch method . . . . . . . . . . . 1772. .

updateProcessedDoc method . . . . . . . . . 1775. .

Database class . . . . . . . . . . . . . . . . . . . . . 1776. .

ACL property . . . . . . . . . . . . . . . . . . . . . 1783. .

Agents property . . . . . . . . . . . . . . . . . . . 1784. .

AllDocuments property . . . . . . . . . . . . . . 1785. .

Categories property . . . . . . . . . . . . . . . . . 1786. .

Created property . . . . . . . . . . . . . . . . . . . 1787. .

CurrentAccessLevel property . . . . . . . . . 1788. .

DesignTemplateName property . . . . . . . 1790. .

FileName property . . . . . . . . . . . . . . . . . 1791. .

FilePath property . . . . . . . . . . . . . . . . . . . 1791. .

FolderReferencesEnabled property . . . . . 1792. .

Forms property . . . . . . . . . . . . . . . . . . . . 1794. .

IsDelayUpdates property . . . . . . . . . . . . 1794. .

IsFTIndexed property . . . . . . . . . . . . . . . 1796. .

IsMultiDbSearch property . . . . . . . . . . . . 1797. .

IsOpen property . . . . . . . . . . . . . . . . . . . 1798. .

IsPrivateAddressBook property . . . . . . . 1799. .

IsPublicAddressBook property . . . . . . . . 1800. .

LastFTIndexed property . . . . . . . . . . . . . 1801. .

LastModified property . . . . . . . . . . . . . . 1802. .

Managers property . . . . . . . . . . . . . . . . . 1803. .

MaxSize property . . . . . . . . . . . . . . . . . . 1804. .

Parent property . . . . . . . . . . . . . . . . . . . . 1805. .

PercentUsed property . . . . . . . . . . . . . . . 1805. .

ReplicaID property . . . . . . . . . . . . . . . . . 1806. .

ReplicationInfo property . . . . . . . . . . . . . 1807. .

Server property . . . . . . . . . . . . . . . . . . . . 1808. .

Size property . . . . . . . . . . . . . . . . . . . . . . 1809. .

SizeQuota property . . . . . . . . . . . . . . . . . 1810. .

TemplateName property . . . . . . . . . . . . . 1811. .

Title property . . . . . . . . . . . . . . . . . . . . . . 1812. .

xxviii Domino Designer Programming Guide

Views property . . . . . . . . . . . . . . . . . . . . 1813. .

compact method . . . . . . . . . . . . . . . . . . . 1814. .

createCopy method . . . . . . . . . . . . . . . . . 1815. .

createDocument method . . . . . . . . . . . . . 1816. .

createFromTemplate method . . . . . . . . . . 1817. .

createOutline method . . . . . . . . . . . . . . . 1819. .

createReplica method . . . . . . . . . . . . . . . 1820. .

enableFolder method . . . . . . . . . . . . . . . . 1821. .

FTDomainSearch method . . . . . . . . . . . . 1822. .

FTSearch method . . . . . . . . . . . . . . . . . . . 1823. .

getAgent method . . . . . . . . . . . . . . . . . . . 1826. .

getDocumentByID method . . . . . . . . . . . 1827. .

getDocumentByUNID method . . . . . . . . 1828. .

getDocumentByURL method . . . . . . . . . . 1830. .

getForm method . . . . . . . . . . . . . . . . . . . 1832. .

getOutline method . . . . . . . . . . . . . . . . . . 1833. .

getProfileDocCollection . . . . . . . . . . . . . . 1834. .

getProfileDocument method . . . . . . . . . . 1835. .

getURLHeaderInfo method . . . . . . . . . . . 1836. .

getView method . . . . . . . . . . . . . . . . . . . 1838. .

grantAccess method . . . . . . . . . . . . . . . . 1839. .

open method . . . . . . . . . . . . . . . . . . . . . . 1840. .

queryAccess method . . . . . . . . . . . . . . . . 1841. .

remove method . . . . . . . . . . . . . . . . . . . . 1843. .

replicate method . . . . . . . . . . . . . . . . . . . 1844. .

revokeAccess method . . . . . . . . . . . . . . . 1845. .

search method . . . . . . . . . . . . . . . . . . . . . 1847. .

updateFTIndex method . . . . . . . . . . . . . . 1848. .

DateRange class . . . . . . . . . . . . . . . . . . . 1849. .

EndDateTime property . . . . . . . . . . . . . . 1852. .

Parent property . . . . . . . . . . . . . . . . . . . . 1853. .

StartDateTime property . . . . . . . . . . . . . . 1853. .

Text property . . . . . . . . . . . . . . . . . . . . . . 1854. .

DateTime class . . . . . . . . . . . . . . . . . . . . 1854. .

DateOnly property . . . . . . . . . . . . . . . . . 1858. .

GMTTime property . . . . . . . . . . . . . . . . . 1859. .

IsDST property . . . . . . . . . . . . . . . . . . . . 1860. .

LocalTime property . . . . . . . . . . . . . . . . . 1861. .

Parent property . . . . . . . . . . . . . . . . . . . . 1863. .

TimeOnly property . . . . . . . . . . . . . . . . . 1863. .

TimeZone property . . . . . . . . . . . . . . . . . 1864. .

ZoneTime property . . . . . . . . . . . . . . . . . 1866. .

adjustDay method . . . . . . . . . . . . . . . . . . 1866. .

adjustHour method . . . . . . . . . . . . . . . . . 1867. .

adjustMinute method . . . . . . . . . . . . . . . 1869. .

adjustMonth method . . . . . . . . . . . . . . . . 1870. .

adjustSecond method . . . . . . . . . . . . . . . 1871. .

adjustYear method . . . . . . . . . . . . . . . . . 1872. .

convertToZone method . . . . . . . . . . . . . . 1874. .

setAnyDate method . . . . . . . . . . . . . . . . . 1875. .

setAnyTime method . . . . . . . . . . . . . . . . 1876. .

setNow method . . . . . . . . . . . . . . . . . . . . 1876. .

timeDifference method . . . . . . . . . . . . . . 1877. .

toJavaDate method . . . . . . . . . . . . . . . . . 1878. .

DbDirectory class . . . . . . . . . . . . . . . . . . 1879. .

Name property . . . . . . . . . . . . . . . . . . . . 1880. .

Parent property . . . . . . . . . . . . . . . . . . . . 1881. .

createDatabase method . . . . . . . . . . . . . . 1881. .

getFirstDatabase method . . . . . . . . . . . . . 1883. .

getNextDatabase method . . . . . . . . . . . . 1884. .

openDatabase method . . . . . . . . . . . . . . . 1885. .

openDatabaseByReplicaID method . . . . . 1886. .

openDatabaseIfModified method . . . . . . 1887. .

openMailDatabase method . . . . . . . . . . . 1888. .

Document class . . . . . . . . . . . . . . . . . . . . 1889. .

Authors property . . . . . . . . . . . . . . . . . . . 1893. .

ColumnValues property . . . . . . . . . . . . . 1895. .

Created property . . . . . . . . . . . . . . . . . . . 1896. .

EmbeddedObjects property . . . . . . . . . . . 1897. .

EncryptionKeys property . . . . . . . . . . . . 1899. .

FolderReferences property . . . . . . . . . . . 1900. .

FTSearchScore property . . . . . . . . . . . . . . 1900. .

xxix

HasEmbedded property . . . . . . . . . . . . . 1901. .

IsEncryptOnSend property . . . . . . . . . . . 1902. .

IsNewNote property . . . . . . . . . . . . . . . . 1903. .

IsProfile property . . . . . . . . . . . . . . . . . . 1904. .

IsResponse property . . . . . . . . . . . . . . . . 1905. .

IsSaveMessageOnSend property . . . . . . . 1905. .

IsSentByAgent property . . . . . . . . . . . . . 1906. .

IsSigned property . . . . . . . . . . . . . . . . . . 1907. .

IsSignOnSend property . . . . . . . . . . . . . . 1908. .

IsValid property . . . . . . . . . . . . . . . . . . . 1909. .

Items property . . . . . . . . . . . . . . . . . . . . . 1910. .

Key property . . . . . . . . . . . . . . . . . . . . . . 1911. .

LastAccessed property . . . . . . . . . . . . . . 1911. .

LastModified property . . . . . . . . . . . . . . 1912. .

NameOfProfile property . . . . . . . . . . . . . 1912. .

NoteID property . . . . . . . . . . . . . . . . . . . 1912. .

ParentDatabase property . . . . . . . . . . . . . 1913. .

ParentDocumentUNID property . . . . . . . 1914. .

ParentView property . . . . . . . . . . . . . . . . 1915. .

Responses property . . . . . . . . . . . . . . . . . 1916. .

Signer property . . . . . . . . . . . . . . . . . . . . 1918. .

Size property . . . . . . . . . . . . . . . . . . . . . . 1918. .

UniversalID property . . . . . . . . . . . . . . . 1919. .

Verifier property . . . . . . . . . . . . . . . . . . . 1920. .

appendItemValue method . . . . . . . . . . . . 1921. .

computeWithForm method . . . . . . . . . . . 1923. .

copyAllItems method . . . . . . . . . . . . . . . 1925. .

copyItem method . . . . . . . . . . . . . . . . . . . 1926. .

copyToDatabase method . . . . . . . . . . . . . 1928. .

createReplyMessage method . . . . . . . . . . 1929. .

createRichTextItem method . . . . . . . . . . . 1930. .

encrypt method . . . . . . . . . . . . . . . . . . . . 1931. .

getAttachment method . . . . . . . . . . . . . . 1933. .

getFirstItem method . . . . . . . . . . . . . . . . 1934. .

getItemValue method . . . . . . . . . . . . . . . 1936. .

getItemValueDouble method . . . . . . . . . . 1938. .

getItemValueInteger method . . . . . . . . . . 1938. .

getItemValueString method . . . . . . . . . . . 1939. .

hasItem method . . . . . . . . . . . . . . . . . . . . 1940. .

makeResponse method . . . . . . . . . . . . . . 1940. .

putInFolder method . . . . . . . . . . . . . . . . 1941. .

remove method . . . . . . . . . . . . . . . . . . . . 1943. .

removeFromFolder method . . . . . . . . . . . 1944. .

removeItem method . . . . . . . . . . . . . . . . 1945. .

renderToRTItem method . . . . . . . . . . . . . 1946. .

replaceItemValue method . . . . . . . . . . . . 1947. .

save method . . . . . . . . . . . . . . . . . . . . . . 1950. .

send method . . . . . . . . . . . . . . . . . . . . . . 1951. .

sign method . . . . . . . . . . . . . . . . . . . . . . . 1954. .

DocumentCollection class . . . . . . . . . . . 1954. .

Count property . . . . . . . . . . . . . . . . . . . . 1957. .

IsSorted property . . . . . . . . . . . . . . . . . . . 1957. .

Parent property . . . . . . . . . . . . . . . . . . . . 1959. .

Query property . . . . . . . . . . . . . . . . . . . . 1960. .

addDocument method . . . . . . . . . . . . . . . 1961. .

deleteDocument method . . . . . . . . . . . . . 1962. .

FTSearch method . . . . . . . . . . . . . . . . . . . 1964. .

getDocument method . . . . . . . . . . . . . . . 1965. .

getFirstDocument method . . . . . . . . . . . . 1967. .

getLastDocument method . . . . . . . . . . . . 1967. .

getNextDocument method . . . . . . . . . . . 1967. .

getNthDocument method . . . . . . . . . . . . 1969. .

getPrevDocument method . . . . . . . . . . . . 1971. .

putAllInFolder method . . . . . . . . . . . . . . 1972. .

removeAll method . . . . . . . . . . . . . . . . . . 1974. .

removeAllFromFolder method . . . . . . . . 1975. .

stampAll method . . . . . . . . . . . . . . . . . . . 1976. .

updateAll method . . . . . . . . . . . . . . . . . . 1977. .

EmbeddedObject class . . . . . . . . . . . . . . 1978. .

ClassName property . . . . . . . . . . . . . . . . 1980. .

FileSize property . . . . . . . . . . . . . . . . . . . 1981. .

Name property . . . . . . . . . . . . . . . . . . . . 1981. .

xxx Domino Designer Programming Guide

Object property . . . . . . . . . . . . . . . . . . . . 1982. .

Parent property . . . . . . . . . . . . . . . . . . . . 1982. .

Source property . . . . . . . . . . . . . . . . . . . . 1982. .

Type property . . . . . . . . . . . . . . . . . . . . . 1983. .

Verbs property . . . . . . . . . . . . . . . . . . . . 1983. .

activate method . . . . . . . . . . . . . . . . . . . . 1984. .

doVerb method . . . . . . . . . . . . . . . . . . . . 1984. .

extractFile method . . . . . . . . . . . . . . . . . . 1985. .

remove method . . . . . . . . . . . . . . . . . . . . 1986. .

Form class . . . . . . . . . . . . . . . . . . . . . . . . 1986. .

Aliases property . . . . . . . . . . . . . . . . . . . 1988. .

Fields property . . . . . . . . . . . . . . . . . . . . 1989. .

FormUsers property . . . . . . . . . . . . . . . . 1990. .

IsProtectReaders property . . . . . . . . . . . . 1992. .

IsProtectUsers property . . . . . . . . . . . . . . 1993. .

IsSubForm property . . . . . . . . . . . . . . . . . 1994. .

Name property . . . . . . . . . . . . . . . . . . . . 1995. .

Parent property . . . . . . . . . . . . . . . . . . . . 1996. .

Readers property . . . . . . . . . . . . . . . . . . . 1996. .

remove method . . . . . . . . . . . . . . . . . . . . 1997. .

International class . . . . . . . . . . . . . . . . . 1998. .

AMString property . . . . . . . . . . . . . . . . . 2000. .

CurrencyDigits property . . . . . . . . . . . . . 2001. .

CurrencySymbol property . . . . . . . . . . . . 2001. .

DateSep property . . . . . . . . . . . . . . . . . . . 2002. .

DecimalSep property . . . . . . . . . . . . . . . . 2004. .

IsCurrencySpace property . . . . . . . . . . . . 2005. .

IsCurrencySuffix property . . . . . . . . . . . . 2005. .

IsCurrencyZero property . . . . . . . . . . . . . 2006. .

IsDateDMY property . . . . . . . . . . . . . . . . 2006. .

IsDateMDY property . . . . . . . . . . . . . . . . 2007. .

IsDateYMD property . . . . . . . . . . . . . . . . 2007. .

IsDST property . . . . . . . . . . . . . . . . . . . . 2008. .

IsTime24Hour property . . . . . . . . . . . . . . 2008. .

Parent property . . . . . . . . . . . . . . . . . . . . 2009. .

PMString property . . . . . . . . . . . . . . . . . . 2009. .

ThousandsSep property . . . . . . . . . . . . . 2010. .

TimeSep property . . . . . . . . . . . . . . . . . . 2010. .

TimeZone property . . . . . . . . . . . . . . . . . 2010. .

Today property . . . . . . . . . . . . . . . . . . . . 2011. .

Tomorrow property . . . . . . . . . . . . . . . . . 2011. .

Yesterday property . . . . . . . . . . . . . . . . . 2012. .

Item class . . . . . . . . . . . . . . . . . . . . . . . . 2012. .

DateTimeValue property . . . . . . . . . . . . . 2016. .

IsAuthors property . . . . . . . . . . . . . . . . . 2016. .

IsEncrypted property . . . . . . . . . . . . . . . . 2018. .

IsNames property . . . . . . . . . . . . . . . . . . 2020. .

IsProtected property . . . . . . . . . . . . . . . . 2021. .

IsReaders property . . . . . . . . . . . . . . . . . 2021. .

IsSaveToDisk property . . . . . . . . . . . . . . 2022. .

IsSigned property . . . . . . . . . . . . . . . . . . 2022. .

IsSummary property . . . . . . . . . . . . . . . . 2023. .

LastModified property . . . . . . . . . . . . . . 2024. .

Name property . . . . . . . . . . . . . . . . . . . . 2024. .

Parent property . . . . . . . . . . . . . . . . . . . . 2024. .

Text property . . . . . . . . . . . . . . . . . . . . . . 2026. .

Type property . . . . . . . . . . . . . . . . . . . . . 2026. .

ValueDouble property . . . . . . . . . . . . . . . 2029. .

ValueInteger property . . . . . . . . . . . . . . . 2030. .

ValueLength property . . . . . . . . . . . . . . . 2030. .

Values property . . . . . . . . . . . . . . . . . . . . 2031. .

ValueString property . . . . . . . . . . . . . . . . 2033. .

abstractText method . . . . . . . . . . . . . . . . 2034. .

appendToTextList method . . . . . . . . . . . 2035. .

containsValue method . . . . . . . . . . . . . . . 2037. .

copyItemToDocument method . . . . . . . . 2038. .

remove method . . . . . . . . . . . . . . . . . . . . 2040. .

Log class . . . . . . . . . . . . . . . . . . . . . . . . . 2041. .

IsLogActions property . . . . . . . . . . . . . . . 2044. .

IsLogErrors property . . . . . . . . . . . . . . . . 2045. .

IsOverwriteFile property . . . . . . . . . . . . . 2046. .

NumActions property . . . . . . . . . . . . . . . 2048. .

xxxi

NumErrors property . . . . . . . . . . . . . . . . 2049. .

Parent property . . . . . . . . . . . . . . . . . . . . 2050. .

ProgramName property . . . . . . . . . . . . . 2050. .

close method . . . . . . . . . . . . . . . . . . . . . . 2051. .

logAction method . . . . . . . . . . . . . . . . . . 2052. .

logError method . . . . . . . . . . . . . . . . . . . 2053. .

logEvent method . . . . . . . . . . . . . . . . . . . 2055. .

openAgentLog method . . . . . . . . . . . . . . 2056. .

openFileLog method . . . . . . . . . . . . . . . . 2057. .

openMailLog method . . . . . . . . . . . . . . . 2059. .

openNotesLog method . . . . . . . . . . . . . . 2060. .

Name class . . . . . . . . . . . . . . . . . . . . . . . 2062. .

Abbreviated property . . . . . . . . . . . . . . . 2065. .

Addr821 property . . . . . . . . . . . . . . . . . . 2065. .

Addr822Comment1 property . . . . . . . . . 2065. .

Addr822Comment2 property . . . . . . . . . 2066. .

Addr822Comment3 property . . . . . . . . . 2066. .

Addr822LocalPart property . . . . . . . . . . . 2066. .

Addr822Phrase property . . . . . . . . . . . . . 2067. .

ADMD property . . . . . . . . . . . . . . . . . . . 2067. .

Canonical property . . . . . . . . . . . . . . . . . 2067. .

Common property . . . . . . . . . . . . . . . . . . 2068. .

Country property . . . . . . . . . . . . . . . . . . 2068. .

Generation property . . . . . . . . . . . . . . . . 2068. .

Given property . . . . . . . . . . . . . . . . . . . . 2069. .

Initials property . . . . . . . . . . . . . . . . . . . . 2069. .

IsHierarchical property . . . . . . . . . . . . . . 2069. .

Keyword property . . . . . . . . . . . . . . . . . . 2070. .

Language property . . . . . . . . . . . . . . . . . 2070. .

Organization property . . . . . . . . . . . . . . . 2074. .

OrgUnit1 property . . . . . . . . . . . . . . . . . . 2074. .

OrgUnit2 property . . . . . . . . . . . . . . . . . . 2074. .

OrgUnit3 property . . . . . . . . . . . . . . . . . . 2075. .

OrgUnit4 property . . . . . . . . . . . . . . . . . . 2075. .

Parent property . . . . . . . . . . . . . . . . . . . . 2075. .

PRMD property . . . . . . . . . . . . . . . . . . . . 2076. .

SurName property . . . . . . . . . . . . . . . . . . 2076. .

Newsletter class . . . . . . . . . . . . . . . . . . . 2076. .

IsDoScore property . . . . . . . . . . . . . . . . . 2079. .

IsDoSubject property . . . . . . . . . . . . . . . . 2079. .

Parent property . . . . . . . . . . . . . . . . . . . . 2080. .

SubjectItemName property . . . . . . . . . . . 2080. .

formatDocument method . . . . . . . . . . . . 2081. .

formatMsgWithDoclinks method . . . . . . 2083. .

Outline class . . . . . . . . . . . . . . . . . . . . . . 2085. .

Alias property . . . . . . . . . . . . . . . . . . . . . 2088. .

Comment property . . . . . . . . . . . . . . . . . 2089. .

Name property . . . . . . . . . . . . . . . . . . . . 2089. .

addEntry method . . . . . . . . . . . . . . . . . . 2089. .

createEntry method . . . . . . . . . . . . . . . . . 2090. .

getFirst method . . . . . . . . . . . . . . . . . . . . 2091. .

getLast method . . . . . . . . . . . . . . . . . . . . 2092. .

getNext method . . . . . . . . . . . . . . . . . . . . 2093. .

getNextSibling method . . . . . . . . . . . . . . 2093. .

getParent method . . . . . . . . . . . . . . . . . . 2094. .

getPrev method . . . . . . . . . . . . . . . . . . . . 2095. .

getPrevSibling method . . . . . . . . . . . . . . 2095. .

moveEntry method . . . . . . . . . . . . . . . . . 2096. .

removeEntry method . . . . . . . . . . . . . . . . 2098. .

save method . . . . . . . . . . . . . . . . . . . . . . 2099. .

OutlineEntry class . . . . . . . . . . . . . . . . . 2099. .

Alias property . . . . . . . . . . . . . . . . . . . . . 2100. .

Database property . . . . . . . . . . . . . . . . . . 2101. .

Document property . . . . . . . . . . . . . . . . . 2101. .

EntryClass property . . . . . . . . . . . . . . . . 2102. .

Formula property . . . . . . . . . . . . . . . . . . 2102. .

FrameText property . . . . . . . . . . . . . . . . . 2103. .

HasChildren property . . . . . . . . . . . . . . . 2103. .

ImagesText property . . . . . . . . . . . . . . . . 2105. .

IsHidden property . . . . . . . . . . . . . . . . . . 2105. .

IsInThisDB property . . . . . . . . . . . . . . . . 2106. .

IsPrivate property . . . . . . . . . . . . . . . . . . 2106. .

xxxii Domino Designer Programming Guide

Label property . . . . . . . . . . . . . . . . . . . . . 2107. .

Level property . . . . . . . . . . . . . . . . . . . . . 2107. .

NamedElement property . . . . . . . . . . . . . 2107. .

Type property . . . . . . . . . . . . . . . . . . . . . 2108. .

URL property . . . . . . . . . . . . . . . . . . . . . 2108. .

View property . . . . . . . . . . . . . . . . . . . . . 2109. .

setAction method . . . . . . . . . . . . . . . . . . 2109. .

setNamedElement method . . . . . . . . . . . 2110. .

setNoteLink method . . . . . . . . . . . . . . . . 2111. .

setURL method . . . . . . . . . . . . . . . . . . . . 2112. .

Registration class . . . . . . . . . . . . . . . . . . 2112. .

CertifierIDFile property . . . . . . . . . . . . . . 2114. .

CreateMailDb property . . . . . . . . . . . . . . 2114. .

Expiration property . . . . . . . . . . . . . . . . . 2115. .

IDType property . . . . . . . . . . . . . . . . . . . 2115. .

IsNorthAmerican property . . . . . . . . . . . 2116. .

MinPasswordLength property . . . . . . . . 2116. .

OrgUnit property . . . . . . . . . . . . . . . . . . 2117. .

RegistrationLog property . . . . . . . . . . . . 2117. .

RegistrationServer property . . . . . . . . . . 2117. .

StoreIDInAddressBook property . . . . . . 2118. .

UpdateAddressbook property . . . . . . . . . 2118. .

addCertifierToAddressbook method . . . . 2119. .

addServerToAddressbook method . . . . . 2120. .

addUserProfile method . . . . . . . . . . . . . . 2121. .

addUserToAddressbook method . . . . . . 2121. .

crossCertify method . . . . . . . . . . . . . . . . 2123. .

deleteIDOnServer method . . . . . . . . . . . . 2123. .

getIDFromServer method . . . . . . . . . . . . 2124. .

getUserInfo method . . . . . . . . . . . . . . . . . 2124. .

recertify method . . . . . . . . . . . . . . . . . . . 2125. .

registerNewCertifier method . . . . . . . . . . 2126. .

registerNewServer method . . . . . . . . . . . 2127. .

registerNewUser method . . . . . . . . . . . . 2128. .

switchToID method . . . . . . . . . . . . . . . . . 2129. .

Replication class . . . . . . . . . . . . . . . . . . . 2130. .

IsAbstract property . . . . . . . . . . . . . . . . . 2133. .

CutoffDate property . . . . . . . . . . . . . . . . 2134. .

CutoffInterval property . . . . . . . . . . . . . . 2135. .

IsCutoffDelete property . . . . . . . . . . . . . . 2135. .

IsDisabled property . . . . . . . . . . . . . . . . . 2136. .

IsDoNotBrowse property . . . . . . . . . . . . 2137. .

IsDoNotCatalog property . . . . . . . . . . . . 2138. .

IsHideDesign property . . . . . . . . . . . . . . 2139. .

IsIgnoreDeletes property . . . . . . . . . . . . . 2140. .

IsIgnoreDestDeletes property . . . . . . . . . 2141. .

IsMultiDbIndex property . . . . . . . . . . . . 2142. .

IsNeverReplicate property . . . . . . . . . . . . 2143. .

IsNoChronos property . . . . . . . . . . . . . . . 2143. .

Priority property . . . . . . . . . . . . . . . . . . . 2144. .

clearHistory method . . . . . . . . . . . . . . . . 2146. .

reset method . . . . . . . . . . . . . . . . . . . . . . 2146. .

save method . . . . . . . . . . . . . . . . . . . . . . 2146. .

RichTextItem class . . . . . . . . . . . . . . . . . 2147. .

EmbeddedObjects property . . . . . . . . . . . 2149. .

addNewLine method . . . . . . . . . . . . . . . . 2150. .

addPageBreak method . . . . . . . . . . . . . . 2152. .

addTab method . . . . . . . . . . . . . . . . . . . . 2152. .

appendDocLink method . . . . . . . . . . . . . 2153. .

appendParagraphStyle method . . . . . . . . 2155. .

appendRTItem method . . . . . . . . . . . . . . 2155. .

appendStyle method . . . . . . . . . . . . . . . . 2156. .

appendText method . . . . . . . . . . . . . . . . 2157. .

embedObject method . . . . . . . . . . . . . . . . 2157. .

getEmbeddedObject method . . . . . . . . . . 2159. .

getFormattedText method . . . . . . . . . . . . 2160. .

RichTextParagraphStyle class . . . . . . . . 2162. .

Alignment property . . . . . . . . . . . . . . . . . 2164. .

FirstLineLeftMargin property . . . . . . . . . 2165. .

InterLineSpacing property . . . . . . . . . . . . 2165. .

LeftMargin property . . . . . . . . . . . . . . . . 2166. .

Pagination property . . . . . . . . . . . . . . . . . 2166. .

xxxiii

RightMargin property . . . . . . . . . . . . . . . 2167. .

SpacingAbove property . . . . . . . . . . . . . . 2168. .

SpacingBelow property . . . . . . . . . . . . . . 2168. .

Tabs property . . . . . . . . . . . . . . . . . . . . . 2169. .

clearAllTabs method . . . . . . . . . . . . . . . . 2169. .

setTab method . . . . . . . . . . . . . . . . . . . . . 2170. .

setTabs method . . . . . . . . . . . . . . . . . . . . 2170. .

RichTextStyle class . . . . . . . . . . . . . . . . . 2172. .

Bold property . . . . . . . . . . . . . . . . . . . . . 2174. .

Color property . . . . . . . . . . . . . . . . . . . . . 2174. .

Effects property . . . . . . . . . . . . . . . . . . . . 2175. .

Font property . . . . . . . . . . . . . . . . . . . . . 2176. .

FontSize property . . . . . . . . . . . . . . . . . . 2177. .

Italic property . . . . . . . . . . . . . . . . . . . . . 2177. .

Parent property . . . . . . . . . . . . . . . . . . . . 2178. .

StrikeThrough property . . . . . . . . . . . . . . 2178. .

Underline property . . . . . . . . . . . . . . . . . 2179. .

RichTextTab class . . . . . . . . . . . . . . . . . . 2179. .

Position property . . . . . . . . . . . . . . . . . . . 2181. .

Type property . . . . . . . . . . . . . . . . . . . . . 2182. .

clear method . . . . . . . . . . . . . . . . . . . . . . 2182. .

Session class . . . . . . . . . . . . . . . . . . . . . . 2182. .

AddressBooks property . . . . . . . . . . . . . . 2185. .

AgentContext property . . . . . . . . . . . . . . 2187. .

CommonUserName property . . . . . . . . . 2187. .

International property . . . . . . . . . . . . . . . 2188. .

IsOnServer property . . . . . . . . . . . . . . . . 2189. .

NotesVersion property . . . . . . . . . . . . . . 2190. .

Platform property . . . . . . . . . . . . . . . . . . 2191. .

ServerName property . . . . . . . . . . . . . . . 2192. .

UserName property . . . . . . . . . . . . . . . . . 2193. .

UserNameList property . . . . . . . . . . . . . . 2194. .

UserNameObject property . . . . . . . . . . . . 2194. .

createDateRange method . . . . . . . . . . . . . 2195. .

createDateTime method . . . . . . . . . . . . . . 2196. .

createLog method . . . . . . . . . . . . . . . . . . 2197. .

createName method . . . . . . . . . . . . . . . . 2197. .

createNewsletter method . . . . . . . . . . . . . 2198. .

createRegistration method . . . . . . . . . . . . 2198. .

createRichTextParagraphStyle method . . 2199. .

createRichTextStyle method . . . . . . . . . . 2199. .

evaluate method . . . . . . . . . . . . . . . . . . . 2200. .

freeTimeSearch method . . . . . . . . . . . . . . 2202. .

getDatabase method . . . . . . . . . . . . . . . . 2203. .

getDbDirectory method . . . . . . . . . . . . . . 2204. .

getEnvironmentString method . . . . . . . . 2205. .

getEnvironmentValue method . . . . . . . . 2207. .

getURLDatabase method . . . . . . . . . . . . . 2209. .

resolve method . . . . . . . . . . . . . . . . . . . . 2210. .

setEnvironmentVar method . . . . . . . . . . 2210. .

View class . . . . . . . . . . . . . . . . . . . . . . . . 2212. .

Aliases property . . . . . . . . . . . . . . . . . . . 2217. .

AllEntries property . . . . . . . . . . . . . . . . . 2218. .

BackgroundColor property . . . . . . . . . . . 2219. .

ColumnCount property . . . . . . . . . . . . . . 2221. .

ColumnNames property . . . . . . . . . . . . . 2222. .

Columns property . . . . . . . . . . . . . . . . . . 2222. .

Created property . . . . . . . . . . . . . . . . . . . 2223. .

HeaderLines property . . . . . . . . . . . . . . . 2224. .

IsAutoUpdate property . . . . . . . . . . . . . . 2225. .

IsCalendar property . . . . . . . . . . . . . . . . 2226. .

IsCategorized property . . . . . . . . . . . . . . 2227. .

IsConflict property . . . . . . . . . . . . . . . . . 2228. .

IsDefaultView property . . . . . . . . . . . . . . 2228. .

IsFolder property . . . . . . . . . . . . . . . . . . . 2229. .

IsHierarchical property . . . . . . . . . . . . . . 2230. .

IsModified property . . . . . . . . . . . . . . . . 2230. .

IsPrivate property . . . . . . . . . . . . . . . . . . 2231. .

IsProtectReaders property . . . . . . . . . . . . 2232. .

LastModified property . . . . . . . . . . . . . . 2233. .

Name property . . . . . . . . . . . . . . . . . . . . 2234. .

Parent property . . . . . . . . . . . . . . . . . . . . 2235. .

xxxiv Domino Designer Programming Guide

Readers property . . . . . . . . . . . . . . . . . . . 2236. .

RowLines property . . . . . . . . . . . . . . . . . 2237. .

Spacing property . . . . . . . . . . . . . . . . . . . 2237. .

TopLevelEntryCount property . . . . . . . . 2238. .

UniversalID property . . . . . . . . . . . . . . . 2238. .

clear method . . . . . . . . . . . . . . . . . . . . . . 2239. .

createViewNav method . . . . . . . . . . . . . . 2239. .

createViewNavFrom method . . . . . . . . . 2241. .

createViewNavFromCategory method . . 2242. .

createViewNavFromChildren method . . 2244. .

createViewNavFromDescendants method 2245. .

createViewNavMaxLevel method . . . . . . 2247. .

FTSearch method . . . . . . . . . . . . . . . . . . . 2248. .

getAllDocumentsByKey method . . . . . . . 2251. .

getAllEntriesByKey method . . . . . . . . . . 2253. .

getChild method . . . . . . . . . . . . . . . . . . . 2256. .

getColumn method . . . . . . . . . . . . . . . . . 2257. .

getDocumentByKey method . . . . . . . . . . 2258. .

getEntryByKey method . . . . . . . . . . . . . . 2260. .

getFirstDocument method . . . . . . . . . . . . 2262. .

getLastDocument method . . . . . . . . . . . . 2263. .

getNextDocument method . . . . . . . . . . . 2264. .

getNextSibling method . . . . . . . . . . . . . . 2266. .

getNthDocument method . . . . . . . . . . . . 2267. .

getParentDocument method . . . . . . . . . . 2268. .

getPrevDocument method . . . . . . . . . . . . 2270. .

getPrevSibling method . . . . . . . . . . . . . . 2271. .

refresh method . . . . . . . . . . . . . . . . . . . . 2272. .

remove method . . . . . . . . . . . . . . . . . . . . 2273. .

ViewColumn class . . . . . . . . . . . . . . . . . 2274. .

Alignment property . . . . . . . . . . . . . . . . . 2277. .

DateFmt property . . . . . . . . . . . . . . . . . . 2278. .

FontColor property . . . . . . . . . . . . . . . . . 2280. .

FontFace property . . . . . . . . . . . . . . . . . . 2282. .

FontPointSize property . . . . . . . . . . . . . . 2283. .

FontStyle . . . . . . . . . . . . . . . . . . . . . . . . . 2283. .

Formula property . . . . . . . . . . . . . . . . . . 2284. .

HeaderAlignment property . . . . . . . . . . . 2285. .

IsAccentSensitiveSort property . . . . . . . . 2285. .

IsCaseSensitiveSort property . . . . . . . . . . 2286. .

IsCategory property . . . . . . . . . . . . . . . . 2286. .

IsField property . . . . . . . . . . . . . . . . . . . . 2287. .

IsFormula property . . . . . . . . . . . . . . . . . 2287. .

IsHidden property . . . . . . . . . . . . . . . . . . 2288. .

IsHideDetail property . . . . . . . . . . . . . . . 2288. .

IsIcon property . . . . . . . . . . . . . . . . . . . . 2290. .

IsResize property . . . . . . . . . . . . . . . . . . . 2290. .

IsResortAscending property . . . . . . . . . . 2290. .

IsResortDescending property . . . . . . . . . 2291. .

IsResortToView property . . . . . . . . . . . . 2291. .

IsResponse property . . . . . . . . . . . . . . . . 2292. .

IsSecondaryResort property . . . . . . . . . . 2293. .

IsSecondaryResortDescending property . 2293. .

IsShowTwistie property . . . . . . . . . . . . . 2294. .

IsSortDescending property . . . . . . . . . . . 2294. .

IsSorted property . . . . . . . . . . . . . . . . . . . 2295. .

ItemName property . . . . . . . . . . . . . . . . . 2296. .

ListSep property . . . . . . . . . . . . . . . . . . . 2297. .

NumberAttrib property . . . . . . . . . . . . . . 2297. .

NumberDigits property . . . . . . . . . . . . . . 2299. .

NumberFormat property . . . . . . . . . . . . . 2299. .

Parent property . . . . . . . . . . . . . . . . . . . . 2300. .

Position property . . . . . . . . . . . . . . . . . . . 2300. .

TimeDateFmt property . . . . . . . . . . . . . . 2301. .

TimeFmt property . . . . . . . . . . . . . . . . . . 2301. .

TimeZoneFmt property . . . . . . . . . . . . . . 2302. .

Title property . . . . . . . . . . . . . . . . . . . . . . 2302. .

Width property . . . . . . . . . . . . . . . . . . . . 2302. .

ViewEntry class . . . . . . . . . . . . . . . . . . . 2304. .

ChildCount property . . . . . . . . . . . . . . . . 2306. .

ColumnIndentLevel property . . . . . . . . . 2306. .

ColumnValues property . . . . . . . . . . . . . 2307. .

xxxv

DescendantCount property . . . . . . . . . . . 2308. .

Document property . . . . . . . . . . . . . . . . . 2308. .

FTSearchScore property . . . . . . . . . . . . . . 2309. .

IndentLevel property . . . . . . . . . . . . . . . . 2309. .

IsCategory property . . . . . . . . . . . . . . . . 2310. .

IsConflict property . . . . . . . . . . . . . . . . . 2310. .

IsDocument property . . . . . . . . . . . . . . . 2310. .

IsTotal property . . . . . . . . . . . . . . . . . . . . 2311. .

IsValid property . . . . . . . . . . . . . . . . . . . 2311. .

NoteID property . . . . . . . . . . . . . . . . . . . 2312. .

Parent property . . . . . . . . . . . . . . . . . . . . 2312. .

SiblingCount property . . . . . . . . . . . . . . . 2313. .

UniversalID property . . . . . . . . . . . . . . . 2313. .

getPosition method . . . . . . . . . . . . . . . . . 2313. .

ViewEntryCollection class . . . . . . . . . . . 2314. .

Count property . . . . . . . . . . . . . . . . . . . . 2316. .

Parent property . . . . . . . . . . . . . . . . . . . . 2316. .

Query property . . . . . . . . . . . . . . . . . . . . 2317. .

addEntry method . . . . . . . . . . . . . . . . . . 2317. .

deleteEntry method . . . . . . . . . . . . . . . . . 2318. .

FTSearch method . . . . . . . . . . . . . . . . . . . 2320. .

getEntry method . . . . . . . . . . . . . . . . . . . 2321. .

getFirstEntry method . . . . . . . . . . . . . . . . 2323. .

getLastEntry method . . . . . . . . . . . . . . . . 2324. .

getNextEntry method . . . . . . . . . . . . . . . 2325. .

getNthEntry method . . . . . . . . . . . . . . . . 2326. .

getPrevEntry method . . . . . . . . . . . . . . . 2327. .

putAllInFolder method . . . . . . . . . . . . . . 2327. .

removeAll method . . . . . . . . . . . . . . . . . . 2329. .

removeAllFromFolder method . . . . . . . . 2330. .

stampAll method . . . . . . . . . . . . . . . . . . . 2331. .

updateAll method . . . . . . . . . . . . . . . . . . 2332. .

ViewNavigator class . . . . . . . . . . . . . . . . 2333. .

CacheSize property . . . . . . . . . . . . . . . . . 2336. .

MaxLevel property . . . . . . . . . . . . . . . . . 2336. .

ParentView property . . . . . . . . . . . . . . . . 2337. .

getChild method . . . . . . . . . . . . . . . . . . . 2337. .

getCurrent method . . . . . . . . . . . . . . . . . 2340. .

getFirst method . . . . . . . . . . . . . . . . . . . . 2340. .

getFirstDocument method . . . . . . . . . . . . 2342. .

getLast method . . . . . . . . . . . . . . . . . . . . 2343. .

getLastDocument method . . . . . . . . . . . . 2345. .

getNext method . . . . . . . . . . . . . . . . . . . . 2346. .

getNextCategory method . . . . . . . . . . . . 2346. .

getNextDocument method . . . . . . . . . . . 2347. .

getNextSibling method . . . . . . . . . . . . . . 2348. .

getNth method . . . . . . . . . . . . . . . . . . . . 2349. .

getParent method . . . . . . . . . . . . . . . . . . 2350. .

getPos method . . . . . . . . . . . . . . . . . . . . . 2351. .

getPrev method . . . . . . . . . . . . . . . . . . . . 2352. .

getPrevCategory method . . . . . . . . . . . . . 2353. .

getPrevDocument method . . . . . . . . . . . . 2354. .

getPrevSibling method . . . . . . . . . . . . . . 2354. .

gotoChild method . . . . . . . . . . . . . . . . . . 2355. .

gotoEntry method . . . . . . . . . . . . . . . . . . 2357. .

gotoFirst method . . . . . . . . . . . . . . . . . . . 2358. .

gotoFirstDocument method . . . . . . . . . . . 2359. .

gotoLast method . . . . . . . . . . . . . . . . . . . 2360. .

gotoLastDocument method . . . . . . . . . . . 2362. .

gotoNext method . . . . . . . . . . . . . . . . . . . 2363. .

gotoNextCategory method . . . . . . . . . . . 2364. .

gotoNextDocument method . . . . . . . . . . 2365. .

gotoNextSibling method . . . . . . . . . . . . . 2365. .

gotoParent method . . . . . . . . . . . . . . . . . 2366. .

gotoPos method . . . . . . . . . . . . . . . . . . . . 2366. .

gotoPrev method . . . . . . . . . . . . . . . . . . . 2367. .

gotoPrevCategory method . . . . . . . . . . . . 2367. .

gotoPrevDocument method . . . . . . . . . . . 2368. .

gotoPrevSibling method . . . . . . . . . . . . . 2369. .

Index . . . . . . . . . . . . . . . . . . . Index-1

xxxvi Domino Designer Programming Guide

Preface

The Domino Designer Programming Guide shows how to attach scripts,formulas, and Java to Domino™ applications.

This book is intended for developers who already understand theirworkstation’s operating environment, know how to use Domino, have anunderstanding of application development in Domino Designer, and havean understanding of LotusScript™ and JavaScript if applicable.

Structure of this guideThe Domino Designer Programming Guide contains ten chapters and isprinted in three volumes.

Volume 1: Formula Language

Chapter 1, “Programming Overview,” provides an overview of Dominoprogramming. This chapter describes where Java, LotusScript, JavaScript,and formulas can be attached, and provides examples.

Chapter 2, “User Interface,” explains the user interface to writing anddebugging scripts in Domino.

Chapter 3, “Formula Language Rules,” explains the rules of formulalanguage.

Chapter 4, “Formula Language Coding Guidelines,” provides guidelines forworking in Domino through formulas.

Chapter 5, “Formula Language @Functions A–Z,” is an A–Z reference of theDomino @functions.

Chapter 6, “Formula Language @Commands A–Z,” is an A–Z reference ofthe Domino @commands.

Volume 2: LotusScript Classes

Chapter 7, “LotusScript Classes Coding Guidelines,” provides guidelinesfor working in Domino through LotusScript.

Chapter 8, “LotusScript Classes A–Z,” is an A–Z reference of the Dominoclasses, methods, properties, and events.

xxxvii

Volume 3: Java Classes

Chapter 9, “Java Classes Coding Guidelines,” provides guidelines forworking in Domino through Java.

Chapter 10, “Java Classes A–Z,” is an A–Z reference of the Java Domino methods.

ConventionsIn Volume 1, keywords listed under “Syntax” are enclosed in brackets andbold face type.

In Volume 2, parameters which appear in brackets are optional.

Structure of Notes and Domino documentationDocumentation for Notes and Domino is provided online in three databasesavailable from the Help menu:

Notes 5 Client Help

Domino 5 Administration Help

Domino 5 Designer Help

In addition, the Administration and Designer documentation is available asprinted books. In Notes, select File - OtherHelp to see a table of all theavailable documentation. You can order books from the Lotus EducationWeb site at: www.lotus.com/education.

Documentation for the Notes ClientIn addition to the online Help, the printed book Step by Step provides atutorial for beginning Notes users.

Documentation for Domino AdministrationThe following table shows the printed books that comprise theAdministration documentation set. The information in these books is also found in the Domino 5 Administration Help online database.

Moving to Notes and Domino Release 5

Describes how to upgrade existing Dominoservers and Notes clients to Release 5. Alsodescribes how to move users to Domino fromother messaging systems.

xxxviii Domino Designer Programming Guide

Configuring the Domino Network

Explains how to configure a specific networkto work with Domino. Also illustrates how torun Notes using multiple network protocolsand individual protocols, such as AppleTalk, Banyan VINES, NetBIOS, Novell SPX(NetWare), and TCP/IP.

Administering the Domino System,Volumes 1 and 2

Describes how to set up and manage servers,users, server connections, mail, replication,security, calendars and scheduling, Webservers, NNTP services, billing, and systemmonitoring. Describes how to troubleshootsystem problems.

Administering Domino Clusters

Describes how to set up, manage, andtroubleshoot Domino clusters.

Managing Domino Databases Provides information on managingdatabases, including putting databases intoproduction, setting up access control lists andreplication, and maintaining databases.

Documentation for Domino DesignerThe following table shows the printed books that comprise the DominoDesigner documentation set. The information in these books is also found in the Domino 5 Designer Help online database.

Application Development withDomino Designer

Explains how to create all the designelements used in building Dominoapplications, how to share information withother applications, and how to customizeapplications.

Domino DesignerProgramming Guide Volume 1: Formula Language

Introduces programming in DominoDesigner and describes the formulalanguage, the @functions, and the@commands.

Domino DesignerProgramming GuideVolume 2: LotusScript Classes

Provides reference information on theLotusScript classes, which provide access todatabases and other Domino structures.

Domino DesignerProgramming GuideVolume 3: Java Classes

Provides reference information on the Javaclasses, which provide access to databasesand other Domino structures.

Preface xxxix

LotusScript Language Guide Describes the basic building blocks ofLotusScript, how to use the language tocreate applications, an overview of theLotusScript programming language, and acomprehensive list of language elements.

Domino Enterprise Integration Guide

Provides information on how to set upDomino Connectors, how to utilize DominoEnterprise Connection Services (DECS) toaccess enterprise data in real-time, andreference material for programming with the LotusScript Extension for DominoConnectors.

Managing Domino Databases Provides information on managingdatabases, including putting databases intoproduction, setting up access control lists andreplication, and maintaining databases.

Step by Step

Setting up a Domino ServerMoving to Notes and Domino Release 5Configuring the Domino NetworkAdministering Domino ClustersAdministering the Domino System, Volume 1Administering the Domino System, Volume 2

Application Development with Domino DesignerDomino Designer Templates GuideDomino Designer Programming Guide, Volume 1: Formula LanguageDomino Designer Programming Guide, Volume 2: LotusScript ClassesDomino Designer Programming Guide, Volume 3: Java ClassesLotusScript Language GuideDomino Enterprise Integration Guide

Managing Domino Databases

AdministrationHelp

Release Notes

DesignerHelp

not available in print

Domino ObjectsPosters

NotesHelp*

*

*

**

** print only

xl Domino Designer Programming Guide

Chapter 1 Programming Overview

This chapter describes how to attach Java, JavaScript, LotusScript, andformula code to Domino objects.

Programming in Domino

Formula, LotusScript, Java, and JavaScript code provide an integralprogramming interface to Domino Designer. You attach code to variousobjects depending on need. For example, if you create a computed field in aform, you would attach a formula to compute the value of the field. Or youcould attach JavaScript code to the onFocus event of a field; this code wouldexecute whenever a user places focus on the field. Or you might decide tocreate a formula, LotusScript, or Java agent to automatically update all thedocuments in a database at scheduled times.

Domino also provides a programming interface for Java applications andapplets. These applications and applets can operate locally by accessinginstalled Domino software or remotely by connecting to a Domino serverusing IIOP protocols.

The topic, Domino Designer Templates, provides templates and examples forthe common cases where you use code. For these cases, you do not have tolearn how to program. Beyond these cases, refer to this manual for completeguidelines and reference material for programming in Domino.

Where to use scripts and formulasBefore you write code, make sure that a simple action won’t do the task.You can design some objects with simple actions in forms or views that donot require programming.

While a particular Domino object determines what programming interfacesare available, consider these guidelines:

Formulas are expressions that have program-like attributes. Forexample, you can assign values to variables and use a limited controllogic. The formula language interface to Domino Designer is throughcalls to @functions and @commands.

1

In general, formulas are best used for working within the object that theuser is currently processing, for example, to return a default value to afield or determine selection criteria for a view. Additionally, formulasprovide better performance in some situations and may be moreconvenient for simple applications.

JavaScript is a cross-platform, object-oriented scripting language.Header scripts may be written in the Programmer’s pane by selecting JSHeader from the Objects tab and typing your script in the Script Area.Scripts may also be attached to specific events such as onClick, or toobjects such as buttons. JavaScript may not be written in an agent.Domino oversees the compilation and loading of user scripts, but doesnot store JavaScript in compiled form.

JavaScript is best used for Web applications, or when a singleapplication will be used in both the Notes and Web environments.

LotusScript is a full object-oriented programming language. Its interfaceto Domino is through predefined classes. Domino oversees thecompilation and loading of user code, and automatically includes theDomino class definitions.

LotusScript is best used for accessing existing objects, for example, tochange a value in one document based on values in other documents.LotusScript provides some capabilities that formulas do not, such as theability to manipulate a database access control list (ACL).

Java is a full object-oriented programming language. Its interface toDomino is through predefined classes. It is comparable to LotusScriptin agents but cannot be attached to events in the Domino UI. Dominooversees the compilation and loading of user code for agents; the codecan be written natively or imported.

Java can be used in agents. Java applications and applets, written andcompiled outside of Domino, can access Domino through the classinterface.

2 Domino Designer Programming Guide, Volume 1: Formula Language

Table of Domino Objects

The following table outlines the programmable objects in Domino. The tablespecifies the scope of the object and whether the object supports simpleactions, formulas, LotusScript, Java, or JavaScript.

Scope Domino object Supports

Workspace SmartIcons® Formula

Database Replication formula Formula

Agent FormulaSimple actionLotusScriptJava

Event LotusScript Formula

Navigator design Hotspot FormulaSimple actionLotusScript

View or folder design Form formula Formula

Selection formula FormulaEasy (simple action)

Column formula FormulaSimple actionField

Action FormulaSimple actionLotusScriptJavaScript

Hide action formula Formula

Event FormulaLotusScript

Form design Window title formula Formula

Section title formula FormulaText

Section access formula Formula

Insert subform formula Formula

Hidden paragraph formula Formula

continued

Chapter 1: Programming Overview 3

Scope Domino object Supports

Action FormulaSimple actionLotusScriptJavaScript

Hide action formula Formula

Event FormulaLotusScriptJavaScript

Hotspot (button or action) FormulaSimple actionLotusScriptJavaScript

Hotspot (link or formula pop-up) Formula

Layout region designon forms

Hotspot (action) FormulaSimple actionLotusScriptJavaScript

Field design on forms Default value formula Formula

Input translation formula Formula

Input validation formula Formula

Value formula for a computedfield

Formula

Keyword field formula Formula

Event LotusScriptJavaScript

Document (Edit Mode)Rich text field

Section title formula FormulaText

Hidden paragraph formula Formula

Hotspot (button or action) FormulaSimple actionLotusScriptJavaScript

Hotspot (link or formula pop-up) Formula

4 Domino Designer Programming Guide, Volume 1: Formula Language

SmartIcons

A SmartIcons button executes a formula when you click it. Domino comeswith over 100 predefined SmartIcons buttons, including buttons for mostmenu commands. Domino also includes over a dozen custom SmartIconsbuttons to which you can assign your own formulas. SmartIcons buttons areassociated with each user’s workspace; they are not associated withdatabases and are not shared among users.

A SmartIcons formula runs on the user’s workstation.

Examples: SmartIcons1. This SmartIcons formula opens the names.nsf database on the DOC

server to the People view:@Command([FileOpenDatabase]; "DOC" : "names.nsf";"People")

2. This SmartIcons formula presents the user with the list of databases in adatabase catalog, and opens the database that the user selects. The first@DbColumn puts a list of the values in column 4 of the Databases by_Replica ID view in the temporary variable titles. The second@DbColumn puts a list of the values in column 2 of the Databases by_Replica ID view in the temporary variable servers. The third@DbColumn puts a list of the values in column 3 of the Databases by_Replica ID view in the temporary variable databases. The temporaryvariable list combines titles, servers, and databases for presentation tothe user in @Prompt. The formula then parses the return value from@Prompt into a server name and database name for inclusion in the@command FileOpenDatabase.titles := @DbColumn(""; "doc":"catalog.nsf"; "Databases by_Replica ID"; 4);servers := @DbColumn(""; "doc":"catalog.nsf"; "Databasesby _Replica ID"; 2);databases := @DbColumn(""; "doc":"catalog.nsf"; "Databasesby _Replica ID"; 3);list := titles + " *-* " + servers + " *:* " + databases;member := @Prompt([OKCANCELLIST]; "Open Database"; "Selecta database"; ""; list);server := @Left(@Right(member; " *-* "); " *:* ");database := @Right(member; " *:* ");@Command([FileOpenDatabase]; server:database)

Chapter 1: Programming Overview 5

Replication formulas

A replication formula selects the documents that are pulled into the currentdatabase during replication.

A replication formula must end with a SELECT statement. If the laststatement in the formula is a logical expression, Domino turns it into aSELECT statement by inserting the keyword SELECT.

A replication formula runs on the server or workstation containing theformula’s database.

Examples: Replication formulas1. The default replication formula for a database replicates all documents.

SELECT @All

2. This formula replicates only documents containing East in the Regionfield.SELECT Region = "East"

3. This formula, which would be useful in a replica of a mail database,does not replicate documents whose From field is Arnold Runion orMary Chen.SELECT !(From="Arnold Runion" | From="Mary Chen")

AgentsAn agent is a user procedure that you can trigger through a number ofmechanisms. An agent runs on:

The user’s workstation if the agent’s trigger is: Manually, If DocumentHas Been Modified, If Documents Have Been Pasted.

The server or workstation containing the agent if the agent’s trigger is:If New Mail Has Arrived, On Schedule.

You can code agents in the formula language, LotusScript, and Java, andyou can use Domino-supplied agents. Before writing your own agent, see ifa Domino-supplied agent will do the job.

Formula-based agents run iteratively on the documents in the database.You can apply search criteria through the agent interface to specify whichdocuments in the database are to be processed. A SELECT statement in theformula further limits the search. If you do not include a SELECT statementin the formula, Domino Designer appends a “SELECT @All” statement.Except for “SELECT @All,” a SELECT statement must be the first statementin the formula to be effective.

6 Domino Designer Programming Guide, Volume 1: Formula Language

LotusScript and Java agents run once. You supply the search criteria andthe iteration through the language constructs. Search criteria appliedthrough the agent interface are effective only throughUnprocessedDocuments in NotesDatabase (LotusScript) orgetUnprocessedDocuments in AgentContext (Java).

Examples: Agents1. This LotusScript code writes a value to the Category field based on the

value of the TotalSales field of each document in the database. Comparewith Examples 2 and 3, which use Java and formula solutions. Thescript example requires more lines of code than the formula solutionbut includes the algorithm for finding the documents being processed.Sub Initialize Dim session As New NotesSession Dim db As NotesDatabase Dim dc As NotesDocumentCollection Dim doc As NotesDocument Set db = session.CurrentDatabase Set dc = db.AllDocuments Set doc = dc.GetFirstDocument While Not(doc Is Nothing) category = doc.Category totalSales = doc.TotalSales Select Case totalSales(0) Case Is >= 200000 : category(0) = "Above Quota" Case Is >= 100000 : category(0) = "OK" Case Else : category(0) = "Below Quota" End Select doc.Category = category Call doc.Save(True, False) Set doc = dc.GetNextDocument(doc) WendEnd Sub

2. This Java agent writes a value to the Category field based on the valueof the TotalSales field of each document in the database. Compare withExamples 1 and 3, which use LotusScript and formula solutions. Aswith LotusScript, the Java code includes the algorithm for finding thedocuments being processed.import lotus.domino.*;public class JavaAgent extends AgentBase { public void NotesMain() { try { Session session = getSession(); AgentContext agentContext =session.getAgentContext();

Chapter 1: Programming Overview 7

// (Your code goes here) Database db = agentContext.getCurrentDatabase(); DocumentCollection dc = db.getAllDocuments(); Document doc = dc.getFirstDocument(); while (doc != null) { double totalSales =doc.getItemValueDouble("TotalSales"); if (totalSales >= 200000) doc.replaceItemValue("Category", "Above quota"); else if (totalSales >= 100000) doc.replaceItemValue("Category", "OK"); else doc.replaceItemValue("Category", "Below quota"); doc.save(true, false); doc = dc.getNextDocument(); }

} catch(Exception e) { e.printStackTrace(); } }}

3. This formula writes a value to the Category field based on the value ofthe TotalSales field of each document in the database, assuming that alldocuments are selected for processing. Compare with Examples 1 and2, which use LotusScript and Java solutions. The formula executes onceon each document selected by combining outside criteria with theSELECT statement. Data declarations are implicit and formula syntax iscryptic making for compact source code.FIELD Category := @If(TotalSales >= 200000; "Above Quota";TotalSales >= 100000; "OK"; "Below Quota");SELECT @All

4. This formula writes a value to the Category of selected documentsbased on the value of the TotalSales field. The SELECT statement, if it isnot SELECT @All, must precede the statements in the formula that itapplies to.SELECT TotalSales >= 200000;FIELD Category := "Above Quota"

5. This LotusScript code finds the sum of all OrderTotal fields in adatabase for one day, and writes a new record to the databasecontaining the daily total. Each record in the database hasOrderNumber, Date, and OrderTotal fields. The script finds all thedocuments in the database, then uses a loop and a comparison of datesto limit processing to today’s documents. For each document, the script

8 Domino Designer Programming Guide, Volume 1: Formula Language

adds the OrderTotal to a dailyTotal variable. The script places thewords “DAILY TOTAL” in the OrderNumber field for the documentthat it writes, and places the dailyTotal value in the OrderTotal field.Sub Initialize Dim session As New NotesSession Dim db As NotesDatabase Dim dc As NotesDocumentCollection Dim doc As NotesDocument Dim dateDate As New NotesDateTime("") Dim dateToday As New NotesDateTime("Today") Set db = session.CurrentDatabase Set dc = db.AllDocuments dailyTotal = 0 Set doc = dc.GetFirstDocument While Not(doc Is Nothing) odate = doc.Date dn = Datenumber(Year(odate(0)), _ Month(odate(0)), Day(odate(0))) orderNumber = doc.OrderNumber If dn = Today _ And orderNumber(0) <> "DAILY TOTAL" Then orderTotal = doc.OrderTotal dailyTotal = dailyTotal + orderTotal(0) End If Set doc = dc.GetNextDocument(doc) Wend Dim docNew As New NotesDocument(db) Set itm = _ docNew.AppendItemValue("OrderNumber", "DAILY TOTAL") Set itm = _ docNew.AppendItemValue("OrderTotal", dailyTotal) Set itm = _ docNew.AppendItemValue("Date", Date$) Call docNew.Save(True, False)End Sub

Chapter 1: Programming Overview 9

Actions

An action is a custom procedure that you can associate with a view or form.When you open the view or open a document based on the form, the actionbecomes available as a menu command under Actions and/or as a buttonon an action bar.

You can conditionally suppress availability of an action on the menu oraction bar with a “Hide action if formula is true” formula.

Actions run on the user’s workstation.

Examples: Actions1. This LotusScript action prints the name of each Domino database in the

Domino data directory on the computer running the script. TheFirstDatabase and NextDatabase methods of NotesDbDirectory walkthrough all the databases for the specified server where null defaults tothe current computer.Sub Click(Source As Button) Dim directory As New NotesDbDirectory("") Dim db As NotesDatabase Set db = directory.GetFirstDatabase(DATABASE) While Not(db Is Nothing) Messagebox db.Title Set db = directory.GetNextDatabase() Wend Messagebox "The End"End Sub

2. This formula lists the names in the Address Book on the CORP1 server,lets the user select any number of names, combines the selected namesinto a string using a comma and a space to separate names, and insertsthe string into the current field. This action works best when the user isin the SendTo field of a mail database.last := @Left(@DbColumn(""; "CORP1" : "names.nsf";"People"; 1); ",");first := @RightBack(@DbColumn(""; "CORP1" : "names.nsf";"People"; 2); " ");list := first + " " + last;name := @Prompt([OKCANCELLISTMULT]; "Send To"; "Who areyou sending this memo to?"; ""; list);@Command([EditInsertText]; @Implode(name; ", "))

10 Domino Designer Programming Guide, Volume 1: Formula Language

3. This formula is a “Hide action if formula is true” formula. The actionbecomes available on the form menu or action bar only if the fieldOrderTotal is 100 or less. (If the user just entered a value forOrder_Total in the current document, a document refresh must occurbefore the new value is effective.)OrderTotal > 100

4. These LotusScripts collectively force the user to use an action to placean existing document in Edit mode. The action script places the currentdocument in Edit mode. The Postopen and Querychangemode eventscripts prevent the user from changing to Edit mode through othermeans such as Actions - Edit Document (CTRL+E).'(Globals) object, (Declarations) eventDim allowEdit As Integer

'(Form) object, Postopen eventSub Postopen(Source As Notesuidocument) 'Let document pass if new or not in EditMode 'Otherwise if existing document is in EditMode ' Set allowEdit so Querymodechange doesn't reprocess ' Turn EditMode off so document opens in Read mode ' Tell the user to use the action If source.EditMode And Not source.IsNewDoc Then allowEdit = True source.EditMode = False Messagebox _ "Use Edit Mode action to edit document" Else allowEdit = False End IfEnd Sub

'(Form) object, Querymodechange eventSub Querymodechange(Source As Notesuidocument, Continue AsInteger) 'Allow user to proceed, and turn off allowEdit if ' user clicked the action (allowEdit on) ' already processed by Postopen (allowEdit on) ' trying to get out of Edit mode ' (allowEdit off but EditMode on) 'Tell user to click action if changing existingdocument ' to Edit mode and not already processed by Postopen ' (allowEdit and EditMode off) If allowEdit Or (source.EditMode And Not allowEdit)Then allowEdit = False Else

Chapter 1: Programming Overview 11

Messagebox _ "Use Edit Mode action to edit document" continue = False End IfEnd Sub

'(Action) object, Click eventSub Click(Source As Button) Dim workspace As New NotesUIWorkspace Dim uidoc As NotesUIDocument Set uidoc = workspace.CurrentDocument 'Turn on allowEdit so Querymodechange will let itpass 'Turn on EditMode allowEdit = True uidoc.EditMode = TrueEnd Sub

HotspotsIn form design, navigator design, layout region design, and rich text fields,you can create hotspots. A hotspot activates when the user selects it and canbe of several types:

A link hotspot jumps to another object. As the designer, you supply thelink.

A text pop-up displays text. As the designer, you supply literal text.

A button performs an action. As the designer, you supply a simpleaction, or formula, LotusScript, or JavaScript code.

A formula pop-up displays text based the result of a formula. As thedesigner, you supply a formula.

An action hotspot performs an action. As the designer, you supply asimple action, or formula, LotusScript, or JavaScript code.

Buttons and action hotspots are the same except that a button appears as abutton and an action hotspot appears as highlighted text.

A hotspot runs on the user’s workstation.

Examples: Hotspots1. This JavaScript code shows an alert when activated by the onClick

event of a button or action hotspot.alert("This is the alert box.")

12 Domino Designer Programming Guide, Volume 1: Formula Language

2. This JavaScript code prompts the user for his or her name whenactivated by the onClick event of a button or action hotspot.var messagevar defaultanswermessage = "Please enter your name:";defaultanswer = myForm.from.value;result = prompt(message, defaultanswer);if(result) { myForm.results.value = result;}

3. This JavaScript example could be attached to the onClick event for abutton or action hotspot. It determines how a mail message is delivered.For “bugs,” the mail is directed to “SprManager.” Other requests aredirected to “WishListManager.” The final line in this script launchesmail.var isBug = confirm("Are you reporting a bug?");var recipient = isBug? "SprManager@xyz.com" :"WishListManager@xyz.com";document.location = "mailto:" + recipient;

4. This LotusScript button or action hotspot is useful in a mail message toa group of persons. When the recipient clicks the hotspot, the scriptsends a mail message indicating “Yes” or “No” for the “RSVP.” Fortesting, the name of the current user is used—in practice, you woulduse your name. Compare with the next example, which uses a formulasolution.'(Declarations)Const MB_YESNO = 4Const MB_ICONQUESTION = 32Const IDYES = 6

'(Click event)Sub Click(Source As Button) Dim session As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument Set db = session.CurrentDatabase Set doc = New NotesDocument(db) yesno = Messagebox _ ("Do you want to attend?", MB_YESNO+MB_ICONQUESTION) If yesno = IDYES Then rsvp = "Yes" Else rsvp = "No" Call doc.AppendItemValue("Subject", "RSVP") Call doc.AppendItemValue("Body", rsvp) Call doc.Send(True, session.UserName)End Sub

Chapter 1: Programming Overview 13

5. This formula button or action hotspot is useful in a mail message to agroup of persons. When the recipient clicks the hotspot, the formulasends a mail message indicating “Yes” or “No” for the “RSVP.” Fortesting, the name of the current user is used — in practice, you can useyour name. Compare with the previous example, which uses aLotusScript solution.yesno := @Prompt([YESNO]; "RSVP"; "Do you want toattend?");rsvp := @If(yesno; "Yes"; "No");@MailSend(@UserName; ""; ""; "RSVP"; ""; rsvp; "")

6. This LotusScript button or action hotspot displays the sum of allOrderTotal fields in a database for one day. Each record in the databasehas OrderNumber, Date, and OrderTotal fields. The script finds all thedocuments in the database, then uses a loop and a comparison of datesto limit processing to today’s documents. For each document, the scriptadds the OrderTotal to a dailyTotal variable.Sub Click(Source As Button) Dim session As New NotesSession Dim db As NotesDatabase Dim dc As NotesDocumentCollection Set db = session.CurrentDatabase Set dc = db.AllDocuments dailyTotal = 0 Set doc = dc.getFirstDocument While Not(doc Is Nothing) odate = doc.Date dn = Datenumber(Year(odate(0)), _ Month(odate(0)), Day(odate(0))) orderNumber = doc.OrderNumber If dn = Today _ And orderNumber(0) <> "DAILY TOTAL" Then orderTotal = doc.OrderTotal dailyTotal = dailyTotal + orderTotal(0) End If Set doc = dc.getNextDocument(doc) Wend Messagebox Format(dailyTotal, "Currency")End Sub

7. This action hotspot is part of a navigator. The formula prompts the userand opens a view selected by the user.view := @Prompt([OKCANCELLIST]; "Which view do you want toopen?"; ""; ""; "By first name" : "By last name");@Command([OpenView]; view)

14 Domino Designer Programming Guide, Volume 1: Formula Language

8. This formula shows “pop-up text from a formula.” You can highlight asa hotspot the following text in a form: “Please note your user name andthe current date and time.” The formula associated with the hotspotwould evaluate to a text string containing the necessary information."Your user name is " + @UserName + @NewLine + "The dateand time are " + @Text(@Now)

Form, selection, and column formulasAs part of the view design process, you specify form, selection, and columnformulas. These formulas run on the user’s workstation.

Form formulasA form formula determines which forms are used for composing anddisplaying documents under different conditions.

A form formula is optional. Domino Designer selects a form in thefollowing preference order:

1. Form stored in the document.

2. Form specified in the form formula.

3. Form with which the document was created.

4. Default form for the database.

A form formula must evaluate to the name of a form.

Example: Form formulasThis formula creates new documents using the “Open New Discussion”form and accesses existing documents using the “Main Topic” form.

@If(@IsNewDoc; "Open New Discussion"; "Main Topic")

Selection formulasA selection formula selects the documents that appear in a view.

A selection formula must end with a SELECT statement. If the laststatement in the formula is a logical expression, Domino turns it into aSELECT statement by prepending the keyword SELECT.

Examples: Selection formulas1. The default selection formula for a database is:

SELECT @All

Chapter 1: Programming Overview 15

2. This formula selects only documents based on the “Main” or “Firstresponse” form:SELECT Form="Main" | Form="First response"

3. These examples are from the mail template mail.ntf. The first exampleis the selection formula for the Drafts By Category view; the documentsselected for this view are those where both the DeliveredDate andPostedDate are not filled in (are null). The second example is theselection formula for the Sent By Category; the documents selected forthis view are those where the PostedDate is filled in, but theDeliveredDate is not. The third example is the selection formula for theReceived By Category view; in this case, either the DeliveredDate or theDate field is filled in.SELECT DeliveredDate = "" & PostedDate = ""

SELECT DeliveredDate = "" & PostedDate != ""

SELECT DeliveredDate != "" | Date != ""

Column formulasA column formula determines what is displayed in a column of a view.

A column formula must evaluate to a text string.

Examples: Column formulas1. This formula specifies the column contents as the Subject field.

Subject

2. This formula specifies the column contents as the Subject field followedby a blank (or nothing if the Subject field is empty), followed by theFrom field in parentheses. By default, the From field contains the nameof the author of the document.DEFAULT From := @Author;@If(Subject != ""; Subject + " "; "") + "(" + From " ")"

3. This formula specifies the column contents as the number 1 forWeekdays forms and 2 for all other forms. If you make this column thefirst column, hidden, and sorted in ascending sequence, you force theWeekdays document (or documents) to the top of the view.@If(Form = "Weekdays"; 1; 2)

16 Domino Designer Programming Guide, Volume 1: Formula Language

4. This formula reformats the contents of Person_Name to put the lastname first followed by a comma, a space, and the first name.@If(@Contains(Person_Name; " "); @Right(Person_Name; " ")+ ", " + @Left(Person_Name; " "); Person_Name)

5. This formula puts the name of the current weekday in the column,except that Saturdays and Sundays are treated as Fridays.T := @Weekday(@Now);@If(T = 2; "Monday"; T = 3; "Tuesday"; T = 4; "Wednesday";T = 5; "Thursday"; "Friday")

Window title, section access, and insert subform formulas

As part of the form design process, you specify window title, section access,and insert subform formulas. These formulas run on the user’s workstation.

Window title formulasA window title formula generates the text that appears in the title bar ofdocuments using the form. The formula must evaluate to a text or numericvalue, except that a single field of any type is permissible.

Rich text fields cannot be used in window title formulas.

Examples: Window title formulas1. This formula displays the static text “Focus Group Discussion” in the

title bar."Focus Group Discussion"

2. This formula displays the static text “New Topic” for a new document.For an existing document, the formula displays the contents of theSubject field followed by text indicating the number of responsedocuments associated with this document.@If(@IsNewDoc; "New Topic"; Subject +@DocDescendents(" (No Responses)"; "(1 Response)"; "(%Responses)"))

3. This formula displays a window title suited to a Response or aResponse to Response document.@If(@IsNewDoc; "New Response to " + Subject;"Response " + @DocNumber("") + " of " + @DocSiblings + "to " + Subject)

Chapter 1: Programming Overview 17

4. This formula, which evaluates to a time-date value, is legal because it isa single field.@DateCreated;

5. In this formula, the time-date field must be explicitly converted to textbecause it is part of an expression."Response created on " + @Text(DateCreated)

Section access formulasA section access formula specifies the names of users who can edit the fieldsin the section. Other users only have reader access to the section. However,this specification does not override the access control list for the database.

A section access formula must evaluate to a name or a list of names.

Examples: Section access formulas1. This formula restricts edit access to a section to Mary Chen and Donna

Hill."Mary Chen" : "Donna Hill"

2. This formula restricts edit access to the section to those users listed inColumn 1 of the By Person view of the current database.@DbColumn(""; ""; "By Person"; 1)

Insert subform formulasAn insert subform formula specifies the name of a subform for insertioninto the form. The formula must evaluate to a text value that is the name ofa subform. An invalid name results in a run-time error.

Example: Insert subform formulasThis example uses the Business Address subform if the Categories field is“Business” and uses the Home Address subform otherwise.

@If(Categories = "Business"; "Business Address"; "HomeAddress")

18 Domino Designer Programming Guide, Volume 1: Formula Language

Section title and hidden paragraph formulas

In form design and in rich text fields, you can use formulas to generatesection titles and hide paragraphs. These formulas run on the user’sworkstation.

Section title formulasThe title for a collapsible section in a form or rich text field can be generatedfrom a formula. A section title formula must evaluate to a text or numericvalue, except that a single field of any type is permissible.

Example: Section title formulasIf Name has the value “Mary Chen,” this formula prints “Mary Chen’spersonal information” as the section title.

Name + "\'s personal information"

Hidden paragraph formulasA paragraph in a form or rich text field can be hidden (not displayed) if anassociated formula is true.

Example: Hidden paragraph formulasThis formula hides a paragraph if the value of the Department field is notSales.

Department != "Sales"

Events

You can write scripts and formulas to handle events that occur duringprocessing as shown in the table “Event descriptions” topic. Forinformation on the sequence of events based on certain tasks, see the table“Event sequencing.”

In the Programmer’s pane, you access objects and events through theObjects tab in the Info List.

Database, view, form, and field events run on the user’s workstation.

Chapter 1: Programming Overview 19

Examples: Events1. This LotusScript event executes when a database opens. It opens a

particular view depending on the value of the OrgUnit1 part of theuser’s name.Sub Postopen(Source As Notesuidatabase) Dim session As New NotesSession Dim userName As NotesName Set userName = session.CreateName(session.UserName) Select Case userName.OrgUnit1 Case "Marketing" Call Source.OpenView("Marketing") Case "Engineering" Call Source.OpenView("Engineering") Case Else Call Source.OpenView("General") End SelectEnd Sub

2. This LotusScript event executes before the Engineering view opens. Ifthe OrgUnit1 part of the user’s name is not “Engineering,” the scriptdisplays a message and sets Continue to False so that the view does notopen.Sub Queryopen(Source As Notesuiview, Continue As Variant) Dim session As New NotesSession Dim userName As NotesName Set userName = session.CreateName("session.UserName") If userName.OrgUnit1 <> "Engineering" Then Continue = False Messagebox _ "This view is reserved for engineering",, _ "No admittance" End IfEnd Sub

3. This LotusScript event executes when the user opens a document. Thedocument goes into edit mode even if the user doesn’t open it that way,the ruler opens, and all sections expand.Sub Postopen(Source As Notesuidocument) source.EditMode = True source.Ruler = True Call source.ExpandAllSectionsEnd Sub

20 Domino Designer Programming Guide, Volume 1: Formula Language

4. This JavaScript button script alters the value of one of the fields on theassociated form. In this example, a document can be assigned a priorityrating from 1 to 10, with 1 being the highest priority. The document’spriority rating is held in a field called “Priority” on the form. Thebutton “Increase Priority” allows users to increase the priority withoutthe need to edit the field directly. When the button is clicked, thePriority field’s value is decreased by 1, assigning it a higher priorityrating. The script will not allow a priority of less than 1 to be assigned.//get a handle to the Priority fieldvar priorityField = document.forms[0].Priority;//get its current integer valuevar currentPriority = parseInt(priorityField.Value);//increase the priority (1 is the highest, 10 is thelowest)var newPriority = Math.max(currentPriority -1, 1);//update the Priority field valuepriorityField.value = newPriority;

5. This LotusScript event executes when the user enters the FullNamefield. The script fills in the FullName field by concatenating theFirstName field, a space, and the LastName field.Sub Entering(Source As Field) Dim workspace As New NotesUIWorkspace Dim uidoc As NotesUIDocument Set uidoc = workspace.CurrentDocument firstName = uidoc.FieldGetText("FirstName") lastName = uidoc.FieldGetText("LastName") fullName = firstName & " " & lastName Call uidoc.FieldSetText("FullName", fullName)End Sub

6. This JavaScript event executes when the focus moves away from thefield. The script trims the white space from the start and end of the fieldand then tests whether the value is a valid zip code. If it is invalid, amessage is displayed in the status bar and the focus is set back onto thefield itself. Note that “trim” and “isValidZipCode” are user-definedfunctions that must be available from within the onBlur handler.var zipCode = trim(this.value);if(!isValidZipCode(zipCode)){ window.status = "Illegal zip code."; this.focus();}

Chapter 1: Programming Overview 21

7. This LotusScript event executes when the user exits from the Age field.The script forces the user to enter a numeric value.Sub Exiting(Source As Field) Dim workspace As New NotesUIWorkspace Dim uidoc As NotesUIDocument Set uidoc = workspace.CurrentDocument age = uidoc.FieldGetText("Age") If age = "" Or Not Isnumeric(age) Then While age = "" age = Inputbox _ ("Whoa! you must enter an age") Wend While Not Isnumeric(age) age = Inputbox("Age must be numeric") Wend Call uidoc.FieldSetText("Age", age) End IfEnd Sub

8. This LotusScript event executes when the user exits from a field. Thescript sends a mail message to Mary Chen.Sub Exiting(Source As Field) Dim session As New NotesSession Dim db As NotesDatabase Set db = session.CurrentDatabase Dim doc As New NotesDocument(db) doc.Form = "Form" doc.Subject = "Sales Updated" doc.Body = "Sales updated by " & session.UserName Call doc.Send(True, "Mary Chen")End Sub

Field design formulas

As part of the field design process, you can write the following formulas torun on the user’s workstation:

Default value formula

Input translation formula

Input validation formula

Value formula for a computed field

Keyword field formula

22 Domino Designer Programming Guide, Volume 1: Formula Language

Default value formulasA default value formula provides an initial value for a field. This formulaexecutes when a document is created, and for uneditable rich text fieldswhen the document is saved. The user can change the value in the fieldexcept for uneditable rich text fields. You must specify a default valueformula for an uneditable rich text field.

A default value formula must evaluate to a value suitable for storage in thecurrent field.

Example: Default value formulasThis default value formula makes the initial value for a field the usersurname in uppercase letters. The @Left function returns the part of thename to the left of the first slash, if there is a slash, which extracts the nameproper from the hierarchical name. The @RightBack function returns thepart of the name to the right of the last space.

@UpperCase(@RightBack(@Left(@UserName; "/"); " "))

Input translation formulasAn input translation formula converts the data entered in the field to adjustthe field value or make the field conform to a format. This formula executeswhen the document containing the field is saved.

An input translation formula must evaluate to a value suitable for storagein the current field.

Example: Input translation formulasThis input translation formula makes the Subject field proper case (initialcapitals) with no extraneous spaces.

@Trim(@ProperCase(Subject))

Input validation formulasAn input validation formula checks the data entered in the field againstcriteria that you specify. This formula executes after the input translationformula.

An input validation formula should end with a call to @Success or @Failure.

Examples: Input validation formulas1. This input validation formula doesn’t let the Cost field exceed 100.

@If(Cost<100; @Success; @Failure("Cost must be less than$100))

Chapter 1: Programming Overview 23

2. This formula forces the user to enter a ten-digit number. The formularemoves up to two hyphens if they are present. The formula convertsthe result to a number and returns a failure if an error occurs on theconversion. The formula converts the number back to text and checksits length, returning a failure if the length is incorrect. This last step isnecessary because @TextToNumber successfully converts, for example,123A to 123.N1 := @If(@Contains(Home_Phone; "-"); @Left(Home_Phone;"-") + @Right(Home_Phone; "-"); Home_Phone);N2 := @If(@Contains(N1; "-"); @Left(N1; "-") + @Right(N1;"-"); N1);N := @TextToNumber(N2);@If(@IsError(N); @Failure("Home phone must bezip-xxx-xxxx."); @Success);@If(@Length(@Text(N)) != 10; @Failure("Home phone must bezip-xxx-xxxx."); @Success)

Value formulas for a computed fieldsIf the field type is Computed, Computed for display, or Computed whencomposed, you must write a formula to specify the field contents. Thisformula executes: for Computed, when the document is created and when itis saved; for Computed for display, whenever the document is opened; forComputed when composed, only when the document is created. Its valuecannot be changed.

A computed field formula must evaluate to a value suitable for storage inthe current field.

Example: Value formulas for a computed fieldsThis computed field formula makes the Date field contain the time and datethat the document is created.

@Created

Keyword field formulasA keyword field presents the user with a list of keywords for entry into thefield. The list can be the result of a formula or a list of constants.

A keyword field formula must evaluate to a value or list of values suitablefor storage in the current field.

24 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: Keyword field formulas1. This formula uses as a keyword list the values in column 1 of the

Names view in the current database.@DbColumn(""; ""; "Names"; 1)

2. This formula reformats the user name as last name, comma, first name,taking care to handle hierarchical names. The formula looks up thereformatted user name in the Phone Numbers view of the currentdatabase and returns a list consisting of the values found in columns 2and 3.n := @Left(@UserName; "/");k := @Right(n; " ") + ", " + @Left(n; " ");@DbLookup(""; ""; "Phone Numbers"; k; 2) : @DbLookup("";""; "Phone Numbers"; k; 3)

Event descriptionsFormula, LotusScript, JavaScript, and Java code executes in response to theoccurrence of events in objects. The Domino objects are databases, agents,actions, views, folders, forms, subforms, pages, fields, hotspot buttons, andhotspot actions. In addition, code can be maintained in script libraries.

The following table lists the events that can be automated using the formulalanguage (F), LotusScript (LS), JavaScript (JS), and Java (J). For informationon sequencing of events, see the table “Event sequencing.”

Object Event name Timing

Database Postopen (LS, F) After a database is opened

Postdocumentdelete (LS, F) After a document is deleted (thedocument is still available)

Queryclose (LS, F) When a database is being closed

Querydocumentdelete (LS, F) Before a document is marked fordeletion

Querydocumentundelete (LS, F) Before a document is unmarked fordeletion

Querydragdrop (LS, F) Before a drag-and-drop operation in aview

Postdragdrop (LS, F) After a drag-and-drop operation in aview

Initialize (LS) When a database is being loaded

Terminate (LS) When a database is being closed

continued

Chapter 1: Programming Overview 25

Object Event name Timing

View Queryopen (LS, F) Before a view or folder is opened

Folder Postopen (LS, F) After a view or folder is opened

Regiondoubleclick (LS, F) When a region in a calendar view isdouble-clicked

Queryopendocument (LS, F) Before a document is loaded

Queryrecalc (LS, F) Before a view or folder is refreshed

Queryaddtofolder (LS, F) Before a document is added to afolder

Querypaste (LS, F) Before a document is pasted

Postpaste (LS, F) After a paste operation

Querydragdrop (LS, F) Before a drag-and-drop operation in acalendar view

Postdragdrop (LS, F) After a drag-and-drop operation in acalendar view

Queryclose (LS, F) When a view or folder is being closed

Initialize (LS) When a view or folder is loaded

Terminate (LS) When a view or folder is being closed

Form WebQueryOpen (F) — form only

Before a Web document displays**

Subform WebQuerySave (F) — form only

Before a Web document is saved**

Page onHelpRequest (F) When help is selected

JS Header (JS) When a document is being loaded

onBlur (JS) When an object is deselected

onClick (JS) When an object is selected

onDblClick (JS) When an object is selected with adouble-click

onFocus (JS) When an editable field is selected

onHelp (JS) When help is selected

onKeyDown (JS) When a key is pressed down

onKeyPress (JS) When a key is pressed

onKeyUp (JS) When a key is released

onLoad (JS) After a document is opened

onMouseDown (JS) When a mouse button is presseddown

continued

26 Domino Designer Programming Guide, Volume 1: Formula Language

Object Event name Timing

onMouseMove (JS) When the mouse is moved

onMouseOut (JS) When the mouse is moved out of anobject

onMouseOver (JS) When the mouse is moved over anobject

onMouseUp (JS) When a mouse button is released

onReset (JS) — form only When a document is reset

onSubmit (JS) — form only Before a document is submitted

onUnload (JS) Before a document is closed

Queryopen (LS, F) Before a document is opened

Postopen (LS, F) After a document is opened

Querymodechange (LS, F) Before a document is changed to reador edit mode

Postmodechange (LS, F) After a document is changed to reador edit mode

Postrecalc (LS, F) After a document is refreshed (andvalues are recalculated)

Querysave (LS, F) Before a document is saved

Postsave (LS, F) After a document is saved

Queryclose (LS, F) Before a document is closed

Initialize (LS) When a document is being loaded

Terminate (LS) After the document is closed

Click (LS) — form only When an object is selected

Field onClick (JS) When an object is selected

onChange (JS) When an object is changed

onBlur (JS) When an editable field is deselected

onFocus (JS) When an editable field is selected

Entering (LS) When an editable field is selected

Exiting (LS) When an editable field is deselected

Initialize (LS) When a document is being loaded —occurs after the Form Initialize event

Terminate (LS) When a document is being closed

Action onBlur (JS) When an object is deselected

Button onClick (JS) When an object is selected

continued

Chapter 1: Programming Overview 27

Object Event name Timing

Hotspot onDblClick (JS) When an object is selected with adouble-click

onFocus (JS) When an editable field is selected

onHelp (JS) When help is selected

onKeyDown (JS) When a key is pressed down

onKeyUp (JS) When a key is released

onMouseDown (JS) When a mouse button is presseddown

onMouseMove (JS) When the mouse is moved

onMouseOut (JS) When the mouse is moved out of anobject

onMouseOver (JS) When the mouse is moved over anobject

onMouseUp (JS) When a mouse button is released

Click (LS, F) When an object is selected

Objectexecute (LS) When an object is activated by anOLE2 server that is FX/NotesFlow™enabled

Initialize (LS) When an object is being loaded

Terminate (LS) When an object is being closed

Agent Action (F) When an agent is run

JavaAgent (J) When an agent is run

Initialize (LS) When an agent is being loaded

Terminate (LS) When an agent is being closed

** WebQueryOpen and WebQuerySave must be a formula with the followingsyntax: @Command([ToolsRunMacro];“agentname”).

You can add LotusScript subroutines and functions to an object. Yourscripts are added to, and can be selected from, the list of scripts belongingto the object.

Each object has a Declarations area where you can write non-executableLotusScript statements that apply to all LotusScript events in the object, andan Options area for statements such as Option, Use, UseLSX, and Const.Each document and view has a Globals area where you can writenon-executable LotusScript statements that apply to all LotusScript eventsin the document.

28 Domino Designer Programming Guide, Volume 1: Formula Language

Changes made to the current document in a Postopen event are treated asdefault values. The document is not marked as changed. If the user closesthe document at this point, the Postopen changes are lost. You mustexplicitly save the changes, for example, with the Save method ofNotesUIDocument, if you want to be sure they are applied.

Event sequencing

The following table shows the sequencing of events during commonDomino tasks.

Task Sequence of events

Opening a database to a view 1. [optional] Script Library Initialize (View)2. Globals Initialize (View)3. Initialize (View)4. Queryopen (View)5. Querypostopen (View)6. [optional] Script Library Initialize

(Database)7. Initialize (Database)8. Postopen (Database)

Closing a database from a view 1. Queryclose (View)2. Terminate (View)3. Globals Terminate (View)4. [optional] Script Library Terminate

(View)5. Queryclose (Database)6. Terminate (Database)7. [optional] Script Library Terminate

(Database)

Opening a database 1. [optional] Script Library Initialize2. Initialize3. Postopen

Closing a database 1. Queryclose2. Terminate3. [optional] Script Library Terminate

continued

Chapter 1: Programming Overview 29

Task Sequence of events

Opening a view 1. [optional] Script Library Initialize2. Globals Initialize3. Initialize4. Queryopen5. Querypostopen

Refreshing a view 1. Queryrecalc

Leaving a view 1. Queryclose2. Terminate3. Globals Terminate4. [optional] Script Library Terminate

Composing a new document 1. [optional] Script Library Initialize2. Globals Initialize3. Initialize4. JS Header5. Queryopen6. Initialize (Fields)7. Postopen8. onLoad

Editing an existing document 1. QueryOpenDocument (View)2. [optional] Script Library Initialize (Form)3. Globals Initialize4. Initialize (Form)5. JS Header6. Queryopen7. Initialize (Fields)8. Postopen9. onLoad

Changing modes (edit/read) in adocument

1. Querymodechange (Form)2. Postmodechange

Saving a document 1. Querysave (Form)2. onSubmit3. Postsave

Refreshing a document 1. Postrecalc (Form)

continued

30 Domino Designer Programming Guide, Volume 1: Formula Language

Task Sequence of events

Closing a document 1. Queryclose (Form)2. unLoad3. Terminate (Fields)4. Terminate (Form)5. Globals Terminate6. [optional] Script Library Terminate

Deleting a document in a view 1. Querydocumentdelete2. Postdocumentdelete

Undeleting a document in a view 1. Querydocumentundelete

Running an agent 1. [optional] Script Library Initialize2. Initialize3. Terminate4. [optional] Script Library Terminate

Entering a field 1. Entering2. onFocus

Exiting a field 1. onChange2. Exiting3. onBlur

Chapter 1: Programming Overview 31

Chapter 2 User Interface

This chapter provides an introduction to the Programmer’s pane userinterface in Domino Designer. The Programmer’s pane allows you to addfunctionality to applications with Java, JavaScript, LotusScript, FormulaLanguage, and simple actions.

Exploring the Programmer’s pane

The Programmer’s pane is located in Domino Designer in the lower half ofthe Work pane, or by itself in some design elements and resources such asagents and shared fields. The Programmer’s pane is context-sensitive andmay change slightly depending on the programming language you select.

For information about developing design elements see ApplicationDevelopment with Domino Designer.

The Programmer’s pane consists of the following main components.

Title bar

Script area

Info List

33

Interface feature Purpose

Info List Contains the Objects and Reference tabs.

Objects tab Lists all of the objects and events availablefor programming in the current context.

Reference tab Lists reference information and syntax.

Reference list Allows you to select and see referenceinformation.

Help button Launches Domino Designer 5 Help fromthe Programmer’s pane. Located on theReference tab.

Paste button Pastes selected information into the Scriptarea.

Paste Full Text check box If selected, pastes the syntax of an event,method, or property from the Referencetab into the Script area when you click thePaste button.

Script area Provides a space to write and compile allrecognized programming languages.Checks syntax as a programminglanguage is written.

Run menu Enables you to select the desiredprogramming language. It displays onlythe languages available for the currentdesign state.

Title bar Displays the title of the design elementthat the programming language isattached to. Double-click here to maximizeor minimize the Programmer’s pane.

Errors box Displays compile-time errors forLotusScript and Java.

34 Domino Designer Programming Guide, Volume 1: Formula Language

Exploring the Java interface in the Programmer’s pane

Java programming can be done in the Programmer’s pane of an agent, or ina Script Library.

Interface element Purpose

Classes tab Lists all classes being used in the agent. This tabreplaces the Objects tab when Java has beenselected as the programming language.

Edit Project button Allows you to add resource, class, or .jar files to anagent project. It can also be used to include a ScriptLibrary on the class path.

New Class button Creates a space for a new class in the Script area.

Export button Exports Java from an agent.

Compile button Compiles the current class, or the entire agent.

Java Debug Console Displays the output generated by your Javaprogramming.

Chapter 2: User Interface 35

When Imported Java is selected from the Run menu, the Programmer’spane does not include the Info List, or the Edit Project, New Class, Export,and Compile buttons. The Programmer’s pane includes the followingfeatures for Imported Java.

Interface Element Purpose

Base Class box Allows you to enter the base class of the currentagent. If you import class files, the base class willbe displayed here.

Import Class Files button Imports Java into an agent.

Accessing the Programmer’s pane1. Launch the Notes Client.

2. Open a database.

3. Choose View - Design.

4. Open an existing design element or resource, or create a new one.

36 Domino Designer Programming Guide, Volume 1: Formula Language

Using the Info List

The Info List appears on the left side of the Programmer’s pane andcontains two context-sensitive tabs:

Objects

Reference

Note When Java is selected from the Run menu, the Objects tab is replacedby the Classes tab.

Adjusting the size of the Info ListYou can adjust width of the Info List by dragging the vertical bar on theright side of the box to the desired size. To adjust the height of the Info List, drag the horizontal bar at the top of the box to the desired size.Adjusting the height of the Info List also affects the height of the entireProgrammer’s pane.

Using the Objects tabThe Objects tab is located in the Info List. It contains a context-sensitive listof objects and events available for the selected programming language. TheObjects tab allows you to:

Program any object or event in the design element.

Locate or view programmed objects by selecting them in the Workpane.

Determine the programming language used for a particular object orevent at a glance.

Press CTRL+0 to access the Objects tab using the keyboard. In the Javaprogramming environment, CTRL+0 accesses the Classes tab.

Programming an object’s properties and events1. Select the desired programming language from the Run menu.

2. Select the object’s property or event from the Objects tab.

3. Type or paste code into the Script area.

Locating code within an objectTo locate code within an object, click on the object in the Work pane. Thepointer on the Objects tab will jump to the appropriate object and displaythe attached code. For example, to find code attached to a button, click onthe button in the Work pane, the Objects tab will jump to the button objectplaceholder and display the attached code.

Chapter 2: User Interface 37

Determining the programming language at a glanceEach programming language recognized in the Programmer’s pane has anicon related to it. These icons appear to the left of the object or event on theObjects tab. The following table shows the relationship of each icon to itsrespective programming language.

Programming language Icon

Formula language

JavaScript

LotusScript

Simple Action(s)

Using the Reference tabThe Reference tab provides you with context-sensitive information for eachprogramming language recognized in the Programmer’s pane. You canview this information by clicking on the Reference tab and selecting thedesired topic from the Reference list.

The Reference tab allows you to:

See the syntax for an event, method, or property.

Paste information from the Reference tab into the Script area.

Programming language Reference tab components

Formula Language Database Fields, Formula @Commands,Formula @Functions

Java Core Java, Notes Java.

JavaScript Web D.O.M., Notes D.O.M.

LotusScript Domino: Classes, Domino: Constants,Domino: Subs and Functions, Domino: Variables, OLE Classes.

Simple Action(s) No Reference tab available.

Pasting information from the Reference tab into the Script area1. Place the cursor where you want the item to appear in the Script area.

2. Click on the item to paste.

3. Click Paste.

38 Domino Designer Programming Guide, Volume 1: Formula Language

Using short-cut keys to access the Reference tabThe table below lists key combinations you can use to access the Reference tab.

Keys Selects

CTRL+1 The first reference category

CTRL+2 The second reference category

CTRL+3 The third reference category

CTRL+4 The fourth reference category

CTRL+5 The fifth reference category

CTRL+6 The sixth reference category

Using the Errors boxThe Errors box is present for Java and LotusScript. Use the Errors box toview error messages that occur during script entry and compilation. TheErrors box displays only one error at a time. To view other errors, click onthe box and select the error from the list. When you select an error from thelist, the cursor in the Script area moves to the line containing the error.

Using the Script areaThe Script area formats LotusScript automatically by indenting andadjusting the case of keywords as needed. In most cases, there is noautomatic formatting for other programming languages.

Use the Script area to:

Set text properties

Move the insertion point while editing code

Select text

Edit text with menu commands

Save and Delete code

Rename an object, subprogram, or class

Chapter 2: User Interface 39

Setting text propertiesThis procedure is applicable to all of the coding languages used in theProgrammer’s pane.

1. Click inside the Script area.

2. Choose Edit - Properties. Click on the arrow and select Programmer’sPane from the list.

3. Click Script/Java, Formulas, or simple Action(s).

4. Select the desired text font, size, and color from the lists provided.These selections apply to all text in the Programmer’s pane for alldesign elements.

5. (Optional) For LotusScript, select different colors as desired to representidentifiers, keywords, comments, errors, and constants on the right sideof the box.

6. Specify whether formula wrapping is enabled or disabled. The defaultsetting is enabled.

7. (Optional) If you’re setting properties for LotusScript, specify whetherLotusScript Auto Indenting is enabled or disabled. The default setting is enabled.

Moving the insertion point while editing text in the Script areaThe table below lists keys that move the insertion point in the Programmer’s pane.

Key Moves the insertion point

RIGHT ARROW One character to the right

LEFT ARROW One character to the left

UP ARROW One line up

DOWN ARROW One line down

HOME To the beginning of the line

END To the end of the line

CTRL+RIGHT ARROW To the first character in the next word

CTRL+LEFT ARROW To the first character in the previous word

CTRL+HOME To the beginning of the first line

CTRL+END To the end of the last line

Tip Use PGUP and PGDN to scroll one screen up or down, overlappingone line from the previous screen.

40 Domino Designer Programming Guide, Volume 1: Formula Language

Selecting textYou can select text with key combinations and the mouse.

Table of key combinationsKey combination Selects

CTRL+A All text in the Script area

SHIFT+RIGHT ARROW The character to the right of the insertionpoint

SHIFT+LEFT ARROW The character to the left of the insertionpoint

SHIFT+UP ARROW The text starting at the left of the insertionpoint and ending at the character aboveand to the right of the insertion point

SHIFT+DOWN ARROW The text starting at the right of the insertionpoint and ending at the character belowand to the left of the insertion point

SHIFT+HOME The text starting with the character at theinsertion point and ending with the firstcharacter on the line

SHIFT+END The text starting with the character at theinsertion point and ending with the lastcharacter on the line

SHIFT+CTRL+RIGHT ARROW The next word or selects the remainder ofthe word if the insertion point is in theword

SHIFT+CTRL+LEFT ARROW The previous word or selects the first partof the word if the insertion point is in theword

Table of mouse operationsMouse operation Selects

SHIFT+CLICK (left mouse click) The text from the insertion point to theposition of the mouse

Drag The text from the starting position of themouse to the ending position

Double+Click (on the word) The entire word and the following space

Right+Click The Edit menu

Chapter 2: User Interface 41

Editing text with key combinations

Key combination Description

CTRL+F Finds and replaces text.

CTRL+Y Redo.

CTRL+Z Undo.

Editing text with menu commands

Menu command Description

Edit - Cut Move selected text to the Clipboard.

Edit - Clear Delete selected text (doesn’t go to the Clipboard).

Edit - Copy Copy selected text to the Clipboard.

Edit - Paste Paste text from the Clipboard to the currentinsertion point.

Edit - SelectAll Selects all text in the window.

Edit - DeselectAll Deselects all text in the window.

Edit - Find/Replace Finds and optionally replaces text in the window.

File - Import Imports the text of a file into the currentLotusScript event or object. This menu choice isavailable for LotusScript only.

File - Export Exports LotusScript to a file. Select “currentsection” to export the current script, view, form,or agent object; “current object” to export allscripts in the current object, for example, just thisbutton or action; “all objects” to export all scriptsin the current database. This menu choice isavailable for LotusScript only.

Saving and deleting text in the Script area

To save text in the Script areaChoose File - Save to save a design element or resource and all of itsassociated programming. You can also save a design element or resourcewhen you exit from it.

To delete text in the Script area1. Select the object or event from the Objects tab.

2. Choose Edit - Select All, or manually select all the text in the Script area.

3. Choose Edit - Cut or Edit - Clear.

42 Domino Designer Programming Guide, Volume 1: Formula Language

Renaming an object, subprogram, or classFor Formula, JavaScript, LotusScript, and Simple action(s) you can renamean object by changing its name in its properties box. The programmingattached to that object will automatically be associated with its new name.An agent may be renamed without affecting the Java in it. You must changeany references to the object; for example, calls to methods that reference thename of the object.

To rename a subroutine or function, edit the script that defines it. If youchange the name of a Domino-defined subprogram such as Initialize orClick, a new user-defined subprogram with the revised name is created and automatically added to the Info List. The script from the original event is moved to the newly-created subprogram, and the original scriptbecomes empty.

Writing Java in an agent1. Select Create - Agent.

2. Specify a name, options, scheduling, and Add Search as needed.

3. Select Java from the Run menu.

4. Write your Java after the remark line, “Your code goes here,” or clickEdit Project to add resource, class, or .jar files to the current agent.

Note Any changes made to the .java files in the current agent existonly in the agent. If you want to update the original files, you mustexport the agent to the directory containing the files you want toupdate.

5. (Optional) Click New Class to add a new class. A horizontal barseparates each class. The name of a class appears on the bar above theclass to which it refers.

6. Click on Compile below the Script area. You can choose to compile thecurrent class or the entire agent.

7. (Optional) Click Export to export Java to a project directory.

Viewing output from a Java agentYou can review output from a Java agent that is running locally in the JavaDebug Console. To activate the console, select File - Tools - Show JavaDebug Console. To clear output from the window, click Clear.

If a Java agent is running on a server, the Java Debug Console output isredirected to a server log file.

Chapter 2: User Interface 43

Adding resource, class, or .jar files to an agent1. Click Edit Project.

2. Select the file to include as a resource.

3. Click Add/Replace File.

Including a Script Library on the class path1. Click Edit Project.

2. Select “Shared Java Libraries.”

3. Select the Script Library to add to the class path.

4. Click Add/Replace File.

Compiling JavaThere are three phases to compiling Java:

A complete compilation occurs when you select File - Save. Allcompile-time errors are reported at this time.

You can compile each class individually by clicking on the class in theScript area, then clicking Compile and selecting “Compile Class Name.”

Compile all of the classes at once by clicking on the Compile button andselecting “Compile All.”

Errors are reported in the Errors box. Click on the Errors box to see whichline in the Script area contains the error.

Errors not detectable during compilation are reported at run-time.

Importing Java into the Programmer’s pane1. Select Imported Java from the Run menu.

2. Click “Import Class Files.”

3. Under the “Available Java Files” column, select the filing system andbase directory for the files you want to import. If you are importingfrom a named package, the base directory must be above the directorycontaining the class files.

4. (Optional) Select the appropriate check box for “Show File Types.” Thedefault file type is All.

5. Select the files you want to import from the file list and clickAdd/Replace. To import all of the files in the base directory and all ofits subdirectories, click Select All. To remove a file, or group of filesfrom the Current Agent Files column, select the file(s) and click Delete.

44 Domino Designer Programming Guide, Volume 1: Formula Language

6. Put the files in the proper order in the “Current Agent Files” column byclicking Reorder Up or Reorder Down to move files up or down, or bydragging files into place. You may move files one at a time, or ingroups.

7. Enter the base class in the “Base class” box or select it from the list.

8. (Optional) Click Refresh, or Refresh all to reload files in the selected list.

9. Click O.K. to import files.

10. (Optional) Click “Reimport Class Files” to import additional files, orreimport an existing file.

Note This step applies to “Imported Java” agents only.

Using AgentRunnerAgentRunner is a Java application program for debugging agents in a JavaIDE. There are two versions of AgentRunner classes for backwardcompatibility:

lotus.domino.AgentRunner for lotus.domino (Notes/Domino Release 5.0)

lotus.notes.AgentRunner for lotus.notes (Notes/Domino Release 4.6)

Included with AgentRunner is a set of debug classes that allow you todebug an agent while working in a Java IDE.

Creating a project for AgentRunnerIn a Java IDE,

1. Add the complete file path for notes.jar to the CLASSPATH in yourJava IDE. Some Java IDEs such as VisualAge require you to import thisfile into your project instead of adding it to the CLASSPATH.

2. Create an agent that extends DebugAgentBase instead of AgentBase. To ensure that the correct DebugAgentBase is used, use “importlotus.notes.*;” for agents created in Notes/Domino Release 4.6 and“import lotus.domino.*;” for agents created with Notes/Domino Release 5.

3. Build the project as an application. A main() method is not required,but if your IDE requires it, you may add a dummy main() method thatDomino will ignore.

4. If necessary, export the class files.

Chapter 2: User Interface 45

Generating an AgentContext documentThe AgentContext document is stored in AgentRunner.nsf.AgentRunner.nsf is automatically placed in your Domino Data directorywhen you install Domino Release 5.

1. Create a Java agent in a database and import the .class files from yourproject. The base class must extend DebugAgentBase.

2. Run the agent to generate an AgentContext document inAgentRunner.nsf.

3. Open AgentRunner.nsf and examine the most recent AgentContextdocument.

4. Note the name of the server, the file path of the database, and the nameof the agent. Local is the name of the server for a database on your localhard drive.

5. In Edit mode, change the “Agent Runs On” and “Search Criteria” fieldsto generate the UnprocesssedDocuments collection that you would liketo use for debugging purposes. You must supply this informationbecause it cannot be determined from running the agent.

DetailsThe “Agent Runs On” and “Search Criteria” that you specified in the agentused to generate the AgentContext document will produce the “Selected”document list.

You can generate another AgentContext document later if you want tochange the run-time environment.

Debugging a Java agent with AgentRunnerFrom the Java IDE,

1. Select the AgentContext document by specifying<Agent>[<Database>[<Server>]] arguments to the AgentRunnerprogram. The arguments should be written as they appear in the“AgentContexts” view of AgentRunner.nsf. To run AgentRunner froma command line, type:java AgentRunner< Agent >[< Database >[< Server >]]

2. Set a breakpoint on any executable line of Java in the NotesMain()method of your agent.

46 Domino Designer Programming Guide, Volume 1: Formula Language

3. Run or debug the project. If you are debugging and no breakpoints areset, you should step into NotesMain() to access your Java.

Some Java IDEs won’t allow you to specify a class .jar or .zip file for thelocation of a project’s main() entry point. To work around this, create adummy main application designed to call the main() method inAgentRunner. For example:

import lotus.domino.*; public class Main { public static voice main (String[] args) { try { AgentRunner.main(args); } catch (Exception e) { e.printStackTrace(); } }}

Writing JavaScript in the Programmer’s pane

JavaScript allows you to write scripts that function on the Web as well as inthe Domino client. The Objects tab provides a list of JavaScript eventssupported in Domino. JavaScript is not available in the agent editor, or inScript Libraries.

The Programmer’s pane allows you to:

Program object events with JavaScript

Use JS Header to enter JavaScript directly into the page header

Compile your JavaScript before leaving the Programmer’s pane

To program an object event in JavaScript, click the placeholder for the objectevent in the Objects tab and type your JavaScript in the Script area.

Chapter 2: User Interface 47

Writing JavaScript in a page headerThe Programmer’s pane provides a placeholder called JS Header on theObjects tab that allows you to write JavaScript in the header of a page.JavaScript written in the header in this way does not require a formula toreturn a JavaScript function, or text to be marked as passthru HTML.

1. Click JS Header on the Objects tab.

2. Write your JavaScript in the Script area.

Compiling JavaScriptJavaScript is compiled by selecting File - Save, or clicking on the greencheckmark, but it is not stored in its compiled form. All JavaScript isrecompiled each time it is run.

Errors detected when the script is saved are displayed in the status bar atthe bottom of the Script area. Only one error is displayed at a time. Once anerror is detected, you must correct the errors before you can exit the designelement. If you want to save a script with errors, make the incorrect line aremark by preceding it with two forward slashes. For example: // This is aremark.

Writing LotusScript in the Programmer’s paneLotusScript allows you to:

Use the placeholder for (Globals) to define subprograms and declarevariables that are available to all objects in the current document.

Create an additional script in LotusScript

Complete a LotusScript block statement automatically

Complete a LotusScript %directive automatically

Compile scripts

Defining global variables and subprogramsThe Programmer’s pane contains a placeholder on the Objects tab called(Globals) that allows you to define global variables and subprograms usingLotusScript. To define a global variable or subprogram perform these steps:

1. Click (Globals) on the Objects tab.

2. Select (Options), (Declarations), Initialize, or Terminate from theObjects tab.

3. Enter your LotusScript variable or subroutine in the Script area.

4. Refer to the subprogram or variable in any script in the application.

48 Domino Designer Programming Guide, Volume 1: Formula Language

Create an additional script in LotusScriptA number of scripts, such as Initialize, Terminate, and Click, areautomatically defined as events for the current Domino object. You selectthem from the Info List. You can create additional scripts and other blockstructures as shown in the following table. When a new script is added, itappears on the Objects tab.

What you type What LotusScript does

Sub name Creates an empty Sub/End Sub block called name forthe current object and adds it to the Event box.Positions the insertion point in the subroutine.

Function name Creates an empty Function/End Function block calledname for the current object and adds it to the Event box.Positions the insertion point in the function.

Property Get name Creates an empty Property Get/End Property Getblock called name for the current object and adds anitem called name Get to the Event box. Positions theinsertion point in the subprogram.

Property Set name Creates an empty Property Set/End Property Set blockcalled name for the current object and adds an itemcalled name Set to the Event box. Positions the insertionpoint in the subprogram.

Type name Creates an empty Type/End Type block called namefor the current object and adds it to the end of the(Declarations) script for the object. Positions theinsertion point at the beginning of the Type block.

Dim name If the Dim statement is typed outside of a subprogram,adds a Dim statement for name to the end of the(Declarations) script for the current object. Positionsthe insertion point at the Dim statement.

Option string Adds an Option statement to the beginning of the(Options) script for the current object. Positions theinsertion point at the Option statement.

Deftype letter_range Adds a Deftype statement to the beginning of the(Options) script for the current object. Positions theinsertion point at the Deftype statement.

Class name Adds a Class statement to the beginning of the(Declarations) script for the current object. Positionsthe insertion point at the Class statement.

Chapter 2: User Interface 49

Completing a LotusScript block statement automaticallyFor LotusScript the following block structures are automatically terminatedand the insertion point is placed in a new, indented line within the blockstructure.

This statement Automatically terminates this statement

Next For

Loop Do, Do While, or Do Until

End Forall Forall

End If If...Then

End Select Select Case

Wend While

Completing a LotusScript %directive automaticallyIf a script contains a %REM directive without a matching %END REMdirective, LotusScript inserts a new line containing %END REMimmediately below the %REM directive when the Script area is closed orsaved, or when a different object or script is selected.

Compiling LotusScriptCompilation takes place in two phases:

1. A partial compilation occurs as you enter the script. Syntax and otherper-line errors are reported at this time.

2. A complete compilation occurs when you save the script. All remainingcompile-time errors are reported at this time.

If you attempt to save a script with compilation errors, you are given achoice of editing the script again or exiting without saving your changes. Ifyou exit, all changes are lost.

If you want to save a script with errors, make the incorrect line a remark bypreceding it with an apostrophe or a REM statement, or setting it off with a%REM ... %END REM directive.

Errors not detectable during compilation are reported at run-time.

If you change (Globals) on a form, all scripts associated with the (Globals)script, with the form, and with all objects on the form are recompiled.Scripts in shared fields and subforms are not recompiled since they aren’ton the form.

If you change the script for an object on a form, all events associated withthe object, but nothing else, are recompiled.

50 Domino Designer Programming Guide, Volume 1: Formula Language

Exploring the LotusScript Debugger

The debugger allows you to:

Select a subprogram

Step through a script

Debug with breakpoints

Use the debugger utilities

Examine and set the values of the script variables.

The debugger has the following components.

Interface feature Purpose

Debug pane Displays the script currently being debugged —an Object box, an Event box and a Calls box.

Continue button Runs the current script until an error is found.

Step Into button Steps through a script one line at a time.

Step Over button Executes the current statement and steps to thenext statement, or steps over a subprogramcalled by the current statement.

Step Exit button Exits the current subprogram.

continued

Debug pane

Script pane

Utilities pane

Chapter 2: User Interface 51

Interface feature Purpose

Stop button Stops all scripts that are at a breakpoint andcloses the debugger.

Script pane Displays the script currently being debugged.

Object box Displays the name of the object containing the script.

Event box Displays the event containing the script.

Calls box Lists subprograms currently on the execution stack.

Utilities pane Contains three tabs: Breakpoints, Variables, and Output.

Breakpoints Displays a list of breakpoints set in the current script.

Variables Displays the variables in the current script.

Output Displays the output of the current script.

New Value box Allows you to enter a new value for anyvariable listed on the Variables tab.

Using the LotusScript DebuggerWhen you run a script in Debug mode, the script is in one of three states:

When a script is interrupted at a breakpoint, the debugger has control.

When a script is stepping, control passes to the script and then back tothe debugger after a single statement in the script is executed.

When a script is continuing, it runs uninterrupted until a breakpoint isreached. If you do not set any breakpoints in a script, it runs as if thedebugger were not present.

Note The debugger does not run on the Terminate event.

To use the LotusScript Debugger1. Choose File - Tools - Debug LotusScript.

2. Perform the action that starts the script, like clicking a button orchoosing an action. When you are in Debug mode and the script runs,execution pauses at the first line of the script and the debugger opens.

3. To adjust the windows, drag the horizontal bar separating the panes as desired.

4. To disable the debugger, select File - Tools - Debug LotusScript again.

52 Domino Designer Programming Guide, Volume 1: Formula Language

Stopping script executionTo stop script execution while the debugger is open, click Stop. All scriptsthat are at a breakpoint are stopped as if the end of the scripts werereached, and the debugger closes.

Selecting a subprogramAs you execute a script the current subprogram appears in the debugger window.

The Calls box contains a list of the subprograms currently in the executionstack in order of execution, with the currently executing subprogram at thetop of the list. Subprograms are listed as object: event, for example,Calculate_totals: CLICK.

If you select a subprogram from the list, its script appears in the debuggerwindow. If you select the subprogram that is currently executing, thecurrent pointer points to the statement about to be executed. If you selectanother subprogram, the current pointer points to the statement that callsthe next subprogram in the stack.

Stepping through a scriptThe debugger provides the following facilities for stepping throughLotusScript:

Step into a subprogram

To execute the current statement and step to the next statement, or stepinto the subprogram if the current statement calls a subprogram, clickStep Into.

Step Into proceeds to the next statement in the program. If the currentstatement calls a subprogram, the debugger displays the script for thesubprogram and sets the current line to the first executable statement inthe subprogram. If no source script is available for the subprogram(because it is an external file), Step Into behaves the same as Step Over.

Step over a subprogram

To execute the current statement and step to the next statement, or stepover the subprogram if the current statement calls a subprogram, clickStep Over or choose Debug - Step Over.

Step Over proceeds to the next statement in the current program unit. Ifthe statement calls a subprogram, the debugger executes the entiresubprogram as if it were a single statement and sets the current line tothe next statement in the calling program unit.

Chapter 2: User Interface 53

Exit from a subprogram

To execute the remaining statements in a subprogram and step to thenext statement in the calling program unit, click Step Exit or chooseDebug - Step Exit.

Step Exit continues executing the current subprogram and stops in the subprogram that called it at the line following the call. If thesubprogram was not called by another, execution continues to the nextbreakpoint or to completion.

Debugging with breakpointsA breakpoint interrupts script execution just before the statement at whichthe breakpoint is set. While script execution is interrupted, you can examineand modify the values of variables and use other debugger commands.Breakpoints cannot be set for the Terminate event.

After you set a breakpoint, you can permanently clear it, temporarilydisable it, or enable it again. Breakpoints are displayed as red stop signswhen enabled and red stop signs with yellow slashes when disabled.

For a statement continued over multiple lines, the last line is highlightedduring stepping and stopping on a breakpoint. To set, disable, enable, orclear a multi-line statement, you must select the last line.

A breakpoint remains in a script until the application session ends or youexplicitly clear the breakpoint.

The debugger provides the following breakpoint facilities:

Set a breakpoint

Select a statement at which no breakpoint is currently set. Double-clickthe statement, or choose Debug - Set/Clear Breakpoint.

Clear a breakpoint

Select a statement at which a breakpoint is currently set. Double-clickthe statement once if the stop sign has a yellow slash or twice if the stopsign is solid red, or choose Debug - Set/Clear Breakpoint. To clear allbreakpoints from all scripts in the active document, choose Debug -Clear All Breakpoints.

Disable a breakpoint

Select a statement at which an enabled (solid red stop sign) breakpointis set. Double-click the statement or choose Debug - Disable Breakpoint.To disable all breakpoints from all scripts in the active document,choose Debug - Disable All Breakpoints.

54 Domino Designer Programming Guide, Volume 1: Formula Language

Enable a breakpoint

Select a statement at which a disabled (red stop sign with yellow slash)breakpoint is set and choose Debug - Enable Breakpoint. To enable allbreakpoints from all scripts in the active document, choose Debug -Enable All Breakpoints.

Continue script execution

To start executing the current script or to resume execution after thescript is interrupted at a breakpoint, click Continue or choose Debug -Continue.

Using the debugger utilities

The debugger utilities appear as three tabbed panels in the Utilities pane ofthe debugger:

Breakpoints panel

Variables panel

Output panel

Using the breakpoints panelClick the Breakpoints tab or choose Debug - Breakpoints to access thebreakpoints panel.

The breakpoints panel displays the current breakpoints in the followingformat:

object: event: line

If the breakpoint is disabled, (Disabled) is appended to the display.

Using the variables panelClick the Variables tab or choose Debug - Variables to access the variablespanel.

The variables defined for the procedure appear in a three-column display,showing the name, value, and data type of each variable. To view array ortype members, click the arrow to the left of the variable name.

To change the value of a variable1. Select the variable.

2. Enter the value in the New Value box.

3. Click the green check mark.

Chapter 2: User Interface 55

Using the output panelClick the Output tab or choose Debug - Output to access the output panel.

Script output, for example from the Print statement, goes to the outputpanel. You can:

View the output.

Clear the output panel by clicking Clear All.

Click Copy to move selected output to the clipboard. Choose Edit -Select All to select all the text in the output panel.

Using Script LibrariesOnly Java and LotusScript may be used in a Script Library.

To create a Script Library, choose Create - Design - Script Library.

To access an existing Script Library, choose View - Design, clickResources and select Script Libraries.

The scope of a Script Library is the current database. All scripts in adatabase can avail themselves of the LotusScript or Java in a library in thatdatabase. However, the library is lost to scripts outside the database. Forexample, if a button in a document uses a Script Library and you mail thedocument to or paste it in another database that does not have the sameScript Library, the script fails. If a script attempts to use a library not in thecurrent database, you see the error message, “Error loading USE or USELSXmodule.”

The Script Library appears as a Programmer’s pane. To name the library,choose Edit - Properties.

Using LotusScript in a Script LibraryFor LotusScript, a Script Library contains (Option), (Declaration), Initialize,Terminate, and user scripts.

To write LotusScript in a Script Library, select LotusScript from the Runmenu, then select the object you want to attach the script to and writeyour script in the Script area.

To write a new script, enter a statement such as Function or Sub in anexisting script. The editor automatically creates a new script andtransfers your script there.

56 Domino Designer Programming Guide, Volume 1: Formula Language

To incorporate a Script Library into a scriptable object, enter aLotusScript Use statement in the (Options) script for the object or forthe (Globals) object. For example, to make the Script Library namedMarket2 available to a form’s scripts, enter the following statement inthe (Declarations) script for the form:Use "Market2"

The name is case-insensitive and should not contain spaces. Specify thename as a character literal (above) or named constant (below):Const m2 = "Market2"Use m2

Note A LotusScript Use statement may not be used to incorporate a ScriptLibrary containing Java.

The script in the (Options), (Declarations), Initialize, and Terminate eventsof the library becomes available as though it were in the current object’scorresponding scripts. User scripts in the library become available asthough they were in the current object.

You cannot change a declaration in a Script Library while a script or agentusing that declaration is open. You must first close the script or agent usingthe declaration, make the change in the library script, and then reopen thescript using the declaration. If you do make a change while a script is open,you must comment out or delete the script that uses the declaration, closeand reopen the script, and then reinsert or uncomment the script.

Using Java in a Script LibraryFor Java, a Script Library allows you to define common classes you canaccess from any Java agent.

To write Java in a Script Library1. Select Java from the Run menu.

2. Enter your Java in the Script area.

To use a Script Library in an agent1. Click Edit Project.

2. From the Browse box, choose Shared Java Libraries.

3. Select the library you want to include.

4. Click Add/Replace.

Chapter 2: User Interface 57

Writing formulas in the Programmer’s pane

Formulas may be written in the Programmer’s pane, or in the Formulawindow located in the properties boxes of some objects. Formula windowsare also located in other parts of the Domino interface such as ReplicationSettings.

To enter a formula in the Programmer’s pane1. Select Run - Formula.

2. Click on the correct object on the Objects tab. The object can be anaction, a button, a hotspot, a field, or the form itself.

3. For fields, click the correct event on the Objects tab. The event can beDefault Value, Input Translation, Input Validation or HTML Attributes.

4. Enter the formula in the Script area. The Reference tab provides a list of@functions, @commands, and fields.

5. Click the check mark that appears on the right just above the Script areato accept your new formula or the edits to an existing formula. You canclick the X to cancel your formula or edits.

6. If you receive syntax error messages, edit the formula until the errorsare corrected.

The column formula has the appearance of a Programmer’s pane but lacksan Object box. Your formula applies to the column that is currently selected.

Using the formula windowThe Formula Window appears anywhere you can enter a formula outside ofthe Programmer’s pane. When entering a formula in the Formula window,you can:

Enter it directly into the small white area on the Hide When tab of aproperties box.

Click Formula Window or Zoom to open a larger Formula Window

To enter a formula in the small Formula window1. Open a screen containing a Formula Window.

2. Enter your formula in the Formula window. A check mark and an Xappear next to the Formula window when you begin typing. Click thecheck mark to accept any changes you have made. Click the X to undoany changes made prior to clicking the check mark.

3. If you receive syntax error messages, edit the formula until the errorsare corrected.

58 Domino Designer Programming Guide, Volume 1: Formula Language

To enter a formula in the large Formula window1. Open the properties box of a design element.

2. Click the Hide When tab.

3. Click Formula Window to display a larger Formula window.

4. To select @functions, @commands, and fields from a list, click FormulaWindow, then click “Fields and Functions.”

5. Type your formula.

6. Click Done.

7. If you receive syntax error messages, edit the formula until the errorsare corrected.

To delete a formula, highlight the formula and press DEL.

Using the Programmer’s pane for Simple action(s)To create a Simple action in the Programmer’s pane:

1. Select Simple action(s) from the Run menu.

2. Click Add Action.

3. Select an action from the list.

4. Enter any additional information. This will vary depending on theaction selected.

Note The Reference tab is not available in Simple action(s) mode.

Chapter 2: User Interface 59

Chapter 3 Formula Language Rules

Formula language provides syntax and @functions for evaluating constantsand variables, and for performing simple logic. Variables can be fields inNotes documents or temporary variables (also called temporary fields) usedonly for the immediate formula.

For more information on how to use the formula language, see theGuidelines chapter, and the A-Z reference chapters for @Functions and@Commands.

Using the syntax rules

You understand formula language through its:

Lexical elements

General syntax rules

Lexical elementsA formula consists of one or more statements, each consisting of any of thefollowing:

Variables

Constants

Operators

@Functions

Keywords

See the applicable sections later in this chapter for descriptions of thestatement components.

A value is a variable, a constant, the result of an @function, or the result ofan expression formed by combining any of the foregoing elements withoperators.

61

Examples: Lexical elements1. D is a variable, := is an operator, and @Created is an @function without

arguments. This formula assigns the creation date of a document to D.D := @Created

2. @Trim is an @function with an argument. The argument, Subject, is avariable. This formula removes extraneous spaces from subject.@Trim(Subject)

3. @Prompt is an @function with three arguments. The first argument,[OK], is a keyword; the second and third arguments are text constants.This formula displays a dialog box.@Prompt([OK]; "Update Complete"; "Your update has beenposted")

4. SELECT is a keyword and @All is an @function without arguments.This formula selects all documents for an operation, for example, forinclusion in a view.SELECT @All

5. LastName is a variable, + is an operator, “, ” is a constant, andFirstName is a variable. This formula concatenates LastName, a comma followed by a space, and FirstName.LastName + ", " + FirstName

General syntax rulesA formula must follow these general syntax rules.

Statement separatorsSeparate multiple statements with semicolons.

FIELD RegionalManager := AreaManager;FIELD AreaManager := @DeleteField

SpacesYou can place any number of spaces, including none, between operators,punctuation, and values. However, keywords must be delineated by at leastone space, and spaces within text constants are significant.

For example, the following statements are equivalent.

LastName + ", " + FirstName;LastName+", "+FirstName

62 Domino Designer Programming Guide, Volume 1: Formula Language

In the following statement, at least one space must follow the keywordSELECT.

SELECT @All

CaseCase is not significant except within text constants. By convention,keywords such as FIELD are uppercase, and @function and @commandnames such as ProperCase are mixed uppercase and lowercase. You neednot follow these conventions when typing, but Domino changes the case toconform to the conventions when saving a formula.

Operators and valuesTwo values must be separated by at least one operator.

Using variablesVariables are of two types:

Fields

Temporary variables

FieldsA formula has access to the fields in the document being processed. Thename and type of each field is as specified in the database design.

Data typesData types must be correct for the operation or @function being performed.For example, if TotalValue is a number field, you cannot display it directlywith @Prompt because @Prompt requires a text argument. You must firstconvert the argument with @Text:

@Prompt([OK]; "Value of MyNumber"; @Text(TotalValue));

Rich text fieldsRich text fields cannot be evaluated for content. For example, if BodyText isa rich text field, you cannot display its contents with @Prompt, and youcannot convert it to plain text by specifying @Text(BodyText). However,you can access the attributes of the field. The following formula tests for theavailability of a rich text field.

@Prompt([OK]; "Is BodyText Available";@If(@IsAvailable(BodyText); "Yes"; "No"))

Chapter 3: Formula Language Rules 63

ListsLists are fields that contain multiple values. Certain @functions andoperators deal specifically with lists. For example, if Locations is a field thatallows multiple values, the following statement returns the number ofvalues in the list:

@Elements(Locations)

Field valuesThe value of a field is as specified in the document when a formula starts.The formula can modify the value of a field unless prohibited by accesscontrol. You must use the FIELD keyword to modify a field — otherwise,the variable is treated as a temporary variable. The FIELD keyword can alsobe used to create a new field in the current document. The followingformula writes a value to the text field Subject.

FIELD Subject := "No Subject"

Null fieldsA null field is equivalent to the text constant “” (empty quotation marks).The following example tests the field named Subject in the currentdocument. If the value of Subject is null, it is reset to “No Subject.”Otherwise, its value does not change.

FIELD Subject := @If(Subject=""; "No Subject"; Subject)

Since “” is a text constant, you should avoid its use in non-text fields. Inparticular, editable non-text fields should use a default formula to ensurethat the field contains a value of the correct type.

Deleting fieldsUse @DeleteField to delete a field from a document.

FIELD BodyText := @DeleteField

Form fieldsIf the form used to create a document is not stored in the document, a fieldnamed Form is available and contains the name of the form. If the form isstored in the document, fields named $TITLE, $Info, $WindowTitle (if thedesign specifies a window title), and $Body are available. $TITLE containsthe name of the form. The following example, which works in a button orhotspot, displays the name of the form used to create the current document.

@Prompt([OK]; "Form"; @If(@IsAvailable(Form); Form; $TITLE))

Choose File - Document Properties, and select Fields to see what fields arein a document.

64 Domino Designer Programming Guide, Volume 1: Formula Language

You can remove a form stored in a document by deleting $TITLE, $Info,$WindowTitle, and $Body. You must then create a Form field and place in itthe name of a form in the database. The following formula, which works asan agent, removes the form Travel Request stored in the current documentand replaces it with the database form Travel Arrangements.

SELECT $TITLE ="Travel Request";FIELD $TITLE := @DeleteField;FIELD $Info := @DeleteField;FIELD $WindowTitle := @DeleteField;FIELD $Body := @DeleteField;FIELD Form := "Travel Arrangements"

Temporary variablesA temporary variable exists only within a formula. Its scope is that formulaand it has no attributes other than the ones assigned to it within theformula.

The syntax for creating a temporary variable is:

variableName := value

The variable takes the type of the value on the righthand side of theequation. This value can be any of the field types or boolean. Boolean datatypes are returned by certain @functions and have a value of true (evaluatesto a text value of 1) or false (evaluates to a text value of 0).

Using a variable name on the lefthand side of an equation results in atemporary variable unless preceded by the keyword FIELD.

The following example makes extensive use of temporary variables to placethe name of the current month in a field named MonthName. The steps are:

1. Place the current date in the temporary variable date.

2. Extract from date and convert to text month, the number of the month.

3. Create a text list “nMonths” with the values 1 through 12.

4. Create a text list “months” with the values January through December.

5. Replace the number value of the current month with its name.date := @Created;month := @Text(@Month(date));nMonths := "1" : "2" : "3" : "4" : "5" : "6" : "7" : "8" : "9" : "10" : "11" : "12";months := "January" : "February" : "March" : "April" : "May" :"June" : "July" : "August" : "September" : "October" :"November" : "December";FIELD MonthName := @Replace(month; nMonths; months)

Chapter 3: Formula Language Rules 65

Using constants

Formulas use three types of constants.

Text constants

Numeric constants

Time-date constants

Lists can also be specified in a constant format.

Text constantsSpecify a text constant by enclosing characters, including spaces, numbers,and special characters, in quotation marks.

Do not enter variable names in quotation marks, or the names will betreated as text.

Enter numbers in quotation marks when you want them treated as text.

To include multiple characters, for example, spaces, use @Repeat.

The backslash ( \ ) serves as an escape character in a text constant. Toembed quotation marks in a text constant, precede each embeddedquotation mark with a backslash. To embed a backslash in a text constant,type two backslashes.

Examples: Text constants1. If you enter the following as a field default value formula, the word

Cost appears as the value in the field."Cost"

2. The formula is:"From: " + Author + " (" + @Text(@Created) + ")"

The result is: From: Mary Tsen (6/15/95)

3. The formula is:"From:" + @Repeat(" "; 8) + Author + " (" +@Text(@Created) + ")"

The result is:From: Mary Tsen (6/15/95)

66 Domino Designer Programming Guide, Volume 1: Formula Language

4. The formula is:"Type \"Yes\" or \"No\""

The result is:Type "Yes" or "No"

5. The formula is:"Type \\Yes\\ or \\No\\"

The result is:Type \Yes\ or \No\

Numeric constantsA numeric constant consists of numeric and special characters, with nointervening spaces, that conform to the following rules:

Integer — The characters 0 - 9 without intervening spaces comprise apositive integer.

Decimal — A decimal point may be placed before, after, or within thenumeric characters.

Sign — The first character of a number may be a plus or minus sign.

Scientific notation — A number may be suffixed by the letter E, anoptional plus (default) or minus sign, and an integer.

The table below shows the acceptable formats for entering numbers.

Type of Number Constant Result

Integer 123 123

Decimal .123 0.123

Negative number -123.4 -123.4

Scientific notation 123E2, 123E-2 12300, 1.23

Time-date constantsA time-date constant consists of a time and/or a date enclosed in squarebrackets formatted as follows:

12-hour time — A time in the format [hh:mm:ss] followed by the lettersAM or PM. The hours can range from 00 to 12. The seconds are optionaland default to 00.

24-hour time — A time in the format [hh:mm:ss]. The hours can rangefrom 00 to 23. The seconds are optional and default to 00).

Chapter 3: Formula Language Rules 67

Date — A date in the format [mm/dd/yy]. The year is optional anddefaults to the current year. Use yy to specify a year in the 20th century(yy is 50 or greater) or the 21st century (yy is less than 50); use yyyy tospecify any year. The validity of a date format depends on the dateseparator that users choose in their operating system control panel. Thedefault separator for Windows, UNIX, and Macintosh is a slash ( / ).The default separator for OS/2 is a hyphen ( - ).

Time and date — A time and a date in the format [time date] or [datetime].

If time-date values are subtracted, the result is an integer that represents thedifference between the times in seconds.

The table below shows the acceptable formats assuming this year is 1997.

Time-date format Constant Result in 12-hour time

24-hour time [5:30] 05:30:00 AM

12-hour time [5:30 PM] 05:30:00 PM

24-hour time [17:30] 05:30:00 PM

Date [6/15] 06/15/97

Date [6/15/97] 06/15/97

Time-date [6/15 5:30 PM] 06/15/97 05:30:00 PM

Time-date [5:30 PM 6/15] 06/15/97 05:30:00 PM

Difference [5:30 PM]-[5:30] 43200

Using operatorsOperators assign values, modify values, and combine existing values intonew values.

Operator overview and precedenceOrder of evaluationAssignment operatorList operatorUnary operatorsArithmetic operatorsText operatorComparison operatorsLogical operatorsOperations on lists

68 Domino Designer Programming Guide, Volume 1: Formula Language

Operator overview and precedenceThe table below lists the operators and their precedence, where 1 is thehighest precedence. The horizontal lines separate operators of differentprecedence.

Operator Operation Precedence

:= Assignment NA

: List concatenation 1

+

-

Positive

Negative

2

*

**

/

*/

Multiplication

Permuted multiplicationDivision

Permuted division

3

+

*+

-

*-

Addition, concatenation

Permuted addition

Subtraction

Permuted subtraction

4

=

*=

<>

!=

=!

><

*<>

<

*<

>

*>

<=

*<=

>=

*>=

Equal

Permuted equal

Not equal

Not equal

Not equal

Not equal

Permuted not equal

Less than

Permuted less than

Greater than

Permuted greater than

Less than or equal

Permuted less than or equal

Greater than or equal

Permuted greater than or equal

5

!

&

|

Logical NOT

Logical AND

Logical OR

6

Chapter 3: Formula Language Rules 69

Order of evaluation for operationsThe values involved in an operation must be of the same data type.Operations occur in the following order:

Parenthesis —You can explicitly force the order of evaluation withparenthesis. Operations within parentheses occur first. For example: (5 - 3) * (6 - 4) = 4

Precedence — Operations not in parenthesis occur in order ofprecedence starting with precedence 1. For example, multiplication hasgreater precedence than subtraction so 3 * 6 occurs first:5 - 3 * 6 - 4 = -17

Left to right — Operations of equal precedence occur left to right. Forexample:8 / 4 * 2 = 4

Assignment operatorThe assignment operator (:=) assigns a value on the righthand side to avariable on the lefthand side. The variable assumes the type of the value onthe righthand side.

This example assigns the numeric value 1 to the temporary variable n.

n := 1

This example increments the temporary variable n by 1.

n := n + 1

This example assigns the text value “London” to the temporary variablecity1.

city1 := "London"

The variable may be preceded by the keyword DEFAULT,ENVIRONMENT, or FIELD. A variable not preceded by a keyword is atemporary variable.

List operatorThe list operator (:) concatenates values into a list. The values must all be ofthe same type. This example is a three-member text list.

"London" : "New York" : "Tokyo"

70 Domino Designer Programming Guide, Volume 1: Formula Language

The values can be constants, variables, and expressions, including otherlists.

lny := "London" : "New York";lny : "Tokyo"

Since list concatenation has the highest precedence, list elements that areexpressions must be in parenthesis. In the following example, the minussign has the unintended effect of applying to both the third and fourthelements of the second list.

1:2:3:4 + 1:2:-3:4 = 2:4:0:0

Use parenthesis to make the minus operation apply only to the thirdelement of the second list.

1:2:3:4 + 1:2:(-3):4 = 2:4:0:8

Unary operatorsThe unary operators (+ and -) specify the sign of a numeric value. Anunsigned numeric value is positive. The following numeric values areequivalent:

5

+5

-(-5)

Arithmetic operatorsThe arithmetic operators (* / + -) combine two numeric values usingmultiplication, division, addition, and subtraction. The following operationsall result in the numeric value 16:

4 * 4

64 / 4

12 + 4

20 - 4

Text operatorThe text concatenation operator (+) combines two text values. The followingoperation results in the value of the variable CompanyName followed by acomma, a space, and Inc.

CompanyName + ", Inc."

Chapter 3: Formula Language Rules 71

Comparison operatorsThe comparison operators (=, <>, !=, ><, <, >, <=, and >=) compare valuesof the same type and produce a logical result (true or false). The followingoperations all result in a logical value of true:

"London" = "Lon" + "don"

"London" != "Tokyo"

2 + 2 > 3

Logical operatorsThe logical operators (!, &, and |) combine logical values. The followingoperations all result in a value of true. The operations are shown twice, withand without parenthesis. The parenthesis clarify the order of evaluation butare unnecessary because the logical operations are lower in precedence thanthe surrounding comparison operations.

4 = 2 + 2 & 5 = 3 + 2(4 = 2 + 2) & (5 = 3 + 2)

4 = 2 + 2 | 5 = 2 + 2(4 = 2 + 2) | (5 = 2 + 2)

! 5 = 2 + 2! (5 = 2 + 2)

Operations on listsOperations on lists are of two types:

Pair-wise — Pair-wise operators act on two lists in parallel-elementfashion. The first element of list 1 pairs with the first element of list 2,the second element of list 1 pairs with the second element of list 2, andso on. If one list has fewer elements than the other, the last element inthe shorter list is repeated for operations with the remaining elementsof the longer list. If list 1 consists of “A”:“B”:“C” and list 2 consists of“1”:“2”, the operation is performed as though list 2 contained“1”:“2”:“2”. For pair-wise equality tests, only one match is needed forthe statement to return True, or 1.

Permuted — Permutation operators act on two lists, pairing everypossible combination of their values. The resulting list has an elementfor each pairing in the following order: list 1 element 1 paired with eachelement in list 2, list 1 element 2 paired with each element in list 2, andso on through the last element in list 1.

If an operation occurs on a list and a non-list value, the non-list value ispaired with each element in the list.

72 Domino Designer Programming Guide, Volume 1: Formula Language

The table below shows the pair-wise and permutation operators.

Pair-wise Operator Permutation Operator Meaning

* ** Multiplication

/ */ Division

+ *+ Addition

- *- Subtraction

> *> Greater than

< *< Less than

>= *>= Greater than or equal to

<= *<= Less than or equal to

= *= Equal

!= *!= Not equal

The table below shows how pair-wise and permutation operators differ.

Operation Statement Yields

Concatenation,pair-wise

“A”:“B”:“C”+“1”:“2”:“3”

“A”:“B”:“C”+“1”:“2”

“A”:“B”:“C”+“1”

“A1”:“B2”:“C3”

“A1”:“B2”:“C2”

“A1”:“B1”:C1”

Concatenation,permutation

“A”:“B”:“C”*+“1”:“2”:“3”

“A”:“B”:“C”*+“1”:“2”

“A1”:“A2”:“A3”:“B1”:“B2”:“B3”:“C1”:“C2”:“C3”

“A1”:“A2”:“B1”:“B2”:“C1”:“C2”

Addition,pair-wise

1:2:3+10:20:30

1:2:3+10:20

1:2:3+10

11:22:33

11:22:23

11:12:13

Addition,permutation

1:2:3*+10:20:30

1:2:3*+10:20

11:21:31:12:22:32:13:23:33

11:21:12:22:13:23

Text equality,pair-wise

“A”:“B”:“C”=“B”:“C”:“A”

“A”:“B”:“C”=“B”:“C”

“B”:“B”:“C”=“B”:“C”

0 False

1 True

1

continued

Chapter 3: Formula Language Rules 73

Operation Statement Yields

Text equality,permutation

“A”:“B”:“C”*=“B”:“C”:“A”

“A”:“B”:“C”*=“B”:“C”

“B”:“B”:“C”*=“D”:“E”

1

1

0

Numberequality,pair-wise

1:2:3=2:3:1

1:2:3=2:3

2:3:3=2:3

2:3:3=3:1

0

1

1

0

Numberequality,permutation

1:2:3*=2:3:1

1:2:3*=2:3

1:2:3*=4:5

1

1

0

Date equality,pair-wise

[1-1-90]:[2-2-90]:[3-3-90]=

[3-3-90]:[2-2-90]:[1-1-90]

[1-1-90]:[2-2-90]:[3-3-90]=

[2-2-90]:[3-3-90]

[2-2-90]:[3-3-90]:[3-3-90]=

[2-2-90]:[3-3-90]

1

1

1

Date equality,permutation

[1-1-90]:[2-2-90]:[3-3-90]*=

[3-3-90]:[2-2-90]:[1-1-90]

[1-1-90]:[2-2-90]:[3-3-90]*=

[2-2-90]:[3-3-90]

[1-1-90]:[2-2-90]:[3-3-90]*=

[4-4-90]:[5-5-90]

1

1

0

74 Domino Designer Programming Guide, Volume 1: Formula Language

Using @functions

Notes @functions are built-in formulas that perform specializedcalculations and return a value.

Syntax

Return value

Side-effects

@Commands

Order of evaluation

For the individual @function and @command descriptions, see Chapters 5and 6.

SyntaxThe general format of an @function is:

@function-name(argument1; argument2; ... argumentn);

An @function consists of the name of the @function followed by arguments,if any. The first character of the name of an @function is always @.

ParenthesisEnclose @function arguments in parenthesis.

@Abs(-4)

Omit parenthesis for @functions without arguments.

@Created

Multiple argumentsSeparate multiple arguments with a semicolon.

@IsCategory("Yes"; "No")

@Middle(Company; 4; 4)

Keyword argumentsEnclose keyword arguments in square brackets. @Abstract, @Command,@PostedCommand, @DocMark, @GetPortsList, @PickList, @MailSend,@Name, and @Prompt use keyword parameters.

@Prompt([OK]; "Response"; Y)

@Name([CN]; AUTHOR)

@Command([EditClear])

Chapter 3: Formula Language Rules 75

Argument data typesSpecify the correct data type for each @function argument per the @functiondescription. For example, the first argument to @Prompt must be akeyword. If the keyword is [OK], it must be followed by two arguments oftype text.

@Prompt([OK]; "The answer is ..."; @Text(N));

Return valueAn @function calculates a return value and replaces itself with the value.The use of the @function must be appropriate for its data type. For example,@Power can compute the value of a numeric field:

@Power(2; Exp)

But must be wrapped in @Text to compute the value of a text field:

@Text(@Power(2; Exp))

Side-effectsA side-effect is an action that occurs outside the immediate scope of theformula. For example, @Prompt displays a dialog box in addition toreturning a value. Make sure that a side-effect occurs at the correct point ofa formula’s execution.

The following @functions have side-effects:

@Function Side-effect

@Command@PostedCommand

A Notes command, such as opening a database, isperformed.

@DbColumn@DbCommand@DbLookup

Another view or database is accessed, and data isretrieved.

@DDEInitiate@DDEExecute@DDEPoke@DDETerminate

A DDE conversation is initiated (or terminated), or a DDEstatement is executed.

@MailSend A Notes mail memo is created and routed to another useror database.

@Prompt@PickList@DialogBox

A dialog box is displayed; data may be returned.

76 Domino Designer Programming Guide, Volume 1: Formula Language

@CommandsThe @Command and @PostedCommand functions execute a Notescommand. The first argument to @Command or @PostedCommand is akeyword argument that specifies the Notes command. Depending on theNotes command, other arguments may be required.

You must use @PostedCommand in applications that run in Notes R3 andR4. The difference between @Command and @PostedCommand is the orderof evaluation.

Because of their large number and special status, these @functions comprisea separate category called @commands. Each @command is named after thefirst argument to @Command or @PostedCommand, which is a keywordargument.

Most @commands mimic a menu command. For example:

@Command([AddDatabase]; "Legal1":"Trademrk.nsf")

@Command([AdminRegisterUser])

@PostedCommand([DesignForms])

@PostedCommand([EditDown]; "5")

You must be careful with @commands due to their side-effects and theirorder of evaluation.

See “Order of evaluation for formula statements” and “Side-effects” in thischapter for additional information.

You can use @commands in formulas for SmartIcons, buttons, hotspots, and actions. You can use @commands in agent formulas that run on thecurrent document. See the individual @command descriptions for furtherrestrictions.

Setting the NoExternalApps environment variable to 1 disables any formulacontaining an @command function. The user does not receive an errormessage — the formula simply does not execute.

Order of evaluation for formula statementsNotes evaluates formulas from top to bottom and left to right, completing each statement before proceeding to the next, except that@PostedCommand and a few @Command functions are executed in orderafter all other @functions complete execution. Formula language does notcontain any branching or iteration constructs. It does contain several@functions for control logic.

Except for @commands, the formula language operates on back-end Notesobjects. For example, a field named in a formula refers to the field as it

Chapter 3: Formula Language Rules 77

exists in storage and the FIELD keyword modifies a stored field.@Commands operate in the user interface; changes made there are notreflected in the back-end until a document is saved. You cannot intersperseback-end and user interface accesses of the same document and get correctresults.

Evaluation of @commandsExecution of an @PostedCommand function occurs after all other@functions in the formula. If you write the following formula:

@PostedCommand([CommandName]; Argument);@If(Condition; TrueStatement; FalseStatement);FIELD X := "Text"

The first statement is executed last.

Execution of an @Command function occurs in the order it appears withsome exceptions. The exceptions execute in @PostedCommand order, thatis, at the end of the formula. The exceptions are: [FileCloseWindow],[FileDatabaseDelete], [FileExit], [NavigateNext], [NavigateNextMain],[NavigateNextSelected], [NavigateNextUnread], [NavigatePrev],[NavigatePrevMain], [NavigatePrevSelected], [NavigatePrevUnread],[NavigateToBackLink], [ToolsRunBackgroundMacro], [ToolsRunMacro],[ViewChange], [ViewSwitchForm].

@If function@If executes one statement or another depending on whether a logical valueis true or false:

@If(LogicalValue; TrueStatement; FalseStatement)

@Do function@Do executes a number of statements in sequence and can be used as anexecution path within an @If function:

@If(LogicalValue; @Do(TrueStatement1; TrueStatement2);FalseStatement)

Any @Command functions within an @Do function are executed in orderafter all other @functions, both within and without the @Do function, areexecuted.

@Return function@Return stops execution of the formula:

@If(LogicalValue; @Return(""); "")

78 Domino Designer Programming Guide, Volume 1: Formula Language

Using keywords

Formula language includes a set of keywords that perform specialfunctions:

Keyword syntax Description

DEFAULT fieldName :=value

Associates a value with a field. If the field exists inthe document being processed, its current value isused. If the field does not exist, the document istreated as if the field does exist and the DEFAULTvalue is used.

ENVIRONMENT variable :=textValue

Assigns a value to an environment variable in theuser’s notes.ini file (Windows, OS/2, UNIX) or NotesPreferences file (Macintosh).

FIELD fieldName := value Assigns a value to a field in the current document. Ifthe field does not exist, it is created; if it alreadyexists, the contents are replaced.

REM [“remarks”] Inserts documentation into the formula withoutaffecting its function.

SELECT logicalValue Specifies whether or not the current document isvalid for processing in view selection, replication,and agent formulas.

A keyword is always the first word in a statement. By convention,keywords are entered in uppercase. You can enter them in lowercase, butNotes converts them to uppercase when saving a formula.

The fieldName and variable specifications to keywords are names, not textconstants. Do not enclose them in parentheses.

Examples: Using keywords1. (DEFAULT) — If the field KeyThought exists, whatever value is in that

field is used for the computed field. If the field KeyThought does notexist, the value of Topic is used.DEFAULT KeyThought := Topic;KeyThought

This formula is equivalent:@If(@IsAvailable(KeyThought); KeyThought; Topic)

2. (ENVIRONMENT) — Converts a number to text and saves it as anenvironment variable.ENVIRONMENT OrderNumber := @Text(NewOrderNumber)

3. (FIELD) — This formula adds “Inc.” to the value of the Company field.

Chapter 3: Formula Language Rules 79

@If(@Matches(@LowerCase(Company); "*, inc*"); @Return("");"");FIELD Company := Company + ", Inc.";

4. (FIELD) — This formula creates a new field called CompanyName tohold the name of the company plus “Inc.” The field does not becomevisible unless you add it to the form design, but you can access it bynaming it in formulas.FIELD CompanyName := Company + ", Inc.";

5. (FIELD) — This formula deletes the field CompanyName.FIELD CompanyName := @DeleteField;

6. (REM) — This formula contains five lines of comments before the code.REM "6/15/95";REM "The following formula calculates the date";REM "for the DueDate field";REM "DueDate is the Date field + thirty days";REM;@Adjust(Date; 0;0;30;0;0;0)

7. (SELECT) — This formula selects all documents in the database.SELECT @All

8. (SELECT) — This view selection formula selects only documentscomposed from the Product Specification form or that are responsedocuments.SELECT Form="Product Specification" | @IsResponseDoc

9. (SELECT) — This example changes the value of the Status field toClosed except for documents whose Categories Field is “UnsignedContracts.”SELECT Categories != "Unsigned Contracts";FIELD Status := "Closed"

80 Domino Designer Programming Guide, Volume 1: Formula Language

Specifying form and view names in formulas

When you specify a form or view name in a formula:

Do not include the accelerator character, an underscore, in the name if itexists. The formula language treats an underscore as a literalunderscore.

Do include the cascade character, a backslash, but remember that itrequires the escape character so must be entered as two backslashes.

The following formula demonstrates how to enter the view name“_Marketing\_Procedures”:

@Command([ViewChange]; "Marketing\\Procedures")

Debugging formulasThe formula language does not provide a formal debugging mechanism.You can use @Prompt to stop at certain points and to examine variables.This example uses @Prompt to set a checkpoint and then to examine avariable. After you establish that your code is running correctly, remove thedebug statements.

@Prompt([OK]; "Checkpoint"; "About to calculate LastName");LastName := @RightBack(@Left(@UserName; "/"); " ");@Prompt([OK]; "Value of LastName"; LastName)

In some cases, such as agents that do not run on the current document andselection formulas, @Prompt does not work. You do not receive a cautionwhen you write or run the formula — the statement simply does not run. Towork around this problem, you can write the formula in a SmartIconsobject, an action, or some other object in which @Prompt works. Aftertesting the formula there, remove the debug statements and copy and pastethe formula into the desired object.

Alternatively, you can design debug fields into the form for the documentsyour formula processes. Your formula loads the debug fields during testingand you open the documents processed to examine the fields. After testing,remove the debug fields from the form as well as the debug statementsfrom the formula.

FIELD DebugLastName := lastName

Chapter 3: Formula Language Rules 81

Chapter 4 Formula Language Coding Guidelines

Formulas are expressions that have program-like attributes. For example,you can assign values to variables and use a limited control logic. Theformula language interface to Domino is through calls to @functions.@Commands, a subset of the @functions, provide access to the user interface.

See Formula Language @Functions A-Z and Formula Language@Commands A-Z for a reference.

Formulas

A formula consists of one or more statements that are executed in order.Depending on the object associated with the formula and other criteria, theformula may execute once or it may execute multiple times on selecteddocuments (one execution per document).

Formulas do not have language elements for loop iteration and transfers of control except for returning from the formula. Conditional pathexecution is limited.

Agent formulas execute multiple times on selected documents giving theeffect of conditional, iterative execution. Data can be processed in listsgiving the effect of conditional, iterative execution.

You can:

Write formulas that evaluate to a result

Write formulas that perform actions

Work with lists

Use conditional statements

83

Writing formulas that evaluate to a resultThe final statement of the following formulas must evaluate to a result:

Replication formula — Must evaluate to true (1) or false (0), and isapplied to each document in the database.

Form formula — Must evaluate to the name of a form.

Selection formula — Must evaluate to true (1) or false (0), and is appliedto each document in the view.

Column formula — Must evaluate to a value that can be converted to atext string.

Show action formula — Must evaluate to true (1) or false (0).

Formula pop-up — Must evaluate to a text string.

Window title formula — Must evaluate to a text or numeric valueexcept that the formula can consist of a single field of any type.

Section access formula — Must evaluate to a name or list of names.

Insert subform formula — Must evaluate to a text value that is the nameof a subform.

Section title formula — Must evaluate to a text or numeric value exceptthat the formula can consist of a single field of any type.

Hidden paragraph formula — Must evaluate to true (1) or false (0).

Default value formula — Must evaluate to a value suitable for storagein the current field.

Input translation formula — Must evaluate to a value suitable forstorage in the current field.

Default validation formula — Must evaluate to success (1) or failure (0).

Computed field formula — Must evaluate to a value suitable forstorage in the current field.

Keyword field formula — Must evaluate to a value or list of valuessuitable for storage in the current field.

These formulas may be as simple as a single field, constant, or @function, ormay contain multiple statements, use temporary variables, modify fields,and produce side-effects. In all cases, however, their final statement must bea value suitable for the result.

The keyword SELECT is prepended to the logical statement that terminatesa replication or selection formula if SELECT is not explicitly specified.These formulas run against every document in the database (replicationformula) or view (selection formula) to determine their inclusion orexclusion in the replication process or the view. The @All function returnsthe value true so the formula “SELECT @All” includes all documents.

84 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: Writing formulas that evaluate to a result1. This example is the default value formula for the From field in a

standard discussion database. It consists of a single @function thatreturns the user’s name.@UserName

2. This example is an adaptation of the input validation formula for theSubject field in a standard discussion database. It consists of an @Iffunction that returns failure if the Subject field is blank (the user did notenter a value) and success if the Subject field contains something. Thefailure condition has the side-effect of printing a message.@If(Subject = ""; @Failure("You must enter a subject foryour document."); @Success)

3. This example is an adaptation of the window title formula for theMemo form in a standard discussion database. It is a single statementbut contains embedded @If commands. If the current document is new,the window title becomes “New Memo.” If the current documentalready existed and the Subject field exists and is not blank, the windowtitle becomes the value of the Subject field, prepended by “>> ” if it hasattachments. If the Subject field does not exist or is blank, the windowtitle becomes the creation date.@If(@IsNewDoc; "New Memo"; @If(@IsAvailable(Subject) &Subject != ""; @If(@Attachments; "» "; "") + Subject;@Text(@Created)))

Writing formulas that perform actionsThe following formulas do not evaluate to a final, usable result but dependon their field assignments and side-effects for function:

SmartIcons formula — Executes once when triggered.

Agent formula — Executes on a database when triggered. An agentformula executes once on each selected document as determined bycriteria specified in the UI and a SELECT keyword included in theformula. The SELECT keyword defaults to SELECT @All.

Action formula — Executes on a view or form when triggered.

Button formula — Executes on a form, navigator, or rich text field whentriggered.

Action hotspot — Executes on a form, navigator, or rich text field whentriggered.

Chapter 4: Formula Language Coding Guidelines 85

Examples: Writing formulas that perform actionsThis agent example substitutes “Wayside Drive” for “Wayside Street” inthe Address field of documents based on Main Form. The effective action isthe FIELD Address assignment. If Address contains “Wayside Street,” thenew Address consists of the characters to the left of “Wayside Street,” thestring “Wayside Drive,” and the characters to the right of “Wayside Street.”Otherwise, Address is reset to its current value.

SELECT Form = "Main Form";ws := "Wayside Street";wd := "Wayside Drive";FIELD Address := @If(@Contains(Address; ws); @Left(Address;ws) + wd +@Right(Address; ws); Address)

Working with listsA list is a named entity that can contain multiple values of the same type.Lists occur as follows:

A field that allows multiple values may contain a list rather than ascalar value.

Some @functions return a list.

Constants can be specified as lists as well as scalar values. The syntax ismultiple scalar constants separated by colons; for example, “London” :“New York” : “Tokyo” is a string list constant of three elements.

Since list concatenation has the highest precedence, list elements thatare expressions must be in parentheses if the expression applies only tothat element. For example, write 1:2:(-3):4, not 1:2:-3:4, if 3 is negativeand 4 is not.

Operators combine lists on a pair-wise or permuted basis.

For more information, see “Operations on lists” in Chapter 3.

Lists provide limited iteration because a list operation applies the operationto each element of the list, like processing an array in a loop.

86 Domino Designer Programming Guide, Volume 1: Formula Language

The following @functions deal specifically with lists.

Function Description

@Elements(list) Determines the number of elements in a list.

@Explode(string) Converts a text string into a text list. Spaces,commas, and semicolons separate elementsin the string.

@Explode(string; separator) As above but the second parameter specifiesthe separators for elements in the string.

@Explode(string; separator; empties) As above but @True for the third parameterincludes empty list elements whereconsecutive separators occur.

@Explode(date-range) Converts a date range into a list of dates.The argument must be time-date value; thereturn value is text list.

@Implode(list) Converts a text list to a text string usingspaces to separate elements.

@Implode(list; separator) As above but the second parameter specifiesthe separator for elements in the string.

@IsMember(string; list) Determines if a string is a member of a list.Returns true (1) or false (0).

@IsMember(list1; list2) Determines if a list is contained in anotherlist. Returns true (1) or false (0).

@IsNotMember(string; list) Determines if a string is not a member of alist. Returns true (1) or false (0).

@IsNotMember(list1; list2) Determines if a list is not contained inanother list. Returns true (1) or false (0).

@Keywords(list1; list2) Locates words in list1 that match words inlist2. Word separators are “ , ? ! ; : [ ] { } < >

@Keywords(list1; list2; separator) As above but the second parameter specifiesthe word separators.

@Member(value; list) Determines the position of a value in astring list.

@Replace(list1; list2; list3) Replaces values in list1 that match values inlist2 with the corresponding values in list3.

@Subset(list; n) Extracts n number of values from the list.Use -n to extract right to left.

@Unique(list) Removes duplicate values from a string list.

@Unique Returns a random, unique text value.

Chapter 4: Formula Language Coding Guidelines 87

Examples: Working with lists1. (Pair-wise operation). This example adds two numeric lists in a

pair-wise operation. The resulting list has the 4 values 11, 22, 27, and 44.list1 := 10 : 20 : 30 : 40;list2 := 1 : 2 : (-3) : 4;list3 := list1 + list2;result := @Text(list1) + " + " + @Text(list2) + " = " +@Text(list3);@Prompt([OKCANCELLIST]; "Result"; ""; ""; result)

2. (Permuted operation). This example concatenates two lists in apermuted operation. The resulting list has the 12 values Blue Sedan,Blue Coupe, Blue Van, Blue Truck, Red Sedan, and so on throughYellow Truck.cars := "Sedan" : "Coupe" : "Van" : "Truck";colors := "Blue" : "Red" : "Yellow";result := colors + " " *+ cars;@Prompt([OKCANCELLIST]; "Result"; ""; ""; result)

3. (@Elements). This example prints a message if the Categories field hasno elements and prints the list if it does.@If(@Elements(Categories) = 0; @Prompt([OK]; "Categories";"No categories");@Prompt([OKCANCELLIST]; "Categories"; ""; ""; Categories))

4. (@Explode). This example explodes a string constant into a list using thedefault separators space, comma, and semicolon. The resulting list hasthe values Paris, London, Chicago, and Seoul.cityList := @Explode("Paris London,Chicago;Seoul");@Prompt([OKCANCELLIST]; "List of cities"; ""; "";cityList)

5. (@Explode). This example explodes a string constant into a list using theseparators comma and semicolon. The resulting list has the valuesParis, London, New York, and Hong Kong. New York and Hong Kongare not separated into New, York, Hong, and Kong because the space isnot included as a separator.cityList := @Explode("Paris,London,New York;Hong Kong";",;");@Prompt([OKCANCELLIST]; "List of cities"; ""; "";cityList)

6. (@Explode). This example includes a blank entry between London andNew York. If the third parameter is @False or is omitted, multipleconsecutive separators are treated as one. Ensure that the commas areconsecutive and not separated by a space.

88 Domino Designer Programming Guide, Volume 1: Formula Language

cityList := @Explode("Paris,London,,New York;Hong Kong";",;"; @True);@Prompt([OKCANCELLIST]; "List of cities"; ""; "";cityList)

7. (@Implode). This example implodes a list constant into a string variableusing a space (the default) to separate the values. The resulting stringhas the value: Minneapolis Detroit Chicago.city := "Minneapolis" : "Detroit" : "Chicago";cityString := @Implode(city);@Prompt([OK]; "Imploded string"; cityString)

8. (@Implode). This example implodes a list constant into a string variableusing a comma and a space to separate the values. The resulting stringhas the value: Minneapolis, Detroit, Chicago.city := "Minneapolis" : "Detroit" : "Chicago";cityString := @Implode(city; ", ");@Prompt([OK]; "Imploded string"; cityString)

9. (@Implode). This example implodes a list field into a string using acolon to separate the values. If the Categories field is entered asMinneapolis, Detroit, Chicago, the resulting string isMinneapolis:Detroit:Chicago.@Prompt([OK]; "Categories"; @Implode(Categories; ":"))

10. (IsMember). This agent example checks the selected documents to see ifAdjusted is in the Categories list. If it is, Categories remains the same. Ifit is not, Adjusted is added to the Categories list.FIELD Categories := @If(@IsMember("Adjusted"; Categories);Categories; @Explode(@Implode(Categories; ";") +";Adjusted"; ";"));SELECT @All

11. (@IsNotMember). This example checks the selected documents to see ifAdjusted and Signed off are in the Categories list. If both are not, bothare added to the Categories list. If both are, Categories remains thesame.FIELD Categories := @If(@IsNotMember("Adjusted" : "Signedoff"; Categories); @Explode(@Implode(Categories; ";") +";Adjusted;Signed off"; ";"); Categories);SELECT @All

12. (@Keywords). This example finds which keywords are used in theCities field.keywords := @Keywords(Cities ; "Paris" : "Moscow" :"Tokyo" : "Boston");@Prompt([OK]; "Keywords"; keywords)

Chapter 4: Formula Language Coding Guidelines 89

13. (@Member). This example has the user pick a value from a list anddisplays the number of that value within the list.cars := "Sedan" : "Coupe" : "Van" : "Truck";car := @Prompt([OKCANCELLIST] : [NOSORT]; "Cars"; "Pickone"; "Sedan"; cars);n := @Member(car; cars);@Prompt([OK]; "Your selection is ..."; "Number " +@Text(n))

14. (@Replace). This example replaces red with scarlet and blue withturquoise in the list derived from colors.colors := "red" : "blue" : "yellow" : "blue" : "black" :"red";from := "red" : "blue";to := "scarlet" : "turquoise";result := @Replace(colors; from; to);@Prompt([OKCANCELLIST] : [NoSort]; "Replacement list"; "";""; result)

15. (@Subset). This example places New Orleans, London, and Frankfurtinto first3, and Singapore and Sydney into last2.cities := "New Orleans" : "London" : "Frankfurt" :"Singapore" :"Sydney";first3 := @Subset(cities; 3);last2 := @Subset(cities; -2);@Prompt([OKCANCELLIST] : [NoSort]; "First three"; ""; "";first3);@Prompt([OKCANCELLIST] : [NoSort]; "Last two"; ""; "";last2)

16. (@Unique). This example returns a list with four elements: red, blue,yellow, and black.colors := "red" : "blue" : "yellow" : "blue" : "black" :"red";result := @Unique(colors);@Prompt([OKCANCELLIST] : [NoSort]; "Unique list"; ""; "";result)

Using conditional statements@If lets you execute one statement or another depending on whether acondition is true or false. A condition is typically the comparison of values,but can also be a constant, a variable, or the result of an @function. Forexample:

@ViewTitle = “By Author” is true if the name of the current view is “By Author.”

@Elements(Categories) > 0 is true if Categories has at least one element.

90 Domino Designer Programming Guide, Volume 1: Formula Language

1 used as a condition means true. @True and @Yes return 1.Comparisons and @functions that evaluate to a condition return 1 if thecondition is true.

0 used as a condition means false. @False and @No return 0.Comparisons and @functions that evaluate to a condition return 0 if thecondition is false.

The @If statement has an odd number of parameters with a minimum ofthree, as follows:

The condition is the first parameter and every other parameterthereafter if the @If statement has multiple conditions.

The statement that is executed if the condition is true is the secondparameter and every other parameter thereafter if the @If statement hasmultiple conditions.

The statement that is executed if the condition is false is the lastparameter.

The simplest @If statement has the following syntax:

@If(condition; true statement; false statement)

An @If statement with three conditions has the following syntax:

@If(condition1; true1; condition2; true2; condition3; true3; false)

The @If function is evaluated left to right and the first condition that is truecauses its corresponding true statement (that is, the next parameter) to beprocessed. No further evaluation or processing within the @If statementtakes place. If none of the conditions are true, the false statement (that is,the last parameter) is processed.

The true and false statements take various forms depending on their context:

If the @If statement is the last statement in a formula that evaluates to aresult, the true and false statements must evaluate to a result.

If the @If statement is the righthand side of an assignment, the true andfalse statements must evaluate to a value suitable to assignment to thefield or temporary variable on the left side.

Otherwise, the true and false statements must cause an action.

A true or false statement in @If cannot contain an assignment. The left sideof an assignment can occur only at the beginning of an outermost statementin a formula. The following syntax is illegal:

@If(condition; variable := value1; variable := value2)

Chapter 4: Formula Language Coding Guidelines 91

You must write it as:

variable := @If(condition; value1; value2)

The parameters of @If can themselves be @If statements. Nested @Ifstatements are useful to work around the limited logic constructs in theformula language but make for complicated syntax.

The @Do function provides a means to execute multiple statements on atrue or false condition.

For more information on conditional operators, see “Using operators” inChapter 3.

Examples: Using conditional statements1. This agent example compares the number of elements in Categories to

0. If the field has elements, it is not changed (it is set to itself). If the fielddoes not have elements, it is set to a constant string.FIELD Categories := @If(@Elements(Categories) > 0;Categories; "To be supplied ...");SELECT @All

2. This window title example first checks the return value of @IsNewDoc.If the document is new, the window title is set to the text constant “NewTopic.” If the document already exists, the window title is set to theSubject field if the current view is AuthorView. Otherwise, the windowtitle is set to the Subject field followed by a string denoting the numberof response documents.StandardTitle := Subject + @DocDescendants(" (NoResponses)"; " (1 Response)"; " (% Responses)");@If(@IsNewDoc; "New Topic"; @ViewTitle = "AuthorView";Subject; StandardTitle)

Writing messages and getting user inputYou can communicate with the user through these techniques:

Writing messages with @Prompt

Getting user input with @Prompt and @Picklist

Filling out a form with @DialogBox

Getting and setting environment variables

92 Domino Designer Programming Guide, Volume 1: Formula Language

Writing messages with @PromptUse the following forms of @Prompt to write messages to an interactive user:

@Prompt([OK]; title; prompt) displays an informational dialog box with the title text at the top of the box and the prompt text in the bodyof the box.

@Prompt([OKCANCELLIST] : [NOSORT]; title; prompt; default; choices)displays a box with the title text at the top of the box, the prompt text inthe body of the box, and the choices text list below the prompt text. Thisform of @Prompt is primarily for getting input but can be used fordisplay. The last parameter must be a text list. The prompt and defaultparameters can be empty. However, if this statement is not the laststatement in the formula and the user clicks Cancel, the rest of theformula is not executed. Do not specify [NOSORT] if you want the list sorted.

Non-text values must be converted with @Text to be used as @Promptparameters. The text values can be constants, temporary variables, fields, orexpressions.

Examples: Writing messages with @Prompt1. This example writes a text constant as the title and a text expression in

the dialog box. The expression is a concatenation of text constants andtime-date values converted to text.@Prompt([OK]; "Current time and date"; "The date is " +@Text(@Now; "D0S0") + ". " + "The time is " + @Text(@Now;"T0S1") + ".")

2. This example writes a text constant as the title. The content of the box isa text constant followed by the value of a multi-value field.@Prompt([OKCANCELLIST] : [NoSort]; "Field offices";"Current field offices are located in the followingcities:"; ""; Field_offices)

Getting user input with @Prompt and @PickListUse the following forms of @Prompt and @PickList to get input from aninteractive user:

@Prompt([YesNo]; title; prompt) displays a dialog box with title text,prompt text, and Yes and No buttons. @Prompt returns true (1) if theuser clicks Yes and false (0) if the user clicks No.

@Prompt([YesNoCancel]; title; prompt) displays a dialog box with titletext, prompt text, and Yes, No, and Cancel buttons. @Prompt returnstrue (1) if the user clicks Yes, false (0) if the user clicks No, and -1 if theuser clicks Cancel.

Chapter 4: Formula Language Coding Guidelines 93

@Prompt([OkCancelEdit]; title; prompt, default) displays a dialog boxwith title text, prompt text, and a box in which the user can type.@Prompt returns what the user types as a text value. If the user clicksCancel, the formula terminates immediately.

@Prompt([Password]; title; prompt) is as above but echoes Xs instead ofwhat the user types in.

@Prompt([OkCancelList] : [NoSort]; title; prompt; default; choices)displays a box with the title text at the top of the box, the prompt text inthe body of the box, and the choices text list below the prompt text,with the default highlighted. The last parameter must be a text list.@Prompt returns the list element the user selects. If the user clicksCancel, the formula terminates immediately. Do not specify [NoSort] ifyou want the list sorted. @DbColumn can be used to generate listsbased on the current contents of views in specified databases.

@Prompt([OkCancelCombo]; title; prompt; default; choices) is as abovebut uses a drop-down list with the default in the box above the list.

@Prompt([OkCancelEditCombo]; title; prompt; default; choices) is asabove but lets the user enter a value in the box above the list or select avalue from the list.

@Prompt([OkCancelListMult]; title; prompt; default; choices) is likeOkCancelList but allows the user to select multiple list elements andreturns a list.

@Prompt([LocalBrowse]; title; filetype) displays a box that allows theuser to select names from the local file system. Title text is at the top ofthe box, a list box for selecting files is at the left of the body of the box,below it is a list box for the type of file, and to the right is a list box forselecting the directory. Select, Cancel and Network or Help buttons.The filetype parameter is a text value, a number from 1 to 3, thatspecifies the types of files to display initially: “1” for .nsf files only; “2”for .ntf files only; “3” for files of all type.

@PickList([Custom] : [Single]; server : file; view; title; prompt; column)displays a box with the title, prompt, and list of choices. The list is aview in a specified database. The user can select one (if [Single] isspecified) or any number of elements (if [Single] is not specified);@PickList returns the values in the specified column for the selected listelements. This is like using @DbColumn to generate a list for @Prompt.

@PickList([Name] : [Single]) is as above except that the database is anAddress Book and the view is the “People” view. The user can selectthe Address Book in the @PickList dialog box.

94 Domino Designer Programming Guide, Volume 1: Formula Language

Non-text values must be converted with @Text to be used as @Prompt and@PickList parameters. The text values can be constants, temporaryvariables, fields, or expressions.

The return value must be converted if it is to be used as a non-text value.

Examples: Getting user input with @Prompt and @PickList1. (YesNo). This validation formula queries the user concerning the

TotalAmount field. If the user clicks No, a failure message is posted.@If(@Prompt([YesNo]; "Is this total within budget?";@Text(TotalAmount; "C")); @Success; @Failure("Total notwithin budget"))

2. (OkCancelEdit). This button formula queries the user for a server anddatabase, and opens the database. If the user clicks Yes without firstentering a value in the edit box, the value returned is an empty string.server := @Prompt([OkCancelEdit]; "Server"; "Enter thename of a server"; "");database0 := @Prompt([OkCancelEdit]; "Database"; "Enterthe name of a database on " + @If(server = ""; "yourworkstation"; server); "");database := @If(@Contains(database0; "."); database0;database0 + ".nsf");@Command([FileOpenDatabase]; server : database)

3. (Password). This field validation formula gets a password from the userand compares it to the Password field in the document.pass := @Prompt([Password]; "Password"; "What is thepassword?");@If(pass = Password; @Success; @Failure("Passwordincorrect"))

4. (OkCancelList). This SmartIcons formula presents the user with the listof databases in a database catalog, and opens the database that the userselects. The first @DbColumn puts a list of the values in column 4 of theDatabases by _Replica ID view in the temporary variable titles. Thesecond @DbColumn puts a list of the values in column 2 of theDatabases by _Replica ID view in the temporary variable servers. Thethird @DbColumn puts a list of the values in column 3 of the Databasesby _Replica ID view in the temporary variable databases. Thetemporary variable list combines titles, servers, and databases forpresentation to the user in @Prompt. The formula then parses the return

Chapter 4: Formula Language Coding Guidelines 95

value from @Prompt into a server name and database name forinclusion in the FileOpenDatabase @command.titles := @DbColumn(""; "doc":"catalog.nsf"; "Databases by_Replica ID"; 4);servers := @DbColumn(""; "doc":"catalog.nsf"; "Databasesby _Replica ID"; 2);databases := @DbColumn(""; "doc":"catalog.nsf"; "Databasesby _Replica ID"; 3);list := titles + " *-* " + servers + " *:* " + databases;member := @Prompt([OkCancelList]; "Open Database"; "Selecta database"; ""; list);server := @Left(@Right(member; " *-* "); " *:* ");database := @Right(member; " *:* ");@Command([FileOpenDatabase]; server:database)

5. (OkCancelListMult). This button formula presents the user a list ofdepartment names and sales totals. The user selects any number ofelements from the list and the formula calculates a grand total.departments := @DbColumn(""; "" : "sales.nsf"; "MainView"; 1);totalSales := @DbColumn(""; "" : "sales.nsf"; "Main View";2);totalsList := @Text(totalSales; "C") + " " +departments;sumList := @Prompt([OkCancelListMult]; "Total sales bydepartment"; "Select the ones you want to sum"; "";totalsList);sum := @Sum(@TextToNumber(sumList)); @Prompt([OK]; "Sum";@Text(sum))

6. (Custom). This button formula presents the user the “Databases byReplica ID” view from CATALOG.NSF on DOC. The user selects anelement (row) from the list (view) and the formula opens that databasewhose name is in column 3 of that row.name := @PickList([Custom]; "doc" : "catalog"; "Databasesby Replica ID"; "Open database"; "Select a database thatis on server Doc"; 3);@Command([FileOpenDatabase]; "doc" : name)

Filling out a form with @DialogBox@DialogBox displays a form of your design in a dialog box that has OK andCancel buttons. When the user clicks OK, the contents of the fields in thedialog box transfer to any fields of the same name in the document in which@DialogBox is executing.

96 Domino Designer Programming Guide, Volume 1: Formula Language

@DialogBox does not transfer rich text fields. These should not be includedin your design.

The form that is displayed in the dialog box is best created using a layout region, and @DialogBox should use the [AutoVertFit] and[AutoHorzFit] options.

Example: Filling out a form with @DialogBoxYou have a form that has many fields, but a user creating a new documentonly fills in a few of them. You create another hidden form named “Dialog”that contains a layout region with the fields that the user typically fills in. Atthe top of the main form you create a button with the following formula.When the user clicks the button, the formula displays a dialog box with the“Dialog” form. The user fills in the fields in the dialog box and clicks OK.The fields transfer to the main form.

@DialogBox("Dialog"; [AutoVertFit] : [AutoHorzFit])

Getting and setting environment variablesYou can set and retrieve the values of the environment variables in thenotes.ini file (Windows, OS/2, and UNIX).

@SetEnvironment(variable; value) sets a named variable to the specifiedvalue. You can also use the ENVIRONMENT keyword and thetwo-parameter form of @Environment.

@Environment(variable) retrieves the value of a named variable.

Environment values are text. Non-text values must be converted beforebeing set and after being retrieved.

User environment variables are prepended with the $ character. If you addan environment variable with an editor or LotusScript, for example, andwant to retrieve it with @Environment, the first character must be $.

Be sure you know which notes.ini file is affected by your formula. If theformula is in a database on a server, the formula runs on the server in thefollowing cases: replication formula, agent whose trigger is If New MailHas Arrived or On Schedule, selection formula, or column formula.Otherwise, the formula runs on the user’s workstation. Replica copiesaccess different notes.ini files depending on which server or workstation thereplica copy is on. Server access is subject to administrative restrictions.

Some uses for environment variables are to:

Pass temporary data among different formulas and databases

Generate sequential numbers for one user

Chapter 4: Formula Language Coding Guidelines 97

Examples: Getting and setting environment variables1. This example converts a number to text and saves it as an

environment variable.ENVIRONMENT OrderNumber := @Text(NewOrderNumber);

These formulas are equivalent.@Environment("OrderNumber"; @Text(NewOrderNumber);

@SetEnvironment("OrderNumber"; @Text(NewOrderNumber);

2. This example retrieves the value of an environment variable, converts it to a number, and stores it in a local variable.OldOrderNumber :=@TextToNumber(@Environment("OrderNumber");

3. This example is for a Computed when composed field. The formulamaintains an environment variable named OrderNumber. When a newdocument is created, the formula retrieves the environment variableand increments it by 1. This algorithm does not work for databases thatare replicated—the database must exist on a single server orworkstation and the formula must run on that same machine.OldOrderNumber := @Environment("OrderNumber");NewOrderNumber := @TextToNumber(@If(OldOrderNumber = "";"0"; OldOrderNumber)) + 1;ENVIRONMENT OrderNumber := @Text(NewOrderNumber);NewOrderNumber;

4. The first formula is run once by each sales person. This formulaprompts for the sales area and makes it the value of an environmentvariable named SalesArea. In the form for the sales documents, youmake the second formula the default value formula for the SalesAreafield. This formula retrieves the value of the environment variable. Thesalesperson does not have to enter the sales area for each newdocument, and neither is a particular sales area hard-coded into thedefault value formula.ENVIRONMENT SalesArea := @Prompt([OKCANCELLIST]; "SalesArea"; "What is your sales area?"; "Central"; "East" :"Central" : "West");

@Environment("SalesArea");

Handling errorsErrors are of two types:

Syntax errors are reported when you check or attempt to exit theformula you are writing.

Run-time errors occur when the formula runs.

98 Domino Designer Programming Guide, Volume 1: Formula Language

Syntax errorsSyntax errors are reported when you check or attempt to exit the formulayou are writing. You receive a message specifying the error and the linecontaining the error is highlighted. You must determine and correct theerror before proceeding. The common syntax errors include:

Incorrectly spelled @function name or keyword

Missing or excessive parentheses

Missing quotation mark on a string constant

No semicolon between statements

You should write a formula a little at a time and check it often as you goalong. Formula syntax tends to be complex due to nesting.

Run-time errorsRun-time errors occur when the formula runs. These errors can becategorized as:

Unexpected — These are development errors that your users shouldnever see. For example, if you forget an @function parameter, thefollowing message appears at run-time: “Insufficient arguments for@function.” You should test your formula and attempt to correct allunexpected errors.

Unreported — These are results that are incorrect but are not reportedas errors. For example, if you try to display a numeric value with@Prompt, @Prompt works but displays a blank. Again, your usershould never see these errors. You should test your formula and ensurethat all results are as expected.

Expected — These are errors that the user might cause at run-time. Forexample, if you prompt for the name of a database, the user might enterthe name of a non-existent database. You cannot prevent these errorsbut you can anticipate and test for them in the formula and takeappropriate actions.

The following @functions help you deal with run-time errors:

@IsError(value) returns 1 if a field, temporary variable, or expressioncontains an error.

@Error generates an error.

@Failure(message) displays a message when used in an inputvalidation formula.

@Success always returns the value 1.

@Return(value) stops execution of the formula and returns a value.

Chapter 4: Formula Language Coding Guidelines 99

Notes generates an error for a field if the built-in validation checking fails.For example, if you specify a field as numeric and the user enters anon-numeric value, Notes makes the value of the field an error. You cangenerate an error for a field by setting its value to @Error.

Notes reports errors in fields when the user attempts to save the document.For example, if a numeric field contains an non-numeric value, Notesgenerates the message “Cannot convert text to a number” when the userattempts to save a document.

To change the message or perform another action when an error occurs, testthe field for an error with @IsError in the field validation formula. You cangenerate your own error message with @Failure, but only in field validationformulas.

To incorporate your own error conditions for a field, test the value of thefield in the field translation formula and return @Error if you detect anerror condition.

Outside field formulas, for example in an agent, button, or hotspot, you cancheck the contents of a field and react immediately to an error condition.For example, if you check a field with a button, you can change the fieldvalue or report the error before the user attempts to save the document. Inchecking for errors, be aware that the built-in validation checking generatesan error as soon as the user enters a value in a field, but that a translationformula using @Error does not generate an error until the user attempts tosave the document.

Examples: Run-time errors1. This validation formula for the Price field causes a save operation for

the document to fail with the specified message if the Price fieldcontains an error.@If(@IsError(Price); @Failure("The Price field must benumeric"); @Success)

2. This example contains input translation and input validation formulas.The input translation formula puts an error in the Price field if its valueis greater than 14.99. The input validation formula causes a saveoperation for the document to fail with the specified message if thePrice field contains an error.REM "Input translation formula for Price field";@If(Price > 14.99; @ERROR; Price)

REM "Input validation formula for Price field";@If(@IsError(Price); @Failure("The Price field must benumeric and 14.99 or less"); @Success)

100 Domino Designer Programming Guide, Volume 1: Formula Language

3. This button formula checks the Price field for an error before applying adiscount. If the field contains an error, the formula returns first givingthe user a message.FIELD Price := @If(!@IsError(Price) & @IsNumber(Price) &Price < 15; Price * 0.85; @Return(@Prompt([OK]; "Error inprice field"; "Must be numeric and less than 15.00";"")));@All

4. This button formula tests the Price field for an error. If the field containsan error, the formula resets it to a value taken from the user by@Prompt.FIELD Price := @If(!@IsError(Price) & @IsNumber(Price) &Price < 15; Price; @TextToNumber(@Prompt([OKCANCELEDIT];"Error in price field"; "Enter a number under $15.00";"")));@All

Working with @functionsAll @functions evaluate to a value and can be placed in a formula anywherea value of that type can be placed. When the formula executes, the value ofthe formula takes the formula’s place. Some formulas also have side-effects,that is, cause actions to occur. For example, @Prompt causes a message boxto appear.

Most @functions can be used in formulas for any Notes object, but some@functions are restricted in their applicability. The following table lists the @functions that are restricted and lists the Notes objects in which theycan be used effectively. In addition, for an @function to return informationon the current database, view, document, or field, these objects must be current.

Restricted function Function only works in these Notes objects

@All Replication formula, agent, view selection formula

@AllChildren Replication formula, view selection formula

@AllDescendants Replication formula, view selection formula

@Command SmartIcons formula, manual agent, button,action hotspot

@DbColumn (Notes databases) SmartIcons formula, action, button, hotspot,field design, agent except mail

continued

Chapter 4: Formula Language Coding Guidelines 101

Restricted function Function only works in these Notes objects

@DbLookup (Notes databases) SmartIcons formula, action, button, hotspot,field design, agent except mail

@DeleteDocument Agent

@DeleteField Agent

@DocChildren Column formula, window title formula

@DocDescendants Column formula, window title formula

@DocLevel Column formula, window title formula

@DocMark Agent

@DocNumber Column formula, window title formula

@DocParentNumber Column formula, window title formula

@DocSiblings Column formula, window title formula

@Failure Field validation formula

ENVIRONMENT All except formula pop-up hotspot

@Environment All except formula pop-up hotspot when writing

FIELD SmartIcons formula, agent, button, actionhotspot, field design

@IsCategory Column formula

@IsDocBeingLoaded Form design, field design

@IsDocBeingMailed Button, hotspot, field design

@IsDocBeingRecalculated Button, hotspot, field design

@IsDocBeingSaved Button, hotspot, field design

@IsExpandable Column formula

@IsNewDoc SmartIcons formula, button, window titleformula, form design, field design

@MailSend SmartIcons formula, agent, button, action hotspot

@PickList SmartIcons formula, manual agent, button,action hotspot, field design

@Platform SmartIcons formula, manual agent, button,hotspot, view design except selection andcolumn formulas, form design, field design

continued

102 Domino Designer Programming Guide, Volume 1: Formula Language

Restricted function Function only works in these Notes objects

@Prompt SmartIcons formula, manual agent, button,action hotspot, field design

@Responses Window title formula, field design

@Return SmartIcons formula, agent, button, hotspot,field design

SELECT Replication formula, agent, view selectionformula

@SetDocField SmartIcons formula, agent, button, actionhotspot, field design

@SetEnvironment All except formula pop-up hotspot

@SetField SmartIcons formula, agent, button, actionhotspot, field design

@Success Validation formula

@Unavailable Agent

@ViewTitle Agent

Working with @commandsd-name]; arg1; arg2; ... argn)

@PostedCommand([ command-name]; arg1 ; arg2 ; ... argn )

The name of the @function is @Command or @PostedCommand. The firstargument is the name of the @command enclosed in brackets. Theremaining arguments are the arguments to the @command. For a list of@commands, see the @commands (A-Z) reference chapter.

You cannot use an @command in a formula that does not interact with theuser such as a scheduled agent, a field formula, or a background macro.

You cannot use most @commands in Web applications, since they are basedon the Notes workstation user interface. You can only use the following@commands in Web applications (restrictions are noted in the individualdescriptions of the @ commands): [CalendarFormat], [CalendarGoTo],[Compose], [EditClear], [EditDocument], [EditInsertFileAttachment],[FileCloseWindow], [FileOpenDatabase], [OpenDocument], [FileSave],[NavigateNext], [NavigatePrev], [NavigateNextMain],[NavigatePrevMain], [OpenNavigator], [OpenView], [ToolsRunMacro],[ViewChange], [ViewExpandAll], [ViewCollapseAll], and[ViewShowSearchBar], [ViewRefreshFields], and [FileOpenDBRepID].

Chapter 4: Formula Language Coding Guidelines 103

@Command functions execute in sequence with other @functions, withsome exceptions. For example, the following formula executes the@command first:

@Command([EditDocument]; "1");@Prompt([OK]; "Edit mode"; "The document is now in editmode.")

@PostedCommand functions execute in sequence with each other after allother @functions execute. This emulates the behavior of @Command inNotes R3. For example, the following formula executes the @command last:

@PostedCommand([EditDocument]; "1");@Prompt([OK]; "Edit mode"; "The document will go into editmode.")

For additional information, see “Order of evaluation for formulastatements” in the Formula Language Rules chapter.

You can check and respond to the return value of @Command (but not@PostedCommand). The return value is @True if the @command succeedsand @False if it fails. The following SmartIcons example returns if theFileOpenDatabase @command fails.

@If(@Command([FileOpenDatabase]; "NEWSUBJ"); ""; @Return(""));@Command([Compose]; ""; "Main Topic");@Command([EditGotoField]; "Subject");@Command([EditInsertText]; "New subject");@Command([EditGotoField]; "Body")

Performing string operations

Formula language @functions enable you to:

Convert data types

Concatenate, compare, and determine length

Locate and extract substrings

Trim, repeat, add a new line, and change case

104 Domino Designer Programming Guide, Volume 1: Formula Language

Converting data typesData must be the correct type for the operation involved. The following@functions convert data, and test for type.

Function Description

@Text(value) Converts a value to a text string.

@Text(value; format) Converts a numeric or date-time value to atext string according to a specified format.

Converts a text string to a number.

Converts a text string to a date-time value.

@IsText(value) Returns true (1) if a value is a text string ortext string list.

@IsNumber(value) Returns true (1) if a value is a number ornumber list.

@IsTime(value) Returns true (1) if a value is a time-date ortime-date list.

@Char(number) Converts an IBM® Code Page 850 codenumber to its corresponding character.

Examples: Converting data types1. (@TextToNumber, @Text). This example reads a number interactively

using @Prompt, calculates its logarithm, and displays the answerinteractively using @Prompt. @Prompt works only with text values sothe input value i must be converted to a number before its log can becalculated, and the answer n must be converted to a text string before itcan be displayed.i := @Prompt([OKCANCELEDIT]; "@Log Test"; "Enter anumber"; "");n := @Log(@TextToNumber(i));@If(@IsError(n); @Return(@Prompt([OK]; "@Log Test"; i + "is not a number")); ""); @Prompt([OK]; "@Log Test"; "The logarithm of " + i + " is " + @Text(n))

2. (@Text). This example converts the current date-time as returned by@Now to text according to the date-time format T1S1 and displays it. T1means the time only and S1 means the hour and minute only. At six inthe evening, the user sees an information box with “The time is ...” asthe header and “06:00 PM” as the contents.@Prompt([OK]; "The time is ..."; @Text(@Now; "T1S1"))

Chapter 4: Formula Language Coding Guidelines 105

3. (@Text). This example converts the number 800 to text according to thenumber format C,2 and displays it. C means the currency format(leading dollar sign) and 2 means two decimal places. The user sees aninformation box with “800 dollars” as the header and “$800.00” as thecontents.@Prompt([OK]; "800 dollars"; @Text(800; "C,2"))

4. (@Text, @TextToTime). This example converts the text string “Today”to today’s date, then converts it to a text string for @Prompt. Forexample, if today is July 8, 1995, the user would see an information boxwith “Today’s Date” as the header and “07/08/95” as the contents.@Prompt([OK]; "Today's Date"; @Text(@TextToTime("Today")))

5. (@IsNumber). This example adds Fields A and B. If either field is notnumeric, it is first converted to the numeric value 0. While a user cannotenter a non-numeric value into a numeric field, a numeric field that isleft blank and has no default value formula defaults to a null text string.The @IsNumber function in this formula traps such an occurrence.@If(@IsNumber(A); A; 0) + @If(@IsNumber(B); B; 0)

6. (@Char). This example converts the integer 65 to an uppercase A.@Prompt([OK]; "IBM Code Page 850 code 65"; @Char(65))

Concatenating, comparing, and determining lengthThe + operator concatenates strings. The =, <>, !=, =!, ><, <, >, <=, and >=operators compare strings. The following @functions determine length andcompare strings:

Function Description and usage

@Length (string) Returns the length of a string in characters.

@Length(stringlist) Returns the length of each element of a string listin characters.

@Matches (string; pattern) Determines whether two strings match.Wildcards can be used to expand the scope ofthe comparison.

@Like (string; pattern) Determines whether two strings match.Conforms to ANSI SQL standard.

@Like(string; pattern; esc) Same as above with an escape character.

continued

106 Domino Designer Programming Guide, Volume 1: Formula Language

Function Description and usage

@Matches Uses ? to match any single character and * tomatch any sequence of characters, plus a numberof other wildcards. @Matches uses \ as anescape character.

@Like Uses _ (underline) to match any single characterand % (percent sign) to match any sequence ofcharacters in accordance with ANSI standardX3.135-1992.

Examples: Concatenating, comparing, and determining length1. (+). This example concatenates the two strings to form ABCDEF.

@Prompt([OK]; "Concatenation"; "ABC" + "DEF")

2. (+). This example concatenates the two input strings.Input1 := @Prompt([OKCANCELEDIT]; "Concatenation - firstelement"; "Enter any text in the box"; "ABC");Input2 := @Prompt([OKCANCELEDIT]; "Concatenation - secondelement"; "Enter any text in the box"; "DEF");@Prompt([OK]; "Concatenation - result"; Input1 + Input2)

3. (=). This example returns True to YesNo if the two input strings areequal, False if they are not equal.Input1 := @Prompt([OKCANCELEDIT]; "Comparison - firstelement"; "Enter any text in the box"; "ABC");Input2 := @Prompt([OKCANCELEDIT]; "Comparison - secondelement"; "Enter any text in the box"; "DEF");YesNO := @If(Input1 = Input2; "The strings are equal";"The strings are not equal"); @Prompt([OK]; "Comparison -result"; YesNo)

4. (@Length). This example displays 9, the length of abcdefghi.@Prompt([OK]; "Length of abcdefghi";@Text(@Length("abcdefghi")))

5. (@Length). This example creates a number list. Each element of this listcontains the length of the corresponding element in TextList.@Length(TextList)

6. (@Matches). This example returns True to YesNo if Input equals abc.Input := @Prompt([OKCANCELLIST]; "@Matches Input"; "Chooseone"; "abc"; "abc" : "bcd" : "cde" : "xyz" : "123");YesNo := @If(@Matches(Input; "abc"); " matches abc"; "does not match abc"); @Prompt([OK]; "@Matches Result";Input + YesNo)

Chapter 4: Formula Language Coding Guidelines 107

7. (@Matches). This example returns True to YesNo if every character inInput is alphabetic, that is, in the range a-z. The set {a-z} specifies thecharacter range and the preceding + means any number of occurrencesof the set.Input := @Prompt([OKCANCELLIST]; "@Matches Input"; "Chooseone"; "abc"; "abc" : "bcd" : "cde" : "xyz" : "123");YesNo := @If(@Matches(Input; "+{a-z}"); " matches +{a-z}";" does not match +{a-z}"); @Prompt([OK]; "@MatchesResult"; Input + YesNo)

8. (@Matches). This example returns True to YesNo if every character inInput is not alphabetic, that is, is outside the set {a-z}. The specification{!a-z} means not in the set of characters a-z, and the preceding + meansany number of occurrences of that set.Input := @Prompt([OKCANCELLIST]; "@Matches Input"; "Chooseone"; "abc"; "abc" : "bcd" : "cde" : "xyz" : "123");YesNo := @If(@Matches(Input; "+{!a-z}"); " matches+{!a-z}"; " does not match +{!a-z}"); @Prompt([OK];"@Matches Result"; Input + YesNo)

9. (@Matches). This Example returns True to YesNo if Input contains thecharacters bc in sequence surrounded by any number of any characters.Input := @Prompt([OKCANCELLIST]; "@Matches Input"; "Chooseone"; "abc"; "abc" : "bcd" : "cde" : "xyz" : "123");YesNo := @If(@Matches(Input; "*bc*"); " matches*bc*"; "does not match *bc*"); @Prompt([OK]; "@Matches Result";Input + YesNo)

10. (@Matches). This Example returns True to YesNo if Input starts with aand is three characters long or starts with 1 and is three characters long.Input := @Prompt([OKCANCELLIST]; "@Matches Input"; "Chooseone"; "abc"; "abc" : "bcd" : "cde" : "xyz" : "123");YesNo := @If(@Matches(Input; "a??|1??"); " matchesa??|1??"; " does not match a??|1??"); @Prompt([OK];"@Matches Result"; Input + YesNo)

11. (@Like). This agent example checks for two sets of strings in thetextBody field of each document. The first string is any text thatcontains “acquisition” and “Acme” in that order. The second string is any text that contains “Acme” and “51%” in that order. The second@Like statement uses the slash (/) as an escape character so the percent sign (%) can be specified. Don’t use the backslash (\) as anescape character.@If(@Like(textBody; "%acquisition%Acme%"); @Prompt([OK];"Found reference to \"acquisition\""; Subject); "");

108 Domino Designer Programming Guide, Volume 1: Formula Language

@If(@Like(textBody; "%Acme%51/%%"; "/"); @Prompt([OK];"Found reference to \"51%\""; Subject); "");SELECT @All

Locating and extracting substringsThe following @functions locate and extract substrings:

Function Description

@Contains(string; sub) Determines whether a string contains a substring.

@Contains(string; list) Determines whether a string contains any substringin a list.

@Begins(string; sub) Determines whether a string begins with a substring.

@Ends(string; sub) Determines whether a string ends with a substring.

@Left(string; n) Extracts the leftmost n characters from a string.

@Left(string; sub) Extracts the leftmost characters from a string up to asubstring, searching left to right.

@LeftBack (string; n) Extracts the leftmost characters from a string up tothe nth character from the right.

@LeftBack(string; sub) Extracts the leftmost characters from a string up to asubstring, searching right to left.

@Right(string; n) Extracts the rightmost n characters from a string.

@Right(string; sub) Extracts the rightmost characters from a string up toa substring, searching left to right.

@RightBack (string; n) Extracts the rightmost characters from a string up tothe nth character from the right.

@RightBack(string; sub) Extracts the rightmost characters from a string up toa substring, searching right to left.

@Middle(string; off; n) Extracts n characters from a string starting at anoffset, searching left to right.

@Middle(string; sub; n) Extracts n characters from a string starting at asubstring, searching left to right.

@Middle(string; off; sub) Extracts characters from a string starting at an offsetand stopping at a substring, searching left to right.

@Middle(string; sub; sub) Extracts characters from a string starting andstopping at substrings, searching left to right.

@MiddleBack(str; off; n) Extracts n characters from a string starting at anoffset, searching right to left.

continued

Chapter 4: Formula Language Coding Guidelines 109

Function Description

@MiddleBack(str; sub; n) Extracts n characters from a string starting at asubstring, searching right to left.

@MiddleBack(str; off; sub) Extracts characters from a string starting at an offsetand stopping at a substring, searching right to left.

@MiddleBack(str; sub; sub) Extracts characters from a string starting andstopping at substrings, searching right to left.

Replaces from with to in source. If from and to arelists, replaces corresponding entries in order.

@Word(string; sep; n) Extracts word n from a string where words are thetext between specified separators.

@Word(list; sep; n) Extracts word n from each string in a list wherewords are the text between specified separators.

Examples: Locating and extracting substrings1. (@Contains). This example returns True to R if Substring is anywhere in

String. The search is case-sensitive.String := @Prompt([OKCANCELEDIT]; "String"; "Enter astring"; "");Substring := @Prompt([OKCANCELEDIT]; "Substring"; "Enter abeginning substring"; "");Yes := Substring + " is in " + String;No := Substring + " is not in " + String;R := @Contains(String; Substring);@If(R; @Prompt([OK]; "Yes"; Yes); @Prompt([OK]; "No"; No))

2. (@Contains). This Example returns true to R if Substring1 or Substring2is anywhere in String. The search is case-sensitive.String := @Prompt([OKCANCELEDIT]; "String"; "Enter astring"; "");Substring1 := @Prompt([OKCANCELEDIT]; "Substring"; "Entersubstring 1"; "");Substring2 := @Prompt([OKCANCELEDIT]; "Substring"; "Entersubstring 2"; "");Yes := Substring1 + " or " + Substring2 + " is in " +String;No := Substring1 + " and " + Substring2 + " are not in " +String;R := @Contains(String; Substring1 : Substring2);@If(R; @Prompt([OK]; "Yes"; Yes); @Prompt([OK]; "No"; No))

3. (@Left). This example returns to R the leftmost N characters in String.String := @Prompt([OKCANCELEDIT]; "String"; "Enter astring"; "");

110 Domino Designer Programming Guide, Volume 1: Formula Language

Number := @Prompt([OKCANCELEDIT]; "Number of characters";"Enter a number of characters"; "");N := @TextToNumber(Number);R := @Left(String; N); @Prompt([OK]; "Leftmostcharacters"; R)

4. (@Left). This example returns to R the characters left of Substring inString.String := @Prompt([OKCANCELEDIT]; "String"; "Enter astring"; "");Substring := @Prompt([OKCANCELEDIT]; "Substring"; "Enter asubstring"; "");R := @Left(String; Substring); @Prompt([OK]; "Charactersleft of " + Substring; R)

5. (@RightBack, @Left). If the common name in the ComposedBy field is“Judith Woo,” this formula calculates “Woo, Judith.” @RightBackreturns the last name and @Left returns the first name.@RightBack(@Name([CN]; ComposedBy); " ") + ", " +@Left(@Name([CN]; ComposedBy); " ")

6. (@Middle). This example returns N characters to R from String startingafter Substring.String := @Prompt([OKCANCELEDIT]; "String"; "Enter astring"; "");Substring := @Prompt([OKCANCELEDIT]; "Substring"; "Enter asubstring"; "");Number := @Prompt([OKCANCELEDIT]; "Number of Characters";"Enter the number of characters"; "");N := @TextToNumber(Number);R := @Middle(String; Substring; N); @Prompt([OK]; Number +" characters starting after " + Substring; R)

7. (@ReplaceSubstring). This agent example makes three substitutions inthe textBody field of the affected documents. The third substitution is incase the second substitution causes a sentence to end with two periods.FIELD textBody := @ReplaceSubstring(textBody; "Acme" :"mousetrap" : ".." ; "Acme, Inc." : "mouse detentiondevice" : ".");SELECT @All

8. (@Word). This example extracts word n from string s using a space asthe word separator.s := @Prompt([OKCANCELEDIT]; "String"; "Enter a string ofwords"; "");n := @Prompt([OKCANCELEDIT]; "Word"; "Enter the number ofthe word to extract"; "");

Chapter 4: Formula Language Coding Guidelines 111

ss := @Word(s; " "; @TextToNumber(n)); @Prompt([OK];"Substring"; "Word " + n + " is \"" + ss + "\"")

Trimming, repeating, adding a new line, and changing caseThe following @functions trim strings, repeat characters, add a new line(carriage return), and change case:

Function Description

@Trim(string) Removes leading, trailing, and redundantspaces from a string.

@Trim(list) Removes leading, trailing, and redundantspaces from each element of a string list, andremoves blank elements from the list.

@Repeat(string, number) Repeats a string a number of times.

@NewLine Inserts a new line (carriage return) into a string.

@LowerCase(string) Converts all uppercase characters in a string to lowercase.

@UpperCase(string) Converts all lowercase characters in a string to uppercase.

@ProperCase Converts the first character of each word in astring to uppercase and the remainingcharacters to lowercase.

Examples: Trimming, repeating, adding a new line, and changing case1. (@Trim). This example returns [Now is the time], removing all

extraneous spaces.Untrimmed := " Now is the time ";Trimmed := @Trim(Untrimmed);@Prompt([OK]; "Untrimmed"; "[" + Untrimmed + "]");@Prompt([OK]; "Trimmed"; "[" + Trimmed + "]")

2. (@Trim, @ProperCase). This example converts the words in Name toinitial uppercase characters and deletes leading, trailing, andextraneous spaces. If “ jane j smith” is entered for Name, this formulaconverts it to “Jane J Smith.”@Trim(@ProperCase(Name))

3. (@Repeat). This example returns “Great Month! Great Month! GreatMonth!” in the Comments field if the Sales field is 100,000 or greater.FIELD Comments := @If(Sales >= 100000; @Repeat("GreatMonth! "; 3); Sales >= 50000; "Good Month"; "I want to seeyou in my office");SELECT @All

112 Domino Designer Programming Guide, Volume 1: Formula Language

4. (@NewLine). This example returns the user name and the dateseparated by a new line.@UserName + @NewLine + @Text(@Now)

5. (@LowerCase). This example returns the user name in lowercase.@LowerCase(@UserName)

6. (@UpperCase). This example returns the user name in uppercase.@UpperCase(@UserName)

Performing arithmetic operations

The * / + - operators multiply, divide, add, and subtract. Multiplication anddivision have precedence over addition and subtraction; otherwise,evaluation is left to right. Parentheses can be used to change the order ofevaluation. The following are the arithmetic @functions.

Function Description

@Abs(number) Calculates the absolute (unsigned) value of a number.

@Sign (number) Returns 1 for a positive number, -1 for anegative number, and 0 for zero.

@Sum(num; num; ...) Calculates the sum of numbers and number lists.

@Integer(number) Truncates a number to an integer.

@Integer(numlist) Truncates the elements of a number list to integers.

@Round(number) Rounds a number to the nearest integer.

@Round(number; factor) Rounds a number to the nearest specified factor.

@Round(numlist) Rounds each number in a list to the nearest integer.

@Round(numlist; factor) Rounds each number in a list to the nearestspecified factor.

@Max(number; number) Calculates the larger of two numbers.

@Max(numlist; numlist) In a pairwise list operation, calculates thelarger of two numbers.

@Min(number; number) Calculates the smaller of two numbers.

continued

Chapter 4: Formula Language Coding Guidelines 113

Function Description

@Min(numlist; numlist) In a pairwise list operation, calculates thesmaller of two numbers.

@Modulo(number; number) Calculates the remainder of a numberdivided by a second number.

@Modulo(numlist; numlist) In a pairwise list operation, calculates theremainder of a number divided by a second number.

@Power(base; exp) Calculates the value of a base raised to thepower of an exponent.

@Sqrt (number) Calculates the square root of a number.

@Pi Calculates the value of Pi.

@Log(number) Calculates the common (base 10) logarithmof a number.

@Ln(number) Calculates the natural (base e) logarithm ofa number.

@Exp(number) Calculates e raised to the power of anumber.

@Random Returns a random number in the range 0 to 1, inclusive.

@Sin(angle) Calculates the sine of an angle (in radians).

@Cos(angle) Calculates the cosine of an angle (in radians).

@Tan(angle) Calculates the tangent of an angle (in radians).

@Asin(sine) Calculates the arc (inverse) sine of a sine.

@Acos(cosine) Calculates the arc (inverse) cosine of a cosine.

@Atan(tangent) Calculates the arc (inverse) tangent of a tangent.

@Atan2(x; y) Calculates the arc (inverse) tangent usingthe tangent y/x of an angle.

114 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: Performing arithmetic operations1. (*, precedence). This example prints 15 for the first @Prompt because

the multiplication 4 * 3 is evaluated first. It prints 21 for the second@Prompt because the parentheses force the evaluation of 3 + 4 first.@Prompt([OK]; "3 + 4 * 3"; @Text(3 + 4 * 3));@Prompt([OK]; "(3 + 4) * 3"; @Text((3 + 4) * 3))

2. (/ *). This example prints 0.333333333333333 for the first @Prompt,performing the division and rounding the result to 15 decimal places. Itprints 1.2635268885E+17 for the second @Prompt, presenting the 11most significant digits of the result as a fraction multiplied by 1017.@Prompt([OK]; "1 / 3"; @Text(1 / 3)); @Prompt([OK];"123456789 * 1023456789"; @Text(123456789 * 1023456789))

3. (@Abs). This example calculates the difference between Score1 andScore2 as an unsigned number no matter which is larger.@Abs(Score1 - Score2)

4. (@Abs). This example calculates the absolute difference between Salesand CostOfSales, and formats it in a text field placing parenthesisaround a negative result.GP := @Abs(Sales - CostOfSales); @If(Sales >= CostOfSales;@Text(GP); "(" + @Text(GP) + ")")

5. (@Sign). This agent example displays the Total field. If the field value isnegative, its absolute value is placed in parentheses; if the field value iszero, the word “Zero” is displayed.sign := @Sign(Total);display := @If(sign = 1; @Text(Total); sign = -1; "(" +@Text(@Abs(Total)) + ")"; "Zero");@Prompt([OK]; "Total"; display);SELECT @All

6. (@Sum). This example prints 15, the sum of the list One23, the variableFour, and the constant 5.One23 := 1 : 2 : 3; Four := 4;S := @Sum(One23; Four; 5); @Prompt([OK]; "Sum of 1-5";@Text(S))

7. (@Integer). This example truncates 3.12 to 3 and 6.735 to 6.@Prompt([OK]; "@Integer(3.12)"; @Text(@Integer(3.12)));@Prompt([OK]; "@Integer(6.735)"; @Text(@Integer(6.735)))

8. (@Integer). This example truncates Sales and Commission to integers ina list.@Integer(Sales : Commission)

Chapter 4: Formula Language Coding Guidelines 115

9. (@Round). This example rounds 3.12 to 3, 6.735 to 7, and 7.5 to 8; 753 bytens to 750; and the list elements 3.12, 6.735, and 7.5 to 3, 6, and 7(converting them to a text string for display).@Prompt([OK]; "@Round(3.12)"; @Text(@Round(3.12)));@Prompt([OK]; "@Round(6.735)"; @Text(@Round(6.735)));@Prompt([OK]; "@Round(7.5)"; @Text(@Round(7.5)));@Prompt([OK]; "@Round(753; 10)"; @Text(@Round(753; 10)));@Prompt([OK]; "@Round(3.12 : 6.735 : 7.5)";@Implode(@Text(@Round(3.12 : 6.735 : 7.5))))

10. (@Max). This example prints 3, the maximum of 1 and 3, and 99 6 7 8,the maximum of the pairwise elements in the two lists.@Prompt([OK]; "@Max(1; 3)"; @Text(@Max(1; 3)));@Prompt([OK]; "@Max(99 : 2 : 3; 5 : 6 : 7 : 8)";@Implode(@Text(@Max(99 : 2 : 3; 5 : 6 : 7 : 8))))

11. (@Min). This example prints 1, the minimum of 1 and 3, and 5 2 3 3, the minimum of the pairwise elements in the two lists in the second example.@Prompt([OK]; "@Min(1; 3)"; @Text(@Min(1; 3)));@Prompt([OK]; "@Min(99 : 2 : 3; 5 : 6 : 7 : 8)";@Implode(@Text(@Min(99 : 2 : 3; 5 : 6 : 7 : 8))))

12. (@Modulo). This example prints 1, the remainder of 4/3; -2, theremainder of -14/3 (the remainder is negative when the dividend isnegative); and 1 2 3 3, the remainders of the pairwise division of thefirst list by the second in the third line.@Prompt([OK]; "@Modulo(4; 3)"; @Text(@Modulo(4; 3)));@Prompt([OK]; "@Modulo(-14; 3)"; @Text(@Modulo(-14; 3)));@Prompt([OK]; "@Modulo(4 : 6 : 8 : 9; 3 : 4 : 5 : 6)";@Implode(@Text(@Modulo(4 : 6 : 8 : 9; 3 : 4 : 5 : 6))))

13. (@Modulo). This example determines if the input number is even(division by 2 leaves a remainder of 0) or odd.n := @TextToNumber(@Prompt([OKCANCELEDIT]; "Input Number";"Type a number"; "")); @Prompt([OK]; "The number is ...";@If(@Modulo(n; 2) = 0; "Even"; "Odd"))

14. (@Power). This example prints 8, 2 raised to the power of 3; -8, -2 raisedto the power of 3; and 0.125, 2 raised to the power of -3.@Prompt([OK]; "@Power(2; 3)"; @Text(@Power(2; 3)));@Prompt([OK]; "@Power(-2; 3)"; @Text(@Power(-2; 3)));@Prompt([OK]; "@Power(2; -3)"; @Text(@Power(2; -3)))

116 Domino Designer Programming Guide, Volume 1: Formula Language

15. (@Sqrt, @Power). This example, which is the value formula for acomputed field, calculates the diagonal of a rectangle whose sides arespecified in the Length and Width fields.@If(Length = "" | Width = ""; ""; @Sqrt(@Power(Length; 2)+ @Power(Width; 2)))

16. (@Pi, @Power). This example, which is the value formula for acomputed field, calculates the area of a circle whose radius is specifiedin the Radius field.@If(Radius = ""; ""; @Pi * @Power(Radius; 2))

17. (@Log). This example prints 0.602059991327962, the common logarithmof 4; and 14, the common logarithm of 1014.@Prompt([OK]; "Common log of 4"; @Text(@Log(4)));@Prompt([OK]; "Common log of 1.0E+14";@Text(@Log(1.0E+14)))

18. (@Ln). This example prints 0.693147180559945, the natural logarithm of2.@Prompt([OK]; "Natural log of 2"; @Text(@Ln(2)))

19. (@Exp). This example calculates 2.71828182845904 (the value of e) forthe first @Exp function, 3.49034295746184 (the value of e to the 1.25) forthe second @Exp function, and 0.28650479686019 (the value of e to the-1.25) for the third @Exp function.@Prompt([OK]; "e to 1"; @Text(@Exp(1))); @Prompt([OK]; "eto 1.25"; @Text(@Exp(1.25))); @Prompt([OK]; "e to -1.25";@Text(@Exp(-1.25)))

20. (@Random). This view action example gets a number from a user andcompares it to a random number in the range 1 through 99, inclusive.userNumber := @Prompt([OKCANCELEDIT]; "Number"; "Must be1-99"; "");winningNumber := @Text(@Integer(98 * @Random + 1));@Prompt([OK]; "Result"; @If(userNumber = winningNumber;"YOU WIN"; "Sorry - winning number is " + winningNumber))

21. (@Sin, @Cos). This example shows the formulas for two computedfields. The first formula calculates the length of a rectangle and thesecond formula calculates its width.Diagonal * @Sin(Angle * @Pi / 180)

Diagonal * @Cos(Angle * @Pi / 180)

Chapter 4: Formula Language Coding Guidelines 117

Performing time-date operations

A time-date value consists of a year, month, day, hour, minute, and second.You can use a time-date value “as is” in a time-date field, but must convertit with @Text to use it as a string. You can convert a string to a time-datevalue with @TextToTime.

A time-date constant is a date, a time, or both, in brackets. The date is themonth, day, and year separated by a slash (/) or a hyphen (-) for OS/2.Year is optional and defaults to the current year; a 2-digit year means the20th century if 50 or greater and the 21st century if less than 50.

The time is the hour, minute, and second (optional; defaults to 0) separatedby colons. You can use 24-hour time or add “PM” for afternoon hours. Youcan add the time zone to indicate another time zone. Separate thecomponents with spaces. Some examples of time-date constants are[6/30/97], [5:30:00 PM], [17:30:00], [17:30 EST], and [6/30 5:30 PM].

Dates can be compared and subtracted. Subtraction yields a numeric valuerepresenting seconds.

The following @functions determine and manipulate time-date values.

Function Description

@Created Returns the time-date the document was created.

@Accessed Returns the time-date the document was last accessed.

@Modified Returns the time-date the document was lastedited and saved.

@Now Returns the current time-date.

@Today Returns today’s date.

@Tomorrow Returns tomorrow’s date.

@Yesterday Returns yesterday’s date.

@Weekday(time-date) Returns the day of the week for a time-dateas 1-7 (Sunday through Saturday).

@Day(time-date) Extracts the day of the month from atime-date.

continued

118 Domino Designer Programming Guide, Volume 1: Formula Language

Function Description

@Month(time-date) Extracts the month from a time-date as 1-12.

@Year(time-date) Extracts the year from a time-date.

@Hour(time-date) Extracts the hour from a time-date.

@Minute(time-date) Extracts the minute from a time-date.

@Second(time-date) Extracts the seconds from a time-date.

@Date(y; m; d) Returns the date for year, month, and day.

@Date(y; m; d; h; m; s) Returns the date for year, month, day, hour,minute, and second.

@Date(time-date) Returns the date for a time-date.

@Time(y; m; d) Returns the time for year, month, and day.

@Time(y; m; d; h; m; s) Returns the time for year, month, day, hour,minute, and second.

@Time(time-date) Returns the time for a time-date.

@Adjust(time-date; y; m; d; h; m; s) Adjusts a time-date by the negative orpositive values of the remaining arguments.

@Zone Returns the time zone setting of the current computer.

@Zone Returns the time zone setting for a time-date.

Examples: Performing time-date operations1. (@Created). This agent example writes “Archive” to the Status field if

the current document was created before 1995, and writes “Current”otherwise.SELECT @All;FIELD Status := @If(@Created < [01/01/95 12:00:00 AM];"Archive"; "Current");

2. (@Modified, @Date, @Today, @Yesterday). This agent example writes“Today,” “Yesterday,” or “Old” to the ViewStatus field depending onthe date that the current document was last modified.FIELD ViewStatus := @If(@Date(@Modified) = @Today;"Today"; @Date(@Modified) = @Yesterday; "Yesterday";"Old");SELECT @All

Chapter 4: Formula Language Coding Guidelines 119

3. (@Modified, @Date, @Weekday, @Today, @Adjust, @Yesterday). Thisagent example modifies the preceding example to exclude weekends inassigning “Yesterday.” If today is Monday, y is set to today’s dateminus 3 days; otherwise y is set to yesterday’s date. Then y instead of@Yesterday is tested against the @Modified date.d := @Date(@Modified);y := @If(@Weekday(@Today) = 2; @Adjust(@Today; 0; 0; -3;0; 0; 0); @Yesterday);FIELD ViewStatus := @If(d = @Today; "Today"; d = y;"Yesterday"; "Old");SELECT @All

4. (@Now, @Month, @Year, @Day). This example of a computed text fielddisplays today’s date in letterhead form. For example, 6/30/95 displaysas “June 30, 1995.”months := "January" : "February" : "March" : "April" :"May" : "June" : "July" : "August" : "September" :"October" : "November" : "December";month := @Subset(@Subset(months; @Month(@Now)); -1);year := @Year(@Now);day := @Day (@Now);month + " " + @Text(day) + ", " + @Text(year)

5. (@Adjust, @Weekday, @Created). This example of a computed timefield displays a date two days from the creation date for the document.The calculation eliminates the weekend by adding 4 days if the creationdate is a Friday.increment := @If(@Weekday(@Created) = 6; 4; 2);@Date(@Adjust(@Created; 0; 0; increment; 0; 0; 0))

Accessing the user environment

The user environment is the server or workstation containing the databasefor: replication formulas, agents whose triggers are If New Mail HasArrived or On Schedule, selection formulas, or column formulas.Otherwise, the user environment is the Notes workstation of the userrunning the formula.

User names can be either distinguished or non-distinguished, anddistinguished names can be canonical or abbreviated. Use @Name tochange the form of a user name.

120 Domino Designer Programming Guide, Volume 1: Formula Language

The following @functions return or process information on the userenvironment.

Function Description

@UserName Returns the user name or server name.

@Name([key]; name) Changes the form of a user name. Thekeywords include [CN] to extract thecommon name from a distinguished name, [Abbreviate] to abbreviate adistinguished name in canonical form,[Canonicalize] to do the reverse, and[ToKeyword] to put the name componentsin reverse order separated by backslashes(for categorized views).

@UserRoles For databases on servers, returns a list ofroles for the current user.

@MailDbName Returns the server name and path namefor the user’s mail database. This@function evaluates to a 2-member list.

@OptimizeMailAddress(address) Removes unnecessary domains from an address.

@Platform Returns the platform that the user isrunning on: Macintosh, NetWare, OS2V1,OS2V2, UNIX, Windows/16, orWindows/32.

@Version Returns (as a string) the version of Notesthat is running.

@Password(string) Encodes a string. You cannot determinethe original string from the encoded result.

Examples: Accessing the user environment1. This view selection formula limits the view to documents whose

From_1 field matches the name of the current user. Both From_1 and@UserName are reduced to the common name portion of thehierarchical name to better ensure a match.SELECT @Name([CN]; @UserName) = @Name([CN]; From_1)

2. In this column formula, the @Name function extracts the common namefrom the “From” field.Subject + " (" + @Name([CN]; From) + @DocDescendants(")";", % response)"; ", % responses)")

Chapter 4: Formula Language Coding Guidelines 121

3. This formula displays information about the user environment. Thereturn value from @MailDbName is imploded because it is a 2-elementlist containing server name and path name.@Prompt([OK]; "User name"; @Name([CN]; @UserName));@Prompt([OK]; "Mail database"; @Implode(@MailDbName));@Prompt([OK]; "Platform"; @Platform);@Prompt([OK]; "Notes version"; @Version)

4. This is the formula for the first column in the “By Author” view. Itconverts the From field, which typically contains a distinguished name,to the form last name, comma, first name.AuthorName :=@If(!@IsAvailable(From);"Anonymous";@Name([CN]; From));Name := @Trim(@Word(AuthorName; "("; 1));LastName := @RightBack(Name; " ");FirstName := @LeftBack(Name; " ");CombinedName := LastName + ", " + FirstName;@If(CombinedName = ", "; Name; CombinedName)

5. This is the input validation formula for the “Password” field in a form.The author can see the password as it is being typed, but when thedocument is saved, the password is encoded and cannot be read.@Password(Password)

Accessing the current database and view

You have immediate access to the database in which the formula is running,except for SmartIcon formulas, which have no database context. You haveimmediate access to the view in which the formula is running if you are inthe context of a view. In the context of a document, you have immediateaccess to the view from which the document was opened.

Database and view attributesThe following table lists @functions that return database and viewattributes.

Function Description

@DbManager Returns the users, groups, and servers who currentlyhave manager access to the database. Returns a list.

@DbName Returns the names of the current Notes server anddatabase. Returns a 2-element list.

@ViewTitle Returns the title of the current view.

122 Domino Designer Programming Guide, Volume 1: Formula Language

Window title and column formula @functionsA number of @functions provide response hierarchy and other informationon views. In a view, main documents are numbered 1, 2, 3, and so forth.Each set of response or response-to-response documents have second andthird numbers starting at 1. By default, the complete number for a responsedocument appears as a decimal. For example, the second response to thethird document is document number 3.2 in the view; the first response tothe second response is document number 3.2.1.

These @functions work only in Window Title and Column formulas, andsome, as noted, are restricted to one or the other. The return value in everycase is a string.

Function Description

@Responses Returns the number of responses in the current viewto the current document. WindowTitle formulas only.

@DocLevel Returns the level of the current document in thecurrent view.

@DocSiblings Returns the number of documents that are at thesame level as the current document, including thecurrent document.

@DocNumber Returns the number of the current document orcategory within the current view.

@DocNumber(sep) As above but separates the components of thenumber with sep rather than a period.

@DocNumber(”“) As above but returns only the rightmost componentof the number.

@DocParentNumber Returns the number of the parent of the currentdocument or category within the current view.

@DocParentNumber(sep) As above but separates the components of thenumber with sep rather than a period.

@DocParentNumber(”“) As above but returns only the rightmost componentof the number.

@DocDescendants Returns the number of descendants, includingchildren and children of children, of the currentdocument.

@DocDescendants(def) As above but returns def. Use % in def to represent the number.

@DocDescendants(zero; def) As above but returns zero if there are no descendants.

continued

Chapter 4: Formula Language Coding Guidelines 123

Function Description

@DocDescendants(one, zero; def)

As above but returns one if there is one descendant.

@DocChildren Returns the number of immediate children of thecurrent document.

@DocChildren(def) As above but returns def. Use % in def to represent the number.

@DocChildren(zero; def) As above but returns zero if there are no children.

@DocChildren(one, zero; def) As above but returns one if there is one child.

@IsCategory Returns an asterisk if any field to the right of thecurrent field in the current row is a category.

@IsCategory(true) Same as above but returns true instead of an asterisk.

@IsCategory(true; false) Same as above but returns false if no fields are categories.

@IsExpandable Returns a plus sign if the current row is expandable.

@IsExpandable(true) Same as above but returns true instead of a plus sign.

@IsExpandable(true; false) Same as above but returns false if the row is notexpandable.

Examples: Accessing the current database and view1. This example displays the database title, its server and database name,

and the names of users who have manager access.@Prompt([OK]; "Title"; @DbTitle);@Prompt([OK]; "Server and database";@Trim(@Implode(@DbName)));@Prompt([OK]; "Managers"; @Implode(@DbManager; ", "))

2. This window title formula displays “New Title” for a new document;the Subject field if the view title is “AuthorView”; or the Subject fieldplus the number of response documents otherwise.StandardTitle := Subject + @DocDescendants(" (NoResponses)"; " (1 Response)"; " (% Responses)");@If(@IsNewDoc; "New Topic"; @ViewTitle = "AuthorView";Subject; StandardTitle)

3. This column formula displays the Subject field, the user name, and thenumber of response documents.Subject + " (" + @Name([CN]; From) + @DocDescendants(")";", % response)"; ", % responses)")

124 Domino Designer Programming Guide, Volume 1: Formula Language

Accessing the current document in the formula language

For form actions, buttons, hotspots, and field formulas, the currentdocument is the one that’s open. For view actions, the current document isthe one that’s highlighted (not checked). For agents, the current document isthe one being acted on according to the build selection and SELECTkeyword criteria.

To read from a field in the current document, name the field. Case does notmatter but otherwise the name must be exact.

To write to a field in the current document, you must use the FIELDkeyword or the @SetField function. You cannot simply name the field.

The FIELD keyword is used in an assignment statement and has thefollowing format. If you omit the FIELD keyword, the assigned variableis treated as a temporary variable.FIELD field-name := expression

@SetField writes to a field and has the same effect as an assignmentstatement using the FIELD keyword. @SetField can be nested in anotherstatement; you cannot do this with the FIELD keyword. The field nameis expressed as a text value, so it can be a variable as well as being theexact name in parentheses. One restriction is that @SetField works onlyon an existing field; if the field you want to write to does not exist in thedocument, “declare” it at the beginning of the formula by using it in aFIELD assignment. @SetField has the following format.@SetField( field-expression-name; expression )

The DEFAULT keyword provides a value in the event that a field is not inthe document. If the field is available, its value is used. If the field isunavailable, the DEFAULT value is used.

DEFAULT field-name := expression

The @MailSend function mails a document. @MailSend without argumentsmails the current document, which must contain a field named SendTocontaining the recipients. @MailSend with arguments constructs thedocument to be mailed from the arguments.

@MailSend

@MailSend( to; cc; bcc; subject; body; fields; flags )

The @DeleteField function deletes a field. You specify it as the expression ina FIELD assignment.

FIELD field-name := @DeleteField

Chapter 4: Formula Language Coding Guidelines 125

The @DocMark([NoUpdate]) function prevents formula changes to thedocument from being written to storage. The document is the same afterprocessing by the formula as before. This @function only affects agents.

This table lists @functions that return document and field attributes.

Function Description

@DocumentUniqueID Returns the document’s unique ID, which is uniqueacross all replicas of the document; in a field,creates a doclink to the current document.

@InheritedDocumentUniqueID

Returns the unique ID of the document’s parent; ina field, creates a doclink to the current document.

@NoteID Returns ”NT“ followed by the note ID of thedocument.

@DocLength Returns the size in bytes of the document.

@Author Returns the abbreviated names of all authors.

@DocFields Returns the names of all the fields in the document.

@IsAvailable(field) Returns true (1) if a field exists in the document.

@IsUnavailable(field) Returns true (1) if a field does not exist in thedocument.

@Attachments Returns the number of attached files.

@AttachmentNames Returns the file names of all attached files.

@AttachmentLengths Returns the size in bytes of each attachment.

@Responses Returns the number of responses to the currentdocument in the current view.

@AllChildren Selects immediate responses to matcheddocuments; use only in a selection formula.

@AllDescendants Selects all responses to matched documents; useonly in a selection formula.

@IsResponseDoc Returns true (1) if the document is a response.

@IsNewDoc Returns true (1) if the document is not yet saved.

@IsDocBeingEdited Returns true (1) if the document is in edit mode.

@IsDocBeingLoaded Returns true (1) if the document is being loaded.

@IsDocBeingSaved Returns true (1) if the document is being saved.

@IsDocBeingMailed Returns true (1) if the document is being mailed.

@IsDocBeingRecalculated Returns true (1) if the document is beingrecalculated.

126 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: Accessing the current document1. This example of a computed field value performs an arithmetic

operation involving two other fields in the document. These fields mustexist in the document, must be numeric, and must be initialized to anumeric value.TotalSales - CostOfSales

2. This agent example performs an arithmetic operation on two fields inthe current document, and assigns the result to a third field. The tworeferenced fields must exist; GrossSales can be new.FIELD GrossSales := TotalSales - CostOfSales;SELECT @All

3. This agent example performs an arithmetic operation on two fields inthe current document, and either assigns the value to a third field orsends a mail message. The first statement initializes GrossSales and isnot necessary if you are certain the field already exists.FIELD GrossSales := 0;gs := TotalSales - CostOfSales;@If(gs > 0; @SetField("GrossSales"; gs); @MailSend("IanPerron"; ""; ""; "No gross sales"; "Gross sales are zeroor less for "; Subject));SELECT @All

4. This column formula example evaluates to the value of KeyThought fordocuments that contain that field. If a document does not contain aKeyThought field, it “defaults” to the value of Topic.DEFAULT KeyThought := Topic;KeyThought

5. This is another way of coding the above example.@If(@IsAvailable(KeyThought); KeyThought; Topic)

6. This agent example deletes the GrossSales field.@If (@IsUnavailable(GrossSales); @Return(""); "");FIELD GrossSales := @DeleteField;SELECT @All

7. This agent example calculates the GrossSales field, then displays theresult and does not mark the document for update. As a result, nochange takes place in the document in storage. The changes are saved if@DocMark is omitted or “@DocMark([Update])” is specified.FIELD GrossSales := TotalSales - CostOfSales;@Prompt([OK]; "Gross sales for " + Subject;@Text(GrossSales));

Chapter 4: Formula Language Coding Guidelines 127

@DocMark([NoUpdate]);SELECT @All

8. This example displays all the fields in the current document.@Prompt([OKCANCELLIST]; "Fields"; "Fields in document";""; @DocFields);SELECT @All

9. This window title formula displays “New Document” for a newdocument. For an existing document, the formula displays the Subjectfield and the number of responses.@If(@IsNewDoc; "New Document"; Subject + " with " +@Text(@Responses) + " response(s)")

10. This view selection formula selects all documents except those whoseForm field contains “Profile” or “Log.”SELECT !@Contains(Form; "Profile" : "Log")

11. This view selection formula selects all documents whose Subject fieldcontains “acme” in any case, plus all their descendants.SELECT @Contains(@LowerCase(Subject); "acme") |@AllDescendants

12. This form action formula displays the names and lengths of allattachments in a document, or “No attachments” if the document hasno attachments.@If(@Attachments > 0; @Prompt([OKCANCELLIST];"Attachments"; "Attachment names and lengths"; "";@AttachmentNames + " (" + @Text(@AttachmentLengths) + "bytes)"); @Prompt([OK]; "Attachments"; "No attachments"))

Accessing data outside the current document and database

The following @functions get data values from a specified database. Youcannot set values with these @functions.

@DbLookup looks up a specified value in the first sorted column of aspecified view in a specified database. For each document that matchesthe search value, @DbLookup returns the value of a specified field onthe document or column in the view.

@DbColumn returns all the values in a specified column in a specifiedview in a specified database.

128 Domino Designer Programming Guide, Volume 1: Formula Language

The first three arguments are the same for both functions:

[NOTES] : [NOCACHE] specifies that the operation is on a Notesdatabase and is not cached. You can specify “” for the first list elementbecause [NOTES] is the default. If the data is stable and/or you areaccessing the database many times, you can specify the second listelement as “” to not use a cache. You can specify the entire argument as“” to mean a Notes database and no cache.

server : database specifies the server and database you are accessing.Specify the first list element as “” to mean the local Notes directory.Specify the entire argument as “” to mean the current database. You canspecify the entire argument as the replica ID of a database. Notes willsearch locally and on servers, and use the first replica it finds. Get thereplica ID from File - Database - Design Synopsis, Replication.

view specifies the view through which to access the database.

For @DbLookup, the fourth argument is the key, the value to search for inthe first sorted column in the view. @DbLookup finds every document thatmatches the key value.

For @DbLookup, the fifth argument is either the name of a field in thedatabase or the number of a column in the view. @DbLookup returns a listof the values in the fields or columns of the found documents.

For @DbColumn, the fourth argument is the number of a column.@DbColumn returns a list of all values in the column.

The following @functions get and set field values in another document inthe current database. However, you must know the unique ID of thedocument.

@GetDocField(unid; fieldName) gets the value of a field given its unique ID.

@SetDocField(unid; fieldName; value) sets the value of a field given itsunique ID.

These functions are suited to accessing and setting values in the parent of aresponse document, since the parent’s unique ID is in the $Ref field of thechild. In documents that have “Formulas inherit values from selecteddocument” set, you can use @InheritedDocumentUniqueID as the formulain a hidden field in the base document, then use that field name as theformula in a hidden field in the inherited document. Otherwise you mustdevise a scheme for storing and retrieving the unique IDs of the documentsyou want to access.

Chapter 4: Formula Language Coding Guidelines 129

Examples: Accessing data outside the current document and database1. This example looks up a person name in the People view of the local

Address Book (NAMES.NSF) and gets the office phone number in thedocument containing that name.inputName := @Prompt([OKCANCELEDIT]; "User name"; "Enteruser name as FIRST LAST"; "");adjName := @Right(inputName; " ") + " , " +@Left(inputName; " ");phoneNumber := @DbLookup("Notes" : "NoCache"; "" :"NAMES"; "People"; adjName; "OfficePhoneNumber");@Prompt([OK]; "Office phone number"; inputName + "'soffice phone is " + phoneNumber)

2. This example is the same as the first with two exceptions. The replica IDof an Address Book database is used instead of a specific name. Noteswill search for the replica locally then on servers and use the firstdatabase it finds with that replica. The last argument to @DbLookup iscolumn 2 instead of the OfficePhoneNumber. Effectively this is thesame because column 2 contains the phone number.inputName := @Prompt([OKCANCELEDIT]; "User name"; "Enteruser name as FIRST LAST"; "");adjName := @Right(inputName; " ") + " , " +@Left(inputName; " ");phoneNumber := @DbLookup("Notes" : "NoCache";"85255AD6:006AE971"; "People"; adjName; 2);@Prompt([OK]; "Office phone number"; inputName + "\'soffice phone is " + phoneNumber)

3. This example looks up the member names for a group in the Groupsview of the local Address Book.groupName := @Prompt([OKCANCELEDIT]; "Group name"; "Entergroup name"; "");members := @DbLookup("Notes" : "NoCache"; "" : "NAMES";"Groups"; groupName; "Members");@Prompt([OKCANCELLIST]; "Group members"; "Members of " +groupName; ""; members)

4. This example gets the associated person name in the local AddressBook, given an office phone number. It is designed to work where onenumber serves exactly one person. Since the database does not have aview sorted by phone number, the example uses @DbColumn to get allphone numbers (column 2) and all persons (column 1), then finds theperson that corresponds to the number.phone := @Prompt([OKCANCELEDIT]; "Phone number"; "Enterphone number"; "");phoneList := @DbColumn("Notes" : "NoCache"; "" : "NAMES";"People"; 2);

130 Domino Designer Programming Guide, Volume 1: Formula Language

nameList := @DbColumn("Notes" : "NoCache"; "" : "NAMES";"People"; 1);position := @Member(phone; phoneList);@If(position = 0; @Do(@Prompt([OK]; "Not listed"; "Nolisting for " + phone); @Return(" " )); "");name := @Subset(@Subset(nameList; position); -1);nameAdj := @Right(name; " ") + " " + @Left(name; ",");@Prompt([OK]; "Phone number " + phone; nameAdj)

Accessing external databases through ODBC using @functions

The following @functions access an external database through ODBC andreturn a value or list of values:

@DbColumn returns all the values in one column of a table, or all thedistinct values.

@DbLookup returns selected values in one column of a table bymatching keys.

@DbCommand passes a command to an external DBMS and returns theresult.

@DbColumn and @DbLookup can only retrieve data. They can’t add,delete, or modify data, or perform other operations. @DbCommand canretrieve data or send other SQL statements that can change data.LotusScript provides a wider range of capabilities including the ability toupdate the external database.

The first four parameters are the same for all three @functions and establishaccess to the database through ODBC. The parameters are:

“ODBC” as a string constant; or “ODBC” : “NoCache”

Name of the data source as defined in the table of data sources(ODBC.INI in Windows)

User ID, list of two user IDs, or a null string, depending on the externaldata source

Password, list of two passwords, or a null string, depending on theexternal data source

(@DbColumn and @DbLookup) Name of the table to be accessed

(@DbCommand) Command string to be executed

(@DbColumn and @DbLookup) Name of the column to be accessed

Option for handling null data returned by the data source

(@DbLookup) Name of the column containing the key

Chapter 4: Formula Language Coding Guidelines 131

(@DbLookup) Value of the key as the appropriate data type, or a list

(@DbColumn and @DbLookup) List of two elements: “Distinct” as akeyword or null string; “Ascending” or “Descending” as a keyword

Where user IDs and passwords are required, you can specify null stringsand let the user supply them when the @function executes.

Examples: Accessing external databases through ODBC using@functions1. This formula gets the PARTNO column of the MANUALS table.

@DbColumn("ODBC";"Oracle";"";"";"MANUALS";"PARTNO";"":"Ascending")

2. This formula gets the TITLE from the row of the MANUALS tablewhere PARTNO is 17-895A.@DbLookup("ODBC";"Oracle";"";"";"MANUALS";"TITLE";"PARTNO";"17-895A")

3. This formula gets the PARTNO column value for every row of theMANUALS table where the numeric value in the ONHAND column isless than 100.@DbCommand("ODBC";"Oracle";"";"";"SELECT PARTNO FROMMANUALS WHERE ONHAND <100")

132 Domino Designer Programming Guide, Volume 1: Formula Language

Chapter 5Formula Language @Functions A–Z

This chapter lists all the @functions in alphabetical order.

Where does this @function work? (Part 1 A –D)The following table lists each @function (A–D) and indicates whether or notthe @function works in the following contexts:

SmartIcons formula

Button formula

Selection formula

Column formula

Agent (run manually from menu)

Agent (run when documents are mailed, pasted, or modified)

Agent (run on schedule)

Hide-when formula

Section editor formula

For a listing of the other @functions in Part 1, see the following:

“Where does this @function work? (Part 1 E–K)”

“Where does this @function work? (Part 1 L–R)”

“Where does this @function work? (Part 1 S–Z)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 2).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

133

Smart-Icons

Button Selection Column Agentmanual

Agentmailpaste

modify

Agentscheduled

Hide-when

Sectioneditor

@Abs X X X X X X X X X

@Abstract X X X X X

@Accessed X X X X X X X X

@Acos X X X X X X X X X

@Adjust X X X X X X X X X

@All X X X X X X X X X

@AllChildren X

@AllDescendants X

@Ascii X X X X X X X X X

@Asin X X X X X X X X X

@Atan X X X X X X X X X

@Atan2 X X X X X X X X X

@AttachmentLengths X X X X X X X X X

@AttachmentNames X X X X X X X X

@Attachments X X X X X X X X X

@Author X X X X X X X X X

@Begins X X X X X X X X X

@Certificate X

@CheckAlarms X X X X X X

@Char X X X X X X X X X

@ClientType X X X X X X

@Command X X X X

@Contains X X X X X X X X X

@Cos X X X X X X X X X

@Created X X X X X X X X X

@Date X X X X X X X X X

@Day X X X X X X X X X

continued

134 Domino Designer Programming Guide, Volume 1: Formula Language

Smart-Icons

Button Selection Column Agentmanual

Agentmailpaste

modify

Agentscheduled

Hide-when

Sectioneditor

@DbColumn (Notes databases)

X X X X X X X

@DbColumn (ODBC) X X X X X

@DbCommand (ODBC)

X X X X X X X

@DbExists X X X X X X

@DbLookup (Notes databases)

X X X X X X X

@DbLookup (ODBC) X X X X X

@DbManager X X X X X X X

@DbName X X X X X X X X X

@DbTitle X X X X X X X X X

@DDEExecute etal. X X X X X X X

@DDEInitiate X X X X X

@DDEPoke X X X X X

@DDETerminate X X X X X

DEFAULT X X X X X X X X X

@DeleteDocument X X X

@DeleteField X X X X X X X

@DialogBox X X X X X X

@Do X X X X X X X

@DocChildren X

@DocDescendants X

@DocFields X X X X X X X

@DocLength X X X X X X X X X

@DocLevel X

@DocMark X X X

@DocNumber X

@DocParentNumber X

continued

Chapter 5: Formula Language @Functions A–Z 135

Smart-Icons

Button Selection Column Agentmanual

Agentmailpaste

modify

Agentscheduled

Hide-when

Sectioneditor

@DocSiblings X

@DocumentUniqueID X X X X X X X X X

@Domain X X X X X X X X X

Where does this @function work? (Part 1 E –K)The following table lists each @function (E–K) and indicates whether or notthe @function works in the following contexts:

SmartIcons formula

Button formula

Selection formula

Column formula

Agent (run manually from menu)

Agent (run when documents are mailed, pasted, or modified)

Agent (run on schedule)

Hide-when formula

Section editor formula

For a listing of the other @functions in Part 1, see the following:

“Where does this @function work? (Part 1 A–D)”

“Where does this @function work? (Part 1 L–R)”

“Where does this @function work? (Part 1 S–Z)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 2).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

136 Domino Designer Programming Guide, Volume 1: Formula Language

Smart-Icons

Button Selection Column Agentmanual

Agentmailpaste

modify

Agentscheduled

Hide-when

Sectioneditor

@EditECL X X X X X

@EditUserECL X X X X X

@Elements X X X X X X X X X

@EnableAlarms X X X X X

@Ends X X X X X X X X X

@Environment X X X X X X X

ENVIRONMENT X X X X X X

@Error X X X X X X X X X

@Exp X X X X X X X X X

@Explode X X X X X X X X X

@Failure X X X

@False X X X X X X X X X

FIELD X X X X X X

@GetDocField X X X X X X X

@GetPortsList X X X X X X X X X

@GetProfileField X X X X X

@Hour X X X X X X X X X

@If X X X X X X X X X

@Implode X X X X X X X X X

@InheritedDocument UniqueID

X X X X X X X X X

@Integer X X X X X X X X X

@IsAgentEnabled X X X X X X X

@IsAvailable X X X X X X X X X

@IsCategory X

@IsDocBeingEdited X X X X

@IsDocBeingLoaded X

@IsDocBeingMailed X X X X

continued

Chapter 5: Formula Language @Functions A–Z 137

Smart-Icons

Button Selection Column Agentmanual

Agentmailpaste

modify

Agentscheduled

Hide-when

Sectioneditor

@IsDocBeing Recalculated

X X X X

@IsDocBeingSaved X X X X

@IsDocTruncated X X X X X X X X X

@IsError X X X X X X X X X

@IsExpandable X

@IsMember X X X X X X X X X

@IsModalHelp X X X X X X X X X

@IsNewDoc X X X X

@IsNotMember X X X X X X X X X

@IsNumber X X X X X X X X X

@IsResponseDoc X X X X X X X X X

@IsText X X X X X X X X X

@IsTime X X X X X X X X X

@IsUnavailable X X X X X X X X X

@IsValid X X X X X

@Keywords X X X X X X X X X

Where does this @function work? (Part 1 L –R)The following table lists each @function (L–R) and indicates whether or notthe @function works in the following contexts:

SmartIcons formula

Button formula

Selection formula

Column formula

Agent (run manually from menu)

Agent (run when documents are mailed, pasted, or modified)

Agent (run on schedule)

138 Domino Designer Programming Guide, Volume 1: Formula Language

Hide-when formula

Section editor formula

For a listing of the other @functions in Part 1, see the following:

“Where does this @function work? (Part 1 A–D)”

“Where does this @function work? (Part 1 E–K)”

“Where does this @function work? (Part 1 S–Z)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 2).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

Smart-Icons

Button Selection Column Agentmanual

Agentmail paste

modify

Agentscheduled

Hide-when

Sectioneditor

@Left X X X X X X X X X

@LeftBack X X X X X X X X X

@Length X X X X X X X X X

@Like X X X X X X X X X

@Ln X X X X X X X X X

@Log X X X X X X X X X

@LowerCase X X X X X X X X X

@MailDbName X X X X X X X X X

@MailEncryptSaved Preference

X X X X X X X

@MailEncryptSent Preference

X X X X X X X

@MailSavePreference X X X X X X X

@MailSend X X X X X X

@MailSignPreference X X X X X X X

@Matches X X X X X X X X X

continued

Chapter 5: Formula Language @Functions A–Z 139

Smart-Icons

Button Selection Column Agentmanual

Agentmail paste

modify

Agentscheduled

Hide-when

Sectioneditor

@Max X X X X X X X X X

@Member X X X X X X X X X

@Middle X X X X X X X X X

@MiddleBack X X X X X X X X X

@Min X X X X X X X X X

@Minute X X X X X X X X X

@Modified X X X X X X X X

@Modulo X X X X X X X X X

@Month X X X X X X X X X

@Name X X X X X X X X X

@NewLine X X X X X X

@No X X X X X X X X X

@NoteID X X X X X X X X X

@Now X X X X X X X X X

@OptimizeMail Address

X X X X X X X

@Password X X X X X X X X X

@Pi X X X X X X X X X

@PickList X X X X X

@Platform X X X X X X X X X

@PostedCommand X X X X

@Power X X X X X X X X X

@Prompt X X X X* X

@ProperCase X X X X X X X X X

@Random X X X X X X X X X

REM X X X X X X X X X

@RefreshECL X X X X X

@Repeat X X X X X X X X X

@Replace X X X X X X X X X

continued

140 Domino Designer Programming Guide, Volume 1: Formula Language

Smart-Icons

Button Selection Column Agentmanual

Agentmail paste

modify

Agentscheduled

Hide-when

Sectioneditor

@ReplaceSubstring X X X X X X X X X

@Return X X X X X X X X X

@Right X X X X X X X X X

@RightBack X X X X X X X X X

@Round X X X X X X X X X

Where does this @function work? (Part 1 S –Z)The following table lists each @function (S–Z) and indicates whether or notthe @function works in the following contexts:

SmartIcons formula

Button formula

Selection formula

Column formula

Agent (run manually from menu)

Agent (run when documents are mailed, pasted, or modified)

Agent (run on schedule)

Hide-when formula

Section editor formula

For a listing of the other @functions in Part 1, see the following:

“Where does this @function work? (Part 1 A–D)”

“Where does this @function work? (Part 1 E–K)”

“Where does this @function work? (Part 1 L–R)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 2).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

Chapter 5: Formula Language @Functions A–Z 141

Smart-Icons

Button Selection Column Agentmanual

Agentmail paste

modify

Agentscheduled

Hide-when

Sectioneditor

@Second X X X X X X X X X

@Select X X X X X X X X X

SELECT X X X X

@Set X X X X X X X X X

@SetDocField X X X X X X X

@SetEnvironment X X X X X X X

@SetField X X X X X X

@Sign X X X X X X X X X

@Sin X X X X X X X X X

@Soundex X

@Sqrt X X X X X X X X X

@Subset X X X X X X X X X

@Success X X X

@Sum X X X X X X X X X

@Tan X X X X X X X X X

@Text X X X X X X X X X

@TextToNumber X X X X X X X X X

@TextToTime X X X X X X X X X

@Time X X X X X X X X X

@Today X X X X X X X X X

@Tomorrow X X X X X X X X X

@Trim X X X X X X X X X

@True X X X X X X X X X

@Unavailable X X X X X X

@Unique X X X X X X X X X

@UpperCase X X X X X X X X X

@URLGetHeader X X X X X

@URLHistory X X X X

@URLOpen X X X X X

continued

142 Domino Designer Programming Guide, Volume 1: Formula Language

Smart-Icons

Button Selection Column Agentmanual

Agentmail paste

modify

Agentscheduled

Hide-when

Sectioneditor

@UserAccess X X X X* X X

@UserName X X X X X X X X X

@UserPrivileges X X X X X X X X

@UserRoles X X X X X X X

@V2If X X X X X X X X X

@V3UserName X X X X X X X X X

@Version X X X X X X X X X

@ViewTitle X X X X

@Weekday X X X X X X X X X

@Word X X X X X X X X X

@Year X X X X X X X X X

@Yes X X X X X X X X X

@Yesterday X X X X X X X X X

@Zone X X X X X X X X X

Where does this @function work? (Part 2 A –D)The following table lists each @function (A–D) and indicates whether or notthe @function works in the following contexts:

Window title formula

Hotspot formula (action)

Hotspot formula (text popup)

Field formula

Form action formula

View action formula

Navigator

Layout region

For a listing of the other @functions in Part 2, see the following:

“Where does this @function work? (Part 2 E–K)”

“Where does this @function work? (Part 2 L–R)”

Chapter 5: Formula Language @Functions A–Z 143

“Where does this @function work? (Part 2 S–Z)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 1).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Abs X X X X X X X X X

@Abstract X X X X X X X

@Accessed X X X X X X X X

@Acos X X X X X X X X X

@Adjust X X X X X X X X X

@All X X X X X X X X X

@Ascii X X X X X X X X X

@Asin X X X X X X X X X

@Atan X X X X X X X X X

@Atan2 X X X X X X X X X

@AttachmentLengths X X X X X X X X

@AttachmentNames X X X X X X X X

@Attachments X X X X X X X X

@Author X X X X X X X X

@Begins X X X X X X X X X

@Certificate X

@Char X X X X X X X X X

@CheckAlarms X X X X X

@ClientType X X X X X X X X

@Command X X X X X X

@Contains X X X X X X X X X

continued

144 Domino Designer Programming Guide, Volume 1: Formula Language

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Cos X X X X X X X X X

@Created X X X X X X X X

@Date X X X X X X X X X

@Day X X X X X X X X X

@DbColumn (Notes databases)

X X X* X X X X X X

@DbColumn (ODBC) X X X X X X X X

@DbCommand (ODBC)

X X X X X X X X

@DbExists X X X X X X X X

@DbLookup (Notes databases)

X X X* X X X X X X

@DbLookup (ODBC) X X X X X X X X

@DbManager X X X X X X X X X

@DbName X X X X X X X X X

@DbTitle X X X X X X X X X

@DDEExecute etal. X X X X X X X X

@DDEInitiate X X X X X X

DEFAULT X X X X X X X X X

@DeleteField X X X X X X

@DialogBox X X X X X X X X X

@Do X X X X X X X X X

@DocChildren X

@DocDescendants X

@DocFields X X X X X X X X

@DocLength X X X X X X X X

@DocLevel X

@DocNumber X

@DocParentNumber X

@DocSiblings X

continued

Chapter 5: Formula Language @Functions A–Z 145

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@DocumentUniqueID X X X X X X X X

@Domain X X X X X X X X

Where does this @function work? (Part 2 E –K)The following table lists each @function (E–K) and indicates whether or notthe @function works in the following contexts:

Window title formula

Hotspot formula (action)

Hotspot formula (text popup)

Field formula

Form action formula

View action formula

Navigator

Layout region

For a listing of the other @functions in Part 2, see the following:

“Where does this @function work? (Part 2 A–D)”

“Where does this @function work? (Part 2 L–R)”

“Where does this @function work? (Part 2 S–Z)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 1).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

146 Domino Designer Programming Guide, Volume 1: Formula Language

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@EditECL X X X

@EditUserECL X X X

@Elements X X X X X X X X X

@Ends X X X X X X X X X

@Environment X X X* X X X X X

ENVIRONMENT X X X* X X X X X

@Error X X X X X X X X X

@Exp X X X X X X X X X

@Explode X X X X X X X X X

@Failure X

@False X X X X X X X X X

FIELD X X X X X X

@GetDocField X X X X X X X

@GetPortsList X X X X X X X X X

@GetProfileField X X X

@Hour X X X X X X X X X

@If X X X X X X X X X

@Implode X X X X X X X X X

@InheritedDocument UniqueID

X X X X X X X X

@Integer X X X X X X X X X

@IsAgentEnabled X X X X X X X X X

@IsAvailable X X X X X X X X

@IsDocBeingEdited X X X X X X

@IsDocBeingLoaded X X X

@IsDocBeingMailed X X X X X

@IsDocBeingRecalculated X X X X X

@IsDocBeingSaved X X X X X

@IsDocTruncated X X X X X X X X

@IsError X X X X X X X X

continued

Chapter 5: Formula Language @Functions A–Z 147

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@IsMember X X X X X X X X X

@IsModalHelp X X X X X X X X X

@IsNewDoc X X X X X X X

@IsNotMember X X X X X X X X X

@IsNumber X X X X X X X X X

@IsResponseDoc X X X X X X X X

@IsText X X X X X X X X X

@IsTime X X X X X X X X X

@IsUnavailable X X X X X X X X

@IsValid X X X X X X X X

@Keywords X X X X X X X X X

Where does this @function work? (Part 2 L –R)The following table lists each @function (L–R) and indicates whether or notthe @function works in the following contexts:

Window title formula

Hotspot formula (action)

Hotspot formula (text popup)

Field formula

Form action formula

View action formula

Navigator

Layout region

For a listing of the other @functions in Part 2, see the following:

“Where does this @function work? (Part 2 A–D)”

“Where does this @function work? (Part 2 E–K)”

“Where does this @function work? (Part 2 S–Z)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 1).”

148 Domino Designer Programming Guide, Volume 1: Formula Language

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

Windowtitle

Hotspotaction

Hotspottext

popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Left X X X X X X X X X

@LeftBack X X X X X X X X X

@Length X X X X X X X X X

@Like X X X X X X X X X

@Ln X X X X X X X X X

@Log X X X X X X X X X

@LowerCase X X X X X X X X X

@MailDbName X X X X X X X X X

@MailEncryptSaved Preference

X X X X X X X X X

@MailEncryptSent Preference

X X X X X X X X X

@MailSavePreference X X X X X X X X X

@MailSend X X X X X X X

@MailSignPreference X X X X X X X X X

@Matches X X X X X X X X X

@Max X X X X X X X X X

@Member X X X X X X X X X

@Middle X X X X X X X X X

@MiddleBack X X X X X X X X X

@Min X X X X X X X X X

@Minute X X X X X X X X X

@Modified X X X X X X X X

@Modulo X X X X X X X X X

continued

Chapter 5: Formula Language @Functions A–Z 149

Windowtitle

Hotspotaction

Hotspottext

popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Month X X X X X X X X X

@Name X X X X X X X X X

@NewLine X X X X X X

@No X X X X X X X X X

@NoteID X X X X X X X

@Now X X X X X X X X X

@OptimizeMail Address

X X X X X X X

@Password X X X X X X X X X

@Pi X X X X X X X X X

@PickList X X X X X X

@Platform X X X X X X X X X

@PostedCommand X X X X X

@Power X X X X X X X X X

@Prompt X X X X X X X X

@ProperCase X X X X X X X X X

@Random X X X X X X X X X

@RefreshECL X X X

REM X X X X X X X X X

@Repeat X X X X X X X X X

@Replace X X X X X X X X X

@ReplaceSubstring X X X X X X X X X

@Responses X

@Return X X X X X X X X X

@Right X X X X X X X X X

@RightBack X X X X X X X X X

@Round X X X X X X X X X

150 Domino Designer Programming Guide, Volume 1: Formula Language

Where does this @function work? (Part 2 S –Z)The following table lists each @function (S–Z) and indicates whether or notthe @function works in the following contexts:

Window title formula

Hotspot formula (action)

Hotspot formula (text popup)

Field formula

Form action formula

View action formula

Navigator

Layout region

For a listing of the other @functions in Part 2, see the following:

“Where does this @function work? (Part 2 A–D)”

“Where does this @function work? (Part 2 E–K)”

“Where does this @function work? (Part 2 L–R)”

If you need to know whether an @function works in a different context, see“Where does this @function work? (Part 1).”

An X indicates that the @function works in that context. A blank cellindicates that the @function does not work in that context. An asteriskindicates that there is a caveat associated with using an @function in aparticular context.

Note that some @functions return different values when the formula runson a server.

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Second X X X X X X X X X

@Select X X X X X X X X X

SELECT X

@Set X X X X X X X X X

@SetDocField X X X X X X X

@SetEnvironment X X X X X X X X

@SetField X X X X X

continued

Chapter 5: Formula Language @Functions A–Z 151

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Sign X X X X X X X X X

@Sin X X X X X X X X X

@Sqrt X X X X X X X X X

@Subset X X X X X X X X X

@Success X

@Sum X X X X X X X X X

@Tan X X X X X X X X X

@Text X X X X X X X X X

@TextToNumber X X X X X X X X X

@TextToTime X X X X X X X X X

@Time X X X X X X X X X

@Today X X X X X X X X X

@Tomorrow X X X X X X X X X

@Trim X X X X X X X X X

@True X X X X X X X X X

@Unavailable X X X X X X

@Unique X X X X X X X X X

@UpperCase X X X X X X X X X

@URLGetHeader X X X X X X

@URLHistory X X X X X X

@URLOpen X X X X X X

@UserAccess X X X X X X X X

@UserName X X X X X X X X X

@UserPrivileges X X X X X X X X X

@UserRoles X X X X X X X X X

@V2If X X X X X X X X X

@V3UserName X X X X X X X X X

@Version X X X X X X X X X

@ViewTitle X X X X X X

continued

152 Domino Designer Programming Guide, Volume 1: Formula Language

Windowtitle

Hotspotaction

Hotspottext popup

Field Form Formaction

Viewaction

Navigator Layoutregion

@Weekday X X X X X X X X X

@Word X X X X X X X X X

@Year X X X X X X X X X

@Yes X X X X X X X X X

@Yesterday X X X X X X X X X

@Zone X X X X X X X X X

@Functions with ECL security

The following table lists the @functions affected by an execute control list(ECL). Those @functions do not execute on the workstation unless themarked ECL privileges are granted to the formula’s signer.

The ECL flags listed in the table are:

Access to current database (cur)

Access to environment variables (env)

Access to non-Notes databases (db)

Access to external programs (prog)

Ability to send mail (mail)

Access to Workstation Security ECL (ecl)

cur env db prog mail ecl

@DbColumn X

@DbCommand X

@DbLookup X

@DDEExecute X

@DDEInitiate X

@DDEPoke X

@DDETerminate X

@DeleteDocument X

@DeleteField X

@EditECL X

continued

Chapter 5: Formula Language @Functions A–Z 153

cur env db prog mail ecl

@EditUserECL X

ENVIRONMENT X

@Environment X

@GetDocField X

@GetProfileField X

@MailSend X

@RefreshECL X

@SetDocField X

@SetEnvironment X

@SetProfileField X

@Unavailable X

@URLGetHeader X

@URLOpen X

@Abs

Returns the absolute (unsigned) value of a number.

Syntax@Abs( anyNumber )

ParameteranyNumber

Number. Any number valid in Notes, whether positive or negative,whole or fractional, integer or real.

Return valueabsoluteValue

Number. The absolute value of anyNumber.

Examples: @Abs1. This example returns 2.16.

@Abs(-2.16)

2. This example returns 2.16 if the number in the field named Net is either2.16 or -2.16.@Abs(Net)

154 Domino Designer Programming Guide, Volume 1: Formula Language

3. This example returns 25 if Score1 = 50 and Score2 = 75, or if Score1 = 75and Score2 = 50.@Abs(Score1 - Score2)

4. This formula, for a computed number field called numDays, uses @Absto calculate the number of days between two dates, which are stored intime fields dateA and dateB. @Integer(dateA-dateB) returns the numberof seconds between dateA and dateB, so the formula divides by60*60*24 to get days. For example, if dateA is 08/11/95 and dateB is09/22/95, the formula returns: 42.@If( numDays = ""; 0; @Abs( @Integer( dateA - dateB ) /(60 * 60 * 24 ) ) )

@AbstractAbbreviates the contents of one or more fields by:

Selecting the most significant parts of the text

Abbreviating common words

Dropping vowels from words

Removing unnecessary text, such as mail headers or white space

This function only works with single-byte character sets.

Syntax@Abstract([commands] ; size ; beginText ; “bodyFields ” )

Parameters[commands]

Any number of commands that tell Notes how you want to abbreviateand sort the text (see list below). Commands are executed in the orderin which you list them. Enclose each command in brackets and separatemultiple commands with colons:[DropVowels]:[NoTrimWhite]:[Abbreviate]

size

Number. The maximum size of the abstracted text. Can be no largerthan 64,994 bytes. The number of bytes available for the abstracted textis size - 1; one byte is reserved for internal use.

beginText

Text. A comment to insert at the beginning of the returned text, nolarger than 10 characters. The size of beginText counts toward the total

Chapter 5: Formula Language @Functions A–Z 155

size of the abstracted text, but its contents are unaffected by @Abstractcommands. Specify an empty string (“”) if you do not want a comment.

“bodyFields”

Text or text list. Any number of fields containing the text to abstract.May be text, rich text, or keyword fields. The text within each field isconcatenated with spaces in the order specified. If Notes cannot locate afield by name, it uses the string literal instead. Enclose each field namein quotes and separate multiple names with colons: “Sales”:“Figures”

Caution Rich text fields are not part of a document until saved. If youwant @Abstract to work on additions and changes to the current document,you must first save and then recalculate the document.

Return ValueabstractedText

Text. The text contained in each of the body fields, abbreviated andsorted as specified by the commands.

CommandsThere are 19 different commands you can use with @Abstract.

[TextOnly]

Removes mail headers and punctuation chunks from the text.

[CountWords]

Computes the significance of each word in the text. A word’ssignificance depends on the number of times it appears in the text. Aword that appears in the Significant Word file (see “Files,” below) getsits significance boosted. A word that appears in the Insignificant Wordfile (see “Files,” below) has no significance.

[Save]

Saves the text in its current state. Saved text can be restored with the[Restore] command.

[Restore]

Discards the current text and restores the last-saved text. You can onlyrestore saved text one time. If no text has been previously saved, thiscommand has no effect.

[TryFit]

Takes the current text and determines if it has become small enough tofit in the specified size. If so, @Abstract returns the current text andstops, ignoring any remaining commands. If not, @Abstract continueswith the next command.

156 Domino Designer Programming Guide, Volume 1: Formula Language

[SortChunks]

Sorts the text according to significance. The text is divided into chunks,of which there are three types: text, mail header, and punctuation.

Text chunks are usually sentences. They may be at the beginning,end, or middle of a paragraph.

Mail header chunks are created according to the contents of the MailHeaders file (see “Files”, below).

Punctuation chunks consist of any text with no letters or digits.

The significance of a chunk depends upon the significances of thewords within it, the number of words in the chunk, and the type andposition of the chunk. To use [SortChunks], you must also use[CountWords].

[Abbrev]

Abbreviates the text. @Abstract uses an Abbreviation Dictionary tosubstitute abbreviations for words in the text (see “Files,” below). Youcan control other aspects of the abbreviation process with the followingcommands (which have no effect unless followed by the [Abbrev]command):

[UseDict]

Specifies that the Abbreviation Dictionary should be used. This is thedefault.

[NoDict]

Specifies that the Abbreviation Dictionary should not be used.

[KeepVowels]

Keeps vowels in words. This is the default.

[DropVowels]

Removes vowels from words. The first vowel in a word that beginswith a vowel isn’t affected. If you use [DropVowels], you can optionallyuse one of the following subcommands.

[DropFirstVowel]

Drops vowels from the beginning of words.

[KeepFirstVowel]

Keeps vowels at the beginning of words. This is the default.

[TrimWhite]

Removes extra white space characters from the text. This is the default.

[NoTrimWhite]

Retains extra white space characters in the text.

Chapter 5: Formula Language @Functions A–Z 157

[TrimPunct]

Removes extra white space characters surrounding punctuation.

[NoTrimPunct]

Retains extra white space characters surrounding punctuation.

[NoStopList]

Disables the insignificant word list (notestop.txt)

[NoSigList]

Disables the significant word list (notesigl.txt).

RulesThere are three built-in programs you can use with @Abstract.

[Rule1] consists of the following commands, executed in this order:

[TextOnly]:[TryFit]

Removes all mail header and punctuation chunks. If the text fits, thefunction is done; otherwise, continue.

[TrimPunct]:

Trims whitespace around punctuation marks.

[Save]:

Saves the current state of the text.

[Abbrev]:[TryFit]:

Abbreviates the text. If the text fits, the function is done; otherwise,continue.

[Restore]:

Restores the state of the text to what it was prior to abbreviating.

[Save]:

Saves the current state of the text.

[DropVowels]:[Abbrev]:[TryFit]:

Abbreviates text by dropping vowels. If the text fits, the function isdone; otherwise, continue.

[Restore]:

Restores the state of the text to what it was prior to abbreviating.

[CountWords]:[SortChunks]:[Abbrev]

Counts words and sorts the chunks. Abbreviates the text and returns it.

158 Domino Designer Programming Guide, Volume 1: Formula Language

If the removal of mail headers and punctuation allowed the text to fit intothe desired size, then text is returned as is. If the first abbreviation wasenough to make the text fit, the returned text begins with a minus character( - ). If the second abbreviation was enough to make the text fit, the returnedtext begins with a plus character ( + ). If the function counted the words andsorted the chunks, the text will start with an asterisk ( * ) and the sentenceswill be separated with a ( | ) to indicate that they were rearranged.

[Rule2] issues the following commands:

[TrimPunct]:[Abbrev]

[Rule3] issues the following commands:

[TextOnly]:[TryFit]:

Removes all mail header and punctuation chunks. If the text fits, thefunction is done; otherwise, continue.

[TrimPunct]:

Trims whitespace around punctuation marks.

[Save]:

Saves the current state of the text.

[Abbrev]:[TryFit]:

Abbreviates the text. If the text fits, the function is done; otherwise,continue.

[Restore]:

Restores the state of the text to what it was prior to abbreviating.

[DropVowels]:

Abbreviates text by dropping vowels.

[Save]:

Saves the current state of the text.

[Abbrev]:[TryFit]:

If the text fits, the function is done; otherwise, continue.

[Restore]:

Restores the state of the text to what it was prior to abbreviating.

[CountWords]:[SortChunks]:[Abbrev]

Counts words and sorts the chunks. Abbreviates the text and returns it.

Chapter 5: Formula Language @Functions A–Z 159

If the function counted the words and sorted the chunks, the returned textbegins with a asterisk ( * ) and the sentences are separated with a ( | ) toindicate that they were rearranged.

FilesThe following files are used by @Abstract. In your path, you can provideall, some, or none of these files, depending on how you want to use@Abstract. The files must be present in your path when you start the Notessoftware.

Abbreviation Dictionary (noteabbr.txt)

Each line of the file should contain two words: the first is the originalword and the second is its abbreviation. An abbreviation must beshorter than the word it replaces. For example:telephone ph

number no

Capitalization works as follows:

If the abbreviation is specified in uppercase letters, then it alwaysappears in uppercase letters.

If the original word appears in lowercase letters, the abbreviationappears as specified in the abbreviation dictionary.

If the original word appears in uppercase letters or in a mixture ofuppercase and lowercase letters:

A lowercase first letter in the abbreviation will be converted touppercase if needed to match the first letter in the original word.

The remaining letters in the abbreviation will be converted touppercase if needed to match the case of the original word’s second letter.

160 Domino Designer Programming Guide, Volume 1: Formula Language

The abbreviation is never converted to lowercase, but it may be convertedto uppercase.

Specifiedabbreviation

Word beingreplaced

Resultingabbreviation Reasoning

telephone Phone The original word appears inlowercase, so the specifiedabbreviation’s case is used.

TElephone PHONE The abbreviation’s case is basedupon the original word’s case.

Phone Telephone Phone The abbreviation’s case is basedupon the original word’s case.

PHONE Telephone PHONE The abbreviation is specified asuppercase, so it always appears as uppercase.

tElephone PHONE The first letter of the abbreviationwas already uppercase, so Notes leaves it alone. Theremaining letters of theabbreviation are converted touppercase to match the secondletter of the original word.

Significant Words (notesigl.txt)

The file should be a free-form list of significant words, such as “urgent”or “immediately.” When @Abstract computes the significance of text, itboosts the significance of any words included in the significant wordlist. For example:client

boss

chocolate

Insignificant Words (notestop.txt)

The file should be a free-form list of words that are always insignificant,such as “the”, “and”, and “of.” When @Abstract computes thesignificance of words, it ignores any words included in this file. For example:the

and

of

Chapter 5: Formula Language @Functions A–Z 161

Mail Headers (notehead.txt)

The file should be a free-form list of words that indicate mail headers,such as Subject, From, and To. In order for @Abstract to consider achunk a mail header, it must begin with one of the words specified inthis file and be followed immediately by a colon and a space. If youwant a mail header to be considered significant, place an asterisk afterthe word. For example:Subject*

From

Examples: @Abstract1. This formula abbreviates the contents of the description field by

eliminating vowels.@Abstract( [DropVowels]:[Abbrev]; 200; ""; "description" )

If the description field contained this text: The kickoff meeting for ourcapital campaign is tomorrow.

Then the formula returns: Th kckff mtng fr or cptl cmpgn is tmrrw.

2. This formula abbreviates the contents of the description field by usingan Abbreviation Dictionary and eliminating vowels.@Abstract([UseDict]:[DropVowels]:[Abbrev]; 200; "";"description" )

If the Abbreviation Dictionary contains the following:

capital capmeeting mtgtomorrow tom

Then the formula returns: Th kckff mtg fr or cap cmpgn is tom.

3. This formula shows a misunderstanding in the use of @Abstract. Itreturns the contents of the description field unaltered, since the[Abbrev] command incorrectly precedes [DropVowels].@Abstract( [Abbrev]:[DropVowels]; 200; ""; "description" )

@AccessedIndicates the time and date when the document was last accessed, whetherfor reading or editing.

Syntax@Accessed

162 Domino Designer Programming Guide, Volume 1: Formula Language

Return valuelastAccessed

Time-date. The time and date that the current document was lastaccessed.

Usage@Accessed is most useful in field formulas, selection formulas, agents, andactions. Because @Accessed requires some time to compute, it should not beused in applications where efficiency is critical.

The value returned by @Accessed is exact only to the day, not the hour. Ifthe document is accessed twice during the same 24-hour period, the valueis not updated.

The last-accessed value is not replicated; each replica copy of the documentmaintains its own value. The value returned by @Accessed represents thelast time the document was accessed in that replica of the database.

If the database is stored on CD-ROM, @Accessed has no meaning becauseread/write access is not controlled by the Notes editor.

Usage in workflow applicationsThis function is useful for determining whether a document has been“stalled” in a workflow application; for example, you can run an agent thatchecks the last-accessed date on a series of documents and sends outreminders about documents that should have been read but have not.

@Accessed can also be used in an agent to determine which documents in adatabase have not been accessed within a certain period of time, andarchive them.

Note @Accessed is similar to @Modified, which records the date thedocument was last edited and saved.

Usage in column or selection formulasBe careful when using @Accessed in views (in column or selectionformulas) because it forces the view to be refreshed every time it’s opened.You can prevent this by selecting the Manual/Background option for theview refresh frequency. Using @Accessed in a view will also cause thatview to perpetually appear to need refreshing—the refresh mark willalways display in the corner.

Example: @AccessedThis formula returns: 06/22/95 10:46:03 AM; if the document was last reador edited on June 22, 1995 at 10:46:03 AM.

@Accessed

Chapter 5: Formula Language @Functions A–Z 163

@Acos

Calculates the arc (inverse) cosine, using the cosine of an angle.

Syntax@Acos( cosine )

Parametercosine

Number. A cosine of an angle, from -1 through 1.

Return valueangle

Number. An angle, in radians, from 0 through pi. This represents anangle between 0 and 180 degrees.

Examples: @Acos1. This example returns pi/2.

@Acos( 0 )

2. This example returns 1.0472 radians (60 degrees).@Acos( 0.5 )

@AddToFolder

Adds current document to one folder while removing it from another.NULL string can be substituted for either argument to skip the action.

Note This @function is new with Release 5.

Syntax@AddToFolder(foldernameadd ; foldernameremove)

Parametersfoldernameadd

Text. The name of the folder document will be added to.

foldernameremove

Text. The name of the folder document will be removed from.

UsageThis formula can be used in SmartIcons, Button, and Agent formulas.

@Command([Folder]; Foldername; MoveOrCopy) works just like@AddToFolder except it moves a document from the current folder.

164 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @AddToFolder1. This example adds the currently selected document to the folder named

Work.@AddToFolder("Work";"")

2. This example adds the currently selected document to the folder namedWork and removes it from the folder named Favorites.@AddToFolder("Work";"Favorites")

@AdjustAdjusts the specified time-date value by the number of years, months,days, hours, minutes, and/or seconds you specify. The amount ofadjustment may be positive or negative.

Syntax@Adjust( dateToAdjust ; years ; months ; days ; hours ; minutes ; seconds ; [DST] )

ParametersdateToAdjust

Time-date. The time-date value you want to increment. This should bea single value, not a range.

years

Number. The number of years to increment by.

months

Number. The number of months to increment by.

days

Number. The number of days to increment by.

hours

Number. The number of hours to increment by.

minutes

Number. The number of minutes to increment by.

seconds

Number. The number of seconds to increment by.

Chapter 5: Formula Language @Functions A–Z 165

dst

Keyword. Optional. Specify [InLocalTime] to further adjust the timefor daylight savings if the adjustment crosses the boundary anddaylight savings is in effect. Specify [InGMT] or omit this parameter tonot further adjust the time for daylight savings. The adjustment is suchthat adding or subtracting in day increments yields the same time in thenew day.

Return valueadjustedDate

Time-date. The date, incremented by the amount of time you havespecified.

UsageYou must include all arguments except the last. Use 0 for those you don’twant to adjust.

While the order of the arguments is that of the value that changes mostslowly (year) to the value that changes most quickly (second), @Adjust actson the arguments from the one that changes most quickly (second) to theone that changes most slowly (year).

Calculating due datesA typical use for @Adjust is calculating a due date from an entry date, byadjusting only one component of the time-date value, for example, themonth component.

Examples: @Adjust1. This example returns 09/2/97.

@Adjust([06/30/95];2;2;2;0;0;0)

Notes sees 30 in the days portion of the time-date value and adjusts itby 2, which increments the month value by 1. Notes then adjusts themonth value by 2, and the year value by 2.

2. This example returns 03/20/94.@Adjust([03/30/96];-2;0;-10;0;0;0)

Notes returns a date that is 2 years and 10 days before the supplieddate.

3. This example returns the date one month from the date in the fieldnamed Date.@Adjust(Date;0;1;0;0;0;0)

4. This example returns the date one month and one day from the currenttime-date.

166 Domino Designer Programming Guide, Volume 1: Formula Language

@Adjust(@Now;0;1;1;0;0;0)

5. Given a date, this formula calculates the beginning of the week. It takesthe date stored in the dueDate field, and returns the date representingthe previous Monday. For example, if dueDate is 06/02/95, thisformula returns 05/29/95.@Adjust( dueDate; 0; 0; - ( @Weekday( dueDate ) - 2 ); 0;0; 0 )

@All

Returns the value True.

Syntax@All

Return valueflag

Number. The number 1 (True).

UsageUse @All in selection formulas, mail agents, paste agents, scheduled agents,or in any formula requiring a SELECT statement. Notes appends SELECT@All to agents in contexts where @All is needed. All views default to aselection formula of SELECT @All.

Examples: @All1. This example selects all documents in the database when used as a view

selection formula.SELECT @All

2. This formula, when used in a mail or paste agent, selects all documentsand sets the Status field to “Open.”FIELD Status:="Open";SELECT@All

@AllChildren

Includes all response documents at all levels for parent documents thatmatch selection criteria.

SyntaxSELECT selectionFormula I @AllChildren

Chapter 5: Formula Language @Functions A–Z 167

Return valueSelects all the documents that match selectionFormula plus their immediateresponses.

Usage@AllChildren can only be used in a view selection or selective replicationformula. It must be appended to the end of a selection formula using theBoolean OR operator (“|”). Don’t use it within complex expressions in aformula.

@AllChildren allows you to define a view as a set of documents that matcha given formula plus the immediate responses to those documents. It alsoallows you to create a selective replication formula to replicate a set ofdocuments along with the immediate responses.

Selection formulas that use @AllChildren may provide a significantadvantage over formulas that use @IsResponseDoc. While @IsResponseDocreturns true for any response document in a database, @AllChildren returnsonly those responses that are immediate children of matching documents.

@AllDescendantsIncludes all response and response-to-response documents for parents thatmatch selection criteria.

SyntaxselectionFormula I @AllDescendants

Return valueSelects all the documents that match selectionFormula plus their responsesand responses-to-responses, for as many levels of response documents asexist.

Usage@AllDescendants can only be used in a view selection or selectivereplication formula. It must be appended to the end of a selection formulausing the Boolean OR operator (“|”). Don’t use it within complexexpressions in a formula.

@AllDescendants allows you to define a view as a set of documents thatmatch a given formula plus all the responses to those documents, at anylevel. It also allows you to create a selective replication formula to replicatea set of documents along with all responses.

Selection formulas that use @AllDescendants may provide a significantadvantage to formulas that use @IsResponseDoc. While @IsResponseDoc

168 Domino Designer Programming Guide, Volume 1: Formula Language

returns true for any response document in a database, @AllDescendantsreturns only those responses that are descendants of matching documents.

Examples: @AllChildren and @AllDescendants1. A response hierarchy contains the following documents.

1.0 What is your favorite color? (Esteban Garcia) 1.1 Blue (Mary Lu) 1.2 Aqua (Jim Thompson) 1.2.1 Why do you like aqua? (Mary Lu) 1.2.2 It reminds me of the ocean (Jim Thompson) 1.3 I like the color orange (Bill Jones)

The first SELECT statement selects documents 1.2, 1.2.1, and 1.2.2; the second selects documents 1.0, 1.1, 1.2, and 1.3; the third selectsdocuments 1.0, 1.1, 1.2, 1.2.1, 1.2.2, and 1.3; and the fourth selectsdocuments 1.2.1 and 1.3.SELECT @Author = "Jim Thompson" | @AllChildren

SELECT @Author = "Esteban Garcia" | @AllChildren

SELECT @Author = "Esteban Garcia" | @AllDescendants

SELECT @Contains( Subject; "like" ) | @AllChildren

2. You have a Flowers discussion database and you want to add a newview that will show only those documents having to do with orchids.You create an Orchid view, use the View InfoBox to indicate that itshould show documents in a response hierarchy, and write thefollowing selection formula for the view:SELECT @Contains( Subject; "orchid" ) | @IsResponseDoc

You get this view:

Date Topic04/08/95 The orchid family of flowers (Anne Davis, 2 responses)04/08/95 Sighting of new variation (Brad Sullivan)04/08/95 The “ghost” orchid (Rachel Greenbaum)04/08/95 Local flower shops that carry orchids (Mary Tsen, 1response)04/08/95 Try the Blumenhaus (Anne Davis)

The view, however, is selecting every response document in the entiredatabase, whether or not it has to do with orchids. For example, here’swhat the view looks like when the response hierarchy is turned off:

Date Topic04/08/95 The orchid family of flowers (AnneDavis)04/08/95 Sighting of new variation (Brad Sullivan)04/08/95 Special varieties of roses (Michael Bowling)

Chapter 5: Formula Language @Functions A–Z 169

04/08/95 My roses bloomed late this year (Marcel DuBois)04/08/95 Local flower shops that carry orchids (Mary Tsen)04/08/95 Try the Blumenhaus (Anne Davis)04/08/95 The “ghost” orchid (Rachel Greenbaum)

The unneeded documents take up valuable space in the view index onthe database server. (In addition, if you used this same formula forreplication, the unneeded documents would be replicated).

You use @AllChildren to rewrite the selection formula:SELECT @Contains( Subject; "orchid" ) | @AllChildren

This formula selects and displays only those response documents whoseparent contains “orchid” in the Subject field. The view does not containany hidden response documents.

Date Topic04/08/95 The orchid family of flowers (Anne Davis, 2 responses)04/08/95 Sighting of new variation (Brad Sullivan)04/08/95 The “ghost” orchid (Rachel Greenbaum)04/08/95 Local flower shops that carry orchids (Mary Tsen, 1response)04/08/95 Try the Blumenhaus (Anne Davis)

3. Just as you’d hoped, the orchids generate a lively discussion. The MainView of the database, which selects all documents, now looks like this:

Date Topic04/08/95 The orchid family of flowers (Anne Davis, 7 responses)04/08/95 Sighting of new variation (Brad Sullivan, 2 responses)04/08/95 What color? (Anne Davis)04/08/95 Please post exact location (Mary Tsen)04/08/95 The “ghost” orchid (Rachel Greenbaum, 3 responses)04/08/95 Very difficult to see (Brad Sullivan, 1 response)04/08/95 Only blooms for an hour or so! (Rachel Greenbaum)04/08/95 Some sightings reported in Florida (AnneDavis)04/08/95 Roses beginning to bloom (Peter Donovan, 2 responses)04/08/95 Special varieties of roses (Michael Bowling)04/08/95 My roses bloomed late this year (Marcel DuBois)04/08/95 Local flower shops that carry orchids (Mary Tsen, 1response)04/08/95 Try the Blumenhaus (Anne Davis)04/08/95 Tulip trips to Holland (Mary Tsen)

The Orchid view you just created, however, does not contain all thedocuments you want. @AllChildren only selects the immediate childrenof any parent document(s) that meet the selection criteria:

170 Domino Designer Programming Guide, Volume 1: Formula Language

Date Topic04/08/95 The orchid family of flowers (Anne Davis, 4 responses)04/08/95 Sighting of new variation (Brad Sullivan)04/08/95 The “ghost” orchid (Rachel Greenbaum, 2 responses)04/08/95 Very difficult to see (Brad Sullivan)04/08/95 Some sightings reported in Florida (Anne Davis)04/08/95 Local flower shops that carry orchids (Mary Tsen, 1response)04/08/95 Try the Blumenhaus (Anne Davis)

In this case, @AllDescendants might provide a better solution. Yourewrite the selection formula:SELECT @Contains( Subject; "orchid" ) | @AllDescendants

The Orchid view now contains entire threads of orchid discussion:

Date Topic04/08/95 The orchid family of flowers (Anne Davis, 7 responses)04/08/95 Sighting of new variation (Brad Sullivan, 2 responses)04/08/95 What color? (Anne Davis)04/08/95 Please post exact location (Mary Tsen)04/08/95 The “ghost” orchid (Rachel Greenbaum, 3 responses)04/08/95 Very difficult to see (Brad Sullivan, 1 response)04/08/95 Only blooms for an hour or so! (Rachel Greenbaum)04/08/95 Some sightings reported in Florida (Anne Davis)04/08/95 Local flower shops that carry orchids (Mary Tsen, 1response)04/08/95 Try the Blumenhaus (Anne Davis)

@Ascii

Converts an LMBCS (Lotus Multi-Byte Character Set) string to an ASCIIstring.

Syntax@Ascii( string )@Ascii( string ; [AllInRange] )

Parametersstring

Text or text-list. An LMBCS string.

Chapter 5: Formula Language @Functions A–Z 171

[AllInRange]

Keyword. Optional. Specifies that @Ascii should return a null string(“”) if any characters in the original string cannot be represented byASCII codes 32 to 127.

Return valuenewString

Text or text-list. The original string, with each character converted to anASCII-compliant character. Any character that can’t be represented byASCII codes 32 to 127 is replaced with a question mark (?). If youspecify [AllInRange] and there are characters that can’t be representedby ASCII codes 32 to 127, returns a null string (“”).

Usage@Ascii first converts the string into ASCII-compliant characters, replacingany unrepresented characters with question marks, and then, if[AllInRange] is true, checks for question marks within the string. Thismeans that if the original string contains a question mark and [AllInRange]is specified, a null string is returned even if the entire string can berepresented by ASCII codes 32-127.

Examples: @Ascii1. This example returns Cue.

@Ascii( "Çüé" )

2. This example returns Cue??.@Ascii( "Çü飥" )

3. This example returns a null string (“”) since the last 2 characters can’tbe represented by ASCII codes 32 to 127.@Ascii("Çü飥";[AllInRange])

4. This example returns Cue??; cat if field1 is a field containing the text list“Çü飥”;“cat”.@Ascii( field1 )

@AsinCalculates the arc (inverse) sine using the sine of an angle.

Syntax@Asin( sine )

172 Domino Designer Programming Guide, Volume 1: Formula Language

Parametersine

Number. A sine of an angle, from -1 through 1.

Return valueangle

Number. An angle, in radians, from -pi/2 through pi/2. This representsan angle between -90 and 90 degrees.

Examples: @Asin1. This example returns pi/2.

@Asin( 1 )

2. This example returns 0.72082 radians (41.3 degrees).@Asin ( 0.66 )

@AtanCalculates the arc (inverse) tangent using the tangent of an angle.

Syntax@Atan( tangent )

Parametertangent

Number. The tangent of an angle.

Return valueangle

Number. An angle, in radians, from -pi/2 through pi/2. This representsan angle between -90 and 90 degrees.

Examples: @Atan1. This example returns pi/4.

@Atan( 1 )

2. This example returns -pi/4.@Atan( -1 )

3. This example returns 1.10715 radians (63.4 degrees).@Atan( 2 )

Chapter 5: Formula Language @Functions A–Z 173

@Atan2

Calculates the arc tangent using the tangent y/x of an angle.

Syntax@Atan2( x ; y )

Parametersx

Number. The denominator of the tangent value y / x.

y

Number. The numerator of the tangent value y / x.

Return valueangle

Number. An angle, in radians, from -pi through pi. This represents anangle between -180 and 180 degrees, depending on the sign of x and y(see the list below).

If: Then angle is in the range:

x is positivey is positive

0 to pi/2 (Quadrant I)

x is negativey is positive

pi/2 to pi (Quadrant II)

x is negativey is negative

-pi to -pi/2 (Quadrant III)

x is positivey is negative

-pi/2 to 0 (Quadrant IV)

Examples: @Atan21. This example returns pi/4.

@Atan2( 1; 1 )

2. This example returns 3pi/4.@Atan2( -1; 1 )

3. This example returns 1.10715 radians (63.4 degrees).@Atan2 ( 1; 2 )

174 Domino Designer Programming Guide, Volume 1: Formula Language

@AttachmentLengths

Returns a number or a number list containing the length of each attachmentto the current document. The number(s) returned are only approximations;the actual size(s) of the attachment(s) may be slightly different.

Syntax@AttachmentLengths

Return valuesizeInBytes

Number or number list.

If the current document contains one attachment, sizeInBytes is anumber representing the size of that attachment in bytes.

If the current document contains more than one attachment,sizeInBytes is a number list where each number in the number list isthe size of one of the attachments, in bytes.

UsageThe attachment size is computed based on uncompressed file size (that is,the number of bytes the attachment would use if you extracted it); theactual disk storage space required for the file may be somewhat smaller.

@AttachmentLengths returns an empty list if there are no attachments. Ifthere is one attachment of length 0, @AttachmentLengths returns 0.

Examples: @AttachmentLengths1. This example returns 6102 if that is the approximate size of the single,

attached file.@AttachmentLengths

2. This example, given a semicolon as the multi-value separator, returnsautoexec.bat:112;config.sys:1549;q4sales.wk4:17636 if those are thenames and lengths of the files attached.@AttachmentNames + ":" + @Text(@AttachmentLengths)

3. This example returns 0 if there is one attachment of length 0.@AttachmentLengths

4. This example returns an empty list (no value appears at all) if there areno attachments.@AttachmentLengths

Chapter 5: Formula Language @Functions A–Z 175

5. This example sums the attachment lengths, checking first to make surethere are attachments.@Sum(@Attachments > 0; @AttachmentLengths; 0)

@AttachmentNames

Returns the operating system file names of any files attached to a document.If there are multiple files attached, the names are returned as amultiple-value text list.

Syntax@AttachmentNames

Return valuenames

Text or text list.

If the current document contains one attachment, names is textrepresenting the file name of that attachment.

If the current document contains more than one attachment, names isa text list where each item is the file name of one of the attachments.

Examples: @AttachmentNames1. If a file named salesq1.wk4 is attached to the document, this example

returns: salesq1.wk4.@AttachmentNames

2. Given a semicolon as the multi-value separator, if files namedsalesq1.wk4 and admin.doc are attached to the document, this examplereturns: salesq1.wk4; admin.doc.@AttachmentNames

@Attachments

Returns the number of files attached to a document.

Syntax@Attachments

Return valuenumFiles

Number. The number of files attached to the current document.

176 Domino Designer Programming Guide, Volume 1: Formula Language

Usage in a Column FormulaWhen used in a column formula in a view or folder, @If(@Attachments;5;0)can be used to display the paper clip icon if the current document has oneor more attachments, or displays a blank if there are no attachments. This isthe formula used to indicate attachments in the Notes mail template. Forthis formula to work, you must select Icon in the Column Definition dialogbox for this column.

Examples: @Attachments1. This example returns 3 if there are three files attached to a document.

@Attachments

2. This example returns 0 if there are no files attached to a document.@Attachments

@AuthorReturns a text list containing the names of the author(s) of the currentdocument.

Syntax@Author

Return valueauthorList

Text list. All the authors of the current document. For authors withhierarchical names, Notes returns the abbreviated form of the name (asin Denise Lee/Research/Acme), rather than the canonical form(CN=Denise Lee/OU=Research/O=Acme).

@Author uses the following instructions (in the sequence outlined below) tofind document author(s) and return the appropriate text list:

1. Search the document for a field of type Authors. If there is one, returnthe name(s) stored there. (If there are multiple Authors fields, returnsthe contents of the first Authors field found in the document.)

2. If there is no Authors field, look for a field called From. If there is aFrom field, look for the field FromDomain.

If both fields are found, combine the two fields, separating them byan @ sign (as in, Mary Tsen@AcmeWest).

Otherwise, return the contents of the From field only.

3. If there is no From field, look for a field named $UpdatedBy. If there isone, return the contents of the field.

Chapter 5: Formula Language @Functions A–Z 177

4. If there is no $UpdatedBy field and this is a new document (not yetsaved), return the current user’s name.

5. If none of the above can be found, return the null string (“”).

Usage@Author is most useful for documents containing an Author Names orFrom field.

Example: @AuthorIf a document has one Authors field that contains: Mary Tsen, David Smith,Denise Lee/Research/Acme. This example returns: Mary Tsen; DavidSmith; Denise Lee/Research/Acme.

@Author

@BeginsDetermines whether a particular substring is stored at the beginning ofanother string.

Syntax@Begins(string ; substring )

Parametersstring

Text. Any string.

substring

Text. The string you want to search for at the beginning of string.

Return valueflag

Boolean. Returns 1 (True) if substring is contained within string,beginning from the first letter; returns 0 (False) if not.

UsageThis function is case-sensitive.

Examples: @Begins1. This example returns 1.

@Begins("Hi There";"Hi")

2. This example returns 0.@Begins("Hi There";"hi")

178 Domino Designer Programming Guide, Volume 1: Formula Language

3. This example checks the field named Topic; if that field begins with thestring “All desks memo”, returns the string: Junk Mail. Otherwise, itreturns the string: Read this first.@If(@Begins(Topic;"All desks memo");"Junk Mail"; "Readthis first")

@BrowserInfoDetermines the capabilities of a Web client, that is you can determine theproperties of the browser for the current request.

Note This @function is new with Release 5.

Syntax@BrowserInfo( “propertyname” )

Parameterspropertyname

Text. The name of the browser property to be retrieved.

Return valueThe return value type is dependent on the capability. The table belowshows the current set of Web Browser and Notes Client capabilities thatNotes supports:

Property name Return type Return value for browsers Return value for Notes client

BrowserType Text The type of the browser:“Microsoft”, “Netscape”,“Compatible” (for browsers thatclaim to be compatible withNetscape, including NotesNavigator 5.0), or “Unknown.”

“Notes”

Cookies Boolean 1 (True) if the browser supportscookies; otherwise 0 (False).

0 (False)

DHTML Boolean 1 (True) if the browser supports dynamic HTML;otherwise 0 (False).

0 (False)

FileUpload Boolean 1 (True) if the browser supportsfile upload; otherwise 0 (False).

0 (False)

continued

Chapter 5: Formula Language @Functions A–Z 179

Property name Return type Return value for browsers Return value for Notes client

Frames Boolean 1 (True) if the browser supportsthe HTML <FRAME> tag;otherwise 0 (False).

1 (True)

Java Boolean 1 (True) if the browser supportsJava applets; otherwise 0 (False).

1 (True)

JavaScript Boolean 1 (True) if the browser supportsJavaScript; otherwise 0 (False).

1 (True)

Iframe Boolean 1 (True) if the browser supportsthe Microsoft HTML <IFRAME>tag; otherwise 0 (False).

0 (False)

Platform Text The operating system platform of the browser: “Win95”,“Win98”, “WinNT”, “MacOS”, or“Unknown”.

“Unknown”

Robot Boolean 1 (True) if the browser isprobably a Web robot; otherwise 0 (False).

0 (False)

SSL Boolean 1 (True) if the browser supportsSSL; otherwise 0 (False).

0 (False)

Tables Boolean 1 (True) if the browser supportsthe HTML <TABLE> tag;otherwise 0 (False).

1 (True)

VBScript Boolean 1 (True) if the browser supportsVBScript; otherwise 0 (False).

0 (False)

Version Number The browser version number, or-1 for unrecognized browsers.

Notes clientbuild number

Usage@BrowserInfo determines the properties of a browser by matching theHTTP User-Agent header sent by the browser to property rules in thebrowser.cnf file in the Notes data directory. @BrowserInfo also containshard-coded rules for the Notes client.

@BrowserInfo can be used in all types of formulas except view selection andview column formulas.

180 Domino Designer Programming Guide, Volume 1: Formula Language

Pre-5.0 Notes clients will not be able to open forms that use @BrowserInfo.The client will display the error message “Invalid formula: unknownfunction/operator”. To prevent this error, check the version number of theclient in your formulas. Example:

@If(@TextToNumber(@Version) >= 160;@BrowserInfo(“BrowserType”);“Unknown”)

Example: @BrowserInfoThis example displays the value in the field named KeyThought, if thecurrent browser supports JavaScript; otherwise the value in the field Topicis diplayed.

@If (@BrowserInfo("JavaScript"); KeyThought;Topic)

@CertificateExtracts information from the Certified Public Key in the Public Address Book.

Syntax@Certificate( [dataToRetrieve ] ; Certificate)

ParameterdataToRetrieve

Keyword. Must be enclosed in brackets as shown. Use one of thefollowing keywords:

Subject

The name of the certified user ID or server ID.

Issuer

The name of the ID used to issue the certificate.

Expiration

The date and time that the North American certificate expires.

IntlExpiration

The date and time that the International certificate expires.

Certificate

Required. This specifies the name of the field where the Certified PublicKey information is stored.

Chapter 5: Formula Language @Functions A–Z 181

Return valuedataRetrieved

Text for the Subject and Issuer names, and time-date values for theExpiration and IntlExpiration dates.

Usage@Certificate is useful within a macro or view selection formula for selectinga list of users whose certificates are about to expire; it is used by severalPublic Address Book tools.

@Certificate only retrieves data; you cannot use it to change certificateinformation (use the appropriate Administration menus to updatecertificates). Certified Public Key information is stored only for users andservers with hierarchical IDs; @Certificate returns a null string fornon-hierarchical IDs.

If you use incorrect syntax, @Certificate returns a null string and does notgenerate an error message.

You cannot use this function in Web applications.

Examples: @Certificate1. This example returns CN=Michael

Bowling/OU=R&D/O=WorkSavers/C=US for Michael Bowling’shierarchical ID.@Certificate([Subject];Certificate)

2. This example returns the name of the ID that certified the ID.@Certificate([Issuer];Certificate)

3. This example returns the date and time the North American ID expires.@Certificate([Expiration];Certificate)

4. This example returns the date and time the International ID expires.@Certificate([IntlExpiration];Certificate)

@CharConverts an IBM Code Page 850 code number into the correspondingone-character string.

Syntax@Char( codePageNumber )

182 Domino Designer Programming Guide, Volume 1: Formula Language

ParametercodePageNumber

Number. Any number between 0 and 255. Non-integer numbers aretruncated to integers.

Return valuecorrespondingChar

Text. A single character that corresponds to codePageNumber.

Usage@Char(0) and @Char(13) both return a carriage return.

@Char(9) returns a tab.

Examples: @Char1. This example returns: A.

@Char(65)

2. This example returns: a.@Char(97)

3. This example returns: 8.@Char(56)

4. This example returns the character in the field namedQuestionnaireNumber if that field is currently filled in; otherwise,returns a null string.@If(@IsAvailable(QuestionnaireNumber);@Char(QuestionnaireNumber);"")

5. This example uses @Char(13) to insert a carriage return into the text of@Prompt.@Prompt([OK]; "Complete"; "The agent has finished." +@Char(13) + "Please exit this document without saving.")

@CheckAlarmsTriggers the alarm daemon to check for new alarms in the mail file.

Syntax@CheckAlarms

UsageYou use @CheckAlarms whenever you make changes to any schedulingthat involves alarms. This includes creating a new appointment or

Chapter 5: Formula Language @Functions A–Z 183

anniversary event with an alarm, changing an existing appointment thathas an alarm (because the mailer daemon has to reread the information tofind out when the new alarm should go off), or deleting an appointmentthat had an alarm.

@ClientType

Returns a text string to differentiate Notes and World Wide Web clients.

Syntax@ClientType

Return valueclient type

Text. Returns “Notes” if the client type is Notes. Returns “Web” if theclient type is Web.

Usage@ClientType is useful within database formulas, form formulas, buttons informs, and “hide-when” formulas. Do not use @ClientType in columnformulas.

@ClientType always returns “None” when executed in a server backgroundagent.

Examples: @ClientType1. This example returns the client type.

@Prompt([OK]; "Client type"; @ClientType)

2. This example, used in a Database script for a Postopen event, opens aview called “By Category - Notes” if the client type is “Notes,” or aview called “By Category - Web” otherwise.“@If(@ClientType = ”Notes"; @Command([OpenView]; "By Category - Notes");@Command([OpenView]; "By Category - Web"))

@Command

Executes a Notes command. Most of the standard menu commands can beexecuted using @Command. In addition, a number of specializedcommands are available. In a formula, any command invoked using@Command runs in the order you specify in the formula. This means that

184 Domino Designer Programming Guide, Volume 1: Formula Language

any changes made by the command, such as inserting text into a field, affectthe rest of the formula (see exceptions below).

Syntax@Command( [command ] ; parameters )

UsageThis function does not work in column, selection, hide-when, section editor,window title, field, or form formulas, or in agents that run on a server. It’sintended for use in SmartIcons, button, hotspot, and action formulas.

ExceptionsThe following commands always execute last in a formula, which meansthat their actions do not affect parts of the formula that follow thecommand:

FileCloseWindow

FileDatabaseDelete

FileExit

NavigateNext

NavigateNextMain

NavigateNextSelected

NavigateNextUnread

NavigatePrev

NavigatePrevMain

NavigatePrevSelected

NavigatePrevUnread

ToolsRunBackgroundMacros

ToolsRunMacro

ViewChange

ViewSwitchForm

Chapter 5: Formula Language @Functions A–Z 185

@Contains

Determines whether a substring is stored anywhere within a string.

Syntax@Contains( string ; substring )

Parametersstring

Text. The string you want to search.

substring

Text or text list. The string you want to search for in string.

Return valueflag

Boolean. Returns 1 (True) if substring is contained within string;otherwise returns 0 (False).

UsageThis function is case sensitive.

Examples: @Contains1. This example returns 1.

@Contains("Hi There";"Th")

2. This formula checks the field named Topic to see if it contains thephrases “I want,” “I need,” or “I must have”; if any of the phrases iscontained in the Topic field, the string Polite refusal needed is returned,otherwise the string Don’t delay response is returned.@If(@Contains(Topic;"I want":"I need":"I musthave");"Polite refusal needed";"Don't delay response")

@CosGiven an angle in radians, returns the cosine of the angle. In a right triangle,the cosine of an acute angle is the ratio of the length of its adjacent side tothe length of the hypotenuse.

Syntax@Cos( angle )

186 Domino Designer Programming Guide, Volume 1: Formula Language

Parameterangle

Number. An angle measured in radians.

Return valuecosine

Number. The cosine of angle, from -1 to 1.

Examples: @Cos1. This formula returns 1.

@Cos( 2 * @Pi )

2. This formula finds the length of side c in triangle ABC. You know thevalue of angle C in radians, and the lengths of sides a and b. Thisformula finds the length of side c.@Sqrt( @Power( sideA; 2 )+@Power( sideB; 2 )-( 2*sideA*sideB*( @Cos( angleC ) ) ))

This formula is a version of the law of cosines, which states that for anytriangle ABC, c2 = a2+b2-2ab(cos(C)).

@CreatedReturns the time-date when the document was created.

Syntax@Created

Return valuedateCreated

Time-date. The date when the current document was created.

Usage@Created differs from @Now, in that @Created returns a time-date valuethat remains constant, while @Now returns a dynamic time-date thatchanges with each formula evaluation when it is used in a computed field.

In a field formula, Notes takes the value for @Created from the server clock,unless the database is local.

Chapter 5: Formula Language @Functions A–Z 187

Examples: @Created1. This example returns 06/23/95 11:36:50 AM for a document created on

June 23, 1995, at 11:36:50 A.M.@Created

2. This example returns 8/4/93 3:10:00 PM for a document created onApril 4, 1992 at 3:10 P.M.@Adjust(@Created;1;4;0;0;0;0)

3. This view selection formula uses @Created to select only thosedocuments created in the current month. To avoid having the viewrefresh indicator display, it uses @TextToTime(“Today”) instead of@Today. Date calculations in views may impact the performance of anapplication.SELECT ( ( @Year( @Created ) = @Year( @TextToTime( "Today") ) ) & ( @Month( @Created ) = @Month( @TextToTime("Today" ) ) ) )

@DateTranslates numbers for the various components of time and date, thenreturns the time-date value.

Syntax@Date( year ; month ; day )@Date( year ; month ; day ; hour ; minute ; second )@Date( time-date )

Parametersyear

Number. The year that you want to appear in the resulting date. Youmust specify an entire four-digit year. (For example, use 1996, not 96).

month

Number. The month that you want to appear in the resulting date.

day

Number. The day that you want to appear in the resulting date.

hour

Number. The number of hours. This value will be truncated from theresulting date.

188 Domino Designer Programming Guide, Volume 1: Formula Language

minute

Number. The number of minutes. This value will be truncated from theresulting date.

second

Number. The number of seconds. This value will be truncated from theresulting date.

time-date

Time-date. For a time-date value such as @Now or [10/31/93 12:00:00],@Date removes the time portion of the value, leaving only the date.

Return valuetruncatedTimeDate

Time-date. The date corresponding to the parameters that you sent to@Date, minus any time components.

Examples: @Date1. This example returns 06/23/95.

@Date(1995; 06; 23)

2. This example returns 06/23/0095.@Date(95; 06; 23)

3. This example returns 06/23/2095.@Date(2095; 06; 23)

4. This example returns 06/23/95 if the time-date value in the fieldnamed ResponseDate is 06/23/95 03:00:01 P.M.@Date(ResponseDate)

5. This example returns 1/20/93 08:58:12 AM.@Date(1995; 01; 20; 8; 58; 12)

6. This example returns 11/20/95.@Date([11/20/95 8:58:12])

Chapter 5: Formula Language @Functions A–Z 189

@Day

Extracts the day of the month from the specified date.

Syntax@Day( timeDateValue )

ParametertimeDateValue

Time-date. The date containing the day value that you want to extract.

Return valuedayOfMonth

Number. The number corresponding to the day of the month indicatedby timeDateValue.

Examples: @Day1. This example returns 15 if today is July 15, August 15, September 15,

and so on.@Day(@Now)

2. This example returns the string “Payment received on or before the15th” if the PaymentReceived field is filled in on or before the 15th ofthe month; otherwise, it returns the string “Payment received after the15th.”@If(@Day(PaymentReceived)<16;"Payment received on orbefore the 15th";"Payment received after the 15th")

@DbColumn (Notes databases)

Looks up and returns an entire column of values from a view or folder ineither the active database or another Notes database.

Syntax@DbColumn( class : “NoCache” ; server : database ; view ; columnNumber )

Parametersclass

Text. Indicates what type of database you are accessing. You canindicate a Notes database with either “” or “Notes”.

190 Domino Designer Programming Guide, Volume 1: Formula Language

“NoCache”

Keyword. Optional. If you exclude “NoCache”, the results of thelookup are cached, that is, they are stored for re-use. Each subsequentlookup to the same location (within the same Notes session and so longas the database executing this lookup remains open) re-uses thatinformation. If you omit “NoCache”, you do not need to replace it withanything—the lookup results are cached automatically. See “SpecifyingNoCache,” below.

If you want to ensure that Notes retrieves the latest information forevery lookup, specify this option, using a colon after the classargument, as in “Notes”:“NoCache”.

server : database

Text list. The server location and file name of the database. See“Specifying the server and database.”

view

Text. The name of the view in which to search. The view name mustexactly match the full name of the view as specified in the Design ViewAttributes dialog box (you can omit any synonyms). If the viewcascades from another name on the menu, include that name, too. See“Specifying the view name.”

columnNumber

Number. The column number within the view. Because Notes looks upinformation in the view based on column numbers, you can onlyretrieve data that actually appears in the view. See “Specifying thecolumn number.”

Return valuevaluesFound

Text, numbers, date-time, or text list. The values found in the viewcolumn that you indicated. See “Accessing the values found,” later inthis chapter.

Specifying “NoCache”The decision to use “NoCache” is based on performance. Forcing Notes toconnect to the database and retrieve the same information again and againtakes time, and slows overall performance. However, if you expect that datato be changing on a frequent basis, it’s worth the extra time to make sureyou’re getting up-to-date information.

For example, if you’re using lookups to a database that stores customeraddresses, it’s generally safe to use caching because you don’t expect theaddresses to change very often. However, if you’re using a lookup to a

Chapter 5: Formula Language @Functions A–Z 191

database where stock prices are stored, and that database gets updatedhourly, it’s safer to skip the caching and force a new lookup each time.

Specifying the server and databaseThere are several ways to specify the server : database parameter:

To perform the lookup on the current database (the same database inwhich the formula is being evaluated), specify “” as the entire argumentto the function. Agents running on a server can only perform lookups todatabases on that same server. That is, “ ” means the local Notesdirectory where you are executing. If you happen to have an agentexecuting on a server, the agent cannot do lookups off of the server.

To perform a lookup on a local database, use “” for the server name andspecify the database name explicitly, such as “”:“database.nsf”.

To perform a lookup (from the workstation) on a Notes database thatresides on a server, include the server plus the path and file name as atext list, as in “server”:“database.nsf”.

If there are multiple copies of the database located on various Dominoservers, using the database replica ID in place of both the server anddatabase name allows you to access a replica copy of that databasewithout having to specify either the server name or the database name.For example, if you use “85255CEB:0032AC04” (a database replica ID,found in the database InfoBox) as the database name, Notes uses areplica of the database to retrieve the information.

Notes searches for replicas in this order, using the first replica itencounters:

Workspace

If there is one replica on your workspace, Notes uses it.

If there are multiple, stacked replicas on your workspace, Notes usesthe replica on top of the stack.

If there are multiple, unstacked replicas on your workspace, Noteslooks for an icon matching your current server and uses that. If noneof the icons matches your current server, Notes uses the icon thatwas added to your workspace first.

Current server

Locally (your hard disk)

Once a replica is located, it’s added to your workspace to save time onfuture lookups.

Tip To avoid typing errors in the replica ID, choose File - Database -Design Synopsis and select Replication. You can then copy the replica IDfrom the synopsis and paste it into your formula.

192 Domino Designer Programming Guide, Volume 1: Formula Language

Note If your database is located in a DOS or OS/2 subdirectory, such asmail\mine.nsF, put a double backslash between the directory and thedatabase name, as in “mail\\mine.nsf”, because formulas treat backslashesas “quote” characters.

Specifying a view or folderYou can specify a view (or folder) parameter using either the full name ofthe view or its synonym. For example, if your Last Name view is cascadedfrom By Author in the View menu, and has the synonym |LName, thename looks like this in the view InfoBox:

By Author\Last Name|LName

When you reference this view with @DbColumn, you can simply use theLName synonym, enclosed in quotation marks:

"LName"

If the view name doesn’t have a synonym, you can use the By Author nameplus the Last Name cascade, again enclosed in quotation marks (butwithout the synonym). And since the view name is used in a formula, the“\” must be preceded with an additional “\” to ensure that Notesinterprets it correctly:

"By Author\\Last Name"

Specifying the column numberTo specify a columnNumber parameter, you count the view columns fromleft to right, with the leftmost column being column number 1. Because ofthe way that Notes indexes views, however, not every column is countedfor the lookup.

Use the following method to calculate the column number for lookuppurposes:

1. Count the columns in the view, from left to right. Look at the view indesign mode to make sure that you see all the columns, includingcolumns used for sorting or categorizing the view.

2. Discount all columns that display a constant value, such as “Submittedby:” or 32. If a column contains a formula that happens to return thesame result for every document, it is not considered a “constant”, so besure to include it in your column count.

3. Discount all columns that consist solely of the following @functions:@DocChildren, @DocDescendants, @DocLevel, @DocNumber,@DocParentNumber, @DocSiblings, @IsCategory, @IsExpandable.

4. Now re-count the columns, working from left to right.

This revised column number is the value to specify in the lookup formula.

Chapter 5: Formula Language @Functions A–Z 193

If you specify a non-existent column, you don’t get an error, but rather anull value.

Accessing the return valuesIf multiple values are returned by @DbColumn, they are formatted as a listand are separated with the multi-value separator designated for the currentfield in the field InfoBox.

@DbColumn can return no more than 64K bytes of data. Use the followingequations to determine how much of your data can be returned using@DbColumn.

For lookups that return text:

2 + (2 * number of entries returned) + total text size of all entries

For lookups that return numbers or dates:

(10 * number of entries returned) + 6

Usage@DbColumn is intended mainly for use with keyword formulas. Instead ofhard-coding a list of keywords and then periodically updating that list byre-editing the form containing the keyword field, @DbColumn allows youto dynamically retrieve a list of values from a database view or table.

This function does not work in column or selection formulas, or in mail agents.

Server agents and securityConsider the database containing @DbColumn as the source database, andthe database being accessed as the target database.

When @DbColumn is used in an agent that runs on a server, it can onlyaccess target databases stored on the same server as the source database.The source database must have at least Reader access to the target database.

If it is not possible to assign Reader access or better to the -Default- groupfor security reasons, it is still possible to grant the @DbColumn macrosaccess from the source database to the target database.

1. Use File - Database - Properties to determine the Replica ID of thesource database, for example: 85255CEB:0032AC04.

2. Use File - Database - Access Control to add a new entry to the targetdatabase ACL. The entry name is the Replica ID itself; give the name atleast Reader access. In the above example, you add an entry with thename 85255CEB:0032AC04. By doing this, you’re specifically grantingthe macros in the source database access to the target database, even if -Default- is No Access.

194 Domino Designer Programming Guide, Volume 1: Formula Language

Other agents and securityWhen @DbColumn is used in any other type of formula or agent, it hasunlimited access to any target database stored on the user’s ownworkstation. If the target database is stored on another Domino server, theaccess for @DbColumn is determined by the user’s own access level (basedon the user’s Notes ID).

@DbColumn is subject to the Read Access list for a view.

Example: @DbColumn (Notes databases)This keyword formula uses @DbColumn. Whenever a document iscomposed using the form, Notes retrieves the list of product names storedin column 2 of the Inventory On Hand view of the Inventory database(inventry.nsf). This lookup is used in a purchase requisitions application toretrieve a current list of products available in inventory.

@DbColumn("";"":"inventry.nsf";"Inventory On Hand";2)

@DbColumn (ODBC)Uses data source information to activate the appropriate ODBC driver. Thedriver then locates the specified DBMS, table, and column, and returns allvalues in that column. You can optionally specify whether the returned listof values is sorted, whether duplicate values are deleted, and how nullvalues are handled.

Note @DbColumn can only retrieve data; it can’t add, delete, or modifydata.

Syntax@DbColumn( “ODBC” : “NoCache” ; data_source ; user_ID1 : user_ID2 ;password1 : password2 ; table ; column : null_handling ; “Distinct” : sort )

Parameters“ODBC”

Keyword. Indicates that you are accessing an ODBC data source.

“NoCache”

Keyword. Optional. If you want to ensure that Notes retrieves the latest information for every lookup, specify this option, as in“ODBC”:“NoCache”. Omit NoCache if you want the results of the lookup to be cached, that is, stored for re-use. Each subsequentlookup to the same location within the same Notes session will re-use that information, as long as the database executing this lookup remains open.

Chapter 5: Formula Language @Functions A–Z 195

If you omit “NoCache”, you do not need to replace it with anything.The lookup results are cached automatically, but you may specify“Cache” for readability.

See “Specifying NoCache.”

data_source

Text. The name of the external data source being accessed. A datasource indicates the location of one or more database tables.

See “Specifying the data source.”

user_ID1 : user_ID2

Text list. The user IDs needed to connect to the external database. Youmay need up to two IDs, depending on the DBMS being accessed.

See “Specifying IDs and passwords.”

password1 : password2

Text list. The passwords required by the user IDs.

See “Specifying IDs and passwords.”

table

Text. The name of the database table being accessed.

column

Text. The name of the column from which data is being retrieved.

null_handling

Text. Specifies how null values are treated when the data is retrieved.

See “Specifying null handling.”

“Distinct”

Keyword. Optional. Removes duplicate values from the list beforereturning data.

See “Specifying Distinct.”

sort

Keyword. Specify “Ascending” to sort the list of values into ascendingorder before it is returned; specify “Descending” to sort the list indescending order.

See “Specifying sort.”

196 Domino Designer Programming Guide, Volume 1: Formula Language

Return valuevaluesFound

Text, number, date-time, or a list of these types. The values found in thecolumn you indicated.

See “Accessing the values found,” later in this chapter.

Specifying NoCacheThe decision to use “NoCache” is based on performance. Forcing Notes toconnect to the database and retrieve the same information again and againtakes time, and slows overall performance. However, if you expect data tobe changing on a frequent basis, it’s worth the extra time to get up-to-dateinformation.

For example, if you’re using lookups to a database that stores customeraddresses, it’s generally safe to use caching because you don’t expect theaddresses to change very often. However, if you’re using a lookup to adatabase where stock prices are stored, and that database gets updatedhourly, it’s safer to omit caching and force a new lookup each time.

Note If you use the option button or the check-box user interface for akeywords field, Notes updates the keyword list only when the document iscomposed or is loaded for editing. If you use the Standard user interface forthe list, the keyword list is updated every time the document isrecalculated.

Specifying the data sourceThe data source name can contain up to 32 alphanumeric characters.

@DbLookup can access data sources that have already been registered inthe odbc.ini file (or similar registry on platforms other than Windows).

Specifying IDs and passwordsYou only need these arguments if your DBMS requires them.

Instead of storing the IDs in the @DbColumn formula, you can replace them with null strings (“”). If an ID is required, the user will be promptedfor it. This is useful when you do not want other designers to see IDs, orwhen you want users to enter their own IDs when accessing external data.However, you must include IDs and passwords in formulas that runautomatically (such as an agent) because these formulas don’t prompt forinformation.

The user IDs and passwords for accessing a data source are required onlyonce per Notes database session, as long as that database remains open. Ifthe user opens another Notes database and executes a formula that accessesthe same data source, the user ID and password will be required again.

Chapter 5: Formula Language @Functions A–Z 197

Password parameters are necessary only when ID parameters are specified.Like IDs, passwords can either be stored in the @DbColumn formula, orprompted for by substituting the null string. If the database password isnull, you can omit it from the formula.

For example, for the full ID/password specification, enter:

“”;“” (two null strings, separated by a semicolon) to specify no ID andpassword, or to prompt for both

“user_ID1”;“password1” to specify one user ID and passwordcombination

“user_ID1”:“user_ID2”;“password1”:“password2” to specify two userID and password combinations

Specifying the table nameYou can optionally include the name of the table’s owner to removeambiguity; use the format “owner_name.table_name”, with a period toseparate the owner name from the table name. For example:

"dbo.author"

Table can also refer to a database view in the DBMS being accessed.

Specifying null handlingNormally, null values are ignored and the resulting list is shortened (sameas using the Discard option described below).

To control how null values are handled, specify one of the following,appended to the column parameter with a colon:

“Fail” generates this error message if the column of data contains anynull values:Null values found - canceling @Db function

No data is returned with the message.

“Discard” discards the null values, thus shortening the returned list ofvalues. If one or more values are discarded when the @DbColumnformula is executed, you see this message on the status bar:Caution: NULL values discarded from @Db list.

“Replacement value” specifies a replacement value for null values. Thereplacement value must be a quoted string, but if the column is numericor date-time, the string must be convertible to that type.

If your formula includes a sort keyword, the list of values to bereturned is sorted before the replacement values are inserted. Duringsorting, all null values are placed at the beginning of the list for anascending sort; and at the end for a descending sort. They are not

198 Domino Designer Programming Guide, Volume 1: Formula Language

replaced until sorting is complete. This can result in a list that has somevalues sorted incorrectly. For example, if you specify “zzz” as yourreplacement value, all the “zzz” values will appear at the beginning ofthe list, even if you sorted it in ascending order.

If one or more values are replaced when the @DbColumn formula isexecuted, you see this message on the status bar:Caution: NULL value replaced with user-defined value in@Db list

Generally, the replacement value should be one that is not likely toappear in the list as valid data; for example, if the column is text, yourreplacement value might be “***” so that you can easily find thosevalues in Notes.

Specifying DistinctThe Distinct keyword is similar to @Unique in Notes, except that Distinctensures that duplicate values are removed before the data is returned. UsingDistinct instead of @Unique has two advantages:

The formula operates more quickly because the additional work isperformed outside of Notes.

You can potentially retrieve a larger amount of useful data intoNotes—since the duplicate values are removed at the back-end, moreunique values can be returned to Notes.

Note Distinct is not supported by all ODBC drivers. If there are null valuesin the data and you specify Distinct, one null is usually returned.

Specifying sortIf you use the Distinct keyword, you can append the sort parameter to itwith a colon. Use one of these keywords for the sort parameter to specifysorting of the return values:

Ascending sorts the list in ascending order.

Descending sorts the list in descending order.

If no sort keyword is specified, values are returned in arbitrary order.

Note The sort keywords are not supported by all ODBC drivers. If youattempt to use both Ascending and Descending in your formula, you see an“Invalid argument” message.

If multiple values are returned, they are formatted as a list and areseparated with the multi-value separator designated for the current field.

@DbColumn can return no more than 64KB of data. Use the followingequations to determine how much of your data can be returned with@DbColumn.

Chapter 5: Formula Language @Functions A–Z 199

For lookups that return text:

2 + (2 * number of entries returned) + total text size of all entries

Each text string is limited to 511 bytes; if only one text string isreturned, it is limited to 64KB.

For lookups that return numbers or dates:

(10 * number of entries returned) + 6

If the user’s notes.ini file includes the statement

NoExternalApps=1

the @DbColumn formula is disabled. The user will not see an errormessage; the formula fails to execute. This applies to @DbColumn onlywhen you use it with ODBC.

Usage@DbColumn is intended mainly for keyword formulas. Instead ofhard-coding a list of keywords and then periodically updating that list,@DbColumn allows you to dynamically retrieve a list of values from anexternal database table.

Examples: @DbColumn (ODBC)1. This formula retrieves from the inventory database the complete list of

colors in which your company’s uniforms are available. The data isstored like this:

Item Size Color

Shirt Small Red

Skirt Small Green

Sweater Medium Red

Trousers Medium Yellow

Use @DbColumn to retrieve the entire contents of the COLOR column(column 3):@DbColumn("OBDC";"INVENTORY";"";"";"UNIFORMS";"Color")

Values in the resulting list appear just as they were encountered in thedatabase; they are not sorted and duplicate values are retained:Red:Green:Red:Yellow

2. This example uses the sample “pubs” database that is included withMicrosoft SQL Server. The formula uses the ODBC SQL Server driver toaccess the database, locate the table called “authors” that is owned byuser “dbo”, and then retrieve the list of names in the “au_lname”

200 Domino Designer Programming Guide, Volume 1: Formula Language

column. The author names are sorted in ascending order; null valuesare discarded.@DbColumn("ODBC";"PUBLISHERS";"dbo";"vanilla";"dbo.authors"; "au_lname":"Discard";"Ascending")

@DbCommand (ODBC)Given data source information from the odbc.ini file (or equivalent), usesthis information to activate the appropriate ODBC driver. The driver thenlocates the specified DBMS, passes the specified command to it forprocessing, and returns the data retrieved by that command.

Note @DbCommand only works with ODBC data sources and only withSELECT statements. If used with statements that don’t retrieve a result set,@DbCommand simply transmits the statement. Use the ODBC capabilitiesof LotusScript for more extensive interaction.

Syntax@DbCommand( “ODBC” : “NoCache” ; data_source ; user_ID1 : user_ID2 ;password1 : password2 ; command_string : null_handling )

Parameters“ODBC”

Keyword. Indicates that you are accessing an ODBC data source.

“NoCache”

Keyword. Optional. If you want to ensure that Notes retrieves the latestinformation for every lookup, specify this option, as in“ODBC”:“NoCache”. Omit “NoCache” if you want the results of thelookup to be cached, that is, stored for re-use. Each subsequent lookup tothe same location within the same Notes session will re-use thatinformation, as long as the database executing the lookup remainsopen.

If you omit “NoCache”, you do not have to replace it withanything—the lookup results are cached automatically, but you canspecify “Cache” for readability. See “Specifying NoCache.”

data_source

Text. The name of the external data source being accessed. A datasource indicates the location of one or more database tables. See“Specifying the data source.”

Chapter 5: Formula Language @Functions A–Z 201

user_ID1 : user_ID2

Text list. The user IDs needed to connect to the external database. Youmay need up to two IDs, depending on the DBMS being accessed. See“Specifying IDs and passwords.”

password1 : password2

Text list. The passwords required by the user ID(s). See “Specifying IDsand passwords.”

command_string

Text. An SQL statement, command statement, or name of a procedureto be executed. See “Specifying a command string.”

null_handling

Text. Specifies how null values are treated when the data is retrieved.See “Specifying null handling.”

Return valuevaluesFound

Text, number, date-time, or a list of these types. The values returned bythe command_string. See “Accessing values found.”

Specifying NoCacheThe decision to use “NoCache” is based on performance issues. ForcingNotes to connect to the database and retrieve the same information againand again takes time, and slows overall performance. However, if youexpect data to be changing on a frequent basis, it’s worth the extra time toget up-to-date information.

For example, if you’re using lookups to a database that stores customeraddresses, it’s generally safe to use caching because you don’t expect theaddresses to change very often. But if you’re using a lookup to a databasewhere stock prices are stored, and that database gets updated hourly, it’ssafer to omit caching and force a new lookup each time.

Note If you use the option button or the check-box user interface for akeywords field, Notes updates the keyword list only when the document iscomposed or is loaded for editing. If you use the Standard user interface forthe list, the keyword list is updated every time the document isrecalculated.

Specifying the data sourceThe data source name can contain up to 32 alphanumeric characters.

@DbCommand can access data sources that have already been registered inthe odbc.ini file (or similar registry on platforms other than Windows).

202 Domino Designer Programming Guide, Volume 1: Formula Language

Specifying IDs and passwordsYou only need these arguments if your DBMS requires them.

Instead of storing the IDs in the @DbCommand formula, you can replacethem with null strings (“”). If an ID is required, the user will be promptedfor it. This is useful when you do not want other designers to see IDs, orwhen you want users to enter their own IDs when accessing external data.However, you must include IDs and passwords in formulas that will runautomatically (such as an agent) because these formulas don’t prompt forinformation.

The user IDs and passwords for accessing a data source are required onlyonce per Notes database session as long as that database remains open. Ifthe user opens another Notes database and executes a formula that accessesthe same data source, the user ID and password will be required again.

Password parameters are necessary only when ID parameters are specified.Like IDs, passwords can either be stored in the @DbColumn formula, orprompted for by substituting the null string. If the database password isnull, you can omit it from the formula.

For example, for the full ID/password specification, enter:

“”;“” (two null strings, separated by a semi-colon) to specify no ID andpassword, or to prompt for both

“user_ID1”;“password1” to specify one user ID and passwordcombination

“user_ID1”:“user_ID2”;“password1”:“password2” to specify two userID and password combinations

Note For complex connections, additional ID and password parametersmay be required to connect to the data source.

Specifying the command stringThe command_string can be any of the following:

An SQL statement (it must use the SQL syntax accepted by theback-end DBMS).

A command statement using the back-end DBMS command language.

The name of a procedure stored within the back-end DBMS (theprocedure contains one or more command strings that are activatedwhen the procedure is called by @DbCommand).

A date-time value must be entered in the format of the database, not that ofDomino; for example, use 1996-01-31-12.00.00 for DB2/2, not1996-01-31-12:00:00.

Chapter 5: Formula Language @Functions A–Z 203

Specifying null handlingTo control how null values are handled, specify one of the following,appended to the command_string parameter with a colon:

“Fail” generates this error message if the column of data contains anynull values:Null values found - canceling @Db function

No data is returned with the message.

“Discard” discards the null values, thus shortening the returned list ofvalues. If one or more values are discarded when the @DbCommandformula is executed, you see this message on the status bar:Caution: NULL values discarded from @Db list.

“Replacement value” specifies a replacement value for null values. Thereplacement value must be a quoted string, but if the column is numericor date-time, the string must be convertible to that type.

If your command string includes a sort keyword, the list of values to bereturned is sorted before the replacement values are inserted. Duringsorting, all null values are placed at the beginning or end of the list,depending on the driver. They are not replaced until sorting iscomplete. This can result in a list that has some values sortedincorrectly.

If one or more values are replaced when the @DbCommand formula isexecuted, you see this message on the status bar:Caution: NULL value replaced with user-defined value in@Db list

Generally, the replacement value should be one that is not likely toappear in the list as valid data; for example, if the column is text, yourreplacement value might be “***” so that you can easily find thosevalues.

Accessing values found@DbCommand can return no more than 64KB of data. Use the followingequations to determine how much of your data can be returned with@DbCommand.

For lookups that return text:

2 + (2 * number of entries returned) + total text size of all entries

Each text string is limited to 511 bytes; if only one text string isreturned, it is limited to 64KB.

For lookups that return numbers or dates:

(10 * number of entries returned) + 6

204 Domino Designer Programming Guide, Volume 1: Formula Language

If the user’s notes.ini file includes the statement

NoExternalApps=1

the @DbCommand formula is disabled. The user will not see an errormessage; the formula fails to execute.

Usage@DbCommand is useful for testing a non-equal relationship (such asless-than), or for testing multiple conditions at the same time. To use@DBCommands, you must pass a command to the back-end database forprocessing.

For example, to return data from records where

BALANCE >= 1000.00 and DAYS_OVERDUE > 30.

You can write the selection statement in SQL, and then use @DbCommandto pass that statement to the DBMS for processing; @DbCommand thenreturns the requested data.

For Web applications, you can use this function only with the syntax:

@DbCommand("Domino"',"ViewNextPage")

or

@Db Command("Domino"',"ViewPreviousPage")

to create a link to the next or previous page in a view. You cannot use@DbCommand in any other context with Web applications

Example: @DbCommand (ODBC)This formula uses the sample “pubs” database that is included withMicrosoft SQL Server. The formula uses an ODBC driver to access the datasource called PUBLISHERS, locate the table called “authors” that is ownedby user “dbo”, and then retrieve the list of names in the “au_lname”column for those authors who live in California and have a contract. Thestring CA is enclosed in single quotation marks, since it is alreadyembedded within a quoted command string.

@DbCommand("ODBC";"PUBLISHERS";"dbo":"";"vanilla":""; "SELECT au_lname FROM dbo.authors WHERE contract=1 ANDstate='CA' ")

Chapter 5: Formula Language @Functions A–Z 205

@DbExists

Given a server and file name, or replica ID, indicates whether the specifieddatabase exists.

Syntax@DbExists( server : file )

@DbExists( server ; replicaID )

Parametersserver

Text. The name of the server. Use an empty string (“”) to indicate thelocal computer.

file

Text. The path and file name of the database. Specify the database pathand file name using the appropriate format for the operating system.

replicationID

Text. The database’s replica ID

Return Valueflag

Number. Returns 1 (True) if the database exists. Returns 0 (False) if itdoes not exist.

UsageThis function does not work in column or selection formulas, or in agentsthat run on a server (mail and scheduled agents).

Examples: @DbExists1. This formula returns 1 if frites.nsf is in the mail directory on the server

Belgium. Otherwise it returns 0.@DbExists( "Belgium" : "mail\\frites.nsf" )

2. This formula checks if a database exists before opening it on theworkspace.server := @Subset( @MailDbName; 1 );file := "mail\\blah.nsf";@If( @DbExists( server : file ) ;@PostedCommand([FileOpenDatabase]; server : file );@Prompt([OK]; "Sorry"; "The database cannot be located onyour home server." ) )

206 Domino Designer Programming Guide, Volume 1: Formula Language

3. This formula uses a database’s replica ID instead of its file name:Exists := @DbExists("Cheshire";"852556DO:00576146");

@DbLookup (Notes databases)

Given a key value, looks in the specified view (or folder) and finds alldocuments containing the key value in the first sorted column within theview. For each selected document, @DbLookup returns either the contentsof a specified column in the view, or the contents of a specified field.

Syntax@DbLookup( class : “NoCache” ; server : database ; view ; key ; fieldName ) or@DbLookup( class : “NoCache” ; server : database ; view ; key ; columnNumber )

Parametersclass

Text. Indicates what type of database you are accessing. You canindicate a Notes database with either “” or “Notes”.

“NoCache”

Keyword. Optional. If you want to ensure that Notes retrieves the latest information for every lookup, specify this option, as in“Notes”:“NoCache”. Omit NoCache if you want the results of the lookup to be cached, that is, stored for re-use. Each subsequent lookup to the same location within the same Notes session will re-use thatinformation, as long as the database executing the lookup remainsopen.

If you omit “NoCache”, you do not have to replace it withanything—the lookup results are cached automatically.

server : database

Text list. The server location and file name of the database. See“Specifying the server and database.”

view

Text. The name of the view or folder in which to search. The view namemust exactly match the view’s full name as specified in the viewInfoBox (you can omit any synonyms). If the view cascades fromanother name on the menu, include that name too. See “Specifying theview name,” below.

Chapter 5: Formula Language @Functions A–Z 207

key

Text. Determines which document is actually read in order to retrieve avalue. A document’s key is the value displayed in the first sortedcolumn within the view. See “Specifying a key.”

fieldName

Text. The name of the field from which the data will be retrieved, oncethe correct document(s) has been identified. See “Specifying a fieldname” below.

columnNumber

Number. When you use a column number, Notes finds all documents inthe view that match the specified key, and returns whatever value isdisplayed in the indicated column for each of those documents,regardless of the formula used to display the data. See “Specifying thecolumn number.”

Return valuevaluesFound

Text, numbers, date-time, or text-list. The values found in the fieldNameor column you indicated. See “Accessing the values found,” later in thischapter.

Specifying “NoCache”The decision to use “NoCache” is based on performance. Forcing Notes toconnect to the database and retrieve the same information again and againtakes time, and slows overall performance. However, if you expect data tobe changing on a frequent basis, it’s worth the extra time to make sureyou’re getting up-to-date information.

For example, if you’re using lookups to a database that stores customeraddresses, it’s generally safe to use caching because you don’t expect theaddresses to change very often. But if you’re using a lookup to a databasewhere stock prices are stored, and that database gets updated hourly, it’ssafer to skip the caching and force a new lookup each time.

Specifying the server and databaseThere are several ways to specify the server : database parameter:

To perform the lookup on the current database (the same database inwhich the formula is being evaluated), specify “” as the entire argumentto the function. Agents running on a server can only perform lookups todatabases on that same server. That is, “” means the local Notesdirectory where you are executing and if you happen to have an agentexecuting on a server, the agent cannot do lookups off the server.

208 Domino Designer Programming Guide, Volume 1: Formula Language

To perform a lookup on a local database, use “” for the server name andspecify the database name explicitly, such as “”:“database.nsf”.

To perform a lookup (from the workstation) on a Notes database thatresides on a server, include the server plus the path and file name as atext list, as in “server”:“database.nsf”.

If there are multiple copies of the database located on various Dominoservers, using the database replica ID in place of both the server anddatabase name lets you access a replica copy of that database withouthaving to specify either the server name or the database name. Forexample, if you use “85255CEB:0032AC04” (a database replica ID,found in the database InfoBox) as the database name, Notes uses areplica of the database to retrieve the information.

Notes searches for replicas in this order, using the first replica itencounters:

Workspace

If there is one replica on your workspace, Notes uses it.

If there are multiple, stacked replicas on your workspace, Notes usesthe replica on top of the stack.

If there are multiple, unstacked replicas on your workspace, Noteslooks for an icon matching your current server and uses that. If noneof the icons matches your current server, Notes uses the icon thatwas added to your workspace first.

Current server

Locally (your hard disk)

Once a replica is located, it’s added to your workspace to save time onfuture lookups.

Tip To avoid typing errors in the replica ID, choose File - Database -Design Synopsis and select Replication. Then copy the replica ID from thesynopsis and paste it into your formula.

Note If your database is located in a DOS or OS/2 subdirectory, such asmail\mine.nsf, put a double backslash between the directory and thedatabase name, as in “mail\\mine.nsf” because formulas treat singlebackslashes as escape characters.

Specifying a viewYou can specify a view parameter using either the full name of the view (orfolder) or its synonym. For example, if your Last Name view is cascadedfrom By Author in the View menu, and has the synonym |LName, it lookslike this in the view InfoBox:

By Author\Last Name|LName

Chapter 5: Formula Language @Functions A–Z 209

When you reference this view with @DbLookup, you can just use theLName synonym, enclosed in quotation marks:

“LName”

If the view name doesn’t have a synonym, you use the By Author nameplus the Last Name cascade, again enclosed in quotation marks (butwithout the synonym). And since the view name is used in a formula, the“\” must be preceded with an additional “\” to ensure that Notesinterprets it correctly:

“By Author\\Last Name”

Specifying a keyYou can only test for values that match the key (equality); there is no way tospecify a different operator such as < (less-than)

Rather than specify a particular key to match, you generally want to use afield name, so Notes looks up a value based on that field’s contents withinthat particular document. For example, if you specify the field LastName asthe key (Notes knows it’s a field because there are no quotation marksaround it), then whenever the @DbLookup formula is executed, the currentvalue of the LastName field is used as the lookup criterion. This method letsyou use the lookup formula in a field, when you cannot predict what valueswill be entered in other fields.

The match between the lookup key and the value in the sort column mustbe exact—capitalization doesn’t matter, but spacing and punctuation mustbe precise.

The view must contain a sorted column in order for the lookup to work;otherwise a null value is returned. Results are not accurate for a multi-valuefield that is sorted but not categorized.

Specifying a field nameWhen you use a fieldName to perform a lookup, the value returned is thevalue that is actually stored in the field; it may be different from whatdisplays in the view. Notes can retrieve data from any field in anydocument displayed in the specified view, but if the field isn’t displayed asa view column, Notes must search the entire document to find the field,which may result in a slower lookup. You cannot retrieve data from a richtext field using @DbLookup.

Some of the documents matching the key may not even contain thespecified field if they were created using different forms.

210 Domino Designer Programming Guide, Volume 1: Formula Language

Specifying the column numberLookups based on view columns are more efficient than those based onfields not included in the view. For best results, you should include thedesired field in the view.

For example, if your view is categorized by product ID and you specify“01776” as the lookup key and 2 as the column, Notes returns whatever is displayed in column 2 for all documents categorized under product ID 01776.

To specify a columnNumber parameter, you count the view’s columns fromleft to right, with the leftmost column being number 1. Because of the wayNotes indexes views, however, not every column is counted for the lookup.

Use this method to calculate the column number for lookup purposes:

1. Count the columns in the view, from left to right.

Be sure you don’t miss any columns, for example, a column used forsorting or categorizing the view may not show up. Look at the view indesign mode to make sure you see all its columns.

2. Discount all columns that display a constant value, such as 32 or“Submitted by: ”. If a column contains a formula that happens to returnthe same result for every document, it is not considered a “constant” sobe sure to include it in your column count.

3. Discount all columns that consist solely of the following @functions:@DocChildren, @DocDescendants, @DocLevel, @DocNumber,@DocParentNumber, @DocSiblings, @IsCategory, @IsExpandable.

4. Now re-count the columns, working from left to right.

This revised column number is the value to specify in the lookup formula.

Note If you choose to use a column number instead of a field name in an@DbLookup formula, you can only retrieve data that actually appears in the view.

Accessing the return valuesIf multiple values are returned by @DbLookup, they are formatted as a listand are separated with the multi-value separator designated in the currentfield’s InfoBox.

@DbLookup can return no more than 64KB of data. Use the followingequations to determine how much of your data can be returned with@DbLookup.

For lookups that return text:

2 + (2 * number of entries returned) + total text size of all entries

Chapter 5: Formula Language @Functions A–Z 211

For lookups that return numbers or dates:

(10 * number of entries returned) + 6

UsageThis function does not work in column or selection formulas, or in mail agents.

Server agents and securityConsider the database containing @DbLookup the source database, and thedatabase being accessed the target database.

When @DbLookup is used in an agent that runs on a server, it can onlyaccess target databases stored on the same server as the source database.The source database must have at least Reader access to the target database.

If it is not possible to assign Reader access or better to the -Default- groupfor security reasons, it is still possible to grant the source database’s@DbLookup macros access to the target database.

1. Use File - Database - Properties to determine the Replica ID of thesource database, for example: 85255CEB:0032AC04.

2. Use File - Database - Access Control on the target database, add a new entry whose name is the Replica ID itself, and give that name atleast Reader access. In the above example, you’d add an entry with thename 85255CEB:0032AC04. By doing this, you’re specifically grantingthe macros in the source database access to the target database, even if -Default- has No Access.

Other agents and securityWhen @DbLookup is used in any other type of formula or agent, it hasunlimited access to any target database stored on the user’s ownworkstation. If the target database is stored on another Domino server,@DbLookup’s access is determined by the user’s own access level (based onthe user’s Notes ID).

@DbLookup is not subject to the Read Access list for a view; so long as it has Reader access to the target database, it can retrieve data from allshared views.

Examples: @DbLookup (Notes databases)1. Your organization maintains employee office location and

department information in the Person documents in the public Name & Address Book.

You might have a Purchasing application where employees fill outPurchase Requests for office supplies. You can have your Notes

212 Domino Designer Programming Guide, Volume 1: Formula Language

application look up this information and automatically insert it into documents.

Mary Tsen composes a Purchase Order. The P.O. Number, Date, andRequested By fields are filled in automatically by Notes. Mary fills inthe details of the purchase order: quantity, part number, and so on.

When Mary saves the Purchase Order, the delivery information in thelower half of the document is calculated using a series of @DbLookupformulas to retrieve information about that user from the public Name & Address Book:

This is accomplished by using computed fields and writing a lookupformula for each field to be retrieved (Location and Telephone). Forexample, the formula for the Location field would be:@DbLookup("";"Purchasing":"Names.NSF";"People";@Right(RequestedBy; "");"Location")

This formula instructs Notes to open the Name & Address Book(NAMES.NSF) on the Purchasing server, locate the People view, andthen locate the person whose last name matches the last name in thepurchase order’s RequestedBy field. Once the correct document hasbeen located, Notes copies the information from the Person document’sLocation field into the purchase order Location field.

A similar formula then copies Mary’s telephone number from thePerson record OfficePhoneNumber field into the purchase order Phone field.

Note For the DeliverTo field, Mary’s name is determined when thedocument is composed, using @UserName.

2. Using the Name & Address Book again, you want to retrieve a list ofoffice telephone numbers for everyone in the Purchasing department.

You could use @DbLookup with the key “Purchasing” to retrieve theOfficePhoneNumber field, and Notes would return the telephonenumber for every employee with “Purchasing” entered in theDepartment field of their Person record. The phone numbers arereturned as a text list, using the selected multi-value separator for the field.

3. This formula returns the value stored in the Status field of the VirusCheck document, which is accessed via the In Progress view of thePROJECTS.NSF database stored in the SMITH subdirectory on theRESEARCH server. The information will not be cached, so if this

Chapter 5: Formula Language @Functions A–Z 213

formula is evaluated again during the same Notes session, a newlookup will be performed to ensure that the status retrieved is up to date.@DbLookup("":"NoCache";"RESEARCH":"SMITH\\PROJECTS.NSF";"In Progress";"Virus Check";"Status")

@DbLookup (ODBC)Uses data source information from the odbc.ini file to activate theappropriate ODBC driver. The driver then locates the specified DBMS,table, and column, and returns only the values in that column belonging torecords whose value in the key column matches the specified key. You canoptionally specify whether the returned list of values is sorted, whetherduplicate values are deleted, and how null values are handled.

Note @DbLookup can only retrieve data; it can’t add, delete, or modifydata.

Syntax@DbLookup( “ODBC” : “NoCache” ; “data_source” ; “user_ID1” :“user_ID2” ; “password1” : “password2” ; “table” ; “column” : “null_handling” ;“key_column” ; “key” ; “Distinct” : “sort” )

Parameters“ODBC”

Keyword. Indicates that you are accessing an ODBC data source.

“NoCache”

Keyword. Optional. If you want to ensure that Notes retrieves the latest information for every lookup, specify this option, as in“ODBC”:“NoCache”. Omit “NoCache” if you want the results of thelookup to be cached, that is, stored for re-use. Each subsequent lookup to the same location within the same Notes session will re-use thatinformation, so long as the database executing this lookup remainsopen.

If you omit “NoCache”, you do not have to replace it withanything—the lookup results are cached automatically, but you can specify “Cache” for readability. See “Specifying NoCache.”

“data_source”

Text. The name of the external data source being accessed. A datasource indicates the location of one or more database tables. See“Specifying the data source.”

214 Domino Designer Programming Guide, Volume 1: Formula Language

“user_ID1” : “user_ID2”

Text-list. The user IDs needed to connect to the external database. Youmay need up to two IDs, depending on the DBMS being accessed. See“Specifying IDs and passwords.”

“password1” : “password2”

Text list. The passwords required by the user IDs. See “Specifying IDsand passwords.”

“table”

Text. The name of the database table being accessed.

“column”

Text. The name of the column from which data is being retrieved.

“null_handling”

Text. Specifies how null values are treated when the data is retrieved.See “Specifying null handling.”

“key_column”

Text. The name of the column used for key matching.

“key”

Text, number, or date-time, or a list. The value to be looked up inkey_column. Use the Notes type that agrees with the type of the keycolumn in the data source.

“Distinct”

Keyword. Optional. Removes duplicate values from the list beforereturning data. See “Specifying Distinct.”

“sort”

Keyword. Sorts the list of values into either ascending or decendingorder before it is returned. See “Specifying sort.”

Return valuevaluesFound

Text, number, date-time, or a list of these types. The values found in thecolumn you indicated. See “Accessing the values found”, later in thischapter.

Specifying NoCacheThe decision to use “NoCache” is based on performance. Forcing Notes toconnect to the database and retrieve the same information again and againtakes time, and slows overall performance. However, if you expect that data

Chapter 5: Formula Language @Functions A–Z 215

to be changing on a frequent basis, it’s worth the extra time to get updatedinformation.

For example, if you’re using lookups to a database that stores customeraddresses, it’s generally safe to use caching because you don’t expect theaddresses to change very often. But if you’re using a lookup to a databasewhere stock prices are stored, and that database gets updated hourly, it’ssafer to omit caching and force a new lookup each time.

Note If you use the option button or the check box user interface for akeywords field, Notes updates the keyword list only when the document is composed or opened for editing. If you use the Standard user interfacefor the list, the keyword list is updated every time the document isrecalculated.

Specifying the data sourceThe data source name can contain up to 32 alphanumeric characters.

Specifying IDs and passwordsYou only need these arguments if your DBMS requires them.

Instead of storing the IDs in the @DbLookup formula, you can replace themwith null strings (“”). If an ID is required, the user will be prompted for it.This is useful when you do not want other designers to see IDs, or whenyou want users to enter their own IDs when accessing external data.However, you must include IDs and passwords in formulas that will runautomatically (such as an agent) because those formulas don’t prompt forinformation.

The user IDs and passwords for accessing a data source are required onlyonce per Notes database session as long as that database remains open. Ifthe user opens another Notes database and executes a formula that accessesthe same data source, the user ID and password will be required again.

Password parameters are necessary only when ID parameters are specified.Like IDs, passwords can either be stored in the @DbLookup formula, orprompted for by the ODBC driver by substituting the null string. If thedatabase password is null, you can omit it from the formula.

For example, for the full ID/password specification, enter:

“”;“” (two null strings, separated by a semi-colon) to specify no ID andpassword, or to prompt for both

“user_ID1”;“password1” to specify one user ID and passwordcombination

“user_ID1”:“user_ID2”;“password1”:“password2” to specify two userID and password combinations

216 Domino Designer Programming Guide, Volume 1: Formula Language

Specifying the table nameIf the DBMS supports it, you can optionally include the name of the table’sowner to remove ambiguity. Use the format “owner_name.table_name”,with a period separating the owner name and the table name.

For example:

"dbo.author"

Table can also refer to a database view in the DBMS being accessed.

Specifying null handlingTo control how null values are handled, specify one of the following,appended to the column parameter with a colon:

“Fail” generates this error message if the column of data contains anynull values:Null values found - @Db function

No data is returned with the message.

“Discard” discards the null values, thus shortening the returned list ofvalues. If one or more values are discarded when the @DbLookupformula is executed, Notes displays this message on the status bar:Caution: NULL values discarded from @Db list.

“Replacement value” specifies a replacement value for null values. Thereplacement value must be a quoted string, but if the column is numericor date-time, the string must be convertible to that type.

If your formula includes a sort keyword, the list of values to bereturned is sorted before the replacement values are inserted. Duringsorting, all null values are placed at the beginning of the list for anascending sort, and at the end for a descending sort. They are notreplaced until sorting is complete. This can result in a list that has somevalues sorted incorrectly. For example, if you specify “zzz” as yourreplacement value, all those “zzz” values will appear at the beginningof the list even though you sorted it by ascending order.

If one or more values are replaced when the @DbLookup formula isexecuted, Notes displays this message on the status bar:Caution: NULL value replaced with user-defined value in@Db list

Generally, the replacement value should be one that is not likely toappear in the list as valid data; for example, if the column is text, your replacement value might be “***” so that you can easily find those values.

Chapter 5: Formula Language @Functions A–Z 217

Specifying key_column and keyUse “key_column” to indicate which column to search for the specified“key”; enclose the column name in quotation marks. If the DBMS productuses case-sensitive column names, be sure to use the correct capitalization.The values in the key column do not have to be sorted before you retrievedata with @DbLookup.

Specify a value using the Notes type that agrees with the key column in thedata source. For example, specify a number or a number-valued expressionwhen the key column is of any numeric type, such as integer, real, float, ordouble. If the key is a string (text) value, enclose it in quotation marks. Adate-time value must be entered in the format of the database, not that ofDomino; for example, use 1996-01-31-12.00.00 for DB2/2, not1996-01-31-12:00:00.

Together, the key column and the key form the “where” clause of a selection statement:

"SELECT column WHERE key_column = key"

The ODBC Application Interface always tests for equality and only returnsdata from records where the value in the key column exactly matches thekey. To test whether the value in the key column matches one of severalpossible values, format the key value as a list, separating items with colonsas in “Red”:“Blue”:“Green.” This acts like an OR operation, returning datafrom all records where the value in the key column matches “Red” OR“Blue” OR “Green.” To perform an AND operation or to test for inequality,use @DbCommand to pass the appropriate command string to the DBMS.Also use @DbCommand to pass the appropriate command string if the key is a time-date value, because @DbLookup does not always convert the time-date value to the correct format for time-dates in the DBMScommand language.

If you cannot get @DbLookup to return the correct values due to typing orother problems, try using a SELECT statement in @DbCommand.

Specifying DistinctThe Distinct keyword is similar to @Unique in Notes, except that Distinctensures that duplicate values are removed before the data is returned toNotes. Using Distinct instead of @Unique has two advantages:

The formula operates more quickly because the additional work isperformed outside of Notes.

You can potentially retrieve a larger amount of useful data intoNotes—since the duplicate values are removed at the back-end, moreunique values can be returned to Notes.

218 Domino Designer Programming Guide, Volume 1: Formula Language

Note Distinct is not supported by all ODBC drivers. If there are null valuesin the data and you specify Distinct, one null is usually returned.

Specifying sortIf you use the Distinct keyword, you can append the sort parameter to itwith a colon. Use one these keywords for the sort parameter to specifysorting of the return values:

“Ascending” sorts the list in ascending order.

“Descending” sorts the list in descending order.

If no sort keyword is specified, values are returned in arbitrary order.

Note The sort keywords are not supported by all ODBC drivers. If youattempt to use both Ascending and Descending in your formula, Notesdisplays an “Invalid argument” message.

Accessing values foundIf multiple values are returned, they are formatted as a list and areseparated with the multi-value separator designated for the current field.

@DbLookup can return no more than 64KB of data. Use the followingequations to determine how much of your data can be returned with@DbLookup.

For lookups that return text:

2 + (2 * number of entries returned) + total text size of all entries

Each text string is limited to 511 bytes; if only one text string isreturned, it is limited to 64KB.

For lookups that return numbers or dates:

(10 * number of entries returned) + 6

If the user’s notes.ini file includes the statement:

NoExternalApps=1

the @DbLookup formula is disabled. The user will not see an error message;the formula fails to execute. This applies to @DbLookup only when you useit with ODBC.

Usage@DbLookup is intended mainly for keyword formulas. Instead ofhard-coding a list of keywords and then periodically updating that list,@DbLookup lets you dynamically retrieve a list of values from an externaldatabase table.

@DbLookup can’t be used in mail macros, although it does work in paste macros.

Chapter 5: Formula Language @Functions A–Z 219

Examples: @DbLookup (ODBC)1. This formula retrieves from the inventory database the complete list

of colors in which company uniforms are available. The data is storedlike this:

Item Size Color

Shirt Small Red

Skirt Small Green

Sweater Medium Red

Trousers Medium Yellow

To retrieve the entire contents of the color column (column 3) for allrecords where the first sorted column (column 1, ITEM) contains“Shirt” or “Trousers”:@DbLookup("OBDC"; "INVENTORY"; ""; ""; "UNIFORMS";"Color"; "Item"; "Shirt" : "Trousers")

Since multiple records contain at least one of the keys, the result is a list:Red:Yellow

Values in the resulting list appear just as they were encountered in thedatabase; they are not sorted and duplicate values are retained.

This example uses the sample “pubs” database that is included withMicrosoft SQL Server. The formula uses an ODBC driver to access the datasource called PUBLISHERS and locate the table called “authors” that isowned by user “dbo”. In this table, the values in the “state” column arecompared with the values “CA” and “TN”. For every record whose statefield contains either “CA” or “TN”, the values stored in the “au_lname”field are returned. The author names are sorted in ascending order; nullvalues are discarded.

@DbLookup("ODBC";"PUBLISHERS";"dbo";"vanilla";"dbo.authors"; "au_lname":"Discard";"state";"CA":"TN";"Ascending")

@DbManagerReturns a list of users, groups, and servers who currently have Manageraccess to the database. In a window title formula, only the name of the firstmanager listed in the ACL is displayed.

@DbManager does not work in selection formulas or column formulas.

220 Domino Designer Programming Guide, Volume 1: Formula Language

Syntax@DbManager

Return valuemanagers

Text or text list. The users, groups, and servers that have manageraccess.

Examples: @DbManager1. This example returns “Gerald Brown” if Gerald Brown is the only user

with Manager access to the current database.@DbManager

2. This example returns “Gerald Brown;Supervisors” if Gerald Brown anda group called Supervisors have Manager access to the currentdatabase.@DbManager

3. This example returns “GERALD BROWN;LOIS BOYD” if GeraldBrown and Lois Boyd are the two users with Manager access to thecurrent database.@UpperCase(@DbManager)

@DbNameReturns the name of the current Notes server and database.

Syntax@DbName

Return valueserver ; path

Text list with two elements:

server is the hierarchical name of the server on which the currentdatabase resides, or an empty string (“”) if the database is local. Use@Name to extract a part of the name; for example, [CN] to extract thecommon name.

path is the path and file name of the database.

Chapter 5: Formula Language @Functions A–Z 221

Examples: @DbNameThese examples assume the semicolon is the selected separator.

1. This example returns “;personal.nsf” if the current document is in thepersonal database stored in the data directory of the user’s owncomputer.@DbName

2. This example returns “sales1;admin\status.nsf” if the current documentis stored in a Notes database named status.nsf in the admin directoryon the sales1 server. If the database is stored at the server’s rootdirectory (that is, it is not stored in a subdirectory), the result would be“sales1;status.nsf.” You can extract just the file name of the list bycombining @DbName with @Subset, as shown in the example below.@DbName

3. This example returns “status.nsf”, the file name, since this is the lastelement in the returned list.@Subset(@DbName;-1)

4. This example returns the path of the current database, without the filename. For example, if the current database is senses\sounds\sigh.nsf,this formula returns “senses\sounds.”@LeftBack(@Subset(@DbName;-1);"\\")

5. This example displays the server, path, and file name of the currentdatabase, substituting the common name for the hierarchical name ofthe server.database := @Subset(@DbName; -1);server := @Name([CN]; @Subset(@DbName; 1));@Prompt([OK]; "Database name"; @Implode(server) + " " +@Implode(database))

@DbTitleReturns the title of the current database.

Syntax@DbTitle

Return valuetitle

Text. The title of the current database.

222 Domino Designer Programming Guide, Volume 1: Formula Language

Example: @DbTitleThis form action formula uses @DbTitle to let the user create and send ane-mail memo to the author of the current document. @DbTitle is used in thememo’s Subject.

return:=@Char(13);memobody:=@Prompt([OKCANCELEDIT]; "Mail message"; "Enter the contents of your mail message below." + return + "It will be sent to " + From + "."; "" );@MailSend(From; ""; ""; "Your posting in " + @DbTitle; "";memobody:return; [IncludeDoclink])

@DDEExecutePasses the specified command string to the DDE application, which isidentified by the conversation ID. @DDEExecute is always used inconjunction with @DDEInitiate and @DDETerminate.

Note DDEExecute is not supported by UNIX or on the Macintosh.

Syntax@DDEExecute( conversationID ; command )

ParametersconversationID

The conversationID is returned by the @DDEInitiate function, whichmust precede the use of @DDEExecute. Use your own variable name;that’s how you pass the conversation ID between Notes and the otherapplication. If the conversation ID is invalid, Notes returns an error. See@IsError.

command

Text. The command must be a text string that adheres to the syntax rulesof the receiving application (see that application’s documentation).Enclose the command in quotation marks so it can be passed intact tothe DDE application; that application will then interpret it as a DDEcommand.

Return valueacknowledgment

Number. Returns @True (1) if the DDE command is successfullyexecuted; if not, returns @False(0). If the conversation ID is invalid, anerror is returned.

Chapter 5: Formula Language @Functions A–Z 223

UsageThis function is intended for use primarily in field formulas and agents,buttons, and SmartIcons. It does not work in column or selection formulas,and is not intended for use in window title or form formulas. Since theMacintosh does not support DDE, these commands will not work onMacintosh workstations. In addition, the format of the DDE commands mayvary somewhat with each platform or application.

If the user’s notes.ini file includes the statement:

NoExternalApps=1

then any formula involving @DDE functions is disabled. The user doesn’tsee an error message; the formula fails to execute.

You can have up to 10 DDE conversations running concurrently, althoughunder normal circumstances you should only have 1 conversation runningat a time. Be sure to terminate all DDE conversations once they’recompleted, or you may run out of sessions and be unable to initiate moreconversations when needed.

You cannot use this function in Web applications.

Example: @DDEExecuteThis formula conducts a DDE conversation between 1-2-3 for Windowsand Notes.

Conv_ID := @DDEInitiate("123W";"Budget95.wk3");@If (@IsError(Conv_ID); @Do(@Prompt([Ok];"Error"; "Unable to initiate conversation");@Return(""));@Do(@DDEPoke(Conv_ID;"A:B6"@Text(Amount));@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B6~\")]");@DDEExecute(Conv_ID;"[RUN(\"/rfc~~\")]");@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B10~{Edit-Copy}\")]");@DDETerminate(Conv_ID);@Command([EditNextField]);@Command([EditPaste])))

The line-by-line explanations:

Conv_ID := @DDEInitiate("123W";"Budget95.wk3");

Initiates a conversation between Notes and 1-2-3. This statement specifieswhich worksheet to use (budget95.wk3) and stores the conversation ID inthe variable Conv_ID. Note that the specified file must be open before the@DDEInitiate is executed.

224 Domino Designer Programming Guide, Volume 1: Formula Language

@If (@IsError(Conv_ID); @Do(@Prompt([Ok];"Error"; "Unable toinitiate conversation"); @Return(""));

Determines whether the DDE conversation was successfully initiated. If itwas, the formula continues; if it wasn’t, a message appears, and the formulastops executing.

@Do(@DDEPoke(Conv_ID;"A:B6";@Text(Amount));

Converts the contents of the numeric Amount field to text, and then passesthat value to cell A:B6 in the 1-2-3 worksheet. The value must be convertedto text because only text can be passed via DDEPoke.

@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B6~\")]");

Makes cell A:B6 the current location in the worksheet.

@DDEExecute(Conv_ID;"[RUN(\"/rfc~~\")]");

Passes the Range, Format, Currency command to 1-2-3; cell A:B6 is nowformatted for currency values.

@DDEExecute(Conv_ID;"[RUN(\"{Goto}A:B10~{Edit-Copy}\")]");

Passes the Goto and Edit Copy commands to 1-2-3; cursor is moved to cellA:B10 within the worksheet and the value stored in that cell is copied to theWindows Clipboard.

@DDETerminate(Conv_ID);

Terminates the DDE conversation.

@Command([EditNextField]);

Navigates to the next field within the current Notes document.

@Command([EditPaste])))

The contents of the Clipboard (the value from cell A:B10) are pasted intothat field.

@DDEInitiate

Initiates a conversation with a DDE server, and returns the conversation ID.

Note DDEInitiate is not supported by UNIX or on the Macintosh.

Syntax@DDEInitiate( application ; topic )

Chapter 5: Formula Language @Functions A–Z 225

Parametersapplication

Text. The name of the application you want to initiate a DDEconversation with. This application must be launched before you call@DDEInitiate. The values for application and topic vary from oneapplication to another; the appropriate values can usually be found inthe index for the application’s documentation, under “DDE.”

topic

Text. The data file you want to use. This file must be opened before youcall @DDEInitiate.

Return valueconversationID

This ID identifies the particular DDE conversation so you can passcommands and data to it with @DDEExecute and @DDEPoke, andeventually terminate the conversation with @DDETerminate. Returnsan error if the conversation cannot be inititated. See @IsError.

UsageIt is intended for use primarily in field formulas and agents, buttons, andSmartIcons. Since the Macintosh does not support DDE, these commandswill not work on Macintosh workstations. This function does not work incolumn or selection formulas, and is not intended for use in window title orform formulas.

If the user’s notes.ini file includes the statement

NoExternalApps=1

then any formula involving @DDE functions is disabled. The user doesn’tsee an error message; the formula fails to execute.

You can have up to 10 DDE conversations running concurrently, althoughunder normal circumstances you should only have 1 conversation runningat a time. Be sure to terminate all DDE conversations once they’recompleted, or you may run out of sessions and be unable to initiate moreconversations when needed.

You cannot use this function in Web applications.

226 Domino Designer Programming Guide, Volume 1: Formula Language

Initiation failuresIf the conversation cannot be initiated, @DDEInitiate will return an error.See @IsError. Below are some reasons why the initiation could fail:

The workstation operating system does not support DDE (Macintosh).

The DDE application you’re trying to set up a conversation with is notrunning. The specified file is not open.

The DDE application is running, but the specified topic is not open orthe application does not support the topic specified with @DDEInitiate.

The DDE application is running, but the specified file does not open.

The maximum number of concurrent DDE conversations has beenreached (currently, the maximum is 10).

@DDEPokeDeposits unsolicited data into the specified location within the DDE serverapplication. If the data was successfully inserted into the target location,@DDEPoke returns an ACK (acknowledgement) with the value @True(1); ifthe attempt was not successful, the call returns a NACK (negativeacknowledgement) with the value @False(0). If the conversation ID isinvalid, an error is returned (see @IsError).

Note DDEPoke is not supported by UNIX or on the Macintosh.

Syntax@DDEPoke( conversationID ; location ; data )

ParametersconversationID

The conversationID is returned by @DDEInitiate.

location

Text. The name of the location where you want to place the data. Thelocation must be a cell, range, or field name; enclose it in quotationmarks.

data

Text. Optional. The data you want to place at location. If you want topass the contents of a non-text field, use @Text to convert it to text first.If data is a text list, only the first value in the list gets passed. If you omitdata, Notes passes the contents of the Windows Clipboard to thereceiving application. If you supply the data as a parameter, eitherenclose it in quotation marks or specify a Notes field name.

Chapter 5: Formula Language @Functions A–Z 227

UsageIt is intended for use primarily in field formulas and agents, buttons, andSmartIcons. Since the Macintosh does not support DDE, these commandswill not work on Macintosh workstations. This function does not work incolumn or selection formulas, and is not intended for use in window title orform formulas.

If the user’s notes.ini file includes the statement

NoExternalApps=1

then any formula involving @DDE functions is disabled. The user doesn’tsee an error message; the formula fails to execute.

You cannot use this function in Web applications.

@DDETerminateTerminates the conversation with a DDE application.

Note DDETerminate is not supported by UNIX or on the Macintosh.

Syntax@DDETerminate( conversationID )

ParametersconversationID

The conversationID is returned by @DDEInitiate. Use the sameconversationID you used with the@DDEInitiate and @DDEExecutecommands.

Return valuestatus

Returns an error if the conversationID is invalid. If valid, returnsnothing. See @IsError.

UsageIt is intended for use primarily in field formulas and agents, buttons, andSmartIcons. Since the Macintosh does not support DDE, these commandswill not work on Macintosh workstations.This function does not work incolumn or selection formulas, and is not intended for use in window title orform formulas.

If the user’s notes.ini file includes the statement

NoExternalApps=1

228 Domino Designer Programming Guide, Volume 1: Formula Language

then any formula involving @DDE functions is disabled. The user doesn’tsee an error message, the formula fails to execute. Be sure to terminate allDDE conversations once they’re completed, or you may run out of sessionsand be unable to initiate more conversations when needed.

You cannot use this function in Web applications.

DEFAULT

Does one of the following:

Assigns a default value to a field.

Says that for the duration of the computation of this formula, if adocument does not have this field, act as though it does with this as itsvalue.

Allows you to assign values that provide dynamic defaults to fields.

SyntaxDEFAULT variableName := value ;

UsageThis keyword works in any formula.

Example: DEFAULTThese two formulas display the value in the field named KeyThought, ifthat field exists; otherwise, the value in the field Topic is displayed. UsingDEFAULT lets you write a simpler formula that is less prone to error, andeasier for others to understand.

@If(@IsAvailable(KeyThought);KeyThought;Topic);

and

DEFAULT KeyThought := Topic;KeyThought;

@DeleteDocument

In an agent that runs a formula, deletes the document currently being processed.

Syntax@DeleteDocument

Chapter 5: Formula Language @Functions A–Z 229

UsageThis function is intended only for use in agents that run formulas; it has noeffect when run elsewhere.

To mark a document for deletion from an icon or view or form action, use@Command[EditClear].

To create an agent that deletes documents from a database without using aformula, select the action Delete from database in the Agent Builder.

You cannot use this function in Web applications.

Example: @DeleteDocumentThis example deletes only those documents where the Status field equals “Closed.”

FIELD Status:=@If(Status="Closed";@DeleteDocument;Status)

@DeleteFieldIn an agent that runs a formula, @DeleteField deletes the specified field.

Syntax@DeleteField

UsageThis function is most useful in agents that run formulas. It does not work incolumn or selection formulas, and is not intended for use in window title orform formulas.

Example: @DeleteFieldThis example deletes the field named RoutingList from each document thatis processed by the macro.

FIELD RoutingList:=@DeleteField;

This statement is equivalent to:

FIELD RoutingList:=@Unavailable;

@DialogBoxBrings up a dialog box that displays the current document using a form youspecify. The user interacts with the form and document as usual, selectingOK or Cancel when finished.

230 Domino Designer Programming Guide, Volume 1: Formula Language

Syntax@DialogBox( form ; [AutoHorzFit] : [AutoVertFit] : [NoCancel] :[NoNewFields] : [NoFieldUpdate] : [ReadOnly] ; sizeToTable ; noOkCancel ;title )

Parametersform

Text. The name of the form.

[AutoHorzFit]

Keyword. Optional. Scales the dialog box horizontally to fit the layoutregion.

[AutoVertFit]

Keyword. Optional. Scales the dialog box vertically to fit the layout region.

[NoCancel]

Keyword. Optional. Displays the dialog box with only an OK button. Ifthis keyword is omitted, the dialog box contains OK and Cancelbuttons.

[NoNewFields]

Keyword. Optional. Do not add fields to the underlying document thatare in the dialog box form but not the underlying form.

[NoFieldUpdate]

Keyword. Optional. Do not pass edits from the fields in the dialog boxto the underlying document (for example, if you’re passing the editssomewhere else in a Queryclose script for the dialog box form).

[ReadOnly]

Keyword. Optional. Prohibits writing to the dialog box (for example, ifyou are using the dialog box to display a help screen). If this keyword isomitted, the dialog box is read-write. Use of this keyword implies[NoCancel].

sizeToTable

Note This parameter is new with Release 5.

Boolean. Optional. Specify True if you want to scale a table to fit intothe dialog box. If you specify False or omit this parameter, the table isnot scaled to fit the dialog box.

Chapter 5: Formula Language @Functions A–Z 231

noOkCancel

Note This parameter is new with Release 5.

Boolean. Optional. Specify True if you do not want to display the Okand Cancel buttons. If you specify False or omit this parameter, bothOK and Cancel buttons appear.

title

Text. The title of the dialog box. Defaults to “Lotus Notes.”

UsageThis function is useful in buttons for actions. It does not work in column orselection formulas, or in agents that run on a server (mail and scheduledagents). It is not intended for use in window title or form formulas. It can beused with any form, but it’s particularly useful with forms that contain asingle layout region, because the user can interact with the layout region asif it were a dialog box.

@DialogBox cannot return data from a rich text field.

You cannot use this function in Web applications.

[AutoHorzFit] and [AutoVertFit] allow you to display an entire layoutregion in a dialog box, without displaying the rest of the form. If there ismore than one layout region on a form, only the first one is displayed. Forbest results:

Use both keywords.

In the layout region InfoBox, deselect Display Border and select 3D style.

If form contains actions on the action bar, they are not displayed in thedialog box.

Sharing of field values@DialogBox displays the current document using a different form. This means:

If the form has field names in common with the current document, thefield values of the current document are displayed in the dialog box.Rich text fields will not be displayed in the form, even if field names arethe same as in the current document.

If the user changes the value of any fields in the dialog box and selects OK, the changes are reflected in the same fields on the current document.

If the user enters a value for a field in the dialog box, and the currentdocument does not contain a field by that name, the value is added tothe document, even if it is not displayed in the form.

232 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @DialogBox1. A form called “Profile” contains a button whose formula is

@DialogBox("Profile Options"; [AutoHorzFit] :[AutoVertFit] )

Both Profile and Profile Options have a field named “Comments.”When the user clicks the button, the document is displayed in a dialogbox, using the Profile Options form. The dialog box is scaled to fit thelayout region on Profile Options.

The user can interact with the dialog box, for example, by editing theComments field.

The user clicks OK. The changes made to the Comments field arereflected in the document, if it is in edit mode.

2. This formula displays a form named “Help screen” for reading only.@DialogBox("Help screen"; [AutoHorzFit] : [AutoVertFit] :[NoCancel] : [NoNewFields] : [ReadOnly]; "Help")

@DoEvaluates expressions from left to right, and returns the value of the lastexpression in the list.

Syntax@Do( expressions )

Parameterexpressions

Any number of expressions that you want @Do to evaluate. Separatemultiple expressions with semicolons: expression1 ; expression2 ;expression3

Return valuelastExpression

The value of the last expression.

UsageThis function is useful in agents, buttons, and SmartIcons and when youwant to execute multiple expressions from within a single @function. It doesnot work in column or selection formulas.

Chapter 5: Formula Language @Functions A–Z 233

Example: @DoThis formula displays a dialog box asking whether the user wants to editthe current document. If the user selects Yes, another dialog box appears,prompting for the user’s name. If the user now selects Cancel, the formulastops execution; if the user enters a name and selects OK, the document isopened in edit mode.

If the user selects No at the first dialog box, a different one follows it. Thistime, a message appears noting that the user chose not to edit thedocument, and Notes navigates to the next document in the view.

@If(@Prompt([YESNO]; "Question";"Edit this document?");@If(@Prompt([OKCANCELEDIT]; "Positive Response";"You have chosen to edit this document. Select OK if the namebelow is correct.";@UserName) != "ERR_CANCEL";@Command([EditDocument]);@Return(""));@Do(@Prompt([OK]; "Negative Response";"You have chosen not to edit this document. Select OK tocontinue to the next document.");@Command([NavigateNext])))

@DocChildrenIn a column or window title formula, returns the number of childdocuments or categories belonging to the current document or category.Only immediate responses count as children. For example, the responses toa main document are its children, but the responses to a response documentare not.

Syntax@DocChildren@DocChildren( defaultString )@DocChildren( zero-string ;defaultString )@DocChildren( zero-string ;one-string ;defaultString )

ParametersdefaultString

Text. Optional. The text to return. If a “%” is used in the string, it will bereplaced with the number of children documents or categories.Example: “% Responses.”

234 Domino Designer Programming Guide, Volume 1: Formula Language

zero-string

Text. Optional. The text to return if the document or category has nochildren, such as “No Responses.”

one-string

Text. Optional. The text to return if the document or category has justone child, such as “One Response.”

Return valueThe return value depends on how you call @DocChildren:

numChildren

Special text. If @DocChildren is called with no parameters, then thenumber of child documents belonging to the current document orcategory is returned. You cannot convert special text to a number.

childString

Special text. If @DocChildren is called with one or more parameters, itreturns the appropriate string, based on the number of child documentsbelonging to the current document or category. You cannot convertspecial text to a number.

UsageUse @DocChildren in window title and column formulas, when you want toindicate how many top-level responses a particular document has, or howmany main documents are within a particular category. This function doesnot work in any other formula.

This @function is calculated when the document is opened. Results areundefined in cases where the document is not opened, such as printingfrom a view.

You cannot use this function in Web applications, except in view andcolumn formulas.

Examples: @DocChildrenIf there are three direct descendants to a document:

1. This example returns 3. @DocChildren

2. This example returns 3 Responses. Notes substitutes the appropriatenumber for %. If the document doesn’t have any responses, thisformula returns 0 Responses.@DocChildren("% Responses")

Chapter 5: Formula Language @Functions A–Z 235

3. This example returns 3 Responses. This time, if the document doesn’thave any responses, the formula returns the message No Responses.@DocChildren("No Responses";"% Responses")

4. This example returns There are 3 Responses. If the document has oneresponse, the message is 1 Response; if the document has no responses,the message is No Responses.@DocChildren("No Responses";"1 Response";"There are % Responses.")

@DocDescendantsIn a column or window title formula, returns the number of descendantdocuments or subcategories belonging to the current document or category.Where @DocChildren only counts direct descendants, @DocDescendantscounts all descendants, regardless of level.

Syntax@DocDescendants@DocDescendants(defaultString )@DocDescendants(zero-string ;defaultString )@DocDescendants(zero-string ;one-string ;defaultString )

ParametersdefaultString

Text. Optional. The text to return. If a “%” is used in the string, it will bereplaced with the number of descendant documents or categories.Example: “% Responses.”

zero-string

Text. Optional. The text to return if the document or category has nodescendants, such as “No Responses.”

one-string

Text. Optional. The text to return if the document or category has justone descendant, such as “One Response.”

Return valueThe return value can be either special text or text:

numChildren

Special text. If @DocDescendants is called with no parameters, then thenumber of descendant documents belonging to the current document orcategory is returned. You cannot convert special text to a number.

236 Domino Designer Programming Guide, Volume 1: Formula Language

childString

Special text. If @DocChildren is called with one or more parameters, itreturns the appropriate string, based on the number of descendantdocuments belonging to the current document or category. You cannotconvert special text to a number.

UsageUse @DocDescendants in window title and column formulas, when youwant to indicate the total number of responses (at all levels) to a particulardocument, or the total number of documents within a particular category.This function does not work in any other formula.

This @function is calculated when the document is opened. Results areundefined in cases where the document is not opened, such as printingfrom a view.

You cannot use this function in Web applications.

Examples: @DocDescendantsIf there are three descendants to a document:

1. This example returns 3.@DocDescendants

2. This example returns 3 Response(s).@DocDescendants("% Response(s)")

3. This example returns 3 Responses. If there are no responses to thedocument, the formula returns No Responses.@DocDescendants("No Responses";"% Responses")

4. This example returns There are 3 Responses. If the document has oneresponse, the message is 1 Response; if the document has no responses,the message is No Responses.@DocDescendants("No Responses";"1 Response";"There are % Responses.")

Chapter 5: Formula Language @Functions A–Z 237

@DocFields

Returns a list of all the fields on a document.

Syntax@DocFields

Return valuefields

Text list. Each item in the list is the name of a field on the document.

UsageThis function works in any formula that runs in the context of one or moredocuments.

Example: @DocFieldsThis example returns Form; result; name; phone if those are the names ofthe fields on a document.

@DocFields

@DocLengthReturns the approximate size of a document in bytes.

Syntax@DocLength

Return valuelength

Number. The size of the document.

UsageThis function works in any formula that runs in the context of one or moredocuments.

The number returned is only an approximation. The actual size of thedocument may differ for the following reasons:

The number accounts for user data only; it does not take into accountper-document or per-field constants such as static text or formulas.

The database allocates storage in 64-byte increments; a document maynot use all of the 64 bytes allotted to it.

Documents that are open typically use more storage than documents thatare closed. The value returned for @DocLength may vary depending on

238 Domino Designer Programming Guide, Volume 1: Formula Language

whether it is running in an open document or a closed document, forexample, a document selected at the view level.

Example: @DocLengthThis example returns 1808 if that is the approximate number of bytes in thedocument (one-page document, no enhanced text).

@DocLength

@DocLevelReturns a text string that represents the level of the document or category.

Syntax@DocLevel

Return valuelevel

Special text. The level of the document or category. You cannot convertspecial text to a number.

UsageUse @DocLevel in column and window title formulas. If you use it in awindow title or field formula, it will always evaluate to “1” until thedocument has been saved and reopened. This function does not work inany other formula.

This @function is calculated when the document is opened. Results areundefined in cases where the document is not opened, such as printingfrom a view.

You cannot use this function in Web applications.

Examples: @DocLevel1. This example of a category returns 1.

@DocLevel

2. This example of a main document in a category returns 2.@DocLevel

3. This example of a response document in a category returns 3.@DocLevel

4. This example of a main document that is not in a category returns 1.@DocLevel

Chapter 5: Formula Language @Functions A–Z 239

@DocMark

In an agent that runs a formula, indicates whether or not you want to savethe changes to a document.

Syntax@DocMark( [Update] )@DocMark( [NoUpdate] )

Parameters[Update]

Keyword. Marks a document so that changes made to it are saved to disk.

[NoUpdate]

Keyword. Marks a document so that changes made to it will not besaved to disk.

UsageUse @DocMark in any type of agent to indicate if the changes made to adocument by the agent should be saved. This function has no effect in anyother formula.

You cannot use this function in Web applications.

@DocNumber

In a column or window title formula, returns a string representing the entrynumber of the current document or category. For example, 2.3 indicates thatthe document is the third entry below the second entry.

Syntax@DocNumber@DocNumber( separator )@DocNumber( “” )

Parametersseparator

Text. Optional. Indicates a separator to be used in the documentnumber instead of “.” (period); must be one character.

“”

Optional. Tells the function to return the least significant item of thedocument number (in other words, its rightmost component).

240 Domino Designer Programming Guide, Volume 1: Formula Language

Return valuedocNum

Special text. Value that represents the document number of thedocument or category in the view. You cannot convert special text to anumber.

UsageUse @DocNumber in column or window title formulas. In window title orfield formulas, it will evaluate to “0” until the document has been savedand reopened. This function does not work in any other formula.

This @function is calculated when the document is opened. Results areundefined in cases where the document is not opened, such as printingfrom a view.

You cannot use this function in Web applications.

Examples: @DocNumber1. This example returns 37.1.3 for entry 37.1.3.

@DocNumber

2. This example returns 37-1-3 for entry 37.1.3.@DocNumber("-")

3. This example returns 3 for entry 37.1.3.@DocNumber("")

@DocParentNumberIn a column or window title formula, returns a string that represents theentry number of a view entry’s parent. Both the current view entry and theparent can be either documents or categories.

Syntax@DocParentNumber@DocParentNumber( separator )@DocParentNumber( “” )

Parametersseparator

Text. Optional. Indicates a separator to be used in the parent documentnumber instead of “.” (period); must be one character.

Chapter 5: Formula Language @Functions A–Z 241

“”

Optional. Tells the function to return the least significant item of theparent document number (in other words, its rightmost component).

Return valuedocNum

Special text. Value that represents the document number of thedocument or category in the view. You cannot convert special text to anumber.

UsageUse @DocParentNumber in column and window title formulas. If you use itin a field formula or window title formula, no result is displayed until thedocument has been saved and reopened. This function does not work inany other formula.

To determine the current entry’s own number, use @DocNumber instead.

You cannot use this function in Web applications.

Examples: @DocParentNumber1. This example returns 37.1.3 for the document or category whose parent

is entry 37.1.3.@DocParentNumber

2. This example returns 37-1-3 for the document or category whoseparent is entry 37.1.3.@DocParentNumber("-")

3. This example returns 3 for the document or category whose parent isentry 37.1.3.@DocParentNumber("")

@DocSiblingsIn a column or window title formula, returns a string that represents thetotal number of entries at the same level as a view entry (document orcategory). The returned total includes the document itself. For example, ifthe document is entry 8.2, and entries 8.1, 8.3, and 8.4 also exist, then thereare four document siblings.

Syntax@DocSiblings

242 Domino Designer Programming Guide, Volume 1: Formula Language

Return valuenumSiblings

Special text. The number of entries at the same level as the document orcategory. You cannot convert special text to a number.

UsageUse @DocSiblings in column and window title formulas. If you use it in afield or window title formula, it evaluates to 0 until the document has beensaved and reopened. This function does not work in any other formula.

This @function is calculated when the document is opened. Results areundefined in cases where the doucment is not opened, such as printingfrom a view.

You cannot use this function in Web applications.

Example: @DocSiblingsThis example returns Response 1 of 4 to Current Vacation Policy if thedocument is one of four responses to a document with the string CurrentVacation Policy in the Topic field.

@If(@IsNewDoc;"New Document";"Response" + @DocNumber(" ") + " of " + @DocSiblings + " to " + Topic)

@DocumentUniqueIDA 32-digit hexadecimal number that uniquely identifies a document acrossall replicas of a database. Two documents are replicas of one another if theyshare the same unique ID.

Syntax@DocumentUniqueID

UsageThis function works in any formula that runs in the context of one or moredocuments.

The unique ID is one part of a document’s entire ID number. To see adocument ID, click the Info tab of the document InfoBox. The first line after“ID” indicates the unique ID, while the rest of the characters comprise otherparts of the document ID. @DocumentUniqueID returns the first line, minusthe OF and ON characters.

Once created, a document’s unique ID never changes, unless the user copiesand pastes a document. Notes considers a pasted document to be anewly-created document, and creates a new unique ID for it.

Chapter 5: Formula Language @Functions A–Z 243

Parent and child documentsApplication developers can use the unique ID to navigate responsehierarchies of documents. Every child document has a special field called$Ref, which contains the unique ID of the child’s parent document. Forexample, the following documents are in a hierarchical view:

1.0 What is your favorite color? ( 1 response )

1.1 Mine is blue.

@DocumentUniqueID for 1.0 returns:

FF863D8A:CB6E2210-852561BD:005867C7

The $Ref field on 1.1 contains the same number:

FF863D8A:CB6E2210-852561BD:005867C7

This means you can write formulas on the child document that find theparent by comparing its $Ref field with the value returned by@DocumentUniqueID.

Field formulasIn a field formula, @DocumentUniqueID creates a link to the currentdocument. If the document is mailed, however, the link will fail because itonly contains enough information to locate the document from within itsoriginal database.

You can use @DocumentUniqueID to get the Unique ID of a document. Youmust, however, use @Text to view the result in hexadecimal digits.Otherwise the function only creates a link to the ID. With @Text, thefunction returns the same value as the UniversalID property of theNotesDocument class.

Examples: @DocumentUniqueID1. In a column formula,

@Text(@DocumentUniqueID)

displays the string: FF863D8A:CB6E2210-852561BD:005867C7.

2. In a computed field formula,@DocumentUniqueID

creates a doclink to the current document.

244 Domino Designer Programming Guide, Volume 1: Formula Language

3. You want the Project field on a child document (created with a Reponseform) to match the Project field on the parent document (created with aMain Topic form). In the form Properties box for Response, checkFormulas inherit values from selected document. Make Project acomputed field and give it the formulaProject

This places the Project field from the Main Topic into the Project field ofa newly-created Response.

4. Field inheritance only happens once: when the Response is created. Butyou want to access the Main Topic even after its Response has alreadybeen created. Therefore, you do the following:

Create a hidden view in the database, called “By doc ID”.

The selection formula for the view is:SELECT Form = "Main Topic"

The first column is sorted and its formula is:@Text(@DocumentUniqueID)

Create an agent that runs on a schedule, selects all documents in thedatabase that use the form “Response,” and runs the followingformula:

FIELD Project := @DbLookup("":""; ""; "By doc ID";@Text($Ref); "Project");@All

Each time the agent runs, it performs a lookup into the By doc ID viewto find the Main Topic that’s the parent of the current Response (that is,the document whose @DocumentUniqueID matches the currentdocument’s $Ref field). It then copies the contents of the Project fieldfrom the parent to the child.

5. The following formula accomplishes the same task as the formula in the agent above, but eliminates the need to create an extra view. It also eliminates the need to use @DocumentUniqueID, because@GetDocField automatically finds the document pointed to by $Ref.FIELD Project:=@GetDocField($Ref; "Project");@All

Chapter 5: Formula Language @Functions A–Z 245

@Domain

Returns the name of the current user’s Notes mail domain listed in thecurrent location document of the Personal Address Book.

Syntax@Domain

Return valuedomain

Text. The current user’s domain.

UsageThis function works in any formula and is useful in formulas thatmanipulate mail addresses. When a formula runs on a server, the server isconsidered the current user, so @Domain returns the name of the server’sdomain.

You cannot use this function in Web applications.

Examples: @Domain1. This example returns WorkSavers if the current user belongs to the

WorkSavers domain.@Domain

2. This formula replaces any occurrences of the user’s mail address with anull string, thus removing the current user’s name from CopyTo.FIELD CopyTo:=@Replace(CopyTo;@UserName+"@"+@Domain;"");

Note The above example works only with non-hierarchical names (thoseIDs certified by a non-hierarchical certifier).

@EditECL

Displays the administration “Workstation Security: Execution Control List”dialog for a specified address book and name, which lets you change thatadministration ECL. Administrators can name Administration ECLs. Thename is not usually a user name, but whatever name the administratorchooses, for example, Manager, Developer, or LimitedAccess.

Syntax@EditECL( server : database ; name )

246 Domino Designer Programming Guide, Volume 1: Formula Language

Parametersserver : database

Text list. The server location and file name of the address book. Omitserver or specify it as “” (null) for the local Notes directory.

name

Text. The name of the ECL. Specify “” (null) for the unnamed ECL.

Example: @EditECLThis formula edits the administration ECL named “Developers” in theaddress book on the server Marketing.

@EditECL("Marketing" : "names.nsf"; "Developers")

@EditUserECLDisplays the “Workstation Security: Execution Control List” dialog box,which lets you change your personal ECL for the current workstation.

Syntax@EditUserECL

@ElementsCalculates the number of text, number, or time-date values in a list. Thisfunction always returns a number to indicate the number of entries in thelist.

Syntax@Elements( list )

Parameterlist

Text list, number list, or time-date list.

Return valuenumElements

Number. The number of elements in the list. If the field value is a nullstring, @Elements(list) returns the number 0.

Chapter 5: Formula Language @Functions A–Z 247

Examples: @Elements1. This example returns 4 if the list in the field named SalesForce is

“Rogers”:“Binney”:“Harris”:“Larson”.@Elements(SalesForce)

2. This example returns 2.@Elements("Jones":"Portsmore")

3. This example returns 5.3 + @Elements("Liston":"Reed")

@EnableAlarmsStarts or stops the alarm daemon.

Syntax@EnableAlarms( enableAlarms )

enableAlarms

Text (“0” or “1”). Specify “0” to disable and “1” to enable.

Usage@EnableAlarms brings up the alarm daemon and sets the $EnableAlarmsnotes.ini variable. Once the variable is set, re-entering Notes brings up thealarm daemon. The “0” option stops the alarm daemon if it is running.

@EndsDetermines if a substring is at the end of a string. @Ends is case sensitive.

Syntax@Ends( string ; substring )

Parametersstring

Text. The string to search.

substring

Text. The string to search for at the end of string.

248 Domino Designer Programming Guide, Volume 1: Formula Language

Return valueflag

Boolean. Returns 1 (True) if it is at the end of string; returns 0 (False) if itis not.

Examples: @Ends1. This example returns 1.

@Ends("Hi There";"re")

2. This example returns 0.@Ends("Hi There";"The")

3. This formula checks to see if the end of the field named Signaturecontains the strings “Owens” or “Irons” or “Baker”. If it does, the stringVerify Signature is returned; otherwise, the string Don’t VerifySignature is returned.@If(@Ends(Signature;"Owens":"Irons":"Baker");"Verifysignature"; "Don't Verify Signature")

ENVIRONMENTSets or gets an environment variable stored in the user’s notes.ini file(Windows, OS/2, and UNIX) or Notes Preferences file (Macintosh).

SyntaxENVIRONMENT variable := textValue ;

UsageFor information on how to use environment variables, see “Getting andsetting environment variables.”

To get the value of an environment variable, use @Environment. To set thevalue of an environment variable, you can also use @Environment, or youcan use @SetEnvironment.

For Web applications, use pre-defined field names to gather informationabout the Web user’s environment by requesting Common GatewayInterface (CGI) environment variables.

Chapter 5: Formula Language @Functions A–Z 249

@Environment

Sets or returns an environment variable stored in the user’s notes.ini file(Windows, OS/2, and UNIX) or Notes Preferences file (Macintosh).

Syntax@Environment( variable )@Environment( variable ; value )

Parametersvariable

Text or text list. The name of the environment variable you want toretrieve. To retrieve multiple environment variables, use a text list.

value

Text. Optional. The value you want to assign to the environmentvariable. Since users, have their own notes.ini or Notes Preferences file,this value can be customized for each user. Omit this parameter if youjust want to retrieve the value, not set it.

If variable is a text list, every environment variable in the list will beassigned value.

If value is a text list, only the first value in the list is used; the rest areignored.

Return valueenvironmentVariable

Text. The value of the environment variable you specified. To use thereturn value in arithmetic operations, use @TextToNumber to convert itto a number.

UsageFor information on how to use environment variables, see “Getting andsetting environment variables” in the chapter “Formula Language Coding Guidelines.”

Use @Environment when you want to set an environment variable within aformula. If it’s to be nested within another @function (such as @If or @Do),use @SetEnvironment instead.

The ENVIRONMENT keyword works the same as @Environment.

@Environment cannot be used in column or selection formulas; it’sintended for use in field and form formulas, buttons, SmartIcons, andagents. Some formulas, such as scheduled agents, are run on the server

250 Domino Designer Programming Guide, Volume 1: Formula Language

instead of the user’s workstation. In this case, the environment variablesaffected are the server’s environment variables, not the workstation’s.

You can also use @Environment to get the value of an environmentvariable.

For Web applications, use pre-defined field names to gather informationabout the Web user’s environment by requesting Common GatewayInterface (CGI) environment variables.

Examples: @Environment, @SetEnvironment, and ENVIRONMENT1. This example returns 8009, if that is the value of the variable

OrderNumber stored in the current user’s notes.ini or NotesPreferences file. This value may differ for different users, allowing youto sequentially number each user’s orders.@Environment("OrderNumber")

2. This example places a variable called OrderNumber in the currentuser’s notes.ini or Notes Preferences file, and assigns it a value of zero.@Environment("OrderNumber";"0")

3. To save users time while completing Profile documents, you want toautomatically fill in an office location for them. You create an editabletext field called OfficeLocation. Its default formula is:@Environment("ENVOfficeLocation")

Its input-translation formula is:@Environment("ENVOfficeLocation"; OfficeLocation);OfficeLocation

The first time the user creates a Profile document, the OfficeLocationfield is blank, so the user types in the office location. When thedocument is saved, the contents of the OfficeLocation field are saved inthe notes.ini or Notes Preferences file. The next time the user creates aProfile document, the office location is retrieved from the environmentvariable ENVOfficeLocation, and the user doesn’t have to type it inagain (unless the office location changes, in which case the user editsthe field).

You could also write the input-translation formula using either@SetEnvironment or the ENVIRONMENT keyword, both of whichachieve the same result:@SetEnvironment("ENVOfficeLocation"; OfficeLocation);OfficeLocation

or

Chapter 5: Formula Language @Functions A–Z 251

ENVIRONMENT ENVOfficeLocation:= OfficeLocation;OfficeLocation

4. In addition to the OfficeLocation, you want to use an environmentvariable to store a user’s birthday. You create an editable time fieldcalled Birthday. Its default formula is similar to the one used forOfficeLocation:@Environment("ENVBirthday")

Its input-translation formula uses @Text to convert the time value into text:@SetEnvironment("ENVBirthday"; @Text(Birthday));Birthday

You use a @Text to write a similar input-translation formula for anumber field.

5. You want to generate sequential numbers on a per user basis, and youwant to store the number in a field called OrderNumber. Define thefield OrderNumber to be a Text data type; it must be some form ofComputed field. Then write the following formula for the field.Temporary := @Environment("OrderNumber");Temporary2 := @If(Temporary="";"0";Temporary);CurrentOrderNumber := @TextToNumber(Temporary2);NextOrderNumber := CurrentOrderNumber + 1;ENVIRONMENT OrderNumber := @Text(NextOrderNumber);@Text(CurrentOrderNumber);

6. This formula tests whether an environment variable calledOrderNumber has been stored in the user’s notes.ini or NotesPreferences file. If there is no such variable stored, @SetEnvironmentinitializes it to zero. If a value has already been stored, @Return returnsit and stops the formula from executing.@If(@Environment(OrderNumber)="";@SetEnvironment("OrderNumber";"0");@Return(@Environment("OrderNumber")))

7. Two agents are used to look up a list of possible group names that usersmight belong to, prompt the user to select one, and then enter thatname in the Group field for all selected documents (which in this case,pertain to the current user).

The Set Group agent looks up the list of group names stored in column1 of the Service Requests - By Group view, prompts the user to select agroup name, and then stores the selected name in the TmpNameenvironment variable before running the “(Set Group Helper)” agent.The “(Set Group Helper)” agent then retrieves the group name from the

252 Domino Designer Programming Guide, Volume 1: Formula Language

user’s notes.ini or Notes Preferences file, and stores it in the Groupname field for all selected documents.

Set Group agent executes once:GroupList:=@DbColumn("":"NoCache";"";"Service Requests\\By Group";1);Group:=@Prompt([OKCancelEditCombo];"Choose agroup";"Choose a group";"Marketing";GroupList);Tmp1:=@Environment("TmpName";Group);@Command([ToolsRunMacro];"(Set Group Helper)");

(Set Group Helper) agent runs on each selected document:FIELD Group:=@Environment("TmpName");

@ErrorAllows you to generate an error condition within an expression. This isuseful if you want to evaluate the current values in several fields, and needto know if an error has occurred in the entry of any of them.

Syntax@Error

Return value@Error

UsageUse @IsError to test for a data entry error.

When an error has occurred, @Error is returned. The function cannot returnany other value.

@Error always results in an error condition when it tests a single value. Ifyou use @Error alone as a formula, you will always generate an error.

You cannot test for an @Error value with any operator or @function otherthan @IsError. If you use an error value as an argument to an operator or@function, the return is always @Error.

Examples: @ErrorRead the following examples closely to understand the difference between@Error and @IsError.

1. This example returns the value in the field Price if it is greater than 100,otherwise returns @Error.@If(Price>100;Price;@Error)

Chapter 5: Formula Language @Functions A–Z 253

2. This example checks to see if there is an @Error in the field namedPrice. If there is an @Error, the string There is an error in the price fieldis returned. If the contents of the field are anything other than @Error,Price Field Okay is returned.@If(@IsError(Price);"There is an error in the pricefield";"Price Field Okay")

@ExpCalculates the number e (approximately 2.718282) raised to the powerspecified (this value can contain up to 14 decimal places).

Syntax@Exp( power )

Parameterpower

Number. The power to which you want to raise e. Notes can onlycalculate this function when number is between -11355.1371 and11356.5234. Values outside this range will return the value @ERROR.

UsageNatural logs use the constant e as their base. Use @Exp in formulasrequiring exponential functions.

Examples: @Exp1. This example returns 3.49034295746184 (e raised to the power of 1.25).

@Exp(1.25)

2. This example returns 0.28650479686019 (e raised to the power of -1.25).@Exp(-1.25)

@ExplodeReturns a text list composed of the elements of a text string or date range.

If you specify a text string, elements are defined either as words (if theyare separated by spaces) or as clauses separated by the specifiedseparator.

If you specify a time-date range, elements are defined as the individualdays that are within the range.

254 Domino Designer Programming Guide, Volume 1: Formula Language

Syntax@Explode( dateRange )@Explode( string )@Explode( string ; separator )@Explode( string ; separator ; includeEmpties )

ParametersdateRange

Time-date range or time-date range list. The range of dates whoseindividual days you want to make into a text list.

string

Text. The string whose contents you want to make into a text list.

separator

Text. Optional. One or more characters in string that are used to definethe end of an element. The default separator is “ ,;” (space commasemicolon), which means that Notes adds a new element to the text listeach time a space, comma, or semicolon is encountered in the originalstring.

includeEmpties

Boolean. Optional. Specify True (1) if you want Notes to place an emptystring (“”) in the returned list whenever a separator appears at the verybeginning or end of the string, or whenever two occurrences of aseparator occur consecutively in the string. Specify False (0) if you do notwant to include such empty occurrences in the returned list.

Return valueexplodedString

Text list. A list containing each element found in string or each datefound in dateRange.

UsageWhen using @Explode with a date range, keep in mind that you mustspecify a valid date-time range, not a string representation of one. Forexample, @Explode( “05/01/96 - 05/02/96” ) is invalid because theparameter is a string. Use @Explode( [05/01/96 - 05/02/96] ).

Chapter 5: Formula Language @Functions A–Z 255

Examples: @ExplodeGiven a semicolon (;) as the default display separator:

1. This example returns Weekly;Status;Report if the contents of the Topicfield is “Weekly Status Report”, “Weekly,Status,Report” or“Weekly;Status;Report”. This is because the default separator is “ ,;”(space, comma, semicolon).@Explode(Topic)

2. This example returns The team meeting takes place at Eva ; Hannah’sbar; b; que tonight at 8. if the contents of the entry field is: “The teammeeting takes place at Eva & Hannah’s bar-b-que tonight at 8.”@Explode( entry; "-&" )

3. This example returns Please send resume + references if the contents ofthe entry field is: “Please send resume & references”.@Implode( @Explode( entry; "&" ); "+" )

4. This example returns Attendance grows at UCLA; Pomona Colleges;and USC if the contents of the Headline field is “Attendance grows atUCLA, Pomona Colleges, and USC”.@Explode(Headline;",")

5. This example returns 4 if the contents of the Country field is “Mexico,Guatemala, Costa Rica, El Salvador”.@Elements(@Explode(Country; ","))

6. This example returns 07/02/96; 07/03/96; 07/04/96; 07/05/96.@Explode([07/02/96 - 07/05/96])

7. This example returns 07/01/94; 05/01/94; 10/01/94; 10/02/94;10/03/94; 04/01/94; 04/02/94; 04/03/94. Note the order in which thedates are returned: single date-time values are returned first, followedby exploded date-time ranges. The return value is a text-list.@Explode([07/01/94]:[10/01/94 -10/03/94]:[05/01/94]:[04/01/94 - 04/03/94])

8. You want users to be able to enter a range of dates into an editable,multi-value, time-date field called Duration and display them in acomputed, multi-value, text field called Days. Give the Duration fieldthe following input-translation formula: @Date(Duration). Give theDays field the following formula: @Explode(Duration). Users can enterdates in the Duration field in this format: 04/16/71-04/18/71.

256 Domino Designer Programming Guide, Volume 1: Formula Language

@Failure

Returns a message that you supply; when used in an input validationformula, @Failure displays its message whenever the entered value doesnot meet the validation criteria.

Syntax@Failure( string )

Parameterstring

Text. The error message you want returned.

Return valuestring

Text. The error message.

Usage@Failure is mainly used in input validation formulas for editable fields,although you can also use it in agents and form formulas. When @Failure isused in formulas other than input validation formulas, the result is theinput string; Notes displays no prompts or messages.

Example: @FailureThis example show an input validation formula. It returns the errormessage “Area codes have only 3 digits” if the user enters a number greaterthan 999 in the field named AreaCode.

@If(AreaCode<999;@Success;@Failure("Area codes have only 3 digits"))

@False

Returns the number 0.

Syntax@False

Return value0

UsageThis function is equivalent to @No.

Chapter 5: Formula Language @Functions A–Z 257

Examples: @False1. This example returns 0.

@False

2. This example returns 0 if the value in the field named Cost is 100 or less.@If(Cost>100;@True;@False)

FIELDThe FIELD keyword is necessary when you are assigning values to fieldsthat are stored in a document (as opposed to temporary fields). You can useFIELD to change the contents of an existing field or to create new fields.

SyntaxFIELD fieldName := value ;

Caution When you use FIELD to create a new field in existing documents,make sure that you do not duplicate the name of a field that already exists.

In some cases, action formulas that don’t evaluate to a result (for example, abutton formula) return a “No Main or Selection expression in formula”error message. You can supply a value such as an empty string (“”), or youcould provide an expression at the end of the formula as shown below:

SELECT @All

UsageThis keyword is most useful in agent, button, hotspot, and action formulas.It does not work in column, selection, hide-when, window title, or formformulas.

Examples: FIELD1. There is a field named Company in a form. When users compose

documents with this form, they enter the name of the company in thisfield. You write the following filter which adds “Inc.” to the contents ofthe Company field:FIELD Company := Company + ", Inc.";

2. Alternatively, you can create a new field called CompanyName in theform to hold the name of the company plus “Inc.” by assigning it thefollowing formula:FIELD CompanyName := Company + ", Inc.";

258 Domino Designer Programming Guide, Volume 1: Formula Language

3. To delete the field CompanyName from an existing set of documents,you can use the following formula:FIELD CompanyName := @DeleteField;

@Fontlist

Provides a list of available fonts on the Notes Client where this @function is executed.

Note This @function is new with Release 5.

Syntax@Fontlist

Return valueavailablefont

Text list. All the available font names. For “Default Serif”, “Default Sans Serif”, and “Default Monospace” fonts, @Fontlist returns aliasvalues as follows:

Default Serif 0

Default Sans Serif 1

Default Monospace 4

Usage@FontList in a keyword formula for a keyword field, where you can selectyour preferred font.

Example: @FontListThe following formula returns a list of font names like “Arial” : “Courier” :“Default Sans Serif|1” : “Default Serif|0” : “Default Monospace|4” :“Times New Roman”....

@FontList

@GetDocField

Given the unique ID of a document, returns the contents of a specific fieldon that document. The document must reside in the current database.

Syntax@GetDocField( documentUNID ; fieldName )

Chapter 5: Formula Language @Functions A–Z 259

ParametersdocumentUNID

Text. The unique ID of a document.

fieldName

Text. The name of a field on the document, enclosed in quotationmarks. If you store the field name in a variable, omit the quotationmarks here.

Return valuefieldValue

Text or text list; number or number list; time-date or time-date range.The contents of the field on the specified document.

UsageThis function does not work in column or selection formulas.

Examples: @GetDocField1. You have a discussion database with main topics and responses. In each

response, you want to store the subject of the parent document in a fieldcalled OriginalSubject. You want OriginalSubject to change if thesubject of the main topic changes, so you write this formula for it. $Refis a special field on a response document that contains the unique ID ofthe parent document.@If(@IsNewDoc; Subject; @GetDocField($Ref; "Subject"))

2. The following formula can run a scheduled agent to update thecontents of a child document, based on the parent.FIELD Project:=@GetDocField($Ref; "Project");@All

@GetPortsListReturns a list of enabled or disabled ports.

Syntax@GetPortsList([portType])

260 Domino Designer Programming Guide, Volume 1: Formula Language

ParametersportType

Keyword. Must be enclosed in brackets. Use one of the following keywords:

Enabled

Returns a list of currently enabled ports.

Disabled

Returns a list of currently disabled ports.

Return ValueportsList

Text list; each port name is one element of the list.

Usage@GetPortsList is used by the Public and Personal Address books todetermine the list of available ports for each Location record. You can thenselect a port from that list.

This function does not work in column formulas, selection formulas, orselective replication formulas.

You cannot use this function in Web applications.

Examples: @GetPortsList1. This example returns Lan0;TCP;AppleTalk® if those are the currently

enabled ports.@GetPortsList([Enabled])

2. This example returns COM1;COM2 if those are the currently disabled ports.@GetPortsList([Disabled])

Note The text list uses the multi-value separator specified for the currentfield or the list separator specified for the current column in a view.

@GetProfileFieldRetrieves a field from a profile document, and caches the field value for theremainder of the session.

Syntax@GetProfileField(profilename ; fieldname [ ; username] )

Chapter 5: Formula Language @Functions A–Z 261

Parametersprofilename

Text. The name of the profile document that contains the field you wantto access.

fieldname

Text. The name of the field you want to access.

username

Text. The name of the user associated with the profile document.

Return Valuefieldvalue

The value of the field.

Examples: @GetProfileField1. This example gets the contents of the “Profile Categories” field of the

“Interest Profile” document.@GetProfileField("Interest Profile"; "Profile Categories")

2. This example gets the contents of the “Profile Categories” field of the“Interest Profile” document for the current user.@GetProfileField("Interest Profile"; "Profile Categories", @UserName)

@HourReturns the number of the hour in the specified time-date.

Syntax@Hour( timeDateValue )

ParametertimeDateValue

Time-date. The value whose hour you want to extract.

Return valuehour

Number. A number representing the hour contained in timeDateValue.

262 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Hour1. This example returns 9.

@Hour([9:30])

2. This example returns 8 if the time in the field named Date is 8:56:34 P.M.@Hour(Date)

3. This example returns 8 if a field named Date is made up of the date and time: 7/30/90 8:56:34 P.M.@Hour(Date)

4. This example returns 3 if the current document was created on 2/15/92at 3:00:12 A.M.@Hour(@Created)

@IfEvaluates a condition; if the condition is True, Notes performs the actionappearing immediately after that condition, and stops. If the condition isFalse, Notes skips to the next condition and tests it, and so on. If none of theconditions is True, Notes performs the else_action.

Syntax@If( condition1 ; action1 ; condition2 ; action2 ; ... ; condition99 ; action99 ;else_action )

Parameterscondition

Expression that returns a boolean. If this expression returns True, actionis performed. If it’s False, Notes skips to the next condition, if there isone. Otherwise, Notes performs else_action.

action

An action to be performed or a value to be returned if the governingcondition returns True.

else_action

An action to be performed or a value to be returned if none of theconditions returns True.

Chapter 5: Formula Language @Functions A–Z 263

UsageIn its simplest form, the If statement looks like this:@If( condition ; action ;else_action ).

You can list up to 99 conditions and corresponding actions, followed by justone action to be performed when all the conditions are False. As soon as acondition evaluates to True, Notes performs the associated action andignores the remainder of the @If statement.

Notes accepts the form @If( condition ), with only one condition and noaction, but does not perform any action based on the condition.

If you compare a field to a value (for example, Year > 1995) and the field isunavailable, the comparison is false. However, you should check for fieldsthat may not be present with @IsUnavailable.

Examples: @If1. This formula tests the single value in the field named CostOfGoods. If

the value is greater than or equal to 12.45, the condition is True, and thestring “Over Budget” is returned. If the value is less than 12.45, thecondition is False and the string “Bill of Materials OK” is returned.@If(CostOfGoods>=12.45;"Over Budget";"Bill of Materials OK")

2. In this example, if CostOfGoods is less than 12.45, the null string is returned.@If(CostOfGoods>=12.45;"Over Budget";"")

3. In this example, @If looks at the value in the field named CostOfGoods;if the value is greater than 12.45, then the string “Over Budget” isreturned; if not, Notes skips to the next condition. The second conditionalso evaluates the CostOfGoods field and if the value is less than 12.45,then the condition is True and Notes returns the string “Bill of MaterialsOK”. If the value is neither greater than nor less than 12.45, Notesmoves on to the “else” action specified, and the string “Estimate Righton Target” is returned.@If(CostOfGoods>12.45;"OverBudget";CostOfGoods<12.45;"Bill of Materials OK";"Estimate Right on Target")

4. Notes first checks that the document has never been saved; if thecondition is True, the value in the field NewNoteTitle is returned. If thefirst condition is false, Notes then checks whether the view is the

264 Domino Designer Programming Guide, Volume 1: Formula Language

Author View; if this is true, the value in the field ByAuthorTitle isreturned. If both conditions are false, the value in the fieldStandardTitle is returned.@If(@IsNewDoc; NewNoteTitle; @ViewTitle = "Author View";ByAuthorTitle; StandardTitle)

@ImplodeConcatenates all members of a text list and returns a text string.

Syntax@Implode( textlistValue ) or@Implode( textlistValue ; separator )

ParameterstextlistValue

Text or text list. List containing the items you want to concatenate into asingle string. If you send a single piece of text instead of a list,@Implode returns the text unaltered.

separator

Text. Used to separate the values in the concatenated string. If youdon’t specify a separator, a space is used.

Return valueimplodedString

Text. String containing each member of textListValue, separated byseparator.

Examples: @Implode1. This example returns Minneapolis Detroit Chicago if the contents of the

City field are “Minneapolis”:“Detroit”:“Chicago”.@Implode(City)

2. This example returns Minneapolis,Detroit,Chicago if the contents of theCity field are “Minneapolis”:“Detroit”:“Chicago”.@Implode(City;",")

3. This example returns European Capitals/Bonn : EuropeanCapitals/Lisbon : European Capitals/Madrid if the contents of theCategories field are European Capitals, and the content of the Citiesfield is a list consisting of Bonn, Lisbon, and Madrid.@Implode(Categories + "/" + City ; " : ")

Chapter 5: Formula Language @Functions A–Z 265

@InheritedDocumentUniqueID

The unique ID of the current document’s inheritance parent. See@DocumentUniqueID for a description of unique IDs.

Syntax@InheritedDocumentUniqueID

UsageThis function is useful for documents created with a form whose fieldvalues inherit from the selected document. In documents that do not inherit,@InheritedDocumentUniqueID returns the same value as@DocumentUniqueID.

In a field formula, @InheritedDocumentUniqueID creates a link in place ofthe ID. If the document is mailed, however, the link will fail because it onlycontains enough information to locate the document from within its originaldatabase.

@Integer

Truncates the values in a number or number list at the whole number,leaving off any decimals. The values in the resulting list are separated using the multi-value separator selected for display in the field containingthe formula.

Syntax@Integer( numberValue )

ParameternumberValue

Number or number list. The value(s) you want to truncate.

Return valuetruncatedValue

Number or number list. The truncated value(s).

UsageWhen using this function with a number list, list concatenation operatortakes precedence over any other operators. Negative numbers must beenclosed in parentheses.

For more information, see “List Operator” in the chapter “FormulaLanguage Rules.”

266 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Integer1. This example returns 123;789.

@Integer(123.001 : 789.999)

2. This example returns 127580;5;7341 if the numbers in the Sales,CommissionRate, and Commission fields are 127580.35, 5.75, and7341.62015 respectively.@Integer(Sales:CommissionRate:Commission)

3. This example returns 3.@Integer(3.12)

4. This example returns 6.@Integer(6.735)

@IsAgentEnabledIndicates whether or not a scheduled agent is enabled.

Syntax@IsAgentEnabled( agent )

Parameteragent

Text. The name of the agent. Not case sensitive.

Return valueflag

Number. Returns 1 (True) if the agent is enabled. Returns 0 (False) if theagent is disabled, or if an agent by that name does not exist.

UsageA database must be open. If a database is not open, returns 0.

@IsAgentEnabled returns 1 for macros created in Notes Release 3 and forany agents that are not scheduled.

@IsAgentEnabled does not work in column or selection formulas and is notintended for use in window title or form formulas.

You cannot use this function in Web applications.

Chapter 5: Formula Language @Functions A–Z 267

Example: @IsAgentEnabledThis example returns 1 if the UnderCover agent is enabled; otherwise,returns 0.

@IsAgentEnabled( "UnderCover" )

@IsAvailableChecks a document for the existence of a field name.

Syntax@IsAvailable( fieldName )

ParameterfieldName

Field. The name of a field.

Return valueflag

Returns 1 (True) if the field is contained in the document, otherwise 0(False).

UsageUse @IsAvailable to provide a default value for documents created withforms that do not include a field name.

Examples: @IsAvailable1. This formula returns the value of the field named Dept if it exists in the

document, otherwise returns Consultant.@If(@IsAvailable(Dept);Dept;"Consultant")

2. This formula returns the value of the field named Topic if it exists in thedocument, otherwise returns the value contained in the field namedSubject.@If(@IsAvailable(Topic);Topic;Subject)

268 Domino Designer Programming Guide, Volume 1: Formula Language

@IsCategory

In a column formula, returns a specified string if any item in the row of aview is defined as a category.

Syntax@IsCategory@IsCategory( trueString )@IsCategory( trueString ; falseString )

ParameterstrueString

Text. A string to return if an item in the view row is a category.

falseString

Text. A string to return if no item in the row is a category.

Return valuespecifiedString

Text. With no parameters, @IsCategory returns * (asterisk) if the entry isa category, and returns nothing if the entry is a document. With a singletrueString parameter, returns trueString instead of *. With bothtrueString and falseString parameters, returns trueString instead of * orfalseString instead of nothing.

UsageUse @IsCategory only in column formulas.

This function only looks at the columns to its right, so be sure to place it tothe left of the categorized column you’re referring to.

You cannot use this function in Web applications.

Examples: @IsCategory1. This example returns * if the row is a category, or nothing if the row is

not a category.@IsCategory

2. This example returns C if the row is a category, or nothing if the row isnot a category.@IsCategory("C")

3. This example returns Y if the row is a category, or N if the row is not acategory.@IsCategory("Y";"N")

Chapter 5: Formula Language @Functions A–Z 269

@IsDocBeingEdited

Checks the current status of the document and returns 1 (True) if thedocument is being edited; otherwise returns 0 (False).

Syntax@IsDocBeingEdited

Return Valueflag

Boolean. Returns 1 (True) only when the document is being edited.Otherwise returns 0 (False).

UsageThis function does not work in column, selection, agent, form, or viewaction formulas. It’s intended for use in button, hide-when, field, and formaction formulas.

@IsDocBeingLoadedChecks the current status of the document and returns 1 (True) if thedocument is being loaded into memory for display; otherwise returns 0(False).

Syntax@IsDocBeingLoaded

Return valueflag

Boolean. Returns 1 (True) only when the document is actually beingloaded into memory. Otherwise returns 0 (False).

UsageUse function in field and form formulas. It does not work in SmartIcons,button, selection, column, agent, section editor, hotspot, form action, orview action formulas.

Examples: @IsDocBeingLoaded1. This example returns 1 when the document is being loaded into

memory.@IsDocBeingLoaded

270 Domino Designer Programming Guide, Volume 1: Formula Language

2. This example returns 0 when the document is saved.@IsDocBeingLoaded

3. This example, when used in a computed field named “Editors,”displays the contents of $UpdatedBy when the document is beingloaded. When the user recalculates the field (by pressing F9), the fielddisplays the user’s name as the current editor, followed by previouseditors’ names. When the document is saved, the value of “Editors”remains unchanged.@If(@IsDocBeingLoaded;$UpdatedBy;@IsDocBeingRecalculated;("Current Editor – " + @UserName):$UpdatedBy;Editors)

@IsDocBeingMailedChecks the current status of the document and returns 1 (True) if thedocument is being mailed; otherwise, returns 0 (False).

Syntax@IsDocBeingMailed

Return valuesflag

Boolean. Returns 1 (True) only while the document is actually beingmailed. Otherwise returns 0 (False).

UsageUse @IsDocBeingMailed in field formulas. This function is useful forcalculating the number of times the user has mailed a document, includingthe number of times the document has been forwarded. It is also useful forchanging a document during mailing; for example, you can change adocument’s form when it is mailed.

It has limited usefulness in SmartIcons, button, hotspot, and form actionformulas. This function does not work in column, selection, agent, windowtitle, form, or view action formulas.

You cannot use this function in Web applications.

Examples: @IsDocBeingMailed1. This example returns 1 when the document is being mailed.

@IsDocBeingMailed

2. This example returns 0 before and after the document has been mailed.@IsDocBeingMailed

Chapter 5: Formula Language @Functions A–Z 271

3. This formula is used in a field to calculate the number of times adocument has been mailed. When this formula is provided as thedefinition of a computed field called TimesMailed, the field isinitialized to 0 (since the document has not been mailed). TimesMailedis incremented with every mail operation, so if the document has beenmailed once, the contents become 1, and the count increases by oneeach time the document is mailed.@If(@IsUnavailable(TimesMailed);0;TimesMailed+@IsDocBeingMailed)

@IsDocBeingRecalculatedChecks the current status of the document and returns 1 (True) if thedocument is being recalculated; otherwise, returns 0 (False).

Syntax@IsDocBeingRecalculated

Return valueflag

Boolean. Returns 1 (True) only when the fields on the document areactually being recalculated. Otherwise returns 0 (False).

UsageUse @IsDocBeingRecalculated in field formulas. It has limited usefulness inSmartIcons, button, hotspot, and form action formulas. This function doesnot work in column, selection, agent, window title, form, or view actionformulas.

If you are using this function to increment a counter, the count increases byone every time the user recalculates the fields on a form.

Examples: @IsDocBeingRecalculated1. This example returns 1 while the document is being calculated or

recalculated.@IsDocBeingRecalculated

2. This example returns 0 before and after the document is calculated orrecalculated.@IsDocBeingRecalculated

3. This example can be used in a time-date field to display different datesunder different circumstances. The formula causes the currenttime-date to be displayed if the document is recalculated during the

272 Domino Designer Programming Guide, Volume 1: Formula Language

editing process; otherwise, it displays the original creation date of thedocument.@If(@IsDocBeingRecalculated;@Now;@Created)

@IsDocBeingSaved

Checks the current status of the document and returns 1 (True) if thedocument is being saved; otherwise, returns 0 (False).

Syntax@IsDocBeingSaved

Return valueflag

Boolean. Returns 1 (True) only when the fields on the document areactually being saved. Otherwise returns 0 (False).

UsageUse @IsDocBeingSaved in field formulas. It has limited usefulness inSmartIcons, button, hotspot, and form action formulas. This function doesnot work in column, selection, agent, window title, form, or view actionformulas.

If you are using this function to increment a counter, the count increases byone every time the user saves the form.

Examples: @IsDocBeingSaved1. This example returns 1 while the document is being saved.

@IsDocBeingSaved

2. This example returns 0 before or after the document is saved.@IsDocBeingSaved

3. This formula sets the field named Readers, which is a Reader Namesfield, to Admins when the document is saved. Otherwise, it sets theReaders field to the value already in the field. This type of formula isuseful for changing the Read Access of a document after it has beencomposed and saved.@If(@IsDocBeingSaved;"Admins";Readers)

Chapter 5: Formula Language @Functions A–Z 273

@IsDocTruncated

Indicates whether the current document has been truncated.

Syntax@IsDocTruncated

Return Valueflag

Boolean. Returns 1 (True) if the document is missing some data; returns0 (False) if the entire document is present.

UsageYou typically use @IsDocTruncated in a column formula to display thetruncated document indicator. You can also use @IsDocTruncated in avariety of other formulas, including SmartIcons, buttons, hide-whenformulas, section editors, window title formulas, field formulas, formformulas, column formulas, selection formulas, and agents.

Documents may be truncated during database replication. Depending uponthe type of truncation, a document can be missing an attached file, an OLEobject, large rich text fields, or non-summary items.

If the document is truncated, you can obtain the entire document bychoosing Action - Retrieve Entire Document, either in the background orduring the next replication of the database. You cannot edit a truncateddocument.

@IsErrorReturns 1 (True) if the value is an @ERROR value, returns 0 (False) if not anerror.

Syntax@IsError( value )

Parametervalue

Number. Can be a literal value or a field name containing data of type Number.

274 Domino Designer Programming Guide, Volume 1: Formula Language

Return valueflag

Boolean. Returns 1 (True) if the value is an @ERROR value, returns 0(False) if not an error.

Examples: @IsError1. This example returns 1.

@IsError(1/0)

2. This example returns 0.@IsError(1/2)

3. This formula checks to see if there is an @ERROR in the field namedPrice, and returns “There is an error in the price field” if it encountersan error; otherwise it returns 0.@If(@IsError(Price); @Failure("There is an error in theprice field"); @Success)

@IsExpandableIn column formulas, returns a specified string if a row in a view can beexpanded.

Syntax@IsExpandable@IsExpandable( trueString )@IsExpandable( trueString ; falseString )

ParameterstrueString

Text. A string to return if the view row is expandable.

falseString

Text. A string to return if the view row is not expandable.

Return valuespecifiedString

Text. With no parameters, returns + (plus) if the entry is expandableand – (minus) if the entry is not expandable. With a single trueStringargument, returns the trueString instead of + if the entry is expandableand nothing if it is not expandable. The two parameter form returnstrueString instead of + and falseString instead of –.

Chapter 5: Formula Language @Functions A–Z 275

UsageUse @IsExpandable in column formulas to indicate whether the currentlevel of documents can be expanded. This function does not work in anyother formula.

In the single parameter and two parameter forms, you should limit thestring to a single character, especially if the lines already have a lot of text inthem.

You cannot use this function in Web applications.

Examples: @IsExpandable1. This example returns + if the document or category is expandable, or -

if it is not expandable.@IsExpandable

2. This example returns & if the document or category is expandable.@IsExpandable("&")

3. This example returns Y if the document or category is expandable, or Nif it is not expandable.@IsExpandable("Y";"N")

@IsMemberIndicates if a piece of text (or a text list) is contained within another text list.The function is case-sensitive.

Syntax@IsMember( textValue ; textListValue )@IsMember( textListValue1 ; textListValue2 )

ParameterstextValue

Text.

textListValue

Text list.

textListValue1

Text list.

textListValue2

Text list.

276 Domino Designer Programming Guide, Volume 1: Formula Language

Return valueflag

Boolean. Returns 1 (True) if the textValue is contained in textListValue;returns 0 (False) if not. If both parameters are lists, returns 1 if allelements of textListValue1 are contained in textListValue2.

UsageIn processing lists, @IsMember differs from a simple = test. An = returnsTrue if the intersection of 2 entities has even one member, that is, theintersection is not empty. @IsMember returns True only if the firstparameter is a subset of the second.

Examples: @IsMember1. This example returns 1.

@IsMember("computer";"printer":"computer":"monitor")

2. This example returns 0.@IsMember("computer":"Notes";"Notes":"printer":"monitor")

3. This example returns 1 if R&D is in the list in the field Department;returns 0 if R&D is not in the list.@IsMember("R&D";Department)

@IsModalHelpIndicates whether the current document is a modal Help document.

Syntax@IsModalHelp

Return Valueflag

Boolean. Returns 1 (True) if the document is a modal Help document;otherwise, returns 0 (False).

UsageUse @IsModalHelp to determine modality so you can execute a formula oraction only when the document is (or isn’t) a modal Help document.

You cannot use this function in Web applications.

Chapter 5: Formula Language @Functions A–Z 277

@IsNewDoc

For a document being edited, indicates if the document has been saved todisk.

Syntax@IsNewDoc

Return valueflag

Boolean. Returns 1 (True) if the document being edited has not yet beensaved to disk; returns 0 (False) if the document has been saved.

UsageThis function evaluates the current state of the document when it is used inSmartIcons, button, hide-when, section editor, window title, field, form, andform action formulas. In column, selection, agent, and view action formulas,it always returns a 0.

Examples: @IsNewDoc1. When used in a window title formula, this formula returns New

Document while the document is composed the first time. When adocument is opened after it has been saved, this formula returns thevalue of the Subject field.@If(@IsNewDoc;"New Document";Subject)

2. If a new document is being created, the string New GeneralInformation appears in the window title. When an existing document isopened, the string General Information for, then the contents of thefield EmpName, then a slash and then the contents of the fieldEmpNumber appear in the window title.@If(@IsNewDoc; "New General Information"; "GeneralInformation for" + EmpName + "/" + EmpNumber)

@IsNotMemberIndicates if a text string (or a text list) is not contained within another textlist. The function is case sensitive.

Syntax@IsNotMember( textValue ; textListValue ) or@IsNotMember( textListValue1 ; textListValue2 )

278 Domino Designer Programming Guide, Volume 1: Formula Language

ParameterstextValue

Text.

textListValue

Text list.

textListValue1

Text list.

textListValue2

Text list.

Return valueflag

Boolean. Returns 1 (True) if the textValue is not contained intextListValue; returns 0 (False) if it is contained. If both parameters arelists, returns 1 if all elements of textListValue1 are not contained intextListValue2.

UsageIn processing lists, @IsNotMember differs from a simple != test. != returnsTrue if the intersection of 2 entities has no entities in common.@IsNotMember returns True only if no member of the first argument iscontained in the second argument.

Examples: @IsNotMember1. This example returns 0.

@IsNotMember("computer";"printer":"computer":"monitor")

2. This example returns 1 if R&D is not in the list of values in the fieldname Department; returns 0 if R&D is in the list.@IsNotMember("R&D";Department)

3. This example returns Marketing in the field named Dept if the currentuser is not contained in the list in the field SalesDepartment; otherwiseSales is returned in the Dept field.FIELD Dept:=@If(@IsNotMember(@Username;SalesDepartment);"Marketing"; "Sales");

Chapter 5: Formula Language @Functions A–Z 279

@IsNumber

Indicates if a given value is a number (or a number list).

Syntax@IsNumber( value )

Parametervalue

Any data type. Any value.

Return valueflag

Boolean. Returns 1 (True) if the value is a number or a number list;otherwise returns 0 (False).

UsageThis is a useful function for checking to see that you have assigned fielddata types correctly.

Examples: @IsNumber1. This example returns 1.

@IsNumber(123)

2. This example returns 0.@IsNumber(@Created)

3. This example returns 1.@IsNumber(-345:2.78:997:.7)

4. This example returns 1 if the field named CostCenters contains a list ofnumber values; returns 0 if the list contains at least one text string.@IsNumber(CostCenters)

@IsResponseDocIndicates if a document is a response to another document.

Syntax

@IsResponseDoc

280 Domino Designer Programming Guide, Volume 1: Formula Language

Return valueflag

Boolean. Returns 1 (True) if the document is a response document;otherwise, returns 0 (False). Returns 0 for new documents, since@IsResponseDoc doesn’t recognize a document’s type until after thedocument is saved.

UsageA response document is one that was composed with a form whose type iseither Response or Response to Response. The designer uses the FormInfoBox to specify the type.

Example: @IsResponseDocThis example returns Response if the document is a response; Topic if thedocument is not a response.

@If(@IsResponseDoc;"Response";"Topic")

@IsTextIndicates if a value is text (or a text list).

Syntax@IsText( value )

Parametervalue

Any data type. Any value.

Return valueflag

Boolean. Returns 1 (True) if the value is text or a text list; otherwisereturns 0 (False).

Examples: @IsText1. This example returns 1.

@IsText("Blanchard & Daughters")

2. This example returns 1, if the field named BranchOffices contains thetext string list “New Orleans”:“Houston”:“Dallas”:“Mobile”.@IsText(BranchOffices)

Chapter 5: Formula Language @Functions A–Z 281

@IsTime

Indicates if a value is a time-date (or a time-date list).

Syntax@IsTime( value )

Parametervalue

Any data type. Any value.

Return valueflag

Boolean. Returns 1 (True) if the value is a time-date or a time-date list;otherwise returns 0 (False).

Examples: @IsTime1. This example returns 1 if the field named DueDate contains a

time-date value.@IsTime(DueDate)

2. This example returns 0.@IsTime(123)

@IsUnavailable

Indicates if a field name exists on a document.

Syntax@IsUnavailable( fieldname )

Parameterfieldname

The name of a field. Do not enclose the name in quotes.

Return valueflag

Boolean. Returns 1 (True) if the field name is not contained in thedocument; otherwise, returns 0 (False).

UsageUse @IsUnavailable to provide default values for fields in documentscreated with forms that do not include a particular field name.

282 Domino Designer Programming Guide, Volume 1: Formula Language

Caution Do not confuse @IsUnavailable with @Unavailable. @Unavailabledeletes fields and can cause serious damage if used unintentionally in placeof @IsUnavailable.

Example: @IsUnavailableThis example returns Consultant if the field Dept does not exist; if Deptdoes exist, the value contained in Dept is returned.

@If(@IsUnavailable(Dept);"Consultant";Dept)

@IsValidExecutes all validation formulas within the current form.

Syntax@IsValid

Return Valueflag

Boolean. Returns 1 (True) if all validation formulas resolve to True;otherwise, returns 0 (False).

UsageUse @IsValid to initiate execution of all of a form’s validation formulas, as ifthe document were being saved.

If validation formulas are added to a form after some documents havealready been saved, you can use @IsValid in a macro to determine which ofthose documents need corrections.

Example: @IsValidYou edit a form after it’s been in use for a while, and insert validationformulas into several fields. Now you want to test existing documents to besure they meet the field validation requirements. You can create anadditional field on the form and use this formula to indicate whether thedocument needs corrections:

@If(@IsValid;"Ok";"Needs corrections")

Chapter 5: Formula Language @Functions A–Z 283

@Keywords

Given two text lists, returns only those items from the second list that arefound in the first list.

Syntax@Keywords( textList1 ; textList2 ) or@Keywords( textList1 ; textList2 ; separator )

ParameterstextList1

Text list. A list of items.

textList2

Text list. A list of items that you want to compare to textList1.

separator

Text. One or more characters to be used as delimiters between words.@Keywords considers each character (not the combination of multiplecharacters) to be a delimiter. For example, defining separator as “. ,”(period, space, comma) tells the function that periods, spaces, andcommas are not to be considered parts of the words.

Return valueresultTextList

Text list. A list containing each item from textList2 that was also foundin textList1. If none of the items are found, returns a null string (“”). Inthe three-argument form, the returned value(s) are the result of exactlymatching characters and must be preceded by the separator defined inthe third argument.

UsageIn the two-argument form of the function, the default word delimiters are”, ? ! ; : [] () {} <> (double quotes, space, comma, question mark, exclamationpoint, semicolon, colon, brackets, parentheses, braces, and angle brackets).

This function is case sensitive; you must standardize the case of stringlist1and stringlist2 if you want case to be ignored (use @LowerCase,@ProperCase or @UpperCase).

Examples: @Keywords1. This formula returns Harvard;Yale;UCLA.

@Keywords("EPA Head speaks at Harvard,Yale":"UCLAChancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share research

284 Domino Designer Programming Guide, Volume 1: Formula Language

facilities";"Harvard":"Brown":"Stanford":"Yale":"Vassar":"UCLA")

2. This formula returns “”, a null string.@Keywords("EPA Head speaks at Harvard,Yale":"UCLAChancellor Retires":"Ohio State wins big game":"Reed andUniversity of Oregon share researchfacilities";"harvard":"brown":"stanford":"vassar":"ucla")

3. This formula returns Yale.@Keywords("EPA Head speaks at Harvard,Yale":"UCLAChancellor Retires":"Ohio State wins big game":"Reed and University of Oregon share researchfacilities";"Harvard":"Brown":"Stanford":"Yale":"UCLA";",")

@LanguagePreference

Returns user’s specified preferred language setting.

Note This function is new with Release 5.

Syntax@LanguagePreference ( key )

Parameterskey

Key. Specify a category for which you would like to get the preferredlanguage. The following categories are available:

[Region] Returns preferred language for region.

[Contents] Returns preferred language for database contents.

[AltName] Returns preferred language for alternate name.

Return valuepreferredlanguage

Text or Text list. Language and country code for user’s preferredsetting. [Region] language is set as the default. If @LanguagePreferencecannot find the language setting for the specified category, it returns thelanguage for [Region].

Chapter 5: Formula Language @Functions A–Z 285

Usage@LanguagePreference is used to implement mechanisms for handlinglanguage-dependent features. A database that is designed to store data inmultiple languages, can select the language in which the data should bepublished for each user by using @LanguagePreference[Contents].

For the language and country code format, please refer to the language tagstable in Language property of NotesName class.

Example: @LanguagePreferenceThe following example returns “fr” if your region language setting isFrench.

@LanguagePreference([Region])

@LeftSearches a string from left to right and returns the leftmost characters of thestring.

Syntax@Left( stringToSearch ; numberOfChars )@Left( stringToSearch ; subString )

ParametersstringToSearch

Text. The string whose leftmost characters you want to find.

numberOfChars

Number. The number of characters to return. If the number is 2, the firsttwo characters of the string are returned; if the number is 5, the first fivecharacters are returned, and so on.

subString

Text. A substring of stringToSearch. @Left returns the characters to theleft of subString. It finds subString by searching stringToSearch from leftto right.

Return valueresultString

Text. The leftmost characters in stringToSearch. The number ofcharacters returned is determined by either numberOfChars or subString.@Left returns “” if subString is not found in stringToSearch.

286 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Left1. This example returns Len.

@Left("Lennard Wallace";3)

2. This example returns Lennard Wal if the string in the field namedContact is Lennard Wallace.@Left(Contact;"la")

3. This example returns Tim if the string in the field named Author isTimothy Altman.@Left(Author;3)

4. This example returns Timothy if the string in the field named Author isTimothy Altman.@Left(Author;" ")

@LeftBackSearches a string from right to left and returns a substring.

Syntax@LeftBack( stringToSearch ; numToSkip ) or@LeftBack( stringToSearch ; startString )

ParametersstringToSearch

Text. The string whose leftmost characters you want to find.

numToSkip

Number. Counting from right to left, the number of characters to skip.All the characters to the left of that number of characters are returned.

startString

Text. A substring of stringToSearch. All the characters to the left ofstartString are returned.

Return valueresultString

Text. The leftmost characters in stringToSearch. The number ofcharacters returned is determined by either numToSkip or startString.

Chapter 5: Formula Language @Functions A–Z 287

Examples: @LeftBack1. This example returns Lennard Wall.

@LeftBack("Lennard Wallace";3)

2. This example returns Lennard.@LeftBack("Lennard Wallace"; " ")

3. This example returns Timothy Alt if the string in the field namedAuthor is Timothy Altman.@LeftBack(Author;3)

@LengthReturns the number of characters in a text string.

Syntax@Length( string ) or

@Length( stringlist )

Parametersstring

Text. A single string whose length you want.

stringList

Text list. A list of strings.

Return valuelength

If the parameter is a text string, @Length returns the number ofcharacters in the specified string, including spaces and punctuation.

If the argument is a text list, @Length searches the list of strings andreturns the number of characters in each string, as a number list.

Examples: @Length1. This example returns 45.

@Length("The boy crossed the wide, but gentle, stream.")

2. This example returns 0;5;3.@Length("": "abcde": "xyz")

288 Domino Designer Programming Guide, Volume 1: Formula Language

3. This example returns 16;10;17 if the contents of the fields From, Topic,and Date are Stephen Brewster, News Flash, and 09/02/95 16:45:10,respectively.@Length(From: Topic: @Text(Date))

@Like

Matches a string with a pattern. It is case-sensitive and supports theNotesSQL™ ODBC driver.

Syntax@Like( string ; pattern )@Like( string ; pattern ; escape )

Parametersstring

Text. The value to be tested to see if it matches pattern.

pattern

Text. The sequence of characters to search for within string. May alsocontain any of the wildcard characters listed below.

escape

Text. Optional. Used before a wildcard character to indicate that itshould be treated literally.

Wildcard characters and symbols are:

C Where C is any character. Matches any single, non-specialcharacter C

(Underscore). Matches any single character.

% Matches any sequence of zero or more characters.

Return values

flag

Number. Returns 1 (True) if the pattern matches the string. Otherwisereturns 0 (False).

Examples: @Like1. This example returns 0. The underscore matches only a single character.

@Like( "A big test" ; "A_test" )

Chapter 5: Formula Language @Functions A–Z 289

2. This example returns 1. The five underscores match“<space>big<space>”. @Like( "A big test" ; "A_____test" )

3. This example returns 1. The % matches “A big ”.@Like( "A big test" ; "%test" )

4. This example returns 0. @Like is case-sensitive.@Like( "A big test" ; "A BIG test" )

5. This example returns 1. The first percent matches “100”. The “/%”matches the percent sign because “/” is specified as the escapecharacter. The last percent matches “ement”.@Like( "A 100% improvement" ; "A %/% improv%" ; "/" )

@Ln

Returns the natural log of a number. Natural logs use e (approximately2.718282) as their base.

Syntax@Ln( number )

Parameternumber

Number. May be any value greater than 0, and can contain up to 15decimal places.

Return valuenaturalLog

Number. The natural log of number.

UsageUse @Ln in formulas requiring natural logs, such as compound growth orloss.

@Ln is the inverse of @Exp.

Example: @LnThis example returns 0.693147180559945.

@Ln(2)

290 Domino Designer Programming Guide, Volume 1: Formula Language

@Locale

Returns the language name for the specified Notes internal language code.

Note This @function is new with Release 5.

Syntax@Locale( action )

@Locale( action; locale-tag )

Parameterlocale-tag

Text or text list. The language code to be retrieved.

action

Specify the return value by selecting one flag from the following table:

Flag Description Return value

[NotesLocale] Locale informationNotes can support

Returns locale code used in Notes. If you specify a locale-tag, it would be mapped to a suitable Notes localecode. If you do not specify a locale-tag,returns a full list of Notes locales.

[AltNameLocale] Locale informationavailable for AltName

Returns locale code used in Notes for alternate name. If you specify alocale-tag, it would be mapped to asuitable alternate name locale code. Ifyou do not specify a locale-tag, returnsa full list of alternate name locales.

[LanguageName] Locale information forlanguage name. Youmust specify locale-tagto use this action.

Returns fully spelled language name.If no match is found, the locale-tag willbe returned. Returns “English” for the“en-us” locale-tag.

[CountryName] Locale information forcountry name. Youmust specify locale-tagto use this action.

Returns fully spelled country name. Ifno match is found, the locale-tag willbe returned. Returns “United States”for the “en-us” locale-tag.

[CntryLangName] Locale information fora combination oflanguage name andcountry name. Youmust specify locale-tagto use this action.

Returns a combination of fully spelledlanguage name and country name. Ifno match is found, the locale-tag willbe returned. Returns “English(UnitedStates)” for the “en-us” locale-tag.

Chapter 5: Formula Language @Functions A–Z 291

UsageYou can use this @function to create a field which will store locale code.Using the list operation, you can create a keyword list for the field such as“French | fr” : “French(Canada) | fr-CA” : “English | en”.

Examples: @Locale1. The following formula returns “French”.

@Locale( [LanguageName]; "fr" )

@Locale( [LanguageName]; "fr-CA" )

2. The following formula returns “Canada”.@Locale( [NotesLocale] : [CountryName]; "fr-CA" )

3. The following formula returns “fr-CA”.@Locale( [NotesLocale]; "fr-CA" )

4. The following formula returns “fr”@Locale ( [AltNameLocale]; "fr-CA" )

5. The following formula returns “French(Canada)”.@Locale ( [CntryLangName]; "fr-CA" )

6. The following formula can be used to create a keyword list for analternate language code field.localeList :=@Locale([AltNameList]);

@Locale([CntryLangName]; localeList) +"|" + localelist

@LogReturns the common logarithm (base 10) of any number greater than zero.

Syntax@Log( number )

Parameternumber

Number. Must be greater than zero.

Return valuecommonLog

Number. The log of number.

292 Domino Designer Programming Guide, Volume 1: Formula Language

UsageUse @Log in any formula requiring a common log, such as the formula tocalculate the root of a number. @Log is the reciprocal of scientific notation.

Examples: @Log1. This example returns 0.602059991327962.

@Log(4)

2. This example returns 14.@Log(1.0E+14)

@LowerCaseConverts the uppercase letters in the specified string to lowercase.

Syntax@LowerCase( string )

Parameterstring

Text. The string you want to convert to lowercase.

Return valuelowerCaseString

Text. The string, converted to lowercase letters.

UsageThis function is useful when you want to search for a particular value andcannot predict whether it will appear in lowercase or uppercase letters, or acombination of the two. You can also use it as an input translation formulato convert a field’s contents to lowercase.

Examples: @LowerCase1. This example returns juan mendoza.

@LowerCase("Juan Mendoza")

2. This example returns arm chair if the Furniture field contains “Arm Chair”, “Arm chair”, “arm chair”, or “ARM CHAIR”, or any other variation.@LowerCase(Furniture)

Chapter 5: Formula Language @Functions A–Z 293

3. This example returns fletcher if William Fletcher is the name associatedwith the current User ID.@LowerCase(@Right(@UserName;" "))

@MailDbName

Returns the name of the Domino server and the name of the current user’sMail database.

Syntax@MailDbName

Return valueserver ; path

Text list with two elements. server is the name of the server on whichthe current database resides, or the null string if the database is local.path is the directory and file name of the database.

UsageThis function works in any formula except column formulas. When aformula runs on a server, the server is considered the current user, so@MailDbName returns the name of the server.

The returned value is formatted as a two-item text list specifying theServer;Directory\Database.NSF, as in:

acmemail;legal\dlee.nsF

If the database is stored on the user’s own computer, Notes returns the nullstring for the server name. For example, dial-up user Debbie Lee may keepa local replica of her Mail database on her workstation; when she is set upfor workstation-based mail, @MailDbName returns:

;dlee.nsf

This is useful in applications that send mail; for example, you can use it todetermine whether the current user is set up for server-based mail, anddetermine the appropriate course of action based on the result.

You cannot use this function in Web applications.

Examples: @MailDbName1. This example returns ;mtsen.nsf if the user’s mail is in the mtsen.nsf

database stored on the user’s own computer and the user is set up touse workstation-based mail.@MailDbName

294 Domino Designer Programming Guide, Volume 1: Formula Language

2. This example returns sales1;mail\mtsen.nsf if the user’s mail is storedin mtsen.nsf in the mail directory on the sales1 server and the user is setup to use server-based mail. If the database is stored at the server’sroot directory (that is, it is not stored in a subdirectory), the resultwould be sales1;mtsen.nsf.@MailDbName

3. This example returns mtsen.nsf, the file name, since this is the lastelement in the list returned by @MailDbName.@Subset(@MailDbName;-1)

@MailEncryptSavedPreference

Indicates whether the user has selected “Encrypt saved mail” in the UserPreferences dialog box.

Syntax@MailEncryptSavedPreference

Return Valueflag

Boolean. Returns 1 (True) if “Encrypt saved mail” is selected; otherwise,returns 0 (False).

Usage@MailEncryptSavedPreference is used in the Mail template to determinewhether to encrypt saved memos. This function is not available in columnformulas, selection formulas, or selective replication formulas.

You cannot use this function in Web applications.

Example: @MailEncryptSavedPreferenceYou design your own Mail form. To determine whether memos created with your form and then saved should be encrypted, use @MailEncryptSavedPreference to determine the current user’s preference.This returns 1 if the “Encrypt saved mail” check box is selected in the UserPreferences dialog box, and 0 if the Encrypt saved mail check box is notselected.

@MailEncryptSavedPreference

Chapter 5: Formula Language @Functions A–Z 295

@MailEncryptSentPreference

Indicates whether the user has selected “Encrypt sent mail” in the UserPreferences dialog box.

Syntax@MailEncryptSentPreference

Return Valueflag

Boolean. Returns 1 (True) if “Encrypt sent mail” is selected; otherwise,returns 0 (False).

Usage@MailEncryptSentPreference is used in the Mail template to determinewhether to encrypt sent memos. This function is not available in columnformulas, selection formulas, or selective replication formulas.

You cannot use this function in Web applications.

Example: @MailEncryptSentPreferenceYou design your own Mail form. To determine whether outgoing memosshould be encrypted automatically, use @MailEncryptSentPreference todetermine the user’s preference. This returns 1 if the “Encrypt sent mail”check box is selected in the User Preferences dialog box and 0 if the Encryptsent mail check box is not selected.

@MailEncryptSentPreference

@MailSavePreferenceIndicates which option the user has selected for the “Save sent mail” settingin the User Preferences dialog box.

Syntax@MailSavePreference

Return Valueflag

Integer. Returns 0 if “Don’t keep a copy” is selected, 1 if “Always keepa copy” is selected, and 2 if “Always prompt” is selected.

296 Domino Designer Programming Guide, Volume 1: Formula Language

Usage@MailSavePreference is used in the Mail template to determine whether tosave copies of outgoing memos. This function is not available in columnformulas, selection formulas, or selective replication formulas.

You cannot use this function in Web applications.

Example: @MailSavePreferenceYou design your own Mail form. To determine whether outgoing memosshould be automatically saved, use @MailSavePreference to determine theuser’s preference. This returns 2 if the “Save sent mail” list has “Alwaysprompt” selected, 1 if the “Save sent mail” list has “Always keep a copy”selected, and 0 if the “Save sent mail” list has “Don’t keep a copy” selected.

@MailSavePreference

@MailSendThere are two ways to use @MailSend:

When used with no parameters, @MailSend mails the current document(the one being processed when the @function is evaluated) to therecipient designated in the document’s SendTo field. The documentmust have a SendTo field.

When used with one or more parameters, @MailSend composes a newmail memo based on the information you supply in the arguments list,and sends it to the recipients listed in the sendTo, copyTo, andblindcopyTo arguments.

Syntax@MailSend@MailSend( sendTo ; copyTo ; blindCopyTo ; subject ; remark ; bodyFields ; [ flags ] )

ParameterssendTo

Text or text list. The primary recipient(s) of the mail memo.

copyTo

Text or text list. Optional. The copy recipient(s) of the mail memo.

blindCopyTo

Text or text list. Optional. The blind copy recipient(s) of the mail memo.

Chapter 5: Formula Language @Functions A–Z 297

subject

Optional. Text. Optional. The text you want displayed in the Subjectfield. This is equivalent to the Subject field on a mail memo; themessage is displayed in the Subject column in the views in therecipients’ mail databases.

remark

Text. Optional. Any text you want at the beginning of the memo’s body field.

bodyFields

Text. The names of one or more fields from the current document thatyou want included in the mail memo. The fields must be of type text ortext list, and are appended to the memo in the order in which you listthem. (You can store @Text of a numeric field in a variable and use thevariable name as a field name.) Enclose each field name in quotationmarks. If you want to list multiple fields, use the list format:“description”:“issues”:“resolution”. If you store the name of the field ina variable, omit the quotation marks here.

When you use the [IncludeDocLink] flag (described below) to includea link to the current document, you should set the bodyFieldsparameter to null (“”). If Notes cannot locate a field by name, it uses thestring literal instead.

[ flags ]

One or more flags indicating the memo’s priority and security. If youspecify multiple flags, format them as a list, as in[Sign]:[PriorityHigh]:[ReturnReceipt]. Enclose each flag in squarebrackets as shown.

The available flags are:

[Sign]

Electronically sign the memo when mailing it, using information fromthe user’s ID. Signing will not occur unless you include this flag.

[Encrypt]

Encrypt the document using the recipient’s public key, so that only therecipient whose private key matches can read the document.Encryption will not occur unless you include this flag.

[PriorityHigh]

Immediately routes the message to the next-hop server as defined bythe combination of Mail Connection records and server records. If aphone call has to be made in order to route the message, then the call is

298 Domino Designer Programming Guide, Volume 1: Formula Language

placed immediately, regardless of the schedule set in the RemoteConnection record. If you omit this flag, the priority defaults to Normal.

[PriorityNormal]

Routes the message to the next-hop server based on the scheduledefined in the Mail Connect records. If the recipient’s mail file resideson a server on the same Domino network, then delivery occursimmediately. If you omit this flag, the priority defaults to Normal.

[PriorityLow]

Routes the message overnight if the recipient’s mail file does not resideon a server on the same Notes network. If the recipient’s mail file doesreside on a server on the same Notes network, then delivery occursimmediately. Low Priority mail can also be controlled by a Notesenvironment variable called MailLowPriorityTime=x, where x is equalto a number from 0 to 23. When placed in the server notes.ini file, thisvariable tells the server when to route Low Priority mail. If you omitthis flag, the priority defaults to Normal.

[ReturnReceipt]

Notify the sender when each recipient reads the message. No receipt isreturned unless you include this flag.

[DeliveryReportConfirmed]

Notify the sender whether delivery of the memo was successful or not.By default, the Basic delivery report is used, which notifies the senderonly when a delivery failure occurs.

[IncludeDocLink]

Include a link pointing to the document that was open or selected when@MailSend was used. You must include this flag if you want thatdocument linked to the mail memo.

UsageUse @MailSend in agents, buttons, form actions, view actions, andSmartIcons. @MailSend is especially useful with scheduled agents as ameans of sending mail at a predetermined interval, for example, to sendreminders about a departmental meeting. This function does not work incolumn, selection, hide-when, or window title formulas.

If the user’s notes.ini file includes the statement

NoExternalApps=1

then any formula involving @MailSend is disabled. The user doesn’t see anerror message; the formula will fail to execute.

You cannot use this function in Web applications.

Chapter 5: Formula Language @Functions A–Z 299

Sending rich text fieldsIf you use @MailSend in a button formula, you cannot send the contents of a rich-text field as one of the bodyfields. If you must send rich text, writean agent formula instead. If you must use a button, change the field type to text.

Mail-related fields on a documentWhen you use @MailSend with no parameters, the current document maycontain one or more mail-related fields; if it does, those fields are usedwhen routing the document.

If the document contains the CopyTo or BlindCopyTo fields, it is routedto those recipients at the same time.

If the document contains the DeliveryPriority, DeliveryReport, orReturnReceipt fields, they are used to control the delivery priority,generation of a delivery report, and generation of a return receipt, justas it’s done when you use the Actions - Send Document command. Ifthe document doesn’t contain these fields, they default to normalpriority, no delivery report, and no return receipt, respectively.

Examples: @MailSend1. This formula sends a memo to David Lee with a blind copy to Joseph

Smith in Support. The memo is titled “Status Report”, and its bodycontains the message “Sorry it’s late!” plus the contents of the STATUSand PLANS fields from the current document. The document is mailedwith the following options: it is signed, delivery confirmation isrequested, and a return receipt will be sent when each recipient readsthe memo. The recipients are listed using distinguished naming syntax(available to Release 3 users only). The copyTo information wasomitted, and was replaced with the null string because additionalarguments follow.@MailSend("David Lee/";"";"Joseph Smith/Support";"StatusReport"; "Sorry it's late!"; "STATUS":"PLANS"; [Sign] :[DeliveryReportConfirmed] : [ReturnReceipt])

2. This formula sends a memo to Mary Tsen and to Joseph Smith inSupport. The subject uses the text stored in the current document’sTOPIC field, and the body of the memo draws from the COMMENTSfield. The copyTo, blindCopyTo, and remark arguments were omitted,and were replaced with null strings because additional arguments stillfollowed. The flags were omitted but because no arguments followedtheir position, the null string was not needed.@MailSend("Mary Tsen/":"JosephSmith/Support";"";"";TOPIC;""; "COMMENTS")

300 Domino Designer Programming Guide, Volume 1: Formula Language

3. This formula sends a memo to Mary Tsen with the message “Followthis link” in the Subject field, and a link to the original document in theBody field.@MailSend("Mary Tsen/";"";"";"Follow thislink";"";"";[IncludeDocLink])

@MailSignPreferenceIndicates whether the user has selected “Sign sent mail” in the UserPreferences dialog box.

Syntax@MailSignPreference

Return Valueflag

Boolean. Returns 1 (True) if “Sign sent mail” is selected; otherwise,returns 0 (False).

Usage@MailSignPreference is used in the Mail template to determine whether toattach an electronic signature to outgoing memos. This function is notavailable in column formulas, selection formulas, or selective replicationformulas.

You cannot use this function in Web applications.

Example: @MailSignPreferenceYou design your own Mail form. To determine whether outgoing memosshould be electronically signed, use @MailSignPreference to determine theuser’s preferences. This returns 1 if the “Sign sent mail” check box isselected in the User Preferences dialog box, and 0 if the “Sign sent mail”check box is not selected.

@MailSignPreference

Chapter 5: Formula Language @Functions A–Z 301

@Matches

Tests a string for a pattern string. Because the pattern string can contain anumber of “wildcard” characters and logical symbols, you can test forcomplex character patterns.

Syntax@Matches( string ; pattern )

Parametersstring

Text. The string you want to scan.

pattern

Text. The pattern you want to scan for in string. May contain wildcardcharacters and symbols (see table below). The following symbolsrequire a preceding backslash unless the pattern is enclosed in braces { }as a set: ?, *, &, !, |, \, +. The symbols require two precedingbackslashes instead of one if the pattern is specified as a literal. This isbecause the backslash is an escape character in string literals, so “\?”passes “?” to the matching engine where it is treated as a wildcard,while “\\?” passes “\?” to the matching engine where it is treated as aquestion mark character.

Return valueflag

Boolean. 1 (True) if the string contains the pattern; 0 (False) if the stringdoes not contain the pattern.

The wildcard characters and symbols are:

Symbol Use

C Where C is any character. Matches any single, non-special character C

? Matches any single character

* Matches any string (any number of characters)

{ABC} Matches any character in set ABC

{A-FL-R} Matches any character in the sets A...F and L...R

+C Matches any number of occurrences of C

! Complements logical meaning of the pattern (logical NOT)

| Performs logical OR of two patterns

& Performs logical AND of two patterns

302 Domino Designer Programming Guide, Volume 1: Formula Language

Note When specifying sets, be sure to enclose them in { } (curly braces) Forexample, the set A...F is represented as {A-F}.

Examples of pattern matching:

Pattern Matches

ABC “ABC”

A?C Any three-character string that starts with “A” and ends with “C”

??? Any three-character string

+? Any string, including the null string

+?{A-Z} Any string that ends in a letter

+{!A-Z} Any string that does not contain a letter

Examples: @Matches1. This example returns 0.

@Matches("A big test";"a?test")

2. This example returns 1.@Matches("A big test";"a?????test")

3. This example converts the contents of the State field to lowercase, andreturns 1 for any value in the field that contains “mont”, for exampleVermont or Montana.@Matches(@Lowercase(State);"*mont*")

4. This example is the default value formula for a field namedSalesNumber. The formula returns the number 224 if the contents of thefield named Division is either Central or Midwest. If the contents ofDivision is anything else, the formula returns the number 124.@If(@Matches(Division;"Central | Midwest");224;124)

@MaxGiven two numbers, returns the larger number.

Syntax@Max( number1 ; number2 )

Chapter 5: Formula Language @Functions A–Z 303

Parametersnumber1

Number or number list.

number2

Number or number list.

Return valuemaxNumber

Number or number list. Either number1 or number2, whichever is larger.If the parameters are number lists, @Max returns a list that is the resultof pair-wise computation on the list values; negative numbers in listsmust be enclosed in parentheses.

UsageWhen using this function with a number list, the list concatenation operatortakes precedence over any other operators.

For more information, see “List Operator.”

Examples: @Max1. This example returns 3.

@Max(1;3)

2. This example returns 99;6;7;8.@Max(99:2:3;5:6:7:8)

3. This example returns -2; 45; 54.@Max((-2.6):45:(-25);(-2):(-50):54)

4. This formula finds the larger of the values in the fields namedCommission and Salary, and compares the value to 50,000; if it is largerthan 50,000, the field named Bonus is changed to 0; if it is smaller than50,000, Bonus becomes 10% of the value in the Salary field.FIELD Bonus:=@If(@Max(Commission;Salary)>50000; 0; (0.10 * Salary));

@MemberGiven a value, finds its position in a text list.

Syntax@Member( value ; stringlist )

304 Domino Designer Programming Guide, Volume 1: Formula Language

Parametersvalue

Text. The value whose position in stringlist you want to find.

stringlist

Text list.

Return valueposition

Number. Returns 0 if the value is not contained in stringlist; returns 1 ton if the value is contained in the stringlist, where 1 to n is the position ofthe value in the stringlist.

Examples: @Member1. This example returns 0.

@Member("Sales";"Finance":"Service":"Legal")

2. This example returns 12 if the value in the field named ReportName isthe 12th value in a list contained in the field named RequiredReading;otherwise returns 0.@Member(ReportName;RequiredReading)

@MiddleReturns any substring from the middle of a string. The middle is found byscanning the string from left to right, and parameters determine where themiddle begins and ends.

Syntax@Middle( string ; offset ; numberchars ) @Middle( string ; offset ; endstring ) @Middle( string ; startString ; endstring ) @Middle( string ; startString ; numberchars )

Parametersstring

Text. Any string.

offset

Number. A character position in string that indicates where you wantthe middle to begin, always counting from left to right. The middlebegins one character after the offset.

Chapter 5: Formula Language @Functions A–Z 305

startString

Text. A substring of string that indicates where you want the middle tobegin, always counting from left to right. The middle begins onecharacter after the end of startString.

numberchars

Number. The number of characters that you want in the middle. Ifnumberchars is negative, the middle starts at offset or startString andcontinues from right to left. If numberchars is positive, the middle startsone character past the offset or startString and continues from left toright.

endstring

Text. A substring of string that indicates the end of the middle. @Middlereturns all the characters between offset and endstring or betweenstartString and endstring.

Return valuemiddle

Text. The substring from the middle of string, which begins at the offsetor startString you specify and ends at the endstring you specify, or afterthe numberchars have been reached.

Examples: @Middle1. This example returns h C. The offset is positioned at the “t” (the fourth

character from the left), and the count starts with the first character afterthe offset, moving from left to right.@Middle("North Carolina";4;3)

2. This example returns ort. The offset is positioned at the “t” (the fourthcharacter from the left), and the count begins at the offset, moving fromright to left.@Middle("North Carolina";4;-3)

3. This example returns Car. The offset is positioned at the first space inthe string “North Carolina” and the count starts with the first characterafter the offset.@Middle("North Carolina";" ";3)

4. This example returns or. The offset is positioned at the substring “th”and the count starts with the first character after the entire offset,moving from right to left.@Middle("North Carolina";"th";-2)

306 Domino Designer Programming Guide, Volume 1: Formula Language

5. This example returns space, is the, space. The return string iseverything from the fifth character through the character before text.@Middle("This is the text"; 4; "text")

6. This example returns space, the, space. The return string is everythingafter is and before text.@Middle("This is the text"; "is"; "text")

@MiddleBack

Returns any substring from the middle of a string. The middle is found byscanning the string from right to left, and parameters determine where themiddle begins and ends.

Syntax@MiddleBack( string ; offset ; numberchars )@MiddleBack( string ; offset ; endstring )@MiddleBack( string ; startString ; endstring )@MiddleBack( string ; startString ; numberchars )

Parametersstring

Text. Any string.

offset

Number. A character position in string that indicates where you wantthe middle to begin, always counting from right to left. The middlebegins one character after the offset.

startString

Text. A substring of string that indicates where you want the middle tobegin, always counting from right to left. The middle begins onecharacter after the end of startString.

numberchars

Number. The number of characters that you want in the middle. Ifnumberchars is negative, the middle starts at offset or startString andcontinues from right to left. If numberchars is positive, the middle startsone character past the offset or startString and continues from left toright.

Chapter 5: Formula Language @Functions A–Z 307

endstring

Text. A substring of string that indicates the end of the middle.@MiddleBack returns all the characters between offset and endstring orbetween startString and endstring.

Return valuemiddle

Text. The substring from the middle of string, which begins at the offsetor startString you specify and ends at the endstring you specify, or afterthe numberchars have been reached.

Examples: @MiddleBack1. This example returns Alt if the contents of the field called Author is

Timothy Altman.@MiddleBack(Author;" ";3)

2. This example returns a blank if the contents of the field named Authoris any string with no spaces, for example “Smith”.@MiddleBack(Author;" ";3)

3. This example returns: from right to left.@MiddleBack("Middleback searches the string from right toleft"; "ing";25)

4. This example returns: searches the string.@MiddleBack("@MiddleBack searches the string from right toleft"; "from"; -20)

5. This example returns space, is the, space. The return string iseverything from the fourth to the last character through the characterafter This.@MiddleBack("This is the text"; 4; "This")

6. This example returns space, the, space. The return string is everythingbefore text and before is.@MiddleBack("This is the text"; "text"; "is")

@MinGiven two numbers, returns the smaller number.

Syntax@Min( number1 ; number2 )

308 Domino Designer Programming Guide, Volume 1: Formula Language

Parametersnumber1

Number or number list.

number2

Number or number list.

Return valueminNumber

Number or number list. Either number1 or number2, whichever issmaller. If the parameters are number lists, @Min returns a list that isthe result of pair-wise computation on the list values; negativenumbers in lists must be enclosed in parentheses.

UsageWhen using this function with a number list, the list concatenation operatortakes precedence over any other operators.

For more information, see “List Operator.”

Examples: @Min1. This example returns 35.

@Min(35;100)

2. This example returns 5;2;3;3.@Min(99:2:3;5:6:7:8)

3. This example returns the contents of the field containing the smallestvalue. If Precinct1 contains 150,000 and Precinct2 contains 100,000, thenthis formula returns 100,000.@Min(Precinct1;Precinct2)

4. This example returns 85,000 if 100,000 is the smallest number containedin either of the fields AreaAPopulation or AreaBPopulation, and thefield DistrictPopulation contains the value 15,000.@Min(AreaAPopulation;AreaBPopulation) - DistrictPopulation

5. This example returns -3.5;-35;54.@Min((-3.5):(-35):100;(-2):45:54)

Chapter 5: Formula Language @Functions A–Z 309

@Minute

Extracts the number of minutes from the specified time-date.

Syntax@Minute( time-date )

Parametertime-date

Time-date.

Return valueminutes

Number. The number of minutes in the minute part of the time.

Examples: @Minute1. This example returns 30.

@Minute([9:30])

2. This example returns 56 if the Time field contains 8:56:34 P.M.@Minute(Time)

3. This example returns 59 if the Date field contains: 7/30/95 9:59:59.@Minute(Date)

4. This example returns 00 if the current document’s created date was9/29/95 3:00:12 A.M.@Minute(@Created)

@Modified

Returns a time-date value indicating when the document was last editedand saved.

Syntax@Modified

Return valuelastModified

Time-date. The date that the current document was last modified.

Usage@Modified works correctly only in column formulas. When used incomputed field or computed-for-display formulas, @Modified returns a

310 Domino Designer Programming Guide, Volume 1: Formula Language

value representing the next-to-last time the document was saved. Thisfunction does not work in mail agent, paste agent, hide-when, sectioneditor, or form formulas.

@Modified is similar to @Accessed, which indicates the last time adocument was accessed for reading or writing.

Examples: @Modified1. This example returns 9/30/95 11:00:00 AM if the document was last

saved on September 30, 1995 at 11:00 A.M.@Modified

2. This example returns a string made up of the contents of the fieldnamed Topic, then a space, then the string Last Edited: and then thetime-date value of the last time the document was saved, converted totext.Topic + " " + "Last Edited: " + @Text(@Modified)

@ModuloReturns the remainder of a division operation.

Syntax@Modulo( number1 ; number2 )

Parametersnumber1

Number or number list.

number2

Number or number list. If this is equal to 0, @Modulo returns @ERROR.

Return valueremainder

Number or number list. The remainder of number1 divided by number2.If the parameters are number lists, @Modulo returns a list that is theresult of pair-wise computation on the list values. The sign of the resultis always the same as the sign of the number1.

UsageA common use of @Modulo is to determine whether a number is odd oreven; if the result of @Modulo(number;2) is 1, the number is odd; if theresult is 0, the number is even.

Chapter 5: Formula Language @Functions A–Z 311

When using this function with a number list, the list concatenation operatortakes precedence over any other operators; negative numbers must beenclosed in parentheses.

For more information, see “List Operator” in the Formula Language Rules chapter.

Examples: @Modulo1. This example returns 1.

@Modulo(4;3)

2. This example returns 0.@Modulo(4;2)

3. This example returns -2.@Modulo((-14);3)

4. This example returns -1;2;3;-3.@Modulo((-4):6:8:(-9);3:4:5:6)

@MonthExtracts the number of the month from the specified time-date.

Syntax@Month( time-date )

Parametertime-date

Time-date.

Return valuemonth

Number. The number of the month.

Examples: @Month1. This example returns 1.

@Month([1/15/88])

2. This example returns 12 if it is December.@Month(@Now)

312 Domino Designer Programming Guide, Volume 1: Formula Language

3. This example returns 2 if it is any date in December other than the 30thor 31st. If it is December 30 or 31, returns 3.@Month(@Adjust(@Now;2;2;2;2;2;2))

4. This formula returns a formatted date string based on the contents ofthe dueDate field. For example, if dueDate contains “06/26/95” theformula returns June 26, 1995. If dueDate contains “01/24/96 3:40:43P.M.” the formula returns January 24, 1996.space:= " ";comma:=",";month:=@Select(@Month(dueDate);"January";"February";"March";"April";"May";"June";"July";"August";"September";"October";"November";"December");day:=@Text(@Day(dueDate));year:=@Text(@Year(dueDate));month + space + day + comma + space + year

@NameLets you manipulate hierarchical names. You can abbreviate the canonicalformat of a name, expand an abbreviated name to its canonical format,identify particular components within the name, and reverse the order ofthe components so you can categorize a view by hierarchical names.

Syntax@Name( [ action ] ; name )

Parameters[ action ]

Indicates what you want done to the name — whether you want toexpand it, abbreviate it, and so on (see list of possible actions below).

name

Text or names. A user or server name, entered in any form. Notesdetermines the full hierarchical name and then returns the requestedcomponents.

With @Name, you can perform the following actions on a hierarchicalname:

[A]

Returns the ADMD component (administration management domain name).

Chapter 5: Formula Language @Functions A–Z 313

[Abbreviate]

Abbreviates a hierarchical name, removing the component labels. Thissaves space in the display, and looks friendlier.

[Address821] (Case must be exact) New with Release 5.

Returns an Internet address in the format based on RFC 821 AddressFormat Syntax regardless of whether the original address was in RFC821 or RFC 822 form.

[C]

Returns the country component of a hierarchical name.

[Canonicalize]

Expands an abbreviated name, adding in whatever components aremissing, as well as their labels. Missing components are taken from thecurrent user ID, not the Address Book.

[CN]

Returns the common name component of the name.

[G]

Returns the given name component (the first name).

[HierarchyOnly] New with Release 5.

Strips the CN component of a hierarchical name and returns theremaining components.

[I]

Returns the initials component.

[LP] New with Release 5.

Returns the LocalPart of a standard Internet address based on RFC 822Address Format Syntax.

[O]

Returns the organization component of the hierarchical name.

[OUn]

Returns the specified organizational unit component of the name; n canbe from 1 to 4, as in OU1. In the canonical form of the name, the OUcomponents are not numbered; however, they are counted from right toleft so that the first occurrence of the OU label is treated as OU1, thesecond occurrence is treated as OU2, and so on. Notes will not accept[OU] as a keyword.

[P]

314 Domino Designer Programming Guide, Volume 1: Formula Language

Returns the PRMD component (private management domain name).

[PHRASE] New with Release 5.

Returns the Phrase part of a standard Internet address based on RFC822 Address Format Syntax.

[Q]

Returns the generation component (such as “Jr”).

[S]

Returns the surname component (the last name).

[ToKeyword]

Reverses the order in which the naming components are displayed, andreplaces slashes with backslashes: Country\Organization\OrganizationUnit... This is useful when you want to categorize a view by thecomponents of a user’s hierarchical name (backslashes representsubcategories in views). The [ToKeyword] option does not return theCommon Name portion of the user name.

Usage@Name is particularly useful for abbreviating hierarchical names in a view.

A hierarchical name is qualified with a series of components identifying thefull name, organizational unit, organization, and country. Usinghierarchical names guarantees that each user and server has a unique name.

As the database designer, you are responsible for controlling how usernames are entered and displayed within Notes applications. For simplicity,you should allow users to enter names in abbreviated form; then you canuse @Name to expand the name to its canonical format. You should alsodisplay names in abbreviated form, using @Name to convert the storedcanonical format of the name to its abbreviated form.

When you use a Names, Readers, or Authors field, Notes automaticallyconverts hierarchical names to an appropriate format for display andstorage. If the user enters an abbreviated name, Notes expands it tocanonical format when storing it; the name is always displayed in a form inabbreviated format.

When you display the contents of a hierarchical name field in a view thereis no automatic conversion; the entire canonical format of the name isdisplayed. You may want to convert the name to its abbreviated form with@Name.

Chapter 5: Formula Language @Functions A–Z 315

Note If you attempt to use the parameters A, G, I, P, Q, & S in Notes withexisting User IDs, it may appear as though the parameters do not work.These parameters were added to take advantage of the addressing used forexternal mail and gateway products. When a mail message is receivedwithin Notes from an external mail source, the naming convention caninclude additional components. The @Name function can be used tomanipulate the hierarchical name, including these additional components.Notes IDs and names do not use these additional components, therefore, it is not possible to use these six parameters with a standard Notes ID and name.

Below, is an example of a full hierarchical name that takes advantage ofevery parameter.

G=Joe/I=JS/S=Smith/Q=Jr/CN=Joseph Smith/OU=Assembly/OU=Engineering/O=Acme/P=PrivAdmin/ A=PubAdmin/C=USA

Examples: @Name1. This example returns Mary Tsen/Illustration/

Documentation/Development/R&D/WorkSavers/US.@Name([Abbreviate];AUTHOR)

If a user is looking at a document where the AUTHOR field containsthe hierarchical form of Mary Tsen’s name.

2. This example returns Mary Tsen.@Name([Canonicalize];"Mary Tsen")

Since there is no slash following the name, it is a non-hierarchical name and has no additional components.

3. This example returnsCN=MaryTsen/OU=Illustration/OU=Documentation/OU=Development/OU=R&D/O=Acme/C=US if that is the current user ID. The hierarchy of the current user ID is appended to the name; no lookup occurs in the Address Book.@Name([Canonicalize];"Mary Tsen/")

4. This example returns Mary Tsen in an informational dialog box format, if the AUTHOR field in the document contains: CN=Mary Tsen/OU=Illustration/O=Acme.@Prompt([OK]; "Common Name"; @Name([CN]; AUTHOR))

5. This example returns Development.@Name([OU2];AUTHOR)

316 Domino Designer Programming Guide, Volume 1: Formula Language

6. This example returnsUS\Acme\R&D\Development\Documentation\Illustration. Theslashes are now backslashes, which allow the naming components to be used as subcategories in a view. The common name component isnot returned.@Name([ToKeyword];AUTHOR)

7. This example returns SStreitfeld if the User_Name field contains thisInternet address in RFC 822 format “Streitfeld, Sara (Miami)”<SStreitfeld@gazette.com>.@Name([LP];User_Name)

8. This example returns “Streitfeld, Sara (Miami)” if the User_Name fieldcontains this Internet address in RFC 822 format “Streitfeld, Sara(Miami)” <SStreitfeld@gazette.com>.@Name([Phrase];User_Name)

9. This example returns SStreitfeld@gazette.com if the User_Name fieldcontains this Internet address in RFC 822 format “Streitfeld, Sara(Miami)” <SStreitfeld@gazette.com>.@Name([Address821];User_Name)

10. This example returns Cam/Lotus If the User_Name field contains JohnDoe/Cam/Lotus@Name([HierarchyOnly];User_Name)

@NameLookup

Searches for each specified username across all NABs and returns a list ofsingle text values for each specified username.

Note This @function is new with Release 5.

Syntax@NameLookup( [ flag ] ; username; itemtoreturn )

Parameters[ flag ]

Search mechanism. The following legal values correspond to this parameter:

[NOUPDATE] Default flag for @NameLookup. Returns a list ofusernames. Corresponds to NAME_LOOKUP_NOUPDATE flag forNotes API. You can specify this flag along with the other flagsexcluding [FORCEUPDATE].

Chapter 5: Formula Language @Functions A–Z 317

[FORCEUPDATE] This flag forces the name space (view) to beupdated. Corresponds to NAME_LOOKUP_UPDATE flag for NotesAPI. You can specify this flag along with the other flags excluding[NOUPDATE].

You can specify one of the following flags along with the[NOUPDATE] or [FORCEUPDATE] flag.

[NOSEARCHING] Searches only the first NAB containing the“($Users)” view, and returns a list of single text values for eachspecified username. An empty string is returned for no match found.Corresponds to NAME_LOOKUP_NOSEARCHING flag for Notes API.

[EXHAUSTIVE] Searches all NABs listed in NAMES variable innotes.ini and returns all information in a text list. The user’s value isomitted if there is no match found.

[TRUSTEDONLY] Searches only those NABs that contain trustinformation and returns a list of single text values for each specifiedusername. An empty string is returned for no match found.Corresponds to NAME_LOOKUP_TRUSTED_NAMESPACES flag forNotes API.

All the users from the secondary directories including the LDAP directoryneed to be authenticated first, and then authorized to access any Notesdatabase administered by the Domino server. The Directory Assistancederived from the Master Address Book uses trusted name rules toauthenticate users. Once a username is authenticated, it gets added to thelist of trusted names. Then this username is compared to the ACL forauthorization.

username

Text or text list. Specify primary or alternate Notes usernames toretrieve their information from the NAB.

itemtoreturn

Text. Item (field) name of the specified user for which you would likethe information.

Return valuevaluelist

Text list. When other flags besides [EXHAUSTIVE] have beenspecified, @NameLookup returns a list of single values for eachspecified user. An empty string is returned for no match found. When[EXHAUSTIVE] has been specified, @NameLookup returns a list of allinformation matched for the specified user. No value is returned forunmatched users.

318 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @NameLookupYou have three NABs on your local environment, namely, Names_A.nsf,Names_B.nsf, and Names_C.nsf. Each Address Book has the followingentries:

Names_A.nsf Names_B.nsf Names_C.nsf

View: ($Users) Not exist exist exist

User: Katsushi User: KatsushiItem: Katsushi_A

User: KatsushiItem: Katsushi_B

User: KatsushiItem: Katsushi_C

User: Jones User: JonesItem: Jones_A

User: JonesItem: Jones_B1Item: Jones_B2

Not exist

User: Smith User: SmithItem: Smith_A

Not exist User: SmithItem: Smith_C

User: Yoshito Not exist Not exist Not exist

1. The following formulas will return “Katsushi_B” : “Jones_B1” :“Smith_C” : “”@NameLookup ( [NOUPDATE]; "Katsushi":"Jones":"Smith": _ "Yoshito"; "Item")

@NameLookup ( [FORCEUPDATE]; "Katsushi":"Jones":"Smith": _ "Yoshito"; "Item")

2. The following formula will return “Katsushi_B” : “Jones_B1” :“” : “”@NameLookup ( [NOSEARCHING]; "Katsushi":"Jones":"Smith": _ "Yoshito"; "Item")

3. The following formula will return “Katsushi_B” : “Katsushi_C” :“Jones_B1” : “Jones_B2” : “Smith_C”@NameLookup ( [EXHAUSTIVE]; "Katsushi":"Jones":"Smith": _ "Yoshito"; "Item")

@NarrowConverts full-pitch alphanumeric characters (double byte characters -DBCS) in the specified string to half-pitch alphanumeric characters (singlebyte characters - SBCS). This function works in Japanese, Korean, SimplifiedChinese, and traditional Chinese environments. In the Japaneseenvironment, this function can convert full-pitch Katakana as well.

Note This @function is new with Release 5.

Chapter 5: Formula Language @Functions A–Z 319

Syntax@Narrow(string )

Parameterstring

Text. The string you want to convert to single byte characters.

Return valuereturnstring

Text. The string converted to single byte characters.

UsageThis function can be used in input translation formulas to convert a field’scontents to single byte characters or in computed field formulas to savespace for displaying the string.

Examples: @Narrow1. This input translation formula returns “Tokyo” as a half-pitch

character, if the Location field contains full-pitch character expressionof “Tokyo”.@Narrow(Location)

2. This computed field formula returns “New York” as a half-pitchcharacter to save space for displaying the string.@Narrow("New York")

@NewLineInserts a new line (carriage return) into a text string.

Syntax@NewLine

Return valuecarriageReturn

Text. A carriage return.

UsageThis function does not work in selection, hide-when, column, window title,or form formulas, or inside of @Prompt.

If you need to insert a carriage return inside an @Prompt formula, see @Char.

320 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @NewLine1. This returns

HiThere

"Hi"+@NewLine+"There"

2. This returns

Foster,Steven

in the field EmpName if the string in the field named LastName isFoster, and the string in the field named FirstName is Steven.FIELD EmpName:= LastName + "," + @NewLine + FirstName;

3. This input translation formula uses @Newline to replace all occurrencesof “%” with a carriage return. If the description field contains “Here weare now%Entertain us,” the formula translates it to:

Here we are nowEntertain us

@Implode(@Explode(description; "%"); @NewLine)

@NoReturns the number 0.

Syntax@No

Return valuenope

Number. Zero ( 0 ).

UsageThis function is equivalent to @False.

Examples: @No1. This example returns 0.

@No

2. This example returns 1 if the value in the field named Cost is greaterthan 100; otherwise returns 0.@If(Cost>100;@Yes;@No)

Chapter 5: Formula Language @Functions A–Z 321

@NoteID

The ID number of the current document.

Syntax@NoteID

Return valueNTidnumber

String. The prefix NT followed by the note ID.

@Now

Returns the current time-date.

Syntax@Now

Return valuenow

Time-date. The current time-date.

UsageThis formula does not work in form formulas.

In a field formula, Notes takes the value for @Now from the clientcomputer’s clock.

Example: @NowThis example returns 01/21/96 7:30:45 AM at 7:30:45 A.M. on January 21,1996.

@Now

@OptimizeMailAddress

Given a mail address, returns it with all unnecessary domains removed.

Syntax@OptimizeMailAddress( address )

322 Domino Designer Programming Guide, Volume 1: Formula Language

Parameteraddress

String. The mail address to optimize.

Return valueoptimizedAddress

String. The optimized address.

UsageAll domains between two duplicate domains, including the duplicatedomain, are removed.

Examples: @OptimizeMailAddress1. This example returns “username @ firstdomain @ thirdomain.”

@OptimizeMailAddress ("username @firstdomain @secondomain@firstdomain @thirdomain")

2. This example returns “username @ firstdomain @ secondomain.”@OptimizeMailAddress ("username @firstdomain @firstdomain@secondomain")

@PasswordEncodes a string.

Syntax@Password( string )

Parameterstring

Text. The string you want encoded.

Return valueencodedString

Text. The encoded string. If string is a list, only the first element isencoded, and the rest are ignored.

Usage@Password is especially useful in an input translation formula to protect auser’s password from being seen by others.

Note There is no way to decode the original string once it has beenencoded by @Password.

Chapter 5: Formula Language @Functions A–Z 323

Examples: @Password1. This example returns (382B112E2E2E99559269337AD9D8AF3C1E).

@Password("chocolate")

2. This example returns (64DFE4C65D72187D4ED2998COFE).@Password("vanilla")

3. This example returns (382B112E2E2E99559269337AD9D8AF3C1E).@Password("chocolate":"vanilla")

@PiReturns the constant value pi, accurate to fifteen decimal places. The value pi is the ratio of the circumference of a circle to its diameter.

Syntax@Pi

Return valuepi

The number 3.14159265358979.

Examples: @Pi1. This formula returns the circumference of a circle whose radius

equals 5.2 * @Pi * 5

2. This formula converts an angle from degrees to radians. One degreeequals pi/180 radians. So an angle of 360 degrees equals 2pi radians, 180 degrees equals pi radians, and so on.( angle * @Pi ) / 180

3. Given the latitude of a particular location, you can find a location’sdistance from the equator. The numeric field latitude holds the latitudein degrees. The numeric field distance computes the distance from theequator using this formula.

First, latitude is converted to radians. Next, it’s multiplied by 6440, theapproximate radius of the earth in kilometers. This gives us the lengthof the arc from the equator to the given latitude.

Notes treats an empty numeric field as a text field, so the formula uses@If to check for an empty latitude field.@If( latitude = ""; 0; ( ( latitude * @Pi ) / 180 ) * 6440 )

324 Domino Designer Programming Guide, Volume 1: Formula Language

@PickList

Displays a modal window that contains either:

A view you specify from which the user can select one or moredocuments. @PickList returns a column value from the selecteddocument(s).

The Address dialog box, displaying information from all availableName & Address books. The user can select one or more person, group,server, room, or resource names, and @PickList returns those names.

Syntax@PickList( [Custom] : [Single] ; server : file ; view ; title ; prompt ; column ;categoryname )

@PickList( [Name] : [Single] )

@PickList([Room])

@PickList([Resource])

@PickList([Folders]; [Single]server:database)

@PickList([Folders]; [Shared] server:database)

@PickList([Folders]; [Private] server:database)

@PickList([Folders]; [NoDesktop] server:database)

Parameters[Custom]

Keyword. Indicates that you want to display a view in a dialog box.

[Name]

Keyword. Indicates that you want to display the Address dialog box,where you can select one or more names.

[Single]

Keyword. Optional. Limits the selection to a single document.

[Room]

Keyword. Opens dialog box for selecting room.

[Resource]

Keyword. Opens dialog box for selecting resources.

Chapter 5: Formula Language @Functions A–Z 325

[Folders]

Keyword. Returns a multi-select, text list of all folder names both in thedatabase and from the desktop. The following keywords can becombined with [Folders]:

[Single]

Keyword. Optional. Limits selection to a single folder.

[Shared]

Keyword. Optional. Limits selection to only shared folders.

[Private]

Keyword. Optional. Limits selection to only private folders (both in thedatabase and on the desktop).

[Shared]:[Private]

Keyword. Optional

[NoDesktop]

Keyword. Optional. Excludes folders in the desktop from selection.

server : file

Text list. The server is the name of the server where the database is. Thefile is the path and file name of the database you want to open. Specifythe database’s name and location using the appropriate format for theoperating system.

You can use a replica ID in place of a server and file name as theparameter following the [custom] keyword only. The replica ID must be text and must include the colon between the two sets of eight hexdigits. For example:

@PickList([Custom]; “852564A0:006B7872”;

“By Category”; “Testing replica ID”; “Test prompt”; 3)

Use “” to specify the currently open database.

view

Text. The name of the view you want to open in the database.

title

Text. The window title for the dialog box.

326 Domino Designer Programming Guide, Volume 1: Formula Language

prompt

Text. The prompt you want to appear inside the dialog box.

column

Number. A number indicating which column value you want @PickListto return. Use 1 to indicate the first column, 2 to indicate the secondcolumn, and so on. Unlike @DbColumn and @DbLookup, @PickListcounts all columns, regardless of the types of formula they contain.

categoryname

Note This parameter is new with Release 5.

Text. Optional. Displays the specified category in the view. The viewshould be categorized in order to use this parameter.

Return valuecolumnValue

Text list. The value(s) in the specified column for the document(s) thatthe user selected.

UsageThis function is useful in button, manual agent, paste agent, form action,and view action formulas. It does not work in column, selection, mail agent,scheduled agent, hide-when, window title, or form formulas.

Although @PickList([Custom]) operates similarly to @DbColumn and@DbLookup, @PickList is preferable because

It stores more data

It performs the lookup faster

It allows you to quickly locate the desired document by typing the firstfew characters

@PickList doesn’t offer a NoCache option like @DbColumn and@DbLookup because lookup results are never stored. Each time @PickList isexecuted, a new lookup is performed.

For a calendar view, @PickList displays two days starting with today,without time slots. The user can click on the date picker button to navigateto other days.

You cannot use this function in Web applications.

Chapter 5: Formula Language @Functions A–Z 327

Examples: @PickList1. This formula displays the Products view of prod.nsf in a dialog box. If

the user selects a Staple remover and Stapler from the products view,the temporary variable choice gets assigned the following text list:Staple remover; Stapler

choice:=@PickList( [Custom] ; "" ; "Products" ; "Select a product" ; "Please select the products you want toorder" ; 1 );

2. This formula achieves the same result as the one above, but uses@DbName to display the Products view of the current database.choice:=@PickList( [Custom] ; @DbName ; "Products" ;"Select a product" ; "Please select the products you wantto order" ; 1 );

3. This formula also displays the Products view of the current database,but returns the contents of the second column in the view.choice:=@PickList( [Custom] ; @DbName ; "Products" ;"Select a product" ; "Please select the products you wantto order" ; 2 );

4. This formula is the same as above but limits the selection to a single document.choice:=@PickList( [Custom] : [Single] ; @DbName ;"Products" ; "Select a product" ; "Please select theproducts you want to order" ; 2 );

5. This formula displays the Address dialog box. The names of the people,groups, or servers that the user selects are placed in the person field onthe current document.FIELD person:=person;@SetField( "person"; @PickList( [Name] ) )

@PlatformReturns the name of the currently running platform version of Notes.

Syntax@Platform([Specific])

Parameter[Specific]

Keyword. Optional. Returns more detailed information, for example,the version number in addition to the name of the platform.

328 Domino Designer Programming Guide, Volume 1: Formula Language

Return valueplatform

Text or text list. Without the parameter, returns the name of theplatform. May be any of the following:

AIX OS/ 2v1 SUN SPARC

HP UNIX OS/2v2 Windows/16

Macintosh/68K SCO OpenDeskTop Windows/95

Macintosh/PowerPC SOLARIS x86 Windows/NT

MS-DOS SOLARIS SPARC UNIXWARE

NetWare

When you use the “specific” keyword, @Platform returns a text listcontaining the following items:

PrimaryOSName

One of the platform names listed above

PrimaryOSVersionNumber

The current version number of the primary operating system. Thenumber is specific, for example,

3.11. For the UNIX platform, @Platform([Specific]) returns only thespecific platform name, not the version number.

SecondaryOSName

The name of the secondary operating system. For example, MS-DOS isthe secondary operating system when Windows/16 runs on top of it.The values are the same as those for the primary operating system.Most platforms don’t have a secondary operating system.

SecondaryOSVersionNum

The current version number of the secondary operating system.

On a Windows16-bit platform, for example, @Platform([Specific]) returnsWindows/16;3.11;MS-DOS;6.22

UsageWhen it is used in column, selection, or scheduled agent formulas,@Platform returns the current platform that the database resides on. If thedatabase resides on a server, @Platform returns the server’s platform; if thedatabase resides locally, @Platform returns the workstation’s platform.

Your application may perform certain operations that are not available inall platform versions of Notes (such as the DDE-related functions). Rather

Chapter 5: Formula Language @Functions A–Z 329

than receive an error, you could use @Platform to determine whether or notto perform the operation.

You can use @Platform([Specific]) to distinguish between Win 32 platforms(NT versus 95), and between UNIX and OS/2 platforms.

This function returns the server’s platform only. Use @ClientType todistinguish between Web and Notes users.

@PostedCommand

Executes a Notes command. Most of the standard menu commands can beexecuted using @PostedCommand. In addition, a number of specializedcommands are available. In a formula, any command invoked using@PostedCommand executes after the rest of the formula has been evaluated.

Syntax@PostedCommand( [ command ] ; parameters )

UsageThis function does not work in column, selection, hide-when, section editor,window title, field, or form formulas, or in agents that run on a server. It’sintended for use in SmartIcons, button, hotspot, and action formulas.

Note If your formula will be executed in Notes Release 3, use@PostedCommand instead of @Command; Notes Release 3 cannot executean @Command formula constructed in Release 4. If your @Commandformulas constructed in Release 3 are compiled in Release 4, Notesautomatically changes each occurrence of @Command to@PostedCommand.

@Power

Raises a number to the power of an exponent.

Syntax@Power( base ; exponent )

Parametersbase

Number. The value you want raised to exponent. May be positive ornegative.

330 Domino Designer Programming Guide, Volume 1: Formula Language

exponent

Number. The power.

Return valueresult

Number. The value of base raised to the power of exponent.

Examples: @Power1. This example returns 8 (2 raised to the power of 3, or 23).

@Power(2;3)

2. This example returns -8 (-2 raised to the power of 3, or -2 3).@Power(-2;3)

3. This example returns 0.125 (2 raised to the power of -3, or 2 -3 ).@Power(2;-3)

@PromptDisplays a dialog box to the user and returns a text value based on theuser’s actions in the dialog box. @Prompt is useful for prompting a user forinformation and determining a course of action based on the user’s input.

Summary of Dialog Box StylesThis table shows the different styles of dialog boxes you can display.@Prompt accepts parameters and returns a value based on the style you indicate.

Style Purpose Contains Return Value

Ok Displays aninformationalmessage

Title and prompt

OK button

1 (True).

YesNo Allows user tomake a Yes/Nodecision

Title and prompt

Yes and No buttons

1 (True, Yes)or 0 (False,No).

YesNoCancel Allows user tomake a Yes/Nodecision, or Cancel

Title and prompt

Yes, No, and Cancelbuttons

1 (True, Yes),0 (False, No),or -1 (Cancel).

continued

Chapter 5: Formula Language @Functions A–Z 331

Style Purpose Contains Return Value

OkCancelEdit Allows user totype in text input

Title and prompt

Text box for input

OK and Cancel buttons

Text. Valuethat userentered.

OkCancelList Allows user toselect one valuefrom a list ofchoices

Title and prompt

List of choices

OK and Cancel buttons

Text. Valuethat userselected.

OkCancelCombo Allows user toselect one valuefrom a drop-downlist of choices

Title and prompt

List of choices

OK and Cancel buttons

Text. Valuethat userselected.

OkCancelEditCombo Allows user toselect one valuefrom a list ofchoices, or type ina different value

Title and prompt

List of choices with textbox

OK and Cancel buttons

Text. Valuethat userselected orentered.

OkCancelListMult Allows user toselect multiplevalues from a listof choices

Title and prompt

List of choices

OK and Cancel buttons

Text list. Allvalues thatuser selected,concatenatedwith : (colon).

LocalBrowse Allows user toselect a file namefrom the local filesystem

Controls and displaysfor browsing local filesystem

Select, Cancel, andNetwork or Helpbuttons

Text. Filename thatuser selectedor entered.

Password Allows user toenter passwordwithout displayingit on the screen

Title and prompt

Text box that acceptsand hides user input

OK and Cancel buttons

Text.Passwordthat userentered.

Syntax@Prompt( [ style ] : [ NoSort ] ; title ; prompt ; defaultChoice ; choiceList ;filetype )

332 Domino Designer Programming Guide, Volume 1: Formula Language

Parameters[style ]

Constant. Indicates the type of dialog box you want to display. May beany of the following:

OK

YesNo

YesNoCancel

OkCancelEdit

OkCancelList

OkCancelCombo

OkCancelEditCombo

OkCancelListMult

LocalBrowse

Password

[NoSort]

Keyword. Optional. Include this keyword if you want the members ofchoiceList to appear in the exact order in which you enter them. If youomit this keyword, the members of choiceList are sorted alphabetically.

title

Text. The text you want displayed in the dialog box’s title bar. Requiredfor all styles, although you can specify a null string with “”.

prompt

Text. The text you want displayed within the dialog box. Required forall styles, except LocalBrowse. If you use a formula for prompt and thatformula returns a list, only the first item in the list will be displayed asthe prompt. To display the entire list, use @Implode. @NewLine cannotbe used in prompt.

defaultChoice

Text. The value that will be used as the default value for the user’sinput. The input section of the dialog box will be primed with the value;the user can either accept it by selecting OK or replace it with anothervalue. Not applicable to dialog boxes of style [Ok], [YesNo],[YesNoCancel], [LocalBrowse], or [Password]. Required for all otherstyles. For [OkCancelListMult], you can specify multiple default valuesas a text list “item1”:“item2”.

Chapter 5: Formula Language @Functions A–Z 333

choiceList

Text list. The values that you want displayed in the dialog box’s listbox. The user can select one of these values as the input. Separate thevalues with colons, as in: “phone.nsf”:@MailDbName. Each value inyour list can be a text string, or an @function that returns a text string.Required only with styles [OkCancelList],[OkCancelCombo],[OkCancelEditCombo], and [OkCancelListMult].

filetype

Text. A value that specifies the types of files to display initially: “1” for.nsf files only; “2” for .ntf files only; “3” for files of all type. Requiredonly with style [LocalBrowse].

Return Valuechoice

If the user enters a value, returns the value as text.

If the user selects Yes, returns 1 (True).

If the user selects No, returns 0 (False).

If the user selects Cancel, formula evaluation stops. The exception is[YesNoCancel], which returns -1 if the user selects Cancel.

@Prompt([OkCancelEdit]) returns only the first 254 characters of thetext entered.

UsageUse @Prompt in field formula, button, SmartIcons, manual agent, formaction, and view action formulas. This function does not work in column,selection, mail agent, or scheduled agent formulas, and has limitedusefulness in window title and form formulas.

You cannot use this function in Web applications.

Examples: @Prompt1. [Ok] displays an informational message; the user clicks OK to close the

dialog box. Use this style when you want to inform the user aboutsomething, without receiving anything back except anacknowledgment.@Prompt([Ok];"Reminder";"Don't forget to run backuptonight.")

334 Domino Designer Programming Guide, Volume 1: Formula Language

2. [YesNo] displays a warning, and gives the user a chance to proceed orcancel the operation. If the user selects Yes the value “1” is returned. Ifthe user selects No the value “0” is returned.@Prompt([YesNo]; "Send memo?"; "This memo will be sent toeveryone listed in the To, CC, and BCC fields.")

3. [YesNoCancel] also displays a warning, and gives the user a chance to select Yes, No, or Cancel. If the user selects Cancel, the value -1 is returned.result=@Prompt([YESNOCANCEL]; "Send memo?"; "This memowill be sent to everyone listed in the To, CC, and BCCfields" )

4. [OkCancelEdit] prompts the user to enter his or her name, which isreturned as a text string. The name defaults to the current user’s Notesuser name, which is calculated using @UserName. If the user selectsCancel, Notes cancels the formula evaluation. Note that@Prompt([OkCancelEdit]) returns only the first 254 characters of thetext entered.@Prompt([OkCancelEdit]; "Enter Your Name"; "Type your namein the box below."; @UserName)

5. [OkCancelList] displays a list box with database names (sortedalphabetically), prompts the user to select a database, and returns thatdatabase’s name as a text string for use in a subsequent operation. If theuser selects Cancel, Notes cancels the formula evaluation.

The third option in the list is the current user’s own mail database, thename of which is calculated with @MailDbName. The user must selectone of the listed options; by default, Schedule is highlighted (the valuelisted as the default must also be included in the display list).@Prompt([OkCancelList]; "Select a Database"; "Select adatabase to open."; "Schedule"; "Schedule":"PhoneBook":@Subset(@MailDbName;-1))

6. [OkCancelCombo] displays a dialog box similar to example 5, exceptthat a drop-down list is used, so that initially only the default value isdisplayed. The user clicks the down arrow on the box to display the restof the list. As in example 5, the user must select one of the listed values;by default, Schedule is selected. This function returns the user’sselection. If the user selects Cancel, Notes cancels the formulaevaluation.@Prompt([OkCancelCombo]; "Select a Database"; "Select adatabase to open."; "Schedule"; "Schedule":"PhoneBook":@Subset(@MailDbName;-1))

Chapter 5: Formula Language @Functions A–Z 335

7. [OkCancelEditCombo] is similar to example 6, except here the user canedit the text box and type in any database name; this way, the user isnot limited to the selections in the list. This function returns the user’sselection or entry. If the user selects Cancel, Notes cancels the formulaevaluation.

The default value must be included in the list, or the text box thatdisplays initially will be blank.@Prompt([OkCancelEditCombo]; "Select a Database"; "Selecta database to open, or type a database specification.";"Schedule"; "Schedule":"Phone Book":@Subset(@MailDbName;-1))

8. [OkCancelListMult] displays a list of names, from which the user canselect one or more (Mary Tsen appears as the default selection). Thisfunction returns the user’s selection(s). If the user selects Cancel, Notescancels the formula evaluation.

The default value must be included in the list.@Prompt([OkCancelListMult]; "Select a Name"; "Select oneor more names as recipients for this request."; "MaryTsen"; "Mary Tsen":"Bill Chu": "Michael Bowling":"MarianWoodward")

9. [Password] displays a dialog box where the user can enter a password.Notes does not display the password on the screen. This functionreturns the password.@Prompt([PASSWORD]; "Password"; "Enter the password forApproach database.")

10. [LocalBrowse] provides controls and displays that allow you to browseand select a name from the local file system. This example opens theNotes database file the user selects from the local browser. The “1”restricts the initial display to .nsf files.file := @Prompt([LOCALBROWSE]; "Select a database to open"; "1");@If(file = ""; @Return(1); "");@Command([FileOpenDatabase]; "" :@Left(file; " "))

@ProperCase

Converts the words in a string to proper-name capitalization: the first letterof each word becomes uppercase, all others become lowercase.

Syntax@ProperCase( string )

336 Domino Designer Programming Guide, Volume 1: Formula Language

Parameterstring

Text. The string you want to convert.

Return valueproperString

Text. The string, converted to proper-name capitalization.

UsageA “word” is a consecutive set of characters with no spaces. Hyphenatedwords are considered two words, as are words separated by any otherpunctuation except an apostrophe.

Examples: @ProperCase1. This example returns Every Child Loves Toys.

@ProperCase("every CHILD LOves toys")

2. This example returns 3-Digit Code.@ProperCase("3-digit code")

3. This example returns Los Angeles if the string in the field named Citycontains the string los angeles, Los Angeles, LOS ANGELES, losAngeles, or any other variation.@ProperCase(City)

@RandomGenerates a random number between 0 and 1, inclusive.

Syntax@Random

UsageTo generate a random number between any two numbers x and y, use theformula ( y - x )*@Random + x.

Example: @RandomThis formula generates a random number between 7 and 22, inclusive. Forexample, it might return 13.

15 * @Random + 7

Chapter 5: Formula Language @Functions A–Z 337

@RefreshECL

Copies the administration execution control list from a specified AddressBook and name to your personal workstation ECL.

Syntax@RefreshECL( server : database ; name )

Parametersserver : database

Text list. The server location and file name of the Address Book. Omitserver or specify it as “” (null) for the local Notes directory.

name

Text. The name of the ECL. Specify “” (null) for the unnamed ECL.

Example: @RefreshECLThis formula refreshes your personal workstation ECL from theadministration ECL named “Developers” in the Address Book on the serverMarketing.

@RefreshECL("Marketing" : "names.nsf"; "Developers")

REMThe REM keyword allows you to add explanatory comments to a formula.Adding comments to a formula makes it easier to maintain the database. Itis especially useful to add comments to a long or complicated formula.

SyntaxREM “comments” ;

UsageIf the comment doesn’t fit on one line, add another REM statement tocomplete the comment.

Example: REMThis formula is commented with REM statements.

REM "6/15/90";REM "The following formula calculates the date";REM "for the DueDate field";REM "DueDate is the Date field + thirty days";REM;@Adjust(Date; 0;0;30;0;0;0);

338 Domino Designer Programming Guide, Volume 1: Formula Language

@Repeat

Repeats a string a specified number of times.

Syntax@Repeat( string ; number ; numberchars )

Parametersstring

Text. The string you want to repeat.

number

Number. The number of times you want to repeat string.

numberchars

Number. Optional. The maximum number of characters you wantreturned. @Repeat truncates the result to this number.

Return valuerepeatedString

Text. The string, repeated number times until numberchars (if specified) is reached.

UsageThe resultant string cannot be larger than 1,024 characters.

Examples: @Repeat1. This example returns HelloHelloHello.

@Repeat("Hello";3)

2. This example returns ByeBye.@Repeat("Bye";2;5)

3. This example returns Great Month! Great Month! Great Month! in theComments field if the amount in the field named Sales is greater than or equal to 100,000; otherwise it returns the string Good Month.FIELD Comments:=@If(Sales>=100000;@Repeat("GreatMonth!";3);"Good Month");

Chapter 5: Formula Language @Functions A–Z 339

@Replace

Performs a find-and-replace operation on a text list.

Syntax@Replace( sourcelist ; fromlist ; tolist )

Parameterssourcelist

Text list. The list whose values you want to scan.

fromlist

Text list. A list containing the values that you want to replace.

tolist

Text list. A list containing the replacement values.

Return valuereplacedList

Text list. The sourcelist, with any values from fromlist replaced by thecorresponding value in tolist. If none of the values in fromlist matchedthe values in sourcelist, then sourcelist is returned unaltered.

Examples: @Replace1. Both sourcelist and fromlist contain “Orange”, which is the first value in

fromlist. The first value in tolist replaces “Orange” in sourcelist. No othermatches were found, so the remainder of sourcelist is left intact; theresult is shown below:@Replace("Red":"Orange":"Yellow":"Green";"Orange":"Blue";"Black":"Brown")

sourcelist fromlist tolist result

Red Orange Black Red

Orange Blue Brown Black (replaces “Orange”)

Yellow Yellow

Green Green

3. This formula looks at the Categories field in each document that it runsagainst. If one of the keywords in a document’s Categories field is “Tobe assigned” then that keyword is replaced with the name stored in thatdocument’s AssignedTo field.FIELD Categories:= @Trim(@Replace(Categories;"To be assigned"; AssignedTo));

340 Domino Designer Programming Guide, Volume 1: Formula Language

You have a database where you log service requests. Incoming requestsare automatically categorized as “To be assigned” by a mail/pastefilter. Each day, you review the new (unassigned) service requests, andassign them to technicians by entering the appropriate name in theAssignedTo field. Once a request has been assigned, you want it toappear under that technician’s name in the view, instead of under “Tobe assigned.”

Rather than manually re-categorizing each document, you can write a filter macro, like the one above, to delete the documents fromthe “To be assigned” category and add them to the appropriatetechnician categories.

@ReplaceSubstringReplaces specific words or phrases in a string with new words or phrasesthat you specify. Case sensitive.

Syntax@ReplaceSubstring( sourceList ; fromList ; toList )

ParameterssourceList

Text or text list. The string whose contents you want to modify.

fromList

Text or text list. A list containing the words or phrases that you want to replace.

toList

Text or text list. A list containing the replacement words or phrases.

Return valuenewSourceList

Text or text list. The sourceList, with any values from fromlist replacedby the corresponding value to tolist. If none of the values in fromlistmatched the values in sourcelist, then sourcelist is returned unaltered.

UsageIf more strings are specified in the fromList than the toList, the extra stringsin fromList are replaced with the last string in toList. Extra strings in toListare ignored. If no matches are found, @ReplaceSubstring returns theunmodified sourceList.

Chapter 5: Formula Language @Functions A–Z 341

If a list is specified for fromList, each subsequent list item is scanned againstthe resulting sourceList, with prior list item substitutions performed.

For example:

@ReplaceSubstring("first";"first":"second";"second":"third")

returns third.

First, @ReplaceSubstring substitutes “second” for “first” from the first listitem in fromList . The resulting sourceList is now“second”. The functionsubstitutes “third” for “second” from the second list item in fromList.

Tip Use @ReplaceSubString to remove carriage returns from text byreplacing them with “ ” or “”.

Examples: @ReplaceSubstring1. This example returns “I hate apples”.

@ReplaceSubstring( "I like apples" ; "like" ; "hate" )

2. This example returns “I hate peaches”.@ReplaceSubstring( "I like apples" ; "like" : "apples" ;"hate" : "peaches")

3. This example replaces all carriage returns in the Description field’s textwith a blank space.@ReplaceSubString(Description;@Newline;" ")

@ResponsesReturns the number of responses (in the current view) to the document.

Syntax@Responses

Return valuenumResponses

Special text. The number of responses to the document. Special textcannot be converted to a number.

UsageUse @Responses in window title formulas. This function does not work inany other formula.

You cannot use this function in Web applications.

342 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Responses1. This example returns 5 if there are five responses to the document.

@Responses

2. This formula returns the string No one has responded to thisdocument if there are no responses to the current document; otherwisea blank is returned.@If(@Responses=0; "No one has responded to this document"; " ")

@ReturnImmediately stops the execution of a formula and returns the specifiedvalue. This is useful when you only want the remainder of the formula to be executed if certain conditions are true.

Syntax@Return( value )

Parametervalue

The value you want returned. You can specify another @function suchas @Error, or a text string such as “Formula stopped,” or a Booleanvalue (True or False). If you don’t want anything returned, use the null string (“”).

Return valueresult

Returns value.

Usage@Return is most useful in field formulas, agents that run formulas, buttons,and SmartIcons. Generally, you use it with @If to determine whether toperform @Return or to perform one or more other statements.

@Return should not be used in column formulas.

Examples: @Return1. This formula displays a dialog offering the user a Yes/No choice. If the

user selects Yes, the next document in the view is opened; if the userselects No, the formula stops and nothing more happens.@If(@Prompt([YesNo];"Continue?";"Do you want to continuereading your mail?");@Command([NavigateNext]);@Return(""))

Chapter 5: Formula Language @Functions A–Z 343

2. This formula tests whether an environment variable calledOrderNumber has been stored in the user’s notes.ini or NotesPreferences file. If there is no such variable stored, @SetEnvironment isused to initialize it to zero. If a value has already been stored, @Returnis used to return it and stop the formula from executing.@If(@Environment(OrderNumber)="";@SetEnvironment("OrderNumber";"0");@Return(@Environment("OrderNumber")))

@RightReturns the rightmost characters in the string. You can specify the numberof rightmost characters you want returned, or you can indicate that youwant all the characters to the right of a specific substring.

Syntax@Right( stringToSearch ; numberOfChars ) or@Right( stringToSearch ; subString )

ParametersstringToSearch

Text. The string whose rightmost characters you want to find.

numberOfChars

Number. The number of characters to return. If the number is 2, the lasttwo characters of string are returned; if the number is 5, the last fivecharacters are returned, and so on.

subString

Text. A substring of stringToSearch. @Right returns all of the charactersto the right of subString. It finds subString by searching stringToSearchfrom left to right.

Return valueresultString

Text. The rightmost characters in stringToSearch. The number ofcharacters returned is determined by either numberOfChars or subString.@Right returns “” if subString is not found in stringToSearch.

344 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Right1. This example returns ace, the rightmost 3 characters in the string.

@Right("Lennard Wallace";3)

2. This example returns Wallace, which represents everything to the rightof the first occurrence of the blank space.Right("Lennard Wallace";" ")

3. This example returns man if the Author field contains “TimothyAltman.”@Right(Author;3)

4. This example returns Altman if the Author field contains “TimothyAltman.”@Right(Author;" ")

@RightBackReturns the rightmost characters in a string.

Syntax@RightBack( stringToSearch ; numberOfChars )

@RightBack(stringToSearch ; subString )

ParametersstringToSearch

Text. The string whose rightmost characters you want to find.

numberOfChars

Number. Counting from left to right, the number of characters to skip.All the characters to the right of that number are returned.

subString

Text. A substring of stringToSearch. @RightBack returns all thecharacters to the right of subString. It finds subString by searchingstringToSearch from right to left.

Return valueresultString

Text. The rightmost characters in stringToSearch. The number ofcharacters returned is determined by either numberOfChars or subString.

Chapter 5: Formula Language @Functions A–Z 345

Examples: @RightBack1. This example returns nard Wallace.

@RightBack("Lennard Wallace";3)

2. This example returns a blank.@RightBack("Lennard Wallace";"")

3. This example returns Wallace.@RightBack("Lennard Wallace";" ")

4. This example returns othy Altman if the name in the field namedAuthor is Timothy Altman.@RightBack(Author;3)

@RoundRounds the designated number to the nearest whole number; if anadditional number is specified, it is used as the rounding factor.

Syntax@Round( number )@Round( number ; factor )

Parametersnumber

Number or number list. Numbers to be rounded.

factor

Number. Optional. The rounding factor to use. For example, if factor is10, @Round rounds to the nearest number that is a factor of 10. If youdon’t specify a factor, the number is rounded to the nearest wholenumber.

Return valueroundedNumber

Number. The value of number, rounded to the specified factor or to thenearest whole number. If number is a list, each number in the list isrounded to the specified factor or to the nearest whole number.

UsageWhen using this function with a number list, the list concatenation operatortakes precedence over any other operators.

For more information, see “List Operator” in the chapter “FormulaLanguage Rules.”

346 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Round1. This example returns 1.

@Round(1.499)

2. This example returns 2.@Round(1.5)

3. This example returns 12340 if the number in the field namedNumberOfEmployees is 12338.@Round(NumberOfEmployees;10)

4. This example returns 1:3:3:4.@Round(1.333:2.897654:3.1:4)

5. This example returns 4510:45010:450010.@Round(4505:45005:450005;10)

This is an example of rounding to the nearest decimal place.

6. This example returns 3.1430E+00.@Round(3.142857; 0.001)

@SecondExtracts and returns the seconds value from the specified time-date.

Syntax@Second( time-date )

Parametertime-date

Time-date. The time-date containing the seconds.

Return valueseconds

Number. The number of seconds in the second part of the time.

Examples: @Second1. This example returns 45.

@Second([9:30:45])

2. This example returns 45 if the current time is 12:30:45 P.M.@Second(@Now)

Chapter 5: Formula Language @Functions A–Z 347

3. This example returns 45 as a text string if the contents of the fieldnamed Date is any time-date value in which the number of seconds is 45.@Text(@Second(Date))

SELECT

The SELECT keyword defines criteria for the selection of documents in anagent that runs a formula, in a view, or during replication. You use aSELECT statement before an expression to define the set of documents thatyou want to change, see in a view, or replicate.

SyntaxSELECT formula ;

UsageIn an agent, you can use the Agent Builder to select the documents youwant to act upon.

In an agent that runs a formula, you can include a SELECT statement inthe formula. The agent acts upon the documents selected with theAgent Builder and the documents selected by the SELECT statement.

In a view, you can use the Search Builder to select the documents youwant to see in the view. You can use SELECT to select documents andprovide more complicated conditions for replication.

For selective replication, you can use the Search Builder to select thedocuments you want to replicate. You can use SELECT to selectdocuments and provide more complicated conditions for replication.

Using SELECT in the formula eliminates the need to go through thedatabase to select the documents. You can run the filter macro on all thedocuments in the database, and the SELECT statement performs theselection process.

The word SELECT is automatically prepended to the view selectionformula when the formula is saved.

Use SELECT @All to select all documents for an operation (for example, useit in the selection formula for a view that displays all of the database’sdocuments). @All should never be used without the SELECT keyword. Ifyour formula contains @All by itself, Notes appends the SELECT @Allstatement to your formula:

@All;SELECT @All;

348 Domino Designer Programming Guide, Volume 1: Formula Language

If you compare a field to a value (for example, Year > 1995) and the field isunavailable, the comparison is false. However, you should check for fieldsthat may not be present with @IsUnavailable.

This keyword does not work in column, hide-when, section editor, windowtitle, hotspot, field, form, or form action formulas.

SELECT is not intended for use in buttons or SmartIcons.

Examples: SELECT1. You want to change the contents of the Status field in several

documents to Closed. However, you do not want to change the Statusfield of any document that contains the value Unsigned Contracts in theCategories field.

To make the desired change, you write and run an agent that runs aformula. When you write the formula, you specify the documents thatyou want Notes to scan to make the change. By adding a SELECTstatement to the formula, you can further limit the documents thatNotes looks at when you run the agent.SELECT Categories != “Unsigned Contracts”;FIELD Status := “Closed”;

2. This replication formula limits replication to documents that contain aYear field whose value is greater than 1995.SELECT @IsAvailable(Year) & Year > 1995

3. This replication formula limits replication to documents that do notcontain a Year field or whose Year field is greater than 1995.SELECT !@IsAvailable(Year) | Year > 1995

@SelectReturns the value that appears in the number position. If the number isgreater than the number of values, @Select returns the last value in the list.If the value in the number position is a list, returns the entire list containedwithin the value.

Syntax@Select( number ; values )

Parametersnumber

Number. The position of the value you want to retrieve.

Chapter 5: Formula Language @Functions A–Z 349

values

Any number of values, separated by semicolons. A value may be anumber, text, time-date, or a number list, text list, or time-date list.

Examples: @Select1. This example returns 3.

@Select(3;1;2;3)

2. This example returns 3.@Select(5;1;2;3)

3. This example returns Apr;May;Jun.@Select(2;“Jan”:“Feb”:“Mar”;“Apr”:“May”:“Jun”;“Jul”:“August”:“Sep”;“Oct”: “Nov”:“Dec”)

4. This example returns San Diego;Sydney;Hong Kong;Amsterdam if thefield named TrainingCenters contains these city names.@Select(3;SalesOffices;ServiceOffices;TrainingCenters)

@SetAssigns a value to a temporary variable for use within a formula.

Syntax@Set( variableName ; value )

ParametersvariableName

Text. The name of a temporary variable.

value

Text, number, or time-date. The value you want to give to variableName.

UsageBefore you use @Set in your formula, the variable receiving the assignmentmust have already been declared within the same formula. One easy way todo this is to assign it a null value at the beginning of your formula:

TemporaryVariable:=“”

Example: @SetThis formula determines whether the FirstName field is blank. If so, it sets the variable FullName to the concatenation of the Title field with theLastName field, as in “Ms. Tsen.” If the FirstName field contains a value,

350 Domino Designer Programming Guide, Volume 1: Formula Language

the variable FullName is instead set to the concatenation of the FirstNamewith the LastName, as in “Mary Tsen.”

Full Name:="";@If(FirstName="";@Set("FullName";Title+" "+LastName); @Set("FullName"; FirstName+" "+LastName))

@SetDocField

Given the unique ID of a document, sets the value of a specific field on that document.

Syntax@SetDocField( documentUNID ; fieldName ; newValue )

ParametersdocumentUNID

Text. The unique ID of a document.

fieldName

Text. The name of a field on the document, enclosed in quotationmarks. If you store the field name in a variable, omit the quotationmarks here.

newValue

Text or text list; number or number list; time-date or time-date range.The value you want to give to the field.

UsageThis function does not work in column or selection formulas. @SetDocFieldis particularly useful in field, button, and agent formulas. You cannot use@SetDocField to access the current document.

Examples: @SetDocField1. This formula, if placed on a button in a response form in a discussion

database, changes the Subject of the parent document to More peopleare commuting by bicycle.@SetDocField($Ref; "Subject"; "More people are commutingby bicycle")

2. In a database, you want to update the parent Project documentwhenever its child Status document changes. Each Project documenthas one Status document. Specifically, you want to update thelatestStatus field on the Project document so that it reflects the contentsof the lastAction field on the child Status document.

Chapter 5: Formula Language @Functions A–Z 351

You write this input translation formula for the lastAction field on theStatus form:@SetDocField($Ref; "latestStatus"; lastAction );lastAction

3. This button formula uses @DbLookup to retrieve the unique ID of aparticular document. It then changes the value of the “employee title”field in that document to “sales associate.”@SetDocField(@DbLookup(""; "Magnet":"Personnel.nsf";"Staff"; "Joe Smith";

"uniqueid"); "Employee Title"; "Sales Associate")

@SetEnvironment

Sets an environment variable stored in the user’s notes.ini file (Windows,OS/2, and UNIX) or Notes Preferences file (Macintosh).

Syntax@SetEnvironment( variableName ; value )

ParametersvariableName

Text. The name of the environment variable, enclosed in quotationmarks. If you enter a text list for the variableName, then every variablenamed in that list receives the specified value. If you store the fieldname in a variable, omit the quotation marks here.

value

Text. The value you want to give to variableName. If you use a text listfor value, only the first value in the list is used; the rest are ignored.

UsageUse @SetEnvironment when you want to set an environment variable fromwithin another @function (such as @If or @Do). To set the environmentvariable outside of an @function, use @Environment or theENVIRONMENT keyword.

@SetEnvironment cannot be used in column or selection formulas. Someformulas, such as scheduled agents, are run on the server instead of theuser’s workstation. In this case, the environment variables affected are theserver’s environment variables, not the workstation’s.

To get the value of an environment variable, use @Environment.

352 Domino Designer Programming Guide, Volume 1: Formula Language

For Web applications, use pre-defined field names to gather informationabout the Web user’s environment by requesting Common GatewayInterface (CGI) environment variables.

@SetField

Assigns a value to a field stored within a document (use @Set for temporaryvariables). This is similar to using the FIELD keyword, except that@SetField can be used within another @function.

Syntax@SetField( fieldName ; value )

ParametersfieldName

The name of the field whose value you want to set, enclosed inquotation marks. If you store the field’s name in a variable, omit thequotation marks here.

value

The value you want to give to fieldName. The value must be the samedata type as the field; for example, if the field is numeric, the value mustbe a number.

UsageThis keyword is most useful in agent, button, hotspot, field, and actionformulas, and SmartIcons. It does not work in column, selection,hide-when, window title, or form formulas.

Before you use @SetField in your formula, the field receiving theassignment must have already been declared within the same formula. Oneway to do this is to declare it at the beginning of your formula:

FIELD Fieldname:=Fieldname;

Example: @SetFieldThis formula checks the value of the Priority field; if the Priority is Low orMedium, the Status field is set to Closed; otherwise, the Status is set toOpen. Before @SetField is encountered in the formula, the Status field isdeclared using the FIELD keyword.

FIELD Status:=Status;@If(Priority="Low"|Priority="Medium";@SetField("Status";"Closed");@SetField("Status";"Open"))

Chapter 5: Formula Language @Functions A–Z 353

@SetProfileField

Sets the value of a field in a profile document.

Syntax@SetProfileField(profilename ; fieldname ; value [ ; username] )

Parametersprofilename

Text. The name of the profile document that contains the field you wantto access.

fieldname

Text. The name of the field you want to access.

value

Text. The value to which you want to set the field.

username

Text. The name of the user associated with the profile document.

Return valuevalue

The value to which you set the field.

Examples: @SetProfileField1. This example sets the contents of the “Profile Categories” field of the

“Interest Profile” document to the name of the current platform.@SetProfileField("Interest Profile"; "Profile Categories",@Platform)

2. This example sets the contents of the “Profile Categories” field of the“Interest Profile” document for the current user to the name of thecurrent platform.@SetProfileField("Interest Profile"; "Profile Categories",@Platform, @UserName)

@SetTargetFrameAllows you to specify a target frame when opening a view, page, orframeset, or when composing or editing a document. This function supportsthe SetTargetFrame method in NotesUIWorkspace.

Note This @function is new with Release 5.

354 Domino Designer Programming Guide, Volume 1: Formula Language

Syntax@SetTargetFrame(targetframe )

Parameterstargetframe

Text. The name of the frame that a view, page, frameset, or documentshould open into.

UsageUse @SetTargetFrame before opening the view, page, or frameset, or beforecomposing or editing a document. The following @commands use the framespecified in the @SetTargetFrame:

@Command([OpenFrameset])

@Command([OpenPage])

@Command([OpenView])

@Command([Compose])

@Command([EditDocument])

If you specify the newinstance parameter for @Command([OpenView]), the@SetTargetFrame function is ignored.

If you do not specify a viewName for @Command([OpenView]), then the lastview is the one that will open in the specified targetframe of@SetTargetFrame.

@SetTargetFrame can be used in action and hotspot formulas.

Examples: @SetTargetFrameConsider 2 framesets — one that contains “Frame A” and “Frame B” andanother frameset nested within “Frame B” that contains “Frame C” and“Frame A”.

1. This example opens the view “My View” in “Frame A” of the firstframeset.@SetTargetFrame("Frame A");

@Command([OpenView]; "My View");

2. This example uses the text list format to open a form into “Frame A”which is nested in the second frameset.@SetTargetFrame( "Frame B":"Frame A");

@Command([Compose]; "Main Form");

Chapter 5: Formula Language @Functions A–Z 355

@Sign

Indicates whether a number is positive, negative, or zero.

Syntax@Sign( signedNumber )

Parameternumber

Number. The number whose sign you want to determine.

Return valuesign

Number. May be any of the following values:

- 1 The signed number is negative.

0 The signed number is zero.

1 The signed number is positive.

Example: @SignThis formula sets the result field to “Profit!” if the earnings field is greaterthan the expenses field, “Loss!” if expenses are greater than earnings, and“Break even” if they are equal.

field result:=result;difference:=earnings - expenses;r:=@If( ( @Sign( difference ) = 1); "Profit!"; ( @Sign( difference ) = -1 ); "Loss!"; "Break even" );@SetField( "result"; r )

@Sin

Given an angle in radians, returns the sine of the angle. In a right triangle,the sine of an acute angle is the ratio of the length of its opposite side to thelength of the hypotenuse.

Syntax@Sin( angle )

Parameterangle

Number. An angle expressed in radians.

356 Domino Designer Programming Guide, Volume 1: Formula Language

Return valuesine

Number. The sine of angle, to 15 decimal places.

Examples: @Sin1. This formula returns 1, the sine of the angle Pi/2 (90 degrees).

@Sin( @Pi/2 )

2. You have a triangle ABC. You know the value of angle A in radians,and the lengths of sides a and b. This formula finds angle B, in radians.This formula is a version of the law of sines, which states that for anytriangle ABC, (sin A / a) = (sin B / b) = (sin C / c).@ASin( ( sideB *( @Sin( angleA ) ) ) / sideA )

@SoundexReturns the Soundex (the Notes phonetic speller) code for the specifiedstring.

Syntax@Soundex( string )

Parameterstring

Text. The string whose Soundex code you want.

Return valuecode

Text. The Soundex code. You cannot convert it to any other data type.

UsageThis function is used almost exclusively by the Address Book. You willrarely use this function.

Examples: @Soundex1. This example returns F430.

@Soundex("field")

2. This example returns P430.@Soundex("phield")

Chapter 5: Formula Language @Functions A–Z 357

@Sqrt

Given a number, returns its positive square root.

Syntax@Sqrt( number )

Parameternumber

Number. The number whose square root you want to find. The numbermust be positive, otherwise @Sqrt returns an error.

Example: @SqrtThis example returns 4.

@Sqrt( 16 )

@Subset

Searches a list from left to right and returns the number values you specify.If you specify a negative number, @Subset searches the list from right toleft, but the result is ordered as from the beginning of the list.

Syntax@Subset( list ; number )

Parameterslist

Text list, number list, or time-date list. The list whose subset you want.

number

Number. The number of values from list that you want.

Return valuesubsetList

Text list, number list, or time-date list. The list, containing the number ofvalues you specified.

Examples: @Subset1. This example returns New Orleans;London.

@Subset("New Orleans":"London":"Frankfurt":"Tokyo";2)

2. This example returns London;Frankfurt;Tokyo.@Subset("New Orleans":"London":"Frankfurt":"Tokyo";-3)

358 Domino Designer Programming Guide, Volume 1: Formula Language

3. This example returns New Orleans;London;Frankfurt if the field namedBranchOffices is made up of the list “New Orleans” : “London” :“Frankfurt” : “Tokyo” : “Singapore” : “Sydney”.@Subset(BranchOffices;3)

@Success

Returns 1 (True). Use this function with @If in field validation formulas toindicate that the value entered satisfies the validation criteria.

Syntax@Success

Return valuetrue

Number. The number 1, meaning True.

UsageUse @Success in input validation formulas for editable fields.

Example: @SuccessThis example returns 1 and allows the document to be saved when thevalue in the field Price is less than 100. This indicates that acceptable datawas entered when used in an input validation formula.

@If(Price<100;@Success;@Failure("Price too large"))

@SumAdds a set of numbers or number lists.

Syntax@Sum( numbers )

Parametersnumbers

Numbers or number lists. As many numbers or number lists as youwant to sum.

Chapter 5: Formula Language @Functions A–Z 359

Return valueresult

Number. The sum of all the numbers, including members of number lists.

UsageMake sure the fields you send as parameters contain a numbervalue—Notes interprets empty number fields as the null string.

Negative numbers in lists must be enclosed in parentheses.

Examples: @Sum1. This example returns 3.

@Sum( 1 : 2 )

2. This example returns 11.@Sum( (-1) : 2 ; (-10) : 20 )

3. This example returns 50 if numPersons is a number field containing 5;10; 15; 20.@Sum( numPersons )

4. This example looks at the Transactions view in the current database,whose first column contains number values indicating the amount of atransaction. The formula sums the transactions and places the total inthe result field on the current document.FIELD result:=result;r:=@DbColumn("":""; ""; "Transactions"; 1 );@SetField( "result"; @Sum( r ) )

5. This example displays a view in a dialog box. The first column in theview contains a product name, the second contains its price. After theuser selects one or more products in the dialog box, the formuladisplays the total cost of the selected items.amounts:=@PickList( [Custom]; @DbName ; "Products";"Choose products"; "Please select the products you want toorder"; 2 );total:=@Sum( @TextToNumber( amounts ) );@Prompt([Ok]; "Total"; "The total cost of these productsis " + @Text(total))

360 Domino Designer Programming Guide, Volume 1: Formula Language

@Tan

Given an angle in radians, returns the tangent of the angle. In a righttriangle the tangent of an acute angle is the ratio of the length of theopposite side to the length of the adjacent side.

Syntax@Tan( angle )

Parameterangle

Number. Any angle, expressed in radians.

Return valuetangent

Number. The tangent of angle.

Example: @TanThis example returns 1.

@Tan( @Pi/4 )

@Text

Converts any value to a text string.

Syntax@Text( value ; “format-string ” )

Parametersvalue

Number, time-date, or text. The value you want to convert to text.

“format-string”

Optional. Up to four format-strings (see table below). These determinehow the text is returned. If the value is already a text data type, theformat-string is ignored.

Return valuetextValue

Text. The value you specified, converted to text. If you used anyformat-strings, they are applied.

Chapter 5: Formula Language @Functions A–Z 361

@Text with time-date componentsThere are four separate categories of time-date format-string components.You can include up to four components, but only one from each category.

Symbol Meaning

D0 Year, month, and day

D1 Month and day, year if it is not the current year

D2 Month and day

D3 Year and month

T0 Hour, minute, and second

T1 Hour and minute

Z0 Always convert time to this zone

Z1 Display zone only when it is not this zone

Z2 Display zone always

S0 Date only

S1 Time only

S2 Date and time

S3 Date, time, Today, or Yesterday

Sx Use when you cannot predict the exact format of the value beingpassed, but you know that it will be either a time, a date, or both.

@Text with number valuesFor number values, compose a format-string by combining any of thefollowing components into a string.

Symbol Meaning

G General format (significant digits only)

F Fixed format (set number of decimal places)

S Scientific format (E notation)

C Currency format (two decimal places)

, Punctuated at thousands (using U.S. format)

% Percentage format

( ) Parentheses around negative numbers

number Number of digits of precision

362 Domino Designer Programming Guide, Volume 1: Formula Language

UsageOnce a number value is converted to text, you will not be able to use thenumber for arithmetic calculations.

Examples: @Text1. This example returns 123.45.

@Text(123.45)

2. This example returns $800.00 if the value in the Sales field is 800.@Text(Sales;"C,2")

3. This example returns 8.00E+02.@Text(800;"S")

4. This example returns 04/11/93 10:43 AM.@Text(@Now)

5. This example returns 04/11.@Text(@Now;"D1S0")

6. This example returns 10:43:30 AM.@Text(@Now;"D1S1")

7. This example returns 04/93 10:43 AM.@Text(@Now;"D3T1")

@TextToNumberConverts a text string to a number, where possible.

Syntax@TextToNumber( string )

Parameterstring

Text. The string you want to convert to a number. If the string containsboth numbers and letters, it must begin with a number to be convertedproperly. For example, the string “12ABC” converts to 12, but “ABC12”produces an error.

Chapter 5: Formula Language @Functions A–Z 363

Return valuenumber

Number. The string, converted to a number.

UsageThis function is useful for converting a number in a text field to a numberthat can be used for computation in a number field.

You can’t use @TextToNumber to convert special text (such as that returnedby @DocChildren or @DocDescendants) to a number.

Examples: @TextToNumber1. This example returns 123 as a number.

@TextToNumber("123")

2. This example returns @ERROR if the contents of the field named Costcannot be converted to a number.@TextToNumber(Cost)

@TextToTimeConverts a text string to a time-date value, where possible.

Syntax@TextToTime( string )

Parameterstring

Text. The string you want to convert to a time-date.

Return valuetime-date

Time-date or time-date range. The string, converted to a time-date.

UsageThis function is useful for converting a date within a text field to a valuethat can be used for computation in a time-date field.

“Today”, “Tomorrow”, and “Yesterday” are the only legal strings to use torepresent relative dates. The formula @TextToTime(“Next week”) returns ablank because the text string “Next week” cannot be converted to atime-date value.

364 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @TextToTime1. This example returns 8/10/90 2:40:00 AM.

@TextToTime("8/10/90 2:40")

2. This example returns Today.@TextToTime("Today")

3. This example sets the value of the result field (a time-date field thatallows multiple values) to the date range 04/16/96 - 08/18/96.FIELD result:=result;@SetField( "result" ; @TextToTime( "04/16/96-08/18/96" ) )

@TimeTranslates numbers for the various components of time and date; thenreturns the time-date value.

Syntax@Time( hour ; minute ; second )@Time( year ; month ; day ; hour ; minute ; second ) @Time( time-date )

Parametersyear

Number. The year.

month

Number. The month.

day

Number. The day.

hour

Number. The number of hours you want to appear in the resulting time.

minute

Number. The number of minutes you want to appear in the resulting time.

second

Number. The number of seconds you want to appear in the resulting time.

Chapter 5: Formula Language @Functions A–Z 365

time-date

Time-date. For a time-date value such as @Now or [10/31/93 12:00:00],@Time removes the date portion of the value, leaving only the time.

Return valuetruncatedTimeDate

Time-date. The time corresponding to the parameters you sent to@Time, minus any date components if the parameter is time-date.

Examples: @Time1. This example returns 4/11/51 11:50:30 PM.

@Time(1951;04;11;23;50;30)

2. This example returns 09:19:24 AM at 9:19:24 A.M. on any day.@Time(@Now)

3. This example returns 09:19:24 AM if 9:19:24 A.M. is the time thedocument was created.@Time(@Created)

@TodayReturns today’s date.

Syntax@Today

Return valuetoday

Time-date. Today’s date.

UsageThis function is identical to the formula @Date(@Now). It is usually used indefault value formulas to automatically enter the current date.

Using @Today in column or selection formulas may impact the efficiency ofyour application. It also causes the view refresh indicator to displayconstantly.

In a field formula, Notes takes the value for @Today from the clientcomputer’s clock.

366 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @Today1. This example returns 02/19/93 if today is February 19, 1993.

@Today

2. This example sets the field named ReceivedDate to today’s date.FIELD ReceivedDate:=@Today

@TomorrowReturns the time-date value that corresponds to tomorrow’s date.

Syntax@Tomorrow

Return valuetomorrow

Time-date. Tomorrow’s date.

UsageUsing @Tomorrow in column or selection formulas may impact theefficiency of your application. It also causes the view refresh indicator todisplay constantly.

In a field formula, Notes takes the value for @Tomorrow from the clientcomputer’s clock.

Examples: @Tomorrow1. This example returns 4/26/93 if today is April 25, 1993.

@Tomorrow

2. This example sets the field named AnswerBack to tomorrow’s date.FIELD AnswerBack:=@Tomorrow

@TrimRemoves leading, trailing, and redundant spaces from a text string, or fromeach element of a text list.

Syntax@Trim( string )

Chapter 5: Formula Language @Functions A–Z 367

Parameterstring

Text or text list.

Return valuetrimmedString

Text or text list. The string, with extra spaces removed.

UsageIf a text string is all spaces, @Trim returns an empty string (length of 0). Ifan element of a text list is all spaces, @Trim removes the element. If allelements of a text list are all spaces, @Trim returns an empty string.

Examples: @Trim1. This example returns ROBERT SMITH.

@Trim(@UpperCase("Robert Smith" ))

2. This example returns ROBERT SMITH.@UpperCase(@Trim("Robert Smith" ))

3. This example returns Just a quick reminder, if the original Topic fieldis “Just a quick reminder.”@Trim(Topic)

4. This example returns Seattle;Toronto;Santiago;USA;Canada;Chile ifthe list of values contained in the City field consists of Seattle, Toronto,Santiago; the StateOrProvince field contains no values; and the Countryfield contains the list of values USA, Canada, Chile.@Trim(City:StateOrProvince:Country)

5. This example returns 45 if the content of the field Date is 8/29/8916:30:45.@Trim(@Text(@Second(Date)))

@TrueReturns the number 1. This function is equivalent to @Yes.

Syntax@True

Return valuetrue

Number. The number 1.

368 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @True1. This example returns 1.

@True

2. This example returns 1 if the value in the field named Dept is greaterthan 100.@If(Dept>100;@True;@False)

@UnavailableUse this function to delete a field.

SyntaxFIELD fieldName = @Unavailable

Return valueNone.

UsageThis function does not work in column, selection, hide when, window title,or form formulas. When you use @Unavailable, you delete documents. Donot use @Unavailable with the SELECT statement in an agent, unless youactually want to delete the documents that the agent runs on. Do not usethis function to test to see if a field is available. Use @IsUnavailable instead.

Example: @UnavailableThis formula creates a field named NewDate and sets it to today’s date,then removes the field named OldDate from the document.

FIELD NewDate:=@Today;FIELD OldDate:=@Unavailable;

@UndeleteDocumentIn a database that has soft deletes enabled in the database properties, thiscommand removes the soft deleted status if a document has been softdeleted.

Note This @function is new with Release 5.

Syntax@UndeleteDocument

UsageThis @function can be used in SmartIcons, button, or agent formulas.

Chapter 5: Formula Language @Functions A–Z 369

@Unique

Without a parameter, returns a random, unique text value.

With a parameter, removes duplicate values from a text list byreturning only the first occurrence of each member of the list.

Syntax@Unique@Unique( textlist )

Parametertextlist

Text list. Any text list.

Return valueWithout a parameter:

uniqueValue

Text. A random, unique text value.

With a parameter:

uniqueList

Text list. The text list, with duplicate values removed.

Usage@Unique is case sensitive.

Examples: @Unique1. This example returns red; green; blue.

@Unique("red":"green":"blue":"green":"red")

2. This example returns red; green; blue; Green.@Unique("red":"green":"blue":"Green":"red")

@UpperCaseConverts the lowercase letters in the specified string to uppercase.

Syntax@UpperCase( string )

370 Domino Designer Programming Guide, Volume 1: Formula Language

Parameterstring

Text. The string you want to convert to uppercase.

Return valueuppercaseString

Text. The string, converted to uppercase letters.

UsageThis function is useful when you want to search for a particular value andcannot predict whether it will appear in lowercase, uppercase, or acombination of the two. You can also use it as an input translation formulato convert a field’s contents to uppercase.

Examples: @UpperCase1. This example returns ROBERT T. SMITH.

@UpperCase("Robert T. Smith")

2. This example returns MA if the State field contains “ma”, “Ma”, or “MA”.@UpperCase(State)

3. This example returns FLETCHER if “William Fletcher” is the nameassociated with the current User ID. @UpperCase is used in conjunctionwith @Right to find and convert only the user’s last name.@UpperCase(@Right(@UserName;" "))

@URLGetHeaderReturns specific Hypertext Transfer Protocol (HTTP) header informationfrom the Uniform Resource Locator (URL). A URL is a text string used foridentifying and addressing a Web page.

Syntax@URLGetHeader( urlstring; headerstring; webusername; webpassword;proxywebusername; proxywebpassword )

Parametersurlstring

Text. The URL for the Web page you want to open, for example,http://www.acme.com/.

Chapter 5: Formula Language @Functions A–Z 371

headerstring

Enter a header string to return the desired URL header value. Theacceptable header strings are documented in the HTTP specification(available at locations on the Internet, such as http://www.w3.org/)and are subject to change based on updated versions of thespecification.

webusername$

Text. Optional. Some Internet servers require you to obtain a usernameand password before you can access their pages. This parameter allowsyou to enter the username that you previously obtained from theauthenticated Internet server.

webpassword$

Text. Optional. Some Internet servers require you to obtain a usernameand password before you can access their pages. This parameter allowsyou to enter the password that you previously obtained from theauthenticated Internet server.

proxywebusername$

Text. Optional. Some proxy servers require that you specify a usernamein order to connect through them. This parameter allows you to enterthe username for the proxy server. See your administrator for theusername required by the proxy.

proxywebpassword$

Text. Optional. Some proxy servers require that you specify a passwordin order to connect through them. This parameter allows you to enterthe username for the proxy server. See your administrator for thepassword required by the proxy.

Return Valueheadervaluestring

Text. Returns the header value that you requested. If a null value isreturned, the header value that you requested was not found in theheader of the Web page.

UsageThe @URLGetHeader function should only be used in the context of eitherthe Server Web Navigator or Personal Web Navigator database.

You cannot use this function in Web applications.

372 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @URLGetHeader1. This example returns the last date that the www.acme.com Web page

was modified.@URLGetHeader ("http://www.acme.com/"; "Last-modified")

2. This example returns the name of the Web server software where thewww.acme.com Web page resides.

@URLGetHeader ("http://www.acme.com/"; "Server")

For more information, see Working with the Internet.

@URLHistoryUsed for navigating, saving, and reloading a Uniform Resource Locator(URL) history list. The URL history list keeps track of all the Web pages youhave visited. The history list is used for the Next and Previous buttons andfor the Web Tours.

Syntax@URLHistory( [Command] )

Parameter[Command]

The name of the @URLHistory command you want to use:

Next

Moves to the next URL in the history list.

Prev

Moves to the previous URL in the history list.

Show

Displays the History dialog box.

Save

Saves the history list into a new Web Tour document, which a usercan reload later to follow that history.

Reload

Reloads the current history list from the Web Tour document.

Chapter 5: Formula Language @Functions A–Z 373

UsageThe @URLHistory function works from the Notes workstation only andshould only be used with either the Server Web Navigator or Personal WebNavigator database.

You cannot use this function in Web applications.

Examples: @URLHistoryBelow are examples of each command you want to specify.

[Next]This example moves to the next URL in the history list.

@URLHistory([Next])

[Prev]This example moves to the previous URL in the history list.

@URLHistory([Prev])

[Show]This example displays the History dialog box.

@URLHistory([Show])

[Save]This example saves the history list into a new Web Tour document that auser can reload later to follow that history.

@URLHistory([Save])

[Reload]This example reloads the history list from the Web Tour document.

@URLHistory([Reload])

@URLOpenRetrieves a World Wide Web page specified by its URL.

Syntax@URLOpen

@URLOpen( urlstring )

@URLOpen( urlstring ; [ reloadflag ] )

@URLOpen( urlstring ; [ URLList ] )

@URLOpen( urlstring ; [ reloadflag ]:[ URLList ] )

374 Domino Designer Programming Guide, Volume 1: Formula Language

@URLOpen( urlstring ; [ reloadflag ]:[ URLList ] ; charset$ )

@URLOpen( urlstring ; [ reloadflag ]:[ URLList ] ; charset$ ; webusername$ )

@URLOpen( urlstring ; [ reloadflag ]:[ URLList ] ; charset$ ; webusername$ ;webpassword$ )

@URLOpen( urlstring ; [ reloadflag ]:[ URLList ] ; charset$ ; webusername$ ;webpassword$ ; Proxywebusername$ )

@URLOpen( urlstring ; [ reloadflag ]:[ URLList ] ; charset$ ; webusername$ ;webpassword$ ; proxywebusername$ ; proxywebpassword$ )

Parametersurlstring

Text. Optional. The URL for the Web page you want to open, forexample, http://www.acme.com/.

[ reloadflag ]

Keyword. Optional.

Reload. Reloads the page from its Internet server.

ReloadIfModified. Reloads the page only if it has been modified on itsInternet server.

[ URLList]

Keyword. Optional. Web pages can contain URL links to other Webpages. This keyword specifies that the Web Navigator should save theURLs in a field called URLLinksn in the Notes document. (The WebNavigator creates a new URLLinksn field each time the field sizereaches 64K. For example, the first URLLinks field would beURLLinks1, the second would be URLLinks2, and so on.)

If you save the URLs, you can use them in agents; for example, youcould create an agent that opens Web pages in the Web Navigatordatabase and then loads all the Web pages saved in each of theURLLinksn field(s).

Caution Saving URLs in the URLLinksn field(s) may affect performance.

[Reload] : [URLList]

Keywords. Optional. Specify both keywords to force a reload of theWeb page and save the URLs in the URLLinksn field in the Notesdocument.

Chapter 5: Formula Language @Functions A–Z 375

charset$

Text. Optional. Enter the MIME character set (for example, ISO-2022-JPfor Japanese or ISO-8859-1 for United States) that you want the WebNavigator to use when processing the Web page. Only use thisparameter when the Web Navigator misdetects the correct MIMEcharacter set of the URL contents.

webusername$

Text. Optional. Some Internet servers require you to obtain a usernamebefore you can access their pages. This parameter allows you to enterthe username that you previously obtained from the Internet server.

webpassword$

Text. Optional. Some Internet servers require you to obtain a passwordbefore you can access their pages. This parameter allows you to enterthe password that you previously obtained from the Internet server.

proxywebusername$

Text. Optional. Some proxy servers require that you specify a usernamein order to connect through them. This parameter allows you to enterthe username for the proxy server. See your administrator for theusername required by the proxy.

proxywebpassword$

Text. Optional. Some proxy servers require that you specify a passwordin order to connect through them. This parameter allows you to enterthe password for the proxy server. See your administrator for thepassword required by the proxy.

UsageThe @URLOpen function works from both the Notes workstation andserver and should only be used in the context of the Web Navigatordatabase.

For use on the server, you need to specify at least one parameter with thefunction; using the function without any parameters will attempt to displaythe URL Open dialog box which cannot be done from the server. If youwant to use any of the parameters that follow the Reload and URLListkeywords without specifying values for either of the keywords, enter a zero(0) in place of the keyword value(s). For example,@URLOpen(“http://www.ibm.com”;0;“myusername”;“mypassword”).

376 Domino Designer Programming Guide, Volume 1: Formula Language

Examples: @URLOpen1. This example displays the URL Open dialog box that allows a user to

enter the URL.@URLOpen

2. This example opens the www.acme.com Web page from the database ifit is found there. If the page is not found in the database, it is retrievedfrom the Web, loaded into the database, and then opened.@URLOpen("http://www.acme.com/")

3. This example retrieves the www.acme.com Web page from the Web,loads it into the database, and then opens it.@URLOpen("http://www.acme.com"/; 1)

@UserAccessGiven a server and file name, indicates the current user’s level of access tothe database.

Note If you used @UserAccess in Release 4 of Domino, it is automaticallyconverted to @V4UserAccess in Release 5 to preserve the functionality ofyour formulas. If you change those formulas to use @UserAccess, be sure torecompile them under Release 5. If you use @UserAccess in Release 5, adatabase created in Release 4 will not recognize the formula until youupgrade that database to Release 5. If the formula will be evaluated inRelease 4, use @V4UserAccess.

Syntax@UserAccess( server : file )

Parametersserver

Text. The name of the server. Use an empty string (“”) to indicate thelocal computer.

file

Text. The path and file name of the database. Specify the database’spath and file name using the appropriate format for the operatingsystem.

Chapter 5: Formula Language @Functions A–Z 377

Return Valuelevel : create documents : delete documents : create personal agents : create personalfolders/views : create shared folders/views : create LotusScript/Java agent : readpublic documents : write public documents

Text list.

level is a number from 1 to 6 that indicates the user’s access level tothe database.

level User’s access level

1 Depositor

2 Reader

3 Author

4 Editor

5 Designer

6 Manager

create documents is a number that returns 1 (True) if the user cancreate documents in the database, and 0 (False) if not.

delete documents is a number that returns 1 (True) if the user candelete documents from the database, and 0 (False) if not.

create personal agents is a number that returns 1 (True) if the user cancreate personal agents in the database, and 0 (False) if not.

create personal folders/views is a number that returns 1 (True) if theuser can create personal views or folders in the database, and 0(False) if not.

create shared folders/views is a number that returns 1 (True) if the usercan create shared views or folders in the database, and 0 (False) ifnot.

create LotusScript/Java agent is a number that returns 1 (True) if theuser can create LotusScript or Java agents in the database, and 0(False) if not.

read public documents is a number that returns 1 (True) if the user canread public documents in the database, and 0 (False) if not.

write public documents is a number that returns 1 (True) if the user canwrite public documents in the database, and 0 (False) if not.

On a local database, @UserAccess always returns 6:1:1. If the currentuser has No Access to the database, Notes displays a message: “You arenot authorized to perform that operation.”

378 Domino Designer Programming Guide, Volume 1: Formula Language

UsageThis function does not work in column or selection formulas, or in agentsthat run on a server (mail and scheduled agents).

Examples: @UserAccess1. This formula returns “3”;“1”;“1”,“1”,“1”0“, if the user has Author

access, permission to create documents, delete documents, createpersonal agents, create personal views and folders, but does not havepermission to create shared views and folders in the nun.nsf databasein the discuss directory on server Gaborone.@UserAccess( ”Gaborone" : "discuss\\nun.nsf" )

2. This formula returns “6”;“1”;“1”,“1”,“1”,“1”,“1”,“1”,“1” if the user hasManager access and permission to create and delete documents, createpersonal agents, create personal and shared views and folders, createLotusScript and/or Java agents, read and write public documents in thecurrent database.@UserAccess( @DbName )

@UserNameReturns the current user name or server name.

If the user name is hierarchical, @UserName returns it in canonical format(including the CN, OU, O, and C identifiers). To return the name inabbreviated format (omitting those identifiers), use @V3UserName.

Note If you used @UserName in Release 3 of Notes, it is automaticallyconverted to @V3UserName in Release 4 to preserve the functionality ofyour formulas. If you change those formulas to use @UserName, be sure torecompile them under Release 4. If you use @UserName in Release 4, adatabase created in Release 3 will not recognize the formula until youupgrade that database to Release 4. If the formula will be evaluated inRelease 3, use @V3UserName.

Note @UserName has been extended in R5.0 to return the alternate nameas well as the primary name which is associated with the ID.

Syntax@UserName ( index )

Parameterindex

Note This parameter is new with Release 5.

Chapter 5: Formula Language @Functions A–Z 379

Number. Optional. Indicating the index of usernames. 0 is for primaryname and 1 is for the alternate name. If this parameter is omitted,@UserName returns the primary name.

Return valuename

Text. The primary or alternate username or alternate server name.

UsageWhen a formula runs on a server, the server is considered the current user,so @UserName returns the name of the server. Using @UserName on a localdatabase or in a private view in a server-based database returns the user’sname. You should not use @UserName in a public view, doing so willproduce unpredictable results. Also, if the field that you are referencingchanges, you will get unpredictable results because the index has to berebuilt to accommodate the new information.

One use for @UserName is to display only those documents relevant to thecurrent user. For example, your Service Request database could use@UserName in the private view named Assignments to display eachtechnician’s assignments, weeding out everyone else’s:

SELECT @UserName=AssignedTo

However, the user can still design a different private view that retrieves alldocuments, so don’t depend on @UserName as a security mechanism.

As an R5.0 Domino user, since you may have an alternate name as well as aprimary name, it is best to store the alternate name in the document asauthor information when using the extended feature of @UserName.

Examples: @UserName1. This example returns Robert T. Smith if this is the name associated with

the current user ID.@UserName(0)

2. This example returns Rob if it is the first alternate name associated withthe current user ID.@UserName(1)

3. This example returns Fletcher if William Fletcher is the name associatedwith the current User ID.@Right(@UserName;" ")

4. This example returns FLETCHER if William Fletcher is the nameassociated with the current User ID.@UpperCase(@Right(@UserName;" "))

380 Domino Designer Programming Guide, Volume 1: Formula Language

5. This example returns the name in canonical format as shown below.Given this hierarchical user ID: CN=MaryTsen/OU=Illustration/OU=Documentation/OU=Development/OU=R&D/O=WorkSavers/C=US. To return the name in abbreviated format (omitting the CN, OU, O, and C identifiers), use @V3UserName.@UserName

@UserNameLanguage

Returns language tags associated with the user ID.

Note This @function is new with Release 5.

Syntax@UserNameLanguage( index )

Parametersindex

Number. Indicates the index of user names. 0 is for primary name and 1 is for alternate name. Numbers greater than 1 are not used butreserved for future use.

Return valuenamelanguage

Text. Language tag for the alternate user name. If the user does nothave the alternate name, @UserNameLanguage returns an empty string(“”). Also, this function returns an empty string for the primary name.

UsageThe alternate name is expected to be used for a user’s native languagename.

Generally the native language name contains non-ASCII characters andcannot be displayed correctly without some proper fonts. The return valuefrom @UsernameLanguage is used as reference of the native language.

@UserNameLanguage can be used as a default value formula to store theauthor’s alternate language tag in their document as well as their primaryname and alternate name. While referring to the language tag, the Dominoapplication can switch the display name on the document between theprimary name and the alternate name.

Chapter 5: Formula Language @Functions A–Z 381

Examples: @UserNameLanguage1. The following example returns “ja” if you have a Japanese name for

your alternate name.@UserNameLanguage(1)

2. The following example returns an empty string (“”) because theprimary name has no language tag associated.@UserNameLanguage(0)

@UserNamesListFor a database on a server or a local database with “Enforce a consistentAccess Control List across all replicas” in effect, @NamesList returns a textlist containing the current user name, any group names, and any roles.

Note This @Function is new with Release 5.

Syntax@UserNamesList

Return valuenames

Text list. Each item in the list is the current user name, group name, andthe name of a role that the current user has in the current database.Returns an empty string (“”) if the current database is local and“Enforce a consistent Access Control List across all replicas” is not ineffect.

UsageThis function does not work in column, selection, mail agent, or scheduledagent formulas.

Choose File - Database - Access Control, Advanced to set “Enforce aconsistent Access Control List across all replicas.”

UserNamesList.

Example: @UserNamesListThis subform formula selects a different subform depending on whether theuser is a member of the Marketing team or not.

@If(@IsMember("Marketing Team"; @NamesList); "Marketing Head"; "Generic Head")

382 Domino Designer Programming Guide, Volume 1: Formula Language

@UserPrivileges

Returns a text list of the current user’s privileges. This function returns onlythe position of the privilege in the privilege list, not the name of theprivilege.

Syntax@UserPrivileges

Return valueprivileges

Number or number list.

UsageThis function does not work in column, selection, mail agent, or scheduledagent formulas.

You cannot use this function in Web applications.

Examples: @UserPrivileges1. A database has five privileges. User Mary Tsen has been assigned

Privileges 2 and 3. This example returns 2:3 (as a text list, not a numericlist).

@UserPrivileges

2. This form formula causes the Marketing Report form to be used if thecurrent user has been assigned the first privilege in the list (regardlessof what it is called); otherwise, the Main Topic form is used.

@If(@UserPrivileges = "1"; "Marketing Report"; "Main Topic")

@UserRoles

For a database on a server or a local database with “Enforce a consistentAccess Control List across all replicas” in effect, returns a list of roles thatthe current user has. Roles are defined in a database’s access control list.

Syntax@UserRoles

Chapter 5: Formula Language @Functions A–Z 383

Return valueroles

Text list. Each item in the list is the name of a role that the current userhas in the current database. The role names are enclosed in brackets.Returns an empty string (“”) if the current database is local and“Enforce a consistent Access Control List across all replicas” is not ineffect.

UsageThis function does not work in column, selection, mail agent, or scheduledagent formulas.

Choose File - Database - Access Control, Advanced to set “Enforce aconsistent Access Control List across all replicas.”

@UserRoles appends $$WebClient to the list of roles when a Web useropens a database.

@UserRoles returns a subset of the information returned by@UserNamesList.

Example: @UserRolesThis subform formula selects a different subform depending on whether theuser is a Web client or not.

@If(@IsMember("WebClient"; @UserRoles); "WebSubform";"NotesSubform")

@V2IfThis function performs an @If operation; the syntax is the same as for @If.Syntax

@V2If(condition1 ; action1 ; condition2 ; action2 ; condition99 ; action99 ;else_action )

UsageUse @V2If when you expect your application to be used with Notes Release2.x. If the application will only be used with Notes Release 3 or Release 4users, you should use @If. The @If function in Notes Release 3 wasredesigned to work in conjunction with the new @functions first available inRelease 3, such as @Prompt. Due to these changes, releases of Notes beforeRelease 3 cannot evaluate @If correctly, and will return an error message.

Note In applications created with earlier releases of Notes, the @If functionwill automatically be renamed to @V2If during the upgrade to Release 4.

384 Domino Designer Programming Guide, Volume 1: Formula Language

@V3UserName

Returns the current user name or server name. Using @V3UserName on alocal database or in a private view in a server-based database returns theuser’s name.

If the user name is hierarchical, @V3UserName returns the name inabbreviated format (omitting the CN, OU, O, and C identifiers). To returnthe name in canonical format, use @UserName.

Note If you used @UserName in Release 3 of Notes, it is automaticallyconverted to @V3UserName in Release 4 to preserve the functionality ofyour formulas. If you change those formulas to use @UserName, be sure torecompile them under Release 4. If you use @UserName in Release 4, adatabase created in Release 3 will not recognize the formula until youupgrade that database to Release 4. If the formula will be evaluated inRelease 3, use @V3UserName.

Syntax@V3UserName

Return Valuename

Text. The current user name or server name.

UsageWhen a formula runs on a server, the server is considered the current user,so @V3UserName returns the name of the server. We do not recommendusing @V3UserName in a public view. Doing so will produce unpredictableresults.

One use for @V3UserName is to display only those documents relevant tothe current user. For example, your Service Request database could use@V3UserName in the private view named Assignments to display eachtechnician’s assignments, weeding out everyone else’s:

SELECT @V3UserName=AssignedTo

However, the user can still design a different private view that retrieves alldocuments, so don’t depend on @V3UserName as a security mechanism.

Examples: @V3UserName1. @V3UserName returns Robert T. Smith if this is the name associated

with the current user ID.

2. @Right(@V3UserName;“ ”) returns Fletcher if William Fletcher is thename associated with the current user ID.

Chapter 5: Formula Language @Functions A–Z 385

3. @UpperCase(@Right(@V3UserName;“ ”)) returns FLETCHER ifWilliam Fletcher is the name associated with the current user ID.

4. Given this hierarchical user ID:CN=MaryTsen/OU=Illustration/OU=Documentation/OU=Development/OU=R&D/O=WorkSavers/C=US

@V3UserName returns the name in abbreviated format:MaryTsen/Illustration/Documentation/Development/R&D/WorkSavers/US

To return the name in canonical format (using the CN, OU, O, and Cidentifiers), use @UserName.

@ValidateInternetAddress

Validates an Internet address based on the RFC 822 or RFC 821 AddressFormat Syntax.

Note This @function is new with Release 5.

Syntax@ValidateInternetAddress( [KEYWORD] ; Address )

ParametersKeywords

[Address821]

Request input address be validated based on RFC821 Address FormatSyntax.

SStreitfeld@gazette.com

[Address822]

Request input address be validated based on RFC822 Address FormatSyntax.

“Streitfeld, Sara (Miami)” <SStreitfeld@gazette.com>

Address

Input address string

Return ValueIf validation is successful, the NULL string will be returned.

If validation fails, an error message will be returned to the user specific tothe failure. More error messages will be added in the future as necessary.

386 Domino Designer Programming Guide, Volume 1: Formula Language

Possible error messages“Invalid Input Parameter”

Invalid parameters to @function - @ValidateInternetAddress.

“Invalid RFC821 syntax, no Phrase required.”

When a phrase is present in an address requiring an RFC821 syntax.

“Invalid Phrase or character found.”

Phrase part of 822 address invalid.

“Invalid Quoted String or mismatched quotes found.”

Quoted string is invalid within the address.

“Invalid comment or mismatched parenthesis found.”

Embedded (comment(s)) within address is invalid.

“Invalid or missing Domain.”

Invalid or missing Domain part of Address.

“Invalid LocalPart or character found.”

Invalid LocalPart specified.

Usage@ValidateInternetAddress is currently used in location records to validateInternet address fields as well as in mail forms. This function is most usefulin field validation formulas where users are asked to input their Internetaddress or in computed fields where Internet addresses are inherited.

Note Multibyte, or 8bit characters, are allowed in the Phrase part of anRFC 822 format Internet address. They are not allowed anywhere else. Also,the Group syntax (i.e. several Internet addresses combined into one groupname such as, “Customers”) is not supported in the validator.

Examples: @ValidateInternetAddressYou have designed a form asking the user to input an Internet address. Theuser enters a standard RFC 821 format Internet addressSStreitfeld@gazette.com in the editable field User_Address.

In the field validation formula you have entered

@ValidateInternetAddress([Address821];User_Address)

Chapter 5: Formula Language @Functions A–Z 387

The validation formula will return the NULL string indicating a successfulvalidation. However if the user entered:

"Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com>

The validation formula would return the following error message:

"Invalid RFC821 syntax, no Phrase required."

@Version

Returns the release number of the Notes software you’re running.

Syntax@Version

Return valueversionNumber

String. The release number.

UsageIn column, selection, mail agent, and scheduled agent formulas, @Versionreturns the release number of the Notes server or workstation containingthe database. In all other formulas, @Version returns the release number ofthe Notes workstation running the formula.

The following table maps the numbers returned by @Version to each Notes version.

Number Returned by @Version Corresponding Notes version

114 Notes 3.x

136 Notes 4.0, 4.0x

138 Notes 4.1, 4.1x

145 Notes 4.5, 4.5x

147 Notes 4.6

Note the following:

@Version returns the same number for all releases of Notes 3.x.

@Version doesn’t distinguish between the maintenance releases ofNotes 4.x.

388 Domino Designer Programming Guide, Volume 1: Formula Language

@ViewTitle

Returns the current view’s name. If there are aliases and synonyms, they arereturned in a text list.

Syntax@ViewTitle

Return valuetitle

Text or text list.

UsageThis function works in SmartIcons, button, hotspot, or form actionformulas, if the formula opens to a view using an @command such asFileOpenDatabase. It can be used in hide-when formulas for view actionbars, but not for other hide-when formulas. It does not work in column,selection, mail agent, paste agent, scheduled agent, section editor, windowtitle, or field formulas.

Examples: @ViewTitle1. This example returns Main View if that is the title of the current view.

@ViewTitle

2. This example returns “Main View”:“By Date” if the view name is MainView|By Date.@ViewTitle

3. This example returns MAIN VIEW if the title of the current view is“main view” in any combination of uppercase and lowercase letters.@UpperCase(@ViewTitle)

@Weekday

Computes the day of the week and returns a number that identifies the day.

Syntax@Weekday( time-date )

Parametertime-date

Time-date. The date whose weekday value you want.

Chapter 5: Formula Language @Functions A–Z 389

Return valueweekdayNumber

Number. Weekday numbers are 1 through 7, with Sunday = 1, Monday = 2, and so on.

Examples: @Weekday1. This example returns 5.

@Weekday([9/29/88])

2. This example returns 2 if the date in the response field happens to fallon a Monday.@Weekday(ResponseDate)

3. This example returns the string Working on the Weekend if the contents of the field named ResponseDate is 7 (Saturday) or 1 (Sunday);otherwise, it returns the date the document was created as a text string.@If(@Weekday(ResponseDate) = 7 | @Weekday(ResponseDate) =1;"Working on the Weekend";@Text(@Created))

@WideConverts half-pitch alphanumeric characters (single byte characters - SBCS)in the specified string to full-pitch alphanumeric characters (double bytecharacters - DBCS). This function works in Japanese, Korean, SimplifiedChinese, and traditional Chinese environments. In the Japaneseenvironment, this function can convert half-pitch Katakana as well.

Note This @function is new with Release 5.

Syntax@Wide(string )

Parameterstring

Text. The string you want to convert to double byte characters.

Return valuereturnstring

Text. The string converted to double byte characters.

390 Domino Designer Programming Guide, Volume 1: Formula Language

UsageThis function can be used in input translation formulas to convert a field’scontents to double byte characters or in computed field formulas to savespace for displaying string.

Examples: @Wide1. This input translation formula returns “Tokyo” as a full-pitch character,

if the Location field contains a half-pitch character expression of“Tokyo”.@Wide(Location)

2. This computed field formula returns “New York” as a full-pitchcharacter, to save space for displaying the string.@Wide("New York")

@WordReturns the specified word from a text string. A “word” is defined as thepart of a string that is delimited by the defined separator character. Forexample, if you specify a space (“ ”) as the separator, then a word is anyseries of characters preceded by and followed by a space (or by thequotation marks that indicate the beginning or end of the string).

@Word( string ; separator ; number )

Syntaxstring

Text or text list. The string you want to scan.

separator

Text. The character that you want used to delimit a word in the string.

number

Number. A position indicating which word you want returned from string.

Return valueword

Text or text list. The word that holds the position specified by thenumber in the string; for example, if number is 3, @Word returns thethird word in the string. If a text list is used, @Word returns (in listformat) a word from each list that holds the specified position.

Chapter 5: Formula Language @Functions A–Z 391

Examples: @Word1. This example returns Collins,.

@Word("Larson, Collins, and Jensen"; " " ; 2)

2. This example returns Collins,:Marketing,.@Word("Larson, Collins, and Jensen":"Sales, Marketing, andAdministration";" ";2)

3. This example returns M.; here, the specified separator is the comma.The string contains 3 words: Larson, James, and M.@Word("Larson,James,M.";",";3)

4. This example returns Larson if James Larson is the name associatedwith the current User ID. It returns M. if James M. Larson is the nameassociated with the current User ID.@Word(@Username;" ";2)

@YearExtracts and returns the year from the specified time-date value.

Syntax@Year( time-date )

Parametertime-date

Time-date. The time-date whose year you want.

Return Valueyear

Number. The year of time-date. @Year returns the year relative to thetime zone in which the date was generated.

Example: @YearThis example returns 1995.

@Year([9/29/95])

392 Domino Designer Programming Guide, Volume 1: Formula Language

@Yes

Returns the value 1.

Syntax@Yes

Return valueyes

Number. The number 1.

UsageThis function is equivalent to @True.

Examples: @Yes1. This example returns 1.

@Yes

2. This example returns 1 if the value in the field named Cost is greaterthan 100.@If(Cost>100;@Yes;@No)

@Yesterday

Returns the time-date value which corresponds to yesterday’s date.

Syntax@Yesterday

Return valueyesterday

Time-date. Yesterday’s date.

UsageUsing @Yesterday in column or selection formulas may impact theefficiency of your application. It also causes the view refresh indicator todisplay constantly.

In a field formula, Notes takes the value for @Yesterday from the clientcomputer’s clock.

Chapter 5: Formula Language @Functions A–Z 393

Examples: @Yesterday1. This example returns 12/31/92 if today is January 1, 1993.

@Yesterday

2. This example returns 8/16/93 if today is August 17, 1993.@Yesterday

@ZoneReturns the time zone setting of the current computer or of a time-datevalue, and indicates if Daylight Saving Time is observed.

The time zone is represented as the number of hours that must be added tothe time-date to convert it to Greenwich Mean Time.

Syntax@Zone@Zone( timeDate )

ParametertimeDate

Time-date. Optional. The time-date whose zone you want to know. Youmust specify both a date and a time; otherwise, @Zone returns 0.

Return ValuezoneNumber.dstFlag

Number. The time zone, followed by a period, followed by a flagindicating Daylight Saving Time.

For time zones east of GMT, zoneNumber is negative.

For time zones west of GMT, zoneNumber is positive.

When you use @Zone with no parameter, and Daylight Saving Timeis being observed on the current computer, dstFlag is 1. If DaylightSaving Time is not being observed, only the zoneNumber is returned.

When you use @Zone with a parameter, and the specified date fallswithin the Daylight Saving Time boundary, dstFlag is 1. If the datedoes not fall within Daylight Saving Time, only the zoneNumber isreturned.

UsageWhen used without a parameter, @Zone returns the zone and DaylightSaving Time setting of the current computer.

394 Domino Designer Programming Guide, Volume 1: Formula Language

When used with the parameter currentTimeDate, @Zone returns the zoneand Daylight Saving Time setting of currentTimeDate.

Time zones that are not full-hour increments from GMTFor time zones that are not a full hour increment from GMT, the returnvalue is:

mmhh.dstFlag

mm is the minutes component of the time relative to GMT.

hh is the hours component of the time relative to GMT

dstFlag is .1 if Daylight Saving Time is being observed. Otherwise, onlythe mmhh is returned.

For example, on a computer with a time zone setting eleven and a half hours west of GMT, with Daylight Saving Time disabled, @Zonereturns: 3011

On a computer with a time zone setting ten and three-quarter hours west ofGMT, with Daylight Saving Time enabled, @Zone returns: 4510.1

On a computer with a time zone setting nine and a half hours east of GMT,with Daylight Saving Time enabled, @Zone returns: -3009.1

Examples: @Zone1. This example returns:

5.1 for Eastern Standard Time and Daylight Saving Time observed.

5 for Eastern Standard Time and Daylight Saving Time not observed.

6 for Central Standard Time and Daylight Saving Time not observed.

7.1 for Mountain Standard Time and Daylight Saving Time observed.

8.1 for Pacific Standard Time and Daylight Saving Time observed.@Zone

2. This example returns 5 if in the Eastern Standard time zone.@Zone([1/26/94 11:00 AM])

3. This example returns 5.1 if in the Eastern Standard time zone andDaylight Saving Time is observed, 5 if Daylight Saving Time is notobserved.@Zone([5/28/94 11:00 AM])

Chapter 5: Formula Language @Functions A–Z 395

Chapter 6Formula Language @Commands A–Z

This chapter lists all the commands in alphabetical order. The syntax for each command is shown, including usage notes and examples, where appropriate.

Using @Commands

An @command executes a Domino command. All of the standard menucommands can be executed using @commands. In addition, a number ofspecialized commands are available.

Syntax@Command([commandName] ; parameters )

Parameters[commandName]

The name of the @command you want to perform.

parameters

Zero, one, or more parameters, depending on the @command you’recalling. Separate parameters with semicolons.

Return valueNone.

@Commands with ECL security

The following table lists the @commands affected by an execute control list(ECL). Those @commands do not execute on the workstation unless themarked ECL privileges are granted to the formula’s signer.

The ECL flags listed in the table are:

Access to the file system (file)

Access to current database (cur)

Access to non-Notes databases (db)

397

Access to external code (code)

Access to external programs (prog)

Ability to send mail (mail)

file cur db code prog mail

AdminSendMailTrace X

AgentEnableDisable X

AgentRun X

AgentSetServerName X

AgentTestRun X

AttachmentDetachAll X

AttachmentLaunch X

DesignRefresh X

EditClear X

EditCopy X

EditCut X

EditDetach X

EditInsertFileAttachment X

EditInsertObject X

EditOpenLink X

EditPaste X

EditPasteSpecial X

EditUntruncate X

EmptyTrash X

ExchangeUnreadMarks X

Execute X

FileDatabaseCompact X

FileExport X

FileImport X

FileOpenDatabase X

FileOpenDbRepID X

FilePrint X

continued

398 Domino Designer Programming Guide, Volume 1: Formula Language

file cur db code prog mail

FileSave X

FileSaveNewVersion X

Folder X

FolderMove X

FolderRename X

MailForward X

MailForwardAsAttachment X

MailRequestCrossCert X

MailRequestNewName X

MailRequestNewPublicKey X

MailSend X

MailSendCertificateRequest X

MailSendEncryptionKey X

MailSendPublicKey X

ObjectOpen X

OpenDocument X

RemoveFromFolder X

ReplicatorReplicateHigh X

ReplicatorReplicateNext X

ReplicatorReplicateSelected X

ReplicatorReplicateWithServer X

ReplicatorSendMail X

ReplicatorSendReceiveMail X

ReplicatorStart X

SetCurrentLocation X

ToolsCategorize X

ToolsReplicate X

ToolsRunBackgroundMacros X X

ToolsRunMacro X X

ToolsScanUnreadSelected X

ViewRefreshUnread X

Chapter 6: Formula Language @Commands A–Z 399

AddBookmark

Adds a bookmark with the specified URL or current object.

Note This @function is new with Release 5.

Syntax@Command([AddBookmark] ; urlstring )

@Command([AddBookmark] ; urlstring ; title )

@Command([AddBookmark] ; urlstring ; title ; folder )

Parametersurlstring

Text. Optional. The URL for the Web page that you would like tobookmark. If you specify a null (“”) string, this function takes thecurrent object using the Domino URL scheme as the object to bebookmarked.

title

Text. Optional. The title that you would like to specify for thebookmark. If you specify a null (“”) string, you get a default title.

folder

Text. The name of the folder where you would like to place thebookmark. If you specify a null (“”) string, this function will selecteither an open bookmark page, or a default bookmark folder.

AddDatabase

Adds the specified database icon to the user’s workspace, without openingthe database.

Syntax@Command([AddDatabase] ; server : database ; bookmark )

Parametersserver

Text. The name of the server where the database is.

database

Text. The path and file name of the database.

400 Domino Designer Programming Guide, Volume 1: Formula Language

bookmark

Note This parameter is new with Release 5.

Text (“0” or “1”). Optional. Specify “1” to bring up the Add Bookmarkdialog box. Here, you can select or create a folder in which thebookmark should be placed. If you specify “0” or omit this parameter, itwill bookmark the database in the Databases folder.

Example: AddDatabaseThis formula adds TRADEMRK.NSF to the user’s workspace; this databaseis stored in the Document directory on the LEGAL server.

@Command([AddDatabase]; "LEGAL" : "Document\\TRADEMRK.NSF")

AddDatabaseRepIDAdds an icon to the desktop for the database specified by its replica ID.

Syntax@Command([AddDatabaseRepID] ; replicaID ; serverHint ; bookmark )

ParametersreplicaID

Text. The replica ID of the database to be added to the desktop.

serverHint

Text. Optional. The name of the server where the replica might reside. Notes checks this server for the replica before checking the other servers.

bookmark

Note This parameter is new with Release 5.

Text (“0” or “1”). Optional. Specify “1” to bring up the Add Bookmarkdialog box. Here, you can select or create a folder in which thebookmark should be placed. If you specify “0” or omit this parameter, itwill bookmark the database in the Databases folder.

UsageAddDatabaseRepID is similar to @Command([AddDatabase]) but uses areplica ID instead of a server/path name.

The database has to exist in the Notes Data directory on the server,otherwise it will not be found.

Chapter 6: Formula Language @Commands A–Z 401

AddDatabaseRepID looks for the replica in the following order:

Checks the user’s workspace.

Checks the server indicated in the serverHint.

Checks other servers known to the current session.

AdminCertify

Displays the Choose Certifier ID dialog box, where you can select a certifierID file. After selecting a certifier ID and entering its password, you selectthe user or server ID to be certified.

Syntax@Command([AdminCertify])

UsageThis command works almost anywhere in Notes except from within adialog box.

AdminCreateGroup

Opens an Address Book and displays a blank Group form.

Syntax@Command([AdminCreateGroup])

UsageAdminCreateGroup is available only when the Administration ControlPanel is open.

When there is only one Address Book on the selected server,AdminCreateGroup opens it and displays a blank Group form so that you can add a new group to that Address Book. When there aremultiple Address books on the selected server, Notes displays a dialog box that allows you to select the Address Book to open.

402 Domino Designer Programming Guide, Volume 1: Formula Language

AdminCrossCertifyIDFile

Displays the Choose Certifier ID dialog box, where you can select a certifierID file. After you select a certifier ID and enter its password, Notes displaysthe Choose ID to be Cross-Certified dialog box, which allows you to create ahierarchical cross certificate for an ID in another organization.

Syntax@Command([AdminCrossCertifyIDFile])

AdminCrossCertifyKeyDisplays the Choose Certifier ID dialog box, where you can select a certifierID file. After you select a certifier ID and enter its password, Notes displaysthe Cross Certify Key dialog box, which allows you to create a crosscertificate for an ID in another organization using the numeric keyassociated with that ID.

Syntax@Command([AdminCrossCertifyKey])

AdminDatabaseAnalysisDisplays the Database Analysis dialog box, which provides informationabout the selected database on the selected server.

Syntax@Command([AdminDatabaseAnalysis])

UsageAdminDatabaseAnalysis is available only when the Administration ControlPanel is open.

Chapter 6: Formula Language @Commands A–Z 403

AdminDatabaseQuotas

Displays for the selected server a list of the databases for which you canchange the size limits.

Syntax@Command([AdminDatabaseQuotas])

UsageAdminDatabaseQuotas is available only when the Administration ControlPanel is open.

AdminIDFileClearPassword

Allows the administrator to delete the password associated with any userID file, without having to first switch to that ID and make it active.

Syntax@Command([AdminIDFileClearPassword])

UsageThis command works almost anywhere in Notes except from within adialog box.

AdminIDFileExamine

Displays the Choose ID File to Examine dialog box. After the administratorselects an ID, Notes displays the User ID dialog box, which containsinformation about the ID’s license type, certificates, and encryption keys.

Syntax@Command([AdminIDFileExamine])

UsageThis command works almost anywhere in Notes except from within adialog box.

404 Domino Designer Programming Guide, Volume 1: Formula Language

AdminIDFileSetPassword

Allows the administrator to assign a password to any user ID file, withouthaving to first switch to that ID and make it active.

Syntax@Command([AdminIDFileSetPassword])

UsageThis command can be used almost anywhere in Notes except from within adialog box. This command is particularly useful for changing the passwordon a certifier ID.

Administration

Opens the Notes Administration Control Panel.

Syntax@Command([Administration])

UsageThis command works anywhere in Notes except from within a dialog box.

AdminNewOrganization

Displays the Register Organization Certifier dialog box, where aadministrator can create a hierarchical certifier ID for an organization. Afterthe administrator enters a name and password for the new certifier ID,Notes asks the user where to save the ID file and then creates the ID.

Syntax@Command([AdminNewOrganization])

UsageThis command works anywhere in Notes except from within a dialog box.

Chapter 6: Formula Language @Commands A–Z 405

AdminNewOrgUnit

Prompts for the certifier ID password and then displays the RegisterOrganizational Unit Certifier dialog box, where the administrator can createa hierarchical certifier ID for an organizational unit.

Syntax@Command([AdminNewOrgUnit])

UsageThis command works anywhere in Notes except from within a dialog box.

AdminOpenAddressBook

Opens an Address Book on the selected server.

Syntax@Command([AdminOpenAddressBook])

UsageAdminOpenAddressBook is available only when the AdministrationControl Panel is open.

When there is only one Address Book on the selected server,AdminOpenAddressBook opens it. When there are multiple Address bookson the selected server, Notes displays a dialog box that allows you to selectthe Address Book to open.

AdminOpenCatalog

Opens the database catalog (catalog.nsf) on the selected server.

Syntax@Command([AdminOpenCatalog])

UsageAdminOpenCatalog is available only when the Administration ControlPanel is open.

406 Domino Designer Programming Guide, Volume 1: Formula Language

AdminOpenCertLog

Opens the certification log (certlog.nsf) on the selected server.

Syntax@Command([AdminOpenCertLog])

UsageAdminOpenCertlog is available only when the Administration ControlPanel is open.

In order for AdminOpenCertLog to operate successfully, there must be acopy of a database named CERTLOG.NSF on the selected server.

AdminOpenGroupsView

Opens an Address Book on the selected server and displays its Groups view.

Syntax@Command([AdminOpenGroupsView])

UsageAdminOpenGroupsView is available only when the Administration ControlPanel is open.

When there is only one Address Book on the selected server,AdminOpenGroupsView opens it and displays its Groups view. Whenthere are multiple Address books on the selected server, Notes displays adialog box that allows you to select the Address Book to open.

AdminOpenServerLog

Opens the server log (log.nsf) on the selected server.

Syntax@Command([AdminOpenServerLog])

UsageAdminOpenServerLog is available only when the Administration ControlPanel is open.

Chapter 6: Formula Language @Commands A–Z 407

AdminOpenServersView

Opens an Address Book on the selected server and displays its Servers view.

Syntax@Command([AdminOpenServersView])

UsageWhen there is only one Address Book on the selected server,AdminOpenServersView opens it and displays its Servers view. Whenthere are multiple Address books on the selected server, Notes displays adialog box that allows you to select the Address Book to open.

AdminOpenStatistics

Opens the statistics reporting database (statrep.nsf) on the selected server.

Syntax@Command([AdminOpenStatistics])

UsageAdminOpenStatistics is available only when the Administration ControlPanel is open.

For AdminOpenStatistics to operate successfully, there has to be a databasenamed statrep.nsf on the selected server. Domino creates this database thefirst time it starts the REPORT server event.

AdminOpenUsersView

Opens an Address Book on the selected server and displays its People view.

Syntax@Command([AdminOpenUsersView])

UsageAdminOpenServerLog is available only when the Administration ControlPanel is open.

When there is only one Address Book on the selected server,AdminOpenUsersView opens it and displays its People view. When thereare multiple Address books on the selected server, Notes displays a dialogbox that allows you to select the Address Book to open.

408 Domino Designer Programming Guide, Volume 1: Formula Language

AdminOutgoingMail

Displays the contents of the selected server’s mail.box.

Syntax@Command([AdminOutgoingMail])

UsageAdminOutgoingMail is available only when the Administration ControlPanel is open.

AdminRegisterFromFile

Displays a series of dialog boxes for certifying multiple new users from atext file. The first dialog box asks if a license has been purchased for eachuser to be registered; the next asks for the location of the text file.

Syntax@Command([AdminRegisterFromFile])

UsageThis command works almost anywhere in Notes except from within adialog box.

AdminRegisterServer

Displays a series of dialog boxes for creating a new server ID. The firstdialog box asks if a license has been purchased for each server to beregistered.

Syntax@Command([AdminRegisterServer])

UsageThis command works anywhere in Notes except from within a dialog box.

Chapter 6: Formula Language @Commands A–Z 409

AdminRegisterUser

Displays a series of dialog boxes for certifying new users. The first dialogbox asks if a license has been purchased for each user to be registered.

Syntax@Command([AdminRegisterUser])

UsageThis can be used anywhere in Notes except from within a dialog box.

AdminRemoteConsole

Displays the Remote Server Console dialog box, where an administrator canenter server console commands from a workstation.

Syntax@Command([AdminRemoteConsole])

UsageThis command works anywhere in Notes except from within a dialog box.

AdminSendMailTrace

Displays the Mail Path Tracing dialog box, which allows you to send amessage to a location on the mail router and return a message.

Syntax@Command([AdminSendMailTrace])

UsageAdminSendMailTrace is available only when the Administration ControlPanel is open.

You use AdminSendMailTrace to determine the source of a mail deliveryfailure or to see if it is possible to deliver mail to a specific address.

410 Domino Designer Programming Guide, Volume 1: Formula Language

AdminStatisticsConfig

Opens the server events database (events4.nsf) on the selected server anddisplays its Servers to Monitor view.

Syntax@Command([AdminStatisticsConfig])

UsageAdminStatisticsConfig is available only when the Administration ControlPanel is open.

In order for AdminStatisticsConfig to operate successfully, there must be adatabase named events4.nsf on the selected server. Notes creates thisdatabase the first time it starts the EVENTS server task.

AdminTraceConnection

Displays the Trace Connections dialog box, which allows you to testnetwork connections through a passthru server.

Syntax@Command([AdminTraceConnection])

AgentEdit

Opens the Agent Builder for the currently selected agent.

Syntax@Command([AgentEdit])

UsageAn agent must be selected in the Agents view of a database.

Chapter 6: Formula Language @Commands A–Z 411

AgentEnableDisable

Enables or disables the specified agent.

Syntax@Command([AgentEnableDisable] ; agentName ; enableState )

ParametersagentName

Text. Optional. The name of a scheduled agent defined for the currentlyselected database. If you omit this parameter, AgentEnableDisableapplies to the currently selected agent.

enableState

Number (“1” or “0”). Optional. A value of “1” specifies that the agent isto be enabled. A value of “0” specifies that the agent is to be disabled. Ifyou omit this parameter, AgentEnableDisable changes the agent’scurrent state from enabled to disabled or from disabled to enabled.

UsageYou can omit both parameters when an Agents window has focus and ascheduled agent is selected. Otherwise, agentName is required.

AgentLog

Displays the log for the currently selected agent. The log containsinformation about when the agent last ran, what actions it performed, andwhen it finished running.

Syntax@Command([AgentLog])

UsageAn agent must be selected in the Agents view of a database. The agent musthave run at least once.

412 Domino Designer Programming Guide, Volume 1: Formula Language

AgentRun

Runs the currently selected agent and then displays its log.

Syntax@Command([AgentRun])

UsageAn agent must be selected in the Agents view of a database.

AgentSetServerName

Specifies a scheduled agent to run on a particular server.

Syntax@Command([AgentSetServerName] ; agentName ; serverName )

ParametersagentName

Text. The name of an existing scheduled agent in the selected database.

serverName

Text. Optional. The name of the server on which you want agentName torun. If you omit this parameter, Notes displays the Choose Server ToRun On dialog box when AgentSetServerName executes.

AgentTestRun

Displays a log for the currently selected agent, describing what actions theagent will perform when run.

Syntax@Command([AgentTestRun])

UsageAn agent must be selected in the Agents view of a database.

Chapter 6: Formula Language @Commands A–Z 413

AttachmentDetachAll

Displays the Save Attachments To dialog box, where you select a locationfor the current document’s attachments.

Syntax@Command([AttachmentDetachAll])

UsageA document must be open in Read or Edit mode

or

A form or subform must be open in Design mode

The document must have two or more attachments at least one of whichmust be selected.

AttachmentLaunch

Launches the selected attachment by opening the application in which itwas created, if possible.

Syntax@Command([AttachmentLaunch])

UsageA document must be open in Read or Edit mode

or

A form or subform must be open in Design mode

An attachment must be selected.

AttachmentProperties

Displays the Properties box for the current attachment.

Syntax@Command([AttachmentProperties])

414 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA document must be open in Read or Edit mode

or

A form or subform must be open in Design mode.

An attachment must be selected.

AttachmentViewLaunches the Attachment Viewer, which lets you view the contents of theselected attachment without opening the application in which it wascreated.

Syntax@Command([AttachmentView])

UsageA document must be open in Read or Edit mode

or

A form or subform must be open in Design mode

An attachment must be selected.

CalendarFormatChanges the Calendar view display to one of five options: One Day, TwoDays, One Week, Two Weeks, One Month.

Syntax@Command([CalendarFormat] ; number )

Parameternumber

Number. Optional. Specify a number that equates to the display, asshown below.

Use “1” to display the calendar as a One Day display. New withRelease 5.

Use “2” to display the calendar as a Two Day display.

Use “7” to display the calendar as a One Week display.

Use “14” to display the calendar as a Two Week display.

Use “30” to display the calendar as a One Month display.

Chapter 6: Formula Language @Commands A–Z 415

UsageWith no parameters, CalendarFormat cycles to the next calendardisplay option, in this order: One Day, Two Days, One Week, TwoWeeks, One Month. With parameters, CalendarFormat changes to thedesignated display.

A Calendar view must be open.

You can use this command with Web applications. On the Web, you canalso use “365” to switch to the one-year view.

CalendarGoToGoes to a particular date in a Calendar view.

Syntax@Command([CalendarGoTo] ; timedate )

Parametertime-date

Time-date. Optional. Enclose the desired date in square brackets, as in[12/09/96]. Any @functions that return a time-date value, such as@Now, @Today, @Yesterday, and @Tomorrow can also be used as thedate parameter.

UsageWith no parameters, CalendarGoTo displays the View Calendar GoTodialog box. With parameters, CalendarGoTo moves the view focus tothe requested date.

A Calendar view must be open.

You can use this command with Web applications.

ChooseFoldersDisplays the Folders dialog box, which allows you to select a folder inwhich to file the current document.

Syntax@Command([ChooseFolders])

UsageA document must be open in Edit mode.

416 Domino Designer Programming Guide, Volume 1: Formula Language

Compose

In a database you specify, creates a new, blank document using the formyou specify.

Syntax@Command([Compose] ; server : database ; form ; width : height)

Parametersserver : database

Text list. The name of the server and database where you want to createa document. Null for server means the local Notes directory.

form

Text. The name of the form you want to use when creating the new document.

width : height

Number list. Optional. The width and height, in inches, of the windowfor the document you compose. If you omit this parameter, or use zerofor either value, you create the window at the default size (usually thesize that the last user set).

To indicate the current database, use an empty string (“”) in place of theserver : database parameters.

UsageWhen @Command([Compose]) is used to compose a Response orResponse-to-Response document, make sure a database is open and adocument is already selected at the view level.

When the command is used to compose main documents, a database iconmust be selected, but the database itself does not have to be open. Thiscommand does not put a database icon on the desktop.

The width/height parameter does not apply in MDI mode when thewindow is maximized. When restored, the window returns to the size you specify. The measurement in inches matches the ruler bar in the editor,so that you can use the ruler bar to guide you in sizing the window. Whenyou specify the width and height, you center the window in the enclosingNotes window (for MDI mode) or in the operating desktop (for Mac andSDI mode).

You can use this command in Web applications, but you must specify theserver argument as a null string (“”), and omit the height argument.

Chapter 6: Formula Language @Commands A–Z 417

Examples: Compose1. The following formula composes a new MainTopic document in the

current database.@Command([Compose] ; ""; "MainTopic")

2. The following formula composes a new Client Information document inthe REPS database on the SALES server.@Command([Compose] ;"sales" : "reps.nsf"; "Client Information")

3. The following formula composes a mail memo in the user’s own Mail database.@Command([Compose] ; @MailDbName; "Memo")

4. The following formula composes a response document based on thecurrently selected document, in a window four inches wide and seveninches high.@Command([Compose] ;"";"Response"; 4:7)

CreateActionCreates a new action and opens the design pane, where you can edit the action.

Syntax@Command([CreateAction])

UsageA form or subform must be open in Design mode

or

A view or folder must be open in Design mode

CreateAgentCreates a new agent in the current database and opens the Agent Builder,where you can edit the agent.

Syntax@Command([CreateAgent])

418 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA database must be open or selected on the workspace. The user must haveat least Designer access to the database or have permission in the ACL tocreate personal agents.

CreateControlledAccessSectionCreates a controlled access section on a form or subform. Unlike a regularsection, a controlled access section has a formula to determine who can edit it.

Syntax@Command([CreateControlledAccessSection])

UsageA form or subform must be open in Design mode and the text you want inthe section must be selected.

CreateEllipseLets you create an ellipse in a navigator. After you invoke the command,the cursor changes to a crosshair when you start to drag the mouse in thedesign area. You create an ellipse by dragging the mouse until the ellipse isthe size you want.

Syntax@Command([CreateEllipse])

UsageA navigator must be open in Design mode.

CreateFolderDisplays the Create Folder dialog box, which lets you choose a location for anew folder and create it.

Syntax@Command([CreateFolder])

Chapter 6: Formula Language @Commands A–Z 419

UsageA database must be open or selected on the workspace, and the user musthave at least Designer access to the database, or have permission in the ACLto create personal folders.

CreateFormCreates a new, blank form in a database.

Syntax@Command([CreateForm])

UsageA database must be open or selected on the workspace, and the user musthave at least Designer access to the database.

CreateLayoutRegionCreates a new layout region in a form or subform.

Syntax@Command([CreateLayoutRegion])

UsageA form or subform must be open in Design mode.

CreateNavigatorCreates a new, blank navigator in a database.

Syntax@Command([CreateNavigator])

UsageA database must be open or selected on the workspace, and the user musthave at least designer access to the database.

420 Domino Designer Programming Guide, Volume 1: Formula Language

CreatePolygon

Lets you create a polygon in a navigator. After you invoke the command,the cursor changes to a crosshair when you start to drag the mouse in thedesign area. You create a polygon by clicking the mouse each time youwant to start a new side. Double-click when you are done.

Syntax@Command([CreatePolygon])

UsageA navigator must be open in Design mode.

CreatePolyline

Lets you create a polyline in a navigator. After you invoke the command,the cursor changes to a crosshair when you start to drag the mouse in thedesign area. You create a polyline by clicking the mouse each time youwant to start a new line. Double-click when you are done.

Syntax@Command([CreatePolyline])

UsageA navigator must be open in Design mode.

CreateRectangle

Lets you create a rectangle in a navigator. After you invoke the command,the cursor changes to a crosshair when you start to drag the mouse in thedesign area. You create a rectangle by dragging the mouse until therectangle is the size you want.

Syntax@Command([CreateRectangle])

UsageA navigator must be open in Design mode.

Chapter 6: Formula Language @Commands A–Z 421

CreateRectangularHotspot

Lets you create a rectanglar hotspot in a navigator. After you invoke thecommand, the cursor changes to a crosshair when you start to drag themouse in the design area. You create a rectangular hotspot by dragging themouse until the rectangle is the size you want.

Syntax@Command([CreateRectangularHotspot])

UsageA navigator must be open in Design mode.

CreateSection

Creates a section.

Syntax@Command([CreateSection])

UsageA document must be open in Edit mode

or

A form or subform must be open in Design mode

The text you want in the section must be selected.

CreateSubForm

Creates a new, blank subform in a database.

Syntax@Command([CreateSubForm])

UsageA database must be open or selected on the workspace, and the user musthave at least Designer access to the database.

422 Domino Designer Programming Guide, Volume 1: Formula Language

CreateTextbox

Lets you create a textbox in a navigator. After you invoke the command, thecursor changes to a crosshair when you start to drag the mouse in thedesign area. You create a textbox by dragging the mouse until the textbox isthe size you want.

Syntax@Command([CreateTextbox])

UsageA navigator must be open in Design mode.

CreateView

Displays the Create View dialog box, which lets you choose a location for anew view and create it.

Syntax@Command([CreateView])

UsageA database must be open or selected on the workspace, and the user musthave at least Designer access to the database.

DatabaseReplSettings

Displays the Replication Settings dialog box for the current database.

Syntax@Command([DatabaseReplSettings])

UsageA database must be open or selected on the workspace.

Chapter 6: Formula Language @Commands A–Z 423

DebugLotusScript

Puts Designer into debug mode, so that all LotusScript scripts run in the debugger. The command is a toggle; reselecting it takes Notes out ofdebug mode.

Syntax@Command([DebugLotusScript])

UsageThis command works almost anywhere in Notes except from within adialog box.

DesignDocumentInfo

Displays the Properties box for the current document.

Syntax@Command([DesignDocumentInfo])

UsageThe user must be at the view level with a document highlighted

or

A document must be open in read or Edit mode

If multiple documents have been selected, the Properties box displays forthe highlighted document.

DesignFormAttributes

Displays the Properties box for the current form, subform, or page.

Syntax@Command([DesignFormAttributes])

UsageA form, subform, or page must be open in Design mode. It’s mostconvenient to use SmartIcons to invoke this command.

424 Domino Designer Programming Guide, Volume 1: Formula Language

DesignFormFieldDefDisplays the Properties box for the currently selected field.

Syntax@Command([DesignFormFieldDef])

UsageA form or subform must be open in Design mode, and a field must beselected. It’s most convenient to use SmartIcons to invoke this command.

DesignFormNewFieldCreates a new field on a form or subform.

Syntax@Command([DesignFormNewField])

UsageA form or subform must be open in Design mode and there must be nofields selected. It’s most convenient to use SmartIcons to invoke thiscommand.

DesignFormsDisplays the Design - Forms view of the current database.

Syntax@Command([DesignForms])

UsageThe user must have at least Designer access to the database.

DesignFormShareFieldTurns a single-use field into a shared field.

Syntax@Command([DesignFormShareField])

UsageA form or subform must be open in Design mode and a field must beselected. It’s most convenient to use SmartIcons to invoke this command.

Chapter 6: Formula Language @Commands A–Z 425

DesignFormUseField

Displays the Insert Shared Field dialog box, where the user can select ashared field to place on the current form or subform.

Syntax@Command([DesignFormUseField])

UsageA form or subform must be open in Design mode and there must be no fields selected. It’s most convenient to use SmartIcons to invoke this command.

DesignFormWindowTitle

Displays the design pane and sets the Event edit control to Window Title, so you can define a formula for a form’s window title.

Syntax@Command([DesignFormWindowTitle])

UsageA form must be open in Design mode. It’s most convenient to useSmartIcons to invoke this command.

DesignHelpAboutDocument

Displays the About document in Edit mode for the current database.

Syntax@Command([DesignHelpAboutDocument])

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

426 Domino Designer Programming Guide, Volume 1: Formula Language

DesignHelpUsingDocument

Displays the Using document in Edit mode for the current database.

Syntax@Command([DesignHelpUsingDocument])

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

DesignIcon

Displays the Design Icon dialog box, where you can edit the currentlyselected database’s icon.

Syntax@Command([DesignIcon])

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

DesignMacros

Displays the Agents and Release 3 macros in the current database.

Syntax@Command([DesignMacros])

UsageA database must be open or selected on the workspace.

Chapter 6: Formula Language @Commands A–Z 427

DesignRefresh

Displays the Refresh Database Design dialog box, where the user canchoose a server that contains the current database’s design template.

Syntax@Command([DesignRefresh])

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

DesignReplace

Displays the Replace Database Design dialog box, where the user canchoose a design template to replace the current database’s design.

Syntax@Command([DesignReplace])

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

DesignSharedFields

Displays the Design - Shared Fields view in the current database.

Syntax@Command([DesignSharedFields])

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

428 Domino Designer Programming Guide, Volume 1: Formula Language

DesignSynopsis

Displays the Design Synopsis dialog box so the user can select the types ofinformation to be included in the synopsis.

Syntax@Command([DesignSynopsis])

DesignViewAppendColumnCreates a column in a view or folder, positioned after the last column.

Syntax@Command([DesignViewAppendColumn])

UsageA view or folder must be open in Design mode.

DesignViewAttributes

Displays the Properties box for the current view or folder.

Syntax@Command([DesignViewAttributes])

UsageA view or folder must be open in Design mode.

DesignViewColumnDef

Displays the Properties box for the currently selected column.

Syntax@Command([DesignViewColumnDef])

UsageA view or folder must be open in Design mode, and a column must be selected.

Chapter 6: Formula Language @Commands A–Z 429

DesignViewEditActions

Displays or hides the action pane.

Syntax@Command([DesignViewEditActions])

UsageA view or folder must be open in Design mode. If the action pane is visible,DesignViewEditActions hides it; and if the action pane is not visible,DesignViewEditActions displays it.

DesignViewFormFormula

Displays the Design Form Formula dialog box, where the user can define aformula that determines which form is used to display documents openedfrom a particular view or folder.

Syntax@Command([DesignViewFormFormula])

UsageA view or folder must be open in Design mode.

DesignViewNewColumn

Creates a new column before the currently selected column in a view or folder.

Syntax@Command([DesignViewNewColumn])

UsageA view or folder must be open in Design mode. It’s most convenient to useSmartIcons to invoke this command.

DesignViews

Displays the Design - Views view in the current database.

Syntax@Command([DesignViews])

430 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA database must be open or selected on the workspace and the user musthave at least Designer access to the database.

DesignViewSelectFormulaDisplays the design pane and sets the Define control to View Selection,which allows you to define a selection formula to determine whichdocuments are displayed in a view.

Syntax@Command([DesignViewSelectFormula])

UsageA view must be open in Design mode.

DialingRulesDisplays the Dialing Rules dialog box, which allows you to define dialingrules for a modem in a Location document in an Address Book.

Syntax@Command([DialingRules])

EditBottomMoves the insertion point to the bottom of a document or form.

Syntax@Command([EditBottom])

UsageIn a form in Design mode, EditBottom moves the insertion point to thebottom of the form as if the user had pressed CTRL+END.

In a document in Edit mode, EditBottom moves the insertion point tothe last editable field on the document.

In a document in Read mode, EditBottom has no effect.

Chapter 6: Formula Language @Commands A–Z 431

EditButton

Displays the design pane and the Properties box for the selected button.

Syntax@Command([EditButton])

UsageA document must be open in Edit mode and a button must be selected.

EditClear

Performs the menu command Edit - Clear.

Syntax@Command([EditClear])

UsageIn a view, folder, or a document in Read mode, marks the currentlyselected document for deletion.

In a document in Edit mode, deletes the highlighted data (text, tables,graphics, links, file attachments, or objects).

In a form, subform, view, or folder in Design mode, deletes thehighlighted data, fields, or columns.

On the workspace, removes the selected icon (without permanentlydeleting the database from disk).

It’s most convenient to use SmartIcons to invoke this command.

When you use this command with Web applications, it deletes the currentdocument. Use this command only on forms for the Web. It does not workin view actions.

EditCopyPerforms the menu command Edit - Copy.

Syntax@Command([EditCopy])

432 Domino Designer Programming Guide, Volume 1: Formula Language

UsageIn a view or folder, copies the selected documents to the Clipboard.

In a document in Read or Edit mode, copies the highlighted data to the Clipboard.

In a form, subform, view, or folder in Design mode, copies thehighlighted data, fields, or columns to the Clipboard.

You can use SmartIcons to invoke this command.

EditCutPerforms the menu command Edit - Cut.

Syntax@Command([EditCut])

UsageIn a view or folder, deletes the selected documents and places them onthe Clipboard.

In a document in Edit mode, deletes the highlighted data and places iton the Clipboard.

In a document in Read mode, EditCut has no effect.

In a form, subform, view, or folder in Design mode, deletes thehighlighted data, fields, or columns and places them on the Clipboard.

It is most convenient to use SmartIcons to invoke this command.

EditDeselectAllPerforms the menu command Edit - Deselect All.

Syntax@Command([EditDeselectAll])

UsageIn a view or folder, deselects all selected documents.

In a document in Read or Edit mode, deselects all highlighted data.

In a form, subform, view, or folder in Design mode, deselects allhighlighted data, fields, and columns.

On the workspace, deselects all selected databases.

Chapter 6: Formula Language @Commands A–Z 433

EditDetach

Detaches a file attachment to a location you specify.

Syntax@Command([EditDetach])

or

@Command([EditDetach] ; sourcefile ; targetfile )

Parameterssourcefile

Text. The name of the attachment you want to detach.

targetfile

Text. A path and file name indicating where you want to put the file.Include the complete path specification (appropriate to the user’soperating system).

UsageWith no parameters, displays the Save Attachment dialog box for thecurrent attachment. A document must be open in Read or Edit mode andthe attachment must be selected.

With both parameters, detaches the specified sourcefile and stores it usingthe targetfile path and file name without displaying the Save Attachmentdialog box. A document must be open in Read or Edit mode, but since youare specifying which attachment to detach, the attachment does not have tobe selected.

Examples: EditDetach1. This formula displays the Save Attachment dialog box.

@Command([EditDetach])

2. This formula detaches the 1-2-3 for Macintosh worksheet “Budget96”from the open document and stores it in the folder called “Worksheets”on “Macintosh HD,” the user’s Macintosh workstation.@Command([EditDetach] ;"BUDGET96";"Macintosh HD:Worksheets:Budget96")

434 Domino Designer Programming Guide, Volume 1: Formula Language

EditDocument

Places the current document into the mode you specify. If you don’t specifya mode, toggles between Read and Edit mode.

Syntax@Command([EditDocument])

or

@Command([EditDocument] ; mode; previewpane )

Parametermode

Number. Specify “1” to place the document in Edit mode or “0” toplace it in Read mode.

previewpane

Number. Specify “1” to edit the document in the preview pane.

UsageIn a view or folder, this @command opens the highlighted document in thespecified mode. If the mode is omitted, Edit mode is assumed.

When you use this command with Web applications, it edits the currentdocument. Use this command only on forms for the Web. It does not workin view actions.

When you edit a document using the @command([EditDocument]), thehidden attributes within rich-text fields are not honored. The hiddenattributes are honored when the document is opened in Read mode with@command([OpenDocument]).

Examples: EditDocument1. This formula opens the current document in Edit mode.

@Command([EditDocument] ; "1" )

2. This formula toggles the currently open document from Read mode to Edit mode, or vice versa. At the view level, opens the document inEdit mode.@Command([EditDocument])

3. This formula opens the current document into Edit mode in thepreview pane if you are viewing from the preview pane. This feature isused in Domino.Action.@Command([EditDocument] ; "1"; "1" )

Chapter 6: Formula Language @Commands A–Z 435

EditDown

Moves the insertion point in a document down by the number of lines you specify. If you don’t specify a number, moves the insertion point downone line.

Syntax@Command([EditDown])

or

@Command([EditDown] ; count )

Parametercount

Number. Optional. Specifies the number of lines to move down.

UsageIn a form or subform in Design mode, moves the insertion point downone line or count lines, as if the user had pressed DOWN.

In a document in Edit mode, moves the insertion point down within the current field, or if there are no more lines in the current field, in the next editable field (which must be below, not to the right of, thecurrent field).

In a document in Read mode, has no effect.

Example: EditDownThis formula moves the insertion point down five lines.

@Command([EditDown] ; "5" )

EditEncryptionKeysDisplays the Properties box for the current document, where you can editits encryption keys.

Syntax@Command([EditEncryptionKeys])

436 Domino Designer Programming Guide, Volume 1: Formula Language

UsageIn a view, the user can assign encryption keys to one or more selected documents.

In a document in Read or Edit mode, the user can assign encryptionkeys to the current document.

EditFindPerforms the menu command Edit - Find/Replace.

Syntax@Command([EditFind])

UsageIn a view, displays the Find dialog box, whether the database is full-textindexed or not.

In a document, displays the Find and Replace dialog box.

EditFindInPreviewPerforms the menu command Edit - Find/Replace without moving thefocus to the editing window. This allows searches to take place when thefocus is on the view or folder panes.

Syntax@Command([EditFindInPreview])

UsageWhen the preview pane is opened, displays the Find or Find/Replacedialog box (depending on whether the user is editing the document inthe preview pane or not).

When the preview pane is not opened, displays the Find dialog box(just as @Command([EditFind]) does).

Chapter 6: Formula Language @Commands A–Z 437

EditFindNext

Performs the menu command Edit - Find Next.

Syntax@Command([EditFindNext])

UsageThe following happens when EditFindNext operates on the result of a fulltext search:

In a view, highlights the next document that contains the search wordor phrase.

In an document, highlights the next occurrence of the search word or phrase.

When EditFindNext is not preceded by a full text search, Notes displays theFind dialog box.

EditGoToFieldIn a document in Edit mode, places the insertion point in a field you specify.

Syntax@Command([EditGotoField] ; fieldName )

ParameterfieldName

Text. The name of the field where you want to place the insertion point.The field must be editable.

UsageA document must be open in Edit mode.

438 Domino Designer Programming Guide, Volume 1: Formula Language

EditHeaderFooter

Displays the Properties box for the current document or form, which allowsyou to set headers, footers, and other print attributes.

Syntax@Command([EditHeaderFooter])

UsageA document must be selected from the view or opened in Read mode

or

A form or subform must be open in Design mode.

EditHorizScrollbar

Displays the horizontal scroll bar in a document.

Note EditHorizScrollbar is not supported under OS/2 and on theMacintosh.

Syntax@Command([EditHorizScrollbar])

UsageA document must be open.

EditIndentIndents a paragraph 1/4 inch. The entire paragraph is indented, as well as any paragraphs that are subsequently typed below it, until the userdisables indenting.

Syntax@Command([EditIndent])

UsageA form or subform must be open in Design mode

or

A document must be open in Edit mode, with the insertion point in arich text field.

Chapter 6: Formula Language @Commands A–Z 439

EditIndentFirstLine

Indents the first line of a paragraph 1/4 inch. The first line of the currentparagraph is indented, as well as first lines of subsequently typedparagraphs, until the user disables indenting. (A carriage return defines anew paragraph.)

Syntax@Command([EditIndentFirstLine])

UsageA form or subform must be open in Design mode

or

A document must be open in Edit mode, with the insertion point in arich text field.

EditInsertButton

Creates a new button and displays the design pane, where the user candefine a formula, simple action(s), LotusScript, or JavaScript for the button.

Syntax@Command([EditInsertButton])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form or subform must be open in Design mode, with nothingselected.

EditInsertFileAttachment

Attaches a file to a document.

Syntax@Command([EditInsertFileAttachment])

or

@Command([EditInsertFileAttachment] ; file ; compress )

440 Domino Designer Programming Guide, Volume 1: Formula Language

Parametersfile

Text. Optional. The name of the file you want to attach. Be sure toinclude the complete path specification (appropriate to the user’soperating system).

compress

Number. Optional. Specify “1” if you want to compress the attachment.Specify “0” if you do not.

Without a file parameter, displays the Create Attachment dialog box. If a fileis specified, attaches that file to the document without opening the CreateAttachment dialog box.

UsageA document must be open in Edit mode with the insertion point in a richtext field.

Examples: EditInsertFileAttachment1. This formula displays the Create Attachment dialog box.

@Command([EditInsertFileAttachment])

2. This formula attaches the 1-2-3 for Macintosh worksheet “Budget96”to the document.@Command([EditInsertFileAttachment] ;"Worksheets:Budget96" )

EditInsertObjectInserts an object into a document, form, or subform.

Note EditInsertObject is not supported by OS/2 and UNIX, or the Macintosh.

Syntax@Command([EditInsertObject])

or

@Command([EditInsertObject] ; object )

Chapter 6: Formula Language @Commands A–Z 441

Parameterobject

Text. Optional. The name of the object you want to insert.

If an object name is included, Notes assumes it represents a registered OLE object and will attempt to insert a copy of it into the document or form. If the object name is omitted, Notes displays the Insert Object dialog box.

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form or subform must be open in Design mode.

Example: EditInsertObjectThis formula inserts a Word Pro OLE object into the document or form.

@Command([EditInsertObject] ; "WordPro Document" )

EditInsertPageBreakInserts a forced page break into a document, form, subform, or page.

Syntax@Command([EditInsertPageBreak])

UsageA document must be open in Edit mode

or

A form, subform, or page must be open in Design mode.

EditInsertPopupCreates a hotspot that displays text.

Syntax@Command([EditInsertPopup])

442 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA document must be open in Edit mode with text selected in a rich text fieldorA form, subform, or page must be open in Design mode and text mustbe selected.

EditInsertTableDisplays the Create Table dialog box, where the user can specify thenumber of rows and columns in a new table.

Syntax@Command([EditInsertTable])

UsageA document must be open in Edit mode with the insertion point in arich text fieldorA form, subform, or page must be open in Design mode, with nothing selected.

EditInsertTextInserts the specified string at the current cursor position.

Syntax@Command([EditInsertText] ; string )

Parameterstring

Text. The string you want to insert.

UsageA document must be open in Edit mode with the insertion point in atext or rich text fieldorA form, subform, or page must be open in Design mode.

Example: EditInsertTextThis formula inserts the text “Jones, Casey M.” at the current position.

@Command([EditInsertText] ; "Jones, Casey M." )

Chapter 6: Formula Language @Commands A–Z 443

EditLeft

Moves the insertion point in a document, form, subform, or page to the leftby the number of spaces you specify. If you don’t specify a number, movesthe insertion point one space to the left.

Syntax@Command([EditLeft] ; count )

Parametercount

Number. Optional. The number of spaces you want to move.

UsageIn a form, subform, or page in Design mode, moves the insertion pointone or count spaces to the left, as if the user had pressed LEFT.

In a document in Edit mode, moves the insertion point one or countspaces to the left within the current field, or if there are no more spacesin the current field, in the previous editable field (which may be to theleft of, or above, the current field).

In a document in Read mode, has no effect.

Example: EditLeftThis formula moves the insertion point four spaces to the left.

@Command([EditLeft] ; "4" )

EditLinksDisplays the External Links dialog box.

Syntax@Command([EditLinks])

UsageA document must be open in Edit mode

or

A form or subform must be open in Design mode

The document, form, or subform must contain at least one DDE or OLE link.

444 Domino Designer Programming Guide, Volume 1: Formula Language

EditLocations

Opens the Personal Address Book to the Locations view.

Syntax@Command([EditLocations])

EditMakeDocLinkCreates a link to the current document and copies it to the Clipboard. Theuser can paste the link into any rich text field.

Syntax@Command([EditMakeDocLink])

UsageA document must be selected in a view

or

A document must be open in Read or Edit mode.

EditNextField

In a document in Edit mode, moves the insertion point to the next editablefield in the document, working left to right, top to bottom.

Syntax@Command([EditNextField])

UsageA document must be open in Edit mode.

EditOpenLink

Opens the selected link.

Syntax@Command([EditOpenLink])

Chapter 6: Formula Language @Commands A–Z 445

EditPaste

Performs the menu command Edit - Paste.

Syntax@Command([EditPaste])

UsageIn a view, pastes in documents that were cut or copied from anotherdatabase.

In a document in Edit mode or a form or subform in design mode,pastes the contents of the Clipboard into the document, form, orsubform. If the data was copied from a rich text field but is pasted intoa non-rich text field, some information may be lost.

In a document in Read mode, or if the Clipboard is empty, has no effect.

EditPasteSpecial

Displays the Paste Special dialog box.

Syntax@Command([EditPasteSpecial])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form or subform must be open in Design mode.

If the clipboard is empty, this command has no effect.

EditPhoneNumbers

Displays the Server/Connections view of the Personal Address Book.

Syntax@Command([EditPhoneNumbers])

446 Domino Designer Programming Guide, Volume 1: Formula Language

EditPrevField

In a document in Edit mode, moves the insertion point to the previouseditable field in the document, working right to left, bottom to top.

Syntax@Command([EditPrevField])

UsageA document must be open in Edit mode.

EditProfile

Opens a new or existing profile document in Edit mode.

Syntax@Command([EditProfile] ; formname; username )

Parametersformname

Text. The form upon which the profile is based. Must exist in thedatabase.

username

Text. Optional. The user name associated with the profile.

Usage

You can access profile documents quickly and use them to store informationthat you don’t want in user documents and to share information acrossscripts within a database.

Only one profile of a given form can exist per database per person. If youcreate a profile without a user name, Notes assumes it’s the only profiledocument of that form in the database. You need at least author access tocreate a profile that applies to an entire database.

Documents saved with EditProfile are hidden.

Chapter 6: Formula Language @Commands A–Z 447

Examples: EditProfile1. This formula opens Mary Tsen’s Interest Profile in a discussion

database.@Command([EditProfile];"Interest Profile";"Mary Tsen/Worksavers/US")

2. This formula creates a Calendar Profile document for the current useror opens the user’s existing Calendar Profile.@Command([EditProfile];"CalendarProfile";@UserName)

3. This formula creates a new Archive Profile document for the currentdatabase or opens the Archive Profile in Edit mode if it already exists.@Command([EditProfile];"Archive Profile")

4. This formula when used in the Public Address Book opens theServer\Setup Profile document.@Command([EditProfile];"Profile")

EditResizePictureDisplays the proportions of the selected graphic at the bottom of the screen.The user can size the picture by dragging the mouse in the appropriatedirection.

Syntax@Command([EditResizePicture])

UsageA document must be open in Edit mode and a graphic must be selected.

EditRightMoves the insertion point in a document to the right by the number ofspaces you specify. If you don’t specify a number, moves the insertion pointone space to the right.

Syntax@Command([EditRight] ; count )

448 Domino Designer Programming Guide, Volume 1: Formula Language

Parametercount

Number. Optional. The number of spaces you want to move.

UsageIn a form or subform in Design mode, EditRight moves the insertionpoint one or count spaces to the right, as if the user had pressed RIGHT.

In a document in Edit mode, EditRight moves the insertion point one orcount spaces to the right within the current field, or if there are no morespaces in the current field, in the next editable field (which may be tothe right of, or below, the current field).

In a document in Read mode, EditRight has no effect.

Examples: EditRightThis formula moves the insertion point three spaces to the right.

@Command([EditRight] ; “3” )

EditSelectAllPerforms the menu command Edit - Select All.

Syntax@Command([EditSelectAll])

UsageIn a view or folder, all documents are selected.

In a document in Read mode, all data on the document is selected,including field labels.

In a document in Edit mode, all data in the current field is selected.

In a form or subform, selects everything on the form or subform exceptlayout regions.

On the workspace, all databases on the current tab are selected.

In a view, folder, or navigator in Design mode, EditSelectAll is invalid.

Chapter 6: Formula Language @Commands A–Z 449

EditSelectByDate

Displays the Select by Date dialog box, where the user indicates whichdocuments should be selected in the view or folder, according to the datethey were created or last modified.

Syntax@Command([EditSelectByDate])

UsageA view or folder must be open.

EditShowHideHiddenChars

Toggles the display of the hidden characters (such as spaces, tabs, andcarriage returns) in a document, form, or subform.

Syntax@Command([EditShowHideHiddenChars] ; showOrHide )

ParametershowOrHide

Number. Optional. Specify “1” if you want to show hidden characters, “0” if you want to hide them. If you omit this parameter,EditShowHideHiddenChars toggles the current state of the hiddencharacters.

UsageA document must be open in Edit mode or a form or subform must be openin Design mode. Hidden characters are shown only in rich text fields.

EditTableDeleteRowColumn

Displays the Delete Row/Column dialog box, where the user can select thenumber of rows or columns to delete from the current table.

Syntax@Command([EditTableDeleteRowColumn])

450 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA document must be open in Edit mode

or

A form, subform, or page must be open in Design mode

The cursor must be in a table.

EditTableFormatDisplays the Properties box for the selected table.

Syntax@Command([EditTableFormat])

UsageA document must be open in Edit mode

or

A form, subform, or page must be open in Design mode

The cursor must be in a table.

EditTableInsertRowColumnDisplays the Insert Row/Column dialog box, where the user can select thenumber of rows or columns to insert into the table.

Syntax@Command([EditTableInsertRowColumn])

UsageA document must be open in Edit mode

or

A form, subform, or page must be open in Design mode

The insertion point must be in a table.

Chapter 6: Formula Language @Commands A–Z 451

EditTop

Moves the insertion point to the top of a document or form.

Syntax@Command([EditTop])

UsageIn a form in Design mode, EditTop moves the insertion point to the topof the form as if the user had pressed CTRL+HOME.

In a document in Edit mode, EditTop moves the insertion point to thefirst editable field on the document.

In a document in Read mode, EditTop has no effect.

EditUndo

Performs the menu command Edit - Undo, which undoes the previousreversible operation.

Syntax@Command([EditUndo])

UsageFor buttons and actions, Edit Undo works only when the user is at the viewlevel; use it to un-delete a document that is marked deleted.

EditUntruncate

Retrieves the full version of a truncated document.

Syntax@Command([EditUntruncate])

UsageIn a database which has undergone replication with the option to receiveonly summary (truncated) documents, EditUntruncate retrieves fullversions of the truncated documents that you select.

452 Domino Designer Programming Guide, Volume 1: Formula Language

EditUp

Moves the insertion point in a document up by the number of lines youspecify. If you don’t specify a number, moves the insertion point up one line.

Syntax@Command([EditUp] ; count )

Parametercount

Number. Optional. Specifies the number of lines to move up.

UsageIn a form in Design mode, moves the insertion point up one or countlines, as if the user had pressed UP.

In a document in Edit mode, moves the insertion point up one linewithin the current field, or if there are no more lines in the current field,in the previous editable field (which must be above, not to the right of,the current field).

In a document in Read mode, has no effect.

Example: EditUpThis formula moves the insertion point up two lines.

@Command([EditUp] ;"2" )

EmptyTrashDeletes documents marked for deletion in a Mail database and refreshes the view.

Syntax@Command([EmptyTrash])

The View applet is now programmable via this @Command. New withRelease 5.

Chapter 6: Formula Language @Commands A–Z 453

ExchangeUnreadMarks

For two selected database replicas, marks the documents as read in onereplica that are marked as read in the other.

Syntax@Command([ExchangeUnreadMarks])

UsageTwo database replicas must be selected whose icons are not stacked.

Execute

Launches an application.

Syntax@Command([Execute] ; application ; fileNames )

Parametersapplication

Text. A path and file name specifying the application you want to open.

fileNames

Text or text list. One or more paths and file names specifying the file(s)you want to open in the application. You can specify more than one file,as long as the application can open multiple files at launch time.

UsageSpecify the paths and file names using the appropriate format for theoperating system.

Examples: Execute1. This formula launches 1-2-3 for Windows.

@Command([Execute] ; "C:\\123W\\PROGRAMS\\123W.EXE" )

2. This formula launches 1-2-3 for Windows and loads the worksheetnamed SALES.WK4.@Command([Execute] ; "C:\\123W\\PROGRAMS\\123W.EXE";"C:\\123W\\WORK\\SALES.WK4" )

454 Domino Designer Programming Guide, Volume 1: Formula Language

FileCloseWindow

Closes the current Notes window. If the document or design element in that window has not been saved, Notes prompts the user to save it before closing.

Syntax@Command([FileCloseWindow])

UsageFileCloseWindow does not close the Notes workspace window.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

You can use this command with Web applications, as long as you enable the“Allow Javascript on the Web” setting on the Basics tab of the DatabaseProperties box. Precede this command with @Command[FileSave] tosimulate a Submit button.

FileDatabaseACL

Displays the access control list for the current database.

Syntax@Command([FileDatabaseACL])

UsageA database must be open or selected on the workspace. Although any userwith access greater than “No access” can view the ACL, only users withManager access can edit the ACL.

FileDatabaseCompactCompacts the white space in a database, and at the same time, converts theold database to the new format.

Syntax@Command([FileDatabaseCompact])

UsageA database must be open, or selected on the workspace. No access level isrequired to compact a database.

Chapter 6: Formula Language @Commands A–Z 455

FileDatabaseCopy

Displays the Copy Database dialog box, where the user can copy thecurrent database to a new location.

Syntax@Command([FileDatabaseCopy])

UsageA database must be open, or selected on the workspace. The user must haveat least Reader access to the database.

FileDatabaseDelete

Permanently deletes the current database file from the hard disk where it isstored.

Syntax@Command([FileDatabaseDelete])

UsageA database icon must be selected, but the database cannot be open. The usermust have Manager access in order to delete the database.

Note To remove the database icon from the user’s workspace withoutdeleting the database, use FileDatabaseRemove.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

FileDatabaseInfo

Displays the Properties box for the current database.

Syntax@Command([FileDatabaseInfo])

UsageA database must be open, or selected on the workspace. Any user with atleast Depositor access to the database can view the information.

456 Domino Designer Programming Guide, Volume 1: Formula Language

FileDatabaseRemove

Removes the current database icon from the workspace.

Syntax@Command([FileDatabaseRemove])

UsageThe database icon must be selected, but the database cannot be open.

Note To delete the database file from the hard disk where it’s stored, useFileDatabaseDelete.

FileDatabaseUseServer

Displays the Switch Servers dialog box, where the user can choose a serverthat contains a replica of the currently selected database.

Syntax@Command([FileDatabaseUseServer])

UsageThe command must be run from the workspace with a database selected.

FileExitPerforms the menu command File - Exit (File - Quit on the Macintosh),which closes Notes and all its open windows.

Syntax@Command([FileExit])

UsageThis can be used almost anywhere in Notes except from within a dialogbox. If an open document or design element has not been saved, Notesprompts the user to save it.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

Chapter 6: Formula Language @Commands A–Z 457

FileExport

Exports a Notes document or view.

Syntax@Command([FileExport])

or

@Command([FileExport] ; fileType ; fileName )

ParametersfileType

Text. The kind of file you want to export to. See list of file types, below.

fileName

Text. The name of the file you want to export to. Must be a completepath specification, including drive, directory, and file name.

If the fileType and fileName parameters are omitted, Notes displays theExport dialog box. If the parameters are included, Notes exports the view or currently opened document using the specified fileType and fileName.

UsageFileExport can be used at the view level, and when a document is open inRead or Edit mode, according to what is being exported.

The fileType must be one of those listed below. You do not have to spell thename exactly as shown; you have to include enough characters to uniquelyidentify the file type. In case of ambiguity, Notes will use the first file typein the list that matches your entry.

Windows and OS/2 File TypesDocument Level Ami ProANSI Metafile®ASCII TextMicrosoftWord RTFTIFF 5.0 ImageWord for Windows 6.0WordPerfect® 6.0/6.1

View LevelLotus 1-2-3 WorksheetStructured TextTabular Text

458 Domino Designer Programming Guide, Volume 1: Formula Language

Macintosh File TypesDocument Level ANSI MetafileASCII TextMicrosoftWord RTFTIFF 5.0 Image

Note The Macintosh does not support document level export of the XTNDfile format (MacWrite II and Text).

View LevelLotus 1-2-3 WorksheetStructured TextTabular Text

UNIX File TypesDocument Level Ami ProANSI MetafileASCII TextFrame® (MIF)Interleaf® ASCIIMicrosoftWord RTFTIFF 5.0 ImageWordPerfect 4.1WordPerfect 4.2WordPerfect 5.0WordPerfect 5.1

View LevelLotus 1-2-3 WorksheetStructured TextTabular Text

Examples: FileExport1. This formula exports a view to c:\temp.txt as tabular text.

@Command([FileExport]; "Tabular Text"; "c:\temp.txt")

2. This formula exports the current view to a 1-2-3 for Macintoshworksheet called Hardware and stores the file in the Lotus 1-2-3 folderon the user’s workstation.@Command([FileExport];"Lotus 1-2-3Worksheet";"SBRAUN:Lotus 1-2-3:Hardware")

Chapter 6: Formula Language @Commands A–Z 459

FileFullTextCreate

Displays the Full Text Create Index dialog box, where the user can specifysettings for the database’s full text index.

Syntax@Command([FileFullTextCreate])

UsageA database must be open, or selected on the workspace, and the user musthave at least Designer access.

FileFullTextDelete

Deletes a database’s full text index.

Syntax@Command([FileFullTextDelete])

UsageA database must be open or selected on the workspace, and must have afull text index already created. The user must have at least Designer accessto the database.

FileFullTextInfo

Displays the Full Text tab of the current database’s Properties box.

Syntax@Command([FileFullTextInfo])

UsageA database must be open, or selected on the workspace.

460 Domino Designer Programming Guide, Volume 1: Formula Language

FileFullTextUpdate

Updates full text indexes for local databases or queues the update requestfor server-based databases.

Syntax@Command([FileFullTextUpdate])

UsageA database must be open, or selected on the workspace.

FileImport

Imports a file into a Notes document or view.

Syntax@Command([FileImport] ; fileType ; fileName )

ParametersfileType

Text. The kind of file you want to import. See list of file types, below.

fileName

Text. The name of the file you want to import. Must be a complete pathspecification, including drive, directory, and file name.

If the fileType and fileName parameters are omitted, this displays the Importdialog box. If the parameters are included, Notes imports the specified fileinto the currently open document, or into a view.

UsageFileImport can be used at the view level, and when a document is open inEdit mode, according to what is being imported. If the document is beingedited, the insertion point must be in a rich text field.

The fileType must be one of those listed below. You do not have to spell thename exactly as shown; you have to include enough characters to uniquelyidentify the file type. In case of ambiguity, Notes will use the first file typein the list that matches your entry.

Chapter 6: Formula Language @Commands A–Z 461

Windows and OS/2 File TypesDocument Level Lotus 1-2-3 WorksheetAmi ProANSI MetafileASCII TextBinary with textBMP ImageExcel 4.0Excel 5.0GIF ImageJPEG ImageLotus PICMicrosoftWord RTFPCX ImageTIFF 5.0 ImageWordPerfect 6.0/6.1Word for Windows 6.0

View LevelLotus 1-2-3 WorksheetStructured TextTabular Text

Macintosh File TypesDocument LevelLotus 1-2-3 WorksheetANSI MetafileASCII TextMicrosoftWord RTFTIFF 5.0 Image

Note The Macintosh does not support document level import of the XTNDfile format (MacWrite II and Text).

View Level Lotus 1-2-3 WorksheetStructured TextTabular Text

UNIX File TypesDocument Level Lotus 1-2-3 WorksheetAmi ProANSI MetafileASCII TextFrame (MIF)

462 Domino Designer Programming Guide, Volume 1: Formula Language

Interleaf ASCIIMicrosoftWord RTFPCX ImageTIFF 5.0 ImageWordPerfect 4.1WordPerfect 4.2WordPerfect 5.0WordPerfect 5.1

View Level Lotus 1-2-3 WorksheetStructured TextTabular Text

Examples: FileImport1. This formula imports a GIF image from the Notes directory into the

current document.@Command([FileImport]; "GIF Image";"c:\\notes32\\sound.gif")

2. This formula imports a 1-2-3 for Macintosh worksheet calledHardware from the Lotus 1-2-3 folder on the user’s workstation intothe current view.@Command([FileImport]; "Lotus 1-2-3 Worksheet";"SBRAUN:Lotus 1-2-3:Hardware")

FileNewDatabaseDisplays the New Database dialog box, where the user can select a server,title, and file name for a new database.

Syntax@Command([FileNewDatabase])

FileNewReplicaDisplays the New Replica dialog box, where the user can create a replica ofthe current database.

Syntax@Command([FileNewReplica])

Chapter 6: Formula Language @Commands A–Z 463

FileOpenDatabase

Opens the specified database to the specified view, highlighting the firstdocument whose value in the sort column matches the key. You specify adatabase using its server and file name.

Syntax@Command([FileOpenDatabase] ; server : database ; viewName ; key ;newinstance ; temporary )

or

@Command([FileOpenDatabase] ; server : database ; navigator ; solo ;newinstance ; temporary )

Parametersserver

Text. The name of the server where the database resides.

database

Text. Optional. The path and file name (in the appropriate format forthe operating system) of the database you want to open. If you omit thename of the database, and one is already open, Notes displays thatdatabase’s view in the topmost, or current, window. If no database isopen but one is selected on the workspace, the selected database isopened. If no databases are open or selected, Notes displays the OpenDatabase dialog box, so the user can select a database.

viewName

Text. Optional. The name of the view you want to open in the database.If you omit the name of the view, the database opens to its default view;or, if the user has opened the database before, to the last view used bythat user.

key

Text. Optional. Indicates which document you want Notes to scroll towhen it opens viewName. The key is a value that appears in the firstsorted column of viewName. If you omit the key, no document isselected.

newinstance

Number. Optional. Specify “1” if you want the view to open in a newwindow, even if the database is already open in that view. If you omitthis parameter, the new window is opened only if the database isopened in a new view.

464 Domino Designer Programming Guide, Volume 1: Formula Language

temporary

Number. Optional. Specify “1” if you only want the database openedon a temporary basis for browsing, without adding the database to theuser’s workspace. If you omit this parameter, the database is added tothe user’s workspace.

navigator

Text. Optional. The name of a navigator defined for the database. Onopening the database, Notes displays this navigator.

solo

Number. Optional. A value of “1” instructs Notes to open the navigatornamed by navigator in its own window.

UsageIf you omit some of the parameters like viewName and key, but still includethe parameters that come after it, substitute “” for each parameter thatyou’re skipping, as in:

@Command([FileOpenDatabase]; "Sales":"problems.nsf"; ""; "";""; "1" )

You can use this command in Web applications, but the server argumentmust be specified as a null string (“”). When using the view argument, youmust follow the command with @Command [OpenDocument].

Examples: FileOpenDatabase1. Notes opens the problems.nsf database, which is stored on the

Development server. If the database is already open, Notes brings thatwindow to the foreground. If the database is not open, Notes opens it ina new window. Since no view was specified, the database opens eitherto the default view, or if the user has opened the database before, to theview last used by the user. If the database is not on the user’sworkspace, it will be added automatically.@Command(FileOpenDatabase];"Development":"problems.nsf")

2. Notes opens the problems.nsf database on the Development server.Additionally, Notes opens a new window, displays the Open ProblemReports view, and highlights the first document containing “Printerproblems” in the key field. Since the temporary parameter is used, thedatabase icon is not added to the user’s workspace.@Command([FileOpenDatabase]; "Development":"problems.nsf";"Open Problem Reports"; "Printer problems"; "1"; "1" )

Chapter 6: Formula Language @Commands A–Z 465

FileOpenDBRepID

Opens the specified database to the specified view, highlighting the firstdocument whose value in the sort column matches the key. You specify adatabase using its replica ID, and Notes searches the workspace and allservers available in the current session to find a replica.

Syntax@Command([FileOpenDBRepID] ; replicaID ; serverHint ; viewName ; key ;newInstance ; temporary )

or

@Command([FileOpenDBRepID] ; replicaID ; serverHint ; navigator ; solo;newInstance ; temporary )

ParametersreplicaID

Text. The replica ID of the database you want to open. You can see thereplica ID for a database in its InfoBox.

serverHint

Text. Optional. The name of a server where the database might reside.Notes checks this server for the replica before checking other serversonly if the database was not accessible from a workspace icon.

viewName

Text. Optional. The name of the view that you want to open in thedatabase. If you omit the name of the view, the database opens to itsdefault view, or if the user has opened the database before, to the lastview used by that person.

key

Text. Optional. Indicates which document you want Notes to scroll to when it opens viewName. The key is a value that appears in the first sorted column of viewName. If you omit the key, no document is selected.

newInstance

Number. Optional. Specify “1” if you want the view to always open in anew window, even if there’s already a window open for the database.Specify an empty string (“”) if you want the new window opened onlywhen it’s actually needed.

466 Domino Designer Programming Guide, Volume 1: Formula Language

temporary

Number. Optional. Specify “1” if you want the database opened on atemporary basis for browsing, without adding the database to the user’sworkspace. Specify an empty string (“”) if you want to add thedatabase to the user’s workspace.

navigator

Text. Optional. The name of a navigator defined for the database. Onopening the database, Notes displays this navigator.

solo

Number. Optional. A value of “1” instructs Notes to open the navigatornamed by navigator in its own window.

UsageFileOpenDBRepID is useful whenever you want to write a formula for usersworking on several different replicas of the same database. Libraries, forexample, use this command to open a database from the library.

FileOpenDBRepID looks for the replica in the following order:

Checks the user’s workspace

Checks the server indicated in the serverHint

Checks other servers known to the current Notes session

Example: FileOpenDBRepIDThis formula opens the first database that Notes finds with the replica ID85255F1E:004F2CEB, to the All by Category view.

@Command([FileOpenDBRepID] ; "85255F1E:004F2CEB"; ""; "All by Category" )

FilePageSetupDisplays the Page Setup dialog box (or, on the Macintosh, the File PrintMargins dialog box), which allows you to specify print settings for theselected database.

Syntax@Command([FilePageSetup])

UsageA database must be selected or open.

Chapter 6: Formula Language @Commands A–Z 467

FilePrint

Prints the currently open or selected document(s), or the current view.

Syntax@Command([FilePrint])

or

@Command([FilePrint] ; numCopies ; fromPage ; toPage ; ifDraft ; ifView ;formName ; breakType ; ifReset; startDate; endDate)

ParametersnumCopies

Text. Optional. The string must evaluate to a number, or be empty. The number of copies you want to print. Specify an empty string (“”) for one copy.

fromPage

Text. Optional. The string must evaluate to a number, or be empty. Thepage of a document where you want to start printing. Specify an emptystring (“”) if you want to print all pages.

toPage

Text. Optional. The string must evaluate to a number, or be empty. Thepage of a document where you want to stop printing. Specify an emptystring (“”) if you want to print all pages.

ifDraft

Text. Optional. Either the word “draft”, to Indicate that you want draftquality printing; or an empty string (“”), if you want regular qualityprinting.

ifView

Text. Optional. Either the word “printview”, to indicate that you wantto print the current view; or an empty string (“”), if you want to printthe selected document(s) in a view, not the view itself. This parameter isignored if you’re printing from an open document.

formName

Text. Optional. The name of the form you want to use to print thedocument. Specify an empty string (“”) if you want to print thedocument using its current form. This parameter is ignored if you’reprinting from an open document.

468 Domino Designer Programming Guide, Volume 1: Formula Language

breakType

Text. Optional. Either the word “pagebreak”, the word “line”, or anempty string (“”). If you’re printing multiple documents from a view,“pagebreak” indicates you want a page break between each document,“line” indicates you want a ruled line between each document, and anempty string indicates you want a blank line between each document.This parameter is ignored if you’re printing from an open document.

ifReset

Text. Optional. Either the word “resetpages”, or an empty string (“”). Ifyou’re printing multiple documents from a view, then “resetpages”specifies that page numbering begins at 1 with each new document; andan empty string (“”) specifies that page numbering begins at 1 with thefirst document and continues cumulatively. This parameter is ignored ifyou’re printing from an open document.

startDate

Time-date. Optional. Used with the printview parameter when printinga calendar view; indicates the first date to be printed. Specify an emptystring (“”) if you want to start printing with the earliest date in theview.

endDate

Time-date. Optional. Used with the printview parameter when printinga calendar view; indicates the last date to be printed. Specify an emptystring (“”) if you want to end printing with the last date in the view.

UsageWith no parameters, FilePrint displays the File Print dialog box (on theMacintosh, the chosen printer’s dialog box). With parameters, FilePrintprints the current document(s) or view without displaying the dialog box.

In Notes Release 3, FilePrint displays the File Print dialog box whether youuse parameters or not.

The Print method in NotesUIView class implements the@Command([FilePrint]).

Chapter 6: Formula Language @Commands A–Z 469

FilePrintSetup

Displays the Print Setup dialog box, which allows you to direct the currentview or document to a printer or a file that you specify.

Note [FilePrintSetup] is not supported on the Macintosh. To make setupchanges, use [FilePrint] ; to select different printers, use the Chooser.

Syntax@Command([FilePrintSetup])

UsageA database must be open to a view or to a document.

FileSave

Performs the menu command File - Save.

Syntax@Command([FileSave])

UsageA document must be open in Edit mode

or

A form, subform, view, folder, agent, or navigator must be open inDesign mode.

You can use this command with Web applications, as long as you enable the“Allow Javascript on the Web” setting on the Basics tab of the DatabaseProperties box. Follow this command with @Command[FileCloseWindow]to simulate a Submit button.

FileSaveNewVersionSaves a document as a new version.

Syntax@Command([FileSaveNewVersion])

UsageA document must be open in Edit mode.

470 Domino Designer Programming Guide, Volume 1: Formula Language

FindFreeTimeDialog

Opens the Free Time dialog box to allow searches for available meeting times.

Syntax

@Command([FindFreeTimeDialog] ; reqPeopleItems; optPeopleItems;reqRoomsItems; optRoomsItems; reqResourcesItems; optResourcesItems;removedPeopleItems; startDateTime; endDateTime)

Parameters

reqPeopleItems

Text or text list. Names of fields (items) in the current document thatcontain names of people required at the meeting.

optPeopleItems

Text or text list. Optional. Names of fields (items) in the currentdocument that contain names of people whose attendance is optional.

reqRoomsItems

Text or text list. Optional. Names of fields (items) in the currentdocument that contain names of rooms required for the meeting.

optRoomsItems

Text or text list. Optional. Names of fields (items) in the currentdocument that contain names of optional rooms.

reqResourcesItems

Text or text list. Optional. Names of fields (items) in the currentdocument that contain names of resources required for the meeting.

optResourcesItems

Text or text list. Optional. Names of fields (items) in the currentdocument that contain names of optional resources.

removedPeopleItems

Text or text list. Optional. Names of fields (items) in the currentdocument that contain names of people to remove from the attendance list.

startDateTime

Text. Name of a Time field (item) in the current document that containsthe start time for the meeting. You must specify the start date time.

Chapter 6: Formula Language @Commands A–Z 471

endDateTime

Text. Name of a Time field (item) in the current document that containsthe end time for the meeting. You must specify the end date time.

Usage

If you don’t need a parameter, use consecutive quotes (“”) to omit it.

The meeting time should not span midnight.

The user can adjust the values specified here through the dialog box.

Example: FindFreeTimeDialogThis @command opens the Free Time dialog box with required people fromthe From and SendTo fields in the current document, and times from theStartDateTime and EndDateTime fields.

@Command([ViewRefreshFields]);@Command([FindFreeTimeDialog]; "From" : "SendTo"; ""; ""; "";""; ""; ""; "StartDateTime"; "EndDateTime")

FolderMoves or copies the selected document to a folder.

Syntax@Command([Folder] ; folderName ; moveOrCopy )

ParametersfolderName

Text. Optional. The name of the folder to which you want to move orcopy the selected document. If you omit this parameter, Notes displaysthe Move to Folder dialog box, where you can choose a folder.

moveOrCopy

Number (“1” or “0”). Optional. A value of “1” moves the document tothe folder. A value of “0” copies the document to the folder. If you omitthis parameter, Folder assumes a value of “0” (copy).

If you include moveOrCopy with a value of “0” but omit folderName,Notes displays the Move to Folder dialog box with the Move buttondimmed. If you include moveOrCopy with a value of “1” but omitfolderName, Notes displays the Move to Folder dialog box with all of itsoptions available.

472 Domino Designer Programming Guide, Volume 1: Formula Language

UsageIf you don’t want to specify a folderName, but you want to specify amoveOrCopy, you will have to use a NULL string as shown below.

@Command([Folder] ;"";"1")

A saved document must be open or selected in a view.

Folder does not work for new documents. If multiple documents areselected in a view, they are all moved or copied to the folder.

@AddToFolder works just like @Command([Folder] ; Foldername;MoveOrCopy) except it can move a document from another folder.

FolderCollapseFor a folder or view containing nested folders or views, collapses theselected folder or view in the navigation pane.

Syntax@Command([FolderCollapse])

UsageA database must be open to a view or folder. Focus must be in thenavigation pane.

FolderCustomizeDisplays the design pane for the currently selected view or folder.

Syntax@Command([FolderCustomize])

UsageA database must be open to a view or folder.

Chapter 6: Formula Language @Commands A–Z 473

FolderExpand

Expands the currently selected view or folder one level in the navigation pane.

Syntax@Command([FolderExpand])

UsageA database must be open to a view or folder. Focus must be in thenavigation pane.

FolderExpandAll

Fully expands all views and folders in the navigation pane.

Syntax@Command([FolderExpandAll])

UsageA database must be open to a view or folder. Focus must be in thenavigation pane.

FolderExpandWithChildren

Fully expands the selected view or folder in the navigation pane.

Syntax@Command([FolderExpandWithChildren])

UsageA database must be open to a view or folder. Focus must be in thenavigation pane.

474 Domino Designer Programming Guide, Volume 1: Formula Language

FolderMove

Displays the Move dialog box for a view or folder, which allows you tomove the selected view or folder.

Syntax@Command([FolderMove])

UsageA database must be open to a view or folder.

FolderProperties

Displays the Properties box for a view or folder.

Syntax@Command([FolderProperties])

UsageA view or folder must be open in Design mode. Focus must be in thenavigation pane.

FolderRename

Displays the Rename dialog box, which allows you to rename the selectedfolder or view.

Syntax@Command([FolderRename])

UsageA database must be open to a view or folder.

Chapter 6: Formula Language @Commands A–Z 475

FormActions

Displays the actions pane for the current form, subform, or Page. Thecommand is a toggle; reselecting it hides the actions pane.

Syntax@Command([FormActions])

UsageA form, subform, or Page must be open in Design mode.

FormTestDocument

Creates a document using the current form or Page, so you can test itsfields, formulas, and scripts.

Syntax@Command([FormTestDocument])

UsageA form or Page must be open in Design mode. This command does notwork for subforms.

GoUpLevel

Displays the view containing the current document when the user closesthat document.

Syntax@Command([GoUpLevel])

UsageIf you open a document by activating a link, use GoUpLevel to display theview in which that document appears rather than close the database whenyou close the document.

Help

Opens online Help to the Index view.

Syntax@Command([Help])

476 Domino Designer Programming Guide, Volume 1: Formula Language

HelpAboutDatabase

Displays the About This Database or database policy document for thecurrent database (which typically explains the purpose of the application, aswell as its intended audience).

Syntax@Command([HelpAboutDatabase])

UsageThis can be used anywhere in Notes/Domino, provided a database is openor selected on the workspace.

HelpAboutNotes

Displays the Notes splash screen that appears when you launch Notes. Thescreen displays the current release number and date.

Syntax@Command([HelpAboutNotes])

HelpFunctions

Displays a list of Notes @functions so the user can select one and receivemore information about it.

Syntax@Command([HelpFunctions])

HelpIndexDisplays an index to the online Help database so the user can select a topicto read about (the index is ordered alphabetically; contrast this withHelpTableOfContents).

Syntax@Command([HelpIndex])

Chapter 6: Formula Language @Commands A–Z 477

HelpKeyboard

Displays keyboard equivalents for common tasks.

Syntax@Command([HelpKeyboard])

HelpMessagesDisplays the list of Notes messages so the user can select one and readabout it.

Syntax@Command([HelpMessages])

HelpRelease3MenuFinderDisplays the Release 3 Menu Finder, where you can choose a Notes Release 3 menu command and see the equivalent menu command for Notes Release 4.

Note This @command is not supported in Release 5.

Syntax@Command([HelpRelease3MenuFinder])

HelpReleaseNotesDisplays the release notes (information concerning changes appearing inthe latest release of Notes).

Syntax@Command([HelpReleaseNotes])

HelpTableOfContentsDisplays the Help database table of contents so the user can select a topic toread about. Topics are grouped by function (contrast this with HelpIndex).

Syntax@Command([HelpTableOfContents])

478 Domino Designer Programming Guide, Volume 1: Formula Language

HelpUsingDatabase

Displays the Using This Database, or database help document for thecurrent database (typically provides pointers on using the application’sforms and views).

Syntax@Command([HelpUsingDatabase])

UsageThis can be used anywhere in Notes/Domino, provided a database is openor selected on the workspace.

HotSpotClear

Removes a hotspot, without deleting the underlying text or graphic.

Syntax@Command([HotSpotClear])

UsageA document must be open in Edit mode

or

A form or subform must be open in Design mode.

This @command does not work on hotspots that are on a picture. It will only work on the hotspots that are created via the Create-Hotspotmenu item.

HotSpotProperties

Displays the Properties box for the current hotspot.

Syntax@Command([HotSpotProperties])

UsageA document must be open in Edit mode

or

A form or subform must be open in Design mode.

The cursor must be within a hotspot.

Chapter 6: Formula Language @Commands A–Z 479

InsertSubForm

Displays the Insert Subform dialog box, where you can select a subform tobe inserted in a form.

Syntax@Command([InsertSubForm])

UsageA form must be open in Design mode. There must be at least one subformin the database.

LayoutAddGraphic

Adds a graphic from the Clipboard to a layout region.

Syntax@Command([LayoutAddGraphic])

UsageA form or subform must be open in Design mode, a layout region must beselected, and the graphic you want to add must be on the Clipboard.

LayoutAddText

Creates a static text box in a layout region.

Syntax@Command([LayoutAddText])

UsageA form or subform must be open in Design mode and a layout region mustbe selected.

480 Domino Designer Programming Guide, Volume 1: Formula Language

LayoutElementBringToFront

Brings the selected layout element to the front, which means it displays ontop of any other layout elements that overlap it.

Syntax@Command([LayoutElementBringToFront])

UsageA form or subform must be open in Design mode, and an element within alayout region must be selected.

LayoutElementProperties

Displays the Properties box for the currently selected layout element.

Syntax@Command([LayoutElementProperties])

UsageA form or subform must be open in Design mode, and an element within alayout region must be selected.

LayoutElementSendToBack

Sends the selected layout element to the back, which means it displaysunderneath any other layout elements that overlap it.

Syntax@Command([LayoutElementSendToBack])

UsageA form or subform must be open in Design mode and an element within alayout region must be selected.

Chapter 6: Formula Language @Commands A–Z 481

LayoutProperties

Displays the Properties box for the currently selected layout region.

Syntax@Command([LayoutProperties])

UsageA form or subform must be open in Design mode and a layout region (or anelement within it) must be selected.

MailAddress

Displays the Mail Address window, where the user can select people andgroups to include in an address field of a mail document.

Syntax@Command([MailAddress])

UsageFor MailAddress to execute successfully, a mail document must be open inEdit mode, and the insertion point must be in an editable field.

MailComposeMemo

Creates and displays a blank mail document. Notes uses the default formfor the user’s mail database. This is a Memo document unless the user haschanged it.

Syntax@Command([MailComposeMemo])

UsageThis command can be used almost anywhere in Notes/Domino except fromwithin a dialog box.

482 Domino Designer Programming Guide, Volume 1: Formula Language

MailForward

Forwards the current document by placing its contents into a mail memo,which the user then addresses and sends like any other mail memo.

Syntax@Command([MailForward])

UsageA document must be open in Read or Edit mode, or selected in a view orfolder. If multiple documents are selected, the contents of each selecteddocument are placed into the mail memo.

MailForwardAsAttachment

In cc:Mail, forwards a Notes document as a cc:Mail attachment.

Syntax@Command([MailForwardAsAttachment])

MailOpen

Opens the user’s mail database to the view or navigator to which it wasmost recently open.

Syntax@Command([MailOpen])

MailRequestCrossCertDisplays the Choose ID to be Cross-Certified dialog box, which allows anadministrator to send a safe copy of a certifier ID to another administrator,who can certify it with a different certifier ID to create a cross certificate.

Syntax@Command([MailRequestCrossCert])

UsageThis can be used almost anywhere in Notes/Domino except from within a dialog box.

Chapter 6: Formula Language @Commands A–Z 483

MailRequestNewName

Displays the Change User Name dialog box, which allows the user to senda portion of the Notes user ID to a Notes administrator, who can change theuser name associated with the ID and return the ID to the user. The userthen merges the updated portion back into the existing user ID.

Syntax@Command([MailRequestNewName])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

MailRequestNewPublicKey

Displays the Mail New Public Key Request dialog box, which allows theuser to send a portion of his or her Notes ID to an administrator, who cancreate a new public key for the ID and return the ID to the user. The userthen merges the updated portion back into the existing user ID.

Syntax@Command([MailRequestNewPublicKey])

UsageThis can be used anywhere in Notes/Domino except from within a dialogbox. The user’s ID file must be certified by a hierarchical certifier.

MailScanUnread

Opens the user’s mail database to the first unread document in the view towhich the database was most recently open.

Syntax@Command([MailScanUnread])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

484 Domino Designer Programming Guide, Volume 1: Formula Language

MailSend

Displays the Mail Send dialog box, which lets the user choose whether ornot to encrypt, sign, or send the selected memo.

Syntax@Command([MailSend])

UsageA document must be open in read or edit mode, or selected in a view. Thedocument must contain a SendTo field, indicating the document’srecipients.

MailSendCertificateRequest

Displays the Mail Certificate Request dialog box. This lets the user send asafe copy of the Notes user ID to an administrator, who certifies and thenreturns it; the user then merges the updated safe copy back into the user ID.

Syntax@Command([MailSendCertificateRequest])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

MailSendEncryptionKey

Displays the User ID dialog box, where the user can define and sendencryption keys. If the user’s ID is password-protected, the user will be required to enter the password before being allowed access to the dialog box.

Syntax@Command([MailSendEncryptionKey])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

Chapter 6: Formula Language @Commands A–Z 485

MailSendPublicKey

Displays the Mail Public Key dialog box. This lets the user send the publickey to another user (typically to an administrator who can then paste thepublic key into that user’s Person record in the Public Address Book).

Syntax@Command([MailSendPublicKey])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

NavigateNext

Navigates to the next document in the current view or folder.

Syntax@Command([NavigateNext])

UsageA database must be open at the view or folder level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

For Web applications, use this command only for forms. It does not workfor view actions.

NavigateNextHighlightNavigates to the next full-text search highlight within a document, workingfrom left to right and top to bottom.

Syntax@Command([NavigateNextHighlight])

UsageA document must be open in Read or Edit mode.

486 Domino Designer Programming Guide, Volume 1: Formula Language

NavigateNextMain

Navigates to the next main document in the current view.

Syntax@Command([NavigateNextMain])

UsageA database must be open at the view or folder level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated, regardless of whether @Command or @PostedCommand is used.

For Web applications, use this command only for forms. It does not work for view actions.

NavigateNextSelected

Navigates to the next selected document in the current view or folder.

Syntax@Command([NavigateNextSelected])

UsageA database must be open at the view or folder level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

Chapter 6: Formula Language @Commands A–Z 487

NavigateNextUnread

Navigates to the next unread document in the current view or folder.

Syntax@Command([NavigateNextUnread])

UsageA database must be open at the view or folder level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated, regardless of whether @Command or @PostedCommand is used.

NavigatePrev

Navigates to the previous document in the current view or folder.

Syntax@Command([NavigatePrev])

UsageA database must be open at the view level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated, regardless of whether @Command or @PostedCommand is used.

For Web applications, use this command only for forms. It does not work for view actions.

488 Domino Designer Programming Guide, Volume 1: Formula Language

NavigatePrevHighlight

Navigates to the previous full-text search highlight within a document,working from right to left and bottom to top.

Syntax@Command([NavigatePrevHighlight])

UsageThe document must be open in Read or Edit mode and the highlight mustalready be moved past the first highlighted occurrence.

NavigatePrevMain

Navigates to the previous main document in the current view or folder.

Syntax@Command([NavigatePrevMain])

UsageA database must be open at the view or folder level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated, regardless of whether @Command or @PostedCommand is used.

For Web applications, use this command only for forms. It does not work for view actions.

Chapter 6: Formula Language @Commands A–Z 489

NavigatePrevSelected

Navigates to the previous selected document in the current view or folder.

Syntax@Command([NavigatePrevSelected])

UsageA database must be open at the view or folder level

or

A document can be open in Read or Edit mode

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

NavigatePrevUnread

Navigates to the previous unread document in the current view or folder.

Syntax@Command([NavigatePrevUnread])

UsageA database must be open at the view or folder level, or a document can beopen in Read or Edit mode.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

NavigateToBackLink

Returns to the document from which you launched the current document.

Syntax@Command([NavigateToBackLink])

UsageWhen you open a document, launch another document from it by activatinga link, and then close the second document, NavigateToBack link closes thedatabase containing the second document and returns to the first document.

490 Domino Designer Programming Guide, Volume 1: Formula Language

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

NavigatorPropertiesDisplays the Properties box for a navigator.

Syntax@Command([NavigatorProperties])

UsageA navigator must be open in Design mode.

NavigatorTestOpens a navigator in Testing mode, so you can test its hotspots, formulas,and scripts. Reselecting this command puts the navigator back into Design mode.

Syntax@Command([NavigatorTest])

UsageA navigator must be open in Design mode.

ObjectDisplayAsDisplays the Display As dialog box, which lets you change the displaysettings of the selected OLE object.

Note ObjectDisplayAs is not supported under OS/2 or UNIX, or on theMacintosh.

Syntax@Command([ObjectDisplayAs])

UsageAn OLE object must be selected.

Chapter 6: Formula Language @Commands A–Z 491

ObjectOpen

Opens an OLE object for editing.

Note ObjectOpen is not supported under OS/2 or UNIX, or on the Macintosh.

Syntax@Command([ObjectOpen])

UsageAn OLE object must be selected.

ObjectProperties

Displays the Propreties box for the selected OLE object.

Syntax@Command([ObjectProperties])

OpenCalendar

Opens a mail file to the Calendar view.

Syntax@Command([OpenCalendar] ; username )

Parameterusername

Text. Optional. User name of the owner of the mail file.

UsageIf you specify username, this command opens the mail file of that user. Ifyou omit username, this command displays the name picker dialog, thenopens the mail file of the selected user. This command temporarily adds theicon for the mail database to the workspace.

492 Domino Designer Programming Guide, Volume 1: Formula Language

OpenDocument

Opens a document.

Syntax@Command([OpenDocument] ; writeOrReadOnly ; UNID ; width : height)

ParameterswriteOrReadOnly

Text (“1” or “0”). Optional. A value of “1” opens the document in Edit mode. A value of “0” (the default) opens the document inRead-only mode.

UNID

Text. Optional. The UNID (unique document ID) of the document youwant to open. If you omit this parameter, Notes opens the currentlyselected document.

width : height

Number list. Optional. The width and height, in inches, of the windowfor the document you open. If you omit this parameter or use zero foreither value, you create the window at the default size (usually the sizethat the last user set).

UsageA database must be open to a document view and the view must containthe document you want to open.

The width-height parameter does not apply in MDI mode when thewindow is maximized. When restored, the window returns to the size youspecify. The measurement in inches matches the ruler bar in the editor, soyou can use the ruler bar to guide you in sizing the window. When youspecify the width and height, you center the window in the enclosing Notes window (for MDI mode) or in the operating desktop (for Mac andSDI mode).

Chapter 6: Formula Language @Commands A–Z 493

OpenFrameset

Opens a frameset defined for the current database. Framesets provide away for designers to display several pages at the same time. A frame isactually one page; a frameset is a collection of pages. Page designers cancreate links between frames. A major advantage of framesets is the ability toleave one page constant as users scroll or link to other pages. This functionsupports the OpenFrameSet method in NotesUIWorkspace.

Note This @Command is new with Release 5.

Syntax@Command([OpenFrameset] ; frameset )

Parametersframeset

Text. The name of a frameset defined for the current database.

Usage@Command([OpenFrameset]) is used in action formulas. You can use thiscommand in Web applications.

OpenHelpDocument

Allows application developers to provide their own help documents thatusers can access by pressing a help button or a key such as <F1>. Thiscommand searches the specified view of the named database for the keyvalue and if found, displays the document in the Help window. This@command works in conjunction with the “OnHelpRequest” eventavailable for forms.

Note This @Command is new with Release 5.

Syntax@Command([OpenHelpDocument] ; server : database; viewname; key)

or

@Command([OpenHelpDocument] ; [ClientHelp] ; viewname; key)

or

@Command([OpenHelpDocument] ; [DesignerHelp] ; viewname; key)

or

@Command([OpenHelpDocument] ; [AdminHelp] ; viewname; key)

494 Domino Designer Programming Guide, Volume 1: Formula Language

Parametersserver

Text. The name of the server where the database resides.

database

Text. Required. The path and file name (in the appropriate format forthe operating system) of the database you want to open.

viewName

Text. The name of the view you want to open in the database.

key

Text. Indicates which document you want Notes to scroll to when itopens viewName. The key is a value that appears in the first sortedcolumn of viewName. It can either be a formula or a hard-coded valuesuch as the title of a document.

UsageIn the Help database, the column that contains the data must be sorted.

The Help database must be on either a server or in the local data directory. If you do not specify the server name, it defaults to your local data directory.

If you do not specify the database name, it searches within the Helpdatabase. For example, in the Notes Client, the search occurs in Notes Client Help (help5_client.nsf).

For Web access, this command is useful to create a button to get Helpdocuments.

Tip You can also create pages for Help and open them with@Command([OpenPage]).

OpenNavigatorOpens a navigator defined for the selected database.

Syntax@Command([OpenNavigator] ; navigator ; solo )

Parametersnavigator

Text. The name of a navigator defined for the selected database.OpenNavigator opens this navigator in an existing navigation pane or window.

Chapter 6: Formula Language @Commands A–Z 495

solo

Number (“1”). Optional. If you include this value, Notes opens thespecified navigator in its own window.

UsageOpenNavigator opens this specified navigator in an existing navigationpane or window.

You can use this command in Web applications but you must omit the solo argument.

OpenPageOpens a page defined for the current database. A page is a design elementthat structures and displays information, including text, graphics, applets,and links. Unlike a form, a page cannot contain fields, subforms, layoutregions, and some embedded controls. This function supports theOpenPage method in NotesUIWorkspace.

Note This @Command is new with Release 5.

Syntax@Command([OpenPage] ; page )

Parameterspage

Text. The name of a page defined for the current database.

Usage@Command([OpenPage]) is used in action formulas. You can use thiscommand in Web applications.

OpenViewOpens the specified view in the current database.

Syntax@Command([OpenView] ; viewName ; key ; newinstance )

ParametersviewName

Text. Optional. The name of the view you want to open. If you omit theview name, the database opens to its default view; or, if the user has

496 Domino Designer Programming Guide, Volume 1: Formula Language

opened the database before, to the last view used by that person. If thedatabase is already open to the specified view, Notes makes that thetopmost window.

key

Text. Optional. Indicates which document you want Notes to scroll to when it opens viewName. The key is a value that appears in the first sorted column of viewName. If you omit the key, no document is selected.

newinstance

Number. Optional. Specify “1” if you want the view to open in a newwindow, even if there’s already a window open for the database. If you omit this parameter, the new window is opened only when it’sactually needed.

Note The view must be sorted in order for the key to work; otherwise, nodocument is selected when the view opens. The key column must be thefirst sorted column when multiple sorted columns are present.

UsageYou can use this command in Web applications.

If you specify the newinstance parameter for @Command([OpenView]), the@SetTargetFrame function is ignored.

If you do not specify a viewName then the last view is the one that will openin the specified targetframe of @SetTargetFrame.

Example: OpenViewThis formula opens the Reverse Chronology view for the current database.

@Command([OpenView] ; "Reverse Chronology")

PasteBitmapAsBackgroundPastes a bitmap into the background of a navigator. All other objects in thenavigator are displayed on top of the background bitmap.

Syntax@Command([PasteBitmapAsBackground])

UsageA navigator must be open in Design mode, and the bitmap you want topaste must be on the Clipboard.

Chapter 6: Formula Language @Commands A–Z 497

PasteBitmapAsObject

Pastes a bitmap into a navigator. The bitmap becomes a hotspot which canbe edited like any other hotspot.

Syntax@Command([PasteBitmapAsObject])

UsageA navigator must be open in Design mode, and the bitmap you want topaste must be on the Clipboard.

PicturePropertiesDisplays the Properties box for a bitmap in a rich text field.

Syntax@Command([PictureProperties])

UsageA bitmap must be selected.

PublishDatabaseDisplays the Publish Database dialog box, where the user selects a library inwhich to publish the selected database.

Syntax@Command([PublishDatabase])

UsageA database must be open or selected on the workspace. Only one databasecan be selected. There must be at least one library on the user’s workspace.

RefreshHideFormulasRefreshes only the hidden formulas in a document or view.

Syntax@Command([RefreshHideFormulas])

UsageA document or view must be open.

498 Domino Designer Programming Guide, Volume 1: Formula Language

RefreshParentNote

This formula sends the values entered in the dialog box to the parentdocument. A designer can update a parent note and close the dialog boxwithout having to use the OK button on the dialog box.

Syntax@Command([RefreshParentNote])

UsageUsed only in dialog boxes. This function is supported by theRefreshParentNote method in NotesUIworkspace.

RemoveFromFolder

Removes the selected document from the current folder.

Syntax@Command([RemoveFromFolder])

UsageA document must be selected in a folder or opened from a folder (not aview). If several documents are selected, they are all removed from thefolder.

RenameDatabase

For a particular database on the user’s workspace, RenameDatabase locatesa replica of that database (based on its replica ID) on the specified server,and replaces the database icon with that of the replica. The only change theuser sees is that the server name has changed on the database icon.

Syntax@Command([RenameDatabase] ; server : database ; newServer )

Parametersserver

Text. The name of the server where the database is.

database

Text. The path and file name of the database. Specify the database’sname and location using the appropriate format for the operatingsystem.

Chapter 6: Formula Language @Commands A–Z 499

newServer

Text. The name of the server where a replica of the database is.

UsageYou can only use this for replicas of a database, not copies. You cannot usethis command to change the name of a server.

If the workspace has stacked replica icons for the database on both serverand newServer, RenameDatabase brings the icon for newServer to the front.

Examples: RenameDatabase1. This formula replaces the database icon pointing to the Statusrp.nsf

database on the CENTRAL server to that on the WEST server. To theuser, the only change is that the database icon now displays WEST asthe server name.@Command([RenameDatabase]; "CENTRAL" : "Statusrp.nsf";"WEST")

2. This formula brings the database icon pointing to the WEST server tothe front, if the workspace already has stacked icons for Statusrp.nsf onboth CENTRAL and WEST. The icon pointing to the CENTRAL serveris stacked underneath.@Command([RenameDatabase]; "CENTRAL" : "Statusrp.nsf";"WEST")

ReplicatorDisplays the Replicator on the Notes workspace page.

Syntax@Command([Replicator])

ReplicatorReplicateHighInitiates replication of databases that have been assigned a priority of High.

Syntax@Command([ReplicatorReplicateHigh])

UsageReplicatorReplicateHigh is available only when Notes is open to theReplicator workspace page.

500 Domino Designer Programming Guide, Volume 1: Formula Language

ReplicatorReplicateNext

Stops replication of the currently replicating database and initiatesreplication of the next database selected for replication.

Syntax@Command([ReplicatorReplicateNext])

UsageReplicatorReplicateNext is available only when Notes is open to theReplicator workspace page.

Note ReplicatorReplicateNext may result in partial replication of thecurrently replicating database.

ReplicatorReplicateSelected

Initiates replication of the selected database.

Syntax@Command([ReplicatorReplicateSelected])

UsageReplicatorReplicateSelected is available only when Notes is open to theReplicator workspace page.

ReplicatorReplicateWithServerDisplays the Replicate With Which Server dialog box, and then initiatesreplication with the server you select.

Syntax@Command([ReplicatorReplicateWithServer])

UsageReplicatorReplicateWithServer is available only when Notes is open to theReplicator workspace page.

Chapter 6: Formula Language @Commands A–Z 501

ReplicatorSendMail

Sends local pending mail to the server.

Syntax@Command([ReplicatorSendMail])

UsageReplicatorSendMail is available only when Notes is open to the Replicatorworkspace page.

ReplicatorSendReceiveMail

Initiates replication between the mail server and your local mail database.

Syntax@Command([ReplicatorSendReceiveMail])

UsageReplicatorSendReceiveMail is available only when Notes is open to theReplicator workspace page.

ReplicatorStart

Initiates or resumes replication of the selected databases.

Syntax@Command([ReplicatorStart])

UsageReplicatorStart is available only when Notes is open to the Replicatorworkspace page.

ReplicatorStop

Stops the current replication process.

Syntax@Command([ReplicatorStop])

502 Domino Designer Programming Guide, Volume 1: Formula Language

UsageReplicatorStop is available only when Notes is open to the Replicatorworkspace page.

Note ReplicatorStop may result in partial replication of the currentlyreplicating database.

SectionCollapseCollapses the current section on a document, form, or subform.

Syntax@Command([SectionCollapse])

UsageA document must be open in Read or Edit mode and a section must be selected.

A form or subform must be open in Design mode and a section must be selected.

SectionCollapseAllCollapses all the sections on a document, form, or subform.

Syntax@Command([SectionCollapseAll])

UsageA document must be open in Read or Edit mode.

A form or subform must be open in Design mode.

SectionDefineEditorsDisplays the Edit Section dialog box for the current section on a form.

Syntax@Command([SectionDefineEditors])

UsageThe current section must be a controlled access section and the form mustbe open in Edit mode.

Chapter 6: Formula Language @Commands A–Z 503

SectionExpand

Expands the current section on a document, form, or subform.

Syntax@Command([SectionExpand])

UsageA document must be open in Read or Edit mode and a section must be selected.

A form or subform must be open in Design mode and a section must be selected.

SectionExpandAllExpands all the sections on a document, form, or subform.

Syntax@Command([SectionExpandAll])

UsageA document must be open in Read or Edit mode.

A form or subform must be open in Design mode.

SectionPropertiesIn a form or subform, displays the Properties box for the selected section.

Syntax@Command([SectionProperties])

UsageA form or subform must be open in Design mode and a section must beselected. SectionProperties does not work for sections on documentsbased on that form or subform.

A document must be open in Edit mode and a section in a rich text fieldmust be selected.

504 Domino Designer Programming Guide, Volume 1: Formula Language

SectionRemoveHeader

Removes the contents of a section from the section. The contents are thendisplayed as they existed before the section was created.

Syntax@Command([SectionRemoveHeader])

UsageA document must be open in Edit mode with a section selected

or

A form or subform must be open in Design mode with a section selected

SetCurrentLocation

Displays the Choose Location dialog box, where you can choose yourcurrent workstation location, such as Office, Island, or Travel.

Syntax@Command([SetCurrentLocation])

UsageThis command works everywhere in Notes. It’s most convenient to useSmartIcons to invoke this command.

ShowHideLinkPreview

Toggles the display of the link preview pane.

Syntax@Command([ShowHideLinkPreview] ; showOrHide )

ParametershowOrHide

Number. Optional. Specify “1” if you want to show the link previewpane, “0” if you want to hide it. If you omit this parameter, the@command toggles the current state of the link preview pane.

UsageA document must be open in Read or Edit mode.

Chapter 6: Formula Language @Commands A–Z 505

ShowHideParentPreview

Toggles the display of the parent document preview pane.

Syntax@Command([ShowHideParentPreview] ; showOrHide )

ParametershowOrHide

Number. Optional. Specify “1” if you want to show the parent previewpane, “0” if you want to hide it. If you omit this parameter, the@command toggles the current state of the parent preview pane.

UsageA document must be open in Read or Edit mode.

ShowHidePreviewPaneToggles the display of the document preview pane.

Syntax@Command([ShowHidePreviewPane] ; showOrHide )

ParametershowOrHide

Number. Optional. Specify “1” if you want to show the documentpreview pane, “0” if you want to hide it. If you omit this parameter, the@command toggles the current state of the document preview pane.

UsageA document must be selected in a view or folder.

ShowPropertiesDisplays the Properties box for the currently selected Notes object. Forexample, if a document is selected in a view, displays the documentProperties box; if a field is selected on a form, displays the field Properties box.

Syntax@Command([ShowProperties])

506 Domino Designer Programming Guide, Volume 1: Formula Language

SmartIconsFloating

Makes the SmartIcons palette “floating” so the user can move it around onthe screen.

Syntax@Command([SmartIconsFloating])

SmartIconsNextSetSwitches to the next set of SmartIcons.

Syntax@Command([SmartIconsNextSet])

StyleCycleKeyCycles through the list of styles that have been defined for the currentdocument, form, or page. This is the same as pressing F11. Each time youinvoke StyleCycleKey, a different style goes into effect.

Syntax@Command([StyleCycleKey])

UsageA document must be open in Edit mode

or

A form, subform, or page must be open in Design mode

In both cases, there must be at least two styles assigned to the style cycle list.

Chapter 6: Formula Language @Commands A–Z 507

TextAlignCenter

Centers the current text.

Syntax@Command([TextAlignCenter])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

TextAlignFull

Aligns the text at both the right and left edges of the field so that the textforms a block.

Syntax@Command([TextAlignFull])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

TextAlignLeft

Aligns text along the left margin.

Syntax@Command([TextAlignLeft])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

508 Domino Designer Programming Guide, Volume 1: Formula Language

TextAlignNone

Reverses the previously specified alignment settings.

Syntax@Command([TextAlignNone])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

TextAlignRight

Aligns text along the right margin.

Syntax@Command([TextAlignRight])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

TextBold

Makes the selected and subsequently entered text bold. This command is atoggle; reselecting it removes the bold.

Syntax@Command([TextBold])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode

or

Chapter 6: Formula Language @Commands A–Z 509

A textbox must be selected in a navigator, with all the text in thetextbox becoming bold

or

A textbox must be selected in a layout region on a form, with all of thetext in the textbox becoming bold

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextBullet

Applies the bullet attribute to selected and subsequently entered text.

Syntax@Command([TextBullet] ; onOff )

ParameteronOff

Number. Optional. Specify “1” to turn the bullet attribute on; specify“0” to turn it off. If you omit this parameter, the command toggles fromthe current state.

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextCycleSpacingResets the interline spacing below the selected text to single, one and a half,or double.

Syntax@Command([TextCycleSpacing])

UsageText must be selected in a rich text field in a document open in Edit modeor in a form or Page open in Design mode. TextCycleSpacing acts as athree-way toggle that sets the spacing below each line of selected text from

510 Domino Designer Programming Guide, Volume 1: Formula Language

single to one and a half, or from one and a half to double, or from double tosingle. If interline spacing in the selected text is not uniform,TextCycleSpacing sets it to single.

Some text must be selected in a rich text field in a document open in Editmode or a form open in Design mode.

TextEnlargeFont

Increases selected and subsequently entered text to the next larger point size.

Syntax@Command([TextEnlargeFont])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextFont

Displays the Properties box for the current text, where the user can selectthe typeface, size, color, and style attributes.

Syntax@Command([TextFont])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

Chapter 6: Formula Language @Commands A–Z 511

TextItalic

Italicizes the selected (and subsequently entered) text. This command is atoggle; reselecting it removes the italics.

Syntax@Command([TextItalic])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode

or

A textbox must be selected in a navigator, with all the text in thetextbox becoming italics

or

A textbox must be selected in a layout region on a form, with all the textin the textbox becoming italics

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextNormal

Removes all style attributes from selected and subsequently entered text.

Syntax@Command([TextNormal])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode

or

A textbox must be selected in a navigator, with all the text in thetextbox going back to plain text

or

A textbox must be selected in a layout region on a form, with all the textin the textbox going back to plain text.

512 Domino Designer Programming Guide, Volume 1: Formula Language

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextNumbers

Applies the numbers attribute to selected and subsequently entered text.

Syntax@Command([TextNumbers] ; onOff )

ParameteronOff

Number. Optional. Specify “1” to turn the numbers attribute on; specify“0” to turn it off. If you omit this parameter, the command toggles fromthe current state.

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextOutdentOutdents selected and subsequently entered text by narrowing its leftmargin.

Syntax@Command([TextOutdent])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

Chapter 6: Formula Language @Commands A–Z 513

TextParagraph

Displays the Paragraph Alignment panel of the Text Properties box.

Syntax@Command([TextParagraph])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

You can use SmartIcons to invoke this command if the text is already selected.

TextParagraphStyles

Displays the Paragraph Styles panel of the Text Properties box.

Syntax@Command([TextParagraphStyles])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

You can use SmartIcons to invoke this command if the text is already selected.

TextPermanentPen

Toggles the permanent pen.

Syntax@Command([TextPermanentPen] ; onOff )

ParameteronOff

Number. Specify “1” to turn permanent pen on; specify “0” to turn it off. Omit this parameter to toggle the permanent pen.

514 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

You can use SmartIcons to invoke this command if the text is already selected.

TextReduceFontDecreases the selected text to the next smaller point size.

Syntax@Command([TextReduceFont])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

TextSetFontColorDisplays text using the specified color.

Syntax@Command([TextSetFontColor] ; [ color ])

Parameter[ color ]

The name of the color you want your text to be. The available colors are:

Black Gray

Red DarkRed

Green DarkGreen

continued

Chapter 6: Formula Language @Commands A–Z 515

Blue DarkBlue

Magenta DarkMagenta

Yellow Brown

Cyan DarkCyan

White

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It is most convenient to use SmartIcons to invoke this command if the text isalready selected.

Example: TextSetFontColorThis formula sets the text color to dark cyan.

@Command([TextSetFontColor] ; [DarkCyan])

TextSetFontFace

Displays text using the specified typeface. It’s most convenient to useSmartIcons to invoke this command if the text is already selected.

Syntax@Command([TextSetFontFace] ; typeface )

Parametertypeface

Text. The name of the font you want. The list of available typefacesdepends upon the platform you are using, and whether you are usingany add-in typeface software.

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

516 Domino Designer Programming Guide, Volume 1: Formula Language

Example: TextSetFontFaceThis formula sets the font to Courier.

@Command([TextSetFontFace] ; "Courier")

TextSetFontSizeDisplays text using the specified point size.

Syntax@Command([TextSetFontSize] ; size )

Parametersize

Text. The font size you want. If you specify a nonexistent size, Notesuses the closest match.

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode.

It is most convenient to use SmartIcons to invoke this command if the text isalready selected.

Example: TextSetFontSizeThis formula sets the font size to 10 points.

@Command([TextSetFontSize] ; "10")

TextSpacingDoubleSets Interline spacing below the selected text to double.

Syntax@Command([TextSpacingSingle])

UsageText must be selected in a rich text field in a document open in Edit modeor in a form or page open in Design mode.

Chapter 6: Formula Language @Commands A–Z 517

TextSpacingOneAndAHalf

Sets interline spacing below the selected text to one and a half.

Syntax@Command([TextSpacingSingle])

UsageText must be selected in a rich text field in a document open in Edit modeor in a form or page open in Design mode.

TextSpacingSingle

Sets interline spacing below the selected text to single.

Syntax@Command([TextSpacingSingle])

UsageText must be selected in a rich text field in a document open in Edit modeor in a form or page open in Design mode.

TextUnderline

Underlines selected and subsequently entered text. This command is atoggle; reselecting it removes the underlining.

Syntax@Command([TextUnderline])

UsageA document must be open in Edit mode with the insertion point in arich text field

or

A form, subform, or page must be open in Design mode

or

518 Domino Designer Programming Guide, Volume 1: Formula Language

A textbox must be selected in a navigator, with all of the text in thetextbox being underlined

or

A textbox must be selected in a layout region on a form, with all of thetext in the textbox being underlined

It’s most convenient to use SmartIcons to invoke this command if the text isalready selected.

ToolsCall

Displays the Call Server dialog box, where the user can select a server todial in to.

Syntax@Command([ToolsCall])

ToolsCategorizeCategorizes the current document.

Syntax@Command([ToolsCategorize])

or

@Command([ToolsCategorize] ; category )

Parametercategory

Text. Optional. The name of the category you want to put the documentin. You can only list a single category name.

UsageIf you include category, the selected documents are moved to that category.If you don’t include category, Notes displays the Categorize dialog box sothe user can select a category.

In a view, all selected documents are categorized.

In a document in Read or Edit mode, only that document is categorized.

The current view must be a categorized view where the first categorizedcolumn sorts on a field named “categories.”

Chapter 6: Formula Language @Commands A–Z 519

Examples: ToolsCategorize1. This formula displays the Categorize dialog box.

@Command([ToolsCategorize])

2. This formula moves the selected documents to the “Weekly StatusReport” category.@Command([ToolsCategorize] ; "Weekly Status Reports")

ToolsHangUpDisplays the Hang Up dialog box.

Syntax@Command([ToolsHangUp])

ToolsMarkAllReadMarks all of the documents in a database as read.

Syntax@Command([ToolsMarkAllRead])

UsageA database must be open at the view or folder level

or

A document must be open in Read or Edit mode.

Note In some databases, there is no difference in the display of read andunread documents in views and folders.

ToolsMarkAllUnreadMarks all of the documents in a database as unread.

Syntax@Command([ToolsMarkAllUnread])

520 Domino Designer Programming Guide, Volume 1: Formula Language

UsageA database must be open at the view level

or

A document must be open in Read or Edit mode.

Note In some databases, there is no difference in the display of read andunread documents in views and folders.

ToolsMarkSelectedReadIn a view or folder, marks all of the selected documents as read.

Syntax@Command([ToolsMarkSelectedRead])

UsageA database must be open at the view level

or

A document must be open in Read or Edit mode.

Note In some databases, there is no difference in the display of read andunread documents in views and folders.

ToolsMarkSelectedUnreadIn a view or folder, marks all of the selected documents as unread.

Syntax@Command([ToolsMarkSelectedUnread])

UsageA database must be open at the view level

or

A document must be open in Read or Edit mode.

Note In some databases, there is no difference in the display of read andunread documents in views and folders.

Chapter 6: Formula Language @Commands A–Z 521

ToolsRefreshAllDocs

Refreshes the fields of all the documents in a view or folder.

Syntax@Command([ToolsRefreshAllDocs])

UsageA database must be open at the view or folder level.

ToolsRefreshSelectedDocs

Refreshes the fields of all the selected documents in a view or folder.

Syntax@Command([ToolsRefreshSelectedDocs])

UsageA database must be open at the view or folder level and at least onedocument must be selected.

ToolsReplicate

Displays the Replicate dialog box, where the user can choose to replicate thecurrent database using the options defined in Replicator or using specialone-time options.

Syntax@Command([ToolsReplicate] ; repMethod )

ParameterrepMethod

Number. Optional. A value of “1” specifies replication using theoptions that the user can set. A value of “0” specifies replication usingthe options defined in Replicator. If this parameter is omitted, Notesprompts the user to choose between these two replication methods.

UsageA database must be open or selected on the workspace.

522 Domino Designer Programming Guide, Volume 1: Formula Language

ToolsRunBackgroundMacros

Runs all of the database’s scheduled agents, regardless of when they arescheduled to run. The agents will then run as usual at their regularlyscheduled times.

Syntax@Command([ToolsRunBackgroundMacros])

UsageA database must be open or selected on the workspace.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

ToolsRunMacro

Executes a macro or agent that you specify.

Syntax@Command([ToolsRunMacro] ; agent )

Parametersagent

Text. Optional. The name of the agent you want to run.

If you omit the agent name, Notes displays a list of Agents in the database,where the user can select which agent to run.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used, except onthe Web. All @Commands run in sequence on the Web.

To get output from an agent in JavaScript-enabled dbs, use@Command([FileCloseWindow]) after @Command([ToolsRunMacro]).

Example: ToolsRunMacroThis formula runs the agent named “PurgeObsoleteRecords.”

@Command([ToolsRunMacro] ;"PurgeObsoleteRecords")

Chapter 6: Formula Language @Commands A–Z 523

ToolsScanUnreadChoose

Displays the Scan Unread Preferred Setup dialog box, where the user canselect the preferred databases to be scanned for unread documents.

Syntax@Command([ToolsScanUnreadChoose])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

ToolsScanUnreadPreferred

Displays the Scan Unread dialog box, where the user can see unread countsfor each of the user preferred databases.

Syntax@Command([ToolsScanUnreadPreferred])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

ToolsScanUnreadSelected

Opens the selected database to the first unread document. The user canthen navigate to subsequent unread documents.

Syntax@Command([ToolsScanUnreadSelected])

UsageIf one database is selected on the workspace, Notes/Domino opens thefirst unread document in the database.

If multiple databases are selected, Notes/Domino displays the ScanUnread dialog box, where the user can see the unread count for each database.

If no database is selected on the workspace, Notes/Domino displays theScan Unread dialog box, which allows you to select a database withunread documents to open.

524 Domino Designer Programming Guide, Volume 1: Formula Language

ToolsSetupLocation

Opens the current location document in your Personal Address Book in Editmode, allowing you to change your home server, mail database location,and time zone.

Syntax@Command([ToolsSetupLocation])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

ToolsSetupMail

Displays the Mail section of the User Preferences dialog box, where the usercan indicate how often Notes should check for new mail, whether to signand encrypt outgoing mail, and so on.

Syntax@Command([ToolsSetupMail])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

ToolsSetupPorts

Displays the Ports section of the User Preferences dialog box, where theuser can enable and disable network ports.

Syntax@Command([ToolsSetupPorts])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

Chapter 6: Formula Language @Commands A–Z 525

ToolsSetupUserSetup

Displays the Basics section of the User Preferences dialog box, where theuser defines Notes startup options.

Syntax@Command([ToolsSetupUserSetup])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

ToolsSmartIcons

Displays the SmartIcons dialog box where the user can create SmartIcons,define SmartIcons sets, and select a set for display on the workspace.

Syntax@Command([ToolsSmartIcons])

UsageThis can be used anywhere within Notes/Domino except from within adialog box.

ToolsSpellCheck

Starts the Notes spell checker.

Syntax@Command([ToolsSpellCheck])

UsageA document must be open in Edit mode.

526 Domino Designer Programming Guide, Volume 1: Formula Language

ToolsUserLogoff

Logs the user off of all Domino servers. Reconnecting to a Domino serverrequires the user Notes ID and, if one is set, password.

Syntax@Command([ToolsUserLogoff])

UsageThis can be used anywhere in Notes/Domino except from within a dialog box.

UserIDCertificates

Displays the Certificates section of the User ID dialog box. If the user ID ispassword-protected, the user must enter the password before displayingthe dialog box.

Syntax@Command([UserIDCertificates])

UsageThis command can be used almost anywhere in Notes/Domino except fromwithin a dialog box.

UserIDClearPassword

Syntax@Command([UserIDClearPassword])

Displays the Enter Password dialog box where the password associatedwith the user ID can be removed. This can be used almost anywhere inNotes/Domino except from within a dialog box.

Chapter 6: Formula Language @Commands A–Z 527

UserIDCreateSafeCopy

Displays the Enter Safe Copy ID File Name dialog box, where the userdefines a file name for storing a safe copy of the Notes user ID. The safecopy contains only the user name, license number, and public key. Theprivate key and all certificates are omitted from the safe copy.

Syntax@Command([UserIDCreateSafeCopy])

UsageThis command can be used anywhere in Notes/Domino except from withina dialog box.

UserIDEncryptionKeys

Displays the Encryption section of the User ID dialog box. If the user ID ispassword-protected, the user must enter the password before displayingthe dialog box.

Syntax@Command([UserIDEncryptionKeys])

UsageThis command can be used anywhere in Notes/Domino except from withina dialog box.

UserIDInfo

Displays the Basics section of the User ID Information dialog box.

Syntax@Command([UserIDInfo])

UsageThis command can be used anywhere in Notes/Domino except from withina dialog box.

528 Domino Designer Programming Guide, Volume 1: Formula Language

UserIDMergeCopy

Displays the Choose User ID to Merge into Current ID dialog box. This letsthe user select an updated user ID (for example, one that has been certifiedby an administrator) and merge it into the existing user ID (thus retainingthe information already stored in the existing ID). If the user ID ispassword-protected, Notes requires the user to enter the password beforedisplaying the dialog box.

Syntax@Command([UserIDMergeCopy])

UsageThis command can be used anywhere in Notes/Domino except from withina dialog box.

UserIDSetPassword

Displays the Set Password dialog box where the user can enter a newpassword for the Notes ID. If a password already exists, the user must enterthe existing password before specifying a new one.

Syntax@Command([UserIDSetPassword])

UsageThis command can be used anywhere in Notes/Domino except from withina dialog box.

UserIDSwitch

Displays the Choose User ID to Switch To dialog box. If the selected ID ispassword-protected, Notes next displays the Enter Password dialog box,where the user must enter the correct password.

Syntax@Command([UserIDSwitch])

UsageThis command can be used anywhere in Notes/Domino except from withina dialog box.

Chapter 6: Formula Language @Commands A–Z 529

V3EditNextFieldIn a document in Edit mode, moves the insertion point to the next editablefield (from an icon in a SmartIcons set) or to the first field (from a button ona form).

Syntax@Command([V3EditNextField])

UsageUse V3EditNextField to enable your application to run under Release 3 ofLotus Notes.

When used in a SmartIcons formula, V3EditNextField moves theinsertion point to the next editable field in the document, working leftto right and top to bottom.

When used in a button that’s built into the form, the first occurrence of V3EditNextField always moves the insertion point to the first field in the document. You must add an additional@Command([V3EditNextField]) to move to each subsequent field (oryou could use a related command such as EditUp or EditDown).

A document must be open in Edit mode.

V3EditPrevFieldIn a document in Edit mode, moves the insertion point to the first editablefield (from an icon in a SmartIcons set) or to the first field (from a button ona form).

Syntax@Command([V3EditPrevField])

Use V3EditPrevField to enable your application to run under Release 3 of Notes.

When used in a SmartIcons formula, V3EditPrevField moves theinsertion point to the first editable field in the document, working rightto left and bottom to top.

When used in a button that’s built into the form, the first occurrence ofV3EditPrevField always moves the insertion point to the first field inthe document. You must add an additional@Command([V3EditPrevField]) to move to the last field on the form,and again for each additional field (or you could use a relatedcommand such as EditUp or EditDown).

A document must be open in Edit mode.

530 Domino Designer Programming Guide, Volume 1: Formula Language

ViewArrangeIcons

Aligns database icons on the current workspace page from left to right andtop to bottom.

Syntax@Command([ViewArrangeIcons])

UsageThis command can only be used on the workspace.

ViewBelowFolders

Places the view pane at the bottom of the screen and the folder pane at the top.

Syntax@Command([ViewBelowFolders])

UsageA database must be open at the view or folder level.

ViewBesideFolders

Places the view pane at the right of the screen and the folder pane at the left.

Syntax@Command([ViewBesideFolders])

UsageA database must be open at the view or folder level.

ViewCertify

Displays the Choose Certifier ID dialog box, in which you specify thecertification to be renewed for the selected user or users.

Syntax@Command([ViewCertify])

Chapter 6: Formula Language @Commands A–Z 531

UsageViewCertify is available once you have opened a server Address Book tothe People view and selected one or more Person documents. View Certifyenables you to initiate recertification of the selected user or users by theAdministration Process.

ViewChangeSwitches to the specified view or folder within the current database or, if aview or folder is not specified, displays the View menu so the user canselect a view.

Syntax@Command([ViewChange])

or

@Command([ViewChange] ; viewName )

ParameterviewName

Text. Optional. The name of the view or folder you want to switch to.

UsageThis command doesn’t work from within a document or form, so youcannot use it to view a document through another form. UseViewSwitchForm instead.

You can use this command in Web applications, but you must use theviewName parameter.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used, except onthe Web. All @Commands run in sequence on the Web.

Example: ViewChange@Command([ViewChange]; "By Author")

switches to the By Author view.

532 Domino Designer Programming Guide, Volume 1: Formula Language

ViewCollapse

Collapses all levels of subcategories, documents, and responses within thecurrent category, so only the topmost category name shows. If the view orfolder has a response hierarchy but is not categorized, ViewCollapsecollapses all levels of response documents under the current maindocument.

Syntax@Command([ViewCollapse])

UsageA database must be open at a view or folder that uses categories and/or aresponse hierarchy.

New with Release 5. The View applet is now programmable via this@Command.

ViewCollapseAll

Collapses all levels of categories, subcategories, documents, and responseswithin a view or folder so that only the topmost level of category namesappears. If the view or folder has a response hierarchy but is notcategorized, ViewCollapseAll collapses all levels of response documentsunder the main documents.

Syntax@Command([ViewCollapseAll])

UsageA database must be open at the view or folder level.

You can use this command in Web applications.

New with Release 5. The View applet is now programmable via this@Command.

Chapter 6: Formula Language @Commands A–Z 533

ViewExpand

Expands one level of subcategories, documents, and responses within thecurrent category. If the view or folder has a response hierarchy but is notcategorized, ViewExpand expands all levels of response documents underthe current main document.

Syntax@Command([ViewExpand])

UsageA database must be open at a view or folder that uses categories and/or aresponse hierarchy.

New with Release 5. The View applet is now programmable via this@Command.

ViewExpandAll

Expands all levels of categories, subcategories, documents, and responseswithin the view or folder.

Syntax@Command([ViewExpandAll])

UsageA database must be open at a view or folder that uses categories, a responsehierarchy, or both. If the view or folder has a response hierarchy but is notcategorized, ViewExpandAll expands all levels of response documentsunder the main documents.

You can use this command in Web applications

New with Release 5. The View applet is now programmable via this@Command.

ViewExpandWithChildren

Expands all levels of subcategories, documents, and responses within theselected category.

Syntax@Command([ViewExpandWithChildren])

534 Domino Designer Programming Guide, Volume 1: Formula Language

ViewHorizScrollBar

Displays the horizontal scroll bar in a view or folder.

Note ViewHorizScrollbar is not supported under OS/2 and on theMacintosh.

Syntax@Command([ViewHorizScrollBar])

UsageA database must be open to a view or folder.

ViewMoveName

Displays the Choose Certifier ID dialog box, which allows you to specify theorganizational unit for which you want to certify the selected user.

Syntax@Command([ViewMoveName])

ViewMoveName is available once you have opened a server Address Bookto the People view and selected a Person document. ViewMoveNameinitiates the process of changing the user’s hierarchical name through theAdministration Process.

ViewNavigatorsFolders

Displays the Folders and Views navigators in the navigator pane and theview or folder that the user most recently selected.

Syntax@Command([ViewNavigatorsFolders])

UsageA database must be open to a view or folder.

Chapter 6: Formula Language @Commands A–Z 535

ViewNavigatorsNone

Hides the navigator pane.

Syntax@Command([ViewNavigatorsNone])

UsageA database must be open to a view or folder.

ViewRefreshFields

Recalculates the fields in the current document or updates the current viewor folder.

Syntax@Command([ViewRefreshFields])

UsageA document must be open in Edit mode

or

A database must be open at the view or folder level

When you execute this command on the Web, it recalculates all fieldsformulas without closing the document. On the Web, you can only use this command for databases where you have enabled JavaScript to generatethe pages.

The View applet is now programmable via this @Command. New withRelease 5.

ViewRefreshUnread

Updates the unread counts on all database icons displayed on the currentworkspace page.

Syntax@Command([ViewRefreshUnread])

UsageA database must be open at the workspace.

536 Domino Designer Programming Guide, Volume 1: Formula Language

ViewRenamePerson

Displays the Certify Selected Entries dialog box, which enables you toupgrade the selected user name to a hierarchical name, change the user’scommon name, or change the user’s hierarchical name.

Syntax@Command([ViewRenamePerson])

UsageViewRenamePerson is available once you have opened a server AddressBook to the People view and selected a Person document.ViewRenamePerson initiates the change you specify through theAdministration Process.

ViewShowFieldHelp

Shows field Help, so that the Help description for the current field (ifavailable) appears on the status bar while the user composes or edits adocument. (Field Help is a design option specified in the Field Propertiesbox.) This command is a toggle; reselecting it hides the field Help.

Syntax@Command([ViewShowFieldHelp])

UsageA document must be open in Edit mode.

ViewShowObject

Displays the “object delimiter” — a dotted frame surrounding an OLE/LELobject within a field. This command is a toggle; reselecting it hides theobject delimiter so the OLE/LEL object looks like regular, editable data.

Syntax@Command([ViewShowObject])

UsageThis command is necessary only when a document is open in Read mode;the object delimiter always displays in Edit mode.

Chapter 6: Formula Language @Commands A–Z 537

ViewShowOnlyCategories

Collapses the view or folder so that only category and subcategory names show up. This command is a toggle; reselecting it expands allcategory levels.

Syntax@Command([ViewShowOnlyCategories])

UsageA database must be open at the view level.

ViewShowOnlySearchResults

Shows the results of a full text search as selected documents in a view orfolder. This command is a toggle. Instead of listing only the documents thatsatisfy the search query (the default for a full text search), the view or folderlists all the documents it normally lists, with a check mark in front of thosedocuments that satisfy the search query.

Syntax@Command([ViewShowOnlySearchResults])

UsageA database must be open at the view or folder level, and a full text searchmust have been run.

ViewShowOnlySelected

Displays only the selected documents or categories in the view or folder(those documents with a check mark). This command is a toggle; reselectingit displays all documents or categories.

Syntax@Command([ViewShowOnlySelected])

UsageA database must be open at the view or folder level.

538 Domino Designer Programming Guide, Volume 1: Formula Language

ViewShowOnlyUnread

Displays only the unread documents in the view or folder. This command isa toggle; reselecting it displays all documents in the view or folder.

Syntax@Command([ViewShowOnlyUnread])

UsageA database must be open at the view or folder level.

ViewShowPageBreaks

Displays a line representing each page break in the document. The pagebreaks indicate where Notes will end each page when the document isprinted on the currently selected printer. This command is a toggle;reselecting it suppresses the display of automatic page breaks (manual pagebreaks will still be displayed).

Syntax@Command([ViewShowPageBreaks])

UsageA document must be open in Edit mode.

ViewShowRuler

Toggles the display of the ruler while a document is open in Edit mode.

Syntax@Command([ViewShowRuler])

ViewShowSearchBar

Toggles the display of the full text search bar at the top of the view. If the database does not have a full text index, the search bar displays but isnot usable.

Syntax@Command([ViewShowSearchBar] ; onOff )

Chapter 6: Formula Language @Commands A–Z 539

ParameteronOff

Number. Specify “1” to show the search bar. Specify “0” to hide it. Omit this parameter to toggle the display of the search bar.

UsageYou can use this command in Web applications.

ViewShowServerNamesToggles the display of server names on the database icons in the user’sworkspace.

Syntax@Command([ViewShowServerNames])

ViewShowUnreadToggles the display of the unread document count on each database icon on the user’s workspace.

Syntax@Command([ViewShowUnread])

ViewSwitchFormChanges the form used to display the current document.

Syntax@Command([ViewSwitchForm] ; formName )

ParameterformName

Text. Optional. The name of the form you want to switch to.

With no parameter, ViewSwitchForm displays a dialog box with a list offorms available in the current database.

Order of executionThis command executes only after the entire formula has been evaluated,regardless of whether @Command or @PostedCommand is used.

540 Domino Designer Programming Guide, Volume 1: Formula Language

WindowMaximize

Maximizes the active Notes window (the window whose title bar ishighlighted).

Syntax@Command([WindowMaximize])

UsageThis command can be used anywhere in Notes, except for an open dialog box.

WindowMaximizeAll

Maximizes all open Notes windows.

Syntax@Command([WindowMaximizeAll])

UsageThis command can be used anywhere in Notes, except for an open dialog box.

WindowMinimize

Minimizes the active Notes window (the window whose title bar ishighlighted).

Syntax@Command([WindowMinimize])

UsageThis command can be used anywhere in Notes, except for an open dialog box.

Chapter 6: Formula Language @Commands A–Z 541

WindowMinimizeAll

Minimizes all open Notes windows.

Syntax@Command([WindowMinimizeAll])

UsageThis command can be used anywhere in Notes, except for an open dialog box.

WindowWorkspace

Displays the Notes workspace as the active (topmost) window.

Syntax@Command([WindowWorkspace])

UsageThis command can be used anywhere in Notes, except for an open dialog box.

WorkspaceProperties

Displays the Properties box for the Notes workspace.

Syntax@Command([WorkspaceProperties])

UsageThe Notes workspace must be open in the current window.

542 Domino Designer Programming Guide, Volume 1: Formula Language

WorkspaceStackReplicaIcons

For databases on the workspace that are replicas of one another, stacksthem into a single icon. The command is a toggle; reselecting it unstacks the replica icons and displays each icon individually.

Syntax@Command([WorkspaceStackReplicaIcons])

UsageThe Notes workspace must be open in the current window.

ZoomPreview

Toggles the ZoomPreview setting in a view.

Syntax@Command([ZoomPreview] ; size )

Parametersize

Text (“0” or “1”). Optional. Specify “1” to zoom the preview pane to the maximum size. Specify “0” to return the preview pane to itsprevious size.

UsageZoomPreview enlarges the preview pane when enabled, and shrinks itwhen disabled. The preview pane must be open. Using the “0” parameter isnot the same as shrinking the window to its minimum size. The windowshrinks to its previous size; if the curent size and previous size are the same,it does not shrink.

Chapter 6: Formula Language @Commands A–Z 543

Symbols@Abs function, 113, 154@Abstract, 155@Accessed function, 118, 162@Acos function, 114, 164[AddBookmark] command, 400[AddDatabase] command, 400[AddDatabaseRepID] command, 401@AddToFolder function, 164@Adjust function, 119, 165[AdminCertify] command, 402[AdminCreateGroup] command, 402[AdminCrossCertifyIDFile]

command, 403[AdminCrossCertifyKey]

command, 403[AdminDatabaseAnalysis]

command, 403[AdminDatabaseQuotas]

command, 404[AdminIDFileClearPassword]

command, 404[AdminIDFileExamine]

command, 404[AdminIDFileSetPassword]

command, 405[Administration] command, 405[AdminNewOrganization]

command, 405[AdminNewOrgUnit] command, 406[AdminOpenAddressBook]

command, 406[AdminOpenCatalog]

command, 406[AdminOpenCertLog]

command, 407[AdminOpenGroupsView]

command, 407[AdminOpenServerLog]

command, 407[AdminOpenServersView]

command, 408[AdminOpenStatistics]

command, 408

[AdminOpenUsersView] command, 408

[AdminOutgoingMail] command, 409

[AdminRegisterFromFile] command, 409

[AdminRegisterServer] command, 409

[AdminRegisterUser] command, 410[AdminRemoteConsole]

command, 410[AdminSendMailTrace]

command, 410[AdminStatisticsConfig]

command, 411[AdminTraceConnection]

command, 411[AgentEdit] command, 411[AgentEnableDisable]

command, 412[AgentLog] command, 412[AgentRun] command, 413[AgentSetServerName]

command, 413[AgentTestRun] command, 413@All function, 6, 15, 84, 101, 167@AllChildren function, 101, 126, 167@AllDescendants function, 101,

126, 168@Ascii function, 171@Asin function, 114, 172@Atan function, 114, 173@Atan2 function, 114, 174[AttachmentDetachAll]

command, 414[AttachmentLaunch] command, 414@AttachmentLengths function,

126, 175@AttachmentNames function,

126, 176[AttachmentProperties]

command, 414@Attachments function, 126, 176[AttachmentView], 415@Author function, 126, 177

[AutoHorzFit] command, 97[AutoVertFit] command, 97@Begins function, 109, 178$Body field, 65@BrowserInfo function, 179[CalendarFormat] command, 415[CalendarGoTo] command, 416@Certificate function, 181@Char function, 105, 182@CheckAlarms function, 183[ChooseFolders] command, 416@ClientType function, 184@Command function, 76, 101, 184@Commands

order of evaluation, 77reference, 397using, 397

@Commands function, 77[Compose] command, 417@Contains function, 109, 186@Cos function, 114, 186[CreateAction] command, 418[CreateAgent] command, 418[CreateControlledAccessSection]

command, 419@Created function, 118, 187[CreateEllipse] command, 419[CreateFolder] command, 419[CreateForm] command, 420[CreateLayoutRegion]

command, 420[CreateNavigator] command, 420[CreatePolygon] command, 421[CreatePolyline] command, 421[CreateRectangle] command, 421[CreateRectangularHotspot]

command, 422[CreateSection] command, 422[CreateSubForm] command, 422[CreateTextbox] command, 423[CreateView] command, 423[DatabaseReplSettings]

command, 423@Date function, 119, 188@Day function, 118, 190

Index-1

Index

@DbColumn function, 76, 101, 131Notes database, 128, 190ODBC, 195

@DbCommand function, 201ODBC, 131

@DbExists function, 206@DbLookup function, 76, 102, 128,

131, 207, 214@DbManager function, 122, 220@DbName function, 122, 221@DbTitle function, 222@DDEExecute function, 76, 223@DDEInitiate function, 76, 225@DDEPoke function, 76, 227@DDETerminate function, 76, 228[DebugLotusScript] command, 424@DeleteDocument function, 102, 229@DeleteField function, 102, 125, 230[DesignDocumentInfo]

command, 424[DesignFormAttributes]

command, 424[DesignFormFieldDef]

command, 425[DesignFormNewField]

command, 425[DesignForms] command, 425[DesignFormShareField]

command, 425[DesignFormUseField]

command, 426[DesignFormWindowTitle]

command, 426[DesignHelpAboutDocument]

command, 426[DesignHelpUsingDocument]

command, 427[DesignIcon] command, 427[DesignMacros] command, 427[DesignRefresh] command, 428[DesignReplace] command, 428[DesignSharedFields] command, 428[DesignSynopsis] command, 429[DesignViewAppendColumn]

command, 429[DesignViewAttributes]

command, 429[DesignViewColumnDef]

command, 429[DesignViewEditActions]

command, 430[DesignViewFormFormula]

command, 430

[DesignViewNewColumn]command, 430

[DesignViews] command, 430[DesignViewSelectFormula]

command, 431[DialingRules] command, 431@DialogBox function, 76, 96, 230@Do function, 78, 233@DocChildren function, 102,

124, 234@DocDescendants function, 102,

123, 236@DocFields function, 126, 238@DocLength function, 126, 238@DocLevel function, 102, 123, 239@DocMark function, 102, 126, 240@DocNumber function, 102, 123, 240@DocParentNumber function, 102,

123, 241@DocSiblings function, 102, 123, 242@DocumentUniqueID function,

126, 243@Domain function, 246[EditBottom] command, 431[EditButton] command, 432[EditClear] command, 432[EditCopy] command, 432[EditCut] command, 433[EditDeselectAll] command, 433[EditDetach] command, 434[EditDocument] command, 435[EditDown] command, 436@EditECL function, 246[EditEncryptionKeys] command, 436[EditFind] command, 437[EditFindInPreview] command, 437[EditFindNext] command, 438[EditGotoField] command, 438[EditHeaderFooter] command, 439[EditHorizScrollbar] command, 439[EditIndent] command, 439[EditIndentFirstLine] command, 440[EditInsertButton] command, 440[EditInsertFileAttachment]

command, 440[EditInsertObject] command, 441[EditInsertPageBreak]

command, 442[EditInsertPopup] command, 442[EditInsertTable] command, 443[EditInsertText] command, 443[EditLeft] command, 444[EditLinks] command, 444

[EditLocations] command, 445[EditMakeDocLink] command, 445[EditNextField] command, 445[EditOpenLink] command, 445[EditPaste] command, 446[EditPasteSpecial] command, 446[EditPhoneNumbers] command, 446[EditPrevField] command, 447[EditProfile] command, 447[EditResizePicture] command, 448[EditRight] command, 449[EditSelectAll] command, 449[EditSelectByDate] command, 450[EditShowHideHiddenChars]

command, 450[EditTableDeleteRowColumn]

command, 450[EditTableFormat] command, 451[EditTableInsertRowColumn]

command, 451[EditTop] command, 452[EditUndo] command, 452[EditUntruncate] command, 452[EditUp] command, 453@EditUserECL function, 247@Elements function, 87, 97, 247[EmptyTrash] command, 453@EnableAlarms function, 248@Ends function, 109, 248@Environment function, 97, 102, 250@Error function, 99, 253[ExchangeUnreadMarks]

command, 454[Execute] command, 454@Exp function, 114, 254@Explode function, 87, 254@Failure function, 99, 102, 257@False function, 257@FIELD function, 102[FileCloseWindow] command, 455[FileDatabaseACL] command, 455[FileDatabaseCompact]

command, 455[FileDatabaseCopy] command, 456[FileDatabaseDelete] command, 456[FileDatabaseInfo] command, 456[FileDatabaseRemove]

command, 457[FileDatabaseUseServer]

command, 457[FileExit] command, 457[FileExport] command, 458[FileFullTextCreate] command, 460

Index-2

[FileFullTextDelete] command, 460[FileFullTextInfo] command, 460[FileFullTextUpdate] command, 461[FileImport] command, 461[FileNewDatabase] command, 463[FileNewReplica] command, 463[FileOpenDatabase] command, 464[FileOpenDBRepID] command, 466[FilePageSetup] command, 467[FilePrint] command, 468[FilePrintSetup] command, 470[FileSave] command, 470[FileSaveNewVersion]

command, 470[FindFree]TimeDialog

command, 471[Folder] command, 472[FolderCollapse] command, 473[FolderCustomize] command, 473[FolderExpand] command, 474[FolderExpandAll] command, 474[FolderExpandWithChildren]

command, 474[FolderMove] command, 475[FolderProperties] commandx, 475[FolderRename] command, 475@FontList function, 259[FormActions] command, 476[FormTestDocument] command, 476@Functions

@Commands, 77described, 101in LotusScript, 549operating, 133, 143order of evaluation, 77reference, 133restrictions, 101return value, 76syntax, 75using, 75, 133, 143

@GetDocField function, 129, 259@GetPortsList function, 260@GetProfileField function, 261[GoUpLevel] command, 476[Help] command, 476[HelpAboutDatabase]

command, 477[HelpAboutNotes] command, 477[HelpFunctions] command, 477[HelpIndex] command, 477[HelpKeyboard] command, 478[HelpMessages] command, 478[HelpReleaseNotes] command, 478

[HelpTableOfContents] command, 478

[HelpUsingDatabase] command, 479[HelpV3ReleaseMenuFinder]

command, 478[HotSpotClear] command, 479[HotSpotProperties] command, 479@Hour function, 119, 262@If function, 78, 90, 263@Implode function, 87, 265$Info field, 65@InheritedDocumentUniqueID

function, 126, 266[InsertSubForm] command, 480@Integer function, 113, 266@IsAgentEnabled function, 267@IsAvailable function, 126, 268@IsCategory function, 102, 124, 269@IsDocBeingEdited function,

126, 270@IsDocBeingLoaded function, 102,

126, 270@IsDocBeingMailed function, 102,

126, 271@IsDocBeingRecalculated function,

102, 126, 272@IsDocBeingSaved function, 102,

126, 273@IsDocTruncated function, 274@IsError function, 99, 274@IsExpandable function, 102,

124, 275@IsMember function, 87, 276@IsModalHelp function, 277@IsNewDoc function, 102, 126, 278@IsNotMember function, 87, 278@IsNumber function, 105, 280@IsResponseDoc function, 126, 280@IsText function, 105, 281@IsTime function, 105, 282@IsUnavailable function, 282@IsValid function, 283@Keywords function, 87, 284@LanguagePreference, 285[LayoutAddGraphic] command, 480[LayoutAddText] command, 480[LayoutElementBringToFront]

command, 481[LayoutElementProperties]

command, 481[LayoutElementSendToBack]

command, 481[LayoutProperties] command, 482

@Left function, 109, 286@LeftBack function, 109, 287@Length function, 106, 288@Like function, 106, 289@Ln function, 114, 290@Locale function, 291@Log function, 114, 292@LowerCase function, 112, 293[MailAddress] command, 482[MailComposeMemo]

command, 482@MailDbName function, 121, 294@MailEncryptSavedPreference

function, 295@MailEncryptSentPreference

function, 296[MailForward] command, 483[MailForwardAsAttachment]

command, 483[MailOpen] command, 483[MailRequestCrossCert]

command, 483[MailRequestNewName]

command, 484[MailRequestNewPublicKey]

command, 484@MailSavePreference function, 296[MailScanUnread] command, 484[MailSend] command, 485@MailSend function, 76, 102,

125, 297[MailSendCertificateRequest]

command, 485[MailSendEncryptionKey]

command, 485[MailSendPublicKey] command, 486@MailSignPreference function, 301@Matches function, 106, 302@Max function, 113, 303@Member function, 87, 304@Middle function, 109, 305@MiddleBack function, 109, 307@Min function, 113, 308@Minute function, 119, 310@Modified function, 118, 310@Modulo function, 114, 311@Month function, 119, 312@Name function, 121, 313@NameLookup function, 317@Narrow function, 319[NavigateNext] command, 486[NavigateNextHighlight]

command, 486

Index-3

[NavigateNextMain] command, 487[NavigateNextSelected]

command, 487[NavigateNextUnread]

command, 488[NavigatePrev] command, 488[NavigatePrevHighlight]

command, 489[NavigatePrevMain] command, 489[NavigatePrevSelected]

command, 490[NavigatePrevUnread]

command, 490[NavigateToBackLink]

command, 490[NavigatorProperties]

command, 491[NavigatorTest] command, 491@NewLine function, 112, 320@No function, 321@NoteID function, 126, 322@Now function, 118, 322[ObjectDisplayAs] command, 491[ObjectOpen] command, 492[ObjectProperties] command, 492[OpenCalendar] command, 492[OpenDocument] command, 493[OpenFrameset] command, 494[OpenHelpDocument]

command, 494[OpenNavigator] command, 495[OpenPage] command, 496[OpenView] command, 496@OptimizeMailAddress function,

121, 322@Password function, 121, 323[PasteBitmapAsBackground]

command, 497[PasteBitmapAsObject]

command, 498@Pi function, 114, 324@PickList [CUSTOM] function, 94@PickList [NAME] function, 94@PickList function, 76, 102, 325[PictureProperties] command, 498@Platform function, 102, 121, 328@PostedCommand, 76@PostedCommand function,

103, 330@Power function, 114, 330@Prompt([OK], 93@Prompt([OKCANCELLIST], 93@Prompt[LOCALBROWSE]

function, 94

@Prompt [OKCANCELCOMBO]function, 94

@Prompt [OKCANCELEDIT]function, 94

@Prompt[OKCANCELEDITCOMBO]function, 94

@Prompt [OKCANCELLIST]function, 94

@Prompt [OKCANCELLISTMULT]function, 94

@Prompt [PASSWORD] function, 94@Prompt [YESNO] function, 93@Prompt [YESNOCANCEL]

function, 93@Prompt function, 76, 81, 93,

103, 331@ProperCase function, 112, 336[PublishDatabase] command, 498@Random function, 114, 337@RefreshECL function, 338[RefreshHideFormulas]

command, 499[RefreshParentNote] command, 498%Rem directive

in Script Editor, 50[RemoveFromFolder] command, 499[RenameDatabase] command, 499@Repeat function, 112, 339@Replace function, 87, 340@ReplaceSubstring function, 341[Replicator] command, 500[ReplicatorReplicateHigh]

command, 500[ReplicatorReplicateNext]

command, 501[ReplicatorReplicateSelected]

command, 501[ReplicatorReplicateWithServer]

command, 501[ReplicatorSendMail] command, 502[ReplicatorSendReceiveMail]

command, 502[ReplicatorStart] command, 502[ReplicatorStop] command, 502@Responses function, 103, 123,

126, 342@Return function, 78, 99, 103, 343@Right function, 109, 344@RightBack function, 109, 345@Round function, 113, 346@Second function, 119, 347[SectionCollapse] command, 503[SectionCollapseAll] command, 503

[SectionDefineEditors] command, 503

[SectionExpand] command, 504[SectionExpandAll] command, 504[SectionProperties] command, 504[SectionRemoveHeader]

command, 505@Select function, 349@Set function, 350[SetCurrentLocation] command, 505@SetDocField function, 103, 129, 351@SetEnvironment function, 97,

103, 352@SetField function, 103, 125, 353@SetProfileField function, 354@SetTargetFrame function, 354[ShowHideLinkPreview]

command, 505[ShowHideParentPreview]

command, 506[ShowHidePreviewPane]

command, 506[ShowProperties] command, 506@Sign function, 113, 356@Sin function, 114, 356[SmartIconsFloating] command, 507[SmartIconsNextSet] command, 507@Soundex function, 357@Sqrt function, 114, 358[StyleCycleKey] command, 507@Subset function, 87, 358@Success function, 99, 103, 359@Sum function, 113, 359@Tan function, 114, 361@Text function, 105, 361[TextAlignCenter] command, 508[TextAlignFull] command, 508[TextAlignLeft] command, 508[TextAlignNone] command, 509[TextAlignRight] command, 509[TextBold] command, 509[TextBullet] command, 510[TextCycleSpacing] command, 510[TextEnlargeFont] command, 511[TextFont] command, 511[TextItalic] command, 512[TextNormal] command, 512[TextNumbers] command, 513[TextOutdent] command, 513[TextParagraph] command, 514[TextParagraphStyles]

command, 514[TextPermanentPen] command, 514[TextReduceFont] command, 515

Index-4

[TextSetFontColor] command, 515[TextSetFontFace] command, 516[TextSetFontSize] command, 517[TextSpacingDouble] command, 517[TextSpacingOneAndAHalf]

command, 518[TextSpacingSingle] command, 518@TextToNumber function, 363@TextToTime function, 364[TextUnderline] command, 518@Time function, 119, 365$Title field, 65@Today function, 118, 366@Tomorrow function, 118, 367[ToolsCall] command, 519[ToolsCategorize] command, 519[ToolsHangUp] command, 520[ToolsMarkAllRead] command, 520[ToolsMarkAllUnread]

command, 520[ToolsMarkSelectedRead]

command, 521[ToolsMarkSelectedUnread]

comand, 521[ToolsRefreshAllDocs]

command, 522[ToolsRefreshSelectedDocs]

command, 522[ToolsReplicate] command, 522[ToolsRunBackgroundMacros]

command, 523[ToolsRunMacro] command, 523[ToolsScanUnreadChoose]

command, 524[ToolsScanUnreadPreferred]

command, 524[ToolsScanUnreadSelected]

command, 524[ToolsSetupLocation] command, 525[ToolsSetupMail] command, 525[ToolsSetupPorts] command, 525[ToolsSetupUserSetup]

command, 526[ToolsSmartIcons] command, 526[ToolsSpellCheck] command, 526[ToolsUserLogoff] command, 527@Trim function, 112, 367@True function, 368@Unavailable function, 103, 369@UndeleteDocument function, 369@Unique function, 87, 370@UpperCase function, 112, 370@URLGetHeader function, 371

@URLHistory function, 373@URLOpen function, 374@UserAccess function, 377[UserIDCertificates] command, 527[UserIDClearPassword]

command, 527[UserIDCreateSafeCopy]

command, 528[UserIDEncryptionKeys]

command, 528[UserIDInfo] command, 528[UserIDMergeCopy] command, 529[UserIDSetPassword] command, 529[UserIDSwitch] command, 529@UserName function, 121, 379@UserNameLanguage function, 381@UserNamesList function, 382@UserPrivileges function, 383@UserRoles function, 121, 383@V2If function, 384@V3Command function, 77[V3EditNextField] command, 530[V3EditPrevField] command, 530@V3UserName function, 385@ValidateInternetAddress

function, 386@Version function, 121, 388[ViewArrangeIcons] command, 531[ViewBelowFolders] command, 531[ViewBesideFolders] commnd, 531[ViewCertify] command, 531[ViewChange] command, 532[ViewCollapse] command, 533[ViewCollapseAll] command, 533[ViewExpand] command, 534[ViewExpandAll] command, 534[ViewExpandWithChildren]

command, 534[ViewHorizScrollBar] command, 535[ViewMoveName] command, 535[ViewNavigatorsFolders]

command, 535[ViewNavigatorsNone]

command, 536[ViewRefreshFields] command, 536[ViewRefreshUnread] command, 536[ViewRenamePerson] command, 537[ViewShowFieldHelp]

command, 537[ViewShowObject] command, 537[ViewShowOnlyCategories]

command, 538

[ViewShowOnlySearchResults]command, 538

[ViewShowOnlySelected] command, 538

[ViewShowOnlyUnread] command, 539

[ViewShowPageBreaks] command, 539

[ViewShowRuler] command, 539[ViewShowSearchBar]

command, 539[ViewShowServerNames]

command, 540[ViewShowUnread] command, 540[ViewSwitchForm] command, 540@ViewTitle function, 103, 122, 389@Weekday function, 118, 389@Wide function, 390[WindowMaximize] command, 541[WindowMaximizeAll]

command, 541[WindowMinimize] command, 541[WindowMinimizeAll]

command, 542$WindowTitle field, 65[WindowWorkspace] command, 542@Word function, 110, 391[WorkspaceProperties]

command, 542[WorspaceStackReplicaIcons]

command, 543@Year function, 119, 392@Yes function, 393@Yesterday function, 118, 393@Zone function, 119, 394[ZoomPreview] command, 543

AAbbreviated property

Name class, 2065NotesName class, 1075

Abs function, 113, 154Abstract method

NotesItem class, 1048Abstract property

NotesReplication class, 1246abstractText method

Item class, 2034Accelerators

in a formula, 81Accent sensitive

ViewColumn class, 2285

Index-5

Access levelsgetCurrentAccessLevel

method, 1788through Java, 1724

Accessed function, 118, 162Accessing

LS:DO class, 666Programmer's pane, 36

ACLaccessing in Java, 1616accessing in LotusScript, 565

ACL class, 1616, 1696ACL property

Database class, 1783NotesDatabase class, 793

ACLEntry class, 1616, 1711ACos function, 114, 164Action scripts and formulas, 85Actions, 3, 10Activate method

NotesEmbeddedObject class, 1003

activate methodEmbeddedObject class, 1984

AddBookmark command, 400AddCertifierToAddressbook

methodNotesRegistration class, 1230

addCertifierToAddressbook methodRegistration class, 2119

AddDatabase command, 400AddDatabase method

NotesUIWorkspace class, 1430AddDatabaseRepID command, 401AddDocument method

NotesDocumentCollection class, 980

addDocument methodDocumentCollection class, 1961

AddEntry methodNotesOutline class, 1199NotesViewEntryCollection

class, 1558addEntry method

Outline class, 2089ViewEntryCollection class, 2317

Addinga new line, 112

Addition, 113Addition operator (+)

Formula Language, 69AddNewLine method

NotesRichTextItem class, 1262

addNewLine methodRichTextItem class, 2150

AddPageBreak methodNotesRichTextItem class, 1263

addPageBreak method, 2152RichTextItem, 2150

Addr821 propertyName class, 2065NotesName class, 1076

Addr822Comment1 propertyName class, 2065NotesName class, 1076

Addr822Comment2 propertyName class, 2066NotesName class, 1076

Addr822Comment3 propertyName class, 2066NotesName class, 1077

Addr822LocalPart propertyName class, 2066NotesName class, 1077

Addr822Phrase propertyName class, 2067NotesName class, 1077

AddressBooks propertyNotesSession class, 1305Session class, 2185

AddRole methodNotesACL class, 733

addRole methodACL class, 1702

AddRow methodODBCResultSet class, 1140

AddServerToAddressbook methodNotesRegistration class, 1230

addServerToAddressbook methodRegistration class, 2120

AddTab methodNotesRichTextItem class, 1264RichTextItem class, 2152

AddToFolder function, 164AddUserProfile method

NotesRegistration class, 1232addUserProfile method

Registration class, 2121AddUserToAddressbook method

NotesRegistration class, 1232addUserToAddressbook method

Registration class, 2121Adjust function, 119, 165AdjustDay method

NotesDateTime class, 891adjustDay method

DateTime class, 1866

AdjustHour methodNotesDateTime class, 892

adjustHour methodDateTime class, 1867

AdjustMinute methodNotesDateTime class, 893

adjustMinute methodDateTime class, 1869

AdjustMonth methodNotesDateTime class, 894

adjustMonth methodDateTime class, 1870

AdjustSecond methodNotesDateTime class, 895

adjustSecond methodDateTime class, 1871

AdjustYear methodNotesDateTime class, 896

adjustYear methodDateTime class, 1872

ADMD propertyName class, 2067NotesName class, 1078

AdminCertify command, 402AdminCreateGroup command, 402AdminCrossCertifyIDFile

command, 403AdminCrossCertifyKey

command, 403AdminDatabaseAnalysis

command, 403AdminDatabaseQuotas

command, 404AdminIDFileClearPassword

command, 404AdminIDFileExamine

command, 404AdminIDFileSetPassword

command, 405Administration servers, 1714AdminNewOrganization

command, 405AdminNewOrgUnit command, 406AdminOpenAddressBook

command, 406AdminOpenCatalog command, 406AdminOpenCertLog command, 407AdminOpenGroupsView

command, 407AdminOpenServerLog

command, 407AdminOpenServersView

command, 408AdminOpenStatistics command, 408

Index-6

AdminOpenUsersView command, 408

AdminOutgoingMail command, 409AdminRegisterFromFile

command, 409AdminRegisterServer command, 409AdminRegisterUser command, 410AdminRemoteConsole

command, 410AdminSendMailTrace

command, 410AdminStatisticsConfig

command, 411AdminTraceConnection

command, 411AfterAddRow event, 1142AfterClose event, 1143AfterConnect event, 1104AfterConnectTo event, 1104AfterDeleteRow event, 1146AfterDisconnect event, 1105AfterExecute event, 1148AfterFirstRow event, 1163AfterGetParameter event, 1165AfterGetParameterName event, 1166AfterGetValue event, 1170AfterLastRow event, 1180AfterListDataSources event, 1109AfterListFields event, 1110AfterListProcedures event, 1111AfterListTables event, 1113AfterLocateRow event, 1182AfterNextRow event, 1184AfterNumColumns event, 1185AfterPrevRow event, 1189AfterRowPositionChange event,

1163, 1180, 1182, 1184, 1189AfterSetParameter event, 1191AfterSetSQL event, 1119AfterSetValue event, 1193AfterUpdateRow event, 1195Agent

Script Libraries in, 57Agent class, 1651, 1736AgentBase class, 1593, 1668AgentContext class, 1757AgentContext document

generating, 46AgentContext property

Session class, 2187AgentEdit command, 411AgentEnableDisable command, 412AgentLog command, 412

AgentRun command, 413AgentRunner

AgentContext document, 46creating a project, 45debugging a Java agent, 46using, 45

Agentsaccessing in Java, 1650, 2143accessing in LotusScript, 650overview, 3, 6running in Java, 1591writing a script and formula, 85

Agents propertyDatabase class, 1784NotesDatabase class, 793

AgentSetServerName command, 413AgentTestRun command, 413Alarm event

NotesTimer class, 1344Alias property

NotesOutline class, 1197NotesOutlineEntry class, 1208Outline class, 2088OutlineEntry class, 2100

Aliases propertyForm class, 1988NotesForm class, 1009NotesView class, 1460View class, 2217

Alignment propertyNotesRichTextParagraphStyle

class, 1278NotesViewColumn class, 1509RichTextParagraphStyle

class, 2164ViewColumn class, 2277

All function, 6, 15, 84, 101, 167AllChildren function, 101, 126, 167AllDescendants function, 101,

126, 168AllDocuments property

Database class, 1785NotesDatabase class, 794

AllEntries propertyNotesView class, 1461View class, 2218

ALOG.NTF file, 657Alternate names, 379, 381AMString property

International class, 2000NotesInternational class, 1019

And operatorFormula Language, 69

AppendDocLink methodNotesRichTextItem class, 1266RichTextItem class, 2153

AppendItemValue methodNotesDocument class, 942

appendItemValue methodDocument class, 1921

AppendParagraphStyle methodNotesRichTextItem class, 1268

appendParagraphStyle methodRichTextItem class, 2155

AppendRTItem methodNotesRichTextItem class, 1269RichTextItem class, 2155

AppendStyle methodNotesRichTextItem class, 1270RichTextItem class, 2156

AppendText methodNotesRichTextItem class, 1271RichTextItem class, 2157

AppendToTextList methodNotesItem class, 1048

appendToTextList methodItem class, 2035

AppletBase class, 1668Applets

running, 1593Arithmetic operators

Formula Language, 71LotusScript, 71table of, 113

Ascii function, 171Asin function, 114, 172Assignment operator

Formula Language, 70Atan function, 114, 173Atan2 function, 114, 174AttachmentDetachAll

command, 414AttachmentLaunch command, 414AttachmentLengths function,

126, 175AttachmentNames function, 126, 176AttachmentProperties

command, 414Attachments

appending in Java, 2157editing, 440getting in Java, 1933

Attachments function, 126, 176Author function, 126, 177Authors property

Document class, 1893NotesDocument class, 909

Index-7

Auto-commit modein LS:DO, 695

AutoCommit propertyODBCConnection class, 1098

AutoHorzFit command, 97AutoReload property

NotesUIDocument class, 1367AutoUpdate property

NotesView class, 1461AutoVertFit command, 97avoidingGUI method

Visibility interface, 1695

BBackgroundColor property

NotesView class, 1462View class, 2219

Backslash (\), 66Base Class box

defined, 36BeforeAddRow event, 1142BeforeClose event, 1143BeforeConnect event, 1104BeforeConnectTo event, 1104BeforeDeleteRow event, 1146BeforeDisconnect event, 1105BeforeExecute event, 1148BeforeFirstRow event, 1163BeforeGetParameter event, 1165BeforeGetParameterName

event, 1166BeforeGetValue event, 1170BeforeLastRow event, 1180BeforeListDataSources event, 1109BeforeListFields event, 1110BeforeListProcedures event, 1111BeforeListTables event, 1113BeforeLocateRow event, 1182BeforeNextRow event, 1184BeforeNumColumns event, 1185BeforePrevRow event, 1189BeforeRowPositionChange event,

1163, 1180, 1182, 1184, 1189BeforeSetParameter event, 1191BeforeSetSQL event, 1119BeforeSetValue event, 1193BeforeUpdateRow event, 1195Begins function, 109, 178Bind keyword, 551Block statements

Script Editor, 50

Bold propertyNotesRichTextStyle class, 1292RichTextStyle class, 2174

Boolean data type, 65Breakpoints

clearing, 54disabling, 54setting, 54using thebreakpoints panel, 55

BrowserInfo function, 179Button class, 784Buttons

as objects, 4as hotspots, 12for a script and formula, 85

CCacheLimit property

ODBCResultSet class, 1131Caches

in LS:DO, 697CacheSize property

ViewNavigator class, 2336CalendarDateTime property

NotesUIView class, 1422CalendarFormat command, 415CalendarGoTo command, 416Call statement, 552CanCreateDocuments property

NotesACLEntry class, 743CanCreateLSOrJavaAgent property

NotesACLEntry class, 744CanCreatePersonalAgent property

NotesACLEntry class, 745CanCreatePersonalFolder property

NotesACLEntry class, 746CanCreateSharedFolder property

NotesACLEntry class, 747CanDeleteDocuments property

NotesACLEntry class, 748Canonical property

Name class, 2067NotesName class, 1078

CaretCategory propertyNotesUIView class, 1423

Cascades, 81Case sensitive

ViewColumn class, 2286Cases

changing, 112Formula Language, 63

Catalog database, 2138

Categoriesaccessing with ViewEntry, 1628View class, 2227

Categories propertyDatabase class, 1786NotesDatabase class, 796

Categorize methodNotesUIDocument class, 1379

Certificate function, 181CertifierIDFile property

NotesRegistration class, 1225Registration class, 2114

CGI variables, 1310Changing

case, 112Char function, 105, 182CheckAlarms function, 183CheckAlarms method

NotesUIWorkspace class, 1431Child entries

ViewNavigator class, 2337ChildCount property

NotesViewEntry class, 1541ViewEntry class, 2306

ChooseFolders command, 416Chronos, 2143Class property

NotesEmbeddedObject class, 994Class statement

in a declaration, 49Classes

LotusScript, 545Classes tab

defined, 35ClassName property

EmbeddedObject class, 1980Classpath environment

variables, 1592Clear method

NotesRichTextTab class, 1303NotesUIDocument class, 1380NotesView class, 1479

clear methodRichTextTab class, 2182View class, 2239

ClearAllTabs methodNotesRichTextParagraphStyle

class, 1287clearAllTabs method

RichTextParagraphStyle class, 2169

ClearHistory methodNotesReplication class, 1257

Index-8

clearHistory methodReplication class, 2146

ClearingScript Editor, 42

Click eventButton class, 784Navigator class, 1087

ClientType function, 184Close method

NotesLog class, 1061NotesUIDocument class, 1381ODBCResultSet class, 1143

close methodLog class, 2051

Close Window, 455Code

locating within an object, 37Coding guidelines

Java classes, 1591LotusScript, 545

CollapseAllSections methodNotesUIDocument class, 1382

Collectionsaccessing with ViewEntry, 1629

Color propertyRichTextStyle class, 2174

ColorsView class, 2219ViewColumn class, 2280

Column formulas, 3, 16, 84, 123Column titles, 2302ColumnCount property

NotesView class, 1464View class, 2221

ColumnIndentLevel propertyNotesViewEntry class, 1542ViewEntry class, 2306

ColumnNames propertyView class, 2222

Columnsaccessing in Java, 1626accessing in LotusScript, 581getting in Java, 2257

Columns propertyNotesView class, 1464View class, 2222

ColumnValues propertyDocument class, 1895NotesDocument class, 911NotesViewEntry class, 1542ViewEntry class, 2307

Command function, 76, 101, 184Command statement, 551Commands, 397

Comment propertyAgent class, 1738NotesAgent class, 766NotesOutline class, 1198NotesTimer class, 1344Outline class, 2089

CommitOnDisconnect propertyODBCConnection class, 1099

CommitTransactions methodODBCConnection class, 1102

Common propertyName class, 2068NotesName class, 1078

CommonOwner propertyAgent class, 1739NotesAgent class, 767

CommonUserName propertyNotesSession class, 1307Session class, 2187

Compact methodNotesDatabase class, 825

compact methodDatabase class, 1814

Comparingstrings in a formula, 106

Comparison operatorsFormula Language, 72

Compile buttondefined, 35

CompilingJava, 44JavaScript, 48LotusScript, 50

ComponentsLotus, 715

Compose command, 417ComposeDocument method

NotesUIWorkspace class, 1431Computed field formulas, 24, 84Computed fields, 4ComputeWithForm method

NotesDocument class, 944computeWithForm method

Document class, 1923Concatenating

strings in a formula, 106Concatenation operator (+), 69Conditional statements

Notes, 90Conflicts

IsConflict property, 2228Connection property

ODBCQuery class, 1115

ConnectTo methodODBCConnection class, 1103

ConstantsFormula Language, 66time/date, 118

Contains function, 109, 186Contains method

NotesItem class, 1050containsValue method

Item class, 2037Converting

alphanumeric characters, 319, 390

Converting data typesin a formula, 105

ConvertToZone methodNotesDateTime class, 897

convertToZone methodDateTime class, 1874

Copy methodNotesUIDocument class, 1382

CopyAllItems methodNotesDocument class, 946

copyAllItems methodDocument class, 1925

Copyingtext in Script Editor, 42

CopyItem methodNotesDocument class, 947

copyItem methodDocument class, 1926

CopyItemToDocument methodNotesItem class, 1051

copyItemToDocument methodItem class, 2038

CopyToDatabase methodNotesDocument class, 948

copyToDatabase methodDocument class, 1928

Cos function, 114, 186Count property

DocumentCollection class, 1957NotesDocumentCollection

class, 977NotesViewEntryCollection

class, 1556ViewEntryCollection, 2316

Country propertyName class, 2068NotesName class, 1079

Create methodNotesDatabase class, 561, 826

CreateACLEntry methodNotesACL class, 734

Index-9

createACLEntry methodACL class, 1703

CreateAction command, 418CreateAgent command, 418CreateControlledAccessSection

command, 419CreateCopy method

NotesDatabase class, 561, 827createCopy method

Database class, 1815Created function, 118, 187Created property

Database class, 1787Document class, 1896NotesDatabase class, 796NotesDocument class, 912NotesView class, 1465View class, 2223

createDatabase methodDbDirectory class, 1881

CreateDateRange methodNotesSession class, 1323

createDateRange methodSession class, 2195

CreateDateTime methodNotesSession class, 1323

createDateTime methodSession class, 2196

CreateDocument methodNotesDatabase class, 829

createDocument methodDatabase class, 1816

CreateEllipse command, 419CreateEntry method

NotesOutline class, 1200createEntry method

Outline class, 2090CreateFolder command, 419CreateForm command, 420CreateFromTemplate method

NotesDatabase class, 561, 830createFromTemplate method

Database class, 1817CreateLayoutRegion command, 420CreateLog method

NotesSession class, 1324createLog method

Session class, 2197CreateMailDb property

NotesRegistration class, 1225Registration class, 2114

CreateName methodNotesSession class, 1325

createName methodSession class, 2197

CreateNavigator command, 420CreateNewsletter method

NotesSession class, 1327createNewsletter method

Session class, 2198CreateObject method

NotesUIDocument class, 1383CreateOutline method

NotesDatabase class, 831createOutline method

Database class, 1819CreatePolygon command, 421CreatePolyline command, 421CreateRectangle command, 421CreateRectangularHotspot

command, 422createRegistration method

Session class, 2198CreateReplica method

NotesDatabase class, 561, 832createReplica method

Database class, 1820CreateReplyMessage method

NotesDocument class, 949createReplyMessage method

Document class, 1929CreateRichTextItem method

NotesDocument class, 950createRichTextItem method

Document class, 1930CreateRichTextParagraphStyle

methodNotesSession class, 1328

createRichTextParagraphStylemethod

Session class, 2199CreateRichTextStyle method

NotesSession class, 1329createRichTextStyle method

Session class, 2199CreateSection command

Formula Language, 422createSession method

NotesFactory class, 1594, 1691CreateSubForm command, 422CreateTextbox command, 423CreateTimer method

NotesSession class, 1329CreateView command, 423CreateViewNav method

NotesView class, 1480

createViewNav methodView class, 2239

CreateViewNavFrom methodNotesView class, 1481

createViewNavFrom methodView class, 2241

CreateViewNavFromCategorymethod

NotesView class, 1482createViewNavFromCategory

methodView class, 2242

CreateViewNavFromChildrenmethod

NotesView class, 1483createViewNavFromChildren

methodView class, 2244

CreateViewNavFromDescendantsmethod

NotesView class, 1483createViewNavFromDescendants

methodView class, 2245

createViewNavMaxLevel methodView class, 2247

Creatinga full text index, 460script in Script Editor, 49

CrossCertify methodNotesRegistration class, 1234

crossCertify methodRegistration class, 2123

Currency formatsViewColumn class, 2299

CurrencyDigits propertyInternational class, 2001NotesInternational class, 1020

CurrencySymbol propertyInternational class, 2001NotesInternational class, 1020

Current documentaccessing in LotusScript, 603

Current documentsaccessing, 125

Current entryViewNavigator class, 2340

Current pointerNotesDocumentCollection

class, 976CurrentAccessLevel property

Database class, 1788NotesDatabase class, 797

Index-10

CurrentAgent propertyAgentContext class, 1759NotesSession class, 1308

CurrentCalendarDateTime propertyNotesUIWorkspace class, 1428

CurrentDatabase propertyAgentContext class, 1760NotesSession class, 1309NotesUIWorkspace class, 1428

CurrentDocument propertyNotesUIWorkspace class,

603, 1429CurrentField property

NotesUIDocument class, 1368CurrentRow property

ODBCResultSet class, 1133CurrentView property

NotesUIWorkspace class, 1430Cut method

NotesUIDocument class, 1384Cutoff deletes, 2135CutoffDate property

NotesReplication class, 1247Replication class, 2134

CutoffDelete propertyNotesReplication class, 1248

CutoffInterval propertyNotesReplication class, 1248Replication class, 2135

Cutting textScript Editor, 42

DData sources

connecting to with LS:DO, 667Data types

@functions, 76Formula Language, 63

Database.FT_STEMS constant, 1769Database class, 1776Database property

NotesOutlineEntry class, 1209NotesUIDatabase class, 1351OutlineEntry class, 2101

DatabaseReplSettings command, 423Databases

accessing in Formula Language, 122

accessing in Java, 1603accessing in LotusScript, 553closing in Java, 1610closing in LotusScript, 558compacting and converting, 455

copying, 456copying in Java, 1815creating in Java, 1614creating in LotusScript, 561deleting, 456displaying ACL, 455locating in Java, 1609new, 463new replica, 463opening in Java, 1610opening in LotusScript, 558properties in Java, 1603properties in LotusScript, 554removing, 457removing in Java, 1614replication settings, 570searching for, 557switch server, 457using replica ID, 466using server, 464

DataSourceName propertyODBCConnection class, 1100

Dateformatting, 68

Date function, 119, 188DateFmt property

NotesViewColumn class, 1510ViewColumn class, 2278

DateOnly propertyDateTime class, 1858NotesDateTime class, 883

DateRange class, 1654, 1849Dates

in LotusScript, 655DateSep property

International class, 2002NotesInternational class, 1021

DateTime class, 1654, 1854DateTimeValue property

Item class, 2016NotesItem class, 1033

Day function, 118, 190DbColumn function, 76, 128

Notes database, 101, 190ODBC, 131, 195

DbCommand function, 131OBDC, 201

DBCS, 319DbDirectory class, 1609, 1879DbExists function, 206DbLookup function, 76, 102, 128,

131, 207, 214DbManager function, 122, 220DbName function, 122, 221

DbTitle function, 222DDEExecute function, 76, 223DDEInitiate function, 76, 225DDEPoke function, 76, 227DDETerminate function, 76, 228Debugger

debugger utilities, 55Debugging

a formula, 81breakpoints, 54Java agent, 45LotusScript, 51

DebugLotusScript command, 424Decimals

Formula Language, 67DecimalSep property

International class, 2004NotesInternational class, 1022

Declarationsin Script Libraries, 57

Default keyword, 79, 125, 229Default validation formulas, 84Default value formulas, 4, 23, 84Default views

View class, 2228Defining

global variable and subprogram, 48

Deftype statementScript Area, 49

Delay updatesisDelayUpdates method, 1794

DelayUpdates propertyNotesDatabase class, 799

Delete old documents, 2135DeleteDocument function, 102, 229DeleteDocument method

NotesDocumentCollection class, 980

NotesUIDocument class, 1385deleteDocument method

DocumentCollection class, 1962DeleteEntry method

NotesViewEntryCollection class, 1558

deleteEntry methodViewEntryCollection class, 2318

DeleteField function, 102, 125, 230DeleteIDOnServer method

NotesRegistration class, 1235deleteIDOnServer method

Registration class, 2123DeleteRole method

NotesACL class, 735

Index-11

deleteRole methodACL class, 1704

DeleteRow methodODBCResultSet class, 1145

Deletinga field, 64, 125, 230, 369a full text index, 460

Deletions, 2140, 2141DescendantCount property

NotesViewEntry class, 1543ViewEntry class, 2308

DeselectAll methodNotesUIDocument class, 1386

Deselectingtext, 42

Design hide, 2139DesignDocumentInfo command, 424DesignFormAttributes

command, 424DesignFormFieldDef command, 425DesignFormNewField

command, 425DesignForms command, 425DesignFormShareField

command, 425DesignFormUseField command, 426DesignFormWindowTitle

command, 426DesignHelpAboutDocument

command, 426DesignHelpUsingDocument

command, 427DesignIcon command, 427DesignMacros command, 427DesignRefresh command, 428DesignReplace command, 428DesignSharedFields command, 428DesignSynopsis command, 429DesignTemplateName property

Database class, 1790NotesDatabase class, 799

DesignViewAppendColumncommand, 429

DesignViewAttributes command, 429

DesignViewColumnDef command, 429

DesignViewEditActions command,430

DesignViewFormFormulacommand, 430

DesignViewNewColumn command, 430

DesignViews command, 430DesignViewSelectFormula

command, 431DialingRules command, 431DialogBox function, 76, 96, 230DialogBox method

NotesUIWorkspace class, 1433DialogBoxCanceled property

NotesUIDocument class, 1369DIIOP server tasks, 1591Dim statement

Script Area, 49Disable replication, 2136, 2143Disabled property

NotesReplication class, 1249DisableRole method

NotesACLEntry class, 761disableRole method

ACLEntry class, 1732Disabling

@Commands, 77Disconnect method

ODBCConnection class, 1105Distinguished names, 315Dividing, 113Division operator (/)

Formula Language, 69, 71Do function, 78, 233Do not browse method, 2137Do not catalog method, 2138DocChildren function, 102, 124, 234DocDescendants function, 102,

123, 236DocFields function, 126, 238DocLength function, 126, 238DocLevel function, 102, 123, 239Doclinks

appending in Java, 2153DocMark function, 102, 126, 240DocNumber function, 102, 123, 240DocParentNumber function, 102,

123, 241DocSiblings function, 102, 123, 242Document class, 1631, 1889Document property

NotesOutlineEntry class, 1209NotesUIDocument class, 1370NotesViewEntry class, 1544OutlineEntry class, 2101ViewEntry class, 2308

DocumentCollection class, 1635, 1954

DocumentContext propertyAgentContext class, 1769Java, 1761NotesSession class, 1310

Documentsaccessing, 575accessing current, 603accessing in Formula Language,

125, 128accessing in Java, 1631Accessing in LotusScript, 575accessing in LotusScript, 599accessing properties in Java, 1632accessing through a view in

LotusScript, 615accessing with ViewEntry, 1628adding in LotusScript, 614collecting all in Java, 1635collecting all in LotusScript, 610copying in Java, 1640copying in LotusScript, 622creating in Java, 1639creating in LotusScript, 621deleting in LotusScript, 621getting all in Java, 1785locating in Java, 1638locating in LotusScript, 614locating within a view in

LotusScript, 617LotusScript properties, 599mailing in Java, 1640mailing in LotusScript, 623removing in Java, 1639removing in LotusScript, 622searching for in Java, 1637searching for in LotusScript, 612

Documents propertyNotesUIDatabase class, 1352NotesUIView class, 1424

DocumentUniqueID function, 126, 243

Domain function, 246Domain Search

FTDomainSearch method in Java, 1822

Domino classesA-Z reference, 1661LotusScript, 545

Domino DirectoriesisPublicAddressBook

method, 1800Domino logs

openNotesLog method, 2060

Index-12

Domino objectstable, 3

DominoAsynchronizeAgentsstatement, 665

DoNoBrowse propertyNotesReplication class, 1250

DoNotCatalog propertyNotesReplication class, 1251

DoScore propertyNotesNewsletter class, 1090

DoSubject propertyNotesNewsletter class, 1091

Double item valuesgetting in Java, 1938

DoVerb methodNotesEmbeddedObject

class, 1005doVerb method

EmbeddedObject class, 1984Driver Manager for ODBC, 667

EECL security

@Commands, 397@Functions, 153Java, 1661LotusScript, 721

Edit Project buttondefined, 35

EditBottom command, 431EditButton command, 432EditClear command, 432EditCopy command, 432EditCut command, 433EditDeselectAll command, 433EditDetach command, 434EditDocument command, 435EditDocument method

NotesUIWorkspace class, 1437EditDown command, 436EditECL function, 246EditEncryptionKeys command, 436EditFind command, 437EditFindInPreview command, 437EditFindNext command, 438EditGotoField command, 438EditHeaderFooter command, 439EditHorizScrollbar command, 439EditIndent command, 439EditIndentFirstLine command, 440Editing text

in the Script Area, 40

EditInsertButton command, 440EditInsertFileAttachment

command, 440EditInsertObject command, 441EditInsertPageBreak command, 442EditInsertPopup command, 442EditInsertTable command, 443EditInsertText command, 443EditLeft command, 444EditLinks command, 444EditLocations command, 445EditMakeDocLink command, 445EditMode property

NotesUIDocument class, 1371EditNextField command, 445EditOpenLink command, 445EditPaste command, 446EditPasteSpecial command, 446EditPhoneNumbers command, 446EditPrevField command, 447EditProfile command, 447EditProfile method

NotesUIWorkspace class, 1438EditResizePicture command, 448EditRight command, 449EditSelectAll command, 449EditSelectByDate command, 450EditShowHideHiddenChars

command, 450EditTableDeleteRowColumn

command, 450EditTableFormat command, 451EditTableInsertRowColumn

command, 451EditTop command, 452EditUndo command, 452EditUntruncate command, 452EditUp command, 453EditUserECL function, 247EffectiveUserName property

AgentContext class, 1762NotesSession class, 1313

Effects propertyNotesRichTextStyle class, 1293RichTextStyle class, 2175

Elements function, 87, 247Embedded objects

accessing in Java, 1646appending in Java, 2157getting in Java, 2149, 2159hasEmbedded method, 1901in LotusScript, 640

EmbeddedObject class, 1646, 1978EmbeddedObjects property

Document class, 1897NotesDocument class, 913NotesRichTextItem class, 1261RichTextItem class, 2149

EmbedObject methodNotesRichTextItem class, 1271

embedObject methodRichTextItem class, 2157

Emboss effectNotesRichTextStyle class, 1293RichTextStyle class, 2175

Empty strings, 367EmptyTrash command, 453EnableAlarms function, 248EnableAlarms method

NotesUIWorkspace class, 1439Enabled property

NotesTimer class, 1344EnableFolder method

NotesDatabase class, 833enableFolder method

Database class, 1821EnableRole method

NotesACLEntry class, 762enableRole method

ACLEntry class, 1733Enabling

breakpoints, 55Encrypt method

NotesDocument class, 951encrypt method

Document class, 1931Encrypt on send

Document class, 1902EncryptionKeys property

Document class, 1899NotesDocument class, 915

EncryptOnSend propertyNotesDocument class, 916

EndDateTime propertyDateRange class, 1852NotesDateRange class, 877

Ends function, 109, 248Entering event

Field class, 1007EntryClass property

NotesOutlineEntry class, 1210OutlineEntry class, 2102

Environment function, 97, 102, 250Environment keyword, 79, 102, 249

Index-13

Environment variables, 97accessing in Java, 1649getting in Java, 2205, 2207in LotusScript, 649setting in Java, 2210

Equals operator (=)Formula Language, 69

Error function, 99, 253Error handling

in LotusScript, 698ODBC, 693

Errorshandling, 98handling in Java, 1669logError method, 2053no main or selection expression

in formula, 258run-time in a formula, 99saving LotusScript with, 50syntax in a formula, 99when compiling, 50

Errors boxdefined, 34using, 39

Escape character (~), 66evaluate method

Session class, 2200Evaluate statement

in Domino, 549Event handling

ODBC, 690Event sequences

table, 29Events

in a database, 19in a field, 19in a form, 19in a view, 19logEvent method, 2055overview, 3, 25Sequencing, 29

Examples@Commands, 401, 418, 434, 435,

441, 442, 443, 444, 448, 449,453, 454, 459, 463, 465, 467,472, 497, 500, 516, 517, 520,523, 532

@Functions, 154, 178, 189, 195,247, 264, 278, 284, 294, 316,337, 347, 361, 363, 364, 365,366, 367, 368, 369, 385

access control list, 566, 1618accessing a Notes agent, 651

accessing a view or foldercolumn, 583

accessing an external database, 132

accessing outside data, 130accessing the current database

and view, 124accessing the current document,

127, 607adding a new line, 112arithmetic operation, 115changing case, 112collecting all documents, 1636collecting documents by

searching, 1637collecting unprocessed

documents, 611compacting a database, 1614concatenating, 107converting a data type, 106converting between Notes and

LotusScript time, 656copying an item, 633creating a database, 561, 1614creating a document, 621creating an item in Formula

Language, 631database properties in Formula

Language, 556database properties in Java, 1606Default keyword, 229document properties, 602, 1634environment variables, 649error handling, 713Evaluate statement, 550filling out form with

@DialogBox, 97form formula, 15getting an item and its value, 628getting and setting environment

variables, 98getting user input with

@Prompt, 96hidden paragraph formula, 19input translation formula, 23input validation formula, 23insert subform formula, 18item properties, 626, 1642keyword field formula, 25lexical elements, 62locating a database, 557, 1609locating a document by ID,

614, 1638

locating a document within aview, 617

locating a view, 1625locating a view and folder, 580locating and extracting

substring, 110opening and closing a database,

558, 1610performing time-date

operation, 119removing a database, 1614removing a document, 622removing a view and folder, 585removing an item, 634repeating, 112replicating a database, 1614run-time errors, 100section access formula, 18section title formula, 19selection formula, 15SmartIcons, 5text constants, 66trimming, 112user environment, 121using a conditional statement, 92using an OCX control, 717using keywords, 79value formula, 24view and folder properties,

579, 1623window title formula, 17working with a list, 88working with an embedded

object, 640working with rich text item, 637writing a button script or

formula, 12writing a default value

formula, 23writing a replication formula, 6writing a script and a formula, 20writing a script for an action, 10writing a script for an agent, 7writing an @function with a

result, 85writing an action formula, 86writing formula for an agent, 7writing message with

@Prompt, 93writing script/formula for an

action, 10Exceptions

handling in Java, 1669

Index-14

ExchangeUnreadMarks command, 454

ExecProcedure MethodODBCResultSet class, 1147

Execute command, 454Execute method

ODBCResultSet class, 1147Execute statement, 552Exiting

a file, 457Exiting event

Field class, 1007Exp function, 114, 254ExpandAllSections method

NotesUIDocument class, 1387Expiration property

NotesRegistration class, 1226Registration class, 2115

Explode function, 87, 254Exploring

Java interface, 35LotusScript debugger, 51Programmer's pane, 33

Export buttondefined, 35

Exportinga file, 458text in Formula Language, 42text in Script Editor, 42

External databasesaccessing in LotusScript, 661

ExtractFile methodNotesEmbeddedObject class,

1005extractFile method

EmbeddedObject class, 1985Extrude effect

NotesRichTextStyle class, 1293RichTextStyle class, 2175

FFailure function, 99, 102, 257False function, 257FetchBatchSize property

ODBCResultSet class, 1135Field class, 1007Field design formulas

writing, 22Field function, 102Field keyword, 65, 79, 125, 258Field values

Formula Language, 64

FieldAppendText methodNotesUIDocument class, 1387

FieldClear methodNotesUIDocument class, 1389

FieldContains methodNotesUIDocument class, 1390

FieldExpectedDataType methodODBCResultSet class, 1149

FieldGetText methodNotesUIDocument class, 1391

FieldHelp propertyNotesUIDocument class, 1372

FieldID methodODBCResultSet class, 1153

FieldInfo methodODBCResultSet class, 1154

FieldName methodODBCResultSet class, 1158

FieldNativeDataType methodODBCResultSet class, 1159

Fieldsaccessing in Formula

Language, 125Formula Language, 63

Fields propertyForm class, 1989NotesForm class, 1010

FieldSetText methodNotesUIDocument class, 1392

FieldSize methodODBCResultSet class, 1161

File attachmentsediting, 440

FileCloseWindow command, 455FileDatabaseACL command, 455FileDatabaseCompact

command, 455FileDatabaseCopy command, 456FileDatabaseDelete command, 456FileDatabaseInfo command, 456FileDatabaseRemove command, 457FileDatabaseUseServer

command, 457FileExit command, 457FileExport command, 458FileFullTextCreate command, 460FileFullTextDelete command, 460FileFullTextInfo command, 460FileFullTextUpdate command, 461FileImport command, 461FileName property

Database class, 1791NotesDatabase class, 801

FileNewDatabase command, 463FileNewReplica command, 463FileOpenDatabase command, 464FileOpenDBRepID command, 466FilePageSetup command, 467FilePath property

Database class, 1791NotesDatabase class, 801

FilePrint command, 468FilePrintSetup command, 470Files

closing in LotusScript, 548extracting in Java, 1985printing, 468saving, 470saving a new version, 470

FileSave command, 470FileSaveNewVersion command, 470FileSize property

EmbeddedObject class, 1981NotesEmbeddedObject class, 995

FindFreeTimeDialog command, 471FindFreeTimeDialog method

NotesUIDocument class, 1393FindFreeTimeDialogEx method

NotesUIDocument class, 1395Finding

text in Script Editor, 42FindString method

NotesUIDocument class, 1397FirstLineLeftMargin property

NotesRichTextParagraphStyleclass, 1279

RichTextParagraphStyle class, 2165

FirstRow methodODBCResultSet class, 1162

FitBelowFields propertyNotesEmbeddedObject class, 996

FitToWindow propertyNotesEmbeddedObject class, 997

Fixed formatsViewColumn class, 2299

Folder command, 472Folder method

NotesUIWorkspace class, 1439FolderCollapse command, 473FolderCustomize command, 473FolderExpand command, 474FolderExpandAll command, 474FolderExpandWithChildren

command, 474FolderMove command, 475

Index-15

FolderProperties command, 475FolderReferences property, 1900

Document class, 1899NotesDocument class, 917

FolderReferencesEnabled propertyDatabase class, 1792NotesDatabase class, 802

FolderRename command, 475Folders

accessing properties in Java, 1621accessing properties in

LotusScript, 578locating in Java, 1625locating in LotusScript, 580, 615removing in Java, 1631

Font propertyRichTextStyle class, 2176

FontColor propertyNotesViewColumn class, 1510ViewColumn class, 2280

FontFace propertyNotesViewColumn class, 1512ViewColumn class, 2282

FontList function, 259FontPointSize property

NotesViewColumn class, 1512ViewColumn class, 2283

FontSize propertyNotesRichTextStyle class, 1294RichTextStyle class, 2177

FontStyle propertyNotesViewColumn class, 1513ViewColumn class, 2283

Form class, 1619, 1986Form fields

Formula Language, 64Form formulas, 3, 15, 84FormActions command, 476FormatDocument method

NotesNewsletter class, 1092formatDocument method

Newsletter class, 2081FormatMsgWithDoclinks method

NotesNewsletter class, 1094formatMsgWithDoclinks method

Newsletter class, 2083Formatted text

getting in Java, 2160Formatting

in the Script Area, 39time and date, 67

Formsaccessing in Java, 1619accessing in LotusScript, 575

filling out, 96naming in a formula, 81

Forms propertyDatabase class, 1794NotesDatabase class, 804

FormTestDocument command, 476Formula language

@functions, 75coding guidelines, 83constants, 66debugging, 81fields, 63icon, 38in LotusScript, 549in the Programmer's pane, 58keywords, 79lexical elements, 61list operations, 72numeric constants, 67overview, 1precedence, 69rules, 61syntax, 61temporary variables, 65text constants, 66time/date constants, 67using an operator, 68variables, 63

Formula operations, order ofevaluation, 70

Formula propertyNotesOutlineEntry class, 1210NotesViewColumn class, 1514OutlineEntry class, 2102ViewColumn class, 2284

Formula windowsusing, 58Programmer's pane, 58

Formulasentering, 58hiding, 498in the Programmer's pane, 58performing an action, 85refreshing, 498result of, 84using, 83versus a script, 1where to use, 1writing, 6

Formulas for SmartIconswriting, 5

FormUsers field, 1011

FormUsers propertyForm class, 1990NotesForm class, 1011

Forward methodNotesUIDocument class, 1398

FrameSetTargetFrame, 354

Framesetdefinition, 494

FrameText propertyNotesOutlineEntry class, 1211OutlineEntry class, 2103

FreeTimeSearch methodNotesSession class, 1331

freeTimeSearch methodSession class, 2202

FT_DATE_ASC constant, 834, 836,864, 1769, 1822, 1824

FT_DATE_DES constant, 834, 836,864, 1769, 1822, 1824

FT_SCORES constant, 834, 836, 864,1769, 1822, 1824

FT_STEMS constant, 834, 836, 865,1769, 1822, 1824

FTDomainSearch methodDatabase class, 1822NotesDatabase class, 834

FTSearch methodDatabase class, 1823DocumentCollection class, 1964NotesDatabase class, 835NotesDocumentCollection

class, 981NotesView class, 1484NotesViewEntryCollection

class, 1559View class, 2248ViewEntryCollection class, 2320

FTSearchScore propertyDocument class, 1900NotesDocument class, 919NotesViewEntry class, 1544ViewEntry class, 2309

Full-text indexesisFTIndexed method, 1796updateFTIndex method, 1848

Full-text searchesclearing in Java, 2239FTDomainSearch method in

Java, 1822FTSearch method in Java, 1823FTSearchScore property, 1900in Java, 1637, 2248in LotusScript, 613, 616

Index-16

Full text indexescreating, 460deleting, 460infomation, 460updating, 461

Functionrenaming, 43

Function blockScript Area, 49

Functionscalling, 552

GgetIndentLevel method

ViewEntry, 2309ViewEntry class, 2306

General formatsViewColumn class, 2299

Generation propertyJava, 2068NotesName class, 1079

getAbbreviated methodName class, 2065

getACL methodDatabase class, 1783

getAddr821 methodName class, 2065

getAddr822Comment1 methodName class, 2065

getAddr822Comment2 methodName class, 2066

getAddr822Comment3 methodName class, 2066

getAddr822LocalPart methodName class, 2066

getAddr822Phrase methodName class, 2067

getAddressBooks methodSession class, 2185

getADMD methodName class, 2067

GetAgent methodNotesDatabase class, 838

getAgent methodDatabase class, 1826

getAgentContext methodSession class, 2187

getAgentOutput method, 1594AgentBase class, 1668

getAgents methodDatabase class, 1784

getAlias methodOutline class, 2088OutlineEntry, 2100

getAliases methodForm class, 1988View class, 2217

getAlignment methodRichTextParagraphStyle

class, 2164ViewColumn class, 2277, 2285

getAllDocuments methodDatabase class, 1785

GetAllDocumentsByKey methodNotesView class, 1486

getAllDocumentsByKey methodView class, 2251

getAllEntries methodView class, 2218

GetAllEntriesByKey methodNotesView class, 1488

getAllEntriesByKey methodView class, 2253

getAMString methodInternational class, 2000

GetAttachment methodNotesDocument class, 952

getAttachment methodDocument class, 1933

getAuthors methodDocument class, 1893

getBackgroundColor methodView class, 2219

getBold methodRichTextStyle class, 2174

getCacheSize methodViewNavigator class, 2336

getCanonical methodName class, 2067

getCategories methodDatabase class, 1786

getCertifierIDFile methodRegistration class, 2114

GetChild methodNotesView class, 1489NotesViewNavigator class, 1574

getChild methodView class, 2256ViewNavigator class, 2337

getChildCount methodViewEntry class, 2306

getClassName methodEmbeddedObject class, 1980

getColor methodRichTextStyle class, 2174

getColumn methodView class, 2257

getColumnCount methodView class, 2221

getColumnIndentLevel methodViewEntry class, 2306

getColumnNames methodView class, 2222

getColumns methodView class, 2222

getColumnValues methodDocument class, 1895ViewEntry class, 2307

getComment methodAgent class, 1738Outline class, 2089

getCommon methodName class, 2068

getCommonOwner methodAgent class, 1739

getCommonUserName methodSession class, 2187

getCount methodDocumentCollection class, 1957ViewEntryCollection, 2316

getCountry methodName class, 2068

getCreated methodDatabase class, 1787Document class, 1896View class, 2223

getCreateMailDb methodRegistration class, 2114

getCurrencyDigits methodInternational class, 2001

getCurrencySymbol methodInternational class, 2001

getCurrent methodViewNavigator class, 2340

getCurrentAccessLevel methodDatabase class, 1788

getCurrentAgent methodAgentContext class, 1759

getCurrentDatabase methodAgentContext class, 1760

getCutoffDate method, 2134Replication class, 2134

getCutoffInterval method, 2135Replication class, 2135

GetDatabase methodNotesSession class, 1333

Index-17

getDatabase methodOutlineEntry class, 2101Session class, 2203

getDateFmt methodViewColumn class, 2278

getDateOnly propertyDateTime class, 1858

getDateSep methodInternational class, 2002

getDateTimeValue methodItem class, 2016

GetDbDirectory methodNotesSession class, 1334

getDbDirectory methodSession class, 2204

getDecimalSep methodyInternational class, 2004

getDescendantCount methodViewEntry class, 2308

getDesignTemplateName methodDatabase class, 1790

GetDocField function, 129, 259GetDocument method

NotesDocumentCollection class, 982

getDocument methodDocumentCollection class, 1965OutlineEntry class, 2101ViewEntry class, 2308

GetDocumentByID methodNotesDatabase class, 839

getDocumentByID methodDatabase class, 1827

GetDocumentByKey methodNotesView class, 1490

getDocumentByKey methodView class, 2258

GetDocumentByUNID methodNotesDatabase class, 841

getDocumentByUNID methodDatabase class, 1828

GetDocumentByURL methodNotesDatabase class, 842

getDocumentByURL methodDatabase class, 1830

getDocumentContext method, 1761AgentContext class, 1769

getEffectiveUserName methodAgentContext class, 1762

getEffects methodRichTextStyle class, 2175

GetEmbeddedObject methodNotesRichTextItem class, 1274

getEmbeddedObject methodRichTextItem class, 2159

getEmbeddedObjects methodDocument class, 1897RichTextItem class, 2149

getEndDateTime methodDateRange class, 1852

GetEntry methodNotesACL class, 736NotesViewEntryCollection

class, 1560NotesViewNavigator class, 1575

getEntry methodACL class, 1705ViewEntryCollection class, 2321

GetEntryByKey methodNotesView class, 1493

getEntryByKey methodView class, 2260

getEntryClass methodOutlineEntry class, 2102

GetEnvironmentString methodNotesSession class, 1335

getEnvironmentString methodSession class, 2205

GetEnvironmentValue methodNotesSession class, 1336

getEnvironmentValue methodSession class, 2207

GetError methodODBCConnection class, 1106ODBCQuery class, 1121ODBCResultSet class, 1164

GetErrorMessage methodODBCConnection class, 1106ODBCQuery class, 1121ODBCResultSet class, 1164

getExpiration methodRegistration class, 2115

GetExtendedErrorMessage methodODBCConnection class, 1106ODBCQuery class, 1127ODBCResultSet class, 1164

getFields methodForm class, 1989

getFileName methodDatabase class, 1791

getFilePath methodDatabase class, 1791

getFileSize methodEmbeddedObject class, 1981

GetFirst methodNotesOutline class, 1200NotesViewNavigator class, 1576

getFirst methodOutline class, 2091ViewNavigator class, 2340

GetFirstDatabase methodNotesDbDirectory class, 557, 902

getFirstDatabase methodDbDirectory class, 1883

GetFirstDocument methodNotesDocumentCollection

class, 983NotesView class, 1494NotesViewNavigator class, 1577

getFirstDocument methodDocumentCollection class, 1967View class, 2262ViewNavigator class, 2342

GetFirstEntry methodNotesACL class, 737NotesViewEntryCollection

class, 1561getFirstEntry method

ACL class, 1707ViewEntryCollection class, 2323

GetFirstItem methodNotesDocument class, 953

getFirstItem methodDocument class, 1934

getFirstLineLeftMargin methodRichTextParagraphStyle

class, 2165getFolderReferences method, 1900

Document class, 1899getFolderReferencesEnabled method

Database class, 1792getFont method

RichTextStyle class, 2176getFontColor method

ViewColumn class, 2280getFontFace method

ViewColumn class, 2282getFontPointSize method

ViewColumn class, 2283getFontSize method

RichTextStyle class, 2177getFontStyle method

ViewColumn class, 2283GetForm method

NotesDatabase class, 844getForm method

Database class, 1794, 1832GetFormattedText method

NotesRichTextItem class, 1276getFormattedText method

RichTextItem class, 2160

Index-18

getFormula methodOutlineEntry class, 2102ViewColumn class, 2284

getFormUsers methodForm class, 1990

getFrameText methodOutlineEntry class, 2103

getFTSearchScore methodDocument class, 1900ViewEntry class, 2309

getGeneration method, 2068getGiven method

Name class, 2069getGMTTime method

DateTime class, 1859getHeaderLines method

View class, 2224GetIDFromServer method

NotesRegistration class, 1236getIDFromServer method

Registration class, 2124getIDType method

Registration class, 2115getImagesText method

OutlineEntry class, 2105getInitials method

Name class, 2069getInterLineSpacing method

RichTextParagraphStyle class, 2165

getInternational methodSession class, 2188

getInternetLevel methodACL class, 1697

getIOR methodNotesFactory class, 1691

getItalic methodRichTextStyle class, 2177

getItemName methodViewColumn class, 2296

getItems methodDocument class, 1910

GetItemValue method, 956getItemValue method

Document class, 1936getItemValueDouble method

Document class, 1938getItemValueInteger method

Document class, 1938getItemValueString method

Document class, 1939getKey method

Document class, 1911

getKeyword methodName class, 2070

getLabel methodOutlineEntry class, 2107

getLanguage methodName class, 2070

GetLast methodNotesOutline class, 1201NotesViewNavigator class, 1578

getLast methodOutline class, 2092ViewNavigator class, 2343

getLastAccessed propertyDocument class, 1911

GetLastDocument methodNotesDocumentCollection

class, 984NotesView class, 1495NotesViewNavigator class, 1579

getLastDocument methodDocumentCollection class, 1967View class, 2263ViewNavigator class, 2345

GetLastEntry methodNotesViewEntryCollection

class, 1562getLastEntry method

ViewEntryCollection class, 2324getLastExitStatus method

AgentContext class, 1763getLastFTIndexed method

Database class, 1801getLastModified method

Database class, 1802Document class, 1912Item class, 2024View class, 2233

getLastRun methodAgent class, 1744

getLastRun sessionAgentContext class, 1764

getLeftMargin methodRichTextParagraphStyle

class, 2166getLevel method

ACLEntry class, 1724OutlineEntry class, 2107

GetListOfTunes methodNotesUIWorkspace class, 1440

getListSep propertyViewColumn class, 2297

getLocalTime methodDateTime class, 1861

GetLSDOMasterRevision propertyODBCConnection class, 1101

getManagers methodDatabase class, 1803

getMaxLevel methodViewNavigator class, 2336

getMaxSize methodDatabase, 1804Database class, 1803

getMinPasswordLength methodRegistration class, 2116

GetName methodView class, 2234

getName methodACLEntry class, 1726Agent class, 1746DbDirectory class, 1880EmbeddedObject class, 1981Form class, 1995Item class, 2024Outline class, 2089

getNamedElement methodOutlineEntry class, 2107

getNameObject methodACLEntry class, 1727

getNameOfProfile methodDocument class, 1912

GetNext methodNotesOutline class, 1202NotesViewNavigator class, 1579

getNext methodOutline class, 2093ViewNavigator class, 2346

GetNextCategory methodNotesViewNavigator class, 1580

getNextCategory methodViewNavigator class, 2346

GetNextDatabase methodNotesDbDirectory class, 557, 903

getNextDatabase methodDbDirectory class, 1884

GetNextDocument methodNotesDocumentCollection

class, 984NotesView class, 1496NotesViewNavigator class, 1581

getNextDocument methodDocumentCollection class, 1967View class, 2264ViewNavigator class, 2347

GetNextEntry methodNotesACL class, 738NotesViewEntryCollection

class, 1563

Index-19

getNextEntry methodACL class, 1708ViewEntryCollection, 2325

GetNextSibling methodNotesOutline class, 1202NotesView class, 1497NotesViewNavigator class, 1582

getNextSibling methodOutline class, 2093View class, 2266ViewNavigator class, 2348

getNoChronos method, 2143getNoteID method

Document class, 1912ViewEntry class, 2312

getNotesVersion methodSession class, 2190

GetNth methodNotesViewNavigator class, 1583

getNth methodViewNavigator class, 2349

GetNthDocument methodNotesDocumentCollection

class, 985NotesView class, 1499

getNthDocument methodDocumentCollection class, 1969View class, 2267

GetNthEntry methodNotesViewEntryCollection

class, 1564getNthEntry method

ViewEntryCollection, 2326getNumActions method

Log class, 2048getNumberAttrib property

ViewColumn class, 2297getNumberDigits property

ViewColumn class, 2299getNumErrors method

Log class, 2049GetObject method

NotesUIDocument class, 1399getObject method

EmbeddedObject class, 1982getOrganization method

Name class, 2074getOrgUnit method

Registration class, 2117getOrgUnit1 method

Name class, 2074getOrgUnit2 method

Name class, 2074

getOrgUnit3 methodName class, 2075

getOrgUnit4 methodName class, 2075

GetOutline methodNotesDatabase class, 845

getOutline methodDatabase class, 1833

getOwner methodAgent class, 1746

getPagination methodRichTextParagraphStyle

class, 2166GetParameter method

ODBCResultSet class, 1164GetParameterName method

ODBCResultSet class, 1166GetParent method

NotesOutline class, 1203NotesViewNavigator class, 1584

getParent method, 2075ACL class, 1700ACLEntry class, 1728Agent class, 1747Database class, 1805DateRange class, 1853DateTime class, 1863DbDirectory class, 1881DocumentCollection class, 1959EmbeddedObject class, 1982International class, 2009Item class, 2024Newsletter class, 2080Outline class, 2094RichTextStyle class, 2178View class, 2235ViewEntry class, 2312ViewEntryCollection, 2316ViewNavigator class, 2350

getParentDatabase methodDocument class, 1913

GetParentDocument methodNotesView class, 1501

getParentDocument methodView class, 2268

getParentDocumentUNID methodDocument class, 1914

getParents methodLog class, 2050

getParentView methodDocument class, 1915ViewNavigator class, 2337

getPercentUsed methodDatabase class, 1805

getPlatform methodSession class, 2191

getPMString methodInternational class, 2009

GetPortsList function, 260GetPos method

NotesViewNavigator class, 1585getPos method

ViewNavigator class, 2351GetPosition method

NotesViewEntry class, 1553getPosition method

ViewColumn class, 2300ViewEntry class, 2313

getPosition propertyRichTextTab class, 2181

GetPrev methodNotesOutline class, 1204NotesViewNavigator class, 1586

getPrev methodOutline class, 2095ViewNavigator, 2352ViewNavigator class, 2349

GetPrevCategory methodNotesViewNavigator class, 1587

getPrevCategory methodViewNavigator class, 2353

GetPrevDocument methodNotesDocumentCollection

class, 987NotesView class, 1502NotesViewNavigator class, 1588

getPrevDocument methodDocumentCollection class, 1971View class, 2270ViewNavigator class, 2354

GetPrevEntry methodNotesViewEntryCollection

class, 1565getPrevEntry method

ViewEntryCollection, 2327GetPrevSibling method

NotesOutline class, 1205NotesView class, 1503NotesViewNavigator class, 1589

getPrevSibling methodOutline class, 2095View class, 2271ViewNavigator class, 2354

getPriority method, 2144getPRMD method

Name class, 2076GetProfileDocCollection method

NotesDatabase class, 847

Index-20

getProfileDocCollection methodDatabase class, 1834

GetProfileDocument methodNotesDatabase class, 845

getProfileDocument methodDatabase class, 1835

GetProfileField function, 261getProgramName method

Log class, 2050getQuery method

Agent class, 1748DocumentCollection class, 1960ViewEntryCollection, 2317

getReaders methodView class, 2236

getRegistrationLog methodRegistration class, 2117

getRegistrationServer methodRegistration class, 2117

getReplicaID methodDatabase class, 1806

getReplicationInfo methodDatabase class, 1807

getResponses methodDocument class, 1916

getRightMargin methodRichTextParagraphStyle

class, 2167getRoles method

ACL class, 1701ACLEntry class, 1729

getRowLines methodView class, 2237

GetRowStatus methodODBCResultSet class, 1167

getSavedData methodAgentContext class, 1765

GetSelectedText methodNotesUIDocument class, 1400

getServer methodDatabase class, 1808

getServerName methodAgent class, 1749Session class, 2192

getSession methodAgentBase class, 1668AppletBase class, 1668

getSiblingCount methodViewEntry class, 2313

getSigner methodDocument class, 1918

getSize method, 1809Document class, 1918

getSizeQuota methodDatabase class, 1810

getSource methodEmbeddedObject class, 1982

getSpacing methodView class, 2237

getSpacingAbove methodRichTextParagraphStyle

class, 2168getSpacingBelow method

RichTextParagraphStyle class, 2168

getStartDateTime methodDateRange class, 1853

getStoreIDToAddressBook propertyRegistration class, 2118

getStrikethrough methodRichTextStyle class, 2178

getSubjectItemName methodNewsletter class, 2080

getSummary methodItem class, 2023

getSurName methodName class, 2076

getTabs methodRichTextParagraphStyle

class, 2169getTemplateName method

Database class, 1811getText method

Item class, 2026getThousandsSep method

International class, 2010getTimeDateFormat method

ViewColumn class, 2301getTimeFormat method

ViewColumn class, 2301getTimeOnly property

DateTime class, 1863getTimeSep method

International class, 2010getTimeZone method

DateTime class, 1864International class, 2010

getTimeZoneFormat methodViewColumn class, 2302

Gettinguser input, 93

getTitle methodDatabase class, 1812NotesViewColumn class, 2302

getToday methodInternational class, 2011

getTomorrow methodInternational class, 2011

getTopLevelEntryCount methodView class, 2238

getType methodEmbeddedObject class, 1983Item class, 2026OutlineEntry, 2108OutlineEntry class, 2105

getType propertyRichTextTab class, 2182

getUnderline methodRichTextStyle class, 2179

getUniveralID methodViewEntry class, 2313

getUniversalID methodDocument class, 1919View class, 2238

getUnprocessedDocuments methodAgentContext class, 1766

getUpdateAddressbook methodRegistration class, 2118

getURL methodJava classes, 1694OutlineEntry class, 2108

getURLDatabase methodSession class, 2209

GetURLHeaderInfo methodNotesDatabase class, 847

getURLHeaderInfo methodDatabase class, 1836

GetUserInfo methodNotesRegistration class, 1237

getUserInfo methodRegistration class, 2124

getUserName methodSession class, 2193

getUserNameList methodSession class, 2194

getUserNameObject methodSession class, 2194

getUserType methodACLEntry class, 1730

GetValue methodODBCResultSet class, 1169

getValueDouble methodItem class, 2029

getValueInteger methodItem class, 2030

getValueLength method, 2030getValues method

Item class, 2031getValueString method

Item class, 2033

Index-21

getVerbs methodEmbeddedObject class, 1983

getVerifier methodDocument class, 1920

GetView methodNotesDatabase class, 577,

580, 849getView method

Database class, 1838OutlineEntry class, 2109

getViews methodDatabase class, 1813

getWidth methodViewColumn class, 2302

getYesterday methodInternational class, 2012

getZoneTime propertyDateTime class, 1866

Given propertyName class, 2069NotesName class, 1079

Global variablesdefining, 48

GMTTime propertyDateTime class, 1859NotesDateTime class, 884

GotoBottom methodNotesUIDocument class, 1401

gotoChild methodViewNavigator class, 2355

gotoEntry methodViewNavigator class, 2357

GotoField methodNotesUIDocument class, 1401

gotoFirst methodViewNavigator class, 2358

gotoFirstDocument methodViewNavigator class, 2359

gotoLast methodViewNavigator class, 2360

gotoLastDocument methodViewNavigator class, 2362

gotoNext methodViewNavigator class, 2363

gotoNextCategory methodViewNavigator class, 2364

gotoNextDocument methodViewNavigator class, 2365

GotoNextField methodNotesUIDocument class, 1402

gotoNextSibling methodViewNavigator class, 2365

gotoParent methodViewNavigator class, 2366

gotoPos methodViewNavigator class, 2366

gotoPrev methodViewNavigator class, 2367

gotoPrevCategory methodViewNavigator class, 2367

gotoPrevDocument methodViewNavigator class, 2368

GotoPrevField methodNotesUIDocument class, 1402

gotoPrevSibling methodViewNavigator class, 2369

GotoTop methodNotesUIDocument class, 1402

GoUpLevel command, 476GrantAccess method

NotesDatabase class, 850grantAccess method

Database class, 1839Greater than operator (>)

Formula Language, 69Greater than or equal to operator

(>= or =>)Formula Language, 69

Groupsaccess in ACL, 1721

HHasChildren property

NotesOutlineEntry class, 1212OutlineEntry class, 2103

HasEmbedded propertyDocument class, 1901NotesDocument class, 920

HasItem methodNotesDocument class, 958

hasItem methodDocument class, 1940

HasRowChanged methodODBCResultSet class, 1171

HeaderAlignment propertyNotesViewColumn class, 1515ViewColumn class, 2285

HeaderLines propertyNotesView class, 1466View class, 2224

Help command, 476HelpAboutDatabase command, 477HelpAboutNotes command, 477HelpFunctions command, 477HelpIndex command, 477HelpKeyboard command, 478

HelpMessages command, 478HelpReleaseNotes command, 478HelpTableOfContents

command, 478HelpUsingDatabase command, 479HelpV3ReleaseMenuFinder

command, 478Hidden paragraph formulas, 3, 84

writing, 19HiddenChars property

NotesUIDocument class, 1373Hide action formulas, 3, 10HideDesign property

NotesReplication class, 1251Hiding

a formula, 498Hierarchical views

View class, 2230History

clear replication, 2146HorzScrollBar property

NotesUIDocument class, 1374HotSpotClear command, 479HotSpotProperties command, 479Hotspots, 4, 12

in a script and formula, 84, 85Hour function, 262HTTP server tasks, 1591

IIcons

programming language, 38ID files

getDocumentByID method, 1827IDType property

NotesRegistration class, 1226Registration class, 2115

If directive, 548If function, 78, 90, 263Ignore deletes, 2140Ignore destination deletes, 2141IgnoreDeletes property

NotesReplication class, 1252IgnoreDestDeletes property

NotesReplication class, 1253ImagesText property

NotesOutlineEntry class, 1212OutlineEntry class, 2105

Implode function, 87, 265Import Class Files button

defined, 36Import method, 1403

Index-22

Imported JavaBase Class box, 36Import Class Files button, 36user interface, 36

Importinga file, 461text, 42

Include directive, 548IndentLevel property

NotesViewEntry class, 1545ViewEntry, 2309ViewEntry class, 2306

Indexes, 2142Info List

adjusting the size of, 37Objects tab, 37Reference tab, 37using, 37

InheritedDocumentUniqueIDfunction, 126, 266

Initial object references, 1594Initials property

Name class, 2069NotesName class, 1080

InPreviewPane propertyNotesUIDocument class, 1374

Input translation formulas, 4, 23, 84Input validation formulas, 4, 23InputBox statement, 552Insert subform formulas, 3, 18, 84

writing, 18Insertion points

Script Area, 40InsertSubForm command, 480InsertText method

NotesUIDocument class, 1404Integer function, 113, 266Integer item values

getting in Java, 1938Integers, 67InterLineSpacing property

NotesRichTextParagraphStyleclass, 1280

RichTextParagraphStyle class, 2165

International class, 1652, 1998International property

NotesSession class, 1314Session class, 2188

International settingsaccessing in Java, 1652accessing in LotusScript, 653

InternetLevel propertyACL class, 1697NotesACL class, 729

Interval propertyNotesTimer class, 1345

IOR, 1594IsAbstract property

Replication class, 2133IsAccentSensitiveSort property

NotesViewColumn class, 1515ViewColumn class, 2285

IsAdminReaderAuthor propertyACLEntry class, 1713NotesACLEntry class, 749

IsAdminServer propertyACLEntry class, 1714NotesACLEntry class, 750

IsAgentEnabled function, 267IsAuthors property

Item class, 2016NotesItem class, 1034

IsAutoUpdate propertyView class, 2225

IsAvailable function, 126, 268IsBeginOfData method

ODBCResultSet class, 1173IsCalendar property

NotesView class, 1466View class, 2226

IsCanCreateDocuments propertyACLEntry class, 1714

IsCanCreateLSOrJavaAgentproperty

ACLEntry class, 1715IsCanCreatePersonalAgent property

ACLEntry class, 1716IsCanCreatePersonalFolder property

ACLEntry class, 1717IsCanCreateSharedFolder property

ACLEntry class, 1719IsCanDeleteDocuments property

ACLEntry class, 1719IsCaseInsensitiveSort property

NotesViewColumn class, 1516IsCaseSensitiveSort property

ViewColumn class, 2286IsCategorized property

NotesView class, 1467View class, 2227

IsCategory function, 102, 124, 269

IsCategory propertyNotesViewColumn class, 1517NotesViewEntry class, 1546ViewColumn class, 2286ViewEntry class, 2310

IsConflict propertyNotesView class, 1468NotesViewEntry class, 1547View class, 2228ViewEntry class, 2310

IsConnected methodODBCConnection class, 1106

IsCurrencySpace propertyInternational class, 2005NotesInternational class, 1023

IsCurrencySuffix propertyInternational class, 2005NotesInternational class, 1023

IsCurrencyZero propertyInternational class, 2006NotesInternational class, 1024

IsCutoffDelete propertyReplication class, 2135

IsDateDMY propertyInternational class, 2006NotesInternational class, 1024

IsDateMDY propertyInternational class, 2007NotesInternational class, 1025

IsDateYMD propertyInternational class, 2007NotesInternational class, 1025

IsDefaultView propertyNotesView class, 1468View class, 2228

IsDelayUpdates propertyDatabase class, 1794

IsDeleted property, 921IsDirectoryCatalog property

NotesDatabase class, 804IsDisabled property

Replication class, 2135IsDocBeingEdited function, 126, 270IsDocBeingLoaded function, 102,

126, 270IsDocBeingMailed function, 102,

126, 271IsDocBeingRecalculated function,

102, 126, 272IsDocBeingSaved function, 102,

126, 273IsDocTruncated function, 274

Index-23

IsDocument propertyNotesViewEntry class, 1548ViewEntry class, 2310

IsDoNotBrowse propertyReplication class, 2137

IsDoNotCatalog propertyReplication class, 2138

IsDoScore propertyNewsletter class, 2079

IsDoSubject propertyNewsletter class, 2079

IsDST propertyDateTime class, 1860International class, 2008NotesDateTime class, 885NotesInternational class, 1025

IsEnabled propertyAgent class, 1740NotesAgent class, 768

IsEncrypted propertyItem class, 2018NotesItem class, 1035

IsEncryptOnSend propertyDocument class, 1902

IsEndOfData methodODBCResultSet class, 1175

IsError function, 99, 274IsExpandable function, 102, 124, 275IsField property

NotesViewColumn class, 1518ViewColumn class, 2287

IsFolder propertyNotesView class, 1469View class, 2229

IsFormula propertyNotesViewColumn class, 1518ViewColumn class, 2287

IsFTIndexed propertyDatabase class, 1796NotesDatabase class, 805

IsGroup propertyACLEntry class, 1721NotesACLEntry class, 751

IsHidden propertyNotesOutlineEntry class, 1213NotesViewColumn class, 1519OutlineEntry class, 2105ViewColumn class, 2288

IsHideDesign propertyReplication class, 2139

IsHideDetail propertyNotesViewColumn class, 1520ViewColumn class, 2288

IsHierarchical propertyName class, 2069NotesName class, 1080NotesView class, 1470View class, 2230

IsIcon propertyJava, 2290NotesViewColumn class, 1521

IsIgnoreDeletes propertyReplication class, 2140

IsIgnoreDestDeletes propertyReplication class, 2141

IsInThisDB propertyNotesOutlineEntry class, 1214OutlineEntry class, 2106

IsLogActions propertyLog class, 2044

IsLogErrors propertyLog class, 2045

IsMember function, 87, 276IsModalHelp function, 277IsModified property

NotesView class, 1471View class, 2230

IsMultiDbIndex propertyReplication class, 2142

IsMultiDbSearch propertyDatabase class, 1797NotesDatabase class, 807

IsNames propertyItem class, 2020NotesItem class, 1036

IsNeverReplicate propertyReplication class, 2143

IsNewDoc function, 102, 126, 278IsNewDoc property

NotesUIDocument class, 1375IsNewNote property

Document class, 1903NotesDocument class, 922

IsNoChronos propertyReplication class, 2143

IsNorthAmerican propertyNotesRegistration class, 1227Registration class, 2116

IsNotesAgent property, 770Agent class, 1742NotesAgent class, 769

IsNotMember function, 87, 278IsNumber function, 105, 280IsOnServer property

NotesSession class, 1315Session class, 2189

IsOpen propertyDatabase class, 1798NotesDatabase class, 807

IsOverwriteFile propertyLog class, 2046

IsPerson propertyACLEntry class, 1721NotesACLEntry class, 752

IsPrivate propertyNotesOutlineEntry class, 1215NotesView class, 1472OutlineEntry class, 2106View class, 2231

IsPrivateAddressBook propertyDatabase class, 1799NotesDatabase class, 808

IsProfile propertyJava, 1904NotesDocument class, 923

IsProtected propertyItem class, 2021NotesItem class, 1037

IsProtectReaders propertyForm class, 1992View class, 2232

IsProtectUsers property, 1993IsPublic property

Agent class, 1743NotesAgent class, 770

IsPublicAddressBook propertyDatabase class, 1800NotesDatabase class, 809

IsPublicReader propertyACLEntry class, 1722NotesACLEntry class, 753

IsPublicWriter propertyACLEntry class, 1723NotesACLEntry class, 754

IsReaders propertyItem class, 2021NotesItem class, 1037

IsResize propertyNotesViewColumn class, 1521ViewColumn class, 2290

IsResortAscending propertyNotesViewColumn class, 1522ViewColumn class, 2290

IsResortDescending propertyNotesViewColumn class, 1523ViewColumn class, 2291

IsResortToView propertyNotesViewColumn class, 1523ViewColumn class, 2291

Index-24

IsResponse propertyDocument class, 1905NotesDocument class, 924NotesViewColumn class, 1524ViewColumn class, 2292

IsResponseDoc function, 126, 280IsResultSetAvailable method

ODBCResultSet class, 1176IsRoleEnabled method

NotesACLEntry class, 763isRoleEnabled method

ACLEntry class, 1734IsSaveMessageOnSend property

Document class, 1905IsSaveToDisk property

Item class, 2022IsSecondaryResort property

Formula Language, 1527ViewColumn class, 2293

IsSecondaryResortDescendingproperty

NotesViewColumn class, 1527ViewColumn class, 2293

IsSentByAgent propertyDocument class, 1906

IsServer propertyACLEntry class, 1723NotesACLEntry class, 755

IsShowTwistie propertyNotesViewColumn class, 1528ViewColumn class, 2294

IsSigned propertyDocument class, 1907Item class, 2022NotesDocument class, 924NotesItem class, 1038

IsSignOnSend propertyDocument class, 1908

IsSortDescending propertyNotesViewColumn class, 1529ViewColumn class, 2294

IsSorted propertyDocumentCollection class, 1957NotesDocumentCollection

class, 977NotesViewColumn class, 1529ViewColumn class, 2295

IsSubForm propertyForm class, 1994NotesForm class, 1012

IsSummary propertyItem class, 2023NotesItem class, 1039

IsSupported methodODBCConnection class, 1107

IsText function, 105, 281IsTime function, 105, 282IsTime24Hour property

International class, 2008NotesInternational class, 1026

IsTotal propertyNotesViewEntry class, 1549

IsTotals propertyViewEntry class, 2311

IsUIDocOpen propertyNotesDocument class, 925

IsUnavailable function, 126, 282IsUniformAccess property

ACL class, 1699IsValid function, 283IsValid property

Document class, 1909NotesDocument class, 926NotesViewEntry class, 1549ViewEntry class, 2311

IsValidDate propertyNotesDateTime class, 886

IsValueAltered methodODBCResultSet class, 1177

IsValueNull methodODBCResultSet class, 1179

IsWebAgent property, 771Agent class, 1744NotesAgent class, 771

Italic propertyNotesRichTextStyle class, 1295RichTextStyle class, 2177

Item class, 1640, 2012Item values

getting in Java, 1936, 1938, 1939,2029, 2030, 2031, 2033

replacing in Java, 1947stampAll method, 1976

ItemName propertyNotesViewColumn class, 1531ViewColumn class, 2296

Itemsaccessing in Java, 1640accessing in LotusScript, 624accessing properties in Java, 1641accessing properties in

LotusScript, 625copying in Java, 1644copying in LotusScript, 633creating in Java, 1644creating in LotusScript, 630

getting in Java, 1643getting in LotusScript, 627removing in Java, 1645, 1945removing in LotusScript, 634

Items propertyDocument class, 1910NotesDocument class, 927

JJava

compiling, 44compiling and running, 1591dates, 1878Errors box, 39icon, 38in the Programmer's pane, 35overview, 1Script Library, 57viewing output, 43

Java agent, 46adding files, 44debugging, 45

Java classesA-Z reference, 1591, 1661coding guidelines, 1591complete list, 1595

Java Debug Consoledefined, 35

Java interfaceClasses tab, 35Compile button, 35Edit Project button, 35Export button, 35Java Debug Console, 35New Class button, 35

JavaScriptcompiling, 48icon, 38in the programmer's pane, 47overview, 1page header, 48remark, 48writing in a page header, 48

JavaScript databasesagent output, 523

JS Headerusing, 48

KKey property

Document class, 1911NotesDocument class, 928

Index-25

Keyssearching by key in Java, 2251,

2253, 2258, 2260sorted column, 616

Keyword field formulas, 4, 24Keyword fields

writing a formula, 84Keyword formulas, 79Keyword parameters

@functions, 75Keyword property

Name class, 2070NotesName class, 1080

Keywords function, 87, 284

LLabel property

NotesOutlineEntry class, 1215OutlineEntry class, 2107

Language Preference function, 285Language property

Name class, 2070NotesName class, 1081

LastAccessed propertyDocument class, 1911NotesDocument class, 928

LastExitStatus propertyAgentContext class, 1763NotesSession class, 1316

LastFTIndexed propertyDatabase class, 1801NotesDatabase class, 810

LastModified propertyDatabase class, 1802Document class, 1912Item class, 2024NotesDatabase class, 810NotesDocument class, 929NotesItem class, 1040NotesView class, 1472View class, 2233

LastRow methodODBCResultSet class, 1180

LastRun propertyAgent class, 1744AgentContext class, 1764NotesAgent class, 772NotesSession class, 1316

LayoutAddGraphic command, 480LayoutAddText command, 480LayoutElementBringToFront

command, 481

LayoutElementProperties command, 481

LayoutElementSendToBackcommand, 481

LayoutProperties command, 482Leading spaces, 367Left function, 109, 286LeftBack function, 109, 287LeftMargin property

NotesRichTextParagraphStyleclass, 1281

RichTextParagraphStyle class, 2166

Length function, 106, 288Lengths

of string in a formula, 106Less than operator (

Formula Language, 69Less than or equal to operator (

Formula Language, 69Level property

ACLEntry class, 1724NotesACLEntry class, 756NotesOutlineEntry class, 1216OutlineEntry class, 2107

Lexical elementsFormula Language, 61

Like function, 106, 289Links

appending in Java, 2157List concatenation operator

Formula Language, 69List operations

Formula Language, 72List operators

Formula Language, 70ListDataSources method

ODBCConnection class, 1109ListFields method

ODBCConnection class, 1110ListProcedures method

ODBCConnection class, 1111Lists

Formula Language, 64, 86in a formula, 86

ListSep propertyNotesViewColumn class, 1532ViewColumn class, 2297

ListTables methodODBCConnection class, 1112

Ln function, 114, 290Locale function, 291

LocalTime propertyDateTime class, 1861NotesDateTime class, 887

LocateRow methodODBCResultSet class, 1181

Log class, 1657, 2041Log function, 114, 292LogAction method

NotesLog class, 1061logAction method

Log class, 2052LogActions property

NotesLog class, 1055LogError method

NotesLog class, 1063logError method

Log class, 2053LogErrors property

NotesLog class, 1056LogEvent method

NotesLog class, 1067logEvent method

Log class, 2055Logical operators

Formula Language, 69, 72Logs

accessing in Java, 1657in LotusScript, 656

Lotus components, 715LotusScript

block statements, 50compiling, 50debugger, 51debugging, 53describing, 1Domino-specific features, 547Errors box, 39icon, 38in Programmer's pane, 48Notes classes, 721overview, 1programming environment, 33using the debugger, 52writing in the Programmer's

pane, 48LotusScript data objects, 661LotusScript debugger

clearing breakpoints, 54enabling and disabling, 52enabling and disabling

breakpoints, 54Output panel, 56

Index-26

setting breakpoints, 54stepping through scripts, 53stopping, 53using, 52variables panel, 55

LowerCase function, 112, 293LS:DO

auto-commit mode, 695caching data, 697creating script, 666handling ODBC errors, 693handling ODBC events, 690multi-threading agents, 697overview, 667requirements, 663setting for multi-thread

environment, 665setting up with ODBC, 664specifying SQL statements, 672transaction mode, 696transaction processing, 695UseLSX, 666working with result sets, 677

LSCONST.LSS file, 548, 699LSERR.LSS file, 548, 698LSGMTTime property

NotesDateTime class, 887LSLocalTime property

NotesDateTime class, 888LSXBEERR.LSS file, 548, 698LSXUIERR.LSS file, 548, 698

MMail

accessing in Java, 1640Mail logs

openMailLog method, 2059MailAddress command, 482MailComposeMemo command, 482MailDbName function, 121, 294MailEncryptSavedPreference

function, 295MailEncryptSentPreference

function, 296MailForward command, 483MailForwardAsAttachment

command, 483Mailing

in LotusScript, 623Mailing documents

send method, 1951MailOpen command, 483

MailRequestCrossCert command, 483

MailRequestNewName command, 484

MailRequestNewPublicKeycommand, 484

MailSavePreference function, 296MailScanUnread command, 484MailSend command, 485MailSend function, 76, 102, 125, 297MailSendCertificateRequest

command, 485MailSendEncryptionKey

command, 485MailSendPublicKey command, 486MailSignPreference function, 301MakeResponse method

NotesDocument class, 960makeResponse method

Document class, 1940Managers property

Database class, 1803NotesDatabase class, 811

Matches function, 106, 302Max function, 113, 303MaxLevel property

NotesViewNavigator class, 1573ViewNavigator class, 2336

MaxRows propertyODBCResultSet class, 1137

MaxSize propertyDatabase, 1804Database class, 1803NotesDatabase class, 813

Member function, 87, 304Memory

recycling, 1694MessageBox statement, 552Messages

writing, 92Middle function, 109, 305MiddleBack function, 109, 307Min function, 113, 308MinPasswordLength property

NotesRegistration class, 1227Registration class, 2116

Minus operator (-), 71Minus sign (-), 67Minute function, 119, 310Modified function, 118, 310Modulo function, 114, 311Month function, 119, 312

Mouse operationstable of, 41

MoveEntry methodNotesOutline class, 1205

moveEntry methodOutline class, 2096

Movinginsertion point, 40

Multi-database indexes, 2136Multi-database searches

isMultiDbSearch method, 1797Multi-threading

in LS:DO, 697MultiDbIndex property

NotesReplication class, 1254Multiple database index, 2142Multiple parameters

@functions, 75Multiplication operator (*)

Formula Language, 69Multiplying, 113

NName class, 1658, 2062Name function, 121, 313Name property

ACLEntry class, 1726Agent class, 1746DbDirectory class, 1880EmbeddedObject class, 1981Form class, 1995Item class, 2024NotesACLEntry class, 757NotesAgent class, 773NotesDbDirectory, 557NotesDbDirectory class, 902NotesEmbeddedObject class, 998NotesForm class, 1013NotesItem class, 1040NotesOutline class, 1199NotesView class, 1473Outline class, 2089View class, 2234

NamedElement propertyin NotesOutlineEntry class, 1217

NameLookup function, 317NameObject property

ACLEntry class, 1727NameOfProfile property

Document class, 1912NotesDocument class, 930

Index-27

Namesalternate, 379in Java, 1658in LotusScript, 659primary, 379

Narrow function, 319NavBarSetText method

NotesUIDocument class, 1404NavBarSpinnerStart method, 1405NavBarSpinnerStop method, 1405NavigateNext command, 486NavigateNextHighlight

command, 486NavigateNextMain command, 487NavigateNextSelected

command, 487NavigateNextUnread command, 488NavigatePrev command, 488NavigatePrevHighlight

command, 489NavigatePrevMain command, 489NavigatePrevSelected

command, 490NavigatePrevUnread

command, 490NavigateToBackLink

command, 490Navigator class, 1087NavigatorProperties

command, 491NavigatorTest command, 491NCSO.JAR file, 1592needsGUI method

Visibility interface, 1695Negation operator (-)

Formula Language, 69Negative numbers, 67Nested

@If function, 92Never replicate, 2143NeverReplicate property

NotesReplication class, 1254New Class button

defined, 35New lines

adding, 112adding in Java, 2150

NewLine function, 112, 320Newsletter class, 1658, 2076Newsletters

accessing in Java, 1658in LotusScript, 658

NextRow methodODBCResultSet class, 1183

No function, 321NoChronos property

NotesReplication class, 1255NoExternalApps

environment variables, 77Not equal to operator ( or >

Formula Language, 69Not operator

Formula Language, 69NoteID function, 126, 322NoteID property

Document class, 1912NotesDocument class, 930NotesViewEntry class, 1550ViewEntry class, 2312

NOTES.INI file, 79, 97, 649, 665,1592, 1649

NOTES.JAR file, 1592NOTES.LOG file, 552Notes Formula Language, 61

guidelines, 83Notes formula language

in the Programmer's pane, 58NotesACL class, 565, 728NotesACLEntry class, 566, 740NotesAgent class, 650, 765notesAppletInit method

AppletBase class, 1668notesAppletStart method

AppletBase class, 1668notesAppletStop method

AppletBase class, 1668NotesBuildVersion property

NotesSession class, 1317NotesColor property

NotesRichTextStyle class, 1296NotesDatabase class, 553, 785, 1603NotesDateRange class, 876NotesDateTime class, 655, 879NotesDbDirectory class, 553, 557,

901, 1603NotesDocument class, 599, 904NotesDocumentCollection class,

610, 974NotesEmbeddedObject class,

639, 992NotesError class, 1669NotesException class, 1669NotesFactory class, 1594, 1691NotesFont property

NotesRichTextStyle class, 1297NotesForm class, 1008NotesIDs

getDocumentByID method, 1827

NotesInternational class, 653, 1018NotesItem class, 624, 1029NotesLog class, 657, 1052NotesName class, 659, 1073NotesNewsletter class, 658, 1088NotesOutline class, 562, 1196NotesOutlineEntry class, 563, 1207NotesRegistration class, 1222NotesReplication class, 1244NotesRichTextItem class, 624,

635, 1258NotesRichTextParagraphStyle class,

643, 1277NotesRichTextStyle class, 641, 1290NotesRichTextTab class, 645, 1301NotesSession class, 646, 1303NotesSession properties, 1648NotesThread class, 1593, 1692NotesTimer class, 659, 1341NotesUIDatabase class, 1345NotesUIDocument class, 604, 1353NotesUIView class, 1413NotesUIWorkspace class, 603, 1426NotesVersion property

NotesSession class, 1318Session class, 2190

NotesView class, 1457NotesViewColumn class, 581, 1506NotesViewEntry class, 1539NotesViewEntryCollection

class, 1554NotesViewNavigator class, 594, 1570Now function, 118, 322Null fields

Formula Language, 64NumActions property

Log class, 2048NotesLog class, 1057

NumberAttrib propertyNotesViewColumn class, 1533ViewColumn class, 2297

NumberDigits propertyNotesViewColumn class, 1533ViewColumn class, 2299

NumberFormat propertyNotesViewColumn class, 1534ViewColumn class, 2299

NumColumns methodODBCResultSet class, 1185

Numeric constantsFormula Language, 67

NumErrors propertyLog class, 2049NotesLog class, 1058

Index-28

NumParameters methodODBCResultSet class, 1186

NumRows methodODBCResultSet class, 1187

OObject

renaming, 43Object links

appending in Java, 2157Object property

EmbeddedObject class, 1982NotesEmbeddedObject class, 999

ObjectDisplayAs command, 491ObjectExecute event

Button class, 785ObjectOpen command, 492ObjectProperties command, 492Objects

assigning, creating, deleting inLotusScript, 551

embedding with Java, 1978overview, 3renaming, 43

Objects and eventsoverview, 25Sequencing, 29

Objects tabdefined, 34defining subprograms, 48global variables, 48JavaScript, 47using, 37

ODBCFormula Language, 132handling errors, 693handling events, 690

ODBC Driver Manager, 667ODBCConnection class, 667, 1097ODBCNonThreadSafeDriver

statement, 665ODBCQuery class, 672, 676, 1114ODBCResultSet class, 676, 1128ODBCThreadSaveDriver

statement, 665OLE

custom controls, 715automation objects, 719LotusScript, 549

On Error statementLotusScript, 698

Open Database dialog, 2137

Open methodNotesDatabase class, 558, 852

open methodDatabase class, 1840

OpenAgentLog methodNotesLog class, 1068

openAgentLog methodLog class, 2056

OpenByReplicaID methodNotesDatabase class, 558, 854

OpenCalendar command, 492OpenDatabase method

NotesUIWorkspace class, 1441openDatabase method

DbDirectory class, 1885openDatabaseByReplicaID method

DbDirectory class, 1886openDatabaseIfModified method

DbDirectory class, 1887OpenDocument command, 493OpenFileDialog method

NotesUIWorkspace class, 1442OpenFileLog method

NotesLog class, 1068openFileLog method

Log class, 2057OpenFrameset command, 494OpenFrameSet method

NotesUIWorkspace class, 1443OpenHelpDocument

command, 494OpenIfModified method

NotesDatabase class, 558, 854OpenMail method

NotesDatabase class, 558, 855openMailDatabase method

DbDirectory class, 1888OpenMailLog method

NotesLog class, 1069openMailLog method

Log class, 2059OpenNavigator command, 495OpenNavigator method

NotesUIDatabase class, 1352OpenNotesLog method

NotesLog class, 1071openNotesLog method

Log class, 2060OpenPage command, 496OpenPage method

NotesUIWorkspace class, 1443OpenURLDb method

NotesDatabase class, 856OpenView command, 496

OpenView methodNotesUIDatabase class, 1352

OpenWithFailover methodNotesDatabase class, 558, 857

OperatorsFormula Language, 68

Operators and valuesFormula Language, 63

OptimizeMailAddress function, 121, 322

Option statementScript Area, 49

Or operator, 69Formula Language, 72

Order of evaluation@commands, 78@functions, 77formula operation, 70

Organization propertyName class, 2074NotesName class, 1085

OrgUnit propertyNotesRegistration class, 1228Registration class, 2117

OrgUnit1 propertyName class, 2074NotesName class, 1085

OrgUnit2 propertyName class, 2074NotesName class, 1085

OrgUnit3 propertyName class, 2075NotesName class, 1086

OrgUnit4 propertyName class, 2075NotesName class, 1086

Outline class, 1620, 2085OutlineEntry class, 1620, 2099Outlines

accessing, 562accessing in Java, 1620accessing in LotusScript, 562creating in Java, 1819getOutline method, 1833

Output panelusing, 56

Overviewscript objects and events, 25scripts and formulas, 1

OverwriteFile propertyNotesLog class, 1059

Owner propertyAgent class, 1746NotesAgent class, 773

Index-29

PPage breaks

adding in Java, 2152Pages

defining, 496setting up, 467

Pagination propertyNotesRichTextParagraphStyle

class, 1282RichTextParagraphStyle

class, 2166Pair-wise list operators, 72Paragraph styles

appending in Java, 2155Parent property

ACL class, 1700ACLEntry class, 1728Agent class, 1747Database class, 1805DateRange class, 1853DateTime class, 1863DbDirectory class, 1881DocumentCollection

class, 1959EmbeddedObject class, 1982Form class, 1996International class, 2009Item class, 2024Log class, 2050Newsletter class, 2080NotesACL class, 730NotesACLEntry class, 759NotesAgent class, 775NotesDatabase class, 813NotesDocumentCollection

class, 978NotesEmbeddedObject

class, 999NotesItem class, 1041NotesView class, 1473NotesViewEntry class, 1551NotesViewEntryCollection

class, 1556RichTextStyle class, 2178View class, 2235ViewColumn class, 2300ViewEntry class, 2312ViewEntryCollection, 2316ViewNavigator class, 2337

ParentDatabase propertyDocument class, 1913NotesDocument class, 931

ParentDocumentUNID propertyDocument class, 1914NotesDocument class, 932

Parenthesespassing by value, 553

Parentheses ( )@functions, 75formula operation, 70

ParentView propertyDocument class, 1915NotesDocument class, 933NotesViewNavigator, 1574

Passing by value, 553PassThruHTML property

NotesRichTextStyle class, 1298Password function, 121, 323Paste method

NotesUIDocument class, 1405PasteBitmapAsBackground

command, 497PasteBitmapAsObject

command, 498Pasting

text in Script Editor, 42PercentUsed property

Database class, 1805NotesDatabase class, 814

Permuted list operators, 72Permuted operators, 69Pi function, 114, 324PickList function, 76, 102, 325PickListCollection method

NotesUIWorkspace class, 1444PickListStrings method

NotesUIWorkspace class, 1445PictureProperties command, 498Platform function, 102, 121, 328Platform property

NotesSession class, 1319Session class, 2191

PlayTune methodNotesUIWorkspace class, 1447

Plus operator (+), 71Plus sign (+), 67PMString property

International class, 2009NotesInternational class, 1026

Position propertyNotesRichTextTab class, 1302NotesViewColumn class, 1535RichTextTab class, 2181ViewColumn class, 2300

Positive operatorFormula Language, 69

PostDocumentDelete eventNotesUIDatabase class, 1347

PostDragDrop eventNotesUIDatabase class, 1347NotesUIView class, 1414

PostedCommand function, 76, 103, 330

PostModeChange eventNotesUIDocument class, 1356

PostOpen eventNotesUIDatabase class, 1348NotesUIDocument class, 1357NotesUIView class, 1415

PostPaste eventNotesUIView class, 1415

PostRecalc eventNotesUIDocument class, 1359

PostSave eventNotesUIDocument class, 1360

Power function, 114, 330Precedence, 69Preferences file, 79, 649, 1649PreviewDocLink property

NotesUIDocument class, 1376PreviewParentDoc property

NotesUIDocument class, 1377PrevRow method

ODBCResultSet class, 1189Primary names, 379, 381Print method

NotesUIDocument class, 1406NotesUIView class, 1425

Print setup, 470Printing

a file, 468PrintWriter class, 1594, 1668Priority property

NotesReplication class, 1256Replication class, 2144

Private viewsView class, 2231

PRMD propertyName class, 2076NotesName class, 1086

Profile documentsgetKey method, 1911getProfileDocCollection

method, 1834getProfileDocument

method, 1835isProfile method, 1904

Index-30

Programmable objects, 3Programmer's pane

accessing, 36Classes tab, 35Compile button, 35Edit Project button, 35Errors box, 39errors box, 34Export button, 35formula windows, 58formulas, 58Imported Java, 36Java, 35Java Debug Console, 35JavaScript, 47LotusScript, 48New Class button, 35programming properties and

events, 37Reference tab, 38run box, 34selecting text, 41setting text properties, 40Simple action(s), 59title bar, 34user interface, 33

Programming environmentLotusScript, 33

Programming languagedetermining, 38

Programming overview, 1ProgramName property

Log class, 2050NotesLog class, 1060

Prompt function, 76, 103, 331Prompt method

NotesUIWorkspace class, 1447ProperCase function, 112, 336Property block

Script Area, 49Protect readers

View class, 2232ProtectReaders property

NotesForm class, 1014NotesView class, 1474

ProtectUsers propertyNotesForm class, 1015

Public Address BookisPublicAddressBook

method, 1800Public readers, 1722Public writers, 1723PublishDatabase command, 498

PutAllInFolder methodNotesDocumentCollection

class, 988NotesViewEntryCollection

class, 1566putAllInFolder method

DocumentCollection class, 1972ViewEntryCollection, 2327

PutInFolder methodNotesDocument class, 961

putInFolder methodDocument class, 1941

QQuery property

Agent class, 1748DocumentCollection class, 1960NotesAgent class, 775NotesDocumentCollection

class, 979NotesViewEntryCollection

class, 1557ODBCResultSet class, 1138ViewEntryCollection, 2317

QueryAccess methodNotesDatabase class, 858

queryAccess methodDatabase class, 1841

QueryAddToFolder eventNotesUIView class, 1416

QueryClose eventNotesUIDatabase class, 1349NotesUIDocument class, 1361NotesUIView class, 1417

QueryDocumentDelete eventNotesUIDatabase class, 1349

QueryDocumentUndelete eventNotesUIDatabase class, 1350

QueryDragDrop eventNotesUIDatabase class, 1350NotesUIView class, 1418

QueryExecuteTimeOut propertyODBCQuery class, 1117

QueryModeChange eventNotesUIDocument class, 1362

QueryOpen eventNotesUIDocument class, 1363NotesUIView class, 1418

QueryOpenDocument eventNotesUIView class, 1419

QueryPaste eventNotesUIView class, 1420

QueryRecalc eventNotesUIView class, 1421

QuerySave event, 1365Quotation marks, 66

RRandom function, 114, 337, 339Readers property

Form class, 1996NotesForm class, 1016NotesView class, 1475View class, 2236

ReadOnly propertyODBCResultSet class, 1139

ReCertify methodNotesRegistration class, 1238

recertify methodRegistration class, 2125

recycle methodJava classes, 1694

Redundant spaces, 367Reference list

defined, 34Reference tab

defined, 34help button, 34paste button, 34paste full text, 34pasting from, 38short-cut keys, 39using, 38

Refresh methodNotesUIDocument class, 1407NotesView class, 1504

refresh methodView class, 2272

RefreshECL function, 338RefreshHideFormulas

command, 499RefreshHideFormulas method

NotesUIDocument class, 1408Refreshing

a formula, 498RefreshParentNote command, 498RefreshParentNote method

NotesUIWorkspace class, 1449Regional settings, 653RegionDoubleClick event

NotesUIView class, 1422RegisterNewCertifier method

NotesRegistration class, 1239

Index-31

registerNewCertifier methodRegistration class, 2126

RegisterNewServer methodNotesRegistration class, 1240

registerNewServer methodRegistration class, 2127

RegisterNewUser methodNotesRegistration class, 1241

registerNewUser methodRegistration class, 2128

Registration class, 2112RegistrationLog property

NotesRegistration class, 1228Registration class, 2117

RegistrationServer propertyNotesRegistration class, 1228Registration class, 2117

Reload methodNotesUIDocument class, 1409

ReloadWindow methodNotesUIWorkspace class, 1450

Rem keyword, 79, 338Remote calls, 1591Remove method

NotesACLEntry class, 764NotesAgent class, 780NotesDatabase class, 860NotesDocument class, 963NotesEmbeddedObject

class, 1006NotesForm class, 1017NotesItem class, 1052NotesView class, 1506

remove methodACLEntry class, 1735Agent class, 1753Database class, 1843Document class, 1943EmbeddedObject class, 1986Form class, 1997Item class, 2040View class, 2273

removeACLEntry methodACL class, 1709

RemoveAll methodNotesDocumentCollection

class, 989NotesViewEntryCollection

class, 1567removeAll method

DocumentCollection class, 1974ViewEntryCollection, 2329

RemoveAllFromFolder methodNotesDocumentCollection

class, 989NotesViewEntryCollection

class, 1567removeAllFromFolder method

DocumentCollection class, 1975ViewEntryCollection, 2330

RemoveEntry methodNotesOutline class, 1206

removeEntry methodOutline class, 2098

RemoveFromFolder command, 499RemoveFromFolder method

NotesDocument class, 964removeFromFolder method

Document class, 1944RemoveItem method

NotesDocument class, 965removeItem method

Document class, 1945RenameDatabase command, 499RenameRole method

NotesACL class, 738renameRole method

ACL class, 1710Renaming

object in Script Editor, 43subprogram in Script Editor, 43

RenderToRTItem methodNotesDocument class, 966

renderToRTItem methodDocument class, 1946

Repeat function, 112Repeating

a string, 112Replace function, 87, 340ReplaceItemValue method, 967replaceItemValue method

Document class, 1947ReplaceSubstring function, 341Replacing

text in Script Editor, 42Replica IDs

openDatabaseByReplicaIDmethod, 1886

ReplicaID propertyDatabase class, 1806NotesDatabase class, 815

Replicascreating in Java, 1820

Replicate methodNotesDatabase class, 861

replicate methodDatabase class, 1844

Replicatinga formula, 84

Replicationresetting the properties in

LotusScript, 574saving the properties in

LotusScript, 574settings in LotusScript, 570

Replication class, 2130Replication formulas, 3, 6Replication priority, 2144ReplicationInfo property

Database class, 1807NotesDatabase class, 815

Replicator command, 500ReplicatorReplicateHigh

command, 500ReplicatorReplicateNext

command, 501ReplicatorReplicateSelected

command, 501ReplicatorReplicateWithServer

command, 501ReplicatorSendMail command, 502ReplicatorSendReceiveMail

command, 502ReplicatorStart command, 502ReplicatorStop command, 502Reset method

NotesReplication class, 1257reset method

Replication class, 2146resolve method

Session class, 2210Response documents, 616

isResponse method, 1905making in Java, 1940

Responses function, 103, 123, 126, 342

Responses propertyDocument class, 1916NotesDocument class, 933

Return function, 78, 99, 103, 343Return value

@functions, 76RevokeAccess method

NotesDatabase class, 861revokeAccess method

Database class, 1845Rich text fields

Formula Language, 63

Index-32

Rich text itemsaccessing in Java, 1645appending in Java, 2155creating in Java, 1930in LotusScript, 635

Rich text paragraph stylesin LotusScript, 643

Rich text stylesin LotusScript, 641

RichTextItem class, 1640, 1645, 2147RichTextParagraphStyle class,

1645, 2162RichTextStyle class, 1645, 2172RichTextTab class, 1645, 2179Right function, 109, 344RightBack function, 109, 345RightMargin property

NotesRichTextParagraphStyleclass, 1283

RichTextParagraphStyle class, 2167

Rolesadding in Java, 1702deleting in Java, 1704disabling in Java, 1732enabling in Java, 1733renaming in Java, 1710

Roles propertyACL class, 1701ACLEntry class, 1729NotesACL class, 731NotesACLEntry class, 760

RollbackTransactions methodODBCConnection class, 1113

Round function, 113, 346RowLines property

NotesView class, 1476View class, 2237

Ruler propertyNotesUIDocument class, 1378

Run-time errorsin a formula, 99LotusScript, 698

Run boxdefined, 34

Run methodNotesAgent class, 782

run methodAgent class, 1755

Runnable interfaces, 1692RunOnServer method

NotesAgent class, 783runOnServer method

Agent class, 1756

RunReadOnly propertyNotesEmbeddedObject

class, 1000

SSave method

NotesACL class, 739NotesAgent class, 784NotesDocument class, 969NotesOutline class, 1207NotesReplication class, 1258NotesUIDocument class, 1410

save methodACL class, 1711Agent class, 1757Document class, 1950Outline class, 2099Replication class, 2146

SavedData propertyAgentContext class, 1765NotesSession class, 1320

SaveFileDialog methodNotesUIWorkspace class, 1450

SaveMessageOnSend propertyNotesDocument class, 935

SaveNewVersion methodNotesUIDocument class, 1410

SaveToDisk propertyNotesItem class, 1041

Savinga file, 470a new version, 470a script, 42

SBCS, 390Scientific formats

ViewColumn class, 2299Scientific notations, 67Scope

of programmable objects, 3Script Area

completing a LotusScript%directive, 50

completing LotusScript blockstatements, 50

defined, 34editing text, 42moving insertion points, 40saving and deleting text, 42selecting text, 41setting text properties, 40table of mouse operations, 41using, 39

Script executionscontinuing, 54

Script Libraryin a Java agent, 44Java, 56LotusScript, 56programming events in, 57using, 56using LotusScript, 56

Scriptscontinuing execution, 55debugging LotusScript, 51deleting, 42flow of execution, 53overview, 1saving, 42versus a formula, 1where to use, 1writing, 6

Search methodNotesDatabase class, 862

search methodDatabase class, 1847

Searchingfor a document in Java, 1637for a document in

LotusScript, 612FTDomainSearch method in

Java, 1822FTSearch method in Java, 1823full-text in LotusScript, 616text in Script Editor, 42

Second function, 119, 347Section access formulas, 3, 18, 84Section title formulas, 3, 19, 84SectionCollapse command, 503SectionCollapseAll command, 503SectionDefineEditors command, 503SectionExpand command, 504SectionExpandAll command, 504SectionProperties command, 504SectionRemoveHeader

command, 505Security

ECL in @Commands, 397ECL in @Functions, 153

Select function, 349Select keyword, 79, 84, 103, 348SelectAll method, 1411SelectDocument method

NotesUIView class, 1426Selecting

a subprogram, 53text in Script Editor, 41

Index-33

Selection formulas, 3, 15writing, 15, 84

Send methodNotesDocument class, 972NotesUIDocument class, 1412

send methodDocument class, 1951

SendKeys statement, 552SentByAgent property

NotesDocument class, 936Server property

Database class, 1808NotesDatabase class, 816

ServerName propertyAgent class, 1749NotesAgent class, 777Session class, 2192

ServersFormula Language, 120requirements for running

Java, 1591Session class, 1594, 1647, 2182Sessions

accessing in Java, 1647accessing in LotusScript, 646accessing properties in Java, 1648accessing properties in

LotusScript, 646Set function, 350setAbstract method, 2133

Replication class, 2133SetAction method

NotesOutlineEntry class, 1219setAction method

OutlineEntry class, 2109setAdminReaderAuthor method

ACLEntry class, 1713setAdminServer method

ACLEntry class, 1714setAlias method

OutlineEntry, 2100OutlineEntry class, 2100

setAlignment methodRichTextParagraphStyle

class, 2164SetAnyDate method

NotesDateTime class, 898setAnyDate method

DateTime class, 1875SetAnyTime method

NotesDateTime class, 898setAnyTime method

DateTime class, 1876

setAuthors methodItem class, 2016

setAutoUpdate methodView class, 2225

setBold methodRichTextStyle class, 2174

setCacheSize methodViewNavigator class, 2336

setCanCreateDocuments methodACLEntry class, 1714

setCanCreateLSOrJavaAgentmethod

ACLEntry class, 1715setCanCreatePersonalAgent method

ACLEntry class, 1716setCanCreatePersonalFolder method

ACLEntry class, 1717setCanCreateSharedFolder method

ACLEntry class, 1719setCanDeleteDocuments method

ACLEntry class, 1719setCategories method

Database class, 1786setCertifierIDFile method

Registration class, 2114setColor method

RichTextStyle class, 2174setComment method

Outline class, 2089setCreateMailDb method

Registration class, 2114SetCurrentLocation command, 505SetCurrentLocation method

NotesUIWorkspace class, 1451setCutoffDelete method, 2135

Replication class, 2135setCutoffInterval method, 2135setDateTimeValue method

Item class, 2016setDelayUpdates method

Database class, 1794setDisabled method, 2136

Replication class, 2136SetDocField function, 103, 129, 351setDoNotBrowse method, 2137

Replication class, 2139setDoNotCatalog method, 2138

Replication class, 2138setDoScore method

Newsletter class, 2079setDoSubject method

Newsletter class, 2079

setEffects methodRichTextStyle class, 2175

setEnabled methodAgent class, 1740

setEncrypted methodItem class, 2018

setEncryptionKeys methodDocument class, 1899

setEncryptOnSend methodDocument class, 1902

setEndDateTime methodDateRange class, 1852

SetEnvironment function, 97, 103, 352

SetEnvironmentVar methodNotesSession class, 1338

setEnvironmentVar methodSession class, 2210

setExpiration methodRegistration class, 2115

SetField function, 103, 125, 353setFirstLineLeftMargin method

RichTextParagraphStyle class, 2165

setFolderReferencesEnabled methodDatabase class, 1792

setFont methodRichTextStyle class, 2176

setFontSize methodRichTextStyle class, 2177

setFormUsers methodForm class, 1990

setFrameText methodOutlineEntry class, 2103

setGroup methodACLEntry class, 1721, 1723

setHidden methodOutlineEntry class, 2105

setHideDesign method, 2139Replication class, 2139

setIDType methodRegistration class, 2115

setIgnoreDeletes method, 2140Replication class, 2140

setIgnoreDestDeletes method, 2141Replication class, 2141

setImagesText methodOutlineEntry, 2105OutlineEntry class, 2099

setInterLineSpacing methodRichTextParagraphStyle

class, 2165

Index-34

setInternetLevel methodACL class, 1697

setItalic methodRichTextStyle class, 2177

setLeftMargin methodRichTextParagraphStyle

class, 2166setLevel method

ACLEntry class, 1724setLocalDate method

DateTime class, 1861setLocalTime method

DateTime class, 1861setLogActions method

Log class, 2044setLogErrors method

Log class, 2045setMaxLevel method

ViewNavigator class, 2336setMinPasswordLength method

Registration class, 2116setMultiDbIndex method, 2142

Replication class, 2142setName method

ACLEntry class, 1726SetNamedElement method

NotesOutlineEntry class, 1220setNamedElement method

OutlineEntry class, 2110setNameObject method

ACLEntry class, 1727setNames method

Item class, 2020setNeverReplicate method

Replication class, 2143setNoChronos method

Replication class, 2143SetNoteLink method

NotesOutlineEntry class, 1220setNoteLink method

OutlineEntry class, 2111SetNow method

NotesDateTime class, 898setNow method

DateTime class, 1876setOrgUnit method

Registration class, 2117setOverwriteFile method

Log class, 2046setPagination method

RichTextParagraphStyle class, 2166

SetParameter methodODBCResultSet class, 1190

setParent methodForm class, 1996

setPriority method, 2144Replication class, 2143

SetProfileField function, 354setProgramName method

Log class, 2050setProtected method

Item class, 2021setProtectReaders method

Form class, 1992View class, 2232

setProtectUsers methodForm class, 1993

setPublicReader methodACLEntry class, 1722

setPublicWriter methodACLEntry class, 1723

setReaders methodItem class, 2021View class, 2236

setRegistrationLog methodRegistration class, 2117

setRegistrationServer methodRegistration class, 2117

setRightMargin methodRichTextParagraphStyle

class, 2167setSaveMessageOnSend method

Document class, 1905setSaveToDisk method

Item class, 2022setServerName method

Agent class, 1749setSigned method

Item class, 2022setSignOnSend method

Document class, 1908setSizeQuota method

Database class, 1810setSpacingAbove method

RichTextParagraphStyle class, 2168

setSpacingBelow methodRichTextParagraphStyle

class, 2168setStartDateTime method

DateRange class, 1853setStoreIDInAddressBook property

Registration class, 2118setStrikethrough method

RichTextStyle class, 2178setSubjectItemName method

Newsletter class, 2080

SetTab methodNotesRichTextParagraphStyle

class, 1287setTab method

RichTextParagraphStyle class, 2170

SetTabs methodNotesRichTextParagraphStyle

class, 1289setTabs method

RichTextParagraphStyle class,2169, 2170

SetTargetFrame function, 354SetTargetFrame method

NotesUIWorkspace class, 1452setText method

DateRange class, 1854setTitle method

Database class, 1812setType method

OutlineEntry, 2108OutlineEntry class, 2106

setUnderline methodRichTextStyle class, 2179

setUniformAccess methodACL class, 1699

setUniversalID methodDocument class, 1919

setUpdateAddressbook methodRegistration class, 2118

SetURL methodNotesOutlineEntry class, 1221

setURL methodOutlineEntry class, 2112

setUserType methodACLEntry class, 1730

SetValue methodODBCResultSet class, 1192

setValueDouble methodItem class, 2029

setValueInteger methodItem class, 2030

setValues methodItem class, 2031

setValueString methodItem class, 2033

Shadow effectNotesRichTextStyle class, 1293RichTextStyle class, 2175

Shared folderscreating, 1719

Short-cut keysReference tab, 39

Index-35

Show action formulas, 84ShowHideLinkPreview

command, 505ShowHideParentPreview

command, 506ShowHidePreviewPane

command, 506ShowProperties command, 506SiblingCount property

NotesViewEntry class, 1552ViewEntry class, 2313

Side effects, 76Sign function, 113, 356Sign method

NotesDocument class, 974sign method

Document class, 1954Signer property

Document class, 1918NotesDocument class, 937

SignOnSend propertyNotesDocument class, 938

SilentMode propertyODBCConnection class, 1101

Simple Action(s)icon, 38

Sin function, 114, 356sinitThread method, 1593

NotesThread class, 1692Size property

Database class, 1809Document class, 1918NotesDatabase class, 817NotesDocument class, 939

SizeQuota propertyDatabase class, 1810NotesDatabase class, 817

SmartIcons, 3, 5SmartIcons formulas, 85SmartIconsFloating command, 507SmartIconsNextSet command, 507Sorted column keys, 616Soundex function, 357Source property

EmbeddedObject class, 1982NotesEmbeddedObject

class, 1000Spaces

Formula Language, 62leading, 367redundant, 367trailing, 367

Spacing propertyNotesView class, 1477View class, 2237

SpacingAbove propertyNotesRichTextParagraphStyle

class, 1284RichTextParagraphStyle

class, 2168SpacingBelow property

NotesRichTextParagraphStyleclass, 1285

RichTextParagraphStyle class, 2168

Specifyingform and view names, 81

SpellCheck methodNotesUIDocument class, 1413

SQL propertyODBCQuery class, 1118

SQL statementsin LS:DO, 673

Sqrt function, 114, 358SSL, 1594StampAll method

NotesDocumentCollection class, 990

NotesViewEntryCollection class, 1568

stampAll methodDocumentCollection class, 1976ViewEntryCollection, 2331

StartDateTime propertyDateRange class, 1853NotesDateRange class, 878

Statementsseparators, 62

Step ExitLotusScript debugger, 54

stermThread method, 1593NotesThread class, 1692

StoreIDInAddressbook propertyNotesRegistration class, 1229Registration class, 2118

StrikeThrough propertyRichTextStyle class, 2178

Strikethrough propertyNotesRichTextStyle class, 1299

String item valuesgetting in Java, 1939

String operations, 104Strings

converting in Java, 1695StyleCycleKey command, 507

Stylesappending in rich text

items, 2156Sub block, 49Subforms

insert subform formula, 18SubjectItemName property

Newsletter class, 2080NotesNewsletter class, 1091

Subprogramsdefining, 48renaming, 43selecting, 53

Subroutinerenaming, 43

Subroutinescalling, 552

Subscript effectNotesRichTextStyle class, 1293RichTextStyle class, 2175

Subset function, 87, 358Substrings, 109Subtraction, 113Subtraction operator (-)

Formula Language, 69Success function, 99, 103, 359Sum function, 113, 359Superscript effect

NotesRichTextStyle class, 1293RichTextStyle class, 2175

SurName propertyName class, 2076

Surname propertyNotesName class, 1087

SwitchToID methodNotesRegistration class, 1243

switchToID methodRegistration class, 2129

Symbolsfor @Matches, 302for @Text, 362

Syntax@functions, 75errors in a formula, 99Formula Language, 61general rules, 62

TTabs

adding in Java, 2152clearing in Java, 2169, 2182in LotusScript, 645setting in Java, 2170

Index-36

Tabs propertyNotesRichTextParagraphStyle

class, 1286RichTextParagraphStyle

class, 2169Tan function, 114, 361Target property

Agent class, 1751NotesAgent class, 778

TemplateName propertyDatabase class, 1811NotesDatabase class, 818

Templatescreating from in Java, 1817getDesignTemplateName

method, 1790Temporary variables, 65Text

appending in Java, 2157editing, 42selecting, 41

Text constants, 66Text function, 105, 361Text operator, 71Text properties

Design panel, 40Text property

DateRange class, 1854Item class, 2026NotesDateRange class, 878NotesItem class, 1042

TextAlignCenter command, 508TextAlignFull command, 508TextAlignLeft command, 508TextAlignNone command, 509TextAlignRight command, 509TextBold command, 509TextBullet command, 510TextCycleSpacing command, 510TextEnlargeFont command, 511TextFont command, 511TextItalic command, 512TextNormal command, 512TextNumbers command, 513TextOutdent command, 513TextParagraph command, 514TextParagraphStyles command, 514TextPermanentPen command, 514TextReduceFont command, 515TextSetFontColor command, 515TextSetFontFace command, 516TextSetFontSize command, 517

TextSpacingDouble command, 517TextSpacingOneAndAHalf

command, 518TextSpacingSingle command, 518TextToNumber function, 363TextToTime function, 364TextUnderline command, 518ThousandsSep property

International class, 2010NotesInternational class, 1027

Threads, 1593NotesThread class, 1692

Timeformatting, 67in LotusScript, 655

Time/dateconstants, 67

Time function, 119, 365TimeDateFmt property

NotesViewColumn class, 1536TimeDateFormat property

ViewColumn class, 2301TimeDifference method

NotesDateTime class, 899timeDifference method

DateTime class, 1877TimeDifferenceDouble method

NotesDateTime class, 900timeDifferenceDouble method

DateTime class, 1877TimeFmt property

NotesViewColumn class, 1536ViewColumn class, 2301

TimeOnly propertyDateTime class, 1863NotesDateTime class, 889

Timersin LotusScript, 659

TimeSep propertyInternational class, 2010NotesInternational class, 1027

TimeZone propertyDateTime class, 1864International class, 2010NotesDateTime class, 889NotesInternational class, 1027

TimeZoneFmt propertyNotesViewColumn class, 1537ViewColumn class, 2302

Title bardefined, 34

Title propertyDatabase class, 1812Java, 2302NotesDatabase class, 819NotesViewColumn class,

1538, 2302Today function, 118, 366Today property

International class, 2011NotesInternational class, 1028

toJavaDate methodDateTime class, 1878

Tomorrow function, 118, 367Tomorrow property

International class, 2011NotesInternational class, 1028

ToolsCall command, 519ToolsCategorize command, 519ToolsHangUp command, 520ToolsMarkAllRead command, 520ToolsMarkAllUnread command, 520ToolsMarkSelectedRead

command, 521ToolsMarkSelectedUnread

comand, 521ToolsRefreshAllDocs command, 522ToolsRefreshSelectedDocs

command, 522ToolsReplicate command, 522ToolsRunBackgroundMacros

command, 523ToolsRunMacro command, 523ToolsScanUnreadChoose

command, 524ToolsScanUnreadPreferred

command, 524ToolsScanUnreadSelected

command, 524ToolsSetupLocation command, 525ToolsSetupMail command, 525ToolsSetupPorts command, 525ToolsSetupUserSetup command, 526ToolsSmartIcons command, 526ToolsSpellCheck command, 526ToolsUserLogoff command, 527TopLevelEntryCount property

NotesView class, 1478View class, 2238

toString methodJava classes, 1695

Trailing spaces, 367

Index-37

Transaction modein LS:DO, 696

Trigger propertyAgent class, 1753NotesAgent class, 779

Trim function, 112, 367Trimming

a string, 112True function, 368Truncate during replication, 2133Type block

Script Area, 49Type property

EmbeddedObject class, 1983Item class, 2026NotesEmbeddedObject

class, 1001NotesItem class, 1044NotesOutlineEntry class, 1217NotesRichTextTab class, 1303OutlineEntry class, 2108RichTextTab class, 2182

UUnary operators, 69, 71Unavailable function, 103, 369UndeleteDocument function, 369Underline property

NotesRichTextStyle class, 1300RichTextStyle class, 2179

UNIDsgetDocumentByUNID

method, 1828Uniform access

ACL class, 1699UniformAccess property

NotesACL class, 732Unique function, 87, 370Unique ID, 266Unique ID function, 243UniversalID property

Document class, 1919NotesDocument class, 939NotesView class, 1478NotesViewEntry class, 1552View class, 2238ViewEntry class, 2313

UnprocessedDocuments propertyAgentContext class, 1766NotesDatabase class, 820

UnprocessedFTSearch methodNotesDatabase class, 864

unprocessedFTSearch methodAgentContext class, 1768

UnprocessedSearch methodNotesDatabase class, 869

unprocessedSearch methodAgentContext class, 1772

UpdateAddressbook propertyNotesRegistration class, 1229Registration class, 2118

UpdateAll methodNotesDocumentCollection

class, 991NotesViewEntryCollection

class, 1569updateAll method

ViewEntryCollection, 2332UpdateFTIndex method

NotesDatabase class, 874updateFTIndex method

Database class, 1848UpdateProcessedDoc method

NotesSession class, 1339updateProcessedDoc method

AgentContext class, 1775UpdateRow method

ODBCResultSet class, 1194Updating

a full text index, 461UpperCase function, 112, 370URL property

NotesOutlineEntry class, 1218OutlineEntry class, 2108

URLGetHeader function, 371URLHistory function, 373URLOpen function, 374URLOpen method

NotesUIWorkspace class, 1452URLs

getDocumentByURL method, 1830

getting in Java, 1694getURLHeaderInfo method, 1836

UseLSXstatement, 666

UseLSX methodNotesUIWorkspace class, 1455

User environment, 120User interface, 33

formula window, 58Programmer's pane, 33

User names, 120UserAccess function, 377UserIDCertificates command, 527

UserIDClearPassword command, 527

UserIDCreateSafeCopy command, 528

UserIDEncryptionKeys command, 528

UserIDInfo command, 528UserIDMergeCopy command, 529UserIDSetPassword command, 529UserIDSwitch command, 529UserName function, 121, 379UserName property

NotesSession class, 1321Session class, 2193

UserNameLanguage function, 381UserNameList property

NotesSession class, 1322Session class, 2194

UserNameObject propertySession class, 2194

UserNamesList function, 382UseRowID property

ODBCQuery class, 1120UserPrivileges function, 383UserRoles function, 121, 383UserType property

ACLEntry class, 1730NotesACLEntry class, 761

Using@commands, 397@functions, 75, 101a formula, 83a list, 86AgentRunner, 45conditional statements, 90constants, 66debugger utilities, 55Java, 57JavaScript, 47keywords, 79LotusScript debugger, 52LotusScript in a script library, 56operators, 68script libraries, 56scripts and formulas, 1short-cut keys, 39syntax rules, 61the Errors box, 39the Info list, 37the Objects tab, 37the Reference tab, 38the script area, 39variables, 63

Index-38

VV2If function, 384V3EditNextField command, 530V3UserName function, 385ValidateInternetAddress

function, 386Value formulas, 4, 24

writing, 24ValueDouble property

Item class, 2029ValueInteger property

Item class, 2030ValueLength property

Item class, 2030NotesItem class, 1046

Values propertyItem class, 2031NotesItem class, 1046

ValueString propertyItem class, 2033

Variablesusing, 63using the variables panel, 55

Verbs propertyEmbeddedObject class, 1983NotesEmbeddedObject

class, 1002Verifier property

Document class, 1920NotesDocument class, 941

Version function, 121, 388Version number

Session class, 2190View class, 577, 1621, 2212View entries

accessing, 587Accessing in LotusScript, 587retrieving, 585retrieving multiple, 585

View entry collectionsaccessing, 590adding an entry, 591deleting an entry, 591removing a document, 593retrieving entries, 592searching for entries, 591

View NavigatorAccessing in LotusScript, 594

View navigatorsaccessing an entry, 595accessing an entry by

position, 598

accessing documents, 596creating, 586properties, 594

View propertyNotesOutlineEntry class, 1219NotesUIView class, 1424OutlineEntry class, 2109

ViewArrangeIcons command, 531ViewBelowFolders command, 531ViewBesideFolders commnd, 531ViewCertify command, 531ViewChange command, 532ViewCollapse command, 533ViewCollapseAll command, 533ViewColumn class, 1626, 2274ViewEntry class, 1628, 2304ViewEntryCollection class,

1629, 2314ViewExpand command, 534ViewExpandAll command, 534ViewExpandWithChildren

command, 534ViewHorizScrollBar command, 535ViewMoveName command, 535Viewname property

NotesUIView class, 1424ViewNavigator class, 1629, 2333ViewNavigatorsFolders

command, 535ViewNavigatorsNone

command, 536ViewRefresh method

NotesUIWorkspace class, 584, 1455

ViewRefreshFields command, 536ViewRefreshUnread command, 536ViewRenamePerson command, 537Views

accessing in Java, 1621accessing in LotusScript, 577accessing properties in Java, 1621accessing properties in

LotusScript, 578locating in Java, 1625locating in LotusScript, 580, 615naming in a formula, 81refreshing in LotusScript, 584removing in Java, 1631traversing in LotusScript, 615

Views propertyDatabase class, 1813NotesDatabase class, 577,

580, 824ViewShowFieldHelp command, 537ViewShowObject command, 537ViewShowOnlyCategories

command, 538ViewShowOnlySearchResults

command, 538ViewShowOnlySelected

command, 538ViewShowOnlyUnread

command, 539ViewShowPageBreaks

command, 539ViewShowRuler command, 539ViewShowSearchBar command, 539ViewShowServerNames

command, 540ViewShowUnread command, 540ViewSwitchForm command, 540ViewTitle function, 103, 122, 389Visibility interface, 1695Visual Basic

with LotusScript, 719

WWays to

handle an error, 98perform string operations, 104use a formula, 83use an operator, 68use constants, 66use syntax rules, 61use the script area, 39use variables, 63write a formula, 58write a message, 92

Weekday function, 118, 389Wide function, 390Width property

NotesViewColumn class, 1539ViewColumn class, 2302

Window title formulas, 3, 17, 84, 123WindowMaximize command, 541WindowMaximizeAll command, 541WindowMinimize command, 541WindowMinimizeAll command, 542

Index-39

WindowTitle propertyNotesUIDocument class, 1379

WindowWorkspace command, 542Word function, 110, 391WorkspaceProperties command, 542WorkspaceStackReplicaIcons

command, 543Workstation

Formula Language, 120Writing

a column formula, 16a default value formula, 23a field design formula, 22a form formula, 15a formula for SmartIcons, 5a formula in the Programmer's

pane, 58a hidden paragraph formula, 19a keyword field formula, 24a message, 92a message with @Prompt, 93a replication formula, 6a script and formula for a

button, 12a script and formula for

action, 10a script and formula for

events, 19a section access formula, 18a section title and hidden

paragraph formula, 19a section title formula, 19a selection formula, 15a value formula, 24a window title formula, 17an input translation formula, 23an input validation formula, 23an insert subform formula, 18JavaScript in a page header, 48LotusScript in the Programmer's

pane, 48scripts and formulas, 6

YYear function, 119, 392Yes function, 393Yesterday function, 118, 393Yesterday property

International class, 2012NotesInternational class, 1028

ZZone function, 119, 394ZoneTime property

DateTime class, 1866NotesDateTime class, 890

ZoomPreview command, 543

Index-40