Starting with version 5.03 of the Notes API, the ability to refresh the design of a database through the API has been exposed. The API call, in its most basic form, is surprisingly easy to use in LotusScript. This tip shows you how to do it.

First, create an agent somewhere (it can be in a temporary local database, independent of the NSF/NTF combination to be refreshed). Put the following code into the (Declarations) section and the Initialize subroutine:

(Declarations)
Declare Private Function W32_NSFDbOpen Lib "nnotes" Alias "NSFDbOpen" (Byval PathName As Lmbcs String, _
hDB As Integer) As Integer
Declare Private Function W32_DesignRefresh Lib "nnotes" Alias "DesignRefresh" _
(Byval ServerName As Lmbcs String, Byval hDB As Integer, Byval dwFlags As Long, _
Byval abortCheck As Integer, Byval messageProc As Integer) As Integer
Declare Private Function W32_NSFDbClose Lib "nnotes" Alias "NSFDbClose" (Byval hDB As Integer) As Integer

Sub Initialize
   Dim s As New notesSession
   Dim sourceDb As notesDatabase
   Dim refreshServer As String
   Dim destPath As String
   Dim rc As Integer
   Dim hDb As Integer
   
   Set sourceDb = s.getDatabase("<Server>", "<File Name>")
   refreshServer = "<Server where NTF is stored>" ' Note: use an empty string to signify "Local"
   On Error Resume Next
   If Not sourceDb.isOpen Then Call sourceDb.open("", "") ' Make sure the source database exists
   If Not sourceDb.isOpen Then Set sourceDb = Nothing
   On Error Goto 0
   If Err <> 0 Then Set sourceDb = Nothing
   If sourceDb Is Nothing Then Exit Sub ' ==== Exit if source db doesn't exist or couldn't be opened ====
   ' Build the API path to the file
   If sourceDb.server = "" Then
      destPath = sourceDb.filePath
   Else
      destPath = sourceDb.server & "!!" & sourceDb.filePath
   End If
   rc = W32_NSFDbOpen(destPath, hDb) ' Open the db in the API and get a handle to the open db
   If rc <> 0 Then ' Return Code zero on success, non-zero on failure
      Msgbox "Database Could Not Be Opened - Error Code " & Cstr(rc), 16, "Error"
   Else
      rc = W32_DesignRefresh(refreshServer, hDb, 0, 0, 0)
      If rc <> 0 Then
         Msgbox "Database Could Not Be Refreshed - Error Code " & Cstr(rc), 16, "Error"
      End If
      Call W32_NSFDbClose(hDb)
   End If
End Sub

Run this agent from your client and the database will be refreshed just like you opened the source database, went to File | Database | Refresh Design and chose that refresh server. The messages will be printed to your status bar.

Now, you may be wondering why this would be useful instead of going through the user interface. Well, two cases come to mind. First would involve an upgrade of a design. Let's say that you will need to migrate some data after moving to the next release of an application. You could write your migration agent to automatically refresh the design of the database either at the start or the end of the agent. Then, you could start the agent and let it run (overnight or whatever).

The second instance would involve a series of databases that all inherit from the same template. You could write an agent that goes through the source databases (which could be on many different servers) and, one by one, refresh the design from the source template. The template doesn't have to be replicated to all the different source servers if this method was used.