"Everything you've always wanted to know about VB Arrays of Strings*
   (*but were afraid to ask)"
Lorri Menard

As promised in the last newsletter, here is an article on "How to pass arrays of strings from Visual Basic to Visual Fortran". Actually, it should be called "How DVF can receive arrays of strings from VB", because Visual Basic doesn't need to do anything special to pass the arrays to Fortran.

The structure that VB uses to pass arrays of strings is called a "Safe Array". These are often used in COM interfaces, and contain information about the dimensions and bounds of the arrays within them.

Appended is an example Fortran subroutine that receives a one-dimensional SafeArray of strings from Visual Basic and writes the contents of each string out to a data file. It then modifies the strings, within the SafeArray structure, and passes them back to VB. I've noted the areas of interest with the keystring "!**", and included a long and involved explanation of why you need to do it that way. (Of course, I reserve the right to claim "Because I said so!")

The call from the Basic routine is as simple as this:

Dim MyArray(2) as String
MyArray(0) = "First element"
MyArray(1) = "Second element"
MyArray(2) = "Third element"
Call ForCall(MyArray)

Now, let's get into the Fortran program.

! ARRAYS.F90
! This subroutine takes as input an array of strings from Visual Basic,
!  and writes each string out to a datafile.
! It also writes various pieces of information about the array to that
!  file, for illustrative purposes.
! 
subroutine ForCall (VBArray)
	!dec$ attributes alias : "ForCall" :: ForCall
	!dec$ attributes dllexport :: ForCall
	!dec$ attributes stdcall :: ForCall
!** Declare the array of strings (SafeArray) as being passed by REFERENCE.
!**  This must be explicit.
	!dec$ attributes reference :: VBArray
!** The following module declares the interfaces to SafeArrayxxx
	use dfcom

	implicit none

!** Declare the SafeArray as a pointer.  Use a generic 
!**   integer as something to point to, because the POINTER statement
!**   requires it.  
!** When this is declared as a pointer it will automatically expand
!**  to fit the size of a pointer for the particular platform.  Today
!**  that is 32 bits - in the future, that may expand.

	pointer (VBArray,SADummy)  !Pointer to a SafeArray structure
	integer SAdummy

!** What is returned by SafeArrayGetElem is a BSTR.  The structure of
!**  a BSTR is such that the length of the BSTR is returned in the word
!**  preceding the pointer, and the string itself is pointed to by
!**  the pointer.  When using COM, BSTRs are coded in Unicode.  Through
!**  experimentation with Visual Basic V5.0 I've found that it passes
!**  BSTRs coded in 8-bit ASCII.  
!** Please note: This may not be true with future releases of VB!
!**  The good news is that it allows us to take some shortcuts for now.
!** 
!**  Set up the appropriate structures.  Declare a character string
!**  that is "long enough".  It doesn't actually take up any space
!**  in your program; it is used as a template to describe the memory
!**  pointed to by the pointer StringPtr

	character*2000 mystring
	pointer (StringPtr, mystring)

	integer i, result, lbound, ubound, length

	! Create the data file
	open (2, file="test.out", status="unknown")

	write (2, *) "Det
ails of the array passed by VB"
	! Get the lower array bound
	result = SafeArrayGetLBound(VBArray, 1, lbound)
	write (2, *) "GetLBound gives ", lbound
	! Get the upper array bound
	result = SafeArrayGetUBound(VBArray, 1, ubound )
	write (2, *) "GetUBound gives ", ubound

!** In this next loop, get each element of the array.  This returns a
!**  pointer to a copy of the string, which can then be referenced through
!**  mystring.  The length of the string is retrieved by the routine
!**  SysStringByteLen.
!** This copy must be freed when we're done with it.

	write (2, *) "Strings from the array:"
	do i = lbound, ubound
		result = SafeArrayGetElement(VBArray, i, LOC(StringPtr))
		length = SysStringByteLen(StringPtr)
		write (2, *) mystring(1:length)
		call SysFreeString(StringPtr)
	end do

	!Done with the data file.
	close (2)

!** This next loop writes a string back into each element of the array.
!**  Through experimentation I've discovered that you MUST write back as
!**  many characters as were there before: no more, no less.  This loop
!**  gets the length of the element, and writes back that many characters.
!** Once again, the SafeArrayGetElement makes a copy, which must be
!**  freed.  
!** SafeArrayPutElement also makes a copy, which is then passed back
!**  to Visual Basic.  Unfortunately, the memory occupied by the original
!**  strings passed in is still allocated, and no longer pointed to.

	!Let's try writing back into VB's array
	do i = lbound, ubound
		result = SafeArrayGetElement(VBArray, i, LOC(StringPtr))
		length = SysStringByteLen(StringPtr)
		mystring(1:length) = "Element#" // char(i+1+48)
		mystring(length+1:length+1) = char(0)
		result = SafeArrayPutElement(VBArray, i, LOC(mystring))
		call SysFreeString(StringPtr)
	end do

	return
	end

"Ask Dr. Fortran"
Steve Lionel

Dear Dr. Fortran,

