Category Archives: IBM/Lotus

In a recent discussion thread in one of the forums on IBM developerWorks, the issue of which is faster, doc.GetItemValue() or viewentry.ColumnValues(). I decided to test this, using two Lotusscript agents, created to be as similar as possible, working against the same view of the same database.

First, here is Agent #1, using ColumnValues() to get the value we are looking for from the first column of the view. This agent took 66.3 seconds to run, and below you can see exactly how that time was spent:

And this is Agent #2, identical to Agent #1, except two lines, first getting the NotesDocument from the view entry, and then using GetItemValue() to get the value out of the document. This agent took 225.8 seconds to run:

In both agents, the call to get the next document in the ViewEntryCollection takes about 60 seconds. As you can see, the 30,000 calls to GetColumnValues() in agent #1 takes pretty much no time — 1.3 seconds — while it takes 133 seconds to open the 30,000 documents and read the value of the field from each one in agent #2. Almost exactly 100 times longer!

In agent 2, you also have to add 26 seconds to get the NotesDocument object from the ViewEntry object.

I hope this settles the discussion.

Yesterday I blogged about a simple class to parse file names, and that inspired me to improve it and add some functionality, which will actually come in handy for a project at work shortly.

The class is pretty self-explanatory, there is really nothing complicated in the code.
When the class is initialized, if a path to a directory (i.e. ending with \) is passed to the constructor the directory is created if it does not exist. If the directory exist, there are functions to copy or move both single files or all files in the directory. Directories can also be deleted using the RemoveDir method.
In addition, there are properties to get the path, file name, extension and file size (in bytes) of the file (if the class was initialized with a file name).

Here is an agent with some examples of how to call the class:

Option Public
Option Declare
Use "Class.FileFunctions"

