                 TESTING THE PORT UTILITIES
          P. A. FOX, A. D. HALL, AND N. L. SCHRYER
                       FEBRUARY 1978
THE TAPE ON WHICH YOU FOUND THIS DOCUMENT HAS THREE FILES:
    FILE 1 - THIS OPERATIONS GUIDE
    FILE 2 - FORTRAN SOURCE FOR THE PORT UTILITY PROGRAMS
    FILE 3 - TEST PROGRAMS
THE NAMES OF THE PORT UTILITY SUBPROGRAMS, WHOSE  SOURCE  IS
PROVIDED  ON  THE  SECOND FILE, ARE LISTED BELOW IN AN ORDER
CONSISTENT   WITH   THE   REQUIREMENTS   OF    A    ONE-PASS
LOADER:  SUBPROGRAMS INVOKED BY OTHER SUBPROGRAMS COME AFTER
THEIR INVOKERS ON THE LIST.
                        ENTSRC
                        RETSRC
                        ISTKQU
                        ISTKMD
                        ISTKRL
                        ISTKGT
                        ISTKIN
                        ISTKST
                        I0TK00
                        R1MACH
                        D1MACH
                        NERROR
                        ERROFF
                        SETERR
                        EPRINT
                        E9RINT
                        I1MACH
                        I8SAVE
                        S88FMT
                        FDUMP
        SUBPROGRAMS CONSTITUTING THE PORT UTILITIES
FEBRUARY 1978              - 1 -        PORT UTILITIES TESTS
IN THIS OPERATIONS GUIDE WE DESCRIBE  THE TESTS TO  BE  USED
IN  CHECKING  THAT THE PORT UTILITIES, THAT IS, THE MACHINE-
CONSTANTS FUNCTIONS, THE AUTOMATIC ERROR HANDLING  ROUTINES,
AND  THE  STACK  ALLOCATION ROUTINES, ARE ALL OPERATING COR-
RECTLY ON A COMPUTER AFTER THEY HAVE BEEN INSTALLED.
THE THIRD FILE ON THIS TAPE CONTAINS THE FOLLOWING TESTS:
    A TEST OF THE PORT LINGUISTIC HYPOTHESES
    A TEST OF THE INSTALLATION OF THE MACHINE CONSTANTS
    THREE TESTS OF THE AUTOMATIC ERROR HANDLING
    TWO TESTS OF THE STACK ALLOCATOR
EACH TEST IS A SELF-CONTAINED PROGRAM CONSISTING OF  A  MAIN
PROGRAM AND PERHAPS ONE OR MORE SUBPROGRAMS.
BEFORE RUNNING THE TESTS, THE THREE PORT FUNCTIONS,  R1MACH,
D1MACH,  AND  I1MACH, WHICH RETURN REAL, FLOATING-POINT, AND
INTEGER CONSTANTS, RESPECTIVELY, MUST BE SET  FOR  THE  COM-
PUTER  ON WHICH THE TESTS ARE TO BE RUN.  IN PARTICULAR, THE
OUTPUT FROM  THE  TESTS  IS  WRITTEN  ON  THE  LOGICAL  UNIT
SPECIFIED BY I1MACH(2).
WITHIN THESE THREE  FUNCTIONS,  APPROPRIATE  CONSTANTS  HAVE
BEEN  SPECIFIED FOR MANY COMPUTER CLASSES, AND CONSTANTS FOR
YET OTHER MACHINES  CAN  EASILY  BE  ADDED.   THE  NUMERICAL
VALUES,  IN  THE FUNCTIONS, ARE GIVEN IN FORTRAN DATA STATE-
MENTS MADE INTO COMMENTS BY A C IN COLUMN 1.  TO  ADAPT  THE
FUNCTIONS TO A GIVEN COMPUTER, THE CORRESPONDING DATA STATE-
MENTS MUST BE MADE ACTIVE BY MAKING EACH INITIAL  C  INTO  A
BLANK.
AFTER THE THREE MACHINE-CONSTANTS FUNCTIONS HAVE  BEEN  PAR-
TICULARIZED  TO  THE HOST COMPUTER, THEY AND THE REST OF THE
SUBPROGRAMS CONSTITUTING THE PORT UTILITIES  (LISTED  ABOVE)
SHOULD  BE  COMPILED  ONTO  AN OBJECT LIBRARY FOR USE BY THE
TEST PROGRAMS.
FEBRUARY 1978              - 2 -        PORT UTILITIES TESTS
           TESTING THE PORT LINGUISTIC HYPOTHESES
