                           README.TXT file

             README file for Microsoft FORTRAN PowerStation
                            Version 1.0

             (C) Copyright Microsoft Corporation, 1993

This document contains notes about using version 1.0 of the Microsoft
FORTRAN PowerStation Development System for Windows and MS-DOS(R). The
information in this document is more up-to-date than that in the manuals.
Microsoft improves its languages documentation at the time of reprinting,
so some of the information in this file may already be included in your
manuals.

============================< Contents >================================

This file has seven parts:

     Part     Contents
     ----     --------
      1       Installing FORTRAN PowerStation
      2       Using the FL32 Compiler
      3       Using the LINK32 Linker
      4       Using the Run-time Library
      5       Using FORTRAN Visual Workbench
      6       Debugging Programs
      7       Miscellaneous

=============< Part 1: Installing FORTRAN PowerStation >===============

Using SHARE
-----------
If you are going to use Windows 3.1, you must start the share utility
prior to starting Windows in order to use the Browser.  This is not
necessary if you will be using Windows for Workgroups, because WFW has
its own internal version of SHARE.


Modifications to SYSTEM.INI
---------------------------              
Setup modifies the SYSTEM.INI file in your Windows directory.  It adds
the following information in the [386ENH] section:

device=c:\f32\bin\dosxnt.386
device=c:\f32\bin\mmd.386

Without these device drivers installed, FORTRAN PowerStation will
not work from within Windows.  The original SYSTEM.INI is renamed
SYSTEM.BK_


Running Setup from MS-DOS or Windows
------------------------------------
The DOSSETUP program installs all of the files necessary in order to
run Microsoft FORTRAN Power Station under MS-DOS. In order to use the
product, however, you need to ensure that your environment variables
in your AUTOEXEC.BAT file are set to run the product correctly.

DOSSETUP has created a file called F32ENV.BAT. This file sets the
current environment of your MS-DOS session to the necessary values.
If you want Microsoft FORTRAN PowerStation to be configured when your
machine starts, you need to copy the lines from F32ENV.BAT to the
end of your AUTOEXEC.BAT. 

If you want to use the Integrated Debugging Environment, you need to
run the SETUP.EXE program from the Program Manager in Microsoft
Windows (version 3.1 or later). Running the Microsoft Windows Setup
program will not affect your ability to run in the MS-DOS environment;
it merely installs extra files used in the Microsoft Windows
environment. Although it is possible to run the browser tools
(sbrpack.exe and bscmake.exe) from the MS-DOS command line, these
tools are not installed by DOSSETUP.


Libraries Replaced by Setup
---------------------------
If you have older versions of the LIBC.LIB, KERNEL32.LIB, FP.LIB, 
or NTDLL.LIB libraries in your installation directory, Setup only
replaces them if the ones on the distribution disk are newer than
the ones on your hard disk. The only library that Setup always
replaces is LIBF.LIB.


Running Setup from Windows for Workgroups (WFW)
-----------------------------------------------
If you install FORTRAN PowerStation from a PC running Windows for
Workgroups, you may get a warning message from Windows when you
allow Setup to restart Windows. If another user is connected to your
PC, you should make certain that restarting Windows on your PC
does not cause them to lose data before proceeding. Some network
connections may have to be re-established manually after Windows
has restarted.


Using a Video Seven Graphics Card
---------------------------------
Video Seven provides a utility called V7VGA to enable extended
resolutions of their card. These extended capabilities are enabled
by default in MS-DOS, but are disabled by default in a Windows
MS-DOS session.

To use VESA modes in Windows, you must first run the command line
"V7VESA /1" using the utility supplied with FORTRAN PowerStation.
You can put this in your AUTOEXEC.BAT file, or run it in a Windows
MS-DOS session. In addition to running this program in a Windows
MS-DOS session, you must give the command line "V7VGA pure:off"
inside the Windows MS-DOS session. This enables the extended
capabilities used by VESA. V7VGA.EXE is provided on the utilities
disk with the Video 7 card. V7VESA.COM is also provided. Microsoft
provides V7VESA.COM, but not V7VGA.EXE.