I know this program who seems to be OK, but he is a little different from all the other programs. (Just between you and me, he is a legacy program. Don't let that get out. It would not be politically correct.)

He started out life written for the IBM 1130 Disk Monitor System with 8k of core storage. He was written in 1130 FORTRAN. The original documentation gives direction as to which switches on the computer must be flipped to invoke certain options. But he is still alive and works well. We still add things to him. He lives on PCs now.

We really don't view him as belonging to us. His original programmers have retired and some have died. So in that respect he is doing better than his creators. We are like park rangers taking care of some national treasure that is to be passed on to our successors.

But lets give this a go. I need some help understanding what really goes on in this guys head. There are many cases of the following coding:

     
        subroutine xyz(n,array)
        integer n
        real array(1)      <-- Note the size is only 1
           . . .           <-- code in here loops from 1 to n.
        return
        end

My questions are:

1. Why does this work? It seems an out of bounds exception should be generated for array since its size is only 1.
2. In the main program the arrays are explicit shape. What type is array in subroutine xyz?
3. Is array(1) standard FORTRAN, or is this something that most compilers just allow?

Sincerely,

Robert Magliola
De Leuw, Cather and Co.

Dear Mr. Magliola,

When this charming program was written, in the days of keypunches and storage drums, FORTRAN IV (FORTRAN-66) was the current standard. While FORTRAN IV did have the "adjustable array" feature, (which could have been used in the above example by using "array(n)" instead of "array(1)"), it did not have the "assumed-size array" feature (where the rightmost upper bound is specified as "*") that was to be introduced in FORTRAN 77. Therefore, programmers who wanted to write subroutines which would accept an array of unknown total size would use a last dimension of 1. This worked because the last upper bound is not needed to calculate the position of an element in a Fortran array, and compilers of the time didn't have array bounds checking (or if they did it could be disabled).

Now fast-forward to 1978 when the FORTRAN 77 standard was adopted. It included a new "assumed-size" array feature (which had already shown up as an extension in many vendors' compilers). So now there was a standard-conforming way to say "I don't know what the upper bound is", yet there were still thousands of existing programs that used the old (1) convention and more compilers supported bounds-checking, even at compile-time (VAX FORTRAN did this, for example.) These old programs would suddenly start getting errors, which was not desirable - the Fortran tradition is provide as much upward compatibility as possible. What to do?

The solution was to have compilers treat a last upper bound of 1 as a special case that was equivalent to *, disabling bounds checking (which answers your first question). The a rray in the above example has a single dimension with lower bound 1 and an implicit upper bound of the total number of elements in the array that was passed, though most compilers don't pass that information and just treat the upper bound as infinite (questions two and three.) It is valid to have a multi-dimension assumed-size array, but only the rightmost (last) dimension can have an upper bound of * (or 1 treated as *). If you have a multi-dimension array with upper bounds other than the last of 1, then 1 is what you get.

I hope you have enjoyed this trip back into the history of the Fortran language.

Ask Dr. Fortran
Hey! Who are you calling "obsolescent"?
Steve Lionel, DVF Development Team

Dr. Fortran didn't receive any appropriate questions for his column this time, so he's going to take on a topic that is sure to raise a ruckus each time it is brought up in the comp.lang.fortran newsgroup: Obsolescent and Deleted Features.

Fortran (or FORTRAN) has had a long history of general upward compatibility - Fortran 77 included almost all of Fortran 66, and Fortran 90 included all of Fortran 77. But Fortran 90 formally introduced the concept of "language evolution" with the goal of removing from the language certain features that had more modern counterparts in the new language.

The Fortran 90 standard added two lists of features, "Deleted" and "Obsolescent". The "Deleted" list, features no longer in the language, was empty in Fortran 90. The "Obsolescent" list contained nine features of Fortran 77 which, to quote the standard, "are redundant and for which better methods are available in Fortran 77." Furthermore, the F90 standard said:

If the use of these features has become insignificant in Fortran programs, it is recommended that future Fortran standards committees consider deleting them from the next revision.

It is recommended that the next Fortran standards committee consider for deletion only those language features that appear in the list of obsolescent features.

It is recommended that processors supporting the Fortran language continue to support these features as long as they continue to be widely used in Fortran programs.

Proponents of "cleaning up" the language argued that it would make compiler implementors' jobs easier. The compiler vendors disagreed; most said that they would not remove support for any features since they knew that users continue to compile old programs. Furthermore, deleting a feature from the language means that there is no official description of how that feature, if still supported, interacts with other language features. (The Fortran 77 standard included an appendix describing how Hollerith constants, a FORTRAN IV feature not included in Fortran 77, should work if a compiler chose to support them.) For the record, DIGITAL will not remove support for any "deleted" language features from its Fortran compilers.

In Fortran 90, the list of "obsolescent" features was as follows:

1. Arithmetic IF
2. Real and double precision DO control variables and DO loop control expressions
3. Shared DO termination and termination on a statement other than END DO or CONTINUE statement.
4. Branching to an END IF statement from outside its IF block
5. Alternate return
6. PAUSE statement
7. ASSIGN statement and assigned GO TO statements
8. Assigned FORMAT specifiers
9. cH edit descriptor

Descriptions of obsolescent features in the standard appeared in a small font and compilers were to provide the ability to issue diagnostics for the use of obsolete features.

Now we come to Fortran 95. Keep in mind that the Fortran 90 standard did not say that the next standard HAD to delete any of the previously-designated "obsolescent" features, but that's exactly what the standards committee did. Six of the nine "obsolescent" features (numbers 2, 4, 6, 7, 8 and 9 ) above were "deleted". Poof! Gone! And guess what - that meant that a valid Fortran 77 program was no longer a valid Fortran 95 program! But never fear: DVF (and indeed most vendors' compilers) will continue to support the deleted features (with optional diagnostics informing you of the fact, of course.)

The Fortran 95 list of obsolescent features includes the remaining items of the above list from Fortran 90 (1, 3 and 5), as well as several new additions. Are you sitting down? Here's the new list:

1. Arithmetic IF
2. Shared DO termination and termination on a statement other than END DO or CONTINUE
3. Alternate return
4. Computed GO TO statement (use CASE)
5. Statement functions (use CONTAINed procedures)
6. DATA statements amongst executable statements (betcha didn't know they could go there!)
7. Assumed length character functions (this means CHARACTER*(*) FUNCTIONs)
8. Fixed form source (!!!!)
9. CHARACTER* form of CHARACTER declaration (use CHARACTER([LEN=]))

Needless to say, the inclusion of fixed-form source on this list has raised a LOT of eyebrows... Assumed-length CHARACTER functions (and the CHARACTER* form of declaration) are deemed to be an "irregularity" in the language, which they are, and there are alternatives available, but Dr. Fortran doesn't see these disappearing from users' code anytime soon.

So does this mean that some of these features will be deleted in the next standard, currently called "Fortran 2000"? [Fortran 2003 - ed.] At present, the answer is "no". The standards committee has agreed to NOT move any features from the "obsolescent" list to the "deleted" list for F2K, and furthermore, is not proposing any additions to the "obsolescent" list. So it would appear that, for now, anyway, the "concept of language evolution" excludes extinction, and that should make Fortran programmers around the world breathe easier.

Dr. Fortran and "The Dog That Did Not Bark"

By Steve Lionel

In past issues of the newsletter, Dr. Fortran has discussed an assortment of things, sometimes obscure, that the Fortran standard says.  In this issue, he's going to take a page from Sherlock Holmes and talk about things that the standard doesn't say, and how they can bite you as well.

Let's start with a simple observation that the standard describes a "standard-conforming program".  That is, it establishes the rules to which a program must conform in order to produce results as specified by the standard.  If your program is not standard-conforming, then all bets are off - the processor (compiler and run-time environment) can do anything (a common example used in comp.lang.fortran is "Start World War III", though the Doctor is not aware of any implementations which would do this - he would consider this a "quality of implementation issue").

You've probably written many non-conforming programs without realizing it. Got INTEGER*4 in your programs?  Non-standard.  Use LOGICAL variables in arithmetic expressions (or use logical operators such as .AND. on integers)?  Non-standard.  What these do is implementation-dependent.  If a compiler supports these and similar uses, it does so as extensions to the standard and is generally required to have the ability to detect the non-conformance at compile-time.  If your program uses such extensions, it is non-portable and may execute differently on different platforms or with different compilers.

However, there is another class of non-conformity that, in general, can't be detected at compile time and which can cause big headaches for programmers who make unwarranted assumptions.  Let's start with one of the Doctor's favorites - order of evaluation of LOGICAL expressions.

Many programmers write something like this:

IF ((I .NE. 0) .AND. (ARRAY(I) .NE. -1) THEN

and expect that if I is zero, then the reference to ARRAY(I) won't happen. The program may work on one platform, but get array bounds errors when ported to another.  However, the standard allows the operands of a logical operator to be evaluated in any order, and at any level of completeness, as long as the result is algebraically correct.  For logical expressions, Fortran does NOT have strict left-to-right ordering nor does it have short-circuit evaluation.  The standard-conforming way of writing this is:

IF (I .NE. 0) THEN
  IF (ARRAY(I) .NE. -1) THEN

Here's another place where the standard's silence can trap the unwary.  What do you see when you execute the following statement?

WRITE (*,'(F3.0)') 2.5

Many Fortran programmers expect "3.".  But try this in Visual Fortran, as well as in most other PC and UNIX workstation Fortran implementations and you'll get "2."!  Why?  Well, the Fortran standard says that the value is to be "rounded", but doesn't define what that means!  On systems which implement IEEE floating arithmetic, the IEEE default rounding rules are used and they specify that if the rounding digit is exactly half-way between two representable results, you round so that the low-order digit is even.  If you're a VAX user, you'll get "3." because VAX rounding uses the "5-9 rounds up" rule, and an OpenVMS Alpha user can see it either way, depending on whether or not IEEE float was selected!  The Doctor notes that the Fortran standards committee is working on a proposal for a future standard that would allow the programmer to specify the rounding method, but for now, the standard is silent and you get whatever the compiler writers think is right.

Pop quiz time - in a CHARACTER(LEN=n) declaration, what is the lowest value of n that a compiler is required to support, according to the standard?  Is it A) 1?  B) 11?  C) 255?  D) 1000?  The standard doesn't explicitly say, but one can make a good argument for one of these.  Go to the end of the column to see which one and why. The Doctor's point is that there are many compiler limits which the standard does not specify (including things such as the number of nested parentheses in an expression, number of actual arguments supported, etc.).  While most implementations have reasonable limits for such things, the Doctor has seen programs which exceed the limits of some implementations (for example, using hundreds of actual arguments) and become non-portable.  Just because one compiler supports something, that doesn't mean that all will!