THIS TEST CONSISTS OF ONE MAIN PROGRAM AND SOME SUBPROGRAMS.
THESE  PROGRAMS SHOULD BE RUN TO TEST THE FOLLOWING PREMISES
MADE IN  PORT  ON  THE  COMPILING  AND  RUNNING  OF  FORTRAN
PROGRAMS:
   1. A VARIABLE (LOCAL TO A SUBPROGRAM) THAT IS INITIALIZED
      BY  A  DATA STATEMENT AND THEN CHANGED WITHIN THE SUB-
C     PROGRAM, RETAINS ITS MOST RECENTLY ASSIGNED VALUE FROM
      ONE INVOCATION TO THE NEXT.
   2. THERE IS NO SUBSCRIPT RANGE CHECKING FOR DUMMY  ARRAYS
      OR  ARRAYS  IN  COMMON.   THUS  AN  ARRAY  WHICH  IS A
      PARAMETER IN A CALL TO A SUBPROGRAM, OR WHICH IS IN  A
      NAMED COMMON REGION, MAY BE INDEXED BEYOND ITS LOCALLY
      DECLARED LENGTH.
   3. IT IS LEGAL FOR A NAMED COMMON REGION TO  BE  DECLARED
      OF  DIFFERENT  LENGTHS  IN  VARIOUS  SUBPROGRAMS.  THE
      LENGTH ASSIGNED BY THE OPERATING SYSTEM TO SUCH A COM-
      MON  REGION  MUST  BE  THE LENGTH DECLARED IN THE MAIN
C     PROGRAM.
IF THIS TEST RUNS CORRECTLY, ONLY THE FOLLOWING LINE WILL BE
PRINTED OUT:
        TEST OF PORT LINGUISTIC HYPOTHESES COMPLETE.
IF THE TEST FINDS ERRORS, APPROPRIATE  DIAGNOSTICS  WILL  BE
PRINTED.
FEBRUARY 1978              - 3 -        PORT UTILITIES TESTS
           TESTING THE MACHINE CONSTANT FUNCTIONS