Problems using 256-color VESA modes
-----------------------------------
Some video adapters do not execute a FLOODFILL correctly if they
are running in 265-color VESA modes. Instead of filling polygons
completely with the specified color, these adapters fill only the
bottom half of the polygon. (You can check how your video adapter
executes FLOODFILL by running the GRDEMO project in the
..F32\SAMPLES\DEMO directory.


Possible MS-DOS Extender Conficts
---------------------------------
Several Microsoft language products provide 32-bit
MS-DOS-extended tools that use the Microsoft DOSXNT MS-DOS
Extender. The version of DOSXNT used by Microsoft PowerStation
FORTRAN version 1.0 is not compatible with the version used by
Microsoft MASM version 6.1.

To ensure that all MS-DOS-extended tools run successfully, it
is recommended that you install each language product in a
separate directory and that you leave each version of
DOSXNT.EXE in the subdirectory that contains the tools it
supports. This allows each MS-DOS-extended tool to locate the
appropriate version of DOSXNT.EXE. Make sure that the PATH
environment variable specifies the directory in which you
installed FORTRAN PowerStation version 1.0 before the directory
that contains MASM 6.1. This ensures that you can run the latest
versions of tools that are in common to both products.

If you install both FORTRAN PowerStation and MASM 6.1 in one
directory, you will not be able to run MASM.EXE and ML.EXE from
the command line. However, you will be able to run these tools as
commands executed by NMAKE.


=================< Part 2: Using the FL32 Compiler >===================

Temporary Files Created by FL32
-------------------------------
The FORTRAN PowerStation compiler creates temporary files during
compilation. These files are normally stored in a directory identified
by the TMP environment variable. (If a TMP environment variable has not
been set, these temporary files are stored in the directory where
FORTRAN PowerStation was installed.) If the directory identified by the
TMP environment variable does not exist, or there is not enough space to
create the temporary files, compilation will fail with the message 
"F1914: cannot open internal files."

To check the location of the TMP environment variable, type SET at the
MS-DOS prompt. All currently set environment variables are listed. You
can use the Windows File Manager to locate the directory specified in
the TMP environment variable.


Using Assumed-size Arrays of Structures
---------------------------------------
Writing an assumed-size array without specifying element indices should
produce an error, but does not if the array is an array of structures.

     subroutine sub(s)
     structure /struc/
       real r
     end structure
     record /struc/ s(*)

C  The following line is incorrect, but will not produce an error:
     write(*,*) s(i).r

C  Instead, a write statement such as the following should be used:
     write(*,*) (s(i).r, i=1,10)


Loop Counter Limitation
-----------------------
The largest number of iterations that a loop can perform is 2,147,483,647.
This is because the tripcounter is an Integer*4 variable; the compiler
does not check for overflow as a means of increasing execution speed.


Notes on the Random Number Generator
------------------------------------
The random number generator provided with FORTRAN PowerStation is different
from the one provided with the 16-bit FORTRAN 5.1. The sequence of numbers
produced by RANDOM is different from that produced by the same seed in the
FORTRAN 5.1 random number generator.

The value -1 is an exception to the rule that a given seed always produces
the same sequence of values from RANDOM. Instead, -1 is equivalent to
RND$TIMESEED, which produces a different sequence each time it is used.


Differences in Substring/Concatenation Operations
-------------------------------------------------
There is a difference in how FORTRAN 5.1 and FORTRAN PowerStation
handle substring/concatenation operations. FORTRAN PowerStation produces
the same results that VAX FORTRAN produces if the VAX extensions (-4Yv)
are enabled. If the VAX extensions are not enabled, these operations are
handled in the same way that FORTRAN 5.1 does. For example, if you define
          CHARACTER*10    BUFFER1
          CHARACTER*11    BUFFER2, BUFFER3
          CHARACTER*1     CHAR1
          BUFFER1 = '0123456789'
          BUFFER2 = '0123456789 '
          BUFFER3 = '0123456789 '
          CHAR1 = 'X'

The statement...
          BUFFER1 = BUFFER1(6:10)//BUFFER1(1:5)

produces '5678901234' with VAX extensions enabled
  ...and '5678956789' with VAX extensions disabled.

The statement...
          BUFFER2 = CHAR1//BUFFER2

produces 'X0123456789' with VAX extensions enabled
  ...and 'XX113355779' with VAX extensions disabled.

The Statement...
          BUFFER3 = BUFFER3(1:10)//CHAR1

Produces '0123456789X' with either switch setting.

The assignment statements for BUFFER1 and BUFFER2
violate the ANSI Standard.  Section 10.4 of the Standard says
that for a Character Assignment Statement of the form:

   v = e

"None of the character positions being defined in 'v' may be
referenced in 'e'."  The FORTRAN PowerStation Language Guide
does not mention this and no run-time error is generated, even
when /4Yb is used.


Handling Mismatched Type and Length Warnings
--------------------------------------------
The FL32 compiler generates a mismatched type warning (F2606) if the
type of a formal argument is different from the type of the actual
argument used in the subprogram call. Under most conditions, this
situation will not prevent a program from executing, but certain
automatic type conversions, such as between REAL*4 and REAL*8, can
cause the program to crash. It is good practice to resolve mismatched
type warnings prior to running a program.



=================< Part 3: Using the LINK32 Linker >===================

Notes on Changes in File Formats
--------------------------------
The FORTRAN PowerStation 1.0 compiler produces 32-bit COFF object files.
The FORTRAN 5.1 compiler produced 16-bit OMF object files. These file
formats are not compatible, therefore you cannot link OMF object files
with COFF object files.


Debugging Unresolved External References
----------------------------------------
If the linker reports an unresolved external name, and the routine
does exist in your code, you should check its parameter list.  The
number following the "@" in the name given in the link error indicates
the number of bytes in the parameter list of the calling statement.
Verify that the calling statement and the subprogram declaration agree
in their number and types of arguments.


Naming the Executable File Produced by LINK32
---------------------------------------------
In order to use the FL32 command to compile and link in one step and
to give the resulting executable file a specific name, use the /Fe
option as in the following command line:

  FL32 TEST.FOR /FeMYTEST

This will result in an executable file called MYTEST.EXE.
The command line

  FL32 TEST.FOR /link -out:MYTEST.EXE

will result in the following error:

  Fatal error: Cannot open input file -- File not found "test.exe"

This is caused by the binding process failing to find the executable
with the changed name. If the executable is then run, it will generate
the error:

  This program cannot be run in DOS mode.

because it was not bound.  Using the command 

  BINDMSF MYTEST.EXE 

will correct this problem.


Getting Help from the MS-DOS Command Line
-----------------------------------------
To get the syntax for LINK32 help, type:
   LINK32 -HELP
To get the syntax for LINK32 LINK options, type:
   LINK32
To get the syntax for LINK32 LIB options, type:
   LINK32 -LIB
To get the syntax for LINK32 DUMP options, type:
   LINK32 -DUMP



================< Part 4: Using the Run-time Library >=================

Floating-Point Coprocessor Limitation
-------------------------------------
Some older 80386 systems have 287 coprocessors instead of 387s;
some floating-point operations will not work correctly in these cases.
To fix this, you must force use of the floating-point emulator by
setting the TNT environment variable as follows.  At the MS-DOS (or
MS-DOS session) command line, enter "SET TNT=-FPEM" before running
your compiled program.  To cancel the forced emulation, you can
enter "SET TNT=-NOFPEM".


Floating-Point Options
----------------------
Prior versions of Microsoft FORTRAN had a variety of floating-point
options:
 * emulator
 * co-processor only
 * alternate math
FORTRAN PowerStation detects the presence of a co-processor and will use
it if it is present. Otherwise, it will emulate the floating-point
co-processor.


Floating-Point Exceptions and Run-Time Math Exceptions
------------------------------------------------------
The following table shows the default behavior for floating-point
exceptions and run-time math exceptions.  Entries in the table are:
     0.          a value of zero,
     (value)     the value resulting from the operation,
     1#INF       IEEE infinity,
     1#IND       IEEE NaN (Invalid),
     M6nnn       run-time error number M6nnn.
When one of the values 0., (value), 1#INF, or 1#IND occurs the
program continues to run.  When a run-time error (M6nnn) occurs,
the program stops after reporting the error. The behavior depends on
which compiler option you specify and whether you use the default
run-time function MATHERRQQ or replace it.

                             Compiler Option and Resulting
                              Default Exception Behavior

                                    Compiler Option

                        (none)      /Op       /Ox /Op    /Ox
Exception

(FP exceptions)
invalid                 M6101       M6101     M6101      M6101     
denormalized            (value)     (value)   (value)    (value)
zerodivide              M6103       M6103     M6103      M6103     
overflow                M6104       M6104     M6104      M6104     
underflow               0.          0.        0.         0.
inexact                 (value)     (value)   (value)    (value)

(Math exceptions)
domain                  M6201       M6201     M6201      (undefined)
singular                M6202       M6202     M6202      (undefined)
overflow                M6203       M6203     M6203      (undefined)
total loss of precision M6205       M6205     M6205      (undefined)

This behavior results from the default call of SETCONTROLLFPQQ
(done by the Run-time library when your program starts) that includes
the exception control flags
     FPCW$DENORMAL + FPCW$UNDERFLOW + FPCW$INEXACT
and the inclusion of the default run-time subroutine MATHERRQQ. (The
behavior of math exceptions for /Ox is undefined; either an IEEE
value results or a run-time error occurs.) 

If you want behavior consistent with IEEE precision and exception
handling, compile with /Op and explicitly call SETCONTROLFPQQ with
all exception control flags:
     FPCW$INVALID + FPCW$DENORMAL + FPCW$ZERODIVIDE +
     FPCW$OVERFLOW + FPCW$UNDERFLOW + FPCW$INEXACT.
In addition, you must link a replacement subroutine MATHERRQQ that does
nothing but return a successful return code.  The next table shows the
IEEE behavior that results.

                        IEEE Precision and Exception Behavior

                               /Op + Flags + MATHERRQQ
Exception

(FP exceptions)
invalid                             1#IND
denormalized                        (value)
zerodivide                          1#INF
overflow                            1#INF
underflow                           0.
inexact                             (value)

(Math exceptions)
domain                              1#IND
singular                            1#IND
overflow                            1#INF
total loss of precision             0.

The sample programs include a program SPECIAL.FOR that illustrates
tailoring the floating-point environment to be the closest possible
to IEEE. It calls SETCONTROLFPQQ with the appropriate flags and
provides a replacement MATHERRQQ.


=============< Part 5: Using FORTRAN Visual Workbench >================

Fonts used in FORTRAN Visual Workbench
--------------------------------------
FORTRAN Visual Workbench will only allow screen fonts.  Most simulated
fonts can not be displayed.  Therefore, many boldface fonts are not
available.  All truetype fonts, bold and italic can be used.
Occasionally the caret will be positioned wrong for some bold or italic
non-truetype fonts.  If you select a font and the caret is positioned
incorrectly, chose a different font. 


Programs with Very Long Paths
-----------------------------
If a program has a very long path, then Project.Execute may bring up
a message box titled "F32EXEC.PIF" which says that the program cannot
be found, although the .EXE file was created and can be run outside of 
FORTRAN Visual Workbench.


Time-out Problems in FORTRAN Visual Workbench
---------------------------------------------
If you have time-out problems with FORTRAN Visual Workbench, check
to see if WinExclusive=1 is in the 386enh section of SYSTEM.INI. If
this is set and Windows has the focus, then Windows gets all the
timeslices.  (Therefore Wintee can't initialize a DOS VM.)

WinExclusive is set from the "Exclusive in Foreground" checkbox in
Windows Control Panel, 386Enhanced.  For FORTRAN Visual Workbench,
the box should NOT be checked.


Using Extended Characters in FORTRAN Visual Workbench
-----------------------------------------------------
Because FORTRAN Visual Workbench runs in Microsoft Windows and produces
programs that run in MS-DOS, two distinct character sets are used:
ANSI and OEM. The ANSI set is normally used in Windows; the OEM set
is used in MS-DOS. Both character sets contain extended characters
(such as accented letters and line-drawing symbols), but the numerical
representation of these characters is different. Windows provides a
special font called Terminal that uses the OEM character set. If you
use extended characters in your files, you need to know about both.

FORTRAN Visual Workbench is an ANSI editor; it does not convert
characters to the OEM character set.  If you want to see the true
OEM characters, use the TERMINAL font.  If you want to enter OEM
characters, add a zero to the beginning of the character code.
(For example, 'ALT + 0130' will produce an accented 'e'; typing
'ALT + 130' will produce the ANSI character.) No translation is
performed when files are loaded or saved. The editor displays the
character representation of what was in the file. When a character
is entered, it is translated to ANSI and saved as that value. This
applies for all characters on the keyboard, including an e-accent
on an international keyboard and an ALT+number entered from the
numeric key pad. The only time a translation is not done is when an
ALT+0+number is entered. When looking at a file from MS-DOS, you
will get the OEM representation of the characters.

We recommend that you do not use extended characters in filenames.

The example program GRDEMO in the ..\F32\SAMPLES\DEMO directory uses
extended characters to produce a boxed menu on the screen. The file
MENU.FOR uses extended characters to draw a box around the menu. The
line characters only display as such if the font is set to Terminal.


Sample Programs in Book, Help and Disk
--------------------------------------
Some of the sample programs on the distribution disks are newer versions
than those which appear in the Language Guide.


===================< Part 6: Using the Debugger >======================

Optimizing Debugging Speed
--------------------------
Because a program being debugged runs as a separate task under Windows,
the speed at which the debugger operates depends upon how many other
programs are being executed at the same time. If screen-swapping is
disabled, FORTRAN Visual Workbench must yield control back to Windows,
and any other program waiting for cycles is serviced along with the
program being debugged in the remote monitor window. To improve the
speed of the debugger, don't run other applications at the same time.


Watching Complex Variables in Commons
-------------------------------------
Debugging code that has complex variables in common blocks causes the
watch window to display them as characters. This affects common record
variables. They are shown in the locals window as a single space rather
than as a structure.


Using Mixed Source/Asm during Debugging
---------------------------------------
You can only view Mixed Source/Asm (selected from the View menu) during
a debugging session if you have not built the target with the /Ox option
(Optimize for Time). (The release version will disable Mixed Source/Asm
if the /Ox option is enabled in the Compiler Options dialog.) If you
attempt to view Mixed Source/Asm for a target built with the /Ox option,
the debugger will not be able to show all of the assembly instructions.
Unexpected results may occur.


Viewing Strings and Arrays in the Locals Window
-----------------------------------------------
When you first step into a program or routine, you will not be able to see
the values or variable-length strings or allocatable arrays until you step
at least once inside the subprogram. This is because the lengths are
computed until after the debugger has begun executing subprogram code.
Once you have stepped into the subprogram, you can view the values of
single dimensional allocatable arrays.


Debugging Very Large Programs
-----------------------------
Although it is possible to debug a program that has an executable file and
symbol table that are close to (or larger than) the amount of physical memory
in your PC, the debugger will take longer to load the symbols. This is because
the Windows memory manager must swap portions of memory during loading.

======================< Part 7: Miscellaneous >========================

Running Programs
----------------
FORTRAN Programs can be executed from FORTRAN Visual Workbench either in a
window or in full-screen mode. You select which to use in the Execute/Debug
Options dialog. FORTRAN programs can be run from an MS-DOS session within
Windows either in a window or in full-screen mode. You can switch between
these modes from within the MS-DOS session by pressing ALT-ENTER. You can
also select the mode for a minimized MS-DOS session from the Settings dialog.

Programs which use graphics may run properly within a window. In most cases,
Microsoft Windows will ask you to switch to full-screen if the graphics mode
is not supported by the graphics driver. Some graphics modes are only
partially supported in a window. In this case, the results will depend upon
which graphics routines are used by the program.

For best results, we recommend that graphics programs are always executed
in full-screen mode.


Redistribution Rights
---------------------
You have the right to distribute the DOS extender files DOSXMSF.EXE and
DOSXNT.386 with programs that you create with FORTRAN PowerStation. There
is no royalty required.

The font files COURB.FON, HELVB.FON and TMSRB.FON are owned by BitStream, Inc.
If you want to distribute these files with a program, you will need get
permission from BitStream.

If you have any questions about redistribution rights, please contact
Microsoft Product Support Services.


About Other Text Files
----------------------
There are three other text files with information about Microsoft FORTRAN
PowerStation.

     Filename      Contents
    ============   ========
     ADDENDA.TXT   Changes to the printed manuals
    QUESTION.TXT   Answers to common questions about FORTRAN PowerStation
    SAMPLIST.TXT   An inventory of samples on the distribution disks.
     VENDORS.TXT   Information about products from other vendors

(...end...)
