/*MAIN
 Overview
 
 RECONSTRUCTION1 is the main reconstruction procedure, i.e. it is the procedure
    that is invoked to start up the reconstruction process.
MAIN*/

/*ARGUMENTS
  Arguments
 
  RECONSTRUCTION1 takes the following arguments, all of which have an IN 
  parameter mode:
   - GFST (VARCHAR2).  This argument represents the name of the Good Frames 
     Statistics Table that was posted by Labview just prior to the onset of 
     reconstruction.  Entries in the GFST were built and logged into a script
     file during processing of the annotated minor frames file by AD.

   - BFST (VARCHAR2).  This argument represents the name of the Bad Frames 
     Statistics Table that was posted by Labview just prior to the onset of
     reconstruction.  Entries in the GFST were built and logged into a script
     file during processing of the annotated minor frames file by AD.

   - START_TIME (NUMBER, default NULL).  This argument represents the time 
     from which a quick-look window of time from a message may start.
ARGUMENTS*/

/*DEPENDENCIES
 Dependencies
 
 The following are the procedures called by RECONSTRUCTION1 (listed in their
 order of call):
   - LOG_FILE.  This is a package of procedures which handle the tasks of 
     creating the file in which reconstruction output messages will be written
     to, writing to the latter file, and closing it at the end of 
     reconstruction.
   
   - SWITCH.  This is the package that manipulates the switches for all 
     the reconstruction rules.

   - DROP_OBJECT.  This procedure drops the specified object.

   - RULES_STATES.  This is a package of three procedures and one function all
     of which serve the role of writing the states of all rules as they become
     available, in the system_state table.

   - OPEN_AND_PARSE.  This function combines what would otherwise have
     been separate calls to the native Oracle DBMS_SQL.OPEN_CURSOR and
     DBMS_SQL.PARSE procedures, into a single function.

   - DBMS_UTILITY.GET_TIME.  The GET_TIME function of the native oracle package
     DBMS_UTILITY returns the elapsed time since an arbitrary time in 100ths of
     seconds

   - EXECUTE_AND_CLOSE.  This function combines what would otherwise have
     been separate calls to the native Oracle DBMS_SQL.EXECUTE and
     DBMS_SQL.CLOSE procedures, into a single function.

   - UNLOAD.  This procedure is responsible for saving away information from
     critical tables into their undo versions in case the session being 
     processed needs a rollback.

   - RECONSTRUCTION3.  This procedure is executed when the GFST has no data.

   - RECONSTRUCTION2.  This procedure is executed when the BFST has no data.

   - DBMS_SQL.  This the native Oracle dynamic SQL package.

   - UPDATE_MNFFPT.  This procedure is executed to update table MNFFPT (minor
     frames file pointer table) by assigning unique small and long pointer to
     the session being processed.

   - INITIALIZE.  This procedure performs some initialization steps on the 
     reconstruction tables, such as making sure that temporary tables do not 
     exist from a previous session, and truncating tables that need to be 
     truncated.

   - POST_STATE.  This is a package of three procedures and one function all
     of which serve the role of writing the states of all rules as they become
     available, in the system_state table.

   - RATIO_RULE.  This function computes the ratio of entries in the BFST to 
     entries in the BFST plus entries in the expanded GFST times the number of
     minor frames for major frame.

   - BFST_SET_MNFSKIP.  This function sets the minor frame skip in the BFST.

   - PWIW_ORDER_TIME.  This procedure sets the order time for the PWIW mission,
     i.e. that if turned on, the frames reconstructed are ordered by UTC time, 
     and if turned off the frames reconstructed will be ordered by spacecraft
     time which is the default.

   - GFST_CHECK_SPANS.  This procedure identifies the number of distinct 
     dataspans available in the GFST.

   - CONFIG.  This is the stored package that manipulates the configuration 
     parameters for all the reconstruction rules.

   - CP_LPOINTER.  This procedure inserts the session's long pointer into the 
     GFST as a new column.

   - GFST_PROCESS1.  This procedure dynamically add columns to the GFST and 
     checks for missing major frames within each dataspan of the GFST based 
     on periodicity.

   - CREATE_INDEXES.  This procedure creates indexes used during reconstruction.

   - BFST_SET_MNFCERR.  This procedure sets the minor frames counter error flag.

   - PWIW_SMOOTH_GRT.  This procedure smooths the PWIW ground receipt time when
     the order time is by UTC time.

   - RESET_TIME.  This procedure when turned on, sets the spacecraft time in the 
     BFST for each minor frame to that of minor frame 0 of the major frame to 
     which the minor frames belong, if the second argument to the procedure is
     -1, or sets the spacecraft time in the BFST for each minor frame to its 
     original value from that of minor frame 0, if the second argument to the 
     procedure is 1.

   - GFST_PROCESS2.  This procedure checks for missing major frames across 
     dataspans of the BFST based on periodicity for the following missions:
     WIND, POLAR, and GEOTAIL.

   - GFST_PROCESS2_PWIW.  This procedure checks for missing major frames across
     dataspans of the BFST based on periodicity for the PWIW mission.

   - BFST_SET_MODEERR.  This procedure sets the mode error flag for minor frames
     in the BFST for the following missions: WIND, POLAR, and GEOTAIL.

   - BFST_SET_MODEERR_PWIW.  This procedure sets the mode error flag for minor
     frames in the BFST for the PWIW mission.
 
   - BFST_SET_HRP_ERR.  This procedure sets the HRP sequence error flag for minor 
     frames in the BFST for the PWIW mission.

   - BFST_SET_DATEERR.  This procedure sets the date error flag for minor frames 
     in the BFST.

   - BFST_FILL_TIMES.  This procedure attempts to fill the spacecraft time for minor
     frames in the BFST where it was not originally unpacked so that they may be 
     identified and recovered.

   - BFST_CORRECT_UMNFC.  This procedure corrects the unpacked minor frame counter
     for the GEOTAIL mission.

   - BFST_REFILL_TIMES.  This procedure attempts to fill the spacecraft time for 
     minor frames in the BFST where it was not originally unpacked, and that did
     not get filled by procedure BFST_FILL_TIMES.

   - BFST_CHECK_FILLED_TIMES.  This procedure compares times computed against those
     originally unpacked in the BFST.

   - BFST_GET_MFT.  This procedure retrieves major frames to be reconstructed from 
     BFST and inserts them into the GFST for the following missions: WIND, POLAR, 
     and GEOTAIL.

   - BFST_GET_MFT_PWIW.  This procedure retrieves major frames to be reconstructed
     from the BFST and inserts them into the GFST for the PWIW mission.

   - DET_QL_WINDOW.  This procedure determines the quick-look window of time.

   - CROSS_CHECK_TIMES.  This procedure cross-checks the datetimes of grade 1 major
     frames in the GFST against those of major frames in the AFST.

   - CREATE_WFST.  This procedure creates the Working Frames Statistics Table.

   - WFST_VERIFY_TIME.  This procedure verifies the datetimes of major frames in the 
     WFST against that in the AFST and Minor Frames Location Tables (MNFLT1, ...).

   - BFST_FAIL_DUPLICATES.  This procedure fails duplicate minor frames in the 
     BFST.

   - CREATE_QUAL_COMP.  This procedure creates the temporary table QUAL_COMP.

   - GFST_CHECK_INSERTS.  This procedure checks entries in the GFST against entries
     in the temporary table GRADE2_TEMP_STOR.

   - GEN_RECIPE3.  This procedure generates a recipe for a quick-look session.

   - MFT_FILL_STATE.  This procedure reports on the the fill state of major frames
     reconstructed.

   - GEN_RECIPE1.  This procedure assigns pointers in the minor frames location 
     tables to minor frames of major frames reported in the BFST (and WFST).

   - CREATE_SPOINTERT1.  This procedure creates the temporary table SPOINTERT and
     inserts into it all small pointers referenced in the location tables across
     all major frames reconstructed within the current message.

   - UPDATE_CDM.  This procedure updates the Current Data Mode for all major frames
     reconstructed.  

   - BFST_ASS_QRANK.  This procedure assigns quality ranks to minor frames in the 
     BFST that will be part of the recipe of the following missions: WIND, POLAR,
     and GEOTAIL.

   - BFST_ASS_QRANK_PWIW.  This procedure assigns quality ranks to minor frames in
     the BFST that will be part of the recipe of the PWIW mission.

   - BFST_COMP_QUAL.  This procedure compares the quality of minor frames received
     during the current session with that of the same minor frames received in 
     previous sessions.

   - GEN_RECIPE2.  This procedure reads the session's recipe from the minor frame 
     location tables and writes it in the recipe table.

   - CREATE_TEMP_AFST.  This procedure creates the temporary table TEMP_AFST used
     by procedure QA_AFST to match major frames in the Accumulated Frames Statistics
     Table (AFST), against those in the GFST.

   - QA_AFST.  This procedure attempts to eliminate major frames in the AFST that
     are also reported in the GFST as grade 0 major frames.

   - UPDATE_IFST.  This procedure copies information on inverted minor frames in 
     the session's BFST and write it in the Inverted Frames Statistics Table (IFST).

   - SET_TTCD.  This procedure sets the Time Tag Correlation Data (TTCD) for GEOTAIL
     filled frames in the RECIPE table.
 
   - SET_HRP_SEQ_NO.  This procedure sets the High-Rate Processor (HRP) sequence
     number for PWIW filled frames in HRP mode in the RECIPE table.

   - TERMINATE_REC.  This procedure performs some closure steps on the reconstruction
     tables, such as making sure that temporary tables are dropped, cached tables are
     altered to non-cached when appropriate, and not needed indexes are dropped.

   - EX_RECONSTRUCTION1.  This is the exception procedure to procedure RECONSTRUCTION1.
     This procedure drop temporary objects created during reconstruction in case of any
     failure within procedure RECONSTRUCTION1.
DEPENDENCIES*/