THIS TEST, CONSISTING OF A MAIN PROGRAM WITH SOME ASSOCIATED
SUBPROGRAMS,  CHECKS  THAT THE THREE PORT FUNCTIONS, R1MACH,
D1MACH, AND  I1MACH,  WHICH  ARE  USED  TO  OBTAIN  MACHINE-
DEPENDENT CONSTANTS, HAVE BEEN CORRECTLY ADAPTED TO THE COM-
PUTER USING THE PROCEDURE DESCRIBED ON PAGE 2.  A CHECK  FOR
THE  CONSISTENCY  OF  THE CONSTANTS IS MADE BY COMPARING THE
REAL AND DOUBLE-PRECISION  CONSTANTS  GIVEN  BY  R1MACH  AND
D1MACH  WITH  THE CORRESPONDING VALUES COMPUTED FROM THE IN-
TEGER SPECIFICATIONS GIVEN IN I1MACH.
THE OUTPUT FROM THIS TEST RUN ON  AN  IBM  370  COMPUTER  IS
GIVEN ON THE NEXT PAGE FOR REFERENCE.
THE DISAGREEMENT SHOWN AT THE END FOR THE VALUE OF D1MACH(5)
SAYS THAT THE VALUE OF THE LOG (TO THE BASE TEN) OF THE BASE
OF THE MACHINE AS PROVIDED BY D1MACH DOES NOT AGREE WITH THE
VALUE  CALCULATED  USING  THE  LOG ROUTINE ON THE LOCAL COM-
PUTER'S FORTRAN LIBRARY.  THIS USUALLY  OCCURS  BECAUSE  THE
LOG  ROUTINE  DOES  NOT CALCULATE THE VALUES TO THE ACCURACY
(LAST BIT) PROVIDED IN D1MACH.
FEBRUARY 1978              - 4 -        PORT UTILITIES TESTS
 FORMAT CONVERSION FOR INTEGERS IS - I12
 INTEGER CONSTANTS FOLLOW
 THE STANDARD INPUT UNIT                                        5
 THE STANDARD OUTPUT UNIT                                       6
 THE STANDARD PUNCH UNIT                                        7
 THE STANDARD ERROR MESSAGE UNIT                                6
 THE NUMBER OF BITS PER WORD                                   32
 THE NUMBER OF CHARACTERS PER WORD                              4
 A, THE BASE OF AN S-DIGIT INTEGER                              2
 S, THE NUMBER OF BASE-A DIGITS                                31
 A**S - 1, THE LARGEST MAGNITUDE                       2147483647
 B, THE BASE OF A T-DIGIT FLOATING-POINT NUMBER                16
 T, THE NUMBER OF BASE-B DIGITS IN SINGLE-PRECISION             6
 EMIN, THE SMALLEST SINGLE-PRECISION EXPONENT                 -64
 EMAX, THE LARGEST SINGLE-PRECISION EXPONENT                   63
 T, THE NUMBER OF BASE-B DIGITS IN DOUBLE-PRECISION            14
 EMIN, THE SMALLEST DOUBLE-PRECISION EXPONENT                 -64
 EMAX, THE LARGEST DOUBLE-PRECISION EXPONENT                   63
 FORMAT CONVERSION FOR SINGLE-PRECISION IS - E16.08
 SINGLE-PRECISION CONSTANTS FOLLOW
 THE SMALLEST POSITIVE MAGNITUDE    0.53976053E-78
 THE LARGEST MAGNITUDE              0.72370051E+76
 THE SMALLEST RELATIVE SPACING      0.59604645E-07
 THE LARGEST RELATIVE SPACING       0.95367432E-06
 LOG10 OF THE BASE                  0.12041197E+01
 FORMAT CONVERSION FOR DOUBLE-PRECISION IS - D25.17
 DOUBLE-PRECISION CONSTANTS FOLLOW
 THE SMALLEST POSITIVE MAGNITUDE    0.53976053469340279D-78
 THE LARGEST MAGNITUDE              0.72370055773322621D+76
 THE SMALLEST RELATIVE SPACING      0.13877787807814457D-16
 THE LARGEST RELATIVE SPACING       0.22204460492503131D-15
 LOG10 OF THE BASE                  0.12041199826559248D+01
 D1MACH(5) DOES NOT AGREE WITH CALCULATED VALUE
 D1MACH(5) =                        0.120411998265592479D+01
 CALCULATED VALUE =                 0.120411998265592457D+01
 DIFFERENCE =                       0.222044604925031308D-15
           MACHINE-CONSTANT TEST:  IBM 370 OUTPUT
FEBRUARY 1978              - 5 -        PORT UTILITIES TESTS
            TESTING THE AUTOMATIC ERROR HANDLING
THERE ARE THREE MAIN PROGRAMS FOR  TESTING  ERROR  HANDLING:
THE FOLLOWING PARAGRAPHS DESCRIBE THE ACTIONS THAT ARE TAKEN
BY THESE PROGRAMS AND THE OUTPUT THAT SHOULD BE PRODUCED.
    1. THE FIRST MAIN PROGRAM TESTS RECOVERABLE ERRORS.
       IT CHECKS THAT THE RECOVERY STATE IS CORRECTLY TURNED
       ON AND OFF BY THE PAIR OF PORT SUBPROGRAMS ENTSRC AND
       RETSRC,  AND  THAT  THE   ERROR-SETTING   SUBPROGRAM,
       SETERR,  THE  ERROR-PRINTING  SUBPROGRAM, EPRINT, AND
       THE SUBPROGRAM TO TURN OFF THE ERROR  STATE,  ERROFF,
       ALL WORK CORRECTLY.
       THE TEST STARTS OUT BY ENTERING  THE  RECOVERY  MODE,
       SETTING AN ERROR AND PRINTING THE ERROR USING EPRINT.
       THE OUTPUT SHOULD BE
        ERROR   1 IN FIRST ERROR TEST - RECOVERABLE ERROR OK
       THE ERROR STATE IS THEN TURNED OFF,  USING  THE  SUB-
