Package constants

builds/win32/msvc15/engine_static.vcxproj

@@ -41,6 +41,7 @@
     <ClCompile Include="..\..\..\gen\jrd\scl.cpp" />
     <ClCompile Include="..\..\..\gen\jrd\SystemTriggers.cpp" />
     <ClCompile Include="..\..\..\gen\utilities\gstat\dba.cpp" />
+    <ClCompile Include="..\..\..\gen\jrd\Package.cpp" />
     <ClCompile Include="..\..\..\src\dsql\AggNodes.cpp" />
     <ClCompile Include="..\..\..\src\dsql\BlrDebugWriter.cpp" />
     <ClCompile Include="..\..\..\src\dsql\BoolNodes.cpp" />
@@ -417,6 +418,7 @@
     <None Include="..\..\..\src\jrd\met.epp" />
     <None Include="..\..\..\src\jrd\scl.epp" />
     <None Include="..\..\..\src\jrd\SystemTriggers.epp" />
+    <None Include="..\..\..\src\jrd\Package.epp" />
     <None Include="..\..\..\src\utilities\gstat\dba.epp" />
   </ItemGroup>
   <PropertyGroup Label="Globals">

builds/win32/msvc15/engine_static.vcxproj.filters

@@ -1199,11 +1199,14 @@
     <None Include="..\..\..\src\jrd\SystemTriggers.epp">
       <Filter>JRD files\GPRE files</Filter>
     </None>
+    <None Include="..\..\..\src\jrd\Package.epp">
+      <Filter>JRD files\GPRE files</Filter>
+    </None>
     <None Include="..\..\..\src\utilities\gstat\dba.epp">
       <Filter>Services</Filter>
     </None>
     <None Include="..\..\..\src\dsql\parse.y">
       <Filter>DSQL</Filter>
     </None>
   </ItemGroup>
-</Project>
+</Project>

builds/win32/preprocess.bat

@@ -65,7 +65,7 @@ goto :EOF
 @for %%i in (alice_meta) do @call :PREPROCESS alice %%i
 @for %%i in (metd, DdlNodes, PackageNodes) do @call :PREPROCESS dsql %%i -gds_cxx
 @for %%i in (gpre_meta) do @call :PREPROCESS gpre/std %%i
-@for %%i in (dfw, dpm, dyn_util, fun, grant, ini, met, scl, Function, SystemTriggers) do @call :PREPROCESS jrd %%i -gds_cxx
+@for %%i in (dfw, dpm, dyn_util, fun, grant, ini, met, scl, Function, SystemTriggers, Package) do @call :PREPROCESS jrd %%i -gds_cxx
 @for %%i in (stats) do @call :PREPROCESS utilities %%i
 @goto :EOF
 
@@ -78,7 +78,7 @@ goto :EOF
 @for %%i in (metd) do @call :PREPROCESS dsql %%i -gds_cxx
 @for %%i in (DdlNodes, PackageNodes) do @call :PREPROCESS dsql %%i -gds_cxx
 @for %%i in (gpre_meta) do @call :PREPROCESS gpre/std %%i
-@for %%i in (dfw, dpm, dyn_util, fun, grant, ini, met, scl, Function, SystemTriggers) do @call :PREPROCESS jrd %%i -gds_cxx
+@for %%i in (dfw, dpm, dyn_util, fun, grant, ini, met, scl, Function, SystemTriggers, Package) do @call :PREPROCESS jrd %%i -gds_cxx
 @for %%i in (extract, isql, show) do @call :PREPROCESS isql %%i -ocxx
 @for %%i in (dba) do @call :PREPROCESS utilities/gstat %%i
 @for %%i in (stats) do @call :PREPROCESS utilities %%i

doc/sql.extensions/README.blob_util.md

@@ -56,7 +56,8 @@ Return type: `VARBINARY(32767)`.
 
 `RDB$BLOB_UTIL.SEEK` is used to set the position for the next `READ_DATA`. It returns the new position.
 
-`MODE` may be 0 (from the start), 1 (from current position) or 2 (from end).
+`MODE` may be 0 (from the start), 1 (from current position) or 2 (from end). The corresponding constants
+are available in the package: `FROM_BEGIN`, `FROM_CURRENT`, `FROM_END`.
 
 When `MODE` is 2, `OFFSET` should be zero or negative.
 

doc/sql.extensions/README.ddl.txt

