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. 01/26/2023Better Running VirtualBox or VMWARE Virtual Machines on Windows 10+ Forgive me, Reader, for I have sinned. I has been nearly 3 years since my last blog entry. The truth is, I haven't had much to say that was worthy of more than a basic social media post -- until today. For my current work, I was assigned a new laptop. It's a real powerhouse machine with 14 processor cores and 64 gigs of ram. It should be perfect for running my development environment in a virtual machine, but it wasn't. VirtualBox was barely starting, and no matter how many features I turned off, it could ...... 
  2. 04/04/2020How many Ventilators for the price of those tanks the Pentagon didn't even want?This goes WAY beyond Trump or Obama. This is decades of poor planning and poor use of funds. Certainly it should have been addressed in the Trump, Obama, Bush, Clinton, Bush, and Reagan administrations -- all of which were well aware of the implications of a pandemic. I want a military prepared to help us, not just hurt other people. As an American I expect that with the ridiculous funding of our military might, we are prepared for damn near everything. Not just killing people and breaking things, but ...... 
  3. 01/28/2020Copyright Troll WarningThere's a copyright troll firm that has automated reverse-image searches and goes around looking for any posted images that they can make a quick copyright claim on. This is not quite a scam because it's technically legal, but it's run very much like a scam. This company works with a few "clients" that have vast repositories of copyrighted images. The trolls do a reverse web search on those images looking for hits. When they find one on a site that looks like someone they can scare, they work it like ...... 
  4. 03/26/2019Undestanding how OAUTH scopes will bring the concept of APPS to your Domino server 
  5. 02/05/2019Toro Yard Equipment - Not really a premium brand as far as I am concerned 
  6. 10/08/2018Will you be at the NYC Launch Event for HCL Domino v10 -- Find me! 
  7. 09/04/2018With two big projects on hold, I suddenly find myself very available for new short and long term projects.  
  8. 07/13/2018Who is HCL and why is it a good thing that they are now the ones behind Notes and Domino? 
  9. 03/21/2018Domino Apps on IOS is a Game Changer. Quit holding back. 
  10. 02/15/2018Andrew’s Proposed Gun Laws 
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.