/*MAIN
 Overview

 GFST_CHECK_SPANS is a sub-procedure of the main reconstruction procedure
    RECONSTRUCTION1.  This procedure modifies the structure of the GFST by
    adding a new column DATASPAN (NUMBER(3)).  Major frames of the same data
    span will have the same DATASPAN number.  Major frames with the same CDM
    (current data mode) and DISC (discontinuity) are identified as belongin 
    to the same data span.  The DATASPAN number is incremented by one for the
    next data span.  
MAIN*/

/*ARGUMENTS
  Arguments

  GFST_CHECK_SPANS takes the following arguments:
   - GFST (IN VARCHAR2).  This variable 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.

   - SPAN_NUMBER (OUT INTEGER).  Represents the number of dataspans found in the
     session's GFST.  This values is returned to the parent procedure RECONSTRUCTION1.
ARGUMENTS*/

/*DEPENDENCIES
 Dependencies
 
 The following are the procedures called by GFST_CHECK_SPANS (listed in their
 order of call):
   - SWITCH.  This is the package that manipulates the switches for all 
     the reconstruction rules.

   - RULES_STATES.  This is a package of three procedures and one function all
     of which track and post reconstruction states for all rules as they become
     available, in the temporary table LOGT.

   - RULE.  This is the stored package that manipulates the reconstruction rules
     numbers, name and version number.

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

   - 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_SQL.  This the native Oracle dynamic SQL package.

   - 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.

   - DBMS_SQL.  This the native Oracle dynamic SQL package.

   - 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.

   - 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.
DEPENDENCIES*/

/*VARIABLES
 Variables

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

   - 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.

   - LIMIT_DATA_SPAN_NUMBER1 (INTEGER).  Represents the limit data span number, a
     configuration parameter empirically derived which stands for the maximum number 
     of data spans that may be found in the GFST.  

   - CURRENT_CDM (INTEGER).  Represents the current CDM (current data mode) of a data
     span.

   - CURRENT_DISC (INTEGER).  Represents the current DISC (discontinuity count) of a
     data span.

   - COUNT_SPAN (INTEGER, default 0).  Represents a running count of the number of 
     data spans found in the GFST.
VARIABLES*/

/*EXAMPLES
  Examples
 
  Here are two calls to RECONSTRUCTION1:
 
   DECLARE 
   SPAN_NUMBER  INTEGER;

   BEGIN
       GFST_CHECK_SPANS ('GEOTAIL1997274142242671GOOD', SPAN_NUMBER);
   END;
   /
 
 The argument GFST of this procedure is passed in from Assembly/Decommutation.  
 The second argument is a variable which will be assigned a value after procedure
 GFST_CHECK_SPANS has executed.  The latter argument will be evaluated by 
 procedure RECONSTRUCTION1 against the configuration parameter LIMIT_DATA_SPAN_NUMBER
 and the outcome of this evaluation will determined whether RECONSTRUCTION1 will 
 proceed or terminates.
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.  
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.
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.

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

/*OTHERS
 Others
 
 It should be noted that the argument SPAN_NUMBER taken by this procedure is
   used by the parent procedure RECONSTRUCTION1 to decide whether to proceed
   with reconstruction or to abort.  If the SPAN_NUMBER returned is greater
   than the configuration parameter LIMIT_DATA_SPAN_NUMBER, reconstruction
   will abort and if the reverse is true, reconstruction will proceed.
  
   If reconstruction terminates prematurely because of the SPAN_NUMBER, the 
   analyst may force a reconstruction by increasing the configuration 
   parameter LIMIT_DATA_SPAN_NUMBER and re-running the session.  The analyst
   may also request a re-transmission of the data.

   The SPAN_NUMBER number is another means the analyst has to detect data that
   may have problem.

 Note that the configuration parameter LIMIT_DATA_SPAN_NUMBER was derived 
   empirically, based on multiple runs and a track down on the normal number 
   data spans found in data.

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