C      PROGRAM  ERROFF,  AND A CHECK IS MADE TO BE SURE THAT
       IT IS OFF AND THAT NO ERROR MESSAGE  IS  OUTSTANDING.
       (THE SECOND EPRINT SHOULD FIND NO MESSAGE AND HAVE NO
       OUTPUT.)
       FINALLY A NEW RECOVERABLE ERROR IS SET WITH THE  MES-
       SAGE
        ERROR   2 IN SAME TEST - LEAVING RECOVERY MODE
       AND THE RECOVERY MODE IS SET TO NONRECOVERY USING THE
       SUBPROGRAM  RETSRC,  BUT SINCE IT IS ILLEGAL TO LEAVE
       THE RECOVERY STATE WHEN AN UNRECOVERED ERROR IS  OUT-
       STANDING,  THE  ABOVE  MESSAGE IS PRINTED OUT AND THE
       RUN TERMINATED.
FEBRUARY 1978              - 6 -        PORT UTILITIES TESTS
      TESTING THE AUTOMATIC ERROR HANDLING, CONTINUED
    2. THE SECOND MAIN PROGRAM  FOR  TESTING  ERROR-HANDLING
       TESTS FATAL ERRORS.
       A CALL IS MADE TO THE SUBPROGRAM, SETERR, SIGNALING A
       FATAL ERROR BY SETTING THE LAST ARGUMENT IN THE CALL,
       IOPT, TO 2.  THIS SHOULD CAUSE THE FOLLOWING  MESSAGE
       TO  BE  PRINTED,  THE  DUMP  SUBPROGRAM, FDUMP, TO BE
       CALLED AND THE RUN TERMINATED.
        ERROR   1 IN SECOND ERROR TEST - FATAL ERROR CHECKED
       THE FDUMP ROUTINE SENT OUT WITH THE PORT UTILITIES IS
       A  SIMPLE,  DUMMY, RETURN-END SUBPROGRAM.  INDIVIDUAL
       SITES SHOULD PROVIDE A LOCAL VERSION.
    3. THE THIRD MAIN PROGRAM  FOR  TESTING  ERROR  HANDLING
       CHECKS  THAT THE OCCURRENCE OF TWO RECOVERABLE ERRORS
       IN A ROW CAUSES A FATAL ERROR.
       THIS SITUATION CAN ONLY ARISE WHEN THE USER HAS  GONE
       INTO  THE  RECOVERY MODE, BECAUSE OTHERWISE THE FIRST
       ERROR IS CONSIDERED FATAL.  IN THE RECOVERY MODE, THE
       USER  IS EXPECTED TO RECOVER FROM A RECOVERABLE ERROR
       AND TURN IT OFF BEFORE RESUMING EXECUTION.
       THE TEST PROGRAM SETS THE FIRST RECOVERABLE ERROR  BY
       CALLING  SETERR,  AND  THEN  CALLS  IT  AGAIN  TO SET
       ANOTHER.  ON THE SECOND CALL SETERR SHOULD  SIGNAL  A
       FATAL  ERROR,  BY  PRINTING  THE FOLLOWING ERROR MES-
       SAGES, PROVIDING A DUMP AND TERMINATING THE RUN.
 ERROR   3 IN SETERR - AN UNRECOVERED ERROR FOLLOWED BY ANOTHER ERROR.
        THE PREVIOUS AND CURRENT ERROR MESSAGES FOLLOW.
        ERROR   1 IN MAIN - FIRST RECOVERABLE ERROR
        ERROR   2 IN MAIN - SECOND RECOVERABLE ERROR