There are many other things the standard doesn't say that programmers often take for granted.   For example, the standard doesn't even say that 1+1=2, or how accurate the SIN intrinsic must be.  An implementation which grossly violates reasonable expectations here would probably be a commercial failure, but it wouldn't be violating the standard!

In summary, writing standard-conforming and portable programs is not just a matter of throwi ng the "standards checking switch".  You also need to be aware of things the standard doesn't say and to make sure that your application doesn't depend on implementation-dependent features and behaviors.  The more platforms you port your application to, the more likely it is that you'll uncover such assumptions in your code.

Answer to Dr. Fortran's pop quiz: B) 11.  Why?  Because INQUIRE(FORM=) is supposed to assign the value "UNFORMATTED" to the specified variable (for unformatted connections) and that's 11 characters long, the longest of the set that INQUIRE returns.  No other language rule implies a longer minimum length.

Doctor Fortran in "To .EQV. or to .NEQV., that is the question", or "It's only LOGICAL"

By Steve Lionel
Visual Fortran Engineering

Most Fortran programmers are familiar with the LOGICAL data type, or at least they think they are.... An object of type LOGICAL has one of only two values, true or false. The language also defines two LOGICAL constant literals .TRUE. and .FALSE., which have the values true and false, respectively. It seems so simple, doesn't it? Yes... and no.

The trouble begins when you start wondering about just what the binary representation of a LOGICAL value is. An object of type "default LOGICAL kind" has the same size as a "default INTEGER kind", which in Visual Fortran (and most current Fortran implementations) is 32 bits. Since true/false could be encoded in just one bit, what do the other 31 do? Which bit pattern(s) represent true, and which represent false? And what bit patterns do .TRUE. and .FALSE. have? On all of these questions, the Fortran standard is silent. Indeed, according to the standard, you shouldn't be able to tell! How is this?

According to the standard, LOGICAL is its own distinct data type unrelated to and not interchangeable with INTEGER. There is a restricted set of operators available for the LOGICAL type which are not defined for any other type: .AND., .OR., .NOT., .EQV. and .NEQV.. Furthermore, there is no implicit conversion defined between LOGICAL and any other type.

"But wait," you cry! "I use .AND. and .OR. on integers all the time!" And so you do - but doing so is non-standard, though it's an almost universal extension in today's compilers, generally implemented as a "bitwise" operation on each bit of the value, and generally harmless. What you really should be using instead is the intrinsics designed for this purpose: IAND, IOR and IEOR.

