.;
.PS58,80;.LM 10;.RM 75;.LC;.FLAGS CAPITALIZE
.TITLE ^^MULTIPLE PRECISION ARITHMETIC PACKAGE\\
.TEST PAGE 10;.SKIP;.INDENT-10;^^SETM([NWRDS][,NPLACE][,ERR])\\
.BREAK;^SETS THE NUMBER OF WORDS (<NWRDS) OF PRECISION USED BY THE PACKAGE, AND
THE NUMBER OF PLACES TO THE RIGHT OF THE DECIMAL POINT ASSUMED.  ^THE DEFAULT FOR
<NWORDS IS 4, SO <REAL*8 VARIABLES CAN BE USED TO STORE MULTIPLE PRECISION VALUES.
^THE MAXIMUM VALUE ALLOWED FOR <NWRDS IS 10. ^INTERNAL REGISTERS IN THE
ROUTINES CAN NOT STORE VALUES LARGER THAN THAT.
^THE DEFAULT FOR <NPLACE IS 2 PLACES TO THE RIGHT OF THE DECIMAL POINT.
^IF EITHER OF THE FIRST TWO ARGUMENTS ARE LEFT OUT, THE DEFAULT VALUE, OR THE LAST
VALUE USED WITHIN A PROGRAM, WILL BE USED.
^IF THE <SETM ROUTINE IS CALLED AT ALL, IT SHOULD BE CALLED ONLY ONCE AND BEFORE ANY
OTHER MULTIPLE PRECISION ROUTINES ARE USED.  <SETM CHANGES THE WAY THAT
NUMBERS ARE REPRESENTED BY THE OTHER ROUTINES, AND CHANGING THIS REPRESENTATION
IN THE MIDDLE OF A RUN WOULD RESULT IN
NUMBERS BEING INTERPRETED INCORRECTLY.
^THE OPTIONAL <ERR ARGUMENT RETURNS A POSITIVE NUMBER IF YOUR PARAMETERS ARE GOOD, AND
A NEGATIVE NUMBER IF BAD.  ^BAD PARAMETERS MEANS YOU SPECIFIED A VALUE FOR <NPLACE
THAT REQUIRED MORE PRECISION THAN CAN BE STORED IN ONLY <NWRDS WORDS.  ^A QUICK
RULE OF THUMB IS: THE MAXIMUM VALUE OF <NPLACE IS ABOUT FOUR TIMES <NWRDS.
^INCIDENTALLY, THIS RULE ALSO APPLIES TO THE TOTAL NUMBER OF DIGITS
ALLOWED IN A SINGLE NUMBER.  ^FOR EXAMPLE, THE DEFAULT VALUE OF
FOUR IN <NWDS ALLOWS AT LEAST SIXTEEN DIGITS OF ACCURACY WHEN YOU COUNT
THE DIGITS BEFORE AND AFTER THE DECIMAL POINT.
^SOME OPERATIONS (<MULM AND <DIVM DESCRIBED BELOW) WILL PRODUCE INTERNAL
TEMPORARY VALUES THAT MAY REQUIRE MORE PRECISION THAN YOUR LARGEST NUMBER.
^TO AVOID OVERFLOW ERRORS IN THESE CASES, YOU CAN USE THE FOLLOWING RULE:
^MAKE SURE <NWDS*4 IS AT LEAST EQUAL TO THE MAXIMUM NUMBER OF DIGITS YOU
EXPECT, PLUS <NPLACE EXTRA DIGITS FOR SAFETY.  ^THE <NWDS*4 RULE IS IN
FACT A LITTLE CONSERVATIVE, BUT THIS LAST RULE IS ACCURATE.  ^THE
INTERMEDIATE VALUES PRODUCED BY <MULM AND <DIVM ARE EXACTLY <NPLACE
POWERS OF TEN LARGER THAN YOUR LARGEST NUMBER.
.TEST PAGE 10;.SKIP;.INDENT-10;^^INPM(RESULT,STRING[,LEN][,ERR])\\
.BREAK;^CONVERTS A STRING OF NUMERALS INTO THE INTERNAL BINARY
REPRESENTATION FOR A MULTIPLE PRECISION NUMBER.
<RESULT MUST BE A VARIABLE OR ARRAY LARGE ENOUGH TO CONTAIN A MULTIPLE
PRECISION NUMBER, (I.E., MUST BE <NWRDS LONG).  ^STRING SHOULD BE A BYTE
ARRAY CONTAINING A STRING OF NUMERALS TO BE CONVERTED.
^IF THE <LEN ARGUMENT IS MISSING, THEN <STRING IS ASSUMED TO BE TERMINATED WITH
A <NUL.  ^ALSO, IF A <NUL IS ENCOUNTERED IN THE STRING BEFORE <LEN
BYTES HAVE BEEN PROCESSED, THE <NUL BYTE DEFINES THE LENGTH, AND THE <LEN ARGUMENT
IS IGNORED. <INPM ACTUALLY REQUIRES A <NUL, AND PUTS ONE IN FOR YOU AFTER THE
^^LEN'\\TH BYTE IN <STRING WHEN YOU DO NOT INCLUDE ONE.  ^THIS MEANS
YOU MUST BE SURE TO ALLOCATE AT LEAST ONE EXTRA BYTE INTO ANY STRINGS YOU
SEND TO THIS ROUTINE.
^THE STRING CAN
CONTAIN DOLLAR SIGNS AND COMMAS, WHICH ARE IGNORED, AS WELL AS A
PLUS OR MINUS SIGN (MINUS SIGNS ARE NOT IGNORED).
^IF A DECIMAL POINT IS ENCOUNTERED, IT IS TREATED CORRECTLY,
BUT IF IT IS MISSING, THEN THE LAST <NPLACE NUMERALS IN THE STRING ARE ASSUMED TO BE
AFTER THE DECIMAL POINT.  ^IF MORE THAN <NPLACE NUMERALS OCCUR AFTER A DECIMAL
POINT, ROUNDING UP WILL BE DONE ON A 5 NUMERAL OR HIGHER, AND THE EXTRA DIGITS WILL
BE DISCARDED.
^THE OPTIONAL <ERR PARAMETER IS AN INTEGER VARIABLE THAT AN ERROR STATUS
WILL BE RETURNED IN.  ^A POSITIVE VALUE MEANS THE INPUT CONVERSION WAS SUCCESSFUL.
^A NEGATIVE VALUE MEANS THERE WERE ILLEGAL CHARACTERS IN THE STRING, OR THE VALUE
WAS TOO BIG TO STORE IN ONLY <NWRDS OF PRECISION.
^IF <INPM IS DECLARED <INTEGER IN THE CALLING PROGRAM, IT CAN BE CALLED
AS A FUNCTION AND THE VALUE RETURNED WILL BE THE SAME AS THE <ERR ARGUMENT.
<INPM CAN BE USED WITH QUOTED LITERALS TO INITIALIZE VARIABLES, FOR EXAMPLE:
^^CALL INPM(PROD,'1.00')\\.
.TEST PAGE 10;.SKIP;.INDENT -10;^^OUTM(VALUE,STRING,LEN,FORMAT[,FLEN][,ERR])\\
^CONVERTS A MULTIPLE PRECISION VALUE INTO A STRING OF NUMERALS READY FOR PRINTING.
<VALUE IS A VARIABLE OR ARRAY THAT CONTAINS A NUMBER TO BE CONVERTED.  <STRING IS
A BYTE ARRAY TO STORE THE RESULTING NUMERAL STRING IN.  <LEN IS THE LENGTH OF THE
<STRING VARIABLE IN BYTES, AND THIS PARAMETER IS REQUIRED SO THAT THE OUTPUT STRING
CAN BE RIGHT JUSTIFIED. ^CURRENTLY, <OUTM DOES NOT DETECT OVERFLOW
WHEN YOUR OUTPUT CANNOT FIT IN <LEN BYTES.  ^YOU SHOULD CAREFULLY COUNT
ALL THE CHARACTERS IN YOUR FORMATS AND MAKE SURE THEY WILL ALL ADD UP TO
<LEN OR FEWER BYTES.  ^IF YOU MAKE A MISTAKE IN THIS PARAMETER, <OUTM
CAN TROMP BACKWARDS OVER OTHER DATA IN YOUR CALLING PROGRAM.
<FORMAT IS A STRING OF SPECIAL CHARACTERS THAT DETERMINE
HOW THE OUPUT STRING WILL LOOK.
^SEE THE DESCRIPTION BELOW FOR DETAILS ON ALL THE SPECIAL
CHARACTERS ALLOWED IN FORMATS.
^THE <FLEN ARGUMENT IS OPTIONAL IF THE <FORMAT STRING IS TERMINATED BY A <NUL,
AND A <NUL IN THE FORMAT STRING WILL OVERRIDE ANY VALUE IN THE <FLEN ARGUMENT
IF THE <NUL IS FOUND FIRST.
^HOWEVER, IF THE <FLEN ARGUMENT IS MISSING, ONLY THE FIRST <MAXLEN
CHARACTERS ARE SEARCHED WHEN LOOKING FOR A <NUL.  (^SEE THE <SETMAX
ROUTINE FOR INFORMATION ABOUT <MAXLEN).
<OUTM ACTUALLY REQUIRES A <NUL AT THE END OF THE <FORMAT STRING, AND
WILL INSERT ONE IF YOU DO NOT.  ^THIS MEANS YOU MUST MAKE SURE TO
ALLOCATE AT LEAST ONE EXTRA BYTE IN YOUR FORMATS, EVEN WHEN YOU SEND
A <FLEN ARGUMENT TO SPECIFY THE END OF THE FORMAT.
^THE <ERROR ARGUMENT RETURNS A STATUS OF 1 IF THERE WERE NO PROBLEMS,
AND A NEGATIVE VALUE IF
THERE WAS NOT ENOUGH ROOM IN YOUR FORMAT TO PRINT ALL THE DIGITS
IN YOUR VALUE.
^IF <OUTM IS DECLARED INTEGER, IT CAN BE CALLED AS A FUNCTION, AND THE
RETURN VALUE WILL BE THE SAME AS THE <ERR ARGUMENT.
^THE <FORMAT ARGUMENT TO <OUTM CAN BE A QUOTED LITERAL, AS IN THE FOLLOWING
EXAMPLE:
.BREAK;^^CALL OUTM(VALUE,BUFFER,20,'-NNN,NNN,NN0.00')\\
.PARAGRAPH;^THE SPECIAL CHARACTERS ALLOWED IN THE <FORMAT STRING
ARE:
.SKIP
.INDENT -5;^A MINUS SIGN (-) WILL CAUSE A MINUS
SIGN TO BE PRINTED ONLY IF THE NUMBER WAS NEGATIVE.
.INDENT -5;^A PLUS SIGN (+) IN THE <FORMAT
STRING WILL CAUSE A PLUS SIGN TO BE PRINTED ONLY IF THE NUMBER IS POSITIVE.
^USING + AND - IN THE SAME FORMAT STRING WILL ALWAYS CAUSE ONE OR THE OTHER SIGN
TO PRINT (ZERO IS CONSIDERED POSITIVE).
.INDENT-5;^AN  "<N" CHARACTER IN THE FORMAT STRING WILL ALLOCATE A POSITION FOR ONE OF THE
NUMERALS OF THE NUMBER BEING CONVERTED.  ^LEADING ZEROS ON NUMBERS WILL BE REPLACED
BY SPACES IN THE POSITIONS THE <N CHARACTERS MARK.
.INDENT -5;^A ZERO (0) CHARACTER IN THE FORMAT ACTS LIKE AN "<N", EXCEPT
LEADING ZEROS IN THIS POSITION ARE NOT REPLACED WITH SPACES.
.INDENT -5; ^A COMMA (,) IN THE FORMAT STRING
WILL CAUSE A COMMA TO PRINT IN THE OUTPUT STRING IF IT COMES AFTER ANY SIGNIFICANT
DIGIT IN THE NUMBER.  ^COMMAS BEFORE THE FIRST SIGNIFICANT DIGIT ARE REPLACED WITH
SPACES.
.INDENT -5;^A DECIMAL POINT (.) WILL FORCE THE PLACEMENT OF THE DECIMAL.
^IF FEWER THAN <NPLACE "<N" OR "0" CHARACTERS APPEAR AFTER A DECIMAL POINT IN THE FORMAT,
THE LAST NUMERAL PRINTED WILL BE ROUNDED UP AS REQUIRED, AND OTHER DIGITS WILL NOT PRINT.
^IF MORE THAN <NPLACE "<N" OR "0" CHARACTERS OCCUR AFTER THE DECIMAL POINT, THEY WILL ALWAYS
PRINT AS SPACES OR  ZEROS RESPECTIVELY.
^IF YOU DO NOT ASK FOR A DECIMAL POINT IN YOUR FORMAT, NONE WILL BE BE
PRINTED.  ^THIS ALLOWS YOU TO SUBSTITUTE SPACES OR OTHER CHARACTERS BETWEEN
THE DOLLARS AND CENTS IN THE OUTPUT STRING. ^SEE THE EXAMPLE BELOW IN THE
DISCUSSION OF THE UNDERLINE CHARACTER.
.INDENT-5;^IF THE LETTER "<C" APPEARS IN THE FORMAT STRING, THEN THE TWO LETTERS
<CR WILL APPEAR IN THE OUTPUT STRING ONLY WHEN THE VALUE IS POSITIVE. 
.INDENT-5;^IF THE LETTER
"<D" APPEARS IN THE FORMAT, THEN THE LETTERS <DR WILL APPEAR IN THE OUTPUT STRING ONLY
WHEN THE VALUE IS NEGATIVE.  ^USING <C AND <D IN THE SAME FORMAT WILL ALWAYS CAUSE THE
APPROPRIATE CHARACTERS TO PRINT (A ZERO VALUE IS ASSUMED TO BE A <CR).
.INDENT -5;^WHEN ANGLE BRACKETS ("_<" AND ">") APPEAR IN THE FORMAT
STRING, THEY WILL APPEAR IN THE OUTPUT STRING ONLY WHEN THE VALUE IS
NEGATIVE.
.INDENT -5;^ANY OTHER CHARACTERS WHATSOEVER THAT APPEAR IN THE FORMAT
STRING WILL BE PASSED TO THE OUTPUT STRING IN THE ORDER THAT THEY ARE
ENCOUNTERED. ^FOR EXAMPLE, A TYPICAL CHARACTER YOU MAY WISH TO INSERT IN
THE FORMAT IS THE DOLLAR SIGN ("$").
.INDENT -5;^THE UNDERLINE (__) IS THE "ESCAPE" CHARACTER WHEN YOU WISH
TO PREVENT CHARACTERS FROM BEING TREATED AS FORMAT CONTROL CHARACTERS.
^FOR EXAMPLE, YOU MAY WISH TO INCLUDE THE STRING "<CENTS" IN THE FORMAT,
BUT THE <C AND THE <N CANNOT BE PRINTED.  ^INCLUDING AN UNDERLINE AFTER
EACH OF THESE CHARACTERS TELLS THE ROUTINE TO LEAVE THEM AS IS. ^THE CORRECT
WAY TO INCLUDE THE WORD CENTS IN TH OUTPUT WOULD BE: "<C__EN__TS".
^AN ALTERNATE SOLUTION IS TO USE LOWER CASE CHARACTERS FOR WORDS LIKE THESE
IN THE FORMAT.  ^LOWER CHASE CHARACTERS ARE ALWAYS PASSED EXACTLY AS THEY
ARE TO THE OUTPUT STRING.  ^AN EXAMPLE MIGHT BE:
"EXACTLY#^^NNN,NNN,NN0\\#AND#00#CENTS".
.PARAGRAPH;^THE RELATIVE POSITION OF THE SPECIAL CHARACTERS WILL DETERMINE THEIR PLACEMENT IN
THE OUTPUT STRING. ^THE CHARACTERS +, -, <CR, <DR, _< AND >, WHEN REQUESTED BEFORE THE NUMERALS, WILL
ALWAYS "FLOAT" DOWN UNTIL THEY PRINT JUST BEFORE THE MOST SIGNIFICANT DIGIT.
^THIS IS TRUE OF "RANDOM" CHARACTERS (LIKE $) IN THE FORMAT STRING ALSO.
^WHEN A SIGN CHARACTER IS REQUESTED AFTER THE NUMERALS, SPACES ARE RESERVED FOR THEM
WHETHER THEY PRINT OR NOT.  ^THIS ASSURES THAT COLUMNS OF NUMBERS WILL
ALWAYS ALIGN PROPERLY.
^IF TWO COMPATIBLE SIGN CHARACTERS ARE REQUESTED ON OPPOSITE SIDES OF THE
NUMBER, (FOR EXAMPLE: '<-NN0.00+', OR '<CNN0.00D'), THE SIGN CHARACTERS
WILL BE PRINTED ONLY ON THE RIGHT SIDE OF THE NUMBER.
.PARAGRAPH
^SOME EXAMPLES:  '<-$NNN.NN' OR "<$-NNN.NN' CAUSES THE MINUS
SIGN TO PRINT ON THE LEFT OR THE RIGHT SIDE OF THE $ RESPECTIVELY.  ^IN THE TWO
STRINGS: '<-NNNN,NN' AND '<NNNN.NN-', THE MINUS SIGN IS PRINTED ON THE LEFT OR
THE RIGHT SIDE OF THE NUMBER. ^AN EXAMPLE OF A COMPLEX FORMAT STRING MIGHT BE:
'<-$NNN,NNN,NN0.00C'.  ^THIS FORMAT CAN PRINT VALUES UP TO ONE BILLION DOLLARS
(MINUS ONE CENT), PRINTING A MINUS SIGN IF THE NUMBER IS NEGATIVE, THEN PRINTING
A DOLLAR SIGN FOLLOWED BY THE DIGITS IN THE NUMBER SEPARATED BY COMMAS EVERY 3 DIGITS.
^THE LAST THREE DIGITS ARE PRINTED EVEN WHEN  THE NUMBER IS ZERO OR LESS
THAN ONE DOLLAR, AND
FINALLY THE NUMBER IS FOLLOWED BY A <CR
SYMBOL IF IT IS POSITIVE.
.TEST PAGE 10;.SKIP;.INDENT -10;^^ADDM(RESULT,A,B[,ERR])\\
.BREAK;^THIS ROUTINE ADDS THE TWO MULTIPLE PRECISION NUMBERS, <A AND <B, STORING
THE SUM IN <RESULT.
.SKIP;.CENTER;^^PARAMETER RULES\\
.PARAGRAPH
^ALL MULTIPLE PRECISION PARAMETERS MUST BE VARIABLES OR ARRAYS LARGE ENOUGH TO
STORE A MULTIPLE PRECISION VALUE WHICH IS <NWRDS WORDS LONG.  <A AND <B SHOULD
HAVE BEEN PREVIOUSLY DEFINED BY ONE OF THE MULTIPLE PRECISION ROUTINES.
^ANY OF THESE ARGUMENTS CAN BE THE SAME <FORTRAN
VARIABLE, BECAUSE THE ARITHMETIC OPERATIONS ALL TAKE PLACE IN INTERNAL SCRATCH REGISTERS.
^THIS ALLOWS YOU TO USE THE ROUTINES TO PERFORM "RUNNING SUM" TYPE OPERATIONS. ^FOR
EXAMPLE: ^^CALL#ADDM(X,X,Y)\\, WHICH IS EQUIVALENT TO SAYING <X=X+Y IN A <REAL EXPRESSION.
.BREAK;^THE OPTIONAL <ERR ARGUMENT RETURNS THE STATUS OF THE OPERATION.
^THIS ARGUMENT IS A <FORTRAN <INTEGER VARIABLE, AND NOT A MULTIPLE PRECISION
VALUE.  ^A POSITIVE
VALUE MEANS SUCCESS, A NEGATIVE VALUE MEANS THAT OVERFLOW OR DIVIDE BY ZERO HAS
OCCURRED.
^ALL THE <MPP ROUTINES CAN BE CALLED AS FUNCTIONS IF THEY ARE DECLARED
<INTEGER IN THE CALLING PROGRAM.  ^WHEN USED IN THIS MANNER, THE FUNCTION
RETURN VALUE IS THE SAME AS THE <ERR ARGUMENT VALUE.
.TEST PAGE 10;.SKIP;.INDENT-10;^^SUBM(RESULT,A,B[,ERR])\\
.BREAK;^THIS ROUTINE SUBTRACTS THE VALUE OF <B FROM THE VALUE OF <A AND STORES THE
DIFFERENCE IN <RESULT.  ^THE RULES FOR PARAMETERS ARE THE SAME AS THE <ADDM ROUTINE.
.TEST PAGE 10;.SKIP;.INDENT-10;^^MULM(RESULT,A,B[,ERR])\\
.BREAK;^THS ROUTINE MULTIPLIES THE VALUE OF <A TIMES THE VALUE OF <B STORING THE 
PRODUCT IN <RESULT.  ^PARAMETER RULES ARE THE SAME AS FOR <ADDM.
^THIS OPERATION CAN RESULT IN EXTRA DIGITS PAST THE DECIMAL POINT, BUT THE
MULTIPLE PRECISION PACKAGE CAN ONLY STORE <NPLACE DIGITS.  ^WHEN THIS HAPPENS,
THE LAST LEGAL DIGIT IS ROUNDED UP AS REQUIRED AND THE EXTRA DIGITS ARE DISCARDED.
.TEST PAGE 10;.SKIP;.INDENT-10;^^DIVM(RESULT,A,B[,REM][,ERR])\\
.BREAK;^THIS ROUTINE DIVIDES THE VALUE OF <A BY THE VALUE OF <B, STORING THE
QUOTIENT IN <RESULT.
^PARAMETERS RULES ARE THE SAME AS THE <ADDM ROUTINE, EXCEPT FOR THE
INCLUSION OF A NEW OPTIONAL RETURN VALUE, <REM.
^IF THE <REM ARGUMENT IS INCLUDED, THE <RESULT IS LEFT AS IS, AND
 THE REMAINDER OF THE DIVISION IS RETURNED.
