Rename a local or server database file with API function

Renames a local server or database file using an API function.

What do you do when you want to rename a notes database filename or move it to a different folder?

No doubt that you create a new replica then delete the old database, or access the server and then rename or move the database to the new location.

Well, here is an undocumented API function that is available in R4 & R5, that will rename or move a notes database, either locally or on a server.

Function Name: NSFDbRename Library: nnotes.dll Parameters: 1. Current database filename 2. New database filename

If you are renaming a database on the local machine, only specify the database folder and filename for both parameters, relative to the Notes data folder.

If you are renaming a database on a server, for both parameters, specify the abbreviated or canonical server name, followed by the string "!!", followed by the database filename as above.

The example below in the script code will rename a database filename from "mailoldmailfile.nsf" to "mailnewmailfile.nsf" on the server "My Server/My Org".

The OSLoadString API function, uses the string resource compiled in Lotus Notes to convert an error number into a text string, so if an error occurs you can see the text string with the error number.


Declare Function W32_NSFDbRename Lib "nnotes.dll" Alias "NSFDbRename" (Byval OldDatabase As String, Byval NewDatabase As String) As Integer
Declare Function W32_OSLoadString Lib "nnotes.dll" Alias "OSLoadString" (Byval hModule As Long, Byval StringCode As Integer, Byval retBuffer As String, Byval BufferLength As Integer) As Integer

#### SCRIPT CODE ####

Sub Initialize
 Dim iret As Integer
 Dim szError As String * 256
 Dim ErrorString As String
 Dim StrLen As Integer
 Dim nnServer As NotesName
 Dim oldDatabase As String
 Dim newDatabase As String
 Set nnServer = New NotesName("My Server/My Org")
 oldDatabase = "mailoldmailfile.nsf"
 newDatabase = "mailnewmailfile.nsf"
'if a server is not specified, then only parse the database information to the API function, not the server
'if a server is specified, then parse both the server and database to the API function
 If nnServer.Canonical = "" Then
  iret = W32_NSFDbRename(oldDatabase, newDatabase)
  iret = W32_NSFDbRename(nnServer.Canonical & "!!" & oldDatabase, nnServer.Canonical & "!!" & newDatabase)
 End If
'If an error occurs, then convert and display the error number and error message
 If iret <> 0 Then
  ErrorString = ""
  szError = String$(256, 0)
  StrLen = W32_OSLoadString(0, iret, szError, 255)
  If Strlen <> 0 Then ErrorString = Left$(szError, StrLen)
  Msgbox "Error " & iret & " (" & ErrorString & ")",,"Lotus Notes Error"
 End If

End Sub
This was first published in July 2002

Dig deeper on Lotus Notes Domino Administration Tools



Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:



  • iSeries tutorials's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...