Implemented #8197: Add generated files for OO API for C language to distribution

builds/install/arch-specific/linux/makeInstallImage.sh.in

@@ -248,9 +248,9 @@ copyFiles() {
 
 	#include (.h .pas files)
 	cp $BuiltFBDir/include/*.h ${TargetDir}@FB_INCDIR@
-	cp $BuiltFBDir/include/firebird/impl/iberror_c.h ${TargetDir}@FB_INCDIR@/firebird/impl
-	cp $BuildRootDir/src/include/firebird/*.h ${TargetDir}@FB_INCDIR@/firebird
-	tar -C $BuildRootDir/src/include/firebird -cf - impl | tar -C ${TargetDir}@FB_INCDIR@/firebird -x
+#	cp $BuiltFBDir/include/firebird/impl/iberror_c.h ${TargetDir}@FB_INCDIR@/firebird/impl
+	cp $BuiltFBDir/include/firebird/*.h ${TargetDir}@FB_INCDIR@/firebird
+	tar -C $BuiltFBDir/include/firebird -cf - impl | tar -C ${TargetDir}@FB_INCDIR@/firebird -x
 	if [ "$CLIENT_ONLY_FLG" = "N" ]; then
 		cp $BuildRootDir/src/include/gen/Firebird.pas ${TargetDir}@FB_INCDIR@/firebird
 	fi
@@ -262,6 +262,7 @@ copyFiles() {
 	if [ "$CLIENT_ONLY_FLG" = "N" ]; then
 		cp -f $BuiltFBDir/lib/libib_util.so ${TargetDir}@FB_LIBDIR@/libib_util.so
 	fi
+	copyIfExists $BuiltFBDir/lib/libfb_c_api.a ${TargetDir}@FB_LIBDIR@
 
 	if [ "$TomMathBuild" = "Y" ]; then
 		makeDirs @FB_LIBDIR@/.tm

builds/install/posix-common/posixLibrary.sh.in

@@ -596,7 +596,7 @@ createLinksInSystemLib() {
     origDirLinksInSystemLib=`pwd`
 
     cd @FB_LIBDIR@
-	Libraries=`echo libfbclient.@SHRLIB_EXT@* libib_util.@SHRLIB_EXT@`
+	Libraries=`echo libfbclient.@SHRLIB_EXT@* libib_util.@SHRLIB_EXT@ libfb_c_api.a`
 
 	cd /
 	for l in $Libraries

builds/posix/Makefile.in

@@ -112,17 +112,24 @@ Debug:
 #
 
 .PHONY: updateCloopInterfaces updateBuildNum
-
-IDL_ROOT=$(SRC_ROOT)/include/firebird
+INCLD_ROOT=$(SRC_ROOT)/include
+IDL_ROOT=$(INCLD_ROOT)/firebird
 IDL_FILE=$(IDL_ROOT)/FirebirdInterface.idl
 API_H_FILE=$(IDL_ROOT)/IdlFbInterfaces.h
-API_PAS_FILE=$(SRC_ROOT)/include/gen/Firebird.pas
+API_PAS_FILE=$(INCLD_ROOT)/gen/Firebird.pas
+API_C_HEADER=fb_c_api.h
+API_C_H_FILE=$(FIREBIRD)/include/firebird/$(API_C_HEADER)
+API_C_TMP_FILE=$(TMP_ROOT)/fb_c_api.tmp
+API_C_IMPL_FILE=$(INCLD_ROOT)/gen/fb_c_api.c
+API_C_TEMPLATE=$(IDL_ROOT)/fb_c_api.hdr
+API_C_LIBRARY=$(LIB)/libfb_c_api.a
+API_C_TMP_OBJ=$(TMP_ROOT)/fb_c_api.obj
 MISC=$(SRC_ROOT)/misc
 PAS_ROOT=$(MISC)/pascal
 PASCAL_SOURCES=$(wildcard $(PAS_ROOT)/*)
 TMP_FUNCS_PAS=$(TMP_ROOT)/func.pas
-XPB_CONSTS=$(SRC_ROOT)/include/firebird/impl/consts_pub.h
-INF_CONSTS=$(SRC_ROOT)/include/firebird/impl/inf_pub.h
+XPB_CONSTS=$(INCLD_ROOT)/firebird/impl/consts_pub.h
+INF_CONSTS=$(INCLD_ROOT)/firebird/impl/inf_pub.h
 ERR_CONSTS_PAS=$(SRC_ROOT)/misc/pascal/gds_codes.pas
 RPL_AWK=$(GEN_ROOT)/def_awk
 RPL_AWK_SRC=$(MISC)/def_awk.c
@@ -134,6 +141,15 @@ updateCloopInterfaces : $(API_H_FILE) $(API_PAS_FILE)
 $(API_H_FILE): $(IDL_FILE)
 	$(CLOOP) $< c++ $@ IDL_FB_INTERFACES_H Firebird I
 
+$(API_C_TMP_FILE): $(IDL_FILE)
+	$(CLOOP) $< c-header $@ FB_C_API_H I
+
+$(API_C_H_FILE): $(API_C_TEMPLATE) $(API_C_TMP_FILE)
+	cat $(API_C_TEMPLATE) $(API_C_TMP_FILE) >$(API_C_H_FILE)
+
+$(API_C_IMPL_FILE): $(IDL_FILE)
+	$(CLOOP) $< c-impl $@ $(API_C_HEADER) I
+
 #
 # This way firebird.pas can be created not using own mini-utilities.
 # They were added to be able to build on windows, this code is left for reference.
@@ -150,7 +166,7 @@ $(RPL_AWK):	$(RPL_AWK_SRC)
 $(RPL_GREP): $(RPL_GREP_SRC)
 	$(CC) -o $@ $^
 
-$(TMP_ROOT)/iberror.pas: $(BUILD_FILE) $(ERR_CONSTS_PAS) $(SRC_ROOT)/include/firebird/impl/msg/*.h
+$(TMP_ROOT)/iberror.pas: $(BUILD_FILE) $(ERR_CONSTS_PAS) $(INCLD_ROOT)/firebird/impl/msg/*.h
 	$(BUILD_FILE) -p $(TMP_ROOT)/iberror_codes.pas
 	cp $(ERR_CONSTS_PAS) $(TMP_ROOT)/iberror.pas
 	cat $(TMP_ROOT)/iberror_codes.pas >> $(TMP_ROOT)/iberror.pas
@@ -691,13 +707,13 @@ $(COMPAT_SQL):	$(SRC_COMPAT_SQL)
 # all the rest we need to build
 #
 
-.PHONY:	message_file tzdata gbak_files
+.PHONY:	message_file tzdata gbak_files api_c_library
 
 FDB_FILES := $(SECURITY_FDB) $(FIREBIRD)/examples/empbuild/employee.fdb
 GBAK_FILES := $(FDB_FILES:.fdb=.gbak)
 GBAK_FILES := $(subst Native,$(TARGET),$(GBAK_FILES))
 
-rest:	message_file tzdata
+rest:	tzdata api_c_library
 
 cross_rest: tzdata
 	$(MAKE) $(BUILD_FILE)
@@ -723,6 +739,14 @@ $(BUILD_FILE):	$(BUILD_Objects)
 
 gbak_files: $(GBAK_FILES)
 
+api_c_library: $(API_C_LIBRARY)
+
+$(API_C_LIBRARY): $(API_C_IMPL_FILE) $(API_C_H_FILE) $(FIREBIRD_MSG)	# use $(FIREBIRD_MSG) as timemark for iberror_c.h
+	$(CC) $(WCFLAGS) -I$(FIREBIRD)/include -c $(API_C_IMPL_FILE) -o $(API_C_TMP_OBJ)
+	-$(RM) $@
+	$(STATICLIB_LINK) $@ $(API_C_TMP_OBJ)
+
+
 #---------------------------------------------------------------------------
 
 # This target builds the include files for distribution with the release

examples/interfaces/01.create.c

@@ -0,0 +1,105 @@
+/*
+ *	PROGRAM:	Object oriented API samples.
+ *	MODULE:		01.create.c
+ *	DESCRIPTION:	Minimal sample of using interfaces from plain C.
+ *
+ *					Run something like this to build: cc 01.create.c -lfb_c_api -lfbclient
+ *
+ *  The contents of this file are subject to the Initial
+ *  Developer's Public License Version 1.0 (the "License");
+ *  you may not use this file except in compliance with the
+ *  License. You may obtain a copy of the License at
+ *  http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_idpl.
+ *
+ *  Software distributed under the License is distributed AS IS,
+ *  WITHOUT WARRANTY OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing rights
+ *  and limitations under the License.
+ *
+ *  The Original Code was created by Alexander Peshkoff
+ *  for the Firebird Open Source RDBMS project.
+ *
+ *  Copyright (c) 2024 Alexander Peshkoff <alexander.peshkoff@gmail.com>
+ *  and all contributors signed below.
+ *
+ *  All Rights Reserved.
+ *  Contributor(s): ______________________________________.
+ */
+
+#include "firebird/fb_c_api.h"
+#include <stdio.h>
+
+#define CHECK_STATUS(st) if (IStatus_getState(st) & IStatus_STATE_ERRORS) {char buf[256]; IUtil_formatStatus(utl, buf, sizeof buf, st); puts(buf); return 1;}
+
+int main()
+{
+	// Here we get access to master interface. This is main interface of firebird,
+	// and the only one for getting which there is special function in our API.
+	struct IMaster* master = fb_get_master_interface();
+
+	// Declare pointers to required interfaces
+	// IStatus is used to return wide error description to user
+	// IProvider is needed to start to work with database (or service)
+	// Status vector, main dispatcher and utility interfaces are returned by IMaster functions
+	// No error return may happen - these functions always succeed
+	struct IStatus* st = IMaster_getStatus(master);
+	struct IProvider* prov = IMaster_getDispatcher(master);
+	struct IUtil* utl = IMaster_getUtilInterface(master);
+
+	// IAttachment and ITransaction contain methods to work with database attachment
+	// and transactions
+	struct IAttachment* att = NULL;
+	struct ITransaction* tra = NULL;
+
+	// IXpbBuilder is used to access various parameters blocks used in API
+	struct IXpbBuilder* dpb = NULL;
+
+	// create DPB - use non-default page size 4Kb
+	dpb = IUtil_getXpbBuilder(utl, st, IXpbBuilder_DPB, NULL, 0);
+	CHECK_STATUS(st);
+	IXpbBuilder_insertInt(dpb, st, isc_dpb_page_size, 4 * 1024);
+	CHECK_STATUS(st);
+	IXpbBuilder_insertString(dpb, st, isc_dpb_user_name, "sysdba");
+	CHECK_STATUS(st);
+	IXpbBuilder_insertString(dpb, st, isc_dpb_password, "masterkey");
+	CHECK_STATUS(st);
+
+	// create empty database
+	att = IProvider_createDatabase(prov, st, "fbtests.fdb",
+		IXpbBuilder_getBufferLength(dpb, st), IXpbBuilder_getBuffer(dpb, st));
+	CHECK_STATUS(st);
+	printf("Database fbtests.fdb created\n");
+
+	// start transaction
+	tra = IAttachment_startTransaction(att, st, 0, NULL);
+	CHECK_STATUS(st);
+
+	// create table
+	IAttachment_execute(att, st, tra, 0, "create table dates_table (d1 date)", 3,
+		NULL, NULL, NULL, NULL);	// Input parameters and output data not used
+	CHECK_STATUS(st);
+
+	// commit transaction retaining
+	ITransaction_commitRetaining(tra, st);
+	CHECK_STATUS(st);
+	printf("Table dates_table created\n");
+
+	// insert a record into dates_table
+	IAttachment_execute(att, st, tra, 0, "insert into dates_table values (CURRENT_DATE)", 3,
+		NULL, NULL, NULL, NULL);	// Input parameters and output data not used
+	CHECK_STATUS(st);
+
+	// commit transaction (will close interface)
+	ITransaction_commit(tra, st);
+	CHECK_STATUS(st);
+	printf("Record inserted into dates_table\n");
+
+	// detach from database (will close interface)
+	IAttachment_detach(att, st);
+	CHECK_STATUS(st);
+
+	IStatus_dispose(st);
+	IProvider_release(prov);
+
+	return 0;
+}

extern/cloop/src/cloop/Main.cpp

@@ -35,6 +35,19 @@ using std::exception;
 using std::string;
 using std::runtime_error;
 
+static string paramError(const char* generator = nullptr, const char* perGenerator = nullptr)
+{
+	string text = "Invalid command line parameters. Required format: inputFile ";
+	text += generator ? generator : "outFormat (one of c-header, c-impl, c++, pascal)";
+	text += " outputFile";
+	if (perGenerator)
+	{
+		text += " ";
+		text += perGenerator;
+	}
+
+	return text;
+}
 
 //--------------------------------------
 
@@ -42,7 +55,7 @@ using std::runtime_error;
 static void run(int argc, const char* argv[])
 {
 	if (argc < 4)
-		throw runtime_error("Invalid command line parameters.");
+		throw runtime_error(paramError());
 
 	string inFilename(argv[1]);
 	string outFormat(argv[2]);
@@ -58,7 +71,7 @@ static void run(int argc, const char* argv[])
 	if (outFormat == "c++")
 	{
 		if (argc < 7)
-			throw runtime_error("Invalid command line parameters for C++ output.");
+			throw runtime_error(paramError("c++", "headerGuard className prefix"));
 
 		string headerGuard(argv[4]);
 		string className(argv[5]);
@@ -69,7 +82,7 @@ static void run(int argc, const char* argv[])
 	else if (outFormat == "c-header")
 	{
 		if (argc < 6)
-			throw runtime_error("Invalid command line parameters for C header output.");
+			throw runtime_error(paramError("c-header", "headerGuard prefix"));
 
 		string headerGuard(argv[4]);
 		string prefix(argv[5]);
@@ -79,7 +92,7 @@ static void run(int argc, const char* argv[])
 	else if (outFormat == "c-impl")
 	{
 		if (argc < 6)
-			throw runtime_error("Invalid command line parameters for C implementation output.");
+			throw runtime_error(paramError("c-impl", "includeFilename prefix"));
 
 		string includeFilename(argv[4]);
 		string prefix(argv[5]);
@@ -89,7 +102,8 @@ static void run(int argc, const char* argv[])
 	else if (outFormat == "pascal")
 	{
 		if (argc < 5)
-			throw runtime_error("Invalid command line parameters for Pascal output.");
+			throw runtime_error(paramError("pascal", "--uses uses --interfaceFile interfaces-file "
+				"--implementationFile implementation-file --exceptionClass class-name --prefix prefix --functionsFile functions-file"));
 
 		string unitName(argv[4]);
 

src/include/firebird/fb_c_api.hdr

@@ -0,0 +1,32 @@
+/*
+ *	PROGRAM:		Firebird interface.
+ *	MODULE:			fb_c_api.h
+ *	DESCRIPTION:	C API file.
+ *
+ *  The contents of this file are subject to the Initial
+ *  Developer's Public License Version 1.0 (the "License");
+ *  you may not use this file except in compliance with the
+ *  License. You may obtain a copy of the License at
+ *  http://www.ibphoenix.com/main.nfs?a=ibphoenix&page=ibp_idpl.
+ *
+ *  Software distributed under the License is distributed AS IS,
+ *  WITHOUT WARRANTY OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing rights
+ *  and limitations under the License.
+ *
+ *  The Original Code was created by Alex Peshkov
+ *  for the Firebird Open Source RDBMS project.
+ *
+ *  Copyright (c) 2024 Alex Peshkov <alexander.peshkoff@gmail.com>
+ *  and all contributors signed below.
+ *
+ *  All Rights Reserved.
+ *  Contributor(s): ______________________________________.
+ *
+ *
+ */
+
+#include <ibase.h>
+
+struct IMaster* ISC_EXPORT fb_get_master_interface();
+