@@ -138,6 +138,7 @@ COMMENT ON <basic_type> name IS {'txt'|NULL};
 COMMENT ON COLUMN table_or_view_name.field_name IS {'txt'|NULL};
 COMMENT ON {PROCEDURE | [EXTERNAL] FUNCTION} [<package_name> .] name.param_name IS {'txt'|NULL};
 COMMENT ON [PROCEDURE | FUNCTION] PARAMETER [<package_name> .] name.param_name IS {'txt'|NULL};
+COMMENT ON CONSTANT [<schema_name> .] <package_name> . name IS {'txt'|NULL};
 
 An empty literal string '' will act as NULL since the internal code (DYN in this case)
 works this way with blobs.

doc/sql.extensions/README.packages.txt

@@ -19,14 +19,18 @@ Syntax:
 
     <package_item> ::=
         <function_decl> ; |
-        <procedure_decl> ;
+        <procedure_decl> ; |
+        <constant_decl> ;
 
     <function_decl> ::=
         FUNCTION <name> [( <parameters> )] RETURNS <type>
 
     <procedure_decl> ::=
         PROCEDURE <name> [( <parameters> ) [RETURNS ( <parameters> )]]
 
+    <constant_decl> ::=
+        CONSTANT <name> <type> = <constant expression>
+
     <package_body> ::=
         { CREATE [OR ALTER] | ALTER | RECREATE } PACKAGE BODY <name>
         AS
@@ -37,7 +41,8 @@ Syntax:
 
     <package_body_item> ::=
         <function_impl> |
-        <procedure_impl>
+        <procedure_impl> |
+        <constant_decl>
 
     <function_impl> ::=
         FUNCTION <name> [( <parameters> )] RETURNS <type>
@@ -75,7 +80,7 @@ Objectives:
       1) The grouping is not represented in the database metadata.
       2) They all participate in a flat namespace and all routines are callable by everyone (not
          talking about security permissions here).
-    
+
     - Facilitate dependency tracking between its internal routines and between other packaged and
       unpackaged routines.
 
@@ -90,9 +95,17 @@ Objectives:
       tables that the package body depends on that object. If you want to, for example, drop that
       object, you first need to remove who depends on it. As who depends on it is a package body,
       you can just drop it even if some other database object depends on this package. When the body
-      is dropped, the header remains, allowing you to create its body again after changing it based 
+      is dropped, the header remains, allowing you to create its body again after changing it based
       on the object removal.
 
+      A package constant is a value initialized by a constant expression.
+      A constant expression is defined by a simple rule: its value does not change after recompilation.
+      Constants declared in the package specification are publicly visible and can be referenced using
+      the [<schema>.]<package>.<constant_name> notation.
+      Constants declared in the package body are private and cannot be accessed from outside the package.
+      However, they can be referenced directly by <constant_name> within <procedure_impl> and <function_impl>.
+      Header constants can also be referenced directly by their name inside package body elements.
+
     - Facilitate permission management.
 
       It's generally a good practice to create routines with a privileged database user and grant
@@ -106,6 +119,10 @@ Objectives:
         GRANT SELECT ON TABLE secret TO PACKAGE pk_secret;
         GRANT EXECUTE ON PACKAGE pk_secret TO ROLE role_secret;
 
+      To use package constants in a select expression, a USAGE permission is required:
+        GRANT USAGE ON PACKAGE [<schema>.]<package_name> to [<user|role>] <name> [<grant_option>] [<granted_by>];
+        REVOKE USAGE ON PACKAGE [<schema>.]<package_name> FROM <user|role> <name> [<granted_by>];
+
     - Introduce private scope to routines making them available only for internal usage in the
       defining package.
 

src/burp/backup.epp

@@ -156,6 +156,7 @@ void write_triggers();
 void write_trigger_messages();
 void write_types();
 void write_user_privileges();
+void write_constants();
 void general_on_error();
 
 
@@ -505,6 +506,13 @@ int BACKUP_backup(const TEXT* dbb_file, const TEXT* file_name)
 		write_pub_tables();
 	}
 
+	if (tdgbl->runtimeODS >= DB_VERSION_DDL14)
+	{
+		// Write constants
+		BURP_verbose(USHORT(isc_gbak_writing_constants));	// writing constants
+		write_constants();
+	}
+
 	// Finish up
 
 	put(tdgbl, (UCHAR) rec_end);
