Andrew Pollack's Blog

Technology, Family, Entertainment, Politics, and Random Noise

Lotscript Error Handling Library

By Andrew Pollack on 03/30/2008 at 12:26 PM EDT

This is a cleaned up version for your use -- in my own case, its a bit more complex as I use a logging database to log much of the agent activity I do.

In that case, the script library opens that database and automatically creates a document with fields for database name, agent name, start time, end time, etc. It also writes logging output to that file in any agent using with a debug_print() function used instead of "print" or "msgbox" throughout the agent. My version also handles the functionname as a stack, so the entire stack can be listed rather than just the current function.

So, here's my simplified version for you:

I understand there is an open source version of this as well -- mine has been in continual use since something like 1994 so it predates that open source one just a bit.


Using the technique below, I get the following advantages:

1. By just including the library, even if I set nothing, I get some level of information about errors.

2. If I remember to set the agent & database name in initialize of the agent, I get more information

3. If I remember to set & clear the functionname on entry and exit of functions and methods, I have complete detail on the location of the error. If not, I've got the name of the most recent one I did remember to set, which isn't great, but its better than nothing.

4. I can event set event monitors on the console to watch for "ERROR!" in the log output and send notifications out.

'Set these in Agent Initialize

'NCT_DBNAME ' ---------------- String. Set in agent Initialize as the name of the database.
'NCT_AGENTNAME ' ------------- String. Set in agent Initialize as the name of the agent or script.
'NCT_ISWEBAGENT ' ------------ Boolean. Set in agent Initialize causes the output to use msgbox instead of print.
'NCT_NORMALTERMINATION ' ----- Boolean. Set in agent Initialize to true, Set in agent Terminate to false
' if set to true when the script library terminate event runs, will flag that the agent didn't complete
' because even if the agent errors out, the script library termination event still fires.

'Ideally, in the initialize as well as any created subs, functions, and object methods, I wrap with code like this:

Sub whatever()
on error goto errorHandler
Dim PrevFunctionName as String
NCT_FUNCTIONNAME = "ThisFunctionName"

exit Sub
NCT_ReportError(erl, error$, "")
resume allDone
End Sub

' ***************************************** SCRIPT LIBRARY *********************************

Private NCT_DBNAME = "DatabaseName"
Private NCT_AGENTNAME = "AgentName"
Private NCT_ISWEBAGENT as Boolean
Private NCT_FUNCTIONNAME as String
private NCT_NORMALTERMINATION as boolean

Sub initialize
on error goto errorHandler
' probably not much code here, as it is the initialize section of the script library
exit Sub
NCT_ReportError(erl, error$, "Default Error Handler.")
resume allDone
End Sub

Sub NCT_ReportError( erln as Integer, errortxt as String, byVal AddtlTxt as String)
msgbox("ERROR! " & NCT_DBNAME & " [" & NCT_AGENTNAME & "] " & NCT_FUNCTIONNAME & " line: " & erln & " - " & errortxt & ". " & addtltxt)
print ("ERROR! " & NCT_DBNAME & " [" & NCT_AGENTNAME & "] " & NCT_FUNCTIONNAME & " at line: " & erln & " - " & errortxt & ". " & addtltxt)
End If
End Sub

Sub Termination
close ' closes any open text files
if NCT_NORMALTERMINATION = false then NCT_ReportError("Agent Terminated Abnormally.")
End Sub
' ************************************** END SCRIPT LIBRARY *********************************

There are  - loading -  comments....

re: Lotscript Error LOGGING LibraryBy Thomas Bahn on 03/30/2008 at 03:18 PM EDT
Hi Andrew,

thank you for your contribution to the community. The main point is DOING some
kind of error logging or handling.

I have just one point: Your library is about error LOGGING only, not error
handling. This would include some "extension" points or settings for at least
some errors, which can be handled in some way - this could be just as simple as
to ignore an "Document not found" error in a function using GetDocumentByUNID
and returning Nothing.

As written on Nathan's blog: using OOP here - with derived classes - could
offer such extension points in your library. As far as I remember, Julian
Robichaux's OpenLog works this way.

Again, the most important part in error handling/logging is: JUST DO IT.

Fair Enough...By Andrew Pollack on 03/30/2008 at 05:28 PM EDT
This part is clearly about logging the error so that I can do something to
prevent it happening. Obviously its meant to be extensible enough for you to
do your own handling around it.

In a block of code I may even use another "on error" statement to handle errors
in that specific block. This is meant as a global wrapper to make diagnostics
re: Fair Enough...By Thomas Bahn on 03/30/2008 at 08:23 PM EDT
second On Error statement:
- You have to restore to original handler after the block of code, you want to
handle differently.
- You can call only one handler at a time, e.g. it's not (simple) possible to
first log the error, then try a cluster mate.
- It's hard to change behavior at runtime.

We have a priority queue of ErrorHandlers (objects of class ErrorHandler or of
sub-classes of it). When an error occurs, the handler with the highest priority
is ask, whether it is interested in this kind of error, and if it is, given the
occasion to handle it. If it returns that it handled the error successfully,
the code execution is resumed. Else the next error handler is asked...
When no handler in the queue could handle the error, the code execution is
stopped (End).

This way, you can register additional error handlers at runtime - depending on
configuration, state or whatever. You can activate/deactivate them for specific
code blocks.

The LoggingErrorHandler - one of the standard sub-classes of ErrorHandler - has
quite a high priority, thus is executed very early in this chain. But it never
"handles" an error (returns false everytime), and the next error handler is