FEBRUARY 1978              - 7 -        PORT UTILITIES TESTS
                    TESTING THE STACK ALLOCATOR
       THERE ARE TWO  TESTS  TO  BE  USED  FOR  TESTING  THE
       STORAGE ALLOCATION PACKAGE.  EACH OF THESE TESTS CON-
       SISTS OF A MAIN PROGAM  AND  ASSOCIATED  SUBPROGRAMS.
       THE FIRST TEST IS USED TO TEST THE STANDARD CASE WHEN
       THE STACK IS AUTOMATICALLY SET TO ITS DEFAULT LENGTH;
       THE  SECOND  TEST  IS  USED  TO  TEST THE ALTERNATIVE
       SITUATION WHERE THE USER HAS INITIALLY SET THE  STACK
       TO A DIFFERENT (NON-DEFAULT) LENGTH.
    1. THE FIRST ALLOCATOR TEST USES THE PORT DEFAULT  STACK
       LENGTH  OF  500 DOUBLE-PRECISION LOCATIONS.  THE TEST
       PROCEDURE CONSISTS OF A NUMBER OF ALLOCATIONS AND AS-
       SIGNMENTS  OF  VALUES  ON  THE STACK, FOLLOWED BY DE-
       ALLOCATIONS  AND  CHECKING  FOR  CONSISTENCY.   REAL,
       DOUBLE-PRECISION, COMPLEX, INTEGER AND LOGICAL VALUES
       ARE PUT ON THE STACK  IN  ALTERNATING  PATTERNS,  AND
       THEN  RELEASED.   ALL THE STACK-HANDLING ROUTINES ARE
       CALLED INTO PLAY TO BE SURE THE MECHANISM IS  WORKING
       AS IT SHOULD.
       BEFORE THE TEST IS RUN THE FOLLOWING LINE IS  PRINTED
       BY THE TEST PROGRAM:
 AN ERROR BELOW INDICATES TROUBLE WITH THE STORAGE ALLOCATOR,
 WHEN USING THE STACK WITH DEFAULT LENGTH.
       THEN, IF NO ERRORS HAVE BEEN FOUND DURING  THE  FIRST
       PART OF THIS TEST, THE FOLLOWING MESSAGE APPEARS:
        FIRST STORAGE ALLOCATION TEST COMPLETE.
       FINALLY,  THE TEST PROGRAM FORCES  AN  ERROR  BY  RE-
       QUESTING  MORE  SPACE  THAN IS LEFT ON THE STACK, AND
       THE FOLLOWING IS PRINTED, A CALL TO  FDUMP  MADE  AND
       THE RUN TERMINATED.
       NOW FORCE AN ERROR BY REQUESTING TOO MUCH SPACE.
        ERROR   4 IN ISTKGT - STACK TOO SHORT.
                 ENLARGE IT AND CALL ISTKIN IN MAIN PROGRAM.
FEBRUARY 1978              - 8 -        PORT UTILITIES TESTS
           TESTING THE STACK ALLOCATOR, CONTINUED
    2. THE SECOND STACK ALLOCATOR TEST IS EXACTLY  THE  SAME
       AS   THE   FIRST  EXCEPT  THAT  THE  STACK  IS  FIRST
       INITIALIZED, IN THE MAIN TEST PROGRAM, TO A LENGTH OF
       5000 DOUBLE-PRECISION LOCATIONS.
       BEFORE THE TEST IS  RUN,  THE  FOLLOWING  MESSAGE  IS
       PRINTED:
        AN ERROR BELOW INDICATES TROUBLE WITH THE ALLOCATOR,
        WHEN USING A STACK INITIALIZED TO NON-DEFAULT LENGTH.
       THEN, AGAIN, AFTER THE FIRST PART OF THE TEST IS RUN,
       PROVIDED  NO  ERRORS  HAVE  BEEN FOUND, THE FOLLOWING
       MESSAGE APPEARS:
        SECOND STORAGE ALLOCATOR TEST COMPLETE.
       FINALLY, THE TEST PROGRAM  FORCES  AN  ERROR  BY  RE-
       QUESTING  MORE  SPACE  THAN IS LEFT ON THE STACK, AND
       THE FOLLOWING IS PRINTED, A CALL TO  FDUMP  MADE  AND
       THE RUN TERMINATED.
       NOW FORCE AN ERROR BY REQUESTING TOO MUCH SPACE.
        ERROR   4 IN ISTKGT - STACK TOO SHORT.
                 ENLARGE IT AND CALL ISTKIN IN MAIN PROGRAM.
FEBRUARY 1978              - 9 -        PORT UTILITIES TESTS
