Refresh Design In LotusScriptStarting 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:
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
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
destPath = sourceDb.server & "!!" & sourceDb.filePath
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"
rc = W32_DesignRefresh(refreshServer, hDb, 0, 0, 0)
If rc <> 0 Then
Msgbox "Database Could Not Be Refreshed - Error Code " & Cstr(rc), 16, "Error"
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.