ScriptForge (UI) extend scope of CreateBaseDocument

The
ui.CreateBaseDocument()
method accepted so far to create Base documents
either embedding HSQLDB or FIREBIRD databases
or linked to a Cals spreadsheet.

It is now extended to make the new Base document
finding its datasource in an external Firebird
database file.

The previous signature
ui.CreateBaseDocument(FileName, EmbeddedDatabase,
CalcFileName)
is replaced by
ui.CreateBaseDocument(FileName, EmbeddedDatabase,
DataFileName, CalcFileName)
=> The CalcFileName argument is deprecated. When present,
it is copied to DataFileName.
The EmbeddedDatabase argument may take next values:
HSQLDB (default), FIREBIRD, FIREBIRD_EXTERNAL or CALC.

The change is valid for both Basic and Python scripts.
The documentation should be upgraded.

Change-Id: I5daf418f50739baca6be899eb1444d1b99cf89aa
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/184935
Reviewed-by: Jean-Pierre Ledure <jp@ledure.be>
Tested-by: Jenkins

4 files changed, 57 insertions, 36 deletions

diff --git a/wizards/source/scriptforge/SF_UI.xba b/wizards/source/scriptforge/SF_UI.xba
index b560c26b9067..656cc9553551 100644
--- a/wizards/source/scriptforge/SF_UI.xba
+++ b/wizards/source/scriptforge/SF_UI.xba
@@ -263,9 +263,11 @@ REM ----------------------------------------------------------------------------
 Public Function CreateBaseDocument(Optional ByVal FileName As Variant _
 							, Optional ByVal EmbeddedDatabase As Variant _
 							, Optional ByVal RegistrationName As Variant _
+							, Optional ByVal DataFileName As Variant _
 							, Optional ByVal CalcFileName As Variant _
 							) As Object
 ''' Create a new LibreOffice Base document embedding an empty database of the given type
+'''	or finding its datasource in an external database file (Calc or Firebird).
 '''	Args:
 '''		FileName: Identifies the file to create. It must follow the SF_FileSystem.FileNaming notation
 '''			If the file already exists, it is overwritten without warning
@@ -273,11 +275,14 @@ Public Function CreateBaseDocument(Optional ByVal FileName As Variant _
 '''		RegistrationName: the name used to store the new database in the databases register
 '''			If "" (default), no registration takes place
 '''			If the name already exists it is overwritten without warning
-'''		CalcFileName: only when EmbedddedDatabase = "CALC", the name of the file containing the tables as Calc sheets
+'''		DataFileName: when EmbedddedDatabase = "CALC", the name of the file containing the tables as Calc sheets,
+'''			when EmbeddedDatabase = "FIREBIRD_EXTERNAL", the Firebird external database file.
 '''			The name of the file must be given in SF_FileSystem.FileNaming notation
 '''			The file must exist
+'''		CalcFileName: only when EmbedddedDatabase = "CALC", the name of the file containing the tables as Calc sheets
+'''			The argument is obsolete as from SF 25.8.
 '''	Returns:
