SearchDomino.com June 11, 2001 Developer Tip ================================================= ------------------------------------------------- Sponsored By: Ives Development, Inc. ------------------------------------------------- Visit us at pedestals 4-7 at Lotus DevCon 2001. We'll show you how to overcome the challenges of version control, team development, configuration management, debugging, code maintenance and reuse, quality assurance, migrating applications and more with the TeamStudio Design System. Plus you'll get a sneak peek at our latest tool?to be announced at the show. And you can check out our TeamStudio PartnerSource tools! Don't wait any longer to discover how you can improve the quality of your applications. To learn about the activities we have planned at Lotus DevCon 2001, visit http://www.teamstudio.com/devcon. ================================================= Feature Tip ================================================= Title: LotusScript 101 - Custom Functions: The most powerful feature most developers never use This tip was submitted by Kevin Ford, our searchDomino.com expert and a Lotus Notes architect and developer at IBM in Poughkeepsie, N.Y. If you have a specific application topic that you'd like Kevin to cover or comments about a tip, email us at [EMAIL PROTECTED], or pose an application question to Kevin in Ask the Experts section: http://searchdomino.techtarget.com/ateQuestion/0,289624,sid4_tax282449,00.html I see a lot of Notes/Domino developers that use LotusScript but don't understand or use customized Functions. This is a real shame, because it is one of the most powerful tools that we have when writing modular code. It is, in fact, required to define modular code. Instead of declaring global variables and calling SubRoutines to modify these variables, create a function that you can pass a value to and will return a value when it is done doing what it is supposed to. Here's the format for the custom function... (I am only going to talk about the simplest implementation.) Function FunctionName( Parameters ) as ReturnType Statements Statements End Function At any time during a function, you can make the function return a value by simply treating the FunctionName like a variable. For example, the statement in parenthesis (FunctionName = "Red") will make the function return the value "Red" to the Call statement that called the function in the first place. For the purpose of this example, my hypothetical function will prorate a salary over two time periods with two pay rates. It will accept three variables; CurrentPayRate, NewPayRate, IncreaseMonth. It will return the prorated salary. Obviously, you could do a lot more sophisticated calculations, but this should get the point across. BELOW IS THE CODE FOR THE FUNCTION ITSELF: ----------------------------------------- Function Prorate( CurrentPayRate As Double, NewPayRate As Double, IncreaseMonth As Integer ) As Double '---- BEGIN simple error checking (Return 0 by using "Prorate = 0" If Not Isnumeric(CurrentPayRate) Or Not Isnumeric(NewPayRate) Or Not Isnumeric(IncreaseMonth) Then Msgbox "You must supply a number for each field", 0, "Invalid Values" Prorate = 0 Exit Function Elseif CurrentPayRate = 0 Or NewPayRate = 0 Or IncreaseMonth = 0 Then Msgbox "You must supply a number for each field", 0, "Invalid Values" Prorate = 0 Exit Function End If '---- END simple error checking '---- BEGIN Calculations on variables that were passed to function ---- CurrentMonthlyRate = (CurrentPayRate / 12) NewMonthlyRate = (NewPayRate / 12) CurrentDollars = (CurrentMonthlyRate * (IncreaseMonth-1) ) NewDollars = ( NewMonthlyRate * (12 - (IncreaseMonth-1) ) ) '---- END Calculations on variables that were passed to function ---- Prorate = (CurrentDollars + NewDollars) End Function BELOW IS THE CODE FOR THE STATEMENTS THAT CALL THE FUNCTION: ----------------------------------------------------------- Sub Click(Source As Button) Set workspace = New NotesUIWorkspace Set uidoc = workspace.CurrentDocument currentPayRate = Cdbl(uidoc.FieldGetText("currentPayRate")) newPayRate = Cdbl(uidoc.FieldGetText("newPayRate")) increaseMonth = Cint(uidoc.FieldGetText("increaseMonth")) NewSalary = ProRate( currentPayRate, newPayRate, increaseMonth ) If NewSalary > 0 Then Msgbox Cstr( NewSalary ) End If End Sub For the above example, I created a form with three fields (named in Click event above). I then created a button marked ProRate. From any LotusScript editing pane for the button, simply typing the word "function functionName" (without quotes) and pressing enter will create a new event in that object and you can begin working immediately. After creating the function as above, I simply modified the click event of the button to call the ProRate function with the proper parameters (Data Types are of course critical). I declared all of my variables in the Global Declarations not as a matter of good practice but just to keep the code smaller for this example. Using a function for a single use as in the button example is not very effective, but if you can do it, you can start creating your own functions that you can call iteratively and save yourself a lot of time in future programming. It would also allow you to create much more compact code. An example might be to pass a back-end NotesDocument object to a function that validates and returns a boolean value of whether or not the document passed the test. Roughly, it would look like this... Function ValidateDoc( doc_in_question as NotesDocument ) As Integer ValidateDoc = 0 if doc_in_question is nothing then Exit Function End If If not doc_in_question.HasItem("ImportantFieldName") then Exit Function End If '---- My two criteria passed, so I assume success and set to 1 then return ValidateDoc = 1 End Function It would be called from any line of LotusScript like this. if ValidateDoc( MyDoc ) = False then MsgBox "It Failed" Else MsgBox "It Worked" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ================================================= NEWLY POSTED DEVELOPER TIPS: ================================================= We posted 13 new tips last week. Thanks for all your tips and keep them coming! Agent Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283834_alpD_idx0,00.html [1] Scheduled local mail archive from server based mail file [2] Negative Database Size in R4.x Domino Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283837_alpD_idx0,00.html [1] Passing variables to agents Formula Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283836_alpD_idx0,00.html [1] Detecting a changed field value between document saves [2] Notes client view hit counter HTML Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283838_alpD_idx0,00.html [1] Display more documents in the same row on a web view JavaScript Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283840_alpD_idx0,00.html [1] Automatically launch an attachment Other Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283842_alpD_idx0,00.html [1] Making Notes workspace your default Script Category http://searchdomino.techtarget.com/tipsIndex/0,289482,sid4_tax283841_alpD_idx0,00.html [1] Changing embedded views for readers [2] Add or Remove Prohibit design refresh [3] Get all field names of a Notes form [4] ODBC connection to external database [5] 'TEST MODE' - so obviously simple! ================================================= FEATURED BOOK: ================================================= Notes and Domino R5 Developer's Guide to Building Applications By Matt Riggsby Notes and Domino provide the technology to solve pressing business problems. But you have to provide the know-how, and this book gives you just that--the hands-on knowledge you need to put the powerful features of R5 to work in effective, fine-tuned solutions that improve the way your organization shares information. http://www.digitalguru.com/dgstore/product.asp?sku=0782128246&dept%5Fid=288&ac%5Fid=60&accountnumber=&couponnumber= ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------- JUNE'S TIP PRIZE! ------------------------------------------------- Will you be sporting the Secret Agent Man Digital Watch? This watch isn't just a watch, it's a high-tech digital device that has everything you'd ever want in a watch and more. Some of the innovative features include: *Storage of up to 100 internet/email addresses, phone numbers or other memos *3 alarms *Self-adjusting calendar *Water resistance up to 100 meters *Optional vertical or horizontal display *Random message feature with 45 preprogrammed greetings *A retail value of $200. Submit a Developer tip in June, and let's see if you can be the latest Secret Agent Man. http://searchdomino.techtarget.com/tipsContest/0,289488,sid4_prz546242_cts546237,00.html ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ================================================= Disclaimer: These tips are submitted by your Domino peers. Our tips services and online tips exchange are a way for you to learn from other IT professionals and share technical advice and expertise with your peers. Techtarget.com provides the infrastructure to facilitate this sharing of information. However, we can't guarantee the accuracy and validity of the material submitted. You agree that your use of the searchDomino.com tips services and your reliance on any questions, answers, information or other materials received through searchDomino.com will be at your own risk. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ================================================= NOTIFY US WITH FEEDBACK ================================================= Send us your tips feedback! Cast your vote and send us your tips comments. If you have vital code information or other comments you'd like to add to one of our online tips, send your comments to [EMAIL PROTECTED], and we'll add your User Feedback to the online tip! ================================================= If you would like to sponsor this or any TechTarget newsletter, please contact Gabrielle DeRussy at [EMAIL PROTECTED] ================================================= If you no longer wish to receive this newsletter simply reply to this message with "REMOVE" in the subject line. Or, visit http://searchDomino.techtarget.com/register and adjust your subscriptions accordingly. If you choose to unsubscribe using our automated processing, you must send the "REMOVE" request from the email account to which this newsletter was delivered. Please allow 24 hours for your "REMOVE" request to be processed.
