Dme at 19:04, 3 March 2019

2019-03-03T19:04:18Z

← Older revision		Revision as of 19:04, 3 March 2019
Line 16:		Line 16:
	However, this M204wiki page only serves as documentation of float		However, this M204wiki page only serves as documentation of float
	handling in <var class="product">Fast/Unload</var>.		handling in <var class="product">Fast/Unload</var>.

			For detailed information about SOUL vs. FUEL numeric differences, see:
			<ul>
			<li>[[Fast/Unload Extraction Language (FUEL)#soulVsFuelDataComparisons\|Contrasting SOUL and FUEL comparisons]]
			<li>[[Floating_point_conversion,_rounding,_and_precision_rules\|SOUL float conversion/rounding/precision rules]]
			</ul>

	The similarity of results with <var class="product">SOUL</var> has been extensively		The similarity of results with <var class="product">SOUL</var> has been extensively
	tested, but there may be edge cases in which <var class="product">Fast/Unload</var> and		tested, but there may be edge cases in which <var class="product">Fast/Unload</var> and

Dme at 19:30, 12 October 2018

2018-10-12T19:30:14Z

← Older revision		Revision as of 19:30, 12 October 2018
Line 237:		Line 237:
	</table>		</table>

	<~~div~~ id="farith"></~~div~~>		==<b id="farith"></b> Arithmetic expressions==
	==Arithmetic expressions==
	~~<!--Caution: <div> above-->~~

	The result of an arithmetic expression is always an 8-byte		The result of an arithmetic expression is always an 8-byte

JAL: add template

2015-03-11T19:47:54Z

add template

← Older revision		Revision as of 19:47, 11 March 2015
Line 298:		Line 298:

	==See also==		==See also==
	[[Fast/Unload ~~overview#WIKFUN$$topics\|Fast/Unload topics]]~~		{{Template:Fast/Unload topic list}}

JAL at 17:49, 23 February 2015

2015-02-23T17:49:17Z

← Older revision		Revision as of 17:49, 23 February 2015
Line 1:		Line 1:
	<!-- Page name: Fast/Unload floating point arithmetic and numeric conversion-->		<!-- Page name: Fast/Unload floating point arithmetic and numeric conversion-->

	Arithmetic operations in <var class="product">Fast/Unload</var> (that is, arithmetic		Arithmetic operations in <var class="product">Fast/Unload</var> (that is, arithmetic
	calculations, as defined in [[Fast/Unload Extraction Language (FUEL)#expr\|Expressions]]) are performed using the IBM/360		calculations, as defined in [[Fast/Unload Extraction Language (FUEL)#expr\|Expressions]]) are performed using the IBM/360

JAL: more conversion cleanup

2015-02-23T17:36:56Z

more conversion cleanup

Show changes

DmeWiccan: Automatically generated page update

2015-01-15T19:40:21Z

Automatically generated page update

← Older revision		Revision as of 19:40, 15 January 2015
Line 2:		Line 2:
	<p></p>		<p></p>
	Arithmetic operations in <var class="product">Fast/Unload</var> (that is, arithmetic		Arithmetic operations in <var class="product">Fast/Unload</var> (that is, arithmetic
	calculations, as defined in [[#expr\|Expressions]]) are performed using the IBM/360		calculations, as defined in [[Fast/Unload Extraction Language (FUEL)#expr\|Expressions]]) are performed using the IBM/360
	floating point arithmetic instructions.		floating point arithmetic instructions.
	In addition,		In addition,
Line 110:		Line 110:
	and [[#flench\|Length-converting PUT statements]]);		and [[#flench\|Length-converting PUT statements]]);
	<li>when the argument of the #FLOAT8 function is a 4-byte floating point value		<li>when the argument of the #FLOAT8 function is a 4-byte floating point value
	(described in [[#flt8\|#FLOAT8: Get 8-byte float, padding 4-byte input with 0]]);		(described in [[Fast/Unload standard functions#flt8\|#FLOAT8: Get 8-byte float, padding 4-byte input with 0]]);
	</ul>		</ul>
	whenever FUEL requires the <b><i>value</i></b> of a <b>floating point</b> value,		whenever FUEL requires the <b><i>value</i></b> of a <b>floating point</b> value,

DmeWiccan: Automatically generated page update

2015-01-14T00:49:25Z

Automatically generated page update

New page

<p></p>
Arithmetic operations in <var class="product">Fast/Unload</var> (that is, arithmetic
calculations, as defined in [[#expr|Expressions]]) are performed using the IBM/360
floating point arithmetic instructions.
In addition,
many operations in <var class="product">Fast/Unload</var> involve converting to or from a numeric value, which
uses a (power of 2) floating point representation.
<p></p>
Many values that are exactly expressed in base 10 (that is, the usual decimal
number system) are not represented exactly as power of 2 floating point values.
Also, the floating point arithmetic instructions will, in many cases, produce results
that are only approximately equal to the given operation and operands.
<p></p>
To satisfy
the requirements of manipulating these numeric values using the
"hexadecimal" floating
point instructions, certain approaches have been adopted in <var class="product">Model 204</var> User Language.
In order to produce results in <var class="product">Fast/Unload</var> that are identical to the results obtained in
User Language, these same approaches have been adopted in <var class="product">Fast/Unload</var>.
However, this wiki page only serves as documentation of float
handling in <var class="product">Fast/Unload</var>.
The similarity of results with <var class="product">SOUL</var> has been extensively
tested, but there may be edge cases in which <var class="product">Fast/Unload</var> and
<var class="product">SOUL</var> differ.
<p></p>
Note also that <var class="product">Fast/Unload</var> contains no exact provision for the floating point
value handling provided by the <code>Image</code> feature in
<var class="product">SOUL</var>.
Information in this wiki page must
not be extrapolated to the operation with Images.
<blockquote class="note"><b>Note:</b> The contents of this wiki page are refreshed as of <var class="product">Fast/Unload</var> 4.3.
It is highly recommended that you use at least <var class="product">Fast/Unload</var> version 4.3 if
your application involves calculations sensitive to the operation of
floating point handling.
</blockquote>
==Overview==
<p></p>
The IBM "hexadecimal" floating point instructions use an exponent based
on a power of sixteen.
If the value being represented contains a fractional part, or if it is beyond
the range of integers that can be exactly represented, then the floating point
representation of a value may be only an approximation of the value.
For example, the value "one-tenth" is represented in base 16 as the
infinite hexadecimal series .1AAAAAAA...
These approximations can lead to surprising results, especially when dealing
with <b>decimal</b> fractions that one commonly considers as having an
exact representation, for example, the base 10 number .1 for the value one-tenth.
<p></p>
To address this problem, the approach to floating point manipulation
in <var class="product">Fast/Unload</var> is based on the following:
<table>
<tr><th>Decimal external inputs and outputs</th><td>For external numeric inputs and outputs of <var class="product">Model 204</var> applications, the original source (for example, data entry fields) and final destination (for example, printed values) is expressed in decimal (base 10) notation.</td></tr>
<tr><th>Arithmetic results mirror decimal operations</th><td>When two numeric values are operated upon, in particular with addition and subtraction, the resulting value, when expressed in decimal, is as close as practical to the value that would occur if the operation were performed in decimal.</td></tr>
</table>
<p></p>
The principles described above are accomplished using the following
algorithms:
<table>
<tr><th>15-digit decimal significance</th><td>An 8-byte floating point value, in the IBM 360 architecture, contains 56 bits of significance for the fraction part. 56 bits can represent the numbers from 0 to approximately 7.2E16 (7.2 times 10 to the 16th power). Therefore, the maximum significance, in decimal, of an 8-byte FLOAT is 16 (decimal) digits. User Language uses a more conservative limit to significance, and uses 15 decimal digit significance with numeric operations.</td></tr>
<tr><th>Float value preserved if target has same length</th><td>A float value is exactly preserved if copied to a float target that has the same length. [[#flench|Length-converting PUT statements]] specifies the rules for copying a float value to a float target that has a different length.</td></tr>
<tr><th>Float length 4 conversions differ from length 8 or 16</th><td> When a float value of length 4 is used in any context other than copying, it is converted as described in [[#fval|Using a float value, with decimal digit precision]]. When a float value of length 8 or 16 is used in any context other than copying or arithmetic, it is converted as described in [[#fval|Using a float value, with decimal digit precision]].</td></tr>
<tr><th>FLoat length 8 or 16 values in arithmetic expressions</th><td>Float values of length 8 or 16 use the high order 8 bytes, without any modification, when they are used as entities in an arithmetic expression.</td></tr>
</table>
<p></p>
The purpose of the above rules is to achieve (approximately) the same
results for float numeric operations as would be given by
operations with decimal numbers.

<div id="fbg"></div>
===Primitive operations===


<p></p>
As a brief background, note the following:
<ul>
<li>
Floating point values use the IBM
hexadecimal floating point representation, which is a one-bit
sign, a 7-bit base 16 exponent, and a binary fraction whose
length is either 3 bytes (FLOAT LEN 4), 7 bytes (FLOAT LEN 8),
or 14 bytes (FLOAT LEN 16).
<li>
In a <b>normalized</b> floating point number, the high-order
nibble (the first four bits) of the fraction has a non-zero value.
<li>
The normalized 8-byte add (AD/R) and subtract (SD/R) instructions are
used for addition and subtraction in arithmetic expressions;
the 8-byte multiply (MD/R) and divide (MD/R) instructions are used
for multiplication and division.
These instructions produce normalized results (except at the limits of
normalized values) and do not round.
<p></p>
See also [[#farith|Arithmetic expressions]], which explains that after every
float addition or subtraction, there is a decimal rounding step to
preserve the proper number of significant digits.
</ul>

<div id="fval"></div>
===Using a float value, with decimal digit precision===


<p></p>
<b>Except</b> for the following cases:
<ul>
<li>when an 8- or 16-byte floating point value is the input to an
arithmetic expression (described in [[#farith|Arithmetic expressions]]);
<li>when a floating point value is the input to a PUT statement or is the
right side of an assignment statement (described in [[#fltasg|Assignments and length-preserved PUT statements]]
and [[#flench|Length-converting PUT statements]]);
<li>when the argument of the #FLOAT8 function is a 4-byte floating point value
(described in [[#flt8|#FLOAT8: Get 8-byte float, padding 4-byte input with 0]]);
</ul>
whenever FUEL requires the <b><i>value</i></b> of a <b>floating point</b> value,
the value obtained is approximately
the closest 8-byte floating point representation of a value, which depends
on the length of the "input" floating point value:
<table>
<tr><th>LEN 4</th><td>The result is the floating point value approximately closest to the <b>decimal</b> number with <b>6</b> significant digits closest to the LEN 4 float input. For example, if a FLOAT LEN 4 field contains the following value, shown in hexadecimal:
<p class="code"><nowiki>41100004
</nowiki></p> which in decimal is:
<p class="code"><nowiki>1.000003814697265625
</nowiki></p> then the nearest <b>6</b>-digit decimal value is:
<p class="code"><nowiki>1.00000
</nowiki></p> so that value is used, represented exactly by the 8-byte float:
<p class="code"><nowiki>4110000000000000
</nowiki></p></td></tr>
<tr><th>LEN 8 or 16</th><td>The result is the floating point value approximately closest to the <b>decimal</b> number with <b>15</b> significant digits closest to the first 8 bytes of the float input. For example, if a FLOAT LEN 8 field contains the following value, shown in hexadecimal:
<p class="code"><nowiki>4110000400000000
</nowiki></p> which in decimal is:
<p class="code"><nowiki>1.000003814697265625
</nowiki></p> then the nearest <b>15</b>-digit decimal value is:
<p class="code"><nowiki>1.00000381469727
</nowiki></p> so that value is used, represented by the 8-byte float that is approximately the nearest:
<p class="code"><nowiki>4110000400000013
</nowiki></p>
<blockquote class="note"><b>Note:</b> The low order 8 bytes of a 16-byte float are ignored. </blockquote></td></tr>
</table>
===Obtaining numeric values from non-floats===
<p></p>
<p></p>
When a numeric value is required in FUEL from a <b>string or constant
that is a decimal number</b>, the value obtained is approximately the
closest 8-byte floating point representation of the decimal value to 15
significant digits.
For example, after this FUEL fragment:
<p class="code"><nowiki>%T = '1.000003814697265625' /* Note: string value
%T = '1.000003814697265625' /* Note: string value
CHANGE MYFIELD = %T /* So field set to string value
%Z = MYFIELD * 1 /* %Z has float value
%Y = %T * 1 /* %Y has (same) float value
PUT MYFIELD /* Line 1: From string, 19 digits
OUTPUT
PUT %Y /* Line 2: From float, 15 digits
OUTPUT
IF %T EQ '1.000003814697265625' THEN /* No conversion here
PUT 'String comparison 1 EQ, of course'
OUTPUT
END IF
IF %T NE %X THEN /* Here converting %X->string: 15 digits
PUT 'String comparison 2 should be NE'
OUTPUT
END IF
IF %T EQ +%X THEN /* Here converting %T->float
PUT 'Float comparison should be EQ'
OUTPUT
END IF
</nowiki></p>
<p></p>
<p></p>
The output file will contain:
<p class="code"><nowiki>1.000003814697265625
1.00000381469727
String comparison 1 EQ, of course
String comparison 2 should be NE
Float comparison should be EQ
</nowiki></p>
And %X, %Y, and %Z will each contain the 8-byte floating
point number <code>X'4100000400000013'</code>.

<div id="fltasg"></div>
==Assignments and length-preserved PUT statements==


<table>
<tr><th>Assignments between fields and %variables</th><td> Whenever a FLOAT field occurrence is assigned to a %variable, the entire 4, 8, or 16 bytes are copied exactly to the %variable. Whenever a %variable that contains a floating point value is assigned (via the CHANGE or ADD[C] statement) as the value of a field occurrence, the %variable's entire 4, 8, or 16 bytes are copied exactly to the field occurrence.</td></tr>
<tr><th>Length-preserved PUT AS FLOAT</th><td> Whenever a field occurrence or %variable that contains a floating point value is used in a PUT AS FLOAT statement, and the FLOAT format specifies a length that is the same as that of the occurrence or %variable, the entire 4, 8, or 16 bytes are copied exactly to the ouput file. <p></p> For example, if field FLT4 contains a 4-byte float value that in hexadecimal is X'41000004', then the following FUEL fragment:
<p class="code"><nowiki>PUT FLT4 AS FLOAT(4)
OUTPUT
%X = FLT4
PUT %X AS FLOAT(4)
OUTPUT
</nowiki></p> places two lines to the output file, each containing the 4 bytes that are hexadecimal <code>X'41000004'</code>.</td></tr>
</table>

<div id="flench"></div>
==Length-converting PUT statements==


<p></p>
Other than obtaining the value of a float (for example, as part of an
IF statement comparison or as an argument to a #function),
which is explained in [[#fval|Using a float value, with decimal digit precision]], the
only context in FUEL in which a float value is transformed to a float
value with a different length is in the PUT statement with a FLOAT
format whose format length differs from the length of the float "input."
The cases are shown below:
<table>
<tr><th>AS FLOAT(4)</th><td>The first (and only, if the input is length 8) 8 bytes of the input are copied to a 4-byte float using the LEDR instruction, which produces the first 4 bytes of the input 8 bytes, or those 4 bytes plus 1 (times the sign of the value) if the high order bit of the second 4 bytes is 1. <p></p> Note that there is no normalization of the input value prior to rounding; thus the low-order 31 fraction bits of an 8-byte float are ignored, and the low-order 31 + 56 fraction bits of a 16-byte float are ignored.</td></tr>
<tr><th>LEN 16 -> 8</th><td> The AS FLOAT(8) clause for a 16-byte float input is obtained by taking the first 8 bytes of the 16-byte float value. <p></p> Note that there is no rounding, as there is when converting from 8-byte to 4-byte floats, and there is no normalization; thus the low order 56 fraction bits of the 16-byte float are ignored.</td></tr>
<tr><th>LEN 4 -> 8/16</th><td> When a 4-byte float value is the input to AS FLOAT(8) or AS FLOAT(16), the 4-byte input float value is converted to an 8-byte value that is approximately nearest the input value expressed as the nearest 6-significant-digit decimal number, as described in the <b>LEN 4</b> case in [[#fval|Using a float value, with decimal digit precision]]. This is the result when the PUT format length is 8; an additional 8 bytes of zeroes are added when it is 16.</td></tr>
<tr><th>LEN 8 -> 16</th><td> The AS FLOAT(16) clause for a 8-byte float input is obtained by appending 8 additional bytes of zeroes to the unchanged 8-byte value.</td></tr>
</table>

<div id="farith"></div>
==Arithmetic expressions==


<p></p>
The result of an arithmetic expression is always an 8-byte
float; these are produced as described in [[#fbg|Primitive operations]].
Also, after every addition or subtraction in the expression,
a step is performed to ensure that the correct significance is
retained as the result of that operation.
This significance is based on the magnitude of the inputs and
the result of the addition or subtraction.
<p></p>
<p></p>
For example, after performing the SDR to operate on the following two values:
<p class="code"><nowiki>%X = 123456789.1234 - 123456789
/* = X'4775BCD151F97247'
/* - X'4775BCD150000000'
/* = X'401F972470000000'
/* = .123399998992682 (rounded to 15 digits)
</nowiki></p>
<p></p>
<p></p>
<var class="product">Fast/Unload</var> examines the magnitude of the absolute values of the result and
addends, and it determines that 4 significant digits should be retained, so
it rounds the result to 4 significant digits:
<p class="code"><nowiki> /* .1234 (result rounded to 4 digits)
/* = X'401F972474538EF3' (float nearest to .1234)
</nowiki></p>
==Example==
<p></p>
Following is one example of the behavior of <var class="product">Fast/Unload</var>.
Versions prior to 4.0 obtain the different result shown below.
<p></p>
<p class="code"><nowiki>%T2 = 1
FOR J FROM 1 TO 7 /* Get 1E-7
%T2 = %T2 / 10
END FOR
PUT %T2
OUTPUT
FOR J FROM 1 TO 5 /* Get .01
%T2 = %T2 * 10
END FOR
PUT %T2
OUTPUT
%T = 0
FOR J FROM 1 TO 10 /* Get .1
%T = %T + %T2
END FOR
PUT %T
OUTPUT
</nowiki></p>
<p></p>
Results (starting with version 4.0):
<p class="code"><nowiki>0.0000001
0.00999999999999999
0.1
</nowiki></p>
Results (prior to version 4.0):
<p class="code"><nowiki>0.0000001
0.00999999999999999
0.0999999999999999
</nowiki></p>
==See also==
[[Fast/Unload overview#WIKFUN$$topics|Fast/Unload topics]]

Fast/Unload floating point arithmetic and numeric conversion - Revision history

Dme at 19:04, 3 March 2019

Dme at 19:30, 12 October 2018

JAL: add template

JAL at 17:49, 23 February 2015

JAL: more conversion cleanup

DmeWiccan: Automatically generated page update

DmeWiccan: Automatically generated page update