^IF THE <REM ARGUMENT IS MISSING, THE <RESULT IS ROUNDED UP APPROPRIATELY.
^THIS <REM ARGUMENT IS A MULTIPLE PRECISION VALUE, AND YOU MUST ALLOCATE
SPACE FOR IT ACCORDINGLY IN YOUR CALLING PROGRAM.
.TEST PAGE 10;.SKIP;.INDENT-10;^^CMPM(A,B[,VERDICT])\\
.BREAK;^THIS ROUTINE COMPARES TWO MULTIPLE PRECISION NUMBERS AND RETURNS
A VERDICT OF GREATER THAN, EQUALS, OR LESS THAN.
<VERDICT IS A <FORTRAN <INTEGER VARIABLE, AND NOT A <MPP VARIABLE.
^THE <VERDICT PARAMETER IS
OPTIONAL BECAUSE <CMPM CAN BE CALLED AS A FUNCTION IF DECLARED INTEGER IN THE
CALLING <FORTRAN PROGRAM.  ^VALUES RETURNED IN VERDICT ARE: +1 IF <A>B, 0 If
<A=<B, AND -1 IF <A_<<B.
.TEST PAGE 10;.SKIP;.INDENT-10;^^TSTM(A[,VERDICT])\\
.BREAK
^TO COMPARE A SINGLE MULTIPLE PRECISION VALUE AGAINST ZERO, YOU CAN USE THIS
ROUTINE.  ^LIKE <CMPM, <TSTM CAN BE CALLED AS AN INTEGER FUNCTION AND THE
VERDICT WILL BE RETURNED AS THE FUNCTION VALUE.  ^ALSO LIKE <CMPM THE
VALUES RETURNED IN <VERDICT WILL BE: +1 IF <A>0, 0 IF <A=0, AND -1
IF <A_<0.
.TEST PAGE 10;.SKIP;.INDENT-10;^^NEGM(RESULT,A)\\
.BREAK
^THIS ROUTINE NEGATES THE VALUE OF <A AND STORES THE RESULT IN <RESULT.
^LIKE OTHER <MPP PARAMETERS, <BOTH <A AND <RESULT CAN BE THE SAME <FORTRAN
VARIABLE TO ALLOW NEGATING A NUMBER IN PLACE.