create or replace PACKAGE CT_MRDS.FILE_ARCHIVER 
AUTHID CURRENT_USER
AS
   /**
      * General comment for package: Please put comments for functions and procedures as shown in below example.
      * It is a standard.
      * The structure of comment is used by GET_PACKAGE_DOCUMENTATION function 
      * which returns documentation text for confluence page (to Copy-Paste it).
   **/

   -- Example comment:
         /**
            * @name     EX_PROCEDURE_NAME
            * @desc     Procedure description
            * @example  select LOGGING_AND_ERROR_MANAGER.EX_PROCEDURE_NAME(pParameter => 129) from dual;
            * @ex_rslt  Example Result
         **/

   -- Package Version Information (Semantic Versioning: MAJOR.MINOR.PATCH)
   PACKAGE_VERSION     CONSTANT VARCHAR2(10) := '3.1.0';
   PACKAGE_BUILD_DATE  CONSTANT VARCHAR2(20) := '2026-01-29 21:00:00';
   PACKAGE_AUTHOR      CONSTANT VARCHAR2(100) := 'Grzegorz Michalski';

   -- Version History (Latest changes first)
   VERSION_HISTORY     CONSTANT VARCHAR2(4000) := 
      '3.1.0 (2026-01-29): Added function overloads for ARCHIVE_TABLE_DATA and GATHER_TABLE_STAT returning SQLCODE for Python library integration' || CHR(13)||CHR(10) ||
      '3.0.0 (2026-01-27): MARS-828 - Added flexible archival strategies (MINIMUM_AGE_MONTHS with 0=current month, HYBRID) via ARCHIVAL_STRATEGY configuration' || CHR(13)||CHR(10) ||
      '2.0.0 (2025-10-22): Added package versioning system using centralized ENV_MANAGER functions' || CHR(13)||CHR(10) ||
      '1.5.0 (2025-10-18): Enhanced ARCHIVE_TABLE_DATA with Hive-style partitioning support' || CHR(13)||CHR(10) ||
      '1.0.0 (2025-09-15): Initial release with table archival and statistics gathering';

   cgBL       CONSTANT  VARCHAR2(2)   := ENV_MANAGER.cgBL;

   /**
      * @name     ARCHIVE_TABLE_DATA
      * @desc     Wrapper procedure for DBMS_CLOUD.EXPORT_DATA.
      *           Exports data from table specified by pSourceFileConfigKey(A_SOURCE_FILE_CONFIG.A_SOURCE_FILE_CONFIG_KEY) into PARQUET file on OCI infrustructure.
      *           Each YEAR_MONTH pair goes to seperate file (implicit partitioning).
   **/
   PROCEDURE ARCHIVE_TABLE_DATA (
      pSourceFileConfigKey   IN CT_MRDS.A_SOURCE_FILE_CONFIG.A_SOURCE_FILE_CONFIG_KEY%TYPE
   );

   /**
      * @name     ARCHIVE_TABLE_DATA
      * @desc     Function overload for ARCHIVE_TABLE_DATA procedure.
      *           Returns SQLCODE for Python library integration.
      *           Calls the main ARCHIVE_TABLE_DATA procedure and captures execution result.
      * @example  SELECT FILE_ARCHIVER.ARCHIVE_TABLE_DATA(pSourceFileConfigKey => 123) FROM DUAL;
      * @ex_rslt  0 (success) or error code
   **/
   FUNCTION ARCHIVE_TABLE_DATA (
      pSourceFileConfigKey   IN CT_MRDS.A_SOURCE_FILE_CONFIG.A_SOURCE_FILE_CONFIG_KEY%TYPE
   ) RETURN PLS_INTEGER;



   /**
      * @name     GATHER_TABLE_STAT
      * @desc     Gather info about EXTERNAL TABLE specified by pSourceFileConfigKey parameter (A_SOURCE_FILE_CONFIG.A_SOURCE_FILE_CONFIG_KEY).
      *           Data is inserted into A_TABLE_STAT and A_TABLE_STAT_HIST.
   **/
   PROCEDURE GATHER_TABLE_STAT (
      pSourceFileConfigKey   IN CT_MRDS.A_SOURCE_FILE_CONFIG.A_SOURCE_FILE_CONFIG_KEY%TYPE
   );

   /**
      * @name     GATHER_TABLE_STAT
      * @desc     Function overload for GATHER_TABLE_STAT procedure.
      *           Returns SQLCODE for Python library integration.
      *           Calls the main GATHER_TABLE_STAT procedure and captures execution result.
      * @example  SELECT FILE_ARCHIVER.GATHER_TABLE_STAT(pSourceFileConfigKey => 123) FROM DUAL;
      * @ex_rslt  0 (success) or error code
   **/
   FUNCTION GATHER_TABLE_STAT (
      pSourceFileConfigKey   IN CT_MRDS.A_SOURCE_FILE_CONFIG.A_SOURCE_FILE_CONFIG_KEY%TYPE
   ) RETURN PLS_INTEGER;

   ---------------------------------------------------------------------------------------------------------------------------
   -- PACKAGE VERSION MANAGEMENT FUNCTIONS
   ---------------------------------------------------------------------------------------------------------------------------

   /**
      * @name     GET_VERSION
      * @desc     Returns the current version number of the FILE_ARCHIVER package.
      *           Uses semantic versioning format (MAJOR.MINOR.PATCH).
      * @example  SELECT FILE_ARCHIVER.GET_VERSION() FROM DUAL;
      * @ex_rslt  2.0.0
   **/
   FUNCTION GET_VERSION RETURN VARCHAR2;

   /**
      * @name     GET_BUILD_INFO
      * @desc     Returns comprehensive build information including version, build date, and author.
      *           Uses centralized ENV_MANAGER.GET_PACKAGE_VERSION_INFO function.
      * @example  SELECT FILE_ARCHIVER.GET_BUILD_INFO() FROM DUAL;
      * @ex_rslt  Package: FILE_ARCHIVER
      *           Version: 2.0.0
      *           Build Date: 2025-10-22 16:45:00
      *           Author: Grzegorz Michalski
   **/
   FUNCTION GET_BUILD_INFO RETURN VARCHAR2;

   /**
      * @name     GET_VERSION_HISTORY
      * @desc     Returns complete version history with all releases and changes.
      *           Uses centralized ENV_MANAGER.FORMAT_VERSION_HISTORY function.
      * @example  SELECT FILE_ARCHIVER.GET_VERSION_HISTORY() FROM DUAL;
      * @ex_rslt  FILE_ARCHIVER Version History:
      *           2.0.0 (2025-10-22): Added package versioning system...
   **/
   FUNCTION GET_VERSION_HISTORY RETURN VARCHAR2;

END;

/