Sub Initialize
  Dim file As FileObject
  Dim cnt As Integer
  Dim success As Boolean 

  '*** Create new file object
  Set file = New FileObject("D:\Downloads\Downloads\MERP\Assassins of Dol Amroth.pdf")

  '*** Copy the file to another (new) directory
  Call file.CopyTo("D:\Downloads\MERP1\", file.FileName)

  '*** Move the file to a new location and replace space with + in file name
  Call file.MoveTo("D:\Downloads\MERP2\", Replace(file.FileName," ","+"))

  '*** Create a new directory if it does not exist
  Set file = New FileObject("D:\Downloads\MERP3\Test\")

  '*** Copy all files in specified directory to another directory
  Set file = New FileObject("D:\Downloads\Downloads\MERP\")
  cnt = file.CopyAllTo("D:\Downloads\MERP\Backup\")
  MsgBox "Copied " & cnt & " files."

  '*** Move all files in the previously specified directory to another location
  cnt = file.MoveAllTo("D:\Downloads\Middle-Earth Role Playing Game\")
  MsgBox "Moved " & cnt & " files."

  '*** Remove D:\Downloads\Downloads\MERP\
  Call file.RemoveDir("")

  '*** Remove D:\Downloads\MERP3\ and Test directory that we created earlier
  success = file.RemoveDir("D:\Downloads\MERP3\Test\")
  If success = True Then
    success = file.RemoveDir("D:\Downloads\MERP3\")
    If success = False Then
      MsgBox "Failed to delete D:\Downloads\MERP3\"
    End If
  Else
    MsgBox "Failed to delete D:\Downloads\MERP3\Test\"
  End If
End Sub

Below is the class itself, I put it in a script library called Class.FileFunctions.

%REM
  Copyright (c) Karl-Henry Martinsson 2012.
  Some code copyright Andre Guirard (see below).
  You are free to use and modify my code, as long as you keep
  all copyright info intact. If you improve the code, please
  consider sharing it back to the community.
%END REM

Option Public
Option Declare

Type FileDetails
  path As String
  filename As String  
  extension As String
  filesize As Long
End Type

Class FileObject
  Private file As FileDetails
  Public silent As Boolean
  
  Public Sub New(filepathname As String)
    silent = False
    FullPathName = filepathname
    If file.FileName = "" Then
      If file.Path <> "" Then
        On Error 76 GoTo parentDoesNotExist 
        'No filename but path, then we create that directory (if missing)
        If Dir$(file.Path,16)="" Then
createDirectory:  
          Call MakeDir(file.Path)
        End If
      End If
      file.FileSize = 0 
    Else
      file.FileSize = FileLen(filepathname)
    End If
    Exit Sub
parentDoesNotExist:          
    Resume createDirectory  
  End Sub
  
  
  Public Property Set FileName As String
    file.FileName = FileName
    file.Extension = StrRightBack(FileName,".")
  End Property
  
  Public Property Get FileName As String
    FileName = file.FileName  
  End Property
  
  
  Public Property Get Extension As String
    Extension = file.Extension  
  End Property
  
  Public Property Set Extension As String
    file.Extension = Extension   
  End Property
  
  
  Public Property Set FilePath As String
    file.Path = FilePath  
    If Right(file.Path,1)<>"\" Then
      file.Path = file.Path & "\"
    End If
  End Property
  
  Public Property Get FilePath As String
    FilePath = file.Path  
  End Property
  
  
  Public Property Set FullPathName As String
    Me.FilePath = StrLeftBack(FullPathName,"\")
    Me.FileName = StrRightBack(FullPathName,"\")
  End Property
  
  Public Property Get FullPathName As String
    FullPathName = file.Path & file.FileName  
  End Property
  
  
  Public Function CopyTo(ByVal newpath As String, ByVal newname As String) As Boolean
    '*** Check if both arguments are blank, then exit
    If FullTrim(newpath) = "" Then
      If FullTrim(newpath) = "" Then
        CopyTo = False
        Exit Function
      End If   
    End If
    If FullTrim(newpath) = "" Then
      newpath = file.Path
    End If  
    If FullTrim(newname) = "" Then
      newname = file.FileName 
    End If  
    Call MakeDir(newpath)
    On Error GoTo errHandlerCopyTo
    FileCopy me.FullPathName, newpath + newname
    If silent = False Then
      Print "Copied " & filename & " from " & file.Path & " to " & newpath
    End If
    CopyTo = True
exitFunctionCopyTo:
    Exit Function
errHandlerCopyTo:
    CopyTo = False
    Resume exitFunctionCopyTo
  End Function
  
  
  Public Function MoveTo(ByVal newpath As String, ByVal newname As String) As Boolean
    '*** Check if both arguments are blank, then exit
    If FullTrim(newpath) = "" Then
      If FullTrim(newpath) = "" Then
        MoveTo = False
        Exit Function
      End If   
    End If
    If FullTrim(newpath) = "" Then
      newpath = file.Path
    End If  
    If FullTrim(newname) = "" Then
      newname = file.FileName 
    End If
    Call MakeDir(newpath)
    On Error GoTo errHandlerMoveTo
    FileCopy me.FullPathName, newpath + newname
    Kill me.FullPathName
    If silent = False Then
      Print "Moved " & filename & " from " & file.Path & " to " & newpath
    End If
    
    MoveTo = True
exitFunctionMoveTo:
    Exit Function
errHandlerMoveTo:
    MoveTo = False
    Resume exitFunctionMoveTo
  End Function


  Public Function CopyAllTo(ByVal newpath As String) As Integer
    Dim filename As String
    Dim filecount As Integer
    '*** Check if both arguments are blank, then exit
    If FullTrim(newpath) = "" Then
      If FullTrim(newpath) = "" Then
        CopyAllTo = 0
        Exit Function
      End If   
    End If
    If FullTrim(newpath) = "" Then
      newpath = file.Path
    End If  
    Call MakeDir(newpath)
    On Error GoTo errHandlerCopyAllTo
    filename = Dir$(file.Path,2)  ' Include hidden files
    Do until filename=""
      FileCopy file.Path + filename, newpath + filename
      If silent = False Then
        Print "Copying " & filename & " from " & file.Path & " to " & newpath
      End If
      filecount = filecount + 1
      filename = Dir$()
    Loop
    CopyAllTo = filecount
exitFunctionCopyAllTo:
    Print "Copied " & filecount & " files"
    Exit Function
errHandlerCopyAllTo:
    CopyAllTo = filecount
    Resume exitFunctionCopyAllTo
  End Function

  Public Function MoveAllTo(ByVal newpath As String) As Integer
    Dim filename As String
    Dim filecount As Integer
    Dim deletelist List As String
    '*** Check if both arguments are blank, then exit
    If FullTrim(newpath) = "" Then
      If FullTrim(newpath) = "" Then
        MoveAllTo = 0
        Exit Function
      End If   
    End If
    If FullTrim(newpath) = "" Then
      newpath = file.Path
    End If  
    Call MakeDir(newpath)
    On Error GoTo errHandlerMoveAllTo
    filename = Dir$(file.Path,2)  ' Include hidden files
    Do Until filename=""
      FileCopy file.Path + filename, newpath + filename
      If silent = False Then
        Print "Moving " & filename & " from " & file.Path & " to " & newpath
      End If
      deletelist(filename) = file.Path + filename
      filecount = filecount + 1
      filename = Dir$()
    Loop
    Print "Cleaning up..."
    ForAll f In deletelist
      Kill f  
    End ForAll
    MoveAllTo = filecount
exitFunctionMoveAllTo:
    Print "Moved " & filecount & " files"
    Exit Function
errHandlerMoveAllTo:
    MoveAllTo = filecount
    Resume exitFunctionMoveAllTo
  End Function

  Public Function RemoveDir(ByVal dirpath As String) As Boolean
    '*** If blank, use the path in object
    If FullTrim(dirpath) = "" Then
      dirpath = file.path
    End If
    On Error GoTo errHandlerRemoveDir
    RmDir dirpath
    RemoveDir = True
exitRemoveDir:        
    Exit Function
errHandlerRemoveDir:
    RemoveDir = False
    Resume exitRemoveDir
  End Function
  

  ' ===== Private Supporting Functions =====  
  
  Private Sub MakeDir(Byval strWhere As String)
    ' *** This code by Andre Guirard @ IBM
    ' *** http://www-10.lotus.com/ldd/bpmpblog.nsf/dx/recursive-mkdir-vs.-iteration
    ' *** Using an iterative method instead of recursive due to stack issues (see link above)
    On Error 76 Goto parentDoesNotExist 
    Dim stack$ 
    Const NL = { 
} 
    Do 
      Mkdir strWhere 
      On Error Goto 0 ' first success, stop trapping errors; avoid infinite loop. 
      strWhere = Strleft(stack, NL) ' "pop" a path for next iteration 
      stack = Mid$(stack, Len(strWhere)+2) 
failed: 
    Loop Until strWhere = "" 
    Exit Sub 
parentDoesNotExist: 
       ' This error code can indicate other problems, but assume missing parent. 
       ' If not, we get a different error (75) later when trying to create the parent. 
    Dim fpath$, fname$ 
    SplitFilepath strWhere, fpath, fname 
    If fpath = "" Then Error 76, "Invalid path: '" & strWhere & "'" 
    stack = strWhere & NL & stack ' "push" onto stack to retry later. 
    strWhere = fpath ' try a path one step shorter. 
    Resume failed 
  End Sub 

  
  Private Sub SplitFilePath(Byval fullpath$, dirpath$, filename$) 
    ' *** This subroutine by Andre Guirard @ IBM
    ' *** http://www-10.lotus.com/ldd/bpmpblog.nsf/dx/recursive-mkdir-vs.-iteration
    ' *** Called from MakeDir()    
    Const DELIMS = {/\:} 
    While Instr(DELIMS, Right$(fullPath, 1)) ' discard final delimiter character... 
      fullpath = Left$(fullpath, Len(fullpath)-1) 
    Wend 
    Dim candidate$, i% 
    filename = Strtoken(fullpath, Left$(DELIMS, 1), -1) 
    For i = 2 To Len(DELIMS) 
      candidate = Strtoken(fullpath, Mid$(DELIMS, i, 1), -1) 
      If Len(candidate) < Len(filename) Then 
        filename = candidate 
      End If 
    Next 
    Dim fplen% 
    fplen = Len(fullpath)-Len(filename) 
    If fplen > 0 Then fplen = fplen - 1 
    dirpath = Left$(fullpath, fplen) 
  End Sub
  
End Class

 
Enjoy!
 

A question I have seen a few times in the developerWorks forums is how to detect what values (often names) have been added in a multi-value field.

This is not very difficult to do in Lotusscript, and there are a few different ways to do it. I prefer to use lists, but you can of course use arrays as well. The basic idea is to declare a global variable to hold the initial value of the field, populate it when the document is either opened or put into edit mode, and then checked when the document is saved.

Globals:
Dim oldValue List As String

PostModeChange:
Dim oldarray as Variant
'*** Create array, assume ; as item separator in field
oldarray = Split(uidoc.FieldGetText("myMultiValueField"),";")
'*** Build a list of values
ForAll o in oldarray 
    oldValue(o) = o 
End ForAll

QuerySave: 
Dim newarray as Variant
Dim newValue List As String
'*** Create array, assume ; as item separator in field
newarray = Split(uidoc.FieldGetText("myMultiValueField"),";")
'*** Compare with values in list
ForAll n in newarray
    '*** Check if value is not in global list, then it is new
    If IsElement(oldValue(n)) = False Then
        newValue(n) = n    ' Add new value to list
    End If
End ForAll
'*** Loop through all new values and print them
ForAll nv in newValue 
    Print nv + " is new." 
End Forall
 

The same technique can be used to detect what fields have changed since the document was opened. Just store the values of all fields (except any starting with $) in a list, then check the values in the fields against that list when saving the document.

 
Globals:
Dim oldValue List As String

QueryOpen:
'*** Build a list of values with field name as listtag
ForAll i in doc.Items 
    If Left$(i.Name,1)<>"$") Then
        oldValue(i.Name)=i.Text
    End If
End ForAll

QuerySave: 
Dim modified List As String
Dim tmpValue As String
'*** Compare current fields with values in list
ForAll o in oldValue 
    '*** Check if value is the same or not
    tmpValue = uidoc.FieldGetText(Listtag(o))   ' Get current field value
    If tmpValue <> o Then
        modified(ListTag(o))=tmpValue    ' Add new value to list of modified fields
    End If
End ForAll
'*** Loop through all modified fields and display new value
ForAll m in modified
    Print Listtag(m) + " was changed from " + oldValue(Listtag(m)) + " to " + m
End Forall
  

All very easy when you know how to do it. And again, it shows the power of lists.

While reading the developerWorks forums, I have noted that some tasks seem to be common, and users often have issues with it. One very common is to export data from Notes/Domino to Excel. My guess is that some manager/executive want to get the data to manipulate and analyze it in Excel, which they know better, and where reporting can be done easier.

First of all, for anyone that want to do real integration with Excel (or Word, or any other office program), I would suggest to look at the presentations given by John Head at Lotusphere and other conferences in the past:
Lotusphere 2011 – JMP208
IamLUG 2009 – Integration and Coexistance
Lotusphere 2006 – BP309
Lotusphere 2005 – JMP108

But if you just need to export raw data to Excel, there are a couple easy ways to do that. You don’t need to automate Excel, something the programmers posting in the forums seem to frequently do. That just makes things more complicated, and if you run the code in a server agent, Microsoft Office have to be installed on the server itself. Different versions of Excel also cause different issues.

The different methods I use to export Notes data to Excel are as follows:

• Create a CSV file, which can be opened in Excel
• Create a HTML table in a file with .xls extension, which can be opened in Excel
• Create a HTML table and return it through a browser, with a content type set to open in Excel.

Depending on what the requirement is, I usually choose one of those method.

Method 1 – CSV file (local)

The easiest way to get data from Notes to Excel (or any other spreadsheet program) is to simply save the data as  comma-separated values (CSV). Use regular Lotusscript file operations and write the values to the file, encased in double quotes and separated by a comma. You need to build a string containing a complete line, as the Print statement adds a line break to the end automatically.

A CSV file could look like this:

FirstName,LastName,Department,StartYear
"Karl-Henry","Martinsson","IT","2002"
"John","Smith","Accounting","2009"

The first row is the header, with the field names listed. This helps on the receiving side, but is optional. Dates and numbers don’t need quotes around them, as long as they don’t contain commas. So make a habit to format any numbers without commas.

Method 2 – HTML file (local)

This method is very similar to the CSV method. The difference is that you create a table in HTML, matching the cells in Excel you want to create/populate. But instead of creating a file with the extension .htm or .html, you give it the extension .xls. Excel is intelligent enough to identify it as HTML and map the content correctly.

The biggest advantages of using a HTML file instead of CSV is that you get more control over the formatting. By using colspan and rowspan, you can merge cells together, for example in a header. You can also use markup to make cells bold or italic, or even set the text and background colors.

Method 3 – HTML (through browser)

This method is a variant of method 2. But instead of calling the agent inside the Notes client and creating a file somewhere in the file system, the agent is called through a URL. This means the Domino HTTP task must be enabled on the server. The URL can be called from inside the Notes client using the @URLOpen function, or the OpenURL method of the NotesUIWorkspace class.

Instead of writing to a file, use the Print statement to print to the browser. The first line printed must be the content type, so the browser realize what application to open the file in. For Excel, it looks like this:

Print "content-type:application/vnd.ms-excel"

It also works with (among other) “application/msexcel” and “application/xls”, but the one above is the official one, so I suggest using that.

After you print the content type, simply print the HTML table code to the browser. This will open the HTML in Excel after the agent is done. It’s that easy.