@@ -4845,6 +4853,61 @@ void write_user_privileges()
 	MISC_release_request_silent(req_handle1);
 }
 
+void write_constants()
+{
+	Firebird::IRequest* req_handle1 = nullptr;
+
+	BurpGlobals* tdgbl = BurpGlobals::getSpecific();
+
+	FOR (REQUEST_HANDLE req_handle1)
+		CONST IN RDB$CONSTANTS CROSS
+		PKG IN RDB$PACKAGES WITH
+			CONST.RDB$SCHEMA_NAME EQ PKG.RDB$SCHEMA_NAME AND
+			CONST.RDB$PACKAGE_NAME EQ PKG.RDB$PACKAGE_NAME AND
+			PKG.RDB$SYSTEM_FLAG NE 1
+	{
+		QualifiedMetaString name(CONST.RDB$CONSTANT_NAME);
+
+		put(tdgbl, rec_constants);
+		PUT_TEXT(att_constant_name, CONST.RDB$CONSTANT_NAME);
+
+		PUT_TEXT(att_constant_package, CONST.RDB$PACKAGE_NAME);
+		name.package = CONST.RDB$PACKAGE_NAME;
+
+		PUT_TEXT(att_constant_field_source, CONST.RDB$FIELD_SOURCE);
+
+		if (!CONST.RDB$PRIVATE_FLAG.NULL)
+			put_int32(att_constant_private_flag, CONST.RDB$PRIVATE_FLAG);
+
+		if (!CONST.RDB$CONSTANT_BLR.NULL)
+			put_blr_blob(att_constant_blr, CONST.RDB$CONSTANT_BLR);
+
+		if (!CONST.RDB$CONSTANT_SOURCE.NULL)
+			put_source_blob(att_constant_source, att_constant_source, CONST.RDB$CONSTANT_SOURCE);
+
+		if (!CONST.RDB$SCHEMA_NAME.NULL)
+		{
+			PUT_TEXT(att_constant_schema_name, CONST.RDB$SCHEMA_NAME);
+			name.schema = CONST.RDB$SCHEMA_NAME;
+		}
+
+		if (!CONST.RDB$DESCRIPTION.NULL)
+		{
+			put_source_blob (att_constant_description, att_constant_description, CONST.RDB$DESCRIPTION);
+		}
+
+		// writing constant %s
+		BURP_verbose(USHORT(isc_gbak_writing_constant), SafeArg() << name.toQuotedString().data());
+		put(tdgbl, att_end);
+	}
+	END_FOR;
+	ON_ERROR
+		general_on_error();
+	END_ERROR;
+
+	MISC_release_request_silent(req_handle1);
+}
+
 } // namespace
 
 namespace Burp {

src/burp/burp.h

@@ -124,7 +124,8 @@ enum rec_type {
 	rec_db_creator,			// Database creator
 	rec_publication,		// Publication
 	rec_pub_table,			// Publication table
-	rec_schema				// Schema
+	rec_schema,				// Schema
+	rec_constants			// Constants
 };
 
 
@@ -701,6 +702,16 @@ enum att_type {
 	att_schema_security_class,
 	att_schema_owner_name,
 	att_schema_description,
+
+	// Constants
+	att_constant_name = SERIES,
+	att_constant_package,
+	att_constant_field_source,
+	att_constant_private_flag,
+	att_constant_blr,
+	att_constant_source,
+	att_constant_schema_name,
+	att_constant_description,
 };
 
 

src/burp/restore.epp

@@ -167,6 +167,7 @@ bool	get_trigger_old (BurpGlobals* tdgbl, burp_rel*);
 bool	get_type(BurpGlobals* tdgbl);
 bool	get_user_privilege(BurpGlobals* tdgbl);
 bool	get_view(BurpGlobals* tdgbl, burp_rel*);
+bool	get_constants_table(BurpGlobals* tdgbl);
 void	ignore_array(BurpGlobals* tdgbl, burp_rel*);
 void	ignore_blob(BurpGlobals* tdgbl);
 rec_type	ignore_data(BurpGlobals* tdgbl, burp_rel*);
@@ -10556,6 +10557,85 @@ bool get_view(BurpGlobals* tdgbl, burp_rel* relation)
 	return true;
 }
 