Not so harmless is another common extension of allowing implicit conversion between LOGICAL and numeric types. This is where you can start getting into trouble due to implementation dependencies on the binary representation of LOGICAL values. For example, if you have:

 
INTEGER I,J,K
I = J .LT. K
                  

just what is the value of I? The answer is "it depends", and the result may even vary within a single implementation. Compaq Fortran traditionally (since the 1970s, at least) considers LOGICAL values with the least significant bit (LSB) one to be true, and values with the LSB zero to be false. All the other bits are ignored when testing for true/false. Many other Fortran compilers adopt the C definition of zero being false and non-zero being true. (Visual Fortran offers the /fpscomp:logicals switch to select the C method, since PowerStation used it as well.) Either way, the result of the expression J.LT.K can be any value which would test correctly as true/false. For example, the value 1 or 999 would both test as true using Compaq Fortran. Just in case you were wondering, Compaq Fortran uses a binary value of -1 for the literal .TRUE. and 0 for the literal .FALSE..

The real trouble with making assumptions about the internal value of LOGICALs is when you try testing them for "equality" against another logical expression. The way many Fortran programmers would naturally do this is as follows:

 IF (LOGVAL1 .EQ. LOGVAL2) ...

but the results of this can vary depending on the internal representation. The Fortran language defines two operators exclusively for use on logical values, .EQV. ("equivalent to") and .NEQV. ("not equivalent to"). So the above test would be properly written as:

 IF (LOGVAL1 .EQV. LOGVAL2) ...

In the Doctor's experience, not too many Fortran programmers use .EQV. and .NEQV. where they should, and get into trouble when porting software to other environments. Get in the habit of using the correct operators on LOGICAL values, and you'll avoid being snared by implementation differences.

However, there is one aspect of these operators you need to be aware of... A customer recently sent us a program that contained the following statement:

 DO WHILE (K .LE. 2 .AND. FOUND .EQV. .FALSE.)

The complaint was that the compiler "generated bad code." What the programmer didn't realize was that the operators .EQV. and .NEQV. have lower precedence than any of the other predefined logical operators. This meant that the statement was treated as if it had been:

 DO WHILE (((K .LE. 2) .AND. FOUND) .EQV. .FALSE.)

what was wanted instead was:

 DO WHILE ((K .LE. 2) .AND. (FOUND .EQV. .FALSE.))