/*VARIABLES
 Variables

 The following are variables used in the procedure:
   - C (INTEGER). Cursor handle.

   - EXECUTE1 (INTEGER).  The number of rows processed by the SQL statement
     if that statement is an UPDATE, INSERT, or DELETE.  If the SQL statement is
     not an UPDATE, INSERT, or DELETE, this value should be ignored.

   - X (VARCHAR2(50)).  Represents the GFST.

   - Y (VARCHAR2(50)).  Represents the BFST.

   - DIRECTION1 (INTEGER).  Represents the direction of the message: forward or
     reverse ordered.

   - AMF_FILE1 (MNFFPT.AMF_FILE%TYPE).  Represents the name of the annotated minor 
     frames file created for this session by the Frame Synchronizer software.

   - NUM_MISSING (INTEGER).  Represents the total number of major frames found 
     missing in the session's GFST.

   - RETURN_VAL1 (INTEGER).  Represents the number of major frames found missing 
     within the dataspans of the GFST.

   - RETURN_VAL2 (INTEGER, default 0).  Represents the number of major frames found  
     missing across the dataspans of the GFST.

   - RETURN_VAL3 (INTEGER, default 0).  Represents the number of major frames found  
     missing across the dataspans of the GFST for the PWIW mission.

   - SPAN_NUMBER (INTEGER).  Represents the number of dataspans found in the
     session's GFST.
VARIABLES*/