A developer can create own sub-classes of ErrorHandler for their specific
needs. For example, if a document contains a UNID of a "version" document, then
he could create a VersionNotFoundErrorHandler for the access to the version
document. This enables domain specific error handling classes! :-D

This, Thomas, is the problem with posting simple code.By Andrew Pollack on 03/30/2008 at 08:53 PM EDT
The coded posted here is designed to be simple, it isn't designed to be the
ultimate error handling code.

Obviously given your knowledge I'm not teaching you new things with this post.
There are many here, however, for whom several things about what I've posted
are new.

If I were to create and post an entire object model with derived classes and
extensible call out points to be used generically for everyone's database,
would I be helping anyone?

There are tools like that out there for download.

Hopefully, what I've got here which easily can be read on one screen, will help
many people understand the core concepts and write better code.

Re-using some else's work is terrific. It doesn't always teach much though.
re: This, Thomas, is the problem with posting simple code.By Thomas Bahn on 03/31/2008 at 03:18 AM EDT
Hi Andrew,

I'm so sorry. I didn't want to insult you. As you wrote, its a simplified
version. And as I wrote: The main point is to DO some kind of error

You are one of the most value-able members of the Lotus community. And NCT
Remember me is prove of your mastery.

no no, not insulted. Just setting the discussion.By Andrew Pollack on 03/31/2008 at 06:56 AM EDT
Thomas, I wasn't insulted by your comments at all. I'm just trying to frame
the discussion so you (and others who read here) understand the goal of what I
re: Fair Enough...By Thomas Bahn on 03/30/2008 at 08:40 PM EDT
... and more than one ErrorHandler is executed (when the one before didn't
handle the error).

We have a standard library for back-end utility functions, which adds a
LoggingErrorHandler, and one for front-end utility functions, which adds a
UserDialogErrorHandler. Other out-of-the-box subclasses are e. g.
MailNotificationErrorHandler and IgnoreErrorHandler.
re: Lotscript Error Handling LibraryBy Mark Haller on 03/31/2008 at 09:53 AM EDT
Hey Andrew

Nice bit of code, all wrapped up and cute :-)

You could derive NCT_FUNCTIONNAME from Lsi_info(2) - that way, you don't have
to code up the function name every time, LS just does it for you :-)

Just replace NCT_FUNCTIONAME = "ThisFunctionName" with


Nice trick.By Andrew Pollack on 03/31/2008 at 03:22 PM EDT
Lsi_Info() is undocumented, last I knew, but it does seem like a good use to
re: Lotscript Error Handling LibraryBy Mark Haller on 03/31/2008 at 09:54 AM EDT
Hey Andrew

Nice bit of code, all wrapped up and cute :-)

You could derive NCT_FUNCTIONNAME from Lsi_info(2) - that way, you don't have
to code up the function name every time, LS just does it for you :-)

Just replace NCT_FUNCTIONAME = "ThisFunctionName" with


re: Lotscript Error Handling LibraryBy Bruce Perry on 03/31/2008 at 05:09 PM EDT
Andrew, have you looked at OpenLog from OpenNTF?

I've been very pleased with it. People at Lotusphere were saying it has been
used in some very large production environments.

Other Recent Stories...

  1. 05/05/2016Is the growing social-sourced economy the modern back door into socialism?Is the growing social-sourced economy the modern back door into socialism? I read a really insightful post a couple of days ago that suggested the use of social network funding sites like “Go Fund Me” and “Kickstarter” have come about and gained popularity in part because the existing economy in no longer serving its purpose for anyone who isn’t already wealthy. Have the traditional ways to get new ventures funded become closed to all but a few who aren’t already connected to them and so onerous as to make ...... 
  2. 04/20/2016Want to be whitelisted? Here are some sensible rules for web site advertisingAn increasing number of websites are now detecting when users have ad-blocking enabled, and refuse to show content unless you "whitelist" their site (disable your ad-blocking for them). I think that is a fair decision on their part, it's how they pay for the site. However, if you want me (and many others) to white list your site, there are some rules you should follow. If you violate these rules, I won't whitelist your site, I'll just find content elsewhere. 1. The total space taken up by advertisements ...... 
  3. 12/30/2015Fantastic new series on Syfy called “The Expanse” – for people who love traditional science fiction[] “The Expanse” is a new science fiction series being broadcast onthe Syfy channelthis winter. It’s closely based on a series of books by author James S. A. Corey beginning with “Leviathan Wakes”. There are 5 books in the “Expanse” series so far. If you’re a fan of the novels you’ll appreciate how closely the books are followed.TIP: The first five episodes are already available on If you’re having trouble getting into the characters and plot, use those to get up to speed.The worlds created for ...... 
  4. 10/20/2015My suggestion is to stay away from PayAnywhere(dot)com  
  5. 08/07/2015Here is one for you VMWARE gurus - particularly if you run ESXi without fancy drive arrays 
  6. 08/06/2015The Killer of Orphans (Orphan Documents) 
  7. 06/02/2015Homeopathic Marketing: Traveler on my Android is now calling itself VERSE. Allow me to translate that for the IBM Notes community... 
  8. 03/17/2015A review of British Airways Premium Economy Service – How to destroy customer goodwill all at once 
  9. 02/26/2015There's a bug in how @TextToTime() and @ToTime() process date strings related to international standards and browser settings. 
  10. 01/21/2015Delivering two new presentations at Developer Camp (EntwicklerCamp) 2015 in Germany 
Click here for more articles.....

pen icon Comment Entry
Your Name
*Your Email
* Your email address is required, but not displayed.
Your thoughts....
Remember Me  

Please wait while your document is saved.