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. 09/04/2018With two big projects on hold, I suddenly find myself very available for new short and long term projects. In twenty five years, I don't think I've ever written an entry like this, but if you need the kind of work I do now would be a great time to get in touch. Both of the big projects I had lined up for late summer and early fall have been placed on hold and will be that way for a while. With the kids now all off at college and careers, I'm open to more travel than such than I have been in decades, but unless something else comes along, I'll be here working on updates to Second Signal and other things that ...... 
  2. 07/13/2018Who is HCL and why is it a good thing that they are now the ones behind Notes and Domino?We need to address some biases here. IBM has made a deal under which the Notes & Domino software and intellectual property is now being developed and maintained by HCL America. HCL America is part of the very large "HCL Technologies" company that has grown from its roots in India to become an 8 Billion Dollar company with a global presence in the IT Industry. You could be excused for initially believing, as many people do when they hear this, that "they've outsourced the code to India where they'll milk it ...... 
  3. 03/21/2018Domino Apps on IOS is a Game Changer. Quit holding back.BOOM. This will be as important for the platform as Traveler. If your company has ditched Notes and Domino, I feel sorry for you. For companies that do use Notes/Domino this is a game changer and Apple should be paying attention. Here's why: There are hundreds of little Notes client applications you'd never spend the time and money to build and deploy for your internal user base on IOS that we use Notes for all the time (those of us still using it). Now, those are suddenly ALL available on the iPad. ...... 
  4. 02/15/2018Andrew’s Proposed Gun Laws 
  5. 05/05/2016Is the growing social-sourced economy the modern back door into socialism? 
  6. 04/20/2016Want to be whitelisted? Here are some sensible rules for web site advertising 
  7. 12/30/2015Fantastic new series on Syfy called “The Expanse” – for people who love traditional science fiction 
  8. 10/20/2015My suggestion is to stay away from PayAnywhere(dot)com  
  9. 08/07/2015Here is one for you VMWARE gurus - particularly if you run ESXi without fancy drive arrays 
  10. 08/06/2015The Killer of Orphans (Orphan Documents) 
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.