+bool get_constants_table(BurpGlobals* tdgbl)
+{
+	if (tdgbl->runtimeODS < DB_VERSION_DDL14)	// FB6
+		return false;
+
+	QualifiedMetaString name;
+
+	att_type attribute;
+	scan_attr_t scan_next_attr;
+
+	Firebird::ITransaction* local_trans = tdgbl->global_trans ? tdgbl->global_trans : gds_trans;
+
+	STORE (TRANSACTION_HANDLE local_trans
+			REQUEST_HANDLE tdgbl->handles_get_type_req_handle1)
+		CONST IN RDB$CONSTANTS
+	{
+		skip_init(&scan_next_attr);
+		while (skip_scan(&scan_next_attr), get_attribute(&attribute, tdgbl) != att_end)
+		{
+			switch (attribute)
+			{
+			case att_constant_name:
+				CONST.RDB$CONSTANT_NAME.NULL = FALSE;
+				GET_TEXT(CONST.RDB$CONSTANT_NAME);
+				name.object = CONST.RDB$CONSTANT_NAME;
+				break;
+
+			case att_constant_package:
+				CONST.RDB$PACKAGE_NAME.NULL = FALSE;
+				GET_TEXT(CONST.RDB$PACKAGE_NAME);
+				name.package = CONST.RDB$PACKAGE_NAME;
+				break;
+
+			case att_constant_field_source:
+				CONST.RDB$FIELD_SOURCE.NULL = FALSE;
+				GET_TEXT(CONST.RDB$FIELD_SOURCE);
+				break;
+
+			case att_constant_private_flag:
+				CONST.RDB$PRIVATE_FLAG.NULL = FALSE;
+				CONST.RDB$PRIVATE_FLAG = (USHORT) get_int32(tdgbl);
+				break;
+
+			case att_constant_blr:
+				CONST.RDB$CONSTANT_BLR.NULL = FALSE;
+				get_blr_blob(tdgbl, CONST.RDB$CONSTANT_BLR, true);
+				break;
+
+			case att_constant_source:
+				CONST.RDB$CONSTANT_SOURCE.NULL = FALSE;
+				get_source_blob(tdgbl, CONST.RDB$CONSTANT_SOURCE, true);
+				break;
+
+			case att_constant_schema_name:
+				CONST.RDB$SCHEMA_NAME.NULL = FALSE;
+				GET_TEXT(CONST.RDB$SCHEMA_NAME);
+				name.schema = CONST.RDB$SCHEMA_NAME;
+				break;
+
+			case att_constant_description:
+				CONST.RDB$DESCRIPTION.NULL = FALSE;
+				get_source_blob(tdgbl, CONST.RDB$DESCRIPTION, true);
+				break;
+			default:
+				bad_attribute(scan_next_attr, attribute, USHORT(isc_gbak_constant));
+				break;
+			}
+		}
+
+		BURP_verbose(USHORT(isc_gbak_restoring_constant), SafeArg() << name.toQuotedString().data());
+	}
+	END_STORE;
+	ON_ERROR
+		general_on_error();
+	END_ERROR;
+
+	return true;
+}
+
 void ignore_array(BurpGlobals* tdgbl, burp_rel* relation)
 {
 /**************************************
@@ -11399,6 +11479,12 @@ bool restore(BurpGlobals* tdgbl, Firebird::IProvider* provider, const TEXT* file
 			flag = true;
 			break;
 
+		case rec_constants:
+			if (!get_constants_table(tdgbl))
+				return false;
+			flag = true;
+			break;
+
 		default:
 			BURP_error(43, true, SafeArg() << record);
 			// msg 43 don't recognize record type %ld

src/common/ParserTokens.h

@@ -138,6 +138,7 @@ PARSER_TOKEN(TOK_CONDITIONAL, "CONDITIONAL", true)
 PARSER_TOKEN(TOK_CONNECT, "CONNECT", false)
 PARSER_TOKEN(TOK_CONNECTIONS, "CONNECTIONS", true)
 PARSER_TOKEN(TOK_CONSISTENCY, "CONSISTENCY", true)
+PARSER_TOKEN(TOK_CONSTANT, "CONSTANT", true)
 PARSER_TOKEN(TOK_CONSTRAINT, "CONSTRAINT", false)
 PARSER_TOKEN(TOK_CONTAINING, "CONTAINING", true)
 PARSER_TOKEN(TOK_CONTINUE, "CONTINUE", true)