/*EXAMPLES
  Examples
 
  Here are two calls to RECONSTRUCTION1:
 
   BEGIN
       RECONSTRUCTION1 ('GEOTAIL1997274142242671GOOD','GEOTAIL1997274142239896BAD');
   END;
   /

   BEGIN
       RECONSTRUCTION1 ('GEOTAIL1997274142242671GOOD','GEOTAIL1997274142239896BAD',
                        2952303829.622000);
   END;
   /
 
 The arguments of this procedure are passed in from Assembly/Decommutation. 
EXAMPLES*/

/*EXCEPTIONS
 Exceptions

 There are no named exceptions for this procedure, except for the generic one
   WHEN OTHERS.  When the latter is triggered, the error message is outputted
   along with the name of the module that erred, and any cursors that may still
   be opened are closed.  Should and unknown exception trigger and error within 
   procedure RECONSTRUCTION1, procedure EX_RECONSTRUCTION1 is executed to drop 
   temporary objects created during reconstruction.
EXCEPTIONS*/

/*ERRORS
 Errors

 There are no errors that this procedure is known to generate.  Should an
   error occur, take action based on the description of the error.  Also when
   an error occurs within procedure RECONSTRUCTION1, procedure EX_RECONSTRUCTION1
   is executed to drop temporary objects created during reconstruction.
ERRORS*/

/*TABLES
 Tables
 
 The following tables are referenced in this procedure:
  - GFST. This is the Good Frames Statistics Table that was posted by
    AD just prior to the onset of reconstruction.

  - LOGT.  This is the log table in which the states of all rules are dynamically
    posted and computed before being written to the system_state table.

  - BFST. This is the Bad Frame statistics Table that was posted by AD
    just prior to the onset of reconstruction.

  - SESSIONS_PARAMETERS.  This table stores information on parameters of all 
    reconstruction sessions.

  - AFST.  This is the Accumulated Frames Statistics Table, which stores information
    about major frames of all grades that have ever been processed.

  - WFST.  This is the Working Frames Statistics Table, a temporary table
    created to hold information on missing and reconstructed frames that
    will ultimately be written to the AFST.

 For more information on these and other tables, see the documentation on tables.
TABLES*/

/*OTHERS
 Others
 
 It should be noted that this is the main reconstruction procedure which sits
   at the top of the rules hierarchy. The third argument to this procedure
   (START_TIME) is supplied only when AD requests a quick-look session, else it
   is not required.  The mandatory arguments are the names of the GFST and BFST
   table.  Prior to invoking procedure RECONSTRUCTION1, AD would have created
   the latter two tables by executing their respective script file built during
   processing of the annotated minor frame file.

 Also note that in this procedure table LOGT is updated through INSERT and UPDATE
   statements whereas in other procedures (except INITIALIZE and UPDATE_MNFFPT, 
   UNLOAD, RECONSTRUCTION2, and RECONSTRUCTION3), table LOGT is updated through
   the RULES_STATES package.  The reason for the latter is because the session's
   pointer has not been assigned through procedure UPDATE_MNFFPT, and the events
   count has not been initialized through procedure POST_STATE.INIT_EVENT.

 At the end of execution of procedure RECONSTRUCTION1, the state for the procedure is
   posted before the temporary table LOGT which track the rules' states is dropped and
   the handle to the reconstruction log file is released.
   This causes a delay of a few second between the time when the procedure is reported
   as having terminated its execution and the actual ending of the procedure.  This 
   can not be helped because RECONSTRUCTION is at the top of the rules's hierarchy.

 For more details on this procedure see the reconstruction documentation.
OTHERS*/
