/*MAIN
 Overview
 
 RATIO_RULE is a function called by the main reconstruction procedure
    RECONSTRUCTION1.  This function computes the ratio of entries in the BFST
    to the sum of entries in the BFST plus entries in the GFST times the number
    of minor frames per major frame.  This funtion serves as indicator to the
    analyst as to how bad the data in a session is.  For each session with 
    in the BFST and GFST, function RATIO_RULE computes a ratio R which it
    compares against the configuration parameter RATIO (this parameter is
    an empirically derived treshold value beyond which a session is said to
    have very bad data): If R is greater than RATIO, function RATIO_RULE returns
    "FAIL" to procedure RECONSTRUCTION1 and reconstruction ends, and if R is
    less than or equal to RATIO, function RATIO_RULE returns "PASS" to procedure
    RECONSTRUCTION1 and reconstruction proceeds.
    proceeds.  
MAIN*/

/*ARGUMENTS
  Arguments
 
  RATIO_RULE takes the following arguments, all of which have an IN 
  parameter mode:
   - GFST (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.

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

   - Return value of the function (VARCHAR2).  There are two possible return
     values: PASS or FAIL.
ARGUMENTS*/

/*DEPENDENCIES
 Dependencies
 
 The following are the procedures called by RATIO_RULE (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.

   - COUNT_ALL.  This is a stored function created to count all entries in any
     table.  This function takes in as argument the name of the table to count
     from (as a varchar2), and any "where" clause that may be used to constraint
     the count (as a varchar2).  Note that if no "where" clause is to be used in 
     a count, the second argument to this function is optional.

   - 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:
   - nGFST (INTEGER).  The number of entries in the GFST.

   - nBFST (INTEGER).  The number of entries in the BFST.

   - NMNF (INTEGER).  The number of minor frames per major frames.

   - R (NUMBER(10,6)).  The computed values of the session's ratio.

   - Desired_R_Value (NUMBER(10,6)).  The value of the configuration parameter RATIO
     (this parameter is an empirically derived treshold value beyond which a session
     is said to have very bad data).
VARIABLES*/

/*EXAMPLES
  Examples
 
  Here is a call to RATIO_RULE:
 
   BEGIN
        IF RATIO_RULE ('PWIW1997287095646983GOOD','PWIW1997287095644634BAD') = 'PASS'
        THEN
            NULL;
        END IF;
   END;
   /
 
 The arguments of this function 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.
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.

  - BFST. This is the Bad Frame 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 when function RATIO_RULE returns "FAIL", reconstruction 
   terminates.  There are three possible courses of action that the analyst may
   take:

   -  the analyst may take a closer look at the data and decide that it is not 
      worth processing, and ask for a retransmission.

   -  the analyst may force the session to reconstruct by increasing the mission
      configuration parameter RATIO.

   -  the analyst may also force the session to reconstruct by turning the rule
      RATIO_RULE off for the mission through the Graphical user interface or
      directly through and interactive SQL session.

   If any of the latter two actions are taken, the analyst should afterward revert
   the states of the mission configuration parameter RATIO, or the switch settings
   of the reconstruction rules back to what they were prior to being changed.

 Note that the configuration parameter RATIO was derived empirically, based on
   multiple runs and a track down on what the ratio for normal data is.

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