 
      SUBROUTINE JOIN2(MM, M, N, A, CLAB, RLAB, TITLE, KC, TH, DMWORK,
     *                WORK1, WORK2, IWORK, DMIWRK, IWORK1, CWORK, IERR,
     *                OUNIT)
C
C<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
C
C   PURPOSE
C   -------
C
C      JOINS DATA VALUES IN A CASE-BY-VARIABLE MATRIX INTO BLOCKS UNTIL
C      ALL WITHIN-BLOCK VARIANCES ARE GREATER THAN A USER-SPECIFIED
C      THRESHOLD
C
C   DESCRIPTION
C   -----------
C
C   1.  THE THRESHOLD IS THE LARGEST WITHIN-BLOCK VARIANCE FOR THE DATA
C       VALUES.  THE VARIABLES SHOULD BE SCALED SIMILARLY (CLUSTER
C       SUBROUTINE STAND CAN BE USED TO STANDARDIZE THE VARIABLES).
C       THE ROUTINE STARTS WITH EACH VALUE IN THE DATA MATRIX FORMING A
C       BLOCK.  THEN THE DISTANCES BETWEEN THE VARIABLES AND THE CASES
C       FOR EACH PAIR OF BLOCKS ARE DETERMINED.  THE SMALLEST OF ALL
C       DISTANCES IS FOUND AND THE CORRESPONDING BLOCKS ARE JOINED TO
C       FORM A NEW BLOCK PROVIDED THE VARIANCE OF EACH VARIABLE IN THE
C       NEW BLOCK IS SMALLER THAN THE THRESHOLD.  THE DISTANCES ARE
C       UPDATED AND THE PROCESS REPEATS UNTIL THE NEW BLOCK HAS A
C       LARGER VARIANCE, THEN THE RESULTS ARE PRINTED IN A BLOCK
C       DIAGRAM ON FORTRAN UNIT OUNIT.  THE THRESHOLD SHOULD BE CHOSEN
C       WISELY AS A LARGE THRESHOLD WILL PRODUCE A FEW LARGE BLOCKS AND
C       A SMALL THRESHOLD WILL PRODUCE MANY SMALL BLOCKS.
C
C   2.  MISSING VALUES SHOULD BE REPRESENTED BY 99999.
C
C   3.  THE BLOCK DIAGRAM IS THE DATA MATRIX WITH THE DATA VALUES
C       MULTIPLIED BY 10.  THE BLOCKS ARE OUTLINED BY THE VERTICAL AND
C       HORIZONTAL LINES.
C
C   INPUT PARAMETERS
C   ----------------
C
C   MM    INTEGER SCALAR (UNCHANGED ON OUTPUT).
C         THE LEADING DIMENSION OF MATRIX A.  MUST BE AT LEAST M.
C
C   M     INTEGER SCALAR (UNCHANGED ON OUTPUT).
C         THE NUMBER OF CASES.
C
C   N     INTEGER SCALAR (UNCHANGED ON OUTPUT).
C         THE NUMBER OF VARIABLES.
C
C   A     REAL MATRIX WHOSE FIRST DIMENSION MUST BE MM AND SECOND
C            DIMENSION MUST BE AT LEAST N (CHANGED ON OUTPUT).
C         THE DATA MATRIX.
C
C         A(I,J) IS THE VALUE FOR THE J-TH VARIABLE FOR THE I-TH CASE.
C
C   CLAB  VECTOR OF 4-CHARACTER VARIABLES DIMENSIONED AT LEAST N
C            (CHANGED ON OUTPUT).
C         ORDERED LABELS OF THE COLUMNS.
C
C   RLAB  VECTOR OF 4-CHARACTER VARIABLES DIMENSIONED AT LEAST M
C            (CHANGED ON OUTPUT).
C         ORDERED LABELS OF THE ROWS.
C
C   TITLE 10-CHARACTER VARIABLE (UNCHANGED ON OUTPUT).
C         TITLE OF DATA SET.
C
C   KC    INTEGER SCALAR (UNCHANGED ON OUTPUT).
C         MAXIMUM NUMBER OF BLOCKS.  SHOULD BE BETWEEN M AND N*M.
C
C   TH    REAL SCALAR (UNCHANGED ON OUTPUT).
C         THRESHOLD VARIANCE FOR DATA VALUES WITHIN A BLOCK.
C
C   DMWORK INTEGER SCALAR (UNCHANGED ON OUTPUT).
C         THE LEADING DIMENSION OF MATRIX WORK1.  MUST BE AT LEAST M.
C
C   WORK1 REAL MATRIX WHOSE FIRST DIMENSION MUST BE DMWORK AND SECOND
C            DIMENSION MUST BE AT LEAST N.
C         WORK MATRIX.
C
C   WORK2 REAL VECTOR DIMENSIONED AT LEAST M + N.
C         WORK VECTOR.
C
C   IWORK INTEGER VECTOR DIMENSIONED AT LEAST 2*M + 2*N.
C         WORK VECTOR.
C
C   DMIWRK INTEGER SCALAR (UNCHANGED ON OUTPUT).
C         THE LEADING DIMENSION OF MATRIX IWORK1.  MUST BE AT LEAST 4.
C
C   IWORK1 INTEGER MATRIX WHOSE FIRST DIMENSION MUST BE DMIWRK AND
C            SECOND DIMENSION MUST BE AT LEAST KC.
C         WORK MATRIX.
C
C   CWORK VECTOR OF 4-CHARACTER VARIABLES DIMENSIONED AT LEAST MAX(M,N).
C         WORK VECTOR.
C
C   OUTPUT PARAMETER
C   ----------------
C
C   IERR  INTEGER SCALAR.
C         ERROR FLAG.
C
C         IERR = 0, NO ERRORS WERE DETECTED DURING EXECUTION
C
C         IERR = 1, THE NUMBER OF BLOCKS NEEDED WAS LARGER THAN THE
C                   NUMBER OF BLOCKS ALLOCATED.  EXECUTION IS
C                   TERMINATED.  INCREASE KC OR INCREASE THRESHOLD TO
C                   PRODUCE FEWER BLOCKS.
C
C         IERR = 2, EITHER THE FIRST AND LAST CASES OR THE CLUSTER
C                   DIAMETER FOR A CLUSTER IS OUT OF BOUNDS.  THE
C                   CLUSTER AND ITS BOUNDARIES ARE PRINTED ON UNIT
C                   OUNIT.  EXECUTION WILL CONTINUE WITH QUESTIONABLE
C                   RESULTS FOR THAT CLUSTER.
C
C         IERR = 3, THE THRESHOLD WAS SO LARGE THAT NO BLOCKS WERE
C                   GENERATED EXECUTION IS TERMINATED.  DECREASE
C                   THRESHOLD.
C
C   REFERENCES
C   ----------
C
C     HARTIGAN, J. A. (1975).  CLUSTERING ALGORITHMS, JOHN WILEY &
C        SONS, INC., NEW YORK.  PAGES 278-298.
C
C     HARTIGAN, J. A. (1975) PRINTER GRAPHICS FOR CLUSTERING. JOURNAL OF
C        STATISTICAL COMPUTATION AND SIMULATION. VOLUME 4,PAGES 187-213.
C
C<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
C
 
 