The Doctor's prescription here is to always use parentheses! That way you'll be sure that the compiler interprets the expression the way you meant it to! (And you therefore don't have to learn the operator precedence table you can find in chapter 4 of the Compaq Fortran Language Reference Manual!)

Doctor Fortran and the Virtues of Omission

Steve Lionel - Compaq Fortran Engineering

As I was walking up the stair
I met a man who wasn't there.
He wasn't there again today.
I wish, I wish he'd stay away.
Hughes Mearns (1875-1965)

Up through Fortran 77, there was no Fortran standard-conforming way of calling a routine with a different number of arguments than it was declared as having. This didn't stop people from omitting arguments, but whether or not it worked was highly implementation and argument dependent. For example, you can often get away with omitting numeric scalar arguments but not CHARACTER or arguments used in adjustable array bounds expressions, as code in the called routine's "prologue" tries to reference the missing data, often resulting in an access violation (see Don't Touch Me There.)

Fortran 90 introduced the concept of optional arguments and a standard-conforming way of omitting said optional arguments. Many users eagerly seized upon this and started using the new feature, but soon got tripped up and confused because they didn't follow all of the rules the standard lays out. The Doctor is here to help.

First things first. To be able to omit an argument when calling a routine, the dummy argument in the called routine must be given the OPTIONAL attribute. For example:

SUBROUTINE WHICH (A,B)
INTEGER, INTENT(OUT) :: A
INTEGER, INTENT(IN), OPTIONAL :: B
...

If an argument has the OPTIONAL attribute, you can test for its presence with the PRESENT intrinsic. The standard prohibits you from accessing an omitted argument, so use PRESENT to test to see if the argument is present before touching it. That part is simple.

The part that people tend to miss, though, is that the use of OPTIONAL arguments means that an explicit interface for the routine is required to be visible to the caller. Generally, this means an INTERFACE block (which must match the actual routine's declaration), but this rule is satisfied if you are calling a CONTAINed procedure. If you don't have an explicit interface, the compiler doesn't know that it has to pass a n "I'm not here" value (usually an address of zero) for the argument being omitted, and you could get an access violation or wrong results.

An interesting aspect of OPTIONAL arguments is that it's ok to pass an omitted argument to another routine (which declares the argument as OPTIONAL) without first checking to see if it is PRESENT. The "omitted-ness" is passed along and can be tested by the other routine. What's even more interesting is that the standard allows you to pull this trick on intrinsics such as MAX, PRODUCT, etc.!

There are some additional aspects of optional arguments, such as the use of keyword names in argument lists, that are worth learning about. For more information, see the section "Optional Arguments" in the Language Reference Manual. Another very important reference is the Language Reference Manual, "Determining When Procedures Require Explicit Interfaces.". The Doctor highly recommends this for your reading pleasure. There will be a quiz next week (just kidding!).

The Perils of Real Numbers (Part 1)

Dave Eklund
Compaq Fortran Engineering

One of Fortran's greatest strengths is its ability to manipulate real numbers. It is astonishing, however, that many Fortran programmers lack even a rudimentary understanding of them. In this series, perhaps we can acquire a better understanding and, at the very least, see how some of the "experts" deal with problems.

Let's begin by asking the simple question, "Which real numbers can be represented EXACTLY?" If I gave you a number, how would you find out if the number actually had a precise representation on any given machine?! In what follows I am going to ALWAYS use a decimal point (.) when I am discussing real (floating point) numbers, and I will NEVER use a decimal point when discussing integers.

So the following would be integers:

17
150
-12
0
1000000000000000000

and the following would be reals:

1.0
-12.5
.1234
0.567
-7.00
3.14159265
0.30517578125
1000000000000000000.

Which of the above do you believe are EXACTLY representable as integers or as reals? Why?

Think POWERS OF TWO. If we start with the positive whole numbers, what we find is that both integers and real numbers are internally represented as sums of powers of 2. Now integers are easier to look at, and real numbers do have a pesky exponent field that needs to be considered, but an integer or real like "9" is the sum of 8 and 1, both of which are powers of 2 (2**3 and 2**0 respectively). The main exceptional value is zero. If you view zero as a power of two, perhaps it's time to increase your medication...

Now negative numbers are somewhat different. For integers, we are talking two's complement arithmetic (normally), but for real numbers we just turn on the sign bit in the real number, which the hardware designers so nicely provided. That's all well and good for whole numbers, but how about decimal fractions like .5 and .25? Well, continue to think POWERS OF TWO. Only now it's the negative powers of two. So, for example, .5 is 2.**(-1) and .25 is 2.**(-2) and so on. In point of fact .5 and .25 look identical as far as the "fraction" part of each real number is concerned, and only the exponent changes! As powers of two, both ARE exactly representable.

When you REALLY need to look at numbers, there are several formats that we find useful (alphabetically):

My personal favorites tend to be F and Z. So let's take an up-close and personal look at some whole numbers first and then some fractions.

Try the following program (printing small whole numbers, both as integers and as reals):

      integer, parameter :: lower = 0
      integer, parameter :: upper  = 8

      do i = lower, upper 
      type 1, i, i, i 
1     format (' integer:  ', i, 1x, b, 1x, z) 
      enddo 

      do i = lower, upper 
      x = float(i) 
      type 2, x, x, x 
2     format (' Real: ', f, 1x, b33.32, 1x, z12.8) 
      enddo

      end 
					

It produces:

 integer:            0                                 0        0
 integer:            1                                 1        1
 integer:            2                                10        2
 integer:            3                                11        3
 integer:            4                               100        4
 integer:            5                               101        5
 integer:            6                               110        6
 integer:            7                               111        7
 integer:            8                              1000        8
 Real:       0.0000000  00000000000000000000000000000000 00000000
 Real:       1.0000000  00111111100000000000000000000000 3F800000
 Real:       2.0000000  01000000000000000000000000000000 40000000
 Real:       3.0000000  01000000010000000000000000000000 40400000
 Real:       4.0000000  01000000100000000000000000000000 40800000
 Real:       5.0000000  01000000101000000000000000000000 40A00000
 Real:       6.0000000  01000000110000000000000000000000 40C00000
 Real:       7.0000000  01000000111000000000000000000000 40E00000

 Real:       8.0000000  01000001000000000000000000000000 41000000
 

The integers form a nice progression of bits (look at the "b" formatted column). If we look at the reals, using "b" or "z" format, we see a similar pattern. Notice that zero is the same for both integer and real (although for a real we CAN represent -0.0). Look at 2.0000000. There is only a single bit set! And it's way up in the exponent field. How can this be?

Normally we would observe that a real number (IEEE) comprises a sign (high, left) bit, an exponent (8 bits for single precision -- real), and a fraction (the remaining, rightmost 23 bits). When we "normalize" any real number, the fraction gets shifted so that the high bit is "1" and the exponent adjusted accordingly. But if the high bit is always "1", we can elect to just discard it to save space (and add precision), and generally this is done. So the fraction is really the rightmost 23 bits PLUS a "hidden" bit of 1. For a number like 2.0, which is exactly 2.**1, the fraction is 10000000000000000000000 before we toss the hidden bit and, hence, is 00000000000000000000000 afterwards! If you look carefully, you will observe that 2.0, 4.0, and 8.0 all have a zero fraction (rightmost 23 bits). But 3.0 whose fraction starts out as 110000000000000000000 becomes 10000000000000000000000 after dropping the (high) hidden bit. And, of course, there are also appropriate exponent bits to the far left (perhaps discussed in more detail in a later article).

Notice that in these real numbers there are quite a few zeros in the fraction (rightmost 23 bits). ALL small integer values will look like this! For example, let's take 42, which as an integer in binary is 101010 (2**5 + 2**3 + 2**1). The fraction before tossing the hidden bit would be 10101000000000000000000 and afterwards is just 01010000000000000000000, so there are lots of zeros (still) to the right. This is a good indication that we are dealing with an "exact" value (not proof, but it happens a lot).

Let's try another program to look at the small negative powers of 2:

      integer, parameter :: lower = 0 
      integer, parameter :: upper = 10 

      x = 1. 
      do i = lower, upper 
      x = x/2.0 
      type 2, x, x, x 
2     format(' Real: ', f25.20, 1x, b, 1x, z) 
      enddo 

      end

Notice that we used a very "wide" format -- f25.20 so that we can get a better look at the "full" result (all of the nonzero digits). This is a VERY useful trick... The result is:

 Real: 0.50000000000000000000 1111110
00000000000000000000000 3F000000
 Real: 0.25000000000000000000 111110100000000000000000000000 3E800000
 Real: 0.12500000000000000000 111110000000000000000000000000 3E000000
 Real: 0.06250000000000000000 111101100000000000000000000000 3D800000
 Real: 0.03125000000000000000 111101000000000000000000000000 3D000000
 Real: 0.01562500000000000000 111100100000000000000000000000 3C800000
 Real: 0.00781250000000000000 111100000000000000000000000000 3C000000
 Real: 0.00390625000000000000 111011100000000000000000000000 3B800000
 Real: 0.00195312500000000000 111011000000000000000000000000 3B000000
 Real: 0.00097656250000000000 111010100000000000000000000000 3A800000
 Real: 0.00048828125000000000 111010000000000000000000000000 3A000000
					

So these are the first few negative powers of two. Just like the positive powers from the first example, these all have a zero fraction (after tossing the hidden bit). Notice that the actual values in f format all end in "5". And the 5 keeps moving to the next column. This means that ANY fractional sum will also end in 5. The consequence is that if you provide a fraction whose last nonzero digit is NOT 5 (like 0.000276000000) it CANNOT be exactly represented as the sum of any negative powers of two! This is a VERY important point. You say, "So what." Well, this means that lots of "common" numbers are not exactly representable, like 0.10000000 and 0.200000000000000, although 0.500 IS exactly representable. And while some fractions ending in 5 CAN be represented, many cannot. Consider 5.0 divided by powers of 10.:

      do i = 1,10 
	  x = 5.0/(10.**i) 
      type 1, x, x 
1     format (1x, f40.30, 1x, b) 
      enddo 
      end 

which produces:

   0.500000000000000000000000000000 111111000000000000000000000000 
   0.050000000745058059692382812500 111101010011001100110011001101 
   0.004999999888241291046142578125 111011101000111101011100001010 
   0.000500000023748725652694702148 111010000000110001001001101111 
   0.000049999998736893758177757263 111000010100011011011100010111 
   0.000004999999873689375817775726 110110101001111100010110101100 
   0.000000499999998737621353939176 110101000001100011011110111101 
   0.000000050000000584304871154018 110011010101101011111110010101 
   0.000000004999999969612645145389 110001101010111100110001110111 
   0.000000000499999985859034268287 110000000010010111000001011111 
                  

Hey, only that first one is EXACT! Notice that the others, while "close" to .05, .005, .0005. etc. are not EXACTLY .05, .005, .0005 etc. Some are a little bigger, some smaller (popularly called "nines disease"). In fact, with the exception of 0.500, all the others CANNOT be exactly represented as sums of powers of 2! Observe, however, that only when a wide format is used is this apparent. With a smaller format width, most of these will look just fine due to rounding!

We are finally at the point where we can decide which numbers are EXACTLY representable:

1.0

Yes (any small integer is fine)

-12.5

Yes, small integer + negative power of 2 (.5)

.1234

No, last fractional digit is not 5

0.567

No, last fractional digit is not 5

-7.00

Yes, small integer

3.14159265

Cannot easily tell (last fractional digit is 5) [Is actually NOT representable]

0.000030517578125

Cannot easily tell (last fractional digit is 5) [IS actually representable]

1000000000000000000.

Maybe (small integer, for some value of "small")

To decide the last 3 values, just try the following:

      type 1, 3.14159265 
      type 1, 0.000030517578125 
      type 1, 1000000000000000000. 
      type 1, 1000000000000000000.D0 
1     format(f60.30) 
      end 

and observe:

                   3.141592741012573242187500000000 
                   0.000030517578125000000000000000 
  999999984306749440.000000000000000000000000000000 
 1000000000000000000.000000000000000000000000000000 
                  

We see that the closest representable real number to 3.14159265 is actually 3.14159274...; 0.000030517578125 CAN be represented exactly (it is, in fact, a power of 2); and while 1000000000000000000. cannot be represented as a real number (can you explain this more precisely?), it CAN be represented as a double-precision number (more than twice as many fraction bits). Once again, notice the use of an even wider format to help get a better look at the numbers! Keep in mind that for a statement like:

type 1, 3.14159265 

the Fortran compiler and runtime library will do a "double conversion." The compiler will convert the string 3.14159265 into a real value, and the runtime system will then convert back to a string (under format control) to produce 3.141592741012573242187500000000. Neither of these conversions is easy, but thankfully the Fortran compiler and runtime library perform all of this heavy lifting!

As a quiz for next time, consider the following program:

      i = 1000000013 
      x = i 
      type 1, i, x 
1     format(1x,i,1x,f20.5) 
      end 
	

It gives:

1000000013    1000000000.00000 

Try to figure out where the "unlucky 13" went!? Why does it come back if we use /real_size:64? Look for the answers in Part II of this article in a future newsletter issue. ]]> http://software.intel.com/en-us/forums/intel-visual-fortran-compiler-for-windows/topic/41911/ Wed, 30 Nov -001 00:00:00 -0800 http://software.intel.com/en-us/forums/intel-visual-fortran-compiler-for-windows/topic/41911/ ISN General April 2001

Doctor Fortran Gets Explicit!

Steve Lionel
Visual Fortran Engineering

In our last issue, the Good Doctor covered the topic of optional arguments, noting that an explicit interface was required. Since explicit interfaces seem to be a common point of confusion for those new to Fortran 90, (and some not so new), we'll cover this subject in more detail.

In Fortran terminology, an interface is a declaration of some other procedure that supplies details, including:

• Name of the procedure
• Whether it is a subroutine or function
• If a function, the result type
• Number, names, shapes and types of arguments
• Argument attributes, such as OPTIONAL and INTENT

Prior to Fortran 90, the only kind of interface was implicit, meaning that the compiler assumed that a routine call matched the actual routine - all you could do was specify the type of a function. The standard required that "the actual arguments ... must agree in order, number and type with the corresponding dummy arguments in the dummy argument list of the referenced subroutine." Not only was this error-prone, but it made it difficult to support desirable features such as optional arguments and array function results.

The explicit interface, introduced with Fortran 90, allows you to tell the compiler many more details about the called routine. This additional information allows a compiler to check for consistency in routine calls and also enables features such as optional arguments that depend on changes in the way the routine is called. In most cases, an explicit interface consists of an INTERFACE block which contains a copy of the called routine's declaration. For example:

INTERFACE
SUBROUTINE MYSUB (A,B)
INTEGER ::A
REAL, OPTIONAL, INTENT(IN) :: B
END SUBROUTINE MYSUB
END INTERFACE

An INTERFACE block can go in the declaration section of a program unit, or can be made visible by use-association (in a MODULE that is USEd) or host-association (a program unit that contains the one that needs to see the interface.) An explicit interface also exists, without an INTERFACE block, if the routine is a contained procedure or is a module procedure in the enclosing module or a module that is use-associated (and the module procedure has not been made PRIVATE).

While there are many good reasons why you should always use explicit interfaces, including better error checking and improved run-time performance (avoiding unnecessary copy-in, copy-out code), there are some cases where you are required to have an explicit interface visible. These are:

• If the procedure has any of the following:
  • An optional dummy argument
  • A dummy argument that is an assumed-shape array, a pointer, or a target
  • A result that is array-valued or a pointer (functions only)
  • A result whose length is neither assumed nor a constant (character functions only)
• If a reference to the procedure appears as follows:
  • With an argument keyword
  • As a reference by its generic name
  • As a defined assignment (subroutines only)
  • In an expression as a defined operator (functions only)
  • In a context that requires it to be pure
• If the procedure is elemental

For more information on explicit interfaces, see Chapter 8 of the Intel Fortran Language Reference Manual.

In closing, Doctor Fortran prescribes using explicit interfaces throughout your application, ideally with an appropriate INTENT attribute specified for each argument. It may be a bit more typing up front, but it will quickly pay off in smoother development and, possibly, faster execution.

[Revisiting this topic in 2008, my advice has changed.  You should avoid writing INTERFACE blocks for Fortran code.  Instead, put your subroutines and functions in modules, or make them CONTAINed procedures if they'll be called from a limited context.  This provides the explicit interface without needing to retype the declarations. - Steve]

The Perils of Real Numbers (Part 2)

Dave Eklund
Compaq Fortran Engineering

In Part 1 we offered the following problematical program:

      i = 1000000013 
      x = i
      type 1, i, x
1     format(1x,i,1x,f20.5)
      end

 1000000013     1000000000.00000

Where did the "unlucky 13" go!? Why does it come back if we use /real_size:64? Let's look a little more closely at the distribution of integer and real numbers. You will recall that any integer is represented simply as the sum of POSITIVE (and zero) powers of 2, and there is no exponent field. This results in a flat distribution of values from -2**31 all the way up to 2**31-1, or -2147483648 up to 2147483647. Every integer value between these end points is included. There is only one value of zero. There is one value which does not have a counterpart of opposite sign (-2**31). Notice that this means that all of the integer values are "evenly spaced" across the entire range.

The same general statements hold for all the other integer types (KIND = 1, 2, and 8 or their non-standard namings: integer*1, integer*2 and integer*8). All evenly spaced, and no exponent field. Not having an exponent field means, in effect, that there are 31 contiguous bits of "value" in an integer, whereas there are only 24 such bits in a real number (the 23 fraction bits and the hidden bit). In a real number the rest of the bits are sign (1 bit) and exponent (8 bits).

So let's look at what whole numbers we can represent as a real number. Well, we already know that we can represent any "small" whole number. In fact there is no difficulty whatsoever representing any whole number up to 2**24. But then something unusual happens. Take the following program:

    integer :: two_24 = 2**24
	  
    do k = -2, 2
    i = two_24 + k
    type 1, i, i, float(i), float(i), float(i)
1   format(i9,1x,z9,1x,f12.1,1x,b33.32,1x,z)
    enddo

    end

The program prints the whole numbers just before and after 2**24 as integers and as real numbers. The result is shown below:

Integer:   in hex:  Real number:      Real in binary: 

16777214    FFFFFE   16777214.0  01001011011111111111111111111110 
16777215    FFFFFF   16777215.0  01001011011111111111111111111111
16777216   1000000   16777216.0  01001011100000000000000000000000
16777217   1000001   16777216.0  01001011100000000000000000000000 
16777218   1000002   16777218.0  01001011100000000000000000000001 

While we had no difficulty representing the value 2**24+1 as an integer, it was quite impossible as a real number. The integer value in hex is: 1000001 -- notice that the first and last "1" bits are 25 bits apart! And this is not possible with the 24-bit fraction field of the real number! Hence 16777217 is the first whole number that we cannot represent as a real. Looked at another way, 16777215 is the last "odd" whole number that can be represented as a (single precision) real. Trivia buffs, rejoice!

From 2.**24 up to 2.**25 we can only represent every other whole number (all the even ones) -- we step by two. From 2.**25 up to 2.**26 we can represent every fourth whole number (all those evenly divisible by 4.). And so it goes. By the time we get up to 1000000013. (the number in the first example above), the two closest representable real numbers are: 1000000000. (4E6E6B28 in hex) and 1000000064. (4E6E6B29 in hex) which are 64. apart!

The thing to remember is that as the real numbers get larger, they get further and further apart! That low order bit in the fraction gets to represent larger and larger "steps" between adjacent numbers. The "step size" is directly determined by the exponent field value. You will find that real numbers are really "dense" near zero. In fact very close to 50% of the real numbers lie between -1.0 and 1.0! The same is true for double precision. With double precision instead of 23 fraction bits (and a hidden bit) we have 52 bits (and a hidden bit). This allows us to express all the whole numbers up to 2**53, but not 2**53+1 . This is why /real_size:64 causes the original example to "work" (not lose the unlucky 13)!

In fact, since double precision has 53 fraction bits, ANY 32-bit integer value can be represented EXACTLY as a double precision value. Similarly any integer(kind=2), which is a 16-bit integer, can be represented EXACTLY as a real (24 covers 16 just as 53 covers 32!).

Does this mean that real numbers are "less precise" as we get further from zero? Curiously enough, the answer is no. While the representable numbers are further apart, they still have exactly the same number of "significant bits" -- 24 or 53 for real and double precision respectively. Significant bits? What about significant dights? When we talk about "significance", we are talking about the number of leading non-zero bits (or digits) that are known to be "present" or fully representable. Remember that we were able to express 16777216 but not 16777217 as a real? Well, the 1677721 part (24 bits, 7 digits) were significant, but that last digit, alas, is imprecise and cannot be represented in the real number format. For those who love the details, since it takes log_base2(10) bits to represent any 1 digit (3.321928 bits per digit), then 24 bits gives us 7.224720 digits--or 7 significant digits. And for double precision 53 bits gives us 53.*LOG10(2.) or 15.95459 digits -- 15 significant digits (nearly 16).

So you are saying that no matter what the real number, there are always 7 significant digits? Well, yes and no (nobody ever said this was simple!). There are three major exceptions: denormalized numbers, +-Infinity, and NaN (Not a Number). All of these anomolies are recent arrivals on the hardware scene. So recent, in fact, that the Fortran Standard does NOT require them, nor pin down their behavior!

For a long time hardware designers were content with integer and then real data types and ever faster computers to manipulate them. But there were those who wanted more; those who were not content that dividing by zero caused their programs to ABEND (die for you youngsters). Those who wanted to be able to express 1.0/0.0; those who could visualize 0.0/0.0 (NOT to be confused with visionaries). Ah, what evil lurks... And so there came to be the IEEE Standard for Binary Floating-Point Arithmetic or ANSI/IEEE Std 754-1985.

In this standard you would find definitions of number formats, basic operations, conversions, exceptions, traps, rounding, etc. Most modern machines provide hardware (and software) that conform to this standard. Portability, efficiency and safety are some of the most important stated goals of this standard. However, the introduction of +-Infinity and NaN brought a whole new set of possibilities and problems.

Let's start with Infinity. In the old days there were two pretty easy ways to get a program to die--divide by zero, or overflow (multiply two very large numbers together, for example). Each of these is a limitation of the "range" of possible result values. If you cannot represent a value of "Infinity", what result value should be given to a divide by zero?! Well, there were two schools of thought. Some wanted their program to die (division by zero is ALWAYS a mistake that was not checked for in MY algorithm).

Others wanted to "keep on trucking" (you simply cannot just die after 3000 hours of running MY program!) with some artificial, but specified, value as the result. While the latter group wanted "non-stop" computing, they also wanted some indication that their final results might be tainted. They successfully lobbied for special values: Infinity, -Infinity and NaN, and a "standard" treatment of these values in subsequent arithmetic computations and comparisons. So, for example if the user:

This standard also defined SQRT, but NOT any of the intrinsic functions like SIN, COS, TAN, SUM, PRODUCT, etc. The result of all of this was that many programs could just keep running, producing +-Infinity and NaN as they went, and not particularly worry about dividing by zero or the aftermath (pun intended!). And these values would tend to propagate themselves whenever they are used. You CAN "get rid of" an Infinity if all you do is to use it as a divisor (producing zero), but NaN is really hard to "get rid of". In fact, about the only way to constructively eliminate a NaN is to do something like:

IF(ISNAN(X)) THEN
! Replace X with something else
! or use better/other algorithm, etc.
ENDIF

Ah, but much was left undefined. For example, what result would you like to produce for SIN(X) where X is Infinity? As you know, SIN normally has a range between -1. and 1., so should we return Infinity? Would NaN be better? How about a more traditional "DOMAIN error" for the intrinsic function? And if intrinsic functions are not enough trouble, how about comparisons? For example while (Infinity .GT. 17.0) is .TRUE. (defined that way), it might not be so obvious that (NaN .EQ. NaN) is .FALSE. or that (Infinity .GT. NaN) is .FALSE. There is a whole new algebra, but only defined for primitive arithmetic and comparison operations (this IS a hardware standard, after all!). Don't even think about COMPLEX numbers such as: (-Infinity, NaN)...

In order to represent Infinity and NaN, the IEEE standard chose to make all reals having the largest exponent value (all 1's) "reserved". If the exponent is all 1's and the fraction is zero, we have an Infinity. The sign bit is relevant, so there is one value for +Infinity (7F800000 in hex) and one value for -Infinity (FF800000). If the exponent is all 1's and the fraction is ANY non-zero value, then this is a NaN. Notice that there are many different values for NaN. There are even two different kinds of NaN, Quiet and Signaling, but this distinction is so esoteric for Fortran that if you understand the difference and make use of it in your Fortran programs, then you can send your resume to us...

Continued in next post

Finally, a denormalized number is one where the exponent field is completely zero and the fraction is non-zero. These are the smallest of the finite numbers (both positive and negative). The very smallest positive (non-zero) number is just 00000001 (in hex). It has only one significant bit (not even one digit!) since the denormalized range does NOT use a hidden bit. Generally speaking the denormalized numbers have fewer significant digits than ANY normalized number, and the smaller the denormalized number, the fewer its significant digits. These are the ONLY real numbers with fewer than 7 significant digits. If you happen to produce and use values in this range, your results may not be as accurate as you might normally expect.

Quiz for next time (I hear the crowds cheering for MORE!). Change the last program above so that the DO loop runs from -2 to 15 (instead of from -2 to 2).

It then generates:

integer:    in hex: Real number:     Real in binary:

16777214    FFFFFE   16777214.0  01001011011111111111111111111110 
16777215    FFFFFF   16777215.0  01001011011111111111111111111111
16777216   1000000   16777216.0  01001011100000000000000000000000 
16777217   1000001   16777216.0  01001011100000000000000000000000
16777218   1000002   16777218.0  01001011100000000000000000000001
16777219   1000003   16777220.0  01001011100000000000000000000010
16777220   1000004   16777220.0  01001011100000000000000000000010
16777221   1000005   16777220.0  01001011100000000000000000000010
16777222   1000006   16777222.0  01001011100000000000000000000011
16777223   1000007   16777224.0  01001011100000000000000000000100 
16777224   1000008   16777224.0  01001011100000000000000000000100 
16777225   1000009   16777224.0  01001011100000000000000000000100
16777226   100000A   16777226.0  01001011100000000000000000000101 
16777227   100000B   16777228.0  01001011100000000000000000000110 
16777228   100000C   16777228.0  01001011100000000000000000000110 
16777229   100000D   16777228.0  01001011100000000000000000000110 
16777230   100000E   16777230.0  01001011100000000000000000000111
16777231   100000F   16777232.0  01001011100000000000000000001000

Glance down the Real number column. Notice that the last few digits are:

14, 15, 16, 16, 18, 20, 20, 20, 22, 24, 24, 24, 26, 28, 28, 28, 30, 32. Explain why there are THREE values of 24, then ONE 26, then THREE values of 28, then ONE 30; this pattern will continue (for a long time). Why not 14, 15, 16, 16, 18, 18, 20, 20, 22, 22, 24, 24, 26, 26, 28, 28, 30, 30 instead?! Extra credit: what "simple" change can our expert Fortran developer make to produce the latter sequence instead of the former? Hint: any of you economists out there ever heard of Banker's Rounding?!