When you do as much work with the Notes API as we do, you'll end up running into errors at one point or another. When writing programs in C or C++, you can translate the error number to a string pretty easily. But we're doing more and more with the API in LotusScript (we've posted a tip on refreshing the design of a database in LotusScript and have many more examples). In this situation, we needed to be able to translate an error number into a text error message.

The most portable way to do all of this is through a script library containing a custom class. That script library can be inherited to any database you need and we'll show how to make the class calls to get the error string.

Create a script library called "Notes API Error". All the code goes into the (Declarations) area of the script library:

Declare Function W32_OSLoadString Lib "nnotes.dll" Alias "OSLoadString" (Byval handle As Integer, _
Byval errNum As Integer, Byval buffer As Lmbcs String, Byval textLen As Integer) As Integer
Const ERR_MASK = &H3FFF

Class NotesAPIError
   Private errNum As Integer
   
   Public Sub New(errorNum As Integer)
      Me.errNum = errorNum
   End Sub
   
   Public Function Message As String
      Dim temp As Integer
      Dim result As String
      temp = Me.errNum And ERR_MASK
      result = String$(255, 0)
      temp = W32_OSLoadString(0, temp, result, Len(result))
      Message = result
   End Function
   
End Class

If you aren't familiar with using the Notes API in LotusScript, then this is a good introduction. You have to declare the external API function call (refer to the documentation that comes with the Notes API for the function names and parameter types). Most times you pass variables by value (the Byval keyword) instead of by reference as is done in "normal" LotusScript. Strings often times need the Lmbcs keyword to specify the character set.

A custom class is going to have a New subroutine called when a new instance of the object is created. In this case, we want the new instance of the class to pass in the error number. We set the private variable "errNum" to the passed-in value. Since the variable is private, it can only be used within the class. In other words, if your agent creates a new NotesAPIError variable, you will not be able to access the .errNum property from the object. We have a habit of using the optional Me keyword to indicate that we're talking about the class object instead of a local variable.

When ready, the function (object property) Message will be called. This function adjusts the error number to be something that the external C function can use and then sets up a return area of 255 character 0's (null characters). That's another thing to be aware of when dealing with external C calls in LotusScript (any C call; not just for the Notes API). If you are going to be returning a string, you have to establish the size the string through a method like this. LotusScript dynamically adjusts the string size and grabs the memory for you, but C doesn't work that way.

After the return string size has been set up, then a call to the external C function is made. You should refer to the API documentation for details, but this function takes the adjusted error number and populates the string with text version of the error number.

Once the error string has been populated, that can be returned as the property/function value.

To test out the agent, create a new agent. In the (Options) section of the agent, include the script library: Use "Notes API Error". The rest of the code goes into the Initialize section:

Sub Initialize
   Dim errorNum As String
   Dim classVar As NotesAPIError
   Dim result As String
   errorNum = Inputbox("Enter the Notes API Error Number", "Enter Number", "")
   If errorNum = "" Then Exit Sub
   Set classVar = New NotesAPIError(Val(errorNum))
   result = "The error message for error number " & errorNum & " is:" & Chr$(10) & classVar.Message
   Msgbox result, 64, "Result"
End Sub

You are prompted for the error number. If you cancel or don't enter anything, the code quits. Otherwise, it sets up a new class object, passing in the value of the text error number. Then a result prompt is created using the Message property of the class object.

To try it out, use error number 18865. This error happens when an unauthorized user tries to do a remote console command. This error number will verify the script library code. Error number 0 means no error, and error number 1 gives you the Notes release string. There are so many error numbers, this code comes in handy when working with the Notes API in LotusScript.