-'''		 A SFDocuments.SF_Document object or one of its subclasses
+'''		 A SFDocuments.SF_Base object or Nothing
 '''	Exceptions
 '''		UNKNOWNFILEERROR				Calc datasource does not exist
 '''	Examples:
@@ -288,12 +293,13 @@ Public Function CreateBaseDocument(Optional ByVal FileName As Variant _
 Dim oCreate As Variant				'	Return value
 Dim oDBContext As Object			'	com.sun.star.sdb.DatabaseContext
 Dim oDatabase As Object				'	com.sun.star.comp.dba.ODatabaseSource
-Dim oComp As Object					'	Loaded component com.sun.star.lang.XComponent
+Dim sTarget As String				'	sdbc abbreviation
 Dim sFileName As String				'	Alias of FileName
 Dim FSO As Object					'	Alias for FileSystem service
 Const cstDocType = "private:factory/s"
 Const cstThisSub = "UI.CreateBaseDocument"
-Const cstSubArgs = "FileName, [EmbeddedDatabase=""HSQLDB""|""FIREBIRD""|""CALC""], [RegistrationName=""""], [CalcFileName]"
+Const cstSubArgs = "FileName, [EmbeddedDatabase=""HSQLDB""|""FIREBIRD""|""FIREBIRD_EXTERNAL""|""CALC""], " _
+					& "[RegistrationName=""""], [DataFileName]"
 
 	If SF_Utils._ErrorHandling() Then On Local Error GoTo Catch
 	Set oCreate = Nothing
@@ -302,34 +308,43 @@ Const cstSubArgs = "FileName, [EmbeddedDatabase=""HSQLDB"&qu
 Check:
 	If IsMissing(EmbeddedDatabase) Or IsEmpty(EmbeddedDatabase) Then EmbeddedDatabase = "HSQLDB"
 	If IsMissing(RegistrationName) Or IsEmpty(RegistrationName) Then RegistrationName = ""
+	If IsMissing(DataFileName) Or IsEmpty(DataFileName) Then DataFileName = ""
 	If IsMissing(CalcFileName) Or IsEmpty(CalcFileName) Then CalcFileName = ""
 	If SF_Utils._EnterFunction(cstThisSub, cstSubArgs) Then
 		If Not SF_Utils._ValidateFile(FileName, "FileName") Then GoTo Finally
-		If Not SF_Utils._Validate(EmbeddedDatabase, "EmbeddedDatabase", V_STRING, Array("CALC", "HSQLDB", "FIREBIRD")) Then GoTo Finally
+		If Not SF_Utils._Validate(EmbeddedDatabase, "EmbeddedDatabase", V_STRING, _
+									Array("CALC", "HSQLDB", "FIREBIRD", "FIREBIRD_EXTERNAL")) Then GoTo Finally
 		If Not SF_Utils._Validate(RegistrationName, "RegistrationName", V_STRING) Then GoTo Finally
-		If UCase(EmbeddedDatabase) = "CALC" Then
-			If Not SF_Utils._ValidateFile(CalcFileName, "CalcFileName") Then GoTo Finally
-			If Not FSO.FileExists(CalcFileName) Then GoTo CatchNotExists
+		If InStr(UCase(EmbeddedDatabase), "CALC,FIREBIRD_EXTERNAL") > 0 Then
+			If Len(CalcFileName) > 0 And Len(DataFileName) = 0 Then DataFileName = CalcFileName
+			If Not SF_Utils._ValidateFile(DataFileName, "DataFileName") Then GoTo Finally
+			If Not FSO.FileExists(DataFileName) Then GoTo CatchNotExists
 		End If
 	End If
 
 Try:
+	sFileName = FSO._ConvertToUrl(FileName)
+
 	Set oDBContext = SF_Utils._GetUNOService("DatabaseContext")
 	With oDBContext
 		Set oDatabase = .createInstance()
-		'	Build the url link to the database
+
+		'	Build the url links in the database descriptors
+		oDatabase.URL = sFileName
 		Select Case UCase(EmbeddedDatabase)
 			Case "HSQLDB", "FIREBIRD"
-				oDatabase.URL = "sdbc:embedded:" & LCase(EmbeddedDatabase)
-			Case "CALC"
-				oDatabase.URL = "sdbc:calc:" & FSO._ConvertToUrl(CalcFileName)
+				oDatabase.DatabaseDocument.DataSource.URL = "sdbc:embedded:" & LCase(EmbeddedDatabase)
+			Case "CALC", "FIREBIRD_EXTERNAL"
+				If UCase(EmbeddedDatabase) = "CALC" Then sTarget = "calc" Else sTarget = "firebird"
+				oDatabase.DatabaseDocument.DataSource.URL = "sdbc:" & sTarget & ":" & FSO._ConvertToUrl(DataFileName)
 		End Select
+
 		'	Create empty Base document
-		sFileName = FSO._ConvertToUrl(FileName)
 		'	An existing file is overwritten without warning
 		If FSO.FileExists(FileName) Then FSO.DeleteFile(FileName)
 		If FSO.FileExists(FileName & ".lck") Then FSO.DeleteFile(FileName & ".lck")
 		oDatabase.DatabaseDocument.storeAsURL(sFileName, Array(SF_Utils._MakePropertyValue("Overwrite", True)))
+
 		'	Register database if requested
 		If Len(RegistrationName) > 0 Then
 			If .hasRegisteredDatabase(RegistrationName) Then
@@ -349,7 +364,7 @@ Finally:
 Catch:
 	GoTo Finally
 CatchNotExists:
-	SF_Exception.RaiseFatal(UNKNOWNFILEERROR, "CalcFileName", CalcFileName)
+	SF_Exception.RaiseFatal(UNKNOWNFILEERROR, "DataFileName", DataFileName)
 	GoTo Finally
 End Function    '   ScriptForge.SF_UI.CreateBaseDocument
 
diff --git a/wizards/source/scriptforge/python/scriptforge.py b/wizards/source/scriptforge/python/scriptforge.py
index 0f4b2a8bf4c2..807d8462b5fb 100644
--- a/wizards/source/scriptforge/python/scriptforge.py
+++ b/wizards/source/scriptforge/python/scriptforge.py
@@ -1752,9 +1752,12 @@ class SFScriptForge:
         def Activate(self, windowname = ''):
             return self.ExecMethod(self.vbMethod, 'Activate', windowname)
 
-        def CreateBaseDocument(self, filename, embeddeddatabase = 'HSQLDB', registrationname = '', calcfilename = ''):
+        def CreateBaseDocument(self, filename, embeddeddatabase = 'HSQLDB', registrationname = '', datafilename = '',
+                               calcfilename = ''):
+            if len(calcfilename) > 0 and len(datafilename) == 0:
+                datafilename = calcfilename
             return self.ExecMethod(self.vbMethod, 'CreateBaseDocument', filename, embeddeddatabase, registrationname,
-                                   calcfilename)
+                                   datafilename)
 
         def CreateDocument(self, documenttype = '', templatefile = '', hidden = False):
             return self.ExecMethod(self.vbMethod, 'CreateDocument', documenttype, templatefile, hidden)
diff --git a/wizards/source/scriptforge/python/scriptforge.pyi b/wizards/source/scriptforge/python/scriptforge.pyi
index f37bd5ee343d..fc30510a0f51 100644
--- a/wizards/source/scriptforge/python/scriptforge.pyi
+++ b/wizards/source/scriptforge/python/scriptforge.pyi
@@ -2392,24 +2392,27 @@ class SFScriptForge:
 
         def CreateBaseDocument(self,
                                filename: str,
-                               embeddeddatabase: Literal['HSQLDB', 'FIREBIRD', 'CALC'] = ...,
+                               embeddeddatabase: Literal['HSQLDB', 'FIREBIRD', 'FIREBIRD_EXTERNAL', 'CALC'] = ...,
                                registrationname: str = ...,
-                               calcfilename: str = ...,
+                               datafilename: str = ...,
                                ) -> BASE:
             """
-                Create a new LibreOffice Base document embedding an empty database of the given type.
+                Create a new LibreOffice Base document embedding an empty database of the given type
+                or finding its datasource in an external database file (Calc or Firebird).
                     Args
                         ``filename``: identifies the file to create. It must follow the ``FileSystem.FileNaming``
                         notation. If the file already exists, it is overwritten without warning.
 
-                        ``embeddeddatabase``: either ``HSQLDB`` or ``FIREBIRD`` or ``CALC``. Defaults to ``HSQLDB``.
+                        ``embeddeddatabase``: either ``HSQLDB``, ``FIREBIRD``, ``FIREBIRD_EXTERNAL`` or ``CALC``.
+                        Defaults to ``HSQLDB``.
 
                         ``registrationname``: the name used to store the new database in the databases register.
                         If "" (default), no registration takes place. If the name already exists it is overwritten
                         without warning.
 
-                        ``calcfilename``: only when ``embeddeddatabase`` = ``CALC``, the name of the file containing
-                        the tables as Calc sheets. The name of the file must be given in ``FileSystem.FileNaming``
+                        ``datafilename``: when ``embeddeddatabase`` = ``CALC``, the name of the file containing
+                        the tables as Calc sheets. When ``embeddeddatabase`` = ``FIREBIRD_EXTERNAL``, the name of the
+                        Firebird external database file. The name of the file must be given in ``FileSystem.FileNaming``
                         notation. The file must exist.
                     Returns
                         A ``Base`` service instance.
diff --git a/wizards/source/scriptforge/script.xlb b/wizards/source/scriptforge/script.xlb
index 54e48f703054..3318b6c54a1c 100644
--- a/wizards/source/scriptforge/script.xlb
+++ b/wizards/source/scriptforge/script.xlb
@@ -1,23 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE library:library PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "library.dtd">
 <library:library xmlns:library="http://openoffice.org/2000/library" library:name="ScriptForge" library:readonly="false" library:passwordprotected="false">
- <library:element library:name="SF_TextStream"/>
- <library:element library:name="SF_Array"/>
- <library:element library:name="SF_Region"/>
- <library:element library:name="SF_L10N"/>
- <library:element library:name="SF_PythonHelper"/>
- <library:element library:name="SF_Platform"/>
  <library:element library:name="SF_Utils"/>
- <library:element library:name="SF_Root"/>
- <library:element library:name="__License"/>
- <library:element library:name="SF_Timer"/>
- <library:element library:name="SF_FileSystem"/>
- <library:element library:name="SF_Session"/>
+ <library:element library:name="SF_Platform"/>
+ <library:element library:name="SF_PythonHelper"/>
+ <library:element library:name="SF_L10N"/>
+ <library:element library:name="SF_Region"/>
+ <library:element library:name="SF_Array"/>
  <library:element library:name="SF_UI"/>
  <library:element library:name="SF_Services"/>
- <library:element library:name="SF_Dictionary"/>
+ <library:element library:name="SF_Session"/>
  <library:element library:name="SF_Exception"/>
- <library:element library:name="_CodingConventions"/>
- <library:element library:name="_ModuleModel"/>
+ <library:element library:name="SF_Dictionary"/>
+ <library:element library:name="SF_Timer"/>
+ <library:element library:name="SF_FileSystem"/>
+ <library:element library:name="SF_TextStream"/>
+ <library:element library:name="SF_Root"/>
+ <library:element library:name="__License"/>
  <library:element library:name="SF_String"/>
+ <library:element library:name="_ModuleModel"/>
+ <library:element library:name="_CodingConventions"/>
 </library:library>
\ No newline at end of file